summaryrefslogtreecommitdiffstats
path: root/man2/statfs.2
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--man2/statfs.2389
1 files changed, 389 insertions, 0 deletions
diff --git a/man2/statfs.2 b/man2/statfs.2
new file mode 100644
index 0000000..26dad7c
--- /dev/null
+++ b/man2/statfs.2
@@ -0,0 +1,389 @@
+.\" Copyright (C) 2003 Andries Brouwer (aeb@cwi.nl)
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\" Modified 2003-08-17 by Walter Harms
+.\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.TH statfs 2 2023-07-18 "Linux man-pages 6.05.01"
+.SH NAME
+statfs, fstatfs \- get filesystem statistics
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.BR "#include <sys/vfs.h> " "/* or <sys/statfs.h> */"
+.PP
+.BI "int statfs(const char *" path ", struct statfs *" buf );
+.BI "int fstatfs(int " fd ", struct statfs *" buf );
+.fi
+.PP
+Unless you need the
+.I f_type
+field, you should use the standard
+.BR statvfs (3)
+interface instead.
+.SH DESCRIPTION
+The
+.BR statfs ()
+system call 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 statfs
+structure defined approximately as follows:
+.PP
+.in +4n
+.EX
+struct statfs {
+ __fsword_t f_type; /* Type of filesystem (see below) */
+ __fsword_t f_bsize; /* Optimal transfer block size */
+ fsblkcnt_t f_blocks; /* Total data blocks in filesystem */
+ fsblkcnt_t f_bfree; /* Free blocks in filesystem */
+ fsblkcnt_t f_bavail; /* Free blocks available to
+ unprivileged user */
+ fsfilcnt_t f_files; /* Total inodes in filesystem */
+ fsfilcnt_t f_ffree; /* Free inodes in filesystem */
+ fsid_t f_fsid; /* Filesystem ID */
+ __fsword_t f_namelen; /* Maximum length of filenames */
+ __fsword_t f_frsize; /* Fragment size (since Linux 2.6) */
+ __fsword_t f_flags; /* Mount flags of filesystem
+ (since Linux 2.6.36) */
+ __fsword_t f_spare[xxx];
+ /* Padding bytes reserved for future use */
+};
+.EE
+.in
+.PP
+The following filesystem types may appear in
+.IR f_type :
+.PP
+.in +4n
+.EX
+ADFS_SUPER_MAGIC 0xadf5
+AFFS_SUPER_MAGIC 0xadff
+AFS_SUPER_MAGIC 0x5346414f
+ANON_INODE_FS_MAGIC 0x09041934 /* Anonymous inode FS (for
+ pseudofiles that have no name;
+ e.g., epoll, signalfd, bpf) */
+AUTOFS_SUPER_MAGIC 0x0187
+BDEVFS_MAGIC 0x62646576
+BEFS_SUPER_MAGIC 0x42465331
+BFS_MAGIC 0x1badface
+BINFMTFS_MAGIC 0x42494e4d
+BPF_FS_MAGIC 0xcafe4a11
+BTRFS_SUPER_MAGIC 0x9123683e
+BTRFS_TEST_MAGIC 0x73727279
+CGROUP_SUPER_MAGIC 0x27e0eb /* Cgroup pseudo FS */
+CGROUP2_SUPER_MAGIC 0x63677270 /* Cgroup v2 pseudo FS */
+CIFS_MAGIC_NUMBER 0xff534d42
+CODA_SUPER_MAGIC 0x73757245
+COH_SUPER_MAGIC 0x012ff7b7
+CRAMFS_MAGIC 0x28cd3d45
+DEBUGFS_MAGIC 0x64626720
+DEVFS_SUPER_MAGIC 0x1373 /* Linux 2.6.17 and earlier */
+DEVPTS_SUPER_MAGIC 0x1cd1
+ECRYPTFS_SUPER_MAGIC 0xf15f
+EFIVARFS_MAGIC 0xde5e81e4
+EFS_SUPER_MAGIC 0x00414a53
+EXT_SUPER_MAGIC 0x137d /* Linux 2.0 and earlier */
+EXT2_OLD_SUPER_MAGIC 0xef51
+EXT2_SUPER_MAGIC 0xef53
+EXT3_SUPER_MAGIC 0xef53
+EXT4_SUPER_MAGIC 0xef53
+F2FS_SUPER_MAGIC 0xf2f52010
+FUSE_SUPER_MAGIC 0x65735546
+FUTEXFS_SUPER_MAGIC 0xbad1dea /* Unused */
+HFS_SUPER_MAGIC 0x4244
+HOSTFS_SUPER_MAGIC 0x00c0ffee
+HPFS_SUPER_MAGIC 0xf995e849
+HUGETLBFS_MAGIC 0x958458f6
+ISOFS_SUPER_MAGIC 0x9660
+JFFS2_SUPER_MAGIC 0x72b6
+JFS_SUPER_MAGIC 0x3153464a
+MINIX_SUPER_MAGIC 0x137f /* original minix FS */
+MINIX_SUPER_MAGIC2 0x138f /* 30 char minix FS */
+MINIX2_SUPER_MAGIC 0x2468 /* minix V2 FS */
+MINIX2_SUPER_MAGIC2 0x2478 /* minix V2 FS, 30 char names */
+MINIX3_SUPER_MAGIC 0x4d5a /* minix V3 FS, 60 char names */
+MQUEUE_MAGIC 0x19800202 /* POSIX message queue FS */
+MSDOS_SUPER_MAGIC 0x4d44
+MTD_INODE_FS_MAGIC 0x11307854
+NCP_SUPER_MAGIC 0x564c
+NFS_SUPER_MAGIC 0x6969
+NILFS_SUPER_MAGIC 0x3434
+NSFS_MAGIC 0x6e736673
+NTFS_SB_MAGIC 0x5346544e
+OCFS2_SUPER_MAGIC 0x7461636f
+OPENPROM_SUPER_MAGIC 0x9fa1
+OVERLAYFS_SUPER_MAGIC 0x794c7630
+PIPEFS_MAGIC 0x50495045
+PROC_SUPER_MAGIC 0x9fa0 /* /proc FS */
+PSTOREFS_MAGIC 0x6165676c
+QNX4_SUPER_MAGIC 0x002f
+QNX6_SUPER_MAGIC 0x68191122
+RAMFS_MAGIC 0x858458f6
+REISERFS_SUPER_MAGIC 0x52654973
+ROMFS_MAGIC 0x7275
+SECURITYFS_MAGIC 0x73636673
+SELINUX_MAGIC 0xf97cff8c
+SMACK_MAGIC 0x43415d53
+SMB_SUPER_MAGIC 0x517b
+SMB2_MAGIC_NUMBER 0xfe534d42
+SOCKFS_MAGIC 0x534f434b
+SQUASHFS_MAGIC 0x73717368
+SYSFS_MAGIC 0x62656572
+SYSV2_SUPER_MAGIC 0x012ff7b6
+SYSV4_SUPER_MAGIC 0x012ff7b5
+TMPFS_MAGIC 0x01021994
+TRACEFS_MAGIC 0x74726163
+UDF_SUPER_MAGIC 0x15013346
+UFS_MAGIC 0x00011954
+USBDEVICE_SUPER_MAGIC 0x9fa2
+V9FS_MAGIC 0x01021997
+VXFS_SUPER_MAGIC 0xa501fcf5
+XENFS_SUPER_MAGIC 0xabba1974
+XENIX_SUPER_MAGIC 0x012ff7b4
+XFS_SUPER_MAGIC 0x58465342
+_XIAFS_SUPER_MAGIC 0x012fd16d /* Linux 2.0 and earlier */
+.EE
+.in
+.PP
+Most of these MAGIC constants are defined in
+.IR /usr/include/linux/magic.h ,
+and some are hardcoded in kernel sources.
+.PP
+The
+.I f_flags
+field is a bit mask indicating mount options for the filesystem.
+It contains zero or more of the following bits:
+.\" XXX Keep this list in sync with statvfs(3)
+.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)).
+.TP
+.BR ST_NOSYMFOLLOW " (since Linux 5.10)"
+.\" dab741e0e02bd3c4f5e2e97be74b39df2523fc6e
+Symbolic links are not followed when resolving paths; see
+.BR mount (2).
+.PP
+Nobody knows what
+.I f_fsid
+is supposed to contain (but see below).
+.PP
+Fields that are undefined for a particular filesystem are set to 0.
+.PP
+.BR fstatfs ()
+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 ( statfs ())
+Search permission is denied for a component of the path prefix of
+.IR path .
+(See also
+.BR path_resolution (7).)
+.TP
+.B EBADF
+.RB ( fstatfs ())
+.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
+The 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 ( statfs ())
+Too many symbolic links were encountered in translating
+.IR path .
+.TP
+.B ENAMETOOLONG
+.RB ( statfs ())
+.I path
+is too long.
+.TP
+.B ENOENT
+.RB ( statfs ())
+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 ( statfs ())
+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 VERSIONS
+.SS The f_fsid field
+Solaris, Irix, and POSIX have a system call
+.BR statvfs (2)
+that returns a
+.I "struct statvfs"
+(defined in
+.IR <sys/statvfs.h> )
+containing an
+.I "unsigned long"
+.IR f_fsid .
+Linux, SunOS, HP-UX, 4.4BSD have a system call
+.BR statfs ()
+that returns a
+.I "struct statfs"
+(defined in
+.IR <sys/vfs.h> )
+containing a
+.I fsid_t
+.IR f_fsid ,
+where
+.I fsid_t
+is defined as
+.IR "struct { int val[2]; }" .
+The same holds for FreeBSD, except that it uses the include file
+.IR <sys/mount.h> .
+.PP
+The general idea is that
+.I f_fsid
+contains some random stuff such that the pair
+.RI ( f_fsid , ino )
+uniquely determines a file.
+Some operating systems use (a variation on) the device number,
+or the device number combined with the filesystem type.
+Several operating systems restrict giving out the
+.I f_fsid
+field to the superuser only (and zero it for unprivileged users),
+because this field is used in the filehandle of the filesystem
+when NFS-exported, and giving it out is a security concern.
+.PP
+Under some operating systems, the
+.I fsid
+can be used as the second argument to the
+.BR sysfs (2)
+system call.
+.SH STANDARDS
+Linux.
+.SH HISTORY
+The Linux
+.BR statfs ()
+was inspired by the 4.4BSD one
+(but they do not use the same structure).
+.PP
+The original Linux
+.BR statfs ()
+and
+.BR fstatfs ()
+system calls were not designed with extremely large file sizes in mind.
+Subsequently, Linux 2.6
+added new
+.BR statfs64 ()
+and
+.BR fstatfs64 ()
+system calls that employ a new structure,
+.IR statfs64 .
+The new structure contains the same fields as the original
+.I statfs
+structure, but the sizes of various fields are increased,
+to accommodate large file sizes.
+The glibc
+.BR statfs ()
+and
+.BR fstatfs ()
+wrapper functions transparently deal with the kernel differences.
+.PP
+LSB has deprecated the library calls
+.BR statfs ()
+and
+.BR fstatfs ()
+and tells us to use
+.BR statvfs (3)
+and
+.BR fstatvfs (3)
+instead.
+.SH NOTES
+The
+.I __fsword_t
+type used for various fields in the
+.I statfs
+structure definition is a glibc internal type,
+not intended for public use.
+This leaves the programmer in a bit of a conundrum when trying to copy
+or compare these fields to local variables in a program.
+Using
+.I "unsigned\ int"
+for such variables suffices on most systems.
+.PP
+Some systems have only \fI<sys/vfs.h>\fP, other systems also have
+\fI<sys/statfs.h>\fP, where the former includes the latter.
+So it seems
+including the former is the best choice.
+.SH BUGS
+From Linux 2.6.38 up to and including Linux 3.1,
+.\" broken in commit ff0c7d15f9787b7e8c601533c015295cc68329f8
+.\" fixed in commit d70ef97baf048412c395bb5d65791d8fe133a52b
+.BR fstatfs ()
+failed with the error
+.B ENOSYS
+for file descriptors created by
+.BR pipe (2).
+.SH SEE ALSO
+.BR stat (2),
+.BR statvfs (3),
+.BR path_resolution (7)