[apple/xnu.git] / bsd / man / man2 / statfs.2

.\"	$NetBSD: statfs.2,v 1.10 1995/06/29 11:40:48 cgd Exp $
.\"
.\" Copyright (c) 1989, 1991, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"	@(#)statfs.2	8.3 (Berkeley) 2/11/94
.\"
.Dd August 14, 2008
.Dt STATFS 2
.Os
.Sh NAME
.Nm statfs,
.Nm statfs64,
.Nm fstatfs,
.Nm fstatfs64
.Nd get file system statistics
.Sh SYNOPSIS
.Fd #include <sys/param.h>
.Fd #include <sys/mount.h>
.Ft int
.Fn statfs "const char *path" "struct statfs *buf"
.Ft int
.Fn fstatfs "int fd" "struct statfs *buf"
.Sh TRANSITIONAL SYNOPSIS (NOW DEPRECATED)
.Ft int
.br
.Fn statfs64 "const char *path" "struct statfs64 *buf" ;
.sp
.Ft int
.br
.Fn fstatfs64 "int fd" "struct statfs64 *buf" ;
.Sh DESCRIPTION
The
.Fn statfs
routine returns information about a mounted file system.
The
.Fa path
argument is the path name of any file or directory within the mounted file system.
The
.Fa buf
argument is a pointer to a 
.Fa statfs
structure.
When the macro
.Dv _DARWIN_FEATURE_64_BIT_INODE
is not defined (see
.Xr stat 2
for more information on this macro), the
.Fa statfs
structure is defined as:
.Bd -literal
typedef struct { int32_t val[2]; } fsid_t;

#define MFSNAMELEN      15 /* length of fs type name, not inc. nul */
#define MNAMELEN        90 /* length of buffer for returned name */

struct statfs { /* when _DARWIN_FEATURE_64_BIT_INODE is NOT defined */
    short   f_otype;	/* type of file system (reserved: zero) */
    short   f_oflags;	/* copy of mount flags (reserved: zero) */
    long    f_bsize;	/* fundamental file system block size */
    long    f_iosize;	/* optimal transfer block size */
    long    f_blocks;	/* total data blocks in file system */
    long    f_bfree;	/* free blocks in fs */
    long    f_bavail;	/* free blocks avail to non-superuser */
    long    f_files;	/* total file nodes in file system */
    long    f_ffree;	/* free file nodes in fs */
    fsid_t  f_fsid;	/* file system id */
    uid_t   f_owner;	/* user that mounted the file system */
    short   f_reserved1;	/* reserved for future use */
    short   f_type;	/* type of file system (reserved) */
    long    f_flags;	/* copy of mount flags (reserved) */
    long    f_reserved2[2];	/* reserved for future use */
    char    f_fstypename[MFSNAMELEN]; /* fs type name */
    char    f_mntonname[MNAMELEN];    /* directory on which mounted */
    char    f_mntfromname[MNAMELEN];  /* mounted file system */
    char    f_reserved3;	/* reserved for future use */
    long    f_reserved4[4];	/* reserved for future use */
};
.Ed
.Pp
However, when the macro
.Dv _DARWIN_FEATURE_64_BIT_INODE
is defined, the
.Fa statfs
structure is defined as:
.Bd -literal
#define MFSTYPENAMELEN  16 /* length of fs type name including null */
#define MAXPATHLEN      1024	
#define MNAMELEN        MAXPATHLEN

struct statfs { /* when _DARWIN_FEATURE_64_BIT_INODE is defined */
    uint32_t    f_bsize;        /* fundamental file system block size */ 
    int32_t     f_iosize;       /* optimal transfer block size */ 
    uint64_t    f_blocks;       /* total data blocks in file system */ 
    uint64_t    f_bfree;        /* free blocks in fs */ 
    uint64_t    f_bavail;       /* free blocks avail to non-superuser */ 
    uint64_t    f_files;        /* total file nodes in file system */ 
    uint64_t    f_ffree;        /* free file nodes in fs */ 
    fsid_t      f_fsid;         /* file system id */ 
    uid_t       f_owner;        /* user that mounted the filesystem */ 
    uint32_t    f_type;         /* type of filesystem */ 
    uint32_t    f_flags;        /* copy of mount exported flags */ 
    uint32_t    f_fssubtype;    /* fs sub-type (flavor) */ 
    char        f_fstypename[MFSTYPENAMELEN];   /* fs type name */ 
    char        f_mntonname[MAXPATHLEN];        /* directory on which mounted */ 
    char        f_mntfromname[MAXPATHLEN];      /* mounted filesystem */ 
    uint32_t    f_reserved[8];  /* For future use */ 
};
.Ed
.Pp
Note that the
.Fa f_fstypename ,
.Fa f_mntonname ,
and
.Fa f_mntfromname
fields are also wider in this variant.
.Pp
Fields that are undefined for a particular file system are set to -1.
The
.Fn fstatfs
routine returns the same information about an open file referenced by descriptor
.Fa fd .
.Sh FLAGS
.Bl -tag -width MNT_UNKNOWNPERMISSIONS
These are some of the flags that may be present in the f_flags field. 
.It Dv MNT_RDONLY
A read-only filesystem
.It Dv MNT_SYNCHRONOUS
File system is written to synchronously
.It Dv MNT_NOEXEC
Can't exec from filesystem
.It Dv MNT_NOSUID
Setuid bits are not honored on this filesystem
.It Dv MNT_NODEV
Don't interpret special files
.It Dv MNT_UNION
Union with underlying filesysten
.It Dv MNT_ASYNC
File system written to asynchronously
.It Dv MNT_EXPORTED
File system is exported
.It Dv MNT_LOCAL
File system is stored locally
.It Dv MNT_QUOTA
Quotas are enabled on this file system
.It Dv MNT_ROOTFS
This file system is the root of the file system
.It Dv MNT_DOVOLFS
File system supports volfs
.It Dv MNT_DONTBROWSE
File system is not appropriate path to user data
.It Dv MNT_UNKNOWNPERMISSIONS
VFS will ignore ownership information on filesystem objects
.It Dv MNT_AUTOMOUNTED
File system was mounted by automounter
.It Dv MNT_JOURNALED
File system is journaled
.It Dv MNT_DEFWRITE
File system should defer writes
.It Dv MNT_MULTILABEL
MAC support for individual labels
.It Dv MNT_CPROTECT
File system supports per-file encrypted data protection
.El
.Sh CAVEATS
In Mac OS X versions before 10.4, f_iosize is 4096. On these older
systems, use MAXBSIZE instead.
.Sh RETURN VALUES
Upon successful completion, a value of 0 is returned.
Otherwise, -1 is returned and the global variable
.Va errno
is set to indicate the error.
.Sh ERRORS
The
.Fn statfs
routine fails if one or more of the following are true:
.Bl -tag -width Er
.It Bq Er ENOTDIR
A component of the path prefix of
.Fa Path
is not a directory.
.It Bq Er ENAMETOOLONG
The length of a component of
.Fa path
exceeds 
.Dv {NAME_MAX}
characters, or the length of
.Fa path
exceeds 
.Dv {PATH_MAX}
characters.
.It Bq Er ENOENT
The file or directory referred to by
.Fa path
does not exist.
.It Bq Er EACCES
Search permission is denied for a component of the path prefix of
.Fa path .
.It Bq Er ELOOP
Too many symbolic links were encountered in translating
.Fa path .
.It Bq Er EFAULT
.Fa Buf
or
.Fa path
points to an invalid address.
.It Bq Er EIO
An
.Tn I/O
error occurred while reading from or writing to the file system.
.El
.Pp
The
.Fn fstatfs
routine fails if one or more of the following are true:
.Bl -tag -width Er
.It Bq Er EBADF
.Fa fd
is not a valid open file descriptor.
.It Bq Er EFAULT
.Fa Buf
points to an invalid address.
.It Bq Er EIO
An
.Tn I/O
error occurred while reading from or writing to the file system.
.El
.Sh TRANSITIONAL DESCRIPTION (NOW DEPRECATED)
The
.Fa statfs64
and
.Fa fstatfs64
routines are equivalent to their corresponding non-64-suffixed routine,
when 64-bit inodes are in effect.
They were added before there was support for the symbol variants, and so are
now deprecated.
Instead of using these, set the
.Dv _DARWIN_USE_64_BIT_INODE
macro before including header files to force 64-bit inode support.
.Pp
The
.Fa statfs64
structure used by these deprecated routines is the same as the
.Fa statfs
structure when 64-bit inodes are in effect (see above).
.Sh HISTORY
The
.Fn statfs
function first appeared in 4.4BSD. The
.Fn statfs64
and 
.Fn fstatfs64
first appeared in Max OS X 10.5 (Leopard) and are now deprecated
in favor of the corresponding symbol variants.
Commit	Line	Data
9bccf70c A	1	.\" $NetBSD: statfs.2,v 1.10 1995/06/29 11:40:48 cgd Exp $
	2	.\"
	3	.\" Copyright (c) 1989, 1991, 1993
	4	.\" The Regents of the University of California. All rights reserved.
	5	.\"
	6	.\" Redistribution and use in source and binary forms, with or without
	7	.\" modification, are permitted provided that the following conditions
	8	.\" are met:
	9	.\" 1. Redistributions of source code must retain the above copyright
	10	.\" notice, this list of conditions and the following disclaimer.
	11	.\" 2. Redistributions in binary form must reproduce the above copyright
	12	.\" notice, this list of conditions and the following disclaimer in the
	13	.\" documentation and/or other materials provided with the distribution.
	14	.\" 3. All advertising materials mentioning features or use of this software
	15	.\" must display the following acknowledgement:
	16	.\" This product includes software developed by the University of
	17	.\" California, Berkeley and its contributors.
	18	.\" 4. Neither the name of the University nor the names of its contributors
	19	.\" may be used to endorse or promote products derived from this software
	20	.\" without specific prior written permission.
	21	.\"
	22	.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
	23	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	24	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	25	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
	26	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	27	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	28	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	29	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	30	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	31	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	32	.\" SUCH DAMAGE.
	33	.\"
	34	.\" @(#)statfs.2 8.3 (Berkeley) 2/11/94
	35	.\"
b0d623f7	36	.Dd August 14, 2008
9bccf70c A	37	.Dt STATFS 2
	38	.Os
	39	.Sh NAME
2d21ac55	40	.Nm statfs,
b0d623f7 A	41	.Nm statfs64,
	42	.Nm fstatfs,
	43	.Nm fstatfs64
9bccf70c A	44	.Nd get file system statistics
	45	.Sh SYNOPSIS
	46	.Fd #include <sys/param.h>
	47	.Fd #include <sys/mount.h>
	48	.Ft int
	49	.Fn statfs "const char path" "struct statfs buf"
	50	.Ft int
	51	.Fn fstatfs "int fd" "struct statfs *buf"
316670eb	52	.Sh TRANSITIONAL SYNOPSIS (NOW DEPRECATED)
b0d623f7 A	53	.Ft int
	54	.br
	55	.Fn statfs64 "const char path" "struct statfs64 buf" ;
	56	.sp
	57	.Ft int
	58	.br
	59	.Fn fstatfs64 "int fd" "struct statfs64 *buf" ;
9bccf70c	60	.Sh DESCRIPTION
b0d623f7 A	61	The
	62	.Fn statfs
	63	routine returns information about a mounted file system.
	64	The
	65	.Fa path
	66	argument is the path name of any file or directory within the mounted file system.
	67	The
	68	.Fa buf
	69	argument is a pointer to a
2d21ac55	70	.Fa statfs
b0d623f7 A	71	structure.
	72	When the macro
	73	.Dv _DARWIN_FEATURE_64_BIT_INODE
6d2010ae A	74	is not defined (see
	75	.Xr stat 2
	76	for more information on this macro), the
	77	.Fa statfs
	78	structure is defined as:
9bccf70c A	79	.Bd -literal
	80	typedef struct { int32_t val[2]; } fsid_t;
	81
b0d623f7 A	82	#define MFSNAMELEN 15 /* length of fs type name, not inc. nul */
	83	#define MNAMELEN 90 /* length of buffer for returned name */
	84
	85	struct statfs { /* when _DARWIN_FEATURE_64_BIT_INODE is NOT defined */
	86	short f_otype; /* type of file system (reserved: zero) */
	87	short f_oflags; /* copy of mount flags (reserved: zero) */
	88	long f_bsize; /* fundamental file system block size */
	89	long f_iosize; /* optimal transfer block size */
	90	long f_blocks; /* total data blocks in file system */
	91	long f_bfree; /* free blocks in fs */
	92	long f_bavail; /* free blocks avail to non-superuser */
	93	long f_files; /* total file nodes in file system */
	94	long f_ffree; /* free file nodes in fs */
	95	fsid_t f_fsid; /* file system id */
	96	uid_t f_owner; /* user that mounted the file system */
	97	short f_reserved1; /* reserved for future use */
	98	short f_type; /* type of file system (reserved) */
	99	long f_flags; /* copy of mount flags (reserved) */
	100	long f_reserved2[2]; /* reserved for future use */
	101	char f_fstypename[MFSNAMELEN]; /* fs type name */
	102	char f_mntonname[MNAMELEN]; /* directory on which mounted */
	103	char f_mntfromname[MNAMELEN]; /* mounted file system */
	104	char f_reserved3; /* reserved for future use */
	105	long f_reserved4[4]; /* reserved for future use */
	106	};
	107	.Ed
	108	.Pp
	109	However, when the macro
	110	.Dv _DARWIN_FEATURE_64_BIT_INODE
	111	is defined, the
b0d623f7	112	.Fa statfs
6d2010ae	113	structure is defined as:
b0d623f7	114	.Bd -literal
2d21ac55 A	115	#define MFSTYPENAMELEN 16 /* length of fs type name including null */
2d21ac55 A	116	#define MAXPATHLEN 1024
b0d623f7	117	#define MNAMELEN MAXPATHLEN
9bccf70c	118
b0d623f7 A	119	struct statfs { /* when _DARWIN_FEATURE_64_BIT_INODE is defined */
	120	uint32_t f_bsize; /* fundamental file system block size */
	121	int32_t f_iosize; /* optimal transfer block size */
	122	uint64_t f_blocks; /* total data blocks in file system */
	123	uint64_t f_bfree; /* free blocks in fs */
	124	uint64_t f_bavail; /* free blocks avail to non-superuser */
	125	uint64_t f_files; /* total file nodes in file system */
	126	uint64_t f_ffree; /* free file nodes in fs */
	127	fsid_t f_fsid; /* file system id */
	128	uid_t f_owner; /* user that mounted the filesystem */
	129	uint32_t f_type; /* type of filesystem */
	130	uint32_t f_flags; /* copy of mount exported flags */
	131	uint32_t f_fssubtype; /* fs sub-type (flavor) */
	132	char f_fstypename[MFSTYPENAMELEN]; /* fs type name */
	133	char f_mntonname[MAXPATHLEN]; /* directory on which mounted */
	134	char f_mntfromname[MAXPATHLEN]; /* mounted filesystem */
	135	uint32_t f_reserved[8]; /* For future use */
2d21ac55	136	};
9bccf70c A	137	.Ed
9bccf70c A	138	.Pp
6d2010ae A	139	Note that the
	140	.Fa f_fstypename ,
	141	.Fa f_mntonname ,
	142	and
	143	.Fa f_mntfromname
	144	fields are also wider in this variant.
	145	.Pp
9bccf70c	146	Fields that are undefined for a particular file system are set to -1.
b0d623f7 A	147	The
	148	.Fn fstatfs
	149	routine returns the same information about an open file referenced by descriptor
9bccf70c	150	.Fa fd .
2d21ac55	151	.Sh FLAGS
316670eb	152	.Bl -tag -width MNT_UNKNOWNPERMISSIONS
2d21ac55 A	153	These are some of the flags that may be present in the f_flags field.
	154	.It Dv MNT_RDONLY
	155	A read-only filesystem
	156	.It Dv MNT_SYNCHRONOUS
	157	File system is written to synchronously
	158	.It Dv MNT_NOEXEC
	159	Can't exec from filesystem
	160	.It Dv MNT_NOSUID
	161	Setuid bits are not honored on this filesystem
	162	.It Dv MNT_NODEV
	163	Don't interpret special files
	164	.It Dv MNT_UNION
	165	Union with underlying filesysten
	166	.It Dv MNT_ASYNC
	167	File system written to asynchronously
	168	.It Dv MNT_EXPORTED
	169	File system is exported
b0d623f7	170	.It Dv MNT_LOCAL
2d21ac55 A	171	File system is stored locally
	172	.It Dv MNT_QUOTA
	173	Quotas are enabled on this file system
	174	.It Dv MNT_ROOTFS
	175	This file system is the root of the file system
	176	.It Dv MNT_DOVOLFS
	177	File system supports volfs
	178	.It Dv MNT_DONTBROWSE
	179	File system is not appropriate path to user data
	180	.It Dv MNT_UNKNOWNPERMISSIONS
	181	VFS will ignore ownership information on filesystem objects
	182	.It Dv MNT_AUTOMOUNTED
	183	File system was mounted by automounter
	184	.It Dv MNT_JOURNALED
	185	File system is journaled
	186	.It Dv MNT_DEFWRITE
	187	File system should defer writes
	188	.It Dv MNT_MULTILABEL
	189	MAC support for individual labels
316670eb A	190	.It Dv MNT_CPROTECT
316670eb A	191	File system supports per-file encrypted data protection
2d21ac55 A	192	.El
	193	.Sh CAVEATS
	194	In Mac OS X versions before 10.4, f_iosize is 4096. On these older
	195	systems, use MAXBSIZE instead.
9bccf70c A	196	.Sh RETURN VALUES
	197	Upon successful completion, a value of 0 is returned.
	198	Otherwise, -1 is returned and the global variable
	199	.Va errno
	200	is set to indicate the error.
	201	.Sh ERRORS
b0d623f7 A	202	The
	203	.Fn statfs
	204	routine fails if one or more of the following are true:
9bccf70c A	205	.Bl -tag -width Er
	206	.It Bq Er ENOTDIR
	207	A component of the path prefix of
	208	.Fa Path
	209	is not a directory.
	210	.It Bq Er ENAMETOOLONG
	211	The length of a component of
	212	.Fa path
	213	exceeds
	214	.Dv {NAME_MAX}
	215	characters, or the length of
	216	.Fa path
	217	exceeds
	218	.Dv {PATH_MAX}
	219	characters.
	220	.It Bq Er ENOENT
b0d623f7	221	The file or directory referred to by
9bccf70c A	222	.Fa path
	223	does not exist.
	224	.It Bq Er EACCES
	225	Search permission is denied for a component of the path prefix of
	226	.Fa path .
	227	.It Bq Er ELOOP
	228	Too many symbolic links were encountered in translating
	229	.Fa path .
	230	.It Bq Er EFAULT
	231	.Fa Buf
	232	or
	233	.Fa path
	234	points to an invalid address.
	235	.It Bq Er EIO
	236	An
	237	.Tn I/O
	238	error occurred while reading from or writing to the file system.
	239	.El
	240	.Pp
b0d623f7 A	241	The
	242	.Fn fstatfs
	243	routine fails if one or more of the following are true:
9bccf70c A	244	.Bl -tag -width Er
	245	.It Bq Er EBADF
	246	.Fa fd
	247	is not a valid open file descriptor.
	248	.It Bq Er EFAULT
	249	.Fa Buf
	250	points to an invalid address.
	251	.It Bq Er EIO
	252	An
	253	.Tn I/O
	254	error occurred while reading from or writing to the file system.
	255	.El
b0d623f7 A	256	.Sh TRANSITIONAL DESCRIPTION (NOW DEPRECATED)
	257	The
	258	.Fa statfs64
	259	and
	260	.Fa fstatfs64
	261	routines are equivalent to their corresponding non-64-suffixed routine,
	262	when 64-bit inodes are in effect.
	263	They were added before there was support for the symbol variants, and so are
	264	now deprecated.
	265	Instead of using these, set the
	266	.Dv _DARWIN_USE_64_BIT_INODE
	267	macro before including header files to force 64-bit inode support.
	268	.Pp
	269	The
	270	.Fa statfs64
	271	structure used by these deprecated routines is the same as the
	272	.Fa statfs
	273	structure when 64-bit inodes are in effect (see above).
9bccf70c A	274	.Sh HISTORY
	275	The
	276	.Fn statfs
b0d623f7 A	277	function first appeared in 4.4BSD. The
	278	.Fn statfs64
	279	and
	280	.Fn fstatfs64
	281	first appeared in Max OS X 10.5 (Leopard) and are now deprecated
	282	in favor of the corresponding symbol variants.