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 "99/06/11"
42 strace \- trace system calls and signals
96 .IX "strace command" "" "\fLstrace\fR command"
103 It intercepts and records the system calls which are called
104 by a process and the signals which are received by a process.
105 The name of each system call, its arguments and its return value
106 are printed on standard error or to the file specified with the
111 is a useful diagnostic, instructional, and debugging tool.
112 System adminstrators, diagnosticians and trouble-shooters will find
113 it invaluable for solving problems with
114 programs for which the source is not readily available since
115 they do not need to be recompiled in order to trace them.
116 Students, hackers and the overly-curious will find that
117 a great deal can be learned about a system and its system calls by
118 tracing even ordinary programs. And programmers will find that
119 since system calls and signals are events that happen at the user/kernel
120 interface, a close examination of this boundary is very
121 useful for bug isolation, sanity checking and
122 attempting to capture race conditions.
124 Each line in the trace contains the system call name, followed
125 by its arguments in parentheses and its return value.
126 An example from stracing the command ``cat /dev/null'' is:
128 open("/dev/null", O_RDONLY) = 3
130 Errors (typically a return value of \-1) have the errno symbol
131 and error string appended.
133 open("/foo/bar", O_RDONLY) = -1 ENOENT (No such file or directory)
135 Signals are printed as a signal symbol and a signal string.
136 An excerpt from stracing and interrupting the command ``sleep 666'' is:
138 sigsuspend([] <unfinished ...>
139 --- SIGINT (Interrupt) ---
140 +++ killed by SIGINT +++
142 Arguments are printed in symbolic form with a passion.
143 This example shows the shell peforming ``>>xyzzy'' output redirection:
145 open("xyzzy", O_WRONLY|O_APPEND|O_CREAT, 0666) = 3
147 Here the three argument form of open is decoded by breaking down the
148 flag argument into its three bitwise-OR constituents and printing the
149 mode value in octal by tradition. Where traditional or native
150 usage differs from ANSI or POSIX, the latter forms are preferred.
153 output has proven to be more readable than the source.
155 Structure pointers are dereferenced and the members are displayed
156 as appropriate. In all cases arguments are formatted in the most C-like
158 For example, the essence of the command ``ls \-l /dev/null'' is captured as:
160 lstat("/dev/null", {st_mode=S_IFCHR|0666, st_rdev=makedev(1, 3), ...}) = 0
162 Notice how the `struct stat' argument is dereferenced and how each member is
163 displayed symbolically. In particular, observe how the st_mode member
164 is carefully decoded into a bitwise-OR of symbolic and numeric values.
165 Also notice in this example that the first argument to lstat is an input
166 to the system call and the second argument is an output. Since output
167 arguments are not modified if the system call fails, arguments may not
168 always be dereferenced. For example, retrying the ``ls \-l'' example
169 with a non-existent file produces the following line:
171 lstat("/foo/bar", 0xb004) = -1 ENOENT (No such file or directory)
173 In this case the porch light is on but nobody is home.
175 Character pointers are dereferenced and printed as C strings.
176 Non-printing characters in strings are normally represented by
177 ordinary C escape codes.
180 (32 by default) bytes of strings are printed;
181 longer strings have an ellipsis appended following the closing quote.
182 Here is a line from ``ls \-l'' where the
184 library routine is reading the password file:
186 read(3, "root::0:0:System Administrator:/"..., 1024) = 422
188 While structures are annotated using curly braces, simple pointers
189 and arrays are printed using square brackets with commas separating
190 elements. Here is an example from the command ``id'' on a system with
191 supplementary group ids:
193 getgroups(32, [100, 0]) = 2
195 On the other hand, bit-sets are also shown using square brackets
196 but set elements are separated only by a space. Here is the shell
197 preparing to execute an external command:
199 sigprocmask(SIG_BLOCK, [CHLD TTOU], []) = 0
201 Here the second argument is a bit-set of two signals, SIGCHLD and SIGTTOU.
202 In some cases the bit-set is so full that printing out the unset
203 elements is more valuable. In that case, the bit-set is prefixed by
206 sigprocmask(SIG_UNBLOCK, ~[], NULL) = 0
208 Here the second argument represents the full set of all signals.
213 Count time, calls, and errors for each system call and report a
214 summary on program exit.
217 Show some debugging output of
219 itself on the standard error.
222 Trace child processes as they are created by currently traced
223 processes as a result of the
225 system call. The new process is
226 attached to as soon as its pid is known (through the return value of
228 in the parent process). This means that such children may run
229 uncontrolled for a while (especially in the case of a
231 until the parent is scheduled again to complete its
234 If the parent process decides to
236 for a child that is currently
237 being traced, it is suspended until an appropriate child process either
238 terminates or incurs a signal that would cause it to terminate (as
239 determined from the child's current signal disposition).
245 option is in effect, each processes trace is written to
247 where pid is the numeric process id of each process.
252 (On SunOS 4.x, this is accomplished with
253 some dynamic linking trickery. On Linux, it requires some kernel
254 functionality not yet in the standard kernel.) Otherwise,
257 not be followed even if
262 Print the help summary.
265 Print the instruction pointer at the time of the system call.
268 Suppress messages about attaching, detaching etc. This happens
269 automatically when output is redirected to a file and the command
270 is run directly instead of attaching.
273 Print a relative timestamp upon entry to each system call. This
274 records the time difference between the beginning of successive
278 Prefix each line of the trace with the time of day.
281 If given twice, the time printed will include the microseconds.
284 If given thrice, the time printed will include the microseconds
285 and the leading portion will be printed as the number
286 of seconds since the epoch.
289 Show the time spent in system calls. This records the time
290 difference between the beginning and the end of each system call.
293 Print unabbreviated versions of environment, stat, termios, etc.
294 calls. These structures are very common in calls and so the default
295 behavior displays a reasonable subset of structure members. Use
296 this option to get all of the gory details.
299 Print the version number of
303 Print all non-ASCII strings in hexadecimal string format.
306 Print all strings in hexadecimal string format.
309 Align return values in a specific column (default column 40).
312 A qualifying expression which modifies which events to trace
313 or how to trace them. The format of the expression is:
316 [\fIqualifier\fB=\fR][\fB!\fR]\fIvalue1\fR[\fB,\fIvalue2\fR]...
332 is a qualifier-dependent symbol or number. The default
335 Using an exclamation mark negates the set of values. For example,
339 which in turn means trace only the
341 system call. By contrast,
343 means to trace every system call except
345 In addition, the special values
349 have the obvious meanings.
351 Note that some shells use the exclamation point for history
352 expansion even inside quoted arguments. If so, you must escape
353 the exclamation point with a backslash.
356 Trace only the specified set of system calls. The
358 option is useful for determining which system calls might be useful
359 to trace. For example,
360 .B trace=open,close,read,write
362 trace those four system calls. Be careful when making inferences
363 about the user/kernel boundary if only a subset of system calls
364 are being monitored. The default is
368 Trace all system calls which take a file name as an argument. You
369 can think of this as an abbreviation for
370 .BR "\-e\ trace=open,stat,chmod,unlink," ...
371 which is useful to seeing what files the process is referencing.
372 Furthermore, using the abbreviation will ensure that you don't
373 accidentally forget to include a call like
375 in the list. Betchya woulda forgot that one.
377 .B "\-e trace=process"
378 Trace all system calls which involve process management. This
379 is useful for watching the fork, wait, and exec steps of a process.
381 .B "\-e trace=network"
382 Trace all the network related system calls.
384 .B "\-e trace=signal"
385 Trace all signal related system calls.
388 Trace all IPC related system calls.
390 .BI "\-e abbrev=" set
391 Abbreviate the output from printing each member of large structures.
396 option has the effect of
399 .BI "\-e verbose=" set
400 Dereference structures for the specified set of system calls. The
405 Print raw, undecoded arguments for the specifed set of system calls.
406 This option has the effect of causing all arguments to be printed
407 in hexadecimal. This is mostly useful if you don't trust the
408 decoding or you need to know the actual numeric value of an
411 .BI "\-e signal=" set
412 Trace only the specified subset of signals. The default is
418 causes SIGIO signals not to be traced.
421 Perform a full hexadecimal and ASCII dump of all the data read from
422 file descriptors listed in the specified set. For example, to see
423 all input activity on file descriptors 3 and 5 use
425 Note that this is independent from the normal tracing of the
427 system call which is controlled by the option
428 .BR "\-e trace=read" .
431 Perform a full hexadecimal and ASCII dump of all the data written to
432 file descriptors listed in the specified set. For example, to see
433 all output activity on file descriptors 3 and 5 use
434 .BR "\-e write=3,5" .
435 Note that this is independent from the normal tracing of the
437 system call which is controlled by the option
438 .BR "\-e trace=write" .
441 Write the trace output to the file
443 rather than to stderr.
449 If the argument begins with `|' or with `!' then the rest of the
450 argument is treated as a command and all output is piped to it.
451 This is convenient for piping the debugging output to a program
452 without affecting the redirections of executed programs.
455 Set the overhead for tracing system calls to
458 This is useful for overriding the default heuristic for guessing
459 how much time is spent in mere measuring when timing system calls using
462 option. The acuracy of the heuristic can be gauged by timing a given
463 program run without tracing (using
465 and comparing the accumulated
466 system call time to the total produced using
470 Attach to the process with the process
474 The trace may be terminated
475 at any time by a keyboard interrupt signal (\c
478 will respond by detaching itself from the traced process(es)
479 leaving it (them) to continue running.
482 options can be used to attach to up to 32 processes in addition to
484 (which is optional if at least one
489 Specify the maximum string size to print (the default is 32). Note
490 that filenames are not considered strings and are always printed in
494 Sort the output of the histogram printed by the
496 option by the specified critereon. Legal values are
506 Run command with the user \s-1ID\s0, group \s-2ID\s0, and
507 supplementary groups of
509 This option is only useful when running as root and enables the
510 correct execution of setuid and/or setgid binaries.
511 Unless this option is used setuid and setgid programs are executed
512 without effective privileges.
513 .SH "SETUID INSTALLATION"
516 is installed setuid to root then the invoking user will be able to
517 attach to and trace processes owned by any user.
518 In addition setuid and setgid programs will be executed and traced
519 with the correct effective privileges.
520 Since only users trusted with full root privileges should be allowed
522 it only makes sense to install
524 as setuid to root when the users who can execute it are restricted
525 to those users who have this trust.
526 For example, it makes sense to install a special version of
528 with mode `rwsr-xr--', user
534 group are trusted users.
535 If you do use this feature, please remember to install
536 a non-setuid version of
538 for ordinary lusers to use.
546 It is a pity that so much tracing clutter is produced by systems
547 employing shared libraries.
549 It is instructive to think about system call inputs and outputs
550 as data-flow across the user/kernel boundary. Because user-space
551 and kernel-space are separate and address-protected, it is
552 sometimes possible to make deductive inferences about process
553 behavior using inputs and outputs as propositions.
555 In some cases, a system call will differ from the documented behavior
556 or have a different name. For example, on System V-derived systems
559 system call does not take an argument and the
563 and takes an extra leading argument. These
564 discrepancies are normal but idiosyncratic characteristics of the
565 system call interface and are accounted for by C library wrapper
568 On some platforms a process that has a system call trace applied
571 option will receive a
573 This signal may interrupt a system call that is not restartable.
574 This may have an unpredictable effect on the process
575 if the process takes no action to restart the system call.
577 Programs that use the
582 privileges while being traced.
584 A traced process ignores
586 except on SVR4 platforms.
588 A traced process which tries to block SIGTRAP will be sent a SIGSTOP
589 in an attempt to force continuation of tracing.
591 A traced process runs slowly.
593 Traced processes which are descended from
595 may be left running after an interrupt signal (\c
598 On Linux, exciting as it would be, tracing the init process is forbidden.
602 option is weakly supported.
607 was written by Paul Kranenburg
608 for SunOS and was inspired by its trace utility.
611 was ported to Linux and enhanced
612 by Branko Lankester, who also wrote the Linux kernel support.
613 Even though Paul released
616 Branko's work was based on Paul's
618 1.5 release from 1991.
619 In 1993, Rick Sladkey merged
621 2.5 for SunOS and the second release of
623 for Linux, added many of the features of
625 from SVR4, and produced an
627 that worked on both platforms. In 1994 Rick ported
629 to SVR4 and Solaris and wrote the
630 automatic configuration support. In 1995 he ported
633 and tired of writing about himself in the third person.
637 should be reported via the Debian Bug Tracking System,
640 mailing list at <strace-devel@lists.sourceforge.net>.