]> git.ipfire.org Git - thirdparty/man-pages.git/blame - man2/mount.2
getent.1, iconv.1, intro.1, ldd.1, locale.1, localedef.1, memusage.1, memusagestat...
[thirdparty/man-pages.git] / man2 / mount.2
CommitLineData
fea681da 1.\" Copyright (C) 1993 Rickard E. Faith <faith@cs.unc.edu>
6883b3e7 2.\" and Copyright (C) 1994 Andries E. Brouwer <aeb@cwi.nl>
eac1e050 3.\" and Copyright (C) 2002, 2005, 2016 Michael Kerrisk <mtk.manpages@gmail.com>
fea681da 4.\"
5fbde956 5.\" SPDX-License-Identifier: Linux-man-pages-copyleft
fea681da
MK
6.\"
7.\" Modified 1996-11-04 by Eric S. Raymond <esr@thyrsus.com>
c11b1abf 8.\" Modified 2001-10-13 by Michael Kerrisk <mtk.manpages@gmail.com>
d9bfdb9c 9.\" Added note on historical behavior of MS_NOSUID
c11b1abf 10.\" Modified 2002-05-16 by Michael Kerrisk <mtk.manpages@gmail.com>
fea681da
MK
11.\" Extensive changes and additions
12.\" Modified 2002-05-27 by aeb
c11b1abf 13.\" Modified 2002-06-11 by Michael Kerrisk <mtk.manpages@gmail.com>
fea681da 14.\" Enhanced descriptions of MS_MOVE, MS_BIND, and MS_REMOUNT
c11b1abf 15.\" Modified 2004-06-17 by Michael Kerrisk <mtk.manpages@gmail.com>
8df37e4d 16.\" 2005-05-18, mtk, Added MNT_EXPIRE, plus a few other tidy-ups.
0a4d78bb
MK
17.\" 2008-10-06, mtk: move umount*() material into separate umount.2 page.
18.\" 2008-10-06, mtk: Add discussion of namespaces.
fea681da 19.\"
17285b25 20.TH MOUNT 2 2022-09-09 "Linux man-pages (unreleased)"
fea681da 21.SH NAME
9ee4a2b6 22mount \- mount filesystem
9c84219f
AC
23.SH LIBRARY
24Standard C library
8fc3b2cf 25.RI ( libc ", " \-lc )
fea681da 26.SH SYNOPSIS
7998dde2 27.nf
fea681da 28.B "#include <sys/mount.h>"
68e4db0a 29.PP
fea681da 30.BI "int mount(const char *" source ", const char *" target ,
7998dde2
MK
31.BI " const char *" filesystemtype ", unsigned long " mountflags ,
32.BI " const void *" data );
7998dde2 33.fi
fea681da 34.SH DESCRIPTION
e511ffb6 35.BR mount ()
9ee4a2b6 36attaches the filesystem specified by
fea681da 37.I source
751de899
MK
38(which is often a pathname referring to a device,
39but can also be the pathname of a directory or file,
40or a dummy string) to the location (a directory or file)
41specified by the pathname in
fea681da 42.IR target .
547ee319 43.PP
fea681da
MK
44Appropriate privilege (Linux: the
45.B CAP_SYS_ADMIN
9ee4a2b6 46capability) is required to mount filesystems.
547ee319 47.PP
fea681da 48Values for the
0daa9e92 49.I filesystemtype
fea681da
MK
50argument supported by the kernel are listed in
51.I /proc/filesystems
9792cd16
MK
52(e.g., "btrfs", "ext4", "jfs", "xfs", "vfat", "fuse",
53"tmpfs", "cgroup", "proc", "mqueue", "nfs", "cifs", "iso9660").
fea681da
MK
54Further types may become available when the appropriate modules
55are loaded.
547ee319 56.PP
b3ae9c7d
MK
57The
58.I data
59argument is interpreted by the different filesystems.
60Typically it is a string of comma-separated options
61understood by this filesystem.
62See
63.BR mount (8)
64for details of the options available for each filesystem type.
c43f976f 65This argument may be specified as NULL, if there are no options.
547ee319 66.PP
f429fadc
MK
67A call to
68.BR mount ()
c3a7b4e9 69performs one of a number of general types of operation,
f429fadc
MK
70depending on the bits specified in
71.IR mountflags .
c3a7b4e9
MK
72The choice of which operation to perform is determined by
73testing the bits set in
f429fadc
MK
74.IR mountflags ,
75with the tests being conducted in the order listed here:
76.IP * 3
77Remount an existing mount:
1ae6b2c7 78.I mountflags
f429fadc
MK
79includes
80.BR MS_REMOUNT .
81.IP *
82Create a bind mount:
1ae6b2c7 83.I mountflags
f429fadc
MK
84includes
85.BR MS_BIND .
86.IP *
87Change the propagation type of an existing mount:
1ae6b2c7 88.I mountflags
f429fadc
MK
89includes one of
90.BR MS_SHARED ,
91.BR MS_PRIVATE ,
92.BR MS_SLAVE ,
93or
94.BR MS_UNBINDABLE .
95.IP *
96Move an existing mount to a new location:
1ae6b2c7 97.I mountflags
f429fadc
MK
98includes
99.BR MS_MOVE .
100.IP *
101Create a new mount:
1ae6b2c7 102.I mountflags
f429fadc
MK
103includes none of the above flags.
104.PP
105Each of these operations is detailed later in this page.
106Further flags may be specified in
1ae6b2c7 107.I mountflags
f429fadc
MK
108to modify the behavior of
109.BR mount (),
110as described below.
2835e6c5 111.\"
f429fadc
MK
112.SS Additional mount flags
113The list below describes the additional flags that can be specified in
114.IR mountflags .
115Note that some operation types ignore some or all of these flags,
116as described later in this page.
2835e6c5 117.\"
bea08fec 118.\" FIXME 2.6.25 Added MS_I_VERSION, which needs to be documented.
fa4c100d
MK
119.\" commit 7a224228ed79d587ece2304869000aad1b8e97dd
120.\" (This is a per-superblock flag)
21d995a8 121.\"
fea681da 122.TP
8df37e4d 123.BR MS_DIRSYNC " (since Linux 2.5.19)"
9ee4a2b6 124Make directory changes on this filesystem synchronous.
fea681da
MK
125(This property can be obtained for individual directories
126or subtrees using
49ec013c 127.BR chattr (1).)
fea681da 128.TP
9b249562 129.BR MS_LAZYTIME " (since Linux 4.0)"
42a8e396
MK
130.\" commit 0ae45f63d4ef8d8eeec49c7d8b44a1775fff13e8
131.\" commit fe032c422c5ba562ba9c2d316f55e258e03259c6
132.\" commit a26f49926da938f47561f386be56a83dd37a496d
133Reduce on-disk updates of inode timestamps (atime, mtime, ctime)
134by maintaining these changes only in memory.
135The on-disk timestamps are updated only when:
136.RS
3ab99460 137.IP (a) 4
42a8e396
MK
138the inode needs to be updated for some change unrelated to file timestamps;
139.IP (b)
140the application employs
141.BR fsync (2),
142.BR syncfs (2),
143or
144.BR sync (2);
145.IP (c)
146an undeleted inode is evicted from memory; or
147.IP (d)
148more than 24 hours have passed since the inode was written to disk.
149.RE
150.IP
5eab76af 151This mount option significantly reduces writes
9cdabfa6
MK
152needed to update the inode's timestamps, especially mtime and atime.
153However, in the event of a system crash, the atime and mtime fields
154on disk might be out of date by up to 24 hours.
054ea65e 155.IP
9cdabfa6
MK
156Examples of workloads where this option could be of significant benefit
157include frequent random writes to preallocated files,
158as well as cases where the
159.B MS_STRICTATIME
160mount option is also enabled.
cdd14e51 161(The advantage of combining
1ae6b2c7 162.B MS_STRICTATIME
cdd14e51 163and
1ae6b2c7 164.B MS_LAZYTIME
9cdabfa6
MK
165is that
166.BR stat (2)
167will return the correctly updated atime, but the atime updates
5eab76af 168will be flushed to disk only in the cases listed above.)
42a8e396 169.TP
fea681da 170.B MS_MANDLOCK
9ee4a2b6 171Permit mandatory locking on files in this filesystem.
fea681da
MK
172(Mandatory locking must still be enabled on a per-file basis,
173as described in
174.BR fcntl (2).)
afa0b44d
MK
175Since Linux 4.5,
176.\" commit 95ace75414f312f9a7b93d873f386987b92a5301
177this mount option requires the
178.B CAP_SYS_ADMIN
41976bc5
MK
179capability and a kernel configured with the
180.B CONFIG_MANDATORY_FILE_LOCKING
181option.
62d23b18
JL
182Mandatory locking has been fully deprecated in v5.15 kernels, so
183this flag should be considered deprecated.
fea681da 184.TP
fea681da 185.B MS_NOATIME
9ee4a2b6 186Do not update access times for (all types of) files on this filesystem.
fea681da
MK
187.TP
188.B MS_NODEV
9ee4a2b6 189Do not allow access to devices (special files) on this filesystem.
fea681da
MK
190.TP
191.B MS_NODIRATIME
9ee4a2b6 192Do not update access times for directories on this filesystem.
882a9435
MK
193This flag provides a subset of the functionality provided by
194.BR MS_NOATIME ;
195that is,
1ae6b2c7 196.B MS_NOATIME
882a9435
MK
197implies
198.BR MS_NODIRATIME .
fea681da
MK
199.TP
200.B MS_NOEXEC
9ee4a2b6
MK
201Do not allow programs to be executed from this filesystem.
202.\" (Possibly useful for a filesystem that contains non-Linux executables.
75b94dc3 203.\" Often used as a security feature, e.g., to make sure that restricted
fea681da
MK
204.\" users cannot execute files uploaded using ftp or so.)
205.TP
206.B MS_NOSUID
4be9e801 207Do not honor set-user-ID and set-group-ID bits or file capabilities
9593da4d
MK
208when executing programs from this filesystem.
209In addition, SELinux domain
210transitions require the permission
211.IR nosuid_transition ,
212which in turn needs
213also the policy capability
214.IR nnp_nosuid_transition .
880f5b4b
MK
215.\" (This is a security feature to prevent users executing set-user-ID and
216.\" set-group-ID programs from removable disk devices.)
fea681da
MK
217.TP
218.B MS_RDONLY
9ee4a2b6 219Mount filesystem read-only.
eac1e050
MK
220.TP
221.BR MS_REC " (since Linux 2.4.11)"
222Used in conjunction with
1ae6b2c7 223.B MS_BIND
eac1e050
MK
224to create a recursive bind mount,
225and in conjunction with the propagation type flags to recursively change
226the propagation type of all of the mounts in a subtree.
227See below for further details.
c13182ef 228.TP
31c1f2b0 229.BR MS_RELATIME " (since Linux 2.6.20)"
9ee4a2b6 230When a file on this filesystem is accessed,
33a0ccb2 231update the file's last access time (atime) only if the current value
7c40de08 232of atime is less than or equal to the file's last modification time (mtime)
926b6e37
MK
233or last status change time (ctime).
234This option is useful for programs, such as
235.BR mutt (1),
236that need to know when a file has been read since it was last modified.
02a4e226
MK
237Since Linux 2.6.30, the kernel defaults to the behavior provided
238by this flag (unless
1ae6b2c7 239.B MS_NOATIME
02a4e226
MK
240was specified), and the
241.B MS_STRICTATIME
242flag is required to obtain traditional semantics.
243In addition, since Linux 2.6.30,
244the file's last access time is always updated if it
245is more than 1 day old.
246.\" Matthew Garrett notes in the patch that added this behavior
247.\" that this lets utilities such as tmpreaper (which deletes
5116355c 248.\" files based on last access time) work correctly.
fea681da 249.TP
f429fadc
MK
250.BR MS_SILENT " (since Linux 2.6.17)"
251Suppress the display of certain
252.RI ( printk ())
253warning messages in the kernel log.
254This flag supersedes the misnamed and obsolete
1ae6b2c7 255.B MS_VERBOSE
f429fadc
MK
256flag (available since Linux 2.4.12), which has the same meaning.
257.TP
258.BR MS_STRICTATIME " (since Linux 2.6.30)"
259Always update the last access time (atime) when files on this
260filesystem are accessed.
261(This was the default behavior before Linux 2.6.30.)
262Specifying this flag overrides the effect of setting the
1ae6b2c7 263.B MS_NOATIME
f429fadc 264and
1ae6b2c7 265.B MS_RELATIME
f429fadc
MK
266flags.
267.TP
268.B MS_SYNCHRONOUS
269Make writes on this filesystem synchronous (as though
270the
271.B O_SYNC
272flag to
273.BR open (2)
274was specified for all file opens to this filesystem).
527375b2 275.TP
97ba2b53
MK
276.BR MS_NOSYMFOLLOW " (since Linux 5.10)"
277.\" dab741e0e02bd3c4f5e2e97be74b39df2523fc6e
278Do not follow symbolic links when resolving paths.
279Symbolic links can still be created,
527375b2
RZ
280and
281.BR readlink (1),
282.BR readlink (2),
d556548b 283.BR realpath (1),
527375b2
RZ
284and
285.BR realpath (3)
286all still work properly.
f429fadc 287.PP
63b0b1a3
MK
288From Linux 2.4 onward, some of the above flags are
289settable on a per-mount basis,
290while others apply to the superblock of the mounted filesystem,
291meaning that all mounts of the same filesystem share those flags.
292(Previously, all of the flags were per-superblock.)
293.PP
294The per-mount-point flags are as follows:
295.IP * 3
296Since Linux 2.4:
f429fadc
MK
297.BR MS_NODEV ", " MS_NOEXEC ", and " MS_NOSUID
298flags are settable on a per-mount-point basis.
63b0b1a3 299.IP *
e7497fba 300Additionally, since Linux 2.6.16:
f429fadc
MK
301.B MS_NOATIME
302and
63b0b1a3
MK
303.BR MS_NODIRATIME .
304.IP *
e7497fba 305Additionally, since Linux 2.6.20:
63b0b1a3
MK
306.BR MS_RELATIME .
307.PP
308The following flags are per-superblock:
309.BR MS_DIRSYNC ,
310.BR MS_LAZYTIME ,
311.BR MS_MANDLOCK ,
e0e0ba7d 312.BR MS_SILENT ,
63b0b1a3
MK
313and
314.BR MS_SYNCHRONOUS .
315.\" And MS_I_VERSION?
46183bb0 316The initial settings of these flags are determined on the first
63b0b1a3
MK
317mount of the filesystem, and will be shared by all subsequent mounts
318of the same filesystem.
319Subsequently, the settings of the flags can be changed
320via a remount operation (see below).
525a8b54 321Such changes will be visible via all mounts associated
63b0b1a3
MK
322with the filesystem.
323.PP
c84a8779
N
324Since Linux 2.6.16,
325.B MS_RDONLY
326can be set or cleared on a per-mount-point basis as well as on
63b0b1a3 327the underlying filesystem superblock.
9edbd686
MK
328The mounted filesystem will be writable only if neither the filesystem
329nor the mountpoint are flagged as read-only.
f429fadc
MK
330.\"
331.SS Remounting an existing mount
332An existing mount may be remounted by specifying
fea681da 333.B MS_REMOUNT
f429fadc
MK
334in
335.IR mountflags .
599e5da7 336This allows you to change the
fea681da
MK
337.I mountflags
338and
339.I data
9ee4a2b6 340of an existing mount without having to unmount and remount the filesystem.
fea681da 341.I target
44535dd2 342should be the same value specified in the initial
fea681da 343.BR mount ()
74b46b5f 344call.
547ee319 345.PP
74b46b5f 346The
44535dd2
MK
347.I source
348and
fea681da 349.I filesystemtype
74b46b5f 350arguments are ignored.
547ee319 351.PP
69b6b231
EB
352The
353.I mountflags
354and
355.I data
356arguments should match the values used in the original
357.BR mount ()
358call, except for those parameters that are being deliberately changed.
a4222367 359.PP
178b977b 360The following
c13182ef 361.I mountflags
178b977b 362can be changed:
9c2678e6 363.BR MS_LAZYTIME ,
495a1a89
MK
364.\" FIXME
365.\" MS_LAZYTIME seems to be available only on a few filesystems,
366.\" and on ext4, it seems (from experiment that this flag
367.\" can only be enabled (but not disabled) on a remount.
368.\" The following code in ext4_remount() (kernel 4.17) seems to
369.\" confirm this:
370.\"
371.\" if (*flags & SB_LAZYTIME)
372.\" sb->s_flags |= SB_LAZYTIME;
014b17c6
MK
373.BR MS_MANDLOCK ,
374.BR MS_NOATIME ,
178b977b 375.BR MS_NODEV ,
014b17c6
MK
376.BR MS_NODIRATIME ,
377.BR MS_NOEXEC ,
378.BR MS_NOSUID ,
9c2678e6 379.BR MS_RELATIME ,
014b17c6 380.BR MS_RDONLY ,
1ae6b2c7 381.B MS_STRICTATIME
849971a1 382(whose effect is to clear the
1ae6b2c7 383.B MS_NOATIME
849971a1 384and
1ae6b2c7 385.B MS_RELATIME
849971a1 386flags),
16008a41 387and
014b17c6 388.BR MS_SYNCHRONOUS .
d8b67bc9 389Attempts to change the setting of the
e0a21e13 390.\" See the definition of MS_RMT_MASK in include/uapi/linux/fs.h,
f66b1d8b
MK
391.\" which excludes MS_DIRSYNC and MS_SILENT, although SB_DIRSYNC
392.\" and SB_SILENT are split out as per-superblock flags in do_mount()
393.\" (Linux 4.17 source code)
1ae6b2c7 394.B MS_DIRSYNC
f66b1d8b 395and
1ae6b2c7 396.B MS_SILENT
f66b1d8b 397flags during a remount are silently ignored.
38ea2e76 398Note that changes to per-superblock flags are visible via
525a8b54
MK
399all mounts of the associated filesystem
400(because the per-superblock flags are shared by all mounts).
547ee319 401.PP
49f68546
MK
402Since Linux 3.17,
403.\" commit ffbc6f0ead47fa5a1dc9642b0331cb75c20a640e
404if none of
405.BR MS_NOATIME ,
406.BR MS_NODIRATIME ,
407.BR MS_RELATIME ,
408or
1ae6b2c7 409.B MS_STRICTATIME
49f68546
MK
410is specified in
411.IR mountflags ,
412then the remount operation preserves the existing values of these flags
413(rather than defaulting to
414.BR MS_RELATIME ).
a4222367 415.PP
5ea1abf8 416Since Linux 2.6.26, the
0610c6f1 417.B MS_REMOUNT
5ea1abf8 418flag can be used with
c84a8779 419.B MS_BIND
a4222367 420to modify only the per-mount-point flags.
f5da58a8 421.\" See https://lwn.net/Articles/281157/
c84a8779 422This is particularly useful for setting or clearing the "read-only"
525a8b54 423flag on a mount without changing the underlying filesystem.
c84a8779 424Specifying
1ae6b2c7 425.I mountflags
f5da58a8 426as:
a4222367 427.PP
e56ab30d
MK
428.in +4n
429.EX
430MS_REMOUNT | MS_BIND | MS_RDONLY
431.EE
432.in
a4222367 433.PP
c84a8779 434will make access through this mountpoint read-only, without affecting
525a8b54 435other mounts.
f429fadc
MK
436.\"
437.SS Creating a bind mount
438If
439.I mountflags
440includes
1ae6b2c7 441.B MS_BIND
f429fadc
MK
442(available since Linux 2.4),
443.\" since 2.4.0-test9
444then perform a bind mount.
445A bind mount makes a file or a directory subtree visible at
446another point within the single directory hierarchy.
447Bind mounts may cross filesystem boundaries and span
448.BR chroot (2)
449jails.
547ee319 450.PP
f429fadc 451The
1ae6b2c7 452.I filesystemtype
02a4e226 453and
1ae6b2c7 454.I data
f429fadc 455arguments are ignored.
547ee319 456.PP
fca61050
MK
457The remaining bits (other than
458.BR MS_REC ,
459described below) in the
f429fadc 460.I mountflags
fca61050 461argument are also ignored.
f429fadc 462(The bind mount has the same mount options as
525a8b54 463the underlying mount.)
f429fadc
MK
464However, see the discussion of remounting above,
465for a method of making an existing bind mount read-only.
547ee319 466.PP
eac1e050
MK
467By default, when a directory is bind mounted,
468only that directory is mounted;
469if there are any submounts under the directory tree,
470they are not bind mounted.
471If the
1ae6b2c7 472.B MS_REC
eac1e050
MK
473flag is also specified, then a recursive bind mount operation is performed:
474all submounts under the
475.I source
476subtree (other than unbindable mounts)
477are also bind mounted at the corresponding location in the
478.I target
479subtree.
f429fadc
MK
480.\"
481.SS Changing the propagation type of an existing mount
c8e5f558 482If
1ae6b2c7 483.I mountflags
c8e5f558
MK
484includes one of
485.BR MS_SHARED ,
486.BR MS_PRIVATE ,
487.BR MS_SLAVE ,
488or
1ae6b2c7 489.B MS_UNBINDABLE
c8e5f558
MK
490(all available since Linux 2.6.15),
491then the propagation type of an existing mount is changed.
492If more than one of these flags is specified, an error results.
547ee319 493.PP
158c5bc0
MK
494The only other flags that can be specified while changing
495the propagation type are
1ae6b2c7 496.B MS_REC
2008f97d 497(described below) and
1ae6b2c7 498.B MS_SILENT
182c1e83 499(which is ignored).
547ee319 500.PP
c8e5f558
MK
501The
502.IR source ,
503.IR filesystemtype ,
504and
1ae6b2c7 505.I data
c8e5f558 506arguments are ignored.
547ee319 507.PP
c8e5f558
MK
508The meanings of the propagation type flags are as follows:
509.TP
1ae6b2c7 510.B MS_SHARED
525a8b54
MK
511Make this mount shared.
512Mount and unmount events immediately under this mount will propagate
513to the other mounts that are members of this mount's peer group.
c8e5f558 514Propagation here means that the same mount or unmount will automatically
525a8b54 515occur under all of the other mounts in the peer group.
c8e5f558 516Conversely, mount and unmount events that take place under
525a8b54 517peer mounts will propagate to this mount.
c8e5f558 518.TP
1ae6b2c7 519.B MS_PRIVATE
525a8b54
MK
520Make this mount private.
521Mount and unmount events do not propagate into or out of this mount.
c8e5f558 522.TP
1ae6b2c7 523.B MS_SLAVE
525a8b54 524If this is a shared mount that is a member of a peer group
c8e5f558 525that contains other members, convert it to a slave mount.
525a8b54 526If this is a shared mount that is a member of a peer group
c8e5f558 527that contains no other members, convert it to a private mount.
525a8b54 528Otherwise, the propagation type of the mount is left unchanged.
054ea65e 529.IP
525a8b54
MK
530When a mount is a slave,
531mount and unmount events propagate into this mount from
c8e5f558 532the (master) shared peer group of which it was formerly a member.
525a8b54 533Mount and unmount events under this mount do not propagate to any peer.
054ea65e 534.IP
525a8b54 535A mount can be the slave of another peer group
c8e5f558
MK
536while at the same time sharing mount and unmount events
537with a peer group of which it is a member.
538.TP
1ae6b2c7 539.B MS_UNBINDABLE
c8e5f558
MK
540Make this mount unbindable.
541This is like a private mount,
542and in addition this mount can't be bind mounted.
543When a recursive bind mount
bf7bc8b8 544.RB ( mount ()
c8e5f558 545with the
1ae6b2c7 546.B MS_BIND
c8e5f558 547and
1ae6b2c7 548.B MS_REC
c8e5f558 549flags) is performed on a directory subtree,
d70a2e57 550any unbindable mounts within the subtree are automatically pruned
c8e5f558
MK
551(i.e., not replicated)
552when replicating that subtree to produce the target subtree.
eac1e050
MK
553.PP
554By default, changing the propagation type affects only the
555.I target
525a8b54 556mount.
eac1e050
MK
557If the
558.B MS_REC
559flag is also specified in
560.IR mountflags ,
525a8b54 561then the propagation type of all mounts under
1ae6b2c7 562.I target
eac1e050 563is also changed.
547ee319 564.PP
472bbe3b
MK
565For further details regarding mount propagation types
566(including the default propagation type assigned to new mounts), see
b7b79845 567.BR mount_namespaces (7).
f429fadc
MK
568.\"
569.SS Moving a mount
570If
571.I mountflags
572contains the flag
1ae6b2c7 573.B MS_MOVE
4a19136b 574(available since Linux 2.4.18),
f429fadc
MK
575then move a subtree:
576.I source
525a8b54 577specifies an existing mount and
f429fadc 578.I target
525a8b54 579specifies the new location to which that mount is to be relocated.
f429fadc 580The move is atomic: at no point is the subtree unmounted.
547ee319 581.PP
f429fadc 582The remaining bits in the
1ae6b2c7 583.I mountflags
f429fadc 584argument are ignored, as are the
1ae6b2c7 585.I filesystemtype
564d9941 586and
1ae6b2c7 587.I data
f429fadc
MK
588arguments.
589.\"
525a8b54 590.SS Creating a new mount
f429fadc
MK
591If none of
592.BR MS_REMOUNT ,
593.BR MS_BIND ,
594.BR MS_MOVE ,
595.BR MS_SHARED ,
596.BR MS_PRIVATE ,
597.BR MS_SLAVE ,
598or
1ae6b2c7 599.B MS_UNBINDABLE
f429fadc
MK
600is specified in
601.IR mountflags ,
602then
603.BR mount ()
525a8b54 604performs its default action: creating a new mount.
1ae6b2c7 605.I source
525a8b54 606specifies the source for the new mount, and
1ae6b2c7 607.I target
f429fadc 608specifies the directory at which to create the mount point.
547ee319 609.PP
c13182ef 610The
f429fadc
MK
611.I filesystemtype
612and
613.I data
614arguments are employed, and further bits may be specified in
1ae6b2c7 615.I mountflags
f429fadc
MK
616to modify the behavior of the call.
617.\"
d282bb24 618.SH RETURN VALUE
c13182ef
MK
619On success, zero is returned.
620On error, \-1 is returned, and
fea681da 621.I errno
f6a4078b 622is set to indicate the error.
fea681da
MK
623.SH ERRORS
624The error values given below result from filesystem type independent
c13182ef 625errors.
9ee4a2b6 626Each filesystem type may have its own special errors and its
c13182ef 627own special behavior.
66a9882e 628See the Linux kernel source code for details.
fea681da
MK
629.TP
630.B EACCES
c13182ef
MK
631A component of a path was not searchable.
632(See also
ad7cc990 633.BR path_resolution (7).)
9e1ae4f8
MK
634.TP
635.B EACCES
636Mounting a read-only filesystem was attempted without giving the
c13182ef 637.B MS_RDONLY
8df37e4d 638flag.
ed6d1908 639.IP
f83eb6bf 640The filesystem may be read-only for various reasons, including:
ed6d1908
MK
641it resides on a read-only optical disk;
642it is resides on a device with a physical switch that has been set to
643mark the device read-only;
644the filesystem implementation was compiled with read-only support;
645or errors were detected when initially mounting the filesystem,
646so that it was marked read-only
647and can't be remounted as read-write (until the errors are fixed).
1c1ccb2c
MK
648.IP
649Some filesystems instead return the error
1ae6b2c7 650.B EROFS
1c1ccb2c 651on an attempt to mount a read-only filesystem.
9e1ae4f8
MK
652.TP
653.B EACCES
654The block device
fea681da 655.I source
9ee4a2b6 656is located on a filesystem mounted with the
8df37e4d
MK
657.B MS_NODEV
658option.
fea681da
MK
659.\" mtk: Probably: write permission is required for MS_BIND, with
660.\" the error EPERM if not present; CAP_DAC_OVERRIDE is required.
661.TP
662.B EBUSY
050f3494
MK
663An attempt was made to stack a new mount directly on
664top of an existing mount point that was created in this
665mount namespace with the same
666.I source
667and
668.IR target .
669.TP
670.B EBUSY
9e1ae4f8
MK
671.I source
672cannot be remounted read-only,
fea681da 673because it still holds files open for writing.
9e1ae4f8 674.TP
fea681da
MK
675.B EFAULT
676One of the pointer arguments points outside the user address space.
677.TP
678.B EINVAL
679.I source
680had an invalid superblock.
9e1ae4f8
MK
681.TP
682.B EINVAL
683A remount operation
8df37e4d
MK
684.RB ( MS_REMOUNT )
685was attempted, but
fea681da
MK
686.I source
687was not already mounted on
688.IR target .
9e1ae4f8
MK
689.TP
690.B EINVAL
691A move operation
8df37e4d 692.RB ( MS_MOVE )
6f4a00d6
MK
693was attempted, but the mount tree under
694.I source
695includes unbindable mounts and
696.I target
525a8b54 697is a mount that has propagation type
6f4a00d6
MK
698.BR MS_SHARED .
699.TP
700.B EINVAL
701A move operation
702.RB ( MS_MOVE )
703was attempted, but the parent mount of
704.I source
705mount has propagation type
706.BR MS_SHARED .
707.TP
708.B EINVAL
709A move operation
710.RB ( MS_MOVE )
8df37e4d 711was attempted, but
fea681da 712.I source
525a8b54 713was not a mount, or was \(aq/\(aq.
fea681da 714.TP
c8e5f558 715.B EINVAL
16170fbc
MK
716A bind operation
717.RB ( MS_BIND )
718was requested where
719.I source
720referred a mount namespace magic link (i.e., a
721.I /proc/[pid]/ns/mnt
722magic link or a bind mount to such a link)
723and the propagation type of the parent mount of
724.I target
725was
726.BR MS_SHARED ,
727.\" See commit 8823c079ba7136dc1948d6f6dcb5f8022bde438e
728but propagation of the requested bind mount could lead to a circular
729dependency that might prevent the mount namespace from ever being freed.
730.TP
731.B EINVAL
c8e5f558
MK
732.I mountflags
733includes more than one of
734.BR MS_SHARED ,
735.BR MS_PRIVATE ,
736.BR MS_SLAVE ,
737or
738.BR MS_UNBINDABLE .
739.TP
740.B EINVAL
741.I mountflags
742includes
743.BR MS_SHARED ,
744.BR MS_PRIVATE ,
745.BR MS_SLAVE ,
746or
1ae6b2c7 747.B MS_UNBINDABLE
c8e5f558 748and also includes a flag other than
1ae6b2c7 749.B MS_REC
c8e5f558
MK
750or
751.BR MS_SILENT .
752.TP
1ae6b2c7 753.B EINVAL
c8e5f558
MK
754An attempt was made to bind mount an unbindable mount.
755.TP
1ae6b2c7 756.B EINVAL
f54c67bf
MK
757In an unprivileged mount namespace
758(i.e., a mount namespace owned by a user namespace
759that was created by an unprivileged user),
760a bind mount operation
360d7455
KF
761.RB ( MS_BIND )
762was attempted without specifying
763.RB ( MS_REC ),
3484e69f 764which would have revealed the filesystem tree underneath one of
360d7455
KF
765the submounts of the directory being bound.
766.TP
fea681da 767.B ELOOP
9b9b4a81 768Too many links encountered during pathname resolution.
9e1ae4f8
MK
769.TP
770.B ELOOP
771A move operation was attempted, and
fea681da
MK
772.I target
773is a descendant of
774.IR source .
775.TP
776.B EMFILE
777(In case no block device is required:)
778Table of dummy devices is full.
779.TP
780.B ENAMETOOLONG
682edefb
MK
781A pathname was longer than
782.BR MAXPATHLEN .
fea681da
MK
783.TP
784.B ENODEV
a90440ba 785.I filesystemtype
fea681da
MK
786not configured in the kernel.
787.TP
788.B ENOENT
789A pathname was empty or had a nonexistent component.
790.TP
791.B ENOMEM
792The kernel could not allocate a free page to copy filenames or data into.
793.TP
794.B ENOTBLK
795.I source
796is not a block device (and a device was required).
797.TP
798.B ENOTDIR
5614f733
MK
799.IR target ,
800or a prefix of
801.IR source ,
802is not a directory.
fea681da
MK
803.TP
804.B ENXIO
805The major number of the block device
806.I source
807is out of range.
808.TP
809.B EPERM
810The caller does not have the required privileges.
1c1ccb2c 811.TP
74ed673c
MK
812.B EPERM
813An attempt was made to modify
814.RB ( MS_REMOUNT )
815the
816.BR MS_RDONLY ,
817.BR MS_NOSUID ,
818or
1ae6b2c7 819.B MS_NOEXEC
74ed673c
MK
820flag, or one of the "atime" flags
821.RB ( MS_NOATIME ,
822.BR MS_NODIRATIME ,
823.BR MS_RELATIME )
824of an existing mount, but the mount is locked; see
825.BR mount_namespaces (7).
826.TP
1c1ccb2c
MK
827.B EROFS
828Mounting a read-only filesystem was attempted without giving the
829.B MS_RDONLY
830flag.
831See
832.BR EACCES ,
833above.
9326e678
MK
834.SH VERSIONS
835The definitions of
836.BR MS_DIRSYNC ,
837.BR MS_MOVE ,
f429fadc 838.BR MS_PRIVATE ,
9326e678
MK
839.BR MS_REC ,
840.BR MS_RELATIME ,
f429fadc 841.BR MS_SHARED ,
67215694 842.BR MS_SLAVE ,
a6bfc757 843.BR MS_STRICTATIME ,
f429fadc 844and
1ae6b2c7 845.B MS_UNBINDABLE
33a0ccb2 846were added to glibc headers in version 2.12.
f429fadc 847.\"
3113c7f3 848.SH STANDARDS
5614f733 849This function is Linux-specific and should not be used in
fea681da 850programs intended to be portable.
889829be 851.SH NOTES
f54e02b4
MK
852Since Linux 2.4 a single filesystem can be mounted at
853multiple mount points, and multiple mounts can be stacked
854on the same mount point.
855.\" Multiple mounts on same mount point: since 2.3.99pre7.
547ee319 856.PP
52f00c05
MK
857The
858.I mountflags
859argument may have the magic number 0xC0ED (\fBMS_MGC_VAL\fP)
860in the top 16 bits.
861(All of the other flags discussed in DESCRIPTION
862occupy the low order 16 bits of
863.IR mountflags .)
864Specifying
1ae6b2c7 865.B MS_MGC_VAL
52f00c05
MK
866was required in kernel versions prior to 2.4,
867but since Linux 2.4 is no longer required and is ignored if specified.
547ee319 868.PP
fea681da 869The original
0daa9e92 870.B MS_SYNC
682edefb 871flag was renamed
0daa9e92 872.B MS_SYNCHRONOUS
682edefb
MK
873in 1.1.69
874when a different
0daa9e92 875.B MS_SYNC
682edefb 876was added to \fI<mman.h>\fP.
dd3568a1 877.PP
880f5b4b 878Before Linux 2.4 an attempt to execute a set-user-ID or set-group-ID program
9ee4a2b6 879on a filesystem mounted with
fea681da
MK
880.B MS_NOSUID
881would fail with
882.BR EPERM .
c13182ef 883Since Linux 2.4 the set-user-ID and set-group-ID bits are
880f5b4b 884just silently ignored in this case.
fea681da 885.\" The change is in patch-2.4.0-prerelease.
f54e02b4 886.\"
dd858bfd
MK
887.SS Mount namespaces
888Starting with kernel 2.4.19, Linux provides mount namespaces.
9ee4a2b6 889A mount namespace is the set of filesystem mounts that
4df2eb09 890are visible to a process.
dd858bfd 891Mount namespaces can be (and usually are)
4df2eb09 892shared between multiple processes,
0a4d78bb
MK
893and changes to the namespace (i.e., mounts and unmounts) by one process
894are visible to all other processes sharing the same namespace.