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 inodes in filesystem */
28               fsfilcnt_t f_ffree;   /* Free inodes 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           SMB2_MAGIC_NUMBER     0xfe534d42
110           SOCKFS_MAGIC          0x534f434b
111           SQUASHFS_MAGIC        0x73717368
112           SYSFS_MAGIC           0x62656572
113           SYSV2_SUPER_MAGIC     0x012ff7b6
114           SYSV4_SUPER_MAGIC     0x012ff7b5
115           TMPFS_MAGIC           0x01021994
116           TRACEFS_MAGIC         0x74726163
117           UDF_SUPER_MAGIC       0x15013346
118           UFS_MAGIC             0x00011954
119           USBDEVICE_SUPER_MAGIC 0x9fa2
120           V9FS_MAGIC            0x01021997
121           VXFS_SUPER_MAGIC      0xa501fcf5
122           XENFS_SUPER_MAGIC     0xabba1974
123           XENIX_SUPER_MAGIC     0x012ff7b4
124           XFS_SUPER_MAGIC       0x58465342
125           _XIAFS_SUPER_MAGIC    0x012fd16d /* Linux 2.0 and earlier */
126
127       Most    of     these     MAGIC     constants     are     defined     in
128       /usr/include/linux/magic.h, and some are hardcoded in kernel sources.
129
130       The  f_flags  field  is  a  bit  mask  indicating mount options for the
131       filesystem.  It contains zero or more of the following bits:
132
133       ST_MANDLOCK
134              Mandatory locking is permitted on the filesystem (see fcntl(2)).
135
136       ST_NOATIME
137              Do not update access times; see mount(2).
138
139       ST_NODEV
140              Disallow access to device special files on this filesystem.
141
142       ST_NODIRATIME
143              Do not update directory access times; see mount(2).
144
145       ST_NOEXEC
146              Execution of programs is disallowed on this filesystem.
147
148       ST_NOSUID
149              The set-user-ID and set-group-ID bits are ignored by exec(3) for
150              executable files on this filesystem
151
152       ST_RDONLY
153              This filesystem is mounted read-only.
154
155       ST_RELATIME
156              Update atime relative to mtime/ctime; see mount(2).
157
158       ST_SYNCHRONOUS
159              Writes  are  synched  to  the  filesystem  immediately  (see the
160              description of O_SYNC in open(2)).
161
162       Nobody knows what f_fsid is supposed to contain (but see below).
163
164       Fields that are undefined for a particular filesystem are set to 0.
165
166       fstatfs() returns the same information about an open file referenced by
167       descriptor fd.
168

RETURN VALUE

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

ERRORS

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

CONFORMING TO

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

NOTES

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

BUGS

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

SEE ALSO

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

COLOPHON

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