Re: [PATCH 2/2] fanotify.7, fanotify_init.2, fanotify_mark.2: Document FAN_RENAME

[Alejandro Colomar <alx.manpages@gmail.com>]

[-- Attachment #1.1: Type: text/plain, Size: 5000 bytes --]

On 6/17/22 15:11, 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>

Please, also check some minor comments below for this patch.

Cheers,

Alex

> ---
>   man2/fanotify_init.2 | 21 +++++++++++++++++----
>   man2/fanotify_mark.2 | 16 ++++++++++++++++
>   man7/fanotify.7      |  4 ++++
>   3 files changed, 37 insertions(+), 4 deletions(-)
> 
> diff --git a/man2/fanotify_init.2 b/man2/fanotify_init.2
> index ac4d3a305..bf87f394b 100644
> --- a/man2/fanotify_init.2
> +++ b/man2/fanotify_init.2
> @@ -173,6 +173,7 @@ 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 ,
> +.BR FAN_RENAME ,
>   and
>   .BR FAN_MOVE ,

See below.

>   or in events such as
> @@ -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

Why does RENAME appear sometimes after and sometimes before MOVE?

> +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 ,
> +.BR FAN_RENAME ,
>   and
>   .BR FAN_MOVE ,

See above.  There are more cases below.  Please check all of them, and 
try to be consistent, if no other more important reason applies.

>   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 ebb327bdd..eb82325b6 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 when trying to set directory entry modification
> diff --git a/man7/fanotify.7 b/man7/fanotify.7
> index 5f2c01408..e08508337 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,6 +559,7 @@ identifying a child object.
>   Note that for the directory entry modification events
>   .BR FAN_CREATE ,
>   .BR FAN_DELETE ,
> +.BR FAN_RENAME ,
>   and
>   .BR FAN_MOVE ,
>   an information record identifying the created/deleted/moved child object

-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]