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 May 19, 2024 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_getopts "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_getopts 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