Re: [PATCH v2] name_to_handle_at.2: Document the AT_HANDLE_CONNECTABLE flag
From: Alejandro Colomar <alx@kernel.org>
Date: 2025-03-30 17:56:39
Also in:
linux-fsdevel
Hi Amir, On Sun, Mar 30, 2025 at 06:35:02PM +0200, Amir Goldstein wrote:
A flag since v6.13 to indicate that the requested file_handle is intended to be used for open_by_handle_at(2) to obtain an open file with a known path. Cc: Chuck Lever <chuck.lever@oracle.com> Cc: Jeff Layton <redacted> Cc: Christian Brauner <brauner@kernel.org> Cc: Jan Kara <jack@suse.cz> Cc: Aleksa Sarai <redacted> Signed-off-by: Amir Goldstein <amir73il@gmail.com> --- Alejandro, Addressed your comments from v1 and added missing documentation for AT_HANDLE_MNT_ID_UNIQUE from v6.12.
Please split AT_HANDLE_MNT_ID_UNIQUE into a separate patch, possibly in the same patch set. Other than that, it LGTM. Thanks! Cheers, Alex
quoted hunk ↗ jump to hunk
Thanks, Amir. man/man2/open_by_handle_at.2 | 46 +++++++++++++++++++++++++++++++++++- 1 file changed, 45 insertions(+), 1 deletion(-)diff --git a/man/man2/open_by_handle_at.2 b/man/man2/open_by_handle_at.2 index 6b9758d42..10af60a76 100644 --- a/man/man2/open_by_handle_at.2 +++ b/man/man2/open_by_handle_at.2@@ -127,6 +127,7 @@ The .I flags argument is a bit mask constructed by ORing together zero or more of .BR AT_HANDLE_FID , +.BR AT_HANDLE_CONNECTABLE, .BR AT_EMPTY_PATH , and .BR AT_SYMLINK_FOLLOW ,@@ -147,6 +148,44 @@ with the returned .I file_handle may fail. .P +When +.I flags +contain the +.BR AT_HANDLE_MNT_ID_UNIQUE " (since Linux 6.12)" +.\" commit 4356d575ef0f39a3e8e0ce0c40d84ce900ac3b61 +flag, the caller indicates that the size of the +.I mount_id +buffer is at least 64bit +and then the mount id returned in that buffer +is the unique mount id as the one returned by +.BR statx (2) +with the +.BR STATX_MNT_ID_UNIQUE +flag. +.P +When +.I flags +contain the +.BR AT_HANDLE_CONNECTABLE " (since Linux 6.13)" +.\" commit a20853ab8296d4a8754482cb5e9adde8ab426a25 +flag, the caller indicates that the returned +.I file_handle +is needed to open a file with known path later, +so it should be expected that a subsequent call to +.BR open_by_handle_at () +with the returned +.I file_handle +may fail if the file was moved, +but otherwise, +the path of the opened file is expected to be visible +from the +.IR /proc/ pid /fd/ * +magic link. +This flag can not be used in combination with the flags +.B AT_HANDLE_FID +and/or +.BR AT_EMPTY_PATH . +.P Together, the .I pathname and@@ -311,7 +350,7 @@ points outside your accessible address space. .TP .B EINVAL .I flags -includes an invalid bit value. +includes an invalid bit value or an invalid bit combination. .TP .B EINVAL .I handle\->handle_bytes@@ -398,6 +437,11 @@ was acquired using the .B AT_HANDLE_FID flag and the filesystem does not support .BR open_by_handle_at (). +This error can also occur if the +.I handle +was acquired using the +.B AT_HANDLE_CONNECTABLE +flag and the file was moved to a different parent. .SH VERSIONS FreeBSD has a broadly similar pair of system calls in the form of .BR getfh ()-- 2.34.1
-- <https://www.alejandro-colomar.es/>
Attachments
- signature.asc [application/pgp-signature] 833 bytes