man2/statfs.2

   1 .\" Copyright (C) 2003 Andries Brouwer (aeb@cwi.nl)
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .\" Modified 2003-08-17 by Walter Harms
   6 .\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com>
   7 .\"
   8 .TH statfs 2 (date) "Linux man-pages (unreleased)"
   9 .SH NAME
  10 statfs, fstatfs \- get filesystem statistics
  11 .SH LIBRARY
  12 Standard C library
  13 .RI ( libc ", " \-lc )
  14 .SH SYNOPSIS
  15 .nf
  16 .BR "#include <sys/vfs.h>    " "/* or <sys/statfs.h> */"
  17 .P
  18 .BI "int statfs(const char *" path ", struct statfs *" buf );
  19 .BI "int fstatfs(int " fd ", struct statfs *" buf );
  20 .fi
  21 .P
  22 Unless you need the
  23 .I f_type
  24 field, you should use the standard
  25 .BR statvfs (3)
  26 interface instead.
  27 .SH DESCRIPTION
  28 The
  29 .BR statfs ()
  30 system call returns information about a mounted filesystem.
  31 .I path
  32 is the pathname of any file within the mounted filesystem.
  33 .I buf
  34 is a pointer to a
  35 .I statfs
  36 structure defined approximately as follows:
  37 .P
  38 .in +4n
  39 .EX
  40 struct statfs {
  41     __fsword_t f_type;    /* Type of filesystem (see below) */
  42     __fsword_t f_bsize;   /* Optimal transfer block size */
  43     fsblkcnt_t f_blocks;  /* Total data blocks in filesystem */
  44     fsblkcnt_t f_bfree;   /* Free blocks in filesystem */
  45     fsblkcnt_t f_bavail;  /* Free blocks available to
  46                              unprivileged user */
  47     fsfilcnt_t f_files;   /* Total inodes in filesystem */
  48     fsfilcnt_t f_ffree;   /* Free inodes in filesystem */
  49     fsid_t     f_fsid;    /* Filesystem ID */
  50     __fsword_t f_namelen; /* Maximum length of filenames */
  51     __fsword_t f_frsize;  /* Fragment size (since Linux 2.6) */
  52     __fsword_t f_flags;   /* Mount flags of filesystem
  53                              (since Linux 2.6.36) */
  54     __fsword_t f_spare[xxx];
  55                     /* Padding bytes reserved for future use */
  56 };
  57 .EE
  58 .in
  59 .P
  60 The following filesystem types may appear in
  61 .IR f_type :
  62 .P
  63 .in +4n
  64 .EX
  65 ADFS_SUPER_MAGIC      0xadf5
  66 AFFS_SUPER_MAGIC      0xadff
  67 AFS_SUPER_MAGIC       0x5346414f
  68 ANON_INODE_FS_MAGIC   0x09041934 /* Anonymous inode FS (for
  69                                     pseudofiles that have no name;
  70                                     e.g., epoll, signalfd, bpf) */
  71 AUTOFS_SUPER_MAGIC    0x0187
  72 BDEVFS_MAGIC          0x62646576
  73 BEFS_SUPER_MAGIC      0x42465331
  74 BFS_MAGIC             0x1badface
  75 BINFMTFS_MAGIC        0x42494e4d
  76 BPF_FS_MAGIC          0xcafe4a11
  77 BTRFS_SUPER_MAGIC     0x9123683e
  78 BTRFS_TEST_MAGIC      0x73727279
  79 CGROUP_SUPER_MAGIC    0x27e0eb   /* Cgroup pseudo FS */
  80 CGROUP2_SUPER_MAGIC   0x63677270 /* Cgroup v2 pseudo FS */
  81 CIFS_MAGIC_NUMBER     0xff534d42
  82 CODA_SUPER_MAGIC      0x73757245
  83 COH_SUPER_MAGIC       0x012ff7b7
  84 CRAMFS_MAGIC          0x28cd3d45
  85 DEBUGFS_MAGIC         0x64626720
  86 DEVFS_SUPER_MAGIC     0x1373     /* Linux 2.6.17 and earlier */
  87 DEVPTS_SUPER_MAGIC    0x1cd1
  88 ECRYPTFS_SUPER_MAGIC  0xf15f
  89 EFIVARFS_MAGIC        0xde5e81e4
  90 EFS_SUPER_MAGIC       0x00414a53
  91 EXT_SUPER_MAGIC       0x137d     /* Linux 2.0 and earlier */
  92 EXT2_OLD_SUPER_MAGIC  0xef51
  93 EXT2_SUPER_MAGIC      0xef53
  94 EXT3_SUPER_MAGIC      0xef53
  95 EXT4_SUPER_MAGIC      0xef53
  96 F2FS_SUPER_MAGIC      0xf2f52010
  97 FUSE_SUPER_MAGIC      0x65735546
  98 FUTEXFS_SUPER_MAGIC   0xbad1dea  /* Unused */
  99 HFS_SUPER_MAGIC       0x4244
 100 HOSTFS_SUPER_MAGIC    0x00c0ffee
 101 HPFS_SUPER_MAGIC      0xf995e849
 102 HUGETLBFS_MAGIC       0x958458f6
 103 ISOFS_SUPER_MAGIC     0x9660
 104 JFFS2_SUPER_MAGIC     0x72b6
 105 JFS_SUPER_MAGIC       0x3153464a
 106 MINIX_SUPER_MAGIC     0x137f     /* original minix FS */
 107 MINIX_SUPER_MAGIC2    0x138f     /* 30 char minix FS */
 108 MINIX2_SUPER_MAGIC    0x2468     /* minix V2 FS */
 109 MINIX2_SUPER_MAGIC2   0x2478     /* minix V2 FS, 30 char names */
 110 MINIX3_SUPER_MAGIC    0x4d5a     /* minix V3 FS, 60 char names */
 111 MQUEUE_MAGIC          0x19800202 /* POSIX message queue FS */
 112 MSDOS_SUPER_MAGIC     0x4d44
 113 MTD_INODE_FS_MAGIC    0x11307854
 114 NCP_SUPER_MAGIC       0x564c
 115 NFS_SUPER_MAGIC       0x6969
 116 NILFS_SUPER_MAGIC     0x3434
 117 NSFS_MAGIC            0x6e736673
 118 NTFS_SB_MAGIC         0x5346544e
 119 OCFS2_SUPER_MAGIC     0x7461636f
 120 OPENPROM_SUPER_MAGIC  0x9fa1
 121 OVERLAYFS_SUPER_MAGIC 0x794c7630
 122 PIPEFS_MAGIC          0x50495045
 123 PROC_SUPER_MAGIC      0x9fa0     /* /proc FS */
 124 PSTOREFS_MAGIC        0x6165676c
 125 QNX4_SUPER_MAGIC      0x002f
 126 QNX6_SUPER_MAGIC      0x68191122
 127 RAMFS_MAGIC           0x858458f6
 128 REISERFS_SUPER_MAGIC  0x52654973
 129 ROMFS_MAGIC           0x7275
 130 SECURITYFS_MAGIC      0x73636673
 131 SELINUX_MAGIC         0xf97cff8c
 132 SMACK_MAGIC           0x43415d53
 133 SMB_SUPER_MAGIC       0x517b
 134 SMB2_MAGIC_NUMBER     0xfe534d42
 135 SOCKFS_MAGIC          0x534f434b
 136 SQUASHFS_MAGIC        0x73717368
 137 SYSFS_MAGIC           0x62656572
 138 SYSV2_SUPER_MAGIC     0x012ff7b6
 139 SYSV4_SUPER_MAGIC     0x012ff7b5
 140 TMPFS_MAGIC           0x01021994
 141 TRACEFS_MAGIC         0x74726163
 142 UDF_SUPER_MAGIC       0x15013346
 143 UFS_MAGIC             0x00011954
 144 USBDEVICE_SUPER_MAGIC 0x9fa2
 145 V9FS_MAGIC            0x01021997
 146 VXFS_SUPER_MAGIC      0xa501fcf5
 147 XENFS_SUPER_MAGIC     0xabba1974
 148 XENIX_SUPER_MAGIC     0x012ff7b4
 149 XFS_SUPER_MAGIC       0x58465342
 150 _XIAFS_SUPER_MAGIC    0x012fd16d /* Linux 2.0 and earlier */
 151 .EE
 152 .in
 153 .P
 154 Most of these MAGIC constants are defined in
 155 .IR /usr/include/linux/magic.h ,
 156 and some are hardcoded in kernel sources.
 157 .P
 158 The
 159 .I f_flags
 160 field is a bit mask indicating mount options for the filesystem.
 161 It contains zero or more of the following bits:
 162 .\" XXX Keep this list in sync with statvfs(3)
 163 .TP
 164 .B ST_MANDLOCK
 165 Mandatory locking is permitted on the filesystem (see
 166 .BR fcntl (2)).
 167 .TP
 168 .B ST_NOATIME
 169 Do not update access times; see
 170 .BR mount (2).
 171 .TP
 172 .B ST_NODEV
 173 Disallow access to device special files on this filesystem.
 174 .TP
 175 .B ST_NODIRATIME
 176 Do not update directory access times; see
 177 .BR mount (2).
 178 .TP
 179 .B ST_NOEXEC
 180 Execution of programs is disallowed on this filesystem.
 181 .TP
 182 .B ST_NOSUID
 183 The set-user-ID and set-group-ID bits are ignored by
 184 .BR exec (3)
 185 for executable files on this filesystem
 186 .TP
 187 .B ST_RDONLY
 188 This filesystem is mounted read-only.
 189 .TP
 190 .B ST_RELATIME
 191 Update atime relative to mtime/ctime; see
 192 .BR mount (2).
 193 .TP
 194 .B ST_SYNCHRONOUS
 195 Writes are synched to the filesystem immediately (see the description of
 196 .B O_SYNC
 197 in
 198 .BR open (2)).
 199 .TP
 200 .BR ST_NOSYMFOLLOW " (since Linux 5.10)"
 201 .\" dab741e0e02bd3c4f5e2e97be74b39df2523fc6e
 202 Symbolic links are not followed when resolving paths; see
 203 .BR mount (2).
 204 .P
 205 Nobody knows what
 206 .I f_fsid
 207 is supposed to contain (but see below).
 208 .P
 209 Fields that are undefined for a particular filesystem are set to 0.
 210 .P
 211 .BR fstatfs ()
 212 returns the same information about an open file referenced by descriptor
 213 .IR fd .
 214 .SH RETURN VALUE
 215 On success, zero is returned.
 216 On error, \-1 is returned, and
 217 .I errno
 218 is set to indicate the error.
 219 .SH ERRORS
 220 .TP
 221 .B EACCES
 222 .RB ( statfs ())
 223 Search permission is denied for a component of the path prefix of
 224 .IR path .
 225 (See also
 226 .BR path_resolution (7).)
 227 .TP
 228 .B EBADF
 229 .RB ( fstatfs ())
 230 .I fd
 231 is not a valid open file descriptor.
 232 .TP
 233 .B EFAULT
 234 .I buf
 235 or
 236 .I path
 237 points to an invalid address.
 238 .TP
 239 .B EINTR
 240 The call was interrupted by a signal; see
 241 .BR signal (7).
 242 .TP
 243 .B EIO
 244 An I/O error occurred while reading from the filesystem.
 245 .TP
 246 .B ELOOP
 247 .RB ( statfs ())
 248 Too many symbolic links were encountered in translating
 249 .IR path .
 250 .TP
 251 .B ENAMETOOLONG
 252 .RB ( statfs ())
 253 .I path
 254 is too long.
 255 .TP
 256 .B ENOENT
 257 .RB ( statfs ())
 258 The file referred to by
 259 .I path
 260 does not exist.
 261 .TP
 262 .B ENOMEM
 263 Insufficient kernel memory was available.
 264 .TP
 265 .B ENOSYS
 266 The filesystem does not support this call.
 267 .TP
 268 .B ENOTDIR
 269 .RB ( statfs ())
 270 A component of the path prefix of
 271 .I path
 272 is not a directory.
 273 .TP
 274 .B EOVERFLOW
 275 Some values were too large to be represented in the returned struct.
 276 .SH VERSIONS
 277 .SS The f_fsid field
 278 Solaris, Irix, and POSIX have a system call
 279 .BR statvfs (2)
 280 that returns a
 281 .I "struct statvfs"
 282 (defined in
 283 .IR <sys/statvfs.h> )
 284 containing an
 285 .I "unsigned long"
 286 .IR f_fsid .
 287 Linux, SunOS, HP-UX, 4.4BSD have a system call
 288 .BR statfs ()
 289 that returns a
 290 .I "struct statfs"
 291 (defined in
 292 .IR <sys/vfs.h> )
 293 containing a
 294 .I fsid_t
 295 .IR f_fsid ,
 296 where
 297 .I fsid_t
 298 is defined as
 299 .IR "struct { int val[2]; }" .
 300 The same holds for FreeBSD, except that it uses the include file
 301 .IR <sys/mount.h> .
 302 .P
 303 The general idea is that
 304 .I f_fsid
 305 contains some random stuff such that the pair
 306 .RI ( f_fsid , ino )
 307 uniquely determines a file.
 308 Some operating systems use (a variation on) the device number,
 309 or the device number combined with the filesystem type.
 310 Several operating systems restrict giving out the
 311 .I f_fsid
 312 field to the superuser only (and zero it for unprivileged users),
 313 because this field is used in the filehandle of the filesystem
 314 when NFS-exported, and giving it out is a security concern.
 315 .P
 316 Under some operating systems, the
 317 .I fsid
 318 can be used as the second argument to the
 319 .BR sysfs (2)
 320 system call.
 321 .SH STANDARDS
 322 Linux.
 323 .SH HISTORY
 324 The Linux
 325 .BR statfs ()
 326 was inspired by the 4.4BSD one
 327 (but they do not use the same structure).
 328 .P
 329 The original Linux
 330 .BR statfs ()
 331 and
 332 .BR fstatfs ()
 333 system calls were not designed with extremely large file sizes in mind.
 334 Subsequently, Linux 2.6
 335 added new
 336 .BR statfs64 ()
 337 and
 338 .BR fstatfs64 ()
 339 system calls that employ a new structure,
 340 .IR statfs64 .
 341 The new structure contains the same fields as the original
 342 .I statfs
 343 structure, but the sizes of various fields are increased,
 344 to accommodate large file sizes.
 345 The glibc
 346 .BR statfs ()
 347 and
 348 .BR fstatfs ()
 349 wrapper functions transparently deal with the kernel differences.
 350 .P
 351 LSB has deprecated the library calls
 352 .BR statfs ()
 353 and
 354 .BR fstatfs ()
 355 and tells us to use
 356 .BR statvfs (3)
 357 and
 358 .BR fstatvfs (3)
 359 instead.
 360 .SH NOTES
 361 The
 362 .I __fsword_t
 363 type used for various fields in the
 364 .I statfs
 365 structure definition is a glibc internal type,
 366 not intended for public use.
 367 This leaves the programmer in a bit of a conundrum when trying to copy
 368 or compare these fields to local variables in a program.
 369 Using
 370 .I "unsigned\ int"
 371 for such variables suffices on most systems.
 372 .P
 373 Some systems have only \fI<sys/vfs.h>\fP, other systems also have
 374 \fI<sys/statfs.h>\fP, where the former includes the latter.
 375 So it seems
 376 including the former is the best choice.
 377 .SH BUGS
 378 From Linux 2.6.38 up to and including Linux 3.1,
 379 .\" broken in commit ff0c7d15f9787b7e8c601533c015295cc68329f8
 380 .\" fixed in commit d70ef97baf048412c395bb5d65791d8fe133a52b
 381 .BR fstatfs ()
 382 failed with the error
 383 .B ENOSYS
 384 for file descriptors created by
 385 .BR pipe (2).
 386 .SH SEE ALSO
 387 .BR stat (2),
 388 .BR statvfs (3),
 389 .BR path_resolution (7)