[PATCH 0/1] fanotify: Document FAN_REPORT_PIDFD Feature

[PATCH 0/1] fanotify: Document FAN_REPORT_PIDFD Feature

[Matthew Bobrowski]

Hi Michael,

This patch series documents the new FAN_REPORT_PIDFD feature that is
available from v5.15.

Note that this patch series is diffbased against the FANOTIFY_UNPRIV
[0, 1] man page updates that are yet to be merged with upstream. That
said, if you could please merge the FANOTIFY_UNPRIV updates first
followed by the FAN_REPORT_PIDFD updates, that would be much
appreciated.

[0] https://lore.kernel.org/linux-man/20210318160817.3586288-1-amir73il@gmail.com/
[1] https://github.com/amir73il/man-pages/commits/fanotify_unpriv

Matthew Bobrowski (1):
  Document the new fanotify initialization flag FAN_REPORT_PIDFD.

 man2/fanotify_init.2 | 54 +++++++++++++++++++++++++
 man7/fanotify.7      | 95 +++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 147 insertions(+), 2 deletions(-)

-- 
2.33.0.1079.g6e70778dc9-goog

/M

[PATCH 1/1] Document the new fanotify initialization flag FAN_REPORT_PIDFD

[Matthew Bobrowski]

This provides an explanation on the kind of additional information that can
be returned alongside the generic struct fanotify_event_metadata and in
what form this additional contextual information is delievered to a
listening application.

Signed-off-by: Matthew Bobrowski <repnop@google.com>
---
 man2/fanotify_init.2 | 54 +++++++++++++++++++++++++
 man7/fanotify.7      | 95 +++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 147 insertions(+), 2 deletions(-)

diff --git a/man2/fanotify_init.2 b/man2/fanotify_init.2
index 0d83e817f..f65b4fa10 100644
--- a/man2/fanotify_init.2
+++ b/man2/fanotify_init.2
@@ -298,6 +298,60 @@ for additional details.
 This is a synonym for
 .RB ( FAN_REPORT_DIR_FID | FAN_REPORT_NAME ).
 .PP
+.TP
+.B FAN_REPORT_PIDFD " (since Linux 5.15)"
+Events for fanotify groups initialized with this flag will contain an
+additional information record object alongside the generic fanotify
+event metadata structure.
+This additional information record will be of type
+.BR FAN_EVENT_INFO_TYPE_PIDFD
+and will contain a pidfd for the process that was responsible for
+generating an event.
+The returned pidfd within the information object is indistinguishable
+from a pidfd that is obtained via
+.BR pidfd_open(2).
+Usage of this additional information record object is for applications
+that are interested in reliably determining whether the process
+responsible for generating the event has either been recycled or
+terminated.
+In the instance that either
+.BR FAN_REPORT_FID
+or
+.BR FAN_REPORT_DFID_NAME
+are supplied along with
+.BR FAN_REPORT_PIDFD
+information record objects of type
+.BR FAN_EVENT_INFO_TYPE_FID,
+.BR FAN_EVENT_INFO_TYPE_DFID
+and
+.BR FAN_EVENT_INFO_TYPE_DFID_NAME
+will likely precede the information object of type
+.BR FAN_EVENT_INFO_TYPE_PIDFD
+for a single event within the read buffer.
+However, an event listener should never work with this information object
+ordering assumption and is encouraged to always check the information type
+set within the
+.IR fanotify_event_info_header
+of each information object.
+The use of the
+.BR FAN_REPORT_TID
+flag along with
+.BR FAN_REPORT_PIDFD
+is currently not supported and attempting to do so will result in the
+error
+.BR EINVAL
+being returned.
+This limitation is 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.
+Additional pidfd specific error cases can be reported back to the
+listening application in an information record object of type
+.BR FAN_EVENT_INFO_TYPE_PIDFD.
+See
+.BR fanotify(7)
+for additional details.
+.PP
 The
 .I event_f_flags
 argument
diff --git a/man7/fanotify.7 b/man7/fanotify.7
index 455e3ed17..09fa4defb 100644
--- a/man7/fanotify.7
+++ b/man7/fanotify.7
@@ -141,12 +141,24 @@ until either a file event occurs or the call is interrupted by a signal
 The use of one of the flags
 .BR FAN_REPORT_FID ,
 .BR FAN_REPORT_DIR_FID
+or
+.BR FAN_REPORT_PIDFD
 in
 .BR fanotify_init (2)
 influences what data structures are returned to the event listener for each
 event.
-Events reported to a group initialized with one of these flags will
-use file handles to identify filesystem objects instead of file descriptors.
+Events reported to a group initialized with one of either
+.BR FAN_REPORT_FID
+or
+.BR FAN_REPORT_DIR_FID
+flags will use file handles to identify filesystem objects instead of
+file descriptors.
+Events reported to a group intialized with
+.BR FAN_REPORT_PIDFD
+will attempt to also create a process file descriptor, commonly
+referred to as a pidfd, for the process responsible for generating the
+event and provide that alongside the generic fanotify metadata event
+structure.
 .PP
 After a successful
 .BR read (2),
@@ -188,6 +200,27 @@ struct fanotify_event_info_fid {
 .EE
 .in
 .PP
+In the instance that the fanotify group has been initialized with
+.BR FAN_REPORT_PIDFD ,
+the listening application should expect to receive a single
+information record object as detailed below alongside the generic
+.I fanotify_event_metadata structure:
+.PP
+.in +4n
+.EX
+struct fanotify_event_info_header {
+    __u8 info_type;
+    __u8 pad;
+    __u16 len;
+};
+
+struct fanotify_event_info_pidfd {
+        struct fanotify_event_info_header hdr;
+        __s32 pidfd;
+};
+.EE
+.in
+.PP
 For performance reasons, it is recommended to use a large
 buffer size (for example, 4096 bytes),
 so that multiple events can be retrieved by a single
@@ -510,6 +543,64 @@ 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 .
+Exactly like the one that is provided in a
+.I fanotify_event_info_fid
+structure, it is a generic header that contains information used to
+describe an additional information record object that is attached to
+an event.
+In the instance that
+.BR FAN_REPORT_PIDFD
+is supplied during fanotify group initialization, a single information
+record object is expected to be attached alongside the generic
+metadata event with its
+.I info_type
+field set to the value of
+.BR FAN_EVENT_INFO_TYPE_PIDFD .
+The
+.I fanotify_event_info_header
+structure also contains a
+.I len
+field.
+The value of the
+.I len
+field is the total size of the
+.I fanotify_event_info_pidfd
+structure, which also includes
+.IR fanotify_event_info_header .
+.TP
+.I pidfd
+This is a file descriptor that refers to the process responsible for
+generating the event.
+This returned 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
+an event, one of two possible error types represented by a negative
+integer value may be returned in this
+.I pidfd
+field.
+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 a
+.BR FAN_NOPIDFD
+is returned.
+The pidfd allocation 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 application 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)
-- 
2.33.0.1079.g6e70778dc9-goog

/M

Re: [PATCH 1/1] Document the new fanotify initialization flag FAN_REPORT_PIDFD

[Jan Kara]

On Wed 27-10-21 20:28:27, Matthew Bobrowski wrote:
> This provides an explanation on the kind of additional information that can
> be returned alongside the generic struct fanotify_event_metadata and in
> what form this additional contextual information is delievered to a
> listening application.
> 
> Signed-off-by: Matthew Bobrowski <repnop@google.com>

Looks good. Feel free to add:

