chiark - git - mdw - mLib/blob - 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