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