Re: [PATCH v3 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: 4746 bytes --]



On 6/30/22 21:06, 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 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@google.com>
> Reviewed-by: Jan Kara <jack@suse.cz>
> Signed-off-by: Amir Goldstein <amir73il@gmail.com>
> ---
>   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_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 ) ,

s/) ,/),/

Check the difference ;)

groff_man(7):
    Font style macros
        The man macro package is limited in its font styling  op‐
        tions,  offering  only bold (.B), italic (.I), and roman.
        Italic text is usually set underscored instead on  termi‐
        nal devices.  The .SM and .SB macros set text in roman or
        bold,  respectively, at a smaller type size; these differ
        visually from regular‐sized roman or bold  text  only  on
        typesetter devices.  It is often necessary to set text in
        different  styles  without intervening space.  The macros
        .BI, .BR, .IB, .IR, .RB, and .RI, where “B”, “I”, and “R”
        indicate bold, italic, and roman, respectively, set their
        odd‐ and even‐numbered arguments in  alternating  styles,
        with no space separating them.

You can run the following test:

$ man -l - << EOF
.TH a b c d e
.SH Space
.BR foo bar baz
.SH No space
.BR now seethis
EOF

Apart from that, it looks good to me.

Cheers,

Alex


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

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

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