[PATCH 0/3] Fanotify man page updates for v5.9

[PATCH 0/3] Fanotify man page updates for v5.9

[Amir Goldstein]

Hi Michael,

These man page updates are posted for the first time, but already
incorporate a lot of feedback provided by Jan Kara on github.

But let's wait for some ACKs here as well...

Thanks,
Amir.


Amir Goldstein (3):
  fanotify.7, fanotify_mark.2: Generalize documentation of
    FAN_REPORT_FID
  fanotify.7, fanotify_init.2: Document FAN_REPORT_DIR_FID
  fanotify.7, fanotify_init.2: Document FAN_REPORT_NAME

 man2/fanotify_init.2 | 115 ++++++++++++++++++++++---
 man2/fanotify_mark.2 |  50 ++++-------
 man7/fanotify.7      | 201 ++++++++++++++++++++++++++++++-------------
 3 files changed, 258 insertions(+), 108 deletions(-)

-- 
2.17.1

[PATCH 1/3] fanotify.7, fanotify_mark.2: Generalize documentation of FAN_REPORT_FID

[Amir Goldstein]

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@gmail.com>
---
 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

[PATCH 2/3] fanotify.7, fanotify_init.2: Document FAN_REPORT_DIR_FID

[Amir Goldstein]

Document fanotify_init(2) flag FAN_REPORT_DIR_FID and event info type
FAN_EVENT_INFO_TYPE_DFID.

Signed-off-by: Amir Goldstein <amir73il@gmail.com>
---
 man2/fanotify_init.2 | 35 +++++++++++++++++++++++++++++++++--
 man7/fanotify.7      | 30 ++++++++++++++++++++++++++----
 2 files changed, 59 insertions(+), 6 deletions(-)

diff --git a/man2/fanotify_init.2 b/man2/fanotify_init.2
index 54646e3c6..c58ae4493 100644
--- a/man2/fanotify_init.2
+++ b/man2/fanotify_init.2
@@ -1,4 +1,4 @@
-.\" Copyright (C) 2013, Heinrich Schuchardt <xypron.glpk@gmx.de>
+\" Copyright (C) 2013, Heinrich Schuchardt <xypron.glpk@gmx.de>
 .\"
 .\" %%%LICENSE_START(VERBATIM)
 .\" Permission is granted to make and distribute verbatim copies of this
@@ -191,7 +191,38 @@ is not permitted with this flag and will result in the error
 .BR EINVAL .
 See
 .BR fanotify (7)
-for additional information.
+for additional details.
+.TP
+.BR FAN_REPORT_DIR_FID " (since Linux 5.9)"
+Events for fanotify groups initialized with this flag will contain
+(see exceptions below) additional information about a directory object
+correlated to an event.
+An additional record of type
+.BR FAN_EVENT_INFO_TYPE_DFID
+encapsulates the information about the directory object and is included
+alongside the generic event metadata structure.
+For events that occur on a non-directory object, the additional structure
+includes a file handle that identifies the parent directory filesystem object.
+Note that there is no guarantee that the directory filesystem object will be
+found at the location described by the file handle information at the time
+the event is received.
+In combination with the flag
+.BR FAN_REPORT_FID ,
+two records may be reported with events that occur on a non-directory object,
+one to identify the non-directory object itself and one to identify the parent
+directory object.
+Note that in some cases, a filesystem object does not have a parent,
+for example, when an event occurs on an unlinked but open file.
+In that case, with the
+.BR FAN_REPORT_FID
+flag, the event will be reported with only one record to identify the
+non-directory object itself, because there is no directory associated with
+the event. Without the
+.BR FAN_REPORT_FID
+flag, no event will be reported.
+See
+.BR fanotify (7)
+for additional details.
 .PP
 The
 .I event_f_flags
diff --git a/man7/fanotify.7 b/man7/fanotify.7
index a7b219168..00fc56368 100644
--- a/man7/fanotify.7
+++ b/man7/fanotify.7
@@ -140,12 +140,13 @@ until either a file event occurs or the call is interrupted by a signal
 (see
 .BR signal (7)).
 .PP
-The use of the
-.BR FAN_REPORT_FID
-flag in
+The use of one of the flags
+.BR FAN_REPORT_FID ,
+.BR FAN_REPORT_DIR_FID
+in
 .BR fanotify_init (2)
 influences what data structures are returned to the event listener for each
-event. Events reported to a group initialized with this flag will
+event. Events reported to a group initialized with one of these flags will
 use file handles to identify filesystem objects instead of file descriptors.
 .TP
 After a successful
@@ -412,6 +413,19 @@ a single information record is expected to be attached to the event with
 .I info_type
 field value of
 .BR FAN_EVENT_INFO_TYPE_FID .
+When an fanotify file descriptor is created using the combination of
+.BR FAN_REPORT_FID
+and
+.BR FAN_REPORT_DIR_FID ,
+there may be two information records attached to the event. One with
+.I info_type
+field value of
+.BR FAN_EVENT_INFO_TYPE_DFID ,
+identifying a parent directory object, and one with
+.I info_type
+field value of
+.BR FAN_EVENT_INFO_TYPE_FID ,
+identifying a non-directory object.
 The
 .I fanotify_event_info_header
 contains a
@@ -469,6 +483,14 @@ field is
 the
 .IR file_handle
 identifies the object correlated to the event.
+If the value of
+.I info_type
+field is
+.BR FAN_EVENT_INFO_TYPE_DFID ,
+the
+.IR file_handle
+identifies the directory object correlated to the event or the parent directory
+of the non-directory 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

