Skip to contentSkip to conversation

Fanotify man page updates for v5.9

PATCH In review Amir Goldstein 2 participants 6 messages Aug 25, 2020 – Aug 28, 2020 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore
Share & tools
lore
#0 lore raw

v2 cover Fanotify man page updates for v5.9

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(-)
Signature · 1 line
2.17.1
#1 lore raw

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

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.

---
 man2/fanotify_init.2 | 26 ++++++++-----
 man2/fanotify_mark.2 | 50 +++++++-----------------
 man7/fanotify.7      | 93 +++++++++++++++++++++++---------------------
 3 files changed, 81 insertions(+), 88 deletions(-)
man2/fanotify_init.2 +17 -9
index 8eedfe194..54646e3c6 100644
@@ -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
man2/fanotify_mark.2 +15 -35

120 lines not on this page · raw message

man7/fanotify.7 +49 -44

175 lines not on this page · raw message

Signature · 1 line
2.17.1
#2 lore raw

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

In reply to Amir Goldstein

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

---
 man2/fanotify_init.2 | 35 +++++++++++++++++++++++++++++++++--
 man7/fanotify.7      | 30 ++++++++++++++++++++++++++----
 2 files changed, 59 insertions(+), 6 deletions(-)
man2/fanotify_init.2 +33 -2
index 54646e3c6..6167a1c37 100644
@@ -1,4 +1,4 @@
-.\" Copyright (C) 2013, Heinrich Schuchardt <[email protected]>
+\" Copyright (C) 2013, Heinrich Schuchardt <[email protected]>
 .\"
 .\" %%%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
man7/fanotify.7 +26 -4
index 734fa7b7c..fa1c85159 100644
@@ -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
Signature · 1 line
2.17.1
#3 lore raw

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

In reply to 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.

---
 man2/fanotify_init.2 | 54 +++++++++++++++++++++++++++++
 man7/fanotify.7      | 81 ++++++++++++++++++++++++++++++++++----------
 2 files changed, 118 insertions(+), 17 deletions(-)
man2/fanotify_init.2 +54 -0
index 6167a1c37..27dbfe498 100644
@@ -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
man7/fanotify.7 +64 -17

161 lines not on this page · raw message

Signature · 1 line
2.17.1
#4 lore raw
In reply to Amir Goldstein

Hi Amir,

Quoted 5 lines · 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.

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

Quoted 6 lines

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

Quoted 8 lines
 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/

#5 lore raw
In reply to Amir Goldstein

Hello Amir,

Quoted 4 lines · 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.

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

Quoted 11 lines

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(-)
Signature · 3 lines
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/