From: deraadt Date: Fri, 12 Jul 2024 11:01:40 +0000 (+0000) Subject: Improve signal handlers guidance. X-Git-Url: http://artulab.com/gitweb/?a=commitdiff_plain;h=0e9fb06b3ef2efde53227eac919879babe4c5adb;p=openbsd Improve signal handlers guidance. ok beck kettenis, earlier versions jmc --- 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