* [PATCH] ioctl_pipe.2: Add. @ 2022-06-08 12:47 chrubis 2022-06-08 15:12 ` Alejandro Colomar 0 siblings, 1 reply; 6+ messages in thread From: chrubis @ 2022-06-08 12:47 UTC (permalink / raw) To: linux-man; +Cc: alx.manpages, mtk.manpages, Cyril Hrubis 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 ^ permalink raw reply related [flat|nested] 6+ messages in thread
* Re: [PATCH] ioctl_pipe.2: Add. 2022-06-08 12:47 [PATCH] ioctl_pipe.2: Add chrubis @ 2022-06-08 15:12 ` Alejandro Colomar 2022-06-08 20:26 ` sorting "See also" cross-references? (was: [PATCH] ioctl_pipe.2: Add.) G. Branden Robinson 2023-03-30 23:57 ` Ping: [PATCH] ioctl_pipe.2: Add Alejandro Colomar 0 siblings, 2 replies; 6+ messages in thread From: Alejandro Colomar @ 2022-06-08 15:12 UTC (permalink / raw) To: chrubis, linux-man; +Cc: David Howells [-- 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 --] ^ permalink raw reply [flat|nested] 6+ messages in thread
* sorting "See also" cross-references? (was: [PATCH] ioctl_pipe.2: Add.) 2022-06-08 15:12 ` Alejandro Colomar @ 2022-06-08 20:26 ` G. Branden Robinson 2022-06-09 8:41 ` Alejandro Colomar 2023-03-30 23:57 ` Ping: [PATCH] ioctl_pipe.2: Add Alejandro Colomar 1 sibling, 1 reply; 6+ messages in thread From: G. Branden Robinson @ 2022-06-08 20:26 UTC (permalink / raw) To: Alejandro Colomar; +Cc: chrubis, linux-man, David Howells [-- 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 --] ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: sorting "See also" cross-references? (was: [PATCH] ioctl_pipe.2: Add.) 2022-06-08 20:26 ` sorting "See also" cross-references? (was: [PATCH] ioctl_pipe.2: Add.) G. Branden Robinson @ 2022-06-09 8:41 ` Alejandro Colomar 0 siblings, 0 replies; 6+ messages in thread From: Alejandro Colomar @ 2022-06-09 8:41 UTC (permalink / raw) To: G. Branden Robinson; +Cc: chrubis, linux-man, David Howells [-- 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 --] ^ permalink raw reply [flat|nested] 6+ messages in thread
* Ping: [PATCH] ioctl_pipe.2: Add. 2022-06-08 15:12 ` Alejandro Colomar 2022-06-08 20:26 ` sorting "See also" cross-references? (was: [PATCH] ioctl_pipe.2: Add.) G. Branden Robinson @ 2023-03-30 23:57 ` Alejandro Colomar 2023-04-03 14:08 ` Cyril Hrubis 1 sibling, 1 reply; 6+ messages in thread From: Alejandro Colomar @ 2023-03-30 23:57 UTC (permalink / raw) To: chrubis, linux-man; +Cc: David Howells [-- 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 --] ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: Ping: [PATCH] ioctl_pipe.2: Add. 2023-03-30 23:57 ` Ping: [PATCH] ioctl_pipe.2: Add Alejandro Colomar @ 2023-04-03 14:08 ` Cyril Hrubis 0 siblings, 0 replies; 6+ messages in thread From: Cyril Hrubis @ 2023-04-03 14:08 UTC (permalink / raw) To: Alejandro Colomar; +Cc: linux-man, David Howells Hi! Sorry, this got burried in my mbox, v2 on the way. -- Cyril Hrubis chrubis@suse.cz ^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2023-04-03 14:09 UTC | newest] Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2022-06-08 12:47 [PATCH] ioctl_pipe.2: Add chrubis 2022-06-08 15:12 ` Alejandro Colomar 2022-06-08 20:26 ` sorting "See also" cross-references? (was: [PATCH] ioctl_pipe.2: Add.) G. Branden Robinson 2022-06-09 8:41 ` Alejandro Colomar 2023-03-30 23:57 ` Ping: [PATCH] ioctl_pipe.2: Add Alejandro Colomar 2023-04-03 14:08 ` Cyril Hrubis
This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.