[apple/xnu.git] / bsd / man / man2 / mount.2

.\"	$OpenBSD: mount.2,v 1.6 1997/03/09 19:41:16 millert Exp $
.\"	$NetBSD: mount.2,v 1.12 1996/02/29 23:47:48 jtc Exp $
.\"
.\" Copyright (c) 1980, 1989, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)mount.2	8.2 (Berkeley) 12/11/93
.\"
.Dd December 11, 1993
.Dt MOUNT 2
.Os BSD 4
.Sh NAME
.Nm mount ,
.Nm unmount
.Nd mount or dismount a filesystem
.Sh SYNOPSIS
.Fd #include <sys/param.h>
.Fd #include <sys/mount.h>
.Ft int
.Fn mount "const char *type" "const char *dir" "int flags" "void *data"
.Ft int
.Fn unmount "const char *dir" "int flags"
.Sh DESCRIPTION
The
.Fn mount
function grafts
a filesystem object onto the system file tree
at the point
.Ar dir .
The argument
.Ar data
describes the filesystem object to be mounted.
The argument
.Ar type
tells the kernel how to interpret
.Ar data
(See
.Ar type
below).
The contents of the filesystem
become available through the new mount point
.Ar dir .
Any files in
.Ar dir
at the time
of a successful mount are swept under the carpet so to speak, and
are unavailable until the filesystem is unmounted.
.Pp
The following
.Ar flags
may be specified to
suppress default semantics which affect filesystem access.
.Bl -tag -width MNT_SYNCHRONOUS
.It Dv MNT_RDONLY
The filesystem should be treated as read-only;
Even the super-user may not write on it.
.It Dv MNT_NOEXEC
Do not allow files to be executed from the filesystem.
.It Dv MNT_NOSUID
Do not honor setuid or setgid bits on files when executing them.
.It Dv MNT_NODEV
Do not interpret special files on the filesystem.
.It Dv MNT_UNION
Union with underlying filesystem instead of obscuring it.
.It Dv MNT_SYNCHRONOUS
All I/O to the filesystem should be done synchronously.
.El
.Pp
The flag
.Dv MNT_UPDATE
indicates that the mount command is being applied
to an already mounted filesystem.
This allows the mount flags to be changed without requiring
that the filesystem be unmounted and remounted.
Some filesystems may not allow all flags to be changed.
For example,
most filesystems will not allow a change from read-write to read-only.
.Pp
The flag
.Dv MNT_RELOAD
causes the vfs subsystem to update its data structures pertaining to
the specified already mounted filesystem.
.Pp
The
.Fa type
argument defines the type of the filesystem.
.Pp
.Fa Data
is a pointer to a structure that contains the type
specific arguments to mount.
The format for these argument structures is described in the
manual page for each filesystem.
.Pp
The
.Fn umount
function call disassociates the filesystem from the specified
mount point
.Fa dir .
.Pp
The
.Fa flags
argument may specify
.Dv MNT_FORCE
to specify that the filesystem should be forcibly unmounted even if files are
still active.
Active special devices continue to work,
but any further accesses to any other active files result in errors
even if the filesystem is later remounted.
.Sh RETURN VALUES
The
.Fn mount
returns the value 0 if the mount was successful, otherwise -1 is returned
and the variable
.Va errno
is set to indicate the error.
.Pp
.Nm Umount
returns the value 0 if the umount succeeded; otherwise -1 is returned
and the variable
.Va errno
is set to indicate the error.
.Sh ERRORS
.Fn Mount
will fail when one of the following occurs:
.Bl -tag -width [ENAMETOOLONG]
.It Bq Er EPERM
The caller is not the super-user, and the device-node and the mountpoint
do not have adequate ownership and permissions.
.It Bq Er ENAMETOOLONG
A component of a pathname exceeded
.Dv {NAME_MAX}
characters, or an entire path name exceeded
.Dv {PATH_MAX}
characters.
.It Bq Er ELOOP
Too many symbolic links were encountered in translating a pathname.
.It Bq Er ENOENT
A component of
.Fa dir
does not exist.
.It Bq Er ENOTDIR
A component of
.Ar name
is not a directory,
or a path prefix of
.Ar special
is not a directory.
.It Bq Er EINVAL
A pathname contains a character with the high-order bit set.
.It Bq Er EBUSY
Another process currently holds a reference to
.Fa dir .
.It Bq Er EFAULT
.Fa Dir
points outside the process's allocated address space.
.El
.Pp
.Nm Umount
may fail with one of the following errors:
.Bl -tag -width [ENAMETOOLONG]
.It Bq Er EPERM
The caller is not the super-user, and the
.Nm mount()
was not done by the user.
.It Bq Er ENOTDIR
A component of the path is not a directory.
.It Bq Er EINVAL
The pathname contains a character with the high-order bit set.
.It Bq Er ENAMETOOLONG
A component of a pathname exceeded
.Dv {NAME_MAX}
characters, or an entire path name exceeded
.Dv {PATH_MAX}
characters.
.It Bq Er ELOOP
Too many symbolic links were encountered in translating the pathname.
.It Bq Er EINVAL
The requested directory is not in the mount table.
.It Bq Er EBUSY
A process is holding a reference to a file located
on the filesystem.
.It Bq Er EIO
An I/O error occurred while writing cached filesystem information.
.It Bq Er EFAULT
.Fa Dir
points outside the process's allocated address space.
.El
.Sh SEE ALSO
.Xr mount 8 ,
.Xr umount 8
.Sh BUGS
Some of the error codes need translation to more obvious messages.
.Sh HISTORY
.Fn Mount
and
.Fn umount
function calls appeared in
.At v6 .
Commit	Line	Data
9bccf70c A	1	.\" $OpenBSD: mount.2,v 1.6 1997/03/09 19:41:16 millert Exp $
	2	.\" $NetBSD: mount.2,v 1.12 1996/02/29 23:47:48 jtc Exp $
	3	.\"
	4	.\" Copyright (c) 1980, 1989, 1993
	5	.\" The Regents of the University of California. All rights reserved.
	6	.\"
	7	.\" Redistribution and use in source and binary forms, with or without
	8	.\" modification, are permitted provided that the following conditions
	9	.\" are met:
	10	.\" 1. Redistributions of source code must retain the above copyright
	11	.\" notice, this list of conditions and the following disclaimer.
	12	.\" 2. Redistributions in binary form must reproduce the above copyright
	13	.\" notice, this list of conditions and the following disclaimer in the
	14	.\" documentation and/or other materials provided with the distribution.
	15	.\" 3. All advertising materials mentioning features or use of this software
	16	.\" must display the following acknowledgement:
	17	.\" This product includes software developed by the University of
	18	.\" California, Berkeley and its contributors.
	19	.\" 4. Neither the name of the University nor the names of its contributors
	20	.\" may be used to endorse or promote products derived from this software
	21	.\" without specific prior written permission.
	22	.\"
	23	.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
	24	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	25	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	26	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
	27	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	28	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	29	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	30	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	31	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	32	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	33	.\" SUCH DAMAGE.
	34	.\"
	35	.\" @(#)mount.2 8.2 (Berkeley) 12/11/93
	36	.\"
	37	.Dd December 11, 1993
	38	.Dt MOUNT 2
	39	.Os BSD 4
	40	.Sh NAME
	41	.Nm mount ,
	42	.Nm unmount
	43	.Nd mount or dismount a filesystem
	44	.Sh SYNOPSIS
	45	.Fd #include <sys/param.h>
	46	.Fd #include <sys/mount.h>
	47	.Ft int
	48	.Fn mount "const char type" "const char dir" "int flags" "void *data"
	49	.Ft int
	50	.Fn unmount "const char *dir" "int flags"
	51	.Sh DESCRIPTION
	52	The
	53	.Fn mount
	54	function grafts
	55	a filesystem object onto the system file tree
	56	at the point
	57	.Ar dir .
	58	The argument
	59	.Ar data
	60	describes the filesystem object to be mounted.
	61	The argument
	62	.Ar type
	63	tells the kernel how to interpret
	64	.Ar data
