HP-11ia/TUSC

NAME

SYNOPSIS

truss [options ] command | -p pid ...  

DESCRIPTION

Tusc traces the system calls a process invokes and the signals it receives. It displays arguments in a symbolic way, shows the first bytes of read and write buffers as well as signal information when available. Tusc can attach to live processes by providing PIDs (process IDs) as argument(s).

If desired, tusc can be invoked as truss, by linking one binary to the other, in order to provide reasonable compatibility with the UnixWare/Solaris tracing tool (see "TRUSS COMPATIBILITY" below).

When invoked as tusc, the options are:

Print exec arguments. If execv(2) syscall is being traced, print all exec arguments and their addresses.

Append to output file. This option has no effect if an output file has not been specified using the -o option.

Show branch events, on IPF (this option is not supported on PA-RISC). To obtain meaningful data, the -i should be used with this option.

Set max data size for -r and -w options. By default, when using these options, the whole read/write buffers are dumped. This option causes a maximum bytes number of bytes to be displayed.

Count syscalls and signals. If a single -c is present, tusc will only report the number of system calls executed by the process(es), the number of errors, if any, the accumulated CPU time for each syscall, and the number of signals. If more than one -c is present, tusc will behave as if this option was not used (i.e. display its normal output) but will report these statistics upon completion. If more than two -c's are present, the CPU time for each syscall instance is also reported, in seconds, between angle brackets at the beginning of each line.

Is similar to -c option but provides more precision and more information, in particular, the low, high and average system call times.

Select file descriptors. This option allows the user to display syscalls using certain file descriptors. If the first character of the string is a plus sign (+), syscalls that do not return or whose argument list doesn't contain file descriptors are also displayed. For the remaining part of the argument string, see the ARGUMENT LISTS section below. Note that, unlike with the -s option, the system call filtering is done by tusc, not by the kernel. See also the -r and -w options.

For instance, using tusc -d8 date will only display syscalls using file descriptor 8 but using tusc -d+8 date will also display syscalls which do not involve file descriptors.

Print environment variables. If execv(2) syscall is being traced, print all environment variables and their addresses.

Show syscall entries. Tusc doesn't require OS notification for system call entry. It collects all the data it needs when the system call returns. This option will cause tusc to stop upon syscall entry and produce a trace. This option is only useful for processes encountering invalid syscall errors as it will show the number of the invalid syscall.

Follow forks. Normally tusc only traces the parent side of fork(2)s. With this option, it will trace all children. Note that debuggers or tracers (like tusc) cannot be followed since only one debugger is allowed to attach to a process at any given time.

Print feature level. Newer kernels provide a way to obtain the ttrace feature level. This option will return that level. See <sys/ttrace.h>.

Do not allow attaching to any process in tusc's session (see getsid(2)). This option is only meaningful when providing process IDs as arguments.