[PATCH 3/3] fanotify.7, fanotify_init.2: Document FAN_REPORT_NAME

[Amir Goldstein]

Document fanotify_init(2) flag FAN_REPORT_NAME and the format of the
event info type FAN_EVENT_INFO_TYPE_DFID_NAME.

The fanotify_fid.c example is extended to also report the name of the
created file or sub-directory.

Signed-off-by: Amir Goldstein <amir73il@gmail.com>
---
 man2/fanotify_init.2 | 54 +++++++++++++++++++++++++++++
 man7/fanotify.7      | 81 ++++++++++++++++++++++++++++++++++----------
 2 files changed, 118 insertions(+), 17 deletions(-)

diff --git a/man2/fanotify_init.2 b/man2/fanotify_init.2
index c58ae4493..a2e2a17fc 100644
--- a/man2/fanotify_init.2
+++ b/man2/fanotify_init.2
@@ -223,6 +223,60 @@ flag, no event will be reported.
 See
 .BR fanotify (7)
 for additional details.
+.TP
+.BR FAN_REPORT_NAME " (since Linux 5.9)"
+Events for fanotify groups initialized with this flag will contain additional
+information about the name of the directory entry correlated to an event.
+This flag must be provided in conjunction with the flag
+.BR FAN_REPORT_DIR_FID .
+Providing this flag value without
+.BR FAN_REPORT_DIR_FID
+will result in the error
+.BR EINVAL .
+This flag may be combined with the flag
+.BR FAN_REPORT_FID .
+An additional record of type
+.BR FAN_EVENT_INFO_TYPE_DFID_NAME ,
+which encapsulates the information about the directory entry is included
+alongside the generic event metadata structure and substitutes the additional
+information record of type
+.BR FAN_EVENT_INFO_TYPE_DFID .
+The additional record includes a file handle that identifies a directory
+filesystem object followed by a name that identifies an entry in that
+directory.
+For the directory entry modification events
+.BR FAN_CREATE ,
+.BR FAN_DELETE ,
+and
+.BR FAN_MOVE ,
+the reported name is that of the created/deleted/moved directory entry.
+For other events that occur on a directory object, the reported file handle
+is that of the directory object itself and the reported name is '.'.
+For other events that occur on a non-directory object, the reported file handle
+is that of the parent directory object and the reported name is the name of a
+directory entry where the object was located at the time of the event.
+The rational behind this logic is that the reported directory file handle can
+be passed to
+.BR open_by_handle_at (2)
+to get an open directory file descriptor and that file descriptor along with
+the reported name can be used to call
+.BR fstatat (2).
+The same rule that applies to record type
+.BR FAN_EVENT_INFO_TYPE_DFID
+also applies to record type
+.BR FAN_EVENT_INFO_TYPE_DFID_NAME \ -
+if a non-directory object has no parent, either the event will not be reported
+or it will be reported without the directory entry information.
+Note that there is no guarantee that the filesystem object will be found at the
+location described by the directory entry information at the time the event is
+received.
+See
+.BR fanotify (7)
+for additional details.
+.TP
+.B FAN_REPORT_DFID_NAME
+This is a synonym for
+.RB ( FAN_REPORT_DIR_FID | FAN_REPORT_NAME ).
 .PP
 The
 .I event_f_flags
diff --git a/man7/fanotify.7 b/man7/fanotify.7
index 00fc56368..5046fce02 100644
--- a/man7/fanotify.7
+++ b/man7/fanotify.7
@@ -470,6 +470,12 @@ the
 .IR file_handle
 identifies the modified directory and not the created/deleted/moved child
 object.
+If the value of
+.I info_type
+field is
+.BR FAN_EVENT_INFO_TYPE_DFID_NAME ,
+the file handle is followed by a null terminated string that identifies the
+created/deleted/moved directory entry name.
 For other events such as
 .BR FAN_OPEN ,
 .BR FAN_ATTRIB ,
@@ -490,7 +496,18 @@ field is
 the
 .IR file_handle
 identifies the directory object correlated to the event or the parent directory
-of the non-directory object correlated to the event.
+of a non-directory object correlated to the event.
+If the value of
+.I info_type
+field is
+.BR FAN_EVENT_INFO_TYPE_DFID_NAME ,
+the
+.IR file_handle
+identifies the same directory object that would be reported with
+.BR FAN_EVENT_INFO_TYPE_DFID
+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 following macros are provided to iterate over a buffer containing
 fanotify event metadata returned by a
@@ -675,12 +692,17 @@ events for the monitored directory itself.
 Fanotify monitoring of directories is not recursive:
 to monitor subdirectories under a directory,
 additional marks must be created.
-(But note that the fanotify API provides no way of detecting when a
-subdirectory has been created under a marked directory,
-which makes recursive monitoring difficult.)
-Monitoring mounts offers the capability to monitor a whole directory tree.
+The
+.B FAN_CREATE
+event can be used for detecting when a subdirectory has been created under
+a marked directory.
+An additional mark must then be set on the newly created subdirectory.
+This approach is racy, because it can lose events that occurred inside the
+newly created subdirectory, before a mark is added on that subdirectory.
+Monitoring mounts offers the capability to monitor a whole directory tree
+in a race free manner.
 Monitoring filesystems offers the capability to monitor changes made from
-any mount of a filesystem instance.
+any mount of a filesystem instance in a race free manner.
 .PP
 The event queue can overflow.
 In this case, events are lost.
