On Wed 22-06-22 19:41:52, Amir Goldstein wrote:
> 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 commit ceaf69f8eadc
> ("fanotify: do not allow setting dirent events in mask of non-dir")
> to v5.18 and backported to v5.17.9.
>
> Reviewed-by: Matthew Bobrowski <repnop@xxxxxxxxxx>
> Signed-off-by: Amir Goldstein <amir73il@xxxxxxxxx>
Looks good. Feel free to add:
Reviewed-by: Jan Kara <jack@xxxxxxx>
Honza
> ---
> man2/fanotify_init.2 | 40 +++++++++++++++++++++++++++++++++++++---
> man2/fanotify_mark.2 | 8 ++++++++
> man7/fanotify.7 | 27 +++++++++++++--------------
> 3 files changed, 58 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..eeaddd173 100644
> --- a/man2/fanotify_mark.2
> +++ b/man2/fanotify_mark.2
> @@ -472,6 +472,14 @@ 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
>
--
Jan Kara <jack@xxxxxxxx>
SUSE Labs, CR
