1STRACE(1) General Commands Manual STRACE(1)
2
6 strace - trace system calls and signals
7
9 strace [-ACdffhikqqrtttTvVwxxyyYzZ] [-a column] [-b execve]
10 [-e expr]... [-I n] [-o file] [-O overhead] [-p pid]...
11 [-P path]... [-s strsize] [-S sortby] [-U columns] [-X format]
12 [--seccomp-bpf] [--syscall-limit limit] [--secontext[=format]]
13 [--tips[=format]] { -p pid | [-DDD] [-E var[=val]]...
14 [-u username] command [args] }
15 strace -c [-dfwzZ] [-b execve] [-e expr]... [-I n] [-O overhead]
17 [-p pid]... [-P path]... [-S sortby] [-U columns]
18 [--seccomp-bpf] [--syscall-limit limit] [--tips[=format]] {
19 -p pid | [-DDD] [-E var[=val]]... [-u username] command [args] }
20 strace --tips[=format]
22
24 In the simplest case strace runs the specified command until it exits.
25 It intercepts and records the system calls which are called by a
26 process and the signals which are received by a process. The name of
27 each system call, its arguments and its return value are printed on
28 standard error or to the file specified with the -o option.
29 strace is a useful diagnostic, instructional, and debugging tool. Sys‐
31 tem administrators, diagnosticians and trouble-shooters will find it
32 invaluable for solving problems with programs for which the source is
33 not readily available since they do not need to be recompiled in order
34 to trace them. Students, hackers and the overly-curious will find that
35 a great deal can be learned about a system and its system calls by
36 tracing even ordinary programs. And programmers will find that since
37 system calls and signals are events that happen at the user/kernel in‐
38 terface, a close examination of this boundary is very useful for bug
39 isolation, sanity checking and attempting to capture race conditions.
40 Each line in the trace contains the system call name, followed by its
42 arguments in parentheses and its return value. An example from strac‐
43 ing the command "cat /dev/null" is:
44 open("/dev/null", O_RDONLY) = 3
46 Errors (typically a return value of -1) have the errno symbol and error
48 string appended.
49 open("/foo/bar", O_RDONLY) = -1 ENOENT (No such file or directory)
51 Signals are printed as signal symbol and decoded siginfo structure. An
53 excerpt from stracing and interrupting the command "sleep 666" is:
54 sigsuspend([] <unfinished ...>
56 --- SIGINT {si_signo=SIGINT, si_code=SI_USER, si_pid=...} ---
57 +++ killed by SIGINT +++
58 If a system call is being executed and meanwhile another one is being
60 called from a different thread/process then strace will try to preserve
61 the order of those events and mark the ongoing call as being unfin‐
62 ished. When the call returns it will be marked as resumed.
63 [pid 28772] select(4, [3], NULL, NULL, NULL <unfinished ...>
65 [pid 28779] clock_gettime(CLOCK_REALTIME, {tv_sec=1130322148, tv_nsec=3977000}) = 0
66 [pid 28772] <... select resumed> ) = 1 (in [3])
67 Interruption of a (restartable) system call by a signal delivery is
69 processed differently as kernel terminates the system call and also ar‐
70 ranges its immediate reexecution after the signal handler completes.
71 read(0, 0x7ffff72cf5cf, 1) = ? ERESTARTSYS (To be restarted)
73 --- SIGALRM {si_signo=SIGALRM, si_code=SI_KERNEL} ---
74 rt_sigreturn({mask=[]}) = 0
75 read(0, "", 1) = 0
76 Arguments are printed in symbolic form with passion. This example
78 shows the shell performing ">>xyzzy" output redirection:
79 open("xyzzy", O_WRONLY|O_APPEND|O_CREAT, 0666) = 3
81 Here, the second and the third argument of open(2) are decoded by
83 breaking down the flag argument into its three bitwise-OR constituents
84 and printing the mode value in octal by tradition. Where the tradi‐
85 tional or native usage differs from ANSI or POSIX, the latter forms are
86 preferred. In some cases, strace output is proven to be more readable
87 than the source.
88 Structure pointers are dereferenced and the members are displayed as
90 appropriate. In most cases, arguments are formatted in the most C-like
91 fashion possible. For example, the essence of the command "ls -l
92 /dev/null" is captured as:
93 lstat("/dev/null", {st_mode=S_IFCHR|0666, st_rdev=makedev(0x1, 0x3), ...}) = 0
95 Notice how the 'struct stat' argument is dereferenced and how each mem‐
97 ber is displayed symbolically. In particular, observe how the st_mode
98 member is carefully decoded into a bitwise-OR of symbolic and numeric
99 values. Also notice in this example that the first argument to
100 lstat(2) is an input to the system call and the second argument is an
101 output. Since output arguments are not modified if the system call
102 fails, arguments may not always be dereferenced. For example, retrying
103 the "ls -l" example with a non-existent file produces the following
104 line:
105 lstat("/foo/bar", 0xb004) = -1 ENOENT (No such file or directory)
107 In this case the porch light is on but nobody is home.
109 Syscalls unknown to strace are printed raw, with the unknown system
111 call number printed in hexadecimal form and prefixed with "syscall_":
112 syscall_0xbad(0x1, 0x2, 0x3, 0x4, 0x5, 0x6) = -1 ENOSYS (Function not implemented)
114 Character pointers are dereferenced and printed as C strings. Non-
117 printing characters in strings are normally represented by ordinary C
118 escape codes. Only the first strsize (32 by default) bytes of strings
119 are printed; longer strings have an ellipsis appended following the
120 closing quote. Here is a line from "ls -l" where the getpwuid(3) li‐
121 brary routine is reading the password file:
122 read(3, "root::0:0:System Administrator:/"..., 1024) = 422
124 While structures are annotated using curly braces, pointers to basic
126 types and arrays are printed using square brackets with commas separat‐
127 ing the elements. Here is an example from the command id(1) on a sys‐
128 tem with supplementary group ids:
129 getgroups(32, [100, 0]) = 2
131 On the other hand, bit-sets are also shown using square brackets, but
133 set elements are separated only by a space. Here is the shell, prepar‐
134 ing to execute an external command:
135 sigprocmask(SIG_BLOCK, [CHLD TTOU], []) = 0
137 Here, the second argument is a bit-set of two signals, SIGCHLD and
139 SIGTTOU. In some cases, the bit-set is so full that printing out the
140 unset elements is more valuable. In that case, the bit-set is prefixed
141 by a tilde like this:
142 sigprocmask(SIG_UNBLOCK, ~[], NULL) = 0
144 Here, the second argument represents the full set of all signals.
146
148 General
149 -e expr A qualifying expression which modifies which events to
150 trace or how to trace them. The format of the expression
151 is:
152 [qualifier=][!]value[,value]...
154 where qualifier is one of trace (or t), trace-fds (or
156 trace-fd or fd or fds), abbrev (or a), verbose (or v), raw
157 (or x), signal (or signals or s), read (or reads or r),
158 write (or writes or w), fault, inject, status, quiet (or
159 silent or silence or q), secontext, decode-fds (or de‐
160 code-fd), decode-pids (or decode-pid), or kvm, and value is
161 a qualifier-dependent symbol or number. The default quali‐
162 fier is trace. Using an exclamation mark negates the set
163 of values. For example, -e open means literally
164 -e trace=open which in turn means trace only the open sys‐
165 tem call. By contrast, -e trace=!open means to trace every
166 system call except open. In addition, the special values
167 all and none have the obvious meanings.
168 Note that some shells use the exclamation point for history
170 expansion even inside quoted arguments. If so, you must
171 escape the exclamation point with a backslash.
172 Startup
174 -E var=val
175 --env=var=val
176 Run command with var=val in its list of environment vari‐
177 ables.
178 -E var
180 --env=var Remove var from the inherited list of environment variables
181 before passing it on to the command.
182 -p pid
184 --attach=pid
185 Attach to the process with the process ID pid and begin
186 tracing. The trace may be terminated at any time by a key‐
187 board interrupt signal (CTRL-C). strace will respond by
188 detaching itself from the traced process(es) leaving it
189 (them) to continue running. Multiple -p options can be
190 used to attach to many processes in addition to command
191 (which is optional if at least one -p option is given).
192 Multiple process IDs, separated by either comma (“,”),
193 space (“ ”), tab, or newline character, can be provided as
194 an argument to a single -p option, so, for example, -p
195 "$(pidof PROG)" and -p "$(pgrep PROG)" syntaxes are sup‐
196 ported.
197 -u username
199 --user=username
200 Run command with the user ID, group ID, and supplementary
201 groups of username. This option is only useful when run‐
202 ning as root and enables the correct execution of setuid
203 and/or setgid binaries. Unless this option is used setuid
204 and setgid programs are executed without effective privi‐
205 leges.
206 --argv0=name
208 Set argv[0] of the command being executed to name. Useful
209 for tracing multi-call executables which interpret argv[0],
210 such as busybox or kmod.
211 Tracing
213 -b syscall
214 --detach-on=syscall
215 If specified syscall is reached, detach from traced
216 process. Currently, only execve(2) syscall is supported.
217 This option is useful if you want to trace multi-threaded
218 process and therefore require -f, but don't want to trace
219 its (potentially very complex) children.
220 -D
222 --daemonize
223 --daemonize=grandchild
224 Run tracer process as a grandchild, not as the parent of
225 the tracee. This reduces the visible effect of strace by
226 keeping the tracee a direct child of the calling process.
227 -DD
229 --daemonize=pgroup
230 --daemonize=pgrp
231 Run tracer process as tracee's grandchild in a separate
232 process group. In addition to reduction of the visible ef‐
233 fect of strace, it also avoids killing of strace with
234 kill(2) issued to the whole process group.
235 -DDD
237 --daemonize=session
238 Run tracer process as tracee's grandchild in a separate
239 session ("true daemonisation"). In addition to reduction
240 of the visible effect of strace, it also avoids killing of
241 strace upon session termination.
242 -f
244 --follow-forks
245 Trace child processes as they are created by currently
246 traced processes as a result of the fork(2), vfork(2) and
247 clone(2) system calls. Note that -p PID -f will attach all
248 threads of process PID if it is multi-threaded, not only
249 thread with thread_id = PID.
250 --output-separately
252 If the --output=filename option is in effect, each pro‐
253 cesses trace is written to filename.pid where pid is the
254 numeric process id of each process.
255 -ff
257 --follow-forks --output-separately
258 Combine the effects of --follow-forks and --output-sepa‐
259 rately options. This is incompatible with -c, since no
260 per-process counts are kept.
261 One might want to consider using strace-log-merge(1) to ob‐
263 tain a combined strace log view.
264 -I interruptible
266 --interruptible=interruptible
267 When strace can be interrupted by signals (such as pressing
268 CTRL-C).
269 1, anywhere no signals are blocked;
271 2, waiting fatal signals are blocked while decoding
272 syscall (default);
273 3, never fatal signals are always blocked (default if
274 -o FILE PROG);
275 4, never_tstp fatal signals and SIGTSTP (CTRL-Z) are al‐
276 ways blocked (useful to make strace -o FILE
277 PROG not stop on CTRL-Z, default if -D).
278 --syscall-limit=limit
280 Detach all tracees when limit number of syscalls have been
281 captured. Syscalls filtered out via --trace, --trace-path
282 or --status options are not considered when keeping track
283 of the number of syscalls that are captured.
284 --kill-on-exit
286 Set PTRACE_O_EXITKILL ptrace option to all tracee processes
287 (which send a SIGKILL signal to the tracee if the tracer
288 exits) and do not detach them on cleanup so they will not
289 be left running after the tracer exit. --kill-on-exit is
290 not compatible with -p/--attach options.
291 Filtering
293 -e trace=syscall_set
294 -e t=syscall_set
295 --trace=syscall_set
296 Trace only the specified set of system calls. syscall_set
297 is defined as [!]value[,value], and value can be one of the
298 following:
299 syscall Trace specific syscall, specified by its name
301 (see syscalls(2) for a reference, but also see
302 NOTES).
303 ?value Question mark before the syscall qualification
305 allows suppression of error in case no
306 syscalls matched the qualification provided.
307 value@64 Limit the syscall specification described by
309 value to 64-bit personality.
310 value@32 Limit the syscall specification described by
312 value to 32-bit personality.
313 value@x32 Limit the syscall specification described by
315 value to x32 personality.
316 all Trace all system calls.
318 /regex Trace only those system calls that match the
320 regex. You can use POSIX Extended Regular Ex‐
321 pression syntax (see regex(7)).
322 %file
324 file Trace all system calls which take a file name
325 as an argument. You can think of this as an
326 abbreviation for -e trace=open,stat,chmod,un‐
327 link,... which is useful to seeing what files
328 the process is referencing. Furthermore, us‐
329 ing the abbreviation will ensure that you
330 don't accidentally forget to include a call
331 like lstat(2) in the list. Betchya woulda
332 forgot that one. The syntax without a preced‐
333 ing percent sign ("-e trace=file") is depre‐
334 cated.
335 %process
337 process Trace system calls associated with process
338 lifecycle (creation, exec, termination). The
339 syntax without a preceding percent sign ("-e
340 trace=process") is deprecated.
341 %net
343 %network
344 network Trace all the network related system calls.
345 The syntax without a preceding percent sign
346 ("-e trace=network") is deprecated.
347 %signal
349 signal Trace all signal related system calls. The
350 syntax without a preceding percent sign ("-e
351 trace=signal") is deprecated.
352 %ipc
354 ipc Trace all IPC related system calls. The syn‐
355 tax without a preceding percent sign ("-e
356 trace=ipc") is deprecated.
357 %desc
359 desc Trace all file descriptor related system
360 calls. The syntax without a preceding percent
361 sign ("-e trace=desc") is deprecated.
362 %memory
364 memory Trace all memory mapping related system calls.
365 The syntax without a preceding percent sign
366 ("-e trace=memory") is deprecated.
367 %creds Trace system calls that read or modify user
369 and group identifiers or capability sets.
370 %stat Trace stat syscall variants.
372 %lstat Trace lstat syscall variants.
374 %fstat Trace fstat, fstatat, and statx syscall vari‐
376 ants.
377 %%stat Trace syscalls used for requesting file status
379 (stat, lstat, fstat, fstatat, statx, and their
380 variants).
381 %statfs Trace statfs, statfs64, statvfs, osf_statfs,
383 and osf_statfs64 system calls. The same ef‐
384 fect can be achieved with
385 -e trace=/^(.*_)?statv?fs regular expression.
386 %fstatfs Trace fstatfs, fstatfs64, fstatvfs, osf_fs‐
388 tatfs, and osf_fstatfs64 system calls. The
389 same effect can be achieved with -e trace=/fs‐
390 tatv?fs regular expression.
391 %%statfs Trace syscalls related to file system statis‐
393 tics (statfs-like, fstatfs-like, and ustat).
394 The same effect can be achieved with
395 -e trace=/statv?fs|fsstat|ustat regular ex‐
396 pression.
397 %clock Trace system calls that read or modify system
399 clocks.
400 %pure Trace syscalls that always succeed and have no
402 arguments. Currently, this list includes
403 arc_gettls(2), getdtablesize(2), getegid(2),
404 getegid32(2), geteuid(2), geteuid32(2), get‐
405 gid(2), getgid32(2), getpagesize(2), getp‐
406 grp(2), getpid(2), getppid(2),
407 get_thread_area(2) (on architectures other
408 than x86), gettid(2), get_tls(2), getuid(2),
409 getuid32(2), getxgid(2), getxpid(2),
410 getxuid(2), kern_features(2), and
411 metag_get_tls(2) syscalls.
412 The -c option is useful for determining which system calls
414 might be useful to trace. For example,
415 trace=open,close,read,write means to only trace those four
416 system calls. Be careful when making inferences about the
417 user/kernel boundary if only a subset of system calls are
418 being monitored. The default is trace=all.
419 -e trace-fd=set
421 -e trace-fds=set
422 -e fd=set
423 -e fds=set
424 --trace-fds=set
425 Trace only the syscalls that operate on the specified sub‐
426 set of (non-negative) file descriptors. Note that usage of
427 this option also filters out all the syscalls that do not
428 operate on file descriptors at all. Applies in (inclusive)
429 disjunction with the --trace-path option.
430 -e signal=set
432 -e signals=set
433 -e s=set
434 --signal=set
435 Trace only the specified subset of signals. The default is
436 signal=all. For example, signal=!SIGIO (or signal=!io)
437 causes SIGIO signals not to be traced.
438 -e status=set
440 --status=set
441 Print only system calls with the specified return status.
442 The default is status=all. When using the status quali‐
443 fier, because strace waits for system calls to return be‐
444 fore deciding whether they should be printed or not, the
445 traditional order of events may not be preserved anymore.
446 If two system calls are executed by concurrent threads,
447 strace will first print both the entry and exit of the
448 first system call to exit, regardless of their respective
449 entry time. The entry and exit of the second system call
450 to exit will be printed afterwards. Here is an example
451 when select(2) is called, but a different thread calls
452 clock_gettime(2) before select(2) finishes:
453 [pid 28779] 1130322148.939977 clock_gettime(CLOCK_REALTIME, {1130322148, 939977000}) = 0
455 [pid 28772] 1130322148.438139 select(4, [3], NULL, NULL, NULL) = 1 (in [3])
456 set can include the following elements:
458 successful Trace system calls that returned without an
460 error code. The -z option has the effect of
461 status=successful.
462 failed Trace system calls that returned with an error
463 code. The -Z option has the effect of sta‐
464 tus=failed.
465 unfinished Trace system calls that did not return. This
466 might happen, for example, due to an execve
467 call in a neighbour thread.
468 unavailable Trace system calls that returned but strace
469 failed to fetch the error status.
470 detached Trace system calls for which strace detached
471 before the return.
472 -P path
474 --trace-path=path
475 Trace only system calls accessing path. Multiple -P op‐
476 tions can be used to specify several paths. Applies in
477 (inclusive) disjunction with the --trace-fds option.
478 -z
480 --successful-only
481 Print only syscalls that returned without an error code.
482 -Z
484 --failed-only
485 Print only syscalls that returned with an error code.
486 Output format
488 -a column
489 --columns=column
490 Align return values in a specific column (default column
491 40).
492 -e abbrev=syscall_set
494 -e a=syscall_set
495 --abbrev=syscall_set
496 Abbreviate the output from printing each member of large
497 structures. The syntax of the syscall_set specification is
498 the same as in the -e trace option. The default is ab‐
499 brev=all. The -v option has the effect of abbrev=none.
500 -e verbose=syscall_set
502 -e v=syscall_set
503 --verbose=syscall_set
504 Dereference structures for the specified set of system
505 calls. The syntax of the syscall_set specification is the
506 same as in the -e trace option. The default is ver‐
507 bose=all.
508 -e raw=syscall_set
510 -e x=syscall_set
511 --raw=syscall_set
512 Print raw, undecoded arguments for the specified set of
513 system calls. The syntax of the syscall_set specification
514 is the same as in the -e trace option. This option has the
515 effect of causing all arguments to be printed in hexadeci‐
516 mal. This is mostly useful if you don't trust the decoding
517 or you need to know the actual numeric value of an argu‐
518 ment. See also -X raw option.
519 -e read=set
521 -e reads=set
522 -e r=set
523 --read=set Perform a full hexadecimal and ASCII dump of all the data
524 read from file descriptors listed in the specified set.
525 For example, to see all input activity on file descriptors
526 3 and 5 use -e read=3,5. Note that this is independent
527 from the normal tracing of the read(2) system call which is
528 controlled by the option -e trace=read.
529 -e write=set
531 -e writes=set
532 -e w=set
533 --write=set Perform a full hexadecimal and ASCII dump of all the data
534 written to file descriptors listed in the specified set.
535 For example, to see all output activity on file descriptors
536 3 and 5 use -e write=3,5. Note that this is independent
537 from the normal tracing of the write(2) system call which
538 is controlled by the option -e trace=write.
539 -e quiet=set
541 -e silent=set
542 -e silence=set
543 -e q=set
544 --quiet=set
545 --silent=set
546 --silence=set
547 Suppress various information messages. The default is
548 quiet=none. set can include the following elements:
549 attach Suppress messages about attaching and de‐
551 taching ("[ Process NNNN attached ]", "[
552 Process NNNN detached ]").
553 exit Suppress messages about process exits
554 ("+++ exited with SSS +++").
555 path-resolution Suppress messages about resolution of
556 paths provided via the -P option ("Re‐
557 quested path "..." resolved into "..."").
558 personality Suppress messages about process personal‐
559 ity changes ("[ Process PID=NNNN runs in
560 PPP mode. ]").
561 thread-execve
562 superseded Suppress messages about process being su‐
563 perseded by execve(2) in another thread
564 ("+++ superseded by execve in pid NNNN
565 +++").
566 -e decode-fds=set
568 --decode-fds=set
569 Decode various information associated with file descrip‐
570 tors. The default is decode-fds=none. set can include the
571 following elements:
572 path Print file paths. Also enables printing of
574 tracee's current working directory when AT_FDCWD
575 constant is used.
576 socket Print socket protocol-specific information,
577 dev Print character/block device numbers.
578 pidfd Print PIDs associated with pidfd file descriptors.
579 signalfd Print signal masks associated with signalfd file
580 descriptors.
581 -e decode-pids=set
583 --decode-pids=set
584 Decode various information associated with process IDs (and
585 also thread IDs, process group IDs, and session IDs). The
586 default is decode-pids=none. set can include the following
587 elements:
588 comm Print command names associated with thread or
590 process IDs.
591 pidns Print thread, process, process group, and session
592 IDs in strace's PID namespace if the tracee is in a
593 different PID namespace.
594 -e kvm=vcpu
596 --kvm=vcpu Print the exit reason of kvm vcpu. Requires Linux kernel
597 version 4.16.0 or higher.
598 -i
600 --instruction-pointer
601 Print the instruction pointer at the time of the system
602 call.
603 -n
605 --syscall-number
606 Print the syscall number.
607 -k
609 --stack-traces
610 Print the execution stack trace of the traced processes af‐
611 ter each system call.
612 -o filename
614 --output=filename
615 Write the trace output to the file filename rather than to
616 stderr. filename.pid form is used if -ff option is sup‐
617 plied. If the argument begins with '|' or '!', the rest of
618 the argument is treated as a command and all output is
619 piped to it. This is convenient for piping the debugging
620 output to a program without affecting the redirections of
621 executed programs. The latter is not compatible with -ff
622 option currently.
623 -A
625 --output-append-mode
626 Open the file provided in the -o option in append mode.
627 -q
629 --quiet
630 --quiet=attach,personality
631 Suppress messages about attaching, detaching, and personal‐
632 ity changes. This happens automatically when output is
633 redirected to a file and the command is run directly in‐
634 stead of attaching.
635 -qq
637 --quiet=attach,personality,exit
638 Suppress messages attaching, detaching, personality
639 changes, and about process exit status.
640 -qqq
642 --quiet=all Suppress all suppressible messages (please refer to the -e
643 quiet option description for the full list of suppressible
644 messages).
645 -r
647 --relative-timestamps[=precision]
648 Print a relative timestamp upon entry to each system call.
649 This records the time difference between the beginning of
650 successive system calls. precision can be one of s (for
651 seconds), ms (milliseconds), us (microseconds), or ns
652 (nanoseconds), and allows setting the precision of time
653 value being printed. Default is us (microseconds). Note
654 that since -r option uses the monotonic clock time for mea‐
655 suring time difference and not the wall clock time, its
656 measurements can differ from the difference in time re‐
657 ported by the -t option.
658 -s strsize
660 --string-limit=strsize
661 Specify the maximum string size to print (the default is
662 32). Note that filenames are not considered strings and
663 are always printed in full.
664 --absolute-timestamps[=[[format:]format],[[precision:]precision]]
666 --timestamps[=[[format:]format],[[precision:]precision]]
667 Prefix each line of the trace with the wall clock time in
668 the specified format with the specified precision. format
669 can be one of the following:
670 none No time stamp is printed. Can be used to
672 override the previous setting.
673 time Wall clock time (strftime(3) format string is
674 %T).
675 unix Number of seconds since the epoch (strf‐
676 time(3) format string is %s).
677 precision can be one of s (for seconds), ms (milliseconds),
679 us (microseconds), or ns (nanoseconds). Default arguments
680 for the option are format:time,precision:s.
681 -t
683 --absolute-timestamps
684 Prefix each line of the trace with the wall clock time.
685 -tt
687 --absolute-timestamps=precision:us
688 If given twice, the time printed will include the microsec‐
689 onds.
690 -ttt
692 --absolute-timestamps=format:unix,precision:us
693 If given thrice, the time printed will include the mi‐
694 croseconds and the leading portion will be printed as the
695 number of seconds since the epoch.
696 -T
698 --syscall-times[=precision]
699 Show the time spent in system calls. This records the time
700 difference between the beginning and the end of each system
701 call. precision can be one of s (for seconds), ms (mil‐
702 liseconds), us (microseconds), or ns (nanoseconds), and al‐
703 lows setting the precision of time value being printed.
704 Default is us (microseconds).
705 -v
707 --no-abbrev Print unabbreviated versions of environment, stat, termios,
708 etc. calls. These structures are very common in calls and
709 so the default behavior displays a reasonable subset of
710 structure members. Use this option to get all of the gory
711 details.
712 --strings-in-hex[=option]
714 Control usage of escape sequences with hexadecimal numbers
715 in the printed strings. Normally (when no --strings-in-hex
716 or -x option is supplied), escape sequences are used to
717 print non-printable and non-ASCII characters (that is,
718 characters with a character code less than 32 or greater
719 than 127), or to disambiguate the output (so, for quotes
720 and other characters that encase the printed string, for
721 example, angle brackets, in case of file descriptor path
722 output); for the former use case, unless it is a white
723 space character that has a symbolic escape sequence defined
724 in the C standard (that is, “\t” for a horizontal tab, “\n”
725 for a newline, “\v” for a vertical tab, “\f” for a form
726 feed page break, and “\r” for a carriage return) are
727 printed using escape sequences with numbers that correspond
728 to their byte values, with octal number format being the
729 default. option can be one of the following:
730 none Hexadecimal numbers are not used in the
732 output at all. When there is a need to
733 emit an escape sequence, octal numbers are
734 used.
735 non-ascii-chars Hexadecimal numbers are used instead of
736 octal in the escape sequences.
737 non-ascii Strings that contain non-ASCII characters
738 are printed using escape sequences with
739 hexadecimal numbers.
740 all All strings are printed using escape se‐
741 quences with hexadecimal numbers.
742 When the option is supplied without an argument, all is as‐
744 sumed.
745 -x
747 --strings-in-hex=non-ascii
748 Print all non-ASCII strings in hexadecimal string format.
749 -xx
751 --strings-in-hex[=all]
752 Print all strings in hexadecimal string format.
753 -X format
755 --const-print-style=format
756 Set the format for printing of named constants and flags.
757 Supported format values are:
758 raw Raw number output, without decoding.
760 abbrev Output a named constant or a set of flags instead
761 of the raw number if they are found. This is the
762 default strace behaviour.
763 verbose Output both the raw value and the decoded string
764 (as a comment).
765 -y
767 --decode-fds
768 --decode-fds=path
769 Print paths associated with file descriptor arguments and
770 with the AT_FDCWD constant.
771 -yy
773 --decode-fds=all
774 Print all available information associated with file de‐
775 scriptors: protocol-specific information associated with
776 socket file descriptors, block/character device number as‐
777 sociated with device file descriptors, and PIDs associated
778 with pidfd file descriptors.
779 --pidns-translation
781 --decode-pids=pidns
782 If strace and tracee are in different PID namespaces, print
783 PIDs in strace's namespace, too.
784 -Y
786 --decode-pids=comm
787 Print command names for PIDs.
788 --secontext[=format]
790 -e secontext=format
791 When SELinux is available and is not disabled, print in
792 square brackets SELinux contexts of processes, files, and
793 descriptors. The format argument is a comma-separated list
794 of items being one of the following:
795 full Print the full context (user, role, type
797 level and category).
798 mismatch Also print the context recorded by the
799 SELinux database in case the current con‐
800 text differs. The latter is printed af‐
801 ter two exclamation marks (!!).
802 The default value for --secontext is !full,mismatch which
804 prints only the type instead of full context and doesn't
805 check for context mismatches.
806 Statistics
808 -c
809 --summary-only
810 Count time, calls, and errors for each system call and re‐
811 port a summary on program exit, suppressing the regular
812 output. This attempts to show system time (CPU time spent
813 running in the kernel) independent of wall clock time. If
814 -c is used with -f, only aggregate totals for all traced
815 processes are kept.
816 -C
818 --summary Like -c but also print regular output while processes are
819 running.
820 -O overhead
822 --summary-syscall-overhead=overhead
823 Set the overhead for tracing system calls to overhead.
824 This is useful for overriding the default heuristic for
825 guessing how much time is spent in mere measuring when tim‐
826 ing system calls using the -c option. The accuracy of the
827 heuristic can be gauged by timing a given program run with‐
828 out tracing (using time(1)) and comparing the accumulated
829 system call time to the total produced using -c.
830 The format of overhead specification is described in sec‐
832 tion Time specification format description.
833 -S sortby
835 --summary-sort-by=sortby
836 Sort the output of the histogram printed by the -c option
837 by the specified criterion. Legal values are time (or
838 time-percent or time-total or total-time), min-time (or
839 shortest or time-min), max-time (or longest or time-max),
840 avg-time (or time-avg), calls (or count), errors (or er‐
841 ror), name (or syscall or syscall-name), and nothing (or
842 none); default is time.
843 -U columns
845 --summary-columns=columns
846 Configure a set (and order) of columns being shown in the
847 call summary. The columns argument is a comma-separated
848 list with items being one of the following:
849 time-percent (or time) Percentage of cumula‐
851 tive time consumed by a
852 specific system call.
853 total-time (or time-total) Total system (or wall
854 clock, if -w option is
855 provided) time consumed
856 by a specific system
857 call.
858 min-time (or shortest or time-min) Minimum observed call
859 duration.
860 max-time (or longest or time-max) Maximum observed call
861 duration.
862 avg-time (or time-avg) Average call duration.
863 calls (or count) Call count.
864 errors (or error) Error count.
865 name (or syscall or syscall-name) Syscall name.
866 The default value is time-percent,to‐
868 tal-time,avg-time,calls,errors,name. If the name field is
869 not supplied explicitly, it is added as the last column.
870 -w
872 --summary-wall-clock
873 Summarise the time difference between the beginning and end
874 of each system call. The default is to summarise the sys‐
875 tem time.
876 Tampering
878 -e inject=syscall_set[:error=errno|:retval=value][:signal=sig]
879 [:syscall=syscall][:delay_enter=delay][:delay_exit=delay][:poke_en‐
880 ter=@argN=DATAN,@argM=DATAM...][:poke_exit=@argN=DATAN,@argM=DATAM...]
881 [:when=expr]
882 --inject=syscall_set[:error=errno|:retval=value][:signal=sig]
883 [:syscall=syscall][:delay_enter=delay][:delay_exit=delay]
884 [:poke_enter=@argN=DATAN,@argM=DATAM...]
885 [:poke_exit=@argN=DATAN,@argM=DATAM...][:when=expr]
886 Perform syscall tampering for the specified set of
887 syscalls. The syntax of the syscall_set specification is
888 the same as in the -e trace option.
889 At least one of error, retval, signal, delay_enter, de‐
891 lay_exit, poke_enter, or poke_exit options has to be speci‐
892 fied. error and retval are mutually exclusive.
893 If :error=errno option is specified, a fault is injected
895 into a syscall invocation: the syscall number is replaced
896 by -1 which corresponds to an invalid syscall (unless a
897 syscall is specified with :syscall= option), and the error
898 code is specified using a symbolic errno value like ENOSYS
899 or a numeric value within 1..4095 range.
900 If :retval=value option is specified, success injection is
902 performed: the syscall number is replaced by -1, but a bo‐
903 gus success value is returned to the callee.
904 If :signal=sig option is specified with either a symbolic
906 value like SIGSEGV or a numeric value within 1..SIGRTMAX
907 range, that signal is delivered on entering every syscall
908 specified by the set.
909 If :delay_enter=delay or :delay_exit=delay options are
911 specified, delay injection is performed: the tracee is de‐
912 layed by time period specified by delay on entering or ex‐
913 iting the syscall, respectively. The format of delay spec‐
914 ification is described in section Time specification format
915 description.
916 If :poke_enter=@argN=DATAN,@argM=DATAM... or
918 :poke_exit=@argN=DATAN,@argM=DATAM... options are speci‐
919 fied, tracee's memory at locations, pointed to by system
920 call arguments argN and argM (going from arg1 to arg7) is
921 overwritten by data DATAN and DATAM (specified in hexadeci‐
922 mal format; for example :poke_en‐
923 ter=@arg1=0000DEAD0000BEEF). :poke_enter modifies memory
924 on syscall enter, and :poke_exit - on exit.
925 If :signal=sig option is specified without :error=errno,
927 :retval=value or :delay_{enter,exit}=usecs options, then
928 only a signal sig is delivered without a syscall fault or
929 delay injection. Conversely, :error=errno or :retval=value
930 option without :delay_enter=delay, :delay_exit=delay or
931 :signal=sig options injects a fault without delivering a
932 signal or injecting a delay, etc.
933 If :signal=sig option is specified together with :error=er‐
935 rno or :retval=value, then both injection of a fault or
936 success and signal delivery are performed.
937 if :syscall=syscall option is specified, the corresponding
939 syscall with no side effects is injected instead of -1.
940 Currently, only "pure" (see -e trace=%pure description)
941 syscalls can be specified there.
942 Unless a :when=expr subexpression is specified, an injec‐
944 tion is being made into every invocation of each syscall
945 from the set.
946 The format of the subexpression is:
948 first[..last][+[step]]
950 Number first stands for the first invocation number in the
952 range, number last stands for the last invocation number in
953 the range, and step stands for the step between two consec‐
954 utive invocations. The following combinations are useful:
955 first For every syscall from the set, perform
957 an injection for the syscall invocation
958 number first only.
959 first..last For every syscall from the set, perform
960 an injection for the syscall invocation
961 number first and all subsequent invoca‐
962 tions until the invocation number last
963 (inclusive).
964 first+ For every syscall from the set, perform
965 injections for the syscall invocation
966 number first and all subsequent invoca‐
967 tions.
968 first..last+ For every syscall from the set, perform
969 injections for the syscall invocation
970 number first and all subsequent invoca‐
971 tions until the invocation number last
972 (inclusive).
973 first+step For every syscall from the set, perform
974 injections for syscall invocations number
975 first, first+step, first+step+step, and
976 so on.
977 first..last+step Same as the previous, but consider only
978 syscall invocations with numbers up to
979 last (inclusive).
980 For example, to fail each third and subsequent chdir
982 syscalls with ENOENT, use -e inject=chdir:er‐
983 ror=ENOENT:when=3+.
984 The valid range for numbers first and step is 1..65535, and
986 for number last is 1..65534.
987 An injection expression can contain only one error= or ret‐
989 val= specification, and only one signal= specification. If
990 an injection expression contains multiple when= specifica‐
991 tions, the last one takes precedence.
992 Accounting of syscalls that are subject to injection is
994 done per syscall and per tracee.
995 Specification of syscall injection can be combined with
997 other syscall filtering options, for example, -P /dev/uran‐
998 dom -e inject=file:error=ENOENT.
999 -e fault=syscall_set[:error=errno][:when=expr]
1001 --fault=syscall_set[:error=errno][:when=expr]
1002 Perform syscall fault injection for the specified set of
1003 syscalls.
1004 This is equivalent to more generic -e inject= expression
1006 with default value of errno option set to ENOSYS.
1007 Miscellaneous
1009 -d
1010 --debug Show some debugging output of strace itself on the standard
1011 error.
1012 -F This option is deprecated. It is retained for backward
1014 compatibility only and may be removed in future releases.
1015 Usage of multiple instances of -F option is still equiva‐
1016 lent to a single -f, and it is ignored at all if used along
1017 with one or more instances of -f option.
1018 -h
1020 --help Print the help summary.
1021 --seccomp-bpf
1023 Try to enable use of seccomp-bpf (see seccomp(2)) to have
1024 ptrace(2)-stops only when system calls that are being
1025 traced occur in the traced processes. This option has no
1026 effect unless -f/--follow-forks is also specified. --sec‐
1027 comp-bpf is not compatible with --syscall-limit and
1028 -b/--detach-on options. It is also not applicable to pro‐
1029 cesses attached using -p/--attach option. An attempt to
1030 enable system calls filtering using seccomp-bpf may fail
1031 for various reasons, e.g. there are too many system calls
1032 to filter, the seccomp API is not available, or strace it‐
1033 self is being traced. In cases when seccomp-bpf filter
1034 setup failed, strace proceeds as usual and stops traced
1035 processes on every system call. When --seccomp-bpf is ac‐
1036 tivated and -p/--attach option is not used, --kill-on-exit
1037 option is activated as well.
1038 --tips[=[[id:]id],[[format:]format]]
1040 Show strace tips, tricks, and tweaks before exit. id can
1041 be a non-negative integer number, which enables printing of
1042 specific tip, trick, or tweak (these ID are not guaranteed
1043 to be stable), or random (the default), in which case a
1044 random tip is printed. format can be one of the following:
1045 none No tip is printed. Can be used to override the
1047 previous setting.
1048 compact Print the tip just big enough to contain all the
1049 text.
1050 full Print the tip in its full glory.
1051 Default is id:random,format:compact.
1053 -V
1055 --version Print the version number of strace. Multiple instances of
1056 the option beyond specific threshold tend to increase
1057 Strauss awareness.
1058 Time specification format description
1060 Time values can be specified as a decimal floating point number (in a
1061 format accepted by strtod(3)), optionally followed by one of the fol‐
1062 lowing suffices that specify the unit of time: s (seconds), ms (mil‐
1063 liseconds), us (microseconds), or ns (nanoseconds). If no suffix is
1064 specified, the value is interpreted as microseconds.
1065 The described format is used for -O, -e inject=delay_enter, and -e in‐
1067 ject=delay_exit options.
1068
1070 When command exits, strace exits with the same exit status. If command
1071 is terminated by a signal, strace terminates itself with the same sig‐
1072 nal, so that strace can be used as a wrapper process transparent to the
1073 invoking parent process. Note that parent-child relationship (signal
1074 stop notifications, getppid(2) value, etc) between traced process and
1075 its parent are not preserved unless -D is used.
1076 When using -p without a command, the exit status of strace is zero un‐
1078 less no processes has been attached or there was an unexpected error in
1079 doing the tracing.
1080
1082 If strace is installed setuid to root then the invoking user will be
1083 able to attach to and trace processes owned by any user. In addition
1084 setuid and setgid programs will be executed and traced with the correct
1085 effective privileges. Since only users trusted with full root privi‐
1086 leges should be allowed to do these things, it only makes sense to in‐
1087 stall strace as setuid to root when the users who can execute it are
1088 restricted to those users who have this trust. For example, it makes
1089 sense to install a special version of strace with mode 'rwsr-xr--',
1090 user root and group trace, where members of the trace group are trusted
1091 users. If you do use this feature, please remember to install a regu‐
1092 lar non-setuid version of strace for ordinary users to use.
1093
1095 On some architectures, strace supports decoding of syscalls for pro‐
1096 cesses that use different ABI rather than the one strace uses. Specif‐
1097 ically, in addition to decoding native ABI, strace can decode the fol‐
1098 lowing ABIs on the following architectures:
1099 ┌───────────────────┬─────────────────────────┐
1101 │Architecture │ ABIs supported │
1102 ├───────────────────┼─────────────────────────┤
1103 │x86_64 │ i386, x32 [1]; i386 [2] │
1104 ├───────────────────┼─────────────────────────┤
1105 │AArch64 │ ARM 32-bit EABI │
1106 ├───────────────────┼─────────────────────────┤
1107 │PowerPC 64-bit [3] │ PowerPC 32-bit │
1108 ├───────────────────┼─────────────────────────┤
1109 │s390x │ s390 │
1110 ├───────────────────┼─────────────────────────┤
1111 │SPARC 64-bit │ SPARC 32-bit │
1112 ├───────────────────┼─────────────────────────┤
1113 │TILE 64-bit │ TILE 32-bit │
1114 └───────────────────┴─────────────────────────┘
1115 [1] When strace is built as an x86_64 application
1116 [2] When strace is built as an x32 application
1117 [3] Big endian only
1118 This support is optional and relies on ability to generate and parse
1120 structure definitions during the build time. Please refer to the out‐
1121 put of the strace -V command in order to figure out what support is
1122 available in your strace build ("non-native" refers to an ABI that dif‐
1123 fers from the ABI strace has):
1124 m32-mpers strace can trace and properly decode non-native 32-bit
1126 binaries.
1127 no-m32-mpers strace can trace, but cannot properly decode non-native
1128 32-bit binaries.
1129 mx32-mpers strace can trace and properly decode non-native
1130 32-on-64-bit binaries.
1131 no-mx32-mpers strace can trace, but cannot properly decode non-native
1132 32-on-64-bit binaries.
1133 If the output contains neither m32-mpers nor no-m32-mpers, then decod‐
1135 ing of non-native 32-bit binaries is not implemented at all or not ap‐
1136 plicable.
1137 Likewise, if the output contains neither mx32-mpers nor no-mx32-mpers,
1139 then decoding of non-native 32-on-64-bit binaries is not implemented at
1140 all or not applicable.
1141
1143 It is a pity that so much tracing clutter is produced by systems em‐
1144 ploying shared libraries.
1145 It is instructive to think about system call inputs and outputs as
1147 data-flow across the user/kernel boundary. Because user-space and ker‐
1148 nel-space are separate and address-protected, it is sometimes possible
1149 to make deductive inferences about process behavior using inputs and
1150 outputs as propositions.
1151 In some cases, a system call will differ from the documented behavior
1153 or have a different name. For example, the faccessat(2) system call
1154 does not have flags argument, and the setrlimit(2) library function
1155 uses prlimit64(2) system call on modern (2.6.38+) kernels. These dis‐
1156 crepancies are normal but idiosyncratic characteristics of the system
1157 call interface and are accounted for by C library wrapper functions.
1158 Some system calls have different names in different architectures and
1160 personalities. In these cases, system call filtering and printing uses
1161 the names that match corresponding __NR_* kernel macros of the tracee's
1162 architecture and personality. There are two exceptions from this gen‐
1163 eral rule: arm_fadvise64_64(2) ARM syscall and xtensa_fadvise64_64(2)
1164 Xtensa syscall are filtered and printed as fadvise64_64(2).
1165 On x32, syscalls that are intended to be used by 64-bit processes and
1167 not x32 ones (for example, readv(2), that has syscall number 19 on
1168 x86_64, with its x32 counterpart has syscall number 515), but called
1169 with __X32_SYSCALL_BIT flag being set, are designated with #64 suffix.
1170 On some platforms a process that is attached to with the -p option may
1172 observe a spurious EINTR return from the current system call that is
1173 not restartable. (Ideally, all system calls should be restarted on
1174 strace attach, making the attach invisible to the traced process, but a
1175 few system calls aren't. Arguably, every instance of such behavior is
1176 a kernel bug.) This may have an unpredictable effect on the process if
1177 the process takes no action to restart the system call.
1178 As strace executes the specified command directly and does not employ a
1180 shell for that, scripts without shebang that usually run just fine when
1181 invoked by shell fail to execute with ENOEXEC error. It is advisable
1182 to manually supply a shell as a command with the script as its argu‐
1183 ment.
1184
1186 Programs that use the setuid bit do not have effective user ID privi‐
1187 leges while being traced.
1188 A traced process runs slowly (but check out the --seccomp-bpf option).
1190 Unless --kill-on-exit option is used (or --seccomp-bpf option is used
1192 in a way that implies --kill-on-exit), traced processes which are de‐
1193 scended from command may be left running after an interrupt signal
1194 (CTRL-C).
1195
1197 The original strace was written by Paul Kranenburg for SunOS and was
1198 inspired by its trace utility. The SunOS version of strace was ported
1199 to Linux and enhanced by Branko Lankester, who also wrote the Linux
1200 kernel support. Even though Paul released strace 2.5 in 1992, Branko's
1201 work was based on Paul's strace 1.5 release from 1991. In 1993, Rick
1202 Sladkey merged strace 2.5 for SunOS and the second release of strace
1203 for Linux, added many of the features of truss(1) from SVR4, and pro‐
1204 duced an strace that worked on both platforms. In 1994 Rick ported
1205 strace to SVR4 and Solaris and wrote the automatic configuration sup‐
1206 port. In 1995 he ported strace to Irix and became tired of writing
1207 about himself in the third person.
1208 Beginning with 1996, strace was maintained by Wichert Akkerman. During
1210 his tenure, strace development migrated to CVS; ports to FreeBSD and
1211 many architectures on Linux (including ARM, IA-64, MIPS, PA-RISC, Pow‐
1212 erPC, s390, SPARC) were introduced. In 2002, the burden of strace
1213 maintainership was transferred to Roland McGrath. Since then, strace
1214 gained support for several new Linux architectures (AMD64, s390x, Su‐
1215 perH), bi-architecture support for some of them, and received numerous
1216 additions and improvements in syscalls decoders on Linux; strace devel‐
1217 opment migrated to Git during that period. Since 2009, strace is ac‐
1218 tively maintained by Dmitry Levin. strace gained support for AArch64,
1219 ARC, AVR32, Blackfin, Meta, Nios II, OpenRISC 1000, RISC-V, Tile/Ti‐
1220 leGx, Xtensa architectures since that time. In 2012, unmaintained and
1221 apparently broken support for non-Linux operating systems was removed.
1222 Also, in 2012 strace gained support for path tracing and file descrip‐
1223 tor path decoding. In 2014, support for stack traces printing was
1224 added. In 2016, syscall fault injection was implemented.
1225 For the additional information, please refer to the NEWS file and
1227 strace repository commit log.
1228
1230 Problems with strace should be reported to the strace mailing list
1231 ⟨mailto:strace-devel@lists.strace.io⟩.
1232
1234 strace-log-merge(1), ltrace(1), perf-trace(1), trace-cmd(1), time(1),
1235 ptrace(2), syscall(2), proc(5), signal(7)
1236 strace Home Page ⟨https://strace.io/⟩
1238
1240 The complete list of strace contributors can be found in the CREDITS
1241 file.
1242strace 6.6 2023-10-13 STRACE(1)