[PATCH] fanotify: Document FAN_REPORT_FD_ERROR

[PATCH] fanotify: Document FAN_REPORT_FD_ERROR

[Amir Goldstein]

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@microsoft.com>
Signed-off-by: Amir Goldstein <amir73il@gmail.com>
---
 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
+.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
+.I fanotify_event_metadata
+will contain
+a negative error value.
+When the group is also initialized with flag
+.BR FAN_REPORT_PIDFD ,
+in case a process file descriptor could not be opened,
+the
+.I pidfd
+memeber of struct
+.I fanotify_event_info_pidfd
+will also contain a negative error value.
+For more details, see
+.BR fanotify (7).
 .P
 The
 .I event_f_flags
diff --git a/man/man7/fanotify.7 b/man/man7/fanotify.7
index a5ddf1df0..7844f52f6 100644
--- a/man/man7/fanotify.7
+++ b/man/man7/fanotify.7
@@ -335,6 +335,12 @@ file status flag is set on the open file description.
 This flag suppresses fanotify event generation.
 Hence, when the receiver of the fanotify event accesses the notified file or
 directory using this file descriptor, no additional events will be created.
+.IP
+When an fanotify group is initialized using
+.BR FAN_REPORT_FD_ERROR ,
+this field will contain a negative error value in case a file descriptor
+could not be opened and
+in case of a queue overflow, the value will be -EBADF.
 .TP
 .I pid
 If flag
@@ -679,6 +685,12 @@ Once the event listener has dealt with an event
 and the pidfd is no longer required,
 the pidfd should be closed via
 .BR close (2).
+.IP
+When an fanotify group is initialized using
+.BR FAN_REPORT_FD_ERROR ,
+this field will contain a negative error value
+in case a pidfd creation failure and
+in case of a terminated process, the value will be -ESRCH.
 .P
 The fields of the
 .I fanotify_event_info_error
-- 
2.34.1

Re: [PATCH] fanotify: Document FAN_REPORT_FD_ERROR

[Jan Kara]

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@microsoft.com>
> Signed-off-by: Amir Goldstein <amir73il@gmail.com>

The text looks correct to me. So feel free to add:

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

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.
> +When the group is also initialized with flag
> +.BR FAN_REPORT_PIDFD ,
> +in case a process file descriptor could not be opened,
> +the
> +.I pidfd
> +memeber of struct
> +.I fanotify_event_info_pidfd
> +will also contain a negative error value.
> +For more details, see
> +.BR fanotify (7).
>  .P
>  The
>  .I event_f_flags
> diff --git a/man/man7/fanotify.7 b/man/man7/fanotify.7
> index a5ddf1df0..7844f52f6 100644
> --- a/man/man7/fanotify.7
> +++ b/man/man7/fanotify.7
> @@ -335,6 +335,12 @@ file status flag is set on the open file description.
>  This flag suppresses fanotify event generation.
>  Hence, when the receiver of the fanotify event accesses the notified file or
>  directory using this file descriptor, no additional events will be created.
> +.IP
> +When an fanotify group is initialized using
> +.BR FAN_REPORT_FD_ERROR ,
> +this field will contain a negative error value in case a file descriptor
> +could not be opened and
> +in case of a queue overflow, the value will be -EBADF.
>  .TP
>  .I pid
>  If flag
> @@ -679,6 +685,12 @@ Once the event listener has dealt with an event
>  and the pidfd is no longer required,
>  the pidfd should be closed via
>  .BR close (2).
> +.IP
> +When an fanotify group is initialized using
> +.BR FAN_REPORT_FD_ERROR ,
> +this field will contain a negative error value
> +in case a pidfd creation failure and
> +in case of a terminated process, the value will be -ESRCH.
>  .P
>  The fields of the
>  .I fanotify_event_info_error
> -- 
> 2.34.1
> 
-- 
Jan Kara <jack@suse.com>
SUSE Labs, CR

Re: [PATCH] fanotify: Document FAN_REPORT_FD_ERROR

[Amir Goldstein]

On Mon, Mar 31, 2025 at 1:34 PM Jan Kara <jack@suse.cz> 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@microsoft.com>
> > Signed-off-by: Amir Goldstein <amir73il@gmail.com>
>
> The text looks correct to me. So feel free to add:
>
> Reviewed-by: Jan Kara <jack@suse.cz>
>
> 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.

Re: [PATCH] fanotify: Document FAN_REPORT_FD_ERROR

[Alejandro Colomar]

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

Hi Amir,

On Mon, Mar 31, 2025 at 01:55:11PM +0200, Amir Goldstein wrote:
> and formatting of:
> 
> in case of a queue overflow, the value will be
> +.BR "" - EBADF .

The '-' needs to be escaped: \-

Also, I'd keep the '-' also in bold:

.BR \-EBADF .


Have a lovely day!
Alex

> 
> As Alejandro requested in another review.
> 
> Will post v2 soon.
> 
> Thanks,
> Amir.

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

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