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
35 .Nd controls signals blocking with a simple memory write
41 .Fn sigfastblock "int cmd" "void *ptr"
44 This function is not intended for a direct usage by applications.
45 The functionality is provided for implementing some optimizations in
51 The function configures the kernel facility that allows a thread to
52 block asynchronous signals delivery with a single write to userspace
53 memory, avoiding overhead of system calls like
55 for establishing critical sections.
56 The C runtime uses it to optimize implementation of async-signal-safe
59 A thread might register a
63 as a location which is consulted by kernel when calculating the
64 blocked signal mask for delivery of asynchronous signals.
65 If the variable indicates that blocking is requested, then the kernel
66 effectively operates as if the mask containing all blockable signals was
70 The variable is supposed to be modified only from the owning thread,
71 there is no way to guarantee visibility of update from other thread
72 to kernel when signals are delivered.
74 Lower bits of the sigblock variable are reserved as flags,
75 which might be set or cleared by kernel at arbitrary moments.
76 Userspace code should use
78 operations of incrementing and decrementing by
80 quantity to recursively block or unblock signals delivery.
82 If a signal would be delivered when unmasked, kernel might set the
85 flag in the sigblock variable.
86 Userspace should perform
87 .Dv SIGFASTBLOCK_UNBLOCK
88 operation when clearing the variable if it notes the pending signal
89 bit is set, which would deliver the pending signals immediately.
90 Otherwise, signals delivery might be postponed.
94 argument specifies one of the following operations:
95 .Bl -tag -width SIGFASTBLOCK_UNSETPTR
96 .It Dv SIGFASTBLOCK_SETPTR
97 Register the variable of type
99 at location pointed to by the
101 argument as sigblock variable for the calling thread.
102 .It Dv SIGFASTBLOCK_UNSETPTR
103 Unregister the currently registered sigblock location.
104 Kernel stops inferring the blocked mask from non-zero value of its
106 New location can be registered after previous one is deregistered.
107 .It Dv SIGFASTBLOCK_UNBLOCK
108 If there are pending signals which should be delivered to the calling
109 thread, they are delivered before returning from the call.
110 The sigblock variable should have zero blocking count, and indicate
111 that the pending signal exists.
112 Effectively this means that the variable should have the value
113 .Dv SIGFASTBLOCK_PEND .
118 The operation may fail with the following errors:
122 .Dv SIGFASTBLOCK_SETPTR
123 attempted while the sigblock address was already registered.
125 .Dv SIGFASTBLOCK_UNBLOCK
126 was called while sigblock variable value is not equal to
127 .Dv SIGFASTBLOCK_PEND .
129 The variable address passed to
130 .Dv SIGFASTBLOCK_SETPTR
131 is not aligned naturally.
133 .Dv SIGFASTBLOCK_UNSETPTR
134 operation was attempted without prior successfull call to
135 .Dv SIGFASTBLOCK_SETPTR .
137 Attempt to read or write to the sigblock variable failed.
138 Note that kernel generates the
140 signal if an attempt to read from the sigblock variable faulted
141 during implicit accesses from syscall entry.
152 function is non-standard, although a similar functionality is a common
153 optimization provided by several other systems.
157 function was introduced in
162 symbol is currently not exported by libc, on purpose.
163 Consumers should either use the
164 .Dv __sys_fast_sigblock
165 symbol from the private libc namespace, or utilize