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