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