sbin/mount/mntopts.3

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