-
.\" Copyright (c) 2000, Apple Computer, Inc. All rights reserved.
.\"
-.Dd November 26, 2001
+.Dd November 7, 2002
.Dt FS_USAGE 1
.Os "Mac OS X"
.Sh NAME
.Nm fs_usage
-.Nd reports system calls and page faults related to filesystem activity
-in real-time.
+.Nd report system calls and page faults related to filesystem activity in
+real-time
.Sh SYNOPSIS
-.Nm fs_usage [-e] [-w] [ pid|cmd [pid|cmd] ...]
+.Nm fs_usage [-e] [-w] [-f mode [-f mode] ...] [ pid|cmd [pid|cmd] ...]
.Sh DESCRIPTION
+The
.Nm fs_usage
-presents an ongoing display of system call usage
-information pertaining to filesystem activity. By default
-this includes all system processes except the running
-fs_usage process,
-Terminal, telnetd, sshd, rlogind, tcsh, csh and sh.
-These defaults can be overridden such that output is limited to
-include or exclude a list of processes specified by the user.
+utility presents an ongoing display of system call usage information
+pertaining to filesystem activity.
+It requires root privileges due to the kernel tracing facility it uses to
+operate.
+By default the activity monitored includes all system processes except the
+running
+.Nm fs_usage
+process, Terminal, telnetd, sshd, rlogind, tcsh, csh and sh.
+These defaults can be overridden such that output is limited to include or
+exclude a list of processes specified by the user.
.Pp
The output presented by
.Nm fs_usage
is formatted according to the size of your window.
A narrow window will display fewer columns of data.
-Use a wide window for maximum data display. You may
-override the window formatting restrictions by
-forcing a wide display with the
+Use a wide window for maximum data display.
+You may override the window formatting restrictions
+by forcing a wide display with the
.Fl w
-option. In this case, the data displayed will wrap
+option.
+In this case, the data displayed will wrap
when the window is not wide enough.
.Pp
The options are as follows:
.Bl -tag -width Ds
+.\" ==========
.It Fl e
Specifying the
.Fl e
option generates output that excludes sampling
-of the running fs_usage tool. If a list of
-process ids or commands is also given, then
-those processes are also excluded from the sampled
-output.
+of the running fs_usage tool.
+If a list of process ids or commands is also given,
+then those processes are also excluded from the sampled output.
+.\" ==========
+.It Fl f
+Specifying the
+.Fl f
+option turns on output filtering based on the
+.Pa mode
+provided.
+Multiple filtering options can be specified.
+By default no output filtering occurs.
+The supported modes are:
+.Pp
+.Pa network
+Only network related output is displayed.
+.Pp
+.Pa filesys
+Only file system related output is displayed.
+.Pp
+.Pa cachehit
+In addition, display CACHE_HIT output.
+.\" ==========
.It Fl w
Specifying the
.Fl w
option forces a wider, more detailed output,
regardless of the window size.
+.\" ==========
.It pid | cmd
-The sampled data can be limited to a list of process
-ids or commands. When a command name is given, all
-processes with that name will be sampled. Using the
+The sampled data can be limited to a list of process ids or commands.
+When a command name is given, all processes with that name will be sampled.
+Using the
.Fl e
-option has the opposite effect, excluding sampled data
-relating to the given list of process ids or commands.
+option has the opposite effect,
+excluding sampled data relating to the given list
+of process ids or commands.
.El
.Pp
-If you set the DYLD_IMAGE_SUFFIX environment variable
-to "_debug", then an application will use
-the debug version of all libraries including the
-Carbon FileManager. See dyld(1). When
-fs_usage is run against a Carbon Application launched
-in this environment, then the high level Carbon FileManager
-calls will be displayed bracketing the system calls that they
-are built on.
+If you set the DYLD_IMAGE_SUFFIX environment variable to
+.Dq Li _debug ,
+then an application will use the debug version of all libraries,
+including the Carbon FileManager.
+See
+.Xr dyld 1 .
+When
+.Nm fs_usage
+is run against a Carbon Application launched in this environment,
+then the high-level Carbon FileManager calls
+will be displayed bracketing the system calls that they are built on.
.Pp
The data columns displayed are as follows:
-.Bl -tag -width TIME_INTERVALWWWW -compact
+.Bl -tag -width Ds
.Pp
.It TIMESTAMP
-TOD when call occurred. Wide mode will
-have millisecond granularity.
+TOD when call occurred.
+Wide mode will have millisecond granularity.
.It CALL
-the name of the filesystem call, page-in, page-out or physical disk access.
+The name of the network or filesystem related call, page-in, page-out,
+or physical disk access.
.It FILE DESCRIPTOR
-Of the form F=x, x is a file descriptor. Depending
-on the type of system call, this will be either
-an input value or a return value.
+Of the form F=x, x is a file descriptor.
+Depending on the type of system call,
+this will be either an input value or a return value.
.It BYTE COUNT
Of the form B=x, x is the number of bytes requested by the call.
.It [ERRNO]
.It PATHNAME
Pathname of the file accessed (up to the last 28 bytes).
.It FAULT ADDRESS
-Of the form A=0xnnnnnnnn, where 0xnnnnnnnn is the
-address being faulted.
+Of the form A=0xnnnnnnnn,
+where 0xnnnnnnnn is the address being faulted.
.It DISK BLOCK NUMBER
-Of the form D=0xnnnnnnnn, where 0xnnnnnnnn is the block number
+Of the form D=0xnnnnnnnn,
+where 0xnnnnnnnn is the block number
of the physical disk block being read or written.
+.It OFFSET
+Of the form O=0xnnnnnnnn, where 0xnnnnnnnn is a file offset.
+.It SELECT RETURN
+Of the form S=x, x is the number of ready descriptors returned
+by the select() system call.
+If S=0, the time limit expired.
.It TIME INTERVAL(W)
The elapsed time spent in the system call.
-A 'W' after the elapsed time indicates
-the process was scheduled out during
-this file activity. In this case, the elapsed
-time includes the wait time.
+A
+.Sq Li W
+after the elapsed time indicates the process was scheduled out
+during this file activity.
+In this case, the elapsed time includes the wait time.
.It PROCESS NAME
The process that made the system call.
.El
.Pp
.Sh SAMPLE USAGE
.Pp
-fs_usage -w telnetd
+fs_usage -w -f filesys Mail
.Pp
.Nm fs_usage
-will report file system usage data for all
-instances of processes named telnetd. Maximum
-data output will be displayed in the window.
+will display file system related data
+for all instances of processes named Mail.
+Maximum data output will be displayed in the window.
.Sh SEE ALSO
+.Xr dyld 1 ,
+.Xr latency 1 ,
+.Xr sc_usage 1 ,
.Xr top 1
-.Xr sc_usage 1
-.Xr latency 1
-.Xr dyld 1
projects / apple / system_cmds.git / blobdiff