truss(1)truss(1)NAMEtruss - Trace system calls and signals
SYNOPSIStruss [-a] [-c] [-e] [-f] [-i] [-m[!]fault[,fault]...] [-ooutfile]
[-rw[!]filedesc[,filedesc]...] [-s[!]signal[,signal]...]
[-tvx[!]syscall[,syscall]...] command[,command]...
truss-p [-a] [-c] [-e] [-f] [-i] [-m[!]fault[,fault]...] [-ooutfile]
[-rw[!]filedesc[,filedesc]...] [-s[!]signal[,signal]...]
[-tvx[!]syscall[,syscall]...] process[,processid]...
OPTIONS
The truss utility recognizes the options listed in this section.
Options can be specified in any order, and you can use the same option
more than once.
For options that take a list argument (listitem[,listitem...]), you can
use all to specify all possible members of the list. If the list
begins with an exclamation point (!), the truss utility excludes rather
than traces the members of the list. For the same name in a list, sub‐
sequent options (to the right) override previous ones (to the left).
Shows the argument strings which are passed in each exec() system call.
Counts traced system calls, faults, and signals rather than displaying
each on its own line. A summary report is produced after the traced
command terminates or when the truss utility is interrupted. If the -f
option is also specified, the counts include all traced system calls,
faults, and signals for child processes. Shows the environment strings
which are passed in each exec() system call. Follows all children cre‐
ated by fork() and includes their signals, faults, and system calls in
the trace output. Normally, only the first-level command or process is
traced. When you specify this option, the process ID is included with
each line of trace output to indicate which process executed the system
call or received the signal. Does not display interruptible sleeping
system calls. Certain system calls, such as open() and read() on termi‐
nal devices or pipes can sleep for indefinite periods and are inter‐
ruptible. Normally, the truss utility reports such sleeping system
calls if they remain asleep for more than one second and a second time
when it completes. The -i option causes such system calls to be
reported only once, when they complete. Traces specified machine
faults. You may specify machine faults by name or number (see
<sys/fault.h>). The default is -mall -m!fltpage.
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 follow immediately each report of a
machine fault (except a page fault) unless that signal is being
blocked by the process. Uses specified file for trace output.
By default, output goes to standard error. Interprets truss
utility operands as a list of process IDs for existing processes
rather than commands to be executed. If you are the process
owner or have root privileges, the truss utility takes control
of each process and begins tracing it. The trace output for mul‐
tiple processes is not produced in strict time order. For exam‐
ple, a read() on a pipe may be reported before the corresponding
write(). For any one process, the output is strictly time-
ordered.
The truss utility does not accept list arguments to the -p
option. For example:
truss-a -p -c 1234 is valid;
truss-a -p 1234 -c is not.
You can also specify processes by their names in the /proc
directory, such as /proc/01234; this also works for remotely-
mounted /proc directories. Refer to the ps(1) reference page.
Shows the full contents of the I/O buffer for each read() on
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 the -r option. The default is -r!all. Traces speci‐
fied signals. The trace output reports the receipt of each spec‐
ified 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 num‐
ber (refer to <sys/signal.h>). The default is -sall. Traces
specified system calls. You can use -tosf_all to trace all sys‐
tem calls supported by the OSF1 habitat. The default is -tall.
Verbose. Displays the contents of any structures passed by
address to the specified system calls, if traced. Input values
are shown, as well as values returned by the operating system.
For any field used as both input and output, only the output
value is shown. You can use -vosf_all to trace all system calls
supported by the OSF1 habitat. The default is -v!all.
Using the ! modifier indicates that the verbose display of
arguments is excluded from the output.
Not all possible structures passed in all possible system calls
are displayed under the -v option. Shows the full contents of
the I/O buffer for each write() on 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 horizon‐
tal tab (\t) and newline (\n). If ASCII interpretation is not
possible, the byte is shown in 2-character hexadecimal represen‐
tation. The first 16 bytes of the I/O buffer for each traced
write() are shown even in the absence of the -w option. The
default is -w!all. Displays the arguments to specified system
calls (if traced) in raw form (usually hexadecimal) rather than
symbolically. This is for unredeemed hackers who must see the
raw bits to be happy. You can use -xosf_all to trace all system
calls supported by the OSF1 habitat. The default is -x!all.
OPERANDS
Execute and trace commands according to the specified options. With
the -p option, trace existing processes according to the specified
options.
DESCRIPTION
[SVR4] The truss utility executes the specified commands and produces
a trace of system calls, signals received, and machine faults incurred.
If you use the -p option, operands are interpreted as existing pro‐
cesses to trace.
Each line of the trace output reports either the fault or signal name
or the system call name with its arguments and return values. System
call arguments are displayed symbolically when possible using defines
from relevant system header files; for any path name pointer argument,
the pointed-to string is displayed. Error returns are reported using
the error code names described in the intro(2) reference page.
If you initiate and trace a command and use the -o option or if you re‐
direct standard error to a non-terminal file, hangup, interrupt, and
quit signals are ignored. This helps you trace interactive programs
that catch interrupt and quit signals from the terminal.
If the trace output remains directed to the terminal or if you use the
-p option to trace existing processes, the truss utility responds to
hangup, interrupt, and quit signals by releasing all traced processes
and exiting. This lets you terminate excessive trace output and release
previously-existing processes. Released processes continue normally, as
though they had never been touched.
NOTES
The trace output contains tab characters under the assumption that
standard tab stops are set at every eight positions.
Some of the files that are referenced by absolute path in the System V
Environment reference pages may actually be located relative to
/usr/opt/svr4. This is particularly true in the case where the inclu‐
sive view option has not been installed.
RESTRICTIONS
The operating system enforces certain security restrictions on process
tracing. Any command whose object file (a.out) cannot be read by a user
cannot be traced by that user; setuid and setgid commands can be traced
only by a user with root privileges. Unless run by a privileged user,
the truss utility loses control of any process that performs an exec of
a set-id or unreadable object file. Such processes continue indepen‐
dently of the truss utility from the point of the
exec.
To avoid collisions with other controlling processes, the truss utility
will not trace a process that is being controlled by another process
through the /proc interface. This allows the truss utility to be
applied to proc(4)-based debuggers as well as to another instance of
itself.
When tracing child processes with the -f option, the system may run out
of per-user process slots. When tracing multiple processes, the truss
utility runs a single controlling process in addition to each traced
process. For example, the spell command uses nine process slots, one
for the shell and eight for the eight -member pipeline, while the truss
utility adds another for a total of ten. The usual system-imposed limit
is 64 processes per user.
EXIT STATUS
Success. Either one of the following conditions causes the truss util‐
ity to exit with a non-zero status: The truss utility is not invoked
correctly. Refer to the Errors section. Any of the commands or pro‐
cesses being traced exits with a non-zero status.
ERRORS
$ truss-p nnnn truss: no process nnnn
Explanation:
Process nnnn does not exist.
User Action:
Use an existing process ID.
$ truss-t syscall truss: no unrecognized syscall: syscall
Explanation:
There is no system call syscall.
User Action:
Use a valid system call. This error message can occur with the -t, -v,
or -x options.
$ truss-s signal truss: unrecognized signal name/number: signal
Explanation:
There is no signal signal.
User Action:
Use a valid signal name or number.
$ truss-m fault truss: unrecognized fault name/number: fault
Explanation:
There is no fault fault.
User Action:
Use a valid fault name or number.
EXAMPLES
The following example traces the find command on the terminal: $ truss
find . -print > find.out
To see only a trace of the open, close, read, and write system
calls for the same command: $ truss-t open,close,read,write
find . -print > find.out The following example traces the spell
command and directs the output to the file truss.out: $ truss-f
-o truss.out spell doc_name
The spell command is a shell script that runs a pipeline of
eight concurrent processes, so the -f option is used to trace
not only the shell but also the processes that it creates. The
following example provides too much output, because most of it
traces lseek(), read(), and write() system calls:
$ truss nroff -man factor.1 > factor.out
To provide more useful output, use the following options: $
truss-t !lseek,read,write nroff -man factor.1 > factor.out If
you have root privileges, this example verbosely traces the
activity of process 1, init: # truss-p -vall 1
Interrupting the truss utility returns init to normal operation.
ENVIRONMENT VARIABLES
Resolves the behaviour of the command for all options that produce con‐
flicting behaviour. If this variable is set to SVR4 or svr4, the com‐
mand behaves as a System V command. The SVR4 options are documented
with the [SVR4] tag.
FILES
process files
SEE ALSOps(1)intro(2)setuid(2)proc(4)signal(4)truss(1)
