strace.1 (56340B)
- .\" Copyright (c) 1991, 1992 Paul Kranenburg <pk@cs.few.eur.nl>
- .\" Copyright (c) 1993 Branko Lankester <branko@hacktic.nl>
- .\" Copyright (c) 1993, 1994, 1995, 1996 Rick Sladkey <jrs@world.std.com>
- .\" Copyright (c) 1996-2021 The strace developers.
- .\" All rights reserved.
- .\"
- .\" SPDX-License-Identifier: LGPL-2.1-or-later
- .de CW
- .sp
- .in +4n
- .nf
- .ft CW
- ..
- .de CE
- .ft R
- .fi
- .in
- .sp
- ..
- .\" Like .OP, but with ellipsis at the end in order to signify that option
- .\" can be provided multiple times. Based on .OP definition in groff's
- .\" an-ext.tmac.
- .de OM
- . ie \\n(.$-1 \
- . RI "[\fB\\$1\fP" "\ \\$2" "]...\&"
- . el \
- . RB "[" "\\$1" "]...\&"
- ..
- .\" Required option.
- .de OR
- . ie \\n(.$-1 \
- . RI "\fB\\$1\fP" "\ \\$2"
- . el \
- . BR "\\$1"
- ..
- .TH STRACE 1 "2024-06-30" "strace 6.12"
- .SH NAME
- strace \- trace system calls and signals
- .SH SYNOPSIS
- .SY strace
- .\" -kk option is available:
- .if ''#' .if '@USE_LIBDW_FALSE@'#' .OP \-ACdffhikkqqrtttTvVwxxyyYzZ
- .\" only -k option is available:
- .if ''#' .if '@USE_LIBUNWIND_FALSE@'#' .OP \-ACdffhikqqrtttTvVwxxyyYzZ
- .\" no -k option is available:
- .if '#'#' .OP \-ACdffhiqqrtttTvVwxxyyYzZ
- .OP \-a column
- .OP \-b execve
- .OM \-e expr
- .OP \-I n
- .OP \-o file
- .OP \-O overhead
- .OM \-p pid
- .OM \-P path
- .OP \-s strsize
- .OP \-S sortby
- .OP \-U columns
- .OP \-X format
- .OP \-\-seccomp\-bpf
- .if ''#' .OP \-\-stack\-trace\-frame\-limit\fR=\fIlimit\fR
- .OP \-\-syscall\-limit=\fIlimit\fR
- .if ''#' .OP \-\-secontext\fR[=\fIformat\fR]
- .OP \-\-tips\fR[=\fIformat\fR]
- .BR "" {
- .OR \-p pid
- .BR "" |
- .OP \-DDD
- .OM \-E var\fR[=\fIval\fR]
- .OP \-u username
- .IR command " [" args ]
- .BR "" }
- .YS
- .SY strace
- .B \-c
- .OP \-dfwzZ
- .OP \-b execve
- .OM \-e expr
- .OP \-I n
- .OP \-O overhead
- .OM \-p pid
- .OM \-P path
- .OP \-S sortby
- .OP \-U columns
- .OP \-\-seccomp\-bpf
- .OP \-\-syscall\-limit=\fIlimit\fR
- .OP \-\-tips\fR[=\fIformat\fR]
- .BR "" {
- .OR \-p pid
- .BR "" |
- .OP \-DDD
- .OM \-E var\fR[=\fIval\fR]
- .OP -u username
- .IR command " [" args ]
- .BR "" }
- .YS
- .SY strace
- .B \-\-tips\fR[=\fIformat\fR]
- .YS
- .SH DESCRIPTION
- .IX "strace command" "" "\fLstrace\fR command"
- .LP
- In the simplest case
- .B strace
- runs the specified
- .I command
- until it exits.
- It intercepts and records the system calls which are called
- by a process and the signals which are received by a process.
- The name of each system call, its arguments and its return value
- are printed on standard error or to the file specified with the
- .B \-o
- option.
- .LP
- .B strace
- is a useful diagnostic, instructional, and debugging tool.
- System administrators, diagnosticians and trouble-shooters will find
- it invaluable for solving problems with
- programs for which the source is not readily available since
- they do not need to be recompiled in order to trace them.
- Students, hackers and the overly-curious will find that
- a great deal can be learned about a system and its system calls by
- tracing even ordinary programs. And programmers will find that
- since system calls and signals are events that happen at the user/kernel
- interface, a close examination of this boundary is very
- useful for bug isolation, sanity checking and
- attempting to capture race conditions.
- .LP
- Each line in the trace contains the system call name, followed
- by its arguments in parentheses and its return value.
- An example from stracing the command "cat /dev/null" is:
- .CW
- open("/dev/null", O_RDONLY) = 3
- .CE
- Errors (typically a return value of \-1) have the errno symbol
- and error string appended.
- .CW
- open("/foo/bar", O_RDONLY) = \-1 ENOENT (No such file or directory)
- .CE
- Signals are printed as signal symbol and decoded siginfo structure.
- An excerpt from stracing and interrupting the command "sleep 666" is:
- .CW
- sigsuspend([] <unfinished ...>
- --- SIGINT {si_signo=SIGINT, si_code=SI_USER, si_pid=...} ---
- +++ killed by SIGINT +++
- .CE
- If a system call is being executed and meanwhile another one is being called
- from a different thread/process then
- .B strace
- will try to preserve the order of those events and mark the ongoing call as
- being
- .IR unfinished .
- When the call returns it will be marked as
- .IR resumed .
- .CW
- [pid 28772] select(4, [3], NULL, NULL, NULL <unfinished ...>
- [pid 28779] clock_gettime(CLOCK_REALTIME, {tv_sec=1130322148, tv_nsec=3977000}) = 0
- [pid 28772] <... select resumed> ) = 1 (in [3])
- .CE
- Interruption of a (restartable) system call by a signal delivery is processed
- differently as kernel terminates the system call and also arranges its
- immediate reexecution after the signal handler completes.
- .CW
- read(0, 0x7ffff72cf5cf, 1) = ? ERESTARTSYS (To be restarted)
- --- SIGALRM {si_signo=SIGALRM, si_code=SI_KERNEL} ---
- rt_sigreturn({mask=[]}) = 0
- read(0, "", 1) = 0
- .CE
- Arguments are printed in symbolic form with passion.
- This example shows the shell performing ">>xyzzy" output redirection:
- .CW
- open("xyzzy", O_WRONLY|O_APPEND|O_CREAT, 0666) = 3
- .CE
- Here, the second and the third argument of
- .BR open (2)
- are decoded by breaking down the
- flag argument into its three bitwise-OR constituents and printing the
- mode value in octal by tradition. Where the traditional or native
- usage differs from ANSI or POSIX, the latter forms are preferred.
- In some cases,
- .B strace
- output is proven to be more readable than the source.
- .LP
- Structure pointers are dereferenced and the members are displayed
- as appropriate. In most cases, arguments are formatted in the most C-like
- fashion possible.
- For example, the essence of the command "ls \-l /dev/null" is captured as:
- .CW
- lstat("/dev/null", {st_mode=S_IFCHR|0666, st_rdev=makedev(0x1, 0x3), ...}) = 0
- .CE
- Notice how the 'struct stat' argument is dereferenced and how each member is
- displayed symbolically. In particular, observe how the
- .B st_mode
- member is carefully decoded into a bitwise-OR of symbolic and numeric values.
- Also notice in this example that the first argument to
- .BR lstat (2)
- is an input to the system call and the second argument is an output.
- Since output arguments are not modified if the system call fails, arguments may
- not always be dereferenced. For example, retrying the "ls \-l" example
- with a non-existent file produces the following line:
- .CW
- lstat("/foo/bar", 0xb004) = \-1 ENOENT (No such file or directory)
- .CE
- In this case the porch light is on but nobody is home.
- .LP
- Syscalls unknown to
- .B strace
- are printed raw, with the unknown system call number printed in hexadecimal form
- and prefixed with "syscall_":
- .CW
- syscall_0xbad(0x1, 0x2, 0x3, 0x4, 0x5, 0x6) = -1 ENOSYS (Function not implemented)
- .CE
- .LP
- Character pointers are dereferenced and printed as C strings.
- Non-printing characters in strings are normally represented by
- ordinary C escape codes.
- Only the first
- .I strsize
- (32 by default) bytes of strings are printed;
- longer strings have an ellipsis appended following the closing quote.
- Here is a line from "ls \-l" where the
- .BR getpwuid (3)
- library routine is reading the password file:
- .CW
- read(3, "root::0:0:System Administrator:/"..., 1024) = 422
- .CE
- While structures are annotated using curly braces, pointers to basic types
- and arrays are printed using square brackets with commas separating
- the elements. Here is an example from the command
- .BR id (1)
- on a system with supplementary group ids:
- .CW
- getgroups(32, [100, 0]) = 2
- .CE
- On the other hand, bit-sets are also shown using square brackets,
- but set elements are separated only by a space.
- Here is the shell, preparing to execute an external command:
- .CW
- sigprocmask(SIG_BLOCK, [CHLD TTOU], []) = 0
- .CE
- Here, the second argument is a bit-set of two signals,
- .BR SIGCHLD " and " SIGTTOU .
- In some cases, the bit-set is so full that printing out the unset
- elements is more valuable. In that case, the bit-set is prefixed by
- a tilde like this:
- .CW
- sigprocmask(SIG_UNBLOCK, ~[], NULL) = 0
- .CE
- Here, the second argument represents the full set of all signals.
- .SH OPTIONS
- .SS General
- .TP 12
- .BI "\-e " expr
- A qualifying expression which modifies which events to trace
- or how to trace them. The format of the expression is:
- .RS 15
- .IP
- [\,\fIqualifier\/\fB=\fR][\fB!\fR]\,\fIvalue\/\fR[\fB,\fR\,\fIvalue\/\fR]...
- .RE
- .IP
- where
- .I qualifier
- is one of
- .BR trace " (or " t ),
- .BR trace\-fds " (or " trace\-fd " or " fd " or " fds ),
- .BR abbrev " (or " a ),
- .BR verbose " (or " v ),
- .BR raw " (or " x ),
- .BR signal " (or " signals " or " s ),
- .BR read " (or " reads " or " r ),
- .BR write " (or " writes " or " w ),
- .BR fault ,
- .BR inject ,
- .BR status ,
- .BR quiet " (or " silent " or " silence " or " q ),
- .if ''#' .BR secontext ,
- .BR decode\-fds " (or " decode\-fd ),
- .BR decode\-pids " (or " decode\-pid ),
- or
- .BR kvm ,
- and
- .I value
- is a qualifier-dependent symbol or number. The default
- qualifier is
- .BR trace .
- Using an exclamation mark negates the set of values. For example,
- .BR \-e "\ " open
- means literally
- .BR \-e "\ " trace = open
- which in turn means trace only the
- .B open
- system call. By contrast,
- .BR \-e "\ " trace "=!" open
- means to trace every system call except
- .BR open .
- In addition, the special values
- .B all
- and
- .B none
- have the obvious meanings.
- .IP
- Note that some shells use the exclamation point for history
- expansion even inside quoted arguments. If so, you must escape
- the exclamation point with a backslash.
- .SS Startup
- .TP 12
- \fB\-E\ \fIvar\fR=\,\fIval\fR
- .TQ
- .BR "\-\-env" = \fIvar\fR = \fIval\fR
- Run command with
- .IR var = val
- in its list of environment variables.
- .TP
- .BI "\-E " var
- .TQ
- .BR "\-\-env" = \fIvar\fR
- Remove
- .IR var
- from the inherited list of environment variables before passing it on to
- the command.
- .TP
- .BI "\-p " pid
- .TQ
- .BR "\-\-attach" = \fIpid\fR
- Attach to the process with the process
- .SM ID
- .I pid
- and begin tracing.
- The trace may be terminated
- at any time by a keyboard interrupt signal
- .RB ( CTRL\-C ).
- .B strace
- will respond by detaching itself from the traced process(es)
- leaving it (them) to continue running.
- Multiple
- .B \-p
- options can be used to attach to many processes in addition to
- .I command
- (which is optional if at least one
- .B \-p
- option is given).
- Multiple process IDs, separated by either
- comma (\(lq,\(rq), space (\(lq \(rq), tab, or newline character,
- can be provided as an argument to a single
- .B \-p
- option, so, for example,
- .B \-p
- "$(pidof PROG)" and
- .B \-p
- "$(pgrep PROG)" syntaxes are supported.
- .TP
- .BI "\-u " username
- .TQ
- .BR "\-\-user" = \fIusername\fR
- Run command with the user \s-1ID\s0, group \s-2ID\s0, and
- supplementary groups of
- .IR username .
- This option is only useful when running as root and enables the
- correct execution of setuid and/or setgid binaries.
- Unless this option is used setuid and setgid programs are executed
- without effective privileges.
- .TQ
- .BI "\-u " UID:GID
- .TQ
- .BR "\-\-user" = \fIUID:GID\fR
- Alternative syntax where the program is started with exactly the given user
- and group IDs, and an empty list of supplementary groups. In this case,
- user and group name lookups are not performed.
- .TP
- .BR "\-\-argv0" = \fIname\fR
- Set argv[0] of the command being executed to
- .IR name .
- Useful for tracing multi-call executables which interpret argv[0],
- such as busybox or kmod.
- .SS Tracing
- .TP 12
- .BI "\-b " syscall
- .TQ
- .BR "\-\-detach\-on" = \fIsyscall\fR
- If specified syscall is reached, detach from traced process.
- Currently, only
- .BR execve (2)
- syscall is supported. This option is useful if you want to trace
- multi-threaded process and therefore require
- .BR \-f ,
- but don't want to trace its (potentially very complex) children.
- .TP
- .B \-D
- .TQ
- .B \-\-daemonize
- .TQ
- .BR \-\-daemonize = grandchild
- Run tracer process as a grandchild, not as the parent of the
- tracee. This reduces the visible effect of
- .B strace
- by keeping the tracee a direct child of the calling process.
- .TP
- .B \-DD
- .TQ
- .BR \-\-daemonize = pgroup
- .TQ
- .BR \-\-daemonize = pgrp
- Run tracer process as tracee's grandchild in a separate process group.
- In addition to reduction of the visible effect of
- .BR strace ,
- it also avoids killing of
- .B strace
- with
- .BR kill (2)
- issued to the whole process group.
- .TP
- .B \-DDD
- .TQ
- .BR \-\-daemonize = session
- Run tracer process as tracee's grandchild in a separate session
- ("true daemonisation").
- In addition to reduction of the visible effect of
- .BR strace ,
- it also avoids killing of
- .B strace
- upon session termination.
- .TP
- .B \-f
- .TQ
- .BR \-\-follow\-forks
- Trace child processes as they are created by currently traced
- processes as a result of the
- .BR fork (2),
- .BR vfork (2)
- and
- .BR clone (2)
- system calls. Note that
- .B \-p
- .I PID
- .B \-f
- will attach all threads of process
- .I PID
- if it is multi-threaded, not only thread with
- .IR thread_id " = " PID .
- .TP
- .B \-\-output\-separately
- If the
- .BR \-\-output = \fIfilename\fR
- option is in effect, each processes trace is written to
- .IR filename . pid
- where
- .I pid
- is the numeric process id of each process.
- .TP
- .B \-ff
- .TQ
- .B \-\-follow\-forks \-\-output\-separately
- Combine the effects of
- .B \-\-follow\-forks
- and
- .B \-\-output\-separately
- options.
- This is incompatible with
- .BR \-c ,
- since no per-process counts are kept.
- .IP
- One might want to consider using
- .BR strace-log-merge (1)
- to obtain a combined strace log view.
- .TP
- .BI "\-I " interruptible
- .TQ
- .BR "\-\-interruptible" = \fIinterruptible\fR
- When
- .B strace
- can be interrupted by signals (such as pressing
- .BR CTRL\-C ).
- .RS
- .TP 15
- .BR 1 ", " anywhere
- no signals are blocked;
- .TQ
- .BR 2 ", " waiting
- fatal signals are blocked while decoding syscall (default);
- .TQ
- .BR 3 ", " never
- fatal signals are always blocked (default if
- .BR -o " " \fIFILE\fR " " \fIPROG\fR );
- .TQ
- .BR 4 ", " never_tstp
- fatal signals and
- .BR SIGTSTP " (" CTRL\-Z )
- are always blocked (useful to make
- .BI "strace -o " "FILE PROG"
- not stop on
- .BR CTRL\-Z ,
- default if
- .BR \-D ).
- .RE
- .TP
- .BR "\-\-syscall\-limit" = \fIlimit\fR
- Detach all tracees when
- .I limit
- number of syscalls have been captured. Syscalls filtered out via
- .BR \-\-trace ,
- .B \-\-trace\-path
- or
- .B \-\-status
- options are not considered when keeping track of the number of syscalls that are captured.
- .TP
- .B \-\-kill\-on\-exit
- Apply
- .B PTRACE_O_EXITKILL
- ptrace option to all tracee processes (which sends a SIGKILL signal to
- the tracee if the tracer exits) and do not detach them on cleanup so
- they will not be left running after the tracer exit.
- .B \-\-kill\-on\-exit
- is not compatible with
- .BR \-p / \-\-attach
- options.
- .SS Filtering
- .TP 12
- \fB\-e\ trace\fR=\,\fIsyscall_set\fR
- .TQ
- \fB\-e\ t\fR=\,\fIsyscall_set\fR
- .TQ
- \fB\-\-trace\fR=\,\fIsyscall_set\fR
- Trace only the specified set of system calls.
- .I syscall_set
- is defined as
- [\fB!\fR]\,\fIvalue\fR[\fB,\fR\,\fIvalue\/\fR],
- and
- .I value
- can be one of the following:
- .RS
- .TP 13
- .I syscall
- Trace specific syscall, specified by its name (see
- .BR syscalls (2)
- for a reference, but also see
- .BR NOTES ).
- .TP
- .BI ? value
- Question mark before the syscall qualification allows suppression of error
- in case no syscalls matched the qualification provided.
- .TP
- .IB value @64
- Limit the syscall specification described by
- .I value
- to 64-bit personality.
- .TP
- .IB value @32
- Limit the syscall specification described by
- .I value
- to 32-bit personality.
- .TP
- .IB value @x32
- Limit the syscall specification described by
- .I value
- to x32 personality.
- .TP
- .B all
- Trace all system calls.
- .TP
- .BI / regex
- Trace only those system calls that match the
- .IR regex .
- You can use
- .B POSIX
- Extended Regular Expression syntax (see
- .BR regex (7)).
- .TP
- .B %file
- .TQ
- .BR file
- Trace all system calls which take a file name as an argument. You
- can think of this as an abbreviation for
- .BR "\-e\ trace" = open , stat , chmod , unlink ,...
- which is useful to seeing what files the process is referencing.
- Furthermore, using the abbreviation will ensure that you don't
- accidentally forget to include a call like
- .BR lstat (2)
- in the list. Betchya woulda forgot that one.
- The syntax without a preceding percent sign
- .RB (\[dq] "-e trace" = file \[dq])
- is deprecated.
- .TP
- .B %process
- .TQ
- .B process
- Trace system calls associated with process lifecycle
- (creation, exec, termination).
- The syntax without a preceding percent sign
- .RB (\[dq] "-e trace" = process \[dq])
- is deprecated.
- .TP
- .B %net
- .TQ
- .B %network
- .TQ
- .B network
- Trace all the network related system calls.
- The syntax without a preceding percent sign
- .RB (\[dq] "-e trace" = network \[dq])
- is deprecated.
- .TP
- .BR %signal
- .TQ
- .BR signal
- Trace all signal related system calls.
- The syntax without a preceding percent sign
- .RB (\[dq] "-e trace" = signal \[dq])
- is deprecated.
- .TP
- .BR %ipc
- .TQ
- .BR ipc
- Trace all IPC related system calls.
- The syntax without a preceding percent sign
- .RB (\[dq] "-e trace" = ipc \[dq])
- is deprecated.
- .TP
- .BR %desc
- .TQ
- .BR desc
- Trace all file descriptor related system calls.
- The syntax without a preceding percent sign
- .RB (\[dq] "-e trace" = desc \[dq])
- is deprecated.
- .TP
- .BR %memory
- .TQ
- .BR memory
- Trace all memory mapping related system calls.
- The syntax without a preceding percent sign
- .RB (\[dq] "-e trace" = memory \[dq])
- is deprecated.
- .TP
- .BR %creds
- Trace system calls that read or modify user and group identifiers or capability sets.
- .TP
- .BR %stat
- Trace stat syscall variants.
- .TP
- .BR %lstat
- Trace lstat syscall variants.
- .TP
- .BR %fstat
- Trace fstat, fstatat, and statx syscall variants.
- .TP
- .BR %%stat
- Trace syscalls used for requesting file status (stat, lstat, fstat, fstatat,
- statx, and their variants).
- .TP
- .BR %statfs
- Trace statfs, statfs64, statvfs, osf_statfs, and osf_statfs64 system calls.
- The same effect can be achieved with
- .BR "\-e\ trace" = /^(.*_)?statv?fs
- regular expression.
- .TP
- .BR %fstatfs
- Trace fstatfs, fstatfs64, fstatvfs, osf_fstatfs, and osf_fstatfs64 system calls.
- The same effect can be achieved with
- .BR "\-e\ trace" = /fstatv?fs
- regular expression.
- .TP
- .BR %%statfs
- Trace syscalls related to file system statistics (statfs-like, fstatfs-like,
- and ustat). The same effect can be achieved with
- .BR "\-e\ trace" = /statv?fs|fsstat|ustat
- regular expression.
- .TP
- .BR %clock
- Trace system calls that read or modify system clocks.
- .TP
- .BR %pure
- Trace syscalls that always succeed and have no arguments.
- Currently, this list includes
- .BR arc_gettls "(2), " getdtablesize "(2), " getegid "(2), " getegid32 "(2),"
- .BR geteuid "(2), " geteuid32 "(2), " getgid "(2), " getgid32 "(2),"
- .BR getpagesize "(2), " getpgrp "(2), " getpid "(2), " getppid "(2),"
- .BR get_thread_area (2)
- (on architectures other than x86),
- .BR gettid "(2), " get_tls "(2), " getuid "(2), " getuid32 "(2),"
- .BR getxgid "(2), " getxpid "(2), " getxuid "(2), " kern_features "(2), and"
- .BR metag_get_tls "(2)"
- syscalls.
- .RE
- .IP
- The
- .B \-c
- option is useful for determining which system calls might be useful
- to trace. For example,
- .BR trace = open,close,read,write
- means to only
- trace those four system calls. Be careful when making inferences
- about the user/kernel boundary if only a subset of system calls
- are being monitored. The default is
- .BR trace = all .
- .TP
- \fB\-e\ trace\-fd\fR=\,\fIset\fR
- .TQ
- \fB\-e\ trace\-fds\fR=\,\fIset\fR
- .TQ
- \fB\-e\ fd\fR=\,\fIset\fR
- .TQ
- \fB\-e\ fds\fR=\,\fIset\fR
- .TQ
- \fB\-\-trace\-fds\fR=\,\fIset\fR
- Trace only the syscalls that operate
- on the specified subset of (non-negative) file descriptors.
- Note that usage of this option also filters out all the syscalls
- that do not operate on file descriptors at all.
- Applies in (inclusive) disjunction with the \fB\-\-trace\-path\fR option.
- .TP
- \fB\-e\ signal\fR=\,\fIset\fR
- .TQ
- \fB\-e\ signals\fR=\,\fIset\fR
- .TQ
- \fB\-e\ s\fR=\,\fIset\fR
- .TQ
- \fB\-\-signal\fR=\,\fIset\fR
- Trace only the specified subset of signals. The default is
- .BR signal = all .
- For example,
- .BR signal "=!" SIGIO
- (or
- .BR signal "=!" io )
- causes
- .B SIGIO
- signals not to be traced.
- .TP
- \fB\-e\ status\fR=\,\fIset\fR
- .TQ
- \fB\-\-status\fR=\,\fIset\fR
- Print only system calls with the specified return status. The default is
- .BR status = all .
- When using the
- .B status
- qualifier, because
- .B strace
- waits for system calls to return before deciding whether they should be printed
- or not, the traditional order of events may not be preserved anymore. If two
- system calls are executed by concurrent threads,
- .B strace
- will first print both the entry and exit of the first system call to exit,
- regardless of their respective entry time. The entry and exit of the second
- system call to exit will be printed afterwards. Here is an example when
- .BR select (2)
- is called, but a different thread calls
- .BR clock_gettime (2)
- before
- .BR select (2)
- finishes:
- .CW
- [pid 28779] 1130322148.939977 clock_gettime(CLOCK_REALTIME, {1130322148, 939977000}) = 0
- [pid 28772] 1130322148.438139 select(4, [3], NULL, NULL, NULL) = 1 (in [3])
- .CE
- .I set
- can include the following elements:
- .RS
- .TP 13
- .B successful
- Trace system calls that returned without an error code.
- The
- .B -z
- option has the effect of
- .BR status = successful .
- .TQ
- .B failed
- Trace system calls that returned with an error code.
- The
- .B -Z
- option has the effect of
- .BR status = failed .
- .TQ
- .B unfinished
- Trace system calls that did not return. This might happen, for example, due to
- an execve call in a neighbour thread.
- .TQ
- .B unavailable
- Trace system calls that returned but strace failed to fetch the error status.
- .TQ
- .B detached
- Trace system calls for which strace detached before the return.
- .RE
- .TP
- .BI "\-P " path
- .TQ
- .BR "\-\-trace\-path" = \fIpath\fR
- Trace only system calls accessing
- .IR path .
- Multiple
- .B \-P
- options can be used to specify several paths.
- Applies in (inclusive) disjunction with the \fB\-\-trace\-fds\fR option.
- .TP
- .B \-z
- .TQ
- .B \-\-successful\-only
- Print only syscalls that returned without an error code.
- .TP
- .B \-Z
- .TQ
- .B \-\-failed\-only
- Print only syscalls that returned with an error code.
- .SS Output format
- .TP 12
- .BI "\-a " column
- .TQ
- .BR "\-\-columns" = \fIcolumn\fR
- Align return values in a specific column (default column 40).
- .TP
- \fB\-e\ abbrev\fR=\,\fIsyscall_set\fR
- .TQ
- \fB\-e\ a\fR=\,\fIsyscall_set\fR
- .TQ
- \fB\-\-abbrev\fR=\,\fIsyscall_set\fR
- Abbreviate the output from printing each member of large structures.
- The syntax of the
- .I syscall_set
- specification is the same as in the
- .B "-e trace"
- option.
- The default is
- .BR abbrev = all .
- The
- .B \-v
- option has the effect of
- .BR abbrev = none .
- .TP
- \fB\-e\ verbose\fR=\,\fIsyscall_set\fR
- .TQ
- \fB\-e\ v\fR=\,\fIsyscall_set\fR
- .TQ
- \fB\-\-verbose\fR=\,\fIsyscall_set\fR
- Dereference structures for the specified set of system calls.
- The syntax of the
- .I syscall_set
- specification is the same as in the
- .B "-e trace"
- option.
- The default is
- .BR verbose = all .
- .TP
- \fB\-e\ raw\fR=\,\fIsyscall_set\fR
- .TQ
- \fB\-e\ x\fR=\,\fIsyscall_set\fR
- .TQ
- \fB\-\-raw\fR=\,\fIsyscall_set\fR
- Print raw, undecoded arguments for the specified set of system calls.
- The syntax of the
- .I syscall_set
- specification is the same as in the
- .B "-e trace"
- option.
- This option has the effect of causing all arguments to be printed
- in hexadecimal. This is mostly useful if you don't trust the
- decoding or you need to know the actual numeric value of an
- argument.
- See also
- .B \-X raw
- option.
- .TP
- \fB\-e\ read\fR=\,\fIset\fR
- .TQ
- \fB\-e\ reads\fR=\,\fIset\fR
- .TQ
- \fB\-e\ r\fR=\,\fIset\fR
- .TQ
- \fB\-\-read\fR=\,\fIset\fR
- Perform a full hexadecimal and ASCII dump of all the data read from
- file descriptors listed in the specified set. For example, to see
- all input activity on file descriptors
- .I 3
- and
- .I 5
- use
- \fB\-e\ read\fR=\,\fI3\fR,\fI5\fR.
- Note that this is independent from the normal tracing of the
- .BR read (2)
- system call which is controlled by the option
- .BR -e "\ " trace = read .
- .TP
- \fB\-e\ write\fR=\,\fIset\fR
- .TQ
- \fB\-e\ writes\fR=\,\fIset\fR
- .TQ
- \fB\-e\ w\fR=\,\fIset\fR
- .TQ
- \fB\-\-write\fR=\,\fIset\fR
- Perform a full hexadecimal and ASCII dump of all the data written to
- file descriptors listed in the specified set. For example, to see
- all output activity on file descriptors
- .I 3
- and
- .I 5
- use
- \fB\-e\ write\fR=\,\fI3\fR,\,\fI5\fR.
- Note that this is independent from the normal tracing of the
- .BR write (2)
- system call which is controlled by the option
- .BR -e "\ " trace = write .
- .TP
- \fB\-e\ quiet\fR=\,\fIset\fR
- .TQ
- \fB\-e\ silent\fR=\,\fIset\fR
- .TQ
- \fB\-e\ silence\fR=\,\fIset\fR
- .TQ
- \fB\-e\ q\fR=\,\fIset\fR
- .TQ
- \fB\-\-quiet\fR=\,\fIset\fR
- .TQ
- \fB\-\-silent\fR=\,\fIset\fR
- .TQ
- \fB\-\-silence\fR=\,\fIset\fR
- Suppress various information messages. The default is
- .BR quiet = none .
- .I set
- can include the following elements:
- .RS
- .TP 17
- .B attach
- Suppress messages about attaching and detaching
- .RB (\[dq] "[ Process NNNN attached ]" "\[dq],"
- .RB "\[dq]" "[ Process NNNN detached ]" "\[dq])."
- .TQ
- .B exit
- Suppress messages about process exits
- .RB (\[dq] "+++ exited with SSS +++" \[dq]).
- .TQ
- .B path-resolution
- Suppress messages about resolution of paths provided via the
- .B \-P
- option
- .RB (\[dq] "Requested path \[dq]...\[dq] resolved into \[dq]...\[dq]" \[dq]).
- .TQ
- .B personality
- Suppress messages about process personality changes
- .RB (\[dq] "[ Process PID=NNNN runs in PPP mode. ]" \[dq]).
- .TQ
- .B thread-execve
- .TQ
- .B superseded
- Suppress messages about process being superseded by
- .BR execve (2)
- in another thread
- .RB (\[dq] "+++ superseded by execve in pid NNNN +++" \[dq]).
- .RE
- .TP
- \fB\-e\ decode\-fds\fR=\,\fIset\fR
- .TQ
- \fB\-\-decode\-fds\fR=\,\fIset\fR
- Decode various information associated with file descriptors. The default is
- .BR decode\-fds = none .
- .I set
- can include the following elements:
- .RS
- .TP 9
- .B path
- Print file paths.
- Also enables printing of tracee's current working directory when
- .B AT_FDCWD
- constant is used.
- .TQ
- .B socket
- Print socket protocol-specific information.
- .TQ
- .B dev
- Print character/block device numbers.
- .TQ
- .B eventfd
- Print eventfd object details associated with eventfd file descriptors.
- .TQ
- .B pidfd
- Print PIDs associated with pidfd file descriptors.
- .TQ
- .B signalfd
- Print signal masks associated with signalfd file descriptors.
- .RE
- .TP
- \fB\-e\ decode\-pids\fR=\,\fIset\fR
- .TQ
- \fB\-\-decode\-pids\fR=\,\fIset\fR
- Decode various information associated with process IDs
- (and also thread IDs, process group IDs, and session IDs).
- The default is
- .BR decode\-pids = none .
- .I set
- can include the following elements:
- .RS
- .TP 8
- .B comm
- Print command names associated with thread or process IDs.
- .TQ
- .B pidns
- Print thread, process, process group, and session IDs in strace's PID namespace
- if the tracee is in a different PID namespace.
- .RE
- .TP
- .BR "\-e\ kvm" = vcpu
- .TQ
- .BR "\-\-kvm" = vcpu
- Print the exit reason of kvm vcpu. Requires Linux kernel version 4.16.0
- or higher.
- .TP
- .B \-i
- .TQ
- .B \-\-instruction\-pointer
- Print the instruction pointer at the time of the system call.
- .TP
- .B \-n
- .TQ
- .B \-\-syscall\-number
- Print the syscall number.
- .if ''#' .TP
- .if ''#' .B \-k
- .if ''#' .TQ
- .if ''#' .BR \-\-stack\-trace [= symbol ]
- .if ''#' Print the execution stack trace of the traced
- .if ''#' processes after each system call.
- .if '@USE_LIBDW_FALSE@'#' .TP
- .if '@USE_LIBDW_FALSE@'#' .B \-kk
- .if '@USE_LIBDW_FALSE@'#' .TQ
- .if '@USE_LIBDW_FALSE@'#' .BR \-\-stack\-trace = source
- .if '@USE_LIBDW_FALSE@'#' Print the execution stack trace and source code information of the traced
- .if '@USE_LIBDW_FALSE@'#' processes after each system call. This option expects the target program is compiled
- .if '@USE_LIBDW_FALSE@'#' with appropriate debug options: "\-g" (gcc), or "\-g \-gdwarf-aranges" (clang).
- .if ''#' .TP
- .if ''#' .BR \-\-stack\-trace\-frame\-limit = \fIlimit\fR
- .if ''#' Print no more than this amount of stack trace frames
- .if ''#' when backtracing a system call (the default is 256).
- .if ''#' Use this option with the
- .if ''#' .B \-\-stack\-trace
- .if ''#' (or
- .if ''#' .BR \-k )
- .if ''#' option.
- .TP
- .BI "\-o " filename
- .TQ
- .BR "\-\-output" = \fIfilename\fR
- Write the trace output to the file
- .I filename
- rather than to stderr.
- .IR filename . pid
- form is used if
- .B \-ff
- option is supplied.
- If the argument begins with '|' or '!', the rest of the
- argument is treated as a command and all output is piped to it.
- This is convenient for piping the debugging output to a program
- without affecting the redirections of executed programs.
- The latter is not compatible with
- .B \-ff
- option currently.
- .TP
- .B \-A
- .TQ
- .B \-\-output\-append\-mode
- Open the file provided in the
- .B \-o
- option in append mode.
- .TP
- .B \-q
- .TQ
- .B \-\-quiet
- .TQ
- .BR \-\-quiet = attach , personality
- Suppress messages about attaching, detaching, and personality changes.
- This happens automatically when output is redirected to a file
- and the command is run directly instead of attaching.
- .TP
- .B \-qq
- .TQ
- .BR \-\-quiet = attach , personality , exit
- Suppress messages attaching, detaching, personality changes,
- and about process exit status.
- .TP
- .B \-qqq
- .TQ
- .BR \-\-quiet = all
- Suppress all suppressible messages (please refer to the
- .B -e quiet
- option description for the full list of suppressible messages).
- .TP
- .B \-r
- .TQ
- .BR \-\-relative\-timestamps [= \fIprecision\fR ]
- Print a relative timestamp upon entry to each system call. This
- records the time difference between the beginning of successive
- system calls.
- .I precision
- can be one of
- .BR s " (for seconds), " ms " (milliseconds), " us " (microseconds), or " ns
- (nanoseconds), and allows setting the precision of time value being printed.
- Default is
- .B us
- (microseconds).
- Note that since
- .B \-r
- option uses the monotonic clock time for measuring time difference and not the
- wall clock time, its measurements can differ from the difference in time
- reported by the
- .B \-t
- option.
- .TP
- .BI "\-s " strsize
- .TQ
- .BR "\-\-string\-limit" = \fIstrsize\fR
- Specify the maximum string size to print (the default is 32). Note
- that filenames are not considered strings and are always printed in
- full.
- .TP
- .BR \-\-absolute\-timestamps [=[[ format: ] \fIformat\fR ],[[ precision: ] \fIprecision ]]
- .TQ
- .BR \-\-timestamps [=[[ format: ] \fIformat\fR ],[[ precision: ] \fIprecision ]]
- Prefix each line of the trace with the wall clock time in the specified
- .I format
- with the specified
- .IR precision .
- .I format
- can be one of the following:
- .RS
- .TP 14
- .B none
- No time stamp is printed.
- Can be used to override the previous setting.
- .TQ
- .B time
- Wall clock time
- .RB ( strftime (3)
- format string is
- .BR %T ).
- .TQ
- .B unix
- Number of seconds since the epoch
- .RB ( strftime (3)
- format string is
- .BR %s ).
- .RE
- .IP
- .I precision
- can be one of
- .BR s " (for seconds), " ms " (milliseconds), " us " (microseconds), or " ns
- (nanoseconds).
- Default arguments for the option are
- .BR format:time , precision:s .
- .TP
- .B \-t
- .TQ
- .B \-\-absolute\-timestamps
- Prefix each line of the trace with the wall clock time.
- .TP
- .B \-tt
- .TQ
- .BR \-\-absolute\-timestamps = precision:us
- If given twice, the time printed will include the microseconds.
- .TP
- .B \-ttt
- .TQ
- .BR \-\-absolute\-timestamps = format:unix , precision:us
- If given thrice, the time printed will include the microseconds
- and the leading portion will be printed as the number
- of seconds since the epoch.
- .TP
- .B \-T
- .TQ
- .BR \-\-syscall\-times [= \fIprecision\fR ]
- Show the time spent in system calls. This records the time
- difference between the beginning and the end of each system call.
- .I precision
- can be one of
- .BR s " (for seconds), " ms " (milliseconds), " us " (microseconds), or " ns
- (nanoseconds), and allows setting the precision of time value being printed.
- Default is
- .B us
- (microseconds).
- .TP
- .B \-v
- .TQ
- .B \-\-no\-abbrev
- Print unabbreviated versions of environment, stat, termios, etc.
- calls. These structures are very common in calls and so the default
- behavior displays a reasonable subset of structure members. Use
- this option to get all of the gory details.
- .TP
- .BR \-\-strings\-in\-hex [= \fIoption\fR ]
- Control usage of escape sequences with hexadecimal numbers
- in the printed strings.
- Normally (when no
- .BR \-\-strings\-in\-hex " or " \-x
- option is supplied),
- escape sequences are used to print non-printable and non-ASCII characters
- (that is, characters with a character code less than 32 or greater than 127),
- or to disambiguate the output
- (so, for quotes and other characters that encase the printed string,
- for example, angle brackets, in case of file descriptor path output);
- for the former use case, unless it is a white space character
- that has a symbolic escape sequence defined in the C standard
- (that is, \(lq\fB\\t\fR\(rq for a horizontal tab,
- \(lq\fB\\n\fR\(rq for a newline,
- \(lq\fB\\v\fR\(rq for a vertical tab,
- \(lq\fB\\f\fR\(rq for a form feed page break,
- and \(lq\fB\\r\fR\(rq for a carriage return)
- are printed using escape sequences with numbers that correspond
- to their byte values, with octal number format being the default.
- .I option
- can be one of the following:
- .RS
- .TP 17
- .B none
- Hexadecimal numbers are not used in the output at all.
- When there is a need to emit an escape sequence, octal numbers are used.
- .TQ
- .B non-ascii-chars
- Hexadecimal numbers are used instead of octal in the escape sequences.
- .TQ
- .B non-ascii
- Strings that contain non-ASCII characters are printed using escape sequences
- with hexadecimal numbers.
- .TQ
- .B all
- All strings are printed using escape sequences with hexadecimal numbers.
- .RE
- .IP
- When the option is supplied without an argument,
- .B all
- is assumed.
- .TP
- .B \-x
- .TQ
- .BR \-\-strings\-in\-hex = non\-ascii
- Print all non-ASCII strings in hexadecimal string format.
- .TP
- .B \-xx
- .TQ
- .BR \-\-strings\-in\-hex [= all ]
- Print all strings in hexadecimal string format.
- .TP
- .BI "\-X " format
- .TQ
- .BR "\-\-const\-print\-style" = \fIformat\fR
- Set the format for printing of named constants and flags.
- Supported
- .I format
- values are:
- .RS
- .TP 10
- .B raw
- Raw number output, without decoding.
- .TQ
- .B abbrev
- Output a named constant or a set of flags instead of the raw number if they are
- found.
- This is the default
- .B strace
- behaviour.
- .TQ
- .B verbose
- Output both the raw value and the decoded string (as a comment).
- .RE
- .TP
- .B \-y
- .TQ
- .B \-\-decode\-fds
- .TQ
- .BR \-\-decode\-fds = path
- Print paths associated with file descriptor arguments and with the
- .B AT_FDCWD
- constant.
- .TP
- .B \-yy
- .TQ
- .BR \-\-decode\-fds = all
- Print all available information associated with file descriptors:
- protocol-specific information associated with socket file descriptors,
- block/character device number associated with device file descriptors,
- and PIDs associated with pidfd file descriptors.
- .TP
- .B \-\-pidns\-translation
- .TQ
- .BR \-\-decode\-pids = pidns
- If strace and tracee are in different PID namespaces, print PIDs in
- strace's namespace, too.
- .TP
- .B \-Y
- .TQ
- .BR \-\-decode\-pids = comm
- Print command names for PIDs.
- .if ''#' .TP
- .if ''#' .BR \-\-secontext\fR[=\fIformat\fR]
- .if ''#' .TQ
- .if ''#' .BR \-e\ secontext\fR=\fIformat\fR
- .if ''#' When SELinux is available and is not disabled,
- .if ''#' print in square brackets SELinux contexts of
- .if ''#' processes, files, and descriptors. The
- .if ''#' .I format
- .if ''#' argument is a comma-separated list of items
- .if ''#' being one of the following:
- .if ''#' .RS
- .if ''#' .TP 18
- .if ''#' .BR full
- .if ''#' Print the full context (user, role, type level
- .if ''#' and category).
- .if ''#' .TQ
- .if ''#' .BR mismatch
- .if ''#' Also print the context recorded by the SELinux
- .if ''#' database in case the current context differs.
- .if ''#' The latter is printed after two exclamation marks (!!).
- .if ''#' .RE
- .if ''#' .IP
- .if ''#' The default value for
- .if ''#' .BR \-\-secontext
- .if ''#' is
- .if ''#' .BR !full,mismatch
- .if ''#' which prints only the type instead of full context
- .if ''#' and doesn't check for context mismatches.
- .TP
- .B \-\-always\-show\-pid
- Show PID prefix also for the process started by strace.
- Implied when \-f and \-o are both specified.
- .RE
- .SS Statistics
- .TP 12
- .B \-c
- .TQ
- .B \-\-summary\-only
- Count time, calls, and errors for each system call and report a summary on
- program exit, suppressing the regular output.
- This attempts to show system time (CPU time spent running
- in the kernel) independent of wall clock time. If
- .B \-c
- is used with
- .BR \-f ,
- only aggregate totals for all traced processes are kept.
- .TP
- .B \-C
- .TQ
- .B \-\-summary
- Like
- .B \-c
- but also print regular output while processes are running.
- .TP
- .BI "\-O " overhead
- .TQ
- .BR "\-\-summary\-syscall\-overhead" = \fIoverhead\fR
- Set the overhead for tracing system calls to
- .IR overhead .
- This is useful for overriding the default heuristic for guessing
- how much time is spent in mere measuring when timing system calls using
- the
- .B \-c
- option. The accuracy of the heuristic can be gauged by timing a given
- program run without tracing (using
- .BR time (1))
- and comparing the accumulated
- system call time to the total produced using
- .BR \-c .
- .IP
- The format of
- .I overhead
- specification is described in section
- .IR "Time specification format description".
- .TP
- .BI "\-S " sortby
- .TQ
- .BR "\-\-summary\-sort\-by" = \fIsortby\fR
- Sort the output of the histogram printed by the
- .B \-c
- option by the specified criterion. Legal values are
- .BR time " (or " time\-percent " or " time\-total " or " total\-time ),
- .BR min\-time " (or " shortest " or " time\-min ),
- .BR max\-time " (or " longest " or " time\-max ),
- .BR avg\-time " (or " time\-avg ),
- .BR calls " (or " count ),
- .BR errors " (or " error ),
- .BR name " (or " syscall " or " syscall\-name ),
- and
- .BR nothing " (or " none );
- default is
- .BR time .
- .TP
- .BI "\-U " columns
- .TQ
- .BR "\-\-summary\-columns" = \fIcolumns\fR
- Configure a set (and order) of columns being shown in the call summary.
- The
- .I columns
- argument is a comma-separated list with items being one of the following:
- .RS
- .TP 36
- .BR time\-percent " (or " time )
- Percentage of cumulative time consumed by a specific system call.
- .TQ
- .BR total\-time " (or " time\-total )
- Total system (or wall clock, if
- .B \-w
- option is provided) time consumed by a specific system call.
- .TQ
- .BR min\-time " (or " shortest " or " time\-min )
- Minimum observed call duration.
- .TQ
- .BR max\-time " (or " longest " or " time\-max )
- Maximum observed call duration.
- .TQ
- .BR avg\-time " (or " time\-avg )
- Average call duration.
- .TQ
- .BR calls " (or " count )
- Call count.
- .TQ
- .BR errors " (or " error )
- Error count.
- .TQ
- .BR name " (or " syscall " or " syscall\-name )
- Syscall name.
- .RE
- .IP
- The default value is
- .BR time\-percent , total\-time , avg\-time , calls , errors , name .
- If the
- .B name
- field is not supplied explicitly, it is added as the last column.
- .TP
- .B \-w
- .TQ
- .B \-\-summary\-wall\-clock
- Summarise the time difference between the beginning and end of
- each system call. The default is to summarise the system time.
- .SS Tampering
- .ad l
- .TP 12
- \fB\-e\ inject\fR=\,\fIsyscall_set\/\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]\:[:\fBpoke_enter\fR=\,\fI@argN=DATAN,@argM=DATAM...\/\fR]\:[:\fBpoke_exit\fR=\,\fI@argN=DATAN,@argM=DATAM...\/\fR]\:[:\fBwhen\fR=\,\fIexpr\/\fR] \{
- .TQ
- \fB\-\-inject\fR=\,\fIsyscall_set\/\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]\:[:\fBpoke_enter\fR=\,\fI@argN=DATAN,@argM=DATAM...\/\fR]\:[:\fBpoke_exit\fR=\,\fI@argN=DATAN,@argM=DATAM...\/\fR]\:[:\fBwhen\fR=\,\fIexpr\/\fR] \{
- .ad b
- Perform syscall tampering for the specified set of syscalls.
- The syntax of the
- .I syscall_set
- specification is the same as in the
- .B "-e trace"
- option.
- .IP
- At least one of
- .BR error ,
- .BR retval ,
- .BR signal ,
- .BR delay_enter ,
- .BR delay_exit ,
- .BR poke_enter ,
- or
- .B poke_exit
- options has to be specified.
- .B error
- and
- .B retval
- are mutually exclusive.
- .IP
- If :\fBerror\fR=\,\fIerrno\/\fR option is specified,
- a fault is injected into a syscall invocation:
- the syscall number is replaced by -1 which corresponds to an invalid syscall
- (unless a syscall is specified with :\fBsyscall=\fR option),
- and the error code is specified using a symbolic
- .I errno
- value like
- .B ENOSYS
- or a numeric value within 1..4095 range.
- .IP
- If :\fBretval\fR=\,\fIvalue\/\fR option is specified,
- success injection is performed: the syscall number is replaced by -1,
- but a bogus success value is returned to the callee.
- .IP
- If :\fBsignal\fR=\,\fIsig\/\fR option is specified with either a symbolic value
- like
- .B SIGSEGV
- or a numeric value within 1..\fBSIGRTMAX\fR range,
- that signal is delivered on entering every syscall specified by the
- .IR set .
- .IP
- If :\fBdelay_enter\fR=\,\fIdelay\/\fR or :\fBdelay_exit\fR=\,\fIdelay\/\fR
- options are specified, delay injection is performed: the tracee is delayed
- by time period specified by
- .IR delay
- on entering or exiting the syscall, respectively.
- The format of
- .I delay
- specification is described in section
- .IR "Time specification format description".
- .IP
- If :\fBpoke_enter\fR=\fI@argN=DATAN,@argM=DATAM...\fR
- or :\fBpoke_exit\fR=\fI@argN=DATAN,@argM=DATAM...\fR options are specified,
- tracee's memory at locations, pointed to by system call arguments
- .IR argN
- and
- .IR argM
- (going from
- .IR arg1
- to
- .IR arg7 )
- is overwritten by data
- .IR DATAN
- and
- .IR DATAM
- (specified in hexadecimal format; for example :\fBpoke_enter\fR=\fI@arg1=0000DEAD0000BEEF\fR).
- :\fBpoke_enter\fR modifies memory on syscall enter, and :\fBpoke_exit\fR - on exit.
- .IP
- If :\fBsignal\fR=\,\fIsig\/\fR option is specified without
- :\fBerror\fR=\,\fIerrno\/\fR, :\fBretval\fR=\,\fIvalue\/\fR or
- :\fBdelay_{enter,exit}\fR=\,\fIusecs\/\fR options,
- then only a signal
- .I sig
- is delivered without a syscall fault or delay injection.
- Conversely, :\fBerror\fR=\,\fIerrno\/\fR or
- :\fBretval\fR=\,\fIvalue\/\fR option without
- :\fBdelay_enter\fR=\,\fIdelay\/\fR,
- :\fBdelay_exit\fR=\,\fIdelay\/\fR or
- :\fBsignal\fR=\,\fIsig\/\fR options injects a fault without delivering a signal
- or injecting a delay, etc.
- .IP
- If
- :\fBsignal\fR=\,\fIsig\/\fR
- option is specified together with
- :\fBerror\fR=\,\fIerrno\/\fR or :\fBretval\fR=\,\fIvalue\/\fR,
- then both injection of a fault or success and signal delivery are performed.
- .IP
- if :\fBsyscall\fR=\fIsyscall\fR option is specified, the corresponding syscall
- with no side effects is injected instead of -1.
- Currently, only "pure" (see
- .BR "-e trace" = "%pure"
- description) syscalls can be specified there.
- .IP
- Unless a :\fBwhen\fR=\,\fIexpr\fR subexpression is specified,
- an injection is being made into every invocation of each syscall from the
- .IR set .
- .IP
- The format of the subexpression is:
- .RS 15
- .IP
- \fIfirst\/\fR[\fB..\fR\,\fIlast\/\fR][\fB+\fR[\,\fIstep\/\fR]]
- .RE
- .IP
- Number
- .I first
- stands for the first invocation number in the range, number
- .I last
- stands for the last invocation number in the range, and
- .I step
- stands for the step between two consecutive invocations.
- The following combinations are useful:
- .RS
- .TP 18
- .I first
- For every syscall from the
- .IR set ,
- perform an injection for the syscall invocation number
- .I first
- only.
- .TQ
- \fIfirst\/\fB..\fR\,\fIlast\fR
- For every syscall from the
- .IR set ,
- perform an injection for the syscall invocation number
- .I first
- and all subsequent invocations until the invocation number
- .I last
- (inclusive).
- .TQ
- \fIfirst\/\fB+\fR
- For every syscall from the
- .IR set ,
- perform injections for the syscall invocation number
- .I first
- and all subsequent invocations.
- .TQ
- \fIfirst\/\fB..\fR\,\fIlast\/\fB+\fR
- For every syscall from the
- .IR set ,
- perform injections for the syscall invocation number
- .I first
- and all subsequent invocations until the invocation number
- .I last
- (inclusive).
- .TQ
- \fIfirst\/\fB+\fR\,\fIstep\fR
- For every syscall from the
- .IR set ,
- perform injections for syscall invocations number
- .IR first ,
- .IR first + step ,
- .IR first + step + step ,
- and so on.
- .TQ
- \fIfirst\/\fB..\fR\,\fIlast\fB+\fR\,\fIstep\fR
- Same as the previous, but consider only syscall invocations with numbers up to
- .I last
- (inclusive).
- .RE
- .IP
- For example, to fail each third and subsequent chdir syscalls with
- .BR ENOENT ,
- use
- \fB\-e\ inject\fR=\,\fIchdir\/\fR:\fBerror\fR=\,\fIENOENT\/\fR:\fBwhen\fR=\,\fI3\/\fB+\fR.
- .IP
- The valid range for numbers
- .I first
- and
- .I step
- is 1..65535, and for number
- .I last
- is 1..65534.
- .IP
- An injection expression can contain only one
- .BR error =
- or
- .BR retval =
- specification, and only one
- .BR signal =
- specification. If an injection expression contains multiple
- .BR when =
- specifications, the last one takes precedence.
- .IP
- Accounting of syscalls that are subject to injection
- is done per syscall and per tracee.
- .IP
- Specification of syscall injection can be combined
- with other syscall filtering options, for example,
- \fB\-P \fI/dev/urandom \fB\-e inject\fR=\,\fIfile\/\fR:\fBerror\fR=\,\fIENOENT\fR.
- .TP
- \fB\-e\ fault\fR=\,\fIsyscall_set\/\fR[:\fBerror\fR=\,\fIerrno\/\fR][:\fBwhen\fR=\,\fIexpr\/\fR]
- .TQ
- \fB\-\-fault\fR=\,\fIsyscall_set\/\fR[:\fBerror\fR=\,\fIerrno\/\fR][:\fBwhen\fR=\,\fIexpr\/\fR]
- Perform syscall fault injection for the specified set of syscalls.
- .IP
- This is equivalent to more generic
- \fB\-e\ inject\fR= expression with default value of
- .I errno
- option set to
- .BR ENOSYS .
- .SS Miscellaneous
- .TP 12
- .B \-d
- .TQ
- .B \-\-debug
- Show some debugging output of
- .B strace
- itself on the standard error.
- .TP
- .B \-F
- This option is deprecated. It is retained for backward compatibility only
- and may be removed in future releases.
- Usage of multiple instances of
- .B \-F
- option is still equivalent to a single
- .BR \-f ,
- and it is ignored at all if used along with one or more instances of
- .B \-f
- option.
- .TP
- .B \-h
- .TQ
- .B \-\-help
- Print the help summary.
- .TP
- .B \-\-seccomp\-bpf
- Try to enable use of seccomp-bpf (see
- .BR seccomp (2))
- to have
- .BR ptrace (2)-stops
- only when system calls that are being traced occur in the traced processes.
- .IP
- This option has no effect unless
- .BR \-f / \-\-follow\-forks
- is also specified.
- .B \-\-seccomp\-bpf
- is not compatible with
- .B \-\-syscall\-limit
- and
- .BR \-b / \-\-detach\-on
- options. It is also not applicable to processes attached using
- .BR \-p / \-\-attach
- option.
- .IP
- An attempt to enable system calls filtering using seccomp-bpf may
- fail for various reasons, e.g. there are too many system calls to filter,
- the seccomp API is not available, or
- .B strace
- itself is being traced.
- In cases when seccomp-bpf filter setup failed,
- .B strace
- proceeds as usual and stops traced processes on every system call.
- .IP
- When
- .B \-\-seccomp\-bpf
- is activated and
- .BR \-p / \-\-attach
- option is not used,
- .B \-\-kill\-on\-exit
- option is activated as well.
- .IP
- Note that in cases when the tracee has another seccomp filter that
- returns an action value with a precedence greater than
- .BR SECCOMP_RET_TRACE ,
- .B strace \-\-seccomp\-bpf
- will not be notified. That is, if another seccomp filter, for example,
- disables the syscall or kills the tracee, then
- .B strace \-\-seccomp\-bpf
- will not be aware of that syscall invocation at all.
- .TP
- .BR \-\-tips [=[[ id: ] \fIid\fR ],[[ format: ] \fIformat\fR ]]
- Show strace tips, tricks, and tweaks before exit.
- .I id
- can be a non-negative integer number,
- which enables printing of specific tip, trick, or tweak
- (these ID are not guaranteed to be stable),
- or
- .B random
- (the default),
- in which case a random tip is printed.
- .I format
- can be one of the following:
- .RS
- .TP 9
- .B none
- No tip is printed.
- Can be used to override the previous setting.
- .TQ
- .B compact
- Print the tip just big enough to contain all the text.
- .TQ
- .B full
- Print the tip in its full glory.
- .RE
- .IP
- Default is
- .BR id:random,format:compact .
- .TP
- .B \-V
- .TQ
- .B \-\-version
- Print the version number of
- .BR strace .
- Multiple instances of the option beyond specific threshold tend to increase
- Strauss awareness.
- .SS "Time specification format description"
- .PP
- Time values can be specified as a decimal floating point number
- (in a format accepted by
- .BR strtod (3)),
- optionally followed by one of the following suffices that specify
- the unit of time:
- .B s
- (seconds),
- .B ms
- (milliseconds),
- .B us
- (microseconds), or
- .B ns
- (nanoseconds).
- If no suffix is specified, the value is interpreted as microseconds.
- .PP
- The described format is used for
- .BR \-O ", " "\-e inject" = delay_enter ", and " "\-e inject" = delay_exit
- options.
- .SH DIAGNOSTICS
- When
- .I command
- exits,
- .B strace
- exits with the same exit status.
- If
- .I command
- is terminated by a signal,
- .B strace
- terminates itself with the same signal, so that
- .B strace
- can be used as a wrapper process transparent to the invoking parent process.
- Note that parent-child relationship (signal stop notifications,
- .BR getppid (2)
- value, etc) between traced process and its parent are not preserved
- unless
- .B \-D
- is used.
- .LP
- When using
- .B \-p
- without a
- .IR command ,
- the exit status of
- .B strace
- is zero unless no processes has been attached or there was an unexpected error
- in doing the tracing.
- .SH "SETUID INSTALLATION"
- If
- .B strace
- is installed setuid to root then the invoking user will be able to
- attach to and trace processes owned by any user.
- In addition setuid and setgid programs will be executed and traced
- with the correct effective privileges.
- Since only users trusted with full root privileges should be allowed
- to do these things,
- it only makes sense to install
- .B strace
- as setuid to root when the users who can execute it are restricted
- to those users who have this trust.
- For example, it makes sense to install a special version of
- .B strace
- with mode 'rwsr-xr--', user
- .B root
- and group
- .BR trace ,
- where members of the
- .B trace
- group are trusted users.
- If you do use this feature, please remember to install
- a regular non-setuid version of
- .B strace
- for ordinary users to use.
- .SH "MULTIPLE PERSONALITIES SUPPORT"
- On some architectures,
- .B strace
- supports decoding of syscalls for processes that use different ABI rather than
- the one
- .B strace
- uses.
- Specifically, in addition to decoding native ABI,
- .B strace
- can decode the following ABIs on the following architectures:
- .TS H
- allbox;
- lb lb
- l l.
- Architecture ABIs supported
- x86_64 i386, x32 [1]; i386 [2]
- AArch64 ARM 32-bit EABI
- PowerPC 64-bit [3] PowerPC 32-bit
- s390x s390
- SPARC 64-bit SPARC 32-bit
- TILE 64-bit TILE 32-bit
- .TE
- .RS 0
- .TP 5
- [1]
- When
- .B strace
- is built as an x86_64 application
- .TQ
- [2]
- When
- .B strace
- is built as an x32 application
- .TQ
- [3]
- Big endian only
- .RE
- .PP
- This support is optional and relies on ability to generate and parse structure
- definitions during the build time.
- Please refer to the output of the
- .B strace \-V
- command in order to figure out what support is available in your
- .B strace
- build ("non-native" refers to an ABI that differs from the ABI
- .B strace
- has):
- .TP 15
- .B m32-mpers
- .B strace
- can trace and properly decode non-native 32-bit binaries.
- .TQ
- .B no-m32-mpers
- .B strace
- can trace, but cannot properly decode non-native 32-bit binaries.
- .TQ
- .B mx32-mpers
- .B strace
- can trace and properly decode non-native 32-on-64-bit binaries.
- .TQ
- .B no-mx32-mpers
- .B strace
- can trace, but cannot properly decode non-native 32-on-64-bit binaries.
- .PP
- If the output contains neither
- .B m32-mpers
- nor
- .BR no-m32-mpers ,
- then decoding of non-native 32-bit binaries is not implemented at all
- or not applicable.
- .PP
- Likewise, if the output contains neither
- .B mx32-mpers
- nor
- .BR no-mx32-mpers ,
- then decoding of non-native 32-on-64-bit binaries is not implemented at all
- or not applicable.
- .SH NOTES
- It is a pity that so much tracing clutter is produced by systems
- employing shared libraries.
- .LP
- It is instructive to think about system call inputs and outputs
- as data-flow across the user/kernel boundary. Because user-space
- and kernel-space are separate and address-protected, it is
- sometimes possible to make deductive inferences about process
- behavior using inputs and outputs as propositions.
- .LP
- In some cases, a system call will differ from the documented behavior
- or have a different name. For example, the
- .BR faccessat (2)
- system call does not have
- .I flags
- argument, and the
- .BR setrlimit (2)
- library function uses
- .BR prlimit64 (2)
- system call on modern (2.6.38+) kernels. These
- discrepancies are normal but idiosyncratic characteristics of the
- system call interface and are accounted for by C library wrapper
- functions.
- .LP
- Some system calls have different names in different architectures and
- personalities. In these cases, system call filtering and printing
- uses the names that match corresponding
- .BR __NR_ *
- kernel macros of the tracee's architecture and personality.
- There are two exceptions from this general rule:
- .BR arm_fadvise64_64 (2)
- ARM syscall and
- .BR xtensa_fadvise64_64 (2)
- Xtensa syscall are filtered and printed as
- .BR fadvise64_64 (2).
- .LP
- On x32, syscalls that are intended to be used by 64-bit processes and not x32
- ones (for example,
- .BR readv (2),
- that has syscall number 19 on x86_64, with its x32 counterpart has syscall
- number 515), but called with
- .B __X32_SYSCALL_BIT
- flag being set, are designated with
- .B "#64"
- suffix.
- .LP
- On some platforms a process that is attached to with the
- .B \-p
- option may observe a spurious
- .B EINTR
- return from the current system call that is not restartable.
- (Ideally, all system calls should be restarted on
- .B strace
- attach, making the attach invisible
- to the traced process, but a few system calls aren't.
- Arguably, every instance of such behavior is a kernel bug.)
- This may have an unpredictable effect on the process
- if the process takes no action to restart the system call.
- .LP
- As
- .B strace
- executes the specified
- .I command
- directly and does not employ a shell for that, scripts without shebang
- that usually run just fine when invoked by shell fail to execute with
- .B ENOEXEC
- error.
- It is advisable to manually supply a shell as a
- .I command
- with the script as its argument.
- .SH BUGS
- Programs that use the
- .I setuid
- bit do not have
- effective user
- .SM ID
- privileges while being traced.
- .LP
- A traced process runs slowly (but check out the
- .B \-\-seccomp\-bpf
- option).
- .LP
- Unless
- .B \-\-kill\-on\-exit
- option is used (or
- .B \-\-seccomp\-bpf
- option is used in a way that implies
- .BR \-\-kill\-on\-exit ),
- traced processes which are descended from
- .I command
- may be left running after an interrupt signal
- .RB ( CTRL\-C ).
- .LP
- By using
- .B CLONE_UNTRACED
- flag of
- .B clone
- system call a tracee can break the guarantee that
- .B \-\-seccomp\-bpf
- will not leave any processes with a seccomp program installed
- for syscall filtering purposes.
- .SH HISTORY
- The original
- .B strace
- was written by Paul Kranenburg
- for SunOS and was inspired by its
- .B trace
- utility.
- The SunOS version of
- .B strace
- was ported to Linux and enhanced
- by Branko Lankester, who also wrote the Linux kernel support.
- Even though Paul released
- .B strace
- 2.5 in 1992,
- Branko's work was based on Paul's
- .B strace
- 1.5 release from 1991.
- In 1993, Rick Sladkey merged
- .B strace
- 2.5 for SunOS and the second release of
- .B strace
- for Linux, added many of the features of
- .BR truss (1)
- from SVR4, and produced an
- .B strace
- that worked on both platforms. In 1994 Rick ported
- .B strace
- to SVR4 and Solaris and wrote the
- automatic configuration support. In 1995 he ported
- .B strace
- to Irix
- and became tired of writing about himself in the third person.
- .PP
- Beginning with 1996,
- .B strace
- was maintained by Wichert Akkerman.
- During his tenure,
- .B strace
- development migrated to CVS; ports to FreeBSD and many architectures on Linux
- (including ARM, IA-64, MIPS, PA-RISC, PowerPC, s390, SPARC) were introduced.
- In 2002, the burden of
- .B strace
- maintainership was transferred to Roland McGrath.
- Since then,
- .B strace
- gained support for several new Linux architectures (AMD64, s390x, SuperH),
- bi-architecture support for some of them, and received numerous additions and
- improvements in syscalls decoders on Linux;
- .B strace
- development migrated to
- .B Git
- during that period.
- Since 2009,
- .B strace
- is actively maintained by Dmitry Levin.
- .B strace
- gained support for AArch64, ARC, AVR32, Blackfin, Meta, Nios II, OpenRISC 1000,
- RISC-V, Tile/TileGx, Xtensa architectures since that time.
- In 2012, unmaintained and apparently broken support for non-Linux operating
- systems was removed.
- Also, in 2012
- .B strace
- gained support for path tracing and file descriptor path decoding.
- In 2014, support for stack trace printing was added.
- In 2016, syscall fault injection was implemented.
- .PP
- For the additional information, please refer to the
- .B NEWS
- file and
- .B strace
- repository commit log.
- .SH REPORTING BUGS
- Problems with
- .B strace
- should be reported to the
- .UR mailto:strace\-devel@lists.strace.io
- .B strace
- mailing list
- .UE .
- .SH "SEE ALSO"
- .BR strace-log-merge (1),
- .BR ltrace (1),
- .BR perf-trace (1),
- .BR trace-cmd (1),
- .BR time (1),
- .BR ptrace (2),
- .BR seccomp (2),
- .BR syscall (2),
- .BR proc (5),
- .BR signal (7)
- .PP
- .UR https://strace.io/
- .B strace
- Home Page
- .UE
- .SH AUTHORS
- The complete list of
- .B strace
- contributors can be found in the
- .B CREDITS
- file.