@@ -964,9 +986,8 @@ main(int argc, char *argv[])
 .EE
 .\"
 .SS Example program: fanotify_fid.c
-The second program is an example of fanotify being used with
-.B FAN_REPORT_FID
-enabled.
+The second program is an example of fanotify being used with a group that
+identifies objects by file handles.
 The program marks the filesystem object that is passed as
 a command-line argument
 and waits until an event of type
@@ -987,7 +1008,7 @@ This is followed by the creation of a regular file,
 This results in a
 .B FAN_CREATE
 event being generated and reported against the file's parent watched
-directory object.
+directory object and with the created file name.
 Program execution ends once all events captured within the buffer have
 been processed.
 .PP
@@ -997,6 +1018,7 @@ been processed.
 Listening for events.
 FAN_CREATE (file created):
         Directory /home/user has been modified.
+        Entry 'testfile.txt' is not a subdirectory.
 All events processed successfully. Program exiting.
 
 $ \fBtouch /home/user/testfile.txt\fP              # In another terminal
@@ -1011,7 +1033,7 @@ This specific action results in a
 .B FAN_CREATE
 event being generated and is reported with the
 .B FAN_ONDIR
-flag set.
+flag set and with the created directory name.
 .PP
 .in +4n
 .EX
@@ -1019,6 +1041,7 @@ flag set.
 Listening for events.
 FAN_CREATE | FAN_ONDIR (subdirectory created):
         Directory /home/user has been modified.
+        Entry 'testdir' is a subdirectory.
 All events processed successfully. Program exiting.
 
 $ \fBmkdir \-p /home/user/testdir\fP          # In another terminal
@@ -1051,6 +1074,8 @@ main(int argc, char **argv)
     struct file_handle *file_handle;
     struct fanotify_event_metadata *metadata;
     struct fanotify_event_info_fid *fid;
+    const char *file_name;
+    struct stat sb;
 
     if (argc != 2) {
         fprintf(stderr, "Invalid number of command line arguments.\en");
@@ -1064,10 +1089,10 @@ main(int argc, char **argv)
     }
 
 
-    /* Create an fanotify file descriptor with FAN_REPORT_FID as a flag
-       so that program can receive fid events. */
+    /* Create an fanotify file descriptor with FAN_REPORT_DFID_NAME as a flag
+       so that program can receive fid events with directory entry name. */
 
