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