[PATCH v3 1/2] fanotify: Fixes for documentation of FAN_FS_ERROR

[PATCH v3 1/2] fanotify: Fixes for documentation of FAN_FS_ERROR

[Amir Goldstein]

The order of FAN_FS_ERROR entry in the event section was rather
arbitrary inside the group of fid info events.

FAN_FS_ERROR is a special event with error info, so place its entry
after the entries for fid info events and before the entries for
permission events.

Reduce unneeded newlines in the FAN_FS_ERROR entry.

Cc: Jan Kara <jack@suse.cz>
Signed-off-by: Amir Goldstein <amir73il@gmail.com>
---
 man/man2/fanotify_mark.2 | 44 +++++++++++++++++++---------------------
 man/man7/fanotify.7      |  6 +++---
 2 files changed, 24 insertions(+), 26 deletions(-)

diff --git a/man/man2/fanotify_mark.2 b/man/man2/fanotify_mark.2
index f02a182da..a6d80ad68 100644
--- a/man/man2/fanotify_mark.2
+++ b/man/man2/fanotify_mark.2
@@ -362,29 +362,6 @@ Create an event when a marked file or directory itself is deleted.
 An fanotify group that identifies filesystem objects by file handles
 is required.
 .TP
-.BR FAN_FS_ERROR " (since Linux 5.16, 5.15.154, and 5.10.220)"
-.\" commit 9709bd548f11a092d124698118013f66e1740f9b
-Create an event when a filesystem error
-leading to inconsistent filesystem metadata is detected.
-An additional information record of type
-.B FAN_EVENT_INFO_TYPE_ERROR
-is returned for each event in the read buffer.
-An fanotify group that identifies filesystem objects by file handles
-is required.
-.IP
-Events of such type are dependent on support
-from the underlying filesystem.
-At the time of writing,
-only the
-.B ext4
-filesystem reports
-.B FAN_FS_ERROR
-events.
-.IP
-See
-.BR fanotify (7)
-for additional details.
-.TP
 .BR FAN_MOVED_FROM " (since Linux 5.1)"
 .\" commit 235328d1fa4251c6dcb32351219bb553a58838d2
 Create an event when a file or directory has been moved from a marked
@@ -418,6 +395,27 @@ Create an event when a marked file or directory itself has been moved.
 An fanotify group that identifies filesystem objects by file handles
 is required.
 .TP
+.BR FAN_FS_ERROR " (since Linux 5.16, 5.15.154, and 5.10.220)"
+.\" commit 9709bd548f11a092d124698118013f66e1740f9b
+Create an event when a filesystem error
+leading to inconsistent filesystem metadata is detected.
+An additional information record of type
+.B FAN_EVENT_INFO_TYPE_ERROR
+is returned for each event in the read buffer.
+An fanotify group that identifies filesystem objects by file handles
+is required.
+Events of such type are dependent on support
+from the underlying filesystem.
+At the time of writing,
+only the
+.B ext4
+filesystem reports
+.B FAN_FS_ERROR
+events.
+See
+.BR fanotify (7)
+for additional details.
+.TP
 .B FAN_OPEN_PERM
 Create an event when a permission to open a file or directory is requested.
 An fanotify file descriptor created with
diff --git a/man/man7/fanotify.7 b/man/man7/fanotify.7
index adbed2c3e..68e930930 100644
--- a/man/man7/fanotify.7
+++ b/man/man7/fanotify.7
@@ -415,9 +415,6 @@ A child file or directory was deleted in a watched parent.
 .B FAN_DELETE_SELF
 A watched file or directory was deleted.
 .TP
-.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
@@ -445,6 +442,9 @@ A file or directory that was opened read-only
 .RB ( O_RDONLY )
 was closed.
 .TP
+.B FAN_FS_ERROR
+A filesystem error was detected.
+.TP
 .B FAN_Q_OVERFLOW
 The event queue exceeded the limit on number of events.
 This limit can be overridden by specifying the
-- 
2.34.1

[RESEND PATCH v3 2/2] fanotify: Document mount namespace events

[Amir Goldstein]

Used to subscribe for notifications for when mounts
are attached/detached from a mount namespace.

Reviewed-by: Jan Kara <jack@suse.cz>
Reviewed-by: Miklos Szeredi <mszeredi@redhat.com>
Reviewed-by: Christian Brauner <brauner@kernel.org>
Signed-off-by: Amir Goldstein <amir73il@gmail.com>
---
 man/man2/fanotify_init.2 | 20 ++++++++++++++++++
 man/man2/fanotify_mark.2 | 37 ++++++++++++++++++++++++++++++++-
 man/man7/fanotify.7      | 45 ++++++++++++++++++++++++++++++++++++++++
 3 files changed, 101 insertions(+), 1 deletion(-)

diff --git a/man/man2/fanotify_init.2 b/man/man2/fanotify_init.2
index b90e91707..93887b875 100644
--- a/man/man2/fanotify_init.2
+++ b/man/man2/fanotify_init.2
@@ -331,6 +331,26 @@ that the directory entry is referring to.
 This is a synonym for
 .RB ( FAN_REPORT_DFID_NAME | FAN_REPORT_FID | FAN_REPORT_TARGET_FID ).
 .TP
+.BR FAN_REPORT_MNT " (since Linux 6.14)"
+.\" commit 0f46d81f2bce970b1c562aa3c944a271bbec2729
+This value allows the receipt of events which contain additional information
+about the underlying mount correlated to an event.
+An additional record of type
+.B FAN_EVENT_INFO_TYPE_MNT
+encapsulates the information about the mount and is included alongside the
+generic event metadata structure.
+The use of
+.BR FAN_CLASS_CONTENT ,
+.BR FAN_CLASS_PRE_CONTENT,
+or any of the
+.B FAN_REPORT_DFID_NAME_TARGET
+flags along with this flag is not permitted
+and will result in the error
+.BR EINVAL .
+See
+.BR fanotify (7)
+for additional details.
+.TP
 .BR FAN_REPORT_PIDFD " (since Linux 5.15 and 5.10.220)"
 .\" commit af579beb666aefb17e9a335c12c788c92932baf1
 Events for fanotify groups initialized with this flag will contain
