xref: /freebsd/share/man/man9/vfs_getopt.9 (revision a0b9e2e854027e6ff61fb075a1309dbc71c42b54)
1.\"
2.\" Copyright (C) 2007 Chad David <davidc@acns.ab.ca>. 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(s), this list of conditions and the following disclaimer as
9.\"    the first lines of this file unmodified other than the possible
10.\"    addition of one or more copyright notices.
11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\"    notice(s), this list of conditions and the following disclaimer in the
13.\"    documentation and/or other materials provided with the distribution.
14.\"
15.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
16.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
17.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
18.\" DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY
19.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
20.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
21.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
22.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
25.\" DAMAGE.
26.\"
27.\" $FreeBSD$
28.\"
29.Dd July 31, 2011
30.Dt VFS_GETOPT 9
31.Os
32.Sh NAME
33.Nm vfs_getopt ,
34.Nm vfs_getopts ,
35.Nm vfs_flagopt ,
36.Nm vfs_scanopt ,
37.Nm vfs_copyopt ,
38.Nm vfs_filteropt ,
39.Nm vfs_setopt ,
40.Nm vfs_setopt_part ,
41.Nm vfs_setopts
42.Nd "manipulate mount options and their values"
43.Sh SYNOPSIS
44.In sys/param.h
45.In sys/mount.h
46.Ft int
47.Fo vfs_getopt
48.Fa "struct vfsoptlist *opts" "const char *name" "void **buf" "int *len"
49.Fc
50.Ft "char *"
51.Fn vfs_getops "struct vfsoptlist *opts" "const char *name" "int *error"
52.Ft int
53.Fo vfs_flagopt
54.Fa "struct vfsoptlist *opts" "const char *name" "uint64_t *flags" "uint64_t flag"
55.Fc
56.Ft int
57.Fo vfs_scanopt
58.Fa "struct vfsoptlist *opts" "const char *name" "const char *fmt" ...
59.Fc
60.Ft int
61.Fo vfs_copyopt
62.Fa "struct vfsoptlist *opts" "const char *name" "void *dest" "int len"
63.Fc
64.Ft int
65.Fo vfs_filteropt
66.Fa "struct vfsoptlist *opts" "const char **legal"
67.Fc
68.Ft int
69.Fo vfs_setopt
70.Fa "struct vfsoptlist *opts" "const char *name" "void *value" "int len"
71.Fc
72.Ft int
73.Fo vfs_setopt_part
74.Fa "struct vfsoptlist *opts" "const char *name" "void *value" "int len"
75.Fc
76.Ft int
77.Fo vfs_setopts
78.Fa "struct vfsoptlist *opts" "const char *name" "const char *value"
79.Fc
80.Sh DESCRIPTION
81The
82.Fn vfs_getopt
83function sets
84.Fa buf
85to point to the value of the named mount option, and sets
86.Fa len
87to the length of the value if it is not
88.Dv NULL .
89The
90.Fa buf
91argument
92will point to the actual value, and does not need to be freed or released
93(and probably should not be modified).
94.Pp
95The
96.Fn vfs_getopts
97function
98returns the value of the specified option if it is a string (i.e.,
99.Dv NUL
100terminated).
101.Pp
102The
103.Fn vfs_flagopt
104function determines if an option exists.
105If the option does exist, and
106.Fa flags
107is not
108.Dv NULL ,
109.Fa flag
110is added to those already set in
111.Fa flags .
112If the option does not exist, and
113.Fa flags
114is not
115.Dv NULL ,
116.Fa flag
117is removed from those already set in
118.Fa flags .
119An example of typical usage is:
120.Bd -literal
121if (vfs_flagopt(mp->mnt_optnew, "wormlike", NULL, 0))
122	vfs_flagopt(mp->mnt_optnew, "appendok", &(mp->flags), F_APPENDOK);
123.Ed
124.Pp
125The
126.Fn vfs_scanopt
127function performs a
128.Xr vsscanf 3
129with the option's value, using the given format,
130into the specified variable arguments.
131The value must be a string (i.e.,
132.Dv NUL
133terminated).
134.Pp
135The
136.Fn vfs_copyopt
137function creates a copy of the option's value.
138The
139.Fa len
140argument must match the length of the option's value exactly
141(i.e., a larger buffer will still cause
142.Fn vfs_copyout
143to fail with
144.Er EINVAL ) .
145.Pp
146The
147.Fn vfs_filteropt
148function ensures that no unknown options were specified.
149A option is valid if its name matches one of the names in the
150list of legal names.
151An option may be prefixed with 'no', and still be considered valid.
152.Pp
153The
154.Fn vfs_setopt
155and
156.Fn vfs_setopt_part
157functions copy new data into the option's value.
158In
159.Fn vfs_setopt ,
160the
161.Fa len
162argument must match the length of the option's value exactly
163(i.e., a larger buffer will still cause
164.Fn vfs_copyout
165to fail with
166.Er EINVAL ) .
167.Pp
168The
169.Fn vfs_setopts
170function copies a new string into the option's value.
171The string, including
172.Dv NUL
173byte, must be no longer than the option's length.
174.Sh RETURN VALUES
175The
176.Fn vfs_getopt
177function returns 0 if the option was found; otherwise,
178.Er ENOENT
179is returned.
180.Pp
181The
182.Fn vfs_getops
183function returns the specified option if it is found, and is
184.Dv NUL
185terminated.
186If the option was found, but is not
187.Dv NUL
188terminated,
189.Fa error
190is set to
191.Er EINVAL
192and
193.Dv NULL
194is returned.
195If the option was not found,
196.Fa error
197is set to 0, and
198.Dv NULL
199is returned.
200.Pp
201The
202.Fn vfs_flagopt
203function returns 1 if the option was found, and 0 if it was not.
204.Pp
205The
206.Fn vfs_scanopt
207function returns 0 if the option was not found, or was not
208.Dv NUL
209terminated; otherwise, the return value of
210.Xr vsscanf 3
211is returned.
212If
213.Xr vsscanf 3
214returns 0, it will be returned unchanged; therefore, a return value of 0 does
215not always mean the option does not exist, or is not a valid string.
216.Pp
217The
218.Fn vfs_copyopt
219and
220.Fn vfs_setopt
221functions return 0 if the copy was successful,
222.Er EINVAL
223if the option was found but the lengths did not match, and
224.Er ENOENT
225if the option was not found.
226.Pp
227The
228.Fn vfs_filteropt
229function returns 0 if all of the options are legal; otherwise,
230.Er EINVAL
231is returned.
232.Pp
233The
234.Fn vfs_setopts
235function returns 0 if the copy was successful,
236.Er EINVAL
237if the option was found but the string was too long, and
238.Er ENOENT
239if the option was not found.
240.Sh AUTHORS
241.An -nosplit
242This manual page was written by
243.An Chad David Aq Mt davidc@FreeBSD.org
244and
245.An Ruslan Ermilov Aq Mt ru@FreeBSD.org .
246