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, {tv_sec=1130322148, tv_nsec=3977000}) = 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 {si_signo=SIGALRM, si_code=SI_KERNEL} ---
71 rt_sigreturn({mask=[]}) = 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, pointers to basic
123 types and arrays are printed using square brackets with commas separat‐
124 ing the elements. Here is an example from the command id(1) on a sys‐
125 tem with supplementary 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 -e t=syscall_set
273 --trace=syscall_set
274 Trace only the specified set of system calls. syscall_set
275 is defined as [!]value[,value], and value can be one of the
276 following:
277 syscall Trace specific syscall, specified by its name
279 (see syscalls(2) for a reference, but also see
280 NOTES).
281 ?value Question mark before the syscall qualification
283 allows suppression of error in case no
284 syscalls matched the qualification provided.
285 value@64 Limit the syscall specification described by
287 value to 64-bit personality.
288 value@32 Limit the syscall specification described by
290 value to 32-bit personality.
291 value@x32 Limit the syscall specification described by
293 value to x32 personality.
294 all Trace all system calls.
296 /regex Trace only those system calls that match the
298 regex. You can use POSIX Extended Regular Ex‐
299 pression syntax (see regex(7)).
300 %file
302 file Trace all system calls which take a file name
303 as an argument. You can think of this as an
304 abbreviation for -e trace=open,stat,chmod,un‐
305 link,... which is useful to seeing what files
306 the process is referencing. Furthermore, us‐
307 ing the abbreviation will ensure that you
308 don't accidentally forget to include a call
309 like lstat(2) in the list. Betchya woulda
310 forgot that one. The syntax without a preced‐
311 ing percent sign ("-e trace=file") is depre‐
312 cated.
313 %process
315 process Trace system calls associated with process
316 lifecycle (creation, exec, termination). The
317 syntax without a preceding percent sign ("-e
318 trace=process") is deprecated.
319 %net
321 %network
322 network Trace all the network related system calls.
323 The syntax without a preceding percent sign
324 ("-e trace=network") is deprecated.
325 %signal
327 signal Trace all signal related system calls. The
328 syntax without a preceding percent sign ("-e
329 trace=signal") is deprecated.
330 %ipc
332 ipc Trace all IPC related system calls. The syn‐
333 tax without a preceding percent sign ("-e
334 trace=ipc") is deprecated.
335 %desc
337 desc Trace all file descriptor related system
338 calls. The syntax without a preceding percent
339 sign ("-e trace=desc") is deprecated.
340 %memory
342 memory Trace all memory mapping related system calls.
343 The syntax without a preceding percent sign
344 ("-e trace=memory") is deprecated.
345 %creds Trace system calls that read or modify user
347 and group identifiers or capability sets.
348 %stat Trace stat syscall variants.
350 %lstat Trace lstat syscall variants.
352 %fstat Trace fstat, fstatat, and statx syscall vari‐
354 ants.
355 %%stat Trace syscalls used for requesting file status
357 (stat, lstat, fstat, fstatat, statx, and their
358 variants).
359 %statfs Trace statfs, statfs64, statvfs, osf_statfs,
361 and osf_statfs64 system calls. The same ef‐
362 fect can be achieved with
363 -e trace=/^(.*_)?statv?fs regular expression.
364 %fstatfs Trace fstatfs, fstatfs64, fstatvfs, osf_fs‐
366 tatfs, and osf_fstatfs64 system calls. The
367 same effect can be achieved with -e trace=/fs‐
368 tatv?fs regular expression.
369 %%statfs Trace syscalls related to file system statis‐
371 tics (statfs-like, fstatfs-like, and ustat).
372 The same effect can be achieved with
373 -e trace=/statv?fs|fsstat|ustat regular ex‐
374 pression.
375 %clock Trace system calls that read or modify system
377 clocks.
378 %pure Trace syscalls that always succeed and have no
380 arguments. Currently, this list includes
381 arc_gettls(2), getdtablesize(2), getegid(2),
382 getegid32(2), geteuid(2), geteuid32(2), get‐
383 gid(2), getgid32(2), getpagesize(2), getp‐
384 grp(2), getpid(2), getppid(2),
385 get_thread_area(2) (on architectures other
386 than x86), gettid(2), get_tls(2), getuid(2),
387 getuid32(2), getxgid(2), getxpid(2),
388 getxuid(2), kern_features(2), and
389 metag_get_tls(2) syscalls.
390 The -c option is useful for determining which system calls
392 might be useful to trace. For example,
393 trace=open,close,read,write means to only trace those four
394 system calls. Be careful when making inferences about the
395 user/kernel boundary if only a subset of system calls are
396 being monitored. The default is trace=all.
397 -e signal=set
399 -e signals=set
400 -e s=set
401 --signal=set
402 Trace only the specified subset of signals. The default is
403 signal=all. For example, signal=!SIGIO (or signal=!io)
404 causes SIGIO signals not to be traced.
405 -e status=set
407 --status=set
408 Print only system calls with the specified return status.
409 The default is status=all. When using the status quali‐
410 fier, because strace waits for system calls to return be‐
411 fore deciding whether they should be printed or not, the
412 traditional order of events may not be preserved anymore.
413 If two system calls are executed by concurrent threads,
414 strace will first print both the entry and exit of the
415 first system call to exit, regardless of their respective
416 entry time. The entry and exit of the second system call
417 to exit will be printed afterwards. Here is an example
418 when select(2) is called, but a different thread calls
419 clock_gettime(2) before select(2) finishes:
420 [pid 28779] 1130322148.939977 clock_gettime(CLOCK_REALTIME, {1130322148, 939977000}) = 0
422 [pid 28772] 1130322148.438139 select(4, [3], NULL, NULL, NULL) = 1 (in [3])
423 set can include the following elements:
425 successful Trace system calls that returned without an
427 error code. The -z option has the effect of
428 status=successful.
429 failed Trace system calls that returned with an error
430 code. The -Z option has the effect of sta‐
431 tus=failed.
432 unfinished Trace system calls that did not return. This
433 might happen, for example, due to an execve
434 call in a neighbour thread.
435 unavailable Trace system calls that returned but strace
436 failed to fetch the error status.
437 detached Trace system calls for which strace detached
438 before the return.
439 -P path
441 --trace-path=path
442 Trace only system calls accessing path. Multiple -P op‐
443 tions can be used to specify several paths.
444 -z
446 --successful-only
447 Print only syscalls that returned without an error code.
448 -Z
450 --failed-only
451 Print only syscalls that returned with an error code.
452 Output format
454 -a column
455 --columns=column
456 Align return values in a specific column (default column
457 40).
458 -e abbrev=syscall_set
460 -e a=syscall_set
461 --abbrev=syscall_set
462 Abbreviate the output from printing each member of large
463 structures. The syntax of the syscall_set specification is
464 the same as in the -e trace option. The default is ab‐
465 brev=all. The -v option has the effect of abbrev=none.
466 -e verbose=syscall_set
468 -e v=syscall_set
469 --verbose=syscall_set
470 Dereference structures for the specified set of system
471 calls. The syntax of the syscall_set specification is the
472 same as in the -e trace option. The default is ver‐
473 bose=all.
474 -e raw=syscall_set
476 -e x=syscall_set
477 --raw=syscall_set
478 Print raw, undecoded arguments for the specified set of
479 system calls. The syntax of the syscall_set specification
480 is the same as in the -e trace option. This option has the
481 effect of causing all arguments to be printed in hexadeci‐
482 mal. This is mostly useful if you don't trust the decoding
483 or you need to know the actual numeric value of an argu‐
484 ment. See also -X raw option.
485 -e read=set
487 -e reads=set
488 -e r=set
489 --read=set Perform a full hexadecimal and ASCII dump of all the data
490 read from file descriptors listed in the specified set.
491 For example, to see all input activity on file descriptors
492 3 and 5 use -e read=3,5. Note that this is independent
493 from the normal tracing of the read(2) system call which is
494 controlled by the option -e trace=read.
495 -e write=set
497 -e writes=set
498 -e w=set
499 --write=set Perform a full hexadecimal and ASCII dump of all the data
500 written to file descriptors listed in the specified set.
501 For example, to see all output activity on file descriptors
502 3 and 5 use -e write=3,5. Note that this is independent
503 from the normal tracing of the write(2) system call which
504 is controlled by the option -e trace=write.
505 -e quiet=set
507 -e silent=set
508 -e silence=set
509 -e q=set
510 --quiet=set
511 --silent=set
512 --silence=set
513 Suppress various information messages. The default is
514 quiet=none. set can include the following elements:
515 attach Suppress messages about attaching and de‐
517 taching ("[ Process NNNN attached ]", "[
518 Process NNNN detached ]").
519 exit Suppress messages about process exits
520 ("+++ exited with SSS +++").
521 path-resolution Suppress messages about resolution of
522 paths provided via the -P option ("Re‐
523 quested path "..." resolved into "..."").
524 personality Suppress messages about process personal‐
525 ity changes ("[ Process PID=NNNN runs in
526 PPP mode. ]").
527 thread-execve
528 superseded Suppress messages about process being su‐
529 perseded by execve(2) in another thread
530 ("+++ superseded by execve in pid NNNN
531 +++").
532 -e decode-fds=set
534 --decode-fds=set
535 Decode various information associated with file descrip‐
536 tors. The default is decode-fds=none. set can include the
537 following elements:
538 path Print file paths. Also enables printing of
540 tracee's current working directory when AT_FDCWD
541 constant is used.
542 socket Print socket protocol-specific information,
543 dev Print character/block device numbers.
544 pidfd Print PIDs associated with pidfd file descriptors.
545 -e decode-pids=set
547 --decode-pids=set
548 Decode various information associated with process IDs (and
549 also thread IDs, process group IDs, and session IDs). The
550 default is decode-pids=none. set can include the following
551 elements:
552 comm Print command names associated with thread or
554 process IDs.
555 pidns Print thread, process, process group, and session
556 IDs in strace's PID namespace if the tracee is in a
557 different PID namespace.
558 -e kvm=vcpu
560 --kvm=vcpu Print the exit reason of kvm vcpu. Requires Linux kernel
561 version 4.16.0 or higher.
562 -i
564 --instruction-pointer
565 Print the instruction pointer at the time of the system
566 call.
567 -n
569 --syscall-number
570 Print the syscall number.
571 -k
573 --stack-traces
574 Print the execution stack trace of the traced processes af‐
575 ter each system call.
576 -o filename
578 --output=filename
579 Write the trace output to the file filename rather than to
580 stderr. filename.pid form is used if -ff option is sup‐
581 plied. If the argument begins with '|' or '!', the rest of
582 the argument is treated as a command and all output is
583 piped to it. This is convenient for piping the debugging
584 output to a program without affecting the redirections of
585 executed programs. The latter is not compatible with -ff
586 option currently.
587 -A
589 --output-append-mode
590 Open the file provided in the -o option in append mode.
591 -q
593 --quiet
594 --quiet=attach,personality
595 Suppress messages about attaching, detaching, and personal‐
596 ity changes. This happens automatically when output is
597 redirected to a file and the command is run directly in‐
598 stead of attaching.
599 -qq
601 --quiet=attach,personality,exit
602 Suppress messages attaching, detaching, personality
603 changes, and about process exit status.
604 -qqq
606 --quiet=all Suppress all suppressible messages (please refer to the -e
607 quiet option description for the full list of suppressible
608 messages).
609 -r
611 --relative-timestamps[=precision]
612 Print a relative timestamp upon entry to each system call.
613 This records the time difference between the beginning of
614 successive system calls. precision can be one of s (for
615 seconds), ms (milliseconds), us (microseconds), or ns
616 (nanoseconds), and allows setting the precision of time
617 value being printed. Default is us (microseconds). Note
618 that since -r option uses the monotonic clock time for mea‐
619 suring time difference and not the wall clock time, its
620 measurements can differ from the difference in time re‐
621 ported by the -t option.
622 -s strsize
624 --string-limit=strsize
625 Specify the maximum string size to print (the default is
626 32). Note that filenames are not considered strings and
627 are always printed in full.
628 --absolute-timestamps[=[[format:]format],[[precision:]precision]]
630 --timestamps[=[[format:]format],[[precision:]precision]]
631 Prefix each line of the trace with the wall clock time in
632 the specified format with the specified precision. format
633 can be one of the following:
634 none No time stamp is printed. Can be used to
636 override the previous setting.
637 time Wall clock time (strftime(3) format string is
638 %T).
639 unix Number of seconds since the epoch (strf‐
640 time(3) format string is %s).
641 precision can be one of s (for seconds), ms (milliseconds),
643 us (microseconds), or ns (nanoseconds). Default arguments
644 for the option are format:time,precision:s.
645 -t
647 --absolute-timestamps
648 Prefix each line of the trace with the wall clock time.
649 -tt
651 --absolute-timestamps=precision:us
652 If given twice, the time printed will include the microsec‐
653 onds.
654 -ttt
656 --absolute-timestamps=format:unix,precision:us
657 If given thrice, the time printed will include the mi‐
658 croseconds and the leading portion will be printed as the
659 number of seconds since the epoch.
660 -T
662 --syscall-times[=precision]
663 Show the time spent in system calls. This records the time
664 difference between the beginning and the end of each system
665 call. precision can be one of s (for seconds), ms (mil‐
666 liseconds), us (microseconds), or ns (nanoseconds), and al‐
667 lows setting the precision of time value being printed.
668 Default is us (microseconds).
669 -v
671 --no-abbrev Print unabbreviated versions of environment, stat, termios,
672 etc. calls. These structures are very common in calls and
673 so the default behavior displays a reasonable subset of
674 structure members. Use this option to get all of the gory
675 details.
676 --strings-in-hex[=option]
678 Control usage of escape sequences with hexadecimal numbers
679 in the printed strings. Normally (when no --strings-in-hex
680 or -x option is supplied), escape sequences are used to
681 print non-printable and non-ASCII characters (that is,
682 characters with a character code less than 32 or greater
683 than 127), or to disambiguate the output (so, for quotes
684 and other characters that encase the printed string, for
685 example, angle brackets, in case of file descriptor path
686 output); for the former use case, unless it is a white
687 space character that has a symbolic escape sequence defined
688 in the C standard (that is, “\t” for a horizontal tab, “\n”
689 for a newline, “\v” for a vertical tab, “\f” for a form
690 feed page break, and “\r” for a carriage return) are
691 printed using escape sequences with numbers that correspond
692 to their byte values, with octal number format being the
693 default. option can be one of the following:
694 none Hexadecimal numbers are not used in the
696 output at all. When there is a need to
697 emit an escape sequence, octal numbers are
698 used.
699 non-ascii-chars Hexadecimal numbers are used instead of
700 octal in the escape sequences.
701 non-ascii Strings that contain non-ASCII characters
702 are printed using escape sequences with
703 hexadecimal numbers.
704 all All strings are printed using escape se‐
705 quences with hexadecimal numbers.
706 When the option is supplied without an argument, all is as‐
708 sumed.
709 -x
711 --strings-in-hex=non-ascii
712 Print all non-ASCII strings in hexadecimal string format.
713 -xx
715 --strings-in-hex[=all]
716 Print all strings in hexadecimal string format.
717 -X format
719 --const-print-style=format
720 Set the format for printing of named constants and flags.
721 Supported format values are:
722 raw Raw number output, without decoding.
724 abbrev Output a named constant or a set of flags instead
725 of the raw number if they are found. This is the
726 default strace behaviour.
727 verbose Output both the raw value and the decoded string
728 (as a comment).
729 -y
731 --decode-fds
732 --decode-fds=path
733 Print paths associated with file descriptor arguments and
734 with the AT_FDCWD constant.
735 -yy
737 --decode-fds=all
738 Print all available information associated with file de‐
739 scriptors: protocol-specific information associated with
740 socket file descriptors, block/character device number as‐
741 sociated with device file descriptors, and PIDs associated
742 with pidfd file descriptors.
743 --pidns-translation
745 --decode-pids=pidns
746 If strace and tracee are in different PID namespaces, print
747 PIDs in strace's namespace, too.
748 -Y
750 --decode-pids=comm
751 Print command names for PIDs.
752 --secontext[=format]
754 -e secontext=format
755 When SELinux is available and is not disabled, print in
756 square brackets SELinux contexts of processes, files, and
757 descriptors. The format argument is a comma-separated list
758 of items being one of the following:
759 full Print the full context (user, role, type
761 level and category).
762 mismatch Also print the context recorded by the
763 SELinux database in case the current con‐
764 text differs. The latter is printed af‐
765 ter two exclamation marks (!!).
766 The default value for --secontext is !full,mismatch which
768 prints only the type instead of full context and doesn't
769 check for context mismatches.
770 Statistics
772 -c
773 --summary-only
774 Count time, calls, and errors for each system call and re‐
775 port a summary on program exit, suppressing the regular
776 output. This attempts to show system time (CPU time spent
777 running in the kernel) independent of wall clock time. If
778 -c is used with -f, only aggregate totals for all traced
779 processes are kept.
780 -C
782 --summary Like -c but also print regular output while processes are
783 running.
784 -O overhead
786 --summary-syscall-overhead=overhead
787 Set the overhead for tracing system calls to overhead.
788 This is useful for overriding the default heuristic for
789 guessing how much time is spent in mere measuring when tim‐
790 ing system calls using the -c option. The accuracy of the
791 heuristic can be gauged by timing a given program run with‐
792 out tracing (using time(1)) and comparing the accumulated
793 system call time to the total produced using -c.
794 The format of overhead specification is described in sec‐
796 tion Time specification format description.
797 -S sortby
799 --summary-sort-by=sortby
800 Sort the output of the histogram printed by the -c option
801 by the specified criterion. Legal values are time (or
802 time-percent or time-total or total-time), min-time (or
803 shortest or time-min), max-time (or longest or time-max),
804 avg-time (or time-avg), calls (or count), errors (or er‐
805 ror), name (or syscall or syscall-name), and nothing (or
806 none); default is time.
807 -U columns
809 --summary-columns=columns
810 Configure a set (and order) of columns being shown in the
811 call summary. The columns argument is a comma-separated
812 list with items being one of the following:
813 time-percent (or time) Percentage of cumula‐
815 tive time consumed by a
816 specific system call.
817 total-time (or time-total) Total system (or wall
818 clock, if -w option is
819 provided) time consumed
820 by a specific system
821 call.
822 min-time (or shortest or time-min) Minimum observed call
823 duration.
824 max-time (or longest or time-max) Maximum observed call
825 duration.
826 avg-time (or time-avg) Average call duration.
827 calls (or count) Call count.
828 errors (or error) Error count.
829 name (or syscall or syscall-name) Syscall name.
830 The default value is time-percent,to‐
832 tal-time,avg-time,calls,errors,name. If the name field is
833 not supplied explicitly, it is added as the last column.
834 -w
836 --summary-wall-clock
837 Summarise the time difference between the beginning and end
838 of each system call. The default is to summarise the sys‐
839 tem time.
840 Tampering
842 -e inject=syscall_set[:error=errno|:retval=value][:signal=sig]
843 [:syscall=syscall][:delay_enter=delay][:delay_exit=delay][:poke_en‐
844 ter=@argN=DATAN,@argM=DATAM...][:poke_exit=@argN=DATAN,@argM=DATAM...]
845 [:when=expr]
846 --inject=syscall_set[:error=errno|:retval=value][:signal=sig]
847 [:syscall=syscall][:delay_enter=delay][:delay_exit=delay]
848 [:poke_enter=@argN=DATAN,@argM=DATAM...]
849 [:poke_exit=@argN=DATAN,@argM=DATAM...][:when=expr]
850 Perform syscall tampering for the specified set of
851 syscalls. The syntax of the syscall_set specification is
852 the same as in the -e trace option.
853 At least one of error, retval, signal, delay_enter, de‐
855 lay_exit, poke_enter, or poke_exit options has to be speci‐
856 fied. error and retval are mutually exclusive.
857 If :error=errno option is specified, a fault is injected
859 into a syscall invocation: the syscall number is replaced
860 by -1 which corresponds to an invalid syscall (unless a
861 syscall is specified with :syscall= option), and the error
862 code is specified using a symbolic errno value like ENOSYS
863 or a numeric value within 1..4095 range.
864 If :retval=value option is specified, success injection is
866 performed: the syscall number is replaced by -1, but a bo‐
867 gus success value is returned to the callee.
868 If :signal=sig option is specified with either a symbolic
870 value like SIGSEGV or a numeric value within 1..SIGRTMAX
871 range, that signal is delivered on entering every syscall
872 specified by the set.
873 If :delay_enter=delay or :delay_exit=delay options are
875 specified, delay injection is performed: the tracee is de‐
876 layed by time period specified by delay on entering or ex‐
877 iting the syscall, respectively. The format of delay spec‐
878 ification is described in section Time specification format
879 description.
880 If :poke_enter=@argN=DATAN,@argM=DATAM... or
882 :poke_exit=@argN=DATAN,@argM=DATAM... options are speci‐
883 fied, tracee's memory at locations, pointed to by system
884 call arguments argN and argM (going from arg1 to arg7) is
885 overwritten by data DATAN and DATAM (specified in hexadeci‐
886 mal format; for example :poke_en‐
887 ter=@arg1=0000DEAD0000BEEF). :poke_enter modifies memory
888 on syscall enter, and :poke_exit - on exit.
889 If :signal=sig option is specified without :error=errno,
891 :retval=value or :delay_{enter,exit}=usecs options, then
892 only a signal sig is delivered without a syscall fault or
893 delay injection. Conversely, :error=errno or :retval=value
894 option without :delay_enter=delay, :delay_exit=delay or
895 :signal=sig options injects a fault without delivering a
896 signal or injecting a delay, etc.
897 If :signal=sig option is specified together with :error=er‐
899 rno or :retval=value, then both injection of a fault or
900 success and signal delivery are performed.
901 if :syscall=syscall option is specified, the corresponding
903 syscall with no side effects is injected instead of -1.
904 Currently, only "pure" (see -e trace=%pure description)
905 syscalls can be specified there.
906 Unless a :when=expr subexpression is specified, an injec‐
908 tion is being made into every invocation of each syscall
909 from the set.
910 The format of the subexpression is:
912 first[..last][+[step]]
914 Number first stands for the first invocation number in the
916 range, number last stands for the last invocation number in
917 the range, and step stands for the step between two consec‐
918 utive invocations. The following combinations are useful:
919 first For every syscall from the set, perform
921 an injection for the syscall invocation
922 number first only.
923 first..last For every syscall from the set, perform
924 an injection for the syscall invocation
925 number first and all subsequent invoca‐
926 tions until the invocation number last
927 (inclusive).
928 first+ For every syscall from the set, perform
929 injections for the syscall invocation
930 number first and all subsequent invoca‐
931 tions.
932 first..last+ For every syscall from the set, perform
933 injections for the syscall invocation
934 number first and all subsequent invoca‐
935 tions until the invocation number last
936 (inclusive).
937 first+step For every syscall from the set, perform
938 injections for syscall invocations number
939 first, first+step, first+step+step, and
940 so on.
941 first..last+step Same as the previous, but consider only
942 syscall invocations with numbers up to
943 last (inclusive).
944 For example, to fail each third and subsequent chdir
946 syscalls with ENOENT, use -e inject=chdir:er‐
947 ror=ENOENT:when=3+.
948 The valid range for numbers first and step is 1..65535, and
950 for number last is 1..65534.
951 An injection expression can contain only one error= or ret‐
953 val= specification, and only one signal= specification. If
954 an injection expression contains multiple when= specifica‐
955 tions, the last one takes precedence.
956 Accounting of syscalls that are subject to injection is
958 done per syscall and per tracee.
959 Specification of syscall injection can be combined with
961 other syscall filtering options, for example, -P /dev/uran‐
962 dom -e inject=file:error=ENOENT.
963 -e fault=syscall_set[:error=errno][:when=expr]
965 --fault=syscall_set[:error=errno][:when=expr]
966 Perform syscall fault injection for the specified set of
967 syscalls.
968 This is equivalent to more generic -e inject= expression
970 with default value of errno option set to ENOSYS.
971 Miscellaneous
973 -d
974 --debug Show some debugging output of strace itself on the standard
975 error.
976 -F This option is deprecated. It is retained for backward
978 compatibility only and may be removed in future releases.
979 Usage of multiple instances of -F option is still equiva‐
980 lent to a single -f, and it is ignored at all if used along
981 with one or more instances of -f option.
982 -h
984 --help Print the help summary.
985 --seccomp-bpf
987 Try to enable use of seccomp-bpf (see seccomp(2)) to have
988 ptrace(2)-stops only when system calls that are being
989 traced occur in the traced processes. This option has no
990 effect unless -f/--follow-forks is also specified. --sec‐
991 comp-bpf is also not applicable to processes attached using
992 -p/--attach option. An attempt to enable system calls fil‐
993 tering using seccomp-bpf may fail for various reasons, e.g.
994 there are too many system calls to filter, the seccomp API
995 is not available, or strace itself is being traced. In
996 cases when seccomp-bpf filter setup failed, strace proceeds
997 as usual and stops traced processes on every system call.
998 --tips[=[[id:]id],[[format:]format]]
1000 Show strace tips, tricks, and tweaks before exit. id can
1001 be a non-negative integer number, which enables printing of
1002 specific tip, trick, or tweak (these ID are not guaranteed
1003 to be stable), or random (the default), in which case a
1004 random tip is printed. format can be one of the following:
1005 none No tip is printed. Can be used to override the
1007 previous setting.
1008 compact Print the tip just big enough to contain all the
1009 text.
1010 full Print the tip in its full glory.
1011 Default is id:random,format:compact.
1013 -V
1015 --version Print the version number of strace. Multiple instances of
1016 the option beyond specific threshold tend to increase
1017 Strauss awareness.
1018 Time specification format description
1020 Time values can be specified as a decimal floating point number (in a
1021 format accepted by strtod(3)), optionally followed by one of the fol‐
1022 lowing suffices that specify the unit of time: s (seconds), ms (mil‐
1023 liseconds), us (microseconds), or ns (nanoseconds). If no suffix is
1024 specified, the value is interpreted as microseconds.
1025 The described format is used for -O, -e inject=delay_enter, and -e in‐
1027 ject=delay_exit options.
1028
1030 When command exits, strace exits with the same exit status. If command
1031 is terminated by a signal, strace terminates itself with the same sig‐
1032 nal, so that strace can be used as a wrapper process transparent to the
1033 invoking parent process. Note that parent-child relationship (signal
1034 stop notifications, getppid(2) value, etc) between traced process and
1035 its parent are not preserved unless -D is used.
1036 When using -p without a command, the exit status of strace is zero un‐
1038 less no processes has been attached or there was an unexpected error in
1039 doing the tracing.
1040
1042 If strace is installed setuid to root then the invoking user will be
1043 able to attach to and trace processes owned by any user. In addition
1044 setuid and setgid programs will be executed and traced with the correct
1045 effective privileges. Since only users trusted with full root privi‐
1046 leges should be allowed to do these things, it only makes sense to in‐
1047 stall strace as setuid to root when the users who can execute it are
1048 restricted to those users who have this trust. For example, it makes
1049 sense to install a special version of strace with mode 'rwsr-xr--',
1050 user root and group trace, where members of the trace group are trusted
1051 users. If you do use this feature, please remember to install a regu‐
1052 lar non-setuid version of strace for ordinary users to use.
1053
1055 On some architectures, strace supports decoding of syscalls for pro‐
1056 cesses that use different ABI rather than the one strace uses. Specif‐
1057 ically, in addition to decoding native ABI, strace can decode the fol‐
1058 lowing ABIs on the following architectures:
1059 ┌───────────────────┬─────────────────────────┐
1061 │Architecture │ ABIs supported │
1062 ├───────────────────┼─────────────────────────┤
1063 │x86_64 │ i386, x32 [1]; i386 [2] │
1064 ├───────────────────┼─────────────────────────┤
1065 │AArch64 │ ARM 32-bit EABI │
1066 ├───────────────────┼─────────────────────────┤
1067 │PowerPC 64-bit [3] │ PowerPC 32-bit │
1068 ├───────────────────┼─────────────────────────┤
1069 │s390x │ s390 │
1070 ├───────────────────┼─────────────────────────┤
1071 │SPARC 64-bit │ SPARC 32-bit │
1072 ├───────────────────┼─────────────────────────┤
1073 │TILE 64-bit │ TILE 32-bit │
1074 └───────────────────┴─────────────────────────┘
1075 [1] When strace is built as an x86_64 application
1076 [2] When strace is built as an x32 application
1077 [3] Big endian only
1078 This support is optional and relies on ability to generate and parse
1080 structure definitions during the build time. Please refer to the out‐
1081 put of the strace -V command in order to figure out what support is
1082 available in your strace build ("non-native" refers to an ABI that dif‐
1083 fers from the ABI strace has):
1084 m32-mpers strace can trace and properly decode non-native 32-bit
1086 binaries.
1087 no-m32-mpers strace can trace, but cannot properly decode non-native
1088 32-bit binaries.
1089 mx32-mpers strace can trace and properly decode non-native
1090 32-on-64-bit binaries.
1091 no-mx32-mpers strace can trace, but cannot properly decode non-native
1092 32-on-64-bit binaries.
1093 If the output contains neither m32-mpers nor no-m32-mpers, then decod‐
1095 ing of non-native 32-bit binaries is not implemented at all or not ap‐
1096 plicable.
1097 Likewise, if the output contains neither mx32-mpers nor no-mx32-mpers,
1099 then decoding of non-native 32-on-64-bit binaries is not implemented at
1100 all or not applicable.
1101
1103 It is a pity that so much tracing clutter is produced by systems em‐
1104 ploying shared libraries.
1105 It is instructive to think about system call inputs and outputs as
1107 data-flow across the user/kernel boundary. Because user-space and ker‐
1108 nel-space are separate and address-protected, it is sometimes possible
1109 to make deductive inferences about process behavior using inputs and
1110 outputs as propositions.
1111 In some cases, a system call will differ from the documented behavior
1113 or have a different name. For example, the faccessat(2) system call
1114 does not have flags argument, and the setrlimit(2) library function
1115 uses prlimit64(2) system call on modern (2.6.38+) kernels. These dis‐
1116 crepancies are normal but idiosyncratic characteristics of the system
1117 call interface and are accounted for by C library wrapper functions.
1118 Some system calls have different names in different architectures and
1120 personalities. In these cases, system call filtering and printing uses
1121 the names that match corresponding __NR_* kernel macros of the tracee's
1122 architecture and personality. There are two exceptions from this gen‐
1123 eral rule: arm_fadvise64_64(2) ARM syscall and xtensa_fadvise64_64(2)
1124 Xtensa syscall are filtered and printed as fadvise64_64(2).
1125 On x32, syscalls that are intended to be used by 64-bit processes and
1127 not x32 ones (for example, readv(2), that has syscall number 19 on
1128 x86_64, with its x32 counterpart has syscall number 515), but called
1129 with __X32_SYSCALL_BIT flag being set, are designated with #64 suffix.
1130 On some platforms a process that is attached to with the -p option may
1132 observe a spurious EINTR return from the current system call that is
1133 not restartable. (Ideally, all system calls should be restarted on
1134 strace attach, making the attach invisible to the traced process, but a
1135 few system calls aren't. Arguably, every instance of such behavior is
1136 a kernel bug.) This may have an unpredictable effect on the process if
1137 the process takes no action to restart the system call.
1138 As strace executes the specified command directly and does not employ a
1140 shell for that, scripts without shebang that usually run just fine when
1141 invoked by shell fail to execute with ENOEXEC error. It is advisable
1142 to manually supply a shell as a command with the script as its argu‐
1143 ment.
1144
1146 Programs that use the setuid bit do not have effective user ID privi‐
1147 leges while being traced.
1148 A traced process runs slowly (but check out the --seccomp-bpf option).
1150 Traced processes which are descended from command may be left running
1152 after an interrupt signal (CTRL-C).
1153
1155 The original strace was written by Paul Kranenburg for SunOS and was
1156 inspired by its trace utility. The SunOS version of strace was ported
1157 to Linux and enhanced by Branko Lankester, who also wrote the Linux
1158 kernel support. Even though Paul released strace 2.5 in 1992, Branko's
1159 work was based on Paul's strace 1.5 release from 1991. In 1993, Rick
1160 Sladkey merged strace 2.5 for SunOS and the second release of strace
1161 for Linux, added many of the features of truss(1) from SVR4, and pro‐
1162 duced an strace that worked on both platforms. In 1994 Rick ported
1163 strace to SVR4 and Solaris and wrote the automatic configuration sup‐
1164 port. In 1995 he ported strace to Irix and became tired of writing
1165 about himself in the third person.
1166 Beginning with 1996, strace was maintained by Wichert Akkerman. During
1168 his tenure, strace development migrated to CVS; ports to FreeBSD and
1169 many architectures on Linux (including ARM, IA-64, MIPS, PA-RISC, Pow‐
1170 erPC, s390, SPARC) were introduced. In 2002, the burden of strace
1171 maintainership was transferred to Roland McGrath. Since then, strace
1172 gained support for several new Linux architectures (AMD64, s390x, Su‐
1173 perH), bi-architecture support for some of them, and received numerous
1174 additions and improvements in syscalls decoders on Linux; strace devel‐
1175 opment migrated to Git during that period. Since 2009, strace is ac‐
1176 tively maintained by Dmitry Levin. strace gained support for AArch64,
1177 ARC, AVR32, Blackfin, Meta, Nios II, OpenRISC 1000, RISC-V, Tile/Ti‐
1178 leGx, Xtensa architectures since that time. In 2012, unmaintained and
1179 apparently broken support for non-Linux operating systems was removed.
1180 Also, in 2012 strace gained support for path tracing and file descrip‐
1181 tor path decoding. In 2014, support for stack traces printing was
1182 added. In 2016, syscall fault injection was implemented.
1183 For the additional information, please refer to the NEWS file and
1185 strace repository commit log.
1186
1188 Problems with strace should be reported to the strace mailing list
1189 ⟨mailto:strace-devel@lists.strace.io⟩.
1190
1192 strace-log-merge(1), ltrace(1), perf-trace(1), trace-cmd(1), time(1),
1193 ptrace(2), syscall(2), proc(5), signal(7)
1194 strace Home Page ⟨https://strace.io/⟩
1196
1198 The complete list of strace contributors can be found in the CREDITS
1199 file.
1200strace 6.1 2022-10-16 STRACE(1)