LIBUNWI...OREDUMP(3libunwind)

💖 LIBUNWI...OREDUMP(3libunwind) 💖

okay bestie, welcome to the Programming Library page for libunwind-coredump — yes that's the manual section, and yes the title got squished, it's giving ✨abbreviated✨ but we move.

---

🌸 NAME 🌸

libunwind-coredump — coredump() support in libunwind

so basically: this is the part of libunwind that lets you look inside a coredump. no cap, it's a whole vibe.

---

✨ SYNOPSIS ✨

#include <libunwind-coredump.h>

unw_accessors_t _UCD_accessors;

struct UCD_info *_UCD_create(char const *);
void _UCD_destroy(struct UCD_info *);

int _UCD_get_num_threads(struct UCD_info *);
void _UCD_select_thread(struct UCD_info *, int);
void _UCD_get_pid(struct UCD_info *);
void _UCD_get_cursig(struct UCD_info *);

int _UCD_find_proc_info(unw_addr_space_t, unw_word_t, unw_proc_info_t *,
int, void *);
void _UCD_put_unwind_info(unw_addr_space_t, unw_proc_info_t *, void *);
int _UCD_get_dyn_info_list_addr(unw_addr_space_t, unw_word_t *, void *);
int _UCD_access_mem(unw_addr_space_t, unw_word_t, unw_word_t *, int,
void *);
int _UCD_access_reg(unw_addr_space_t, unw_regnum_t, unw_word_t *, int,
void *);
int _UCD_access_fpreg(unw_addr_space_t, unw_regnum_t, unw_fpreg_t *,
int, void *);
int _UCD_get_proc_name(unw_addr_space_t, unw_word_t, char *, size_t,
unw_word_t *, void *);
int _UCD_resume(unw_addr_space_t, unw_cursor_t *, void *);

like. look at all those little _UCD_ functions. they're a family. a squad. 🫶

---

💅 DESCRIPTION 💅

so picture this: you can take a snapshot of a process's state at one specific moment in time and save it into a specially-formatted file called a coredump. iconic behaviour, honestly. this usually happens all on its own when a process hits an unrecoverable error and the OS is like "not me catching your whole state at the moment of disaster" and captures it. 💀

libunwind ships a library you can use as part of a lightweight tool to generate some useful info about why the process abnormally terminated — like a stack trace of all threads of execution. main character diagnostics. ⭐

the routines and variables that implement this facility all use the prefix _UCD, which stands for unwind-via-coredump. iykyk.

---

🦋 getting started, bestie 🦋

an application that wants to use the coredump remote first needs to create a new libunwind address space that represents the target process. you do that by calling unw_create_addr_space().

in many cases, the application will simply want to pass the address of _UCD_accessors as the first argument to this routine. doing so will ensure that libunwind will be able to properly unwind the target process. slay.

however — and this is the tea — in special circumstances, an application may prefer to use only portions of the _UCD-facility. for this reason, the individual callback routines (_UCD_find_proc_info(), _UCD_put_unwind_info(), etc.) are also available for direct use.

of course, the addresses of these routines could also be picked up from _UCD_accessors, but doing so would prevent static initialization. also, when using _UCD_accessors, all the callback routines will be linked into the application, even if they are never actually called. lowkey wasteful but okay.

---

🎀 the actual flow 🎀

next, the application needs to load the corefile for analysis and create an (opaque) UCD_info structure by calling _UCD_create(), passing the name of the corefile. the returned opaque pointer then needs to be passed as the argument pointer (third argument) to unw_init_remote().

when the application is done using libunwind on the corefile, _UCD_destroy() needs to be called, passing it the pointer that was returned by the corresponding call to _UCD_create(). this ensures that all memory and other resources are freed up. no leaks, we're not that girl. 🙈

---

💜 the lil helper functions 💜

• _UCD_get_num_threads() — gets the number of threads in the corefile.
• _UCD_get_pid() — gets the process ID of the process associated with the corefile.
• _UCD_get_cursig() — gets the current signal begin received by the process associated with the corefile (if any).
• _UCD_select_thread() — selects the current thread for unwinding.

---

🌈 THREAD SAFETY 🌈

the coredump remote assumes that a single _UCD_info structure is never shared between threads. because of this, no explicit locking is used.

as long as only one thread uses a _UCD_info structure at any given time, this facility is thread-safe. one at a time, babes. one. at. a. time. ✋

---

💖 RETURN VALUE 💖

_UCD_create() may return a null pointer if it fails to create the UCD_info for any reason.

so like, check your return values, bestie. fr fr. 😭

---

🍓 FILES 🍓

• libunwind-coredump.h — header file to include when using the interface defined by this library.
• -lunwind-coredump -lunwind-generic — linker-switches to add when building a program that uses the functions defined by this library.

---

👑 SEE ALSO 👑

• libunwind(3libunwind)

---

and that's the whole page, periodt. 💅 this was Programming Library energy, dated 29 August 2023, and it lives at the top of the page as LIBUNWI...OREDUMP(3libunwind) — yeah the title's still squished, we don't talk about it. mwah, go unwind something. 🧚✨