Commands Reference, Volume 5

truss Command

Purpose

Traces a process's system calls, dynamically loaded user level function calls, received signals, and incurred machine faults.

Syntax

truss [ -f] [ -c] [ -a] [ -l ] [ -d ] [ -D ] [ -e] [ -i] [ { -t | -x} [!] Syscall [...] ] [ -s [!] Signal [...] ] [ { -m }[!] Fault [...]] [ { -r | -w} [!] FileDescriptor [...] ] [ { -u } [!]LibraryName [...]:: [!]FunctionName [ ... ] ] [ -o Outfile] {Command| -p pid [. . .]}

Description

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.

The lightweight processes (LWP) mentioned in truss output are really kernel threads. The option -l displays the LWP id (i.e. the thread id) on each line of the trace output.

User library functions in AIX libraries have both static and dynamic loaded function calls. The tracing with option -u is done for dynamically loaded function calls only.

User level function call tracing for dynamically loaded function calls is provided with -u option. This option will produce an entry/exit trace of the function calls.

Flags

-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.
-d	A timestamp will be included with each line of output. Time displayed is in seconds relative to the beginning of the trace. The first line of the trace output will show the base time from which the individual time stamps are measured. By default timestamps are not displayed.
-D	Delta time is displayed on each line of output. The delta time represents the elapsed time for the LWP that incurred the event since the last reported event incurred by that thread. By default delta times are not displayed.
-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.
-l	Display the id (thread id) of the responsible LWP process along with truss output. By default LWP id is not displayed in the output.
-m [!]Fault	Traces the machine faults in the process. Machine faults to trace must be separated from each other by a comma. Faults may be specified by name or number (see the sys/procfs.h header file). If the list begins with the "!" symbol, the specified faults are excluded from being traced and are not displayed with the trace output. The default is -m`all` -m`!fltpage`.
-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.
-u [!] [LibraryName [...]::[!]FunctionName [...] ]	Traces dynamically loaded user level function calls from user libraries. The LibraryName is a comma-separated list of library names. The FunctionName is a comma-separated list of function names. In both cases the names can include name-matching metacharacters *, ?, [] with the same meanings as interpreted by the shell but as applied to the library/function name spaces, and not to files. A leading ! on either list specifies an exclusion list of 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. Multiple -u options may be specified and they are honored left-to-right. By default no library/function calls are traced.
-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.

Examples

To produce a trace of the find command on the terminal, type:
```
truss find . -print >find.out
```
To trace the lseek, close, statx, and open system calls, type:
```
truss -t lseek,close,statx,open find . -print > find.out
```
To display thread id along with regular output for find command, enter:
```
truss -l find . -print >find.out 
```
To display timestamps along with regular output for find command, enter:
```
truss -d find . -print >find.out 
```
To display delta times along with regular output for find command, enter:
```
truss -D find . -print >find.out 
```
To trace the malloc() function call and exclude the strlen() function call in the libc.a library while running the ls command, enter:
```
truss -u libc.a::malloc,!strlen ls 
```
To trace all function calls in the libc.a library with names starting with "m" while running the ls command, enter:
```
truss -u libc.a::m*,!strlen ls 
```
To trace all function calls from the library libcurses.a and exclude calls from libc.a while running executable foo, enter:
```
truss -u libcurses.a,!libc.a::* foo 
```
To trace the refresh() function call from libcurses.a and the malloc() function call from libc.a while running the executable foo, enter:
```
 truss -u libc.a::malloc -u libcurses.a::refresh foo
```

Files

/proc filesystem

Related Information

The fork subroutine.

The /proc file.