lookup.subproj/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: src/lib/libc/gen/getfsent.3,v 1.17 2007/01/09 00:27:53 imp Exp $
  30 .\"
  31 .\" @APPLE_LICENSE_HEADER_START@
  32 .\"
  33 .\" Portions Copyright (c) 2003-2013 Apple Inc.  All Rights Reserved.
  34 .\"
  35 .\" This file contains Original Code and/or Modifications of Original Code
  36 .\" as defined in and that are subject to the Apple Public Source License
  37 .\" Version 2.0 (the 'License'). You may not use this file except in
  38 .\" compliance with the License. Please obtain a copy of the License at
  39 .\" http://www.opensource.apple.com/apsl/ and read it before using this
  40 .\" file.
  41 .\"
  42 .\" The Original Code and all software distributed under the License are
  43 .\" distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  44 .\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  45 .\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  46 .\" FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  47 .\" Please see the License for the specific language governing rights and
  48 .\" limitations under the License.
  49 .\"
  50 .\" @APPLE_LICENSE_HEADER_END@
  51 .\"
  52 .Dd April 7, 2003
  53 .Dt GETFSENT 3
  54 .Os
  55 .Sh NAME
  56 .Nm getfsent ,
  57 .Nm getfsspec ,
  58 .Nm getfsfile ,
  59 .Nm setfsent ,
  60 .Nm endfsent
  61 .Nd get file system descriptor file entry
  62 .Sh LIBRARY
  63 Standard system libraries.
  64 .Sh SYNOPSIS
  65 .In fstab.h
  66 .Ft "struct fstab *"
  67 .Fn getfsent void
  68 .Ft "struct fstab *"
  69 .Fn getfsspec "const char *spec"
  70 .Ft "struct fstab *"
  71 .Fn getfsfile "const char *file"
  72 .Ft int
  73 .Fn setfsent void
  74 .Ft void
  75 .Fn endfsent void
  76 .\".Ft void
  77 .\".Fn setfstab "const char *file"
  78 .\".Ft "const char *"
  79 .\".Fn getfstab void
  80 .Sh DESCRIPTION
  81 The
  82 .Fn getfsent ,
  83 .Fn getfsspec ,
  84 and
  85 .Fn getfsfile
  86 functions
  87 each return a pointer to an object with the following structure
  88 containing file system descriptions from the directory systems
  89 consulted by the
  90 .Nm opendirectoryd
  91 daemon.
  92 This will include records from the local /etc/fstab file.
  93 .Bd -literal -offset indent
  94 struct fstab {
  95         char    *fs_spec;       /* block special device name */
  96         char    *fs_file;       /* file system path prefix */
  97         char    *fs_vfstype;    /* File system type, ufs, nfs */
  98         char    *fs_mntops;     /* Mount options ala -o */
  99         char    *fs_type;       /* FSTAB_* from fs_mntops */
 100         int     fs_freq;        /* dump frequency, in days */
 101         int     fs_passno;      /* pass number on parallel fsck */
 102 };
 103 .Ed
 104 .Pp
 105 The fields have meanings described in
 106 .Xr fstab 5 .
 107 .Pp
 108 The
 109 .Fn getfsspec
 110 and
 111 .Fn getfsfile
 112 functions
 113 search in available directory services 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 searches all available directory services on it's first invocation.
 119 It caches the returned entries in a list
 120 and returns fstab entries one at a time.
 121 .Pp
 122 The
 123 .Fn setfsent
 124 and
 125 .Fn endfsent
 126 functions clear the cached results from a previous
 127 .Fn getfsent
 128 call.
 129 .Pp
 130 Entries in the /etc/fstab file with a type field equivalent to
 131 .Dv FSTAB_XX
 132 are ignored.
 133 .Sh RETURN VALUES
 134 The
 135 .Fn getfsent ,
 136 .Fn getfsspec ,
 137 and
 138 .Fn getfsfile
 139 functions
 140 return a
 141 .Dv NULL
 142 pointer on
 143 .Dv EOF
 144 or error.
 145 The
 146 .Fn setfsent
 147 function
 148 returns 0 on failure, 1 on success.
 149 The
 150 .Fn endfsent
 151 function
 152 returns nothing.
 153 .Sh FILES
 154 .Bl -tag -width /etc/fstab -compact
 155 .It Pa /etc/fstab
 156 .El
 157 .Sh SEE ALSO
 158 .Xr opendirectoryd 8 ,
 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 .Sh BUGS
 174 The data space used by
 175 these functions is thread-specific; if future use requires the data, it should be
 176 copied before any subsequent calls to these functions overwrite it.