diff options
| author | Amir Goldstein <amir73il@gmail.com> | 2022-06-30 22:06:09 +0300 |
|---|---|---|
| committer | Alejandro Colomar <alx.manpages@gmail.com> | 2022-07-04 11:51:48 +0200 |
| commit | f5e3b67eeb1e5e9d1a4247ae6785dae1dc3c911c (patch) | |
| tree | 0ba38213af22bc9066bb6e8db7b23f67b3996575 | |
| parent | 7580780ebc1edf97760f66a857c17fdd9fff3e9c (diff) | |
| download | man-pages-f5e3b67eeb1e5e9d1a4247ae6785dae1dc3c911c.tar.gz | |
fanotify.7, fanotify_init.2: Document FAN_REPORT_TARGET_FID
FAN_REPORT_TARGET_FID adds an information record about the child
to directory entry modification events (create/delete/move).
This flag also adds sanity checks that directory modification events
(create,delete,moved) cannot be set in mask of a non-dir inode mark.
Note that while FAN_REPORT_TARGET_FID was merged to v5.17, the sanity
checks resulting in ENOTDIR were merged as fix commits ceaf69f8eadc
("fanotify: do not allow setting dirent events in mask of non-dir")
and 8698e3bab4dd ("fanotify: refine the validation checks on non-dir
inode mask") in later kernel releases.
Reviewed-by: Matthew Bobrowski <repnop@google.com>
Reviewed-by: Jan Kara <jack@suse.cz>
Signed-off-by: Amir Goldstein <amir73il@gmail.com>
[alx: ffix]
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
| -rw-r--r-- | man2/fanotify_init.2 | 40 | ||||
| -rw-r--r-- | man2/fanotify_mark.2 | 18 | ||||
| -rw-r--r-- | man7/fanotify.7 | 27 |
3 files changed, 68 insertions, 17 deletions
diff --git a/man2/fanotify_init.2 b/man2/fanotify_init.2 index 9abec5fca7..ac4d3a305f 100644 --- a/man2/fanotify_init.2 +++ b/man2/fanotify_init.2 @@ -182,9 +182,11 @@ and .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. +Note that without the flag +.BR FAN_REPORT_TARGET_FID , +for the directory entry modification events, +there is an inforamtion record that identifies the modified directory +and not the created/deleted/moved child object. The use of .B FAN_CLASS_CONTENT or @@ -282,6 +284,38 @@ for additional details. .B FAN_REPORT_DFID_NAME This is a synonym for .RB ( FAN_REPORT_DIR_FID | FAN_REPORT_NAME ). +.TP +.BR FAN_REPORT_TARGET_FID " (since Linux 5.17)" +.\" commit d61fd650e9d206a71fda789f02a1ced4b19944c4 +Events for fanotify groups initialized with this flag +will contain additional information about the child +correlated with directory entry modification events. +This flag must be provided in conjunction with the flags +.BR FAN_REPORT_FID , +.B FAN_REPORT_DIR_FID +and +.BR FAN_REPORT_NAME . +or else the error +.B EINVAL +will be returned. +For the directory entry modification events +.BR FAN_CREATE , +.BR FAN_DELETE , +and +.BR FAN_MOVE , +an additional record of type +.BR FAN_EVENT_INFO_TYPE_FID , +is reported in addition to the information record of type +.B FAN_EVENT_INFO_TYPE_DFID +or +.BR FAN_EVENT_INFO_TYPE_DFID_NAME . +The additional record includes a file handle +that identifies the filesystem child object +that the directory entry is referring to. +.TP +.B FAN_REPORT_DFID_NAME_TARGET +This is a synonym for +.RB ( FAN_REPORT_DFID_NAME | FAN_REPORT_FID | FAN_REPORT_TARGET_FID ). .PP .TP .BR FAN_REPORT_PIDFD " (since Linux 5.15)" diff --git a/man2/fanotify_mark.2 b/man2/fanotify_mark.2 index 3dc538b7f8..f73fe255c3 100644 --- a/man2/fanotify_mark.2 +++ b/man2/fanotify_mark.2 @@ -473,6 +473,24 @@ and .I pathname do not specify a directory. .TP +.B ENOTDIR +The fanotify group was initialized with flag +.BR FAN_REPORT_TARGET_FID , +.I mask +contains directory entry modification events +(e.g., +.BR FAN_CREATE , +.BR FAN_DELETE ), +or directory event flags +(e.g., +.BR FAN_ONDIR , +.BR FAN_EVENT_ON_CHILD ), +and +.I dirfd +and +.I pathname +do not specify a directory. +.TP .B EOPNOTSUPP The object indicated by .I pathname diff --git a/man7/fanotify.7 b/man7/fanotify.7 index f4d391603c..2a8b08a233 100644 --- a/man7/fanotify.7 +++ b/man7/fanotify.7 @@ -171,14 +171,14 @@ alongside the generic structure. For example, if a notification group is initialized with -.B FAN_REPORT_FID +.B FAN_REPORT_TARGET_FID and .BR FAN_REPORT_PIDFD , -then an event listener should also expect to receive both +then an event listener should expect to receive up to two .I fanotify_event_info_fid -and +information records and one .I fanotify_event_info_pidfd -structures alongside the generic +information record alongside the generic .I fanotify_event_metadata structure. Importantly, @@ -552,7 +552,15 @@ 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. +identifying a child object. +Note that for the directory entry modification events +.BR FAN_CREATE , +.BR FAN_DELETE , +and +.BR FAN_MOVE , +an information record identifying the created/deleted/moved child object +is reported only if an fanotify group was initialized with the flag +.BR FAN_REPORT_TARGET_FID . .TP .I fsid This is a unique identifier of the filesystem containing the object @@ -572,15 +580,6 @@ filesystem as returned by It can be used to uniquely identify a file on a filesystem and can be passed as an argument to .BR open_by_handle_at (2). -Note that for the directory entry modification events -.BR FAN_CREATE , -.BR FAN_DELETE , -and -.BR FAN_MOVE , -the -.I file_handle -identifies the modified directory and not the created/deleted/moved child -object. If the value of .I info_type field is |