Skip to contentSkip to conversation

fanotify.7, fanotify_mark.2: Document FAN_FS_ERROR

PATCH Superseded Gabriel Krisman Bertazi 3 participants 3 messages Nov 1, 2021 – Nov 2, 2021 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

v3 of 5 Superseded Latest is v5 →

lore
Share & tools
lore
#0 lore raw

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

FAN_FS_ERROR is a new event for fanotify to report filesystem errors.

Cc Amir Goldstein <[email protected]>
Cc Jan Kara <[email protected]>
Cc Matthew Bobrowski <[email protected]>

---
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

To: Michael Kerrisk <[email protected]>
Cc: [email protected]

---
 man2/fanotify_mark.2 | 36 ++++++++++++++++++++++
 man7/fanotify.7      | 71 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 107 insertions(+)
man2/fanotify_mark.2 +36 -0
index be3f72e040c0..d8560f788db8 100644
@@ -214,6 +214,35 @@ 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 9709bd548f11a092d124698118013f66e1740f9b
+Create an event when a filesystem error is detected.
+Support for this notification type
+is dependent on the underlying filesystem.
+.IP
+The filesystems that currently support
+.BR FAN_FS_ERROR
+are:
+.RS
+.IP "* ext4 "
+.RE
+.IP
+A user can also expect to receive additional information
+in the form of a
+.BR FAN_EVENT_INFO_TYPE_ERROR
+record
+alongside the generic metadata event.
+.IP
+A fanotify group initialized with
+.BR FAN_REPORT_FID
+is required, or the error
+.B EINVAL
+will occur.
+.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
@@ -389,6 +418,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 events in
+.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.33.0
#1 lore raw
Quoted 3 lines · Gabriel Krisman Bertazi

FAN_FS_ERROR is a new event for fanotify to report filesystem errors.

You need to be very explicit when posting to man pages that this is NOT upstream code yet.

UAPIs can practically be changed until the .0 release, but it's fine to post man pages update for wider review before that as long as the review is properly labeled as such.

Quoted 29 lines
Cc Amir Goldstein <[email protected]>
Cc Jan Kara <[email protected]>
Cc Matthew Bobrowski <[email protected]>

---
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

To: Michael Kerrisk <[email protected]>
Cc: [email protected]

---
 man2/fanotify_mark.2 | 36 ++++++++++++++++++++++
 man7/fanotify.7      | 71 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 107 insertions(+)
man2/fanotify_mark.2 +0 -0
index be3f72e040c0..d8560f788db8 100644

man2/fanotify_mark.2 Create an event when a marked file or directory itself is deleted. · line 217

Quoted 4 lines
man2/fanotify_mark.2 +1 -0
@@ -214,6 +214,35 @@ 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)"

That is a mistake.
This code is aiming for 5.16.
5.15 is already out the door.

Thanks,
Amir.

#2 lore raw
In reply to Gabriel Krisman Bertazi
Quoted 6 lines · Gabriel Krisman Bertazi

FAN_FS_ERROR is a new event for fanotify to report filesystem errors.

Cc Amir Goldstein <[email protected]>
Cc Jan Kara <[email protected]>
Cc Matthew Bobrowski <[email protected]>
Quoted 5 lines · Just one more comment besides what Amir already
man7/fanotify.7 +1 -0
@@ -599,6 +646,30 @@ field.
 In that case, the audit subsystem will log information about the access
 decision to the audit logs.
 .\"
+.SS Monitoring filesystems for errors

man7/fanotify.7 field. · line 659

Quoted 10 lines
man7/fanotify.7 +10 -0
+A single FAN_FS_ERROR event is stored per filesystem 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 generic errno values
+but not all kinds of errors types are reported by all filesystems.
+Refer to the filesystem documentation
+for additional information on the type of errors that are reported,
+and the meaning of those errors.

Hmm, I wish there was any filesystem documentation for this :). I think the only real source of this information is the kernel source code?

Honza

Signature · 2 lines
Jan Kara <[email protected]>
SUSE Labs, CR