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