statvfs(), statvfs64()

QNX SDP8.0C Library ReferenceAPIDeveloper

Get filesystem information, given a path

Synopsis:

#include <sys/statvfs.h>

int statvfs( const char *path,
             struct statvfs *buf );

int statvfs64( const char *path,
               struct statvfs64 *buf );

Arguments:

path: The name of a file that resides on the filesystem.
buf: A pointer to a buffer where the function can store the information.

Library:

libc

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

Description:

The statvfs() and statvfs64() functions return a generic superblock describing a filesystem that you can use to acquire information about mounted filesystems. The fstatvfs() and fstatvfs64() functions are similar, but they take a file descriptor instead of a path.

Note:

The statvfs64() function is a large-file support version of statvfs() provided for backwards compatibility. If you're using large-file support functions and data types, you should define _LARGEFILE64_SOURCE with a value of 1 to ensure they appear in the name space. For more information, see Classification in What's in a Function Description?.

The filesystem type is known to the operating system. You don't need to have read, write, or execute permission for the named file, but all directories listed in the path name leading to the file must be searchable.

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 non-privileged process.

Note:

Many file systems do not have a concept of "privileged user". For those file systems, f_bavail will equal f_bfree, and f_favail will equal f_ffree.

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 non-privileged process.

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: This filesystem embeds inodes in directories, so the number of files is limited by the amount of disk space, so basically there's no limit. It doesn't count the number of files created either, so it sets all these fields to 0.
fs-qnx6.so: This filesystem has a fixed inodes table, so it fills in these fields.
fs-udf.so: This read-only filesystem always sets f_ffree and f_favail to 0. For fs-udf.so, it knows when a UDF is mounted—ISO formats don't indicate that information—so f_files is set to 0.
devf-*: Flash filesystem drivers estimate the values of these fields, based on the amount of free space.

The underlying resource managers provide this information via the DCMD_FSYS_STATVFS devctl() command.

Returns:

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

Errors:

EACCES: Search permission is denied on a component of the path prefix.
EFAULT: The path or buf argument points to an illegal address.
EINTR: A signal was caught during execution.
EIO: An I/O error occurred while reading the filesystem.
ELOOP: Too many symbolic links were encountered in translating path.
EMULTIHOP: Components of path require hopping to multiple remote machines and the filesystem type doesn't allow it.
ENAMETOOLONG: The length of path exceeds PATH_MAX.
ENOENT: Either a component of the path prefix or the file referred to by path doesn't exist.
ENOLINK: The path argument points to a remote machine and the link to that machine is no longer active.
ENOTDIR: A component of the path prefix of path isn't a directory.
EOVERFLOW: One of the values to be returned can't be represented correctly in the structure pointed to by buf.

Classification:

statvfs() is POSIX 1003.1; statvfs64() is Large-file support


Safety:
Cancellation point	No
Signal handler	Yes
Thread	Yes

Page updated: December 04, 2024