.\" -*-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
.\" @lbuf_close
.\" @lbuf_free
.\" @lbuf_snarf
+.\" @lbuf_setsize
.\" @lbuf_init
+.\" @lbuf_destroy
.SH "SYNOPSIS"
.nf
.B "#include <mLib/lbuf.h>"
.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"
initializes a line buffer ready for use. It is given three arguments:
.TP
.BI "lbuf *" b
-A pointer to the block of memory to use for the line buffer. This is
-all the memory the line buffer requires.
+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
.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
+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
-.I l
+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
the argument
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,
-.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>
~mdw / mLib / blobdiff