.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
.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