SETJMP(3)

💖 SETJMP(3) — non-local jumps · Library Functions Manual

🌸 NAME

sigsetjmp, siglongjmp, setjmp, longjmp, _setjmp, _longjmp, longjmperror — non-local jumps

📚 LIBRARY

Standard C Library (libc, -lc). Yes bestie, it lives in libc 💅

✨ 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

Okay so picture a save point in a game, but make it C. The sigsetjmp(), setjmp(), and _setjmp() functions save their calling environment in env. Each one returns 0. Iconic behavior, honestly 🎀

The matching longjmp() functions restore the environment saved by their most recent respective invocations of the setjmp() function. Then they return so your program keeps going as if that setjmp() call had just returned the value you passed in val instead of 0. It’s giving “the call came back different” energy ✨

• Mixing pairs is allowed: both sigsetjmp() with siglongjmp() and setjmp() with longjmp() combinations may be used in the same program. But individual calls may not be mixed — for example, the env argument to setjmp() may not be passed to siglongjmp() 🙅‍♀️

Do not call the longjmp() routines after the routine which called the setjmp() routines returns. That’s the cursed timeline, bestie. No cap 💀

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 the longjmp() call are indeterminate. So yeah, those values are not giving reliable, and that’s on purpose 😭

Signal-mask tea ☕:

• setjmp() / longjmp() pairs save and restore the signal mask.
• _setjmp() / _longjmp() pairs save and restore only the register set and the stack. (See sigprocmask(2).)
• 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.

😭 ERRORS

This is the yikes section, so listen up 🫶

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

• sigaction(2)
• sigaltstack(2)
• signal(3)

📜 STANDARDS

• The setjmp() and longjmp() functions conform to ISO/IEC 9899:1990 (“ISO C90”).
• The sigsetjmp() and siglongjmp() functions conform to IEEE Std 1003.1-1988 (“POSIX.1”).

🕰️ HISTORY

The setjmp() and longjmp() functions first appeared in the Programmer's Workbench (PWB/UNIX). Vintage behavior, but make it slay 🌈

---

xoxo, Debian 💖 April 2, 2022 🎀