fstatvfs(), fstatvfs64()

Get filesystem information, given a file descriptor

Synopsis:

#include <sys/statvfs.h>

int fstatvfs( int fildes, 
              struct statvfs *buf );

int fstatvfs64( int fildes,
                struct statvfs64 *buf );

Arguments:

fildes
The descriptor for a file that resides on the filesystem that you want to get information about.
buf
A pointer to a buffer where the function can store information about the filesystem; see below.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The fstatvfs() function returns a "generic superblock" describing a filesystem; you can use it to get information about mounted filesystems. The fstatvfs64() function is a 64-bit version of fstatvfs(). The statvfs() and statvfs64() functions are similar, but they take a path name instead of a file descriptor.

The fildes argument is an open file descriptor, obtained from a successful call to open(), creat(), dup(), fcntl(), or pipe(), for a file that resides on that filesystem. The filesystem type is known to the operating system. Read, write, or execute permission for the named file isn't required.

The buf argument is a pointer to a statvfs or statvfs64 structure that's filled by the function. It contains at least:

unsigned long f_bsize
The preferred filesystem blocksize.
unsigned long f_frsize
The fundamental filesystem blocksize (if supported)
fsblkcnt_t f_blocks
The total number of blocks on the filesystem, in units of f_frsize.
fsblkcnt_t f_bfree
The total number of free blocks.
fsblkcnt_t f_bavail
The number of free blocks available to a nonsuperuser.
fsfilcnt_t f_files
The total number of file nodes (inodes).
fsfilcnt_t f_ffree
The total number of free file nodes.
fsfilcnt_t f_favail
The number of inodes available to a nonsuperuser.
unsigned long f_fsid
The filesystem ID (currently the device ID).
char f_basetype[16]
The type of the target filesystem, as a null-terminated string.
unsigned long f_flag
A bitmask of flags; the function can set these flags (the _MOUNT_* and ST_* bits are equivalent):
_MOUNT_* ST_* Meaning
_MOUNT_READONLY ST_RDONLY The filesystem is read-only.
_MOUNT_NOEXEC ST_NOEXEC The filesystem doesn't permit the loading of executables.
_MOUNT_NOSUID ST_NOSUID The filesystem doesn't support setuid() and setgid() semantics.
_MOUNT_NOCREAT ST_NOCREAT You can't create files on the filesystem.
_MOUNT_OFF32 ST_OFF32 The off_t type is limited to 32 bits.
_MOUNT_NOATIME ST_NOATIME The filesystem doesn't support the logging of file access times.
unsigned long f_namemax
The maximum filename length.

The values returned for f_files, f_ffree, and f_favail depend on the filesystem:

fs-dos.so, fs-qnx4.so
These filesystems embed inodes in directories, so the number of files is limited by the amount of disk space, so basically there's no limit. They don't count the number of files created either, so they set all these fields to 0.
fs-qnx6.so, fs-etfs-ram, fs-ext2.so
These filesystems have a fixed inodes table, so they fill in these fields.
fs-cd.so, fs-mac.so, fs-nt.so, fs-udf.so
Read-only fsystems always set f_ffree and f_favail to 0. Where possible or known, they try to set f_files:
  • fs-mac.so knows exactly
  • fs-nt.so provides an upper bound based on the current size of the Master File Table (MFT)
  • fs-udf.so knows when it's a UDF that's mounted; ISO formats don't indicate that information, so f_files is set to 0
  • fs-cd.so sets it to 0
fs-cifs
The CIFS filesystem sets these fields to 0.
devf-*
Flash filesystem drivers estimate the values of these fields, based on the amount of free space.

Returns:

0
Success.
-1
An error occurred (errno is set).

Errors:

EBADF
The fildes argument isn't an open file descriptor.
EFAULT
The buf argument points to an illegal address.
EINTR
A signal was caught during execution.
EIO
An I/O error occurred while reading the filesystem.
EOVERFLOW
One of the values to be returned can't be represented correctly in the structure pointed to by buf.

Classification:

fstatvfs() is POSIX 1003.1 XSI; fstatvfs64() is Large-file support

Safety:  
Cancellation point No
Interrupt handler No
Signal handler Yes
Thread Yes