--- /dev/null
+Statfs
+~~~~~~
+
+The 'statfs' VFS method queries file-system-wide space and inode
+usage. For details about the MDS_STATFS RPC, including possible faults
+and error return codes, see <<mds-statfs-rpc>>, and for OST_STATFS see
+<<ost-statfs-rpc>>.
+
+A client gets 'statfs' information for the file system as a whole by
+first querying the individual storage targets for the 'statfs'
+information on each back-end file system. The RPCs that flow are as
+shown in <<statfs-rpcs>>. The values returned in the VFS call are
+built from the results of the *_STATFS RPCs as follows:
+
+.Statfs values
+[options="header"]
+|====
+| field | VFS value
+| 'f_type' | 0x0bd00bd0
+| 'f_bsize' | OST 'os_bsize'
+| 'f_blocks' | sum over OSTs 'os_blocks'
+| 'f_bfree' | sum over OSTs 'os_bfree'
+| 'f_bavail' | sum over OSTs 'os_bavail'
+| 'f_files' | sum over MDTs 'os_ffiles'
+| 'f_ffree' | sum over MDTs 'of_ffree'
+| 'f_fsid' | UUID
+| 'f_namelen' | maximum filename length
+|====
+
+See the discussion in <<struct-obd-statfs>> for details about the
+'obd_statfs' fields 'os_*'. In particular, the total and free objects
+counts would normally be determined by the corresponding values on the
+MDTs, but if the total objects available across all OSTs (respectively
+free objects) happens to be fewer than the number on the MDTs, then
+the smaller value is used. The number of free objects is modified as
+described below to ensure that at least this many new files can be
+created. The total number of objects is changed to preserve the
+difference 'f_files' - 'f_ffree', which is the current number of
+used objects. This is what "df" displays.
+
+The number of OST free objects is divided by the filesystem-wide
+default stripe count (i.e. the expected number of OST objects used per
+MDT file), so that 'f_ffree' represents the expected minimum number of
+files that can be created at the current time.
+
+The 'os_{bfree,bavail,blocks}' values are scaled down (in power-of-two
+increments) to match the maximum 'os_bsize' returned from any OST so
+that the sum of these fields makes sense, and potentially scaled down
+again (also in power-of-two increments) to increase 'f_bsize' to fit
+into the 'statfs' structure so that the 'f_blocks' field will fit into the
+available field width (which may only be 2^32 blocks on a 32-bit
+client).
+
+For most possible error conditions directly related to processing
+'statfs' information (ENOMEM, for instance) the error is propagated
+back to the VFS and the 'struct statfs' does not have valid
+information. In the case of an EAGAIN during an exchange of RPC
+messages, that error is handled transparently to the 'statfs' itself.
+
+.Statfs RPCs
+[[statfs-rpcs]]
+image::statfs_rpcs.png["statfs RPCs",height=150]
+
+//////////////////////////////////////////////////////////////////////
+The statfs_rpcs.png diagram resembles this text art:
+
+Time
+Step Client MDT OST
+ ------- ------- -------
+1 MDS_STATFS------>
+2 <------MDS_STATFS
+3 OST_STATFS------>
+4 <------OST_STATFS
+//////////////////////////////////////////////////////////////////////
+
+1 - The client issues an MDS_STATFS request to each MDT.
+
+The MDS_STATFS request is a so-called 'empty' RPC in that it consists
+only of the 'ptlrpc_body' (Lustre RPC descriptor) with the opcode set to
+MDS_STATFS (41). Refer to the discussion of <<mds-statfs-rpc>> for
+more general information about the MDS_STATFS RPC's request and reply
+messages.
+
+.MDS_STATFS Request Packet Structure
+
+:frame: none
+:grid: none
+[width="50%", cols="2a"]
+|====
+| request
+[cols="1"]
+!===================
+! <<struct-ptlrpc-body,ptlrpc_body>> !
+!===================
+|====
+
+2 - The MDS_STATFS reply returns 'statfs' info
+
+In addition to the 'ptlrpc_body' (Lustre RPC descriptor), the
+MDS_STATFS reply to the client has the 'obd_statfs' structure. For a
+detailed discussion of the fields in the 'obd_statfs' refer to
+<<struct-obd-statfs>>.
+
+.MDS_STATFS Reply Packet Structure
+
+:frame: none
+:grid: none
+[width="50%", cols="2a"]
+|====
+| reply
+[cols="2"]
+!===================
+! <<struct-ptlrpc-body,ptlrpc_body>> ! <<struct-obd-statfs,obd_statfs>> !
+!===================
+|====
+
+3 - The client issues an OST_STATFS request to each OST.
+
+The OST_STATFS RPC looks just like the MDS_STATFS, except the opcode
+is 13 instead of 41 and the target of the RPC is an OST instead of an
+MDT.
+
+.OST_STATFS Request Packet Structure
+
+:frame: none
+:grid: none
+[width="50%", cols="2a"]
+|====
+| request
+[cols="1"]
+!===================
+! <<struct-ptlrpc-body,ptlrpc_body>> !
+!===================
+|====
+
+
+4 - The OST_STATFS reply returns 'statfs' info
+
+In addition to the 'ptlrpc_body' (Lustre RPC descriptor), the OST_STATFS
+reply to the client has the 'obd_statfs' structure. For a detailed
+discussion of the fields in the 'obd_statfs' refer to
+<<struct-obd-statfs>>.
+
+.OST_STATFS Reply Packet Structure
+
+:frame: none
+:grid: none
+[width="50%", cols="2a"]
+|====
+| reply
+[cols="2"]
+!===================
+! <<struct-ptlrpc-body,ptlrpc_body>> ! <<struct-obd-statfs,obd_statfs>> !
+!===================
+|====
git://git.whamcloud.com / doc / protocol.git / blobdiff