Pass line length to line handler function. Provide a @typedef@ for

[mLib] / man / lbuf.3

diff --git a/man/lbuf.3 b/man/lbuf.3
index 87f41a359a92a0fe4e13c22d974b22a28683f6db..b887130acddf927acd6a2eb4f4b6573e457bda0b 100644 (file)
--- a/man/lbuf.3
+++ b/man/lbuf.3
@@ -18,9 +18,7 @@ lbuf \- split lines out of asynchronously received blocks
 .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"
@@ -51,10 +49,13 @@ A pointer to the block of memory to use for the line buffer.  The line
 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
@@ -138,9 +139,19 @@ function is trivially implemented in terms of the more complex
 .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
@@ -150,10 +161,16 @@ and return only the initial portion.  It will ignore the rest of the
 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 .
@@ -164,7 +181,9 @@ terminating zero byte is not permitted.
 .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