* [PATCH v2 0/2] fanotify man page updates for v5.17 @ 2022-06-22 16:41 Amir Goldstein 2022-06-22 16:41 ` [PATCH v2 1/2] fanotify.7, fanotify_init.2: Document FAN_REPORT_TARGET_FID Amir Goldstein 2022-06-22 16:41 ` [PATCH v2 2/2] fanotify.7, fanotify_init.2, fanotify_mark.2: Document FAN_RENAME Amir Goldstein 0 siblings, 2 replies; 7+ messages in thread From: Amir Goldstein @ 2022-06-22 16:41 UTC (permalink / raw) To: Alejandro Colomar; +Cc: Michael Kerrisk, Jan Kara, Matthew Bobrowski, linux-man Hi Alex, These two complementary APIs, FAN_REPORT_TARGET_FID (fanotify_init) and FAN_RENAME (fanotify_mark) were merged to kernel v5.17. v2 addresses the few comments you had on v1. Thanks, Amir Changes since v1: - Rebased on master - Mention the fix commit of ENOTDIR change in commit message - Break long line - Consistent order of FAN_MOVE,FAN_RENAME in man pages Amir Goldstein (2): fanotify.7, fanotify_init.2: Document FAN_REPORT_TARGET_FID fanotify.7, fanotify_init.2, fanotify_mark.2: Document FAN_RENAME man2/fanotify_init.2 | 55 ++++++++++++++++++++++++++++++++++++++++---- man2/fanotify_mark.2 | 24 +++++++++++++++++++ man7/fanotify.7 | 31 ++++++++++++++----------- 3 files changed, 92 insertions(+), 18 deletions(-) -- 2.25.1 ^ permalink raw reply [flat|nested] 7+ messages in thread
* [PATCH v2 1/2] fanotify.7, fanotify_init.2: Document FAN_REPORT_TARGET_FID 2022-06-22 16:41 [PATCH v2 0/2] fanotify man page updates for v5.17 Amir Goldstein @ 2022-06-22 16:41 ` Amir Goldstein 2022-06-23 9:33 ` Jan Kara 2022-06-26 15:31 ` Amir Goldstein 2022-06-22 16:41 ` [PATCH v2 2/2] fanotify.7, fanotify_init.2, fanotify_mark.2: Document FAN_RENAME Amir Goldstein 1 sibling, 2 replies; 7+ messages in thread From: Amir Goldstein @ 2022-06-22 16:41 UTC (permalink / raw) To: Alejandro Colomar; +Cc: Michael Kerrisk, Jan Kara, Matthew Bobrowski, linux-man 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 commit ceaf69f8eadc ("fanotify: do not allow setting dirent events in mask of non-dir") to v5.18 and backported to v5.17.9. Reviewed-by: Matthew Bobrowski <repnop@google.com> Signed-off-by: Amir Goldstein <amir73il@gmail.com> --- man2/fanotify_init.2 | 40 +++++++++++++++++++++++++++++++++++++--- man2/fanotify_mark.2 | 8 ++++++++ man7/fanotify.7 | 27 +++++++++++++-------------- 3 files changed, 58 insertions(+), 17 deletions(-) diff --git a/man2/fanotify_init.2 b/man2/fanotify_init.2 index 9abec5fca..ac4d3a305 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 3dc538b7f..eeaddd173 100644 --- a/man2/fanotify_mark.2 +++ b/man2/fanotify_mark.2 @@ -472,6 +472,14 @@ and and .I pathname do not specify a directory. +For an fanotify group that was initialized with flag +.BR FAN_REPORT_TARGET_FID , +this error will also be returned +when trying to set directory entry modification events +(e.g., +.BR FAN_CREATE , +.BR FAN_DELETE ) +in the mask of a non directory inode mark. .TP .B EOPNOTSUPP The object indicated by diff --git a/man7/fanotify.7 b/man7/fanotify.7 index f4d391603..5f2c01408 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 -- 2.25.1 ^ permalink raw reply related [flat|nested] 7+ messages in thread
* Re: [PATCH v2 1/2] fanotify.7, fanotify_init.2: Document FAN_REPORT_TARGET_FID 2022-06-22 16:41 ` [PATCH v2 1/2] fanotify.7, fanotify_init.2: Document FAN_REPORT_TARGET_FID Amir Goldstein @ 2022-06-23 9:33 ` Jan Kara 2022-06-26 15:31 ` Amir Goldstein 1 sibling, 0 replies; 7+ messages in thread From: Jan Kara @ 2022-06-23 9:33 UTC (permalink / raw) To: Amir Goldstein Cc: Alejandro Colomar, Michael Kerrisk, Jan Kara, Matthew Bobrowski, linux-man On Wed 22-06-22 19:41:52, Amir Goldstein wrote: > 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 commit ceaf69f8eadc > ("fanotify: do not allow setting dirent events in mask of non-dir") > to v5.18 and backported to v5.17.9. > > Reviewed-by: Matthew Bobrowski <repnop@google.com> > Signed-off-by: Amir Goldstein <amir73il@gmail.com> Looks good. Feel free to add: Reviewed-by: Jan Kara <jack@suse.cz> Honza > --- > man2/fanotify_init.2 | 40 +++++++++++++++++++++++++++++++++++++--- > man2/fanotify_mark.2 | 8 ++++++++ > man7/fanotify.7 | 27 +++++++++++++-------------- > 3 files changed, 58 insertions(+), 17 deletions(-) > > diff --git a/man2/fanotify_init.2 b/man2/fanotify_init.2 > index 9abec5fca..ac4d3a305 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 3dc538b7f..eeaddd173 100644 > --- a/man2/fanotify_mark.2 > +++ b/man2/fanotify_mark.2 > @@ -472,6 +472,14 @@ and > and > .I pathname > do not specify a directory. > +For an fanotify group that was initialized with flag > +.BR FAN_REPORT_TARGET_FID , > +this error will also be returned > +when trying to set directory entry modification events > +(e.g., > +.BR FAN_CREATE , > +.BR FAN_DELETE ) > +in the mask of a non directory inode mark. > .TP > .B EOPNOTSUPP > The object indicated by > diff --git a/man7/fanotify.7 b/man7/fanotify.7 > index f4d391603..5f2c01408 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 > -- > 2.25.1 > -- Jan Kara <jack@suse.com> SUSE Labs, CR ^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [PATCH v2 1/2] fanotify.7, fanotify_init.2: Document FAN_REPORT_TARGET_FID 2022-06-22 16:41 ` [PATCH v2 1/2] fanotify.7, fanotify_init.2: Document FAN_REPORT_TARGET_FID Amir Goldstein 2022-06-23 9:33 ` Jan Kara @ 2022-06-26 15:31 ` Amir Goldstein 2022-07-03 18:38 ` Alejandro Colomar 1 sibling, 1 reply; 7+ messages in thread From: Amir Goldstein @ 2022-06-26 15:31 UTC (permalink / raw) To: Alejandro Colomar; +Cc: Michael Kerrisk, Jan Kara, Matthew Bobrowski, linux-man On Wed, Jun 22, 2022 at 7:41 PM Amir Goldstein <amir73il@gmail.com> wrote: > > 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 commit ceaf69f8eadc > ("fanotify: do not allow setting dirent events in mask of non-dir") > to v5.18 and backported to v5.17.9. > > Reviewed-by: Matthew Bobrowski <repnop@google.com> > Signed-off-by: Amir Goldstein <amir73il@gmail.com> > --- > man2/fanotify_init.2 | 40 +++++++++++++++++++++++++++++++++++++--- > man2/fanotify_mark.2 | 8 ++++++++ > man7/fanotify.7 | 27 +++++++++++++-------------- > 3 files changed, 58 insertions(+), 17 deletions(-) > > diff --git a/man2/fanotify_init.2 b/man2/fanotify_init.2 > index 9abec5fca..ac4d3a305 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 3dc538b7f..eeaddd173 100644 > --- a/man2/fanotify_mark.2 > +++ b/man2/fanotify_mark.2 > @@ -472,6 +472,14 @@ and > and > .I pathname > do not specify a directory. > +For an fanotify group that was initialized with flag > +.BR FAN_REPORT_TARGET_FID , > +this error will also be returned > +when trying to set directory entry modification events > +(e.g., > +.BR FAN_CREATE , > +.BR FAN_DELETE ) > +in the mask of a non directory inode mark. Alex, I hope the reviewers won't mind, but because we are adding more reasons of ENOTDIR later on, I think this section would look better with every ENOTDIR reason in a paragraph of its own, like this: .TP .B ENOTDIR .I flags contains .BR FAN_MARK_ONLYDIR , and .I dirfd 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 ) , and .I dirfd and .I pathname do not specify a directory. .TP The end result [1] after the following FAN_RENAME patch looks like this: ENOTDIR flags contains FAN_MARK_ONLYDIR, and dirfd and pathname do not specify a directory. ENOTDIR mask contains FAN_RENAME, and dirfd and pathname do not specify a directory. ENOTDIR The fanotify group was initialized with flag FAN_REPORT_TARGET_FID, mask contains directory entry modification events (e.g., FAN_CREATE, FAN_DELETE), and dirfd and pathname do not specify a directory. BTW, I could not figure out what causes the line break after ENOTDIR. Other errors look similarly formatted and don't have this line break. Thanks, Amir. [1] https://github.com/amir73il/man-pages/commits/fan_rename ^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [PATCH v2 1/2] fanotify.7, fanotify_init.2: Document FAN_REPORT_TARGET_FID 2022-06-26 15:31 ` Amir Goldstein @ 2022-07-03 18:38 ` Alejandro Colomar 0 siblings, 0 replies; 7+ messages in thread From: Alejandro Colomar @ 2022-07-03 18:38 UTC (permalink / raw) To: Amir Goldstein; +Cc: Jan Kara, Matthew Bobrowski, linux-man [-- Attachment #1.1: Type: text/plain, Size: 3416 bytes --] Hi Amir! On 6/26/22 17:31, Amir Goldstein wrote: > > Alex, > > I hope the reviewers won't mind, but because we are adding more > reasons of ENOTDIR > later on, I think this section would look better with every ENOTDIR > reason in a paragraph > of its own, like this: That makes sense. Other pages also do that already, so it's fine for me. I must say that it was a bit weird to me a long time ago, when I started reading manual pages, and I've also received a report recently from someone who thought the same, but now it reads normal to me, so I'll assume it's just part of the learning curve of learning to read man pages. Probably having a lot of text together in a single entry would be even worse from the readability point of view, so go ahead. For the review, as long as you don't change existing code, you can do it all in one commit. If you're refactoring text at the same time as adding new text, I'd prefer if you break the commit into 2, the first one being the refactor, to make it easy to review (same as kernel rules, I guess). > > .TP > .B ENOTDIR > .I flags > contains > .BR FAN_MARK_ONLYDIR , > and > .I dirfd > 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 ) , > and > .I dirfd > and > .I pathname > do not specify a directory. > .TP > > The end result [1] after the following FAN_RENAME patch looks like this: > > ENOTDIR > flags contains FAN_MARK_ONLYDIR, and dirfd and pathname > do not specify a directory. > > ENOTDIR > mask contains FAN_RENAME, and dirfd and pathname do not > specify a directory. > > ENOTDIR > The fanotify group was initialized with flag > FAN_REPORT_TARGET_FID, mask contains > directory entry modification events (e.g., FAN_CREATE, > FAN_DELETE), and dirfd and > pathname do not specify a directory. > > BTW, I could not figure out what causes the line break after ENOTDIR. > Other errors look similarly formatted and don't have this line break. That's normal. There must be at least a space between the tag and the paragraph in a tagged paragraph (.TP), so if there's not room for the space, it breaks, but it's normal. groff_man(7): .TP [indentation] Set a paragraph with a leading tag, and the re‐ mainder of the paragraph indented. The input line following this macro, known as the tag, is printed at the current left margin. Subsequent text is indented by indentation, if specified, and by a default amount otherwise; see subsection “Horizon‐ tal and vertical spacing” below. If the tag is not as wide as the indentation, the paragraph starts on the same line as the tag, at the applicable indentation, and continues on the following lines. Otherwise, the descriptive part of the paragraph begins on the line following the tag. Thanks, Alex -- Alejandro Colomar <http://www.alejandro-colomar.es/> [-- Attachment #2: OpenPGP digital signature --] [-- Type: application/pgp-signature, Size: 833 bytes --] ^ permalink raw reply [flat|nested] 7+ messages in thread
* [PATCH v2 2/2] fanotify.7, fanotify_init.2, fanotify_mark.2: Document FAN_RENAME 2022-06-22 16:41 [PATCH v2 0/2] fanotify man page updates for v5.17 Amir Goldstein 2022-06-22 16:41 ` [PATCH v2 1/2] fanotify.7, fanotify_init.2: Document FAN_REPORT_TARGET_FID Amir Goldstein @ 2022-06-22 16:41 ` Amir Goldstein 2022-06-23 9:35 ` Jan Kara 1 sibling, 1 reply; 7+ messages in thread From: Amir Goldstein @ 2022-06-22 16:41 UTC (permalink / raw) To: Alejandro Colomar; +Cc: Michael Kerrisk, Jan Kara, Matthew Bobrowski, linux-man FAN_RENAME is a new event type that includes information about both old and new directory entries. It is a successor of the two separate FAN_MOVED_TO/FROM events, but those event types are still supported. Reviewed-by: Matthew Bobrowski <repnop@google.com> Signed-off-by: Amir Goldstein <amir73il@gmail.com> --- man2/fanotify_init.2 | 25 +++++++++++++++++++------ man2/fanotify_mark.2 | 16 ++++++++++++++++ man7/fanotify.7 | 6 +++++- 3 files changed, 40 insertions(+), 7 deletions(-) diff --git a/man2/fanotify_init.2 b/man2/fanotify_init.2 index ac4d3a305..810f3fc73 100644 --- a/man2/fanotify_init.2 +++ b/man2/fanotify_init.2 @@ -173,8 +173,9 @@ Additionally, it may be used for applications monitoring a directory or a filesystem that are interested in the directory entry modification events .BR FAN_CREATE , .BR FAN_DELETE , -and .BR FAN_MOVE , +and +.BR FAN_RENAME , or in events such as .BR FAN_ATTRIB , .BR FAN_DELETE_SELF , @@ -257,6 +258,15 @@ For the directory entry modification events and .BR FAN_MOVE , the reported name is that of the created/deleted/moved directory entry. +The event +.B FAN_RENAME +may contain two information records. +One of type +.B FAN_EVENT_INFO_TYPE_OLD_DFID_NAME +identifying the old directory entry, +and another of type +.B FAN_EVENT_INFO_TYPE_NEW_DFID_NAME +identifying the new directory entry. For other events that occur on a directory object, the reported file handle is that of the directory object itself and the reported name is '.'. For other events that occur on a non-directory object, the reported file handle @@ -301,14 +311,17 @@ will be returned. For the directory entry modification events .BR FAN_CREATE , .BR FAN_DELETE , -and .BR FAN_MOVE , +and +.BR FAN_RENAME , 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 . +is reported in addition to the information records of type +.BR FAN_EVENT_INFO_TYPE_DFID , +.BR FAN_EVENT_INFO_TYPE_DFID_NAME , +.BR FAN_EVENT_INFO_TYPE_OLD_DFID_NAME , +and +.BR FAN_EVENT_INFO_TYPE_NEW_DFID_NAME . The additional record includes a file handle that identifies the filesystem child object that the directory entry is referring to. diff --git a/man2/fanotify_mark.2 b/man2/fanotify_mark.2 index eeaddd173..66c704c19 100644 --- a/man2/fanotify_mark.2 +++ b/man2/fanotify_mark.2 @@ -240,6 +240,19 @@ directory. An fanotify group that identifies filesystem objects by file handles is required. .TP +.BR FAN_RENAME " (since Linux 5.17)" +.\" commit 8cc3b1ccd930fe6971e1527f0c4f1bdc8cb56026 +This event contains the same information provided by events +.B FAN_MOVED_FROM +and +.BR FAN_MOVED_TO , +however is represented by a single event with up to two information records. +An fanotify group that identifies filesystem objects by file handles +is required. +If the filesystem object to be marked is not a directory, the error +.B ENOTDIR +shall be raised. +.TP .BR FAN_MOVE_SELF " (since Linux 5.1)" .\" commit 235328d1fa4251c6dcb32351219bb553a58838d2 Create an event when a marked file or directory itself has been moved. @@ -472,6 +485,9 @@ and and .I pathname do not specify a directory. +This error will also be returned when trying to set the event +.B FAN_RENAME +in the mask of a non directory inode mark. For an fanotify group that was initialized with flag .BR FAN_REPORT_TARGET_FID , this error will also be returned diff --git a/man7/fanotify.7 b/man7/fanotify.7 index 5f2c01408..47e104b1b 100644 --- a/man7/fanotify.7 +++ b/man7/fanotify.7 @@ -391,6 +391,9 @@ A watched file or directory was deleted. .B FAN_FS_ERROR A filesystem error was detected. .TP +.B FAN_RENAME +A file or directory has been moved to or from a watched parent directory. +.TP .B FAN_MOVED_FROM A file or directory has been moved from a watched parent directory. .TP @@ -556,8 +559,9 @@ identifying a child object. Note that for the directory entry modification events .BR FAN_CREATE , .BR FAN_DELETE , -and .BR FAN_MOVE , +and +.BR FAN_RENAME , 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. -- 2.25.1 ^ permalink raw reply related [flat|nested] 7+ messages in thread
* Re: [PATCH v2 2/2] fanotify.7, fanotify_init.2, fanotify_mark.2: Document FAN_RENAME 2022-06-22 16:41 ` [PATCH v2 2/2] fanotify.7, fanotify_init.2, fanotify_mark.2: Document FAN_RENAME Amir Goldstein @ 2022-06-23 9:35 ` Jan Kara 0 siblings, 0 replies; 7+ messages in thread From: Jan Kara @ 2022-06-23 9:35 UTC (permalink / raw) To: Amir Goldstein Cc: Alejandro Colomar, Michael Kerrisk, Jan Kara, Matthew Bobrowski, linux-man On Wed 22-06-22 19:41:53, Amir Goldstein wrote: > FAN_RENAME is a new event type that includes information about > both old and new directory entries. > > It is a successor of the two separate FAN_MOVED_TO/FROM events, > but those event types are still supported. > > Reviewed-by: Matthew Bobrowski <repnop@google.com> > Signed-off-by: Amir Goldstein <amir73il@gmail.com> Looks good. Feel free to add: Reviewed-by: Jan Kara <jack@suse.cz> Honza > --- > man2/fanotify_init.2 | 25 +++++++++++++++++++------ > man2/fanotify_mark.2 | 16 ++++++++++++++++ > man7/fanotify.7 | 6 +++++- > 3 files changed, 40 insertions(+), 7 deletions(-) > > diff --git a/man2/fanotify_init.2 b/man2/fanotify_init.2 > index ac4d3a305..810f3fc73 100644 > --- a/man2/fanotify_init.2 > +++ b/man2/fanotify_init.2 > @@ -173,8 +173,9 @@ Additionally, it may be used for applications monitoring a directory or a > filesystem that are interested in the directory entry modification events > .BR FAN_CREATE , > .BR FAN_DELETE , > -and > .BR FAN_MOVE , > +and > +.BR FAN_RENAME , > or in events such as > .BR FAN_ATTRIB , > .BR FAN_DELETE_SELF , > @@ -257,6 +258,15 @@ For the directory entry modification events > and > .BR FAN_MOVE , > the reported name is that of the created/deleted/moved directory entry. > +The event > +.B FAN_RENAME > +may contain two information records. > +One of type > +.B FAN_EVENT_INFO_TYPE_OLD_DFID_NAME > +identifying the old directory entry, > +and another of type > +.B FAN_EVENT_INFO_TYPE_NEW_DFID_NAME > +identifying the new directory entry. > For other events that occur on a directory object, the reported file handle > is that of the directory object itself and the reported name is '.'. > For other events that occur on a non-directory object, the reported file handle > @@ -301,14 +311,17 @@ will be returned. > For the directory entry modification events > .BR FAN_CREATE , > .BR FAN_DELETE , > -and > .BR FAN_MOVE , > +and > +.BR FAN_RENAME , > 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 . > +is reported in addition to the information records of type > +.BR FAN_EVENT_INFO_TYPE_DFID , > +.BR FAN_EVENT_INFO_TYPE_DFID_NAME , > +.BR FAN_EVENT_INFO_TYPE_OLD_DFID_NAME , > +and > +.BR FAN_EVENT_INFO_TYPE_NEW_DFID_NAME . > The additional record includes a file handle > that identifies the filesystem child object > that the directory entry is referring to. > diff --git a/man2/fanotify_mark.2 b/man2/fanotify_mark.2 > index eeaddd173..66c704c19 100644 > --- a/man2/fanotify_mark.2 > +++ b/man2/fanotify_mark.2 > @@ -240,6 +240,19 @@ directory. > An fanotify group that identifies filesystem objects by file handles > is required. > .TP > +.BR FAN_RENAME " (since Linux 5.17)" > +.\" commit 8cc3b1ccd930fe6971e1527f0c4f1bdc8cb56026 > +This event contains the same information provided by events > +.B FAN_MOVED_FROM > +and > +.BR FAN_MOVED_TO , > +however is represented by a single event with up to two information records. > +An fanotify group that identifies filesystem objects by file handles > +is required. > +If the filesystem object to be marked is not a directory, the error > +.B ENOTDIR > +shall be raised. > +.TP > .BR FAN_MOVE_SELF " (since Linux 5.1)" > .\" commit 235328d1fa4251c6dcb32351219bb553a58838d2 > Create an event when a marked file or directory itself has been moved. > @@ -472,6 +485,9 @@ and > and > .I pathname > do not specify a directory. > +This error will also be returned when trying to set the event > +.B FAN_RENAME > +in the mask of a non directory inode mark. > For an fanotify group that was initialized with flag > .BR FAN_REPORT_TARGET_FID , > this error will also be returned > diff --git a/man7/fanotify.7 b/man7/fanotify.7 > index 5f2c01408..47e104b1b 100644 > --- a/man7/fanotify.7 > +++ b/man7/fanotify.7 > @@ -391,6 +391,9 @@ A watched file or directory was deleted. > .B FAN_FS_ERROR > A filesystem error was detected. > .TP > +.B FAN_RENAME > +A file or directory has been moved to or from a watched parent directory. > +.TP > .B FAN_MOVED_FROM > A file or directory has been moved from a watched parent directory. > .TP > @@ -556,8 +559,9 @@ identifying a child object. > Note that for the directory entry modification events > .BR FAN_CREATE , > .BR FAN_DELETE , > -and > .BR FAN_MOVE , > +and > +.BR FAN_RENAME , > 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. > -- > 2.25.1 > -- Jan Kara <jack@suse.com> SUSE Labs, CR ^ permalink raw reply [flat|nested] 7+ messages in thread
end of thread, other threads:[~2022-07-03 18:38 UTC | newest] Thread overview: 7+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2022-06-22 16:41 [PATCH v2 0/2] fanotify man page updates for v5.17 Amir Goldstein 2022-06-22 16:41 ` [PATCH v2 1/2] fanotify.7, fanotify_init.2: Document FAN_REPORT_TARGET_FID Amir Goldstein 2022-06-23 9:33 ` Jan Kara 2022-06-26 15:31 ` Amir Goldstein 2022-07-03 18:38 ` Alejandro Colomar 2022-06-22 16:41 ` [PATCH v2 2/2] fanotify.7, fanotify_init.2, fanotify_mark.2: Document FAN_RENAME Amir Goldstein 2022-06-23 9:35 ` Jan Kara
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox