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

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

[Gabriel Krisman Bertazi]

The kernel patches are not merged upstream, so please refrain from merging
it at the moment.  This submission attempts to preview the interface
and gather some interface review.

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

---
To: Michael Kerrisk <mtk.manpages@gmail.com>
Cc: linux-man@vger.kernel.org
---
 man2/fanotify_mark.2 | 14 +++++++++
 man7/fanotify.7      | 72 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 86 insertions(+)

diff --git a/man2/fanotify_mark.2 b/man2/fanotify_mark.2
index be3f72e040c0..500e41faa4f0 100644
--- a/man2/fanotify_mark.2
+++ b/man2/fanotify_mark.2
@@ -214,6 +214,20 @@ 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.15)"
+.\" commit WIP
+Create an event when a file system error is detected.
+A fanotify group that identifies filesystem objects by file handles
+is required.
+Support for this type of notification is done per-file system,
+but not every filesystem supports it.
+Additional information is submitted in the form of a
+.BR FAN_EVENT_INFO_TYPE_ERROR
+record.
+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
diff --git a/man7/fanotify.7 b/man7/fanotify.7
index 6a7e70d75845..155ba8273463 100644
--- a/man7/fanotify.7
+++ b/man7/fanotify.7
@@ -188,6 +188,24 @@ struct fanotify_event_info_fid {
 .EE
 .in
 .PP
+In case of a FAN_FS_ERROR event,
+besides the file handle record,
+an additional record describing the error that occurred
+is included in the read buffer.
+The structure described below, will follow the generic
+.I fanotify_event_metadata
+structure within the read buffer:
+.PP
+.in +4n
+.EX
+struct fanotify_event_info_error {
+    struct fanotify_event_info_header hdr;
+    __s32 error;
+    __u32 error_count;
+};
+.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
@@ -311,6 +329,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 file-system error was detected.
+.TP
 .B FAN_MOVED_FROM
 A file or directory has been moved from a watched parent directory.
 .TP
@@ -510,6 +531,32 @@ 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_error
+structure are as follows:
+.TP
+.I hdr
+This is a structure of type
+.IR fanotify_event_info_header .
+is a generic header that contains information used to
+describe an additional information record attached to the event.
+For
+.IR fanotify_event_info_error ,
+.I info_type
+will have the value
+.BR FAN_EVENT_INFO_TYPE_ERROR .
+.I len
+has the size of the additional information record including the
+.IR fanotify_event_info_header
+itself.
+.TP
+.I error
+Identifies the file system specific error that occured
+.TP
+.I error_count
+This counts 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)
@@ -599,6 +646,31 @@ field.
 In that case, the audit subsystem will log information about the access
 decision to the audit logs.
 .\"
+.SS Monitoring file systems for error
+A single FAN_FS_ERROR event is stored by the kernel at once.
+Extra error messages are suppressed and accounted
+inside the current FAN_FS_ERROR event record,
+but details about the errors are lost.
+.PP
+Error types reported by FAN_FS_ERROR are file system specific
+and not all kinds of error are reported by all file system.
+Refer to the file system documentation
+for the information of which errors are reported,
+and the meaning of those errors.
+.PP
+Errors not directly related to a file (i.e. super block corruption)
+are reported with an invalid file handler.
+For these errors,
+.I file_handle
+will have the field
+.I handle_type
+set to
+.BR FILEID_INVALID ,
+and the
+.I f_handle
+buffer 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.32.0

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

[Amir Goldstein]

+linux-api

On Tue, Jul 20, 2021 at 7:02 PM Gabriel Krisman Bertazi
<krisman@collabora.com> wrote:
>
> The kernel patches are not merged upstream, so please refrain from merging
> it at the moment.  This submission attempts to preview the interface
> and gather some interface review.
>
> Cc: Amir Goldstein <amir73il@gmail.com>
> Cc: Jan Kara <jack@suse.cz>
> Signed-off-by: Gabriel Krisman Bertazi <krisman@collabora.com>
>

Looks good as a first draft.

Thanks,
Amir.

