NAME

       sigwait - wait for queued signals

SYNOPSIS

       #include <signal.h>

       int sigwait(const sigset_t *restrict set, int *restrict sig);

DESCRIPTION

       The  sigwait()  function  shall select a pending signal from set, atomically clear it from
       the system's set of pending signals,  and  return  that  signal  number  in  the  location
       referenced  by sig. If prior to the call to sigwait() there are multiple pending instances
       of a single signal number, it is implementation-defined  whether  upon  successful  return
       there  are  any remaining pending signals for that signal number.    If the implementation
       supports queued signals and there are  multiple  signals  queued  for  the  signal  number
       selected,  the  first  such  queued  signal  shall  cause  a return from sigwait() and the
       remainder shall remain queued.  If no signal in set is pending at the time  of  the  call,
       the  thread  shall  be 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.  The  effect  of  sigwait() on the signal actions for the signals in set is
       unspecified.

       If more than one thread is using sigwait() to wait for the same signal, no more  than  one
       of  these threads shall return from sigwait() with the signal number. Which thread returns
       from sigwait() if more than a single thread is waiting is unspecified.

       Should any of the multiple pending signals in the range SIGRTMIN to SIGRTMAX be  selected,
       it shall be the lowest numbered one. The selection order between realtime and non-realtime
       signals, or between multiple pending non-realtime signals, is unspecified.

RETURN VALUE

       Upon successful completion, sigwait() shall store the signal number of the received signal
       at  the  location  referenced  by sig and return zero. Otherwise, an error number shall be
       returned to indicate the error.

ERRORS

       The sigwait() function may fail if:

       EINVAL The set argument contains an invalid or unsupported signal number.

       The following sections are informative.

EXAMPLES

       None.

APPLICATION USAGE

       None.

RATIONALE

       To provide a  convenient  way  for  a  thread  to  wait  for  a  signal,  this  volume  of
       IEEE Std 1003.1-2001 provides the sigwait() function. For most cases where a thread has to
       wait for a signal, the sigwait() function  should  be  quite  convenient,  efficient,  and
       adequate.

       However,  requests were made for a lower-level primitive than sigwait() and for semaphores
       that could be used by threads.  After some consideration,  threads  were  allowed  to  use
       semaphores and sem_post() was defined to be async-signal and async-cancel-safe.

       In  summary,  when  it  is necessary for code run in response to an asynchronous signal to
       notify a thread, sigwait() should be used to handle  the  signal.  Alternatively,  if  the
       implementation  provides  semaphores, they also can be used, either following sigwait() or
       from within a signal handling routine previously registered with sigaction().

FUTURE DIRECTIONS

       None.

SEE ALSO

       Signal Concepts  ,  Realtime  Signals  ,  pause()  ,  pthread_sigmask()  ,  sigaction()  ,
       sigpending()   ,   sigsuspend()   ,   sigwaitinfo()  ,  the  Base  Definitions  volume  of
       IEEE Std 1003.1-2001, <signal.h>, <time.h>

COPYRIGHT

       Portions of this text are reprinted and  reproduced  in  electronic  form  from  IEEE  Std
       1003.1,  2003  Edition,  Standard  for Information Technology -- Portable Operating System
       Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2003  by
       the  Institute  of  Electrical  and  Electronics Engineers, Inc and The Open Group. In the
       event of any discrepancy between this version and the original IEEE  and  The  Open  Group
       Standard,  the  original  IEEE  and  The  Open Group Standard is the referee document. The
       original Standard can be obtained online at http://www.opengroup.org/unix/online.html .