Print syscall list (#define, id and number of arguments) for validation purposes.

Print the status of the entire process hierarchy when idle. Normally, unless the -i is specified, tusc reports the waiting syscall for the last active process only. With this option the state of all processes currently traced is reported.

Don't show sleeping (interruptible) syscalls. By default, if a system call takes more than 1 to 2 seconds to complete, or if the traced process is spinning in user mode, an indication of the state of the process is displayed. If this option is used, these traces are suppressed. See ENVIRONMENT section.

Single-step and display instructions. This option allows the user to single-step through the target program between all or some of the system calls. The output can be fed to a disassembler to provide more information. The n1 argument specifies that single-stepping should occur after the n1'th syscall. The n2 argument specifies the number of syscalls after which single-stepping will stop (default is the remainder of the process).

The PC and instructions that are displayed (not available with older kernels) are obtained from the SIGTRAP siginfo and are the PC/instruction where the single-step originated from. If a single -v flag is provided, the current PC and instruction will also be displayed. If two -v flags are present, the register context at the time of the single-step is also printed.

Keep tracing after main process exits. Normally, when specifying a binary (not a process ID) to trace and following children, tusc will terminate when that process exits. This option forces it to wait until all children have exited. This is especially useful when tracing daemon processes that place themselves in the background by forking and exiting the parent. When this option is used, tusc exits with the exit code of the process that was last traced.

Print all lwpids. This option is most useful when tracing multi-threaded processes.

Print process names. This option is most useful when tracing a large number of processes.

Send trace output to given file or file descriptor. Normally, tusc's output goes to standard output. This option provides a way to separate tusc's standard output from that of the process(es) it traces. If the argument is a valid number greater than zero, it is assumed to be a file descriptor, not a file name. For instance, "tusc -o2" will cause the traces to go to stderr.

Print pids. By default, process IDs are not printed.

Quiet. Most informational warnings are not printed.

Print read buffers for given file descriptors. If this option is used, all (unless the dump size is modified using the -b option) read data performed by the specified file descriptor(s) is dumped. See the ARGUMENT LISTS section below.

The data, by default, is displayed 32 byte wide using characters followed by a blank, if the character is printable, a "C" escape sequence notation or a 2 digit hexadecimal value. See the ENVIRONMENT section for ways to dump data in different formats.

Note that the -d option has precedence: no buffer data will be displayed if the file descriptor has been selected out.

Show syscall restarts. This option shows system call restarts. It is not clear how useful it is at this point.

Select syscalls. By default, all system calls are traced. This option allows a user to trace a limited number of calls. See the ARGUMENT LISTS section below. The arguments can be a combination of numbers, full system call names or global expressions.

Select signals. By default, all signals are traced. This option allows tracing of a limited number of signals. See the ARGUMENT LISTS section below. The arguments can be a combination of numbers, full signal names or signal names without the SIG prefix (i.e. SIGINT or INT both work). Specifying uncatchable signals has no effect.

Detach process if it enters traced mode. If this option is used, tusc silently checks system call entry events and releases the process if it is performing a ttrace(TT_PROC_SETTRC) or a ptrace(PT_SETTRC) syscall. If the call is ttrace(TT_PROC_ATTACH) or ptrace(PT_ATTACH), the process being attached to is also released if tusc was tracing it.

Show time stamp for each syscall and signal. If the format argument is an empty string or if it is the string "hires", the time of day in tv_sec.tv_usec format will be displayed. Else, format is expected to be a string containing time formatting directives. For details, refer to the strftime(3C) man page.

User thread IDs. If this option is present, user thread IDs (see pthreads) are displayed.

Verbose. If this option is present, more verbose data is produced for some system calls. Additional -v options will provide more data for a subset of those syscalls (the stat, statfs, statvfs and pstat families). Three -v options provides the most verbosity at this time.

Print version. This option simply prints the current tusc version.

Print write buffers for given file descriptors. Identical to option but for write buffers.

Print raw (hex) arguments. Tusc produces symbolic output for a large number of system calls. This option causes all arguments to be displayed in hexadecimal rather than in symbolic form. If used with the -v option, data that are normally displayed in symbolic form are also displayed in hexadecimal.

Print syscall traces in an exportable format. When this option is used, Tusc will print the syscall traces in an format that will allow them to be imported by a spreadsheet: IDs, time stamps, syscall name, syscall argument(s) in a single parenthesized block and return value(s) are separated with tabs. Signal traces are split in 2 blocks, the first one being the signal received, the second the remainder of the data. Refer to the ENVIRONMENT section if another field separator is desired. All verbose or buffer data is unchanged.

Verbose option for registers. A single -y will print the PC (and disassemble the instruction, on IPF), an additional -y will dump all registers. This option is only meaningful when -I is used. For backward compatibility, the -v option has the same effect on register display but will also produce verbose system call data where available.

Do not print information about successful syscalls. Print only failed syscalls as well as all signals.

ARGUMENT LISTS

SEE ALSO

ttrace(2), ttrace_wait(2), strftime(3c), regcomp(3), fnmatch(3).

A front end script, sstep, is available to provide on-the-fly symbolic disassembly.  

EXAMPLES

tusc date

Trace the date(1) command.

tusc 1

Trace init(1M), if super-user.

tusc -f -o make.trace make

Trace make(1) and all the processes it invokes and send the output to the file make.trace.

tusc -s read,write cat /etc/passwd

Show the read and write syscalls from the command 'cat /etc/passwd'.

tusc -s !sig,mmap sleep 10

Show all system calls except mmap and those having 'sig' in their name.

CAVEATS

Historically, debuggers (applications using tracing interfaces) have destroyed their children, or the processes they are attached to, when exiting, or, rather, the operating system has provided this service to them. This is clearly not always a desirable behavior and tusc catches signals in order to detach itself from processes it may have attached to, before exiting. However, in the case of multiple tracers tracing each other and the last one attaching to a live process (for instance, "tusc tusc <PID>"), it is possible that the first tracer will exit first, taking the entire process chain with it and not allowing the last one to detach from the PID before exiting.
Newer (currently unreleased) versions of the OS allow a debugger to specify what action should be taken upon debugger exit. Tusc uses the detach-on-exit option when running on OSes that provide that option.

When tracing the crooked shell (aka C-shell, aka csh) and following children, on 11.0, one should ignore SIGUSR1 to avoid races between parent and child processes. This problem is fixed in the 11i kernel.  

NOTE

TRUSS COMPATIBILITY

o The default trace output becomes stderr.

o The default filler character is changed from dot to space.

o The pid/lwpid display more closely resembles output from truss.

The following truss options are supported (see truss(1) on UnixWare or Solaris for details):

Same as tusc's. Compatible with truss.

Same as tusc's but only one level supported.

Compatible with truss.

Same as tusc's -ccc but without the syscall summary.

Same as tusc's. Compatible with truss.

Same as tusc's but also turns on process ID display as it does with truss.

Same as tusc's. Compatible with truss.

Same as tusc's. Compatible with truss.

Same as tusc's. Compatible with truss.

Compatible with truss.

Same as tusc's. Compatible with truss.

Same as tusc's -S option. Compatible with truss.

Same as tusc's -s option. Compatible with truss.

Argument is ignored. -v is turned on for all syscalls.

Same as tusc's. Compatible with truss.

Argument is ignored. -x is turned on for all syscalls.

The following truss options are not supported: -m, -M, -T, -S, -u, -U.  

ENVIRONMENT

Unless the -i option is used, tusc uses a 2 second alarm to report sleeping system calls in the process that was last continued. The TUSCALARM variable may be used to change the default alarm.

Tusc has preset values to horizontally divide the output into syscall data and return value. The TUSCMARGIN variable may be set to specify a number of columns for the latter. Values greater than the number of columns are ignored.

The width used to print process names, when the -n option is used, can be adjusted by setting the TUSCNMW variable to a positive number.

If the -n option is used, TUSCSN can be set to true to convert commands' full path names into simple names.

By default, read/write buffers contents are displayed in character pairs, using the following algorithm: ascii printable characters are printed with a space on the right, the "C" language's escape character constants (\0, \n, \r, etc...) are printed as such and all other characters are printed in hexadecimal. The TUSCBUFMODE variable alters this behavior. If it is set to hex, all words will be printed in hexadecimal. If it is set to ascii, printable characters will be printed without spaces on the right and non-printable characters will be shown as dots. If it is set to dual, hexadecimal values are printed on the left of the pipe sign, ascii on the right. In dual mode, output resulting from the -r and -w options is also boxed, the hex values are space separated and the columns are numbered.

Some system calls have variable argument lists. If TUSCVARARGS is set to true, these syscalls will only display the arguments examined by the OS to avoid displaying garbage. Currently, only open(2), ptrace(2) and sysfs(2) have been registered as supporting variable arguments.

Tusc reports inconsistent number of arguments between what it expects and what the OS reports. Undeclared syscalls (reported as SC-### where ### is the syscall number) do not generate this warning unless TUSCMMAW, which stands for "mismatch argument warning", is set to all. Note that these warnings or any "SC-###" report indicates that tusc's internal syscall table should be updated.

By default, when running in truss compatibility mode, unsupported options cause a warning to be printed to stderr. If TRUSSSTRICT is set to true, unsupported options will cause truss to exit.

Setting the TUSCL10N variable to true will cause system error messages, time stamps and floating numbers to be localized on systems that support it.

By default, the verbose output is center justified and aligned on the colon, if the LHS is wide enough, and always includes at least 2 spaces on the left. The TUSCVWIDTH variable controls the position of the colon. If that variable is set to zero, the output will be left justfied. The verbose data for the getdents syscall is always left justified, due to the nature of the output.

The TUSCMATCH variable controls what type of pattern matching is used. If the value is reg, tusc evaluates regular expressions using regcomp(3) with the REG_ICASE and REG_NOSUB options. If the value is sh, tusc uses shell (see sh(1)) pattern matching. If the value is both, the latter is used if the former doesn't provide a match. When running in truss emulation mode, the variable is not evaluated and sh pattern matching is used.

Unless the -x option is used, IPv6 addresses are printed using the double colon ('::') notation to skip contiguous zero elements (for instance, the IPv6 loopback would be displayed as ::1). If this behavior is not desired, setting TUSCRAWIPV6 to true will cause tusc to print all elements.

By default, tusc ignores failing system calls when setting high/low execution times (-C option). Setting the TUSCHILOERRS variable to true will cause tusc to include failing syscalls.

By default, tusc uses tabs as field separators when the -X option is used. The TUSCSEP can be used to specify a character string (including a null string) to be used instead of the tabs.

When single-stepping on IPF, the default is to use symbolic register names. If the TUSCPHYSREGNAMES variable is set to true, physical register names will be used.

Newer versions of tusc print user, interrupt and elapsed times upon exit when syscall statistics are requested. If the TUSCNOUSTATS variable is set to true, this additional information won't be printed.

By default, the -T hires prints the time starting at the current time. If the TUSCTRUSSTIMESTAMPS variable is set to true, it will start at zero like the -d option of truss does.  

AUTHOR

IPF disassembler contributed by Steven M. Valentine (HP).

Copyright (c) 1996-2007 Hewlett-Packard Development Company, L.P.  

DISCLAIMER