Reviewed-by: Jan Kara <jack@suse.cz>

								Honza

> ---
>  man2/fanotify_init.2 | 54 +++++++++++++++++++++++++
>  man7/fanotify.7      | 95 +++++++++++++++++++++++++++++++++++++++++++-
>  2 files changed, 147 insertions(+), 2 deletions(-)
> 
> diff --git a/man2/fanotify_init.2 b/man2/fanotify_init.2
> index 0d83e817f..f65b4fa10 100644
> --- a/man2/fanotify_init.2
> +++ b/man2/fanotify_init.2
> @@ -298,6 +298,60 @@ for additional details.
>  This is a synonym for
>  .RB ( FAN_REPORT_DIR_FID | FAN_REPORT_NAME ).
>  .PP
> +.TP
> +.B FAN_REPORT_PIDFD " (since Linux 5.15)"
> +Events for fanotify groups initialized with this flag will contain an
> +additional information record object alongside the generic fanotify
> +event metadata structure.
> +This additional information record will be of type
> +.BR FAN_EVENT_INFO_TYPE_PIDFD
> +and will contain a pidfd for the process that was responsible for
> +generating an event.
> +The returned pidfd within the information object is indistinguishable
> +from a pidfd that is obtained via
> +.BR pidfd_open(2).
> +Usage of this additional information record object is for applications
> +that are interested in reliably determining whether the process
> +responsible for generating the event has either been recycled or
> +terminated.
> +In the instance that either
> +.BR FAN_REPORT_FID
> +or
> +.BR FAN_REPORT_DFID_NAME
> +are supplied along with
> +.BR FAN_REPORT_PIDFD
> +information record objects of type
> +.BR FAN_EVENT_INFO_TYPE_FID,
> +.BR FAN_EVENT_INFO_TYPE_DFID
> +and
> +.BR FAN_EVENT_INFO_TYPE_DFID_NAME
> +will likely precede the information object of type
> +.BR FAN_EVENT_INFO_TYPE_PIDFD
> +for a single event within the read buffer.
> +However, an event listener should never work with this information object
> +ordering assumption and is encouraged to always check the information type
> +set within the
> +.IR fanotify_event_info_header
> +of each information object.
> +The use of the
> +.BR FAN_REPORT_TID
> +flag along with
> +.BR FAN_REPORT_PIDFD
> +is currently not supported and attempting to do so will result in the
> +error
> +.BR EINVAL
> +being returned.
> +This limitation is 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.
> +Additional pidfd specific error cases can be reported back to the
> +listening application in an information record object of type
> +.BR FAN_EVENT_INFO_TYPE_PIDFD.
> +See
> +.BR fanotify(7)
> +for additional details.
> +.PP
>  The
>  .I event_f_flags
>  argument
> diff --git a/man7/fanotify.7 b/man7/fanotify.7
> index 455e3ed17..09fa4defb 100644
> --- a/man7/fanotify.7
> +++ b/man7/fanotify.7
> @@ -141,12 +141,24 @@ until either a file event occurs or the call is interrupted by a signal
>  The use of one of the flags
>  .BR FAN_REPORT_FID ,
>  .BR FAN_REPORT_DIR_FID
> +or
> +.BR FAN_REPORT_PIDFD
>  in
>  .BR fanotify_init (2)
>  influences what data structures are returned to the event listener for each
>  event.
> -Events reported to a group initialized with one of these flags will
> -use file handles to identify filesystem objects instead of file descriptors.
> +Events reported to a group initialized with one of either
> +.BR FAN_REPORT_FID
> +or
> +.BR FAN_REPORT_DIR_FID
> +flags will use file handles to identify filesystem objects instead of
> +file descriptors.
> +Events reported to a group intialized with
> +.BR FAN_REPORT_PIDFD
> +will attempt to also create a process file descriptor, commonly
> +referred to as a pidfd, for the process responsible for generating the
> +event and provide that alongside the generic fanotify metadata event
> +structure.
>  .PP
>  After a successful
>  .BR read (2),
> @@ -188,6 +200,27 @@ struct fanotify_event_info_fid {
>  .EE
>  .in
>  .PP
> +In the instance that the fanotify group has been initialized with
> +.BR FAN_REPORT_PIDFD ,
> +the listening application should expect to receive a single
> +information record object as detailed below alongside the generic
> +.I fanotify_event_metadata structure:
> +.PP
> +.in +4n
> +.EX
> +struct fanotify_event_info_header {
> +    __u8 info_type;
> +    __u8 pad;
> +    __u16 len;
> +};
> +
> +struct fanotify_event_info_pidfd {
> +        struct fanotify_event_info_header hdr;
> +        __s32 pidfd;
> +};
> +.EE
> +.in
> +.PP
>  For performance reasons, it is recommended to use a large
>  buffer size (for example, 4096 bytes),
>  so that multiple events can be retrieved by a single
> @@ -510,6 +543,64 @@ 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 .
> +Exactly like the one that is provided in a
> +.I fanotify_event_info_fid
> +structure, it is a generic header that contains information used to
> +describe an additional information record object that is attached to
> +an event.
> +In the instance that
> +.BR FAN_REPORT_PIDFD
> +is supplied during fanotify group initialization, a single information
> +record object is expected to be attached alongside the generic
> +metadata event with its
> +.I info_type
> +field set to the value of
> +.BR FAN_EVENT_INFO_TYPE_PIDFD .
> +The
> +.I fanotify_event_info_header
> +structure also contains a
> +.I len
> +field.
> +The value of the
> +.I len
> +field is the total size of the
> +.I fanotify_event_info_pidfd
> +structure, which also includes
> +.IR fanotify_event_info_header .
> +.TP
> +.I pidfd
> +This is a file descriptor that refers to the process responsible for
> +generating the event.
> +This returned 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
> +an event, one of two possible error types represented by a negative
> +integer value may be returned in this
> +.I pidfd
> +field.
> +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 a
> +.BR FAN_NOPIDFD
> +is returned.
> +The pidfd allocation 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 application 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)
> -- 
> 2.33.0.1079.g6e70778dc9-goog
> 
> /M
-- 
Jan Kara <jack@suse.com>
SUSE Labs, CR

Re: [PATCH 1/1] Document the new fanotify initialization flag FAN_REPORT_PIDFD

[Amir Goldstein]

On Wed, Oct 27, 2021 at 12:28 PM Matthew Bobrowski <repnop@google.com> wrote:
>
> This provides an explanation on the kind of additional information that can
> be returned alongside the generic struct fanotify_event_metadata and in
> what form this additional contextual information is delievered to a
> listening application.
>
> Signed-off-by: Matthew Bobrowski <repnop@google.com>
> ---
>  man2/fanotify_init.2 | 54 +++++++++++++++++++++++++
>  man7/fanotify.7      | 95 +++++++++++++++++++++++++++++++++++++++++++-
>  2 files changed, 147 insertions(+), 2 deletions(-)
>
> diff --git a/man2/fanotify_init.2 b/man2/fanotify_init.2
> index 0d83e817f..f65b4fa10 100644
> --- a/man2/fanotify_init.2
> +++ b/man2/fanotify_init.2
> @@ -298,6 +298,60 @@ for additional details.
>  This is a synonym for
>  .RB ( FAN_REPORT_DIR_FID | FAN_REPORT_NAME ).
>  .PP
> +.TP
> +.B FAN_REPORT_PIDFD " (since Linux 5.15)"
> +Events for fanotify groups initialized with this flag will contain an
> +additional information record object alongside the generic fanotify
> +event metadata structure.
> +This additional information record will be of type
> +.BR FAN_EVENT_INFO_TYPE_PIDFD
> +and will contain a pidfd for the process that was responsible for
> +generating an event.
> +The returned pidfd within the information object is indistinguishable
> +from a pidfd that is obtained via
> +.BR pidfd_open(2).
> +Usage of this additional information record object is for applications
> +that are interested in reliably determining whether the process
> +responsible for generating the event has either been recycled or
> +terminated.
> +In the instance that either
> +.BR FAN_REPORT_FID
> +or
> +.BR FAN_REPORT_DFID_NAME
> +are supplied along with
> +.BR FAN_REPORT_PIDFD
> +information record objects of type
> +.BR FAN_EVENT_INFO_TYPE_FID,
> +.BR FAN_EVENT_INFO_TYPE_DFID
> +and
> +.BR FAN_EVENT_INFO_TYPE_DFID_NAME
> +will likely precede the information object of type

