| TRUSS(1) | User Commands | TRUSS(1) |
truss - trace system calls and signals
truss [-fcaeildDE] [- [tTvx] [!] syscall ,...]
[- [sS] [!] signal ,...] [- [mM] [!] fault ,...]
[- [rw] [!] fd ,...]
[- [uU] [!] lib ,... : [:] [!] func ,...]
[-o outfile] command | -p pid[/lwps]...
The truss utility 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 headers. For any path name pointer argument, the pointed-to string is displayed. Error returns are reported using the error code names described in Intro(3). If, in the case of an error, the kernel reports a missing privilege, a privilege name as described in privileges(7) is reported in square brackets ([ ]) after the error code name.
Optionally (see the -u option), truss also produce an entry/exit trace of user-level function calls executed by the traced process, indented to indicate nesting.
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
-c
-d
-D
-e
-E
In contrast to the -D option, this is the amount of time spent within the system call.
-f
-i
-l
-m [!]fault,...
-M [!]fault,...
-o outfile
-p
-r [!]fd,...
-s [!]signal,...
-S [!]signal,...
-t [!]syscall,...
-T [!]syscall,...
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,...
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,...
-v [!]syscall,...
-w [!]fd,...
-x [!]syscall,...
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.
/proc/*
date(1), find(1), proc(1), ps(1), sh(1), spell(1), exec(2), fork(2), lseek(2), open(2), read(2), time(2), vfork(2), write(2), Intro(3), ctime(3C), signal.h(3HEAD), proc(5), attributes(7), privileges(7), threads(7), init(8)
man pages section 2: System Calls
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.
| July 31, 2004 | OmniOS |