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

PATCH Superseded Amir Goldstein 3 participants 5 messages Oct 8, 2024 – Nov 1, 2024

Subsystems (2)

VFS Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore

Share & tools

lore

Amir Goldstein

author

2024-10-08 09:45 UTC #0 lore raw

PATCH 1/1 fanotify.7,fanotify_mark.2: update documentation of fanotify w.r.t fsid

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

Signed-off-by Amir Goldstein <[email protected]>

---

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

man/man2/fanotify_mark.2 +21 -6

index fc9b83459..b5e091c25 100644
@@ -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

man/man7/fanotify.7 +10 -0

index 449af949c..db8fe6c00 100644
@@ -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

Signature · 1 line

2.34.1

Jan Kara

reviewer Reviewed-by on v1 1/1

2024-10-09 15:39 UTC #1 lore raw

Quoted 3 lines · Amir Goldstein

Clarify the conditions for getting the -EXDEV and -ENODEV errors.
Signed-off-by Amir Goldstein <[email protected]>

Looks good. Feel free to add:

Reviewed-by Jan Kara <[email protected]>

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

Honza

Quoted 86 lines

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

man/man2/fanotify_mark.2 +21 -6

index fc9b83459..b5e091c25 100644
@@ -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

man/man7/fanotify.7 +10 -0

index 449af949c..db8fe6c00 100644
@@ -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

Signature · 1 line

2.34.1

Signature · 2 lines

Jan Kara <[email protected]>
SUSE Labs, CR

Amir Goldstein

author

2024-10-09 15:49 UTC #2 lore raw

Quoted 4 lines · Jan Kara

Quoted 2 lines · Amir Goldstein
Clarify the conditions for getting the -EXDEV and -ENODEV errors.

Quoted 8 lines

Quoted 1 line
Signed-off-by Amir Goldstein <[email protected]>
Looks good. Feel free to add:
Reviewed-by Jan Kara <[email protected]>
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.

Alejandro Colomar

maintainer

2024-11-01 13:07 UTC #3 lore raw

In reply to Jan Kara

Hi Amir, Jan,

Quoted 6 lines · Jan Kara

Quoted 3 lines · Amir Goldstein
Clarify the conditions for getting the -EXDEV and -ENODEV errors.
Signed-off-by Amir Goldstein <[email protected]>
Looks good. Feel free to add:

Please see some minor inline comments below.

Quoted 1 line

Reviewed-by Jan Kara <[email protected]>

Thanks!

Quoted 3 lines

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

Quoted 30 lines

Honza

Quoted 27 lines

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

man/man2/fanotify_mark.2 +1 -3

index fc9b83459..b5e091c25 100644
@@ -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

Quoted 8 lines

man/man2/fanotify_mark.2 The filesystem object indicated by · line 670

Quoted 8 lines

man/man2/fanotify_mark.2 +3 -3

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

Quoted 32 lines

man/man2/fanotify_mark.2 +17 -0

+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

man/man7/fanotify.7 +0 -0

index 449af949c..db8fe6c00 100644
@@ -575,6 +575,16 @@ and contains the same value as

Quoted 8 lines

man/man7/fanotify.7 and contains the same value as · line 582
Quoted 8 lines
man/man7/fanotify.7 +5 -0
 .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.

Quoted 14 lines

Quoted 11 lines

man/man7/fanotify.7 +5 -0

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

Signature · 1 line

2.34.1

Signature · 2 lines

Jan Kara <[email protected]>
SUSE Labs, CR

Signature · 1 line

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

Jan Kara

reviewer

2024-11-01 17:40 UTC #4 lore raw

Hi Alejandro!

Quoted 12 lines · Alejandro Colomar

Quoted 6 lines · Jan Kara
Quoted 3 lines · Amir Goldstein
Clarify the conditions for getting the -EXDEV and -ENODEV errors.
Signed-off-by Amir Goldstein <[email protected]>
Looks good. Feel free to add:
Please see some minor inline comments below.
Quoted 1 line
Reviewed-by Jan Kara <[email protected]>

Quoted 8 lines

Thanks!
Quoted 3 lines
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!

Quoted 3 lines

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

Signature · 2 lines

Jan Kara <[email protected]>
SUSE Labs, CR