lib/libc/gen/getfsent.3

   1 .\" Copyright (c) 1983, 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 .\" 4. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)getfsent.3  8.1 (Berkeley) 6/4/93
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd April 7, 2003
  32 .Dt GETFSENT 3
  33 .Os
  34 .Sh NAME
  35 .Nm getfsent ,
  36 .Nm getfsspec ,
  37 .Nm getfsfile ,
  38 .Nm setfsent ,
  39 .Nm endfsent
  40 .Nd get file system descriptor file entry
  41 .Sh LIBRARY
  42 .Lb libc
  43 .Sh SYNOPSIS
  44 .In fstab.h
  45 .Ft "struct fstab *"
  46 .Fn getfsent void
  47 .Ft "struct fstab *"
  48 .Fn getfsspec "const char *spec"
  49 .Ft "struct fstab *"
  50 .Fn getfsfile "const char *file"
  51 .Ft int
  52 .Fn setfsent void
  53 .Ft void
  54 .Fn endfsent void
  55 .Ft void
  56 .Fn setfstab "const char *file"
  57 .Ft "const char *"
  58 .Fn getfstab void
  59 .Sh DESCRIPTION
  60 The
  61 .Fn getfsent ,
  62 .Fn getfsspec ,
  63 and
  64 .Fn getfsfile
  65 functions
  66 each return a pointer to an object with the following structure
  67 containing the broken-out fields of a line in the file system
  68 description file,
  69 .In fstab.h .
  70 .Bd -literal -offset indent
  71 struct fstab {
  72         char    *fs_spec;       /* block special device name */
  73         char    *fs_file;       /* file system path prefix */
  74         char    *fs_vfstype;    /* File system type, ufs, nfs */
  75         char    *fs_mntops;     /* Mount options ala -o */
  76         char    *fs_type;       /* FSTAB_* from fs_mntops */
  77         int     fs_freq;        /* dump frequency, in days */
  78         int     fs_passno;      /* pass number on parallel fsck */
  79 };
  80 .Ed
  81 .Pp
  82 The fields have meanings described in
  83 .Xr fstab 5 .
  84 .Pp
  85 The
  86 .Fn setfsent
  87 function
  88 opens the file (closing any previously opened file) or rewinds it
  89 if it is already open.
  90 .Pp
  91 The
  92 .Fn endfsent
  93 function
  94 closes the file.
  95 .Pp
  96 The
  97 .Fn setfstab
  98 function sets the file to be used by subsequent operations.
  99 The value set by
 100 .Fn setfstab
 101 does not persist across calls to
 102 .Fn endfsent .
 103 .Pp
 104 The
 105 .Fn getfstab
 106 function returns the name of the file that will be used.
 107 .Pp
 108 The
 109 .Fn getfsspec
 110 and
 111 .Fn getfsfile
 112 functions
 113 search the entire file (opening it if necessary) for a matching special
 114 file name or file system file name.
 115 .Pp
 116 For programs wishing to read the entire database,
 117 .Fn getfsent
 118 reads the next entry (opening the file if necessary).
 119 .Pp
 120 All entries in the file with a type field equivalent to
 121 .Dv FSTAB_XX
 122 are ignored.
 123 .Sh RETURN VALUES
 124 The
 125 .Fn getfsent ,
 126 .Fn getfsspec ,
 127 and
 128 .Fn getfsfile
 129 functions
 130 return a
 131 .Dv NULL
 132 pointer on
 133 .Dv EOF
 134 or error.
 135 The
 136 .Fn setfsent
 137 function
 138 returns 0 on failure, 1 on success.
 139 The
 140 .Fn endfsent
 141 function
 142 returns nothing.
 143 .Sh ENVIRONMENT
 144 .Bl -tag -width ".Ev PATH_FSTAB"
 145 .It Ev PATH_FSTAB
 146 If the environment variable
 147 .Ev PATH_FSTAB
 148 is set, all operations are performed against the specified file.
 149 .Ev PATH_FSTAB
 150 will not be honored if the process environment or memory address space is
 151 considered
 152 .Dq tainted .
 153 (See
 154 .Xr issetugid 2
 155 for more information.)
 156 .El
 157 .Sh FILES
 158 .Bl -tag -width /etc/fstab -compact
 159 .It Pa /etc/fstab
 160 .El
 161 .Sh SEE ALSO
 162 .Xr fstab 5
 163 .Sh HISTORY
 164 The
 165 .Fn getfsent
 166 function appeared in
 167 .Bx 4.0 ;
 168 the
 169 .Fn endfsent ,
 170 .Fn getfsfile ,
 171 .Fn getfsspec ,
 172 and
 173 .Fn setfsent
 174 functions appeared in
 175 .Bx 4.3 ;
 176 the
 177 .Fn setfstab
 178 and
 179 .Fn getfstab
 180 functions appeared in
 181 .Fx 5.1 .
 182 .Sh BUGS
 183 These functions use static data storage;
 184 if the data is needed for future use, it should be
 185 copied before any subsequent calls overwrite it.