getmntopts.3

   1 .\"     $NetBSD: getmntopts.3,v 1.7 2004/02/24 15:12:51 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 April 11, 2003
  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;          /* is this a negative option, e.g., "dev" */
  80         int m_flag;             /* bit to set, e.g., MNT_RDONLY */
  81         int m_altloc;           /* non-zero to 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 EXAMPLES
 161 Most commands will use the standard option set.
 162 Local filesystems which support the
 163 .Dv MNT_UPDATE
 164 flag, would also have an
 165 .Dv MOPT_UPDATE
 166 entry.
 167 This can be declared and used as follows:
 168 .Bd -literal
 169 #include \*[Lt]mntopts.h\*[Gt]
 170
 171 static const struct mntopt mopts[] = {
 172         MOPT_STDOPTS,
 173         MOPT_UPDATE,
 174         { NULL }
 175 };
 176
 177 ...
 178 long val;
 179 mntflags = mntaltflags = 0;
 180 mntoptparse_t mp;
 181 ...
 182 if ((mp = getmntopts(options, mopts, \*[Am]mntflags, \*[Am]mntaltflags)) == NULL)
 183         err(1, NULL);
 184 ...
 185 val = getmntoptnum(mp, "rsize");
 186 freemntopts(mp);
 187 .Ed
 188 .Sh RETURN VALUE
 189 .Fn getmntopts
 190 returns
 191 .Dv NULL
 192 if an error occurred.
 193 .Fn getmntoptstr
 194 returns
 195 .Dv NULL
 196 if the option does not have an argument, or the option string.
 197 .Fn getmntoptnum
 198 returns \-1 if an error occurred and
 199 .Va getmnt_silent
 200 is set.
 201 .Sh DIAGNOSTICS
 202 If the external integer variable
 203 .Va getmnt_silent
 204 is non-zero then the
 205 .Fn getmntopts
 206 function displays an error message and exits if an
 207 unrecognized option is encountered.
 208 By default
 209 .Va getmnt_silent
 210 is zero.
 211 .Sh SEE ALSO
 212 .Xr err 3 ,
 213 .Xr mount 8
 214 .Sh HISTORY
 215 The
 216 .Fn getmntopts
 217 function appeared in
 218 .Bx 4.4 .
 219 It was moved to the utilities library and enhanced to retrieve option
 220 values in
 221 .Nx 2.0 .