[apple/libutil.git] / getmntopts.3

.\"	$NetBSD: getmntopts.3,v 1.12 2010/08/24 12:05:01 christos Exp $
.\"
.\" Copyright (c) 1994
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"	@(#)getmntopts.3	8.3 (Berkeley) 3/30/95
.\"
.Dd May 4, 2010
.Dt GETMNTOPTS 3
.Os
.Sh NAME
.Nm getmntopts
.Nd scan mount options
.Sh LIBRARY
.Lb libutil
.Sh SYNOPSIS
.In mntopts.h
.Ft mntoptparse_t
.Fn getmntopts "const char *options" "const struct mntopt *mopts" "int *flagp" "int *altflagp"
.Ft const char *
.Fn getmntoptstr "mntoptparse_t mp" "const char *opt"
.Ft long
.Fn getmntoptnum "mntoptparse_t mp" "const char *opt"
.Ft void
.Fn freemntopts "mntoptparse_t mp"
.Sh DESCRIPTION
The
.Fn getmntopts
function takes a comma separated option list and a list
of valid option names, and computes the bitmasks
corresponding to the requested set of options.
.Pp
The string
.Ar options
is broken down into a sequence of comma separated tokens.
Each token is looked up in the table described by
.Ar mopts
and the bits in
the word referenced by either
.Ar flagp
or
.Ar altflagp
(depending on the
.Dv m_altloc
field of the option's table entry)
are updated.
The flag words are not initialized by
.Fn getmntopts .
The table,
.Ar mopts ,
has the following format:
.Bd -literal
struct mntopt {
	const char *m_option;	/* option name */
	int m_inverse;		/* negative option, e.g., "dev" */
	int m_flag;		/* bit to set, e.g., MNT_RDONLY */
	int m_altloc;		/* use altflagp rather than flagp */
};
.Ed
.Pp
The members of this structure are:
.Bl -tag -width m_inverse
.It Fa m_option
the option name,
for example
.Dq suid .
.It Fa m_inverse
tells
.Fn getmntopts
that the name has the inverse meaning of the bit.
For example,
.Dq suid
is the string, whereas the mount flag is
.Dv MNT_NOSUID .
In this case, the sense of the string and the flag
are inverted, so the
.Fa m_inverse
flag should be set.
.It Fa m_flag
the value of the bit to be set or cleared in
the flag word when the option is recognized.
The bit is set when the option is discovered,
but cleared if the option name was preceded
by the letters
.Dq no .
The
.Fa m_inverse
flag causes these two operations to be reversed.
.It Fa m_altloc
the bit should be set or cleared in
.Ar altflagp
rather than
.Ar flagp .
.El
.Pp
Each of the user visible
.Dv MNT_
flags has a corresponding
.Dv MOPT_
macro which defines an appropriate
.Li "struct mntopt"
entry.
To simplify the program interface and ensure consistency across all
programs, a general purpose macro,
.Dv MOPT_STDOPTS ,
is defined which contains an entry for all the generic VFS options:
.Bd -literal -offset indent
MOPT_USERQUOTA,
MOPT_GROUPQUOTA,
MOPT_FSTAB_COMPAT,
MOPT_NODEV,
MOPT_NOEXEC,
MOPT_NOSUID,
MOPT_RDONLY,
MOPT_UNION,
MOPT_BROWSE,
MOPT_AUTOMOUNTED,
MOPT_DEFWRITE,
MOPT_NOATIME,
MOPT_PERMISSIONS,
MOPT_IGNORE_OWNERSHIP,
MOPT_QUARANTINE,
MOPT_CPROTECT
.Ed
.Pp
In addition, the macros
.Dv MOPT_FORCE
and
.Dv MOPT_UPDATE
exist to enable the
.Dv MNT_FORCE
and
.Dv MNT_UPDATE
flags to be set.
Finally, the table must be terminated by an entry with a
.Dv NULL
first element.
.Pp
.Fn getmntopts
returns a
.Li "mntoptparse_t"
handle that can be used in subsequent
.Fn getmntoptstr
and
.Fn getmntoptnum
calls to fetch a value for an option and that must be freed with a call
to
.Fn freemntopts .
If an error occurred, then if the external integer value
.Va getmnt_silent
is zero then
.Fn getmntopts
prints an error message and exits;
if
.Va getmnt_silent
is non-zero then
.Fn getmntopts
returns
.Dv NULL .
.Pp
The
.Fn getmntoptstr
function returns the string value of the named option, if such a value
was set in the option string.
If the value was not set, then if the external integer value
.Va getmnt_silent
is zero then
.Fn getmntoptstr
prints an error message and exits;
if
.Va getmnt_silent
is non-zero then
.Fn getmntoptstr
returns
.Dv NULL .
.Pp
The
.Fn getmntoptnum
returns the long value of the named option, if such a value was set in the
option string.
If the value was not set, or could not be converted from a string to a
long, then if the external integer value
.Va getmnt_silent
is zero then
.Fn getmntoptnum
prints an error message and exits;
if
.Va getmnt_silent
is non-zero then
.Fn getmntoptnum
returns \-1.
.Pp
The
.Fn freemntopts
frees the storage used by
.Fn getmntopts .
.Sh RETURN VALUES
.Fn getmntopts
returns
.Dv NULL
if an error occurred.
Note that some bits may already have been set in
.Va flagp
and
.Va altflagp
even if
.Dv NULL
is returned.
.Fn getmntoptstr
returns
.Dv NULL
if an error occurred.
.Fn getmntoptnum
returns \-1 if an error occurred.
.Sh EXAMPLES
Most commands will use the standard option set.
Local filesystems which support the
.Dv MNT_UPDATE
flag, would also have an
.Dv MOPT_UPDATE
entry.
This can be declared and used as follows:
.Bd -literal -offset indent
#include \*[Lt]mntopts.h\*[Gt]

static const struct mntopt mopts[] = {
	MOPT_STDOPTS,
	MOPT_UPDATE,
	{ NULL }
};

\&...

long val;
mntoptparse_t mp;
mntflags = mntaltflags = 0;

\&...

mp = getmntopts(options, mopts, \*[Am]mntflags, \*[Am]mntaltflags);

if (mp == NULL)
	err(EXIT_FAILURE, "getmntopts");

\&...

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