1.\" Copyright (c) 2016 The FreeBSD Foundation, Inc. 2.\" 3.\" This documentation was written by 4.\" Konstantin Belousov <[email protected]> under sponsorship 5.\" from the FreeBSD Foundation. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 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 the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" $FreeBSD$ 29.\" 30.Dd December 13, 2019 31.Dt SIGFASTBLOCK 2 32.Os 33.Sh NAME 34.Nm sigfastblock 35.Nd controls signals blocking with a simple memory write 36.Sh LIBRARY 37.Lb libc 38.Sh SYNOPSIS 39.In sys/signalvar.h 40.Ft int 41.Fn sigfastblock "int cmd" "void *ptr" 42.Sh DESCRIPTION 43.Bf -symbolic 44This function is not intended for a direct usage by applications. 45The functionality is provided for implementing some optimizations in 46.Xr ld-elf.so.1 8 47and 48.Lb libthr . 49.Ef 50.Pp 51The function configures the kernel facility that allows a thread to 52block asynchronous signals delivery with a single write to userspace 53memory, avoiding overhead of system calls like 54.Xr sigprocmask 2 55for establishing critical sections. 56The C runtime uses it to optimize implementation of async-signal-safe 57functionality. 58.Pp 59A thread might register a 60.Dv sigblock 61variable of type 62.Vt int 63as a location which is consulted by kernel when calculating the 64blocked signal mask for delivery of asynchronous signals. 65If the variable indicates that blocking is requested, then the kernel 66effectively operates as if the mask containing all blockable signals was 67supplied to 68.Xr sigprocmask 2 . 69.Pp 70The variable is supposed to be modified only from the owning thread, 71there is no way to guarantee visibility of update from other thread 72to kernel when signals are delivered. 73.Pp 74Lower bits of the sigblock variable are reserved as flags, 75which might be set or cleared by kernel at arbitrary moments. 76Userspace code should use 77.Xr atomic 9 78operations of incrementing and decrementing by 79.Dv SIGFASTBLOCK_INC 80quantity to recursively block or unblock signals delivery. 81.Pp 82If a signal would be delivered when unmasked, kernel might set the 83.Dv SIGFASTBLOCK_PEND 84.Dq pending signal 85flag in the sigblock variable. 86Userspace should perform 87.Dv SIGFASTBLOCK_UNBLOCK 88operation when clearing the variable if it notes the pending signal 89bit is set, which would deliver the pending signals immediately. 90Otherwise, signals delivery might be postponed. 91.Pp 92The 93.Fa cmd 94argument specifies one of the following operations: 95.Bl -tag -width SIGFASTBLOCK_UNSETPTR 96.It Dv SIGFASTBLOCK_SETPTR 97Register the variable of type 98.Vt int 99at location pointed to by the 100.Fa ptr 101argument as sigblock variable for the calling thread. 102.It Dv SIGFASTBLOCK_UNSETPTR 103Unregister the currently registered sigblock location. 104Kernel stops inferring the blocked mask from non-zero value of its 105blocked count. 106New location can be registered after previous one is deregistered. 107.It Dv SIGFASTBLOCK_UNBLOCK 108If there are pending signals which should be delivered to the calling 109thread, they are delivered before returning from the call. 110The sigblock variable should have zero blocking count, and indicate 111that the pending signal exists. 112Effectively this means that the variable should have the value 113.Dv SIGFASTBLOCK_PEND . 114.El 115.Sh RETURN VALUES 116.Rv -std 117.Sh ERRORS 118The operation may fail with the following errors: 119.Bl -tag -width Er 120.It Bq Er EBUSY 121The 122.Dv SIGFASTBLOCK_SETPTR 123attempted while the sigblock address was already registered. 124The 125.Dv SIGFASTBLOCK_UNBLOCK 126was called while sigblock variable value is not equal to 127.Dv SIGFASTBLOCK_PEND . 128.It Bq Er EINVAL 129The variable address passed to 130.Dv SIGFASTBLOCK_SETPTR 131is not aligned naturally. 132The 133.Dv SIGFASTBLOCK_UNSETPTR 134operation was attempted without prior successfull call to 135.Dv SIGFASTBLOCK_SETPTR . 136.It Bq Er EFAULT 137Attempt to read or write to the sigblock variable failed. 138Note that kernel generates the 139.Dv SIGSEGV 140signal if an attempt to read from the sigblock variable faulted 141during implicit accesses from syscall entry. 142.El 143.Sh SEE ALSO 144.Xr kill 2 , 145.Xr signal 2 , 146.Xr sigprocmask 2 , 147.Xr libthr 3 , 148.Xr ld-elf.so.1 8 149.Sh STANDARDS 150The 151.Nm 152function is non-standard, although a similar functionality is a common 153optimization provided by several other systems. 154.Sh HISTORY 155The 156.Nm 157function was introduced in 158.Fx 13.0 . 159.Sh BUGS 160The 161.Nm 162symbol is currently not exported by libc, on purpose. 163Consumers should either use the 164.Dv __sys_fast_sigblock 165symbol from the private libc namespace, or utilize 166.Xr syscall 2 . 167