fs_usage.tproj/fs_usage.1

   1
   2 .\" Copyright (c) 2000, Apple Computer, Inc.  All rights reserved.
   3 .\"
   4 .Dd November 26, 2001
   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 defaults 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 you set the DYLD_IMAGE_SUFFIX environment variable
  59 to "_debug", then an application will use
  60 the debug version of all libraries including the
  61 Carbon FileManager.  See dyld(1).  When
  62 fs_usage is run against a Carbon Application launched
  63 in this environment, then the high level Carbon FileManager
  64 calls will be displayed bracketing the system calls that they
  65 are built on.
  66 .Pp
  67 The data columns displayed are as follows:
  68 .Bl -tag -width TIME_INTERVALWWWW -compact
  69 .Pp
  70 .It TIMESTAMP
  71 TOD when call occurred. Wide mode will
  72 have millisecond granularity.
  73 .It CALL
  74 the name of the filesystem call, page-in, page-out or physical disk access.
  75 .It FILE DESCRIPTOR
  76 Of the form F=x, x is a file descriptor. Depending
  77 on the type of system call, this will be either
  78 an input value or a return value.
  79 .It BYTE COUNT
  80 Of the form B=x, x is the number of bytes requested by the call.
  81 .It [ERRNO]
  82 On error, the errno is displayed in brackets.
  83 .It PATHNAME
  84 Pathname of the file accessed (up to the last 28 bytes).
  85 .It FAULT ADDRESS
  86 Of the form A=0xnnnnnnnn, where 0xnnnnnnnn is the
  87 address being faulted.
  88 .It DISK BLOCK NUMBER
  89 Of the form D=0xnnnnnnnn, where 0xnnnnnnnn is the block number
  90 of the physical disk block being read or written.
  91 .It TIME INTERVAL(W)
  92 The elapsed time spent in the system call.
  93 A 'W' after the elapsed time indicates
  94 the process was scheduled out during
  95 this file activity.  In this case, the elapsed
  96 time includes the wait time.
  97 .It PROCESS NAME
  98 The process that made the system call.
  99 .El
 100 .Pp
 101 .Sh SAMPLE USAGE
 102 .Pp
 103 fs_usage -w telnetd
 104 .Pp
 105 .Nm fs_usage
 106 will report file system usage data for all
 107 instances of processes named telnetd.  Maximum
 108 data output will be displayed in the window.
 109 .Sh SEE ALSO
 110 .Xr top 1
 111 .Xr sc_usage 1
 112 .Xr latency 1
 113 .Xr dyld 1