Traces a process's system calls, recieved signals and incurred machine faults.
truss [ -f] [ -c] [ -a] [ -e] [ -i] [ { -t | -x} [!] Syscall [...] ] [ -s [!] Signal [...] ] [ -m [!] Fault [...]] [ { -r | -w} [!] FileDescriptor [...]] [ -o Outfile] {Command| -p pid [. . .]}
The truss command executes a specified command, or attaches to listed process IDs, and produces a trace of the system calls, received signals, and machine faults a process incurs. Each line of the trace output reports either the Fault or Signal name, or the Syscall name with parameters and return values. The subroutines defined in system libraries are not necessarily the exact system calls made to the kernel. The truss command does not report these subroutines, but rather, the underlying system calls they make. When possible, system call parameters are displayed symbolically using definitions from relevant system header files. For path name pointer parameters, truss displays the string being pointed to. By default, undefined system calls are displayed with their name, all eight possible argments and the return value in hexadecimal format.
When the -o flag is used with truss, or if standard error is redirected to a non-terminal file, truss ignores the hangup, interrupt, and signals processes. This facilitates the 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 (using the -p flag), 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 to function normally.
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 (for example, 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).
Every machine fault, with the exception of a page fault, results in posting a signal to the process which incurred the fault. A report of a received signal immediately follows each report of a machine fault, unless that signal is being blocked by the process.
To avoid collisions with other controlling processes, truss does not trace a process which it detects is being controlled by another process with the /proc interface.
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. However, for each process the output is strictly time-ordered. The trace output contains tab characters and standard tab stops are set at every eight positions.
The system may run out of per-user process slots when tracing children. This is because when tracing more than one process, truss runs as one controlling process for each process being traced, doubling the number of process slots being used for any given process. The usual system-imposed limit of 25 processes per user should be taken into account prior to running a trace on multiple processes
truss uses shared memory and semaphores when dealing with more than one process, such as when using the -f flag and -p flag with more than one process id. If need be, these traces can be run even if a system is not configured for them. In these cases, truss issues a warning message and proceeds with the trace. However, the trace output may become garbled, the output of the -c flag reports only the top-level command or first process id, and no children are counted.
The operating system enforces certain security restrictions on the tracing of processes. You must have access privileges to the commands you are tracing. The set-uid and set-gid processes can only be traced by a privileged user. The truss command loses control of any process which performs an execution of a set-id or unreadable object file, unless it is run by a privileged user. These untraced processes continue normally and independently of truss from the point of the execution.
| -a | Displays the parameter strings which are passed in each executed system call. |
| -c | Counts traced system calls, faults, and signals rather than displaying trace results line by line. A summary report is produced after the traced command terminates or when truss is interrupted. If the -f flag is also used, the counts include all traced Syscalls, Faults, and Signals for child processes. |
| -e | Displays the environment strings which are passed in each executed system call. |
| -f | Follows all children created by the fork system call and includes their signals, faults, and system calls in the trace output. Normally, only the first-level command or process is traced. When the -f flag is specified, the process id is included with each line of trace output to show which process executed the system call or received the signal. |
| -i | Keeps interruptible sleeping system calls from being displayed. Certain system calls on terminal devices or pipes, such as open and kread, 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 then reported a second time when it completes. The -i flag causes such system calls to be reported only once, upon completion. |
| -m [!] Fault | Machine faults to trace or exclude. Listed machine faults must be separated from each other by a comma. Faults may be specified by name or number (see the sys/fault.h header file). If the list begins with the "!" symbol, the specified faults are excluded from being displayed with the trace output. The default is -mall. |
| -o Outfile | Designates the file to be used for the trace output. By default, the output goes to standard error. |
| -p | Interprets the parameters to truss as a list of process ids
for an existing process rather than as a command to be executed.
truss takes control of each process and begins tracing it, provided
that the user id and group id of the process match those of the user or that
the user is a privileged user.
|
| -r [!] FileDescriptor | Displays 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 either as an ASCII character (preceded by one blank) or as a two-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 two-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 flag. The default is -r!all. |
| -s [!] Signal | Permits listing Signals to trace or exclude. Those signals specified in a list (separated by a comma) are traced. The trace output reports the receipt of each specified signal even if the signal is being ignored, but 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 the "!" symbol, the listed signals are excluded from being displayed with the trace output. The default is -s all. |
| -t [!] Syscall | Includes or excludes system calls from the trace process. System calls to be traced must be specified in a list and separated by commas. If the list begins with an "!" symbol, the specified system calls are excluded from the trace output. The default is -tall. |
|
| |
| -w [!] FileDescriptor | Displays the contents of the I/O buffer for each write on any of the listed file descriptors (see -r). The default is -w!all. |
| -x [!] Syscall | Displays data from the specified parameters of traced sytem calls in raw format, usually hexadecimal, rather than symbolically. The default is -x!all. |
truss find . -print >find.out
truss -t lseek,close,statx,open find . -print > find.out
/proc filesystem
The fork subroutine.
The /proc file.