diff --git a/man/man2/fanotify_mark.2 b/man/man2/fanotify_mark.2
index a6d80ad68..2c9d6e9b9 100644
--- a/man/man2/fanotify_mark.2
+++ b/man/man2/fanotify_mark.2
@@ -67,7 +67,8 @@ contains
 all marks for filesystems are removed from the group.
 Otherwise, all marks for directories and files are removed.
 No flag other than, and at most one of, the flags
-.B FAN_MARK_MOUNT
+.BR FAN_MARK_MNTNS ,
+.BR FAN_MARK_MOUNT ,
 or
 .B FAN_MARK_FILESYSTEM
 can be used in conjunction with
@@ -99,6 +100,20 @@ If the filesystem object to be marked is not a directory, the error
 .B ENOTDIR
 shall be raised.
 .TP
+.BR FAN_MARK_MNTNS " (since Linux 6.14)"
+.\" commit 0f46d81f2bce970b1c562aa3c944a271bbec2729
+Mark the mount namespace specified by
+.IR pathname .
+If the
+.I pathname
+is not a path that represents a mount namespace (e.g.
+.IR /proc/ pid /ns/mnt ),
+the call fails with the error
+.BR EINVAL .
+An fanotify group that was initialized with flag
+.B FAN_REPORT_MNT
+is required.
+.TP
 .B FAN_MARK_MOUNT
 Mark the mount specified by
 .IR path .
@@ -395,6 +410,26 @@ Create an event when a marked file or directory itself has been moved.
 An fanotify group that identifies filesystem objects by file handles
 is required.
 .TP
+.B FAN_MNT_ATTACH
+.TQ
+.BR FAN_MNT_DETACH " (both since Linux 6.14)"
+.\" commit 0f46d81f2bce970b1c562aa3c944a271bbec2729
+Create an event when a mount was attached to or detached from a marked mount namespace, respectively.
+An attempt to set this flag on an inode, mount, or filesystem mark
+will result in the error
+.BR EINVAL .
+An fanotify group that was initialized with flag
+.B FAN_REPORT_MNT
+and the mark flag
+.B FAN_MARK_MNTNS
+are required.
+An additional information record of type
+.B FAN_EVENT_INFO_TYPE_MNT
+is returned with the event.
+See
+.BR fanotify (7)
+for additional details.
+.TP
 .BR FAN_FS_ERROR " (since Linux 5.16, 5.15.154, and 5.10.220)"
 .\" commit 9709bd548f11a092d124698118013f66e1740f9b
 Create an event when a filesystem error
diff --git a/man/man7/fanotify.7 b/man/man7/fanotify.7
index 68e930930..de0ea8e55 100644
--- a/man/man7/fanotify.7
+++ b/man/man7/fanotify.7
@@ -228,6 +228,23 @@ struct fanotify_event_info_pidfd {
 .EE
 .in
 .P
+In cases where an fanotify group is initialized with
+.BR FAN_REPORT_MNT ,
+event listeners should expect to receive the below
+information record object alongside the generic
+.I fanotify_event_metadata
+structure within the read buffer.
+This structure is defined as follows:
+.P
+.in +4n
+.EX
+struct fanotify_event_info_mnt {
+    struct fanotify_event_info_header hdr;
+    __u64 mnt_id;
+};
+.EE
+.in
+.P
 In case of a
 .B FAN_FS_ERROR
 event,
@@ -442,6 +459,12 @@ A file or directory that was opened read-only
 .RB ( O_RDONLY )
 was closed.
 .TP
+.BR FAN_MNT_ATTACH
+A mount was attached to mount namespace.
+.TP
+.BR FAN_MNT_DETACH
+A mount was detached from mount namespace.
+.TP
 .B FAN_FS_ERROR
 A filesystem error was detected.
 .TP
@@ -540,6 +563,8 @@ The value of this field can be set to one of the following.
 .B FAN_EVENT_INFO_TYPE_ERROR
 .TQ
 .B FAN_EVENT_INFO_TYPE_RANGE
+.TQ
+.B FAN_EVENT_INFO_TYPE_MNT
 .RE
 .IP
 The value set for this field
@@ -725,6 +750,26 @@ in case of a terminated process, the value will be
 .BR \-ESRCH .
 .P
 The fields of the
+.I fanotify_event_info_mnt
+structure are as follows:
+.TP
+.I .hdr
+This is a structure of type
+.IR fanotify_event_info_header .
+The
+.I .info_type
+field is set to
+.BR FAN_EVENT_INFO_TYPE_MNT .
+.TP
+.I .mnt_id
+Identifies the mount associated with the event.
+It is a 64-bit unique mount id as the one returned by
+.BR statx (2)
+with the
+.B STATX_MNT_ID_UNIQUE
+flag.
+.P
+The fields of the
 .I fanotify_event_info_error
 structure are as follows:
 .TP
-- 
2.34.1

Re: [PATCH v3 1/2] fanotify: Fixes for documentation of FAN_FS_ERROR

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 4003 bytes --]

Hi Amir,

On Fri, Apr 04, 2025 at 12:47:22PM +0200, Amir Goldstein wrote:
> The order of FAN_FS_ERROR entry in the event section was rather
> arbitrary inside the group of fid info events.
> 
> FAN_FS_ERROR is a special event with error info, so place its entry
> after the entries for fid info events and before the entries for
> permission events.
> 
> Reduce unneeded newlines in the FAN_FS_ERROR entry.
> 
> Cc: Jan Kara <jack@suse.cz>
> Signed-off-by: Amir Goldstein <amir73il@gmail.com>

Thanks!  I've applied this patch.


Have a lovely day!
Alex

