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 second and the third argument of open(2) are decoded by
80 breaking down the flag argument into its three bitwise-OR constituents
81 and printing the mode value in octal by tradition. Where the tradi‐
82 tional or native usage differs from ANSI or POSIX, the latter forms are
83 preferred. In some cases, strace output is proven to be more readable
84 than the 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 system calls associated with process
307 lifecycle (creation, exec, termination). The
308 syntax without a preceding percent sign ("-e
309 trace=process") is deprecated.
310 %net
312 %network
313 network Trace all the network related system calls.
314 The syntax without a preceding percent sign
315 ("-e trace=network") is deprecated.
316 %signal
318 signal Trace all signal related system calls. The
319 syntax without a preceding percent sign ("-e
320 trace=signal") is deprecated.
321 %ipc
323 ipc Trace all IPC related system calls. The syn‐
324 tax without a preceding percent sign ("-e
325 trace=ipc") is deprecated.
326 %desc
328 desc Trace all file descriptor related system
329 calls. The syntax without a preceding percent
330 sign ("-e trace=desc") is deprecated.
331 %memory
333 memory Trace all memory mapping related system calls.
334 The syntax without a preceding percent sign
335 ("-e trace=memory") is deprecated.
336 %creds Trace system calls that read or modify user
338 and group identifiers or capability sets.
339 %stat Trace stat syscall variants.
341 %lstat Trace lstat syscall variants.
343 %fstat Trace fstat, fstatat, and statx syscall vari‐
345 ants.
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 %clock Trace system calls that read or modify system
368 clocks.
369 %pure Trace syscalls that always succeed and have no
371 arguments. Currently, this list includes
372 arc_gettls(2), getdtablesize(2), getegid(2),
373 getegid32(2), geteuid(2), geteuid32(2), get‐
374 gid(2), getgid32(2), getpagesize(2), getp‐
375 grp(2), getpid(2), getppid(2),
376 get_thread_area(2) (on architectures other
377 than x86), gettid(2), get_tls(2), getuid(2),
378 getuid32(2), getxgid(2), getxpid(2),
379 getxuid(2), kern_features(2), and
380 metag_get_tls(2) syscalls.
381 The -c option is useful for determining which system calls
383 might be useful to trace. For example,
384 trace=open,close,read,write means to only trace those four
385 system calls. Be careful when making inferences about the
386 user/kernel boundary if only a subset of system calls are
387 being monitored. The default is trace=all.
388 -e signal=set
390 --signal=set
391 Trace only the specified subset of signals. The default is
392 signal=all. For example, signal=!SIGIO (or signal=!io)
393 causes SIGIO signals not to be traced.
394 -e status=set
396 --status=set
397 Print only system calls with the specified return status.
398 The default is status=all. When using the status quali‐
399 fier, because strace waits for system calls to return
400 before deciding whether they should be printed or not, the
401 traditional order of events may not be preserved anymore.
402 If two system calls are executed by concurrent threads,
403 strace will first print both the entry and exit of the
404 first system call to exit, regardless of their respective
405 entry time. The entry and exit of the second system call
406 to exit will be printed afterwards. Here is an example
407 when select(2) is called, but a different thread calls
408 clock_gettime(2) before select(2) finishes:
409 [pid 28779] 1130322148.939977 clock_gettime(CLOCK_REALTIME, {1130322148, 939977000}) = 0
411 [pid 28772] 1130322148.438139 select(4, [3], NULL, NULL, NULL) = 1 (in [3])
412 set can include the following elements:
414 successful Trace system calls that returned without an
416 error code. The -z option has the effect of
417 status=successful.
418 failed Trace system calls that returned with an error
419 code. The -Z option has the effect of sta‐
420 tus=failed.
421 unfinished Trace system calls that did not return. This
422 might happen, for example, due to an execve
423 call in a neighbour thread.
424 unavailable Trace system calls that returned but strace
425 failed to fetch the error status.
426 detached Trace system calls for which strace detached
427 before the return.
428 -P path
430 --trace-path=path
431 Trace only system calls accessing path. Multiple -P
432 options can be used to specify several paths.
433 -z
435 --successful-only
436 Print only syscalls that returned without an error code.
437 -Z
439 --failed-only
440 Print only syscalls that returned with an error code.
441 Output format
443 -a column
444 --columns=column
445 Align return values in a specific column (default column
446 40).
447 -e abbrev=syscall_set
449 --abbrev=syscall_set
450 Abbreviate the output from printing each member of large
451 structures. The syntax of the syscall_set specification is
452 the same as in the -e trace option. The default is
453 abbrev=all. The -v option has the effect of abbrev=none.
454 -e verbose=syscall_set
456 --verbose=syscall_set
457 Dereference structures for the specified set of system
458 calls. The syntax of the syscall_set specification is the
459 same as in the -e trace option. The default is ver‐
460 bose=all.
461 -e raw=syscall_set
463 --raw=syscall_set
464 Print raw, undecoded arguments for the specified set of
465 system calls. The syntax of the syscall_set specification
466 is the same as in the -e trace option. This option has the
467 effect of causing all arguments to be printed in hexadeci‐
468 mal. This is mostly useful if you don't trust the decoding
469 or you need to know the actual numeric value of an argu‐
470 ment. See also -X raw option.
471 -e read=set
473 --read=set Perform a full hexadecimal and ASCII dump of all the data
474 read from file descriptors listed in the specified set.
475 For example, to see all input activity on file descriptors
476 3 and 5 use -e read=3,5. Note that this is independent
477 from the normal tracing of the read(2) system call which is
478 controlled by the option -e trace=read.
479 -e write=set
481 --write=set Perform a full hexadecimal and ASCII dump of all the data
482 written to file descriptors listed in the specified set.
483 For example, to see all output activity on file descriptors
484 3 and 5 use -e write=3,5. Note that this is independent
485 from the normal tracing of the write(2) system call which
486 is controlled by the option -e trace=write.
487 -e quiet=set
489 --quiet=set
490 --silent=set
491 --silence=set
492 Suppress various information messages. The default is
493 quiet=none. set can include the following elements:
494 attach Suppress messages about attaching and
496 detaching ("[ Process NNNN attached ]", "[
497 Process NNNN detached ]").
498 exit Suppress messages about process exits
499 ("+++ exited with SSS +++").
500 path-resolution Suppress messages about resolution of
501 paths provided via the -P option
502 ("Requested path "..." resolved into
503 "..."").
504 personality Suppress messages about process personal‐
505 ity changes ("[ Process PID=NNNN runs in
506 PPP mode. ]").
507 thread-execve
508 superseded Suppress messages about process being
509 superseded by execve(2) in another thread
510 ("+++ superseded by execve in pid NNNN
511 +++").
512 -e decode-fds=set
514 --decode-fds=set
515 Decode various information associated with file descrip‐
516 tors. The default is decode-fds=none. set can include the
517 following elements:
518 path Print file paths.
520 socket Print socket protocol-specific information,
521 dev Print character/block device numbers.
522 pidfd Print PIDs associated with pidfd file descriptors.
523 -e kvm=vcpu
525 --kvm=vcpu Print the exit reason of kvm vcpu. Requires Linux kernel
526 version 4.16.0 or higher.
527 -i
529 --instruction-pointer
530 Print the instruction pointer at the time of the system
531 call.
532 -n
534 --syscall-number
535 Print the syscall number.
536 -k
538 --stack-traces
539 Print the execution stack trace of the traced processes
540 after each system call.
541 -o filename
543 --output=filename
544 Write the trace output to the file filename rather than to
545 stderr. filename.pid form is used if -ff option is sup‐
546 plied. If the argument begins with '|' or '!', the rest of
547 the argument is treated as a command and all output is
548 piped to it. This is convenient for piping the debugging
549 output to a program without affecting the redirections of
550 executed programs. The latter is not compatible with -ff
551 option currently.
552 -A
554 --output-append-mode
555 Open the file provided in the -o option in append mode.
556 -q
558 --quiet
559 --quiet=attach,personality
560 Suppress messages about attaching, detaching, and personal‐
561 ity changes. This happens automatically when output is
562 redirected to a file and the command is run directly
563 instead of attaching.
564 -qq
566 --quiet=attach,personality,exit
567 Suppress messages attaching, detaching, personality
568 changes, and about process exit status.
569 -qqq
571 --quiet=all Suppress all suppressible messages (please refer to the -e
572 quiet option description for the full list of suppressible
573 messages).
574 -r
576 --relative-timestamps[=precision]
577 Print a relative timestamp upon entry to each system call.
578 This records the time difference between the beginning of
579 successive system calls. precision can be one of s (for
580 seconds), ms (milliseconds), us (microseconds), or ns
581 (nanoseconds), and allows setting the precision of time
582 value being printed. Default is us (microseconds). Note
583 that since -r option uses the monotonic clock time for mea‐
584 suring time difference and not the wall clock time, its
585 measurements can differ from the difference in time
586 reported by the -t option.
587 -s strsize
589 --string-limit=strsize
590 Specify the maximum string size to print (the default is
591 32). Note that filenames are not considered strings and
592 are always printed in full.
593 --absolute-timestamps[=[[format:]format],[[precision:]precision]]
595 --timestamps[=[[format:]format],[[precision:]precision]]
596 Prefix each line of the trace with the wall clock time in
597 the specified format with the specified precision. format
598 can be one of the following:
599 none No time stamp is printed. Can be used to
601 override the previous setting.
602 time Wall clock time (strftime(3) format string is
603 %T).
604 unix Number of seconds since the epoch (strf‐
605 time(3) format string is %s).
606 precision can be one of s (for seconds), ms (milliseconds),
608 us (microseconds), or ns (nanoseconds). Default arguments
609 for the option are format:time,precision:s.
610 -t
612 --absolute-timestamps
613 Prefix each line of the trace with the wall clock time.
614 -tt
616 --absolute-timestamps=precision:us
617 If given twice, the time printed will include the microsec‐
618 onds.
619 -ttt
621 --absolute-timestamps=format:unix,precision:us
622 If given thrice, the time printed will include the
623 microseconds and the leading portion will be printed as the
624 number of seconds since the epoch.
625 -T
627 --syscall-times[=precision]
628 Show the time spent in system calls. This records the time
629 difference between the beginning and the end of each system
630 call. precision can be one of s (for seconds), ms (mil‐
631 liseconds), us (microseconds), or ns (nanoseconds), and
632 allows setting the precision of time value being printed.
633 Default is us (microseconds).
634 -v
636 --no-abbrev Print unabbreviated versions of environment, stat, termios,
637 etc. calls. These structures are very common in calls and
638 so the default behavior displays a reasonable subset of
639 structure members. Use this option to get all of the gory
640 details.
641 -x
643 --strings-in-hex=non-ascii
644 Print all non-ASCII strings in hexadecimal string format.
645 -xx
647 --strings-in-hex
648 --strings-in-hex=all
649 Print all strings in hexadecimal string format.
650 -X format
652 --const-print-style=format
653 Set the format for printing of named constants and flags.
654 Supported format values are:
655 raw Raw number output, without decoding.
657 abbrev Output a named constant or a set of flags instead
658 of the raw number if they are found. This is the
659 default strace behaviour.
660 verbose Output both the raw value and the decoded string
661 (as a comment).
662 -y
664 --decode-fds
665 --decode-fds=path
666 Print paths associated with file descriptor arguments.
667 -yy
669 --decode-fds=all
670 Print all available information associated with file
671 descriptors: protocol-specific information associated with
672 socket file descriptors, block/character device number
673 associated with device file descriptors, and PIDs associ‐
674 ated with pidfd file descriptors.
675 --pidns-translation
677 If strace and tracee are in different PID namespaces, print
678 PIDs in strace's namespace, too.
679 Statistics
681 -c
682 --summary-only
683 Count time, calls, and errors for each system call and
684 report a summary on program exit, suppressing the regular
685 output. This attempts to show system time (CPU time spent
686 running in the kernel) independent of wall clock time. If
687 -c is used with -f, only aggregate totals for all traced
688 processes are kept.
689 -C
691 --summary Like -c but also print regular output while processes are
692 running.
693 -O overhead
695 --summary-syscall-overhead =overhead
696 Set the overhead for tracing system calls to overhead.
697 This is useful for overriding the default heuristic for
698 guessing how much time is spent in mere measuring when tim‐
699 ing system calls using the -c option. The accuracy of the
700 heuristic can be gauged by timing a given program run with‐
701 out tracing (using time(1)) and comparing the accumulated
702 system call time to the total produced using -c.
703 The format of overhead specification is described in sec‐
705 tion Time specification format description.
706 -S sortby
708 --summary-sort-by=sortby
709 Sort the output of the histogram printed by the -c option
710 by the specified criterion. Legal values are time (or
711 time-percent or time-total or total-time), min-time (or
712 shortest or time-min), max-time (or longest or time-max),
713 avg-time (or time-avg), calls (or count), errors (or
714 error), name (or syscall or syscall-name), and nothing (or
715 none); default is time.
716 -U columns
718 --summary-columns=columns
719 Configure a set (and order) of columns being shown in the
720 call summary. The columns argument is a comma-separated
721 list with items being one of the following:
722 time-percent (or time) Percentage of cumula‐
724 tive time consumed by a
725 specific system call.
726 total-time (or time-total) Total system (or wall
727 clock, if -w option is
728 provided) time consumed
729 by a specific system
730 call.
731 min-time (or shortest or time-min) Minimum observed call
732 duration.
733 max-time (or longest or time-max) Maximum observed call
734 duration.
735 avg-time (or time-avg) Average call duration.
736 calls (or count) Call count.
737 errors (or error) Error count.
738 name (or syscall or syscall-name) Syscall name.
739 The default value is time-per‐
741 cent,total-time,avg-time,calls,errors,name. If the name
742 field is not supplied explicitly, it is added as the last
743 column.
744 -w
746 --summary-wall-clock
747 Summarise the time difference between the beginning and end
748 of each system call. The default is to summarise the sys‐
749 tem time.
750 Tampering
752 -e inject=syscall_set[:error=errno|:retval=value][:sig‐
753 nal=sig][:syscall=syscall][:delay_enter=delay][:delay_exit=delay][:when=expr]
754 --inject=syscall_set[:error=errno|:retval=value][:sig‐
755 nal=sig][:syscall=syscall][:delay_enter=delay][:delay_exit=delay][:when=expr]
756 Perform syscall tampering for the specified set of
757 syscalls. The syntax of the syscall_set specification is
758 the same as in the -e trace option.
759 At least one of error, retval, signal, delay_enter, or
761 delay_exit options has to be specified. error and retval
762 are mutually exclusive.
763 If :error=errno option is specified, a fault is injected
765 into a syscall invocation: the syscall number is replaced
766 by -1 which corresponds to an invalid syscall (unless a
767 syscall is specified with :syscall= option), and the error
768 code is specified using a symbolic errno value like ENOSYS
769 or a numeric value within 1..4095 range.
770 If :retval=value option is specified, success injection is
772 performed: the syscall number is replaced by -1, but a
773 bogus success value is returned to the callee.
774 If :signal=sig option is specified with either a symbolic
776 value like SIGSEGV or a numeric value within 1..SIGRTMAX
777 range, that signal is delivered on entering every syscall
778 specified by the set.
779 If :delay_enter=delay or :delay_exit=delay options are
781 specified, delay injection is performed: the tracee is
782 delayed by time period specified by delay on entering or
783 exiting the syscall, respectively. The format of delay
784 specification is described in section Time specification
785 format description.
786 If :signal=sig option is specified without :error=errno,
788 :retval=value or :delay_{enter,exit}=usecs options, then
789 only a signal sig is delivered without a syscall fault or
790 delay injection. Conversely, :error=errno or :retval=value
791 option without :delay_enter=delay, :delay_exit=delay or
792 :signal=sig options injects a fault without delivering a
793 signal or injecting a delay, etc.
794 If both :error=errno or :retval=value and :signal=sig
796 options are specified, then both a fault or success is
797 injected and a signal is delivered.
798 if :syscall=syscall option is specified, the corresponding
800 syscall with no side effects is injected instead of -1.
801 Currently, only "pure" (see -e trace=%pure description)
802 syscalls can be specified there.
803 Unless a :when=expr subexpression is specified, an injec‐
805 tion is being made into every invocation of each syscall
806 from the set.
807 The format of the subexpression is:
809 first[..last][+[step]]
811 Number first stands for the first invocation number in the
813 range, number last stands for the last invocation number in
814 the range, and step stands for the step between two consec‐
815 utive invocations. The following combinations are useful:
816 first For every syscall from the set, perform
818 an injection for the syscall invocation
819 number first only.
820 first..last For every syscall from the set, perform
821 an injection for the syscall invocation
822 number first and all subsequent invoca‐
823 tions until the invocation number last
824 (inclusive).
825 first+ For every syscall from the set, perform
826 injections for the syscall invocation
827 number first and all subsequent invoca‐
828 tions.
829 first..last+ For every syscall from the set, perform
830 injections for the syscall invocation
831 number first and all subsequent invoca‐
832 tions until the invocation number last
833 (inclusive).
834 first+step For every syscall from the set, perform
835 injections for syscall invocations number
836 first, first+step, first+step+step, and
837 so on.
838 first..last+step Same as the previous, but consider only
839 syscall invocations with numbers up to
840 last (inclusive).
841 For example, to fail each third and subsequent chdir
843 syscalls with ENOENT, use
844 -e inject=chdir:error=ENOENT:when=3+.
845 The valid range for numbers first and step is 1..65535, and
847 for number last is 1..65534.
848 An injection expression can contain only one error= or ret‐
850 val= specification, and only one signal= specification. If
851 an injection expression contains multiple when= specifica‐
852 tions, the last one takes precedence.
853 Accounting of syscalls that are subject to injection is
855 done per syscall and per tracee.
856 Specification of syscall injection can be combined with
858 other syscall filtering options, for example, -P /dev/uran‐
859 dom -e inject=file:error=ENOENT.
860 -e fault=syscall_set[:error=errno][:when=expr]
862 --fault=syscall_set[:error=errno][:when=expr]
863 Perform syscall fault injection for the specified set of
864 syscalls.
865 This is equivalent to more generic -e inject= expression
867 with default value of errno option set to ENOSYS.
868 Miscellaneous
870 -d
871 --debug Show some debugging output of strace itself on the standard
872 error.
873 -F This option is deprecated. It is retained for backward
875 compatibility only and may be removed in future releases.
876 Usage of multiple instances of -F option is still equiva‐
877 lent to a single -f, and it is ignored at all if used along
878 with one or more instances of -f option.
879 -h
881 --help Print the help summary.
882 --seccomp-bpf
884 Try to enable use of seccomp-bpf (see seccomp(2)) to have
885 ptrace(2)-stops only when system calls that are being
886 traced occur in the traced processes. This option has no
887 effect unless -f/--follow-forks is also specified. --sec‐
888 comp-bpf is also not applicable to processes attached using
889 -p/--attach option. An attempt to enable system calls fil‐
890 tering using seccomp-bpf may fail for various reasons, e.g.
891 there are too many system calls to filter, the seccomp API
892 is not available, or strace itself is being traced. In
893 cases when seccomp-bpf filter setup failed, strace proceeds
894 as usual and stops traced processes on every system call.
895 -V
897 --version Print the version number of strace.
898 Time specification format description
900 Time values can be specified as a decimal floating point number (in a
901 format accepted by strtod(3)), optionally followed by one of the fol‐
902 lowing suffices that specify the unit of time: s (seconds), ms (mil‐
903 liseconds), us (microseconds), or ns (nanoseconds). If no suffix is
904 specified, the value is interpreted as microseconds.
905 The described format is used for -O, -e inject=delay_enter, and -e
907 inject=delay_exit options.
908
910 When command exits, strace exits with the same exit status. If command
911 is terminated by a signal, strace terminates itself with the same sig‐
912 nal, so that strace can be used as a wrapper process transparent to the
913 invoking parent process. Note that parent-child relationship (signal
914 stop notifications, getppid(2) value, etc) between traced process and
915 its parent are not preserved unless -D is used.
916 When using -p without a command, the exit status of strace is zero
918 unless no processes has been attached or there was an unexpected error
919 in doing the tracing.
920
922 If strace is installed setuid to root then the invoking user will be
923 able to attach to and trace processes owned by any user. In addition
924 setuid and setgid programs will be executed and traced with the correct
925 effective privileges. Since only users trusted with full root privi‐
926 leges should be allowed to do these things, it only makes sense to
927 install strace as setuid to root when the users who can execute it are
928 restricted to those users who have this trust. For example, it makes
929 sense to install a special version of strace with mode 'rwsr-xr--',
930 user root and group trace, where members of the trace group are trusted
931 users. If you do use this feature, please remember to install a regu‐
932 lar non-setuid version of strace for ordinary users to use.
933
935 On some architectures, strace supports decoding of syscalls for pro‐
936 cesses that use different ABI rather than the one strace uses. Specif‐
937 ically, in addition to decoding native ABI, strace can decode the fol‐
938 lowing ABIs on the following architectures:
939 ┌───────────────────┬─────────────────────────┐
941 │Architecture │ ABIs supported │
942 ├───────────────────┼─────────────────────────┤
943 │x86_64 │ i386, x32 [1]; i386 [2] │
944 ├───────────────────┼─────────────────────────┤
945 │AArch64 │ ARM 32-bit EABI │
946 ├───────────────────┼─────────────────────────┤
947 │PowerPC 64-bit [3] │ PowerPC 32-bit │
948 ├───────────────────┼─────────────────────────┤
949 │s390x │ s390 │
950 ├───────────────────┼─────────────────────────┤
951 │SPARC 64-bit │ SPARC 32-bit │
952 ├───────────────────┼─────────────────────────┤
953 │TILE 64-bit │ TILE 32-bit │
954 └───────────────────┴─────────────────────────┘
955 [1] When strace is built as an x86_64 application
956 [2] When strace is built as an x32 application
957 [3] Big endian only
958 This support is optional and relies on ability to generate and parse
960 structure definitions during the build time. Please refer to the out‐
961 put of the strace -V command in order to figure out what support is
962 available in your strace build ("non-native" refers to an ABI that dif‐
963 fers from the ABI strace has):
964 m32-mpers strace can trace and properly decode non-native 32-bit
966 binaries.
967 no-m32-mpers strace can trace, but cannot properly decode non-native
968 32-bit binaries.
969 mx32-mpers strace can trace and properly decode non-native
970 32-on-64-bit binaries.
971 no-mx32-mpers strace can trace, but cannot properly decode non-native
972 32-on-64-bit binaries.
973 If the output contains neither m32-mpers nor no-m32-mpers, then decod‐
975 ing of non-native 32-bit binaries is not implemented at all or not
976 applicable.
977 Likewise, if the output contains neither mx32-mpers nor no-mx32-mpers,
979 then decoding of non-native 32-on-64-bit binaries is not implemented at
980 all or not applicable.
981
983 It is a pity that so much tracing clutter is produced by systems
984 employing shared libraries.
985 It is instructive to think about system call inputs and outputs as
987 data-flow across the user/kernel boundary. Because user-space and ker‐
988 nel-space are separate and address-protected, it is sometimes possible
989 to make deductive inferences about process behavior using inputs and
990 outputs as propositions.
991 In some cases, a system call will differ from the documented behavior
993 or have a different name. For example, the faccessat(2) system call
994 does not have flags argument, and the setrlimit(2) library function
995 uses prlimit64(2) system call on modern (2.6.38+) kernels. These dis‐
996 crepancies are normal but idiosyncratic characteristics of the system
997 call interface and are accounted for by C library wrapper functions.
998 Some system calls have different names in different architectures and
1000 personalities. In these cases, system call filtering and printing uses
1001 the names that match corresponding __NR_* kernel macros of the tracee's
1002 architecture and personality. There are two exceptions from this gen‐
1003 eral rule: arm_fadvise64_64(2) ARM syscall and xtensa_fadvise64_64(2)
1004 Xtensa syscall are filtered and printed as fadvise64_64(2).
1005 On x32, syscalls that are intended to be used by 64-bit processes and
1007 not x32 ones (for example, readv(2), that has syscall number 19 on
1008 x86_64, with its x32 counterpart has syscall number 515), but called
1009 with __X32_SYSCALL_BIT flag being set, are designated with #64 suffix.
1010 On some platforms a process that is attached to with the -p option may
1012 observe a spurious EINTR return from the current system call that is
1013 not restartable. (Ideally, all system calls should be restarted on
1014 strace attach, making the attach invisible to the traced process, but a
1015 few system calls aren't. Arguably, every instance of such behavior is
1016 a kernel bug.) This may have an unpredictable effect on the process if
1017 the process takes no action to restart the system call.
1018 As strace executes the specified command directly and does not employ a
1020 shell for that, scripts without shebang that usually run just fine when
1021 invoked by shell fail to execute with ENOEXEC error. It is advisable
1022 to manually supply a shell as a command with the script as its argu‐
1023 ment.
1024
1026 Programs that use the setuid bit do not have effective user ID privi‐
1027 leges while being traced.
1028 A traced process runs slowly (but check out the --seccomp-bpf option).
1030 Traced processes which are descended from command may be left running
1032 after an interrupt signal (CTRL-C).
1033
1035 The original strace was written by Paul Kranenburg for SunOS and was
1036 inspired by its trace utility. The SunOS version of strace was ported
1037 to Linux and enhanced by Branko Lankester, who also wrote the Linux
1038 kernel support. Even though Paul released strace 2.5 in 1992, Branko's
1039 work was based on Paul's strace 1.5 release from 1991. In 1993, Rick
1040 Sladkey merged strace 2.5 for SunOS and the second release of strace
1041 for Linux, added many of the features of truss(1) from SVR4, and pro‐
1042 duced an strace that worked on both platforms. In 1994 Rick ported
1043 strace to SVR4 and Solaris and wrote the automatic configuration sup‐
1044 port. In 1995 he ported strace to Irix and tired of writing about him‐
1045 self in the third person.
1046 Beginning with 1996, strace was maintained by Wichert Akkerman. During
1048 his tenure, strace development migrated to CVS; ports to FreeBSD and
1049 many architectures on Linux (including ARM, IA-64, MIPS, PA-RISC, Pow‐
1050 erPC, s390, SPARC) were introduced. In 2002, the burden of strace
1051 maintainership was transferred to Roland McGrath. Since then, strace
1052 gained support for several new Linux architectures (AMD64, s390x,
1053 SuperH), bi-architecture support for some of them, and received numer‐
1054 ous additions and improvements in syscalls decoders on Linux; strace
1055 development migrated to git during that period. Since 2009, strace is
1056 actively maintained by Dmitry Levin. strace gained support for
1057 AArch64, ARC, AVR32, Blackfin, Meta, Nios II, OpenRISC 1000, RISC-V,
1058 Tile/TileGx, Xtensa architectures since that time. In 2012, unmain‐
1059 tained and apparently broken support for non-Linux operating systems
1060 was removed. Also, in 2012 strace gained support for path tracing and
1061 file descriptor path decoding. In 2014, support for stack traces
1062 printing was added. In 2016, syscall fault injection was implemented.
1063 For the additional information, please refer to the NEWS file and
1065 strace repository commit log.
1066
1068 Problems with strace should be reported to the strace mailing list
1069 ⟨mailto:strace-devel@lists.strace.io⟩.
1070
1072 strace-log-merge(1), ltrace(1), perf-trace(1), trace-cmd(1), time(1),
1073 ptrace(2), proc(5)
1074 strace Home Page ⟨https://strace.io/⟩
1076
1078 The complete list of strace contributors can be found in the CREDITS
1079 file.
1080strace 5.10 2020-11-29 STRACE(1)