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 detached grandchild, not as parent of the
342 tracee. This reduces the visible effect of
344 by keeping the tracee a direct child of the calling process.
347 Trace child processes as they are created by currently traced
348 processes as a result of the
353 system calls. Note that
357 will attach all threads of process
359 if it is multi-threaded, not only thread with
360 .IR thread_id " = " PID .
366 option is in effect, each processes trace is written to
370 is the numeric process id of each process.
371 This is incompatible with
373 since no per-process counts are kept.
375 One might want to consider using
376 .BR strace-log-merge (1)
377 to obtain a combined strace log view.
379 .BI "\-I " interruptible
382 can be interrupted by signals (such as pressing
387 no signals are blocked;
390 fatal signals are blocked while decoding syscall (default);
393 fatal signals are always blocked (default if
394 .BR -o " " \fIFILE\fR " " \fIPROG\fR );
398 .BR SIGTSTP " (" CTRL\-Z )
399 are always blocked (useful to make
400 .BI "strace -o " "FILE PROG"
408 \fB\-e\ trace\fR=\,\fIset\fR
409 Trace only the specified set of system calls. The
411 option is useful for determining which system calls might be useful
412 to trace. For example,
413 .BR trace = open,close,read,write
415 trace those four system calls. Be careful when making inferences
416 about the user/kernel boundary if only a subset of system calls
417 are being monitored. The default is
420 \fB\-e\ trace\fR=/\,\fIregex\fR
421 Trace only those system calls that match the
425 Extended Regular Expression syntax (see
428 .BR "\-e\ trace" = %file
430 .BR "\-e\ trace" = file
431 Trace all system calls which take a file name as an argument. You
432 can think of this as an abbreviation for
433 .BR "\-e\ trace" = open , stat , chmod , unlink ,...
434 which is useful to seeing what files the process is referencing.
435 Furthermore, using the abbreviation will ensure that you don't
436 accidentally forget to include a call like
438 in the list. Betchya woulda forgot that one.
439 The syntax without a preceding percent sign
440 .RB (\[dq] "-e trace" = file \[dq])
443 .BR "\-e\ trace" = %process
445 .BR "\-e\ trace" = process
446 Trace all system calls which involve process management. This
447 is useful for watching the fork, wait, and exec steps of a process.
448 The syntax without a preceding percent sign
449 .RB (\[dq] "-e trace" = process \[dq])
452 .BR "\-e\ trace" = %net
454 .BR "\-e\ trace" = %network
456 .BR "\-e\ trace" = network
457 Trace all the network related system calls.
458 The syntax without a preceding percent sign
459 .RB (\[dq] "-e trace" = network \[dq])
462 .BR "\-e\ trace" = %signal
464 .BR "\-e\ trace" = signal
465 Trace all signal related system calls.
466 The syntax without a preceding percent sign
467 .RB (\[dq] "-e trace" = signal \[dq])
470 .BR "\-e\ trace" = %ipc
472 .BR "\-e\ trace" = ipc
473 Trace all IPC related system calls.
474 The syntax without a preceding percent sign
475 .RB (\[dq] "-e trace" = ipc \[dq])
478 .BR "\-e\ trace" = %desc
480 .BR "\-e\ trace" = desc
481 Trace all file descriptor related system calls.
482 The syntax without a preceding percent sign
483 .RB (\[dq] "-e trace" = desc \[dq])
486 .BR "\-e\ trace" = %memory
488 .BR "\-e\ trace" = memory
489 Trace all memory mapping related system calls.
490 The syntax without a preceding percent sign
491 .RB (\[dq] "-e trace" = memory \[dq])
494 .BR "\-e\ trace" = %stat
495 Trace stat syscall variants.
497 .BR "\-e\ trace" = %lstat
498 Trace lstat syscall variants.
500 .BR "\-e\ trace" = %fstat
501 Trace fstat and fstatat syscall variants.
503 .BR "\-e\ trace" = %%stat
504 Trace syscalls used for requesting file status (stat, lstat, fstat, fstatat,
505 statx, and their variants).
507 .BR "\-e\ trace" = %statfs
508 Trace statfs, statfs64, statvfs, osf_statfs, and osf_statfs64 system calls.
509 The same effect can be achieved with
510 .BR "\-e\ trace" = /^(.*_)?statv?fs
513 .BR "\-e\ trace" = %fstatfs
514 Trace fstatfs, fstatfs64, fstatvfs, osf_fstatfs, and osf_fstatfs64 system calls.
515 The same effect can be achieved with
516 .BR "\-e\ trace" = /fstatv?fs
519 .BR "\-e\ trace" = %%statfs
520 Trace syscalls related to file system statistics (statfs-like, fstatfs-like,
521 and ustat). The same effect can be achieved with
522 .BR "\-e\ trace" = /statv?fs|fsstat|ustat
525 .BR "\-e\ trace" = %pure
526 Trace syscalls that always succeed and have no arguments.
527 Currently, this list includes
528 .BR arc_gettls "(2), " getdtablesize "(2), " getegid "(2), " getegid32 "(2),"
529 .BR geteuid "(2), " geteuid32 "(2), " getgid "(2), " getgid32 "(2),"
530 .BR getpagesize "(2), " getpgrp "(2), " getpid "(2), " getppid "(2),"
531 .BR get_thread_area (2)
532 (on architectures other than x86),
533 .BR gettid "(2), " get_tls "(2), " getuid "(2), " getuid32 "(2),"
534 .BR getxgid "(2), " getxpid "(2), " getxuid "(2), " kern_features "(2), and"
535 .BR metag_get_tls "(2)"
538 \fB\-e\ signal\fR=\,\fIset\fR
539 Trace only the specified subset of signals. The default is
542 .BR signal "=!" SIGIO
547 signals not to be traced.
549 \fB\-e\ status\fR=\,\fIset\fR
550 Print only system calls with the specified return status. The default is
556 waits for system calls to return before deciding whether they should be printed
557 or not, the traditional order of events may not be preserved anymore. If two
558 system calls are executed by concurrent threads,
560 will first print both the entry and exit of the first system call to exit,
561 regardless of their respective entry time. The entry and exit of the second
562 system call to exit will be printed afterwards. Here is an example when
564 is called, but a different thread calls
565 .BR clock_gettime (2)
570 [pid 28779] 1130322148.939977 clock_gettime(CLOCK_REALTIME, {1130322148, 939977000}) = 0
571 [pid 28772] 1130322148.438139 select(4, [3], NULL, NULL, NULL) = 1 (in [3])
574 can include the following elements:
578 Trace system calls that returned without an error code.
581 option has the effect of
582 .BR status = successful .
585 Trace system calls that returned with an error code.
588 option has the effect of
589 .BR status = failed .
592 Trace system calls that did not return. This might happen, for example, due to
593 an execve call in a neighbour thread.
596 Trace system calls that returned but strace failed to fetch the error status.
599 Trace system calls for which strace detached before the return.
603 Trace only system calls accessing
607 options can be used to specify several paths.
610 Print only syscalls that returned without an error code.
613 Print only syscalls that returned with an error code.
617 Align return values in a specific column (default column 40).
619 \fB\-e\ abbrev\fR=\,\fIset\fR
620 Abbreviate the output from printing each member of large structures.
625 option has the effect of
628 \fB\-e\ verbose\fR=\,\fIset\fR
629 Dereference structures for the specified set of system calls. The
633 \fB\-e\ raw\fR=\,\fIset\fR
634 Print raw, undecoded arguments for the specified set of system calls.
635 This option has the effect of causing all arguments to be printed
636 in hexadecimal. This is mostly useful if you don't trust the
637 decoding or you need to know the actual numeric value of an
643 \fB\-e\ read\fR=\,\fIset\fR
644 Perform a full hexadecimal and ASCII dump of all the data read from
645 file descriptors listed in the specified set. For example, to see
646 all input activity on file descriptors
651 \fB\-e\ read\fR=\,\fI3\fR,\fI5\fR.
652 Note that this is independent from the normal tracing of the
654 system call which is controlled by the option
655 .BR -e "\ " trace = read .
657 \fB\-e\ write\fR=\,\fIset\fR
658 Perform a full hexadecimal and ASCII dump of all the data written to
659 file descriptors listed in the specified set. For example, to see
660 all output activity on file descriptors
665 \fB\-e\ write\fR=\,\fI3\fR,\,\fI5\fR.
666 Note that this is independent from the normal tracing of the
668 system call which is controlled by the option
669 .BR -e "\ " trace = write .
671 .BR "\-e\ kvm" = vcpu
672 Print the exit reason of kvm vcpu. Requires Linux kernel version 4.16.0
676 Print the instruction pointer at the time of the system call.
677 .if '@ENABLE_STACKTRACE_FALSE@'#' .TP
678 .if '@ENABLE_STACKTRACE_FALSE@'#' .B \-k
679 .if '@ENABLE_STACKTRACE_FALSE@'#' Print the execution stack trace of the traced
680 .if '@ENABLE_STACKTRACE_FALSE@'#' processes after each system call.
683 Write the trace output to the file
685 rather than to stderr.
690 If the argument begins with '|' or '!', the rest of the
691 argument is treated as a command and all output is piped to it.
692 This is convenient for piping the debugging output to a program
693 without affecting the redirections of executed programs.
694 The latter is not compatible with
699 Open the file provided in the
701 option in append mode.
704 Suppress messages about attaching, detaching etc. This happens
705 automatically when output is redirected to a file and the command
706 is run directly instead of attaching.
709 If given twice, suppress messages about process exit status.
712 Print a relative timestamp upon entry to each system call. This
713 records the time difference between the beginning of successive
717 option uses the monotonic clock time for measuring time difference and not the
718 wall clock time, its measurements can differ from the difference in time
724 Specify the maximum string size to print (the default is 32). Note
725 that filenames are not considered strings and are always printed in
729 Prefix each line of the trace with the wall clock time.
732 If given twice, the time printed will include the microseconds.
735 If given thrice, the time printed will include the microseconds
736 and the leading portion will be printed as the number
737 of seconds since the epoch.
740 Show the time spent in system calls. This records the time
741 difference between the beginning and the end of each system call.
744 Print unabbreviated versions of environment, stat, termios, etc.
745 calls. These structures are very common in calls and so the default
746 behavior displays a reasonable subset of structure members. Use
747 this option to get all of the gory details.
750 Print all non-ASCII strings in hexadecimal string format.
753 Print all strings in hexadecimal string format.
756 Set the format for printing of named constants and flags.
763 Raw number output, without decoding.
766 Output a named constant or a set of flags instead of the raw number if they are
773 Output both the raw value and the decoded string (as a comment).
777 Print paths associated with file descriptor arguments.
780 Print protocol specific information associated with socket file descriptors,
781 and block/character device number associated with device file descriptors.
785 Count time, calls, and errors for each system call and report a summary on
786 program exit, suppressing the regular output.
787 This attempts to show system time (CPU time spent running
788 in the kernel) independent of wall clock time. If
792 only aggregate totals for all traced processes are kept.
797 but also print regular output while processes are running.
800 Set the overhead for tracing system calls to
803 This is useful for overriding the default heuristic for guessing
804 how much time is spent in mere measuring when timing system calls using
807 option. The accuracy of the heuristic can be gauged by timing a given
808 program run without tracing (using
810 and comparing the accumulated
811 system call time to the total produced using
815 Sort the output of the histogram printed by the
817 option by the specified criterion. Legal values are
818 .BR time " (or " time_total " or " total_time ),
819 .BR calls " (or " count ),
820 .BR errors " (or " error ),
821 .BR name " (or " syscall " or " syscall_name ),
823 .BR nothing " (or " none );
828 Summarise the time difference between the beginning and end of
829 each system call. The default is to summarise the system time.
832 \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]
833 Perform syscall tampering for the specified set of syscalls.
842 options has to be specified.
846 are mutually exclusive.
848 If :\fBerror\fR=\,\fIerrno\/\fR option is specified,
849 a fault is injected into a syscall invocation:
850 the syscall number is replaced by -1 which corresponds to an invalid syscall
851 (unless a syscall is specified with :\fBsyscall=\fR option),
852 and the error code is specified using a symbolic
856 or a numeric value within 1..4095 range.
858 If :\fBretval\fR=\,\fIvalue\/\fR option is specified,
859 success injection is performed: the syscall number is replaced by -1,
860 but a bogus success value is returned to the callee.
862 If :\fBsignal\fR=\,\fIsig\/\fR option is specified with either a symbolic value
865 or a numeric value within 1..\fBSIGRTMAX\fR range,
866 that signal is delivered on entering every syscall specified by the
869 If :\fBdelay_enter\fR=\,\fIusecs\/\fR or :\fBdelay_exit\fR=\,\fIusecs\/\fR
870 options are specified, delay injection is performed: the tracee is delayed
873 microseconds on entering or exiting the syscall.
875 If :\fBsignal\fR=\,\fIsig\/\fR option is specified without
876 :\fBerror\fR=\,\fIerrno\/\fR, :\fBretval\fR=\,\fIvalue\/\fR or
877 :\fBdelay_{enter,exit}\fR=\,\fIusecs\/\fR options,
880 is delivered without a syscall fault or delay injection.
881 Conversely, :\fBerror\fR=\,\fIerrno\/\fR or
882 :\fBretval\fR=\,\fIvalue\/\fR option without
883 :\fBdelay_enter\fR=\,\fIusecs\/\fR,
884 :\fBdelay_exit\fR=\,\fIusecs\/\fR or
885 :\fBsignal\fR=\,\fIsig\/\fR options injects a fault without delivering a signal
886 or injecting a delay, etc.
888 If both :\fBerror\fR=\,\fIerrno\/\fR or :\fBretval\fR=\,\fIvalue\/\fR
889 and :\fBsignal\fR=\,\fIsig\/\fR options are specified, then both
890 a fault or success is injected and a signal is delivered.
892 if :\fBsyscall\fR=\fIsyscall\fR option is specified, the corresponding syscall
893 with no side effects is injected instead of -1.
894 Currently, only "pure" (see
895 .BR "-e trace" = "%pure"
896 description) syscalls can be specified there.
898 Unless a :\fBwhen\fR=\,\fIexpr\fR subexpression is specified,
899 an injection is being made into every invocation of each syscall from the
902 The format of the subexpression is one of the following:
906 For every syscall from the
908 perform an injection for the syscall invocation number
913 For every syscall from the
915 perform injections for the syscall invocation number
917 and all subsequent invocations.
919 \fIfirst\/\fB+\fIstep\fR
920 For every syscall from the
922 perform injections for syscall invocations number
925 .IR first + step + step ,
929 For example, to fail each third and subsequent chdir syscalls with
932 \fB\-e\ inject\fR=\,\fIchdir\/\fR:\fBerror\fR=\,\fIENOENT\/\fR:\fBwhen\fR=\,\fI3\/\fB+\fR.
934 The valid range for numbers
940 An injection expression can contain only one
944 specification, and only one
946 specification. If an injection expression contains multiple
948 specifications, the last one takes precedence.
950 Accounting of syscalls that are subject to injection
951 is done per syscall and per tracee.
953 Specification of syscall injection can be combined
954 with other syscall filtering options, for example,
955 \fB\-P \fI/dev/urandom \fB\-e inject\fR=\,\fIfile\/\fR:\fBerror\fR=\,\fIENOENT\fR.
957 \fB\-e\ fault\fR=\,\fIset\/\fR[:\fBerror\fR=\,\fIerrno\/\fR][:\fBwhen\fR=\,\fIexpr\/\fR]
958 Perform syscall fault injection for the specified set of syscalls.
960 This is equivalent to more generic
961 \fB\-e\ inject\fR= expression with default value of
968 Show some debugging output of
970 itself on the standard error.
973 Enable (experimental) usage of seccomp-bpf to have ptrace(2)-stops only when
974 system calls that are being traced occur in the traced processes. Implies the
977 An attempt to rely on seccomp-bpf to filter system calls may fail for various
978 reasons, e.g. there are too many system calls to filter, the seccomp API is not
981 itself is being traced.
983 is also ineffective on processes attached using
985 In cases when seccomp-bpf filter setup failed,
987 proceeds as usual and stops traced processes on every system call.
990 This option is deprecated. It is retained for backward compatibility only
991 and may be removed in future releases.
992 Usage of multiple instances of
994 option is still equivalent to a single
996 and it is ignored at all if used along with one or more instances of
1003 Print the help summary.
1008 Print the version number of
1015 exits with the same exit status.
1018 is terminated by a signal,
1020 terminates itself with the same signal, so that
1022 can be used as a wrapper process transparent to the invoking parent process.
1023 Note that parent-child relationship (signal stop notifications,
1025 value, etc) between traced process and its parent are not preserved
1036 is zero unless no processes has been attached or there was an unexpected error
1037 in doing the tracing.
1038 .SH "SETUID INSTALLATION"
1041 is installed setuid to root then the invoking user will be able to
1042 attach to and trace processes owned by any user.
1043 In addition setuid and setgid programs will be executed and traced
1044 with the correct effective privileges.
1045 Since only users trusted with full root privileges should be allowed
1047 it only makes sense to install
1049 as setuid to root when the users who can execute it are restricted
1050 to those users who have this trust.
1051 For example, it makes sense to install a special version of
1053 with mode 'rwsr-xr--', user
1057 where members of the
1059 group are trusted users.
1060 If you do use this feature, please remember to install
1061 a regular non-setuid version of
1063 for ordinary users to use.
1064 .SH "MULTIPLE PERSONALITY SUPPORT"
1065 On some architectures,
1067 supports decoding of syscalls for processes that use different ABI rather than
1071 Specifically, in addition to decoding native ABI,
1073 can decode the following ABIs on the following architectures:
1078 Architecture ABIs supported
1079 x86_64 i386, x32 [1]; i386 [2]
1080 AArch64 ARM 32-bit EABI
1081 PowerPC 64-bit [3] PowerPC 32-bit
1083 SPARC 64-bit SPARC 32-bit
1084 TILE 64-bit TILE 32-bit
1091 is built as an x86_64 application
1096 is built as an x32 application
1102 This support is optional and relies on ability to generate and parse structure
1103 definitions during the build time.
1104 Please refer to the output of the
1106 command in order to figure out what support is available in your
1108 build ("non-native" refers to an ABI that differs from the ABI
1114 can trace and properly decode non-native 32-bit binaries.
1118 can trace, but cannot properly decode non-native 32-bit binaries.
1122 can trace and properly decode non-native 32-on-64-bit binaries.
1126 can trace, but cannot properly decode non-native 32-on-64-bit binaries.
1128 If the output contains neither
1132 then decoding of non-native 32-bit binaries is not implemented at all
1135 Likewise, if the output contains neither
1139 then decoding of non-native 32-on-64-bit binaries is not implemented at all
1142 It is a pity that so much tracing clutter is produced by systems
1143 employing shared libraries.
1145 It is instructive to think about system call inputs and outputs
1146 as data-flow across the user/kernel boundary. Because user-space
1147 and kernel-space are separate and address-protected, it is
1148 sometimes possible to make deductive inferences about process
1149 behavior using inputs and outputs as propositions.
1151 In some cases, a system call will differ from the documented behavior
1152 or have a different name. For example, the
1154 system call does not have
1158 library function uses
1160 system call on modern (2.6.38+) kernels. These
1161 discrepancies are normal but idiosyncratic characteristics of the
1162 system call interface and are accounted for by C library wrapper
1165 Some system calls have different names in different architectures and
1166 personalities. In these cases, system call filtering and printing
1167 uses the names that match corresponding
1169 kernel macros of the tracee's architecture and personality.
1170 There are two exceptions from this general rule:
1171 .BR arm_fadvise64_64 (2)
1173 .BR xtensa_fadvise64_64 (2)
1174 Xtensa syscall are filtered and printed as
1175 .BR fadvise64_64 (2).
1177 On x32, syscalls that are intended to be used by 64-bit processes and not x32
1180 that has syscall number 19 on x86_64, with its x32 counterpart has syscall
1181 number 515), but called with
1182 .B __X32_SYSCALL_BIT
1183 flag being set, are designated with
1187 On some platforms a process that is attached to with the
1189 option may observe a spurious
1191 return from the current system call that is not restartable.
1192 (Ideally, all system calls should be restarted on
1194 attach, making the attach invisible
1195 to the traced process, but a few system calls aren't.
1196 Arguably, every instance of such behavior is a kernel bug.)
1197 This may have an unpredictable effect on the process
1198 if the process takes no action to restart the system call.
1202 executes the specified
1204 directly and does not employ a shell for that, scripts without shebang
1205 that usually run just fine when invoked by shell fail to execute with
1208 It is advisable to manually supply a shell as a
1210 with the script as its argument.
1212 Programs that use the
1217 privileges while being traced.
1219 A traced process runs slowly.
1221 Traced processes which are descended from
1223 may be left running after an interrupt signal
1228 was written by Paul Kranenburg
1229 for SunOS and was inspired by its
1232 The SunOS version of
1234 was ported to Linux and enhanced
1235 by Branko Lankester, who also wrote the Linux kernel support.
1236 Even though Paul released
1239 Branko's work was based on Paul's
1241 1.5 release from 1991.
1242 In 1993, Rick Sladkey merged
1244 2.5 for SunOS and the second release of
1246 for Linux, added many of the features of
1248 from SVR4, and produced an
1250 that worked on both platforms. In 1994 Rick ported
1252 to SVR4 and Solaris and wrote the
1253 automatic configuration support. In 1995 he ported
1256 and tired of writing about himself in the third person.
1258 Beginning with 1996,
1260 was maintained by Wichert Akkerman.
1263 development migrated to CVS; ports to FreeBSD and many architectures on Linux
1264 (including ARM, IA-64, MIPS, PA-RISC, PowerPC, s390, SPARC) were introduced.
1265 In 2002, the burden of
1267 maintainership was transferred to Roland McGrath.
1270 gained support for several new Linux architectures (AMD64, s390x, SuperH),
1271 bi-architecture support for some of them, and received numerous additions and
1272 improvements in syscalls decoders on Linux;
1274 development migrated to
1279 is actively maintained by Dmitry Levin.
1281 gained support for AArch64, ARC, AVR32, Blackfin, Meta, Nios II, OpenSISC 1000,
1282 RISC-V, Tile/TileGx, Xtensa architectures since that time.
1283 In 2012, unmaintained and apparently broken support for non-Linux operating
1284 systems was removed.
1287 gained support for path tracing and file descriptor path decoding.
1288 In 2014, support for stack traces printing was added.
1289 In 2016, syscall fault injection was implemented.
1291 For the additional information, please refer to the
1295 repository commit log.
1299 should be reported to the
1301 mailing list at <strace\-devel@lists.strace.io>.
1303 .BR strace-log-merge (1),
1311 .UR https://strace.io/
1316 The complete list of
1318 contributors can be found in the
projects / strace / blob