From nobody Sun Oct 5 09:06:18 2025 Received: from mout-p-103.mailbox.org (mout-p-103.mailbox.org [80.241.56.161]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 981E02BCF4F; Wed, 6 Aug 2025 17:45:03 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=80.241.56.161 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1754502305; cv=none; b=HwI//g1r5c3N6wwVbFoAprQRBOCpaA7TWn1gSsPLa+wIG4ugHBLHmC+9yyWPUn4tonS+kk79P29eGk18GKtW0vjCxY2nP2g10C5lGUH6/E5VTDtTeAs9OAe2DpsyPd4eA12ylyioJ0L+ZP4wBgaJryGQZYtzHEHwpE+FW5n2Vhw= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1754502305; c=relaxed/simple; bh=13kudgbKXbJx4krYwEelfDLkJuG6/PIQ2nEiAbfcm3w=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=nBqHvW6zZQeMoy9x2iQQNxxkXU4Uvwt1hPbyupkPuYghM4I+PLAlXgFmqOjZTwZcSAPgc+4INld2sw6Lz0HafcwgEEHSDMDe1Rvv+gmNiIXaJOYetJVUG+yIeHYdSN7raw1WwpkuSHaTEi5ockKzQ8NxLqT+AE/paZJcMajoTJA= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=cyphar.com; spf=pass smtp.mailfrom=cyphar.com; dkim=pass (2048-bit key) header.d=cyphar.com header.i=@cyphar.com header.b=hDNFYPJw; arc=none smtp.client-ip=80.241.56.161 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=cyphar.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=cyphar.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=cyphar.com header.i=@cyphar.com header.b="hDNFYPJw" Received: from smtp102.mailbox.org (smtp102.mailbox.org [10.196.197.102]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) by mout-p-103.mailbox.org (Postfix) with ESMTPS id 4bxyNk5dp5z9tGx; Wed, 6 Aug 2025 19:44:54 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=cyphar.com; s=MBO0001; t=1754502294; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=zBmcpHxiLObUdOrrVuAKzBG2uoCjEctpjRwfJ7cGgFw=; b=hDNFYPJwluKDqZKsRVVNaREcdnJb3G9aaNBq2Ulfue3pZ5bIObEndJLg+wu5CQky/5aGj4 1QlAGneSv92u6dHyklEPKbdNVpCFcP/EHDb6uV0jqJtR5dYe2AY58tizkqOWLcjhuIGsbm sBRaLs3E8vV+nrJYCWhgmNBa5Dnaa5EwJUv3ij/85okYWABKNEmeo9EPG49qNCr33dHixb /1fBFHk6WiJIUcw3RF/rIggVdOPDdlqs1IFH3RPyQnO1xXvfoupn2o2JZqMrrq/tmt9HcM 6iafaPtNbhq4V6rIwCfEYyamsCwr+C81brbD+HlTGJ4b1IYOFS083fD+0lIoQA== From: Aleksa Sarai Date: Thu, 07 Aug 2025 03:44:35 +1000 Subject: [PATCH v2 01/11] mount_setattr.2: document glibc >= 2.36 syscall wrappers Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Message-Id: <20250807-new-mount-api-v2-1-558a27b8068c@cyphar.com> References: <20250807-new-mount-api-v2-0-558a27b8068c@cyphar.com> In-Reply-To: <20250807-new-mount-api-v2-0-558a27b8068c@cyphar.com> To: Alejandro Colomar Cc: "Michael T. Kerrisk" , Alexander Viro , Jan Kara , Askar Safin , "G. Branden Robinson" , linux-man@vger.kernel.org, linux-api@vger.kernel.org, linux-fsdevel@vger.kernel.org, linux-kernel@vger.kernel.org, David Howells , Christian Brauner , Aleksa Sarai X-Developer-Signature: v=1; a=openpgp-sha256; l=2998; i=cyphar@cyphar.com; h=from:subject:message-id; bh=13kudgbKXbJx4krYwEelfDLkJuG6/PIQ2nEiAbfcm3w=; b=owGbwMvMwCWmMf3Xpe0vXfIZT6slMWRMntKm9bV7YXR+tJ5u8ENz4fsHtNg406Mmrq1/miak/ 2DCcYHkjlIWBjEuBlkxRZZtfp6hm+YvvpL8aSUbzBxWJpAhDFycAjCRh4EM/7MyztX/q2GZ2JCw bfvvyrLPi6dLHqr+keS5gi+I63s312OG/1X6F6PWOjB+ZmNM3MHLyWzy+v+bqEVvGyyWGteGL01 fzw8A X-Developer-Key: i=cyphar@cyphar.com; a=openpgp; fpr=C9C370B246B09F6DBCFC744C34401015D1D2D386 Glibc 2.36 added syscall wrappers for the entire family of fd-based mount syscalls, including mount_setattr(2). Thus it's no longer necessary to instruct users to do raw syscall(2) operations. Signed-off-by: Aleksa Sarai --- man/man2/mount_setattr.2 | 45 +++++++-------------------------------------- 1 file changed, 7 insertions(+), 38 deletions(-) diff --git a/man/man2/mount_setattr.2 b/man/man2/mount_setattr.2 index 60d9cf9de8aa..c96f0657f046 100644 --- a/man/man2/mount_setattr.2 +++ b/man/man2/mount_setattr.2 @@ -10,21 +10,12 @@ .SH LIBRARY .RI ( libc ,\~ \-lc ) .SH SYNOPSIS .nf -.BR "#include " " /* Definition of " AT_* " constants */" -.BR "#include " " /* Definition of " MOUNT_ATTR_* " constan= ts */" -.BR "#include " " /* Definition of " SYS_* " constants */" -.B #include +.BR "#include " " /* Definition of " AT_* " constants */" +.B #include .P -.BI "int syscall(SYS_mount_setattr, int " dirfd ", const char *" path , -.BI " unsigned int " flags ", struct mount_attr *" attr \ -", size_t " size ); +.BI "int mount_setattr(int " dirfd ", const char *" path ", unsigned int "= flags "," +.BI " struct mount_attr *" attr ", size_t " size );" .fi -.P -.IR Note : -glibc provides no wrapper for -.BR mount_setattr (), -necessitating the use of -.BR syscall (2). .SH DESCRIPTION The .BR mount_setattr () @@ -586,6 +577,7 @@ .SH HISTORY .\" commit 7d6beb71da3cc033649d641e1e608713b8220290 .\" commit 2a1867219c7b27f928e2545782b86daaf9ad50bd .\" commit 9caccd41541a6f7d6279928d9f971f6642c361af +glibc 2.36. .SH NOTES .SS ID-mapped mounts Creating an ID-mapped mount makes it possible to @@ -914,37 +906,14 @@ .SH EXAMPLES #include #include #include -#include -#include +#include +#include #include #include #include #include -#include #include \& -static inline int -mount_setattr(int dirfd, const char *path, unsigned int flags, - struct mount_attr *attr, size_t size) -{ - return syscall(SYS_mount_setattr, dirfd, path, flags, - attr, size); -} -\& -static inline int -open_tree(int dirfd, const char *filename, unsigned int flags) -{ - return syscall(SYS_open_tree, dirfd, filename, flags); -} -\& -static inline int -move_mount(int from_dirfd, const char *from_path, - int to_dirfd, const char *to_path, unsigned int flags) -{ - return syscall(SYS_move_mount, from_dirfd, from_path, - to_dirfd, to_path, flags); -} -\& static const struct option longopts[] =3D { {"map\-mount", required_argument, NULL, \[aq]a\[aq]}, {"recursive", no_argument, NULL, \[aq]b\[aq]}, --=20 2.50.1 From nobody Sun Oct 5 09:06:18 2025 Received: from mout-p-103.mailbox.org (mout-p-103.mailbox.org [80.241.56.161]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 3F73329CB58; Wed, 6 Aug 2025 17:45:04 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=80.241.56.161 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1754502305; cv=none; b=KGnjX9DOCAPcZpM3ixwDe4UJ3H1Wr5fRILBd7fEI2bQXMoi8fUYTUXVcdhjvZJnUtsLDlgrtOysEHqw+UrVD/QXc50oMKhlhIdTVPJTs8/tK0LYPu5+S99m2gT1MvLrm2nvYTYC8MxGDOv/wr2efleiMtWyhUoDxiH1fBTeW0RI= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1754502305; c=relaxed/simple; bh=8DPMg3YdXXlcxIrWJ1hq+5y1fTKw/qmcyDBJf8cL2Fg=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=LHDMAqxNpw+OuuLm6YKOw98XAdu1U6UyAWLmjwHM6YydaFevHSOx8bfNuTLVhyxk0XJ8uqYNntjTxkxJEWzMkBjzpBO7YTy1dKSuDvPFP6I8xjCA4HK9t54kezlNCp3GFB81+RCYqqpaqk75GIpMoX1RW7eFsF0bTI8Fr1Yv9k4= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=cyphar.com; spf=pass smtp.mailfrom=cyphar.com; dkim=pass (2048-bit key) header.d=cyphar.com header.i=@cyphar.com header.b=ShbUj0+j; arc=none smtp.client-ip=80.241.56.161 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=cyphar.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=cyphar.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=cyphar.com header.i=@cyphar.com header.b="ShbUj0+j" Received: from smtp102.mailbox.org (smtp102.mailbox.org [10.196.197.102]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) by mout-p-103.mailbox.org (Postfix) with ESMTPS id 4bxyNr5QmZz9tHN; Wed, 6 Aug 2025 19:45:00 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=cyphar.com; s=MBO0001; t=1754502300; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=VlFKUKsClHvae08VDfYFxp2k8jZdmsu6fCRZQ1cGOHc=; b=ShbUj0+j0vj4MOBNbPQoIw9uYb1+LCmMqURHP19joNM7jC4L9O6cbwL7kwrxhbCC7vvrWj /3CgsVrjo5s8ScgApEEteErIFI60QchTTO6RXfnapuyrRDaT9E7z0tBN4o6aghR7e9kVmv V6XmaaUpOlwcC2V6HtY7CH3uD8fPeeruAtH2ump/kDPmbkvWreWKo1ySzU7VK/sH175Wad AquVmjtNa70ZDTF0s2qq7jHk2q9prITz877QKSjZUP9BpN7IelHjr00ZOy2dMoT8BMGuQ4 0Fv2WsAPd97Sh1uSmo1IkufzCOcpakdrR61ts1Re28O0FfayZodXt3jIv1Mn8A== From: Aleksa Sarai Date: Thu, 07 Aug 2025 03:44:36 +1000 Subject: [PATCH v2 02/11] mount_setattr.2: move mount_attr struct to mount_attr.2type Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Message-Id: <20250807-new-mount-api-v2-2-558a27b8068c@cyphar.com> References: <20250807-new-mount-api-v2-0-558a27b8068c@cyphar.com> In-Reply-To: <20250807-new-mount-api-v2-0-558a27b8068c@cyphar.com> To: Alejandro Colomar Cc: "Michael T. Kerrisk" , Alexander Viro , Jan Kara , Askar Safin , "G. Branden Robinson" , linux-man@vger.kernel.org, linux-api@vger.kernel.org, linux-fsdevel@vger.kernel.org, linux-kernel@vger.kernel.org, David Howells , Christian Brauner , Aleksa Sarai X-Developer-Signature: v=1; a=openpgp-sha256; l=3031; i=cyphar@cyphar.com; h=from:subject:message-id; bh=8DPMg3YdXXlcxIrWJ1hq+5y1fTKw/qmcyDBJf8cL2Fg=; b=owGbwMvMwCWmMf3Xpe0vXfIZT6slMWRMntLWzJyTMk3I40f737q2GwInzlopZCpu/5OdJHtLc lF19sGsjlIWBjEuBlkxRZZtfp6hm+YvvpL8aSUbzBxWJpAhDFycAjARKSFGhsk/PlbKm8/Ntzu/ bO03c8Vly43aLkc5sBi82pPUpV/Upc3wi2lL8n//7zteTNt34ESmbZd5Wbx9XvTP1v7p9zd+ncC zmhMA X-Developer-Key: i=cyphar@cyphar.com; a=openpgp; fpr=C9C370B246B09F6DBCFC744C34401015D1D2D386 As with open_how(2type), it makes sense to move this to a separate man page. In addition, future man pages added in this patchset will want to reference mount_attr(2type). Signed-off-by: Aleksa Sarai --- man/man2/mount_setattr.2 | 17 ++++--------- man/man2type/mount_attr.2type | 58 +++++++++++++++++++++++++++++++++++++++= ++++ 2 files changed, 63 insertions(+), 12 deletions(-) diff --git a/man/man2/mount_setattr.2 b/man/man2/mount_setattr.2 index c96f0657f046..d44fafc93a20 100644 --- a/man/man2/mount_setattr.2 +++ b/man/man2/mount_setattr.2 @@ -114,18 +114,11 @@ .SH DESCRIPTION .I attr argument of .BR mount_setattr () -is a structure of the following form: -.P -.in +4n -.EX -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 */ -}; -.EE -.in +is a pointer to a +.I mount_attr +structure, +described in +.BR mount_attr (2type). .P The .I attr_set diff --git a/man/man2type/mount_attr.2type b/man/man2type/mount_attr.2type new file mode 100644 index 000000000000..b7a3ace6b3b9 --- /dev/null +++ b/man/man2type/mount_attr.2type @@ -0,0 +1,58 @@ + +.\" Copyright, the authors of the Linux man-pages project +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH mount_attr 2type (date) "Linux man-pages (unreleased)" +.SH NAME +mount_attr \- what mount properties to set and clear +.SH LIBRARY +Linux kernel headers +.SH SYNOPSIS +.EX +.B #include +.P +.B struct mount_attr { +.BR " __u64 attr_set;" " /* Mount properties to set */" +.BR " __u64 attr_clr;" " /* Mount properties to clear */" +.BR " __u64 propagation;" " /* Mount propagation type */" +.BR " __u64 userns_fd;" " /* User namespace file descriptor */" + /* ... */ +.B }; +.EE +.SH DESCRIPTION +Specifies which mount properties should be changed with +.BR mount_setattr (2). +.P +The fields are as follows: +.TP +.I .attr_set +This field specifies which +.BI MOUNT_ATTR_ * +attribute flags to set. +.TP +.I .attr_clr +This fields specifies which +.BI MOUNT_ATTR_ * +attribute flags to clear. +.TP +.I .propagation +This field specifies what mount propagation will be applied. +The valid values of this field are the same propagation types described in +.BR mount_namespaces (7). +.TP +.I .userns_fd +This fields specifies a file descriptor that indicates which user namespac= e to +use as a reference for ID-mapped mounts with +.BR MOUNT_ATTR_IDMAP . +.SH VERSIONS +Extra fields may be appended to the structure, +with a zero value in a new field resulting in +the kernel behaving as though that extension field was not present. +Therefore, a user +.I must +zero-fill this structure on initialization. +.SH STANDARDS +Linux. +.SH SEE ALSO +.BR mount_setattr (2) --=20 2.50.1 From nobody Sun Oct 5 09:06:18 2025 Received: from mout-p-101.mailbox.org (mout-p-101.mailbox.org [80.241.56.151]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 818D029CB2A; Wed, 6 Aug 2025 17:45:10 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=80.241.56.151 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1754502313; cv=none; b=C1dYB1pFJoYNOleGpkHQ+hpgNEiTuwb417cq5Sa59fK9APwXd0JBp4CkDUDMIkOxIbCeadEh1flTaaXHO+FYgUs7BBMEFHi/YjWBo5tKqMfQPjD6y33h+kkJJBWWMUnbW+RxiLGSORqOC3nYIwBqMm0jVeaCSZZR0OG0PnXkV0s= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1754502313; c=relaxed/simple; bh=rtEL/1PtST1O6OkS7l6BEWm7Sm3ivZ+QFJIb1vrFfbw=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=Sq+v9BMAJFudovv+NMXK4xCEBsSd00Y0HXOc1Q+INk7I3UEXe82eItXjsJWsPWxGAA5EIM1YlP9f044fLQpgLjmiBE44eAHCGk/3Ey/yVSbeR0ODc1B9hwCOJqG9gj/3atF3JHSKfUhOv94z4Xj5HheWqp8KUqptJpVFi0+yqj8= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=cyphar.com; spf=pass smtp.mailfrom=cyphar.com; dkim=pass (2048-bit key) header.d=cyphar.com header.i=@cyphar.com header.b=p7+zER1D; arc=none smtp.client-ip=80.241.56.151 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=cyphar.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=cyphar.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=cyphar.com header.i=@cyphar.com header.b="p7+zER1D" Received: from smtp102.mailbox.org (smtp102.mailbox.org [IPv6:2001:67c:2050:b231:465::102]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) by mout-p-101.mailbox.org (Postfix) with ESMTPS id 4bxyNz0VMsz9snx; Wed, 6 Aug 2025 19:45:07 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=cyphar.com; s=MBO0001; t=1754502307; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=X30AUyAeqE3TsRYyo+P8Bb9KUQDA0X3R2xjUFUbnNZU=; b=p7+zER1D+PHebwxof4y98fJxvspq3mxEx59gqrsTeC0rJgmEJNctAX6lcgirDnCIY1Q94G 8qyeVZKInzC7Ku5PNO887PbeJyzdGKQmQllwBIx0sMzMMhSDl/LdHPU0AmqeSBEL4XOF8O MEyTN5gUlzKHN+sLYxASUVlDLK1FghCgyiERipUissyC7MheL2fr2nOqxYvZrUh4t/2uGo DUtmLclWhyIybzkLE+FKCuweBLByOWyVt9pViumR2kt/c385T1iX36je+pvWZRmxQTsb8K TglRsgTH8VPYheY+trEB7+pMrjEsGF7NE7rrymdjZAkeyrI/AD03o1UK4QSWvA== Authentication-Results: outgoing_mbo_mout; dkim=none; spf=pass (outgoing_mbo_mout: domain of cyphar@cyphar.com designates 2001:67c:2050:b231:465::102 as permitted sender) smtp.mailfrom=cyphar@cyphar.com From: Aleksa Sarai Date: Thu, 07 Aug 2025 03:44:37 +1000 Subject: [PATCH v2 03/11] fsopen.2: document 'new' mount api Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Message-Id: <20250807-new-mount-api-v2-3-558a27b8068c@cyphar.com> References: <20250807-new-mount-api-v2-0-558a27b8068c@cyphar.com> In-Reply-To: <20250807-new-mount-api-v2-0-558a27b8068c@cyphar.com> To: Alejandro Colomar Cc: "Michael T. Kerrisk" , Alexander Viro , Jan Kara , Askar Safin , "G. Branden Robinson" , linux-man@vger.kernel.org, linux-api@vger.kernel.org, linux-fsdevel@vger.kernel.org, linux-kernel@vger.kernel.org, David Howells , Christian Brauner , Aleksa Sarai X-Developer-Signature: v=1; a=openpgp-sha256; l=10268; i=cyphar@cyphar.com; h=from:subject:message-id; bh=rtEL/1PtST1O6OkS7l6BEWm7Sm3ivZ+QFJIb1vrFfbw=; b=owGbwMvMwCWmMf3Xpe0vXfIZT6slMWRMntI2T5Ix4aHVy6QtomzLbiuFihinPHe7V8jJ1pB36 mxUzduejlIWBjEuBlkxRZZtfp6hm+YvvpL8aSUbzBxWJpAhDFycAjCRwN2MDLN3cf2tNL43ffa0 9ZG85ewKcUWsyxdO52Oc4L7t+SXvC5sYGXr+/OO12PmbIXPZOT8O9vpK64zf117KqTI45n38nCH 8nRUA X-Developer-Key: i=cyphar@cyphar.com; a=openpgp; fpr=C9C370B246B09F6DBCFC744C34401015D1D2D386 X-Rspamd-Queue-Id: 4bxyNz0VMsz9snx This is loosely based on the original documentation written by David Howells and later maintained by Christian Brauner, but has been rewritten to be more from a user perspective (as well as fixing a few critical mistakes). Co-developed-by: David Howells Co-developed-by: Christian Brauner Signed-off-by: Aleksa Sarai --- man/man2/fsopen.2 | 319 ++++++++++++++++++++++++++++++++++++++++++++++++++= ++++ 1 file changed, 319 insertions(+) diff --git a/man/man2/fsopen.2 b/man/man2/fsopen.2 new file mode 100644 index 000000000000..ad38ef0782be --- /dev/null +++ b/man/man2/fsopen.2 @@ -0,0 +1,319 @@ +.\" Copyright, the authors of the Linux man-pages project +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH fsopen 2 (date) "Linux man-pages (unreleased)" +.SH NAME +fsopen \- create a new filesystem context +.SH LIBRARY +Standard C library +.RI ( libc ,\~ \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " +.P +.BI "int fsopen(const char *" fsname ", unsigned int " flags ");" +.fi +.SH DESCRIPTION +The +.BR fsopen () +system call is part of the suite of file descriptor based mount facilities= in +Linux. +.P +.BR fsopen () +creates a blank filesystem configuration context within the kernel +for the filesystem named by +.IR fsname , +puts the context into creation mode and attaches it to a file descriptor, +which is then returned. +The calling process must have the +.B \%CAP_SYS_ADMIN +capability in order to create a new filesystem configuration context. +.P +A filesystem configuration context is an in-kernel representation of a pen= ding +transaction, +containing a set of configuration parameters that are to be applied +when creating a new instance of a filesystem +(or modifying the configuration of an existing filesystem instance, +such as when using +.BR fspick (2)). +.P +After obtaining a filesystem configuration context with +.BR fsopen (), +the general workflow for operating on the context looks like the following: +.IP (1) 5 +Pass the filesystem context file descriptor to +.BR fsconfig (2) +to specify any desired filesystem parameters. +This may be done as many times as necessary. +.IP (2) +Pass the same filesystem context file descriptor to +.BR fsconfig (2) +with +.B \%FSCONFIG_CMD_CREATE +to create an instance of the configured filesystem. +.IP (3) +Pass the same filesystem context file descriptor to +.BR fsmount (2) +to create a new mount object for the root of the filesystem, +which is then attached to a new file descriptor. +This also places the filesystem context file descriptor into reconfigurati= on +mode, +similar to the mode produced by +.BR fspick (2). +.IP (4) +Use the mount object file descriptor as a +.I dirfd +argument to "*at()" system calls; +or attach the mount object to a mount point +by passing the mount object file descriptor to +.BR move_mount (2). +.P +A filesystem context will move between different modes throughout its +lifecycle +(such as the creation phase when created with +.BR fsopen (), +the reconfiguration phase when an existing filesystem instance is selected= by +.BR fspick (2), +and the intermediate "needs-mount" phase between +.\" FS_CONTEXT_NEEDS_MOUNT is the term the kernel uses for this. +.BR \%FSCONFIG_CMD_CREATE +and +.BR fsmount (2)), +which has an impact on what operations are permitted on the filesystem con= text. +.P +The file descriptor returned by +.BR fsopen () +also acts as a channel for filesystem drivers to provide more comprehensive +error, warning, and information messages +than are normally provided through the standard +.BR errno (3) +interface for system calls. +If an error occurs at any time during the workflow mentioned above, +calling +.BR read (2) +on the filesystem context file descriptor will retrieve any ancillary +information about the encountered errors. +(See the "Message retrieval interface" section for more details on the mes= sage +format.) +.P +.I flags +can be used to control aspects of the creation of the filesystem configura= tion +context file descriptor. +A value for +.I flags +is constructed by bitwise ORing +zero or more of the following constants: +.RS +.TP +.B FSOPEN_CLOEXEC +Set the close-on-exec +.RB ( FD_CLOEXEC ) +flag on the new file descriptor. +See the description of the +.B O_CLOEXEC +flag in +.BR open (2) +for reasons why this may be useful. +.RE +.P +A list of filesystems supported by the running kernel +(and thus a list of valid values for +.IR fsname ) +can be obtained from +.IR /proc/filesystems . +(See also +.BR proc_filesystems (5).) +.SS Message retrieval interface +When doing operations on a filesystem configuration context, +the filesystem driver may choose to provide ancillary information to users= pace +in the form of message strings. +.P +The filesystem context file descriptors returned by +.BR fsopen () +and +.BR fspick (2) +may be queried for message strings at any time by calling +.BR read (2) +on the file descriptor. +Each call to +.BR read (2) +will return a single message, +prefixed to indicate its class: +.RS +.TP +.B "e " +An error message was logged. +This is usually associated with an error being returned from the correspon= ding +system call which triggered this message. +.TP +.B "w " +A warning message was logged. +.TP +.B "i " +An informational message was logged. +.RE +.P +Messages are removed from the queue as they are read. +Note that the message queue has limited depth, +so it is possible for messages to get lost. +If there are no messages in the message queue, +.B read(2) +will return no data and +.I errno +will be set to +.BR \%ENODATA . +If the +.I buf +argument to +.BR read (2) +is not large enough to contain the message, +.BR read (2) +will return no data and +.I errno +will be set to +.BR \%EMSGSIZE . +.P +If there are multiple filesystem context file descriptors referencing the = same +filesystem instance +(such as if you call +.BR fspick (2) +multiple times for the same mount), +each one gets its own independent message queue. +This does not apply to file descriptors that were duplicated with +.BR dup (2). +.P +Messages strings will usually be prefixed by the filesystem driver that lo= gged +the message, though this may not always be the case. +See the Linux kernel source code for details. +.SH RETURN VALUE +On success, a new file descriptor is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EFAULT +.I fsname +is NULL +or a pointer to a location +outside the calling process's accessible address space. +.TP +.B EINVAL +.I flags +had an invalid flag set. +.TP +.B EMFILE +The calling process has too many open files to create more. +.TP +.B ENFILE +The system has too many open files to create more. +.TP +.B ENODEV +The filesystem named by +.I fsname +is not supported by the kernel. +.TP +.B ENOMEM +The kernel could not allocate sufficient memory to complete the operation. +.TP +.B EPERM +The calling process does not have the required +.B \%CAP_SYS_ADMIN +capability. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 5.2. +.\" commit 24dcb3d90a1f67fe08c68a004af37df059d74005 +glibc 2.36. +.SH EXAMPLES +To illustrate the workflow for creating a new mount, +the following is an example of how to mount an +.BR ext4 (5) +filesystem stored on +.I /dev/sdb1 +onto +.IR /mnt . +.P +.in +4n +.EX +int fsfd, mntfd; +\& +fsfd =3D fsopen("ext4", FSOPEN_CLOEXEC); +fsconfig(fsfd, FSCONFIG_SET_FLAG, "ro", NULL, 0); +fsconfig(fsfd, FSCONFIG_SET_PATH, "source", "/dev/sdb1", AT_FDCWD); +fsconfig(fsfd, FSCONFIG_SET_FLAG, "noatime", NULL, 0); +fsconfig(fsfd, FSCONFIG_SET_FLAG, "acl", NULL, 0); +fsconfig(fsfd, FSCONFIG_SET_FLAG, "user_xattr", NULL, 0); +fsconfig(fsfd, FSCONFIG_SET_FLAG, "iversion", NULL, 0) +fsconfig(fsfd, FSCONFIG_CMD_CREATE, NULL, NULL, 0); +mntfd =3D fsmount(fsfd, FSMOUNT_CLOEXEC, MOUNT_ATTR_RELATIME); +move_mount(mntfd, "", AT_FDCWD, "/mnt", MOVE_MOUNT_F_EMPTY_PATH); +.EE +.in +.P +First, an ext4 configuration context is created and attached to the file +descriptor +.IR fsfd . +Then, a series of parameters +(such as the source of the filesystem) +are provided using +.BR fsconfig (2), +followed by the filesystem instance being created with +.BR \%FSCONFIG_CMD_CREATE . +.BR fsmount (2) +is then used to create a new mount object attached to the file descriptor +.IR mntfd , +which is then attached to the intended mount point using +.BR move_mount (2). +.P +The above procedure is functionally equivalent to the following mount oper= ation +using +.BR mount (2): +.P +.in +4n +.EX +mount("/dev/sdb1", "/mnt", "ext4", MS_RELATIME, + "ro,noatime,acl,user_xattr,iversion"); +.EE +.in +.P +And here's an example of creating a mount object +of an NFS server share +and setting a Smack security module label. +However, instead of attaching it to a mount point, +the program uses the mount object directly +to open a file from the NFS share. +.P +.in +4n +.EX +int fsfd, mntfd, fd; +\& +fsfd =3D fsopen("nfs", 0); +fsconfig(fsfd, FSCONFIG_SET_STRING, "source", "example.com/pub/linux", 0); +fsconfig(fsfd, FSCONFIG_SET_STRING, "nfsvers", "3", 0); +fsconfig(fsfd, FSCONFIG_SET_STRING, "rsize", "65536", 0); +fsconfig(fsfd, FSCONFIG_SET_STRING, "wsize", "65536", 0); +fsconfig(fsfd, FSCONFIG_SET_STRING, "smackfsdef", "foolabel", 0); +fsconfig(fsfd, FSCONFIG_SET_FLAG, "rdma", NULL, 0); +fsconfig(fsfd, FSCONFIG_CMD_CREATE, NULL, NULL, 0); +mntfd =3D fsmount(fsfd, 0, MOUNT_ATTR_NODEV); +fd =3D openat(mntfd, "src/linux-5.2.tar.xz", O_RDONLY); +.EE +.in +.P +Unlike the previous example, +this operation has no trivial equivalent with +.BR mount (2), +as it was not previously possible to create a mount object +that is not attached to any mount point. +.SH SEE ALSO +.BR fsconfig (2), +.BR fsmount (2), +.BR fspick (2), +.BR mount (2), +.BR mount_setattr (2), +.BR move_mount (2), +.BR open_tree (2), +.BR mount_namespaces (7) --=20 2.50.1 From nobody Sun Oct 5 09:06:18 2025 Received: from mout-p-101.mailbox.org (mout-p-101.mailbox.org [80.241.56.151]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 63CEF29E0E1; Wed, 6 Aug 2025 17:45:16 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=80.241.56.151 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1754502318; cv=none; b=d18Ww2PGx+il9Axmda3r+x3Zjs84O2lDfGfKgfZDAWg89Jjy669EPdWDzgqVOACAsbOPhFIVld/YMlnCGrtGRU/gjSPlupABJCOFaTxdNIBn6OBlBPpUtjtJxpqQQt7LFvbQpWhJHlHi3MlbyAufDH/3AldiHrDGOqjrAgQoqMc= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1754502318; c=relaxed/simple; bh=uybFdMRBk75CtOoblIzuAXGoty26tP69FQdwl5sxj1A=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=HSvk5t0u503T28oJw3JmYsj7TXt+JSyJsZTSEOU5rd196DBG9nTVjxlXl9dhxRU0QzHEiyZgOvKALZ9dbEty7pbF5kokfe2WZZbKRVYEpIdBcDPtZ2c/G6VgOu7S+qYz5V5oF1A4Rg6RjewcBOpnP0ixTZ/OBtlDU6me4ksp9fU= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=cyphar.com; spf=pass smtp.mailfrom=cyphar.com; dkim=pass (2048-bit key) header.d=cyphar.com header.i=@cyphar.com header.b=Pb/V0r04; arc=none smtp.client-ip=80.241.56.151 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=cyphar.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=cyphar.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=cyphar.com header.i=@cyphar.com header.b="Pb/V0r04" Received: from smtp102.mailbox.org (smtp102.mailbox.org [10.196.197.102]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) by mout-p-101.mailbox.org (Postfix) with ESMTPS id 4bxyP50nzDz9t2t; Wed, 6 Aug 2025 19:45:13 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=cyphar.com; s=MBO0001; t=1754502313; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=XYMs0hqTz8I8g9fHRUKiI4BOZ+NMWWn0g25B8md5Rjk=; b=Pb/V0r04Fdm4ogjWXr6lgzpMcXSI5jvQYa+SYs//CqztcQCqyFOwcSiM3NvGC7BY2DzhHH /xX8geaWu2/LZP3lpKUR6/YZHkwO8JIZt9oPgZYyp+5o+W7BFrGZq00HcIcAH1dA1xJ04n U08w9tMkoVCeT3YG0h/P4uw78asqcZc/XVE4ZZAm9asCauX8IEU6RHZ+uUy+uE57/zw9gh MGwM0Gi9q13MNBZLnLxon+egmaXGhb63jjuYR2sqSSHU8tTKTQJFmrinxDLZ+oef/2H6LO YO0gSUDI8/XmyBL54HdHRDVyNvdB5h+KZOXCvlYzku/sTM8MuQvnGMgfRbXOvw== From: Aleksa Sarai Date: Thu, 07 Aug 2025 03:44:38 +1000 Subject: [PATCH v2 04/11] fspick.2: document 'new' mount api Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Message-Id: <20250807-new-mount-api-v2-4-558a27b8068c@cyphar.com> References: <20250807-new-mount-api-v2-0-558a27b8068c@cyphar.com> In-Reply-To: <20250807-new-mount-api-v2-0-558a27b8068c@cyphar.com> To: Alejandro Colomar Cc: "Michael T. Kerrisk" , Alexander Viro , Jan Kara , Askar Safin , "G. Branden Robinson" , linux-man@vger.kernel.org, linux-api@vger.kernel.org, linux-fsdevel@vger.kernel.org, linux-kernel@vger.kernel.org, David Howells , Christian Brauner , Aleksa Sarai X-Developer-Signature: v=1; a=openpgp-sha256; l=7513; i=cyphar@cyphar.com; h=from:subject:message-id; bh=uybFdMRBk75CtOoblIzuAXGoty26tP69FQdwl5sxj1A=; b=owGbwMvMwCWmMf3Xpe0vXfIZT6slMWRMntLW7BTGu/IPv2af0GndnYd3NDM8e7Xpy3Vvv9nVu r/M9z5c0lHKwiDGxSArpsiyzc8zdNP8xVeSP61kg5nDygQyhIGLUwAmkmPH8L8kwvCPY9TBX6VH r3ziPXz7TLLRqbtzmYS7bU4FG4k9ufOC4X/yxukB3R9qdxm0f5gbxlqlz/rbSaaszObFv+dB52e nGjMDAA== X-Developer-Key: i=cyphar@cyphar.com; a=openpgp; fpr=C9C370B246B09F6DBCFC744C34401015D1D2D386 This is loosely based on the original documentation written by David Howells and later maintained by Christian Brauner, but has been rewritten to be more from a user perspective (as well as fixing a few critical mistakes). Co-developed-by: David Howells Co-developed-by: Christian Brauner Signed-off-by: Aleksa Sarai --- man/man2/fspick.2 | 305 ++++++++++++++++++++++++++++++++++++++++++++++++++= ++++ 1 file changed, 305 insertions(+) diff --git a/man/man2/fspick.2 b/man/man2/fspick.2 new file mode 100644 index 000000000000..5215d706428b --- /dev/null +++ b/man/man2/fspick.2 @@ -0,0 +1,305 @@ +.\" Copyright, the authors of the Linux man-pages project +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH fspick 2 (date) "Linux man-pages (unreleased)" +.SH NAME +fspick \- select filesystem for reconfiguration +.SH LIBRARY +Standard C library +.RI ( libc ,\~ \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " \ +" /* Definition of " AT_* " constants */" +.BR "#include " +.P +.BI "int fspick(int " dirfd ", const char *" path ", unsigned int " flags = ");" +.fi +.SH DESCRIPTION +The +.BR fspick () +system call is part of +the suite of file descriptor based mount facilities +in Linux. +.P +.BR fspick() +creates a new filesystem configuration context +for the filesystem instance +associated with the path described by +.IR dirfd +and +.IR path , +places it into reconfiguration mode +(similar to +.BR mount (8) +with the +.I -o remount +option), +and attaches it to a new file descriptor, +which is then returned. +The calling process must have the +.BR CAP_SYS_ADMIN +capability in order to create a new filesystem configuration context. +.P +The resultant file descriptor can be used with +.BR fsconfig (2) +to specify the desired set of changes +to mount parameters +of the filesystem instance. +Once the desired set of changes have been configured, +the changes can be effectuated by calling +.BR fsconfig (2) +with the +.B \%FSCONFIG_CMD_RECONFIGURE +command. +.P +As with "*at()" system calls, +.BR fspick () +uses the +.I dirfd +argument in conjunction with the +.I path +argument to determine the path to operate on, as follows: +.IP \[bu] 3 +If the pathname given in +.I path +is absolute, then +.I dirfd +is ignored. +.IP \[bu] +If the pathname given in +.I path +is relative and +.I dirfd +is the special value +.BR AT_FDCWD , +then +.I path +is interpreted relative to +the current working directory +of the calling process (like +.BR open (2)). +.IP \[bu] +If the pathname given in +.I path +is relative, +then it is interpreted relative to +the directory referred to by the file descriptor +.I dirfd +(rather than relative to +the current working directory +of the calling process, +as is done by +.BR open (2) +for a relative pathname). +In this case, +.I dirfd +must be a directory +that was opened for reading +.RB ( O_RDONLY ) +or using the +.B O_PATH +flag. +.IP \[bu] +If +.I path +is an empty string, +and +.I flags +contains +.BR \%FSPICK_EMPTY_PATH , +then the file descriptor referenced by +.I dirfd +is operated on directly. +In this case, +.I dirfd +can refer to any type of file, +not just a directory. +.P +.I flags +can be used to control aspects of how +.I path +is resolved +and properties of the returned file descriptor. +A value for +.I flags +is constructed by bitwise ORing +zero or more of the following constants: +.RS +.TP +.B FSPICK_CLOEXEC +Set the close-on-exec +.RB ( FD_CLOEXEC ) +flag on the new file descriptor. +See the description of the +.B O_CLOEXEC +flag in +.BR open (2) +for reasons why this may be useful. +.TP +.B FSPICK_EMPTY_PATH +If +.I path +is an empty string, +operate on the file referred to by +.I dirfd +(which may have been obtained from +.BR open (2), +.BR fsmount (2), +or +.BR open_tree (2)). +In this case, +.I dirfd +can refer to any type of file, not just a directory. +If +.I dirfd +is +.BR \%AT_FDCWD , +the call operates on the current working directory +of the calling process. +.TP +.B FSPICK_SYMLINK_NOFOLLOW +Do not follow symbolic links +in the terminal component of +.IR path . +If +.I path +references a symbolic link, +the returned filesystem context will reference +the filesystem that the symbolic link itself resides on. +.TP +.B FSPICK_NO_AUTOMOUNT +Do not follow automounts in the terminal component of +.IR path . +This allows you to configure the underlying automount point +without triggering the automount. +This flag has no effect if the automount point has already been mounted ov= er. +.RE +.P +As with filesystem contexts created with +.BR fsopen (2), +the file descriptor returned by +.BR fspick () +may be queried for message strings at any time by calling +.BR read (2) +on the file descriptor. +(See the "Message retrieval interface" subsection in +.BR fsopen (2) +for more details on the message format.) +.SH RETURN VALUE +On success, a new file descriptor is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EACCES +Search permission is denied +for one of the directories +in the path prefix of +.IR path . +(See also +.BR path_resolution (7).) +.TP +.B EBADF +.I path +is relative but +.I dirfd +is neither +.B AT_FDCWD +nor a valid file descriptor. +.TP +.B EFAULT +.I path +is NULL +or a pointer to a location +outside the calling process's accessible address space. +.TP +.B EINVAL +Invalid flag specified in +.IR flags . +.TP +.B ELOOP +Too many symbolic links encountered when resolving +.IR path . +.TP +.B ENAMETOOLONG +.I path +is longer than +.BR PATH_MAX . +.TP +.B ENOENT +A component of +.I path +does not exist, +or is a dangling symbolic link. +.TP +.B ENOENT +.I path +is an empty string, but +.B \%FSPICK_EMPTY_PATH +is not specified in +.IR flags . +.TP +.B ENOTDIR +A component of the path prefix of +.I path +is not a directory, or +.I path +is relative and +.I dirfd +is a file descriptor referring to a file other than a directory. +.TP +.B ENOMEM +The kernel could not allocate sufficient memory to complete the operation. +.TP +.B EMFILE +The calling process has too many open files to create more. +.TP +.B ENFILE +The system has too many open files to create more. +.TP +.B EPERM +The calling process does not have the required +.B \%CAP_SYS_ADMIN +capability. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 5.2. +.\" commit cf3cba4a429be43e5527a3f78859b1bfd9ebc5fb +glibc 2.36. +.SH EXAMPLES +The following example sets the read-only flag +on the filesystem instance referenced by +the mount object attached at +.IR /tmp . +.P +.in +4n +.EX +int fsfd =3D fspick(AT_FDCWD, "/tmp", FSPICK_CLOEXEC); +fsconfig(fsfd, FSCONFIG_SET_FLAG, "ro", NULL, 0); +fsconfig(fsfd, FSCONFIG_CMD_RECONFIGURE, NULL, NULL, 0); +.EE +.in +.P +The above procedure is functionally equivalent to the following mount oper= ation +using +.BR mount (2): +.P +.in +4n +.EX +mount(NULL, "/tmp", NULL, MS_REMOUNT | MS_RDONLY, NULL); +.EE +.in +.SH SEE ALSO +.BR fsconfig (2), +.BR fsmount (2), +.BR fsopen (2), +.BR mount (2), +.BR mount_setattr (2), +.BR move_mount (2), +.BR open_tree (2), +.BR mount_namespaces (7) + --=20 2.50.1 From nobody Sun Oct 5 09:06:18 2025 Received: from mout-p-202.mailbox.org (mout-p-202.mailbox.org [80.241.56.172]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 8394329E118; Wed, 6 Aug 2025 17:45:23 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=80.241.56.172 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1754502327; cv=none; b=EVfLT9uxKtFg0qRCQGkEzRmpdxEu2wCjnD/gYwzaiVtJDLhyAuBed/p4hu5ZLmfXgPLVDiimzZKlacRldThtAFIalvcrwuP8dnQMNOoH8hp+3fMA6I0G9w9i008NSEPievOykMrmOAG2fEwXotWnmgPmruLEUv86jUm6Fq7XVqM= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1754502327; c=relaxed/simple; bh=8V5517SfnGC9fh/OccXaDL7CQ7+9CNxdK3JGUA8FL2w=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=bO0+1JDSffCY9iVnC1Q8P1nuvc5CfKludnndQ4h5d626Ow7Tj3YhX9NikiMuhdWxcjFt5VSlmDuhhFS06aaYsjvmkJfCGzjSczbnq/ltY5QhlCO9yYJofS7l/XERUONbRbv7P5omKTvhSQ6Y0Dk8Js10gvcRRzP1YEyu701Ht+U= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=cyphar.com; spf=pass smtp.mailfrom=cyphar.com; dkim=pass (2048-bit key) header.d=cyphar.com header.i=@cyphar.com header.b=HhyqPcca; arc=none smtp.client-ip=80.241.56.172 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=cyphar.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=cyphar.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=cyphar.com header.i=@cyphar.com header.b="HhyqPcca" Received: from smtp102.mailbox.org (smtp102.mailbox.org [IPv6:2001:67c:2050:b231:465::102]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) by mout-p-202.mailbox.org (Postfix) with ESMTPS id 4bxyPC2Srhz9ssJ; Wed, 6 Aug 2025 19:45:19 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=cyphar.com; s=MBO0001; t=1754502319; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=DxruyvtEGOEMkNqH0my5XkmE1kqlEqYsLOif0ZsJwuc=; b=HhyqPccaikb6aqP9MUVNglo3Ws7krVK9k2+aGH8qUVjq3yqGjgUytA3F+RJIgkT1NRqiX9 2Rq2KnNvz/CTuA9CXcv+59aWTsK1nJvohisxBbtCNUS6DTV7FPaTFAXuMl+/Z0AgIQcbI+ jjyysEl/+v7/fZV19fyX3xRAKtYtUArVdpN34TfZI0h3z03wZGWtSgQGMgan33kZnW4YKh vj02Ums/7+Rvjmn+SSQfEOz2rLYEwtk+w0RQZ5hr+rtNZG6QrrQxEPyoqNagetN/TAtH61 3siGD/dgHPdFi1vKcmFTSGVByo+BBEaYjHn2DTE68jXYcEAnoAmhHVRhcG9faA== Authentication-Results: outgoing_mbo_mout; dkim=none; spf=pass (outgoing_mbo_mout: domain of cyphar@cyphar.com designates 2001:67c:2050:b231:465::102 as permitted sender) smtp.mailfrom=cyphar@cyphar.com From: Aleksa Sarai Date: Thu, 07 Aug 2025 03:44:39 +1000 Subject: [PATCH v2 05/11] fsconfig.2: document 'new' mount api Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Message-Id: <20250807-new-mount-api-v2-5-558a27b8068c@cyphar.com> References: <20250807-new-mount-api-v2-0-558a27b8068c@cyphar.com> In-Reply-To: <20250807-new-mount-api-v2-0-558a27b8068c@cyphar.com> To: Alejandro Colomar Cc: "Michael T. Kerrisk" , Alexander Viro , Jan Kara , Askar Safin , "G. Branden Robinson" , linux-man@vger.kernel.org, linux-api@vger.kernel.org, linux-fsdevel@vger.kernel.org, linux-kernel@vger.kernel.org, David Howells , Christian Brauner , Aleksa Sarai X-Developer-Signature: v=1; a=openpgp-sha256; l=15498; i=cyphar@cyphar.com; h=from:subject:message-id; bh=8V5517SfnGC9fh/OccXaDL7CQ7+9CNxdK3JGUA8FL2w=; b=owGbwMvMwCWmMf3Xpe0vXfIZT6slMWRMntLWwBr60k74B9uvwytm2jxoK760RPKO+AOhZC2HL 6fLbl3e1VHKwiDGxSArpsiyzc8zdNP8xVeSP61kg5nDygQyhIGLUwAmYtPFyPAstX4pj8mKl4zH 69asLOzmSVh5gqtJ7cyqG/Iv67JZmuoZ/kcmtyzgP5MZb197b0H0/4RqjwlXd3E+sTAwfrxH+d9 caTYA X-Developer-Key: i=cyphar@cyphar.com; a=openpgp; fpr=C9C370B246B09F6DBCFC744C34401015D1D2D386 X-Rspamd-Queue-Id: 4bxyPC2Srhz9ssJ This is loosely based on the original documentation written by David Howells and later maintained by Christian Brauner, but has been rewritten to be more from a user perspective (as well as fixing a few critical mistakes). Co-developed-by: David Howells Co-developed-by: Christian Brauner Signed-off-by: Aleksa Sarai --- man/man2/fsconfig.2 | 559 ++++++++++++++++++++++++++++++++++++++++++++++++= ++++ 1 file changed, 559 insertions(+) diff --git a/man/man2/fsconfig.2 b/man/man2/fsconfig.2 new file mode 100644 index 000000000000..e2121b7a6b68 --- /dev/null +++ b/man/man2/fsconfig.2 @@ -0,0 +1,559 @@ +.\" Copyright, the authors of the Linux man-pages project +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH fsconfig 2 (date) "Linux man-pages (unreleased)" +.SH NAME +fsconfig \- configure new or existing filesystem context +.SH LIBRARY +Standard C library +.RI ( libc ,\~ \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " +.P +.BI "int fsconfig(int " fd ", unsigned int " cmd "," +.BI " const char *" key ", const void *" value ", int " aux ")= ;" +.fi +.SH DESCRIPTION +The +.BR fsconfig () +system call is part of the suite of file descriptor based mount facilities +in Linux. +.P +.BR fsconfig () +is used to supply parameters to +and issue commands against +the filesystem configuration context +associated with the file descriptor +.IR fd . +Filesystem configuration contexts can be created with +.BR fsopen (2) +or instantiated from an extant filesystem instance with +.BR fspick (2). +.P +The +.I cmd +argument indicates the command to be issued. +Some commands supply parameters to the context +(equivalent to mount options specified with +.BR mount (8)), +while others are meta-operations on the filesystem context. +The list of valid +.I cmd +values are: +.RS +.TP +.B FSCONFIG_SET_FLAG +Set the flag parameter named by +.IR key . +.I value +must be NULL, +and +.I aux +must be 0. +.TP +.B FSCONFIG_SET_STRING +Set the string parameter named by +.I key +to the value specified by +.IR value . +.I value +points to a null-terminated string, +and +.I aux +must be 0. +.TP +.B FSCONFIG_SET_BINARY +Set the blob parameter named by +.I key +to the contents of the binary blob +specified by +.IR value . +.I value +points to +the start of a buffer +that is +.I aux +bytes in length. +.TP +.B FSCONFIG_SET_FD +Set the file parameter named by +.I key +to the file referenced by the file descriptor +.IR aux . +.I value +must be NULL. +.IP +You may also use +.B \%FSCONFIG_SET_STRING +for file parameters, +with +.I value +set to a null-terminated string +containing a base-10 representation +of the file descriptor number. +This mechanism is primarily intended for compatibility with older +.BR mount (2)-based +programs. +.TP +.B FSCONFIG_SET_PATH +Set the path parameter named by +.I key +to the object at a provided path, +resolved in a similar manner to +.BR openat (2). +.I value +points to a null-terminated pathname string, +and +.I aux +is equivalent to the +.I dirfd +argument to +.BR openat (2). +.IP +You may also use +.B \%FSCONFIG_SET_STRING +for path parameters, +the behaviour of which is equivalent to +.B \%FSCONFIG_SET_PATH +with +.I aux +set to +.BR AT_FDCWD . +.TP +.B FSCONFIG_SET_PATH_EMPTY +As with +.BR \%FSCONFIG_SET_PATH , +except that if +.I value +is an empty string, +the file descriptor specified by +.I aux +may be any type of file +(not just a directory) +and will be used as the path parameter value, +equivalent to the behaviour of +.B \%AT_EMPTY_PATH +with most "*at()" system calls. +If +.I aux +is +.BR AT_FDCWD , +the call operates on the current working directory +of the calling process. +.IP +Note that this behaviour with empty paths is distinct in some subtle ways = to +.BR \%FSCONFIG_SET_FD . +.B \%FSCONFIG_SET_FD +indicates that the underlying file +for the file descriptor +.I aux +should be used as the parameter value directly; +.B \%FSCONFIG_SET_PATH_EMPTY +indicates that the underlying file +for the file descriptor +.I aux +should be re-opened by the filesystem driver, +and the newly created file description +should be used as the parameter value. +This can result in slightly different behaviour +when dealing with special files +or files sourced from pseudofilesystems. +Filesystems may also choose to only support one kind of parameter, +and so a parameter that accepts +.B FSCONFIG_SET_FD +may not work with +.BR FSCONFIG_SET_PATH ( _EMPTY ) +(or vice-versa). +.TP +.B FSCONFIG_CMD_CREATE +This command instructs the filesystem driver +to instantiate an instance of the filesystem in the kernel +with the parameters set in the filesystem configuration context +referenced by the file descriptor +.IR fd . +.IR key " and " value +must be NULL, +and +.I aux +must be 0. +.IP +If this operation succeeds, +the filesystem context +associated with file descriptor +.I fd +now references the created filesystem instance, +and is placed into a special "needs-mount" mode +that allows you to use +.BR fsmount (2) +to create a mount object from the filesystem instance. +.IP +This is intended for use with filesystem configuration contexts created wi= th +.BR fsopen (2). +In order to create a filesystem instance, +the calling process must have the +.B \%CAP_SYS_ADMIN +capability. +.IP +Note that the Linux kernel reuses filesystem instances +for many filesystems, +so (depending on the filesystem being configured and parameters used) +it is possible for the filesystem instance "created" by +.B \%FSCONFIG_CMD_CREATE +to, in fact, be a reference +to an existing filesystem instance in the kernel. +The kernel will attempt to merge the specified parameters +of this filesystem configuration context +with those of the filesystem instance being reused, +but some parameters may be +.IR "silently ignored" . +.IP +Programs that need to ensure +that they create a new filesystem instance +with specific parameters +(notably, security-related parameters such as "acl" to enable +POSIX ACLs as described in +.BR acl (5)) +should use +.B \%FSCONFIG_CMD_CREATE_EXCL +instead. +.TP +.BR FSCONFIG_CMD_CREATE_EXCL " (since Linux 6.6)" +.\" commit 22ed7ecdaefe0cac0c6e6295e83048af60435b13 +As with +.BR \%FSCONFIG_CMD_CREATE , +except that the kernel is instructed +to create a new filesystem instance +("superblock" in kernel developer parlance) +rather than reusing an existing one. +.IP +If this is not possible +(such as with disk-backed filesystems +where multiple filesystem instances +using the same filesystem driver +and writing to the same underlying device +could result in data corruption), +this operation will incur +an +.B EBUSY +error. +.IP +As a result (unlike +.BR \%FSCONFIG_CMD_CREATE ), +if this command succeeds +then the calling process can be sure that +all of the parameters successfully configured with +.BR fsconfig () +will actually be applied +to the created filesystem instance. +.TP +.B FSCONFIG_CMD_RECONFIGURE +This command instructs the filesystem driver +to apply the parameters set in this filesystem configuration context +to an already existing filesystem instance. +.IP +This is primarily intended for use with +.BR fspick (2), +but may also be used to modify the parameters of filesystem instance after +.BR \%FSCONFIG_CMD_CREATE +was used to create it +and a mount object was created using +.BR fsmount (2). +In order to reconfigure an extant filesystem instance, +the calling process must have the +.B CAP_SYS_ADMIN +capability. +.IP +Once this operation succeeds, the filesystem context is reset +but remains in reconfiguration mode +and thus can be used for subsequent +.B \%FSCONFIG_CMD_RECONFIGURE +commands. +.SH RETURN VALUE +On success, +.BR fsconfig () +returns 0. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +If an error occurs, the filesystem driver may provide +additional information about the error +through the message retrieval interface for filesystem configuration conte= xts. +This additional information can be retrieved at any time by calling +.BR read (2) +on the filesystem instance or filesystem configuration context referenced = by +the file descriptor +.IR fd . +(See the "Message retrieval interface" subsection in +.BR fsopen (2) +for more details on the message format.) +.P +Even after an error occurs, +the filesystem configuration context is +.I not +invalidated, +and thus can still be used with other +.BR fsconfig () +commands. +This means that users can probe support for mount parameters +on a per-parameter basis, +and adjust which parameters they wish to set. +.P +The error values given below result from filesystem type independent error= s. +Each filesystem type may have its own special errors +and its own special behavior. +See the Linux kernel source code for details. +.TP +.B EACCES +A component of a path +provided as a path parameter +was not searchable. +(See also +.BR path_resolution (7).) +.TP +.B EACCES +.B \%FSCONFIG_CMD_CREATE +was attempted +for a read-only filesystem +without specifying the +.RB ' ro ' +flag parameter. +.TP +.B EACCES +A specified block device parameter +is located on a filesystem +mounted with the +.B \%MS_NODEV +option. +.TP +.B EBADF +The file descriptor given by +.I fd +(or possibly by +.IR aux , +depending on the command) +is invalid. +.TP +.B EBUSY +The filesystem context attached to +.I fd +is in the wrong state +for the given command. +.TP +.B EBUSY +The filesystem instance cannot be reconfigured as read-only +with +.B \%FSCONFIG_CMD_RECONFIGURE +because some programs +still hold files open for writing. +.TP +.B EBUSY +A new filesystem instance was requested with +.B \%FSCONFIG_CMD_CREATE_EXCL +but a matching superblock already existed. +.TP +.B EFAULT +One of the pointer arguments +points to a location +outside the calling process's accessible address space. +.TP +.B EINVAL +.I fd +does not refer to +a filesystem configuration context +or filesystem instance. +.TP +.B EINVAL +One of the values of +.IR name , +.IR value , +and/or +.I aux +were set to a non-zero value when +.I cmd +required that they be zero +(or NULL). +.TP +.B EINVAL +The parameter named by +.I name +cannot be set +using the type specified with +.IR cmd . +.TP +.B EINVAL +One of the source parameters +referred to +an invalid superblock. +.TP +.B ELOOP +Too many links encountered +during pathname resolution +of a path argument. +.TP +.B ENAMETOOLONG +A path argument was longer than +.BR PATH_MAX . +.TP +.B ENOENT +A path argument had a non-existent component. +.TP +.B ENOENT +A path argument is an empty string, +but +.I cmd +is not +.BR \%FSCONFIG_SET_PATH_EMPTY . +.TP +.B ENOMEM +The kernel could not allocate sufficient memory to complete the operation. +.TP +.B ENOTBLK +The parameter named by +.I name +must be a block device, +but the provided parameter value was not a block device. +.TP +.B ENOTDIR +A component of the path prefix +of a path argument +was not a directory. +.TP +.B EOPNOTSUPP +The command given by +.I cmd +is not valid. +.TP +.B ENXIO +The major number +of a block device parameter +is out of range. +.TP +.B EPERM +The command given by +.I cmd +was +.BR \%FSCONFIG_CMD_CREATE , +.BR \%FSCONFIG_CMD_CREATE_EXCL , +or +.BR \% FSCONFIG_CMD_RECONFIGURE , +but the calling process does not have the required +.B \%CAP_SYS_ADMIN +capability. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 5.2. +.\" commit ecdab150fddb42fe6a739335257949220033b782 +glibc 2.36. +.SH EXAMPLES +To illustrate the different kinds of flags that can be configured with +.BR fsconfig (), +here are a few examples of some different filesystems being created: +.P +.in +4n +.EX +int fsfd, mntfd; +\& +fsfd =3D fsopen("tmpfs", FSOPEN_CLOEXEC); +fsconfig(fsfd, FSCONFIG_SET_FLAG, "inode64", NULL, 0); +fsconfig(fsfd, FSCONFIG_SET_STRING, "uid", "1234", 0); +fsconfig(fsfd, FSCONFIG_SET_STRING, "huge", "never", 0); +fsconfig(fsfd, FSCONFIG_SET_FLAG, "casefold", NULL, 0); +fsconfig(fsfd, FSCONFIG_CMD_CREATE, NULL, NULL, 0); +mntfd =3D fsmount(fsfd, FSMOUNT_CLOEXEC, MOUNT_ATTR_NOEXEC); +move_mount(mntfd, "", AT_FDCWD, "/tmp", MOVE_MOUNT_F_EMPTY_PATH); +\& +fsfd =3D fsopen("erofs", FSOPEN_CLOEXEC); +fsconfig(fsfd, FSCONFIG_SET_STRING, "source", "/dev/loop0", 0); +fsconfig(fsfd, FSCONFIG_SET_FLAG, "acl", NULL, 0); +fsconfig(fsfd, FSCONFIG_SET_FLAG, "user_xattr", NULL, 0); +fsconfig(fsfd, FSCONFIG_CMD_CREATE_EXCL, NULL, NULL, 0); +mntfd =3D fsmount(fsfd, FSMOUNT_CLOEXEC, MOUNT_ATTR_NOSUID); +move_mount(mntfd, "", AT_FDCWD, "/mnt", MOVE_MOUNT_F_EMPTY_PATH); +.EE +.in +.P +Some filesystems have different behaviour +when using +.BR fsconfig () +to set the same parameter +named by +.I key +multiple times: +.P +.in +4n +.EX +\& +int fsfd, mntfd, lowerdirfd; +\& +lowerdirfd =3D open("/o/ctr/lower1", O_DIRECTORY | O_CLOEXEC); +fsfd =3D fsopen("overlay", FSOPEN_CLOEXEC); +/* "lowerdir+" appends to the lower dir stack */ +fsconfig(fsfd, FSCONFIG_SET_FD, "lowerdir+", NULL, lowerdirfd); +fsconfig(fsfd, FSCONFIG_SET_STRING, "lowerdir+", "/o/ctr/lower2", 0); +.\" fsconfig(fsfd, FSCONFIG_SET_PATH, "lowerdir+", "/o/ctr/lower3", AT_FDC= WD); +.\" fsconfig(fsfd, FSCONFIG_SET_PATH_EMPTY, "lowerdir+", "", lowerdirfd); +fsconfig(fsfd, FSCONFIG_SET_STRING, "xino", "auto", 0); +fsconfig(fsfd, FSCONFIG_SET_STRING, "nfs_export", "off", 0); +fsconfig(fsfd, FSCONFIG_CMD_CREATE, NULL, NULL, 0); +mntfd =3D fsmount(fsfd, FSMOUNT_CLOEXEC, 0); +move_mount(mntfd, "", AT_FDCWD, "/mnt", MOVE_MOUNT_F_EMPTY_PATH); +.EE +.in +.P +Other filesystems allow you to use different +.BI FSCONFIG_SET_ * +commands for the same parameter +named by +.IR key : +.P +.in +4n +.EX +\& +int fsfd, mntfd, nsfd, nsdirfd; +\& +nsfd =3D open("/proc/self/ns/pid", O_PATH); +nsdirfd =3D open("/proc/1/ns", O_DIRECTORY); +\& +fsfd =3D fsopen("proc", FSOPEN_CLOEXEC); +/* "pidns" changes the value each time. */ +fsconfig(fsfd, FSCONFIG_SET_PATH, "pidns", "/proc/self/ns/pid", AT_FDCWD); +fsconfig(fsfd, FSCONFIG_SET_PATH, "pidns", "pid", NULL, nsdirfd); +fsconfig(fsfd, FSCONFIG_SET_PATH_EMPTY, "pidns", "", nsfd); +fsconfig(fsfd, FSCONFIG_SET_FD, "pidns", NULL, nsfd); +fsconfig(fsfd, FSCONFIG_CMD_CREATE, NULL, NULL, 0); +mntfd =3D fsmount(fsfd, FSMOUNT_CLOEXEC, 0); +move_mount(mntfd, "", AT_FDCWD, "/proc", MOVE_MOUNT_F_EMPTY_PATH); +.EE +.in +.P +And here is an example of how +.BR fspick (2) +can be used with +.BR fsconfig () +to reconfigure the parameters +of an extant filesystem instance +attached to +.IR /proc : +.P +.in +4n +.EX +int fsfd =3D fspick(AT_FDCWD, "/proc", FSPICK_CLOEXEC); +fsconfig(fsfd, FSCONFIG_SET_STRING, "hidepid", "ptraceable", 0); +fsconfig(fsfd, FSCONFIG_SET_STRING, "subset", "pid", 0); +fsconfig(fsfd, FSCONFIG_CMD_RECONFIGURE, NULL, NULL, 0); +.EE +.in +.SH SEE ALSO +.BR fsmount (2), +.BR fsopen (2), +.BR fspick (2), +.BR mount (2), +.BR mount_setattr (2), +.BR move_mount (2), +.BR open_tree (2), +.BR mount_namespaces (7) + --=20 2.50.1 From nobody Sun Oct 5 09:06:18 2025 Received: from mout-p-202.mailbox.org (mout-p-202.mailbox.org [80.241.56.172]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id BD0332BE63F; Wed, 6 Aug 2025 17:45:28 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=80.241.56.172 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1754502330; cv=none; b=cRsINy6pE4vk55wo4FBEaEUAXdL48dmvNFmLQz1f3r2roEXJfAEoUPx9O2mnfUknSit40Sq4Sdp/FIdptXFYXwYzs8r7rCP8M3km7D4pzPVYLcIsQUQs2Pn2B6T/b7Y+ZHpqlVn71w19P8R7TtfTjMAMOmoOCm+E5dvouBdCbWc= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1754502330; c=relaxed/simple; bh=YqZDnDozwkdg2Pt9cfjnVWsOPSvNBiSa9IakteYzhAk=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=JljtgjmVFNhBqz8Nngk/588qVPhiPvOXNtJdN5tahtZnREgq4cKLoe/nS4tMAfDVZRpKiEUGFt0LarisCMmj0/1sX6nL+WM8ecntl8qctSGLW7TFTGp4gEF0NBr02PNbFUOv1wGEEdD2mfY+4yOxlHKvvCLBR/CCZTnTJbP+y2I= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=cyphar.com; spf=pass smtp.mailfrom=cyphar.com; dkim=pass (2048-bit key) header.d=cyphar.com header.i=@cyphar.com header.b=s3/xhnoQ; arc=none smtp.client-ip=80.241.56.172 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=cyphar.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=cyphar.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=cyphar.com header.i=@cyphar.com header.b="s3/xhnoQ" Received: from smtp102.mailbox.org (smtp102.mailbox.org [IPv6:2001:67c:2050:b231:465::102]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) by mout-p-202.mailbox.org (Postfix) with ESMTPS id 4bxyPK2Ptbz9sqy; Wed, 6 Aug 2025 19:45:25 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=cyphar.com; s=MBO0001; t=1754502325; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=65WnrfSaWXYag9/vDU51p8WBVUnXfx9dXJMQvrHv3n4=; b=s3/xhnoQHjejYLINY3tFUo1r3yp+9IVKvLppN39/z41ebXkoVFeQjiLzesIMIaqlc8XShR BuEVUJsiqhQ7TpG43IFVz5YdDiaaByri+Ffz9fXeCLGhyvl4zK4nhWk9C2RKNmxBuQrP9T hGuc1IthBEcFeeza6XIexbuuS19UedOurv1bic03xqmIHrFGz6OYEjEhZ9wnyxYz1uYdQz M9wSpCcD/ATJiLY1//rKev6ZIqqqxku7ogskC9iJlIm9/qlwhdWiWrhvzUgJZkBxDLIhWJ XvS/NXejXsY21+TzethlRpIWcP66I5K3cdRyWiTC+coIlfLnCodJoFkO75A0ug== Authentication-Results: outgoing_mbo_mout; dkim=none; spf=pass (outgoing_mbo_mout: domain of cyphar@cyphar.com designates 2001:67c:2050:b231:465::102 as permitted sender) smtp.mailfrom=cyphar@cyphar.com From: Aleksa Sarai Date: Thu, 07 Aug 2025 03:44:40 +1000 Subject: [PATCH v2 06/11] fsmount.2: document 'new' mount api Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Message-Id: <20250807-new-mount-api-v2-6-558a27b8068c@cyphar.com> References: <20250807-new-mount-api-v2-0-558a27b8068c@cyphar.com> In-Reply-To: <20250807-new-mount-api-v2-0-558a27b8068c@cyphar.com> To: Alejandro Colomar Cc: "Michael T. Kerrisk" , Alexander Viro , Jan Kara , Askar Safin , "G. Branden Robinson" , linux-man@vger.kernel.org, linux-api@vger.kernel.org, linux-fsdevel@vger.kernel.org, linux-kernel@vger.kernel.org, David Howells , Christian Brauner , Aleksa Sarai X-Developer-Signature: v=1; a=openpgp-sha256; l=5778; i=cyphar@cyphar.com; h=from:subject:message-id; bh=YqZDnDozwkdg2Pt9cfjnVWsOPSvNBiSa9IakteYzhAk=; b=owGbwMvMwCWmMf3Xpe0vXfIZT6slMWRMntKeLXusdOXMsl+cGhncerJ+m2etCS4pfjHx6LKiB +sUvc5/7yhlYRDjYpAVU2TZ5ucZumn+4ivJn1aywcxhZQIZwsDFKQATmRPE8D/kz/xfDvOld5Xv zHoaNrl69nLGJU5Rj1rsLLR90q5rnMpl+B/WYrj6h9+9YMNts49W5PPUymq3XNaff7DFZb7JdF+ mEhYA X-Developer-Key: i=cyphar@cyphar.com; a=openpgp; fpr=C9C370B246B09F6DBCFC744C34401015D1D2D386 X-Rspamd-Queue-Id: 4bxyPK2Ptbz9sqy This is loosely based on the original documentation written by David Howells and later maintained by Christian Brauner, but has been rewritten to be more from a user perspective (as well as fixing a few critical mistakes). Co-developed-by: David Howells Co-developed-by: Christian Brauner Signed-off-by: Aleksa Sarai --- man/man2/fsmount.2 | 209 +++++++++++++++++++++++++++++++++++++++++++++++++= ++++ 1 file changed, 209 insertions(+) diff --git a/man/man2/fsmount.2 b/man/man2/fsmount.2 new file mode 100644 index 000000000000..8c264c3d5aba --- /dev/null +++ b/man/man2/fsmount.2 @@ -0,0 +1,209 @@ +.\" Copyright, the authors of the Linux man-pages project +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH fsmount 2 (date) "Linux man-pages (unreleased)" +.SH NAME +fsmount \- instantiate mount object from filesystem context +.SH LIBRARY +Standard C library +.RI ( libc ,\~ \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " +.P +.BI "int fsmount(int " fsfd ", unsigned int " flags ", \ +unsigned int " attr_flags ");" +.fi +.SH DESCRIPTION +The +.BR fsmount () +system call is part of the suite of file descriptor based mount facilities +in Linux. +.P +.BR fsmount () +takes the created filesystem instance +referenced by the filesystem context +associated with the file descriptor +.I fsfd +and creates a new mount object +for the root of the filesystem instance, +which is then attached to a new file descriptor +and returned. +In order to create a mount object with +.BR fsmount (), +the calling process must have the +.BR \%CAP_SYS_ADMIN +capability. +.P +The filesystem context must have been created with a call to +.BR fsopen (2) +and then had a filesystem instance instantiated with a call to +.BR fsconfig (2) +with +.B \%FSCONFIG_CMD_CREATE +or +.B \%FSCONFIG_CMD_CREATE_EXCL +in order to be in the correct state +for this operation. +.P +As with file descriptors returned from +.BR open_tree (2) +called with +.BR OPEN_TREE_CLONE , +the returned file descriptor +can then be used with +.BR move_mount (2), +.BR mount_setattr (2), +or other such system calls +to do further mount operations. +This mount object will be unmounted and destroyed +when the file descriptor is closed +if it was not otherwise mounted somewhere else +by calling +.BR move_mount (2). +The returned file descriptor +also acts the same as one produced by +.BR open (2) +with +.BR O_PATH , +meaning it can also be used as a +.I dirfd +argument +to "*at()" system calls. +.P +.I flags +controls the creation of the returned file descriptor. +A value for +.I flags +is constructed by bitwise ORing +zero or more of the following constants: +.RS +.TP +.B FSMOUNT_CLOEXEC +Set the close-on-exec +.RB ( FD_CLOEXEC ) +flag on the new file descriptor. +See the description of the +.B O_CLOEXEC +flag in +.BR open (2) +for reasons why this may be useful. +.RE +.P +.I attr_flags +specifies the mount attributes +for the created mount object +and accepts the same set of +.BI \%MOUNT_ATTR_ * +flags as +.BR mount_setattr (2), +except for flags such as +.B \%MOUNT_ATTR_IDMAP +which require specifying additional fields in +.BR mount_attr (2type). +.P +If the +.BR fsmount () +operation is successful, +the filesystem context +associated with the file descriptor +.I fsfd +is reset +and placed into a reconfiguration state, +similar to the one produced by +.BR fspick (2). +You may coninue to use +.BR fsconfig (2) +with the +.B \%FSCONFIG_CMD_RECONFIGURE +command +to reconfigure the filesystem instance. +.P +Unlike +.BR open_tree (2), +.BR fsmount () +can only be called once +to produce a mount object +for a given filesystem configuration context. +.SH RETURN VALUE +On success, a new file descriptor is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBUSY +The filesystem context attached to +.I fsfd +is not in the right state +to be used by +.BR fsmount (). +.TP +.B EINVAL +.I flags +had an invalid flag set. +.TP +.B EINVAL +.I attr_flags +had an invalid +.BI MOUNT_ATTR_ * +flag set. +.TP +.B EMFILE +The calling process has too many open files to create more. +.TP +.B ENFILE +The system has too many open files to create more. +.TP +.B ENOSPC +The "anonymous" mount namespace +necessary to contain the new mount object +could not be allocated, +as doing so would +exceed the configured per-user limit +on the number of mount namespaces +in the current user namespace. +(See also +.BR namespaces (7).) +.TP +.B ENOMEM +The kernel could not allocate sufficient memory to complete the operation. +.TP +.B EPERM +The calling process does not have the required +.B CAP_SYS_ADMIN +capability. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 5.2. +.\" commit 93766fbd2696c2c4453dd8e1070977e9cd4e6b6d +glibc 2.36. +.SH EXAMPLES +.in +4n +.EX +int fsfd, mntfd, tmpfd; +\& +fsfd =3D fsopen("tmpfs", FSOPEN_CLOEXEC); +fsconfig(fsfd, FSCONFIG_CMD_CREATE, NULL, NULL, 0); +mntfd =3D fsmount(fsfd, FSMOUNT_CLOEXEC, MOUNT_ATTR_NODEV | MOUNT_ATTR_NOE= XEC); +\& +/* Create a new file without attaching the mount object. */ +int tmpfd =3D openat(mntfd, "tmpfile", O_CREAT | O_EXCL | O_RDWR, 0600); +unlinkat(mntfd, "tmpfile", 0); +\& +/* Attach the mount object to "/tmp". */ +move_mount(mntfd, "", AT_FDCWD, "/tmp", MOVE_MOUNT_F_EMPTY_PATH); +.EE +.in +.SH SEE ALSO +.BR fsconfig (2), +.BR fsopen (2), +.BR fspick (2), +.BR mount (2), +.BR mount_setattr (2), +.BR move_mount (2), +.BR open_tree (2), +.BR mount_namespaces (7) + --=20 2.50.1 From nobody Sun Oct 5 09:06:18 2025 Received: from mout-p-103.mailbox.org (mout-p-103.mailbox.org [80.241.56.161]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id C9D172BEC2E; Wed, 6 Aug 2025 17:45:34 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=80.241.56.161 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1754502337; cv=none; b=Rls1nDgOsBk17Wd1/csEPpTi/e6e95sGOxOzXsdN/Iw5EzS5PVHxoY8+LZhaOb2DZu+OyFk+iohfR+4+BrOGinRqWwGXNpdNyHz8gdRUxCbnrOsX45JFZJoK03puaf8zIV/eTAsu0Nbx2yFKXuH4WjFKJZt44DByFzaKK//T9dw= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1754502337; c=relaxed/simple; bh=DfVp7Qh4qzNKnR+wvPx9r0CCicFOLCmcxyEIhNKUYHY=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=NTv93D/KHOEvXL79ZMtzxRUOWlnGMRvS98sCXBJOc+pb1M8FPOqWJbG45/xPv4K44ZSp3xp1qECv8vfqi2w6qnta7HsC3KRCRpeXtXvAipaTw4HBlZnNyk2fbMZly0jkGDC+DlMv0lxXBc3uU4Er3HS9h/41QfJHjtrsBhh6xwM= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=cyphar.com; spf=pass smtp.mailfrom=cyphar.com; dkim=pass (2048-bit key) header.d=cyphar.com header.i=@cyphar.com header.b=gdsm/Hvr; arc=none smtp.client-ip=80.241.56.161 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=cyphar.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=cyphar.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=cyphar.com header.i=@cyphar.com header.b="gdsm/Hvr" Received: from smtp102.mailbox.org (smtp102.mailbox.org [10.196.197.102]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) by mout-p-103.mailbox.org (Postfix) with ESMTPS id 4bxyPR32lbz9t6m; Wed, 6 Aug 2025 19:45:31 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=cyphar.com; s=MBO0001; t=1754502331; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=jZ6rAyB1NSbePvXR8lDYnagwjuE0pZoX6N+BqIoX6RY=; b=gdsm/HvrQc+vohEtPfsUnIp7zquCkI268Ffs1X8WzVvmLRhm/Zy3kon2sy42qdjShXtstl Ft3gH/gv438Sbk8fUJ/9tXR3J8ryVILmKmMe7/R2KA7cK84tXqmaMguUxWgBQ8QR+kqU00 An4CoTD2CDkR7cf8gn09eCvQfm1y4sWxHAymfYlX6IKCXrG7aAvjaS84h3YTY7ekPQbRkJ o1xWQgzu36uuAdyJNlQ7gthi6BVohw/hCjutAydCGhghZl8pun1UBrB60vqe986CUBI7wZ y2dS/RpSvTSftmMRTJG8HYh9C4/kCSaZntQI/LFHi5sb6O8E1uiCjUyRDLzSwg== From: Aleksa Sarai Date: Thu, 07 Aug 2025 03:44:41 +1000 Subject: [PATCH v2 07/11] move_mount.2: document 'new' mount api Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Message-Id: <20250807-new-mount-api-v2-7-558a27b8068c@cyphar.com> References: <20250807-new-mount-api-v2-0-558a27b8068c@cyphar.com> In-Reply-To: <20250807-new-mount-api-v2-0-558a27b8068c@cyphar.com> To: Alejandro Colomar Cc: "Michael T. Kerrisk" , Alexander Viro , Jan Kara , Askar Safin , "G. Branden Robinson" , linux-man@vger.kernel.org, linux-api@vger.kernel.org, linux-fsdevel@vger.kernel.org, linux-kernel@vger.kernel.org, David Howells , Christian Brauner , Aleksa Sarai X-Developer-Signature: v=1; a=openpgp-sha256; l=14804; i=cyphar@cyphar.com; h=from:subject:message-id; bh=DfVp7Qh4qzNKnR+wvPx9r0CCicFOLCmcxyEIhNKUYHY=; b=owGbwMvMwCWmMf3Xpe0vXfIZT6slMWRMntJuJreLV/FhlG6Cte3sd7HF3TNs3Dh/T7tzW2i2B 9e/w8/zO0pZGMS4GGTFFFm2+XmGbpq/+Eryp5VsMHNYmUCGMHBxCsBEgvQZ/ieydm9vX7VCYKlE lSdX0jvzvVUq1rOqDuhOzV3CsPok0xuGf/bF632Uk/ZYlf1pZhf4M+sdp0Jny6dQ/QWpNxU9Vl3 K4wcA X-Developer-Key: i=cyphar@cyphar.com; a=openpgp; fpr=C9C370B246B09F6DBCFC744C34401015D1D2D386 This is loosely based on the original documentation written by David Howells and later maintained by Christian Brauner, but has been rewritten to be more from a user perspective (as well as fixing a few critical mistakes). Co-developed-by: David Howells Co-developed-by: Christian Brauner Signed-off-by: Aleksa Sarai --- man/man2/move_mount.2 | 609 ++++++++++++++++++++++++++++++++++++++++++++++= ++++ 1 file changed, 609 insertions(+) diff --git a/man/man2/move_mount.2 b/man/man2/move_mount.2 new file mode 100644 index 000000000000..6a944198f620 --- /dev/null +++ b/man/man2/move_mount.2 @@ -0,0 +1,609 @@ +.\" Copyright, the authors of the Linux man-pages project +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH move_mount 2 (date) "Linux man-pages (unreleased)" +.SH NAME +move_mount \- move or attach mount object to filesystem +.SH LIBRARY +Standard C library +.RI ( libc ,\~ \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " \ +" /* Definition of " AT_* " constants */" +.BR "#include " +.P +.BI "int move_mount(int " from_dirfd ", const char *" from_path "," +.BI " int " to_dirfd ", const char *" to_path "," +.BI " unsigned int " flags ");" +.fi +.SH DESCRIPTION +The +.BR move_mount () +system call is part of the suite of file descriptor based mount facilities +in Linux. +.P +.BR move_mount () +moves the mount object indicated by +.I from_dirfd +and +.I from_path +to the path indicated by +.I to_dirfd +and +.IR to_path . +The mount object being moved +could be an existing mount point in the current mount namespace, +or it could be a detached mount object created by +.BR fsmount (2) +or +.BR open_tree (2) +with +.BR \%OPEN_TREE_CLONE . +.P +To access the source mount object +or the destination mount point, +no permissions are required on the object itself, +but if either pathname is supplied, +execute (search) permission is required +on all of the directories specified in +.I from_path +or +.IR to_path . +.P +The calling process must have the +.BR \%CAP_SYS_ADMIN +capability in order to attach or move a mount object. +.P +As with "*at()" system calls, +.BR move_mount () +uses the +.I from_dirfd +and +.I to_dirfd +arguments +in conjunction with the +.I from_path +and +.I to_path +arguments to determine the source and destination objects to operate on +(respectively), as follows: +.IP \[bu] 3 +If the pathname given in +.I *_path +is absolute, then +the corresponding +.I *_dirfd +is ignored. +.IP \[bu] +If the pathname given in +.I *_path +is relative and +the corresponding +.I *_dirfd +is the special value +.BR AT_FDCWD , +then +.I *_path +is interpreted relative to +the current working directory +of the calling process (like +.BR open (2)). +.IP \[bu] +If the pathname given in +.I *_path +is relative, +then it is interpreted relative to +the directory referred to by +the corresponding file descriptor +.I *_dirfd +(rather than relative to +the current working directory +of the calling process, +as is done by +.BR open (2) +for a relative pathname). +In this case, +the corresponding +.I *_dirfd +must be a directory +that was opened for reading +.RB ( O_RDONLY ) +or using the +.B O_PATH +flag. +.IP \[bu] +If +.I *_path +is an empty string, +and +.I flags +contains the appropriate +.BI \%MOVE_MOUNT_ * _EMPTY_PATH +flag, +then the file descriptor referenced by +the corresponding +.I *_dirfd +is operated on directly. +In this case, +the corresponding +.I *_dirfd +can refer to any type of file, +not just a directory. +.IP +This is the most common mechanism +used to attach detached mount objects +to a mount point target. +.P +.I flags +can be used to control aspects of the path lookup +for both the source and destination objects, +as well as other properties of the mount operation. +A value for +.I flags +is constructed by bitwise ORing +zero or more of the following constants: +.RS +.TP +.B MOVE_MOUNT_F_EMPTY_PATH +If +.I from_path +is an empty string, operate on the file referred to by +.I from_dirfd +(which may have been obtained from +.BR open (2), +.BR fsmount (2), +or +.BR open_tree (2)). +In this case, +.I from_dirfd +can refer to any type of file, +not just a directory. +If +.I from_dirfd +is +.BR AT_FDCWD , +the call operates on the current working directory. +.TP +.B MOVE_MOUNT_T_EMPTY_PATH +As with +.BR \%MOVE_MOUNT_F_EMPTY_PATH , +except operating on +.IR to_dirfd " and " to_path . +.TP +.B MOVE_MOUNT_F_SYMLINKS +If +.IR from_path +references a symbolic link, +then dereference it. +The default behaviour for +.BR move_mount () +is to +.I not follow +symbolic links. +.TP +.B MOVE_MOUNT_T_SYMLINKS +As with +.BR \%MOVE_MOUNT_F_SYMLINKS , +except operating on +.I to_dirfd +and +.IR to_path . +.TP +.B MOVE_MOUNT_F_NO_AUTOMOUNT +Don't automount the terminal ("basename") component of +.I from_path +if it is a directory that is an automount point. +This allows a mount object +that has an automount point at its root +to be moved +and prevents unintended triggering of an automount point. +This flag has no effect +if the automount point has already been mounted over. +.TP +.B MOVE_MOUNT_T_NO_AUTOMOUNT +As with +.BR \%MOVE_MOUNT_F_NO_AUTOMOUNT , +except operating on +.IR to_dirfd " and " to_path . +This allows an automount point to be manually mounted over. +.TP +.BR MOVE_MOUNT_SET_GROUP " (since Linux 5.15)" +Add the attached (private) mount indicated by +.I to_dirfd +and +.I to_path +into the mount propagation "peer group" +of the attached (non-private) mount +indicated by +.IR from_dirfd " and " from_path . +.IP +Unlike other +.BR move_mount () +operations, +this operation does not move any actual mount objects. +Instead, it only updates the metadata +of existing (attached) mount objects. +.IP +This makes it possible to first create a mount tree +consisting only of private mounts +and then configure the desired propagation layout afterwards. +(See the "SHARED SUBTREES" section of +.BR mount_namespaces (7) +for more information about mount propagation and peer groups.) +.TP +.BR MOVE_MOUNT_BENEATH " (since Linux 6.5)" +If the path indicated by +.I to_dirfd +and +.I to_path +is an existing mount object, +rather than placing the mount object indicated by +.I from_dirfd +and +.I from_path +on top of the mount stack, +place it below the current top mount +on the mount stack. +.IP +After using +.BR \%MOVE_MOUNT_BENEATH , +it is possible to +.BR umount (2) +the top mount +in order to reveal the mount +which was moved beneath it earlier. +This allows for the seamless (and atomic) replacement +of intricate mount trees, +which can further be used +to "upgrade" a mount tree with a newer version. +.IP +This operation has several restrictions: +.RS +.IP \[bu] 3 +Mounts cannot be moved beneath the rootfs, +including the rootfs as configured by +.BR chroot (2) +and +.BR pivot_root (2). +To mount beneath the rootfs, +.BR pivot_root (2) +must be used. +.IP \[bu] +The target path indicated by +.I to_dirfd +and +.I to_path +must be an attached mount object. +It must not be a detached mount object given by +.BR open_tree (2) +with +.B \%OPEN_TREE_CLONE +or +.BR fsmount (2). +.IP \[bu] +The current top mount +of the target path's mount stack +and its parent mount +must be in the calling process's mount namespace. +.IP \[bu] +The caller must have sufficient privileges +to unmount the top mount +of the target path's mount stack, +to prove they have privileges +to reveal the underlying mount. +.IP \[bu] +Mount propagation events triggered by this +.BR move_mount () +operation +are calculated based on the parent mount +of the current top mount +of the target path's mount stack. +.IP \[bu] +The target path's mount +cannot be a parent mount +of the source mount object. +.IP \[bu] +The source mount object +must not have any overmounts, +otherwise it would be possible to create "shadow mounts" +(i.e., two mounts mounted on the same parent mount at the same mount point= ). +.IP \[bu] +It is not possible to move a mount +beneath a top mount +if the parent mount +of the current top mount +propagates to the top mount itself. +Otherwise, +.B \%MOVE_MOUNT_BENEATH +would cause the mount object +to be propagated +to the top mount +from the parent mount, +defeating the purpose of using +.BR \%MOVE_MOUNT_BENEATH . +.IP \[bu] +It is not possible to move a mount +beneath a top mount +if the parent mount +of the current top mount +propagates to the mount object +being mounted beneath. +Otherwise, this would cause a similar propagation issue +to the previous point, +also defeating the purpose of using +.BR \%MOVE_MOUNT_BENEATH . +.RE +.RE +.P +If +.BR move_mount () +is called repeatedly +with a file descriptor +that refers to a mount object, +then the object will be attached (or moved) +the first time +and then moved again and again, +detaching it from the previous mount point each time. +.SH RETURN VALUE +On success, +.BR move_mount () +returns 0. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EACCES +Search permission is denied +for one of the directories +in the path prefix of one of +.IR from_path " or " to_path . +(See also +.BR path_resolution (7).) +.TP +.B EBADF +One of +.I from_dirfd +or +.I to_dirfd +is not a valid file descriptor. +.TP +.B EFAULT +One of +.I from_path +or +.I to_path +is NULL +or a pointer to a location +outside the calling process's accessible address space. +.TP +.B EINVAL +Invalid flag specified in +.IR flags . +.TP +.B EINVAL +The path indicated by +.IR from_dirfd " and " from_path +is not a mount object. +.TP +.B EINVAL +The mount object type +of the source mount object and target inode +are not compatible +(i.e., the source is a file but the target is a directory, or vice-versa). +.TP +.B EINVAL +The source mount object or target path +are not in the calling process's mount namespace +(or an anonymous mount namespace of the calling process). +.TP +.B EINVAL +The source mount object's parent mount +has shared mount propagation, +and thus cannot be moved +(as described in +.BR mount_namespaces (7)). +.TP +.B EINVAL +The source mount has +.B MS_UNBINDABLE +child mounts +but the target path +resides on a mount tree with shared mount propagation, +which would otherwise cause the unbindable mounts to be propagated +(as described in +.BR mount_namespaces (7)). +.TP +.B EINVAL +.B \%MOVE_MOUNT_BENEATH +was attempted, +but one of the listed restrictions was violated. +.TP +.B ELOOP +Too many symbolic links encountered +when resolving one of +.I from_path +or +.IR to_path . +.TP +.B ENAMETOOLONG +One of +.I from_path +or +.I to_path +is longer than +.BR PATH_MAX . +.TP +.B ENOENT +A component of one of +.I from_path +or +.I to_path +does not exist. +.TP +.B ENOENT +One of +.I from_path +or +.I to_path +is an empty string, +but the corresponding +.BI MOVE_MOUNT_ * _EMPTY_PATH +flag is not specified in +.IR flags . +.TP +.B ENOTDIR +A component of the path prefix of one of +.I from_path +or +.I to_path +is not a directory, +or one of +.I from_path +or +.I to_path +is relative +and the corresponding +.I from_dirfd +or +.I to_dirfd +is a file descriptor referring to a file other than a directory. +.TP +.B ENOMEM +The kernel could not allocate sufficient memory to complete the operation. +.TP +.B EPERM +The calling process does not have the required +.B \%CAP_SYS_ADMIN +capability. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 5.2. +.\" commit 2db154b3ea8e14b04fee23e3fdfd5e9d17fbc6ae +glibc 2.36. +.SH EXAMPLES +.BR move_mount () +can be used to move attached mounts like the following: +.P +.in +4n +.EX +move_mount(AT_FDCWD, "/a", AT_FDCWD, "/b", 0); +.EE +.in +.P +This would move the mount object mounted on +.I /a +to +.IR /b . +The above procedure is functionally equivalent to +the following mount operation +using +.BR mount (2): +.P +.in +4n +.EX +mount("/a", "/b", NULL, MS_MOVE, NULL); +.EE +.in +.P +.BR move_mount () +can also be used in conjunction with file descriptors returned from +.BR open_tree (2) +or +.BR open (2): +.P +.in +4n +.EX +int fd =3D open_tree(AT_FDCWD, "/mnt", 0); /* or open("/mnt", O_PATH); */ +move_mount(fd, "", AT_FDCWD, "/mnt2", MOVE_MOUNT_F_EMPTY_PATH); +move_mount(fd, "", AT_FDCWD, "/mnt3", MOVE_MOUNT_F_EMPTY_PATH); +move_mount(fd, "", AT_FDCWD, "/mnt4", MOVE_MOUNT_F_EMPTY_PATH); +.EE +.in +.P +This would move the mount object mounted at +.I /mnt +to +.IR /mnt2 , +then +.IR /mnt3 , +then +.IR /mnt4 . +.P +If the source mount object +indicated by +.I from_dirfd +and +.I from_path +is a detached mount object, +.BR move_mount () +can be used to attach it to a mount point: +.P +.in +4n +.EX +int fsfd, mntfd; +\& +fsfd =3D fsopen("ext4", FSOPEN_CLOEXEC); +fsconfig(fsfd, FSCONFIG_SET_STRING, "source", "/dev/sda1", 0); +fsconfig(fsfd, FSCONFIG_SET_FLAG, "user_xattr", NULL, 0); +fsconfig(fsfd, FSCONFIG_CMD_CREATE, NULL, NULL, 0); +mntfd =3D fsmount(fsfd, FSMOUNT_CLOEXEC, MOUNT_ATTR_NODEV); +move_mount(mntfd, "", AT_FDCWD, "/home", MOVE_MOUNT_F_EMPTY_PATH); +.EE +.in +.P +This creates a new filesystem configuration context for ext4, +configures it, +creates a mount object, +and then attaches it to +.IR /home . +The above procedure is functionally equivalent to +the following mount operation +using +.BR mount (2): +.P +.in +4n +.EX +mount("/dev/sda1", "/home", "ext4", MS_NODEV, "user_xattr"); +.EE +.in +.P +This also works with detached bind-mounts created with +.BR open_tree (2) +with +.BR OPEN_TREE_CLONE : +.P +.in +4n +.EX +int mntfd =3D open_tree(AT_FDCWD, "/home/cyphar", OPEN_TREE_CLONE); +move_mount(mntfd, "", AT_FDCWD, "/root", MOVE_MOUNT_F_EMPTY_PATH); +.EE +.in +.P +This creates a new detached bind-mount mount object of +.IR /home/cyphar , +and then attaches it to +.IR /root . +The above procedure is functionally equivalent to +the following mount operation +using +.BR mount (2): +.P +.in +4n +.EX +mount("/home/cyphar", "/root", NULL, MS_BIND, NULL); +.EE +.in +.SH SEE ALSO +.BR fsconfig (2), +.BR fsmount (2), +.BR fsopen (2), +.BR fspick (2), +.BR mount (2), +.BR mount_setattr (2), +.BR open_tree (2), +.BR mount_namespaces (7) + --=20 2.50.1 From nobody Sun Oct 5 09:06:18 2025 Received: from mout-p-101.mailbox.org (mout-p-101.mailbox.org [80.241.56.151]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 4C58A2BEC2F; Wed, 6 Aug 2025 17:45:41 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=80.241.56.151 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1754502343; cv=none; b=kJ9/vRhheAHXRhGwO672fAZoRXQcyr06aWcMaLmtLRpGACFWAprcAKp4WHu40QvO45R0BXUGngII39ddY9/9QLAvW3ByL8CB/F1KPTrcr004Ju86+2VrAu8wJrnsNdW3fIwDLL/bV/qa3IY0eMF+4BaNfw2+ie5sqRHGAP1D9cc= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1754502343; c=relaxed/simple; bh=4ZTIn9D1X12x6PVrv/yeSTeywK9pERTHMdyG1D3Nf/o=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=R/Pjsaml7RFLFICd00fb+HTQfmqe5C7b8UMUruevdBFhii2CeyIHVJJizaQu1qclPFCtylCiQtxT7xXztqUWtxd+NoD90+7Hx4d3uUGYKu1VW1uJf4ErLTML6olT8UUPfdqRZMZSxxn9udgJqTX93wWBEJ1XPcYHFgu8hfSeC0k= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=cyphar.com; spf=pass smtp.mailfrom=cyphar.com; dkim=pass (2048-bit key) header.d=cyphar.com header.i=@cyphar.com header.b=XemyqhcY; arc=none smtp.client-ip=80.241.56.151 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=cyphar.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=cyphar.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=cyphar.com header.i=@cyphar.com header.b="XemyqhcY" Received: from smtp102.mailbox.org (smtp102.mailbox.org [IPv6:2001:67c:2050:b231:465::102]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) by mout-p-101.mailbox.org (Postfix) with ESMTPS id 4bxyPY5ypWz9tHy; Wed, 6 Aug 2025 19:45:37 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=cyphar.com; s=MBO0001; t=1754502337; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=XGG0l/ryQP/CN7FHdoYEHqi+DiEVNG8C3u5jOcNGqmI=; b=XemyqhcYqTexIWWZamMQfWk7N+QCUwd9GSGMm3LgCjKT9kDHMIsESjHaLel7OqbgugDFkb xAVBdMgKuA/rrQvWY/AUb7++R827qJyUsCVPleNS9vApFoFZbRqZ3NZwrD0ppbd63SF4vV lg66YwsFU5E6/Am1ttxnOrePNpv2AO/FUA/jKepOqGVNH4p3O1C1p7e1kfsvOREaWB/cHn QHmFKFhEU6hUNZeB7wQSB1bunUFu0DD4AoifbJf1Ewot28y5CFDEDcJy6rlbzLRbcRwacK HJEkSaO2YGUr0T5il6dAIbk2mByL7ZJCfYJMXC6awhzFzwkUiI9RHG+4/FYmdw== Authentication-Results: outgoing_mbo_mout; dkim=none; spf=pass (outgoing_mbo_mout: domain of cyphar@cyphar.com designates 2001:67c:2050:b231:465::102 as permitted sender) smtp.mailfrom=cyphar@cyphar.com From: Aleksa Sarai Date: Thu, 07 Aug 2025 03:44:42 +1000 Subject: [PATCH v2 08/11] open_tree.2: document 'new' mount api Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Message-Id: <20250807-new-mount-api-v2-8-558a27b8068c@cyphar.com> References: <20250807-new-mount-api-v2-0-558a27b8068c@cyphar.com> In-Reply-To: <20250807-new-mount-api-v2-0-558a27b8068c@cyphar.com> To: Alejandro Colomar Cc: "Michael T. Kerrisk" , Alexander Viro , Jan Kara , Askar Safin , "G. Branden Robinson" , linux-man@vger.kernel.org, linux-api@vger.kernel.org, linux-fsdevel@vger.kernel.org, linux-kernel@vger.kernel.org, David Howells , Christian Brauner , Aleksa Sarai X-Developer-Signature: v=1; a=openpgp-sha256; l=10424; i=cyphar@cyphar.com; h=from:subject:message-id; bh=4ZTIn9D1X12x6PVrv/yeSTeywK9pERTHMdyG1D3Nf/o=; b=owGbwMvMwCWmMf3Xpe0vXfIZT6slMWRMntJ+WWHijF7vPSWl+kEfXfVrvz86e61/5uFyBoOUB +p5J195dJSyMIhxMciKKbJs8/MM3TR/8ZXkTyvZYOawMoEMYeDiFICJFEkyMizctI7106+7chl2 QU8uhhT0nj5oYnOb5V5/e927eayCgfcZ/qnvSnXbo7vIvfRa96riqr8nvrdU3E+RvX/Y8Eq6vMw uEX4A X-Developer-Key: i=cyphar@cyphar.com; a=openpgp; fpr=C9C370B246B09F6DBCFC744C34401015D1D2D386 X-Rspamd-Queue-Id: 4bxyPY5ypWz9tHy This is loosely based on the original documentation written by David Howells and later maintained by Christian Brauner, but has been rewritten to be more from a user perspective (as well as fixing a few critical mistakes). Co-developed-by: David Howells Co-developed-by: Christian Brauner Signed-off-by: Aleksa Sarai --- man/man2/open_tree.2 | 405 +++++++++++++++++++++++++++++++++++++++++++++++= ++++ 1 file changed, 405 insertions(+) diff --git a/man/man2/open_tree.2 b/man/man2/open_tree.2 new file mode 100644 index 000000000000..3d38e27b5254 --- /dev/null +++ b/man/man2/open_tree.2 @@ -0,0 +1,405 @@ +.\" Copyright, the authors of the Linux man-pages project +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH open_tree 2 (date) "Linux man-pages (unreleased)" +.SH NAME +open_tree \- open path or create detached mount object and attach to fd +.SH LIBRARY +Standard C library +.RI ( libc ,\~ \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " \ +" /* Definition of " AT_* " constants */" +.BR "#include " +.P +.BI "int open_tree(int " dirfd ", const char *" path ", unsigned int " fla= gs ");" +.fi +.SH DESCRIPTION +The +.BR open_tree () +system call is part of the suite of file descriptor based mount facilities +in Linux. +.P +If +.I flags +contains +.BR \%OPEN_TREE_CLONE , +.BR open_tree () +creates a detached mount object +consisting of a bind-mount of the path +specified by the +.IR path , +and attaches it to a new file descriptor, +which is then returned. +The mount object is equivalent to a bind-mount +that would be created by +.BR mount (2) +called with +.BR MS_BIND , +except that it is tied to a file descriptor +and is not mounted onto the filesystem. +.P +As with file descriptors returned from +.BR fsmount (2), +the resultant file descriptor can then be used with +.BR move_mount (2), +.BR mount_setattr (2), +or other such system calls +to do further mount operations. +This mount object will be unmounted and destroyed +when the file descriptor is closed +if it was not otherwise attached to a mount point +by calling +.BR move_mount (2). +.P +If +.I flags +does not contain +.BR \%OPEN_TREE_CLONE , +.BR open_tree () +returns a file descriptor +that is exactly equivalent to +one produced by +.BR open (2). +.P +In either case, the resultant file descriptor +acts the same as one produced by +.BR open (2) +with +.BR O_PATH , +meaning it can also be used as a +.I dirfd +argument to +"*at()" system calls. +.P +As with "*at()" system calls, +.BR fspick () +uses the +.I dirfd +argument in conjunction with the +.I path +argument to determine the path to operate on, as follows: +.IP \[bu] 3 +If the pathname given in +.I path +is absolute, then +.I dirfd +is ignored. +.IP \[bu] +If the pathname given in +.I path +is relative and +.I dirfd +is the special value +.BR AT_FDCWD , +then +.I path +is interpreted relative to +the current working directory +of the calling process (like +.BR open (2)). +.IP \[bu] +If the pathname given in +.I path +is relative, +then it is interpreted relative to +the directory referred to by the file descriptor +.I dirfd +(rather than relative to +the current working directory +of the calling process, +as is done by +.BR open (2) +for a relative pathname). +In this case, +.I dirfd +must be a directory +that was opened for reading +.RB ( O_RDONLY ) +or using the +.B O_PATH +flag. +.IP \[bu] +If +.I path +is an empty string, +and +.I flags +contains +.BR \%AT_EMPTY_PATH , +then the file descriptor referenced by +.I dirfd +is operated on directly. +In this case, +.I dirfd +can refer to any type of file, +not just a directory. +.P +.I flags +can be used to control aspects of the path lookup +and properties of the returned file descriptor. +A value for +.I flags +is constructed by bitwise ORing +zero or more of the following constants: +.RS +.TP +.B AT_EMPTY_PATH +If +.I path +is an empty string, operate on the file referred to by +.I dirfd +(which may have been obtained from +.BR open (2), +.BR fsmount(2), +or from another +.BR open_tree () +call). +In this case, +.I dirfd +can refer to any type of file, not just a directory. +If +.I dirfd +is +.BR AT_FDCWD , +the call operates on the current working directory +of the calling process. +This flag is Linux-specific; define +.B \%_GNU_SOURCE +to obtain its definition. +.TP +.B AT_NO_AUTOMOUNT +Don't automount the terminal ("basename") component of +.I path +if it is a directory that is an automount point. +This allows the caller to gather attributes of an automount point +(rather than the location it would mount). +This flag has no effect if the mount point has already been mounted over. +This flag is Linux-specific; define +.B \%_GNU_SOURCE +to obtain its definition. +.TP +.B AT_SYMLINK_NOFOLLOW +If +.I path +is a symbolic link, do not dereference it; instead, +create either a handle to the link itself +or a bind-mount of it. +The resultant file descriptor is indistinguishable from one produced by +.BR openat (2) +with +.BR \%O_PATH | O_NOFOLLLOW . +.TP +.B OPEN_TREE_CLOEXEC +Set the close-on-exec +.RB ( FD_CLOEXEC ) +flag on the new file descriptor. +See the description of the +.B O_CLOEXEC +flag in +.BR open (2) +for reasons why this may be useful. +.TP +.B OPEN_TREE_CLONE +Rather than opening the path as a regular file +(a-la +.BR openat (2)), +create a detached bind-mount mount object +and attach it to the file descriptor. +In order to do this operation, +the calling process must have the +.BR \%CAP_SYS_ADMIN +capability. +.TP +.B AT_RECURSIVE +Create a recursive bind-mount of the path +(a-la +.BR mount (2) +with +.BR MS_BIND | MS_REC ), +and attach it to the file descriptor. +This flag is only permitted in conjunction with +.BR \%OPEN_TREE_CLONE . +.SH RETURN VALUE +On success, a new file descriptor is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EACCES +Search permission is denied for one of the directories +in the path prefix of +.IR path . +(See also +.BR path_resolution (7).) +.TP +.B EPERM +.I flags +contains +.B \%OPEN_TREE_CLONE +but the calling process does not have the required +.B CAP_SYS_ADMIN +capability. +.TP +.B EBADF +.I path +is relative but +.I dirfd +is neither +.B AT_FDCWD +nor a valid file descriptor. +.TP +.B EFAULT +.I path +is NULL +or a pointer to a location +outside the calling process's accessible address space. +.TP +.B EINVAL +Invalid flag specified in +.IR flags . +.TP +.B ELOOP +Too many symbolic links encountered when resolving +.IR path . +.TP +.B ENAMETOOLONG +.I path +is longer than +.BR PATH_MAX . +.TP +.B ENOENT +A component of +.I path +does not exist, or is a dangling symbolic link. +.TP +.B ENOENT +.I path +is an empty string, but +.B AT_EMPTY_PATH +is not specified in +.IR flags . +.TP +.B ENOTDIR +A component of the path prefix of +.I path +is not a directory, or +.I path +is relative and +.I dirfd +is a file descriptor referring to a file other than a directory. +.TP +.B ENOSPC +The "anonymous" mount namespace +necessary to contain the +.B \%OPEN_TREE_CLONE +detached bind-mount mount object +could not be allocated, +as doing so would +exceed the configured per-user limit +on the number of mount namespaces +in the current user namespace. +(See also +.BR namespaces (7).) +.TP +.B ENOMEM +The kernel could not allocate sufficient memory to complete the operation. +.TP +.B EMFILE +The calling process has too many open files to create more. +.TP +.B ENFILE +The system has too many open files to create more. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 5.2. +.\" commit a07b20004793d8926f78d63eb5980559f7813404 +glibc 2.36. +.SH NOTES +.SS Anonymous mount namespaces +The bind-mount mount objects created by +.BR open_tree () +with +.B \%OPEN_TREE_CLONE +are not attached to the mount namespace of the calling process. +Instead, each mount object is attached to +a newly allocated "anonymous" mount namespace +associated with the calling process. +.P +One of the side-effects of this is that +(unlike bind-mounts created with +.BR mount (2)), +mount propagation +(as described in +.BR mount_namespaces (7)) +will not be applied to bind-mounts created by +.BR open_tree () +until the bind-mount is attached with +.BR move_mount (2), +at which point the mount +will be associated with the mount namespace +where it was mounted +and mount propagation will resume. +.SH EXAMPLES +The following examples show how +.BR open_tree () +can be used in place of more traditional +.BR mount (2) +calls with +.BR MS_BIND . +.P +.in +4n +.EX +int srcfd; +\& +/* mount --bind /var /mnt */ +mount("/var", "/mnt", NULL, MS_BIND, NULL); +/* ... is equivalent to ... */ +srcfd =3D open_tree(AT_FDCWD, "/var", OPEN_TREE_CLONE); +move_mount(srcfd, "", AT_FDCWD, "/mnt", MOVE_MOUNT_F_EMPTY_PATH); +\& +/* mount --rbind /var /mnt */ +mount("/var", "/mnt", NULL, MS_BIND|MS_REC, NULL); +/* ... is equivalent to ... */ +srcfd =3D open_tree(AT_FDCWD, "/var", OPEN_TREE_CLONE | AT_RECURSIVE); +move_mount(srcfd, "", AT_FDCWD, "/mnt", MOVE_MOUNT_F_EMPTY_PATH); +\& +/* mount --bind /proc/self/fd/100 /proc/self/fd/200/foo */ +mount("/proc/self/fd/100", "/proc/self/fd/200/foo", NULL, MS_BIND, NULL); +/* ... is equivalent to ... */ +srcfd =3D open_tree(100, "", AT_EMPTY_PATH | OPEN_TREE_CLONE); +move_mount(srcfd, "", 200, "foo", MOVE_MOUNT_F_EMPTY_PATH); +.EE +.in +.P +In addition, you can use the file descriptor returned by +.BR open_tree () +as the +.I dirfd +argument to any "*at()" system calls: +.P +.in +4n +.EX +int dirfd, fd; +\& +dirfd =3D open_tree(AT_FDCWD, "/etc", OPEN_TREE_CLONE); +fd =3D openat(dirfd, "passwd", O_RDONLY); +fchmodat(dirfd, "shadow", 0000, 0); +close(dirfd); +close(fd); +/* The bind-mount is now destroyed. */ +.EE +.in +.SH SEE ALSO +.BR fsconfig (2), +.BR fsmount (2), +.BR fsopen (2), +.BR fspick (2), +.BR mount (2), +.BR mount_setattr (2), +.BR move_mount (2), +.BR mount_namespaces (7) --=20 2.50.1 From nobody Sun Oct 5 09:06:18 2025 Received: from mout-p-202.mailbox.org (mout-p-202.mailbox.org [80.241.56.172]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 6EBF32BEFE9; Wed, 6 Aug 2025 17:45:47 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=80.241.56.172 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1754502348; cv=none; b=PyHoIT60GtP/G6YTZyxWdpr6/ppfuQu9w5UlCIrKmGq+8Y06Vn4tknPOHSyuAaEXqw1yJQp0su5WtcBT2cLmL76uPZQaCFBLQPwnjEBqvtLD6Oc+3WHvf6D4jfmjtoUaqT1HA9pDzlYWoDzutFnX3q5Xp7cqMPaBjlc9sg+15Ys= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1754502348; c=relaxed/simple; bh=RDJQO007ERabTkgl/PrzfQjR8d5XxCqa8xKNU89DqCo=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=iRcNpa4hUBTn8/ksd0Amt1wp8zVCLJDNDvOXEGg4EIdKz+8wrbQByShXz7rfUDPtjwZWGO7Om+83eeE9V6830Q9DGXnPPMRoxPDPXfldKYixDdZ+Bi9HjI+zaO9APL5/pJ+nf2fnMwgnUTfmk7UGd5vOlqjBLYYrZj19MRV5Xm0= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=cyphar.com; spf=pass smtp.mailfrom=cyphar.com; dkim=pass (2048-bit key) header.d=cyphar.com header.i=@cyphar.com header.b=CIboG/jz; arc=none smtp.client-ip=80.241.56.172 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=cyphar.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=cyphar.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=cyphar.com header.i=@cyphar.com header.b="CIboG/jz" Received: from smtp102.mailbox.org (smtp102.mailbox.org [IPv6:2001:67c:2050:b231:465::102]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) by mout-p-202.mailbox.org (Postfix) with ESMTPS id 4bxyPg6DNWz9sqy; Wed, 6 Aug 2025 19:45:43 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=cyphar.com; s=MBO0001; t=1754502343; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=LBWNR74Nu1rSft9Gxex91tgUE5zJxVh5493aLPxeGcw=; b=CIboG/jz3nvHCTnsZUfUjATDr/Bru0eB8Fg5iLBYdSHPeQKIh5AxEkTSpEOnJR56hespM7 ZBmwIDA6RrdlQx/AFb33vKvMB/KsncvUyQXwpUst9UGcYrO/6B35madSsOkAHbK06msbNw S9KbaqvDWohllx3akkuuYw3ILt2xsj7kr+XgzWNtkS++PXBX7yAwXQA9+OXrw3IKLW1QbT yTItwUiw72pNZn/5D/Xdz1+hXDiDIC6kQqIbuX7hSXXo3AZXcDMh3437QA7z1sBUuJrWo2 m38jHvsas/vi2I1Ub+eM4Kv38PrRIBnrbL6GjJjaYOn3bYNgLCMTP5Uh+Px8+w== Authentication-Results: outgoing_mbo_mout; dkim=none; spf=pass (outgoing_mbo_mout: domain of cyphar@cyphar.com designates 2001:67c:2050:b231:465::102 as permitted sender) smtp.mailfrom=cyphar@cyphar.com From: Aleksa Sarai Date: Thu, 07 Aug 2025 03:44:43 +1000 Subject: [PATCH v2 09/11] mount_setattr.2: mirror opening sentence from fsopen(2) Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Message-Id: <20250807-new-mount-api-v2-9-558a27b8068c@cyphar.com> References: <20250807-new-mount-api-v2-0-558a27b8068c@cyphar.com> In-Reply-To: <20250807-new-mount-api-v2-0-558a27b8068c@cyphar.com> To: Alejandro Colomar Cc: "Michael T. Kerrisk" , Alexander Viro , Jan Kara , Askar Safin , "G. Branden Robinson" , linux-man@vger.kernel.org, linux-api@vger.kernel.org, linux-fsdevel@vger.kernel.org, linux-kernel@vger.kernel.org, David Howells , Christian Brauner , Aleksa Sarai X-Developer-Signature: v=1; a=openpgp-sha256; l=970; i=cyphar@cyphar.com; h=from:subject:message-id; bh=RDJQO007ERabTkgl/PrzfQjR8d5XxCqa8xKNU89DqCo=; b=owGbwMvMwCWmMf3Xpe0vXfIZT6slMWRMntKeunVS6Ln/6/52aHV4XJx5duXCg3muL16maXC75 gpUqVxo6ShlYRDjYpAVU2TZ5ucZumn+4ivJn1aywcxhZQIZwsDFKQATsXnH8D86V5SVd89uqY82 K7K2S7yuN6gKXiTtVDHrVvYc17I3p7QY/ocFyeTqPf3itKVKkX3VpWox1olOIb9+B7yqc57kb64 2kRsA X-Developer-Key: i=cyphar@cyphar.com; a=openpgp; fpr=C9C370B246B09F6DBCFC744C34401015D1D2D386 X-Rspamd-Queue-Id: 4bxyPg6DNWz9sqy All of the other new mount API docs have this lead-in sentence in order to make this set of APIs feel a little bit more cohesive. Despite being a bit of a latecomer, mount_setattr(2) is definitely part of this family of APIs and so deserves the same treatment. Signed-off-by: Aleksa Sarai --- man/man2/mount_setattr.2 | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/man/man2/mount_setattr.2 b/man/man2/mount_setattr.2 index d44fafc93a20..b9afc21035b8 100644 --- a/man/man2/mount_setattr.2 +++ b/man/man2/mount_setattr.2 @@ -19,7 +19,11 @@ .SH SYNOPSIS .SH DESCRIPTION The .BR mount_setattr () -system call changes the mount properties of a mount or an entire mount tre= e. +system call is part of the suite of file descriptor based mount facilities +in Linux. +.P +.BR mount_setattr () +changes the mount properties of a mount or an entire mount tree. If .I path is relative, --=20 2.50.1 From nobody Sun Oct 5 09:06:18 2025 Received: from mout-p-101.mailbox.org (mout-p-101.mailbox.org [80.241.56.151]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 7618F2BF009; Wed, 6 Aug 2025 17:45:53 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=80.241.56.151 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1754502355; cv=none; b=AHJt69o5f8JdJps2SZI7zBfT0DLnjFbeuIxHzPiz4oMmZ2mZPtlgo9hjvaFPQpZqQ9uBpDtkjp15DkaR0ccuiNMPHB9gAH8EOpy6zjMRQaKTlceAL1qy5aazVwMPOha7fS/bmVksB9/ZoNBM+wOkqveNAlHJ7w9IFV4pRURtZo8= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1754502355; c=relaxed/simple; bh=88pixLZilCbLz/yjfDYQoTyUZ5ObBDDeN1zdu4FRdNI=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=AWtMmx7xgyxneEiokrpClkQJX8SVK/T0YsoFWtf6I4S0KVdYCZF60J9vidDPqE27hWicdtsuRAlynOYfRxKR2FOgF6C8WkBANVsnLUxMxdHjYqYRWRXFDTYRGDZTQPx0RpfYHBk6G3UH2L3w9FUUwtea/Pp4eJDSjPEgsL1xsEY= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=cyphar.com; spf=pass smtp.mailfrom=cyphar.com; dkim=pass (2048-bit key) header.d=cyphar.com header.i=@cyphar.com header.b=jhTAtbyw; arc=none smtp.client-ip=80.241.56.151 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=cyphar.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=cyphar.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=cyphar.com header.i=@cyphar.com header.b="jhTAtbyw" Received: from smtp102.mailbox.org (smtp102.mailbox.org [IPv6:2001:67c:2050:b231:465::102]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) by mout-p-101.mailbox.org (Postfix) with ESMTPS id 4bxyPp0T0nz9t80; Wed, 6 Aug 2025 19:45:50 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=cyphar.com; s=MBO0001; t=1754502350; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=j+MX4/TVRSIyTRewqaveai9CyOrf1mx+NDItuqJPG/w=; b=jhTAtbywriLs41Suas6vpFfmC29X5P4NiluYw9S6NmEf3Q0sHWt3rrlp18ohsvXpFYxcKC 4zFIibL1yg2/BCaQPqMkA32XldoP7WIXtzOt8+UaTAll8SDTGxMgwTr0RspVjquxJJLCF5 VcY8bGghzzBXQWsyLrv0h4z2TOeFicvHhcZ9pZ41105WA9LpwqIGQdxch4Sg7mFC+7+VP5 gXegQkRwWCC5VasW0LLr3F8gRxHezCcFXY+23NHCbKeQ/c1JCUiZWCjY2VAGWlyKho7cUD 1ouuV1ZDfewhwCv2/xxFYzCYtgjoGN75eKaPFOiY980FbQWv+REBWqun8B43dw== Authentication-Results: outgoing_mbo_mout; dkim=none; spf=pass (outgoing_mbo_mout: domain of cyphar@cyphar.com designates 2001:67c:2050:b231:465::102 as permitted sender) smtp.mailfrom=cyphar@cyphar.com From: Aleksa Sarai Date: Thu, 07 Aug 2025 03:44:44 +1000 Subject: [PATCH v2 10/11] open_tree_attr.2, open_tree.2: document new open_tree_attr() api Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Message-Id: <20250807-new-mount-api-v2-10-558a27b8068c@cyphar.com> References: <20250807-new-mount-api-v2-0-558a27b8068c@cyphar.com> In-Reply-To: <20250807-new-mount-api-v2-0-558a27b8068c@cyphar.com> To: Alejandro Colomar Cc: "Michael T. Kerrisk" , Alexander Viro , Jan Kara , Askar Safin , "G. Branden Robinson" , linux-man@vger.kernel.org, linux-api@vger.kernel.org, linux-fsdevel@vger.kernel.org, linux-kernel@vger.kernel.org, David Howells , Christian Brauner , Aleksa Sarai X-Developer-Signature: v=1; a=openpgp-sha256; l=3539; i=cyphar@cyphar.com; h=from:subject:message-id; bh=88pixLZilCbLz/yjfDYQoTyUZ5ObBDDeN1zdu4FRdNI=; b=owGbwMvMwCWmMf3Xpe0vXfIZT6slMWRMntJuMf1j3Ydzv/o2X0lcwDBpHdOFarFlSUeP+waus 2f5prDxWUcpC4MYF4OsmCLLNj/P0E3zF19J/rSSDWYOKxPIEAYuTgGYSIs/I8PfT1YfrLO3sy5Y v8Qnq6xMZJnx7OTSGSfWrvqTI3jRONCc4Q/nZ41F8/ume/szrFI2r8mwje175pV4XPiHJ++fP9L vdLgA X-Developer-Key: i=cyphar@cyphar.com; a=openpgp; fpr=C9C370B246B09F6DBCFC744C34401015D1D2D386 X-Rspamd-Queue-Id: 4bxyPp0T0nz9t80 This is a new API added in Linux 6.15, and is effectively just a minor expansion of open_tree(2) in order to allow for MOUNT_ATTR_IDMAP to be changed for an existing ID-mapped mount. Glibc does not yet have a wrapper for this. Cc: Christian Brauner Signed-off-by: Aleksa Sarai --- man/man2/open_tree.2 | 74 +++++++++++++++++++++++++++++++++++++++++++= ++++ man/man2/open_tree_attr.2 | 1 + 2 files changed, 75 insertions(+) diff --git a/man/man2/open_tree.2 b/man/man2/open_tree.2 index 3d38e27b5254..6e7ec4998d42 100644 --- a/man/man2/open_tree.2 +++ b/man/man2/open_tree.2 @@ -15,7 +15,19 @@ .SH SYNOPSIS .BR "#include " .P .BI "int open_tree(int " dirfd ", const char *" path ", unsigned int " fla= gs ");" +.P +.BR "#include " " /* Definition of " SYS_* " constants *= /" +.P +.BI "int syscall(SYS_open_tree_attr, int " dirfd ", const char *" path "," +.BI " unsigned int " flags ", struct mount_attr *" attr ", \ +size_t " size ");" .fi +.P +.IR Note : +glibc provides no wrapper for +.BR open_tree_attr (), +necessitating the use of +.BR syscall (2). .SH DESCRIPTION The .BR open_tree () @@ -222,6 +234,64 @@ .SH DESCRIPTION and attach it to the file descriptor. This flag is only permitted in conjunction with .BR \%OPEN_TREE_CLONE . +.SS open_tree_attr() +The +.BR open_tree_attr () +system call operates in exactly the same way as +.BR open_tree (), +except for the differences described here. +.P +After performing the same operation as with +.BR open_tree (), +(before returning the resulting file descriptor) +.BR open_tree_attr () +will apply the mount attributes requested in +.I attr +to the mount object. +(See +.BR mount_attr (2type) +for a description of the +.I mount_attr +structure. +As described in +.BR mount_setattr (2), +.I size +must be set to +.I sizeof(struct mount_attr) +in order to support future extensions.) +.P +For the most part, the application of +.I attr +has identical semantics to +.BR mount_setattr (2), +except that it is possible to change the +.B \%MOUNT_ATTR_IDMAP +attribute for a mount object +that is already configured as an ID-mapped mount. +This is usually forbidden by +.BR mount_setattr (2) +and thus +.BR open_tree_attr () +is currently the only permitted mechanism to change this attribute. +Changing an ID-mapped mount is only permitted +if a new detached mount object is being created with +.I flags +including +.BR \%OPEN_TREE_CLONE . +.P +If +.I flags +contains +.BR \%AT_RECURSIVE , +then the attributes are applied recursively +(just as when +.BR mount_setattr (2) +is called with +.BR \%AT_RECURSIVE ). +This applies in addition to the +.BR open_tree ()-specific +behaviour regarding +.BR \%AT_RECURSIVE . .SH RETURN VALUE On success, a new file descriptor is returned. On error, \-1 is returned, and @@ -316,9 +386,13 @@ .SH ERRORS .SH STANDARDS Linux. .SH HISTORY +.SS open_tree() Linux 5.2. .\" commit a07b20004793d8926f78d63eb5980559f7813404 glibc 2.36. +.SS open_tree_attr() +Linux 6.15. +.\" commit c4a16820d90199409c9bf01c4f794e1e9e8d8fd8 .SH NOTES .SS Anonymous mount namespaces The bind-mount mount objects created by diff --git a/man/man2/open_tree_attr.2 b/man/man2/open_tree_attr.2 new file mode 100644 index 000000000000..e57269bbd269 --- /dev/null +++ b/man/man2/open_tree_attr.2 @@ -0,0 +1 @@ +.so man2/open_tree.2 --=20 2.50.1 From nobody Sun Oct 5 09:06:18 2025 Received: from mout-p-101.mailbox.org (mout-p-101.mailbox.org [80.241.56.151]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id A6D532BFC9B; Wed, 6 Aug 2025 17:45:59 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=80.241.56.151 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1754502362; cv=none; b=QYwFByM0ZdIdRBtZASNXDJop/IMHFQgLrjgXXfV1rS3ghCSX231j5WdG7jOwfq78DW69LOoW9tQ8DxtBD+xlqb+al570RSeQiEtG26io/6hPAWL24in1nf8MvI4EYBM352qanBJgekJ4x4rGmbfWA998q8vIELbfGo+VuEO4ZYo= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1754502362; c=relaxed/simple; bh=PA7loxIPBLGOhG+xaEAeoYFr7UKxY5keNiex8tkAodM=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=iqQYyAXdd2ODyGcFXeQkXxplcXBD2IM29ATDdLephOpahD69cq6bbZ4YyywuGGFCvRxWJZ+CfK2dkM8j7ncHp4j505ke80YO6989qSVtRJJQOU+QGbeoioeRzqabnRDAzYXZEQt4Ad0W8xc35h7CfNikV58U5pbXhTdvTtqv8XA= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=cyphar.com; spf=pass smtp.mailfrom=cyphar.com; dkim=pass (2048-bit key) header.d=cyphar.com header.i=@cyphar.com header.b=vfoKcSgz; arc=none smtp.client-ip=80.241.56.151 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=cyphar.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=cyphar.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=cyphar.com header.i=@cyphar.com header.b="vfoKcSgz" Received: from smtp102.mailbox.org (smtp102.mailbox.org [10.196.197.102]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) by mout-p-101.mailbox.org (Postfix) with ESMTPS id 4bxyPw1FZhz9snx; Wed, 6 Aug 2025 19:45:56 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=cyphar.com; s=MBO0001; t=1754502356; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=2YYCu5R1XiGIudL58R408XKwHqQ+bXkM+6ufvf1daHo=; b=vfoKcSgzG6rLa0oQk5oIFzsv/K/YkgPlfIhc5iZKQ43Doy2DR91KiJtbyDN0tKnwdjUjbt QkH+E3cGpcefF3pIEKKBRhn2nLRIzcMQH2gF5rhD99T0ZB8XjetqtjMAkvyu7/WBDiHtHQ Egw5eFq1g12a79/rdtYACxRkEiwMIwkg+Ojcn/wlB03zZS9Ztxt+3rFNFd7lavuR6ChS+t 2s3Z5F8Y1mMxmJOUvA4Cchln8SUQ4rdLMrpCJe5VtXnkT71EKZsj7CFihodVL8Y0mlXeQd UFkVrFQJSn1gxjIfi1SakBDbbqtmcxzDTkqnHOdPL+lPvsFAGZVCbj0rMGvv7g== From: Aleksa Sarai Date: Thu, 07 Aug 2025 03:44:45 +1000 Subject: [PATCH v2 11/11] fsconfig.2, mount_setattr.2: add note about attribute-parameter distinction Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Message-Id: <20250807-new-mount-api-v2-11-558a27b8068c@cyphar.com> References: <20250807-new-mount-api-v2-0-558a27b8068c@cyphar.com> In-Reply-To: <20250807-new-mount-api-v2-0-558a27b8068c@cyphar.com> To: Alejandro Colomar Cc: "Michael T. Kerrisk" , Alexander Viro , Jan Kara , Askar Safin , "G. Branden Robinson" , linux-man@vger.kernel.org, linux-api@vger.kernel.org, linux-fsdevel@vger.kernel.org, linux-kernel@vger.kernel.org, David Howells , Christian Brauner , Aleksa Sarai X-Developer-Signature: v=1; a=openpgp-sha256; l=2475; i=cyphar@cyphar.com; h=from:subject:message-id; bh=PA7loxIPBLGOhG+xaEAeoYFr7UKxY5keNiex8tkAodM=; b=owGbwMvMwCWmMf3Xpe0vXfIZT6slMWRMntKxe6X44h89CyT2NLpaf9kTt+BQ6cL8H5sjrL3+s fzOXy8g3lHKwiDGxSArpsiyzc8zdNP8xVeSP61kg5nDygQyhIGLUwAm0tnP8Ifb2m9NzMTFEd+E d6y4/ELkS4SjctPn1S67t3y5enBC1/d5jAyP+U1YK34tkpKfl1+sfuMP16SjivO5FS1WJqYZLne ZxsgCAA== X-Developer-Key: i=cyphar@cyphar.com; a=openpgp; fpr=C9C370B246B09F6DBCFC744C34401015D1D2D386 This was not particularly well documented in mount(8) nor mount(2), and since this is a fairly notable aspect of the new mount API, we should probably add some words about it. Signed-off-by: Aleksa Sarai --- man/man2/fsconfig.2 | 7 +++++++ man/man2/mount_setattr.2 | 37 +++++++++++++++++++++++++++++++++++++ 2 files changed, 44 insertions(+) diff --git a/man/man2/fsconfig.2 b/man/man2/fsconfig.2 index e2121b7a6b68..9e0e25acff3b 100644 --- a/man/man2/fsconfig.2 +++ b/man/man2/fsconfig.2 @@ -448,6 +448,13 @@ .SH HISTORY Linux 5.2. .\" commit ecdab150fddb42fe6a739335257949220033b782 glibc 2.36. +.SH NOTES +.SS Mount attributes and filesystem parameters +For a description of the distinction between +mount attributes and filesystem parameters, +see the "Mount attributes and filesystem paramers" subsection +of +.BR mount_setattr (2). .SH EXAMPLES To illustrate the different kinds of flags that can be configured with .BR fsconfig (), diff --git a/man/man2/mount_setattr.2 b/man/man2/mount_setattr.2 index b9afc21035b8..3e6b59e5b57a 100644 --- a/man/man2/mount_setattr.2 +++ b/man/man2/mount_setattr.2 @@ -790,6 +790,43 @@ .SS ID-mapped mounts .BR chown (2) system call changes the ownership globally and permanently. .\" +.SS Mount attributes and filesystem parameters +Some mount attributes +(traditionally associated with +.BR mount (8)-style +options) +are also filesystem parameters. +For example, the +.I -o ro +option to +.BR mount (8) +can refer to the +"read-only" filesystem parameter, +or the "read-only" mount attribute. +.P +The distinction between these two kinds of option is that +mount object attributes are applied per-mount-object +(allowing different mount objects +derived from a given filesystem instance +to have different attributes), +while filesystem instance parameters +("superblock flags" in kernel developer parlance) +apply to all mount objects +derived from the same filesystem instance. +.P +When using +.BR mount (2), +the line between these two types of mount options was blurred. +However, with +.BR mount_setattr () +and +.BR fsconfig (2), +the distinction is made much clearer. +Mount attributes are configured with +.BR mount_setattr (), +while filesystem parameters can be configured using +.BR fsconfig (2). +.\" .SS Extensibility In order to allow for future extensibility, .BR mount_setattr () --=20 2.50.1