> ---
>  man/man2/fanotify_mark.2 | 44 +++++++++++++++++++---------------------
>  man/man7/fanotify.7      |  6 +++---
>  2 files changed, 24 insertions(+), 26 deletions(-)
> 
> diff --git a/man/man2/fanotify_mark.2 b/man/man2/fanotify_mark.2
> index f02a182da..a6d80ad68 100644
> --- a/man/man2/fanotify_mark.2
> +++ b/man/man2/fanotify_mark.2
> @@ -362,29 +362,6 @@ Create an event when a marked file or directory itself is deleted.
>  An fanotify group that identifies filesystem objects by file handles
>  is required.
>  .TP
> -.BR FAN_FS_ERROR " (since Linux 5.16, 5.15.154, and 5.10.220)"
> -.\" commit 9709bd548f11a092d124698118013f66e1740f9b
> -Create an event when a filesystem error
> -leading to inconsistent filesystem metadata is detected.
> -An additional information record of type
> -.B FAN_EVENT_INFO_TYPE_ERROR
> -is returned for each event in the read buffer.
> -An fanotify group that identifies filesystem objects by file handles
> -is required.
> -.IP
> -Events of such type are dependent on support
> -from the underlying filesystem.
> -At the time of writing,
> -only the
> -.B ext4
> -filesystem reports
> -.B FAN_FS_ERROR
> -events.
> -.IP
> -See
> -.BR fanotify (7)
> -for additional details.
> -.TP
>  .BR FAN_MOVED_FROM " (since Linux 5.1)"
>  .\" commit 235328d1fa4251c6dcb32351219bb553a58838d2
>  Create an event when a file or directory has been moved from a marked
> @@ -418,6 +395,27 @@ Create an event when a marked file or directory itself has been moved.
>  An fanotify group that identifies filesystem objects by file handles
>  is required.
>  .TP
> +.BR FAN_FS_ERROR " (since Linux 5.16, 5.15.154, and 5.10.220)"
> +.\" commit 9709bd548f11a092d124698118013f66e1740f9b
> +Create an event when a filesystem error
> +leading to inconsistent filesystem metadata is detected.
> +An additional information record of type
> +.B FAN_EVENT_INFO_TYPE_ERROR
> +is returned for each event in the read buffer.
> +An fanotify group that identifies filesystem objects by file handles
> +is required.
> +Events of such type are dependent on support
> +from the underlying filesystem.
> +At the time of writing,
> +only the
> +.B ext4
> +filesystem reports
> +.B FAN_FS_ERROR
> +events.
> +See
> +.BR fanotify (7)
> +for additional details.
> +.TP
>  .B FAN_OPEN_PERM
>  Create an event when a permission to open a file or directory is requested.
>  An fanotify file descriptor created with
> diff --git a/man/man7/fanotify.7 b/man/man7/fanotify.7
> index adbed2c3e..68e930930 100644
> --- a/man/man7/fanotify.7
> +++ b/man/man7/fanotify.7
> @@ -415,9 +415,6 @@ A child file or directory was deleted in a watched parent.
>  .B FAN_DELETE_SELF
>  A watched file or directory was deleted.
>  .TP
> -.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
> @@ -445,6 +442,9 @@ A file or directory that was opened read-only
>  .RB ( O_RDONLY )
>  was closed.
>  .TP
> +.B FAN_FS_ERROR
> +A filesystem error was detected.
> +.TP
>  .B FAN_Q_OVERFLOW
>  The event queue exceeded the limit on number of events.
>  This limit can be overridden by specifying the
> -- 
> 2.34.1
> 
> 

-- 
<https://www.alejandro-colomar.es/>
<https://www.alejandro-colomar.es:8443/>
<http://www.alejandro-colomar.es:8080/>

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

Re: [RESEND PATCH v3 2/2] fanotify: Document mount namespace events

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 8571 bytes --]

Hi Amir,

On Fri, Apr 04, 2025 at 12:47:23PM +0200, Amir Goldstein wrote:
> Used to subscribe for notifications for when mounts
> are attached/detached from a mount namespace.
> 
> Reviewed-by: Jan Kara <jack@suse.cz>
> Reviewed-by: Miklos Szeredi <mszeredi@redhat.com>
> Reviewed-by: Christian Brauner <brauner@kernel.org>
> Signed-off-by: Amir Goldstein <amir73il@gmail.com>
> ---
>  man/man2/fanotify_init.2 | 20 ++++++++++++++++++
>  man/man2/fanotify_mark.2 | 37 ++++++++++++++++++++++++++++++++-
>  man/man7/fanotify.7      | 45 ++++++++++++++++++++++++++++++++++++++++
>  3 files changed, 101 insertions(+), 1 deletion(-)
> 
> diff --git a/man/man2/fanotify_init.2 b/man/man2/fanotify_init.2
> index b90e91707..93887b875 100644
> --- a/man/man2/fanotify_init.2
> +++ b/man/man2/fanotify_init.2
> @@ -331,6 +331,26 @@ that the directory entry is referring to.
>  This is a synonym for
>  .RB ( FAN_REPORT_DFID_NAME | FAN_REPORT_FID | FAN_REPORT_TARGET_FID ).
>  .TP
> +.BR FAN_REPORT_MNT " (since Linux 6.14)"
> +.\" commit 0f46d81f2bce970b1c562aa3c944a271bbec2729
> +This value allows the receipt of events which contain additional information

Should we use wording more consistent with other paragraphs introducing
FAN_REPORT_* flags?

	$ grep -n -B1 -A3 '^\.BR FAN_REPORT_.*since' man/man2/fanotify_init.2 
	134-.TP
	135:.BR FAN_REPORT_TID " (since Linux 4.20)"
	136-.\" commit d0a6a87e40da49cfc7954c491d3065a25a641b29
	137-Report thread ID (TID) instead of process ID (PID)
	138-in the
	--
	160-.TP
	161:.BR FAN_REPORT_FID " (since Linux 5.1)"
	162-.\" commit a8b13aa20afb69161b5123b4f1acc7ea0a03d360
	163-This value allows the receipt of events which contain additional information
	164-about the underlying filesystem object correlated to an event.
	--
	201-.TP
	202:.BR FAN_REPORT_DIR_FID " (since Linux 5.9)"
	203-.\" commit 83b7a59896dd24015a34b7f00027f0ff3747972f
	204-Events for fanotify groups initialized with this flag will contain
	205-(see exceptions below) additional information about a directory object
	--
	234-.TP
	235:.BR FAN_REPORT_NAME " (since Linux 5.9)"
	236-.\" commit 929943b38daf817f2e6d303ea04401651fc3bc05
	237-Events for fanotify groups initialized with this flag will contain additional
	238-information about the name of the directory entry correlated to an event.
	--
	298-.TP
	299:.BR FAN_REPORT_TARGET_FID " (since Linux 5.17, 5.15.154, and 5.10.220)"
	300-.\" commit d61fd650e9d206a71fda789f02a1ced4b19944c4
	301-Events for fanotify groups initialized with this flag
	302-will contain additional information about the child
	--
	333-.TP
	334:.BR FAN_REPORT_MNT " (since Linux 6.14)"
	335-.\" commit 0f46d81f2bce970b1c562aa3c944a271bbec2729
	336-This value allows the receipt of events which contain additional information
	337-about the underlying mount correlated to an event.
	--
	353-.TP
	354:.BR FAN_REPORT_PIDFD " (since Linux 5.15 and 5.10.220)"
	355-.\" commit af579beb666aefb17e9a335c12c788c92932baf1
	356-Events for fanotify groups initialized with this flag will contain
	357-an additional information record alongside the generic
	--
	388-.TP
	389:.BR FAN_REPORT_FD_ERROR " (since Linux 6.13 and 6.12.4 and 6.6.66)"
	390-.\" commit 522249f05c5551aec9ec0ba9b6438f1ec19c138d
	391-Events for fanotify groups initialized with this flag may contain
	392-an error code that explains the reason for failure to open a file descriptor.

