Hello Cyril, On 1/26/22 14:17, chrubis@xxxxxxx wrote: > From: Cyril Hrubis <chrubis@xxxxxxx> > > 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/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 > > TODO: > > Where to place the info about the structures and ioctls()? Does that > belong into pipe.2 as well? We're documenting types in system_data_types(7). You could try there. Regarding ioctls(), there are a few pages. Maybe you could start a new one; I don't know. $ apropos ioctl console_ioctl (4) - ioctls for console terminal and virtual consoles ioctl (2) - control device ioctl_console (2) - ioctls for console terminal and virtual consoles ioctl_fat (2) - manipulating the FAT filesystem ioctl_ficlone (2) - share some the data of one file with another file ioctl_ficlonerange (2) - share some the data of one file with another file ioctl_fideduperange (2) - share some the data of one file with another file ioctl_fslabel (2) - get or set a filesystem label ioctl_getfsmap (2) - retrieve the physical layout of the filesystem ioctl_iflags (2) - ioctl() operations for inode flags ioctl_ns (2) - ioctl() operations for Linux namespaces ioctl_tty (2) - ioctls for terminals and serial lines ioctl_userfaultfd (2) - create a file descriptor for handling page faults in ... tty_ioctl (4) - ioctls for terminals and serial lines blockdev (8) - call block device ioctls from the command line f2fs_io (8) - f2fs ioctl utility ioctl (3posix) - control a STREAMS device (STREAMS) ioctl_list (2) - list of ioctl calls in Linux/i386 kernel use_tioctl (3ncurses) - miscellaneous curses utility routines use_tioctl_sp (3ncurses) - curses screen-pointer extension > > Signed-off-by: Cyril Hrubis <chrubis@xxxxxxx> > --- > man2/pipe.2 | 17 +++++++++++++++++ > 1 file changed, 17 insertions(+) > > diff --git a/man2/pipe.2 b/man2/pipe.2 > index 41a482f37..7d4db0323 100644 > --- a/man2/pipe.2 > +++ b/man2/pipe.2 > @@ -149,6 +149,14 @@ referred to by the new file descriptors. > Using this flag saves extra calls to > .BR fcntl (2) > to achieve the same result. > +.TP > +.BR O_NOTIFICATION_PIPE Use .B You don't need the 'R'. groff_man(7): .B Bold Font style macros .BI Bold, italic alternating Font style macros .BR Bold, roman alternating Font style macros > +Since Linux 5.8, > +.\" commit c73be61cede5882f9605a852414db559c0ebedfd > +general notification mechanims is build on the top of the pipe where kernel typo: mechanims typo: build > +splices notification messages into pipes opened by userspace. The owner of the Also: 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. Also: s/userspace/user space/ man-pages(7): Preferred terms The following table lists some preferred terms to use in man pages, mainly to ensure consistency across pages. Term Avoid using Notes ─────────────────────────────────────────────────────────── [...] user space userspace > +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 +199,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 > +.IR flags Use .I You don't need the 'R'. groff_man(7): .I Italic Font style macros .IB Italic, bold alternating Font style macros .IP Indented paragraph Paragraph macros .IR Italic, roman alternating Font style macros Thanks, Alex > +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; -- Alejandro Colomar Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/ http://www.alejandro-colomar.es/
