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:
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
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
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
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
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
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.