sigwait(3pthread)
sigwait --
wait for a signal to be posted
Synopsis
#include <signal.h>
int sigwait(sigset_t *set);
cc [options] -Kthread file
#include <signal.h>
#define _XOPEN_SOURCE 500
#define _POSIX_C_SOURCE 199506
int sigwait(const sigset_t *set, int *sig);
Description
There are two versions of the sigwait function in
this release.
Non-POSIX-compliant version
This version of the function atomically chooses and clears a pending
signal from set and returns the number of the signal chosen.
If no signal in set is pending at the time of the call,
the calling function shall be suspended until one or more signals become
pending.
This suspension is indefinite in extent.
The set of signals remains blocked after return.
An application should not mix use of sigwait and
sigaction for a given signal number
because the results may be unpredictable.
POSIX compliant version
To access the POSIX version of sigwait you must
define the value of _XOPEN_SOURCE to be greater
than or equal to
500, and the value of _POSIX_C_SOURCE to be
greater than or equal to 199506.
You must also specify the Kthread library as an
option to the cc command.
The POSIX compliant version of sigwait, shown in
the second synopsis shown above, selects
a pending signal from set, atomically clears it
from the system's set of pending signals, and returns that
signal number in the location referenced by sig.
If no signal in set is pending at the time
of the call, the thread is suspended until
one or more becomes pending.
The signals defined by set shall have been blocked
at the time of the call to sigwait;
otherwise the behavior is undefined.
If more than one thread is using sigwait
to wait for the same signal, only one
of these threads will return from sigwait
with the signal number.
Return values
Upon successful completion,
the non-POSIX-compliant version of sigwait returns
the signal number of the received signal.
Otherwise, it returns a negative value and errno is
set to indicate the error.
Upon successful completion, the POSIX compliant version of
sigwait stores the signal number of the received
signal at the location referenced by sig
and returns zero.
Otherwise, an error number is returned to indicate the error.
Diagnostics
The non-POSIX-compliant version of sigwait
returns a negative value and sets errno to the following
values if the corresponding conditions are detected.:
EINVAL-
set contains an invalid or unsupported signal number
EFAULT-
set points to an illegal address.
The POSIX compliant version of sigwait returns the following
value if the corresponding condition is detected:
EINVAL-
set contains an invalid or unsupported signal number
EFAULT-
set points to an illegal address.
Standards compliance
The Single UNIX Specification, Version 2; The Open Group.
References
Intro(3thread),
Intro(3pthread),
_lwp_kill(2),
kill(2),
pause(2),
pthread_sigmask(3pthread),
sigaction(2),
signal(5),
sigpending(2),
sigsend(2),
sigsuspend(2),
thr_sigsetmask(3thread)
Notices
Considerations for threads programming
The sigwait system call allows a multithreaded application
to use a synchronous organization for signal handling.
Usage
The semantics of sigwait make it ideal for a thread that will
be dedicated to handling certain signal types for a process.
The functionality that might have been placed in a separate handler
function could be placed after the return from sigwait
to be executed once a signal arrives.
Once handling is complete,
the thread could call sigwait again to block itself until
arrival of the next signal.
To be sure that signals are delivered to the intended thread:
-
All threads in the process
(including the thread that will be using sigwait)
should mask the relevant signal types.
-
Only the intended thread should use sigwait.
-
No thread should define a handler function.
See
signal(5)
for further details.
Code to handle a signal type on return from sigwait
is not considered a handler in the containing process' disposition for
that signal type.
It is important that signal types handled by a thread using
sigwait(2)
be included in the signal mask of every thread,
otherwise, the default response for the process will be triggered.
Even the thread calling sigwait should mask that signal type
because a signal of that type may arrive while the thread is
between calls to
sigwait(2).
While one thread is blocked, siblings might still be executing.
© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 25 April 2004