3 * $Id: lbuf.h,v 1.7 2002/01/13 13:32:52 mdw Exp $
5 * Block-to-line buffering
7 * (c) 1999 Straylight/Edgeware
10 /*----- Licensing notice --------------------------------------------------*
12 * This file is part of the mLib utilities library.
14 * mLib is free software; you can redistribute it and/or modify
15 * it under the terms of the GNU Library General Public License as
16 * published by the Free Software Foundation; either version 2 of the
17 * License, or (at your option) any later version.
19 * mLib is distributed in the hope that it will be useful,
20 * but WITHOUT ANY WARRANTY; without even the implied warranty of
21 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
22 * GNU Library General Public License for more details.
24 * You should have received a copy of the GNU Library General Public
25 * License along with mLib; if not, write to the Free
26 * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
30 /*----- Revision history --------------------------------------------------*
33 * Revision 1.7 2002/01/13 13:32:52 mdw
34 * Pass line length to line handler function. Provide a @typedef@ for
35 * handler functions. Allow run-time configuration of line delimiters.
37 * Revision 1.6 2001/02/03 16:23:33 mdw
38 * Bug fix: handle a disable during a close-induced flush without dumping
41 * Revision 1.5 2001/01/20 12:06:01 mdw
42 * Define flags with macros, to ensure unsignedness.
44 * Revision 1.4 2000/06/17 10:38:14 mdw
45 * Add support for variable buffer sizes.
47 * Revision 1.3 1999/12/10 23:42:04 mdw
48 * Change header file guard names.
50 * Revision 1.2 1999/05/17 20:36:08 mdw
51 * Make the magical constants for the buffer flags uppercase.
53 * Revision 1.1 1999/05/14 21:01:14 mdw
54 * Integrated `select' handling bits from the background resolver project.
65 /*----- Line buffering ----------------------------------------------------*
67 * The line buffer accepts as input arbitrary-sized lumps of data and
68 * converts them, by passing them to a client-supplied function, into a
69 * sequence of lines. It's particularly useful when performing multiplexed
70 * network I/O. It's not normally acceptable to block while waiting for the
71 * rest of a text line to arrive, for example. The line buffer stores the
72 * start of the line until the rest of it arrives later.
74 * A line is a piece of text terminated by either a linefeed or a carriage-
75 * return/linefeed pair. (The former is there to cope with Unix; the latter
76 * copes with Internet-format line ends.)
78 * There's a limit to the size of lines that the buffer can cope with. It's
79 * not hard to remove this limit, but it's probably a bad idea in a lot of
80 * cases, because it'd allow a remote user to gobble arbitrary amounts of
81 * your memory. If a line exceeds the limit, it is truncated: the initial
82 * portion of the line is processed normally, and the remaining portion is
85 * Lines extracted from the input data are passed, one at a time, to a
86 * `handler function', along with a caller-supplied pointer argument to
87 * provide the handler with some context. The line read is null-terminated
88 * and does not include the trailing newline characters. It is legal for a
89 * handler function to modify the string it is passed. However, writing
90 * beyond the terminating null byte is not allowed. An end-of-file condition
91 * is signalled to the handler by passing it a null pointer rather than the
92 * address of a string.
94 * A complexity arises because of the concept of a `disabled' buffer.
95 * Disablement is really a higher-level concept, but it turns out to be
96 * important to implement it here. It's useful for a line handler function
97 * to `disable' itself, so that it doesn't get called any more. For example,
98 * this might happen if it encouters an error, or when it finishes reading
99 * everything it wanted to read. The line buffer needs to be `in the loop'
100 * so that it stops attempting to flush any further lines stored in its
101 * buffer towards a handler function which isn't ready to accept them.
102 * Buffers are initially enabled, although higher- level buffering systems
103 * might well disable them immediately for their own purposes.
106 /*----- Header files ------------------------------------------------------*/
114 /*----- Data structures ---------------------------------------------------*/
116 /* --- The buffer structure --- *
118 * The only thing that's safe to fiddle with in here is the @lbuf_enable@
119 * flag. Only higher-level buffering systems should be playing with even
125 typedef void lbuf_func(char */
*s*/
, size_t /*len*/, void */
*p*/
);
127 typedef struct lbuf
{
128 lbuf_func
*func
; /* Handler function */
129 void *p
; /* Argument for handler */
130 size_t len
; /* Length of data in buffer */
131 size_t sz
; /* Buffer size */
132 unsigned delim
; /* Delimiter to look for */
133 unsigned f
; /* Various useful state flags */
134 arena
*a
; /* Memory allocation arena */
135 char *buf
; /* The actual buffer */
138 #define LBUF_CR 1u /* Read a carriage return */
139 #define LBUF_ENABLE 2u /* Buffer is currently enabled */
140 #define LBUF_CLOSE 4u /* Buffer is now closed */
144 LBUF_STRICTCRLF
= 257
147 /*----- Functions provided ------------------------------------------------*/
149 /* --- @lbuf_flush@ --- *
151 * Arguments: @lbuf *b@ = pointer to buffer block
152 * @char *p@ = pointer to where to start searching
153 * @size_t len@ = length of new material added
157 * Use: Flushes any complete lines in a line buffer. New material
158 * is assumed to have been added starting at @p@. If @p@ is
159 * null, then the scan starts at the beginning of the buffer,
160 * and the size of data already in the buffer is used in place
163 * It is assumed that the buffer is initially enabled. You
164 * shouldn't be contributing data to a disabled buffer anyway.
165 * However, the buffer handler may at some point disable itself,
166 * and @lbuf_flush@ can cope with this eventuality. Any pending
167 * data is left at the start of the buffer and can be flushed
168 * out by calling @lbuf_flush(b, 0, 0)@ if the buffer is ever
172 extern void lbuf_flush(lbuf */
*b*/
, char */
*p*/
, size_t /*len*/);
174 /* --- @lbuf_close@ --- *
176 * Arguments: @lbuf *b@ = pointer to buffer block
180 * Use: Empties the buffer of any data currently lurking in it, and
181 * informs the client that this has happened. It's assumed that
182 * the buffer is enabled: you shouldn't be reading close events
183 * on disabled buffers.
186 extern void lbuf_close(lbuf */
*b*/
);
188 /* --- @lbuf_free@ --- *
190 * Arguments: @lbuf *b@ = pointer to buffer block
191 * @char **p@ = output pointer to free space
193 * Returns: Free buffer size.
195 * Use: Returns the free portion of a line buffer. Data can then be
196 * written to this portion, and split out into lines by calling
200 extern size_t lbuf_free(lbuf */
*b*/
, char **/
*p*/
);
202 /* --- @lbuf_snarf@ --- *
204 * Arguments: @lbuf *b@ = pointer to buffer block
205 * @const void *p@ = pointer to input data buffer
206 * @size_t sz@ = size of data in input buffer
210 * Use: Snarfs the data from the input buffer and spits it out as
211 * lines. This interface ignores the complexities of dealing
212 * with disablement: you should be using @lbuf_free@ to
213 * contribute data if you want to cope with that.
216 extern void lbuf_snarf(lbuf */
*b*/
, const void */
*p*/
, size_t /*sz*/);
218 /* --- @lbuf_setsize@ --- *
220 * Arguments: @lbuf *b@ = pointer to buffer block
221 * @size_t sz@ = requested maximum line size
225 * Use: Allocates a buffer of the requested size reading lines.
228 extern void lbuf_setsize(lbuf */
*b*/
, size_t /*sz*/);
230 /* --- @lbuf_init@ --- *
232 * Arguments: @lbuf *b@ = pointer to buffer block
233 * @lbuf_func *func@ = handler function
234 * @void *p@ = argument pointer for @func@
238 * Use: Initializes a line buffer block. Any recognized lines are
239 * passed to @func@ for processing.
242 extern void lbuf_init(lbuf */
*b*/
, lbuf_func */
*func*/
, void */
*p*/
);
244 /* --- @lbuf_destroy@ --- *
246 * Arguments: @lbuf *b@ = pointer to buffer block
250 * Use: Deallocates a line buffer and frees any resources it owned.
253 extern void lbuf_destroy(lbuf */
*b*/
);
255 /*----- That's all, folks -------------------------------------------------*/