*/*.3: Align arguments properly to the right of the opening `('.

[mLib] / sel / selbuf.3

.\" -*-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 );
.ds mT \fBvoid selbuf_init(
.BI "\*(mTselbuf *" b ", sel_state *" s ", int " fd ,
.BI "\h'\w'\*(mT'u'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>