[PATCH RESEND v5] fanotify.7, fanotify_mark.2: Document FAN_FS_ERROR

[PATCH RESEND v5] fanotify.7, fanotify_mark.2: Document FAN_FS_ERROR

[Gabriel Krisman Bertazi]

FAN_FS_ERROR is a new event for fanotify to report filesystem errors
that might lead to some corruption.
This documents how to use the feature and specific caveats.

Reviewed-by: Jan Kara <jack@suse.cz>
Reviewed-by: Amir Goldstein <amir73il@gmail.com>
Reviewed-by: Matthew Bobrowski <repnop@google.com>
Signed-off-by: Gabriel Krisman Bertazi <krisman@collabora.com>

---
as discussed this is rebased on top of the PIDFD documentation: commit
207080c7f7f5 ("fanotify: Document FAN_REPORT_PIDFD Feature")

changes since v5:
 (matthew)
 - typo fix

changes since v4:
 (Matthew)
 - Grammar fixes
 - Reword sections
 (Jan)
 - Explain fs error only apply to some errors
 (Amir)
 - Clarify what supported by ext4 means.

Changes since v3:
 (Matthew)
 - Rewording and fixes from github)
 (amir)
 - 5.15 -> 5.16

Changes since v2:
  (matthew)
    - Grammar
    - List filesystems that support the feature
    - file system -> filesystem
Changes since v1:
(Matthew)
  - Grammar fixes
  - Don't use the term "submitted" for events sent to the listener
  - Clarify the kind of information that is file system specific
---
 man2/fanotify_mark.2 | 30 +++++++++++++++++++++
 man7/fanotify.7      | 64 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 94 insertions(+)

diff --git a/man2/fanotify_mark.2 b/man2/fanotify_mark.2
index 9a45cbb77893..3dc538b7f84b 100644
--- a/man2/fanotify_mark.2
+++ b/man2/fanotify_mark.2
@@ -203,6 +203,29 @@ Create an event when a marked file or directory itself is deleted.
 An fanotify group that identifies filesystem objects by file handles
 is required.
 .TP
+.BR FAN_FS_ERROR " (since Linux 5.16)"
+.\" commit 9709bd548f11a092d124698118013f66e1740f9b
+Create an event when a filesystem error
+leading to inconsistent filesystem metadata is detected.
+An additional information record of type
+.B FAN_EVENT_INFO_TYPE_ERROR
+is returned for each event in the read buffer.
+An fanotify group that identifies filesystem objects by file handles
+is required.
+.IP
+Events of such type are dependent on support
+from the underlying filesystem.
+At the time of writing,
+only the
+.B ext4
+filesystem reports
+.B FAN_FS_ERROR
+events.
+.IP
+See
+.BR fanotify (7)
+for additional details.
+.TP
 .BR FAN_MOVED_FROM " (since Linux 5.1)"
 .\" commit 235328d1fa4251c6dcb32351219bb553a58838d2
 Create an event when a file or directory has been moved from a marked
@@ -391,6 +414,13 @@ and mask contains a flag for permission events
 or
 .BR FAN_ACCESS_PERM ).
 .TP
+.B EINVAL
+The group was initialized without
+.B FAN_REPORT_FID
+but one or more event types specified in the
+.I mask
+require it.
+.TP
 .B ENODEV
 The filesystem object indicated by
 .I pathname
