1STRACE(1)                   General Commands Manual                  STRACE(1)
2
3
4

NAME

6       strace - trace system calls and signals
7

SYNOPSIS

9       strace [-ACdffhikqqrtttTvVwxxyyzZ] [-I n] [-b execve] [-e expr]...
10              [-a column] [-o file] [-s strsize] [-X format] [-P path]...
11              [-p pid]... [--seccomp-bpf] { -p pid | [-D] [-E var[=val]]...
12              [-u username] command [args] }
13
14       strace -c [-dfwzZ] [-I n] [-b execve] [-e expr]... [-O overhead]
15              [-S sortby] [-P path]... [-p pid]... [--seccomp-bpf] { -p pid |
16              [-D] [-E var[=val]]... [-u username] command [args] }
17
18

DESCRIPTION

20       In the simplest case strace runs the specified command until it  exits.
21       It  intercepts  and  records  the  system  calls  which are called by a
22       process and the signals which are received by a process.  The  name  of
23       each  system  call,  its  arguments and its return value are printed on
24       standard error or to the file specified with the -o option.
25
26       strace is a useful diagnostic, instructional, and debugging tool.  Sys‐
27       tem  administrators,  diagnosticians  and trouble-shooters will find it
28       invaluable for solving problems with programs for which the  source  is
29       not  readily available since they do not need to be recompiled in order
30       to trace them.  Students, hackers and the overly-curious will find that
31       a  great  deal  can  be  learned about a system and its system calls by
32       tracing even ordinary programs.  And programmers will find  that  since
33       system  calls  and  signals  are  events that happen at the user/kernel
34       interface, a close examination of this boundary is very useful for  bug
35       isolation, sanity checking and attempting to capture race conditions.
36
37       Each  line  in the trace contains the system call name, followed by its
38       arguments in parentheses and its return value.  An example from  strac‐
39       ing the command "cat /dev/null" is:
40
41           open("/dev/null", O_RDONLY) = 3
42
43       Errors (typically a return value of -1) have the errno symbol and error
44       string appended.
45
46           open("/foo/bar", O_RDONLY) = -1 ENOENT (No such file or directory)
47
48       Signals are printed as signal symbol and decoded siginfo structure.  An
49       excerpt from stracing and interrupting the command "sleep 666" is:
50
51           sigsuspend([] <unfinished ...>
52           --- SIGINT {si_signo=SIGINT, si_code=SI_USER, si_pid=...} ---
53           +++ killed by SIGINT +++
54
55       If  a  system call is being executed and meanwhile another one is being
56       called from a different thread/process then strace will try to preserve
57       the  order  of  those  events and mark the ongoing call as being unfin‐
58       ished.  When the call returns it will be marked as resumed.
59
60           [pid 28772] select(4, [3], NULL, NULL, NULL <unfinished ...>
61           [pid 28779] clock_gettime(CLOCK_REALTIME, {1130322148, 939977000}) = 0
62           [pid 28772] <... select resumed> )      = 1 (in [3])
63
64       Interruption of a (restartable) system call by  a  signal  delivery  is
65       processed  differently  as  kernel  terminates the system call and also
66       arranges its immediate reexecution after the signal handler completes.
67
68           read(0, 0x7ffff72cf5cf, 1)              = ? ERESTARTSYS (To be restarted)
69           --- SIGALRM ... ---
70           rt_sigreturn(0xe)                       = 0
71           read(0, "", 1)                          = 0
72
73       Arguments are printed in symbolic  form  with  passion.   This  example
74       shows the shell performing ">>xyzzy" output redirection:
75
76           open("xyzzy", O_WRONLY|O_APPEND|O_CREAT, 0666) = 3
77
78       Here,  the  third  argument  of open(2) is decoded by breaking down the
79       flag argument into its three bitwise-OR constituents and  printing  the
80       mode  value  in  octal  by  tradition.  Where the traditional or native
81       usage differs from ANSI or POSIX, the latter forms are  preferred.   In
82       some  cases,  strace  output  is  proven  to  be more readable than the
83       source.
84
85       Structure pointers are dereferenced and the members  are  displayed  as
86       appropriate.  In most cases, arguments are formatted in the most C-like
87       fashion possible.  For example, the  essence  of  the  command  "ls  -l
88       /dev/null" is captured as:
89
90           lstat("/dev/null", {st_mode=S_IFCHR|0666, st_rdev=makedev(0x1, 0x3), ...}) = 0
91
92       Notice how the 'struct stat' argument is dereferenced and how each mem‐
93       ber is displayed symbolically.  In particular, observe how the  st_mode
94       member  is  carefully decoded into a bitwise-OR of symbolic and numeric
95       values.  Also notice  in  this  example  that  the  first  argument  to
96       lstat(2)  is  an input to the system call and the second argument is an
97       output.  Since output arguments are not modified  if  the  system  call
98       fails, arguments may not always be dereferenced.  For example, retrying
99       the "ls -l" example with a non-existent  file  produces  the  following
100       line:
101
102           lstat("/foo/bar", 0xb004) = -1 ENOENT (No such file or directory)
103
104       In this case the porch light is on but nobody is home.
105
106       Syscalls  unknown  to  strace  are printed raw, with the unknown system
107       call number printed in hexadecimal form and prefixed with "syscall_":
108
109           syscall_0xbad(0x1, 0x2, 0x3, 0x4, 0x5, 0x6) = -1 ENOSYS (Function not implemented)
110
111
112       Character pointers are dereferenced and printed  as  C  strings.   Non-
113       printing  characters  in strings are normally represented by ordinary C
114       escape codes.  Only the first strsize (32 by default) bytes of  strings
115       are  printed;  longer  strings  have an ellipsis appended following the
116       closing quote.  Here is a line  from  "ls  -l"  where  the  getpwuid(3)
117       library routine is reading the password file:
118
119           read(3, "root::0:0:System Administrator:/"..., 1024) = 422
120
121       While  structures are annotated using curly braces, simple pointers and
122       arrays are printed using square brackets with  commas  separating  ele‐
123       ments.  Here is an example from the command id(1) on a system with sup‐
124       plementary group ids:
125
126           getgroups(32, [100, 0]) = 2
127
128       On the other hand, bit-sets are also shown using  square  brackets  but
129       set elements are separated only by a space.  Here is the shell, prepar‐
130       ing to execute an external command:
131
132           sigprocmask(SIG_BLOCK, [CHLD TTOU], []) = 0
133
134       Here, the second argument is a bit-set  of  two  signals,  SIGCHLD  and
135       SIGTTOU.   In  some cases, the bit-set is so full that printing out the
136       unset elements is more valuable.  In that case, the bit-set is prefixed
137       by a tilde like this:
138
139           sigprocmask(SIG_UNBLOCK, ~[], NULL) = 0
140
141       Here, the second argument represents the full set of all signals.
142

OPTIONS

144   General
145       -e expr     A  qualifying  expression  which  modifies  which events to
146                   trace or how to trace them.  The format of  the  expression
147                   is:
148
149                             [qualifier=][!][?]value1[,[?]value2]...
150
151                   where qualifier is one of trace, abbrev, verbose, raw, sig‐
152                   nal, read, write, fault, inject, status, or kvm  and  value
153                   is  a  qualifier-dependent  symbol  or number.  The default
154                   qualifier is trace.  Using an exclamation mark negates  the
155                   set  of  values.   For  example,  -e open  means  literally
156                   -e trace=open which in turn means trace only the open  sys‐
157                   tem call.  By contrast, -e trace=!open means to trace every
158                   system call except open.  Question mark before the  syscall
159                   qualification  allows  suppression  of  error  in  case  no
160                   syscalls matched the qualification provided.  Appending one
161                   of "@64", "@32", or "@x32" suffixes to the syscall qualifi‐
162                   cation allows specifying  syscalls  only  for  the  64-bit,
163                   32-bit,  or  32-on-64-bit  personality,  respectively.   In
164                   addition, the special values all and none have the  obvious
165                   meanings.
166
167                   Note that some shells use the exclamation point for history
168                   expansion even inside quoted arguments.  If  so,  you  must
169                   escape the exclamation point with a backslash.
170
171   Startup
172       -E var=val  Run  command  with var=val in its list of environment vari‐
173                   ables.
174
175       -E var      Remove var from the inherited list of environment variables
176                   before passing it on to the command.
177
178       -p pid      Attach  to  the  process  with the process ID pid and begin
179                   tracing.  The trace may be terminated at any time by a key‐
180                   board  interrupt  signal  (CTRL-C).  strace will respond by
181                   detaching itself from the  traced  process(es)  leaving  it
182                   (them)  to  continue  running.   Multiple -p options can be
183                   used to attach to many processes  in  addition  to  command
184                   (which is optional if at least one -p option is given).  -p
185                   "`pidof PROG`" syntax is supported.
186
187       -u username Run command with the user ID, group ID,  and  supplementary
188                   groups  of  username.  This option is only useful when run‐
189                   ning as root and enables the correct  execution  of  setuid
190                   and/or  setgid binaries.  Unless this option is used setuid
191                   and setgid programs are executed without  effective  privi‐
192                   leges.
193
194   Tracing
195       -b syscall  If   specified  syscall  is  reached,  detach  from  traced
196                   process.  Currently, only execve(2) syscall  is  supported.
197                   This  option  is useful if you want to trace multi-threaded
198                   process and therefore require -f, but don't want  to  trace
199                   its (potentially very complex) children.
200
201       -D          Run  tracer process as a detached grandchild, not as parent
202                   of the tracee.  This reduces the visible effect  of  strace
203                   by  keeping  the  tracee  a  direct  child  of  the calling
204                   process.
205
206       -f          Trace child processes as  they  are  created  by  currently
207                   traced  processes  as a result of the fork(2), vfork(2) and
208                   clone(2) system calls.  Note that -p PID -f will attach all
209                   threads  of  process  PID if it is multi-threaded, not only
210                   thread with thread_id = PID.
211
212       -ff         If the -o filename option  is  in  effect,  each  processes
213                   trace  is  written to filename.pid where pid is the numeric
214                   process id of each process.  This is incompatible with  -c,
215                   since no per-process counts are kept.
216
217                   One  might  want  to  consider using strace-log-merge(1) to
218                   obtain a combined strace log view.
219
220       -I interruptible
221                   When strace can be interrupted by signals (such as pressing
222                   CTRL-C).
223
224                   1   no signals are blocked;
225                   2   fatal   signals  are  blocked  while  decoding  syscall
226                       (default);
227                   3   fatal signals are always blocked (default  if  -o  FILE
228                       PROG);
229                   4   fatal  signals  and SIGTSTP (CTRL-Z) are always blocked
230                       (useful to make strace -o FILE PROG not stop on CTRL-Z,
231                       default if -D).
232
233   Filtering
234       -e trace=set
235                   Trace  only  the  specified  set  of  system calls.  The -c
236                   option is useful for determining which system  calls  might
237                   be       useful      to      trace.       For      example,
238                   trace=open,close,read,write means to only trace those  four
239                   system  calls.  Be careful when making inferences about the
240                   user/kernel boundary if only a subset of system  calls  are
241                   being monitored.  The default is trace=all.
242
243       -e trace=/regex
244                   Trace  only  those  system calls that match the regex.  You
245                   can use  POSIX  Extended  Regular  Expression  syntax  (see
246                   regex(7)).
247
248       -e trace=%file
249       -e trace=file
250                   Trace  all  system calls which take a file name as an argu‐
251                   ment.  You  can  think  of  this  as  an  abbreviation  for
252                   -e trace=open,stat,chmod,unlink,...   which  is  useful  to
253                   seeing what files the process is referencing.  Furthermore,
254                   using  the abbreviation will ensure that you don't acciden‐
255                   tally forget to include a call like lstat(2) in  the  list.
256                   Betchya  woulda forgot that one.  The syntax without a pre‐
257                   ceding percent sign ("-e trace=file") is deprecated.
258
259       -e trace=%process
260       -e trace=process
261                   Trace all system calls which  involve  process  management.
262                   This  is useful for watching the fork, wait, and exec steps
263                   of a process.  The syntax without a preceding percent  sign
264                   ("-e trace=process") is deprecated.
265
266       -e trace=%net
267       -e trace=%network
268       -e trace=network
269                   Trace  all  the  network  related system calls.  The syntax
270                   without a preceding percent sign  ("-e  trace=network")  is
271                   deprecated.
272
273       -e trace=%signal
274       -e trace=signal
275                   Trace  all signal related system calls.  The syntax without
276                   a preceding percent sign ("-e trace=signal") is deprecated.
277
278       -e trace=%ipc
279       -e trace=ipc
280                   Trace all IPC related system calls.  The syntax  without  a
281                   preceding percent sign ("-e trace=ipc") is deprecated.
282
283       -e trace=%desc
284       -e trace=desc
285                   Trace all file descriptor related system calls.  The syntax
286                   without a preceding percent sign ("-e trace=desc") is  dep‐
287                   recated.
288
289       -e trace=%memory
290       -e trace=memory
291                   Trace  all memory mapping related system calls.  The syntax
292                   without a preceding percent  sign  ("-e  trace=memory")  is
293                   deprecated.
294
295       -e trace=%stat
296                   Trace stat syscall variants.
297
298       -e trace=%lstat
299                   Trace lstat syscall variants.
300
301       -e trace=%fstat
302                   Trace fstat and fstatat syscall variants.
303
304       -e trace=%%stat
305                   Trace  syscalls  used  for  requesting  file  status (stat,
306                   lstat, fstat, fstatat, statx, and their variants).
307
308       -e trace=%statfs
309                   Trace   statfs,   statfs64,   statvfs,   osf_statfs,    and
310                   osf_statfs64 system calls.  The same effect can be achieved
311                   with -e trace=/^(.*_)?statv?fs regular expression.
312
313       -e trace=%fstatfs
314                   Trace  fstatfs,  fstatfs64,  fstatvfs,   osf_fstatfs,   and
315                   osf_fstatfs64   system  calls.   The  same  effect  can  be
316                   achieved with -e trace=/fstatv?fs regular expression.
317
318       -e trace=%%statfs
319                   Trace syscalls related to file system  statistics  (statfs-
320                   like,  fstatfs-like,  and  ustat).   The same effect can be
321                   achieved   with   -e trace=/statv?fs|fsstat|ustat   regular
322                   expression.
323
324       -e trace=%pure
325                   Trace  syscalls  that always succeed and have no arguments.
326                   Currently, this  list  includes  arc_gettls(2),  getdtable‐
327                   size(2),      getegid(2),     getegid32(2),     geteuid(2),
328                   geteuid32(2), getgid(2), getgid32(2), getpagesize(2), getp‐
329                   grp(2),   getpid(2),   getppid(2),  get_thread_area(2)  (on
330                   architectures  other  than  x86),  gettid(2),   get_tls(2),
331                   getuid(2), getuid32(2), getxgid(2), getxpid(2), getxuid(2),
332                   kern_features(2), and metag_get_tls(2) syscalls.
333
334       -e signal=set
335                   Trace only the specified subset of signals.  The default is
336                   signal=all.   For  example,  signal=!SIGIO  (or signal=!io)
337                   causes SIGIO signals not to be traced.
338
339       -e status=set
340                   Print only system calls with the specified  return  status.
341                   The  default  is  status=all.  When using the status quali‐
342                   fier, because strace  waits  for  system  calls  to  return
343                   before  deciding whether they should be printed or not, the
344                   traditional order of events may not be  preserved  anymore.
345                   If  two  system  calls  are executed by concurrent threads,
346                   strace will first print both the  entry  and  exit  of  the
347                   first  system  call to exit, regardless of their respective
348                   entry time.  The entry and exit of the second  system  call
349                   to  exit  will  be  printed afterwards.  Here is an example
350                   when select(2) is called,  but  a  different  thread  calls
351                   clock_gettime(2) before select(2) finishes:
352
353                       [pid 28779] 1130322148.939977 clock_gettime(CLOCK_REALTIME, {1130322148, 939977000}) = 0
354                       [pid 28772] 1130322148.438139 select(4, [3], NULL, NULL, NULL) = 1 (in [3])
355
356                   set can include the following elements:
357
358                   successful   Trace  system  calls  that returned without an
359                                error code.  The -z option has the  effect  of
360                                status=successful.
361                   failed       Trace system calls that returned with an error
362                                code.  The -Z option has the  effect  of  sta‐
363                                tus=failed.
364                   unfinished   Trace  system calls that did not return.  This
365                                might happen, for example, due  to  an  execve
366                                call in a neighbour thread.
367                   unavailable  Trace  system  calls  that returned but strace
368                                failed to fetch the error status.
369                   detached     Trace system calls for which  strace  detached
370                                before the return.
371
372       -P path     Trace  only  system  calls  accessing  path.   Multiple  -P
373                   options can be used to specify several paths.
374
375       -z          Print only syscalls that returned without an error code.
376
377       -Z          Print only syscalls that returned with an error code.
378
379   Output format
380       -a column   Align return values in a specific  column  (default  column
381                   40).
382
383       -e abbrev=set
384                   Abbreviate  the  output  from printing each member of large
385                   structures.  The default is abbrev=all.  The -v option  has
386                   the effect of abbrev=none.
387
388       -e verbose=set
389                   Dereference  structures  for  the  specified  set of system
390                   calls.  The default is verbose=all.
391
392       -e raw=set  Print raw, undecoded arguments for  the  specified  set  of
393                   system  calls.   This  option has the effect of causing all
394                   arguments to be printed in  hexadecimal.   This  is  mostly
395                   useful  if you don't trust the decoding or you need to know
396                   the actual numeric value of an argument.  See also  -X  raw
397                   option.
398
399       -e read=set Perform  a  full hexadecimal and ASCII dump of all the data
400                   read from file descriptors listed  in  the  specified  set.
401                   For  example, to see all input activity on file descriptors
402                   3 and 5 use -e read=3,5.  Note  that  this  is  independent
403                   from the normal tracing of the read(2) system call which is
404                   controlled by the option -e trace=read.
405
406       -e write=set
407                   Perform a full hexadecimal and ASCII dump of all  the  data
408                   written  to  file  descriptors listed in the specified set.
409                   For example, to see all output activity on file descriptors
410                   3  and  5  use -e write=3,5.  Note that this is independent
411                   from the normal tracing of the write(2) system  call  which
412                   is controlled by the option -e trace=write.
413
414       -e kvm=vcpu Print  the  exit reason of kvm vcpu.  Requires Linux kernel
415                   version 4.16.0 or higher.
416
417
418       -i          Print the instruction pointer at the  time  of  the  system
419                   call.
420
421       -k          Print  the  execution  stack  trace of the traced processes
422                   after each system call.
423
424       -o filename Write the trace output to the file filename rather than  to
425                   stderr.   filename.pid  form  is used if -ff option is sup‐
426                   plied.  If the argument begins with '|' or '!', the rest of
427                   the  argument  is  treated  as  a command and all output is
428                   piped to it.  This is convenient for piping  the  debugging
429                   output  to  a program without affecting the redirections of
430                   executed programs.  The latter is not compatible  with  -ff
431                   option currently.
432
433       -A          Open the file provided in the -o option in append mode.
434
435       -q          Suppress  messages  about  attaching,  detaching etc.  This
436                   happens automatically when output is redirected to  a  file
437                   and the command is run directly instead of attaching.
438
439       -qq         If  given  twice, suppress messages about process exit sta‐
440                   tus.
441
442       -r          Print a relative timestamp upon entry to each system  call.
443                   This  records  the time difference between the beginning of
444                   successive system calls.  Note that since  -r  option  uses
445                   the  monotonic clock time for measuring time difference and
446                   not the wall clock time, its measurements can  differ  from
447                   the difference in time reported by the -t option.
448
449       -s strsize  Specify  the  maximum  string size to print (the default is
450                   32).  Note that filenames are not  considered  strings  and
451                   are always printed in full.
452
453       -t          Prefix each line of the trace with the wall clock time.
454
455       -tt         If given twice, the time printed will include the microsec‐
456                   onds.
457
458       -ttt        If  given  thrice,  the  time  printed  will  include   the
459                   microseconds and the leading portion will be printed as the
460                   number of seconds since the epoch.
461
462       -T          Show the time spent in system calls.  This records the time
463                   difference between the beginning and the end of each system
464                   call.
465
466       -v          Print unabbreviated versions of environment, stat, termios,
467                   etc.  calls.  These structures are very common in calls and
468                   so the default behavior displays  a  reasonable  subset  of
469                   structure  members.  Use this option to get all of the gory
470                   details.
471
472       -x          Print all non-ASCII strings in hexadecimal string format.
473
474       -xx         Print all strings in hexadecimal string format.
475
476       -X format   Set the format for printing of named constants  and  flags.
477                   Supported format values are:
478
479                   raw       Raw number output, without decoding.
480                   abbrev    Output a named constant or a set of flags instead
481                             of the raw number if they are found.  This is the
482                             default strace behaviour.
483                   verbose   Output  both the raw value and the decoded string
484                             (as a comment).
485
486       -y          Print paths associated with file descriptor arguments.
487
488       -yy         Print protocol specific information associated with  socket
489                   file descriptors, and block/character device number associ‐
490                   ated with device file descriptors.
491
492   Statistics
493       -c          Count time, calls, and errors  for  each  system  call  and
494                   report  a  summary on program exit, suppressing the regular
495                   output.  This attempts to show system time (CPU time  spent
496                   running  in the kernel) independent of wall clock time.  If
497                   -c is used with -f, only aggregate totals  for  all  traced
498                   processes are kept.
499
500       -C          Like  -c  but also print regular output while processes are
501                   running.
502
503       -O overhead Set the overhead  for  tracing  system  calls  to  overhead
504                   microseconds.   This  is  useful for overriding the default
505                   heuristic for guessing how much time is spent in mere  mea‐
506                   suring  when  timing system calls using the -c option.  The
507                   accuracy of the heuristic can be gauged by timing  a  given
508                   program  run  without tracing (using time(1)) and comparing
509                   the accumulated system call  time  to  the  total  produced
510                   using -c.
511
512       -S sortby   Sort  the  output of the histogram printed by the -c option
513                   by the specified criterion.   Legal  values  are  time  (or
514                   time_total  or  total_time),  calls  (or count), errors (or
515                   error), name (or syscall or syscall_name), and nothing  (or
516                   none); default is time.
517
518       -w          Summarise the time difference between the beginning and end
519                   of each system call.  The default is to summarise the  sys‐
520                   tem time.
521
522   Tampering
523       -e inject=set[:error=errno|:retval=value][:sig‐
524       nal=sig][:syscall=syscall][:delay_enter=usecs][:delay_exit=usecs][:when=expr]
525              Perform syscall tampering for the specified set of syscalls.
526
527              At   least   one  of  error,  retval,  signal,  delay_enter,  or
528              delay_exit options has to be specified.  error  and  retval  are
529              mutually exclusive.
530
531              If  :error=errno option is specified, a fault is injected into a
532              syscall invocation: the syscall number is replaced by  -1  which
533              corresponds to an invalid syscall (unless a syscall is specified
534              with :syscall= option), and the error code is specified using  a
535              symbolic  errno  value  like  ENOSYS  or  a numeric value within
536              1..4095 range.
537
538              If :retval=value option is specified, success injection is  per‐
539              formed:  the  syscall number is replaced by -1, but a bogus suc‐
540              cess value is returned to the callee.
541
542              If :signal=sig option is specified with either a symbolic  value
543              like  SIGSEGV  or a numeric value within 1..SIGRTMAX range, that
544              signal is delivered on entering every syscall specified  by  the
545              set.
546
547              If  :delay_enter=usecs  or  :delay_exit=usecs options are speci‐
548              fied, delay injection is performed: the tracee is delayed by  at
549              least usecs microseconds on entering or exiting the syscall.
550
551              If  :signal=sig  option is specified without :error=errno, :ret‐
552              val=value or :delay_{enter,exit}=usecs options, then only a sig‐
553              nal sig is delivered without a syscall fault or delay injection.
554              Conversely,  :error=errno  or   :retval=value   option   without
555              :delay_enter=usecs,  :delay_exit=usecs  or  :signal=sig  options
556              injects a fault without  delivering  a  signal  or  injecting  a
557              delay, etc.
558
559              If  both  :error=errno  or :retval=value and :signal=sig options
560              are specified, then both a fault or success is  injected  and  a
561              signal is delivered.
562
563              if  :syscall=syscall  option  is  specified,  the  corresponding
564              syscall with no side effects is injected instead  of  -1.   Cur‐
565              rently,  only  "pure"  (see -e trace=%pure description) syscalls
566              can be specified there.
567
568              Unless a :when=expr subexpression is specified, an injection  is
569              being made into every invocation of each syscall from the set.
570
571              The format of the subexpression is one of the following:
572
573              first       For every syscall from the set, perform an injection
574                          for the syscall invocation number first only.
575              first+      For every syscall from the set,  perform  injections
576                          for the syscall invocation number first and all sub‐
577                          sequent invocations.
578              first+step  For every syscall from the set,  perform  injections
579                          for  syscall  invocations  number first, first+step,
580                          first+step+step, and so on.
581
582              For example, to fail each third and  subsequent  chdir  syscalls
583              with ENOENT, use -e inject=chdir:error=ENOENT:when=3+.
584
585              The valid range for numbers first and step is 1..65535.
586
587              An  injection  expression can contain only one error= or retval=
588              specification, and only one signal= specification.  If an injec‐
589              tion expression contains multiple when= specifications, the last
590              one takes precedence.
591
592              Accounting of syscalls that are subject to injection is done per
593              syscall and per tracee.
594
595              Specification  of  syscall  injection can be combined with other
596              syscall filtering  options,  for  example,  -P  /dev/urandom  -e
597              inject=file:error=ENOENT.
598
599
600       -e fault=set[:error=errno][:when=expr]
601              Perform  syscall  fault  injection  for  the  specified  set  of
602              syscalls.
603
604              This is equivalent to more generic  -e inject=  expression  with
605              default value of errno option set to ENOSYS.
606
607   Miscellaneous
608       -d          Show some debugging output of strace itself on the standard
609                   error.
610
611       --seccomp-bpf
612                   Enable  (experimental)  usage  of   seccomp-bpf   to   have
613                   ptrace(2)-stops  only  when  system  calls  that  are being
614                   traced occur in  the  traced  processes.   Implies  the  -f
615                   option.  An attempt to rely on seccomp-bpf to filter system
616                   calls may fail for various reasons, e.g. there are too many
617                   system  calls  to filter, the seccomp API is not available,
618                   or strace itself is being traced.   --seccomp-bpf  is  also
619                   ineffective  on processes attached using -p.  In cases when
620                   seccomp-bpf filter setup failed, strace proceeds  as  usual
621                   and stops traced processes on every system call.
622
623       -F          This  option  is  deprecated.   It is retained for backward
624                   compatibility only and may be removed in  future  releases.
625                   Usage  of  multiple instances of -F option is still equiva‐
626                   lent to a single -f, and it is ignored at all if used along
627                   with one or more instances of -f option.
628
629       -h,
630       --help      Print the help summary.
631
632       -V,
633       --version   Print the version number of strace.
634

DIAGNOSTICS

636       When command exits, strace exits with the same exit status.  If command
637       is terminated by a signal, strace terminates itself with the same  sig‐
638       nal, so that strace can be used as a wrapper process transparent to the
639       invoking parent process.  Note that parent-child  relationship  (signal
640       stop  notifications,  getppid(2) value, etc) between traced process and
641       its parent are not preserved unless -D is used.
642
643       When using -p without a command, the exit  status  of  strace  is  zero
644       unless  no processes has been attached or there was an unexpected error
645       in doing the tracing.
646

SETUID INSTALLATION

648       If strace is installed setuid to root then the invoking  user  will  be
649       able  to  attach to and trace processes owned by any user.  In addition
650       setuid and setgid programs will be executed and traced with the correct
651       effective  privileges.   Since only users trusted with full root privi‐
652       leges should be allowed to do these things,  it  only  makes  sense  to
653       install  strace as setuid to root when the users who can execute it are
654       restricted to those users who have this trust.  For example,  it  makes
655       sense  to  install  a  special version of strace with mode 'rwsr-xr--',
656       user root and group trace, where members of the trace group are trusted
657       users.   If you do use this feature, please remember to install a regu‐
658       lar non-setuid version of strace for ordinary users to use.
659

MULTIPLE PERSONALITY SUPPORT

661       On some architectures, strace supports decoding of  syscalls  for  pro‐
662       cesses that use different ABI rather than the one strace uses.  Specif‐
663       ically, in addition to decoding native ABI, strace can decode the  fol‐
664       lowing ABIs on the following architectures:
665
666       ┌───────────────────┬─────────────────────────┐
667Architecture       ABIs supported          
668       ├───────────────────┼─────────────────────────┤
669       │x86_64             │ i386, x32 [1]; i386 [2] │
670       ├───────────────────┼─────────────────────────┤
671       │AArch64            │ ARM 32-bit EABI         │
672       ├───────────────────┼─────────────────────────┤
673       │PowerPC 64-bit [3] │ PowerPC 32-bit          │
674       ├───────────────────┼─────────────────────────┤
675       │s390x              │ s390                    │
676       ├───────────────────┼─────────────────────────┤
677       │SPARC 64-bit       │ SPARC 32-bit            │
678       ├───────────────────┼─────────────────────────┤
679       │TILE 64-bit        │ TILE 32-bit             │
680       └───────────────────┴─────────────────────────┘
681       [1]  When strace is built as an x86_64 application
682       [2]  When strace is built as an x32 application
683       [3]  Big endian only
684
685       This  support  is  optional and relies on ability to generate and parse
686       structure definitions during the build time.  Please refer to the  out‐
687       put  of  the  strace  -V command in order to figure out what support is
688       available in your strace build ("non-native" refers to an ABI that dif‐
689       fers from the ABI strace has):
690
691       m32-mpers      strace  can  trace and properly decode non-native 32-bit
692                      binaries.
693       no-m32-mpers   strace can trace, but cannot properly decode  non-native
694                      32-bit binaries.
695       mx32-mpers     strace   can   trace   and  properly  decode  non-native
696                      32-on-64-bit binaries.
697       no-mx32-mpers  strace can trace, but cannot properly decode  non-native
698                      32-on-64-bit binaries.
699
700       If  the output contains neither m32-mpers nor no-m32-mpers, then decod‐
701       ing of non-native 32-bit binaries is not  implemented  at  all  or  not
702       applicable.
703
704       Likewise,  if the output contains neither mx32-mpers nor no-mx32-mpers,
705       then decoding of non-native 32-on-64-bit binaries is not implemented at
706       all or not applicable.
707

NOTES

709       It  is  a  pity  that  so  much  tracing clutter is produced by systems
710       employing shared libraries.
711
712       It is instructive to think about system  call  inputs  and  outputs  as
713       data-flow across the user/kernel boundary.  Because user-space and ker‐
714       nel-space are separate and address-protected, it is sometimes  possible
715       to  make  deductive  inferences about process behavior using inputs and
716       outputs as propositions.
717
718       In some cases, a system call will differ from the  documented  behavior
719       or  have  a  different name.  For example, the faccessat(2) system call
720       does not have flags argument, and  the  setrlimit(2)  library  function
721       uses  prlimit64(2) system call on modern (2.6.38+) kernels.  These dis‐
722       crepancies are normal but idiosyncratic characteristics of  the  system
723       call interface and are accounted for by C library wrapper functions.
724
725       Some  system  calls have different names in different architectures and
726       personalities.  In these cases, system call filtering and printing uses
727       the names that match corresponding __NR_* kernel macros of the tracee's
728       architecture and personality.  There are two exceptions from this  gen‐
729       eral  rule:  arm_fadvise64_64(2) ARM syscall and xtensa_fadvise64_64(2)
730       Xtensa syscall are filtered and printed as fadvise64_64(2).
731
732       On x32, syscalls that are intended to be used by 64-bit  processes  and
733       not  x32  ones  (for  example,  readv(2), that has syscall number 19 on
734       x86_64, with its x32 counterpart has syscall number  515),  but  called
735       with __X32_SYSCALL_BIT flag being set, are designated with #64 suffix.
736
737       On  some platforms a process that is attached to with the -p option may
738       observe a spurious EINTR return from the current system  call  that  is
739       not  restartable.   (Ideally,  all  system calls should be restarted on
740       strace attach, making the attach invisible to the traced process, but a
741       few  system calls aren't.  Arguably, every instance of such behavior is
742       a kernel bug.)  This may have an unpredictable effect on the process if
743       the process takes no action to restart the system call.
744
745       As strace executes the specified command directly and does not employ a
746       shell for that, scripts without shebang that usually run just fine when
747       invoked  by  shell fail to execute with ENOEXEC error.  It is advisable
748       to manually supply a shell as a command with the script  as  its  argu‐
749       ment.
750

BUGS

752       Programs  that  use the setuid bit do not have effective user ID privi‐
753       leges while being traced.
754
755       A traced process runs slowly.
756
757       Traced processes which are descended from command may be  left  running
758       after an interrupt signal (CTRL-C).
759

HISTORY

761       The  original  strace  was written by Paul Kranenburg for SunOS and was
762       inspired by its trace utility.  The SunOS version of strace was  ported
763       to  Linux  and  enhanced  by Branko Lankester, who also wrote the Linux
764       kernel support.  Even though Paul released strace 2.5 in 1992, Branko's
765       work  was  based on Paul's strace 1.5 release from 1991.  In 1993, Rick
766       Sladkey merged strace 2.5 for SunOS and the second  release  of  strace
767       for  Linux,  added many of the features of truss(1) from SVR4, and pro‐
768       duced an strace that worked on both platforms.   In  1994  Rick  ported
769       strace  to  SVR4 and Solaris and wrote the automatic configuration sup‐
770       port.  In 1995 he ported strace to Irix and tired of writing about him‐
771       self in the third person.
772
773       Beginning with 1996, strace was maintained by Wichert Akkerman.  During
774       his tenure, strace development migrated to CVS; ports  to  FreeBSD  and
775       many  architectures on Linux (including ARM, IA-64, MIPS, PA-RISC, Pow‐
776       erPC, s390, SPARC) were introduced.  In  2002,  the  burden  of  strace
777       maintainership  was  transferred to Roland McGrath.  Since then, strace
778       gained support for  several  new  Linux  architectures  (AMD64,  s390x,
779       SuperH),  bi-architecture support for some of them, and received numer‐
780       ous additions and improvements in syscalls decoders  on  Linux;  strace
781       development  migrated to git during that period.  Since 2009, strace is
782       actively  maintained  by  Dmitry  Levin.   strace  gained  support  for
783       AArch64,  ARC,  AVR32,  Blackfin, Meta, Nios II, OpenSISC 1000, RISC-V,
784       Tile/TileGx, Xtensa architectures since that time.   In  2012,  unmain‐
785       tained  and  apparently  broken support for non-Linux operating systems
786       was removed.  Also, in 2012 strace gained support for path tracing  and
787       file  descriptor  path  decoding.   In  2014,  support for stack traces
788       printing was added.  In 2016, syscall fault injection was implemented.
789
790       For the additional information, please  refer  to  the  NEWS  file  and
791       strace repository commit log.
792

REPORTING BUGS

794       Problems  with  strace should be reported to the strace mailing list at
795       <strace-devel@lists.strace.io>.
796

SEE ALSO

798       strace-log-merge(1), ltrace(1), perf-trace(1),  trace-cmd(1),  time(1),
799       ptrace(2), proc(5)
800
801       strace Home Page ⟨https://strace.io/
802

AUTHORS

804       The  complete  list  of strace contributors can be found in the CREDITS
805       file.
806
807
808
809strace 5.3                        2019-09-25                         STRACE(1)
Impressum