> +about the underlying mount correlated to an event.
> +An additional record of type
> +.B FAN_EVENT_INFO_TYPE_MNT
> +encapsulates the information about the mount and is included alongside the
> +generic event metadata structure.
> +The use of
> +.BR FAN_CLASS_CONTENT ,
> +.BR FAN_CLASS_PRE_CONTENT,

Missing space.

> +or any of the
> +.B FAN_REPORT_DFID_NAME_TARGET
> +flags along with this flag is not permitted
> +and will result in the error
> +.BR EINVAL .
> +See
> +.BR fanotify (7)
> +for additional details.
> +.TP
>  .BR FAN_REPORT_PIDFD " (since Linux 5.15 and 5.10.220)"
>  .\" commit af579beb666aefb17e9a335c12c788c92932baf1
>  Events for fanotify groups initialized with this flag will contain
> diff --git a/man/man2/fanotify_mark.2 b/man/man2/fanotify_mark.2
> index a6d80ad68..2c9d6e9b9 100644
> --- a/man/man2/fanotify_mark.2
> +++ b/man/man2/fanotify_mark.2
> @@ -67,7 +67,8 @@ contains
>  all marks for filesystems are removed from the group.
>  Otherwise, all marks for directories and files are removed.
>  No flag other than, and at most one of, the flags
> -.B FAN_MARK_MOUNT
> +.BR FAN_MARK_MNTNS ,
> +.BR FAN_MARK_MOUNT ,
>  or
>  .B FAN_MARK_FILESYSTEM
>  can be used in conjunction with
> @@ -99,6 +100,20 @@ If the filesystem object to be marked is not a directory, the error
>  .B ENOTDIR
>  shall be raised.
>  .TP
> +.BR FAN_MARK_MNTNS " (since Linux 6.14)"
> +.\" commit 0f46d81f2bce970b1c562aa3c944a271bbec2729
> +Mark the mount namespace specified by
> +.IR pathname .
> +If the
> +.I pathname
> +is not a path that represents a mount namespace (e.g.
> +.IR /proc/ pid /ns/mnt ),
> +the call fails with the error
> +.BR EINVAL .
> +An fanotify group that was initialized with flag
> +.B FAN_REPORT_MNT
> +is required.
> +.TP
>  .B FAN_MARK_MOUNT
>  Mark the mount specified by
>  .IR path .
> @@ -395,6 +410,26 @@ Create an event when a marked file or directory itself has been moved.
>  An fanotify group that identifies filesystem objects by file handles
>  is required.
>  .TP
> +.B FAN_MNT_ATTACH
> +.TQ
> +.BR FAN_MNT_DETACH " (both since Linux 6.14)"
> +.\" commit 0f46d81f2bce970b1c562aa3c944a271bbec2729
> +Create an event when a mount was attached to or detached from a marked mount namespace, respectively.

Lines should be shorter than 80 columns.


Cheers,
Alex

