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