thread_trace(4) thread_trace(4)
NAME
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:
Copyright 1994 Novell, Inc. Page 1
thread_trace(4) thread_trace(4)
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
Copyright 1994 Novell, Inc. Page 2
thread_trace(4) thread_trace(4)
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
Copyright 1994 Novell, Inc. Page 3
thread_trace(4) thread_trace(4)
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
Copyright 1994 Novell, Inc. Page 4
thread_trace(4) thread_trace(4)
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
Copyright 1994 Novell, Inc. Page 5
thread_trace(4) thread_trace(4)
_________________________________________________________________________________
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.
Copyright 1994 Novell, Inc. Page 6
thread_trace(4) thread_trace(4)
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)
Copyright 1994 Novell, Inc. Page 7