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 August 28, 2019 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.El 278.Pp 279The following errors can occur for a 280.Em ufs 281file system mount: 282.Bl -tag -width Er 283.It Bq Er ENODEV 284A component of ufs_args 285.Fa fspec 286does not exist. 287.It Bq Er ENOTBLK 288The 289.Fa fspec 290argument 291is not a block device. 292.It Bq Er ENOTEMPTY 293The 294.Dv MNT_EMPTYDIR 295option was specified, and the requested mount point 296is not an empty directory. 297.It Bq Er ENXIO 298The major device number of 299.Fa fspec 300is out of range (this indicates no device driver exists 301for the associated hardware). 302.It Bq Er EBUSY 303.Fa fspec 304is already mounted. 305.It Bq Er EMFILE 306No space remains in the mount table. 307.It Bq Er EINVAL 308The super block for the file system had a bad magic 309number or an out of range block size. 310.It Bq Er ENOMEM 311Not enough memory was available to read the cylinder 312group information for the file system. 313.It Bq Er EIO 314An I/O error occurred while reading the super block or 315cylinder group information. 316.It Bq Er EFAULT 317The 318.Fa fspec 319argument 320points outside the process's allocated address space. 321.El 322.Pp 323The following errors can occur for a 324.Em nfs 325file system mount: 326.Bl -tag -width Er 327.It Bq Er ETIMEDOUT 328.Em Nfs 329timed out trying to contact the server. 330.It Bq Er EFAULT 331Some part of the information described by nfs_args 332points outside the process's allocated address space. 333.El 334.Pp 335The 336.Fn unmount 337system call may fail with one of the following errors: 338.Bl -tag -width Er 339.It Bq Er EPERM 340The caller is neither the super-user nor the user who issued the corresponding 341.Fn mount 342call. 343.It Bq Er ENAMETOOLONG 344The length of the path name exceeded 1023 characters. 345.It Bq Er EINVAL 346The requested directory is not in the mount table. 347.It Bq Er ENOENT 348The file system ID specified using 349.Dv MNT_BYFSID 350was not found in the mount table. 351.It Bq Er EINVAL 352The file system ID specified using 353.Dv MNT_BYFSID 354could not be decoded. 355.It Bq Er EINVAL 356The specified file system is the root file system. 357.It Bq Er EBUSY 358A process is holding a reference to a file located 359on the file system. 360.It Bq Er EIO 361An I/O error occurred while writing cached file system information. 362.It Bq Er EFAULT 363The 364.Fa dir 365argument 366points outside the process's allocated address space. 367.El 368.Sh SEE ALSO 369.Xr lsvfs 1 , 370.Xr mksnap_ffs 8 , 371.Xr mount 8 , 372.Xr umount 8 373.Sh HISTORY 374The 375.Fn mount 376and 377.Fn unmount 378functions appeared in 379.At v1 . 380The 381.Fn nmount 382system call first appeared in 383.Fx 5.0 . 384.Sh BUGS 385Some of the error codes need translation to more obvious messages. 386.Pp 387Allowing untrusted users to mount arbitrary media, e.g. by enabling 388.Va vfs.usermount , 389should not be considered safe. 390Most file systems in 391.Fx 392were not built to safeguard against malicious devices. 393