77 Non-local jumps — <setjmp.h>

77.1 Why it exists — the makeshift of a language without exceptions

When trouble arises deep down, a language with exceptions escapes to the upper floors with one throw. C has none. So an error must be carried up one layer at a time as a return value, and every function in between must take that value and pass it on (chapter 51).

setjmp/longjmp is the device that skips that chain. It was already in Unix V7 in the 1970s, and its reason for being was the same as now — getting out of deep recursion in one move.

The standard’s footnote states the purpose narrowly: these functions “are useful for dealing with unusual conditions encountered in a low-level function of a program.” That is, the original place of the device is an escape hatch for exceptional situations, not a substitute for exceptions.

77.2 The two words — the exact shape

77.2.1 setjmp — the macro that seems to return twice

setjmp is a macro, not a function (the standard allows a function to be provided as well, but suppressing the macro and calling the function directly is undefined behaviour).

The rule for its return value is simple, and it is nearly the whole header.

That is why longjmp(env, 0) cannot produce 0. Zero already means “saving right now”, so the standard turns it into 1.

/* <setjmp.h> — going back to a saved place. Follow the flow with your eyes. */
#include <setjmp.h>
#include <stdio.h>

static jmp_buf env;

static void deep(int level)
{
    printf("  entering depth %d\n", level);
    if (level == 3) {
        puts("  trouble at depth 3 — longjmp(env, 42)");
        longjmp(env, 42);        /* does not return from here */
    }
    if (level < 5) deep(level + 1);   /* the guard keeps the compiler from seeing infinite recursion */
    printf("  leaving depth %d normally\n", level);      /* not reached */
}

int main(void)
{
    /* setjmp appears to yield a value *twice*:
       (1) 0 when called directly, (2) the val when returned to by longjmp */
    int rc = setjmp(env);

    if (rc == 0) {
        puts("(1) setjmp returned 0 — meaning the place was saved");
        deep(1);
        puts("this line does not run");
    } else {
        printf("(2) setjmp returned %d — we came back by longjmp\n", rc);
    }

    /* even longjmp(env, 0) does not make setjmp return 0 — it becomes 1 */
    static int once;
    if (!once) {
        once = 1;
        puts("\ntesting longjmp(env, 0):");
        longjmp(env, 0);
    }
    printf("\nsizeof(jmp_buf) = %zu bytes\n", sizeof(jmp_buf));
    return 0;
}

(1) setjmp returned 0 — meaning the place was saved
  entering depth 1
  entering depth 2
  entering depth 3
  trouble at depth 3 — longjmp(env, 42)
(2) setjmp returned 42 — we came back by longjmp

testing longjmp(env, 0):
(2) setjmp returned 1 — we came back by longjmp

sizeof(jmp_buf) = 200 bytes

The demonstration follows that flow exactly. The first time it yields 0 and goes down into deep; at depth 3 the longjmp(env, 42) brings us straight back to main’s setjmp and 42 appears. The intervening deep(2) and deep(1) never get to print their “leaving normally” line — those frames simply vanished.

The last test is longjmp(env, 0). We gave 0, and 1 came back.

77.2.2 Where setjmp may appear — four contexts only

The standard (§7.13.1.1) restricts the context by enumeration. Using it outside these four is undefined behaviour.

So int rc = setjmp(env); is not one of the standard’s contexts. It does work on many implementations and this book’s demonstration writes it that way, but where portability matters, switch (setjmp(env)) or if (setjmp(env) == 0) is the safer form.

77.2.3 longjmp — three things to check before jumping

longjmp(env, val) does not return (C23 marks it [[noreturn]]). Three conditions must hold before jumping, and breaking any one is undefined behaviour.

The second is the accident that happens most often. Thinking “I will make an error handler and call it from anywhere”, one calls longjmp after the function that called setjmp has already returned — and by then another function’s frame has moved into that place.

77.3 What jmp_buf really is

jmp_buf is an array type. The standard nails that down for a practical reason — being an array, passing it to a function decays it to the address of its first element (chapter 38), so setjmp(env) can modify the original without writing &env.

What is inside? The standard says only “information sufficient for longjmp to restore the calling environment”. In practice it is roughly these.

The size the demonstration printed (200 bytes on this implementation) is the sum of those contents. But looking inside or editing it by hand is outside the contract — treat it as opaque data.

The standard is also explicit about what is not saved: the state of the floating-point environment, of open files, or of any other component of the abstract machine. That one sentence produces every pitfall in the next section.

