libucontext(3)

🦋 libucontext(3) — Library Functions Manual 🦋

okay so bestie, this is libucontext(3) from the Library Functions Manual, and it is literally the userspace context-swapping cheat sheet. no cap, it's giving low-level but make it cute. 💅✨

---

🌸 NAME 🌸

libucontext — a library for userspace context swapping. that's the whole vibe. 🫶

✨ SYNOPSIS ✨

here's the include and the structs, bestie — copy these exactly, okay?

#include <libucontext/libucontext.h>

typedef struct {
  /* depends on target architecture */
} libucontext_mcontext_t;

typedef struct {
  void *ss_sp;
  int ss_flags;
  size_t ss_size;
} libucontext_stack_t;

typedef struct libucontext_ucontext {
  unsigned int uc_flags;
  struct libucontext_ucontext *uc_link;
  libucontext_stack_t uc_stack;
  libucontext_mcontext_t uc_mcontext;
} libucontext_ucontext_t;

and the functions go like this:

int libucontext_getcontext(libucontext_ucontext_t *ucp);

int libucontext_setcontext(const libucontext_ucontext_t *ucp);

void libucontext_makecontext(libucontext_ucontext_t *ucp, void
(*func)(), int argc, ...);

int libucontext_swapcontext(libucontext_ucontext_t *oucp, const
libucontext_ucontext_t *ucp);

💖 DESCRIPTION 💖

so what is this library actually doing? libucontext provides an implementation of the SysV ucontext functions. those are traditionally used to implement user-space context swapping. iconic behavior, honestly.

you make that happen by using libucontext_getcontext, libucontext_setcontext, libucontext_makecontext, and libucontext_swapcontext as appropriate. yes bestie, all four, and yes they slay.

• libucontext_getcontext — initializes a structure pointed to by ucp with the current user context. ✨
• libucontext_setcontext — sets the current user context to the structure pointed to by ucp. it discards the current user context, so yeah, that context is gone-gone. 💀
• libucontext_swapcontext — saves the current user context in a structure pointed to by oucp, then sets the current user context to the new context in a structure pointed to by ucp. very main character energy. 👑
• libucontext_makecontext — modifies a user context in a structure pointed to by ucp to run a function pointed to by func, and sets up an argument list of argc values. cute little function-launcher setup. 🎀

🚨 CAVEATS 🚨

okay, important stuff, bestie — read this part fr fr.

In SysV, the ucontext functions save and restore signal masks. The libucontext library, however, does not. In practice, this does not usually matter, as users of these functions rarely change the signal mask between contexts. 🫶

also:

Other implementations may or may not save and restore additional processor registers that this implementation does not. The libucontext library only saves and restores the general purpose registers. In practice, this has proven sufficient. 💅

so like, don't expect it to save every single little register, because it doesn't. it's still sufficient in practice, and that's the tea. 🍓

🌈 EXAMPLE 🌈

here's a practical example showing cooperative multithreading. it is intended for illustrative purpose only and has been written in a way favoring simplicity over performance and robustness:

#include <assert.h>
#include <stddef.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <time.h>
#include <libucontext/libucontext.h>

libucontext_ucontext_t mainctx = {};
libucontext_ucontext_t *curthr = &mainctx;
libucontext_ucontext_t *threads = NULL;
size_t thrcount = 0;

void
yieldto(libucontext_ucontext_t *target)
{
     libucontext_ucontext_t *oldthr = curthr;
     curthr = target;

     libucontext_swapcontext(oldthr, curthr);
}

void
yield(void)
{
     libucontext_ucontext_t *newthr;

     /* we set uc_flags to non-zero to signal thread completion. */
     do
          newthr = &threads[random() % thrcount];
     while (newthr == curthr || newthr->uc_flags);

     srandom(time(NULL));

     yieldto(newthr);
}

void
worker(size_t multiple)
{
     size_t accum = 1;

     for (size_t i = 0; i < 10; i++)
     {
          accum += (multiple * i);

          printf("[%p] accumulated %zun", curthr, accum);
          yield();
     }

     /* mark thread as completed, so we don't return here */
     curthr->uc_flags = 1;
}

void
create(size_t multiple)
{
     libucontext_ucontext_t *cursor;

     thrcount += 1;
     threads = realloc(threads, sizeof(*threads) * thrcount);

     cursor = &threads[thrcount - 1];
     memset(cursor, '0', sizeof *cursor);

     /* initialize the new thread's values to our current context */
     libucontext_getcontext(cursor);

     /* set up uc_link */
     cursor->uc_link = thrcount > 1 ? &threads[thrcount - 2] : &mainctx;

     /* set up a stack */
     cursor->uc_stack.ss_size = 8192;
     cursor->uc_stack.ss_sp = calloc(1, cursor->uc_stack.ss_size);

     /* set up the function call */
     libucontext_makecontext(cursor, worker, 1, multiple);
}

int
main(int argc, const char *argv[])
{
     srandom(time(NULL));

     libucontext_getcontext(&mainctx);

     for (size_t i = 1; i < 4; i++)
          create(i);

     /* start the threads off by yielding to the last one */
     yieldto(&threads[thrcount - 1]);

     return EXIT_SUCCESS;
}

💜 AUTHORS 💜

Ariadne Conill <ariadne@dereferenced.org> — iconic author behavior, we love to see it. 🫶✨

---

and that's the whole page, bestie! this was libucontext(3) from the Library Functions Manual, dated 2026-05-10. mwah, periodt. 💋🎀