On Sat, Oct 8, 2022 at 2:43 AM Alejandro Colomar <alx.manpages@xxxxxxxxx> wrote: > > Hi Amir! > > On 10/7/22 08:13, Amir Goldstein wrote: > > 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. > > > > Reviewed-by: Jan Kara <jack@xxxxxxx> > > Reviewed-by: Matthew Bobrowski <repnop@xxxxxxxxxx> > > Signed-off-by: Amir Goldstein <amir73il@xxxxxxxxx> > > --- > > > > Hi Alex, > > > > This is the fanotify man page update for the 6.0 release. > > > > Thanks, > > Amir. > > > > Changes since [v1]: > > - Address review comments by Jan and Matthew > > > > [v1] https://lore.kernel.org/linux-man/20220904155113.2623371-1-amir73il@xxxxxxxxx/ > > Thanks! The semantic newline usage is very good! ;) > See some small formatting comments below. > > Cheers, > > Alex > > > > > man2/fanotify_mark.2 | 177 ++++++++++++++++++++++++++++++++++++++++++- > > 1 file changed, 175 insertions(+), 2 deletions(-) > > > > diff --git a/man2/fanotify_mark.2 b/man2/fanotify_mark.2 > > index b9b3357e2..f08ee2069 100644 > > --- a/man2/fanotify_mark.2 > > +++ b/man2/fanotify_mark.2 > > @@ -146,12 +146,130 @@ 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 when provided with this flag. > > +The effect of setting the flags > > +.B FAN_ONDIR , > > s/B/BR/ > > bold roman (alternating) > > > +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, > > +.\" 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 , > > bold roman > > > +and > > +.B FAN_EVENT_ON_CHILD > > +flags take effect on the ignore mask. > > +Specifically, unless the > > +.B FAN_ONDIR > > +flag is set with > > +.BR FAN_MARK_IGNORE , > > +events on directories will not be ignored. > > +If the flag > > +.B FAN_EVENT_ON_CHILD > > +is set with > > +.BR FAN_MARK_IGNORE , > > +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 > > +the events for creation of sub-directories. > > +When using the > > +.B FAN_MARK_IGNORE > > +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. > > +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 ). > > I'm not sure if I'd format this as code (italics) right?, > rather than separate constant names. > > Please check the below paragraphs from man-pages(7), > and I'll leave the decission up to you. > I kind of like it the way it is, which is also consistent with similar constructs in fanotify_init.2. Would you like me to post v3 for the 2 minor formatting fixes? Or will you make them on commit? Thanks, Amir.
