X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/mLib/blobdiff_plain/dd3c57bc8cac59e0d657ee665ce462988d27d714..18c831dcd0ae4d660c70ccac69d27ed2a97851be:/sel/selpk.3

diff --git a/sel/selpk.3 b/sel/selpk.3
new file mode 100644
index 0000000..f0a56ee
--- /dev/null
+++ b/sel/selpk.3
@@ -0,0 +1,106 @@
+.\" -*-nroff-*-
+.TH selpk 3 "23 May 1999" "Straylight/Edgeware" "mLib utilities library"
+.SH NAME
+selpk \- packet-buffering input selector
+.\" @selpk_enable
+.\" @selpk_disable
+.\" @selpk_want
+.\" @selpk_init
+.\" @selpk_destroy
+.SH SYNOPSIS
+.nf
+.B "#include <mLib/selpk.h>"
+
+.BI "void selpk_enable(selpk *" pk );
+.BI "void selpk_disable(selpk *" pk );
+.BI "void selpk_want(selpk *" pk ", size_t " sz );
+.BI "void selpk_init(selpk *" pk ", sel_state *" s ", int " fd ,
+.BI "                pkbuf_func *" func ", void *" p );
+.BI "void selpk_destroy(selpk *" b );
+.fi
+.SH DESCRIPTION
+The
+.B selpk
+subsystem is a selector which integrates with the
+.BR sel (3)
+system for I/O multiplexing.  It reads packets from a file descriptor
+and passes them to a caller-defined function.  It uses the packet buffer
+described in
+.BR pkbuf (3)
+to do its work: you should read about it in order to understand exactly
+how the packet buffer decides how much data is in each packet and the
+exact rules about what your packet handling function should and
+shouldn't do.
+.PP
+The data for a packet selector is stored in an object of type
+.BR selpk .
+This object must be allocated by the caller, and initialized using the
+.B selpk_init
+function.  This requires a fair few arguments:
+.TP
+.BI "selpk *" pk
+Pointer to the
+.B selpk
+object to initialize.
+.TP
+.BI "sel_state *" s
+Pointer to a multiplexor object (type
+.BR sel_state )
+to which this selector should be attached.  See
+.BR sel (3)
+for more details about multiplexors, and how this whole system works.
+.TP
+.BI "int " fd
+The file descriptor of the stream the selector should read from.
+.TP
+.BI "pkbuf_func *" func
+The
+.I "packet handler"
+function.  It is given a pointer to each packet read from the file (or
+null to indicate end-of-file) and an arbitrary pointer (the
+.I p
+argument to
+.B selpk_init
+described below).  See
+.BR pkbuf (3)
+for full details.
+.TP
+.BI "void *" p
+A pointer argument passed to
+.I func
+for each packet read from the file.  Apart from this, the pointer is not
+used at all.
+.PP
+The
+.B selpk
+selector is immediately active.  Subsequent calls to
+.B sel_select
+on the same multiplexor will cause any packets read from the file to be
+passed to your handling function.  This function can at any time call
+.B selpk_disable
+to stop itself from being called any more.  The selector is then
+disengaged from the I/O multiplexor and won't do anything until
+.B selpk_enable
+is called.  Note that
+.B selpk_enable
+may well immediately start emitting complete packets of text which were
+queued up from the last I/O operation: it doesn't necessarily wait for
+the next
+.B sel_select
+call.
+.PP
+The size of packets read by the buffer is set by calling
+.BR selpk_want .
+See
+.BR pkbuf (3)
+for more details about how packet buffering works.
+.PP
+When it's finished with, a packet selector must be destroyed by calling
+.BR selpk_destroy .
+.SH "SEE ALSO"
+.BR pkbuf (3),
+.BR sel (3),
+.BR selbuf (3),
+.BR mLib (3).
+.SH AUTHOR
+Mark Wooding, <mdw@distorted.org.uk>