X-Git-Url: https://git.saurik.com/apple/system_cmds.git/blobdiff_plain/2fc1e207eccd68aee093ed29dae719e77bac17dd..ac27e6b4e9f2f269ad11856171ae8e1f51fa26f0:/fs_usage.tproj/fs_usage.1 diff --git a/fs_usage.tproj/fs_usage.1 b/fs_usage.tproj/fs_usage.1 index 4479900..5fe9c95 100644 --- a/fs_usage.tproj/fs_usage.1 +++ b/fs_usage.tproj/fs_usage.1 @@ -8,7 +8,7 @@ .Nd report system calls and page faults related to filesystem activity in real-time .Sh SYNOPSIS -.Nm fs_usage [-e] [-w] [-f mode [-f mode] ...] [ pid|cmd [pid|cmd] ...] +.Nm fs_usage [-e] [-w] [-f mode] [-b] [-t seconds] [-R rawfile [-S start_time] [-E end_time]] [pid | cmd [pid | cmd] ...] .Sh DESCRIPTION The .Nm fs_usage @@ -16,7 +16,7 @@ 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 +By default, the activity monitored includes all system processes except the running .Nm fs_usage process, Terminal, telnetd, sshd, rlogind, tcsh, csh and sh. @@ -28,25 +28,30 @@ The output presented by 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 +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. +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. +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. +option forces a wider, more detailed output, +regardless of the window size. +.\" ========== .It Fl f Specifying the .Fl f @@ -54,50 +59,91 @@ option turns on output filtering based on the .Pa mode provided. Multiple filtering options can be specified. -By default no output filtering occurs. +By default, no output filtering occurs. The supported modes are: .Pp .Pa network -Only network related output is displayed. +Network-related events are displayed. .Pp .Pa filesys -Only file system related output is displayed. +Filesystem-related events are displayed. +.Pp +.Pa pathname +Pathname-related events are displayed. +.Pp +.Pa exec +Exec and spawn events are displayed. +.Pp +.Pa diskio +Disk I/O events are displayed. .Pp .Pa cachehit -In addition, display CACHE_HIT output. +In addition, show cache hits. +.\" ========== +.It Fl b +Specifying the +.Fl b +option annotates disk I/O events with BootCache info (if available). +.\" ========== +.It Fl t Ar seconds +Specifies a run timeout in seconds. +.Nm fs_usage +will run for no longer than the timeout specified. +.\" ========== +.It Fl R Ar raw_file +Specifies a raw trace file to process. +.\" ========== +.It Fl S Ar start_time +If +.Fl R +is selected, specifies the start time in microseconds to +begin processing entries from the raw trace file. Entries +with timestamps before the specified start time will be +skipped. +.\" ========== +.It Fl E Ar end_time +If +.Fl R +is selected, specifies the ending time in microseconds to +stop processing entries from the raw trace file. Entries +with timestamps beyond the specified ending time will be +skipped. +.\" ========== .It pid | cmd -The sampled data can be limited to a list of process ids or commands. +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 .Dq Li _debug , -then an application will use the debug version of all libraries including the -Carbon FileManager. +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. +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 Ds .Pp .It TIMESTAMP TOD when call occurred. -Wide mode will have millisecond granularity. +Wide mode will have microsecond granularity. .It CALL -The name of the network or filesystem related 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. +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] @@ -105,25 +151,28 @@ 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. +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. +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. +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 .Sq Li W -after the elapsed time indicates the process was scheduled out during this file -activity. +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. +The process that made the system call. Wide mode will append the +thread id to the process name (i.e Mail.nnn). .El .Pp .Sh SAMPLE USAGE @@ -131,10 +180,11 @@ The process that made the system call. fs_usage -w -f filesys Mail .Pp .Nm fs_usage -will display file system related data for all instances of processes named Mail. +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 top 1 , -.Xr sc_usage 1 , +.Xr dyld 1 , .Xr latency 1 , -.Xr dyld 1 +.Xr sc_usage 1 , +.Xr top 1