usr.bin/truss/truss.1

   1 .\" $FreeBSD$
   2 .\"
   3 .Dd May 12, 2009
   4 .Dt TRUSS 1
   5 .Os
   6 .Sh NAME
   7 .Nm truss
   8 .Nd trace system calls
   9 .Sh SYNOPSIS
  10 .Nm
  11 .Op Fl facedDS
  12 .Op Fl o Ar file
  13 .Op Fl s Ar strsize
  14 .Fl p Ar pid
  15 .Nm
  16 .Op Fl facedDS
  17 .Op Fl o Ar file
  18 .Op Fl s Ar strsize
  19 .Ar command Op Ar args
  20 .Sh DESCRIPTION
  21 The
  22 .Nm
  23 utility traces the system calls called by the specified process or program.
  24 Output is to the specified output file, or standard error by default.
  25 It does this by stopping and restarting the process being monitored via
  26 .Xr ptrace 2 .
  27 .Pp
  28 The options are as follows:
  29 .Bl -tag -width indent
  30 .It Fl f
  31 Trace descendants of the original traced process created by
  32 .Xr fork 2 ,
  33 .Xr vfork 2 ,
  34 etc.
  35 .It Fl a
  36 Show the argument strings that are passed in each
  37 .Xr execve 2
  38 system call.
  39 .It Fl c
  40 Do not display individual system calls.
  41 Instead, before exiting, print a summary containing for each system call:
  42 the total system time used,
  43 the number of times the call was invoked,
  44 and the number of times the call returned with an error.
  45 .It Fl e
  46 Show the environment strings that are passed in each
  47 .Xr execve 2
  48 system call.
  49 .It Fl d
  50 Include timestamps in the output showing the time elapsed
  51 since the trace was started.
  52 .It Fl D
  53 Include timestamps in the output showing the time elapsed
  54 since the last recorded event.
  55 .It Fl S
  56 Do not display information about signals received by the process.
  57 (Normally,
  58 .Nm
  59 displays signal as well as system call events.)
  60 .It Fl o Ar file
  61 Print the output to the specified
  62 .Ar file
  63 instead of standard error.
  64 .It Fl s Ar strsize
  65 Display strings using at most
  66 .Ar strsize
  67 characters.
  68 If the buffer is larger,
  69 .Dq Li ...
  70 will be displayed at the end of the string.
  71 The default
  72 .Ar strsize
  73 is 32.
  74 .It Fl p Ar pid
  75 Follow the process specified by
  76 .Ar pid
  77 instead of a new command.
  78 .It Ar command Op Ar args
  79 Execute
  80 .Ar command
  81 and trace the system calls of it.
  82 (The
  83 .Fl p
  84 and
  85 .Ar command
  86 options are mutually exclusive.)
  87 .El
  88 .Sh EXAMPLES
  89 # Follow the system calls used in echoing "hello"
  90 .Dl $ truss /bin/echo hello
  91 # Do the same, but put the output into a file
  92 .Dl $ truss -o /tmp/truss.out /bin/echo hello
  93 # Follow an already-running process
  94 .Dl $ truss -p 34
  95 .Sh SEE ALSO
  96 .Xr kdump 1 ,
  97 .Xr ktrace 1 ,
  98 .Xr ptrace 2
  99 .Sh HISTORY
 100 The
 101 .Nm
 102 command was written by
 103 .An Sean Eric Fagan
 104 for
 105 .Fx .
 106 It was modeled after
 107 similar commands available for System V Release 4 and SunOS.