The mount_setattr() system call changes the mount properties of a
mount or an entire mount tree. If pathname is a relative
pathname, then it is interpreted relative to the directory
referred to by the file descriptor dirfd. If dirfd is the
special value AT_FDCWD, then pathname is interpreted relative to
the current working directory of the calling process. If
pathname is the empty string and AT_EMPTY_PATH is specified in
flags, then the mount properties of the mount identified by dirfd
are changed. (See openat(2) for an explanation of why the dirfd
argument is useful.)
The mount_setattr() system call uses an extensible structure
(struct mount_attr) to allow for future extensions. Any non-flag
extensions to mount_setattr() will be implemented as new fields
appended to the this structure, with a zero value in a new field
resulting in the kernel behaving as though that extension field
was not present. Therefore, the caller must zero-fill this
structure on initialization. See the "Extensibility" subsection
under NOTES for more details.
The size argument should usually be specified as sizeof(struct
mount_attr). However, if the caller is using a kernel that
supports an extended struct mount_attr, but the caller does not
intend to make use of these features, it is possible to pass the
size of an earlier version of the structure together with the
extended structure. This allows the kernel to not copy later
parts of the structure that aren't used anyway. With each
extension that changes the size of struct mount_attr, the kernel
will expose a definition of the form MOUNT_ATTR_SIZE_VERnumber.
For example, the macro for the size of the initial version of
struct mount_attr is MOUNT_ATTR_SIZE_VER0.
The flags argument can be used to alter the pathname resolution
behavior. The supported values are:
AT_EMPTY_PATH
If pathname is the empty string, change the mount
properties on dirfd itself.
AT_RECURSIVE
Change the mount properties of the entire mount tree.
AT_SYMLINK_NOFOLLOW
Don't follow trailing symbolic links.
AT_NO_AUTOMOUNT
Don't trigger automounts.
The attr argument of mount_setattr() is a structure of the
following form:
struct mount_attr {
__u64 attr_set; /* Mount properties to set */
__u64 attr_clr; /* Mount properties to clear */
__u64 propagation; /* Mount propagation type */
__u64 userns_fd; /* User namespace file descriptor */
};
The attr_set and attr_clr members are used to specify the mount
properties that are supposed to be set or cleared for a mount or
mount tree. Flags set in attr_set enable a property on a mount
or mount tree, and flags set in attr_clr remove a property from a
mount or mount tree.
When changing mount properties, the kernel will first clear the
flags specified in the attr_clr field, and then set the flags
specified in the attr_set field. For example, these settings:
struct mount_attr attr = {
.attr_clr = MOUNT_ATTR_NOEXEC | MOUNT_ATTR_NODEV,
.attr_set = MOUNT_ATTR_RDONLY | MOUNT_ATTR_NOSUID,
};
are equivalent to the following steps:
unsigned int current_mnt_flags = mnt->mnt_flags;
/*
* Clear all flags set in .attr_clr,
* clearing MOUNT_ATTR_NOEXEC and MOUNT_ATTR_NODEV.
*/
current_mnt_flags &= ~attr->attr_clr;
/*
* Now set all flags set in .attr_set,
* applying MOUNT_ATTR_RDONLY and MOUNT_ATTR_NOSUID.
*/
current_mnt_flags |= attr->attr_set;
mnt->mnt_flags = current_mnt_flags;
As a result of this change, the mount or mount tree (a) is read-
only; (b) blocks the execution of set-user-ID and set-group-ID
programs; (c) allows execution of programs; and (d) allows access
to devices.
Multiple changes with the same set of flags requested in attr_clr
and attr_set are guaranteed to be idempotent after the changes
have been applied.
The following mount attributes can be specified in the attr_set
or attr_clr fields:
MOUNT_ATTR_RDONLY
If set in attr_set, makes the mount read-only. If set in
attr_clr, removes the read-only setting if set on the
mount.
MOUNT_ATTR_NOSUID
If set in attr_set, causes the mount not to honor the set-
user-ID and set-group-ID mode bits and file capabilities
when executing programs. If set in attr_clr, clears the
set-user-ID, set-group-ID, and file capability restriction
if set on this mount.
MOUNT_ATTR_NODEV
If set in attr_set, prevents access to devices on this
mount. If set in attr_clr, removes the restriction that
prevented accessing devices on this mount.
MOUNT_ATTR_NOEXEC
If set in attr_set, prevents executing programs on this
mount. If set in attr_clr, removes the restriction that
prevented executing programs on this mount.
MOUNT_ATTR_NOSYMFOLLOW
If set in attr_set, prevents following symbolic links on
this mount. If set in attr_clr, removes the restriction
that prevented following symbolic links on this mount.
MOUNT_ATTR_NODIRATIME
If set in attr_set, prevents updating access time for
directories on this mount. If set in attr_clr, removes
the restriction that prevented updating access time for
directories. Note that MOUNT_ATTR_NODIRATIME can be
combined with other access-time settings and is implied by
the noatime setting. All other access-time settings are
mutually exclusive.
MOUNT_ATTR__ATIME - changing access-time settings
The access-time values listed below are an enumeration
that includes the value zero, expressed in the bits
defined by the mask MOUNT_ATTR__ATIME. Even though these
bits are an enumeration (in contrast to the other mount
flags such as MOUNT_ATTR_NOEXEC), they are nonetheless
passed in attr_set and attr_clr for consistency with
fsmount(2), which introduced this behavior.
Note that, since the access-time values are an enumeration
rather than bit values, a caller wanting to transition to
a different access-time setting cannot simply specify the
access-time setting in attr_set, but must also include
MOUNT_ATTR__ATIME in the attr_clr field. The kernel will
verify that MOUNT_ATTR__ATIME isn't partially set in
attr_clr (i.e., either all bits in the MOUNT_ATTR__ATIME
bit field are either set or clear), and that attr_set
doesn't have any access-time bits set if MOUNT_ATTR__ATIME
isn't set in attr_clr.
MOUNT_ATTR_RELATIME
When a file is accessed via this mount, update the
file's last access time (atime) only if the current
value of atime is less than or equal to the file's
last modification time (mtime) or last status
change time (ctime).
To enable this access-time setting on a mount or
mount tree, MOUNT_ATTR_RELATIME must be set in
attr_set and MOUNT_ATTR__ATIME must be set in the
attr_clr field.
MOUNT_ATTR_NOATIME
Do not update access times for (all types of) files
on this mount.
To enable this access-time setting on a mount or
mount tree, MOUNT_ATTR_NOATIME must be set in
attr_set and MOUNT_ATTR__ATIME must be set in the
attr_clr field.
MOUNT_ATTR_STRICTATIME
Always update the last access time (atime) when
files are accessed on this mount.
To enable this access-time setting on a mount or
mount tree, MOUNT_ATTR_STRICTATIME must be set in
attr_set and MOUNT_ATTR__ATIME must be set in the
attr_clr field.
MOUNT_ATTR_IDMAP
If set in attr_set, creates an ID-mapped mount. The ID
mapping is taken from the user namespace specified in
userns_fd and attached to the mount.
Since it is not supported to change the ID mapping of a
mount after it has been ID mapped, it is invalid to
specify MOUNT_ATTR_IDMAP in attr_clr.
For further details, see the subsection "ID-mapped mounts"
under NOTES.
The propagation field is used to specify the propagation type of
the mount or mount tree. This field either has the value zero,
meaning leave the propagation type unchanged, or it has one of
the following values:
MS_PRIVATE
Turn all mounts into private mounts.
MS_SHARED
Turn all mounts into shared mounts.
MS_SLAVE
Turn all mounts into dependent mounts.
MS_UNBINDABLE
Turn all mounts into unbindable mounts.
For further details on the above propagation types, see
mount_namespaces(7).
