[PATCH 1/2] fanotify.7, fanotify_init.2: Document FAN_REPORT_TARGET_FID

[Amir Goldstein <amir73il@gmail.com>]

FAN_REPORT_TARGET_FID adds an information record about the child
to directory entry modification events (create/delete/move).

This flag also adds sanity checks that directory modification events
(create,delete,moved) cannot be set in mask of a non-dir inode mark.

Reviewed-by: Matthew Bobrowski <repnop@google.com>
Signed-off-by: Amir Goldstein <amir73il@gmail.com>
---
 man2/fanotify_init.2 | 40 +++++++++++++++++++++++++++++++++++++---
 man2/fanotify_mark.2 |  7 +++++++
 man7/fanotify.7      | 27 +++++++++++++--------------
 3 files changed, 57 insertions(+), 17 deletions(-)

diff --git a/man2/fanotify_init.2 b/man2/fanotify_init.2
index 9abec5fca..ac4d3a305 100644
--- a/man2/fanotify_init.2
+++ b/man2/fanotify_init.2
@@ -182,9 +182,11 @@ and
 .BR FAN_MOVE_SELF .
 All the events above require an fanotify group that identifies filesystem
 objects by file handles.
-Note that for the directory entry modification events the reported file handle
-identifies the modified directory and not the created/deleted/moved child
-object.
+Note that without the flag
+.BR FAN_REPORT_TARGET_FID ,
+for the directory entry modification events,
+there is an inforamtion record that identifies the modified directory
+and not the created/deleted/moved child object.
 The use of
 .B FAN_CLASS_CONTENT
 or
@@ -282,6 +284,38 @@ for additional details.
 .B FAN_REPORT_DFID_NAME
 This is a synonym for
 .RB ( FAN_REPORT_DIR_FID | FAN_REPORT_NAME ).
+.TP
+.BR FAN_REPORT_TARGET_FID " (since Linux 5.17)"
+.\" commit d61fd650e9d206a71fda789f02a1ced4b19944c4
+Events for fanotify groups initialized with this flag
+will contain additional information about the child
+correlated with directory entry modification events.
+This flag must be provided in conjunction with the flags
+.BR FAN_REPORT_FID ,
+.B FAN_REPORT_DIR_FID
+and
+.BR FAN_REPORT_NAME .
+or else the error
+.B EINVAL
+will be returned.
+For the directory entry modification events
+.BR FAN_CREATE ,
+.BR FAN_DELETE ,
+and
+.BR FAN_MOVE ,
+an additional record of type
+.BR FAN_EVENT_INFO_TYPE_FID ,
+is reported in addition to the information record of type
+.B FAN_EVENT_INFO_TYPE_DFID
+or
+.BR FAN_EVENT_INFO_TYPE_DFID_NAME .
+The additional record includes a file handle
+that identifies the filesystem child object
+that the directory entry is referring to.
+.TP
+.B FAN_REPORT_DFID_NAME_TARGET
+This is a synonym for
+.RB ( FAN_REPORT_DFID_NAME | FAN_REPORT_FID | FAN_REPORT_TARGET_FID ).
 .PP
 .TP
 .BR FAN_REPORT_PIDFD " (since Linux 5.15)"
diff --git a/man2/fanotify_mark.2 b/man2/fanotify_mark.2
index 3dc538b7f..ebb327bdd 100644
--- a/man2/fanotify_mark.2
+++ b/man2/fanotify_mark.2
@@ -472,6 +472,13 @@ and
 and
 .I pathname
 do not specify a directory.
+For an fanotify group that was initialized with flag
+.BR FAN_REPORT_TARGET_FID ,
+this error will also be returned when trying to set directory entry modification
+events (e.g.,
+.BR FAN_CREATE ,
+.BR FAN_DELETE )
+in the mask of a non directory inode mark.
 .TP
 .B EOPNOTSUPP
 The object indicated by
diff --git a/man7/fanotify.7 b/man7/fanotify.7
index f4d391603..5f2c01408 100644
--- a/man7/fanotify.7
+++ b/man7/fanotify.7
@@ -171,14 +171,14 @@ alongside the generic
 structure.
 For example,
 if a notification group is initialized with
-.B FAN_REPORT_FID
+.B FAN_REPORT_TARGET_FID
 and
 .BR FAN_REPORT_PIDFD ,
-then an event listener should also expect to receive both
+then an event listener should expect to receive up to two
 .I fanotify_event_info_fid
-and
+information records and one
 .I fanotify_event_info_pidfd
-structures alongside the generic
+information record alongside the generic
 .I fanotify_event_metadata
 structure.
 Importantly,
@@ -552,7 +552,15 @@ identifying a parent directory object, and one with
 .I info_type
 field value of
 .BR FAN_EVENT_INFO_TYPE_FID ,
-identifying a non-directory object.
+identifying a child object.
+Note that for the directory entry modification events
+.BR FAN_CREATE ,
+.BR FAN_DELETE ,
+and
+.BR FAN_MOVE ,
+an information record identifying the created/deleted/moved child object
+is reported only if an fanotify group was initialized with the flag
+.BR FAN_REPORT_TARGET_FID.
 .TP
 .I fsid
 This is a unique identifier of the filesystem containing the object
@@ -572,15 +580,6 @@ filesystem as returned by
 It can be used to uniquely identify a file on a filesystem and can be
 passed as an argument to
 .BR open_by_handle_at (2).
-Note that for the directory entry modification events
-.BR FAN_CREATE ,
-.BR FAN_DELETE ,
-and
-.BR FAN_MOVE ,
-the
-.I file_handle
-identifies the modified directory and not the created/deleted/moved child
-object.
 If the value of
 .I info_type
 field is
-- 
2.25.1