1 .\" Copyright (c) 1991, 1992 Paul Kranenburg <pk@cs.few.eur.nl>
2 .\" Copyright (c) 1993 Branko Lankester <branko@hacktic.nl>
3 .\" Copyright (c) 1993, 1994, 1995, 1996 Rick Sladkey <jrs@world.std.com>
4 .\" All rights reserved.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. The name of the author may not be used to endorse or promote products
15 .\" derived from this software without specific prior written permission.
17 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
18 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
19 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
20 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
21 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
22 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
23 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
24 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
26 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
40 .TH STRACE 1 "2003-01-21"
42 strace \- trace system calls and signals
104 .IX "strace command" "" "\fLstrace\fR command"
111 It intercepts and records the system calls which are called
112 by a process and the signals which are received by a process.
113 The name of each system call, its arguments and its return value
114 are printed on standard error or to the file specified with the
119 is a useful diagnostic, instructional, and debugging tool.
120 System adminstrators, diagnosticians and trouble-shooters will find
121 it invaluable for solving problems with
122 programs for which the source is not readily available since
123 they do not need to be recompiled in order to trace them.
124 Students, hackers and the overly-curious will find that
125 a great deal can be learned about a system and its system calls by
126 tracing even ordinary programs. And programmers will find that
127 since system calls and signals are events that happen at the user/kernel
128 interface, a close examination of this boundary is very
129 useful for bug isolation, sanity checking and
130 attempting to capture race conditions.
132 Each line in the trace contains the system call name, followed
133 by its arguments in parentheses and its return value.
134 An example from stracing the command ``cat /dev/null'' is:
136 open("/dev/null", O_RDONLY) = 3
138 Errors (typically a return value of \-1) have the errno symbol
139 and error string appended.
141 open("/foo/bar", O_RDONLY) = -1 ENOENT (No such file or directory)
143 Signals are printed as a signal symbol and a signal string.
144 An excerpt from stracing and interrupting the command ``sleep 666'' is:
146 sigsuspend([] <unfinished ...>
147 --- SIGINT (Interrupt) ---
148 +++ killed by SIGINT +++
150 Arguments are printed in symbolic form with a passion.
151 This example shows the shell peforming ``>>xyzzy'' output redirection:
153 open("xyzzy", O_WRONLY|O_APPEND|O_CREAT, 0666) = 3
155 Here the three argument form of open is decoded by breaking down the
156 flag argument into its three bitwise-OR constituents and printing the
157 mode value in octal by tradition. Where traditional or native
158 usage differs from ANSI or POSIX, the latter forms are preferred.
161 output has proven to be more readable than the source.
163 Structure pointers are dereferenced and the members are displayed
164 as appropriate. In all cases arguments are formatted in the most C-like
166 For example, the essence of the command ``ls \-l /dev/null'' is captured as:
168 lstat("/dev/null", {st_mode=S_IFCHR|0666, st_rdev=makedev(1, 3), ...}) = 0
170 Notice how the `struct stat' argument is dereferenced and how each member is
171 displayed symbolically. In particular, observe how the st_mode member
172 is carefully decoded into a bitwise-OR of symbolic and numeric values.
173 Also notice in this example that the first argument to lstat is an input
174 to the system call and the second argument is an output. Since output
175 arguments are not modified if the system call fails, arguments may not
176 always be dereferenced. For example, retrying the ``ls \-l'' example
177 with a non-existent file produces the following line:
179 lstat("/foo/bar", 0xb004) = -1 ENOENT (No such file or directory)
181 In this case the porch light is on but nobody is home.
183 Character pointers are dereferenced and printed as C strings.
184 Non-printing characters in strings are normally represented by
185 ordinary C escape codes.
188 (32 by default) bytes of strings are printed;
189 longer strings have an ellipsis appended following the closing quote.
190 Here is a line from ``ls \-l'' where the
192 library routine is reading the password file:
194 read(3, "root::0:0:System Administrator:/"..., 1024) = 422
196 While structures are annotated using curly braces, simple pointers
197 and arrays are printed using square brackets with commas separating
198 elements. Here is an example from the command ``id'' on a system with
199 supplementary group ids:
201 getgroups(32, [100, 0]) = 2
203 On the other hand, bit-sets are also shown using square brackets
204 but set elements are separated only by a space. Here is the shell
205 preparing to execute an external command:
207 sigprocmask(SIG_BLOCK, [CHLD TTOU], []) = 0
209 Here the second argument is a bit-set of two signals, SIGCHLD and SIGTTOU.
210 In some cases the bit-set is so full that printing out the unset
211 elements is more valuable. In that case, the bit-set is prefixed by
214 sigprocmask(SIG_UNBLOCK, ~[], NULL) = 0
216 Here the second argument represents the full set of all signals.
221 Count time, calls, and errors for each system call and report a
222 summary on program exit.
225 Show some debugging output of
227 itself on the standard error.
230 Trace child processes as they are created by currently traced
231 processes as a result of the
233 system call. The new process is
234 attached to as soon as its pid is known (through the return value of
236 in the parent process). This means that such children may run
237 uncontrolled for a while (especially in the case of a
239 until the parent is scheduled again to complete its
242 If the parent process decides to
244 for a child that is currently
245 being traced, it is suspended until an appropriate child process either
246 terminates or incurs a signal that would cause it to terminate (as
247 determined from the child's current signal disposition).
253 option is in effect, each processes trace is written to
255 where pid is the numeric process id of each process.
260 (On SunOS 4.x, this is accomplished with
261 some dynamic linking trickery. On Linux, it requires some kernel
262 functionality not yet in the standard kernel.) Otherwise,
265 not be followed even if
270 Print the help summary.
273 Print the instruction pointer at the time of the system call.
276 Suppress messages about attaching, detaching etc. This happens
277 automatically when output is redirected to a file and the command
278 is run directly instead of attaching.
281 Print a relative timestamp upon entry to each system call. This
282 records the time difference between the beginning of successive
286 Prefix each line of the trace with the time of day.
289 If given twice, the time printed will include the microseconds.
292 If given thrice, the time printed will include the microseconds
293 and the leading portion will be printed as the number
294 of seconds since the epoch.
297 Show the time spent in system calls. This records the time
298 difference between the beginning and the end of each system call.
301 Print unabbreviated versions of environment, stat, termios, etc.
302 calls. These structures are very common in calls and so the default
303 behavior displays a reasonable subset of structure members. Use
304 this option to get all of the gory details.
307 Print the version number of
311 Print all non-ASCII strings in hexadecimal string format.
314 Print all strings in hexadecimal string format.
317 Align return values in a specific column (default column 40).
320 A qualifying expression which modifies which events to trace
321 or how to trace them. The format of the expression is:
324 [\fIqualifier\fB=\fR][\fB!\fR]\fIvalue1\fR[\fB,\fIvalue2\fR]...
340 is a qualifier-dependent symbol or number. The default
343 Using an exclamation mark negates the set of values. For example,
347 which in turn means trace only the
349 system call. By contrast,
351 means to trace every system call except
353 In addition, the special values
357 have the obvious meanings.
359 Note that some shells use the exclamation point for history
360 expansion even inside quoted arguments. If so, you must escape
361 the exclamation point with a backslash.
364 Trace only the specified set of system calls. The
366 option is useful for determining which system calls might be useful
367 to trace. For example,
368 .B trace=open,close,read,write
370 trace those four system calls. Be careful when making inferences
371 about the user/kernel boundary if only a subset of system calls
372 are being monitored. The default is
376 Trace all system calls which take a file name as an argument. You
377 can think of this as an abbreviation for
378 .BR "\-e\ trace=open,stat,chmod,unlink," ...
379 which is useful to seeing what files the process is referencing.
380 Furthermore, using the abbreviation will ensure that you don't
381 accidentally forget to include a call like
383 in the list. Betchya woulda forgot that one.
385 .B "\-e trace=process"
386 Trace all system calls which involve process management. This
387 is useful for watching the fork, wait, and exec steps of a process.
389 .B "\-e trace=network"
390 Trace all the network related system calls.
392 .B "\-e trace=signal"
393 Trace all signal related system calls.
396 Trace all IPC related system calls.
398 .BI "\-e abbrev=" set
399 Abbreviate the output from printing each member of large structures.
404 option has the effect of
407 .BI "\-e verbose=" set
408 Dereference structures for the specified set of system calls. The
413 Print raw, undecoded arguments for the specifed set of system calls.
414 This option has the effect of causing all arguments to be printed
415 in hexadecimal. This is mostly useful if you don't trust the
416 decoding or you need to know the actual numeric value of an
419 .BI "\-e signal=" set
420 Trace only the specified subset of signals. The default is
426 causes SIGIO signals not to be traced.
429 Perform a full hexadecimal and ASCII dump of all the data read from
430 file descriptors listed in the specified set. For example, to see
431 all input activity on file descriptors 3 and 5 use
433 Note that this is independent from the normal tracing of the
435 system call which is controlled by the option
436 .BR "\-e trace=read" .
439 Perform a full hexadecimal and ASCII dump of all the data written to
440 file descriptors listed in the specified set. For example, to see
441 all output activity on file descriptors 3 and 5 use
442 .BR "\-e write=3,5" .
443 Note that this is independent from the normal tracing of the
445 system call which is controlled by the option
446 .BR "\-e trace=write" .
449 Write the trace output to the file
451 rather than to stderr.
457 If the argument begins with `|' or with `!' then the rest of the
458 argument is treated as a command and all output is piped to it.
459 This is convenient for piping the debugging output to a program
460 without affecting the redirections of executed programs.
463 Set the overhead for tracing system calls to
466 This is useful for overriding the default heuristic for guessing
467 how much time is spent in mere measuring when timing system calls using
470 option. The acuracy of the heuristic can be gauged by timing a given
471 program run without tracing (using
473 and comparing the accumulated
474 system call time to the total produced using
478 Attach to the process with the process
482 The trace may be terminated
483 at any time by a keyboard interrupt signal (\c
486 will respond by detaching itself from the traced process(es)
487 leaving it (them) to continue running.
490 options can be used to attach to up to 32 processes in addition to
492 (which is optional if at least one
497 Specify the maximum string size to print (the default is 32). Note
498 that filenames are not considered strings and are always printed in
502 Sort the output of the histogram printed by the
504 option by the specified critereon. Legal values are
514 Run command with the user \s-1ID\s0, group \s-2ID\s0, and
515 supplementary groups of
517 This option is only useful when running as root and enables the
518 correct execution of setuid and/or setgid binaries.
519 Unless this option is used setuid and setgid programs are executed
520 without effective privileges.
525 in its list of environment variables.
530 from the inherited list of environment variables before passing it on to
532 .SH "SETUID INSTALLATION"
535 is installed setuid to root then the invoking user will be able to
536 attach to and trace processes owned by any user.
537 In addition setuid and setgid programs will be executed and traced
538 with the correct effective privileges.
539 Since only users trusted with full root privileges should be allowed
541 it only makes sense to install
543 as setuid to root when the users who can execute it are restricted
544 to those users who have this trust.
545 For example, it makes sense to install a special version of
547 with mode `rwsr-xr--', user
553 group are trusted users.
554 If you do use this feature, please remember to install
555 a non-setuid version of
557 for ordinary lusers to use.
565 It is a pity that so much tracing clutter is produced by systems
566 employing shared libraries.
568 It is instructive to think about system call inputs and outputs
569 as data-flow across the user/kernel boundary. Because user-space
570 and kernel-space are separate and address-protected, it is
571 sometimes possible to make deductive inferences about process
572 behavior using inputs and outputs as propositions.
574 In some cases, a system call will differ from the documented behavior
575 or have a different name. For example, on System V-derived systems
578 system call does not take an argument and the
582 and takes an extra leading argument. These
583 discrepancies are normal but idiosyncratic characteristics of the
584 system call interface and are accounted for by C library wrapper
587 On some platforms a process that has a system call trace applied
590 option will receive a
592 This signal may interrupt a system call that is not restartable.
593 This may have an unpredictable effect on the process
594 if the process takes no action to restart the system call.
596 Programs that use the
601 privileges while being traced.
603 A traced process ignores
605 except on SVR4 platforms.
607 A traced process which tries to block SIGTRAP will be sent a SIGSTOP
608 in an attempt to force continuation of tracing.
610 A traced process runs slowly.
612 Traced processes which are descended from
614 may be left running after an interrupt signal (\c
617 On Linux, exciting as it would be, tracing the init process is forbidden.
621 option is weakly supported.
626 was written by Paul Kranenburg
627 for SunOS and was inspired by its trace utility.
630 was ported to Linux and enhanced
631 by Branko Lankester, who also wrote the Linux kernel support.
632 Even though Paul released
635 Branko's work was based on Paul's
637 1.5 release from 1991.
638 In 1993, Rick Sladkey merged
640 2.5 for SunOS and the second release of
642 for Linux, added many of the features of
644 from SVR4, and produced an
646 that worked on both platforms. In 1994 Rick ported
648 to SVR4 and Solaris and wrote the
649 automatic configuration support. In 1995 he ported
652 and tired of writing about himself in the third person.
656 should be reported via the Debian Bug Tracking System,
659 mailing list at <strace-devel@lists.sourceforge.net>.