diff --git a/man7/fanotify.7 b/man7/fanotify.7
index 57dd2b040380..3dc4113a551c 100644
--- a/man7/fanotify.7
+++ b/man7/fanotify.7
@@ -217,6 +217,25 @@ struct fanotify_event_info_pidfd {
 .EE
 .in
 .PP
+In case of a
+.B FAN_FS_ERROR
+event,
+an additional information record describing the error that occurred
+is returned alongside the generic
+.I fanotify_event_metadata
+structure within the read buffer.
+This structure is defined as follows:
+.PP
+.in +4n
+.EX
+struct fanotify_event_info_error {
+    struct fanotify_event_info_header hdr;
+    __s32 error;
+    __u32 error_count;
+};
+.EE
+.in
+.PP
 All information records contain a nested structure of type
 .IR fanotify_event_info_header .
 This structure holds meta-information about the information record
@@ -358,6 +377,9 @@ A child file or directory was deleted in a watched parent.
 .B FAN_DELETE_SELF
 A watched file or directory was deleted.
 .TP
+.B FAN_FS_ERROR
+A filesystem error was detected.
+.TP
 .B FAN_MOVED_FROM
 A file or directory has been moved from a watched parent directory.
 .TP
@@ -630,6 +652,25 @@ 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 fields of the
+.I fanotify_event_info_error
+structure are as follows:
+.TP
+.I hdr
+This is a structure of type
+.IR fanotify_event_info_header .
+The
+.I info_type
+field is set to
+.BR FAN_EVENT_INFO_TYPE_ERROR .
+.TP
+.I error
+Identifies the type of error that occurred.
+.TP
+.I error_count
+This is a counter of the number of errors suppressed
+since the last error was read.
+.PP
 The following macros are provided to iterate over a buffer containing
 fanotify event metadata returned by a
 .BR read (2)
@@ -719,6 +760,29 @@ field.
 In that case, the audit subsystem will log information about the access
 decision to the audit logs.
 .\"
+.SS Monitoring filesystems for errors
+A single FAN_FS_ERROR event is stored per filesystem at once.
+Extra error messages are suppressed and accounted for
+in the
+.I error_count
+field of the existing FAN_FS_ERROR event record,
+but details about the errors are lost.
+.PP
+Errors reported by FAN_FS_ERROR are generic errno values
+but not all kinds of error types are reported by all filesystems.
+.PP
+Errors not directly related to a file (i.e. super block corruption)
+are reported with an invalid
+.IR file_handle .
+For these errors, the
+.I file_handle
+will have the field
+.I handle_type
+set to
+.BR FILEID_INVALID ,
+and the handle buffer size set to
+.BR 0 .
+.\"
 .SS Closing the fanotify file descriptor
 When all file descriptors referring to the fanotify notification group are
 closed, the fanotify group is released and its resources
-- 
2.36.1

Re: [PATCH RESEND v5] fanotify.7, fanotify_mark.2: Document FAN_FS_ERROR

[Amir Goldstein]

[adding correct address of Alejandro]

On Fri, May 20, 2022 at 9:09 PM Gabriel Krisman Bertazi
<krisman@collabora.com> wrote:
>
> FAN_FS_ERROR is a new event for fanotify to report filesystem errors
> that might lead to some corruption.
> This documents how to use the feature and specific caveats.
>
> Reviewed-by: Jan Kara <jack@suse.cz>
> Reviewed-by: Amir Goldstein <amir73il@gmail.com>
> Reviewed-by: Matthew Bobrowski <repnop@google.com>
> Signed-off-by: Gabriel Krisman Bertazi <krisman@collabora.com>
>
> ---
> as discussed this is rebased on top of the PIDFD documentation: commit
> 207080c7f7f5 ("fanotify: Document FAN_REPORT_PIDFD Feature")

Which commit is that? From my tree?
Anyway, I see that Matthew has posted v4 since and Alejandro followed with v5.

Pushed v5 to fanotify_pidfd branch in my tree [1]
and this patch of yours (applies with no conflicts) to branch
fan-fs-error in my tree.

I also pushed branches fanotify_target_fid and fan_rename with a minor
update to include ENOTDIR error that was added in v5.18-rc7 and v5.17.9.

Matthew, the ENOTDIR change is minor so I kept your Reviewed-by.
Please ACK.

Thanks,
Amir.

[1] https://github.com/amir73il/man-pages



>
> changes since v5:
>  (matthew)
>  - typo fix
>
> changes since v4:
>  (Matthew)
>  - Grammar fixes
>  - Reword sections
>  (Jan)
>  - Explain fs error only apply to some errors
>  (Amir)
>  - Clarify what supported by ext4 means.
>
> Changes since v3:
>  (Matthew)
>  - Rewording and fixes from github)
>  (amir)
>  - 5.15 -> 5.16
>
> Changes since v2:
>   (matthew)
>     - Grammar
>     - List filesystems that support the feature
>     - file system -> filesystem
> Changes since v1:
> (Matthew)
>   - Grammar fixes
>   - Don't use the term "submitted" for events sent to the listener
>   - Clarify the kind of information that is file system specific
> ---
>  man2/fanotify_mark.2 | 30 +++++++++++++++++++++
>  man7/fanotify.7      | 64 ++++++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 94 insertions(+)
>
> diff --git a/man2/fanotify_mark.2 b/man2/fanotify_mark.2
> index 9a45cbb77893..3dc538b7f84b 100644
> --- a/man2/fanotify_mark.2
> +++ b/man2/fanotify_mark.2
> @@ -203,6 +203,29 @@ Create an event when a marked file or directory itself is deleted.
>  An fanotify group that identifies filesystem objects by file handles
>  is required.
>  .TP
> +.BR FAN_FS_ERROR " (since Linux 5.16)"
> +.\" commit 9709bd548f11a092d124698118013f66e1740f9b
> +Create an event when a filesystem error
> +leading to inconsistent filesystem metadata is detected.
> +An additional information record of type
> +.B FAN_EVENT_INFO_TYPE_ERROR
> +is returned for each event in the read buffer.
> +An fanotify group that identifies filesystem objects by file handles
> +is required.
> +.IP
> +Events of such type are dependent on support
> +from the underlying filesystem.
> +At the time of writing,
> +only the
> +.B ext4
> +filesystem reports
> +.B FAN_FS_ERROR
> +events.
> +.IP
> +See
> +.BR fanotify (7)
> +for additional details.
> +.TP
>  .BR FAN_MOVED_FROM " (since Linux 5.1)"
>  .\" commit 235328d1fa4251c6dcb32351219bb553a58838d2
>  Create an event when a file or directory has been moved from a marked
> @@ -391,6 +414,13 @@ and mask contains a flag for permission events
>  or
>  .BR FAN_ACCESS_PERM ).
>  .TP
> +.B EINVAL
> +The group was initialized without
> +.B FAN_REPORT_FID
> +but one or more event types specified in the
> +.I mask
> +require it.
> +.TP
>  .B ENODEV
>  The filesystem object indicated by
>  .I pathname
> diff --git a/man7/fanotify.7 b/man7/fanotify.7
> index 57dd2b040380..3dc4113a551c 100644
> --- a/man7/fanotify.7
> +++ b/man7/fanotify.7
> @@ -217,6 +217,25 @@ struct fanotify_event_info_pidfd {
>  .EE
>  .in
>  .PP
> +In case of a
> +.B FAN_FS_ERROR
> +event,
> +an additional information record describing the error that occurred
> +is returned alongside the generic
> +.I fanotify_event_metadata
> +structure within the read buffer.
> +This structure is defined as follows:
> +.PP
> +.in +4n
> +.EX
> +struct fanotify_event_info_error {
> +    struct fanotify_event_info_header hdr;
> +    __s32 error;
> +    __u32 error_count;
> +};
> +.EE
> +.in
> +.PP
>  All information records contain a nested structure of type
>  .IR fanotify_event_info_header .
>  This structure holds meta-information about the information record
> @@ -358,6 +377,9 @@ A child file or directory was deleted in a watched parent.
>  .B FAN_DELETE_SELF
>  A watched file or directory was deleted.
>  .TP
> +.B FAN_FS_ERROR
> +A filesystem error was detected.
> +.TP
>  .B FAN_MOVED_FROM
>  A file or directory has been moved from a watched parent directory.
>  .TP
> @@ -630,6 +652,25 @@ 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 fields of the
> +.I fanotify_event_info_error
> +structure are as follows:
> +.TP
> +.I hdr
> +This is a structure of type
> +.IR fanotify_event_info_header .
> +The
> +.I info_type
> +field is set to
> +.BR FAN_EVENT_INFO_TYPE_ERROR .
> +.TP
> +.I error
> +Identifies the type of error that occurred.
> +.TP
> +.I error_count
> +This is a counter of the number of errors suppressed
> +since the last error was read.
> +.PP
>  The following macros are provided to iterate over a buffer containing
>  fanotify event metadata returned by a
>  .BR read (2)
> @@ -719,6 +760,29 @@ field.
>  In that case, the audit subsystem will log information about the access
>  decision to the audit logs.
>  .\"
> +.SS Monitoring filesystems for errors
> +A single FAN_FS_ERROR event is stored per filesystem at once.
> +Extra error messages are suppressed and accounted for
> +in the
> +.I error_count
> +field of the existing FAN_FS_ERROR event record,
> +but details about the errors are lost.
> +.PP
> +Errors reported by FAN_FS_ERROR are generic errno values
> +but not all kinds of error types are reported by all filesystems.
> +.PP
> +Errors not directly related to a file (i.e. super block corruption)
> +are reported with an invalid
> +.IR file_handle .
> +For these errors, the
> +.I file_handle
> +will have the field
> +.I handle_type
> +set to
> +.BR FILEID_INVALID ,
> +and the handle buffer size set to
> +.BR 0 .
> +.\"
>  .SS Closing the fanotify file descriptor
>  When all file descriptors referring to the fanotify notification group are
>  closed, the fanotify group is released and its resources
> --
> 2.36.1
>

Re: [PATCH RESEND v5] fanotify.7, fanotify_mark.2: Document FAN_FS_ERROR

[Alejandro Colomar]

Hi,

On 5/21/22 08:40, Amir Goldstein wrote:
> [adding correct address of Alejandro]

Thanks!

> 
> On Fri, May 20, 2022 at 9:09 PM Gabriel Krisman Bertazi
> <krisman@collabora.com> wrote:
>>
>> FAN_FS_ERROR is a new event for fanotify to report filesystem errors
>> that might lead to some corruption.
>> This documents how to use the feature and specific caveats.
>>
>> Reviewed-by: Jan Kara <jack@suse.cz>
>> Reviewed-by: Amir Goldstein <amir73il@gmail.com>
>> Reviewed-by: Matthew Bobrowski <repnop@google.com>
>> Signed-off-by: Gabriel Krisman Bertazi <krisman@collabora.com>

Please check a few minor formatting issues below.
Other than that, looks good to me.

However, it seems that I'm missing some patch, as I can't apply it to my 
tree.  Should I apply any other patch before this?
It doesn't apply on top of the kernel.org master branch either (but 
don't use that one as reference, since it's quite old).

