1.\" Copyright (c) 1989, 1991, 1993
2.\" The Regents of the University of California. All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\" notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\" notice, this list of conditions and the following disclaimer in the
11.\" documentation and/or other materials provided with the distribution.
12.\" 3. All advertising materials mentioning features or use of this software
13.\" must display the following acknowledgement:
14.\" This product includes software developed by the University of
15.\" California, Berkeley and its contributors.
16.\" 4. Neither the name of the University nor the names of its contributors
17.\" may be used to endorse or promote products derived from this software
18.\" without specific prior written permission.
19.\"
20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
32.\" @(#)statfs.2 8.5 (Berkeley) 5/24/95
33.\" $FreeBSD: head/lib/libc/sys/statfs.2 132467 2004-07-20 19:30:57Z csjp $
34.\"
35.Dd November 16, 2003
36.Dt STATFS 2
37.Os
38.Sh NAME
39.Nm statfs
40.Nd get file system statistics
41.Sh LIBRARY
42.Lb libc
43.Sh SYNOPSIS
44.In sys/param.h
45.In sys/mount.h
46.Ft int
47.Fn statfs "const char *path" "struct statfs *buf"
48.Ft int
49.Fn fstatfs "int fd" "struct statfs *buf"
50.Sh DESCRIPTION
51The
52.Fn statfs
53system call
54returns information about a mounted file system.
55The
56.Fa path
57argument
58is the path name of any file within the mounted file system.
59The
60.Fa buf
61argument
62is a pointer to a
63.Vt statfs
64structure defined as follows:
65.Bd -literal
66typedef struct fsid { int32_t val[2]; } fsid_t; /* file system id type */
67
68/*
69 * filesystem statistics
70 */
71
72#define MFSNAMELEN 16 /* length of type name including null */
73#define MNAMELEN 88 /* size of on/from name bufs */
74#define STATFS_VERSION 0x20030518 /* current version number */
75
76struct statfs {
77uint32_t f_version; /* structure version number */
78uint32_t f_type; /* type of filesystem */
79uint64_t f_flags; /* copy of mount exported flags */
80uint64_t f_bsize; /* filesystem fragment size */
81uint64_t f_iosize; /* optimal transfer block size */
82uint64_t f_blocks; /* total data blocks in filesystem */
83uint64_t f_bfree; /* free blocks in filesystem */
84int64_t f_bavail; /* free blocks avail to non-superuser */
85uint64_t f_files; /* total file nodes in filesystem */
86int64_t f_ffree; /* free nodes avail to non-superuser */
87uint64_t f_syncwrites; /* count of sync writes since mount */
88uint64_t f_asyncwrites; /* count of async writes since mount */
89uint64_t f_syncreads; /* count of sync reads since mount */
90uint64_t f_asyncreads; /* count of async reads since mount */
91uint64_t f_spare[10]; /* unused spare */
92uint32_t f_namemax; /* maximum filename length */
93uid_t f_owner; /* user that mounted the filesystem */
94fsid_t f_fsid; /* filesystem id */
95char f_charspare[80]; /* spare string space */
96char f_fstypename[MFSNAMELEN]; /* filesystem type name */
97char f_mntfromname[MNAMELEN]; /* mounted filesystem */
98char f_mntonname[MNAMELEN]; /* directory on which mounted */
99};
100.Ed
101.Pp
102The flags that may be returned include:
103.Bl -tag -width MNT_SYNCHRONOUS
104.It Dv MNT_RDONLY
105The file system is mounted read-only;
106Even the super-user may not write on it.
107.It Dv MNT_NOEXEC
108Files may not be executed from the file system.
109.It Dv MNT_NOSUID
110Setuid and setgid bits on files are not honored when they are executed.
111.It Dv MNT_NODEV
112Special files in the file system may not be opened.
113.It Dv MNT_SYNCHRONOUS
114All I/O to the file system is done synchronously.
115.It Dv MNT_ASYNC
116No file system I/O is done synchronously.
117.It Dv MNT_SOFTDEP
118Soft updates being done (see
119.Xr ffs 7 ) .
120.It Dv MNT_SUIDDIR
121Special handling of SUID bit on directories.
122.It Dv MNT_UNION
123Union with underlying file system.
124.It Dv MNT_NOSYMFOLLOW
125Symbolic links are not followed.
126.It Dv MNT_NOCLUSTERR
127Read clustering is disabled.
128.It Dv MNT_NOCLUSTERW
129Write clustering is disabled.
130.\".It Dv MNT_JAILDEVFS
131.\"XXX
132.It Dv MNT_MULTILABEL
133Mandatory Access Control (MAC) support for individual objects
134(see
135.Xr mac 4 ) .
136.It Dv MNT_ACLS
137Access Control List (ACL) support enabled.
138.It Dv MNT_LOCAL
139The file system resides locally.
140.It Dv MNT_QUOTA
141The file system has quotas enabled on it.
142.It Dv MNT_ROOTFS
143Identifies the root file system.
144.It Dv MNT_EXRDONLY
145The file system is exported read-only.
146.It Dv MNT_NOATIME
147Updating of file access times is disabled.
148.It Dv MNT_USER
149The file system has been mounted by a user.
150.\".It Dv MNT_IGNORE
151.\"XXX
152.It Dv MNT_EXPORTED
153The file system is exported for both reading and writing.
154.It Dv MNT_DEFEXPORTED
155The file system is exported for both reading and writing to any Internet host.
156.It Dv MNT_EXPORTANON
157The file system maps all remote accesses to the anonymous user.
158.It Dv MNT_EXKERB
159The file system is exported with Kerberos uid mapping.
160.It Dv MNT_EXPUBLIC
161The file system is exported publicly (WebNFS).
162.El
163.Pp
164Fields that are undefined for a particular file system are set to -1.
165The
166.Fn fstatfs
167system call
168returns the same information about an open file referenced by descriptor
169.Fa fd .
170.Sh RETURN VALUES
171.Rv -std
172.Sh ERRORS
173The
174.Fn statfs
175system call
176fails if one or more of the following are true:
177.Bl -tag -width Er
178.It Bq Er ENOTDIR
179A component of the path prefix of
180.Fa path
181is not a directory.
182.It Bq Er ENAMETOOLONG
183The length of a component of
184.Fa path
185exceeds 255 characters,
186or the length of
187.Fa path
188exceeds 1023 characters.
189.It Bq Er ENOENT
190The file referred to by
191.Fa path
192does not exist.
193.It Bq Er EACCES
194Search permission is denied for a component of the path prefix of
195.Fa path .
196.It Bq Er ELOOP
197Too many symbolic links were encountered in translating
198.Fa path .
199.It Bq Er EFAULT
200The
201.Fa buf
202or
203.Fa path
204argument
205points to an invalid address.
206.It Bq Er EIO
207An
208.Tn I/O
209error occurred while reading from or writing to the file system.
210.El
211.Pp
212The
213.Fn fstatfs
214system call
215fails if one or more of the following are true:
216.Bl -tag -width Er
217.It Bq Er EBADF
218The
219.Fa fd
220argument
221is not a valid open file descriptor.
222.It Bq Er EFAULT
223The
224.Fa buf
225argument
226points to an invalid address.
227.It Bq Er EIO
228An
229.Tn I/O
230error occurred while reading from or writing to the file system.
231.El
232.Sh HISTORY
233The
234.Fn statfs
235system call first appeared in
236.Bx 4.4 .
2.\" The Regents of the University of California. All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\" notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\" notice, this list of conditions and the following disclaimer in the
11.\" documentation and/or other materials provided with the distribution.
12.\" 3. All advertising materials mentioning features or use of this software
13.\" must display the following acknowledgement:
14.\" This product includes software developed by the University of
15.\" California, Berkeley and its contributors.
16.\" 4. Neither the name of the University nor the names of its contributors
17.\" may be used to endorse or promote products derived from this software
18.\" without specific prior written permission.
19.\"
20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
32.\" @(#)statfs.2 8.5 (Berkeley) 5/24/95
33.\" $FreeBSD: head/lib/libc/sys/statfs.2 132467 2004-07-20 19:30:57Z csjp $
34.\"
35.Dd November 16, 2003
36.Dt STATFS 2
37.Os
38.Sh NAME
39.Nm statfs
40.Nd get file system statistics
41.Sh LIBRARY
42.Lb libc
43.Sh SYNOPSIS
44.In sys/param.h
45.In sys/mount.h
46.Ft int
47.Fn statfs "const char *path" "struct statfs *buf"
48.Ft int
49.Fn fstatfs "int fd" "struct statfs *buf"
50.Sh DESCRIPTION
51The
52.Fn statfs
53system call
54returns information about a mounted file system.
55The
56.Fa path
57argument
58is the path name of any file within the mounted file system.
59The
60.Fa buf
61argument
62is a pointer to a
63.Vt statfs
64structure defined as follows:
65.Bd -literal
66typedef struct fsid { int32_t val[2]; } fsid_t; /* file system id type */
67
68/*
69 * filesystem statistics
70 */
71
72#define MFSNAMELEN 16 /* length of type name including null */
73#define MNAMELEN 88 /* size of on/from name bufs */
74#define STATFS_VERSION 0x20030518 /* current version number */
75
76struct statfs {
77uint32_t f_version; /* structure version number */
78uint32_t f_type; /* type of filesystem */
79uint64_t f_flags; /* copy of mount exported flags */
80uint64_t f_bsize; /* filesystem fragment size */
81uint64_t f_iosize; /* optimal transfer block size */
82uint64_t f_blocks; /* total data blocks in filesystem */
83uint64_t f_bfree; /* free blocks in filesystem */
84int64_t f_bavail; /* free blocks avail to non-superuser */
85uint64_t f_files; /* total file nodes in filesystem */
86int64_t f_ffree; /* free nodes avail to non-superuser */
87uint64_t f_syncwrites; /* count of sync writes since mount */
88uint64_t f_asyncwrites; /* count of async writes since mount */
89uint64_t f_syncreads; /* count of sync reads since mount */
90uint64_t f_asyncreads; /* count of async reads since mount */
91uint64_t f_spare[10]; /* unused spare */
92uint32_t f_namemax; /* maximum filename length */
93uid_t f_owner; /* user that mounted the filesystem */
94fsid_t f_fsid; /* filesystem id */
95char f_charspare[80]; /* spare string space */
96char f_fstypename[MFSNAMELEN]; /* filesystem type name */
97char f_mntfromname[MNAMELEN]; /* mounted filesystem */
98char f_mntonname[MNAMELEN]; /* directory on which mounted */
99};
100.Ed
101.Pp
102The flags that may be returned include:
103.Bl -tag -width MNT_SYNCHRONOUS
104.It Dv MNT_RDONLY
105The file system is mounted read-only;
106Even the super-user may not write on it.
107.It Dv MNT_NOEXEC
108Files may not be executed from the file system.
109.It Dv MNT_NOSUID
110Setuid and setgid bits on files are not honored when they are executed.
111.It Dv MNT_NODEV
112Special files in the file system may not be opened.
113.It Dv MNT_SYNCHRONOUS
114All I/O to the file system is done synchronously.
115.It Dv MNT_ASYNC
116No file system I/O is done synchronously.
117.It Dv MNT_SOFTDEP
118Soft updates being done (see
119.Xr ffs 7 ) .
120.It Dv MNT_SUIDDIR
121Special handling of SUID bit on directories.
122.It Dv MNT_UNION
123Union with underlying file system.
124.It Dv MNT_NOSYMFOLLOW
125Symbolic links are not followed.
126.It Dv MNT_NOCLUSTERR
127Read clustering is disabled.
128.It Dv MNT_NOCLUSTERW
129Write clustering is disabled.
130.\".It Dv MNT_JAILDEVFS
131.\"XXX
132.It Dv MNT_MULTILABEL
133Mandatory Access Control (MAC) support for individual objects
134(see
135.Xr mac 4 ) .
136.It Dv MNT_ACLS
137Access Control List (ACL) support enabled.
138.It Dv MNT_LOCAL
139The file system resides locally.
140.It Dv MNT_QUOTA
141The file system has quotas enabled on it.
142.It Dv MNT_ROOTFS
143Identifies the root file system.
144.It Dv MNT_EXRDONLY
145The file system is exported read-only.
146.It Dv MNT_NOATIME
147Updating of file access times is disabled.
148.It Dv MNT_USER
149The file system has been mounted by a user.
150.\".It Dv MNT_IGNORE
151.\"XXX
152.It Dv MNT_EXPORTED
153The file system is exported for both reading and writing.
154.It Dv MNT_DEFEXPORTED
155The file system is exported for both reading and writing to any Internet host.
156.It Dv MNT_EXPORTANON
157The file system maps all remote accesses to the anonymous user.
158.It Dv MNT_EXKERB
159The file system is exported with Kerberos uid mapping.
160.It Dv MNT_EXPUBLIC
161The file system is exported publicly (WebNFS).
162.El
163.Pp
164Fields that are undefined for a particular file system are set to -1.
165The
166.Fn fstatfs
167system call
168returns the same information about an open file referenced by descriptor
169.Fa fd .
170.Sh RETURN VALUES
171.Rv -std
172.Sh ERRORS
173The
174.Fn statfs
175system call
176fails if one or more of the following are true:
177.Bl -tag -width Er
178.It Bq Er ENOTDIR
179A component of the path prefix of
180.Fa path
181is not a directory.
182.It Bq Er ENAMETOOLONG
183The length of a component of
184.Fa path
185exceeds 255 characters,
186or the length of
187.Fa path
188exceeds 1023 characters.
189.It Bq Er ENOENT
190The file referred to by
191.Fa path
192does not exist.
193.It Bq Er EACCES
194Search permission is denied for a component of the path prefix of
195.Fa path .
196.It Bq Er ELOOP
197Too many symbolic links were encountered in translating
198.Fa path .
199.It Bq Er EFAULT
200The
201.Fa buf
202or
203.Fa path
204argument
205points to an invalid address.
206.It Bq Er EIO
207An
208.Tn I/O
209error occurred while reading from or writing to the file system.
210.El
211.Pp
212The
213.Fn fstatfs
214system call
215fails if one or more of the following are true:
216.Bl -tag -width Er
217.It Bq Er EBADF
218The
219.Fa fd
220argument
221is not a valid open file descriptor.
222.It Bq Er EFAULT
223The
224.Fa buf
225argument
226points to an invalid address.
227.It Bq Er EIO
228An
229.Tn I/O
230error occurred while reading from or writing to the file system.
231.El
232.Sh HISTORY
233The
234.Fn statfs
235system call first appeared in
236.Bx 4.4 .