1STATFS(2)                  Linux Programmer's Manual                 STATFS(2)
2
3
4

NAME

6       statfs, fstatfs - get filesystem statistics
7

SYNOPSIS

9       #include <sys/vfs.h>    /* or <sys/statfs.h> */
10
11       int statfs(const char *path, struct statfs *buf);
12       int fstatfs(int fd, struct statfs *buf);
13

DESCRIPTION

15       The  statfs()  system call returns information about a mounted filesys‐
16       tem.  path is the pathname of any file within the  mounted  filesystem.
17       buf  is  a  pointer to a statfs structure defined approximately as fol‐
18       lows:
19
20           struct statfs {
21               __fsword_t f_type;    /* Type of filesystem (see below) */
22               __fsword_t f_bsize;   /* Optimal transfer block size */
23               fsblkcnt_t f_blocks;  /* Total data blocks in filesystem */
24               fsblkcnt_t f_bfree;   /* Free blocks in filesystem */
25               fsblkcnt_t f_bavail;  /* Free blocks available to
26                                        unprivileged user */
27               fsfilcnt_t f_files;   /* Total file nodes in filesystem */
28               fsfilcnt_t f_ffree;   /* Free file nodes in filesystem */
29               fsid_t     f_fsid;    /* Filesystem ID */
30               __fsword_t f_namelen; /* Maximum length of filenames */
31               __fsword_t f_frsize;  /* Fragment size (since Linux 2.6) */
32               __fsword_t f_flags;   /* Mount flags of filesystem
33                                        (since Linux 2.6.36) */
34               __fsword_t f_spare[xxx];
35                               /* Padding bytes reserved for future use */
36           };
37
38       The following filesystem types may appear in f_type:
39
40           ADFS_SUPER_MAGIC      0xadf5
41           AFFS_SUPER_MAGIC      0xadff
42           AFS_SUPER_MAGIC       0x5346414f
43           ANON_INODE_FS_MAGIC   0x09041934 /* Anonymous inode FS (for
44                                               pseudofiles that have no name;
45                                               e.g., epoll, signalfd, bpf) */
46           AUTOFS_SUPER_MAGIC    0x0187
47           BDEVFS_MAGIC          0x62646576
48           BEFS_SUPER_MAGIC      0x42465331
49           BFS_MAGIC             0x1badface
50           BINFMTFS_MAGIC        0x42494e4d
51           BPF_FS_MAGIC          0xcafe4a11
52           BTRFS_SUPER_MAGIC     0x9123683e
53           BTRFS_TEST_MAGIC      0x73727279
54           CGROUP_SUPER_MAGIC    0x27e0eb   /* Cgroup pseudo FS */
55           CGROUP2_SUPER_MAGIC   0x63677270 /* Cgroup v2 pseudo FS */
56           CIFS_MAGIC_NUMBER     0xff534d42
57           CODA_SUPER_MAGIC      0x73757245
58           COH_SUPER_MAGIC       0x012ff7b7
59           CRAMFS_MAGIC          0x28cd3d45
60           DEBUGFS_MAGIC         0x64626720
61           DEVFS_SUPER_MAGIC     0x1373     /* Linux 2.6.17 and earlier */
62           DEVPTS_SUPER_MAGIC    0x1cd1
63           ECRYPTFS_SUPER_MAGIC  0xf15f
64           EFIVARFS_MAGIC        0xde5e81e4
65           EFS_SUPER_MAGIC       0x00414a53
66           EXT_SUPER_MAGIC       0x137d     /* Linux 2.0 and earlier */
67           EXT2_OLD_SUPER_MAGIC  0xef51
68           EXT2_SUPER_MAGIC      0xef53
69           EXT3_SUPER_MAGIC      0xef53
70           EXT4_SUPER_MAGIC      0xef53
71           F2FS_SUPER_MAGIC      0xf2f52010
72           FUSE_SUPER_MAGIC      0x65735546
73           FUTEXFS_SUPER_MAGIC   0xbad1dea  /* Unused */
74           HFS_SUPER_MAGIC       0x4244
75           HOSTFS_SUPER_MAGIC    0x00c0ffee
76           HPFS_SUPER_MAGIC      0xf995e849
77           HUGETLBFS_MAGIC       0x958458f6
78           ISOFS_SUPER_MAGIC     0x9660
79           JFFS2_SUPER_MAGIC     0x72b6
80           JFS_SUPER_MAGIC       0x3153464a
81           MINIX_SUPER_MAGIC     0x137f     /* original minix FS */
82           MINIX_SUPER_MAGIC2    0x138f     /* 30 char minix FS */
83           MINIX2_SUPER_MAGIC    0x2468     /* minix V2 FS */
84           MINIX2_SUPER_MAGIC2   0x2478     /* minix V2 FS, 30 char names */
85           MINIX3_SUPER_MAGIC    0x4d5a     /* minix V3 FS, 60 char names */
86           MQUEUE_MAGIC          0x19800202 /* POSIX message queue FS */
87           MSDOS_SUPER_MAGIC     0x4d44
88           MTD_INODE_FS_MAGIC    0x11307854
89           NCP_SUPER_MAGIC       0x564c
90           NFS_SUPER_MAGIC       0x6969
91           NILFS_SUPER_MAGIC     0x3434
92           NSFS_MAGIC            0x6e736673
93           NTFS_SB_MAGIC         0x5346544e
94           OCFS2_SUPER_MAGIC     0x7461636f
95           OPENPROM_SUPER_MAGIC  0x9fa1
96           OVERLAYFS_SUPER_MAGIC 0x794c7630
97           PIPEFS_MAGIC          0x50495045
98           PROC_SUPER_MAGIC      0x9fa0     /* /proc FS */
99           PSTOREFS_MAGIC        0x6165676c
100           QNX4_SUPER_MAGIC      0x002f
101           QNX6_SUPER_MAGIC      0x68191122
102           RAMFS_MAGIC           0x858458f6
103           REISERFS_SUPER_MAGIC  0x52654973
104           ROMFS_MAGIC           0x7275
105           SECURITYFS_MAGIC      0x73636673
106           SELINUX_MAGIC         0xf97cff8c
107           SMACK_MAGIC           0x43415d53
108           SMB_SUPER_MAGIC       0x517b
109           SOCKFS_MAGIC          0x534f434b
110           SQUASHFS_MAGIC        0x73717368
111           SYSFS_MAGIC           0x62656572
112           SYSV2_SUPER_MAGIC     0x012ff7b6
113           SYSV4_SUPER_MAGIC     0x012ff7b5
114           TMPFS_MAGIC           0x01021994
115           TRACEFS_MAGIC         0x74726163
116           UDF_SUPER_MAGIC       0x15013346
117           UFS_MAGIC             0x00011954
118           USBDEVICE_SUPER_MAGIC 0x9fa2
119           V9FS_MAGIC            0x01021997
120           VXFS_SUPER_MAGIC      0xa501fcf5
121           XENFS_SUPER_MAGIC     0xabba1974
122           XENIX_SUPER_MAGIC     0x012ff7b4
123           XFS_SUPER_MAGIC       0x58465342
124           _XIAFS_SUPER_MAGIC    0x012fd16d /* Linux 2.0 and earlier */
125
126       Most    of     these     MAGIC     constants     are     defined     in
127       /usr/include/linux/magic.h, and some are hardcoded in kernel sources.
128
129       The  f_flags  field  is  a  bit  mask  indicating mount options for the
130       filesystem.  It contains zero or more of the following bits:
131
132       ST_MANDLOCK
133              Mandatory locking is permitted on the filesystem (see fcntl(2)).
134
135       ST_NOATIME
136              Do not update access times; see mount(2).
137
138       ST_NODEV
139              Disallow access to device special files on this filesystem.
140
141       ST_NODIRATIME
142              Do not update directory access times; see mount(2).
143
144       ST_NOEXEC
145              Execution of programs is disallowed on this filesystem.
146
147       ST_NOSUID
148              The set-user-ID and set-group-ID bits are ignored by exec(3) for
149              executable files on this filesystem
150
151       ST_RDONLY
152              This filesystem is mounted read-only.
153
154       ST_RELATIME
155              Update atime relative to mtime/ctime; see mount(2).
156
157       ST_SYNCHRONOUS
158              Writes  are  synched  to  the  filesystem  immediately  (see the
159              description of O_SYNC in open(2)).
160
161       Nobody knows what f_fsid is supposed to contain (but see below).
162
163       Fields that are undefined for a particular filesystem are set to 0.
164
165       fstatfs() returns the same information about an open file referenced by
166       descriptor fd.
167

