1.\" Copyright (c) 2016 The FreeBSD Foundation, Inc. 2.\" 3.\" This documentation was written by 4.\" Konstantin Belousov <kib@FreeBSD.org> 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.Dd December 13, 2019 29.Dt SIGFASTBLOCK 2 30.Os 31.Sh NAME 32.Nm sigfastblock 33.Nd controls signals blocking with a simple memory write 34.Sh LIBRARY 35.Lb libc 36.Sh SYNOPSIS 37.In sys/signalvar.h 38.Ft int 39.Fn sigfastblock "int cmd" "void *ptr" 40.Sh DESCRIPTION 41.Bf -symbolic 42This function is not intended for a direct usage by applications. 43The functionality is provided for implementing some optimizations in 44.Xr ld-elf.so.1 8 45and 46.Lb libthr . 47.Ef 48.Pp 49The function configures the kernel facility that allows a thread to 50block asynchronous signals delivery with a single write to userspace 51memory, avoiding overhead of system calls like 52.Xr sigprocmask 2 53for establishing critical sections. 54The C runtime uses it to optimize implementation of async-signal-safe 55functionality. 56.Pp 57A thread might register a 58.Dv sigblock 59variable of type 60.Vt int 61as a location which is consulted by kernel when calculating the 62blocked signal mask for delivery of asynchronous signals. 63If the variable indicates that blocking is requested, then the kernel 64effectively operates as if the mask containing all blockable signals was 65supplied to 66.Xr sigprocmask 2 . 67.Pp 68The variable is supposed to be modified only from the owning thread, 69there is no way to guarantee visibility of update from other thread 70to kernel when signals are delivered. 71.Pp 72Lower bits of the sigblock variable are reserved as flags, 73which might be set or cleared by kernel at arbitrary moments. 74Userspace code should use 75.Xr atomic 9 76operations of incrementing and decrementing by 77.Dv SIGFASTBLOCK_INC 78quantity to recursively block or unblock signals delivery. 79.Pp 80If a signal would be delivered when unmasked, kernel might set the 81.Dv SIGFASTBLOCK_PEND 82.Dq pending signal 83flag in the sigblock variable. 84Userspace should perform 85.Dv SIGFASTBLOCK_UNBLOCK 86operation when clearing the variable if it notes the pending signal 87bit is set, which would deliver the pending signals immediately. 88Otherwise, signals delivery might be postponed. 89.Pp 90The 91.Fa cmd 92argument specifies one of the following operations: 93.Bl -tag -width SIGFASTBLOCK_UNSETPTR 94.It Dv SIGFASTBLOCK_SETPTR 95Register the variable of type 96.Vt int 97at location pointed to by the 98.Fa ptr 99argument as sigblock variable for the calling thread. 100.It Dv SIGFASTBLOCK_UNSETPTR 101Unregister the currently registered sigblock location. 102Kernel stops inferring the blocked mask from non-zero value of its 103blocked count. 104New location can be registered after previous one is deregistered. 105.It Dv SIGFASTBLOCK_UNBLOCK 106If there are pending signals which should be delivered to the calling 107thread, they are delivered before returning from the call. 108The sigblock variable should have zero blocking count, and indicate 109that the pending signal exists. 110Effectively this means that the variable should have the value 111.Dv SIGFASTBLOCK_PEND . 112.El 113.Sh RETURN VALUES 114.Rv -std 115.Sh ERRORS 116The operation may fail with the following errors: 117.Bl -tag -width Er 118.It Bq Er EBUSY 119The 120.Dv SIGFASTBLOCK_SETPTR 121attempted while the sigblock address was already registered. 122The 123.Dv SIGFASTBLOCK_UNBLOCK 124was called while sigblock variable value is not equal to 125.Dv SIGFASTBLOCK_PEND . 126.It Bq Er EINVAL 127The variable address passed to 128.Dv SIGFASTBLOCK_SETPTR 129is not aligned naturally. 130The 131.Dv SIGFASTBLOCK_UNSETPTR 132operation was attempted without prior successful call to 133.Dv SIGFASTBLOCK_SETPTR . 134.It Bq Er EFAULT 135Attempt to read or write to the sigblock variable failed. 136Note that kernel generates the 137.Dv SIGSEGV 138signal if an attempt to read from the sigblock variable faulted 139during implicit accesses from syscall entry. 140.El 141.Sh SEE ALSO 142.Xr kill 2 , 143.Xr signal 2 , 144.Xr sigprocmask 2 , 145.Xr libthr 3 , 146.Xr ld-elf.so.1 8 147.Sh STANDARDS 148The 149.Nm 150function is non-standard, although a similar functionality is a common 151optimization provided by several other systems. 152.Sh HISTORY 153The 154.Nm 155function was introduced in 156.Fx 13.0 . 157.Sh BUGS 158The 159.Nm 160symbol is currently not exported by libc, on purpose. 161Consumers should either use the 162.Dv __sys_fast_sigblock 163symbol from the private libc namespace, or utilize 164.Xr syscall 2 . 165