xref: /dflybsd-src/lib/libc/upmap/sigblockall.3 (revision 020a87849405163b7dd0ac75005db634e075ab70)
1ea59862cSMatthew Dillon.\" Copyright (c) 2019 The DragonFly Project.  All rights reserved.
2ea59862cSMatthew Dillon.\"
3ea59862cSMatthew Dillon.\" This code is derived from software contributed to The DragonFly Project
4ea59862cSMatthew Dillon.\" by Matthew Dillon <dillon@backplane.com>.
5ea59862cSMatthew Dillon.\"
6ea59862cSMatthew Dillon.\" Redistribution and use in source and binary forms, with or without
7ea59862cSMatthew Dillon.\" modification, are permitted provided that the following conditions
8ea59862cSMatthew Dillon.\" are met:
9ea59862cSMatthew Dillon.\"
10ea59862cSMatthew Dillon.\" 1. Redistributions of source code must retain the above copyright
11ea59862cSMatthew Dillon.\"    notice, this list of conditions and the following disclaimer.
12ea59862cSMatthew Dillon.\" 2. Redistributions in binary form must reproduce the above copyright
13ea59862cSMatthew Dillon.\"    notice, this list of conditions and the following disclaimer in
14ea59862cSMatthew Dillon.\"    the documentation and/or other materials provided with the
15ea59862cSMatthew Dillon.\"    distribution.
16ea59862cSMatthew Dillon.\" 3. Neither the name of The DragonFly Project nor the names of its
17ea59862cSMatthew Dillon.\"    contributors may be used to endorse or promote products derived
18ea59862cSMatthew Dillon.\"    from this software without specific, prior written permission.
19ea59862cSMatthew Dillon.\"
20ea59862cSMatthew Dillon.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
21ea59862cSMatthew Dillon.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
22ea59862cSMatthew Dillon.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
23ea59862cSMatthew Dillon.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
24ea59862cSMatthew Dillon.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
25ea59862cSMatthew Dillon.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
26ea59862cSMatthew Dillon.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
27ea59862cSMatthew Dillon.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
28ea59862cSMatthew Dillon.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
29ea59862cSMatthew Dillon.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
30ea59862cSMatthew Dillon.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
31ea59862cSMatthew Dillon.\" SUCH DAMAGE.
32ea59862cSMatthew Dillon.\"
33ea59862cSMatthew Dillon.Dd November 12, 2019
34ea59862cSMatthew Dillon.Dt SIGBLOCKALL 3
35ea59862cSMatthew Dillon.Os
36ea59862cSMatthew Dillon.Sh NAME
37ea59862cSMatthew Dillon.Nm sigblockall ,
38ea59862cSMatthew Dillon.Nm sigunblockall
39*020a8784SSascha Wildner.Nd quickly block and unblock all maskable signals
40ea59862cSMatthew Dillon.Sh LIBRARY
41ea59862cSMatthew Dillon.Lb libc
42ea59862cSMatthew Dillon.Sh SYNOPSIS
43ea59862cSMatthew Dillon.In signal.h
44ea59862cSMatthew Dillon.Ft int
45ea59862cSMatthew Dillon.Fn sigblockall "void"
46ea59862cSMatthew Dillon.Ft int
47ea59862cSMatthew Dillon.Fn sigunblockall "void"
48ea59862cSMatthew Dillon.Sh DESCRIPTION
49ea59862cSMatthew DillonThese functions operate on a per-thread basis and temporarily prevent
50ea59862cSMatthew Dillonsignal posts to the calling thread, protecting the function from
51ea59862cSMatthew Dillonpotential reentrancy issues due to signal interruption.
52ea59862cSMatthew DillonThe signal mask is not modified in any way and synchronous signals
53*020a8784SSascha Wildnercaused by traps (such as
54*020a8784SSascha Wildner.Dv SIGSEGV )
55*020a8784SSascha Wildnerwill still be immediately posted.
56ea59862cSMatthew Dillon.Pp
57ea59862cSMatthew DillonThese functions operate via the /dev/lpmap per-thread shared page facility
58ea59862cSMatthew Dillonand, once primed, will operate without having to issue any system calls.
59ea59862cSMatthew DillonThey are designed to be very fast, typically sub-10nS.
60ea59862cSMatthew Dillon.Pp
61ea59862cSMatthew DillonThe
62ea59862cSMatthew Dillon.Fn sigblockall
63*020a8784SSascha Wildnerprocedure temporarily blocks the posting of any maskable signal.
64*020a8784SSascha Wildner.Dv SIGSTOP
65*020a8784SSascha Wildnerand
66*020a8784SSascha Wildner.Dv SIGKILL
67*020a8784SSascha Wildnerare not maskable and will still be delivered, as will any
68*020a8784SSascha Wildnersignals caused by synchronous traps.
69*020a8784SSascha WildnerThis facility does not prevent
70ea59862cSMatthew Dillonsignals from being delivered to the thread, it simply prevents the signals
71ea59862cSMatthew Dillonfrom being posted to (interrupting) the thread.
72ea59862cSMatthew Dillon.Pp
73ea59862cSMatthew DillonCallers must pair all calls to
74ea59862cSMatthew Dillon.Fn sigblockall
75ea59862cSMatthew Dillonwith calls to
76ea59862cSMatthew Dillon.Fn sigunblockall .
77ea59862cSMatthew DillonThese functions may be used recursively.
78ea59862cSMatthew Dillon.Pp
79ea59862cSMatthew DillonThe
80ea59862cSMatthew Dillon.Fn sigunblockall
81*020a8784SSascha Wildnerprocedure unwinds the operation.
82*020a8784SSascha WildnerOn the last transition, any blocked
83ea59862cSMatthew Dillonsignals not otherwise masked through the normal signal mask will be
84ea59862cSMatthew Dillonimmediately posted prior to the function returning.
85ea59862cSMatthew Dillon.Sh RETURN VALUES
86ea59862cSMatthew DillonBoth procedures return the recursive blocking count's value after
87ea59862cSMatthew Dillonthe operation.
88ea59862cSMatthew DillonThus the first call to
89ea59862cSMatthew Dillon.Fn sigblockall
90ea59862cSMatthew Dillonwill generally return the value 1 and the last call to
91ea59862cSMatthew Dillon.Fn sigunblockall
92ea59862cSMatthew Dillonwill generally return the value 0.
93ea59862cSMatthew Dillon.Pp
94ea59862cSMatthew DillonThe returned value may have bit 31 set, resulting in a negative number.
95ea59862cSMatthew DillonBit 31 set indicates that one or more signals may have been blocked from
96ea59862cSMatthew Dillonbeing posted and represents cumulative state until the last call to
97ea59862cSMatthew Dillon.Fn sigunblockall .
98ea59862cSMatthew Dillon.Pp
99ea59862cSMatthew DillonIf bit 31 is set in the value returned by the last call to
100ea59862cSMatthew Dillon.Fn sigunblockall ,
101ea59862cSMatthew Dillonit is an indication that signals were previously blocked and have now
102*020a8784SSascha Wildnerbeen posted.
103*020a8784SSascha WildnerBit 31 will be cleared in libc's internal state
104ea59862cSMatthew Dillonfor the calling thread on the last call.
105ea59862cSMatthew Dillon.Sh WARNINGS
106ea59862cSMatthew DillonAny blocking count for the current thread present as-of any
107ea59862cSMatthew Dillon.Xr fork 2
108ea59862cSMatthew Dillonor
109ea59862cSMatthew Dillon.Xr vfork 2
110*020a8784SSascha Wildnerwill be inherited by the child and must be unwound in both parent and child.
111*020a8784SSascha WildnerThis also allows programs to conveniently prevent signal delivery
112ea59862cSMatthew Dillonin a new child process until they are ready to deal with it, if desired.
113ea59862cSMatthew Dillon.Pp
114ea59862cSMatthew DillonCare must be taken if coupling the use of these functions with the
115*020a8784SSascha Wildnerlongjmp and ucontext facilities.
116*020a8784SSascha WildnerThe blocking count is associated with the thread, NOT the context.
117ea59862cSMatthew Dillon.Sh ERRORS
118ea59862cSMatthew DillonThese functions return -1 on error, which can only occur if the
119ea59862cSMatthew Dillon.Pa /dev/lpmap
120*020a8784SSascha Wildnerfacility is not available.
121*020a8784SSascha WildnerHowever, generally speaking, because these
122ea59862cSMatthew Dillonprocedures are meant to be used in critical code paths, callers are not
123ea59862cSMatthew Dillonexpected to check for this failure condition in critical code paths.
124ea59862cSMatthew DillonDetecting support can be done at the start of the program, if desired,
125ea59862cSMatthew Dillonsimply by issuing the function pair and retaining the result.
126ea59862cSMatthew Dillon.Sh SEE ALSO
127ea59862cSMatthew Dillon.Xr sigprocmask 2
128ea59862cSMatthew Dillon.Sh HISTORY
129ea59862cSMatthew DillonThe
130ea59862cSMatthew Dillon.Fn sigblockall
131ea59862cSMatthew Dillonfamiliy of functions first appeared in
132ea59862cSMatthew Dillon.Dx 5.7 .
133