TUSC(1) TUSC(1)
Not currently an official HP product
NAME
tusc - trace unix system calls
SYNOPSIS
tusc [options] command [args ...] | pid [pid ...]
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:
-a Print exec arguments. If execv(2) syscall is being traced,
print all exec arguments and their addresses.
-A Append to output file. This option has no effect if an output
file has not been specified using the -o option.
-B 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.
-b bytes
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.
-c 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.
-C Is similar to -c option but provides more precision and more
information, in particular, the low, high and average system
call times.
- 1 - Formatted: April 18, 2024
TUSC(1) TUSC(1)
Not currently an official HP product
-d [+][!]fds
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.
-D Print syscall execution time, i.e. the elapsed time between
syscall entry and return events, in parenthesis. Note that
this data is more accurate on 11.31 than on older versions
because, starting with that version, the timing information is
provided by the kernel. On older releases, particularly under
heavy CPU loads, latency can influence these values.
-e Print environment variables. If execv(2) syscall is being
traced, print all environment variables and their addresses.
-E 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.
-f 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.
-F Print feature level. Newer kernels provide a way to obtain the
ttrace feature level. This option will return that level. See
<sys/ttrace.h>.
-g 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.
-G Print syscall list (#define, id and number of arguments) for
validation purposes.
-h Print the status of the entire process hierarchy when idle.
Normally, unless the -i is specified, tusc reports the waiting
- 2 - Formatted: April 18, 2024
TUSC(1) TUSC(1)
Not currently an official HP product
syscall for the last active process only. With this option the
state of all processes currently traced is reported.
-i 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.
-I n1[/n2]
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.
-k 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.
-l Print all lwpids. This option is most useful when tracing
multi-threaded processes.
-n Print process names. This option is most useful when tracing a
large number of processes.
-o [file|fd]
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.
- 3 - Formatted: April 18, 2024
TUSC(1) TUSC(1)
Not currently an official HP product
-p Print pids. By default, process IDs are not printed.
-Q Quiet. Most informational warnings are not printed.
-r [!]fds
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.
-R Show syscall restarts. This option shows system call restarts.
It is not clear how useful it is at this point.
-s [!]syscalls
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.
-S [!]signals
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.
-t 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.
-T format
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
- 4 - Formatted: April 18, 2024
TUSC(1) TUSC(1)
Not currently an official HP product
formatting directives. For details, refer to the strftime(3C)
man page.
-u User thread IDs. If this option is present, user thread IDs
(see pthreads) are displayed.
-v 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.
-V Print version. This option simply prints the current tusc
version.
-w [!]fds
Print write buffers for given file descriptors. Identical to
-r option but for write buffers.
-x 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.
-X 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.
-y 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.
-z Do not print information about successful syscalls. Print only
failed syscalls as well as all signals.
ARGUMENT LISTS
Several tusc options require a list of objects (syscalls, file
descriptors, signals). The argument lists are in the form:
[!]arg1[,arg2[,...]]
- 5 - Formatted: April 18, 2024
TUSC(1) TUSC(1)
Not currently an official HP product
The optional leading '!', means "all but". The rest of the string is a
list of arguments separated by commas (',') or the all keyword which,
except for syscall names, has the expected behavior.
The -d option supports multiple file descriptor ranges in the form:
[!]low-high,[low2-high2],...
The -s option supports a single begin-end range as argument:
[!]syscall-[syscall]
where syscall can be a system call number or an exact system call
name. If the second value is omitted, the last system call number is
implied. This is mostly useful to debug newly added syscalls
internally.
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
Tusc cannot trace a process being debugged or traced by another
process since a process may only have one debugger at a time.
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
- 6 - Formatted: April 18, 2024
TUSC(1) TUSC(1)
Not currently an official HP product
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
The tusc interface and features may evolve in the future.
TRUSS COMPATIBILITY
If tusc is invoked as truss, it provide some level of compatibility
with the latter:
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):
-a Same as tusc's. Compatible with truss.
-c Same as tusc's but only one level supported.
-d Compatible with truss.
-D Same as tusc's -ccc but without the syscall summary.
-e Same as tusc's. Compatible with truss.
-f Same as tusc's but also turns on process ID display as it does
with truss.
-i Same as tusc's. Compatible with truss.
-l Same as tusc's. Compatible with truss.
-o Same as tusc's. Compatible with truss.
-p Compatible with truss.
-r Same as tusc's. Compatible with truss.
- 7 - Formatted: April 18, 2024
TUSC(1) TUSC(1)
Not currently an official HP product
-s Same as tusc's -S option. Compatible with truss.
-t Same as tusc's -s option. Compatible with truss.
-v Argument is ignored. -v is turned on for all syscalls.
-w Same as tusc's. Compatible with truss.
-x Argument is ignored. -x is turned on for all syscalls.
The following truss options are not supported: -m, -M, -T, -S, -u, -U.
ENVIRONMENT
Tusc aligns return values, when possible, and uses dots as filler. If
the TUSCFILLER variable is set, that string is used as filler instead
if it doesn't contain tabs or non printable characters.
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 truss (or if the program is invoked as
truss), the space will be to the left of the printable characters. 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
- 8 - Formatted: April 18, 2024
TUSC(1) TUSC(1)
Not currently an official HP product
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.
- 9 - Formatted: April 18, 2024
TUSC(1) TUSC(1)
Not currently an official HP product
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.
On 11.23 and newer systems, lwp_create causes a syscall return event
to be generated by the kernel, in the context of the newly created
thread, before that thread executes any syscall. Setting
TUSCLWPCREATECHILD to true will cause this event to be reported.
AUTHOR
Written by Chris Bertin (HP).
IPF disassembler contributed by Steven M. Valentine (HP).
Copyright (c) 1996-2011 Hewlett-Packard Development Company, L.P.
DISCLAIMER
Tusc is not an official Hewlett-Packard product. As such, it is
delivered "as is" with no expressed or implied warranty and is a "use
at your own risk" tool.
- 10 - Formatted: April 18, 2024