Thanks,

Alex

>>
>> ---
>> as discussed this is rebased on top of the PIDFD documentation: commit
>> 207080c7f7f5 ("fanotify: Document FAN_REPORT_PIDFD Feature")
> 
> Which commit is that? From my tree?
> Anyway, I see that Matthew has posted v4 since and Alejandro followed with v5.
> 
> Pushed v5 to fanotify_pidfd branch in my tree [1]
> and this patch of yours (applies with no conflicts) to branch
> fan-fs-error in my tree.
> 
> I also pushed branches fanotify_target_fid and fan_rename with a minor
> update to include ENOTDIR error that was added in v5.18-rc7 and v5.17.9.
> 
> Matthew, the ENOTDIR change is minor so I kept your Reviewed-by.
> Please ACK.
> 
> Thanks,
> Amir.
> 
> [1] https://github.com/amir73il/man-pages
> 
> 
> 
>>
>> changes since v5:
>>   (matthew)
>>   - typo fix
>>
>> changes since v4:
>>   (Matthew)
>>   - Grammar fixes
>>   - Reword sections
>>   (Jan)
>>   - Explain fs error only apply to some errors
>>   (Amir)
>>   - Clarify what supported by ext4 means.
>>
>> Changes since v3:
>>   (Matthew)
>>   - Rewording and fixes from github)
>>   (amir)
>>   - 5.15 -> 5.16
>>
>> Changes since v2:
>>    (matthew)
>>      - Grammar
>>      - List filesystems that support the feature
>>      - file system -> filesystem
>> Changes since v1:
>> (Matthew)
>>    - Grammar fixes
>>    - Don't use the term "submitted" for events sent to the listener
>>    - Clarify the kind of information that is file system specific
>> ---
>>   man2/fanotify_mark.2 | 30 +++++++++++++++++++++
>>   man7/fanotify.7      | 64 ++++++++++++++++++++++++++++++++++++++++++++
>>   2 files changed, 94 insertions(+)
>>
>> diff --git a/man2/fanotify_mark.2 b/man2/fanotify_mark.2
>> index 9a45cbb77893..3dc538b7f84b 100644
>> --- a/man2/fanotify_mark.2
>> +++ b/man2/fanotify_mark.2
>> @@ -203,6 +203,29 @@ Create an event when a marked file or directory itself is deleted.
>>   An fanotify group that identifies filesystem objects by file handles
>>   is required.
>>   .TP
>> +.BR FAN_FS_ERROR " (since Linux 5.16)"
>> +.\" commit 9709bd548f11a092d124698118013f66e1740f9b
>> +Create an event when a filesystem error
>> +leading to inconsistent filesystem metadata is detected.
>> +An additional information record of type
>> +.B FAN_EVENT_INFO_TYPE_ERROR
>> +is returned for each event in the read buffer.
>> +An fanotify group that identifies filesystem objects by file handles
>> +is required.
>> +.IP
>> +Events of such type are dependent on support
>> +from the underlying filesystem.
>> +At the time of writing,
>> +only the
>> +.B ext4
>> +filesystem reports
>> +.B FAN_FS_ERROR
>> +events.
>> +.IP
>> +See
>> +.BR fanotify (7)
>> +for additional details.
>> +.TP
>>   .BR FAN_MOVED_FROM " (since Linux 5.1)"
>>   .\" commit 235328d1fa4251c6dcb32351219bb553a58838d2
>>   Create an event when a file or directory has been moved from a marked
>> @@ -391,6 +414,13 @@ and mask contains a flag for permission events
>>   or
>>   .BR FAN_ACCESS_PERM ).
>>   .TP
>> +.B EINVAL
>> +The group was initialized without
>> +.B FAN_REPORT_FID
>> +but one or more event types specified in the
>> +.I mask
>> +require it.
>> +.TP
>>   .B ENODEV
>>   The filesystem object indicated by
>>   .I pathname
>> diff --git a/man7/fanotify.7 b/man7/fanotify.7
>> index 57dd2b040380..3dc4113a551c 100644
>> --- a/man7/fanotify.7
>> +++ b/man7/fanotify.7
>> @@ -217,6 +217,25 @@ struct fanotify_event_info_pidfd {
>>   .EE
>>   .in
>>   .PP
>> +In case of a
>> +.B FAN_FS_ERROR
>> +event,
>> +an additional information record describing the error that occurred
>> +is returned alongside the generic
>> +.I fanotify_event_metadata
>> +structure within the read buffer.
>> +This structure is defined as follows:
>> +.PP
>> +.in +4n
>> +.EX
>> +struct fanotify_event_info_error {
>> +    struct fanotify_event_info_header hdr;
>> +    __s32 error;
>> +    __u32 error_count;
>> +};
>> +.EE
>> +.in
>> +.PP
>>   All information records contain a nested structure of type
>>   .IR fanotify_event_info_header .
>>   This structure holds meta-information about the information record
>> @@ -358,6 +377,9 @@ A child file or directory was deleted in a watched parent.
>>   .B FAN_DELETE_SELF
>>   A watched file or directory was deleted.
>>   .TP
>> +.B FAN_FS_ERROR
>> +A filesystem error was detected.
>> +.TP
>>   .B FAN_MOVED_FROM
>>   A file or directory has been moved from a watched parent directory.
>>   .TP
>> @@ -630,6 +652,25 @@ 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 fields of the
>> +.I fanotify_event_info_error
>> +structure are as follows:
>> +.TP
>> +.I hdr
>> +This is a structure of type
>> +.IR fanotify_event_info_header .
>> +The
>> +.I info_type
>> +field is set to
>> +.BR FAN_EVENT_INFO_TYPE_ERROR .
>> +.TP
>> +.I error
>> +Identifies the type of error that occurred.
>> +.TP
>> +.I error_count
>> +This is a counter of the number of errors suppressed
>> +since the last error was read.
>> +.PP
>>   The following macros are provided to iterate over a buffer containing
>>   fanotify event metadata returned by a
>>   .BR read (2)
>> @@ -719,6 +760,29 @@ field.
>>   In that case, the audit subsystem will log information about the access
>>   decision to the audit logs.
>>   .\"
>> +.SS Monitoring filesystems for errors
>> +A single FAN_FS_ERROR event is stored per filesystem at once.

.B FAN_FS_ERROR

(also a few more times below)

>> +Extra error messages are suppressed and accounted for
>> +in the
>> +.I error_count
>> +field of the existing FAN_FS_ERROR event record,
>> +but details about the errors are lost.
>> +.PP
>> +Errors reported by FAN_FS_ERROR are generic errno values

.I errno

>> +but not all kinds of error types are reported by all filesystems.
>> +.PP
>> +Errors not directly related to a file (i.e. super block corruption)
>> +are reported with an invalid
>> +.IR file_handle .
>> +For these errors, the
>> +.I file_handle
>> +will have the field
>> +.I handle_type
>> +set to
>> +.BR FILEID_INVALID ,
>> +and the handle buffer size set to
>> +.BR 0 .
>> +.\"
>>   .SS Closing the fanotify file descriptor
>>   When all file descriptors referring to the fanotify notification group are
>>   closed, the fanotify group is released and its resources
>> --
>> 2.36.1
>>

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

Re: [PATCH RESEND v5] fanotify.7, fanotify_mark.2: Document FAN_FS_ERROR

[Amir Goldstein]

On Sun, May 22, 2022 at 6:44 PM Alejandro Colomar
<alx.manpages@gmail.com> wrote:
>
> Hi,
>
> On 5/21/22 08:40, Amir Goldstein wrote:
> > [adding correct address of Alejandro]
>
> Thanks!
>
> >
> > On Fri, May 20, 2022 at 9:09 PM Gabriel Krisman Bertazi
> > <krisman@collabora.com> wrote:
> >>
> >> FAN_FS_ERROR is a new event for fanotify to report filesystem errors
> >> that might lead to some corruption.
> >> This documents how to use the feature and specific caveats.
> >>
> >> Reviewed-by: Jan Kara <jack@suse.cz>
> >> Reviewed-by: Amir Goldstein <amir73il@gmail.com>
> >> Reviewed-by: Matthew Bobrowski <repnop@google.com>
> >> Signed-off-by: Gabriel Krisman Bertazi <krisman@collabora.com>
>
> Please check a few minor formatting issues below.
> Other than that, looks good to me.
>
> However, it seems that I'm missing some patch, as I can't apply it to my
> tree.  Should I apply any other patch before this?
> It doesn't apply on top of the kernel.org master branch either (but
> don't use that one as reference, since it's quite old).