77.3.1 Looking inside the eight slots

On this implementation (glibc, x86-64) the 200 bytes of a jmp_buf divide thus.

Print the eight slots and their order appears — RBX, RBP, R12, R13, R14, R15, the stack pointer, the return address. That is exactly the list the x86-64 SysV calling convention marks callee-saved (chapter 44′s automatic lifetime and call frames).

Two things stand out.

First, three of the slots hold scrambled values. Print the slots for RBP, the stack pointer and the return address and they do not look like stack addresses. glibc stores them mixed with a per-thread guard value — a device against overwriting a jmp_buf to jump to an address of the attacker’s choosing. It confirms the rule that the inside of a jmp_buf is not to be edited by hand.

Second, registers not on that list are not saved. RAX, RCX, RDX, RSI, RDI and R8–R11 are the ones the convention marks “the caller’s business” (caller-saved), so setjmp does not keep them.

77.3.2 And that is the volatile rule

Read those two facts from a local variable’s point of view and the next section’s rule follows by itself. A compiler puts a local in one of three places.

Turn optimisation off and the compiler mostly puts locals on the stack, so only the first row happens — which is why nothing appears wrong at -O0. Turn it on and heavily used variables move into registers, and the second and third rows appear.

It is also why the standard writes “indeterminate representation” rather than “becomes the old value”. The result depends on where the variable was, so the standard promises none of them.

77.4 What happens to values on return — the volatile rule

The most practical rule in this chapter. The standard (§7.13.2.1) settles it thus.

All objects have the values they had at the time longjmp was called, with one exception — objects of automatic storage duration local to the function containing the setjmp, that are not volatile and have been changed since the setjmp, have indeterminate representations.

/* what happens to locals after a longjmp — why volatile is needed. */
#include <setjmp.h>
#include <stdio.h>

static jmp_buf env;

static void fail(void) { longjmp(env, 1); }

int main(void)
{
    /* The standard's rule (§7.13.2.1): among the automatic variables of the
       function that called setjmp, those that are
       (1) not volatile and
       (2) changed between setjmp and longjmp
       have *indeterminate representations* after the longjmp.
       Every other object keeps the value it had when longjmp was called. */
    int                 plain    = 1;    /* risky: automatic + non-volatile */
    volatile int        guarded  = 1;    /* safe: volatile */
    static int          statik   = 1;    /* safe: static storage duration */

    if (setjmp(env) == 0) {
        plain   = 2;                     /* changed between setjmp and longjmp */
        guarded = 2;
        statik  = 2;
        puts("all three set to 2, then longjmp");
        fail();
    }

    printf("\nafter coming back by longjmp:\n");
    printf("  plain   (automatic, non-volatile) = %d   <- not guaranteed\n",
           plain);
    printf("  guarded (automatic, volatile)     = %d   <- guaranteed\n", guarded);
    printf("  statik  (static)                  = %d   <- guaranteed\n", statik);

#ifdef __OPTIMIZE__
    puts("\n(This build has optimization on. See that plain came back as 1 —");
    puts(" the compiler had kept that variable in a register.)");
#else
    puts("\n(This build has optimization off. plain shows 2, but that is not a");
    puts(" guarantee — the same code built with -O2 prints 1. We checked.)");
#endif
    puts("One rule: put volatile on any local that must survive across a");
    puts("longjmp.");
    return 0;
}

all three set to 2, then longjmp

after coming back by longjmp:
  plain   (automatic, non-volatile) = 2   <- not guaranteed
  guarded (automatic, volatile)     = 2   <- guaranteed
  statik  (static)                  = 2   <- guaranteed

(This build has optimization off. plain shows 2, but that is not a
 guarantee — the same code built with -O2 prints 1. We checked.)
One rule: put volatile on any local that must survive across a
longjmp.

Three variables split exactly along that rule.

This rule really does bite. Build with optimisation off and all three show 2; build the same code with -O2 and plain comes back as 1 — the compiler had kept that variable in a register, and longjmp restored the registers to their values at setjmp. This book ran both builds and confirmed the difference, and the example reports which build it is by looking at __OPTIMIZE__.

77.5 Nobody cleans up the resources

longjmp only rolls back the stack pointer. Whatever was taken in between stays taken.

