[PATCH] man/man7/epoll.7: Note that an edge-triggered listener needs an accept loop

[PATCH] man/man7/epoll.7: Note that an edge-triggered listener needs an accept loop

[Ben Kuo via B4 Relay]

From: Ben Kuo <ben.kuo.tw@proton.me>

The example registers the listening socket as level-triggered and
calls accept(2) once per event, but doesn't say that this only works
for a level-triggered listener.  If a reader adds EPOLLET to the
listening socket in the example, connections are left in the accept
queue and the server stalls.

Tested on Linux 6.12 (Debian 13, arm64) with an echo server whose
listening socket is registered with EPOLLET, and a client that opens
2000 connections at once.  With one accept4(2) call per listener
event, the client never finishes: ss(8) shows 1420 connections left
in the accept queue (Recv-Q), while the server stays blocked in
epoll_wait(2).  With accept4(2) called in a loop until EAGAIN, all
connections are echoed.

Link: <https://github.com/benkuotw/epoll-lab>
Signed-off-by: Ben Kuo <ben.kuo.tw@proton.me>
---
 man/man7/epoll.7 | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/man/man7/epoll.7 b/man/man7/epoll.7
index 2628cbb168b499786e495cf3c614fc5e58217295..aff844a568a5cd6d8eb310ed833266a0ccfd0a4d 100644
--- a/man/man7/epoll.7
+++ b/man/man7/epoll.7
@@ -339,6 +339,16 @@ for (;;) {
 .EE
 .in
 .P
+The listening socket in this example is level-triggered.
+If it is registered with
+.BR EPOLLET ,
+.BR accept (2)
+must be called in a loop until it fails with
+.BR EAGAIN :
+a single event may report several pending connections,
+and no further event is reported for those still queued
+until another connection arrives.
+.P
 When used as an edge-triggered interface, for performance reasons, it is
 possible to add the file descriptor inside the
 .B epoll

---
base-commit: c6cefe27dd02beaf518bb654493e5f09e62b3225
change-id: 20261015-epoll-et-listener-c9873cce62bc

Best regards,
-- 
Ben Kuo <ben.kuo.tw@proton.me>

[PATCH] man/man7/epoll.7: Note that an edge-triggered listener needs an accept loop

[Ben Kuo]

The example registers the listening socket as level-triggered and
calls accept(2) once per event, but doesn't say that this only works
for a level-triggered listener.  If a reader adds EPOLLET to the
listening socket in the example, connections are left in the accept
queue and the server stalls.

Tested on Linux 6.12 (Debian 13, arm64) with an echo server whose
listening socket is registered with EPOLLET, and a client that opens
2000 connections at once.  With one accept4(2) call per listener
event, the client never finishes: ss(8) shows 1420 connections left
in the accept queue (Recv-Q), while the server stays blocked in
epoll_wait(2).  With accept4(2) called in a loop until EAGAIN, all
connections are echoed.

Link: <https://github.com/benkuotw/epoll-lab>
Signed-off-by: Ben Kuo <ben.kuo.tw@proton.me>
---
 man/man7/epoll.7 | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/man/man7/epoll.7 b/man/man7/epoll.7
index 2628cbb168b499786e495cf3c614fc5e58217295..aff844a568a5cd6d8eb310ed833266a0ccfd0a4d 100644
--- a/man/man7/epoll.7
+++ b/man/man7/epoll.7
@@ -339,6 +339,16 @@ for (;;) {
 .EE
 .in
 .P
+The listening socket in this example is level-triggered.
+If it is registered with
+.BR EPOLLET ,
+.BR accept (2)
+must be called in a loop until it fails with
+.BR EAGAIN :
+a single event may report several pending connections,
+and no further event is reported for those still queued
+until another connection arrives.
+.P
 When used as an edge-triggered interface, for performance reasons, it is
 possible to add the file descriptor inside the
 .B epoll

---
base-commit: c6cefe27dd02beaf518bb654493e5f09e62b3225
change-id: 20261015-epoll-et-listener-c9873cce62bc

Best regards,
-- 
Ben Kuo <ben.kuo.tw@proton.me>

Re: [PATCH] man/man7/epoll.7: Note that an edge-triggered listener needs an accept loop

[Ben Kuo]

Hi Alejandro,

Gentle ping on this patch.

Thanks,
Ben

Re: [PATCH] man/man7/epoll.7: Note that an edge-triggered listener needs an accept loop

[Alejandro Colomar]

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

Hi Ben,

> Date: 2026-10-15 21:48:33+0800
> From: Ben Kuo via B4 Relay <devnull+ben.kuo.tw.proton.me@kernel.org>
>
> From: Ben Kuo <ben.kuo.tw@proton.me>
> 
> The example registers the listening socket as level-triggered and
> calls accept(2) once per event, but doesn't say that this only works
> for a level-triggered listener.  If a reader adds EPOLLET to the
> listening socket in the example, connections are left in the accept
> queue and the server stalls.
> 
> Tested on Linux 6.12 (Debian 13, arm64) with an echo server whose
> listening socket is registered with EPOLLET, and a client that opens
> 2000 connections at once.  With one accept4(2) call per listener
> event, the client never finishes: ss(8) shows 1420 connections left
> in the accept queue (Recv-Q), while the server stays blocked in
> epoll_wait(2).  With accept4(2) called in a loop until EAGAIN, all
> connections are echoed.
> 
> Link: <https://github.com/benkuotw/epoll-lab>
> Signed-off-by: Ben Kuo <ben.kuo.tw@proton.me>
> ---

Thanks!  I've applied the patch.


Have a lovely day!
Alex

>  man/man7/epoll.7 | 10 ++++++++++
>  1 file changed, 10 insertions(+)
> 
> diff --git a/man/man7/epoll.7 b/man/man7/epoll.7
> index 2628cbb168b499786e495cf3c614fc5e58217295..aff844a568a5cd6d8eb310ed833266a0ccfd0a4d 100644
> --- a/man/man7/epoll.7
> +++ b/man/man7/epoll.7
> @@ -339,6 +339,16 @@ for (;;) {
>  .EE
>  .in
>  .P
> +The listening socket in this example is level-triggered.
> +If it is registered with
> +.BR EPOLLET ,
> +.BR accept (2)
> +must be called in a loop until it fails with
> +.BR EAGAIN :
> +a single event may report several pending connections,
> +and no further event is reported for those still queued
> +until another connection arrives.
> +.P
>  When used as an edge-triggered interface, for performance reasons, it is
>  possible to add the file descriptor inside the
>  .B epoll
> 
> ---
> base-commit: c6cefe27dd02beaf518bb654493e5f09e62b3225
> change-id: 20261015-epoll-et-listener-c9873cce62bc
> 
> Best regards,
> -- 
> Ben Kuo <ben.kuo.tw@proton.me>
> 
> 
> 

-- 
<https://www.alejandro-colomar.es>

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