UNW_GET_PROC_INFO(3libunwind)

💖 UNW_GET_PROC_INFO 💖

okay so bestie, welcome to unw_get_proc_info(3libunwind) — it's a little function from the libunwind programming library and it's literally here to spill the tea about whatever procedure made a stack frame. sit down, grab a boba, we're doing this. 🧋

---

✨ NAME ✨

unw_get_proc_info — get info on current procedure

---

🌸 SYNOPSIS 🌸

#include <libunwind.h>

int unw_get_proc_info(unw_cursor_t *cp, unw_proc_info_t *pip);

---

🦋 DESCRIPTION 🦋

so the unw_get_proc_info() routine hands you back the auxiliary info about the procedure that created the stack frame your argument cp is pointing at. the pip argument is a pointer to a structure of type unw_proc_info_t, and that's where all the info goes to live. no cap.

and unw_proc_info_t has these members, okay, let's go one by one because she's got range:

• unw_word_t start_ip — the address of the very first instruction of the procedure. if this address can't be figured out (like, say, there's no unwind information to work with 😭), then start_ip gets cleared to 0.
• unw_word_t end_ip — the address of the first instruction beyond the end of the procedure (so, like, one past the finish line, not the last instruction itself 💅). if this address can't be determined (again, e.g. because of missing unwind information), end_ip gets cleared to 0.
• unw_word_t lsda — the address of the language-specific data area (LSDA). this area normally holds language-specific stuff that's needed during exception handling. if the procedure doesn't have one of those areas, this member is cleared to 0.
• unw_word_t handler — the address of the exception handler routine. sometimes people call this the personality routine. if the procedure doesn't define a personality routine, handler gets cleared to 0.
• unw_word_t gp — the global pointer of the procedure. on platforms that don't use a global pointer, this member may hold an undefined value 👀. on all other platforms, it must be set either to the correct global pointer value of the procedure, or to 0 if the proper global pointer can't be obtained for some reason.
• unw_word_t flags — a set of flags. rn there are no target-independent flags. for the IA-64 target tho, the flag UNW_PI_FLAG_IA64_RBS_SWITCH is set if the procedure may switch the register backing store.
• int format — the format of the unwind info for this procedure. if the unwind info is dynamic procedure info, format equals UNW_INFO_FORMAT_DYNAMIC. if the unwind info is a (target-specific) unwind table, it equals UNW_INFO_FORMAT_TABLE. all other values are reserved for future use by libunwind. this member exists for the find_proc_info() callback to use (peep unw_create_addr_space(3libunwind)). and heads up — unw_get_proc_info() may return an undefined value in this member. 🙈
• int unwind_info_size — the size of the unwind info in bytes. this member exists for use by the find_proc_info() callback (again, see unw_create_addr_space(3libunwind)). and again, unw_get_proc_info() may return an undefined value in this member.
• void *unwind_info — the pointer to the unwind info. if no unwind info is available, this member must be set to NULL. this member exists for the find_proc_info() callback to use (yes, unw_create_addr_space(3libunwind)). and yep, unw_get_proc_info() may return an undefined value in this member.

also, important vibe check: for libunwind's purposes, the code of a procedure is assumed to occupy a single, contiguous range of addresses. that's why it's always possible to describe the extent of a procedure with the start_ip and end_ip members. if one single function/routine gets split into multiple discontiguous pieces, libunwind just treats each piece as its own separate procedure. periodt. 💅

---

⭐ RETURN VALUE ⭐

on successful completion, unw_get_proc_info() returns 0. otherwise, the negative value of one of the error codes listed below comes back at you. 😭

---

🫶 THREAD AND SIGNAL SAFETY 🫶

unw_get_proc_info() is thread safe, slay. and if cursor cp is in the local address space, this routine is also safe to use from a signal handler. iconic behaviour honestly.

---

💀 ERRORS 💀

• UNW_EUNSPEC — an unspecified error occurred. (the classic "something happened, idk what" 😭)
• UNW_ENOINFO — libunwind was unable to locate unwind info for the procedure.
• UNW_EBADVERSION — the unwind info for the procedure has a version or format that libunwind does not understand.

on top of all that, unw_get_proc_info() may also return any error returned by the access_mem() callback (see unw_create_addr_space(3libunwind)).

---

🌈 SEE ALSO 🌈

libunwind(3libunwind), unw_create_addr_space(3libunwind), unw_get_proc_name(3libunwind)

---

👑 AUTHOR 👑

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

---

and that's the whole page bestie!! this Programming Library moment was brought to you by the 29 August 2023 era of the libunwind manual, and honestly she ate. go forth and unwind your stacks responsibly 💖✨🎀