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] [--secontext[=format]] { -p pid | [-DDD]
13 [-E var[=val]]... [-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 in‐
35 terface, 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 ar‐
67 ranges 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) li‐
118 brary 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), secontext, decode-fds
156 (or decode-fd), decode-pids (or decode-pid), or kvm, and
157 value is a qualifier-dependent symbol or number. The de‐
158 fault qualifier is trace. Using an exclamation mark
159 negates the set of values. For example, -e open means lit‐
160 erally -e trace=open which in turn means trace only the
161 open system call. By contrast, -e trace=!open means to
162 trace every system call except open. In addition, the spe‐
163 cial values all and none have 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).
188 Multiple process IDs, separated by either comma (“,”),
189 space (“ ”), tab, or newline character, can be provided as
190 an argument to a single -p option, so, for example, -p
191 "$(pidof PROG)" and -p "$(pgrep PROG)" syntaxes are sup‐
192 ported.
193 -u username
195 --user=username
196 Run command with the user ID, group ID, and supplementary
197 groups of username. This option is only useful when run‐
198 ning as root and enables the correct execution of setuid
199 and/or setgid binaries. Unless this option is used setuid
200 and setgid programs are executed without effective privi‐
201 leges.
202 Tracing
204 -b syscall
205 --detach-on=syscall
206 If specified syscall is reached, detach from traced
207 process. Currently, only execve(2) syscall is supported.
208 This option is useful if you want to trace multi-threaded
209 process and therefore require -f, but don't want to trace
210 its (potentially very complex) children.
211 -D
213 --daemonize
214 --daemonize=grandchild
215 Run tracer process as a grandchild, not as the parent of
216 the tracee. This reduces the visible effect of strace by
217 keeping the tracee a direct child of the calling process.
218 -DD
220 --daemonize=pgroup
221 --daemonize=pgrp
222 Run tracer process as tracee's grandchild in a separate
223 process group. In addition to reduction of the visible ef‐
224 fect of strace, it also avoids killing of strace with
225 kill(2) issued to the whole process group.
226 -DDD
228 --daemonize=session
229 Run tracer process as tracee's grandchild in a separate
230 session ("true daemonisation"). In addition to reduction
231 of the visible effect of strace, it also avoids killing of
232 strace upon session termination.
233 -f
235 --follow-forks
236 Trace child processes as they are created by currently
237 traced processes as a result of the fork(2), vfork(2) and
238 clone(2) system calls. Note that -p PID -f will attach all
239 threads of process PID if it is multi-threaded, not only
240 thread with thread_id = PID.
241 --output-separately
243 If the --output=filename option is in effect, each pro‐
244 cesses trace is written to filename.pid where pid is the
245 numeric process id of each process.
246 -ff
248 --follow-forks --output-separately
249 Combine the effects of --follow-forks and --output-sepa‐
250 rately options. This is incompatible with -c, since no
251 per-process counts are kept.
252 One might want to consider using strace-log-merge(1) to ob‐
254 tain a combined strace log view.
255 -I interruptible
257 --interruptible=interruptible
258 When strace can be interrupted by signals (such as pressing
259 CTRL-C).
260 1, anywhere no signals are blocked;
262 2, waiting fatal signals are blocked while decoding
263 syscall (default);
264 3, never fatal signals are always blocked (default if
265 -o FILE PROG);
266 4, never_tstp fatal signals and SIGTSTP (CTRL-Z) are al‐
267 ways blocked (useful to make strace -o FILE
268 PROG not stop on CTRL-Z, default if -D).
269 Filtering
271 -e trace=syscall_set
272 --trace=syscall_set
273 Trace only the specified set of system calls. syscall_set
274 is defined as [!]value[,value], and value can be one of the
275 following:
276 syscall Trace specific syscall, specified by its name
278 (but see NOTES).
279 ?value Question mark before the syscall qualification
281 allows suppression of error in case no
282 syscalls matched the qualification provided.
283 /regex Trace only those system calls that match the
285 regex. You can use POSIX Extended Regular Ex‐
286 pression syntax (see regex(7)).
287 syscall@64 Trace syscall only for the 64-bit personality.
289 syscall@32 Trace syscall only for the 32-bit personality.
291 syscall@x32 Trace syscall only for the 32-on-64-bit per‐
293 sonality.
294 %file
296 file Trace all system calls which take a file name
297 as an argument. You can think of this as an
298 abbreviation for -e trace=open,stat,chmod,un‐
299 link,... which is useful to seeing what files
300 the process is referencing. Furthermore, us‐
301 ing the abbreviation will ensure that you
302 don't accidentally forget to include a call
303 like lstat(2) in the list. Betchya woulda
304 forgot that one. The syntax without a preced‐
305 ing percent sign ("-e trace=file") is depre‐
306 cated.
307 %process
309 process Trace system calls associated with process
310 lifecycle (creation, exec, termination). The
311 syntax without a preceding percent sign ("-e
312 trace=process") is deprecated.
313 %net
315 %network
316 network Trace all the network related system calls.
317 The syntax without a preceding percent sign
318 ("-e trace=network") is deprecated.
319 %signal
321 signal Trace all signal related system calls. The
322 syntax without a preceding percent sign ("-e
323 trace=signal") is deprecated.
324 %ipc
326 ipc Trace all IPC related system calls. The syn‐
327 tax without a preceding percent sign ("-e
328 trace=ipc") is deprecated.
329 %desc
331 desc Trace all file descriptor related system
332 calls. The syntax without a preceding percent
333 sign ("-e trace=desc") is deprecated.
334 %memory
336 memory Trace all memory mapping related system calls.
337 The syntax without a preceding percent sign
338 ("-e trace=memory") is deprecated.
339 %creds Trace system calls that read or modify user
341 and group identifiers or capability sets.
342 %stat Trace stat syscall variants.
344 %lstat Trace lstat syscall variants.
346 %fstat Trace fstat, fstatat, and statx syscall vari‐
348 ants.
349 %%stat Trace syscalls used for requesting file status
351 (stat, lstat, fstat, fstatat, statx, and their
352 variants).
353 %statfs Trace statfs, statfs64, statvfs, osf_statfs,
355 and osf_statfs64 system calls. The same ef‐
356 fect can be achieved with
357 -e trace=/^(.*_)?statv?fs regular expression.
358 %fstatfs Trace fstatfs, fstatfs64, fstatvfs, osf_fs‐
360 tatfs, and osf_fstatfs64 system calls. The
361 same effect can be achieved with -e trace=/fs‐
362 tatv?fs regular expression.
363 %%statfs Trace syscalls related to file system statis‐
365 tics (statfs-like, fstatfs-like, and ustat).
366 The same effect can be achieved with
367 -e trace=/statv?fs|fsstat|ustat regular ex‐
368 pression.
369 %clock Trace system calls that read or modify system
371 clocks.
372 %pure Trace syscalls that always succeed and have no
374 arguments. Currently, this list includes
375 arc_gettls(2), getdtablesize(2), getegid(2),
376 getegid32(2), geteuid(2), geteuid32(2), get‐
377 gid(2), getgid32(2), getpagesize(2), getp‐
378 grp(2), getpid(2), getppid(2),
379 get_thread_area(2) (on architectures other
380 than x86), gettid(2), get_tls(2), getuid(2),
381 getuid32(2), getxgid(2), getxpid(2),
382 getxuid(2), kern_features(2), and
383 metag_get_tls(2) syscalls.
384 The -c option is useful for determining which system calls
386 might be useful to trace. For example,
387 trace=open,close,read,write means to only trace those four
388 system calls. Be careful when making inferences about the
389 user/kernel boundary if only a subset of system calls are
390 being monitored. The default is trace=all.
391 -e signal=set
393 --signal=set
394 Trace only the specified subset of signals. The default is
395 signal=all. For example, signal=!SIGIO (or signal=!io)
396 causes SIGIO signals not to be traced.
397 -e status=set
399 --status=set
400 Print only system calls with the specified return status.
401 The default is status=all. When using the status quali‐
402 fier, because strace waits for system calls to return be‐
403 fore deciding whether they should be printed or not, the
404 traditional order of events may not be preserved anymore.
405 If two system calls are executed by concurrent threads,
406 strace will first print both the entry and exit of the
407 first system call to exit, regardless of their respective
408 entry time. The entry and exit of the second system call
409 to exit will be printed afterwards. Here is an example
410 when select(2) is called, but a different thread calls
411 clock_gettime(2) before select(2) finishes:
412 [pid 28779] 1130322148.939977 clock_gettime(CLOCK_REALTIME, {1130322148, 939977000}) = 0
414 [pid 28772] 1130322148.438139 select(4, [3], NULL, NULL, NULL) = 1 (in [3])
415 set can include the following elements:
417 successful Trace system calls that returned without an
419 error code. The -z option has the effect of
420 status=successful.
421 failed Trace system calls that returned with an error
422 code. The -Z option has the effect of sta‐
423 tus=failed.
424 unfinished Trace system calls that did not return. This
425 might happen, for example, due to an execve
426 call in a neighbour thread.
427 unavailable Trace system calls that returned but strace
428 failed to fetch the error status.
429 detached Trace system calls for which strace detached
430 before the return.
431 -P path
433 --trace-path=path
434 Trace only system calls accessing path. Multiple -P op‐
435 tions can be used to specify several paths.
436 -z
438 --successful-only
439 Print only syscalls that returned without an error code.
440 -Z
442 --failed-only
443 Print only syscalls that returned with an error code.
444 Output format
446 -a column
447 --columns=column
448 Align return values in a specific column (default column
449 40).
450 -e abbrev=syscall_set
452 --abbrev=syscall_set
453 Abbreviate the output from printing each member of large
454 structures. The syntax of the syscall_set specification is
455 the same as in the -e trace option. The default is ab‐
456 brev=all. The -v option has the effect of abbrev=none.
457 -e verbose=syscall_set
459 --verbose=syscall_set
460 Dereference structures for the specified set of system
461 calls. The syntax of the syscall_set specification is the
462 same as in the -e trace option. The default is ver‐
463 bose=all.
464 -e raw=syscall_set
466 --raw=syscall_set
467 Print raw, undecoded arguments for the specified set of
468 system calls. The syntax of the syscall_set specification
469 is the same as in the -e trace option. This option has the
470 effect of causing all arguments to be printed in hexadeci‐
471 mal. This is mostly useful if you don't trust the decoding
472 or you need to know the actual numeric value of an argu‐
473 ment. See also -X raw option.
474 -e read=set
476 --read=set Perform a full hexadecimal and ASCII dump of all the data
477 read from file descriptors listed in the specified set.
478 For example, to see all input activity on file descriptors
479 3 and 5 use -e read=3,5. Note that this is independent
480 from the normal tracing of the read(2) system call which is
481 controlled by the option -e trace=read.
482 -e write=set
484 --write=set Perform a full hexadecimal and ASCII dump of all the data
485 written to file descriptors listed in the specified set.
486 For example, to see all output activity on file descriptors
487 3 and 5 use -e write=3,5. Note that this is independent
488 from the normal tracing of the write(2) system call which
489 is controlled by the option -e trace=write.
490 -e quiet=set
492 --quiet=set
493 --silent=set
494 --silence=set
495 Suppress various information messages. The default is
496 quiet=none. set can include the following elements:
497 attach Suppress messages about attaching and de‐
499 taching ("[ Process NNNN attached ]", "[
500 Process NNNN detached ]").
501 exit Suppress messages about process exits
502 ("+++ exited with SSS +++").
503 path-resolution Suppress messages about resolution of
504 paths provided via the -P option ("Re‐
505 quested path "..." resolved into "..."").
506 personality Suppress messages about process personal‐
507 ity changes ("[ Process PID=NNNN runs in
508 PPP mode. ]").
509 thread-execve
510 superseded Suppress messages about process being su‐
511 perseded by execve(2) in another thread
512 ("+++ superseded by execve in pid NNNN
513 +++").
514 -e decode-fds=set
516 --decode-fds=set
517 Decode various information associated with file descrip‐
518 tors. The default is decode-fds=none. set can include the
519 following elements:
520 path Print file paths. Also enables printing of
522 tracee's current working directory when AT_FDCWD
523 constant is used.
524 socket Print socket protocol-specific information,
525 dev Print character/block device numbers.
526 pidfd Print PIDs associated with pidfd file descriptors.
527 -e decode-pids=set
529 --decode-pids=set
530 Decode various information associated with process IDs (and
531 also thread IDs, process group IDs, and session IDs). The
532 default is decode-pids=none. set can include the following
533 elements:
534 comm Print command names associated with thread or
536 process IDs.
537 pidns Print thread, process, process group, and session
538 IDs in strace's PID namespace if the tracee is in a
539 different PID namespace.
540 -e kvm=vcpu
542 --kvm=vcpu Print the exit reason of kvm vcpu. Requires Linux kernel
543 version 4.16.0 or higher.
544 -i
546 --instruction-pointer
547 Print the instruction pointer at the time of the system
548 call.
549 -n
551 --syscall-number
552 Print the syscall number.
553 -k
555 --stack-traces
556 Print the execution stack trace of the traced processes af‐
557 ter each system call.
558 -o filename
560 --output=filename
561 Write the trace output to the file filename rather than to
562 stderr. filename.pid form is used if -ff option is sup‐
563 plied. If the argument begins with '|' or '!', the rest of
564 the argument is treated as a command and all output is
565 piped to it. This is convenient for piping the debugging
566 output to a program without affecting the redirections of
567 executed programs. The latter is not compatible with -ff
568 option currently.
569 -A
571 --output-append-mode
572 Open the file provided in the -o option in append mode.
573 -q
575 --quiet
576 --quiet=attach,personality
577 Suppress messages about attaching, detaching, and personal‐
578 ity changes. This happens automatically when output is
579 redirected to a file and the command is run directly in‐
580 stead of attaching.
581 -qq
583 --quiet=attach,personality,exit
584 Suppress messages attaching, detaching, personality
585 changes, and about process exit status.
586 -qqq
588 --quiet=all Suppress all suppressible messages (please refer to the -e
589 quiet option description for the full list of suppressible
590 messages).
591 -r
593 --relative-timestamps[=precision]
594 Print a relative timestamp upon entry to each system call.
595 This records the time difference between the beginning of
596 successive system calls. precision can be one of s (for
597 seconds), ms (milliseconds), us (microseconds), or ns
598 (nanoseconds), and allows setting the precision of time
599 value being printed. Default is us (microseconds). Note
600 that since -r option uses the monotonic clock time for mea‐
601 suring time difference and not the wall clock time, its
602 measurements can differ from the difference in time re‐
603 ported by the -t option.
604 -s strsize
606 --string-limit=strsize
607 Specify the maximum string size to print (the default is
608 32). Note that filenames are not considered strings and
609 are always printed in full.
610 --absolute-timestamps[=[[format:]format],[[precision:]precision]]
612 --timestamps[=[[format:]format],[[precision:]precision]]
613 Prefix each line of the trace with the wall clock time in
614 the specified format with the specified precision. format
615 can be one of the following:
616 none No time stamp is printed. Can be used to
618 override the previous setting.
619 time Wall clock time (strftime(3) format string is
620 %T).
621 unix Number of seconds since the epoch (strf‐
622 time(3) format string is %s).
623 precision can be one of s (for seconds), ms (milliseconds),
625 us (microseconds), or ns (nanoseconds). Default arguments
626 for the option are format:time,precision:s.
627 -t
629 --absolute-timestamps
630 Prefix each line of the trace with the wall clock time.
631 -tt
633 --absolute-timestamps=precision:us
634 If given twice, the time printed will include the microsec‐
635 onds.
636 -ttt
638 --absolute-timestamps=format:unix,precision:us
639 If given thrice, the time printed will include the mi‐
640 croseconds and the leading portion will be printed as the
641 number of seconds since the epoch.
642 -T
644 --syscall-times[=precision]
645 Show the time spent in system calls. This records the time
646 difference between the beginning and the end of each system
647 call. precision can be one of s (for seconds), ms (mil‐
648 liseconds), us (microseconds), or ns (nanoseconds), and al‐
649 lows setting the precision of time value being printed.
650 Default is us (microseconds).
651 -v
653 --no-abbrev Print unabbreviated versions of environment, stat, termios,
654 etc. calls. These structures are very common in calls and
655 so the default behavior displays a reasonable subset of
656 structure members. Use this option to get all of the gory
657 details.
658 --strings-in-hex[=option]
660 Control usage of escape sequences with hexadecimal numbers
661 in the printed strings. Normally (when no --strings-in-hex
662 or -x option is supplied), escape sequences are used to
663 print non-printable and non-ASCII characters (that is,
664 characters with a character code less than 32 or greater
665 than 127), or to disambiguate the output (so, for quotes
666 and other characters that encase the printed string, for
667 example, angle brackets, in case of file descriptor path
668 output); for the former use case, unless it is a white
669 space character that has a symbolic escape sequence defined
670 in the C standard (that is, “\t” for a horizontal tab, “\n”
671 for a newline, “\v” for a vertical tab, “\f” for a form
672 feed page break, and “\r” for a carriage return) are
673 printed using escape sequences with numbers that correspond
674 to their byte values, with octal number format being the
675 default. option can be one of the following:
676 none Hexadecimal numbers are not used in the
678 output at all. When there is a need to
679 emit an escape sequence, octal numbers are
680 used.
681 non-ascii-chars Hexadecimal numbers are used instead of
682 octal in the escape sequences.
683 non-ascii Strings that contain non-ASCII characters
684 are printed using escape sequences with
685 hexadecimal numbers.
686 all All strings are printed using escape se‐
687 quences with hexadecimal numbers.
688 When the option is supplied without an argument, all is as‐
690 sumed.
691 -x
693 --strings-in-hex=non-ascii
694 Print all non-ASCII strings in hexadecimal string format.
695 -xx
697 --strings-in-hex[=all]
698 Print all strings in hexadecimal string format.
699 -X format
701 --const-print-style=format
702 Set the format for printing of named constants and flags.
703 Supported format values are:
704 raw Raw number output, without decoding.
706 abbrev Output a named constant or a set of flags instead
707 of the raw number if they are found. This is the
708 default strace behaviour.
709 verbose Output both the raw value and the decoded string
710 (as a comment).
711 -y
713 --decode-fds
714 --decode-fds=path
715 Print paths associated with file descriptor arguments and
716 with the AT_FDCWD constant.
717 -yy
719 --decode-fds=all
720 Print all available information associated with file de‐
721 scriptors: protocol-specific information associated with
722 socket file descriptors, block/character device number as‐
723 sociated with device file descriptors, and PIDs associated
724 with pidfd file descriptors.
725 --pidns-translation
727 --decode-pids=pidns
728 If strace and tracee are in different PID namespaces, print
729 PIDs in strace's namespace, too.
730 -Y
732 --decode-pids=comm
733 Print command names for PIDs.
734 --secontext[=format]
736 -e secontext=format
737 When SELinux is available and is not disabled, print in
738 square brackets SELinux contexts of processes, files, and
739 descriptors. The format argument is a comma-separated list
740 of items being one of the following:
741 full Print the full context (user, role, type
743 level and category).
744 mismatch Also print the context recorded by the
745 SELinux database in case the current con‐
746 text differs. The latter is printed af‐
747 ter two exclamation marks (!!).
748 The default value for --secontext is !full,mismatch which
750 prints only the type instead of full context and doesn't
751 check for context mismatches.
752 Statistics
754 -c
755 --summary-only
756 Count time, calls, and errors for each system call and re‐
757 port a summary on program exit, suppressing the regular
758 output. This attempts to show system time (CPU time spent
759 running in the kernel) independent of wall clock time. If
760 -c is used with -f, only aggregate totals for all traced
761 processes are kept.
762 -C
764 --summary Like -c but also print regular output while processes are
765 running.
766 -O overhead
768 --summary-syscall-overhead=overhead
769 Set the overhead for tracing system calls to overhead.
770 This is useful for overriding the default heuristic for
771 guessing how much time is spent in mere measuring when tim‐
772 ing system calls using the -c option. The accuracy of the
773 heuristic can be gauged by timing a given program run with‐
774 out tracing (using time(1)) and comparing the accumulated
775 system call time to the total produced using -c.
776 The format of overhead specification is described in sec‐
778 tion Time specification format description.
779 -S sortby
781 --summary-sort-by=sortby
782 Sort the output of the histogram printed by the -c option
783 by the specified criterion. Legal values are time (or
784 time-percent or time-total or total-time), min-time (or
785 shortest or time-min), max-time (or longest or time-max),
786 avg-time (or time-avg), calls (or count), errors (or er‐
787 ror), name (or syscall or syscall-name), and nothing (or
788 none); default is time.
789 -U columns
791 --summary-columns=columns
792 Configure a set (and order) of columns being shown in the
793 call summary. The columns argument is a comma-separated
794 list with items being one of the following:
795 time-percent (or time) Percentage of cumula‐
797 tive time consumed by a
798 specific system call.
799 total-time (or time-total) Total system (or wall
800 clock, if -w option is
801 provided) time consumed
802 by a specific system
803 call.
804 min-time (or shortest or time-min) Minimum observed call
805 duration.
806 max-time (or longest or time-max) Maximum observed call
807 duration.
808 avg-time (or time-avg) Average call duration.
809 calls (or count) Call count.
810 errors (or error) Error count.
811 name (or syscall or syscall-name) Syscall name.
812 The default value is time-percent,to‐
814 tal-time,avg-time,calls,errors,name. If the name field is
815 not supplied explicitly, it is added as the last column.
816 -w
818 --summary-wall-clock
819 Summarise the time difference between the beginning and end
820 of each system call. The default is to summarise the sys‐
821 tem time.
822 Tampering
824 -e inject=syscall_set[:error=errno|:retval=value][:sig‐
825 nal=sig][:syscall=syscall][:delay_enter=delay][:delay_exit=de‐
826 lay][:poke_en‐
827 ter=@argN=DATAN,@argM=DATAM...][:poke_exit=@argN=DATAN,@argM=DATAM...][:when=expr]
828 --inject=syscall_set[:error=errno|:retval=value][:sig‐
829 nal=sig][:syscall=syscall][:delay_en‐
830 ter=delay][:delay_exit=delay][:poke_en‐
831 ter=@argN=DATAN,@argM=DATAM...][:poke_exit=@argN=DATAN,@argM=DATAM...][:when=expr]
832 Perform syscall tampering for the specified set of
833 syscalls. The syntax of the syscall_set specification is
834 the same as in the -e trace option.
835 At least one of error, retval, signal, delay_enter, de‐
837 lay_exit, poke_enter, or poke_exit options has to be speci‐
838 fied. error and retval are mutually exclusive.
839 If :error=errno option is specified, a fault is injected
841 into a syscall invocation: the syscall number is replaced
842 by -1 which corresponds to an invalid syscall (unless a
843 syscall is specified with :syscall= option), and the error
844 code is specified using a symbolic errno value like ENOSYS
845 or a numeric value within 1..4095 range.
846 If :retval=value option is specified, success injection is
848 performed: the syscall number is replaced by -1, but a bo‐
849 gus success value is returned to the callee.
850 If :signal=sig option is specified with either a symbolic
852 value like SIGSEGV or a numeric value within 1..SIGRTMAX
853 range, that signal is delivered on entering every syscall
854 specified by the set.
855 If :delay_enter=delay or :delay_exit=delay options are
857 specified, delay injection is performed: the tracee is de‐
858 layed by time period specified by delay on entering or ex‐
859 iting the syscall, respectively. The format of delay spec‐
860 ification is described in section Time specification format
861 description.
862 If :poke_enter=@argN=DATAN,@argM=DATAM... or
864 :poke_exit=@argN=DATAN,@argM=DATAM... options are speci‐
865 fied, tracee's memory at locations, pointed to by system
866 call arguments argN and argM (going from arg1 to arg7) is
867 overwritten by data DATAN and DATAM (specified in hexadeci‐
868 mal format; for example :poke_en‐
869 ter=@arg1=0000DEAD0000BEEF). :poke_enter modifies memory
870 on syscall enter, and :poke_exit - on exit.
871 If :signal=sig option is specified without :error=errno,
873 :retval=value or :delay_{enter,exit}=usecs options, then
874 only a signal sig is delivered without a syscall fault or
875 delay injection. Conversely, :error=errno or :retval=value
876 option without :delay_enter=delay, :delay_exit=delay or
877 :signal=sig options injects a fault without delivering a
878 signal or injecting a delay, etc.
879 If :signal=sig option is specified together with :error=er‐
881 rno or :retval=value, then both injection of a fault or
882 success and signal delivery are performed.
883 if :syscall=syscall option is specified, the corresponding
885 syscall with no side effects is injected instead of -1.
886 Currently, only "pure" (see -e trace=%pure description)
887 syscalls can be specified there.
888 Unless a :when=expr subexpression is specified, an injec‐
890 tion is being made into every invocation of each syscall
891 from the set.
892 The format of the subexpression is:
894 first[..last][+[step]]
896 Number first stands for the first invocation number in the
898 range, number last stands for the last invocation number in
899 the range, and step stands for the step between two consec‐
900 utive invocations. The following combinations are useful:
901 first For every syscall from the set, perform
903 an injection for the syscall invocation
904 number first only.
905 first..last For every syscall from the set, perform
906 an injection for the syscall invocation
907 number first and all subsequent invoca‐
908 tions until the invocation number last
909 (inclusive).
910 first+ For every syscall from the set, perform
911 injections for the syscall invocation
912 number first and all subsequent invoca‐
913 tions.
914 first..last+ For every syscall from the set, perform
915 injections for the syscall invocation
916 number first and all subsequent invoca‐
917 tions until the invocation number last
918 (inclusive).
919 first+step For every syscall from the set, perform
920 injections for syscall invocations number
921 first, first+step, first+step+step, and
922 so on.
923 first..last+step Same as the previous, but consider only
924 syscall invocations with numbers up to
925 last (inclusive).
926 For example, to fail each third and subsequent chdir
928 syscalls with ENOENT, use -e inject=chdir:er‐
929 ror=ENOENT:when=3+.
930 The valid range for numbers first and step is 1..65535, and
932 for number last is 1..65534.
933 An injection expression can contain only one error= or ret‐
935 val= specification, and only one signal= specification. If
936 an injection expression contains multiple when= specifica‐
937 tions, the last one takes precedence.
938 Accounting of syscalls that are subject to injection is
940 done per syscall and per tracee.
941 Specification of syscall injection can be combined with
943 other syscall filtering options, for example, -P /dev/uran‐
944 dom -e inject=file:error=ENOENT.
945 -e fault=syscall_set[:error=errno][:when=expr]
947 --fault=syscall_set[:error=errno][:when=expr]
948 Perform syscall fault injection for the specified set of
949 syscalls.
950 This is equivalent to more generic -e inject= expression
952 with default value of errno option set to ENOSYS.
953 Miscellaneous
955 -d
956 --debug Show some debugging output of strace itself on the standard
957 error.
958 -F This option is deprecated. It is retained for backward
960 compatibility only and may be removed in future releases.
961 Usage of multiple instances of -F option is still equiva‐
962 lent to a single -f, and it is ignored at all if used along
963 with one or more instances of -f option.
964 -h
966 --help Print the help summary.
967 --seccomp-bpf
969 Try to enable use of seccomp-bpf (see seccomp(2)) to have
970 ptrace(2)-stops only when system calls that are being
971 traced occur in the traced processes. This option has no
972 effect unless -f/--follow-forks is also specified. --sec‐
973 comp-bpf is also not applicable to processes attached using
974 -p/--attach option. An attempt to enable system calls fil‐
975 tering using seccomp-bpf may fail for various reasons, e.g.
976 there are too many system calls to filter, the seccomp API
977 is not available, or strace itself is being traced. In
978 cases when seccomp-bpf filter setup failed, strace proceeds
979 as usual and stops traced processes on every system call.
980 -V
982 --version Print the version number of strace.
983 Time specification format description
985 Time values can be specified as a decimal floating point number (in a
986 format accepted by strtod(3)), optionally followed by one of the fol‐
987 lowing suffices that specify the unit of time: s (seconds), ms (mil‐
988 liseconds), us (microseconds), or ns (nanoseconds). If no suffix is
989 specified, the value is interpreted as microseconds.
990 The described format is used for -O, -e inject=delay_enter, and -e in‐
992 ject=delay_exit options.
993
995 When command exits, strace exits with the same exit status. If command
996 is terminated by a signal, strace terminates itself with the same sig‐
997 nal, so that strace can be used as a wrapper process transparent to the
998 invoking parent process. Note that parent-child relationship (signal
999 stop notifications, getppid(2) value, etc) between traced process and
1000 its parent are not preserved unless -D is used.
1001 When using -p without a command, the exit status of strace is zero un‐
1003 less no processes has been attached or there was an unexpected error in
1004 doing the tracing.
1005
1007 If strace is installed setuid to root then the invoking user will be
1008 able to attach to and trace processes owned by any user. In addition
1009 setuid and setgid programs will be executed and traced with the correct
1010 effective privileges. Since only users trusted with full root privi‐
1011 leges should be allowed to do these things, it only makes sense to in‐
1012 stall strace as setuid to root when the users who can execute it are
1013 restricted to those users who have this trust. For example, it makes
1014 sense to install a special version of strace with mode 'rwsr-xr--',
1015 user root and group trace, where members of the trace group are trusted
1016 users. If you do use this feature, please remember to install a regu‐
1017 lar non-setuid version of strace for ordinary users to use.
1018
1020 On some architectures, strace supports decoding of syscalls for pro‐
1021 cesses that use different ABI rather than the one strace uses. Specif‐
1022 ically, in addition to decoding native ABI, strace can decode the fol‐
1023 lowing ABIs on the following architectures:
1024 ┌───────────────────┬─────────────────────────┐
1026 │Architecture │ ABIs supported │
1027 ├───────────────────┼─────────────────────────┤
1028 │x86_64 │ i386, x32 [1]; i386 [2] │
1029 ├───────────────────┼─────────────────────────┤
1030 │AArch64 │ ARM 32-bit EABI │
1031 ├───────────────────┼─────────────────────────┤
1032 │PowerPC 64-bit [3] │ PowerPC 32-bit │
1033 ├───────────────────┼─────────────────────────┤
1034 │s390x │ s390 │
1035 ├───────────────────┼─────────────────────────┤
1036 │SPARC 64-bit │ SPARC 32-bit │
1037 ├───────────────────┼─────────────────────────┤
1038 │TILE 64-bit │ TILE 32-bit │
1039 └───────────────────┴─────────────────────────┘
1040 [1] When strace is built as an x86_64 application
1041 [2] When strace is built as an x32 application
1042 [3] Big endian only
1043 This support is optional and relies on ability to generate and parse
1045 structure definitions during the build time. Please refer to the out‐
1046 put of the strace -V command in order to figure out what support is
1047 available in your strace build ("non-native" refers to an ABI that dif‐
1048 fers from the ABI strace has):
1049 m32-mpers strace can trace and properly decode non-native 32-bit
1051 binaries.
1052 no-m32-mpers strace can trace, but cannot properly decode non-native
1053 32-bit binaries.
1054 mx32-mpers strace can trace and properly decode non-native
1055 32-on-64-bit binaries.
1056 no-mx32-mpers strace can trace, but cannot properly decode non-native
1057 32-on-64-bit binaries.
1058 If the output contains neither m32-mpers nor no-m32-mpers, then decod‐
1060 ing of non-native 32-bit binaries is not implemented at all or not ap‐
1061 plicable.
1062 Likewise, if the output contains neither mx32-mpers nor no-mx32-mpers,
1064 then decoding of non-native 32-on-64-bit binaries is not implemented at
1065 all or not applicable.
1066
1068 It is a pity that so much tracing clutter is produced by systems em‐
1069 ploying shared libraries.
1070 It is instructive to think about system call inputs and outputs as
1072 data-flow across the user/kernel boundary. Because user-space and ker‐
1073 nel-space are separate and address-protected, it is sometimes possible
1074 to make deductive inferences about process behavior using inputs and
1075 outputs as propositions.
1076 In some cases, a system call will differ from the documented behavior
1078 or have a different name. For example, the faccessat(2) system call
1079 does not have flags argument, and the setrlimit(2) library function
1080 uses prlimit64(2) system call on modern (2.6.38+) kernels. These dis‐
1081 crepancies are normal but idiosyncratic characteristics of the system
1082 call interface and are accounted for by C library wrapper functions.
1083 Some system calls have different names in different architectures and
1085 personalities. In these cases, system call filtering and printing uses
1086 the names that match corresponding __NR_* kernel macros of the tracee's
1087 architecture and personality. There are two exceptions from this gen‐
1088 eral rule: arm_fadvise64_64(2) ARM syscall and xtensa_fadvise64_64(2)
1089 Xtensa syscall are filtered and printed as fadvise64_64(2).
1090 On x32, syscalls that are intended to be used by 64-bit processes and
1092 not x32 ones (for example, readv(2), that has syscall number 19 on
1093 x86_64, with its x32 counterpart has syscall number 515), but called
1094 with __X32_SYSCALL_BIT flag being set, are designated with #64 suffix.
1095 On some platforms a process that is attached to with the -p option may
1097 observe a spurious EINTR return from the current system call that is
1098 not restartable. (Ideally, all system calls should be restarted on
1099 strace attach, making the attach invisible to the traced process, but a
1100 few system calls aren't. Arguably, every instance of such behavior is
1101 a kernel bug.) This may have an unpredictable effect on the process if
1102 the process takes no action to restart the system call.
1103 As strace executes the specified command directly and does not employ a
1105 shell for that, scripts without shebang that usually run just fine when
1106 invoked by shell fail to execute with ENOEXEC error. It is advisable
1107 to manually supply a shell as a command with the script as its argu‐
1108 ment.
1109
1111 Programs that use the setuid bit do not have effective user ID privi‐
1112 leges while being traced.
1113 A traced process runs slowly (but check out the --seccomp-bpf option).
1115 Traced processes which are descended from command may be left running
1117 after an interrupt signal (CTRL-C).
1118
1120 The original strace was written by Paul Kranenburg for SunOS and was
1121 inspired by its trace utility. The SunOS version of strace was ported
1122 to Linux and enhanced by Branko Lankester, who also wrote the Linux
1123 kernel support. Even though Paul released strace 2.5 in 1992, Branko's
1124 work was based on Paul's strace 1.5 release from 1991. In 1993, Rick
1125 Sladkey merged strace 2.5 for SunOS and the second release of strace
1126 for Linux, added many of the features of truss(1) from SVR4, and pro‐
1127 duced an strace that worked on both platforms. In 1994 Rick ported
1128 strace to SVR4 and Solaris and wrote the automatic configuration sup‐
1129 port. In 1995 he ported strace to Irix and tired of writing about him‐
1130 self in the third person.
1131 Beginning with 1996, strace was maintained by Wichert Akkerman. During
1133 his tenure, strace development migrated to CVS; ports to FreeBSD and
1134 many architectures on Linux (including ARM, IA-64, MIPS, PA-RISC, Pow‐
1135 erPC, s390, SPARC) were introduced. In 2002, the burden of strace
1136 maintainership was transferred to Roland McGrath. Since then, strace
1137 gained support for several new Linux architectures (AMD64, s390x, Su‐
1138 perH), bi-architecture support for some of them, and received numerous
1139 additions and improvements in syscalls decoders on Linux; strace devel‐
1140 opment migrated to git during that period. Since 2009, strace is ac‐
1141 tively maintained by Dmitry Levin. strace gained support for AArch64,
1142 ARC, AVR32, Blackfin, Meta, Nios II, OpenRISC 1000, RISC-V, Tile/Ti‐
1143 leGx, Xtensa architectures since that time. In 2012, unmaintained and
1144 apparently broken support for non-Linux operating systems was removed.
1145 Also, in 2012 strace gained support for path tracing and file descrip‐
1146 tor path decoding. In 2014, support for stack traces printing was
1147 added. In 2016, syscall fault injection was implemented.
1148 For the additional information, please refer to the NEWS file and
1150 strace repository commit log.
1151
1153 Problems with strace should be reported to the strace mailing list
1154 ⟨mailto:strace-devel@lists.strace.io⟩.
1155
1157 strace-log-merge(1), ltrace(1), perf-trace(1), trace-cmd(1), time(1),
1158 ptrace(2), proc(5)
1159 strace Home Page ⟨https://strace.io/⟩
1161
1163 The complete list of strace contributors can be found in the CREDITS
1164 file.
1165strace 5.16 2022-01-04 STRACE(1)