Skip to contentSkip to conversation

fanotify.7, fanotify_init.2, fanotify_mark.2: Document FAN_REPORT_FID and directory modification events

PATCH In review Matthew Bobrowski 2 participants 3 messages Mar 25, 2019 – Mar 30, 2019 VFS

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 fanotify.7, fanotify_init.2, fanotify_mark.2: Document FAN_REPORT_FID and directory modification events

Details relating to the new initialization flag FAN_REPORT_FID has been added. As part of the FAN_REPORT_FID feature, a new set of event masks are available and have been documented accordingly.

A simple example program has been added to also support the understanding and use case of FAN_REPORT_FID.

---

This patch contains the supporting documentation for the newly introduced FAN_REPORT_FID flag and directory entry modification events. These changes have been merged with master and are available as of Linux 5.1.

 man2/fanotify_init.2 |  30 +++++
 man2/fanotify_mark.2 |  94 ++++++++++++++-
 man7/fanotify.7      | 331 +++++++++++++++++++++++++++++++++++++++++++++++++--
 3 files changed, 442 insertions(+), 13 deletions(-)
man2/fanotify_init.2 +30 -0
index 9be15be51..c808c2bd7 100644
@@ -94,6 +94,34 @@ already contain their final content.
 This notification class might be used by malware detection programs, for
 example.
 .TP
+.BR FAN_REPORT_FID " (since Linux 5.1)"
+.\" commit a8b13aa20afb69161b5123b4f1acc7ea0a03d360
+This value allows the receipt of events which contain additional information
+about the underlying object correlated to an event.
+An additional structure 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
+.BR FAN_CREATE ,
+.BR FAN_ATTRIB ,
+.BR FAN_MOVE
+and
+.BR FAN_DELETE
+for example.
+The use of
+.BR FAN_CLASS_CONTENT
+or
+.BR FAN_CLASS_PRE_CONTENT
+is not permitted with this flag and will result in the error
+.BR EINVAL .
+See
+.BR fanotify (7)
+for additional information.
+.TP
 .B FAN_CLASS_NOTIF
 This is the default value.
 It does not need to be specified.
@@ -224,6 +252,8 @@ An invalid value was passed in
 or
 .IR event_f_flags .
 .B FAN_ALL_INIT_FLAGS
+(deprecated since Linux kernel version 4.20)
+.\" commit 23c9deeb3285d34fd243abb3d6b9f07db60c3cf4
 defines all allowable bits for
 .IR flags .
 .TP
man2/fanotify_mark.2 +92 -2

140 lines not on this page · raw message

man7/fanotify.7 +320 -11

407 lines not on this page · raw message

Signature · 5 lines
2.16.4


-- 
Matthew Bobrowski
reviewer Reviewed-by on v1 1/1
#1 lore raw
Quoted 9 lines · Matthew Bobrowski

Details relating to the new initialization flag FAN_REPORT_FID has been added. As part of the FAN_REPORT_FID feature, a new set of event masks are available and have been documented accordingly.

A simple example program has been added to also support the understanding and use case of FAN_REPORT_FID.

Looks good to me, you can add:

Two nits below:

man7/fanotify.7 This is a synonym for: · line 399

Quoted 12 lines

+.I hdr

man7/fanotify.7 +11 -0
+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.
+For example, when an fanotify file descriptor is created using
+.B FAN_REPORT_FID
+the
+.I info_type
+field of this header is set to
+.BR FAN_EVENT_INFO_TYPE_FID .
+Event listeners can use this field to check that events of the correct

^^^ additional
information of the correct type?

...

man7/fanotify.7 main(int argc, char *argv[]) · line 1043

Quoted 10 lines
man7/fanotify.7 +10 -0
+    /* Process all events within the buffer */
+    for (metadata = (struct fanotify_event_metadata *) events_buf;
+            FAN_EVENT_OK(metadata, len);
+            metadata = FAN_EVENT_NEXT(metadata, len)) {
+        fid = (struct fanotify_event_info_fid *) (metadata + 1);
+        file_handle = (struct file_handle *) fid->handle;
+
+        /* Ensure that the event info is of the correct type */
+        if (fid->hdr.info_type != FAN_EVENT_INFO_TYPE_FID) {
+            fprintf(stderr, "Received unexpected event type.\\n");

^^^ event info type?

Honza

Signature · 2 lines
Jan Kara <[email protected]>
SUSE Labs, CR
#2 lore raw
Quoted 8 lines · Jan Kara
Quoted 7 lines · Matthew Bobrowski

Details relating to the new initialization flag FAN_REPORT_FID has been added. As part of the FAN_REPORT_FID feature, a new set of event masks are available and have been documented accordingly.

A simple example program has been added to also support the understanding and use case of FAN_REPORT_FID.

Quoted 8 lines
Quoted 2 lines

Looks good to me, you can add:

Two nits below:

Thanks for the review Jan! Both nits have been addressed so I'll be sending through version 2 of this patch through at some point today.

Quoted 15 lines

man7/fanotify.7 This is a synonym for: · line 399

Quoted 12 lines

+.I hdr

man7/fanotify.7 +11 -0
+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.
+For example, when an fanotify file descriptor is created using
+.B FAN_REPORT_FID
+the
+.I info_type
+field of this header is set to
+.BR FAN_EVENT_INFO_TYPE_FID .
+Event listeners can use this field to check that events of the correct

^^^ additional
information of the correct type?

Quoted 1 line

...

I've changed it to the following which I believe is more accurate and is aligned with your recommendation.

--
Event listeners can use this field to check that the additional information received for an event is of the correct type. --

Signature · 1 line
Matthew Bobrowski