[PATCH] name_to_handle_at.2,fanotify_mark.2: Document the AT_HANDLE_FID flag

[PATCH] name_to_handle_at.2,fanotify_mark.2: Document the AT_HANDLE_FID flag

[Amir Goldstein]

A flag to indicate that the requested file_handle is not intended
to be used for open_by_handle_at(2) and may be needed to identify
filesystem objects reported in fanotify events.

Signed-off-by: Amir Goldstein <amir73il@gmail.com>
---

Hi Alejandro,

This is a followup on AT_HANDLE_FID feature from v6.5.

Thanks,
Amir.

 man2/fanotify_mark.2     | 11 +++++++++--
 man2/open_by_handle_at.2 | 42 +++++++++++++++++++++++++++++++++++++---
 2 files changed, 48 insertions(+), 5 deletions(-)

diff --git a/man2/fanotify_mark.2 b/man2/fanotify_mark.2
index 3f85deb23..8e885af69 100644
--- a/man2/fanotify_mark.2
+++ b/man2/fanotify_mark.2
@@ -743,10 +743,17 @@ do not specify a directory.
 .B EOPNOTSUPP
 The object indicated by
 .I pathname
-is associated with a filesystem that does not support the encoding of file
-handles.
+is associated with a filesystem
+that does not support the encoding of file handles.
 This error can be returned only with an fanotify group that identifies
 filesystem objects by file handles.
+Calling
+.BR name_to_handle_at (2)
+with the flag
+.BR AT_HANDLE_FID " (since Linux 6.5)"
+.\" commit 96b2b072ee62be8ae68c8ecf14854c4d0505a8f8
+can be used as a test
+to check if a filesystem supports reporting events with file handles.
 .TP
 .B EPERM
 The operation is not permitted because the caller lacks a required capability.
diff --git a/man2/open_by_handle_at.2 b/man2/open_by_handle_at.2
index 4061faea9..4cfa21d9c 100644
--- a/man2/open_by_handle_at.2
+++ b/man2/open_by_handle_at.2
@@ -109,17 +109,44 @@ structure as an opaque data type: the
 .I handle_type
 and
 .I f_handle
-fields are needed only by a subsequent call to
+fields can be used in a subsequent call to
 .BR open_by_handle_at ().
+The caller can also use the opaque
+.I file_handle
+to compare the identity of filesystem objects
+that were queried at different times and possibly
+at different paths.
+The
+.BR fanotify (7)
+subsystem can report events
+with an information record containing a
+.I file_handle
+to identify the filesystem object.
 .PP
 The
 .I flags
 argument is a bit mask constructed by ORing together zero or more of
-.B AT_EMPTY_PATH
+.BR AT_HANDLE_FID ,
+.BR AT_EMPTY_PATH ,
 and
 .BR AT_SYMLINK_FOLLOW ,
 described below.
 .PP
+When
+.I flags
+contain the
+.BR AT_HANDLE_FID " (since Linux 6.5)"
+.\" commit 96b2b072ee62be8ae68c8ecf14854c4d0505a8f8
+flag, the caller indicates that the returned
+.I file_handle
+is needed to identify the filesystem object,
+and not for opening the file later,
+so it should be expected that a subsequent call to
+.BR open_by_handle_at ()
+with the returned
+.I file_handle
+may fail.
+.PP
 Together, the
 .I pathname
 and
@@ -363,8 +390,14 @@ capability.
 .B ESTALE
 The specified
 .I handle
-is not valid.
+is not valid for opening a file.
 This error will occur if, for example, the file has been deleted.
+This error can also occur if the
+.I handle
+was aquired using the
+.B AT_HANDLE_FID
+flag and the filesystem does not support
+.BR open_by_handle_at ().
 .SH VERSIONS
 FreeBSD has a broadly similar pair of system calls in the form of
 .BR getfh ()
@@ -386,6 +419,9 @@ file handles, for example,
 .IR /proc ,
 .IR /sys ,
 and various network filesystems.
+Some filesystem support the translation of pathnames to
+file handles, but do not support using those file handles in
+.BR open_by_handle_at ().
 .PP
 A file handle may become invalid ("stale") if a file is deleted,
 or for other filesystem-specific reasons.
-- 
2.34.1

Re: [PATCH] name_to_handle_at.2,fanotify_mark.2: Document the AT_HANDLE_FID flag

[Jan Kara]

On Sun 03-09-23 15:04:33, Amir Goldstein wrote:
> A flag to indicate that the requested file_handle is not intended
> to be used for open_by_handle_at(2) and may be needed to identify
> filesystem objects reported in fanotify events.
> 
> Signed-off-by: Amir Goldstein <amir73il@gmail.com>

Looks good to me. Feel free to add:

