path: root/usr/src/man/man1m/fsstat.1m

'\" te
.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH FSSTAT 1M "Jan 5, 2007"
.SH NAME
fsstat \- report file system statistics
.SH SYNOPSIS
.LP
.nf
\fBfsstat\fR [\fB-a|f|i|n|v\fR] [\fB-T\fR | u|d] {\fB-F\fR | {\fIfstype\fR|\fIpath\fR}...}
     [\fIinterval\fR [\fIcount\fR]]
.fi

.SH DESCRIPTION
.sp
.LP
\fBfsstat\fR reports kernel file operation activity by the file system type
(\fIfstype\fR) or by the path name, which is converted to a mount point. The
first set of lines of output reports all activity since:
.RS +4
.TP
.ie t \(bu
.el o
The file system module was loaded (in the case of \fIfstype\fR)
.RE
.RS +4
.TP
.ie t \(bu
.el o
The file system was mounted (in the case of mount point)
.RE
.sp
.LP
Statistics are gathered at the file system independent layer at both the
\fIfstype\fR and the mount point levels. However, not all file system types are
represented in the gathering of statistics. (See the NOTES section of this man
page.)
.sp
.LP
The output of \fBfsstat\fR is dependent on the mode (option) requested. All
statistic fields are displayed using "smart numbers" which automatically scale
the units in a human readable form that fits in a maximum of 5 characters. For
example:
.sp
.ne 2
.na
\fB100\fR
.ad
.RS 11n
is displayed as 100
.RE

.sp
.ne 2
.na
\fB2048\fR
.ad
.RS 11n
is displayed as 2K
.RE

.sp
.ne 2
.na
\fB3000000\fR
.ad
.RS 11n
is displayed as 2.86M
.RE

.sp
.LP
The unit modifiers are: K (Kbyte), M (Mbyte), G (Gbyte), T (terabyte), P
(petabyte), and E (exabyte).
.sp
.LP
During the execution of \fBfsstat\fR, the state of the system can change. If
relevant, a state change message is included in the \fBfsstat\fR output in one
of the following forms:
.sp
.in +2
.nf
<<mount point no longer available: {path}>>
<<file system module no longer loaded: {fstype}>>
.fi
.in -2
.sp

.sp
.LP
After the state change messages are displayed, \fBfsstat\fR continues to
display the statistics as directed. If all of the \fIfstypes\fR and mount
points that \fBfsstat\fR was reporting on are no longer available, then
\fBfsstat\fR exits.
.sp
.LP
The user is required to specify the \fB-F\fR option (all available file system
types) or a list of one or more \fIfstypes\fR and/or mount points.
.sp
.LP
The default report shows general file system activity. This display combines
similar operations into general categories as follows:
.sp
.ne 2
.na
\fBnew file\fR
.ad
.RS 15n
Number of creation operations for file system objects (for example, files,
directories, symlinks, etc.)
.RE

.sp
.ne 2
.na
\fBname remov\fR
.ad
.RS 15n
Number of name removal operations
.RE

.sp
.ne 2
.na
\fBname chng\fR
.ad
.RS 15n
Number of name change operations
.RE

.sp
.ne 2
.na
\fBattr get\fR
.ad
.RS 15n
Number of object attribute retrieval operations
.RE

.sp
.ne 2
.na
\fBattr set\fR
.ad
.RS 15n
Number of object attribute change operations
.RE

.sp
.ne 2
.na
\fBlookup ops\fR
.ad
.RS 15n
Number of object lookup operations
.RE

.sp
.ne 2
.na
\fBrddir ops\fR
.ad
.RS 15n
Number of read directory operations
.RE

.sp
.ne 2
.na
\fBread ops\fR
.ad
.RS 15n
Number of data read operations
.RE

.sp
.ne 2
.na
\fBread bytes\fR
.ad
.RS 15n
Bytes transferred by data read operations
.RE

.sp
.ne 2
.na
\fBwrite ops\fR
.ad
.RS 15n
Number of data write operations
.RE

.sp
.ne 2
.na
\fBwrite bytes\fR
.ad
.RS 15n
Bytes transferred by data write operations
.RE

.sp
.LP
The entity being reported on (\fIfstype\fR or mount point) is displayed in the
last column.
.SH OPTIONS
.sp
.LP
The following options are supported:
.sp
.ne 2
.na
\fB\fB-a\fR\fR
.ad
.RS 10n
Report the activity for kernel attribute operations. The following statistics
are reported:
.sp
.ne 2
.na
\fBgetattr\fR
.ad
.RS 11n
Number of file attribute retrieval calls
.RE

.sp
.ne 2
.na
\fBsetattr\fR
.ad
.RS 11n
Number of file attribute modification calls
.RE

.sp
.ne 2
.na
\fBgetsec\fR
.ad
.RS 11n
Number of file security attribute retrieval calls
.RE

.sp
.ne 2
.na
\fBsetsec\fR
.ad
.RS 11n
Number of file security attribute modification calls
.RE

The entity being reported on (\fIfstype\fR or mount point) is displayed in the
last column.
.RE

.sp
.ne 2
.na
\fB\fB-f\fR\fR
.ad
.RS 10n
Report the full activity for all kernel file operations. Each file operation is
listed in the left column. The following statistics are reported for each
operation:
.sp
.ne 2
.na
\fB#ops\fR
.ad
.RS 9n
Number of calls for this operation
.RE

.sp
.ne 2
.na
\fBbytes\fR
.ad
.RS 9n
Average transfer size in bytes (only applies to read, write, readdir)
.RE

The entity being reported on (\fIfstype\fR or mount point) is displayed in the
first row.
.RE

.sp
.ne 2
.na
\fB\fB-i\fR\fR
.ad
.RS 10n
Reports the activity for kernel I/O operations. The following statistics are
reported:
.sp
.ne 2
.na
\fBread ops\fR
.ad
.RS 15n
Number of data read calls
.RE

.sp
.ne 2
.na
\fBread bytes\fR
.ad
.RS 15n
Number of bytes read
.RE

.sp
.ne 2
.na
\fBwrite ops\fR
.ad
.RS 15n
Number of data write calls
.RE

.sp
.ne 2
.na
\fBwrite bytes\fR
.ad
.RS 15n
Number of bytes written
.RE

.sp
.ne 2
.na
\fBrddir ops\fR
.ad
.RS 15n
Number of read directory calls
.RE

.sp
.ne 2
.na
\fBrddir bytes\fR
.ad
.RS 15n
Number of bytes read by reading directories
.RE

.sp
.ne 2
.na
\fBrwlock ops\fR
.ad
.RS 15n
Number of internal file system lock operations
.RE

.sp
.ne 2
.na
\fBrwulock ops\fR
.ad
.RS 15n
Number of internal file system unlock operations
.RE

The entity being reported on (\fIfstype\fR or mount point) is displayed in the
last column.
.RE

.sp
.ne 2
.na
\fB\fB-n\fR\fR
.ad
.RS 10n
Reports the activity for kernel naming operations. The following statistics are
reported:
.sp
.ne 2
.na
\fBlookup\fR
.ad
.RS 11n
Number of file name retrieval calls
.RE

.sp
.ne 2
.na
\fBcreat\fR
.ad
.RS 11n
Number of file creation calls
.RE

.sp
.ne 2
.na
\fBremov\fR
.ad
.RS 11n
Number of file remove calls
.RE

.sp
.ne 2
.na
\fBlink\fR
.ad
.RS 11n
Number of link calls
.RE

.sp
.ne 2
.na
\fBrenam\fR
.ad
.RS 11n
Number of file renaming calls
.RE

.sp
.ne 2
.na
\fBmkdir\fR
.ad
.RS 11n
Number of directory creation calls
.RE

.sp
.ne 2
.na
\fBrmdir\fR
.ad
.RS 11n
Number of directory removal calls
.RE

.sp
.ne 2
.na
\fBrddir\fR
.ad
.RS 11n
Number of directory read calls
.RE

.sp
.ne 2
.na
\fBsymlink\fR
.ad
.RS 11n
Number of symlink creation calls
.RE

.sp
.ne 2
.na
\fBrdlink\fR
.ad
.RS 11n
Number of symlink read calls
.RE

The entity being reported on (\fIfstype\fR or mount point) is displayed in the
last column.
.RE

.sp
.ne 2
.na
\fB\fB-v\fR\fR
.ad
.RS 10n
Reports the activity for calls to the virtual memory operations. The following
statistics are reported.
.sp
.ne 2
.na
\fBmap\fR
.ad
.RS 10n
Number of calls mapping a file
.RE

.sp
.ne 2
.na
\fBaddmap\fR
.ad
.RS 10n
Number of calls setting additional mapping to a mapped file
.RE

.sp
.ne 2
.na
\fBdelmap\fR
.ad
.RS 10n
Number of calls deleting mapping to a file
.RE

.sp
.ne 2
.na
\fBgetpag\fR
.ad
.RS 10n
Number of calls retrieving a page of data from a file
.RE

.sp
.ne 2
.na
\fBputpag\fR
.ad
.RS 10n
Number of calls writing a page of data to a file
.RE

.sp
.ne 2
.na
\fBpagio\fR
.ad
.RS 10n
Number of calls to transfer pages in file system swap files
.RE

The entity being reported on (fstype or mount point) is displayed in the last
column.
.RE

.sp
.ne 2
.na
\fB\fB-F\fR\fR
.ad
.RS 10n
Report on all available file system types.
.RE

.sp
.ne 2
.na
\fB\fB-T\fR \fIu\fR|\fId\fR\fR
.ad
.RS 10n
Display a time stamp.
.sp
Specify \fIu\fR for a printed representation of the internal representation of
time (see \fBtime\fR(2)) Specify \fId\fR for the standard date format. (See
\fBdate\fR(1)). The time stamp is only used when an interval is set.
.RE

.SH OPERANDS
.sp
.LP
The following operands are supported:
.sp
.ne 2
.na
\fB\fIcount\fR\fR
.ad
.RS 12n
Display only \fIcount\fR reports.
.RE

.sp
.ne 2
.na
\fB\fIfstype\fR\fR
.ad
.RS 12n
Explicitly specify the file system type(s) to be reported. The file system
module must be loaded.
.RE

.sp
.ne 2
.na
\fB\fIinterval\fR\fR
.ad
.RS 12n
Report once each \fIinterval\fR seconds.
.RE

.sp
.ne 2
.na
\fB\fIpath\fR\fR
.ad
.RS 12n
Specify the path(s) of the mount point(s) to be reported. If path is not a
mount point, the mount point containing path will be determined and displayed
in the output.
.RE

.sp
.LP
If no \fIinterval\fR and no \fIcount\fR are specified, a single report is
printed and \fBfsstat\fR exits. If an \fIinterval\fR is specified but no
\fIcount\fR is specified, \fBfsstat\fR prints reports every \fIinterval\fR
seconds indefinitely until the command is interrupted.
.SH EXAMPLES
.LP
\fBExample 1 \fRDisplaying General Activity
.sp
.LP
The following example shows general activity for all file system types.

.sp
.in +2
.nf
\fB$ fsstat -F\fR
 new  name   name  attr   attr lookup rddir  read read  write write
 file remov  chng   get    set    ops   ops   ops bytes   ops bytes
  313K  214K 38.5K 2.16M 56.2K  8.36M 52.8K 19.7M 39.9G 18.8M 39.1G ufs
     0     0     0 2.95K     0  3.81K   282 2.52K  466K     0     0 proc
     0     0     0     0     0      0     0     0     0     0     0 nfs
    10     8     2    86     9     98    15   413  103M 8.43K 1.05G zfs
    13    14     4    98    16    125    10 1.01K  258M 15.9K  127M lofs
8.73K 3.29K 5.25K 55.3K    37  1.20M    44 37.9K 38.3M 47.2K 35.9M tmpfs
     0     0     0 4.93K     0      0     0 1.08K  913K     0     0 mntfs
     3     2     1   503     3    897    13   122 25.8K   128  272K nfs3
    10     8     0   615    10  10.1K    18    61 45.6K   292 2.26M nfs4
.fi
.in -2
.sp

.LP
\fBExample 2 \fRDisplaying Naming Activity
.sp
.LP
The following example shows the naming activity for ufs, nfs, nfs3, nfs4, and
tmpfs:

.sp
.in +2
.nf
\fB$ fsstat -n ufs nfs nfs3 nfs4 tmpfs\fR
lookup creat remov  link renam mkdir rmdir rddir symlnk rdlnk
3.57M  3.10K   586     6    24   115   100 30.2K      5  330K ufs
    0      0     0     0     0     0     0     0      0     0 nfs
18.3K      3     5     0     0     0     0 1.03K      2   346 nfs3
  535      0     0     0     0     0     0    46      0     4 nfs4
  146     24    15     0     0     4     0     4      0     0 tmpfs
.fi
.in -2
.sp

.LP
\fBExample 3 \fRDisplaying Attribute Activity
.sp
.LP
The following example shows the attribute activity for the FS type ufs and the
mounted file systems "/" and "/export/home" every three seconds for every third
iteration:

.sp
.in +2
.nf
\fB# fsstat -a ufs / /export/home 3 3\fR
getattr setattr getsec setsec
  378K    91.9K  11.8K      0 ufs
  367K    82.3K  11.6K      0 /
 11.3K     9.6K    198      0 /export/home
 4.97K    2.27K    163      0 ufs
 3.94K    1.36K    162      0 /
 1.03K      927      1      0 /export/home
 2.30K    1.06K     73      0 ufs
 1.95K      766     71      0 /
   361      317      2      0 /export/home
 2.33K    1.06K     78      0 ufs
 1.64K      451     77      0 /
   711      631      1      0 /export/home
.fi
.in -2
.sp

.LP
\fBExample 4 \fRDisplaying File Operation Statistics
.sp
.LP
The following example shows the statistics for each file operation for "/"
(using the \fB-f\fR option):

.sp
.in +2
.nf
\fB$ fsstat -f /\fR
Mountpoint: /
 operation  #ops  bytes
      open 8.54K
     close  9.8K
      read 43.6K  65.9M
     write 1.57K  2.99M
     ioctl 2.06K
     setfl     4
   getattr 40.3K
   setattr    38
    access 9.19K
    lookup  203K
    create   595
    remove    56
      link     0
    rename     9
     mkdir    19
     rmdir     0
   readdir 2.02K  2.27M
   symlink     4
  readlink 8.31K
     fsync   199
  inactive 2.96K
       fid     0
    rwlock 47.2K
  rwunlock 47.2K
      seek 29.1K
       cmp 42.9K
    frlock 4.45K
     space     8
    realvp 3.25K
   getpage  104K
   putpage 2.69K
       map 13.2K
    addmap 34.4K
    delmap 33.4K
      poll   287
      dump     0
  pathconf    54
    pageio     0
   dumpctl     0
   dispose 23.8K
getsecattr   697
setsecattr     0
   shrlock     0
   vnevent     0
.fi
.in -2
.sp

.SH ENVIRONMENT VARIABLES
.sp
.LP
See \fBenviron\fR(5) for descriptions of the following environment variables
that affect the execution of \fBfsstat\fR: \fBLANG\fR, \fBLC_ALL\fR,
\fBLC_CTYPE\fR,  \fBLC_MESSAGES\fR,  \fBLC_TIME\fR, and \fBNLSPATH\fR.
.SH EXIT STATUS
.sp
.LP
The following exit values are returned:
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.RS 5n
Successful completion.
.RE

.sp
.ne 2
.na
\fB\fB1\fR\fR
.ad
.RS 5n
A fatal error occurred. A fatal error could be a failed system call or another
internal error.
.RE

.sp
.ne 2
.na
\fB\fB2\fR\fR
.ad
.RS 5n
Invalid command-line options were specified.
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
CSI	Enabled
_
Interface Stability	See below.
.TE

.sp
.LP
The command-line options are Unstable. The human-readable output is not
considered an interface.
.SH SEE ALSO
.sp
.LP
\fBdate\fR(1), \fBtime\fR(2), \fBattributes\fR(5)
.SH NOTES
.sp
.LP
All display options (\fB-a\fR, \fB-f\fR, \fB-i\fR, \fB-n\fR, \fB-v\fR) are
mutually exclusive. Entering more than one of these options will result in an
error.
.sp
.LP
The \fIfstype\fR and \fIpath\fR operands must appear after the option, but
before the \fIinterval\fR or \fIcount\fR on the command line. For example,
"\fBfsstat\fR \fB-a\fR \fIfstype\fR \fIinterval\fR". Preference is given to
\fIfstype\fR so that if a user wishes to see the statistics for a directory
that has the same name as an \fIfstype\fR (for example, ufs), then the path
must be specified unambiguously (for example, ./ufs). Similarly, in order to
define a file with a numeric name (for example, "10") from an interval or count
operand, the name should be prefixed accordingly (for example, ./10).
.sp
.LP
When an interval is used, headers repeat after more than 12 lines of statistics
have been displayed and the set of lines to be displayed in the current
interval have completed.
.sp
.LP
Statistics are not displayed for all pseudo-filesystems. The output displayed
with the \fB-F\fR option shows which of the loaded filesystem types are
supported.
.sp
.LP
Unbundled file systems may not be recognized by \fBfsstat\fR.
.sp
.LP
The command-line options are classified as Unstable and could change. The
output is not considered to be an interface. The construction of higher level
software tools depend on either the command-line options or the output of
\fBfsstat\fR is not recommended.