thread_trace(4)


thread_trace -- trace data files for the threads library

Synopsis

   cc [options] -Kthread file
   

#include <thread.h> #include <synch.h>

Description

The threads library provides a mechanism for tracing significant library events. Calls to all threads library interfaces, both thread management [thread(3thread)] and user synchronization interfaces [synch(3synch)], can be traced. Significant information, such as arguments, return values, lock contention, and duration of execution are recorded.

To avoid a performance penalty on the threads library, a separate library, libthreadT.so, contains the tracing routines. To obtain trace data, the application must be linked to libthreadT.so instead of libthread.so.

Trace data is collected for each LWP and stored in a separate file, by default in the current working directory. The files are named:

   tr.xxxxxxx.yyy
where xxxxxxx is the seven least significant hexadecimal digits of the process ID associated with the LWP and yyy is the three least significant hexadecimal digits of the LWP ID.

Format of the trace data files

Each line in the files is a trace record in the following format:

time1:time2:lwpid:pid:tid:event1:event2:which:a1:a2:a3:a4:a5

The type and meaning of each field in the record is shown in the following table:

Field Type Meaning
time1 long current time in seconds
time2 long current time in nanoseconds
lwpid lwpid_t LWP ID of calling thread
pid pid_t process ID of calling thread
tid thread_t thread ID of calling thread
event1 short general category of event (see next table)
event2 short specific event (name of interface called, see next table)
which short 0 for a single record associated with this event,
1 for the first of 2 records, or 2 for the second or two records
a1 long depends on event
a2 long depends on event
a3 long depends on event
a4 long depends on event
a5 long depends on event

 Field    Type       Meaning
 time1    long       current time in seconds
 time2    long       current time in nanoseconds
 lwpid    lwpid_t    LWP ID of calling thread
 pid      pid_t      process ID of calling thread
 tid      thread_t   thread ID of calling thread
 event1   short      general category of event (see next table)
 event2   short      specific event (name of interface called, see next table)
 which    short      0 for a single record associated with this event,
                     1 for the first of 2 records, or 2 for the second or two records
 a1       long       depends on event
 a2       long       depends on event
 a3       long       depends on event
 a4       long       depends on event
 a5       long       depends on event

The first two fields record the time, the next three fields record information about the caller, the next three fields identify the event, and the remaining fields record specific details about the event, such as the arguments passed to the interface in question.

Events and event categories

The table below shows the code numbers used in the event1 and event2 fields of the trace record.

Category event1 Specific event2
of Event Code Event Code
thread 1 thr_create 1
    thr_exit 2
    thr_join 3
    thr_self 4
    thr_minstack 5
    thr_continue 6
    thr_suspend 7
    thr_setconcurrency 8
    thr_getconcurrency 9
    thr_kill 10
    thr_sigsetmask 11
    thr_setscheduler 12
    thr_getscheduler 13
    thr_setprio 14
    thr_getprio 15
    thr_yield 16
    thr_get_rr_interval 17
    thr_keycreate 18
    thr_keydelete 19
    thr_setspecific 20
    thr_getspecific 21
mutex 2 mutex_init 1
    mutex_lock 2
    mutex_trylock 3
    mutex_unlock 4
    mutex_destroy 5
cond 3 cond_init 1
    cond_signal 2
    cond_broadcast 3
    cond_wait 4
    cond_timedwait 5
    cond_destroy 6

     

     
sema 4 sema_init 1
    sema_wait 2
    sema_trywait 3
    sema_post 4
    sema_destroy 5
rwlock 5 rwlock_init 1
    rw_rdlock 2
    rw_wrlock 3
    rw_unlock 4
    rw_tryrdlock 5
    rw_trywrlock 6
    rwlock_destroy 7
rmutex 6 rmutex_init 1
    rmutex_lock 2
    rmutex_trylock 3
    rmutex_unlock 4
    rmutex_destroy 5
