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>> !
!===================
|====