.\" -*-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 "void lbuf_close(lbuf *" b );
.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_destroy(lbuf *" b );
.fi
.SH "DESCRIPTION"
The declarations in
.B lbuf_init
initializes a line buffer ready for use. It is given three arguments:
.TP
-.I b
-A pointer to the block of memory to use for the line buffer. This is
-all the memory the line buffer requires.
+.BI "lbuf *" b
+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
-.I func
+.BI "void (*" func ")(char *" s ", void *" p )
The
.I line-handler
function to which the line buffer should pass completed lines of text.
.TP
-.I p
+.BI "void *" p
A pointer argument to be passed to the function when a completed line of
text arrives.
.PP
-Since the line buffer requires no memory except for the actual
-.B lbuf
-object, and doesn't hook itself onto anything else, it can just be
-thrown away when you don't want it any more. No explicit finalization
-is required.
+The amount of memory set aside for reading lines is configurable. It
+may be set by calling
+.B lbuf_setsize
+at any time when the buffer is empty. The default limit is 256 bytes.
+Lines longer than the limit are truncated. By default, the buffer is
+allocated from the current arena,
+.BR arena_global (3);
+this may be changed by altering the buffer's
+.B a
+member to refer to a different arena at any time when the buffer is
+unallocated.
+.PP
+A line buffer must be destroyed after use by calling
+.BR lbuf_destroy ,
+passing it the address of the buffer block.
.SS "Inserting data into the buffer"
There are two interfaces for inserting data into the buffer. One's much
simpler than the other, although it's less expressive.
.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
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
+.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
is called to examine the new data and break it into text lines. This is
given three arguments:
.TP
-.I b
+.BI "lbuf *" b
The address of the line buffer.
.TP
-.I p
+.BI "char *" p
The address at which the new data has been written. This must be the
base address returned from
.BR lbuf_free .
.TP
-.I len
+.BI "size_t " len
The number of bytes which have been written to the buffer.
.PP
The
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
of the line which has just been read, 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
~mdw / mLib / blobdiff