chiark - git - mdw - mLib/blob - struct/buf.h

   1 /* -*-c-*-
   2  *
   3  * Reading and writing packet buffers
   4  *
   5  * (c) 2001 Straylight/Edgeware
   6  */
   7
   8 /*----- Licensing notice --------------------------------------------------*
   9  *
  10  * This file is part of the mLib utilities library.
  11  *
  12  * mLib is free software; you can redistribute it and/or modify
  13  * it under the terms of the GNU Library General Public License as
  14  * published by the Free Software Foundation; either version 2 of the
  15  * License, or (at your option) any later version.
  16  *
  17  * mLib is distributed in the hope that it will be useful,
  18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20  * GNU Library General Public License for more details.
  21  *
  22  * You should have received a copy of the GNU Library General Public
  23  * License along with mLib; if not, write to the Free
  24  * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
  25  * MA 02111-1307, USA.
  26  */
  27
  28 #ifndef MLIB_BUF_H
  29 #define MLIB_BUF_H
  30
  31 #ifdef __cplusplus
  32   extern "C" {
  33 #endif
  34
  35 /*----- Header files ------------------------------------------------------*/
  36
  37 #include <stddef.h>
  38
  39 #ifndef MLIB_BITS_H
  40 #  include "bits.h"
  41 #endif
  42
  43 #ifndef MLIB_DSTR_H
  44 #  include "dstr.h"
  45 #endif
  46
  47 #ifndef MLIB_MACROS_H
  48 #  include "macros.h"
  49 #endif
  50
  51 /*----- Data structures ---------------------------------------------------*/
  52
  53 /* --- Buffers --- *
  54  *
  55  * Buffers provide a simple stream-like interface for building and parsing
  56  * packets.
  57  */
  58
  59 typedef struct buf {
  60   octet *base, *p, *limit;              /* Pointers to the buffer */
  61   unsigned f;                           /* Various flags */
  62 } buf;
  63
  64 #define BF_BROKEN 1u                    /* Buffer is broken */
  65
  66 /*----- Useful macros -----------------------------------------------------*/
  67
  68 #define BBASE(b) ((b)->base)
  69 #define BLIM(b) ((b)->limit)
  70 #define BCUR(b) ((b)->p)
  71 #define BSZ(b) ((b)->limit - (b)->base)
  72 #define BLEN(b) ((b)->p - (b)->base)
  73 #define BLEFT(b) ((b)->limit - (b)->p)
  74 #define BSTEP(b, sz) ((b)->p += (sz))
  75 #define BBAD(b) ((b)->f & BF_BROKEN)
  76 #define BOK(b) (!BBAD(b))
  77
  78 #if GCC_VERSION_P(8, 0)
  79 #  define BENSURE(b, sz)                                                \
  80      MUFFLE_WARNINGS_EXPR(GCC_WARNING("-Wint-in-bool-context"),         \
  81        (BBAD(b) ? -1 : (sz) > BLEFT(b) ? (b)->f |= BF_BROKEN, -1 : 0))
  82 #else
  83 #  define BENSURE(b, sz)                                                \
  84      (BBAD(b) ? -1 : (sz) > BLEFT(b) ? (b)->f |= BF_BROKEN, -1 : 0)
  85 #endif
  86
  87 #define BUF_DOSUFFIXES(_) DOUINTCONV(_) _(z, z, z)
  88
  89 /*----- Functions provided ------------------------------------------------*/
  90
  91 /* --- @buf_init@ --- *
  92  *
  93  * Arguments:   @buf *b@ = pointer to a buffer block
  94  *              @void *p@ = pointer to a buffer
  95  *              @size_t sz@ = size of the buffer
  96  *
  97  * Returns:     ---
  98  *
  99  * Use:         Initializes the buffer block appropriately.
 100  */
 101
 102 extern void buf_init(buf */*b*/, void */*p*/, size_t /*sz*/);
 103
 104 /* --- @buf_break@ --- *
 105  *
 106  * Arguments:   @buf *b@ = pointer to a buffer block
 107  *
 108  * Returns:     Some negative value.
 109  *
 110  * Use:         Marks a buffer as broken.
 111  */
 112
 113 extern int buf_break(buf */*b*/);
 114
 115 /* --- @buf_flip@ --- *
 116  *
 117  * Arguments:   @buf *b@ = pointer to a buffer block
 118  *
 119  * Returns:     ---
 120  *
 121  * Use:         Flips a buffer so that if you've just been writing to it,
 122  *              you can now read from the bit you've written.
 123  */
 124
 125 extern void buf_flip(buf */*b*/);
 126
 127 /* --- @buf_ensure@ --- *
 128  *
 129  * Arguments:   @buf *b@ = pointer to a buffer block
 130  *              @size_t sz@ = size of data wanted
 131  *
 132  * Returns:     Zero if it worked, nonzero if there wasn't enough space.
 133  *
 134  * Use:         Ensures that there are @sz@ bytes still in the buffer.
 135  */
 136
 137 extern int buf_ensure(buf */*b*/, size_t /*sz*/);
 138
 139 /* --- @buf_get@ --- *
 140  *
 141  * Arguments:   @buf *b@ = pointer to a buffer block
 142  *              @size_t sz@ = size of the buffer
 143  *
 144  * Returns:     Pointer to the place in the buffer.
 145  *
 146  * Use:         Reserves a space in the buffer of the requested size, and
 147  *              returns its start address.
 148  */
 149
 150 extern void *buf_get(buf */*b*/, size_t /*sz*/);
 151
 152 /* --- @buf_put@ --- *
 153  *
 154  * Arguments:   @buf *b@ = pointer to a buffer block
 155  *              @const void *p@ = pointer to a buffer
 156  *              @size_t sz@ = size of the buffer
 157  *
 158  * Returns:     Zero if it worked, nonzero if there wasn't enough space.
 159  *
 160  * Use:         Fetches data from some place and puts it in the buffer
 161  */
 162
 163 extern int buf_put(buf */*b*/, const void */*p*/, size_t /*sz*/);
 164
 165 /* --- @buf_getbyte@ --- *
 166  *
 167  * Arguments:   @buf *b@ = pointer to a buffer block
 168  *
 169  * Returns:     A byte, or less than zero if there wasn't a byte there.
 170  *
 171  * Use:         Gets a single byte from a buffer.
 172  */
 173
 174 extern int buf_getbyte(buf */*b*/);
 175
 176 /* --- @buf_putbyte@ --- *
 177  *
 178  * Arguments:   @buf *b@ = pointer to a buffer block
 179  *              @int ch@ = byte to write
 180  *
 181  * Returns:     Zero if OK, nonzero if there wasn't enough space.
 182  *
 183  * Use:         Puts a single byte in a buffer.
 184  */
 185
 186 extern int buf_putbyte(buf */*b*/, int /*ch*/);
 187
 188 /* --- @buf_getu{8,{16,24,32,64}{,l,b}}@ --- *
 189  *
 190  * Arguments:   @buf *b@ = pointer to a buffer block
 191  *              @uintSZ *w@ = where to put the word
 192  *
 193  * Returns:     Zero if OK, or nonzero if there wasn't a word there.
 194  *
 195  * Use:         Gets a word of appropriate size and order from a buffer.
 196  */
 197
 198 #define BUF_DECL_GETU_(n, W, w)                                         \
 199   extern int buf_getu##w(buf */*b*/, uint##n */*w*/);
 200 DOUINTCONV(BUF_DECL_GETU_)
 201
 202 /* --- @buf_getk64{,l,b}@ --- *
 203  *
 204  * Arguments:   @buf *b@ = pointer to a buffer block
 205  *              @kludge64 *w@ = where to put the word
 206  *
 207  * Returns:     Zero if OK, or nonzero if there wasn't a word there.
 208  *
 209  * Use:         Gets a word of appropriate size and order from a buffer.
 210  */
 211
 212 extern int buf_getk64(buf */*b*/, kludge64 */*w*/);
 213 extern int buf_getk64l(buf */*b*/, kludge64 */*w*/);
 214 extern int buf_getk64b(buf */*b*/, kludge64 */*w*/);
 215
 216 /* --- @buf_putu{8,{16,24,32,64}{,l,b}}@ --- *
 217  *
 218  * Arguments:   @buf *b@ = pointer to a buffer block
 219  *              @uintSZ w@ = word to write
 220  *
 221  * Returns:     Zero if OK, or nonzero if there wasn't enough space
 222  *
 223  * Use:         Puts a word into a buffer with appropriate size and order.
 224  */
 225
 226 #define BUF_DECL_PUTU_(n, W, w)                                         \
 227   extern int buf_putu##w(buf */*b*/, uint##n /*w*/);
 228 DOUINTCONV(BUF_DECL_PUTU_)
 229
 230 /* --- @buf_putk64{,l,b}@ --- *
 231  *
 232  * Arguments:   @buf *b@ = pointer to a buffer block
 233  *              @kludge64 w@ = word to write
 234  *
 235  * Returns:     Zero if OK, or nonzero if there wasn't enough space
 236  *
 237  * Use:         Gets a word of appropriate size and order from a buffer.
 238  */
 239
 240 extern int buf_putk64(buf */*b*/, kludge64 /*w*/);
 241 extern int buf_putk64l(buf */*b*/, kludge64 /*w*/);
 242 extern int buf_putk64b(buf */*b*/, kludge64 /*w*/);
 243
 244 /* --- @buf_getmem{8,{16,24,32,64}{,l,b},z} --- *
 245  *
 246  * Arguments:   @buf *b@ = pointer to a buffer block
 247  *              @size_t *nn@ = where to put the length
 248  *
 249  * Returns:     Pointer to the buffer data, or null.
 250  *
 251  * Use:         Gets a chunk of memory from a buffer.  The suffix is the
 252  *              width and byte order of the length; @z@ means null-
 253  *              terminated.
 254  */
 255
 256 #define BUF_DECL_GETMEM_(n, W, w)                                       \
 257   extern void *buf_getmem##w(buf */*b*/, size_t */*nn*/);
 258 BUF_DOSUFFIXES(BUF_DECL_GETMEM_)
 259
 260 /* --- @buf_putmem{8,{16,24,32,64}{,l,b},z} --- *
 261  *
 262  * Arguments:   @buf *b@ = pointer to a buffer block
 263  *              @const void *p@ = pointer to data to write
 264  *              @size_t n@ = length to write
 265  *
 266  * Returns:     Zero if OK, nonzero if there wasn't enough space.
 267  *
 268  * Use:         Writes a chunk of data to a buffer.  The suffix is the
 269  *              width and byte order of the length; @z@ means null-
 270  *              terminated.
 271  */
 272
 273 #define BUF_DECL_PUTMEM_(n, W, w)                                       \
 274   extern int buf_putmem##w(buf */*b*/, const void */*p*/, size_t /*nn*/);
 275 BUF_DOSUFFIXES(BUF_DECL_PUTMEM_)
 276
 277 /* --- @buf_getbuf{8,{16,24,32,64}{,l,b},z} --- *
 278  *
 279  * Arguments:   @buf *b@ = pointer to a buffer block
 280  *              @buf *bb@ = where to put the result
 281  *
 282  * Returns:     Zero if it worked, nonzero if there wasn't enough space.
 283  *
 284  * Use:         Gets a block of data from a buffer, and writes its bounds to
 285  *              another buffer.
 286  */
 287
 288 #define BUF_DECL_GETBUF_(n, W, w)                                       \
 289   extern int buf_getbuf##w(buf */*b*/, buf */*bb*/);
 290 BUF_DOSUFFIXES(BUF_DECL_GETBUF_)
 291
 292 /* --- @buf_putbuf{8,{16,24,32,64}{,l,b},z} --- *
 293  *
 294  * Arguments:   @buf *b@ = pointer to a buffer block
 295  *              @buf *bb@ = buffer to write
 296  *
 297  * Returns:     Zero if it worked, nonzero if there wasn't enough space.
 298  *
 299  * Use:         Puts the contents of a buffer to a buffer.
 300  */
 301
 302 #define BUF_DECL_PUTBUF_(n, W, w)                                       \
 303   extern int buf_putbuf##w(buf */*b*/, buf */*bb*/);
 304 BUF_DOSUFFIXES(BUF_DECL_PUTBUF_)
 305
 306 /* --- @buf_getdstr{8,{16,24,32,64}{,l,b},z} --- *
 307  *
 308  * Arguments:   @buf *b@ = pointer to a buffer block
 309  *              @dstr *d@ = where to put the result
 310  *
 311  * Returns:     Zero if it worked, nonzero if there wasn't enough space.
 312  *
 313  * Use:         Gets a block of data from a buffer, and writes its contents
 314  *              to a string.
 315  */
 316
 317 #define BUF_DECL_GETDSTR_(n, W, w)                                      \
 318   extern int buf_getdstr##w(buf */*b*/, dstr */*d*/);
 319 BUF_DOSUFFIXES(BUF_DECL_GETDSTR_)
 320
 321 /* --- @buf_putdstr{8,{16,24,32,64}{,l,b},z} --- *
 322  *
 323  * Arguments:   @buf *b@ = pointer to a buffer block
 324  *              @dstr *d@ = string to write
 325  *
 326  * Returns:     Zero if it worked, nonzero if there wasn't enough space.
 327  *
 328  * Use:         Puts a dynamic string to a buffer.
 329  */
 330
 331 #define BUF_DECL_PUTDSTR_(n, W, w)                                      \
 332   extern int buf_putdstr##w(buf */*b*/, dstr */*d*/);
 333 BUF_DOSUFFIXES(BUF_DECL_PUTDSTR_)
 334
 335 /* --- @buf_putstr{8,{16,24,32,64}{,l,b},z} --- *
 336  *
 337  * Arguments:   @buf *b@ = pointer to a buffer block
 338  *              @const char *p@ = string to write
 339  *
 340  * Returns:     Zero if it worked, nonzero if there wasn't enough space.
 341  *
 342  * Use:         Puts a null-terminated string to a buffer.
 343  */
 344
 345 #define BUF_DECL_PUTSTR_(n, W, w)                                       \
 346   extern int buf_putstr##w(buf */*b*/, const char */*p*/);
 347 BUF_DOSUFFIXES(BUF_DECL_PUTSTR_)
 348
 349 /*----- That's all, folks -------------------------------------------------*/
 350
 351 #ifdef __cplusplus
 352   }
 353 #endif
 354
 355 #endif