1MOUNT(2)                   Linux Programmer's Manual                  MOUNT(2)
2
3
4

NAME

6       mount - mount filesystem
7

SYNOPSIS

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

DESCRIPTION

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.  This argument may be specified as NULL, if there  are
34       no options.
35
36       A  call  to mount() performs one of a number of general types of opera‐
37       tion, depending on the bits specified in  mountflags.   The  choice  of
38       which  operation  to  perform  is determined by testing the bits set in
39       mountflags, with the tests being conducted in the order listed here:
40
41       *  Remount an existing mount: mountflags includes MS_REMOUNT.
42
43       *  Create a bind mount: mountflags includes MS_BIND.
44
45       *  Change the propagation type of an  existing  mount:  mountflags  in‐
46          cludes one of MS_SHARED, MS_PRIVATE, MS_SLAVE, or MS_UNBINDABLE.
47
48       *  Move  an  existing  mount  to  a  new  location: mountflags includes
49          MS_MOVE.
50
51       *  Create a new mount: mountflags includes none of the above flags.
52
53       Each of these operations is detailed later in this page.  Further flags
54       may  be  specified  in mountflags to modify the behavior of mount(), as
55       described below.
56
57   Additional mount flags
58       The list below describes the additional flags that can be specified  in
59       mountflags.  Note that some operation types ignore some or all of these
60       flags, as described later in this page.
61
62       MS_DIRSYNC (since Linux 2.5.19)
63              Make directory changes on this  filesystem  synchronous.   (This
64              property  can be obtained for individual directories or subtrees
65              using chattr(1).)
66
67       MS_LAZYTIME (since Linux 4.0)
68              Reduce on-disk updates of inode timestamps (atime, mtime, ctime)
69              by  maintaining these changes only in memory.  The on-disk time‐
70              stamps are updated only when:
71
72              (a) the inode needs to be updated for some change  unrelated  to
73                  file timestamps;
74
75              (b) the application employs fsync(2), syncfs(2), or sync(2);
76
77              (c) an undeleted inode is evicted from memory; or
78
79              (d) more  than  24 hours have passed since the inode was written
80                  to disk.
81
82              This mount option significantly reduces writes needed to  update
83              the inode's timestamps, especially mtime and atime.  However, in
84              the event of a system crash, the atime and mtime fields on  disk
85              might be out of date by up to 24 hours.
86
87              Examples  of workloads where this option could be of significant
88              benefit include frequent random writes to preallocated files, as
89              well  as cases where the MS_STRICTATIME mount option is also en‐
90              abled.  (The advantage of combining MS_STRICTATIME and  MS_LAZY‐
91              TIME  is  that  stat(2) will return the correctly updated atime,
92              but the atime updates will be flushed to disk only in the  cases
93              listed above.)
94
95       MS_MANDLOCK
96              Permit  mandatory  locking on files in this filesystem.  (Manda‐
97              tory locking must still be enabled on a per-file basis,  as  de‐
98              scribed  in  fcntl(2).)   Since Linux 4.5, this mount option re‐
99              quires the CAP_SYS_ADMIN capability and a kernel configured with
100              the CONFIG_MANDATORY_FILE_LOCKING option.
101
102       MS_NOATIME
103              Do  not  update  access  times  for (all types of) files on this
104              filesystem.
105
106       MS_NODEV
107              Do not allow access to devices (special files) on this  filesys‐
108              tem.
109
110       MS_NODIRATIME
111              Do  not  update access times for directories on this filesystem.
112              This flag provides a subset of  the  functionality  provided  by
113              MS_NOATIME; that is, MS_NOATIME implies MS_NODIRATIME.
114
115       MS_NOEXEC
116              Do not allow programs to be executed from this filesystem.
117
118       MS_NOSUID
119              Do not honor set-user-ID and set-group-ID bits or file capabili‐
120              ties when executing programs from this filesystem.  In addition,
121              SELinux domain transitions require the permission nosuid_transi‐
122              tion, which in turn needs also  the  policy  capability  nnp_no‐
123              suid_transition.
124
125       MS_RDONLY
126              Mount filesystem read-only.
127
128       MS_REC (since Linux 2.4.11)
129              Used  in  conjunction  with  MS_BIND  to create a recursive bind
130              mount, and in conjunction with the propagation type flags to re‐
131              cursively  change the propagation type of all of the mounts in a
132              subtree.  See below for further details.
133
134       MS_RELATIME (since Linux 2.6.20)
135              When a file on this filesystem is accessed,  update  the  file's
136              last  access  time (atime) only if the current value of atime is
137              less than or equal to the file's last modification time  (mtime)
138              or  last  status change time (ctime).  This option is useful for
139              programs, such as mutt(1), that need to know  when  a  file  has
140              been  read  since it was last modified.  Since Linux 2.6.30, the
141              kernel defaults to the behavior provided by  this  flag  (unless
142              MS_NOATIME  was  specified),  and the MS_STRICTATIME flag is re‐
143              quired to obtain  traditional  semantics.   In  addition,  since
144              Linux  2.6.30,  the file's last access time is always updated if
145              it is more than 1 day old.
146
147       MS_SILENT (since Linux 2.6.17)
148              Suppress the display of certain (printk()) warning  messages  in
149              the  kernel log.  This flag supersedes the misnamed and obsolete
150              MS_VERBOSE flag (available since Linux 2.4.12),  which  has  the
151              same meaning.
152
153       MS_STRICTATIME (since Linux 2.6.30)
154              Always  update  the  last access time (atime) when files on this
155              filesystem are accessed.  (This was the default behavior  before
156              Linux  2.6.30.)   Specifying  this  flag overrides the effect of
157              setting the MS_NOATIME and MS_RELATIME flags.
158
159       MS_SYNCHRONOUS
160              Make writes on this filesystem synchronous (as though the O_SYNC
161              flag  to  open(2)  was  specified  for  all  file  opens to this
162              filesystem).
163
164       MS_NOSYMFOLLOW (since Linux 5.10)
165              Do not follow symbolic links  when  resolving  paths.   Symbolic
166              links  can still be created, and readlink(1), readlink(2), real‐
167              path(1), and realpath(3) all still work properly.
168
169       From Linux 2.4 onward, some of the above flags are settable on  a  per-
170       mount  basis,  while  others  apply  to  the  superblock of the mounted
171       filesystem, meaning that all mounts of the same filesystem share  those
172       flags.  (Previously, all of the flags were per-superblock.)
173
174       The per-mount-point flags are as follows:
175
176       *  Since  Linux  2.4: MS_NODEV, MS_NOEXEC, and MS_NOSUID flags are set‐
177          table on a per-mount-point basis.
178
179       *  Additionally, since Linux 2.6.16: MS_NOATIME and MS_NODIRATIME.
180
181       *  Additionally, since Linux 2.6.20: MS_RELATIME.
182
183       The  following  flags  are  per-superblock:  MS_DIRSYNC,   MS_LAZYTIME,
184       MS_MANDLOCK,  MS_SILENT,  and  MS_SYNCHRONOUS.  The initial settings of
185       these flags are determined on the first mount of  the  filesystem,  and
186       will be shared by all subsequent mounts of the same filesystem.  Subse‐
187       quently, the settings of the flags can be changed via a remount  opera‐
188       tion  (see below).  Such changes will be visible via all mounts associ‐
189       ated with the filesystem.
190
191       Since Linux 2.6.16, MS_RDONLY can be set or  cleared  on  a  per-mount-
192       point  basis  as  well as on the underlying filesystem superblock.  The
193       mounted filesystem will be writable only if neither the filesystem  nor
194       the mountpoint are flagged as read-only.
195
196   Remounting an existing mount
197       An  existing  mount may be remounted by specifying MS_REMOUNT in mount‐
198       flags.  This allows you to change the mountflags and data of an  exist‐
199       ing mount without having to unmount and remount the filesystem.  target
200       should be the same value specified in the initial mount() call.
201
202       The source and filesystemtype arguments are ignored.
203
204       The mountflags and data arguments should match the values used  in  the
205       original  mount()  call, except for those parameters that are being de‐
206       liberately changed.
207
208       The following mountflags  can  be  changed:  MS_LAZYTIME,  MS_MANDLOCK,
209       MS_NOATIME, MS_NODEV, MS_NODIRATIME, MS_NOEXEC, MS_NOSUID, MS_RELATIME,
210       MS_RDONLY, MS_STRICTATIME (whose effect is to clear the MS_NOATIME  and
211       MS_RELATIME flags), and MS_SYNCHRONOUS.  Attempts to change the setting
212       of the MS_DIRSYNC and MS_SILENT flags during a remount are silently ig‐
213       nored.   Note  that changes to per-superblock flags are visible via all
214       mounts of the associated filesystem (because the  per-superblock  flags
215       are shared by all mounts).
216
217       Since Linux 3.17, if none of MS_NOATIME, MS_NODIRATIME, MS_RELATIME, or
218       MS_STRICTATIME is specified in mountflags, then the  remount  operation
219       preserves the existing values of these flags (rather than defaulting to
220       MS_RELATIME).
221
222       Since Linux 2.6.26, the MS_REMOUNT flag can be  used  with  MS_BIND  to
223       modify only the per-mount-point flags.  This is particularly useful for
224       setting or clearing the "read-only" flag on a  mount  without  changing
225       the underlying filesystem.  Specifying mountflags as:
226
227           MS_REMOUNT | MS_BIND | MS_RDONLY
228
229       will  make  access through this mountpoint read-only, without affecting
230       other mounts.
231
232   Creating a bind mount
233       If mountflags includes MS_BIND (available since Linux 2.4),  then  per‐
234       form  a  bind  mount.  A bind mount makes a file or a directory subtree
235       visible at another point within the single directory  hierarchy.   Bind
236       mounts may cross filesystem boundaries and span chroot(2) jails.
237
238       The filesystemtype and data arguments are ignored.
239
240       The  remaining  bits (other than MS_REC, described below) in the mount‐
241       flags argument are also ignored.  (The bind mount has  the  same  mount
242       options  as  the underlying mount.)  However, see the discussion of re‐
243       mounting above, for a method of making an  existing  bind  mount  read-
244       only.
245
246       By  default,  when  a directory is bind mounted, only that directory is
247       mounted; if there are any submounts under the directory tree, they  are
248       not  bind mounted.  If the MS_REC flag is also specified, then a recur‐
249       sive bind mount operation is performed: all submounts under the  source
250       subtree  (other  than  unbindable  mounts) are also bind mounted at the
251       corresponding location in the target subtree.
252
253   Changing the propagation type of an existing mount
254       If mountflags includes  one  of  MS_SHARED,  MS_PRIVATE,  MS_SLAVE,  or
255       MS_UNBINDABLE  (all available since Linux 2.6.15), then the propagation
256       type of an existing mount is changed.  If more than one of these  flags
257       is specified, an error results.
258
259       The  only other flags that can be specified while changing the propaga‐
260       tion type are MS_REC (described below)  and  MS_SILENT  (which  is  ig‐
261       nored).
262
263       The source, filesystemtype, and data arguments are ignored.
264
265       The meanings of the propagation type flags are as follows:
266
267       MS_SHARED
268              Make  this  mount  shared.  Mount and unmount events immediately
269              under this mount will propagate to the  other  mounts  that  are
270              members of this mount's peer group.  Propagation here means that
271              the same mount or unmount will automatically occur under all  of
272              the  other  mounts in the peer group.  Conversely, mount and un‐
273              mount events that take place under peer mounts will propagate to
274              this mount.
275
276       MS_PRIVATE
277              Make this mount private.  Mount and unmount events do not propa‐
278              gate into or out of this mount.
279
280       MS_SLAVE
281              If this is a shared mount that is a member of a peer group  that
282              contains other members, convert it to a slave mount.  If this is
283              a shared mount that is a member of a peer group that contains no
284              other  members,  convert  it to a private mount.  Otherwise, the
285              propagation type of the mount is left unchanged.
286
287              When a mount is a slave, mount and unmount events propagate into
288              this  mount  from the (master) shared peer group of which it was
289              formerly a member.  Mount and unmount events under this mount do
290              not propagate to any peer.
291
292              A mount can be the slave of another peer group while at the same
293              time sharing mount and unmount events with a peer group of which
294              it is a member.
295
296       MS_UNBINDABLE
297              Make  this  mount unbindable.  This is like a private mount, and
298              in addition this mount can't be bind mounted.  When a  recursive
299              bind  mount  (mount() with the MS_BIND and MS_REC flags) is per‐
300              formed on a directory subtree, any unbindable mounts within  the
301              subtree  are  automatically  pruned  (i.e., not replicated) when
302              replicating that subtree to produce the target subtree.
303
304       By default, changing the  propagation  type  affects  only  the  target
305       mount.   If  the  MS_REC flag is also specified in mountflags, then the
306       propagation type of all mounts under target is also changed.
307
308       For further details regarding mount propagation  types  (including  the
309       default  propagation  type  assigned  to  new  mounts), see mount_name‐
310       spaces(7).
311
312   Moving a mount
313       If mountflags contains the flag MS_MOVE (available since Linux 2.4.18),
314       then  move  a  subtree:  source  specifies an existing mount and target
315       specifies the new location to which that mount is to be relocated.  The
316       move is atomic: at no point is the subtree unmounted.
317
318       The  remaining  bits in the mountflags argument are ignored, as are the
319       filesystemtype and data arguments.
320
321   Creating a new mount
322       If  none  of  MS_REMOUNT,  MS_BIND,  MS_MOVE,  MS_SHARED,   MS_PRIVATE,
323       MS_SLAVE,  or  MS_UNBINDABLE  is  specified in mountflags, then mount()
324       performs its default action: creating a new  mount.   source  specifies
325       the  source  for  the  new mount, and target specifies the directory at
326       which to create the mount point.
327
328       The filesystemtype and data arguments are employed,  and  further  bits
329       may be specified in mountflags to modify the behavior of the call.
330

