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 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 .