-.\" $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.
.\" 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
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
.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)
}
.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
-.\" $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
.\"
.\" @(#)sigaction.2 8.2 (Berkeley) 4/3/94
.\"
-.Dd $Mdocdate: October 13 2022 $
+.Dd $Mdocdate: July 12 2024 $
.Dt SIGACTION 2
.Os
.Sh NAME
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
.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)
}
.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
projects / openbsd / commitdiff