lib/libc/sys/statvfs.2

   1 .\"     $NetBSD: statvfs.2,v 1.5 2010/05/31 12:16:20 njoly Exp $
   2 .\"
   3 .\" Copyright (c) 1989, 1991, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. Neither the name of the University nor the names of its contributors
  15 .\"    may be used to endorse or promote products derived from this software
  16 .\"    without specific prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .\"     @(#)statfs.2    8.5 (Berkeley) 5/24/95
  31 .\"
  32 .Dd April 14, 2004
  33 .Dt STATVFS 2
  34 .Os
  35 .Sh NAME
  36 .Nm statvfs ,
  37 .Nm statvfs1 ,
  38 .Nm fstatvfs ,
  39 .Nm fstatvfs1
  40 .Nd get file system statistics
  41 .Sh LIBRARY
  42 .Lb libc
  43 .Sh SYNOPSIS
  44 .In sys/statvfs.h
  45 .Ft int
  46 .Fn statvfs "const char *path" "struct statvfs *buf"
  47 .Ft int
  48 .Fn statvfs1 "const char *path" "struct statvfs *buf" "int flags"
  49 .Ft int
  50 .Fn fstatvfs "int fd" "struct statvfs *buf"
  51 .Ft int
  52 .Fn fstatvfs1 "int fd" "struct statvfs *buf" "int flags"
  53 .Sh DESCRIPTION
  54 .Fn statvfs
  55 and
  56 .Fn statvfs1
  57 return information about a mounted file system.
  58 .Fa path
  59 is the path name of any file within the mounted file system.
  60 .Fa buf
  61 is a pointer to a
  62 .Nm statvfs
  63 structure defined in
  64 .Xr statvfs 5 .
  65 .Pp
  66 .Fn fstatvfs
  67 and
  68 .Fn fstatvfs1
  69 return the same information about an open file referenced by descriptor
  70 .Fa fd .
  71 .Pp
  72 The
  73 .Fn statvfs1
  74 and
  75 .Fn fstatvfs1
  76 functions allow an extra
  77 .Fa flags
  78 argument which can be
  79 .Dv ST_WAIT
  80 and
  81 .Dv ST_NOWAIT .
  82 When
  83 .Dv ST_NOWAIT
  84 is specified, then only cached statistics are returned.
  85 This can result in significant savings on non-local filesystems, where
  86 gathering statistics involves a network communication.
  87 .Pp
  88 The
  89 .Fn statvfs
  90 and
  91 .Fn fstatvfs
  92 calls are equivalent to the respective
  93 .Fn statvfs1
  94 and
  95 .Fn fstatvfs1
  96 calls with
  97 .Dv ST_WAIT
  98 specified as the
  99 .Fa flags
 100 argument.
 101 .Sh RETURN VALUES
 102 Upon successful completion, a value of 0 is returned.
 103 Otherwise, \-1 is returned and the global variable
 104 .Va errno
 105 is set to indicate the error.
 106 .Sh ERRORS
 107 .Fn statvfs
 108 and
 109 .Fn statvfs1
 110 fail if one or more of the following are true:
 111 .Bl -tag -width Er
 112 .It Bq Er ENOTDIR
 113 A component of the path prefix of
 114 .Fa path
 115 is not a directory.
 116 .It Bq Er ENAMETOOLONG
 117 The length of a component of
 118 .Fa path
 119 exceeds
 120 .Brq Dv NAME_MAX
 121 characters, or the length of
 122 .Fa path
 123 exceeds
 124 .Brq Dv PATH_MAX
 125 characters.
 126 .It Bq Er ENOENT
 127 The file referred to by
 128 .Fa path
 129 does not exist.
 130 .It Bq Er EACCES
 131 Search permission is denied for a component of the path prefix of
 132 .Fa path .
 133 .It Bq Er ELOOP
 134 Too many symbolic links were encountered in translating
 135 .Fa path .
 136 .It Bq Er EFAULT
 137 .Fa buf
 138 or
 139 .Fa path
 140 points to an invalid address.
 141 .It Bq Er EIO
 142 An
 143 .Tn I/O
 144 error occurred while reading from or writing to the file system.
 145 .El
 146 .Pp
 147 .Fn fstatvfs
 148 and
 149 .Fn fstatvfs1
 150 fail if one or more of the following are true:
 151 .Bl -tag -width Er
 152 .It Bq Er EBADF
 153 .Fa fd
 154 is not a valid open file descriptor.
 155 .It Bq Er EFAULT
 156 .Fa buf
 157 points to an invalid address.
 158 .It Bq Er EIO
 159 An
 160 .Tn I/O
 161 error occurred while reading from or writing to the file system.
 162 .El
 163 .Sh SEE ALSO
 164 .Xr statvfs 5
 165 .Sh HISTORY
 166 The
 167 .Fn statvfs ,
 168 .Fn statvfs1 ,
 169 .Fn fstatvfs ,
 170 and
 171 .Fn fstatvfs1
 172 functions first appeared in
 173 .Nx 3.0
 174 to replace
 175 the
 176 .Fn statfs
 177 family of functions which first appeared in
 178 .Bx 4.4 .