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

FreeBSD Manual Pages

  
 
  

home | help
sigwait(2)		      System Calls Manual		    sigwait(2)

NAME
       sigwait(),  sigwaitinfo(), sigtimedwait() - synchronously accept	a sig-
       nal

SYNOPSIS

DESCRIPTION
       The function atomically selects and clears a pending  signal  from  set
       and  returns  the  signal number	in the location	pointed	to by sig.  If
       none of the signals in set is pending at	the  time  of  the  call,  the
       calling thread will be suspended	until one or more signals become pend-
       ing or the thread is interrupted	by an unblocked, caught	 signal.   The
       signals	in set should be blocked at the	time of	the call to Otherwise,
       the behavior is undefined.

       If there	are multiple signals queued for	the  selected  signal  number,
       will  return with the first queued signal and the remainder will	remain
       queued.	If any of multiple pending signals in  the  range  to  is  se-
       lected, the lowest numbered signal will be returned.  The selection or-
       der between realtime and	nonrealtime signals, or	between	multiple pend-
       ing nonrealtime signals,	is unspecified.

       If  more	 than  one thread in a process is in for the same signal, only
       one thread will return from with	the signal number;  which  thread  re-
       turns is	undefined.

       has the same behavior as	if the info parameter is If the	info parameter
       is not has the same behavior as except that the selected	signal	number
       is  returned  in	the si_signo field of the info parameter and the cause
       of the signal is	returned in the	si_code	field.	If any value is	queued
       to  the	selected  signal, the first such queued	value will be dequeued
       and stored in the si_value member of info and the system	resource  used
       to  queue the signal will be released and made available	to queue other
       signals.	If no value is queued, the contents of the si_value member  is
       undefined.  If  no  further signals are queued for the selected signal,
       the pending indication for that signal will be reset.

       has the same behavior as	except that will only wait for the time	inter-
       val specified by	the timeout parameter if none of the signals specified
       by set are pending at the time of the call.  If the  timeout  parameter
       specifies  a  zero-valued  time	interval, then will return immediately
       with an error if	no signals in set are pending at the time of the call.
       If the timeout parameter	is the behavior	is undefined.

APPLICATION USAGE
       For a given signal number, the sigwait family of	routines should	not be
       used in conjunction with	or any other functions which change signal ac-
       tion.  If they are used together, the results are undefined.

   Threads Considerations
       The  sigwait  family  of	routines enable	a thread to synchronously wait
       for signals.  This makes	the sigwait routines ideal for	handling  sig-
       nals  in	a multithreaded	process.  The suggested	method for signal han-
       dling in	a multithreaded	process	is to have all threads block the  sig-
       nals  of	interest and dedicate one thread to call a sigwait function to
       wait for	the signals.  When a signal causes a sigwait function  to  re-
       turn, the code to handle	the signal can be placed immediately after the
       return from the sigwait routine.	 After the signal is handled,  a  sig-
       wait function can again be called to wait for another signal.

       In  order to ensure that	the dedicated thread handles the signal, it is
       essential that all threads, including the thread	 issuing  the  sigwait
       call,  block  the  signals of interest.	Otherwise, the signal could be
       delivered to a thread other than	the dedicated signal handling  thread.
       This  could result in the default action	being carried out for the sig-
       nal.  It	is important that the thread issuing  the  sigwait  call  also
       block  the signal.  This	will prevent signals from carrying out the de-
       fault signal action while the dedicated signal handling thread  is  be-
       tween calls to a	sigwait	function.

RETURN VALUE
       Upon  successful	 completion,  stores the signal	number selected	in the
       location	pointed	to by sig and returns with a value of (zero).	Other-
       wise,  it  returns an error number to indicate the error.  The variable
       is NOT set if an	error occurs.

       Upon successful completion, and will return the selected	signal number.
       Otherwise a value of -1 is returned and is set to indicate the error.

ERRORS
       If  any	of  the	following conditions occur, the	sigwait	family of rou-
       tines will return the following error number:

	      [EAGAIN]	     was called	and no signal in the set parameter was
			     delivered	within	the time interval specified by
			     the timeout parameter.

       If any of the following conditions occur	and the	condition is detected,
       the sigwait family of routines will fail	and return the following error
       number:

	      [EINVAL]	     set contains an  invalid  or  unsupported	signal
			     number.

	      [EINVAL]	     was  called and the timeout parameter specified a
			     tv_nsec value less	than zero or greater  than  or
			     equal  to	1000  million,	or a tv_sec value less
			     than zero or greater than or equal	to  2147483648
			     (that  is,	a value	too large to be	represented as
			     a signed 32-bit integer).

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

	      [EFAULT]	     At	 least	one  of	the set, sig, info, or timeout
			     parameters	references an illegal address.

AUTHOR
       sigwaitinfo() and sigtimedwait()	 were  derived	from  the  IEEE	 POSIX
       P1003.1b	standard.

       sigwait() was derived from the IEEE POSIX P1003.1c standard.

SEE ALSO
       pause(2),   sigaction(2),  sigpending(2),  sigsuspend(2),  pthread_sig-
       mask(3T), signal(5).

STANDARDS CONFORMANCE
								    sigwait(2)

NAME | SYNOPSIS | DESCRIPTION | APPLICATION USAGE | RETURN VALUE | ERRORS | AUTHOR | SEE ALSO | STANDARDS CONFORMANCE

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

home | help