man2/mount.2

   1 .\" Hey Emacs! This file is -*- nroff -*- source.
   2 .\"
   3 .\" Copyright (C) 1993 Rickard E. Faith <faith@cs.unc.edu>
   4 .\" and Copyright (C) 1994 Andries E. Brouwer <aeb@cwi.nl>
   5 .\" and Copyright (C) 2002, 2005 Michael Kerrisk <mtk.manpages@gmail.com>
   6 .\"
   7 .\" Permission is granted to make and distribute verbatim copies of this
   8 .\" manual provided the copyright notice and this permission notice are
   9 .\" preserved on all copies.
  10 .\"
  11 .\" Permission is granted to copy and distribute modified versions of this
  12 .\" manual under the conditions for verbatim copying, provided that the
  13 .\" entire resulting derived work is distributed under the terms of a
  14 .\" permission notice identical to this one.
  15 .\"
  16 .\" Since the Linux kernel and libraries are constantly changing, this
  17 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  18 .\" responsibility for errors or omissions, or for damages resulting from
  19 .\" the use of the information contained herein.  The author(s) may not
  20 .\" have taken the same level of care in the production of this manual,
  21 .\" which is licensed free of charge, as they might when working
  22 .\" professionally.
  23 .\"
  24 .\" Formatted or processed versions of this manual, if unaccompanied by
  25 .\" the source, must acknowledge the copyright and authors of this work.
  26 .\"
  27 .\" Modified 1996-11-04 by Eric S. Raymond <esr@thyrsus.com>
  28 .\" Modified 2001-10-13 by Michael Kerrisk <mtk.manpages@gmail.com>
  29 .\"     Added note on historical behavior of MS_NOSUID
  30 .\" Modified 2002-05-16 by Michael Kerrisk <mtk.manpages@gmail.com>
  31 .\"     Extensive changes and additions
  32 .\" Modified 2002-05-27 by aeb
  33 .\" Modified 2002-06-11 by Michael Kerrisk <mtk.manpages@gmail.com>
  34 .\"     Enhanced descriptions of MS_MOVE, MS_BIND, and MS_REMOUNT
  35 .\" Modified 2004-06-17 by Michael Kerrisk <mtk.manpages@gmail.com>
  36 .\" 2005-05-18, mtk, Added MNT_EXPIRE, plus a few other tidy-ups.
  37 .\" 2008-10-06, mtk: move umount*() material into separate umount.2 page.
  38 .\" 2008-10-06, mtk: Add discussion of namespaces.
  39 .\"
  40 .TH MOUNT 2 2008-10-06 "Linux" "Linux Programmer's Manual"
  41 .SH NAME
  42 mount \- mount file system
  43 .SH SYNOPSIS
  44 .nf
  45 .B "#include <sys/mount.h>"
  46 .sp
  47 .BI "int mount(const char *" source ", const char *" target ,
  48 .BI "          const char *" filesystemtype ", unsigned long " mountflags ,
  49 .BI "          const void *" data );
  50 .fi
  51 .SH DESCRIPTION
  52 .BR mount ()
  53 attaches the file system specified by
  54 .I source
  55 (which is often a device name, but can also be a directory name
  56 or a dummy) to the directory specified by
  57 .IR target .
  58
  59 Appropriate privilege (Linux: the
  60 .B CAP_SYS_ADMIN
  61 capability) is required to mount file systems.
  62
  63 Since Linux 2.4 a single file system can be visible at
  64 multiple mount points, and multiple mounts can be stacked
  65 on the same mount point.
  66 .\" Multiple mounts on same mount point: since 2.3.99pre7.
  67
  68 Values for the
  69 .I filesystemtype
  70 argument supported by the kernel are listed in
  71 .I /proc/filesystems
  72 (like "minix", "ext2", "ext3", "jfs", "xfs", "reiserfs",
  73 "msdos", "proc", "nfs", "iso9660" etc.).
  74 Further types may become available when the appropriate modules
  75 are loaded.
  76
  77 The
  78 .I mountflags
  79 argument may have the magic number 0xC0ED (\fBMS_MGC_VAL\fP)
  80 in the top 16 bits (this was required in kernel versions prior to 2.4, but
  81 is no longer required and ignored if specified),
  82 and various mount flags (as defined in \fI<linux/fs.h>\fP for libc4 and libc5
  83 and in \fI<sys/mount.h>\fP for glibc2) in the low order 16 bits:
  84 .\" FIXME 2.6.15 added flags for "shared sub-tree" functionality:
  85 .\" MS_UNBINDABLE, MS_PRIVATE, MS_SHARED, MS_SLAVE
  86 .\" These need to be documented on this page.
  87 .\" See:
  88 .\" Documentation/filesystems/sharedsubtree.txt
  89 .\"
  90 .\" http://lwn.net/Articles/159077/
  91 .\"
  92 .\" http://myweb.sudhaa.com:2022/~ram/sharedsubtree/paper/sharedsubtree.1.pdf
  93 .\" Shared-Subtree Concept, Implementation, and Applications in Linux
  94 .\" Al Viro viro@ftp.linux.org.uk
  95 .\" Ram Pai linuxram@us.ibm.com
  96 .\"
  97 .\" http://foss.in/2005/slides/sharedsubtree1.pdf
  98 .\" Shared Subtree Concept and Implementation in the Linux Kernel
  99 .\" Ram Pai
 100 .\"
 101 .TP
 102 .BR MS_BIND " (Linux 2.4 onwards)"
 103 .\" since 2.4.0-test9
 104 Perform a bind mount, making a file or a directory subtree visible at
 105 another point within a file system.
 106 Bind mounts may cross file system boundaries and span
 107 .BR chroot (2)
 108 jails.
 109 The
 110 .IR filesystemtype
 111 and
 112 .IR data
 113 arguments are ignored.
 114 Up until Linux 2.6.26,
 115 .I mountflags
 116 was also ignored
 117 .\" with the exception of the "hidden" MS_REC mountflags bit
 118 (the bind mount has the same mount options as
 119 the underlying mount point).
 120 Since Linux 2.6.26, the
 121 .B MS_RDONLY
 122 flag is honored when making a bind mount.
 123 .TP
 124 .BR MS_DIRSYNC " (since Linux 2.5.19)"
 125 Make directory changes on this file system synchronous.
 126 (This property can be obtained for individual directories
 127 or subtrees using
 128 .BR chattr (1).)
 129 .TP
 130 .B MS_MANDLOCK
 131 Permit mandatory locking on files in this file system.
 132 (Mandatory locking must still be enabled on a per-file basis,
 133 as described in
 134 .BR fcntl (2).)
 135 .\" FIXME Say more about MS_MOVE
 136 .TP
 137 .B MS_MOVE
 138 Move a subtree.
 139 .I source
 140 specifies an existing mount point and
 141 .I target
 142 specifies the new location.
 143 The move is atomic: at no point is the subtree unmounted.
 144 The
 145 .IR filesystemtype ", " mountflags ", and " data
 146 arguments are ignored.
 147 .TP
 148 .B MS_NOATIME
 149 Do not update access times for (all types of) files on this file system.
 150 .TP
 151 .B MS_NODEV
 152 Do not allow access to devices (special files) on this file system.
 153 .TP
 154 .B MS_NODIRATIME
 155 Do not update access times for directories on this file system.
 156 This flag provides a subset of the functionality provided by
 157 .BR MS_NOATIME ;
 158 that is,
 159 .BR MS_NOATIME
 160 implies
 161 .BR MS_NODIRATIME .
 162 .TP
 163 .B MS_NOEXEC
 164 Do not allow programs to be executed from this file system.
 165 .\" (Possibly useful for a file system that contains non-Linux executables.
 166 .\" Often used as a security feature, e.g., to make sure that restricted
 167 .\" users cannot execute files uploaded using ftp or so.)
 168 .TP
 169 .B MS_NOSUID
 170 Do not honor set-user-ID and set-group-ID bits when executing
 171 programs from this file system.
 172 .\" (This is a security feature to prevent users executing set-user-ID and
 173 .\" set-group-ID programs from removable disk devices.)
 174 .TP
 175 .B MS_RDONLY
 176 Mount file system read-only.
 177 .\"
 178 .\" FIXME Document MS_REC, available since 2.4.11.
 179 .\" This flag has meaning in conjunction with MS_BIND and
 180 .\" also with the shared sub-tree flags.
 181 .TP
 182 .BR MS_RELATIME " (Since Linux 2.6.20)"
 183 When a file on this file system is accessed,
 184 only update the file's last access time (atime) if the current value
 185 of atime is less than or equal to the file's last modification time (mtime)
 186 or last status change time (ctime).
 187 This option is useful for programs, such as
 188 .BR mutt (1),
 189 that need to know when a file has been read since it was last modified.
 190 .TP
 191 .B MS_REMOUNT
 192 Remount an existing mount.
 193 This allows you to change the
 194 .I mountflags
 195 and
 196 .I data
 197 of an existing mount without having to unmount and remount the file system.
 198 .I source
 199 and
 200 .I target
 201 should be the same values specified in the initial
 202 .BR mount ()
 203 call;
 204 .I filesystemtype
 205 is ignored.
 206
 207 The following
 208 .I mountflags
 209 can be changed:
 210 .BR MS_RDONLY ,
 211 .BR MS_SYNCHRONOUS ,
 212 .BR MS_MANDLOCK ;
 213 before kernel 2.6.16, the following could also be changed:
 214 .B MS_NOATIME
 215 and
 216 .BR MS_NODIRATIME ;
 217 and, additionally, before kernel 2.4.10, the following could also be changed:
 218 .BR MS_NOSUID ,
 219 .BR MS_NODEV ,
 220 .BR MS_NOEXEC .
 221 .TP
 222 .BR MS_SILENT " (since Linux 2.6.17)"
 223 Suppress the display of certain
 224 .RI ( printk ())
 225 warning messages in the kernel log.
 226 This flag supersedes the misnamed and obsolete
 227 .BR MS_VERBOSE
 228 flag (available since Linux 2.4.12), which has the same meaning.
 229 .TP
 230 .B MS_SYNCHRONOUS
 231 Make writes on this file system synchronous (as though
 232 the
 233 .B O_SYNC
 234 flag to
 235 .BR open (2)
 236 was specified for all file opens to this file system).
 237 .PP
 238 From Linux 2.4 onwards, the
 239 .BR MS_NODEV ", " MS_NOEXEC ", and " MS_NOSUID
 240 flags are settable on a per-mount-point basis.
 241 From kernel 2.6.16 onwards,
 242 .B MS_NOATIME
 243 and
 244 .B MS_NODIRATIME
 245 are also settable on a per-mount-point basis.
 246 The
 247 .B MS_RELATIME
 248 flag is also settable on a per-mount-point basis.
 249 .PP
 250 The
 251 .I data
 252 argument is interpreted by the different file systems.
 253 Typically it is a string of comma-separated options
 254 understood by this file system.
 255 See
 256 .BR mount (8)
 257 for details of the options available for each filesystem type.
 258 .SH "RETURN VALUE"
 259 On success, zero is returned.
 260 On error, \-1 is returned, and
 261 .I errno
 262 is set appropriately.
 263 .SH ERRORS
 264 The error values given below result from filesystem type independent
 265 errors.
 266 Each filesystem type may have its own special errors and its
 267 own special behavior.
 268 See the kernel source code for details.
 269 .TP
 270 .B EACCES
 271 A component of a path was not searchable.
 272 (See also
 273 .BR path_resolution (7).)
 274 Or, mounting a read-only filesystem was attempted without giving the
 275 .B MS_RDONLY
 276 flag.
 277 Or, the block device
 278 .I source
 279 is located on a filesystem mounted with the
 280 .B MS_NODEV
 281 option.
 282 .\" mtk: Probably: write permission is required for MS_BIND, with
 283 .\" the error EPERM if not present; CAP_DAC_OVERRIDE is required.
 284 .TP
 285 .B EBUSY
 286 .I source
 287 is already mounted.
 288 Or, it cannot be remounted read-only,
 289 because it still holds files open for writing.
 290 Or, it cannot be mounted on
 291 .I target
 292 because
 293 .I target
 294 is still busy (it is the working directory of some task,
 295 the mount point of another device, has open files, etc.).
 296 .TP
 297 .B EFAULT
 298 One of the pointer arguments points outside the user address space.
 299 .TP
 300 .B EINVAL
 301 .I source
 302 had an invalid superblock.
 303 Or, a remount
 304 .RB ( MS_REMOUNT )
 305 was attempted, but
 306 .I source
 307 was not already mounted on
 308 .IR target .
 309 Or, a move
 310 .RB ( MS_MOVE )
 311 was attempted, but
 312 .I source
 313 was not a mount point, or was \(aq/\(aq.
 314 .TP
 315 .B ELOOP
 316 Too many links encountered during pathname resolution.
 317 Or, a move was attempted, while
 318 .I target
 319 is a descendant of
 320 .IR source .
 321 .TP
 322 .B EMFILE
 323 (In case no block device is required:)
 324 Table of dummy devices is full.
 325 .TP
 326 .B ENAMETOOLONG
 327 A pathname was longer than
 328 .BR MAXPATHLEN .
 329 .TP
 330 .B ENODEV
 331 .I filesystemtype
 332 not configured in the kernel.
 333 .TP
 334 .B ENOENT
 335 A pathname was empty or had a nonexistent component.
 336 .TP
 337 .B ENOMEM
 338 The kernel could not allocate a free page to copy filenames or data into.
 339 .TP
 340 .B ENOTBLK
 341 .I source
 342 is not a block device (and a device was required).
 343 .TP
 344 .B ENOTDIR
 345 .IR target ,
 346 or a prefix of
 347 .IR source ,
 348 is not a directory.
 349 .TP
 350 .B ENXIO
 351 The major number of the block device
 352 .I source
 353 is out of range.
 354 .TP
 355 .B EPERM
 356 The caller does not have the required privileges.
 357 .SH "CONFORMING TO"
 358 This function is Linux-specific and should not be used in
 359 programs intended to be portable.
 360 .SH NOTES
 361 The original
 362 .B MS_SYNC
 363 flag was renamed
 364 .B MS_SYNCHRONOUS
 365 in 1.1.69
 366 when a different
 367 .B MS_SYNC
 368 was added to \fI<mman.h>\fP.
 369 .LP
 370 Before Linux 2.4 an attempt to execute a set-user-ID or set-group-ID program
 371 on a filesystem mounted with
 372 .B MS_NOSUID
 373 would fail with
 374 .BR EPERM .
 375 Since Linux 2.4 the set-user-ID and set-group-ID bits are
 376 just silently ignored in this case.
 377 .\" The change is in patch-2.4.0-prerelease.
 378 .SS Per-process Namespaces
 379 Starting with kernel 2.4.19, Linux provides per-process namespaces.
 380 A namespace is the set of file system mounts that are visible to a process.
 381 Namespaces can be (and usually are) shared between multiple processes,
 382 and changes to the namespace (i.e., mounts and unmounts) by one process
 383 are visible to all other processes sharing the same namespace.
 384 (The pre-2.4.19 situation can be considered as one in which there was
 385 a single namespace was shared by every process on the system.)
 386
 387 A child process created by
 388 .BR fork (2)
 389 shares its parent's namespace;
 390 the namespace is preserved across an
 391 .BR execve (2).
 392
 393 A process can obtain a private namespace if:
 394 it was created using the
 395 .BR clone ()
 396 .BR CLONE_NEWNS
 397 flag,
 398 in which case its new namespace is initialized to be a
 399 .I copy
 400 of the namespace of the process that called
 401 .BR clone ();
 402 or it calls
 403 .BR unshare (2)
 404 with the
 405 .BR CLONE_NEWNS
 406 flag,
 407 which causes the caller's namespace to obtain a private copy
 408 of the namespace that it was previously sharing with other processes,
 409 so that future mounts and unmounts by the caller are invisible
 410 to other processes (except child processes that the caller
 411 subsequently creates) and vice versa.
 412
 413 The Linux-specific
 414 .I /proc/PID/self
 415 file exposes the list of mount points in the namespace of the process with
 416 the specified ID; see
 417 .BR proc (5)
 418 for details.
 419 .SH "SEE ALSO"
 420 .BR umount (2),
 421 .BR path_resolution (7),
 422 .BR mount (8),
 423 .BR umount (8)