diff mbox series

[v2] fanotify: Document mount namespace events

Message ID 20250401194629.1535477-1-amir73il@gmail.com (mailing list archive)
State New
Headers show
Series [v2] fanotify: Document mount namespace events | expand

Commit Message

Amir Goldstein April 1, 2025, 7:46 p.m. UTC 
Used to subscribe for notifications for when mounts
are attached/detached from a mount namespace.

Cc: Jan Kara <jack@suse.cz>
Cc: Miklos Szeredi <mszeredi@redhat.com>
Reviewed-by: Christian Brauner <brauner@kernel.org>
Signed-off-by: Amir Goldstein <amir73il@gmail.com>
---

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

Comments

Miklos Szeredi April 2, 2025, 9:53 a.m. UTC | #1 
On Tue, 1 Apr 2025 at 21:46, Amir Goldstein <amir73il@gmail.com> wrote:
>
> Used to subscribe for notifications for when mounts
> are attached/detached from a mount namespace.
>
> Cc: Jan Kara <jack@suse.cz>
> Cc: Miklos Szeredi <mszeredi@redhat.com>
> Reviewed-by: Christian Brauner <brauner@kernel.org>
> Signed-off-by: Amir Goldstein <amir73il@gmail.com>

Reviewed-by: Miklos Szeredi <mszeredi@redhat.com>

Thanks,
Miklos
Jan Kara April 2, 2025, 12:25 p.m. UTC | #2 
On Tue 01-04-25 21:46:29, Amir Goldstein wrote:
> Used to subscribe for notifications for when mounts
> are attached/detached from a mount namespace.
> 
> Cc: Jan Kara <jack@suse.cz>
> Cc: Miklos Szeredi <mszeredi@redhat.com>
> Reviewed-by: Christian Brauner <brauner@kernel.org>
> Signed-off-by: Amir Goldstein <amir73il@gmail.com>

Looks good. Feel free to add:

Reviewed-by: Jan Kara <jack@suse.cz>

								Honza


> ---
> 
> 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 ).
>  .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 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 ),
> +the call fails with the error
> +.BR EINVAL .
> +An fanotify group that is initialized with flag
> +.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)"
> +.\" commit 0f46d81f2bce970b1c562aa3c944a271bbec2729
> +Create an event when a mount was attached to or detached from a marked mount namespace.
> +An attempt to set this flag on an inode, mount or filesystem mark
> +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 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
> +.BR statx (2)
> +with the
> +.BR STATX_MNT_ID_UNIQUE
> +flag.
> +.P
> +The fields of the
>  .I fanotify_event_info_error
>  structure are as follows:
>  .TP
> -- 
> 2.34.1
>
Alejandro Colomar April 2, 2025, 8:20 p.m. UTC | #3 
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@suse.cz>
> Cc: Miklos Szeredi <mszeredi@redhat.com>
> Reviewed-by: Christian Brauner <brauner@kernel.org>
> Signed-off-by: Amir Goldstein <amir73il@gmail.com>
> ---
> 
> 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 ).
>  .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

> +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/

> +flag.
> +.P
> +The fields of the
>  .I fanotify_event_info_error
>  structure are as follows:
>  .TP

Have a lovely night!
Alex
Amir Goldstein April 3, 2025, 12:23 p.m. UTC | #4 
On Wed, Apr 2, 2025 at 10:20 PM Alejandro Colomar <alx@kernel.org> 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@suse.cz>
> > Cc: Miklos Szeredi <mszeredi@redhat.com>
> > Reviewed-by: Christian Brauner <brauner@kernel.org>
> > Signed-off-by: Amir Goldstein <amir73il@gmail.com>
> > ---
> >
> > 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.
diff mbox series

Patch

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 ).
 .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 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 ),
+the call fails with the error
+.BR EINVAL .
+An fanotify group that is initialized with flag
+.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)"
+.\" commit 0f46d81f2bce970b1c562aa3c944a271bbec2729
+Create an event when a mount was attached to or detached from a marked mount namespace.
+An attempt to set this flag on an inode, mount or filesystem mark
+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 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
+.BR statx (2)
+with the
+.BR STATX_MNT_ID_UNIQUE
+flag.
+.P
+The fields of the
 .I fanotify_event_info_error
 structure are as follows:
 .TP