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