truss(1) truss(1)
NAME
truss - trace system calls and signals
SYNOPSIS
truss [-p] [-f] [-c] [-a] [-e] [-i] [-[tvx] [!] syscall...] [-s [!]
signal...] [-m [!] fault...] [-[rw] [!] fd...] [-o outfile]
command
DESCRIPTION
truss executes the specified command and produces a trace of the
system calls it performs, the signals it receives, and the machine
faults it incurs. Each line of the trace output reports either the
fault or signal name or the system call name with its arguments and
return value(s). System call arguments are displayed symbolically
when possible using defines from relevant system header files; for
any pathname pointer argument, the pointed-to string is displayed.
Error returns are reported using the error code names described in
intro(2).
The following options are recognized. For those options which take a
list argument, the name all can be used as a shorthand to specify all
possible members of the list. If the list begins with a !, the
meaning of the option is negated (e.g., exclude rather than trace).
Multiple occurrences of the same option may be specified. For the
same name in a list, subsequent options (those to the right) override
previous ones (those to the left).
-p Interpret the arguments to truss as a list of process-
ids for existing processes (see ps(1)) rather than as a
command to be executed. truss takes control of each
process and begins tracing it provided that the userid
and groupid of the process match those of the user or
that the user is a privileged user. Processes may also
be specified by their names in the /proc directory,
e.g., /proc/1234; this works for remotely-mounted /proc
directories as well.
-f Follow all children created by fork() and include their
signals, faults, and system calls in the trace output.
Normally, only the first-level command or process is
traced. When -f is specified, the process-id is
included with each line of trace output to indicate
which process executed the system call or received the
signal.
-c Count traced system calls, faults, and signals rather
than displaying the trace line-by-line. A summary
report is produced after the traced command terminates
or when truss is interrupted. If -f is also specified,
the counts include all traced system calls, faults, and
signals for child processes.
7/91 Page 1
truss(1) truss(1)
-a Show the argument strings which are passed in each
exec() system call.
-e Show the environment strings which are passed in each
exec() system call.
-i Don't display interruptible sleeping system calls.
Certain system calls, such as open() and read() on
terminal devices or pipes can sleep for indefinite
periods and are interruptible. Normally, truss reports
such sleeping system calls if they remain asleep for
more than one second. The system call is reported
again a second time when it completes. The -i option
causes such system calls to be reported only once, when
they complete.
-t [!] syscall,...
System calls to trace or exclude. Those system calls
specified in the comma-separated list are traced. If
the list begins with a `!', the specified system calls
are excluded from the trace output. Default is -tall.
-v [!] syscall,...
Verbose. Display the contents of any structures passed
by address to the specified system calls (if traced).
Input values as well as values returned by the
operating system are shown. For any field used as both
input and output, only the output value is shown.
Default is -v!all.
-x [!] syscall,...
Display the arguments to the specified system calls (if
traced) in raw form, usually hexadecimal, rather than
symbolically. Default is -x!all.
-s [!] signal,...
Signals to trace or exclude. Those signals specified
in the comma-separated list are traced. The trace
output reports the receipt of each specified signal,
even if the signal is being ignored (not blocked) by
the process. (Blocked signals are not received until
the process releases them.) Signals may be specified
by name or number (see <sys/signal.h>). If the list
begins with a `!', the specified signals are excluded
from the trace output. Default is -sall.
-m [!] fault,...
Machine faults to trace or exclude. Those machine
faults specified in the comma-separated list are
traced. Faults may be specified by name or number (see
<sys/fault.h>). If the list begins with a `!', the
Page 2 7/91
truss(1) truss(1)
specified faults are excluded from the trace output.
Default is -mall -m!fltpage.
-r [!] fd,... Show the full contents of the I/O buffer for each
read() on any of the specified file descriptors. The
output is formatted 32 bytes per line and shows each
byte as an ascii character (preceded by one blank) or
as a 2-character C language escape sequence for control
characters such as horizontal tab (\t) and newline
(\n). If ascii interpretation is not possible, the
byte is shown in 2-character hexadecimal
representation. (The first 16 bytes of the I/O buffer
for each traced read() are shown even in the absence of
-r.) Default is -r!all.
-w [!] fd,... Show the contents of the I/O buffer for each write() on
any of the specified file descriptors (see -r).
Default is -w!all.
-o outfile File to be used for the trace output. By default, the
output goes to standard error.
See Section 2 of the Programmer's Reference Manual for syscall names
accepted by the -t, -v, and -x options. System call numbers are also
accepted.
If truss is used to initiate and trace a specified command and if the
-o option is used or if standard error is redirected to a non-
terminal file, then truss runs with hangup, interrupt, and quit
signals ignored. This facilitates tracing of interactive programs
which catch interrupt and quit signals from the terminal.
If the trace output remains directed to the terminal, or if existing
processes are traced (the -p option), then truss responds to hangup,
interrupt, and quit signals by releasing all traced processes and
exiting. This enables the user to terminate excessive trace output
and to release previously-existing processes. Released processes
continue normally, as though they had never been touched.
EXAMPLES
This example produces a trace of the find(1) command on the terminal:
truss find . -print >find.out
Or, to see only a trace of the open, close, read, and write system
calls:
truss -t open,close,read,write find . -print >find.out
7/91 Page 3
truss(1) truss(1)
This produces a trace of the spell(1) command on the file truss.out:
truss -f -o truss.out spell document
spell is a shell script, so the -f flag is needed to trace not only
the shell but also the processes created by the shell. (The spell
script runs a pipeline of eight concurrent processes.)
A particularly boring example is:
truss nroff -mm document >nroff.out
because 97% of the output reports lseek(), read(), and write() system
calls. To abbreviate it:
truss -t !lseek,read,write nroff -mm document >nroff.out
This example verbosely traces the activity of process #1, init(1M)
(provided you are a privileged user):
truss -p -v all 1
Interrupting truss returns init to normal operation.
FILES
/proc/nnnnn process files
NOTES
Some of the system calls described in Section 2 of the Programmer's
Reference Manual differ from the actual operating system interfaces.
Do not be surprised by minor deviations of the trace output from the
descriptions in Section 2.
Every machine fault (except a page fault) results in the posting of a
signal to the process which incurred the fault. A report of a
received signal will immediately follow each report of a machine
fault (except a page fault) unless that signal is being blocked by
the process.
The operating system enforces certain security restrictions on the
tracing of processes. In particular, any command whose object file
(a.out) cannot be read by a user cannot be traced by that user; set-
uid and set-gid commands can be traced only by a privileged user.
Unless it is run by a privileged user, truss loses control of any
process which performs an exec(2) of a set-id or unreadable object
file; such processes continue normally, though independently of
truss, from the point of the exec().
Page 4 7/91
truss(1) truss(1)
To avoid collisions with other controlling processes, truss will not
trace a process which it detects is being controlled by another
process via the /proc interface. This allows truss to be applied to
proc(4)-based debuggers as well as to another instance of itself.
The trace output contains tab characters under the assumption that
standard tab stops are set (every eight positions).
The trace output for multiple processes is not produced in strict
time order. For example, a read() on a pipe may be reported before
the corresponding write(). For any one process, the output is
strictly time-ordered.
The system may run out of per-user process slots when tracing of
children is requested. When tracing more than one process, truss
runs as one controlling process for each process being traced. For
the example of the spell command shown above, spell itself uses 9
process slots, one for the shell and 8 for the 8-member pipeline,
while truss adds another 9 processes, for a total of 18. This is
perilously close to the usual system-imposed limit of 25 processes
per user.
truss uses shared memory and semaphores when dealing with more than
one process (-f option or -p with more than one pid). It issues a
warning message and proceeds when these are needed but not configured
in the system. However, the trace output may become garbled in this
case and the output of the -c option reports only the top-level
command or first pid and no children are counted.
Not all possible structures passed in all possible system calls are
displayed under the -v option.
On -
03 systems supporting the -
03 Binary Compatible Standard, BCS,
truss may not correctly trace programs compiled and linked on a pre
-
ov system.
SEE ALSO
intro(2), proc(4) in the Programmer's Reference Manual.
7/91 Page 5