[PATCH v2 1/3] fanotify: Document FAN_REPORT_FD_ERROR

[Amir Goldstein <amir73il@gmail.com>]

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>
Reviewed-by: Jan Kara <jack@suse.cz>
Signed-off-by: Amir Goldstein <amir73il@gmail.com>
---

Changes from v1:
- Added RVB
- typo and format fixes

 man/man2/fanotify_init.2 | 28 ++++++++++++++++++++++++++++
 man/man7/fanotify.7      | 14 ++++++++++++++
 2 files changed, 42 insertions(+)

diff --git a/man/man2/fanotify_init.2 b/man/man2/fanotify_init.2
index fa4ae9125..bf573c6fa 100644
--- a/man/man2/fanotify_init.2
+++ b/man/man2/fanotify_init.2
@@ -364,6 +364,34 @@ 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
+member of the
+.I fanotify_event_metadata
+structure 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
+member of the
+.I fanotify_event_metadata
+structure 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
+member of the
+.I fanotify_event_info_pidfd
+structure 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 a532a963a..fd16bf294 100644
--- a/man/man7/fanotify.7
+++ b/man/man7/fanotify.7
@@ -335,6 +335,13 @@ 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
+.BR \-EBADF .
 .TP
 .I pid
 If flag
@@ -679,6 +686,13 @@ 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
+.BR \-ESRCH .
 .P
 The fields of the
 .I fanotify_event_info_error
-- 
2.34.1