void work(void) {
    FILE *f = fopen("data", "r");     /* opened */
    char *buf = malloc(1024);          /* taken */
    parse(f, buf);                     /* if a longjmp happens here… */
    free(buf);                         /* does not run — a leak */
    fclose(f);                         /* does not run — the file leaks too */
}

So code that uses this device keeps one discipline without exception — gather the places that take and release resources inside the function that called setjmp. Having jumped back, that function can clean up itself.

77.5.1 The quieter accident — a pointer reverts to its old value

The previous counter-example was a free that never ran. There is a quieter one. The cleanup code runs perfectly well, but the pointer saying what to free falls foul of the previous section’s rule and reverts to its old value.

/* when a pointer reverts after a longjmp — the road to leaks and double frees. */
#include <setjmp.h>
#include <stdio.h>
#include <stdlib.h>

static jmp_buf  env;
static void    *recorded;       /* the address malloc really returned (static, so safe) */

[[noreturn]] static void fail(void) { longjmp(env, 1); }

int main(void)
{
    char          *risky = NULL;   /* automatic + non-volatile — the risky place */
    char *volatile safe  = NULL;   /* the pointer itself is volatile */

    if (setjmp(env) == 0) {
        risky    = malloc(64);
        safe     = risky;
        recorded = risky;
        if (!risky) return 1;
        puts("took 64 bytes with malloc. then something deep fails.");
        fail();
    }

    /* back again. do the two variables still hold the same address? */
    printf("does risky hold the allocated address? %s\n",
           (void *)risky == recorded ? "yes" : "no - it reverted to the old value");
    printf("does safe  hold the allocated address? %s\n",
           (void *)safe  == recorded ? "yes" : "no - it reverted to the old value");

#ifdef __OPTIMIZE__
    puts("\n(This build has optimization on. See risky revert to the null it held");
    puts(" at setjmp: free(risky) frees null, does nothing, and 64 bytes leak.)");
#else
    puts("\n(This build has optimization off. Both survived, but risky is not");
    puts(" guaranteed - built with -O2 it reverts to null. We checked.)");
#endif

    free((void *)safe);            /* free through the volatile one — the only one inside the contract */
    puts("freed exactly once, through safe.");
    return 0;
}

took 64 bytes with malloc. then something deep fails.
does risky hold the allocated address? yes
does safe  hold the allocated address? yes

(This build has optimization off. Both survived, but risky is not
 guaranteed - built with -O2 it reverts to null. We checked.)
freed exactly once, through safe.

At -O0 both survive, but build the same code at -O1 or above and the non-volatile one reverts to the null it held at setjmp (we checked). Then free(risky) frees null, does nothing, and 64 bytes leak for good — clear the static copy and ASan reports it as “Direct leak of 64 byte(s)”.

There is cleanup code, and it still leaks. Reading the code will not show it, and it appears only in the optimised build that ships. Of the accidents in this pattern it is the hardest to diagnose.

There is an opposite direction too. If the old value is not null but an address already freed, it is a double free.

char *p = malloc(64);
if (setjmp(env) == 0) {
    free(p);            /* freed once */
    p = malloc(128);    /* and taken afresh */
    work(p);            /* a longjmp happens here */
}
free(p);                /* if p reverted, this frees what was already freed */

The discipline is one line — do not keep a pointer that must survive a longjmp in an automatic local. Give it volatile, or put it in a static variable or a context struct. The load_image of the next demonstration does exactly that.

/* imitating exceptions — the error pattern libjpeg's family uses, and its price. */
#include <setjmp.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

/* ── a shrunken copy of libjpeg's error manager ────────────────────
   A jmp_buf sits inside the struct, and a failure deep down jumps to it.
   libjpeg's setup_error_handler and png_jmpbuf are exactly this shape. */
typedef struct {
    jmp_buf env;
    char    message[64];
    int     code;
} error_ctx;

static error_ctx *current;          /* the context in force (one global) */

[[noreturn]] static void throw_error(int code, const char *msg)
{
    snprintf(current->message, sizeof current->message, "%s", msg);
    current->code = code;
    longjmp(current->env, 1);       /* to the caller's setjmp */
}

/* the deep functions — they do not return errors as values */
static int parse_header(const char *s)
{
    if (strncmp(s, "IMG", 3) != 0) throw_error(2, "magic does not match");
    return 3;
}

static int parse_size(const char *s)
{
    int n = atoi(s);
    if (n <= 0)      throw_error(3, "size is zero or less");
    if (n > 1000000) throw_error(4, "size is too large");
    return n;
}

