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