It is applied on top of:

https://lore.kernel.org/linux-man/20220514131346.10171-1-alx.manpages@gmail.com/T/#u

We have a rather long backlog of man page updates pending merge
from Matthew, Gabriel and myself.
We need to merge them by order.
The entire stack is available in [BRANCHES] on my github tree [1].

Let me summarize it for you again:

FAN_REPORT_PIDFD v5.15 [fanotify_pidfd]
FAN_FS_ERROR v5.16 [fan-fs-error]
FAN_REPORT_TARGET_FID v5.17 [fanotify_target_fid]
FAN_RENAME v5.17 [fan_rename]

And I have more changes for upcoming v5.19...

Let me know if anything is not clear.

BTW, is there any prospect of updating kernel.org man pages
anytime soon?

Thanks,
Amir.

[1] https://github.com/amir73il/man-pages

Re: [PATCH RESEND v5] fanotify.7, fanotify_mark.2: Document FAN_FS_ERROR

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 1478 bytes --]

Hi Amir,

On 5/22/22 18:12, Amir Goldstein wrote:
> It is applied on top of:
> 
> https://lore.kernel.org/linux-man/20220514131346.10171-1-alx.manpages@gmail.com/T/#u

Okay, I see that other one is pending some rewording, so I'll hold this one.

