From 5614f733089e5f3cff5ca48b80b07b896d13209e Mon Sep 17 00:00:00 2001 From: Michael Kerrisk Date: Mon, 6 Oct 2008 13:09:26 +0200 Subject: [PATCH] mount.2, umount.2: split umoun*() out into a separate page The length of this page means that it's becoming difficult to parse which info is specific to mount() versus umount()/umount2(), so split the umount material out into its own page. Signed-off-by: Michael Kerrisk --- man2/mount.2 | 99 +++--------------------------- man2/umount.2 | 164 +++++++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 172 insertions(+), 91 deletions(-) diff --git a/man2/mount.2 b/man2/mount.2 index 57a5af29d..19fcb3233 100644 --- a/man2/mount.2 +++ b/man2/mount.2 @@ -35,9 +35,9 @@ .\" Modified 2004-06-17 by Michael Kerrisk .\" 2005-05-18, mtk, Added MNT_EXPIRE, plus a few other tidy-ups. .\" -.TH MOUNT 2 2008-10-02 "Linux" "Linux Programmer's Manual" +.TH MOUNT 2 2008-10-06 "Linux" "Linux Programmer's Manual" .SH NAME -mount, umount, umount2 \- mount and unmount file systems +mount \- mount file system .SH SYNOPSIS .nf .B "#include " @@ -45,13 +45,8 @@ mount, umount, umount2 \- mount and unmount file systems .BI "int mount(const char *" source ", const char *" target , .BI " const char *" filesystemtype ", unsigned long " mountflags , .BI " const void *" data ); -.sp -.BI "int umount(const char *" target ); -.sp -.BI "int umount2(const char *" target ", int " flags ); .fi .SH DESCRIPTION -.\" FIXME . This page could be better structured .BR mount () attaches the file system specified by .I source @@ -59,15 +54,9 @@ attaches the file system specified by or a dummy) to the directory specified by .IR target . -.BR umount () -and -.BR umount2 () -remove the attachment of the (topmost) file system mounted on -.IR target . - Appropriate privilege (Linux: the .B CAP_SYS_ADMIN -capability) is required to mount and unmount file systems. +capability) is required to mount file systems. Since Linux 2.4 a single file system can be visible at multiple mount points, and multiple mounts can be stacked @@ -263,49 +252,6 @@ understood by this file system. See .BR mount (8) for details of the options available for each filesystem type. -.PP -.\" Note: the kernel naming differs from the glibc naming -.\" umount2 is the glibc name for what the kernel now calls umount -.\" and umount is the glibc name for oldumount -Linux 2.1.116 added the -.BR umount2 () -system call, which, like -.BR umount (), -unmounts a target, but allows additional -.I flags -controlling the behavior of the operation: -.TP -.BR MNT_FORCE " (since Linux 2.1.116)" -Force unmount even if busy. -This can cause data loss. -(Only for NFS mounts.) -.\" FIXME Can MNT_FORCE result in data loss? According to -.\" the Solaris manual page it can cause data loss on Solaris. -.\" If the same holds on Linux, then this should be documented. -.TP -.BR MNT_DETACH " (since Linux 2.4.11)" -Perform a lazy unmount: make the mount point unavailable for -new accesses, and actually perform the unmount when the mount point -ceases to be busy. -.TP -.BR MNT_EXPIRE " (since Linux 2.6.8)" -Mark the mount point as expired. -If a mount point is not currently in use, then an initial call to -.BR umount2 () -with this flag fails with the error -.BR EAGAIN , -but marks the mount point as expired. -The mount point remains expired as long as it isn't accessed -by any process. -A second -.BR umount2 () -call specifying -.B MNT_EXPIRE -unmounts an expired mount point. -This flag cannot be specified with either -.B MNT_FORCE -or -.BR MNT_DETACH . .SH "RETURN VALUE" On success, zero is returned. On error, \-1 is returned, and @@ -333,13 +279,6 @@ option. .\" mtk: Probably: write permission is required for MS_BIND, with .\" the error EPERM if not present; CAP_DAC_OVERRIDE is required. .TP -.B EAGAIN -A call to -.BR umount2 () -specifying -.B MNT_EXPIRE -successfully marked an unbusy file system as expired. -.TP .B EBUSY .I source is already mounted. @@ -351,7 +290,6 @@ because .I target is still busy (it is the working directory of some task, the mount point of another device, has open files, etc.). -Or, it could not be unmounted because it is busy. .TP .B EFAULT One of the pointer arguments points outside the user address space. @@ -370,17 +308,6 @@ Or, a move was attempted, but .I source was not a mount point, or was \(aq/\(aq. -Or, an unmount was attempted, but -.I target -was not a mount point. -Or, -.BR umount2 () -was called with -.B MNT_EXPIRE -and either -.B MNT_DETACH -or -.BR MNT_FORCE . .TP .B ELOOP Too many links encountered during pathname resolution. @@ -412,8 +339,10 @@ The kernel could not allocate a free page to copy filenames or data into. is not a block device (and a device was required). .TP .B ENOTDIR -The second argument, or a prefix of the first argument, is not -a directory. +.IR target , +or a prefix of +.IR source , +is not a directory. .TP .B ENXIO The major number of the block device @@ -423,22 +352,11 @@ is out of range. .B EPERM The caller does not have the required privileges. .SH "CONFORMING TO" -These functions are Linux-specific and should not be used in +This function is Linux-specific and should not be used in programs intended to be portable. .SH NOTES .SS Linux Notes The original -.BR umount () -function was called as \fIumount(device)\fP and would return -.B ENOTBLK -when called with something other than a block device. -In Linux 0.98p4 a call \fIumount(dir)\fP was added, in order to -support anonymous devices. -In Linux 2.3.99-pre7 the call \fIumount(device)\fP was removed, -leaving only \fIumount(dir)\fP (since now devices can be mounted -in more than one place, so specifying the device does not suffice). -.LP -The original .B MS_SYNC flag was renamed .B MS_SYNCHRONOUS @@ -456,6 +374,7 @@ Since Linux 2.4 the set-user-ID and set-group-ID bits are just silently ignored in this case. .\" The change is in patch-2.4.0-prerelease. .SH "SEE ALSO" +.BR umount (2), .BR path_resolution (7), .BR mount (8), .BR umount (8) diff --git a/man2/umount.2 b/man2/umount.2 index 373253092..9f94e6ef1 100644 --- a/man2/umount.2 +++ b/man2/umount.2 @@ -1 +1,163 @@ -.so man2/mount.2 +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (C) 1993 Rickard E. Faith +.\" and Copyright (C) 1994 Andries E. Brouwer +.\" and Copyright (C) 2002, 2005 Michael Kerrisk +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" 2008-10-06, mtk: Created this as a new page by splitting +.\" umount/umount2 material out of mount.2 +.\" +.TH UMOUNT 2 2008-10-06 "Linux" "Linux Programmer's Manual" +.SH NAME +umount, umount2 \- unmount file system +.SH SYNOPSIS +.nf +.B "#include " +.sp +.BI "int umount(const char *" target ); +.sp +.BI "int umount2(const char *" target ", int " flags ); +.fi +.SH DESCRIPTION +.BR umount () +and +.BR umount2 () +remove the attachment of the (topmost) file system mounted on +.IR target . +.\" Note: the kernel naming differs from the glibc naming +.\" umount2 is the glibc name for what the kernel now calls umount +.\" and umount is the glibc name for oldumount + +Appropriate privilege (Linux: the +.B CAP_SYS_ADMIN +capability) is required to unmount file systems. + +Linux 2.1.116 added the +.BR umount2 () +system call, which, like +.BR umount (), +unmounts a target, but allows additional +.I flags +controlling the behavior of the operation: +.TP +.BR MNT_FORCE " (since Linux 2.1.116)" +Force unmount even if busy. +This can cause data loss. +(Only for NFS mounts.) +.\" FIXME Can MNT_FORCE result in data loss? According to +.\" the Solaris manual page it can cause data loss on Solaris. +.\" If the same holds on Linux, then this should be documented. +.TP +.BR MNT_DETACH " (since Linux 2.4.11)" +Perform a lazy unmount: make the mount point unavailable for +new accesses, and actually perform the unmount when the mount point +ceases to be busy. +.TP +.BR MNT_EXPIRE " (since Linux 2.6.8)" +Mark the mount point as expired. +If a mount point is not currently in use, then an initial call to +.BR umount2 () +with this flag fails with the error +.BR EAGAIN , +but marks the mount point as expired. +The mount point remains expired as long as it isn't accessed +by any process. +A second +.BR umount2 () +call specifying +.B MNT_EXPIRE +unmounts an expired mount point. +This flag cannot be specified with either +.B MNT_FORCE +or +.BR MNT_DETACH . +.SH "RETURN VALUE" +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +The error values given below result from filesystem type independent +errors. +Each filesystem type may have its own special errors and its +own special behavior. +See the kernel source code for details. +.TP +.B EAGAIN +A call to +.BR umount2 () +specifying +.B MNT_EXPIRE +successfully marked an unbusy file system as expired. +.TP +.B EBUSY +.I target +could not be unmounted because it is busy. +.TP +.B EFAULT +.I target +points outside the user address space. +.TP +.B EINVAL +.I target +is not a mount point. +Or, +.BR umount2 () +was called with +.B MNT_EXPIRE +and either +.B MNT_DETACH +or +.BR MNT_FORCE . +.TP +.B ENAMETOOLONG +A pathname was longer than +.BR MAXPATHLEN . +.TP +.B ENOENT +A pathname was empty or had a nonexistent component. +.TP +.B ENOMEM +The kernel could not allocate a free page to copy filenames or data into. +.TP +.B EPERM +The caller does not have the required privileges. +.SH "CONFORMING TO" +These functions are Linux-specific and should not be used in +programs intended to be portable. +.SH NOTES +The original +.BR umount () +function was called as \fIumount(device)\fP and would return +.B ENOTBLK +when called with something other than a block device. +In Linux 0.98p4 a call \fIumount(dir)\fP was added, in order to +support anonymous devices. +In Linux 2.3.99-pre7 the call \fIumount(device)\fP was removed, +leaving only \fIumount(dir)\fP (since now devices can be mounted +in more than one place, so specifying the device does not suffice). +.SH "SEE ALSO" +.BR mount (2), +.BR path_resolution (7), +.BR mount (8), +.BR umount (8)