statvfs() — Get file system information

Standards

Standards / Extensions	C or C++	Dependencies
XPG4.2 Single UNIX Specification, Version 3	both

Format

#define _XOPEN_SOURCE_EXTENDED 1
#include <sys/statvfs.h>

int statvfs(const char *_restrict_ pathname, struct statvfs *_restrict_ fsinfo);

General description

The statvfs() function obtains information about the file system containing the file named by pathname and stores it in the area of memory pointed to by the fsinfo argument. The process does not need permissions on the file itself, but must have search permission on all directory components of the pathname.

The information is returned in the following statvfs structure, as defined in the sys/statvfs.h header file.

Table 1. Values Returned in statvfs Structure
Value	Description
char f_OEcbid[4]	The structure acronym (eye catcher).
int f_OEcblen	The length of the structure.
unsigned long f_bsize	The file system block size.
unsigned long f_blocks	The total number of blocks on the file system in units of f_frsize.
unsigned long f_OEusedspace	The allocated space in block size units.
unsigned long f_bavail	The number of free blocks available to non-privileged process.
unsigned long f_fsid	The file system ID.
unsigned long f_flag	A bit string indicating file system status.
int f_OEmaxfilesizehw	The high word of maximum file size.
unsigned long f_OEmaxfilesizelw	The low word of maximum file size.
unsigned long f_frsize	The fundamental file system block size.
unsigned long f_bfree	The total number of free blocks.
unsigned long f_files	The total number of file serial numbers.
unsigned long f_ffree	The total number of free file serial numbers.
unsigned long f_favail	The number of file serial numbers available to non-privileged process.
unsigned long f_namemax	The maximum file name length.
unsigned long f_OEinvarsec	The number of seconds the file system will remain unchanged.

The following flags can be returned in the f_flag member:

ST_RDONLY: read-only file system
ST_NOSUID: setuid/setgid bits ignored by exec
ST_OEEXPORTED: file system is exported

If statvfs() successfully determines this information, it stores in the area indicated by the fsinfo argument. The size of the buffer determines how much information is stored; data that exceeds the size of the buffer is truncated.

Returned value

If successful, statvfs() returns 0.

If unsuccessful, statvfs() returns -1 and sets errno to one of the following values:

Error Code: Description
EACCES: The process does not have search permission on some component of the pathname prefix.
EINTR: A signal was caught during the execution of the function.
EIO: An I/O error has occurred while reading the file system.
ELOOP: A loop exists in symbolic links encountered during resolution of the pathname argument. This error is issued if more than the system-defined limit of symbolic links, 8, are detected in the resolution of pathname.
ENAMETOOLONG: The length of the pathname exceeds PATH_MAX or a component of pathname is longer than NAME_MAX.
ENOENT: There is no file named pathname, or pathname is an empty string.
ENOTDIR: A component of the pathname prefix is not a directory.

Example

#include <sys/statvfs.h>
#include <stdio.h>

main() {
  int fd;
  struct statvfs buf;

  if (statvfs(".", &buf) == -1)
    perror("statvfs() error");
  else {
    printf("each block is %d bytes big\n", fs,
           buf.f_bsize);
    printf("there are %d blocks available out of a total of %d\n",
           buf.f_bavail, buf.f_blocks);
    printf("in bytes, that's %.0f bytes free out of a total of %.0f\n
           ((double)buf.f_bavail * buf.f_bsize),
           ((double)buf.f_blocks * buf.f_bsize));
  }
}

Output

each block is 4096 bytes big
there are 2089 blocks available out of a total of 2400
in bytes, that's 8556544 bytes free out of a total of 9830400