vrb_new(3)

💫 vrb_new(3) 💫

okay so this is a page from the VRB Programmer's Manual — yes bestie, the Virtual Ring Buffer library, we're doing this 🫶

---

🌸 NAME 🌸

vrb_new — literally creates a brand new virtual ring buffer ✨

---

📚 LIBRARY 📚

-lvrb — that's the flag you link with, don't forget it 💅

---

✨ SYNOPSIS ✨

#include <vrb.h>

vrb_p vrb_new(size_t size, const char *name);

---

🦋 DESCRIPTION 🦋

vrb_new makes you a fresh new instance of a virtual ring buffer, no cap 🔥

So what even is a virtual ring buffer? It's a character FIFO queue — first in, first out, iconic behavior — but with one absolutely unhinged superpower: any sequence of characters in the buffer can be accessed as a single contiguous block of memory. Which means you never, ever have to split a sequence just because the buffer wrapped around. No splicing, no gymnastics, no "wait which half am I reading" moment. It just works. The way that a wraparound used to ruin your whole afternoon and now it simply doesn't 💀✨

---

🎀 ARGUMENTS 🎀

• size_t size — the requested minimum buffer size to be allocated. Heads up: the value you give gets rounded up to the nearest (or equal) whole multiple of the system page size. Also, the virtual ring buffer is implemented by mapping two adjacent blocks of memory to the same memory object — so it eats up twice as much virtual address space, and your specified size has to be less than half of the available virtual address space for this process. Math is real, bestie 😭
• const char *name — an optional temporary name pattern, or an actual name of a file, to be used as backing store via mmap(2) in a mounted filesystem where the process has write permission 🗂️ If the name string ends in "XXXXXX" then mkstemp(3) gets called to make the file unique. Otherwise it's used exactly as-is. If the named file already exists or otherwise can't be opened for write — error, sorry 🙈 And if you pass NULL, swap space is used as backing store via shmat(2). Easy.

---

🫶 RETURN VALUE 🫶

• vrb_p — on success you get a handle (a pointer, iykyk) to your freshly created virtual ring buffer 👑 On error, you get NULL. That's it, that's the deal.

---

💀 ERRORS 💀

If an error gets returned, then errno will be holding one of these:

• EINVAL — you requested a buffer size that's too large for address space allocation arithmetic. Big mood, but no.
• ENOMEM — out of memory while allocating the virtual ring buffer structure 😭
• - — an errno value set by a failing system call. Not us, it's the syscall's fault fr fr.

---

🌈 SEE ALSO 🌈

vrb(3), vrb_capacity(3), vrb_data_len(3), vrb_data_ptr(3), vrb_destroy(3), vrb_get(3), vrb_get_min(3), vrb_give(3), vrb_init(3), vrb_init_opt(3), vrb_is_empty(3), vrb_is_full(3), vrb_is_not_empty(3), vrb_is_not_full(3), vrb_move(3), vrb_new_opt(3), vrb_put(3), vrb_put_all(3), vrb_read(3), vrb_read_min(3), vrb_resize(3), vrb_space_len(3), vrb_space_ptr(3), vrb_take(3), vrb_uninit(3), vrb_write(3), vrb_write_min(3)

---

and that's the whole page, bestie! 💖 go forth and allocate responsibly ✨

signing off from the vrb corner of the manual, dated 2002-09-30, on page vrb_new(3) — mwah 🎀