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