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