inotify.7: Document IN_MASK_CREATE

Add documentation for new flag IN_MASK_CREATE for inotify_add_watch()
which is used to only allow new watches to be created.

Information obtained from a patch I submitted to the linux kernel
https://marc.info/?l=linux-fsdevel&m=152775980422847&w=2

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

diff --git a/man7/inotify.7 b/man7/inotify.7
index 85c05a9bcd34262b31cbb8a4e87b9a87b822caac..873bc27bc9d19176098381514982900c02f7bafa 100644 (file)
--- a/man7/inotify.7
+++ b/man7/inotify.7
@@ -347,7 +347,12 @@ If a watch instance already exists for the filesystem object corresponding to
 .IR pathname ,
 add (OR) the events in
 .I mask
-to the watch mask (instead of replacing the mask).
+to the watch mask (instead of replacing the mask);
+the error
+.B EINVAL
+results if
+.B IN_MASK_CREATE
+is also specified.
 .TP
 .B IN_ONESHOT
 Monitor the filesystem object corresponding to
@@ -366,6 +371,22 @@ results if
 is not a directory.
 Using this flag provides an application with a race-free way of
 ensuring that the monitored object is a directory.
+.TP
+.BR IN_MASK_CREATE " (from Linux 4.18)"
+Watch
+.I pathname
+only if it does not already have a watch associated with it;
+the error
+.B EEXIST
+results if
+.I pathname
+already is being watched.
+Using this flag provides an application with a way of ensuring
+that new watches do not modify existing ones. This is useful
+because multiple paths may refer to the same inode, and
+multiple calls to
+.B inotify_add_watch (2)
+without this flag may clobber existing watch masks.
 .RE
 .PP
 The following bits may be set in the