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

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

[Amir Goldstein]

Hi Michael,

Posting v2 with Reviewed-by from Jan Kara and Matthew Bobrowski
and fixes for a few minor issues they pointed out.

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      | 200 +++++++++++++++++++++++++++++--------------
 3 files changed, 256 insertions(+), 109 deletions(-)

-- 
2.17.1

[PATCH v2 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>
Reviewed-by: Jan Kara <jack@suse.cz>
Reviewed-by: Matthew Bobrowski <mbobrowski@mbobrowski.org>
---
 man2/fanotify_init.2 | 26 ++++++++-----
 man2/fanotify_mark.2 | 50 +++++++-----------------
 man7/fanotify.7      | 93 +++++++++++++++++++++++---------------------
 3 files changed, 81 insertions(+), 88 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..734fa7b7c 100644
--- a/man7/fanotify.7
+++ b/man7/fanotify.7
@@ -110,14 +110,9 @@ 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
-(see below).
+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.
 Permission events are requests to the receiving application to decide
 whether permission for a file access shall be granted.
 For these events, the recipient must write a response which decides whether
@@ -147,7 +142,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 +163,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 +202,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 +235,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 +391,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 +401,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 +437,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 v2 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>
Reviewed-by: Jan Kara <jack@suse.cz>
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..6167a1c37 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.
+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 734fa7b7c..fa1c85159 100644
--- a/man7/fanotify.7
+++ b/man7/fanotify.7
@@ -137,12 +137,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
@@ -409,6 +410,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
@@ -466,6 +480,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 v2 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>
Reviewed-by: Jan Kara <jack@suse.cz>
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 6167a1c37..27dbfe498 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 rationale 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 fa1c85159..65fb2720a 100644
--- a/man7/fanotify.7
+++ b/man7/fanotify.7
@@ -467,6 +467,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 ,
@@ -487,7 +493,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
@@ -672,12 +689,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.
@@ -961,9 +983,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
@@ -984,7 +1005,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
@@ -994,6 +1015,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
@@ -1008,7 +1030,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
@@ -1016,6 +1038,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
@@ -1048,6 +1071,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");
@@ -1061,10 +1086,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);
@@ -1100,7 +1125,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);
         }
@@ -1111,8 +1142,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.
@@ -1146,6 +1177,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 v2 0/3] Fanotify man page updates for v5.9

[Michael Kerrisk (man-pages)]

Hi Amir,

On Tue, 25 Aug 2020 at 13:41, Amir Goldstein <amir73il@gmail.com> wrote:
>
> Hi Michael,
>
> Posting v2 with Reviewed-by from Jan Kara and Matthew Bobrowski
> and fixes for a few minor issues they pointed out.

Should I be merging these already, or waiting on the revised version
of your "fanotify.7, fanotify_mark.2: Generalize documentation of
FAN_REPORT_FID" patch?

Thanks,

Michael



> 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      | 200 +++++++++++++++++++++++++++++--------------
>  3 files changed, 256 insertions(+), 109 deletions(-)
>
> --
> 2.17.1
>


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

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

[Michael Kerrisk (man-pages)]

Hello Amir,

On 8/25/20 1:40 PM, Amir Goldstein wrote:
> Hi Michael,
> 
> Posting v2 with Reviewed-by from Jan Kara and Matthew Bobrowski
> and fixes for a few minor issues they pointed out.

I've applied all three patches, and done a very small number of edits
(there really wasn't much that I saw that could be improved!)

Amir, thanks (again_) for taking such good care of these 
fanotify pages; it makes my life so much easier!


Matthew, Jan, thanks for supporting the work Amir does!

Cheers,

Michael

> 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      | 200 +++++++++++++++++++++++++++++--------------
>  3 files changed, 256 insertions(+), 109 deletions(-)
> 


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