[PATCH] fanotify_mark.2: Document FAN_MARK_EVICTABLE

[PATCH] fanotify_mark.2: Document FAN_MARK_EVICTABLE

[Amir Goldstein]

Add section about evictable inode marks and example use case.
Add possible error case EEXIST related to evictable marks.

Reviewed-by: Matthew Bobrowski <repnop@google.com>
Signed-off-by: Amir Goldstein <amir73il@gmail.com>
---

Hi Alex,

This is an update for a new fanotify feature in v5.19.
Please wait to see if Jan has any commetns before merging.

Thanks,
Amir.

 man2/fanotify_mark.2 | 50 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)

diff --git a/man2/fanotify_mark.2 b/man2/fanotify_mark.2
index 2696a803a..757ad9159 100644
--- a/man2/fanotify_mark.2
+++ b/man2/fanotify_mark.2
@@ -153,6 +153,44 @@ If this flag is not set,
 the ignore mask is cleared when a modify event occurs
 for the ignored file or directory.
 .PP
+.TP
+.BR FAN_MARK_EVICTABLE " (since Linux 5.19)"
+.\" commit 5f9d3bd520261fd7a850818c71809fd580e0f30c
+When an inode mark is created with this flag,
+the inode object will not be pinned to the inode cache.
+Therefore, allowing the inode object to be evicted from the inode cache
+when the memory pressure on the system is high.
+The eviction of the inode object results in the evictable mark also
+being lost.
+When the mask of an evictable inode mark is updated
+without using the
+.B FAN_MARK_EVICATBLE
+flag,
+the marked inode is pinned to inode cache
+and the mark is no longer evictable.
+When the mask of a non-evictable inode mark is updated
+with the
+.B FAN_MARK_EVICTABLE
+flag,
+the inode mark remains non-evictable
+and the update fails with
+.B EEXIST
+error.
+Mounts and filesystems are not evictable,
+so an attempt to create an evictable mount or filesystem mark
+will results with
+.B EINVAL
+error.
+For example,
+inode marks can be used in combination with mount marks
+to reduce the amount of events from noninteresting paths.
+The event listener reads events,
+checks if the path reported in the event is of interest
+and if it is not,
+the listener sets a mark with an ignore mask on the directory.
+Evictable inode marks allow using this method for a large number of directories
+without the concern of pinning all inodes and exhausting the system's memory.
+.PP
 .I mask
 defines which events shall be listened for (or which shall be ignored).
 It is a bit mask composed of the following values:
@@ -409,6 +447,18 @@ is neither
 .B AT_FDCWD
 nor a valid file descriptor.
 .TP
+.B EEXIST
+The filesystem object indicated by
+.I dirfd
+and
+.I pathname
+has a mark that was updated without the
+.B FAN_MARK_EVICTABLE
+flag,
+and the user attempted to update the mark with
+.B FAN_MARK_EVICTABLE
+flag.
+.TP
 .B EINVAL
 An invalid value was passed in
 .I flags
-- 
2.25.1

Re: [PATCH] fanotify_mark.2: Document FAN_MARK_EVICTABLE

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 4134 bytes --]

Hi Amir,

On 9/4/22 17:46, Amir Goldstein wrote:
> Add section about evictable inode marks and example use case.
> Add possible error case EEXIST related to evictable marks.
> 
> Reviewed-by: Matthew Bobrowski <repnop@google.com>
> Signed-off-by: Amir Goldstein <amir73il@gmail.com>
> ---
> 
> Hi Alex,
> 
> This is an update for a new fanotify feature in v5.19.
> Please wait to see if Jan has any commetns before merging.

Sure.  Also, please check some comments of mine below.

Cheers,

Alex

> 
> Thanks,
> Amir.
> 
>   man2/fanotify_mark.2 | 50 ++++++++++++++++++++++++++++++++++++++++++++
>   1 file changed, 50 insertions(+)
> 
> diff --git a/man2/fanotify_mark.2 b/man2/fanotify_mark.2
> index 2696a803a..757ad9159 100644
> --- a/man2/fanotify_mark.2
> +++ b/man2/fanotify_mark.2
> @@ -153,6 +153,44 @@ If this flag is not set,
>   the ignore mask is cleared when a modify event occurs
>   for the ignored file or directory.
>   .PP
> +.TP

.PP followed by another paragraph macro is a no-op.  Remove .PP above.

Check the 'Paragraph macros' subsection in groff_man(7) for more details.

$ man groff_man
/^...Paragraph macros

> +.BR FAN_MARK_EVICTABLE " (since Linux 5.19)"
> +.\" commit 5f9d3bd520261fd7a850818c71809fd580e0f30c
> +When an inode mark is created with this flag,
> +the inode object will not be pinned to the inode cache.
> +Therefore, allowing the inode object to be evicted from the inode cache