65	(See
66	.Ar type
67	below).
68	The contents of the filesystem
69	become available through the new mount point
70	.Ar dir .
71	Any files in
72	.Ar dir
73	at the time
74	of a successful mount are swept under the carpet so to speak, and
75	are unavailable until the filesystem is unmounted.
76	.Pp
77	The following
78	.Ar flags
79	may be specified to
80	suppress default semantics which affect filesystem access.
81	.Bl -tag -width MNT_SYNCHRONOUS
82	.It Dv MNT_RDONLY
83	The filesystem should be treated as read-only;
84	Even the super-user may not write on it.
9bccf70c A	85	.It Dv MNT_NOEXEC
	86	Do not allow files to be executed from the filesystem.
	87	.It Dv MNT_NOSUID
	88	Do not honor setuid or setgid bits on files when executing them.
	89	.It Dv MNT_NODEV
	90	Do not interpret special files on the filesystem.
	91	.It Dv MNT_UNION
	92	Union with underlying filesystem instead of obscuring it.
	93	.It Dv MNT_SYNCHRONOUS
	94	All I/O to the filesystem should be done synchronously.
	95	.El
	96	.Pp
	97	The flag
	98	.Dv MNT_UPDATE
	99	indicates that the mount command is being applied
	100	to an already mounted filesystem.
	101	This allows the mount flags to be changed without requiring
	102	that the filesystem be unmounted and remounted.
	103	Some filesystems may not allow all flags to be changed.
	104	For example,
	105	most filesystems will not allow a change from read-write to read-only.
	106	.Pp
