Commit b325bbea authored by Gabriel Krisman Bertazi's avatar Gabriel Krisman Bertazi
Browse files

fanotify.7, fanotify_mark.2: Document FAN_FS_ERROR



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: default avatarGabriel Krisman Bertazi <krisman@collabora.com>

---
To: Michael Kerrisk <mtk.manpages@gmail.com>
Cc: linux-man@vger.kernel.org
parent 33248cfe
......@@ -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
......
......@@ -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
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment