system_cmds/sc_usage.tproj/sc_usage.1

   1 .\" Copyright (c) 2000, Apple Computer, Inc.  All rights reserved.
   2 .\"
   3 .Dd October 28, 2002
   4 .Dt SC_USAGE 1
   5 .Os "Mac OS X"
   6 .Sh NAME
   7 .Nm sc_usage
   8 .Nd show system call usage statistics
   9 .Sh SYNOPSIS
  10 .Nm sc_usage
  11 .Op Fl c Ar codefile
  12 .Op Fl e
  13 .Op Fl l
  14 .Op Fl s Ar interval
  15 pid | cmd |
  16 .Fl E
  17 execute
  18 .Sh DESCRIPTION
  19 .Nm sc_usage
  20 displays an ongoing sample of system call and page fault usage statistics for
  21 a given process in a
  22 .Dq Li top-like
  23 fashion.
  24 It requires root privileges due to the kernel tracing facility it uses to
  25 operate.
  26 .Pp
  27 Page faults can be of the following types:
  28 .Bl -tag -width CACHEHITTT -compact
  29 .It PAGE_IN
  30 page had to read from disk
  31 .It ZERO_FILL
  32 page was created and zero filled
  33 .It COW
  34 page was copied from another page
  35 .It CACHE_HIT
  36 page was found in the cache
  37 .El
  38 .Pp
  39 The arguments are as follows:
  40 .Bl -tag -width Ds
  41 .It Fl c
  42 When the
  43 .Fl c
  44 option is specified, it expects a path to a
  45 .Ar codefile
  46 that
  47 contains the mappings for the system calls.
  48 This option overrides the default location of the system call codefile which
  49 is found in /usr/share/misc/trace.codes.
  50 .It Fl e
  51 Specifying the
  52 .Fl e
  53 option generates output that is sorted by call count.
  54 This overrides the default sort by time.
  55 .It Fl l
  56 The
  57 .Fl l
  58 option causes
  59 .Nm sc_usage
  60 to turn off its continuous window updating style of output and instead output
  61 as a continuous scrolling of data.
  62 .It Fl s
  63 By default,
  64 .Nm sc_usage
  65 updates its output at one second intervals.
  66 This sampling interval may be changed by specifying the
  67 .Fl s
  68 option.
  69 Enter the
  70 .Ar interval
  71 in seconds.
  72 .It pid | cmd | -E execute
  73 The last argument must be a process id, a running command name, or using the
  74 .Fl E
  75 option, an execution path followed by optional arguments.
  76 The system call usage data for the process or command is displayed.
  77 If the
  78 .Fl E
  79 flag is used, sc_usage will launch the executable, pass along any optional
  80 arguments and display system call usage date for that executable.
  81 .El
  82 .Pp
  83 The data columns displayed are as follows:
  84 .Bl -tag -width LAST_PATHNAME_WAITED_FOR -compact
  85 .Pp
  86 .It TYPE
  87 the system call type
  88 .It NUMBER
  89 the system call count
  90 .It CPU_TIME
  91 the amount of cpu time consumed
  92 .It WAIT_TIME
  93 the absolute time the process is waiting
  94 .It CURRENT_TYPE
  95 the current system call type
  96 .It LAST_PATHNAME_WAITED_FOR
  97 for each active thread, the last pathname
  98 that was referenced by a system call that blocked
  99 .It CUR_WAIT_TIME
 100 the cumulative time that a thread has been blocked
 101 .It THRD#
 102 the thread number
 103 .It PRI
 104 current scheduling priority
 105 .El
 106 .Pp
 107 The
 108 .Nm sc_usage
 109 command also displays some global state in the first few lines of output,
 110 including the number of preemptions, context switches, threads, faults and
 111 system calls, found during the sampling period.
 112 The current time and the elapsed time that the command has been running is also
 113 displayed here.
 114 The
 115 .Nm sc_usage
 116 command is also SIGWINCH savvy, so adjusting your window geometry may change
 117 the list of system calls being displayed.
 118 Typing a
 119 .Sq Li q
 120 will cause sc_usage to exit immediately.
 121 Typing any other character will cause sc_usage to reset its counters and the
 122 display.
 123 .Sh SAMPLE USAGE
 124 .Pp
 125 sc_usage Finder -e -s2
 126 .Pp
 127 .Nm sc_usage
 128 will sort the Finder process usage data according to system call count and
 129 update the output at 2 second intervals.
 130 .Sh SEE ALSO
 131 .Xr fs_usage 1 ,
 132 .Xr latency 1 ,
 133 .Xr top 1