Debian Codegraph @

upstream/debian-unstable/man3/statvfs.3

raw
1 '\" t
2 .\" Copyright 2003, Andries E. Brouwer <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH statvfs 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 statvfs, fstatvfs \- get filesystem statistics
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #include <sys/statvfs.h>
16 .P
17 .BI "int statvfs(const char *restrict " path \
18 ", struct statvfs *restrict " buf );
19 .BI "int fstatvfs(int " fd ", struct statvfs *" buf );
20 .fi
21 .SH DESCRIPTION
22 The function
23 .BR statvfs ()
24 returns information about a mounted filesystem.
25 .I path
26 is the pathname of any file within the mounted filesystem.
27 .I buf
28 is a pointer to a
29 .I statvfs
30 structure defined approximately as follows:
31 .P
32 .in +4n
33 .EX
34 struct statvfs {
35 unsigned long f_bsize; /* Filesystem block size */
36 unsigned long f_frsize; /* Fragment size */
37 fsblkcnt_t f_blocks; /* Size of fs in f_frsize units */
38 fsblkcnt_t f_bfree; /* Number of free blocks */
39 fsblkcnt_t f_bavail; /* Number of free blocks for
40 unprivileged users */
41 fsfilcnt_t f_files; /* Number of inodes */
42 fsfilcnt_t f_ffree; /* Number of free inodes */
43 fsfilcnt_t f_favail; /* Number of free inodes for
44 unprivileged users */
45 unsigned long f_fsid; /* Filesystem ID */
46 unsigned long f_flag; /* Mount flags */
47 unsigned long f_namemax; /* Maximum filename length */
48 };
49 .EE
50 .in
51 .P
52 Here the types
53 .I fsblkcnt_t
54 and
55 .I fsfilcnt_t
56 are defined in
57 .IR <sys/types.h> .
58 Both used to be
59 .IR "unsigned long" .
60 .P
61 The field
62 .I f_flag
63 is a bit mask indicating various options that were employed
64 when mounting this filesystem.
65 It contains zero or more of the following flags:
66 .\" XXX Keep this list in sync with statfs(2)
67 .TP
68 .B ST_MANDLOCK
69 Mandatory locking is permitted on the filesystem (see
70 .BR fcntl (2)).
71 .TP
72 .B ST_NOATIME
73 Do not update access times;
74 see
75 .BR mount (2).
76 .TP
77 .B ST_NODEV
78 Disallow access to device special files on this filesystem.
79 .TP
80 .B ST_NODIRATIME
81 Do not update directory access times;
82 see
83 .BR mount (2).
84 .TP
85 .B ST_NOEXEC
86 Execution of programs is disallowed on this filesystem.
87 .TP
88 .B ST_NOSUID
89 The set-user-ID and set-group-ID bits are ignored by
90 .BR exec (3)
91 for executable files on this filesystem
92 .TP
93 .B ST_RDONLY
94 This filesystem is mounted read-only.
95 .TP
96 .B ST_RELATIME
97 Update atime relative to mtime/ctime;
98 see
99 .BR mount (2).
100 .TP
101 .B ST_SYNCHRONOUS
102 Writes are synched to the filesystem immediately (see the description of
103 .B O_SYNC
104 in
105 .BR open (2)).
106 .P
107 It is unspecified whether all members of the returned struct
108 have meaningful values on all filesystems.
109 .P
110 .BR fstatvfs ()
111 returns the same information about an open file referenced by descriptor
112 .IR fd .
113 .SH RETURN VALUE
114 On success, zero is returned.
115 On error, \-1 is returned, and
116 .I errno
117 is set to indicate the error.
118 .SH ERRORS
119 .TP
120 .B EACCES
121 .RB ( statvfs ())
122 Search permission is denied for a component of the path prefix of
123 .IR path .
124 (See also
125 .BR path_resolution (7).)
126 .TP
127 .B EBADF
128 .RB ( fstatvfs ())
129 .I fd
130 is not a valid open file descriptor.
131 .TP
132 .B EFAULT
133 .I Buf
134 or
135 .I path
136 points to an invalid address.
137 .TP
138 .B EINTR
139 This call was interrupted by a signal;
140 see
141 .BR signal (7).
142 .TP
143 .B EIO
144 An I/O error occurred while reading from the filesystem.
145 .TP
146 .B ELOOP
147 .RB ( statvfs ())
148 Too many symbolic links were encountered in translating
149 .IR path .
150 .TP
151 .B ENAMETOOLONG
152 .RB ( statvfs ())
153 .I path
154 is too long.
155 .TP
156 .B ENOENT
157 .RB ( statvfs ())
158 The file referred to by
159 .I path
160 does not exist.
161 .TP
162 .B ENOMEM
163 Insufficient kernel memory was available.
164 .TP
165 .B ENOSYS
166 The filesystem does not support this call.
167 .TP
168 .B ENOTDIR
169 .RB ( statvfs ())
170 A component of the path prefix of
171 .I path
172 is not a directory.
173 .TP
174 .B EOVERFLOW
175 Some values were too large to be represented in the returned struct.
176 .SH ATTRIBUTES
177 For an explanation of the terms used in this section, see
178 .BR attributes (7).
179 .TS
180 allbox;
181 lbx lb lb
182 l l l.
183 Interface Attribute Value
184 T{
185 .na
186 .nh
187 .BR statvfs (),
188 .BR fstatvfs ()
189 T} Thread safety MT-Safe
190 .TE
191 .SH VERSIONS
192 Only the
193 .B ST_NOSUID
194 and
195 .B ST_RDONLY
196 flags of the
197 .I f_flag
198 field are specified in POSIX.1.
199 To obtain definitions of the remaining flags, one must define
200 .BR _GNU_SOURCE .
201 .SH NOTES
202 The Linux kernel has system calls
203 .BR statfs (2)
204 and
205 .BR fstatfs (2)
206 to support this library call.
207 .P
208 The glibc implementations of
209 .P
210 .in +4n
211 .EX
212 pathconf(path, _PC_REC_XFER_ALIGN);
213 pathconf(path, _PC_ALLOC_SIZE_MIN);
214 pathconf(path, _PC_REC_MIN_XFER_SIZE);
215 .EE
216 .in
217 .P
218 respectively use the
219 .IR f_frsize ,
220 .IR f_frsize ,
221 and
222 .I f_bsize
223 fields returned by a call to
224 .BR statvfs ()
225 with the argument
226 .IR path .
227 .P
228 Under Linux,
229 .I f_favail
230 is always the same as
231 .IR f_ffree ,
232 and there's no way for a filesystem to report otherwise.
233 This is not an issue,
234 since no filesystems with an inode root reservation exist.
235 .SH STANDARDS
236 POSIX.1-2008.
237 .SH HISTORY
238 POSIX.1-2001.
239 .P
240 Before glibc 2.13,
241 .\" glibc commit 3cdaa6adb113a088fdfb87aa6d7747557eccc58d
242 .BR statvfs ()
243 populated the bits of the
244 .I f_flag
245 field by scanning the mount options shown in
246 .IR /proc/mounts .
247 However, starting with Linux 2.6.36, the underlying
248 .BR statfs (2)
249 system call provides the necessary information via the
250 .I f_flags
251 field, and since glibc 2.13, the
252 .BR statvfs ()
253 function will use information from that field rather than scanning
254 .IR /proc/mounts .
255 .SH SEE ALSO
256 .BR statfs (2)