334 lines
9.5 KiB
HTML
334 lines
9.5 KiB
HTML
|
<!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>sigsetjmp()--Set Jump Point for Nonlocal Goto</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 html cleanup on 04/29/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>sigsetjmp()--Set Jump Point for Nonlocal Goto</h2>
|
||
|
|
|
||
|
|
<div class="box" style="width: 60%;">
|
||
|
|
<br>
|
||
|
|
Syntax<br>
|
||
|
|
<pre>
|
||
|
|
#include <setjmp.h>
|
||
|
|
|
||
|
|
int sigsetjmp( sigjmp_buf <em>env</em>, int <em>savemask</em> );
|
||
|
|
</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>sigsetjmp()</strong> function saves the current stack
|
||
|
|
environment and, optionally, the current signal mask. The stack environment and
|
||
|
|
signal mask saved by <strong>sigsetjmp()</strong> can subsequently be restored
|
||
|
|
by <strong>siglongjmp()</strong>.</p>
|
||
|
|
|
||
|
|
<p><strong>sigsetjmp()</strong> is similar to <strong>setjmp()</strong>, except
|
||
|
|
for the optional capability of saving the signal mask. Like <strong>
|
||
|
|
setjmp()</strong> and <strong>longjmp()</strong>, the <strong>
|
||
|
|
sigsetjmp()</strong> and <strong>siglongjmp()</strong> functions provide a way
|
||
|
|
to perform a nonlocal "goto."</p>
|
||
|
|
|
||
|
|
<p>A call to <strong>sigsetjmp()</strong> causes it to save the current stack
|
||
|
|
environment in <em>env</em>. If the value of the <em>savemask</em> parameter is
|
||
|
|
nonzero, <strong>sigsetjmp()</strong> also saves the current signal mask in
|
||
|
|
<em>env</em>. A subsequent call to <strong>siglongjmp()</strong> does the
|
||
|
|
following:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>Restores the saved environment and signal mask (if saved by <strong>
|
||
|
|
sigsetjmp()</strong>).<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>Returns control to a point corresponding to the <strong>
|
||
|
|
sigsetjmp()</strong> call.</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p>The values of all variables (except register variables) accessible to the
|
||
|
|
function receiving control contain the values they had when <strong>
|
||
|
|
siglongjmp()</strong> was called. The values of register variables are
|
||
|
|
unpredictable. Nonvolatile automatic storage variables that are changed between
|
||
|
|
calls to <strong>sigsetjmp()</strong> and <strong>siglongjmp()</strong> are
|
||
|
|
also unpredictable.</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>env</em></strong></dt>
|
||
|
|
|
||
|
|
<dd>(Input) An array type for holding the information needed to restore a
|
||
|
|
calling environment.<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong><em>savemask</em></strong></dt>
|
||
|
|
|
||
|
|
<dd>(Input) An indicator used to determine if the current signal mask of the
|
||
|
|
thread is to be saved. This value may be zero.</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<h3>Return Value</h3>
|
||
|
|
|
||
|
|
<table cellpadding="5">
|
||
|
|
<!-- cols="10 90" -->
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>0</em></td>
|
||
|
|
<td align="left" valign="top"><strong>sigsetjmp()</strong> was called to save
|
||
|
|
the stack environment and, optionally, the signal mask. It may have been either
|
||
|
|
successful or not successful.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>val</em></td>
|
||
|
|
<td align="left" valign="top"><strong>siglongjmp()</strong> caused control to
|
||
|
|
be transferred to the place in the user's program where <strong>
|
||
|
|
sigsetjmp()</strong> was issued. The value returned is the value specified on
|
||
|
|
<strong>siglongjmp()</strong> for the <em>val</em> parameter (or 1 if the value
|
||
|
|
of <em>val</em> is zero).</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<br>
|
||
|
|
<h3>Error Conditions</h3>
|
||
|
|
|
||
|
|
<p>The <strong>sigsetjmp()</strong> function does not return an error.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<h3>Usage Notes</h3>
|
||
|
|
|
||
|
|
<p>The <strong>sigsetjmp()</strong>-<strong>siglongjmp()</strong> pair and the
|
||
|
|
<strong>setjmp()</strong>-<strong>longjmp()</strong> pair cannot be intermixed.
|
||
|
|
A stack environment and signal mask saved by <strong>sigsetjmp()</strong> can
|
||
|
|
be restored only by <strong>siglongjmp()</strong>.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<h3>Related Information</h3>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>The <<strong>setjmp.h</strong>> file (see <a href="unix13.htm">Header
|
||
|
|
Files for UNIX-Type Functions</a>)<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li><a href="sigactn.htm">sigaction()</a>--Examine and Change Signal Action<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li><a href="siglngj.htm">siglongjmp()</a>--Perform Nonlocal Goto with Signal
|
||
|
|
Handling<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</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>This example saves the stack environment and signal mask at the following
|
||
|
|
statement:</p>
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
if( sigsetjmp(mark,1) != 0 ) { ...
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p>When the system first performs the <samp>if</samp> statement, it saves the
|
||
|
|
environment and signal mask in <em>mark</em> and sets the condition to false
|
||
|
|
because <strong>sigsetjmp()</strong> returns a <samp>0</samp> when it saves the
|
||
|
|
environment. The program prints the following message:</p>
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
sigsetjmp() has been called
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p>The subsequent call to function <strong>p()</strong> tests for a local error
|
||
|
|
condition, which can cause it to perform <strong>siglongjmp()</strong> (in this
|
||
|
|
example as a result of calling a signal catching function). Control is returned
|
||
|
|
to the original <strong>sigsetjmp()</strong> function using the environment
|
||
|
|
saved in <em>mark</em> and the restored signal mask. This time, the condition
|
||
|
|
is true because -<samp>1</samp> is the return value from <strong>
|
||
|
|
siglongjmp()</strong>. The program then performs the statements in the block
|
||
|
|
and prints the following:</p>
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
siglongjmp() function was called
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p>Then the program performs the <strong>recover()</strong> function and
|
||
|
|
exits.</p>
|
||
|
|
|
||
|
|
<p>Here is the program:</p>
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
#include <signal.h>
|
||
|
|
#include <setjmp.h>
|
||
|
|
#include <unistd.h>
|
||
|
|
#include <stdio.h>
|
||
|
|
|
||
|
|
sigset_t sigset;
|
||
|
|
sigjmp_buf mark;
|
||
|
|
|
||
|
|
void catcher( int );
|
||
|
|
void p( void );
|
||
|
|
void recover( void );
|
||
|
|
|
||
|
|
int main( int argc, char *argv[] ) {
|
||
|
|
|
||
|
|
int result;
|
||
|
|
|
||
|
|
/*
|
||
|
|
* Block the SIGUSR1 and SIGUSR2 signals. This set of
|
||
|
|
* signals will be saved as part of the environment
|
||
|
|
* by the sigsetjmp() function.
|
||
|
|
*/
|
||
|
|
|
||
|
|
sigemptyset( &sigset );
|
||
|
|
sigaddset( &sigset, SIGUSR1 );
|
||
|
|
sigaddset( &sigset, SIGUSR2 );
|
||
|
|
sigprocmask( SIG_SETMASK, &sigset, NULL );
|
||
|
|
|
||
|
|
if( sigsetjmp( mark, 1 ) != 0 ) {
|
||
|
|
printf( "siglongjmp() function was called\n" );
|
||
|
|
recover();
|
||
|
|
result=0;
|
||
|
|
}
|
||
|
|
else {
|
||
|
|
printf( "sigsetjmp() has been called\n" );
|
||
|
|
p();
|
||
|
|
sigprocmask( SIG_SETMASK, NULL, &sigset );
|
||
|
|
if( sigismember( &sigset, SIGUSR2 ) )
|
||
|
|
printf( "siglongjmp() was not called\n" );
|
||
|
|
result=-1;
|
||
|
|
}
|
||
|
|
printf( "return to main with result %d\n", result);
|
||
|
|
|
||
|
|
return( result );
|
||
|
|
}
|
||
|
|
|
||
|
|
void p( void ) {
|
||
|
|
|
||
|
|
struct sigaction sigact;
|
||
|
|
int error=0;
|
||
|
|
|
||
|
|
printf( "performing function p()\n" );
|
||
|
|
|
||
|
|
/* Send signal handler in case error condition is detected */
|
||
|
|
|
||
|
|
sigemptyset( &sigact.sa_mask );
|
||
|
|
sigact.sa_flags = 0;
|
||
|
|
sigact.sa_handler = catcher;
|
||
|
|
sigaction( SIGUSR2, &sigact, NULL );
|
||
|
|
|
||
|
|
sigdelset( &sigset, SIGUSR2 );
|
||
|
|
sigprocmask( SIG_SETMASK, &sigset, NULL );
|
||
|
|
|
||
|
|
/* After some processing an error condition is detected */
|
||
|
|
|
||
|
|
error=-1;
|
||
|
|
|
||
|
|
/* Call catcher() function if error is detected */
|
||
|
|
|
||
|
|
if( error != 0 ) {
|
||
|
|
printf( "error condition detected, send SIGUSR2 signal\n" );
|
||
|
|
kill( getpid(), SIGUSR2 );
|
||
|
|
}
|
||
|
|
printf( "return from catcher() function is an error\n" );
|
||
|
|
}
|
||
|
|
|
||
|
|
void recover( void ) {
|
||
|
|
|
||
|
|
printf( "taking recovery action\n" );
|
||
|
|
|
||
|
|
sigprocmask( SIG_SETMASK, NULL, &sigset );
|
||
|
|
if( sigismember( &sigset, SIGUSR2 ) )
|
||
|
|
printf( "signal mask was restored after siglongjmp()\n" );
|
||
|
|
}
|
||
|
|
|
||
|
|
void catcher( int signo ) {
|
||
|
|
|
||
|
|
printf( "in catcher() before siglongjmp()\n" );
|
||
|
|
|
||
|
|
siglongjmp( mark, -1 );
|
||
|
|
|
||
|
|
printf( "in catcher() after siglongjmp() is an error\n" );
|
||
|
|
}
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<h3>Output:</h3>
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
sigsetjmp() has been called
|
||
|
|
performing function p()
|
||
|
|
error condition detected, send SIGUSR2 signal
|
||
|
|
in catcher() before siglongjmp()
|
||
|
|
siglongjmp() function was called
|
||
|
|
taking recovery action
|
||
|
|
signal mask was restored after siglongjmp()
|
||
|
|
return to main with result 0
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<hr>
|
||
|
|
API introduced: V3R6
|
||
|
|
|
||
|
|
<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>
|
||
|
|
|