> 
> We have a rather long backlog of man page updates pending merge
> from Matthew, Gabriel and myself.
> We need to merge them by order.
> The entire stack is available in [BRANCHES] on my github tree [1].
> 
> Let me summarize it for you again:

Thanks.  I'll write here what I know about the, just to be sure I didn't 
miss anything.  If you need anything from me, please tell me.

> 
> FAN_REPORT_PIDFD v5.15 [fanotify_pidfd]

Pending a rewording of a paragraph.

> FAN_FS_ERROR v5.16 [fan-fs-error]

This one.  Looks good to me.

> FAN_REPORT_TARGET_FID v5.17 [fanotify_target_fid]

I don't see this one in my mbox or linux-man@.
I assume it's not yet ready?

> FAN_RENAME v5.17 [fan_rename]

I don't see this either.  I assume it's not ready either.

> 
> And I have more changes for upcoming v5.19... >
> Let me know if anything is not clear.
> 
> BTW, is there any prospect of updating kernel.org man pages
> anytime soon?

Not likely for 2022.  Sorry.

> 
> Thanks,
> Amir.
> 
> [1] https://github.com/amir73il/man-pages

Regards,

Alex

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

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH RESEND v5] fanotify.7, fanotify_mark.2: Document FAN_FS_ERROR

