name_to_handle_at.2: Document the AT_HANDLE_CONNECTABLE flag

PATCH Superseded Amir Goldstein 2 participants 2 messages Mar 30, 2025

Subsystems (2)

VFS Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore

Share & tools

lore

Amir Goldstein

author

2025-03-30 11:16 UTC #0 lore raw

PATCH 1/1 name_to_handle_at.2: Document the AT_HANDLE_CONNECTABLE flag

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 <[email protected]>

---
 man/man2/open_by_handle_at.2 | 31 ++++++++++++++++++++++++++++++-
 1 file changed, 30 insertions(+), 1 deletion(-)

man/man2/open_by_handle_at.2 +30 -1

index 6b9758d42..ce3a2cec8 100644
@@ -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 ()

Signature · 1 line

2.34.1

Alejandro Colomar

maintainer

2025-03-30 11:58 UTC #1 lore raw

Hi Amir,

Quoted 5 lines · 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 <[email protected]>

Please add explicit CC tags for everyone CCd.

Quoted 27 lines

---
 man/man2/open_by_handle_at.2 | 31 ++++++++++++++++++++++++++++++-
 1 file changed, 30 insertions(+), 1 deletion(-)

man/man2/open_by_handle_at.2 +8 -0

index 6b9758d42..ce3a2cec8 100644
@@ -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

man/man2/open_by_handle_at.2 with the returned · line 167

Quoted 10 lines

man/man2/open_by_handle_at.2 +10 -0

+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/ *

man/man2/open_by_handle_at.2 with the returned · line 170

Quoted 3 lines

man/man2/open_by_handle_at.2 +3 -0

+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.

man/man2/open_by_handle_at.2 with the returned · line 171

Quoted 1 line

man/man2/open_by_handle_at.2 +1 -0
+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

Quoted 29 lines

man/man2/open_by_handle_at.2 +8 -1

+.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 ()

Signature · 1 line

2.34.1

Signature · 1 line

<https://www.alejandro-colomar.es/>