truss(1) truss(1)
NAME
truss - trace system calls and signals
SYNOPSIS
truss [option ...] command
DESCRIPTION
truss executes the specified command and produces a trace of the sys-
tem calls it performs, the signals it receives, and the machine faults
it causes. Each line of the trace output reports either the fault or
the 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 header files. Error returns are reported
using the error names described in introprm2(2).
OPTIONS
No option specified:
truss writes to standard error a trace of the system calls the
specified command performs, the signals it receives, and the
machine errors it causes.
With the following options, it is possible to specify the same option
more than once with different option arguments. In the event of con-
flicts, the options to the right override those further to the left.
-a truss outputs the argument strings which are passed in each
exec(2) system call.
-c truss counts the traced system calls, faults and signals rather
than displaying the trace, outputting the result after the speci-
fied command has terminated or when truss is interrupted. The
count contains a separate total for system calls, faults and sig-
nals.
If -f is also specified, the counts also include system calls,
faults and signals for all child processes.
-e truss outputs the environment strings which are passed in each
exec(2) system call.
-f truss also traces all the child processes created by fork(2) and
includes their system calls, faults and signals. The process ID
(PID) is included with each line of trace output to indicate
which process executed the system call or received the signal.
-f not specified:
Only the first-level command or process is traced.
Page 1 Reliant UNIX 5.44 Printed 11/98
truss(1) truss(1)
-i truss does not trace interruptible sleeping system calls, such as
open(2) and read(2) on terminal devices or pipes, until they have
terminated.
-i not specified:
truss traces interruptible sleeping processes once when they have
been asleep for more than a second, and again when they have ter-
minated.
-m [!]fault, ...
You specify one or more machine faults that you want truss to
trace. Faults may be specified either name or number (see
<sys/fault.h>). If you want all faults traced, you can enter all
for fault. If you put an exclamation point ! before fault, truss
excludes the listed faults from the trace output.
-m [!]fault not specified:
has the same effect as -m all -m !fltpage, i.e. all machine
faults apart from FLTPAGE (recoverable page fault) are traced.
-o outfile
truss writes the trace to outfile.
-o outfile not specified:
truss writes the trace to standard error.
-p truss interprets command as a list of process IDs (PIDs) 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 the user ID (UID) and group ID (GID) [see ps(1)] of
the user match those of the process, or the user is the system
administrator. Processes can also be specified by their name in
the /proc directory, e.g. /proc/1234. This works for remotely
mounted proc directories as well.
-r [!]fd, ...
truss shows the full contents of the I/O buffer for each read(2)
system call on any of the specified file descriptors fd. Specify-
ing all for fd gives you all file descriptors. If you put an exc-
lamation point ! before fd, truss excludes the listed file
descriptors from the trace output. The output is formatted 32
bytes per line and shows each byte as an ASCII character preceded
by one blank or as a two-character C language escape sequence for
control characters, such as \t for horizontal tab or \n for new-
line. If ASCII interpretation is not possible, the byte is shown
in hexadecimal code.
Page 2 Reliant UNIX 5.44 Printed 11/98
truss(1) truss(1)
-r [!]fd not specified:
has the same effect as -r !all, i.e. truss does not show the full
contents of the I/O buffer for any file descriptor. Only the
first twelve bytes of the I/O buffer are show for each traced
read(2) or write(2).
-s [!]signal, ...
You specify a comma-separated list of signals that truss is to
trace. To trace all signals, you specify all for signal. If you
put an exclamation point ! before signal, truss excludes the
listed signals from the trace output. truss traces 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 signal(5)].
-s [!]signal not specified:
has the same effect as -s all, i.e. all signals are traced.
-t [!]syscall, ...
You specify a comma-separated list of system calls that truss is
to trace. To trace all system calls, you specify all for syscall.
If you put an exclamation point ! before syscall, truss excludes
the listed system calls from the trace output. System calls may
be specified by name or number [see introprm2(2)].
-t [!]syscall not specified:
has the same effect as -t all, i.e. all system calls are traced.
-v [!]syscall, ...
truss displays the contents of any structures passed by address
to the specified system call(s). Input values as well as the
values returned by the operating system are shown. For any field
used as both input and output, only the output value is given. To
trace all system calls, you specify all for syscall. If you put
an exclamation point ! before syscall, truss excludes the struc-
ture contents of the listed system calls from the trace output.
System calls may be specified by name or number [see
introprm2(2)].
-v [!]syscall not specified:
has the same effect as -v !all.
-w [!]fd, ...
as -r, but for write(2) rather than read(2).
Page 3 Reliant UNIX 5.44 Printed 11/98
truss(1) truss(1)
-x [!]systemcall, ...
truss displays the arguments to the specified system call(s) in
raw form, usually hexadecimal, rather than symbolically. To
specify all system calls, you enter all for syscall. If you put
an exclamation mark ! before syscall, truss excludes the listed
system calls from the trace output. System calls may be specified
by name or number [see introprm2(2)].
-x [!]systemcall not specified:
has the same effect as -x !all, i.e. no system call is displayed
in hexadecimal.
FUNCTIONALITY
If you call truss with the -o option or redirect standard error to a
non-terminal file, truss ignores SIGHUP, SIGINT and SIGQUIT signals.
This facilitates tracing of interactive programs which receive such
signals from the terminal.
If the truss output is directed to a terminal or if existing processes
are being traced with the -p option, truss responds to SIGHUP, SIGINT
and SIGQUIT signals by releasing all traced processes and terminating.
This enables you to terminate excessive trace output and to release
processes that existed before truss was started. Released processes
continue normally as though they had never been touched.
Every machine fault, except a page fault, results in the posting of a
signal to the process which caused 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: Thus, for example, a truss, which waits with
semop for the release of a semaphore, returns a null value instead of
the expected "sleeping", as data structures can be lost if a number of
processes are traced by truss. Thus any command whose object file
(a.out) cannot be read by a user cannot be traced by that user. Com-
mands for which the set-user-id or set-group-id bit [see chmod(1)] has
been set can only be traced by the system administrator. Unless run by
the system administrator, truss loses control of any process which
performs an exec(2) for an object file for which the set-uid or set-
gid bit has been set or which is unreadable. Such processes continue
normally, though independently of truss, from the point at which the
exec(2) is performed.
To avoid conflicts with other controlling processes, truss will not
trace a process which it detects is being controlled by another pro-
cess via the /proc interface. For each existing process, a file that
can be accessed by calls like open(2), close(2) and ioctl(2) is set up
in the /proc directory. This mechanism is used by debuggers such as
sdb as an alternative to ptrace(2). truss uses this mechanism as well.
A process that is already being controlled by another process on the
Page 4 Reliant UNIX 5.44 Printed 11/98
truss(1) truss(1)
basis of /proc cannot be processed by truss, as the following example
shows:
$ truss -o /dev/null sh&
Let us assume that the sh process has the PID 18027:
$ truss -p 18027
truss: someone else is tracing process 18027
It is possible, however, to apply truss to a debugger that in turn is
controlling a process on the basis of /proc. truss can then trace the
debugger, but not the processes started by the debugger. Similarly,
truss can be applied to another instance of itself, e.g.:
$ truss truss ls
| |
| cannot be traced by the first truss as already controlled
| by the second truss on the basis of proc(4)
|
can be traced
The truss 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(2) on a pipe may be reported before the
corresponding write(2). For any one process, the output is strictly
time-ordered.
The system may run out of per-user process slots when tracing of child
processes is requested (the system has an upper limit of 25
processes). When tracing more than one process, truss runs as one con-
trolling process for each process being traced. For example, the spell
command requires 9 processes and truss adds another 9, giving a total
of 18.
truss uses shared memory and semaphores when dealing with more than
one process (-f and -p options with more than one PID). It issues a
warning message and proceeds when these are needed but not configured
in the system. The truss output may become garbled in this case, how-
ever, and the output of the -c option reports only the top-level com-
mand or first PID and no child processes are counted.
Page 5 Reliant UNIX 5.44 Printed 11/98
truss(1) truss(1)
ERROR MESSAGES
truss: someone else is tracing process <PID>
truss was applied to a process that was already being controlled.
truss: invalid process id: <PID>
Self-explanatory.
truss: cannot control process <PID>
No access rights for process ID PID.
truss: Cannot find program: name
Self-explanatory.
EXAMPLES
Example 1
The find command is to be traced, with the trace displayed on the
screen (standard error) and the output of find (standard output)
directed to the file find.out:
$ truss find . -print > find.out
Example 2
The system calls open(2), close(2), read(2) and write(2) invoked by
find are to be traced:
$ truss -t open,close,read,write find . -print > find.out
Example 3
The spell command is to be traced with a file called document passed
as an argument. The truss output is to be redirected to the file
truss.out. Since spell is a shell script, truss must be called with
the -f option so that any child processes are traced.
$ truss -f -o truss.out spell document
Example 4
The activities of the init process are to be traced. Only the system
administrator is allowed to do this.
$ truss -p -v all 1
FILES
/proc directory containing the files set up for the current process
SEE ALSO
ps(1), introprm2(2), signal(5).
Page 6 Reliant UNIX 5.44 Printed 11/98