Man Linux: Main Page and Category List

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 .