| blob | c3932091817c0248013235d3c0bc3384192ff263 |
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 February 28, 2007
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 .Nd "manipulate mount options and their values"
40 .Sh SYNOPSIS
41 .In sys/param.h
42 .In sys/mount.h
43 .Ft int
44 .Fo vfs_getopt
45 .Fa "struct vfsoptlist *opts" "const char *name" "void **buf" "int *len"
46 .Fc
47 .Ft "char *"
48 .Fn vfs_getops "struct vfsoptlist *opts" "const char *name" "int *error"
49 .Ft int
50 .Fo vfs_flagopt
51 .Fa "struct vfsoptlist *opts" "const char *name" "u_int *flags" "u_int flag"
52 .Fc
53 .Ft int
54 .Fo vfs_scanopt
55 .Fa "struct vfsoptlist *opts" "const char *name" "const char *fmt" ...
56 .Fc
57 .Ft int
58 .Fo vfs_copyopt
59 .Fa "struct vfsoptlist *opts" "const char *name" "void *dest" "int len"
60 .Fc
61 .Ft int
62 .Fo vfs_filteropt
63 .Fa "struct vfsoptlist *opts" "const char **legal"
64 .Fc
65 .Sh DESCRIPTION
66 The
67 .Fn vfs_getopt
68 function sets
69 .Fa buf
70 to point to the value of the named mount option, and sets
71 .Fa len
72 to the length of the value if it is not
73 .Dv NULL .
74 The
75 .Fa buf
76 argument
77 will point to the actual value, and does not need to be freed or released
78 (and probably should not be modified).
79 .Pp
80 The
81 .Fn vfs_getopts
82 function
83 returns the value of the specified option if it is a string (i.e.,
84 .Dv NUL
85 terminated).
86 .Pp
87 The
88 .Fn vfs_flagopt
89 function determines if an option exists.
90 If the option does exist, and
91 .Fa flags
92 is not
93 .Dv NULL ,
94 .Fa flag
95 is added to those already set in
96 .Fa flags .
97 If the option does not exist, and
98 .Fa flags
99 is not
100 .Dv NULL ,
101 .Fa flag
102 is removed from those already set in
103 .Fa flags .
104 An example of typical usage is:
105 .Bd -literal
106 if (vfs_flagopt(mp->mnt_optnew, "wormlike", NULL, 0))
107 vfs_flagopt(mp->mnt_optnew, "appendok", &(mp->flags), F_APPENDOK);
108 .Ed
109 .Pp
110 The
111 .Fn vfs_scanopt
112 function performs a
113 .Xr vsscanf 3
114 with the options value, using the given format,
115 into the specified variable arguments.
116 The value must be a string (i.e.,
117 .Dv NUL
118 terminated).
119 .Pp
120 The
121 .Fn vfs_copyopt
122 function creates a copy of the options value.
123 The
124 .Fa len
125 argument must match the length of the options value exactly
126 (i.e., a larger buffer will still cause
127 .Fn vfs_copyout
128 to fail with
129 .Er EINVAL ) .
130 .Pp
131 The
132 .Fn vfs_filteropt
133 function ensures that no unknown options were specified.
134 A option is valid if its name matches one of the names in the
135 list of legal names.
136 An option may be prefixed with 'no', and still be considered valid.
137 .Sh RETURN VALUES
138 The
139 .Fn vfs_getopt
140 function returns 0 if the option was found; otherwise,
141 .Er ENOENT
142 is returned.
143 .Pp
144 The
145 .Fn vfs_getops
146 function returns the specified option if it is found, and is
147 .Dv NUL
148 terminated.
149 If the option was found, but is not
150 .Dv NUL
151 terminated,
152 .Fa error
153 is set to
154 .Er EINVAL
155 and
156 .Dv NULL
157 is returned.
158 If the option was not found,
159 .Fa error
160 is set to 0, and
161 .Dv NULL
162 is returned.
163 .Pp
164 The
165 .Fn vfs_flagopt
166 function returns 1 if the option was found, and 0 if it was not.
167 .Pp
168 The
169 .Fn vfs_scanopt
170 function returns 0 if the option was not found, or was not
171 .Dv NUL
172 terminated; otherwise, the return value of
173 .Xr vsscanf 3
174 is returned.
175 If
176 .Xr vsscanf 3
177 returns 0, it will be returned unchanged; therefore, a return value of 0 does
178 not always mean the option does not exist, or is not a valid string.
179 .Pp
180 The
181 .Fn vfs_copyopt
182 function returns 0 if the copy was successful,
183 .Er EINVAL
184 if the option was found but the lengths did not match, and
185 .Er ENOENT
186 if the option was not found.
187 .Pp
188 The
189 .Fn vfs_filteropt
190 function returns 0 if all of the options are legal; otherwise,
191 .Er EINVAL
192 is returned.
193 .Sh AUTHORS
194 .An -nosplit
195 This manual page was written by
196 .An Chad David Aq davidc@FreeBSD.org
197 and
198 .An Ruslan Ermilov Aq ru@FreeBSD.org .