fanotify: Fixes for documentation of FAN_FS_ERROR
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
@@ -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
@@ -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
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
@@ -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
@@ -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
Alejandro Colomar
maintainerRe: [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.
Reviewed-by Jan Kara <[email protected]>Reviewed-by Miklos Szeredi <[email protected]>Reviewed-by Christian Brauner <[email protected]>Signed-off-by Amir Goldstein <[email protected]>--- 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
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 containman/man2/fanotify_mark.2 +16
-1@@ -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 errorman/man7/fanotify.7 +45
-0@@ -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: .TPSignature · 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/>
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.
Reviewed-by Jan Kara <[email protected]>Reviewed-by Miklos Szeredi <[email protected]>Reviewed-by Christian Brauner <[email protected]>Signed-off-by Amir Goldstein <[email protected]>--- 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@@ -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 informationShould 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 containman/man2/fanotify_mark.2 +16
-1@@ -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.
Alejandro Colomar
maintainerRe: [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_MNTandFAN_REPORT_FIDare special because they "allows the receipt of events..."
You cannot request FAN_MNT_* events if not initializing group withFAN_REPORT_MNT.
You cannot request FAN_CREATE/RENAME/DELETE if you did not initialize the group withFAN_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_FIDand why I think this is fine that the phrasing of differentFAN_REPOT_flags are slightly different.
Makes sense. Thanks!
Quoted 7 lines
Quoted 7 lines
Quoted 6 lines
.TP
+.BFAN_MNT_ATTACH
+.TQ
+.BRFAN_MNT_DETACH" (both since Linux 6.14)"
+.\" commit0f46d81f2bce970b1c562aa3c944a271bbec2729
+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/>
Alejandro Colomar
maintainerRe: [RESEND PATCH v3 2/2] fanotify: Document mount namespace events
In reply to Amir GoldsteinHi 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/>
Alejandro Colomar
maintainerRe: [RESEND PATCH v3 2/2] fanotify: Document mount namespace events
In reply to Amir GoldsteinHi Amir,
Quoted 7 lines · Amir Goldstein
Used to subscribe for notifications for when mounts are attached/detached from a mount namespace.
Reviewed-by Jan Kara <[email protected]>Reviewed-by Miklos Szeredi <[email protected]>Reviewed-by Christian Brauner <[email protected]>Signed-off-by Amir Goldstein <[email protected]>
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@@ -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 containman/man2/fanotify_mark.2 +36
-1@@ -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 errorman/man7/fanotify.7 +45
-0@@ -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: .TPSignature · 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/>
Alejandro Colomar
maintainerHi Amir,
Quoted 11 lines · Amir Goldstein
The order of
FAN_FS_ERRORentry in the event section was rather arbitrary inside the group of fid info events.
FAN_FS_ERRORis 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_ERRORentry.Cc Jan Kara <[email protected]>Signed-off-by Amir Goldstein <[email protected]>
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@@ -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 withman/man7/fanotify.7 +3
-3@@ -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 theSignature · 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/>