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 July 20, 2025 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_NAMEDATTR 129The file system supports named attributes as described in 130.Xr named_attribute 7 . 131.It Dv MNT_NFS4ACLS 132ACLs in NFSv4 variant are supported. 133.It Dv MNT_NOATIME 134Updating of file access times is disabled. 135.It Dv MNT_NOCLUSTERR 136Read clustering is disabled. 137.It Dv MNT_NOCLUSTERW 138Write clustering is disabled. 139.It Dv MNT_NOEXEC 140Files may not be executed from the file system. 141.It Dv MNT_NOSUID 142Setuid and setgid bits on files are not honored when they are executed. 143.It Dv MNT_NOSYMFOLLOW 144Symbolic links are not followed. 145.It Dv MNT_SOFTDEP 146Soft updates being done (see 147.Xr ffs 4 ) . 148.It Dv MNT_SUIDDIR 149Special handling of SUID bit on directories. 150.It Dv MNT_SUJ 151Soft-updates with journaling being done. 152.It Dv MNT_SYNCHRONOUS 153All I/O to the file system is done synchronously. 154.It Dv MNT_QUOTA 155The file system has quotas enabled on it. 156.It Dv MNT_RDONLY 157The file system is mounted read-only; 158Even the super-user may not write on it. 159.It Dv MNT_ROOTFS 160Identifies the root file system. 161.It Dv MNT_UNION 162Union with underlying file system. 163.It Dv MNT_UNTRUSTED 164The file system was mounted with the 165.Cm untrusted 166option, which indicates media of unknown provenance or integrity. 167Currently honored by 168.Xr ffs 4 . 169.It Dv MNT_USER 170The file system has been mounted by a user. 171.It Dv MNT_VERIFIED 172The file system is marked as verified, no fingerprint check on 173.Xr execve 2 174is needed, see 175.Xr mac_veriexec 4 . 176.El 177.Pp 178Fields that are undefined for a particular file system are set to -1. 179The 180.Fn fstatfs 181system call 182returns the same information about an open file referenced by descriptor 183.Fa fd . 184.Sh RETURN VALUES 185.Rv -std 186.Sh ERRORS 187The 188.Fn statfs 189system call 190fails if one or more of the following are true: 191.Bl -tag -width Er 192.It Bq Er ENOTDIR 193A component of the path prefix of 194.Fa path 195is not a directory. 196.It Bq Er ENAMETOOLONG 197The length of a component of 198.Fa path 199exceeds 255 characters, 200or the length of 201.Fa path 202exceeds 1023 characters. 203.It Bq Er ENOENT 204The file referred to by 205.Fa path 206does not exist. 207.It Bq Er EACCES 208Search permission is denied for a component of the path prefix of 209.Fa path . 210.It Bq Er ELOOP 211Too many symbolic links were encountered in translating 212.Fa path . 213.It Bq Er EFAULT 214The 215.Fa buf 216or 217.Fa path 218argument 219points to an invalid address. 220.It Bq Er EIO 221An 222.Tn I/O 223error occurred while reading from or writing to the file system. 224.It Bq Er EINTEGRITY 225Corrupted data was detected while reading from the file system. 226.El 227.Pp 228The 229.Fn fstatfs 230system call 231fails if one or more of the following are true: 232.Bl -tag -width Er 233.It Bq Er EBADF 234The 235.Fa fd 236argument 237is not a valid open file descriptor. 238.It Bq Er EFAULT 239The 240.Fa buf 241argument 242points to an invalid address. 243.It Bq Er EIO 244An 245.Tn I/O 246error occurred while reading from or writing to the file system. 247.It Bq Er EINTEGRITY 248Corrupted data was detected while reading from the file system. 249.El 250.Sh NOTES 251The fields in the 252.Vt statfs 253structure have been defined to provide the parameters relevant for 254traditional UNIX file systems. 255For some other file systems, values that have similar, but not 256identical, semantics to those described above may be returned. 257An example is msdosfs, which in case of FAT12 or FAT16 file systems 258reports the number of available and of free root directory entries 259instead of inodes 260.Po 261where 1 to 21 such directory entries are required to store 262each file or directory name or disk label 263.Pc . 264.Sh SEE ALSO 265.Xr fhstatfs 2 , 266.Xr getfsstat 2 , 267.Xr named_attribute 7 268.Sh HISTORY 269The 270.Fn statfs 271system call first appeared in 272.Bx 4.4 . 273