usr.bin/truss/truss.1

   1 .\" $FreeBSD$
   2 .\"
   3 .Dd September 3, 2004
   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 faedDS
  12 .Op Fl o Ar file
  13 .Fl p Ar pid
  14 .Nm
  15 .Op Fl faedDS
  16 .Op Fl o Ar file
  17 command
  18 .Op args
  19 .Sh DESCRIPTION
  20 The
  21 .Nm
  22 utility traces the system calls called by the specified process or program.
  23 Output is to the specified output file, or standard error by default.
  24 It does this by stopping and restarting the process being monitored via
  25 .Xr procfs 5 .
  26 .Pp
  27 The options are as follows:
  28 .Bl -tag -width indent
  29 .It Fl f
  30 Trace descendants of the original traced process created by
  31 .Xr fork 2 ,
  32 .Xr vfork 2 ,
  33 etc.
  34 .It Fl a
  35 Show the argument strings that are passed in each
  36 .Xr execve 2
  37 system call.
  38 .It Fl e
  39 Show the environment strings that are passed in each
  40 .Xr execve 2
  41 system call.
  42 .It Fl d
  43 Include timestamps in the output showing the time elapsed
  44 since the trace was started.
  45 .It Fl D
  46 Include timestamps in the output showing the time elapsed
  47 since the last recorded event.
  48 .It Fl S
  49 Do not display information about signals received by the process.
  50 (Normally,
  51 .Nm
  52 displays signal as well as system call events.)
  53 .It Fl o Ar file
  54 Print the output to the specified
  55 .Ar file
  56 instead of standard error.
  57 .It Fl p Ar pid
  58 Follow the process specified by
  59 .Ar pid
  60 instead of a new command.
  61 .It Ar command Op args
  62 Execute
  63 .Ar command
  64 and trace the system calls of it.
  65 (The
  66 .Fl p
  67 and
  68 .Ar command
  69 options are mutually exclusive.)
  70 .El
  71 .Pp
  72 The
  73 .Xr procctl 8
  74 utility can be used to clear tracepoints in a stuck process
  75 left behind if
  76 .Nm
  77 terminates abnormally.
  78 .Sh EXAMPLES
  79 # Follow the system calls used in echoing "hello"
  80 .Dl $ truss /bin/echo hello
  81 # Do the same, but put the output into a file
  82 .Dl $ truss -o /tmp/truss.out /bin/echo hello
  83 # Follow an already-running process
  84 .Dl $ truss -p 1
  85 .Sh SEE ALSO
  86 .Xr kdump 1 ,
  87 .Xr ktrace 1 ,
  88 .Xr procfs 5 ,
  89 .Xr procctl 8
  90 .Sh HISTORY
  91 The
  92 .Nm
  93 command was written by
  94 .An Sean Eric Fagan
  95 for
  96 .Fx .
  97 It was modeled after
  98 similar commands available for System V Release 4 and SunOS.