-    fd = fanotify_init(FAN_CLASS_NOTIF | FAN_REPORT_FID, 0);
+    fd = fanotify_init(FAN_CLASS_NOTIF | FAN_REPORT_DFID_NAME, 0);
     if (fd == \-1) {
         perror("fanotify_init");
         exit(EXIT_FAILURE);
@@ -1103,7 +1128,13 @@ main(int argc, char **argv)
 
         /* Ensure that the event info is of the correct type */
 
-        if (fid\->hdr.info_type != FAN_EVENT_INFO_TYPE_FID) {
+        if (fid\->hdr.info_type == FAN_EVENT_INFO_TYPE_FID ||
+            fid\->hdr.info_type == FAN_EVENT_INFO_TYPE_DFID) {
+            file_name = NULL;
+        } else if (fid\->hdr.info_type == FAN_EVENT_INFO_TYPE_DFID_NAME) {
+            file_name = file_handle->f_handle +
+                        file_handle->handle_bytes;
+        } else {
             fprintf(stderr, "Received unexpected event info type.\en");
             exit(EXIT_FAILURE);
         }
@@ -1114,8 +1145,8 @@ main(int argc, char **argv)
         if (metadata\->mask == (FAN_CREATE | FAN_ONDIR))
             printf("FAN_CREATE | FAN_ONDIR (subdirectory created):\en");
 
-        /* metadata\->fd is set to FAN_NOFD when FAN_REPORT_FID is
-           enabled.  To obtain a file descriptor for the file object
+        /* metadata\->fd is set to FAN_NOFD when the group identifies objects
+           by file handles.  To obtain a file descriptor for the file object
            corresponding to an event you can use the struct file_handle
            that\(aqs provided within the fanotify_event_info_fid in
            conjunction with the open_by_handle_at(2) system call.
@@ -1149,6 +1180,22 @@ main(int argc, char **argv)
         path[path_len] = \(aq\e0\(aq;
         printf("\etDirectory \(aq%s\(aq has been modified.\en", path);
 
+        if (file_name) {
+            ret = fstatat(event_fd, file_name, &sb, 0);
+            if (ret == \-1) {
+                if (errno != ENOENT) {
+                    perror("fstatat");
+                    exit(EXIT_FAILURE);
+                }
+                printf("\etEntry \(aq%s\(aq does not exist.\en", file_name);
+            } else if ((sb.st_mode & S_IFMT) == S_IFDIR) {
+                printf("\etEntry \(aq%s\(aq is a subdirectory.\en", file_name);
+            } else {
+                printf("\etEntry \(aq%s\(aq is not a subdirectory.\en",
+                        file_name);
+            }
+        }
+
         /* Close associated file descriptor for this event */
 
         close(event_fd);
-- 
2.17.1

Re: [PATCH 1/3] fanotify.7, fanotify_mark.2: Generalize documentation of FAN_REPORT_FID

[Jan Kara]

On Mon 24-08-20 11:03:24, Amir Goldstein wrote:
> 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@gmail.com>

The changes look good to me. You can add:

Reviewed-by: Jan Kara <jack@suse.cz>

								Honza

> ---
>  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
> 
-- 
Jan Kara <jack@suse.com>
SUSE Labs, CR

Re: [PATCH 2/3] fanotify.7, fanotify_init.2: Document FAN_REPORT_DIR_FID

[Jan Kara]

On Mon 24-08-20 11:03:25, Amir Goldstein wrote:
> Document fanotify_init(2) flag FAN_REPORT_DIR_FID and event info type
> FAN_EVENT_INFO_TYPE_DFID.
> 
> Signed-off-by: Amir Goldstein <amir73il@gmail.com>

The patch looks good to me. You can add:

Reviewed-by: Jan Kara <jack@suse.cz>

								Honza

> ---
>  man2/fanotify_init.2 | 35 +++++++++++++++++++++++++++++++++--
>  man7/fanotify.7      | 30 ++++++++++++++++++++++++++----
>  2 files changed, 59 insertions(+), 6 deletions(-)
> 
> diff --git a/man2/fanotify_init.2 b/man2/fanotify_init.2
> index 54646e3c6..c58ae4493 100644
> --- a/man2/fanotify_init.2
> +++ b/man2/fanotify_init.2
> @@ -1,4 +1,4 @@
> -.\" Copyright (C) 2013, Heinrich Schuchardt <xypron.glpk@gmx.de>
> +\" Copyright (C) 2013, Heinrich Schuchardt <xypron.glpk@gmx.de>
>  .\"
>  .\" %%%LICENSE_START(VERBATIM)
>  .\" Permission is granted to make and distribute verbatim copies of this
> @@ -191,7 +191,38 @@ is not permitted with this flag and will result in the error
>  .BR EINVAL .
>  See
>  .BR fanotify (7)
> -for additional information.
> +for additional details.
> +.TP
> +.BR FAN_REPORT_DIR_FID " (since Linux 5.9)"
> +Events for fanotify groups initialized with this flag will contain
> +(see exceptions below) additional information about a directory object
> +correlated to an event.
> +An additional record of type
> +.BR FAN_EVENT_INFO_TYPE_DFID
> +encapsulates the information about the directory object and is included
> +alongside the generic event metadata structure.
> +For events that occur on a non-directory object, the additional structure
> +includes a file handle that identifies the parent directory filesystem object.
> +Note that there is no guarantee that the directory filesystem object will be
> +found at the location described by the file handle information at the time
> +the event is received.
> +In combination with the flag
> +.BR FAN_REPORT_FID ,
> +two records may be reported with events that occur on a non-directory object,
> +one to identify the non-directory object itself and one to identify the parent
> +directory object.
> +Note that in some cases, a filesystem object does not have a parent,
> +for example, when an event occurs on an unlinked but open file.
> +In that case, with the
> +.BR FAN_REPORT_FID
> +flag, the event will be reported with only one record to identify the
> +non-directory object itself, because there is no directory associated with
> +the event. Without the
> +.BR FAN_REPORT_FID
> +flag, no event will be reported.
> +See
> +.BR fanotify (7)
> +for additional details.
>  .PP
>  The
>  .I event_f_flags
> diff --git a/man7/fanotify.7 b/man7/fanotify.7
> index a7b219168..00fc56368 100644
> --- a/man7/fanotify.7
> +++ b/man7/fanotify.7
> @@ -140,12 +140,13 @@ until either a file event occurs or the call is interrupted by a signal
>  (see
>  .BR signal (7)).
>  .PP
> -The use of the
> -.BR FAN_REPORT_FID
> -flag in
> +The use of one of the flags
> +.BR FAN_REPORT_FID ,
> +.BR FAN_REPORT_DIR_FID
> +in
>  .BR fanotify_init (2)
>  influences what data structures are returned to the event listener for each
> -event. Events reported to a group initialized with this flag will
> +event. Events reported to a group initialized with one of these flags will
>  use file handles to identify filesystem objects instead of file descriptors.
>  .TP
>  After a successful
> @@ -412,6 +413,19 @@ a single information record is expected to be attached to the event with
>  .I info_type
>  field value of
>  .BR FAN_EVENT_INFO_TYPE_FID .
> +When an fanotify file descriptor is created using the combination of
> +.BR FAN_REPORT_FID
> +and
> +.BR FAN_REPORT_DIR_FID ,
> +there may be two information records attached to the event. One with
> +.I info_type
> +field value of
> +.BR FAN_EVENT_INFO_TYPE_DFID ,
> +identifying a parent directory object, and one with
> +.I info_type
> +field value of
> +.BR FAN_EVENT_INFO_TYPE_FID ,
> +identifying a non-directory object.
>  The
>  .I fanotify_event_info_header
>  contains a
> @@ -469,6 +483,14 @@ field is
>  the
>  .IR file_handle
>  identifies the object correlated to the event.
> +If the value of
> +.I info_type
> +field is
> +.BR FAN_EVENT_INFO_TYPE_DFID ,
> +the
> +.IR file_handle
> +identifies the directory object correlated to the event or the parent directory
> +of the non-directory 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
> 
-- 
Jan Kara <jack@suse.com>
SUSE Labs, CR

Re: [PATCH 3/3] fanotify.7, fanotify_init.2: Document FAN_REPORT_NAME

[Jan Kara]

On Mon 24-08-20 11:03:26, Amir Goldstein wrote:
> Document fanotify_init(2) flag FAN_REPORT_NAME and the format of the
> event info type FAN_EVENT_INFO_TYPE_DFID_NAME.
> 
> The fanotify_fid.c example is extended to also report the name of the
> created file or sub-directory.
> 
> Signed-off-by: Amir Goldstein <amir73il@gmail.com>

Just one spelling fix below. Otherwise feel free to add:

Reviewed-by: Jan Kara <jack@suse.cz>

								Honza


> diff --git a/man2/fanotify_init.2 b/man2/fanotify_init.2
> index c58ae4493..a2e2a17fc 100644
> --- a/man2/fanotify_init.2
> +++ b/man2/fanotify_init.2
> @@ -223,6 +223,60 @@ flag, no event will be reported.
>  See
>  .BR fanotify (7)
>  for additional details.
> +.TP
> +.BR FAN_REPORT_NAME " (since Linux 5.9)"
> +Events for fanotify groups initialized with this flag will contain additional
> +information about the name of the directory entry correlated to an event.
> +This flag must be provided in conjunction with the flag
> +.BR FAN_REPORT_DIR_FID .
> +Providing this flag value without
> +.BR FAN_REPORT_DIR_FID
> +will result in the error
> +.BR EINVAL .
> +This flag may be combined with the flag
> +.BR FAN_REPORT_FID .
> +An additional record of type
> +.BR FAN_EVENT_INFO_TYPE_DFID_NAME ,
> +which encapsulates the information about the directory entry is included
> +alongside the generic event metadata structure and substitutes the additional
> +information record of type
> +.BR FAN_EVENT_INFO_TYPE_DFID .
> +The additional record includes a file handle that identifies a directory
> +filesystem object followed by a name that identifies an entry in that
> +directory.
> +For the directory entry modification events
> +.BR FAN_CREATE ,
> +.BR FAN_DELETE ,
> +and
> +.BR FAN_MOVE ,
> +the reported name is that of the created/deleted/moved directory entry.
> +For other events that occur on a directory object, the reported file handle
> +is that of the directory object itself and the reported name is '.'.
> +For other events that occur on a non-directory object, the reported file handle
> +is that of the parent directory object and the reported name is the name of a
> +directory entry where the object was located at the time of the event.
> +The rational behind this logic is that the reported directory file handle can
       ^^^^^^^ rationale
-- 
Jan Kara <jack@suse.com>
SUSE Labs, CR

Re: [PATCH 2/3] fanotify.7, fanotify_init.2: Document FAN_REPORT_DIR_FID

[Matthew Bobrowski]

On Mon, Aug 24, 2020 at 11:03:25AM +0300, Amir Goldstein wrote:
> Document fanotify_init(2) flag FAN_REPORT_DIR_FID and event info type
> FAN_EVENT_INFO_TYPE_DFID.
> 
> Signed-off-by: Amir Goldstein <amir73il@gmail.com>

I've made one minor suggestion below. Other than that, this patch
looks healthy to me.

Reviewed-by: Matthew Bobrowski <mbobrowski@mbobrowski.org>

> ---
>  man2/fanotify_init.2 | 35 +++++++++++++++++++++++++++++++++--
>  man7/fanotify.7      | 30 ++++++++++++++++++++++++++----
>  2 files changed, 59 insertions(+), 6 deletions(-)
> 
> diff --git a/man2/fanotify_init.2 b/man2/fanotify_init.2
> index 54646e3c6..c58ae4493 100644
> --- a/man2/fanotify_init.2
> +++ b/man2/fanotify_init.2
> @@ -1,4 +1,4 @@
> -.\" Copyright (C) 2013, Heinrich Schuchardt <xypron.glpk@gmx.de>
> +\" Copyright (C) 2013, Heinrich Schuchardt <xypron.glpk@gmx.de>
>  .\"
>  .\" %%%LICENSE_START(VERBATIM)
>  .\" Permission is granted to make and distribute verbatim copies of this
> @@ -191,7 +191,38 @@ is not permitted with this flag and will result in the error
>  .BR EINVAL .
>  See
>  .BR fanotify (7)
> -for additional information.
> +for additional details.
> +.TP
> +.BR FAN_REPORT_DIR_FID " (since Linux 5.9)"
> +Events for fanotify groups initialized with this flag will contain
> +(see exceptions below) additional information about a directory object
> +correlated to an event.
> +An additional record of type
> +.BR FAN_EVENT_INFO_TYPE_DFID
> +encapsulates the information about the directory object and is included
> +alongside the generic event metadata structure.
> +For events that occur on a non-directory object, the additional structure
> +includes a file handle that identifies the parent directory filesystem object.
> +Note that there is no guarantee that the directory filesystem object will be
> +found at the location described by the file handle information at the time
> +the event is received.
> +In combination with the flag

I think it would read a lot nicer if we used:
When combined with the flag

> +.BR FAN_REPORT_FID ,
> +two records may be reported with events that occur on a non-directory object,
> +one to identify the non-directory object itself and one to identify the parent
> +directory object.
> +Note that in some cases, a filesystem object does not have a parent,
> +for example, when an event occurs on an unlinked but open file.
> +In that case, with the
> +.BR FAN_REPORT_FID
> +flag, the event will be reported with only one record to identify the
> +non-directory object itself, because there is no directory associated with
> +the event. Without the
> +.BR FAN_REPORT_FID
> +flag, no event will be reported.
> +See
> +.BR fanotify (7)
> +for additional details.
>  .PP
>  The
>  .I event_f_flags
> diff --git a/man7/fanotify.7 b/man7/fanotify.7
> index a7b219168..00fc56368 100644
> --- a/man7/fanotify.7
> +++ b/man7/fanotify.7
> @@ -140,12 +140,13 @@ until either a file event occurs or the call is interrupted by a signal
>  (see
>  .BR signal (7)).
>  .PP
> -The use of the
> -.BR FAN_REPORT_FID
> -flag in
> +The use of one of the flags
> +.BR FAN_REPORT_FID ,
> +.BR FAN_REPORT_DIR_FID
> +in
>  .BR fanotify_init (2)
>  influences what data structures are returned to the event listener for each
> -event. Events reported to a group initialized with this flag will
> +event. Events reported to a group initialized with one of these flags will
>  use file handles to identify filesystem objects instead of file descriptors.
>  .TP
>  After a successful
> @@ -412,6 +413,19 @@ a single information record is expected to be attached to the event with
>  .I info_type
>  field value of
>  .BR FAN_EVENT_INFO_TYPE_FID .
> +When an fanotify file descriptor is created using the combination of
> +.BR FAN_REPORT_FID
> +and
> +.BR FAN_REPORT_DIR_FID ,
> +there may be two information records attached to the event. One with
> +.I info_type
> +field value of
> +.BR FAN_EVENT_INFO_TYPE_DFID ,
> +identifying a parent directory object, and one with
> +.I info_type
> +field value of
> +.BR FAN_EVENT_INFO_TYPE_FID ,
> +identifying a non-directory object.
>  The
>  .I fanotify_event_info_header
>  contains a
> @@ -469,6 +483,14 @@ field is
>  the
>  .IR file_handle
>  identifies the object correlated to the event.
> +If the value of
> +.I info_type
> +field is
> +.BR FAN_EVENT_INFO_TYPE_DFID ,
> +the
> +.IR file_handle
> +identifies the directory object correlated to the event or the parent directory
> +of the non-directory 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
> 
/M

Re: [PATCH 3/3] fanotify.7, fanotify_init.2: Document FAN_REPORT_NAME

[Matthew Bobrowski]

On Mon, Aug 24, 2020 at 11:03:26AM +0300, Amir Goldstein wrote:
> Document fanotify_init(2) flag FAN_REPORT_NAME and the format of the
> event info type FAN_EVENT_INFO_TYPE_DFID_NAME.

These names sure are becoming a little bit of a mouth full. :)
 
> The fanotify_fid.c example is extended to also report the name of the
> created file or sub-directory.
> 
> Signed-off-by: Amir Goldstein <amir73il@gmail.com>

Other than what Jan has already mentioned in regards to the spelling
correction, the patch looks good to me!  Feel free to add:

Reviewed-by: Matthew Bobrowski <mbobrowski@mbobrowski.org>

> ---
>  man2/fanotify_init.2 | 54 +++++++++++++++++++++++++++++
>  man7/fanotify.7      | 81 ++++++++++++++++++++++++++++++++++----------
>  2 files changed, 118 insertions(+), 17 deletions(-)
> 
> diff --git a/man2/fanotify_init.2 b/man2/fanotify_init.2
> index c58ae4493..a2e2a17fc 100644
> --- a/man2/fanotify_init.2
> +++ b/man2/fanotify_init.2
> @@ -223,6 +223,60 @@ flag, no event will be reported.
>  See
>  .BR fanotify (7)
>  for additional details.
> +.TP
> +.BR FAN_REPORT_NAME " (since Linux 5.9)"
> +Events for fanotify groups initialized with this flag will contain additional
> +information about the name of the directory entry correlated to an event.
> +This flag must be provided in conjunction with the flag
> +.BR FAN_REPORT_DIR_FID .
> +Providing this flag value without
> +.BR FAN_REPORT_DIR_FID
> +will result in the error
> +.BR EINVAL .
> +This flag may be combined with the flag
> +.BR FAN_REPORT_FID .
> +An additional record of type
> +.BR FAN_EVENT_INFO_TYPE_DFID_NAME ,
> +which encapsulates the information about the directory entry is included
> +alongside the generic event metadata structure and substitutes the additional
> +information record of type
> +.BR FAN_EVENT_INFO_TYPE_DFID .
> +The additional record includes a file handle that identifies a directory
> +filesystem object followed by a name that identifies an entry in that
> +directory.
> +For the directory entry modification events
> +.BR FAN_CREATE ,
> +.BR FAN_DELETE ,
> +and
> +.BR FAN_MOVE ,
> +the reported name is that of the created/deleted/moved directory entry.
> +For other events that occur on a directory object, the reported file handle
> +is that of the directory object itself and the reported name is '.'.
> +For other events that occur on a non-directory object, the reported file handle
> +is that of the parent directory object and the reported name is the name of a
> +directory entry where the object was located at the time of the event.
> +The rational behind this logic is that the reported directory file handle can
> +be passed to
> +.BR open_by_handle_at (2)
> +to get an open directory file descriptor and that file descriptor along with
> +the reported name can be used to call
> +.BR fstatat (2).
> +The same rule that applies to record type
> +.BR FAN_EVENT_INFO_TYPE_DFID
> +also applies to record type
> +.BR FAN_EVENT_INFO_TYPE_DFID_NAME \ -
> +if a non-directory object has no parent, either the event will not be reported
> +or it will be reported without the directory entry information.
> +Note that there is no guarantee that the filesystem object will be found at the
> +location described by the directory entry information at the time the event is
> +received.
> +See
> +.BR fanotify (7)
> +for additional details.
> +.TP
> +.B FAN_REPORT_DFID_NAME
> +This is a synonym for
> +.RB ( FAN_REPORT_DIR_FID | FAN_REPORT_NAME ).
>  .PP
>  The
>  .I event_f_flags
> diff --git a/man7/fanotify.7 b/man7/fanotify.7
> index 00fc56368..5046fce02 100644
> --- a/man7/fanotify.7
> +++ b/man7/fanotify.7
> @@ -470,6 +470,12 @@ the
>  .IR file_handle
>  identifies the modified directory and not the created/deleted/moved child
>  object.
> +If the value of
> +.I info_type
> +field is
> +.BR FAN_EVENT_INFO_TYPE_DFID_NAME ,
> +the file handle is followed by a null terminated string that identifies the
> +created/deleted/moved directory entry name.
>  For other events such as
>  .BR FAN_OPEN ,
>  .BR FAN_ATTRIB ,
> @@ -490,7 +496,18 @@ field is
>  the
>  .IR file_handle
>  identifies the directory object correlated to the event or the parent directory
> -of the non-directory object correlated to the event.
> +of a non-directory object correlated to the event.
> +If the value of
> +.I info_type
> +field is
> +.BR FAN_EVENT_INFO_TYPE_DFID_NAME ,
> +the
> +.IR file_handle
> +identifies the same directory object that would be reported with
> +.BR FAN_EVENT_INFO_TYPE_DFID
> +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 following macros are provided to iterate over a buffer containing
>  fanotify event metadata returned by a
> @@ -675,12 +692,17 @@ events for the monitored directory itself.
>  Fanotify monitoring of directories is not recursive:
>  to monitor subdirectories under a directory,
>  additional marks must be created.
> -(But note that the fanotify API provides no way of detecting when a
> -subdirectory has been created under a marked directory,
> -which makes recursive monitoring difficult.)
> -Monitoring mounts offers the capability to monitor a whole directory tree.
> +The
> +.B FAN_CREATE
> +event can be used for detecting when a subdirectory has been created under
> +a marked directory.
> +An additional mark must then be set on the newly created subdirectory.
> +This approach is racy, because it can lose events that occurred inside the
> +newly created subdirectory, before a mark is added on that subdirectory.
> +Monitoring mounts offers the capability to monitor a whole directory tree
> +in a race free manner.
>  Monitoring filesystems offers the capability to monitor changes made from
> -any mount of a filesystem instance.
> +any mount of a filesystem instance in a race free manner.
>  .PP
>  The event queue can overflow.
>  In this case, events are lost.
> @@ -964,9 +986,8 @@ main(int argc, char *argv[])
>  .EE
>  .\"
>  .SS Example program: fanotify_fid.c
> -The second program is an example of fanotify being used with
> -.B FAN_REPORT_FID
> -enabled.
> +The second program is an example of fanotify being used with a group that
> +identifies objects by file handles.
>  The program marks the filesystem object that is passed as
>  a command-line argument
>  and waits until an event of type
> @@ -987,7 +1008,7 @@ This is followed by the creation of a regular file,
>  This results in a
>  .B FAN_CREATE
>  event being generated and reported against the file's parent watched
> -directory object.
> +directory object and with the created file name.
>  Program execution ends once all events captured within the buffer have
>  been processed.
>  .PP
> @@ -997,6 +1018,7 @@ been processed.
>  Listening for events.
>  FAN_CREATE (file created):
>          Directory /home/user has been modified.
> +        Entry 'testfile.txt' is not a subdirectory.
>  All events processed successfully. Program exiting.
>  
>  $ \fBtouch /home/user/testfile.txt\fP              # In another terminal
> @@ -1011,7 +1033,7 @@ This specific action results in a
>  .B FAN_CREATE
>  event being generated and is reported with the
>  .B FAN_ONDIR
> -flag set.
> +flag set and with the created directory name.
>  .PP
>  .in +4n
>  .EX
> @@ -1019,6 +1041,7 @@ flag set.
>  Listening for events.
>  FAN_CREATE | FAN_ONDIR (subdirectory created):
>          Directory /home/user has been modified.
> +        Entry 'testdir' is a subdirectory.
>  All events processed successfully. Program exiting.
>  
>  $ \fBmkdir \-p /home/user/testdir\fP          # In another terminal
> @@ -1051,6 +1074,8 @@ main(int argc, char **argv)
>      struct file_handle *file_handle;
>      struct fanotify_event_metadata *metadata;
>      struct fanotify_event_info_fid *fid;
> +    const char *file_name;
> +    struct stat sb;
>  
>      if (argc != 2) {
>          fprintf(stderr, "Invalid number of command line arguments.\en");
> @@ -1064,10 +1089,10 @@ main(int argc, char **argv)
>      }
>  
>  
> -    /* Create an fanotify file descriptor with FAN_REPORT_FID as a flag
> -       so that program can receive fid events. */
> +    /* Create an fanotify file descriptor with FAN_REPORT_DFID_NAME as a flag
> +       so that program can receive fid events with directory entry name. */
>  
> -    fd = fanotify_init(FAN_CLASS_NOTIF | FAN_REPORT_FID, 0);
> +    fd = fanotify_init(FAN_CLASS_NOTIF | FAN_REPORT_DFID_NAME, 0);
>      if (fd == \-1) {
>          perror("fanotify_init");
>          exit(EXIT_FAILURE);
> @@ -1103,7 +1128,13 @@ main(int argc, char **argv)
>  
>          /* Ensure that the event info is of the correct type */
>  
> -        if (fid\->hdr.info_type != FAN_EVENT_INFO_TYPE_FID) {
> +        if (fid\->hdr.info_type == FAN_EVENT_INFO_TYPE_FID ||
> +            fid\->hdr.info_type == FAN_EVENT_INFO_TYPE_DFID) {
> +            file_name = NULL;
> +        } else if (fid\->hdr.info_type == FAN_EVENT_INFO_TYPE_DFID_NAME) {
> +            file_name = file_handle->f_handle +
> +                        file_handle->handle_bytes;
> +        } else {
>              fprintf(stderr, "Received unexpected event info type.\en");
>              exit(EXIT_FAILURE);
>          }
> @@ -1114,8 +1145,8 @@ main(int argc, char **argv)
>          if (metadata\->mask == (FAN_CREATE | FAN_ONDIR))
>              printf("FAN_CREATE | FAN_ONDIR (subdirectory created):\en");
>  
> -        /* metadata\->fd is set to FAN_NOFD when FAN_REPORT_FID is
> -           enabled.  To obtain a file descriptor for the file object
> +        /* metadata\->fd is set to FAN_NOFD when the group identifies objects
> +           by file handles.  To obtain a file descriptor for the file object
>             corresponding to an event you can use the struct file_handle
>             that\(aqs provided within the fanotify_event_info_fid in
>             conjunction with the open_by_handle_at(2) system call.
> @@ -1149,6 +1180,22 @@ main(int argc, char **argv)
>          path[path_len] = \(aq\e0\(aq;
>          printf("\etDirectory \(aq%s\(aq has been modified.\en", path);
>  
> +        if (file_name) {
> +            ret = fstatat(event_fd, file_name, &sb, 0);
> +            if (ret == \-1) {
> +                if (errno != ENOENT) {
> +                    perror("fstatat");
> +                    exit(EXIT_FAILURE);
> +                }
> +                printf("\etEntry \(aq%s\(aq does not exist.\en", file_name);
> +            } else if ((sb.st_mode & S_IFMT) == S_IFDIR) {
> +                printf("\etEntry \(aq%s\(aq is a subdirectory.\en", file_name);
> +            } else {
> +                printf("\etEntry \(aq%s\(aq is not a subdirectory.\en",
> +                        file_name);
> +            }
> +        }
> +
>          /* Close associated file descriptor for this event */
>  
>          close(event_fd);
> -- 
> 2.17.1
> 
/M

Re: [PATCH 1/3] fanotify.7, fanotify_mark.2: Generalize documentation of FAN_REPORT_FID

[Matthew Bobrowski]

On Mon, Aug 24, 2020 at 11:03:24AM +0300, Amir Goldstein wrote:
> 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@gmail.com>

...

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

Changes read well up until this point.

> +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).

Then there's this sentence, which doesn't really read overly smoothly
as if there was a few words missing or something. Or, quite possibly
it's just me not understanding something?

/M

Re: [PATCH 1/3] fanotify.7, fanotify_mark.2: Generalize documentation of FAN_REPORT_FID

[Amir Goldstein]

On Tue, Aug 25, 2020 at 2:50 AM Matthew Bobrowski
<mbobrowski@mbobrowski.org> wrote:
>
> On Mon, Aug 24, 2020 at 11:03:24AM +0300, Amir Goldstein wrote:
> > 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@gmail.com>
>
> ...
>
> > 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.
>
> Changes read well up until this point.
>
> > +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).
>
> Then there's this sentence, which doesn't really read overly smoothly
> as if there was a few words missing or something. Or, quite possibly
> it's just me not understanding something?
>

Yeh. I think this sentence doesn't serve anything in this context.
I will remove it.

So can I add your reviewed-by on this patch as well?

Thanks!
Amir.

Re: [PATCH 1/3] fanotify.7, fanotify_mark.2: Generalize documentation of FAN_REPORT_FID

[Matthew Bobrowski]

On Tue, Aug 25, 2020 at 11:19:35AM +0300, Amir Goldstein wrote:
> On Tue, Aug 25, 2020 at 2:50 AM Matthew Bobrowski
> > > +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).
> >
> > Then there's this sentence, which doesn't really read overly smoothly
> > as if there was a few words missing or something. Or, quite possibly
> > it's just me not understanding something?
> >
> 
> Yeh. I think this sentence doesn't serve anything in this context.
> I will remove it.
> 
> So can I add your reviewed-by on this patch as well?

