1.\" $NetBSD: getmntopts.3,v 1.12 2010/08/24 12:05:01 christos 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 May 4, 2010 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 51The 52.Fn getmntopts 53function takes a comma separated option list and a list 54of valid option names, and computes the bitmasks 55corresponding to the requested set of options. 56.Pp 57The string 58.Ar options 59is broken down into a sequence of comma separated tokens. 60Each token is looked up in the table described by 61.Ar mopts 62and the bits in 63the word referenced by either 64.Ar flagp 65or 66.Ar altflagp 67(depending on the 68.Dv m_altloc 69field of the option's table entry) 70are updated. 71The flag words are not initialized by 72.Fn getmntopts . 73The table, 74.Ar mopts , 75has the following format: 76.Bd -literal 77struct mntopt { 78 const char *m_option; /* option name */ 79 int m_inverse; /* negative option, e.g., "dev" */ 80 int m_flag; /* bit to set, e.g., MNT_RDONLY */ 81 int m_altloc; /* use altflagp rather than flagp */ 82}; 83.Ed 84.Pp 85The members of this structure are: 86.Bl -tag -width m_inverse 87.It Fa m_option 88the option name, 89for example 90.Dq suid . 91.It Fa m_inverse 92tells 93.Fn getmntopts 94that the name has the inverse meaning of the bit. 95For example, 96.Dq suid 97is the string, whereas the mount flag is 98.Dv MNT_NOSUID . 99In this case, the sense of the string and the flag 100are inverted, so the 101.Fa m_inverse 102flag should be set. 103.It Fa m_flag 104the value of the bit to be set or cleared in 105the flag word when the option is recognized. 106The bit is set when the option is discovered, 107but cleared if the option name was preceded 108by the letters 109.Dq no . 110The 111.Fa m_inverse 112flag causes these two operations to be reversed. 113.It Fa m_altloc 114the bit should be set or cleared in 115.Ar altflagp 116rather than 117.Ar flagp . 118.El 119.Pp 120Each of the user visible 121.Dv MNT_ 122flags has a corresponding 123.Dv MOPT_ 124macro which defines an appropriate 125.Li "struct mntopt" 126entry. 127To simplify the program interface and ensure consistency across all 128programs, a general purpose macro, 129.Dv MOPT_STDOPTS , 130is defined which contains an entry for all the generic VFS options. 131In addition, the macros 132.Dv MOPT_FORCE 133and 134.Dv MOPT_UPDATE 135exist to enable the 136.Dv MNT_FORCE 137and 138.Dv MNT_UPDATE 139flags to be set. 140Finally, the table must be terminated by an entry with a 141.Dv NULL 142first element. 143.Pp 144.Fn getmntopts 145returns a 146.Li "mntoptparse_t" 147handle that can be used in subsequent 148.Fn getmntoptstr 149and 150.Fn getmntoptnum 151calls to fetch a value for an option and that must be freed with a call 152to 153.Fn freemntopts . 154If an error occurred, then if the external integer value 155.Va getmnt_silent 156is zero then 157.Fn getmntopts 158prints an error message and exits; 159if 160.Va getmnt_silent 161is non-zero then 162.Fn getmntopts 163returns 164.Dv NULL . 165.Pp 166The 167.Fn getmntoptstr 168function returns the string value of the named option, if such a value 169was set in the option string. 170If the value was not set, then if the external integer value 171.Va getmnt_silent 172is zero then 173.Fn getmntoptstr 174prints an error message and exits; 175if 176.Va getmnt_silent 177is non-zero then 178.Fn getmntoptstr 179returns 180.Dv NULL . 181.Pp 182The 183.Fn getmntoptnum 184returns the long value of the named option, if such a value was set in the 185option string. 186If the value was not set, or could not be converted from a string to a 187long, then if the external integer value 188.Va getmnt_silent 189is zero then 190.Fn getmntoptnum 191prints an error message and exits; 192if 193.Va getmnt_silent 194is non-zero then 195.Fn getmntoptnum 196returns \-1. 197.Pp 198The 199.Fn freemntopts 200frees the storage used by 201.Fn getmntopts . 202.Sh RETURN VALUES 203.Fn getmntopts 204returns 205.Dv NULL 206if an error occurred. 207Note that some bits may already have been set in 208.Va flagp 209and 210.Va altflagp 211even if 212.Dv NULL 213is returned. 214.Fn getmntoptstr 215returns 216.Dv NULL 217if an error occurred. 218.Fn getmntoptnum 219returns \-1 if an error occurred. 220.Sh EXAMPLES 221Most commands will use the standard option set. 222Local filesystems which support the 223.Dv MNT_UPDATE 224flag, would also have an 225.Dv MOPT_UPDATE 226entry. 227This can be declared and used as follows: 228.Bd -literal -offset indent 229#include \*[Lt]mntopts.h\*[Gt] 230 231static const struct mntopt mopts[] = { 232 MOPT_STDOPTS, 233 MOPT_UPDATE, 234 { NULL } 235}; 236 237\&... 238 239long val; 240mntoptparse_t mp; 241mntflags = mntaltflags = 0; 242 243\&... 244 245mp = getmntopts(options, mopts, \*[Am]mntflags, \*[Am]mntaltflags); 246 247if (mp == NULL) 248 err(EXIT_FAILURE, "getmntopts"); 249 250\&... 251 252val = getmntoptnum(mp, "rsize"); 253freemntopts(mp); 254.Ed 255.Sh DIAGNOSTICS 256If the external integer variable 257.Va getmnt_silent 258is zero then the 259.Fn getmntopts , 260.Fn getmntoptstr , 261and 262.Fn getmntoptnum 263functions display an error message and exit if an error occurred. 264By default 265.Va getmnt_silent 266is zero. 267.Sh SEE ALSO 268.Xr err 3 , 269.Xr mount 8 270.Sh HISTORY 271The 272.Fn getmntopts 273function appeared in 274.Bx 4.4 . 275It was moved to the utilities library and enhanced to retrieve option 276values in 277.Nx 2.0 . 278