1.\" Copyright (c) 2023 Marshall Kirk McKusick 2.\" Copyright (c) 1994 The Regents of the University of California. 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, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.Dd January 19, 2023 26.Dt MNTOPTS 3 27.Os 28.Sh NAME 29.Nm getmntopts , 30.Nm getmntpoint , 31.Nm chkdoreload , 32.Nm build_iovec , 33.Nm build_iovec_argf , 34.Nm free_iovec , 35.Nm checkpath , 36.Nm rmslashes 37.Nd "mount point operations" 38.Sh SYNOPSIS 39.In mntopts.h 40.Ft void 41.Fo getmntopts 42.Fa "const char *options" "const struct mntopt *mopts" 43.Fa "int *flagp" "int *altflagp" 44.Fc 45.Ft struct statfs * 46.Fn getmntpoint "const char *name" 47.Ft int 48.Fo chkdoreload 49.Fa "struct statfs *mntp" 50.Fa "void (*prtmsg)(const char *fmt, ...)" 51.Fc 52.Ft void 53.Fo build_iovec 54.Fa "struct iovec **iov" "int *iovlen" "const char *name" "void *val" 55.Fa "size_t len" 56.Fc 57.Ft void 58.Fo build_iovec_argf 59.Fa "struct iovec **iov" "int *iovlen" "const char *name" 60.Fa "const char *fmt" "..." 61.Fc 62.Ft void 63.Fn free_iovec "struct iovec **iov" "int *iovlen" 64.Ft int 65.Fn checkpath "const char *path" "char *resolved" 66.Ft void 67.Fn rmslashes "char *rrpin" "char *rrpout" 68.Sh DESCRIPTION 69The 70.Nm mntopts 71functions support operations associated with a mount point. 72For historic reasons are in a file in the sources for the 73.Xr mount 8 74program. 75Thus, to access them the following lines need to be added to the 76.Nm Makefile 77of the program wanting to use them: 78.Bd -literal 79SRCS+= getmntopts.c 80MOUNT= ${SRCTOP}/sbin/mount 81CFLAGS+= -I${MOUNT} 82\&.PATH: ${MOUNT} 83.Ed 84.Pp 85The 86.Fn getmntopts 87function takes a comma separated option list and a list 88of valid option names, and computes the bitmask 89corresponding to the requested set of options. 90.Pp 91The string 92.Fa options 93is broken down into a sequence of comma separated tokens. 94Each token is looked up in the table described by 95.Fa mopts 96and the bits in 97the word referenced by either 98.Fa flagp 99or 100.Fa altflagp 101(depending on the 102.Va m_altloc 103field of the option's table entry) 104are updated. 105The flag words are not initialized by 106.Fn getmntopts . 107The table, 108.Fa mopts , 109has the following format: 110.Bd -literal 111struct mntopt { 112 char *m_option; /* option name */ 113 int m_inverse; /* is this a negative option, e.g., "dev" */ 114 int m_flag; /* bit to set, e.g., MNT_RDONLY */ 115 int m_altloc; /* non-zero to use altflagp rather than flagp */ 116}; 117.Ed 118.Pp 119The members of this structure are: 120.Bl -tag -width m_inverse 121.It Va m_option 122the option name, 123for example 124.Dq Li suid . 125.It Va m_inverse 126tells 127.Fn getmntopts 128that the name has the inverse meaning of the 129bit. 130For example, 131.Dq Li suid 132is the string, whereas the 133mount flag is 134.Dv MNT_NOSUID . 135In this case, the sense of the string and the flag 136are inverted, so the 137.Va m_inverse 138flag should be set. 139.It Va m_flag 140the value of the bit to be set or cleared in 141the flag word when the option is recognized. 142The bit is set when the option is discovered, 143but cleared if the option name was preceded 144by the letters 145.Dq Li no . 146The 147.Va m_inverse 148flag causes these two operations to be reversed. 149.It Va m_altloc 150the bit should be set or cleared in 151.Fa altflagp 152rather than 153.Fa flagp . 154.El 155.Pp 156Each of the user visible 157.Dv MNT_ 158flags has a corresponding 159.Dv MOPT_ 160macro which defines an appropriate 161.Vt "struct mntopt" 162entry. 163To simplify the program interface and ensure consistency across all 164programs, a general purpose macro, 165.Dv MOPT_STDOPTS , 166is defined which 167contains an entry for all the generic VFS options. 168In addition, the macros 169.Dv MOPT_FORCE 170and 171.Dv MOPT_UPDATE 172exist to enable the 173.Dv MNT_FORCE 174and 175.Dv MNT_UPDATE 176flags to be set. 177Finally, the table must be terminated by an entry with a 178.Dv NULL 179first element. 180.Pp 181The 182.Fn getmntpoint 183function takes the pathname of a possible mount point 184or of a device (with or without 185.Pa /dev/ 186prepended to it). 187If the pathname is a directory or a file, 188.Fn getmntpoint 189checks to see if the mount point currently has a filesystem 190mounted on it. 191If the pathname is a device, 192.Fn getmntpoint 193checks to see if it is currently mounted. 194If there is an associated mount, a pointer to a 195.Vt "struct statfs" 196is returned. 197The returned result is stored in a static buffer that is over-written 198each time the 199.Fn getmntpoint 200function or the 201.Xr getmntinfo 3 202library routine is called. 203If no mount is found, NULL is returned. 204.Pp 205The 206.Fn chkdoreload 207function takes a pointer to a 208.Vt "struct statfs" . 209If the filesystem associated with the mount point is mounted read-only, 210.Fn chkdoreload 211requests the filesystem to reload all of its metadata from its backing store. 212The second parameter is the function to call to print an error message 213if the reload fails. 214If no error message is desired, a 215.Dv NULL 216can be passed as the second argument. 217The 218.Fn chkdoreload 219function returns zero on success or non-zero on failure. 220.Pp 221The 222.Fn build_iovec 223function adds a parameter to a list of parameters to be passed to the 224.Xr nmount 2 225system call. 226The parameter list is built up in 227.Va iov 228and its length is kept in 229.Va iovlen . 230Before the first call to 231.Fn build_iovec , 232.Va iov 233should be set to 234.Dv NULL 235and 236.Va iovlen 237should be set to 0. 238The parameter name is passed in 239.Va name . 240The value of the parameter name is pointed to by 241.Va val . 242The size of the value is passed in 243.Va len . 244If the value is a string, a 245.Va len 246of -1 is passed to indicate that the length should be determined using 247.Xr strlen 3 . 248If the parameter has no value, 249.Va name 250should be 251.Dv NULL 252and 253.Va len 254should be 0. 255.Pp 256The 257.Fn build_iovec_argf 258function adds a formatted parameter to a list of parameters to be passed 259to the 260.Xr nmount 2 261system call. 262The parameter list is built up in 263.Va iov 264and its length is kept in 265.Va iovlen . 266Before the first call to 267.Fn build_iovec_argf , 268.Va iov 269should be set to 270.Dv NULL 271and 272.Va iovlen 273should be set to 0. 274The parameter name is passed in 275.Va name . 276The value of the parameter name is described by a format string pointed to by 277.Va fmt . 278If the parameter has no value, 279.Va name 280should be 281.Dv NULL . 282.Pp 283The 284.Fn free_iovec 285function frees the memory in the 286.Va iov 287vector of the length specified in 288.Va iovlen 289that was previously allocated by the 290.Fn build_iovec 291and / or 292.Fn build_iovec_argf 293functions. 294The 295.Va iov 296is set to 297.Dv NULL 298and the 299.Va iovlen 300is set to 0 to indicate that the space has been freed. 301.Pp 302The 303.Fn checkpath 304function uses 305.Xr realpath 3 306to verify that its 307.Va path 308argument is valid and references a directory. 309The 310.Fn checkpath 311function returns zero on success or non-zero on failure. 312.Pp 313The 314.Fn rmslashes 315function removes all double slashes and trailing slashes from its 316.Va rrpin 317pathname parameter and returns the resulting pathname in its 318.Va rrpout 319parameter. 320.Sh EXAMPLES 321Most commands will use the standard option set. 322Local file systems which support the 323.Dv MNT_UPDATE 324flag, would also have an 325.Dv MOPT_UPDATE 326entry. 327This can be declared and used as follows: 328.Bd -literal 329#include "mntopts.h" 330 331struct mntopt mopts[] = { 332 MOPT_STDOPTS, 333 MOPT_UPDATE, 334 { NULL } 335}; 336 337 ... 338 mntflags = mntaltflags = 0; 339 ... 340 getmntopts(options, mopts, &mntflags, &mntaltflags); 341 ... 342.Ed 343.Sh DIAGNOSTICS 344If the external integer variable 345.Va getmnt_silent 346is zero, then the 347.Fn getmntopts 348function displays an error message and exits if an 349unrecognized option is encountered. 350Otherwise unrecognized options are silently ignored. 351By default 352.Va getmnt_silent 353is zero. 354.Sh SEE ALSO 355.Xr err 3 , 356.Xr mount 8 , 357.Xr nmount 8 358.Sh HISTORY 359The 360.Fn getmntopts 361function appeared in 362.Bx 4.4 . 363The 364.Fn build_iovec , 365.Fn build_iovec_argf , 366.Fn free_iovec , 367.Fn checkpath , 368and 369.Fn rmslashes 370functions were added with 371.Xr nmount 8 372in 373.Fx 5.0 . 374The 375.Fn getmntpoint 376and 377.Fn chkdoreload 378functions were added in 379.Fx 13.2 . 380