On Wed, Apr 2, 2025 at 10:20 PM Alejandro Colomar <alx@xxxxxxxxxx> wrote:
>
> Hi Amir,
>
> On Tue, Apr 01, 2025 at 09:46:29PM +0200, Amir Goldstein wrote:
> > Used to subscribe for notifications for when mounts
> > are attached/detached from a mount namespace.
> >
> > Cc: Jan Kara <jack@xxxxxxx>
> > Cc: Miklos Szeredi <mszeredi@xxxxxxxxxx>
> > Reviewed-by: Christian Brauner <brauner@xxxxxxxxxx>
> > Signed-off-by: Amir Goldstein <amir73il@xxxxxxxxx>
> > ---
> >
> > Changes since v1:
> > - Add RVB
> > - Add reference to statx() unique mnt_id (Jan)
> > - Fix description of MARK_MNTNS path (Miklos)
> >
> > man/man2/fanotify_init.2 | 20 ++++++++++++++++++
> > man/man2/fanotify_mark.2 | 35 +++++++++++++++++++++++++++++++-
> > man/man7/fanotify.7 | 44 ++++++++++++++++++++++++++++++++++++++++
> > 3 files changed, 98 insertions(+), 1 deletion(-)
> >
> > diff --git a/man/man2/fanotify_init.2 b/man/man2/fanotify_init.2
> > index 699b6f054..26289c496 100644
> > --- a/man/man2/fanotify_init.2
> > +++ b/man/man2/fanotify_init.2
> > @@ -330,6 +330,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 ).
See here
> > .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
>
> What do you mean by any of the flags? Is _NAME_ a placeholder? If so,
> the placeholder should be in italics:
>
> .BI FOO_ placeholder _BAR
FAN_REPORT_DFID_NAME_TARGET is a macro for combination
of flags (see above)
None of those flags are allowed together with FAN_REPORT_MNT
>
> > +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 da569279b..dab7e1a32 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.
> > +.BR /proc/ pid /ns/mnt ),
>
> Paths should be in italics, not bold.
>
> .IR /proc/ pid /ns/mnt ),
>
> > +the call fails with the error
> > +.BR EINVAL .
> > +An fanotify group that is initialized with flag
>
> The fanotify group must have been initialized previously, I assume. If
> so, I think we should say s/is/have been/. Or maybe s/is/was/.
>
> > +.B FAN_REPORT_MNT
> > +is required.
> > +.TP
> > .B FAN_MARK_MOUNT
> > Mark the mount specified by
> > .IR pathname .
> > @@ -395,6 +410,24 @@ 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_MNT_ATTACH ", " FAN_MNT_DETACH " (since Linux 6.14)"
>
> Let's use two separate tags. We can do like sched_setattr(2):
>
>
> SCHED_FLAG_UTIL_CLAMP_MIN
> SCHED_FLAG_UTIL_CLAMP_MAX (both since Linux 5.3)
> These flags indicate that the sched_util_min or
> sched_util_max fields, respectively, are present,
> representing the expected minimum and maximum uti‐
> lization of the thread.
>
> The utilization attributes provide the scheduler
> with boundaries within which it should schedule the
> thread, potentially informing its decisions regard‐
> ing task placement and frequency selection.
>
> This would be coded as:
>
> .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.
>
> Please don't go past 80 columns in source code. Here, I'd break after
> 'event', for example, and maybe also before 'marked'.
>
> > +An attempt to set this flag on an inode, mount or filesystem mark
>
> If I'm reading this correctly, I think you should add a comma after
> 'mount'.
>
> > +will result in the error
> > +.BR EINVAL .
> > +An fanotify group that is 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 77dcb8aa5..a2f766839 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'd break the sentence after 'receive' and before 'alongside'.
>
> > +.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,7 @@ The value of this field can be set to one of the following:
> > .BR FAN_EVENT_INFO_TYPE_FID ,
> > .BR FAN_EVENT_INFO_TYPE_DFID ,
> > .BR FAN_EVENT_INFO_TYPE_DFID_NAME ,
> > +.BR FAN_EVENT_INFO_TYPE_MNT ,
> > .BR FAN_EVENT_INFO_TYPE_ERROR ,
> > .BR FAN_EVENT_INFO_TYPE_RANGE ,
> > or
> > @@ -727,6 +751,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 64bit unique mount id as the one returned by
>
> s/64bit/64-bit/
>
> > +.BR statx (2)
> > +with the
> > +.BR STATX_MNT_ID_UNIQUE
>
> s/BR/B/
>
Fixed all.
Let me know if you are happy with my clarification on
FAN_REPORT_DFID_NAME_TARGET
and I will post v3.
Thanks,
Amir.
