UNW_GE...E_BY_IP(3libunwind)

✨ NAME ✨

unw_get_proc_name_by_ip — bestie, this is literally the "get procedure name" function 💅

So real quick, we're in the libunwind manual here (that's the manual name, keeping it cute and accounted for 🫶), and this little icon is about turning a raw instruction pointer into a human-readable procedure name. No cursor required. Obsessed.

🌸 SYNOPSIS 🌸

#include <libunwind.h>

int unw_get_proc_name_by_ip(unw_addr_space_t as, unw_word_t ip, char
*bufp, size_t len, unw_word_t *offp, void *arg);

Look at that signature. A whole meal. 😌

🦋 DESCRIPTION 🦋

okay so unw_get_proc_name_by_ip() returns the name of a procedure, exactly like unw_get_proc_name() does — except (and this is the whole vibe) the name gets looked up by instruction pointer (IP) instead of by a cursor. Same energy, different entry point. Slay.

Here's what it expects from you, argument by argument, no gatekeeping:

• as — the address-space in which the instruction pointer should be looked up. If you're doing a look-up in the local address-space, you can just pass unw_local_addr_space here. Easy.
• ip — the instruction-pointer whose procedure name you want. This is the star of the show.
• bufp — a pointer to a character buffer that is at least len bytes long. This buffer is where the procedure name gets returned to you. 📥
• len — the length of that buffer, obviously. Be generous, bestie.
• offp — a pointer to a word that returns the byte offset of the instruction-pointer relative to the start of the procedure. Little coordinate, big meaning.
• arg — the address-space argument that should be used when accessing the address space. It has the exact same purpose as the argument of the same name for unw_init_remote(). And heads up: when you're accessing the local address space (that's when the first argument is unw_local_addr_space), you must pass NULL for this argument. Not optional. NULL it up.

⚠️ now for the caveat section, and it's a real one, so listen up bestie: on some platforms there is no reliable way to distinguish between procedure names and ordinary labels. And if symbol information has been stripped from a program, procedure names may be completely unavailable, or may be limited to those exported via a dynamic symbol table. In those cases, unw_get_proc_name_by_ip() may return the name of a label or a preceding (nearby) procedure. it's giving "close enough, we tried" 😭

BUT — and this is the part that saves us — 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 be equal to the instruction pointer ip. So even when the name is a little sus, the math still eats. 🔥

👑 RETURN VALUE 👑

On successful completion, unw_get_proc_name_by_ip() returns 0. Iconic. Perfect. No notes.

Otherwise, it returns the negative value of one of the error codes below. Yeah, negative — that's your sign something went sideways. 💀

🌈 THREAD AND SIGNAL SAFETY 🌈

unw_get_proc_name_by_ip() is thread safe. 🧵✨

And if the local address-space is passed in argument as, this routine is also safe to use from a signal handler. Which is lowkey amazing, ngl.

💖 ERRORS 💖

• UNW_EUNSPEC — an unspecified error occurred. The classic "something happened, don't ask" 🫠
• UNW_ENOINFO — libunwind was unable to determine the name of the procedure. It looked. It found nothing. Tragic.
• UNW_ENOMEM — the procedure name is too long to fit in the buffer provided. A truncated version of the name has been returned. So you got a name, just not the whole name. F in the chat for those lost characters ✂️

In addition, unw_get_proc_name_by_ip() may return any error returned by the access_mem() callback — see unw_create_addr_space(3libunwind) for the deets.

💜 SEE ALSO 💜

• libunwind(3libunwind)
• unw_create_addr_space(3libunwind)
• unw_get_proc_name(3libunwind)
• unw_init_remote(3libunwind)

go read them, bestie, iykyk 📚

🎀 AUTHOR 🎀

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

okay that's the whole page, no cap. this beauty lives in the Programming Library manual, dated 29 August 2023 — so like, go forth and look up those procedure names, you absolute main character 💅🦋⭐ periodt.