[Matthew Bobrowski]

On Sun, May 22, 2022 at 11:37:25PM +0200, Alejandro Colomar wrote:
> Hi Amir,
> 
> On 5/22/22 18:12, Amir Goldstein wrote:
> > It is applied on top of:
> > 
> > https://lore.kernel.org/linux-man/20220514131346.10171-1-alx.manpages@gmail.com/T/#u
> 
> Okay, I see that other one is pending some rewording, so I'll hold this one.
> 
> > 
> > We have a rather long backlog of man page updates pending merge
> > from Matthew, Gabriel and myself.
> > We need to merge them by order.
> > The entire stack is available in [BRANCHES] on my github tree [1].
> > 
> > Let me summarize it for you again:
> 
> Thanks.  I'll write here what I know about the, just to be sure I didn't
> miss anything.  If you need anything from me, please tell me.
> 
> > 
> > FAN_REPORT_PIDFD v5.15 [fanotify_pidfd]
>
> Pending a rewording of a paragraph.

Right, I'll get around to this at some point today.

/M

Re: [PATCH RESEND v5] fanotify.7, fanotify_mark.2: Document FAN_FS_ERROR

[Matthew Bobrowski]

On Mon, May 23, 2022 at 09:50:42PM +0000, Matthew Bobrowski wrote:
> On Sun, May 22, 2022 at 11:37:25PM +0200, Alejandro Colomar wrote:
> > Hi Amir,
> > 
> > On 5/22/22 18:12, Amir Goldstein wrote:
> > > It is applied on top of:
> > > 
> > > https://lore.kernel.org/linux-man/20220514131346.10171-1-alx.manpages@gmail.com/T/#u
> > 
> > Okay, I see that other one is pending some rewording, so I'll hold this one.
> > 
> > > 
> > > We have a rather long backlog of man page updates pending merge
> > > from Matthew, Gabriel and myself.
> > > We need to merge them by order.
> > > The entire stack is available in [BRANCHES] on my github tree [1].
> > > 
> > > Let me summarize it for you again:
> > 
> > Thanks.  I'll write here what I know about the, just to be sure I didn't
> > miss anything.  If you need anything from me, please tell me.
> > 
> > > 
> > > FAN_REPORT_PIDFD v5.15 [fanotify_pidfd]
> >
> > Pending a rewording of a paragraph.
> 
> Right, I'll get around to this at some point today.

