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