# sigwaitinfo

## NAME



           sigwaitinfo, sigtimedwait, rt_sigtimedwait - synchronously wait
           for queued signals
    


## LIBRARY



           Standard C library (_libc_ , _-lc_)
    


## SYNOPSIS



           **#include <signal.h>**
    
           **int sigwaitinfo(const sigset_t *restrict** _set_**,**
                           **siginfo_t *_Nullable restrict** _info_**);**
           **int sigtimedwait(const sigset_t *restrict** _set_**,**
                           **siginfo_t *_Nullable restrict** _info_**,**
                           **const struct timespec *restrict** _timeout_**);**
    
       Feature Test Macro Requirements for glibc (see
       feature_test_macros(7)):
    
           **sigwaitinfo**(), **sigtimedwait**():
               _POSIX_C_SOURCE >= 199309L
    


## DESCRIPTION



           **sigwaitinfo**() suspends execution of the calling thread until one
           of the signals in _set_ is pending (If one of the signals in _set_ is
           already pending for the calling thread, **sigwaitinfo**() will return
           immediately.)
    
           **sigwaitinfo**() removes the signal from the set of pending signals
           and returns the signal number as its function result.  If the _info_
           argument is not NULL, then the buffer that it points to is used to
           return a structure of type _siginfo_t_ (see sigaction(2)) containing
           information about the signal.
    
           If multiple signals in _set_ are pending for the caller, the signal
           that is retrieved by **sigwaitinfo**() is determined according to the
           usual ordering rules; see signal(7) for further details.
    
           **sigtimedwait**() operates in exactly the same way as **sigwaitinfo**()
           except that it has an additional argument, _timeout_ , which
           specifies the interval for which the thread is suspended waiting
           for a signal.  (This interval will be rounded up to the system
           clock granularity, and kernel scheduling delays mean that the
           interval may overrun by a small amount.)  This argument is a
           **timespec**(3) structure.
    
           If both fields of this structure are specified as 0, a poll is
           performed: **sigtimedwait**() returns immediately, either with
           information about a signal that was pending for the caller, or
           with an error if none of the signals in _set_ was pending.
    


## RETURN VALUE



           On success, both **sigwaitinfo**() and **sigtimedwait**() return a signal
           number (i.e., a value greater than zero).  On failure both calls
           return -1, with _errno_ set to indicate the error.
    


## ERRORS



           **EAGAIN** No signal in _set_ became pending within the _timeout_ period
                  specified to **sigtimedwait**().
    
           **EINTR** The wait was interrupted by a signal handler; see
                  signal(7).  (This handler was for a signal other than one
                  of those in _set_.)
    
           **EINVAL** _timeout_ was invalid.
    


## VERSIONS



       **C library/kernel differences**
           On Linux, **sigwaitinfo**() is a library function implemented on top
           of **sigtimedwait**().
    
           The glibc wrapper functions for **sigwaitinfo**() and **sigtimedwait**()
           silently ignore attempts to wait for the two real-time signals
           that are used internally by the NPTL threading implementation.
           See nptl(7) for details.
    
           The original Linux system call was named **sigtimedwait**().  However,
           with the addition of real-time signals in Linux 2.2, the fixed-
           size, 32-bit _sigset_t_ type supported by that system call was no
           longer fit for purpose.  Consequently, a new system call,
           **rt_sigtimedwait**(), was added to support an enlarged _sigset_t_ type.
           The new system call takes a fourth argument, _size_t sigsetsize_ ,
           which specifies the size in bytes of the signal set in _set_.  This
           argument is currently required to have the value _sizeof(sigset_t)_
           (or the error **EINVAL** results).  The glibc **sigtimedwait**() wrapper
           function hides these details from us, transparently calling
           **rt_sigtimedwait**() when the kernel provides it.
    


## STANDARDS



           POSIX.1-2008.
    


## NOTES



           In normal usage, the calling program blocks the signals in _set_ via
           a prior call to sigprocmask(2) (so that the default disposition
           for these signals does not occur if they become pending between
           successive calls to **sigwaitinfo**() or **sigtimedwait**()) and does not
           establish handlers for these signals.  In a multithreaded program,
           the signal should be blocked in all threads, in order to prevent
           the signal being treated according to its default disposition in a
           thread other than the one calling **sigwaitinfo**() or
           **sigtimedwait**()).
    
           The set of signals that is pending for a given thread is the union
           of the set of signals that is pending specifically for that thread
           and the set of signals that is pending for the process as a whole
           (see signal(7)).
    
           Attempts to wait for **SIGKILL** and **SIGSTOP** are silently ignored.
    
           If multiple threads of a process are blocked waiting for the same
           signal(s) in **sigwaitinfo**() or **sigtimedwait**(), then exactly one of
           the threads will actually receive the signal if it becomes pending
           for the process as a whole; which of the threads receives the
           signal is indeterminate.
    
           **sigwaitinfo**() or **sigtimedwait**(), can't be used to receive signals
           that are synchronously generated, such as the **SIGSEGV** signal that
           results from accessing an invalid memory address or the **SIGFPE**
           signal that results from an arithmetic error.  Such signals can be
           caught only via signal handler.
    
           POSIX leaves the meaning of a NULL value for the _timeout_ argument
           of **sigtimedwait**() unspecified, permitting the possibility that
           this has the same meaning as a call to **sigwaitinfo**(), and indeed
           this is what is done on Linux.
    


* * *