Re: [PATCH v4] fanotify: Document FAN_REPORT_PIDFD Feature

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

Hi Matthew,

On 4/20/22 00:43, Matthew Bobrowski wrote:
> Update the fanotify API documentation to include details on the new
> FAN_REPORT_PIDFD feature. This patch also includes a generic section
> describing the concept of information records which are supported by
> the fanotify API.
> 
> Signed-off-by: Matthew Bobrowski <repnop@google.com>
> Reviewed-by: Jan Kara <jack@suse.cz>
> Reviewed-by: Amir Goldstein <amir73il@gmail.com>
> ---
> 
> Changes in v4:
> 
> * Applied style and grammatical suggestions by Alejandro Colomar
>    [0]. This includes the use of Oxford-style commas and semantic
>    newlines.

I've further edited the patch a bit (only whitespace) regarding semantic 
newlines.  I'll send it as a reply to this patch in a moment.

Apart from that, I couldn't understand a paragraph.  See below.


Thanks,

Alex

> 
> [0] https://lore.kernel.org/linux-man/f40ff271-a18e-9833-f858-9abf3bb19cd2@gmail.com/
> 
>   man2/fanotify_init.2 |  34 +++++++
>   man7/fanotify.7      | 213 +++++++++++++++++++++++++++++++++++--------
>   2 files changed, 209 insertions(+), 38 deletions(-)
> 
[...]
> diff --git a/man7/fanotify.7 b/man7/fanotify.7
> index f8345b3f5..bf648782c 100644
> --- a/man7/fanotify.7
> +++ b/man7/fanotify.7
[...]
> @@ -498,6 +592,49 @@ and the file handle is followed by a null terminated string that identifies the
>   name of a directory entry in that directory, or '.' to identify the directory
>   object itself.
>   .PP
> +The fields of the
> +.I fanotify_event_info_pidfd
> +structure are as follows:
> +.TP
> +.I hdr
> +This is a structure of type
> +.IR fanotify_event_info_header .
> +When an fanotify group is initialized using
> +.BR FAN_REPORT_PIDFD ,
> +the
> +.I info_type
> +field value of the
> +.I fanotify_event_info_header
> +is set to
> +.BR FAN_EVENT_INFO_TYPE_PIDFD .
> +.TP
> +.I pidfd
> +This is a process file descriptor that refers to the process
> +responsible for generating the event.
> +The returned process file descriptor is no different from one which
> +could be obtained manually if
> +.BR pidfd_open (2)
> +were to be called on
> +.IR fanotify_event_metadata.pid .


> +In the instance that an error is encountered during pidfd creation for
> +one of two possible error types represented by a negative integer
> +value may be returned in this
> +.I pidfd
> +field.

I couldn't understand the paragraph above.  Could you maybe rephrase it 
a bit?  Maybe add some commas?

> +In cases where the process responsible for generating the event has
> +terminated prior to the event listener being able to read events from the
> +notification queue,
> +.B FAN_NOPIDFD
> +is returned.
> +The pidfd creation for an event is only performed at the time the
> +events are read from the notification queue.
> +All other possible pidfd creation failures are represented by
> +.BR FAN_EPIDFD.
> +Once the event listener has dealt with an event and the pidfd is no
> +longer required,
> +the pidfd should be closed via
> +.BR close(2).
> +.PP
>   The following macros are provided to iterate over a buffer containing
>   fanotify event metadata returned by a
>   .BR read (2)

-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/