mirror of
https://github.com/freebsd/freebsd-src.git
synced 2026-10-28 11:25:21 +01:00
82 lines
2.4 KiB
Plaintext
82 lines
2.4 KiB
Plaintext
.\" Copyright (c) 2025 The FreeBSD Foundation
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" SPDX-License-Identifier: BSD-2-Clause
|
|
.\"
|
|
.\" This documentation was written by
|
|
.\" Konstantin Belousov <[email protected]> under sponsorship
|
|
.\" from the FreeBSD Foundation.
|
|
.\"
|
|
.Dd May 16, 2025
|
|
.Dt PTHREAD_SIGNALS_BLOCK_NP 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm pthread_signals_block_np ,
|
|
.Nm pthread_signals_unblock_np
|
|
.Nd fast asynchronous signals blocking and unblocking
|
|
.Sh LIBRARY
|
|
.Lb libpthread
|
|
.Sh SYNOPSIS
|
|
.In pthread_np.h
|
|
.Ft void
|
|
.Fn pthread_signals_block_np "void"
|
|
.Ft void
|
|
.Fn pthread_signals_unblock_np "void"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Fn pthread_signals_block_np
|
|
and
|
|
.Fn pthread_signals_unblock_np
|
|
functions provide user programs an interface to the fast asynchronous
|
|
signals blocking facility
|
|
.Xr sigfastblock 2 .
|
|
.Pp
|
|
Blocking signals with
|
|
.Fn pthread_signals_block_np
|
|
disables delivery of any asynchronous signal, until unblocked.
|
|
Signal blocking establishes a critical section where the execution
|
|
flow of the thread cannot be diverted into a signal handler.
|
|
Blocking signals is fast, it is performed by a single memory write into
|
|
a location established with the kernel.
|
|
.Pp
|
|
Synchronous signal delivery cannot be blocked in general, including with
|
|
these functions.
|
|
.Pp
|
|
The blocked state established by the
|
|
.Fn pthread_signals_block_np
|
|
is not completely POSIX-compliant.
|
|
Specifically, system calls executed while in a blocked section,
|
|
might abort sleep and return
|
|
.Er EINTR
|
|
upon queuing of an asynchronous signal to the thread,
|
|
but the signal handler is not called until the last unblock is done.
|
|
.Pp
|
|
Calls to
|
|
.Nm pthread_signals_block_np
|
|
can be nested, and must be complemented by an equal count of
|
|
calls to
|
|
.Nm pthread_signals_unblock_np
|
|
to return the calling thread to the standard mode of signal receiving.
|
|
.Pp
|
|
An example use of these function might be the construction of the CPU
|
|
state that cannot be done atomically, and which includes stages where
|
|
the state of the thread is not ABI compliant.
|
|
If a signal is delivered while such state is not yet finished, signal
|
|
handlers would misbehave.
|
|
Using standard functions
|
|
.Pq Fn sigprocmask
|
|
to establish critical section might be much slower, because
|
|
.Fn sigprocmask
|
|
is system call, while
|
|
.Fn pthread_signals_block_np
|
|
consists of a single atomic memory write.
|
|
.Sh RETURN VALUES
|
|
The functions do not return a value.
|
|
.Sh ERRORS
|
|
There are no errors reported by the functions.
|
|
.Sh SEE ALSO
|
|
.Xr sigfastblock 2 ,
|
|
.Xr sigprocmask 2 ,
|
|
.Xr pthread_np 3 ,
|
|
.Xr pthread_sigmask 3
|