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_RDONLY 98The file system is mounted read-only; 99Even the super-user may not write on it. 100.It Dv MNT_NOEXEC 101Files may not be executed from the file system. 102.It Dv MNT_NOSUID 103Setuid and setgid bits on files are not honored when they are executed. 104.It Dv MNT_SYNCHRONOUS 105All I/O to the file system is done synchronously. 106.It Dv MNT_ASYNC 107No file system I/O is done synchronously. 108.It Dv MNT_SOFTDEP 109Soft updates being done (see 110.Xr ffs 7 ) . 111.It Dv MNT_GJOURNAL 112Journaling with gjournal is enabled (see 113.Xr gjournal 8 ) . 114.It Dv MNT_SUIDDIR 115Special handling of SUID bit on directories. 116.It Dv MNT_UNION 117Union with underlying file system. 118.It Dv MNT_NOSYMFOLLOW 119Symbolic links are not followed. 120.It Dv MNT_NOCLUSTERR 121Read clustering is disabled. 122.It Dv MNT_NOCLUSTERW 123Write clustering is disabled. 124.\".It Dv MNT_JAILDEVFS 125.\"XXX 126.It Dv MNT_MULTILABEL 127Mandatory Access Control (MAC) support for individual objects 128(see 129.Xr mac 4 ) . 130.It Dv MNT_ACLS 131Access Control List (ACL) support enabled. 132.It Dv MNT_LOCAL 133The file system resides locally. 134.It Dv MNT_QUOTA 135The file system has quotas enabled on it. 136.It Dv MNT_ROOTFS 137Identifies the root file system. 138.It Dv MNT_EXRDONLY 139The file system is exported read-only. 140.It Dv MNT_NOATIME 141Updating of file access times is disabled. 142.It Dv MNT_USER 143The file system has been mounted by a user. 144.\".It Dv MNT_IGNORE 145.\"XXX 146.It Dv MNT_EXPORTED 147The file system is exported for both reading and writing. 148.It Dv MNT_DEFEXPORTED 149The file system is exported for both reading and writing to any Internet host. 150.It Dv MNT_EXPORTANON 151The file system maps all remote accesses to the anonymous user. 152.It Dv MNT_EXKERB 153The file system is exported with Kerberos uid mapping. 154.It Dv MNT_EXPUBLIC 155The file system is exported publicly (WebNFS). 156.El 157.Pp 158Fields that are undefined for a particular file system are set to -1. 159The 160.Fn fstatfs 161system call 162returns the same information about an open file referenced by descriptor 163.Fa fd . 164.Sh RETURN VALUES 165.Rv -std 166.Sh ERRORS 167The 168.Fn statfs 169system call 170fails if one or more of the following are true: 171.Bl -tag -width Er 172.It Bq Er ENOTDIR 173A component of the path prefix of 174.Fa path 175is not a directory. 176.It Bq Er ENAMETOOLONG 177The length of a component of 178.Fa path 179exceeds 255 characters, 180or the length of 181.Fa path 182exceeds 1023 characters. 183.It Bq Er ENOENT 184The file referred to by 185.Fa path 186does not exist. 187.It Bq Er EACCES 188Search permission is denied for a component of the path prefix of 189.Fa path . 190.It Bq Er ELOOP 191Too many symbolic links were encountered in translating 192.Fa path . 193.It Bq Er EFAULT 194The 195.Fa buf 196or 197.Fa path 198argument 199points to an invalid address. 200.It Bq Er EIO 201An 202.Tn I/O 203error occurred while reading from or writing to the file system. 204.It Bq Er EINTEGRITY 205Corrupted data was detected while reading from the file system. 206.El 207.Pp 208The 209.Fn fstatfs 210system call 211fails if one or more of the following are true: 212.Bl -tag -width Er 213.It Bq Er EBADF 214The 215.Fa fd 216argument 217is not a valid open file descriptor. 218.It Bq Er EFAULT 219The 220.Fa buf 221argument 222points to an invalid address. 223.It Bq Er EIO 224An 225.Tn I/O 226error occurred while reading from or writing to the file system. 227.It Bq Er EINTEGRITY 228Corrupted data was detected while reading from the file system. 229.El 230.Sh NOTES 231The fields in the 232.Vt statfs 233structure have been defined to provide the parameters relevant for 234traditional 235.Tm UNIX 236file systems. 237For some other file systems, values that have similar, but not 238identical, semantics to those described above may be returned. 239An example is msdosfs, which in case of FAT12 or FAT16 file systems 240reports the number of available and of free root directory entries 241instead of inodes 242.Po 243where 1 to 21 such directory entries are required to store 244each file or directory name or disk label 245.Pc . 246.Sh SEE ALSO 247.Xr fhstatfs 2 , 248.Xr getfsstat 2 249.Sh HISTORY 250The 251.Fn statfs 252system call first appeared in 253.Bx 4.4 . 254