UNW_GET...N_RANGE(3libunwind)

💖 UNW_GET...N_RANGE — bestie edition 💖

okay so this is a page from libunwind, section 3libunwind — the programming library zone. Grab a strawberry 🍓 and let's get into it.

✨ NAME ✨

unw_get_proc_info_in_range — bestie, it gets you procedure info inside an IP range plus a frame index table. That's the whole vibe.

🌸 SYNOPSIS 🌸

#include <libunwind.h>

int unw_get_proc_info_in_range(unw_word_t start_ip, unw_word_t end_ip,
unw_word_t eh_frame_table, unw_word_t eh_frame_table_len, unw_word_t
exidx_frame_table, unw_word_t exidx_frame_table_len,, unw_addr_space_t
*as, void *arg);

ngl, yes, there really are two commas in a row up there in the original signature (exidx_frame_table_len,,). Not a typo I made. I'm just the messenger 💅 copy it as-is, bestie.

🦋 DESCRIPTION 🦋

So unw_get_proc_info_in_range() hands you back the same kind of auxiliary info about a procedure that unw_get_proc_info_by_ip() does. Same flavor, same energy. 🫶

The difference? It looks the info up in an instruction pointer (IP) range and a frame table, instead of just at a single IP. That's it, that's the twist.

And the way this is equally flexible is that you can look up the info for any arbitrary procedure — even one that is not part of the current call chain. Iconic, honestly. Main character energy for a lookup function.

But ✋ and this is the part where I hold your hand — because it's more flexible, it also tends to run slower than unw_get_proc_info(). And not like a lil slower. often much slower. 😭 So like… know what you're signing up for.

💅 RETURN VALUE 💅

• On a successful completion, unw_get_proc_info_in_range() returns 0. Slay.
• Otherwise it returns the negative value of one of the error codes listed below. Not slay, but informative.

🧚 THREAD AND SIGNAL SAFETY 🧚

unw_get_proc_info_in_range() is thread safe. Periodt. 💖

And bonus: if the local address space is passed in the argument as, then this routine is also safe to use from a signal handler. Little treat for you. 🎀

👑 ERRORS 👑

• UNW_EUNSPEC — an unspecified error occurred. Vague, mysterious, unhelpful. 💀
• UNW_ENOINFO — libunwind was unable to locate unwind-info for the procedure. It went looking, it found nothing. 🕵️
• UNW_EBADVERSION — the unwind-info for the procedure has a version or format that is not understood by libunwind. It's giving "I don't speak that language." 😭
• UNW_EINVAL — an unsupported table encoding was specified. Bestie. Check your encoding.

Plus: unw_get_proc_info_by_ip() may return any error returned by the access_mem() callback — go see unw_create_addr_space(3libunwind) for that whole situation.

🌈 SEE ALSO 🌈

• libunwind(3libunwind)
• unw_get_proc_info_in_range(3libunwind)
• unw_create_addr_space(3libunwind)
• unw_get_proc_name(3libunwind)
• unw_get_proc_info(3libunwind)

⭐ AUTHOR ⭐

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

okay that's the whole page, you ate it, go forth and unwind (or like, don't, but with correct error handling) 💜

This gem came out of the Programming Library manual set, dated 29 August 2023, filed under UNW_GET...N_RANGE(3libunwind). Bye bestie! 🦋✨