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