Debian Codegraph @

upstream/debian-unstable/man2/move_mount.2

raw
1 .\" Copyright, the authors of the Linux man-pages project
2 .\"
3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
4 .\"
5 .TH move_mount 2 2026-02-11 "Linux man-pages 6.18"
6 .SH NAME
7 move_mount \- move or attach mount object to filesystem
8 .SH LIBRARY
9 Standard C library
10 .RI ( libc ,\~ \-lc )
11 .SH SYNOPSIS
12 .nf
13 .BR "#include <fcntl.h>" " /* Definition of " AT_* " constants */"
14 .B #include <sys/mount.h>
15 .P
16 .BI "int move_mount(int " from_dirfd ", const char *" from_path ,
17 .BI " int " to_dirfd ", const char *" to_path ,
18 .BI " unsigned int " flags );
19 .fi
20 .SH DESCRIPTION
21 The
22 .BR move_mount ()
23 system call is part of
24 the suite of file-descriptor-based mount facilities in Linux.
25 .P
26 .BR move_mount ()
27 moves the mount object indicated by
28 .I from_dirfd
29 and
30 .I from_path
31 to the path indicated by
32 .I to_dirfd
33 and
34 .IR to_path .
35 The mount object being moved
36 can be an existing mount point in the current mount namespace,
37 or a detached mount object created by
38 .BR fsmount (2)
39 or
40 .BR open_tree (2)
41 with
42 .BR \%OPEN_TREE_CLONE .
43 .P
44 To access the source mount object
45 or the destination mount point,
46 no permissions are required on the object itself,
47 but if either pathname is supplied,
48 execute (search) permission is required
49 on all of the directories specified in
50 .I from_path
51 or
52 .IR to_path .
53 .P
54 The calling process must have the
55 .B \%CAP_SYS_ADMIN
56 capability in order to move or attach a mount object.
57 .P
58 As with "*at()" system calls,
59 .BR move_mount ()
60 uses the
61 .I from_dirfd
62 and
63 .I to_dirfd
64 arguments
65 in conjunction with the
66 .I from_path
67 and
68 .I to_path
69 arguments to determine the source and destination objects to operate on
70 (respectively), as follows:
71 .IP \[bu] 3
72 If the pathname given in
73 .RI * _path
74 is absolute, then
75 the corresponding
76 .RI * _dirfd
77 is ignored.
78 .IP \[bu]
79 If the pathname given in
80 .RI * _path
81 is relative and
82 the corresponding
83 .RI * _dirfd
84 is the special value
85 .BR \%AT_FDCWD ,
86 then
87 .RI * _path
88 is interpreted relative to
89 the current working directory
90 of the calling process (like
91 .BR open (2)).
92 .IP \[bu]
93 If the pathname given in
94 .RI * _path
95 is relative,
96 then it is interpreted relative to
97 the directory referred to by
98 the corresponding file descriptor
99 .RI * _dirfd
100 (rather than relative to
101 the current working directory
102 of the calling process,
103 as is done by
104 .BR open (2)
105 for a relative pathname).
106 In this case,
107 the corresponding
108 .RI * _dirfd
109 must be a directory
110 that was opened for reading
111 .RB ( O_RDONLY )
112 or using the
113 .B O_PATH
114 flag.
115 .IP \[bu]
116 If
117 .RI * _path
118 is an empty string,
119 and
120 .I flags
121 contains the appropriate
122 .BI \%MOVE_MOUNT_ * _EMPTY_PATH
123 flag,
124 then the corresponding file descriptor
125 .RI * _dirfd
126 is operated on directly.
127 In this case,
128 the corresponding
129 .RI * _dirfd
130 may refer to any type of file,
131 not just a directory.
132 .P
133 See
134 .BR openat (2)
135 for an explanation of why the
136 .RI * _dirfd
137 arguments are useful.
138 .P
139 .I flags
140 can be used to control aspects of the path lookup
141 for both the source and destination objects,
142 as well as other properties of the mount operation.
143 A value for
144 .I flags
145 is constructed by bitwise ORing
146 zero or more of the following constants:
147 .RS
148 .TP
149 .B MOVE_MOUNT_F_EMPTY_PATH
150 If
151 .I from_path
152 is an empty string, operate on the file referred to by
153 .I from_dirfd
154 (which may have been obtained from
155 .BR open (2),
156 .BR fsmount (2),
157 or
158 .BR open_tree (2)).
159 In this case,
160 .I from_dirfd
161 may refer to any type of file,
162 not just a directory.
163 If
164 .I from_dirfd
165 is
166 .BR \%AT_FDCWD ,
167 .BR move_mount ()
168 will operate on the current working directory
169 of the calling process.
170 .IP
171 This is the most common mechanism
172 used to attach detached mount objects
173 produced by
174 .BR fsmount (2)
175 and
176 .BR open_tree (2)
177 to a mount point.
178 .TP
179 .B MOVE_MOUNT_T_EMPTY_PATH
180 As with
181 .BR \%MOVE_MOUNT_F_EMPTY_PATH ,
182 except operating on
183 .I to_dirfd
184 and
185 .IR to_path .
186 .TP
187 .B MOVE_MOUNT_F_SYMLINKS
188 If
189 .I from_path
190 references a symbolic link,
191 then dereference it.
192 The default behavior for
193 .BR move_mount ()
194 is to
195 .I not follow
196 symbolic links.
197 .TP
198 .B MOVE_MOUNT_T_SYMLINKS
199 As with
200 .BR \%MOVE_MOUNT_F_SYMLINKS ,
201 except operating on
202 .I to_dirfd
203 and
204 .IR to_path .
205 .TP
206 .B MOVE_MOUNT_F_NO_AUTOMOUNT
207 Do not automount the terminal ("basename") component of
208 .I \%from_path
209 if it is a directory that is an automount point.
210 This allows a mount object
211 that has an automount point at its root
212 to be moved
213 and prevents unintended triggering of an automount point.
214 This flag has no effect
215 if the automount point has already been mounted over.
216 .TP
217 .B MOVE_MOUNT_T_NO_AUTOMOUNT
218 As with
219 .BR \%MOVE_MOUNT_F_NO_AUTOMOUNT ,
220 except operating on
221 .I to_dirfd
222 and
223 .IR to_path .
224 This allows an automount point to be manually mounted over.
225 .TP
226 .BR MOVE_MOUNT_SET_GROUP " (since Linux 5.15)"
227 Add the attached private-propagation mount object indicated by
228 .I to_dirfd
229 and
230 .I to_path
231 into the mount propagation "peer group"
232 of the attached non-private-propagation mount object indicated by
233 .I from_dirfd
234 and
235 .IR from_path .
236 .IP
237 Unlike other
238 .BR move_mount ()
239 operations,
240 this operation does not move or attach any mount objects.
241 Instead, it only updates the metadata
242 of attached mount objects.
243 (Also, take careful note of
244 the argument order\[em]\c
245 the mount object being modified
246 by this operation is the one specified by
247 .I to_dirfd
248 and
249 .IR to_path .)
250 .IP
251 This makes it possible to first create a mount tree
252 consisting only of private mounts
253 and then configure the desired propagation layout afterwards.
254 (See the "SHARED SUBTREES" section of
255 .BR mount_namespaces (7)
256 for more information about mount propagation and peer groups.)
257 .TP
258 .BR MOVE_MOUNT_BENEATH " (since Linux 6.5)"
259 If the path indicated by
260 .I to_dirfd
261 and
262 .I to_path
263 is an existing mount object,
264 rather than attaching or moving the mount object
265 indicated by
266 .I from_dirfd
267 and
268 .I from_path
269 on top of the mount stack,
270 attach or move it beneath the current top mount
271 on the mount stack.
272 .IP
273 After using
274 .BR \%MOVE_MOUNT_BENEATH ,
275 it is possible to
276 .BR umount (2)
277 the top mount
278 in order to reveal the mount object
279 which was attached beneath it earlier.
280 This allows for the seamless (and atomic) replacement
281 of intricate mount trees,
282 which can further be used
283 to "upgrade" a mount tree with a newer version.
284 .IP
285 This operation has several restrictions:
286 .RS
287 .IP \[bu] 3
288 Mount objects cannot be attached beneath the filesystem root,
289 including cases where
290 the filesystem root was configured by
291 .BR chroot (2)
292 or
293 .BR pivot_root (2).
294 To mount beneath the filesystem root,
295 .BR pivot_root (2)
296 must be used.
297 .IP \[bu]
298 The target path indicated by
299 .I to_dirfd
300 and
301 .I to_path
302 must not be a detached mount object,
303 such as those produced by
304 .BR open_tree (2)
305 with
306 .B \%OPEN_TREE_CLONE
307 or
308 .BR fsmount (2).
309 .IP \[bu]
310 The current top mount
311 of the target path's mount stack
312 and its parent mount
313 must be in the calling process's mount namespace.
314 .IP \[bu]
315 The caller must have sufficient privileges
316 to unmount the top mount
317 of the target path's mount stack,
318 to prove they have privileges
319 to reveal the underlying mount.
320 .IP \[bu]
321 Mount propagation events triggered by this
322 .BR move_mount ()
323 operation
324 (as described in
325 .BR mount_namespaces (7))
326 are calculated based on the parent mount
327 of the current top mount
328 of the target path's mount stack.
329 .IP \[bu]
330 The target path's mount
331 cannot be an ancestor in the mount tree of
332 the source mount object.
333 .IP \[bu]
334 The source mount object
335 must not have any overmounts,
336 otherwise it would be possible to create "shadow mounts"
337 (i.e., two mounts mounted on the same parent mount at the same mount point).
338 .IP \[bu]
339 It is not possible to move a mount
340 beneath a top mount
341 if the parent mount
342 of the current top mount
343 propagates to the top mount itself.
344 Otherwise,
345 .B \%MOVE_MOUNT_BENEATH
346 would cause the mount object
347 to be propagated
348 to the top mount
349 from the parent mount,
350 defeating the purpose of using
351 .BR \%MOVE_MOUNT_BENEATH .
352 .IP \[bu]
353 It is not possible to move a mount
354 beneath a top mount
355 if the parent mount
356 of the current top mount
357 propagates to the mount object
358 being mounted beneath.
359 Otherwise, this would cause a similar propagation issue
360 to the previous point,
361 also defeating the purpose of using
362 .BR \%MOVE_MOUNT_BENEATH .
363 .RE
364 .RE
365 .P
366 If
367 .I from_dirfd
368 is a mount object file descriptor and
369 .BR move_mount ()
370 is operating on it directly,
371 .I from_dirfd
372 will remain associated with the mount object after
373 .BR move_mount ()
374 succeeds,
375 so you may repeatedly use
376 .I from_dirfd
377 with
378 .BR move_mount (2)
379 and/or "*at()" system calls
380 as many times as necessary.
381 .SH RETURN VALUE
382 On success,
383 .BR move_mount ()
384 returns 0.
385 On error, \-1 is returned, and
386 .I errno
387 is set to indicate the error.
388 .SH ERRORS
389 .TP
390 .B EACCES
391 Search permission is denied
392 for one of the directories
393 in the path prefix of one of
394 .I from_path
395 or
396 .IR to_path .
397 (See also
398 .BR path_resolution (7).)
399 .TP
400 .B EBADF
401 One of
402 .I from_dirfd
403 or
404 .I to_dirfd
405 is not a valid file descriptor.
406 .TP
407 .B EFAULT
408 One of
409 .I from_path
410 or
411 .I to_path
412 is NULL
413 or a pointer to a location
414 outside the calling process's accessible address space.
415 .TP
416 .B EINVAL
417 Invalid flag specified in
418 .IR flags .
419 .TP
420 .B EINVAL
421 The path indicated by
422 .I from_dirfd
423 and
424 .I from_path
425 is not a mount object.
426 .TP
427 .B EINVAL
428 The mount object type
429 of the source mount object and target inode
430 are not compatible
431 (i.e., the source is a file but the target is a directory, or vice-versa).
432 .TP
433 .B EINVAL
434 The source mount object or target path
435 are not in the calling process's mount namespace
436 (or an anonymous mount namespace of the calling process).
437 .TP
438 .B EINVAL
439 The source mount object's parent mount
440 has shared mount propagation,
441 and thus cannot be moved
442 (as described in
443 .BR mount_namespaces (7)).
444 .TP
445 .B EINVAL
446 The source mount has
447 .B MS_UNBINDABLE
448 child mounts
449 but the target path
450 resides on a mount tree with shared mount propagation,
451 which would otherwise cause the unbindable mounts to be propagated
452 (as described in
453 .BR mount_namespaces (7)).
454 .TP
455 .B EINVAL
456 .B \%MOVE_MOUNT_BENEATH
457 was attempted,
458 but one of the listed restrictions was violated.
459 .TP
460 .B ELOOP
461 Too many symbolic links encountered
462 when resolving one of
463 .I from_path
464 or
465 .IR to_path .
466 .TP
467 .B ENAMETOOLONG
468 One of
469 .I from_path
470 or
471 .I to_path
472 is longer than
473 .BR PATH_MAX .
474 .TP
475 .B ENOENT
476 A component of one of
477 .I from_path
478 or
479 .I to_path
480 does not exist.
481 .TP
482 .B ENOENT
483 One of
484 .I from_path
485 or
486 .I to_path
487 is an empty string,
488 but the corresponding
489 .BI MOVE_MOUNT_ * _EMPTY_PATH
490 flag is not specified in
491 .IR flags .
492 .TP
493 .B ENOTDIR
494 A component of the path prefix of one of
495 .I from_path
496 or
497 .I to_path
498 is not a directory,
499 or one of
500 .I from_path
501 or
502 .I to_path
503 is relative
504 and the corresponding
505 .I from_dirfd
506 or
507 .I to_dirfd
508 is a file descriptor referring to a file other than a directory.
509 .TP
510 .B ENOMEM
511 The kernel could not allocate sufficient memory to complete the operation.
512 .TP
513 .B EPERM
514 The calling process does not have the required
515 .B \%CAP_SYS_ADMIN
516 capability.
517 .SH STANDARDS
518 Linux.
519 .SH HISTORY
520 Linux 5.2,
521 .\" commit 2db154b3ea8e14b04fee23e3fdfd5e9d17fbc6ae
522 .\" commit 400913252d09f9cfb8cce33daee43167921fc343
523 glibc 2.36.
524 .SH EXAMPLES
525 .BR move_mount ()
526 can be used to move attached mounts like the following:
527 .P
528 .in +4n
529 .EX
530 move_mount(AT_FDCWD, "/a", AT_FDCWD, "/b", 0);
531 .EE
532 .in
533 .P
534 This would move the mount object mounted on
535 .I /a
536 to
537 .IR /b .
538 The above procedure is functionally equivalent to
539 the following mount operation
540 using
541 .BR mount (2):
542 .P
543 .in +4n
544 .EX
545 mount("/a", "/b", NULL, MS_MOVE, NULL);
546 .EE
547 .in
548 .P
549 .BR move_mount ()
550 can also be used in conjunction with file descriptors returned from
551 .BR open_tree (2)
552 or
553 .BR open (2):
554 .P
555 .in +4n
556 .EX
557 int fd = open_tree(AT_FDCWD, "/mnt", 0); /* open("/mnt", O_PATH); */
558 move_mount(fd, "", AT_FDCWD, "/mnt2", MOVE_MOUNT_F_EMPTY_PATH);
559 move_mount(fd, "", AT_FDCWD, "/mnt3", MOVE_MOUNT_F_EMPTY_PATH);
560 move_mount(fd, "", AT_FDCWD, "/mnt4", MOVE_MOUNT_F_EMPTY_PATH);
561 .EE
562 .in
563 .P
564 This would move the mount object mounted at
565 .I /mnt
566 to
567 .IR /mnt2 ,
568 then
569 .IR /mnt3 ,
570 and then
571 .IR /mnt4 .
572 .P
573 If the source mount object
574 indicated by
575 .I from_dirfd
576 and
577 .I from_path
578 is a detached mount object,
579 .BR move_mount ()
580 can be used to attach it to a mount point:
581 .P
582 .in +4n
583 .EX
584 int fsfd, mntfd;
585 \&
586 fsfd = fsopen("ext4", FSOPEN_CLOEXEC);
587 fsconfig(fsfd, FSCONFIG_SET_STRING, "source", "/dev/sda1", 0);
588 fsconfig(fsfd, FSCONFIG_SET_FLAG, "user_xattr", NULL, 0);
589 fsconfig(fsfd, FSCONFIG_CMD_CREATE, NULL, NULL, 0);
590 mntfd = fsmount(fsfd, FSMOUNT_CLOEXEC, MOUNT_ATTR_NODEV);
591 move_mount(mntfd, "", AT_FDCWD, "/home", MOVE_MOUNT_F_EMPTY_PATH);
592 .EE
593 .in
594 .P
595 This would create a new filesystem configuration context for ext4,
596 configure it,
597 create a detached mount object,
598 and then attach it to
599 .IR /home .
600 The above procedure is functionally equivalent to
601 the following mount operation
602 using
603 .BR mount (2):
604 .P
605 .in +4n
606 .EX
607 mount("/dev/sda1", "/home", "ext4", MS_NODEV, "user_xattr");
608 .EE
609 .in
610 .P
611 The same operation also works with detached bind-mounts created with
612 .BR open_tree (2)
613 with
614 .BR OPEN_TREE_CLONE :
615 .P
616 .in +4n
617 .EX
618 int mntfd = open_tree(AT_FDCWD, "/home/cyphar", OPEN_TREE_CLONE);
619 move_mount(mntfd, "", AT_FDCWD, "/root", MOVE_MOUNT_F_EMPTY_PATH);
620 .EE
621 .in
622 .P
623 This would create a new bind-mount of
624 .I /home/cyphar
625 as a detached mount object,
626 and then attach it to
627 .IR /root .
628 The above procedure is functionally equivalent to
629 the following mount operation
630 using
631 .BR mount (2):
632 .P
633 .in +4n
634 .EX
635 mount("/home/cyphar", "/root", NULL, MS_BIND, NULL);
636 .EE
637 .in
638 .SH SEE ALSO
639 .BR fsconfig (2),
640 .BR fsmount (2),
641 .BR fsopen (2),
642 .BR fspick (2),
643 .BR mount (2),
644 .BR mount_setattr (2),
645 .BR open_tree (2),
646 .BR mount_namespaces (7)