lib/libutil/getmntopts.3

   1 .\"     $NetBSD: getmntopts.3,v 1.9 2009/05/04 20:43:48 wiz 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 August 26, 2007
  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 bitmask
  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 The
 145 .Fn getmntoptstr
 146 function returns the string value of the named option, if such a value
 147 was set it the option string.
 148 .Pp
 149 The
 150 .Fn getmntoptnum
 151 returns the long value of the named option, if such a value was set it the
 152 option string.
 153 It prints an error message and exits if the value was not
 154 set, or could not be converted from a string to a long.
 155 .Pp
 156 The
 157 .Fn freemntopts
 158 frees the storage used by
 159 .Fn getmntopts .
 160 .Sh RETURN VALUES
 161 .Fn getmntopts
 162 returns
 163 .Dv NULL
 164 if an error occurred.
 165 Note that some bits may already have been set in
 166 .Va flagp
 167 and
 168 .Va altflagp
 169 even if
 170 .Dv NULL
 171 is returned.
 172 .Fn getmntoptstr
 173 returns
 174 .Dv NULL
 175 if the option does not have an argument, or the option string.
 176 .Fn getmntoptnum
 177 returns \-1 if an error occurred.
 178 .Sh EXAMPLES
 179 Most commands will use the standard option set.
 180 Local filesystems which support the
 181 .Dv MNT_UPDATE
 182 flag, would also have an
 183 .Dv MOPT_UPDATE
 184 entry.
 185 This can be declared and used as follows:
 186 .Bd -literal
 187 #include \*[Lt]mntopts.h\*[Gt]
 188
 189 static const struct mntopt mopts[] = {
 190         MOPT_STDOPTS,
 191         MOPT_UPDATE,
 192         { NULL }
 193 };
 194
 195 \&...
 196 long val;
 197 mntflags = mntaltflags = 0;
 198 mntoptparse_t mp;
 199 \&...
 200 if ((mp = getmntopts(options, mopts, \*[Am]mntflags, \*[Am]mntaltflags)) == NULL)
 201         err(1, NULL);
 202 \&...
 203 val = getmntoptnum(mp, "rsize");
 204 freemntopts(mp);
 205 .Ed
 206 .Sh DIAGNOSTICS
 207 If the external integer variable
 208 .Va getmnt_silent
 209 is zero then the
 210 .Fn getmntopts
 211 function displays an error message and exits if an
 212 unrecognized option is encountered.
 213 By default
 214 .Va getmnt_silent
 215 is zero.
 216 .Sh SEE ALSO
 217 .Xr err 3 ,
 218 .Xr mount 8
 219 .Sh HISTORY
 220 The
 221 .Fn getmntopts
 222 function appeared in
 223 .Bx 4.4 .
 224 It was moved to the utilities library and enhanced to retrieve option
 225 values in
 226 .Nx 2.0 .