lib/libutil/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 In addition, the macros
 132 .Dv MOPT_FORCE
 133 and
 134 .Dv MOPT_UPDATE
 135 exist to enable the
 136 .Dv MNT_FORCE
 137 and
 138 .Dv MNT_UPDATE
 139 flags to be set.
 140 Finally, the table must be terminated by an entry with a
 141 .Dv NULL
 142 first element.
 143 .Pp
 144 .Fn getmntopts
 145 returns a
 146 .Li "mntoptparse_t"
 147 handle that can be used in subsequent
 148 .Fn getmntoptstr
 149 and
 150 .Fn getmntoptnum
 151 calls to fetch a value for an option and that must be freed with a call
 152 to
 153 .Fn freemntopts .
 154 If an error occurred, then if the external integer value
 155 .Va getmnt_silent
 156 is zero then
 157 .Fn getmntopts
 158 prints an error message and exits;
 159 if
 160 .Va getmnt_silent
 161 is non-zero then
 162 .Fn getmntopts
 163 returns
 164 .Dv NULL .
 165 .Pp
 166 The
 167 .Fn getmntoptstr
 168 function returns the string value of the named option, if such a value
 169 was set in the option string.
 170 If the value was not set, then if the external integer value
 171 .Va getmnt_silent
 172 is zero then
 173 .Fn getmntoptstr
 174 prints an error message and exits;
 175 if
 176 .Va getmnt_silent
 177 is non-zero then
 178 .Fn getmntoptstr
 179 returns
 180 .Dv NULL .
 181 .Pp
 182 The
 183 .Fn getmntoptnum
 184 returns the long value of the named option, if such a value was set in the
 185 option string.
 186 If the value was not set, or could not be converted from a string to a
 187 long, then if the external integer value
 188 .Va getmnt_silent
 189 is zero then
 190 .Fn getmntoptnum
 191 prints an error message and exits;
 192 if
 193 .Va getmnt_silent
 194 is non-zero then
 195 .Fn getmntoptnum
 196 returns \-1.
 197 .Pp
 198 The
 199 .Fn freemntopts
 200 frees the storage used by
 201 .Fn getmntopts .
 202 .Sh RETURN VALUES
 203 .Fn getmntopts
 204 returns
 205 .Dv NULL
 206 if an error occurred.
 207 Note that some bits may already have been set in
 208 .Va flagp
 209 and
 210 .Va altflagp
 211 even if
 212 .Dv NULL
 213 is returned.
 214 .Fn getmntoptstr
 215 returns
 216 .Dv NULL
 217 if an error occurred.
 218 .Fn getmntoptnum
 219 returns \-1 if an error occurred.
 220 .Sh EXAMPLES
 221 Most commands will use the standard option set.
 222 Local filesystems which support the
 223 .Dv MNT_UPDATE
 224 flag, would also have an
 225 .Dv MOPT_UPDATE
 226 entry.
 227 This can be declared and used as follows:
 228 .Bd -literal -offset indent
 229 #include \*[Lt]mntopts.h\*[Gt]
 230
 231 static const struct mntopt mopts[] = {
 232         MOPT_STDOPTS,
 233         MOPT_UPDATE,
 234         { NULL }
 235 };
 236
 237 \&...
 238
 239 long val;
 240 mntoptparse_t mp;
 241 mntflags = mntaltflags = 0;
 242
 243 \&...
 244
 245 mp = getmntopts(options, mopts, \*[Am]mntflags, \*[Am]mntaltflags);
 246
 247 if (mp == NULL)
 248         err(EXIT_FAILURE, "getmntopts");
 249
 250 \&...
 251
 252 val = getmntoptnum(mp, "rsize");
 253 freemntopts(mp);
 254 .Ed
 255 .Sh DIAGNOSTICS
 256 If the external integer variable
 257 .Va getmnt_silent
 258 is zero then the
 259 .Fn getmntopts ,
 260 .Fn getmntoptstr ,
 261 and
 262 .Fn getmntoptnum
 263 functions display an error message and exit if an error occurred.
 264 By default
 265 .Va getmnt_silent
 266 is zero.
 267 .Sh SEE ALSO
 268 .Xr err 3 ,
 269 .Xr mount 8
 270 .Sh HISTORY
 271 The
 272 .Fn getmntopts
 273 function appeared in
 274 .Bx 4.4 .
 275 It was moved to the utilities library and enhanced to retrieve option
 276 values in
 277 .Nx 2.0 .