Debian Codegraph @

upstream/debian-unstable/man2/mount_setattr.2

raw
1 .\" Copyright 2021, Christian Brauner <[email protected]>
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH mount_setattr 2 2026-02-11 "Linux man-pages 6.18"
7 .SH NAME
8 mount_setattr \- change properties of a mount or mount tree
9 .SH LIBRARY
10 Standard C library
11 .RI ( libc ,\~ \-lc )
12 .SH SYNOPSIS
13 .nf
14 .BR "#include <fcntl.h>" " /* Definition of " AT_* " constants */"
15 .B #include <sys/mount.h>
16 .P
17 .BI "int mount_setattr(int " dirfd ", const char *" path ", unsigned int " flags ","
18 .BI " struct mount_attr *" attr ", size_t " size );
19 .fi
20 .SH DESCRIPTION
21 The
22 .BR mount_setattr ()
23 system call is part of
24 the suite of file-descriptor-based mount facilities in Linux.
25 .P
26 .BR mount_setattr ()
27 changes the mount properties of a mount or an entire mount tree.
28 If
29 .I path
30 is relative,
31 then it is interpreted relative to
32 the directory referred to by the file descriptor
33 .IR dirfd .
34 If
35 .I dirfd
36 is the special value
37 .BR AT_FDCWD ,
38 then
39 .I path
40 is interpreted relative to
41 the current working directory of the calling process.
42 If
43 .I path
44 is the empty string and
45 .B AT_EMPTY_PATH
46 is specified in
47 .IR flags ,
48 then the mount properties of the mount identified by
49 .I dirfd
50 are changed.
51 (See
52 .BR openat (2)
53 for an explanation of why the
54 .I dirfd
55 argument is useful.)
56 .P
57 The
58 .BR mount_setattr ()
59 system call uses an extensible structure
60 .RI ( "struct mount_attr" )
61 to allow for future extensions.
62 Any non-flag extensions to
63 .BR mount_setattr ()
64 will be implemented as new fields appended to the this structure,
65 with a zero value in a new field resulting in the kernel behaving
66 as though that extension field was not present.
67 Therefore,
68 the caller
69 .I must
70 zero-fill this structure on initialization.
71 See the "Extensibility" subsection under
72 .B NOTES
73 for more details.
74 .P
75 The
76 .I size
77 argument should usually be specified as
78 .IR "sizeof(struct mount_attr)" .
79 However, if the caller is using a kernel that supports an extended
80 .IR "struct mount_attr" ,
81 but the caller does not intend to make use of these features,
82 it is possible to pass the size of an earlier
83 version of the structure together with the extended structure.
84 This allows the kernel to not copy later parts of the structure
85 that aren't used anyway.
86 With each extension that changes the size of
87 .IR "struct mount_attr" ,
88 the kernel will expose a definition of the form
89 .BI MOUNT_ATTR_SIZE_VER number\c
90 \&.
91 For example, the macro for the size of the initial version of
92 .I struct mount_attr
93 is
94 .BR MOUNT_ATTR_SIZE_VER0 .
95 .P
96 The
97 .I flags
98 argument can be used to alter the pathname resolution behavior.
99 The supported values are:
100 .TP
101 .B AT_EMPTY_PATH
102 If
103 .I path
104 is the empty string,
105 change the mount properties on
106 .I dirfd
107 itself.
108 .TP
109 .B AT_RECURSIVE
110 Change the mount properties of the entire mount tree.
111 .TP
112 .B AT_SYMLINK_NOFOLLOW
113 Don't follow trailing symbolic links.
114 .TP
115 .B AT_NO_AUTOMOUNT
116 Don't trigger automounts.
117 .P
118 The
119 .I attr
120 argument of
121 .BR mount_setattr ()
122 is a pointer to a
123 .I mount_attr
124 structure,
125 described in
126 .BR mount_attr (2type).
127 .P
128 The
129 .I attr_set
130 and
131 .I attr_clr
132 members are used to specify the mount properties that
133 are supposed to be set or cleared for a mount or mount tree.
134 Flags set in
135 .I attr_set
136 enable a property on a mount or mount tree,
137 and flags set in
138 .I attr_clr
139 remove a property from a mount or mount tree.
140 .P
141 When changing mount properties,
142 the kernel will first clear the flags specified
143 in the
144 .I attr_clr
145 field,
146 and then set the flags specified in the
147 .I attr_set
148 field.
149 For example, these settings:
150 .P
151 .in +4n
152 .EX
153 struct mount_attr attr = {
154 .attr_clr = MOUNT_ATTR_NOEXEC | MOUNT_ATTR_NODEV,
155 .attr_set = MOUNT_ATTR_RDONLY | MOUNT_ATTR_NOSUID,
156 };
157 .EE
158 .in
159 .P
160 are equivalent to the following steps:
161 .P
162 .in +4n
163 .EX
164 unsigned int current_mnt_flags = mnt\->mnt_flags;
165 \&
166 /*
167 * Clear all flags set in .attr_clr,
168 * clearing MOUNT_ATTR_NOEXEC and MOUNT_ATTR_NODEV.
169 */
170 current_mnt_flags &= \(tiattr\->attr_clr;
171 \&
172 /*
173 * Now set all flags set in .attr_set,
174 * applying MOUNT_ATTR_RDONLY and MOUNT_ATTR_NOSUID.
175 */
176 current_mnt_flags |= attr\->attr_set;
177 \&
178 mnt\->mnt_flags = current_mnt_flags;
179 .EE
180 .in
181 .P
182 As a result of this change, the mount or mount tree (a) is read-only;
183 (b) blocks the execution of set-user-ID and set-group-ID programs;
184 (c) allows execution of programs;
185 and
186 (d) allows access to devices.
187 .P
188 Multiple changes with the same set of flags requested
189 in
190 .I attr_clr
191 and
192 .I attr_set
193 are guaranteed to be idempotent after the changes have been applied.
194 .P
195 The following mount attributes can be specified in the
196 .I attr_set
197 or
198 .I attr_clr
199 fields:
200 .TP
201 .B MOUNT_ATTR_RDONLY
202 If set in
203 .IR attr_set ,
204 makes the mount read-only.
205 If set in
206 .IR attr_clr ,
207 removes the read-only setting if set on the mount.
208 .TP
209 .B MOUNT_ATTR_NOSUID
210 If set in
211 .IR attr_set ,
212 causes the mount not to honor the set-user-ID and set-group-ID mode bits and
213 file capabilities when executing programs.
214 If set in
215 .IR attr_clr ,
216 clears the set-user-ID, set-group-ID,
217 and file capability restriction if set on this mount.
218 .TP
219 .B MOUNT_ATTR_NODEV
220 If set in
221 .IR attr_set ,
222 prevents access to devices on this mount.
223 If set in
224 .IR attr_clr ,
225 removes the restriction that prevented accessing devices on this mount.
226 .TP
227 .B MOUNT_ATTR_NOEXEC
228 If set in
229 .IR attr_set ,
230 prevents executing programs on this mount.
231 If set in
232 .IR attr_clr ,
233 removes the restriction that prevented executing programs on this mount.
234 .TP
235 .B MOUNT_ATTR_NOSYMFOLLOW
236 If set in
237 .IR attr_set ,
238 prevents following symbolic links on this mount.
239 If set in
240 .IR attr_clr ,
241 removes the restriction that prevented following symbolic links on this mount.
242 .TP
243 .B MOUNT_ATTR_NODIRATIME
244 If set in
245 .IR attr_set ,
246 prevents updating access time for directories on this mount.
247 If set in
248 .IR attr_clr ,
249 removes the restriction that prevented updating access time for directories.
250 Note that
251 .B MOUNT_ATTR_NODIRATIME
252 can be combined with other access-time settings
253 and is implied by the noatime setting.
254 All other access-time settings are mutually exclusive.
255 .TP
256 .BR MOUNT_ATTR__ATIME " - changing access-time settings"
257 The access-time values listed below are an enumeration that
258 includes the value zero, expressed in the bits defined by the mask
259 .BR MOUNT_ATTR__ATIME .
260 Even though these bits are an enumeration
261 (in contrast to the other mount flags such as
262 .BR MOUNT_ATTR_NOEXEC ),
263 they are nonetheless passed in
264 .I attr_set
265 and
266 .I attr_clr
267 for consistency with
268 .BR fsmount (2),
269 which introduced this behavior.
270 .IP
271 Note that,
272 since the access-time values are an enumeration rather than bit values,
273 a caller wanting to transition to a different access-time setting
274 cannot simply specify the access-time setting in
275 .IR attr_set ,
276 but must also include
277 .B MOUNT_ATTR__ATIME
278 in the
279 .I attr_clr
280 field.
281 The kernel will verify that
282 .B MOUNT_ATTR__ATIME
283 isn't partially set in
284 .I attr_clr
285 (i.e., either all bits in the
286 .B MOUNT_ATTR__ATIME
287 bit field are either set or clear), and that
288 .I attr_set
289 doesn't have any access-time bits set if
290 .B MOUNT_ATTR__ATIME
291 isn't set in
292 .IR attr_clr .
293 .RS
294 .TP
295 .B MOUNT_ATTR_RELATIME
296 When a file is accessed via this mount,
297 update the file's last access time (atime)
298 only if the current value of atime is less than or equal to
299 the file's last modification time (mtime) or last status change time (ctime).
300 .IP
301 To enable this access-time setting on a mount or mount tree,
302 .B MOUNT_ATTR_RELATIME
303 must be set in
304 .I attr_set
305 and
306 .B MOUNT_ATTR__ATIME
307 must be set in the
308 .I attr_clr
309 field.
310 .TP
311 .B MOUNT_ATTR_NOATIME
312 Do not update access times for (all types of) files on this mount.
313 .IP
314 To enable this access-time setting on a mount or mount tree,
315 .B MOUNT_ATTR_NOATIME
316 must be set in
317 .I attr_set
318 and
319 .B MOUNT_ATTR__ATIME
320 must be set in the
321 .I attr_clr
322 field.
323 .TP
324 .B MOUNT_ATTR_STRICTATIME
325 Always update the last access time (atime)
326 when files are accessed on this mount.
327 .IP
328 To enable this access-time setting on a mount or mount tree,
329 .B MOUNT_ATTR_STRICTATIME
330 must be set in
331 .I attr_set
332 and
333 .B MOUNT_ATTR__ATIME
334 must be set in the
335 .I attr_clr
336 field.
337 .RE
338 .TP
339 .B MOUNT_ATTR_IDMAP
340 If set in
341 .IR attr_set ,
342 creates an ID-mapped mount.
343 The ID mapping is taken from the user namespace specified in
344 .I userns_fd
345 and attached to the mount.
346 .IP
347 Since it is not supported to
348 change the ID mapping of a mount after it has been ID mapped,
349 it is invalid to specify
350 .B MOUNT_ATTR_IDMAP
351 in
352 .IR attr_clr .
353 .IP
354 For further details, see the subsection "ID-mapped mounts" under NOTES.
355 .P
356 The
357 .I propagation
358 field is used to specify the propagation type of the mount or mount tree.
359 This field either has the value zero,
360 meaning leave the propagation type unchanged, or it has one of
361 the following values:
362 .TP
363 .B MS_PRIVATE
364 Turn all mounts into private mounts.
365 .TP
366 .B MS_SHARED
367 Turn all mounts into shared mounts.
368 .TP
369 .B MS_SLAVE
370 Turn all mounts into dependent mounts.
371 .TP
372 .B MS_UNBINDABLE
373 Turn all mounts into unbindable mounts.
374 .P
375 For further details on the above propagation types, see
376 .BR mount_namespaces (7).
377 .SH RETURN VALUE
378 On success,
379 .BR mount_setattr ()
380 returns zero.
381 On error,
382 \-1 is returned and
383 .I errno
384 is set to indicate the error.
385 .SH ERRORS
386 .TP
387 .B EBADF
388 .I path
389 is relative but
390 .I dirfd
391 is neither
392 .B AT_FDCWD
393 nor a valid file descriptor.
394 .TP
395 .B EBADF
396 .I userns_fd
397 is not a valid file descriptor.
398 .TP
399 .B EBUSY
400 The caller tried to change the mount to
401 .BR MOUNT_ATTR_RDONLY ,
402 but the mount still holds files open for writing.
403 .TP
404 .B EBUSY
405 The caller tried to create an ID-mapped mount raising
406 .B MOUNT_ATTR_IDMAP
407 and specifying
408 .I userns_fd
409 but the mount still holds files open for writing.
410 .TP
411 .B EINVAL
412 The pathname specified via the
413 .I dirfd
414 and
415 .I path
416 arguments to
417 .BR mount_setattr ()
418 isn't a mount point.
419 .TP
420 .B EINVAL
421 An unsupported value was set in
422 .IR flags .
423 .TP
424 .B EINVAL
425 An unsupported value was specified in the
426 .I attr_set
427 field of
428 .IR mount_attr .
429 .TP
430 .B EINVAL
431 An unsupported value was specified in the
432 .I attr_clr
433 field of
434 .IR mount_attr .
435 .TP
436 .B EINVAL
437 An unsupported value was specified in the
438 .I propagation
439 field of
440 .IR mount_attr .
441 .TP
442 .B EINVAL
443 More than one of
444 .BR MS_SHARED ,
445 .BR MS_SLAVE ,
446 .BR MS_PRIVATE ,
447 or
448 .B MS_UNBINDABLE
449 was set in the
450 .I propagation
451 field of
452 .IR mount_attr .
453 .TP
454 .B EINVAL
455 An access-time setting was specified in the
456 .I attr_set
457 field without
458 .B MOUNT_ATTR__ATIME
459 being set in the
460 .I attr_clr
461 field.
462 .TP
463 .B EINVAL
464 .B MOUNT_ATTR_IDMAP
465 was specified in
466 .IR attr_clr .
467 .TP
468 .B EINVAL
469 A file descriptor value was specified in
470 .I userns_fd
471 which exceeds
472 .BR INT_MAX .
473 .TP
474 .B EINVAL
475 A valid file descriptor value was specified in
476 .IR userns_fd ,
477 but the file descriptor did not refer to a user namespace.
478 .TP
479 .B EINVAL
480 The underlying filesystem does not support ID-mapped mounts.
481 .TP
482 .B EINVAL
483 The mount that is to be ID mapped is not a detached mount;
484 that is, the mount has not previously been visible in a mount namespace.
485 .TP
486 .B EINVAL
487 A partial access-time setting was specified in
488 .I attr_clr
489 instead of
490 .B MOUNT_ATTR__ATIME
491 being set.
492 .TP
493 .B EINVAL
494 The mount is located outside the caller's mount namespace.
495 .TP
496 .B EINVAL
497 The underlying filesystem has been mounted in a mount namespace that is
498 owned by a noninitial user namespace
499 .TP
500 .B ENOENT
501 A pathname was empty or had a nonexistent component.
502 .TP
503 .B ENOMEM
504 When changing mount propagation to
505 .BR MS_SHARED ,
506 a new peer group ID needs to be allocated for all mounts without a peer group
507 ID set.
508 This allocation failed because there was not
509 enough memory to allocate the relevant internal structures.
510 .TP
511 .B ENOSPC
512 When changing mount propagation to
513 .BR MS_SHARED ,
514 a new peer group ID needs to be allocated for all mounts without a peer group
515 ID set.
516 This allocation failed because
517 the kernel has run out of IDs.
518 .\" Christian Brauner: i.e., someone has somehow managed to
519 .\" allocate so many peer groups and managed to keep the kernel running
520 .\" (???) that the ida has ran out of ids
521 .\" Note that technically further error codes are possible that are
522 .\" specific to the ID allocation implementation used.
523 .TP
524 .B EPERM
525 One of the mounts had at least one of
526 .BR MOUNT_ATTR_NOATIME ,
527 .BR MOUNT_ATTR_NODEV ,
528 .BR MOUNT_ATTR_NODIRATIME ,
529 .BR MOUNT_ATTR_NOEXEC ,
530 .BR MOUNT_ATTR_NOSUID ,
531 or
532 .B MOUNT_ATTR_RDONLY
533 set and the flag is locked.
534 Mount attributes become locked on a mount if:
535 .RS
536 .IP \[bu] 3
537 A new mount or mount tree is created causing mount propagation across user
538 namespaces
539 (i.e., propagation to a mount namespace owned by a different user namespace).
540 The kernel will lock the aforementioned flags to prevent these sensitive
541 properties from being altered.
542 .IP \[bu]
543 A new mount and user namespace pair is created.
544 This happens for example when specifying
545 .B CLONE_NEWUSER | CLONE_NEWNS
546 in
547 .BR unshare (2),
548 .BR clone (2),
549 or
550 .BR clone3 (2).
551 The aforementioned flags become locked in the new mount namespace
552 to prevent sensitive mount properties from being altered.
553 Since the newly created mount namespace will be owned by the
554 newly created user namespace,
555 a calling process that is privileged in the new
556 user namespace would\[em]in the absence of such locking\[em]be
557 able to alter sensitive mount properties (e.g., to remount a mount
558 that was marked read-only as read-write in the new mount namespace).
559 .RE
560 .TP
561 .B EPERM
562 A valid file descriptor value was specified in
563 .IR userns_fd ,
564 but the file descriptor refers to the initial user namespace.
565 .TP
566 .B EPERM
567 An attempt was made to add an ID mapping to a mount that is already ID mapped.
568 .TP
569 .B EPERM
570 The caller does not have
571 .B CAP_SYS_ADMIN
572 in the initial user namespace.
573 .SH STANDARDS
574 Linux.
575 .SH HISTORY
576 Linux 5.12,
577 .\" commit 7d6beb71da3cc033649d641e1e608713b8220290
578 .\" commit 2a1867219c7b27f928e2545782b86daaf9ad50bd
579 .\" commit 9caccd41541a6f7d6279928d9f971f6642c361af
580 glibc 2.36.
581 .SH NOTES
582 .SS ID-mapped mounts
583 Creating an ID-mapped mount makes it possible to
584 change the ownership of all files located under a mount.
585 Thus, ID-mapped mounts make it possible to
586 change ownership in a temporary and localized way.
587 It is a localized change because the ownership changes are
588 visible only via a specific mount.
589 All other users and locations where the filesystem is exposed are unaffected.
590 It is a temporary change because
591 the ownership changes are tied to the lifetime of the mount.
592 .P
593 Whenever callers interact with the filesystem through an ID-mapped mount,
594 the ID mapping of the mount will be applied to
595 user and group IDs associated with filesystem objects.
596 This encompasses the user and group IDs associated with inodes
597 and also the following
598 .BR xattr (7)
599 keys:
600 .IP \[bu] 3
601 .IR security.capability ,
602 whenever filesystem capabilities
603 are stored or returned in the
604 .B VFS_CAP_REVISION_3
605 format,
606 which stores a root user ID alongside the capabilities
607 (see
608 .BR capabilities (7)).
609 .IP \[bu]
610 .I system.posix_acl_access
611 and
612 .IR system.posix_acl_default ,
613 whenever user IDs or group IDs are stored in
614 .B ACL_USER
615 or
616 .B ACL_GROUP
617 entries.
618 .P
619 The following conditions must be met in order to create an ID-mapped mount:
620 .IP \[bu] 3
621 The caller must have the
622 .B CAP_SYS_ADMIN
623 capability in the user namespace the filesystem was mounted in.
624 .\" commit bd303368b776eead1c29e6cdda82bde7128b82a7
625 .\" Christian Brauner
626 .\" Note, currently no filesystems mountable in non-initial user namespaces
627 .\" support ID-mapped mounts.
628 .IP \[bu]
629 The underlying filesystem must support ID-mapped mounts.
630 Currently, the following filesystems support ID-mapped mounts:
631 .\" fs_flags = FS_ALLOW_IDMAP in kernel sources
632 .RS
633 .IP \[bu] 3
634 .PD 0
635 .BR xfs (5)
636 (since Linux 5.12)
637 .IP \[bu]
638 .BR ext4 (5)
639 (since Linux 5.12)
640 .IP \[bu]
641 .B FAT
642 (since Linux 5.12)
643 .IP \[bu]
644 .BR btrfs (5)
645 (since Linux 5.15)
646 .\" commit 5b9b26f5d0b88b74001dcfe4ab8a8f2f4e744112
647 .IP \[bu]
648 .B ntfs3
649 (since Linux 5.15)
650 .\" commit 82cae269cfa953032fbb8980a7d554d60fb00b17
651 .IP \[bu]
652 .B f2fs
653 (since Linux 5.18)
654 .\" commit 984fc4e76d63345499f01c0c198a4b44860cf027
655 .IP \[bu]
656 .B erofs
657 (since Linux 5.19)
658 .\" commit 6c459b78d4793afbba6d864c466cc5cd2932459d
659 .IP \[bu]
660 .B overlayfs
661 (ID-mapped lower and upper layers supported since Linux 5.19)
662 .IP \[bu]
663 .B squashfs
664 (since Linux 6.2)
665 .IP \[bu]
666 .B tmpfs
667 (since Linux 6.3)
668 .IP \[bu]
669 .B cephfs
670 (since Linux 6.7)
671 .IP \[bu]
672 .B hugetlbfs
673 (since Linux 6.9)
674 .PD
675 .RE
676 .IP \[bu]
677 The mount must not already be ID-mapped.
678 This also implies that the ID mapping of a mount cannot be altered.
679 .IP \[bu]
680 The mount must not have any writers.
681 .\" commit 1bbcd277a53e08d619ffeec56c5c9287f2bf42f
682 .IP \[bu]
683 The mount must be a detached mount;
684 that is,
685 it must have been created by calling
686 .BR open_tree (2)
687 with the
688 .B OPEN_TREE_CLONE
689 flag and it must not already have been visible in a mount namespace.
690 (To put things another way:
691 the mount must not have been attached to the filesystem hierarchy
692 with a system call such as
693 .BR move_mount (2).)
694 .P
695 ID mappings can be created for user IDs, group IDs, and project IDs.
696 An ID mapping is essentially a mapping of a range of user or group IDs into
697 another or the same range of user or group IDs.
698 ID mappings are written to map files as three numbers
699 separated by white space.
700 The first two numbers specify the starting user or group ID
701 in each of the two user namespaces.
702 The third number specifies the range of the ID mapping.
703 For example,
704 a mapping for user IDs such as "1000\ 1001\ 1" would indicate that
705 user ID 1000 in the caller's user namespace is mapped to
706 user ID 1001 in its ancestor user namespace.
707 Since the map range is 1,
708 only user ID 1000 is mapped.
709 .P
710 It is possible to specify up to 340 ID mappings for each ID mapping type.
711 If any user IDs or group IDs are not mapped,
712 all files owned by that unmapped user or group ID will appear as
713 being owned by the overflow user ID or overflow group ID respectively.
714 .P
715 Further details on setting up ID mappings can be found in
716 .BR user_namespaces (7).
717 .P
718 In the common case, the user namespace passed in
719 .I userns_fd
720 (together with
721 .B MOUNT_ATTR_IDMAP
722 in
723 .IR attr_set )
724 to create an ID-mapped mount will be the user namespace of a container.
725 In other scenarios it will be a dedicated user namespace associated with
726 a user's login session as is the case for portable home directories in
727 .BR systemd-homed.service (8)).
728 It is also perfectly fine to create a dedicated user namespace
729 for the sake of ID mapping a mount.
730 .P
731 ID-mapped mounts can be useful in the following
732 and a variety of other scenarios:
733 .IP \[bu] 3
734 Sharing files or filesystems
735 between multiple users or multiple machines,
736 especially in complex scenarios.
737 For example,
738 ID-mapped mounts are used to implement portable home directories in
739 .BR systemd-homed.service (8),
740 where they allow users to move their home directory
741 to an external storage device
742 and use it on multiple computers
743 where they are assigned different user IDs and group IDs.
744 This effectively makes it possible to
745 assign random user IDs and group IDs at login time.
746 .IP \[bu]
747 Sharing files or filesystems
748 from the host with unprivileged containers.
749 This allows a user to avoid having to change ownership permanently through
750 .BR chown (2).
751 .IP \[bu]
752 ID mapping a container's root filesystem.
753 Users don't need to change ownership permanently through
754 .BR chown (2).
755 Especially for large root filesystems, using
756 .BR chown (2)
757 can be prohibitively expensive.
758 .IP \[bu]
759 Sharing files or filesystems
760 between containers with non-overlapping ID mappings.
761 .IP \[bu]
762 Implementing discretionary access (DAC) permission checking
763 for filesystems lacking a concept of ownership.
764 .IP \[bu]
765 Efficiently changing ownership on a per-mount basis.
766 In contrast to
767 .BR chown (2),
768 changing ownership of large sets of files is instantaneous with
769 ID-mapped mounts.
770 This is especially useful when ownership of
771 an entire root filesystem of a virtual machine or container
772 is to be changed as mentioned above.
773 With ID-mapped mounts,
774 a single
775 .BR mount_setattr ()
776 system call will be sufficient to change the ownership of all files.
777 .IP \[bu]
778 Taking the current ownership into account.
779 ID mappings specify precisely
780 what a user or group ID is supposed to be mapped to.
781 This contrasts with the
782 .BR chown (2)
783 system call which cannot by itself
784 take the current ownership of the files it changes into account.
785 It simply changes the ownership to the specified user ID and group ID.
786 .IP \[bu]
787 Locally and temporarily restricted ownership changes.
788 ID-mapped mounts make it possible to change ownership locally,
789 restricting the ownership changes to specific mounts,
790 and temporarily as the ownership changes only apply as long as the mount exists.
791 By contrast,
792 changing ownership via the
793 .BR chown (2)
794 system call changes the ownership globally and permanently.
795 .\"
796 .SS Mount attributes and filesystem parameters
797 Some mount attributes
798 (traditionally associated with
799 .BR mount (8)-style
800 options)
801 have a sibling filesystem parameter
802 with superficially similar user-facing behavior.
803 For example, the
804 .I \-o\~ro
805 option to
806 .BR mount (8)
807 can refer to the
808 "read-only" filesystem parameter,
809 or the "read-only" mount attribute.
810 Both of these result in mount objects becoming read-only,
811 but they do have different behavior.
812 .P
813 The distinction between these two kinds of option is that
814 mount object attributes are applied per-mount-object
815 (allowing different mount objects
816 derived from a given filesystem instance
817 to have different attributes),
818 while filesystem instance parameters
819 ("superblock flags" in kernel-developer parlance)
820 apply to all mount objects
821 derived from the same filesystem instance.
822 .P
823 When using
824 .BR mount (2),
825 the line between these two types of mount options was blurred.
826 However, with
827 .BR mount_setattr ()
828 and
829 .BR fsconfig (2),
830 the distinction is made much clearer.
831 Mount attributes are configured with
832 .BR mount_setattr (),
833 while filesystem parameters are configured using
834 .BR fsconfig (2).
835 .SS Extensibility
836 In order to allow for future extensibility,
837 .BR mount_setattr ()
838 requires the user-space application to specify the size of the
839 .I mount_attr
840 structure that it is passing.
841 By providing this information, it is possible for
842 .BR mount_setattr ()
843 to provide both forwards- and backwards-compatibility, with
844 .I size
845 acting as an implicit version number.
846 (Because new extension fields will always
847 be appended, the structure size will always increase.)
848 This extensibility design is very similar to other system calls such as
849 .BR perf_setattr (2),
850 .BR perf_event_open (2),
851 .BR clone3 (2)
852 and
853 .BR openat2 (2).
854 .P
855 Let
856 .I usize
857 be the size of the structure as specified by the user-space application,
858 and let
859 .I ksize
860 be the size of the structure which the kernel supports,
861 then there are three cases to consider:
862 .IP \[bu] 3
863 If
864 .I ksize
865 equals
866 .IR usize ,
867 then there is no version mismatch and
868 .I attr
869 can be used verbatim.
870 .IP \[bu]
871 If
872 .I ksize
873 is larger than
874 .IR usize ,
875 then there are some extension fields that the kernel supports
876 which the user-space application is unaware of.
877 Because a zero value in any added extension field signifies a no-op,
878 the kernel treats all of the extension fields
879 not provided by the user-space application
880 as having zero values.
881 This provides backwards-compatibility.
882 .IP \[bu]
883 If
884 .I ksize
885 is smaller than
886 .IR usize ,
887 then there are some extension fields which the user-space application is aware
888 of but which the kernel does not support.
889 Because any extension field must have its zero values signify a no-op,
890 the kernel can safely ignore the unsupported extension fields
891 if they are all zero.
892 If any unsupported extension fields are non-zero,
893 then \-1 is returned and
894 .I errno
895 is set to
896 .BR E2BIG .
897 This provides forwards-compatibility.
898 .P
899 Because the definition of
900 .I struct mount_attr
901 may change in the future
902 (with new fields being added when system headers are updated),
903 user-space applications should zero-fill
904 .I struct mount_attr
905 to ensure that recompiling the program with new headers will not result in
906 spurious errors at run time.
907 The simplest way is to use a designated initializer:
908 .P
909 .in +4n
910 .EX
911 struct mount_attr attr = {
912 .attr_set = MOUNT_ATTR_RDONLY,
913 .attr_clr = MOUNT_ATTR_NODEV
914 };
915 .EE
916 .in
917 .P
918 Alternatively, the structure can be zero-filled using
919 .BR memset (3)
920 or similar functions:
921 .P
922 .in +4n
923 .EX
924 struct mount_attr attr;
925 memset(&attr, 0, sizeof(attr));
926 attr.attr_set = MOUNT_ATTR_RDONLY;
927 attr.attr_clr = MOUNT_ATTR_NODEV;
928 .EE
929 .in
930 .P
931 A user-space application that wishes to determine which extensions the running
932 kernel supports can do so by conducting a binary search on
933 .I size
934 with a structure which has every byte nonzero
935 (to find the largest value which doesn't produce an error of
936 .BR E2BIG ).
937 .SH EXAMPLES
938 .\" SRC BEGIN (mount_setattr.c)
939 .EX
940 /*
941 * This program allows the caller to create a new detached mount
942 * and set various properties on it.
943 */
944 #define _GNU_SOURCE
945 #include <err.h>
946 #include <fcntl.h>
947 #include <getopt.h>
948 #include <sys/mount.h>
949 #include <sys/types.h>
950 #include <stdbool.h>
951 #include <stdio.h>
952 #include <stdlib.h>
953 #include <string.h>
954 #include <unistd.h>
955 \&
956 static const struct option longopts[] = {
957 {"map\-mount", required_argument, NULL, \[aq]a\[aq]},
958 {"recursive", no_argument, NULL, \[aq]b\[aq]},
959 {"read\-only", no_argument, NULL, \[aq]c\[aq]},
960 {"block\-setid", no_argument, NULL, \[aq]d\[aq]},
961 {"block\-devices", no_argument, NULL, \[aq]e\[aq]},
962 {"block\-exec", no_argument, NULL, \[aq]f\[aq]},
963 {"no\-access\-time", no_argument, NULL, \[aq]g\[aq]},
964 { NULL, 0, NULL, 0 },
965 };
966 \&
967 int
968 main(int argc, char *argv[])
969 {
970 int fd_userns = \-1;
971 int fd_tree;
972 int index = 0;
973 int ret;
974 bool recursive = false;
975 const char *source;
976 const char *target;
977 struct mount_attr *attr = &(struct mount_attr){};
978 \&
979 while ((ret = getopt_long_only(argc, argv, "",
980 longopts, &index)) != \-1) {
981 switch (ret) {
982 case \[aq]a\[aq]:
983 fd_userns = open(optarg, O_RDONLY | O_CLOEXEC);
984 if (fd_userns == \-1)
985 err(EXIT_FAILURE, "open(%s)", optarg);
986 break;
987 case \[aq]b\[aq]:
988 recursive = true;
989 break;
990 case \[aq]c\[aq]:
991 attr\->attr_set |= MOUNT_ATTR_RDONLY;
992 break;
993 case \[aq]d\[aq]:
994 attr\->attr_set |= MOUNT_ATTR_NOSUID;
995 break;
996 case \[aq]e\[aq]:
997 attr\->attr_set |= MOUNT_ATTR_NODEV;
998 break;
999 case \[aq]f\[aq]:
1000 attr\->attr_set |= MOUNT_ATTR_NOEXEC;
1001 break;
1002 case \[aq]g\[aq]:
1003 attr\->attr_set |= MOUNT_ATTR_NOATIME;
1004 attr\->attr_clr |= MOUNT_ATTR__ATIME;
1005 break;
1006 default:
1007 errx(EXIT_FAILURE, "Invalid argument specified");
1008 }
1009 }
1010 \&
1011 if ((argc \- optind) < 2)
1012 errx(EXIT_FAILURE, "Missing source or target mount point");
1013 \&
1014 source = argv[optind];
1015 target = argv[optind + 1];
1016 \&
1017 /* In the following, \-1 as the \[aq]dirfd\[aq] argument ensures that
1018 open_tree() fails if \[aq]source\[aq] is not an absolute pathname. */
1019 .\" Christian Brauner
1020 .\" When writing programs I like to never use relative paths with AT_FDCWD
1021 .\" because. Because making assumptions about the current working directory
1022 .\" of the calling process is just too easy to get wrong; especially when
1023 .\" pivot_root() or chroot() are in play.
1024 .\" My absolut preference (joke intended) is to open a well-known starting
1025 .\" point with an absolute path to get a dirfd and then scope all future
1026 .\" operations beneath that dirfd. This already works with old-style
1027 .\" openat() and _very_ cautious programming but openat2() and its
1028 .\" resolve-flag space have made this **chef's kiss**.
1029 .\" If I can't operate based on a well-known dirfd I use absolute paths
1030 .\" with a -EBADF dirfd passed to *at() functions.
1031 \&
1032 fd_tree = open_tree(\-1, source,
1033 OPEN_TREE_CLONE | OPEN_TREE_CLOEXEC |
1034 AT_EMPTY_PATH | (recursive ? AT_RECURSIVE : 0));
1035 if (fd_tree == \-1)
1036 err(EXIT_FAILURE, "open(%s)", source);
1037 \&
1038 if (fd_userns >= 0) {
1039 attr\->attr_set |= MOUNT_ATTR_IDMAP;
1040 attr\->userns_fd = fd_userns;
1041 }
1042 \&
1043 ret = mount_setattr(fd_tree, "",
1044 AT_EMPTY_PATH | (recursive ? AT_RECURSIVE : 0),
1045 attr, sizeof(struct mount_attr));
1046 if (ret == \-1)
1047 err(EXIT_FAILURE, "mount_setattr");
1048 \&
1049 close(fd_userns);
1050 \&
1051 /* In the following, \-1 as the \[aq]to_dirfd\[aq] argument ensures that
1052 open_tree() fails if \[aq]target\[aq] is not an absolute pathname. */
1053 \&
1054 ret = move_mount(fd_tree, "", \-1, target,
1055 MOVE_MOUNT_F_EMPTY_PATH);
1056 if (ret == \-1)
1057 err(EXIT_FAILURE, "move_mount() to %s", target);
1058 \&
1059 close(fd_tree);
1060 \&
1061 exit(EXIT_SUCCESS);
1062 }
1063 .EE
1064 .\" SRC END
1065 .SH SEE ALSO
1066 .BR newgidmap (1),
1067 .BR newuidmap (1),
1068 .BR clone (2),
1069 .BR mount (2),
1070 .BR unshare (2),
1071 .BR proc (5),
1072 .BR capabilities (7),
1073 .BR mount_namespaces (7),
1074 .BR user_namespaces (7),
1075 .BR xattr (7)