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. 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 .\"     @(#)getfsent.3  8.1 (Berkeley) 6/4/93
  33 .\" $FreeBSD: src/lib/libc/gen/getfsent.3,v 1.5.2.4 2001/12/14 18:33:51 ru Exp $
  34 .\" $DragonFly: src/lib/libc/gen/getfsent.3,v 1.2 2003/06/17 04:26:42 dillon Exp $
  35 .\"
  36 .Dd June 4, 1993
  37 .Dt GETFSENT 3
  38 .Os
  39 .Sh NAME
  40 .Nm getfsent ,
  41 .Nm getfsspec ,
  42 .Nm getfsfile ,
  43 .Nm setfsent ,
  44 .Nm endfsent
  45 .Nd get file system descriptor file entry
  46 .Sh LIBRARY
  47 .Lb libc
  48 .Sh SYNOPSIS
  49 .In fstab.h
  50 .Ft struct fstab *
  51 .Fn getfsent void
  52 .Ft struct fstab *
  53 .Fn getfsspec "const char *spec"
  54 .Ft struct fstab *
  55 .Fn getfsfile "const char *file"
  56 .Ft int
  57 .Fn setfsent void
  58 .Ft void
  59 .Fn endfsent void
  60 .Sh DESCRIPTION
  61 The
  62 .Fn getfsent ,
  63 .Fn getfsspec ,
  64 and
  65 .Fn getfsfile
  66 functions
  67 each return a pointer to an object with the following structure
  68 containing the broken-out fields of a line in the file system
  69 description file,
  70 .Aq Pa fstab.h .
  71 .Bd -literal -offset indent
  72 struct fstab {
  73         char    *fs_spec;       /* block special device name */
  74         char    *fs_file;       /* file system path prefix */
  75         char    *fs_vfstype;    /* File system type, ufs, nfs */
  76         char    *fs_mntops;     /* Mount options ala -o */
  77         char    *fs_type;       /* FSTAB_* from fs_mntops */
  78         int     fs_freq;        /* dump frequency, in days */
  79         int     fs_passno;      /* pass number on parallel fsck */
  80 };
  81 .Ed
  82 .Pp
  83 The fields have meanings described in
  84 .Xr fstab 5 .
  85 .Pp
  86 The
  87 .Fn setfsent
  88 function
  89 opens the file (closing any previously opened file) or rewinds it
  90 if it is already open.
  91 .Pp
  92 The
  93 .Fn endfsent
  94 function
  95 closes the file.
  96 .Pp
  97 The
  98 .Fn getfsspec
  99 and
 100 .Fn getfsfile
 101 functions
 102 search the entire file (opening it if necessary) for a matching special
 103 file name or file system file name.
 104 .Pp
 105 For programs wishing to read the entire database,
 106 .Fn getfsent
 107 reads the next entry (opening the file if necessary).
 108 .Pp
 109 All entries in the file with a type field equivalent to
 110 .Dv FSTAB_XX
 111 are ignored.
 112 .Sh RETURN VALUES
 113 The
 114 .Fn getfsent ,
 115 .Fn getfsspec ,
 116 and
 117 .Fn getfsfile
 118 functions
 119 return a
 120 .Dv NULL
 121 pointer on
 122 .Dv EOF
 123 or error.
 124 The
 125 .Fn setfsent
 126 function
 127 returns 0 on failure, 1 on success.
 128 The
 129 .Fn endfsent
 130 function
 131 returns nothing.
 132 .Sh FILES
 133 .Bl -tag -width /etc/fstab -compact
 134 .It Pa /etc/fstab
 135 .El
 136 .Sh SEE ALSO
 137 .Xr fstab 5
 138 .Sh HISTORY
 139 The
 140 .Fn getfsent
 141 function appeared in
 142 .Bx 4.0 ;
 143 the
 144 .Fn endfsent ,
 145 .Fn getfsfile ,
 146 .Fn getfsspec ,
 147 and
 148 .Fn setfsent
 149 functions appeared in
 150 .Bx 4.3 .
 151 .Sh BUGS
 152 These functions use static data storage;
 153 if the data is needed for future use, it should be
 154 copied before any subsequent calls overwrite it.