gen/getmntinfo.3

   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 .\"     @(#)getmntinfo.3        8.1 (Berkeley) 6/9/93
  33 .\" $FreeBSD: src/lib/libc/gen/getmntinfo.3,v 1.12 2002/12/19 09:40:21 ru Exp $
  34 .\"
  35 .Dd May 15, 2008
  36 .Dt GETMNTINFO 3
  37 .Os
  38 .Sh NAME
  39 .Nm getmntinfo
  40 .Nd get information about mounted file systems
  41 .Sh SYNOPSIS
  42 .In sys/param.h
  43 .In sys/ucred.h
  44 .In sys/mount.h
  45 .Ft int
  46 .Fn getmntinfo "struct statfs **mntbufp" "int flags"
  47 #ifdef UNIFDEF_LEGACY_64_APIS
  48 .Sh TRANSITIIONAL SYNOPSIS (NOW DEPRECATED)
  49 .Ft int
  50 .br
  51 .Fn getmntinfo64 "struct statfs64 **mntbufp" "int flags" ;
  52 #endif /* UNIFDEF_LEGACY_64_APIS */
  53 .Sh DESCRIPTION
  54 The
  55 .Fn getmntinfo
  56 function
  57 returns an array of
  58 .Ft statfs
  59 structures describing each currently mounted file system (see
  60 .Xr statfs 2 ) .
  61 .Pp
  62 The
  63 .Fn getmntinfo
  64 function
  65 passes its
  66 .Fa flags
  67 argument transparently to
  68 .Xr getfsstat 2 .
  69 #ifdef UNIFDEF_LEGACY_64_APIS
  70 .Pp
  71 Like
  72 .Xr getfsstat 2 ,
  73 when the macro
  74 .Dv _DARWIN_FEATURE_64_BIT_INODE
  75 is defined, the
  76 .Ft ino_t
  77 type will be 64-bits (force 64-bit inode mode by defining the
  78 .Dv _DARWIN_USE_64_BIT_INODE
  79 macro before including header files).
  80 This will cause the symbol variant of
  81 .Fn getmntinfo ,
  82 with the
  83 .Fa $INODE64
  84 suffixes, to be automatically linked in.
  85 In addition, the
  86 .Ft statfs
  87 structure will be the 64-bit inode version.
  88 If
  89 .Dv _DARWIN_USE_64_BIT_INODE
  90 is not defined, both
  91 .Fn getmntinfo
  92 and the
  93 .Ft statfs
  94 structure will refer to the 32-bit inode versions.
  95 #endif /* UNIFDEF_LEGACY_64_APIS */
  96 .Sh RETURN VALUES
  97 On successful completion,
  98 .Fn getmntinfo
  99 returns a count of the number of elements in the array.
 100 The pointer to the array is stored into
 101 .Fa mntbufp .
 102 .Pp
 103 If an error occurs, zero is returned and the external variable
 104 .Va errno
 105 is set to indicate the error.
 106 Although the pointer
 107 .Fa mntbufp
 108 will be unmodified, any information previously returned by
 109 .Fn getmntinfo
 110 will be lost.
 111 .Sh ERRORS
 112 The
 113 .Fn getmntinfo
 114 function
 115 may fail and set errno for any of the errors specified for the library
 116 routines
 117 .Xr getfsstat 2
 118 or
 119 .Xr malloc 3 .
 120 #ifdef UNIFDEF_LEGACY_64_APIS
 121 .Sh TRANSITIONAL DESCRIPTION (NOW DEPRECATED)
 122 The
 123 .Fn getmntinfo64
 124 routine is equivalent to its corresponding non-64-suffixed routine,
 125 when 64-bit inodes are in effect.
 126 It was added before there was support for the symbol variants, and so is
 127 now deprecated.
 128 Instead of using it, set the
 129 .Dv _DARWIN_USE_64_BIT_INODE
 130 macro before including header files to force 64-bit inode support.
 131 .Pp
 132 The
 133 .Ft statfs64
 134 structure used by this deprecated routine is the same as the
 135 .Ft statfs
 136 structure when 64-bit inodes are in effect.
 137 #endif /* UNIFDEF_LEGACY_64_APIS */
 138 .Sh SEE ALSO
 139 .Xr getfsstat 2 ,
 140 .Xr mount 2 ,
 141 .Xr statfs 2 ,
 142 .Xr mount 8
 143 .Sh HISTORY
 144 The
 145 .Fn getmntinfo
 146 function first appeared in
 147 .Bx 4.4 .
 148 .Sh BUGS
 149 The
 150 .Fn getmntinfo
 151 #ifdef UNIFDEF_LEGACY_64_APIS
 152 and
 153 .Fn getmntinfo64
 154 functions write the array of structures to an internal static object
 155 #else /* !UNIFDEF_LEGACY_64_APIS */
 156 function writes the array of structures to an internal static object
 157 #endif /* UNIFDEF_LEGACY_64_APIS */
 158 and returns
 159 a pointer to that object.
 160 Subsequent calls to
 161 .Fn getmntinfo
 162 #ifdef UNIFDEF_LEGACY_64_APIS
 163 and
 164 .Fn getmntinfo64
 165 #endif /* UNIFDEF_LEGACY_64_APIS */
 166 will modify the same object.
 167 .Pp
 168 The memory allocated by
 169 .Fn getmntinfo
 170 #ifdef UNIFDEF_LEGACY_64_APIS
 171 and
 172 .Fn getmntinfo64
 173 #endif /* UNIFDEF_LEGACY_64_APIS */
 174 cannot be
 175 .Xr free 3 Ns 'd
 176 by the application.