lib/libc/sys/sigfastblock.2

   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
  42 This function is not intended for a direct usage by applications.
  43 The functionality is provided for implementing some optimizations in
  44 .Xr ld-elf.so.1 8
  45 and
  46 .Lb libthr .
  47 .Ef
  48 .Pp
  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
  52 .Xr sigprocmask 2
  53 for establishing critical sections.
  54 The C runtime uses it to optimize implementation of async-signal-safe
  55 functionality.
  56 .Pp
  57 A thread might register a
  58 .Dv sigblock
  59 variable of type
  60 .Vt int
  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
  65 supplied to
  66 .Xr sigprocmask 2 .
  67 .Pp
  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.
  71 .Pp
  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
  75 .Xr atomic 9
  76 operations of incrementing and decrementing by
  77 .Dv SIGFASTBLOCK_INC
  78 quantity to recursively block or unblock signals delivery.
  79 .Pp
  80 If a signal would be delivered when unmasked, kernel might set the
  81 .Dv SIGFASTBLOCK_PEND
  82 .Dq pending signal
  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.
  89 .Pp
  90 The
  91 .Fa cmd
  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
  96 .Vt int
  97 at location pointed to by the
  98 .Fa ptr
  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
 103 blocked count.
 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 .
 112 .El
 113 .Sh RETURN VALUES
 114 .Rv -std
 115 .Sh ERRORS
 116 The operation may fail with the following errors:
 117 .Bl -tag -width Er
 118 .It Bq Er EBUSY
 119 The
 120 .Dv SIGFASTBLOCK_SETPTR
 121 attempted while the sigblock address was already registered.
 122 The
 123 .Dv SIGFASTBLOCK_UNBLOCK
 124 was called while sigblock variable value is not equal to
 125 .Dv SIGFASTBLOCK_PEND .
 126 .It Bq Er EINVAL
 127 The variable address passed to
 128 .Dv SIGFASTBLOCK_SETPTR
 129 is not aligned naturally.
 130 The
 131 .Dv SIGFASTBLOCK_UNSETPTR
 132 operation was attempted without prior successfull call to
 133 .Dv SIGFASTBLOCK_SETPTR .
 134 .It Bq Er EFAULT
 135 Attempt to read or write to the sigblock variable failed.
 136 Note that kernel generates the
 137 .Dv SIGSEGV
 138 signal if an attempt to read from the sigblock variable faulted
 139 during 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
 148 The
 149 .Nm
 150 function is non-standard, although a similar functionality is a common
 151 optimization provided by several other systems.
 152 .Sh HISTORY
 153 The
 154 .Nm
 155 function was introduced in
 156 .Fx 13.0 .
 157 .Sh BUGS
 158 The
 159 .Nm
 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
 164 .Xr syscall 2 .