Standard C Library Functions setjmp(3C)
NAME
setjmp, sigsetjmp, longjmp, siglongjmp - non-local goto
SYNOPSIS
#include
int setjmp(jmpbuf env);
int sigsetjmp(sigjmpbuf env, int savemask);
void longjmp(jmpbuf env, int val);
void siglongjmp(sigjmpbuf env, int val);
DESCRIPTION
These functions are useful for dealing with errors and
interrupts encountered in a low-level subroutine of a pro-
gram.
The setjmp() function saves its stack environment in env for
later use by longjmp().
The sigsetjmp() function saves the calling process's regis-
ters and stack environment (see sigaltstack(2)) in env for
later use by siglongjmp(). 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() completes, 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 siglongjmp() completes, program execution
continues as if the corresponding call to sigsetjmp() had
SunOS 5.11 Last change: 14 Aug 2002 1
Standard C Library Functions setjmp(3C)
just returned the value val. The siglongjmp() function can-
not cause sigsetjmp() to return the value 0. If
siglongjmp() is invoked with a second argument of 0, sig-
setjmp() will return 1. At the time of the second return
from sigsetjmp(), all external and static variables have
values as of the time siglongjmp() was called.
If a signal-catching function interrupts sleep(3C) and calls
siglongjmp() to restore an environment saved prior to the
sleep() call, the action associated with SIGALRM and time it
is scheduled to be generated are unspecified. It is also
unspecified whether the SIGALRM signal 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() function with a non-zero savemask argument.
The values of register and automatic variables are unde-
fined. 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 sig-
setjmp() 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 specified 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() func-
tion cannot cause sigsetjmp() to return 0; if val is 0, sig-
setjmp() returns 1.
EXAMPLES
Example 1 Example of setjmp() and longjmp() functions.
SunOS 5.11 Last change: 14 Aug 2002 2
Standard C Library Functions setjmp(3C)
The following example uses both setjmp() and longjmp() to
return the flow of control to the appropriate instruction
block:
#include
#include
#include
#include
jmpbuf env; static void signalhandler();
main() {
int returnedfromlongjump, processing = 1;
unsigned int timeinterval = 4;
if ((returnedfromlongjump = setjmp(env)) != 0)
switch (returnedfromlongjump) {
case SIGINT:
printf("longjumped from interrupt %d\n",SIGINT);
break;
case SIGALRM:
printf("longjumped from alarm %d\n",SIGALRM);
break;
}
(void) signal(SIGINT, signalhandler);
(void) signal(SIGALRM, signalhandler);
alarm(timeinterval);
while (processing) {
printf(" waiting for you to INTERUPT (cntrl-C) ...\n");
sleep(1);
} /* end while forever loop */
}
static void signalhandler(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
SunOS 5.11 Last change: 14 Aug 2002 3
Standard C Library Functions setjmp(3C)
Additionally, every 4 seconds the alarm will expire, signal-
ling this process, and the output will be:
longjumped from alarm
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Standard
MT-Level Unsafe
SEE ALSO
getcontext(2), priocntl(2), sigaction(2), sigaltstack(2),
sigprocmask(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 Last change: 14 Aug 2002 4
|
