VENTI-PACKET(3)

🎀 VENTI-PACKET(3) 🎀

hiii bestie 💖 welcome to VENTI-PACKET(3), the manual page for the zero-copy network buffer girlies. this is the one where packets are made of fragments and we are all very normal about avoiding unnecessary memory copies. 🦋

✨ NAME ✨

the whole squad on this page is Packet, packetalloc, packetappend, packetasize, packetcmp, packetconcat, packetconsume, packetcopy, packetdup, packetforeign, packetfragments, packetfree, packetheader, packetpeek, packetprefix, packetsha1, packetsize, packetsplit, packetstats, packettrailer, and packettrim — they are the zero-copy network buffers, periodt. 👑

🌸 SYNOPSIS 🌸

okay so here is the exact C lineup, no cap:

#include <u.h>
#include <libc.h>
#include <venti.h>

Packet* packetalloc(void);

void    packetappend(Packet *p, uchar *buf, int n)

uint    packetasize(Packet *p)

int     packetcmp(Packet *p, Packet *q)

void    packetconcat(Packet *p, Packet *q)

int     packetconsume(Packet *p, uchar *buf, int n)

int     packetcopy(Packet *p, uchar *buf, int offset, int n)

Packet* packetdup(Packet *p, int offset, int n)

Packet* packetforeign(uchar *buf, int n,
            void (*free)(void *a), void *a)

int     packetfragments(Packet *p, IOchunk *io, int nio,
            int offset)

void    packetfree(Packet *p)

uchar*  packetheader(Packet *p, int n)

uchar*  packetpeek(Packet *p, uchar *buf, int offset, int n)

void    packetprefix(Packet *p, uchar *buf, int n)

void    packetsha1(Packet *p, uchar sha1[20])

uint    packetsize(Packet *p)

Packet* packetsplit(Packet *p, int n)

void    packetstats(void)

uchar*  packettrailer(Packet *p, int n)

int     packettrim(Packet *p, int offset, int n)

🫶 DESCRIPTION 🫶

okay so a Packet is a chain of blocks of data. each block is called a fragment, and a fragment is contiguous in memory, but the entire packet may not be. this representation helps avoid unnecessary memory copies — that is literally the whole vibe. 💅

• packetalloc — allocates an empty packet. fresh out the box, no notes. ✨
• packetappend — appends the n bytes at buf to the end of p.
• packetasize — returns the number of data bytes allocated to p. this may be larger than the number of bytes stored in p, because fragments may not be filled completely. she can have extra room, bestie.
• packetcmp — compares the data sections of two packets as memcmp (see memory(3)) would.
• packetconcat — removes all data from q, appending it to p. it is giving “your stuff is my stuff now.” 🫶
• packetconsume — removes n bytes from the beginning of p, storing them into buf.
• packetcopy — copies n bytes at offset in p to buf.
• packetdup — creates a new packet initialized with n bytes from offset in p.
• packetforeign — allocates a packet containing foreign data: the n bytes pointed to by buf. once the bytes are no longer needed, they are freed by calling free(a).
• packetfragments — initializes up to nio of the io structures with pointers to the data in p, starting at offset. it returns the total number of bytes represented by the returned structures. it initializes any unused io structures with nil pointer and zero length.
• packetfree — frees the packet p.
• packetheader — returns a pointer to the first n bytes of p, making them contiguous in memory if necessary.
• packetpeek — returns a pointer to the n bytes at offset in p. if the requested bytes are already stored contiguously in memory, the returned pointer points at the internal data storage for p. otherwise, the bytes are copied into buf, and packetpeek returns buf.
• packetprefix — inserts a copy of the n bytes at buf at the beginning of p.
• packetsha1 — computes the SHA1 hash of the data contained in p.
• packetsize — returns the length, in bytes, of the data contained in p.
• packetsplit — returns a new packet initialized with n bytes removed from the beginning of p.
• packetstats — prints run-time statistics to standard output.
• packettrailer — returns a pointer to the last n bytes of p, making them contiguous in memory if necessary.
• packettrim — deletes all bytes from the packet p except the n bytes at offset offset.

📦 SOURCE 📦

/src/libventi — that is where this lives, bestie. 🏠

👀 SEE ALSO 👀

venti(3) — go read that too, iykyk. 👑

💀 DIAGNOSTICS 💀

these functions return errors only when passed invalid inputs, e.g., requests for data at negative offsets or beyond the end of a packet. so like, do not be weird with the offsets, bestie. 😭

functions returning pointers return nil on error; functions returning integers return -1 on error. most functions returning integers return 0 on success. the exceptions are packetfragments and packetcmp, whose return values are described above.

when these functions run out of memory, they print error messages and call sysfatal. that is the dramatic part. 💀

💌 later, bestie — this was VENTI-PACKET(3), sourced from /src/libventi; the footer did not list a separate version or date, it just repeated the page tag. mwah 💋