man3/statvfs.3

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