UNW_RESUME(3libunwind)

💖 UNW_RESUME 💖

okay bestie, gather round, because we're about to talk about resuming execution in a particular stack frame and honestly? it's giving time travel but for registers. this is unw_resume(3libunwind) from the libunwind programming library and she is iconic. 🦋

---

✨ SYNOPSIS ✨

#include <libunwind.h>

int unw_resume(unw_cursor_t *cp);

literally that's it. one function. one cursor. one vibe. 💅

---

🌸 DESCRIPTION 🌸

so unw_resume() resumes execution at the stack frame identified by cp. and here's the tea: the behavior differs slightly depending on whether you're doing local or remote unwinding. two moods, one function, we love a versatile queen. 👑

💫 Local unwinding

For local unwinding, unw_resume() restores the machine state and then directly resumes execution in the target stack frame. Which means... yeah... unw_resume() does not return in this case. it just leaves. no goodbye. no text back. 💀

Restoring the machine state normally involves restoring the ``preserved'' (callee-saved) registers. However — and this is the plot twist — if execution in any of the stack frames younger (more deeply nested) than the one identified by cp was interrupted by a signal, then unw_resume() will restore all registers as well as the signal mask. she does the full glam routine, not just the touch-up. ✨

🚨 BESTIE WARNING 🚨 — attempting to call unw_resume() on a cursor which identifies the stack frame of another thread results in undefined behavior (e.g., the program may crash). do NOT do this. this is not the moment. this is not the vibe check you want to fail. 😭

🌈 Remote unwinding

For remote unwinding, unw_resume() installs the machine state identified by the cursor by calling the access_reg and access_fpreg accessor callbacks as needed. Once that's accomplished, the resume accessor callback is invoked. Then unw_resume returns normally — that is, unlikely for local unwinding, unw_resume will always return for remote unwinding. so remote is the emotionally available one, basically. 🫶

👑 The exception-argument-register situation

Most platforms reserve some registers to pass arguments to exception handlers (e.g., IA-64 uses r15-r18 for this purpose). These registers are normally treated like ``scratch'' registers.

But if libunwind is used to set an exception argument register to a particular value (e.g., via unw_set_reg()), then unw_resume() will install this value as the contents of the register. In other words, the exception handling arguments are installed even in cases where normally only the ``preserved'' registers are restored. she remembered. she always remembers. 🎀

🙈 The one thing she will NOT do

Note that unw_resume() does not invoke any unwind handlers (aka, ``personality routines''). If a program needs this, it will have to do so on its own by obtaining the unw_proc_info_t of each unwound frame and appropriately processing its unwind handler and language-specific data area (lsda). These steps are generally dependent on the target platform and are regulated by the processor-specific ABI (application-binary interface).

tl;dr: she's not your personality-routine babysitter. you want that, you do it yourself, main character. 💅

---

⭐ RETURN VALUE ⭐

• For local unwinding, unw_resume() does not return on success. (she's gone, she's thriving, she's not texting back 🦋)
• For remote unwinding, it returns 0 on success.
• On failure, the negative value of one of the errors below is returned.

---

🧚 THREAD AND SIGNAL SAFETY 🧚

unw_resume() is thread-safe. ✨ And if cursor cp is in the local address-space, this routine is also safe to use from a signal handler. multi-tasking icon behavior, no cap. 🎀

---

💀 ERRORS 💀

• UNW_EUNSPEC — An unspecified error occurred. (mysterious. unbothered. no further comment.)
• UNW_EBADREG — A register needed by unw_resume() wasn't accessible. (she needed that register and it ghosted her. 😭)
• UNW_EINVALIDIP — The instruction pointer identified by cp is not valid.
• UNW_BADFRAME — The stack frame identified by cp is not valid.

---

🔥 SEE ALSO 🔥

• libunwind(3libunwind)
• unw_set_reg(3libunwind)
• sigprocmask(2)

go read those too, bestie, the lore is deep. 📚

---

💜 AUTHOR 💜

David Mosberger-Tang

• Email: dmosberger@gmail.com
• WWW: http://www.nongnu.org/libunwind/

---

and that's the whole page, periodt. 🌈 this was the Programming Library manual, dated 29 August 2023, and it lives at UNW_RESUME(3libunwind). stay safe out there, don't resume another thread's stack frame, and hydrate. 🍓✨💖