lib/libc/gen/statvfs.3

   1 .\"
   2 .\" Copyright 2002 Massachusetts Institute of Technology
   3 .\"
   4 .\" Permission to use, copy, modify, and distribute this software and
   5 .\" its documentation for any purpose and without fee is hereby
   6 .\" granted, provided that both the above copyright notice and this
   7 .\" permission notice appear in all copies, that both the above
   8 .\" copyright notice and this permission notice appear in all
   9 .\" supporting documentation, and that the name of M.I.T. not be used
  10 .\" in advertising or publicity pertaining to distribution of the
  11 .\" software without specific, written prior permission.  M.I.T. makes
  12 .\" no representations about the suitability of this software for any
  13 .\" purpose.  It is provided "as is" without express or implied
  14 .\" warranty.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY M.I.T. ``AS IS''.  M.I.T. DISCLAIMS
  17 .\" ALL EXPRESS OR IMPLIED WARRANTIES WITH REGARD TO THIS SOFTWARE,
  18 .\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
  19 .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT
  20 .\" SHALL M.I.T. BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  21 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  22 .\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
  23 .\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  24 .\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  25 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  26 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  27 .\" SUCH DAMAGE.
  28 .\"
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd July 13, 2002
  32 .Dt STATVFS 3
  33 .Os
  34 .Sh NAME
  35 .Nm statvfs ,
  36 .Nm fstatvfs
  37 .Nd retrieve file system information
  38 .Sh LIBRARY
  39 .Lb libc
  40 .Sh SYNOPSIS
  41 .In sys/statvfs.h
  42 .Ft int
  43 .Fn statvfs "const char * restrict path" "struct statvfs * restrict buf"
  44 .Ft int
  45 .Fn fstatvfs "int fd" "struct statvfs *buf"
  46 .Sh DESCRIPTION
  47 The
  48 .Fn statvfs
  49 and
  50 .Fn fstatvfs
  51 functions fill the structure pointed to by
  52 .Fa buf
  53 with garbage.
  54 This garbage will occasionally bear resemblance to file system
  55 statistics, but portable applications must not depend on this.
  56 Applications must pass a pathname or file descriptor which refers to a
  57 file on the file system in which they are interested.
  58 .Pp
  59 The
  60 .Vt statvfs
  61 structure contains the following members:
  62 .Bl -tag -offset indent -width ".Va f_namemax"
  63 .It Va f_namemax
  64 The maximum length in bytes of a file name on this file system.
  65 Applications should use
  66 .Xr pathconf 2
  67 instead.
  68 .It Va f_fsid
  69 Not meaningful in this implementation.
  70 .It Va f_frsize
  71 The size in bytes of the minimum unit of allocation on this
  72 file system.
  73 (This corresponds to the
  74 .Va f_bsize
  75 member of
  76 .Vt "struct statfs" . )
  77 .It Va f_bsize
  78 The preferred length of I/O requests for files on this file system.
  79 (Corresponds to the
  80 .Va f_iosize
  81 member of
  82 .Vt "struct statfs" . )
  83 .It Va f_flag
  84 Flags describing mount options for this file system; see below.
  85 .El
  86 .Pp
  87 In addition, there are three members of type
  88 .Vt fsfilcnt_t ,
  89 which represent counts of file serial numbers
  90 .Em ( i.e. ,
  91 inodes); these are named
  92 .Va f_files , f_favail ,
  93 and
  94 .Va f_ffree ,
  95 and represent the number of file serial numbers which exist in total,
  96 are available to unprivileged processes, and are available to
  97 privileged processes, respectively.
  98 Likewise, the members
  99 .Va f_blocks , f_bavail ,
 100 and
 101 .Va f_bfree
 102 (all of type
 103 .Vt fsblkcnt_t )
 104 represent the respective allocation-block counts.
 105 .Pp
 106 There are two flags defined for the
 107 .Va f_flag
 108 member:
 109 .Bl -tag -offset indent -width ".Dv ST_NOSUID"
 110 .It Dv ST_RDONLY
 111 The file system is mounted read-only.
 112 .It Dv ST_NOSUID
 113 The semantics of the
 114 .Dv S_ISUID
 115 and
 116 .Dv S_ISGID
 117 file mode bits
 118 are not supported by, or are disabled on, this file system.
 119 .El
 120 .Sh IMPLEMENTATION NOTES
 121 The
 122 .Fn statvfs
 123 and
 124 .Fn fstatvfs
 125 functions are implemented as wrappers around the
 126 .Fn statfs
 127 and
 128 .Fn fstatfs
 129 functions, respectively.
 130 Not all the information provided by those functions is made available
 131 through this interface.
 132 .Sh RETURN VALUES
 133 .Rv -std statvfs fstatvfs
 134 .Sh ERRORS
 135 The
 136 .Fn statvfs
 137 and
 138 .Fn fstatvfs
 139 functions may fail for any of the reasons documented for
 140 .Xr statfs 2
 141 or
 142 .Xr fstatfs 2
 143 and
 144 .Xr pathconf 2
 145 or
 146 .Xr fpathconf 2 ,
 147 respectively.
 148 In addition,
 149 .Fn statvfs
 150 and
 151 .Fn fstatvfs
 152 functions may also fail for the following reason:
 153 .Bl -tag -width Er
 154 .It Bq Er EOVERFLOW
 155 One or more of the file system statistics has a value which cannot be
 156 represented by the data types used in
 157 .Vt "struct statvfs" .
 158 .El
 159 .Sh SEE ALSO
 160 .Xr pathconf 2 ,
 161 .Xr statfs 2
 162 .Sh STANDARDS
 163 The
 164 .Fn statvfs
 165 and
 166 .Fn fstatvfs
 167 functions conform to
 168 .St -p1003.1-2001 .
 169 As standardized, portable applications cannot depend on these functions
 170 returning any valid information at all.
 171 This implementation attempts to provide as much useful information as
 172 is provided by the underlying file system, subject to the limitations
 173 of the specified data types.
 174 .Sh HISTORY
 175 The
 176 .Fn statvfs
 177 and
 178 .Fn fstatvfs
 179 functions first appeared in
 180 .Fx 5.0 .
 181 .Sh AUTHORS
 182 The
 183 .Fn statvfs
 184 and
 185 .Fn fstatvfs
 186 functions and this manual page were written by
 187 .An Garrett Wollman Aq wollman@FreeBSD.org .