RETURN VALUE

332       On  success,  zero is returned.  On error, -1 is returned, and errno is
333       set to indicate the error.
334

ERRORS

336       The error values given below result from  filesystem  type  independent
337       errors.   Each  filesystem type may have its own special errors and its
338       own special behavior.  See the Linux kernel source code for details.
339
340       EACCES A component of a path was not searchable.  (See also  path_reso‐
341              lution(7).)
342
343       EACCES Mounting a read-only filesystem was attempted without giving the
344              MS_RDONLY flag.
345
346              The filesystem may be read-only for various reasons,  including:
347              it  resides  on a read-only optical disk; it is resides on a de‐
348              vice with a physical switch that has been set to mark the device
349              read-only; the filesystem implementation was compiled with read-
350              only support; or errors were detected  when  initially  mounting
351              the filesystem, so that it was marked read-only and can't be re‐
352              mounted as read-write (until the errors are fixed).
353
354              Some filesystems instead return the error EROFS on an attempt to
355              mount a read-only filesystem.
356
357       EACCES The  block device source is located on a filesystem mounted with
358              the MS_NODEV option.
359
360       EBUSY  An attempt was made to stack a new mount directly on top  of  an
361              existing  mount  point  that was created in this mount namespace
362              with the same source and target.
363
364       EBUSY  source cannot be remounted read-only,  because  it  still  holds
365              files open for writing.
366
367       EFAULT One  of  the  pointer  arguments points outside the user address
368              space.
369
370       EINVAL source had an invalid superblock.
371
372       EINVAL A remount operation (MS_REMOUNT) was attempted, but  source  was
373              not already mounted on target.
374
375       EINVAL A move operation (MS_MOVE) was attempted, but the mount tree un‐
376              der source includes unbindable mounts and target is a mount that
377              has propagation type MS_SHARED.
378
379       EINVAL A  move  operation (MS_MOVE) was attempted, but the parent mount
380              of source mount has propagation type MS_SHARED.
381
382       EINVAL A move operation (MS_MOVE) was attempted, but source was  not  a
383              mount, or was '/'.
384
385       EINVAL A bind operation (MS_BIND) was requested where source referred a
386              mount namespace magic link  (i.e.,  a  /proc/[pid]/ns/mnt  magic
387              link or a bind mount to such a link) and the propagation type of
388              the parent mount of target was MS_SHARED, but propagation of the
389              requested  bind  mount  could lead to a circular dependency that
390              might prevent the mount namespace from ever being freed.
391
392       EINVAL mountflags includes more  than  one  of  MS_SHARED,  MS_PRIVATE,
393              MS_SLAVE, or MS_UNBINDABLE.
394
395       EINVAL mountflags  includes  MS_SHARED, MS_PRIVATE, MS_SLAVE, or MS_UN‐
396              BINDABLE  and  also  includes  a  flag  other  than  MS_REC   or
397              MS_SILENT.
398
399       EINVAL An attempt was made to bind mount an unbindable mount.
400
401       EINVAL In  an  unprivileged  mount  namespace  (i.e., a mount namespace
402              owned by a user namespace that was created  by  an  unprivileged
403              user),  a  bind  mount operation (MS_BIND) was attempted without
404              specifying (MS_REC), which would have  revealed  the  filesystem
405              tree  underneath  one  of  the  submounts of the directory being
406              bound.
407
408       ELOOP  Too many links encountered during pathname resolution.
409
410       ELOOP  A move operation was attempted, and target is  a  descendant  of
411              source.
412
413       EMFILE (In case no block device is required:) Table of dummy devices is
414              full.
415
416       ENAMETOOLONG
417              A pathname was longer than MAXPATHLEN.
418
419       ENODEV filesystemtype not configured in the kernel.
420
421       ENOENT A pathname was empty or had a nonexistent component.
422
423       ENOMEM The kernel could not allocate a free page to copy  filenames  or
424              data into.
425
426       ENOTBLK
427              source is not a block device (and a device was required).
428
429       ENOTDIR
430              target, or a prefix of source, is not a directory.
431
432       ENXIO  The major number of the block device source is out of range.
433
434       EPERM  The caller does not have the required privileges.
435
436       EPERM  An attempt was made to modify (MS_REMOUNT) the MS_RDONLY, MS_NO‐
437              SUID, or MS_NOEXEC flag, or one of the "atime"  flags  (MS_NOAT‐
438              IME,  MS_NODIRATIME,  MS_RELATIME) of an existing mount, but the
439              mount is locked; see mount_namespaces(7).
440
441       EROFS  Mounting a read-only filesystem was attempted without giving the
442              MS_RDONLY flag.  See EACCES, above.
443

