chiark / gitweb /
Commit as 2.1.0.
[mLib] / lbuf.3
05fbeb03 1.\" -*-nroff-*-
fbf20b5b 2.TH lbuf 3 "6 July 1999" "Straylight/Edgeware" "mLib utilities library"
05fbeb03 3.SH "NAME"
4lbuf \- split lines out of asynchronously received blocks
5.\" @lbuf_flush
6.\" @lbuf_close
7.\" @lbuf_free
8.\" @lbuf_snarf
31e83d07 9.\" @lbuf_setsize
05fbeb03 10.\" @lbuf_init
31e83d07 11.\" @lbuf_destroy
05fbeb03 12.SH "SYNOPSIS"
14.B "#include <mLib/lbuf.h>"
16.BI "void lbuf_flush(lbuf *" b ", char *" p ", size_t " len );
17.BI "void lbuf_close(lbuf *" b );
18.BI "size_t lbuf_free(lbuf *" b ", char **" p );
19.BI "void lbuf_snarf(lbuf *" b ", const void *" p ", size_t " sz );
cededfbe 20.BI "void lbuf_setsize(lbuf *" b ", size_t " sz );
83c63e03 21.BI "void lbuf_init(lbuf *" b ", lbuf_func *" func ", void *" p );
cededfbe 22.BI "void lbuf_destroy(lbuf *" b );
25The declarations in
26.B <mLib/lbuf.h>
27implement a handy object called a
28.IR "line buffer" .
29Given unpredictably-sized chunks of data, the line buffer extracts
30completed lines of text and passes them to a caller-supplied function.
31This is useful in nonblocking network servers, for example: the server
32can feed input from a client into a line buffer as it arrives and deal
33with completed text lines as they appear without having to wait for
34newline characters.
36The state of a line buffer is stored in an object of type
37.BR lbuf .
38This is a structure which must be allocated by the caller. The
39structure should normally be considered opaque (see the section on
40.B Disablement
41for an exception to this).
42.SS "Initialization and finalization"
43The function
44.B lbuf_init
45initializes a line buffer ready for use. It is given three arguments:
ff76c38f 47.BI "lbuf *" b
31e83d07 48A pointer to the block of memory to use for the line buffer. The line
49buffer will allocate memory to store incoming data automatically: this
50structure just contains bookkeeping information.
05fbeb03 51.TP
83c63e03 52.BI "lbuf_func *" func
05fbeb03 53The
54.I line-handler
55function to which the line buffer should pass completed lines of text.
83c63e03 56See
57.B "Line-handler functions"
58below for a description of this function.
05fbeb03 59.TP
ff76c38f 60.BI "void *" p
05fbeb03 61A pointer argument to be passed to the function when a completed line of
62text arrives.
cededfbe 64The amount of memory set aside for reading lines is configurable. It
65may be set by calling
66.B lbuf_setsize
67at any time when the buffer is empty. The default limit is 256 bytes.
68Lines longer than the limit are truncated. By default, the buffer is
69allocated from the current arena,
70.BR arena_global (3);
71this may be changed by altering the buffer's
72.B a
73member to refer to a different arena at any time when the buffer is
76A line buffer must be destroyed after use by calling
77.BR lbuf_destroy ,
78passing it the address of the buffer block.
05fbeb03 79.SS "Inserting data into the buffer"
80There are two interfaces for inserting data into the buffer. One's much
81simpler than the other, although it's less expressive.
83The simple interface is
84.BR lbuf_snarf .
85This function is given three arguments: a pointer
86.I b
87to a line buffer structure; a pointer
88.I p
d0053e2e 89to a chunk of data to read; and the size
05fbeb03 90.I sz
91of the chunk of data. The data is pushed through the line buffer and
92any complete lines are passed on to the line handler.
94The complex interface is the pair of functions
d0053e2e 95.B lbuf_free
05fbeb03 96and
d0053e2e 97.BR lbuf_flush .
05fbeb03 98.PP
d4efbcd9 99The
05fbeb03 100.B lbuf_free
101function returns the address and size of a free portion of the line
102buffer's memory into which data may be written. The function is passed
d4efbcd9 103the address
31e83d07 104.I b
05fbeb03 105of the line buffer. Its result is the size of the free area, and it
106writes the base address of this free space to the location pointed to by
107the argument
108.IR p .
109The caller's data must be written to ascending memory locations starting
111.BI * p
112and no data may be written beyond the end of the free space. However,
113it isn't necessary to completely fill the buffer.
115Once the free area has had some data written to it,
116.B lbuf_flush
117is called to examine the new data and break it into text lines. This is
118given three arguments:
ff76c38f 120.BI "lbuf *" b
05fbeb03 121The address of the line buffer.
ff76c38f 123.BI "char *" p
05fbeb03 124The address at which the new data has been written. This must be the
125base address returned from
126.BR lbuf_free .
ff76c38f 128.BI "size_t " len
05fbeb03 129The number of bytes which have been written to the buffer.
132.B lbuf_flush
133function breaks the new data into lines as described below, and passes
134each one in turn to the line-handler function.
137.B lbuf_snarf
138function is trivially implemented in terms of the more complex
d0053e2e 139.BR lbuf_free / lbuf_flush
05fbeb03 140interface.
141.SS "Line breaking"
83c63e03 142By default, the line buffer considers a line to end with either a simple
143linefeed character (the normal Unix convention) or a
144carriage-return/linefeed pair (the Internet convention). This can be
145changed by modifying the
146.B delim
147member of the
148.B lbuf
149structure: the default value is
151If set to
153only a carriage-return/linefeed pair will terminate a line. Any other
154value is a single character which is considered to be the line terminator.
05fbeb03 155.PP
156The line buffer has a fixed amount of memory available to it. This is
157deliberate, to prevent a trivial attack whereby a remote user sends a
158stream of data containing no newline markers, wasting the server's
159memory. Instead, the buffer will truncate overly long lines (silently)
160and return only the initial portion. It will ignore the rest of the
161line completely.
162.SS "Line-handler functions"
163Completed lines, as already said, are passed to the caller's
83c63e03 164line-handler function. This function has the signature
166.B "void"
167.IB func "(char *" s ", size_t " len ", void *" p );
169It is given three arguments: the address
05fbeb03 170.I s
83c63e03 171of the line which has just been read; the length
172.I len
173of the line (not including the null terminator), and the pointer
05fbeb03 174.I p
175which was set up in the call to
d0053e2e 176.BR lbuf_init .
05fbeb03 177The line passed is null-terminated, and has had its trailing newline
178stripped. The area of memory in which the string is located may be
179overwritten by the line-handler function, although writing beyond the
180terminating zero byte is not permitted.
182The line pointer argument
183.I s
83c63e03 184may be null to signify end-of-file; in this case, the length
185.I len
186will be zero. See the next section.
05fbeb03 187.SS "Flushing the remaining data"
188When the client program knows that there's no more data arriving (for
189example, an end-of-file condition exists on its data source) it should
190call the function
191.BR lbuf_close
192to flush out the remaining data in the buffer as one last (improperly
193terminated) line. This will pass the remaining text to the line
194handler, if there is any, and then call the handler one final time with
195a null pointer rather than the address of a text line to inform it of
196the end-of-file.
197.SS "Disablement"
198The line buffer is intended to be used in higher-level program objects,
199such as the buffer selector described in
200.BR selbuf (3).
201Unfortunately, a concept from this high level needs to exist at the line
202buffer level, which complicates the description somewhat. The idea is
203that, when a line-handler attached to some higher-level object decides
204that it's read enough, it can
205.I disable
206the object so that it doesn't see any more data.
208Clearly, since an
209.B lbuf_flush
528c8b4d 210call can emit more than one line, it must be aware that the line handler
211isn't interested in any more lines. However, this fact must also be
212signalled to the higher-level object so that it can detach itself from
213its data source.
05fbeb03 214.PP
215Rather than invent some complex interface for this, the line buffer
3bc42912 216exports one of its structure members, a flags word called
217.BR f .
05fbeb03 218A higher-level object wishing to disable the line buffer simply clears
219the bit
3bc42912 221in this flags word.
05fbeb03 222.PP
223Disabling a buffer causes an immediate return from
224.BR lbuf_flush .
225However, it is not permitted for the functions
226.B lbuf_flush
228.B lbuf_close
229to be called on a disabled buffer. (This condition isn't checked for;
230it'll just do the wrong thing.) Furthermore, the
231.B lbuf_snarf
232function does not handle disablement at all, because it would complicate
233the interface so much that it wouldn't have any advantage over the more
235.BR lbuf_free / lbuf_flush .
237.BR selbuf (3),
238.BR mLib (3).
9b5ac6ff 240Mark Wooding, <>