Skip to contentSkip to conversation

pipe.2: Add mention of O_NOTIFICATION_PIPE flag

PATCH In review [email protected] 2 participants 2 messages Jun 8, 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 pipe.2: Add mention of O_NOTIFICATION_PIPE flag

From: Cyril Hrubis <[email protected]>

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

---
 man2/pipe.2 | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)
man2/pipe.2 +18 -0
index 41a482f37..bd01b8da0 100644
@@ -149,6 +149,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,
@@ -191,6 +200,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;
Signature · 1 line
2.35.1
#1 lore raw

Hi Cyril,

Quoted 13 lines · On 6/8/22 14:46, [email protected] wrote:

From: Cyril Hrubis <[email protected]>

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)

Quoted 6 lines

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

Thanks for the patch. Applied.

Cheers,

Alex

Quoted 40 lines
---
  man2/pipe.2 | 18 ++++++++++++++++++
  1 file changed, 18 insertions(+)
man2/pipe.2 +18 -0
index 41a482f37..bd01b8da0 100644
@@ -149,6 +149,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,
@@ -191,6 +200,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;
Signature · 3 lines
Alejandro Colomar
Linux man-pages comaintainer; http://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/