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 ]
84 .IX "strace command" "" "\fLstrace\fR command"
91 It intercepts and records the system calls which are called
92 by a process and the signals which are received by a process.
93 The name of each system call, its arguments and its return value
94 are printed on standard error or to the file specified with the
99 is a useful diagnostic, instructional, and debugging tool.
100 System administrators, diagnosticians and trouble-shooters will find
101 it invaluable for solving problems with
102 programs for which the source is not readily available since
103 they do not need to be recompiled in order to trace them.
104 Students, hackers and the overly-curious will find that
105 a great deal can be learned about a system and its system calls by
106 tracing even ordinary programs. And programmers will find that
107 since system calls and signals are events that happen at the user/kernel
108 interface, a close examination of this boundary is very
109 useful for bug isolation, sanity checking and
110 attempting to capture race conditions.
112 Each line in the trace contains the system call name, followed
113 by its arguments in parentheses and its return value.
114 An example from stracing the command "cat /dev/null" is:
116 open("/dev/null", O_RDONLY) = 3
118 Errors (typically a return value of \-1) have the errno symbol
119 and error string appended.
121 open("/foo/bar", O_RDONLY) = \-1 ENOENT (No such file or directory)
123 Signals are printed as signal symbol and decoded siginfo structure.
124 An excerpt from stracing and interrupting the command "sleep 666" is:
126 sigsuspend([] <unfinished ...>
127 --- SIGINT {si_signo=SIGINT, si_code=SI_USER, si_pid=...} ---
128 +++ killed by SIGINT +++
130 If a system call is being executed and meanwhile another one is being called
131 from a different thread/process then
133 will try to preserve the order of those events and mark the ongoing call as
136 When the call returns it will be marked as
139 [pid 28772] select(4, [3], NULL, NULL, NULL <unfinished ...>
140 [pid 28779] clock_gettime(CLOCK_REALTIME, {1130322148, 939977000}) = 0
141 [pid 28772] <... select resumed> ) = 1 (in [3])
143 Interruption of a (restartable) system call by a signal delivery is processed
144 differently as kernel terminates the system call and also arranges its
145 immediate reexecution after the signal handler completes.
147 read(0, 0x7ffff72cf5cf, 1) = ? ERESTARTSYS (To be restarted)
149 rt_sigreturn(0xe) = 0
152 Arguments are printed in symbolic form with passion.
153 This example shows the shell performing ">>xyzzy" output redirection:
155 open("xyzzy", O_WRONLY|O_APPEND|O_CREAT, 0666) = 3
157 Here, the third argument of
159 is decoded by breaking down the
160 flag argument into its three bitwise-OR constituents and printing the
161 mode value in octal by tradition. Where the traditional or native
162 usage differs from ANSI or POSIX, the latter forms are preferred.
165 output is proven to be more readable than the source.
167 Structure pointers are dereferenced and the members are displayed
168 as appropriate. In most cases, arguments are formatted in the most C-like
170 For example, the essence of the command "ls \-l /dev/null" is captured as:
172 lstat("/dev/null", {st_mode=S_IFCHR|0666, st_rdev=makedev(0x1, 0x3), ...}) = 0
174 Notice how the 'struct stat' argument is dereferenced and how each member is
175 displayed symbolically. In particular, observe how the
177 member is carefully decoded into a bitwise-OR of symbolic and numeric values.
178 Also notice in this example that the first argument to
180 is an input to the system call and the second argument is an output.
181 Since output arguments are not modified if the system call fails, arguments may
182 not always be dereferenced. For example, retrying the "ls \-l" example
183 with a non-existent file produces the following line:
185 lstat("/foo/bar", 0xb004) = \-1 ENOENT (No such file or directory)
187 In this case the porch light is on but nobody is home.
191 are printed raw, with the unknown system call number printed in hexadecimal form
192 and prefixed with "syscall_":
194 syscall_0xbad(0x1, 0x2, 0x3, 0x4, 0x5, 0x6) = -1 ENOSYS (Function not implemented)
197 Character pointers are dereferenced and printed as C strings.
198 Non-printing characters in strings are normally represented by
199 ordinary C escape codes.
202 (32 by default) bytes of strings are printed;
203 longer strings have an ellipsis appended following the closing quote.
204 Here is a line from "ls \-l" where the
206 library routine is reading the password file:
208 read(3, "root::0:0:System Administrator:/"..., 1024) = 422
210 While structures are annotated using curly braces, simple pointers
211 and arrays are printed using square brackets with commas separating
212 elements. Here is an example from the command
214 on a system with supplementary group ids:
216 getgroups(32, [100, 0]) = 2
218 On the other hand, bit-sets are also shown using square brackets
219 but set elements are separated only by a space. Here is the shell,
220 preparing to execute an external command:
222 sigprocmask(SIG_BLOCK, [CHLD TTOU], []) = 0
224 Here, the second argument is a bit-set of two signals,
225 .BR SIGCHLD " and " SIGTTOU .
226 In some cases, the bit-set is so full that printing out the unset
227 elements is more valuable. In that case, the bit-set is prefixed by
230 sigprocmask(SIG_UNBLOCK, ~[], NULL) = 0
232 Here, the second argument represents the full set of all signals.
237 A qualifying expression which modifies which events to trace
238 or how to trace them. The format of the expression is:
241 [\,\fIqualifier\/\fB=\fR][\fB!\fR][\fB?\fR]\,\fIvalue1\/\fR[\fB,\fR[\fB?\fR]\,\fIvalue2\/\fR]...
261 is a qualifier-dependent symbol or number. The default
264 Using an exclamation mark negates the set of values. For example,
267 .BR \-e "\ " trace = open
268 which in turn means trace only the
270 system call. By contrast,
271 .BR \-e "\ " trace "=!" open
272 means to trace every system call except
274 Question mark before the syscall qualification allows suppression of error
275 in case no syscalls matched the qualification provided.
276 Appending one of "@64", "@32", or "@x32" suffixes to the syscall qualification
277 allows specifying syscalls only for the 64-bit, 32-bit, or 32-on-64-bit
278 personality, respectively.
279 In addition, the special values
283 have the obvious meanings.
285 Note that some shells use the exclamation point for history
286 expansion even inside quoted arguments. If so, you must escape
287 the exclamation point with a backslash.
290 \fB\-E\ \fIvar\fR=\,\fIval\fR
293 in its list of environment variables.
298 from the inherited list of environment variables before passing it on to
302 Attach to the process with the process
306 The trace may be terminated
307 at any time by a keyboard interrupt signal
310 will respond by detaching itself from the traced process(es)
311 leaving it (them) to continue running.
314 options can be used to attach to many processes in addition to
316 (which is optional if at least one
320 "`pidof PROG`" syntax is supported.
323 Run command with the user \s-1ID\s0, group \s-2ID\s0, and
324 supplementary groups of
326 This option is only useful when running as root and enables the
327 correct execution of setuid and/or setgid binaries.
328 Unless this option is used setuid and setgid programs are executed
329 without effective privileges.
333 If specified syscall is reached, detach from traced process.
336 syscall is supported. This option is useful if you want to trace
337 multi-threaded process and therefore require
339 but don't want to trace its (potentially very complex) children.
342 Run tracer process as a detached grandchild, not as parent of the
343 tracee. This reduces the visible effect of
345 by keeping the tracee a direct child of the calling process.
348 Trace child processes as they are created by currently traced
349 processes as a result of the
354 system calls. Note that
358 will attach all threads of process
360 if it is multi-threaded, not only thread with
361 .IR thread_id " = " PID .
367 option is in effect, each processes trace is written to
371 is the numeric process id of each process.
372 This is incompatible with
374 since no per-process counts are kept.
376 One might want to consider using
377 .BR strace-log-merge (1)
378 to obtain a combined strace log view.
380 .BI "\-I " interruptible
383 can be interrupted by signals (such as pressing
388 no signals are blocked;
391 fatal signals are blocked while decoding syscall (default);
394 fatal signals are always blocked (default if
395 .BR -o " " \fIFILE\fR " " \fIPROG\fR );
399 .BR SIGTSTP " (" CTRL\-Z )
400 are always blocked (useful to make
401 .BI "strace -o " "FILE PROG"
409 \fB\-e\ trace\fR=\,\fIset\fR
410 Trace only the specified set of system calls. The
412 option is useful for determining which system calls might be useful
413 to trace. For example,
414 .BR trace = open,close,read,write
416 trace those four system calls. Be careful when making inferences
417 about the user/kernel boundary if only a subset of system calls
418 are being monitored. The default is
421 \fB\-e\ trace\fR=/\,\fIregex\fR
422 Trace only those system calls that match the
426 Extended Regular Expression syntax (see
429 .BR "\-e\ trace" = %file
431 .BR "\-e\ trace" = file
432 Trace all system calls which take a file name as an argument. You
433 can think of this as an abbreviation for
434 .BR "\-e\ trace" = open , stat , chmod , unlink ,...
435 which is useful to seeing what files the process is referencing.
436 Furthermore, using the abbreviation will ensure that you don't
437 accidentally forget to include a call like
439 in the list. Betchya woulda forgot that one.
440 The syntax without a preceding percent sign
441 .RB (\[dq] "-e trace" = file \[dq])
444 .BR "\-e\ trace" = %process
446 .BR "\-e\ trace" = process
447 Trace all system calls which involve process management. This
448 is useful for watching the fork, wait, and exec steps of a process.
449 The syntax without a preceding percent sign
450 .RB (\[dq] "-e trace" = process \[dq])
453 .BR "\-e\ trace" = %net
455 .BR "\-e\ trace" = %network
457 .BR "\-e\ trace" = network
458 Trace all the network related system calls.
459 The syntax without a preceding percent sign
460 .RB (\[dq] "-e trace" = network \[dq])
463 .BR "\-e\ trace" = %signal
465 .BR "\-e\ trace" = signal
466 Trace all signal related system calls.
467 The syntax without a preceding percent sign
468 .RB (\[dq] "-e trace" = signal \[dq])
471 .BR "\-e\ trace" = %ipc
473 .BR "\-e\ trace" = ipc
474 Trace all IPC related system calls.
475 The syntax without a preceding percent sign
476 .RB (\[dq] "-e trace" = ipc \[dq])
479 .BR "\-e\ trace" = %desc
481 .BR "\-e\ trace" = desc
482 Trace all file descriptor related system calls.
483 The syntax without a preceding percent sign
484 .RB (\[dq] "-e trace" = desc \[dq])
487 .BR "\-e\ trace" = %memory
489 .BR "\-e\ trace" = memory
490 Trace all memory mapping related system calls.
491 The syntax without a preceding percent sign
492 .RB (\[dq] "-e trace" = memory \[dq])
495 .BR "\-e\ trace" = %stat
496 Trace stat syscall variants.
498 .BR "\-e\ trace" = %lstat
499 Trace lstat syscall variants.
501 .BR "\-e\ trace" = %fstat
502 Trace fstat and fstatat syscall variants.
504 .BR "\-e\ trace" = %%stat
505 Trace syscalls used for requesting file status (stat, lstat, fstat, fstatat,
506 statx, and their variants).
508 .BR "\-e\ trace" = %statfs
509 Trace statfs, statfs64, statvfs, osf_statfs, and osf_statfs64 system calls.
510 The same effect can be achieved with
511 .BR "\-e\ trace" = /^(.*_)?statv?fs
514 .BR "\-e\ trace" = %fstatfs
515 Trace fstatfs, fstatfs64, fstatvfs, osf_fstatfs, and osf_fstatfs64 system calls.
516 The same effect can be achieved with
517 .BR "\-e\ trace" = /fstatv?fs
520 .BR "\-e\ trace" = %%statfs
521 Trace syscalls related to file system statistics (statfs-like, fstatfs-like,
522 and ustat). The same effect can be achieved with
523 .BR "\-e\ trace" = /statv?fs|fsstat|ustat
526 .BR "\-e\ trace" = %pure
527 Trace syscalls that always succeed and have no arguments.
528 Currently, this list includes
529 .BR arc_gettls "(2), " getdtablesize "(2), " getegid "(2), " getegid32 "(2),"
530 .BR geteuid "(2), " geteuid32 "(2), " getgid "(2), " getgid32 "(2),"
531 .BR getpagesize "(2), " getpgrp "(2), " getpid "(2), " getppid "(2),"
532 .BR get_thread_area (2)
533 (on architectures other than x86),
534 .BR gettid "(2), " get_tls "(2), " getuid "(2), " getuid32 "(2),"
535 .BR getxgid "(2), " getxpid "(2), " getxuid "(2), " kern_features "(2), and"
536 .BR metag_get_tls "(2)"
539 \fB\-e\ signal\fR=\,\fIset\fR
540 Trace only the specified subset of signals. The default is
543 .BR signal "=!" SIGIO
548 signals not to be traced.
550 \fB\-e\ status\fR=\,\fIset\fR
551 Print only system calls with the specified return status. The default is
557 waits for system calls to return before deciding whether they should be printed
558 or not, the traditional order of events may not be preserved anymore. If two
559 system calls are executed by concurrent threads,
561 will first print both the entry and exit of the first system call to exit,
562 regardless of their respective entry time. The entry and exit of the second
563 system call to exit will be printed afterwards. Here is an example when
565 is called, but a different thread calls
566 .BR clock_gettime (2)
571 [pid 28779] 1130322148.939977 clock_gettime(CLOCK_REALTIME, {1130322148, 939977000}) = 0
572 [pid 28772] 1130322148.438139 select(4, [3], NULL, NULL, NULL) = 1 (in [3])
575 can include the following elements:
579 Trace system calls that returned without an error code.
582 option has the effect of
583 .BR status = successful .
586 Trace system calls that returned with an error code.
589 option has the effect of
590 .BR status = failed .
593 Trace system calls that did not return. This might happen, for example, due to
594 an execve call in a neighbour thread.
597 Trace system calls that returned but strace failed to fetch the error status.
600 Trace system calls for which strace detached before the return.
604 Trace only system calls accessing
608 options can be used to specify several paths.
611 Print only syscalls that returned without an error code.
614 Print only syscalls that returned with an error code.
618 Align return values in a specific column (default column 40).
620 \fB\-e\ abbrev\fR=\,\fIset\fR
621 Abbreviate the output from printing each member of large structures.
626 option has the effect of
629 \fB\-e\ verbose\fR=\,\fIset\fR
630 Dereference structures for the specified set of system calls. The
634 \fB\-e\ raw\fR=\,\fIset\fR
635 Print raw, undecoded arguments for the specified set of system calls.
636 This option has the effect of causing all arguments to be printed
637 in hexadecimal. This is mostly useful if you don't trust the
638 decoding or you need to know the actual numeric value of an
644 \fB\-e\ read\fR=\,\fIset\fR
645 Perform a full hexadecimal and ASCII dump of all the data read from
646 file descriptors listed in the specified set. For example, to see
647 all input activity on file descriptors
652 \fB\-e\ read\fR=\,\fI3\fR,\fI5\fR.
653 Note that this is independent from the normal tracing of the
655 system call which is controlled by the option
656 .BR -e "\ " trace = read .
658 \fB\-e\ write\fR=\,\fIset\fR
659 Perform a full hexadecimal and ASCII dump of all the data written to
660 file descriptors listed in the specified set. For example, to see
661 all output activity on file descriptors
666 \fB\-e\ write\fR=\,\fI3\fR,\,\fI5\fR.
667 Note that this is independent from the normal tracing of the
669 system call which is controlled by the option
670 .BR -e "\ " trace = write .
672 .BR "\-e\ kvm" = vcpu
673 Print the exit reason of kvm vcpu. Requires Linux kernel version 4.16.0
678 Print the instruction pointer at the time of the system call.
679 .if '@ENABLE_STACKTRACE_FALSE@'#' .TP
680 .if '@ENABLE_STACKTRACE_FALSE@'#' .B \-k
681 .if '@ENABLE_STACKTRACE_FALSE@'#' Print the execution stack trace of the traced
682 .if '@ENABLE_STACKTRACE_FALSE@'#' processes after each system call.
685 Write the trace output to the file
687 rather than to stderr.
692 If the argument begins with '|' or '!', the rest of the
693 argument is treated as a command and all output is piped to it.
694 This is convenient for piping the debugging output to a program
695 without affecting the redirections of executed programs.
696 The latter is not compatible with
701 Open the file provided in the
703 option in append mode.
706 Suppress messages about attaching, detaching etc. This happens
707 automatically when output is redirected to a file and the command
708 is run directly instead of attaching.
711 If given twice, suppress messages about process exit status.
714 Print a relative timestamp upon entry to each system call. This
715 records the time difference between the beginning of successive
719 option uses the monotonic clock time for measuring time difference and not the
720 wall clock time, its measurements can differ from the difference in time
726 Specify the maximum string size to print (the default is 32). Note
727 that filenames are not considered strings and are always printed in
731 Prefix each line of the trace with the wall clock time.
734 If given twice, the time printed will include the microseconds.
737 If given thrice, the time printed will include the microseconds
738 and the leading portion will be printed as the number
739 of seconds since the epoch.
742 Show the time spent in system calls. This records the time
743 difference between the beginning and the end of each system call.
746 Print unabbreviated versions of environment, stat, termios, etc.
747 calls. These structures are very common in calls and so the default
748 behavior displays a reasonable subset of structure members. Use
749 this option to get all of the gory details.
752 Print all non-ASCII strings in hexadecimal string format.
755 Print all strings in hexadecimal string format.
758 Set the format for printing of named constants and flags.
765 Raw number output, without decoding.
768 Output a named constant or a set of flags instead of the raw number if they are
775 Output both the raw value and the decoded string (as a comment).
779 Print paths associated with file descriptor arguments.
782 Print protocol specific information associated with socket file descriptors,
783 and block/character device number associated with device file descriptors.
787 Count time, calls, and errors for each system call and report a summary on
788 program exit, suppressing the regular output.
789 This attempts to show system time (CPU time spent running
790 in the kernel) independent of wall clock time. If
794 only aggregate totals for all traced processes are kept.
799 but also print regular output while processes are running.
802 Set the overhead for tracing system calls to
805 This is useful for overriding the default heuristic for guessing
806 how much time is spent in mere measuring when timing system calls using
809 option. The accuracy of the heuristic can be gauged by timing a given
810 program run without tracing (using
812 and comparing the accumulated
813 system call time to the total produced using
817 Sort the output of the histogram printed by the
819 option by the specified criterion. Legal values are
820 .BR time " (or " time_total " or " total_time ),
821 .BR calls " (or " count ),
822 .BR errors " (or " error ),
823 .BR name " (or " syscall " or " syscall_name ),
825 .BR nothing " (or " none );
830 Summarise the time difference between the beginning and end of
831 each system call. The default is to summarise the system time.
834 \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=\,\fIusecs\/\fR][:\fBdelay_exit\fR=\,\fIusecs\/\fR][:\fBwhen\fR=\,\fIexpr\/\fR]
835 Perform syscall tampering for the specified set of syscalls.
844 options has to be specified.
848 are mutually exclusive.
850 If :\fBerror\fR=\,\fIerrno\/\fR option is specified,
851 a fault is injected into a syscall invocation:
852 the syscall number is replaced by -1 which corresponds to an invalid syscall
853 (unless a syscall is specified with :\fBsyscall=\fR option),
854 and the error code is specified using a symbolic
858 or a numeric value within 1..4095 range.
860 If :\fBretval\fR=\,\fIvalue\/\fR option is specified,
861 success injection is performed: the syscall number is replaced by -1,
862 but a bogus success value is returned to the callee.
864 If :\fBsignal\fR=\,\fIsig\/\fR option is specified with either a symbolic value
867 or a numeric value within 1..\fBSIGRTMAX\fR range,
868 that signal is delivered on entering every syscall specified by the
871 If :\fBdelay_enter\fR=\,\fIusecs\/\fR or :\fBdelay_exit\fR=\,\fIusecs\/\fR
872 options are specified, delay injection is performed: the tracee is delayed
875 microseconds on entering or exiting the syscall.
877 If :\fBsignal\fR=\,\fIsig\/\fR option is specified without
878 :\fBerror\fR=\,\fIerrno\/\fR, :\fBretval\fR=\,\fIvalue\/\fR or
879 :\fBdelay_{enter,exit}\fR=\,\fIusecs\/\fR options,
882 is delivered without a syscall fault or delay injection.
883 Conversely, :\fBerror\fR=\,\fIerrno\/\fR or
884 :\fBretval\fR=\,\fIvalue\/\fR option without
885 :\fBdelay_enter\fR=\,\fIusecs\/\fR,
886 :\fBdelay_exit\fR=\,\fIusecs\/\fR or
887 :\fBsignal\fR=\,\fIsig\/\fR options injects a fault without delivering a signal
888 or injecting a delay, etc.
890 If both :\fBerror\fR=\,\fIerrno\/\fR or :\fBretval\fR=\,\fIvalue\/\fR
891 and :\fBsignal\fR=\,\fIsig\/\fR options are specified, then both
892 a fault or success is injected and a signal is delivered.
894 if :\fBsyscall\fR=\fIsyscall\fR option is specified, the corresponding syscall
895 with no side effects is injected instead of -1.
896 Currently, only "pure" (see
897 .BR "-e trace" = "%pure"
898 description) syscalls can be specified there.
900 Unless a :\fBwhen\fR=\,\fIexpr\fR subexpression is specified,
901 an injection is being made into every invocation of each syscall from the
904 The format of the subexpression is one of the following:
908 For every syscall from the
910 perform an injection for the syscall invocation number
915 For every syscall from the
917 perform injections for the syscall invocation number
919 and all subsequent invocations.
921 \fIfirst\/\fB+\fIstep\fR
922 For every syscall from the
924 perform injections for syscall invocations number
927 .IR first + step + step ,
931 For example, to fail each third and subsequent chdir syscalls with
934 \fB\-e\ inject\fR=\,\fIchdir\/\fR:\fBerror\fR=\,\fIENOENT\/\fR:\fBwhen\fR=\,\fI3\/\fB+\fR.
936 The valid range for numbers
942 An injection expression can contain only one
946 specification, and only one
948 specification. If an injection expression contains multiple
950 specifications, the last one takes precedence.
952 Accounting of syscalls that are subject to injection
953 is done per syscall and per tracee.
955 Specification of syscall injection can be combined
956 with other syscall filtering options, for example,
957 \fB\-P \fI/dev/urandom \fB\-e inject\fR=\,\fIfile\/\fR:\fBerror\fR=\,\fIENOENT\fR.
960 \fB\-e\ fault\fR=\,\fIset\/\fR[:\fBerror\fR=\,\fIerrno\/\fR][:\fBwhen\fR=\,\fIexpr\/\fR]
961 Perform syscall fault injection for the specified set of syscalls.
963 This is equivalent to more generic
964 \fB\-e\ inject\fR= expression with default value of
971 Show some debugging output of
973 itself on the standard error.
976 Enable (experimental) usage of seccomp-bpf to have ptrace(2)-stops only when
977 system calls that are being traced occur in the traced processes. Implies the
980 An attempt to rely on seccomp-bpf to filter system calls may fail for various
981 reasons, e.g. there are too many system calls to filter, the seccomp API is not
984 itself is being traced.
986 is also ineffective on processes attached using
988 In cases when seccomp-bpf filter setup failed,
990 proceeds as usual and stops traced processes on every system call.
993 This option is deprecated. It is retained for backward compatibility only
994 and may be removed in future releases.
995 Usage of multiple instances of
997 option is still equivalent to a single
999 and it is ignored at all if used along with one or more instances of
1006 Print the help summary.
1011 Print the version number of
1018 exits with the same exit status.
1021 is terminated by a signal,
1023 terminates itself with the same signal, so that
1025 can be used as a wrapper process transparent to the invoking parent process.
1026 Note that parent-child relationship (signal stop notifications,
1028 value, etc) between traced process and its parent are not preserved
1039 is zero unless no processes has been attached or there was an unexpected error
1040 in doing the tracing.
1041 .SH "SETUID INSTALLATION"
1044 is installed setuid to root then the invoking user will be able to
1045 attach to and trace processes owned by any user.
1046 In addition setuid and setgid programs will be executed and traced
1047 with the correct effective privileges.
1048 Since only users trusted with full root privileges should be allowed
1050 it only makes sense to install
1052 as setuid to root when the users who can execute it are restricted
1053 to those users who have this trust.
1054 For example, it makes sense to install a special version of
1056 with mode 'rwsr-xr--', user
1060 where members of the
1062 group are trusted users.
1063 If you do use this feature, please remember to install
1064 a regular non-setuid version of
1066 for ordinary users to use.
1067 .SH "MULTIPLE PERSONALITY SUPPORT"
1068 On some architectures,
1070 supports decoding of syscalls for processes that use different ABI rather than
1074 Specifically, in addition to decoding native ABI,
1076 can decode the following ABIs on the following architectures:
1081 Architecture ABIs supported
1082 x86_64 i386, x32 [1]; i386 [2]
1083 AArch64 ARM 32-bit EABI
1084 PowerPC 64-bit [3] PowerPC 32-bit
1086 SPARC 64-bit SPARC 32-bit
1087 TILE 64-bit TILE 32-bit
1094 is built as an x86_64 application
1099 is built as an x32 application
1105 This support is optional and relies on ability to generate and parse structure
1106 definitions during the build time.
1107 Please refer to the output of the
1109 command in order to figure out what support is available in your
1111 build ("non-native" refers to an ABI that differs from the ABI
1117 can trace and properly decode non-native 32-bit binaries.
1121 can trace, but cannot properly decode non-native 32-bit binaries.
1125 can trace and properly decode non-native 32-on-64-bit binaries.
1129 can trace, but cannot properly decode non-native 32-on-64-bit binaries.
1131 If the output contains neither
1135 then decoding of non-native 32-bit binaries is not implemented at all
1138 Likewise, if the output contains neither
1142 then decoding of non-native 32-on-64-bit binaries is not implemented at all
1145 It is a pity that so much tracing clutter is produced by systems
1146 employing shared libraries.
1148 It is instructive to think about system call inputs and outputs
1149 as data-flow across the user/kernel boundary. Because user-space
1150 and kernel-space are separate and address-protected, it is
1151 sometimes possible to make deductive inferences about process
1152 behavior using inputs and outputs as propositions.
1154 In some cases, a system call will differ from the documented behavior
1155 or have a different name. For example, the
1157 system call does not have
1161 library function uses
1163 system call on modern (2.6.38+) kernels. These
1164 discrepancies are normal but idiosyncratic characteristics of the
1165 system call interface and are accounted for by C library wrapper
1168 Some system calls have different names in different architectures and
1169 personalities. In these cases, system call filtering and printing
1170 uses the names that match corresponding
1172 kernel macros of the tracee's architecture and personality.
1173 There are two exceptions from this general rule:
1174 .BR arm_fadvise64_64 (2)
1176 .BR xtensa_fadvise64_64 (2)
1177 Xtensa syscall are filtered and printed as
1178 .BR fadvise64_64 (2).
1180 On x32, syscalls that are intended to be used by 64-bit processes and not x32
1183 that has syscall number 19 on x86_64, with its x32 counterpart has syscall
1184 number 515), but called with
1185 .B __X32_SYSCALL_BIT
1186 flag being set, are designated with
1190 On some platforms a process that is attached to with the
1192 option may observe a spurious
1194 return from the current system call that is not restartable.
1195 (Ideally, all system calls should be restarted on
1197 attach, making the attach invisible
1198 to the traced process, but a few system calls aren't.
1199 Arguably, every instance of such behavior is a kernel bug.)
1200 This may have an unpredictable effect on the process
1201 if the process takes no action to restart the system call.
1205 executes the specified
1207 directly and does not employ a shell for that, scripts without shebang
1208 that usually run just fine when invoked by shell fail to execute with
1211 It is advisable to manually supply a shell as a
1213 with the script as its argument.
1215 Programs that use the
1220 privileges while being traced.
1222 A traced process runs slowly.
1224 Traced processes which are descended from
1226 may be left running after an interrupt signal
1231 was written by Paul Kranenburg
1232 for SunOS and was inspired by its
1235 The SunOS version of
1237 was ported to Linux and enhanced
1238 by Branko Lankester, who also wrote the Linux kernel support.
1239 Even though Paul released
1242 Branko's work was based on Paul's
1244 1.5 release from 1991.
1245 In 1993, Rick Sladkey merged
1247 2.5 for SunOS and the second release of
1249 for Linux, added many of the features of
1251 from SVR4, and produced an
1253 that worked on both platforms. In 1994 Rick ported
1255 to SVR4 and Solaris and wrote the
1256 automatic configuration support. In 1995 he ported
1259 and tired of writing about himself in the third person.
1261 Beginning with 1996,
1263 was maintained by Wichert Akkerman.
1266 development migrated to CVS; ports to FreeBSD and many architectures on Linux
1267 (including ARM, IA-64, MIPS, PA-RISC, PowerPC, s390, SPARC) were introduced.
1268 In 2002, the burden of
1270 maintainership was transferred to Roland McGrath.
1273 gained support for several new Linux architectures (AMD64, s390x, SuperH),
1274 bi-architecture support for some of them, and received numerous additions and
1275 improvements in syscalls decoders on Linux;
1277 development migrated to
1282 is actively maintained by Dmitry Levin.
1284 gained support for AArch64, ARC, AVR32, Blackfin, Meta, Nios II, OpenSISC 1000,
1285 RISC-V, Tile/TileGx, Xtensa architectures since that time.
1286 In 2012, unmaintained and apparently broken support for non-Linux operating
1287 systems was removed.
1290 gained support for path tracing and file descriptor path decoding.
1291 In 2014, support for stack traces printing was added.
1292 In 2016, syscall fault injection was implemented.
1294 For the additional information, please refer to the
1298 repository commit log.
1302 should be reported to the
1304 mailing list at <strace\-devel@lists.strace.io>.
1306 .BR strace-log-merge (1),
1314 .UR https://strace.io/
1319 The complete list of
1321 contributors can be found in the
projects / strace / blob