bsd/man/man2/statfs.2

   1 .\"     $NetBSD: statfs.2,v 1.10 1995/06/29 11:40:48 cgd 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. All advertising materials mentioning features or use of this software
  15 .\"    must display the following acknowledgement:
  16 .\"     This product includes software developed by the University of
  17 .\"     California, Berkeley and its contributors.
  18 .\" 4. Neither the name of the University nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .\"     @(#)statfs.2    8.3 (Berkeley) 2/11/94
  35 .\"
  36 .Dd February 11, 1994
  37 .Dt STATFS 2
  38 .Os
  39 .Sh NAME
  40 .Nm statfs,
  41 .Nm statfs64,
  42 .Nm fstatfs,
  43 .Nm fstatfs64
  44 .Nd get file system statistics
  45 .Sh SYNOPSIS
  46 .Fd #include <sys/param.h>
  47 .Fd #include <sys/mount.h>
  48 .Ft int
  49 .Fn statfs "const char *path" "struct statfs *buf"
  50 .Ft int
  51 .Fn statfs64 "const char *path" "struct statfs64 *buf"
  52 .Ft int
  53 .Fn fstatfs "int fd" "struct statfs *buf"
  54 .Ft int
  55 .Fn fstatfs64 "int fd" "struct statfs64 *buf"
  56 .Sh DESCRIPTION
  57 .Fn Statfs
  58 returns information about a mounted file system.
  59 .Fa Path
  60 is the path name of any file within the mounted file system.
  61 .Fa Buf
  62 is a pointer to a
  63 .Fa statfs
  64 or
  65 .Fa statfs64
  66 structure defined as follows:
  67 .Bd -literal
  68 typedef struct { int32_t val[2]; } fsid_t;
  69
  70 #define MFSNAMELEN      15 /* length of fs type name, not inc. nul */
  71 #define MNAMELEN        90 /* length of buffer for returned name */
  72 #define MFSTYPENAMELEN  16 /* length of fs type name including null */
  73 #define MAXPATHLEN      1024
  74
  75 struct statfs {
  76     short   f_otype;    /* type of file system (reserved: zero) */
  77     short   f_oflags;   /* copy of mount flags (reserved: zero) */
  78     long    f_bsize;    /* fundamental file system block size */
  79     long    f_iosize;   /* optimal transfer block size */
  80     long    f_blocks;   /* total data blocks in file system */
  81     long    f_bfree;    /* free blocks in fs */
  82     long    f_bavail;   /* free blocks avail to non-superuser */
  83     long    f_files;    /* total file nodes in file system */
  84     long    f_ffree;    /* free file nodes in fs */
  85     fsid_t  f_fsid;     /* file system id */
  86     uid_t   f_owner;    /* user that mounted the file system */
  87     short   f_reserved1;        /* reserved for future use */
  88     short   f_type;     /* type of file system (reserved) */
  89     long    f_flags;    /* copy of mount flags (reserved) */
  90     long    f_reserved2[2];     /* reserved for future use */
  91     char    f_fstypename[MFSNAMELEN]; /* fs type name */
  92     char    f_mntonname[MNAMELEN];    /* directory on which mounted */
  93     char    f_mntfromname[MNAMELEN];  /* mounted file system */
  94     char    f_reserved3;        /* reserved for future use */
  95     long    f_reserved4[4];     /* reserved for future use */
  96 };
  97
  98 struct statfs64 {
  99     uint32_t        f_bsize;        /* fundamental file system block size */
 100     int32_t         f_iosize;       /* optimal transfer block size */
 101     uint64_t        f_blocks;       /* total data blocks in file system */
 102     uint64_t        f_bfree;        /* free blocks in fs */
 103     uint64_t        f_bavail;       /* free blocks avail to non-superuser */
 104     uint64_t        f_files;        /* total file nodes in file system */
 105     uint64_t        f_ffree;        /* free file nodes in fs */
 106     fsid_t          f_fsid;         /* file system id */
 107     uid_t           f_owner;        /* user that mounted the filesystem */
 108     uint32_t        f_type;         /* type of filesystem */
 109     uint32_t        f_flags;        /* copy of mount exported flags */
 110     uint32_t        f_fssubtype;    /* fs sub-type (flavor) */
 111     char            f_fstypename[MFSTYPENAMELEN];   /* fs type name */
 112     char            f_mntonname[MAXPATHLEN];        /* directory on which mounted */
 113     char            f_mntfromname[MAXPATHLEN];      /* mounted filesystem */
 114     uint32_t        f_reserved[8];  /* For future use */
 115 };
 116 .Ed
 117 .Pp
 118 Fields that are undefined for a particular file system are set to -1.
 119 .Fn Fstatfs
 120 returns the same information about an open file referenced by descriptor
 121 .Fa fd .
 122 .Sh FLAGS
 123 .Bl -tag -width MNT_UNKOWNPERMISSIONS
 124 These are some of the flags that may be present in the f_flags field.
 125 .It Dv MNT_RDONLY
 126 A read-only filesystem
 127 .It Dv MNT_SYNCHRONOUS
 128 File system is written to synchronously
 129 .It Dv MNT_NOEXEC
 130 Can't exec from filesystem
 131 .It Dv MNT_NOSUID
 132 Setuid bits are not honored on this filesystem
 133 .It Dv MNT_NODEV
 134 Don't interpret special files
 135 .It Dv MNT_UNION
 136 Union with underlying filesysten
 137 .It Dv MNT_ASYNC
 138 File system written to asynchronously
 139 .It Dv MNT_EXPORTED
 140 File system is exported
 141 .it Dv MNT_LOCAL
 142 File system is stored locally
 143 .It Dv MNT_QUOTA
 144 Quotas are enabled on this file system
 145 .It Dv MNT_ROOTFS
 146 This file system is the root of the file system
 147 .It Dv MNT_DOVOLFS
 148 File system supports volfs
 149 .It Dv MNT_DONTBROWSE
 150 File system is not appropriate path to user data
 151 .It Dv MNT_UNKNOWNPERMISSIONS
 152 VFS will ignore ownership information on filesystem objects
 153 .It Dv MNT_AUTOMOUNTED
 154 File system was mounted by automounter
 155 .It Dv MNT_JOURNALED
 156 File system is journaled
 157 .It Dv MNT_DEFWRITE
 158 File system should defer writes
 159 .It Dv MNT_MULTILABEL
 160 MAC support for individual labels
 161 .El
 162 .Sh CAVEATS
 163 In Mac OS X versions before 10.4, f_iosize is 4096. On these older
 164 systems, use MAXBSIZE instead.
 165 .Sh RETURN VALUES
 166 Upon successful completion, a value of 0 is returned.
 167 Otherwise, -1 is returned and the global variable
 168 .Va errno
 169 is set to indicate the error.
 170 .Sh ERRORS
 171 .Fn Statfs
 172 fails if one or more of the following are true:
 173 .Bl -tag -width Er
 174 .It Bq Er ENOTDIR
 175 A component of the path prefix of
 176 .Fa Path
 177 is not a directory.
 178 .It Bq Er ENAMETOOLONG
 179 The length of a component of
 180 .Fa path
 181 exceeds
 182 .Dv {NAME_MAX}
 183 characters, or the length of
 184 .Fa path
 185 exceeds
 186 .Dv {PATH_MAX}
 187 characters.
 188 .It Bq Er ENOENT
 189 The file referred to by
 190 .Fa path
 191 does not exist.
 192 .It Bq Er EACCES
 193 Search permission is denied for a component of the path prefix of
 194 .Fa path .
 195 .It Bq Er ELOOP
 196 Too many symbolic links were encountered in translating
 197 .Fa path .
 198 .It Bq Er EFAULT
 199 .Fa Buf
 200 or
 201 .Fa path
 202 points to an invalid address.
 203 .It Bq Er EIO
 204 An
 205 .Tn I/O
 206 error occurred while reading from or writing to the file system.
 207 .El
 208 .Pp
 209 .Fn Fstatfs
 210 fails if one or more of the following are true:
 211 .Bl -tag -width Er
 212 .It Bq Er EBADF
 213 .Fa fd
 214 is not a valid open file descriptor.
 215 .It Bq Er EFAULT
 216 .Fa Buf
 217 points to an invalid address.
 218 .It Bq Er EIO
 219 An
 220 .Tn I/O
 221 error occurred while reading from or writing to the file system.
 222 .El
 223 .Sh HISTORY
 224 The
 225 .Fn statfs
 226 function first appeared in 4.4BSD. The
 227 .Fn statfs64
 228 and
 229 .Fn fstatfs64
 230 first appeared in Max OS X 10.5 (Leopard).