> +An attempt to set this flag on an inode, mount, or filesystem mark
> +will result in the error
> +.BR EINVAL .
> +An fanotify group that was initialized with flag
> +.B FAN_REPORT_MNT
> +and the mark flag
> +.B FAN_MARK_MNTNS
> +are required.
> +An additional information record of type
> +.B FAN_EVENT_INFO_TYPE_MNT
> +is returned with the event.
> +See
> +.BR fanotify (7)
> +for additional details.
> +.TP
>  .BR FAN_FS_ERROR " (since Linux 5.16, 5.15.154, and 5.10.220)"
>  .\" commit 9709bd548f11a092d124698118013f66e1740f9b
>  Create an event when a filesystem error
> diff --git a/man/man7/fanotify.7 b/man/man7/fanotify.7
> index 68e930930..de0ea8e55 100644
> --- a/man/man7/fanotify.7
> +++ b/man/man7/fanotify.7
> @@ -228,6 +228,23 @@ struct fanotify_event_info_pidfd {
>  .EE
>  .in
>  .P
> +In cases where an fanotify group is initialized with
> +.BR FAN_REPORT_MNT ,
> +event listeners should expect to receive the below
> +information record object alongside the generic
> +.I fanotify_event_metadata
> +structure within the read buffer.
> +This structure is defined as follows:
> +.P
> +.in +4n
> +.EX
> +struct fanotify_event_info_mnt {
> +    struct fanotify_event_info_header hdr;
> +    __u64 mnt_id;
> +};
> +.EE
> +.in
> +.P
>  In case of a
>  .B FAN_FS_ERROR
>  event,
> @@ -442,6 +459,12 @@ A file or directory that was opened read-only
>  .RB ( O_RDONLY )
>  was closed.
>  .TP
> +.BR FAN_MNT_ATTACH
> +A mount was attached to mount namespace.
> +.TP
> +.BR FAN_MNT_DETACH
> +A mount was detached from mount namespace.
> +.TP
>  .B FAN_FS_ERROR
>  A filesystem error was detected.
>  .TP
> @@ -540,6 +563,8 @@ The value of this field can be set to one of the following.
>  .B FAN_EVENT_INFO_TYPE_ERROR
>  .TQ
>  .B FAN_EVENT_INFO_TYPE_RANGE
> +.TQ
> +.B FAN_EVENT_INFO_TYPE_MNT
>  .RE
>  .IP
>  The value set for this field
> @@ -725,6 +750,26 @@ in case of a terminated process, the value will be
>  .BR \-ESRCH .
>  .P
>  The fields of the
> +.I fanotify_event_info_mnt
> +structure are as follows:
> +.TP
> +.I .hdr
> +This is a structure of type
> +.IR fanotify_event_info_header .
> +The
> +.I .info_type
> +field is set to
> +.BR FAN_EVENT_INFO_TYPE_MNT .
> +.TP
> +.I .mnt_id
> +Identifies the mount associated with the event.
> +It is a 64-bit unique mount id as the one returned by
> +.BR statx (2)
> +with the
> +.B STATX_MNT_ID_UNIQUE
> +flag.
> +.P
> +The fields of the
>  .I fanotify_event_info_error
>  structure are as follows:
>  .TP
> -- 
> 2.34.1
> 

-- 
<https://www.alejandro-colomar.es/>
<https://www.alejandro-colomar.es:8443/>
<http://www.alejandro-colomar.es:8080/>

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

Re: [RESEND PATCH v3 2/2] fanotify: Document mount namespace events

[Amir Goldstein]

On Fri, Apr 4, 2025 at 4:40 PM Alejandro Colomar <alx@kernel.org> wrote:
>
> Hi Amir,
>
> On Fri, Apr 04, 2025 at 12:47:23PM +0200, Amir Goldstein wrote:
> > Used to subscribe for notifications for when mounts
> > are attached/detached from a mount namespace.
> >
> > Reviewed-by: Jan Kara <jack@suse.cz>
> > Reviewed-by: Miklos Szeredi <mszeredi@redhat.com>
> > Reviewed-by: Christian Brauner <brauner@kernel.org>
> > Signed-off-by: Amir Goldstein <amir73il@gmail.com>
> > ---
> >  man/man2/fanotify_init.2 | 20 ++++++++++++++++++
> >  man/man2/fanotify_mark.2 | 37 ++++++++++++++++++++++++++++++++-
> >  man/man7/fanotify.7      | 45 ++++++++++++++++++++++++++++++++++++++++
> >  3 files changed, 101 insertions(+), 1 deletion(-)
> >
> > diff --git a/man/man2/fanotify_init.2 b/man/man2/fanotify_init.2
> > index b90e91707..93887b875 100644
> > --- a/man/man2/fanotify_init.2
> > +++ b/man/man2/fanotify_init.2
> > @@ -331,6 +331,26 @@ that the directory entry is referring to.
> >  This is a synonym for
> >  .RB ( FAN_REPORT_DFID_NAME | FAN_REPORT_FID | FAN_REPORT_TARGET_FID ).
> >  .TP
> > +.BR FAN_REPORT_MNT " (since Linux 6.14)"
> > +.\" commit 0f46d81f2bce970b1c562aa3c944a271bbec2729
> > +This value allows the receipt of events which contain additional information
>
> Should we use wording more consistent with other paragraphs introducing
> FAN_REPORT_* flags?

No, I think that is fine as is.

FAN_REPORT_MNT and FAN_REPORT_FID are special because
they "allows the receipt of events..."
You cannot request FAN_MNT_* events if not initializing group with
FAN_REPORT_MNT.
You cannot request FAN_CREATE/RENAME/DELETE if you did
not initialize the group with FAN_REPORT_FID.

Other FAN_REPORT_ flags do not impact the set events that
can be requested but add more info to existing events.
Some add more information (FAN_REPORT_PIDFD),
some replace existing information with other information
(FAN_REPORT_TID) and some change semantics of existing
information fields (FAN_REPORT_FD_ERROR).

This is why I used the phrasing from FAN_REPORT_FID
and why I think this is fine that the phrasing of different
FAN_REPOT_ flags are slightly different.

>
>         $ grep -n -B1 -A3 '^\.BR FAN_REPORT_.*since' man/man2/fanotify_init.2
>         134-.TP
>         135:.BR FAN_REPORT_TID " (since Linux 4.20)"
>         136-.\" commit d0a6a87e40da49cfc7954c491d3065a25a641b29
>         137-Report thread ID (TID) instead of process ID (PID)
>         138-in the
>         --
>         160-.TP
>         161:.BR FAN_REPORT_FID " (since Linux 5.1)"
>         162-.\" commit a8b13aa20afb69161b5123b4f1acc7ea0a03d360
>         163-This value allows the receipt of events which contain additional information
>         164-about the underlying filesystem object correlated to an event.
>         --
>         201-.TP
>         202:.BR FAN_REPORT_DIR_FID " (since Linux 5.9)"
>         203-.\" commit 83b7a59896dd24015a34b7f00027f0ff3747972f
>         204-Events for fanotify groups initialized with this flag will contain
>         205-(see exceptions below) additional information about a directory object
>         --
>         234-.TP
>         235:.BR FAN_REPORT_NAME " (since Linux 5.9)"
>         236-.\" commit 929943b38daf817f2e6d303ea04401651fc3bc05
>         237-Events for fanotify groups initialized with this flag will contain additional
>         238-information about the name of the directory entry correlated to an event.
>         --
>         298-.TP
>         299:.BR FAN_REPORT_TARGET_FID " (since Linux 5.17, 5.15.154, and 5.10.220)"
>         300-.\" commit d61fd650e9d206a71fda789f02a1ced4b19944c4
>         301-Events for fanotify groups initialized with this flag
>         302-will contain additional information about the child
>         --
>         333-.TP
>         334:.BR FAN_REPORT_MNT " (since Linux 6.14)"
>         335-.\" commit 0f46d81f2bce970b1c562aa3c944a271bbec2729
>         336-This value allows the receipt of events which contain additional information
>         337-about the underlying mount correlated to an event.
>         --
>         353-.TP
>         354:.BR FAN_REPORT_PIDFD " (since Linux 5.15 and 5.10.220)"
>         355-.\" commit af579beb666aefb17e9a335c12c788c92932baf1
>         356-Events for fanotify groups initialized with this flag will contain
>         357-an additional information record alongside the generic
>         --
>         388-.TP
>         389:.BR FAN_REPORT_FD_ERROR " (since Linux 6.13 and 6.12.4 and 6.6.66)"
>         390-.\" commit 522249f05c5551aec9ec0ba9b6438f1ec19c138d
>         391-Events for fanotify groups initialized with this flag may contain
>         392-an error code that explains the reason for failure to open a file descriptor.
>
> > +about the underlying mount correlated to an event.
> > +An additional record of type
> > +.B FAN_EVENT_INFO_TYPE_MNT
> > +encapsulates the information about the mount and is included alongside the
> > +generic event metadata structure.
> > +The use of
> > +.BR FAN_CLASS_CONTENT ,
> > +.BR FAN_CLASS_PRE_CONTENT,
>
> Missing space.
>
> > +or any of the
> > +.B FAN_REPORT_DFID_NAME_TARGET
> > +flags along with this flag is not permitted
> > +and will result in the error
> > +.BR EINVAL .
> > +See
> > +.BR fanotify (7)
> > +for additional details.
> > +.TP
> >  .BR FAN_REPORT_PIDFD " (since Linux 5.15 and 5.10.220)"
> >  .\" commit af579beb666aefb17e9a335c12c788c92932baf1
> >  Events for fanotify groups initialized with this flag will contain
> > diff --git a/man/man2/fanotify_mark.2 b/man/man2/fanotify_mark.2
> > index a6d80ad68..2c9d6e9b9 100644
> > --- a/man/man2/fanotify_mark.2
> > +++ b/man/man2/fanotify_mark.2
> > @@ -67,7 +67,8 @@ contains
> >  all marks for filesystems are removed from the group.
> >  Otherwise, all marks for directories and files are removed.
> >  No flag other than, and at most one of, the flags
> > -.B FAN_MARK_MOUNT
> > +.BR FAN_MARK_MNTNS ,
> > +.BR FAN_MARK_MOUNT ,
> >  or
> >  .B FAN_MARK_FILESYSTEM
> >  can be used in conjunction with
> > @@ -99,6 +100,20 @@ If the filesystem object to be marked is not a directory, the error
> >  .B ENOTDIR
> >  shall be raised.
> >  .TP
> > +.BR FAN_MARK_MNTNS " (since Linux 6.14)"
> > +.\" commit 0f46d81f2bce970b1c562aa3c944a271bbec2729
> > +Mark the mount namespace specified by
> > +.IR pathname .
> > +If the
> > +.I pathname
> > +is not a path that represents a mount namespace (e.g.
> > +.IR /proc/ pid /ns/mnt ),
> > +the call fails with the error
> > +.BR EINVAL .
> > +An fanotify group that was initialized with flag
> > +.B FAN_REPORT_MNT
> > +is required.
> > +.TP
> >  .B FAN_MARK_MOUNT
> >  Mark the mount specified by
> >  .IR path .
> > @@ -395,6 +410,26 @@ Create an event when a marked file or directory itself has been moved.
> >  An fanotify group that identifies filesystem objects by file handles
> >  is required.
> >  .TP
> > +.B FAN_MNT_ATTACH
> > +.TQ
> > +.BR FAN_MNT_DETACH " (both since Linux 6.14)"
> > +.\" commit 0f46d81f2bce970b1c562aa3c944a271bbec2729
> > +Create an event when a mount was attached to or detached from a marked mount namespace, respectively.
>
> Lines should be shorter than 80 columns.
>

Sorry.
Could you fix that on commit?

Thanks,
Amir.

Re: [RESEND PATCH v3 2/2] fanotify: Document mount namespace events

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 1713 bytes --]

