lib/libutil/getmntopts.3

   1 .\" Copyright (c) 1994
   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 .\" 3. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)getmntopts.3        8.3 (Berkeley) 3/30/95
  33 .\" $FreeBSD: src/sbin/mount/getmntopts.3,v 1.6.2.4 2003/02/23 20:17:15 trhodes Exp $
  34 .\"
  35 .Dd June 8, 2012
  36 .Dt GETMNTOPTS 3
  37 .Os
  38 .Sh NAME
  39 .Nm getmntopts
  40 .Nd scan mount options
  41 .Sh LIBRARY
  42 .Lb libutil
  43 .Sh SYNOPSIS
  44 .In mntopts.h
  45 .Ft void
  46 .Fn getmntopts "char *options" "struct mntopt *mopts" "int *flagp" "int *altflagp"
  47 .Sh DESCRIPTION
  48 The
  49 .Fn getmntopts
  50 function takes a comma separated option list and a list
  51 of valid option names, and computes the bitmask
  52 corresponding to the requested set of options.
  53 .Pp
  54 The string
  55 .Fa options
  56 is broken down into a sequence of comma separated tokens.
  57 Each token is looked up in the table described by
  58 .Fa mopts
  59 and the bits in
  60 the word referenced by either
  61 .Fa flagp
  62 or
  63 .Fa altflagp
  64 (depending on the
  65 .Va m_altloc
  66 field of the option's table entry)
  67 are updated.
  68 The flag words are not initialized by
  69 .Fn getmntopts .
  70 The table,
  71 .Fa mopts ,
  72 has the following format:
  73 .Bd -literal
  74 struct mntopt {
  75         char *m_option;         /* option name */
  76         int m_inverse;          /* is this a negative option, e.g. "dev" */
  77         int m_flag;             /* bit to set, e.g. MNT_RDONLY */
  78         int m_altloc;           /* non-zero to use altflagp rather than flagp */
  79 };
  80 .Ed
  81 .Pp
  82 The members of this structure are:
  83 .Bl -tag -width m_inverse
  84 .It Va m_option
  85 the option name,
  86 for example
  87 .Dq Li suid .
  88 .It Va m_inverse
  89 tells
  90 .Fn getmntopts
  91 that the name has the inverse meaning of the
  92 bit.
  93 For example,
  94 .Dq Li suid
  95 is the string, whereas the
  96 mount flag is
  97 .Dv MNT_NOSUID .
  98 In this case, the sense of the string and the flag
  99 are inverted, so the
 100 .Va m_inverse
 101 flag should be set.
 102 .It Va m_flag
 103 the value of the bit to be set or cleared in
 104 the flag word when the option is recognized.
 105 The bit is set when the option is discovered,
 106 but cleared if the option name was preceded
 107 by the letters
 108 .Dq Li no .
 109 The
 110 .Va m_inverse
 111 flag causes these two operations to be reversed.
 112 .It Va m_altloc
 113 the bit should be set or cleared in
 114 .Fa altflagp
 115 rather than
 116 .Fa flagp .
 117 .El
 118 .Pp
 119 Each of the user visible
 120 .Dv MNT_
 121 flags has a corresponding
 122 .Dv MOPT_
 123 macro which defines an appropriate
 124 .Vt "struct mntopt"
 125 entry.
 126 To simplify the program interface and ensure consistency across all
 127 programs, a general purpose macro,
 128 .Dv MOPT_STDOPTS ,
 129 is defined which
 130 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 .Sh EXAMPLES
 144 Most commands will use the standard option set.
 145 Local file systems which support the
 146 .Dv MNT_UPDATE
 147 flag, would also have an
 148 .Dv MOPT_UPDATE
 149 entry.
 150 This can be declared and used as follows:
 151 .Bd -literal
 152 #include <mntopts.h>
 153
 154 struct mntopt mopts[] = {
 155         MOPT_STDOPTS,
 156         MOPT_UPDATE,
 157         { NULL }
 158 };
 159
 160         ...
 161         mntflags = mntaltflags = 0;
 162         ...
 163         getmntopts(options, mopts, &mntflags, &mntaltflags);
 164         ...
 165 .Ed
 166 .Sh DIAGNOSTICS
 167 If the external integer variable
 168 .Va getmnt_silent
 169 is non-zero then the
 170 .Fn getmntopts
 171 function displays an error message and exits if an
 172 unrecognized option is encountered.
 173 By default
 174 .Va getmnt_silent
 175 is zero.
 176 .Sh SEE ALSO
 177 .Xr err 3 ,
 178 .Xr mount 8
 179 .Sh HISTORY
 180 The
 181 .Fn getmntopts
 182 function appeared in
 183 .Bx 4.4 .