system_cmds-230.tar.gz

[apple/system_cmds.git] / fs_usage.tproj / fs_usage.1

.\" Copyright (c) 2000, Apple Computer, Inc.  All rights reserved.
.\"
.Dd November 26, 2001
.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.
.Sh SYNOPSIS
.Nm fs_usage [-e] [-w] [ pid|cmd [pid|cmd] ...]
.Sh DESCRIPTION
.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.
.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
.Fl w
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.
.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
.Fl e
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.
.Pp
The data columns displayed are as follows:
.Bl -tag -width TIME_INTERVALWWWW -compact
.Pp
.It TIMESTAMP
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.
.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.
.It BYTE COUNT
Of the form B=x, x is the number of bytes requested by the call.
.It [ERRNO]
On error, the errno is displayed in brackets.
.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.
.It DISK BLOCK NUMBER
Of the form D=0xnnnnnnnn, where 0xnnnnnnnn is the block number
of the physical disk block being read or written.
.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.
.It PROCESS NAME
The process that made the system call.
.El
.Pp
.Sh SAMPLE USAGE
.Pp
fs_usage -w telnetd
.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.
.Sh SEE ALSO
.Xr top 1
.Xr sc_usage 1
.Xr latency 1
.Xr dyld 1