Hi Amir,

On Fri, Apr 04, 2025 at 04:58:19PM +0200, Amir Goldstein wrote:
> > Should we use wording more consistent with other paragraphs introducing
> > FAN_REPORT_* flags?
> 
> No, I think that is fine as is.
> 
> FAN_REPORT_MNT and FAN_REPORT_FID are special because
> they "allows the receipt of events..."
> You cannot request FAN_MNT_* events if not initializing group with
> FAN_REPORT_MNT.
> You cannot request FAN_CREATE/RENAME/DELETE if you did
> not initialize the group with FAN_REPORT_FID.
> 
> Other FAN_REPORT_ flags do not impact the set events that
> can be requested but add more info to existing events.
> Some add more information (FAN_REPORT_PIDFD),
> some replace existing information with other information
> (FAN_REPORT_TID) and some change semantics of existing
> information fields (FAN_REPORT_FD_ERROR).
> 
> This is why I used the phrasing from FAN_REPORT_FID
> and why I think this is fine that the phrasing of different
> FAN_REPOT_ flags are slightly different.

Makes sense.  Thanks!

> > >  .TP
> > > +.B FAN_MNT_ATTACH
> > > +.TQ
> > > +.BR FAN_MNT_DETACH " (both since Linux 6.14)"
> > > +.\" commit 0f46d81f2bce970b1c562aa3c944a271bbec2729
> > > +Create an event when a mount was attached to or detached from a marked mount namespace, respectively.
> >
> > Lines should be shorter than 80 columns.
> >
> 
> Sorry.
> Could you fix that on commit?

Yep, no problem.  I was going to amend it myself, until I asked the
question from above.  I'll amend.


Have a lovely night!
Alex

> 
> Thanks,
> Amir.

-- 
<https://www.alejandro-colomar.es/>
<https://www.alejandro-colomar.es:8443/>
<http://www.alejandro-colomar.es:8080/>

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

Re: [RESEND PATCH v3 2/2] fanotify: Document mount namespace events

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 998 bytes --]

Hi Amir,

A small doubt below.

On Fri, Apr 04, 2025 at 12:47:23PM +0200, Amir Goldstein wrote:
> @@ -99,6 +100,20 @@ If the filesystem object to be marked is not a directory, the error
>  .B ENOTDIR
>  shall be raised.
>  .TP
> +.BR FAN_MARK_MNTNS " (since Linux 6.14)"
> +.\" commit 0f46d81f2bce970b1c562aa3c944a271bbec2729
> +Mark the mount namespace specified by
> +.IR pathname .
> +If the
> +.I pathname
> +is not a path that represents a mount namespace (e.g.
> +.IR /proc/ pid /ns/mnt ),

