man2/statfs.2

   1 .\" Copyright (C) 2003 Andries Brouwer (aeb@cwi.nl)
   2 .\"
   3 .\" Permission is granted to make and distribute verbatim copies of this
   4 .\" manual provided the copyright notice and this permission notice are
   5 .\" preserved on all copies.
   6 .\"
   7 .\" Permission is granted to copy and distribute modified versions of this
   8 .\" manual under the conditions for verbatim copying, provided that the
   9 .\" entire resulting derived work is distributed under the terms of a
  10 .\" permission notice identical to this one.
  11 .\"
  12 .\" Since the Linux kernel and libraries are constantly changing, this
  13 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  14 .\" responsibility for errors or omissions, or for damages resulting from
  15 .\" the use of the information contained herein.  The author(s) may not
  16 .\" have taken the same level of care in the production of this manual,
  17 .\" which is licensed free of charge, as they might when working
  18 .\" professionally.
  19 .\"
  20 .\" Formatted or processed versions of this manual, if unaccompanied by
  21 .\" the source, must acknowledge the copyright and authors of this work.
  22 .\"
  23 .\" Modified 2003-08-17 by Walter Harms
  24 .\" Modified 2004-06-23 by Michael Kerrisk <mtk-manpages@gmx.net>
  25 .\"
  26 .TH STATFS 2 2004-06-23 "Linux 2.6.7" "Linux Programmer's Manual"
  27 .SH NAME
  28 statfs, fstatfs \- get file system statistics
  29 .SH SYNOPSIS
  30 .BR "#include <sys/vfs.h>    " "/* or <sys/statfs.h> */"
  31 .sp
  32 .BI "int statfs(const char *" path ", struct statfs *" buf );
  33 .br
  34 .BI "int fstatfs(int " fd ", struct statfs *" buf );
  35 .SH DESCRIPTION
  36 The function
  37 .BR statfs ()
  38 returns information about a mounted file system.
  39 .I path
  40 is the path name of any file within the mounted filesystem.
  41 .I buf
  42 is a pointer to a
  43 .I statfs
  44 structure defined approximately as follows:
  45
  46 .RS
  47 .nf
  48 struct statfs {
  49    long    f_type;     /* type of filesystem (see below) */
  50    long    f_bsize;    /* optimal transfer block size */
  51    long    f_blocks;   /* total data blocks in file system */
  52    long    f_bfree;    /* free blocks in fs */
  53    long    f_bavail;   /* free blocks avail to non-superuser */
  54    long    f_files;    /* total file nodes in file system */
  55    long    f_ffree;    /* free file nodes in fs */
  56    fsid_t  f_fsid;     /* file system id */
  57    long    f_namelen;  /* maximum length of filenames */
  58 };
  59
  60 File system types:
  61
  62    ADFS_SUPER_MAGIC      0xadf5
  63    AFFS_SUPER_MAGIC      0xADFF
  64    BEFS_SUPER_MAGIC      0x42465331
  65    BFS_MAGIC             0x1BADFACE
  66    CIFS_MAGIC_NUMBER     0xFF534D42
  67    CODA_SUPER_MAGIC      0x73757245
  68    COH_SUPER_MAGIC       0x012FF7B7
  69    CRAMFS_MAGIC          0x28cd3d45
  70    DEVFS_SUPER_MAGIC     0x1373
  71    EFS_SUPER_MAGIC       0x00414A53
  72    EXT_SUPER_MAGIC       0x137D
  73    EXT2_OLD_SUPER_MAGIC  0xEF51
  74    EXT2_SUPER_MAGIC      0xEF53
  75    EXT3_SUPER_MAGIC      0xEF53
  76    HFS_SUPER_MAGIC       0x4244
  77    HPFS_SUPER_MAGIC      0xF995E849
  78    HUGETLBFS_MAGIC       0x958458f6
  79    ISOFS_SUPER_MAGIC     0x9660
  80    JFFS2_SUPER_MAGIC     0x72b6
  81    JFS_SUPER_MAGIC       0x3153464a
  82    MINIX_SUPER_MAGIC     0x137F /* orig. minix */
  83    MINIX_SUPER_MAGIC2    0x138F /* 30 char minix */
  84    MINIX2_SUPER_MAGIC    0x2468 /* minix V2 */
  85    MINIX2_SUPER_MAGIC2   0x2478 /* minix V2, 30 char names */
  86    MSDOS_SUPER_MAGIC     0x4d44
  87    NCP_SUPER_MAGIC       0x564c
  88    NFS_SUPER_MAGIC       0x6969
  89    NTFS_SB_MAGIC         0x5346544e
  90    OPENPROM_SUPER_MAGIC  0x9fa1
  91    PROC_SUPER_MAGIC      0x9fa0
  92    QNX4_SUPER_MAGIC      0x002f
  93    REISERFS_SUPER_MAGIC  0x52654973
  94    ROMFS_MAGIC           0x7275
  95    SMB_SUPER_MAGIC       0x517B
  96    SYSV2_SUPER_MAGIC     0x012FF7B6
  97    SYSV4_SUPER_MAGIC     0x012FF7B5
  98    TMPFS_MAGIC           0x01021994
  99    UDF_SUPER_MAGIC       0x15013346
 100    UFS_MAGIC             0x00011954
 101    USBDEVICE_SUPER_MAGIC 0x9fa2
 102    VXFS_SUPER_MAGIC      0xa501FCF5
 103    XENIX_SUPER_MAGIC     0x012FF7B4
 104    XFS_SUPER_MAGIC       0x58465342
 105    _XIAFS_SUPER_MAGIC    0x012FD16D
 106 .fi
 107 .RE
 108 .PP
 109 Nobody knows what
 110 .I f_fsid
 111 is supposed to contain (but see below).
 112 .PP
 113 Fields that are undefined for a particular file system are set to 0.
 114 .BR fstatfs ()
 115 returns the same information about an open file referenced by descriptor
 116 .IR fd .
 117 .SH "RETURN VALUE"
 118 On success, zero is returned.  On error, \-1 is returned, and
 119 .I errno
 120 is set appropriately.
 121 .SH ERRORS
 122 .TP
 123 .B EACCES
 124 (statfs)
 125 Search permission is denied for a component of the path prefix of
 126 .IR path .
 127 (See also
 128 .BR path_resolution (2).)
 129 .TP
 130 .B EBADF
 131 (fstatfs)
 132 .I fd
 133 is not a valid open file descriptor.
 134 .TP
 135 .B EFAULT
 136 .I buf
 137 or
 138 .I path
 139 points to an invalid address.
 140 .TP
 141 .B EINTR
 142 This call was interrupted by a signal.
 143 .TP
 144 .B EIO
 145 An I/O error occurred while reading from the file system.
 146 .TP
 147 .B ELOOP
 148 (statfs)
 149 Too many symbolic links were encountered in translating
 150 .IR path .
 151 .TP
 152 .B ENAMETOOLONG
 153 (statfs)
 154 .I path
 155 is too long.
 156 .TP
 157 .B ENOENT
 158 (statfs)
 159 The file referred to by
 160 .I path
 161 does not exist.
 162 .TP
 163 .B ENOMEM
 164 Insufficient kernel memory was available.
 165 .TP
 166 .B ENOSYS
 167 The file system does not support this call.
 168 .TP
 169 .B ENOTDIR
 170 (statfs)
 171 A component of the path prefix of
 172 .I path
 173 is not a directory.
 174 .TP
 175 .B EOVERFLOW
 176 Some values were too large to be represented in the returned struct.
 177 .PP
 178 .SH "CONFORMING TO"
 179 The Linux
 180 .BR statfs ()
 181 was inspired by the 4.4BSD one
 182 (but they do not use the same structure).
 183 .SH "NOTES ON f_fsid"
 184 Solaris, Irix and POSIX have a system call
 185 .BR statvfs (2)
 186 that returns a
 187 .B "struct statvfs"
 188 (defined in
 189 .IR "<sys/statvfs.h>" )
 190 containing an
 191 .B "unsigned long"
 192 .IR f_fsid .
 193 Linux, SunOS, HPUX, 4.4BSD have a system call
 194 .I statfs
 195 that returns a
 196 .B "struct statfs"
 197 (defined in
 198 .IR "<sys/vfs.h>" )
 199 containing a
 200 .B fsid_t
 201 .IR f_fsid ,
 202 where
 203 .I fsid_t
 204 is defined as
 205 .BR "struct { int val[2]; }" .
 206 The same holds for FreeBSD, except that it uses the include file
 207 .IR "<sys/mount.h>" .
 208
 209 The general idea is that
 210 .I f_fsid
 211 contains some random stuff such that the pair
 212 .RI ( f_fsid , ino )
 213 uniquely determines a file.
 214 Some OSes use (a variation on) the device number, or the device number
 215 combined with the filesystem type.
 216 Several OSes restrict giving out the
 217 .I f_fsid
 218 field to the superuser only (and zero it for nonprivileged users),
 219 because this field is used in the filehandle of the filesystem
 220 when NFS-exported, and giving it out is a security concern.
 221 .LP
 222 Under some OSes the
 223 .I fsid
 224 can be used as second parameter to the
 225 .IR sysfs ()
 226 system call.
 227 .SH NOTES
 228 The kernel has system calls statfs, fstatfs, statfs64, fstatfs64
 229 to support this library call.
 230
 231 Some systems only have <sys/vfs.h>, other systems also have
 232 <sys/statfs.h>, where the former includes the latter. So it seems
 233 including the former is the best choice.
 234
 235 LSB has deprecated the library calls
 236 .I [f]statfs()
 237 and tells us to use
 238 .I [f]statvfs()
 239 instead.
 240 .SH "SEE ALSO"
 241 .BR path_resolution (2),
 242 .BR stat (2),
 243 .BR statvfs (2)