RETURN VALUE

169       On  success,  zero is returned.  On error, -1 is returned, and errno is
170       set appropriately.
171

ERRORS

173       EACCES (statfs()) Search permission is denied for a  component  of  the
174              path prefix of path.  (See also path_resolution(7).)
175
176       EBADF  (fstatfs()) fd is not a valid open file descriptor.
177
178       EFAULT buf or path points to an invalid address.
179
180       EINTR  The call was interrupted by a signal; see signal(7).
181
182       EIO    An I/O error occurred while reading from the filesystem.
183
184       ELOOP  (statfs()) Too many symbolic links were encountered in translat‐
185              ing path.
186
187       ENAMETOOLONG
188              (statfs()) path is too long.
189
190       ENOENT (statfs()) The file referred to by path does not exist.
191
192       ENOMEM Insufficient kernel memory was available.
193
194       ENOSYS The filesystem does not support this call.
195
196       ENOTDIR
197              (statfs()) A component of the path  prefix  of  path  is  not  a
198              directory.
199
200       EOVERFLOW
201              Some  values  were  too  large to be represented in the returned
202              struct.
203

CONFORMING TO

205       Linux-specific.  The Linux statfs() was inspired by the 4.4BSD one (but
206       they do not use the same structure).
207

NOTES

209       The  __fsword_t  type  used  for various fields in the statfs structure
210       definition is a glibc internal type, not intended for public use.  This
211       leaves  the  programmer  in a bit of a conundrum when trying to copy or
212       compare  these  fields  to  local  variables  in  a   program.    Using
213       unsigned int for such variables suffices on most systems.
214
215       The  original  Linux  statfs()  and  fstatfs()  system  calls  were not
216       designed with extremely large file sizes in mind.  Subsequently,  Linux
217       2.6 added new statfs64() and fstatfs64() system calls that employ a new
218       structure, statfs64.  The new structure contains the same fields as the
219       original  statfs  structure,  but  the  sizes  of  various  fields  are
220       increased, to accommodate large file sizes.   The  glibc  statfs()  and
221       fstatfs()  wrapper functions transparently deal with the kernel differ‐
222       ences.
223
224       Some  systems  have  only  <sys/vfs.h>,   other   systems   also   have
225       <sys/statfs.h>,  where  the  former  includes  the latter.  So it seems
226       including the former is the best choice.
227
228       LSB has deprecated the library calls statfs() and fstatfs()  and  tells
229       us to use statvfs(2) and fstatvfs(2) instead.
230
231   The f_fsid field
232       Solaris,  Irix  and  POSIX have a system call statvfs(2) that returns a
233       struct statvfs (defined in <sys/statvfs.h>) containing an unsigned long
234       f_fsid.   Linux,  SunOS, HP-UX, 4.4BSD have a system call statfs() that
235       returns a struct statfs (defined in <sys/vfs.h>)  containing  a  fsid_t
236       f_fsid,  where  fsid_t  is defined as struct { int val[2]; }.  The same
237       holds for FreeBSD, except that it uses the include file <sys/mount.h>.
238
239       The general idea is that f_fsid contains some random  stuff  such  that
240       the  pair (f_fsid,ino) uniquely determines a file.  Some operating sys‐
241       tems use (a variation on) the device number, or the device number  com‐
242       bined  with  the  filesystem  type.  Several operating systems restrict
243       giving out the f_fsid field to the superuser  only  (and  zero  it  for
244       unprivileged  users),  because  this field is used in the filehandle of
245       the filesystem when NFS-exported, and giving it out is a security  con‐
246       cern.
247
248       Under  some operating systems, the fsid can be used as the second argu‐
249       ment to the sysfs(2) system call.
250

BUGS

252       From Linux 2.6.38 up to and including Linux 3.1, fstatfs() failed  with
253       the error ENOSYS for file descriptors created by pipe(2).
254

SEE ALSO

256       stat(2), statvfs(3), path_resolution(7)
257

COLOPHON

259       This  page  is  part of release 4.15 of the Linux man-pages project.  A
260       description of the project, information about reporting bugs,  and  the
261       latest     version     of     this    page,    can    be    found    at
262       https://www.kernel.org/doc/man-pages/.
263
264
265
266Linux                             2017-09-15                         STATFS(2)
Impressum