gh-131803: Clarify that you must register signal handlers for set_wakeup_fd (#131859)

diff --git a/Doc/library/signal.rst b/Doc/library/signal.rst
index 17fcb2b3707978854deda040c6d1f9b582e9e208..c28841dbb8cfc89bf5002850937585558b58cc60 100644 (file)
--- a/Doc/library/signal.rst
+++ b/Doc/library/signal.rst
@@ -510,10 +510,12 @@ The :mod:`signal` module defines the following functions:
 
 .. function:: set_wakeup_fd(fd, *, warn_on_full_buffer=True)
 
-   Set the wakeup file descriptor to *fd*.  When a signal is received, the
-   signal number is written as a single byte into the fd.  This can be used by
-   a library to wakeup a poll or select call, allowing the signal to be fully
-   processed.
+   Set the wakeup file descriptor to *fd*.  When a signal your program has
+   registered a signal handler for is received, the signal number is written as
+   a single byte into the fd.  If you haven't registered a signal handler for
+   the signals you care about, then nothing will be written to the wakeup fd.
+   This can be used by a library to wakeup a poll or select call, allowing the
+   signal to be fully processed.
 
    The old wakeup fd is returned (or -1 if file descriptor wakeup was not
    enabled).  If *fd* is -1, file descriptor wakeup is disabled.