1.\"	$OpenBSD: getmntopts.3,v 1.7 2003/06/02 20:06:15 millert Exp $
2.\"	$NetBSD: getmntopts.3,v 1.2 1995/03/18 14:56:56 cgd Exp $
3.\"
4.\" Copyright (c) 1994
5.\"	The Regents of the University of California.  All rights reserved.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
10.\" 1. Redistributions of source code must retain the above copyright
11.\"    notice, this list of conditions and the following disclaimer.
12.\" 2. Redistributions in binary form must reproduce the above copyright
13.\"    notice, this list of conditions and the following disclaimer in the
14.\"    documentation and/or other materials provided with the distribution.
15.\" 3. Neither the name of the University nor the names of its contributors
16.\"    may be used to endorse or promote products derived from this software
17.\"    without specific prior written permission.
18.\"
19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29.\" SUCH DAMAGE.
30.\"
31.\"	@(#)getmntopts.3	8.1 (Berkeley) 3/27/94
32.\"
33.Dd March 27, 1994
34.Dt GETMNTOPTS 3
35.Os
36.Sh NAME
37.Nm getmntopts
38.Nd scan mount options
39.Sh SYNOPSIS
40.Fd #include <mntopts.h>
41.Ft void
42.Fn getmntopts "char *options" "struct mntopt *mopts" "int *flagp"
43.Sh DESCRIPTION
44The
45.Fn getmntopts
46function takes a comma separated option list and a list
47of valid option names, and computes the bitmask
48corresponding to the requested set of options.
49.Pp
50The string
51.Ar options
52is broken down into a sequence of comma separated tokens.
53Each token is looked up in the table described by
54.Ar mopts
55and the bits in
56the word referenced by
57.Ar flagp
58are updated.
59The flag word is not initialized by
60.Fn getmntopts .
61The table,
62.Dv mopts ,
63has the following format:
64.Bd -literal
65struct mntopt {
66	char *m_option;		/* option name */
67	int m_inverse;		/* is this a negative option, eg "dev" */
68	int m_flag;		/* bit to set, eg MNT_RDONLY */
69};
70.Ed
71.Pp
72The members of this structure are:
73.Bl -tag -width m_inverse
74.It Fa m_option
75The option name,
76for example
77.Dq suid .
78.It Fa m_inverse
79Tells
80.Fn getmntopts
81that the name has the inverse meaning of the
82bit.
83For example,
84.Dq suid
85is the string, whereas the
86mount flag is
87.Dv MNT_NOSUID .
88In this case, the sense of the string and the flag
89are inverted, so the
90.Dv m_inverse
91flag should be set.
92.It Fa m_flag
93The value of the bit to be set or cleared in
94the flag word when the option is recognized.
95The bit is set when the option is discovered,
96but cleared if the option name was preceded
97by the letters
98.Dq no .
99The
100.Dv m_inverse
101flag causes these two operations to be reversed.
102.El
103.Pp
104Each of the user visible
105.Dv MNT_
106flags has a corresponding
107.Dv MOPT_
108macro which defines an appropriate
109.Li "struct mntopt"
110entry.
111To simplify the program interface and ensure consistency across all
112programs, a general purpose macro,
113.Dv MOPT_STDOPTS ,
114is defined which
115contains an entry for all the generic VFS options.
116In addition, the macros
117.Dv MOPT_FORCE
118and
119.Dv MOPT_UPDATE
120exist to enable the
121.Dv MNT_FORCE
122and
123.Dv MNT_UPDATE
124flags to be set.
125Finally, the table must be terminated by an entry with a NULL
126first element.
127.Sh EXAMPLES
128Most commands will use the standard option set.
129Local filesystems which support the
130.Dv MNT_UPDATE
131flag, would also have an
132.Dv MOPT_UPDATE
133entry.
134This can be declared and used as follows:
135.Bd -literal
136#include "mntopts.h"
137
138struct mntopt mopts[] = {
139	MOPT_STDOPTS,
140	MOPT_UPDATE,
141	{ NULL }
142};
143
144	...
145	mntflags = 0;
146	...
147	getmntopts(options, mopts, &mntflags)
148	...
149.Ed
150.Sh DIAGNOSTICS
151The
152.Fn getmntopts
153function displays an error message and exits if an
154unrecognized option is encountered.
155.Sh SEE ALSO
156.Xr err 3 ,
157.Xr mount 8
158.Sh HISTORY
159The
160.Fn getmntopts
161function appeared in
162.Bx 4.4 .
163