> ---
> To: Michael Kerrisk <mtk.manpages@gmail.com>
> Cc: linux-man@vger.kernel.org
> ---
>  man2/fanotify_mark.2 | 14 +++++++++
>  man7/fanotify.7      | 72 ++++++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 86 insertions(+)
>
> diff --git a/man2/fanotify_mark.2 b/man2/fanotify_mark.2
> index be3f72e040c0..500e41faa4f0 100644
> --- a/man2/fanotify_mark.2
> +++ b/man2/fanotify_mark.2
> @@ -214,6 +214,20 @@ 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.15)"
> +.\" commit WIP
> +Create an event when a file system error is detected.
> +A fanotify group that identifies filesystem objects by file handles
> +is required.
> +Support for this type of notification is done per-file system,
> +but not every filesystem supports it.
> +Additional information is submitted in the form of a
> +.BR FAN_EVENT_INFO_TYPE_ERROR
> +record.
> +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
> diff --git a/man7/fanotify.7 b/man7/fanotify.7
> index 6a7e70d75845..155ba8273463 100644
> --- a/man7/fanotify.7
> +++ b/man7/fanotify.7
> @@ -188,6 +188,24 @@ struct fanotify_event_info_fid {
>  .EE
>  .in
>  .PP
> +In case of a FAN_FS_ERROR event,
> +besides the file handle record,
> +an additional record describing the error that occurred
> +is included in the read buffer.
> +The structure described below, will follow the generic
> +.I fanotify_event_metadata
> +structure within the read buffer:
> +.PP
> +.in +4n
> +.EX
> +struct fanotify_event_info_error {
> +    struct fanotify_event_info_header hdr;
> +    __s32 error;
> +    __u32 error_count;
> +};
> +.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
> @@ -311,6 +329,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 file-system error was detected.
> +.TP
>  .B FAN_MOVED_FROM
>  A file or directory has been moved from a watched parent directory.
>  .TP
> @@ -510,6 +531,32 @@ 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_error
> +structure are as follows:
> +.TP
> +.I hdr
> +This is a structure of type
> +.IR fanotify_event_info_header .
> +is a generic header that contains information used to
> +describe an additional information record attached to the event.
> +For
> +.IR fanotify_event_info_error ,
> +.I info_type
> +will have the value
> +.BR FAN_EVENT_INFO_TYPE_ERROR .
> +.I len
> +has the size of the additional information record including the
> +.IR fanotify_event_info_header
> +itself.
> +.TP
> +.I error
> +Identifies the file system specific error that occured
> +.TP
> +.I error_count
> +This counts 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)
> @@ -599,6 +646,31 @@ field.
>  In that case, the audit subsystem will log information about the access
>  decision to the audit logs.
>  .\"
> +.SS Monitoring file systems for error
> +A single FAN_FS_ERROR event is stored by the kernel at once.
> +Extra error messages are suppressed and accounted
> +inside the current FAN_FS_ERROR event record,
> +but details about the errors are lost.
> +.PP
> +Error types reported by FAN_FS_ERROR are file system specific
> +and not all kinds of error are reported by all file system.
> +Refer to the file system documentation
> +for the information of which errors are reported,
> +and the meaning of those errors.
> +.PP
> +Errors not directly related to a file (i.e. super block corruption)
> +are reported with an invalid file handler.
> +For these errors,
> +.I file_handle
> +will have the field
> +.I handle_type
> +set to
> +.BR FILEID_INVALID ,
> +and the
> +.I f_handle
> +buffer 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.32.0
>

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

[Matthew Bobrowski]

Hey Gabriel,

Sorry, I haven't really been following this series. However, I've just read
through this man-pages patch from the perspective of an API consumer and
sprayed a couple suggestions.

For the next iteration, do you mind CC'ing me?

On Tue, Jul 20, 2021 at 08:47:31PM +0300, Amir Goldstein wrote:
> +linux-api
> 
> On Tue, Jul 20, 2021 at 7:02 PM Gabriel Krisman Bertazi
> <krisman@collabora.com> wrote:
> >
> > The kernel patches are not merged upstream, so please refrain from merging
> > it at the moment.  This submission attempts to preview the interface
> > and gather some interface review.
> >
> > Cc: Amir Goldstein <amir73il@gmail.com>
> > Cc: Jan Kara <jack@suse.cz>
> > Signed-off-by: Gabriel Krisman Bertazi <krisman@collabora.com>
> >
> 
> Looks good as a first draft.
> 
> Thanks,
> Amir.
> 
> > ---
> > To: Michael Kerrisk <mtk.manpages@gmail.com>
> > Cc: linux-man@vger.kernel.org
> > ---
> >  man2/fanotify_mark.2 | 14 +++++++++
> >  man7/fanotify.7      | 72 ++++++++++++++++++++++++++++++++++++++++++++
> >  2 files changed, 86 insertions(+)
> >
> > diff --git a/man2/fanotify_mark.2 b/man2/fanotify_mark.2
> > index be3f72e040c0..500e41faa4f0 100644
> > --- a/man2/fanotify_mark.2
> > +++ b/man2/fanotify_mark.2
> > @@ -214,6 +214,20 @@ 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.15)"
> > +.\" commit WIP
> > +Create an event when a file system error is detected.
> > +A fanotify group that identifies filesystem objects by file handles
> > +is required.
> > +Support for this type of notification is done per-file system,
> > +but not every filesystem supports it.
> > +Additional information is submitted in the form of a
> > +.BR FAN_EVENT_INFO_TYPE_ERROR
> > +record.

