This provides an explanation on the kind of additional information that can
be returned alongside the generic struct fanotify_event_metadata and in
what form this additional contextual information is delievered to a
listening application.
Signed-off-by: Matthew Bobrowski <repnop@xxxxxxxxxx>
---
man2/fanotify_init.2 | 54 +++++++++++++++++++++++++
man7/fanotify.7 | 95 +++++++++++++++++++++++++++++++++++++++++++-
2 files changed, 147 insertions(+), 2 deletions(-)
diff --git a/man2/fanotify_init.2 b/man2/fanotify_init.2
index 0d83e817f..f65b4fa10 100644
--- a/man2/fanotify_init.2
+++ b/man2/fanotify_init.2
@@ -298,6 +298,60 @@ for additional details.
This is a synonym for
.RB ( FAN_REPORT_DIR_FID | FAN_REPORT_NAME ).
.PP
+.TP
+.B FAN_REPORT_PIDFD " (since Linux 5.15)"
+Events for fanotify groups initialized with this flag will contain an
+additional information record object alongside the generic fanotify
+event metadata structure.
+This additional information record will be of type
+.BR FAN_EVENT_INFO_TYPE_PIDFD
+and will contain a pidfd for the process that was responsible for
+generating an event.
+The returned pidfd within the information object is indistinguishable
+from a pidfd that is obtained via
+.BR pidfd_open(2).
+Usage of this additional information record object is for applications
+that are interested in reliably determining whether the process
+responsible for generating the event has either been recycled or
+terminated.
+In the instance that either
+.BR FAN_REPORT_FID
+or
+.BR FAN_REPORT_DFID_NAME
+are supplied along with
+.BR FAN_REPORT_PIDFD
+information record objects of type
+.BR FAN_EVENT_INFO_TYPE_FID,
+.BR FAN_EVENT_INFO_TYPE_DFID
+and
+.BR FAN_EVENT_INFO_TYPE_DFID_NAME
+will likely precede the information object of type
+.BR FAN_EVENT_INFO_TYPE_PIDFD
+for a single event within the read buffer.
+However, an event listener should never work with this information object
+ordering assumption and is encouraged to always check the information type
+set within the
+.IR fanotify_event_info_header
+of each information object.
+The use of the
+.BR FAN_REPORT_TID
+flag along with
+.BR FAN_REPORT_PIDFD
+is currently not supported and attempting to do so will result in the
+error
+.BR EINVAL
+being returned.
+This limitation is imposed by the pidfd API as it currently only
+supports the creation of pidfds for thread-group leaders.
+Creating pidfds for non-thread-group leaders may be supported at some
+point in the future, so this restriction may eventually be lifted.
+Additional pidfd specific error cases can be reported back to the
+listening application in an information record object of type
+.BR FAN_EVENT_INFO_TYPE_PIDFD.
+See
+.BR fanotify(7)
+for additional details.
+.PP
The
.I event_f_flags
argument
diff --git a/man7/fanotify.7 b/man7/fanotify.7
index 455e3ed17..09fa4defb 100644
--- a/man7/fanotify.7
+++ b/man7/fanotify.7
@@ -141,12 +141,24 @@ until either a file event occurs or the call is interrupted by a signal
The use of one of the flags
.BR FAN_REPORT_FID ,
.BR FAN_REPORT_DIR_FID
+or
+.BR FAN_REPORT_PIDFD
in
.BR fanotify_init (2)
influences what data structures are returned to the event listener for each
event.
-Events reported to a group initialized with one of these flags will
-use file handles to identify filesystem objects instead of file descriptors.
+Events reported to a group initialized with one of either
+.BR FAN_REPORT_FID
+or
+.BR FAN_REPORT_DIR_FID
+flags will use file handles to identify filesystem objects instead of
+file descriptors.
+Events reported to a group intialized with
+.BR FAN_REPORT_PIDFD
+will attempt to also create a process file descriptor, commonly
+referred to as a pidfd, for the process responsible for generating the
+event and provide that alongside the generic fanotify metadata event
+structure.
.PP
After a successful
.BR read (2),
@@ -188,6 +200,27 @@ struct fanotify_event_info_fid {
.EE
.in
.PP
+In the instance that the fanotify group has been initialized with
+.BR FAN_REPORT_PIDFD ,
+the listening application should expect to receive a single
+information record object as detailed below alongside the generic
+.I fanotify_event_metadata structure:
+.PP
+.in +4n
+.EX
+struct fanotify_event_info_header {
+ __u8 info_type;
+ __u8 pad;
+ __u16 len;
+};
+
+struct fanotify_event_info_pidfd {
+ struct fanotify_event_info_header hdr;
+ __s32 pidfd;
+};
+.EE
+.in
+.PP
For performance reasons, it is recommended to use a large
buffer size (for example, 4096 bytes),
so that multiple events can be retrieved by a single
@@ -510,6 +543,64 @@ and the file handle is followed by a null terminated string that identifies the
name of a directory entry in that directory, or '.' to identify the directory
object itself.
.PP
+The fields of the
+.I fanotify_event_info_pidfd
+structure are as follows:
+.TP
+.I hdr
+This is a structure of type
+.IR fanotify_event_info_header .
+Exactly like the one that is provided in a
+.I fanotify_event_info_fid
+structure, it is a generic header that contains information used to
+describe an additional information record object that is attached to
+an event.
+In the instance that
+.BR FAN_REPORT_PIDFD
+is supplied during fanotify group initialization, a single information
+record object is expected to be attached alongside the generic
+metadata event with its
+.I info_type
+field set to the value of
+.BR FAN_EVENT_INFO_TYPE_PIDFD .
+The
+.I fanotify_event_info_header
+structure also contains a
+.I len
+field.
+The value of the
+.I len
+field is the total size of the
+.I fanotify_event_info_pidfd
+structure, which also includes
+.IR fanotify_event_info_header .
+.TP
+.I pidfd
+This is a file descriptor that refers to the process responsible for
+generating the event.
+This returned file descriptor is no different from one which could be
+obtained manually if
+.BR pidfd_open(2)
+were to be called on
+.IR fanotify_event_metadata.pid .
+In the instance that an error is encountered during pidfd creation for
+an event, one of two possible error types represented by a negative
+integer value may be returned in this
+.I pidfd
+field.
+In cases where the process responsible for generating the event has
+terminated prior to the event listener being able to read events from the
+notification queue a
+.BR FAN_NOPIDFD
+is returned.
+The pidfd allocation for an event is only performed at the time the events
+are read from the notification queue.
+All other possible pidfd creation failures are represented by
+.BR FAN_EPIDFD .
+Once the application has dealt with an event and the pidfd is no
+longer required, the pidfd should be closed via
+.BR close(2) .
+.PP
The following macros are provided to iterate over a buffer containing
fanotify event metadata returned by a
.BR read (2)
--
2.33.0.1079.g6e70778dc9-goog
/M
