UNW_GETCONTEXT(3libunwind)

📦
version 1.8.3 · 2 versions
, in alpine 3.22, alpine 3.23, alpine 3.24, arch rolling, epel 10, epel 9, fedora 43, fedora 44, nixpkgs unstable, opensuse-leap 16.0

💫 UNW_GETCONTEXT 💫

okay so this is a page from the libunwind manual, section 3libunwind, and bestie we are about to get into machine-state and it's honestly kind of iconic 🫶

✨ NAME ✨

unw_getcontext — get initial machine-state 💅

🌸 SYNOPSIS 🌸

#include <libunwind.h>

int unw_getcontext(unw_context_t *ucp);

🦋 DESCRIPTION 🦋

so. the unw_getcontext() routine initializes the context structure pointed to by ucp with the machine state of the call site. like, it's literally grabbing a lil snapshot of where you are right now 📸

the exact set of registers stored by unw_getcontext() is platform-specific, but, in general, at least all preserved (``callee-saved'') and all frame-related registers, such as the stack pointer, will be stored. so basically the important ones, no cap.

🚨 real talk: this routine is normally implemented as a macro and applications should not attempt to take its address. like... do not do that. it's giving undefined and we're not about that life 🙈

🎀 PLATFORM-SPECIFIC NOTES 🎀

on IA-64, unw_context_t has a layout that is compatible with that of ucontext_t and such structures can be initialized with getcontext() instead of unw_getcontext(). cute, right? ✨

however — and this is the part where you gotta pay attention bestie — the reverse is not true. it is not safe to use structures initialized by unw_getcontext() in places where a structure initialized by getcontext() is expected. 💀

the reason for this asymmetry is that unw_getcontext() is optimized for maximum performance and does not, for example, save the signal mask. she's fast, she's efficient, she's not doing the extra credit 💅

⭐ RETURN VALUE ⭐

  • on successful completion, unw_getcontext() returns 0 👑
  • otherwise, a value of -1 is returned 😭

💖 THREAD AND SIGNAL SAFETY 💖

unw_getcontext() is thread safe as well as safe to use from a signal handler. yes bestie, both. she does it all 🌈

🔥 SEE ALSO 🔥

🌟 AUTHOR 🌟

David Mosberger-Tang Email: dmosberger@gmail.com WWW: http://www.nongnu.org/libunwind/

and that's the whole vibe check, fr fr — this was the Programming Library manual, dated 29 August 2023, page UNW_GETCONTEXT(3libunwind). slay, go init some contexts, ily 💜

📦 where this page comes from