1truss(1) User Commands truss(1)
2
6 truss - trace system calls and signals
7
9 truss [-fcaeildDE] [- [tTvx] [!] syscall ,...]
10 [- [sS] [!] signal ,...] [- [mM] [!] fault ,...]
11 [- [rw] [!] fd ,...]
12 [- [uU] [!] lib ,... : [:] [!] func ,...]
13 [-o outfile] command | -p pid[/lwps]...
14
17 The truss utility executes the specified command and produces a trace
18 of the system calls it performs, the signals it receives, and the
19 machine faults it incurs. Each line of the trace output reports either
20 the fault or signal name or the system call name with its arguments and
21 return value(s). System call arguments are displayed symbolically when
22 possible using defines from relevant system headers. For any path name
23 pointer argument, the pointed-to string is displayed. Error returns are
24 reported using the error code names described in Intro(3). If, in the
25 case of an error, the kernel reports a missing privilege, a privilege
26 name as described in privileges(5) is reported in square brackets ([ ])
27 after the error code name.
28 Optionally (see the -u option), truss also produce an entry/exit trace
31 of user-level function calls executed by the traced process, indented
32 to indicate nesting.
33
35 For those options that take a list argument, the name all can be used
36 as a shorthand to specify all possible members of the list. If the list
37 begins with a !, the meaning of the option is negated (for example,
38 exclude rather than trace). Multiple occurrences of the same option can
39 be specified. For the same name in a list, subsequent options (those to
40 the right) override previous ones (those to the left).
41 The following options are supported:
44 -a
46 Shows the argument strings that are passed in each exec() system
48 call.
49 -c
52 Counts traced system calls, faults, and signals rather than dis‐
54 playing the trace line-by-line. A summary report is produced after
55 the traced command terminates or when truss is interrupted. If -f
56 is also specified, the counts include all traced system calls,
57 faults, and signals for child processes.
58 -d
61 Includes a time stamp on each line of trace output. The time stamp
63 appears as a field containing seconds.fraction at the start of the
64 line. This represents a time in seconds relative to the beginning
65 of the trace. The first line of the trace output shows the base
66 time from which the individual time stamps are measured, both as
67 seconds since the epoch (see time(2)) and as a date string (see
68 ctime(3C) and date(1)). The times that are reported are the times
69 that the event in question occurred. For all system calls, the
70 event is the completion of the system call, not the start of the
71 system call.
72 -D
75 Includes a time delta on each line of trace output. The value
77 appears as a field containing seconds.fraction and represents the
78 elapsed time for the LWP that incurred the event since the last
79 reported event incurred by that LWP. Specifically, for system
80 calls, this is not the time spent within the system call.
81 -e
84 Shows the environment strings that are passed in each exec() system
86 call.
87 -E
90 Includes a time delta on each line of trace output. The value
92 appears as a field containing seconds.fraction and represents the
93 difference in time elapsed between the beginning and end of a sys‐
94 tem call.
95 In contrast to the -D option, this is the amount of time spent
97 within the system call.
98 -f
101 Follows all children created by fork() or vfork() and includes
103 their signals, faults, and system calls in the trace output. Nor‐
104 mally, only the first-level command or process is traced. When -f
105 is specified, the process-id is included with each line of trace
106 output to indicate which process executed the system call or
107 received the signal.
108 -i
111 Does not display interruptible sleeping system calls. Certain sys‐
113 tem calls, such as open() and read() on terminal devices or pipes,
114 can sleep for indefinite periods and are interruptible. Normally,
115 truss reports such sleeping system calls if they remain asleep for
116 more than one second. The system call is reported again a second
117 time when it completes. The -i option causes such system calls to
118 be reported only once, when they complete.
119 -l
122 Includes the id of the responsible lightweight process (LWP) with
124 each line of trace output. If -f is also specified, both the
125 process-id and the LWP-id are included.
126 -m [!]fault,...
129 Machine faults to trace or exclude. Those faults specified in the
131 comma-separated list are traced. Faults can be specified by name or
132 number (see <sys/fault.h>). If the list begins with a !, the speci‐
133 fied faults are excluded from the trace output. Default is -mall -m
134 !fltpage.
135 -M [!]fault,...
138 Machine faults that stop the process. The specified faults are
140 added to the set specified by -m. If one of the specified faults is
141 incurred, truss leaves the process stopped and abandoned (see the
142 -T option). Default is -M!all.
143 -o outfile
146 File to be used for the trace output. By default, the output goes
148 to standard error.
149 -p
152 Interprets the command arguments to truss as a list of process-ids
154 for existing processes (see ps(1)) rather than as a command to be
155 executed. truss takes control of each process and begins tracing it
156 provided that the userid and groupid of the process match those of
157 the user or that the user is a privileged user. Users can trace
158 only selected threads by appending /thread-id to the process-id.
159 Mutiple threads can be selected using the - and , delimiters. For
160 example /1,2,7-9 traces threads 1, 2, 7, 8, and 9. Processes can
161 also be specified by their names in the /proc directory, for exam‐
162 ple, /proc/12345.
163 -r [!]fd,...
166 Shows the full contents of the I/O buffer for each read() on any of
168 the specified file descriptors. The output is formatted 32 bytes
169 per line and shows each byte as an ASCII character (preceded by one
170 blank) or as a 2-character C language escape sequence for control
171 characters such as horizontal tab (\t) and newline (\n). If ASCII
172 interpretation is not possible, the byte is shown in 2-character
173 hexadecimal representation. (The first 12 bytes of the I/O buffer
174 for each traced print >read() are shown even in the absence of -r.)
175 Default is -r!all.
176 -s [!]signal,...
179 Signals to trace or exclude. Those signals specified in the comma-
181 separated list are traced. The trace output reports the receipt of
182 each specified signal, even if the signal is being ignored (not
183 blocked). (Blocked signals are not received until they are
184 unblocked.) Signals can be specified by name or number (see
185 <sys/signal.h>). If the list begins with a !, the specified signals
186 are excluded from the trace output. Default is -sall.
187 -S [!]signal,...
190 Signals that stop the process. The specified signals are added to
192 the set specified by -s. If one of the specified signals is
193 received, truss leaves the process stopped and abandoned (see the
194 -T option). Default is -S!all.
195 -t [!]syscall,...
198 System calls to trace or exclude. Those system calls specified in
200 the comma-separated list are traced. If the list begins with a !,
201 the specified system calls are excluded from the trace output.
202 Default is -tall.
203 -T [!]syscall,...
206 Specifies system calls that stop the process. The specified system
208 calls are added to the set specified by -t. If one of the specified
209 system calls is encountered, truss leaves the process stopped and
210 abandoned. That is, truss releases the process and exits but leaves
211 the process in the stopped state at completion of the system call
212 in question. A debugger or other process inspection tool (see
213 proc(1)) can then be applied to the stopped process. truss can be
214 reapplied to the stopped process with the same or different options
215 to continue tracing. Default is -T!all.
216 A process left stopped in this manner cannot be restarted by the
218 application of kill -CONT because it is stopped on an event of
219 interest via /proc, not by the default action of a stopping signal
220 (see signal.h(3HEAD)). The prun(1) command described in proc(1) can
221 be used to set the stopped process running again.
222 -u [!]lib,...:[:][!]func,...
225 User-level function call tracing. lib,... is a comma-separated list
227 of dynamic library names, excluding the ``.so.n'' suffix. func,...
228 is a comma-separated list of function names. In both cases the
229 names can include name-matching metacharacters *,?,[] with the same
230 meanings as those of sh(1) but as applied to the library/function
231 name spaces, not to files. An empty library or function list
232 defaults to *, trace all libraries or functions in a library. A
233 leading ! on either list specifies an exclusion list, names of
234 libraries or functions not to be traced. Excluding a library
235 excludes all functions in that library; any function list following
236 a library exclusion list is ignored.
237 A single : separating the library list from the function list means
239 to trace calls into the libraries from outside the libraries, but
240 omit calls made to functions in a library from other functions in
241 the same library. A double :: means to trace all calls, regardless
242 of origin.
243 Library patterns do not match either the executable file or the
245 dynamic linker unless there is an exact match (l* does not match
246 ld.so.1). To trace functions in either of these objects, the names
247 must be specified exactly, as in:
248 truss -u a.out -u ld ...
250 a.out is the literal name to be used for this purpose; it does not
253 stand for the name of the executable file. Tracing a.out function
254 calls implies all calls (default is ::).
255 Multiple -u options can be specified and they are honored left-to-
257 right. The id of the thread that performed the function call is
258 included in the trace output for the call. truss searches the
259 dynamic symbol table in each library to find function names and
260 also searches the standard symbol table if it has not been
261 stripped.
262 -U [!]lib,...:[:][!]func,...
265 User-level function calls that stop the process. The specified
267 functions are added to the set specified by -u. If one of the spec‐
268 ified functions is called, truss leaves the process stopped and
269 abandoned (see the -T option).
270 -v [!]syscall,...
273 Verbose. Displays the contents of any structures passed by address
275 to the specified system calls (if traced by -t). Input values as
276 well as values returned by the operating system are shown. For any
277 field used as both input and output, only the output value is
278 shown. Default is -v!all.
279 -w [!]fd,...
282 Shows the contents of the I/O buffer for each write() on any of the
284 specified file descriptors (see the -r option). Default is -w!all.
285 -x [!]syscall,...
288 Displays the arguments to the specified system calls (if traced by
290 -t) in raw form, usually hexadecimal, rather than symbolically.
291 This is for unredeemed hackers who must see the raw bits to be
292 happy. Default is -x!all.
293 See man pages section 2: System Calls for system call names accepted by
297 the -t, -T, -v, and -x options. System call numbers are also accepted.
298 If truss is used to initiate and trace a specified command and if the
301 -o option is used or if standard error is redirected to a non-terminal
302 file, then truss runs with hangup, interrupt, and quit signals ignored.
303 This facilitates tracing of interactive programs that catch interrupt
304 and quit signals from the terminal.
305 If the trace output remains directed to the terminal, or if existing
308 processes are traced (the -p option), then truss responds to hangup,
309 interrupt, and quit signals by releasing all traced processes and exit‐
310 ing. This enables the user to terminate excessive trace output and to
311 release previously-existing processes. Released processes continue nor‐
312 mally, as though they had never been touched.
313
315 Example 1 Tracing a Command
316 The following example produces a trace of the find(1) command on the
319 terminal:
320 example$ truss find . -print >find.out
323 Example 2 Tracing Common System Calls
327 The following example shows only a trace of the open, close, read, and
330 write system calls:
331 example$ truss -t open,close,read,write find . -print >find.out
334 Example 3 Tracing a Shell Script
338 The following example produces a trace of the spell(1) command on the
341 file truss.out:
342 example$ truss -f -o truss.out spell document
345 spell is a shell script, so the -f flag is needed to trace not only the
350 shell but also the processes created by the shell. (The spell script
351 runs a pipeline of eight processes.)
352 Example 4 Abbreviating Output
355 The following example abreviates output:
358 example$ truss nroff -mm document >nroff.out
361 because 97% of the output reports lseek(), read(), and write() system
366 calls. To abbreviate it:
367 example$ truss -t !lseek,read,write nroff -mm document >nroff.out
370 Example 5 Tracing Library Calls From Outside the C Library
374 The following example traces all user-level calls made to any function
377 in the C library from outside the C library:
378 example$ truss -u libc ...
381 Example 6 Tracing library calls from within the C library
385 The following example includes calls made to functions in the C library
388 from within the C library itself:
389 example$ truss -u libc:: ...
392 Example 7 Tracing Library Calls Other Than the C Library
396 The following example traces all user-level calls made to any library
399 other than the C library:
400 example$ truss -u '*' -u !libc ...
403 Example 8 Tracing printf and scanf Function Calls
407 The following example traces all user-level calls to functions in the
410 printf and scanf family contained in the C library:
411 example$ truss -u 'libc:*printf,*scanf' ...
414 Example 9 Tracing Every User-level Function Call
418 The following example traces every user-level function call from any‐
421 where to anywhere:
422 example$ truss -u a.out -u ld:: -u :: ...
425 Example 10 Tracing a System Call Verbosely
429 The following example verbosely traces the system call activity of
432 process #1, init(1M) (if you are a privileged user):
433 example# truss -p -v all 1
436 Interrupting truss returns init to normal operation.
441
444 /proc/* Process files
445
448 See attributes(5) for descriptions of the following attributes:
449 ┌─────────────────────────────┬─────────────────────────────┐
454 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
455 ├─────────────────────────────┼─────────────────────────────┤
456 │Availability │SUNWtoo │
457 └─────────────────────────────┴─────────────────────────────┘
458
460 date(1), find(1), proc(1), ps(1), sh(1), spell(1), init(1M), Intro(3),
461 exec(2), fork(2), lseek(2), open(2), read(2), time(2), vfork(2),
462 write(2), ctime(3C), signal.h(3HEAD), proc(4), attributes(5), privi‐
463 leges(5), threads(5)
464 man pages section 2: System Calls
467
469 Some of the system calls described in man pages section 2: System Calls
470 differ from the actual operating system interfaces. Do not be surprised
471 by minor deviations of the trace output from the descriptions in that
472 document.
473 Every machine fault (except a page fault) results in the posting of a
476 signal to the LWP that incurred the fault. A report of a received sig‐
477 nal immediately follows each report of a machine fault (except a page
478 fault) unless that signal is being blocked.
479 The operating system enforces certain security restrictions on the
482 tracing of processes. In particular, any command whose object file
483 (a.out) cannot be read by a user cannot be traced by that user; set-uid
484 and set-gid commands can be traced only by a privileged user. Unless it
485 is run by a privileged user, truss loses control of any process that
486 performs an exec() of a set-id or unreadable object file; such pro‐
487 cesses continue normally, though independently of truss, from the point
488 of the exec().
489 To avoid collisions with other controlling processes, truss does not
492 trace a process that it detects is being controlled by another process
493 via the /proc interface. This allows truss to be applied to
494 proc(4)-based debuggers as well as to another instance of itself.
495 The trace output contains tab characters under the assumption that
498 standard tab stops are set (every eight positions).
499 The trace output for multiple processes or for a multithreaded process
502 (one that contains more than one LWP) is not produced in strict time
503 order. For example, a read() on a pipe can be reported before the cor‐
504 responding write(). For any one LWP (a traditional process contains
505 only one), the output is strictly time-ordered.
506 When tracing more than one process, truss runs as one controlling
509 process for each process being traced. For the example of the spell
510 command shown above, spell itself uses 9 process slots, one for the
511 shell and 8 for the 8-member pipeline, while truss adds another 9 pro‐
512 cesses, for a total of 18.
513 Not all possible structures passed in all possible system calls are
516 displayed under the -v option.
517SunOS 5.11 31 Jul 2004 truss(1)