Makefile: Use check_PROGRAMS target.

[mLib] / man / pkbuf.3

diff --git a/man/pkbuf.3 b/man/pkbuf.3
index 9d26463fdd67e4cdd3c2c9ea5a2dd04fc440d5e9..80eed4b549ae39d8026c23cf6ffc07469aa3ac51 100644 (file)
--- a/man/pkbuf.3
+++ b/man/pkbuf.3
@@ -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 "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"
@@ -31,7 +28,7 @@ implement a
 .IR "packet buffer" .
 Given unpredictably-sized chunks of data, the packet buffer extracts
 completed packets of data, with sizes ascertained by a handler
-function. 
+function.
 .PP
 The state of a packet buffer is stored in an object of type
 .BR pkbuf .
@@ -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
-.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
-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.
@@ -82,7 +78,7 @@ This function is given three arguments: a pointer
 .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.
@@ -92,11 +88,11 @@ The complex interface is the pair of functions
 and
 .IR pkbuf_flush .
 .PP
-The 
+The
 .B pkbuf_free
 function returns the address and size of a free portion of the packet
 buffer's memory into which data may be written.  The function is passed
-the address 
+the address
 .I pk
 of the packet buffer.  Its result is the size of the free area, and it
 writes the base address of this free space to the location pointed to by
@@ -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
-.B pkbuf_free / pkbuf_flush
+.BR pkbuf_free / pkbuf_flush
 interface.
-.SS "Packet breaking and the handler fucntion"
+.SS "Packet breaking and the handler function"
 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
-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
@@ -188,18 +191,18 @@ the object so that it doesn't see any more data.
 .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.
 .PP
 Rather than invent some complex interface for this, the packet buffer
-exports one of its structure members,
-.BR flags .
+exports one of its structure members, a flags words called
+.BR f .
 A higher-level object wishing to disable the packet buffer simply clears
 the bit
 .B PKBUF_ENABLE
-in the flags word.
+in this flags word.
 .PP
 Disabling a buffer causes an immediate return from
 .BR pkbuf_flush .
@@ -219,4 +222,4 @@ general
 .BR selpk (3),
 .BR mLib (3).
 .SH "AUTHOR"
-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>