SETJMP(3) — UNIX Programmer’s Manual

NAME

setjmp, longjmp, _setjmp, _longjmp, __longjmp, longjmperror − non-local goto

SYNOPSIS

#include <setjmp.h>

setjmp(env)
jmp_buf env;

longjmp(env, val)
jmp_buf env;

_setjmp(env)
jmp_buf env;

_longjmp(env, val)
jmp_buf env;

__longjmp(env, val)
jmp_buf env;

longjmperror()

DESCRIPTION

These routines are useful for dealing with errors and interrupts encountered in a low-level subroutine of a program. (But see the BUGS section below).

Setjmp saves its stack environment in env for later use by longjmp. It returns value 0.

Longjmp restores the environment saved by the last call of setjmp. It then returns in such a way that execution continues as if the call of setjmp had just returned the value val to the function that invoked setjmp, which must not itself have returned in the interim. All accessible data have values as of the time longjmp was called.

Setjmp and longjmp save and restore the signal mask sigmask(2), while _setjmp and _longjmp do not. In fact on the ARM _setjmp functions in precisely the same way as setjmp (ie the mask is saved in env). _longjmp does not restore the mask from env − it does, however, correctly exit from a signal handler.

__longjmp is the ARM specific low level interface − see the description of longjmperror below.

ERRORS

If the contents of the jmp_buf are corrupted, or correspond to an environment that has already returned, longjmp calls the routine longjmperror. If longjmperror returns the program is aborted by a call to abort(3) − no error message is output, longjmperror is expected to do this. The default version of longjmperror prints the message “longjmp botch: <reason>” to standard error using perror(3) and returns. User programs wishing to exit more gracefully can write their own versions of longjmperror.

The ARM specific function __longjmp functions exactly as longjmp except that it simply returns on error. This provides a cleaner interface to errors in setjmp or longjmp calls, although it is, of course, not portable.

BUGS

The current implementation of longjmp only works correctly with versions of the Norcroft C compiler cc (1) of or later than version 300/330 (dated May 15 1989). Earlier versions assume a longjmp implementation which unwinds the stack, restoring register values as it goes. The compiler recognises the name setjmp and adjusts code generation to take account of the implementation of longjmp. As a result use of _setjmp (which is not recognised by the compiler) is always unreliable; it is most strongly recommended that this interface is never used. The identical functionality is obtained by calling setjmp then using _longjmp with the resulting jmpbuf.

Museum