55e303ae A	107	The flag
	108	.Dv MNT_RELOAD
	109	causes the vfs subsystem to update its data structures pertaining to
	110	the specified already mounted filesystem.
	111	.Pp
9bccf70c A	112	The
	113	.Fa type
	114	argument defines the type of the filesystem.
55e303ae	115	.Pp
9bccf70c A	116	.Fa Data
	117	is a pointer to a structure that contains the type
	118	specific arguments to mount.
55e303ae A	119	The format for these argument structures is described in the
55e303ae A	120	manual page for each filesystem.
9bccf70c A	121	.Pp
	122	The
	123	.Fn umount
	124	function call disassociates the filesystem from the specified
	125	mount point
	126	.Fa dir .
	127	.Pp
	128	The
	129	.Fa flags
	130	argument may specify
	131	.Dv MNT_FORCE
	132	to specify that the filesystem should be forcibly unmounted even if files are
	133	still active.
	134	Active special devices continue to work,
	135	but any further accesses to any other active files result in errors
	136	even if the filesystem is later remounted.
	137	.Sh RETURN VALUES
	138	The
	139	.Fn mount
	140	returns the value 0 if the mount was successful, otherwise -1 is returned
	141	and the variable
	142	.Va errno
	143	is set to indicate the error.
	144	.Pp
	145	.Nm Umount
	146	returns the value 0 if the umount succeeded; otherwise -1 is returned
	147	and the variable
	148	.Va errno
	149	is set to indicate the error.
	150	.Sh ERRORS
	151	.Fn Mount
	152	will fail when one of the following occurs:
	153	.Bl -tag -width [ENAMETOOLONG]
	154	.It Bq Er EPERM
55e303ae A	155	The caller is not the super-user, and the device-node and the mountpoint
55e303ae A	156	do not have adequate ownership and permissions.
9bccf70c A	157	.It Bq Er ENAMETOOLONG
	158	A component of a pathname exceeded
	159	.Dv {NAME_MAX}
	160	characters, or an entire path name exceeded
	161	.Dv {PATH_MAX}
	162	characters.
	163	.It Bq Er ELOOP
	164	Too many symbolic links were encountered in translating a pathname.
	165	.It Bq Er ENOENT
	166	A component of
	167	.Fa dir
	168	does not exist.
	169	.It Bq Er ENOTDIR
	170	A component of
	171	.Ar name
	172	is not a directory,
	173	or a path prefix of
	174	.Ar special
	175	is not a directory.
	176	.It Bq Er EINVAL
	177	A pathname contains a character with the high-order bit set.
	178	.It Bq Er EBUSY
	179	Another process currently holds a reference to
	180	.Fa dir .
	181	.It Bq Er EFAULT
	182	.Fa Dir
	183	points outside the process's allocated address space.
	184	.El
	185	.Pp
9bccf70c A	186	.Nm Umount
	187	may fail with one of the following errors:
	188	.Bl -tag -width [ENAMETOOLONG]
	189	.It Bq Er EPERM
55e303ae A	190	The caller is not the super-user, and the
	191	.Nm mount()
	192	was not done by the user.
9bccf70c A	193	.It Bq Er ENOTDIR
	194	A component of the path is not a directory.
	195	.It Bq Er EINVAL
	196	The pathname contains a character with the high-order bit set.
	197	.It Bq Er ENAMETOOLONG
	198	A component of a pathname exceeded
	199	.Dv {NAME_MAX}
	200	characters, or an entire path name exceeded
	201	.Dv {PATH_MAX}
	202	characters.
	203	.It Bq Er ELOOP
	204	Too many symbolic links were encountered in translating the pathname.
	205	.It Bq Er EINVAL
	206	The requested directory is not in the mount table.
	207	.It Bq Er EBUSY
	208	A process is holding a reference to a file located
	209	on the filesystem.
	210	.It Bq Er EIO
	211	An I/O error occurred while writing cached filesystem information.
	212	.It Bq Er EFAULT
	213	.Fa Dir
	214	points outside the process's allocated address space.
	215	.El
9bccf70c A	216	.Sh SEE ALSO
9bccf70c A	217	.Xr mount 8 ,
2d21ac55	218	.Xr umount 8
9bccf70c A	219	.Sh BUGS
	220	Some of the error codes need translation to more obvious messages.
	221	.Sh HISTORY
	222	.Fn Mount
	223	and
	224	.Fn umount
	225	function calls appeared in
	226	.At v6 .