emulated/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: src/lib/libc/gen/statvfs.3,v 1.7 2003/06/08 10:01:51 charnier Exp $
  30 .\"
  31 .Dd July 13, 2002
  32 .Dt STATVFS 3
  33 .Os
  34 .Sh NAME
  35 .Nm fstatvfs ,
  36 .Nm statvfs
  37 .Nd retrieve file system information
  38 .Sh LIBRARY
  39 .Lb libc
  40 .Sh SYNOPSIS
  41 .In sys/statvfs.h
  42 .Ft int
  43 .Fo fstatvfs
  44 .Fa "int fildes"
  45 .Fa "struct statvfs *buf"
  46 .Fc
  47 .Ft int
  48 .Fo statvfs
  49 .Fa "const char *restrict path"
  50 .Fa "struct statvfs *restrict buf"
  51 .Fc
  52 .Sh DESCRIPTION
  53 The
  54 .Fn statvfs
  55 and
  56 .Fn fstatvfs
  57 functions attempt to fill the structure pointed to by
  58 .Fa buf
  59 with file system
  60 statistics, but portable applications must not depend on this.
  61 Applications must pass a pathname or file descriptor which refers to a
  62 file on the file system in which they are interested.
  63 .Pp
  64 The
  65 .Vt statvfs
  66 structure contains the following members:
  67 .Bl -tag -offset indent -width ".Va f_namemax"
  68 .It Va f_namemax
  69 The maximum length in bytes of a file name on this file system.
  70 Applications should use
  71 .Xr pathconf 2
  72 instead.
  73 .It Va f_fsid
  74 Not meaningful in this implementation.
  75 .It Va f_frsize
  76 The size in bytes of the minimum unit of allocation on this
  77 file system.
  78 (This corresponds to the
  79 .Va f_bsize
  80 member of
  81 .Vt "struct statfs" . )
  82 .It Va f_bsize
  83 The preferred length of I/O requests for files on this file system.
  84 (Corresponds to the
  85 .Va f_iosize
  86 member of
  87 .Vt "struct statfs" . )
  88 .It Va f_flag
  89 Flags describing mount options for this file system; see below.
  90 .El
  91 .Pp
  92 In addition, there are three members of type
  93 .Vt fsfilcnt_t ,
  94 which represent counts of file serial numbers
  95 .Em ( i.e. ,
  96 inodes); these are named
  97 .Va f_files , f_favail ,
  98 and
  99 .Va f_ffree ,
 100 and represent the number of file serial numbers which exist in total,
 101 are available to unprivileged processes, and are available to
 102 privileged processes, respectively.
 103 Likewise, the members
 104 .Va f_blocks , f_bavail ,
 105 and
 106 .Va f_bfree
 107 (all of type
 108 .Vt fsblkcnt_t )
 109 represent the respective allocation-block counts.
 110 .Pp
 111 There are two flags defined for the
 112 .Va f_flag
 113 member:
 114 .Bl -tag -offset indent -width ".Dv ST_NOSUID"
 115 .It Dv ST_RDONLY
 116 The file system is mounted read-only.
 117 .It Dv ST_NOSUID
 118 The semantics of the
 119 .Dv S_ISUID
 120 and
 121 .Dv S_ISGID
 122 file mode bits
 123 are not supported by, or are disabled on, this file system.
 124 .El
 125 .Sh IMPLEMENTATION NOTES
 126 The
 127 .Fn statvfs
 128 and
 129 .Fn fstatvfs
 130 functions are implemented as wrappers around the
 131 .Fn statfs
 132 and
 133 .Fn fstatfs
 134 functions, respectively.
 135 Not all the information provided by those functions is made available
 136 through this interface.
 137 .Sh RETURN VALUES
 138 .Rv -std statvfs fstatvfs
 139 .Sh ERRORS
 140 The
 141 .Fn statvfs
 142 function fails if one or more of the following are true:
 143 .Bl -tag -width Er
 144 .It Bq Er EACCES
 145 Search permission is denied for a component of the path prefix of
 146 .Fa path .
 147 .It Bq Er EFAULT
 148 .Fa Buf
 149 or
 150 .Fa path
 151 points to an invalid address.
 152 .It Bq Er EIO
 153 An
 154 .Tn I/O
 155 error occurred while reading from or writing to the file system.
 156 .It Bq Er ELOOP
 157 Too many symbolic links were encountered in translating
 158 .Fa path .
 159 .It Bq Er ENAMETOOLONG
 160 The length of a component of
 161 .Fa path
 162 exceeds
 163 .Dv {NAME_MAX}
 164 characters, or the length of
 165 .Fa path
 166 exceeds
 167 .Dv {PATH_MAX}
 168 characters.
 169 .It Bq Er ENOENT
 170 The file referred to by
 171 .Fa path
 172 does not exist.
 173 .It Bq Er ENOTDIR
 174 A component of the path prefix of
 175 .Fa Path
 176 is not a directory.
 177 .El
 178 .Pp
 179 The
 180 .Fn fstatvfs
 181 functions fails if one or more of the following are true:
 182 .Bl -tag -width Er
 183 .It Bq Er EBADF
 184 .Fa fildes
 185 is not a valid open file descriptor.
 186 .It Bq Er EFAULT
 187 .Fa Buf
 188 points to an invalid address.
 189 .It Bq Er EIO
 190 An
 191 .Tn I/O
 192 error occurred while reading from or writing to the file system.
 193 .El
 194 .Sh SEE ALSO
 195 .Xr statfs 2
 196 .Sh STANDARDS
 197 The
 198 .Fn statvfs
 199 and
 200 .Fn fstatvfs
 201 functions conform to
 202 .St -p1003.1-2001 .
 203 As standardized, portable applications cannot depend on these functions
 204 returning any valid information at all.
 205 This implementation attempts to provide as much useful information as
 206 is provided by the underlying file system, subject to the limitations
 207 of the specified data types.
 208 .Sh AUTHORS
 209 The
 210 .Fn statvfs
 211 and
 212 .Fn fstatvfs
 213 manual page was originally written by
 214 .An Garrett Wollman Aq wollman@FreeBSD.org .