man/man2/statmount.2 - pub/scm/docs/man-pages/man-pages - Git at Google

 '\" t
 .\" Copyright (c) 2024 Josef Bacik <josef@toxicpanda.com>
 .\"
 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
 .\"
 .TH statmount 2 (date) "Linux man-pages (unreleased)"
 .SH NAME
 statmount \- get a mount status
 .SH LIBRARY
 Standard C library
 .RI ( libc ,\~ \-lc )
 .SH SYNOPSIS
 .nf
 .BR "#include <linux/mount.h>" "  /* Definition of STATMOUNT_* constants */"
 .B #include <unistd.h>
 .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 <linux/mount.h>
 .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)
	'\" t
	.\" Copyright (c) 2024 Josef Bacik <josef@toxicpanda.com>
	.\"
	.\" SPDX-License-Identifier: Linux-man-pages-copyleft
	.\"
	.TH statmount 2 (date) "Linux man-pages (unreleased)"
	.SH NAME
	statmount \- get a mount status
	.SH LIBRARY
	Standard C library
	.RI ( libc ,\~ \-lc )
	.SH SYNOPSIS
	.nf
	.BR "#include <linux/mount.h>" " /* Definition of STATMOUNT_* constants */"
	.B #include <unistd.h>
	.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 <linux/mount.h>
	.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)