man/man?/fanotify*: Document FAN_REPORT_FD_ERROR

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>
Message-ID: <20250331133959.1436376-1-amir73il@gmail.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

diff --git a/man/man2/fanotify_init.2 b/man/man2/fanotify_init.2
index fa4ae9125db3a2d43665471ea57f5d4a1bc1353d..bf573c6fa1ea3f42083eb309c99a8f3005ef786c 100644 (file)
--- 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 156e4c35f48196fad96d4a2d560f3fe35ee4c532..712d5dfff4bd8b6bd6aaf4003200de73d3823dca 100644 (file)
--- 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