6/lib/libc/sys/statfs.2

   1 .\" Copyright (c) 1989, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)statfs.2    8.5 (Berkeley) 5/24/95
  33 .\" $FreeBSD$
  34 .\"
  35 .Dd November 26, 2004
  36 .Dt STATFS 2
  37 .Os
  38 .Sh NAME
  39 .Nm statfs
  40 .Nd get file system statistics
  41 .Sh LIBRARY
  42 .Lb libc
  43 .Sh SYNOPSIS
  44 .In sys/param.h
  45 .In 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 The
  52 .Fn statfs
  53 system call
  54 returns information about a mounted file system.
  55 The
  56 .Fa path
  57 argument
  58 is the path name of any file within the mounted file system.
  59 The
  60 .Fa buf
  61 argument
  62 is a pointer to a
  63 .Vt statfs
  64 structure defined as follows:
  65 .Bd -literal
  66 typedef struct fsid { int32_t val[2]; } fsid_t; /* file system id type */
  67
  68 /*
  69  * filesystem statistics
  70  */
  71
  72 #define MFSNAMELEN      16              /* length of type name including null */
  73 #define MNAMELEN        88              /* size of on/from name bufs */
  74 #define STATFS_VERSION  0x20030518      /* current version number */
  75
  76 struct statfs {
  77 uint32_t f_version;             /* structure version number */
  78 uint32_t f_type;                /* type of filesystem */
  79 uint64_t f_flags;               /* copy of mount exported flags */
  80 uint64_t f_bsize;               /* filesystem fragment size */
  81 uint64_t f_iosize;              /* optimal transfer block size */
  82 uint64_t f_blocks;              /* total data blocks in filesystem */
  83 uint64_t f_bfree;               /* free blocks in filesystem */
  84 int64_t  f_bavail;              /* free blocks avail to non-superuser */
  85 uint64_t f_files;               /* total file nodes in filesystem */
  86 int64_t  f_ffree;               /* free nodes avail to non-superuser */
  87 uint64_t f_syncwrites;          /* count of sync writes since mount */
  88 uint64_t f_asyncwrites;         /* count of async writes since mount */
  89 uint64_t f_syncreads;           /* count of sync reads since mount */
  90 uint64_t f_asyncreads;          /* count of async reads since mount */
  91 uint64_t f_spare[10];           /* unused spare */
  92 uint32_t f_namemax;             /* maximum filename length */
  93 uid_t     f_owner;              /* user that mounted the filesystem */
  94 fsid_t    f_fsid;               /* filesystem id */
  95 char      f_charspare[80];          /* spare string space */
  96 char      f_fstypename[MFSNAMELEN]; /* filesystem type name */
  97 char      f_mntfromname[MNAMELEN];  /* mounted filesystem */
  98 char      f_mntonname[MNAMELEN];    /* directory on which mounted */
  99 };
 100 .Ed
 101 .Pp
 102 The flags that may be returned include:
 103 .Bl -tag -width MNT_SYNCHRONOUS
 104 .It Dv MNT_RDONLY
 105 The file system is mounted read-only;
 106 Even the super-user may not write on it.
 107 .It Dv MNT_NOEXEC
 108 Files may not be executed from the file system.
 109 .It Dv MNT_NOSUID
 110 Setuid and setgid bits on files are not honored when they are executed.
 111 .It Dv MNT_SYNCHRONOUS
 112 All I/O to the file system is done synchronously.
 113 .It Dv MNT_ASYNC
 114 No file system I/O is done synchronously.
 115 .It Dv MNT_SOFTDEP
 116 Soft updates being done (see
 117 .Xr ffs 7 ) .
 118 .It Dv MNT_SUIDDIR
 119 Special handling of SUID bit on directories.
 120 .It Dv MNT_UNION
 121 Union with underlying file system.
 122 .It Dv MNT_NOSYMFOLLOW
 123 Symbolic links are not followed.
 124 .It Dv MNT_NOCLUSTERR
 125 Read clustering is disabled.
 126 .It Dv MNT_NOCLUSTERW
 127 Write clustering is disabled.
 128 .\".It Dv MNT_JAILDEVFS
 129 .\"XXX
 130 .It Dv MNT_MULTILABEL
 131 Mandatory Access Control (MAC) support for individual objects
 132 (see
 133 .Xr mac 4 ) .
 134 .It Dv MNT_ACLS
 135 Access Control List (ACL) support enabled.
 136 .It Dv MNT_LOCAL
 137 The file system resides locally.
 138 .It Dv MNT_QUOTA
 139 The file system has quotas enabled on it.
 140 .It Dv MNT_ROOTFS
 141 Identifies the root file system.
 142 .It Dv MNT_EXRDONLY
 143 The file system is exported read-only.
 144 .It Dv MNT_NOATIME
 145 Updating of file access times is disabled.
 146 .It Dv MNT_USER
 147 The file system has been mounted by a user.
 148 .\".It Dv MNT_IGNORE
 149 .\"XXX
 150 .It Dv MNT_EXPORTED
 151 The file system is exported for both reading and writing.
 152 .It Dv MNT_DEFEXPORTED
 153 The file system is exported for both reading and writing to any Internet host.
 154 .It Dv MNT_EXPORTANON
 155 The file system maps all remote accesses to the anonymous user.
 156 .It Dv MNT_EXKERB
 157 The file system is exported with Kerberos uid mapping.
 158 .It Dv MNT_EXPUBLIC
 159 The file system is exported publicly (WebNFS).
 160 .El
 161 .Pp
 162 Fields that are undefined for a particular file system are set to -1.
 163 The
 164 .Fn fstatfs
 165 system call
 166 returns the same information about an open file referenced by descriptor
 167 .Fa fd .
 168 .Sh RETURN VALUES
 169 .Rv -std
 170 .Sh ERRORS
 171 The
 172 .Fn statfs
 173 system call
 174 fails if one or more of the following are true:
 175 .Bl -tag -width Er
 176 .It Bq Er ENOTDIR
 177 A component of the path prefix of
 178 .Fa path
 179 is not a directory.
 180 .It Bq Er ENAMETOOLONG
 181 The length of a component of
 182 .Fa path
 183 exceeds 255 characters,
 184 or the length of
 185 .Fa path
 186 exceeds 1023 characters.
 187 .It Bq Er ENOENT
 188 The file referred to by
 189 .Fa path
 190 does not exist.
 191 .It Bq Er EACCES
 192 Search permission is denied for a component of the path prefix of
 193 .Fa path .
 194 .It Bq Er ELOOP
 195 Too many symbolic links were encountered in translating
 196 .Fa path .
 197 .It Bq Er EFAULT
 198 The
 199 .Fa buf
 200 or
 201 .Fa path
 202 argument
 203 points to an invalid address.
 204 .It Bq Er EIO
 205 An
 206 .Tn I/O
 207 error occurred while reading from or writing to the file system.
 208 .El
 209 .Pp
 210 The
 211 .Fn fstatfs
 212 system call
 213 fails if one or more of the following are true:
 214 .Bl -tag -width Er
 215 .It Bq Er EBADF
 216 The
 217 .Fa fd
 218 argument
 219 is not a valid open file descriptor.
 220 .It Bq Er EFAULT
 221 The
 222 .Fa buf
 223 argument
 224 points to an invalid address.
 225 .It Bq Er EIO
 226 An
 227 .Tn I/O
 228 error occurred while reading from or writing to the file system.
 229 .El
 230 .Sh HISTORY
 231 The
 232 .Fn statfs
 233 system call first appeared in
 234 .Bx 4.4 .