pipe.2: Add mention of O_NOTIFICATION_PIPE flag

This adds very basic information about the notification pipe that have
been added into Linux 5.8.

There is some description about the interface at:

https://www.kernel.org/doc/html/latest/core-api/watch_queue.html

(I think that there is at least on bug in that page, since the
notification pipe has to be opened with O_NOTIFICATION_PIPE which is
defined to O_EXCL not O_TMPFILE)

The ENOPKG error should be clear from this header (see
watch_queue_init() at the end):

https://github.com/torvalds/linux/blob/5bfc75d92efd494db37f5c4c173d3639d4772966/include/linux/watch_queue.h

Signed-off-by: Cyril Hrubis <chrubis@suse.cz>
Cc: David Howells <dhowells@redhat.com>
[alx: wsfix]
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>

diff --git a/man2/pipe.2 b/man2/pipe.2
index de50ee491f55660aa46d6bb58735109373f56baf..b0d466727ac52b3b80f9b39e5032771889783fae 100644 (file)
--- a/man2/pipe.2
+++ b/man2/pipe.2
@@ -132,6 +132,15 @@ referred to by the new file descriptors.
 Using this flag saves extra calls to
 .BR fcntl (2)
 to achieve the same result.
+.TP
+.B O_NOTIFICATION_PIPE
+Since Linux 5.8,
+.\" commit c73be61cede5882f9605a852414db559c0ebedfd
+general notification mechanism is built on the top of the pipe where
+kernel splices notification messages into pipes opened by user space.
+The owner of the pipe has to tell the kernel which sources of events to watch
+and filters can also be applied to select
+which subevents should be placed into the pipe.
 .SH RETURN VALUE
 On success, zero is returned.
 On error, \-1 is returned,
@@ -174,6 +183,15 @@ The system-wide limit on the total number of open files has been reached.
 The user hard limit on memory that can be allocated for pipes
 has been reached and the caller is not privileged; see
 .BR pipe (7).
+.TP
+.B ENOPKG
+.RB ( pipe2 ())
+.B O_NOTIFICATION_PIPE
+was passed in
+.I flags
+and support for notifications
+.RB ( CONFIG_WATCH_QUEUE )
+is not compiled into the kernel.
 .SH VERSIONS
 .BR pipe2 ()
 was added to Linux in version 2.6.27;