v6 has been posted [0], PTAL.

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

/M

Re: [PATCH RESEND v5] fanotify.7, fanotify_mark.2: Document FAN_FS_ERROR

[Amir Goldstein]

Hi Alex,

Getting back to the fanotify man page backlog...

>
> >
> > We have a rather long backlog of man page updates pending merge
> > from Matthew, Gabriel and myself.
> > We need to merge them by order.
> > The entire stack is available in [BRANCHES] on my github tree [1].
> >
> > Let me summarize it for you again:
>
> Thanks.  I'll write here what I know about the, just to be sure I didn't
> miss anything.  If you need anything from me, please tell me.
>
> >
> > FAN_REPORT_PIDFD v5.15 [fanotify_pidfd]

I see you finally managed to flow this into kernel.org repo. Yay! :)

>
> Pending a rewording of a paragraph.
>
> > FAN_FS_ERROR v5.16 [fan-fs-error]
>
> This one.  Looks good to me.
>

Rebased on top of upstream, fixed the few minor nits
you pointed out and push to:

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

Can you please apply?

> > FAN_REPORT_TARGET_FID v5.17 [fanotify_target_fid]
>
> I don't see this one in my mbox or linux-man@.
> I assume it's not yet ready?
>
> > FAN_RENAME v5.17 [fan_rename]
>
> I don't see this either.  I assume it's not ready either.
>