Sure, you can add the Reviewed-by tag. 

/M

Re: [PATCH 1/3] fanotify.7, fanotify_mark.2: Generalize documentation of FAN_REPORT_FID

[Michael Kerrisk (man-pages)]

Hi Amir,

On Mon, 24 Aug 2020 at 10:03, Amir Goldstein <amir73il@gmail.com> wrote:
>
> 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.

If I understand correctly, this patch is just about improving the
description of existing behavior, in preparation for later patches
that describe new behavior (to be added in 5.9), and once you've
revised after Matthew's comments I can apply immediately, right?

Thanks,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: [PATCH 1/3] fanotify.7, fanotify_mark.2: Generalize documentation of FAN_REPORT_FID

[Amir Goldstein]

On Tue, Aug 25, 2020 at 2:45 PM Michael Kerrisk (man-pages)
<mtk.manpages@gmail.com> wrote:
>
> Hi Amir,
>
> On Mon, 24 Aug 2020 at 10:03, Amir Goldstein <amir73il@gmail.com> wrote:
> >
> > 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.
>
> If I understand correctly, this patch is just about improving the
> description of existing behavior, in preparation for later patches
> that describe new behavior (to be added in 5.9), and once you've
> revised after Matthew's comments I can apply immediately, right?
>

That is correct.

Thanks,
Amir.