logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

strace.1 (56340B)


  1. .\" Copyright (c) 1991, 1992 Paul Kranenburg <pk@cs.few.eur.nl>
  2. .\" Copyright (c) 1993 Branko Lankester <branko@hacktic.nl>
  3. .\" Copyright (c) 1993, 1994, 1995, 1996 Rick Sladkey <jrs@world.std.com>
  4. .\" Copyright (c) 1996-2021 The strace developers.
  5. .\" All rights reserved.
  6. .\"
  7. .\" SPDX-License-Identifier: LGPL-2.1-or-later
  8. .de CW
  9. .sp
  10. .in +4n
  11. .nf
  12. .ft CW
  13. ..
  14. .de CE
  15. .ft R
  16. .fi
  17. .in
  18. .sp
  19. ..
  20. .\" Like .OP, but with ellipsis at the end in order to signify that option
  21. .\" can be provided multiple times. Based on .OP definition in groff's
  22. .\" an-ext.tmac.
  23. .de OM
  24. . ie \\n(.$-1 \
  25. . RI "[\fB\\$1\fP" "\ \\$2" "]...\&"
  26. . el \
  27. . RB "[" "\\$1" "]...\&"
  28. ..
  29. .\" Required option.
  30. .de OR
  31. . ie \\n(.$-1 \
  32. . RI "\fB\\$1\fP" "\ \\$2"
  33. . el \
  34. . BR "\\$1"
  35. ..
  36. .TH STRACE 1 "2024-06-30" "strace 6.12"
  37. .SH NAME
  38. strace \- trace system calls and signals
  39. .SH SYNOPSIS
  40. .SY strace
  41. .\" -kk option is available:
  42. .if ''#' .if '@USE_LIBDW_FALSE@'#' .OP \-ACdffhikkqqrtttTvVwxxyyYzZ
  43. .\" only -k option is available:
  44. .if ''#' .if '@USE_LIBUNWIND_FALSE@'#' .OP \-ACdffhikqqrtttTvVwxxyyYzZ
  45. .\" no -k option is available:
  46. .if '#'#' .OP \-ACdffhiqqrtttTvVwxxyyYzZ
  47. .OP \-a column
  48. .OP \-b execve
  49. .OM \-e expr
  50. .OP \-I n
  51. .OP \-o file
  52. .OP \-O overhead
  53. .OM \-p pid
  54. .OM \-P path
  55. .OP \-s strsize
  56. .OP \-S sortby
  57. .OP \-U columns
  58. .OP \-X format
  59. .OP \-\-seccomp\-bpf
  60. .if ''#' .OP \-\-stack\-trace\-frame\-limit\fR=\fIlimit\fR
  61. .OP \-\-syscall\-limit=\fIlimit\fR
  62. .if ''#' .OP \-\-secontext\fR[=\fIformat\fR]
  63. .OP \-\-tips\fR[=\fIformat\fR]
  64. .BR "" {
  65. .OR \-p pid
  66. .BR "" |
  67. .OP \-DDD
  68. .OM \-E var\fR[=\fIval\fR]
  69. .OP \-u username
  70. .IR command " [" args ]
  71. .BR "" }
  72. .YS
  73. .SY strace
  74. .B \-c
  75. .OP \-dfwzZ
  76. .OP \-b execve
  77. .OM \-e expr
  78. .OP \-I n
  79. .OP \-O overhead
  80. .OM \-p pid
  81. .OM \-P path
  82. .OP \-S sortby
  83. .OP \-U columns
  84. .OP \-\-seccomp\-bpf
  85. .OP \-\-syscall\-limit=\fIlimit\fR
  86. .OP \-\-tips\fR[=\fIformat\fR]
  87. .BR "" {
  88. .OR \-p pid
  89. .BR "" |
  90. .OP \-DDD
  91. .OM \-E var\fR[=\fIval\fR]
  92. .OP -u username
  93. .IR command " [" args ]
  94. .BR "" }
  95. .YS
  96. .SY strace
  97. .B \-\-tips\fR[=\fIformat\fR]
  98. .YS
  99. .SH DESCRIPTION
  100. .IX "strace command" "" "\fLstrace\fR command"
  101. .LP
  102. In the simplest case
  103. .B strace
  104. runs the specified
  105. .I command
  106. until it exits.
  107. It intercepts and records the system calls which are called
  108. by a process and the signals which are received by a process.
  109. The name of each system call, its arguments and its return value
  110. are printed on standard error or to the file specified with the
  111. .B \-o
  112. option.
  113. .LP
  114. .B strace
  115. is a useful diagnostic, instructional, and debugging tool.
  116. System administrators, diagnosticians and trouble-shooters will find
  117. it invaluable for solving problems with
  118. programs for which the source is not readily available since
  119. they do not need to be recompiled in order to trace them.
  120. Students, hackers and the overly-curious will find that
  121. a great deal can be learned about a system and its system calls by
  122. tracing even ordinary programs. And programmers will find that
  123. since system calls and signals are events that happen at the user/kernel
  124. interface, a close examination of this boundary is very
  125. useful for bug isolation, sanity checking and
  126. attempting to capture race conditions.
  127. .LP
  128. Each line in the trace contains the system call name, followed
  129. by its arguments in parentheses and its return value.
  130. An example from stracing the command "cat /dev/null" is:
  131. .CW
  132. open("/dev/null", O_RDONLY) = 3
  133. .CE
  134. Errors (typically a return value of \-1) have the errno symbol
  135. and error string appended.
  136. .CW
  137. open("/foo/bar", O_RDONLY) = \-1 ENOENT (No such file or directory)
  138. .CE
  139. Signals are printed as signal symbol and decoded siginfo structure.
  140. An excerpt from stracing and interrupting the command "sleep 666" is:
  141. .CW
  142. sigsuspend([] <unfinished ...>
  143. --- SIGINT {si_signo=SIGINT, si_code=SI_USER, si_pid=...} ---
  144. +++ killed by SIGINT +++
  145. .CE
  146. If a system call is being executed and meanwhile another one is being called
  147. from a different thread/process then
  148. .B strace
  149. will try to preserve the order of those events and mark the ongoing call as
  150. being
  151. .IR unfinished .
  152. When the call returns it will be marked as
  153. .IR resumed .
  154. .CW
  155. [pid 28772] select(4, [3], NULL, NULL, NULL <unfinished ...>
  156. [pid 28779] clock_gettime(CLOCK_REALTIME, {tv_sec=1130322148, tv_nsec=3977000}) = 0
  157. [pid 28772] <... select resumed> ) = 1 (in [3])
  158. .CE
  159. Interruption of a (restartable) system call by a signal delivery is processed
  160. differently as kernel terminates the system call and also arranges its
  161. immediate reexecution after the signal handler completes.
  162. .CW
  163. read(0, 0x7ffff72cf5cf, 1) = ? ERESTARTSYS (To be restarted)
  164. --- SIGALRM {si_signo=SIGALRM, si_code=SI_KERNEL} ---
  165. rt_sigreturn({mask=[]}) = 0
  166. read(0, "", 1) = 0
  167. .CE
  168. Arguments are printed in symbolic form with passion.
  169. This example shows the shell performing ">>xyzzy" output redirection:
  170. .CW
  171. open("xyzzy", O_WRONLY|O_APPEND|O_CREAT, 0666) = 3
  172. .CE
  173. Here, the second and the third argument of
  174. .BR open (2)
  175. are decoded by breaking down the
  176. flag argument into its three bitwise-OR constituents and printing the
  177. mode value in octal by tradition. Where the traditional or native
  178. usage differs from ANSI or POSIX, the latter forms are preferred.
  179. In some cases,
  180. .B strace
  181. output is proven to be more readable than the source.
  182. .LP
  183. Structure pointers are dereferenced and the members are displayed
  184. as appropriate. In most cases, arguments are formatted in the most C-like
  185. fashion possible.
  186. For example, the essence of the command "ls \-l /dev/null" is captured as:
  187. .CW
  188. lstat("/dev/null", {st_mode=S_IFCHR|0666, st_rdev=makedev(0x1, 0x3), ...}) = 0
  189. .CE
  190. Notice how the 'struct stat' argument is dereferenced and how each member is
  191. displayed symbolically. In particular, observe how the
  192. .B st_mode
  193. member is carefully decoded into a bitwise-OR of symbolic and numeric values.
  194. Also notice in this example that the first argument to
  195. .BR lstat (2)
  196. is an input to the system call and the second argument is an output.
  197. Since output arguments are not modified if the system call fails, arguments may
  198. not always be dereferenced. For example, retrying the "ls \-l" example
  199. with a non-existent file produces the following line:
  200. .CW
  201. lstat("/foo/bar", 0xb004) = \-1 ENOENT (No such file or directory)
  202. .CE
  203. In this case the porch light is on but nobody is home.
  204. .LP
  205. Syscalls unknown to
  206. .B strace
  207. are printed raw, with the unknown system call number printed in hexadecimal form
  208. and prefixed with "syscall_":
  209. .CW
  210. syscall_0xbad(0x1, 0x2, 0x3, 0x4, 0x5, 0x6) = -1 ENOSYS (Function not implemented)
  211. .CE
  212. .LP
  213. Character pointers are dereferenced and printed as C strings.
  214. Non-printing characters in strings are normally represented by
  215. ordinary C escape codes.
  216. Only the first
  217. .I strsize
  218. (32 by default) bytes of strings are printed;
  219. longer strings have an ellipsis appended following the closing quote.
  220. Here is a line from "ls \-l" where the
  221. .BR getpwuid (3)
  222. library routine is reading the password file:
  223. .CW
  224. read(3, "root::0:0:System Administrator:/"..., 1024) = 422
  225. .CE
  226. While structures are annotated using curly braces, pointers to basic types
  227. and arrays are printed using square brackets with commas separating
  228. the elements. Here is an example from the command
  229. .BR id (1)
  230. on a system with supplementary group ids:
  231. .CW
  232. getgroups(32, [100, 0]) = 2
  233. .CE
  234. On the other hand, bit-sets are also shown using square brackets,
  235. but set elements are separated only by a space.
  236. Here is the shell, preparing to execute an external command:
  237. .CW
  238. sigprocmask(SIG_BLOCK, [CHLD TTOU], []) = 0
  239. .CE
  240. Here, the second argument is a bit-set of two signals,
  241. .BR SIGCHLD " and " SIGTTOU .
  242. In some cases, the bit-set is so full that printing out the unset
  243. elements is more valuable. In that case, the bit-set is prefixed by
  244. a tilde like this:
  245. .CW
  246. sigprocmask(SIG_UNBLOCK, ~[], NULL) = 0
  247. .CE
  248. Here, the second argument represents the full set of all signals.
  249. .SH OPTIONS
  250. .SS General
  251. .TP 12
  252. .BI "\-e " expr
  253. A qualifying expression which modifies which events to trace
  254. or how to trace them. The format of the expression is:
  255. .RS 15
  256. .IP
  257. [\,\fIqualifier\/\fB=\fR][\fB!\fR]\,\fIvalue\/\fR[\fB,\fR\,\fIvalue\/\fR]...
  258. .RE
  259. .IP
  260. where
  261. .I qualifier
  262. is one of
  263. .BR trace " (or " t ),
  264. .BR trace\-fds " (or " trace\-fd " or " fd " or " fds ),
  265. .BR abbrev " (or " a ),
  266. .BR verbose " (or " v ),
  267. .BR raw " (or " x ),
  268. .BR signal " (or " signals " or " s ),
  269. .BR read " (or " reads " or " r ),
  270. .BR write " (or " writes " or " w ),
  271. .BR fault ,
  272. .BR inject ,
  273. .BR status ,
  274. .BR quiet " (or " silent " or " silence " or " q ),
  275. .if ''#' .BR secontext ,
  276. .BR decode\-fds " (or " decode\-fd ),
  277. .BR decode\-pids " (or " decode\-pid ),
  278. or
  279. .BR kvm ,
  280. and
  281. .I value
  282. is a qualifier-dependent symbol or number. The default
  283. qualifier is
  284. .BR trace .
  285. Using an exclamation mark negates the set of values. For example,
  286. .BR \-e "\ " open
  287. means literally
  288. .BR \-e "\ " trace = open
  289. which in turn means trace only the
  290. .B open
  291. system call. By contrast,
  292. .BR \-e "\ " trace "=!" open
  293. means to trace every system call except
  294. .BR open .
  295. In addition, the special values
  296. .B all
  297. and
  298. .B none
  299. have the obvious meanings.
  300. .IP
  301. Note that some shells use the exclamation point for history
  302. expansion even inside quoted arguments. If so, you must escape
  303. the exclamation point with a backslash.
  304. .SS Startup
  305. .TP 12
  306. \fB\-E\ \fIvar\fR=\,\fIval\fR
  307. .TQ
  308. .BR "\-\-env" = \fIvar\fR = \fIval\fR
  309. Run command with
  310. .IR var = val
  311. in its list of environment variables.
  312. .TP
  313. .BI "\-E " var
  314. .TQ
  315. .BR "\-\-env" = \fIvar\fR
  316. Remove
  317. .IR var
  318. from the inherited list of environment variables before passing it on to
  319. the command.
  320. .TP
  321. .BI "\-p " pid
  322. .TQ
  323. .BR "\-\-attach" = \fIpid\fR
  324. Attach to the process with the process
  325. .SM ID
  326. .I pid
  327. and begin tracing.
  328. The trace may be terminated
  329. at any time by a keyboard interrupt signal
  330. .RB ( CTRL\-C ).
  331. .B strace
  332. will respond by detaching itself from the traced process(es)
  333. leaving it (them) to continue running.
  334. Multiple
  335. .B \-p
  336. options can be used to attach to many processes in addition to
  337. .I command
  338. (which is optional if at least one
  339. .B \-p
  340. option is given).
  341. Multiple process IDs, separated by either
  342. comma (\(lq,\(rq), space (\(lq \(rq), tab, or newline character,
  343. can be provided as an argument to a single
  344. .B \-p
  345. option, so, for example,
  346. .B \-p
  347. "$(pidof PROG)" and
  348. .B \-p
  349. "$(pgrep PROG)" syntaxes are supported.
  350. .TP
  351. .BI "\-u " username
  352. .TQ
  353. .BR "\-\-user" = \fIusername\fR
  354. Run command with the user \s-1ID\s0, group \s-2ID\s0, and
  355. supplementary groups of
  356. .IR username .
  357. This option is only useful when running as root and enables the
  358. correct execution of setuid and/or setgid binaries.
  359. Unless this option is used setuid and setgid programs are executed
  360. without effective privileges.
  361. .TQ
  362. .BI "\-u " UID:GID
  363. .TQ
  364. .BR "\-\-user" = \fIUID:GID\fR
  365. Alternative syntax where the program is started with exactly the given user
  366. and group IDs, and an empty list of supplementary groups. In this case,
  367. user and group name lookups are not performed.
  368. .TP
  369. .BR "\-\-argv0" = \fIname\fR
  370. Set argv[0] of the command being executed to
  371. .IR name .
  372. Useful for tracing multi-call executables which interpret argv[0],
  373. such as busybox or kmod.
  374. .SS Tracing
  375. .TP 12
  376. .BI "\-b " syscall
  377. .TQ
  378. .BR "\-\-detach\-on" = \fIsyscall\fR
  379. If specified syscall is reached, detach from traced process.
  380. Currently, only
  381. .BR execve (2)
  382. syscall is supported. This option is useful if you want to trace
  383. multi-threaded process and therefore require
  384. .BR \-f ,
  385. but don't want to trace its (potentially very complex) children.
  386. .TP
  387. .B \-D
  388. .TQ
  389. .B \-\-daemonize
  390. .TQ
  391. .BR \-\-daemonize = grandchild
  392. Run tracer process as a grandchild, not as the parent of the
  393. tracee. This reduces the visible effect of
  394. .B strace
  395. by keeping the tracee a direct child of the calling process.
  396. .TP
  397. .B \-DD
  398. .TQ
  399. .BR \-\-daemonize = pgroup
  400. .TQ
  401. .BR \-\-daemonize = pgrp
  402. Run tracer process as tracee's grandchild in a separate process group.
  403. In addition to reduction of the visible effect of
  404. .BR strace ,
  405. it also avoids killing of
  406. .B strace
  407. with
  408. .BR kill (2)
  409. issued to the whole process group.
  410. .TP
  411. .B \-DDD
  412. .TQ
  413. .BR \-\-daemonize = session
  414. Run tracer process as tracee's grandchild in a separate session
  415. ("true daemonisation").
  416. In addition to reduction of the visible effect of
  417. .BR strace ,
  418. it also avoids killing of
  419. .B strace
  420. upon session termination.
  421. .TP
  422. .B \-f
  423. .TQ
  424. .BR \-\-follow\-forks
  425. Trace child processes as they are created by currently traced
  426. processes as a result of the
  427. .BR fork (2),
  428. .BR vfork (2)
  429. and
  430. .BR clone (2)
  431. system calls. Note that
  432. .B \-p
  433. .I PID
  434. .B \-f
  435. will attach all threads of process
  436. .I PID
  437. if it is multi-threaded, not only thread with
  438. .IR thread_id " = " PID .
  439. .TP
  440. .B \-\-output\-separately
  441. If the
  442. .BR \-\-output = \fIfilename\fR
  443. option is in effect, each processes trace is written to
  444. .IR filename . pid
  445. where
  446. .I pid
  447. is the numeric process id of each process.
  448. .TP
  449. .B \-ff
  450. .TQ
  451. .B \-\-follow\-forks \-\-output\-separately
  452. Combine the effects of
  453. .B \-\-follow\-forks
  454. and
  455. .B \-\-output\-separately
  456. options.
  457. This is incompatible with
  458. .BR \-c ,
  459. since no per-process counts are kept.
  460. .IP
  461. One might want to consider using
  462. .BR strace-log-merge (1)
  463. to obtain a combined strace log view.
  464. .TP
  465. .BI "\-I " interruptible
  466. .TQ
  467. .BR "\-\-interruptible" = \fIinterruptible\fR
  468. When
  469. .B strace
  470. can be interrupted by signals (such as pressing
  471. .BR CTRL\-C ).
  472. .RS
  473. .TP 15
  474. .BR 1 ", " anywhere
  475. no signals are blocked;
  476. .TQ
  477. .BR 2 ", " waiting
  478. fatal signals are blocked while decoding syscall (default);
  479. .TQ
  480. .BR 3 ", " never
  481. fatal signals are always blocked (default if
  482. .BR -o " " \fIFILE\fR " " \fIPROG\fR );
  483. .TQ
  484. .BR 4 ", " never_tstp
  485. fatal signals and
  486. .BR SIGTSTP " (" CTRL\-Z )
  487. are always blocked (useful to make
  488. .BI "strace -o " "FILE PROG"
  489. not stop on
  490. .BR CTRL\-Z ,
  491. default if
  492. .BR \-D ).
  493. .RE
  494. .TP
  495. .BR "\-\-syscall\-limit" = \fIlimit\fR
  496. Detach all tracees when
  497. .I limit
  498. number of syscalls have been captured. Syscalls filtered out via
  499. .BR \-\-trace ,
  500. .B \-\-trace\-path
  501. or
  502. .B \-\-status
  503. options are not considered when keeping track of the number of syscalls that are captured.
  504. .TP
  505. .B \-\-kill\-on\-exit
  506. Apply
  507. .B PTRACE_O_EXITKILL
  508. ptrace option to all tracee processes (which sends a SIGKILL signal to
  509. the tracee if the tracer exits) and do not detach them on cleanup so
  510. they will not be left running after the tracer exit.
  511. .B \-\-kill\-on\-exit
  512. is not compatible with
  513. .BR \-p / \-\-attach
  514. options.
  515. .SS Filtering
  516. .TP 12
  517. \fB\-e\ trace\fR=\,\fIsyscall_set\fR
  518. .TQ
  519. \fB\-e\ t\fR=\,\fIsyscall_set\fR
  520. .TQ
  521. \fB\-\-trace\fR=\,\fIsyscall_set\fR
  522. Trace only the specified set of system calls.
  523. .I syscall_set
  524. is defined as
  525. [\fB!\fR]\,\fIvalue\fR[\fB,\fR\,\fIvalue\/\fR],
  526. and
  527. .I value
  528. can be one of the following:
  529. .RS
  530. .TP 13
  531. .I syscall
  532. Trace specific syscall, specified by its name (see
  533. .BR syscalls (2)
  534. for a reference, but also see
  535. .BR NOTES ).
  536. .TP
  537. .BI ? value
  538. Question mark before the syscall qualification allows suppression of error
  539. in case no syscalls matched the qualification provided.
  540. .TP
  541. .IB value @64
  542. Limit the syscall specification described by
  543. .I value
  544. to 64-bit personality.
  545. .TP
  546. .IB value @32
  547. Limit the syscall specification described by
  548. .I value
  549. to 32-bit personality.
  550. .TP
  551. .IB value @x32
  552. Limit the syscall specification described by
  553. .I value
  554. to x32 personality.
  555. .TP
  556. .B all
  557. Trace all system calls.
  558. .TP
  559. .BI / regex
  560. Trace only those system calls that match the
  561. .IR regex .
  562. You can use
  563. .B POSIX
  564. Extended Regular Expression syntax (see
  565. .BR regex (7)).
  566. .TP
  567. .B %file
  568. .TQ
  569. .BR file
  570. Trace all system calls which take a file name as an argument. You
  571. can think of this as an abbreviation for
  572. .BR "\-e\ trace" = open , stat , chmod , unlink ,...
  573. which is useful to seeing what files the process is referencing.
  574. Furthermore, using the abbreviation will ensure that you don't
  575. accidentally forget to include a call like
  576. .BR lstat (2)
  577. in the list. Betchya woulda forgot that one.
  578. The syntax without a preceding percent sign
  579. .RB (\[dq] "-e trace" = file \[dq])
  580. is deprecated.
  581. .TP
  582. .B %process
  583. .TQ
  584. .B process
  585. Trace system calls associated with process lifecycle
  586. (creation, exec, termination).
  587. The syntax without a preceding percent sign
  588. .RB (\[dq] "-e trace" = process \[dq])
  589. is deprecated.
  590. .TP
  591. .B %net
  592. .TQ
  593. .B %network
  594. .TQ
  595. .B network
  596. Trace all the network related system calls.
  597. The syntax without a preceding percent sign
  598. .RB (\[dq] "-e trace" = network \[dq])
  599. is deprecated.
  600. .TP
  601. .BR %signal
  602. .TQ
  603. .BR signal
  604. Trace all signal related system calls.
  605. The syntax without a preceding percent sign
  606. .RB (\[dq] "-e trace" = signal \[dq])
  607. is deprecated.
  608. .TP
  609. .BR %ipc
  610. .TQ
  611. .BR ipc
  612. Trace all IPC related system calls.
  613. The syntax without a preceding percent sign
  614. .RB (\[dq] "-e trace" = ipc \[dq])
  615. is deprecated.
  616. .TP
  617. .BR %desc
  618. .TQ
  619. .BR desc
  620. Trace all file descriptor related system calls.
  621. The syntax without a preceding percent sign
  622. .RB (\[dq] "-e trace" = desc \[dq])
  623. is deprecated.
  624. .TP
  625. .BR %memory
  626. .TQ
  627. .BR memory
  628. Trace all memory mapping related system calls.
  629. The syntax without a preceding percent sign
  630. .RB (\[dq] "-e trace" = memory \[dq])
  631. is deprecated.
  632. .TP
  633. .BR %creds
  634. Trace system calls that read or modify user and group identifiers or capability sets.
  635. .TP
  636. .BR %stat
  637. Trace stat syscall variants.
  638. .TP
  639. .BR %lstat
  640. Trace lstat syscall variants.
  641. .TP
  642. .BR %fstat
  643. Trace fstat, fstatat, and statx syscall variants.
  644. .TP
  645. .BR %%stat
  646. Trace syscalls used for requesting file status (stat, lstat, fstat, fstatat,
  647. statx, and their variants).
  648. .TP
  649. .BR %statfs
  650. Trace statfs, statfs64, statvfs, osf_statfs, and osf_statfs64 system calls.
  651. The same effect can be achieved with
  652. .BR "\-e\ trace" = /^(.*_)?statv?fs
  653. regular expression.
  654. .TP
  655. .BR %fstatfs
  656. Trace fstatfs, fstatfs64, fstatvfs, osf_fstatfs, and osf_fstatfs64 system calls.
  657. The same effect can be achieved with
  658. .BR "\-e\ trace" = /fstatv?fs
  659. regular expression.
  660. .TP
  661. .BR %%statfs
  662. Trace syscalls related to file system statistics (statfs-like, fstatfs-like,
  663. and ustat). The same effect can be achieved with
  664. .BR "\-e\ trace" = /statv?fs|fsstat|ustat
  665. regular expression.
  666. .TP
  667. .BR %clock
  668. Trace system calls that read or modify system clocks.
  669. .TP
  670. .BR %pure
  671. Trace syscalls that always succeed and have no arguments.
  672. Currently, this list includes
  673. .BR arc_gettls "(2), " getdtablesize "(2), " getegid "(2), " getegid32 "(2),"
  674. .BR geteuid "(2), " geteuid32 "(2), " getgid "(2), " getgid32 "(2),"
  675. .BR getpagesize "(2), " getpgrp "(2), " getpid "(2), " getppid "(2),"
  676. .BR get_thread_area (2)
  677. (on architectures other than x86),
  678. .BR gettid "(2), " get_tls "(2), " getuid "(2), " getuid32 "(2),"
  679. .BR getxgid "(2), " getxpid "(2), " getxuid "(2), " kern_features "(2), and"
  680. .BR metag_get_tls "(2)"
  681. syscalls.
  682. .RE
  683. .IP
  684. The
  685. .B \-c
  686. option is useful for determining which system calls might be useful
  687. to trace. For example,
  688. .BR trace = open,close,read,write
  689. means to only
  690. trace those four system calls. Be careful when making inferences
  691. about the user/kernel boundary if only a subset of system calls
  692. are being monitored. The default is
  693. .BR trace = all .
  694. .TP
  695. \fB\-e\ trace\-fd\fR=\,\fIset\fR
  696. .TQ
  697. \fB\-e\ trace\-fds\fR=\,\fIset\fR
  698. .TQ
  699. \fB\-e\ fd\fR=\,\fIset\fR
  700. .TQ
  701. \fB\-e\ fds\fR=\,\fIset\fR
  702. .TQ
  703. \fB\-\-trace\-fds\fR=\,\fIset\fR
  704. Trace only the syscalls that operate
  705. on the specified subset of (non-negative) file descriptors.
  706. Note that usage of this option also filters out all the syscalls
  707. that do not operate on file descriptors at all.
  708. Applies in (inclusive) disjunction with the \fB\-\-trace\-path\fR option.
  709. .TP
  710. \fB\-e\ signal\fR=\,\fIset\fR
  711. .TQ
  712. \fB\-e\ signals\fR=\,\fIset\fR
  713. .TQ
  714. \fB\-e\ s\fR=\,\fIset\fR
  715. .TQ
  716. \fB\-\-signal\fR=\,\fIset\fR
  717. Trace only the specified subset of signals. The default is
  718. .BR signal = all .
  719. For example,
  720. .BR signal "=!" SIGIO
  721. (or
  722. .BR signal "=!" io )
  723. causes
  724. .B SIGIO
  725. signals not to be traced.
  726. .TP
  727. \fB\-e\ status\fR=\,\fIset\fR
  728. .TQ
  729. \fB\-\-status\fR=\,\fIset\fR
  730. Print only system calls with the specified return status. The default is
  731. .BR status = all .
  732. When using the
  733. .B status
  734. qualifier, because
  735. .B strace
  736. waits for system calls to return before deciding whether they should be printed
  737. or not, the traditional order of events may not be preserved anymore. If two
  738. system calls are executed by concurrent threads,
  739. .B strace
  740. will first print both the entry and exit of the first system call to exit,
  741. regardless of their respective entry time. The entry and exit of the second
  742. system call to exit will be printed afterwards. Here is an example when
  743. .BR select (2)
  744. is called, but a different thread calls
  745. .BR clock_gettime (2)
  746. before
  747. .BR select (2)
  748. finishes:
  749. .CW
  750. [pid 28779] 1130322148.939977 clock_gettime(CLOCK_REALTIME, {1130322148, 939977000}) = 0
  751. [pid 28772] 1130322148.438139 select(4, [3], NULL, NULL, NULL) = 1 (in [3])
  752. .CE
  753. .I set
  754. can include the following elements:
  755. .RS
  756. .TP 13
  757. .B successful
  758. Trace system calls that returned without an error code.
  759. The
  760. .B -z
  761. option has the effect of
  762. .BR status = successful .
  763. .TQ
  764. .B failed
  765. Trace system calls that returned with an error code.
  766. The
  767. .B -Z
  768. option has the effect of
  769. .BR status = failed .
  770. .TQ
  771. .B unfinished
  772. Trace system calls that did not return. This might happen, for example, due to
  773. an execve call in a neighbour thread.
  774. .TQ
  775. .B unavailable
  776. Trace system calls that returned but strace failed to fetch the error status.
  777. .TQ
  778. .B detached
  779. Trace system calls for which strace detached before the return.
  780. .RE
  781. .TP
  782. .BI "\-P " path
  783. .TQ
  784. .BR "\-\-trace\-path" = \fIpath\fR
  785. Trace only system calls accessing
  786. .IR path .
  787. Multiple
  788. .B \-P
  789. options can be used to specify several paths.
  790. Applies in (inclusive) disjunction with the \fB\-\-trace\-fds\fR option.
  791. .TP
  792. .B \-z
  793. .TQ
  794. .B \-\-successful\-only
  795. Print only syscalls that returned without an error code.
  796. .TP
  797. .B \-Z
  798. .TQ
  799. .B \-\-failed\-only
  800. Print only syscalls that returned with an error code.
  801. .SS Output format
  802. .TP 12
  803. .BI "\-a " column
  804. .TQ
  805. .BR "\-\-columns" = \fIcolumn\fR
  806. Align return values in a specific column (default column 40).
  807. .TP
  808. \fB\-e\ abbrev\fR=\,\fIsyscall_set\fR
  809. .TQ
  810. \fB\-e\ a\fR=\,\fIsyscall_set\fR
  811. .TQ
  812. \fB\-\-abbrev\fR=\,\fIsyscall_set\fR
  813. Abbreviate the output from printing each member of large structures.
  814. The syntax of the
  815. .I syscall_set
  816. specification is the same as in the
  817. .B "-e trace"
  818. option.
  819. The default is
  820. .BR abbrev = all .
  821. The
  822. .B \-v
  823. option has the effect of
  824. .BR abbrev = none .
  825. .TP
  826. \fB\-e\ verbose\fR=\,\fIsyscall_set\fR
  827. .TQ
  828. \fB\-e\ v\fR=\,\fIsyscall_set\fR
  829. .TQ
  830. \fB\-\-verbose\fR=\,\fIsyscall_set\fR
  831. Dereference structures for the specified set of system calls.
  832. The syntax of the
  833. .I syscall_set
  834. specification is the same as in the
  835. .B "-e trace"
  836. option.
  837. The default is
  838. .BR verbose = all .
  839. .TP
  840. \fB\-e\ raw\fR=\,\fIsyscall_set\fR
  841. .TQ
  842. \fB\-e\ x\fR=\,\fIsyscall_set\fR
  843. .TQ
  844. \fB\-\-raw\fR=\,\fIsyscall_set\fR
  845. Print raw, undecoded arguments for the specified set of system calls.
  846. The syntax of the
  847. .I syscall_set
  848. specification is the same as in the
  849. .B "-e trace"
  850. option.
  851. This option has the effect of causing all arguments to be printed
  852. in hexadecimal. This is mostly useful if you don't trust the
  853. decoding or you need to know the actual numeric value of an
  854. argument.
  855. See also
  856. .B \-X raw
  857. option.
  858. .TP
  859. \fB\-e\ read\fR=\,\fIset\fR
  860. .TQ
  861. \fB\-e\ reads\fR=\,\fIset\fR
  862. .TQ
  863. \fB\-e\ r\fR=\,\fIset\fR
  864. .TQ
  865. \fB\-\-read\fR=\,\fIset\fR
  866. Perform a full hexadecimal and ASCII dump of all the data read from
  867. file descriptors listed in the specified set. For example, to see
  868. all input activity on file descriptors
  869. .I 3
  870. and
  871. .I 5
  872. use
  873. \fB\-e\ read\fR=\,\fI3\fR,\fI5\fR.
  874. Note that this is independent from the normal tracing of the
  875. .BR read (2)
  876. system call which is controlled by the option
  877. .BR -e "\ " trace = read .
  878. .TP
  879. \fB\-e\ write\fR=\,\fIset\fR
  880. .TQ
  881. \fB\-e\ writes\fR=\,\fIset\fR
  882. .TQ
  883. \fB\-e\ w\fR=\,\fIset\fR
  884. .TQ
  885. \fB\-\-write\fR=\,\fIset\fR
  886. Perform a full hexadecimal and ASCII dump of all the data written to
  887. file descriptors listed in the specified set. For example, to see
  888. all output activity on file descriptors
  889. .I 3
  890. and
  891. .I 5
  892. use
  893. \fB\-e\ write\fR=\,\fI3\fR,\,\fI5\fR.
  894. Note that this is independent from the normal tracing of the
  895. .BR write (2)
  896. system call which is controlled by the option
  897. .BR -e "\ " trace = write .
  898. .TP
  899. \fB\-e\ quiet\fR=\,\fIset\fR
  900. .TQ
  901. \fB\-e\ silent\fR=\,\fIset\fR
  902. .TQ
  903. \fB\-e\ silence\fR=\,\fIset\fR
  904. .TQ
  905. \fB\-e\ q\fR=\,\fIset\fR
  906. .TQ
  907. \fB\-\-quiet\fR=\,\fIset\fR
  908. .TQ
  909. \fB\-\-silent\fR=\,\fIset\fR
  910. .TQ
  911. \fB\-\-silence\fR=\,\fIset\fR
  912. Suppress various information messages. The default is
  913. .BR quiet = none .
  914. .I set
  915. can include the following elements:
  916. .RS
  917. .TP 17
  918. .B attach
  919. Suppress messages about attaching and detaching
  920. .RB (\[dq] "[ Process NNNN attached ]" "\[dq],"
  921. .RB "\[dq]" "[ Process NNNN detached ]" "\[dq])."
  922. .TQ
  923. .B exit
  924. Suppress messages about process exits
  925. .RB (\[dq] "+++ exited with SSS +++" \[dq]).
  926. .TQ
  927. .B path-resolution
  928. Suppress messages about resolution of paths provided via the
  929. .B \-P
  930. option
  931. .RB (\[dq] "Requested path \[dq]...\[dq] resolved into \[dq]...\[dq]" \[dq]).
  932. .TQ
  933. .B personality
  934. Suppress messages about process personality changes
  935. .RB (\[dq] "[ Process PID=NNNN runs in PPP mode. ]" \[dq]).
  936. .TQ
  937. .B thread-execve
  938. .TQ
  939. .B superseded
  940. Suppress messages about process being superseded by
  941. .BR execve (2)
  942. in another thread
  943. .RB (\[dq] "+++ superseded by execve in pid NNNN +++" \[dq]).
  944. .RE
  945. .TP
  946. \fB\-e\ decode\-fds\fR=\,\fIset\fR
  947. .TQ
  948. \fB\-\-decode\-fds\fR=\,\fIset\fR
  949. Decode various information associated with file descriptors. The default is
  950. .BR decode\-fds = none .
  951. .I set
  952. can include the following elements:
  953. .RS
  954. .TP 9
  955. .B path
  956. Print file paths.
  957. Also enables printing of tracee's current working directory when
  958. .B AT_FDCWD
  959. constant is used.
  960. .TQ
  961. .B socket
  962. Print socket protocol-specific information.
  963. .TQ
  964. .B dev
  965. Print character/block device numbers.
  966. .TQ
  967. .B eventfd
  968. Print eventfd object details associated with eventfd file descriptors.
  969. .TQ
  970. .B pidfd
  971. Print PIDs associated with pidfd file descriptors.
  972. .TQ
  973. .B signalfd
  974. Print signal masks associated with signalfd file descriptors.
  975. .RE
  976. .TP
  977. \fB\-e\ decode\-pids\fR=\,\fIset\fR
  978. .TQ
  979. \fB\-\-decode\-pids\fR=\,\fIset\fR
  980. Decode various information associated with process IDs
  981. (and also thread IDs, process group IDs, and session IDs).
  982. The default is
  983. .BR decode\-pids = none .
  984. .I set
  985. can include the following elements:
  986. .RS
  987. .TP 8
  988. .B comm
  989. Print command names associated with thread or process IDs.
  990. .TQ
  991. .B pidns
  992. Print thread, process, process group, and session IDs in strace's PID namespace
  993. if the tracee is in a different PID namespace.
  994. .RE
  995. .TP
  996. .BR "\-e\ kvm" = vcpu
  997. .TQ
  998. .BR "\-\-kvm" = vcpu
  999. Print the exit reason of kvm vcpu. Requires Linux kernel version 4.16.0
  1000. or higher.
  1001. .TP
  1002. .B \-i
  1003. .TQ
  1004. .B \-\-instruction\-pointer
  1005. Print the instruction pointer at the time of the system call.
  1006. .TP
  1007. .B \-n
  1008. .TQ
  1009. .B \-\-syscall\-number
  1010. Print the syscall number.
  1011. .if ''#' .TP
  1012. .if ''#' .B \-k
  1013. .if ''#' .TQ
  1014. .if ''#' .BR \-\-stack\-trace [= symbol ]
  1015. .if ''#' Print the execution stack trace of the traced
  1016. .if ''#' processes after each system call.
  1017. .if '@USE_LIBDW_FALSE@'#' .TP
  1018. .if '@USE_LIBDW_FALSE@'#' .B \-kk
  1019. .if '@USE_LIBDW_FALSE@'#' .TQ
  1020. .if '@USE_LIBDW_FALSE@'#' .BR \-\-stack\-trace = source
  1021. .if '@USE_LIBDW_FALSE@'#' Print the execution stack trace and source code information of the traced
  1022. .if '@USE_LIBDW_FALSE@'#' processes after each system call. This option expects the target program is compiled
  1023. .if '@USE_LIBDW_FALSE@'#' with appropriate debug options: "\-g" (gcc), or "\-g \-gdwarf-aranges" (clang).
  1024. .if ''#' .TP
  1025. .if ''#' .BR \-\-stack\-trace\-frame\-limit = \fIlimit\fR
  1026. .if ''#' Print no more than this amount of stack trace frames
  1027. .if ''#' when backtracing a system call (the default is 256).
  1028. .if ''#' Use this option with the
  1029. .if ''#' .B \-\-stack\-trace
  1030. .if ''#' (or
  1031. .if ''#' .BR \-k )
  1032. .if ''#' option.
  1033. .TP
  1034. .BI "\-o " filename
  1035. .TQ
  1036. .BR "\-\-output" = \fIfilename\fR
  1037. Write the trace output to the file
  1038. .I filename
  1039. rather than to stderr.
  1040. .IR filename . pid
  1041. form is used if
  1042. .B \-ff
  1043. option is supplied.
  1044. If the argument begins with '|' or '!', the rest of the
  1045. argument is treated as a command and all output is piped to it.
  1046. This is convenient for piping the debugging output to a program
  1047. without affecting the redirections of executed programs.
  1048. The latter is not compatible with
  1049. .B \-ff
  1050. option currently.
  1051. .TP
  1052. .B \-A
  1053. .TQ
  1054. .B \-\-output\-append\-mode
  1055. Open the file provided in the
  1056. .B \-o
  1057. option in append mode.
  1058. .TP
  1059. .B \-q
  1060. .TQ
  1061. .B \-\-quiet
  1062. .TQ
  1063. .BR \-\-quiet = attach , personality
  1064. Suppress messages about attaching, detaching, and personality changes.
  1065. This happens automatically when output is redirected to a file
  1066. and the command is run directly instead of attaching.
  1067. .TP
  1068. .B \-qq
  1069. .TQ
  1070. .BR \-\-quiet = attach , personality , exit
  1071. Suppress messages attaching, detaching, personality changes,
  1072. and about process exit status.
  1073. .TP
  1074. .B \-qqq
  1075. .TQ
  1076. .BR \-\-quiet = all
  1077. Suppress all suppressible messages (please refer to the
  1078. .B -e quiet
  1079. option description for the full list of suppressible messages).
  1080. .TP
  1081. .B \-r
  1082. .TQ
  1083. .BR \-\-relative\-timestamps [= \fIprecision\fR ]
  1084. Print a relative timestamp upon entry to each system call. This
  1085. records the time difference between the beginning of successive
  1086. system calls.
  1087. .I precision
  1088. can be one of
  1089. .BR s " (for seconds), " ms " (milliseconds), " us " (microseconds), or " ns
  1090. (nanoseconds), and allows setting the precision of time value being printed.
  1091. Default is
  1092. .B us
  1093. (microseconds).
  1094. Note that since
  1095. .B \-r
  1096. option uses the monotonic clock time for measuring time difference and not the
  1097. wall clock time, its measurements can differ from the difference in time
  1098. reported by the
  1099. .B \-t
  1100. option.
  1101. .TP
  1102. .BI "\-s " strsize
  1103. .TQ
  1104. .BR "\-\-string\-limit" = \fIstrsize\fR
  1105. Specify the maximum string size to print (the default is 32). Note
  1106. that filenames are not considered strings and are always printed in
  1107. full.
  1108. .TP
  1109. .BR \-\-absolute\-timestamps [=[[ format: ] \fIformat\fR ],[[ precision: ] \fIprecision ]]
  1110. .TQ
  1111. .BR \-\-timestamps [=[[ format: ] \fIformat\fR ],[[ precision: ] \fIprecision ]]
  1112. Prefix each line of the trace with the wall clock time in the specified
  1113. .I format
  1114. with the specified
  1115. .IR precision .
  1116. .I format
  1117. can be one of the following:
  1118. .RS
  1119. .TP 14
  1120. .B none
  1121. No time stamp is printed.
  1122. Can be used to override the previous setting.
  1123. .TQ
  1124. .B time
  1125. Wall clock time
  1126. .RB ( strftime (3)
  1127. format string is
  1128. .BR %T ).
  1129. .TQ
  1130. .B unix
  1131. Number of seconds since the epoch
  1132. .RB ( strftime (3)
  1133. format string is
  1134. .BR %s ).
  1135. .RE
  1136. .IP
  1137. .I precision
  1138. can be one of
  1139. .BR s " (for seconds), " ms " (milliseconds), " us " (microseconds), or " ns
  1140. (nanoseconds).
  1141. Default arguments for the option are
  1142. .BR format:time , precision:s .
  1143. .TP
  1144. .B \-t
  1145. .TQ
  1146. .B \-\-absolute\-timestamps
  1147. Prefix each line of the trace with the wall clock time.
  1148. .TP
  1149. .B \-tt
  1150. .TQ
  1151. .BR \-\-absolute\-timestamps = precision:us
  1152. If given twice, the time printed will include the microseconds.
  1153. .TP
  1154. .B \-ttt
  1155. .TQ
  1156. .BR \-\-absolute\-timestamps = format:unix , precision:us
  1157. If given thrice, the time printed will include the microseconds
  1158. and the leading portion will be printed as the number
  1159. of seconds since the epoch.
  1160. .TP
  1161. .B \-T
  1162. .TQ
  1163. .BR \-\-syscall\-times [= \fIprecision\fR ]
  1164. Show the time spent in system calls. This records the time
  1165. difference between the beginning and the end of each system call.
  1166. .I precision
  1167. can be one of
  1168. .BR s " (for seconds), " ms " (milliseconds), " us " (microseconds), or " ns
  1169. (nanoseconds), and allows setting the precision of time value being printed.
  1170. Default is
  1171. .B us
  1172. (microseconds).
  1173. .TP
  1174. .B \-v
  1175. .TQ
  1176. .B \-\-no\-abbrev
  1177. Print unabbreviated versions of environment, stat, termios, etc.
  1178. calls. These structures are very common in calls and so the default
  1179. behavior displays a reasonable subset of structure members. Use
  1180. this option to get all of the gory details.
  1181. .TP
  1182. .BR \-\-strings\-in\-hex [= \fIoption\fR ]
  1183. Control usage of escape sequences with hexadecimal numbers
  1184. in the printed strings.
  1185. Normally (when no
  1186. .BR \-\-strings\-in\-hex " or " \-x
  1187. option is supplied),
  1188. escape sequences are used to print non-printable and non-ASCII characters
  1189. (that is, characters with a character code less than 32 or greater than 127),
  1190. or to disambiguate the output
  1191. (so, for quotes and other characters that encase the printed string,
  1192. for example, angle brackets, in case of file descriptor path output);
  1193. for the former use case, unless it is a white space character
  1194. that has a symbolic escape sequence defined in the C standard
  1195. (that is, \(lq\fB\\t\fR\(rq for a horizontal tab,
  1196. \(lq\fB\\n\fR\(rq for a newline,
  1197. \(lq\fB\\v\fR\(rq for a vertical tab,
  1198. \(lq\fB\\f\fR\(rq for a form feed page break,
  1199. and \(lq\fB\\r\fR\(rq for a carriage return)
  1200. are printed using escape sequences with numbers that correspond
  1201. to their byte values, with octal number format being the default.
  1202. .I option
  1203. can be one of the following:
  1204. .RS
  1205. .TP 17
  1206. .B none
  1207. Hexadecimal numbers are not used in the output at all.
  1208. When there is a need to emit an escape sequence, octal numbers are used.
  1209. .TQ
  1210. .B non-ascii-chars
  1211. Hexadecimal numbers are used instead of octal in the escape sequences.
  1212. .TQ
  1213. .B non-ascii
  1214. Strings that contain non-ASCII characters are printed using escape sequences
  1215. with hexadecimal numbers.
  1216. .TQ
  1217. .B all
  1218. All strings are printed using escape sequences with hexadecimal numbers.
  1219. .RE
  1220. .IP
  1221. When the option is supplied without an argument,
  1222. .B all
  1223. is assumed.
  1224. .TP
  1225. .B \-x
  1226. .TQ
  1227. .BR \-\-strings\-in\-hex = non\-ascii
  1228. Print all non-ASCII strings in hexadecimal string format.
  1229. .TP
  1230. .B \-xx
  1231. .TQ
  1232. .BR \-\-strings\-in\-hex [= all ]
  1233. Print all strings in hexadecimal string format.
  1234. .TP
  1235. .BI "\-X " format
  1236. .TQ
  1237. .BR "\-\-const\-print\-style" = \fIformat\fR
  1238. Set the format for printing of named constants and flags.
  1239. Supported
  1240. .I format
  1241. values are:
  1242. .RS
  1243. .TP 10
  1244. .B raw
  1245. Raw number output, without decoding.
  1246. .TQ
  1247. .B abbrev
  1248. Output a named constant or a set of flags instead of the raw number if they are
  1249. found.
  1250. This is the default
  1251. .B strace
  1252. behaviour.
  1253. .TQ
  1254. .B verbose
  1255. Output both the raw value and the decoded string (as a comment).
  1256. .RE
  1257. .TP
  1258. .B \-y
  1259. .TQ
  1260. .B \-\-decode\-fds
  1261. .TQ
  1262. .BR \-\-decode\-fds = path
  1263. Print paths associated with file descriptor arguments and with the
  1264. .B AT_FDCWD
  1265. constant.
  1266. .TP
  1267. .B \-yy
  1268. .TQ
  1269. .BR \-\-decode\-fds = all
  1270. Print all available information associated with file descriptors:
  1271. protocol-specific information associated with socket file descriptors,
  1272. block/character device number associated with device file descriptors,
  1273. and PIDs associated with pidfd file descriptors.
  1274. .TP
  1275. .B \-\-pidns\-translation
  1276. .TQ
  1277. .BR \-\-decode\-pids = pidns
  1278. If strace and tracee are in different PID namespaces, print PIDs in
  1279. strace's namespace, too.
  1280. .TP
  1281. .B \-Y
  1282. .TQ
  1283. .BR \-\-decode\-pids = comm
  1284. Print command names for PIDs.
  1285. .if ''#' .TP
  1286. .if ''#' .BR \-\-secontext\fR[=\fIformat\fR]
  1287. .if ''#' .TQ
  1288. .if ''#' .BR \-e\ secontext\fR=\fIformat\fR
  1289. .if ''#' When SELinux is available and is not disabled,
  1290. .if ''#' print in square brackets SELinux contexts of
  1291. .if ''#' processes, files, and descriptors. The
  1292. .if ''#' .I format
  1293. .if ''#' argument is a comma-separated list of items
  1294. .if ''#' being one of the following:
  1295. .if ''#' .RS
  1296. .if ''#' .TP 18
  1297. .if ''#' .BR full
  1298. .if ''#' Print the full context (user, role, type level
  1299. .if ''#' and category).
  1300. .if ''#' .TQ
  1301. .if ''#' .BR mismatch
  1302. .if ''#' Also print the context recorded by the SELinux
  1303. .if ''#' database in case the current context differs.
  1304. .if ''#' The latter is printed after two exclamation marks (!!).
  1305. .if ''#' .RE
  1306. .if ''#' .IP
  1307. .if ''#' The default value for
  1308. .if ''#' .BR \-\-secontext
  1309. .if ''#' is
  1310. .if ''#' .BR !full,mismatch
  1311. .if ''#' which prints only the type instead of full context
  1312. .if ''#' and doesn't check for context mismatches.
  1313. .TP
  1314. .B \-\-always\-show\-pid
  1315. Show PID prefix also for the process started by strace.
  1316. Implied when \-f and \-o are both specified.
  1317. .RE
  1318. .SS Statistics
  1319. .TP 12
  1320. .B \-c
  1321. .TQ
  1322. .B \-\-summary\-only
  1323. Count time, calls, and errors for each system call and report a summary on
  1324. program exit, suppressing the regular output.
  1325. This attempts to show system time (CPU time spent running
  1326. in the kernel) independent of wall clock time. If
  1327. .B \-c
  1328. is used with
  1329. .BR \-f ,
  1330. only aggregate totals for all traced processes are kept.
  1331. .TP
  1332. .B \-C
  1333. .TQ
  1334. .B \-\-summary
  1335. Like
  1336. .B \-c
  1337. but also print regular output while processes are running.
  1338. .TP
  1339. .BI "\-O " overhead
  1340. .TQ
  1341. .BR "\-\-summary\-syscall\-overhead" = \fIoverhead\fR
  1342. Set the overhead for tracing system calls to
  1343. .IR overhead .
  1344. This is useful for overriding the default heuristic for guessing
  1345. how much time is spent in mere measuring when timing system calls using
  1346. the
  1347. .B \-c
  1348. option. The accuracy of the heuristic can be gauged by timing a given
  1349. program run without tracing (using
  1350. .BR time (1))
  1351. and comparing the accumulated
  1352. system call time to the total produced using
  1353. .BR \-c .
  1354. .IP
  1355. The format of
  1356. .I overhead
  1357. specification is described in section
  1358. .IR "Time specification format description".
  1359. .TP
  1360. .BI "\-S " sortby
  1361. .TQ
  1362. .BR "\-\-summary\-sort\-by" = \fIsortby\fR
  1363. Sort the output of the histogram printed by the
  1364. .B \-c
  1365. option by the specified criterion. Legal values are
  1366. .BR time " (or " time\-percent " or " time\-total " or " total\-time ),
  1367. .BR min\-time " (or " shortest " or " time\-min ),
  1368. .BR max\-time " (or " longest " or " time\-max ),
  1369. .BR avg\-time " (or " time\-avg ),
  1370. .BR calls " (or " count ),
  1371. .BR errors " (or " error ),
  1372. .BR name " (or " syscall " or " syscall\-name ),
  1373. and
  1374. .BR nothing " (or " none );
  1375. default is
  1376. .BR time .
  1377. .TP
  1378. .BI "\-U " columns
  1379. .TQ
  1380. .BR "\-\-summary\-columns" = \fIcolumns\fR
  1381. Configure a set (and order) of columns being shown in the call summary.
  1382. The
  1383. .I columns
  1384. argument is a comma-separated list with items being one of the following:
  1385. .RS
  1386. .TP 36
  1387. .BR time\-percent " (or " time )
  1388. Percentage of cumulative time consumed by a specific system call.
  1389. .TQ
  1390. .BR total\-time " (or " time\-total )
  1391. Total system (or wall clock, if
  1392. .B \-w
  1393. option is provided) time consumed by a specific system call.
  1394. .TQ
  1395. .BR min\-time " (or " shortest " or " time\-min )
  1396. Minimum observed call duration.
  1397. .TQ
  1398. .BR max\-time " (or " longest " or " time\-max )
  1399. Maximum observed call duration.
  1400. .TQ
  1401. .BR avg\-time " (or " time\-avg )
  1402. Average call duration.
  1403. .TQ
  1404. .BR calls " (or " count )
  1405. Call count.
  1406. .TQ
  1407. .BR errors " (or " error )
  1408. Error count.
  1409. .TQ
  1410. .BR name " (or " syscall " or " syscall\-name )
  1411. Syscall name.
  1412. .RE
  1413. .IP
  1414. The default value is
  1415. .BR time\-percent , total\-time , avg\-time , calls , errors , name .
  1416. If the
  1417. .B name
  1418. field is not supplied explicitly, it is added as the last column.
  1419. .TP
  1420. .B \-w
  1421. .TQ
  1422. .B \-\-summary\-wall\-clock
  1423. Summarise the time difference between the beginning and end of
  1424. each system call. The default is to summarise the system time.
  1425. .SS Tampering
  1426. .ad l
  1427. .TP 12
  1428. \fB\-e\ inject\fR=\,\fIsyscall_set\/\fR[:\fBerror\fR=\,\fIerrno\/\fR|:\fBretval\fR=\,\fIvalue\/\fR]\:[:\fBsignal\fR=\,\fIsig\/\fR]\:[:\fBsyscall\fR=\,\fIsyscall\/\fR]\:[:\fBdelay_enter\fR=\,\fIdelay\/\fR]\:[:\fBdelay_exit\fR=\,\fIdelay\/\fR]\:[:\fBpoke_enter\fR=\,\fI@argN=DATAN,@argM=DATAM...\/\fR]\:[:\fBpoke_exit\fR=\,\fI@argN=DATAN,@argM=DATAM...\/\fR]\:[:\fBwhen\fR=\,\fIexpr\/\fR] \{
  1429. .TQ
  1430. \fB\-\-inject\fR=\,\fIsyscall_set\/\fR[:\fBerror\fR=\,\fIerrno\/\fR|:\fBretval\fR=\,\fIvalue\/\fR]\:[:\fBsignal\fR=\,\fIsig\/\fR]\:[:\fBsyscall\fR=\,\fIsyscall\/\fR]\:[:\fBdelay_enter\fR=\,\fIdelay\/\fR]\:[:\fBdelay_exit\fR=\,\fIdelay\/\fR]\:[:\fBpoke_enter\fR=\,\fI@argN=DATAN,@argM=DATAM...\/\fR]\:[:\fBpoke_exit\fR=\,\fI@argN=DATAN,@argM=DATAM...\/\fR]\:[:\fBwhen\fR=\,\fIexpr\/\fR] \{
  1431. .ad b
  1432. Perform syscall tampering for the specified set of syscalls.
  1433. The syntax of the
  1434. .I syscall_set
  1435. specification is the same as in the
  1436. .B "-e trace"
  1437. option.
  1438. .IP
  1439. At least one of
  1440. .BR error ,
  1441. .BR retval ,
  1442. .BR signal ,
  1443. .BR delay_enter ,
  1444. .BR delay_exit ,
  1445. .BR poke_enter ,
  1446. or
  1447. .B poke_exit
  1448. options has to be specified.
  1449. .B error
  1450. and
  1451. .B retval
  1452. are mutually exclusive.
  1453. .IP
  1454. If :\fBerror\fR=\,\fIerrno\/\fR option is specified,
  1455. a fault is injected into a syscall invocation:
  1456. the syscall number is replaced by -1 which corresponds to an invalid syscall
  1457. (unless a syscall is specified with :\fBsyscall=\fR option),
  1458. and the error code is specified using a symbolic
  1459. .I errno
  1460. value like
  1461. .B ENOSYS
  1462. or a numeric value within 1..4095 range.
  1463. .IP
  1464. If :\fBretval\fR=\,\fIvalue\/\fR option is specified,
  1465. success injection is performed: the syscall number is replaced by -1,
  1466. but a bogus success value is returned to the callee.
  1467. .IP
  1468. If :\fBsignal\fR=\,\fIsig\/\fR option is specified with either a symbolic value
  1469. like
  1470. .B SIGSEGV
  1471. or a numeric value within 1..\fBSIGRTMAX\fR range,
  1472. that signal is delivered on entering every syscall specified by the
  1473. .IR set .
  1474. .IP
  1475. If :\fBdelay_enter\fR=\,\fIdelay\/\fR or :\fBdelay_exit\fR=\,\fIdelay\/\fR
  1476. options are specified, delay injection is performed: the tracee is delayed
  1477. by time period specified by
  1478. .IR delay
  1479. on entering or exiting the syscall, respectively.
  1480. The format of
  1481. .I delay
  1482. specification is described in section
  1483. .IR "Time specification format description".
  1484. .IP
  1485. If :\fBpoke_enter\fR=\fI@argN=DATAN,@argM=DATAM...\fR
  1486. or :\fBpoke_exit\fR=\fI@argN=DATAN,@argM=DATAM...\fR options are specified,
  1487. tracee's memory at locations, pointed to by system call arguments
  1488. .IR argN
  1489. and
  1490. .IR argM
  1491. (going from
  1492. .IR arg1
  1493. to
  1494. .IR arg7 )
  1495. is overwritten by data
  1496. .IR DATAN
  1497. and
  1498. .IR DATAM
  1499. (specified in hexadecimal format; for example :\fBpoke_enter\fR=\fI@arg1=0000DEAD0000BEEF\fR).
  1500. :\fBpoke_enter\fR modifies memory on syscall enter, and :\fBpoke_exit\fR - on exit.
  1501. .IP
  1502. If :\fBsignal\fR=\,\fIsig\/\fR option is specified without
  1503. :\fBerror\fR=\,\fIerrno\/\fR, :\fBretval\fR=\,\fIvalue\/\fR or
  1504. :\fBdelay_{enter,exit}\fR=\,\fIusecs\/\fR options,
  1505. then only a signal
  1506. .I sig
  1507. is delivered without a syscall fault or delay injection.
  1508. Conversely, :\fBerror\fR=\,\fIerrno\/\fR or
  1509. :\fBretval\fR=\,\fIvalue\/\fR option without
  1510. :\fBdelay_enter\fR=\,\fIdelay\/\fR,
  1511. :\fBdelay_exit\fR=\,\fIdelay\/\fR or
  1512. :\fBsignal\fR=\,\fIsig\/\fR options injects a fault without delivering a signal
  1513. or injecting a delay, etc.
  1514. .IP
  1515. If
  1516. :\fBsignal\fR=\,\fIsig\/\fR
  1517. option is specified together with
  1518. :\fBerror\fR=\,\fIerrno\/\fR or :\fBretval\fR=\,\fIvalue\/\fR,
  1519. then both injection of a fault or success and signal delivery are performed.
  1520. .IP
  1521. if :\fBsyscall\fR=\fIsyscall\fR option is specified, the corresponding syscall
  1522. with no side effects is injected instead of -1.
  1523. Currently, only "pure" (see
  1524. .BR "-e trace" = "%pure"
  1525. description) syscalls can be specified there.
  1526. .IP
  1527. Unless a :\fBwhen\fR=\,\fIexpr\fR subexpression is specified,
  1528. an injection is being made into every invocation of each syscall from the
  1529. .IR set .
  1530. .IP
  1531. The format of the subexpression is:
  1532. .RS 15
  1533. .IP
  1534. \fIfirst\/\fR[\fB..\fR\,\fIlast\/\fR][\fB+\fR[\,\fIstep\/\fR]]
  1535. .RE
  1536. .IP
  1537. Number
  1538. .I first
  1539. stands for the first invocation number in the range, number
  1540. .I last
  1541. stands for the last invocation number in the range, and
  1542. .I step
  1543. stands for the step between two consecutive invocations.
  1544. The following combinations are useful:
  1545. .RS
  1546. .TP 18
  1547. .I first
  1548. For every syscall from the
  1549. .IR set ,
  1550. perform an injection for the syscall invocation number
  1551. .I first
  1552. only.
  1553. .TQ
  1554. \fIfirst\/\fB..\fR\,\fIlast\fR
  1555. For every syscall from the
  1556. .IR set ,
  1557. perform an injection for the syscall invocation number
  1558. .I first
  1559. and all subsequent invocations until the invocation number
  1560. .I last
  1561. (inclusive).
  1562. .TQ
  1563. \fIfirst\/\fB+\fR
  1564. For every syscall from the
  1565. .IR set ,
  1566. perform injections for the syscall invocation number
  1567. .I first
  1568. and all subsequent invocations.
  1569. .TQ
  1570. \fIfirst\/\fB..\fR\,\fIlast\/\fB+\fR
  1571. For every syscall from the
  1572. .IR set ,
  1573. perform injections for the syscall invocation number
  1574. .I first
  1575. and all subsequent invocations until the invocation number
  1576. .I last
  1577. (inclusive).
  1578. .TQ
  1579. \fIfirst\/\fB+\fR\,\fIstep\fR
  1580. For every syscall from the
  1581. .IR set ,
  1582. perform injections for syscall invocations number
  1583. .IR first ,
  1584. .IR first + step ,
  1585. .IR first + step + step ,
  1586. and so on.
  1587. .TQ
  1588. \fIfirst\/\fB..\fR\,\fIlast\fB+\fR\,\fIstep\fR
  1589. Same as the previous, but consider only syscall invocations with numbers up to
  1590. .I last
  1591. (inclusive).
  1592. .RE
  1593. .IP
  1594. For example, to fail each third and subsequent chdir syscalls with
  1595. .BR ENOENT ,
  1596. use
  1597. \fB\-e\ inject\fR=\,\fIchdir\/\fR:\fBerror\fR=\,\fIENOENT\/\fR:\fBwhen\fR=\,\fI3\/\fB+\fR.
  1598. .IP
  1599. The valid range for numbers
  1600. .I first
  1601. and
  1602. .I step
  1603. is 1..65535, and for number
  1604. .I last
  1605. is 1..65534.
  1606. .IP
  1607. An injection expression can contain only one
  1608. .BR error =
  1609. or
  1610. .BR retval =
  1611. specification, and only one
  1612. .BR signal =
  1613. specification. If an injection expression contains multiple
  1614. .BR when =
  1615. specifications, the last one takes precedence.
  1616. .IP
  1617. Accounting of syscalls that are subject to injection
  1618. is done per syscall and per tracee.
  1619. .IP
  1620. Specification of syscall injection can be combined
  1621. with other syscall filtering options, for example,
  1622. \fB\-P \fI/dev/urandom \fB\-e inject\fR=\,\fIfile\/\fR:\fBerror\fR=\,\fIENOENT\fR.
  1623. .TP
  1624. \fB\-e\ fault\fR=\,\fIsyscall_set\/\fR[:\fBerror\fR=\,\fIerrno\/\fR][:\fBwhen\fR=\,\fIexpr\/\fR]
  1625. .TQ
  1626. \fB\-\-fault\fR=\,\fIsyscall_set\/\fR[:\fBerror\fR=\,\fIerrno\/\fR][:\fBwhen\fR=\,\fIexpr\/\fR]
  1627. Perform syscall fault injection for the specified set of syscalls.
  1628. .IP
  1629. This is equivalent to more generic
  1630. \fB\-e\ inject\fR= expression with default value of
  1631. .I errno
  1632. option set to
  1633. .BR ENOSYS .
  1634. .SS Miscellaneous
  1635. .TP 12
  1636. .B \-d
  1637. .TQ
  1638. .B \-\-debug
  1639. Show some debugging output of
  1640. .B strace
  1641. itself on the standard error.
  1642. .TP
  1643. .B \-F
  1644. This option is deprecated. It is retained for backward compatibility only
  1645. and may be removed in future releases.
  1646. Usage of multiple instances of
  1647. .B \-F
  1648. option is still equivalent to a single
  1649. .BR \-f ,
  1650. and it is ignored at all if used along with one or more instances of
  1651. .B \-f
  1652. option.
  1653. .TP
  1654. .B \-h
  1655. .TQ
  1656. .B \-\-help
  1657. Print the help summary.
  1658. .TP
  1659. .B \-\-seccomp\-bpf
  1660. Try to enable use of seccomp-bpf (see
  1661. .BR seccomp (2))
  1662. to have
  1663. .BR ptrace (2)-stops
  1664. only when system calls that are being traced occur in the traced processes.
  1665. .IP
  1666. This option has no effect unless
  1667. .BR \-f / \-\-follow\-forks
  1668. is also specified.
  1669. .B \-\-seccomp\-bpf
  1670. is not compatible with
  1671. .B \-\-syscall\-limit
  1672. and
  1673. .BR \-b / \-\-detach\-on
  1674. options. It is also not applicable to processes attached using
  1675. .BR \-p / \-\-attach
  1676. option.
  1677. .IP
  1678. An attempt to enable system calls filtering using seccomp-bpf may
  1679. fail for various reasons, e.g. there are too many system calls to filter,
  1680. the seccomp API is not available, or
  1681. .B strace
  1682. itself is being traced.
  1683. In cases when seccomp-bpf filter setup failed,
  1684. .B strace
  1685. proceeds as usual and stops traced processes on every system call.
  1686. .IP
  1687. When
  1688. .B \-\-seccomp\-bpf
  1689. is activated and
  1690. .BR \-p / \-\-attach
  1691. option is not used,
  1692. .B \-\-kill\-on\-exit
  1693. option is activated as well.
  1694. .IP
  1695. Note that in cases when the tracee has another seccomp filter that
  1696. returns an action value with a precedence greater than
  1697. .BR SECCOMP_RET_TRACE ,
  1698. .B strace \-\-seccomp\-bpf
  1699. will not be notified. That is, if another seccomp filter, for example,
  1700. disables the syscall or kills the tracee, then
  1701. .B strace \-\-seccomp\-bpf
  1702. will not be aware of that syscall invocation at all.
  1703. .TP
  1704. .BR \-\-tips [=[[ id: ] \fIid\fR ],[[ format: ] \fIformat\fR ]]
  1705. Show strace tips, tricks, and tweaks before exit.
  1706. .I id
  1707. can be a non-negative integer number,
  1708. which enables printing of specific tip, trick, or tweak
  1709. (these ID are not guaranteed to be stable),
  1710. or
  1711. .B random
  1712. (the default),
  1713. in which case a random tip is printed.
  1714. .I format
  1715. can be one of the following:
  1716. .RS
  1717. .TP 9
  1718. .B none
  1719. No tip is printed.
  1720. Can be used to override the previous setting.
  1721. .TQ
  1722. .B compact
  1723. Print the tip just big enough to contain all the text.
  1724. .TQ
  1725. .B full
  1726. Print the tip in its full glory.
  1727. .RE
  1728. .IP
  1729. Default is
  1730. .BR id:random,format:compact .
  1731. .TP
  1732. .B \-V
  1733. .TQ
  1734. .B \-\-version
  1735. Print the version number of
  1736. .BR strace .
  1737. Multiple instances of the option beyond specific threshold tend to increase
  1738. Strauss awareness.
  1739. .SS "Time specification format description"
  1740. .PP
  1741. Time values can be specified as a decimal floating point number
  1742. (in a format accepted by
  1743. .BR strtod (3)),
  1744. optionally followed by one of the following suffices that specify
  1745. the unit of time:
  1746. .B s
  1747. (seconds),
  1748. .B ms
  1749. (milliseconds),
  1750. .B us
  1751. (microseconds), or
  1752. .B ns
  1753. (nanoseconds).
  1754. If no suffix is specified, the value is interpreted as microseconds.
  1755. .PP
  1756. The described format is used for
  1757. .BR \-O ", " "\-e inject" = delay_enter ", and " "\-e inject" = delay_exit
  1758. options.
  1759. .SH DIAGNOSTICS
  1760. When
  1761. .I command
  1762. exits,
  1763. .B strace
  1764. exits with the same exit status.
  1765. If
  1766. .I command
  1767. is terminated by a signal,
  1768. .B strace
  1769. terminates itself with the same signal, so that
  1770. .B strace
  1771. can be used as a wrapper process transparent to the invoking parent process.
  1772. Note that parent-child relationship (signal stop notifications,
  1773. .BR getppid (2)
  1774. value, etc) between traced process and its parent are not preserved
  1775. unless
  1776. .B \-D
  1777. is used.
  1778. .LP
  1779. When using
  1780. .B \-p
  1781. without a
  1782. .IR command ,
  1783. the exit status of
  1784. .B strace
  1785. is zero unless no processes has been attached or there was an unexpected error
  1786. in doing the tracing.
  1787. .SH "SETUID INSTALLATION"
  1788. If
  1789. .B strace
  1790. is installed setuid to root then the invoking user will be able to
  1791. attach to and trace processes owned by any user.
  1792. In addition setuid and setgid programs will be executed and traced
  1793. with the correct effective privileges.
  1794. Since only users trusted with full root privileges should be allowed
  1795. to do these things,
  1796. it only makes sense to install
  1797. .B strace
  1798. as setuid to root when the users who can execute it are restricted
  1799. to those users who have this trust.
  1800. For example, it makes sense to install a special version of
  1801. .B strace
  1802. with mode 'rwsr-xr--', user
  1803. .B root
  1804. and group
  1805. .BR trace ,
  1806. where members of the
  1807. .B trace
  1808. group are trusted users.
  1809. If you do use this feature, please remember to install
  1810. a regular non-setuid version of
  1811. .B strace
  1812. for ordinary users to use.
  1813. .SH "MULTIPLE PERSONALITIES SUPPORT"
  1814. On some architectures,
  1815. .B strace
  1816. supports decoding of syscalls for processes that use different ABI rather than
  1817. the one
  1818. .B strace
  1819. uses.
  1820. Specifically, in addition to decoding native ABI,
  1821. .B strace
  1822. can decode the following ABIs on the following architectures:
  1823. .TS H
  1824. allbox;
  1825. lb lb
  1826. l l.
  1827. Architecture ABIs supported
  1828. x86_64 i386, x32 [1]; i386 [2]
  1829. AArch64 ARM 32-bit EABI
  1830. PowerPC 64-bit [3] PowerPC 32-bit
  1831. s390x s390
  1832. SPARC 64-bit SPARC 32-bit
  1833. TILE 64-bit TILE 32-bit
  1834. .TE
  1835. .RS 0
  1836. .TP 5
  1837. [1]
  1838. When
  1839. .B strace
  1840. is built as an x86_64 application
  1841. .TQ
  1842. [2]
  1843. When
  1844. .B strace
  1845. is built as an x32 application
  1846. .TQ
  1847. [3]
  1848. Big endian only
  1849. .RE
  1850. .PP
  1851. This support is optional and relies on ability to generate and parse structure
  1852. definitions during the build time.
  1853. Please refer to the output of the
  1854. .B strace \-V
  1855. command in order to figure out what support is available in your
  1856. .B strace
  1857. build ("non-native" refers to an ABI that differs from the ABI
  1858. .B strace
  1859. has):
  1860. .TP 15
  1861. .B m32-mpers
  1862. .B strace
  1863. can trace and properly decode non-native 32-bit binaries.
  1864. .TQ
  1865. .B no-m32-mpers
  1866. .B strace
  1867. can trace, but cannot properly decode non-native 32-bit binaries.
  1868. .TQ
  1869. .B mx32-mpers
  1870. .B strace
  1871. can trace and properly decode non-native 32-on-64-bit binaries.
  1872. .TQ
  1873. .B no-mx32-mpers
  1874. .B strace
  1875. can trace, but cannot properly decode non-native 32-on-64-bit binaries.
  1876. .PP
  1877. If the output contains neither
  1878. .B m32-mpers
  1879. nor
  1880. .BR no-m32-mpers ,
  1881. then decoding of non-native 32-bit binaries is not implemented at all
  1882. or not applicable.
  1883. .PP
  1884. Likewise, if the output contains neither
  1885. .B mx32-mpers
  1886. nor
  1887. .BR no-mx32-mpers ,
  1888. then decoding of non-native 32-on-64-bit binaries is not implemented at all
  1889. or not applicable.
  1890. .SH NOTES
  1891. It is a pity that so much tracing clutter is produced by systems
  1892. employing shared libraries.
  1893. .LP
  1894. It is instructive to think about system call inputs and outputs
  1895. as data-flow across the user/kernel boundary. Because user-space
  1896. and kernel-space are separate and address-protected, it is
  1897. sometimes possible to make deductive inferences about process
  1898. behavior using inputs and outputs as propositions.
  1899. .LP
  1900. In some cases, a system call will differ from the documented behavior
  1901. or have a different name. For example, the
  1902. .BR faccessat (2)
  1903. system call does not have
  1904. .I flags
  1905. argument, and the
  1906. .BR setrlimit (2)
  1907. library function uses
  1908. .BR prlimit64 (2)
  1909. system call on modern (2.6.38+) kernels. These
  1910. discrepancies are normal but idiosyncratic characteristics of the
  1911. system call interface and are accounted for by C library wrapper
  1912. functions.
  1913. .LP
  1914. Some system calls have different names in different architectures and
  1915. personalities. In these cases, system call filtering and printing
  1916. uses the names that match corresponding
  1917. .BR __NR_ *
  1918. kernel macros of the tracee's architecture and personality.
  1919. There are two exceptions from this general rule:
  1920. .BR arm_fadvise64_64 (2)
  1921. ARM syscall and
  1922. .BR xtensa_fadvise64_64 (2)
  1923. Xtensa syscall are filtered and printed as
  1924. .BR fadvise64_64 (2).
  1925. .LP
  1926. On x32, syscalls that are intended to be used by 64-bit processes and not x32
  1927. ones (for example,
  1928. .BR readv (2),
  1929. that has syscall number 19 on x86_64, with its x32 counterpart has syscall
  1930. number 515), but called with
  1931. .B __X32_SYSCALL_BIT
  1932. flag being set, are designated with
  1933. .B "#64"
  1934. suffix.
  1935. .LP
  1936. On some platforms a process that is attached to with the
  1937. .B \-p
  1938. option may observe a spurious
  1939. .B EINTR
  1940. return from the current system call that is not restartable.
  1941. (Ideally, all system calls should be restarted on
  1942. .B strace
  1943. attach, making the attach invisible
  1944. to the traced process, but a few system calls aren't.
  1945. Arguably, every instance of such behavior is a kernel bug.)
  1946. This may have an unpredictable effect on the process
  1947. if the process takes no action to restart the system call.
  1948. .LP
  1949. As
  1950. .B strace
  1951. executes the specified
  1952. .I command
  1953. directly and does not employ a shell for that, scripts without shebang
  1954. that usually run just fine when invoked by shell fail to execute with
  1955. .B ENOEXEC
  1956. error.
  1957. It is advisable to manually supply a shell as a
  1958. .I command
  1959. with the script as its argument.
  1960. .SH BUGS
  1961. Programs that use the
  1962. .I setuid
  1963. bit do not have
  1964. effective user
  1965. .SM ID
  1966. privileges while being traced.
  1967. .LP
  1968. A traced process runs slowly (but check out the
  1969. .B \-\-seccomp\-bpf
  1970. option).
  1971. .LP
  1972. Unless
  1973. .B \-\-kill\-on\-exit
  1974. option is used (or
  1975. .B \-\-seccomp\-bpf
  1976. option is used in a way that implies
  1977. .BR \-\-kill\-on\-exit ),
  1978. traced processes which are descended from
  1979. .I command
  1980. may be left running after an interrupt signal
  1981. .RB ( CTRL\-C ).
  1982. .LP
  1983. By using
  1984. .B CLONE_UNTRACED
  1985. flag of
  1986. .B clone
  1987. system call a tracee can break the guarantee that
  1988. .B \-\-seccomp\-bpf
  1989. will not leave any processes with a seccomp program installed
  1990. for syscall filtering purposes.
  1991. .SH HISTORY
  1992. The original
  1993. .B strace
  1994. was written by Paul Kranenburg
  1995. for SunOS and was inspired by its
  1996. .B trace
  1997. utility.
  1998. The SunOS version of
  1999. .B strace
  2000. was ported to Linux and enhanced
  2001. by Branko Lankester, who also wrote the Linux kernel support.
  2002. Even though Paul released
  2003. .B strace
  2004. 2.5 in 1992,
  2005. Branko's work was based on Paul's
  2006. .B strace
  2007. 1.5 release from 1991.
  2008. In 1993, Rick Sladkey merged
  2009. .B strace
  2010. 2.5 for SunOS and the second release of
  2011. .B strace
  2012. for Linux, added many of the features of
  2013. .BR truss (1)
  2014. from SVR4, and produced an
  2015. .B strace
  2016. that worked on both platforms. In 1994 Rick ported
  2017. .B strace
  2018. to SVR4 and Solaris and wrote the
  2019. automatic configuration support. In 1995 he ported
  2020. .B strace
  2021. to Irix
  2022. and became tired of writing about himself in the third person.
  2023. .PP
  2024. Beginning with 1996,
  2025. .B strace
  2026. was maintained by Wichert Akkerman.
  2027. During his tenure,
  2028. .B strace
  2029. development migrated to CVS; ports to FreeBSD and many architectures on Linux
  2030. (including ARM, IA-64, MIPS, PA-RISC, PowerPC, s390, SPARC) were introduced.
  2031. In 2002, the burden of
  2032. .B strace
  2033. maintainership was transferred to Roland McGrath.
  2034. Since then,
  2035. .B strace
  2036. gained support for several new Linux architectures (AMD64, s390x, SuperH),
  2037. bi-architecture support for some of them, and received numerous additions and
  2038. improvements in syscalls decoders on Linux;
  2039. .B strace
  2040. development migrated to
  2041. .B Git
  2042. during that period.
  2043. Since 2009,
  2044. .B strace
  2045. is actively maintained by Dmitry Levin.
  2046. .B strace
  2047. gained support for AArch64, ARC, AVR32, Blackfin, Meta, Nios II, OpenRISC 1000,
  2048. RISC-V, Tile/TileGx, Xtensa architectures since that time.
  2049. In 2012, unmaintained and apparently broken support for non-Linux operating
  2050. systems was removed.
  2051. Also, in 2012
  2052. .B strace
  2053. gained support for path tracing and file descriptor path decoding.
  2054. In 2014, support for stack trace printing was added.
  2055. In 2016, syscall fault injection was implemented.
  2056. .PP
  2057. For the additional information, please refer to the
  2058. .B NEWS
  2059. file and
  2060. .B strace
  2061. repository commit log.
  2062. .SH REPORTING BUGS
  2063. Problems with
  2064. .B strace
  2065. should be reported to the
  2066. .UR mailto:strace\-devel@lists.strace.io
  2067. .B strace
  2068. mailing list
  2069. .UE .
  2070. .SH "SEE ALSO"
  2071. .BR strace-log-merge (1),
  2072. .BR ltrace (1),
  2073. .BR perf-trace (1),
  2074. .BR trace-cmd (1),
  2075. .BR time (1),
  2076. .BR ptrace (2),
  2077. .BR seccomp (2),
  2078. .BR syscall (2),
  2079. .BR proc (5),
  2080. .BR signal (7)
  2081. .PP
  2082. .UR https://strace.io/
  2083. .B strace
  2084. Home Page
  2085. .UE
  2086. .SH AUTHORS
  2087. The complete list of
  2088. .B strace
  2089. contributors can be found in the
  2090. .B CREDITS
  2091. file.