manual/LDP_man-pages/original/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@gmail.com>
  25 .\"
  26 .TH STATFS 2 2004-06-23 "Linux" "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 pathname of any file within the mounted file system.
  41 .I buf
  42 is a pointer to a
  43 .I statfs
  44 structure defined approximately as follows:
  45
  46 .in +4n
  47 .nf
  48 struct statfs {
  49    long    f_type;     /* type of file system (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 unprivileged user */
  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 .in
 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.
 119 On error, \-1 is returned, and
 120 .I errno
 121 is set appropriately.
 122 .SH ERRORS
 123 .TP
 124 .B EACCES
 125 .RB ( statfs ())
 126 Search permission is denied for a component of the path prefix of
 127 .IR path .
 128 (See also
 129 .BR path_resolution (7).)
 130 .TP
 131 .B EBADF
 132 .RB ( fstatfs ())
 133 .I fd
 134 is not a valid open file descriptor.
 135 .TP
 136 .B EFAULT
 137 .I buf
 138 or
 139 .I path
 140 points to an invalid address.
 141 .TP
 142 .B EINTR
 143 This call was interrupted by a signal.
 144 .TP
 145 .B EIO
 146 An I/O error occurred while reading from the file system.
 147 .TP
 148 .B ELOOP
 149 .RB ( statfs ())
 150 Too many symbolic links were encountered in translating
 151 .IR path .
 152 .TP
 153 .B ENAMETOOLONG
 154 .RB ( statfs ())
 155 .I path
 156 is too long.
 157 .TP
 158 .B ENOENT
 159 .RB ( statfs ())
 160 The file referred to by
 161 .I path
 162 does not exist.
 163 .TP
 164 .B ENOMEM
 165 Insufficient kernel memory was available.
 166 .TP
 167 .B ENOSYS
 168 The file system does not support this call.
 169 .TP
 170 .B ENOTDIR
 171 .RB ( statfs ())
 172 A component of the path prefix of
 173 .I path
 174 is not a directory.
 175 .TP
 176 .B EOVERFLOW
 177 Some values were too large to be represented in the returned struct.
 178 .SH "CONFORMING TO"
 179 Linux-specific.
 180 The Linux
 181 .BR statfs ()
 182 was inspired by the 4.4BSD one
 183 (but they do not use the same structure).
 184 .SH NOTES
 185 The kernel has system calls
 186 .BR statfs (),
 187 .BR fstatfs (),
 188 .BR statfs64 (),
 189 and
 190 .BR fstatfs64 ()
 191 to support this library call.
 192
 193 Some systems only have \fI<sys/vfs.h>\fP, other systems also have
 194 \fI<sys/statfs.h>\fP, where the former includes the latter.
 195 So it seems
 196 including the former is the best choice.
 197
 198 LSB has deprecated the library calls
 199 .BR statfs ()
 200 and
 201 .BR fstatfs ()
 202 and tells us to use
 203 .BR statvfs (2)
 204 and
 205 .BR fstatvfs (2)
 206 instead.
 207 .SS The f_fsid field
 208 Solaris, Irix and POSIX have a system call
 209 .BR statvfs (2)
 210 that returns a
 211 .I "struct statvfs"
 212 (defined in
 213 .IR <sys/statvfs.h> )
 214 containing an
 215 .I "unsigned long"
 216 .IR f_fsid .
 217 Linux, SunOS, HP-UX, 4.4BSD have a system call
 218 .BR statfs ()
 219 that returns a
 220 .I "struct statfs"
 221 (defined in
 222 .IR <sys/vfs.h> )
 223 containing a
 224 .I fsid_t
 225 .IR f_fsid ,
 226 where
 227 .I fsid_t
 228 is defined as
 229 .IR "struct { int val[2]; }" .
 230 The same holds for FreeBSD, except that it uses the include file
 231 .IR <sys/mount.h> .
 232
 233 The general idea is that
 234 .I f_fsid
 235 contains some random stuff such that the pair
 236 .RI ( f_fsid , ino )
 237 uniquely determines a file.
 238 Some OSes use (a variation on) the device number, or the device number
 239 combined with the file-system type.
 240 Several OSes restrict giving out the
 241 .I f_fsid
 242 field to the superuser only (and zero it for unprivileged users),
 243 because this field is used in the filehandle of the file system
 244 when NFS-exported, and giving it out is a security concern.
 245 .LP
 246 Under some OSes the
 247 .I fsid
 248 can be used as second argument to the
 249 .BR sysfs ()
 250 system call.
 251 .SH "SEE ALSO"
 252 .BR stat (2),
 253 .BR statvfs (2),
 254 .BR path_resolution (7)