[ Previous | Next | Table of Contents | Index | Library Home |
Legal |
Search ]
Technical Reference: Base Operating System and Extensions, Volume 1
Dumps traceback information into a lightweight core file.
PTools Library (libptools_ptr.a)
void mt_trce (int FileDescriptor, int Signal, struct sigcontext *Context, int Node);
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.
| 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 non-zero. 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.
Upon successful completion, the mt_trce subroutine returns a
value of 0. Otherwise, an error number is returned to indicate the
error.
If an error occurs, the subroutine returns -1 and the errno
global variable is set to indicate the error, as follows:
| 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.
|
- 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
The install_lwcf_handler and
sigaction subroutines.
[ Previous | Next | Table of Contents | Index |
Library Home |
Legal |
Search ]