281 lines
4.5 KiB
Text
281 lines
4.5 KiB
Text
.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 .
|