unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-5.10)
Page:
Section:
Apropos / Subsearch:
optional field

sigwait(2)                       System Calls                       sigwait(2)



NAME
       sigwait - wait until a signal is posted

SYNOPSIS
       #include <signal.h>

       int sigwait(sigset_t *set);

   Standard conforming
       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 pending on the
       calling thread (see thr_create(3C) and pthread_create(3C).) If no  sig-
       nal  in  set is pending, 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 standard-conforming 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 the set argument points to an invalid address, the behavior is unde-
       fined and errno may be set to EFAULT.

       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 standard-conforming 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 indicate an error.

ERRORS
       The sigwait() function will fail if:

       EINTR    The wait was interrupted by an unblocked, caught signal.



       EINVAL   The set argument contains an unsupported signal number.



       The sigwait() function may fail if:

       EFAULT   The set argument points to an invalid address.



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 asynchronously generated sig-
       nal, 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 standard-conforming 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 attributes:


       tab()     allbox;     cw(2.750000i)|    cw(2.750000i)    lw(2.750000i)|
       lw(2.750000i).  ATTRIBUTE TYPEATTRIBUTE VALUE Interface  StabilityStan-
       dard MT-LevelAsync-Signal-Safe


SEE ALSO
       sigaction(2),  signal.h(3HEAD),  sigpending(2), sigprocmask(2), sigsus-
       pend(2),   pthread_create(3C),   pthread_sigmask(3C),   thr_create(3C),
       thr_sigsetmask(3C), attributes(5), 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() facility as spec-
       ified in POSIX.1c Draft 6. The  final  POSIX.1c  standard  changed  the
       interface as described above. Support for the Draft 6 interface is pro-
       vided for compatibility  only  and  may  not  be  supported  in  future
       releases.   New applications and libraries should use the standard-con-
       forming interface.



SunOS 5.10                        24 Jun 2002                       sigwait(2)