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
18       directory  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
45          includes 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
89              enabled.    (The   advantage  of  combining  MS_STRICTATIME  and
90              MS_LAZYTIME is that stat(2) will return  the  correctly  updated
91              atime, but the atime updates will be flushed to disk only in the
92              cases 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
97              described in fcntl(2).)  Since  Linux  4.5,  this  mount  option
98              requires  the  CAP_SYS_ADMIN  capability and a kernel configured
99              with 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
127              recursively  change the propagation type of all of the mounts in
128              a 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
139              required 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       From Linux 2.4 onward, some of the above flags are settable on  a  per-
161       mount  basis,  while  others  apply  to  the  superblock of the mounted
162       filesystem, meaning that all mounts of the same filesystem share  those
163       flags.  (Previously, all of the flags were per-superblock.)
164
165       The per-mount-point flags are as follows:
166
167       *  Since  Linux  2.4: MS_NODEV, MS_NOEXEC, and MS_NOSUID flags are set‐
168          table on a per-mount-point basis.
169
170       *  Since Linux 2.6.16: MS_NOATIME and MS_NODIRATIME.
171
172       *  Since Linux 2.6.20: MS_RELATIME.
173
174       The  following  flags  are  per-superblock:  MS_DIRSYNC,   MS_LAZYTIME,
175       MS_MANDLOCK,  MS_SILENT,  and  MS_SYNCHRONOUS.  The initial settings of
176       these flags are determined on the first mount of  the  filesystem,  and
177       will be shared by all subsequent mounts of the same filesystem.  Subse‐
178       quently, the settings of the flags can be changed via a remount  opera‐
179       tion  (see  below).   Such changes will be visible via all mount points
180       associated with the filesystem.
181
182       Since Linux 2.6.16, MS_RDONLY can be set or  cleared  on  a  per-mount-
183       point  basis  as  well as on the underlying filesystem superblock.  The
184       mounted filesystem will be writable only if neither the filesystem  nor
185       the mountpoint are flagged as read-only.
186
187   Remounting an existing mount
188       An  existing  mount may be remounted by specifying MS_REMOUNT in mount‐
189       flags.  This allows you to change the mountflags and data of an  exist‐
190       ing mount without having to unmount and remount the filesystem.  target
191       should be the same value specified in the initial mount() call.
192
193       The source and filesystemtype arguments are ignored.
194
195       The mountflags and data arguments should match the values used  in  the
196       original  mount()  call,  except  for  those  parameters that are being
197       deliberately changed.
198
199       The following mountflags  can  be  changed:  MS_LAZYTIME,  MS_MANDLOCK,
200       MS_NOATIME, MS_NODEV, MS_NODIRATIME, MS_NOEXEC, MS_NOSUID, MS_RELATIME,
201       MS_RDONLY, MS_STRICTATIME (whose effect is to clear the MS_NOATIME  and
202       MS_RELATIME flags), and MS_SYNCHRONOUS.  Attempts to change the setting
203       of the MS_DIRSYNC and MS_SILENT flags during  a  remount  are  silently
204       ignored.  Note that changes to per-superblock flags are visible via all
205       mount points of the associated filesystem (because  the  per-superblock
206       flags are shared by all mount points).
207
208       Since Linux 3.17, if none of MS_NOATIME, MS_NODIRATIME, MS_RELATIME, or
209       MS_STRICTATIME is specified in mountflags, then the  remount  operation
210       preserves the existing values of these flags (rather than defaulting to
211       MS_RELATIME).
212
213       Since Linux 2.6.26, the MS_REMOUNT flag can be  used  with  MS_BIND  to
214       modify only the per-mount-point flags.  This is particularly useful for
215       setting or clearing the "read-only"  flag  on  a  mount  point  without
216       changing the underlying filesystem.  Specifying mountflags as:
217
218           MS_REMOUNT | MS_BIND | MS_RDONLY
219
220       will  make  access through this mountpoint read-only, without affecting
221       other mount points.
222
223   Creating a bind mount
224       If mountflags includes MS_BIND (available since Linux 2.4),  then  per‐
225       form  a  bind  mount.  A bind mount makes a file or a directory subtree
226       visible at another point within the single directory  hierarchy.   Bind
227       mounts may cross filesystem boundaries and span chroot(2) jails.
228
229       The filesystemtype and data arguments are ignored.
230
231       The  remaining  bits (other than MS_REC, described below) in the mount‐
232       flags argument are also ignored.  (The bind mount has  the  same  mount
233       options as the underlying mount point.)  However, see the discussion of
234       remounting above, for a method of making an existing bind  mount  read-
235       only.
236
237       By  default,  when  a directory is bind mounted, only that directory is
238       mounted; if there are any submounts under the directory tree, they  are
239       not  bind mounted.  If the MS_REC flag is also specified, then a recur‐
240       sive bind mount operation is performed: all submounts under the  source
241       subtree  (other  than  unbindable  mounts) are also bind mounted at the
242       corresponding location in the target subtree.
243
244   Changing the propagation type of an existing mount
245       If mountflags includes  one  of  MS_SHARED,  MS_PRIVATE,  MS_SLAVE,  or
246       MS_UNBINDABLE  (all available since Linux 2.6.15), then the propagation
247       type of an existing mount is changed.  If more than one of these  flags
248       is specified, an error results.
249
250       The  only other flags that can be specified while changing the propaga‐
251       tion  type  are  MS_REC  (described  below)  and  MS_SILENT  (which  is
252       ignored).
253
254       The source, filesystemtype, and data arguments are ignored.
255
256       The meanings of the propagation type flags are as follows:
257
258       MS_SHARED
259              Make  this mount point shared.  Mount and unmount events immedi‐
260              ately under this mount point will propagate to the  other  mount
261              points that are members of this mount's peer group.  Propagation
262              here means that the same mount  or  unmount  will  automatically
263              occur  under  all  of  the other mount points in the peer group.
264              Conversely, mount and unmount events that take place under  peer
265              mount points will propagate to this mount point.
266
267       MS_PRIVATE
268              Make  this mount point private.  Mount and unmount events do not
269              propagate into or out of this mount point.
270
271       MS_SLAVE
272              If this is a shared mount point that is a member of a peer group
273              that  contains  other  members, convert it to a slave mount.  If
274              this is a shared mount point that is a member of  a  peer  group
275              that  contains  no other members, convert it to a private mount.
276              Otherwise, the propagation type  of  the  mount  point  is  left
277              unchanged.
278
279              When  a  mount point is a slave, mount and unmount events propa‐
280              gate into this mount point from the (master) shared  peer  group
281              of  which  it  was  formerly a member.  Mount and unmount events
282              under this mount point do not propagate to any peer.
283
284              A mount point can be the slave of another peer  group  while  at
285              the same time sharing mount and unmount events with a peer group
286              of which it is a member.
287
288       MS_UNBINDABLE
289              Make this mount unbindable.  This is like a private  mount,  and
290              in  addition this mount can't be bind mounted.  When a recursive
291              bind mount (mount() with the MS_BIND and MS_REC flags)  is  per‐
292              formed  on a directory subtree, any unbindable mounts within the
293              subtree are automatically pruned  (i.e.,  not  replicated)  when
294              replicating that subtree to produce the target subtree.
295
296       By default, changing the propagation type affects only the target mount
297       point.  If the MS_REC flag is also specified in  mountflags,  then  the
298       propagation type of all mount points under target is also changed.
299
300       For  further  details  regarding mount propagation types (including the
301       default propagation type assigned  to  new  mounts),  see  mount_names‐
302       paces(7).
303
304   Moving a mount
305       If mountflags contains the flag MS_MOVE (available since Linux 2.4.18),
306       then move a subtree: source specifies an existing mount point and  tar‐
307       get specifies the new location to which that mount point is to be relo‐
308       cated.  The move is atomic: at no point is the subtree unmounted.
309
310       The remaining bits in the mountflags argument are ignored, as  are  the
311       filesystemtype and data arguments.
312
313   Creating a new mount point
314       If   none  of  MS_REMOUNT,  MS_BIND,  MS_MOVE,  MS_SHARED,  MS_PRIVATE,
315       MS_SLAVE, or MS_UNBINDABLE is specified  in  mountflags,  then  mount()
316       performs its default action: creating a new mount point.  source speci‐
317       fies the source for the new  mount  point,  and  target  specifies  the
318       directory at which to create the mount point.
319
320       The  filesystemtype  and  data arguments are employed, and further bits
321       may be specified in mountflags to modify the behavior of the call.
322

RETURN VALUE

324       On success, zero is returned.  On error, -1 is returned, and  errno  is
325       set appropriately.
326

ERRORS

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

VERSIONS

425       The definitions of MS_DIRSYNC, MS_MOVE,  MS_PRIVATE,  MS_REC,  MS_RELA‐
426       TIME, MS_SHARED, MS_SLAVE, MS_STRICTATIME, and MS_UNBINDABLE were added
427       to glibc headers in version 2.12.
428

CONFORMING TO

430       This function is Linux-specific and should  not  be  used  in  programs
431       intended to be portable.
432

NOTES

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

SEE ALSO

501       mountpoint(1), chroot(2),  ioctl_iflags(2),  pivot_root(2),  umount(2),
502       mount_namespaces(7),    path_resolution(7),    findmnt(8),    lsblk(8),
503       mount(8), umount(8)
504

COLOPHON

506       This page is part of release 5.04 of the Linux  man-pages  project.   A
507       description  of  the project, information about reporting bugs, and the
508       latest    version    of    this    page,    can     be     found     at
509       https://www.kernel.org/doc/man-pages/.
510
511
512
513Linux                             2019-08-02                          MOUNT(2)
Impressum