For those options that 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 (for example, exclude
rather than trace). Multiple occurrences of the same option can be specified.
For the same name in a list, subsequent options (those to the right) override
previous ones (those to the left).
The following options are supported:
-a
Shows the argument strings that are passed in each
exec() system call.
-c
Counts 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.
-d
Includes a time stamp on each line of trace output. The
time stamp appears as a field containing
seconds.
fraction at the
start of the line. This represents a time in seconds relative to the beginning
of the trace. The first line of the trace output shows the base time from
which the individual time stamps are measured, both as seconds since the epoch
(see
time(2)) and as a date string (see
ctime(3C) and
date(1)). The times that are reported are the times that the event in
question occurred. For all system calls, the event is the completion of the
system call, not the start of the system call.
-D
Includes a time delta on each line of trace output. The
value appears as a field containing seconds.fraction and
represents the elapsed time for the LWP that incurred the event since
the last reported event incurred by that LWP. Specifically, for system
calls, this is not the time spent within the system call.
-e
Shows the environment strings that are passed in each
exec() system call.
-E
Includes a time delta on each line of trace output. The
value appears as a field containing
seconds.fraction and
represents the difference in time elapsed between the beginning and end of a
system call.
In contrast to the -D option, this is the amount of time
spent within the system call.
-f
Follows all children created by fork() or
vfork() and includes 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.
-i
Does not 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.
-l
Includes the id of the responsible lightweight process
(LWP) with each line of trace output. If -f is also specified,
both the process-id and the LWP-id are included.
-m [!]fault,...
Machine faults to trace or exclude. Those faults
specified in the comma-separated list are traced. Faults can be specified by
name or number (see <sys/fault.h>). If the list begins with a
!, the specified faults are excluded from the trace output. Default is
-mall -m !fltpage.
-M [!]fault,...
Machine faults that stop the process. The specified
faults are added to the set specified by -m. If one of the specified
faults is incurred, truss leaves the process stopped and abandoned (see
the -T option). Default is -M!all.
-o outfile
File to be used for the trace output. By default, the
output goes to standard error.
-p
Interprets the
command 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. Users can trace only
selected threads by appending
/thread-id to the process-id.
Multiple threads can be selected using the
- and
, delimiters.
For example
/1,2,7-9 traces threads
1,
2,
7,
8, and
9. Processes can also be specified by their names in the
/proc directory, for example,
/proc/12345.
-r [!]fd,...
Shows 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 12 bytes of the I/O buffer for
each traced print >read() are shown even in the absence of
-r.) Default is -r!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).
(Blocked signals are not received until they are unblocked.) Signals can 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.
-S [!]signal,...
Signals that stop the process. The specified signals are
added to the set specified by -s. If one of the specified signals is
received, truss leaves the process stopped and abandoned (see the
-T option). Default is -S!all.
-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.
-T [!]syscall,...
Specifies system calls that stop the process. The
specified system calls are added to the set specified by
-t. If one of
the specified system calls is encountered,
truss leaves the process
stopped and abandoned. That is,
truss releases the process and exits
but leaves the process in the stopped state at completion of the system call
in question. A debugger or other process inspection tool (see
proc(1))
can then be applied to the stopped process.
truss can be reapplied to
the stopped process with the same or different options to continue tracing.
Default is
-T!all.
A process left stopped in this manner cannot be restarted by the
application of kill -CONT because it is stopped on an event of
interest via /proc, not by the default action of a stopping signal
(see signal.h(3HEAD)). The prun(1) command described in
proc(1) can be used to set the stopped process running again.
-u
[!]lib,...:[:][!]func,...
User-level function call tracing.
lib,... is a
comma-separated list of dynamic library names, excluding the
``
.so.n'' suffix.
func,... is a comma-separated list of
function names. In both cases the names can include name-matching
metacharacters
*,
?,
[] with the same meanings as those of
sh(1) but as applied to the library/function name spaces, not to files.
An empty library or function list defaults to
*, trace all libraries or
functions in a library. A leading
! on either list specifies an
exclusion list, names of libraries or functions not to be traced. Excluding a
library excludes all functions in that library; any function list following a
library exclusion list is ignored.
A single : separating the library list from the function
list means to trace calls into the libraries from outside the libraries, but
omit calls made to functions in a library from other functions in the same
library. A double :: means to trace all calls, regardless of
origin.
Library patterns do not match either the executable file or the
dynamic linker unless there is an exact match (l* does not match
ld.so.1). To trace functions in either of these objects, the names
must be specified exactly, as in:
truss -u a.out -u ld ...
a.out is the literal name to be used for this purpose; it
does not stand for the name of the executable file. Tracing a.out
function calls implies all calls (default is ::).
Multiple -u options can be specified and they are honored
left-to-right. The id of the thread that performed the function call is
included in the trace output for the call. truss searches the dynamic
symbol table in each library to find function names and also searches the
standard symbol table if it has not been stripped.
-U
[!]lib,...:[:][!]func,...
User-level function calls that stop the process. The
specified functions are added to the set specified by -u. If one of the
specified functions is called, truss leaves the process stopped and
abandoned (see the -T option).
-v [!]syscall,...
Verbose. Displays the contents of any structures passed
by address to the specified system calls (if traced by -t). 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.
-w [!]fd,...
Shows the contents of the I/O buffer for each
write() on any of the specified file descriptors (see the -r
option). Default is -w!all.
-x [!]syscall,...
Displays the arguments to the specified system calls (if
traced by -t) in raw form, usually hexadecimal, rather than
symbolically. This is for unredeemed hackers who must see the raw bits to be
happy. Default is -x!all.
See man pages section 2: System Calls for system call names
accepted by the -t, -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 that 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.
Example 1 Tracing a Command
The following example produces a trace of the find(1)
command on the terminal:
example$ truss find . -print >find.out
Example 2 Tracing Common System Calls
The following example shows only a trace of the open, close, read,
and write system calls:
example$ truss -t open,close,read,write find . -print >find.out
Example 3 Tracing a Shell Script
The following example produces a trace of the spell(1)
command on the file truss.out:
example$ 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 processes.)
Example 4 Abbreviating Output
The following example abbreviates output:
example$ truss nroff -mm document >nroff.out
because 97% of the output reports lseek(), read(),
and write() system calls. To abbreviate it:
example$ truss -t !lseek,read,write nroff -mm document >nroff.out
Example 5 Tracing Library Calls From Outside the C
Library
The following example traces all user-level calls made to any
function in the C library from outside the C library:
example$ truss -u libc ...
Example 6 Tracing library calls from within the C
library
The following example includes calls made to functions in the C
library from within the C library itself:
example$ truss -u libc:: ...
Example 7 Tracing Library Calls Other Than the C
Library
The following example traces all user-level calls made to any
library other than the C library:
example$ truss -u '*' -u !libc ...
Example 8 Tracing printf and scanf Function
Calls
The following example traces all user-level calls to functions in
the printf and scanf family contained in the C library:
example$ truss -u 'libc:*printf,*scanf' ...
Example 9 Tracing Every User-level Function Call
The following example traces every user-level function call from
anywhere to anywhere:
example$ truss -u a.out -u ld:: -u :: ...
Example 10 Tracing a System Call Verbosely
The following example verbosely traces the system call activity of
process #1, init(8) (if you are a privileged user):
example# truss -p -v all 1
Interrupting truss returns init to normal
operation.
Some of the system calls described in man pages section 2: System Calls
differ from the actual operating system interfaces. Do not be surprised by
minor deviations of the trace output from the descriptions in that document.
Every machine fault (except a page fault) results in the posting
of a signal to the LWP that incurred the fault. A report of a
received signal immediately follows each report of a machine fault (except a
page fault) unless that signal is being blocked.
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
that performs an exec() of a set-id or unreadable object file; such
processes continue normally, though independently of truss, from the
point of the exec().
To avoid collisions with other controlling processes, truss
does not trace a process that it detects is being controlled by another
process via the /proc interface. This allows truss to be
applied to proc(5)-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 or for a multithreaded
process (one that contains more than one LWP) is not produced in
strict time order. For example, a read() on a pipe can be reported
before the corresponding write(). For any one LWP (a
traditional process contains only one), the output is strictly
time-ordered.
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.
Not all possible structures passed in all possible system calls
are displayed under the -v option.