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 .\" 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 March 30, 1995
  36 .Dt GETMNTOPTS 3
  37 .Os
  38 .Sh NAME
  39 .Nm getmntopts
  40 .Nd scan mount options
  41 .Sh SYNOPSIS
  42 .Fd #include \&"mntopts.h"
  43 .Ft void
  44 .Fn getmntopts "char *options" "struct mntopt *mopts" "int *flagp" "int *altflagp"
  45 .Sh DESCRIPTION
  46 The
  47 .Fn getmntopts
  48 function takes a comma separated option list and a list
  49 of valid option names, and computes the bitmask
  50 corresponding to the requested set of options.
  51 .Pp
  52 The string
  53 .Fa options
  54 is broken down into a sequence of comma separated tokens.
  55 Each token is looked up in the table described by
  56 .Fa mopts
  57 and the bits in
  58 the word referenced by either
  59 .Fa flagp
  60 or
  61 .Fa altflagp
  62 (depending on the
  63 .Va m_altloc
  64 field of the option's table entry)
  65 are updated.
  66 The flag words are not initialized by
  67 .Fn getmntopts .
  68 The table,
  69 .Fa mopts ,
  70 has the following format:
  71 .Bd -literal
  72 struct mntopt {
  73         char *m_option;         /* option name */
  74         int m_inverse;          /* is this a negative option, e.g. "dev" */
  75         int m_flag;             /* bit to set, e.g. MNT_RDONLY */
  76         int m_altloc;           /* non-zero to use altflagp rather than flagp */
  77 };
  78 .Ed
  79 .Pp
  80 The members of this structure are:
  81 .Bl -tag -width m_inverse
  82 .It Va m_option
  83 the option name,
  84 for example
  85 .Dq Li suid .
  86 .It Va m_inverse
  87 tells
  88 .Fn getmntopts
  89 that the name has the inverse meaning of the
  90 bit.
  91 For example,
  92 .Dq Li suid
  93 is the string, whereas the
  94 mount flag is
  95 .Dv MNT_NOSUID .
  96 In this case, the sense of the string and the flag
  97 are inverted, so the
  98 .Va m_inverse
  99 flag should be set.
 100 .It Va m_flag
 101 the value of the bit to be set or cleared in
 102 the flag word when the option is recognized.
 103 The bit is set when the option is discovered,
 104 but cleared if the option name was preceded
 105 by the letters
 106 .Dq Li no .
 107 The
 108 .Va m_inverse
 109 flag causes these two operations to be reversed.
 110 .It Va m_altloc
 111 the bit should be set or cleared in
 112 .Fa altflagp
 113 rather than
 114 .Fa flagp .
 115 .El
 116 .Pp
 117 Each of the user visible
 118 .Dv MNT_
 119 flags has a corresponding
 120 .Dv MOPT_
 121 macro which defines an appropriate
 122 .Vt "struct mntopt"
 123 entry.
 124 To simplify the program interface and ensure consistency across all
 125 programs, a general purpose macro,
 126 .Dv MOPT_STDOPTS ,
 127 is defined which
 128 contains an entry for all the generic VFS options.
 129 In addition, the macros
 130 .Dv MOPT_FORCE
 131 and
 132 .Dv MOPT_UPDATE
 133 exist to enable the
 134 .Dv MNT_FORCE
 135 and
 136 .Dv MNT_UPDATE
 137 flags to be set.
 138 Finally, the table must be terminated by an entry with a
 139 .Dv NULL
 140 first element.
 141 .Sh EXAMPLES
 142 Most commands will use the standard option set.
 143 Local file systems which support the
 144 .Dv MNT_UPDATE
 145 flag, would also have an
 146 .Dv MOPT_UPDATE
 147 entry.
 148 This can be declared and used as follows:
 149 .Bd -literal
 150 #include "mntopts.h"
 151
 152 struct mntopt mopts[] = {
 153         MOPT_STDOPTS,
 154         MOPT_UPDATE,
 155         { NULL }
 156 };
 157
 158         ...
 159         mntflags = mntaltflags = 0;
 160         ...
 161         getmntopts(options, mopts, &mntflags, &mntaltflags);
 162         ...
 163 .Ed
 164 .Sh DIAGNOSTICS
 165 If the external integer variable
 166 .Va getmnt_silent
 167 is non-zero then the
 168 .Fn getmntopts
 169 function displays an error message and exits if an
 170 unrecognized option is encountered.
 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 .