<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation">
<title>sigwait()--Synchronously Accept a Signal</title>
<!-- All rights reserved. Licensed Materials Property of IBM          -->
<!-- US Government Users Restricted Rights                            -->
<!-- Use, duplication or disclosure restricted by                     -->
<!-- GSA ADP Schedule Contract with IBM Corp.                         -->
<!-- Begin Header Records  ========================================== -->
<!-- UNIX5 SCRIPT J converted by B2H R4.1 (346) (CMS) by V2KEA304   -->
<!-- at RCHVMW2 on 17 Feb 1999 at 11:05:09                            -->
<!-- Edited by Kersten Feb 02 -->
<!-- This file has undergone error condition cleanup on 04/30/02 by JET -->
<!--End Header Records -->
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
</head>
<body>
<a name="Top_Of_Page"></a> 
<!-- Java sync-link -->
<script type="text/javascript" language="Javascript" src="../rzahg/synch.js">
</script>

<h2>sigwait()--Synchronously Accept a Signal</h2>

<div class="box" style="width: 60%;">
<br>
&nbsp;&nbsp;Syntax<br>
<pre>
 #include &lt;signal.h&gt;

 int sigwait( const sigset_t *set, int *sig );   
</pre>

<br>
&nbsp;&nbsp;Service Program Name: QPOSSRV1<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: Yes<br>
<!-- iddvc RMBR -->
<br>
</div>

<p>The <strong>sigwait()</strong> function selects a pending signal from <em>
set</em>, clears it from the set of pending signals for the thread or process,
and returns that signal number in the location that is referenced by <em>
sig</em>. If prior to the call to <strong>sigwait()</strong> there are multiple
pending instances of a single signal number, upon successful return the number
of remaining signals for that signal number is decremented by one.</p>

<p>If no signal in <em>set</em> is pending at the time of the call, the thread
shall be suspended. The thread does not resume until one or more signals in
<em>set</em> become pending.</p>

<p>The signals defined by <em>set</em> are required to be blocked at the time
of the call to <strong>sigwait()</strong>; otherwise, <strong>
sigwait()</strong> is not successful, and an [EINVAL] error is returned. The
signals SIGKILL or SIGStop cannot be selected. Any attempt to use <strong>
sigwait()</strong> to select these signals is simply ignored, and no error is
returned.</p>

<p>The signal action for the signal in <em>set</em> that is returned in the
location referenced by <em>sig</em> is not taken.</p>

<p>If more than one thread is using a <em>sigwait</em> function to wait for the
same signal, only one of these threads will return from the <em>sigwait</em>
function with the signal number. If more than one thread is waiting for the
same signal, the first thread to wait on the signal will return from the <em>
sigwait</em> function.</p>

<br>
<!-- Please NOTE:  DO NOT DELETE THIS SECTION if this API has no authorities and locks.  -->
<!-- Instead, use the commented out coding below to indicate NONE.                       -->
<h3>Authorities and Locks</h3>

<!-- Use this if there are no authorities and locks.                                     -->
<p>None.</p>

<br>
<h3>Parameters</h3>

<dl>
<dt><strong><em>*set</em></strong></dt>

<dd>(Input) A pointer to a signal set to be waited upon.<br>
<br>
</dd>

<dt><strong><em>*sig</em></strong></dt>

<dd>(Output) A pointer to the storage location where <strong>sigwait()</strong>
can store the signal number that completed the wait.</dd>
</dl>

<br>
<h3>Return Value</h3>

<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top"><strong>sigwait()</strong> was successful.</td>
</tr>

<tr>
<td align="left" valign="top"><em>-1</em></td>
<td align="left" valign="top"><strong>sigwait()</strong> was not successful.
The <em>errno</em> variable is set to indicate the reason.</td>
</tr>
</table>

<br>
<br>
<h3>Error Conditions</h3>

<p>If <strong>sigwait()</strong> is not successful, <em>errno</em> usually
indicates the following error. Under some conditions, <em>errno</em> could
indicate an error other than that listed here.</p>

<dl>
<dt><em>[EINVAL]</em></dt>

<dd>
<p>The value specified for the argument is not correct.</p>

<p>A function was passed incorrect argument values, or an operation was
attempted on an object and the operation specified is not supported for that
type of object.</p>

<p>An argument value is not valid, out of range, or NULL.</p>

<p>One of the following has occurred:</p>

<ul>
<li>The signal set pointed to by <em>set</em> contains a signal that is not
within the valid range or a signal that is not supported.</li>

