With fanotify_init(2) flag FAN_REPORT_FID, the group identifies
filesystem objects by file handles in a single event info record of type
FAN_EVENT_INFO_TYPE_FID.
We indend to add support for new fanotify_init(2) flags for which the
group identifies filesystem objects by file handles and add more event
info record types.
To that end, start by changing the language of the man page to refer
to a "group that identifies filesystem objects by file handles" instead
of referring to the FAN_REPORT_FID flag and document the extended event
format structure in a more generic manner that allows more than a single
event info record and not only a record of type FAN_EVENT_INFO_TYPE_FID.
Clarify that the object identified by the file handle refers to the
directory in directory entry modification events.
Remove a note about directory entry modification events and monitoring
a mount point that I found to be too confusing and out of context.
Signed-off-by: Amir Goldstein <amir73il@xxxxxxxxx>
---
man2/fanotify_init.2 | 26 +++++++-----
man2/fanotify_mark.2 | 50 +++++++----------------
man7/fanotify.7 | 94 ++++++++++++++++++++++++--------------------
3 files changed, 83 insertions(+), 87 deletions(-)
diff --git a/man2/fanotify_init.2 b/man2/fanotify_init.2
index 8eedfe194..54646e3c6 100644
--- a/man2/fanotify_init.2
+++ b/man2/fanotify_init.2
@@ -159,22 +159,30 @@ supplied to
.\" commit a8b13aa20afb69161b5123b4f1acc7ea0a03d360
This value allows the receipt of events which contain additional information
about the underlying filesystem object correlated to an event.
-An additional structure encapsulates the information about the object and is
-included alongside the generic event metadata structure.
+An additional record of type
+.BR FAN_EVENT_INFO_TYPE_FID
+encapsulates the information about the object and is included alongside the
+generic event metadata structure.
The file descriptor that is used to represent the object correlated to an
event is instead substituted with a file handle.
It is intended for applications that may find the use of a file handle to
identify an object more suitable than a file descriptor.
-Additionally, it may be used for applications that are interested in
-directory entry events, such as
+Additionally, it may be used for applications monitoring a directory or a
+filesystem that are interested in the directory entry modification events
.BR FAN_CREATE ,
-.BR FAN_ATTRIB ,
+.BR FAN_DELETE ,
+and
.BR FAN_MOVE ,
+or in events such as
+.BR FAN_ATTRIB ,
+.BR FAN_DELETE_SELF ,
and
-.BR FAN_DELETE
-for example.
-Note that the use of directory modification events are not supported when
-monitoring a mount point.
+.BR FAN_MOVE_SELF .
+All the events above require an fanotify group that identifies filesystem
+objects by file handles.
+Note that for the directory entry modification events the reported file handle
+identifies the modified directory and not the created/deleted/moved child
+object.
The use of
.BR FAN_CLASS_CONTENT
or
diff --git a/man2/fanotify_mark.2 b/man2/fanotify_mark.2
index 579e5a907..042841687 100644
--- a/man2/fanotify_mark.2
+++ b/man2/fanotify_mark.2
@@ -126,10 +126,7 @@ is not itself a mount point, the mount point containing
will be marked.
All directories, subdirectories, and the contained files of the mount point
will be monitored.
-The events which require the
-.I fanotify_fd
-file descriptor to have been initialized with the flag
-.BR FAN_REPORT_FID ,
+The events which require that filesystem objects are identified by file handles,
such as
.BR FAN_CREATE ,
.BR FAN_ATTRIB ,
@@ -194,54 +191,47 @@ See NOTES for additional details.
.BR FAN_ATTRIB " (since Linux 5.1)"
.\" commit 235328d1fa4251c6dcb32351219bb553a58838d2
Create an event when the metadata for a file or directory has changed.
-An fanotify file descriptor created with
-.B FAN_REPORT_FID
+An fanotify group that identifies filesystem objects by file handles
is required.
.TP
.BR FAN_CREATE " (since Linux 5.1)"
.\" commit 235328d1fa4251c6dcb32351219bb553a58838d2
Create an event when a file or directory has been created in a marked
parent directory.
-An fanotify file descriptor created with
-.B FAN_REPORT_FID
+An fanotify group that identifies filesystem objects by file handles
is required.
.TP
.BR FAN_DELETE " (since Linux 5.1)"
.\" commit 235328d1fa4251c6dcb32351219bb553a58838d2
Create an event when a file or directory has been deleted in a marked
parent directory.
-An fanotify file descriptor created with
-.B FAN_REPORT_FID
+An fanotify group that identifies filesystem objects by file handles
is required.
.TP
.BR FAN_DELETE_SELF " (since Linux 5.1)"
.\" commit 235328d1fa4251c6dcb32351219bb553a58838d2
Create an event when a marked file or directory itself is deleted.
-An fanotify file descriptor created with
-.B FAN_REPORT_FID
+An fanotify group that identifies filesystem objects by file handles
is required.
.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
parent directory.
-An fanotify file descriptor created with
-.B FAN_REPORT_FID
+An fanotify group that identifies filesystem objects by file handles
is required.
.TP
.BR FAN_MOVED_TO " (since Linux 5.1)"
.\" commit 235328d1fa4251c6dcb32351219bb553a58838d2
Create an event when a file or directory has been moved to a marked parent
directory.
-An fanotify file descriptor created with
-.B FAN_REPORT_FID
+An fanotify group that identifies filesystem objects by file handles
is required.
.TP
.BR FAN_MOVE_SELF " (since Linux 5.1)"
.\" commit 235328d1fa4251c6dcb32351219bb553a58838d2
Create an event when a marked file or directory itself has been moved.
-An fanotify file descriptor created with
-.B FAN_REPORT_FID
+An fanotify group that identifies filesystem objects by file handles
is required.
.TP
.B FAN_OPEN_PERM
@@ -393,8 +383,7 @@ was not an fanotify file descriptor.
.B EINVAL
The fanotify file descriptor was opened with
.B FAN_CLASS_NOTIF
-or
-.B FAN_REPORT_FID
+or the fanotify group identifies filesystem objects by file handles
and mask contains a flag for permission events
.RB ( FAN_OPEN_PERM
or
@@ -407,11 +396,8 @@ is not associated with a filesystem that supports
.I fsid
(e.g.,
.BR tmpfs (5)).
-This error can be returned only when an fanotify file descriptor returned
-by
-.BR fanotify_init (2)
-has been created with
-.BR FAN_REPORT_FID .
+This error can be returned only with an fanotify group that identifies
+filesystem objects by file handles.
.TP
.B ENOENT
The filesystem object indicated by
@@ -452,11 +438,8 @@ The object indicated by
.I pathname
is associated with a filesystem that does not support the encoding of file
handles.
-This error can be returned only when an fanotify file descriptor returned
-by
-.BR fanotify_init (2)
-has been created with
-.BR FAN_REPORT_FID .
+This error can be returned only with an fanotify group that identifies
+filesystem objects by file handles.
.TP
.B EXDEV
The filesystem object indicated by
@@ -466,11 +449,8 @@ resides within a filesystem subvolume (e.g.,
which uses a different
.I fsid
than its root superblock.
-This error can be returned only when an fanotify file descriptor returned
-by
-.BR fanotify_init (2)
-has been created with
-.BR FAN_REPORT_FID .
+This error can be returned only with an fanotify group that identifies
+filesystem objects by file handles.
.SH VERSIONS
.BR fanotify_mark ()
was introduced in version 2.6.36 of the Linux kernel and enabled in version
diff --git a/man7/fanotify.7 b/man7/fanotify.7
index a7d60b2b9..a7b219168 100644
--- a/man7/fanotify.7
+++ b/man7/fanotify.7
@@ -110,13 +110,11 @@ Two types of events are generated:
events and
.I permission
events.
-Notification events are merely informative
-and require no action to be taken by
-the receiving application with the exception being that the file
-descriptor provided within a generic event must be closed.
-The closing of file descriptors for each event applies only to
-applications that have initialized fanotify without using
-.BR FAN_REPORT_FID
+Notification events are merely informative and require no action to be taken
+by the receiving application with one exception - if a valid file descriptor
+is provided within a generic event, the file descriptor must be closed.
+File descriptors are not provided with event to applications that have
+created fanotify group so that it identifies filesystem objects by file handles
(see below).
Permission events are requests to the receiving application to decide
whether permission for a file access shall be granted.
@@ -147,7 +145,9 @@ The use of the
flag in
.BR fanotify_init (2)
influences what data structures are returned to the event listener for each
-event.
+event. Events reported to a group initialized with this flag will
+use file handles to identify filesystem objects instead of file descriptors.
+.TP
After a successful
.BR read (2),
the read buffer contains one or more of the following structures:
@@ -166,17 +166,20 @@ struct fanotify_event_metadata {
.EE
.in
.PP
-In the case where
-.BR FAN_REPORT_FID
-is supplied as one of the flags to
-.BR fanotify_init (2),
-you should also expect to receive the structure detailed below following
-the generic
+In case of an fanotify group that identifies filesystem objects by file
+handles, you should also expect to receive one or more additional information
+records of the structure detailed below following the generic
.I fanotify_event_metadata
structure within the read buffer:
.PP
.in +4n
.EX
+struct fanotify_event_info_header {
+ __u8 info_type;
+ __u8 pad;
+ __u16 len;
+};
+
struct fanotify_event_info_fid {
struct fanotify_event_info_header hdr;
__kernel_fsid_t fsid;
@@ -202,16 +205,13 @@ structure are as follows:
.I event_len
This is the length of the data for the current event and the offset
to the next event in the buffer.
-Without
-.BR FAN_REPORT_FID ,
-the value of
+Unless the group identifies filesystem objects by file handles, the value of
.I event_len
is always
.BR FAN_EVENT_METADATA_LEN .
-With
-.BR FAN_REPORT_FID ,
+For a group that identifies filesystem objects by file handles,
.I event_len
-also includes the variable length file identifier.
+also includes the variable length file identifier records.
.TP
.I vers
This field holds a version number for the structure.
@@ -238,8 +238,7 @@ This is a bit mask describing the event (see below).
This is an open file descriptor for the object being accessed, or
.B FAN_NOFD
if a queue overflow occurred.
-If the fanotify file descriptor has been initialized using
-.BR FAN_REPORT_FID ,
+With an fanotify group that identifies filesystem objects by file handles,
applications should expect this value to be set to
.B FAN_NOFD
for each event that is received.
@@ -395,9 +394,8 @@ See
for additional details.
The
.BR FAN_ONDIR
-flag is reported in an event mask only if the fanotify group has been
-initialized with the flag
-.BR FAN_REPORT_FID .
+flag is reported in an event mask only if the fanotify group identifies
+filesystem objects by file handles.
.PP
The fields of the
.I fanotify_event_info_fid
@@ -406,24 +404,30 @@ structure are as follows:
.I hdr
This is a structure of type
.IR fanotify_event_info_header .
-It is a generic header that contains information used to describe
-additional information attached to the event.
+It is a generic header that contains information used to describe an
+additional information record attached to the event.
For example, when an fanotify file descriptor is created using
.BR FAN_REPORT_FID ,
-the
+a single information record is expected to be attached to the event with
.I info_type
-field of this header is set to
+field value of
.BR FAN_EVENT_INFO_TYPE_FID .
-Event listeners can use this field to check that the additional
-information received for an event is of the correct type.
-Additionally, the
+The
.I fanotify_event_info_header
-also contains a
+contains a
.I len
field.
-In the current implementation, the value of
+The value of
.I len
-is always (event_len \- FAN_EVENT_METADATA_LEN).
+is the size of the additional information record including the
+.IR fanotify_event_info_header
+itself. The total size of all additional information records is not expected
+to be bigger than
+(
+.IR event_len
+\-
+.IR metadata_len
+).
.TP
.I fsid
This is a unique identifier of the filesystem containing the object
@@ -436,31 +440,35 @@ when calling
.BR statfs (2).
.TP
.I file_handle
-This is a variable length structure of type
-.IR file_handle .
+This is a variable length structure of type struct file_handle.
It is an opaque handle that corresponds to a specified object on a
filesystem as returned by
.BR name_to_handle_at (2).
It can be used to uniquely identify a file on a filesystem and can be
passed as an argument to
.BR open_by_handle_at (2).
-Note that for directory entry events, such as
+Note that for the directory entry modification events
.BR FAN_CREATE ,
.BR FAN_DELETE ,
and
.BR FAN_MOVE ,
the
.IR file_handle
-describes the modified directory and not the created/deleted/moved child
+identifies the modified directory and not the created/deleted/moved child
object.
-The events
+For other events such as
+.BR FAN_OPEN ,
.BR FAN_ATTRIB ,
.BR FAN_DELETE_SELF ,
and
-.BR FAN_MOVE_SELF
-will carry the
+.BR FAN_MOVE_SELF ,
+if the value of
+.I info_type
+field is
+.BR FAN_EVENT_INFO_TYPE_FID ,
+the
.IR file_handle
-information for the child object if the child object is being watched.
+identifies the object correlated to the event.
.PP
The following macros are provided to iterate over a buffer containing
fanotify event metadata returned by a
--
2.17.1
