1.\" $NetBSD: mount.2,v 1.42 2009/03/15 08:04:12 joerg Exp $ 2.\" 3.\" Copyright (c) 1980, 1989, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" @(#)mount.2 8.3 (Berkeley) 5/24/95 31.\" 32.Dd July 14, 2007 33.Dt MOUNT 2 34.Os 35.Sh NAME 36.Nm mount , 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" "size_t data_len" 46.Ft int 47.Fn unmount "const char *dir" "int flags" 48.Sh DESCRIPTION 49The 50.Fn mount 51function grafts 52a file system object onto the system file tree 53at the point 54.Ar dir . 55The argument 56.Ar data 57describes the file system object to be mounted, and is 58.Ar data_len 59bytes long. 60The argument 61.Ar type 62tells the kernel how to interpret 63.Ar data 64(See 65.Ar type 66below). 67The contents of the file system 68become available through the new mount point 69.Ar dir . 70Any files in 71.Ar dir 72at the time 73of a successful mount are swept under the carpet so to speak, and 74are unavailable until the file system is unmounted. 75.Pp 76The following 77.Ar flags 78may be specified to 79suppress default semantics which affect file system access. 80.Bl -tag -width MNT_SYNCHRONOUS 81.It Dv MNT_RDONLY 82The file system should be treated as read-only; 83even the super-user may not write on it. 84.It Dv MNT_UNION 85Union with underlying filesystem instead of obscuring it. 86.It Dv MNT_HIDDEN 87Cause the 88.Xr df 1 89program, and perhaps others, to, by default, 90exclude this filesystem from its output. 91.It Dv MNT_NOEXEC 92Do not allow files to be executed from the file system. 93.It Dv MNT_NOSUID 94Do not honor setuid or setgid bits on files when executing them. 95.It Dv MNT_NODEV 96Do not interpret special files on the file system. 97.It Dv MNT_NOCOREDUMP 98Do not allow programs to dump core files on the file system. 99.It Dv MNT_NOATIME 100Never update access time in the file system. 101.It Dv MNT_NODEVMTIME 102Never update modification time of device files. 103.It Dv MNT_SYMPERM 104Recognize the permission of symbolic link when reading or traversing. 105.It Dv MNT_SYNCHRONOUS 106All I/O to the file system should be done synchronously. 107This will slow I/O performance considerably, but 108enhances overall filesystem reliability. 109.It Dv MNT_ASYNC 110All I/O to the file system should be done asynchronously. 111This vastly improves I/O throughput, 112but at a cost of making the filesystem likely to be 113completely unrecoverable should the system crash while 114unwritten data is pending in kernel buffers. 115.It Dv MNT_SOFTDEP 116Use soft dependencies. 117This enhanced system performance in many cases compared 118to a default mount, i.e. one neither 119.Dv MNT_ASYNC 120nor 121.Dv MNT_SYNCHRONOUS , 122by carefully sequencing meta-data writes to achieve the 123effect achieved by a default mount causing many meta-data 124writes to be synchronous. 125.It Dv MNT_LOG 126Use a filesystem journal. 127This is incompatible with, and overrides, 128.Dv MNT_SOFTDEP . 129.Dv MNT_LOG 130causes a journal (or log) to be created in the 131filesystem, creating a record of meta-data writes to be 132performed, allowing the actual writes to be deferred. 133This improves performance in most cases. 134.El 135.Pp 136The 137.Dv MNT_UPDATE , 138.Dv MNT_RELOAD , 139and 140.Dv MNT_GETARGS 141flags indicate that the mount command is being applied 142to an already mounted file system. 143The 144.Dv MNT_UPDATE 145flag allows the mount flags to be changed without requiring 146that the file system be unmounted and remounted. 147A conversion from read-write to read-only will fail if any files 148are currently open for writing on the filesystem, unless the 149.Dv MNT_FORCE 150flag is also applied. 151Some file systems may not allow all flags to be changed. 152For example, 153some file systems will not allow a change from read-write to read-only. 154The 155.Dv MNT_RELOAD 156flag causes kernel filesystem data to be reloaded from 157the filesystem device. 158It is only permitted on filesystems mounted read-only. 159Its purpose is to notify the system that the filesystem 160data has been modified by some external process. 161The 162.Dv MNT_GETARGS 163flag does not alter any of the mounted filesystem's properties, 164but returns the filesystem-specific arguments for the currently mounted 165filesystem. 166.Pp 167The 168.Fa type 169argument defines the type of the file system. 170The types of file systems known to the system are defined in 171.Aq Pa sys/mount.h , 172and those supported by the current running kernel obtained 173using 174.Xr sysctl 8 175to obtain the node 176.\" .Bd -literal -offset indent 177vfs.generic.fstypes. 178.\" XXX from lite-2: 179.\" The types of filesystems known to the system can be obtained with 180.\" .Xr sysctl 8 181.\" by using the command: 182.\" .Bd -literal -offset indent 183.\" sysctl vfs 184.\" .Ed 185.\" .Pp 186.Fa data 187is a pointer to a structure that contains the type 188specific arguments to mount. 189Some of the currently supported types of file systems and 190their type specific data are: 191.Pp 192.Dv MOUNT_FFS 193.Bd -literal -offset indent -compact 194struct ufs_args { 195 char *fspec; /* block special file to mount */ 196}; 197.Ed 198.Pp 199.Dv MOUNT_NFS 200.Bd -literal -offset indent -compact 201struct nfs_args { 202 int version; /* args structure version */ 203 struct sockaddr *addr; /* file server address */ 204 int addrlen; /* length of address */ 205 int sotype; /* Socket type */ 206 int proto; /* and Protocol */ 207 u_char *fh; /* File handle to be mounted */ 208 int fhsize; /* Size, in bytes, of fh */ 209 int flags; /* flags */ 210 int wsize; /* write size in bytes */ 211 int rsize; /* read size in bytes */ 212 int readdirsize; /* readdir size in bytes */ 213 int timeo; /* initial timeout in .1 secs */ 214 int retrans; /* times to retry send */ 215 int maxgrouplist; /* Max. size of group list */ 216 int readahead; /* # of blocks to readahead */ 217 int leaseterm; /* Term (sec) of lease */ 218 int deadthresh; /* Retrans threshold */ 219 char *hostname; /* server's name */ 220}; 221.Ed 222.Pp 223.Dv MOUNT_MFS 224.Bd -literal -offset indent -compact 225struct mfs_args { 226 char *fspec; /* name to export for statfs */ 227 struct export_args30 pad; /* unused */ 228 caddr_t base; /* base of file system in mem */ 229 u_long size; /* size of file system */ 230}; 231.Ed 232.\" XXX from lite-2: 233.\" The format for these argument structures is described in the 234.\" manual page for each filesystem. 235.\" By convention filesystem manual pages are named 236.\" by prefixing ``mount_'' to the name of the filesystem as returned by 237.\" .Xr sysctl 8 . 238.\" Thus the 239.\" .Nm NFS 240.\" filesystem is described by the 241.\" .Xr mount_nfs 8 242.\" manual page. 243.Pp 244The 245.Fn unmount 246function call disassociates the file system from the specified 247mount point 248.Fa dir . 249.Pp 250The 251.Fa flags 252argument may specify 253.Dv MNT_FORCE 254to specify that the file system should be forcibly unmounted even if files are 255still active. 256Active special devices continue to work, 257but any further accesses to any other active files result in errors 258even if the file system is later remounted. 259.Sh RETURN VALUES 260.Fn mount 261returns the value 0 if the mount was successful, 262the number of bytes written to 263.Ar data 264for 265.Dv MNT_GETARGS , 266otherwise \-1 is returned and the variable 267.Va errno 268is set to indicate the error. 269.Pp 270.Fn unmount 271returns the value 0 if the unmount succeeded; otherwise \-1 is returned 272and the variable 273.Va errno 274is set to indicate the error. 275.Sh ERRORS 276.Fn mount 277will fail when one of the following occurs: 278.Bl -tag -width Er 279.It Bq Er EBUSY 280Another process currently holds a reference to 281.Fa dir , 282or for an update from read-write to read-only 283there are files on the filesystem open for writes. 284.It Bq Er EFAULT 285.Fa dir 286points outside the process's allocated address space. 287.It Bq Er ELOOP 288Too many symbolic links were encountered in translating a pathname. 289.It Bq Er ENAMETOOLONG 290A component of a pathname exceeded 291.Dv NAME_MAX 292characters, or an entire path name exceeded 293.Dv PATH_MAX 294characters. 295.It Bq Er ENOENT 296A component of 297.Fa dir 298does not exist. 299.It Bq Er ENOTDIR 300A component of 301.Ar name 302is not a directory, 303or a path prefix of 304.Ar special 305is not a directory. 306.It Bq Er EPERM 307The caller is not the super-user, 308and ordinary user mounts are not permitted or 309this particular request violates the rules. 310.El 311.Pp 312The following errors can occur for a 313.Em ufs 314file system mount: 315.Bl -tag -width Er 316.It Bq Er EBUSY 317.Ar Fspec 318is already mounted. 319.It Bq Er EFAULT 320.Ar Fspec 321points outside the process's allocated address space. 322.It Bq Er EINVAL 323The super block for the file system had a bad magic 324number or an out of range block size. 325.It Bq Er EIO 326An I/O error occurred while reading the super block or 327cylinder group information. 328.It Bq Er EMFILE 329No space remains in the mount table. 330.It Bq Er ENODEV 331A component of ufs_args 332.Ar fspec 333does not exist. 334.It Bq Er ENOMEM 335Not enough memory was available to read the cylinder 336group information for the file system. 337.It Bq Er ENOTBLK 338.Ar Fspec 339is not a block device. 340.It Bq Er ENXIO 341The major device number of 342.Ar fspec 343is out of range (this indicates no device driver exists 344for the associated hardware). 345.El 346.Pp 347The following errors can occur for a 348.Em nfs 349file system mount: 350.Bl -tag -width Er 351.It Bq Er EFAULT 352Some part of the information described by nfs_args 353points outside the process's allocated address space. 354.It Bq Er ETIMEDOUT 355.Em Nfs 356timed out trying to contact the server. 357.El 358.Pp 359The following errors can occur for a 360.Em mfs 361file system mount: 362.Bl -tag -width Er 363.It Bq Er EFAULT 364.Em Name 365points outside the process's allocated address space. 366.It Bq Er EINVAL 367The super block for the file system had a bad magic 368number or an out of range block size. 369.It Bq Er EIO 370A paging error occurred while reading the super block or 371cylinder group information. 372.It Bq Er EMFILE 373No space remains in the mount table. 374.It Bq Er ENOMEM 375Not enough memory was available to read the cylinder 376group information for the file system. 377.El 378.Pp 379.Fn unmount 380may fail with one of the following errors: 381.Bl -tag -width Er 382.It Bq Er EBUSY 383A process is holding a reference to a file located 384on the file system. 385.It Bq Er EFAULT 386.Fa dir 387points outside the process's allocated address space. 388.It Bq Er EINVAL 389The requested directory is not in the mount table. 390.It Bq Er EIO 391An I/O error occurred while writing cached file system information. 392.It Bq Er ELOOP 393Too many symbolic links were encountered in translating the pathname. 394.It Bq Er ENAMETOOLONG 395A component of a pathname exceeded 396.Dv NAME_MAX 397characters, or an entire path name exceeded 398.Dv PATH_MAX 399characters. 400.It Bq Er ENOTDIR 401A component of the path is not a directory. 402.It Bq Er EPERM 403The caller is not the super-user. 404.El 405.Pp 406A 407.Em ufs 408or 409.Em mfs 410mount can also fail if the maximum number of file systems are currently 411mounted. 412.Sh SEE ALSO 413.Xr df 1 , 414.Xr getvfsstat 2 , 415.Xr nfssvc 2 , 416.Xr getmntinfo 3 , 417.Xr symlink 7 , 418.Xr mount 8 , 419.Xr sysctl 8 , 420.Xr umount 8 421.Sh HISTORY 422The 423.Fn mount 424and 425.Fn umount 426(now 427.Fn unmount ) 428function calls were all present in 429.At v6 . 430.Pp 431Prior to 432.Nx 4.0 433the 434.Nm 435call was used to export NFS filesystems. 436This is now done through 437.Fn nfssvc . 438.Pp 439The 440.Dv data_len 441argument was added for 442.Nx 5.0 . 443.Sh BUGS 444Some of the error codes need translation to more obvious messages. 445.Pp 446Far more filesystems are supported than those those listed. 447