getmntopts.3

   1 .\"     $NetBSD: getmntopts.3,v 1.12 2010/08/24 12:05:01 christos Exp $
   2 .\"
   3 .\" Copyright (c) 1994
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. Neither the name of the University nor the names of its contributors
  15 .\"    may be used to endorse or promote products derived from this software
  16 .\"    without specific prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .\"     @(#)getmntopts.3        8.3 (Berkeley) 3/30/95
  31 .\"
  32 .Dd May 4, 2010
  33 .Dt GETMNTOPTS 3
  34 .Os
  35 .Sh NAME
  36 .Nm getmntopts
  37 .Nd scan mount options
  38 .Sh LIBRARY
  39 .Lb libutil
  40 .Sh SYNOPSIS
  41 .In mntopts.h
  42 .Ft mntoptparse_t
  43 .Fn getmntopts "const char *options" "const struct mntopt *mopts" "int *flagp" "int *altflagp"
  44 .Ft const char *
  45 .Fn getmntoptstr "mntoptparse_t mp" "const char *opt"
  46 .Ft long
  47 .Fn getmntoptnum "mntoptparse_t mp" "const char *opt"
  48 .Ft void
  49 .Fn freemntopts "mntoptparse_t mp"
  50 .Sh DESCRIPTION
  51 The
  52 .Fn getmntopts
  53 function takes a comma separated option list and a list
  54 of valid option names, and computes the bitmasks
  55 corresponding to the requested set of options.
  56 .Pp
  57 The string
  58 .Ar options
  59 is broken down into a sequence of comma separated tokens.
  60 Each token is looked up in the table described by
  61 .Ar mopts
  62 and the bits in
  63 the word referenced by either
  64 .Ar flagp
  65 or
  66 .Ar altflagp
  67 (depending on the
  68 .Dv m_altloc
  69 field of the option's table entry)
  70 are updated.
  71 The flag words are not initialized by
  72 .Fn getmntopts .
  73 The table,
  74 .Ar mopts ,
  75 has the following format:
  76 .Bd -literal
  77 struct mntopt {
  78         const char *m_option;   /* option name */
  79         int m_inverse;          /* negative option, e.g., "dev" */
  80         int m_flag;             /* bit to set, e.g., MNT_RDONLY */
  81         int m_altloc;           /* use altflagp rather than flagp */
  82 };
  83 .Ed
  84 .Pp
  85 The members of this structure are:
  86 .Bl -tag -width m_inverse
  87 .It Fa m_option
  88 the option name,
  89 for example
  90 .Dq suid .
  91 .It Fa m_inverse
  92 tells
  93 .Fn getmntopts
  94 that the name has the inverse meaning of the bit.
  95 For example,
  96 .Dq suid
  97 is the string, whereas the mount flag is
  98 .Dv MNT_NOSUID .
  99 In this case, the sense of the string and the flag
 100 are inverted, so the
 101 .Fa m_inverse
 102 flag should be set.
 103 .It Fa m_flag
 104 the value of the bit to be set or cleared in
 105 the flag word when the option is recognized.
 106 The bit is set when the option is discovered,
 107 but cleared if the option name was preceded
 108 by the letters
 109 .Dq no .
 110 The
 111 .Fa m_inverse
 112 flag causes these two operations to be reversed.
 113 .It Fa m_altloc
 114 the bit should be set or cleared in
 115 .Ar altflagp
 116 rather than
 117 .Ar flagp .
 118 .El
 119 .Pp
 120 Each of the user visible
 121 .Dv MNT_
 122 flags has a corresponding
 123 .Dv MOPT_
 124 macro which defines an appropriate
 125 .Li "struct mntopt"
 126 entry.
 127 To simplify the program interface and ensure consistency across all
 128 programs, a general purpose macro,
 129 .Dv MOPT_STDOPTS ,
 130 is defined which contains an entry for all the generic VFS options:
 131 .Bd -literal -offset indent
 132 MOPT_USERQUOTA,
 133 MOPT_GROUPQUOTA,
 134 MOPT_FSTAB_COMPAT,
 135 MOPT_NODEV,
 136 MOPT_NOEXEC,
 137 MOPT_NOSUID,
 138 MOPT_RDONLY,
 139 MOPT_UNION,
 140 MOPT_BROWSE,
 141 MOPT_AUTOMOUNTED,
 142 MOPT_DEFWRITE,
 143 MOPT_NOATIME,
 144 MOPT_PERMISSIONS,
 145 MOPT_IGNORE_OWNERSHIP,
 146 MOPT_QUARANTINE,
 147 MOPT_CPROTECT
 148 .Ed
 149 .Pp
 150 In addition, the macros
 151 .Dv MOPT_FORCE
 152 and
 153 .Dv MOPT_UPDATE
 154 exist to enable the
 155 .Dv MNT_FORCE
 156 and
 157 .Dv MNT_UPDATE
 158 flags to be set.
 159 Finally, the table must be terminated by an entry with a
 160 .Dv NULL
 161 first element.
 162 .Pp
 163 .Fn getmntopts
 164 returns a
 165 .Li "mntoptparse_t"
 166 handle that can be used in subsequent
 167 .Fn getmntoptstr
 168 and
 169 .Fn getmntoptnum
 170 calls to fetch a value for an option and that must be freed with a call
 171 to
 172 .Fn freemntopts .
 173 If an error occurred, then if the external integer value
 174 .Va getmnt_silent
 175 is zero then
 176 .Fn getmntopts
 177 prints an error message and exits;
 178 if
 179 .Va getmnt_silent
 180 is non-zero then
 181 .Fn getmntopts
 182 returns
 183 .Dv NULL .
 184 .Pp
 185 The
 186 .Fn getmntoptstr
 187 function returns the string value of the named option, if such a value
 188 was set in the option string.
 189 If the value was not set, then if the external integer value
 190 .Va getmnt_silent
 191 is zero then
 192 .Fn getmntoptstr
 193 prints an error message and exits;
 194 if
 195 .Va getmnt_silent
 196 is non-zero then
 197 .Fn getmntoptstr
 198 returns
 199 .Dv NULL .
 200 .Pp
 201 The
 202 .Fn getmntoptnum
 203 returns the long value of the named option, if such a value was set in the
 204 option string.
 205 If the value was not set, or could not be converted from a string to a
 206 long, then if the external integer value
 207 .Va getmnt_silent
 208 is zero then
 209 .Fn getmntoptnum
 210 prints an error message and exits;
 211 if
 212 .Va getmnt_silent
 213 is non-zero then
 214 .Fn getmntoptnum
 215 returns \-1.
 216 .Pp
 217 The
 218 .Fn freemntopts
 219 frees the storage used by
 220 .Fn getmntopts .
 221 .Sh RETURN VALUES
 222 .Fn getmntopts
 223 returns
 224 .Dv NULL
 225 if an error occurred.
 226 Note that some bits may already have been set in
 227 .Va flagp
 228 and
 229 .Va altflagp
 230 even if
 231 .Dv NULL
 232 is returned.
 233 .Fn getmntoptstr
 234 returns
 235 .Dv NULL
 236 if an error occurred.
 237 .Fn getmntoptnum
 238 returns \-1 if an error occurred.
 239 .Sh EXAMPLES
 240 Most commands will use the standard option set.
 241 Local filesystems which support the
 242 .Dv MNT_UPDATE
 243 flag, would also have an
 244 .Dv MOPT_UPDATE
 245 entry.
 246 This can be declared and used as follows:
 247 .Bd -literal -offset indent
 248 #include \*[Lt]mntopts.h\*[Gt]
 249
 250 static const struct mntopt mopts[] = {
 251         MOPT_STDOPTS,
 252         MOPT_UPDATE,
 253         { NULL }
 254 };
 255
 256 \&...
 257
 258 long val;
 259 mntoptparse_t mp;
 260 mntflags = mntaltflags = 0;
 261
 262 \&...
 263
 264 mp = getmntopts(options, mopts, \*[Am]mntflags, \*[Am]mntaltflags);
 265
 266 if (mp == NULL)
 267         err(EXIT_FAILURE, "getmntopts");
 268
 269 \&...
 270
 271 val = getmntoptnum(mp, "rsize");
 272 freemntopts(mp);
 273 .Ed
 274 .Sh DIAGNOSTICS
 275 If the external integer variable
 276 .Va getmnt_silent
 277 is zero then the
 278 .Fn getmntopts ,
 279 .Fn getmntoptstr ,
 280 and
 281 .Fn getmntoptnum
 282 functions display an error message and exit if an error occurred.
 283 By default
 284 .Va getmnt_silent
 285 is zero.
 286 .Sh SEE ALSO
 287 .Xr err 3 ,
 288 .Xr mount 8
 289 .Sh HISTORY
 290 The
 291 .Fn getmntopts
 292 function appeared in
 293 .Bx 4.4 .
 294 It was moved to the utilities library and enhanced to retrieve option
 295 values in
 296 .Nx 2.0 .