Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Standard			   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |Async-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  in-
       terface	as  described above. Support for the Draft 6 interface is pro-
       vided for compatibility only and	may not	be  supported  in  future  re-
       leases.	 New  applications  and	libraries should use the standard-con-
       forming interface.

SunOS 5.10			  24 Jun 2002			    sigwait(2)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | EXAMPLES | ATTRIBUTES | SEE ALSO | NOTES

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=sigwait&sektion=2&manpath=SunOS+5.10>

home | help