STATVFS(5)

STATVFS(5) | File Formats Manual | STATVFS(5)

# NAME

`statvfs` — file system statistics

# SYNOPSIS

`#include <sys/types.h>`
`#include <sys/statvfs.h>`

# DESCRIPTION

The `<sys/statvfs.h>` header defines the structures and functions that return information about a mounted file system. The `statvfs` structure is defined as follows:

    typedef struct { int32_t val[2]; } fsid_t;	/* file system id type */

    #define VFS_NAMELEN  32 	/* length of fs type name, including nul */
    #define VFS_MNAMELEN 1024	/* length of buffer for returned name */

    struct statvfs {
        unsigned long f_flag;	/* copy of mount exported flags */
        unsigned long f_bsize;	/* system block size */
        unsigned long f_frsize;	/* system fragment size */
        unsigned long f_iosize;	/* optimal file system block size */

        /* The following are in units of f_frsize */
        fsblkcnt_t	f_blocks;	/* number of blocks in file system */
        fsblkcnt_t	f_bfree;	/* free blocks avail in file system */
        fsblkcnt_t	f_bavail;	/* free blocks avail to non-root */
        fsblkcnt_t	f_bresvd;	/* blocks reserved for root */

        fsfilcnt_t	f_files;	/* total file nodes in file system */
        fsfilcnt_t	f_ffree;	/* free file nodes in file system */
        fsfilcnt_t	f_favail	/* free file nodes avail to non-root */
        fsfilcnt_t	f_fresvd;	/* file nodes reserved for root */

        uint64_t	f_syncreads;	/* count of sync reads since mount */
        uint64_t	f_syncwrites;	/* count of sync writes since mount */

        uint64_t	f_asyncreads;	/* count of async reads since mount */
        uint64_t	f_asyncwrites;	/* count of async writes since mount */

        fsid_t	f_fsidx;	/* NetBSD compatible file system id */
        unsigned long f_fsid;	/* POSIX compliant file system id */

        unsigned long f_namemax;	/* maximum filename length */
        uid_t	f_owner;	/* user that mounted the file system */

        uint64_t	f_spare[4];	/* spare space */

        char f_fstypename[VFS_NAMELEN];	/* fs type name */
        char f_mntonname[VFS_MNAMELEN];	/* directory on which mounted */
        char f_mntfromname[VFS_MNAMELEN];	/* mounted file system */
        char f_mntfromlabel[_VFS_MNAMELEN];	/* disk label name if avail */
    };

The f_flag argument can have the following bits set:

`ST_RDONLY`
  The filesystem is mounted read-only; Even the super-user may not write on it.
`ST_NOEXEC`
  Files may not be executed from the filesystem.
`ST_NOSUID`
  Setuid and setgid bits on files are not honored when they are executed.
`ST_NODEV`
  Special files in the filesystem may not be opened.
`ST_UNION`
  Union with underlying filesystem instead of obscuring it.
`ST_SYNCHRONOUS`
  All I/O to the filesystem is done synchronously.
`ST_ASYNC`
  No filesystem I/O is done synchronously.
`ST_NOCOREDUMP`
  Don't write core dumps to this file system.
`ST_NOATIME`
  Never update access times.
`ST_SYMPERM`
  Recognize symbolic link permission.
`ST_NODEVMTIME`
  Never update modification times for device files.
`ST_LOG`
  Use logging (journaling).
`ST_LOCAL`
  The filesystem resides locally.
`ST_QUOTA`
  The filesystem has quotas enabled on it.
`ST_ROOTFS`
  Identifies the root filesystem.
`ST_EXRDONLY`
  The filesystem is exported read-only.
`ST_EXPORTED`
  The filesystem is exported for both reading and writing.
`ST_DEFEXPORTED`
  The filesystem is exported for both reading and writing to any Internet host.
`ST_EXPORTANON`
  The filesystem maps all remote accesses to the anonymous user.
`ST_EXKERB`
  The filesystem is exported with Kerberos uid mapping.
`ST_EXNORESPORT`
  Don't enforce reserved ports (NFS).
`ST_EXPUBLIC`
  Public export (WebNFS).

Fields that are undefined for a particular file system are set to -1.

# NOTES

f_flag
  The f_flag field is the same as the f_flags field in the 4.3BSD `statfs` system call.
f_fsid
  Is defined to be unsigned long by the X/Open standard. Unfortunately this is not enough space to store our fsid_t, so we define an additional f_fsidx field.
f_bavail
  Could historically be negative (in the `statfs` system call) when the used space has exceeded the non-superuser free space. In order to comply with the X/Open standard, we have to define fsblkcnt_t as an unsigned type, so in all cases where f_bavail would have been negative, we set it to 0. In addition we provide f_bresvd which contains the amount of reserved blocks for the superuser, so the old value of f_bavail can be easily computed as:

      	old_bavail = f_bfree - f_bresvd;

# SEE ALSO

statvfs(2)

# HISTORY

The `<sys/statvfs.h>` header first appeared in NetBSD 3.0.

February 13, 2025 | NetBSD 11.0