Reviewed-by: Jan Kara <jack@suse.cz>

								Honza

> ---
> 
> Hi Alejandro,
> 
> This is a followup on AT_HANDLE_FID feature from v6.5.
> 
> Thanks,
> Amir.
> 
>  man2/fanotify_mark.2     | 11 +++++++++--
>  man2/open_by_handle_at.2 | 42 +++++++++++++++++++++++++++++++++++++---
>  2 files changed, 48 insertions(+), 5 deletions(-)
> 
> diff --git a/man2/fanotify_mark.2 b/man2/fanotify_mark.2
> index 3f85deb23..8e885af69 100644
> --- a/man2/fanotify_mark.2
> +++ b/man2/fanotify_mark.2
> @@ -743,10 +743,17 @@ do not specify a directory.
>  .B EOPNOTSUPP
>  The object indicated by
>  .I pathname
> -is associated with a filesystem that does not support the encoding of file
> -handles.
> +is associated with a filesystem
> +that does not support the encoding of file handles.
>  This error can be returned only with an fanotify group that identifies
>  filesystem objects by file handles.
> +Calling
> +.BR name_to_handle_at (2)
> +with the flag
> +.BR AT_HANDLE_FID " (since Linux 6.5)"
> +.\" commit 96b2b072ee62be8ae68c8ecf14854c4d0505a8f8
> +can be used as a test
> +to check if a filesystem supports reporting events with file handles.
>  .TP
>  .B EPERM
>  The operation is not permitted because the caller lacks a required capability.
> diff --git a/man2/open_by_handle_at.2 b/man2/open_by_handle_at.2
> index 4061faea9..4cfa21d9c 100644
> --- a/man2/open_by_handle_at.2
> +++ b/man2/open_by_handle_at.2
> @@ -109,17 +109,44 @@ structure as an opaque data type: the
>  .I handle_type
>  and
>  .I f_handle
> -fields are needed only by a subsequent call to
> +fields can be used in a subsequent call to
>  .BR open_by_handle_at ().
> +The caller can also use the opaque
> +.I file_handle
> +to compare the identity of filesystem objects
> +that were queried at different times and possibly
> +at different paths.
> +The
> +.BR fanotify (7)
> +subsystem can report events
> +with an information record containing a
> +.I file_handle
> +to identify the filesystem object.
>  .PP
>  The
>  .I flags
>  argument is a bit mask constructed by ORing together zero or more of
> -.B AT_EMPTY_PATH
> +.BR AT_HANDLE_FID ,
> +.BR AT_EMPTY_PATH ,
>  and
>  .BR AT_SYMLINK_FOLLOW ,
>  described below.
>  .PP
> +When
> +.I flags
> +contain the
> +.BR AT_HANDLE_FID " (since Linux 6.5)"
> +.\" commit 96b2b072ee62be8ae68c8ecf14854c4d0505a8f8
> +flag, the caller indicates that the returned
> +.I file_handle
> +is needed to identify the filesystem object,
> +and not for opening the file later,
> +so it should be expected that a subsequent call to
> +.BR open_by_handle_at ()
> +with the returned
> +.I file_handle
> +may fail.
> +.PP
>  Together, the
>  .I pathname
>  and
> @@ -363,8 +390,14 @@ capability.
>  .B ESTALE
>  The specified
>  .I handle
> -is not valid.
> +is not valid for opening a file.
>  This error will occur if, for example, the file has been deleted.
> +This error can also occur if the
> +.I handle
> +was aquired using the
> +.B AT_HANDLE_FID
> +flag and the filesystem does not support
> +.BR open_by_handle_at ().
>  .SH VERSIONS
>  FreeBSD has a broadly similar pair of system calls in the form of
>  .BR getfh ()
> @@ -386,6 +419,9 @@ file handles, for example,
>  .IR /proc ,
>  .IR /sys ,
>  and various network filesystems.
> +Some filesystem support the translation of pathnames to
> +file handles, but do not support using those file handles in
> +.BR open_by_handle_at ().
>  .PP
>  A file handle may become invalid ("stale") if a file is deleted,
>  or for other filesystem-specific reasons.
> -- 
> 2.34.1
> 
-- 
Jan Kara <jack@suse.com>
SUSE Labs, CR

Re: [PATCH] name_to_handle_at.2,fanotify_mark.2: Document the AT_HANDLE_FID flag

[Christian Brauner]

On Sun, Sep 03, 2023 at 03:04:33PM +0300, Amir Goldstein wrote:
> A flag to indicate that the requested file_handle is not intended
> to be used for open_by_handle_at(2) and may be needed to identify
> filesystem objects reported in fanotify events.
> 
> Signed-off-by: Amir Goldstein <amir73il@gmail.com>
> ---

For the content,
Acked-by: Christian Brauner <brauner@kernel.org>

