Penguin
Annotated edit history of strace(1) version 1, including all changes. View license author blame.
Rev Author # Line
1 perry 1 STRACE
2 !!!STRACE
3 NAME
4 SYNOPSIS
5 DESCRIPTION
6 OPTIONS
7 SETUID INSTALLATION
8 SEE ALSO
9 NOTES
10 BUGS
11 HISTORY
12 PROBLEMS
13 ----
14 !!NAME
15
16
17 strace - trace system calls and signals
18 !!SYNOPSIS
19
20
21 __strace__ [[ __-dffhiqrtttTvxx__ ] [[
22 __-a__''column'' ] [[ __-e__''expr'' ] ... [[
23 __-o__''file'' ] [[ __-p__''pid'' ] ... [[
24 __-s__''strsize'' ] [[ __-u__''username'' ] [[
25 ''command'' [[ ''arg'' ... ] ]
26
27
28 __strace -c__ [[ __-e__''expr'' ] ... [[
29 __-O__''overhead'' ] [[ __-S__''sortby'' ] [[
30 ''command'' [[ ''arg'' ... ] ]
31 !!DESCRIPTION
32
33
34 In the simplest case __strace__ runs the specified
35 ''command'' until it exits. It intercepts and records the
36 system calls which are called by a process and the signals
37 which are received by a process. The name of each system
38 call, its arguments and its return value are printed on
39 standard error or to the file specified with the __-o__
40 option.
41
42
43 __strace__ is a useful diagnostic, instructional, and
44 debugging tool. System adminstrators, diagnosticians and
45 trouble-shooters will find it invaluable for solving
46 problems with programs for which the source is not readily
47 available since they do not need to be recompiled in order
48 to trace them. Students, hackers and the overly-curious will
49 find that a great deal can be learned about a system and its
50 system calls by tracing even ordinary programs. And
51 programmers will find that since system calls and signals
52 are events that happen at the user/kernel interface, a close
53 examination of this boundary is very useful for bug
54 isolation, sanity checking and attempting to capture race
55 conditions.
56
57
58 Each line in the trace contains the system call name,
59 followed by its arguments in parentheses and its return
60 value. An example from stracing the command ``cat
61 /dev/null'' is:
62
63
64 open(
65 Errors (typically a return value of -1) have the errno symbol and error string appended.
66
67
68 open(
69 Signals are printed as a signal symbol and a signal string. An excerpt from stracing and interrupting the command ``sleep 666'' is:
70
71
72 sigsuspend([[]
73 Arguments are printed in symbolic form with a passion. This example shows the shell peforming ``
74
75
76 open(
77 Here the three argument form of open is decoded by breaking down the flag argument into its three bitwise-OR constituents and printing the mode value in octal by tradition. Where traditional or native usage differs from ANSI or POSIX, the latter forms are preferred. In some cases, __strace__ output has proven to be more readable than the source.
78
79
80 Structure pointers are dereferenced and the members are
81 displayed as appropriate. In all cases arguments are
82 formatted in the most C-like fashion possible. For example,
83 the essence of the command ``ls -l /dev/null'' is captured
84 as:
85
86
87 lstat(
88 Notice how the `struct stat' argument is dereferenced and how each member is displayed symbolically. In particular, observe how the st_mode member is carefully decoded into a bitwise-OR of symbolic and numeric values. Also notice in this example that the first argument to lstat is an input to the system call and the second argument is an output. Since output arguments are not modified if the system call fails, arguments may not always be dereferenced. For example, retrying the ``ls -l'' example with a non-existent file produces the following line:
89
90
91 lstat(
92 In this case the porch light is on but nobody is home.
93
94
95 Character pointers are dereferenced and printed as C
96 strings. Non-printing characters in strings are normally
97 represented by ordinary C escape codes. Only the first
98 ''strsize'' (32 by default) bytes of strings are printed;
99 longer strings have an ellipsis appended following the
100 closing quote. Here is a line from ``ls -l'' where the
101 __getpwuid__ library routine is reading the password
102 file:
103
104
105 read(3,
106 While structures are annotated using curly braces, simple pointers and arrays are printed using square brackets with commas separating elements. Here is an example from the command ``id'' on a system with supplementary group ids:
107
108
109 getgroups(32, [[100, 0]) = 2
110 On the other hand, bit-sets are also shown using square brackets but set elements are separated only by a space. Here is the shell preparing to execute an external command:
111
112
113 sigprocmask(SIG_BLOCK, [[CHLD TTOU], [[]) = 0
114 Here the second argument is a bit-set of two signals, SIGCHLD and SIGTTOU. In some cases the bit-set is so full that printing out the unset elements is more valuable. In that case, the bit-set is prefixed by a tilde like this:
115
116
117 sigprocmask(SIG_UNBLOCK, ~[[], NULL) = 0
118 Here the second argument represents the full set of all signals.
119 !!OPTIONS
120
121
122 __-c__ Count time, calls, and errors for each system call
123 and report a summary on program exit.
124
125
126 __-d__ Show some debugging output of __strace__ itself
127 on the standard error.
128
129
130 __-f__ Trace child processes as they are created by
131 currently traced processes as a result of the fork(2)
132 system call. The new process is attached to as soon as its
133 pid is known (through the return value of fork(2) in
134 the parent process). This means that such children may run
135 uncontrolled for a while (especially in the case of a
136 vfork(2)), until the parent is scheduled again to
137 complete its (__v__)fork(2) call. If the parent
138 process decides to wait(2) for a child that is
139 currently being traced, it is suspended until an appropriate
140 child process either terminates or incurs a signal that
141 would cause it to terminate (as determined from the child's
142 current signal disposition).
143
144
145 __-ff__ If the __-o__ ''filename'' option is in
146 effect, each processes trace is written to
147 ''filename.pid'' where pid is the numeric process id of
148 each process.
149
150
151 __-F__ Attempt to follow __vfork__s. (On SunOS 4.x,
152 this is accomplished with some dynamic linking trickery. On
153 Linux, it requires some kernel functionality not yet in the
154 standard kernel.) Otherwise, __vfork__s will not be
155 followed even if __-f__ has been given.
156
157
158 __-h__ Print the help summary.
159
160
161 __-i__ Print the instruction pointer at the time of the
162 system call.
163
164
165 __-q__ Suppress messages about attaching, detaching etc.
166 This happens automatically when output is redirected to a
167 file and the command is run directly instead of
168 attaching.
169
170
171 __-r__ Print a relative timestamp upon entry to each
172 system call. This records the time difference between the
173 beginning of successive system calls.
174
175
176 __-t__ Prefix each line of the trace with the time of
177 day.
178
179
180 __-tt__ If given twice, the time printed will include the
181 microseconds.
182
183
184 __-ttt__ If given thrice, the time printed will include
185 the microseconds and the leading portion will be printed as
186 the number of seconds since the epoch.
187
188
189 __-T__ Show the time spent in system calls. This records
190 the time difference between the beginning and the end of
191 each system call.
192
193
194 __-v__ Print unabbreviated versions of environment, stat,
195 termios, etc. calls. These structures are very common in
196 calls and so the default behavior displays a reasonable
197 subset of structure members. Use this option to get all of
198 the gory details.
199
200
201 __-V__ Print the version number of
202 __strace__.
203
204
205 __-x__ Print all non-ASCII strings in hexadecimal string
206 format.
207
208
209 __-xx__ Print all strings in hexadecimal string
210 format.
211
212
213 __-a__ ''column''
214
215
216 Align return values in a specific column (default column
217 40).
218
219
220 __-e__ ''expr''
221
222
223 A qualifying expression which modifies which events to trace
224 or how to trace them. The format of the expression
225 is:
226
227
228 [[''qualifier''__=__][[__!__]''value1''[[__,__''value2'']...
229
230
231 where ''qualifier'' is one of __trace__,
232 __abbrev__, __verbose__, __raw__, __signal__,
233 __read__, or __write__ and ''value'' is a
234 qualifier-dependent symbol or number. The default qualifier
235 is __trace__. Using an exclamation mark negates the set
236 of values. For example, __-eopen__ means literally __-e
237 trace=open__ which in turn means trace only the
238 __open__ system call. By contrast, __-etrace=!open__
239 means to trace every system call except __open__. In
240 addition, the special values __all__ and __none__ have
241 the obvious meanings.
242
243
244 Note that some shells use the exclamation point for history
245 expansion even inside quoted arguments. If so, you must
246 escape the exclamation point with a backslash.
247
248
249 __-e trace=__''set''
250
251
252 Trace only the specified set of system calls. The __-c__
253 option is useful for determining which system calls might be
254 useful to trace. For example,
255 __trace=open,close,read,write__ means to only trace those
256 four system calls. Be careful when making inferences about
257 the user/kernel boundary if only a subset of system calls
258 are being monitored. The default is
259 __trace=all__.
260
261
262 __-e trace=file__
263
264
265 Trace all system calls which take a file name as an
266 argument. You can think of this as an abbreviation for __-e
267 trace=open,stat,chmod,unlink,__... which is useful to
268 seeing what files the process is referencing. Furthermore,
269 using the abbreviation will ensure that you don't
270 accidentally forget to include a call like __lstat__ in
271 the list. Betchya woulda forgot that one.
272
273
274 __-e trace=process__
275
276
277 Trace all system calls which involve process management.
278 This is useful for watching the fork, wait, and exec steps
279 of a process.
280
281
282 __-e trace=network__
283
284
285 Trace all the network related system calls.
286
287
288 __-e trace=signal__
289
290
291 Trace all signal related system calls.
292
293
294 __-e trace=ipc__
295
296
297 Trace all IPC related system calls.
298
299
300 __-e abbrev=__''set''
301
302
303 Abbreviate the output from printing each member of large
304 structures. The default is __abbrev=all__. The __-v__
305 option has the effect of __abbrev=none__.
306
307
308 __-e verbose=__''set''
309
310
311 Dereference structures for the specified set of system
312 calls. The default is __verbose=all__.
313
314
315 __-e raw=__''set''
316
317
318 Print raw, undecoded arguments for the specifed set of
319 system calls. This option has the effect of causing all
320 arguments to be printed in hexadecimal. This is mostly
321 useful if you don't trust the decoding or you need to know
322 the actual numeric value of an argument.
323
324
325 __-e signal=__''set''
326
327
328 Trace only the specified subset of signals. The default is
329 __signal=all__. For example, __signal=!SIGIO__ (or
330 __signal=!io__) causes SIGIO signals not to be
331 traced.
332
333
334 __-e read=__''set''
335
336
337 Perform a full hexadecimal and ASCII dump of all the data
338 read from file descriptors listed in the specified set. For
339 example, to see all input activity on file descriptors 3 and
340 5 use __-e read=3,5__. Note that this is independent from
341 the normal tracing of the read(2) system call which
342 is controlled by the option __-e
343 trace=read__.
344
345
346 __-e write=__''set''
347
348
349 Perform a full hexadecimal and ASCII dump of all the data
350 written to file descriptors listed in the specified set. For
351 example, to see all output activity on file descriptors 3
352 and 5 use __-e write=3,5__. Note that this is independent
353 from the normal tracing of the write(2) system call
354 which is controlled by the option __-e
355 trace=write__.
356
357
358 __-o__ ''filename''
359
360
361 Write the trace output to the file ''filename'' rather
362 than to stderr. Use ''filename.pid'' if __-ff__ is
363 used. If the argument begins with `|' or with `!' then the
364 rest of the argument is treated as a command and all output
365 is piped to it. This is convenient for piping the debugging
366 output to a program without affecting the redirections of
367 executed programs.
368
369
370 __-O__ ''overhead''
371
372
373 Set the overhead for tracing system calls to ''overhead''
374 microseconds. This is useful for overriding the default
375 heuristic for guessing how much time is spent in mere
376 measuring when timing system calls using the __-c__
377 option. The acuracy of the heuristic can be gauged by timing
378 a given program run without tracing (using time(1))
379 and comparing the accumulated system call time to the total
380 produced using __-c__.
381
382
383 __-p__ ''pid''
384
385
386 Attach to the process with the process ID
387 ''pid'' and begin tracing. The trace may be terminated at
388 any time by a keyboard interrupt signal (
389 CTRL -C). __strace__ will respond by
390 detaching itself from the traced process(es) leaving it
391 (them) to continue running. Multiple __-p__ options can
392 be used to attach to up to 32 processes in addition to
393 ''command'' (which is optional if at least one __-p__
394 option is given).
395
396
397 __-s__ ''strsize''
398
399
400 Specify the maximum string size to print (the default is
401 32). Note that filenames are not considered strings and are
402 always printed in full.
403
404
405 __-S__ ''sortby''
406
407
408 Sort the output of the histogram printed by the __-c__
409 option by the specified critereon. Legal values are
410 __time__, __calls__, __name__, and __nothing__
411 (default __time__).
412
413
414 __-u__ ''username''
415
416
417 Run command with the user ID , group
418 ID , and supplementary groups of
419 ''username''. This option is only useful when running as
420 root and enables the correct execution of setuid and/or
421 setgid binaries. Unless this option is used setuid and
422 setgid programs are executed without effective
423 privileges.
424 !!SETUID INSTALLATION
425
426
427 If __strace__ is installed setuid to root then the
428 invoking user will be able to attach to and trace processes
429 owned by any user. In addition setuid and setgid programs
430 will be executed and traced with the correct effective
431 privileges. Since only users trusted with full root
432 privileges should be allowed to do these things, it only
433 makes sense to install __strace__ as setuid to root when
434 the users who can execute it are restricted to those users
435 who have this trust. For example, it makes sense to install
436 a special version of __strace__ with mode `rwsr-xr--',
437 user __root__ and group __trace__, where members of
438 the __trace__ group are trusted users. If you do use this
439 feature, please remember to install a non-setuid version of
440 __strace__ for ordinary lusers to use.
441 !!SEE ALSO
442
443
444 ptrace(2), proc(4), time(1),
445 trace(1), truss(1)
446 !!NOTES
447
448
449 It is a pity that so much tracing clutter is produced by
450 systems employing shared libraries.
451
452
453 It is instructive to think about system call inputs and
454 outputs as data-flow across the user/kernel boundary.
455 Because user-space and kernel-space are separate and
456 address-protected, it is sometimes possible to make
457 deductive inferences about process behavior using inputs and
458 outputs as propositions.
459
460
461 In some cases, a system call will differ from the documented
462 behavior or have a different name. For example, on System
463 V-derived systems the true time(2) system call does
464 not take an argument and the __stat__ function is called
465 __xstat__ and takes an extra leading argument. These
466 discrepancies are normal but idiosyncratic characteristics
467 of the system call interface and are accounted for by C
468 library wrapper functions.
469
470
471 On some platforms a process that has a system call trace
472 applied to it with the __-p__ option will receive a
473 __SIGSTOP__ . This signal may interrupt a
474 system call that is not restartable. This may have an
475 unpredictable effect on the process if the process takes no
476 action to restart the system call.
477 !!BUGS
478
479
480 Programs that use the ''setuid'' bit do not have
481 effective user ID privileges while being
482 traced.
483
484
485 A traced process ignores SIGSTOP except on
486 SVR4 platforms.
487
488
489 A traced process which tries to block SIGTRAP will be sent a
490 SIGSTOP in an attempt to force continuation of
491 tracing.
492
493
494 A traced process runs slowly.
495
496
497 Traced processes which are descended from ''command'' may
498 be left running after an interrupt signal (
499 CTRL -C).
500
501
502 On Linux, exciting as it would be, tracing the init process
503 is forbidden.
504
505
506 The __-i__ option is weakly supported.
507 !!HISTORY
508
509
510 __strace__ The original __strace__ was written by Paul
511 Kranenburg for SunOS and was inspired by its trace utility.
512 The SunOS version of __strace__ was ported to Linux and
513 enhanced by Branko Lankester, who also wrote the Linux
514 kernel support. Even though Paul released __strace__ 2.5
515 in 1992, Branko's work was based on Paul's __strace__ 1.5
516 release from 1991. In 1993, Rick Sladkey merged
517 __strace__ 2.5 for SunOS and the second release of
518 __strace__ for Linux, added many of the features of
519 truss(1) from SVR4, and produced an __strace__
520 that worked on both platforms. In 1994 Rick ported
521 __strace__ to SVR4 and Solaris and wrote the automatic
522 configuration support. In 1995 he ported __strace__ to
523 Irix and tired of writing about himself in the third
524 person.
525 !!PROBLEMS
526
527
528 Problems with __strace__ should be reported to the
529 current __strace__ maintainer, Wichert Akkerman, at
530 __
531 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.