[PATCH 0/2] fanotify man page updates for v5.17

[PATCH 0/2] fanotify man page updates for v5.17

[Amir Goldstein]

Hi Alex,

These two complementary APIs, FAN_REPORT_TARGET_FID (fanotify_init)
and FAN_RENAME (fanotify_mark) were merged to kernel v5.17.

Note that we used the fact that this is new API to fix a glitch that
exists in the old APIs - it is possble to request CREATE/DELETE/MOVE
events for a non-directrory, but those event can only be generated on
a directory.

When the new flags are used, ENOTDIR will be returned in such cases
and this change is reflected in the man pages updates.

However, we noticed this opportunity a bit late and the ENOTDIR change
was merged last minute to v5.18 and then backported to v5.17.9:
ceaf69f8eadc ("fanotify: do not allow setting dirent events in mask of
non-dir").

I did not mention this course of events in the man page, because it
seemed too much irrelevant information for end user, but am mentioning
it here for full disclosure in case somebody thinks this information is
relevant.

These patches apply on top of fan-fs-error branch in my tree [1]
which you have already reviewed, but have not yet applied.

[1] https://github.com/amir73il/man-pages/commits/fan-fs-error

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 | 53 +++++++++++++++++++++++++++++++++++++++++---
 man2/fanotify_mark.2 | 23 +++++++++++++++++++
 man7/fanotify.7      | 31 ++++++++++++++------------
 3 files changed, 90 insertions(+), 17 deletions(-)

-- 
2.25.1

[PATCH 1/2] fanotify.7, fanotify_init.2: Document FAN_REPORT_TARGET_FID

[Amir Goldstein]

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.

Reviewed-by: Matthew Bobrowski <repnop@google.com>
Signed-off-by: Amir Goldstein <amir73il@gmail.com>
---
 man2/fanotify_init.2 | 40 +++++++++++++++++++++++++++++++++++++---
 man2/fanotify_mark.2 |  7 +++++++
 man7/fanotify.7      | 27 +++++++++++++--------------
 3 files changed, 57 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..ebb327bdd 100644
--- a/man2/fanotify_mark.2
+++ b/man2/fanotify_mark.2
@@ -472,6 +472,13 @@ 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

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

[Amir Goldstein]

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 | 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 ,
 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
+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 ,
 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
-- 
2.25.1

Re: [PATCH 0/2] fanotify man page updates for v5.17

[Alejandro Colomar]

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

Hi Amir,

On 6/17/22 15:11, Amir Goldstein wrote:
[...]
> 
> I did not mention this course of events in the man page, because it
> seemed too much irrelevant information for end user, but am mentioning
> it here for full disclosure in case somebody thinks this information is
> relevant.

Hmm, maybe we should include it in the commit message?

I'll comment also on the patches, but mostly good stuff.

Cheers,

Alex

> 
> These patches apply on top of fan-fs-error branch in my tree [1]
> which you have already reviewed, but have not yet applied.
> 
> [1] https://github.com/amir73il/man-pages/commits/fan-fs-error
> 
> 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 | 53 +++++++++++++++++++++++++++++++++++++++++---
>   man2/fanotify_mark.2 | 23 +++++++++++++++++++
>   man7/fanotify.7      | 31 ++++++++++++++------------
>   3 files changed, 90 insertions(+), 17 deletions(-)
> 

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

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

Re: [PATCH 1/2] fanotify.7, fanotify_init.2: Document FAN_REPORT_TARGET_FID

[Alejandro Colomar]

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

On 6/17/22 15:11, 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.
> 
> Reviewed-by: Matthew Bobrowski <repnop@google.com>
> Signed-off-by: Amir Goldstein <amir73il@gmail.com>

Hi Amir,

Please see some comment below.

Thanks,

Alex

> ---
>   man2/fanotify_init.2 | 40 +++++++++++++++++++++++++++++++++++++---
>   man2/fanotify_mark.2 |  7 +++++++
>   man7/fanotify.7      | 27 +++++++++++++--------------
>   3 files changed, 57 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..ebb327bdd 100644
> --- a/man2/fanotify_mark.2
> +++ b/man2/fanotify_mark.2
> @@ -472,6 +472,13 @@ 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.,

man-pages(7):
    Use semantic newlines
        In the source of a manual page, new sentences  should  be
        started on new lines, long sentences should be split into
        lines  at  clause breaks (commas, semicolons, colons, and
        so on), and long clauses should be split at phrase bound‐
        aries.  This convention,  sometimes  known  as  "semantic
        newlines",  makes it easier to see the effect of patches,
        which often operate at the level of individual sentences,
        clauses, or phrases.


It only applies to the 2 lines above.  The rest of the patch looks good.

> +.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

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

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

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

[Alejandro Colomar]

[-- 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 --]

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

[Amir Goldstein]

On Fri, Jun 17, 2022 at 4:53 PM Alejandro Colomar
<alx.manpages@gmail.com> wrote:
>
> 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.
>

The only reason is to minimize changed lines.
Consistency is more important, so I'll fix this up.

Thanks,
Amir.

Re: [PATCH 0/2] fanotify man page updates for v5.17

[Amir Goldstein]

On Fri, Jun 17, 2022 at 4:49 PM Alejandro Colomar
<alx.manpages@gmail.com> wrote:
>
> Hi Amir,
>
> On 6/17/22 15:11, Amir Goldstein wrote:
> [...]
> >
> > I did not mention this course of events in the man page, because it
> > seemed too much irrelevant information for end user, but am mentioning
> > it here for full disclosure in case somebody thinks this information is
> > relevant.
>
> Hmm, maybe we should include it in the commit message?

Sure, no problem.
I'll wait to see if Jan has more comments and then I will post v2 with minor
fixes that you requested and this in commit message of first patch.

Thanks,
Amir.