Are there any other paths that may represent a mount namespace?  Maybe
we should change s/e.g./i.e./?


Have a lovely day!
Alex

> +the call fails with the error
> +.BR EINVAL .
> +An fanotify group that was initialized with flag
> +.B FAN_REPORT_MNT
> +is required.
> +.TP
>  .B FAN_MARK_MOUNT
>  Mark the mount specified by
>  .IR path .

-- 
<https://www.alejandro-colomar.es/>
<https://www.alejandro-colomar.es:8443/>
<http://www.alejandro-colomar.es:8080/>

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

Re: [RESEND PATCH v3 2/2] fanotify: Document mount namespace events

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 9226 bytes --]

Hi Amir,

On Fri, Apr 04, 2025 at 12:47:23PM +0200, Amir Goldstein wrote:
> Used to subscribe for notifications for when mounts
> are attached/detached from a mount namespace.
> 
> Reviewed-by: Jan Kara <jack@suse.cz>
> Reviewed-by: Miklos Szeredi <mszeredi@redhat.com>
> Reviewed-by: Christian Brauner <brauner@kernel.org>
> Signed-off-by: Amir Goldstein <amir73il@gmail.com>

Thanks!  I've applied the patch.  I've amended with the following edits
(plus some edits to the subject lines).
<https://www.alejandro-colomar.es:8443/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=4c4d9f0f5148caf1271394018d0f7381c1b8b400>

	diff --git i/man/man2/fanotify_init.2 w/man/man2/fanotify_init.2
	index 93887b875..7038845bf 100644
	--- i/man/man2/fanotify_init.2
	+++ w/man/man2/fanotify_init.2
	@@ -337,11 +337,11 @@ .SH DESCRIPTION
	 about the underlying mount correlated to an event.
	 An additional record of type
	 .B FAN_EVENT_INFO_TYPE_MNT
	-encapsulates the information about the mount and is included alongside the
	-generic event metadata structure.
	+encapsulates the information about the mount
	+and is included alongside the generic event metadata structure.
	 The use of
	 .BR FAN_CLASS_CONTENT ,
	-.BR FAN_CLASS_PRE_CONTENT,
	+.BR FAN_CLASS_PRE_CONTENT ,
	 or any of the
	 .B FAN_REPORT_DFID_NAME_TARGET
	 flags along with this flag is not permitted
	diff --git i/man/man2/fanotify_mark.2 w/man/man2/fanotify_mark.2
	index 2c9d6e9b9..5bd3cb2ab 100644
	--- i/man/man2/fanotify_mark.2
	+++ w/man/man2/fanotify_mark.2
	@@ -103,10 +103,10 @@ .SH DESCRIPTION
	 .BR FAN_MARK_MNTNS " (since Linux 6.14)"
	 .\" commit 0f46d81f2bce970b1c562aa3c944a271bbec2729
	 Mark the mount namespace specified by
	-.IR pathname .
	-If the
	-.I pathname
	-is not a path that represents a mount namespace (e.g.
	+.IR path .
	+If
	+.I path
	+does not represent a mount namespace (e.g.
	 .IR /proc/ pid /ns/mnt ),
	 the call fails with the error
	 .BR EINVAL .
	@@ -414,7 +414,9 @@ .SH DESCRIPTION
	 .TQ
	 .BR FAN_MNT_DETACH " (both since Linux 6.14)"
	 .\" commit 0f46d81f2bce970b1c562aa3c944a271bbec2729
	-Create an event when a mount was attached to or detached from a marked mount namespace, respectively.
	+Create an event when
	+a mount was attached to or detached from a marked mount namespace,
	+respectively.
	 An attempt to set this flag on an inode, mount, or filesystem mark
	 will result in the error
	 .BR EINVAL .
	diff --git i/man/man7/fanotify.7 w/man/man7/fanotify.7
	index de0ea8e55..b4f65f8a0 100644
	--- i/man/man7/fanotify.7
	+++ w/man/man7/fanotify.7
	@@ -230,8 +230,9 @@ .SS Reading fanotify events
	 .P
	 In cases where an fanotify group is initialized with
	 .BR FAN_REPORT_MNT ,
	-event listeners should expect to receive the below
	-information record object alongside the generic
	+event listeners should expect to receive
	+the below information record object
	+alongside the generic
	 .I fanotify_event_metadata
	 structure within the read buffer.
	 This structure is defined as follows:
	@@ -460,10 +460,10 @@ .SS Reading fanotify events
	 .RB ( O_RDONLY )
	 was closed.
	 .TP
	-.BR FAN_MNT_ATTACH
	+.B FAN_MNT_ATTACH
	 A mount was attached to mount namespace.
	 .TP
	-.BR FAN_MNT_DETACH
	+.B FAN_MNT_DETACH
	 A mount was detached from mount namespace.
	 .TP
	 .B FAN_FS_ERROR


Cheers,
Alex

> ---
>  man/man2/fanotify_init.2 | 20 ++++++++++++++++++
>  man/man2/fanotify_mark.2 | 37 ++++++++++++++++++++++++++++++++-
>  man/man7/fanotify.7      | 45 ++++++++++++++++++++++++++++++++++++++++
>  3 files changed, 101 insertions(+), 1 deletion(-)
> 
> diff --git a/man/man2/fanotify_init.2 b/man/man2/fanotify_init.2
> index b90e91707..93887b875 100644
> --- a/man/man2/fanotify_init.2
> +++ b/man/man2/fanotify_init.2
> @@ -331,6 +331,26 @@ that the directory entry is referring to.
>  This is a synonym for
>  .RB ( FAN_REPORT_DFID_NAME | FAN_REPORT_FID | FAN_REPORT_TARGET_FID ).
>  .TP
> +.BR FAN_REPORT_MNT " (since Linux 6.14)"
> +.\" commit 0f46d81f2bce970b1c562aa3c944a271bbec2729
> +This value allows the receipt of events which contain additional information
> +about the underlying mount correlated to an event.
> +An additional record of type
> +.B FAN_EVENT_INFO_TYPE_MNT
> +encapsulates the information about the mount and is included alongside the
> +generic event metadata structure.
> +The use of
> +.BR FAN_CLASS_CONTENT ,
> +.BR FAN_CLASS_PRE_CONTENT,
> +or any of the
> +.B FAN_REPORT_DFID_NAME_TARGET
> +flags along with this flag is not permitted
> +and will result in the error
> +.BR EINVAL .
> +See
> +.BR fanotify (7)
> +for additional details.
> +.TP
>  .BR FAN_REPORT_PIDFD " (since Linux 5.15 and 5.10.220)"
>  .\" commit af579beb666aefb17e9a335c12c788c92932baf1
>  Events for fanotify groups initialized with this flag will contain
> diff --git a/man/man2/fanotify_mark.2 b/man/man2/fanotify_mark.2
> index a6d80ad68..2c9d6e9b9 100644
> --- a/man/man2/fanotify_mark.2
> +++ b/man/man2/fanotify_mark.2
> @@ -67,7 +67,8 @@ contains
>  all marks for filesystems are removed from the group.
>  Otherwise, all marks for directories and files are removed.
>  No flag other than, and at most one of, the flags
> -.B FAN_MARK_MOUNT
> +.BR FAN_MARK_MNTNS ,
> +.BR FAN_MARK_MOUNT ,
>  or
>  .B FAN_MARK_FILESYSTEM
>  can be used in conjunction with
> @@ -99,6 +100,20 @@ If the filesystem object to be marked is not a directory, the error
>  .B ENOTDIR
>  shall be raised.
>  .TP
> +.BR FAN_MARK_MNTNS " (since Linux 6.14)"
> +.\" commit 0f46d81f2bce970b1c562aa3c944a271bbec2729
> +Mark the mount namespace specified by
> +.IR pathname .
> +If the
> +.I pathname
> +is not a path that represents a mount namespace (e.g.
> +.IR /proc/ pid /ns/mnt ),
> +the call fails with the error
> +.BR EINVAL .
> +An fanotify group that was initialized with flag
> +.B FAN_REPORT_MNT
> +is required.
> +.TP
>  .B FAN_MARK_MOUNT
>  Mark the mount specified by
>  .IR path .
> @@ -395,6 +410,26 @@ Create an event when a marked file or directory itself has been moved.
>  An fanotify group that identifies filesystem objects by file handles
>  is required.
>  .TP
> +.B FAN_MNT_ATTACH
> +.TQ
> +.BR FAN_MNT_DETACH " (both since Linux 6.14)"
> +.\" commit 0f46d81f2bce970b1c562aa3c944a271bbec2729
> +Create an event when a mount was attached to or detached from a marked mount namespace, respectively.
> +An attempt to set this flag on an inode, mount, or filesystem mark
> +will result in the error
> +.BR EINVAL .
> +An fanotify group that was initialized with flag
> +.B FAN_REPORT_MNT
> +and the mark flag
> +.B FAN_MARK_MNTNS
> +are required.
> +An additional information record of type
> +.B FAN_EVENT_INFO_TYPE_MNT
> +is returned with the event.
> +See
> +.BR fanotify (7)
> +for additional details.
> +.TP
>  .BR FAN_FS_ERROR " (since Linux 5.16, 5.15.154, and 5.10.220)"
>  .\" commit 9709bd548f11a092d124698118013f66e1740f9b
>  Create an event when a filesystem error
> diff --git a/man/man7/fanotify.7 b/man/man7/fanotify.7
> index 68e930930..de0ea8e55 100644
> --- a/man/man7/fanotify.7
> +++ b/man/man7/fanotify.7
> @@ -228,6 +228,23 @@ struct fanotify_event_info_pidfd {
>  .EE
>  .in
>  .P
> +In cases where an fanotify group is initialized with
> +.BR FAN_REPORT_MNT ,
> +event listeners should expect to receive the below
> +information record object alongside the generic
> +.I fanotify_event_metadata
> +structure within the read buffer.
> +This structure is defined as follows:
> +.P
> +.in +4n
> +.EX
> +struct fanotify_event_info_mnt {
> +    struct fanotify_event_info_header hdr;
> +    __u64 mnt_id;
> +};
> +.EE
> +.in
> +.P
>  In case of a
>  .B FAN_FS_ERROR
>  event,
> @@ -442,6 +459,12 @@ A file or directory that was opened read-only
>  .RB ( O_RDONLY )
>  was closed.
>  .TP
> +.BR FAN_MNT_ATTACH
> +A mount was attached to mount namespace.
> +.TP
> +.BR FAN_MNT_DETACH
> +A mount was detached from mount namespace.
> +.TP
>  .B FAN_FS_ERROR
>  A filesystem error was detected.
>  .TP
> @@ -540,6 +563,8 @@ The value of this field can be set to one of the following.
>  .B FAN_EVENT_INFO_TYPE_ERROR
>  .TQ
>  .B FAN_EVENT_INFO_TYPE_RANGE
> +.TQ
> +.B FAN_EVENT_INFO_TYPE_MNT
>  .RE
>  .IP
>  The value set for this field
> @@ -725,6 +750,26 @@ in case of a terminated process, the value will be
>  .BR \-ESRCH .
>  .P
>  The fields of the
> +.I fanotify_event_info_mnt
> +structure are as follows:
> +.TP
> +.I .hdr
> +This is a structure of type
> +.IR fanotify_event_info_header .
> +The
> +.I .info_type
> +field is set to
> +.BR FAN_EVENT_INFO_TYPE_MNT .
> +.TP
> +.I .mnt_id
> +Identifies the mount associated with the event.
> +It is a 64-bit unique mount id as the one returned by
> +.BR statx (2)
> +with the
> +.B STATX_MNT_ID_UNIQUE
> +flag.
> +.P
> +The fields of the
>  .I fanotify_event_info_error
>  structure are as follows:
>  .TP
> -- 
> 2.34.1
> 

-- 
<https://www.alejandro-colomar.es/>
<https://www.alejandro-colomar.es:8443/>
<http://www.alejandro-colomar.es:8080/>

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