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    /usr/in‐
128       clude/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 de‐
160              scription of O_SYNC in open(2)).
161
162       ST_NOSYMFOLLOW (since Linux 5.10)
163              Symbolic links  are  not  followed  when  resolving  paths;  see
164              mount(2).
165
166       Nobody knows what f_fsid is supposed to contain (but see below).
167
168       Fields that are undefined for a particular filesystem are set to 0.
169
170       fstatfs() returns the same information about an open file referenced by
171       descriptor fd.
172

RETURN VALUE

174       On success, zero is returned.  On error, -1 is returned, and  errno  is
175       set to indicate the error.
176

ERRORS

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

CONFORMING TO

210       Linux-specific.  The Linux statfs() was inspired by the 4.4BSD one (but
211       they do not use the same structure).
212

NOTES

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

BUGS

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

SEE ALSO

260       stat(2), statvfs(3), path_resolution(7)
261

COLOPHON

263       This  page  is  part of release 5.13 of the Linux man-pages project.  A
264       description of the project, information about reporting bugs,  and  the
265       latest     version     of     this    page,    can    be    found    at
266       https://www.kernel.org/doc/man-pages/.
267
268
269
270Linux                             2021-03-22                         STATFS(2)
Impressum