Print this page
9842 man page typos and spelling
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man1/truss.1.man.txt
+++ new/usr/src/man/man1/truss.1.man.txt
1 1 TRUSS(1) User Commands TRUSS(1)
2 2
3 3
4 4
5 5 NAME
6 6 truss - trace system calls and signals
7 7
8 8 SYNOPSIS
9 9 truss [-fcaeildDE] [- [tTvx] [!] syscall ,...]
10 10 [- [sS] [!] signal ,...] [- [mM] [!] fault ,...]
11 11 [- [rw] [!] fd ,...]
12 12 [- [uU] [!] lib ,... : [:] [!] func ,...]
13 13 [-o outfile] command | -p pid[/lwps]...
14 14
15 15
16 16 DESCRIPTION
17 17 The truss utility executes the specified command and produces a trace
18 18 of the system calls it performs, the signals it receives, and the
19 19 machine faults it incurs. Each line of the trace output reports either
20 20 the fault or signal name or the system call name with its arguments and
21 21 return value(s). System call arguments are displayed symbolically when
22 22 possible using defines from relevant system headers. For any path name
23 23 pointer argument, the pointed-to string is displayed. Error returns are
24 24 reported using the error code names described in Intro(3). If, in the
25 25 case of an error, the kernel reports a missing privilege, a privilege
26 26 name as described in privileges(5) is reported in square brackets ([ ])
27 27 after the error code name.
28 28
29 29
30 30 Optionally (see the -u option), truss also produce an entry/exit trace
31 31 of user-level function calls executed by the traced process, indented
32 32 to indicate nesting.
33 33
34 34 OPTIONS
35 35 For those options that take a list argument, the name all can be used
36 36 as a shorthand to specify all possible members of the list. If the list
37 37 begins with a !, the meaning of the option is negated (for example,
38 38 exclude rather than trace). Multiple occurrences of the same option can
39 39 be specified. For the same name in a list, subsequent options (those
40 40 to the right) override previous ones (those to the left).
41 41
42 42
43 43 The following options are supported:
44 44
45 45 -a
46 46
47 47 Shows the argument strings that are passed in each exec() system
48 48 call.
49 49
50 50
51 51 -c
52 52
53 53 Counts traced system calls, faults, and signals rather than
54 54 displaying the trace line-by-line. A summary report is produced
55 55 after the traced command terminates or when truss is interrupted.
56 56 If -f is also specified, the counts include all traced system
57 57 calls, faults, and signals for child processes.
58 58
59 59
60 60 -d
61 61
62 62 Includes a time stamp on each line of trace output. The time stamp
63 63 appears as a field containing seconds.fraction at the start of the
64 64 line. This represents a time in seconds relative to the beginning
65 65 of the trace. The first line of the trace output shows the base
66 66 time from which the individual time stamps are measured, both as
67 67 seconds since the epoch (see time(2)) and as a date string (see
68 68 ctime(3C) and date(1)). The times that are reported are the times
69 69 that the event in question occurred. For all system calls, the
70 70 event is the completion of the system call, not the start of the
71 71 system call.
72 72
73 73
74 74 -D
75 75
76 76 Includes a time delta on each line of trace output. The value
77 77 appears as a field containing seconds.fraction and represents the
78 78 elapsed time for the LWP that incurred the event since the last
79 79 reported event incurred by that LWP. Specifically, for system
80 80 calls, this is not the time spent within the system call.
81 81
82 82
83 83 -e
84 84
85 85 Shows the environment strings that are passed in each exec() system
86 86 call.
87 87
88 88
89 89 -E
90 90
91 91 Includes a time delta on each line of trace output. The value
92 92 appears as a field containing seconds.fraction and represents the
93 93 difference in time elapsed between the beginning and end of a
94 94 system call.
95 95
96 96 In contrast to the -D option, this is the amount of time spent
97 97 within the system call.
98 98
99 99
100 100 -f
101 101
102 102 Follows all children created by fork() or vfork() and includes
103 103 their signals, faults, and system calls in the trace output.
104 104 Normally, only the first-level command or process is traced. When
105 105 -f is specified, the process-id is included with each line of trace
106 106 output to indicate which process executed the system call or
107 107 received the signal.
108 108
109 109
110 110 -i
111 111
112 112 Does not display interruptible sleeping system calls. Certain
113 113 system calls, such as open() and read() on terminal devices or
114 114 pipes, can sleep for indefinite periods and are interruptible.
115 115 Normally, truss reports such sleeping system calls if they remain
116 116 asleep for more than one second. The system call is reported again
117 117 a second time when it completes. The -i option causes such system
118 118 calls to be reported only once, when they complete.
119 119
120 120
121 121 -l
122 122
123 123 Includes the id of the responsible lightweight process (LWP) with
124 124 each line of trace output. If -f is also specified, both the
125 125 process-id and the LWP-id are included.
126 126
127 127
128 128 -m [!]fault,...
129 129
130 130 Machine faults to trace or exclude. Those faults specified in the
131 131 comma-separated list are traced. Faults can be specified by name or
132 132 number (see <sys/fault.h>). If the list begins with a !, the
133 133 specified faults are excluded from the trace output. Default is
134 134 -mall -m !fltpage.
135 135
136 136
137 137 -M [!]fault,...
138 138
139 139 Machine faults that stop the process. The specified faults are
140 140 added to the set specified by -m. If one of the specified faults is
141 141 incurred, truss leaves the process stopped and abandoned (see the
142 142 -T option). Default is -M!all.
143 143
144 144
145 145 -o outfile
146 146
147 147 File to be used for the trace output. By default, the output goes
148 148 to standard error.
149 149
150 150
151 151 -p
152 152
153 153 Interprets the command arguments to truss as a list of process-ids
154 154 for existing processes (see ps(1)) rather than as a command to be
155 155 executed. truss takes control of each process and begins tracing it
156 156 provided that the userid and groupid of the process match those of
157 157 the user or that the user is a privileged user. Users can trace
158 158 only selected threads by appending /thread-id to the process-id.
159 159 Mutiple threads can be selected using the - and , delimiters. For
160 160 example /1,2,7-9 traces threads 1, 2, 7, 8, and 9. Processes can
161 161 also be specified by their names in the /proc directory, for
162 162 example, /proc/12345.
163 163
164 164
165 165 -r [!]fd,...
166 166
167 167 Shows the full contents of the I/O buffer for each read() on any of
168 168 the specified file descriptors. The output is formatted 32 bytes
169 169 per line and shows each byte as an ASCII character (preceded by one
170 170 blank) or as a 2-character C language escape sequence for control
171 171 characters such as horizontal tab (\t) and newline (\n). If ASCII
172 172 interpretation is not possible, the byte is shown in 2-character
173 173 hexadecimal representation. (The first 12 bytes of the I/O buffer
174 174 for each traced print >read() are shown even in the absence of -r.)
175 175 Default is -r!all.
176 176
177 177
178 178 -s [!]signal,...
179 179
180 180 Signals to trace or exclude. Those signals specified in the comma-
181 181 separated list are traced. The trace output reports the receipt of
182 182 each specified signal, even if the signal is being ignored (not
183 183 blocked). (Blocked signals are not received until they are
184 184 unblocked.) Signals can be specified by name or number (see
185 185 <sys/signal.h>). If the list begins with a !, the specified signals
186 186 are excluded from the trace output. Default is -sall.
187 187
188 188
189 189 -S [!]signal,...
190 190
191 191 Signals that stop the process. The specified signals are added to
192 192 the set specified by -s. If one of the specified signals is
193 193 received, truss leaves the process stopped and abandoned (see the
194 194 -T option). Default is -S!all.
195 195
196 196
197 197 -t [!]syscall,...
198 198
199 199 System calls to trace or exclude. Those system calls specified in
200 200 the comma-separated list are traced. If the list begins with a !,
201 201 the specified system calls are excluded from the trace output.
202 202 Default is -tall.
203 203
204 204
205 205 -T [!]syscall,...
206 206
207 207 Specifies system calls that stop the process. The specified system
208 208 calls are added to the set specified by -t. If one of the specified
209 209 system calls is encountered, truss leaves the process stopped and
210 210 abandoned. That is, truss releases the process and exits but leaves
211 211 the process in the stopped state at completion of the system call
212 212 in question. A debugger or other process inspection tool (see
213 213 proc(1)) can then be applied to the stopped process. truss can be
214 214 reapplied to the stopped process with the same or different options
215 215 to continue tracing. Default is -T!all.
216 216
217 217 A process left stopped in this manner cannot be restarted by the
218 218 application of kill -CONT because it is stopped on an event of
219 219 interest via /proc, not by the default action of a stopping signal
220 220 (see signal.h(3HEAD)). The prun(1) command described in proc(1) can
221 221 be used to set the stopped process running again.
222 222
223 223
224 224 -u [!]lib,...:[:][!]func,...
225 225
226 226 User-level function call tracing. lib,... is a comma-separated list
227 227 of dynamic library names, excluding the ``.so.n'' suffix. func,...
228 228 is a comma-separated list of function names. In both cases the
229 229 names can include name-matching metacharacters *,?,[] with the same
230 230 meanings as those of sh(1) but as applied to the library/function
231 231 name spaces, not to files. An empty library or function list
232 232 defaults to *, trace all libraries or functions in a library. A
233 233 leading ! on either list specifies an exclusion list, names of
234 234 libraries or functions not to be traced. Excluding a library
235 235 excludes all functions in that library; any function list following
236 236 a library exclusion list is ignored.
237 237
238 238 A single : separating the library list from the function list means
239 239 to trace calls into the libraries from outside the libraries, but
240 240 omit calls made to functions in a library from other functions in
241 241 the same library. A double :: means to trace all calls, regardless
242 242 of origin.
243 243
244 244 Library patterns do not match either the executable file or the
245 245 dynamic linker unless there is an exact match (l* does not match
246 246 ld.so.1). To trace functions in either of these objects, the names
247 247 must be specified exactly, as in:
248 248
249 249 truss -u a.out -u ld ...
250 250
251 251
252 252 a.out is the literal name to be used for this purpose; it does not
253 253 stand for the name of the executable file. Tracing a.out function
254 254 calls implies all calls (default is ::).
255 255
256 256 Multiple -u options can be specified and they are honored left-to-
257 257 right. The id of the thread that performed the function call is
258 258 included in the trace output for the call. truss searches the
259 259 dynamic symbol table in each library to find function names and
260 260 also searches the standard symbol table if it has not been
261 261 stripped.
262 262
263 263
264 264 -U [!]lib,...:[:][!]func,...
265 265
266 266 User-level function calls that stop the process. The specified
267 267 functions are added to the set specified by -u. If one of the
268 268 specified functions is called, truss leaves the process stopped and
269 269 abandoned (see the -T option).
270 270
271 271
272 272 -v [!]syscall,...
273 273
274 274 Verbose. Displays the contents of any structures passed by address
275 275 to the specified system calls (if traced by -t). Input values as
276 276 well as values returned by the operating system are shown. For any
277 277 field used as both input and output, only the output value is
278 278 shown. Default is -v!all.
279 279
280 280
281 281 -w [!]fd,...
282 282
283 283 Shows the contents of the I/O buffer for each write() on any of the
284 284 specified file descriptors (see the -r option). Default is -w!all.
285 285
286 286
287 287 -x [!]syscall,...
288 288
289 289 Displays the arguments to the specified system calls (if traced by
290 290 -t) in raw form, usually hexadecimal, rather than symbolically.
291 291 This is for unredeemed hackers who must see the raw bits to be
292 292 happy. Default is -x!all.
293 293
294 294
295 295
296 296 See man pages section 2: System Calls for system call names accepted by
297 297 the -t, -T, -v, and -x options. System call numbers are also accepted.
298 298
299 299
300 300 If truss is used to initiate and trace a specified command and if the
301 301 -o option is used or if standard error is redirected to a non-terminal
302 302 file, then truss runs with hangup, interrupt, and quit signals ignored.
303 303 This facilitates tracing of interactive programs that catch interrupt
304 304 and quit signals from the terminal.
305 305
306 306
307 307 If the trace output remains directed to the terminal, or if existing
308 308 processes are traced (the -p option), then truss responds to hangup,
309 309 interrupt, and quit signals by releasing all traced processes and
310 310 exiting. This enables the user to terminate excessive trace output and
311 311 to release previously-existing processes. Released processes continue
312 312 normally, as though they had never been touched.
313 313
314 314 EXAMPLES
315 315 Example 1 Tracing a Command
316 316
317 317
318 318 The following example produces a trace of the find(1) command on the
319 319 terminal:
320 320
321 321
322 322 example$ truss find . -print >find.out
323 323
324 324
325 325
326 326 Example 2 Tracing Common System Calls
327 327
328 328
329 329 The following example shows only a trace of the open, close, read, and
330 330 write system calls:
331 331
332 332
333 333 example$ truss -t open,close,read,write find . -print >find.out
334 334
335 335
336 336
337 337 Example 3 Tracing a Shell Script
338 338
339 339
340 340 The following example produces a trace of the spell(1) command on the
341 341 file truss.out:
342 342
343 343
344 344 example$ truss -f -o truss.out spell document
345 345
346 346
|
↓ open down ↓ |
346 lines elided |
↑ open up ↑ |
347 347
348 348
349 349 spell is a shell script, so the -f flag is needed to trace not only the
350 350 shell but also the processes created by the shell. (The spell script
351 351 runs a pipeline of eight processes.)
352 352
353 353
354 354 Example 4 Abbreviating Output
355 355
356 356
357 - The following example abreviates output:
357 + The following example abbreviates output:
358 358
359 359
360 360 example$ truss nroff -mm document >nroff.out
361 361
362 362
363 363
364 364
365 365 because 97% of the output reports lseek(), read(), and write() system
366 366 calls. To abbreviate it:
367 367
368 368
369 369 example$ truss -t !lseek,read,write nroff -mm document >nroff.out
370 370
371 371
372 372
373 373 Example 5 Tracing Library Calls From Outside the C Library
374 374
375 375
376 376 The following example traces all user-level calls made to any function
377 377 in the C library from outside the C library:
378 378
379 379
380 380 example$ truss -u libc ...
381 381
382 382
383 383
384 384 Example 6 Tracing library calls from within the C library
385 385
386 386
387 387 The following example includes calls made to functions in the C library
388 388 from within the C library itself:
389 389
390 390
391 391 example$ truss -u libc:: ...
392 392
393 393
394 394
395 395 Example 7 Tracing Library Calls Other Than the C Library
396 396
397 397
398 398 The following example traces all user-level calls made to any library
399 399 other than the C library:
400 400
401 401
402 402 example$ truss -u '*' -u !libc ...
403 403
404 404
405 405
406 406 Example 8 Tracing printf and scanf Function Calls
407 407
408 408
409 409 The following example traces all user-level calls to functions in the
410 410 printf and scanf family contained in the C library:
411 411
412 412
413 413 example$ truss -u 'libc:*printf,*scanf' ...
414 414
415 415
416 416
417 417 Example 9 Tracing Every User-level Function Call
418 418
419 419
420 420 The following example traces every user-level function call from
421 421 anywhere to anywhere:
422 422
423 423
424 424 example$ truss -u a.out -u ld:: -u :: ...
425 425
426 426
427 427
428 428 Example 10 Tracing a System Call Verbosely
429 429
430 430
431 431 The following example verbosely traces the system call activity of
432 432 process #1, init(1M) (if you are a privileged user):
433 433
434 434
435 435 example# truss -p -v all 1
436 436
437 437
438 438
439 439
440 440 Interrupting truss returns init to normal operation.
441 441
442 442
443 443 FILES
444 444 /proc/*
445 445 Process files
446 446
447 447
448 448 SEE ALSO
449 449 date(1), find(1), proc(1), ps(1), sh(1), spell(1), init(1M), Intro(3),
450 450 exec(2), fork(2), lseek(2), open(2), read(2), time(2), vfork(2),
451 451 write(2), ctime(3C), signal.h(3HEAD), proc(4), attributes(5),
452 452 privileges(5), threads(5)
453 453
454 454
455 455 man pages section 2: System Calls
456 456
457 457 NOTES
458 458 Some of the system calls described in man pages section 2: System Calls
459 459 differ from the actual operating system interfaces. Do not be surprised
460 460 by minor deviations of the trace output from the descriptions in that
461 461 document.
462 462
463 463
464 464 Every machine fault (except a page fault) results in the posting of a
465 465 signal to the LWP that incurred the fault. A report of a received
466 466 signal immediately follows each report of a machine fault (except a
467 467 page fault) unless that signal is being blocked.
468 468
469 469
470 470 The operating system enforces certain security restrictions on the
471 471 tracing of processes. In particular, any command whose object file
472 472 (a.out) cannot be read by a user cannot be traced by that user; set-uid
473 473 and set-gid commands can be traced only by a privileged user. Unless it
474 474 is run by a privileged user, truss loses control of any process that
475 475 performs an exec() of a set-id or unreadable object file; such
476 476 processes continue normally, though independently of truss, from the
477 477 point of the exec().
478 478
479 479
480 480 To avoid collisions with other controlling processes, truss does not
481 481 trace a process that it detects is being controlled by another process
482 482 via the /proc interface. This allows truss to be applied to
483 483 proc(4)-based debuggers as well as to another instance of itself.
484 484
485 485
486 486 The trace output contains tab characters under the assumption that
487 487 standard tab stops are set (every eight positions).
488 488
489 489
490 490 The trace output for multiple processes or for a multithreaded process
491 491 (one that contains more than one LWP) is not produced in strict time
492 492 order. For example, a read() on a pipe can be reported before the
493 493 corresponding write(). For any one LWP (a traditional process contains
494 494 only one), the output is strictly time-ordered.
495 495
496 496
497 497 When tracing more than one process, truss runs as one controlling
498 498 process for each process being traced. For the example of the spell
499 499 command shown above, spell itself uses 9 process slots, one for the
500 500 shell and 8 for the 8-member pipeline, while truss adds another 9
501 501 processes, for a total of 18.
502 502
503 503
504 504 Not all possible structures passed in all possible system calls are
505 505 displayed under the -v option.
506 506
507 507
508 508
509 509 July 31, 2004 TRUSS(1)
|
↓ open down ↓ |
142 lines elided |
↑ open up ↑ |
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX