UNW_INIT_REMOTE(3libunwind)

💫 UNW_INIT_REMOTE 💫

okay bestie, welcome to UNW_INIT_REMOTE from the Programming Library (that's 3libunwind for the catalogue girlies) — the function that gets your unwind cursor set up for remote unwinding. yes queen, remote. we're reaching out 💅

---

✨ NAME ✨

unw_init_remote — initialize cursor for remote unwinding 🦋

---

🌸 SYNOPSIS 🌸

#include <libunwind.h>

int unw_init_remote(unw_cursor_t *c, unw_addr_space_t as, void *arg);

---

💖 DESCRIPTION 💖

so the unw_init_remote() routine initializes the unwind cursor that c points to, for unwinding inside the address space identified by as. and as? she can either be unw_local_addr_space (the local address space, hi bestie 🫶) or literally any arbitrary address space you made with unw_create_addr_space().

now the arg opaque pointer — this is the part where you tell the address space exactly which entity should be unwound. like, if you passed unw_local_addr_space as as, then arg needs to be a pointer to a context structure holding the machine-state of the initial stack frame. but other address spaces might instead expect a process ID, a thread ID, or a pointer to some arbitrary structure that identifies the stack frame chain to be unwound. in other words: the interpretation of arg is entirely dependent on the address space in use — libunwind never interprets the argument in any way on its own. she minds her own business, periodt.

not me pointing out that unw_init_remote() can be used to initiate unwinding in any process, including the local process in which the unwinder itself is running 👀

but for local unwinding, it's generally preferable to use unw_init_local() instead — because it's easier to use and because it may perform better. lowkey just take the easier route, bestie.

---

⭐ RETURN VALUE ⭐

on successful completion, unw_init_remote() returns 0. otherwise the negative value of one of the error-codes below is returned. slay when it works, 😭 when it doesn't.

---

🧚 THREAD AND SIGNAL SAFETY 🧚

unw_init_remote() is thread safe. and if the local address space is passed in argument as as, this routine is also safe to use from a signal handler. iconic behaviour honestly 💜

---

💀 ERRORS 💀

• UNW_EINVAL — unw_init_remote() was called in a version of libunwind which supports local unwinding only (this normally happens when defining UNW_LOCAL_ONLY before including <libunwind.h> and then calling unw_init_remote()). yeah... that combo is not the vibe 🙈
• UNW_EUNSPEC — an unspecified error occurred. mysterious. no explanation. we move.
• UNW_EBADREG — a register needed by unw_init_remote() wasn't accessible. she needed that register and it ghosted her 💔

---

🔥 SEE ALSO 🔥

• libunwind(3libunwind)
• unw_create_addr_space(3libunwind)
• unw_init_local(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 edition, dated 29 August 2023, filed under UNW_INIT_REMOTE(3libunwind) — go forth and unwind remotely, you absolute main character 🌈✨🎀