setjmp(3C) Standard C Library Functions setjmp(3C)NAME
setjmp, sigsetjmp, longjmp, siglongjmp - non-local goto
SYNOPSIS
#include <setjmp.h>
int setjmp(jmp_buf env);
int sigsetjmp(sigjmp_buf env, int savemask);
void longjmp(jmp_buf env, int val);
void siglongjmp(sigjmp_buf env, int val);
DESCRIPTION
These functions are useful for dealing with errors and interrupts
encountered in a low-level subroutine of a program.
The setjmp() function saves its stack environment in env for later use
by longjmp().
The sigsetjmp() function saves the calling process's registers and
stack environment (see sigaltstack(2)) in env for later use by sig‐
longjmp(). If savemask is non-zero, the calling process's signal mask
(see sigprocmask(2)) and scheduling parameters (see priocntl(2)) are
also saved.
The longjmp() function restores the environment saved by the last call
of setjmp() with the corresponding env argument. After longjmp() com‐
pletes, program execution continues as if the corresponding call to
setjmp() had just returned the value val. The caller of setjmp() must
not have returned in the interim. The longjmp() function cannot cause
setjmp() to return the value 0. If longjmp() is invoked with a second
argument of 0, setjmp() will return 1. At the time of the second return
from setjmp(), all external and static variables have values as of the
time longjmp() is called (see EXAMPLES).
The siglongjmp() function restores the environment saved by the last
call of sigsetjmp() with the corresponding env argument. After sig‐
longjmp() completes, program execution continues as if the correspond‐
ing call to sigsetjmp() had just returned the value val. The sig‐
longjmp() function cannot cause sigsetjmp() to return the value 0. If
siglongjmp() is invoked with a second argument of 0, sigsetjmp() will
return 1. At the time of the second return from sigsetjmp(), all exter‐
nal and static variables have values as of the time siglongjmp() was
called.
If a signal-catching function interrupts sleep(3C) and calls sig‐
longjmp() to restore an environment saved prior to the sleep() call,
the action associated with SIGALRM and time it is scheduled to be gen‐
erated are unspecified. It is also unspecified whether the SIGALRM sig‐
nal is blocked, unless the process's signal mask is restored as part of
the environment.
The siglongjmp() function restores the saved signal mask if and only
if the env argument was initialized by a call to the sigsetjmp() func‐
tion with a non-zero savemask argument.
The values of register and automatic variables are undefined. Register
or automatic variables whose value must be relied upon must be declared
as volatile.
RETURN VALUES
If the return is from a direct invocation, setjmp() and sigsetjmp()
return 0. If the return is from a call to longjmp(), setjmp() returns a
non-zero value. If the return is from a call to siglongjmp(),
sigsetjmp() returns a non-zero value.
After longjmp() is completed, program execution continues as if the
corresponding invocation of setjmp() had just returned the value speci‐
fied by val. The longjmp() function cannot cause setjmp() to return 0;
if val is 0, setjmp() returns 1.
After siglongjmp() is completed, program execution continues as if the
corresponding invocation of sigsetjmp() had just returned the value
specified by val. The siglongjmp() function cannot cause sigsetjmp() to
return 0; if val is 0, sigsetjmp() returns 1.
EXAMPLES
Example 1 Example of setjmp() and longjmp() functions.
The following example uses both setjmp() and longjmp() to return the
flow of control to the appropriate instruction block:
#include <stdio.h>
#include <setjmp.h>
#include <signal.h>
#include <unistd.h>
jmp_buf env; static void signal_handler();
main() {
int returned_from_longjump, processing = 1;
unsigned int time_interval = 4;
if ((returned_from_longjump = setjmp(env)) != 0)
switch (returned_from_longjump) {
case SIGINT:
printf("longjumped from interrupt %d\n",SIGINT);
break;
case SIGALRM:
printf("longjumped from alarm %d\n",SIGALRM);
break;
}
(void) signal(SIGINT, signal_handler);
(void) signal(SIGALRM, signal_handler);
alarm(time_interval);
while (processing) {
printf(" waiting for you to INTERRUPT (cntrl-C) ...\n");
sleep(1);
} /* end while forever loop */
}
static void signal_handler(sig)
int sig; {
switch (sig) {
case SIGINT: ... /* process for interrupt */
longjmp(env,sig);
/* break never reached */
case SIGALRM: ... /* process for alarm */
longjmp(env,sig);
/* break never reached */
default: exit(sig);
}
}
When this example is compiled and executed, and the user sends an
interrupt signal, the output will be:
longjumped from interrupt
Additionally, every 4 seconds the alarm will expire, signalling this
process, and the output will be:
longjumped from alarm
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
┌─────────────────────────────┬─────────────────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├─────────────────────────────┼─────────────────────────────┤
│Interface Stability │Committed │
├─────────────────────────────┼─────────────────────────────┤
│MT-Level │Unsafe │
├─────────────────────────────┼─────────────────────────────┤
│Standard │See standards(5). │
└─────────────────────────────┴─────────────────────────────┘
SEE ALSOgetcontext(2), priocntl(2), sigaction(2), sigaltstack(2), sigproc‐
mask(2), signal(3C), attributes(5), standards(5)WARNINGS
If longjmp() or siglongjmp() are called even though env was never
primed by a call to setjmp() or sigsetjmp(), or when the last such call
was in a function that has since returned, the results are undefined.
SunOS 5.11 14 Aug 2002 setjmp(3C)
