[PATCH v3 1/2] name_to_handle_at.2: Document the AT_HANDLE_MNT_ID_UNIQUE flag

[PATCH v3 1/2] name_to_handle_at.2: Document the AT_HANDLE_MNT_ID_UNIQUE flag

[Amir Goldstein]

A flag since v6.12 to indicate that the requested mount_id is
a 64bit unique id.

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>
---
 man/man2/open_by_handle_at.2 | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/man/man2/open_by_handle_at.2 b/man/man2/open_by_handle_at.2
index 6b9758d42..e3ec70dd5 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_MNT_ID_UNIQUE,
 .BR AT_EMPTY_PATH ,
 and
 .BR AT_SYMLINK_FOLLOW ,
@@ -147,6 +148,21 @@ 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
 Together, the
 .I pathname
 and
-- 
2.34.1

[PATCH v3 2/2] 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.

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>
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 e3ec70dd5..f808ea933 100644
--- a/man/man2/open_by_handle_at.2
+++ b/man/man2/open_by_handle_at.2
@@ -128,6 +128,7 @@ The
 argument is a bit mask constructed by ORing together zero or more of
 .BR AT_HANDLE_FID ,
 .BR AT_HANDLE_MNT_ID_UNIQUE,
+.BR AT_HANDLE_CONNECTABLE,
 .BR AT_EMPTY_PATH ,
 and
 .BR AT_SYMLINK_FOLLOW ,
@@ -163,6 +164,29 @@ 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
@@ -327,7 +351,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
@@ -414,6 +438,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 v3 1/2] name_to_handle_at.2: Document the AT_HANDLE_MNT_ID_UNIQUE flag

[Alejandro Colomar]

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

Hi Amir,

On Mon, Mar 31, 2025 at 10:16:41AM +0200, Amir Goldstein wrote:
> A flag since v6.12 to indicate that the requested mount_id is
> a 64bit unique id.
> 
> 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>

Thanks!  I've applied the patch, with some minor amendments:

	diff --git i/man/man2/open_by_handle_at.2 w/man/man2/open_by_handle_at.2
	index da0129dee..47405b118 100644
	--- i/man/man2/open_by_handle_at.2
	+++ w/man/man2/open_by_handle_at.2
	@@ -127,7 +127,7 @@ .SS name_to_handle_at()
	 .I flags
	 argument is a bit mask constructed by ORing together zero or more of
	 .BR AT_HANDLE_FID ,
	-.BR AT_HANDLE_MNT_ID_UNIQUE,
	+.BR AT_HANDLE_MNT_ID_UNIQUE ,
	 .BR AT_EMPTY_PATH ,
	 and
	 .BR AT_SYMLINK_FOLLOW ,
	@@ -153,11 +153,11 @@ .SS name_to_handle_at()
	 contain the
	 .BR AT_HANDLE_MNT_ID_UNIQUE " (since Linux 6.12)"
	 .\" commit 4356d575ef0f39a3e8e0ce0c40d84ce900ac3b61
	-flag, the caller indicates that the size of the
	+flag, the caller indicates that the width of the
	 .I mount_id
	-buffer is at least 64bit
	+buffer is at least 64 bits,
	 and then the mount id returned in that buffer
	-is the unique mount id as the one returned by
	+is the unique mount id as returned by
	 .BR statx (2)
	 with the
	 .BR STATX_MNT_ID_UNIQUE

The most notable one is s/size/width/.  In C23 there are the concepts of
the width of a type and the size of a type.  The width is measured in
bits, and the size is measured in bytes.  Let's be consistent with that.

I have also proposed a new set of operators for ISO C2y, which are
_Minof, _Maxof, and _Widthof, which yield the minimum and maximum values
of a type, and its width in bits.
<https://www.open-std.org/jtc1/sc22/wg14/www/docs/n3518.txt>
The C Committee seems in favour of that proposal, and I expect it will
be accepted in August.


Have a lovely day!
Alex

P.S.:  I'm not using my @gmail account anymore.  Please use
       <alx@kernel.org>.

