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@xxxxxxxxxx> Reviewed-by: Jan Kara <jack@xxxxxxx> Reviewed-by: Amir Goldstein <amir73il@xxxxxxxxx> --- 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@xxxxxxxxx/ 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/
