sigwaitinfo()
Wait for a pending signal and retrieve its information
Synopsis:
#include <signal.h>
int sigwaitinfo ( const sigset_t *set,
siginfo_t *info );
Arguments:
- set
- A pointer to a sigset_t object that specifies the signals you want to wait for.
- info
- NULL, or a pointer to a siginfo_t structure where the function can store information about the signal.
Library:
libc
Use the -l c option to qcc to link against this library. This library is usually included automatically.
Description:
The sigwaitinfo() function selects a pending signal from set, atomically clears it from the set of pending signals in the system, and if info isn't NULL, stores the selected signal in the si_signo member of info and the cause of the signal in the si_code member. If no signal in set is pending, sigwaitinfo() blocks until a signal is pending. Otherwise, the function immediately returns without blocking.
If any value is queued to the selected signal, the first queued value is dequeued and, if the info argument is non-NULL, the value is stored in the si_value member of info. The system resources used to queue the signal are released and made available to queue other signals. If no value is queued, the content of the si_value member is undefined.
If no further signals are queued for the selected signal, the pending indication for that signal is reset.
The signals defined by set should be blocked by all threads, including the one that will handle them, before this designated handler thread calls sigwaitinfo(). This design ensures simplicity by separating application threads into those that ignore signals and those that handle them. If you don't block signals, there's a race condition because a signal can be delivered just before the call is made, causing the call to block, which you might not want it to do.
However, simply blocking a signal is insufficient, as there's still a race condition where the signal is delivered just before the call to block it is handled. To avoid this situation, you could do the following:
- Install a signal handler that sets a flag.
- Block the signal.
- Check if the flag is set.
- Call sigwaitinfo().
Or, if portability isn't important, you could call SignalWaitinfoMask(), which blocks a specified set of signals and then waits.
It is recommended to have just one thread call sigwaitinfo() for a given signal. This means if multiple threads use this function, they must specify non-overlapping signals in set. Handling signals with just one thread is simpler and race-free, and you don't have to worry about whether you're using something that is unsafe in a signal handler. If your design requires that you have more than one thread use sigwaitinfo() for the same signal, be aware that only one of these threads (chosen arbitrarily) will return from this function with the signal's information.
Returns:
A signal number, or -1 if an error occurred (errno is set).
Errors:
- EFAULT
- A fault occurred while accessing the buffers.
- EINTR
- The wait was interrupted by an unblocked, caught signal.
Classification:
| Safety: | |
|---|---|
| Cancellation point | Yes |
| Signal handler | Yes |
| Thread | Yes |