fanotify: Document FAN_REPORT_PIDFD Feature
PATCH v4 1/1 fanotify: Document FAN_REPORT_PIDFD Feature
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.
---
Changes in v4:
* Applied style and grammatical suggestions by Alejandro Colomar [0]. This includes the use of Oxford-style commas and semantic newlines.
[0] https://lore.kernel.org/linux-man/[email protected]/
man2/fanotify_init.2 | 34 +++++++ man7/fanotify.7 | 213 +++++++++++++++++++++++++++++++++++-------- 2 files changed, 209 insertions(+), 38 deletions(-)
man2/fanotify_init.2 +34 -0
@@ -283,6 +283,40 @@ for additional details. This is a synonym for .RB ( FAN_REPORT_DIR_FID | FAN_REPORT_NAME ). .PP +.TP +.BR FAN_REPORT_PIDFD " (since Linux 5.15)" +.\" commit af579beb666aefb17e9a335c12c788c92932baf1 +Events for fanotify groups initialized with this flag will contain an +additional information record alongside the generic +.I fanotify_event_metadata +structure. +This information record will be of type +.B FAN_EVENT_INFO_TYPE_PIDFD +and will contain a pidfd for the process that was responsible for +generating an event. +A pidfd returned in this information record object is no different +to the pidfd that is returned when calling +.BR pidfd_open(2). +Usage of this information record are for applications that may be +interested in reliably determining whether the process responsible for +generating an event has been recycled or terminated. +The use of the +.B FAN_REPORT_TID +flag along with +.B FAN_REPORT_PIDFD +is currently not supported and attempting to do so will result in the +error +.B EINVAL +being returned. +This limitation is currently imposed by the pidfd API as it currently +only supports the creation of pidfds for thread-group leaders. +Creating pidfds for non-thread-group leaders may be supported at some +point in the future, +so this restriction may eventually be lifted. +For more details on information records, +see +.BR fanotify(7). +.PP The .I event_f_flags argument
man7/fanotify.7 +175 -38
260 lines not on this page · raw message
Signature · 3 lines
2.36.0.rc0.470.gd361397f0d-goog /M
Hi Matthew,
Quoted 8 lines · Matthew Bobrowski
Update the fanotify API documentation to include details on the new
FAN_REPORT_PIDFDfeature. 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 <[email protected]>Reviewed-by Jan Kara <[email protected]>Reviewed-by Amir Goldstein <[email protected]>
Quoted 7 lines
---
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
Quoted 7 lines
[0] https://lore.kernel.org/linux-man/[email protected]/
man2/fanotify_init.2 | 34 +++++++ man7/fanotify.7 | 213 +++++++++++++++++++++++++++++++++++-------- 2 files changed, 209 insertions(+), 38 deletions(-)
[...]
Quoted 4 lines
man7/fanotify.7 +0
-0
[...]
Quoted 25 lines
man7/fanotify.7 +21
-0@@ -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
man7/fanotify.7 and the file handle is followed by a null terminated string that identifies the · line 625
Quoted 10 lines
man7/fanotify.7 +8
-0+.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?
Quoted 17 lines
man7/fanotify.7 +14
-0+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 containingfanotify event metadata returned by a
.BR read (2)
Signature · 3 lines
Alejandro Colomar Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/ http://www.alejandro-colomar.es/
Quoted 32 lines · Alejandro Colomar
Hi Matthew,
Quoted 8 lines · Matthew Bobrowski
Update the fanotify API documentation to include details on the new
FAN_REPORT_PIDFDfeature. 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 <[email protected]>Reviewed-by Jan Kara <[email protected]>Reviewed-by Amir Goldstein <[email protected]>Quoted 7 lines
---
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.
Quoted 7 lines
man7/fanotify.7 +7
-0+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 .
Quoted 8 lines
man7/fanotify.7 and the file handle is followed by a null terminated string that identifies the · line 623
Quoted 5 lines
man7/fanotify.7 +5
-0+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?
I had a read through it and if we drop "for" from that sentence and add a comma after "creation", then I think this sentence reads perfectly fine. Having said that, is it necessarsy for me to resend version 6 (with your semantic newline modifications in addition to this minor rephrase), or are you OK with just amending these changes when applying the patch?
/M
Quoted 42 lines · Matthew Bobrowski
Quoted 32 lines · Alejandro Colomar
Hi Matthew,
Quoted 8 lines · Matthew Bobrowski
Update the fanotify API documentation to include details on the new
FAN_REPORT_PIDFDfeature. 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 <[email protected]>Reviewed-by Jan Kara <[email protected]>Reviewed-by Amir Goldstein <[email protected]>Quoted 7 lines
---
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.
Quoted 7 lines
man7/fanotify.7 +7
-0+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 .Quoted 8 lines
man7/fanotify.7 and the file handle is followed by a null terminated string that identifies the · line 623
Quoted 5 lines
man7/fanotify.7 +5
-0+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?
Quoted 6 lines
I had a read through it and if we drop "for" from that sentence and add a comma after "creation", then I think this sentence reads perfectly fine. Having said that, is it necessarsy for me to resend version 6 (with your semantic newline modifications in addition to this minor rephrase), or are you OK with just amending these changes when applying the patch?
v6 has been posted [0], which incorporates this change. PTAL.
/M
PATCH v5 1/1 fanotify: Document FAN_REPORT_PIDFD Feature
In reply to Matthew BobrowskiFrom: Matthew Bobrowski <[email protected]>
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.
---
v5: [alx]
further fix semantic newlines
man2/fanotify_init.2 | 36 +++++++ man7/fanotify.7 | 221 +++++++++++++++++++++++++++++++++++-------- 2 files changed, 219 insertions(+), 38 deletions(-)
man2/fanotify_init.2 +36 -0
@@ -283,6 +283,42 @@ for additional details. This is a synonym for .RB ( FAN_REPORT_DIR_FID | FAN_REPORT_NAME ). .PP +.TP +.BR FAN_REPORT_PIDFD " (since Linux 5.15)" +.\" commit af579beb666aefb17e9a335c12c788c92932baf1 +Events for fanotify groups initialized with this flag will contain +an additional information record alongside the generic +.I fanotify_event_metadata +structure. +This information record will be of type +.B FAN_EVENT_INFO_TYPE_PIDFD +and will contain a pidfd for the process that +was responsible for generating an event. +A pidfd returned in this information record object is +no different to the pidfd that is returned when calling +.BR pidfd_open(2). +Usage of this information record are for applications that +may be interested in reliably determining whether +the process responsible for generating an event +has been recycled or terminated. +The use of the +.B FAN_REPORT_TID +flag along with +.B FAN_REPORT_PIDFD +is currently not supported and +attempting to do so will result in the error +.B EINVAL +being returned. +This limitation is currently imposed by the pidfd API +as it currently only supports +the creation of pidfds for thread-group leaders. +Creating pidfds for non-thread-group leaders +may be supported at some point in the future, +so this restriction may eventually be lifted. +For more details on information records, +see +.BR fanotify(7). +.PP The .I event_f_flags argument
man7/fanotify.7 +183 -38
268 lines not on this page · raw message
Signature · 1 line
2.36.0