[PATCH] fanotify.7,fanotify_mark.2: update documentation of fanotify w.r.t fsid

[PATCH] fanotify.7,fanotify_mark.2: update documentation of fanotify w.r.t fsid

[Amir Goldstein]

Clarify the conditions for getting the -EXDEV and -ENODEV errors.

Signed-off-by: Amir Goldstein <amir73il@gmail.com>
---

Hi Alejandro,

This is a followup on fanotify changes from v6.8
that are forgot to follow up on at the time.

Thanks,
Amir.

 man/man2/fanotify_mark.2 | 27 +++++++++++++++++++++------
 man/man7/fanotify.7      | 10 ++++++++++
 2 files changed, 31 insertions(+), 6 deletions(-)

diff --git a/man/man2/fanotify_mark.2 b/man/man2/fanotify_mark.2
index fc9b83459..b5e091c25 100644
--- a/man/man2/fanotify_mark.2
+++ b/man/man2/fanotify_mark.2
@@ -659,17 +659,16 @@ The filesystem object indicated by
 .I dirfd
 and
 .I pathname
-is not associated with a filesystem that supports
+is associated with a filesystem that reports zero
 .I fsid
 (e.g.,
 .BR fuse (4)).
-.BR tmpfs (5)
-did not support
-.I fsid
-prior to Linux 5.13.
-.\" commit 59cda49ecf6c9a32fae4942420701b6e087204f6
 This error can be returned only with an fanotify group that identifies
 filesystem objects by file handles.
+Since Linux 6.8,
+.\" commit 30ad1938326bf9303ca38090339d948975a626f5
+this error can be returned only when
+trying to add a mount or filesystem mark.
 .TP
 .B ENOENT
 The filesystem object indicated by
@@ -768,6 +767,22 @@ which uses a different
 than its root superblock.
 This error can be returned only with an fanotify group that identifies
 filesystem objects by file handles.
+Since Linux 6.8,
+.\" commit 30ad1938326bf9303ca38090339d948975a626f5
+this error will be returned
+when trying to add a mount or filesystem mark on a subvolume,
+when trying to add inode marks in different subvolumes,
+or when trying to add inode marks in a
+.BR btrfs (5)
+subvolume and in another filesystem.
+Since Linux 6.8,
+.\" commit 30ad1938326bf9303ca38090339d948975a626f5
+this error will also be returned
+when trying to add marks in different filesystems,
+where one of the filesystems reports zero
+.I fsid
+(e.g.,
+.BR fuse (4)).
 .SH STANDARDS
 Linux.
 .SH HISTORY
diff --git a/man/man7/fanotify.7 b/man/man7/fanotify.7
index 449af949c..db8fe6c00 100644
--- a/man/man7/fanotify.7
+++ b/man/man7/fanotify.7
@@ -575,6 +575,16 @@ and contains the same value as
 .I f_fsid
 when calling
 .BR statfs (2).
+Note that some filesystems (e.g.,
+.BR fuse (4))
+report zero
+.IR fsid .
+In these cases, it is not possible to use
+.I fsid
+to associate the event with a specific filesystem instance,
+so monitoring different filesystem instances that report zero
+.I fsid
+with the same fanotify group is not supported.
 .TP
 .I handle
 This field contains a variable-length structure of type
-- 
2.34.1

Re: [PATCH] fanotify.7,fanotify_mark.2: update documentation of fanotify w.r.t fsid

[Jan Kara]

On Tue 08-10-24 11:45:03, Amir Goldstein wrote:
> Clarify the conditions for getting the -EXDEV and -ENODEV errors.
> 
> Signed-off-by: Amir Goldstein <amir73il@gmail.com>

Looks good. Feel free to add:

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

But I've read somewhere that Alejandro stepped down as manpages maintainer
so they are officially unmaintained?

								Honza

