mt__trce Subroutine
Purpose
Dumps traceback information into a lightweight core file.
Library
PTools Library (libptools_ptr.a)
Syntax
void mt__trce (int FileDescriptor, int Signal, struct sigcontext *Context, int Node);
Description
The mt__trce subroutine dumps traceback information of the calling thread and all other threads allocated in the process space into the file specified by the FileDescriptor parameter. The format of the output from this subroutine complies with the Parallel Tools Consortium Lightweight CoreFile Format. Threads, except the calling thread, will be suspended after the calling thread enters this subroutine and while the traceback information is being obtained. Threads execution resumes when this subroutine returns.
When using the mt__trce subroutine in a signal handler, it is recommended that the application be started with the environment variable AIXTHREAD_SCOPE set to S (As in export AIXTHREAD_SCOPE=S). If this variable is not set, the application may hang.
Parameters
Item | Description |
---|---|
Context | Points to the sigcontext structure containing the context of the thread when the signal happens. The context is used to generate the traceback information for the calling thread. This is used only if the Signal parameter is nonzero. If the mt__trce subroutine is called with the Signal parameter set to zero, the Context parameter is ignored and the traceback information is generated based on the current context of the calling thread. Refer to the sigaction subroutine for further description about signal handlers and how the sigcontext structure is passed to a signal handler. |
File Descriptor | The file descriptor of the lightweight core file. It specifies the target file into which the traceback information is written. |
Node | Specifies the number of the tasks or nodes where this subroutine is executing and is used only for a parallel application consisting of multiple tasks. The Node parameter will be used in section headers of the traceback information to identify the task or node from which the information is generated. |
Signal | The number of the signal that causes the signal
handler to be executed. This is used only if the mt__trce subroutine
is called from a signal handler. A Fault-Info section defined by the
Parallel Tools Consortium Lightweight Core File Format will be written
into the output lightweight core file based on this signal number.
If the mt__trce subroutine is not called from a signal handler,
the Signal parameter must be set to 0 and
a Fault-Info section will not be generated. |
- To obtain source line information in the traceback, the programs must have been compiled with the -g option to include the necessary line number information in the executable files. Otherwise, address offset from the beginning of the function is provided.
- Line number information is not provided for shared objects even if they were compiled with the -g option.
- Function names are not provided if a program or a library is compiled with optimization. To obtain function name information in the traceback and still have the object code optimized, compiler option -qtbtable=full must be specified.
- In rare cases, the traceback of a thread may seem to skip one level of procedure calls. This is because the traceback is obtained at the moment the thread entered a procedure and has not yet allocated a stack frame.
- The source line information in a
Lightweight_core
file is not displayed by default when the text page size is 64 K. When the text page size is 64K, use the environment variableAIX_LDSYM=ON
to get the source line information in aLightweight_core
file.
Return Values
Upon successful completion, the mt__trce subroutine returns a value of 0. Otherwise, an error number is returned to indicate the error.
Error Codes
If an error occurs, the subroutine returns -1 and the errno global variable is set to indicate the error, as follows:
Item | Description |
---|---|
EBADF | The FileDescriptor parameter does not specify a valid file descriptor open for writing. |
ENOSPC | No free space is left in the file system containing the file. |
EDQUOT | New disk blocks cannot be allocated for the file because the user or group quota of blocks has been exhausted on the file system. |
EINVAL | The value of the Signal parameter is invalid or the Context parameter points to an invalid context. |
ENOMEM | Insufficient memory exists to perform the operation. |
Examples
- The following example calls the mt__trce subroutine to
generate traceback information in a signal handler.
void my_handler(int signal, int code, struct sigcontext *sigcontext_data) { int lcf_fd; .... lcf_fd = open(file_name, O_WRONLY|O_CREAT|O_APPEND, 0666); .... rc = mt__trce(lcf_fd, signal, sigcontext_data, 0); .... close(lcf_fd); .... }
- The following is an example of the lightweight core file generated
by the mt__trce subroutine. Notice the thread ID in the information
is the unique sequence number of a thread for the life time of the
process containing the thread.
+++PARALLEL TOOLS CONSORTIUM LIGHTWEIGHT COREFILE FORMAT version 1.0 +++LCB 1.0 Thu Jun 30 16:02:35 1999 Generated by AIX # +++ID Node 0 Process 21084 Thread 1 ***FAULT "SIGABRT - Abort" +++STACK func2 : 123 # in file func1 : 272 # in file main : 49 # in file ---STACK ---ID Node 0 Process 21084 Thread 1 # +++ID Node 0 Process 21084 Thread 2 +++STACK nsleep : 0x0000001c sleep : 0x00000030 f_mt_exec : 21 # in file _pthread_body : 0x00000114 ---STACK ---ID Node 0 Process 21084 Thread 2 # +++ID Node 0 Process 21084 Thread 3 +++STACK nsleep : 0x0000001c sleep : 0x00000030 f_mt_exec : 21 # in file _pthread_body : 0x00000114 ---STACK ---ID Node 0 Process 21084 Thread 3 ---LCB