chiark
/
gitweb
/
~mdw
/
mLib
/ blobdiff
commit
grep
author
committer
pickaxe
?
search:
re
summary
|
shortlog
|
log
|
commit
|
commitdiff
|
tree
raw
|
inline
| side by side
Version bump.
[mLib]
/
man
/
pkbuf.3
diff --git
a/man/pkbuf.3
b/man/pkbuf.3
index 2bf9d170e8ac94e6fc269253ddb0384036db26fc..4922b00dd518077756a72e1f726171719c335afc 100644
(file)
--- a/
man/pkbuf.3
+++ b/
man/pkbuf.3
@@
-1,5
+1,5
@@
.\" -*-nroff-*-
.\" -*-nroff-*-
-.TH pkbuf 3 "16 July 2000"
mLib
+.TH pkbuf 3 "16 July 2000"
"Straylight/Edgeware" "mLib utilities library"
.SH "NAME"
pkbuf \- split packets out of asynchronously received blocks
.\" @pkbuf_flush
.SH "NAME"
pkbuf \- split packets out of asynchronously received blocks
.\" @pkbuf_flush
@@
-18,10
+18,7
@@
pkbuf \- split packets out of asynchronously received blocks
.BI "size_t pkbuf_free(pkbuf *" pk ", octet **" p );
.BI "void pkbuf_snarf(pkbuf *" pk ", const void *" p ", size_t " sz );
.BI "void pkbuf_want(pkbuf *" pk ", size_t " want );
.BI "size_t pkbuf_free(pkbuf *" pk ", octet **" p );
.BI "void pkbuf_snarf(pkbuf *" pk ", const void *" p ", size_t " sz );
.BI "void pkbuf_want(pkbuf *" pk ", size_t " want );
-.BI "void pkbuf_init(pkbuf *" pk ,
-.BI " void (*" func ")(octet *" b ", size_t " sz ", pkbuf *" pk ,
-.BI " size_t *" keep ", void *" p ),
-.BI " void *" pk );
+.BI "void pkbuf_init(pkbuf *" pk ", pkbuf_func *" func ", void *" p );
.BI "void pkbuf_destroy(pkbuf *" pk );
.fi
.SH "DESCRIPTION"
.BI "void pkbuf_destroy(pkbuf *" pk );
.fi
.SH "DESCRIPTION"
@@
-49,14
+46,13
@@
A pointer to the block of memory to use for the packet buffer. The packet
buffer will allocate memory to store incoming data automatically: this
structure just contains bookkeeping information.
.TP
buffer will allocate memory to store incoming data automatically: this
structure just contains bookkeeping information.
.TP
-.nf
-.BI "void (*" func ")(octet *" b ", size_t " sz ", pkbuf *" p ,
-.BI " size_t *" keep ", void *" p )
-.fi
+.BI "pkbuf_func *" func
The
.I packet-handler
function to which the packet buffer should pass packets of data when
The
.I packet-handler
function to which the packet buffer should pass packets of data when
-they're received.
+they're received. See
+.B "Packet breaking and the handler function"
+below.
.TP
.BI "void *" p
A pointer argument to be passed to the function when a packet arrives.
.TP
.BI "void *" p
A pointer argument to be passed to the function when a packet arrives.
@@
-82,7
+78,7
@@
This function is given three arguments: a pointer
.I pk
to a packet buffer structure; a pointer
.I p
.I pk
to a packet buffer structure; a pointer
.I p
-
to a chunk of data to read; and the size
+to a chunk of data to read; and the size
.I sz
of the chunk of data. The data is pushed through the packet buffer and
any complete packets are passed on to the packet handler.
.I sz
of the chunk of data. The data is pushed through the packet buffer and
any complete packets are passed on to the packet handler.
@@
-132,9
+128,9
@@
each one in turn to the packet-handler function.
The
.B pkbuf_snarf
function is trivially implemented in terms of the more complex
The
.B pkbuf_snarf
function is trivially implemented in terms of the more complex
-.B pkbuf_free / pkbuf_flush
+.B
R
pkbuf_free / pkbuf_flush
interface.
interface.
-.SS "Packet breaking and the handler fu
cn
tion"
+.SS "Packet breaking and the handler fu
nc
tion"
The function
.B pkbuf_want
is used to inform the packet buffer of the expected length of the next
The function
.B pkbuf_want
is used to inform the packet buffer of the expected length of the next
@@
-144,8
+140,15
@@
to the packet buffer and a size
.I sz
of the packet.
.PP
.I sz
of the packet.
.PP
-When enough data has arrived, the packet-handler function is called, and
-passed:
+When enough data has arrived, the packet-handler function is called.
+This has the signature
+.IP
+.nf
+.BI "void (*" func ")(octet *" b ", size_t " sz ", pkbuf *" p ,
+.BI " size_t *" keep ", void *" p );
+.fi
+.PP
+It is passed:
.TP
.BI "octet *" b
A pointer to the packet data in the buffer, or zero to signify
.TP
.BI "octet *" b
A pointer to the packet data in the buffer, or zero to signify
@@
-188,7
+191,7
@@
the object so that it doesn't see any more data.
.PP
Clearly, since an
.B pkbuf_flush
.PP
Clearly, since an
.B pkbuf_flush
-call can emit more than one packet,
so
it must be aware that the packet
+call can emit more than one packet, it must be aware that the packet
handler isn't interested in any more packet. However, this fact must
also be signalled to the higher-level object so that it can detach
itself from its data source.
handler isn't interested in any more packet. However, this fact must
also be signalled to the higher-level object so that it can detach
itself from its data source.