Mirror of strace – the linux syscall tracer
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

strace.1.in 37KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371
  1. .\" Copyright (c) 1991, 1992 Paul Kranenburg <pk@cs.few.eur.nl>
  2. .\" Copyright (c) 1993 Branko Lankester <branko@hacktic.nl>
  3. .\" Copyright (c) 1993, 1994, 1995, 1996 Rick Sladkey <jrs@world.std.com>
  4. .\" Copyright (c) 1996-2017 The strace developers.
  5. .\" All rights reserved.
  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 "@MANPAGE_DATE@" "strace @VERSION@"
  37. .SH NAME
  38. strace \- trace system calls and signals
  39. .SH SYNOPSIS
  40. .SY strace
  41. .if '@ENABLE_STACKTRACE_FALSE@'#' .OP \-ACdffhikqqrtttTvVwxxyyzZ
  42. .if '@ENABLE_STACKTRACE_TRUE@'#' .OP \-ACdffhiqqrtttTvVwxxyyzZ
  43. .OP \-I n
  44. .OP \-b execve
  45. .OM \-e expr
  46. .OP \-a column
  47. .OP \-o file
  48. .OP \-s strsize
  49. .OP \-X format
  50. .OM \-P path
  51. .OM \-p pid
  52. .OP \-\-seccomp\-bpf
  53. .BR "" {
  54. .OR \-p pid
  55. .BR "" |
  56. .OP \-DDD
  57. .OM \-E var\fR[=\fIval\fR]
  58. .OP \-u username
  59. .IR command " [" args ]
  60. .BR "" }
  61. .YS
  62. .SY strace
  63. .B \-c
  64. .OP \-dfwzZ
  65. .OP \-I n
  66. .OP \-b execve
  67. .OM \-e expr
  68. .OP \-O overhead
  69. .OP \-S sortby
  70. .OM \-P path
  71. .OM \-p pid
  72. .OP \-\-seccomp\-bpf
  73. .BR "" {
  74. .OR \-p pid
  75. .BR "" |
  76. .OP \-DDD
  77. .OM \-E var\fR[=\fIval\fR]
  78. .OP -u username
  79. .IR command " [" args ]
  80. .BR "" }
  81. .YS
  82. .SH DESCRIPTION
  83. .IX "strace command" "" "\fLstrace\fR command"
  84. .LP
  85. In the simplest case
  86. .B strace
  87. runs the specified
  88. .I command
  89. until it exits.
  90. It intercepts and records the system calls which are called
  91. by a process and the signals which are received by a process.
  92. The name of each system call, its arguments and its return value
  93. are printed on standard error or to the file specified with the
  94. .B \-o
  95. option.
  96. .LP
  97. .B strace
  98. is a useful diagnostic, instructional, and debugging tool.
  99. System administrators, diagnosticians and trouble-shooters will find
  100. it invaluable for solving problems with
  101. programs for which the source is not readily available since
  102. they do not need to be recompiled in order to trace them.
  103. Students, hackers and the overly-curious will find that
  104. a great deal can be learned about a system and its system calls by
  105. tracing even ordinary programs. And programmers will find that
  106. since system calls and signals are events that happen at the user/kernel
  107. interface, a close examination of this boundary is very
  108. useful for bug isolation, sanity checking and
  109. attempting to capture race conditions.
  110. .LP
  111. Each line in the trace contains the system call name, followed
  112. by its arguments in parentheses and its return value.
  113. An example from stracing the command "cat /dev/null" is:
  114. .CW
  115. open("/dev/null", O_RDONLY) = 3
  116. .CE
  117. Errors (typically a return value of \-1) have the errno symbol
  118. and error string appended.
  119. .CW
  120. open("/foo/bar", O_RDONLY) = \-1 ENOENT (No such file or directory)
  121. .CE
  122. Signals are printed as signal symbol and decoded siginfo structure.
  123. An excerpt from stracing and interrupting the command "sleep 666" is:
  124. .CW
  125. sigsuspend([] <unfinished ...>
  126. --- SIGINT {si_signo=SIGINT, si_code=SI_USER, si_pid=...} ---
  127. +++ killed by SIGINT +++
  128. .CE
  129. If a system call is being executed and meanwhile another one is being called
  130. from a different thread/process then
  131. .B strace
  132. will try to preserve the order of those events and mark the ongoing call as
  133. being
  134. .IR unfinished .
  135. When the call returns it will be marked as
  136. .IR resumed .
  137. .CW
  138. [pid 28772] select(4, [3], NULL, NULL, NULL <unfinished ...>
  139. [pid 28779] clock_gettime(CLOCK_REALTIME, {1130322148, 939977000}) = 0
  140. [pid 28772] <... select resumed> ) = 1 (in [3])
  141. .CE
  142. Interruption of a (restartable) system call by a signal delivery is processed
  143. differently as kernel terminates the system call and also arranges its
  144. immediate reexecution after the signal handler completes.
  145. .CW
  146. read(0, 0x7ffff72cf5cf, 1) = ? ERESTARTSYS (To be restarted)
  147. --- SIGALRM ... ---
  148. rt_sigreturn(0xe) = 0
  149. read(0, "", 1) = 0
  150. .CE
  151. Arguments are printed in symbolic form with passion.
  152. This example shows the shell performing ">>xyzzy" output redirection:
  153. .CW
  154. open("xyzzy", O_WRONLY|O_APPEND|O_CREAT, 0666) = 3
  155. .CE
  156. Here, the third argument of
  157. .BR open (2)
  158. is decoded by breaking down the
  159. flag argument into its three bitwise-OR constituents and printing the
  160. mode value in octal by tradition. Where the traditional or native
  161. usage differs from ANSI or POSIX, the latter forms are preferred.
  162. In some cases,
  163. .B strace
  164. output is proven to be more readable than the source.
  165. .LP
  166. Structure pointers are dereferenced and the members are displayed
  167. as appropriate. In most cases, arguments are formatted in the most C-like
  168. fashion possible.
  169. For example, the essence of the command "ls \-l /dev/null" is captured as:
  170. .CW
  171. lstat("/dev/null", {st_mode=S_IFCHR|0666, st_rdev=makedev(0x1, 0x3), ...}) = 0
  172. .CE
  173. Notice how the 'struct stat' argument is dereferenced and how each member is
  174. displayed symbolically. In particular, observe how the
  175. .B st_mode
  176. member is carefully decoded into a bitwise-OR of symbolic and numeric values.
  177. Also notice in this example that the first argument to
  178. .BR lstat (2)
  179. is an input to the system call and the second argument is an output.
  180. Since output arguments are not modified if the system call fails, arguments may
  181. not always be dereferenced. For example, retrying the "ls \-l" example
  182. with a non-existent file produces the following line:
  183. .CW
  184. lstat("/foo/bar", 0xb004) = \-1 ENOENT (No such file or directory)
  185. .CE
  186. In this case the porch light is on but nobody is home.
  187. .LP
  188. Syscalls unknown to
  189. .B strace
  190. are printed raw, with the unknown system call number printed in hexadecimal form
  191. and prefixed with "syscall_":
  192. .CW
  193. syscall_0xbad(0x1, 0x2, 0x3, 0x4, 0x5, 0x6) = -1 ENOSYS (Function not implemented)
  194. .CE
  195. .LP
  196. Character pointers are dereferenced and printed as C strings.
  197. Non-printing characters in strings are normally represented by
  198. ordinary C escape codes.
  199. Only the first
  200. .I strsize
  201. (32 by default) bytes of strings are printed;
  202. longer strings have an ellipsis appended following the closing quote.
  203. Here is a line from "ls \-l" where the
  204. .BR getpwuid (3)
  205. library routine is reading the password file:
  206. .CW
  207. read(3, "root::0:0:System Administrator:/"..., 1024) = 422
  208. .CE
  209. While structures are annotated using curly braces, simple pointers
  210. and arrays are printed using square brackets with commas separating
  211. elements. Here is an example from the command
  212. .BR id (1)
  213. on a system with supplementary group ids:
  214. .CW
  215. getgroups(32, [100, 0]) = 2
  216. .CE
  217. On the other hand, bit-sets are also shown using square brackets,
  218. but set elements are separated only by a space.
  219. Here is the shell, preparing to execute an external command:
  220. .CW
  221. sigprocmask(SIG_BLOCK, [CHLD TTOU], []) = 0
  222. .CE
  223. Here, the second argument is a bit-set of two signals,
  224. .BR SIGCHLD " and " SIGTTOU .
  225. In some cases, the bit-set is so full that printing out the unset
  226. elements is more valuable. In that case, the bit-set is prefixed by
  227. a tilde like this:
  228. .CW
  229. sigprocmask(SIG_UNBLOCK, ~[], NULL) = 0
  230. .CE
  231. Here, the second argument represents the full set of all signals.
  232. .SH OPTIONS
  233. .SS General
  234. .TP 12
  235. .BI "\-e " expr
  236. A qualifying expression which modifies which events to trace
  237. or how to trace them. The format of the expression is:
  238. .RS 15
  239. .IP
  240. [\,\fIqualifier\/\fB=\fR][\fB!\fR][\fB?\fR]\,\fIvalue1\/\fR[\fB,\fR[\fB?\fR]\,\fIvalue2\/\fR]...
  241. .RE
  242. .IP
  243. where
  244. .I qualifier
  245. is one of
  246. .BR trace ,
  247. .BR abbrev ,
  248. .BR verbose ,
  249. .BR raw ,
  250. .BR signal ,
  251. .BR read ,
  252. .BR write ,
  253. .BR fault ,
  254. .BR inject ,
  255. .BR status ,
  256. or
  257. .B kvm
  258. and
  259. .I value
  260. is a qualifier-dependent symbol or number. The default
  261. qualifier is
  262. .BR trace .
  263. Using an exclamation mark negates the set of values. For example,
  264. .BR \-e "\ " open
  265. means literally
  266. .BR \-e "\ " trace = open
  267. which in turn means trace only the
  268. .B open
  269. system call. By contrast,
  270. .BR \-e "\ " trace "=!" open
  271. means to trace every system call except
  272. .BR open .
  273. Question mark before the syscall qualification allows suppression of error
  274. in case no syscalls matched the qualification provided.
  275. Appending one of "@64", "@32", or "@x32" suffixes to the syscall qualification
  276. allows specifying syscalls only for the 64-bit, 32-bit, or 32-on-64-bit
  277. personality, respectively.
  278. In addition, the special values
  279. .B all
  280. and
  281. .B none
  282. have the obvious meanings.
  283. .IP
  284. Note that some shells use the exclamation point for history
  285. expansion even inside quoted arguments. If so, you must escape
  286. the exclamation point with a backslash.
  287. .SS Startup
  288. .TP 12
  289. \fB\-E\ \fIvar\fR=\,\fIval\fR
  290. Run command with
  291. .IR var = val
  292. in its list of environment variables.
  293. .TP
  294. .BI "\-E " var
  295. Remove
  296. .IR var
  297. from the inherited list of environment variables before passing it on to
  298. the command.
  299. .TP
  300. .BI "\-p " pid
  301. Attach to the process with the process
  302. .SM ID
  303. .I pid
  304. and begin tracing.
  305. The trace may be terminated
  306. at any time by a keyboard interrupt signal
  307. .RB ( CTRL\-C ).
  308. .B strace
  309. will respond by detaching itself from the traced process(es)
  310. leaving it (them) to continue running.
  311. Multiple
  312. .B \-p
  313. options can be used to attach to many processes in addition to
  314. .I command
  315. (which is optional if at least one
  316. .B \-p
  317. option is given).
  318. .B \-p
  319. "`pidof PROG`" syntax is supported.
  320. .TP
  321. .BI "\-u " username
  322. Run command with the user \s-1ID\s0, group \s-2ID\s0, and
  323. supplementary groups of
  324. .IR username .
  325. This option is only useful when running as root and enables the
  326. correct execution of setuid and/or setgid binaries.
  327. Unless this option is used setuid and setgid programs are executed
  328. without effective privileges.
  329. .SS Tracing
  330. .TP 12
  331. .BI "\-b " syscall
  332. If specified syscall is reached, detach from traced process.
  333. Currently, only
  334. .BR execve (2)
  335. syscall is supported. This option is useful if you want to trace
  336. multi-threaded process and therefore require
  337. .BR \-f ,
  338. but don't want to trace its (potentially very complex) children.
  339. .TP
  340. .B \-D
  341. Run tracer process as a grandchild, not as the parent of the
  342. tracee. This reduces the visible effect of
  343. .B strace
  344. by keeping the tracee a direct child of the calling process.
  345. .TP
  346. .B \-DD
  347. Run tracer process as tracee's grandchild in a separate process group.
  348. In addition to reduction of the visible effect of
  349. .BR strace ,
  350. it also avoids killing of
  351. .B strace
  352. with
  353. .BR kill (2)
  354. issued to the whole process group.
  355. .TP
  356. .B \-DDD
  357. Run tracer process as tracee's grandchild in a separate session
  358. ("true daemonisation").
  359. In addition to reduction of the visible effect of
  360. .BR strace ,
  361. it also avoids killing of
  362. .B strace
  363. upon session termination.
  364. .TP
  365. .B \-f
  366. Trace child processes as they are created by currently traced
  367. processes as a result of the
  368. .BR fork (2),
  369. .BR vfork (2)
  370. and
  371. .BR clone (2)
  372. system calls. Note that
  373. .B \-p
  374. .I PID
  375. .B \-f
  376. will attach all threads of process
  377. .I PID
  378. if it is multi-threaded, not only thread with
  379. .IR thread_id " = " PID .
  380. .TP
  381. .B \-ff
  382. If the
  383. .B \-o
  384. .I filename
  385. option is in effect, each processes trace is written to
  386. .IR filename . pid
  387. where
  388. .I pid
  389. is the numeric process id of each process.
  390. This is incompatible with
  391. .BR \-c ,
  392. since no per-process counts are kept.
  393. .IP
  394. One might want to consider using
  395. .BR strace-log-merge (1)
  396. to obtain a combined strace log view.
  397. .TP
  398. .BI "\-I " interruptible
  399. When
  400. .B strace
  401. can be interrupted by signals (such as pressing
  402. .BR CTRL\-C ).
  403. .RS
  404. .TP 4
  405. .B 1
  406. no signals are blocked;
  407. .TQ
  408. .B 2
  409. fatal signals are blocked while decoding syscall (default);
  410. .TQ
  411. .B 3
  412. fatal signals are always blocked (default if
  413. .BR -o " " \fIFILE\fR " " \fIPROG\fR );
  414. .TQ
  415. .B 4
  416. fatal signals and
  417. .BR SIGTSTP " (" CTRL\-Z )
  418. are always blocked (useful to make
  419. .BI "strace -o " "FILE PROG"
  420. not stop on
  421. .BR CTRL\-Z ,
  422. default if
  423. .BR \-D ).
  424. .RE
  425. .SS Filtering
  426. .TP 12
  427. \fB\-e\ trace\fR=\,\fIset\fR
  428. Trace only the specified set of system calls. The
  429. .B \-c
  430. option is useful for determining which system calls might be useful
  431. to trace. For example,
  432. .BR trace = open,close,read,write
  433. means to only
  434. trace those four system calls. Be careful when making inferences
  435. about the user/kernel boundary if only a subset of system calls
  436. are being monitored. The default is
  437. .BR trace = all .
  438. .TP
  439. \fB\-e\ trace\fR=/\,\fIregex\fR
  440. Trace only those system calls that match the
  441. .IR regex .
  442. You can use
  443. .B POSIX
  444. Extended Regular Expression syntax (see
  445. .BR regex (7)).
  446. .TP
  447. .BR "\-e\ trace" = %file
  448. .TQ
  449. .BR "\-e\ trace" = file
  450. Trace all system calls which take a file name as an argument. You
  451. can think of this as an abbreviation for
  452. .BR "\-e\ trace" = open , stat , chmod , unlink ,...
  453. which is useful to seeing what files the process is referencing.
  454. Furthermore, using the abbreviation will ensure that you don't
  455. accidentally forget to include a call like
  456. .BR lstat (2)
  457. in the list. Betchya woulda forgot that one.
  458. The syntax without a preceding percent sign
  459. .RB (\[dq] "-e trace" = file \[dq])
  460. is deprecated.
  461. .TP
  462. .BR "\-e\ trace" = %process
  463. .TQ
  464. .BR "\-e\ trace" = process
  465. Trace all system calls which involve process management. This
  466. is useful for watching the fork, wait, and exec steps of a process.
  467. The syntax without a preceding percent sign
  468. .RB (\[dq] "-e trace" = process \[dq])
  469. is deprecated.
  470. .TP
  471. .BR "\-e\ trace" = %net
  472. .TQ
  473. .BR "\-e\ trace" = %network
  474. .TQ
  475. .BR "\-e\ trace" = network
  476. Trace all the network related system calls.
  477. The syntax without a preceding percent sign
  478. .RB (\[dq] "-e trace" = network \[dq])
  479. is deprecated.
  480. .TP
  481. .BR "\-e\ trace" = %signal
  482. .TQ
  483. .BR "\-e\ trace" = signal
  484. Trace all signal related system calls.
  485. The syntax without a preceding percent sign
  486. .RB (\[dq] "-e trace" = signal \[dq])
  487. is deprecated.
  488. .TP
  489. .BR "\-e\ trace" = %ipc
  490. .TQ
  491. .BR "\-e\ trace" = ipc
  492. Trace all IPC related system calls.
  493. The syntax without a preceding percent sign
  494. .RB (\[dq] "-e trace" = ipc \[dq])
  495. is deprecated.
  496. .TP
  497. .BR "\-e\ trace" = %desc
  498. .TQ
  499. .BR "\-e\ trace" = desc
  500. Trace all file descriptor related system calls.
  501. The syntax without a preceding percent sign
  502. .RB (\[dq] "-e trace" = desc \[dq])
  503. is deprecated.
  504. .TP
  505. .BR "\-e\ trace" = %memory
  506. .TQ
  507. .BR "\-e\ trace" = memory
  508. Trace all memory mapping related system calls.
  509. The syntax without a preceding percent sign
  510. .RB (\[dq] "-e trace" = memory \[dq])
  511. is deprecated.
  512. .TP
  513. .BR "\-e\ trace" = %stat
  514. Trace stat syscall variants.
  515. .TP
  516. .BR "\-e\ trace" = %lstat
  517. Trace lstat syscall variants.
  518. .TP
  519. .BR "\-e\ trace" = %fstat
  520. Trace fstat and fstatat syscall variants.
  521. .TP
  522. .BR "\-e\ trace" = %%stat
  523. Trace syscalls used for requesting file status (stat, lstat, fstat, fstatat,
  524. statx, and their variants).
  525. .TP
  526. .BR "\-e\ trace" = %statfs
  527. Trace statfs, statfs64, statvfs, osf_statfs, and osf_statfs64 system calls.
  528. The same effect can be achieved with
  529. .BR "\-e\ trace" = /^(.*_)?statv?fs
  530. regular expression.
  531. .TP
  532. .BR "\-e\ trace" = %fstatfs
  533. Trace fstatfs, fstatfs64, fstatvfs, osf_fstatfs, and osf_fstatfs64 system calls.
  534. The same effect can be achieved with
  535. .BR "\-e\ trace" = /fstatv?fs
  536. regular expression.
  537. .TP
  538. .BR "\-e\ trace" = %%statfs
  539. Trace syscalls related to file system statistics (statfs-like, fstatfs-like,
  540. and ustat). The same effect can be achieved with
  541. .BR "\-e\ trace" = /statv?fs|fsstat|ustat
  542. regular expression.
  543. .TP
  544. .BR "\-e\ trace" = %pure
  545. Trace syscalls that always succeed and have no arguments.
  546. Currently, this list includes
  547. .BR arc_gettls "(2), " getdtablesize "(2), " getegid "(2), " getegid32 "(2),"
  548. .BR geteuid "(2), " geteuid32 "(2), " getgid "(2), " getgid32 "(2),"
  549. .BR getpagesize "(2), " getpgrp "(2), " getpid "(2), " getppid "(2),"
  550. .BR get_thread_area (2)
  551. (on architectures other than x86),
  552. .BR gettid "(2), " get_tls "(2), " getuid "(2), " getuid32 "(2),"
  553. .BR getxgid "(2), " getxpid "(2), " getxuid "(2), " kern_features "(2), and"
  554. .BR metag_get_tls "(2)"
  555. syscalls.
  556. .TP
  557. \fB\-e\ signal\fR=\,\fIset\fR
  558. Trace only the specified subset of signals. The default is
  559. .BR signal = all .
  560. For example,
  561. .BR signal "=!" SIGIO
  562. (or
  563. .BR signal "=!" io )
  564. causes
  565. .B SIGIO
  566. signals not to be traced.
  567. .TP
  568. \fB\-e\ status\fR=\,\fIset\fR
  569. Print only system calls with the specified return status. The default is
  570. .BR status = all .
  571. When using the
  572. .B status
  573. qualifier, because
  574. .B strace
  575. waits for system calls to return before deciding whether they should be printed
  576. or not, the traditional order of events may not be preserved anymore. If two
  577. system calls are executed by concurrent threads,
  578. .B strace
  579. will first print both the entry and exit of the first system call to exit,
  580. regardless of their respective entry time. The entry and exit of the second
  581. system call to exit will be printed afterwards. Here is an example when
  582. .BR select (2)
  583. is called, but a different thread calls
  584. .BR clock_gettime (2)
  585. before
  586. .BR select (2)
  587. finishes:
  588. .CW
  589. [pid 28779] 1130322148.939977 clock_gettime(CLOCK_REALTIME, {1130322148, 939977000}) = 0
  590. [pid 28772] 1130322148.438139 select(4, [3], NULL, NULL, NULL) = 1 (in [3])
  591. .CE
  592. .I set
  593. can include the following elements:
  594. .RS
  595. .TP 13
  596. .B successful
  597. Trace system calls that returned without an error code.
  598. The
  599. .B -z
  600. option has the effect of
  601. .BR status = successful .
  602. .TQ
  603. .B failed
  604. Trace system calls that returned with an error code.
  605. The
  606. .B -Z
  607. option has the effect of
  608. .BR status = failed .
  609. .TQ
  610. .B unfinished
  611. Trace system calls that did not return. This might happen, for example, due to
  612. an execve call in a neighbour thread.
  613. .TQ
  614. .B unavailable
  615. Trace system calls that returned but strace failed to fetch the error status.
  616. .TQ
  617. .B detached
  618. Trace system calls for which strace detached before the return.
  619. .RE
  620. .TP
  621. .BI "\-P " path
  622. Trace only system calls accessing
  623. .IR path .
  624. Multiple
  625. .B \-P
  626. options can be used to specify several paths.
  627. .TP
  628. .B \-z
  629. Print only syscalls that returned without an error code.
  630. .TP
  631. .B \-Z
  632. Print only syscalls that returned with an error code.
  633. .SS Output format
  634. .TP 12
  635. .BI "\-a " column
  636. Align return values in a specific column (default column 40).
  637. .TP
  638. \fB\-e\ abbrev\fR=\,\fIset\fR
  639. Abbreviate the output from printing each member of large structures.
  640. The default is
  641. .BR abbrev = all .
  642. The
  643. .B \-v
  644. option has the effect of
  645. .BR abbrev = none .
  646. .TP
  647. \fB\-e\ verbose\fR=\,\fIset\fR
  648. Dereference structures for the specified set of system calls. The
  649. default is
  650. .BR verbose = all .
  651. .TP
  652. \fB\-e\ raw\fR=\,\fIset\fR
  653. Print raw, undecoded arguments for the specified set of system calls.
  654. This option has the effect of causing all arguments to be printed
  655. in hexadecimal. This is mostly useful if you don't trust the
  656. decoding or you need to know the actual numeric value of an
  657. argument.
  658. See also
  659. .B \-X raw
  660. option.
  661. .TP
  662. \fB\-e\ read\fR=\,\fIset\fR
  663. Perform a full hexadecimal and ASCII dump of all the data read from
  664. file descriptors listed in the specified set. For example, to see
  665. all input activity on file descriptors
  666. .I 3
  667. and
  668. .I 5
  669. use
  670. \fB\-e\ read\fR=\,\fI3\fR,\fI5\fR.
  671. Note that this is independent from the normal tracing of the
  672. .BR read (2)
  673. system call which is controlled by the option
  674. .BR -e "\ " trace = read .
  675. .TP
  676. \fB\-e\ write\fR=\,\fIset\fR
  677. Perform a full hexadecimal and ASCII dump of all the data written to
  678. file descriptors listed in the specified set. For example, to see
  679. all output activity on file descriptors
  680. .I 3
  681. and
  682. .I 5
  683. use
  684. \fB\-e\ write\fR=\,\fI3\fR,\,\fI5\fR.
  685. Note that this is independent from the normal tracing of the
  686. .BR write (2)
  687. system call which is controlled by the option
  688. .BR -e "\ " trace = write .
  689. .TP
  690. .BR "\-e\ kvm" = vcpu
  691. Print the exit reason of kvm vcpu. Requires Linux kernel version 4.16.0
  692. or higher.
  693. .TP
  694. .B \-i
  695. Print the instruction pointer at the time of the system call.
  696. .if '@ENABLE_STACKTRACE_FALSE@'#' .TP
  697. .if '@ENABLE_STACKTRACE_FALSE@'#' .B \-k
  698. .if '@ENABLE_STACKTRACE_FALSE@'#' Print the execution stack trace of the traced
  699. .if '@ENABLE_STACKTRACE_FALSE@'#' processes after each system call.
  700. .TP
  701. .BI "\-o " filename
  702. Write the trace output to the file
  703. .I filename
  704. rather than to stderr.
  705. .IR filename . pid
  706. form is used if
  707. .B \-ff
  708. option is supplied.
  709. If the argument begins with '|' or '!', the rest of the
  710. argument is treated as a command and all output is piped to it.
  711. This is convenient for piping the debugging output to a program
  712. without affecting the redirections of executed programs.
  713. The latter is not compatible with
  714. .B \-ff
  715. option currently.
  716. .TP
  717. .B \-A
  718. Open the file provided in the
  719. .B \-o
  720. option in append mode.
  721. .TP
  722. .B \-q
  723. Suppress messages about attaching, detaching etc. This happens
  724. automatically when output is redirected to a file and the command
  725. is run directly instead of attaching.
  726. .TP
  727. .B \-qq
  728. If given twice, suppress messages about process exit status.
  729. .TP
  730. .B \-r
  731. Print a relative timestamp upon entry to each system call. This
  732. records the time difference between the beginning of successive
  733. system calls.
  734. Note that since
  735. .B \-r
  736. option uses the monotonic clock time for measuring time difference and not the
  737. wall clock time, its measurements can differ from the difference in time
  738. reported by the
  739. .B \-t
  740. option.
  741. .TP
  742. .BI "\-s " strsize
  743. Specify the maximum string size to print (the default is 32). Note
  744. that filenames are not considered strings and are always printed in
  745. full.
  746. .TP
  747. .B \-t
  748. Prefix each line of the trace with the wall clock time.
  749. .TP
  750. .B \-tt
  751. If given twice, the time printed will include the microseconds.
  752. .TP
  753. .B \-ttt
  754. If given thrice, the time printed will include the microseconds
  755. and the leading portion will be printed as the number
  756. of seconds since the epoch.
  757. .TP
  758. .B \-T
  759. Show the time spent in system calls. This records the time
  760. difference between the beginning and the end of each system call.
  761. .TP
  762. .B \-v
  763. Print unabbreviated versions of environment, stat, termios, etc.
  764. calls. These structures are very common in calls and so the default
  765. behavior displays a reasonable subset of structure members. Use
  766. this option to get all of the gory details.
  767. .TP
  768. .B \-x
  769. Print all non-ASCII strings in hexadecimal string format.
  770. .TP
  771. .B \-xx
  772. Print all strings in hexadecimal string format.
  773. .TP
  774. .BI "\-X " format
  775. Set the format for printing of named constants and flags.
  776. Supported
  777. .I format
  778. values are:
  779. .RS
  780. .TP 10
  781. .B raw
  782. Raw number output, without decoding.
  783. .TQ
  784. .B abbrev
  785. Output a named constant or a set of flags instead of the raw number if they are
  786. found.
  787. This is the default
  788. .B strace
  789. behaviour.
  790. .TQ
  791. .B verbose
  792. Output both the raw value and the decoded string (as a comment).
  793. .RE
  794. .TP
  795. .B \-y
  796. Print paths associated with file descriptor arguments.
  797. .TP
  798. .B \-yy
  799. Print protocol specific information associated with socket file descriptors,
  800. and block/character device number associated with device file descriptors.
  801. .SS Statistics
  802. .TP 12
  803. .B \-c
  804. Count time, calls, and errors for each system call and report a summary on
  805. program exit, suppressing the regular output.
  806. This attempts to show system time (CPU time spent running
  807. in the kernel) independent of wall clock time. If
  808. .B \-c
  809. is used with
  810. .BR \-f ,
  811. only aggregate totals for all traced processes are kept.
  812. .TP
  813. .B \-C
  814. Like
  815. .B \-c
  816. but also print regular output while processes are running.
  817. .TP
  818. .BI "\-O " overhead
  819. Set the overhead for tracing system calls to
  820. .IR overhead .
  821. This is useful for overriding the default heuristic for guessing
  822. how much time is spent in mere measuring when timing system calls using
  823. the
  824. .B \-c
  825. option. The accuracy of the heuristic can be gauged by timing a given
  826. program run without tracing (using
  827. .BR time (1))
  828. and comparing the accumulated
  829. system call time to the total produced using
  830. .BR \-c .
  831. .IP
  832. The format of
  833. .I overhead
  834. specification is described in section
  835. .IR "Time specification format description".
  836. .TP
  837. .BI "\-S " sortby
  838. Sort the output of the histogram printed by the
  839. .B \-c
  840. option by the specified criterion. Legal values are
  841. .BR time " (or " time_total " or " total_time ),
  842. .BR calls " (or " count ),
  843. .BR errors " (or " error ),
  844. .BR name " (or " syscall " or " syscall_name ),
  845. and
  846. .BR nothing " (or " none );
  847. default is
  848. .BR time .
  849. .TP
  850. .B \-w
  851. Summarise the time difference between the beginning and end of
  852. each system call. The default is to summarise the system time.
  853. .SS Tampering
  854. .TP 12
  855. \fB\-e\ inject\fR=\,\fIset\/\fR[:\fBerror\fR=\,\fIerrno\/\fR|:\fBretval\fR=\,\fIvalue\/\fR][:\fBsignal\fR=\,\fIsig\/\fR][:\fBsyscall\fR=\fIsyscall\fR][:\fBdelay_enter\fR=\,\fIdelay\/\fR][:\fBdelay_exit\fR=\,\fIdelay\/\fR][:\fBwhen\fR=\,\fIexpr\/\fR]
  856. Perform syscall tampering for the specified set of syscalls.
  857. .IP
  858. At least one of
  859. .BR error ,
  860. .BR retval ,
  861. .BR signal ,
  862. .BR delay_enter ,
  863. or
  864. .B delay_exit
  865. options has to be specified.
  866. .B error
  867. and
  868. .B retval
  869. are mutually exclusive.
  870. .IP
  871. If :\fBerror\fR=\,\fIerrno\/\fR option is specified,
  872. a fault is injected into a syscall invocation:
  873. the syscall number is replaced by -1 which corresponds to an invalid syscall
  874. (unless a syscall is specified with :\fBsyscall=\fR option),
  875. and the error code is specified using a symbolic
  876. .I errno
  877. value like
  878. .B ENOSYS
  879. or a numeric value within 1..4095 range.
  880. .IP
  881. If :\fBretval\fR=\,\fIvalue\/\fR option is specified,
  882. success injection is performed: the syscall number is replaced by -1,
  883. but a bogus success value is returned to the callee.
  884. .IP
  885. If :\fBsignal\fR=\,\fIsig\/\fR option is specified with either a symbolic value
  886. like
  887. .B SIGSEGV
  888. or a numeric value within 1..\fBSIGRTMAX\fR range,
  889. that signal is delivered on entering every syscall specified by the
  890. .IR set .
  891. .IP
  892. If :\fBdelay_enter\fR=\,\fIdelay\/\fR or :\fBdelay_exit\fR=\,\fIdelay\/\fR
  893. options are specified, delay injection is performed: the tracee is delayed
  894. by time period specified by
  895. .IR delay
  896. on entering or exiting the syscall, respectively.
  897. The format of
  898. .I delay
  899. specification is described in section
  900. .IR "Time specification format description".
  901. .IP
  902. If :\fBsignal\fR=\,\fIsig\/\fR option is specified without
  903. :\fBerror\fR=\,\fIerrno\/\fR, :\fBretval\fR=\,\fIvalue\/\fR or
  904. :\fBdelay_{enter,exit}\fR=\,\fIusecs\/\fR options,
  905. then only a signal
  906. .I sig
  907. is delivered without a syscall fault or delay injection.
  908. Conversely, :\fBerror\fR=\,\fIerrno\/\fR or
  909. :\fBretval\fR=\,\fIvalue\/\fR option without
  910. :\fBdelay_enter\fR=\,\fIdelay\/\fR,
  911. :\fBdelay_exit\fR=\,\fIdelay\/\fR or
  912. :\fBsignal\fR=\,\fIsig\/\fR options injects a fault without delivering a signal
  913. or injecting a delay, etc.
  914. .IP
  915. If both :\fBerror\fR=\,\fIerrno\/\fR or :\fBretval\fR=\,\fIvalue\/\fR
  916. and :\fBsignal\fR=\,\fIsig\/\fR options are specified, then both
  917. a fault or success is injected and a signal is delivered.
  918. .IP
  919. if :\fBsyscall\fR=\fIsyscall\fR option is specified, the corresponding syscall
  920. with no side effects is injected instead of -1.
  921. Currently, only "pure" (see
  922. .BR "-e trace" = "%pure"
  923. description) syscalls can be specified there.
  924. .IP
  925. Unless a :\fBwhen\fR=\,\fIexpr\fR subexpression is specified,
  926. an injection is being made into every invocation of each syscall from the
  927. .IR set .
  928. .IP
  929. The format of the subexpression is one of the following:
  930. .RS
  931. .TP 12
  932. .I first
  933. For every syscall from the
  934. .IR set ,
  935. perform an injection for the syscall invocation number
  936. .I first
  937. only.
  938. .TQ
  939. \fIfirst\/\fB+\fR
  940. For every syscall from the
  941. .IR set ,
  942. perform injections for the syscall invocation number
  943. .I first
  944. and all subsequent invocations.
  945. .TQ
  946. \fIfirst\/\fB+\fIstep\fR
  947. For every syscall from the
  948. .IR set ,
  949. perform injections for syscall invocations number
  950. .IR first ,
  951. .IR first + step ,
  952. .IR first + step + step ,
  953. and so on.
  954. .RE
  955. .IP
  956. For example, to fail each third and subsequent chdir syscalls with
  957. .BR ENOENT ,
  958. use
  959. \fB\-e\ inject\fR=\,\fIchdir\/\fR:\fBerror\fR=\,\fIENOENT\/\fR:\fBwhen\fR=\,\fI3\/\fB+\fR.
  960. .IP
  961. The valid range for numbers
  962. .I first
  963. and
  964. .I step
  965. is 1..65535.
  966. .IP
  967. An injection expression can contain only one
  968. .BR error =
  969. or
  970. .BR retval =
  971. specification, and only one
  972. .BR signal =
  973. specification. If an injection expression contains multiple
  974. .BR when =
  975. specifications, the last one takes precedence.
  976. .IP
  977. Accounting of syscalls that are subject to injection
  978. is done per syscall and per tracee.
  979. .IP
  980. Specification of syscall injection can be combined
  981. with other syscall filtering options, for example,
  982. \fB\-P \fI/dev/urandom \fB\-e inject\fR=\,\fIfile\/\fR:\fBerror\fR=\,\fIENOENT\fR.
  983. .TP
  984. \fB\-e\ fault\fR=\,\fIset\/\fR[:\fBerror\fR=\,\fIerrno\/\fR][:\fBwhen\fR=\,\fIexpr\/\fR]
  985. Perform syscall fault injection for the specified set of syscalls.
  986. .IP
  987. This is equivalent to more generic
  988. \fB\-e\ inject\fR= expression with default value of
  989. .I errno
  990. option set to
  991. .BR ENOSYS .
  992. .SS Miscellaneous
  993. .TP 12
  994. .B \-d
  995. Show some debugging output of
  996. .B strace
  997. itself on the standard error.
  998. .TP
  999. .B \-F
  1000. This option is deprecated. It is retained for backward compatibility only
  1001. and may be removed in future releases.
  1002. Usage of multiple instances of
  1003. .B \-F
  1004. option is still equivalent to a single
  1005. .BR \-f ,
  1006. and it is ignored at all if used along with one or more instances of
  1007. .B \-f
  1008. option.
  1009. .TP
  1010. .BR \-h ,
  1011. .TQ
  1012. .B \-\-help
  1013. Print the help summary.
  1014. .TP
  1015. .B \-\-seccomp\-bpf
  1016. Enable (experimental) usage of seccomp-bpf (see
  1017. .BR seccomp (2))
  1018. to have
  1019. .BR ptrace (2)-stops
  1020. only when system calls that are being traced occur in the traced processes.
  1021. Implies the
  1022. .B \-f
  1023. option.
  1024. An attempt to rely on seccomp-bpf to filter system calls may fail for various
  1025. reasons, e.g. there are too many system calls to filter, the seccomp API is not
  1026. available, or
  1027. .B strace
  1028. itself is being traced.
  1029. .B \-\-seccomp\-bpf
  1030. is also ineffective on processes attached using
  1031. .BR \-p .
  1032. In cases when seccomp-bpf filter setup failed,
  1033. .B strace
  1034. proceeds as usual and stops traced processes on every system call.
  1035. .TP
  1036. .BR \-V ,
  1037. .TQ
  1038. .B \-\-version
  1039. Print the version number of
  1040. .BR strace .
  1041. .SS "Time specification format description"
  1042. .PP
  1043. Time values can be specified as a decimal floating point number
  1044. (in a format accepted by
  1045. .BR strtod (3)),
  1046. optionally followed by one of the following suffices that specify
  1047. the unit of time:
  1048. .B s
  1049. (seconds),
  1050. .B ms
  1051. (milliseconds),
  1052. .B us
  1053. (microseconds), or
  1054. .B ns
  1055. (nanoseconds).
  1056. If no suffix is specified, the value is interpreted as microseconds.
  1057. .PP
  1058. The described format is used for
  1059. .BR \-O ", " "\-e inject" = delay_enter ", and " "\-e inject" = delay_exit
  1060. options.
  1061. .SH DIAGNOSTICS
  1062. When
  1063. .I command
  1064. exits,
  1065. .B strace
  1066. exits with the same exit status.
  1067. If
  1068. .I command
  1069. is terminated by a signal,
  1070. .B strace
  1071. terminates itself with the same signal, so that
  1072. .B strace
  1073. can be used as a wrapper process transparent to the invoking parent process.
  1074. Note that parent-child relationship (signal stop notifications,
  1075. .BR getppid (2)
  1076. value, etc) between traced process and its parent are not preserved
  1077. unless
  1078. .B \-D
  1079. is used.
  1080. .LP
  1081. When using
  1082. .B \-p
  1083. without a
  1084. .IR command ,
  1085. the exit status of
  1086. .B strace
  1087. is zero unless no processes has been attached or there was an unexpected error
  1088. in doing the tracing.
  1089. .SH "SETUID INSTALLATION"
  1090. If
  1091. .B strace
  1092. is installed setuid to root then the invoking user will be able to
  1093. attach to and trace processes owned by any user.
  1094. In addition setuid and setgid programs will be executed and traced
  1095. with the correct effective privileges.
  1096. Since only users trusted with full root privileges should be allowed
  1097. to do these things,
  1098. it only makes sense to install
  1099. .B strace
  1100. as setuid to root when the users who can execute it are restricted
  1101. to those users who have this trust.
  1102. For example, it makes sense to install a special version of
  1103. .B strace
  1104. with mode 'rwsr-xr--', user
  1105. .B root
  1106. and group
  1107. .BR trace ,
  1108. where members of the
  1109. .B trace
  1110. group are trusted users.
  1111. If you do use this feature, please remember to install
  1112. a regular non-setuid version of
  1113. .B strace
  1114. for ordinary users to use.
  1115. .SH "MULTIPLE PERSONALITY SUPPORT"
  1116. On some architectures,
  1117. .B strace
  1118. supports decoding of syscalls for processes that use different ABI rather than
  1119. the one
  1120. .B strace
  1121. uses.
  1122. Specifically, in addition to decoding native ABI,
  1123. .B strace
  1124. can decode the following ABIs on the following architectures:
  1125. .TS H
  1126. allbox;
  1127. lb lb
  1128. l l.
  1129. Architecture ABIs supported
  1130. x86_64 i386, x32 [1]; i386 [2]
  1131. AArch64 ARM 32-bit EABI
  1132. PowerPC 64-bit [3] PowerPC 32-bit
  1133. s390x s390
  1134. SPARC 64-bit SPARC 32-bit
  1135. TILE 64-bit TILE 32-bit
  1136. .TE
  1137. .RS 0
  1138. .TP 5
  1139. [1]
  1140. When
  1141. .B strace
  1142. is built as an x86_64 application
  1143. .TQ
  1144. [2]
  1145. When
  1146. .B strace
  1147. is built as an x32 application
  1148. .TQ
  1149. [3]
  1150. Big endian only
  1151. .RE
  1152. .PP
  1153. This support is optional and relies on ability to generate and parse structure
  1154. definitions during the build time.
  1155. Please refer to the output of the
  1156. .B strace \-V
  1157. command in order to figure out what support is available in your
  1158. .B strace
  1159. build ("non-native" refers to an ABI that differs from the ABI
  1160. .B strace
  1161. has):
  1162. .TP 15
  1163. .B m32-mpers
  1164. .B strace
  1165. can trace and properly decode non-native 32-bit binaries.
  1166. .TQ
  1167. .B no-m32-mpers
  1168. .B strace
  1169. can trace, but cannot properly decode non-native 32-bit binaries.
  1170. .TQ
  1171. .B mx32-mpers
  1172. .B strace
  1173. can trace and properly decode non-native 32-on-64-bit binaries.
  1174. .TQ
  1175. .B no-mx32-mpers
  1176. .B strace
  1177. can trace, but cannot properly decode non-native 32-on-64-bit binaries.
  1178. .PP
  1179. If the output contains neither
  1180. .B m32-mpers
  1181. nor
  1182. .BR no-m32-mpers ,
  1183. then decoding of non-native 32-bit binaries is not implemented at all
  1184. or not applicable.
  1185. .PP
  1186. Likewise, if the output contains neither
  1187. .B mx32-mpers
  1188. nor
  1189. .BR no-mx32-mpers ,
  1190. then decoding of non-native 32-on-64-bit binaries is not implemented at all
  1191. or not applicable.
  1192. .SH NOTES
  1193. It is a pity that so much tracing clutter is produced by systems
  1194. employing shared libraries.
  1195. .LP
  1196. It is instructive to think about system call inputs and outputs
  1197. as data-flow across the user/kernel boundary. Because user-space
  1198. and kernel-space are separate and address-protected, it is
  1199. sometimes possible to make deductive inferences about process
  1200. behavior using inputs and outputs as propositions.
  1201. .LP
  1202. In some cases, a system call will differ from the documented behavior
  1203. or have a different name. For example, the
  1204. .BR faccessat (2)
  1205. system call does not have
  1206. .I flags
  1207. argument, and the
  1208. .BR setrlimit (2)
  1209. library function uses
  1210. .BR prlimit64 (2)
  1211. system call on modern (2.6.38+) kernels. These
  1212. discrepancies are normal but idiosyncratic characteristics of the
  1213. system call interface and are accounted for by C library wrapper
  1214. functions.
  1215. .LP
  1216. Some system calls have different names in different architectures and
  1217. personalities. In these cases, system call filtering and printing
  1218. uses the names that match corresponding
  1219. .BR __NR_ *
  1220. kernel macros of the tracee's architecture and personality.
  1221. There are two exceptions from this general rule:
  1222. .BR arm_fadvise64_64 (2)
  1223. ARM syscall and
  1224. .BR xtensa_fadvise64_64 (2)
  1225. Xtensa syscall are filtered and printed as
  1226. .BR fadvise64_64 (2).
  1227. .LP
  1228. On x32, syscalls that are intended to be used by 64-bit processes and not x32
  1229. ones (for example,
  1230. .BR readv (2),
  1231. that has syscall number 19 on x86_64, with its x32 counterpart has syscall
  1232. number 515), but called with
  1233. .B __X32_SYSCALL_BIT
  1234. flag being set, are designated with
  1235. .B "#64"
  1236. suffix.
  1237. .LP
  1238. On some platforms a process that is attached to with the
  1239. .B \-p
  1240. option may observe a spurious
  1241. .B EINTR
  1242. return from the current system call that is not restartable.
  1243. (Ideally, all system calls should be restarted on
  1244. .B strace
  1245. attach, making the attach invisible
  1246. to the traced process, but a few system calls aren't.
  1247. Arguably, every instance of such behavior is a kernel bug.)
  1248. This may have an unpredictable effect on the process
  1249. if the process takes no action to restart the system call.
  1250. .LP
  1251. As
  1252. .B strace
  1253. executes the specified
  1254. .I command
  1255. directly and does not employ a shell for that, scripts without shebang
  1256. that usually run just fine when invoked by shell fail to execute with
  1257. .B ENOEXEC
  1258. error.
  1259. It is advisable to manually supply a shell as a
  1260. .I command
  1261. with the script as its argument.
  1262. .SH BUGS
  1263. Programs that use the
  1264. .I setuid
  1265. bit do not have
  1266. effective user
  1267. .SM ID
  1268. privileges while being traced.
  1269. .LP
  1270. A traced process runs slowly.
  1271. .LP
  1272. Traced processes which are descended from
  1273. .I command
  1274. may be left running after an interrupt signal
  1275. .RB ( CTRL\-C ).
  1276. .SH HISTORY
  1277. The original
  1278. .B strace
  1279. was written by Paul Kranenburg
  1280. for SunOS and was inspired by its
  1281. .B trace
  1282. utility.
  1283. The SunOS version of
  1284. .B strace
  1285. was ported to Linux and enhanced
  1286. by Branko Lankester, who also wrote the Linux kernel support.
  1287. Even though Paul released
  1288. .B strace
  1289. 2.5 in 1992,
  1290. Branko's work was based on Paul's
  1291. .B strace
  1292. 1.5 release from 1991.
  1293. In 1993, Rick Sladkey merged
  1294. .B strace
  1295. 2.5 for SunOS and the second release of
  1296. .B strace
  1297. for Linux, added many of the features of
  1298. .BR truss (1)
  1299. from SVR4, and produced an
  1300. .B strace
  1301. that worked on both platforms. In 1994 Rick ported
  1302. .B strace
  1303. to SVR4 and Solaris and wrote the
  1304. automatic configuration support. In 1995 he ported
  1305. .B strace
  1306. to Irix
  1307. and tired of writing about himself in the third person.
  1308. .PP
  1309. Beginning with 1996,
  1310. .B strace
  1311. was maintained by Wichert Akkerman.
  1312. During his tenure,
  1313. .B strace
  1314. development migrated to CVS; ports to FreeBSD and many architectures on Linux
  1315. (including ARM, IA-64, MIPS, PA-RISC, PowerPC, s390, SPARC) were introduced.
  1316. In 2002, the burden of
  1317. .B strace
  1318. maintainership was transferred to Roland McGrath.
  1319. Since then,
  1320. .B strace
  1321. gained support for several new Linux architectures (AMD64, s390x, SuperH),
  1322. bi-architecture support for some of them, and received numerous additions and
  1323. improvements in syscalls decoders on Linux;
  1324. .B strace
  1325. development migrated to
  1326. .B git
  1327. during that period.
  1328. Since 2009,
  1329. .B strace
  1330. is actively maintained by Dmitry Levin.
  1331. .B strace
  1332. gained support for AArch64, ARC, AVR32, Blackfin, Meta, Nios II, OpenSISC 1000,
  1333. RISC-V, Tile/TileGx, Xtensa architectures since that time.
  1334. In 2012, unmaintained and apparently broken support for non-Linux operating
  1335. systems was removed.
  1336. Also, in 2012
  1337. .B strace
  1338. gained support for path tracing and file descriptor path decoding.
  1339. In 2014, support for stack traces printing was added.
  1340. In 2016, syscall fault injection was implemented.
  1341. .PP
  1342. For the additional information, please refer to the
  1343. .B NEWS
  1344. file and
  1345. .B strace
  1346. repository commit log.
  1347. .SH REPORTING BUGS
  1348. Problems with
  1349. .B strace
  1350. should be reported to the
  1351. .B strace
  1352. mailing list at <strace\-devel@lists.strace.io>.
  1353. .SH "SEE ALSO"
  1354. .BR strace-log-merge (1),
  1355. .BR ltrace (1),
  1356. .BR perf-trace (1),
  1357. .BR trace-cmd (1),
  1358. .BR time (1),
  1359. .BR ptrace (2),
  1360. .BR proc (5)
  1361. .PP
  1362. .UR https://strace.io/
  1363. .B strace
  1364. Home Page
  1365. .UE
  1366. .SH AUTHORS
  1367. The complete list of
  1368. .B strace
  1369. contributors can be found in the
  1370. .B CREDITS
  1371. file.