> Hi Alejandro,
> 
> This is a followup on fanotify changes from v6.8
> that are forgot to follow up on at the time.
> 
> Thanks,
> Amir.
> 
>  man/man2/fanotify_mark.2 | 27 +++++++++++++++++++++------
>  man/man7/fanotify.7      | 10 ++++++++++
>  2 files changed, 31 insertions(+), 6 deletions(-)
> 
> diff --git a/man/man2/fanotify_mark.2 b/man/man2/fanotify_mark.2
> index fc9b83459..b5e091c25 100644
> --- a/man/man2/fanotify_mark.2
> +++ b/man/man2/fanotify_mark.2
> @@ -659,17 +659,16 @@ The filesystem object indicated by
>  .I dirfd
>  and
>  .I pathname
> -is not associated with a filesystem that supports
> +is associated with a filesystem that reports zero
>  .I fsid
>  (e.g.,
>  .BR fuse (4)).
> -.BR tmpfs (5)
> -did not support
> -.I fsid
> -prior to Linux 5.13.
> -.\" commit 59cda49ecf6c9a32fae4942420701b6e087204f6
>  This error can be returned only with an fanotify group that identifies
>  filesystem objects by file handles.
> +Since Linux 6.8,
> +.\" commit 30ad1938326bf9303ca38090339d948975a626f5
> +this error can be returned only when
> +trying to add a mount or filesystem mark.
>  .TP
>  .B ENOENT
>  The filesystem object indicated by
> @@ -768,6 +767,22 @@ which uses a different
>  than its root superblock.
>  This error can be returned only with an fanotify group that identifies
>  filesystem objects by file handles.
> +Since Linux 6.8,
> +.\" commit 30ad1938326bf9303ca38090339d948975a626f5
> +this error will be returned
> +when trying to add a mount or filesystem mark on a subvolume,
> +when trying to add inode marks in different subvolumes,
> +or when trying to add inode marks in a
> +.BR btrfs (5)
> +subvolume and in another filesystem.
> +Since Linux 6.8,
> +.\" commit 30ad1938326bf9303ca38090339d948975a626f5
> +this error will also be returned
> +when trying to add marks in different filesystems,
> +where one of the filesystems reports zero
> +.I fsid
> +(e.g.,
> +.BR fuse (4)).
>  .SH STANDARDS
>  Linux.
>  .SH HISTORY
> diff --git a/man/man7/fanotify.7 b/man/man7/fanotify.7
> index 449af949c..db8fe6c00 100644
> --- a/man/man7/fanotify.7
> +++ b/man/man7/fanotify.7
> @@ -575,6 +575,16 @@ and contains the same value as
>  .I f_fsid
>  when calling
>  .BR statfs (2).
> +Note that some filesystems (e.g.,
> +.BR fuse (4))
> +report zero
> +.IR fsid .
> +In these cases, it is not possible to use
> +.I fsid
> +to associate the event with a specific filesystem instance,
> +so monitoring different filesystem instances that report zero
> +.I fsid
> +with the same fanotify group is not supported.
>  .TP
>  .I handle
>  This field contains a variable-length structure of type
> -- 
> 2.34.1
> 
-- 
Jan Kara <jack@suse.com>
SUSE Labs, CR

Re: [PATCH] fanotify.7,fanotify_mark.2: update documentation of fanotify w.r.t fsid

[Amir Goldstein]

On Wed, Oct 9, 2024 at 5:38 PM Jan Kara <jack@suse.cz> wrote:
>
> On Tue 08-10-24 11:45:03, Amir Goldstein wrote:
> > Clarify the conditions for getting the -EXDEV and -ENODEV errors.
> >
> > Signed-off-by: Amir Goldstein <amir73il@gmail.com>
>
> Looks good. Feel free to add:
>
> Reviewed-by: Jan Kara <jack@suse.cz>
>
> But I've read somewhere that Alejandro stepped down as manpages maintainer
> so they are officially unmaintained?

Yes, I just caught up with this news.
Anyway, it's good to have the patch on the list.
I will be maintaining the fanotify man pages queue
until manpages are back to maintenance.

Thanks,
Amir.

Re: [PATCH] fanotify.7,fanotify_mark.2: update documentation of fanotify w.r.t fsid

[Alejandro Colomar]

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

Hi Amir, Jan,

On Wed, Oct 09, 2024 at 05:38:36PM +0200, Jan Kara wrote:
> On Tue 08-10-24 11:45:03, Amir Goldstein wrote:
> > Clarify the conditions for getting the -EXDEV and -ENODEV errors.
> > 
> > Signed-off-by: Amir Goldstein <amir73il@gmail.com>
> 
> Looks good. Feel free to add:

Please see some minor inline comments below.

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

Thanks!

> 
> But I've read somewhere that Alejandro stepped down as manpages maintainer
> so they are officially unmaintained?

A contract is imminent, and I've started to review/apply old patches
today already.  I'll probably make an official announcement soon.
Maintenance is restored.  (As much as I possibly can, since my region
has limited electricity, water, and internet, after the worst flooding
in centuries.)

Have a lovely day!
Alex

