.\" @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.
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