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 2010-11-21 "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 #if __WORDSIZE == 32            /* System word size */
  49 # define __SWORD_TYPE           int
  50 #else /* __WORDSIZE == 64 */
  51 # define __SWORD_TYPE           long int
  52 #endif
  53
  54 struct statfs {
  55     __SWORD_TYPE f_type;    /* type of file system (see below) */
  56     __SWORD_TYPE f_bsize;   /* optimal transfer block size */
  57     fsblkcnt_t   f_blocks;  /* total data blocks in file system */
  58     fsblkcnt_t   f_bfree;   /* free blocks in fs */
  59     fsblkcnt_t   f_bavail;  /* free blocks available to
  60                                unprivileged user */
  61     fsfilcnt_t   f_files;   /* total file nodes in file system */
  62     fsfilcnt_t   f_ffree;   /* free file nodes in fs */
  63     fsid_t       f_fsid;    /* file system id */
  64     __SWORD_TYPE f_namelen; /* maximum length of filenames */
  65     __SWORD_TYPE f_frsize;  /* fragment size (since Linux 2.6) */
  66     __SWORD_TYPE f_spare[5];
  67 };
  68
  69 File system types:
  70
  71    ADFS_SUPER_MAGIC      0xadf5
  72    AFFS_SUPER_MAGIC      0xADFF
  73    BEFS_SUPER_MAGIC      0x42465331
  74    BFS_MAGIC             0x1BADFACE
  75    CIFS_MAGIC_NUMBER     0xFF534D42
  76    CODA_SUPER_MAGIC      0x73757245
  77    COH_SUPER_MAGIC       0x012FF7B7
  78    CRAMFS_MAGIC          0x28cd3d45
  79    DEVFS_SUPER_MAGIC     0x1373
  80    EFS_SUPER_MAGIC       0x00414A53
  81    EXT_SUPER_MAGIC       0x137D
  82    EXT2_OLD_SUPER_MAGIC  0xEF51
  83    EXT2_SUPER_MAGIC      0xEF53
  84    EXT3_SUPER_MAGIC      0xEF53
  85    EXT4_SUPER_MAGIC      0xEF53
  86    HFS_SUPER_MAGIC       0x4244
  87    HPFS_SUPER_MAGIC      0xF995E849
  88    HUGETLBFS_MAGIC       0x958458f6
  89    ISOFS_SUPER_MAGIC     0x9660
  90    JFFS2_SUPER_MAGIC     0x72b6
  91    JFS_SUPER_MAGIC       0x3153464a
  92    MINIX_SUPER_MAGIC     0x137F /* orig. minix */
  93    MINIX_SUPER_MAGIC2    0x138F /* 30 char minix */
  94    MINIX2_SUPER_MAGIC    0x2468 /* minix V2 */
  95    MINIX2_SUPER_MAGIC2   0x2478 /* minix V2, 30 char names */
  96    MSDOS_SUPER_MAGIC     0x4d44
  97    NCP_SUPER_MAGIC       0x564c
  98    NFS_SUPER_MAGIC       0x6969
  99    NTFS_SB_MAGIC         0x5346544e
 100    OPENPROM_SUPER_MAGIC  0x9fa1
 101    PROC_SUPER_MAGIC      0x9fa0
 102    QNX4_SUPER_MAGIC      0x002f
 103    REISERFS_SUPER_MAGIC  0x52654973
 104    ROMFS_MAGIC           0x7275
 105    SMB_SUPER_MAGIC       0x517B
 106    SYSV2_SUPER_MAGIC     0x012FF7B6
 107    SYSV4_SUPER_MAGIC     0x012FF7B5
 108    TMPFS_MAGIC           0x01021994
 109    UDF_SUPER_MAGIC       0x15013346
 110    UFS_MAGIC             0x00011954
 111    USBDEVICE_SUPER_MAGIC 0x9fa2
 112    VXFS_SUPER_MAGIC      0xa501FCF5
 113    XENIX_SUPER_MAGIC     0x012FF7B4
 114    XFS_SUPER_MAGIC       0x58465342
 115    _XIAFS_SUPER_MAGIC    0x012FD16D
 116 .fi
 117 .in
 118 .PP
 119 Nobody knows what
 120 .I f_fsid
 121 is supposed to contain (but see below).
 122 .PP
 123 Fields that are undefined for a particular file system are set to 0.
 124 .BR fstatfs ()
 125 returns the same information about an open file referenced by descriptor
 126 .IR fd .
 127 .SH "RETURN VALUE"
 128 On success, zero is returned.
 129 On error, \-1 is returned, and
 130 .I errno
 131 is set appropriately.
 132 .SH ERRORS
 133 .TP
 134 .B EACCES
 135 .RB ( statfs ())
 136 Search permission is denied for a component of the path prefix of
 137 .IR path .
 138 (See also
 139 .BR path_resolution (7).)
 140 .TP
 141 .B EBADF
 142 .RB ( fstatfs ())
 143 .I fd
 144 is not a valid open file descriptor.
 145 .TP
 146 .B EFAULT
 147 .I buf
 148 or
 149 .I path
 150 points to an invalid address.
 151 .TP
 152 .B EINTR
 153 This call was interrupted by a signal.
 154 .TP
 155 .B EIO
 156 An I/O error occurred while reading from the file system.
 157 .TP
 158 .B ELOOP
 159 .RB ( statfs ())
 160 Too many symbolic links were encountered in translating
 161 .IR path .
 162 .TP
 163 .B ENAMETOOLONG
 164 .RB ( statfs ())
 165 .I path
 166 is too long.
 167 .TP
 168 .B ENOENT
 169 .RB ( statfs ())
 170 The file referred to by
 171 .I path
 172 does not exist.
 173 .TP
 174 .B ENOMEM
 175 Insufficient kernel memory was available.
 176 .TP
 177 .B ENOSYS
 178 The file system does not support this call.
 179 .TP
 180 .B ENOTDIR
 181 .RB ( statfs ())
 182 A component of the path prefix of
 183 .I path
 184 is not a directory.
 185 .TP
 186 .B EOVERFLOW
 187 Some values were too large to be represented in the returned struct.
 188 .SH "CONFORMING TO"
 189 Linux-specific.
 190 The Linux
 191 .BR statfs ()
 192 was inspired by the 4.4BSD one
 193 (but they do not use the same structure).
 194 .SH NOTES
 195 The original Linux
 196 .BR statfs ()
 197 and
 198 .BR fstatfs ()
 199 system calls were not designed with extremely large file sizes in mind.
 200 Subsequently, Linux 2.6
 201 added new
 202 .BR statfs64 ()
 203 and
 204 .BR fstatfs64 ()
 205 system calls that employ a new structure,
 206 .IR statfs64 .
 207 The new structure contains the same fields as the original
 208 .I statfs
 209 structure, but the sizes of various fields are increased,
 210 to accommodate large file sizes.
 211 The glibc
 212 .BR statfs ()
 213 and
 214 .BR fstatfs ()
 215 wrapper functions transparently deal with the kernel differences.
 216
 217 Some systems only have \fI<sys/vfs.h>\fP, other systems also have
 218 \fI<sys/statfs.h>\fP, where the former includes the latter.
 219 So it seems
 220 including the former is the best choice.
 221
 222 LSB has deprecated the library calls
 223 .BR statfs ()
 224 and
 225 .BR fstatfs ()
 226 and tells us to use
 227 .BR statvfs (2)
 228 and
 229 .BR fstatvfs (2)
 230 instead.
 231 .SS The f_fsid field
 232 Solaris, Irix and POSIX have a system call
 233 .BR statvfs (2)
 234 that returns a
 235 .I "struct statvfs"
 236 (defined in
 237 .IR <sys/statvfs.h> )
 238 containing an
 239 .I "unsigned long"
 240 .IR f_fsid .
 241 Linux, SunOS, HP-UX, 4.4BSD have a system call
 242 .BR statfs ()
 243 that returns a
 244 .I "struct statfs"
 245 (defined in
 246 .IR <sys/vfs.h> )
 247 containing a
 248 .I fsid_t
 249 .IR f_fsid ,
 250 where
 251 .I fsid_t
 252 is defined as
 253 .IR "struct { int val[2]; }" .
 254 The same holds for FreeBSD, except that it uses the include file
 255 .IR <sys/mount.h> .
 256
 257 The general idea is that
 258 .I f_fsid
 259 contains some random stuff such that the pair
 260 .RI ( f_fsid , ino )
 261 uniquely determines a file.
 262 Some operating systems use (a variation on) the device number, or the device number
 263 combined with the file-system type.
 264 Several OSes restrict giving out the
 265 .I f_fsid
 266 field to the superuser only (and zero it for unprivileged users),
 267 because this field is used in the filehandle of the file system
 268 when NFS-exported, and giving it out is a security concern.
 269 .LP
 270 Under some operating systems the
 271 .I fsid
 272 can be used as second argument to the
 273 .BR sysfs (2)
 274 system call.
 275 .SH "SEE ALSO"
 276 .BR stat (2),
 277 .BR statvfs (2),
 278 .BR path_resolution (7)