Infrastructure: Split the files into subdirectories.

[mLib] / sel / selbuf.3

diff --git a/sel/selbuf.3 b/sel/selbuf.3
new file mode 100644 (file)
index 0000000..cdf561b
--- /dev/null
+++ b/sel/selbuf.3
@@ -0,0 +1,106 @@
+.\" -*-nroff-*-
+.TH selbuf 3 "23 May 1999" "Straylight/Edgeware" "mLib utilities library"
+.SH NAME
+selbuf \- line-buffering input selector
+.\" @selbuf_enable
+.\" @selbuf_disable
+.\" @selbuf_setsize
+.\" @selbuf_init
+.\" @selbuf_destroy
+.SH SYNOPSIS
+.nf
+.B "#include <mLib/selbuf.h>"
+
+.BI "void selbuf_enable(selbuf *" b );
+.BI "void selbuf_disable(selbuf *" b );
+.BI "void selbuf_setsize(selbuf *" b ", size_t " sz );
+.BI "void selbuf_init(selbuf *" b ", sel_state *" s ", int " fd ,
+.BI "                 lbuf_func *" func ", void *" p );
+.BI "void selbuf_destroy(selbuf *" b );
+.fi
+.SH DESCRIPTION
+The
+.B selbuf
+subsystem is a selector which integrates with the
+.BR sel (3)
+system for I/O multiplexing.  It reads entire text lines from a file
+descriptor and passes them to a caller-defined function.  It uses the
+line buffer described in
+.BR lbuf (3)
+to do its work: you should read about it in order to understand exactly
+what gets considered to be a line of text and what doesn't, and the
+exact rules about what your line handling function should and shouldn't
+do.
+.PP
+The data for a line selector is stored in an object of type
+.BR selbuf .
+This object must be allocated by the caller, and initialized using the
+.B selbuf_init
+function.  This requires a fair few arguments:
+.TP
+.BI "selbuf *" b
+Pointer to the
+.B selbuf
+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 "lbuf_func *" func
+The
+.I "line handler"
+function.  It is passed a pointer to each line read from the file (or
+null to indicate end-of-file), the length of the line, and an arbitrary
+pointer (the
+.I p
+argument to
+.B selbuf_init
+described below).  For full details, see
+.BR lbuf (3).
+.TP
+.BI "void *" p
+A pointer argument passed to
+.I func
+for each line read from the file.  Apart from this, the pointer is not
+used at all.
+.PP
+The
+.B selbuf
+selector is immediately active.  Subsequent calls to
+.B sel_select
+on the same multiplexor will cause any complete lines read from the file
+to be passed to your handling function.  This function can at any time
+call
+.B selbuf_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 selbuf_enable
+is called.  Note that
+.B selbuf_enable
+may well immediately start emitting complete lines 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 line buffer has a finite amount of memory for reading strings.  The
+size of this buffer is set by calling
+.B selbuf_setsize
+with the requested size.  The default buffer size is 256 bytes.
+.PP
+When it's finished with, a line buffer selector must be destroyed by
+calling
+.BR selbuf_destroy .
+.SH "SEE ALSO"
+.BR lbuf (3),
+.BR sel (3),
+.BR mLib (3).
+.SH AUTHOR
+Mark Wooding, <mdw@distorted.org.uk>