barrier 7 barrier_init 1
    barrier_wait 2
    barrier_destroy 3
barrier_spin 8 _barrier_spin_init 1
    _barrier_spin 2
    _barrier_spin_destroy 3
spin 9 _spin_init 1
    _spin_lock 2
    _spin_trylock 3
    _spin_unlock 4
    _spin_destroy 5

 Category       event1   Specific                event2
 of Event       Code     Event                   Code
 thread              1   thr_create                   1
                         thr_exit                     2
                         thr_join                     3
                         thr_self                     4
                         thr_minstack                 5
                         thr_continue                 6
                         thr_suspend                  7
                         thr_setconcurrency           8
                         thr_getconcurrency           9
                         thr_kill                    10
                         thr_sigsetmask              11
                         thr_setscheduler            12
                         thr_getscheduler            13
                         thr_setprio                 14
                         thr_getprio                 15
                         thr_yield                   16
                         thr_get_rr_interval         17
                         thr_keycreate               18
                         thr_keydelete               19
                         thr_setspecific             20
                         thr_getspecific             21
 mutex               2   mutex_init                   1
                         mutex_lock                   2
                         mutex_trylock                3
                         mutex_unlock                 4
                         mutex_destroy                5
 cond                3   cond_init                    1
                         cond_signal                  2
                         cond_broadcast               3
                         cond_wait                    4
                         cond_timedwait               5
                         cond_destroy                 6
 sema                4   sema_init                    1
                         sema_wait                    2
                         sema_trywait                 3
                         sema_post                    4
                         sema_destroy                 5
 rwlock              5   rwlock_init                  1
                         rw_rdlock                    2
                         rw_wrlock                    3
                         rw_unlock                    4
                         rw_tryrdlock                 5
                         rw_trywrlock                 6
                         rwlock_destroy               7
 rmutex              6   rmutex_init                  1
                         rmutex_lock                  2
                         rmutex_trylock               3
                         rmutex_unlock                4
                         rmutex_destroy               5
 barrier             7   barrier_init                 1
                         barrier_wait                 2
                         barrier_destroy              3
 barrier_spin        8   _barrier_spin_init           1
                         _barrier_spin                2
                         _barrier_spin_destroy        3
 spin                9   _spin_init                   1
                         _spin_lock                   2
                         _spin_trylock                3
                         _spin_unlock                 4
                         _spin_destroy                5

Fields a1 - a5 for thread events

The following table shows what the values in fields a1 through a5 represent for each thread trace event. If no value is shown in the table, 0 is recorded in the trace record. Values starting with arg followed by a digit refer to the arguments passed to the interface in question. If one of these arguments is preceded by a '*', the value placed by the indicated interface into the memory location referred to by that argument is recorded. rval indicates the return value from the interface.

