contrib/bind-9.2.4rc7/lib/lwres/include/lwres/lwbuffer.h

   1 /*
   2  * Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
   3  * Copyright (C) 2000, 2001  Internet Software Consortium.
   4  *
   5  * Permission to use, copy, modify, and distribute this software for any
   6  * purpose with or without fee is hereby granted, provided that the above
   7  * copyright notice and this permission notice appear in all copies.
   8  *
   9  * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  10  * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  11  * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  12  * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  13  * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  14  * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  15  * PERFORMANCE OF THIS SOFTWARE.
  16  */
  17
  18 /* $Id: lwbuffer.h,v 1.15.2.1 2004/03/09 06:12:37 marka Exp $ */
  19
  20 #ifndef LWRES_LWBUFFER_H
  21 #define LWRES_LWBUFFER_H 1
  22
  23 /*****
  24  ***** Module Info
  25  *****/
  26
  27 /*
  28  * Buffers
  29  *
  30  * A buffer is a region of memory, together with a set of related subregions.
  31  * Buffers are used for parsing and I/O operations.
  32  *
  33  * The 'used region' and the 'available' region are disjoint, and their
  34  * union is the buffer's region.  The used region extends from the beginning
  35  * of the buffer region to the last used byte.  The available region
  36  * extends from one byte greater than the last used byte to the end of the
  37  * buffer's region.  The size of the used region can be changed using various
  38  * buffer commands.  Initially, the used region is empty.
  39  *
  40  * The used region is further subdivided into two disjoint regions: the
  41  * 'consumed region' and the 'remaining region'.  The union of these two
  42  * regions is the used region.  The consumed region extends from the beginning
  43  * of the used region to the byte before the 'current' offset (if any).  The
  44  * 'remaining' region the current pointer to the end of the used
  45  * region.  The size of the consumed region can be changed using various
  46  * buffer commands.  Initially, the consumed region is empty.
  47  *
  48  * The 'active region' is an (optional) subregion of the remaining region.
  49  * It extends from the current offset to an offset in the remaining region
  50  * that is selected with lwres_buffer_setactive().  Initially, the active
  51  * region is empty.  If the current offset advances beyond the chosen offset,
  52  * the active region will also be empty.
  53  *
  54  *  /----- used region -----\/-- available --\
  55  *  +----------------------------------------+
  56  *  | consumed  | remaining |                |
  57  *  +----------------------------------------+
  58  *  a           b     c     d                e
  59  *
  60  * a == base of buffer.
  61  * b == current pointer.  Can be anywhere between a and d.
  62  * c == active pointer.  Meaningful between b and d.
  63  * d == used pointer.
  64  * e == length of buffer.
  65  *
  66  * a-e == entire (length) of buffer.
  67  * a-d == used region.
  68  * a-b == consumed region.
  69  * b-d == remaining region.
  70  * b-c == optional active region.
  71  *
  72  * The following invariants are maintained by all routines:
  73  *
  74  *      length > 0
  75  *
  76  *      base is a valid pointer to length bytes of memory
  77  *
  78  *      0 <= used <= length
  79  *
  80  *      0 <= current <= used
  81  *
  82  *      0 <= active <= used
  83  *      (although active < current implies empty active region)
  84  *
  85  * MP:
  86  *      Buffers have no synchronization.  Clients must ensure exclusive
  87  *      access.
  88  *
  89  * Reliability:
  90  *      No anticipated impact.
  91  *
  92  * Resources:
  93  *      Memory: 1 pointer + 6 unsigned integers per buffer.
  94  *
  95  * Security:
  96  *      No anticipated impact.
  97  *
  98  * Standards:
  99  *      None.
 100  */
 101
 102 /***
 103  *** Imports
 104  ***/
 105
 106 #include <lwres/lang.h>
 107 #include <lwres/int.h>
 108
 109 LWRES_LANG_BEGINDECLS
 110
 111 /***
 112  *** Magic numbers
 113  ***/
 114 #define LWRES_BUFFER_MAGIC              0x4275663fU     /* Buf?. */
 115
 116 #define LWRES_BUFFER_VALID(b)           ((b) != NULL && \
 117                                          (b)->magic == LWRES_BUFFER_MAGIC)
 118
 119 /*
 120  * The following macros MUST be used only on valid buffers.  It is the
 121  * caller's responsibility to ensure this by using the LWRES_BUFFER_VALID
 122  * check above, or by calling another lwres_buffer_*() function (rather than
 123  * another macro.)
 124  */
 125
 126 /*
 127  * Get the length of the used region of buffer "b"
 128  */
 129 #define LWRES_BUFFER_USEDCOUNT(b)       ((b)->used)
 130
 131 /*
 132  * Get the length of the available region of buffer "b"
 133  */
 134 #define LWRES_BUFFER_AVAILABLECOUNT(b)  ((b)->length - (b)->used)
 135
 136 #define LWRES_BUFFER_REMAINING(b)       ((b)->used - (b)->current)
 137
 138 /*
 139  * Note that the buffer structure is public.  This is principally so buffer
 140  * operations can be implemented using macros.  Applications are strongly
 141  * discouraged from directly manipulating the structure.
 142  */
 143
 144 typedef struct lwres_buffer lwres_buffer_t;
 145 struct lwres_buffer {
 146         unsigned int            magic;
 147         unsigned char          *base;
 148         /* The following integers are byte offsets from 'base'. */
 149         unsigned int            length;
 150         unsigned int            used;
 151         unsigned int            current;
 152         unsigned int            active;
 153 };
 154
 155 /***
 156  *** Functions
 157  ***/
 158
 159 void
 160 lwres_buffer_init(lwres_buffer_t *b, void *base, unsigned int length);
 161 /*
 162  * Make 'b' refer to the 'length'-byte region starting at base.
 163  *
 164  * Requires:
 165  *
 166  *      'length' > 0
 167  *
 168  *      'base' is a pointer to a sequence of 'length' bytes.
 169  *
 170  */
 171
 172 void
 173 lwres_buffer_invalidate(lwres_buffer_t *b);
 174 /*
 175  * Make 'b' an invalid buffer.
 176  *
 177  * Requires:
 178  *      'b' is a valid buffer.
 179  *
 180  * Ensures:
 181  *      If assertion checking is enabled, future attempts to use 'b' without
 182  *      calling lwres_buffer_init() on it will cause an assertion failure.
 183  */
 184
 185 void
 186 lwres_buffer_add(lwres_buffer_t *b, unsigned int n);
 187 /*
 188  * Increase the 'used' region of 'b' by 'n' bytes.
 189  *
 190  * Requires:
 191  *
 192  *      'b' is a valid buffer
 193  *
 194  *      used + n <= length
 195  *
 196  */
 197
 198 void
 199 lwres_buffer_subtract(lwres_buffer_t *b, unsigned int n);
 200 /*
 201  * Decrease the 'used' region of 'b' by 'n' bytes.
 202  *
 203  * Requires:
 204  *
 205  *      'b' is a valid buffer
 206  *
 207  *      used >= n
 208  *
 209  */
 210
 211 void
 212 lwres_buffer_clear(lwres_buffer_t *b);
 213 /*
 214  * Make the used region empty.
 215  *
 216  * Requires:
 217  *
 218  *      'b' is a valid buffer
 219  *
 220  * Ensures:
 221  *
 222  *      used = 0
 223  *
 224  */
 225
 226 void
 227 lwres_buffer_first(lwres_buffer_t *b);
 228 /*
 229  * Make the consumed region empty.
 230  *
 231  * Requires:
 232  *
 233  *      'b' is a valid buffer
 234  *
 235  * Ensures:
 236  *
 237  *      current == 0
 238  *
 239  */
 240
 241 void
 242 lwres_buffer_forward(lwres_buffer_t *b, unsigned int n);
 243 /*
 244  * Increase the 'consumed' region of 'b' by 'n' bytes.
 245  *
 246  * Requires:
 247  *
 248  *      'b' is a valid buffer
 249  *
 250  *      current + n <= used
 251  *
 252  */
 253
 254 void
 255 lwres_buffer_back(lwres_buffer_t *b, unsigned int n);
 256 /*
 257  * Decrease the 'consumed' region of 'b' by 'n' bytes.
 258  *
 259  * Requires:
 260  *
 261  *      'b' is a valid buffer
 262  *
 263  *      n <= current
 264  *
 265  */
 266
 267 lwres_uint8_t
 268 lwres_buffer_getuint8(lwres_buffer_t *b);
 269 /*
 270  * Read an unsigned 8-bit integer from 'b' and return it.
 271  *
 272  * Requires:
 273  *
 274  *      'b' is a valid buffer.
 275  *
 276  *      The length of the available region of 'b' is at least 1.
 277  *
 278  * Ensures:
 279  *
 280  *      The current pointer in 'b' is advanced by 1.
 281  *
 282  * Returns:
 283  *
 284  *      A 8-bit unsigned integer.
 285  */
 286
 287 void
 288 lwres_buffer_putuint8(lwres_buffer_t *b, lwres_uint8_t val);
 289 /*
 290  * Store an unsigned 8-bit integer from 'val' into 'b'.
 291  *
 292  * Requires:
 293  *      'b' is a valid buffer.
 294  *
 295  *      The length of the unused region of 'b' is at least 1.
 296  *
 297  * Ensures:
 298  *      The used pointer in 'b' is advanced by 1.
 299  */
 300
 301 lwres_uint16_t
 302 lwres_buffer_getuint16(lwres_buffer_t *b);
 303 /*
 304  * Read an unsigned 16-bit integer in network byte order from 'b', convert
 305  * it to host byte order, and return it.
 306  *
 307  * Requires:
 308  *
 309  *      'b' is a valid buffer.
 310  *
 311  *      The length of the available region of 'b' is at least 2.
 312  *
 313  * Ensures:
 314  *
 315  *      The current pointer in 'b' is advanced by 2.
 316  *
 317  * Returns:
 318  *
 319  *      A 16-bit unsigned integer.
 320  */
 321
 322 void
 323 lwres_buffer_putuint16(lwres_buffer_t *b, lwres_uint16_t val);
 324 /*
 325  * Store an unsigned 16-bit integer in host byte order from 'val'
 326  * into 'b' in network byte order.
 327  *
 328  * Requires:
 329  *      'b' is a valid buffer.
 330  *
 331  *      The length of the unused region of 'b' is at least 2.
 332  *
 333  * Ensures:
 334  *      The used pointer in 'b' is advanced by 2.
 335  */
 336
 337 lwres_uint32_t
 338 lwres_buffer_getuint32(lwres_buffer_t *b);
 339 /*
 340  * Read an unsigned 32-bit integer in network byte order from 'b', convert
 341  * it to host byte order, and return it.
 342  *
 343  * Requires:
 344  *
 345  *      'b' is a valid buffer.
 346  *
 347  *      The length of the available region of 'b' is at least 2.
 348  *
 349  * Ensures:
 350  *
 351  *      The current pointer in 'b' is advanced by 2.
 352  *
 353  * Returns:
 354  *
 355  *      A 32-bit unsigned integer.
 356  */
 357
 358 void
 359 lwres_buffer_putuint32(lwres_buffer_t *b, lwres_uint32_t val);
 360 /*
 361  * Store an unsigned 32-bit integer in host byte order from 'val'
 362  * into 'b' in network byte order.
 363  *
 364  * Requires:
 365  *      'b' is a valid buffer.
 366  *
 367  *      The length of the unused region of 'b' is at least 4.
 368  *
 369  * Ensures:
 370  *      The used pointer in 'b' is advanced by 4.
 371  */
 372
 373 void
 374 lwres_buffer_putmem(lwres_buffer_t *b, const unsigned char *base,
 375                     unsigned int length);
 376 /*
 377  * Copy 'length' bytes of memory at 'base' into 'b'.
 378  *
 379  * Requires:
 380  *      'b' is a valid buffer.
 381  *
 382  *      'base' points to 'length' bytes of valid memory.
 383  *
 384  */
 385
 386 void
 387 lwres_buffer_getmem(lwres_buffer_t *b, unsigned char *base,
 388                     unsigned int length);
 389 /*
 390  * Copy 'length' bytes of memory from 'b' into 'base'.
 391  *
 392  * Requires:
 393  *      'b' is a valid buffer.
 394  *
 395  *      'base' points to at least 'length' bytes of valid memory.
 396  *
 397  *      'b' have at least 'length' bytes remaining.
 398  */
 399
 400 LWRES_LANG_ENDDECLS
 401
 402 #endif /* LWRES_LWBUFFER_H */