man2/statfs.2

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