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.
Note that while FAN_REPORT_TARGET_FID was merged to v5.17, the sanity
checks resulting in ENOTDIR were merged as fix commits ceaf69f8eadc
("fanotify: do not allow setting dirent events in mask of non-dir")
and 8698e3bab4dd ("fanotify: refine the validation checks on non-dir
inode mask") in later kernel releases.
Reviewed-by: Matthew Bobrowski <repnop@xxxxxxxxxx>
Reviewed-by: Jan Kara <jack@xxxxxxx>
Signed-off-by: Amir Goldstein <amir73il@xxxxxxxxx>
---
man2/fanotify_init.2 | 40 +++++++++++++++++++++++++++++++++++++---
man2/fanotify_mark.2 | 18 ++++++++++++++++++
man7/fanotify.7 | 27 +++++++++++++--------------
3 files changed, 68 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..80f73b983 100644
--- a/man2/fanotify_mark.2
+++ b/man2/fanotify_mark.2
@@ -473,6 +473,24 @@ and
.I pathname
do not specify a directory.
.TP
+.B ENOTDIR
+The fanotify group was initialized with flag
+.BR FAN_REPORT_TARGET_FID ,
+.I mask
+contains directory entry modification events
+(e.g.,
+.BR FAN_CREATE ,
+.BR FAN_DELETE ) ,
+or directory event flags
+(e.g.,
+.BR FAN_ONDIR ,
+.BR FAN_EVENT_ON_CHILD ) ,
+and
+.I dirfd
+and
+.I pathname
+do not specify a directory.
+.TP
.B EOPNOTSUPP
The object indicated by
.I pathname
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
