STACK(9)

✨ NAME ✨</p>

stack — the kernel thread stack tracing routines, bestie 💖

It's a Kernel Developer's Manual situation, so like… kernel devs only, iykyk 🧚

---

🌸 SYNOPSIS 🌸

#include <sys/param.h>
#include <sys/stack.h>

In the kernel configuration file:

options DDB
options STACK

struct stack *
stack_create(int flags);

void
stack_destroy(struct stack *st);

int
stack_put(struct stack *st, vm_offset_t pc);

void
stack_copy(const struct stack *src, struct stack dst);

void
stack_zero(struct stack *st);

void
stack_print(const struct stack *st);

void
stack_print_ddb(const struct stack *st);

void
stack_print_short(const struct stack *st);

void
stack_print_short_ddb(const struct stack *st);

void
stack_sbuf_print(struct sbuf sb*, const struct stack *st);

void
stack_sbuf_print_ddb(struct sbuf sb*, const struct stack *st);

void
stack_save(struct stack *st);

void
stack_save_td(struct stack *st, struct thread *td);

int
stack_save_td_running(struct stack *st, struct thread *td);

---

🦋 DESCRIPTION 🦋

okay so the stack KPI is the whole moment for querying kernel stack trace info and auto-generating kernel stack trace strings, all for debugging and tracing purposes. lowkey iconic. but bestie, listen — to even use this KPI, you gotta have at least one of options DDB or options STACK compiled into the kernel. no exceptions, no cap. 💅

Every single stack trace is described by a struct stack. And before a trace can be created or, like, manipulated in any way?? you have to allocate storage for it with stack_create(). The flags argument gets passed straight to malloc(9) — it's giving "just forwarding your vibes along". 🫶 Memory tied to a trace gets freed by calling stack_destroy().

Wanna capture the call stack of the current kernel thread? that's stack_save(), slay. And stack_save_td() plus stack_save_td_running() can also capture the stack of a thread you specify as the caller. ⚠️ but real talk: callers of these functions MUST own the thread lock of the specified thread. no sneaking around the lock, bestie, that's not the vibe.

stack_save_td() can capture the stack of a kernel thread that is not running or swapped out at the time of the call. and stack_save_td_running() can capture the stack of a running kernel thread. two different energies, both valid. ✨

stack_print() and stack_print_short() are your girls for printing a stack trace using the kernel printf(9) — but heads up, they may sleep as a result of acquiring sx(9) locks in the kernel linker while they're looking up symbol names. 😴 In locking-sensitive environments, the unsynchronized stack_print_ddb() and stack_print_short_ddb() variants may be invoked instead. This function bypasses kernel linker locking, which makes it usable in ddb(4)… but NOT in a live system where linker data structures may change. ma'am. please. 🙈

stack_sbuf_print() is for constructing a human-readable string, including conversion (where possible) from a simple kernel instruction pointer to a named symbol and offset. 🎀 The sb argument must be an initialized struct sbuf as described in sbuf(9). This function may sleep if an auto-extending struct sbuf is used, or because of kernel linker locking. In locking-sensitive environments — like ddb(4) — the unsynchronized stack_sbuf_print_ddb() variant may be invoked to dodge kernel linker locking; it should be used with a fixed-length sbuf. noted. 💅

And then the utility functions stack_zero, stack_copy, and stack_put may be used to manipulate stack data structures directly. little hands-on queens. 👑

---

⭐ RETURN VALUES ⭐

stack_put() returns 0 on success. slay! Otherwise the struct stack does not contain space to record additional frames, and a non-zero value is returned. 💀

stack_save_td_running() returns 0 when the stack capture was successful and a non-zero error number otherwise. In particular:

• EAGAIN is returned if the thread was running in user mode at the time that the capture was attempted 😭
• EOPNOTSUPP is returned if the operation is not implemented 🙈

---

🎀 SEE ALSO 🎀

• ddb(4)
• printf(9)
• sbuf(9)
• sx(9)

---

👑 AUTHORS 👑

The stack function suite was created by Antoine Brodin. 💖 And stack was extended by Robert Watson for general-purpose use outside of ddb(4). absolute main character energy from both of them, fr fr. 🫶✨

---

and that's the whole page bestie!! 💅 this lil writeup is from the Debian crew, dated October 6, 2017 — yes, she's an elder but she still ate, and the manual section is still STACK(9). periodt. 🎀💜