mirror of
https://sourceware.org/git/glibc.git
synced 2025-10-30 10:45:40 +03:00
124 lines
3.7 KiB
Groff
124 lines
3.7 KiB
Groff
.TH PTHREAD_SIGNAL 3 LinuxThreads
|
|
|
|
.XREF pthread_kill
|
|
.XREF sigwait
|
|
|
|
.SH NAME
|
|
pthread_sigmask, pthread_kill, sigwait \- handling of signals in threads
|
|
|
|
.SH SYNOPSIS
|
|
#include <pthread.h>
|
|
.br
|
|
#include <signal.h>
|
|
|
|
int pthread_sigmask(int how, const sigset_t *newmask, sigset_t *oldmask);
|
|
|
|
int pthread_kill(pthread_t thread, int signo);
|
|
|
|
int sigwait(const sigset_t *set, int *sig);
|
|
|
|
.SH DESCRIPTION
|
|
|
|
!pthread_sigmask! changes the signal mask for the calling thread as
|
|
described by the |how| and |newmask| arguments. If |oldmask| is not
|
|
!NULL!, the previous signal mask is stored in the location pointed to
|
|
by |oldmask|.
|
|
|
|
The meaning of the |how| and |newmask| arguments is the same as for
|
|
!sigprocmask!(2). If |how| is !SIG_SETMASK!, the signal mask is set to
|
|
|newmask|. If |how| is !SIG_BLOCK!, the signals specified to |newmask|
|
|
are added to the current signal mask. If |how| is !SIG_UNBLOCK!, the
|
|
signals specified to |newmask| are removed from the current signal
|
|
mask.
|
|
|
|
Recall that signal masks are set on a per-thread basis, but signal
|
|
actions and signal handlers, as set with !sigaction!(2), are shared
|
|
between all threads.
|
|
|
|
!pthread_kill! send signal number |signo| to the thread
|
|
|thread|. The signal is delivered and handled as described in
|
|
!kill!(2).
|
|
|
|
!sigwait! suspends the calling thread until one of the signals
|
|
in |set| is delivered to the calling thread. It then stores the number
|
|
of the signal received in the location pointed to by |sig| and
|
|
returns. The signals in |set| must be blocked and not ignored on
|
|
entrance to !sigwait!. If the delivered signal has a signal handler
|
|
function attached, that function is |not| called.
|
|
|
|
.SH CANCELLATION
|
|
|
|
!sigwait! is a cancellation point.
|
|
|
|
.SH "RETURN VALUE"
|
|
|
|
On success, 0 is returned. On failure, a non-zero error code is returned.
|
|
|
|
.SH ERRORS
|
|
|
|
The !pthread_sigmask! function returns the following error codes
|
|
on error:
|
|
.RS
|
|
.TP
|
|
!EINVAL!
|
|
|how| is not one of !SIG_SETMASK!, !SIG_BLOCK!, or !SIG_UNBLOCK!
|
|
|
|
.TP
|
|
!EFAULT!
|
|
|newmask| or |oldmask| point to invalid addresses
|
|
.RE
|
|
|
|
The !pthread_kill! function returns the following error codes
|
|
on error:
|
|
.RS
|
|
.TP
|
|
!EINVAL!
|
|
|signo| is not a valid signal number
|
|
|
|
.TP
|
|
!ESRCH!
|
|
the thread |thread| does not exist (e.g. it has already terminated)
|
|
.RE
|
|
|
|
The !sigwait! function never returns an error.
|
|
|
|
.SH AUTHOR
|
|
Xavier Leroy <Xavier.Leroy@inria.fr>
|
|
|
|
.SH "SEE ALSO"
|
|
!sigprocmask!(2),
|
|
!kill!(2),
|
|
!sigaction!(2),
|
|
!sigsuspend!(2).
|
|
|
|
.SH NOTES
|
|
|
|
For !sigwait! to work reliably, the signals being waited for must be
|
|
blocked in all threads, not only in the calling thread, since
|
|
otherwise the POSIX semantics for signal delivery do not guarantee
|
|
that it's the thread doing the !sigwait! that will receive the signal.
|
|
The best way to achieve this is block those signals before any threads
|
|
are created, and never unblock them in the program other than by
|
|
calling !sigwait!.
|
|
|
|
.SH BUGS
|
|
|
|
Signal handling in LinuxThreads departs significantly from the POSIX
|
|
standard. According to the standard, ``asynchronous'' (external)
|
|
signals are addressed to the whole process (the collection of all
|
|
threads), which then delivers them to one particular thread. The
|
|
thread that actually receives the signal is any thread that does
|
|
not currently block the signal.
|
|
|
|
In LinuxThreads, each thread is actually a kernel process with its own
|
|
PID, so external signals are always directed to one particular thread.
|
|
If, for instance, another thread is blocked in !sigwait! on that
|
|
signal, it will not be restarted.
|
|
|
|
The LinuxThreads implementation of !sigwait! installs dummy signal
|
|
handlers for the signals in |set| for the duration of the wait. Since
|
|
signal handlers are shared between all threads, other threads must not
|
|
attach their own signal handlers to these signals, or alternatively
|
|
they should all block these signals (which is recommended anyway --
|
|
see the Notes section).
|