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

[mLib] / sel / selpk.3

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