SETJMP(3POSIX)

📦 version 2017a, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 SETJMP — the POSIX programmer's manual, but make it cute 💖

okay bestie, before we even start: this page lives in the POSIX Programmer's Manual. But heads up — the Linux version of this interface might act different (so go check the matching Linux man page for the actual Linux tea ☕), or it might not even be implemented on Linux at all. Not every platform is gonna have this one, and that's just facts. 🙈

✨ NAME ✨

setjmp — set a jump point for a non-local goto, aka planting a little flag so you can teleport back to it later 🚩

🌸 SYNOPSIS 🌸

#include <setjmp.h>

int setjmp(jmp_buf env);

that's it, that's the whole vibe check 💅

🦋 DESCRIPTION 🦋

okay so everything on this page is aligned with the ISO C standard. If anything here ever clashes with the ISO C standard? Totally unintentional, no drama intended. This volume of POSIX.1‐2017 defers to the ISO C standard. periodt.

A call to setjmp() shall save the calling environment into its env argument, so longjmp() can come back to it later. it's giving "bookmark but for execution state" 🔖

Now here's a lil mystery for you: it is unspecified whether setjmp() is a macro or a function. So if a macro definition gets suppressed just so you can reach an actual function, or if a program defines an external identifier named setjmp — that's undefined behavior, bestie. do not do that. 💀

An application shall make sure that an invocation of setjmp() shows up in one of these contexts only:

  • The entire controlling expression of a selection or iteration statement
  • One operand of a relational or equality operator with the other operand an integral constant expression, with the resulting expression being the entire controlling expression of a selection or iteration statement
  • The operand of a unary '!' operator with the resulting expression being the entire controlling expression of a selection or iteration
  • The entire expression of an expression statement (possibly cast to void)

And if your invocation shows up in any other context? Undefined behavior. literally nowhere else, she said what she said 🚫

💜 RETURN VALUE 💜

  • If the return is from a direct invocation, setjmp() shall return 0.
  • If the return is from a call to longjmp(), setjmp() shall return a non-zero value.

zero means "hi I just got here", non-zero means "I've been sent back". iconic behavior honestly ✨

🎀 ERRORS 🎀

No errors are defined.

The following sections are informative. (translation: the important stuff is done, everything below is bonus content 🍓)

🌈 EXAMPLES 🌈

None. she's mysterious like that 💅

🫶 APPLICATION USAGE 🫶

ngl, in general sigsetjmp() is more useful when you're dealing with errors and interrupts popping up in a low-level subroutine of a program. so if that's your situation, maybe go say hi to her instead 👑

⭐ RATIONALE ⭐

None.

🧚 FUTURE DIRECTIONS 🧚

None.

🔥 SEE ALSO 🔥

  • longjmp()
  • sigsetjmp()

And from the Base Definitions volume of POSIX.1‐2017: <setjmp.h> 📚

Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1-2017, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between this version and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html .

Any typographical or formatting errors that appear in this page are most likely to have been introduced during the conversion of the source files to man page format. To report such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html .

🌸 that's a wrap bestie!! this absolute classic was brought to you by IEEE/The Open Group, dated 2017, from the SETJMP(3POSIX) page of the POSIX Programmer's Manual. go plant your jump point, save your env, and slay 💖🦋✨
📦 where this page comes from