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 33KB

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