Re: [PATCH] name_to_handle_at.2,fanotify_mark.2: Document the AT_HANDLE_FID flag

[Tom Schwindl]

Hi,

On Sun Sep 3, 2023 at 2:04 PM CEST, Amir Goldstein wrote:
> A flag to indicate that the requested file_handle is not intended
> to be used for open_by_handle_at(2) and may be needed to identify
> filesystem objects reported in fanotify events.
>
> Signed-off-by: Amir Goldstein <amir73il@gmail.com>
> ---
>
> Hi Alejandro,
>
> This is a followup on AT_HANDLE_FID feature from v6.5.
>
> Thanks,
> Amir.
>
>  man2/fanotify_mark.2     | 11 +++++++++--
>  man2/open_by_handle_at.2 | 42 +++++++++++++++++++++++++++++++++++++---
>  2 files changed, 48 insertions(+), 5 deletions(-)
>
> diff --git a/man2/fanotify_mark.2 b/man2/fanotify_mark.2
> index 3f85deb23..8e885af69 100644
> --- a/man2/fanotify_mark.2
> +++ b/man2/fanotify_mark.2
> @@ -743,10 +743,17 @@ do not specify a directory.
>  .B EOPNOTSUPP
>  The object indicated by
>  .I pathname
> -is associated with a filesystem that does not support the encoding of file
> -handles.
> +is associated with a filesystem
> +that does not support the encoding of file handles.
>  This error can be returned only with an fanotify group that identifies
>  filesystem objects by file handles.
> +Calling
> +.BR name_to_handle_at (2)
> +with the flag
> +.BR AT_HANDLE_FID " (since Linux 6.5)"
> +.\" commit 96b2b072ee62be8ae68c8ecf14854c4d0505a8f8
> +can be used as a test
> +to check if a filesystem supports reporting events with file handles.
>  .TP
>  .B EPERM
>  The operation is not permitted because the caller lacks a required capability.
> diff --git a/man2/open_by_handle_at.2 b/man2/open_by_handle_at.2
> index 4061faea9..4cfa21d9c 100644
> --- a/man2/open_by_handle_at.2
> +++ b/man2/open_by_handle_at.2
> @@ -109,17 +109,44 @@ structure as an opaque data type: the
>  .I handle_type
>  and
>  .I f_handle
> -fields are needed only by a subsequent call to
> +fields can be used in a subsequent call to
>  .BR open_by_handle_at ().
> +The caller can also use the opaque
> +.I file_handle
> +to compare the identity of filesystem objects
> +that were queried at different times and possibly
> +at different paths.
> +The
> +.BR fanotify (7)
> +subsystem can report events
> +with an information record containing a
> +.I file_handle
> +to identify the filesystem object.
>  .PP
>  The
>  .I flags
>  argument is a bit mask constructed by ORing together zero or more of
> -.B AT_EMPTY_PATH
> +.BR AT_HANDLE_FID ,
> +.BR AT_EMPTY_PATH ,
>  and
>  .BR AT_SYMLINK_FOLLOW ,
>  described below.
>  .PP
> +When
> +.I flags
> +contain the
> +.BR AT_HANDLE_FID " (since Linux 6.5)"
> +.\" commit 96b2b072ee62be8ae68c8ecf14854c4d0505a8f8
> +flag, the caller indicates that the returned
> +.I file_handle
> +is needed to identify the filesystem object,
> +and not for opening the file later,
> +so it should be expected that a subsequent call to
> +.BR open_by_handle_at ()
> +with the returned
> +.I file_handle
> +may fail.
> +.PP
>  Together, the
>  .I pathname
>  and
> @@ -363,8 +390,14 @@ capability.
>  .B ESTALE
>  The specified
>  .I handle
> -is not valid.
> +is not valid for opening a file.
>  This error will occur if, for example, the file has been deleted.
> +This error can also occur if the
> +.I handle
> +was aquired using the

This should probably be s/aquired/acquired/

> +.B AT_HANDLE_FID
> +flag and the filesystem does not support
> +.BR open_by_handle_at ().
>  .SH VERSIONS
>  FreeBSD has a broadly similar pair of system calls in the form of
>  .BR getfh ()
> @@ -386,6 +419,9 @@ file handles, for example,
>  .IR /proc ,
>  .IR /sys ,
>  and various network filesystems.
> +Some filesystem support the translation of pathnames to

You should use the plural, filesystems, here.

> +file handles, but do not support using those file handles in
> +.BR open_by_handle_at ().
>  .PP
>  A file handle may become invalid ("stale") if a file is deleted,
>  or for other filesystem-specific reasons.

Re: [PATCH] name_to_handle_at.2,fanotify_mark.2: Document the AT_HANDLE_FID flag

[Amir Goldstein]

