<!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> Syntax<br> <pre> #include <signal.h> int sigwait( const sigset_t *set, int *sig ); </pre> <br> Service Program Name: QPOSSRV1<br> <!-- iddvc RMBR --> <br> Default Public Authority: *USE<br> <!-- iddvc RMBR --> <br> 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 <<strong>signal.h</strong>> 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 <signal.h> #include <unistd.h> #include <stdio.h> #include <time.h> 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( &sigact.sa_mask ); sigact.sa_flags = 0; sigact.sa_handler = catcher; sigaction( SIGALRM, &sigact, NULL ); sigemptyset( &waitset ); sigaddset( &waitset, SIGALRM ); sigprocmask( SIG_BLOCK, &waitset, NULL ); alarm( 10 ); timestamp( "before sigwait()" ); result = sigwait( &waitset, &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>