Skip to contentSkip to conversation

ioctl_eventpoll.2: Add eventpoll ioctl documentation

PATCH Superseded Joe Damato 2 participants 6 messages Jun 11, 2024 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

v3 of 4 Superseded Latest is v4 →

lore
Share & tools
lore

Joe Damato

author
#0 lore raw

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
author
#1 lore raw

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
index f0327e8ba..013f81b64 100644
@@ -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
index 6d5bc032e..29a6da375 100644
@@ -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
index 5b8c28a9c..6f7725904 100644
@@ -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
new file mode 100644
index 000000000..b70a1a565
@@ -0,0 +1 @@
+.so man2/ioctl_eventpoll.2
man/man2const/EPIOCSPARAMS.2const new file +1 -0
new file mode 100644
index 000000000..b70a1a565
@@ -0,0 +1 @@
+.so man2/ioctl_eventpoll.2
man/man7/epoll.7 +1 -0
index e7892922e..951500131 100644
@@ -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
#2 lore raw

Re: [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 to

     man/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 of ioctl_epoll with ioctl_eventpoll

Many 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.

---
 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
index f0327e8ba..013f81b64 100644
@@ -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
index 6d5bc032e..29a6da375 100644
@@ -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
index 5b8c28a9c..6f7725904 100644
@@ -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
new file mode 100644
index 000000000..0fe03d6d4

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(&params, 0, sizeof(struct epoll_params));
+\&
+params.busy_poll_usecs = 25;
+params.busy_poll_budget = 8;
+params.prefer_busy_poll = 1;
+\&
+if (ioctl(epollfd, EPIOCSPARAMS, &params) == \-1) {
+    perror("ioctl");
+    exit(EXIT_FAILURE);
+}
+\&
+/* Code to show how to retrieve the current settings */
+\&
+memset(&params, 0, sizeof(struct epoll_params));
+\&
+if (ioctl(epollfd, EPIOCGPARAMS, &params) == \-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.rst
man/man2const/EPIOCGPARAMS.2const new file +1 -0
new file mode 100644
index 000000000..b70a1a565
@@ -0,0 +1 @@
+.so man2/ioctl_eventpoll.2
man/man2const/EPIOCSPARAMS.2const new file +1 -0
new file mode 100644
index 000000000..b70a1a565
@@ -0,0 +1 @@
+.so man2/ioctl_eventpoll.2
man/man7/epoll.7 +1 -0
index e7892922e..951500131 100644
@@ -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/>
author
#3 lore raw

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 to

     man/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 of ioctl_epoll with ioctl_eventpoll

Many 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.

---
 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
index f0327e8ba..013f81b64 100644
@@ -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
index 6d5bc032e..29a6da375 100644
@@ -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
index 5b8c28a9c..6f7725904 100644
@@ -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..0fe03d6d4

man/man2/ioctl_eventpoll.2 new file +1 -0
@@ -0,0 +1,173 @@
+.\" Copyright (c) 2024, Joe Damato

1d

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
+.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.

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>"
+.P

Here 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 };
+.EE

And 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 92c270d32caf3f8d5a02b8e46c7ec5d9d0315158

Please 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 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/

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_ADMIN

s/.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(&params, 0, sizeof(struct epoll_params));
+\&
+params.busy_poll_usecs = 25;
+params.busy_poll_budget = 8;
+params.prefer_busy_poll = 1;
+\&
+if (ioctl(epollfd, EPIOCSPARAMS, &params) == \-1) {
+    perror("ioctl");
+    exit(EXIT_FAILURE);
+}
+\&
+/* Code to show how to retrieve the current settings */
+\&
+memset(&params, 0, sizeof(struct epoll_params));
+\&
+if (ioctl(epollfd, EPIOCGPARAMS, &params) == \-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. :)

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

#4 lore raw

Re: [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
new file mode 100644
index 000000000..0fe03d6d4
@@ -0,0 +1,173 @@
+.\" Copyright (c) 2024, Joe Damato

1d

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 __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 {

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 HISTORY

Quoted 1 line

Regarding semantic newlines, it looks great. Thanks!

Great!

Have a lovely night!
Alex

Signature · 1 line
<https://www.alejandro-colomar.es/>
author
#5 lore raw

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
new file mode 100644
index 000000000..0fe03d6d4
@@ -0,0 +1,173 @@
+.\" Copyright (c) 2024, Joe Damato

1d

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 __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 {

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

Quoted 1 line

Regarding semantic newlines, it looks great. Thanks!

Great!

Have a lovely night!
Alex

Signature · 1 line
<https://www.alejandro-colomar.es/>