From: Amir Goldstein Date: Tue, 25 Aug 2020 11:40:55 +0000 (+0300) Subject: fanotify.7, fanotify_init.2: Document FAN_REPORT_DIR_FID X-Git-Tag: man-pages-5.09~485 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=e9f14fa0bbc13a86912bc558d7876eeff406bb58;p=thirdparty%2Fman-pages.git fanotify.7, fanotify_init.2: Document FAN_REPORT_DIR_FID Document fanotify_init(2) flag FAN_REPORT_DIR_FID and event info type FAN_EVENT_INFO_TYPE_DFID. Signed-off-by: Amir Goldstein Reviewed-by: Jan Kara Reviewed-by: Matthew Bobrowski Signed-off-by: Michael Kerrisk --- diff --git a/man2/fanotify_init.2 b/man2/fanotify_init.2 index 54646e3c68..6167a1c377 100644 --- a/man2/fanotify_init.2 +++ b/man2/fanotify_init.2 @@ -1,4 +1,4 @@ -.\" Copyright (C) 2013, Heinrich Schuchardt +\" Copyright (C) 2013, Heinrich Schuchardt .\" .\" %%%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 734fa7b7c0..fa1c85159d 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