NAME
sigsetjmp,
siglongjmp, setjmp,
longjmp, _setjmp,
_longjmp, longjmperror
— non-local jumps
SYNOPSIS
#include
<setjmp.h>
int
sigsetjmp(sigjmp_buf
env, int
savemask);
void
siglongjmp(sigjmp_buf
env, int val);
int
setjmp(jmp_buf
env);
void
longjmp(jmp_buf
env, int val);
int
_setjmp(jmp_buf
env);
void
_longjmp(jmp_buf
env, int val);
void
longjmperror(void);
DESCRIPTION
The
sigsetjmp(),
setjmp(), and
_setjmp()
functions save their calling environment in env. Each
of these functions returns 0.
The corresponding
longjmp()
functions restore the environment saved by the most recent invocation of the
respective setjmp() function. They then return so
that program execution continues as if the corresponding invocation of the
setjmp() call had just returned the value specified
by val, instead of 0. The value specified by
val must be non-zero; a 0 value is treated as 1 to
allow the programmer to differentiate between a direct invocation of
setjmp() and a return via
longjmp().
Pairs of calls may be intermixed; i.e., both
sigsetjmp()
and
siglongjmp()
as well as setjmp() and
longjmp() combinations may be used in the same
program. However, individual calls may not — e.g., the
env argument to setjmp() may
not be passed to siglongjmp().
The
longjmp()
routines may not be called after the routine which called the
setjmp() routines returns.
All accessible objects have values as of the time
the
longjmp()
routine was called, except that the values of objects of automatic storage
invocation duration that do not have the volatile
type and have been changed between the setjmp()
invocation and longjmp() call are indeterminate.
The
setjmp()/longjmp()
function pairs save and restore the signal mask while the
_setjmp()/_longjmp()
function pairs save and restore only the register set and the stack (see
sigmask(3)).
The
sigsetjmp()/siglongjmp()
function pairs save and restore the signal mask if the argument
savemask is non-zero. Otherwise, only the register set
and the stack are saved.
In other words,
setjmp()/longjmp()
are functionally equivalent to
sigsetjmp()/siglongjmp()
when sigsetjmp() is called with a non-zero
savemask argument. Conversely,
_setjmp()/_longjmp() are
functionally equivalent to
sigsetjmp()/siglongjmp()
when sigsetjmp() is called with a zero-value
savemask.
The
sigsetjmp()/siglongjmp()
interfaces are preferred for maximum portability.
ERRORS
If the contents of the env are corrupted or
correspond to an environment that has already returned, the
longjmp() routine calls the routine
longjmperror(3). If longjmperror()
returns, the program is aborted (see
abort(3)). The default version of
longjmperror() prints the message
“longjmp botch” to standard error and
returns. User programs wishing to exit more gracefully should write their
own versions of longjmperror().
SEE ALSO
STANDARDS
The setjmp() and
longjmp() functions conform to ANSI
X3.159-1989 (“ANSI C89”). The
sigsetjmp() and siglongjmp()
functions conform to IEEE Std 1003.1-1990
(“POSIX.1”).
CAVEATS
Historically, on AT&T System V
UNIX, the
setjmp()/longjmp() functions
have been equivalent to the BSD
_setjmp()/_longjmp()
functions and do not restore the signal mask. Because of this discrepancy,
the sigsetjmp()/siglongjmp()
interfaces should be used if portability is desired.
Use of longjmp() or
siglongjmp() from inside a signal handler is not as
easy as it might seem. Generally speaking, all possible code paths between
the setjmp() and longjmp()
must be signal race safe, as discussed in
signal(3). Furthermore, the code paths must not do resource
management (such as
open(2) or
close(2)) without blocking the signal in question, or resources might
be mismanaged. Obviously this makes longjmp() much
less useful than previously thought.