truss

trace program on NuTCRACKER Platform 

Command

SYNOPSIS

truss [-fFaelT] [-[tvx] [!]syscall, ...] [-s [!]signal, ...] [-[rw] [!]fd, ...] [-o outfile] program args

truss [-fFaelT] [-[tvx] [!]syscall, ...] [-s [!]signal, ...] [-[rw] [!]fd, ...] -o outfile -p pid...

DESCRIPTION

truss executes the specified NuTCRACKER Platform program, or attaches to the specified NuTCRACKER Platform processes, and produces a trace of system calls, the signals it receives, and machine faults. Each line of the trace output reports either the fault or signal name or the system call name with its arguments and return values. System call arguments are displayed symbolically when possible using defines from relevant system headers; for any path name pointer argument, the full path name is displayed.

Every machine fault (except a page fault) posts a signal to the thread incurring 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 trace output for multiple processes or for a multithreaded process is not produced in strict time order. For example, a read() on a pipe may be reported before the corresponding write(). For any one thread, the output is strictly time-ordered.

Not all possible structures passed in all possible system calls are displayed by the -v option. Many system calls display structure constants independent of the setting of -v.

Options

For those options that take a list argument, the name all can be used as shorthand to specify all possible members of the list. If the list begins with !, 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).

-a  

shows the argument strings that are passed in each exec() system call.

-e  

shows the environment strings that are passed in each exec() system call.

-f  

follows all children created by fork() or vfork() and include 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 IDs is included with each line of trace output to indicate which process executed the system call or received the signal.

-F  

is similar to -f, except that tracing continues across an exec().

-l  

includes the thread ID in each line of output.

-o outfile  

specifies the file to be used for the trace output. By default, the output goes to standard error.

-p pid ...  

interprets the command arguments to truss as a list of process IDs for existing processes 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. You must use -o outfile, when using this option. This option must appear at the end of the command line.

-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 new line (\n). If ASCII interpretation is not possible, the byte is shown in 2-character hexadecimal representation. (The first 48 bytes of the I/O buffer for each traced read() are shown even in the absence of -r.) The default is -r !all.

-s [!]signal,...  

specifies 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.) Specify signals by number (see <sys/signal.h>). If the list begins with !, the specified signals are excluded from the trace output. The default is -s all.

-t [!]syscall,...  

specifies system calls to trace or exclude. Those system calls specified in the comma-separated list are traced. If the list begins with !, the specified system calls are excluded from the trace output. The default is -t all.

-T  

includes a time stamp with each line of output.

-v [!]syscall,...  

uses verbose mode. It displays the contents of any structures passed by address to the specified system calls (if traced). Input values as well as return values are shown. For any field used as both input and output, only the output value is shown. The 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 -r). The default is -w !all.

-x [!]syscall,...  

displays the arguments to the specified system calls (if traced) in raw form, usually hexadecimal, rather than symbolically. The default is -x !all.

Options that take a system call name can also take value pthread as a placeholder for all POSIX thread calls. For example, use -t !pthread to disable tracing of all POSIX thread calls.

If you trace a command and use the -o option or redirect standard error to a non-terminal file, truss ignores hangup, interrupt, and quit signals. This helps trace 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), truss responds to hangup, interrupt, and quit signals by releasing all traced processes and exiting. This lets you terminate excessive trace output and release previously existing processes. Released processes continue normally, as though they had never been touched.

The timestamp printed when the -T option is specified is the number of milliseconds since the system was started, as returned by the Win32 GetTickCount() API function. The tick count rolls over after approximately 49.7 days.

PORTABILITY

UNIX 98.

AVAILABILITY

PTC MKS Toolkit for Power Users
PTC MKS Toolkit for System Administrators
PTC MKS Toolkit for Developers
PTC MKS Toolkit for Interoperability
PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition

SEE ALSO

Commands:
ipcs, process

PTC MKS Toolkit 10.5 Documentation Build 40.