UNW_STEP(3libunwind)

✨ UNW_STEP — advance to next stack frame ✨

okay bestie, this is a page from the libunwind programming library, and today's main character is unw_step. it's giving "walk the stack, one frame at a time" 💅

---

🌸 SYNOPSIS 🌸

#include <libunwind.h>

int unw_step(unw_cursor_t *cp);

---

💖 DESCRIPTION 💖

so unw_step() takes your unwind cursor cp and advances it to the next older, less deeply nested stack frame. that's it, that's the whole vibe. you're literally just walking up the stack, frame by frame, like scrolling up in a group chat to find the message where it all went wrong 😭

---

👑 RETURN VALUE 👑

on a successful completion, here's the tea:

• unw_step() returns a positive value if the updated cursor is pointing at a valid stack frame 🫶
• it returns 0 if the previous stack frame was the last frame in the chain (you hit the end, no more scrolling bestie)
• on error, it returns the negative value of one of the error codes listed below 💀

---

🦋 THREAD AND SIGNAL SAFETY 🦋

unw_step() is thread-safe. periodt. ✨

and if the cursor cp is in the local address-space, this routine is also safe to use from a signal handler. iconic behaviour fr fr.

---

🎀 ERRORS 🎀

here's the full roster of ways this can go sideways. no skipping, we list them all:

• UNW_EUNSPEC — an unspecified error occurred. (mystery error, very main character, zero explanation 🙈)
• UNW_ENOINFO — libunwind was unable to locate the unwind-info needed to complete the operation.
• UNW_EBADVERSION — the unwind-info needed to complete the operation has a version or a format that is not understood by libunwind.
• UNW_EINVALIDIP — the instruction-pointer (program-counter) of the next stack frame is invalid (e.g., not properly aligned).
• UNW_EBADFRAME — the next stack frame is invalid. 😭
• UNW_ESTOPUNWIND — returned if a call to find_proc_info() returned -UNW_ESTOPUNWIND.

also, heads up: unw_step() may return any error returned by the find_proc_info(), get_dyn_info_list_addr(), access_mem(), access_reg(), or access_fpreg() call-backs — see unw_create_addr_space(3libunwind). so if one of those is acting up, that's on them, not on unw_step() 🫠

---

🌈 SEE ALSO 🌈

• libunwind(3libunwind)
• unw_create_addr_space(3libunwind)

---

💜 AUTHOR 💜

David Mosberger-Tang

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

---

and that's the whole page, bestie 💖 this one's from the Programming Library, dated 29 August 2023, and it lives under the name UNW_STEP(3libunwind). slay, go unwind something. 🌸🦋✨