1STRACE(1) General Commands Manual STRACE(1)
2
6 strace - trace system calls and signals
7
9 strace [-ACdffhikqqrtttTvVwxxyyzZ] [-I n] [-b execve] [-e expr]...
10 [-O overhead] [-S sortby] [-U columns] [-a column] [-o file]
11 [-s strsize] [-X format] [-P path]... [-p pid]...
12 [--seccomp-bpf] { -p pid | [-DDD] [-E var[=val]]...
13 [-u username] command [args] }
14 strace -c [-dfwzZ] [-I n] [-b execve] [-e expr]... [-O overhead]
16 [-S sortby] [-U columns] [-P path]... [-p pid]...
17 [--seccomp-bpf] { -p pid | [-DDD] [-E var[=val]]...
18 [-u username] command [args] }
19
21 In the simplest case strace runs the specified command until it exits.
22 It intercepts and records the system calls which are called by a
23 process and the signals which are received by a process. The name of
24 each system call, its arguments and its return value are printed on
25 standard error or to the file specified with the -o option.
26 strace is a useful diagnostic, instructional, and debugging tool. Sys‐
28 tem administrators, diagnosticians and trouble-shooters will find it
29 invaluable for solving problems with programs for which the source is
30 not readily available since they do not need to be recompiled in order
31 to trace them. Students, hackers and the overly-curious will find that
32 a great deal can be learned about a system and its system calls by
33 tracing even ordinary programs. And programmers will find that since
34 system calls and signals are events that happen at the user/kernel
35 interface, a close examination of this boundary is very useful for bug
36 isolation, sanity checking and attempting to capture race conditions.
37 Each line in the trace contains the system call name, followed by its
39 arguments in parentheses and its return value. An example from strac‐
40 ing the command "cat /dev/null" is:
41 open("/dev/null", O_RDONLY) = 3
43 Errors (typically a return value of -1) have the errno symbol and error
45 string appended.
46 open("/foo/bar", O_RDONLY) = -1 ENOENT (No such file or directory)
48 Signals are printed as signal symbol and decoded siginfo structure. An
50 excerpt from stracing and interrupting the command "sleep 666" is:
51 sigsuspend([] <unfinished ...>
53 --- SIGINT {si_signo=SIGINT, si_code=SI_USER, si_pid=...} ---
54 +++ killed by SIGINT +++
55 If a system call is being executed and meanwhile another one is being
57 called from a different thread/process then strace will try to preserve
58 the order of those events and mark the ongoing call as being unfin‐
59 ished. When the call returns it will be marked as resumed.
60 [pid 28772] select(4, [3], NULL, NULL, NULL <unfinished ...>
62 [pid 28779] clock_gettime(CLOCK_REALTIME, {1130322148, 939977000}) = 0
63 [pid 28772] <... select resumed> ) = 1 (in [3])
64 Interruption of a (restartable) system call by a signal delivery is
66 processed differently as kernel terminates the system call and also
67 arranges its immediate reexecution after the signal handler completes.
68 read(0, 0x7ffff72cf5cf, 1) = ? ERESTARTSYS (To be restarted)
70 --- SIGALRM ... ---
71 rt_sigreturn(0xe) = 0
72 read(0, "", 1) = 0
73 Arguments are printed in symbolic form with passion. This example
75 shows the shell performing ">>xyzzy" output redirection:
76 open("xyzzy", O_WRONLY|O_APPEND|O_CREAT, 0666) = 3
78 Here, the third argument of open(2) is decoded by breaking down the
80 flag argument into its three bitwise-OR constituents and printing the
81 mode value in octal by tradition. Where the traditional or native
82 usage differs from ANSI or POSIX, the latter forms are preferred. In
83 some cases, strace output is proven to be more readable than the
84 source.
85 Structure pointers are dereferenced and the members are displayed as
87 appropriate. In most cases, arguments are formatted in the most C-like
88 fashion possible. For example, the essence of the command "ls -l
89 /dev/null" is captured as:
90 lstat("/dev/null", {st_mode=S_IFCHR|0666, st_rdev=makedev(0x1, 0x3), ...}) = 0
92 Notice how the 'struct stat' argument is dereferenced and how each mem‐
94 ber is displayed symbolically. In particular, observe how the st_mode
95 member is carefully decoded into a bitwise-OR of symbolic and numeric
96 values. Also notice in this example that the first argument to
97 lstat(2) is an input to the system call and the second argument is an
98 output. Since output arguments are not modified if the system call
99 fails, arguments may not always be dereferenced. For example, retrying
100 the "ls -l" example with a non-existent file produces the following
101 line:
102 lstat("/foo/bar", 0xb004) = -1 ENOENT (No such file or directory)
104 In this case the porch light is on but nobody is home.
106 Syscalls unknown to strace are printed raw, with the unknown system
108 call number printed in hexadecimal form and prefixed with "syscall_":
109 syscall_0xbad(0x1, 0x2, 0x3, 0x4, 0x5, 0x6) = -1 ENOSYS (Function not implemented)
111 Character pointers are dereferenced and printed as C strings. Non-
114 printing characters in strings are normally represented by ordinary C
115 escape codes. Only the first strsize (32 by default) bytes of strings
116 are printed; longer strings have an ellipsis appended following the
117 closing quote. Here is a line from "ls -l" where the getpwuid(3)
118 library routine is reading the password file:
119 read(3, "root::0:0:System Administrator:/"..., 1024) = 422
121 While structures are annotated using curly braces, simple pointers and
123 arrays are printed using square brackets with commas separating ele‐
124 ments. Here is an example from the command id(1) on a system with sup‐
125 plementary group ids:
126 getgroups(32, [100, 0]) = 2
128 On the other hand, bit-sets are also shown using square brackets, but
130 set elements are separated only by a space. Here is the shell, prepar‐
131 ing to execute an external command:
132 sigprocmask(SIG_BLOCK, [CHLD TTOU], []) = 0
134 Here, the second argument is a bit-set of two signals, SIGCHLD and
136 SIGTTOU. In some cases, the bit-set is so full that printing out the
137 unset elements is more valuable. In that case, the bit-set is prefixed
138 by a tilde like this:
139 sigprocmask(SIG_UNBLOCK, ~[], NULL) = 0
141 Here, the second argument represents the full set of all signals.
143
145 General
146 -e expr A qualifying expression which modifies which events to
147 trace or how to trace them. The format of the expression
148 is:
149 [qualifier=][!]value[,value]...
151 where qualifier is one of trace (or t), abbrev (or a), ver‐
153 bose (or v), raw (or x), signal (or signals or s), read (or
154 reads or r), write (or writes or w), fault, inject, status,
155 quiet (or silent or silence or q), decode-fds (or
156 decode-fd), or kvm, and value is a qualifier-dependent sym‐
157 bol or number. The default qualifier is trace. Using an
158 exclamation mark negates the set of values. For example,
159 -e open means literally -e trace=open which in turn means
160 trace only the open system call. By contrast,
161 -e trace=!open means to trace every system call except
162 open. In addition, the special values all and none have
163 the obvious meanings.
164 Note that some shells use the exclamation point for history
166 expansion even inside quoted arguments. If so, you must
167 escape the exclamation point with a backslash.
168 Startup
170 -E var=val
171 --env=var=val
172 Run command with var=val in its list of environment vari‐
173 ables.
174 -E var
176 --env=var Remove var from the inherited list of environment variables
177 before passing it on to the command.
178 -p pid
180 --attach=pid
181 Attach to the process with the process ID pid and begin
182 tracing. The trace may be terminated at any time by a key‐
183 board interrupt signal (CTRL-C). strace will respond by
184 detaching itself from the traced process(es) leaving it
185 (them) to continue running. Multiple -p options can be
186 used to attach to many processes in addition to command
187 (which is optional if at least one -p option is given). -p
188 "`pidof PROG`" syntax is supported.
189 -u username
191 --user=username
192 Run command with the user ID, group ID, and supplementary
193 groups of username. This option is only useful when run‐
194 ning as root and enables the correct execution of setuid
195 and/or setgid binaries. Unless this option is used setuid
196 and setgid programs are executed without effective privi‐
197 leges.
198 Tracing
200 -b syscall
201 --detach-on=syscall
202 If specified syscall is reached, detach from traced
203 process. Currently, only execve(2) syscall is supported.
204 This option is useful if you want to trace multi-threaded
205 process and therefore require -f, but don't want to trace
206 its (potentially very complex) children.
207 -D
209 --daemonize
210 --daemonize=grandchild
211 Run tracer process as a grandchild, not as the parent of
212 the tracee. This reduces the visible effect of strace by
213 keeping the tracee a direct child of the calling process.
214 -DD
216 --daemonize=pgroup
217 --daemonize=pgrp
218 Run tracer process as tracee's grandchild in a separate
219 process group. In addition to reduction of the visible
220 effect of strace, it also avoids killing of strace with
221 kill(2) issued to the whole process group.
222 -DDD
224 --daemonize=session
225 Run tracer process as tracee's grandchild in a separate
226 session ("true daemonisation"). In addition to reduction
227 of the visible effect of strace, it also avoids killing of
228 strace upon session termination.
229 -f
231 --follow-forks
232 Trace child processes as they are created by currently
233 traced processes as a result of the fork(2), vfork(2) and
234 clone(2) system calls. Note that -p PID -f will attach all
235 threads of process PID if it is multi-threaded, not only
236 thread with thread_id = PID.
237 --output-separately
239 If the --output=filename option is in effect, each pro‐
240 cesses trace is written to filename.pid where pid is the
241 numeric process id of each process.
242 -ff
244 --follow-forks --output-separately
245 Combine the effects of --follow-forks and --output-sepa‐
246 rately options. This is incompatible with -c, since no
247 per-process counts are kept.
248 One might want to consider using strace-log-merge(1) to
250 obtain a combined strace log view.
251 -I interruptible
253 --interruptible=interruptible
254 When strace can be interrupted by signals (such as pressing
255 CTRL-C).
256 1, anywhere no signals are blocked;
258 2, waiting fatal signals are blocked while decoding
259 syscall (default);
260 3, never fatal signals are always blocked (default if
261 -o FILE PROG);
262 4, never_tstp fatal signals and SIGTSTP (CTRL-Z) are
263 always blocked (useful to make strace -o
264 FILE PROG not stop on CTRL-Z, default if
265 -D).
266 Filtering
268 -e trace=syscall_set
269 --trace=syscall_set
270 Trace only the specified set of system calls. syscall_set
271 is defined as [!]value[,value], and value can be one of the
272 following:
273 syscall Trace specific syscall, specified by its name
275 (but see NOTES).
276 ?value Question mark before the syscall qualification
278 allows suppression of error in case no
279 syscalls matched the qualification provided.
280 /regex Trace only those system calls that match the
282 regex. You can use POSIX Extended Regular
283 Expression syntax (see regex(7)).
284 syscall@64 Trace syscall only for the 64-bit personality.
286 syscall@32 Trace syscall only for the 32-bit personality.
288 syscall@x32 Trace syscall only for the 32-on-64-bit per‐
290 sonality.
291 %file
293 file Trace all system calls which take a file name
294 as an argument. You can think of this as an
295 abbreviation for
296 -e trace=open,stat,chmod,unlink,... which is
297 useful to seeing what files the process is
298 referencing. Furthermore, using the abbrevia‐
299 tion will ensure that you don't accidentally
300 forget to include a call like lstat(2) in the
301 list. Betchya woulda forgot that one. The
302 syntax without a preceding percent sign ("-e
303 trace=file") is deprecated.
304 %process
306 process Trace all system calls which involve process
307 management. This is useful for watching the
308 fork, wait, and exec steps of a process. The
309 syntax without a preceding percent sign ("-e
310 trace=process") is deprecated.
311 %net
313 %network
314 network Trace all the network related system calls.
315 The syntax without a preceding percent sign
316 ("-e trace=network") is deprecated.
317 %signal
319 signal Trace all signal related system calls. The
320 syntax without a preceding percent sign ("-e
321 trace=signal") is deprecated.
322 %ipc
324 ipc Trace all IPC related system calls. The syn‐
325 tax without a preceding percent sign ("-e
326 trace=ipc") is deprecated.
327 %desc
329 desc Trace all file descriptor related system
330 calls. The syntax without a preceding percent
331 sign ("-e trace=desc") is deprecated.
332 %memory
334 memory Trace all memory mapping related system calls.
335 The syntax without a preceding percent sign
336 ("-e trace=memory") is deprecated.
337 %creds Trace system calls that read or modify user
339 and group identifiers or capability sets.
340 %stat Trace stat syscall variants.
342 %lstat Trace lstat syscall variants.
344 %fstat Trace fstat and fstatat syscall variants.
346 %%stat Trace syscalls used for requesting file status
348 (stat, lstat, fstat, fstatat, statx, and their
349 variants).
350 %statfs Trace statfs, statfs64, statvfs, osf_statfs,
352 and osf_statfs64 system calls. The same
353 effect can be achieved with
354 -e trace=/^(.*_)?statv?fs regular expression.
355 %fstatfs Trace fstatfs, fstatfs64, fstatvfs,
357 osf_fstatfs, and osf_fstatfs64 system calls.
358 The same effect can be achieved with
359 -e trace=/fstatv?fs regular expression.
360 %%statfs Trace syscalls related to file system statis‐
362 tics (statfs-like, fstatfs-like, and ustat).
363 The same effect can be achieved with
364 -e trace=/statv?fs|fsstat|ustat regular
365 expression.
366 %pure Trace syscalls that always succeed and have no
368 arguments. Currently, this list includes
369 arc_gettls(2), getdtablesize(2), getegid(2),
370 getegid32(2), geteuid(2), geteuid32(2), get‐
371 gid(2), getgid32(2), getpagesize(2), getp‐
372 grp(2), getpid(2), getppid(2),
373 get_thread_area(2) (on architectures other
374 than x86), gettid(2), get_tls(2), getuid(2),
375 getuid32(2), getxgid(2), getxpid(2),
376 getxuid(2), kern_features(2), and
377 metag_get_tls(2) syscalls.
378 The -c option is useful for determining which system calls
380 might be useful to trace. For example,
381 trace=open,close,read,write means to only trace those four
382 system calls. Be careful when making inferences about the
383 user/kernel boundary if only a subset of system calls are
384 being monitored. The default is trace=all.
385 -e signal=set
387 --signal=set
388 Trace only the specified subset of signals. The default is
389 signal=all. For example, signal=!SIGIO (or signal=!io)
390 causes SIGIO signals not to be traced.
391 -e status=set
393 --status=set
394 Print only system calls with the specified return status.
395 The default is status=all. When using the status quali‐
396 fier, because strace waits for system calls to return
397 before deciding whether they should be printed or not, the
398 traditional order of events may not be preserved anymore.
399 If two system calls are executed by concurrent threads,
400 strace will first print both the entry and exit of the
401 first system call to exit, regardless of their respective
402 entry time. The entry and exit of the second system call
403 to exit will be printed afterwards. Here is an example
404 when select(2) is called, but a different thread calls
405 clock_gettime(2) before select(2) finishes:
406 [pid 28779] 1130322148.939977 clock_gettime(CLOCK_REALTIME, {1130322148, 939977000}) = 0
408 [pid 28772] 1130322148.438139 select(4, [3], NULL, NULL, NULL) = 1 (in [3])
409 set can include the following elements:
411 successful Trace system calls that returned without an
413 error code. The -z option has the effect of
414 status=successful.
415 failed Trace system calls that returned with an error
416 code. The -Z option has the effect of sta‐
417 tus=failed.
418 unfinished Trace system calls that did not return. This
419 might happen, for example, due to an execve
420 call in a neighbour thread.
421 unavailable Trace system calls that returned but strace
422 failed to fetch the error status.
423 detached Trace system calls for which strace detached
424 before the return.
425 -P path
427 --trace-path=path
428 Trace only system calls accessing path. Multiple -P
429 options can be used to specify several paths.
430 -z
432 --successful-only
433 Print only syscalls that returned without an error code.
434 -Z
436 --failed-only
437 Print only syscalls that returned with an error code.
438 Output format
440 -a column
441 --columns=column
442 Align return values in a specific column (default column
443 40).
444 -e abbrev=syscall_set
446 --abbrev=syscall_set
447 Abbreviate the output from printing each member of large
448 structures. The syntax of the syscall_set specification is
449 the same as in the -e trace option. The default is
450 abbrev=all. The -v option has the effect of abbrev=none.
451 -e verbose=syscall_set
453 --verbose=syscall_set
454 Dereference structures for the specified set of system
455 calls. The syntax of the syscall_set specification is the
456 same as in the -e trace option. The default is ver‐
457 bose=all.
458 -e raw=syscall_set
460 --raw=syscall_set
461 Print raw, undecoded arguments for the specified set of
462 system calls. The syntax of the syscall_set specification
463 is the same as in the -e trace option. This option has the
464 effect of causing all arguments to be printed in hexadeci‐
465 mal. This is mostly useful if you don't trust the decoding
466 or you need to know the actual numeric value of an argu‐
467 ment. See also -X raw option.
468 -e read=set
470 --read=set Perform a full hexadecimal and ASCII dump of all the data
471 read from file descriptors listed in the specified set.
472 For example, to see all input activity on file descriptors
473 3 and 5 use -e read=3,5. Note that this is independent
474 from the normal tracing of the read(2) system call which is
475 controlled by the option -e trace=read.
476 -e write=set
478 --write=set Perform a full hexadecimal and ASCII dump of all the data
479 written to file descriptors listed in the specified set.
480 For example, to see all output activity on file descriptors
481 3 and 5 use -e write=3,5. Note that this is independent
482 from the normal tracing of the write(2) system call which
483 is controlled by the option -e trace=write.
484 -e quiet=set
486 --quiet=set
487 --silent=set
488 --silence=set
489 Suppress various information messages. The default is
490 quiet=none. set can include the following elements:
491 attach Suppress messages about attaching and
493 detaching ("[ Process NNNN attached ]", "[
494 Process NNNN detached ]").
495 exit Suppress messages about process exits
496 ("+++ exited with SSS +++").
497 path-resolution Suppress messages about resolution of
498 paths provided via the -P option
499 ("Requested path "..." resolved into
500 "..."").
501 personality Suppress messages about process personal‐
502 ity changes ("[ Process PID=NNNN runs in
503 PPP mode. ]").
504 thread-execve
505 superseded Suppress messages about process being
506 superseded by execve(2) in another thread
507 ("+++ superseded by execve in pid NNNN
508 +++").
509 -e decode-fds=set
511 --decode-fds=set
512 Decode various information associated with file descrip‐
513 tors. The default is decode-fds=none. set can include the
514 following elements:
515 path Print file paths.
517 socket Print socket protocol-specific information,
518 dev Print character/block device numbers.
519 pidfd Print PIDs associated with pidfd file descriptors.
520 -e kvm=vcpu
522 --kvm=vcpu Print the exit reason of kvm vcpu. Requires Linux kernel
523 version 4.16.0 or higher.
524 -i
526 --instruction-pointer
527 Print the instruction pointer at the time of the system
528 call.
529 -k
531 --stack-traces
532 Print the execution stack trace of the traced processes
533 after each system call.
534 -o filename
536 --output=filename
537 Write the trace output to the file filename rather than to
538 stderr. filename.pid form is used if -ff option is sup‐
539 plied. If the argument begins with '|' or '!', the rest of
540 the argument is treated as a command and all output is
541 piped to it. This is convenient for piping the debugging
542 output to a program without affecting the redirections of
543 executed programs. The latter is not compatible with -ff
544 option currently.
545 -A
547 --output-append-mode
548 Open the file provided in the -o option in append mode.
549 -q
551 --quiet
552 --quiet=attach,personality
553 Suppress messages about attaching, detaching, and personal‐
554 ity changes. This happens automatically when output is
555 redirected to a file and the command is run directly
556 instead of attaching.
557 -qq
559 --quiet=attach,personality,exit
560 Suppress messages attaching, detaching, personality
561 changes, and about process exit status.
562 -qqq
564 --quiet=all Suppress all suppressible messages (please refer to the -e
565 quiet option description for the full list of suppressible
566 messages).
567 -r
569 --relative-timestamps[=precision]
570 Print a relative timestamp upon entry to each system call.
571 This records the time difference between the beginning of
572 successive system calls. precision can be one of s (for
573 seconds), ms (milliseconds), us (microseconds), or ns
574 (nanoseconds), and allows setting the precision of time
575 value being printed. Default is us (microseconds). Note
576 that since -r option uses the monotonic clock time for mea‐
577 suring time difference and not the wall clock time, its
578 measurements can differ from the difference in time
579 reported by the -t option.
580 -s strsize
582 --string-limit=strsize
583 Specify the maximum string size to print (the default is
584 32). Note that filenames are not considered strings and
585 are always printed in full.
586 --absolute-timestamps[=[[format:]format],[[precision:]precision]]
588 --timestamps[=[[format:]format],[[precision:]precision]]
589 Prefix each line of the trace with the wall clock time in
590 the specified format with the specified precision. format
591 can be one of the following:
592 none No time stamp is printed. Can be used to
594 override the previous setting.
595 time Wall clock time (strftime(3) format string is
596 %T).
597 unix Number of seconds since the epoch (strf‐
598 time(3) format string is %s).
599 precision can be one of s (for seconds), ms (milliseconds),
601 us (microseconds), or ns (nanoseconds). Default arguments
602 for the option are format:time,precision:s.
603 -t
605 --absolute-timestamps
606 Prefix each line of the trace with the wall clock time.
607 -tt
609 --absolute-timestamps=precision:us
610 If given twice, the time printed will include the microsec‐
611 onds.
612 -ttt
614 --absolute-timestamps=format:unix,precision:us
615 If given thrice, the time printed will include the
616 microseconds and the leading portion will be printed as the
617 number of seconds since the epoch.
618 -T
620 --syscall-times[=precision]
621 Show the time spent in system calls. This records the time
622 difference between the beginning and the end of each system
623 call. precision can be one of s (for seconds), ms (mil‐
624 liseconds), us (microseconds), or ns (nanoseconds), and
625 allows setting the precision of time value being printed.
626 Default is us (microseconds).
627 -v
629 --no-abbrev Print unabbreviated versions of environment, stat, termios,
630 etc. calls. These structures are very common in calls and
631 so the default behavior displays a reasonable subset of
632 structure members. Use this option to get all of the gory
633 details.
634 -x
636 --strings-in-hex=non-ascii
637 Print all non-ASCII strings in hexadecimal string format.
638 -xx
640 --strings-in-hex
641 --strings-in-hex=all
642 Print all strings in hexadecimal string format.
643 -X format
645 --const-print-style=format
646 Set the format for printing of named constants and flags.
647 Supported format values are:
648 raw Raw number output, without decoding.
650 abbrev Output a named constant or a set of flags instead
651 of the raw number if they are found. This is the
652 default strace behaviour.
653 verbose Output both the raw value and the decoded string
654 (as a comment).
655 -y
657 --decode-fds
658 --decode-fds=path
659 Print paths associated with file descriptor arguments.
660 -yy
662 --decode-fds=all
663 Print all available information associated with file
664 descritors: protocol-specific information associated with
665 socket file descriptors, block/character device number
666 associated with device file descriptors, and PIDs asociated
667 with pidfd file descriptors.
668 Statistics
670 -c
671 --summary-only
672 Count time, calls, and errors for each system call and
673 report a summary on program exit, suppressing the regular
674 output. This attempts to show system time (CPU time spent
675 running in the kernel) independent of wall clock time. If
676 -c is used with -f, only aggregate totals for all traced
677 processes are kept.
678 -C
680 --summary Like -c but also print regular output while processes are
681 running.
682 -O overhead
684 --summary-syscall-overhead =overhead
685 Set the overhead for tracing system calls to overhead.
686 This is useful for overriding the default heuristic for
687 guessing how much time is spent in mere measuring when tim‐
688 ing system calls using the -c option. The accuracy of the
689 heuristic can be gauged by timing a given program run with‐
690 out tracing (using time(1)) and comparing the accumulated
691 system call time to the total produced using -c.
692 The format of overhead specification is described in sec‐
694 tion Time specification format description.
695 -S sortby
697 --summary-sort-by=sortby
698 Sort the output of the histogram printed by the -c option
699 by the specified criterion. Legal values are time (or
700 time-percent or time-total or total-time), min-time (or
701 shortest or time-min), max-time (or longest or time-max),
702 avg-time (or time-avg), calls (or count), errors (or
703 error), name (or syscall or syscall-name), and nothing (or
704 none); default is time.
705 -U columns
707 --summary-columns=columns
708 Configure a set (and order) of columns being shown in the
709 call summary. The columns argument is a comma-separated
710 list with items being one of the following:
711 time-percent (or time) Percentage of cumula‐
713 tive time consumed by a
714 specific system call.
715 total-time (or time-total) Total system (or wall
716 clock, if -w option is
717 provided) time consumed
718 by a specific system
719 call.
720 min-time (or shortest or time-min) Minimum observed call
721 duration.
722 max-time (or longest or time-max) Maximum observed call
723 duration.
724 avg-time (or time-avg) Average call duration.
725 calls (or count) Call count.
726 errors (or error) Error count.
727 name (or syscall or syscall-name) Syscall name.
728 The default value is time-per‐
730 cent,total-time,avg-time,calls,errors,name. If the name
731 field is not supplied explicitly, it is added as the last
732 column.
733 -w
735 --summary-wall-clock
736 Summarise the time difference between the beginning and end
737 of each system call. The default is to summarise the sys‐
738 tem time.
739 Tampering
741 -e inject=syscall_set[:error=errno|:retval=value][:sig‐
742 nal=sig][:syscall=syscall][:delay_enter=delay][:delay_exit=delay][:when=expr]
743 --inject=syscall_set[:error=errno|:retval=value][:sig‐
744 nal=sig][:syscall=syscall][:delay_enter=delay][:delay_exit=delay][:when=expr]
745 Perform syscall tampering for the specified set of
746 syscalls. The syntax of the syscall_set specification is
747 the same as in the -e trace option.
748 At least one of error, retval, signal, delay_enter, or
750 delay_exit options has to be specified. error and retval
751 are mutually exclusive.
752 If :error=errno option is specified, a fault is injected
754 into a syscall invocation: the syscall number is replaced
755 by -1 which corresponds to an invalid syscall (unless a
756 syscall is specified with :syscall= option), and the error
757 code is specified using a symbolic errno value like ENOSYS
758 or a numeric value within 1..4095 range.
759 If :retval=value option is specified, success injection is
761 performed: the syscall number is replaced by -1, but a
762 bogus success value is returned to the callee.
763 If :signal=sig option is specified with either a symbolic
765 value like SIGSEGV or a numeric value within 1..SIGRTMAX
766 range, that signal is delivered on entering every syscall
767 specified by the set.
768 If :delay_enter=delay or :delay_exit=delay options are
770 specified, delay injection is performed: the tracee is
771 delayed by time period specified by delay on entering or
772 exiting the syscall, respectively. The format of delay
773 specification is described in section Time specification
774 format description.
775 If :signal=sig option is specified without :error=errno,
777 :retval=value or :delay_{enter,exit}=usecs options, then
778 only a signal sig is delivered without a syscall fault or
779 delay injection. Conversely, :error=errno or :retval=value
780 option without :delay_enter=delay, :delay_exit=delay or
781 :signal=sig options injects a fault without delivering a
782 signal or injecting a delay, etc.
783 If both :error=errno or :retval=value and :signal=sig
785 options are specified, then both a fault or success is
786 injected and a signal is delivered.
787 if :syscall=syscall option is specified, the corresponding
789 syscall with no side effects is injected instead of -1.
790 Currently, only "pure" (see -e trace=%pure description)
791 syscalls can be specified there.
792 Unless a :when=expr subexpression is specified, an injec‐
794 tion is being made into every invocation of each syscall
795 from the set.
796 The format of the subexpression is one of the following:
798 first For every syscall from the set, perform an
800 injection for the syscall invocation number
801 first only.
802 first+ For every syscall from the set, perform injec‐
803 tions for the syscall invocation number first
804 and all subsequent invocations.
805 first+step For every syscall from the set, perform injec‐
806 tions for syscall invocations number first,
807 first+step, first+step+step, and so on.
808 For example, to fail each third and subsequent chdir
810 syscalls with ENOENT, use
811 -e inject=chdir:error=ENOENT:when=3+.
812 The valid range for numbers first and step is 1..65535.
814 An injection expression can contain only one error= or ret‐
816 val= specification, and only one signal= specification. If
817 an injection expression contains multiple when= specifica‐
818 tions, the last one takes precedence.
819 Accounting of syscalls that are subject to injection is
821 done per syscall and per tracee.
822 Specification of syscall injection can be combined with
824 other syscall filtering options, for example, -P /dev/uran‐
825 dom -e inject=file:error=ENOENT.
826 -e fault=syscall_set[:error=errno][:when=expr]
828 --fault=syscall_set[:error=errno][:when=expr]
829 Perform syscall fault injection for the specified set of
830 syscalls.
831 This is equivalent to more generic -e inject= expression
833 with default value of errno option set to ENOSYS.
834 Miscellaneous
836 -d
837 --debug Show some debugging output of strace itself on the standard
838 error.
839 -F This option is deprecated. It is retained for backward
841 compatibility only and may be removed in future releases.
842 Usage of multiple instances of -F option is still equiva‐
843 lent to a single -f, and it is ignored at all if used along
844 with one or more instances of -f option.
845 -h
847 --help Print the help summary.
848 --seccomp-bpf
850 Try to enable use of seccomp-bpf (see seccomp(2)) to have
851 ptrace(2)-stops only when system calls that are being
852 traced occur in the traced processes. This option has no
853 effect unless -f/--follow-forks is also specified. --sec‐
854 comp-bpf is also not applicable to processes attached using
855 -p/--attach option. An attempt to enable system calls fil‐
856 tering using seccomp-bpf may fail for various reasons, e.g.
857 there are too many system calls to filter, the seccomp API
858 is not available, or strace itself is being traced. In
859 cases when seccomp-bpf filter setup failed, strace proceeds
860 as usual and stops traced processes on every system call.
861 -V
863 --version Print the version number of strace.
864 Time specification format description
866 Time values can be specified as a decimal floating point number (in a
867 format accepted by strtod(3)), optionally followed by one of the fol‐
868 lowing suffices that specify the unit of time: s (seconds), ms (mil‐
869 liseconds), us (microseconds), or ns (nanoseconds). If no suffix is
870 specified, the value is interpreted as microseconds.
871 The described format is used for -O, -e inject=delay_enter, and -e
873 inject=delay_exit options.
874
876 When command exits, strace exits with the same exit status. If command
877 is terminated by a signal, strace terminates itself with the same sig‐
878 nal, so that strace can be used as a wrapper process transparent to the
879 invoking parent process. Note that parent-child relationship (signal
880 stop notifications, getppid(2) value, etc) between traced process and
881 its parent are not preserved unless -D is used.
882 When using -p without a command, the exit status of strace is zero
884 unless no processes has been attached or there was an unexpected error
885 in doing the tracing.
886
888 If strace is installed setuid to root then the invoking user will be
889 able to attach to and trace processes owned by any user. In addition
890 setuid and setgid programs will be executed and traced with the correct
891 effective privileges. Since only users trusted with full root privi‐
892 leges should be allowed to do these things, it only makes sense to
893 install strace as setuid to root when the users who can execute it are
894 restricted to those users who have this trust. For example, it makes
895 sense to install a special version of strace with mode 'rwsr-xr--',
896 user root and group trace, where members of the trace group are trusted
897 users. If you do use this feature, please remember to install a regu‐
898 lar non-setuid version of strace for ordinary users to use.
899
901 On some architectures, strace supports decoding of syscalls for pro‐
902 cesses that use different ABI rather than the one strace uses. Specif‐
903 ically, in addition to decoding native ABI, strace can decode the fol‐
904 lowing ABIs on the following architectures:
905 ┌───────────────────┬─────────────────────────┐
907 │Architecture │ ABIs supported │
908 ├───────────────────┼─────────────────────────┤
909 │x86_64 │ i386, x32 [1]; i386 [2] │
910 ├───────────────────┼─────────────────────────┤
911 │AArch64 │ ARM 32-bit EABI │
912 ├───────────────────┼─────────────────────────┤
913 │PowerPC 64-bit [3] │ PowerPC 32-bit │
914 ├───────────────────┼─────────────────────────┤
915 │s390x │ s390 │
916 ├───────────────────┼─────────────────────────┤
917 │SPARC 64-bit │ SPARC 32-bit │
918 ├───────────────────┼─────────────────────────┤
919 │TILE 64-bit │ TILE 32-bit │
920 └───────────────────┴─────────────────────────┘
921 [1] When strace is built as an x86_64 application
922 [2] When strace is built as an x32 application
923 [3] Big endian only
924 This support is optional and relies on ability to generate and parse
926 structure definitions during the build time. Please refer to the out‐
927 put of the strace -V command in order to figure out what support is
928 available in your strace build ("non-native" refers to an ABI that dif‐
929 fers from the ABI strace has):
930 m32-mpers strace can trace and properly decode non-native 32-bit
932 binaries.
933 no-m32-mpers strace can trace, but cannot properly decode non-native
934 32-bit binaries.
935 mx32-mpers strace can trace and properly decode non-native
936 32-on-64-bit binaries.
937 no-mx32-mpers strace can trace, but cannot properly decode non-native
938 32-on-64-bit binaries.
939 If the output contains neither m32-mpers nor no-m32-mpers, then decod‐
941 ing of non-native 32-bit binaries is not implemented at all or not
942 applicable.
943 Likewise, if the output contains neither mx32-mpers nor no-mx32-mpers,
945 then decoding of non-native 32-on-64-bit binaries is not implemented at
946 all or not applicable.
947
949 It is a pity that so much tracing clutter is produced by systems
950 employing shared libraries.
951 It is instructive to think about system call inputs and outputs as
953 data-flow across the user/kernel boundary. Because user-space and ker‐
954 nel-space are separate and address-protected, it is sometimes possible
955 to make deductive inferences about process behavior using inputs and
956 outputs as propositions.
957 In some cases, a system call will differ from the documented behavior
959 or have a different name. For example, the faccessat(2) system call
960 does not have flags argument, and the setrlimit(2) library function
961 uses prlimit64(2) system call on modern (2.6.38+) kernels. These dis‐
962 crepancies are normal but idiosyncratic characteristics of the system
963 call interface and are accounted for by C library wrapper functions.
964 Some system calls have different names in different architectures and
966 personalities. In these cases, system call filtering and printing uses
967 the names that match corresponding __NR_* kernel macros of the tracee's
968 architecture and personality. There are two exceptions from this gen‐
969 eral rule: arm_fadvise64_64(2) ARM syscall and xtensa_fadvise64_64(2)
970 Xtensa syscall are filtered and printed as fadvise64_64(2).
971 On x32, syscalls that are intended to be used by 64-bit processes and
973 not x32 ones (for example, readv(2), that has syscall number 19 on
974 x86_64, with its x32 counterpart has syscall number 515), but called
975 with __X32_SYSCALL_BIT flag being set, are designated with #64 suffix.
976 On some platforms a process that is attached to with the -p option may
978 observe a spurious EINTR return from the current system call that is
979 not restartable. (Ideally, all system calls should be restarted on
980 strace attach, making the attach invisible to the traced process, but a
981 few system calls aren't. Arguably, every instance of such behavior is
982 a kernel bug.) This may have an unpredictable effect on the process if
983 the process takes no action to restart the system call.
984 As strace executes the specified command directly and does not employ a
986 shell for that, scripts without shebang that usually run just fine when
987 invoked by shell fail to execute with ENOEXEC error. It is advisable
988 to manually supply a shell as a command with the script as its argu‐
989 ment.
990
992 Programs that use the setuid bit do not have effective user ID privi‐
993 leges while being traced.
994 A traced process runs slowly.
996 Traced processes which are descended from command may be left running
998 after an interrupt signal (CTRL-C).
999
1001 The original strace was written by Paul Kranenburg for SunOS and was
1002 inspired by its trace utility. The SunOS version of strace was ported
1003 to Linux and enhanced by Branko Lankester, who also wrote the Linux
1004 kernel support. Even though Paul released strace 2.5 in 1992, Branko's
1005 work was based on Paul's strace 1.5 release from 1991. In 1993, Rick
1006 Sladkey merged strace 2.5 for SunOS and the second release of strace
1007 for Linux, added many of the features of truss(1) from SVR4, and pro‐
1008 duced an strace that worked on both platforms. In 1994 Rick ported
1009 strace to SVR4 and Solaris and wrote the automatic configuration sup‐
1010 port. In 1995 he ported strace to Irix and tired of writing about him‐
1011 self in the third person.
1012 Beginning with 1996, strace was maintained by Wichert Akkerman. During
1014 his tenure, strace development migrated to CVS; ports to FreeBSD and
1015 many architectures on Linux (including ARM, IA-64, MIPS, PA-RISC, Pow‐
1016 erPC, s390, SPARC) were introduced. In 2002, the burden of strace
1017 maintainership was transferred to Roland McGrath. Since then, strace
1018 gained support for several new Linux architectures (AMD64, s390x,
1019 SuperH), bi-architecture support for some of them, and received numer‐
1020 ous additions and improvements in syscalls decoders on Linux; strace
1021 development migrated to git during that period. Since 2009, strace is
1022 actively maintained by Dmitry Levin. strace gained support for
1023 AArch64, ARC, AVR32, Blackfin, Meta, Nios II, OpenRISC 1000, RISC-V,
1024 Tile/TileGx, Xtensa architectures since that time. In 2012, unmain‐
1025 tained and apparently broken support for non-Linux operating systems
1026 was removed. Also, in 2012 strace gained support for path tracing and
1027 file descriptor path decoding. In 2014, support for stack traces
1028 printing was added. In 2016, syscall fault injection was implemented.
1029 For the additional information, please refer to the NEWS file and
1031 strace repository commit log.
1032
1034 Problems with strace should be reported to the strace mailing list
1035 ⟨mailto:strace-devel@lists.strace.io⟩.
1036
1038 strace-log-merge(1), ltrace(1), perf-trace(1), trace-cmd(1), time(1),
1039 ptrace(2), proc(5)
1040 strace Home Page ⟨https://strace.io/⟩
1042
1044 The complete list of strace contributors can be found in the CREDITS
1045 file.
1046strace 5.6 2020-04-06 STRACE(1)