chiark / gitweb /
Commit as 2.1.0.
[mLib] / lbuf.h
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
95 struct lbuf;
96
97 typedef void lbuf_func(char */*s*/, size_t /*len*/, void */*p*/);
98
99 typedef 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
114 enum {
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
144 extern 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
158 extern 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
172 extern 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
188 extern 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
200 extern 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
214 extern 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
225 extern void lbuf_destroy(lbuf */*b*/);
226
227 /*----- That's all, folks -------------------------------------------------*/
228
229 #ifdef __cplusplus
230   }
231 #endif
232
233 #endif