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