And now I can finally proceed to post these :)

> >
> > And I have more changes for upcoming v5.19... >

I have a question for you regarding new UAPI, such as
FAN_MARK_EVICTABLE that got merged to v5.19-rc1.

Often, Michael would not want to merge UAPI changes to
man pages before .0 release, because UAPI changes could
be reverted before final release (which happened for fanotify).
I still want to post those man page patches for review early,
but don't want to mess up your patch review process.

I guess if I post them as [RFC] it will be a good sign for you not
to merge them until the .0 release?
Should I simply use the subject "Fanotify updated for v5.19"?

Do you have a different view on the matter?
Don't care at all? ;-)

Thanks,
Amir.

Re: [PATCH RESEND v5] fanotify.7, fanotify_mark.2: Document FAN_FS_ERROR

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 1768 bytes --]

Hi, Amir!

On 6/17/22 14:37, Amir Goldstein wrote:
> I see you finally managed to flow this into kernel.org repo. Yay! :)

:)

>>> FAN_FS_ERROR v5.16 [fan-fs-error]
>>
>> This one.  Looks good to me.
>>
> 
> Rebased on top of upstream, fixed the few minor nits
> you pointed out and push to:
> 
> https://github.com/amir73il/man-pages/commits/fan-fs-error
> 
> Can you please apply?

Could you please send it as a patch set to the list?
That helps avoiding errors from my side.

>>> And I have more changes for upcoming v5.19... >
> 
> I have a question for you regarding new UAPI, such as
> FAN_MARK_EVICTABLE that got merged to v5.19-rc1.
> 
> Often, Michael would not want to merge UAPI changes to
> man pages before .0 release, because UAPI changes could
> be reverted before final release (which happened for fanotify).

That makes sense.

> I still want to post those man page patches for review early,

That also makes sense.

> but don't want to mess up your patch review process. >
> I guess if I post them as [RFC] it will be a good sign for you not
> to merge them until the .0 release?
> Should I simply use the subject "Fanotify updated for v5.19"?

[RFC] seems good to me for that purpose (I also use it for patches that 
shouldn't be applied).  If you want to make sure I don't apply it by 
accident (which may happen), you can also add a line in the email noting 
that, but normally, RFC should be enough.

> 
> Do you have a different view on the matter?
> Don't care at all? ;-)

Heh :)

I wonder sometimes if I'm beeing too much strict with contributors.  I 
think I'm usually being more strict than Michael was.

Cheers,

Alex

-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]