summaryrefslogtreecommitdiffstats
path: root/man3/statvfs.3
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--man3/statvfs.3257
1 files changed, 257 insertions, 0 deletions
diff --git a/man3/statvfs.3 b/man3/statvfs.3
new file mode 100644
index 0000000..9b1978b
--- /dev/null
+++ b/man3/statvfs.3
@@ -0,0 +1,257 @@
+'\" t
+.\" Copyright (C) 2003 Andries Brouwer (aeb@cwi.nl)
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\" The pathconf note is from Walter Harms
+.\" This is not a system call on Linux
+.\"
+.\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.TH statvfs 3 2023-07-20 "Linux man-pages 6.05.01"
+.SH NAME
+statvfs, fstatvfs \- get filesystem statistics
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <sys/statvfs.h>
+.PP
+.BI "int statvfs(const char *restrict " path \
+", struct statvfs *restrict " buf );
+.BI "int fstatvfs(int " fd ", struct statvfs *" buf );
+.fi
+.SH DESCRIPTION
+The function
+.BR statvfs ()
+returns information about a mounted filesystem.
+.I path
+is the pathname of any file within the mounted filesystem.
+.I buf
+is a pointer to a
+.I statvfs
+structure defined approximately as follows:
+.PP
+.in +4n
+.EX
+struct statvfs {
+ unsigned long f_bsize; /* Filesystem block size */
+ unsigned long f_frsize; /* Fragment size */
+ fsblkcnt_t f_blocks; /* Size of fs in f_frsize units */
+ fsblkcnt_t f_bfree; /* Number of free blocks */
+ fsblkcnt_t f_bavail; /* Number of free blocks for
+ unprivileged users */
+ fsfilcnt_t f_files; /* Number of inodes */
+ fsfilcnt_t f_ffree; /* Number of free inodes */
+ fsfilcnt_t f_favail; /* Number of free inodes for
+ unprivileged users */
+ unsigned long f_fsid; /* Filesystem ID */
+ unsigned long f_flag; /* Mount flags */
+ unsigned long f_namemax; /* Maximum filename length */
+};
+.EE
+.in
+.PP
+Here the types
+.I fsblkcnt_t
+and
+.I fsfilcnt_t
+are defined in
+.IR <sys/types.h> .
+Both used to be
+.IR "unsigned long" .
+.PP
+The field
+.I f_flag
+is a bit mask indicating various options that were employed
+when mounting this filesystem.
+It contains zero or more of the following flags:
+.\" XXX Keep this list in sync with statfs(2)
+.TP
+.B ST_MANDLOCK
+Mandatory locking is permitted on the filesystem (see
+.BR fcntl (2)).
+.TP
+.B ST_NOATIME
+Do not update access times; see
+.BR mount (2).
+.TP
+.B ST_NODEV
+Disallow access to device special files on this filesystem.
+.TP
+.B ST_NODIRATIME
+Do not update directory access times; see
+.BR mount (2).
+.TP
+.B ST_NOEXEC
+Execution of programs is disallowed on this filesystem.
+.TP
+.B ST_NOSUID
+The set-user-ID and set-group-ID bits are ignored by
+.BR exec (3)
+for executable files on this filesystem
+.TP
+.B ST_RDONLY
+This filesystem is mounted read-only.
+.TP
+.B ST_RELATIME
+Update atime relative to mtime/ctime; see
+.BR mount (2).
+.TP
+.B ST_SYNCHRONOUS
+Writes are synched to the filesystem immediately (see the description of
+.B O_SYNC
+in
+.BR open (2)).
+.PP
+It is unspecified whether all members of the returned struct
+have meaningful values on all filesystems.
+.PP
+.BR fstatvfs ()
+returns the same information about an open file referenced by descriptor
+.IR fd .
+.SH RETURN VALUE
+On success, zero is returned.
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B EACCES
+.RB ( statvfs ())
+Search permission is denied for a component of the path prefix of
+.IR path .
+(See also
+.BR path_resolution (7).)
+.TP
+.B EBADF
+.RB ( fstatvfs ())
+.I fd
+is not a valid open file descriptor.
+.TP
+.B EFAULT
+.I Buf
+or
+.I path
+points to an invalid address.
+.TP
+.B EINTR
+This call was interrupted by a signal; see
+.BR signal (7).
+.TP
+.B EIO
+An I/O error occurred while reading from the filesystem.
+.TP
+.B ELOOP
+.RB ( statvfs ())
+Too many symbolic links were encountered in translating
+.IR path .
+.TP
+.B ENAMETOOLONG
+.RB ( statvfs ())
+.I path
+is too long.
+.TP
+.B ENOENT
+.RB ( statvfs ())
+The file referred to by
+.I path
+does not exist.
+.TP
+.B ENOMEM
+Insufficient kernel memory was available.
+.TP
+.B ENOSYS
+The filesystem does not support this call.
+.TP
+.B ENOTDIR
+.RB ( statvfs ())
+A component of the path prefix of
+.I path
+is not a directory.
+.TP
+.B EOVERFLOW
+Some values were too large to be represented in the returned struct.
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface Attribute Value
+T{
+.na
+.nh
+.BR statvfs (),
+.BR fstatvfs ()
+T} Thread safety MT-Safe
+.TE
+.sp 1
+.SH VERSIONS
+Only the
+.B ST_NOSUID
+and
+.B ST_RDONLY
+flags of the
+.I f_flag
+field are specified in POSIX.1.
+To obtain definitions of the remaining flags, one must define
+.BR _GNU_SOURCE .
+.SH NOTES
+The Linux kernel has system calls
+.BR statfs (2)
+and
+.BR fstatfs (2)
+to support this library call.
+.PP
+The glibc implementations of
+.PP
+.in +4n
+.EX
+pathconf(path, _PC_REC_XFER_ALIGN);
+pathconf(path, _PC_ALLOC_SIZE_MIN);
+pathconf(path, _PC_REC_MIN_XFER_SIZE);
+.EE
+.in
+.PP
+respectively use the
+.IR f_frsize ,
+.IR f_frsize ,
+and
+.I f_bsize
+fields returned by a call to
+.BR statvfs ()
+with the argument
+.IR path .
+.PP
+Under Linux,
+.I f_favail
+is always the same as
+.IR f_ffree ,
+and there's no way for a filesystem to report otherwise.
+This is not an issue,
+since no filesystems with an inode root reservation exist.
+.SH STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001.
+.PP
+Before glibc 2.13,
+.\" glibc commit 3cdaa6adb113a088fdfb87aa6d7747557eccc58d
+.BR statvfs ()
+populated the bits of the
+.I f_flag
+field by scanning the mount options shown in
+.IR /proc/mounts .
+However, starting with Linux 2.6.36, the underlying
+.BR statfs (2)
+system call provides the necessary information via the
+.I f_flags
+field, and since glibc 2.13, the
+.BR statvfs ()
+function will use information from that field rather than scanning
+.IR /proc/mounts .
+.SH SEE ALSO
+.BR statfs (2)