Re: [PATCH] fanotify: Document FAN_REPORT_FD_ERROR

[Amir Goldstein <amir73il@xxxxxxxxx>]

On Mon, Mar 31, 2025 at 1:34 PM Jan Kara <jack@xxxxxxx> wrote:
>
> On Sun 30-03-25 14:51:46, Amir Goldstein wrote:
> > This flag from v6.13 allows reporting detailed errors on failure to
> > open a file descriptor for an event.
> >
> > This API was backported to LTS kernels v6.12.4 and v6.6.66.
> >
> > Cc: Krishna Vivek Vitta <kvitta@xxxxxxxxxxxxx>
> > Signed-off-by: Amir Goldstein <amir73il@xxxxxxxxx>
>
> The text looks correct to me. So feel free to add:
>
> Reviewed-by: Jan Kara <jack@xxxxxxx>
>
> Just two typo corrections below.
>
>                                                                 Honza
>
> > ---
> >  man/man2/fanotify_init.2 | 29 +++++++++++++++++++++++++++++
> >  man/man7/fanotify.7      | 12 ++++++++++++
> >  2 files changed, 41 insertions(+)
> >
> > diff --git a/man/man2/fanotify_init.2 b/man/man2/fanotify_init.2
> > index fa4ae9125..23fbe126f 100644
> > --- a/man/man2/fanotify_init.2
> > +++ b/man/man2/fanotify_init.2
> > @@ -364,6 +364,35 @@ so this restriction may eventually be lifted.
> >  For more details on information records,
> >  see
> >  .BR fanotify (7).
> > +.TP
> > +.BR FAN_REPORT_FD_ERROR " (since Linux 6.13 and 6.12.4 and 6.6.66)"
> > +.\" commit 522249f05c5551aec9ec0ba9b6438f1ec19c138d
> > +Events for fanotify groups initialized with this flag may contain
> > +an error code that explains the reason for failure to open a file descriptor.
> > +The
> > +.I fd
> > +memeber of struct
>    ^^^ typo here
>
> > +.I fanotify_event_metadata
> > +normally contains
> > +an open file descriptor associated with the object of the event
> > +or FAN_NOFD in case a file descriptor could not be opened.
> > +For a group initialized with this flag, instead of FAN_NOFD,
> > +the
> > +.I fd
> > +memeber of struct
>    ^^^ typo here
>
> > +.I fanotify_event_metadata
> > +will contain
> > +a negative error value.

Right.
I also changed the phrasing to

The
.I .fd
member of the
.I fanotify_event_metadata
structure will contain a negative error value.

and formatting of:

in case of a queue overflow, the value will be
+.BR "" - EBADF .

As Alejandro requested in another review.

Will post v2 soon.

Thanks,
Amir.