ioctl_eventpoll.2: Add eventpoll ioctl documentation
v3 cover ioctl_eventpoll.2: Add eventpoll ioctl documentation
Greetings:
Welcome to v3.
This revision includes several important changes:
1. Renamed the file from man/man2/ioctl_epoll.2 to
man/man2/ioctl_eventpoll.2.
2. Attempts to use semantic newlines to shorten long lines.
3. Replaces the include with <sys/epoll.h> instead of the kernel sources.
4. Many style issues that Alejandro pointed out in v2.
5. Using \[rs] instead of \e in the example code.
6. Replace all instances of ioctl_epoll with ioctl_eventpoll
Many thanks for Alejandro for his unending patience and attention to detail.
Thanks,
Joe
v2->v3:
- Rename file from man/man2/ioctl_epoll.2 to man/man2/ioctl_eventpoll.2.
- Attempt to use semantic newlines.
- Replace includes with sys/epoll.h, since this code is in glibc.
- Several style changes suggested by Alejandro.
- Replacing \e with \[rs] in the sample code included.
- Replacing all instances of ioctl_epoll with ioctl_eventpoll
v1->v2:
- Add link pages for EPIOCSPARAMS and EPIOCGPARAMS.
- Many edits to the main ioctl_epoll file to better describe the operations and document the interface.
Joe Damato (1):
ioctl_eventpoll.2: New page describing epoll ioctl(2)
man/man2/epoll_create.2 | 1 + man/man2/epoll_ctl.2 | 1 + man/man2/ioctl.2 | 1 + man/man2/ioctl_eventpoll.2 | 173 ++++++++++++++++++++++++++++++ man/man2const/EPIOCGPARAMS.2const | 1 + man/man2const/EPIOCSPARAMS.2const | 1 + man/man7/epoll.7 | 1 + 7 files changed, 179 insertions(+) create mode 100644 man/man2/ioctl_eventpoll.2 create mode 100644 man/man2const/EPIOCGPARAMS.2const create mode 100644 man/man2const/EPIOCSPARAMS.2const
Signature · 1 line
2.34.1
PATCH v3 1/1 ioctl_eventpoll.2: New page describing epoll ioctl(2)
A new page is added which describes epoll fd ioctls: EPIOCSPARAMS and EPIOCGPARAMS which allow the user to control epoll-based busy polling.
Also add link pages for EPIOCSPARAMS and EPIOCGPARAMS.
--- man/man2/epoll_create.2 | 1 + man/man2/epoll_ctl.2 | 1 + man/man2/ioctl.2 | 1 + man/man2/ioctl_eventpoll.2 | 173 ++++++++++++++++++++++++++++++ man/man2const/EPIOCGPARAMS.2const | 1 + man/man2const/EPIOCSPARAMS.2const | 1 + man/man7/epoll.7 | 1 + 7 files changed, 179 insertions(+) create mode 100644 man/man2/ioctl_eventpoll.2 create mode 100644 man/man2const/EPIOCGPARAMS.2const create mode 100644 man/man2const/EPIOCSPARAMS.2const
man/man2/epoll_create.2 +1 -0
@@ -141,4 +141,5 @@ on overrun. .BR close (2), .BR epoll_ctl (2), .BR epoll_wait (2), +.BR ioctl_eventpoll (2), .BR epoll (7)
man/man2/epoll_ctl.2 +1 -0
@@ -425,5 +425,6 @@ flag. .SH SEE ALSO .BR epoll_create (2), .BR epoll_wait (2), +.BR ioctl_eventpoll (2), .BR poll (2), .BR epoll (7)
man/man2/ioctl.2 +1 -0
@@ -225,6 +225,7 @@ for the various architectures. .BR ioctl_ns (2), .BR ioctl_tty (2), .BR ioctl_userfaultfd (2), +.BR ioctl_eventpoll (2), .BR open (2), .\" .BR mt (4), .BR sd (4),
man/man2/ioctl_eventpoll.2 new file +173 -0
173 lines not on this page · raw message
man/man2const/EPIOCGPARAMS.2const new file +1 -0
@@ -0,0 +1 @@ +.so man2/ioctl_eventpoll.2
man/man2const/EPIOCSPARAMS.2const new file +1 -0
@@ -0,0 +1 @@ +.so man2/ioctl_eventpoll.2
man/man7/epoll.7 +1 -0
@@ -606,5 +606,6 @@ is present in an epoll instance. .BR epoll_create1 (2), .BR epoll_ctl (2), .BR epoll_wait (2), +.BR ioctl_eventpoll (2), .BR poll (2), .BR select (2)
Signature · 1 line
2.34.1
Alejandro Colomar
maintainerRe: [PATCH v3 1/1] ioctl_eventpoll.2: New page describing epoll ioctl(2)
Greetings Joe,
Quoted 7 lines · Joe Damato
Greetings:
Welcome to v3.
This revision includes several important changes:
1. Renamed the file from man/man2/ioctl_epoll.2 toman/man2/ioctl_eventpoll.2.
Quoted 8 lines
2. Attempts to use semantic newlines to shorten long lines.
3. Replaces the include with <sys/epoll.h> instead of the kernel sources.
4. Many style issues that Alejandro pointed out in v2.
5. Using \[rs] instead of \e in the example code.
6. Replace all instances ofioctl_epollwithioctl_eventpollMany thanks for Alejandro for his unending patience and attention to detail.
Thank you. :)
We'll still need a v4, but we're almost there.
Quoted 1 line
Subject: ioctl_eventpoll.2: New page describing epoll ioctl(2)
Let's make the commit subject this:
ioctl_eventpoll.2, EPIOC[GS]PARAMS.2const: New page describing epoll ioctl(2)
Quoted 58 lines · Joe Damato
A new page is added which describes epoll fd ioctls: EPIOCSPARAMS and EPIOCGPARAMS which allow the user to control epoll-based busy polling.
Also add link pages for EPIOCSPARAMS and EPIOCGPARAMS.
Signed-off-by Joe Damato <[email protected]>--- man/man2/epoll_create.2 | 1 + man/man2/epoll_ctl.2 | 1 + man/man2/ioctl.2 | 1 + man/man2/ioctl_eventpoll.2 | 173 ++++++++++++++++++++++++++++++ man/man2const/EPIOCGPARAMS.2const | 1 + man/man2const/EPIOCSPARAMS.2const | 1 + man/man7/epoll.7 | 1 + 7 files changed, 179 insertions(+) create mode 100644 man/man2/ioctl_eventpoll.2 create mode 100644 man/man2const/EPIOCGPARAMS.2const create mode 100644 man/man2const/EPIOCSPARAMS.2constman/man2/epoll_create.2 +1
-0@@ -141,4 +141,5 @@ on overrun. .BR close (2), .BR epoll_ctl (2), .BR epoll_wait (2), +.BR ioctl_eventpoll (2), .BR epoll (7)man/man2/epoll_ctl.2 +1
-0@@ -425,5 +425,6 @@ flag. .SH SEE ALSO .BR epoll_create (2), .BR epoll_wait (2), +.BR ioctl_eventpoll (2), .BR poll (2), .BR epoll (7)man/man2/ioctl.2 +1
-0@@ -225,6 +225,7 @@ for the various architectures. .BR ioctl_ns (2), .BR ioctl_tty (2), .BR ioctl_userfaultfd (2), +.BR ioctl_eventpoll (2), .BR open (2), .\" .BR mt (4), .BR sd (4),man/man2/ioctl_eventpoll.2 new file +0
-0
man/man2/ioctl_eventpoll.2 line 1
Quoted 1 line
man/man2/ioctl_eventpoll.2 new file +1
-0@@ -0,0 +1,173 @@ +.\" Copyright (c) 2024, Joe Damato
1d
Quoted 6 lines
man/man2/ioctl_eventpoll.2 new file +6
-0+.\" Copyright 2024, Joe Damato <[email protected]> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH ioctl_eventpoll 2 (date) "Linux man-pages (unreleased)" +.SH NAME
man/man2/ioctl_eventpoll.2 line 17
Quoted 10 lines
man/man2/ioctl_eventpoll.2 new file +10
-0+ioctl_eventpoll, +EPIOCSPARAMS, +EPIOCGPARAMS +\- +ioctl() operations for epoll file descriptors +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.EX
This should be '.nf' instead of '.EX'. We want most of the SYNOPSIS to use proportional font in PDF. EX/EE is nf/fi + monospace. We want it for the structs, but not for the rest of the SYNOPSIS.
man/man2/ioctl_eventpoll.2 line 25
Quoted 8 lines
man/man2/ioctl_eventpoll.2 new file +8
-0+.BR "#include <sys/epoll.h>" " /* Definition of " EPIOC* " constants */" +.B "#include <sys/ioctl.h>" +.P +.BI "int ioctl(int " fd ", EPIOCSPARAMS, const struct epoll_params *" argp ); +.BI "int ioctl(int " fd ", EPIOCGPARAMS, struct epoll_params *" argp ); +.P +.B "#include <sys/epoll.h>" +.P
Here let's insert a .EX to make the structure use monospace (for alignment reasons).
man/man2/ioctl_eventpoll.2 line 26
Quoted 1 line
man/man2/ioctl_eventpoll.2 new file +1
-0+.B struct epoll_params {
When reading the page in a usual terminal, these comments go past the 80 column, which is not nice. Please shorten the comments so that the SYNOPSIS renders nicely in a (80x24) usual terminal.
Below go some suggestions.
man/man2/ioctl_eventpoll.2 line 28
Quoted 2 lines
man/man2/ioctl_eventpoll.2 new file +2
-0+.BR " uint32_t busy_poll_usecs;" " /* Number of usecs to busy poll */" +.BR " uint16_t busy_poll_budget;" " /* Maximum number of packets to retrieve per poll */"
s/Maximum number of/Max/
s/to retrieve //
man/man2/ioctl_eventpoll.2 line 29
Quoted 1 line
man/man2/ioctl_eventpoll.2 new file +1
-0+.BR " uint8_t prefer_busy_poll;" " /* Boolean to enable or disable prefer busy poll */"
I'd simplify this as
/* Boolean preference */
Also, I'd like to align the member names according to
<https://nginx.org/en/docs/dev/development_guide.html#code_style_variables>.
That is, 2 spaces of minimum alignment, plus the necessary to make them all aligned (so 3 on the last).
I'd like also 2 spaces minimum before the comments, instead of just 1.
man/man2/ioctl_eventpoll.2 line 34
Quoted 5 lines
man/man2/ioctl_eventpoll.2 new file +5
-0+\& +.BR " " " /* pad the struct to a multiple of 64bits */" +.BR " uint8_t __pad;" " /* Must be zero */" +.B }; +.EE
And here append .fi to close the initial .nf.
Quoted 11 lines
man/man2/ioctl_eventpoll.2 new file +11
-0+.SH DESCRIPTION +.TP +.B EPIOCSPARAMS +Set the +.I epoll_params +structure to configure the operation of epoll. +Refer to the structure description below +to learn what configuration is supported. +.TP +.B EPIOCGPARAMS +Get the current
man/man2/ioctl_eventpoll.2 line 55
Quoted 10 lines
man/man2/ioctl_eventpoll.2 new file +10
-0+.I epoll_params +configuration settings. +.P +All operations documented above must be performed on an epoll file descriptor, +which can be obtained with a call to +.BR epoll_create (2) +or +.BR epoll_create1 (2). +.\" linux.git commit 18e2bf0edf4dd88d9656ec92395aa47392e85b61 +.\" glibc.git commit 92c270d32caf3f8d5a02b8e46c7ec5d9d0315158
Please move these comments to HISTORY.
man/man2/ioctl_eventpoll.2 line 62
Quoted 7 lines
man/man2/ioctl_eventpoll.2 new file +7
-0+.SS The epoll_params structure +.I argp.busy_poll_usecs +denotes the number of microseconds that the network stack will busy poll. +During this time period, +the network device will be polled repeatedly for packets. +This value cannot exceed +.B INT_MAX.
.BR INT_MAX .
man/man2/ioctl_eventpoll.2 line 71
Quoted 9 lines
man/man2/ioctl_eventpoll.2 new file +9
-0+.in +.P +.I argp.busy_poll_budget +the maximum number of packets that the network stack will retrieve +on each poll attempt. +This value cannot exceed +.B NAPI_POLL_WEIGHT +(which is 64 as of Linux 6.9), unless the process is run with +.B CAP_NET_ADMIN.
.BR CAP_NET_ADMIN .
Quoted 26 lines
man/man2/ioctl_eventpoll.2 new file +26
-0+.P +.I argp.prefer_busy_poll +is a boolean field and +must be either 0 (disabled) or 1 (enabled). +If enabled, +this indicates to the network stack that +busy poll is the preferred method of processing network data +and the network stack should give the application the opportunity to busy poll. +Without this option, +very busy systems may continue to do network processing +via the normal method of IRQs triggering softIRQ and NAPI. +.P +.I argp.__pad +must be zero. +.SH RETURN VALUE +On success, 0 is returned. +On failure, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EOPNOTSUPP +The kernel was not compiled with busy poll support. +.TP +.B EINVAL +.I fd
man/man2/ioctl_eventpoll.2 line 107
Quoted 10 lines
man/man2/ioctl_eventpoll.2 new file +10
-0+is not a valid file descriptor. +.TP +.B EINVAL +.I argp.__pad +is not zero. +.TP +.B EINVAL +.I argp.busy_poll_usecs +exceeds +.B INT_MAX .
s/B/BR/
Mnemonics are:
B is for Bold, and BR is for alternating Bold and Roman.
man/man2/ioctl_eventpoll.2 line 115
Quoted 8 lines
man/man2/ioctl_eventpoll.2 new file +8
-0+.TP +.B EINVAL +.I argp.prefer_busy_poll +is not 0 or 1. +.TP +.B EPERM +The process is being run without +.I CAP_NET_ADMIN
s/.I/.B/
We use B for constants or type names, and I for variable names or code.
man/man2/ioctl_eventpoll.2 line 119
Quoted 4 lines
man/man2/ioctl_eventpoll.2 new file +4
-0+and the specified +.I argp.busy_poll_budget +exceeds +.B NAPI_POLL_WEIGHT.
.BR NAPI_POLL_WEIGHT .
Quoted 33 lines
man/man2/ioctl_eventpoll.2 new file +33
-0+.TP +.B EFAULT +.I argp +does not point to a valid memory address. +.SH EXAMPLES +.EX +/* Code to set the epoll params to enable busy polling */ +\& +int epollfd = epoll_create1(0); +struct epoll_params params; +\& +if (epollfd == \-1) { + perror("epoll_create1"); + exit(EXIT_FAILURE); +} +\& +memset(¶ms, 0, sizeof(struct epoll_params)); +\& +params.busy_poll_usecs = 25; +params.busy_poll_budget = 8; +params.prefer_busy_poll = 1; +\& +if (ioctl(epollfd, EPIOCSPARAMS, ¶ms) == \-1) { + perror("ioctl"); + exit(EXIT_FAILURE); +} +\& +/* Code to show how to retrieve the current settings */ +\& +memset(¶ms, 0, sizeof(struct epoll_params)); +\& +if (ioctl(epollfd, EPIOCGPARAMS, ¶ms) == \-1) { + perror("ioctl");
man/man2/ioctl_eventpoll.2 line 162
Quoted 10 lines
man/man2/ioctl_eventpoll.2 new file +10
-0+ exit(EXIT_FAILURE); +} +\& +/* params struct now contains the current parameters */ +\& +fprintf(stderr, "epoll usecs: %lu\[rs]n", params.busy_poll_usecs); +fprintf(stderr, "epoll packet budget: %u\[rs]n", params.busy_poll_budget); +fprintf(stderr, "epoll prefer busy poll: %u\[rs]n", params.prefer_busy_poll); +\& +.SH History
You read my mind. :)
While I have plans to use sentence case in section names (thus, History instead of HISTORY), that's still just a plan. For now, please use upper case.
Also, HISTORY goes before EXAMPLES. You can check the order of the sections in man-pages(7):
$ MANWIDTH=72 man man-pages | sed -n '/Sections within a manual page/,+29p'
Sections within a manual page
The list below shows conventional or suggested sections. Most
manual pages should include at least the highlighted sections.
Arrange a new manual page so that sections are placed in the order
shown in the list. NAME
LIBRARY [Normally only in Sections 2, 3]
SYNOPSIS
CONFIGURATION [Normally only in Section 4]
DESCRIPTION
OPTIONS [Normally only in Sections 1, 8]
EXIT STATUS [Normally only in Sections 1, 8]
RETURN VALUE [Normally only in Sections 2, 3]
ERRORS [Typically only in Sections 2, 3]
ENVIRONMENT
FILES
ATTRIBUTES [Normally only in Sections 2, 3]
VERSIONS [Normally only in Sections 2, 3]
STANDARDS
HISTORY
NOTES
CAVEATS
BUGS
EXAMPLES
AUTHORS [Discouraged]
REPORTING BUGS [Not used in man‐pages]
COPYRIGHT [Not used in man‐pages]
SEE ALSO
Please also add a STANDARDS section, which just says "Linux."
Regarding semantic newlines, it looks great. Thanks!
Have a lovely night!
Alex
Quoted 40 lines
man/man2/ioctl_eventpoll.2 new file +11
-0+Linux 6.9. +glibc 2.40. +.SH SEE ALSO +.BR ioctl (2), +.BR epoll_create (2), +.BR epoll_create1 (2), +.BR epoll (7) +.P +.I linux.git/Documentation/networking/napi.rst +.P +.I linux.git/Documentation/admin-guide/sysctl/net.rstman/man2const/EPIOCGPARAMS.2const new file +1
-0@@ -0,0 +1 @@ +.so man2/ioctl_eventpoll.2man/man2const/EPIOCSPARAMS.2const new file +1
-0@@ -0,0 +1 @@ +.so man2/ioctl_eventpoll.2man/man7/epoll.7 +1
-0@@ -606,5 +606,6 @@ is present in an epoll instance. .BR epoll_create1 (2), .BR epoll_ctl (2), .BR epoll_wait (2), +.BR ioctl_eventpoll (2), .BR poll (2), .BR select (2)Signature · 1 line
2.34.1
Signature · 1 line
<https://www.alejandro-colomar.es/>
Re: [PATCH v3 1/1] ioctl_eventpoll.2: New page describing epoll ioctl(2)
Quoted 21 lines · Alejandro Colomar
Greetings Joe,
Quoted 7 lines · Joe Damato
Greetings:
Welcome to v3.
This revision includes several important changes:
1. Renamed the file from man/man2/ioctl_epoll.2 toman/man2/ioctl_eventpoll.2.Quoted 8 lines
2. Attempts to use semantic newlines to shorten long lines.
3. Replaces the include with <sys/epoll.h> instead of the kernel sources.
4. Many style issues that Alejandro pointed out in v2.
5. Using \[rs] instead of \e in the example code.
6. Replace all instances ofioctl_epollwithioctl_eventpollMany thanks for Alejandro for his unending patience and attention to detail.
Thank you. :)
Quoted 7 lines
We'll still need a v4, but we're almost there.
Quoted 1 line
Subject: ioctl_eventpoll.2: New page describing epoll ioctl(2)
Let's make the commit subject this:
ioctl_eventpoll.2, EPIOC[GS]PARAMS.2const: New page describing epoll ioctl(2)
Fixed!
Quoted 54 lines · Joe Damato
Quoted 53 lines
A new page is added which describes epoll fd ioctls: EPIOCSPARAMS and EPIOCGPARAMS which allow the user to control epoll-based busy polling.
Also add link pages for EPIOCSPARAMS and EPIOCGPARAMS.
Signed-off-by Joe Damato <[email protected]>--- man/man2/epoll_create.2 | 1 + man/man2/epoll_ctl.2 | 1 + man/man2/ioctl.2 | 1 + man/man2/ioctl_eventpoll.2 | 173 ++++++++++++++++++++++++++++++ man/man2const/EPIOCGPARAMS.2const | 1 + man/man2const/EPIOCSPARAMS.2const | 1 + man/man7/epoll.7 | 1 + 7 files changed, 179 insertions(+) create mode 100644 man/man2/ioctl_eventpoll.2 create mode 100644 man/man2const/EPIOCGPARAMS.2const create mode 100644 man/man2const/EPIOCSPARAMS.2constman/man2/epoll_create.2 +1
-0@@ -141,4 +141,5 @@ on overrun. .BR close (2), .BR epoll_ctl (2), .BR epoll_wait (2), +.BR ioctl_eventpoll (2), .BR epoll (7)man/man2/epoll_ctl.2 +1
-0@@ -425,5 +425,6 @@ flag. .SH SEE ALSO .BR epoll_create (2), .BR epoll_wait (2), +.BR ioctl_eventpoll (2), .BR poll (2), .BR epoll (7)man/man2/ioctl.2 +1
-0@@ -225,6 +225,7 @@ for the various architectures. .BR ioctl_ns (2), .BR ioctl_tty (2), .BR ioctl_userfaultfd (2), +.BR ioctl_eventpoll (2), .BR open (2), .\" .BR mt (4), .BR sd (4),man/man2/ioctl_eventpoll.2 +0
-0
Quoted 8 lines
man/man2/ioctl_eventpoll.2 line 1
Quoted 6 lines
new file mode 100644
index 000000000..0fe03d6d4man/man2/ioctl_eventpoll.2 new file +1
-0@@ -0,0 +1,173 @@ +.\" Copyright (c) 2024, Joe Damato1d
My apologies, but I am not sure what you mean by this. What does 1d mean?
Quoted 12 lines
Quoted 12 lines
man/man2/ioctl_eventpoll.2 new file +12
-0+.\" Copyright 2024, Joe Damato <[email protected]> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH ioctl_eventpoll 2 (date) "Linux man-pages (unreleased)" +.SH NAME +ioctl_eventpoll, +EPIOCSPARAMS, +EPIOCGPARAMS +\- +ioctl() operations for epoll file descriptors +.SH LIBRARY
Quoted 8 lines
man/man2/ioctl_eventpoll.2 line 17
Quoted 4 lines
man/man2/ioctl_eventpoll.2 new file +4
-0+Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.EXThis should be '.nf' instead of '.EX'. We want most of the SYNOPSIS to use proportional font in PDF. EX/EE is nf/fi + monospace. We want it for the structs, but not for the rest of the SYNOPSIS.
OK I've made this .nf and added a corresponding .fi at the bottom.
Quoted 11 lines
man/man2/ioctl_eventpoll.2 line 25
Quoted 8 lines
man/man2/ioctl_eventpoll.2 new file +8
-0+.BR "#include <sys/epoll.h>" " /* Definition of " EPIOC* " constants */" +.B "#include <sys/ioctl.h>" +.P +.BI "int ioctl(int " fd ", EPIOCSPARAMS, const struct epoll_params *" argp ); +.BI "int ioctl(int " fd ", EPIOCGPARAMS, struct epoll_params *" argp ); +.P +.B "#include <sys/epoll.h>" +.PHere let's insert a .EX to make the structure use monospace (for alignment reasons).
I've inserted an .EX here as suggested.
Quoted 11 lines
man/man2/ioctl_eventpoll.2 line 26
Quoted 1 line
man/man2/ioctl_eventpoll.2 new file +1
-0+.B struct epoll_params {When reading the page in a usual terminal, these comments go past the 80 column, which is not nice. Please shorten the comments so that the SYNOPSIS renders nicely in a (80x24) usual terminal.
Below go some suggestions.
man/man2/ioctl_eventpoll.2 line 28
Quoted 2 lines
man/man2/ioctl_eventpoll.2 new file +2
-0+.BR " uint32_t busy_poll_usecs;" " /* Number of usecs to busy poll */" +.BR " uint16_t busy_poll_budget;" " /* Maximum number of packets to retrieve per poll */"
Quoted 8 lines
s/Maximum number of/Max/
s/to retrieve //man/man2/ioctl_eventpoll.2 line 29
Quoted 1 line
man/man2/ioctl_eventpoll.2 new file +1
-0+.BR " uint8_t prefer_busy_poll;" " /* Boolean to enable or disable prefer busy poll */"I'd simplify this as
/* Boolean preference */
On the comment changes above, I've taken your suggestions exactly. Thank you!
Quoted 6 lines
Also, I'd like to align the member names according to
<https://nginx.org/en/docs/dev/development_guide.html#code_style_variables>.
That is, 2 spaces of minimum alignment, plus the necessary to make them all aligned (so 3 on the last).I'd like also 2 spaces minimum before the comments, instead of just 1.
OK, based on the link you sent, I've aligned the start of each of the types and then aligned the start of the field names. Lastly, I've aligned the start of the comments for the first 3 fields, but left the comment for the __pad just two spaces after the field name.
Did you want the comment for __pad to be aligned to the comments for the in-use fields above?
This is what I have now, but I can insert space to move the pad comment over if you like.
.EX
.B struct epoll_params {
.BR " uint32_t busy_poll_usecs;" " /* Number of usecs to busy poll */" .BR " uint16_t busy_poll_budget;" " /* Max packets per poll */" .BR " uint8_t prefer_busy_poll;" " /* Boolean preference */"
\&
.BR " " "/* pad the struct to a multiple of 64bits */" .BR " uint8_t __pad;" " /* Must be zero */" .B };
.EE
Quoted 23 lines
man/man2/ioctl_eventpoll.2 line 34
Quoted 5 lines
man/man2/ioctl_eventpoll.2 new file +5
-0+\& +.BR " " " /* pad the struct to a multiple of 64bits */" +.BR " uint8_t __pad;" " /* Must be zero */" +.B }; +.EEAnd here append .fi to close the initial .nf.
Quoted 15 lines
man/man2/ioctl_eventpoll.2 new file +15
-0+.SH DESCRIPTION +.TP +.B EPIOCSPARAMS +Set the +.I epoll_params +structure to configure the operation of epoll. +Refer to the structure description below +to learn what configuration is supported. +.TP +.B EPIOCGPARAMS +Get the current +.I epoll_params +configuration settings. +.P +All operations documented above must be performed on an epoll file descriptor,
Quoted 8 lines
man/man2/ioctl_eventpoll.2 line 55
Quoted 6 lines
man/man2/ioctl_eventpoll.2 new file +6
-0+which can be obtained with a call to +.BR epoll_create (2) +or +.BR epoll_create1 (2). +.\" linux.git commit 18e2bf0edf4dd88d9656ec92395aa47392e85b61 +.\" glibc.git commit 92c270d32caf3f8d5a02b8e46c7ec5d9d0315158Please move these comments to HISTORY.
Done!
Quoted 9 lines
man/man2/ioctl_eventpoll.2 line 62
Quoted 7 lines
man/man2/ioctl_eventpoll.2 new file +7
-0+.SS The epoll_params structure +.I argp.busy_poll_usecs +denotes the number of microseconds that the network stack will busy poll. +During this time period, +the network device will be polled repeatedly for packets. +This value cannot exceed +.B INT_MAX..BR
INT_MAX.
Fixed.
Quoted 11 lines
man/man2/ioctl_eventpoll.2 line 71
Quoted 9 lines
man/man2/ioctl_eventpoll.2 new file +9
-0+.in +.P +.I argp.busy_poll_budget +the maximum number of packets that the network stack will retrieve +on each poll attempt. +This value cannot exceed +.B NAPI_POLL_WEIGHT +(which is 64 as of Linux 6.9), unless the process is run with +.B CAP_NET_ADMIN..BR
CAP_NET_ADMIN.
Fixed.
Quoted 39 lines
Quoted 26 lines
man/man2/ioctl_eventpoll.2 new file +26
-0+.P +.I argp.prefer_busy_poll +is a boolean field and +must be either 0 (disabled) or 1 (enabled). +If enabled, +this indicates to the network stack that +busy poll is the preferred method of processing network data +and the network stack should give the application the opportunity to busy poll. +Without this option, +very busy systems may continue to do network processing +via the normal method of IRQs triggering softIRQ and NAPI. +.P +.I argp.__pad +must be zero. +.SH RETURN VALUE +On success, 0 is returned. +On failure, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EOPNOTSUPP +The kernel was not compiled with busy poll support. +.TP +.B EINVAL +.I fdman/man2/ioctl_eventpoll.2 line 107
Quoted 10 lines
man/man2/ioctl_eventpoll.2 new file +10
-0+is not a valid file descriptor. +.TP +.B EINVAL +.I argp.__pad +is not zero. +.TP +.B EINVAL +.I argp.busy_poll_usecs +exceeds +.B INT_MAX .s/B/BR/
Quoted 2 lines
Mnemonics are:
B is for Bold, and BR is for alternating Bold and Roman.
Fixed.
Quoted 11 lines
man/man2/ioctl_eventpoll.2 line 115
Quoted 8 lines
man/man2/ioctl_eventpoll.2 new file +8
-0+.TP +.B EINVAL +.I argp.prefer_busy_poll +is not 0 or 1. +.TP +.B EPERM +The process is being run without +.I CAP_NET_ADMINs/.I/.B/
Quoted 1 line
We use B for constants or type names, and I for variable names or code.
Fixed.
Quoted 6 lines
man/man2/ioctl_eventpoll.2 line 119
Quoted 4 lines
man/man2/ioctl_eventpoll.2 new file +4
-0+and the specified +.I argp.busy_poll_budget +exceeds +.B NAPI_POLL_WEIGHT..BR
NAPI_POLL_WEIGHT.
Fixed.
Quoted 46 lines
Quoted 33 lines
man/man2/ioctl_eventpoll.2 new file +33
-0+.TP +.B EFAULT +.I argp +does not point to a valid memory address. +.SH EXAMPLES +.EX +/* Code to set the epoll params to enable busy polling */ +\& +int epollfd = epoll_create1(0); +struct epoll_params params; +\& +if (epollfd == \-1) { + perror("epoll_create1"); + exit(EXIT_FAILURE); +} +\& +memset(¶ms, 0, sizeof(struct epoll_params)); +\& +params.busy_poll_usecs = 25; +params.busy_poll_budget = 8; +params.prefer_busy_poll = 1; +\& +if (ioctl(epollfd, EPIOCSPARAMS, ¶ms) == \-1) { + perror("ioctl"); + exit(EXIT_FAILURE); +} +\& +/* Code to show how to retrieve the current settings */ +\& +memset(¶ms, 0, sizeof(struct epoll_params)); +\& +if (ioctl(epollfd, EPIOCGPARAMS, ¶ms) == \-1) { + perror("ioctl");man/man2/ioctl_eventpoll.2 line 162
Quoted 10 lines
man/man2/ioctl_eventpoll.2 new file +10
-0+ exit(EXIT_FAILURE); +} +\& +/* params struct now contains the current parameters */ +\& +fprintf(stderr, "epoll usecs: %lu\[rs]n", params.busy_poll_usecs); +fprintf(stderr, "epoll packet budget: %u\[rs]n", params.busy_poll_budget); +fprintf(stderr, "epoll prefer busy poll: %u\[rs]n", params.prefer_busy_poll); +\& +.SH HistoryYou read my mind. :)
Quoted 6 lines
While I have plans to use sentence case in section names (thus, History instead of HISTORY), that's still just a plan. For now, please use upper case.
Also, HISTORY goes before EXAMPLES. You can check the order of the sections in man-pages(7):
OK, renamed to HISTORY and moved before EXAMPLES.
Quoted 31 lines
$ MANWIDTH=72 man man-pages | sed -n '/Sections within a manual page/,+29p' Sections within a manual page The list below shows conventional or suggested sections. Most manual pages should include at least the highlighted sections. Arrange a new manual page so that sections are placed in the order shown in the list.NAME
LIBRARY [Normally only in Sections 2, 3]
SYNOPSIS
CONFIGURATION [Normally only in Section 4]
DESCRIPTION
OPTIONS [Normally only in Sections 1, 8]
EXIT STATUS [Normally only in Sections 1, 8]
RETURN VALUE [Normally only in Sections 2, 3]
ERRORS [Typically only in Sections 2, 3]
ENVIRONMENT
FILES
ATTRIBUTES [Normally only in Sections 2, 3]
VERSIONS [Normally only in Sections 2, 3]
STANDARDS
HISTORY
NOTES
CAVEATS
BUGS
EXAMPLES
AUTHORS [Discouraged]
REPORTING BUGS [Not used in man-pages]
COPYRIGHT [Not used in man-pages]
SEE ALSO
Quoted 1 line
Please also add a STANDARDS section, which just says "Linux."
OK added STANDARDS (in the order above) which just says Linux:
.SH STANDARDS
.P
Linux.
.SH HISTORY
Quoted 1 line
Regarding semantic newlines, it looks great. Thanks!
Great!
Thanks,
Joe
Alejandro Colomar
maintainerRe: [PATCH v3 1/1] ioctl_eventpoll.2: New page describing epoll ioctl(2)
Hi Joe,
Quoted 10 lines · Joe Damato
Quoted 9 lines
man/man2/ioctl_eventpoll.2 line 1
Quoted 7 lines
man/man2/ioctl_eventpoll.2 new file +1
-0@@ -0,0 +1,173 @@ +.\" Copyright (c) 2024, Joe Damato1d
Quoted 2 lines
My apologies, but I am not sure what you mean by this. What does 1d mean?
I meant sed -i 1d. This line was redundant with line 2.
Quoted 4 lines
Quoted 4 lines
Quoted 4 lines
man/man2/ioctl_eventpoll.2 new file +4
-0+.\" Copyright 2024, Joe Damato <[email protected]> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\"
[...]
Quoted 20 lines
Quoted 6 lines
Also, I'd like to align the member names according to
<https://nginx.org/en/docs/dev/development_guide.html#code_style_variables>.
That is, 2 spaces of minimum alignment, plus the necessary to make them all aligned (so 3 on the last).I'd like also 2 spaces minimum before the comments, instead of just 1.
OK, based on the link you sent, I've aligned the start of each of the types and then aligned the start of the field names. Lastly, I've aligned the start of the comments for the first 3 fields, but left the comment for the
__padjust two spaces after the field name.Did you want the comment for
__padto be aligned to the comments for the in-use fields above?This is what I have now, but I can insert space to move the pad comment over if you like.
.EX
.B structepoll_params{
Quoted 8 lines
.BR " uint32_t busy_poll_usecs;" " /* Number of usecs to busy poll */" .BR " uint16_t busy_poll_budget;" " /* Max packets per poll */" .BR " uint8_t prefer_busy_poll;" " /* Boolean preference */"\&
.BR " " "/* pad the struct to a multiple of 64bits */" .BR "uint8_t__pad;" " /* Must be zero */" .B };
.EE
LGTM.
[...]
Quoted 6 lines
Quoted 1 line
Please also add a STANDARDS section, which just says "Linux."
OK added STANDARDS (in the order above) which just says Linux:
.SH STANDARDS
.P
.P after .SH is redundant.
Quoted 6 lines
Linux.
.SH HISTORYQuoted 1 line
Regarding semantic newlines, it looks great. Thanks!
Great!
Have a lovely night!
Alex
Signature · 1 line
<https://www.alejandro-colomar.es/>
Re: [PATCH v3 1/1] ioctl_eventpoll.2: New page describing epoll ioctl(2)
Quoted 13 lines · Alejandro Colomar
Hi Joe,
Quoted 10 lines · Joe Damato
Quoted 9 lines
man/man2/ioctl_eventpoll.2 line 1
Quoted 7 lines
man/man2/ioctl_eventpoll.2 new file +1
-0@@ -0,0 +1,173 @@ +.\" Copyright (c) 2024, Joe Damato1d
Quoted 4 lines
Quoted 2 lines
My apologies, but I am not sure what you mean by this. What does 1d mean?
I meant
sed -i 1d. This line was redundant with line 2.
Ah, of course. I've removed that line above and left the line below instead.
Quoted 40 lines
Quoted 4 lines
Quoted 4 lines
Quoted 4 lines
man/man2/ioctl_eventpoll.2 new file +4
-0+.\" Copyright 2024, Joe Damato <[email protected]> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\"[...]
Quoted 20 lines
Quoted 6 lines
Also, I'd like to align the member names according to
<https://nginx.org/en/docs/dev/development_guide.html#code_style_variables>.
That is, 2 spaces of minimum alignment, plus the necessary to make them all aligned (so 3 on the last).I'd like also 2 spaces minimum before the comments, instead of just 1.
OK, based on the link you sent, I've aligned the start of each of the types and then aligned the start of the field names. Lastly, I've aligned the start of the comments for the first 3 fields, but left the comment for the
__padjust two spaces after the field name.Did you want the comment for
__padto be aligned to the comments for the in-use fields above?This is what I have now, but I can insert space to move the pad comment over if you like.
.EX
.B structepoll_params{Quoted 8 lines
.BR " uint32_t busy_poll_usecs;" " /* Number of usecs to busy poll */" .BR " uint16_t busy_poll_budget;" " /* Max packets per poll */" .BR " uint8_t prefer_busy_poll;" " /* Boolean preference */"\&
.BR " " "/* pad the struct to a multiple of 64bits */" .BR "uint8_t__pad;" " /* Must be zero */" .B };
.EELGTM.
[...]
Quoted 8 lines
Quoted 6 lines
Quoted 1 line
Please also add a STANDARDS section, which just says "Linux."
OK added STANDARDS (in the order above) which just says Linux:
.SH STANDARDS
.P.P after .SH is redundant.
Fixed.
Will push a v4 shortly after re-reading this one.
Quoted 12 lines
Quoted 6 lines
Linux.
.SH HISTORYQuoted 1 line
Regarding semantic newlines, it looks great. Thanks!
Great!
Have a lovely night!
AlexSignature · 1 line
<https://www.alejandro-colomar.es/>