UNW_REG...ITERATE(3libunwind)

💖 UNW_REG_STATES_ITERATE — a libunwind moment 💖

okay bestie, welcome to unw_reg_states_iterate, a lil routine from the Programming Library that lives in the 3libunwind manual. she's not flashy but she's so important, iykyk. let's get into it 🫶

---

✨ NAME ✨

unw_reg_states_iterate — get register state info on current procedure 👑

---

🌸 SYNOPSIS 🌸

#include <libunwind.h>

int unw_reg_states_iterate(unw_cursor_t *cp, unw_reg_states_callbackcb,
void *token);

---

🦋 DESCRIPTION 🦋

so unw_reg_states_iterate() gives you the tea ☕ about the procedure that created the stack frame identified by the argument cp. that's the vibe.

the cb argument is a pointer to a function of type unw_reg_states_callback, and that function is literally how the info gets handed back to you. and unw_reg_states_callback has this definition, no cap:

int ( *unw_reg_states_callback)(void *token, void *reg_states_data,
size_t reg_states_data_size, unw_word_t start_ip, unw_word_t end_ip);

now here's the part where it gets a little extra: the callback function may be invoked several times for each call of unw_reg_states_iterate. like, she's not a one-and-done girlie. 💅

each call is associated with an instruction address range plus a set of instructions on how to update register values when returning from the procedure in that address range. iconic behaviour honestly.

for each invocation, the arguments handed to the callback function are:

• void * token — the token value passed to unw_reg_states_callback. yes, it's just your lil token coming back home 🎀
• void * reg_states_data — a pointer to data about updating register values. this data, or a copy of it, can be passed to unw_apply_reg_state. keep it safe bestie 💖
• int reg_states_data_size — the size of the register update data. it's giving "know your size" ✨
• unw_word_t start_ip — the address of the first instruction of the address range. the beginning of the era 🌅
• unw_word_t end_ip — the address of the first instruction beyond the end of the address range. one step past the finish line, she's just outside 🏁

---

⭐ RETURN VALUE ⭐

on successful completion, unw_reg_states_iterate() returns 0. slay. ✅

if the callback function returns a nonzero value, that indicates failure and the function returns immediately. like, she's leaving, no further questions 😭

otherwise the negative value of one of the error codes below is returned. ngl, that part's a little rude.

---

🧚 THREAD AND SIGNAL SAFETY 🧚

unw_reg_states_iterate() is thread safe. 👑

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

---

💀 ERRORS 💀

• UNW_EUNSPEC — an unspecified error occurred. we don't know what happened and honestly we're not gonna find out 🙈
• UNW_ENOINFO — libunwind was unable to locate unwind-info for the procedure. the info said "not today" 💅
• UNW_EBADVERSION — the unwind-info for the procedure has version or format that is not understood by libunwind. she's speaking a language libunwind simply does not know 🫠

plus, unw_reg_states_iterate() may return any error returned by the access_mem() call-back (see unw_create_addr_space(3libunwind)). so like, the drama can come from elsewhere too.

---

🌈 SEE ALSO 🌈

• libunwind(3libunwind)
• unw_apply_reg_state(3libunwind)

---

👑 AUTHOR 👑

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

---

and that's the whole page, bestie!! 🎀 this was the Programming Library page for unw_reg_states_iterate, dated 29 August 2023, from the 3libunwind manual — go forth and iterate those register states, you absolute main character 💖✨🦋