[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.
.It Dv MNT_CPROTECT
Enable data protection on the filesystem if the filesystem is configured for it.
.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 unmount
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 unmount
returns the value 0 if the unmount 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 unmount
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 unmount 8
.Sh BUGS
Some of the error codes need translation to more obvious messages.
.Sh HISTORY
.Fn Mount
and
.Fn unmount
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.
3e170ce0 A	95	.It Dv MNT_CPROTECT
3e170ce0 A	96	Enable data protection on the filesystem if the filesystem is configured for it.
9bccf70c A	97	.El
	98	.Pp
	99	The flag
	100	.Dv MNT_UPDATE
	101	indicates that the mount command is being applied
	102	to an already mounted filesystem.
	103	This allows the mount flags to be changed without requiring
	104	that the filesystem be unmounted and remounted.
	105	Some filesystems may not allow all flags to be changed.
	106	For example,
	107	most filesystems will not allow a change from read-write to read-only.
	108	.Pp
55e303ae A	109	The flag
	110	.Dv MNT_RELOAD
	111	causes the vfs subsystem to update its data structures pertaining to
	112	the specified already mounted filesystem.
	113	.Pp
9bccf70c A	114	The
	115	.Fa type
	116	argument defines the type of the filesystem.
55e303ae	117	.Pp
9bccf70c A	118	.Fa Data
	119	is a pointer to a structure that contains the type
	120	specific arguments to mount.
55e303ae A	121	The format for these argument structures is described in the
55e303ae A	122	manual page for each filesystem.
9bccf70c A	123	.Pp
9bccf70c A	124	The
3e170ce0	125	.Fn unmount
9bccf70c A	126	function call disassociates the filesystem from the specified
	127	mount point
	128	.Fa dir .
	129	.Pp
	130	The
	131	.Fa flags
	132	argument may specify
	133	.Dv MNT_FORCE
	134	to specify that the filesystem should be forcibly unmounted even if files are
	135	still active.
	136	Active special devices continue to work,
	137	but any further accesses to any other active files result in errors
	138	even if the filesystem is later remounted.
	139	.Sh RETURN VALUES
	140	The
	141	.Fn mount
	142	returns the value 0 if the mount was successful, otherwise -1 is returned
	143	and the variable
	144	.Va errno
	145	is set to indicate the error.
	146	.Pp
3e170ce0 A	147	.Nm unmount
3e170ce0 A	148	returns the value 0 if the unmount succeeded; otherwise -1 is returned
9bccf70c A	149	and the variable
	150	.Va errno
	151	is set to indicate the error.
	152	.Sh ERRORS
	153	.Fn Mount
	154	will fail when one of the following occurs:
	155	.Bl -tag -width [ENAMETOOLONG]
	156	.It Bq Er EPERM
55e303ae A	157	The caller is not the super-user, and the device-node and the mountpoint
55e303ae A	158	do not have adequate ownership and permissions.
9bccf70c A	159	.It Bq Er ENAMETOOLONG
	160	A component of a pathname exceeded
	161	.Dv {NAME_MAX}
	162	characters, or an entire path name exceeded
	163	.Dv {PATH_MAX}
	164	characters.
	165	.It Bq Er ELOOP
	166	Too many symbolic links were encountered in translating a pathname.
	167	.It Bq Er ENOENT
	168	A component of
	169	.Fa dir
	170	does not exist.
	171	.It Bq Er ENOTDIR
	172	A component of
	173	.Ar name
	174	is not a directory,
	175	or a path prefix of
	176	.Ar special
	177	is not a directory.
	178	.It Bq Er EINVAL
	179	A pathname contains a character with the high-order bit set.
	180	.It Bq Er EBUSY
	181	Another process currently holds a reference to
	182	.Fa dir .
	183	.It Bq Er EFAULT
	184	.Fa Dir
	185	points outside the process's allocated address space.
	186	.El
	187	.Pp
3e170ce0	188	.Nm unmount
9bccf70c A	189	may fail with one of the following errors:
	190	.Bl -tag -width [ENAMETOOLONG]
	191	.It Bq Er EPERM
55e303ae A	192	The caller is not the super-user, and the
	193	.Nm mount()
	194	was not done by the user.
9bccf70c A	195	.It Bq Er ENOTDIR
	196	A component of the path is not a directory.
	197	.It Bq Er EINVAL
	198	The pathname contains a character with the high-order bit set.
	199	.It Bq Er ENAMETOOLONG
	200	A component of a pathname exceeded
	201	.Dv {NAME_MAX}
	202	characters, or an entire path name exceeded
	203	.Dv {PATH_MAX}
	204	characters.
	205	.It Bq Er ELOOP
	206	Too many symbolic links were encountered in translating the pathname.
	207	.It Bq Er EINVAL
	208	The requested directory is not in the mount table.
	209	.It Bq Er EBUSY
	210	A process is holding a reference to a file located
	211	on the filesystem.
	212	.It Bq Er EIO
	213	An I/O error occurred while writing cached filesystem information.
	214	.It Bq Er EFAULT
	215	.Fa Dir
	216	points outside the process's allocated address space.
	217	.El
9bccf70c A	218	.Sh SEE ALSO
9bccf70c A	219	.Xr mount 8 ,
3e170ce0	220	.Xr unmount 8
9bccf70c A	221	.Sh BUGS
	222	Some of the error codes need translation to more obvious messages.
	223	.Sh HISTORY
	224	.Fn Mount
	225	and
3e170ce0	226	.Fn unmount
9bccf70c A	227	function calls appeared in
9bccf70c A	228	.At v6 .