1 .\" Copyright (c) 2016 The FreeBSD Foundation, Inc.
3 .\" This documentation was written by
4 .\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship
5 .\" from the FreeBSD Foundation.
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
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.
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
33 .Nd controls signals blocking with a simple memory write
39 .Fn sigfastblock "int cmd" "void *ptr"
42 This function is not intended for a direct usage by applications.
43 The functionality is provided for implementing some optimizations in
49 The function configures the kernel facility that allows a thread to
50 block asynchronous signals delivery with a single write to userspace
51 memory, avoiding overhead of system calls like
53 for establishing critical sections.
54 The C runtime uses it to optimize implementation of async-signal-safe
57 A thread might register a
61 as a location which is consulted by kernel when calculating the
62 blocked signal mask for delivery of asynchronous signals.
63 If the variable indicates that blocking is requested, then the kernel
64 effectively operates as if the mask containing all blockable signals was
68 The variable is supposed to be modified only from the owning thread,
69 there is no way to guarantee visibility of update from other thread
70 to kernel when signals are delivered.
72 Lower bits of the sigblock variable are reserved as flags,
73 which might be set or cleared by kernel at arbitrary moments.
74 Userspace code should use
76 operations of incrementing and decrementing by
78 quantity to recursively block or unblock signals delivery.
80 If a signal would be delivered when unmasked, kernel might set the
83 flag in the sigblock variable.
84 Userspace should perform
85 .Dv SIGFASTBLOCK_UNBLOCK
86 operation when clearing the variable if it notes the pending signal
87 bit is set, which would deliver the pending signals immediately.
88 Otherwise, signals delivery might be postponed.
92 argument specifies one of the following operations:
93 .Bl -tag -width SIGFASTBLOCK_UNSETPTR
94 .It Dv SIGFASTBLOCK_SETPTR
95 Register the variable of type
97 at location pointed to by the
99 argument as sigblock variable for the calling thread.
100 .It Dv SIGFASTBLOCK_UNSETPTR
101 Unregister the currently registered sigblock location.
102 Kernel stops inferring the blocked mask from non-zero value of its
104 New location can be registered after previous one is deregistered.
105 .It Dv SIGFASTBLOCK_UNBLOCK
106 If there are pending signals which should be delivered to the calling
107 thread, they are delivered before returning from the call.
108 The sigblock variable should have zero blocking count, and indicate
109 that the pending signal exists.
110 Effectively this means that the variable should have the value
111 .Dv SIGFASTBLOCK_PEND .
116 The operation may fail with the following errors:
120 .Dv SIGFASTBLOCK_SETPTR
121 attempted while the sigblock address was already registered.
123 .Dv SIGFASTBLOCK_UNBLOCK
124 was called while sigblock variable value is not equal to
125 .Dv SIGFASTBLOCK_PEND .
127 The variable address passed to
128 .Dv SIGFASTBLOCK_SETPTR
129 is not aligned naturally.
131 .Dv SIGFASTBLOCK_UNSETPTR
132 operation was attempted without prior successfull call to
133 .Dv SIGFASTBLOCK_SETPTR .
135 Attempt to read or write to the sigblock variable failed.
136 Note that kernel generates the
138 signal if an attempt to read from the sigblock variable faulted
139 during implicit accesses from syscall entry.
150 function is non-standard, although a similar functionality is a common
151 optimization provided by several other systems.
155 function was introduced in
160 symbol is currently not exported by libc, on purpose.
161 Consumers should either use the
162 .Dv __sys_fast_sigblock
163 symbol from the private libc namespace, or utilize