I think 'Therefore' should continue the last sentence and be separated 
by ',' or ';' instead of '.', and possibly removing the ',' after it.

> +when the memory pressure on the system is high.
> +The eviction of the inode object results in the evictable mark also
> +being lost.

Please rewrap the sentence above according to semantic newlines.

man-pages(7):
    Use semantic newlines
        In the source of a manual page, new sentences  should  be
        started on new lines, long sentences should be split into
        lines  at  clause breaks (commas, semicolons, colons, and
        so on), and long clauses should be split at phrase bound‐
        aries.  This convention,  sometimes  known  as  "semantic
        newlines",  makes it easier to see the effect of patches,
        which often operate at the level of individual sentences,
        clauses, or phrases.


> +When the mask of an evictable inode mark is updated
> +without using the
> +.B FAN_MARK_EVICATBLE
> +flag,
> +the marked inode is pinned to inode cache
> +and the mark is no longer evictable.
> +When the mask of a non-evictable inode mark is updated
> +with the
> +.B FAN_MARK_EVICTABLE
> +flag,
> +the inode mark remains non-evictable
> +and the update fails with
> +.B EEXIST
> +error.
> +Mounts and filesystems are not evictable,
> +so an attempt to create an evictable mount or filesystem mark
> +will results with

Some rewording needed ni the sentence above.

> +.B EINVAL
> +error.
> +For example,
> +inode marks can be used in combination with mount marks
> +to reduce the amount of events from noninteresting paths.
> +The event listener reads events,
> +checks if the path reported in the event is of interest

s/$/,/

> +and if it is not,
> +the listener sets a mark with an ignore mask on the directory.
> +Evictable inode marks allow using this method for a large number of directories
> +without the concern of pinning all inodes and exhausting the system's memory.
> +.PP
>   .I mask
>   defines which events shall be listened for (or which shall be ignored).
>   It is a bit mask composed of the following values:
> @@ -409,6 +447,18 @@ is neither
>   .B AT_FDCWD
>   nor a valid file descriptor.
>   .TP
> +.B EEXIST
> +The filesystem object indicated by
> +.I dirfd
> +and
> +.I pathname
> +has a mark that was updated without the
> +.B FAN_MARK_EVICTABLE
> +flag,
> +and the user attempted to update the mark with
> +.B FAN_MARK_EVICTABLE
> +flag.
> +.TP
>   .B EINVAL
>   An invalid value was passed in
>   .I flags

-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>

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

Re: [PATCH] fanotify_mark.2: Document FAN_MARK_EVICTABLE

[Amir Goldstein]

On Mon, Sep 5, 2022 at 11:10 PM Alejandro Colomar
<alx.manpages@gmail.com> wrote:
>
> Hi Amir,
>
> On 9/4/22 17:46, Amir Goldstein wrote:
> > Add section about evictable inode marks and example use case.
> > Add possible error case EEXIST related to evictable marks.
> >
> > Reviewed-by: Matthew Bobrowski <repnop@google.com>
> > Signed-off-by: Amir Goldstein <amir73il@gmail.com>
> > ---
> >
> > Hi Alex,
> >
> > This is an update for a new fanotify feature in v5.19.
> > Please wait to see if Jan has any commetns before merging.
>
> Sure.  Also, please check some comments of mine below.
>
> Cheers,
>
> Alex
>
> >
> > Thanks,
> > Amir.
> >
> >   man2/fanotify_mark.2 | 50 ++++++++++++++++++++++++++++++++++++++++++++
> >   1 file changed, 50 insertions(+)
> >
> > diff --git a/man2/fanotify_mark.2 b/man2/fanotify_mark.2
> > index 2696a803a..757ad9159 100644
> > --- a/man2/fanotify_mark.2
> > +++ b/man2/fanotify_mark.2
> > @@ -153,6 +153,44 @@ If this flag is not set,
> >   the ignore mask is cleared when a modify event occurs
> >   for the ignored file or directory.
> >   .PP
> > +.TP
>
> .PP followed by another paragraph macro is a no-op.  Remove .PP above.
>
> Check the 'Paragraph macros' subsection in groff_man(7) for more details.
>
> $ man groff_man
> /^...Paragraph macros
>
> > +.BR FAN_MARK_EVICTABLE " (since Linux 5.19)"
> > +.\" commit 5f9d3bd520261fd7a850818c71809fd580e0f30c
> > +When an inode mark is created with this flag,
> > +the inode object will not be pinned to the inode cache.
> > +Therefore, allowing the inode object to be evicted from the inode cache
>
> I think 'Therefore' should continue the last sentence and be separated
> by ',' or ';' instead of '.', and possibly removing the ',' after it.
>
> > +when the memory pressure on the system is high.
> > +The eviction of the inode object results in the evictable mark also
> > +being lost.
>
> Please rewrap the sentence above according to semantic newlines.
>
> man-pages(7):
>     Use semantic newlines
>         In the source of a manual page, new sentences  should  be
>         started on new lines, long sentences should be split into
>         lines  at  clause breaks (commas, semicolons, colons, and
>         so on), and long clauses should be split at phrase bound‐
>         aries.  This convention,  sometimes  known  as  "semantic
>         newlines",  makes it easier to see the effect of patches,
>         which often operate at the level of individual sentences,
>         clauses, or phrases.
>
>
> > +When the mask of an evictable inode mark is updated
> > +without using the
> > +.B FAN_MARK_EVICATBLE
> > +flag,
> > +the marked inode is pinned to inode cache
> > +and the mark is no longer evictable.
> > +When the mask of a non-evictable inode mark is updated
> > +with the
> > +.B FAN_MARK_EVICTABLE
> > +flag,
> > +the inode mark remains non-evictable
> > +and the update fails with
> > +.B EEXIST
> > +error.
> > +Mounts and filesystems are not evictable,
> > +so an attempt to create an evictable mount or filesystem mark
> > +will results with
>
> Some rewording needed ni the sentence above.

