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.
Note:
  1. 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.
  2. Line number information is not provided for shared objects even if they were compiled with the -g option.
  3. 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.
  4. 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.

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

  1. 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);
    ....
}
  2. 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