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