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