sc_usage.tproj/sc_usage.1

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