[PATCH] name_to_handle_at.2: Document the AT_HANDLE_CONNECTABLE flag

[PATCH] name_to_handle_at.2: Document the AT_HANDLE_CONNECTABLE flag

[Amir Goldstein]

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.

Signed-off-by: Amir Goldstein <amir73il@gmail.com>
---
 man/man2/open_by_handle_at.2 | 31 ++++++++++++++++++++++++++++++-
 1 file changed, 30 insertions(+), 1 deletion(-)

diff --git a/man/man2/open_by_handle_at.2 b/man/man2/open_by_handle_at.2
index 6b9758d42..ce3a2cec8 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,29 @@ with the returned
 .I file_handle
 may fail.
 .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
+.BR AT_HANDLE_FID ,
+and
+.BR AT_EMPTY_PATH .
+.P
 Together, the
 .I pathname
 and
@@ -311,7 +335,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 +422,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

Re: [PATCH] name_to_handle_at.2: Document the AT_HANDLE_CONNECTABLE flag

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 2833 bytes --]

Hi Amir,

On Sun, Mar 30, 2025 at 01:16:43PM +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.
> 
> Signed-off-by: Amir Goldstein <amir73il@gmail.com>

Please add explicit CC tags for everyone CCd.

> ---
>  man/man2/open_by_handle_at.2 | 31 ++++++++++++++++++++++++++++++-
>  1 file changed, 30 insertions(+), 1 deletion(-)
> 
> diff --git a/man/man2/open_by_handle_at.2 b/man/man2/open_by_handle_at.2
> index 6b9758d42..ce3a2cec8 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,29 @@ with the returned
>  .I file_handle
>  may fail.
>  .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/*

Literal parts of a path name should be in italics, but variable parts
should be in roman.  Thus:

	.IR /proc/ pid /fd/ *

> +magic link.
> +This flag can not be used in combination with the flags
> +.BR AT_HANDLE_FID ,

for only two items, we don't need a comma here.  It's for three or more
items, that Oxford comma applies.

> +and

Maybe it's better to say 'and/or'?  Otherwise, one may wonder if
combining with only one of those but not both may be valid?


Have a lovely day!
Alex

> +.BR AT_EMPTY_PATH .
> +.P
>  Together, the
>  .I pathname
>  and
> @@ -311,7 +335,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 +422,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/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]