Skip to contentSkip to conversation

fanotify.7, fanotify_mark.2: Document FAN_FS_ERROR

PATCH In review Amir Goldstein 2 participants 2 messages Jun 17, 2022 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore
Share & tools
lore
#0 lore raw

PATCH v6 1/1 fanotify.7, fanotify_mark.2: Document FAN_FS_ERROR

From: Gabriel Krisman Bertazi <[email protected]>

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.

---

Hi Alex,

Posting v6 of Gabriel's patch with minor fixes per your request. Rebased on top of upstream.

Thanks,
Amir.

 man2/fanotify_mark.2 | 30 +++++++++++++++++++
 man7/fanotify.7      | 71 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 101 insertions(+)
man2/fanotify_mark.2 +30 -0
index 9a45cbb77..3dc538b7f 100644
@@ -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
man7/fanotify.7 +71 -0

95 lines not on this page · raw message

Signature · 1 line
2.25.1
#1 lore raw

Hi Amir,

Quoted 11 lines · Amir Goldstein

From: Gabriel Krisman Bertazi <[email protected]>

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.

Quoted 4 lines

Hi Alex,

Posting v6 of Gabriel's patch with minor fixes per your request. Rebased on top of upstream.

Patch applied. Thanks!

BTW, please check a comment below.

Cheers,

Alex

Quoted 71 lines

Thanks,
Amir.

  man2/fanotify_mark.2 | 30 +++++++++++++++++++
  man7/fanotify.7      | 71 ++++++++++++++++++++++++++++++++++++++++++++
  2 files changed, 101 insertions(+)
man2/fanotify_mark.2 +30 -0
index 9a45cbb77..3dc538b7f 100644
@@ -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
man7/fanotify.7 +6 -0
index a0dc0dfba..f4d391603 100644
@@ -228,6 +228,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

man7/fanotify.7 struct fanotify_event_info_pidfd { · line 246

Quoted 10 lines
man7/fanotify.7 +10 -0
+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;
+};

Since this is old, I'm applying it as is.
But if you don't mind, I'd like to see types described in separate pages in the subsection 3type. So, for future pages, please consider that:).

See for example iovec(3type), or uint8_t(3type).

<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/?id=6c809df77b359bb3a9e06f32547e0aed155408be>
<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/?id=cb3366169531510bcc7d445e15df68396291a05d>

That helps keep information more organized, and deduplicate it. And makes it easy to check man iovec for a quick reference.

This is following what started in man-pages-5.09 in system_data_types(7).

<https://linux-man-pages.blogspot.com/2020/11/man-pages-509-is-released.html>

See also:

<https://stackoverflow.com/questions/55190317/where-is-ssize-t-defined-in-linux>
<https://lore.kernel.org/linux-man/[email protected]/T/#u>

Quoted 79 lines
man7/fanotify.7 +55 -0
+.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
@@ -369,6 +388,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
@@ -643,6 +665,25 @@ 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)
@@ -732,6 +773,36 @@ 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
+.B 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
+.B FAN_FS_ERROR
+event record,
+but details about the errors are lost.
+.PP
+Errors reported by
+.B FAN_FS_ERROR
+are generic
+.I 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
Signature · 2 lines
Alejandro Colomar
<http://www.alejandro-colomar.es/>