How's this:

Mounts and filesystems are not evictable objects,
therefore,
an attempt to create a mount mark or a filesystem mark
with the
.B FAN_MARK_EVICTABLE
flag,
will result in the error
.BR EINVAL .

Thanks for the review,
Amir.

Re: [PATCH] fanotify_mark.2: Document FAN_MARK_EVICTABLE

[Jan Kara]

On Sun 04-09-22 18:46:39, Amir Goldstein wrote:
> Add section about evictable inode marks and example use case.
> Add possible error case EEXIST related to evictable marks.
> 
> Reviewed-by: Matthew Bobrowski <repnop@google.com>
> Signed-off-by: Amir Goldstein <amir73il@gmail.com>
> ---
> 
> Hi Alex,
> 
> This is an update for a new fanotify feature in v5.19.
> Please wait to see if Jan has any commetns before merging.

Besides the mistakes Alejandro already found the patch looks good to me.

								Honza
> 
> Thanks,
> Amir.
> 
>  man2/fanotify_mark.2 | 50 ++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 50 insertions(+)
> 
> diff --git a/man2/fanotify_mark.2 b/man2/fanotify_mark.2
> index 2696a803a..757ad9159 100644
> --- a/man2/fanotify_mark.2
> +++ b/man2/fanotify_mark.2
> @@ -153,6 +153,44 @@ If this flag is not set,
>  the ignore mask is cleared when a modify event occurs
>  for the ignored file or directory.
>  .PP
> +.TP
> +.BR FAN_MARK_EVICTABLE " (since Linux 5.19)"
> +.\" commit 5f9d3bd520261fd7a850818c71809fd580e0f30c
> +When an inode mark is created with this flag,
> +the inode object will not be pinned to the inode cache.
> +Therefore, allowing the inode object to be evicted from the inode cache
> +when the memory pressure on the system is high.
> +The eviction of the inode object results in the evictable mark also
> +being lost.
> +When the mask of an evictable inode mark is updated
> +without using the
> +.B FAN_MARK_EVICATBLE
> +flag,
> +the marked inode is pinned to inode cache
> +and the mark is no longer evictable.
> +When the mask of a non-evictable inode mark is updated
> +with the
> +.B FAN_MARK_EVICTABLE
> +flag,
> +the inode mark remains non-evictable
> +and the update fails with
> +.B EEXIST
> +error.
> +Mounts and filesystems are not evictable,
> +so an attempt to create an evictable mount or filesystem mark
> +will results with
> +.B EINVAL
> +error.
> +For example,
> +inode marks can be used in combination with mount marks
> +to reduce the amount of events from noninteresting paths.
> +The event listener reads events,
> +checks if the path reported in the event is of interest
> +and if it is not,
> +the listener sets a mark with an ignore mask on the directory.
> +Evictable inode marks allow using this method for a large number of directories
> +without the concern of pinning all inodes and exhausting the system's memory.
> +.PP
>  .I mask
>  defines which events shall be listened for (or which shall be ignored).
>  It is a bit mask composed of the following values:
> @@ -409,6 +447,18 @@ is neither
>  .B AT_FDCWD
>  nor a valid file descriptor.
>  .TP
> +.B EEXIST
> +The filesystem object indicated by
> +.I dirfd
> +and
> +.I pathname
> +has a mark that was updated without the
> +.B FAN_MARK_EVICTABLE
> +flag,
> +and the user attempted to update the mark with
> +.B FAN_MARK_EVICTABLE
> +flag.
> +.TP
>  .B EINVAL
>  An invalid value was passed in
>  .I flags
> -- 
> 2.25.1
> 
-- 
Jan Kara <jack@suse.com>
SUSE Labs, CR

