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

[Alejandro Colomar <alx.manpages@gmail.com>]

[-- Attachment #1.1: Type: text/plain, Size: 5950 bytes --]

On 6/17/22 15:11, 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.
> 
> Reviewed-by: Matthew Bobrowski <repnop@google.com>
> Signed-off-by: Amir Goldstein <amir73il@gmail.com>

Hi Amir,

Please see some comment below.

Thanks,

Alex

> ---
>   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.,

man-pages(7):
    Use semantic newlines
        In the source of a manual page, new sentences  should  be
        started on new lines, long sentences should be split into
        lines  at  clause breaks (commas, semicolons, colons, and
        so on), and long clauses should be split at phrase bound‐
        aries.  This convention,  sometimes  known  as  "semantic
        newlines",  makes it easier to see the effect of patches,
        which often operate at the level of individual sentences,
        clauses, or phrases.


It only applies to the 2 lines above.  The rest of the patch looks good.

> +.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

-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]