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              [-O overhead] [-S sortby] [-U columns] [-a column] [-o file]
11              [-s strsize] [-X format] [-P path]... [-p pid]...
12              [--seccomp-bpf] [--secontext[=format]] { -p pid | [-DDD]
13              [-E var[=val]]... [-u username] command [args] }
14
15       strace -c [-dfwzZ] [-I n] [-b execve] [-e expr]... [-O overhead]
16              [-S sortby] [-U columns] [-P path]... [-p pid]...
17              [--seccomp-bpf] { -p pid | [-DDD] [-E var[=val]]...
18              [-u username] command [args] }
19

DESCRIPTION

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

OPTIONS

145   General
146       -e expr     A  qualifying  expression  which  modifies  which events to
147                   trace or how to trace them.  The format of  the  expression
148                   is:
149
150                             [qualifier=][!]value[,value]...
151
152                   where qualifier is one of trace (or t), abbrev (or a), ver‐
153                   bose (or v), raw (or x), signal (or signals or s), read (or
154                   reads or r), write (or writes or w), fault, inject, status,
155                   quiet (or silent or silence or  q),  secontext,  decode-fds
156                   (or  decode-fd),  decode-pids  (or decode-pid), or kvm, and
157                   value is a qualifier-dependent symbol or number.   The  de‐
158                   fault  qualifier  is  trace.   Using  an  exclamation  mark
159                   negates the set of values.  For example, -e open means lit‐
160                   erally  -e trace=open  which  in  turn means trace only the
161                   open system call.  By  contrast,  -e trace=!open  means  to
162                   trace every system call except open.  In addition, the spe‐
163                   cial values all and none have the obvious meanings.
164
165                   Note that some shells use the exclamation point for history
166                   expansion  even  inside  quoted arguments.  If so, you must
167                   escape the exclamation point with a backslash.
168
169   Startup
170       -E var=val
171       --env=var=val
172                   Run command with var=val in its list of  environment  vari‐
173                   ables.
174
175       -E var
176       --env=var   Remove var from the inherited list of environment variables
177                   before passing it on to the command.
178
179       -p pid
180       --attach=pid
181                   Attach to the process with the process  ID  pid  and  begin
182                   tracing.  The trace may be terminated at any time by a key‐
183                   board interrupt signal (CTRL-C).  strace  will  respond  by
184                   detaching  itself  from  the  traced process(es) leaving it
185                   (them) to continue running.  Multiple  -p  options  can  be
186                   used  to  attach  to  many processes in addition to command
187                   (which is optional if at least one  -p  option  is  given).
188                   Multiple  process  IDs,  separated  by  either comma (“,”),
189                   space (“ ”), tab, or newline character, can be provided  as
190                   an  argument  to  a  single  -p option, so, for example, -p
191                   "$(pidof PROG)" and -p "$(pgrep PROG)"  syntaxes  are  sup‐
192                   ported.
193
194       -u username
195       --user=username
196                   Run  command  with the user ID, group ID, and supplementary
197                   groups of username.  This option is only useful  when  run‐
198                   ning  as  root  and enables the correct execution of setuid
199                   and/or setgid binaries.  Unless this option is used  setuid
200                   and  setgid  programs are executed without effective privi‐
201                   leges.
202
203   Tracing
204       -b syscall
205       --detach-on=syscall
206                   If  specified  syscall  is  reached,  detach  from   traced
207                   process.   Currently,  only execve(2) syscall is supported.
208                   This option is useful if you want to  trace  multi-threaded
209                   process  and  therefore require -f, but don't want to trace
210                   its (potentially very complex) children.
211
212       -D
213       --daemonize
214       --daemonize=grandchild
215                   Run tracer process as a grandchild, not as  the  parent  of
216                   the  tracee.   This reduces the visible effect of strace by
217                   keeping the tracee a direct child of the calling process.
218
219       -DD
220       --daemonize=pgroup
221       --daemonize=pgrp
222                   Run tracer process as tracee's  grandchild  in  a  separate
223                   process group.  In addition to reduction of the visible ef‐
224                   fect of strace, it  also  avoids  killing  of  strace  with
225                   kill(2) issued to the whole process group.
226
227       -DDD
228       --daemonize=session
229                   Run  tracer  process  as  tracee's grandchild in a separate
230                   session ("true daemonisation").  In addition  to  reduction
231                   of  the visible effect of strace, it also avoids killing of
232                   strace upon session termination.
233
234       -f
235       --follow-forks
236                   Trace child processes as  they  are  created  by  currently
237                   traced  processes  as a result of the fork(2), vfork(2) and
238                   clone(2) system calls.  Note that -p PID -f will attach all
239                   threads  of  process  PID if it is multi-threaded, not only
240                   thread with thread_id = PID.
241
242       --output-separately
243                   If the --output=filename option is  in  effect,  each  pro‐
244                   cesses  trace  is  written to filename.pid where pid is the
245                   numeric process id of each process.
246
247       -ff
248       --follow-forks --output-separately
249                   Combine the effects of  --follow-forks  and  --output-sepa‐
250                   rately  options.   This  is  incompatible with -c, since no
251                   per-process counts are kept.
252
253                   One might want to consider using strace-log-merge(1) to ob‐
254                   tain a combined strace log view.
255
256       -I interruptible
257       --interruptible=interruptible
258                   When strace can be interrupted by signals (such as pressing
259                   CTRL-C).
260
261                   1, anywhere    no signals are blocked;
262                   2, waiting     fatal signals  are  blocked  while  decoding
263                                  syscall (default);
264                   3, never       fatal signals are always blocked (default if
265                                  -o FILE PROG);
266                   4, never_tstp  fatal signals and SIGTSTP (CTRL-Z)  are  al‐
267                                  ways  blocked (useful to make strace -o FILE
268                                  PROG not stop on CTRL-Z, default if -D).
269
270   Filtering
271       -e trace=syscall_set
272       --trace=syscall_set
273                   Trace only the specified set of system calls.   syscall_set
274                   is defined as [!]value[,value], and value can be one of the
275                   following:
276
277                   syscall      Trace specific syscall, specified by its  name
278                                (but see NOTES).
279
280                   ?value       Question mark before the syscall qualification
281                                allows  suppression  of  error  in   case   no
282                                syscalls matched the qualification provided.
283
284                   /regex       Trace  only  those system calls that match the
285                                regex.  You can use POSIX Extended Regular Ex‐
286                                pression syntax (see regex(7)).
287
288                   syscall@64   Trace syscall only for the 64-bit personality.
289
290                   syscall@32   Trace syscall only for the 32-bit personality.
291
292                   syscall@x32  Trace  syscall  only for the 32-on-64-bit per‐
293                                sonality.
294
295                   %file
296                   file         Trace all system calls which take a file  name
297                                as  an  argument.  You can think of this as an
298                                abbreviation for  -e trace=open,stat,chmod,un‐
299                                link,...  which is useful to seeing what files
300                                the process is referencing.  Furthermore,  us‐
301                                ing  the  abbreviation  will  ensure  that you
302                                don't accidentally forget to  include  a  call
303                                like  lstat(2)  in  the  list.  Betchya woulda
304                                forgot that one.  The syntax without a preced‐
305                                ing  percent  sign ("-e trace=file") is depre‐
306                                cated.
307
308                   %process
309                   process      Trace system  calls  associated  with  process
310                                lifecycle  (creation, exec, termination).  The
311                                syntax without a preceding percent  sign  ("-e
312                                trace=process") is deprecated.
313
314                   %net
315                   %network
316                   network      Trace  all  the  network related system calls.
317                                The syntax without a  preceding  percent  sign
318                                ("-e trace=network") is deprecated.
319
320                   %signal
321                   signal       Trace  all  signal  related system calls.  The
322                                syntax without a preceding percent  sign  ("-e
323                                trace=signal") is deprecated.
324
325                   %ipc
326                   ipc          Trace  all IPC related system calls.  The syn‐
327                                tax without  a  preceding  percent  sign  ("-e
328                                trace=ipc") is deprecated.
329
330                   %desc
331                   desc         Trace   all  file  descriptor  related  system
332                                calls.  The syntax without a preceding percent
333                                sign ("-e trace=desc") is deprecated.
334
335                   %memory
336                   memory       Trace all memory mapping related system calls.
337                                The syntax without a  preceding  percent  sign
338                                ("-e trace=memory") is deprecated.
339
340                   %creds       Trace  system  calls  that read or modify user
341                                and group identifiers or capability sets.
342
343                   %stat        Trace stat syscall variants.
344
345                   %lstat       Trace lstat syscall variants.
346
347                   %fstat       Trace fstat, fstatat, and statx syscall  vari‐
348                                ants.
349
350                   %%stat       Trace syscalls used for requesting file status
351                                (stat, lstat, fstat, fstatat, statx, and their
352                                variants).
353
354                   %statfs      Trace  statfs,  statfs64, statvfs, osf_statfs,
355                                and osf_statfs64 system calls.  The  same  ef‐
356                                fect       can      be      achieved      with
357                                -e trace=/^(.*_)?statv?fs regular expression.
358
359                   %fstatfs     Trace fstatfs,  fstatfs64,  fstatvfs,  osf_fs‐
360                                tatfs,  and  osf_fstatfs64  system calls.  The
361                                same effect can be achieved with -e trace=/fs‐
362                                tatv?fs regular expression.
363
364                   %%statfs     Trace  syscalls related to file system statis‐
365                                tics (statfs-like, fstatfs-like,  and  ustat).
366                                The   same   effect   can   be  achieved  with
367                                -e trace=/statv?fs|fsstat|ustat  regular   ex‐
368                                pression.
369
370                   %clock       Trace  system calls that read or modify system
371                                clocks.
372
373                   %pure        Trace syscalls that always succeed and have no
374                                arguments.    Currently,  this  list  includes
375                                arc_gettls(2),  getdtablesize(2),  getegid(2),
376                                getegid32(2),  geteuid(2),  geteuid32(2), get‐
377                                gid(2),  getgid32(2),  getpagesize(2),   getp‐
378                                grp(2),         getpid(2),         getppid(2),
379                                get_thread_area(2)  (on  architectures   other
380                                than  x86),  gettid(2), get_tls(2), getuid(2),
381                                getuid32(2),      getxgid(2),      getxpid(2),
382                                getxuid(2),        kern_features(2),       and
383                                metag_get_tls(2) syscalls.
384
385                   The -c option is useful for determining which system  calls
386                   might     be     useful    to    trace.     For    example,
387                   trace=open,close,read,write means to only trace those  four
388                   system  calls.  Be careful when making inferences about the
389                   user/kernel boundary if only a subset of system  calls  are
390                   being monitored.  The default is trace=all.
391
392       -e signal=set
393       --signal=set
394                   Trace only the specified subset of signals.  The default is
395                   signal=all.  For  example,  signal=!SIGIO  (or  signal=!io)
396                   causes SIGIO signals not to be traced.
397
398       -e status=set
399       --status=set
400                   Print  only  system calls with the specified return status.
401                   The default is status=all.  When using  the  status  quali‐
402                   fier,  because  strace waits for system calls to return be‐
403                   fore deciding whether they should be printed  or  not,  the
404                   traditional  order  of events may not be preserved anymore.
405                   If two system calls are  executed  by  concurrent  threads,
406                   strace  will  first  print  both  the entry and exit of the
407                   first system call to exit, regardless of  their  respective
408                   entry  time.   The entry and exit of the second system call
409                   to exit will be printed afterwards.   Here  is  an  example
410                   when  select(2)  is  called,  but  a different thread calls
411                   clock_gettime(2) before select(2) finishes:
412
413                       [pid 28779] 1130322148.939977 clock_gettime(CLOCK_REALTIME, {1130322148, 939977000}) = 0
414                       [pid 28772] 1130322148.438139 select(4, [3], NULL, NULL, NULL) = 1 (in [3])
415
416                   set can include the following elements:
417
418                   successful   Trace system calls that  returned  without  an
419                                error  code.   The -z option has the effect of
420                                status=successful.
421                   failed       Trace system calls that returned with an error
422                                code.   The  -Z  option has the effect of sta‐
423                                tus=failed.
424                   unfinished   Trace system calls that did not return.   This
425                                might  happen,  for  example, due to an execve
426                                call in a neighbour thread.
427                   unavailable  Trace system calls that  returned  but  strace
428                                failed to fetch the error status.
429                   detached     Trace  system  calls for which strace detached
430                                before the return.
431
432       -P path
433       --trace-path=path
434                   Trace only system calls accessing path.   Multiple  -P  op‐
435                   tions can be used to specify several paths.
436
437       -z
438       --successful-only
439                   Print only syscalls that returned without an error code.
440
441       -Z
442       --failed-only
443                   Print only syscalls that returned with an error code.
444
445   Output format
446       -a column
447       --columns=column
448                   Align  return  values  in a specific column (default column
449                   40).
450
451       -e abbrev=syscall_set
452       --abbrev=syscall_set
453                   Abbreviate the output from printing each  member  of  large
454                   structures.  The syntax of the syscall_set specification is
455                   the same as in the -e trace option.   The  default  is  ab‐
456                   brev=all.  The -v option has the effect of abbrev=none.
457
458       -e verbose=syscall_set
459       --verbose=syscall_set
460                   Dereference  structures  for  the  specified  set of system
461                   calls.  The syntax of the syscall_set specification is  the
462                   same  as  in  the  -e  trace  option.   The default is ver‐
463                   bose=all.
464
465       -e raw=syscall_set
466       --raw=syscall_set
467                   Print raw, undecoded arguments for  the  specified  set  of
468                   system  calls.  The syntax of the syscall_set specification
469                   is the same as in the -e trace option.  This option has the
470                   effect  of causing all arguments to be printed in hexadeci‐
471                   mal.  This is mostly useful if you don't trust the decoding
472                   or  you  need  to know the actual numeric value of an argu‐
473                   ment.  See also -X raw option.
474
475       -e read=set
476       --read=set  Perform a full hexadecimal and ASCII dump of all  the  data
477                   read  from  file  descriptors  listed in the specified set.
478                   For example, to see all input activity on file  descriptors
479                   3  and  5  use  -e read=3,5.  Note that this is independent
480                   from the normal tracing of the read(2) system call which is
481                   controlled by the option -e trace=read.
482
483       -e write=set
484       --write=set Perform  a  full hexadecimal and ASCII dump of all the data
485                   written to file descriptors listed in  the  specified  set.
486                   For example, to see all output activity on file descriptors
487                   3 and 5 use -e write=3,5.  Note that  this  is  independent
488                   from  the  normal tracing of the write(2) system call which
489                   is controlled by the option -e trace=write.
490
491       -e quiet=set
492       --quiet=set
493       --silent=set
494       --silence=set
495                   Suppress various  information  messages.   The  default  is
496                   quiet=none.  set can include the following elements:
497
498                   attach           Suppress  messages about attaching and de‐
499                                    taching ("[ Process NNNN attached  ]",  "[
500                                    Process NNNN detached ]").
501                   exit             Suppress   messages  about  process  exits
502                                    ("+++ exited with SSS +++").
503                   path-resolution  Suppress  messages  about  resolution   of
504                                    paths  provided  via  the  -P option ("Re‐
505                                    quested path "..." resolved into "..."").
506                   personality      Suppress messages about process  personal‐
507                                    ity  changes  ("[ Process PID=NNNN runs in
508                                    PPP mode. ]").
509                   thread-execve
510                   superseded       Suppress messages about process being  su‐
511                                    perseded  by  execve(2)  in another thread
512                                    ("+++ superseded by  execve  in  pid  NNNN
513                                    +++").
514
515       -e decode-fds=set
516       --decode-fds=set
517                   Decode  various  information  associated with file descrip‐
518                   tors.  The default is decode-fds=none.  set can include the
519                   following elements:
520
521                   path    Print   file   paths.   Also  enables  printing  of
522                           tracee's current working  directory  when  AT_FDCWD
523                           constant is used.
524                   socket  Print socket protocol-specific information,
525                   dev     Print character/block device numbers.
526                   pidfd   Print PIDs associated with pidfd file descriptors.
527
528       -e decode-pids=set
529       --decode-pids=set
530                   Decode various information associated with process IDs (and
531                   also thread IDs, process group IDs, and session IDs).   The
532                   default is decode-pids=none.  set can include the following
533                   elements:
534
535                   comm    Print  command  names  associated  with  thread  or
536                           process IDs.
537                   pidns   Print  thread,  process, process group, and session
538                           IDs in strace's PID namespace if the tracee is in a
539                           different PID namespace.
540
541       -e kvm=vcpu
542       --kvm=vcpu  Print  the  exit reason of kvm vcpu.  Requires Linux kernel
543                   version 4.16.0 or higher.
544
545       -i
546       --instruction-pointer
547                   Print the instruction pointer at the  time  of  the  system
548                   call.
549
550       -n
551       --syscall-number
552                   Print the syscall number.
553
554       -k
555       --stack-traces
556                   Print the execution stack trace of the traced processes af‐
557                   ter each system call.
558
559       -o filename
560       --output=filename
561                   Write the trace output to the file filename rather than  to
562                   stderr.   filename.pid  form  is used if -ff option is sup‐
563                   plied.  If the argument begins with '|' or '!', the rest of
564                   the  argument  is  treated  as  a command and all output is
565                   piped to it.  This is convenient for piping  the  debugging
566                   output  to  a program without affecting the redirections of
567                   executed programs.  The latter is not compatible  with  -ff
568                   option currently.
569
570       -A
571       --output-append-mode
572                   Open the file provided in the -o option in append mode.
573
574       -q
575       --quiet
576       --quiet=attach,personality
577                   Suppress messages about attaching, detaching, and personal‐
578                   ity changes.  This happens  automatically  when  output  is
579                   redirected  to  a  file and the command is run directly in‐
580                   stead of attaching.
581
582       -qq
583       --quiet=attach,personality,exit
584                   Suppress   messages   attaching,   detaching,   personality
585                   changes, and about process exit status.
586
587       -qqq
588       --quiet=all Suppress  all suppressible messages (please refer to the -e
589                   quiet option description for the full list of  suppressible
590                   messages).
591
592       -r
593       --relative-timestamps[=precision]
594                   Print  a relative timestamp upon entry to each system call.
595                   This records the time difference between the  beginning  of
596                   successive  system  calls.   precision can be one of s (for
597                   seconds),  ms  (milliseconds),  us  (microseconds),  or  ns
598                   (nanoseconds),  and  allows  setting  the precision of time
599                   value being printed.  Default is us  (microseconds).   Note
600                   that since -r option uses the monotonic clock time for mea‐
601                   suring time difference and not the  wall  clock  time,  its
602                   measurements  can  differ  from  the difference in time re‐
603                   ported by the -t option.
604
605       -s strsize
606       --string-limit=strsize
607                   Specify the maximum string size to print  (the  default  is
608                   32).   Note  that  filenames are not considered strings and
609                   are always printed in full.
610
611       --absolute-timestamps[=[[format:]format],[[precision:]precision]]
612       --timestamps[=[[format:]format],[[precision:]precision]]
613                   Prefix each line of the trace with the wall clock  time  in
614                   the  specified format with the specified precision.  format
615                   can be one of the following:
616
617                   none          No time stamp is printed.   Can  be  used  to
618                                 override the previous setting.
619                   time          Wall clock time (strftime(3) format string is
620                                 %T).
621                   unix          Number of  seconds  since  the  epoch  (strf‐
622                                 time(3) format string is %s).
623
624                   precision can be one of s (for seconds), ms (milliseconds),
625                   us (microseconds), or ns (nanoseconds).  Default  arguments
626                   for the option are format:time,precision:s.
627
628       -t
629       --absolute-timestamps
630                   Prefix each line of the trace with the wall clock time.
631
632       -tt
633       --absolute-timestamps=precision:us
634                   If given twice, the time printed will include the microsec‐
635                   onds.
636
637       -ttt
638       --absolute-timestamps=format:unix,precision:us
639                   If given thrice, the time  printed  will  include  the  mi‐
640                   croseconds  and  the leading portion will be printed as the
641                   number of seconds since the epoch.
642
643       -T
644       --syscall-times[=precision]
645                   Show the time spent in system calls.  This records the time
646                   difference between the beginning and the end of each system
647                   call.  precision can be one of s (for  seconds),  ms  (mil‐
648                   liseconds), us (microseconds), or ns (nanoseconds), and al‐
649                   lows setting the precision of  time  value  being  printed.
650                   Default is us (microseconds).
651
652       -v
653       --no-abbrev Print unabbreviated versions of environment, stat, termios,
654                   etc.  calls.  These structures are very common in calls and
655                   so  the  default  behavior  displays a reasonable subset of
656                   structure members.  Use this option to get all of the  gory
657                   details.
658
659       --strings-in-hex[=option]
660                   Control  usage of escape sequences with hexadecimal numbers
661                   in the printed strings.  Normally (when no --strings-in-hex
662                   or  -x  option  is  supplied), escape sequences are used to
663                   print non-printable  and  non-ASCII  characters  (that  is,
664                   characters  with  a  character code less than 32 or greater
665                   than 127), or to disambiguate the output  (so,  for  quotes
666                   and  other  characters  that encase the printed string, for
667                   example, angle brackets, in case of  file  descriptor  path
668                   output);  for  the  former  use  case, unless it is a white
669                   space character that has a symbolic escape sequence defined
670                   in the C standard (that is, “\t” for a horizontal tab, “\n
671                   for a newline, “\v” for a vertical tab,  “\f”  for  a  form
672                   feed  page  break,  and  “\r”  for  a  carriage return) are
673                   printed using escape sequences with numbers that correspond
674                   to  their  byte  values, with octal number format being the
675                   default.  option can be one of the following:
676
677                   none             Hexadecimal numbers are not  used  in  the
678                                    output  at  all.   When there is a need to
679                                    emit an escape sequence, octal numbers are
680                                    used.
681                   non-ascii-chars  Hexadecimal  numbers  are  used instead of
682                                    octal in the escape sequences.
683                   non-ascii        Strings that contain non-ASCII  characters
684                                    are  printed  using  escape sequences with
685                                    hexadecimal numbers.
686                   all              All strings are printed using  escape  se‐
687                                    quences with hexadecimal numbers.
688
689                   When the option is supplied without an argument, all is as‐
690                   sumed.
691
692       -x
693       --strings-in-hex=non-ascii
694                   Print all non-ASCII strings in hexadecimal string format.
695
696       -xx
697       --strings-in-hex[=all]
698                   Print all strings in hexadecimal string format.
699
700       -X format
701       --const-print-style=format
702                   Set the format for printing of named constants  and  flags.
703                   Supported format values are:
704
705                   raw       Raw number output, without decoding.
706                   abbrev    Output a named constant or a set of flags instead
707                             of the raw number if they are found.  This is the
708                             default strace behaviour.
709                   verbose   Output  both the raw value and the decoded string
710                             (as a comment).
711
712       -y
713       --decode-fds
714       --decode-fds=path
715                   Print paths associated with file descriptor  arguments  and
716                   with the AT_FDCWD constant.
717
718       -yy
719       --decode-fds=all
720                   Print  all  available  information associated with file de‐
721                   scriptors: protocol-specific  information  associated  with
722                   socket  file descriptors, block/character device number as‐
723                   sociated with device file descriptors, and PIDs  associated
724                   with pidfd file descriptors.
725
726       --pidns-translation
727       --decode-pids=pidns
728                   If strace and tracee are in different PID namespaces, print
729                   PIDs in strace's namespace, too.
730
731       -Y
732       --decode-pids=comm
733                   Print command names for PIDs.
734
735       --secontext[=format]
736       -e secontext=format
737                   When SELinux is available and is  not  disabled,  print  in
738                   square  brackets  SELinux contexts of processes, files, and
739                   descriptors.  The format argument is a comma-separated list
740                   of items being one of the following:
741
742                   full              Print  the full context (user, role, type
743                                     level and category).
744                   mismatch          Also print the context  recorded  by  the
745                                     SELinux database in case the current con‐
746                                     text differs.  The latter is printed  af‐
747                                     ter two exclamation marks (!!).
748
749                   The  default  value for --secontext is !full,mismatch which
750                   prints only the type instead of full  context  and  doesn't
751                   check for context mismatches.
752
753   Statistics
754       -c
755       --summary-only
756                   Count  time, calls, and errors for each system call and re‐
757                   port a summary on program  exit,  suppressing  the  regular
758                   output.   This attempts to show system time (CPU time spent
759                   running in the kernel) independent of wall clock time.   If
760                   -c  is  used  with -f, only aggregate totals for all traced
761                   processes are kept.
762
763       -C
764       --summary   Like -c but also print regular output while  processes  are
765                   running.
766
767       -O overhead
768       --summary-syscall-overhead=overhead
769                   Set  the  overhead  for  tracing  system calls to overhead.
770                   This is useful for overriding  the  default  heuristic  for
771                   guessing how much time is spent in mere measuring when tim‐
772                   ing system calls using the -c option.  The accuracy of  the
773                   heuristic can be gauged by timing a given program run with‐
774                   out tracing (using time(1)) and comparing  the  accumulated
775                   system call time to the total produced using -c.
776
777                   The  format  of overhead specification is described in sec‐
778                   tion Time specification format description.
779
780       -S sortby
781       --summary-sort-by=sortby
782                   Sort the output of the histogram printed by the  -c  option
783                   by  the  specified  criterion.   Legal  values are time (or
784                   time-percent or time-total  or  total-time),  min-time  (or
785                   shortest  or  time-min), max-time (or longest or time-max),
786                   avg-time (or time-avg), calls (or count),  errors  (or  er‐
787                   ror),  name  (or  syscall or syscall-name), and nothing (or
788                   none); default is time.
789
790       -U columns
791       --summary-columns=columns
792                   Configure a set (and order) of columns being shown  in  the
793                   call  summary.   The  columns argument is a comma-separated
794                   list with items being one of the following:
795
796                   time-percent (or time)              Percentage  of  cumula‐
797                                                       tive time consumed by a
798                                                       specific system call.
799                   total-time (or time-total)          Total system  (or  wall
800                                                       clock,  if -w option is
801                                                       provided) time consumed
802                                                       by  a  specific  system
803                                                       call.
804                   min-time (or shortest or time-min)  Minimum  observed  call
805                                                       duration.
806                   max-time (or longest or time-max)   Maximum  observed  call
807                                                       duration.
808                   avg-time (or time-avg)              Average call duration.
809                   calls (or count)                    Call count.
810                   errors (or error)                   Error count.
811                   name (or syscall or syscall-name)   Syscall name.
812
813                   The      default      value       is       time-percent,to‐
814                   tal-time,avg-time,calls,errors,name.   If the name field is
815                   not supplied explicitly, it is added as the last column.
816
817       -w
818       --summary-wall-clock
819                   Summarise the time difference between the beginning and end
820                   of  each system call.  The default is to summarise the sys‐
821                   tem time.
822
823   Tampering
824       -e inject=syscall_set[:error=errno|:retval=value][:sig‐
825       nal=sig][:syscall=syscall][:delay_enter=delay][:delay_exit=de‐
826       lay][:poke_en‐
827       ter=@argN=DATAN,@argM=DATAM...][:poke_exit=@argN=DATAN,@argM=DATAM...][:when=expr]
828       --inject=syscall_set[:error=errno|:retval=value][:sig‐
829       nal=sig][:syscall=syscall][:delay_en‐
830       ter=delay][:delay_exit=delay][:poke_en‐
831       ter=@argN=DATAN,@argM=DATAM...][:poke_exit=@argN=DATAN,@argM=DATAM...][:when=expr]
832                   Perform  syscall  tampering  for  the  specified   set   of
833                   syscalls.   The  syntax of the syscall_set specification is
834                   the same as in the -e trace option.
835
836                   At least one of error,  retval,  signal,  delay_enter,  de‐
837                   lay_exit, poke_enter, or poke_exit options has to be speci‐
838                   fied.  error and retval are mutually exclusive.
839
840                   If :error=errno option is specified, a  fault  is  injected
841                   into  a  syscall invocation: the syscall number is replaced
842                   by -1 which corresponds to an  invalid  syscall  (unless  a
843                   syscall  is specified with :syscall= option), and the error
844                   code is specified using a symbolic errno value like  ENOSYS
845                   or a numeric value within 1..4095 range.
846
847                   If  :retval=value option is specified, success injection is
848                   performed: the syscall number is replaced by -1, but a  bo‐
849                   gus success value is returned to the callee.
850
851                   If  :signal=sig  option is specified with either a symbolic
852                   value like SIGSEGV or a numeric  value  within  1..SIGRTMAX
853                   range,  that  signal is delivered on entering every syscall
854                   specified by the set.
855
856                   If  :delay_enter=delay  or  :delay_exit=delay  options  are
857                   specified,  delay injection is performed: the tracee is de‐
858                   layed by time period specified by delay on entering or  ex‐
859                   iting the syscall, respectively.  The format of delay spec‐
860                   ification is described in section Time specification format
861                   description.
862
863                   If        :poke_enter=@argN=DATAN,@argM=DATAM...         or
864                   :poke_exit=@argN=DATAN,@argM=DATAM...  options  are  speci‐
865                   fied,  tracee's  memory  at locations, pointed to by system
866                   call arguments argN and argM (going from arg1 to  arg7)  is
867                   overwritten by data DATAN and DATAM (specified in hexadeci‐
868                   mal       format;       for        example        :poke_en‐
869                   ter=@arg1=0000DEAD0000BEEF).   :poke_enter  modifies memory
870                   on syscall enter, and :poke_exit - on exit.
871
872                   If :signal=sig option is  specified  without  :error=errno,
873                   :retval=value  or  :delay_{enter,exit}=usecs  options, then
874                   only a signal sig is delivered without a syscall  fault  or
875                   delay injection.  Conversely, :error=errno or :retval=value
876                   option  without  :delay_enter=delay,  :delay_exit=delay  or
877                   :signal=sig  options  injects  a fault without delivering a
878                   signal or injecting a delay, etc.
879
880                   If :signal=sig option is specified together with :error=er‐
881                   rno  or  :retval=value,  then  both injection of a fault or
882                   success and signal delivery are performed.
883
884                   if :syscall=syscall option is specified, the  corresponding
885                   syscall  with  no  side  effects is injected instead of -1.
886                   Currently, only "pure"  (see  -e  trace=%pure  description)
887                   syscalls can be specified there.
888
889                   Unless  a  :when=expr subexpression is specified, an injec‐
890                   tion is being made into every invocation  of  each  syscall
891                   from the set.
892
893                   The format of the subexpression is:
894
895                             first[..last][+[step]]
896
897                   Number  first stands for the first invocation number in the
898                   range, number last stands for the last invocation number in
899                   the range, and step stands for the step between two consec‐
900                   utive invocations.  The following combinations are useful:
901
902                   first             For every syscall from the  set,  perform
903                                     an  injection  for the syscall invocation
904                                     number first only.
905                   first..last       For every syscall from the  set,  perform
906                                     an  injection  for the syscall invocation
907                                     number first and all  subsequent  invoca‐
908                                     tions  until  the  invocation number last
909                                     (inclusive).
910                   first+            For every syscall from the  set,  perform
911                                     injections  for  the  syscall  invocation
912                                     number first and all  subsequent  invoca‐
913                                     tions.
914                   first..last+      For  every  syscall from the set, perform
915                                     injections  for  the  syscall  invocation
916                                     number  first  and all subsequent invoca‐
917                                     tions until the  invocation  number  last
918                                     (inclusive).
919                   first+step        For  every  syscall from the set, perform
920                                     injections for syscall invocations number
921                                     first,  first+step,  first+step+step, and
922                                     so on.
923                   first..last+step  Same as the previous, but  consider  only
924                                     syscall  invocations  with  numbers up to
925                                     last (inclusive).
926
927                   For example,  to  fail  each  third  and  subsequent  chdir
928                   syscalls     with     ENOENT,    use    -e inject=chdir:er‐
929                   ror=ENOENT:when=3+.
930
931                   The valid range for numbers first and step is 1..65535, and
932                   for number last is 1..65534.
933
934                   An injection expression can contain only one error= or ret‐
935                   val= specification, and only one signal= specification.  If
936                   an  injection expression contains multiple when= specifica‐
937                   tions, the last one takes precedence.
938
939                   Accounting of syscalls that are  subject  to  injection  is
940                   done per syscall and per tracee.
941
942                   Specification  of  syscall  injection  can be combined with
943                   other syscall filtering options, for example, -P /dev/uran‐
944                   dom -e inject=file:error=ENOENT.
945
946       -e fault=syscall_set[:error=errno][:when=expr]
947       --fault=syscall_set[:error=errno][:when=expr]
948                   Perform  syscall  fault  injection for the specified set of
949                   syscalls.
950
951                   This is equivalent to more  generic  -e inject=  expression
952                   with default value of errno option set to ENOSYS.
953
954   Miscellaneous
955       -d
956       --debug     Show some debugging output of strace itself on the standard
957                   error.
958
959       -F          This option is deprecated.  It  is  retained  for  backward
960                   compatibility  only  and may be removed in future releases.
961                   Usage of multiple instances of -F option is  still  equiva‐
962                   lent to a single -f, and it is ignored at all if used along
963                   with one or more instances of -f option.
964
965       -h
966       --help      Print the help summary.
967
968       --seccomp-bpf
969                   Try to enable use of seccomp-bpf (see seccomp(2))  to  have
970                   ptrace(2)-stops  only  when  system  calls  that  are being
971                   traced occur in the traced processes.  This option  has  no
972                   effect  unless -f/--follow-forks is also specified.  --sec‐
973                   comp-bpf is also not applicable to processes attached using
974                   -p/--attach option.  An attempt to enable system calls fil‐
975                   tering using seccomp-bpf may fail for various reasons, e.g.
976                   there  are too many system calls to filter, the seccomp API
977                   is not available, or strace itself  is  being  traced.   In
978                   cases when seccomp-bpf filter setup failed, strace proceeds
979                   as usual and stops traced processes on every system call.
980
981       -V
982       --version   Print the version number of strace.
983
984   Time specification format description
985       Time values can be specified as a decimal floating point number  (in  a
986       format  accepted  by strtod(3)), optionally followed by one of the fol‐
987       lowing suffices that specify the unit of time: s  (seconds),  ms  (mil‐
988       liseconds),  us  (microseconds),  or ns (nanoseconds).  If no suffix is
989       specified, the value is interpreted as microseconds.
990
991       The described format is used for -O, -e inject=delay_enter, and -e  in‐
992       ject=delay_exit options.
993

DIAGNOSTICS

995       When command exits, strace exits with the same exit status.  If command
996       is terminated by a signal, strace terminates itself with the same  sig‐
997       nal, so that strace can be used as a wrapper process transparent to the
998       invoking parent process.  Note that parent-child  relationship  (signal
999       stop  notifications,  getppid(2) value, etc) between traced process and
1000       its parent are not preserved unless -D is used.
1001
1002       When using -p without a command, the exit status of strace is zero  un‐
1003       less no processes has been attached or there was an unexpected error in
1004       doing the tracing.
1005

SETUID INSTALLATION

1007       If strace is installed setuid to root then the invoking  user  will  be
1008       able  to  attach to and trace processes owned by any user.  In addition
1009       setuid and setgid programs will be executed and traced with the correct
1010       effective  privileges.   Since only users trusted with full root privi‐
1011       leges should be allowed to do these things, it only makes sense to  in‐
1012       stall  strace  as  setuid to root when the users who can execute it are
1013       restricted to those users who have this trust.  For example,  it  makes
1014       sense  to  install  a  special version of strace with mode 'rwsr-xr--',
1015       user root and group trace, where members of the trace group are trusted
1016       users.   If you do use this feature, please remember to install a regu‐
1017       lar non-setuid version of strace for ordinary users to use.
1018

MULTIPLE PERSONALITIES SUPPORT

1020       On some architectures, strace supports decoding of  syscalls  for  pro‐
1021       cesses that use different ABI rather than the one strace uses.  Specif‐
1022       ically, in addition to decoding native ABI, strace can decode the  fol‐
1023       lowing ABIs on the following architectures:
1024
1025       ┌───────────────────┬─────────────────────────┐
1026Architecture       ABIs supported          
1027       ├───────────────────┼─────────────────────────┤
1028       │x86_64             │ i386, x32 [1]; i386 [2] │
1029       ├───────────────────┼─────────────────────────┤
1030       │AArch64            │ ARM 32-bit EABI         │
1031       ├───────────────────┼─────────────────────────┤
1032       │PowerPC 64-bit [3] │ PowerPC 32-bit          │
1033       ├───────────────────┼─────────────────────────┤
1034       │s390x              │ s390                    │
1035       ├───────────────────┼─────────────────────────┤
1036       │SPARC 64-bit       │ SPARC 32-bit            │
1037       ├───────────────────┼─────────────────────────┤
1038       │TILE 64-bit        │ TILE 32-bit             │
1039       └───────────────────┴─────────────────────────┘
1040       [1]  When strace is built as an x86_64 application
1041       [2]  When strace is built as an x32 application
1042       [3]  Big endian only
1043
1044       This  support  is  optional and relies on ability to generate and parse
1045       structure definitions during the build time.  Please refer to the  out‐
1046       put  of  the  strace  -V command in order to figure out what support is
1047       available in your strace build ("non-native" refers to an ABI that dif‐
1048       fers from the ABI strace has):
1049
1050       m32-mpers      strace  can  trace and properly decode non-native 32-bit
1051                      binaries.
1052       no-m32-mpers   strace can trace, but cannot properly decode  non-native
1053                      32-bit binaries.
1054       mx32-mpers     strace   can   trace   and  properly  decode  non-native
1055                      32-on-64-bit binaries.
1056       no-mx32-mpers  strace can trace, but cannot properly decode  non-native
1057                      32-on-64-bit binaries.
1058
1059       If  the output contains neither m32-mpers nor no-m32-mpers, then decod‐
1060       ing of non-native 32-bit binaries is not implemented at all or not  ap‐
1061       plicable.
1062
1063       Likewise,  if the output contains neither mx32-mpers nor no-mx32-mpers,
1064       then decoding of non-native 32-on-64-bit binaries is not implemented at
1065       all or not applicable.
1066

NOTES

1068       It  is  a  pity that so much tracing clutter is produced by systems em‐
1069       ploying shared libraries.
1070
1071       It is instructive to think about system  call  inputs  and  outputs  as
1072       data-flow across the user/kernel boundary.  Because user-space and ker‐
1073       nel-space are separate and address-protected, it is sometimes  possible
1074       to  make  deductive  inferences about process behavior using inputs and
1075       outputs as propositions.
1076
1077       In some cases, a system call will differ from the  documented  behavior
1078       or  have  a  different name.  For example, the faccessat(2) system call
1079       does not have flags argument, and  the  setrlimit(2)  library  function
1080       uses  prlimit64(2) system call on modern (2.6.38+) kernels.  These dis‐
1081       crepancies are normal but idiosyncratic characteristics of  the  system
1082       call interface and are accounted for by C library wrapper functions.
1083
1084       Some  system  calls have different names in different architectures and
1085       personalities.  In these cases, system call filtering and printing uses
1086       the names that match corresponding __NR_* kernel macros of the tracee's
1087       architecture and personality.  There are two exceptions from this  gen‐
1088       eral  rule:  arm_fadvise64_64(2) ARM syscall and xtensa_fadvise64_64(2)
1089       Xtensa syscall are filtered and printed as fadvise64_64(2).
1090
1091       On x32, syscalls that are intended to be used by 64-bit  processes  and
1092       not  x32  ones  (for  example,  readv(2), that has syscall number 19 on
1093       x86_64, with its x32 counterpart has syscall number  515),  but  called
1094       with __X32_SYSCALL_BIT flag being set, are designated with #64 suffix.
1095
1096       On  some platforms a process that is attached to with the -p option may
1097       observe a spurious EINTR return from the current system  call  that  is
1098       not  restartable.   (Ideally,  all  system calls should be restarted on
1099       strace attach, making the attach invisible to the traced process, but a
1100       few  system calls aren't.  Arguably, every instance of such behavior is
1101       a kernel bug.)  This may have an unpredictable effect on the process if
1102       the process takes no action to restart the system call.
1103
1104       As strace executes the specified command directly and does not employ a
1105       shell for that, scripts without shebang that usually run just fine when
1106       invoked  by  shell fail to execute with ENOEXEC error.  It is advisable
1107       to manually supply a shell as a command with the script  as  its  argu‐
1108       ment.
1109

BUGS

1111       Programs  that  use the setuid bit do not have effective user ID privi‐
1112       leges while being traced.
1113
1114       A traced process runs slowly (but check out the --seccomp-bpf option).
1115
1116       Traced processes which are descended from command may be  left  running
1117       after an interrupt signal (CTRL-C).
1118

HISTORY

1120       The  original  strace  was written by Paul Kranenburg for SunOS and was
1121       inspired by its trace utility.  The SunOS version of strace was  ported
1122       to  Linux  and  enhanced  by Branko Lankester, who also wrote the Linux
1123       kernel support.  Even though Paul released strace 2.5 in 1992, Branko's
1124       work  was  based on Paul's strace 1.5 release from 1991.  In 1993, Rick
1125       Sladkey merged strace 2.5 for SunOS and the second  release  of  strace
1126       for  Linux,  added many of the features of truss(1) from SVR4, and pro‐
1127       duced an strace that worked on both platforms.   In  1994  Rick  ported
1128       strace  to  SVR4 and Solaris and wrote the automatic configuration sup‐
1129       port.  In 1995 he ported strace to Irix and tired of writing about him‐
1130       self in the third person.
1131
1132       Beginning with 1996, strace was maintained by Wichert Akkerman.  During
1133       his tenure, strace development migrated to CVS; ports  to  FreeBSD  and
1134       many  architectures on Linux (including ARM, IA-64, MIPS, PA-RISC, Pow‐
1135       erPC, s390, SPARC) were introduced.  In  2002,  the  burden  of  strace
1136       maintainership  was  transferred to Roland McGrath.  Since then, strace
1137       gained support for several new Linux architectures (AMD64,  s390x,  Su‐
1138       perH),  bi-architecture support for some of them, and received numerous
1139       additions and improvements in syscalls decoders on Linux; strace devel‐
1140       opment  migrated  to git during that period.  Since 2009, strace is ac‐
1141       tively maintained by Dmitry Levin.  strace gained support for  AArch64,
1142       ARC,  AVR32,  Blackfin,  Meta, Nios II, OpenRISC 1000, RISC-V, Tile/Ti‐
1143       leGx, Xtensa architectures since that time.  In 2012, unmaintained  and
1144       apparently  broken support for non-Linux operating systems was removed.
1145       Also, in 2012 strace gained support for path tracing and file  descrip‐
1146       tor  path  decoding.   In  2014,  support for stack traces printing was
1147       added.  In 2016, syscall fault injection was implemented.
1148
1149       For the additional information, please  refer  to  the  NEWS  file  and
1150       strace repository commit log.
1151

REPORTING BUGS

1153       Problems  with  strace  should  be  reported to the strace mailing list
1154       ⟨mailto:strace-devel@lists.strace.io⟩.
1155

SEE ALSO

1157       strace-log-merge(1), ltrace(1), perf-trace(1),  trace-cmd(1),  time(1),
1158       ptrace(2), proc(5)
1159
1160       strace Home Page ⟨https://strace.io/
1161

AUTHORS

1163       The  complete  list  of strace contributors can be found in the CREDITS
1164       file.
1165
1166
1167
1168strace 5.16                       2022-01-04                         STRACE(1)
Impressum