<li>A signal in the signal set pointed to by <em>set</em> contains a signal
that is not blocked.</li>

</ul><br>
<br>
</dd>

<dt><em>[ENOTSIGINIT]</em></dt>

<dd>
<p>Process not enabled for signals.</p>

<p>An attempt was made to call a signal function under one of the following
conditions:</p>

<ul>
<li>The signal function is being called for a process that is not enabled for
asynchronous signals.</li>

<li>The signal function is being called when the system signal controls have
not been initialized.</li>
</ul>
</dd>
</dl>

<br>
<h3>Usage Notes</h3>

<p>The <strong>sigwait()</strong> function enables a process for signals if the
process is not already enabled for signals. For details, see <a href= 
"sigesig.htm">Qp0sEnableSignals()--Enable Process for Signals</a>. If the
system has not been enabled for signals, <strong>sigwait()</strong> is not
successful, and an [ENOTSIGINIT] error is returned.</p>

<br>
<h3>Related Information</h3>

<ul>
<li>The &lt;<strong>signal.h</strong>&gt; file (see <a href="unix13.htm">Header
Files for UNIX-Type Functions</a>)<br>
<br>
</li>

<li><a href="sigdsig.htm">Qp0sDisableSignals()</a>--Disable Process for
Signals<br>
<br>
</li>

<li><a href="sigesig.htm">Qp0sEnableSignals()</a>--Enable Process for
Signals<br>
<br>
</li>

<li><a href="sigactn.htm">sigaction()</a>--Examine and Change Signal Action<br>
<br>
</li>

<li><a href="sigpend.htm">sigpending()</a>--Examine Pending Signals<br>
<br>
</li>

<li><a href="sigpmsk.htm">sigprocmask()</a>--Examine and Change Blocked
Signals<br>
<br>
</li>

<li><a href="sigsusp.htm">sigsuspend()</a>--Wait for Signal<br>
<br>
</li>

<li><a href="sigtwait.htm">sigtimedwait()</a>--Synchronously Accept a Signal
for Interval of Time<br>
<br>
</li>

<li><a href="sigwaiti.htm">sigwaitinfo()</a>--Synchronously Accept a Signal and
Signal Data</li>
</ul>

<br>
<h3>Example</h3>

<p>See <a href="../apiref/aboutapis.htm#codedisclaimer">Code disclaimer information</a>
for information pertaining to code examples.</p>

<p>The following example suspends processing by using the <strong>
sigwait()</strong> function and determines the current time:</p>

<p><strong>Note:</strong> The signal catching function is not called.</p>

<pre>
#include &lt;signal.h&gt;
#include &lt;unistd.h&gt;
#include &lt;stdio.h&gt;
#include &lt;time.h&gt;

extern int errno;

void catcher( int sig ) {
    printf( "Signal catcher called for signal %d\n", sig );
}

void timestamp( char *str ) {
    time_t t;

    time( <em>T</em> );
    printf( "The time %s is %s\n", str, ctime(<em>T</em>) );
}

int main( int argc, char *argv[] ) {

    struct sigaction sigact;
    sigset_t waitset;
    int sig;
    int result = 0;

    sigemptyset( &amp;sigact.sa_mask );
    sigact.sa_flags = 0;
    sigact.sa_handler = catcher;
    sigaction( SIGALRM, &amp;sigact, NULL );

    sigemptyset( &amp;waitset );
    sigaddset( &amp;waitset, SIGALRM );

    sigprocmask( SIG_BLOCK, &amp;waitset, NULL );

    alarm( 10 );

    timestamp( "before sigwait()" );

    result = sigwait( &amp;waitset, &amp;sig );
    if( result == 0 )
        printf( "sigwait() returned for signal %d\n", sig );
    else {
        printf( "sigwait() returned error number %d\n", errno );
        perror( "sigwait() function failed\n" );
    }

    timestamp( "after sigwait()" );

    return( result );
}
</pre>

<h3>Output:</h3>

<pre>
    The time before sigwait() is Tue Jul 15 11:15:43 1997
    sigwait() returned for signal 14
    The time after sigwait() is Tue Jul 15 11:15:54 1997
</pre>

<br>
<hr>
API introduced: V4R2 

<hr>
<center>
<table cellpadding="2" cellspacing="2">
<tr align="center">
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href= 
"unix.htm">UNIX-Type APIs</a> | <a href="aplist.htm">APIs by category</a></td>
</tr>
</table>
</center>
</body>
</html>