--- name: "fstatfs" section: "2" platform: "macos" package: "xnu" version: "12377.121.6" release: "macOS 26.5" platforms: ["linux", "freebsd", "macos"] url: "https://new.carta.tech/statfs/2" --- # fstatfs(2) get file system statistics Part of [statfs(2)](/statfs/2.md). ## NAME **statfs,** **statfs64,** **fstatfs,** **fstatfs64** – get file system statistics ## SYNOPSIS **#include \** **#include \** *int*\ **statfs**(*const char \*path*, *struct statfs \*buf*); *int*\ **fstatfs**(*int fd*, *struct statfs \*buf*); ## TRANSITIONAL SYNOPSIS (NOW DEPRECATED) *int*\ **statfs64**(*const char \*path*, *struct statfs64 \*buf*); *int*\ **fstatfs64**(*int fd*, *struct statfs64 \*buf*); ## DESCRIPTION The **statfs**() routine returns information about a mounted file system. The *path* argument is the path name of any file or directory within the mounted file system. The *buf* argument is a pointer to a *statfs* structure. When the macro \_DARWIN\_FEATURE\_64\_BIT\_INODE is not defined (see [stat(2)](/stat/2.md) for more information on this macro), the *statfs* structure is defined as: ``` 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 */ 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 */ }; ``` However, when the macro \_DARWIN\_FEATURE\_64\_BIT\_INODE is defined, the *statfs* structure is defined as: ``` #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 */ }; ``` Note that the *f\_fstypename*, *f\_mntonname*, and *f\_mntfromname* fields are also wider in this variant. Fields that are undefined for a particular file system are set to -1. The **fstatfs**() routine returns the same information about an open file referenced by descriptor *fd*. ## FLAGS - MNT\_RDONLY A read-only filesystem - MNT\_SYNCHRONOUS File system is written to synchronously - MNT\_NOEXEC Can't exec from filesystem - MNT\_NOSUID Setuid bits are not honored on this filesystem - MNT\_NODEV Don't interpret special files - MNT\_UNION Union with underlying filesysten - MNT\_ASYNC File system written to asynchronously - MNT\_EXPORTED File system is exported - MNT\_LOCAL File system is stored locally - MNT\_QUOTA Quotas are enabled on this file system - MNT\_ROOTFS This file system is the root of the file system - MNT\_DOVOLFS File system supports volfs - MNT\_DONTBROWSE File system is not appropriate path to user data - MNT\_UNKNOWNPERMISSIONS VFS will ignore ownership information on filesystem objects - MNT\_AUTOMOUNTED File system was mounted by automounter - MNT\_JOURNALED File system is journaled - MNT\_DEFWRITE File system should defer writes - MNT\_MULTILABEL MAC support for individual labels - MNT\_CPROTECT File system supports per-file encrypted data protection These are some of the flags that may be present in the f\_flags field. ## CAVEATS In Mac OS X versions before 10.4, f\_iosize is 4096. On these older systems, use MAXBSIZE instead. ## RETURN VALUES Upon successful completion, a value of 0 is returned. Otherwise, -1 is returned and the global variable *errno* is set to indicate the error. ## ERRORS The **statfs**() routine fails if one or more of the following are true: - \[ENOTDIR\] A component of the path prefix of *Path* is not a directory. - \[ENAMETOOLONG\] The length of a component of *path* exceeds {NAME\_MAX} characters, or the length of *path* exceeds {PATH\_MAX} characters. - \[ENOENT\] The file or directory referred to by *path* does not exist. - \[EACCES\] Search permission is denied for a component of the path prefix of *path*. - \[ELOOP\] Too many symbolic links were encountered in translating *path*. - \[EFAULT\] *Buf* or *path* points to an invalid address. - \[EIO\] An I/O error occurred while reading from or writing to the file system. The **fstatfs**() routine fails if one or more of the following are true: - \[EBADF\] *fd* is not a valid open file descriptor. - \[EFAULT\] *Buf* points to an invalid address. - \[EIO\] An I/O error occurred while reading from or writing to the file system. ## TRANSITIONAL DESCRIPTION (NOW DEPRECATED) The *statfs64* and *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 \_DARWIN\_USE\_64\_BIT\_INODE macro before including header files to force 64-bit inode support. The *statfs64* structure used by these deprecated routines is the same as the *statfs* structure when 64-bit inodes are in effect (see above). ## SEE ALSO [stat(2)](/stat/2.md), [getfsstat(2)](/getfsstat/2.md) ## HISTORY The **statfs**() function first appeared in 4.4BSD. The **statfs64**() and **fstatfs64**() first appeared in Max OS X 10.5 (Leopard) and are now deprecated in favor of the corresponding symbol variants.