[PATCH] ioctl_pipe.2: Add.

[PATCH] ioctl_pipe.2: Add.

[chrubis]

From: Cyril Hrubis <chrubis@suse.cz>

Signed-off-by: Cyril Hrubis <chrubis@suse.cz>
---
 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
+.\"
+.\"
+.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
+.BI "int ioctl(int " pipefd[1] ", IOC_WATCH_QUEUE_SET_FILTER, struct watch_notification_filter * " filter ");
+.fi
+.PP
+.SH DESCRIPTION
+The following
+.BR ioctl (2)
+operations are provided to set up a general notification queue parameters.
+The notification queue is build on the top of a
+.BR pipe (2)
+opened with
+.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.
+Filters are passed in a \fIstruct watch_notification_filter\fP
+and each filter is described by \fIstruct watch_notification_type_filter\fP structure.
+
+.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
+
+.SH SEE ALSO
+.BR pipe (2),
+.BR ioctl (2)
-- 
2.35.1

Re: [PATCH] ioctl_pipe.2: Add.

[Alejandro Colomar]

[-- 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 --]

sorting "See also" cross-references? (was: [PATCH] ioctl_pipe.2: Add.)

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 1832 bytes --]

Hi Alex!

At 2022-06-08T17:12:19+0200, Alejandro Colomar wrote:
> > +.SH SEE ALSO
> > +.BR pipe (2),
> > +.BR ioctl (2)
> 
> | sort

I'd like to suggest (gently), that advocating a lexicographic sort for
this material is not the best approach.  In principle, a man page
renderer could recognize a "See also" section and perform a sort of man
page references within it itself, because that is a mechanical process.
(Recognizing man page cross references will be much easier with groff
1.23's [and plan9port troff's] `MR` macro.)

In practice, I don't think any man(7) renderer does that because it's
not worth the trouble, and doing so would lose sight of why the section
is present.

In the groff man pages, I try to order these cross references in a
considered way, starting with the page that I consider most "important"
or likely to fruitfully follow up the topic for the reader.  That sort
of judgment is subjective, of course, but with a well curated man page
corpus, I think it's likely more useful than a mechanical sort.

For example, in groff 1.23, the groff_man(7) and groff_man_style(7)
pages refer first to each other; then to groff(7) (a reference for the
groff language).

And groff(7)'s "See also" section is more of an annotated bibliography;
it was already largely that way when I started contributing to groff
development.  I think that's a good choice because a reader bewildered
by a laconic yet lengthy (because the formatter has many features)
reference page might strongly desire a more synoptic view, especially if
they don't know where to go next.

Steering people where they might value going next is the very point of
a "See also" section, in my opinion.  Their next best stop is not, in
general, likely to fall in English lexicographic order.

Regards,
Branden

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

Re: sorting "See also" cross-references? (was: [PATCH] ioctl_pipe.2: Add.)

[Alejandro Colomar]

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

Hi Branden!

On 6/8/22 22:26, G. Branden Robinson wrote:
> Hi Alex!
> 
> At 2022-06-08T17:12:19+0200, Alejandro Colomar wrote:
>>> +.SH SEE ALSO
>>> +.BR pipe (2),
>>> +.BR ioctl (2)
>>
>> | sort
> 
[...]
> In the groff man pages, I try to order these cross references in a
> considered way, starting with the page that I consider most "important"
> or likely to fruitfully follow up the topic for the reader.  That sort
> of judgment is subjective, of course, but with a well curated man page
> corpus, I think it's likely more useful than a mechanical sort.
> 
Makes sense.  Most pages have lexicographic order, but importance order 
seems an improvement.

Cheers,

Alex


-- 
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 --]

Ping: [PATCH] ioctl_pipe.2: Add.

[Alejandro Colomar]

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

Hi Cyril,

I'm checking old mail, and found that this thread was unresolved.
Do you still have that page around and would like to resend?

Thanks,
Alex

On 6/8/22 17:12, Alejandro Colomar wrote:
> 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
> 
> 

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

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

Re: Ping: [PATCH] ioctl_pipe.2: Add.

[Cyril Hrubis]

Hi!
Sorry, this got burried in my mbox, v2 on the way.

-- 
Cyril Hrubis
chrubis@suse.cz