lib/libc/sys/mount.2

   1 .\" Copyright (c) 1980, 1989, 1993
   2 .\"     The Regents of the University of California.  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, 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 .\" 3. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)mount.2     8.3 (Berkeley) 5/24/95
  29 .\"
  30 .Dd March 30, 2020
  31 .Dt MOUNT 2
  32 .Os
  33 .Sh NAME
  34 .Nm mount ,
  35 .Nm nmount ,
  36 .Nm unmount
  37 .Nd mount or dismount a file system
  38 .Sh LIBRARY
  39 .Lb libc
  40 .Sh SYNOPSIS
  41 .In sys/param.h
  42 .In sys/mount.h
  43 .Ft int
  44 .Fn mount "const char *type" "const char *dir" "int flags" "void *data"
  45 .Ft int
  46 .Fn unmount "const char *dir" "int flags"
  47 .In sys/uio.h
  48 .Ft int
  49 .Fn nmount "struct iovec *iov" "u_int niov" "int flags"
  50 .Sh DESCRIPTION
  51 The
  52 .Fn mount
  53 system call grafts
  54 a file system object onto the system file tree
  55 at the point
  56 .Fa dir .
  57 The argument
  58 .Fa data
  59 describes the file system object to be mounted.
  60 The argument
  61 .Fa type
  62 tells the kernel how to interpret
  63 .Fa data
  64 (See
  65 .Fa type
  66 below).
  67 The contents of the file system
  68 become available through the new mount point
  69 .Fa dir .
  70 Any files in
  71 .Fa dir
  72 at the time
  73 of a successful mount are swept under the carpet so to speak, and
  74 are unavailable until the file system is unmounted.
  75 .Pp
  76 The
  77 .Fn nmount
  78 system call behaves similarly to
  79 .Fn mount ,
  80 except that the mount options (file system type name, device to mount,
  81 mount-point name, etc.) are passed as an array of name-value pairs
  82 in the array
  83 .Fa iov ,
  84 containing
  85 .Fa niov
  86 elements.
  87 The following options are required by all file systems:
  88 .Bl -column fstype -offset indent
  89 .It
  90 .Li fstype Ta file system type name (e.g., Dq Li procfs )
  91 .It
  92 .Li fspath Ta mount point pathname (e.g., Dq Li /proc )
  93 .El
  94 .Pp
  95 Depending on the file system type, other options may be
  96 recognized or required;
  97 for example, most disk-based file systems require a
  98 .Dq Li from
  99 option containing the pathname of a special device
 100 in addition to the options listed above.
 101 .Pp
 102 By default only the super-user may call the
 103 .Fn mount
 104 system call.
 105 This restriction can be removed by setting the
 106 .Va vfs.usermount
 107 .Xr sysctl 8
 108 variable
 109 to a non-zero value; see the BUGS section for more information.
 110 .Pp
 111 The following
 112 .Fa flags
 113 may be specified to
 114 suppress default semantics which affect file system access.
 115 .Bl -tag -width MNT_SYNCHRONOUS
 116 .It Dv MNT_RDONLY
 117 The file system should be treated as read-only;
 118 even the super-user may not write on it.
 119 Specifying MNT_UPDATE without this option will upgrade
 120 a read-only file system to read/write.
 121 .It Dv MNT_NOEXEC
 122 Do not allow files to be executed from the file system.
 123 .It Dv MNT_NOSUID
 124 Do not honor setuid or setgid bits on files when executing them.
 125 This flag is set automatically when the caller is not the super-user.
 126 .It Dv MNT_NOATIME
 127 Disable update of file access times.
 128 .It Dv MNT_SNAPSHOT
 129 Create a snapshot of the file system.
 130 This is currently only supported on UFS2 file systems, see
 131 .Xr mksnap_ffs 8
 132 for more information.
 133 .It Dv MNT_SUIDDIR
 134 Directories with the SUID bit set chown new files to their own owner.
 135 This flag requires the SUIDDIR option to have been compiled into the kernel
 136 to have any effect.
 137 See the
 138 .Xr mount 8
 139 and
 140 .Xr chmod 2
 141 pages for more information.
 142 .It Dv MNT_SYNCHRONOUS
 143 All I/O to the file system should be done synchronously.
 144 .It Dv MNT_ASYNC
 145 All I/O to the file system should be done asynchronously.
 146 .It Dv MNT_FORCE
 147 Force a read-write mount even if the file system appears to be unclean.
 148 Dangerous.
 149 Together with
 150 .Dv MNT_UPDATE
 151 and
 152 .Dv MNT_RDONLY ,
 153 specify that the file system is to be forcibly downgraded to a read-only
 154 mount even if some files are open for writing.
 155 .It Dv MNT_NOCLUSTERR
 156 Disable read clustering.
 157 .It Dv MNT_NOCLUSTERW
 158 Disable write clustering.
 159 .It Dv MNT_NOCOVER
 160 Do not mount over the root of another mount point.
 161 .It Dv MNT_EMPTYDIR
 162 Require an empty directory for the mount point directory.
 163 .El
 164 .Pp
 165 The flag
 166 .Dv MNT_UPDATE
 167 indicates that the mount command is being applied
 168 to an already mounted file system.
 169 This allows the mount flags to be changed without requiring
 170 that the file system be unmounted and remounted.
 171 Some file systems may not allow all flags to be changed.
 172 For example,
 173 many file systems will not allow a change from read-write to read-only.
 174 .Pp
 175 The flag
 176 .Dv MNT_RELOAD
 177 causes the vfs subsystem to update its data structures pertaining to
 178 the specified already mounted file system.
 179 .Pp
 180 The
 181 .Fa type
 182 argument names the file system.
 183 The types of file systems known to the system can be obtained with
 184 .Xr lsvfs 1 .
 185 .Pp
 186 The
 187 .Fa data
 188 argument
 189 is a pointer to a structure that contains the type
 190 specific arguments to mount.
 191 The format for these argument structures is described in the
 192 manual page for each file system.
 193 By convention file system manual pages are named
 194 by prefixing ``mount_'' to the name of the file system as returned by
 195 .Xr lsvfs 1 .
 196 Thus the
 197 .Tn NFS
 198 file system is described by the
 199 .Xr mount_nfs 8
 200 manual page.
 201 It should be noted that a manual page for default
 202 file systems, known as UFS and UFS2, does not exist.
 203 .Pp
 204 The
 205 .Fn unmount
 206 system call disassociates the file system from the specified
 207 mount point
 208 .Fa dir .
 209 .Pp
 210 The
 211 .Fa flags
 212 argument may include
 213 .Dv MNT_FORCE
 214 to specify that the file system should be forcibly unmounted
 215 even if files are still active.
 216 Active special devices continue to work,
 217 but any further accesses to any other active files result in errors
 218 even if the file system is later remounted.
 219 .Pp
 220 If the
 221 .Dv MNT_BYFSID
 222 flag is specified,
 223 .Fa dir
 224 should instead be a file system ID encoded as
 225 .Dq Li FSID : Ns Ar val0 : Ns Ar val1 ,
 226 where
 227 .Ar val0
 228 and
 229 .Ar val1
 230 are the contents of the
 231 .Vt fsid_t
 232 .Va val[]
 233 array in decimal.
 234 The file system that has the specified file system ID will be unmounted.
 235 .Sh RETURN VALUES
 236 .Rv -std
 237 .Sh ERRORS
 238 The
 239 .Fn mount
 240 and
 241 .Fn nmount
 242 system calls will fail when one of the following occurs:
 243 .Bl -tag -width Er
 244 .It Bq Er EPERM
 245 The caller is neither the super-user nor the owner of
 246 .Fa dir .
 247 .It Bq Er ENAMETOOLONG
 248 A component of a pathname exceeded 255 characters,
 249 or the entire length of a path name exceeded 1023 characters.
 250 .It Bq Er ELOOP
 251 Too many symbolic links were encountered in translating a pathname.
 252 .It Bq Er ENOENT
 253 A component of
 254 .Fa dir
 255 does not exist.
 256 .It Bq Er ENOTDIR
 257 A component of
 258 .Fa name
 259 is not a directory,
 260 or a path prefix of
 261 .Fa special
 262 is not a directory.
 263 .It Bq Er EBUSY
 264 Another process currently holds a reference to
 265 .Fa dir .
 266 .It Bq Er EBUSY
 267 The
 268 .Dv MNT_NOCOVER
 269 option was given, and the requested mount point
 270 is already the root of another mount point.
 271 .It Bq Er EFAULT
 272 The
 273 .Fa dir
 274 argument
 275 points outside the process's allocated address space.
 276 .It Bq Er EIO
 277 An I/O error occurred while reading data from
 278 .Fa special .
 279 .It Bq Er EINTEGRITY
 280 The backing store for
 281 .Fa special
 282 detected corrupted data while reading.
 283 .El
 284 .Pp
 285 The following errors can occur for a
 286 .Em ufs
 287 file system mount:
 288 .Bl -tag -width Er
 289 .It Bq Er ENODEV
 290 A component of ufs_args
 291 .Fa fspec
 292 does not exist.
 293 .It Bq Er ENOTBLK
 294 The
 295 .Fa fspec
 296 argument
 297 is not a block device.
 298 .It Bq Er ENOTEMPTY
 299 The
 300 .Dv MNT_EMPTYDIR
 301 option was specified, and the requested mount point
 302 is not an empty directory.
 303 .It Bq Er ENXIO
 304 The major device number of
 305 .Fa fspec
 306 is out of range (this indicates no device driver exists
 307 for the associated hardware).
 308 .It Bq Er EBUSY
 309 .Fa fspec
 310 is already mounted.
 311 .It Bq Er EMFILE
 312 No space remains in the mount table.
 313 .It Bq Er EINVAL
 314 The super block for the file system had a bad magic
 315 number or an out of range block size.
 316 .It Bq Er EINTEGRITY
 317 The super block for the file system had a bad check hash.
 318 The check hash can usually be corrected by running
 319 .Xr fsck 8 .
 320 .It Bq Er ENOMEM
 321 Not enough memory was available to read the cylinder
 322 group information for the file system.
 323 .It Bq Er EIO
 324 An I/O error occurred while reading the super block or
 325 cylinder group information.
 326 .It Bq Er EFAULT
 327 The
 328 .Fa fspec
 329 argument
 330 points outside the process's allocated address space.
 331 .El
 332 .Pp
 333 The following errors can occur for a
 334 .Em nfs
 335 file system mount:
 336 .Bl -tag -width Er
 337 .It Bq Er ETIMEDOUT
 338 .Em Nfs
 339 timed out trying to contact the server.
 340 .It Bq Er EFAULT
 341 Some part of the information described by nfs_args
 342 points outside the process's allocated address space.
 343 .El
 344 .Pp
 345 The
 346 .Fn unmount
 347 system call may fail with one of the following errors:
 348 .Bl -tag -width Er
 349 .It Bq Er EPERM
 350 The caller is neither the super-user nor the user who issued the corresponding
 351 .Fn mount
 352 call.
 353 .It Bq Er ENAMETOOLONG
 354 The length of the path name exceeded 1023 characters.
 355 .It Bq Er EINVAL
 356 The requested directory is not in the mount table.
 357 .It Bq Er ENOENT
 358 The file system ID specified using
 359 .Dv MNT_BYFSID
 360 was not found in the mount table.
 361 .It Bq Er EINVAL
 362 The file system ID specified using
 363 .Dv MNT_BYFSID
 364 could not be decoded.
 365 .It Bq Er EINVAL
 366 The specified file system is the root file system.
 367 .It Bq Er EBUSY
 368 A process is holding a reference to a file located
 369 on the file system.
 370 .It Bq Er EIO
 371 An I/O error occurred while writing cached file system information.
 372 .It Bq Er EFAULT
 373 The
 374 .Fa dir
 375 argument
 376 points outside the process's allocated address space.
 377 .El
 378 .Sh SEE ALSO
 379 .Xr lsvfs 1 ,
 380 .Xr mksnap_ffs 8 ,
 381 .Xr mount 8 ,
 382 .Xr umount 8
 383 .Sh HISTORY
 384 The
 385 .Fn mount
 386 and
 387 .Fn unmount
 388 functions appeared in
 389 .At v1 .
 390 The
 391 .Fn nmount
 392 system call first appeared in
 393 .Fx 5.0 .
 394 .Sh BUGS
 395 Some of the error codes need translation to more obvious messages.
 396 .Pp
 397 Allowing untrusted users to mount arbitrary media, e.g. by enabling
 398 .Va vfs.usermount ,
 399 should not be considered safe.
 400 Most file systems in
 401 .Fx
 402 were not built to safeguard against malicious devices.