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

[PATCH v3 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 and flags FAN_ONDIR/FAN_EVENT_ON_CHILD for a non-directrory,
but those events and flags are only relevant for directories.

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

The ENOTDIR error was added by later commits, one of them just merged
to mainline, which are also mentioned in the commit message of the
first patch.

Both Jan and Matthew re-reviewed the changes to the ENOTDIR section.

Thanks,
Amir,

Changes since v2:
- Rearrange ENOTDIR errors section
- Add more cases of ENOTDIR following fix patch

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 | 41 +++++++++++++++++++++++++++++++++
 man7/fanotify.7      | 31 ++++++++++++++-----------
 3 files changed, 109 insertions(+), 18 deletions(-)

-- 
2.25.1

[PATCH v3 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.

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>
---
 man2/fanotify_init.2 | 40 +++++++++++++++++++++++++++++++++++++---
 man2/fanotify_mark.2 | 18 ++++++++++++++++++
 man7/fanotify.7      | 27 +++++++++++++--------------
 3 files changed, 68 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..80f73b983 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 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 v3 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>
Reviewed-by: Jan Kara <jack@suse.cz>
Signed-off-by: Amir Goldstein <amir73il@gmail.com>
---
 man2/fanotify_init.2 | 25 +++++++++++++++++++------
 man2/fanotify_mark.2 | 23 +++++++++++++++++++++++
 man7/fanotify.7      |  6 +++++-
 3 files changed, 47 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 80f73b983..a56475f0a 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.
@@ -474,6 +487,16 @@ and
 do not specify a directory.
 .TP
 .B ENOTDIR
+.I mask
+contains
+.BR FAN_RENAME ,
+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
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

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

[Alejandro Colomar]

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



On 6/30/22 21:06, 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 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>
> ---
>   man2/fanotify_init.2 | 40 +++++++++++++++++++++++++++++++++++++---
>   man2/fanotify_mark.2 | 18 ++++++++++++++++++
>   man7/fanotify.7      | 27 +++++++++++++--------------
>   3 files changed, 68 insertions(+), 17 deletions(-)
> 

[...]

> diff --git a/man2/fanotify_mark.2 b/man2/fanotify_mark.2
> index 3dc538b7f..80f73b983 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 ) ,

s/) ,/),/

Check the difference ;)

groff_man(7):
    Font style macros
        The man macro package is limited in its font styling  op‐
        tions,  offering  only bold (.B), italic (.I), and roman.
        Italic text is usually set underscored instead on  termi‐
        nal devices.  The .SM and .SB macros set text in roman or
        bold,  respectively, at a smaller type size; these differ
        visually from regular‐sized roman or bold  text  only  on
        typesetter devices.  It is often necessary to set text in
        different  styles  without intervening space.  The macros
        .BI, .BR, .IB, .IR, .RB, and .RI, where “B”, “I”, and “R”
        indicate bold, italic, and roman, respectively, set their
        odd‐ and even‐numbered arguments in  alternating  styles,
        with no space separating them.

You can run the following test:

$ man -l - << EOF
.TH a b c d e
.SH Space
.BR foo bar baz
.SH No space
.BR now seethis
EOF

Apart from that, it looks good to me.

Cheers,

Alex


> +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 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 v3 1/2] fanotify.7, fanotify_init.2: Document FAN_REPORT_TARGET_FID

[Alejandro Colomar]

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

Hi Amir,

On 7/4/22 09:27, Amir Goldstein wrote:
> Hi Alex,
>
[...]

> if you can make that small fix on commit that would be great.

Sure, patch set applied!

Cheers,

Alex

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

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