From patchwork Tue Jun 25 18:56:04 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Josef Bacik X-Patchwork-Id: 13711838 Received: from mail-oi1-f182.google.com (mail-oi1-f182.google.com [209.85.167.182]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id F2017178CFD for ; Tue, 25 Jun 2024 18:56:54 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.167.182 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1719341816; cv=none; b=sZ+YkmB8h/YVdFqp4xArd6C3mP3Feo1tRr/0neSOiWj8Q8iTd2aNE1bnN+hmMr2Q11kuwpCfZTGDr6Um5uR6fPf4aYkhDWBoL3nq7oOyvqRnjOhwA7twCxfjfWcPSLcLk0NAvhAGkQBApclWxbciCjv8+UVaip7BaEFd3gz/caw= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1719341816; c=relaxed/simple; bh=cPyFS29MhsjbQsEzTdqOG8AYbV9KPWslEBcXgiruLzM=; h=From:To:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=gFwVLNIZX/BfjRfW1qDu+HGOPWK59v+//PBltSaloLqioF/ymSIUqqFdeRohj7tXXRyxnRxNw3sO36SkkgK0xk/4muPpKUaK25JjCge2qwIuKRqKQiZxv/MDJhhrhfurJs5jUXXIrKRHpi+UQ2JHahnydDfKB4QChT/Q51rnJN8= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=toxicpanda.com; spf=none smtp.mailfrom=toxicpanda.com; dkim=pass (2048-bit key) header.d=toxicpanda-com.20230601.gappssmtp.com header.i=@toxicpanda-com.20230601.gappssmtp.com header.b=gt/+FqjM; arc=none smtp.client-ip=209.85.167.182 Authentication-Results: smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=toxicpanda.com Authentication-Results: smtp.subspace.kernel.org; spf=none smtp.mailfrom=toxicpanda.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=toxicpanda-com.20230601.gappssmtp.com header.i=@toxicpanda-com.20230601.gappssmtp.com header.b="gt/+FqjM" Received: by mail-oi1-f182.google.com with SMTP id 5614622812f47-3d55c0fadd2so451461b6e.3 for ; Tue, 25 Jun 2024 11:56:54 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=toxicpanda-com.20230601.gappssmtp.com; s=20230601; t=1719341814; x=1719946614; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to; bh=rb9wT4QSaiHaz9QBF9Tfy5DasMFtVo8sghmiqbkkuXw=; b=gt/+FqjMNnGPdDM+BgvN5jLcz8pIiCW9A8gBHEnhB2+DoFGmpWKoMnQM084g66cChB neDneM+PkbjX+rT88V0HXofsZvkpR4sfeIrrsULxn0qRBNZDPGPRNGyqWQUFrHtbNmyY lWonDFcwc53cizoZNCHiJ1Jzr5T+S2Zoyw/VKZ4l2CUEfkSXORpBbpOldDls/DFEbFb8 FqEn1yENiLkImML7UMlw4uEq7biw4gsGUYXDv5c9T2ZJYIlP8K2hCCzn7AU3xEQPVOh/ hc99sd8KX9gQjzn9k47IDR0NziQL9CMbYzTx0qg0y8styQi34x6nQrgN0SHnA6kZRjBo qSNg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1719341814; x=1719946614; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=rb9wT4QSaiHaz9QBF9Tfy5DasMFtVo8sghmiqbkkuXw=; b=uVvzSrwzYKICeCqVoDP9l+IjJCi0J+wRrUm7ww3XJVaYtEaVxRp9OgufD/+NHQMMeK g/86Md0ejWPYdxS+pNtmiaq9riTwNbG5cvdZa3/LFFvHpg7YijFkS93MFctQWmuZJDAD rSXpNLqWLYRAWLz4juSIag5pZZLvHmvmAQ1HOVfMOiaF3yJc01q0AwXpvDwVOhCB3xwi 9RCYASJoMD50vd4tm8NtJSviEgZjfGjxhXn7v3d+crxNo3KmvEL/6jMUfg/WsIw/bHiX nkiIM2VLKJ/fGwFiQaVyZpZXgQq9nV7pQXSvdao2+/rIBZHu9kMZDFozQ1ZjwagyoOWX UyAQ== X-Forwarded-Encrypted: i=1; AJvYcCXozUMEx1HOOThYJRKHJ2GTZYQckO03zh1ERoy9J7VI+6wwsenwsZW7axbFONY2fYWKAhBE3OL60bO+Ig0q2aub78MBMPZsaPYjlWPOEg== X-Gm-Message-State: AOJu0YwKT0OJiR/TsqsyMa1EH2WPmJ+b3BUIxaGKafkdh1WIE/E5u90m ezcbOWNTzFjXANP7rOdcIaxaDImX2Y9615Tv2Fo4j/igq/GdFKF1MwzEaWB8iBg= X-Google-Smtp-Source: AGHT+IFeNUser9m9SFMDA91HJIPpG+2ywT2PBdGGK4w7tNaXp3Fls7OvSC/z3dQbtgSBWqca92mNQg== X-Received: by 2002:a05:6808:1a21:b0:3d2:3811:bc69 with SMTP id 5614622812f47-3d543b84811mr10825652b6e.48.1719341813980; Tue, 25 Jun 2024 11:56:53 -0700 (PDT) Received: from localhost (syn-076-182-020-124.res.spectrum.com. [76.182.20.124]) by smtp.gmail.com with ESMTPSA id d75a77b69052e-444c2c3d924sm57436991cf.61.2024.06.25.11.56.53 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 25 Jun 2024 11:56:53 -0700 (PDT) From: Josef Bacik To: alx@kernel.org, linux-man@vger.kernel.org, brauner@kernel.org, linux-fsdevel@vger.kernel.org, mszeredi@redhat.com, kernel-team@fb.com Subject: [PATCH 1/3] statx.2: Document STATX_MNT_ID_UNIQUE Date: Tue, 25 Jun 2024 14:56:04 -0400 Message-ID: X-Mailer: git-send-email 2.43.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-fsdevel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Linux 6.8 adds STATX_MNT_ID_UNIQUE support https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=98d2b43081972 Add the text and explanation to the statx man page. Signed-off-by: Josef Bacik --- man/man2/statx.2 | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/man/man2/statx.2 b/man/man2/statx.2 index 0dcf7e20b..3d5ecd651 100644 --- a/man/man2/statx.2 +++ b/man/man2/statx.2 @@ -234,7 +234,7 @@ .SH DESCRIPTION .I mask is an ORed combination of the following constants: .P -.in +4n +.in +1n .TS lB l. STATX_TYPE Want stx_mode & S_IFMT @@ -255,6 +255,7 @@ .SH DESCRIPTION STATX_MNT_ID Want stx_mnt_id (since Linux 5.8) STATX_DIOALIGN Want stx_dio_mem_align and stx_dio_offset_align (since Linux 6.1; support varies by filesystem) +STATX_MNT_ID_UNIQUE Want unique stx_mnt_id (since Linux 6.8) .TE .in .P @@ -410,11 +411,18 @@ .SH DESCRIPTION .TP .I stx_mnt_id .\" commit fa2fcf4f1df1559a0a4ee0f46915b496cc2ebf60 -The mount ID of the mount containing the file. +If using STATX_MNT_ID, this is the mount ID of the mount containing the file. This is the same number reported by .BR name_to_handle_at (2) and corresponds to the number in the first field in one of the records in .IR /proc/self/mountinfo . +.IP +If using STATX_MNT_ID_UNIQUE, this is the unique mount ID of the mount +containing the file. This is the number reported by +.BR listmount (2) +and is the ID used to query the mount with +.BR statmount (2) . +It is guaranteed to not be reused while the system is running. .TP .I stx_dio_mem_align The alignment (in bytes) required for user memory buffers for direct I/O From patchwork Tue Jun 25 18:56:05 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Josef Bacik X-Patchwork-Id: 13711839 Received: from mail-qk1-f173.google.com (mail-qk1-f173.google.com [209.85.222.173]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 0DC7E17BB2E for ; Tue, 25 Jun 2024 18:56:55 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.222.173 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1719341817; cv=none; b=mgdqVMS/GWnMrSvRicfK8iWIpWgIEY3YD9mTdh4DlTGs3RX77Wyewg9jVPB8oYbr8AfaJ15odueZ+CuJ/Sxk23xy2Br/v00z1NJMLlwvD9IGEN790Ab/TxeOfQj/rMjTE8BocNVcHcBPvxSCEKU6gW6fCRNeMeQ1hVb2XqUvvww= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1719341817; c=relaxed/simple; bh=dZPRy9RJldPnzZDsjDXKJfnzD18VM/UJeT5fOs38FqU=; h=From:To:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=WurFwHUXCPWfi0F7oMvoyaVorgCGS2T5DYOQf//k4XBEooA3qHmqob9OmiWKRXHuZvc7+mO9eQty8guzMdCLbwYrMsDPeOoYsxLQNvVq9y94VVfUN8Wy4W9XhG3eQlIEljxhx7VM/6pkxHFz5h8d8XObuZVCzOwoh6HvDOwdsFw= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=toxicpanda.com; spf=none smtp.mailfrom=toxicpanda.com; dkim=pass (2048-bit key) header.d=toxicpanda-com.20230601.gappssmtp.com header.i=@toxicpanda-com.20230601.gappssmtp.com header.b=c0BA4pVc; arc=none smtp.client-ip=209.85.222.173 Authentication-Results: smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=toxicpanda.com Authentication-Results: smtp.subspace.kernel.org; spf=none smtp.mailfrom=toxicpanda.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=toxicpanda-com.20230601.gappssmtp.com header.i=@toxicpanda-com.20230601.gappssmtp.com header.b="c0BA4pVc" Received: by mail-qk1-f173.google.com with SMTP id af79cd13be357-79c076c0d83so54452485a.3 for ; Tue, 25 Jun 2024 11:56:55 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=toxicpanda-com.20230601.gappssmtp.com; s=20230601; t=1719341815; x=1719946615; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to; bh=3NXW6nnv/i+alulXxPSqC7wQA1lycPr4EG0b46GZWV0=; b=c0BA4pVcj42mGsCI3LO+0ubmKpny7Nq+fxtXFlOfMIwwYMSDHmv9vKx/lxp35cpHFZ ibE2APARYWPVssFCmbUnsF6MbAx/GK9H3QiYnYloysmGS4VkzeT22ZgLiaVozhjVychD VN8pnxNUnE8Z4AhHdcqbSQar1SmFSCfx19LMHHvFpwWy3hbVgIDqI0dSZJQ91ro9AZp+ B1Sq6yf/ruUmd2QaAvz/lHUddqAKFTLyRvO+S9EqvTEiiw9kMaBxeZsIa6rkAOdYSzoS SSGuy4NWRwAfcNb7/CBJF/ubk3tdyJ9TQIm7glKA3QN9Y5rUId8xBP0mbGIs6ojMJQ6a /5aw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1719341815; x=1719946615; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=3NXW6nnv/i+alulXxPSqC7wQA1lycPr4EG0b46GZWV0=; b=aTA93aQaSZ+Kh1YqeSnqDbeDd3tU6qM7miAGHtkGv7sXaDJMFJt8+qD/8zvMsYSxAt stRPnn2EVL+BDEvxW35jOltW4WOYHBLTzOzQBvwg2nqqubenVUaMr26Ce55RmIgjBCWa 3vqKYTzny5mqOLJG7+FswjKkUn0BDsV2RURhprSMfGUfRR6Mg9b6ntOfX6HUAMDpMLFF wWhaH0ucUuj7QkPgqZ6iAav2t1IIzOQERQ45FS1n0yjYvLjH2ANjikbk91i5KObmTvsp kJIT/0AFqlGLYfCkmAayfXTSxLwfLlDz9V/rOwbSo6Qx6DHqY+EzQX7NedWAnddtUI8P paEA== X-Forwarded-Encrypted: i=1; AJvYcCVJR2CHjJmf7RTBVNBK07C1sdMvz7eG+2cHwxHQZzoCTvJQ+StTUMNYK3nX2kuDUyJeEUVqODdH1ulo/vUvr2ZQWn7Au5iE1Gj7vI8Pdw== X-Gm-Message-State: AOJu0YzHuCouXrTVhjNZDQHqnerCdUiSxJP3luK6DqukG6EvCFPTpEuw suBjOy9OaXM7ILaOX8LefOLq/gxeBi264LjHlAzmA2vgBdcxmM4eQc7YUJZE4Z8= X-Google-Smtp-Source: AGHT+IEq0wcrtmy1hYscKVH2VpvexGWGBLLtfWiegJbPQ61RXGYZ2viI2Y9gaI1Rg7ZwD4yGLiCndA== X-Received: by 2002:a05:620a:1a18:b0:795:493f:9f3c with SMTP id af79cd13be357-79be6efbb80mr1058050385a.39.1719341814973; Tue, 25 Jun 2024 11:56:54 -0700 (PDT) Received: from localhost (syn-076-182-020-124.res.spectrum.com. [76.182.20.124]) by smtp.gmail.com with ESMTPSA id af79cd13be357-79bce936027sm432916485a.115.2024.06.25.11.56.54 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 25 Jun 2024 11:56:54 -0700 (PDT) From: Josef Bacik To: alx@kernel.org, linux-man@vger.kernel.org, brauner@kernel.org, linux-fsdevel@vger.kernel.org, mszeredi@redhat.com, kernel-team@fb.com Subject: [PATCH 2/3] statmount.2: New page describing the statmount syscall Date: Tue, 25 Jun 2024 14:56:05 -0400 Message-ID: X-Mailer: git-send-email 2.43.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-fsdevel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Add some documentation on the new statmount syscall. Signed-off-by: Josef Bacik --- man/man2/statmount.2 | 274 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 274 insertions(+) create mode 100644 man/man2/statmount.2 diff --git a/man/man2/statmount.2 b/man/man2/statmount.2 new file mode 100644 index 000000000..6d9f505f9 --- /dev/null +++ b/man/man2/statmount.2 @@ -0,0 +1,274 @@ +'\" t +.\" Copyright (c) 2024 Josef Bacik +.\" +.\" 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 " " /* Definition of STATMOUNT_* constants */" +.B #include +.P +.BI "int syscall(SYS_statmount, struct mnt_id_req * " req , +.BI " struct statmount * " statmountbuf ", size_t " bufsize , +.BI " unsigned long " flags " ); +.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 }; +.EE +.fi +.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, you 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 buf . +The returned buffer is a structure of the following type: +.P +.in +4n +.EX +struct statmount { + __u32 size; + __u64 mask; + __u32 sb_dev_major; + __u32 sb_dev_minor; + __u64 sb_magic; + __u32 sb_flags; + __u32 fs_type; + __u64 mnt_id; + __u64 mnt_parent_id; + __u32 mnt_id_old; + __u32 mnt_parent_id_old; + __u64 mnt_attr; + __u64 mnt_propagation; + __u64 mnt_peer_group; + __u64 mnt_master; + __u64 propagate_from; + __u32 mnt_root; + __u32 mnt_point; + char str[]; +}; +.EE +.in +.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 struct +.I mnt_id_req +is being passed in, it should always be set to 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 +lBl. +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 +Note that, 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 statmountbuf . +Included in this is +.I size +which indicates the size of the +.I statmountbuf +that was filled in, including any strings. +.I mask +which indicates what information in the structure has been filled in. +.P +It should be noted that the kernel may return fileds 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 . +.P +Apart from +.I mask +(which is described above), the fields in the +.I statmount +structure are: +.TP +.I size +The size of the returned +.I statmountbuf +structure. +.TP +.IR sb_dev_major " and " sb_dev_minor +The device that is mounted at this mount point. +.TP +.I sb_magic +The file system specific super block magic. +.TP +.I 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 fs_type +The offset to the location in the +.I statmount.str +buffer that contains the string representation of the mounted file system. It is +a NULL terminated string. +.TP +.I mnt_id +The unique mount ID of the mount. +.TP +.I mnt_parent_id +The unique mount ID of the parent mount point of this mount. If this is the +root mount point then +.B mnt_id +== +.BR parent_mount_id . +.TP +.I mnt_id_old +This corresponds to the mount ID that is exported by /proc/$PID/mountinfo. +.TP +.I mnt_parent_id_old +This corresponds to the parent mount ID that is exported by +/proc/$PID/mountinfo. +.TP +.I mnt_attr +The +.B MOUNT_ATTR_ +flags set on this mount point. +.TP +.I 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 mnt_peer_group +The ID of the shared peer group. +.TP +.I mnt_master +The mount point receives its propagation from this mount ID. +.TP +.I propagate_from +The ID from the namespace we propagated from. +.TP +.I mnt_root +The offset to the location in the +.I statmount.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 mnt_point +The offset to the location in the +.I statmount.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 statmountbuf +is NULL or 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. +.B E2BIG +.I req +is too large, the limit is the architectures page size. +.TP +.B EOVERFLOW +The size of +.I statmountbuf +is too small to contain either the +.IR statmountbuf.fs_type , +.IR statmountbuf.mnt_root , +or +.IR statmountbuf.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) From patchwork Tue Jun 25 18:56:06 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Josef Bacik X-Patchwork-Id: 13711840 Received: from mail-qv1-f52.google.com (mail-qv1-f52.google.com [209.85.219.52]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 09D5517C7B4 for ; Tue, 25 Jun 2024 18:56:56 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.219.52 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1719341818; cv=none; b=iiurgntu5RF3LOyI7sWw/DJiyREA6W9JvfVsHZ3tVvJ00DrrKX+6Ig74RDxnb44JbhdV2HKIKWm/9EU6vKyVdpmjCT4ETksP2j9JcuwTYGn9kEbvC6c5WeBZtCNtMtnq5yvAMZJcHqaoTu9slP2cSlIFn0Wrcf37Rx7MM/iRPzU= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1719341818; c=relaxed/simple; bh=dCY3e0OUWikA6esJuT04kMUFqhFWCUUw+uC84EoZem8=; h=From:To:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=bpHsfMqmAutr91Wx0yPXUZV2N/u+Af3J4+zyklmd2vCup9TouNCMJcCpZ697yNbKtl3XcdzvhiskyW2yuui/Sx/ujjP2QYfHNHs9ykjYzkkhedIS687XhLUCjPCMPhHbwUs/6gWFmVu98UjE0zdwWG+PrqquEXsiFrjYJ/qSyPg= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=toxicpanda.com; spf=none smtp.mailfrom=toxicpanda.com; dkim=pass (2048-bit key) header.d=toxicpanda-com.20230601.gappssmtp.com header.i=@toxicpanda-com.20230601.gappssmtp.com header.b=LMOybjYX; arc=none smtp.client-ip=209.85.219.52 Authentication-Results: smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=toxicpanda.com Authentication-Results: smtp.subspace.kernel.org; spf=none smtp.mailfrom=toxicpanda.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=toxicpanda-com.20230601.gappssmtp.com header.i=@toxicpanda-com.20230601.gappssmtp.com header.b="LMOybjYX" Received: by mail-qv1-f52.google.com with SMTP id 6a1803df08f44-6b4fced5999so26780036d6.2 for ; Tue, 25 Jun 2024 11:56:56 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=toxicpanda-com.20230601.gappssmtp.com; s=20230601; t=1719341816; x=1719946616; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to; bh=v1jr6BdqGpDo32AhsO8LnS3krEzwCc+6umTuLztF2Uw=; b=LMOybjYXcEiMPFP72vT4t2Y6gVypK+dmq97e0qOjQ2K3/EzhFcfsx9BldD3e1m8MRR guysJCBTduzhUH0SDkhp8mHYHRwr4OjwRCDVfCECmfvkAmxgOcXubp9sNg1QkF8PUpLu vbWfRX5rA22hj36QjqqlIoXsLcrpdT2mQjSfmoVf6mviz8vZipgsYrFm1TaFWZvz+qYK qYqLWBNTjt0RMXWs1fxXL1UdFcDdDh4zp7TIXOU1m2VjJmpXmWpsYcjQxP8Ct69mvhb6 iTBRdKBDZqxw0D9X2yx/Xdu9XWTHenQWZUSnTcQG4fhj/oSB9BeT3ugdTakPiGibSFeF 8GnQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1719341816; x=1719946616; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=v1jr6BdqGpDo32AhsO8LnS3krEzwCc+6umTuLztF2Uw=; b=fJ4kI91ST4icKnD4fOftA57iJpF2wqULGspYftlZe7sC+vcRTcPlwiNLYNPIyxbnMJ BRZSzUez3OYZfJagY+9ahf85iPLpaGLia4kIT98J/I8R3uAXuErb64n7uvFxiV2XKPcC UOyKhF68O5QddckCrLJHZmRM/5521Gr8If6ALZfhb2BtVegv1NtExPk0P9VnCgjJoQFc gvALeP+iBM4W0jErI1n2jEz2I5ZegxJ5wa52/RqQ+dDUiu87wbZm0gUFCc3naziEenOE kMJQQ5iDpVqPuz32N/NpvVOZQot7LKbcA719QIzl4BlgbS3OzKbUdQ1Qf7Ud1WihLp3l qn+Q== X-Forwarded-Encrypted: i=1; AJvYcCXqOtg2F+pjmVA3OvulBIEyEhqk68mu0UgMwZNiDpUEfYqr/09CLBxvU7K/TF8rKU5KLs7I3k40F6KtMBXrXilQ14ruBKMVbIo/7e/jwA== X-Gm-Message-State: AOJu0Yx4Km2uu/fNbSULUMN70tT0pMoooDxTJw0r5ORLs3gEc9lTe8hR cTPS/8J9V8tEc8brrsPcRyeMp7jNs4MCWWrBHGiBiQPhD8aGPkrDKgRu5AVQqEA= X-Google-Smtp-Source: AGHT+IFhM4sr/45vUWDgEV/xCw14F/DTI4fmWKd+auo6Ag/2o3iXetzGLHBiXi/BDeFAy43qD781TA== X-Received: by 2002:ad4:5c4e:0:b0:6b0:86ab:feaf with SMTP id 6a1803df08f44-6b540aaa87cmr116158676d6.48.1719341816046; Tue, 25 Jun 2024 11:56:56 -0700 (PDT) Received: from localhost (syn-076-182-020-124.res.spectrum.com. [76.182.20.124]) by smtp.gmail.com with ESMTPSA id 6a1803df08f44-6b52b16e9basm38236256d6.6.2024.06.25.11.56.55 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 25 Jun 2024 11:56:55 -0700 (PDT) From: Josef Bacik To: alx@kernel.org, linux-man@vger.kernel.org, brauner@kernel.org, linux-fsdevel@vger.kernel.org, mszeredi@redhat.com, kernel-team@fb.com Subject: [PATCH 3/3] listmount.2: New page describing the listmount syscall Date: Tue, 25 Jun 2024 14:56:06 -0400 Message-ID: X-Mailer: git-send-email 2.43.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-fsdevel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Add some documentation for the new listmount syscall. Signed-off-by: Josef Bacik --- man/man2/listmount.2 | 107 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 107 insertions(+) create mode 100644 man/man2/listmount.2 diff --git a/man/man2/listmount.2 b/man/man2/listmount.2 new file mode 100644 index 000000000..442125a5c --- /dev/null +++ b/man/man2/listmount.2 @@ -0,0 +1,107 @@ +'\" t +.\" Copyright (c) 2024 Josef Bacik +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH listmount 2 (date) "Linux man-pages (unreleased)" +.SH NAME +listmount \- get a list of mount ID's +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of struct mnt_id_req constants */" +.B #include +.P +.BI "int syscall(SYS_listmount, struct mnt_id_req * " req , +.BI " u64 * " mnt_ids ", size_t " nr_mnt_ids , +.BI " unsigned long " flags " ); +.P +.EX +.B struct mnt_id_req { +.BR " __u32 size;" " /* sizeof(struct mnt_id_req) */" +.BR " __u64 mnt_id;" " /* The parent mnt_id being searched */" +.BR " __u64 param;" " /* The next mnt_id we want to find */" +.B }; +.EE +.fi +.P +.IR Note : +glibc provides no wrapper for +.BR listmount (), +necessitating the use of +.BR syscall (2). +.SH DESCRIPTION +To access the mounts in your namespace , you must have CAP_SYS_ADMIN in the user +namespace. +.P +This function returns a list of mount IDs under the +.BR req.mnt_id . +This is meant to be used in conjuction with +.BR statmount (2) +in order to provide a way to iterate and discover mounted file systems. +.SS The mnt_id_req structure +.I req.size +is used by the kernel to determine which struct +.I mnt_id_req +is being passed in, it should always be set to sizeof(struct mnt_id req). +.P +.I req.mnt_id +is the parent mnt_id that we will list from, which can either be +.B LSMT_ROOT +which means the root mount of the current mount namespace, or a mount ID +obtained from either +.BR statx (2) +using +.B STATX_MNT_ID_UNIQUE +or from +.BR listmount (2) . +.P +.I req.param +is used to tell the kernel what mount ID to start the list from. This is +useful if multiple calls to +.BR listmount (2) +are required. This can be set to the last mount ID returned + 1 in order to +resume from a previous spot in the list. +.SH RETURN VALUE +On success, the number of entries filled into +.I mnt_ids +is returned, 0 if there are no more mounts left. 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 mnt_ids +is NULL or 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. +.B E2BIG +.I req +is too large, the limit is the architectures page size. +.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 statmount (2), +.BR statx (2)