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 administrators, 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 performing ``>>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 summary on
222 program exit. On Linux, this attempts to show system time (CPU time spent
223 running in the kernel) independent of wall clock time.
226 Show some debugging output of
228 itself on the standard error.
231 Trace child processes as they are created by currently traced
232 processes as a result of the
234 system call. The new process is
235 attached to as soon as its pid is known (through the return value of
237 in the parent process). This means that such children may run
238 uncontrolled for a while (especially in the case of a
240 until the parent is scheduled again to complete its
243 If the parent process decides to
245 for a child that is currently
246 being traced, it is suspended until an appropriate child process either
247 terminates or incurs a signal that would cause it to terminate (as
248 determined from the child's current signal disposition).
254 option is in effect, each processes trace is written to
256 where pid is the numeric process id of each process.
261 (On SunOS 4.x, this is accomplished with
262 some dynamic linking trickery.)
266 not be followed even if
271 Print the help summary.
274 Print the instruction pointer at the time of the system call.
277 Suppress messages about attaching, detaching etc. This happens
278 automatically when output is redirected to a file and the command
279 is run directly instead of attaching.
282 Print a relative timestamp upon entry to each system call. This
283 records the time difference between the beginning of successive
287 Prefix each line of the trace with the time of day.
290 If given twice, the time printed will include the microseconds.
293 If given thrice, the time printed will include the microseconds
294 and the leading portion will be printed as the number
295 of seconds since the epoch.
298 Show the time spent in system calls. This records the time
299 difference between the beginning and the end of each system call.
302 Print unabbreviated versions of environment, stat, termios, etc.
303 calls. These structures are very common in calls and so the default
304 behavior displays a reasonable subset of structure members. Use
305 this option to get all of the gory details.
308 Print the version number of
312 Print all non-ASCII strings in hexadecimal string format.
315 Print all strings in hexadecimal string format.
318 Align return values in a specific column (default column 40).
321 A qualifying expression which modifies which events to trace
322 or how to trace them. The format of the expression is:
325 [\fIqualifier\fB=\fR][\fB!\fR]\fIvalue1\fR[\fB,\fIvalue2\fR]...
341 is a qualifier-dependent symbol or number. The default
344 Using an exclamation mark negates the set of values. For example,
348 which in turn means trace only the
350 system call. By contrast,
352 means to trace every system call except
354 In addition, the special values
358 have the obvious meanings.
360 Note that some shells use the exclamation point for history
361 expansion even inside quoted arguments. If so, you must escape
362 the exclamation point with a backslash.
365 Trace only the specified set of system calls. The
367 option is useful for determining which system calls might be useful
368 to trace. For example,
369 .B trace=open,close,read,write
371 trace those four system calls. Be careful when making inferences
372 about the user/kernel boundary if only a subset of system calls
373 are being monitored. The default is
377 Trace all system calls which take a file name as an argument. You
378 can think of this as an abbreviation for
379 .BR "\-e\ trace=open,stat,chmod,unlink," ...
380 which is useful to seeing what files the process is referencing.
381 Furthermore, using the abbreviation will ensure that you don't
382 accidentally forget to include a call like
384 in the list. Betchya woulda forgot that one.
386 .B "\-e trace=process"
387 Trace all system calls which involve process management. This
388 is useful for watching the fork, wait, and exec steps of a process.
390 .B "\-e trace=network"
391 Trace all the network related system calls.
393 .B "\-e trace=signal"
394 Trace all signal related system calls.
397 Trace all IPC related system calls.
400 Trace all file descriptor related system calls.
402 .BI "\-e abbrev=" set
403 Abbreviate the output from printing each member of large structures.
408 option has the effect of
411 .BI "\-e verbose=" set
412 Dereference structures for the specified set of system calls. The
417 Print raw, undecoded arguments for the specified set of system calls.
418 This option has the effect of causing all arguments to be printed
419 in hexadecimal. This is mostly useful if you don't trust the
420 decoding or you need to know the actual numeric value of an
423 .BI "\-e signal=" set
424 Trace only the specified subset of signals. The default is
430 causes SIGIO signals not to be traced.
433 Perform a full hexadecimal and ASCII dump of all the data read from
434 file descriptors listed in the specified set. For example, to see
435 all input activity on file descriptors 3 and 5 use
437 Note that this is independent from the normal tracing of the
439 system call which is controlled by the option
440 .BR "\-e trace=read" .
443 Perform a full hexadecimal and ASCII dump of all the data written to
444 file descriptors listed in the specified set. For example, to see
445 all output activity on file descriptors 3 and 5 use
446 .BR "\-e write=3,5" .
447 Note that this is independent from the normal tracing of the
449 system call which is controlled by the option
450 .BR "\-e trace=write" .
453 Write the trace output to the file
455 rather than to stderr.
461 If the argument begins with `|' or with `!' then the rest of the
462 argument is treated as a command and all output is piped to it.
463 This is convenient for piping the debugging output to a program
464 without affecting the redirections of executed programs.
467 Set the overhead for tracing system calls to
470 This is useful for overriding the default heuristic for guessing
471 how much time is spent in mere measuring when timing system calls using
474 option. The accuracy of the heuristic can be gauged by timing a given
475 program run without tracing (using
477 and comparing the accumulated
478 system call time to the total produced using
482 Attach to the process with the process
486 The trace may be terminated
487 at any time by a keyboard interrupt signal (\c
490 will respond by detaching itself from the traced process(es)
491 leaving it (them) to continue running.
494 options can be used to attach to up to 32 processes in addition to
496 (which is optional if at least one
501 Specify the maximum string size to print (the default is 32). Note
502 that filenames are not considered strings and are always printed in
506 Sort the output of the histogram printed by the
508 option by the specified criterion. Legal values are
518 Run command with the user \s-1ID\s0, group \s-2ID\s0, and
519 supplementary groups of
521 This option is only useful when running as root and enables the
522 correct execution of setuid and/or setgid binaries.
523 Unless this option is used setuid and setgid programs are executed
524 without effective privileges.
529 in its list of environment variables.
534 from the inherited list of environment variables before passing it on to
536 .SH "SETUID INSTALLATION"
539 is installed setuid to root then the invoking user will be able to
540 attach to and trace processes owned by any user.
541 In addition setuid and setgid programs will be executed and traced
542 with the correct effective privileges.
543 Since only users trusted with full root privileges should be allowed
545 it only makes sense to install
547 as setuid to root when the users who can execute it are restricted
548 to those users who have this trust.
549 For example, it makes sense to install a special version of
551 with mode `rwsr-xr--', user
557 group are trusted users.
558 If you do use this feature, please remember to install
559 a non-setuid version of
561 for ordinary lusers to use.
569 It is a pity that so much tracing clutter is produced by systems
570 employing shared libraries.
572 It is instructive to think about system call inputs and outputs
573 as data-flow across the user/kernel boundary. Because user-space
574 and kernel-space are separate and address-protected, it is
575 sometimes possible to make deductive inferences about process
576 behavior using inputs and outputs as propositions.
578 In some cases, a system call will differ from the documented behavior
579 or have a different name. For example, on System V-derived systems
582 system call does not take an argument and the
586 and takes an extra leading argument. These
587 discrepancies are normal but idiosyncratic characteristics of the
588 system call interface and are accounted for by C library wrapper
591 On some platforms a process that has a system call trace applied
594 option will receive a
596 This signal may interrupt a system call that is not restartable.
597 This may have an unpredictable effect on the process
598 if the process takes no action to restart the system call.
600 Programs that use the
605 privileges while being traced.
607 A traced process ignores
609 except on SVR4 platforms.
611 A traced process which tries to block SIGTRAP will be sent a SIGSTOP
612 in an attempt to force continuation of tracing.
614 A traced process runs slowly.
616 Traced processes which are descended from
618 may be left running after an interrupt signal (\c
621 On Linux, exciting as it would be, tracing the init process is forbidden.
625 option is weakly supported.
630 was written by Paul Kranenburg
631 for SunOS and was inspired by its trace utility.
634 was ported to Linux and enhanced
635 by Branko Lankester, who also wrote the Linux kernel support.
636 Even though Paul released
639 Branko's work was based on Paul's
641 1.5 release from 1991.
642 In 1993, Rick Sladkey merged
644 2.5 for SunOS and the second release of
646 for Linux, added many of the features of
648 from SVR4, and produced an
650 that worked on both platforms. In 1994 Rick ported
652 to SVR4 and Solaris and wrote the
653 automatic configuration support. In 1995 he ported
656 and tired of writing about himself in the third person.
660 should be reported via the Debian Bug Tracking System,
663 mailing list at <strace-devel@lists.sourceforge.net>.