Please get rid of "likely to precede"

> +.BR FAN_EVENT_INFO_TYPE_PIDFD
> +for a single event within the read buffer.
> +However, an event listener should never work with this information object
> +ordering assumption and is encouraged to always check the information type

"However" "encouraged" are too weak to my taste.

An event listener should not assume any specific order for information records
within an event and must always check the information type...

> +set within the
> +.IR fanotify_event_info_header
> +of each information object.
> +The use of the
> +.BR FAN_REPORT_TID
> +flag along with
> +.BR FAN_REPORT_PIDFD
> +is currently not supported and attempting to do so will result in the
> +error
> +.BR EINVAL
> +being returned.
> +This limitation is 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.
> +Additional pidfd specific error cases can be reported back to the
> +listening application in an information record object of type
> +.BR FAN_EVENT_INFO_TYPE_PIDFD.
> +See
> +.BR fanotify(7)
> +for additional details.
> +.PP
>  The
>  .I event_f_flags
>  argument
> diff --git a/man7/fanotify.7 b/man7/fanotify.7
> index 455e3ed17..09fa4defb 100644
> --- a/man7/fanotify.7
> +++ b/man7/fanotify.7
> @@ -141,12 +141,24 @@ until either a file event occurs or the call is interrupted by a signal
>  The use of one of the flags
>  .BR FAN_REPORT_FID ,
>  .BR FAN_REPORT_DIR_FID
> +or
> +.BR FAN_REPORT_PIDFD
>  in
>  .BR fanotify_init (2)
>  influences what data structures are returned to the event listener for each
>  event.
> -Events reported to a group initialized with one of these flags will
> -use file handles to identify filesystem objects instead of file descriptors.
> +Events reported to a group initialized with one of either
> +.BR FAN_REPORT_FID
> +or
> +.BR FAN_REPORT_DIR_FID
> +flags will use file handles to identify filesystem objects instead of
> +file descriptors.
> +Events reported to a group intialized with
> +.BR FAN_REPORT_PIDFD
> +will attempt to also create a process file descriptor, commonly
> +referred to as a pidfd, for the process responsible for generating the
> +event and provide that alongside the generic fanotify metadata event
> +structure.
>  .PP
>  After a successful
>  .BR read (2),
> @@ -188,6 +200,27 @@ struct fanotify_event_info_fid {
>  .EE
>  .in
>  .PP
> +In the instance that the fanotify group has been initialized with
> +.BR FAN_REPORT_PIDFD ,
> +the listening application should expect to receive a single
> +information record object as detailed below alongside the generic
> +.I fanotify_event_metadata structure:
> +.PP
> +.in +4n
> +.EX
> +struct fanotify_event_info_header {
> +    __u8 info_type;
> +    __u8 pad;
> +    __u16 len;
> +};

This structure was just listed a few lines up.
There is no need to re-list it here.

> +
> +struct fanotify_event_info_pidfd {
> +        struct fanotify_event_info_header hdr;
> +        __s32 pidfd;
> +};
> +.EE
> +.in
> +.PP
>  For performance reasons, it is recommended to use a large
>  buffer size (for example, 4096 bytes),
>  so that multiple events can be retrieved by a single
> @@ -510,6 +543,64 @@ 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 .
> +Exactly like the one that is provided in a
> +.I fanotify_event_info_fid
> +structure, it is a generic header that contains information used to
> +describe an additional information record object that is attached to
> +an event.
> +In the instance that
> +.BR FAN_REPORT_PIDFD
> +is supplied during fanotify group initialization, a single information
> +record object is expected to be attached alongside the generic
> +metadata event with its
> +.I info_type
> +field set to the value of
> +.BR FAN_EVENT_INFO_TYPE_PIDFD .
> +The
> +.I fanotify_event_info_header
> +structure also contains a
> +.I len
> +field.
> +The value of the
> +.I len
> +field is the total size of the
> +.I fanotify_event_info_pidfd
> +structure, which also includes
> +.IR fanotify_event_info_header .

It would be a shame if we needed to repeat the same text for every new info_type
that we add. There should be no duplicate documentation of the
fanotify_event_info_header fields. Perhaps we need to describe those fields
before documenting fanotify_event_info_fid fields instead of inline in the
documentation of hdr field.

Thanks,
Amir.

Re: [PATCH 1/1] Document the new fanotify initialization flag FAN_REPORT_PIDFD

[Matthew Bobrowski]

On Wed, Oct 27, 2021 at 01:14:49PM +0300, Amir Goldstein wrote:
> On Wed, Oct 27, 2021 at 12:28 PM Matthew Bobrowski <repnop@google.com> wrote:
> >
> > This provides an explanation on the kind of additional information that can
> > be returned alongside the generic struct fanotify_event_metadata and in
> > what form this additional contextual information is delievered to a
> > listening application.
> >
> > Signed-off-by: Matthew Bobrowski <repnop@google.com>
> > ---
> >  man2/fanotify_init.2 | 54 +++++++++++++++++++++++++
> >  man7/fanotify.7      | 95 +++++++++++++++++++++++++++++++++++++++++++-
> >  2 files changed, 147 insertions(+), 2 deletions(-)
> >
> > diff --git a/man2/fanotify_init.2 b/man2/fanotify_init.2
> > index 0d83e817f..f65b4fa10 100644
> > --- a/man2/fanotify_init.2
> > +++ b/man2/fanotify_init.2
> > @@ -298,6 +298,60 @@ for additional details.
> >  This is a synonym for
> >  .RB ( FAN_REPORT_DIR_FID | FAN_REPORT_NAME ).
> >  .PP
> > +.TP
> > +.B FAN_REPORT_PIDFD " (since Linux 5.15)"
> > +Events for fanotify groups initialized with this flag will contain an
> > +additional information record object alongside the generic fanotify
> > +event metadata structure.
> > +This additional information record will be of type
> > +.BR FAN_EVENT_INFO_TYPE_PIDFD
> > +and will contain a pidfd for the process that was responsible for
> > +generating an event.
> > +The returned pidfd within the information object is indistinguishable
> > +from a pidfd that is obtained via
> > +.BR pidfd_open(2).
> > +Usage of this additional information record object is for applications
> > +that are interested in reliably determining whether the process
> > +responsible for generating the event has either been recycled or
> > +terminated.
> > +In the instance that either
> > +.BR FAN_REPORT_FID
> > +or
> > +.BR FAN_REPORT_DFID_NAME
> > +are supplied along with
> > +.BR FAN_REPORT_PIDFD
> > +information record objects of type
> > +.BR FAN_EVENT_INFO_TYPE_FID,
> > +.BR FAN_EVENT_INFO_TYPE_DFID
> > +and
> > +.BR FAN_EVENT_INFO_TYPE_DFID_NAME
> > +will likely precede the information object of type
> 
> Please get rid of "likely to precede"

ACK.

> > +.BR FAN_EVENT_INFO_TYPE_PIDFD
> > +for a single event within the read buffer.
> > +However, an event listener should never work with this information object
> > +ordering assumption and is encouraged to always check the information type
> 
> "However" "encouraged" are too weak to my taste.
> 
> An event listener should not assume any specific order for information records
> within an event and must always check the information type...

ACK.

> > +set within the
> > +.IR fanotify_event_info_header
> > +of each information object.
> > +The use of the
> > +.BR FAN_REPORT_TID
> > +flag along with
> > +.BR FAN_REPORT_PIDFD
> > +is currently not supported and attempting to do so will result in the
> > +error
> > +.BR EINVAL
> > +being returned.
> > +This limitation is 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.
> > +Additional pidfd specific error cases can be reported back to the
> > +listening application in an information record object of type
> > +.BR FAN_EVENT_INFO_TYPE_PIDFD.
> > +See
> > +.BR fanotify(7)
> > +for additional details.
> > +.PP
> >  The
> >  .I event_f_flags
> >  argument
> > diff --git a/man7/fanotify.7 b/man7/fanotify.7
> > index 455e3ed17..09fa4defb 100644
> > --- a/man7/fanotify.7
> > +++ b/man7/fanotify.7
> > @@ -141,12 +141,24 @@ until either a file event occurs or the call is interrupted by a signal
> >  The use of one of the flags
> >  .BR FAN_REPORT_FID ,
> >  .BR FAN_REPORT_DIR_FID
> > +or
> > +.BR FAN_REPORT_PIDFD
> >  in
> >  .BR fanotify_init (2)
> >  influences what data structures are returned to the event listener for each
> >  event.
> > -Events reported to a group initialized with one of these flags will
> > -use file handles to identify filesystem objects instead of file descriptors.
> > +Events reported to a group initialized with one of either
> > +.BR FAN_REPORT_FID
> > +or
> > +.BR FAN_REPORT_DIR_FID
> > +flags will use file handles to identify filesystem objects instead of
> > +file descriptors.
> > +Events reported to a group intialized with
> > +.BR FAN_REPORT_PIDFD
> > +will attempt to also create a process file descriptor, commonly
> > +referred to as a pidfd, for the process responsible for generating the
> > +event and provide that alongside the generic fanotify metadata event
> > +structure.
> >  .PP
> >  After a successful
> >  .BR read (2),
> > @@ -188,6 +200,27 @@ struct fanotify_event_info_fid {
> >  .EE
> >  .in
> >  .PP
> > +In the instance that the fanotify group has been initialized with
> > +.BR FAN_REPORT_PIDFD ,
> > +the listening application should expect to receive a single
> > +information record object as detailed below alongside the generic
> > +.I fanotify_event_metadata structure:
> > +.PP
> > +.in +4n
> > +.EX
> > +struct fanotify_event_info_header {
> > +    __u8 info_type;
> > +    __u8 pad;
> > +    __u16 len;
> > +};
> 
> This structure was just listed a few lines up.
> There is no need to re-list it here.

ACK.

> > +
> > +struct fanotify_event_info_pidfd {
> > +        struct fanotify_event_info_header hdr;
> > +        __s32 pidfd;
> > +};
> > +.EE
> > +.in
> > +.PP
> >  For performance reasons, it is recommended to use a large
> >  buffer size (for example, 4096 bytes),
> >  so that multiple events can be retrieved by a single
> > @@ -510,6 +543,64 @@ 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 .
> > +Exactly like the one that is provided in a
> > +.I fanotify_event_info_fid
> > +structure, it is a generic header that contains information used to
> > +describe an additional information record object that is attached to
> > +an event.
> > +In the instance that
> > +.BR FAN_REPORT_PIDFD
> > +is supplied during fanotify group initialization, a single information
> > +record object is expected to be attached alongside the generic
> > +metadata event with its
> > +.I info_type
> > +field set to the value of
> > +.BR FAN_EVENT_INFO_TYPE_PIDFD .
> > +The
> > +.I fanotify_event_info_header
> > +structure also contains a
> > +.I len
> > +field.
> > +The value of the
> > +.I len
> > +field is the total size of the
> > +.I fanotify_event_info_pidfd
> > +structure, which also includes
> > +.IR fanotify_event_info_header .
> 
> It would be a shame if we needed to repeat the same text for every new info_type
> that we add. There should be no duplicate documentation of the
> fanotify_event_info_header fields. Perhaps we need to describe those fields
> before documenting fanotify_event_info_fid fields instead of inline in the
> documentation of hdr field.

Right, I see where you're coming from and I do generally agree. If we
continue repeating the same pattern for each bonus event that is based
on fanotify_event_info_header, then we'll end up unnecessarily
polluting the documentation.

Would you like me to try shuffle things around in a patch that
precedes this one?

/M

Re: [PATCH 1/1] Document the new fanotify initialization flag FAN_REPORT_PIDFD

[Amir Goldstein]

> > > @@ -188,6 +200,27 @@ struct fanotify_event_info_fid {
> > >  .EE
> > >  .in
> > >  .PP
> > > +In the instance that the fanotify group has been initialized with
> > > +.BR FAN_REPORT_PIDFD ,
> > > +the listening application should expect to receive a single
> > > +information record object as detailed below alongside the generic
> > > +.I fanotify_event_metadata structure:
> > > +.PP
> > > +.in +4n
> > > +.EX
> > > +struct fanotify_event_info_header {
> > > +    __u8 info_type;
> > > +    __u8 pad;
> > > +    __u16 len;
> > > +};
> >
> > This structure was just listed a few lines up.
> > There is no need to re-list it here.
>
> ACK.
>
> > > +
> > > +struct fanotify_event_info_pidfd {
> > > +        struct fanotify_event_info_header hdr;
> > > +        __s32 pidfd;
> > > +};
> > > +.EE
> > > +.in
> > > +.PP
> > >  For performance reasons, it is recommended to use a large
> > >  buffer size (for example, 4096 bytes),
> > >  so that multiple events can be retrieved by a single
> > > @@ -510,6 +543,64 @@ 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 .
> > > +Exactly like the one that is provided in a
> > > +.I fanotify_event_info_fid
> > > +structure, it is a generic header that contains information used to
> > > +describe an additional information record object that is attached to
> > > +an event.
> > > +In the instance that
> > > +.BR FAN_REPORT_PIDFD
> > > +is supplied during fanotify group initialization, a single information
> > > +record object is expected to be attached alongside the generic
> > > +metadata event with its
> > > +.I info_type
> > > +field set to the value of
> > > +.BR FAN_EVENT_INFO_TYPE_PIDFD .
> > > +The
> > > +.I fanotify_event_info_header
> > > +structure also contains a
> > > +.I len
> > > +field.
> > > +The value of the
> > > +.I len
> > > +field is the total size of the
> > > +.I fanotify_event_info_pidfd
> > > +structure, which also includes
> > > +.IR fanotify_event_info_header .
> >
> > It would be a shame if we needed to repeat the same text for every new info_type
> > that we add. There should be no duplicate documentation of the
> > fanotify_event_info_header fields. Perhaps we need to describe those fields
> > before documenting fanotify_event_info_fid fields instead of inline in the
> > documentation of hdr field.
>
> Right, I see where you're coming from and I do generally agree. If we
> continue repeating the same pattern for each bonus event that is based
> on fanotify_event_info_header, then we'll end up unnecessarily
> polluting the documentation.
>
> Would you like me to try shuffle things around in a patch that
> precedes this one?
>

Yes, please do. Either prep patch or in same patch is fine by me.

Thanks,
Amir.

Re: [PATCH 1/1] Document the new fanotify initialization flag FAN_REPORT_PIDFD

[Alejandro Colomar (man-pages)]

Hi Matthew,

On 11/1/21 22:02, Matthew Bobrowski wrote:
> On Wed, Oct 27, 2021 at 01:14:49PM +0300, Amir Goldstein wrote:
>> On Wed, Oct 27, 2021 at 12:28 PM Matthew Bobrowski <repnop@google.com> wrote:
>>> +The
>>> +.I fanotify_event_info_header
>>> +structure also contains a
>>> +.I len
>>> +field.
>>> +The value of the
>>> +.I len
>>> +field is the total size of the
>>> +.I fanotify_event_info_pidfd
>>> +structure, which also includes
>>> +.IR fanotify_event_info_header .
>>
>> It would be a shame if we needed to repeat the same text for every new info_type
>> that we add. There should be no duplicate documentation of the
>> fanotify_event_info_header fields. Perhaps we need to describe those fields
>> before documenting fanotify_event_info_fid fields instead of inline in the
>> documentation of hdr field.
> 
> Right, I see where you're coming from and I do generally agree. If we
> continue repeating the same pattern for each bonus event that is based
> on fanotify_event_info_header, then we'll end up unnecessarily
> polluting the documentation.
> 
> Would you like me to try shuffle things around in a patch that
> precedes this one?

Sure.  Would you consider adding an entry to the system_data_types(7) 
manual page documenting that type?

Thanks,

Alex


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

Re: [PATCH 0/1] fanotify: Document FAN_REPORT_PIDFD Feature

[Amir Goldstein]

On Wed, Oct 27, 2021 at 12:28 PM Matthew Bobrowski <repnop@google.com> wrote:
>
> Hi Michael,
>
> This patch series documents the new FAN_REPORT_PIDFD feature that is
> available from v5.15.
>
> Note that this patch series is diffbased against the FANOTIFY_UNPRIV
> [0, 1] man page updates that are yet to be merged with upstream. That
> said, if you could please merge the FANOTIFY_UNPRIV updates first
> followed by the FAN_REPORT_PIDFD updates, that would be much
> appreciated.
>
> [0] https://lore.kernel.org/linux-man/20210318160817.3586288-1-amir73il@gmail.com/
> [1] https://github.com/amir73il/man-pages/commits/fanotify_unpriv
>

Alejandro,

Is there any changes of getting those long due 5.13 fanotify update
patches merged?

Matthew,

For v2 please base your own fanotify_pidfd branch on top of fanotify_unpriv
(I just rebased it to master again) and provide a branch, that Gabriel
and I could
base the next man page updates on.

Currently, neither your fanotify_pidfd patch nor Gabriel's fan-fs-error patch
conflict with fanotify_unpriv changes, but fan-fs-error does have conflicts
with fanotify_pidfd.

Thanks,
Amir.

Re: [PATCH 1/1] Document the new fanotify initialization flag FAN_REPORT_PIDFD

[Amir Goldstein]

On Wed, Oct 27, 2021 at 12:28 PM Matthew Bobrowski <repnop@google.com> wrote:
>
> This provides an explanation on the kind of additional information that can
> be returned alongside the generic struct fanotify_event_metadata and in
> what form this additional contextual information is delievered to a
> listening application.
>
> Signed-off-by: Matthew Bobrowski <repnop@google.com>
> ---
>  man2/fanotify_init.2 | 54 +++++++++++++++++++++++++
>  man7/fanotify.7      | 95 +++++++++++++++++++++++++++++++++++++++++++-
>  2 files changed, 147 insertions(+), 2 deletions(-)
>
> diff --git a/man2/fanotify_init.2 b/man2/fanotify_init.2
> index 0d83e817f..f65b4fa10 100644
> --- a/man2/fanotify_init.2
> +++ b/man2/fanotify_init.2
> @@ -298,6 +298,60 @@ for additional details.
>  This is a synonym for
>  .RB ( FAN_REPORT_DIR_FID | FAN_REPORT_NAME ).
>  .PP
> +.TP
> +.B FAN_REPORT_PIDFD " (since Linux 5.15)"

Matthew,

For v2, please document commit id.
Please also consider including below cleanup patch
to document commit ids that we missed in v5.9 update.

Thanks,
Amir.

--- a/man2/fanotify_init.2
+++ b/man2/fanotify_init.2
@@ -213,6 +213,7 @@ See
 for additional details.
 .TP
 .BR FAN_REPORT_DIR_FID " (since Linux 5.9)"
+.\" commit 83b7a59896dd24015a34b7f00027f0ff3747972f
 Events for fanotify groups initialized with this flag will contain
 (see exceptions below) additional information about a directory object
 correlated to an event.
@@ -245,6 +246,7 @@ See
 for additional details.
 .TP
 .BR FAN_REPORT_NAME " (since Linux 5.9)"
+.\" commit 929943b38daf817f2e6d303ea04401651fc3bc05
 Events for fanotify groups initialized with this flag will contain additional
 information about the name of the directory entry correlated to an event.
 This flag must be provided in conjunction with the flag

Re: [PATCH 0/1] fanotify: Document FAN_REPORT_PIDFD Feature

[Alejandro Colomar (man-pages)]

Hi Amir,

On 11/20/21 11:36, Amir Goldstein wrote:
> Alejandro,
> 
> Is there any changes of getting those long due 5.13 fanotify update
> patches merged?

I thought I was waiting for an v2,
since there was a bit of discussion in the patch thread,
and some comments hinted that there would be a v2.

See 
<https://lore.kernel.org/linux-man/12909faf-1d45-1eee-aa6c-c7704518dc59@gmail.com/>

Am I correct?


Thanks,
Alex


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

Re: [PATCH 0/1] fanotify: Document FAN_REPORT_PIDFD Feature

[Amir Goldstein]

On Sat, Nov 20, 2021 at 3:32 PM Alejandro Colomar (man-pages)
<alx.manpages@gmail.com> wrote:
>
> Hi Amir,
>
> On 11/20/21 11:36, Amir Goldstein wrote:
> > Alejandro,
> >
> > Is there any changes of getting those long due 5.13 fanotify update
> > patches merged?
>
> I thought I was waiting for an v2,
> since there was a bit of discussion in the patch thread,
> and some comments hinted that there would be a v2.
>
> See
> <https://lore.kernel.org/linux-man/12909faf-1d45-1eee-aa6c-c7704518dc59@gmail.com/>
>
> Am I correct?
>
>

v2 would be for the v5.15 update that Matthew posted (FAN_REPORT_PIDFD).

I was asking if you could merge to the v5.13 updates that I posted 9 months ago:
https://lore.kernel.org/linux-man/20210318160817.3586288-1-amir73il@gmail.com/

You can find them rebased on master in branch:
https://github.com/amir73il/man-pages/commits/fanotify_unpriv

Along with two other minor updates that I posted since.

Thanks,
Amir.

Re: [PATCH 0/1] fanotify: Document FAN_REPORT_PIDFD Feature

[Alejandro Colomar (man-pages)]

Hi Amir,

On 11/20/21 15:45, Amir Goldstein wrote:
> On Sat, Nov 20, 2021 at 3:32 PM Alejandro Colomar (man-pages)
> <alx.manpages@gmail.com> wrote:
>>
>> Hi Amir,
>>
>> On 11/20/21 11:36, Amir Goldstein wrote:
>>> Alejandro,
>>>
>>> Is there any changes of getting those long due 5.13 fanotify update
>>> patches merged?
>>
>> I thought I was waiting for an v2,
>> since there was a bit of discussion in the patch thread,
>> and some comments hinted that there would be a v2.
>>
>> See
>> <https://lore.kernel.org/linux-man/12909faf-1d45-1eee-aa6c-c7704518dc59@gmail.com/>
>>
>> Am I correct?
>>
>>
> 
> v2 would be for the v5.15 update that Matthew posted (FAN_REPORT_PIDFD).
> 
> I was asking if you could merge to the v5.13 updates that I posted 9 months ago:
> https://lore.kernel.org/linux-man/20210318160817.3586288-1-amir73il@gmail.com/

Ahh, I didn't know that one.

> 
> You can find them rebased on master in branch:
> https://github.com/amir73il/man-pages/commits/fanotify_unpriv
> 
> Along with two other minor updates that I posted since.


Would you mind sending a v2 with what you think I should merge?

Thanks,
Alex

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

Re: [PATCH 0/1] fanotify: Document FAN_REPORT_PIDFD Feature

[Amir Goldstein]

On Sat, Nov 20, 2021 at 6:51 PM Alejandro Colomar (man-pages)
<alx.manpages@gmail.com> wrote:
>
> Hi Amir,
>
> On 11/20/21 15:45, Amir Goldstein wrote:
> > On Sat, Nov 20, 2021 at 3:32 PM Alejandro Colomar (man-pages)
> > <alx.manpages@gmail.com> wrote:
> >>
> >> Hi Amir,
> >>
> >> On 11/20/21 11:36, Amir Goldstein wrote:
> >>> Alejandro,
> >>>
> >>> Is there any changes of getting those long due 5.13 fanotify update
> >>> patches merged?
> >>
> >> I thought I was waiting for an v2,
> >> since there was a bit of discussion in the patch thread,
> >> and some comments hinted that there would be a v2.
> >>
> >> See
> >> <https://lore.kernel.org/linux-man/12909faf-1d45-1eee-aa6c-c7704518dc59@gmail.com/>
> >>
> >> Am I correct?
> >>
> >>
> >
> > v2 would be for the v5.15 update that Matthew posted (FAN_REPORT_PIDFD).
> >
> > I was asking if you could merge to the v5.13 updates that I posted 9 months ago:
> > https://lore.kernel.org/linux-man/20210318160817.3586288-1-amir73il@gmail.com/
>
> Ahh, I didn't know that one.
>
> >
> > You can find them rebased on master in branch:
> > https://github.com/amir73il/man-pages/commits/fanotify_unpriv
> >
> > Along with two other minor updates that I posted since.
>
>
> Would you mind sending a v2 with what you think I should merge?
>

Will do.

Thanks,
Amir.

Re: [PATCH 0/1] fanotify: Document FAN_REPORT_PIDFD Feature

[Matthew Bobrowski]

On Sat, Nov 20, 2021 at 12:36:26PM +0200, Amir Goldstein wrote:
> On Wed, Oct 27, 2021 at 12:28 PM Matthew Bobrowski <repnop@google.com> wrote:
> >
> > Hi Michael,
> >
> > This patch series documents the new FAN_REPORT_PIDFD feature that is
> > available from v5.15.
> >
> > Note that this patch series is diffbased against the FANOTIFY_UNPRIV
> > [0, 1] man page updates that are yet to be merged with upstream. That
> > said, if you could please merge the FANOTIFY_UNPRIV updates first
> > followed by the FAN_REPORT_PIDFD updates, that would be much
> > appreciated.
> >
> > [0] https://lore.kernel.org/linux-man/20210318160817.3586288-1-amir73il@gmail.com/
> > [1] https://github.com/amir73il/man-pages/commits/fanotify_unpriv
> >
> 
> Alejandro,
> 
> Is there any changes of getting those long due 5.13 fanotify update
> patches merged?
> 
> Matthew,
> 
> For v2 please base your own fanotify_pidfd branch on top of fanotify_unpriv
> (I just rebased it to master again) and provide a branch, that Gabriel
> and I could
> base the next man page updates on.
> 
> Currently, neither your fanotify_pidfd patch nor Gabriel's fan-fs-error patch
> conflict with fanotify_unpriv changes, but fan-fs-error does have conflicts
> with fanotify_pidfd.

ACK.

As per request, v2 of the FAN_REPORT_PIDFD documentation can be found
here [0].

The branch fanotify_pidfd_v2 is based off your fanotify_unpriv
branch. I'd like to post through this series at some point tomorrow,
so if you could PTAL in the interim, that'd be appreciated.

I've incorporated the explicit documentation of the
fanotify_event_info_header structure, rather than duplicating field
explanations of such a structure across each information record types
as we had discussed.

[0] https://github.com/matthewbobrowski/man-pages/tree/fanotify_pidfd_v2

/M

Re: [PATCH 1/1] Document the new fanotify initialization flag FAN_REPORT_PIDFD

[Matthew Bobrowski]

On Sat, Nov 20, 2021 at 02:19:38PM +0200, Amir Goldstein wrote:
> On Wed, Oct 27, 2021 at 12:28 PM Matthew Bobrowski <repnop@google.com> wrote:
> >
> > This provides an explanation on the kind of additional information that can
> > be returned alongside the generic struct fanotify_event_metadata and in
> > what form this additional contextual information is delievered to a
> > listening application.
> >
> > Signed-off-by: Matthew Bobrowski <repnop@google.com>
> > ---
> >  man2/fanotify_init.2 | 54 +++++++++++++++++++++++++
> >  man7/fanotify.7      | 95 +++++++++++++++++++++++++++++++++++++++++++-
> >  2 files changed, 147 insertions(+), 2 deletions(-)
> >
> > diff --git a/man2/fanotify_init.2 b/man2/fanotify_init.2
> > index 0d83e817f..f65b4fa10 100644
> > --- a/man2/fanotify_init.2
> > +++ b/man2/fanotify_init.2
> > @@ -298,6 +298,60 @@ for additional details.
> >  This is a synonym for
> >  .RB ( FAN_REPORT_DIR_FID | FAN_REPORT_NAME ).
> >  .PP
> > +.TP
> > +.B FAN_REPORT_PIDFD " (since Linux 5.15)"
> 
> Matthew,
> 
> For v2, please document commit id.
> Please also consider including below cleanup patch
> to document commit ids that we missed in v5.9 update.

ACK.

PTAL [0]. BTW, the cleanup patch you referenced appears to be in your
fanotify_unpriv [1] branch, and my fanotify_pidfd_v2 [2] is based off
fanotify_unpriv, so we should be good here.

> 
> --- a/man2/fanotify_init.2
> +++ b/man2/fanotify_init.2
> @@ -213,6 +213,7 @@ See
>  for additional details.
>  .TP
>  .BR FAN_REPORT_DIR_FID " (since Linux 5.9)"
> +.\" commit 83b7a59896dd24015a34b7f00027f0ff3747972f
>  Events for fanotify groups initialized with this flag will contain
>  (see exceptions below) additional information about a directory object
>  correlated to an event.
> @@ -245,6 +246,7 @@ See
>  for additional details.
>  .TP
>  .BR FAN_REPORT_NAME " (since Linux 5.9)"
> +.\" commit 929943b38daf817f2e6d303ea04401651fc3bc05
>  Events for fanotify groups initialized with this flag will contain additional
>  information about the name of the directory entry correlated to an event.
>  This flag must be provided in conjunction with the flag

[0] https://github.com/matthewbobrowski/man-pages/commit/070c144b2f92acffa752ee10ea0c239ee5258b72
[1] https://github.com/amir73il/man-pages/tree/fanotify_unpriv
[2] https://github.com/matthewbobrowski/man-pages/tree/fanotify_pidfd_v2

/M

Re: [PATCH 0/1] fanotify: Document FAN_REPORT_PIDFD Feature

[Amir Goldstein]

On Mon, Nov 22, 2021 at 1:19 PM Matthew Bobrowski <repnop@google.com> wrote:
>
> On Sat, Nov 20, 2021 at 12:36:26PM +0200, Amir Goldstein wrote:
> > On Wed, Oct 27, 2021 at 12:28 PM Matthew Bobrowski <repnop@google.com> wrote:
> > >
> > > Hi Michael,
> > >
> > > This patch series documents the new FAN_REPORT_PIDFD feature that is
> > > available from v5.15.
> > >
> > > Note that this patch series is diffbased against the FANOTIFY_UNPRIV
> > > [0, 1] man page updates that are yet to be merged with upstream. That
> > > said, if you could please merge the FANOTIFY_UNPRIV updates first
> > > followed by the FAN_REPORT_PIDFD updates, that would be much
> > > appreciated.
> > >
> > > [0] https://lore.kernel.org/linux-man/20210318160817.3586288-1-amir73il@gmail.com/
> > > [1] https://github.com/amir73il/man-pages/commits/fanotify_unpriv
> > >
> >
> > Alejandro,
> >
> > Is there any changes of getting those long due 5.13 fanotify update
> > patches merged?
> >
> > Matthew,
> >
> > For v2 please base your own fanotify_pidfd branch on top of fanotify_unpriv
> > (I just rebased it to master again) and provide a branch, that Gabriel
> > and I could
> > base the next man page updates on.
> >
> > Currently, neither your fanotify_pidfd patch nor Gabriel's fan-fs-error patch
> > conflict with fanotify_unpriv changes, but fan-fs-error does have conflicts
> > with fanotify_pidfd.
>
> ACK.
>
> As per request, v2 of the FAN_REPORT_PIDFD documentation can be found
> here [0].
>
> The branch fanotify_pidfd_v2 is based off your fanotify_unpriv
> branch. I'd like to post through this series at some point tomorrow,
> so if you could PTAL in the interim, that'd be appreciated.
>
> I've incorporated the explicit documentation of the
> fanotify_event_info_header structure, rather than duplicating field
> explanations of such a structure across each information record types
> as we had discussed.
>
> [0] https://github.com/matthewbobrowski/man-pages/tree/fanotify_pidfd_v2
>

Hi Mattew,

I'm basically fine with most of the text in the sections, but
the sections need some reordering IMO to make more sense.
High level, I think it should look something like:

- "...the read buffer contains one or more struct fanotify_event_metadata..."
- Text about several optional information records in event
- Explain about fanotify_event_info_header and info_type
- List of fanotify_event_info_* that belong to specific info types

Commented in github.

Thanks,
Amir.

Re: [PATCH 0/1] fanotify: Document FAN_REPORT_PIDFD Feature

[Matthew Bobrowski]

On Mon, Nov 22, 2021 at 03:37:30PM +0200, Amir Goldstein wrote:
> On Mon, Nov 22, 2021 at 1:19 PM Matthew Bobrowski <repnop@google.com> wrote:
> >
> > On Sat, Nov 20, 2021 at 12:36:26PM +0200, Amir Goldstein wrote:
> > > On Wed, Oct 27, 2021 at 12:28 PM Matthew Bobrowski <repnop@google.com> wrote:
> > > >
> > > > Hi Michael,
> > > >
> > > > This patch series documents the new FAN_REPORT_PIDFD feature that is
> > > > available from v5.15.
> > > >
> > > > Note that this patch series is diffbased against the FANOTIFY_UNPRIV
> > > > [0, 1] man page updates that are yet to be merged with upstream. That
> > > > said, if you could please merge the FANOTIFY_UNPRIV updates first
> > > > followed by the FAN_REPORT_PIDFD updates, that would be much
> > > > appreciated.
> > > >
> > > > [0] https://lore.kernel.org/linux-man/20210318160817.3586288-1-amir73il@gmail.com/
> > > > [1] https://github.com/amir73il/man-pages/commits/fanotify_unpriv
> > > >
> > >
> > > Alejandro,
> > >
> > > Is there any changes of getting those long due 5.13 fanotify update
> > > patches merged?
> > >
> > > Matthew,
> > >
> > > For v2 please base your own fanotify_pidfd branch on top of fanotify_unpriv
> > > (I just rebased it to master again) and provide a branch, that Gabriel
> > > and I could
> > > base the next man page updates on.
> > >
> > > Currently, neither your fanotify_pidfd patch nor Gabriel's fan-fs-error patch
> > > conflict with fanotify_unpriv changes, but fan-fs-error does have conflicts
> > > with fanotify_pidfd.
> >
> > ACK.
> >
> > As per request, v2 of the FAN_REPORT_PIDFD documentation can be found
> > here [0].
> >
> > The branch fanotify_pidfd_v2 is based off your fanotify_unpriv
> > branch. I'd like to post through this series at some point tomorrow,
> > so if you could PTAL in the interim, that'd be appreciated.
> >
> > I've incorporated the explicit documentation of the
> > fanotify_event_info_header structure, rather than duplicating field
> > explanations of such a structure across each information record types
> > as we had discussed.
> >
> > [0] https://github.com/matthewbobrowski/man-pages/tree/fanotify_pidfd_v2
> >
> 
> Hi Mattew,
> 
> I'm basically fine with most of the text in the sections, but
> the sections need some reordering IMO to make more sense.
> High level, I think it should look something like:

Right, I had thought that the ordering might need some work, thanks
for pulling this up.

> - "...the read buffer contains one or more struct fanotify_event_metadata..."
> - Text about several optional information records in event
> - Explain about fanotify_event_info_header and info_type
> - List of fanotify_event_info_* that belong to specific info types
> 
> Commented in github.

OK, I think this will make more sense when I read through the comments
on GitHub. I'll get around to this tonight/tomorrow.

/M

Re: [PATCH 0/1] fanotify: Document FAN_REPORT_PIDFD Feature

[Amir Goldstein]

On Tue, Nov 23, 2021 at 7:15 AM Matthew Bobrowski <repnop@google.com> wrote:
>
> On Mon, Nov 22, 2021 at 03:37:30PM +0200, Amir Goldstein wrote:
> > On Mon, Nov 22, 2021 at 1:19 PM Matthew Bobrowski <repnop@google.com> wrote:
> > >
> > > On Sat, Nov 20, 2021 at 12:36:26PM +0200, Amir Goldstein wrote:
> > > > On Wed, Oct 27, 2021 at 12:28 PM Matthew Bobrowski <repnop@google.com> wrote:
> > > > >
> > > > > Hi Michael,
> > > > >
> > > > > This patch series documents the new FAN_REPORT_PIDFD feature that is
> > > > > available from v5.15.
> > > > >
> > > > > Note that this patch series is diffbased against the FANOTIFY_UNPRIV
> > > > > [0, 1] man page updates that are yet to be merged with upstream. That
> > > > > said, if you could please merge the FANOTIFY_UNPRIV updates first
> > > > > followed by the FAN_REPORT_PIDFD updates, that would be much
> > > > > appreciated.
> > > > >
> > > > > [0] https://lore.kernel.org/linux-man/20210318160817.3586288-1-amir73il@gmail.com/
> > > > > [1] https://github.com/amir73il/man-pages/commits/fanotify_unpriv
> > > > >
> > > >
> > > > Alejandro,
> > > >
> > > > Is there any changes of getting those long due 5.13 fanotify update
> > > > patches merged?
> > > >
> > > > Matthew,
> > > >
> > > > For v2 please base your own fanotify_pidfd branch on top of fanotify_unpriv
> > > > (I just rebased it to master again) and provide a branch, that Gabriel
> > > > and I could
> > > > base the next man page updates on.
> > > >
> > > > Currently, neither your fanotify_pidfd patch nor Gabriel's fan-fs-error patch
> > > > conflict with fanotify_unpriv changes, but fan-fs-error does have conflicts
> > > > with fanotify_pidfd.
> > >
> > > ACK.
> > >
> > > As per request, v2 of the FAN_REPORT_PIDFD documentation can be found
> > > here [0].
> > >
> > > The branch fanotify_pidfd_v2 is based off your fanotify_unpriv
> > > branch. I'd like to post through this series at some point tomorrow,
> > > so if you could PTAL in the interim, that'd be appreciated.
> > >
> > > I've incorporated the explicit documentation of the
> > > fanotify_event_info_header structure, rather than duplicating field
> > > explanations of such a structure across each information record types
> > > as we had discussed.
> > >
> > > [0] https://github.com/matthewbobrowski/man-pages/tree/fanotify_pidfd_v2
> > >
> >
> > Hi Mattew,
> >
> > I'm basically fine with most of the text in the sections, but
> > the sections need some reordering IMO to make more sense.
> > High level, I think it should look something like:
>
> Right, I had thought that the ordering might need some work, thanks
> for pulling this up.
>
> > - "...the read buffer contains one or more struct fanotify_event_metadata..."
> > - Text about several optional information records in event
> > - Explain about fanotify_event_info_header and info_type
> > - List of fanotify_event_info_* that belong to specific info types
> >
> > Commented in github.
>
> OK, I think this will make more sense when I read through the comments
> on GitHub. I'll get around to this tonight/tomorrow.
>

Hi Matthew,

Did you ever get the chance to work on those edits?
If you do not have time for this please let us know so that somebody can
pick up this work and unclog the queue of man-page updates sitting on top
of your branch:

https://github.com/amir73il/man-pages/commits/fan-fs-error
https://github.com/amir73il/man-pages/commits/fan_rename

Thanks,
Amir.

Re: [PATCH 0/1] fanotify: Document FAN_REPORT_PIDFD Feature

[Matthew Bobrowski]

Hey Amir,

On Thu, Mar 17, 2022 at 12:09:45PM +0200, Amir Goldstein wrote:
> On Tue, Nov 23, 2021 at 7:15 AM Matthew Bobrowski <repnop@google.com> wrote:
> >
> > On Mon, Nov 22, 2021 at 03:37:30PM +0200, Amir Goldstein wrote:
> > > On Mon, Nov 22, 2021 at 1:19 PM Matthew Bobrowski <repnop@google.com> wrote:
> > > >
> > > > On Sat, Nov 20, 2021 at 12:36:26PM +0200, Amir Goldstein wrote:
> > > > > On Wed, Oct 27, 2021 at 12:28 PM Matthew Bobrowski <repnop@google.com> wrote:
> > > > > >
> > > > > > Hi Michael,
> > > > > >
> > > > > > This patch series documents the new FAN_REPORT_PIDFD feature that is
> > > > > > available from v5.15.
> > > > > >
> > > > > > Note that this patch series is diffbased against the FANOTIFY_UNPRIV
> > > > > > [0, 1] man page updates that are yet to be merged with upstream. That
> > > > > > said, if you could please merge the FANOTIFY_UNPRIV updates first
> > > > > > followed by the FAN_REPORT_PIDFD updates, that would be much
> > > > > > appreciated.
> > > > > >
> > > > > > [0] https://lore.kernel.org/linux-man/20210318160817.3586288-1-amir73il@gmail.com/
> > > > > > [1] https://github.com/amir73il/man-pages/commits/fanotify_unpriv
> > > > > >
> > > > >
> > > > > Alejandro,
> > > > >
> > > > > Is there any changes of getting those long due 5.13 fanotify update
> > > > > patches merged?
> > > > >
> > > > > Matthew,
> > > > >
> > > > > For v2 please base your own fanotify_pidfd branch on top of fanotify_unpriv
> > > > > (I just rebased it to master again) and provide a branch, that Gabriel
> > > > > and I could
> > > > > base the next man page updates on.
> > > > >
> > > > > Currently, neither your fanotify_pidfd patch nor Gabriel's fan-fs-error patch
> > > > > conflict with fanotify_unpriv changes, but fan-fs-error does have conflicts
> > > > > with fanotify_pidfd.
> > > >
> > > > ACK.
> > > >
> > > > As per request, v2 of the FAN_REPORT_PIDFD documentation can be found
> > > > here [0].
> > > >
> > > > The branch fanotify_pidfd_v2 is based off your fanotify_unpriv
> > > > branch. I'd like to post through this series at some point tomorrow,
> > > > so if you could PTAL in the interim, that'd be appreciated.
> > > >
> > > > I've incorporated the explicit documentation of the
> > > > fanotify_event_info_header structure, rather than duplicating field
> > > > explanations of such a structure across each information record types
> > > > as we had discussed.
> > > >
> > > > [0] https://github.com/matthewbobrowski/man-pages/tree/fanotify_pidfd_v2
> > > >
> > >
> > > Hi Mattew,
> > >
> > > I'm basically fine with most of the text in the sections, but
> > > the sections need some reordering IMO to make more sense.
> > > High level, I think it should look something like:
> >
> > Right, I had thought that the ordering might need some work, thanks
> > for pulling this up.
> >
> > > - "...the read buffer contains one or more struct fanotify_event_metadata..."
> > > - Text about several optional information records in event
> > > - Explain about fanotify_event_info_header and info_type
> > > - List of fanotify_event_info_* that belong to specific info types
> > >
> > > Commented in github.
> >
> > OK, I think this will make more sense when I read through the comments
> > on GitHub. I'll get around to this tonight/tomorrow.
> >
> 
> Hi Matthew,
> 
> Did you ever get the chance to work on those edits?
> If you do not have time for this please let us know so that somebody can
> pick up this work and unclog the queue of man-page updates sitting on top
> of your branch:
> 
> https://github.com/amir73il/man-pages/commits/fan-fs-error
> https://github.com/amir73il/man-pages/commits/fan_rename

I've been on parental leave for the last couple of months so I haven't
really had a chance to wrap the pending man-pages updates up. Now that
I'm back, I'll get the refactoring completed and sent through for
review.

Sorry about the delay on this.

/M