xref: /freebsd/lib/libc/gen/statvfs.3 (revision b1f9167f94059fd55c630891d359bcff987bd7eb)
1.\"
2.\" Copyright 2002 Massachusetts Institute of Technology
3.\"
4.\" Permission to use, copy, modify, and distribute this software and
5.\" its documentation for any purpose and without fee is hereby
6.\" granted, provided that both the above copyright notice and this
7.\" permission notice appear in all copies, that both the above
8.\" copyright notice and this permission notice appear in all
9.\" supporting documentation, and that the name of M.I.T. not be used
10.\" in advertising or publicity pertaining to distribution of the
11.\" software without specific, written prior permission.  M.I.T. makes
12.\" no representations about the suitability of this software for any
13.\" purpose.  It is provided "as is" without express or implied
14.\" warranty.
15.\"
16.\" THIS SOFTWARE IS PROVIDED BY M.I.T. ``AS IS''.  M.I.T. DISCLAIMS
17.\" ALL EXPRESS OR IMPLIED WARRANTIES WITH REGARD TO THIS SOFTWARE,
18.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
19.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT
20.\" SHALL M.I.T. BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
21.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
22.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
23.\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
24.\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
25.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
26.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
27.\" SUCH DAMAGE.
28.\"
29.\" $FreeBSD$
30.\"
31.Dd July 13, 2002
32.Dt STATVFS 3
33.Os
34.Sh NAME
35.Nm statvfs ,
36.Nm fstatvfs
37.Nd retrieve file system information
38.Sh LIBRARY
39.Lb libc
40.Sh SYNOPSIS
41.In sys/statvfs.h
42.Ft int
43.Fn statvfs "const char * restrict path" "struct statvfs * restrict buf"
44.Ft int
45.Fn fstatvfs "int fd" "struct statvfs *buf"
46.Sh DESCRIPTION
47The
48.Fn statvfs
49and
50.Fn fstatvfs
51functions fill the structure pointed to by
52.Fa buf
53with garbage.
54This garbage will occasionally bear resemblance to file system
55statistics, but portable applications must not depend on this.
56Applications must pass a pathname or file descriptor which refers to a
57file on the file system in which they are interested.
58.Pp
59The
60.Vt statvfs
61structure contains the following members:
62.Bl -tag -offset indent -width ".Va f_namemax"
63.It Va f_namemax
64The maximum length in bytes of a file name on this file system.
65Applications should use
66.Xr pathconf 2
67instead.
68.It Va f_fsid
69Not meaningful in this implementation.
70.It Va f_frsize
71The size in bytes of the minimum unit of allocation on this
72file system.
73(This corresponds to the
74.Va f_bsize
75member of
76.Vt "struct statfs" . )
77.It Va f_bsize
78The preferred length of I/O requests for files on this file system.
79(Corresponds to the
80.Va f_iosize
81member of
82.Vt "struct statfs" . )
83.It Va f_flag
84Flags describing mount options for this file system; see below.
85.El
86.Pp
87In addition, there are three members of type
88.Vt fsfilcnt_t ,
89which represent counts of file serial numbers
90.Em ( i.e. ,
91inodes); these are named
92.Va f_files , f_favail ,
93and
94.Va f_ffree ,
95and represent the number of file serial numbers which exist in total,
96are available to unprivileged processes, and are available to
97privileged processes, respectively.
98Likewise, the members
99.Va f_blocks , f_bavail ,
100and
101.Va f_bfree
102(all of type
103.Vt fsblkcnt_t )
104represent the respective allocation-block counts.
105.Pp
106There are two flags defined for the
107.Va f_flag
108member:
109.Bl -tag -offset indent -width ".Dv ST_NOSUID"
110.It Dv ST_RDONLY
111The file system is mounted read-only.
112.It Dv ST_NOSUID
113The semantics of the
114.Dv S_ISUID
115and
116.Dv S_ISGID
117file mode bits
118are not supported by, or are disabled on, this file system.
119.El
120.Sh IMPLEMENTATION NOTES
121The
122.Fn statvfs
123and
124.Fn fstatvfs
125functions are implemented as wrappers around the
126.Fn statfs
127and
128.Fn fstatfs
129functions, respectively.
130Not all the information provided by those functions is made available
131through this interface.
132.Sh RETURN VALUES
133.Rv -std statvfs fstatvfs
134.Sh ERRORS
135The
136.Fn statvfs
137and
138.Fn fstatvfs
139functions may fail for any of the reasons documented for
140.Xr statfs 2
141or
142.Xr fstatfs 2
143and
144.Xr pathconf 2
145or
146.Xr fpathconf 2 ,
147respectively.
148In addition,
149.Fn statvfs
150and
151.Fn fstatvfs
152functions may also fail for the following reason:
153.Bl -tag -width Er
154.It Bq Er EOVERFLOW
155One or more of the file system statistics has a value which cannot be
156represented by the data types used in
157.Vt "struct statvfs" .
158.El
159.Sh SEE ALSO
160.Xr pathconf 2 ,
161.Xr statfs 2
162.Sh STANDARDS
163The
164.Fn statvfs
165and
166.Fn fstatvfs
167functions conform to
168.St -p1003.1-2001 .
169As standardized, portable applications cannot depend on these functions
170returning any valid information at all.
171This implementation attempts to provide as much useful information as
172is provided by the underlying file system, subject to the limitations
173of the specified data types.
174.Sh HISTORY
175The
176.Fn statvfs
177and
178.Fn fstatvfs
179functions first appeared in
180.Fx 5.0 .
181.Sh AUTHORS
182The
183.Fn statvfs
184and
185.Fn fstatvfs
186functions and this manual page were written by
187.An Garrett Wollman Aq Mt wollman@FreeBSD.org .
188