man3/statvfs.3

   1 '\" t
   2 .\" Copyright (C) 2003 Andries Brouwer (aeb@cwi.nl)
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .\" The pathconf note is from Walter Harms
   7 .\" This is not a system call on Linux
   8 .\"
   9 .\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com>
  10 .\"
  11 .TH statvfs 3 (date) "Linux man-pages (unreleased)"
  12 .SH NAME
  13 statvfs, fstatvfs \- get filesystem statistics
  14 .SH LIBRARY
  15 Standard C library
  16 .RI ( libc ", " \-lc )
  17 .SH SYNOPSIS
  18 .nf
  19 .B #include <sys/statvfs.h>
  20 .P
  21 .BI "int statvfs(const char *restrict " path \
  22 ", struct statvfs *restrict " buf );
  23 .BI "int fstatvfs(int " fd ", struct statvfs *" buf );
  24 .fi
  25 .SH DESCRIPTION
  26 The function
  27 .BR statvfs ()
  28 returns information about a mounted filesystem.
  29 .I path
  30 is the pathname of any file within the mounted filesystem.
  31 .I buf
  32 is a pointer to a
  33 .I statvfs
  34 structure defined approximately as follows:
  35 .P
  36 .in +4n
  37 .EX
  38 struct statvfs {
  39     unsigned long  f_bsize;    /* Filesystem block size */
  40     unsigned long  f_frsize;   /* Fragment size */
  41     fsblkcnt_t     f_blocks;   /* Size of fs in f_frsize units */
  42     fsblkcnt_t     f_bfree;    /* Number of free blocks */
  43     fsblkcnt_t     f_bavail;   /* Number of free blocks for
  44                                   unprivileged users */
  45     fsfilcnt_t     f_files;    /* Number of inodes */
  46     fsfilcnt_t     f_ffree;    /* Number of free inodes */
  47     fsfilcnt_t     f_favail;   /* Number of free inodes for
  48                                   unprivileged users */
  49     unsigned long  f_fsid;     /* Filesystem ID */
  50     unsigned long  f_flag;     /* Mount flags */
  51     unsigned long  f_namemax;  /* Maximum filename length */
  52 };
  53 .EE
  54 .in
  55 .P
  56 Here the types
  57 .I fsblkcnt_t
  58 and
  59 .I fsfilcnt_t
  60 are defined in
  61 .IR <sys/types.h> .
  62 Both used to be
  63 .IR "unsigned long" .
  64 .P
  65 The field
  66 .I f_flag
  67 is a bit mask indicating various options that were employed
  68 when mounting this filesystem.
  69 It contains zero or more of the following flags:
  70 .\" XXX Keep this list in sync with statfs(2)
  71 .TP
  72 .B ST_MANDLOCK
  73 Mandatory locking is permitted on the filesystem (see
  74 .BR fcntl (2)).
  75 .TP
  76 .B ST_NOATIME
  77 Do not update access times; see
  78 .BR mount (2).
  79 .TP
  80 .B ST_NODEV
  81 Disallow access to device special files on this filesystem.
  82 .TP
  83 .B ST_NODIRATIME
  84 Do not update directory access times; see
  85 .BR mount (2).
  86 .TP
  87 .B ST_NOEXEC
  88 Execution of programs is disallowed on this filesystem.
  89 .TP
  90 .B ST_NOSUID
  91 The set-user-ID and set-group-ID bits are ignored by
  92 .BR exec (3)
  93 for executable files on this filesystem
  94 .TP
  95 .B ST_RDONLY
  96 This filesystem is mounted read-only.
  97 .TP
  98 .B ST_RELATIME
  99 Update atime relative to mtime/ctime; see
 100 .BR mount (2).
 101 .TP
 102 .B ST_SYNCHRONOUS
 103 Writes are synched to the filesystem immediately (see the description of
 104 .B O_SYNC
 105 in
 106 .BR open (2)).
 107 .P
 108 It is unspecified whether all members of the returned struct
 109 have meaningful values on all filesystems.
 110 .P
 111 .BR fstatvfs ()
 112 returns the same information about an open file referenced by descriptor
 113 .IR fd .
 114 .SH RETURN VALUE
 115 On success, zero is returned.
 116 On error, \-1 is returned, and
 117 .I errno
 118 is set to indicate the error.
 119 .SH ERRORS
 120 .TP
 121 .B EACCES
 122 .RB ( statvfs ())
 123 Search permission is denied for a component of the path prefix of
 124 .IR path .
 125 (See also
 126 .BR path_resolution (7).)
 127 .TP
 128 .B EBADF
 129 .RB ( fstatvfs ())
 130 .I fd
 131 is not a valid open file descriptor.
 132 .TP
 133 .B EFAULT
 134 .I Buf
 135 or
 136 .I path
 137 points to an invalid address.
 138 .TP
 139 .B EINTR
 140 This call was interrupted by a signal; see
 141 .BR signal (7).
 142 .TP
 143 .B EIO
 144 An I/O error occurred while reading from the filesystem.
 145 .TP
 146 .B ELOOP
 147 .RB ( statvfs ())
 148 Too many symbolic links were encountered in translating
 149 .IR path .
 150 .TP
 151 .B ENAMETOOLONG
 152 .RB ( statvfs ())
 153 .I path
 154 is too long.
 155 .TP
 156 .B ENOENT
 157 .RB ( statvfs ())
 158 The file referred to by
 159 .I path
 160 does not exist.
 161 .TP
 162 .B ENOMEM
 163 Insufficient kernel memory was available.
 164 .TP
 165 .B ENOSYS
 166 The filesystem does not support this call.
 167 .TP
 168 .B ENOTDIR
 169 .RB ( statvfs ())
 170 A component of the path prefix of
 171 .I path
 172 is not a directory.
 173 .TP
 174 .B EOVERFLOW
 175 Some values were too large to be represented in the returned struct.
 176 .SH ATTRIBUTES
 177 For an explanation of the terms used in this section, see
 178 .BR attributes (7).
 179 .TS
 180 allbox;
 181 lbx lb lb
 182 l l l.
 183 Interface       Attribute       Value
 184 T{
 185 .na
 186 .nh
 187 .BR statvfs (),
 188 .BR fstatvfs ()
 189 T}      Thread safety   MT-Safe
 190 .TE
 191 .SH VERSIONS
 192 Only the
 193 .B ST_NOSUID
 194 and
 195 .B ST_RDONLY
 196 flags of the
 197 .I f_flag
 198 field are specified in POSIX.1.
 199 To obtain definitions of the remaining flags, one must define
 200 .BR _GNU_SOURCE .
 201 .SH NOTES
 202 The Linux kernel has system calls
 203 .BR statfs (2)
 204 and
 205 .BR fstatfs (2)
 206 to support this library call.
 207 .P
 208 The glibc implementations of
 209 .P
 210 .in +4n
 211 .EX
 212 pathconf(path, _PC_REC_XFER_ALIGN);
 213 pathconf(path, _PC_ALLOC_SIZE_MIN);
 214 pathconf(path, _PC_REC_MIN_XFER_SIZE);
 215 .EE
 216 .in
 217 .P
 218 respectively use the
 219 .IR f_frsize ,
 220 .IR f_frsize ,
 221 and
 222 .I f_bsize
 223 fields returned by a call to
 224 .BR statvfs ()
 225 with the argument
 226 .IR path .
 227 .P
 228 Under Linux,
 229 .I f_favail
 230 is always the same as
 231 .IR f_ffree ,
 232 and there's no way for a filesystem to report otherwise.
 233 This is not an issue,
 234 since no filesystems with an inode root reservation exist.
 235 .SH STANDARDS
 236 POSIX.1-2008.
 237 .SH HISTORY
 238 POSIX.1-2001.
 239 .P
 240 Before glibc 2.13,
 241 .\" glibc commit 3cdaa6adb113a088fdfb87aa6d7747557eccc58d
 242 .BR statvfs ()
 243 populated the bits of the
 244 .I f_flag
 245 field by scanning the mount options shown in
 246 .IR /proc/mounts .
 247 However, starting with Linux 2.6.36, the underlying
 248 .BR statfs (2)
 249 system call provides the necessary information via the
 250 .I f_flags
 251 field, and since glibc 2.13, the
 252 .BR statvfs ()
 253 function will use information from that field rather than scanning
 254 .IR /proc/mounts .
 255 .SH SEE ALSO
 256 .BR statfs (2)