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
       signal 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 undefined 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
       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
");

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

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

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

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

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

	     printf("thread sigint [tid: %d] awaiting SIGINT
",
				     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("
SIGINT signal %d caught by sigint thread [tid: %d]
",
				     sig, pthread_self());
	     pthread_exit((void *)0);
	 }

ATTRIBUTES

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Standard			   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |Async-Signal-Safe 	   |
       +-----------------------------+-----------------------------+

SEE ALSO

       sigaction(2), signal.h(3HEAD),  sigpending(2),  sigprocmask(2),	sigsuspend(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 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 applications and libraries should use the standard-conforming interface.

SunOS 5.11							    24 Jun 2002 							sigwait(2)