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

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