fanotify.7, fanotify_mark.2: Document FAN_FS_ERROR
A message that is not in the archive (sent off-list or not yet received): [email protected]
A message that is not in the archive (sent off-list or not yet received): CAOQ4uxjpwZs8Jg-cZ5yWqUis=FA=+g+ycjdBchz0kzKBhs6HxQ@mail.gmail.com
A message that is not in the archive (sent off-list or not yet received): [email protected]
A message that is not in the archive (sent off-list or not yet received): [email protected]
A message that is not in the archive (sent off-list or not yet received): [email protected]
PATCH v4 1/1 fanotify.7, fanotify_mark.2: Document FAN_FS_ERROR
FAN_FS_ERROR is a new event for fanotify to report filesystem errors. This documents how to use the feature and specific caveats.
---
+ Michael, linux-man
Matthew,
as discussed, this is rebased on top of the PIDFD documentation: commit 207080c7f7f5 ("fanotify: Document FAN_REPORT_PIDFD Feature").
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 | 28 +++++++++++++++++++ man7/fanotify.7 | 64 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 92 insertions(+)
man2/fanotify_mark.2 +28 -0
@@ -203,6 +203,27 @@ 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 is detected. +An fanotify group that identifies filesystem objects by file handles +is required. +.IP +An additional information record of type +.BR FAN_EVENT_INFO_TYPE_ERROR +is returned for each event in the read buffer. +.IP +Events of such type are dependent on support +from the underlying filesystem. +At the time of this writing, +only the +.B ext4 +filesystem supports this feature. +.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 +412,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 +64 -0
88 lines not on this page · raw message
Signature · 1 line
2.35.1
Quoted 4 lines · Gabriel Krisman Bertazi
FAN_FS_ERRORis a new event for fanotify to report filesystem errors. This documents how to use the feature and specific caveats.
Quoted 8 lines
Signed-off-by Gabriel Krisman Bertazi <[email protected]>+ Michael, linux-man
Matthew,
as discussed, this is rebased on top of the PIDFD documentation: commit
207080c7f7f5("fanotify: DocumentFAN_REPORT_PIDFDFeature").
Mostly looks OK. I've left a couple suggestions that I think could be adopted.
Quoted 30 lines
Changes since v3:
(Matthew)
- Rewording and fixes from github)
(amir)
- 5.15 -> 5.16Changes 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 | 28 +++++++++++++++++++ man7/fanotify.7 | 64 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 92 insertions(+)man2/fanotify_mark.2 +0
-0@@ -203,6 +203,27 @@ 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
man2/fanotify_mark.2 Create an event when a marked file or directory itself is deleted. · line 215
Quoted 10 lines
man2/fanotify_mark.2 +10
-0+.BR FAN_FS_ERROR " (since Linux 5.16)" +.\" commit 9709bd548f11a092d124698118013f66e1740f9b +Create an event when a filesystem error is detected. +An fanotify group that identifies filesystem objects by file handles +is required. +.IP +An additional information record of type +.BR FAN_EVENT_INFO_TYPE_ERROR +is returned for each event in the read buffer. +.IP
I'd update this to:
Create an event when a filesystem error 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.
man2/fanotify_mark.2 Create an event when a marked file or directory itself is deleted. · line 218
Quoted 3 lines
man2/fanotify_mark.2 +3
-0+Events of such type are dependent on support +from the underlying filesystem. +At the time of this writing,
At the time of writing,
Quoted 12 lines
man2/fanotify_mark.2 +8
-0+only the +.B ext4 +filesystem supports this feature. +.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
man2/fanotify_mark.2 and mask contains a flag for permission events · line 421
Quoted 10 lines
man2/fanotify_mark.2 +7
-0@@ -391,6 +412,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
I'd update this to:
The fanotify group was initialized without
.BR FAN_REPORT_FID .
One or more event types specified in the
.I mask
require it.
Quoted 8 lines
man2/fanotify_mark.2 +0
-0.B ENODEV The filesystem object indicated by .I pathnameman7/fanotify.7 +0
-0
man7/fanotify.7 struct fanotify_event_info_pidfd { · line 223
Quoted 7 lines
man7/fanotify.7 +4
-0@@ -217,6 +217,25 @@ struct fanotify_event_info_pidfd { .EE .in .PP +In case of a +.B FAN_FS_ERROR +event, +an additional record describing the error that occurred
^ information
Quoted 55 lines
man7/fanotify.7 +37
-0+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)
man7/fanotify.7 field. · line 764
Quoted 5 lines
man7/fanotify.7 +2
-0@@ -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.
This is just for my understanding. So, it isn't until the event listener reads and clears the FAN_FS_ERROR event from the event queue that you're able to receive subsequent filesystem errors for potentially different objects on the same filesystem. Based on this, it sounds like if there were to be two separate objects on the same filesystem that experienced some kind of error at the same time, then only one of those errors encoded in FAN_FS_ERROR would be returned?
man7/fanotify.7 field. · line 771
Quoted 7 lines
man7/fanotify.7 +7
-0+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 types reported by FAN_FS_ERROR are generic errno values
I'd update this to:
Errors reported by FAN_FS_ERROR ...
man7/fanotify.7 field. · line 772
Quoted 1 line
man7/fanotify.7 +1
-0+but not all kinds of errors types are reported by all filesystems.
^ s/errors/error
Quoted 6 lines
man7/fanotify.7 +6
-0+.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
man7/fanotify.7 field. · line 788
Quoted 10 lines
man7/fanotify.7 +7
-0+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
/M
Quoted 183 lines · Matthew Bobrowski
Quoted 4 lines · Gabriel Krisman Bertazi
FAN_FS_ERRORis a new event for fanotify to report filesystem errors. This documents how to use the feature and specific caveats.Quoted 8 lines
Signed-off-by Gabriel Krisman Bertazi <[email protected]>+ Michael, linux-man
Matthew,
as discussed, this is rebased on top of the PIDFD documentation: commit
207080c7f7f5("fanotify: DocumentFAN_REPORT_PIDFDFeature").Mostly looks OK. I've left a couple suggestions that I think could be adopted.
Quoted 30 lines
Changes since v3:
(Matthew)
- Rewording and fixes from github)
(amir)
- 5.15 -> 5.16Changes 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 | 28 +++++++++++++++++++ man7/fanotify.7 | 64 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 92 insertions(+)man2/fanotify_mark.2 +0
-0@@ -203,6 +203,27 @@ Create an event when a marked file or directory itself is deleted. An fanotify group that identifies filesystem objects by file handles is required. .TPman2/fanotify_mark.2 Create an event when a marked file or directory itself is deleted. · line 215
Quoted 10 lines
man2/fanotify_mark.2 +10
-0+.BR FAN_FS_ERROR " (since Linux 5.16)" +.\" commit 9709bd548f11a092d124698118013f66e1740f9b +Create an event when a filesystem error is detected. +An fanotify group that identifies filesystem objects by file handles +is required. +.IP +An additional information record of type +.BR FAN_EVENT_INFO_TYPE_ERROR +is returned for each event in the read buffer. +.IPI'd update this to:
Create an event when a filesystem error is detected.
An additional information record of type
.BFAN_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.man2/fanotify_mark.2 Create an event when a marked file or directory itself is deleted. · line 218
Quoted 3 lines
man2/fanotify_mark.2 +3
-0+Events of such type are dependent on support +from the underlying filesystem. +At the time of this writing,At the time of writing,
Quoted 12 lines
man2/fanotify_mark.2 +8
-0+only the +.B ext4 +filesystem supports this feature. +.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 markedman2/fanotify_mark.2 and mask contains a flag for permission events · line 421
Quoted 10 lines
man2/fanotify_mark.2 +7
-0@@ -391,6 +412,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. +.TPI'd update this to:
The fanotify group was initialized without
.BRFAN_REPORT_FID.
One or more event types specified in the
.I mask
require it.Quoted 8 lines
man2/fanotify_mark.2 +0
-0.B ENODEV The filesystem object indicated by .I pathnameman7/fanotify.7 +0
-0man7/fanotify.7 struct fanotify_event_info_pidfd { · line 223
Quoted 7 lines
man7/fanotify.7 +4
-0@@ -217,6 +217,25 @@ struct fanotify_event_info_pidfd { .EE .in .PP +In case of a +.B FAN_FS_ERROR +event, +an additional record describing the error that occurred^ informationQuoted 55 lines
man7/fanotify.7 +37
-0+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)man7/fanotify.7 field. · line 764
Quoted 5 lines
man7/fanotify.7 +2
-0@@ -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.
Quoted 7 lines
This is just for my understanding. So, it isn't until the event listener reads and clears the
FAN_FS_ERRORevent from the event queue that you're able to receive subsequent filesystem errors for potentially different objects on the same filesystem. Based on this, it sounds like if there were to be two separate objects on the same filesystem that experienced some kind of error at the same time, then only one of those errors encoded inFAN_FS_ERRORwould be returned?
Matthew,
That is correct. we queue up to one event per filesystem. The reasoning is that, when an error occurs, the most important piece of information is the first failure, but the filesystem is very likely to spew dozens of extra errors after the first one, usually not very interesting. A proper response would be using some fsck tool to repair the entire filesystem.
Quoted 34 lines
man7/fanotify.7 field. · line 771
Quoted 7 lines
man7/fanotify.7 +7
-0+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 types reported by FAN_FS_ERROR are generic errno valuesI'd update this to:
Errors reported by
FAN_FS_ERROR...man7/fanotify.7 field. · line 772
Quoted 1 line
man7/fanotify.7 +1
-0+but not all kinds of errors types are reported by all filesystems.^ s/errors/errorQuoted 6 lines
man7/fanotify.7 +6
-0+.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_handleman7/fanotify.7 field. · line 788
Quoted 10 lines
man7/fanotify.7 +7
-0+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/M
Signature · 1 line
Gabriel Krisman Bertazi
Quoted 19 lines · Gabriel Krisman Bertazi
FAN_FS_ERRORis a new event for fanotify to report filesystem errors. This documents how to use the feature and specific caveats.Signed-off-by Gabriel Krisman Bertazi <[email protected]>---
+ Michael, linux-manMatthew,
as discussed, this is rebased on top of the PIDFD documentation: commit
207080c7f7f5("fanotify: DocumentFAN_REPORT_PIDFDFeature").Changes since v3:
(Matthew)
- Rewording and fixes from github)
(amir)
- 5.15 -> 5.16
Quoted 10 lines
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
Thanks for the manpage! Couple of notes below.
man2/fanotify_mark.2 Create an event when a marked file or directory itself is deleted. · line 208
Quoted 11 lines
man2/fanotify_mark.2 +3
-0@@ -203,6 +203,27 @@ 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 is detected.
Maybe we could specify here a bit more what "filesystem error" means? Because we don't generate the event e.g. on ENOSPC which could be considered filesystem error. We don't generate it on EIO in data block either. So maybe something like: "Create an event when a filesystem error leading to inconsistent filesystem metadata is detected." Because that's closer to what we currently do as far as I remember.
Quoted 8 lines
man2/fanotify_mark.2 +8
-0+An fanotify group that identifies filesystem objects by file handles +is required. +.IP +An additional information record of type +.BR FAN_EVENT_INFO_TYPE_ERROR +is returned for each event in the read buffer. +.IP +Events of such type are dependent on support
man2/fanotify_mark.2 Create an event when a marked file or directory itself is deleted. · line 226
Quoted 10 lines
man2/fanotify_mark.2 +10
-0+from the underlying filesystem. +At the time of this writing, +only the +.B ext4 +filesystem supports this feature. +.IP +See +.BR fanotify (7) +for additional details. +.TP
BTW any plans to add support to XFS or btrfs? I guess it would be good to spread the use a bit more so that it does not end up as a niche ext4 feature not very useful to programmers...
Otherwise the changes look good (modulo some language issues Matthew already pointed out).
Honza
Signature · 2 lines
Jan Kara <[email protected]> SUSE Labs, CR
Amir Goldstein
Reviewed-byQuoted 67 lines · Jan Kara
Quoted 19 lines · Gabriel Krisman Bertazi
FAN_FS_ERRORis a new event for fanotify to report filesystem errors. This documents how to use the feature and specific caveats.Signed-off-by Gabriel Krisman Bertazi <[email protected]>---
+ Michael, linux-manMatthew,
as discussed, this is rebased on top of the PIDFD documentation: commit
207080c7f7f5("fanotify: DocumentFAN_REPORT_PIDFDFeature").Changes since v3:
(Matthew)
- Rewording and fixes from github)
(amir)
- 5.15 -> 5.16Quoted 10 lines
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 specificThanks for the manpage! Couple of notes below.
man2/fanotify_mark.2 Create an event when a marked file or directory itself is deleted. · line 208
Quoted 11 lines
man2/fanotify_mark.2 +3
-0@@ -203,6 +203,27 @@ 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 is detected.Maybe we could specify here a bit more what "filesystem error" means? Because we don't generate the event e.g. on ENOSPC which could be considered filesystem error. We don't generate it on EIO in data block either. So maybe something like: "Create an event when a filesystem error leading to inconsistent filesystem metadata is detected." Because that's closer to what we currently do as far as I remember.
Quoted 14 lines
man2/fanotify_mark.2 +14
-0+An fanotify group that identifies filesystem objects by file handles +is required. +.IP +An additional information record of type +.BR FAN_EVENT_INFO_TYPE_ERROR +is returned for each event in the read buffer. +.IP +Events of such type are dependent on support +from the underlying filesystem. +At the time of this writing, +only the +.B ext4 +filesystem supports this feature. +.IP
Quoted 9 lines
man2/fanotify_mark.2 Create an event when a marked file or directory itself is deleted. · line 226
Quoted 4 lines
man2/fanotify_mark.2 +4
-0+See +.BR fanotify (7) +for additional details. +.TPBTW any plans to add support to XFS or btrfs? I guess it would be good to spread the use a bit more so that it does not end up as a niche ext4 feature not very useful to programmers...
I would like to point that the term "filesystem supports this feature" is somewhat
ambiguous here.
This same man page says: "...tmpfs(5) did not support fsid prior to Linux 5.13." meaning that an attempt to setup a mark with FAN_REPORT_FID group on tmpfs would result in an error.
OTOH, trying to setup a mark with FAN_FS_ERROR on tmpfs/xfs is not going to result in any error, it is just going to result in no FAN_FS_ERROR errors reported.
I think that we should make that more clear by saying something like:
"At the time of this writing, only the ext4 filesystem reports FAN_FS_ERROR events.
With that you may add:
And I will update your v5 patch in my patch queue.
Thanks,
Amir.
Quoted 5 lines · Jan Kara
On Tue 12-04-22 14:50:28, Gabriel Krisman Bertazi wrote:
BTW any plans to add support to XFS or btrfs? I guess it would be good to spread the use a bit more so that it does not end up as a niche ext4 feature not very useful to programmers...
Hi Jan,
Yes. i have plans to wire other filesystems, starting with btrfs, but I have a few items ahead of it. I definitely don't want to have this as a single-filesystem feature.
Quoted 2 lines
Otherwise the changes look good (modulo some language issues Matthew already pointed out).
Thanks. I'm following up with the v5 shortly.
Signature · 1 line
Gabriel Krisman Bertazi