TH VENTI-PACKET 2
SH NAME
Packet,
packetalloc,
packetappend,
packetasize,
packetcmp,
packetconcat,
packetconsume,
packetcopy,
packetdup,
packetforeign,
packetfragments,
packetfree,
packetheader,
packetpeek,
packetprefix,
packetsha1,
packetsize,
packetsplit,
packetstats,
packettrailer,
packettrim \- zero-copy network buffers
SH SYNOPSIS
ft L
#include <u.h>
br
#include <libc.h>
br
#include <venti.h>
ta +\w'\fLPacket* 'u +\w'\fLxxxx'u
PP
B
PP
B
Packet* packetalloc(void);
PP
B
void packetappend(Packet *p, uchar *buf, int n)
PP
B
uint packetasize(Packet *p)
PP
B
int packetcmp(Packet *p, Packet *q)
PP
B
void packetconcat(Packet *p, Packet *q)
PP
B
int packetconsume(Packet *p, uchar *buf, int n)
PP
B
int packetcopy(Packet *p, uchar *buf, int offset, int n)
PP
B
Packet* packetdup(Packet *p, int offset, int n)
PP
B
Packet* packetforeign(uchar *buf, int n,
br
B
void (*free)(void *a), void *a)
PP
B
int packetfragments(Packet *p, IOchunk *io, int nio,
br
B
int offset)
PP
B
void packetfree(Packet *p)
PP
B
uchar* packetheader(Packet *p, int n)
PP
B
uchar* packetpeek(Packet *p, uchar *buf, int offset, int n)
PP
B
void packetprefix(Packet *p, uchar *buf, int n)
PP
B
void packetsha1(Packet *p, uchar sha1[20])
PP
B
uint packetsize(Packet *p)
PP
B
Packet* packetsplit(Packet *p, int n)
PP
B
void packetstats(void)
PP
B
uchar* packettrailer(Packet *p, int n)
PP
B
int packettrim(Packet *p, int offset, int n)
SH DESCRIPTION
A
B Packet
is a chain of blocks of data.
Each block, called a fragment,
is contiguous in memory, but the entire packet
may not be.
This representation helps avoid unnecessary memory copies.
PP
I Packetalloc
allocates an empty packet.
PP
I Packetappend
appends the
I n
bytes at
I buf
to the end of
IR p .
PP
I Packetasize
returns the number of data bytes allocated to
IR p .
This may be larger than the number of bytes stored
in
IR p
because fragments may not be filled completely.
PP
I Packetcmp
compares the data sections of two packets as
I memcmp
(see
IR memory (2))
would.
PP
I Packetconcat
removes all data from
IR q ,
appending it to
IR p .
PP
I Packetconsume
removes
I n
bytes from the beginning of
IR p ,
storing them into
IR buf .
PP
I Packetcopy
copies
I n
bytes at
I offset
in
I p
to
IR buf .
PP
I Packetdup
creates a new packet initialized with
I n
bytes from
I offset
in
IR p .
PP
I Packetforeign
allocates a packet containing `foreign' data: the
I n
bytes pointed to by
IR buf .
Once the bytes are no longer needed, they are freed by calling
IB free ( a )\fR.
PP
I Packetfragments
initializes up to
I nio
of the
I io
structures with pointers to the data in
IR p ,
starting at
IR offset .
It returns the total number of bytes represented
by the returned structures.
I Packetfragments
initializes any unused
I io
structures with nil pointer and zero length.
PP
I Packetfree
frees the packet
IR p .
PP
I Packetheader
returns a pointer to the first
I n
bytes of
IR p ,
making them contiguous in memory
if necessary.
PP
I Packetpeek
returns a pointer to the
I n
bytes at
I offset
in
IR p .
If the requested bytes are already stored contiguously in memory,
the returned pointer points at the internal data storage for
IR p .
Otherwise, the bytes are copied into
IR buf ,
and
I packetpeek
returns
IR buf .
PP
I Packetprefix
inserts a copy of the
I n
bytes at
I buf
at the beginning of
IR p .
PP
I Packetsha1
computes the SHA1 hash of the data contained in
IR p .
PP
I Packetsize
returns the length, in bytes, of the data contained in
IR p .
PP
I Packetsplit
returns a new packet initialized with
I n
bytes removed from the beginning of
IR p .
PP
I Packetstats
prints run-time statistics to standard output.
PP
I Packettrailer
returns a pointer to the last
I n
bytes of
IR p ,
making them contiguous in memory
if necessary.
PP
I Packettrim
deletes all bytes from the packet
I p
except the
I n
bytes at offset
IR offset .
SH SOURCE
B /sys/src/libventi
SH SEE ALSO
IR venti (2)
SH DIAGNOSTICS
These functions return errors only when passed
invalid inputs,
IR e.g. ,
requests for data at negative offsets or beyond the end of a packet.
PP
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
I packetfragments
and
IR packetcmp ,
whose return values are described above.
PP
When these functions run out of memory, they
print error messages and call
IR sysfatal .