The term "submitted" sounds confusing in this context, does it not? I think
we traditionally mention that an event listener can expect to receive an
additional information object of type X alongside the generic metadata
event.

> > +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
> > diff --git a/man7/fanotify.7 b/man7/fanotify.7
> > index 6a7e70d75845..155ba8273463 100644
> > --- a/man7/fanotify.7
> > +++ b/man7/fanotify.7
> > @@ -188,6 +188,24 @@ struct fanotify_event_info_fid {
> >  .EE
> >  .in
> >  .PP
> > +In case of a FAN_FS_ERROR event,
> > +besides the file handle record,
> > +an additional record describing the error that occurred
> > +is included in the read buffer.
> > +The structure described below, will follow the generic
> > +.I fanotify_event_metadata
> > +structure within the read buffer:
> > +.PP
> > +.in +4n
> > +.EX
> > +struct fanotify_event_info_error {
> > +    struct fanotify_event_info_header hdr;
> > +    __s32 error;
> > +    __u32 error_count;
> > +};
> > +.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
> > @@ -311,6 +329,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 file-system error was detected.
> > +.TP
> >  .B FAN_MOVED_FROM
> >  A file or directory has been moved from a watched parent directory.
> >  .TP
> > @@ -510,6 +531,32 @@ 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_error
> > +structure are as follows:
> > +.TP
> > +.I hdr
> > +This is a structure of type
> > +.IR fanotify_event_info_header .
> > +is a generic header that contains information used to

... and is a generic ...

> > +describe an additional information record attached to the event.
> > +For
> > +.IR fanotify_event_info_error ,
> > +.I info_type
> > +will have the value
> > +.BR FAN_EVENT_INFO_TYPE_ERROR .
> > +.I len
> > +has the size of the additional information record including the
> > +.IR fanotify_event_info_header
> > +itself.
> > +.TP
> > +.I error
> > +Identifies the file system specific error that occured
> > +.TP
> > +.I error_count
> > +This counts 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)
> > @@ -599,6 +646,31 @@ field.
> >  In that case, the audit subsystem will log information about the access
> >  decision to the audit logs.
> >  .\"
> > +.SS Monitoring file systems for error
					  ^ s?
					  
> > +A single FAN_FS_ERROR event is stored by the kernel at once.
> > +Extra error messages are suppressed and accounted
						       ^ for?
> > +inside the current FAN_FS_ERROR event record,
> > +but details about the errors are lost.
> > +.PP
> > +Error types reported by FAN_FS_ERROR are file system specific
> > +and not all kinds of error are reported by all file system.
    	     	       	       ^ s?			       ^ s?

Here, my understanding is that the filesystem errors are distinct across
each of the different filesystems that are capable of generating
FAN_FS_ERROR errors i.e. ext4; therefore filesystem specific documentation
should be consulted in order to get more meta-information about the actual
underlying filesystem error that occurred on the watched object.

Is that correct?

> > +Refer to the file system documentation
> > +for the information of which errors are reported,

... for additional/more information on the type of errors that are
supported/reported, ...?

> > +and the meaning of those errors.
> > +.PP
> > +Errors not directly related to a file (i.e. super block corruption)
> > +are reported with an invalid file handler.
    	 	       	  	  ^
.I file_handle .

> > +For these errors,
> > +.I file_handle

For such errors, the
.I file_handle
will have the field... 

> > +will have the field
> > +.I handle_type
> > +set to
> > +.BR FILEID_INVALID ,
> > +and the
> > +.I f_handle
> > +buffer 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.32.0
> >

/M