1 .\" Copyright (c) 1991, 1992 Paul Kranenburg <pk@cs.few.eur.nl>
2 .\" Copyright (c) 1993 Branko Lankester <branko@hacktic.nl>
3 .\" Copyright (c) 1993, 1994, 1995, 1996 Rick Sladkey <jrs@world.std.com>
4 .\" Copyright (c) 1996-2017 The strace developers.
5 .\" All rights reserved.
7 .\" SPDX-License-Identifier: LGPL-2.1-or-later
20 .\" Like .OP, but with ellipsis at the end in order to signify that option
21 .\" can be provided multiple times. Based on .OP definition in groff's
25 . RI "[\fB\\$1\fP" "\ \\$2" "]...\&"
27 . RB "[" "\\$1" "]...\&"
32 . RI "\fB\\$1\fP" "\ \\$2"
36 .TH STRACE 1 "@MANPAGE_DATE@" "strace @VERSION@"
38 strace \- trace system calls and signals
41 .if '@ENABLE_STACKTRACE_FALSE@'#' .OP \-ACdffhikqqrtttTvVwxxyyzZ
42 .if '@ENABLE_STACKTRACE_TRUE@'#' .OP \-ACdffhiqqrtttTvVwxxyyzZ
57 .OM \-E var\fR[=\fIval\fR]
59 .IR command " [" args ]
77 .OM \-E var\fR[=\fIval\fR]
79 .IR command " [" args ]
83 .IX "strace command" "" "\fLstrace\fR command"
90 It intercepts and records the system calls which are called
91 by a process and the signals which are received by a process.
92 The name of each system call, its arguments and its return value
93 are printed on standard error or to the file specified with the
98 is a useful diagnostic, instructional, and debugging tool.
99 System administrators, diagnosticians and trouble-shooters will find
100 it invaluable for solving problems with
101 programs for which the source is not readily available since
102 they do not need to be recompiled in order to trace them.
103 Students, hackers and the overly-curious will find that
104 a great deal can be learned about a system and its system calls by
105 tracing even ordinary programs. And programmers will find that
106 since system calls and signals are events that happen at the user/kernel
107 interface, a close examination of this boundary is very
108 useful for bug isolation, sanity checking and
109 attempting to capture race conditions.
111 Each line in the trace contains the system call name, followed
112 by its arguments in parentheses and its return value.
113 An example from stracing the command "cat /dev/null" is:
115 open("/dev/null", O_RDONLY) = 3
117 Errors (typically a return value of \-1) have the errno symbol
118 and error string appended.
120 open("/foo/bar", O_RDONLY) = \-1 ENOENT (No such file or directory)
122 Signals are printed as signal symbol and decoded siginfo structure.
123 An excerpt from stracing and interrupting the command "sleep 666" is:
125 sigsuspend([] <unfinished ...>
126 --- SIGINT {si_signo=SIGINT, si_code=SI_USER, si_pid=...} ---
127 +++ killed by SIGINT +++
129 If a system call is being executed and meanwhile another one is being called
130 from a different thread/process then
132 will try to preserve the order of those events and mark the ongoing call as
135 When the call returns it will be marked as
138 [pid 28772] select(4, [3], NULL, NULL, NULL <unfinished ...>
139 [pid 28779] clock_gettime(CLOCK_REALTIME, {1130322148, 939977000}) = 0
140 [pid 28772] <... select resumed> ) = 1 (in [3])
142 Interruption of a (restartable) system call by a signal delivery is processed
143 differently as kernel terminates the system call and also arranges its
144 immediate reexecution after the signal handler completes.
146 read(0, 0x7ffff72cf5cf, 1) = ? ERESTARTSYS (To be restarted)
148 rt_sigreturn(0xe) = 0
151 Arguments are printed in symbolic form with passion.
152 This example shows the shell performing ">>xyzzy" output redirection:
154 open("xyzzy", O_WRONLY|O_APPEND|O_CREAT, 0666) = 3
156 Here, the third argument of
158 is decoded by breaking down the
159 flag argument into its three bitwise-OR constituents and printing the
160 mode value in octal by tradition. Where the traditional or native
161 usage differs from ANSI or POSIX, the latter forms are preferred.
164 output is proven to be more readable than the source.
166 Structure pointers are dereferenced and the members are displayed
167 as appropriate. In most cases, arguments are formatted in the most C-like
169 For example, the essence of the command "ls \-l /dev/null" is captured as:
171 lstat("/dev/null", {st_mode=S_IFCHR|0666, st_rdev=makedev(0x1, 0x3), ...}) = 0
173 Notice how the 'struct stat' argument is dereferenced and how each member is
174 displayed symbolically. In particular, observe how the
176 member is carefully decoded into a bitwise-OR of symbolic and numeric values.
177 Also notice in this example that the first argument to
179 is an input to the system call and the second argument is an output.
180 Since output arguments are not modified if the system call fails, arguments may
181 not always be dereferenced. For example, retrying the "ls \-l" example
182 with a non-existent file produces the following line:
184 lstat("/foo/bar", 0xb004) = \-1 ENOENT (No such file or directory)
186 In this case the porch light is on but nobody is home.
190 are printed raw, with the unknown system call number printed in hexadecimal form
191 and prefixed with "syscall_":
193 syscall_0xbad(0x1, 0x2, 0x3, 0x4, 0x5, 0x6) = -1 ENOSYS (Function not implemented)
196 Character pointers are dereferenced and printed as C strings.
197 Non-printing characters in strings are normally represented by
198 ordinary C escape codes.
201 (32 by default) bytes of strings are printed;
202 longer strings have an ellipsis appended following the closing quote.
203 Here is a line from "ls \-l" where the
205 library routine is reading the password file:
207 read(3, "root::0:0:System Administrator:/"..., 1024) = 422
209 While structures are annotated using curly braces, simple pointers
210 and arrays are printed using square brackets with commas separating
211 elements. Here is an example from the command
213 on a system with supplementary group ids:
215 getgroups(32, [100, 0]) = 2
217 On the other hand, bit-sets are also shown using square brackets,
218 but set elements are separated only by a space.
219 Here is the shell, preparing to execute an external command:
221 sigprocmask(SIG_BLOCK, [CHLD TTOU], []) = 0
223 Here, the second argument is a bit-set of two signals,
224 .BR SIGCHLD " and " SIGTTOU .
225 In some cases, the bit-set is so full that printing out the unset
226 elements is more valuable. In that case, the bit-set is prefixed by
229 sigprocmask(SIG_UNBLOCK, ~[], NULL) = 0
231 Here, the second argument represents the full set of all signals.
236 A qualifying expression which modifies which events to trace
237 or how to trace them. The format of the expression is:
240 [\,\fIqualifier\/\fB=\fR][\fB!\fR][\fB?\fR]\,\fIvalue1\/\fR[\fB,\fR[\fB?\fR]\,\fIvalue2\/\fR]...
260 is a qualifier-dependent symbol or number. The default
263 Using an exclamation mark negates the set of values. For example,
266 .BR \-e "\ " trace = open
267 which in turn means trace only the
269 system call. By contrast,
270 .BR \-e "\ " trace "=!" open
271 means to trace every system call except
273 Question mark before the syscall qualification allows suppression of error
274 in case no syscalls matched the qualification provided.
275 Appending one of "@64", "@32", or "@x32" suffixes to the syscall qualification
276 allows specifying syscalls only for the 64-bit, 32-bit, or 32-on-64-bit
277 personality, respectively.
278 In addition, the special values
282 have the obvious meanings.
284 Note that some shells use the exclamation point for history
285 expansion even inside quoted arguments. If so, you must escape
286 the exclamation point with a backslash.
289 \fB\-E\ \fIvar\fR=\,\fIval\fR
292 in its list of environment variables.
297 from the inherited list of environment variables before passing it on to
301 Attach to the process with the process
305 The trace may be terminated
306 at any time by a keyboard interrupt signal
309 will respond by detaching itself from the traced process(es)
310 leaving it (them) to continue running.
313 options can be used to attach to many processes in addition to
315 (which is optional if at least one
319 "`pidof PROG`" syntax is supported.
322 Run command with the user \s-1ID\s0, group \s-2ID\s0, and
323 supplementary groups of
325 This option is only useful when running as root and enables the
326 correct execution of setuid and/or setgid binaries.
327 Unless this option is used setuid and setgid programs are executed
328 without effective privileges.
332 If specified syscall is reached, detach from traced process.
335 syscall is supported. This option is useful if you want to trace
336 multi-threaded process and therefore require
338 but don't want to trace its (potentially very complex) children.
341 Run tracer process as a grandchild, not as the parent of the
342 tracee. This reduces the visible effect of
344 by keeping the tracee a direct child of the calling process.
347 Run tracer process as tracee's grandchild in a separate process group.
348 In addition to reduction of the visible effect of
350 it also avoids killing of
354 issued to the whole process group.
357 Run tracer process as tracee's grandchild in a separate session
358 ("true daemonisation").
359 In addition to reduction of the visible effect of
361 it also avoids killing of
363 upon session termination.
366 Trace child processes as they are created by currently traced
367 processes as a result of the
372 system calls. Note that
376 will attach all threads of process
378 if it is multi-threaded, not only thread with
379 .IR thread_id " = " PID .
385 option is in effect, each processes trace is written to
389 is the numeric process id of each process.
390 This is incompatible with
392 since no per-process counts are kept.
394 One might want to consider using
395 .BR strace-log-merge (1)
396 to obtain a combined strace log view.
398 .BI "\-I " interruptible
401 can be interrupted by signals (such as pressing
406 no signals are blocked;
409 fatal signals are blocked while decoding syscall (default);
412 fatal signals are always blocked (default if
413 .BR -o " " \fIFILE\fR " " \fIPROG\fR );
417 .BR SIGTSTP " (" CTRL\-Z )
418 are always blocked (useful to make
419 .BI "strace -o " "FILE PROG"
427 \fB\-e\ trace\fR=\,\fIset\fR
428 Trace only the specified set of system calls. The
430 option is useful for determining which system calls might be useful
431 to trace. For example,
432 .BR trace = open,close,read,write
434 trace those four system calls. Be careful when making inferences
435 about the user/kernel boundary if only a subset of system calls
436 are being monitored. The default is
439 \fB\-e\ trace\fR=/\,\fIregex\fR
440 Trace only those system calls that match the
444 Extended Regular Expression syntax (see
447 .BR "\-e\ trace" = %file
449 .BR "\-e\ trace" = file
450 Trace all system calls which take a file name as an argument. You
451 can think of this as an abbreviation for
452 .BR "\-e\ trace" = open , stat , chmod , unlink ,...
453 which is useful to seeing what files the process is referencing.
454 Furthermore, using the abbreviation will ensure that you don't
455 accidentally forget to include a call like
457 in the list. Betchya woulda forgot that one.
458 The syntax without a preceding percent sign
459 .RB (\[dq] "-e trace" = file \[dq])
462 .BR "\-e\ trace" = %process
464 .BR "\-e\ trace" = process
465 Trace all system calls which involve process management. This
466 is useful for watching the fork, wait, and exec steps of a process.
467 The syntax without a preceding percent sign
468 .RB (\[dq] "-e trace" = process \[dq])
471 .BR "\-e\ trace" = %net
473 .BR "\-e\ trace" = %network
475 .BR "\-e\ trace" = network
476 Trace all the network related system calls.
477 The syntax without a preceding percent sign
478 .RB (\[dq] "-e trace" = network \[dq])
481 .BR "\-e\ trace" = %signal
483 .BR "\-e\ trace" = signal
484 Trace all signal related system calls.
485 The syntax without a preceding percent sign
486 .RB (\[dq] "-e trace" = signal \[dq])
489 .BR "\-e\ trace" = %ipc
491 .BR "\-e\ trace" = ipc
492 Trace all IPC related system calls.
493 The syntax without a preceding percent sign
494 .RB (\[dq] "-e trace" = ipc \[dq])
497 .BR "\-e\ trace" = %desc
499 .BR "\-e\ trace" = desc
500 Trace all file descriptor related system calls.
501 The syntax without a preceding percent sign
502 .RB (\[dq] "-e trace" = desc \[dq])
505 .BR "\-e\ trace" = %memory
507 .BR "\-e\ trace" = memory
508 Trace all memory mapping related system calls.
509 The syntax without a preceding percent sign
510 .RB (\[dq] "-e trace" = memory \[dq])
513 .BR "\-e\ trace" = %stat
514 Trace stat syscall variants.
516 .BR "\-e\ trace" = %lstat
517 Trace lstat syscall variants.
519 .BR "\-e\ trace" = %fstat
520 Trace fstat and fstatat syscall variants.
522 .BR "\-e\ trace" = %%stat
523 Trace syscalls used for requesting file status (stat, lstat, fstat, fstatat,
524 statx, and their variants).
526 .BR "\-e\ trace" = %statfs
527 Trace statfs, statfs64, statvfs, osf_statfs, and osf_statfs64 system calls.
528 The same effect can be achieved with
529 .BR "\-e\ trace" = /^(.*_)?statv?fs
532 .BR "\-e\ trace" = %fstatfs
533 Trace fstatfs, fstatfs64, fstatvfs, osf_fstatfs, and osf_fstatfs64 system calls.
534 The same effect can be achieved with
535 .BR "\-e\ trace" = /fstatv?fs
538 .BR "\-e\ trace" = %%statfs
539 Trace syscalls related to file system statistics (statfs-like, fstatfs-like,
540 and ustat). The same effect can be achieved with
541 .BR "\-e\ trace" = /statv?fs|fsstat|ustat
544 .BR "\-e\ trace" = %pure
545 Trace syscalls that always succeed and have no arguments.
546 Currently, this list includes
547 .BR arc_gettls "(2), " getdtablesize "(2), " getegid "(2), " getegid32 "(2),"
548 .BR geteuid "(2), " geteuid32 "(2), " getgid "(2), " getgid32 "(2),"
549 .BR getpagesize "(2), " getpgrp "(2), " getpid "(2), " getppid "(2),"
550 .BR get_thread_area (2)
551 (on architectures other than x86),
552 .BR gettid "(2), " get_tls "(2), " getuid "(2), " getuid32 "(2),"
553 .BR getxgid "(2), " getxpid "(2), " getxuid "(2), " kern_features "(2), and"
554 .BR metag_get_tls "(2)"
557 \fB\-e\ signal\fR=\,\fIset\fR
558 Trace only the specified subset of signals. The default is
561 .BR signal "=!" SIGIO
566 signals not to be traced.
568 \fB\-e\ status\fR=\,\fIset\fR
569 Print only system calls with the specified return status. The default is
575 waits for system calls to return before deciding whether they should be printed
576 or not, the traditional order of events may not be preserved anymore. If two
577 system calls are executed by concurrent threads,
579 will first print both the entry and exit of the first system call to exit,
580 regardless of their respective entry time. The entry and exit of the second
581 system call to exit will be printed afterwards. Here is an example when
583 is called, but a different thread calls
584 .BR clock_gettime (2)
589 [pid 28779] 1130322148.939977 clock_gettime(CLOCK_REALTIME, {1130322148, 939977000}) = 0
590 [pid 28772] 1130322148.438139 select(4, [3], NULL, NULL, NULL) = 1 (in [3])
593 can include the following elements:
597 Trace system calls that returned without an error code.
600 option has the effect of
601 .BR status = successful .
604 Trace system calls that returned with an error code.
607 option has the effect of
608 .BR status = failed .
611 Trace system calls that did not return. This might happen, for example, due to
612 an execve call in a neighbour thread.
615 Trace system calls that returned but strace failed to fetch the error status.
618 Trace system calls for which strace detached before the return.
622 Trace only system calls accessing
626 options can be used to specify several paths.
629 Print only syscalls that returned without an error code.
632 Print only syscalls that returned with an error code.
636 Align return values in a specific column (default column 40).
638 \fB\-e\ abbrev\fR=\,\fIset\fR
639 Abbreviate the output from printing each member of large structures.
644 option has the effect of
647 \fB\-e\ verbose\fR=\,\fIset\fR
648 Dereference structures for the specified set of system calls. The
652 \fB\-e\ raw\fR=\,\fIset\fR
653 Print raw, undecoded arguments for the specified set of system calls.
654 This option has the effect of causing all arguments to be printed
655 in hexadecimal. This is mostly useful if you don't trust the
656 decoding or you need to know the actual numeric value of an
662 \fB\-e\ read\fR=\,\fIset\fR
663 Perform a full hexadecimal and ASCII dump of all the data read from
664 file descriptors listed in the specified set. For example, to see
665 all input activity on file descriptors
670 \fB\-e\ read\fR=\,\fI3\fR,\fI5\fR.
671 Note that this is independent from the normal tracing of the
673 system call which is controlled by the option
674 .BR -e "\ " trace = read .
676 \fB\-e\ write\fR=\,\fIset\fR
677 Perform a full hexadecimal and ASCII dump of all the data written to
678 file descriptors listed in the specified set. For example, to see
679 all output activity on file descriptors
684 \fB\-e\ write\fR=\,\fI3\fR,\,\fI5\fR.
685 Note that this is independent from the normal tracing of the
687 system call which is controlled by the option
688 .BR -e "\ " trace = write .
690 .BR "\-e\ kvm" = vcpu
691 Print the exit reason of kvm vcpu. Requires Linux kernel version 4.16.0
695 Print the instruction pointer at the time of the system call.
696 .if '@ENABLE_STACKTRACE_FALSE@'#' .TP
697 .if '@ENABLE_STACKTRACE_FALSE@'#' .B \-k
698 .if '@ENABLE_STACKTRACE_FALSE@'#' Print the execution stack trace of the traced
699 .if '@ENABLE_STACKTRACE_FALSE@'#' processes after each system call.
702 Write the trace output to the file
704 rather than to stderr.
709 If the argument begins with '|' or '!', the rest of the
710 argument is treated as a command and all output is piped to it.
711 This is convenient for piping the debugging output to a program
712 without affecting the redirections of executed programs.
713 The latter is not compatible with
718 Open the file provided in the
720 option in append mode.
723 Suppress messages about attaching, detaching etc. This happens
724 automatically when output is redirected to a file and the command
725 is run directly instead of attaching.
728 If given twice, suppress messages about process exit status.
731 Print a relative timestamp upon entry to each system call. This
732 records the time difference between the beginning of successive
736 option uses the monotonic clock time for measuring time difference and not the
737 wall clock time, its measurements can differ from the difference in time
743 Specify the maximum string size to print (the default is 32). Note
744 that filenames are not considered strings and are always printed in
748 Prefix each line of the trace with the wall clock time.
751 If given twice, the time printed will include the microseconds.
754 If given thrice, the time printed will include the microseconds
755 and the leading portion will be printed as the number
756 of seconds since the epoch.
759 Show the time spent in system calls. This records the time
760 difference between the beginning and the end of each system call.
763 Print unabbreviated versions of environment, stat, termios, etc.
764 calls. These structures are very common in calls and so the default
765 behavior displays a reasonable subset of structure members. Use
766 this option to get all of the gory details.
769 Print all non-ASCII strings in hexadecimal string format.
772 Print all strings in hexadecimal string format.
775 Set the format for printing of named constants and flags.
782 Raw number output, without decoding.
785 Output a named constant or a set of flags instead of the raw number if they are
792 Output both the raw value and the decoded string (as a comment).
796 Print paths associated with file descriptor arguments.
799 Print protocol specific information associated with socket file descriptors,
800 and block/character device number associated with device file descriptors.
804 Count time, calls, and errors for each system call and report a summary on
805 program exit, suppressing the regular output.
806 This attempts to show system time (CPU time spent running
807 in the kernel) independent of wall clock time. If
811 only aggregate totals for all traced processes are kept.
816 but also print regular output while processes are running.
819 Set the overhead for tracing system calls to
821 This is useful for overriding the default heuristic for guessing
822 how much time is spent in mere measuring when timing system calls using
825 option. The accuracy of the heuristic can be gauged by timing a given
826 program run without tracing (using
828 and comparing the accumulated
829 system call time to the total produced using
834 specification is described in section
835 .IR "Time specification format description".
838 Sort the output of the histogram printed by the
840 option by the specified criterion. Legal values are
841 .BR time " (or " time_total " or " total_time ),
842 .BR calls " (or " count ),
843 .BR errors " (or " error ),
844 .BR name " (or " syscall " or " syscall_name ),
846 .BR nothing " (or " none );
851 Summarise the time difference between the beginning and end of
852 each system call. The default is to summarise the system time.
855 \fB\-e\ inject\fR=\,\fIset\/\fR[:\fBerror\fR=\,\fIerrno\/\fR|:\fBretval\fR=\,\fIvalue\/\fR][:\fBsignal\fR=\,\fIsig\/\fR][:\fBsyscall\fR=\fIsyscall\fR][:\fBdelay_enter\fR=\,\fIdelay\/\fR][:\fBdelay_exit\fR=\,\fIdelay\/\fR][:\fBwhen\fR=\,\fIexpr\/\fR]
856 Perform syscall tampering for the specified set of syscalls.
865 options has to be specified.
869 are mutually exclusive.
871 If :\fBerror\fR=\,\fIerrno\/\fR option is specified,
872 a fault is injected into a syscall invocation:
873 the syscall number is replaced by -1 which corresponds to an invalid syscall
874 (unless a syscall is specified with :\fBsyscall=\fR option),
875 and the error code is specified using a symbolic
879 or a numeric value within 1..4095 range.
881 If :\fBretval\fR=\,\fIvalue\/\fR option is specified,
882 success injection is performed: the syscall number is replaced by -1,
883 but a bogus success value is returned to the callee.
885 If :\fBsignal\fR=\,\fIsig\/\fR option is specified with either a symbolic value
888 or a numeric value within 1..\fBSIGRTMAX\fR range,
889 that signal is delivered on entering every syscall specified by the
892 If :\fBdelay_enter\fR=\,\fIdelay\/\fR or :\fBdelay_exit\fR=\,\fIdelay\/\fR
893 options are specified, delay injection is performed: the tracee is delayed
894 by time period specified by
896 on entering or exiting the syscall, respectively.
899 specification is described in section
900 .IR "Time specification format description".
902 If :\fBsignal\fR=\,\fIsig\/\fR option is specified without
903 :\fBerror\fR=\,\fIerrno\/\fR, :\fBretval\fR=\,\fIvalue\/\fR or
904 :\fBdelay_{enter,exit}\fR=\,\fIusecs\/\fR options,
907 is delivered without a syscall fault or delay injection.
908 Conversely, :\fBerror\fR=\,\fIerrno\/\fR or
909 :\fBretval\fR=\,\fIvalue\/\fR option without
910 :\fBdelay_enter\fR=\,\fIdelay\/\fR,
911 :\fBdelay_exit\fR=\,\fIdelay\/\fR or
912 :\fBsignal\fR=\,\fIsig\/\fR options injects a fault without delivering a signal
913 or injecting a delay, etc.
915 If both :\fBerror\fR=\,\fIerrno\/\fR or :\fBretval\fR=\,\fIvalue\/\fR
916 and :\fBsignal\fR=\,\fIsig\/\fR options are specified, then both
917 a fault or success is injected and a signal is delivered.
919 if :\fBsyscall\fR=\fIsyscall\fR option is specified, the corresponding syscall
920 with no side effects is injected instead of -1.
921 Currently, only "pure" (see
922 .BR "-e trace" = "%pure"
923 description) syscalls can be specified there.
925 Unless a :\fBwhen\fR=\,\fIexpr\fR subexpression is specified,
926 an injection is being made into every invocation of each syscall from the
929 The format of the subexpression is one of the following:
933 For every syscall from the
935 perform an injection for the syscall invocation number
940 For every syscall from the
942 perform injections for the syscall invocation number
944 and all subsequent invocations.
946 \fIfirst\/\fB+\fIstep\fR
947 For every syscall from the
949 perform injections for syscall invocations number
952 .IR first + step + step ,
956 For example, to fail each third and subsequent chdir syscalls with
959 \fB\-e\ inject\fR=\,\fIchdir\/\fR:\fBerror\fR=\,\fIENOENT\/\fR:\fBwhen\fR=\,\fI3\/\fB+\fR.
961 The valid range for numbers
967 An injection expression can contain only one
971 specification, and only one
973 specification. If an injection expression contains multiple
975 specifications, the last one takes precedence.
977 Accounting of syscalls that are subject to injection
978 is done per syscall and per tracee.
980 Specification of syscall injection can be combined
981 with other syscall filtering options, for example,
982 \fB\-P \fI/dev/urandom \fB\-e inject\fR=\,\fIfile\/\fR:\fBerror\fR=\,\fIENOENT\fR.
984 \fB\-e\ fault\fR=\,\fIset\/\fR[:\fBerror\fR=\,\fIerrno\/\fR][:\fBwhen\fR=\,\fIexpr\/\fR]
985 Perform syscall fault injection for the specified set of syscalls.
987 This is equivalent to more generic
988 \fB\-e\ inject\fR= expression with default value of
995 Show some debugging output of
997 itself on the standard error.
1000 This option is deprecated. It is retained for backward compatibility only
1001 and may be removed in future releases.
1002 Usage of multiple instances of
1004 option is still equivalent to a single
1006 and it is ignored at all if used along with one or more instances of
1013 Print the help summary.
1016 Enable (experimental) usage of seccomp-bpf (see
1019 .BR ptrace (2)-stops
1020 only when system calls that are being traced occur in the traced processes.
1024 An attempt to rely on seccomp-bpf to filter system calls may fail for various
1025 reasons, e.g. there are too many system calls to filter, the seccomp API is not
1028 itself is being traced.
1030 is also ineffective on processes attached using
1032 In cases when seccomp-bpf filter setup failed,
1034 proceeds as usual and stops traced processes on every system call.
1039 Print the version number of
1041 .SS "Time specification format description"
1043 Time values can be specified as a decimal floating point number
1044 (in a format accepted by
1046 optionally followed by one of the following suffices that specify
1056 If no suffix is specified, the value is interpreted as microseconds.
1058 The described format is used for
1059 .BR \-O ", " "\-e inject" = delay_enter ", and " "\-e inject" = delay_exit
1066 exits with the same exit status.
1069 is terminated by a signal,
1071 terminates itself with the same signal, so that
1073 can be used as a wrapper process transparent to the invoking parent process.
1074 Note that parent-child relationship (signal stop notifications,
1076 value, etc) between traced process and its parent are not preserved
1087 is zero unless no processes has been attached or there was an unexpected error
1088 in doing the tracing.
1089 .SH "SETUID INSTALLATION"
1092 is installed setuid to root then the invoking user will be able to
1093 attach to and trace processes owned by any user.
1094 In addition setuid and setgid programs will be executed and traced
1095 with the correct effective privileges.
1096 Since only users trusted with full root privileges should be allowed
1098 it only makes sense to install
1100 as setuid to root when the users who can execute it are restricted
1101 to those users who have this trust.
1102 For example, it makes sense to install a special version of
1104 with mode 'rwsr-xr--', user
1108 where members of the
1110 group are trusted users.
1111 If you do use this feature, please remember to install
1112 a regular non-setuid version of
1114 for ordinary users to use.
1115 .SH "MULTIPLE PERSONALITY SUPPORT"
1116 On some architectures,
1118 supports decoding of syscalls for processes that use different ABI rather than
1122 Specifically, in addition to decoding native ABI,
1124 can decode the following ABIs on the following architectures:
1129 Architecture ABIs supported
1130 x86_64 i386, x32 [1]; i386 [2]
1131 AArch64 ARM 32-bit EABI
1132 PowerPC 64-bit [3] PowerPC 32-bit
1134 SPARC 64-bit SPARC 32-bit
1135 TILE 64-bit TILE 32-bit
1142 is built as an x86_64 application
1147 is built as an x32 application
1153 This support is optional and relies on ability to generate and parse structure
1154 definitions during the build time.
1155 Please refer to the output of the
1157 command in order to figure out what support is available in your
1159 build ("non-native" refers to an ABI that differs from the ABI
1165 can trace and properly decode non-native 32-bit binaries.
1169 can trace, but cannot properly decode non-native 32-bit binaries.
1173 can trace and properly decode non-native 32-on-64-bit binaries.
1177 can trace, but cannot properly decode non-native 32-on-64-bit binaries.
1179 If the output contains neither
1183 then decoding of non-native 32-bit binaries is not implemented at all
1186 Likewise, if the output contains neither
1190 then decoding of non-native 32-on-64-bit binaries is not implemented at all
1193 It is a pity that so much tracing clutter is produced by systems
1194 employing shared libraries.
1196 It is instructive to think about system call inputs and outputs
1197 as data-flow across the user/kernel boundary. Because user-space
1198 and kernel-space are separate and address-protected, it is
1199 sometimes possible to make deductive inferences about process
1200 behavior using inputs and outputs as propositions.
1202 In some cases, a system call will differ from the documented behavior
1203 or have a different name. For example, the
1205 system call does not have
1209 library function uses
1211 system call on modern (2.6.38+) kernels. These
1212 discrepancies are normal but idiosyncratic characteristics of the
1213 system call interface and are accounted for by C library wrapper
1216 Some system calls have different names in different architectures and
1217 personalities. In these cases, system call filtering and printing
1218 uses the names that match corresponding
1220 kernel macros of the tracee's architecture and personality.
1221 There are two exceptions from this general rule:
1222 .BR arm_fadvise64_64 (2)
1224 .BR xtensa_fadvise64_64 (2)
1225 Xtensa syscall are filtered and printed as
1226 .BR fadvise64_64 (2).
1228 On x32, syscalls that are intended to be used by 64-bit processes and not x32
1231 that has syscall number 19 on x86_64, with its x32 counterpart has syscall
1232 number 515), but called with
1233 .B __X32_SYSCALL_BIT
1234 flag being set, are designated with
1238 On some platforms a process that is attached to with the
1240 option may observe a spurious
1242 return from the current system call that is not restartable.
1243 (Ideally, all system calls should be restarted on
1245 attach, making the attach invisible
1246 to the traced process, but a few system calls aren't.
1247 Arguably, every instance of such behavior is a kernel bug.)
1248 This may have an unpredictable effect on the process
1249 if the process takes no action to restart the system call.
1253 executes the specified
1255 directly and does not employ a shell for that, scripts without shebang
1256 that usually run just fine when invoked by shell fail to execute with
1259 It is advisable to manually supply a shell as a
1261 with the script as its argument.
1263 Programs that use the
1268 privileges while being traced.
1270 A traced process runs slowly.
1272 Traced processes which are descended from
1274 may be left running after an interrupt signal
1279 was written by Paul Kranenburg
1280 for SunOS and was inspired by its
1283 The SunOS version of
1285 was ported to Linux and enhanced
1286 by Branko Lankester, who also wrote the Linux kernel support.
1287 Even though Paul released
1290 Branko's work was based on Paul's
1292 1.5 release from 1991.
1293 In 1993, Rick Sladkey merged
1295 2.5 for SunOS and the second release of
1297 for Linux, added many of the features of
1299 from SVR4, and produced an
1301 that worked on both platforms. In 1994 Rick ported
1303 to SVR4 and Solaris and wrote the
1304 automatic configuration support. In 1995 he ported
1307 and tired of writing about himself in the third person.
1309 Beginning with 1996,
1311 was maintained by Wichert Akkerman.
1314 development migrated to CVS; ports to FreeBSD and many architectures on Linux
1315 (including ARM, IA-64, MIPS, PA-RISC, PowerPC, s390, SPARC) were introduced.
1316 In 2002, the burden of
1318 maintainership was transferred to Roland McGrath.
1321 gained support for several new Linux architectures (AMD64, s390x, SuperH),
1322 bi-architecture support for some of them, and received numerous additions and
1323 improvements in syscalls decoders on Linux;
1325 development migrated to
1330 is actively maintained by Dmitry Levin.
1332 gained support for AArch64, ARC, AVR32, Blackfin, Meta, Nios II, OpenSISC 1000,
1333 RISC-V, Tile/TileGx, Xtensa architectures since that time.
1334 In 2012, unmaintained and apparently broken support for non-Linux operating
1335 systems was removed.
1338 gained support for path tracing and file descriptor path decoding.
1339 In 2014, support for stack traces printing was added.
1340 In 2016, syscall fault injection was implemented.
1342 For the additional information, please refer to the
1346 repository commit log.
1350 should be reported to the
1352 mailing list at <strace\-devel@lists.strace.io>.
1354 .BR strace-log-merge (1),
1362 .UR https://strace.io/
1367 The complete list of
1369 contributors can be found in the
projects / strace / blob