C Standard Library setjmp.h

What You’ll Learn

<setjmp.h> defines non-local jumps: save where you are with setjmp, then snap back later with longjmp. It is powerful for deep error recovery (parsers, interpreters) but dangerous for everyday code because it bypasses normal returns and cleanup.

Definition and Usage

A normal function returns with return. setjmp / longjmp let you jump back to an earlier point in the call stack without unwinding each function in between. The saved state lives in a jmp_buf object.

Think of setjmp(env) as planting a bookmark. The first time it runs, the bookmark is placed and the call returns 0. Later, longjmp(env, val) reopens the book at that bookmark; setjmp appears to return again, this time with a non-zero value derived from val.

📝 Syntax

Include the header:

#include <setjmp.h>

Types and macros

jmp_buf env;           /* buffer holding saved environment */

int setjmp(jmp_buf env);
void longjmp(jmp_buf env, int val);

setjmp and longjmp may be implemented as macros. Do not use env as an expression with side effects, and do not return from the function that called setjmp if longjmp might still target that buffer.

Return rules

• setjmp first call → returns 0.
• longjmp(env, val) → setjmp returns val, unless val == 0, then it returns 1.
• Use distinct non-zero val values to signal different error types.

Critical restrictions

• Only volatile local variables are reliable after longjmp.
• Do not longjmp to a setjmp in a function that already returned.
• Automatic variables in the function that called setjmp may be indeterminate unless volatile.
• longjmp does not call fclose, free, etc.—clean up first or leak resources.

Headers and linking

• #include <setjmp.h> — no special link flag.
• Compile: gcc program.c -std=c11 -o program

Examples Gallery

Compile with gcc file.c -std=c11 -o out. These examples are for learning control flow—in production, prefer return codes and structured cleanup.

#include <setjmp.h>
#include <stdio.h>

static jmp_buf env;

void divide(int a, int b) {
    if (b == 0) {
        longjmp(env, 1);
    }
    printf("Result: %d\n", a / b);
}

int main(void) {
    if (setjmp(env) == 0) {
        divide(10, 2);
        divide(10, 0);   /* triggers longjmp */
        printf("This line is skipped\n");
    } else {
        printf("Error: Division by zero!\n");
    }

    printf("Program continues after recovery\n");
    return 0;
}

Result: 5
Error: Division by zero!
Program continues after recovery

#include <setjmp.h>
#include <stdio.h>

static jmp_buf env;

void fail(int code) {
    longjmp(env, code);
}

int main(void) {
    int err = setjmp(env);

    if (err == 0) {
        printf("Normal path\n");
        fail(42);
    } else if (err == 42) {
        printf("Caught error code 42\n");
    } else {
        printf("Unknown error %d\n", err);
    }

    return 0;
}

Normal path
Caught error code 42

#include <setjmp.h>
#include <stdio.h>

static jmp_buf env;

void level3(void) {
    printf("  level3: about to longjmp\n");
    longjmp(env, 99);
}

void level2(void) {
    printf(" level2\n");
    level3();
    printf(" level2: never reached\n");
}

void level1(void) {
    printf("level1\n");
    level2();
}

int main(void) {
    if (setjmp(env) == 0) {
        level1();
    } else {
        printf("Recovered in main (code 99)\n");
    }
    return 0;
}

level1
 level2
  level3: about to longjmp
Recovered in main (code 99)

#include <stdio.h>

int safe_divide(int a, int b, int *out) {
    if (b == 0) {
        return -1;
    }
    *out = a / b;
    return 0;
}

int main(void) {
    int result;

    if (safe_divide(10, 2, &result) == 0) {
        printf("Result: %d\n", result);
    }

    if (safe_divide(10, 0, &result) != 0) {
        printf("Error: Division by zero!\n");
    }

    return 0;
}

Result: 5
Error: Division by zero!

#include <setjmp.h>
#include <stdio.h>

static jmp_buf env;

int main(void) {
    volatile int counter = 0;
    int plain = 0;

    if (setjmp(env) == 0) {
        counter++;
        plain++;
        longjmp(env, 1);
    }

    printf("volatile counter = %d (reliable)\n", counter);
    printf("plain may be unreliable after longjmp (value: %d)\n", plain);

    return 0;
}

volatile counter = 1 (reliable)
plain may be unreliable after longjmp (value: 0 or 1)

🚀 Common Use Cases

• Expression parsers — abort parse on syntax error deep in recursion.
• Interpreters / VMs — bail out to a top-level REPL on fatal script errors.
• Unit test frameworks — some C test runners use jumps for failure recovery.
• Legacy codebases — error handling before widespread return-code discipline.
• Teaching — understand stack unwinding vs exceptions in other languages.
• Not recommended — everyday validation, file I/O, or network errors (use return codes).

📝 Notes

• setjmp / longjmp are not C++ exceptions—no destructors, no RAII.
• Mark locals volatile if their values matter after a jump.
• Never longjmp out of a function that has already returned from the setjmp caller.
• Free memory and close files before longjmp, or you leak resources.
• Using setjmp in multiple threads on the same jmp_buf is unsafe.
• POSIX offers sigsetjmp / siglongjmp when jumping from signal handlers—see signal.h.

⚡ Optimization

setjmp saves registers—not free, but usually cheaper than deep manual error propagation in huge recursive parsers. For simple functions, return codes are faster to execute and far easier for the compiler to optimize.

💡 Best Practices