plan9fox/sys/man/2/venti-packet

.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 .