Subversion Repositories planix.SVN

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