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 fstatfs
  42 .Nd get file system statistics
  43 .Sh SYNOPSIS
  44 .Fd #include <sys/param.h>
  45 .Fd #include <sys/mount.h>
  46 .Ft int
  47 .Fn statfs "const char *path" "struct statfs *buf"
  48 .Ft int
  49 .Fn fstatfs "int fd" "struct statfs *buf"
  50 .Sh DESCRIPTION
  51 .Fn Statfs
  52 returns information about a mounted file system.
  53 .Fa Path
  54 is the path name of any file within the mounted file system.
  55 .Fa Buf
  56 is a pointer to a
  57 .Fa statfs
  58 structure defined as follows:
  59 .Bd -literal
  60 typedef struct { int32_t val[2]; } fsid_t;
  61
  62 #define MFSTYPENAMELEN  16 /* length of fs type name including null */
  63 #define MAXPATHLEN      1024
  64
  65 struct statfs {
  66     uint32_t        f_bsize;        /* fundamental file system block size */
  67     int32_t         f_iosize;       /* optimal transfer block size */
  68     uint64_t        f_blocks;       /* total data blocks in file system */
  69     uint64_t        f_bfree;        /* free blocks in fs */
  70     uint64_t        f_bavail;       /* free blocks avail to non-superuser */
  71     uint64_t        f_files;        /* total file nodes in file system */
  72     uint64_t        f_ffree;        /* free file nodes in fs */
  73     fsid_t          f_fsid;         /* file system id */
  74     uid_t           f_owner;        /* user that mounted the filesystem */
  75     uint32_t        f_type;         /* type of filesystem */
  76     uint32_t        f_flags;        /* copy of mount exported flags */
  77     uint32_t        f_fssubtype;    /* fs sub-type (flavor) */
  78     char            f_fstypename[MFSTYPENAMELEN];   /* fs type name */
  79     char            f_mntonname[MAXPATHLEN];        /* directory on which mounted */
  80     char            f_mntfromname[MAXPATHLEN];      /* mounted filesystem */
  81     uint32_t        f_reserved[8];  /* For future use */
  82 };
  83 .Ed
  84 .Pp
  85 Fields that are undefined for a particular file system are set to -1.
  86 .Fn Fstatfs
  87 returns the same information about an open file referenced by descriptor
  88 .Fa fd .
  89 .Sh FLAGS
  90 .Bl -tag -width MNT_UNKOWNPERMISSIONS
  91 These are some of the flags that may be present in the f_flags field.
  92 .It Dv MNT_RDONLY
  93 A read-only filesystem
  94 .It Dv MNT_SYNCHRONOUS
  95 File system is written to synchronously
  96 .It Dv MNT_NOEXEC
  97 Can't exec from filesystem
  98 .It Dv MNT_NOSUID
  99 Setuid bits are not honored on this filesystem
 100 .It Dv MNT_NODEV
 101 Don't interpret special files
 102 .It Dv MNT_UNION
 103 Union with underlying filesysten
 104 .It Dv MNT_ASYNC
 105 File system written to asynchronously
 106 .It Dv MNT_EXPORTED
 107 File system is exported
 108 .it Dv MNT_LOCAL
 109 File system is stored locally
 110 .It Dv MNT_QUOTA
 111 Quotas are enabled on this file system
 112 .It Dv MNT_ROOTFS
 113 This file system is the root of the file system
 114 .It Dv MNT_DOVOLFS
 115 File system supports volfs
 116 .It Dv MNT_DONTBROWSE
 117 File system is not appropriate path to user data
 118 .It Dv MNT_UNKNOWNPERMISSIONS
 119 VFS will ignore ownership information on filesystem objects
 120 .It Dv MNT_AUTOMOUNTED
 121 File system was mounted by automounter
 122 .It Dv MNT_JOURNALED
 123 File system is journaled
 124 .It Dv MNT_DEFWRITE
 125 File system should defer writes
 126 .It Dv MNT_MULTILABEL
 127 MAC support for individual labels
 128 .El
 129 .Sh CAVEATS
 130 In Mac OS X versions before 10.4, f_iosize is 4096. On these older
 131 systems, use MAXBSIZE instead.
 132 .Sh RETURN VALUES
 133 Upon successful completion, a value of 0 is returned.
 134 Otherwise, -1 is returned and the global variable
 135 .Va errno
 136 is set to indicate the error.
 137 .Sh ERRORS
 138 .Fn Statfs
 139 fails if one or more of the following are true:
 140 .Bl -tag -width Er
 141 .It Bq Er ENOTDIR
 142 A component of the path prefix of
 143 .Fa Path
 144 is not a directory.
 145 .It Bq Er ENAMETOOLONG
 146 The length of a component of
 147 .Fa path
 148 exceeds
 149 .Dv {NAME_MAX}
 150 characters, or the length of
 151 .Fa path
 152 exceeds
 153 .Dv {PATH_MAX}
 154 characters.
 155 .It Bq Er ENOENT
 156 The file referred to by
 157 .Fa path
 158 does not exist.
 159 .It Bq Er EACCES
 160 Search permission is denied for a component of the path prefix of
 161 .Fa path .
 162 .It Bq Er ELOOP
 163 Too many symbolic links were encountered in translating
 164 .Fa path .
 165 .It Bq Er EFAULT
 166 .Fa Buf
 167 or
 168 .Fa path
 169 points to an invalid address.
 170 .It Bq Er EIO
 171 An
 172 .Tn I/O
 173 error occurred while reading from or writing to the file system.
 174 .El
 175 .Pp
 176 .Fn Fstatfs
 177 fails if one or more of the following are true:
 178 .Bl -tag -width Er
 179 .It Bq Er EBADF
 180 .Fa fd
 181 is not a valid open file descriptor.
 182 .It Bq Er EFAULT
 183 .Fa Buf
 184 points to an invalid address.
 185 .It Bq Er EIO
 186 An
 187 .Tn I/O
 188 error occurred while reading from or writing to the file system.
 189 .El
 190 .Sh HISTORY
 191 The
 192 .Fn statfs
 193 function first appeared in 4.4BSD.