original/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 2014-06-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 function
  39 .BR statfs ()
  40 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 #if __WORDSIZE == 32            /* System word size */
  51 # define __SWORD_TYPE           int
  52 #else /* __WORDSIZE == 64 */
  53 # define __SWORD_TYPE           long int
  54 #endif
  55
  56 struct statfs {
  57     __SWORD_TYPE f_type;    /* type of filesystem (see below) */
  58     __SWORD_TYPE f_bsize;   /* optimal transfer block size */
  59     fsblkcnt_t   f_blocks;  /* total data blocks in filesystem */
  60     fsblkcnt_t   f_bfree;   /* free blocks in fs */
  61     fsblkcnt_t   f_bavail;  /* free blocks available to
  62                                unprivileged user */
  63     fsfilcnt_t   f_files;   /* total file nodes in filesystem */
  64     fsfilcnt_t   f_ffree;   /* free file nodes in fs */
  65     fsid_t       f_fsid;    /* filesystem id */
  66     __SWORD_TYPE f_namelen; /* maximum length of filenames */
  67     __SWORD_TYPE f_frsize;  /* fragment size (since Linux 2.6) */
  68     __SWORD_TYPE f_spare[5];
  69 };
  70
  71 Filesystem types:
  72
  73    ADFS_SUPER_MAGIC      0xadf5
  74    AFFS_SUPER_MAGIC      0xADFF
  75    BDEVFS_MAGIC          0x62646576
  76    BEFS_SUPER_MAGIC      0x42465331
  77    BFS_MAGIC             0x1BADFACE
  78    BINFMTFS_MAGIC        0x42494e4d
  79    BTRFS_SUPER_MAGIC     0x9123683E
  80    CGROUP_SUPER_MAGIC    0x27e0eb
  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
  87    DEVPTS_SUPER_MAGIC    0x1cd1
  88    EFIVARFS_MAGIC        0xde5e81e4
  89    EFS_SUPER_MAGIC       0x00414A53
  90    EXT_SUPER_MAGIC       0x137D
  91    EXT2_OLD_SUPER_MAGIC  0xEF51
  92    EXT2_SUPER_MAGIC      0xEF53
  93    EXT3_SUPER_MAGIC      0xEF53
  94    EXT4_SUPER_MAGIC      0xEF53
  95    FUSE_SUPER_MAGIC      0x65735546
  96    FUTEXFS_SUPER_MAGIC   0xBAD1DEA
  97    HFS_SUPER_MAGIC       0x4244
  98    HOSTFS_SUPER_MAGIC    0x00c0ffee
  99    HPFS_SUPER_MAGIC      0xF995E849
 100    HUGETLBFS_MAGIC       0x958458f6
 101    ISOFS_SUPER_MAGIC     0x9660
 102    JFFS2_SUPER_MAGIC     0x72b6
 103    JFS_SUPER_MAGIC       0x3153464a
 104    MINIX_SUPER_MAGIC     0x137F /* orig. minix */
 105    MINIX_SUPER_MAGIC2    0x138F /* 30 char minix */
 106    MINIX2_SUPER_MAGIC    0x2468 /* minix V2 */
 107    MINIX2_SUPER_MAGIC2   0x2478 /* minix V2, 30 char names */
 108    MINIX3_SUPER_MAGIC    0x4d5a /* minix V3 fs, 60 char names */
 109    MQUEUE_MAGIC          0x19800202
 110    MSDOS_SUPER_MAGIC     0x4d44
 111    NCP_SUPER_MAGIC       0x564c
 112    NFS_SUPER_MAGIC       0x6969
 113    NILFS_SUPER_MAGIC     0x3434
 114    NTFS_SB_MAGIC         0x5346544e
 115    OPENPROM_SUPER_MAGIC  0x9fa1
 116    PIPEFS_MAGIC          0x50495045
 117    PROC_SUPER_MAGIC      0x9fa0
 118    PSTOREFS_MAGIC        0x6165676C
 119    QNX4_SUPER_MAGIC      0x002f
 120    QNX6_SUPER_MAGIC      0x68191122
 121    RAMFS_MAGIC           0x858458f6
 122    REISERFS_SUPER_MAGIC  0x52654973
 123    ROMFS_MAGIC           0x7275
 124    SELINUX_MAGIC         0xf97cff8c
 125    SMACK_MAGIC           0x43415d53
 126    SMB_SUPER_MAGIC       0x517B
 127    SOCKFS_MAGIC          0x534F434B
 128    SQUASHFS_MAGIC        0x73717368
 129    SYSFS_MAGIC           0x62656572
 130    SYSV2_SUPER_MAGIC     0x012FF7B6
 131    SYSV4_SUPER_MAGIC     0x012FF7B5
 132    TMPFS_MAGIC           0x01021994
 133    UDF_SUPER_MAGIC       0x15013346
 134    UFS_MAGIC             0x00011954
 135    USBDEVICE_SUPER_MAGIC 0x9fa2
 136    V9FS_MAGIC            0x01021997
 137    VXFS_SUPER_MAGIC      0xa501FCF5
 138    XENFS_SUPER_MAGIC     0xabba1974
 139    XENIX_SUPER_MAGIC     0x012FF7B4
 140    XFS_SUPER_MAGIC       0x58465342
 141    _XIAFS_SUPER_MAGIC    0x012FD16D
 142 .fi
 143 .in
 144 .PP
 145 Most of these MAGIC constants are defined in
 146 .IR /usr/include/linux/magic.h ,
 147 and some are hardcoded in kernel sources.
 148 .PP
 149 Nobody knows what
 150 .I f_fsid
 151 is supposed to contain (but see below).
 152 .PP
 153 Fields that are undefined for a particular filesystem are set to 0.
 154 .BR fstatfs ()
 155 returns the same information about an open file referenced by descriptor
 156 .IR fd .
 157 .SH RETURN VALUE
 158 On success, zero is returned.
 159 On error, \-1 is returned, and
 160 .I errno
 161 is set appropriately.
 162 .SH ERRORS
 163 .TP
 164 .B EACCES
 165 .RB ( statfs ())
 166 Search permission is denied for a component of the path prefix of
 167 .IR path .
 168 (See also
 169 .BR path_resolution (7).)
 170 .TP
 171 .B EBADF
 172 .RB ( fstatfs ())
 173 .I fd
 174 is not a valid open file descriptor.
 175 .TP
 176 .B EFAULT
 177 .I buf
 178 or
 179 .I path
 180 points to an invalid address.
 181 .TP
 182 .B EINTR
 183 This call was interrupted by a signal.
 184 .TP
 185 .B EIO
 186 An I/O error occurred while reading from the filesystem.
 187 .TP
 188 .B ELOOP
 189 .RB ( statfs ())
 190 Too many symbolic links were encountered in translating
 191 .IR path .
 192 .TP
 193 .B ENAMETOOLONG
 194 .RB ( statfs ())
 195 .I path
 196 is too long.
 197 .TP
 198 .B ENOENT
 199 .RB ( statfs ())
 200 The file referred to by
 201 .I path
 202 does not exist.
 203 .TP
 204 .B ENOMEM
 205 Insufficient kernel memory was available.
 206 .TP
 207 .B ENOSYS
 208 The filesystem does not support this call.
 209 .TP
 210 .B ENOTDIR
 211 .RB ( statfs ())
 212 A component of the path prefix of
 213 .I path
 214 is not a directory.
 215 .TP
 216 .B EOVERFLOW
 217 Some values were too large to be represented in the returned struct.
 218 .SH CONFORMING TO
 219 Linux-specific.
 220 The Linux
 221 .BR statfs ()
 222 was inspired by the 4.4BSD one
 223 (but they do not use the same structure).
 224 .SH NOTES
 225 The original Linux
 226 .BR statfs ()
 227 and
 228 .BR fstatfs ()
 229 system calls were not designed with extremely large file sizes in mind.
 230 Subsequently, Linux 2.6
 231 added new
 232 .BR statfs64 ()
 233 and
 234 .BR fstatfs64 ()
 235 system calls that employ a new structure,
 236 .IR statfs64 .
 237 The new structure contains the same fields as the original
 238 .I statfs
 239 structure, but the sizes of various fields are increased,
 240 to accommodate large file sizes.
 241 The glibc
 242 .BR statfs ()
 243 and
 244 .BR fstatfs ()
 245 wrapper functions transparently deal with the kernel differences.
 246
 247 Some systems only have \fI<sys/vfs.h>\fP, other systems also have
 248 \fI<sys/statfs.h>\fP, where the former includes the latter.
 249 So it seems
 250 including the former is the best choice.
 251
 252 LSB has deprecated the library calls
 253 .BR statfs ()
 254 and
 255 .BR fstatfs ()
 256 and tells us to use
 257 .BR statvfs (2)
 258 and
 259 .BR fstatvfs (2)
 260 instead.
 261 .SS The f_fsid field
 262 Solaris, Irix and POSIX have a system call
 263 .BR statvfs (2)
 264 that returns a
 265 .I "struct statvfs"
 266 (defined in
 267 .IR <sys/statvfs.h> )
 268 containing an
 269 .I "unsigned long"
 270 .IR f_fsid .
 271 Linux, SunOS, HP-UX, 4.4BSD have a system call
 272 .BR statfs ()
 273 that returns a
 274 .I "struct statfs"
 275 (defined in
 276 .IR <sys/vfs.h> )
 277 containing a
 278 .I fsid_t
 279 .IR f_fsid ,
 280 where
 281 .I fsid_t
 282 is defined as
 283 .IR "struct { int val[2]; }" .
 284 The same holds for FreeBSD, except that it uses the include file
 285 .IR <sys/mount.h> .
 286
 287 The general idea is that
 288 .I f_fsid
 289 contains some random stuff such that the pair
 290 .RI ( f_fsid , ino )
 291 uniquely determines a file.
 292 Some operating systems use (a variation on) the device number,
 293 or the device number combined with the filesystem type.
 294 Several operating systems restrict giving out the
 295 .I f_fsid
 296 field to the superuser only (and zero it for unprivileged users),
 297 because this field is used in the filehandle of the filesystem
 298 when NFS-exported, and giving it out is a security concern.
 299 .LP
 300 Under some operating systems, the
 301 .I fsid
 302 can be used as the second argument to the
 303 .BR sysfs (2)
 304 system call.
 305 .SH BUGS
 306 From Linux 2.6.38 up to and including Linux 3.1,
 307 .\" broken in commit ff0c7d15f9787b7e8c601533c015295cc68329f8
 308 .\" fixed in commit d70ef97baf048412c395bb5d65791d8fe133a52b
 309 .BR fstatfs ()
 310 failed with the error
 311 .B ENOSYS
 312 for file descriptors created by
 313 .BR pipe (2).
 314 .SH SEE ALSO
 315 .BR stat (2),
 316 .BR statvfs (2),
 317 .BR path_resolution (7)
 318 .SH COLOPHON
 319 This page is part of release 3.78 of the Linux
 320 .I man-pages
 321 project.
 322 A description of the project,
 323 information about reporting bugs,
 324 and the latest version of this page,
 325 can be found at
 326 \%http://www.kernel.org/doc/man\-pages/.