|
Hopefully, this page is exactly what you are looking for, but if not, you can always find further assistance on Unix/Linux Forum!
User Commands truss(1)
NAME
truss - trace system calls and signals
SYNOPSIS
truss [-fcaeildDE] [ - [tTvx] [!] syscall ,...] [ - [sS] [!]
signal ,...] [ - [mM] [!] fault ,...] [ - [rw] [!] fd ,...]
[ - [uU] [!] lib ,... : [:] [!] func ,...] [-o outfile] com-
mand | -p pid[/lwps]...
DESCRIPTION
The truss utility executes the specified command and pro-
duces a trace of the system calls it performs, the signals
it receives, and the machine faults it incurs. Each line of
the trace output reports either the fault or signal name or
the system call name with its arguments and return value(s).
System call arguments are displayed symbolically when possi-
ble using defines from relevant system headers. For any path
name pointer argument, the pointed-to string is displayed.
Error returns are reported using the error code names
described in intro(3). If, in the case of an error, the ker-
nel reports a missing privilege, a privilege name as
described in privileges(5) is reported in square brackets ([
]) after the error code name.
Optionally (see the -u option), truss also produce an
entry/exit trace of user-level function calls executed by
the traced process, indented to indicate nesting.
OPTIONS
For those options that 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 can be specified.
For the same name in a list, subsequent options (those to
the right) override previous ones (those to the left).
The following options are supported:
-a
Shows the argument strings that are passed in each
exec() system call.
-c
Counts traced system calls, faults, and signals rather
than displaying the trace line-by-line. A summary report
is produced after the traced command terminates or when
truss is interrupted. If -f is also specified, the
SunOS 5.10 Last change: 31 Jul 2004 1
User Commands truss(1)
counts include all traced system calls, faults, and sig-
nals for child processes.
-d
Includes a time stamp on each line of trace output. The
time stamp appears as a field containing
seconds.fraction at the start of the line. This
represents a time in seconds relative to the beginning
of the trace. The first line of the trace output shows
the base time from which the individual time stamps are
measured, both as seconds since the epoch (see time(2))
and as a date string (see ctime(3C) and date(1)). The
times that are reported are the times that the event in
question occurred. For all system calls, the event is
the completion of the system call, not the start of the
system call.
-D
Includes a time delta on each line of trace output. The
value appears as a field containing seconds.fraction and
represents the elapsed time for the LWP that incurred
the event since the last reported event incurred by that
LWP. Specifically, for system calls, this is not the
time spent within the system call.
-e
Shows the environment strings that are passed in each
exec() system call.
-E
Includes a time delta on each line of trace output. The
value appears as a field containing seconds.fraction and
represents the difference in time elapsed between the
beginning and end of a system call.
In contrast to the -D option, this is the amount of
time spent within the system call.
SunOS 5.10 Last change: 31 Jul 2004 2
User Commands truss(1)
-f
Follows all children created by fork() or vfork() and
includes 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-id
is included with each line of trace output to indicate
which process executed the system call or received the
signal.
-i
Does not display interruptible sleeping system calls.
Certain system calls, such as open() and read() on ter-
minal devices or pipes, 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 reported again a
second time when it completes. The -i option causes such
system calls to be reported only once, when they com-
plete.
-l
Includes the id of the responsible lightweight process
(LWP) with each line of trace output. If -f is also
specified, both the process-id and the LWP-id are
included.
-m [!]fault,...
Machine faults to trace or exclude. Those faults speci-
fied in the comma-separated list are traced. Faults can
be specified by name or number (see <sys/fault.h>). If
the list begins with a !, the specified faults are
excluded from the trace output. Default is -mall
-m!fltpage.
-M [!]fault,...
Machine faults that stop the process. The specified
faults are added to the set specified by -m. If one of
the specified faults is incurred, truss leaves the pro-
cess stopped and abandoned (see the -T option). Default
SunOS 5.10 Last change: 31 Jul 2004 3
User Commands truss(1)
is -M!all.
-o outfile
File to be used for the trace output. By default, the
output goes to standard error.
-p
Interprets the command arguments to truss as a list of
process-ids for existing processes (see ps(1)) rather
than as a command to be executed. truss takes control of
each process and begins tracing it provided that the
userid and groupid of the process match those of the
user or that the user is a privileged user. Users can
trace only selected threads by appending /thread-id to
the process-id. Mutiple threads can be selected using
the - and , delimiters. For example /1,2,7-9 traces
threads 1, 2, 7, 8, and 9. Processes can also be speci-
fied by their names in the /proc directory, for example,
/proc/12345.
-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 newline (\n).
If ASCII interpretation is not possible, the byte is
shown in 2-character hexadecimal representation. (The
first 12 bytes of the I/O buffer for each traced read()
are shown even in the absence of -r.) Default is -r!all.
-s [!]signal,...
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 sig-
nals are not received until they are unblocked.) Signals
can be specified by name or number (see <sys/signal.h>).
If the list begins with a !, the specified signals are
SunOS 5.10 Last change: 31 Jul 2004 4
User Commands truss(1)
excluded from the trace output. Default is -sall.
-S [!]signal,...
Signals that stop the process. The specified signals are
added to the set specified by -s. If one of the speci-
fied signals is received, truss leaves the process
stopped and abandoned (see the -T option). Default is
-S!all.
-t [!]syscall,...
System calls to trace or exclude. Those system calls
specified in the comma-separated list are traced. If the
list begins with a !, the specified system calls are
excluded from the trace output. Default is -tall.
-T [!]syscall,...
Specifies system calls that stop the process. The speci-
fied system calls are added to the set specified by -t.
If one of the specified system calls is encountered,
truss leaves the process stopped and abandoned. That is,
truss releases the process and exits but leaves the pro-
cess in the stopped state at completion of the system
call in question. A debugger or other process inspection
tool (see proc(1)) can then be applied to the stopped
process. truss can be reapplied to the stopped process
with the same or different options to continue tracing.
Default is -T!all.
A process left stopped in this manner cannot be res-
tarted by the application of kill -CONT because it is
stopped on an event of interest via /proc, not by the
default action of a stopping signal (see
signal.h(3HEAD)). The prun(1) command described in
proc(1) can be used to set the stopped process running
again.
-u [!]lib,...:[:][!]func,...
User-level function call tracing. lib,... is a comma-
separated list of dynamic library names, excluding the
``.so.n'' suffix. func,... is a comma-separated list of
SunOS 5.10 Last change: 31 Jul 2004 5
User Commands truss(1)
function names. In both cases the names can include
name-matching metacharacters *,?,[] with the same mean-
ings as those of sh(1) but as applied to the
library/function name spaces, not to files. An empty
library or function list defaults to *, trace all
libraries or functions in a library. A leading ! on
either list specifies an exclusion list, 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.
A single : separating the library list from the function
list means to trace calls into the libraries from out-
side the libraries, but omit calls made to functions in
a library from other functions in the same library. A
double :: means to trace all calls, regardless of ori-
gin.
Library patterns do not match either the executable file
or the dynamic linker unless there is an exact match (l*
does not match ld.so.1). To trace functions in either of
these objects, the names must be specified exactly, as
in:
truss -u a.out -u ld ...
a.out is the literal name to be used for this purpose;
it does not stand for the name of the executable file.
Tracing a.out function calls implies all calls (default
is ::).
Multiple -u options can be specified and they are
honored left-to-right. The id of the thread that per-
formed the function call is included in the trace output
for the call. truss searches the dynamic symbol table in
each library to find function names and also searches
the standard symbol table if it has not been stripped.
-U [!]lib,...:[:][!]func,...
User-level function calls that stop the process. The
specified functions are added to the set specified by
-u. If one of the specified functions is called, truss
leaves the process stopped and abandoned (see the -T
option).
SunOS 5.10 Last change: 31 Jul 2004 6
User Commands truss(1)
-v [!]syscall,...
Verbose. Displays the contents of any structures passed
by address to the specified system calls (if traced by
-t). Input values as well as values returned by the
operating system are shown. For any field used as both
input and output, only the output value is shown.
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 the -r
option). Default is -w!all.
-x [!]syscall,...
Displays the arguments to the specified system calls (if
traced by -t) in raw form, usually hexadecimal, rather
than symbolically. This is for unredeemed hackers who
must see the raw bits to be happy. Default is -x!all.
See man pages section 2: System Calls for system call names
accepted by the -t, -T, -v, and -x options. System call
numbers are also accepted.
If truss is used to initiate and trace a specified command
and if the -o option is used or if standard error is
redirected to a non-terminal file, then truss runs with
hangup, interrupt, and quit signals ignored. This facili-
tates tracing of 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), 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 normally, as
though they had never been touched.
EXAMPLES
Example 1: Tracing a Command
The following example produces a trace of the find(1) com-
mand on the terminal:
SunOS 5.10 Last change: 31 Jul 2004 7
User Commands truss(1)
example$ truss find . -print >find.out
Example 2: Tracing Common System Calls
The following example shows only a trace of the open, close,
read, and write system calls:
example$ truss -t open,close,read,write find . -print >find.out
Example 3: Tracing a Shell Script
The following example produces a trace of the spell(1) com-
mand on the file truss.out:
example$ truss -f -o truss.out spell document
spell is a shell script, so the -f flag is needed to trace
not only the shell but also the processes created by the
shell. (The spell script runs a pipeline of eight
processes.)
Example 4: Abbreviating Output
The following example abreviates output:
example$ truss nroff -mm document >nroff.out
because 97% of the output reports lseek(), read(), and
write() system calls. To abbreviate it:
example$ truss -t !lseek,read,write nroff -mm document >nroff.out
Example 5: Tracing Library Calls From Outside the C Library
The following example traces all user-level calls made to
any function in the C library from outside the C library:
example$ truss -u libc ...
Example 6: Tracing library calls from within the C library
The following example includes calls made to functions in
the C library from within the C library itself:
example$ truss -u libc:: ...
Example 7: Tracing Library Calls Other Than the C Library
The following example traces all user-level calls made to
any library other than the C library:
SunOS 5.10 Last change: 31 Jul 2004 8
User Commands truss(1)
example$ truss -u '*' -u !libc ...
Example 8: Tracing printf and scanf Function Calls
The following example traces all user-level calls to func-
tions in the printf and scanf family contained in the C
library:
example$ truss -u 'libc:*printf,*scanf' ...
Example 9: Tracing Every User-level Function Call
The following example traces every user-level function call
from anywhere to anywhere:
example$ truss -u a.out -u ld:: -u :: ...
Example 10: Tracing a System Call Verbosely
The following example verbosely traces the system call
activity of process #1, init(1M) (if you are a privileged
user):
example# truss -p -v all 1
Interrupting truss returns init to normal operation.
FILES
/proc/* Process files
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Availability | SUNWtoo |
|_____________________________|_____________________________|
SEE ALSO
date(1), find(1), proc(1), ps(1), sh(1), spell(1), init(1M),
intro(3), exec(2), fork(2), lseek(2), open(2), read(2),
time(2), vfork(2), write(2), ctime(3C), signal.h(3HEAD),
proc(4), attributes(5), privileges(5), threads(5)
man pages section 2: System Calls
SunOS 5.10 Last change: 31 Jul 2004 9
User Commands truss(1)
NOTES
Some of the system calls described in man pages section 2:
System Calls differ from the actual operating system inter-
faces. Do not be surprised by minor deviations of the trace
output from the descriptions in that document.
Every machine fault (except a page fault) results in the
posting of a signal to the LWP that incurred 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 operating system enforces certain security restrictions
on the tracing of processes. In particular, any command
whose object file (a.out) cannot be read by a user cannot be
traced by that user; set-uid and set-gid commands can be
traced only by a privileged user. Unless it is run by a
privileged user, truss loses control of any process that
performs an exec() of a set-id or unreadable object file;
such processes continue normally, though independently of
truss, from the point of the exec().
To avoid collisions with other controlling processes, truss
does not trace a process that it detects is being controlled
by another process via the /proc interface. This allows
truss to be applied to proc(4)-based debuggers as well as to
another instance of itself.
The trace output contains tab characters under the assump-
tion that standard tab stops are set (every eight posi-
tions).
The trace output for multiple processes or for a mul-
tithreaded process (one that contains more than one LWP) is
not produced in strict time order. For example, a read() on
a pipe can be reported before the corresponding write().
For any one LWP (a traditional process contains only one),
the output is strictly time-ordered.
When tracing more than one process, truss runs as one con-
trolling process for each process being traced. For the
example of the spell command shown above, spell itself uses
9 process slots, one for the shell and 8 for the 8-member
pipeline, while truss adds another 9 processes, for a total
of 18.
Not all possible structures passed in all possible system
calls are displayed under the -v option.
SunOS 5.10 Last change: 31 Jul 2004 10
Man(1) output converted with
man2html and wrapped by fishsponge
This page was generated on Wed Sep 12 11:25:34 GMT 2007
|
Your favourite pages:
No pages logged yet.
Trying to save cookie... Top 10 most popular pages:
sqlite3 man page (4764 hits)
(openSUSE 10.2)
adv_cap_autoneg man page (4617 hits)
(Solaris 10 11_06)
CPAN man page (4352 hits)
(Suse Linux 10.1)
ssh man page (4196 hits)
(Suse Linux 10.1)
svn man page (3410 hits)
(FreeBSD 6.2)
startproc man page (1957 hits)
(Suse Linux 10.1)
pprosetup man page (1745 hits)
(Solaris 10 11_06)
netcat man page (1697 hits)
(Suse Linux 10.1)
signal man page (1686 hits)
(Suse Linux 10.1)
ssh-socks5-proxy-connect man page (1661 hits)
(Solaris 10 11_06)
|
Man Pages 
