Skip to contentSkip to conversation

fanotify_mark.2: Document FAN_MARK_IGNORE

RFC PATCH Superseded Amir Goldstein 3 participants 8 messages Sep 4, 2022 – Sep 8, 2022 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

v1 of 2 Superseded Latest is v2 →

lore
Share & tools
lore
#0 lore raw

RFC PATCH 1/1 fanotify_mark.2: Document FAN_MARK_IGNORE

A new flavor of FAN_MARK_IGNORED_MASK that helps to resolve the ambiguity around the combination of event flags and ignore mask.

It is also more strict in the events and flags allowed to be set in a non-directory inode mark mask and it mandates the use of FAN_MARK_IGNORED_SURV_MODIFY flag on filesystem, mount and directory inode marks.

---

Hi Alex,

This is an update for a new fanotify feature merged to v6.0-rc1. I am posting this man page update for early review.

You would probably want to wait for v6.0 release before merging this anyway.

Thanks,
Amir.

 man2/fanotify_mark.2 | 147 ++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 146 insertions(+), 1 deletion(-)
man2/fanotify_mark.2 +146 -1
index 757ad9159..e9303827c 100644
@@ -146,12 +146,102 @@ capability.
 The events in
 .I mask
 shall be added to or removed from the ignore mask.
+Note that the flags
+.B FAN_ONDIR ,
+and
+.B FAN_EVENT_ON_CHILD
+have no effect in combination with this flag.
+The effect of setting those flags in the mask
+on ignoring events that are set in the ignore mask
+is undefined and depend on the Linux kernel version.
+Specifically, prior to Linux 5.9,
+.\" commit 497b0c5a7c0688c1b100a9c2e267337f677c198e
+setting a mark mask on a file
+and a mark with ignore mask on its parent directory
+would not result in ignoring events on the file,
+regardless of the
+.B FAN_EVENT_ON_CHILD
+flag in the parent directory's mark mask.
+When the ignore mask is updated with the
+.B FAN_MARK_IGNORED_MASK
+flag,
+on a mark that was previously updated with the
+.B FAN_MARK_IGNORE
+flag,
+the update fails with
+.B EEXIST
+error.
+.TP
+.BR FAN_MARK_IGNORE " (since Linux 6.0)"
+.\" commit e252f2ed1c8c6c3884ab5dd34e003ed21f1fe6e0
+This flag has a similar effect as setting the
+.B FAN_MARK_IGNORED_MASK
+flag.
+The events in
+.I mask
+shall be added to or removed from the ignore mask.
+Unlike the
+.B FAN_MARK_IGNORED_MASK
+flag,
+this flag also has the effect that the
+.B FAN_ONDIR ,
+and
+.B FAN_EVENT_ON_CHILD
+flags take effect on the ignore mask.
+Specifically, unless
+.B FAN_ONDIR
+flag is set with
+.BR FAN_MARK_IGNORE ,
+events on directories will not be ignored
+and if the flag
+.B FAN_EVENT_ON_CHILD
+is set,
+events on children will be ignored.
+For example,
+a mark on a directory with combination of
+a mask with
+.B FAN_CREATE
+event
+and
+.B FAN_ONDIR
+flag
+and an ignore mask with
+.B FAN_CREATE
+event
+and without
+.B FAN_ONDIR
+flag,
+will result in getting only events for creation of sub-directories.
+When using this flag to add to an ignore mask
+of a mount, filesystem, or directory inode mark,
+the
+.B FAN_MARK_IGNORED_SURV_MODIFY
+flag must be specified.
+Failure to do so will results with
+.B EINVAL
+or
+.B EISDIR
+error.
 .TP
 .B FAN_MARK_IGNORED_SURV_MODIFY
 The ignore mask shall survive modify events.
 If this flag is not set,
 the ignore mask is cleared when a modify event occurs
 for the ignored file or directory.
+This flag cannot be removed from a mark once set.
+When the ignore mask is updated without this flag,
+on a mark that was previously updated with the
+.B FAN_MARK_IGNORE
+and
+.B FAN_MARK_IGNORED_SURV_MODIFY
+flags,
+the update fails with
+.B EEXIST
+error.
+.TP
+.B FAN_MARK_IGNORE_SURV
+This is a synonym for
+.RB ( FAN_MARK_IGNORE | FAN_MARK_IGNORED_SURV_MODIFY ).
 .PP
 .TP
 .BR FAN_MARK_EVICTABLE " (since Linux 5.19)"
@@ -459,6 +549,32 @@ and the user attempted to update the mark with
 .B FAN_MARK_EVICTABLE
 flag.
 .TP
