'\" t .\" Copyright (c) 2024 Josef Bacik .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .TH statmount 2 2024-07-23 "Linux man-pages 6.10" .SH NAME statmount \- get a mount status .SH LIBRARY Standard C library .RI ( libc ,\~ \-lc ) .SH SYNOPSIS .nf .BR "#include " " /* Definition of STATMOUNT_* constants */" .B #include .P .BI "int syscall(SYS_statmount, struct mnt_id_req *" req , .BI " struct statmount *" smbuf ", size_t " bufsize , .BI " unsigned long " flags ); .P .B #include .fi .P .EX .B struct mnt_id_req { .BR " __u32 size;" " /* sizeof(struct mnt_id_req) */" .BR " __u64 mnt_id;" " /* The mnt_id being queried */" .BR " __u64 param;" " /* An ORed combination of the STATMOUNT_ constants */" .B }; .P .B struct statmount { .B " __u32 size;" .B " __u64 mask;" .B " __u32 sb_dev_major;" .B " __u32 sb_dev_minor;" .B " __u64 sb_magic;" .B " __u32 sb_flags;" .B " __u32 fs_type;" .B " __u64 mnt_id;" .B " __u64 mnt_parent_id;" .B " __u32 mnt_id_old;" .B " __u32 mnt_parent_id_old;" .B " __u64 mnt_attr;" .B " __u64 mnt_propagation;" .B " __u64 mnt_peer_group;" .B " __u64 mnt_master;" .B " __u64 propagate_from;" .B " __u32 mnt_root;" .B " __u32 mnt_point;" .B " char str[];" .B }; .EE .P .IR Note : glibc provides no wrapper for .BR statmount (), necessitating the use of .BR syscall (2). .SH DESCRIPTION To access a mount's status, the caller must have CAP_SYS_ADMIN in the user namespace. .P This function returns information about a mount, storing it in the buffer pointed to by .IR smbuf . The returned buffer is a .I struct statmount which is of size .I bufsize with the fields filled in as described below. .P (Note that reserved space and padding is omitted.) .SS The mnt_id_req structure .I req.size is used by the kernel to determine which .I struct\~mnt_id_req is being passed in; it should always be set to .IR sizeof(struct\~mnt_id_req) . .P .I req.mnt_id can be obtained from either .BR statx (2) using .B STATX_MNT_ID_UNIQUE or from .BR listmount (2) and is used as the identifier to query the status of the desired mount point. .P .I req.param is used to tell the kernel which fields the caller is interested in. It is an ORed combination of the following constants .P .in +4n .TS lB l. STATMOUNT_SB_BASIC /* Want/got sb_* */ STATMOUNT_MNT_BASIC /* Want/got mnt_* */ STATMOUNT_PROPAGATE_FROM /* Want/got propagate_from */ STATMOUNT_MNT_ROOT /* Want/got mnt_root */ STATMOUNT_MNT_POINT /* Want/got mnt_point */ STATMOUNT_FS_TYPE /* Want/got fs_type */ .TE .in .P In general, the kernel does .I not reject values in .I req.param other than the above. (For an exception, see .B EINVAL in errors.) Instead, it simply informs the caller which values are supported by this kernel and filesystem via the .I statmount.mask field. Therefore, .I do not simply set .I req.param to .B UINT_MAX (all bits set), as one or more bits may, in the future, be used to specify an extension to the buffer. .SS The returned information The status information for the target mount is returned in the .I statmount structure pointed to by .IR smbuf . .P The fields in the .I statmount structure are: .TP .I smbuf.size The size of the returned .I smbuf structure, including any of the strings fields that were filled. .TP .I smbuf.mask The ORed combination of .BI STATMOUNT_ * flags indicating which fields were filled in and thus valid. The kernel may return fields that weren't requested, and may fail to return fields that were requested, depending on what the backing file system and kernel supports. In either case, .I req.param will not be equal to .IR mask . .TP .I smbuf.sb_dev_major .TQ .I smbuf.sb_dev_minor The device that is mounted at this mount point. .TP .I smbuf.sb_magic The file system specific super block magic. .TP .I smbuf.sb_flags The flags that are set on the super block, an ORed combination of .BR SB_RDONLY , .BR SB_SYNCHRONOUS , .BR SB_DIRSYNC , .BR SB_LAZYTIME . .TP .I smbuf.fs_type The offset to the location in the .I smbuf.str buffer that contains the string representation of the mounted file system. It is a null-terminated string. .TP .I smbuf.mnt_id The unique mount ID of the mount. .TP .I smbuf.mnt_parent_id The unique mount ID of the parent mount point of this mount. If this is the root mount point then .IR smbuf.mnt_id\~==\~smbuf.parent_mount_id . .TP .I smbuf.mnt_id_old This corresponds to the mount ID that is exported by .IR /proc/ pid /mountinfo . .TP .I smbuf.mnt_parent_id_old This corresponds to the parent mount ID that is exported by .IR /proc/ pid /mountinfo . .TP .I smbuf.mnt_attr The .BI MOUNT_ATTR_ * flags set on this mount point. .TP .I smbuf.mnt_propagation The mount propagation flags, which can be one of .BR MS_SHARED , .BR MS_SLAVE , .BR MS_PRIVATE , .BR MS_UNBINDABLE . .TP .I smbuf.mnt_peer_group The ID of the shared peer group. .TP .I smbuf.mnt_master The mount point receives its propagation from this mount ID. .TP .I smbuf.propagate_from The ID from the namespace we propagated from. .TP .I smbuf.mnt_root The offset to the location in the .I smbuf.str buffer that contains the string representation of the mount relative to the root of the file system. It is a null-terminated string. .TP .I smbuf.mnt_point The offset to the location in the .I smbuf.str buffer that contains the string representation of the mount relative to the current root (ie if you are in a .BR chroot ). It is a null-terminated string. .SH RETURN VALUE On success, zero is returned. On error, \-1 is returned, and .I errno is set to indicate the error. .SH ERRORS .TP .B EPERM Permission is denied for accessing this mount. .TP .B EFAULT .I req or .I smbuf points to a location outside the process's accessible address space. .TP .B EINVAL Invalid flag specified in .IR flags . .TP .B EINVAL .I req is of insufficient size to be utilized. .TP .B E2BIG .I req is too large. .TP .B EOVERFLOW The size of .I smbuf is too small to contain either the .IR smbuf.fs_type , .IR smbuf.mnt_root , or .IR smbuf.mnt_point . Allocate a larger buffer and retry the call. .TP .B ENOENT The specified .I req.mnt_id doesn't exist. .TP .B ENOMEM Out of memory (i.e., kernel memory). .SH STANDARDS Linux. .SH SEE ALSO .BR listmount (2), .BR statx (2)