xref: /freebsd/share/man/man9/vfs_getopt.9 (revision e0c4386e) 
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.Dd July 31, 2011
28.Dt VFS_GETOPT 9
29.Os
30.Sh NAME
31.Nm vfs_getopt ,
32.Nm vfs_getopts ,
33.Nm vfs_flagopt ,
34.Nm vfs_scanopt ,
35.Nm vfs_copyopt ,
36.Nm vfs_filteropt ,
37.Nm vfs_setopt ,
38.Nm vfs_setopt_part ,
39.Nm vfs_setopts
40.Nd "manipulate mount options and their values"
41.Sh SYNOPSIS
42.In sys/param.h
43.In sys/mount.h
44.Ft int
45.Fo vfs_getopt
46.Fa "struct vfsoptlist *opts" "const char *name" "void **buf" "int *len"
47.Fc
48.Ft "char *"
49.Fn vfs_getops "struct vfsoptlist *opts" "const char *name" "int *error"
50.Ft int
51.Fo vfs_flagopt
52.Fa "struct vfsoptlist *opts" "const char *name" "uint64_t *flags" "uint64_t flag"
53.Fc
54.Ft int
55.Fo vfs_scanopt
56.Fa "struct vfsoptlist *opts" "const char *name" "const char *fmt" ...
57.Fc
58.Ft int
59.Fo vfs_copyopt
60.Fa "struct vfsoptlist *opts" "const char *name" "void *dest" "int len"
61.Fc
62.Ft int
63.Fo vfs_filteropt
64.Fa "struct vfsoptlist *opts" "const char **legal"
65.Fc
66.Ft int
67.Fo vfs_setopt
68.Fa "struct vfsoptlist *opts" "const char *name" "void *value" "int len"
69.Fc
70.Ft int
71.Fo vfs_setopt_part
72.Fa "struct vfsoptlist *opts" "const char *name" "void *value" "int len"
73.Fc
74.Ft int
75.Fo vfs_setopts
76.Fa "struct vfsoptlist *opts" "const char *name" "const char *value"
77.Fc
78.Sh DESCRIPTION
79The
80.Fn vfs_getopt
81function sets
82.Fa buf
83to point to the value of the named mount option, and sets
84.Fa len
85to the length of the value if it is not
86.Dv NULL .
87The
88.Fa buf
89argument
90will point to the actual value, and does not need to be freed or released
91(and probably should not be modified).
92.Pp
93The
94.Fn vfs_getopts
95function
96returns the value of the specified option if it is a string (i.e.,
97.Dv NUL
98terminated).
99.Pp
100The
101.Fn vfs_flagopt
102function determines if an option exists.
103If the option does exist, and
104.Fa flags
105is not
106.Dv NULL ,
107.Fa flag
108is added to those already set in
109.Fa flags .
110If the option does not exist, and
111.Fa flags
112is not
113.Dv NULL ,
114.Fa flag
115is removed from those already set in
116.Fa flags .
117An example of typical usage is:
118.Bd -literal
119if (vfs_flagopt(mp->mnt_optnew, "wormlike", NULL, 0))
120	vfs_flagopt(mp->mnt_optnew, "appendok", &(mp->flags), F_APPENDOK);
121.Ed
122.Pp
123The
124.Fn vfs_scanopt
125function performs a
126.Xr vsscanf 3
127with the option's value, using the given format,
128into the specified variable arguments.
129The value must be a string (i.e.,
130.Dv NUL
131terminated).
132.Pp
133The
134.Fn vfs_copyopt
135function creates a copy of the option's value.
136The
137.Fa len
138argument must match the length of the option's value exactly
139(i.e., a larger buffer will still cause
140.Fn vfs_copyout
141to fail with
142.Er EINVAL ) .
143.Pp
144The
145.Fn vfs_filteropt
146function ensures that no unknown options were specified.
147A option is valid if its name matches one of the names in the
148list of legal names.
149An option may be prefixed with 'no', and still be considered valid.
150.Pp
151The
152.Fn vfs_setopt
153and
154.Fn vfs_setopt_part
155functions copy new data into the option's value.
156In
157.Fn vfs_setopt ,
158the
159.Fa len
160argument must match the length of the option's value exactly
161(i.e., a larger buffer will still cause
162.Fn vfs_copyout
163to fail with
164.Er EINVAL ) .
165.Pp
166The
167.Fn vfs_setopts
168function copies a new string into the option's value.
169The string, including
170.Dv NUL
171byte, must be no longer than the option's length.
172.Sh RETURN VALUES
173The
174.Fn vfs_getopt
175function returns 0 if the option was found; otherwise,
176.Er ENOENT
177is returned.
178.Pp
179The
180.Fn vfs_getops
181function returns the specified option if it is found, and is
182.Dv NUL
183terminated.
184If the option was found, but is not
185.Dv NUL
186terminated,
187.Fa error
188is set to
189.Er EINVAL
190and
191.Dv NULL
192is returned.
193If the option was not found,
194.Fa error
195is set to 0, and
196.Dv NULL
197is returned.
198.Pp
199The
200.Fn vfs_flagopt
201function returns 1 if the option was found, and 0 if it was not.
202.Pp
203The
204.Fn vfs_scanopt
205function returns 0 if the option was not found, or was not
206.Dv NUL
207terminated; otherwise, the return value of
208.Xr vsscanf 3
209is returned.
210If
211.Xr vsscanf 3
212returns 0, it will be returned unchanged; therefore, a return value of 0 does
213not always mean the option does not exist, or is not a valid string.
214.Pp
215The
216.Fn vfs_copyopt
217and
218.Fn vfs_setopt
219functions return 0 if the copy was successful,
220.Er EINVAL
221if the option was found but the lengths did not match, and
222.Er ENOENT
223if the option was not found.
224.Pp
225The
226.Fn vfs_filteropt
227function returns 0 if all of the options are legal; otherwise,
228.Er EINVAL
229is returned.
230.Pp
231The
232.Fn vfs_setopts
233function returns 0 if the copy was successful,
234.Er EINVAL
235if the option was found but the string was too long, and
236.Er ENOENT
237if the option was not found.
238.Sh AUTHORS
239.An -nosplit
240This manual page was written by
241.An Chad David Aq Mt davidc@FreeBSD.org
242and
243.An Ruslan Ermilov Aq Mt ru@FreeBSD.org .
244