+.B EEXIST
+The filesystem object indicated by
+.I dirfd
+and
+.I pathname
+has a mark that was updated with the
+.B FAN_MARK_IGNORE
+flag,
+and the user attempted to update the mark with
+.B FAN_MARK_IGNORED_MASK
+flag.
+.TP
+.B EEXIST
+The filesystem object indicated by
+.I dirfd
+and
+.I pathname
+has a mark that was updated with the
+.B FAN_MARK_IGNORE
+and
+.B FAN_MARK_IGNORED_SURV_MODIFY
+flags,
+and the user attempted to update the mark only with
+.B FAN_MARK_IGNORE
+flag.
+.TP
 .B EINVAL
 An invalid value was passed in
 .I flags
@@ -484,8 +600,33 @@ but one or more event types specified in the
 .I mask
 require it.
 .TP
+.B EINVAL
+.I flags
+contains
+.BR FAN_MARK_IGNORE ,
+and either
+.B FAN_MARK_MOUNT
+or
+.BR FAN_MARK_FILESYSTEM ,
+but does not contain
+.BR FAN_MARK_IGNORED_SURV_MODIFY .
+.TP
+.B EISDIR
+.I flags
+contains
+.BR FAN_MARK_IGNORE ,
+and
+.BR FAN_MARK_IGNORED_SURV_MODIFY ,
+and
+.I dirfd
+and
+.I pathname
+specify a directory.
+.TP
 .B ENODEV
 The filesystem object indicated by
+.I dirfd
+and
 .I pathname
 is not associated with a filesystem that supports
 .I fsid
@@ -547,8 +688,12 @@ and
 do not specify a directory.
 .TP
 .B ENOTDIR
-The fanotify group was initialized with flag
+.I flags
+contains
+.BR FAN_MARK_IGNORE ,
+or the fanotify group was initialized with flag
 .BR FAN_REPORT_TARGET_FID ,
