1 '\" te
2 .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
3 .\" Copyright 1989 AT&T
4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
7 .TH TRUSS 1 "Jul 31, 2004"
8 .SH NAME
9 truss \- trace system calls and signals
10 .SH SYNOPSIS
11 .LP
12 .nf
13 \fBtruss\fR [\fB-fcaeildDE\fR] [\fB-\fR [tTvx] [!] \fIsyscall\fR ,...]
14 [\fB-\fR [sS] [!] \fIsignal\fR ,...] [\fB-\fR [mM] [!] \fIfault\fR ,...]
15 [\fB-\fR [rw] [!] \fIfd\fR ,...]
16 [\fB-\fR [uU] [!] \fIlib\fR ,... : [:] [!] \fIfunc\fR ,...]
17 [\fB-o\fR \fIoutfile\fR] \fIcommand\fR | \fB-p\fR \fIpid\fR[\fI/lwps\fR]...
18 .fi
19
20 .SH DESCRIPTION
21 .sp
22 .LP
23 The \fBtruss\fR utility executes the specified command and produces a trace of
24 the system calls it performs, the signals it receives, and the machine faults
25 it incurs. Each line of the trace output reports either the fault or signal
26 name or the system call name with its arguments and return value(s). System
27 call arguments are displayed symbolically when possible using defines from
28 relevant system headers. For any path name pointer argument, the pointed-to
29 string is displayed. Error returns are reported using the error code names
30 described in \fBIntro\fR(3). If, in the case of an error, the kernel reports a
31 missing privilege, a privilege name as described in \fBprivileges\fR(5) is
32 reported in square brackets (\fB[ ]\fR) after the error code name.
33 .sp
34 .LP
35 Optionally (see the \fB-u\fR option), \fBtruss\fR also produce an entry/exit
36 trace of user-level function calls executed by the traced process, indented to
37 indicate nesting.
38 .SH OPTIONS
39 .sp
40 .LP
41 For those options that take a list argument, the name \fBall\fR can be used as
42 a shorthand to specify all possible members of the list. If the list begins
43 with a \fB!\fR, the meaning of the option is negated (for example, exclude
44 rather than trace). Multiple occurrences of the same option can be specified.
45 For the same name in a list, subsequent options (those to the right) override
46 previous ones (those to the left).
47 .sp
48 .LP
49 The following options are supported:
50 .sp
51 .ne 2
52 .na
53 \fB\fB-a\fR\fR
54 .ad
55 .sp .6
56 .RS 4n
57 Shows the argument strings that are passed in each \fBexec()\fR system call.
58 .RE
59
467 file \fBtruss.out\fR:
468
469 .sp
470 .in +2
471 .nf
472 example$ \fBtruss -f -o truss.out spell \fIdocument\fR\fR
473 .fi
474 .in -2
475 .sp
476
477 .sp
478 .LP
479 \fBspell\fR is a shell script, so the \fB-f\fR flag is needed to trace not only
480 the shell but also the processes created by the shell. (The spell script runs a
481 pipeline of eight processes.)
482
483 .LP
484 \fBExample 4 \fRAbbreviating Output
485 .sp
486 .LP
487 The following example abreviates output:
488
489 .sp
490 .in +2
491 .nf
492 example$ \fBtruss nroff -mm \fIdocument\fR >nroff.out\fR
493 .fi
494 .in -2
495 .sp
496
497 .sp
498 .LP
499 because 97% of the output reports \fBlseek()\fR, \fBread()\fR, and
500 \fBwrite()\fR system calls. To abbreviate it:
501
502 .sp
503 .in +2
504 .nf
505 example$ \fBtruss -t !lseek,read,write nroff -mm \fIdocument\fR >nroff.out\fR
506 .fi
507 .in -2
585 .LP
586 \fBExample 10 \fRTracing a System Call Verbosely
587 .sp
588 .LP
589 The following example verbosely traces the system call activity of process #1,
590 \fBinit\fR(1M) (if you are a privileged user):
591
592 .sp
593 .in +2
594 .nf
595 example# \fBtruss -p -v all 1\fR
596 .fi
597 .in -2
598 .sp
599
600 .sp
601 .LP
602 Interrupting \fBtruss\fR returns \fBinit\fR to normal operation.
603
604 .SH FILES
605 .sp
606 .ne 2
607 .na
608 \fB\fB/proc/*\fR\fR
609 .ad
610 .RS 11n
611 Process files
612 .RE
613
614 .SH SEE ALSO
615 .sp
616 .LP
617 \fBdate\fR(1), \fBfind\fR(1), \fBproc\fR(1), \fBps\fR(1), \fBsh\fR(1),
618 \fBspell\fR(1), \fBinit\fR(1M), \fBIntro\fR(3), \fBexec\fR(2), \fBfork\fR(2),
619 \fBlseek\fR(2), \fBopen\fR(2), \fBread\fR(2), \fBtime\fR(2), \fBvfork\fR(2),
620 \fBwrite\fR(2), \fBctime\fR(3C), \fBsignal.h\fR(3HEAD), \fBproc\fR(4),
621 \fBattributes\fR(5), \fBprivileges\fR(5), \fBthreads\fR(5)
622 .sp
623 .LP
624 \fIman pages section 2: System Calls\fR
625 .SH NOTES
626 .sp
627 .LP
628 Some of the system calls described in \fIman pages section 2: System Calls\fR
629 differ from the actual operating system interfaces. Do not be surprised by
630 minor deviations of the trace output from the descriptions in that document.
631 .sp
632 .LP
633 Every machine fault (except a page fault) results in the posting of a signal to
634 the \fBLWP\fR that incurred the fault. A report of a received signal
635 immediately follows each report of a machine fault (except a page fault) unless
636 that signal is being blocked.
637 .sp
638 .LP
639 The operating system enforces certain security restrictions on the tracing of
640 processes. In particular, any command whose object file (\fBa.out\fR) cannot be
641 read by a user cannot be traced by that user; set-uid and set-gid commands can
642 be traced only by a privileged user. Unless it is run by a privileged user,
643 \fBtruss\fR loses control of any process that performs an \fBexec()\fR of a
644 set-id or unreadable object file; such processes continue normally, though
645 independently of \fBtruss\fR, from the point of the \fBexec()\fR.
646 .sp
|
1 '\" te
2 .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
3 .\" Copyright 1989 AT&T
4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
7 .TH TRUSS 1 "Jul 31, 2004"
8 .SH NAME
9 truss \- trace system calls and signals
10 .SH SYNOPSIS
11 .LP
12 .nf
13 \fBtruss\fR [\fB-fcaeildDE\fR] [\fB-\fR [tTvx] [!] \fIsyscall\fR ,...]
14 [\fB-\fR [sS] [!] \fIsignal\fR ,...] [\fB-\fR [mM] [!] \fIfault\fR ,...]
15 [\fB-\fR [rw] [!] \fIfd\fR ,...]
16 [\fB-\fR [uU] [!] \fIlib\fR ,... : [:] [!] \fIfunc\fR ,...]
17 [\fB-o\fR \fIoutfile\fR] \fIcommand\fR | \fB-p\fR \fIpid\fR[\fI/lwps\fR]...
18 .fi
19
20 .SH DESCRIPTION
21 .LP
22 The \fBtruss\fR utility executes the specified command and produces a trace of
23 the system calls it performs, the signals it receives, and the machine faults
24 it incurs. Each line of the trace output reports either the fault or signal
25 name or the system call name with its arguments and return value(s). System
26 call arguments are displayed symbolically when possible using defines from
27 relevant system headers. For any path name pointer argument, the pointed-to
28 string is displayed. Error returns are reported using the error code names
29 described in \fBIntro\fR(3). If, in the case of an error, the kernel reports a
30 missing privilege, a privilege name as described in \fBprivileges\fR(5) is
31 reported in square brackets (\fB[ ]\fR) after the error code name.
32 .sp
33 .LP
34 Optionally (see the \fB-u\fR option), \fBtruss\fR also produce an entry/exit
35 trace of user-level function calls executed by the traced process, indented to
36 indicate nesting.
37 .SH OPTIONS
38 .LP
39 For those options that take a list argument, the name \fBall\fR can be used as
40 a shorthand to specify all possible members of the list. If the list begins
41 with a \fB!\fR, the meaning of the option is negated (for example, exclude
42 rather than trace). Multiple occurrences of the same option can be specified.
43 For the same name in a list, subsequent options (those to the right) override
44 previous ones (those to the left).
45 .sp
46 .LP
47 The following options are supported:
48 .sp
49 .ne 2
50 .na
51 \fB\fB-a\fR\fR
52 .ad
53 .sp .6
54 .RS 4n
55 Shows the argument strings that are passed in each \fBexec()\fR system call.
56 .RE
57
465 file \fBtruss.out\fR:
466
467 .sp
468 .in +2
469 .nf
470 example$ \fBtruss -f -o truss.out spell \fIdocument\fR\fR
471 .fi
472 .in -2
473 .sp
474
475 .sp
476 .LP
477 \fBspell\fR is a shell script, so the \fB-f\fR flag is needed to trace not only
478 the shell but also the processes created by the shell. (The spell script runs a
479 pipeline of eight processes.)
480
481 .LP
482 \fBExample 4 \fRAbbreviating Output
483 .sp
484 .LP
485 The following example abbreviates output:
486
487 .sp
488 .in +2
489 .nf
490 example$ \fBtruss nroff -mm \fIdocument\fR >nroff.out\fR
491 .fi
492 .in -2
493 .sp
494
495 .sp
496 .LP
497 because 97% of the output reports \fBlseek()\fR, \fBread()\fR, and
498 \fBwrite()\fR system calls. To abbreviate it:
499
500 .sp
501 .in +2
502 .nf
503 example$ \fBtruss -t !lseek,read,write nroff -mm \fIdocument\fR >nroff.out\fR
504 .fi
505 .in -2
583 .LP
584 \fBExample 10 \fRTracing a System Call Verbosely
585 .sp
586 .LP
587 The following example verbosely traces the system call activity of process #1,
588 \fBinit\fR(1M) (if you are a privileged user):
589
590 .sp
591 .in +2
592 .nf
593 example# \fBtruss -p -v all 1\fR
594 .fi
595 .in -2
596 .sp
597
598 .sp
599 .LP
600 Interrupting \fBtruss\fR returns \fBinit\fR to normal operation.
601
602 .SH FILES
603 .ne 2
604 .na
605 \fB\fB/proc/*\fR\fR
606 .ad
607 .RS 11n
608 Process files
609 .RE
610
611 .SH SEE ALSO
612 .LP
613 \fBdate\fR(1), \fBfind\fR(1), \fBproc\fR(1), \fBps\fR(1), \fBsh\fR(1),
614 \fBspell\fR(1), \fBinit\fR(1M), \fBIntro\fR(3), \fBexec\fR(2), \fBfork\fR(2),
615 \fBlseek\fR(2), \fBopen\fR(2), \fBread\fR(2), \fBtime\fR(2), \fBvfork\fR(2),
616 \fBwrite\fR(2), \fBctime\fR(3C), \fBsignal.h\fR(3HEAD), \fBproc\fR(4),
617 \fBattributes\fR(5), \fBprivileges\fR(5), \fBthreads\fR(5)
618 .sp
619 .LP
620 \fIman pages section 2: System Calls\fR
621 .SH NOTES
622 .LP
623 Some of the system calls described in \fIman pages section 2: System Calls\fR
624 differ from the actual operating system interfaces. Do not be surprised by
625 minor deviations of the trace output from the descriptions in that document.
626 .sp
627 .LP
628 Every machine fault (except a page fault) results in the posting of a signal to
629 the \fBLWP\fR that incurred the fault. A report of a received signal
630 immediately follows each report of a machine fault (except a page fault) unless
631 that signal is being blocked.
632 .sp
633 .LP
634 The operating system enforces certain security restrictions on the tracing of
635 processes. In particular, any command whose object file (\fBa.out\fR) cannot be
636 read by a user cannot be traced by that user; set-uid and set-gid commands can
637 be traced only by a privileged user. Unless it is run by a privileged user,
638 \fBtruss\fR loses control of any process that performs an \fBexec()\fR of a
639 set-id or unreadable object file; such processes continue normally, though
640 independently of \fBtruss\fR, from the point of the \fBexec()\fR.
641 .sp
|