.\" -*-nroff-*-
-.TH selbuf 3 "23 May 1999" mLib
+.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_init(selbuf *" b ,
-.BI " sel_state *" s ,
-.BI " int " fd ,
-.BI " void (*" func ")(char *" s ", void *" p ),
-.BI " void *" p );
+.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
exact rules about what your line handling function should and shouldn't
do.
.PP
-All the data for a
-.B selbuf
-selector is stored in an object of type
+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
-.I b
+.BI "selbuf *" b
Pointer to the
.B selbuf
object to initialize.
.TP
-.I s
+.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
-.I fd
+.BI "int " fd
The file descriptor of the stream the selector should read from.
.TP
-.I func
+.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) and an arbitrary pointer (the
+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).
+described below). For full details, see
+.BR lbuf (3).
.TP
-.I p
+.BI "void *" p
A pointer argument passed to
.I func
for each line read from the file. Apart from this, the pointer is not
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@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>