chiark / gitweb /
Expunge revision histories in files.
[mLib] / lbuf.h
... / ...
CommitLineData
1/* -*-c-*-
2 *
3 * $Id: lbuf.h,v 1.8 2004/04/08 01:36:13 mdw Exp $
4 *
5 * Block-to-line buffering
6 *
7 * (c) 1999 Straylight/Edgeware
8 */
9
10/*----- Licensing notice --------------------------------------------------*
11 *
12 * This file is part of the mLib utilities library.
13 *
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.
18 *
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.
23 *
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,
27 * MA 02111-1307, USA.
28 */
29
30#ifndef MLIB_LBUF_H
31#define MLIB_LBUF_H
32
33#ifdef __cplusplus
34 extern "C" {
35#endif
36
37/*----- Line buffering ----------------------------------------------------*
38 *
39 * The line buffer accepts as input arbitrary-sized lumps of data and
40 * converts them, by passing them to a client-supplied function, into a
41 * sequence of lines. It's particularly useful when performing multiplexed
42 * network I/O. It's not normally acceptable to block while waiting for the
43 * rest of a text line to arrive, for example. The line buffer stores the
44 * start of the line until the rest of it arrives later.
45 *
46 * A line is a piece of text terminated by either a linefeed or a carriage-
47 * return/linefeed pair. (The former is there to cope with Unix; the latter
48 * copes with Internet-format line ends.)
49 *
50 * There's a limit to the size of lines that the buffer can cope with. It's
51 * not hard to remove this limit, but it's probably a bad idea in a lot of
52 * cases, because it'd allow a remote user to gobble arbitrary amounts of
53 * your memory. If a line exceeds the limit, it is truncated: the initial
54 * portion of the line is processed normally, and the remaining portion is
55 * simply discarded.
56 *
57 * Lines extracted from the input data are passed, one at a time, to a
58 * `handler function', along with a caller-supplied pointer argument to
59 * provide the handler with some context. The line read is null-terminated
60 * and does not include the trailing newline characters. It is legal for a
61 * handler function to modify the string it is passed. However, writing
62 * beyond the terminating null byte is not allowed. An end-of-file condition
63 * is signalled to the handler by passing it a null pointer rather than the
64 * address of a string.
65 *
66 * A complexity arises because of the concept of a `disabled' buffer.
67 * Disablement is really a higher-level concept, but it turns out to be
68 * important to implement it here. It's useful for a line handler function
69 * to `disable' itself, so that it doesn't get called any more. For example,
70 * this might happen if it encouters an error, or when it finishes reading
71 * everything it wanted to read. The line buffer needs to be `in the loop'
72 * so that it stops attempting to flush any further lines stored in its
73 * buffer towards a handler function which isn't ready to accept them.
74 * Buffers are initially enabled, although higher- level buffering systems
75 * might well disable them immediately for their own purposes.
76 */
77
78/*----- Header files ------------------------------------------------------*/
79
80#include <stddef.h>
81
82#ifndef MLIB_ARENA_H
83# include "arena.h"
84#endif
85
86/*----- Data structures ---------------------------------------------------*/
87
88/* --- The buffer structure --- *
89 *
90 * The only thing that's safe to fiddle with in here is the @lbuf_enable@
91 * flag. Only higher-level buffering systems should be playing with even
92 * that.
93 */
94
95struct lbuf;
96
97typedef void lbuf_func(char */*s*/, size_t /*len*/, void */*p*/);
98
99typedef struct lbuf {
100 lbuf_func *func; /* Handler function */
101 void *p; /* Argument for handler */
102 size_t len; /* Length of data in buffer */
103 size_t sz; /* Buffer size */
104 unsigned delim; /* Delimiter to look for */
105 unsigned f; /* Various useful state flags */
106 arena *a; /* Memory allocation arena */
107 char *buf; /* The actual buffer */
108} lbuf;
109
110#define LBUF_CR 1u /* Read a carriage return */
111#define LBUF_ENABLE 2u /* Buffer is currently enabled */
112#define LBUF_CLOSE 4u /* Buffer is now closed */
113
114enum {
115 LBUF_CRLF = 256,
116 LBUF_STRICTCRLF = 257
117};
118
119/*----- Functions provided ------------------------------------------------*/
120
121/* --- @lbuf_flush@ --- *
122 *
123 * Arguments: @lbuf *b@ = pointer to buffer block
124 * @char *p@ = pointer to where to start searching
125 * @size_t len@ = length of new material added
126 *
127 * Returns: ---
128 *
129 * Use: Flushes any complete lines in a line buffer. New material
130 * is assumed to have been added starting at @p@. If @p@ is
131 * null, then the scan starts at the beginning of the buffer,
132 * and the size of data already in the buffer is used in place
133 * of @len@.
134 *
135 * It is assumed that the buffer is initially enabled. You
136 * shouldn't be contributing data to a disabled buffer anyway.
137 * However, the buffer handler may at some point disable itself,
138 * and @lbuf_flush@ can cope with this eventuality. Any pending
139 * data is left at the start of the buffer and can be flushed
140 * out by calling @lbuf_flush(b, 0, 0)@ if the buffer is ever
141 * re-enabled.
142 */
143
144extern void lbuf_flush(lbuf */*b*/, char */*p*/, size_t /*len*/);
145
146/* --- @lbuf_close@ --- *
147 *
148 * Arguments: @lbuf *b@ = pointer to buffer block
149 *
150 * Returns: ---
151 *
152 * Use: Empties the buffer of any data currently lurking in it, and
153 * informs the client that this has happened. It's assumed that
154 * the buffer is enabled: you shouldn't be reading close events
155 * on disabled buffers.
156 */
157
158extern void lbuf_close(lbuf */*b*/);
159
160/* --- @lbuf_free@ --- *
161 *
162 * Arguments: @lbuf *b@ = pointer to buffer block
163 * @char **p@ = output pointer to free space
164 *
165 * Returns: Free buffer size.
166 *
167 * Use: Returns the free portion of a line buffer. Data can then be
168 * written to this portion, and split out into lines by calling
169 * @lbuf_flush@.
170 */
171
172extern size_t lbuf_free(lbuf */*b*/, char **/*p*/);
173
174/* --- @lbuf_snarf@ --- *
175 *
176 * Arguments: @lbuf *b@ = pointer to buffer block
177 * @const void *p@ = pointer to input data buffer
178 * @size_t sz@ = size of data in input buffer
179 *
180 * Returns: ---
181 *
182 * Use: Snarfs the data from the input buffer and spits it out as
183 * lines. This interface ignores the complexities of dealing
184 * with disablement: you should be using @lbuf_free@ to
185 * contribute data if you want to cope with that.
186 */
187
188extern void lbuf_snarf(lbuf */*b*/, const void */*p*/, size_t /*sz*/);
189
190/* --- @lbuf_setsize@ --- *
191 *
192 * Arguments: @lbuf *b@ = pointer to buffer block
193 * @size_t sz@ = requested maximum line size
194 *
195 * Returns: ---
196 *
197 * Use: Allocates a buffer of the requested size reading lines.
198 */
199
200extern void lbuf_setsize(lbuf */*b*/, size_t /*sz*/);
201
202/* --- @lbuf_init@ --- *
203 *
204 * Arguments: @lbuf *b@ = pointer to buffer block
205 * @lbuf_func *func@ = handler function
206 * @void *p@ = argument pointer for @func@
207 *
208 * Returns: ---
209 *
210 * Use: Initializes a line buffer block. Any recognized lines are
211 * passed to @func@ for processing.
212 */
213
214extern void lbuf_init(lbuf */*b*/, lbuf_func */*func*/, void */*p*/);
215
216/* --- @lbuf_destroy@ --- *
217 *
218 * Arguments: @lbuf *b@ = pointer to buffer block
219 *
220 * Returns: ---
221 *
222 * Use: Deallocates a line buffer and frees any resources it owned.
223 */
224
225extern void lbuf_destroy(lbuf */*b*/);
226
227/*----- That's all, folks -------------------------------------------------*/
228
229#ifdef __cplusplus
230 }
231#endif
232
233#endif