fs_usage.tproj/fs_usage.1

   1
   2 .\" Copyright (c) 2000, Apple Computer, Inc.  All rights reserved.
   3 .\"
   4 .Dd March 28, 2000
   5 .Dt FS_USAGE 1
   6 .Os "Mac OS X"
   7 .Sh NAME
   8 .Nm fs_usage
   9 .Nd reports system calls and page faults related to filesystem activity
  10 in real-time.
  11 .Sh SYNOPSIS
  12 .Nm fs_usage [-e] [-w] [ pid|cmd [pid|cmd] ...]
  13 .Sh DESCRIPTION
  14 .Nm fs_usage
  15 presents an ongoing display of system call usage
  16 information pertaining to filesystem activity.  By default
  17 this includes all system processes except the running
  18 fs_usage process,
  19 Terminal, telnetd, sshd, rlogind, tcsh, csh and sh.
  20 These defaluts can be overridden such that output is limited to
  21 include or exclude a list of processes specified by the user.
  22 .Pp
  23 The output presented by
  24 .Nm fs_usage
  25 is formatted according to the size of your window.
  26 A narrow window will display fewer columns of data.
  27 Use a wide window for maximum data display.  You may
  28 override the window formatting restrictions by
  29 forcing a wide display with the
  30 .Fl w
  31 option.  In this case, the data displayed will wrap
  32 when the window is not wide enough.
  33 .Pp
  34 The options are as follows:
  35 .Bl -tag -width Ds
  36 .It Fl e
  37 Specifying the
  38 .Fl e
  39 option generates output that excludes sampling
  40 of the running fs_usage tool. If a list of
  41 process ids or commands is also given, then
  42 those processes are also excluded from the sampled
  43 output.
  44 .It Fl w
  45 Specifying the
  46 .Fl w
  47 option forces a wider, more detailed output,
  48 regardless of the window size.
  49 .It  pid | cmd
  50 The sampled data can be limited to a list of process
  51 ids or commands.  When a command name is given, all
  52 processes with that name will be sampled.  Using the
  53 .Fl e
  54 option has the opposite effect, excluding sampled data
  55 relating to the given list of process ids or commands.
  56 .El
  57 .Pp
  58 If "/tmp/FileTracing" is present when a Carbon Application
  59 is launched, then the high level Carbon FileManager
  60 calls will be displayed bracketing the system calls that they
  61 are built on.
  62 .Pp
  63 The data columns displayed are as follows:
  64 .Bl -tag -width TIME_INTERVALWWWW -compact
  65 .Pp
  66 .It TIMESTAMP
  67 TOD when call occurred. Wide mode will
  68 have millesecond granularity.
  69 .It CALL
  70 the name of the filesystem call or page-in.
  71 .It FILE DESCRIPTOR
  72 Of the form F=x, x is a file descriptor. Depending
  73 on the type of system call, this will be either
  74 an input value or a return value.
  75 .It BYTE COUNT
  76 Of the form B=x, x is the number of bytes requested by the call.
  77 .It [ERRNO]
  78 On error, the errno is displayed in brackets.
  79 .It PATHNAME
  80 Pathname of the file accessed (up to the last 28 bytes).
  81 .It FAULT ADDRESS
  82 Of the form A=0xnnnnnnnn, where 0xnnnnnnnn is the
  83 address being faulted.
  84 .It TIME INTERVAL(W)
  85 The elapsed time spent in the system call.
  86 A 'W' after the elapsed time indicates
  87 the process was scheduled out during
  88 this file activity.  In this case, the elapsed
  89 time includes the wait time.
  90 .It PROCESS NAME
  91 The process that made the system call.
  92 .El
  93 .Pp
  94 .Sh SAMPLE USAGE
  95 .Pp
  96 fs_usage -w telnetd
  97 .Pp
  98 .Nm fs_usage
  99 will report file system usage data for all
 100 instances of processes named telnetd.  Maximum
 101 data output will be displayed in the window.
 102 .Sh SEE ALSO
 103 .Xr top 1
 104 .Xr sc_usage 1
 105 .Xr latency 1