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 .\" 3. 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 .Dd April 7, 2003
  29 .Dt GETFSENT 3
  30 .Os
  31 .Sh NAME
  32 .Nm getfsent ,
  33 .Nm getfsspec ,
  34 .Nm getfsfile ,
  35 .Nm setfsent ,
  36 .Nm endfsent
  37 .Nd get file system descriptor file entry
  38 .Sh LIBRARY
  39 .Lb libc
  40 .Sh SYNOPSIS
  41 .In fstab.h
  42 .Ft "struct fstab *"
  43 .Fn getfsent void
  44 .Ft "struct fstab *"
  45 .Fn getfsspec "const char *spec"
  46 .Ft "struct fstab *"
  47 .Fn getfsfile "const char *file"
  48 .Ft int
  49 .Fn setfsent void
  50 .Ft void
  51 .Fn endfsent void
  52 .Ft void
  53 .Fn setfstab "const char *file"
  54 .Ft "const char *"
  55 .Fn getfstab void
  56 .Sh DESCRIPTION
  57 The
  58 .Fn getfsent ,
  59 .Fn getfsspec ,
  60 and
  61 .Fn getfsfile
  62 functions
  63 each return a pointer to an object with the following structure
  64 containing the broken-out fields of a line in the file system
  65 description file,
  66 .In fstab.h .
  67 .Bd -literal -offset indent
  68 struct fstab {
  69         char    *fs_spec;       /* block special device name */
  70         char    *fs_file;       /* file system path prefix */
  71         char    *fs_vfstype;    /* File system type, ufs, nfs */
  72         char    *fs_mntops;     /* Mount options ala -o */
  73         char    *fs_type;       /* FSTAB_* from fs_mntops */
  74         int     fs_freq;        /* dump frequency, in days */
  75         int     fs_passno;      /* pass number on parallel fsck */
  76 };
  77 .Ed
  78 .Pp
  79 The fields have meanings described in
  80 .Xr fstab 5 .
  81 .Pp
  82 The
  83 .Fn setfsent
  84 function
  85 opens the file (closing any previously opened file) or rewinds it
  86 if it is already open.
  87 .Pp
  88 The
  89 .Fn endfsent
  90 function
  91 closes the file.
  92 .Pp
  93 The
  94 .Fn setfstab
  95 function sets the file to be used by subsequent operations.
  96 The value set by
  97 .Fn setfstab
  98 does not persist across calls to
  99 .Fn endfsent .
 100 .Pp
 101 The
 102 .Fn getfstab
 103 function returns the name of the file that will be used.
 104 .Pp
 105 The
 106 .Fn getfsspec
 107 and
 108 .Fn getfsfile
 109 functions
 110 search the entire file (opening it if necessary) for a matching special
 111 file name or file system file name.
 112 .Pp
 113 For programs wishing to read the entire database,
 114 .Fn getfsent
 115 reads the next entry (opening the file if necessary).
 116 .Pp
 117 All entries in the file with a type field equivalent to
 118 .Dv FSTAB_XX
 119 are ignored.
 120 .Sh RETURN VALUES
 121 The
 122 .Fn getfsent ,
 123 .Fn getfsspec ,
 124 and
 125 .Fn getfsfile
 126 functions
 127 return a
 128 .Dv NULL
 129 pointer on
 130 .Dv EOF
 131 or error.
 132 The
 133 .Fn setfsent
 134 function
 135 returns 0 on failure, 1 on success.
 136 The
 137 .Fn endfsent
 138 function
 139 returns nothing.
 140 .Sh ENVIRONMENT
 141 .Bl -tag -width ".Ev PATH_FSTAB"
 142 .It Ev PATH_FSTAB
 143 If the environment variable
 144 .Ev PATH_FSTAB
 145 is set, all operations are performed against the specified file.
 146 .Ev PATH_FSTAB
 147 will not be honored if the process environment or memory address space is
 148 considered
 149 .Dq tainted .
 150 (See
 151 .Xr issetugid 2
 152 for more information.)
 153 .El
 154 .Sh FILES
 155 .Bl -tag -width /etc/fstab -compact
 156 .It Pa /etc/fstab
 157 .El
 158 .Sh SEE ALSO
 159 .Xr fstab 5
 160 .Sh HISTORY
 161 The
 162 .Fn getfsent
 163 function appeared in
 164 .Bx 4.0 ;
 165 the
 166 .Fn endfsent ,
 167 .Fn getfsfile ,
 168 .Fn getfsspec ,
 169 and
 170 .Fn setfsent
 171 functions appeared in
 172 .Bx 4.3 ;
 173 the
 174 .Fn setfstab
 175 and
 176 .Fn getfstab
 177 functions appeared in
 178 .Fx 5.1 .
 179 .Sh BUGS
 180 These functions use static data storage;
 181 if the data is needed for future use, it should be
 182 copied before any subsequent calls overwrite it.