On Wed, Sep 6, 2023 at 2:28 AM Tom Schwindl <schwindl@posteo.de> wrote:
>
> Hi,
>
> On Sun Sep 3, 2023 at 2:04 PM CEST, Amir Goldstein wrote:
> > A flag to indicate that the requested file_handle is not intended
> > to be used for open_by_handle_at(2) and may be needed to identify
> > filesystem objects reported in fanotify events.
> >
> > Signed-off-by: Amir Goldstein <amir73il@gmail.com>
> > ---
> >
> > Hi Alejandro,
> >
> > This is a followup on AT_HANDLE_FID feature from v6.5.
> >
> > Thanks,
> > Amir.
> >
> >  man2/fanotify_mark.2     | 11 +++++++++--
> >  man2/open_by_handle_at.2 | 42 +++++++++++++++++++++++++++++++++++++---
> >  2 files changed, 48 insertions(+), 5 deletions(-)
> >
> > diff --git a/man2/fanotify_mark.2 b/man2/fanotify_mark.2
> > index 3f85deb23..8e885af69 100644
> > --- a/man2/fanotify_mark.2
> > +++ b/man2/fanotify_mark.2
> > @@ -743,10 +743,17 @@ do not specify a directory.
> >  .B EOPNOTSUPP
> >  The object indicated by
> >  .I pathname
> > -is associated with a filesystem that does not support the encoding of file
> > -handles.
> > +is associated with a filesystem
> > +that does not support the encoding of file handles.
> >  This error can be returned only with an fanotify group that identifies
> >  filesystem objects by file handles.
> > +Calling
> > +.BR name_to_handle_at (2)
> > +with the flag
> > +.BR AT_HANDLE_FID " (since Linux 6.5)"
> > +.\" commit 96b2b072ee62be8ae68c8ecf14854c4d0505a8f8
> > +can be used as a test
> > +to check if a filesystem supports reporting events with file handles.
> >  .TP
> >  .B EPERM
> >  The operation is not permitted because the caller lacks a required capability.
> > diff --git a/man2/open_by_handle_at.2 b/man2/open_by_handle_at.2
> > index 4061faea9..4cfa21d9c 100644
> > --- a/man2/open_by_handle_at.2
> > +++ b/man2/open_by_handle_at.2
> > @@ -109,17 +109,44 @@ structure as an opaque data type: the
> >  .I handle_type
> >  and
> >  .I f_handle
> > -fields are needed only by a subsequent call to
> > +fields can be used in a subsequent call to
> >  .BR open_by_handle_at ().
> > +The caller can also use the opaque
> > +.I file_handle
> > +to compare the identity of filesystem objects
> > +that were queried at different times and possibly
> > +at different paths.
> > +The
> > +.BR fanotify (7)
> > +subsystem can report events
> > +with an information record containing a
> > +.I file_handle
> > +to identify the filesystem object.
> >  .PP
> >  The
> >  .I flags
> >  argument is a bit mask constructed by ORing together zero or more of
> > -.B AT_EMPTY_PATH
> > +.BR AT_HANDLE_FID ,
> > +.BR AT_EMPTY_PATH ,
> >  and
> >  .BR AT_SYMLINK_FOLLOW ,
> >  described below.
> >  .PP
> > +When
> > +.I flags
> > +contain the
> > +.BR AT_HANDLE_FID " (since Linux 6.5)"
> > +.\" commit 96b2b072ee62be8ae68c8ecf14854c4d0505a8f8
> > +flag, the caller indicates that the returned
> > +.I file_handle
> > +is needed to identify the filesystem object,
> > +and not for opening the file later,
> > +so it should be expected that a subsequent call to
> > +.BR open_by_handle_at ()
> > +with the returned
> > +.I file_handle
> > +may fail.
> > +.PP
> >  Together, the
> >  .I pathname
> >  and
> > @@ -363,8 +390,14 @@ capability.
> >  .B ESTALE
> >  The specified
> >  .I handle
> > -is not valid.
> > +is not valid for opening a file.
> >  This error will occur if, for example, the file has been deleted.
> > +This error can also occur if the
> > +.I handle
> > +was aquired using the
>
> This should probably be s/aquired/acquired/
>
> > +.B AT_HANDLE_FID
> > +flag and the filesystem does not support
> > +.BR open_by_handle_at ().
> >  .SH VERSIONS
> >  FreeBSD has a broadly similar pair of system calls in the form of
> >  .BR getfh ()
> > @@ -386,6 +419,9 @@ file handles, for example,
> >  .IR /proc ,
> >  .IR /sys ,
> >  and various network filesystems.
> > +Some filesystem support the translation of pathnames to
>
> You should use the plural, filesystems, here.
>

Fixed in v2.

Thanks for the review!
Amir.