VERSIONS

445       The  definitions  of  MS_DIRSYNC, MS_MOVE, MS_PRIVATE, MS_REC, MS_RELA‐
446       TIME, MS_SHARED, MS_SLAVE, MS_STRICTATIME, and MS_UNBINDABLE were added
447       to glibc headers in version 2.12.
448

CONFORMING TO

450       This  function is Linux-specific and should not be used in programs in‐
451       tended to be portable.
452

NOTES

454       Since Linux 2.4 a single filesystem can be mounted  at  multiple  mount
455       points, and multiple mounts can be stacked on the same mount point.
456
457       The  mountflags  argument may have the magic number 0xC0ED (MS_MGC_VAL)
458       in the top 16 bits.  (All of the other flags discussed  in  DESCRIPTION
459       occupy the low order 16 bits of mountflags.)  Specifying MS_MGC_VAL was
460       required in kernel versions prior to 2.4, but since  Linux  2.4  is  no
461       longer required and is ignored if specified.
462
463       The  original  MS_SYNC flag was renamed MS_SYNCHRONOUS in 1.1.69 when a
464       different MS_SYNC was added to <mman.h>.
465
466       Before Linux 2.4 an attempt to execute a  set-user-ID  or  set-group-ID
467       program  on  a filesystem mounted with MS_NOSUID would fail with EPERM.
468       Since Linux 2.4 the set-user-ID and set-group-ID bits are just silently
469       ignored in this case.
470
471   Mount namespaces
472       Starting  with kernel 2.4.19, Linux provides mount namespaces.  A mount
473       namespace is the set  of  filesystem  mounts  that  are  visible  to  a
474       process.  Mount namespaces can be (and usually are) shared between mul‐
475       tiple processes, and changes to the namespace  (i.e.,  mounts  and  un‐
476       mounts)  by  one process are visible to all other processes sharing the
477       same namespace.  (The pre-2.4.19 Linux situation can be  considered  as
478       one in which a single namespace was shared by every process on the sys‐
479       tem.)
480
481       A child process created by fork(2) shares its parent's mount namespace;
482       the mount namespace is preserved across an execve(2).
483
484       A process can obtain a private mount namespace if: it was created using
485       the clone(2) CLONE_NEWNS flag, in which case its new namespace is  ini‐
486       tialized  to  be  a  copy  of  the namespace of the process that called
487       clone(2); or it calls  unshare(2)  with  the  CLONE_NEWNS  flag,  which
488       causes  the  caller's  mount  namespace to obtain a private copy of the
489       namespace that it was previously sharing with other processes, so  that
490       future  mounts  and  unmounts by the caller are invisible to other pro‐
491       cesses (except child processes that the  caller  subsequently  creates)
492       and vice versa.
493
494       For further details on mount namespaces, see mount_namespaces(7).
495
496   Parental relationship between mounts
497       Each  mount  has  a parent mount.  The overall parental relationship of
498       all mounts defines the single directory hierarchy seen by the processes
499       within a mount namespace.
500
501       The parent of a new mount is defined when the mount is created.  In the
502       usual case, the parent of a new mount is the mount  of  the  filesystem
503       containing  the  directory  or file at which the new mount is attached.
504       In the case where a new mount is stacked on top of an  existing  mount,
505       the  parent  of the new mount is the previous mount that was stacked at
506       that location.
507
508       The parental relationship between mounts  can  be  discovered  via  the
509       /proc/[pid]/mountinfo file (see below).
510
511   /proc/[pid]/mounts and /proc/[pid]/mountinfo
512       The  Linux-specific  /proc/[pid]/mounts file exposes the list of mounts
513       in the mount namespace of the  process  with  the  specified  ID.   The
514       /proc/[pid]/mountinfo  file exposes even more information about mounts,
515       including the propagation type and mount ID information that  makes  it
516       possible  to  discover  the  parental relationship between mounts.  See
517       proc(5) and mount_namespaces(7) for details of this file.
518

SEE ALSO

520       mountpoint(1),    chroot(2),     ioctl_iflags(2),     mount_settatr(2),
521       pivot_root(2),   umount(2),   mount_namespaces(7),  path_resolution(7),
522       findmnt(8), lsblk(8), mount(8), umount(8)
523

COLOPHON

525       This page is part of release 5.13 of the Linux  man-pages  project.   A
526       description  of  the project, information about reporting bugs, and the
527       latest    version    of    this    page,    can     be     found     at
528       https://www.kernel.org/doc/man-pages/.
529
530
531
532Linux                             2021-08-27                          MOUNT(2)
Impressum