sigwait(2)

NAME

     sigwait - wait until a signal is posted

SYNOPSIS

  Default
     #include <signal.h>

     int sigwait(sigset_t *set);

  POSIX
     cc [ flag ... ] file ... -D_POSIX_PTHREAD_SEMANTICS [ library...]
     #include <signal.h>

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

DESCRIPTION

     The sigwait() function selects a signal in set that is pend-
     ing   on   the  calling  thread  (see  thr_create(3THR)  and
     pthread_create(3THR).)  If no signal in set is pending, then
     sigwait()  blocks until a signal in set becomes pending. The
     selected signal is cleared from the set of  signals  pending
     on  the  calling  thread  and  the  number  of the signal is
     returned, or in the POSIX version (see standards(5))  placed
     in  sig.  The selection of a signal in set is independent of
     the signal mask of the calling thread. This means  a  thread
     can synchronously wait for signals that are being blocked by
     the signal mask of the calling thread . To ensure that  only
     the  caller receives the signals defined in set, all threads
     should have signals in  set  masked  including  the  calling
     thread.

     If sigwait() is  called  on  an  ignored  signal,  then  the
     occurrence of the signal will be ignored, unless sigaction()
     changes the disposition. If more than one thread  waits  for
     the  same  signal,  only  one  is  unblocked when the signal
     arrives.

RETURN VALUES

     Upon successful completion, the default version of sigwait()
     returns  a  signal  number;  the POSIX version returns 0 and
     stores the received signal number at the location pointed to
     by  sig. Otherwise, -1 is returned and errno is set to indi-
     cate an error.

ERRORS

     The sigwait() function will fail if:

     EFAULT
           The set argument points to an invalid address.

     EINTR The wait was interrupted by an unblocked, caught  sig-
           nal.

     EINVAL
           The  set  argument  contains  an  unsupported   signal
           number.

EXAMPLES

     Example 1: Creating a thread to handle receipt of a signal

     The following sample C code creates a thread to  handle  the
     receipt of a signal. More specifically, it catches the asyn-
     chronously generated signal, SIGINT.

     /********************************************************************
     *
     * compile with -D_POSIX_PTHREAD_SEMANTICS switch;
     * required by sigwait()
     *
     * sigint thread handles delivery of signal. uses sigwait() to wait
     * for SIGINT signal.
     *
     ********************************************************************/
     #include <pthread.h>
     #include <stdlib.h>
     #include <stdio.h>
     #include <string.h>
     #include <unistd.h>
     #include <signal.h>
     #include <synch.h>

     static void    *threadTwo(void *);
     static void    *threadThree(void *);
     static void    *sigint(void *);

     sigset_t       signalSet;

     void *
     main(void)
     {
         pthread_t    t;
         pthread_t    t2;
         pthread_t    t3;

         sigfillset ( &signalSet );
         /*
          * Block signals in initial thread. New threads will
          * inherit this signal mask.
          */
         pthread_sigmask ( SIG_BLOCK, &signalSet, NULL );

         printf("Creating threads\n");

         pthread_create(&t, NULL, sigint, NULL);
         pthread_create(&t2, NULL, threadTwo, NULL);
         pthread_create(&t3, NULL, threadThree, NULL);

         printf("##################\n");
         printf("press CTRL-C to deliver SIGINT to sigint thread\n");
         printf("##################\n");

         pthread_exit((void *)0);
     }
     static void *
     threadTwo(void *arg)
     {
         printf("hello world, from threadTwo [tid: %d]\n",
                                 pthread_self());
         printf("threadTwo [tid: %d} is now complete and exiting\n",
                                 pthread_self());
         pthread_exit((void *)0);
     }

     static void *
     threadThree(void *arg)
     {
         printf("hello world, from threadThree [tid: %d]\n",
                                 pthread_self());
         printf("threadThree [tid: %d} is now complete and exiting\n",
                                 pthread_self());
         pthread_exit((void *)0);
     }

     void *
     sigint(void *arg)
     {
         int    sig;
         int    err;

         printf("thread sigint [tid: %d] awaiting SIGINT\n",
                                 pthread_self());

         /*
         /* use POSIX sigwait() -- 2 args: signal set, signum
          */
         err = sigwait ( &signalSet, &sig );

         /* test for SIGINT; could catch other signals */
         if (err || sig != SIGINT)
             abort();

         printf("\nSIGINT signal %d caught by sigint thread [tid: %d]\n",
                                 sig, pthread_self());
         pthread_exit((void *)0);
     }

ATTRIBUTES

     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | MT-Level                    | Async-Signal-Safe           |
    |_____________________________|_____________________________|

SEE ALSO

     sigaction(2), sigpending(2), sigprocmask(2),  sigsuspend(2),
     pthread_create(3THR),  pthread_sigmask(3THR), signal(3HEAD),
     thr_create(3THR), thr_sigsetmask(3THR), standards(5)

NOTES

     The sigwait() function cannot be used to  wait  for  signals
     that  cannot  be caught (see sigaction(2)). This restriction
     is silently imposed by the system.

     Solaris 2.4 and earlier releases provided a sigwait() facil-
     ity  as  specified  in  POSIX.1c Draft 6. The final POSIX.1c
     standard changed the interface as described  above.  Support
     for the Draft 6 interface is provided for compatibility only
     and may not be supported in future releases.   New  applica-
     tions and libraries should use the POSIX standard interface.