.\" -*-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
.I b
to a line buffer structure; a pointer
.I p
- to a chunk of data to read; and the size
+to a chunk of data to read; and the size
.I sz
of the chunk of data. The data is pushed through the line buffer and
any complete lines are passed on to the line handler.
.PP
The complex interface is the pair of functions
-.I lbuf_free
+.B lbuf_free
and
-.IR lbuf_flush .
+.BR lbuf_flush .
.PP
The
.B lbuf_free
The
.B lbuf_snarf
function is trivially implemented in terms of the more complex
-.B lbuf_free / lbuf_flush
+.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
-.B lbuf_init .
+.BR lbuf_init .
The line passed is null-terminated, and has had its trailing newline
stripped. The area of memory in which the string is located may be
overwritten by the line-handler function, although writing beyond the
.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,