STK(3)

🌸 NAME 🌸

Okay so this is STK(3), bestie: the data stack storage library page from the Library Functions Manual. It’s giving “efficient stack-oriented dynamic storage” and honestly? Pretty iconic. 💅

---

✨ SYNOPSIS ✨

#include <stk.h>

Stk_t *stkopen(int flags);
Stk_t *stkinstall(Stk_t *stack, char *(overflow)(int));
int stkclose(Stk_t *stack);
void stklink(Stk_t *stack)

char *stkalloc(Stk_t *stack, unsigned size);
char *stkcopy(Stk_t *stack, const char *string);
char *stkset(Stk_t *stack, char *address, unsigned offset);

char *stkseek(Stk_t *stack, unsigned offset);
int stktell(Stk_t *stack);
char *stkptr(Stk_t *stack, unsigned offset);
char *stkfreeze(Stk_t *stack, unsigned extra);
int stkon(Stk *stack, char* addr)

---

🦋 DESCRIPTION 🦋

So stk is a whole package of routines made for efficient stack-oriented dynamic storage. A stack abstraction is basically an ordered list of contiguous memory regions called stack frames, and those frames can hold objects of arbitrary size. No cap. ✨

A stack is represented by the type Stk_t, which is defined in the header <stk.h>. And plot twist: the type Stk_t is compatible with the type Sfio_t defined by the sfio(3) library. Compatible! We love a crossover episode. 🫶

At any instant there is one active stack, and it can be referenced by the constant stkstd. Variable-size objects can be added to the active stack, and programs can reference those objects directly with pointers. Also, the last object on the stack — here called the current object — can be built incrementally. The current object has an associated offset that determines its current size. While the current object is being built incrementally, its location might change, so it is necessary to reference the object with relative offsets ranging from zero to the current offset of the object. Lowkey important. Don’t forget it. 😭

There is a preset initial active stack. To use an additional stack, you need to create it and install it as the active stack. A stack is created with the stkopen() function. A flags argument of STK_SMALL indicates that unused space on the stack should be freed whenever this stack ceases to be the active stack. If successful, stkopen() returns a pointer to a stack whose reference count is 1. Otherwise, stkopen() returns a null pointer. Periodt.

• stklink() — increases the reference count for the given stack.
• stkinstall() — makes the specified stack the active stack and returns a pointer to the previous active stack. When the overflow argument is not null, it specifies a function that will be called whenever malloc(3) fails while trying to grow the stack. The overflow function will be called with the size that was passed to malloc(3). The overflow function can call exit(3), call longjmp(3) or return. If the overflow function returns, it must return a pointer to a memory region of the given size. The default action is to write an error to standard error and to call exit(2) with a non-zero exit value. When stack is a null pointer, the active stack is not changed, but the overflow function for the active stack can be changed and a pointer to the active stack is returned.
• stkclose() — decrements the reference count and frees the memory associated with the specified stack when the reference count is zero. The effect of subsequent references to objects on the stack are undefined. ⚠️ Like, actually undefined. Be careful.
• stkalloc() — returns an aligned pointer to space on the active stack that can be used to hold any object of the given size. stkalloc() is similar to malloc(3) except that individual items returned by stkalloc() can not be freed. stkalloc() causes the offset of the current object to be set to zero.
• stkcopy() — copies the given string onto the stack and returns a pointer to the string on the stack. stkcopy() causes the offset of the current object to be set to zero.
• stkset() — finds the frame containing the given address, frees all frames that were created after the one containing the given address, and sets the current object to the given address. The top of the current object is set to offset bytes from the current object. If address is not the address of an object on the stack, the result is undefined. 🙈
• stkseek() — used to set the offset for the current object. The offset argument to stkseek() specifies the new offset for the current object. The frame will be extended or moved if offset causes the new current offset to extend beyond the current frame. stkseek() returns a pointer to the beginning of the current object.
• stktell() — gives the offset of the current object.
• stkptr() — converts the given offset for the current object into a memory address on the stack. This address is only valid until another stack operation is given. The result is not defined if offset exceeds the size of the current object.
• stkfreeze() — terminates the current object on the stack and returns a pointer to the beginning of this object. If extra is non-zero, extra bytes are added to the stack before the current object is terminated. The first added byte will contain zero and the contents of the remaining bytes are undefined.
• stkon() — returns non-zero if the address given by addr is on the stack stack and 0 otherwise.

The sfio(3) output functions can be used to build the current object incrementally. An object that is built incrementally on the stack will always occupy contiguous memory within a stack frame, but until stkfreeze() is called, the location in memory for the object can change. There is a current offset associated with the current object that determines where subsequent operations apply. Initially, this offset is zero, and the offset changes as a result of the operations you specify. That’s the whole vibe: build it, track the offset, freeze it when you’re done. 🧚

---

🌈 HISTORY 🌈

The stk interface was derived from similar routines in the KornShell code that is used for building parse trees and carrying out expansions. It provides an efficient mechanism for grouping dynamically allocated objects so that they can be freed all at once rather than individually. Honestly? A slay concept. 👑

---

💖 AUTHOR 💖

David Korn

---

🎀 SEE ALSO 🎀

exit(2) longjmp(3) malloc(3) sfio(3)

---

Bye bestie 🫶 — signing off from the Library Functions Manual’s STK(3) page, with no footer date shown to report, and no fake date sneaking in. 💜