> ---
>  man/man2/open_by_handle_at.2 | 16 ++++++++++++++++
>  1 file changed, 16 insertions(+)
> 
> diff --git a/man/man2/open_by_handle_at.2 b/man/man2/open_by_handle_at.2
> index 6b9758d42..e3ec70dd5 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_MNT_ID_UNIQUE,
>  .BR AT_EMPTY_PATH ,
>  and
>  .BR AT_SYMLINK_FOLLOW ,
> @@ -147,6 +148,21 @@ 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
>  Together, the
>  .I pathname
>  and
> -- 
> 2.34.1
> 

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

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

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

[Alejandro Colomar]

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

Hi Amir,

On Mon, Mar 31, 2025 at 10:16:42AM +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>
> Signed-off-by: Amir Goldstein <amir73il@gmail.com>

Thanks!  I've applied the patch.

> ---
>  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 e3ec70dd5..f808ea933 100644
> --- a/man/man2/open_by_handle_at.2
> +++ b/man/man2/open_by_handle_at.2
> @@ -128,6 +128,7 @@ The
>  argument is a bit mask constructed by ORing together zero or more of
>  .BR AT_HANDLE_FID ,
>  .BR AT_HANDLE_MNT_ID_UNIQUE,
> +.BR AT_HANDLE_CONNECTABLE,

I amended here the missing space.


Cheers,
Alex

>  .BR AT_EMPTY_PATH ,
>  and
>  .BR AT_SYMLINK_FOLLOW ,
> @@ -163,6 +164,29 @@ 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
> @@ -327,7 +351,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
> @@ -414,6 +438,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 --]

Re: [PATCH v3 1/2] name_to_handle_at.2: Document the AT_HANDLE_MNT_ID_UNIQUE flag

[Amir Goldstein]

On Mon, Mar 31, 2025 at 10:38 AM Alejandro Colomar <alx@kernel.org> wrote:
>
> Hi Amir,
>
> On Mon, Mar 31, 2025 at 10:16:41AM +0200, Amir Goldstein wrote:
> > A flag since v6.12 to indicate that the requested mount_id is
> > a 64bit unique id.
> >
> > 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>
>
> Thanks!  I've applied the patch, with some minor amendments:
>
>         diff --git i/man/man2/open_by_handle_at.2 w/man/man2/open_by_handle_at.2
>         index da0129dee..47405b118 100644
>         --- i/man/man2/open_by_handle_at.2
>         +++ w/man/man2/open_by_handle_at.2
>         @@ -127,7 +127,7 @@ .SS name_to_handle_at()
>          .I flags
>          argument is a bit mask constructed by ORing together zero or more of
>          .BR AT_HANDLE_FID ,
>         -.BR AT_HANDLE_MNT_ID_UNIQUE,
>         +.BR AT_HANDLE_MNT_ID_UNIQUE ,
>          .BR AT_EMPTY_PATH ,
>          and
>          .BR AT_SYMLINK_FOLLOW ,
>         @@ -153,11 +153,11 @@ .SS name_to_handle_at()
>          contain the
>          .BR AT_HANDLE_MNT_ID_UNIQUE " (since Linux 6.12)"
>          .\" commit 4356d575ef0f39a3e8e0ce0c40d84ce900ac3b61
>         -flag, the caller indicates that the size of the
>         +flag, the caller indicates that the width of the
>          .I mount_id
>         -buffer is at least 64bit
>         +buffer is at least 64 bits,
>          and then the mount id returned in that buffer
>         -is the unique mount id as the one returned by
>         +is the unique mount id as returned by
>          .BR statx (2)
>          with the
>          .BR STATX_MNT_ID_UNIQUE
>
> The most notable one is s/size/width/.  In C23 there are the concepts of
> the width of a type and the size of a type.  The width is measured in
> bits, and the size is measured in bytes.  Let's be consistent with that.
>
> I have also proposed a new set of operators for ISO C2y, which are
> _Minof, _Maxof, and _Widthof, which yield the minimum and maximum values
> of a type, and its width in bits.
> <https://www.open-std.org/jtc1/sc22/wg14/www/docs/n3518.txt>
> The C Committee seems in favour of that proposal, and I expect it will
> be accepted in August.
>

Thanks! I did not know that.

>
> Have a lovely day!
> Alex
>
> P.S.:  I'm not using my @gmail account anymore.  Please use
>        <alx@kernel.org>.
>

Fixed my script.

Thanks,
Amir.