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 .\"
  35 .Dd June 4, 1993
  36 .Dt GETFSENT 3
  37 .Os
  38 .Sh NAME
  39 .Nm getfsent ,
  40 .Nm getfsspec ,
  41 .Nm getfsfile ,
  42 .Nm setfsent ,
  43 .Nm endfsent
  44 .Nd get file system descriptor file entry
  45 .Sh LIBRARY
  46 .Lb libc
  47 .Sh SYNOPSIS
  48 .In fstab.h
  49 .Ft struct fstab *
  50 .Fn getfsent void
  51 .Ft struct fstab *
  52 .Fn getfsspec "const char *spec"
  53 .Ft struct fstab *
  54 .Fn getfsfile "const char *file"
  55 .Ft int
  56 .Fn setfsent void
  57 .Ft void
  58 .Fn endfsent 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 .Aq Pa 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 getfsspec
  98 and
  99 .Fn getfsfile
 100 functions
 101 search the entire file (opening it if necessary) for a matching special
 102 file name or file system file name.
 103 .Pp
 104 For programs wishing to read the entire database,
 105 .Fn getfsent
 106 reads the next entry (opening the file if necessary).
 107 .Pp
 108 All entries in the file with a type field equivalent to
 109 .Dv FSTAB_XX
 110 are ignored.
 111 .Sh RETURN VALUES
 112 The
 113 .Fn getfsent ,
 114 .Fn getfsspec ,
 115 and
 116 .Fn getfsfile
 117 functions
 118 return a
 119 .Dv NULL
 120 pointer on
 121 .Dv EOF
 122 or error.
 123 The
 124 .Fn setfsent
 125 function
 126 returns 0 on failure, 1 on success.
 127 The
 128 .Fn endfsent
 129 function
 130 returns nothing.
 131 .Sh FILES
 132 .Bl -tag -width /etc/fstab -compact
 133 .It Pa /etc/fstab
 134 .El
 135 .Sh SEE ALSO
 136 .Xr fstab 5
 137 .Sh HISTORY
 138 The
 139 .Fn getfsent
 140 function appeared in
 141 .Bx 4.0 ;
 142 the
 143 .Fn endfsent ,
 144 .Fn getfsfile ,
 145 .Fn getfsspec ,
 146 and
 147 .Fn setfsent
 148 functions appeared in
 149 .Bx 4.3 .
 150 .Sh BUGS
 151 These functions use static data storage;
 152 if the data is needed for future use, it should be
 153 copied before any subsequent calls overwrite it.