UNW_GET_PROC_NAME(3libunwind)

💖 UNW_GET_PROC_NAME 💖

okay bestie, welcome to libunwind's programming library corner of the world — this one's UNW_GET_PROC_NAME(3libunwind) and she's here to tell you whose function you're staring at. no cap. 🦋

---

✨ NAME ✨

unw_get_proc_name — get the name of the current procedure. that's it. that's the whole job. she's an icon, she's a legend, and she's the moment. 💅

---

🌸 SYNOPSIS 🌸

#include <libunwind.h>

int unw_get_proc_name(unw_cursor_t *cp, char *bufp, size_t len,
unw_word_t *offp);

---

🎀 DESCRIPTION 🎀

so, the tea: unw_get_proc_name() hands you back the name of the procedure that created the stack frame your cursor cp is pointing at. main character energy fr.

let's break down the little squad of arguments:

• cp — the cursor, aka the pointer to the stack frame we're investigating. this is the one you came here for.
• bufp — a pointer to a character buffer that's at least len bytes long. this is where the procedure name gets written. she's the delivery vessel. 🫶
• len — how big that buffer is, in bytes. don't be stingy.
• offp — a pointer to a word where we stash the byte offset of the instruction-pointer saved in the stack frame identified by cp, measured relative to the start of the procedure.

and here's the example that makes it click, lowkey iconic:

say procedure foo() starts at address 0x40003000. if you invoke unw_get_proc_name() on a stack frame whose instruction pointer value is 0x40003080, then the word pointed to by offp gets 0x80 — that's assuming the procedure is at least 0x80 bytes long. math is mathing. ✨

now for the caveats, because bestie we gotta be real:

on some platforms there is no reliable way to tell the difference between procedure names and ordinary labels. and if symbol information has been stripped from a program, procedure names may be completely unavailable, or limited to just the ones exported via a dynamic symbol table. in those cases unw_get_proc_name() may return the name of a label, or of a preceding (nearby) procedure. kinda giving "close enough" energy, ngl.

BUT — and this part is important, don't skip it — the offset returned through offp is always relative to the returned name. which means the value (address) of the returned name plus the returned offset will always equal the instruction pointer of the stack frame identified by cp. so the math stays valid even when the name is a little sus. periodt. 💀

---

🔥 RETURN VALUE 🔥

on successful completion, unw_get_proc_name() returns 0. slay.

otherwise, she returns the negative value of one of the error codes listed below. not a vibe, but forewarned is forearmed.

---

🧚 THREAD AND SIGNAL SAFETY 🧚

unw_get_proc_name() is thread safe. 👑

and if cursor cp is in the local address space, this routine is also safe to use from a signal handler. so yes, she can handle chaos.

---

⭐ ERRORS ⭐

• UNW_EUNSPEC — an unspecified error occurred. mysterious. cryptic. unhelpful but valid. 🙈
• UNW_ENOINFO — libunwind was unable to determine the name of the procedure. she tried, bestie, she really did. 😭
• UNW_ENOMEM — the procedure name is too long to fit in the buffer you provided. a truncated version of the name has been returned. (yes, she still gave you something. generous queen.) 🍓

in addition, unw_get_proc_name() may return any error returned by the access_mem() callback — see unw_create_addr_space(3libunwind) for that whole situation.

---

🌈 SEE ALSO 🌈

• libunwind(3libunwind)
• unw_get_proc_info(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 manual, dated 29 August 2023, and you just read UNW_GET_PROC_NAME(3libunwind) — go forth and get those procedure names, you absolute legend. 🦋💖✨