Skip to contentSkip to conversation

fanotify: Document FAN_REPORT_PIDFD Feature

PATCH Superseded Matthew Bobrowski 2 participants 5 messages Apr 19, 2022 – May 24, 2022 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

v4 of 6 Superseded Latest is v6 →

lore
Share & tools
lore
#0 lore raw

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
index 7f9a21a52..3dc17c5c7 100644
@@ -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
#1 lore raw

Hi Matthew,

Quoted 8 lines · Matthew Bobrowski

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.

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
index f8345b3f5..bf648782c 100644

[...]

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 containing

fanotify 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/
#2 lore raw
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_PIDFD feature. This patch also includes a generic section describing the concept of information records which are supported by the fanotify API.

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

#3 lore raw
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_PIDFD feature. This patch also includes a generic section describing the concept of information records which are supported by the fanotify API.

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.

[0] https://lore.kernel.org/linux-man/83b96ea91e5da1bdc092b34ab92bd5d1db4dbee0.1653371709.git.repnop@google.com/T/#u

/M

#4 lore raw

PATCH v5 1/1 fanotify: Document FAN_REPORT_PIDFD Feature

In reply to Matthew Bobrowski

From: 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
index 7f9a21a52..03d0b1711 100644
@@ -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