Re: [PATCH] fanotify_mark.2: Document FAN_MARK_EVICTABLE

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 3780 bytes --]

Hi Amir,

On 9/6/22 08:00, Amir Goldstein wrote:
> On Mon, Sep 5, 2022 at 11:10 PM Alejandro Colomar
> <alx.manpages@gmail.com> wrote:
>>
>> Hi Amir,
>>
>> On 9/4/22 17:46, Amir Goldstein wrote:
>>> Add section about evictable inode marks and example use case.
>>> Add possible error case EEXIST related to evictable marks.
>>>
>>> Reviewed-by: Matthew Bobrowski <repnop@google.com>
>>> Signed-off-by: Amir Goldstein <amir73il@gmail.com>
>>> ---
>>>
>>> Hi Alex,
>>>
>>> This is an update for a new fanotify feature in v5.19.
>>> Please wait to see if Jan has any commetns before merging.
>>
>> Sure.  Also, please check some comments of mine below.
>>
>> Cheers,
>>
>> Alex
>>
>>>
>>> Thanks,
>>> Amir.
>>>
>>>    man2/fanotify_mark.2 | 50 ++++++++++++++++++++++++++++++++++++++++++++
>>>    1 file changed, 50 insertions(+)
>>>
>>> diff --git a/man2/fanotify_mark.2 b/man2/fanotify_mark.2
>>> index 2696a803a..757ad9159 100644
>>> --- a/man2/fanotify_mark.2
>>> +++ b/man2/fanotify_mark.2
>>> @@ -153,6 +153,44 @@ If this flag is not set,
>>>    the ignore mask is cleared when a modify event occurs
>>>    for the ignored file or directory.
>>>    .PP
>>> +.TP
>>
>> .PP followed by another paragraph macro is a no-op.  Remove .PP above.
>>
>> Check the 'Paragraph macros' subsection in groff_man(7) for more details.
>>
>> $ man groff_man
>> /^...Paragraph macros
>>
>>> +.BR FAN_MARK_EVICTABLE " (since Linux 5.19)"
>>> +.\" commit 5f9d3bd520261fd7a850818c71809fd580e0f30c
>>> +When an inode mark is created with this flag,
>>> +the inode object will not be pinned to the inode cache.
>>> +Therefore, allowing the inode object to be evicted from the inode cache
>>
>> I think 'Therefore' should continue the last sentence and be separated
>> by ',' or ';' instead of '.', and possibly removing the ',' after it.
>>
>>> +when the memory pressure on the system is high.
>>> +The eviction of the inode object results in the evictable mark also
>>> +being lost.
>>
>> Please rewrap the sentence above according to semantic newlines.
>>
>> man-pages(7):
>>      Use semantic newlines
>>          In the source of a manual page, new sentences  should  be
>>          started on new lines, long sentences should be split into
>>          lines  at  clause breaks (commas, semicolons, colons, and
>>          so on), and long clauses should be split at phrase bound‐
>>          aries.  This convention,  sometimes  known  as  "semantic
>>          newlines",  makes it easier to see the effect of patches,
>>          which often operate at the level of individual sentences,
>>          clauses, or phrases.
>>
>>
>>> +When the mask of an evictable inode mark is updated
>>> +without using the
>>> +.B FAN_MARK_EVICATBLE
>>> +flag,
>>> +the marked inode is pinned to inode cache
>>> +and the mark is no longer evictable.
>>> +When the mask of a non-evictable inode mark is updated
>>> +with the
>>> +.B FAN_MARK_EVICTABLE
>>> +flag,
>>> +the inode mark remains non-evictable
>>> +and the update fails with
>>> +.B EEXIST
>>> +error.
>>> +Mounts and filesystems are not evictable,
>>> +so an attempt to create an evictable mount or filesystem mark
>>> +will results with
>>
>> Some rewording needed ni the sentence above.
> 
> How's this:
> 
> Mounts and filesystems are not evictable objects,
> therefore,
> an attempt to create a mount mark or a filesystem mark
> with the
> .B FAN_MARK_EVICTABLE
> flag,
> will result in the error
> .BR EINVAL .
> 
> Thanks for the review,
> Amir.

Yeah, that makes sense to me.

I'll review your v2 soon.  Or do you plan an v3 after Jan's email?

Cheers,

Alex

-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>

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