Skip to contentSkip to conversation

fanotify: Fixes for documentation of FAN_FS_ERROR

PATCH In review Amir Goldstein 2 participants 8 messages Apr 4, 2025 – Apr 5, 2025 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore
Share & tools
lore
#0 lore raw

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

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.

---
 man/man2/fanotify_mark.2 | 44 +++++++++++++++++++---------------------
 man/man7/fanotify.7      |  6 +++---
 2 files changed, 24 insertions(+), 26 deletions(-)
man/man2/fanotify_mark.2 +21 -23
index f02a182da..a6d80ad68 100644
@@ -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
man/man7/fanotify.7 +3 -3
index adbed2c3e..68e930930 100644
@@ -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
Signature · 1 line
2.34.1
#1 lore raw

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

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

---
 man/man2/fanotify_init.2 | 20 ++++++++++++++++++
 man/man2/fanotify_mark.2 | 37 ++++++++++++++++++++++++++++++++-
 man/man7/fanotify.7      | 45 ++++++++++++++++++++++++++++++++++++++++
 3 files changed, 101 insertions(+), 1 deletion(-)
man/man2/fanotify_init.2 +20 -0
index b90e91707..93887b875 100644
@@ -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
man/man2/fanotify_mark.2 +36 -1
index a6d80ad68..2c9d6e9b9 100644
@@ -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
man/man7/fanotify.7 +45 -0

69 lines not on this page · raw message

Signature · 1 line
2.34.1
#2 lore raw

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

Hi Amir,

Quoted 18 lines · Amir Goldstein

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

---
 man/man2/fanotify_init.2 | 20 ++++++++++++++++++
 man/man2/fanotify_mark.2 | 37 ++++++++++++++++++++++++++++++++-
 man/man7/fanotify.7      | 45 ++++++++++++++++++++++++++++++++++++++++
 3 files changed, 101 insertions(+), 1 deletion(-)
man/man2/fanotify_init.2 +0 -0
index b90e91707..93887b875 100644

man/man2/fanotify_init.2 that the directory entry is referring to. · line 336

Quoted 6 lines
man/man2/fanotify_init.2 +3 -0
@@ -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.

man/man2/fanotify_init.2 that the directory entry is referring to. · line 344

Quoted 8 lines
man/man2/fanotify_init.2 +8 -0
+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.

Quoted 48 lines
man/man2/fanotify_init.2 +9 -0
+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
man/man2/fanotify_mark.2 +16 -1
index a6d80ad68..2c9d6e9b9 100644
@@ -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 .

man/man2/fanotify_mark.2 Create an event when a marked file or directory itself has been moved. · line 417

Quoted 8 lines
man/man2/fanotify_mark.2 +5 -0
@@ -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

Quoted 98 lines
man/man2/fanotify_mark.2 +15 -0
+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
man/man7/fanotify.7 +45 -0
index 68e930930..de0ea8e55 100644
@@ -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
Signature · 1 line
2.34.1
Signature · 3 lines
<https://www.alejandro-colomar.es/>
<https://www.alejandro-colomar.es:8443/>
<http://www.alejandro-colomar.es:8080/>
#3 lore raw

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

Quoted 17 lines · Alejandro Colomar

Hi Amir,

Quoted 13 lines · Amir Goldstein

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

---
 man/man2/fanotify_init.2 | 20 ++++++++++++++++++
 man/man2/fanotify_mark.2 | 37 ++++++++++++++++++++++++++++++++-
 man/man7/fanotify.7      | 45 ++++++++++++++++++++++++++++++++++++++++
 3 files changed, 101 insertions(+), 1 deletion(-)
Quoted 14 lines

man/man2/fanotify_init.2 that the directory entry is referring to. · line 336

Quoted 11 lines
man/man2/fanotify_init.2 +3 -0
index b90e91707..93887b875 100644
@@ -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.

Quoted 111 lines
        $ 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.

man/man2/fanotify_init.2 that the directory entry is referring to. · line 344

Quoted 8 lines
man/man2/fanotify_init.2 +8 -0
+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.

Quoted 50 lines
man/man2/fanotify_init.2 +9 -0
+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
man/man2/fanotify_mark.2 +16 -1
index a6d80ad68..2c9d6e9b9 100644
@@ -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.
Quoted 9 lines

man/man2/fanotify_mark.2 Create an event when a marked file or directory itself has been moved. · line 417

Quoted 6 lines
man/man2/fanotify_mark.2 +5 -0
 .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.

#4 lore raw

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

Hi Amir,

Quoted 19 lines · Amir Goldstein
Quoted 2 lines

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

Quoted 3 lines

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!

Quoted 7 lines
Quoted 7 lines
Quoted 6 lines

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

Quoted 5 lines
Quoted 2 lines

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

Quoted 3 lines

Thanks,
Amir.

Signature · 3 lines
<https://www.alejandro-colomar.es/>
<https://www.alejandro-colomar.es:8443/>
<http://www.alejandro-colomar.es:8080/>
#5 lore raw

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

In reply to Amir Goldstein

Hi Amir,

A small doubt below.

man/man2/fanotify_mark.2 If the filesystem object to be marked is not a directory, the error · line 110

Quoted 12 lines · Amir Goldstein
man/man2/fanotify_mark.2 +8 -0
@@ -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

Quoted 9 lines
man/man2/fanotify_mark.2 +6 -0
+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 .
Signature · 3 lines
<https://www.alejandro-colomar.es/>
<https://www.alejandro-colomar.es:8443/>
<http://www.alejandro-colomar.es:8080/>
#6 lore raw

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

In reply to Amir Goldstein

Hi Amir,

Quoted 7 lines · Amir Goldstein

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

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

Quoted 179 lines
---
 man/man2/fanotify_init.2 | 20 ++++++++++++++++++
 man/man2/fanotify_mark.2 | 37 ++++++++++++++++++++++++++++++++-
 man/man7/fanotify.7      | 45 ++++++++++++++++++++++++++++++++++++++++
 3 files changed, 101 insertions(+), 1 deletion(-)
man/man2/fanotify_init.2 +20 -0
index b90e91707..93887b875 100644
@@ -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
man/man2/fanotify_mark.2 +36 -1
index a6d80ad68..2c9d6e9b9 100644
@@ -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
man/man7/fanotify.7 +45 -0
index 68e930930..de0ea8e55 100644
@@ -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
Signature · 1 line
2.34.1
Signature · 3 lines
<https://www.alejandro-colomar.es/>
<https://www.alejandro-colomar.es:8443/>
<http://www.alejandro-colomar.es:8080/>
#7 lore raw
In reply to Amir Goldstein

Hi Amir,

Quoted 11 lines · 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.

Thanks! I've applied this patch.

Have a lovely day!
Alex

Quoted 95 lines
---
 man/man2/fanotify_mark.2 | 44 +++++++++++++++++++---------------------
 man/man7/fanotify.7      |  6 +++---
 2 files changed, 24 insertions(+), 26 deletions(-)
man/man2/fanotify_mark.2 +21 -23
index f02a182da..a6d80ad68 100644
@@ -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
man/man7/fanotify.7 +3 -3
index adbed2c3e..68e930930 100644
@@ -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
Signature · 1 line
2.34.1
Signature · 3 lines
<https://www.alejandro-colomar.es/>
<https://www.alejandro-colomar.es:8443/>
<http://www.alejandro-colomar.es:8080/>