X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/mLib/blobdiff_plain/fbf20b5bd30e237c383ed290428261f28dfa5803..d4efbcd93c940ad522fcf8c601ec1829d2e0b10d:/man/lbuf.3

diff --git a/man/lbuf.3 b/man/lbuf.3
index 87f41a3..6595f30 100644
--- 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
@@ -95,11 +96,11 @@ The complex interface is the pair of functions
 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
@@ -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
@@ -188,18 +207,18 @@ the object so that it doesn't see any more data.
 .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 .
@@ -218,4 +237,4 @@ general
 .BR selbuf (3),
 .BR mLib (3).
 .SH "AUTHOR"
-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>