fanotify.7, fanotify_init.2, fanotify_mark.2: Document FAN_REPORT_FID and directory modification events
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
@@ -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
Quoted 9 lines · Matthew Bobrowski
Details relating to the new initialization flag
FAN_REPORT_FIDhas been added. As part of theFAN_REPORT_FIDfeature, 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.Signed-off-by Matthew Bobrowski <[email protected]>Reviewed-by Amir Goldstein <[email protected]>
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
Quoted 8 lines · Jan Kara
Quoted 7 lines · Matthew Bobrowski
Details relating to the new initialization flag
FAN_REPORT_FIDhas been added. As part of theFAN_REPORT_FIDfeature, 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
Signed-off-by Matthew Bobrowski <[email protected]>Reviewed-by Amir Goldstein <[email protected]>Looks good to me, you can add:
Reviewed-by Jan Kara <[email protected]>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