Skip to contentSkip to conversation

fanotify_mark.2: Document FAN_MARK_EVICTABLE

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

lore
Share & tools
lore
#0 lore raw

PATCH v2 1/1 fanotify_mark.2: Document FAN_MARK_EVICTABLE

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

---

Hi Alex,

Here is v2 with fixes to your review comments
and Jan's Reviewed-by.

Thanks,
Amir.

 man2/fanotify_mark.2 | 53 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)
man2/fanotify_mark.2 +53 -0
index 2696a803a..b9b3357e2 100644
@@ -152,6 +152,47 @@ 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.
+.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 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 .
+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).
@@ -409,6 +450,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
Signature · 1 line
2.25.1
#1 lore raw

Hi Amir,

Quoted 6 lines · Amir Goldstein

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

I applied the patch.

Thanks,
Alex

Quoted 84 lines

---

Hi Alex,

Here is v2 with fixes to your review comments
and Jan's Reviewed-by.

Thanks,
Amir.

  man2/fanotify_mark.2 | 53 ++++++++++++++++++++++++++++++++++++++++++++
  1 file changed, 53 insertions(+)
man2/fanotify_mark.2 +53 -0
index 2696a803a..b9b3357e2 100644
@@ -152,6 +152,47 @@ 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.
+.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 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 .
+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).
@@ -409,6 +450,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
Signature · 2 lines
Alejandro Colomar
<http://www.alejandro-colomar.es/>