.\" -*-nroff-*-
-.TH lbuf 3 "6 July 1999" mLib
+.TH lbuf 3 "6 July 1999" "Straylight/Edgeware" "mLib utilities library"
.SH "NAME"
lbuf \- split lines out of asynchronously received blocks
.\" @lbuf_flush
.BI "size_t lbuf_free(lbuf *" b ", char **" p );
.BI "void lbuf_snarf(lbuf *" b ", const void *" p ", size_t " sz );
.BI "void lbuf_setsize(lbuf *" b ", size_t " sz );
-.BI "void lbuf_init(lbuf *" b ,
-.BI " void (*" func ")(char *" s ", void *" p ),
-.BI " void *" p );
+.BI "void lbuf_init(lbuf *" b ", lbuf_func *" func ", void *" p );
.BI "void lbuf_destroy(lbuf *" b );
.fi
.SH "DESCRIPTION"
buffer will allocate memory to store incoming data automatically: this
structure just contains bookkeeping information.
.TP
-.BI "void (*" func ")(char *" s ", void *" p )
+.BI "lbuf_func *" func
The
.I line-handler
function to which the line buffer should pass completed lines of text.
+See
+.B "Line-handler functions"
+below for a description of this function.
.TP
.BI "void *" p
A pointer argument to be passed to the function when a completed line of
and
.BR lbuf_flush .
.PP
-The
+The
.B lbuf_free
function returns the address and size of a free portion of the line
buffer's memory into which data may be written. The function is passed
-the address
+the address
.I b
of the line buffer. Its result is the size of the free area, and it
writes the base address of this free space to the location pointed to by
.BR lbuf_free / lbuf_flush
interface.
.SS "Line breaking"
-The line buffer considers a line to end with either a simple linefeed
-character (the normal Unix convention) or a carriage-return/linefeed
-pair (the Internet convention).
+By default, the line buffer considers a line to end with either a simple
+linefeed character (the normal Unix convention) or a
+carriage-return/linefeed pair (the Internet convention). This can be
+changed by modifying the
+.B delim
+member of the
+.B lbuf
+structure: the default value is
+.BR LBUF_CRLF .
+If set to
+.BR LBUF_STRICTCRLF ,
+only a carriage-return/linefeed pair will terminate a line. Any other
+value is a single character which is considered to be the line terminator.
.PP
The line buffer has a fixed amount of memory available to it. This is
deliberate, to prevent a trivial attack whereby a remote user sends a
line completely.
.SS "Line-handler functions"
Completed lines, as already said, are passed to the caller's
-line-handler function. The function is given two arguments:
-the address
+line-handler function. This function has the signature
+.IP
+.B "void"
+.IB func "(char *" s ", size_t " len ", void *" p );
+.PP
+It is given three arguments: the address
.I s
-of the line which has just been read, and the pointer
+of the line which has just been read; the length
+.I len
+of the line (not including the null terminator), and the pointer
.I p
which was set up in the call to
.BR lbuf_init .
.PP
The line pointer argument
.I s
-may be null to signify end-of-file. See the next section.
+may be null to signify end-of-file; in this case, the length
+.I len
+will be zero. See the next section.
.SS "Flushing the remaining data"
When the client program knows that there's no more data arriving (for
example, an end-of-file condition exists on its data source) it should
.PP
Clearly, since an
.B lbuf_flush
-call can emit more than one line, so it must be aware that the line
-handler isn't interested in any more lines. However, this fact must
-also be signalled to the higher-level object so that it can detach
-itself from its data source.
+call can emit more than one line, it must be aware that the line handler
+isn't interested in any more lines. However, this fact must also be
+signalled to the higher-level object so that it can detach itself from
+its data source.
.PP
Rather than invent some complex interface for this, the line buffer
-exports one of its structure members,
-.BR flags .
+exports one of its structure members, a flags word called
+.BR f .
A higher-level object wishing to disable the line buffer simply clears
the bit
.B LBUF_ENABLE
-in the flags word.
+in this flags word.
.PP
Disabling a buffer causes an immediate return from
.BR lbuf_flush .
.BR selbuf (3),
.BR mLib (3).
.SH "AUTHOR"
-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>