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

Amir Goldstein
2023-09-06T07:39:38Z

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.