Re: [PATCH] ioctl_pipe.2: Add.

[Alejandro Colomar <alx.manpages@gmail.com>]

[-- Attachment #1.1: Type: text/plain, Size: 5360 bytes --]

Hi Cyril,

On 6/8/22 14:47, chrubis@suse.cz wrote:
> From: Cyril Hrubis <chrubis@suse.cz>
> 
> Signed-off-by: Cyril Hrubis <chrubis@suse.cz>

Please check a few things below.  Thanks for the page.

Also, the title could be a little bit clearer; maybe "Add page".

Cheers,

Alex

> ---
>   man2/ioctl_pipe.2 | 75 +++++++++++++++++++++++++++++++++++++++++++++++
>   1 file changed, 75 insertions(+)
>   create mode 100644 man2/ioctl_pipe.2
> 
> diff --git a/man2/ioctl_pipe.2 b/man2/ioctl_pipe.2
> new file mode 100644
> index 000000000..e60bc2134
> --- /dev/null
> +++ b/man2/ioctl_pipe.2
> @@ -0,0 +1,75 @@
> +.\" Copyright (c) 2022 by Cyril Hrubis <chrubi@suse.cz>
> +.\"
> +.\" %%%LICENSE_START(VERBATIM)
> +.\" Permission is granted to make and distribute verbatim copies of this
> +.\" manual provided the copyright notice and this permission notice are
> +.\" preserved on all copies.
> +.\"
> +.\" Permission is granted to copy and distribute modified versions of this
> +.\" manual under the conditions for verbatim copying, provided that the
> +.\" entire resulting derived work is distributed under the terms of a
> +.\" permission notice identical to this one.
> +.\"
> +.\" Since the Linux kernel and libraries are constantly changing, this
> +.\" manual page may be incorrect or out-of-date.  The author(s) assume no
> +.\" responsibility for errors or omissions, or for damages resulting from
> +.\" the use of the information contained herein.  The author(s) may not
> +.\" have taken the same level of care in the production of this manual,
> +.\" which is licensed free of charge, as they might when working
> +.\" professionally.
> +.\"
> +.\" Formatted or processed versions of this manual, if unaccompanied by
> +.\" the source, must acknowledge the copyright and authors of this work.
> +.\" %%%LICENSE_END

Could you please add just an SPDX-License-Identifier?  I removed the 
actual license texts recently to have less overhead lines.

See 
<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/man2/pipe.2?h=alx/main&id=5fbde956cb550ffeae83c31e4f8c1142544f4b4f>

> +.\"
> +.\"
> +.TH IOCTL_PIPE 2 2022-08-06 "Linux" "Linux Programmer's Manual"
> +.SH NAME
> +ioctl_pipe \- ioctl() operations for General notification mechanism
> +.SH SYNOPSIS
> +.nf
> +.B #include <linux/watch_queue.h>
> +.PP
> +.BI "int ioctl(int " pipefd[1] ", IOC_WATCH_QUEUE_SET_SIZE, int " size ");
> +.PP

You can remove that .PP to get the two prototypes together.  I looks 
nicer, IMO.

See man-pages(7):
    SYNOPSIS
        Wrap the function prototype(s) in a .nf/.fi pair to  pre-
        vent filling.

        In  general,  where  more  than one function prototype is
        shown in the SYNOPSIS, the prototypes should not be sepa-
        rated by blank lines.  However, blank lines (achieved us-
        ing .PP) may be added in the following cases:

        *  to separate long lists of function prototypes into re-
           lated groups (see for example list(3));

        *  in other cases that may improve readability.


> +.BI "int ioctl(int " pipefd[1] ", IOC_WATCH_QUEUE_SET_FILTER, struct watch_notification_filter * " filter ");

This gets past the 80-col margin.  Check for example openat2(2) for a 
solution.

> +.fi
> +.PP
> +.SH DESCRIPTION
> +The following
> +.BR ioctl (2)
> +operations are provided to set up a general notification queue parameters.

s/a //   ?

> +The notification queue is build on the top of a

s/build/built/

> +.BR pipe (2)
> +opened with

s/with/with the/

> +.B O_NOTIFICATION_PIPE
> +flag.
> +.TP
> +.BR IOC_WATCH_QUEUE_SET_SIZE " (since Linux 5.8)"
> +.\" commit c73be61cede5882f9605a852414db559c0ebedfd
> +Preallocates the pipe buffer memory so that it can fit size notification messages. Currently the size must be between 1 and 512.
> +.TP
> +.BR IOC_WATCH_QUEUE_SET_FILTER " (since Linux 5.8)"
> +.\" commit c73be61cede5882f9605a852414db559c0ebedfd
> +Watch queue filter, if set, can limit events that are received.

Of course if set, isn't it?  I mean, if it's not set, it can't do 
nothing.  Do we need to specify "if set"? :)

> +Filters are passed in a \fIstruct watch_notification_filter\fP

.I struct watch_notification_filter

> +and each filter is described by \fIstruct watch_notification_type_filter\fP structure.

.I str [...] ilter

> +

.PP

See man-pages(7):
    Formatting conventions (general)
        Paragraphs  should be separated by suitable markers (usu-
        ally either .PP or .IP).  Do not separate paragraphs  us-
        ing  blank  lines,  as  this results in poor rendering in
        some output formats (such as PostScript and PDF).

> +.EX
> +struct watch_notification_filter {
> +        __u32   nr_filters;
> +        __u32   __reserved;
> +        struct watch_notification_type_filter filters[];
> +};
> +
> +struct watch_notification_type_filter {
> +        __u32   type;
> +        __u32   info_filter;
> +        __u32   info_mask;
> +        __u32   subtype_filter[8];
> +};
> +.EE
> +

.PP

> +.SH SEE ALSO
> +.BR pipe (2),
> +.BR ioctl (2)

| sort


-- 
Alejandro Colomar
Linux man-pages comaintainer; http://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]