blob: c1f87e9da3c1f260ee1ad81539ad4143d5eb3d4c [file] [log] [blame]
Wichert Akkerman76baf7c1999-02-19 00:21:36 +00001.\" 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.\" All rights reserved.
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright
10.\" notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\" notice, this list of conditions and the following disclaimer in the
13.\" documentation and/or other materials provided with the distribution.
14.\" 3. The name of the author may not be used to endorse or promote products
15.\" derived from this software without specific prior written permission.
16.\"
17.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
18.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
19.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
20.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
21.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
22.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
23.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
24.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
26.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Wichert Akkerman76baf7c1999-02-19 00:21:36 +000027.de CW
28.sp
29.nf
30.ft CW
31..
32.de CE
Wichert Akkerman8829a551999-06-11 13:18:40 +000033.ft R
Wichert Akkerman76baf7c1999-02-19 00:21:36 +000034.fi
35.sp
36..
Dmitry V. Levina1978322014-06-03 12:03:41 +000037.\" Macro IX is not defined in the groff macros
38.if \n(.g \{\
39. de IX
40..
41.\}
Dmitry V. Levina7835e62010-03-31 17:26:49 +000042.TH STRACE 1 "2010-03-30"
Wichert Akkerman76baf7c1999-02-19 00:21:36 +000043.SH NAME
44strace \- trace system calls and signals
45.SH SYNOPSIS
46.B strace
Luca Clementi327064b2013-07-23 00:11:35 -070047[\fB-CdffhikqrtttTvVxxy\fR]
Denys Vlasenkoc5ccfa42012-03-26 13:10:50 +020048[\fB-I\fIn\fR]
Denys Vlasenko22efaf02013-02-27 12:15:19 +010049[\fB-b\fIexecve\fR]
50[\fB-e\fIexpr\fR]...
51[\fB-a\fIcolumn\fR]
Denys Vlasenkoc5ccfa42012-03-26 13:10:50 +020052[\fB-o\fIfile\fR]
53[\fB-s\fIstrsize\fR]
54[\fB-P\fIpath\fR]... \fB-p\fIpid\fR... /
55[\fB-D\fR]
56[\fB-E\fIvar\fR[=\fIval\fR]]... [\fB-u\fIusername\fR]
57\fIcommand\fR [\fIargs\fR]
Wichert Akkerman76baf7c1999-02-19 00:21:36 +000058.sp
59.B strace
Denys Vlasenkoc5ccfa42012-03-26 13:10:50 +020060\fB-c\fR[\fBdf\fR]
61[\fB-I\fIn\fR]
Denys Vlasenko22efaf02013-02-27 12:15:19 +010062[\fB-b\fIexecve\fR]
63[\fB-e\fIexpr\fR]...
64[\fB-O\fIoverhead\fR]
Denys Vlasenkoc5ccfa42012-03-26 13:10:50 +020065[\fB-S\fIsortby\fR] \fB-p\fIpid\fR... /
66[\fB-D\fR]
67[\fB-E\fIvar\fR[=\fIval\fR]]... [\fB-u\fIusername\fR]
68\fIcommand\fR [\fIargs\fR]
Wichert Akkerman76baf7c1999-02-19 00:21:36 +000069.SH DESCRIPTION
70.IX "strace command" "" "\fLstrace\fR command"
71.LP
72In the simplest case
73.B strace
74runs the specified
75.I command
76until it exits.
77It intercepts and records the system calls which are called
78by a process and the signals which are received by a process.
79The name of each system call, its arguments and its return value
80are printed on standard error or to the file specified with the
81.B \-o
Roland McGratha09353a2008-12-10 06:09:29 +000082option.
Wichert Akkerman76baf7c1999-02-19 00:21:36 +000083.LP
84.B strace
Nate Sammonsb4aa1131999-03-31 05:59:04 +000085is a useful diagnostic, instructional, and debugging tool.
Roland McGrath0411b402003-10-22 06:16:32 +000086System administrators, diagnosticians and trouble-shooters will find
Wichert Akkerman76baf7c1999-02-19 00:21:36 +000087it invaluable for solving problems with
88programs for which the source is not readily available since
89they do not need to be recompiled in order to trace them.
90Students, hackers and the overly-curious will find that
91a great deal can be learned about a system and its system calls by
92tracing even ordinary programs. And programmers will find that
93since system calls and signals are events that happen at the user/kernel
94interface, a close examination of this boundary is very
95useful for bug isolation, sanity checking and
96attempting to capture race conditions.
97.LP
98Each line in the trace contains the system call name, followed
99by its arguments in parentheses and its return value.
Denys Vlasenkob5370532013-06-26 15:35:16 +0200100An example from stracing the command "cat /dev/null" is:
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000101.CW
102open("/dev/null", O_RDONLY) = 3
103.CE
104Errors (typically a return value of \-1) have the errno symbol
105and error string appended.
106.CW
Dmitry V. Levina1978322014-06-03 12:03:41 +0000107open("/foo/bar", O_RDONLY) = \-1 ENOENT (No such file or directory)
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000108.CE
Denys Vlasenkob5370532013-06-26 15:35:16 +0200109Signals are printed as signal symbol and decoded siginfo structure.
110An excerpt from stracing and interrupting the command "sleep 666" is:
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000111.CW
112sigsuspend([] <unfinished ...>
Denys Vlasenkob5370532013-06-26 15:35:16 +0200113--- SIGINT {si_signo=SIGINT, si_code=SI_USER, si_pid=...} ---
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000114+++ killed by SIGINT +++
115.CE
Jan Kratochvil14256a72008-09-12 08:44:30 +0000116If a system call is being executed and meanwhile another one is being called
117from a different thread/process then
118.B strace
119will try to preserve the order of those events and mark the ongoing call as
Dmitry V. Levina7835e62010-03-31 17:26:49 +0000120being
121.IR unfinished .
122When the call returns it will be marked as
123.IR resumed .
Jan Kratochvil14256a72008-09-12 08:44:30 +0000124.CW
125[pid 28772] select(4, [3], NULL, NULL, NULL <unfinished ...>
126[pid 28779] clock_gettime(CLOCK_REALTIME, {1130322148, 939977000}) = 0
127[pid 28772] <... select resumed> ) = 1 (in [3])
128.CE
129Interruption of a (restartable) system call by a signal delivery is processed
130differently as kernel terminates the system call and also arranges its
131immediate reexecution after the signal handler completes.
132.CW
133read(0, 0x7ffff72cf5cf, 1) = ? ERESTARTSYS (To be restarted)
Denys Vlasenkob5370532013-06-26 15:35:16 +0200134--- SIGALRM ... ---
Jan Kratochvil14256a72008-09-12 08:44:30 +0000135rt_sigreturn(0xe) = 0
Denys Vlasenkob5370532013-06-26 15:35:16 +0200136read(0, "", 1) = 0
Jan Kratochvil14256a72008-09-12 08:44:30 +0000137.CE
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000138Arguments are printed in symbolic form with a passion.
Denys Vlasenkob5370532013-06-26 15:35:16 +0200139This example shows the shell performing ">>xyzzy" output redirection:
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000140.CW
141open("xyzzy", O_WRONLY|O_APPEND|O_CREAT, 0666) = 3
142.CE
Dmitry V. Levin9b3eb842012-02-22 00:29:44 +0000143Here the third argument of open is decoded by breaking down the
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000144flag argument into its three bitwise-OR constituents and printing the
145mode value in octal by tradition. Where traditional or native
146usage differs from ANSI or POSIX, the latter forms are preferred.
Wichert Akkerman8829a551999-06-11 13:18:40 +0000147In some cases,
148.B strace
149output has proven to be more readable than the source.
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000150.LP
151Structure pointers are dereferenced and the members are displayed
152as appropriate. In all cases arguments are formatted in the most C-like
153fashion possible.
Denys Vlasenkob5370532013-06-26 15:35:16 +0200154For example, the essence of the command "ls \-l /dev/null" is captured as:
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000155.CW
156lstat("/dev/null", {st_mode=S_IFCHR|0666, st_rdev=makedev(1, 3), ...}) = 0
157.CE
Denys Vlasenkob5370532013-06-26 15:35:16 +0200158Notice how the 'struct stat' argument is dereferenced and how each member is
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000159displayed symbolically. In particular, observe how the st_mode member
160is carefully decoded into a bitwise-OR of symbolic and numeric values.
161Also notice in this example that the first argument to lstat is an input
162to the system call and the second argument is an output. Since output
Wichert Akkerman8829a551999-06-11 13:18:40 +0000163arguments are not modified if the system call fails, arguments may not
Denys Vlasenkob5370532013-06-26 15:35:16 +0200164always be dereferenced. For example, retrying the "ls \-l" example
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000165with a non-existent file produces the following line:
166.CW
Dmitry V. Levina1978322014-06-03 12:03:41 +0000167lstat("/foo/bar", 0xb004) = \-1 ENOENT (No such file or directory)
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000168.CE
169In this case the porch light is on but nobody is home.
170.LP
171Character pointers are dereferenced and printed as C strings.
172Non-printing characters in strings are normally represented by
173ordinary C escape codes.
174Only the first
175.I strsize
176(32 by default) bytes of strings are printed;
177longer strings have an ellipsis appended following the closing quote.
Denys Vlasenkob5370532013-06-26 15:35:16 +0200178Here is a line from "ls \-l" where the
Wichert Akkerman8829a551999-06-11 13:18:40 +0000179.B getpwuid
180library routine is reading the password file:
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000181.CW
182read(3, "root::0:0:System Administrator:/"..., 1024) = 422
183.CE
184While structures are annotated using curly braces, simple pointers
185and arrays are printed using square brackets with commas separating
Denys Vlasenkob5370532013-06-26 15:35:16 +0200186elements. Here is an example from the command "id" on a system with
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000187supplementary group ids:
188.CW
189getgroups(32, [100, 0]) = 2
190.CE
191On the other hand, bit-sets are also shown using square brackets
192but set elements are separated only by a space. Here is the shell
193preparing to execute an external command:
194.CW
195sigprocmask(SIG_BLOCK, [CHLD TTOU], []) = 0
196.CE
197Here the second argument is a bit-set of two signals, SIGCHLD and SIGTTOU.
198In some cases the bit-set is so full that printing out the unset
199elements is more valuable. In that case, the bit-set is prefixed by
200a tilde like this:
201.CW
202sigprocmask(SIG_UNBLOCK, ~[], NULL) = 0
203.CE
204Here the second argument represents the full set of all signals.
205.SH OPTIONS
206.TP 12
207.TP
208.B \-c
Roland McGrath4de04aa2004-08-31 07:47:47 +0000209Count time, calls, and errors for each system call and report a summary on
210program exit. On Linux, this attempts to show system time (CPU time spent
Dmitry V. Levina7835e62010-03-31 17:26:49 +0000211running in the kernel) independent of wall clock time. If
212.B \-c
213is used with
214.B \-f
215or
216.B \-F
217(below), only aggregate totals for all traced processes are kept.
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000218.TP
Dmitry V. Levine3a7ef52010-03-28 19:24:54 +0000219.B \-C
220Like
221.B \-c
222but also print regular output while processes are running.
223.TP
Andreas Schwabb87d30c2010-06-11 15:49:36 +0200224.B \-D
Andreas Schwabb87d30c2010-06-11 15:49:36 +0200225Run tracer process as a detached grandchild, not as parent of the
226tracee. This reduces the visible effect of
227.B strace
228by keeping the tracee a direct child of the calling process.
229.TP
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000230.B \-d
Wichert Akkerman8829a551999-06-11 13:18:40 +0000231Show some debugging output of
232.B strace
233itself on the standard error.
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000234.TP
235.B \-f
236Trace child processes as they are created by currently traced
Wichert Akkerman8829a551999-06-11 13:18:40 +0000237processes as a result of the
Denys Vlasenko22efaf02013-02-27 12:15:19 +0100238.BR fork (2),
239.BR vfork (2)
240and
241.BR clone (2)
Dmitry V. Levina1978322014-06-03 12:03:41 +0000242system calls. Note that
Denys Vlasenko22efaf02013-02-27 12:15:19 +0100243.B \-p
244.I PID
245.B \-f
246will attach all threads of process PID if it is multi-threaded,
247not only thread with thread_id = PID.
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000248.TP
249.B \-ff
250If the
251.B \-o
252.I filename
253option is in effect, each processes trace is written to
254.I filename.pid
255where pid is the numeric process id of each process.
Dmitry V. Levina7835e62010-03-31 17:26:49 +0000256This is incompatible with
257.BR \-c ,
258since no per-process counts are kept.
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000259.TP
260.B \-F
Roland McGrath41c48222008-07-18 00:25:10 +0000261This option is now obsolete and it has the same functionality as
Dmitry V. Levina7835e62010-03-31 17:26:49 +0000262.BR \-f .
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000263.TP
264.B \-h
265Print the help summary.
266.TP
267.B \-i
268Print the instruction pointer at the time of the system call.
269.TP
Luca Clementi327064b2013-07-23 00:11:35 -0700270.B \-k
Dmitry V. Levin2734a702014-06-18 15:34:27 +0000271Print the execution stack trace of the traced processes after each system call (experimental).
Giedrius Statkevičius6a63bfa2015-03-03 21:24:34 +0200272This option is available only if
273.B strace
274is built with libunwind.
Luca Clementi327064b2013-07-23 00:11:35 -0700275.TP
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000276.B \-q
277Suppress messages about attaching, detaching etc. This happens
278automatically when output is redirected to a file and the command
279is run directly instead of attaching.
280.TP
Daniel P. Berrange01997cf2013-05-13 11:30:55 +0100281.B \-qq
Dmitry V. Levine8ff4c62013-05-28 20:27:10 +0000282If given twice, suppress messages about process exit status.
Daniel P. Berrange01997cf2013-05-13 11:30:55 +0100283.TP
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000284.B \-r
285Print a relative timestamp upon entry to each system call. This
286records the time difference between the beginning of successive
287system calls.
288.TP
289.B \-t
290Prefix each line of the trace with the time of day.
291.TP
292.B \-tt
293If given twice, the time printed will include the microseconds.
294.TP
295.B \-ttt
296If given thrice, the time printed will include the microseconds
297and the leading portion will be printed as the number
298of seconds since the epoch.
299.TP
300.B \-T
Dmitry V. Levina1978322014-06-03 12:03:41 +0000301Show the time spent in system calls. This records the time
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000302difference between the beginning and the end of each system call.
303.TP
Mark Hillse53bf232014-05-28 17:52:40 +0100304.B \-w
305Summarise the time difference between the beginning and end of
Dmitry V. Levina1978322014-06-03 12:03:41 +0000306each system call. The default is to summarise the system time.
Mark Hillse53bf232014-05-28 17:52:40 +0100307.TP
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000308.B \-v
309Print unabbreviated versions of environment, stat, termios, etc.
310calls. These structures are very common in calls and so the default
311behavior displays a reasonable subset of structure members. Use
312this option to get all of the gory details.
313.TP
314.B \-V
Wichert Akkerman8829a551999-06-11 13:18:40 +0000315Print the version number of
316.BR strace .
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000317.TP
318.B \-x
Wichert Akkerman8829a551999-06-11 13:18:40 +0000319Print all non-ASCII strings in hexadecimal string format.
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000320.TP
321.B \-xx
322Print all strings in hexadecimal string format.
323.TP
Grant Edwards8a082772011-04-07 20:25:40 +0000324.B \-y
325Print paths associated with file descriptor arguments.
326.TP
Dmitry V. Levin2f6510c2014-08-21 03:17:48 +0000327.B \-yy
328Print ip:port pairs associated with socket file descriptors.
329.TP
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000330.BI "\-a " column
Wichert Akkerman4dc8a2a1999-12-23 14:20:14 +0000331Align return values in a specific column (default column 40).
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000332.TP
Denys Vlasenko22efaf02013-02-27 12:15:19 +0100333.BI "\-b " syscall
334If specified syscall is reached, detach from traced process.
335Currently, only
336.I execve
Dmitry V. Levina1978322014-06-03 12:03:41 +0000337syscall is supported. This option is useful if you want to trace
Denys Vlasenko22efaf02013-02-27 12:15:19 +0100338multi-threaded process and therefore require -f, but don't want
339to trace its (potentially very complex) children.
340.TP
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000341.BI "\-e " expr
342A qualifying expression which modifies which events to trace
343or how to trace them. The format of the expression is:
Wichert Akkerman8829a551999-06-11 13:18:40 +0000344.RS 15
345.IP
Dmitry V. Levina1978322014-06-03 12:03:41 +0000346[\,\fIqualifier\/\fB=\fR][\fB!\fR]\,\fIvalue1\/\fR[\fB,\,\fIvalue2\/\fR]...
Wichert Akkerman8829a551999-06-11 13:18:40 +0000347.RE
348.IP
349where
350.I qualifier
351is one of
352.BR trace ,
353.BR abbrev ,
354.BR verbose ,
355.BR raw ,
356.BR signal ,
357.BR read ,
358or
359.B write
360and
361.I value
362is a qualifier-dependent symbol or number. The default
363qualifier is
364.BR trace .
365Using an exclamation mark negates the set of values. For example,
Dmitry V. Levina7835e62010-03-31 17:26:49 +0000366.BR \-e "\ " open
Wichert Akkerman8829a551999-06-11 13:18:40 +0000367means literally
Dmitry V. Levina7835e62010-03-31 17:26:49 +0000368.BR \-e "\ " trace = open
Wichert Akkerman8829a551999-06-11 13:18:40 +0000369which in turn means trace only the
370.B open
371system call. By contrast,
Dmitry V. Levina7835e62010-03-31 17:26:49 +0000372.BR \-e "\ " trace "=!" open
Wichert Akkerman8829a551999-06-11 13:18:40 +0000373means to trace every system call except
374.BR open .
375In addition, the special values
376.B all
377and
378.B none
379have the obvious meanings.
380.IP
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000381Note that some shells use the exclamation point for history
Wichert Akkerman8829a551999-06-11 13:18:40 +0000382expansion even inside quoted arguments. If so, you must escape
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000383the exclamation point with a backslash.
384.TP
Dmitry V. Levina1978322014-06-03 12:03:41 +0000385\fB\-e\ trace\fR=\,\fIset\fR
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000386Trace only the specified set of system calls. The
387.B \-c
388option is useful for determining which system calls might be useful
Wichert Akkerman8829a551999-06-11 13:18:40 +0000389to trace. For example,
Dmitry V. Levina7835e62010-03-31 17:26:49 +0000390.BR trace = open,close,read,write
Wichert Akkerman8829a551999-06-11 13:18:40 +0000391means to only
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000392trace those four system calls. Be careful when making inferences
393about the user/kernel boundary if only a subset of system calls
Wichert Akkerman8829a551999-06-11 13:18:40 +0000394are being monitored. The default is
Dmitry V. Levina7835e62010-03-31 17:26:49 +0000395.BR trace = all .
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000396.TP
Dmitry V. Levin1c3031b2011-01-14 17:17:20 +0000397.BR "\-e\ trace" = file
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000398Trace all system calls which take a file name as an argument. You
399can think of this as an abbreviation for
Dmitry V. Levina7835e62010-03-31 17:26:49 +0000400.BR "\-e\ trace" = open , stat , chmod , unlink ,...
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000401which is useful to seeing what files the process is referencing.
402Furthermore, using the abbreviation will ensure that you don't
403accidentally forget to include a call like
404.B lstat
405in the list. Betchya woulda forgot that one.
406.TP
Dmitry V. Levin1c3031b2011-01-14 17:17:20 +0000407.BR "\-e\ trace" = process
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000408Trace all system calls which involve process management. This
409is useful for watching the fork, wait, and exec steps of a process.
410.TP
Dmitry V. Levin1c3031b2011-01-14 17:17:20 +0000411.BR "\-e\ trace" = network
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000412Trace all the network related system calls.
413.TP
Dmitry V. Levin1c3031b2011-01-14 17:17:20 +0000414.BR "\-e\ trace" = signal
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000415Trace all signal related system calls.
416.TP
Dmitry V. Levin1c3031b2011-01-14 17:17:20 +0000417.BR "\-e\ trace" = ipc
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000418Trace all IPC related system calls.
419.TP
Dmitry V. Levin1c3031b2011-01-14 17:17:20 +0000420.BR "\-e\ trace" = desc
Roland McGrath2fe7b132005-07-05 03:25:35 +0000421Trace all file descriptor related system calls.
422.TP
Namhyung Kim96792962012-10-24 11:41:57 +0900423.BR "\-e\ trace" = memory
424Trace all memory mapping related system calls.
425.TP
Dmitry V. Levina1978322014-06-03 12:03:41 +0000426\fB\-e\ abbrev\fR=\,\fIset\fR
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000427Abbreviate the output from printing each member of large structures.
Wichert Akkerman8829a551999-06-11 13:18:40 +0000428The default is
Dmitry V. Levina7835e62010-03-31 17:26:49 +0000429.BR abbrev = all .
Wichert Akkerman8829a551999-06-11 13:18:40 +0000430The
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000431.B \-v
Wichert Akkerman8829a551999-06-11 13:18:40 +0000432option has the effect of
Dmitry V. Levina7835e62010-03-31 17:26:49 +0000433.BR abbrev = none .
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000434.TP
Dmitry V. Levina1978322014-06-03 12:03:41 +0000435\fB\-e\ verbose\fR=\,\fIset\fR
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000436Dereference structures for the specified set of system calls. The
Wichert Akkerman8829a551999-06-11 13:18:40 +0000437default is
Dmitry V. Levina7835e62010-03-31 17:26:49 +0000438.BR verbose = all .
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000439.TP
Dmitry V. Levina1978322014-06-03 12:03:41 +0000440\fB\-e\ raw\fR=\,\fIset\fR
Roland McGrath0411b402003-10-22 06:16:32 +0000441Print raw, undecoded arguments for the specified set of system calls.
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000442This option has the effect of causing all arguments to be printed
443in hexadecimal. This is mostly useful if you don't trust the
444decoding or you need to know the actual numeric value of an
445argument.
446.TP
Dmitry V. Levina1978322014-06-03 12:03:41 +0000447\fB\-e\ signal\fR=\,\fIset\fR
Wichert Akkerman8829a551999-06-11 13:18:40 +0000448Trace only the specified subset of signals. The default is
Dmitry V. Levina7835e62010-03-31 17:26:49 +0000449.BR signal = all .
Wichert Akkerman8829a551999-06-11 13:18:40 +0000450For example,
Dmitry V. Levina7835e62010-03-31 17:26:49 +0000451.B signal "=!" SIGIO
Wichert Akkerman8829a551999-06-11 13:18:40 +0000452(or
Dmitry V. Levina7835e62010-03-31 17:26:49 +0000453.BR signal "=!" io )
Wichert Akkerman8829a551999-06-11 13:18:40 +0000454causes SIGIO signals not to be traced.
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000455.TP
Dmitry V. Levina1978322014-06-03 12:03:41 +0000456\fB\-e\ read\fR=\,\fIset\fR
Wichert Akkerman8829a551999-06-11 13:18:40 +0000457Perform a full hexadecimal and ASCII dump of all the data read from
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000458file descriptors listed in the specified set. For example, to see
Dmitry V. Levina7835e62010-03-31 17:26:49 +0000459all input activity on file descriptors
460.I 3
461and
462.I 5
463use
Dmitry V. Levina1978322014-06-03 12:03:41 +0000464\fB\-e\ read\fR=\,\fI3\fR,\fI5\fR.
Wichert Akkerman8829a551999-06-11 13:18:40 +0000465Note that this is independent from the normal tracing of the
466.BR read (2)
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000467system call which is controlled by the option
Dmitry V. Levina7835e62010-03-31 17:26:49 +0000468.BR -e "\ " trace = read .
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000469.TP
Dmitry V. Levina1978322014-06-03 12:03:41 +0000470\fB\-e\ write\fR=\,\fIset\fR
Wichert Akkerman8829a551999-06-11 13:18:40 +0000471Perform a full hexadecimal and ASCII dump of all the data written to
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000472file descriptors listed in the specified set. For example, to see
Dmitry V. Levina7835e62010-03-31 17:26:49 +0000473all output activity on file descriptors
474.I 3
475and
476.I 5
477use
Dmitry V. Levina1978322014-06-03 12:03:41 +0000478\fB\-e\ write\fR=\,\fI3\fR,\,\fI5\fR.
Wichert Akkerman8829a551999-06-11 13:18:40 +0000479Note that this is independent from the normal tracing of the
480.BR write (2)
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000481system call which is controlled by the option
Dmitry V. Levina7835e62010-03-31 17:26:49 +0000482.BR -e "\ " trace = write .
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000483.TP
Denys Vlasenkoc5ccfa42012-03-26 13:10:50 +0200484.BI "\-I " interruptible
485When strace can be interrupted by signals (such as pressing ^C).
4861: no signals are blocked; 2: fatal signals are blocked while decoding syscall
487(default); 3: fatal signals are always blocked (default if '-o FILE PROG');
4884: fatal signals and SIGTSTP (^Z) are always blocked (useful to make
489strace -o FILE PROG not stop on ^Z).
490.TP
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000491.BI "\-o " filename
492Write the trace output to the file
493.I filename
494rather than to stderr.
495Use
496.I filename.pid
497if
498.B \-ff
499is used.
Denys Vlasenkob5370532013-06-26 15:35:16 +0200500If the argument begins with '|' or with '!' then the rest of the
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000501argument is treated as a command and all output is piped to it.
502This is convenient for piping the debugging output to a program
503without affecting the redirections of executed programs.
504.TP
505.BI "\-O " overhead
Wichert Akkerman8829a551999-06-11 13:18:40 +0000506Set the overhead for tracing system calls to
507.I overhead
508microseconds.
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000509This is useful for overriding the default heuristic for guessing
510how much time is spent in mere measuring when timing system calls using
511the
512.B \-c
Roland McGrath0411b402003-10-22 06:16:32 +0000513option. The accuracy of the heuristic can be gauged by timing a given
Wichert Akkerman8829a551999-06-11 13:18:40 +0000514program run without tracing (using
515.BR time (1))
516and comparing the accumulated
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000517system call time to the total produced using
Wichert Akkerman8829a551999-06-11 13:18:40 +0000518.BR \-c .
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000519.TP
520.BI "\-p " pid
521Attach to the process with the process
522.SM ID
523.I pid
524and begin tracing.
525The trace may be terminated
526at any time by a keyboard interrupt signal (\c
527.SM CTRL\s0-C).
528.B strace
529will respond by detaching itself from the traced process(es)
530leaving it (them) to continue running.
531Multiple
532.B \-p
Denys Vlasenko94f00e62012-03-26 13:31:11 +0200533options can be used to attach to many processes.
Denys Vlasenko6bc050c2012-03-13 11:48:22 +0100534-p "`pidof PROG`" syntax is supported.
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000535.TP
Grant Edwards8a082772011-04-07 20:25:40 +0000536.BI "\-P " path
537Trace only system calls accessing
538.I path.
539Multiple
540.B \-P
Denys Vlasenko7239dbc2013-03-05 15:46:34 +0100541options can be used to specify several paths.
Grant Edwards8a082772011-04-07 20:25:40 +0000542.TP
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000543.BI "\-s " strsize
544Specify the maximum string size to print (the default is 32). Note
545that filenames are not considered strings and are always printed in
546full.
547.TP
548.BI "\-S " sortby
549Sort the output of the histogram printed by the
550.B \-c
Roland McGrath0411b402003-10-22 06:16:32 +0000551option by the specified criterion. Legal values are
Wichert Akkerman8829a551999-06-11 13:18:40 +0000552.BR time ,
553.BR calls ,
554.BR name ,
555and
556.B nothing
Dmitry V. Levina7835e62010-03-31 17:26:49 +0000557(default is
Wichert Akkerman8829a551999-06-11 13:18:40 +0000558.BR time ).
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000559.TP
560.BI "\-u " username
Wichert Akkerman8829a551999-06-11 13:18:40 +0000561Run command with the user \s-1ID\s0, group \s-2ID\s0, and
562supplementary groups of
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000563.IR username .
564This option is only useful when running as root and enables the
565correct execution of setuid and/or setgid binaries.
566Unless this option is used setuid and setgid programs are executed
567without effective privileges.
Roland McGrath4417fda2003-01-24 04:31:20 +0000568.TP
Dmitry V. Levina1978322014-06-03 12:03:41 +0000569\fB\-E\ \fIvar\fR=\,\fIval\fR
Roland McGrath4417fda2003-01-24 04:31:20 +0000570Run command with
Dmitry V. Levina7835e62010-03-31 17:26:49 +0000571.IR var = val
Roland McGrath4417fda2003-01-24 04:31:20 +0000572in its list of environment variables.
573.TP
574.BI "\-E " var
575Remove
576.IR var
577from the inherited list of environment variables before passing it on to
578the command.
Roland McGratha09353a2008-12-10 06:09:29 +0000579.SH DIAGNOSTICS
580When
581.I command
582exits,
583.B strace
584exits with the same exit status.
585If
586.I command
587is terminated by a signal,
588.B strace
589terminates itself with the same signal, so that
590.B strace
591can be used as a wrapper process transparent to the invoking parent process.
Denys Vlasenkob5370532013-06-26 15:35:16 +0200592Note that parent-child relationship (signal stop notifications,
593getppid() value, etc) between traced process and its parent are not preserved
594unless
595.B \-D
596is used.
Roland McGratha09353a2008-12-10 06:09:29 +0000597.LP
598When using
Dmitry V. Levina7835e62010-03-31 17:26:49 +0000599.BR \-p ,
Roland McGratha09353a2008-12-10 06:09:29 +0000600the exit status of
601.B strace
602is zero unless there was an unexpected error in doing the tracing.
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000603.SH "SETUID INSTALLATION"
604If
605.B strace
606is installed setuid to root then the invoking user will be able to
607attach to and trace processes owned by any user.
608In addition setuid and setgid programs will be executed and traced
609with the correct effective privileges.
610Since only users trusted with full root privileges should be allowed
611to do these things,
612it only makes sense to install
613.B strace
614as setuid to root when the users who can execute it are restricted
615to those users who have this trust.
616For example, it makes sense to install a special version of
Wichert Akkerman8829a551999-06-11 13:18:40 +0000617.B strace
Denys Vlasenkob5370532013-06-26 15:35:16 +0200618with mode 'rwsr-xr--', user
Wichert Akkerman8829a551999-06-11 13:18:40 +0000619.B root
620and group
621.BR trace ,
622where members of the
623.B trace
624group are trusted users.
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000625If you do use this feature, please remember to install
Wichert Akkerman8829a551999-06-11 13:18:40 +0000626a non-setuid version of
627.B strace
628for ordinary lusers to use.
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000629.SH "SEE ALSO"
Roland McGrath7f7f4362005-12-02 03:59:35 +0000630.BR ltrace (1),
Wichert Akkerman8829a551999-06-11 13:18:40 +0000631.BR time (1),
Roland McGrath7f7f4362005-12-02 03:59:35 +0000632.BR ptrace (2),
633.BR proc (5)
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000634.SH NOTES
635It is a pity that so much tracing clutter is produced by systems
636employing shared libraries.
637.LP
638It is instructive to think about system call inputs and outputs
639as data-flow across the user/kernel boundary. Because user-space
640and kernel-space are separate and address-protected, it is
641sometimes possible to make deductive inferences about process
642behavior using inputs and outputs as propositions.
643.LP
644In some cases, a system call will differ from the documented behavior
Wichert Akkerman8829a551999-06-11 13:18:40 +0000645or have a different name. For example, on System V-derived systems
646the true
647.BR time (2)
648system call does not take an argument and the
649.B stat
650function is called
651.B xstat
652and takes an extra leading argument. These
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000653discrepancies are normal but idiosyncratic characteristics of the
654system call interface and are accounted for by C library wrapper
655functions.
656.LP
Denys Vlasenkob5370532013-06-26 15:35:16 +0200657On some platforms a process that is attached to with the
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000658.B \-p
Denys Vlasenkob5370532013-06-26 15:35:16 +0200659option may observe a spurious EINTR return from the current
Dmitry V. Levina1978322014-06-03 12:03:41 +0000660system call that is not restartable. (Ideally, all system calls
Denys Vlasenkob5370532013-06-26 15:35:16 +0200661should be restarted on strace attach, making the attach invisible
662to the traced process, but a few system calls aren't.
663Arguably, every instance of such behavior is a kernel bug.)
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000664This may have an unpredictable effect on the process
665if the process takes no action to restart the system call.
666.SH BUGS
667Programs that use the
668.I setuid
669bit do not have
670effective user
671.SM ID
672privileges while being traced.
673.LP
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000674A traced process runs slowly.
675.LP
676Traced processes which are descended from
677.I command
678may be left running after an interrupt signal (\c
679.SM CTRL\s0-C).
680.LP
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000681The
682.B \-i
683option is weakly supported.
684.SH HISTORY
Wichert Akkerman8829a551999-06-11 13:18:40 +0000685The original
686.B strace
687was written by Paul Kranenburg
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000688for SunOS and was inspired by its trace utility.
Wichert Akkerman8829a551999-06-11 13:18:40 +0000689The SunOS version of
690.B strace
691was ported to Linux and enhanced
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000692by Branko Lankester, who also wrote the Linux kernel support.
Wichert Akkerman8829a551999-06-11 13:18:40 +0000693Even though Paul released
694.B strace
6952.5 in 1992,
696Branko's work was based on Paul's
697.B strace
6981.5 release from 1991.
699In 1993, Rick Sladkey merged
700.B strace
7012.5 for SunOS and the second release of
702.B strace
703for Linux, added many of the features of
704.BR truss (1)
705from SVR4, and produced an
706.B strace
707that worked on both platforms. In 1994 Rick ported
708.B strace
709to SVR4 and Solaris and wrote the
710automatic configuration support. In 1995 he ported
711.B strace
712to Irix
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000713and tired of writing about himself in the third person.
714.SH PROBLEMS
715Problems with
716.B strace
Dmitry V. Levindd762c32012-02-25 15:29:21 +0100717should be reported to the
Wichert Akkerman76baf7c1999-02-19 00:21:36 +0000718.B strace
Dmitry V. Levina7835e62010-03-31 17:26:49 +0000719mailing list at <strace\-devel@lists.sourceforge.net>.