chiark - git - mdw - mLib/blob - lbuf.h

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