1MOUNT(2) Linux Programmer's Manual MOUNT(2)
2
3
4
6 mount - mount filesystem
7
9 #include <sys/mount.h>
10
11 int mount(const char *source, const char *target,
12 const char *filesystemtype, unsigned long mountflags,
13 const void *data);
14
16 mount() attaches the filesystem specified by source (which is often a
17 pathname referring to a device, but can also be the pathname of a di‐
18 rectory or file, or a dummy string) to the location (a directory or
19 file) specified by the pathname in target.
20
21 Appropriate privilege (Linux: the CAP_SYS_ADMIN capability) is required
22 to mount filesystems.
23
24 Values for the filesystemtype argument supported by the kernel are
25 listed in /proc/filesystems (e.g., "btrfs", "ext4", "jfs", "xfs",
26 "vfat", "fuse", "tmpfs", "cgroup", "proc", "mqueue", "nfs", "cifs",
27 "iso9660"). Further types may become available when the appropriate
28 modules are loaded.
29
30 The data argument is interpreted by the different filesystems. Typi‐
31 cally it is a string of comma-separated options understood by this
32 filesystem. See mount(8) for details of the options available for each
33 filesystem type.
34
35 A call to mount() performs one of a number of general types of opera‐
36 tion, depending on the bits specified in mountflags. The choice of
37 which operation to perform is determined by testing the bits set in
38 mountflags, with the tests being conducted in the order listed here:
39
40 * Remount an existing mount: mountflags includes MS_REMOUNT.
41
42 * Create a bind mount: mountflags includes MS_BIND.
43
44 * Change the propagation type of an existing mount: mountflags in‐
45 cludes one of MS_SHARED, MS_PRIVATE, MS_SLAVE, or MS_UNBINDABLE.
46
47 * Move an existing mount to a new location: mountflags includes
48 MS_MOVE.
49
50 * Create a new mount: mountflags includes none of the above flags.
51
52 Each of these operations is detailed later in this page. Further flags
53 may be specified in mountflags to modify the behavior of mount(), as
54 described below.
55
56 Additional mount flags
57 The list below describes the additional flags that can be specified in
58 mountflags. Note that some operation types ignore some or all of these
59 flags, as described later in this page.
60
61 MS_DIRSYNC (since Linux 2.5.19)
62 Make directory changes on this filesystem synchronous. (This
63 property can be obtained for individual directories or subtrees
64 using chattr(1).)
65
66 MS_LAZYTIME (since Linux 4.0)
67 Reduce on-disk updates of inode timestamps (atime, mtime, ctime)
68 by maintaining these changes only in memory. The on-disk time‐
69 stamps are updated only when:
70
71 (a) the inode needs to be updated for some change unrelated to
72 file timestamps;
73
74 (b) the application employs fsync(2), syncfs(2), or sync(2);
75
76 (c) an undeleted inode is evicted from memory; or
77
78 (d) more than 24 hours have passed since the inode was written
79 to disk.
80
81 This mount option significantly reduces writes needed to update
82 the inode's timestamps, especially mtime and atime. However, in
83 the event of a system crash, the atime and mtime fields on disk
84 might be out of date by up to 24 hours.
85
86 Examples of workloads where this option could be of significant
87 benefit include frequent random writes to preallocated files, as
88 well as cases where the MS_STRICTATIME mount option is also en‐
89 abled. (The advantage of combining MS_STRICTATIME and MS_LAZY‐
90 TIME is that stat(2) will return the correctly updated atime,
91 but the atime updates will be flushed to disk only in the cases
92 listed above.)
93
94 MS_MANDLOCK
95 Permit mandatory locking on files in this filesystem. (Manda‐
96 tory locking must still be enabled on a per-file basis, as de‐
97 scribed in fcntl(2).) Since Linux 4.5, this mount option re‐
98 quires the CAP_SYS_ADMIN capability and a kernel configured with
99 the CONFIG_MANDATORY_FILE_LOCKING option.
100
101 MS_NOATIME
102 Do not update access times for (all types of) files on this
103 filesystem.
104
105 MS_NODEV
106 Do not allow access to devices (special files) on this filesys‐
107 tem.
108
109 MS_NODIRATIME
110 Do not update access times for directories on this filesystem.
111 This flag provides a subset of the functionality provided by
112 MS_NOATIME; that is, MS_NOATIME implies MS_NODIRATIME.
113
114 MS_NOEXEC
115 Do not allow programs to be executed from this filesystem.
116
117 MS_NOSUID
118 Do not honor set-user-ID and set-group-ID bits or file capabili‐
119 ties when executing programs from this filesystem.
120
121 MS_RDONLY
122 Mount filesystem read-only.
123
124 MS_REC (since Linux 2.4.11)
125 Used in conjunction with MS_BIND to create a recursive bind
126 mount, and in conjunction with the propagation type flags to re‐
127 cursively change the propagation type of all of the mounts in a
128 subtree. See below for further details.
129
130 MS_RELATIME (since Linux 2.6.20)
131 When a file on this filesystem is accessed, update the file's
132 last access time (atime) only if the current value of atime is
133 less than or equal to the file's last modification time (mtime)
134 or last status change time (ctime). This option is useful for
135 programs, such as mutt(1), that need to know when a file has
136 been read since it was last modified. Since Linux 2.6.30, the
137 kernel defaults to the behavior provided by this flag (unless
138 MS_NOATIME was specified), and the MS_STRICTATIME flag is re‐
139 quired to obtain traditional semantics. In addition, since
140 Linux 2.6.30, the file's last access time is always updated if
141 it is more than 1 day old.
142
143 MS_SILENT (since Linux 2.6.17)
144 Suppress the display of certain (printk()) warning messages in
145 the kernel log. This flag supersedes the misnamed and obsolete
146 MS_VERBOSE flag (available since Linux 2.4.12), which has the
147 same meaning.
148
149 MS_STRICTATIME (since Linux 2.6.30)
150 Always update the last access time (atime) when files on this
151 filesystem are accessed. (This was the default behavior before
152 Linux 2.6.30.) Specifying this flag overrides the effect of
153 setting the MS_NOATIME and MS_RELATIME flags.
154
155 MS_SYNCHRONOUS
156 Make writes on this filesystem synchronous (as though the O_SYNC
157 flag to open(2) was specified for all file opens to this
158 filesystem).
159
160 MS_NOSYMFOLLOW (since Linux 5.10)
161 Do not follow symbolic links when resolving paths. Symbolic
162 links can still be created, and readlink(1), readlink(2), real‐
163 path(1), and realpath(3) all still work properly.
164
165 From Linux 2.4 onward, some of the above flags are settable on a per-
166 mount basis, while others apply to the superblock of the mounted
167 filesystem, meaning that all mounts of the same filesystem share those
168 flags. (Previously, all of the flags were per-superblock.)
169
170 The per-mount-point flags are as follows:
171
172 * Since Linux 2.4: MS_NODEV, MS_NOEXEC, and MS_NOSUID flags are set‐
173 table on a per-mount-point basis.
174
175 * Additionally, since Linux 2.6.16: MS_NOATIME and MS_NODIRATIME.
176
177 * Additionally, since Linux 2.6.20: MS_RELATIME.
178
179 The following flags are per-superblock: MS_DIRSYNC, MS_LAZYTIME,
180 MS_MANDLOCK, MS_SILENT, and MS_SYNCHRONOUS. The initial settings of
181 these flags are determined on the first mount of the filesystem, and
182 will be shared by all subsequent mounts of the same filesystem. Subse‐
183 quently, the settings of the flags can be changed via a remount opera‐
184 tion (see below). Such changes will be visible via all mount points
185 associated with the filesystem.
186
187 Since Linux 2.6.16, MS_RDONLY can be set or cleared on a per-mount-
188 point basis as well as on the underlying filesystem superblock. The
189 mounted filesystem will be writable only if neither the filesystem nor
190 the mountpoint are flagged as read-only.
191
192 Remounting an existing mount
193 An existing mount may be remounted by specifying MS_REMOUNT in mount‐
194 flags. This allows you to change the mountflags and data of an exist‐
195 ing mount without having to unmount and remount the filesystem. target
196 should be the same value specified in the initial mount() call.
197
198 The source and filesystemtype arguments are ignored.
199
200 The mountflags and data arguments should match the values used in the
201 original mount() call, except for those parameters that are being de‐
202 liberately changed.
203
204 The following mountflags can be changed: MS_LAZYTIME, MS_MANDLOCK,
205 MS_NOATIME, MS_NODEV, MS_NODIRATIME, MS_NOEXEC, MS_NOSUID, MS_RELATIME,
206 MS_RDONLY, MS_STRICTATIME (whose effect is to clear the MS_NOATIME and
207 MS_RELATIME flags), and MS_SYNCHRONOUS. Attempts to change the setting
208 of the MS_DIRSYNC and MS_SILENT flags during a remount are silently ig‐
209 nored. Note that changes to per-superblock flags are visible via all
210 mount points of the associated filesystem (because the per-superblock
211 flags are shared by all mount points).
212
213 Since Linux 3.17, if none of MS_NOATIME, MS_NODIRATIME, MS_RELATIME, or
214 MS_STRICTATIME is specified in mountflags, then the remount operation
215 preserves the existing values of these flags (rather than defaulting to
216 MS_RELATIME).
217
218 Since Linux 2.6.26, the MS_REMOUNT flag can be used with MS_BIND to
219 modify only the per-mount-point flags. This is particularly useful for
220 setting or clearing the "read-only" flag on a mount point without
221 changing the underlying filesystem. Specifying mountflags as:
222
223 MS_REMOUNT | MS_BIND | MS_RDONLY
224
225 will make access through this mountpoint read-only, without affecting
226 other mount points.
227
228 Creating a bind mount
229 If mountflags includes MS_BIND (available since Linux 2.4), then per‐
230 form a bind mount. A bind mount makes a file or a directory subtree
231 visible at another point within the single directory hierarchy. Bind
232 mounts may cross filesystem boundaries and span chroot(2) jails.
233
234 The filesystemtype and data arguments are ignored.
235
236 The remaining bits (other than MS_REC, described below) in the mount‐
237 flags argument are also ignored. (The bind mount has the same mount
238 options as the underlying mount point.) However, see the discussion of
239 remounting above, for a method of making an existing bind mount read-
240 only.
241
242 By default, when a directory is bind mounted, only that directory is
243 mounted; if there are any submounts under the directory tree, they are
244 not bind mounted. If the MS_REC flag is also specified, then a recur‐
245 sive bind mount operation is performed: all submounts under the source
246 subtree (other than unbindable mounts) are also bind mounted at the
247 corresponding location in the target subtree.
248
249 Changing the propagation type of an existing mount
250 If mountflags includes one of MS_SHARED, MS_PRIVATE, MS_SLAVE, or
251 MS_UNBINDABLE (all available since Linux 2.6.15), then the propagation
252 type of an existing mount is changed. If more than one of these flags
253 is specified, an error results.
254
255 The only other flags that can be specified while changing the propaga‐
256 tion type are MS_REC (described below) and MS_SILENT (which is ig‐
257 nored).
258
259 The source, filesystemtype, and data arguments are ignored.
260
261 The meanings of the propagation type flags are as follows:
262
263 MS_SHARED
264 Make this mount point shared. Mount and unmount events immedi‐
265 ately under this mount point will propagate to the other mount
266 points that are members of this mount's peer group. Propagation
267 here means that the same mount or unmount will automatically oc‐
268 cur under all of the other mount points in the peer group. Con‐
269 versely, mount and unmount events that take place under peer
270 mount points will propagate to this mount point.
271
272 MS_PRIVATE
273 Make this mount point private. Mount and unmount events do not
274 propagate into or out of this mount point.
275
276 MS_SLAVE
277 If this is a shared mount point that is a member of a peer group
278 that contains other members, convert it to a slave mount. If
279 this is a shared mount point that is a member of a peer group
280 that contains no other members, convert it to a private mount.
281 Otherwise, the propagation type of the mount point is left un‐
282 changed.
283
284 When a mount point is a slave, mount and unmount events propa‐
285 gate into this mount point from the (master) shared peer group
286 of which it was formerly a member. Mount and unmount events un‐
287 der this mount point do not propagate to any peer.
288
289 A mount point can be the slave of another peer group while at
290 the same time sharing mount and unmount events with a peer group
291 of which it is a member.
292
293 MS_UNBINDABLE
294 Make this mount unbindable. This is like a private mount, and
295 in addition this mount can't be bind mounted. When a recursive
296 bind mount (mount() with the MS_BIND and MS_REC flags) is per‐
297 formed on a directory subtree, any unbindable mounts within the
298 subtree are automatically pruned (i.e., not replicated) when
299 replicating that subtree to produce the target subtree.
300
301 By default, changing the propagation type affects only the target mount
302 point. If the MS_REC flag is also specified in mountflags, then the
303 propagation type of all mount points under target is also changed.
304
305 For further details regarding mount propagation types (including the
306 default propagation type assigned to new mounts), see mount_name‐
307 spaces(7).
308
309 Moving a mount
310 If mountflags contains the flag MS_MOVE (available since Linux 2.4.18),
311 then move a subtree: source specifies an existing mount point and tar‐
312 get specifies the new location to which that mount point is to be relo‐
313 cated. The move is atomic: at no point is the subtree unmounted.
314
315 The remaining bits in the mountflags argument are ignored, as are the
316 filesystemtype and data arguments.
317
318 Creating a new mount point
319 If none of MS_REMOUNT, MS_BIND, MS_MOVE, MS_SHARED, MS_PRIVATE,
320 MS_SLAVE, or MS_UNBINDABLE is specified in mountflags, then mount()
321 performs its default action: creating a new mount point. source speci‐
322 fies the source for the new mount point, and target specifies the di‐
323 rectory at which to create the mount point.
324
325 The filesystemtype and data arguments are employed, and further bits
326 may be specified in mountflags to modify the behavior of the call.
327
329 On success, zero is returned. On error, -1 is returned, and errno is
330 set appropriately.
331
333 The error values given below result from filesystem type independent
334 errors. Each filesystem type may have its own special errors and its
335 own special behavior. See the Linux kernel source code for details.
336
337 EACCES A component of a path was not searchable. (See also path_reso‐
338 lution(7).)
339
340 EACCES Mounting a read-only filesystem was attempted without giving the
341 MS_RDONLY flag.
342
343 The filesystem may be read-only for various reasons, including:
344 it resides on a read-only optical disk; it is resides on a de‐
345 vice with a physical switch that has been set to mark the device
346 read-only; the filesystem implementation was compiled with read-
347 only support; or errors were detected when initially mounting
348 the filesystem, so that it was marked read-only and can't be re‐
349 mounted as read-write (until the errors are fixed).
350
351 Some filesystems instead return the error EROFS on an attempt to
352 mount a read-only filesystem.
353
354 EACCES The block device source is located on a filesystem mounted with
355 the MS_NODEV option.
356
357 EBUSY An attempt was made to stack a new mount directly on top of an
358 existing mount point that was created in this mount namespace
359 with the same source and target.
360
361 EBUSY source cannot be remounted read-only, because it still holds
362 files open for writing.
363
364 EFAULT One of the pointer arguments points outside the user address
365 space.
366
367 EINVAL source had an invalid superblock.
368
369 EINVAL A remount operation (MS_REMOUNT) was attempted, but source was
370 not already mounted on target.
371
372 EINVAL A move operation (MS_MOVE) was attempted, but the mount tree un‐
373 der source includes unbindable mounts and target is a mount
374 point that has propagation type MS_SHARED.
375
376 EINVAL A move operation (MS_MOVE) was attempted, but the parent mount
377 of source mount has propagation type MS_SHARED.
378
379 EINVAL A move operation (MS_MOVE) was attempted, but source was not a
380 mount point, or was '/'.
381
382 EINVAL A bind operation (MS_BIND) was requested where source referred a
383 mount namespace magic link (i.e., a /proc/[pid]/ns/mnt magic
384 link or a bind mount to such a link) and the propagation type of
385 the parent mount of target was MS_SHARED, but propagation of the
386 requested bind mount could lead to a circular dependency that
387 might prevent the mount namespace from ever being freed.
388
389 EINVAL mountflags includes more than one of MS_SHARED, MS_PRIVATE,
390 MS_SLAVE, or MS_UNBINDABLE.
391
392 EINVAL mountflags includes MS_SHARED, MS_PRIVATE, MS_SLAVE, or MS_UN‐
393 BINDABLE and also includes a flag other than MS_REC or
394 MS_SILENT.
395
396 EINVAL An attempt was made to bind mount an unbindable mount.
397
398 EINVAL In an unprivileged mount namespace (i.e., a mount namespace
399 owned by a user namespace that was created by an unprivileged
400 user), a bind mount operation (MS_BIND) was attempted without
401 specifying (MS_REC), which would have revealed the filesystem
402 tree underneath one of the submounts of the directory being
403 bound.
404
405 ELOOP Too many links encountered during pathname resolution.
406
407 ELOOP A move operation was attempted, and target is a descendant of
408 source.
409
410 EMFILE (In case no block device is required:) Table of dummy devices is
411 full.
412
413 ENAMETOOLONG
414 A pathname was longer than MAXPATHLEN.
415
416 ENODEV filesystemtype not configured in the kernel.
417
418 ENOENT A pathname was empty or had a nonexistent component.
419
420 ENOMEM The kernel could not allocate a free page to copy filenames or
421 data into.
422
423 ENOTBLK
424 source is not a block device (and a device was required).
425
426 ENOTDIR
427 target, or a prefix of source, is not a directory.
428
429 ENXIO The major number of the block device source is out of range.
430
431 EPERM The caller does not have the required privileges.
432
433 EROFS Mounting a read-only filesystem was attempted without giving the
434 MS_RDONLY flag. See EACCES, above.
435
437 The definitions of MS_DIRSYNC, MS_MOVE, MS_PRIVATE, MS_REC, MS_RELA‐
438 TIME, MS_SHARED, MS_SLAVE, MS_STRICTATIME, and MS_UNBINDABLE were added
439 to glibc headers in version 2.12.
440
442 This function is Linux-specific and should not be used in programs in‐
443 tended to be portable.
444
446 Since Linux 2.4 a single filesystem can be mounted at multiple mount
447 points, and multiple mounts can be stacked on the same mount point.
448
449 The mountflags argument may have the magic number 0xC0ED (MS_MGC_VAL)
450 in the top 16 bits. (All of the other flags discussed in DESCRIPTION
451 occupy the low order 16 bits of mountflags.) Specifying MS_MGC_VAL was
452 required in kernel versions prior to 2.4, but since Linux 2.4 is no
453 longer required and is ignored if specified.
454
455 The original MS_SYNC flag was renamed MS_SYNCHRONOUS in 1.1.69 when a
456 different MS_SYNC was added to <mman.h>.
457
458 Before Linux 2.4 an attempt to execute a set-user-ID or set-group-ID
459 program on a filesystem mounted with MS_NOSUID would fail with EPERM.
460 Since Linux 2.4 the set-user-ID and set-group-ID bits are just silently
461 ignored in this case.
462
463 Mount namespaces
464 Starting with kernel 2.4.19, Linux provides mount namespaces. A mount
465 namespace is the set of filesystem mounts that are visible to a
466 process. Mount namespaces can be (and usually are) shared between mul‐
467 tiple processes, and changes to the namespace (i.e., mounts and un‐
468 mounts) by one process are visible to all other processes sharing the
469 same namespace. (The pre-2.4.19 Linux situation can be considered as
470 one in which a single namespace was shared by every process on the sys‐
471 tem.)
472
473 A child process created by fork(2) shares its parent's mount namespace;
474 the mount namespace is preserved across an execve(2).
475
476 A process can obtain a private mount namespace if: it was created using
477 the clone(2) CLONE_NEWNS flag, in which case its new namespace is ini‐
478 tialized to be a copy of the namespace of the process that called
479 clone(2); or it calls unshare(2) with the CLONE_NEWNS flag, which
480 causes the caller's mount namespace to obtain a private copy of the
481 namespace that it was previously sharing with other processes, so that
482 future mounts and unmounts by the caller are invisible to other pro‐
483 cesses (except child processes that the caller subsequently creates)
484 and vice versa.
485
486 For further details on mount namespaces, see mount_namespaces(7).
487
488 Parental relationship between mount points
489 Each mount point has a parent mount point. The overall parental rela‐
490 tionship of all mount points defines the single directory hierarchy
491 seen by the processes within a mount namespace.
492
493 The parent of a new mount point is defined when the mount point is cre‐
494 ated. In the usual case, the parent of a new mount is the mount point
495 of the filesystem containing the directory or file at which the new
496 mount is attached. In the case where a new mount is stacked on top of
497 an existing mount, the parent of the new mount is the previous mount
498 that was stacked at that location.
499
500 The parental relationship between mount points can be discovered via
501 the /proc/[pid]/mountinfo file (see below).
502
503 /proc/[pid]/mounts and /proc/[pid]/mountinfo
504 The Linux-specific /proc/[pid]/mounts file exposes the list of mount
505 points in the mount namespace of the process with the specified ID.
506 The /proc/[pid]/mountinfo file exposes even more information about
507 mount points, including the propagation type and mount ID information
508 that makes it possible to discover the parental relationship between
509 mount points. See proc(5) and mount_namespaces(7) for details of this
510 file.
511
513 mountpoint(1), chroot(2), ioctl_iflags(2), pivot_root(2), umount(2),
514 mount_namespaces(7), path_resolution(7), findmnt(8), lsblk(8),
515 mount(8), umount(8)
516
518 This page is part of release 5.10 of the Linux man-pages project. A
519 description of the project, information about reporting bugs, and the
520 latest version of this page, can be found at
521 https://www.kernel.org/doc/man-pages/.
522
523
524
525Linux 2020-12-21 MOUNT(2)