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@xxxxxxxxx> I've made one minor suggestion below. Other than that, this patch looks healthy to me. Reviewed-by: Matthew Bobrowski <mbobrowski@xxxxxxxxxxxxxx> > --- > 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@xxxxxx> > +\" Copyright (C) 2013, Heinrich Schuchardt <xypron.glpk@xxxxxx> > .\" > .\" %%%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