event2 which a1 a2 a3 a4 a5
thr_create 1 arg1 arg2 arg3 arg4 arg5
thr_create 2 rval new_tid      
thr_exit 0 arg1        
thr_join 1 arg1        
thr_join 2 *arg2 *arg3 rval    
thr_self 0          
thr_minstack 0          
thr_suspend 1 arg1        
thr_suspend 2 rval        
thr_continue 0 arg1 rval      
thr_getconcurrency 0 rval        
thr_setconcurrency 0 arg1 rval      
thr_kill 0 arg1 arg2 rval    
thr_sigsetmask 0 arg1 arg2 arg3 rval  
thr_keycreate 0 arg1 arg2 rval    
thr_keydelete 0 arg1 rval      
thr_getspecific 0 arg1 *arg2 rval    
thr_setspecific 0 arg1 arg2 rval    
thr_getprio 0 arg1 *arg2 rval    
thr_setprio 0 arg1 arg2 rval    
thr_getscheduler 0 arg1 *arg2.policy *arg2.policy_params rval  
thr_setscheduler 0 arg1 arg2.policy arg2.policy_params rval  
thr_get_rr_interval 0          
thr_yield 0          

 event2                which   a1      a2             a3                    a4     a5
 thr_create            1       arg1    arg2           arg3                  arg4   arg5
 thr_create            2       rval    new_tid
 thr_exit              0       arg1
 thr_join              1       arg1
 thr_join              2       *arg2   *arg3          rval
 thr_self              0
 thr_minstack          0
 thr_suspend           1       arg1
 thr_suspend           2       rval
 thr_continue          0       arg1    rval
 thr_getconcurrency    0       rval
 thr_setconcurrency    0       arg1    rval
 thr_kill              0       arg1    arg2           rval
 thr_sigsetmask        0       arg1    arg2           arg3                  rval
 thr_keycreate         0       arg1    arg2           rval
 thr_keydelete         0       arg1    rval
 thr_getspecific       0       arg1    *arg2          rval
 thr_setspecific       0       arg1    arg2           rval
 thr_getprio           0       arg1    *arg2          rval
 thr_setprio           0       arg1    arg2           rval
 thr_getscheduler      0       arg1    *arg2.policy   *arg2.policy_params   rval
 thr_setscheduler      0       arg1    arg2.policy    arg2.policy_params    rval
 thr_get_rr_interval   0
 thr_yield             0

Fields a1 - a5 for synchronization events

The following table shows what the values in fields a1 through a5 represent for each synchronization trace event. In addition to the symbols explained above, waiters? indicates whether threads were waiting on the synchronization object and block? indicates if the calling thread had to block during the event. For semaphores and barriers, the synchronization object count is provided instead of block? since this provides potentially more useful information.

