share/man/man9/vfs_getopt.9

   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
  81 The
  82 .Fn vfs_getopt
  83 function sets
  84 .Fa buf
  85 to point to the value of the named mount option, and sets
  86 .Fa len
  87 to the length of the value if it is not
  88 .Dv NULL .
  89 The
  90 .Fa buf
  91 argument
  92 will point to the actual value, and does not need to be freed or released
  93 (and probably should not be modified).
  94 .Pp
  95 The
  96 .Fn vfs_getopts
  97 function
  98 returns the value of the specified option if it is a string (i.e.,
  99 .Dv NUL
 100 terminated).
 101 .Pp
 102 The
 103 .Fn vfs_flagopt
 104 function determines if an option exists.
 105 If the option does exist, and
 106 .Fa flags
 107 is not
 108 .Dv NULL ,
 109 .Fa flag
 110 is added to those already set in
 111 .Fa flags .
 112 If the option does not exist, and
 113 .Fa flags
 114 is not
 115 .Dv NULL ,
 116 .Fa flag
 117 is removed from those already set in
 118 .Fa flags .
 119 An example of typical usage is:
 120 .Bd -literal
 121 if (vfs_flagopt(mp->mnt_optnew, "wormlike", NULL, 0))
 122         vfs_flagopt(mp->mnt_optnew, "appendok", &(mp->flags), F_APPENDOK);
 123 .Ed
 124 .Pp
 125 The
 126 .Fn vfs_scanopt
 127 function performs a
 128 .Xr vsscanf 3
 129 with the option's value, using the given format,
 130 into the specified variable arguments.
 131 The value must be a string (i.e.,
 132 .Dv NUL
 133 terminated).
 134 .Pp
 135 The
 136 .Fn vfs_copyopt
 137 function creates a copy of the option's value.
 138 The
 139 .Fa len
 140 argument must match the length of the option's value exactly
 141 (i.e., a larger buffer will still cause
 142 .Fn vfs_copyout
 143 to fail with
 144 .Er EINVAL ) .
 145 .Pp
 146 The
 147 .Fn vfs_filteropt
 148 function ensures that no unknown options were specified.
 149 A option is valid if its name matches one of the names in the
 150 list of legal names.
 151 An option may be prefixed with 'no', and still be considered valid.
 152 .Pp
 153 The
 154 .Fn vfs_setopt
 155 and
 156 .Fn vfs_setopt_part
 157 functions copy new data into the option's value.
 158 In
 159 .Fn vfs_setopt ,
 160 the
 161 .Fa len
 162 argument must match the length of the option's value exactly
 163 (i.e., a larger buffer will still cause
 164 .Fn vfs_copyout
 165 to fail with
 166 .Er EINVAL ) .
 167 .Pp
 168 The
 169 .Fn vfs_setopts
 170 function copies a new string into the option's value.
 171 The string, including
 172 .Dv NUL
 173 byte, must be no longer than the option's length.
 174 .Sh RETURN VALUES
 175 The
 176 .Fn vfs_getopt
 177 function returns 0 if the option was found; otherwise,
 178 .Er ENOENT
 179 is returned.
 180 .Pp
 181 The
 182 .Fn vfs_getops
 183 function returns the specified option if it is found, and is
 184 .Dv NUL
 185 terminated.
 186 If the option was found, but is not
 187 .Dv NUL
 188 terminated,
 189 .Fa error
 190 is set to
 191 .Er EINVAL
 192 and
 193 .Dv NULL
 194 is returned.
 195 If the option was not found,
 196 .Fa error
 197 is set to 0, and
 198 .Dv NULL
 199 is returned.
 200 .Pp
 201 The
 202 .Fn vfs_flagopt
 203 function returns 1 if the option was found, and 0 if it was not.
 204 .Pp
 205 The
 206 .Fn vfs_scanopt
 207 function returns 0 if the option was not found, or was not
 208 .Dv NUL
 209 terminated; otherwise, the return value of
 210 .Xr vsscanf 3
 211 is returned.
 212 If
 213 .Xr vsscanf 3
 214 returns 0, it will be returned unchanged; therefore, a return value of 0 does
 215 not always mean the option does not exist, or is not a valid string.
 216 .Pp
 217 The
 218 .Fn vfs_copyopt
 219 and
 220 .Fn vfs_setopt
 221 functions return 0 if the copy was successful,
 222 .Er EINVAL
 223 if the option was found but the lengths did not match, and
 224 .Er ENOENT
 225 if the option was not found.
 226 .Pp
 227 The
 228 .Fn vfs_filteropt
 229 function returns 0 if all of the options are legal; otherwise,
 230 .Er EINVAL
 231 is returned.
 232 .Pp
 233 The
 234 .Fn vfs_setopts
 235 function returns 0 if the copy was successful,
 236 .Er EINVAL
 237 if the option was found but the string was too long, and
 238 .Er ENOENT
 239 if the option was not found.
 240 .Sh AUTHORS
 241 .An -nosplit
 242 This manual page was written by
 243 .An Chad David Aq davidc@FreeBSD.org
 244 and
 245 .An Ruslan Ermilov Aq ru@FreeBSD.org .