epoll_ctl.2: BUGS: EPOLLWAKEUP is silently ignored without CAP_BLOCK_SUSPEND

If the caller does not have CAP_BLOCK_SUSPEND, then EPOLLWAKEUP
is silently ignored.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

man2/epoll_ctl.2

@@ -174,6 +174,7 @@ until the next call to
 on the same
 .BR epoll (7)
 file descriptor.
+See also BUGS.
 .SH RETURN VALUE
 When successful,
 .BR epoll_ctl ()
@@ -270,6 +271,33 @@ when using
 Applications that need to be portable to kernels before 2.6.9
 should specify a non-null pointer in
 .IR event .
+
+If
+.B EPOLLWAKEUP
+is specified in
+.IR flags ,
+but the caller does not have the
+.BR CAP_BLOCK_SUSPEND
+capability, then the
+.B EPOLLWAKEUP
+flag is
+.IR "silently ignored" .
+This unfortunate behavior is necessary because no validity
+checks were performed on the
+.IR flags
+argument in the original implementation, and the addition of the
+.B EPOLLWAKEUP
+with a check that caused the call to fail if the caller did not have the
+.B CAP_BLOCK_SUSPEND
+capability caused a breakage in at least one existing user-space
+application that happened to randomly (and uselessly) specify this bit.
+.\" commit a8159414d7e3af7233e7a5a82d1c5d85379bd75c (behavior change)
+.\" https://lwn.net/Articles/520198/
+A robust application should therefore double check that it has the
+.B CAP_BLOCK_SUSPEND
+capability if attempting to use the
+.B EPOLLWAKEUP
+flag.
 .SH SEE ALSO
 .BR epoll_create (2),
 .BR epoll_wait (2),