10564b1175
groff 1.23.0 added .MR to its -man macro package. The NEWS file states
that the inclusion of the macro "was prompted by its introduction to
Plan 9 from User Space's troff in August 2020." From d32deab it seems
that the name for Plan 9 from User Space's implementation was suggested
by groff maintainer G. Brandon Robinson.
Not sure if the intention was to make these definitions compatible, but
it would be nice if they were.
Currently, Plan 9 from User Space's .MR expects its second argument to
be parenthesized. groff's .MR does not. This results in extra
parentheses appearing in manual references when viewing Plan 9 from User
Space's manual pages on a system using groff.
282 lines
4.5 KiB
Groff
282 lines
4.5 KiB
Groff
.TH VENTI-PACKET 3
|
|
.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
|
|
.MR memory 3 )
|
|
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 \*9/src/libventi
|
|
.SH SEE ALSO
|
|
.MR venti 3
|
|
.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 .
|