Event which a1 a2 a3 a4 a5
mutex_init 0 arg1 arg2 arg3 rval  
mutex_lock 1 arg1        
mutex_lock 2 rval block?      
mutex_trylock 0 arg1 rval      
mutex_unlock 0 arg1 rval waiters?    
mutex_destroy 0 arg1 rval      
cond_init 0 arg1 arg2 arg3 rval  
cond_signal 0 arg1 rval waiters?    
cond_broadcast 0 arg1 rval waiters?    
cond_wait 1 arg1 arg2      
cond_wait 2 rval        
cond_timedwait 1 arg1 arg2 arg3.sec arg3.nsec  
cond_timedwait 2 rval        
cond_destroy 0 arg1 rval      
sema_init 0 arg1 arg2 arg3 arg4 rval
sema_wait 1 arg1 s_count      
sema_wait 2 rval        
sema_trywait 0 arg1 rval      
sema_post 0 arg1 rval s_count    
sema_destroy 0 arg1 rval      
rwlock_init 0 arg1 arg2 arg3 rval  
rw_rdlock 1 arg1        
rw_rdlock 2 rval block? rw_readers    
rw_wrlock 1 arg1        
rw_wrlock 2 rval block?      
rw_unlock 0 arg1 rval waiters?    
rw_tryrdlock 0 arg1 rval      
rw_trywrlock 0 arg1 rval      
rwlock_destroy 0 arg1 rval      
rmutex_init 0 arg1 arg2 arg3 rval  
rmutex_lock 1 arg1        
rmutex_lock 2 rval block? rm_depth    
rmutex_trylock 0 arg1 rval      
rmutex_unlock 0 arg1 rval      
rmutex_destroy 0 arg1 rval      
barrier_init 0 arg1 arg2 arg3 arg4 rval
barrier_wait 1 arg1 b_count      
barrier_wait 2 rval        
barrier_destroy 0 arg1 rval      
_barrier_spin_init 0 arg1 arg2 arg3 rval  
_barrier_spin_wait 1 arg1 bs_count      
_barrier_spin_wait 2 rval        
_barrier_spin_destroy 0 arg1 rval      
_spin_init 0 arg1 arg2 rval    
_spin_lock 1 arg1        
_spin_lock 2 block?        
_spin_trylock 0 arg1 rval      
_spin_unlock 0 arg1        
_spin_destroy 0 arg1 rval      

 Event                   which   a1       a2         a3           a4          a5
 mutex_init              0       arg1     arg2       arg3         rval
 mutex_lock              1       arg1
 mutex_lock              2       rval     block?
 mutex_trylock           0       arg1     rval
 mutex_unlock            0       arg1     rval       waiters?
 mutex_destroy           0       arg1     rval
 cond_init               0       arg1     arg2       arg3         rval
 cond_signal             0       arg1     rval       waiters?
 cond_broadcast          0       arg1     rval       waiters?
 cond_wait               1       arg1     arg2
 cond_wait               2       rval
 cond_timedwait          1       arg1     arg2       arg3.sec     arg3.nsec
 cond_timedwait          2       rval
 cond_destroy            0       arg1     rval
 sema_init               0       arg1     arg2       arg3         arg4        rval
 sema_wait               1       arg1     s_count
 sema_wait               2       rval
 sema_trywait            0       arg1     rval
 sema_post               0       arg1     rval       s_count
 sema_destroy            0       arg1     rval
 rwlock_init             0       arg1     arg2       arg3         rval
 rw_rdlock               1       arg1
 rw_rdlock               2       rval     block?     rw_readers
 rw_wrlock               1       arg1
 rw_wrlock               2       rval     block?
 rw_unlock               0       arg1     rval       waiters?
 rw_tryrdlock            0       arg1     rval
 rw_trywrlock            0       arg1     rval
 rwlock_destroy          0       arg1     rval
 rmutex_init             0       arg1     arg2       arg3         rval
 rmutex_lock             1       arg1
 rmutex_lock             2       rval     block?     rm_depth
 rmutex_trylock          0       arg1     rval
 rmutex_unlock           0       arg1     rval
 rmutex_destroy          0       arg1     rval
 barrier_init            0       arg1     arg2       arg3         arg4        rval
 barrier_wait            1       arg1     b_count
 barrier_wait            2       rval
 barrier_destroy         0       arg1     rval
 _barrier_spin_init      0       arg1     arg2       arg3         rval
 _barrier_spin_wait      1       arg1     bs_count
 _barrier_spin_wait      2       rval
 _barrier_spin_destroy   0       arg1     rval
 _spin_init              0       arg1     arg2       rval
 _spin_lock              1       arg1
 _spin_lock              2       block?
 _spin_trylock           0       arg1     rval
 _spin_unlock            0       arg1
 _spin_destroy           0       arg1     rval

Files


tr.xxxxxxx.yyy
trace data files

Environment variables

The following environment variables can be set to change default trace data collection.

Variable Effect
THR_TRACE_EVENTS control which events to trace
THR_TRACE_DIR control directory to create trace files
THR_TRACE_BUF disable buffering of trace

 Variable           Effect
 THR_TRACE_EVENTS   control which events to trace
 THR_TRACE_DIR      control directory to create trace files
 THR_TRACE_BUF      disable buffering of trace

The defaults and alternate values for these environment variables are described below.


THR_TRACE_EVENTS
a colon-separated list of the categories of events to be traced. The categories are the strings listed in the first column of the table above under "Events and Events Categories." For example, to trace only mutex, condition variable and semaphore operations, the value of THR_TRACE_EVENTS should be mutex:cond:sema. The default, if THR_TRACE_EVENTS is NULL, is to trace all events.

THR_TRACE_DIR
the full pathname to a directory writable by the process where trace data files should be stored. The default, if THR_TRACE_DIR is NULL, is to create trace data files in the current working directory.

THR_TRACE_BUF
any non-NULL value. Normally, trace data is buffered and written to file only when the buffer is full or the process is exiting. If THR_TRACE_BUF is set to any non-NULL value, trace data will be flushed immediately. The default, if THR_TRACE_BUF is NULL, is to buffer trace data.

References

synch(3synch), thread(3thread)
© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 25 April 2004