diff mbox series

[v2] name_to_handle_at.2: Document the AT_HANDLE_CONNECTABLE flag

Message ID 20250330163502.1415011-1-amir73il@gmail.com (mailing list archive)
State New
Headers show
Series [v2] name_to_handle_at.2: Document the AT_HANDLE_CONNECTABLE flag | expand

Commit Message

Amir Goldstein March 30, 2025, 4:35 p.m. UTC 
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 <jlayton@poochiereds.net>
Cc: Christian Brauner <brauner@kernel.org>
Cc: Jan Kara <jack@suse.cz>
Cc: Aleksa Sarai <cyphar@cyphar.com>
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.

Thanks,
Amir.

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

Comments

Alejandro Colomar March 30, 2025, 5:56 p.m. UTC | #1 
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 <jlayton@poochiereds.net>
> Cc: Christian Brauner <brauner@kernel.org>
> Cc: Jan Kara <jack@suse.cz>
> Cc: Aleksa Sarai <cyphar@cyphar.com>
> 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

> 
> 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
>
Amir Goldstein March 30, 2025, 7:17 p.m. UTC | #2 
On Sun, Mar 30, 2025 at 7:56 PM Alejandro Colomar <alx@kernel.org> wrote:
>
> 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 <jlayton@poochiereds.net>
> > Cc: Christian Brauner <brauner@kernel.org>
> > Cc: Jan Kara <jack@suse.cz>
> > Cc: Aleksa Sarai <cyphar@cyphar.com>
> > 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!
>

I pushed the separate patches to
https://github.com/amir73il/man-pages/commits/connectable-fh/

Do you mind taking them from there?

Most of the reviewers that I CC-ed would care about the text
of the man page and less about formatting and patch separation,
and I would rather not spam the reviewers more than have to,
but if you insist, I can post the patches.

Thanks,
Amir.
Alejandro Colomar March 30, 2025, 7:21 p.m. UTC | #3 
Hi Amir,

On Sun, Mar 30, 2025 at 09:17:51PM +0200, Amir Goldstein wrote:
> On Sun, Mar 30, 2025 at 7:56 PM Alejandro Colomar <alx@kernel.org> wrote:
> >
> > 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 <jlayton@poochiereds.net>
> > > Cc: Christian Brauner <brauner@kernel.org>
> > > Cc: Jan Kara <jack@suse.cz>
> > > Cc: Aleksa Sarai <cyphar@cyphar.com>
> > > 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!
> >
> 
> I pushed the separate patches to
> https://github.com/amir73il/man-pages/commits/connectable-fh/
> 
> Do you mind taking them from there?
> 
> Most of the reviewers that I CC-ed would care about the text
> of the man page and less about formatting and patch separation,
> and I would rather not spam the reviewers more than have to,
> but if you insist, I can post the patches.

Could you please send with git-send-email(1) --suppress-cc=all?


Cheers,
Alex

> 
> Thanks,
> Amir.
Amir Goldstein March 30, 2025, 7:54 p.m. UTC | #4 
On Sun, Mar 30, 2025 at 9:21 PM Alejandro Colomar <alx@kernel.org> wrote:
>
> Hi Amir,
>
> On Sun, Mar 30, 2025 at 09:17:51PM +0200, Amir Goldstein wrote:
> > On Sun, Mar 30, 2025 at 7:56 PM Alejandro Colomar <alx@kernel.org> wrote:
> > >
> > > 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 <jlayton@poochiereds.net>
> > > > Cc: Christian Brauner <brauner@kernel.org>
> > > > Cc: Jan Kara <jack@suse.cz>
> > > > Cc: Aleksa Sarai <cyphar@cyphar.com>
> > > > 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!
> > >
> >
> > I pushed the separate patches to
> > https://github.com/amir73il/man-pages/commits/connectable-fh/
> >
> > Do you mind taking them from there?
> >
> > Most of the reviewers that I CC-ed would care about the text
> > of the man page and less about formatting and patch separation,
> > and I would rather not spam the reviewers more than have to,
> > but if you insist, I can post the patches.
>
> Could you please send with git-send-email(1) --suppress-cc=all?
>
>

no problem.

Thanks,
Amir.
diff mbox series

Patch

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