> 
> 								Honza
> 
> > Hi Alejandro,
> > 
> > This is a followup on fanotify changes from v6.8
> > that are forgot to follow up on at the time.
> > 
> > Thanks,
> > Amir.
> > 
> >  man/man2/fanotify_mark.2 | 27 +++++++++++++++++++++------
> >  man/man7/fanotify.7      | 10 ++++++++++
> >  2 files changed, 31 insertions(+), 6 deletions(-)
> > 
> > diff --git a/man/man2/fanotify_mark.2 b/man/man2/fanotify_mark.2
> > index fc9b83459..b5e091c25 100644
> > --- a/man/man2/fanotify_mark.2
> > +++ b/man/man2/fanotify_mark.2
> > @@ -659,17 +659,16 @@ The filesystem object indicated by
> >  .I dirfd
> >  and
> >  .I pathname
> > -is not associated with a filesystem that supports
> > +is associated with a filesystem that reports zero
> >  .I fsid
> >  (e.g.,
> >  .BR fuse (4)).
> > -.BR tmpfs (5)
> > -did not support
> > -.I fsid
> > -prior to Linux 5.13.
> > -.\" commit 59cda49ecf6c9a32fae4942420701b6e087204f6
> >  This error can be returned only with an fanotify group that identifies
> >  filesystem objects by file handles.
> > +Since Linux 6.8,
> > +.\" commit 30ad1938326bf9303ca38090339d948975a626f5
> > +this error can be returned only when

I think "when" is more appropriate in the following line.  It also adds
some consistency with the rest of the patch below (@@762).

> > +trying to add a mount or filesystem mark.
> >  .TP
> >  .B ENOENT
> >  The filesystem object indicated by
> > @@ -768,6 +767,22 @@ which uses a different
> >  than its root superblock.
> >  This error can be returned only with an fanotify group that identifies
> >  filesystem objects by file handles.
> > +Since Linux 6.8,
> > +.\" commit 30ad1938326bf9303ca38090339d948975a626f5
> > +this error will be returned
> > +when trying to add a mount or filesystem mark on a subvolume,
> > +when trying to add inode marks in different subvolumes,
> > +or when trying to add inode marks in a
> > +.BR btrfs (5)
> > +subvolume and in another filesystem.
> > +Since Linux 6.8,
> > +.\" commit 30ad1938326bf9303ca38090339d948975a626f5
> > +this error will also be returned
> > +when trying to add marks in different filesystems,
> > +where one of the filesystems reports zero
> > +.I fsid
> > +(e.g.,
> > +.BR fuse (4)).
> >  .SH STANDARDS
> >  Linux.
> >  .SH HISTORY
> > diff --git a/man/man7/fanotify.7 b/man/man7/fanotify.7
> > index 449af949c..db8fe6c00 100644
> > --- a/man/man7/fanotify.7
> > +++ b/man/man7/fanotify.7
> > @@ -575,6 +575,16 @@ and contains the same value as
> >  .I f_fsid
> >  when calling
> >  .BR statfs (2).
> > +Note that some filesystems (e.g.,
> > +.BR fuse (4))
> > +report zero
> > +.IR fsid .
> > +In these cases, it is not possible to use

Please break the line after the comma.

> > +.I fsid
> > +to associate the event with a specific filesystem instance,
> > +so monitoring different filesystem instances that report zero
> > +.I fsid
> > +with the same fanotify group is not supported.
> >  .TP
> >  .I handle
> >  This field contains a variable-length structure of type
> > -- 
> > 2.34.1
> > 
> -- 
> Jan Kara <jack@suse.com>
> SUSE Labs, CR

-- 
<https://www.alejandro-colomar.es/>

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

Re: [PATCH] fanotify.7,fanotify_mark.2: update documentation of fanotify w.r.t fsid

[Jan Kara]

Hi Alejandro!

On Fri 01-11-24 14:07:32, Alejandro Colomar wrote:
> On Wed, Oct 09, 2024 at 05:38:36PM +0200, Jan Kara wrote:
> > On Tue 08-10-24 11:45:03, Amir Goldstein wrote:
> > > Clarify the conditions for getting the -EXDEV and -ENODEV errors.
> > > 
> > > Signed-off-by: Amir Goldstein <amir73il@gmail.com>
> > 
> > Looks good. Feel free to add:
> 
> Please see some minor inline comments below.
> 
> > Reviewed-by: Jan Kara <jack@suse.cz>
> 
> Thanks!
> 
> > 
> > But I've read somewhere that Alejandro stepped down as manpages maintainer
> > so they are officially unmaintained?
> 
> A contract is imminent, and I've started to review/apply old patches
> today already.  I'll probably make an official announcement soon.

I'm happy to hear that!

> Maintenance is restored.  (As much as I possibly can, since my region
> has limited electricity, water, and internet, after the worst flooding
> in centuries.)

I've heard about huge floods in Spain. We had pretty bad ones a month and
half ago in Czech republic as well. But my area was only lightly affected.
Stay safe!
								Honza

-- 
Jan Kara <jack@suse.com>
SUSE Labs, CR