/* ── the side that wraps the flow ──────────────────────────────── */
static int load_image(const char *text, char *err, size_t errcap)
{
    error_ctx ctx = { .code = 0 };
    error_ctx *saved = current;
    current = &ctx;

    /* resources are taken here — coming back by longjmp, we must free them *ourselves* */
    void *buffer = malloc(1024);
    if (!buffer) { current = saved; return -1; }

    volatile int result;            /* survives across the longjmp */
    if (setjmp(ctx.env) == 0) {
        int off = parse_header(text);
        int n   = parse_size(text + off);
        printf("  success: size %d\n", n);
        result = n;
    } else {
        snprintf(err, errcap, "%s (code %d)", ctx.message, ctx.code);
        result = -1;
    }

    free(buffer);                   /* both paths pass here — the heart of the design */
    current = saved;
    return result;
}

int main(void)
{
    const char *cases[] = { "IMG640", "BMP640", "IMG0", "IMG9999999" };
    for (size_t i = 0; i < sizeof cases / sizeof *cases; i++) {
        char err[96] = "";
        printf("input \"%s\":\n", cases[i]);
        int rc = load_image(cases[i], err, sizeof err);
        if (rc < 0) printf("  failure: %s\n", err);
    }

    puts("\nThree conditions this pattern needs:");
    puts("  (1) freeing happens in *one place* inside the function that called setjmp");
    puts("  (2) locals that cross the longjmp carry volatile");
    puts("  (3) longjmp happens only while that function is still alive");
    return 0;
}

input "IMG640":
  success: size 640
input "BMP640":
  failure: magic does not match (code 2)
input "IMG0":
  failure: size is zero or less (code 3)
input "IMG9999999":
  failure: size is too large (code 4)

Three conditions this pattern needs:
  (1) freeing happens in *one place* inside the function that called setjmp
  (2) locals that cross the longjmp carry volatile
  (3) longjmp happens only while that function is still alive

The demonstration’s load_image is that structure. The malloc happens before the setjmp, and the free sits once, in a place both the success and the failure path pass through. The deep parse_header and parse_size take no resources and only jump.

77.6 What is actually built on this

The device is not recommended for new code, but what is already built is plentiful.

struct my_error_mgr { struct jpeg_error_mgr pub; jmp_buf setjmp_buffer; };

static void my_error_exit(j_common_ptr cinfo) {
    struct my_error_mgr *err = (struct my_error_mgr *)cinfo->err;
    longjmp(err->setjmp_buffer, 1);
}

77.6.1 How do they cope with memory — the answer is always the same

Read the previous table again, this time asking only “who frees the memory taken before the jump?”

The common thread is visible — they are all arenas. The flaw that longjmp cleans up nothing was worked around by a structure in which no individual free is needed: tie everything taken into one bundle, and at the place you jump back to, throw away that one bundle.

So one more conclusion attaches. Use setjmp without an arena and a leak is a matter of time. Part XII’s arena is also the precondition that makes this pattern legitimate.

77.7 POSIX’s sigsetjmp/siglongjmp

Unix-like systems have one more pair.

int  sigsetjmp(sigjmp_buf env, int savemask);
[[noreturn]] void siglongjmp(sigjmp_buf env, int val);

The difference is whether the signal mask (chapter 76) is saved along with the rest. If savemask is non-zero the current mask is saved too, and siglongjmp restores it.

Why is that needed? Consider code that escapes from a signal handler with longjmp. While the handler runs that signal is blocked, and jumping out with the standard longjmp may leave it blocked — after which that signal never arrives again. sigsetjmp closes that hole.

77.8 Its place today — when to use it, what to use instead

The goto cleanup pattern is worth writing out again, because most of what people reach for setjmp to do is in fact covered by it.

int work(void) {
    int rc = -1;
    FILE *f = fopen("data", "r");
    if (!f) goto out;
    char *buf = malloc(1024);
    if (!buf) goto close;
    if (parse(f, buf) != 0) goto free_buf;
    rc = 0;
free_buf: free(buf);
close:    fclose(f);
out:      return rc;
}

Within one function this is better. The flow is visible, the order of cleanup is written in the code, and the compiler checks it. setjmp is needed only when several functions must be skipped over.

We have seen the two devices that cut a flow and jump — the signal that comes from outside, and the non-local jump that leaps from within. The next chapter is what recent standards added, and the long argument over “safe” functions.