man2/umount.2

   1 .\" Copyright (C) 1993 Rickard E. Faith <faith@cs.unc.edu>
   2 .\" and Copyright (C) 1994 Andries E. Brouwer <aeb@cwi.nl>
   3 .\" and Copyright (C) 2002, 2005 Michael Kerrisk <mtk.manpages@gmail.com>
   4 .\"
   5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   6 .\"
   7 .\" 2008-10-06, mtk: Created this as a new page by splitting
   8 .\"     umount/umount2 material out of mount.2
   9 .\"
  10 .TH UMOUNT 2 2022-09-09 "Linux man-pages (unreleased)"
  11 .SH NAME
  12 umount, umount2 \- unmount filesystem
  13 .SH LIBRARY
  14 Standard C library
  15 .RI ( libc ", " \-lc )
  16 .SH SYNOPSIS
  17 .nf
  18 .B "#include <sys/mount.h>"
  19 .PP
  20 .BI "int umount(const char *" target );
  21 .BI "int umount2(const char *" target ", int " flags );
  22 .fi
  23 .SH DESCRIPTION
  24 .BR umount ()
  25 and
  26 .BR umount2 ()
  27 remove the attachment of the (topmost) filesystem mounted on
  28 .IR target .
  29 .\" Note: the kernel naming differs from the glibc naming
  30 .\" umount2 is the glibc name for what the kernel now calls umount
  31 .\" and umount is the glibc name for oldumount
  32 .PP
  33 Appropriate privilege (Linux: the
  34 .B CAP_SYS_ADMIN
  35 capability) is required to unmount filesystems.
  36 .PP
  37 Linux 2.1.116 added the
  38 .BR umount2 ()
  39 system call, which, like
  40 .BR umount (),
  41 unmounts a target, but allows additional
  42 .I flags
  43 controlling the behavior of the operation:
  44 .TP
  45 .BR MNT_FORCE " (since Linux 2.1.116)"
  46 Ask the filesystem to abort pending requests before attempting the
  47 unmount.
  48 This may allow the unmount to complete without waiting
  49 for an inaccessible server, but could cause data loss.
  50 If, after aborting requests,
  51 some processes still have active references to the filesystem,
  52 the unmount will still fail.
  53 As at Linux 4.12,
  54 .B MNT_FORCE
  55 is supported only on the following filesystems:
  56 9p (since Linux 2.6.16),
  57 ceph (since Linux 2.6.34),
  58 cifs (since Linux 2.6.12),
  59 fuse (since Linux 2.6.16),
  60 lustre (since Linux 3.11),
  61 and NFS (since Linux 2.1.116).
  62 .TP
  63 .BR MNT_DETACH " (since Linux 2.4.11)"
  64 Perform a lazy unmount: make the mount unavailable for new
  65 accesses, immediately disconnect the filesystem and all filesystems
  66 mounted below it from each other and from the mount table, and
  67 actually perform the unmount when the mount ceases to be busy.
  68 .TP
  69 .BR MNT_EXPIRE " (since Linux 2.6.8)"
  70 Mark the mount as expired.
  71 If a mount is not currently in use, then an initial call to
  72 .BR umount2 ()
  73 with this flag fails with the error
  74 .BR EAGAIN ,
  75 but marks the mount as expired.
  76 The mount remains expired as long as it isn't accessed
  77 by any process.
  78 A second
  79 .BR umount2 ()
  80 call specifying
  81 .B MNT_EXPIRE
  82 unmounts an expired mount.
  83 This flag cannot be specified with either
  84 .B MNT_FORCE
  85 or
  86 .BR MNT_DETACH .
  87 .TP
  88 .BR UMOUNT_NOFOLLOW " (since Linux 2.6.34)"
  89 .\" Later added to 2.6.33-stable
  90 Don't dereference
  91 .I target
  92 if it is a symbolic link.
  93 This flag allows security problems to be avoided in set-user-ID-\fIroot\fP
  94 programs that allow unprivileged users to unmount filesystems.
  95 .SH RETURN VALUE
  96 On success, zero is returned.
  97 On error, \-1 is returned, and
  98 .I errno
  99 is set to indicate the error.
 100 .SH ERRORS
 101 The error values given below result from filesystem type independent
 102 errors.
 103 Each filesystem type may have its own special errors and its
 104 own special behavior.
 105 See the Linux kernel source code for details.
 106 .TP
 107 .B EAGAIN
 108 A call to
 109 .BR umount2 ()
 110 specifying
 111 .B MNT_EXPIRE
 112 successfully marked an unbusy filesystem as expired.
 113 .TP
 114 .B EBUSY
 115 .I target
 116 could not be unmounted because it is busy.
 117 .TP
 118 .B EFAULT
 119 .I target
 120 points outside the user address space.
 121 .TP
 122 .B EINVAL
 123 .I target
 124 is not a mount point.
 125 .TP
 126 .B EINVAL
 127 .I target
 128 is locked; see
 129 .BR mount_namespaces (7).
 130 .TP
 131 .B EINVAL
 132 .BR umount2 ()
 133 was called with
 134 .B MNT_EXPIRE
 135 and either
 136 .B MNT_DETACH
 137 or
 138 .BR MNT_FORCE .
 139 .TP
 140 .BR EINVAL " (since Linux 2.6.34)"
 141 .BR umount2 ()
 142 was called with an invalid flag value in
 143 .IR flags .
 144 .TP
 145 .B ENAMETOOLONG
 146 A pathname was longer than
 147 .BR MAXPATHLEN .
 148 .TP
 149 .B ENOENT
 150 A pathname was empty or had a nonexistent component.
 151 .TP
 152 .B ENOMEM
 153 The kernel could not allocate a free page to copy filenames or data into.
 154 .TP
 155 .B EPERM
 156 The caller does not have the required privileges.
 157 .SH VERSIONS
 158 .B MNT_DETACH
 159 and
 160 .B MNT_EXPIRE
 161 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=10092
 162 are available in glibc since version 2.11.
 163 .SH STANDARDS
 164 These functions are Linux-specific and should not be used in
 165 programs intended to be portable.
 166 .SH NOTES
 167 .SS umount() and shared mounts
 168 Shared mounts cause any mount activity on a mount, including
 169 .BR umount ()
 170 operations, to be forwarded to every shared mount in the
 171 peer group and every slave mount of that peer group.
 172 This means that
 173 .BR umount ()
 174 of any peer in a set of shared mounts will cause all of its
 175 peers to be unmounted and all of their slaves to be unmounted as well.
 176 .PP
 177 This propagation of unmount activity can be particularly surprising
 178 on systems where every mount is shared by default.
 179 On such systems,
 180 recursively bind mounting the root directory of the filesystem
 181 onto a subdirectory and then later unmounting that subdirectory with
 182 .B MNT_DETACH
 183 will cause every mount in the mount namespace to be lazily unmounted.
 184 .PP
 185 To ensure
 186 .BR umount ()
 187 does not propagate in this fashion,
 188 the mount may be remounted using a
 189 .BR mount (2)
 190 call with a
 191 .I mount_flags
 192 argument that includes both
 193 .B MS_REC
 194 and
 195 .B MS_PRIVATE
 196 prior to
 197 .BR umount ()
 198 being called.
 199 .SS Historical details
 200 The original
 201 .BR umount ()
 202 function was called as \fIumount(device)\fP and would return
 203 .B ENOTBLK
 204 when called with something other than a block device.
 205 In Linux 0.98p4, a call \fIumount(dir)\fP was added, in order to
 206 support anonymous devices.
 207 In Linux 2.3.99-pre7, the call \fIumount(device)\fP was removed,
 208 leaving only \fIumount(dir)\fP (since now devices can be mounted
 209 in more than one place, so specifying the device does not suffice).
 210 .SH SEE ALSO
 211 .BR mount (2),
 212 .BR mount_namespaces (7),
 213 .BR path_resolution (7),
 214 .BR mount (8),
 215 .BR umount (8)