Improve signal handlers guidance.

ok beck kettenis, earlier versions jmc

2 files changed, 52 insertions, 48 deletions

diff --git a/lib/libc/gen/signal.3 b/lib/libc/gen/signal.3
index 52de1a7384a..a3c4f065c28 100644
--- a/lib/libc/gen/signal.3
+++ b/lib/libc/gen/signal.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: signal.3,v 1.57 2022/10/13 21:37:05 jmc Exp $
+.\"	$OpenBSD: signal.3,v 1.58 2024/07/12 11:01:40 deraadt Exp $
 .\"
 .\" Copyright (c) 1980, 1991, 1993
 .\"	The Regents of the University of California.  All rights reserved.
@@ -27,7 +27,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: October 13 2022 $
+.Dd $Mdocdate: July 12 2024 $
 .Dt SIGNAL 3
 .Os
 .Sh NAME
@@ -240,10 +240,22 @@ function;
 other
 ignored signals remain ignored.
 .Pp
-The following functions are either reentrant or not interruptible
-by signals and are async-signal-safe.
-Therefore applications may
-invoke them, without restriction, from signal-catching functions:
+Signal handlers should be as minimal as possible, and use only signal-safe
+operations.
+The safest handlers only change a single variable of type
+.Va volatile sig_atomic_t ,
+which is inspected by an event loop.
+Other variables accessed inside the handler must be either const, or
+local to the handler.
+More complicated global variables (such as strings, structs, or lists)
+will require external methods to gaurantee consistancy, such as
+signal-blocking with
+.Xr sigprocmask 2 .
+.Pp
+More complicated handlers must restrict themselves to calling only the following
+list of signal-safe functions directly.
+Avoid abstracting the work to helper functions which are also called from
+other contexts because future coders will forget the signal-safe requirement.
 .Pp
 Standard Interfaces:
 .Pp
@@ -418,21 +430,9 @@ Extension Interfaces:
 .Fn wait3 ,
 .Fn wait4 .
 .Pp
-In addition, access and updates to
-.Va errno
-are guaranteed to be safe.
-Most functions not in the above lists are considered to be unsafe
-with respect to signals.
-That is to say, the behaviour of such functions when called from
-a signal handler is undefined.
-In general though, signal handlers should do little more than set a
-flag, ideally of type volatile sig_atomic_t; most other actions are not safe.
-.Pp
-Additionally, it is advised that signal handlers guard against
-modification of the external symbol
+Since signal-safe functions can encounter system call errors,
 .Va errno
-by the above functions, saving it at entry and restoring
-it on return, thus:
+should be protected inside the handler with the following pattern:
 .Bd -literal -offset indent
 void
 handler(int sig)
@@ -444,10 +444,12 @@ handler(int sig)
 }
 .Ed
 .Pp
-The functions below are async-signal-safe in
-.Ox
-except when used with floating-point arguments or directives,
-but are probably unsafe on other systems:
+On
+.Ox ,
+a few more functions are signal-safe (except when the format string contains
+floating-point arguments).
+These functions are expected to be unsafe on other systems, so be very cautious of
+the portability trap!
 .Pp
 .Bl -tag -offset indent -compact -width foofoofoofoo
 .It Fn dprintf
diff --git a/lib/libc/sys/sigaction.2 b/lib/libc/sys/sigaction.2
index 7e821468c60..edcd3e3eefd 100644
--- a/lib/libc/sys/sigaction.2
+++ b/lib/libc/sys/sigaction.2
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: sigaction.2,v 1.77 2022/10/13 21:37:05 jmc Exp $
+.\"	$OpenBSD: sigaction.2,v 1.78 2024/07/12 11:01:40 deraadt Exp $
 .\"	$NetBSD: sigaction.2,v 1.7 1995/10/12 15:41:16 jtc Exp $
 .\"
 .\" Copyright (c) 1980, 1990, 1993
@@ -30,7 +30,7 @@
 .\"
 .\"	@(#)sigaction.2	8.2 (Berkeley) 4/3/94
 .\"
-.Dd $Mdocdate: October 13 2022 $
+.Dd $Mdocdate: July 12 2024 $
 .Dt SIGACTION 2
 .Os
 .Sh NAME
@@ -471,10 +471,22 @@ and other signal interfaces may reject attempts to use or alter the
 handling of
 .Dv SIGTHR .
 .Pp
-The following functions are either reentrant or not interruptible
-by signals and are async-signal-safe.
-Therefore applications may
-invoke them, without restriction, from signal-catching functions:
+Signal handlers should be as minimal as possible, and use only signal-safe
+operations.
+The safest handlers only change a single variable of type
+.Va volatile sig_atomic_t ,
+which is inspected by an event loop.
+Other variables accessed inside the handler must be either const, or
+local to the handler.
+More complicated global variables (such as strings, structs, or lists)
+will require external methods to gaurantee consistancy, such as
+signal-blocking with
+.Xr sigprocmask 2 .
+.Pp
+More complicated handlers must restrict themselves to calling only the following
+list of signal-safe functions directly.
+Avoid abstracting the work to helper functions which are also called from
+other contexts because future coders will forget the signal-safe requirement.
 .Pp
 Standard Interfaces:
 .Pp
@@ -649,21 +661,9 @@ Extension Interfaces:
 .Fn wait3 ,
 .Fn wait4 .
 .Pp
-In addition, access and updates to
-.Va errno
-are guaranteed to be safe.
-Most functions not in the above lists are considered to be unsafe
-with respect to signals.
-That is to say, the behaviour of such functions when called from
-a signal handler is undefined.
-In general though, signal handlers should do little more than set a
-flag, ideally of type volatile sig_atomic_t; most other actions are not safe.
-.Pp
-Additionally, it is advised that signal handlers guard against
-modification of the external symbol
+Since signal-safe functions can encounter system call errors,
 .Va errno
-by the above functions, saving it at entry and restoring
-it on return, thus:
+should be protected inside the handler with the following pattern:
 .Bd -literal -offset indent
 void
 handler(int sig)
@@ -675,10 +675,12 @@ handler(int sig)
 }
 .Ed
 .Pp
-The functions below are async-signal-safe in
-.Ox
-except when used with floating-point arguments or directives,
-but are probably unsafe on other systems:
+On
+.Ox ,
+a few more functions are signal-safe (except when the format string contains
+floating-point arguments).
+These functions are expected to be unsafe on other systems, so be very cautious of
+the portability trap!
 .Pp
 .Bl -tag -offset indent -compact -width foofoofoofoo
 .It Fn dprintf