setjmp

 

C

Language

Headers

Type support

Program utilities

Variadic function support

Error handling

Dynamic memory management

Date and time utilities

Strings library

Algorithms

Numerics

Input/output support

Localization support

Atomic operations (C11)

Thread support (C11)

Technical Specifications

 

Program support utilities

Program termination
abort exit quick_exit (C11) _Exit (C99)	atexit at_quick_exit (C11) EXIT_SUCCESSEXIT_FAILURE
Communicating with the environment
system	getenvgetenv_s (C11)
Signals
signal raise sig_atomic_t	SIG_DFLSIG_IGN SIG_ERR
Signal types
SIGABRTSIGFPESIGILLSIGINTSIGSEGVSIGTERM
Non-local jumps
setjmp
longjmp
Types
jmp_buf

 

Defined in header <setjmp.h>
#define setjmp(env) /* implementation-defined */

Saves the current execution context into a variable env of type jmp_buf. This variable can later be used to restore the current execution context by longjmp function. That is, when a call to longjmp function is made, the execution continues at the particular call site that constructed the jmp_buf variable passed to longjmp. In that case setjmp returns the value passed to longjmp.

The invocation of setjmp must appear only in one of the following contexts:

• the entire controlling expression of if, switch, while, do-while, for

switch(setjmp(env)) { ..

• one operand of a relational or equality operator with the other operand an integer constant expression, with the resulting expression being the entire controlling expression of if, switch, while, do-while, for

if(setjmp(env) > 10) { ...

• the operand of a unary ! operator with the resulting expression being the entire controlling expression of if, switch, while, do-while, for

while(!setjmp(env)) { ...

• the entire expression of an expression statement (possibly cast to void).

setjmp(env);

If setjmp appears in any other context, the behavior is undefined.

Upon return to the scope of setjmp, all accessible objects, floating-point status flags, and other components of the abstract machine have the same values as they had when longjmp was executed, except for the non-volatile local variables in setjmp's scope, whose values are indeterminate if they have been changed since the setjmp invocation.

Parameters

env

-

variable to save the execution state of the program to.

Return value

​0​ if the macro was called by the original code and the execution context was saved to env.

Non-zero value if a non-local jump was just performed. The return value in the same as passed to longjmp.

Example

Run this code

#include <stdio.h>
#include <setjmp.h>
#include <stdnoreturn.h>
 
jmp_buf jump_buffer;
 
noreturn void a(int count) 
{
    printf("a(%d) called\n", count);
    longjmp(jump_buffer, count+1); // will return count+1 out of setjmp
}
 
int main(void)
{
    volatile int count = 0; // modified local vars in setjmp scope must be volatile
    if (setjmp(jump_buffer) != 9) // compare against constant in an if
        a(++count);
}

Output:

a(1) called
a(2) called
a(3) called
a(4) called
a(5) called
a(6) called
a(7) called
a(8) called

References

• C11 standard (ISO/IEC 9899:2011):

• 7.13.1.1 The setjmp macro (p: 262-263)

• C99 standard (ISO/IEC 9899:1999):

• 7.13.1.1 The setjmp macro (p: 243-244)

• C89/C90 standard (ISO/IEC 9899:1990):

• 4.6.1 The setjmp macro

See also

longjmp

jumps to specified location (function)