NEEDSTACK(3)

💖 NEEDSTACK(3) 💖

okay so this is NEEDSTACK(3) from the Library Functions Manual, and it's literally the stack-overflow vibe check bestie 💅. No cap, it's short but important.

🌸 NAME 🌸

needstack — check for execution stack overflow 🫶

✨ SYNOPSIS ✨

#include <u.h>

#include <libc.h>

int  needstack(int n)

💜 DESCRIPTION 💜

Stack overflow in the thread library leads to bugs that are difficult to diagnose 😭. The Plan 9 libraries are careful about not allocating large structures on the stack, so typically four or eight kilobytes is plenty of stack for a thread. Other libraries are not always as careful 🙈.

Calling needstack indicates to the thread library that an external routine is about to be called that will require n bytes of stack space. If there is not enough space left on the stack, the thread library prints an error and terminates the program 💀. The call needstack(0) can be used to check whether the stack is currently overflowed.

Needstack is defined in libc.h so that library functions used in threaded and non-threaded contexts can call it. The implementation of needstack in lib9 is a no-op.

Think of needstack as a comment checked at run time, like assert(3) 💖. That's the energy: a little runtime note that says “bestie, check the stack.”

🎀 EXAMPLE 🎀

The X Window library implementation of XLookupString allocates some very large buffers on the stack, so /src/cmd/devdraw/x11-itrans.c calls needstack(64*1024) before making calls to XLookupString. If a thread (in this case, the keyboard-reading thread used inside the draw(3) library) does not allocate a large enough stack, the problem is diagnosed immediately rather than left to corrupt memory 🔥.

🦋 SOURCE 🦋

• /src/lib9/needstack.c
• /src/libthread

🌈 SEE ALSO 🌈

• thread(3)

and that's the whole page bestie — footer says NEEDSTACK(3), periodt 💅✨