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

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

Security

Examples

1. To produce a trace of the find command on the terminal, type:

   truss find . -print >find.out

2. To trace the lseek, close, statx, and open system calls, type:

   truss -t lseek,close,statx,open find . -print > find.out

3. To display thread id along with regular output for find command, enter:

   truss -l find . -print >find.out 

4. To display timestamps along with regular output for find command, enter:

   truss -d find . -print >find.out 

5. To display delta times along with regular output for find command, enter:

   truss -D find . -print >find.out 

6. 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 

7. To trace all function calls in the libc.a library with names starting with "m", and exclude the strlen() function call in the libc.a library while running the ls command, enter:

   truss -u libc.a::m*,!strlen ls 

8. 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* ls

9. 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 

10. 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