+and
 .I mask
 contains directory entry modification events
 (e.g.,
Signature · 1 line
2.25.1
#1 lore raw
Quoted 9 lines · Amir Goldstein

A new flavor of FAN_MARK_IGNORED_MASK that helps to resolve the ambiguity around the combination of event flags and ignore mask.

It is also more strict in the events and flags allowed to be set in a non-directory inode mark mask and it mandates the use of FAN_MARK_IGNORED_SURV_MODIFY flag on filesystem, mount and directory inode marks.

<snip>

Quoted 35 lines

+.BR FAN_MARK_IGNORE " (since Linux 6.0)" +.\" commit e252f2ed1c8c6c3884ab5dd34e003ed21f1fe6e0

man2/fanotify_mark.2 +33 -0
+This flag has a similar effect as setting the
+.B FAN_MARK_IGNORED_MASK
+flag.
+The events in
+.I mask
+shall be added to or removed from the ignore mask.
+Unlike the
+.B FAN_MARK_IGNORED_MASK
+flag,
+this flag also has the effect that the
+.B FAN_ONDIR ,
+and
+.B FAN_EVENT_ON_CHILD
+flags take effect on the ignore mask.
+Specifically, unless
+.B FAN_ONDIR
+flag is set with
+.BR FAN_MARK_IGNORE ,
+events on directories will not be ignored
+and if the flag
+.B FAN_EVENT_ON_CHILD
+is set,
+events on children will be ignored.
+For example,
+a mark on a directory with combination of
+a mask with
+.B FAN_CREATE
+event
+and
+.B FAN_ONDIR
+flag
+and an ignore mask with
+.B FAN_CREATE

man2/fanotify_mark.2 capability. · line 219

Quoted 10 lines
man2/fanotify_mark.2 +10 -0
+event
+and without
+.B FAN_ONDIR
+flag,
+will result in getting only events for creation of sub-directories.
+When using this flag to add to an ignore mask
+of a mount, filesystem, or directory inode mark,
+the
+.B FAN_MARK_IGNORED_SURV_MODIFY
+flag must be specified.

Perhaps a short rationaly why this flag is required would be good here?

Quoted 5 lines
man2/fanotify_mark.2 +5 -0
+Failure to do so will results with
+.B EINVAL
+or
+.B EISDIR
+error.

<snip>

man2/fanotify_mark.2 but one or more event types specified in the · line 619

Quoted 7 lines

+.TP
+.B EISDIR
+.I flags

man2/fanotify_mark.2 +4 -0
+contains
+.BR FAN_MARK_IGNORE ,
+and
+.BR FAN_MARK_IGNORED_SURV_MODIFY ,

I think it should rather be "but does not contain
FAN_MARK_IGNORED_SURV_MODIFY", shouldn't it?

man2/fanotify_mark.2 but one or more event types specified in the · line 624

Quoted 5 lines
man2/fanotify_mark.2 +5 -0
+and
+.I dirfd
+and
+.I pathname
+specify a directory.

Otherwise the changes look good to me.

Honza

Signature · 2 lines
Jan Kara <[email protected]>
SUSE Labs, CR
#2 lore raw
Quoted 53 lines · Jan Kara
Quoted 9 lines · Amir Goldstein

A new flavor of FAN_MARK_IGNORED_MASK that helps to resolve the ambiguity around the combination of event flags and ignore mask.

It is also more strict in the events and flags allowed to be set in a non-directory inode mark mask and it mandates the use of FAN_MARK_IGNORED_SURV_MODIFY flag on filesystem, mount and directory inode marks.

<snip>

Quoted 39 lines

+.BR FAN_MARK_IGNORE " (since Linux 6.0)" +.\" commit e252f2ed1c8c6c3884ab5dd34e003ed21f1fe6e0

man2/fanotify_mark.2 +37 -0
+This flag has a similar effect as setting the
+.B FAN_MARK_IGNORED_MASK
+flag.
+The events in
+.I mask
+shall be added to or removed from the ignore mask.
+Unlike the
+.B FAN_MARK_IGNORED_MASK
+flag,
+this flag also has the effect that the
+.B FAN_ONDIR ,
+and
+.B FAN_EVENT_ON_CHILD
+flags take effect on the ignore mask.
+Specifically, unless
+.B FAN_ONDIR
+flag is set with
+.BR FAN_MARK_IGNORE ,
+events on directories will not be ignored
+and if the flag
+.B FAN_EVENT_ON_CHILD
+is set,
+events on children will be ignored.
+For example,
+a mark on a directory with combination of
+a mask with
+.B FAN_CREATE
+event
+and
+.B FAN_ONDIR
+flag
+and an ignore mask with
+.B FAN_CREATE
+event
+and without
+.B FAN_ONDIR
+flag,
Quoted 8 lines

man2/fanotify_mark.2 capability. · line 219

Quoted 6 lines
man2/fanotify_mark.2 +6 -0
+will result in getting only events for creation of sub-directories.
+When using this flag to add to an ignore mask
+of a mount, filesystem, or directory inode mark,
+the
+.B FAN_MARK_IGNORED_SURV_MODIFY
+flag must be specified.

Perhaps a short rationaly why this flag is required would be good here?

Here is a bit much IMO.
I will add it to the next section.
How's that?

.B FAN_MARK_IGNORED_SURV_MODIFY
The ignore mask shall survive modify events. If this flag is not set,
the ignore mask is cleared when a modify event occurs
-for the ignored file or directory.
+on the marked object.
+Omitting this flag is typically used to suppress events +(e.g.,
+.BR FAN_OPEN )
+for a specific file,
+until that specific file's content has been modified. +It is far less useful to suppress events
+on an entire filesystem,
+or mount,
+or on all files inside a directory,
+until some file's content has been modified. +For this reason,
+the
+.B FAN_MARK_IGNORE
+flag requires the
+.B FAN_MARK_IGNORED_SURV_MODIFY
+flag on a mount,
+filesystem,
+or directory inode mark.
+This flag cannot be removed from a mark once set. +When the ignore mask is updated without this flag, +on a mark that was previously updated with the +.B FAN_MARK_IGNORE
+and
+.B FAN_MARK_IGNORED_SURV_MODIFY
+flags,
+the update fails with
+.B EEXIST
+error.
+.TP
+.B FAN_MARK_IGNORE_SURV
+This is a synonym for
+.RB ( FAN_MARK_IGNORE | FAN_MARK_IGNORED_SURV_MODIFY ).
.TP

Quoted 9 lines
Quoted 6 lines
man2/fanotify_mark.2 +5 -0
+Failure to do so will results with
+.B EINVAL
+or
+.B EISDIR
+error.

<snip>

Quoted 11 lines

man2/fanotify_mark.2 but one or more event types specified in the · line 619

Quoted 7 lines

+.TP
+.B EISDIR
+.I flags

man2/fanotify_mark.2 +4 -0
+contains
+.BR FAN_MARK_IGNORE ,
+and
+.BR FAN_MARK_IGNORED_SURV_MODIFY ,

I think it should rather be "but does not contain
FAN_MARK_IGNORED_SURV_MODIFY", shouldn't it?

Yes. Good catch!

Thanks,
Amir.

#3 lore raw
Quoted 96 lines · Amir Goldstein
Quoted 53 lines · Jan Kara
Quoted 9 lines · Amir Goldstein

A new flavor of FAN_MARK_IGNORED_MASK that helps to resolve the ambiguity around the combination of event flags and ignore mask.

It is also more strict in the events and flags allowed to be set in a non-directory inode mark mask and it mandates the use of FAN_MARK_IGNORED_SURV_MODIFY flag on filesystem, mount and directory inode marks.

<snip>

Quoted 39 lines

+.BR FAN_MARK_IGNORE " (since Linux 6.0)" +.\" commit e252f2ed1c8c6c3884ab5dd34e003ed21f1fe6e0

man2/fanotify_mark.2 +37 -0
+This flag has a similar effect as setting the
+.B FAN_MARK_IGNORED_MASK
+flag.
+The events in
+.I mask
+shall be added to or removed from the ignore mask.
+Unlike the
+.B FAN_MARK_IGNORED_MASK
+flag,
+this flag also has the effect that the
+.B FAN_ONDIR ,
+and
+.B FAN_EVENT_ON_CHILD
+flags take effect on the ignore mask.
+Specifically, unless
+.B FAN_ONDIR
+flag is set with
+.BR FAN_MARK_IGNORE ,
+events on directories will not be ignored
+and if the flag
+.B FAN_EVENT_ON_CHILD
+is set,
+events on children will be ignored.
+For example,
+a mark on a directory with combination of
+a mask with
+.B FAN_CREATE
+event
+and
+.B FAN_ONDIR
+flag
+and an ignore mask with
+.B FAN_CREATE
+event
+and without
+.B FAN_ONDIR
+flag,
Quoted 8 lines

man2/fanotify_mark.2 capability. · line 219

Quoted 6 lines
man2/fanotify_mark.2 +6 -0
+will result in getting only events for creation of sub-directories.
+When using this flag to add to an ignore mask
+of a mount, filesystem, or directory inode mark,
+the
+.B FAN_MARK_IGNORED_SURV_MODIFY
+flag must be specified.

Perhaps a short rationaly why this flag is required would be good here?

Here is a bit much IMO.
I will add it to the next section.
How's that?

.B FAN_MARK_IGNORED_SURV_MODIFY
The ignore mask shall survive modify events. If this flag is not set,
the ignore mask is cleared when a modify event occurs

(quoted diff) +24 -1
-for the ignored file or directory.
+on the marked object.
+Omitting this flag is typically used to suppress events
+(e.g.,
+.BR FAN_OPEN )
+for a specific file,
+until that specific file's content has been modified.
+It is far less useful to suppress events
+on an entire filesystem,
+or mount,
+or on all files inside a directory,
+until some file's content has been modified.
+For this reason,
+the
+.B FAN_MARK_IGNORE
+flag requires the
+.B FAN_MARK_IGNORED_SURV_MODIFY
+flag on a mount,
+filesystem,
+or directory inode mark.
+This flag cannot be removed from a mark once set.
+When the ignore mask is updated without this flag,
+on a mark that was previously updated with the
+.B FAN_MARK_IGNORE
+and

Review

Quoted 10 lines
(quoted diff) +9 -0
+.B FAN_MARK_IGNORED_SURV_MODIFY
+flags,
+the update fails with
+.B EEXIST
+error.
+.TP
+.B FAN_MARK_IGNORE_SURV
+This is a synonym for
+.RB ( FAN_MARK_IGNORE | FAN_MARK_IGNORED_SURV_MODIFY ).
 .TP

Yes, looks good.

Honza

Signature · 2 lines
Jan Kara <[email protected]>
SUSE Labs, CR
#4 lore raw
In reply to Amir Goldstein

Maybe some useful nits.

Quoted 5 lines · Amir Goldstein
man2/fanotify_mark.2 +0 -0
index 757ad9159..e9303827c 100644

man2/fanotify_mark.2 capability. · line 154

Quoted 9 lines
man2/fanotify_mark.2 +6 -0
@@ -146,12 +146,102 @@ capability.
 The events in
 .I mask
 shall be added to or removed from the ignore mask.
+Note that the flags
+.B FAN_ONDIR ,
+and
+.B FAN_EVENT_ON_CHILD
+have no effect in combination with this flag.
+The effect of setting those flags in the mask

Is there anything wrong with explicitly specifying the exact flags you're referring to here? Like, "is it those flags there?", or "is it those flags over there?". Oh wait, you mean "it is those flags there?".

I think it's best not describe flag usage and behavior of something based on spatial proximity.

man2/fanotify_mark.2 capability. · line 156

Quoted 2 lines
man2/fanotify_mark.2 +2 -0
+on ignoring events that are set in the ignore mask
+is undefined and depend on the Linux kernel version.

Reading this sentence made me a little confused at first. Just checking, what I understood was that the use of FAN_ONDIR or FAN_EVENT_ON_CHILD when setting the ignore mask via FAN_MARK_IGNORED_MASK leads to undefined behavior. Is my understanding correct?

man2/fanotify_mark.2 capability. · line 167

Quoted 11 lines
man2/fanotify_mark.2 +11 -0
+Specifically, prior to Linux 5.9,
+.\" commit 497b0c5a7c0688c1b100a9c2e267337f677c198e
+setting a mark mask on a file
+and a mark with ignore mask on its parent directory
+would not result in ignoring events on the file,
+regardless of the
+.B FAN_EVENT_ON_CHILD
+flag in the parent directory's mark mask.
+When the ignore mask is updated with the
+.B FAN_MARK_IGNORED_MASK
+flag,

I'd just allow this sentence to flow without the use of comma after flag.

Quoted 14 lines
man2/fanotify_mark.2 +14 -0
+on a mark that was previously updated with the
+.B FAN_MARK_IGNORE
+flag,
+the update fails with
+.B EEXIST
+error.
+.TP
+.BR FAN_MARK_IGNORE " (since Linux 6.0)"
+.\" commit e252f2ed1c8c6c3884ab5dd34e003ed21f1fe6e0
+This flag has a similar effect as setting the
+.B FAN_MARK_IGNORED_MASK
+flag.
+The events in
+.I mask

man2/fanotify_mark.2 capability. · line 191

Quoted 10 lines
man2/fanotify_mark.2 +10 -0
+shall be added to or removed from the ignore mask.
+Unlike the
+.B FAN_MARK_IGNORED_MASK
+flag,
+this flag also has the effect that the
+.B FAN_ONDIR ,
+and
+.B FAN_EVENT_ON_CHILD
+flags take effect on the ignore mask.
+Specifically, unless
			^
			the

man2/fanotify_mark.2 capability. · line 195

Quoted 4 lines
man2/fanotify_mark.2 +4 -0
+.B FAN_ONDIR
+flag is set with
+.BR FAN_MARK_IGNORE ,
+events on directories will not be ignored
					    ^
					    .

man2/fanotify_mark.2 capability. · line 196

Quoted 1 line
man2/fanotify_mark.2 +1 -0
+and if the flag

I'd start a new sentence here.

Quoted 8 lines
man2/fanotify_mark.2 +8 -0
+.B FAN_EVENT_ON_CHILD
+is set,
+events on children will be ignored.
+For example,
+a mark on a directory with combination of
+a mask with
+.B FAN_CREATE
+event

man2/fanotify_mark.2 capability. · line 214

Quoted 10 lines
man2/fanotify_mark.2 +10 -0
+and
+.B FAN_ONDIR
+flag
+and an ignore mask with
+.B FAN_CREATE
+event
+and without
+.B FAN_ONDIR
+flag,
+will result in getting only events for creation of sub-directories.

^
the

Quoted 8 lines
man2/fanotify_mark.2 +8 -0
+When using this flag to add to an ignore mask
+of a mount, filesystem, or directory inode mark,
+the
+.B FAN_MARK_IGNORED_SURV_MODIFY
+flag must be specified.
+Failure to do so will results with
+.B EINVAL
+or

man2/fanotify_mark.2 capability. · line 232

Quoted 10 lines
man2/fanotify_mark.2 +4 -0
+.B EISDIR
+error.
 .TP
 .B FAN_MARK_IGNORED_SURV_MODIFY
 The ignore mask shall survive modify events.
 If this flag is not set,
 the ignore mask is cleared when a modify event occurs
 for the ignored file or directory.
+This flag cannot be removed from a mark once set.
+When the ignore mask is updated without this flag,
						    ^

Don't think the comma is needed here.

Quoted 99 lines
man2/fanotify_mark.2 +68 -1
+on a mark that was previously updated with the
+.B FAN_MARK_IGNORE
+and
+.B FAN_MARK_IGNORED_SURV_MODIFY
+flags,
+the update fails with
+.B EEXIST
+error.
+.TP
+.B FAN_MARK_IGNORE_SURV
+This is a synonym for
+.RB ( FAN_MARK_IGNORE | FAN_MARK_IGNORED_SURV_MODIFY ).
 .PP
 .TP
 .BR FAN_MARK_EVICTABLE " (since Linux 5.19)"
@@ -459,6 +549,32 @@ and the user attempted to update the mark with
 .B FAN_MARK_EVICTABLE
 flag.
 .TP
+.B EEXIST
+The filesystem object indicated by
+.I dirfd
+and
+.I pathname
+has a mark that was updated with the
+.B FAN_MARK_IGNORE
+flag,
+and the user attempted to update the mark with
+.B FAN_MARK_IGNORED_MASK
+flag.
+.TP
+.B EEXIST
+The filesystem object indicated by
+.I dirfd
+and
+.I pathname
+has a mark that was updated with the
+.B FAN_MARK_IGNORE
+and
+.B FAN_MARK_IGNORED_SURV_MODIFY
+flags,
+and the user attempted to update the mark only with
+.B FAN_MARK_IGNORE
+flag.
+.TP
 .B EINVAL
 An invalid value was passed in
 .I flags
@@ -484,8 +600,33 @@ but one or more event types specified in the
 .I mask
 require it.
 .TP
+.B EINVAL
+.I flags
+contains
+.BR FAN_MARK_IGNORE ,
+and either
+.B FAN_MARK_MOUNT
+or
+.BR FAN_MARK_FILESYSTEM ,
+but does not contain
+.BR FAN_MARK_IGNORED_SURV_MODIFY .
+.TP
+.B EISDIR
+.I flags
+contains
+.BR FAN_MARK_IGNORE ,
+and
+.BR FAN_MARK_IGNORED_SURV_MODIFY ,
+and
+.I dirfd
+and
+.I pathname
+specify a directory.
+.TP
 .B ENODEV
 The filesystem object indicated by
+.I dirfd
+and
 .I pathname
 is not associated with a filesystem that supports
 .I fsid
@@ -547,8 +688,12 @@ and
 do not specify a directory.
 .TP
 .B ENOTDIR
-The fanotify group was initialized with flag
+.I flags
+contains
+.BR FAN_MARK_IGNORE ,
+or the fanotify group was initialized with flag
 .BR FAN_REPORT_TARGET_FID ,
+and
 .I mask
 contains directory entry modification events
 
Signature · 1 line
2.25.1

/M

#5 lore raw
Quoted 2 lines · Matthew Bobrowski

Maybe some useful nits.

Definitely useful.
Thanks!

Quoted 22 lines · Amir Goldstein
Quoted 5 lines
man2/fanotify_mark.2 +0 -0
index 757ad9159..e9303827c 100644

man2/fanotify_mark.2 capability. · line 154

Quoted 9 lines
man2/fanotify_mark.2 +6 -0
@@ -146,12 +146,102 @@ capability.
 The events in
 .I mask
 shall be added to or removed from the ignore mask.
+Note that the flags
+.B FAN_ONDIR ,
+and
+.B FAN_EVENT_ON_CHILD
+have no effect in combination with this flag.
+The effect of setting those flags in the mask

Is there anything wrong with explicitly specifying the exact flags you're referring to here? Like, "is it those flags there?", or "is it those flags over there?". Oh wait, you mean "it is those flags there?".

Quoted 3 lines

I think it's best not describe flag usage and behavior of something based on spatial proximity.

ok.

Quoted 4 lines

man2/fanotify_mark.2 capability. · line 156

Quoted 2 lines
man2/fanotify_mark.2 +2 -0
+on ignoring events that are set in the ignore mask
+is undefined and depend on the Linux kernel version.

Reading this sentence made me a little confused at first. Just

Yeh, it's a badly phrased sentence.
I tried to improve it a bit:

.B FAN_MARK_IGNORED_MASK
The events in
.I mask
shall be added to or removed from the ignore mask.
+Note that the flags
+.B FAN_ONDIR ,
+and
+.B FAN_EVENT_ON_CHILD
+have no effect in combination with this flag. +The effect of setting the flags
+.B FAN_ONDIR ,
+and
+.B FAN_EVENT_ON_CHILD
+in the mark mask
+on the events that are set in the ignore mask +is undefined and depends on the Linux kernel version. +Specifically, prior to Linux 5.9,

I would love to get suggestions for improvement.

Quoted 5 lines

checking, what I understood was that the use of FAN_ONDIR or FAN_EVENT_ON_CHILD when setting the ignore mask via FAN_MARK_IGNORED_MASK leads to undefined behavior. Is my understanding correct?

Not exactly.
Setting those flags in the ignore mask has no effect (as mentioned above).
Setting those flags in the mask has undefined behavior w.r.t whether the events on a directory or on a child will be ignored, when said events are in the ignore mask.

See the "Specifically" clause below.

Quoted 6 lines
Quoted 6 lines
man2/fanotify_mark.2 +6 -0
+Specifically, prior to Linux 5.9,
+.\" commit 497b0c5a7c0688c1b100a9c2e267337f677c198e
+setting a mark mask on a file
+and a mark with ignore mask on its parent directory
+would not result in ignoring events on the file,
+regardless of the
Quoted 8 lines

man2/fanotify_mark.2 capability. · line 167

Quoted 5 lines
man2/fanotify_mark.2 +5 -0
+.B FAN_EVENT_ON_CHILD
+flag in the parent directory's mark mask.
+When the ignore mask is updated with the
+.B FAN_MARK_IGNORED_MASK
+flag,

I'd just allow this sentence to flow without the use of comma after flag.

ok.

Quoted 19 lines
Quoted 19 lines
man2/fanotify_mark.2 +18 -0
+on a mark that was previously updated with the
+.B FAN_MARK_IGNORE
+flag,
+the update fails with
+.B EEXIST
+error.
+.TP
+.BR FAN_MARK_IGNORE " (since Linux 6.0)"
+.\" commit e252f2ed1c8c6c3884ab5dd34e003ed21f1fe6e0
+This flag has a similar effect as setting the
+.B FAN_MARK_IGNORED_MASK
+flag.
+The events in
+.I mask
+shall be added to or removed from the ignore mask.
+Unlike the
+.B FAN_MARK_IGNORED_MASK
+flag,
Quoted 9 lines

man2/fanotify_mark.2 capability. · line 191

Quoted 6 lines
man2/fanotify_mark.2 +6 -0
+this flag also has the effect that the
+.B FAN_ONDIR ,
+and
+.B FAN_EVENT_ON_CHILD
+flags take effect on the ignore mask.
+Specifically, unless
                        ^
                        the

ok.

Quoted 10 lines

man2/fanotify_mark.2 capability. · line 195

Quoted 4 lines
man2/fanotify_mark.2 +4 -0
+.B FAN_ONDIR
+flag is set with
+.BR FAN_MARK_IGNORE ,
+events on directories will not be ignored
                                            ^
                                            .

man2/fanotify_mark.2 capability. · line 196

Quoted 1 line
man2/fanotify_mark.2 +1 -0
+and if the flag

I'd start a new sentence here.

ok.

Quoted 13 lines
Quoted 13 lines
man2/fanotify_mark.2 +12 -0
+.B FAN_EVENT_ON_CHILD
+is set,
+events on children will be ignored.
+For example,
+a mark on a directory with combination of
+a mask with
+.B FAN_CREATE
+event
+and
+.B FAN_ONDIR
+flag
+and an ignore mask with
Quoted 8 lines

man2/fanotify_mark.2 capability. · line 214

Quoted 6 lines
man2/fanotify_mark.2 +6 -0
+.B FAN_CREATE
+event
+and without
+.B FAN_ONDIR
+flag,
+will result in getting only events for creation of sub-directories.
                                         ^
                                         the

ok.

Quoted 20 lines
Quoted 9 lines
man2/fanotify_mark.2 +8 -0
+When using this flag to add to an ignore mask
+of a mount, filesystem, or directory inode mark,
+the
+.B FAN_MARK_IGNORED_SURV_MODIFY
+flag must be specified.
+Failure to do so will results with
+.B EINVAL
+or

man2/fanotify_mark.2 capability. · line 232

Quoted 10 lines
man2/fanotify_mark.2 +4 -0
+.B EISDIR
+error.
 .TP
 .B FAN_MARK_IGNORED_SURV_MODIFY
 The ignore mask shall survive modify events.
 If this flag is not set,
 the ignore mask is cleared when a modify event occurs
 for the ignored file or directory.
+This flag cannot be removed from a mark once set.
+When the ignore mask is updated without this flag,
                                                    ^
Quoted 1 line

Don't think the comma is needed here.

ok.

FYI, I pushed the fixes to:

https://github.com/amir73il/man-pages/commits/fan_mark_ignore

If you want to review them there and provide your RVB, because I don't intend to post v2 before v6.0 release.

Thanks,
Amir.

Reviewed-by
#6 lore raw
Quoted 185 lines · Amir Goldstein
Quoted 2 lines · Matthew Bobrowski

Maybe some useful nits.

Definitely useful.
Thanks!

Quoted 22 lines · Amir Goldstein
Quoted 5 lines
man2/fanotify_mark.2 +0 -0
index 757ad9159..e9303827c 100644

man2/fanotify_mark.2 capability. · line 154

Quoted 9 lines
man2/fanotify_mark.2 +6 -0
@@ -146,12 +146,102 @@ capability.
 The events in
 .I mask
 shall be added to or removed from the ignore mask.
+Note that the flags
+.B FAN_ONDIR ,
+and
+.B FAN_EVENT_ON_CHILD
+have no effect in combination with this flag.
+The effect of setting those flags in the mask

Is there anything wrong with explicitly specifying the exact flags you're referring to here? Like, "is it those flags there?", or "is it those flags over there?". Oh wait, you mean "it is those flags there?".

Quoted 3 lines

I think it's best not describe flag usage and behavior of something based on spatial proximity.

ok.

Quoted 4 lines

man2/fanotify_mark.2 capability. · line 156

Quoted 2 lines
man2/fanotify_mark.2 +2 -0
+on ignoring events that are set in the ignore mask
+is undefined and depend on the Linux kernel version.

Reading this sentence made me a little confused at first. Just

Yeh, it's a badly phrased sentence.
I tried to improve it a bit:

.B FAN_MARK_IGNORED_MASK
The events in
.I mask
shall be added to or removed from the ignore mask.

man2/fanotify_mark.2 +13 -0
+Note that the flags
+.B FAN_ONDIR ,
+and
+.B FAN_EVENT_ON_CHILD
+have no effect in combination with this flag.
+The effect of setting the flags
+.B FAN_ONDIR ,
+and
+.B FAN_EVENT_ON_CHILD
+in the mark mask
+on the events that are set in the ignore mask
+is undefined and depends on the Linux kernel version.
+Specifically, prior to Linux 5.9,

I would love to get suggestions for improvement.

Quoted 5 lines

checking, what I understood was that the use of FAN_ONDIR or FAN_EVENT_ON_CHILD when setting the ignore mask via FAN_MARK_IGNORED_MASK leads to undefined behavior. Is my understanding correct?

Not exactly.
Setting those flags in the ignore mask has no effect (as mentioned above).
Setting those flags in the mask has undefined behavior w.r.t whether the events on a directory or on a child will be ignored, when said events are in the ignore mask.

See the "Specifically" clause below.

Quoted 6 lines
Quoted 6 lines
man2/fanotify_mark.2 +6 -0
+Specifically, prior to Linux 5.9,
+.\" commit 497b0c5a7c0688c1b100a9c2e267337f677c198e
+setting a mark mask on a file
+and a mark with ignore mask on its parent directory
+would not result in ignoring events on the file,
+regardless of the
Quoted 8 lines

man2/fanotify_mark.2 capability. · line 167

Quoted 5 lines
man2/fanotify_mark.2 +5 -0
+.B FAN_EVENT_ON_CHILD
+flag in the parent directory's mark mask.
+When the ignore mask is updated with the
+.B FAN_MARK_IGNORED_MASK
+flag,

I'd just allow this sentence to flow without the use of comma after flag.

ok.

Quoted 19 lines
Quoted 19 lines
man2/fanotify_mark.2 +18 -0
+on a mark that was previously updated with the
+.B FAN_MARK_IGNORE
+flag,
+the update fails with
+.B EEXIST
+error.
+.TP
+.BR FAN_MARK_IGNORE " (since Linux 6.0)"
+.\" commit e252f2ed1c8c6c3884ab5dd34e003ed21f1fe6e0
+This flag has a similar effect as setting the
+.B FAN_MARK_IGNORED_MASK
+flag.
+The events in
+.I mask
+shall be added to or removed from the ignore mask.
+Unlike the
+.B FAN_MARK_IGNORED_MASK
+flag,
Quoted 9 lines

man2/fanotify_mark.2 capability. · line 191

Quoted 6 lines
man2/fanotify_mark.2 +6 -0
+this flag also has the effect that the
+.B FAN_ONDIR ,
+and
+.B FAN_EVENT_ON_CHILD
+flags take effect on the ignore mask.
+Specifically, unless
                        ^
                        the

ok.

Quoted 10 lines

man2/fanotify_mark.2 capability. · line 195

Quoted 4 lines
man2/fanotify_mark.2 +4 -0
+.B FAN_ONDIR
+flag is set with
+.BR FAN_MARK_IGNORE ,
+events on directories will not be ignored
                                            ^
                                            .

man2/fanotify_mark.2 capability. · line 196

Quoted 1 line
man2/fanotify_mark.2 +1 -0
+and if the flag

I'd start a new sentence here.

ok.

Quoted 13 lines
Quoted 13 lines
man2/fanotify_mark.2 +12 -0
+.B FAN_EVENT_ON_CHILD
+is set,
+events on children will be ignored.
+For example,
+a mark on a directory with combination of
+a mask with
+.B FAN_CREATE
+event
+and
+.B FAN_ONDIR
+flag
+and an ignore mask with
Quoted 8 lines

man2/fanotify_mark.2 capability. · line 214

Quoted 6 lines
man2/fanotify_mark.2 +6 -0
+.B FAN_CREATE
+event
+and without
+.B FAN_ONDIR
+flag,
+will result in getting only events for creation of sub-directories.
                                         ^
                                         the

ok.

Quoted 20 lines
Quoted 9 lines
man2/fanotify_mark.2 +8 -0
+When using this flag to add to an ignore mask
+of a mount, filesystem, or directory inode mark,
+the
+.B FAN_MARK_IGNORED_SURV_MODIFY
+flag must be specified.
+Failure to do so will results with
+.B EINVAL
+or

man2/fanotify_mark.2 capability. · line 232

Quoted 10 lines
man2/fanotify_mark.2 +4 -0
+.B EISDIR
+error.
 .TP
 .B FAN_MARK_IGNORED_SURV_MODIFY
 The ignore mask shall survive modify events.
 If this flag is not set,
 the ignore mask is cleared when a modify event occurs
 for the ignored file or directory.
+This flag cannot be removed from a mark once set.
+When the ignore mask is updated without this flag,
                                                    ^
Quoted 1 line

Don't think the comma is needed here.

Quoted 5 lines

ok.

FYI, I pushed the fixes to:

https://github.com/amir73il/man-pages/commits/fan_mark_ignore

One optional suggestion, but apart from that the refactoring LGTM.

/M