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. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.Dd March 29, 2023 29.Dt STATFS 2 30.Os 31.Sh NAME 32.Nm statfs 33.Nd get file system statistics 34.Sh LIBRARY 35.Lb libc 36.Sh SYNOPSIS 37.In sys/param.h 38.In sys/mount.h 39.Ft int 40.Fn statfs "const char *path" "struct statfs *buf" 41.Ft int 42.Fn fstatfs "int fd" "struct statfs *buf" 43.Sh DESCRIPTION 44The 45.Fn statfs 46system call 47returns information about a mounted file system. 48The 49.Fa path 50argument 51is the path name of any file within the mounted file system. 52The 53.Fa buf 54argument 55is a pointer to a 56.Vt statfs 57structure defined as follows: 58.Bd -literal 59typedef struct fsid { int32_t val[2]; } fsid_t; /* file system id type */ 60 61/* 62 * filesystem statistics 63 */ 64 65#define MFSNAMELEN 16 /* length of type name including null */ 66#define MNAMELEN 1024 /* size of on/from name bufs */ 67#define STATFS_VERSION 0x20140518 /* current version number */ 68 69struct statfs { 70uint32_t f_version; /* structure version number */ 71uint32_t f_type; /* type of filesystem */ 72uint64_t f_flags; /* copy of mount exported flags */ 73uint64_t f_bsize; /* filesystem fragment size */ 74uint64_t f_iosize; /* optimal transfer block size */ 75uint64_t f_blocks; /* total data blocks in filesystem */ 76uint64_t f_bfree; /* free blocks in filesystem */ 77int64_t f_bavail; /* free blocks avail to non-superuser */ 78uint64_t f_files; /* total file nodes in filesystem */ 79int64_t f_ffree; /* free nodes avail to non-superuser */ 80uint64_t f_syncwrites; /* count of sync writes since mount */ 81uint64_t f_asyncwrites; /* count of async writes since mount */ 82uint64_t f_syncreads; /* count of sync reads since mount */ 83uint64_t f_asyncreads; /* count of async reads since mount */ 84uint64_t f_spare[10]; /* unused spare */ 85uint32_t f_namemax; /* maximum filename length */ 86uid_t f_owner; /* user that mounted the filesystem */ 87fsid_t f_fsid; /* filesystem id */ 88char f_charspare[80]; /* spare string space */ 89char f_fstypename[MFSNAMELEN]; /* filesystem type name */ 90char f_mntfromname[MNAMELEN]; /* mounted filesystem */ 91char f_mntonname[MNAMELEN]; /* directory on which mounted */ 92}; 93.Ed 94.Pp 95The flags that may be returned include: 96.Bl -tag -width MNT_SYNCHRONOUS 97.It Dv MNT_ACLS 98Access Control List (ACL) support enabled. 99.It Dv MNT_ASYNC 100No file system I/O is done synchronously. 101.It Dv MNT_AUTOMOUNTED 102The filesystem was auto-mounted, see 103.Xr autofs 4 . 104.It Dv MNT_DEFEXPORTED 105The file system is exported for both reading and writing to any Internet host. 106.It Dv MNT_GJOURNAL 107Journaling with gjournal is enabled (see 108.Xr gjournal 8 ) . 109.It Dv MNT_EXKERB 110The file system is exported with Kerberos uid mapping. 111.It Dv MNT_EXPORTANON 112The file system maps all remote accesses to the anonymous user. 113.It Dv MNT_EXPORTED 114The file system is exported for both reading and writing. 115.It Dv MNT_EXPUBLIC 116The file system is exported publicly (WebNFS). 117.It Dv MNT_EXRDONLY 118The file system is exported read-only. 119.It Dv MNT_IGNORE 120The file system should not be listed, e.g. by 121.Xr df 1 . 122.It Dv MNT_LOCAL 123The file system resides locally. 124.It Dv MNT_MULTILABEL 125Mandatory Access Control (MAC) support for individual objects 126(see 127.Xr mac 4 ) . 128.It Dv MNT_NFS4ACLS 129ACLs in NFSv4 variant are supported. 130.It Dv MNT_NOATIME 131Updating of file access times is disabled. 132.It Dv MNT_NOCLUSTERR 133Read clustering is disabled. 134.It Dv MNT_NOCLUSTERW 135Write clustering is disabled. 136.It Dv MNT_NOEXEC 137Files may not be executed from the file system. 138.It Dv MNT_NOSUID 139Setuid and setgid bits on files are not honored when they are executed. 140.It Dv MNT_NOSYMFOLLOW 141Symbolic links are not followed. 142.It Dv MNT_SOFTDEP 143Soft updates being done (see 144.Xr ffs 4 ) . 145.It Dv MNT_SUIDDIR 146Special handling of SUID bit on directories. 147.It Dv MNT_SUJ 148Soft-updates with journaling being done. 149.It Dv MNT_SYNCHRONOUS 150All I/O to the file system is done synchronously. 151.It Dv MNT_QUOTA 152The file system has quotas enabled on it. 153.It Dv MNT_RDONLY 154The file system is mounted read-only; 155Even the super-user may not write on it. 156.It Dv MNT_ROOTFS 157Identifies the root file system. 158.It Dv MNT_UNION 159Union with underlying file system. 160.It Dv MNT_UNTRUSTED 161The file system was mounted with the 162.Cm untrusted 163option, which indicates media of unknown provenance or integrity. 164Currently honored by 165.Xr ffs 4 . 166.It Dv MNT_USER 167The file system has been mounted by a user. 168.It Dv MNT_VERIFIED 169The file system is marked as verified, no fingerprint check on 170.Xr execve 2 171is needed, see 172.Xr mac_veriexec 4 . 173.El 174.Pp 175Fields that are undefined for a particular file system are set to -1. 176The 177.Fn fstatfs 178system call 179returns the same information about an open file referenced by descriptor 180.Fa fd . 181.Sh RETURN VALUES 182.Rv -std 183.Sh ERRORS 184The 185.Fn statfs 186system call 187fails if one or more of the following are true: 188.Bl -tag -width Er 189.It Bq Er ENOTDIR 190A component of the path prefix of 191.Fa path 192is not a directory. 193.It Bq Er ENAMETOOLONG 194The length of a component of 195.Fa path 196exceeds 255 characters, 197or the length of 198.Fa path 199exceeds 1023 characters. 200.It Bq Er ENOENT 201The file referred to by 202.Fa path 203does not exist. 204.It Bq Er EACCES 205Search permission is denied for a component of the path prefix of 206.Fa path . 207.It Bq Er ELOOP 208Too many symbolic links were encountered in translating 209.Fa path . 210.It Bq Er EFAULT 211The 212.Fa buf 213or 214.Fa path 215argument 216points to an invalid address. 217.It Bq Er EIO 218An 219.Tn I/O 220error occurred while reading from or writing to the file system. 221.It Bq Er EINTEGRITY 222Corrupted data was detected while reading from the file system. 223.El 224.Pp 225The 226.Fn fstatfs 227system call 228fails if one or more of the following are true: 229.Bl -tag -width Er 230.It Bq Er EBADF 231The 232.Fa fd 233argument 234is not a valid open file descriptor. 235.It Bq Er EFAULT 236The 237.Fa buf 238argument 239points to an invalid address. 240.It Bq Er EIO 241An 242.Tn I/O 243error occurred while reading from or writing to the file system. 244.It Bq Er EINTEGRITY 245Corrupted data was detected while reading from the file system. 246.El 247.Sh NOTES 248The fields in the 249.Vt statfs 250structure have been defined to provide the parameters relevant for 251traditional UNIX file systems. 252For some other file systems, values that have similar, but not 253identical, semantics to those described above may be returned. 254An example is msdosfs, which in case of FAT12 or FAT16 file systems 255reports the number of available and of free root directory entries 256instead of inodes 257.Po 258where 1 to 21 such directory entries are required to store 259each file or directory name or disk label 260.Pc . 261.Sh SEE ALSO 262.Xr fhstatfs 2 , 263.Xr getfsstat 2 264.Sh HISTORY 265The 266.Fn statfs 267system call first appeared in 268.Bx 4.4 . 269