chiark / gitweb /
Import buf from Catacomb; split out the dstr bits, and throw away the mp and
authormdw <mdw>
Fri, 23 Sep 2005 15:16:12 +0000 (15:16 +0000)
committermdw <mdw>
Fri, 23 Sep 2005 15:16:12 +0000 (15:16 +0000)
ec stuff.  Document it.  Fix email addresses.

50 files changed:
Makefile.am
bits.h
buf-dstr.c [new file with mode: 0644]
buf.c
buf.h
man/alloc.3
man/arena.3
man/assoc.3
man/atom.3
man/base32.3
man/base64.3
man/bits.3
man/bres.3
man/buf.3 [new file with mode: 0644]
man/conn.3
man/crc-mktab.1
man/crc32.3
man/darray.3
man/dspool.3
man/dstr.3
man/env.3
man/exc.3
man/fdflags.3
man/fdpass.3
man/fwatch.3
man/hash.3
man/hex.3
man/ident.3
man/lbuf.3
man/lock.3
man/mLib.3
man/macros.3
man/mdwopt.3
man/pkbuf.3
man/pool.3
man/quis.3
man/report.3
man/sel.3
man/selbuf.3
man/selpk.3
man/sig.3
man/str.3
man/sub.3
man/sym.3
man/testrig.3
man/trace.3
man/tv.3
man/unihash-mkstatic.1
man/unihash.3
man/url.3

index aa3aa1d..a0779cc 100644 (file)
@@ -43,7 +43,8 @@ pkglibexec_PROGRAMS = @BRES_LIBEXEC@
 EXTRA_PROGRAMS = bres
 
 pkginclude_HEADERS = \
-       align.h alloc.h arena.h bits.h exc.h macros.h quis.h report.h sub.h \
+       align.h alloc.h arena.h bits.h buf.h exc.h macros.h quis.h \
+         report.h sub.h \
        trace.h track.h unihash.h \
        pool.h \
        atom.h assoc.h darray.h dstr.h dspool.h hash.h sym.h crc32.h \
@@ -59,10 +60,11 @@ libmLib_la_LDFLAGS = -version-info 2:3:0
 ## difference between the first and last numbers is major version.
 
 libmLib_la_SOURCES = \
-       alloc.c arena.c exc.c quis.c pquis.c report.c sub.c trace.c \
+       alloc.c arena.c buf.c exc.c quis.c pquis.c report.c sub.c trace.c \
                traceopt.c track.c \
        pool.c pool-file.c pool-sub.c \
-       atom.c assoc.c darray.c dstr.c dputf.c dspool.c hash.c sym.c \
+       atom.c assoc.c buf-dstr.c darray.c dstr.c dputf.c dspool.c hash.c \
+         sym.c \
        crc32.c crc32-tab.c \
        unihash.c unihash-global.c \
        env.c fdflags.c fdpass.c fwatch.c lock.c \
diff --git a/bits.h b/bits.h
index b895dd4..f6217ef 100644 (file)
--- a/bits.h
+++ b/bits.h
  */
 
 typedef unsigned short uint16;
-typedef unsigned char octet;
+typedef unsigned char octet, uint8;
 
 /* --- WARNING! --- *
  *
@@ -126,17 +126,19 @@ typedef unsigned char octet;
 
 #define MASK8 0xffu
 #define MASK16 0xffffu
-#define MASK16_L 0xffffu
-#define MASK16_B 0xffffu
+#define MASK16_L MASK16
+#define MASK16_B MASK16
 #define MASK24 0xffffffu
-#define MASK24_L 0xffffffu
-#define MASK24_B 0xffffffu
+#define MASK24_L MASK24
+#define MASK24_B MASK24
 #define MASK32 0xffffffffu
-#define MASK32_L 0xffffffffu
-#define MASK32_B 0xffffffffu
+#define MASK32_L MASK32
+#define MASK32_B MASK32
 
 #ifdef HAVE_UINT64
 #  define MASK64 MLIB_BITS_EXTENSION 0xffffffffffffffffu
+#  define MASK64_L MASK64
+#  define MASK64_B MASK64
 #endif
 
 /* --- Sizes --- */
@@ -152,6 +154,50 @@ typedef unsigned char octet;
 #define SZ_32_L 4
 #define SZ_32_B 4
 
+#ifdef HAVE_UINT64
+#  define SZ_64 8
+#  define SZ_64_L 8
+#  define SZ_64_B 8
+#endif
+
+/* --- Type aliases --- */
+
+#define TY_U8 octet
+#define TY_U16 uint16
+#define TY_U16_L uint16
+#define TY_U16_B uint16
+#define TY_U24 uint24
+#define TY_U24_L uint24
+#define TY_U24_B uint24
+#define TY_U32 uint32
+#define TY_U32_L uint32
+#define TY_U32_B uint32
+
+#ifdef HAVE_UINT64
+#  define TY_U64 uint64
+#  define TY_U64_L uint64
+#  define TY_U64_B uint64
+#endif
+
+/* --- List macros --- */
+
+#ifdef HAVE_UINT64
+#  define  DOUINTCONV(_)                                               \
+     _(8, 8, 8)                                                                \
+     _(16, 16, 16) _(16, 16_L, 16l) _(16, 16_B, 16b)                   \
+     _(24, 24, 24) _(24, 24_L, 24l) _(24, 24_B, 24b)                   \
+     _(32, 32, 32) _(32, 32_L, 32l) _(32, 32_B, 32b)                   \
+     _(64, 64, 64) _(64, 64_L, 64l) _(64, 64_B, 64b)
+#  define DOINTSZ(_) _(8) _(16) _(24) _(32) _(64)
+#else
+#  define  DOUINTCONV(_)                                               \
+     _(8, 8, 8)                                                                \
+     _(16, 16, 16) _(16, 16_L, 16l) _(16, 16_B, 16b)                   \
+     _(24, 24, 24) _(24, 24_L, 24l) _(24, 24_B, 24b)                   \
+     _(32, 32, 32) _(32, 32_L, 32l) _(32, 32_B, 32b)
+#  define DOINTSZ(_) _(8) _(16) _(24) _(32)
+#endif
+
 /* --- Type coercions --- */
 
 #define U8(x) ((octet)((x) & MASK8))
diff --git a/buf-dstr.c b/buf-dstr.c
new file mode 100644 (file)
index 0000000..6cc0c43
--- /dev/null
@@ -0,0 +1,77 @@
+/* -*-c-*-
+ *
+ * $Id$
+ *
+ * Buffers and dynamic strings
+ *
+ * (c) 2005 Straylight/Edgeware
+ */
+
+/*----- Licensing notice --------------------------------------------------* 
+ *
+ * This file is part of the mLib utilities library.
+ *
+ * mLib is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU Library General Public License as
+ * published by the Free Software Foundation; either version 2 of the
+ * License, or (at your option) any later version.
+ * 
+ * mLib is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Library General Public License for more details.
+ * 
+ * You should have received a copy of the GNU Library General Public
+ * License along with mLib; if not, write to the Free
+ * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
+ * MA 02111-1307, USA.
+ */
+
+/*----- Header files ------------------------------------------------------*/
+
+#include <string.h>
+
+#include "buf.h"
+
+/*----- Main code ---------------------------------------------------------*/
+
+/* --- @buf_getdstr{8,{16,24,32,64}{,l,b},z} --- *
+ *
+ * Arguments:  @buf *b@ = pointer to a buffer block
+ *             @dstr *d@ = where to put the result
+ *
+ * Returns:    Zero if it worked, nonzero if there wasn't enough space.
+ *
+ * Use:                Gets a block of data from a buffer, and writes its contents
+ *             to a string.
+ */
+
+#define BUF_GETDSTR_(n, W, w)                                          \
+  int buf_getdstr##w(buf *b, dstr *d)                                  \
+  {                                                                    \
+    void *p;                                                           \
+    size_t sz;                                                         \
+                                                                       \
+    if ((p = buf_getmem##w(b, &sz)) == 0)                              \
+      return (-1);                                                     \
+    DPUTM(d, p, sz);                                                   \
+    return (0);                                                                \
+  }
+BUF_DOSUFFIXES(BUF_GETDSTR_)
+
+/* --- @buf_putdstr{8,{16,24,32,64}{,l,b},z} --- *
+ *
+ * Arguments:  @buf *b@ = pointer to a buffer block
+ *             @dstr *d@ = string to write
+ *
+ * Returns:    Zero if it worked, nonzero if there wasn't enough space.
+ *
+ * Use:                Puts a dynamic string to a buffer.
+ */
+
+#define BUF_PUTDSTR_(n, W, w)                                          \
+  int buf_putdstr##w(buf *b, dstr *d)                                  \
+    { return (buf_putmem##w(b, d->buf, d->len)); }
+BUF_DOSUFFIXES(BUF_PUTDSTR_)
+
+/*----- That's all, folks -------------------------------------------------*/
diff --git a/buf.c b/buf.c
index e34d876..3dc4996 100644 (file)
--- a/buf.c
+++ b/buf.c
@@ -9,30 +9,29 @@
 
 /*----- Licensing notice --------------------------------------------------* 
  *
- * This file is part of Catacomb.
+ * This file is part of the mLib utilities library.
  *
- * Catacomb is free software; you can redistribute it and/or modify
+ * mLib is free software; you can redistribute it and/or modify
  * it under the terms of the GNU Library General Public License as
  * published by the Free Software Foundation; either version 2 of the
  * License, or (at your option) any later version.
  * 
- * Catacomb is distributed in the hope that it will be useful,
+ * mLib is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  * GNU Library General Public License for more details.
  * 
  * You should have received a copy of the GNU Library General Public
- * License along with Catacomb; if not, write to the Free
+ * License along with mLib; if not, write to the Free
  * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
  * MA 02111-1307, USA.
  */
 
 /*----- Header files ------------------------------------------------------*/
 
+#include <assert.h>
 #include <string.h>
 
-#include "mp.h"
-#include "ec.h"
 #include "buf.h"
 
 /*----- Main code ---------------------------------------------------------*/
@@ -169,81 +168,45 @@ int buf_putbyte(buf *b, int ch)
   return (0);
 }
 
-/* --- @buf_getu16@ --- *
+/* --- @buf_getu{8,{16,24,32,64}{,l,b}}@ --- *
  *
  * Arguments:  @buf *b@ = pointer to a buffer block
- *             @uint16 *w@ = where to put the word
+ *             @uintSZ *w@ = where to put the word
  *
  * Returns:    Zero if OK, or nonzero if there wasn't a word there.
  *
- * Use:                Gets a 16-bit word from a buffer.
+ * Use:                Gets a word of appropriate size and order from a buffer.
  */
 
-int buf_getu16(buf *b, uint16 *w)
-{
-  if (BENSURE(b, 2))
-    return (-1);
-  *w = LOAD16(b->p);
-  BSTEP(b, 2);
-  return (0);
-}
-
-/* --- @buf_putu16@ --- *
- *
- * Arguments:  @buf *b@ = pointer to a buffer block
- *             @uint16 w@ = word to write
- *
- * Returns:    Zero if OK, nonzero if there wasn't enough space.
- *
- * Use:                Puts a 16-but word in a buffer.
- */
-
-int buf_putu16(buf *b, uint16 w)
-{
-  if (BENSURE(b, 2))
-    return (-1);
-  STORE16(b->p, w);
-  BSTEP(b, 2);
-  return (0);
-}
-
-/* --- @buf_getu32@ --- *
- *
- * Arguments:  @buf *b@ = pointer to a buffer block
- *             @uint32 *w@ = where to put the word
- *
- * Returns:    Zero if OK, or nonzero if there wasn't a word there.
- *
- * Use:                Gets a 32-bit word from a buffer.
- */
-
-int buf_getu32(buf *b, uint32 *w)
-{
-  if (BENSURE(b, 4))
-    return (-1);
-  *w = LOAD32(b->p);
-  BSTEP(b, 4);
-  return (0);
-}
+#define BUF_GETU_(n, W, w)                                             \
+  int buf_getu##w(buf *b, uint##n *ww)                                 \
+  {                                                                    \
+    if (BENSURE(b, SZ_##W)) return (-1);                               \
+    *ww = LOAD##W(b->p);                                               \
+    BSTEP(b, SZ_##W);                                                  \
+    return (0);                                                                \
+  }
+DOUINTCONV(BUF_GETU_)
 
-/* --- @buf_putu32@ --- *
+/* --- @buf_putu{8,{16,24,32,64}{,l,b}}@ --- *
  *
  * Arguments:  @buf *b@ = pointer to a buffer block
- *             @uint32 w@ = word to write
+ *             @uintSZ w@ = word to write
  *
- * Returns:    Zero if OK, nonzero if there wasn't enough space.
+ * Returns:    Zero if OK, or nonzero if there wasn't enough space
  *
- * Use:                Puts a 32-but word in a buffer.
+ * Use:                Puts a word into a buffer with appropriate size and order.
  */
 
-int buf_putu32(buf *b, uint32 w)
-{
-  if (BENSURE(b, 4))
-    return (-1);
-  STORE32(b->p, w);
-  BSTEP(b, 4);
-  return (0);
-}
+#define BUF_PUTU_(n, W, w)                                             \
+  int buf_putu##w(buf *b, uint##n ww)                                  \
+  {                                                                    \
+    if (BENSURE(b, SZ_##W)) return (-1);                               \
+    STORE##W(b->p, ww);                                                        \
+    BSTEP(b, SZ_##W);                                                  \
+    return (0);                                                                \
+  }
+DOUINTCONV(BUF_PUTU_)
 
 /* --- @findz@ --- *
  *
@@ -267,53 +230,35 @@ static int findz(buf *b, size_t *nn)
   return (0);
 }
 
-#define DOSUFFIXES(DO) DO(8) DO(16) DO(32) DO(z)
-
-/* --- @buf_getmem{8,16,32,z} --- *
+/* --- @buf_getmem{8,{16,24,32,64}{,l,b},z} --- *
  *
  * Arguments:  @buf *b@ = pointer to a buffer block
  *             @size_t *nn@ = where to put the length
  *
  * Returns:    Pointer to the buffer data, or null.
  *
- * Use:                Gets a chunk of memory from a buffer.  The number, @16@ or
- *             @32@, is the width of the length; @z@ means null-terminated.
+ * Use:                Gets a chunk of memory from a buffer.  The suffix is the
+ *             width and byte order of the length; @z@ means null-
+ *             terminated.
  */
 
-void *buf_getmem8(buf *b, size_t *nn)
-{
-  int n;
-
-  if ((n = buf_getbyte(b)) < 0) return (0);
-  *nn = n;
-  return (buf_get(b, n));
-}
-
-void *buf_getmem16(buf *b, size_t *nn)
-{
-  uint16 n;
-
-  if (buf_getu16(b, &n)) return (0);
-  *nn = n;
-  return (buf_get(b, n));
-}
-
-void *buf_getmem32(buf *b, size_t *nn)
-{
-  uint32 n;
+#define BUF_GETMEM_(n, W, w)                                           \
+  void *buf_getmem##w(buf *b, size_t *nn)                              \
+  {                                                                    \
+    uint##n sz;                                                                \
+    if (buf_getu##n(b, &sz)) return (0);                               \
+    *nn = sz;                                                          \
+    return (buf_get(b, sz));                                           \
+  }
+DOUINTCONV(BUF_GETMEM_)
 
-  if (buf_getu32(b, &n)) return (0);
-  *nn = n;
-  return (buf_get(b, n));
-}
-  
 void *buf_getmemz(buf *b, size_t *nn)
 {
   if (findz(b, nn)) return (0);
   return (buf_get(b, *nn));
 }
 
-/* --- @buf_putmem{8,16,32,z} --- *
+/* --- @buf_putmem{8,{16,24,32,64}{,l,b},z} --- *
  *
  * Arguments:  @buf *b@ = pointer to a buffer block
  *             @const void *p@ = pointer to data to write
@@ -321,33 +266,20 @@ void *buf_getmemz(buf *b, size_t *nn)
  *
  * Returns:    Zero if OK, nonzero if there wasn't enough space.
  *
- * Use:                Writes a chunk of data to a buffer.  The number, @16@ or
- *             @32@, is the width of the length; @z@ means null-terminated.
+ * Use:                Writes a chunk of data to a buffer.  The suffix is the
+ *             width and byte order of the length; @z@ means null-
+ *             terminated.
  */
 
-int buf_putmem8(buf *b, const void *p, size_t n)
-{
-  assert(n <= 0xfful);
-  if (buf_putbyte(b, n) || buf_put(b, p, n))
-    return (-1);
-  return (0);
-}
-
-int buf_putmem16(buf *b, const void *p, size_t n)
-{
-  assert(n <= 0xfffful);
-  if (buf_putu16(b, n) || buf_put(b, p, n))
-    return (-1);
-  return (0);
-}
-
-int buf_putmem32(buf *b, const void *p, size_t n)
-{
-  assert(n <= 0xfffffffful);
-  if (buf_putu32(b, n) || buf_put(b, p, n))
-    return (-1);
-  return (0);
-}
+#define BUF_PUTMEM_(n, W, w)                                           \
+  int buf_putmem##w(buf *b, const void *p, size_t sz)                  \
+  {                                                                    \
+    assert(sz <= MASK##W);                                             \
+    if (buf_putu##n(b, sz) || buf_put(b, p, sz))                       \
+      return (-1);                                                     \
+    return (0);                                                                \
+  }
+DOUINTCONV(BUF_PUTMEM_)
 
 int buf_putmemz(buf *b, const void *p, size_t n)
 {
@@ -361,7 +293,7 @@ int buf_putmemz(buf *b, const void *p, size_t n)
   return (0);
 }
 
-/* --- @buf_getbuf{8,16,32,z}@ --- *
+/* --- @buf_getbuf{8,{16,24,32,64}{,l,b},z} --- *
  *
  * Arguments:  @buf *b@ = pointer to a buffer block
  *             @buf *bb@ = where to put the result
@@ -369,165 +301,50 @@ int buf_putmemz(buf *b, const void *p, size_t n)
  * Returns:    Zero if it worked, nonzero if there wasn't enough space.
  *
  * Use:                Gets a block of data from a buffer, and writes its bounds to
- *             another buffer.  The number, @16@ or @32@, is the width of
- *             the length; @z@ means null-terminated.
+ *             another buffer.
  */
 
-#define GETBUF(suff) int buf_getbuf##suff(buf *b, buf *bb)             \
-{                                                                      \
-  void *p;                                                             \
-  size_t n;                                                            \
+#define BUF_GETBUF_(n, W, w)                                           \
+  int buf_getbuf##w(buf *b, buf *bb)                                   \
+  {                                                                    \
+    void *p;                                                           \
+    size_t sz;                                                         \
                                                                        \
-  if ((p = buf_getmem##suff(b, &n)) == 0)                              \
-    return (-1);                                                       \
-  buf_init(bb, p, n);                                                  \
-  return (0);                                                          \
-}
-DOSUFFIXES(GETBUF)
-
-/* --- @buf_putbuf{8,16,32,z}@ --- *
- *
- * Arguments:  @buf *b@ = pointer to a buffer block
- *             @buf *bb@ = buffer to write
- *
- * Returns:    Zero if it worked, nonzero if there wasn't enough space.
- *
- * Use:                Puts the contents of a buffer to a buffer.  The number, @16@
- *             or @32@, is the width of the length; @z@ means null-
- *             terminated.
- */
-
-#define PUTBUF(suff) int buf_putbuf##suff(buf *b, buf *bb)             \
-  { return (buf_putmem##suff(b, BBASE(bb), BLEN(bb))); }
-DOSUFFIXES(PUTBUF)  
-
-/* --- @buf_getstr{8,16,32,z}@ --- *
- *
- * Arguments:  @buf *b@ = pointer to a buffer block
- *             @dstr *d@ = where to put the result
- *
- * Returns:    Zero if it worked, nonzero if there wasn't enough space.
- *
- * Use:                Gets a block of data from a buffer, and writes its contents
- *             to a string.  The number, @16@ or @32@, is the width of the
- *             length; @z@ means null-terminated.
- */
-
-#define GETSTR(suff) int buf_getstr##suff(buf *b, dstr *d)             \
-{                                                                      \
-  void *p;                                                             \
-  size_t n;                                                            \
-                                                                       \
-  if ((p = buf_getmem##suff(b, &n)) == 0)                              \
-    return (-1);                                                       \
-  DPUTM(d, p, n);                                                      \
-  return (0);                                                          \
-}
-DOSUFFIXES(GETSTR)
-
-/* --- @buf_putstr{8,16,32,z}@ --- *
- *
- * Arguments:  @buf *b@ = pointer to a buffer block
- *             @dstr *d@ = string to write
- *
- * Returns:    Zero if it worked, nonzero if there wasn't enough space.
- *
- * Use:                Puts a string to a buffer, and writes its bounds to
- *             another buffer.  The number, @16@ or @32@, is the width of
- *             the length; @z@ means null-terminated.
- */
-
-#define PUTSTR(suff) int buf_putstr##suff(buf *b, dstr *d)             \
-  { return (buf_putmem##suff(b, d->buf, d->len)); }
-DOSUFFIXES(PUTSTR)
-
-/* --- @buf_getmp@ --- *
- *
- * Arguments:  @buf *b@ = pointer to a buffer block
- *
- * Returns:    A multiprecision integer, or null if there wasn't one there.
- *
- * Use:                Gets a multiprecision integer from a buffer.
- */
-
-mp *buf_getmp(buf *b)
-{
-  uint16 sz;
-  size_t n;
-  mp *m;
-  if (buf_getu16(b, &sz) || buf_ensure(b, sz))
-    return (0);
-  m = mp_loadb(MP_NEW, BCUR(b), sz);
-  n = mp_octets(m);
-  if (n != sz && n != 0 && sz != 1) {
-    mp_drop(m);
-    return (0);
+    if ((p = buf_getmem##w(b, &sz)) == 0)                              \
+      return (-1);                                                     \
+    buf_init(bb, p, sz);                                               \
+    return (0);                                                                \
   }
-  BSTEP(b, sz);
-  return (m);
-}
+BUF_DOSUFFIXES(BUF_GETBUF_)
 
-/* --- @buf_putmp@ --- *
+/* --- @buf_putbuf{8,{16,24,32,64}{,l,b},z} --- *
  *
  * Arguments:  @buf *b@ = pointer to a buffer block
- *             @mp *m@ = a multiprecision integer
+ *             @buf *bb@ = buffer to write
  *
  * Returns:    Zero if it worked, nonzero if there wasn't enough space.
  *
- * Use:                Puts a multiprecision integer to a buffer.
+ * Use:                Puts the contents of a buffer to a buffer.
  */
 
-int buf_putmp(buf *b, mp *m)
-{
-  size_t sz = mp_octets(m);
-  assert(sz < MASK16);
-  if (!sz) sz = 1;
-  if (buf_putu16(b, sz) || buf_ensure(b, sz))
-    return (-1);
-  mp_storeb(m, BCUR(b), sz);
-  BSTEP(b, sz);
-  return (0);
-}
+#define BUF_PUTBUF_(n, W, w)                                           \
+  int buf_putbuf##w(buf *b, buf *bb)                                   \
+    { return (buf_putmem##w(b, BBASE(bb), BLEN(bb))); }
+BUF_DOSUFFIXES(BUF_PUTBUF_)
 
-/* --- @buf_getec@ --- *
+/* --- @buf_putstr{8,{16,24,32,64}{,l,b},z} --- *
  *
  * Arguments:  @buf *b@ = pointer to a buffer block
- *             @ec *p@ = where to put the point
- *
- * Returns:    Zero if it worked, nonzero if it failed.
- *
- * Use:                Gets a multiprecision integer from a buffer.  The point must
- *             be initialized.
- */
-
-int buf_getec(buf *b, ec *p)
-{
-  mp *x = 0, *y = 0;
-  uint16 n;
-  if (buf_ensure(b, 2)) return (-1);
-  n = LOAD16(BCUR(b)); if (!n) { BSTEP(b, 2); EC_SETINF(p); return (0); }
-  if ((x = buf_getmp(b)) == 0 || (y = buf_getmp(b)) == 0) {
-    mp_drop(x); mp_drop(y); return (-1);
-  }
-  EC_DESTROY(p); p->x = x; p->y = y; p->z = 0;
-  return (0);
-}
-
-/* --- @buf_putec@ --- *
- *
- * Arguments:  @buf *b@ = pointer to a buffer block
- *             @ec *p@ = an elliptic curve point
+ *             @const char *p@ = string to write
  *
  * Returns:    Zero if it worked, nonzero if there wasn't enough space.
  *
- * Use:                Puts an elliptic curve point to a buffer.
+ * Use:                Puts a null-terminated string to a buffer.
  */
 
-int buf_putec(buf *b, ec *p)
-{
-  if (EC_ATINF(p)) return (buf_putu16(b, 0));
-  if (buf_putmp(b, p->x) || buf_putmp(b, p->y)) return (-1);
-  return (0);
-}
+#define BUF_PUTSTR_(n, W, w)                                           \
+  int buf_putstr##w(buf *b, const char *p)                             \
+    { return (buf_putmem##w(b, p, strlen(p))); }
+BUF_DOSUFFIXES(BUF_PUTSTR_)
 
 /*----- That's all, folks -------------------------------------------------*/
diff --git a/buf.h b/buf.h
index 84c4121..924f096 100644 (file)
--- a/buf.h
+++ b/buf.h
@@ -9,26 +9,26 @@
 
 /*----- Licensing notice --------------------------------------------------* 
  *
- * This file is part of Catacomb.
+ * This file is part of the mLib utilities library.
  *
- * Catacomb is free software; you can redistribute it and/or modify
+ * mLib is free software; you can redistribute it and/or modify
  * it under the terms of the GNU Library General Public License as
  * published by the Free Software Foundation; either version 2 of the
  * License, or (at your option) any later version.
  * 
- * Catacomb is distributed in the hope that it will be useful,
+ * mLib is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  * GNU Library General Public License for more details.
  * 
  * You should have received a copy of the GNU Library General Public
- * License along with Catacomb; if not, write to the Free
+ * License along with mLib; if not, write to the Free
  * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
  * MA 02111-1307, USA.
  */
 
-#ifndef CATACOMB_BUF_H
-#define CATACOMB_BUF_H
+#ifndef MLIB_BUF_H
+#define MLIB_BUF_H
 
 #ifdef __cplusplus
   extern "C" {
 
 #include <stddef.h>
 
-#include <mLib/bits.h>
-
-#ifndef CATACOMB_MP_H
-#  include "mp.h"
+#ifndef MLIB_BITS_H
+#  include "bits.h"
 #endif
 
-#ifndef CATACOMB_EC_H
-#  include "ec.h"
+#ifndef MLIB_DSTR_H
+#  include "dstr.h"
 #endif
 
 /*----- Data structures ---------------------------------------------------*/
@@ -78,6 +76,8 @@ typedef struct buf {
 #define BENSURE(b, sz)                                                 \
   (BBAD(b) ? -1 : (sz) > BLEFT(b) ? (b)->f |= BF_BROKEN, -1 : 0)
 
+#define BUF_DOSUFFIXES(_) DOUINTCONV(_) _(z, z, z)
+
 /*----- Functions provided ------------------------------------------------*/
 
 /* --- @buf_init@ --- *
@@ -177,71 +177,51 @@ extern int buf_getbyte(buf */*b*/);
 
 extern int buf_putbyte(buf */*b*/, int /*ch*/);
 
-/* --- @buf_getu16@ --- *
+/* --- @buf_getu{8,{16,24,32,64}{,l,b}}@ --- *
  *
  * Arguments:  @buf *b@ = pointer to a buffer block
- *             @uint16 *w@ = where to put the word
+ *             @uintSZ *w@ = where to put the word
  *
  * Returns:    Zero if OK, or nonzero if there wasn't a word there.
  *
- * Use:                Gets a 16-bit word from a buffer.
- */
-
-extern int buf_getu16(buf */*b*/, uint16 */*w*/);
-
-/* --- @buf_putu16@ --- *
- *
- * Arguments:  @buf *b@ = pointer to a buffer block
- *             @uint16 w@ = word to write
- *
- * Returns:    Zero if OK, nonzero if there wasn't enough space.
- *
- * Use:                Puts a 16-but word in a buffer.
+ * Use:                Gets a word of appropriate size and order from a buffer.
  */
 
-extern int buf_putu16(buf */*b*/, uint16 /*w*/);
+#define BUF_DECL_GETU_(n, W, w)                                                \
+  extern int buf_getu##w(buf */*b*/, uint##n */*w*/);
+DOUINTCONV(BUF_DECL_GETU_)
 
-/* --- @buf_getu32@ --- *
+/* --- @buf_putu{8,{16,24,32,64}{,l,b}}@ --- *
  *
  * Arguments:  @buf *b@ = pointer to a buffer block
- *             @uint32 *w@ = where to put the word
+ *             @uintSZ w@ = word to write
  *
- * Returns:    Zero if OK, or nonzero if there wasn't a word there.
+ * Returns:    Zero if OK, or nonzero if there wasn't enough space
  *
- * Use:                Gets a 32-bit word from a buffer.
+ * Use:                Puts a word into a buffer with appropriate size and order.
  */
 
-extern int buf_getu32(buf */*b*/, uint32 */*w*/);
+#define BUF_DECL_PUTU_(n, W, w)                                                \
+  extern int buf_putu##w(buf */*b*/, uint##n /*w*/);
+DOUINTCONV(BUF_DECL_PUTU_)
 
-/* --- @buf_putu32@ --- *
- *
- * Arguments:  @buf *b@ = pointer to a buffer block
- *             @uint32 w@ = word to write
- *
- * Returns:    Zero if OK, nonzero if there wasn't enough space.
- *
- * Use:                Puts a 32-but word in a buffer.
- */
-
-extern int buf_putu32(buf */*b*/, uint32 /*w*/);
-
-/* --- @buf_getmem{8,16,32,z} --- *
+/* --- @buf_getmem{8,{16,24,32,64}{,l,b},z} --- *
  *
  * Arguments:  @buf *b@ = pointer to a buffer block
  *             @size_t *nn@ = where to put the length
  *
  * Returns:    Pointer to the buffer data, or null.
  *
- * Use:                Gets a chunk of memory from a buffer.  The number, @16@ or
- *             @32@, is the width of the length; @z@ means null-terminated.
+ * Use:                Gets a chunk of memory from a buffer.  The suffix is the
+ *             width and byte order of the length; @z@ means null-
+ *             terminated.
  */
 
-extern void *buf_getmem8(buf */*b*/, size_t */*nn*/);
-extern void *buf_getmem16(buf */*b*/, size_t */*nn*/);
-extern void *buf_getmem32(buf */*b*/, size_t */*nn*/);
-extern void *buf_getmemz(buf */*b*/, size_t */*nn*/);
+#define BUF_DECL_GETMEM_(n, W, w)                                      \
+  extern void *buf_getmem##w(buf */*b*/, size_t */*nn*/);
+BUF_DOSUFFIXES(BUF_DECL_GETMEM_)
 
-/* --- @buf_putmem{8,16,32,z} --- *
+/* --- @buf_putmem{8,{16,24,32,64}{,l,b},z} --- *
  *
  * Arguments:  @buf *b@ = pointer to a buffer block
  *             @const void *p@ = pointer to data to write
@@ -249,16 +229,16 @@ extern void *buf_getmemz(buf */*b*/, size_t */*nn*/);
  *
  * Returns:    Zero if OK, nonzero if there wasn't enough space.
  *
- * Use:                Writes a chunk of data to a buffer.  The number, @16@ or
- *             @32@, is the width of the length; @z@ means null-terminated.
+ * Use:                Writes a chunk of data to a buffer.  The suffix is the
+ *             width and byte order of the length; @z@ means null-
+ *             terminated.
  */
 
-extern int buf_putmem8(buf */*b*/, const void */*p*/, size_t /*n*/);
-extern int buf_putmem16(buf */*b*/, const void */*p*/, size_t /*n*/);
-extern int buf_putmem32(buf */*b*/, const void */*p*/, size_t /*n*/);
-extern int buf_putmemz(buf */*b*/, const void */*p*/, size_t /*n*/);
+#define BUF_DECL_PUTMEM_(n, W, w)                                      \
+  extern int buf_putmem##w(buf */*b*/, const void */*p*/, size_t /*nn*/);
+BUF_DOSUFFIXES(BUF_DECL_PUTMEM_)
 
-/* --- @buf_getbuf{8,16,32,z}@ --- *
+/* --- @buf_getbuf{8,{16,24,32,64}{,l,b},z} --- *
  *
  * Arguments:  @buf *b@ = pointer to a buffer block
  *             @buf *bb@ = where to put the result
@@ -266,33 +246,28 @@ extern int buf_putmemz(buf */*b*/, const void */*p*/, size_t /*n*/);
  * Returns:    Zero if it worked, nonzero if there wasn't enough space.
  *
  * Use:                Gets a block of data from a buffer, and writes its bounds to
- *             another buffer.  The number, @16@ or @32@, is the width of
- *             the length; @z@ means null-terminated.
+ *             another buffer.
  */
 
-extern int buf_getbuf8(buf */*b*/, buf */*bb*/);
-extern int buf_getbuf16(buf */*b*/, buf */*bb*/);
-extern int buf_getbuf32(buf */*b*/, buf */*bb*/);
-extern int buf_getbufz(buf */*b*/, buf */*bb*/);
+#define BUF_DECL_GETBUF_(n, W, w)                                      \
+  extern int buf_getbuf##w(buf */*b*/, buf */*bb*/);
+BUF_DOSUFFIXES(BUF_DECL_GETBUF_)
 
-/* --- @buf_putbuf{8,16,32,z}@ --- *
+/* --- @buf_putbuf{8,{16,24,32,64}{,l,b},z} --- *
  *
  * Arguments:  @buf *b@ = pointer to a buffer block
  *             @buf *bb@ = buffer to write
  *
  * Returns:    Zero if it worked, nonzero if there wasn't enough space.
  *
- * Use:                Puts the contents of a buffer to a buffer.  The number, @16@
- *             or @32@, is the width of the length; @z@ means null-
- *             terminated.
+ * Use:                Puts the contents of a buffer to a buffer.
  */
 
-extern int buf_putbuf8(buf */*b*/, buf */*bb*/);
-extern int buf_putbuf16(buf */*b*/, buf */*bb*/);
-extern int buf_putbuf32(buf */*b*/, buf */*bb*/);
-extern int buf_putbufz(buf */*b*/, buf */*bb*/);
+#define BUF_DECL_PUTBUF_(n, W, w)                                      \
+  extern int buf_putbuf##w(buf */*b*/, buf */*bb*/);
+BUF_DOSUFFIXES(BUF_DECL_PUTBUF_)
 
-/* --- @buf_getstr{8,16,32,z}@ --- *
+/* --- @buf_getdstr{8,{16,24,32,64}{,l,b},z} --- *
  *
  * Arguments:  @buf *b@ = pointer to a buffer block
  *             @dstr *d@ = where to put the result
@@ -300,80 +275,41 @@ extern int buf_putbufz(buf */*b*/, buf */*bb*/);
  * Returns:    Zero if it worked, nonzero if there wasn't enough space.
  *
  * Use:                Gets a block of data from a buffer, and writes its contents
- *             to a string.  The number, @16@ or @32@, is the width of the
- *             length; @z@ means null-terminated.
+ *             to a string.
  */
 
-extern int buf_getstr8(buf */*b*/, dstr */*d*/);
-extern int buf_getstr16(buf */*b*/, dstr */*d*/);
-extern int buf_getstr32(buf */*b*/, dstr */*d*/);
-extern int buf_getstrz(buf */*b*/, dstr */*d*/);
+#define BUF_DECL_GETDSTR_(n, W, w)                                     \
+  extern int buf_getdstr##w(buf */*b*/, dstr */*d*/);
+BUF_DOSUFFIXES(BUF_DECL_GETDSTR_)
 
-/* --- @buf_putstr{8,16,32,z}@ --- *
+/* --- @buf_putdstr{8,{16,24,32,64}{,l,b},z} --- *
  *
  * Arguments:  @buf *b@ = pointer to a buffer block
  *             @dstr *d@ = string to write
  *
  * Returns:    Zero if it worked, nonzero if there wasn't enough space.
  *
- * Use:                Puts a string to a buffer, and writes its bounds to
- *             another buffer.  The number, @16@ or @32@, is the width of
- *             the length; @z@ means null-terminated.
+ * Use:                Puts a dynamic string to a buffer.
  */
 
-extern int buf_putstr8(buf */*b*/, dstr */*d*/);
-extern int buf_putstr16(buf */*b*/, dstr */*d*/);
-extern int buf_putstr32(buf */*b*/, dstr */*d*/);
-extern int buf_putstrz(buf */*b*/, dstr */*d*/);
+#define BUF_DECL_PUTDSTR_(n, W, w)                                     \
+  extern int buf_putdstr##w(buf */*b*/, dstr */*d*/);
+BUF_DOSUFFIXES(BUF_DECL_PUTDSTR_)
 
-/* --- @buf_getmp@ --- *
+/* --- @buf_putstr{8,{16,24,32,64}{,l,b},z} --- *
  *
  * Arguments:  @buf *b@ = pointer to a buffer block
- *
- * Returns:    A multiprecision integer, or null if there wasn't one there.
- *
- * Use:                Gets a multiprecision integer from a buffer.
- */
-
-extern mp *buf_getmp(buf */*b*/);
-
-/* --- @buf_putmp@ --- *
- *
- * Arguments:  @buf *b@ = pointer to a buffer block
- *             @mp *m@ = a multiprecision integer
- *
- * Returns:    Zero if it worked, nonzero if there wasn't enough space.
- *
- * Use:                Puts a multiprecision integer to a buffer.
- */
-
-extern int buf_putmp(buf */*b*/, mp */*m*/);
-
-/* --- @buf_getec@ --- *
- *
- * Arguments:  @buf *b@ = pointer to a buffer block
- *             @ec *p@ = where to put the point
- *
- * Returns:    Zero if it worked, nonzero if it failed.
- *
- * Use:                Gets a multiprecision integer from a buffer.  The point must
- *             be initialized.
- */
-
-extern int buf_getec(buf */*b*/, ec */*p*/);
-
-/* --- @buf_putec@ --- *
- *
- * Arguments:  @buf *b@ = pointer to a buffer block
- *             @ec *p@ = an elliptic curve point
+ *             @const char *p@ = string to write
  *
  * Returns:    Zero if it worked, nonzero if there wasn't enough space.
  *
- * Use:                Puts an elliptic curve point to a buffer.
+ * Use:                Puts a null-terminated string to a buffer.
  */
 
-extern int buf_putec(buf */*b*/, ec */*p*/);
-
+#define BUF_DECL_PUTSTR_(n, W, w)                                      \
+  extern int buf_putstr##w(buf */*b*/, const char */*p*/);             \
+BUF_DOSUFFIXES(BUF_DECL_PUTSTR_)
+       
 /*----- That's all, folks -------------------------------------------------*/
 
 #ifdef __cplusplus
index cdf53fd..06ad53d 100644 (file)
@@ -65,5 +65,5 @@ allocation from the current arena
 .BR exc (3),
 .BR mLib (3).
 .SH AUTHOR
-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>
 
index f0268c0..2a36820 100644 (file)
@@ -124,4 +124,4 @@ specified by the ANSI C standard.
 .BR alloc (3),
 .BR mLib (3).
 .SH AUTHOR
-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>
index b9699e8..5b4ead0 100644 (file)
@@ -152,4 +152,4 @@ You don't need to call any functions beforehand.
 .BR sym (3),
 .BR mLib (3).
 .SH AUTHOR
-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>
index 446a46d..65c655a 100644 (file)
@@ -146,4 +146,4 @@ particular order.
 .BR hash (3),
 .BR mLib (3).
 .SH AUTHOR
-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>
index 3efab74..13d57c8 100644 (file)
@@ -92,4 +92,4 @@ automatically based on the input size.
 .BR hex (3),
 .BR mLib (3).
 .SH AUTHOR
-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>
index 4ab320a..9f5474a 100644 (file)
@@ -92,4 +92,4 @@ automatically based on the input size.
 .BR hex (3),
 .BR mLib (3).
 .SH AUTHOR
-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>
index b8ba8ad..fc2885d 100644 (file)
@@ -208,5 +208,5 @@ actually perform at all badly in real use.
 .SH "SEE ALSO"
 .BR mLib (3).
 .SH AUTHOR
-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>
 
index f6f790b..917ab9c 100644 (file)
@@ -128,4 +128,4 @@ to return the expected IP address, an error is reported.
 .BR sel (3),
 .BR mLib (3).
 .SH "AUTHOR"
-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>
diff --git a/man/buf.3 b/man/buf.3
new file mode 100644 (file)
index 0000000..64eba27
--- /dev/null
+++ b/man/buf.3
@@ -0,0 +1,406 @@
+.\" -*-nroff-*-
+.de VS
+.sp 1
+.RS
+.nf
+.ft B
+..
+.de VE
+.ft R
+.fi
+.RE
+.sp 1
+..
+.de hP
+.IP
+.ft B
+\h'-\w'\\$1\ 'u'\\$1\ \c
+.ft P
+..
+.ie t .ds o \(bu
+.el .ds o o
+.TH buf 3 "23 September 2005" "Straylight/Edgeware" "mLib utilities library"
+.SH NAME
+buf \- reading and writing stuff in buffers
+.\" @BBASE
+.\" @BLIM
+.\" @BCUR
+.\" @BSZ
+.\" @BLEN
+.\" @BLEFT
+.\" @BSTEP
+.\" @BBAD
+.\" @BOK
+.\" @BENSURE
+.
+.\" @buf_init
+.\" @buf_break
+.\" @buf_flip
+.\" @buf_ensure
+.\" @buf_get
+.\" @buf_put
+.
+.\" @buf_getbyte
+.\" @buf_putbyte
+.
+.\" @buf_getu8
+.\" @buf_getu16
+.\" @buf_getu16b
+.\" @buf_getu16l
+.\" @buf_getu24
+.\" @buf_getu24b
+.\" @buf_getu24l
+.\" @buf_getu32
+.\" @buf_getu32b
+.\" @buf_getu32l
+.
+.\" @buf_putu8
+.\" @buf_putu16
+.\" @buf_putu16b
+.\" @buf_putu16l
+.\" @buf_putu24
+.\" @buf_putu24b
+.\" @buf_putu24l
+.\" @buf_putu32
+.\" @buf_putu32b
+.\" @buf_putu32l
+.
+.\" @buf_getbuf8
+.\" @buf_getbuf16
+.\" @buf_getbuf16b
+.\" @buf_getbuf16l
+.\" @buf_getbuf24
+.\" @buf_getbuf24b
+.\" @buf_getbuf24l
+.\" @buf_getbuf32
+.\" @buf_getbuf32b
+.\" @buf_getbuf32l
+.\" @buf_getbufz
+.
+.\" @buf_putbuf8
+.\" @buf_putbuf16
+.\" @buf_putbuf16b
+.\" @buf_putbuf16l
+.\" @buf_putbuf24
+.\" @buf_putbuf24b
+.\" @buf_putbuf24l
+.\" @buf_putbuf32
+.\" @buf_putbuf32b
+.\" @buf_putbuf32l
+.\" @buf_putbufz
+.
+.\" @buf_getmem16
+.\" @buf_getmem16b
+.\" @buf_getmem16l
+.\" @buf_getmem24
+.\" @buf_getmem24b
+.\" @buf_getmem24l
+.\" @buf_getmem32
+.\" @buf_getmem32b
+.\" @buf_getmem32l
+.\" @buf_getmem8
+.\" @buf_getmemz
+.
+.\" @buf_putmem8
+.\" @buf_putmem16
+.\" @buf_putmem16b
+.\" @buf_putmem16l
+.\" @buf_putmem24
+.\" @buf_putmem24b
+.\" @buf_putmem24l
+.\" @buf_putmem32
+.\" @buf_putmem32b
+.\" @buf_putmem32l
+.\" @buf_putmemz
+.
+.\" @buf_putstr8
+.\" @buf_putstr16
+.\" @buf_putstr16b
+.\" @buf_putstr16l
+.\" @buf_putstr24
+.\" @buf_putstr24b
+.\" @buf_putstr24l
+.\" @buf_putstr32
+.\" @buf_putstr32b
+.\" @buf_putstr32l
+.\" @buf_putstrz
+.
+.\" @buf_getdstr8
+.\" @buf_getdstr16
+.\" @buf_getdstr16b
+.\" @buf_getdstr16l
+.\" @buf_getdstr24
+.\" @buf_getdstr24b
+.\" @buf_getdstr24l
+.\" @buf_getdstr32
+.\" @buf_getdstr32b
+.\" @buf_getdstr32l
+.\" @buf_getdstrz
+.
+.\" @buf_putdstr8
+.\" @buf_putdstr16
+.\" @buf_putdstr16b
+.\" @buf_putdstr16l
+.\" @buf_putdstr24
+.\" @buf_putdstr24b
+.\" @buf_putdstr24l
+.\" @buf_putdstr32
+.\" @buf_putdstr32b
+.\" @buf_putdstr32l
+.\" @buf_putdstrz
+.SH SYNOPSIS
+.nf
+.B "#include <mLib/dstr.h>"
+
+.BI "void buf_init(buf *" b ", void *" p ", size_t " sz );
+.BI "void buf_flip(buf *" b );
+.BI "octet *BBASE(buf *" b );
+.BI "octet *BLIM(buf *" b );
+.BI "octet *BCUR(buf *" b );
+.BI "ptrdiff_t BSZ(buf *" b );
+.BI "ptrdiff_t BLEN(buf *" b );
+.BI "ptrdiff_t BLEFT(buf *" b );
+
+.BI "int buf_break(buf *" b );
+.BI "int BBAD(buf *" b );
+.BI "int BOK(buf *" b );
+
+.BI "int buf_ensure(buf *" b ", size_t " sz );
+.BI "int BENSURE(buf *" b ", size_t " sz );
+.BI "octet *BSTEP(buf *" b );
+
+.BI "void *buf_get(buf *" b ", size_t " sz );
+.BI "void *buf_put(buf *" b ", const void *" p ", size_t " sz );
+
+.BI "int buf_getbyte(buf *" b );
+.BI "int buf_putbyte(buf *" b ", int ch" );
+.BI "int buf_getu" suff "(buf *" b ", uint" suff " *" w );
+.BI "int buf_putu" suff "(buf *" b ", uint" suff " " w );
+.BI "void *buf_getmem" suff "(buf *" b ", size_t *" sz );
+.BI "int buf_putmem" suff "(buf *" b ", const void *" p ", size_t " sz );
+.BI "int buf_getbuf" suff "(buf *" b ", buf *" bb );
+.BI "int buf_putbuf" suff "(buf *" b ", buf *" bb );
+.BI "int buf_getdstr" suff "(buf *" b ", dstr *" d );
+.BI "int buf_putdstr" suff "(buf *" b ", dstr *" d );
+.BI "int buf_putstr" suff "(buf *" b ", const char *" p );
+.fi
+.SH DESCRIPTION
+The
+.B buf
+interface allows relatively convenient reading and writing of structured
+binary data from and to fixed-size memory buffers.  It's useful for
+formatting and parsing down network data packets, for example.
+.SS "Buffer basics"
+A buffer has three important pointers associated with it:
+.TP
+.I base
+The base address of the buffer.
+.TP
+.I limit
+Just past the last usable byte in the buffer
+.TP
+.I current
+The position in the buffer at which the next read or write will occur.
+.PP
+A buffer is created using the
+.B buf_init
+function.  You must pass it the buffer base address and size, and a
+pointer to a 
+.B buf
+structure to fill in.  It doesn't allocate any memory, so you don't need
+to dispose of the
+.B buf
+structure in any way before forgetting about it.
+.PP
+A collection of macros is provided for finding the positions of the
+various interesting pointers known about a buffer, and the sizes of the
+regions of memory they imply.
+.TP
+.B BBASE
+The buffer's
+.I base
+pointer.
+.TP
+.B BLIM
+The buffer's
+.I limit
+pointer.
+.TP
+.B BCUR
+The buffer's
+.I current
+pointer.
+.TP
+.B BSZ
+The size of the buffer; i.e.,
+.I limit
+\-
+.IR base .
+.TP
+.B BLEN
+The length of data in the buffer (if writing) or the amount of data
+read (if reading); i.e., 
+.I current
+\-
+.IR base .
+.TP
+.B BLEFT
+The amount of space left in the buffer (if writing) or the amount of
+data yet to read (if reading); i.e.,
+.I limit
+\-
+.IR current .
+.PP
+The function
+.B buf_flip
+takes a buffer which has been used for writing, and makes it suitable
+for reading.  This turns out to be useful when building packets in
+multi-layered networking software.  Its precise behaviour is to preserve 
+.IR base ,
+to set
+.I limit
+to
+.IR current ,
+and to set 
+.I current
+to
+.IR base .
+.PP
+A buffer can be
+.IR broken ,
+to indicate that it has overflowed or that its contents are otherwise
+invalid.  The various buffer access functions described below all fail
+on a broken buffer, and any errors they encounter cause the buffer to
+become broken.  Most simple programs which only use the supplied buffer
+access functions can avoid the tedium of error-checking every function
+call and just check the brokenness state at the end of their run.
+.PP
+The function
+.B buf_break
+will break a buffer.  The macro
+.B BBAD
+reports true (nonzero) if its buffer argument is broken, or false (zero)
+otherwise; its counterpart
+.B BOK
+reports true if the buffer is OK, and false if it is broken.
+.SS "Low-level buffer access"
+Access to the data in the buffer is usually sequential.  The
+.B BENSURE
+macro (or the equivalent
+.B buf_ensure
+function) checks that the buffer is OK and that there is enough space
+remaining in the buffer for
+.I sz
+bytes: if so, it returns zero; otherwise it breaks the buffer and
+returns \-1.
+.PP
+The
+.B BSTEP
+macro advances the buffer's
+.I current
+pointer by
+.I sz
+bytes.  It does no bounds checking.  Together with
+.BR BENSURE ,
+this provides sequential access to the buffer's contents.
+.PP
+The
+.B buf_get
+function is the basis of most buffer access functions, whether for
+reading or writing.  If the buffer is OK, and there are
+.I sz
+or more bytes remaining, it steps the buffer's
+.I current
+pointer by
+.I sz
+and returns the 
+.I original
+(pre-stepping)
+.I current
+pointer; otherwise it breaks the buffer if necessary, and returns a null
+pointer.
+.PP
+The
+.B buf_put
+function writes 
+.I sz
+bytes of data starting at
+.I p
+to the buffer.  If it succeeded, it returns 0; otherwise it returns \-1.
+.SS "Formatted buffer access"
+The function
+.B buf_getbyte
+returns the next byte from a buffer as a nonnegative integer, or \-1 on
+error.  The function
+.B buf_putbyte
+writes its argument to a buffer, and returns 0 on succes; it returns \-1
+if it failed.
+.PP
+Many of the remaining functions deal with integer formatting and buffer
+lengths.  The functions support 8-, 16-, 24- and 32-bit integers, in
+big- or little-endian order; on platforms with 64-bit integers, these
+are supported too.  The functions' names carry a suffix which is the
+width in bits of the integers they deal with and an optional
+.RB ` l '
+for little- or
+.RB ` b '
+for big-endian byte order.  (The variant with no letter uses big-endian
+order.  Use of these variants tends to mean `I don't really care, but be
+consistent,' and is not recommended if you have an externally-defined
+spec you're meant to be compatible with.)
+.PP
+The function
+.BI buf_getu suff
+reads an integer.  On success, it stores the integer it read at the
+address
+.I w
+given, and returns zero; on failure, it returns \-1.  The function
+.BI buf_putu suff
+write an integer.  It returns zero on success or \-1 on failure.
+.PP
+Functions which deal with block lengths assume the length is prefixed to
+the data, and don't include themselves.  They also have an additional
+.RB ` z '
+variant, which deals with zero-terminated data.  No checks are done on
+writing that the data written contains no zero bytes.
+.PP
+The function
+.BI buf_getmem suff
+fetches a block of data.  On success, it returns its base address and
+stores its length at the given address; on failure, it returns null.
+The function
+.BI buf_putmem suff
+writes a block of data; it return zero on success or \-1 on failure.
+.PP
+The functon
+.BI buf_getbuf suff
+fetches a block of data and makes a second buffer point to it, i.e.,
+setting its
+.I base
+and
+.I current
+pointers to the start of the block and its
+.I limit
+pointer to just past the end.  No copying of bulk data is performed.
+The function
+.BI buf_putbuf suff
+writes the contents of a buffer (i.e., between its
+.I base
+and
+.I current
+pointers).  The function
+.BI buf_getdstr suff
+fetches a block of data and append it to a dynamic string (see
+.BR dstr (3)).
+The function
+.BI buf_putdstr suff
+writes the contents of a dynamic string to a buffer.  Finally, the
+function
+.BI buf_putstr suff
+writes a standard C null-terminated string to a buffer.  All these
+functions return zero on success or \-1 on failure.
+.SH "SEE ALSO"
+.BR dstr (3),
+.BR mLib (3).
+.SH AUTHOR
+Mark Wooding, <mdw@distorted.org.uk>
index 74a4604..02261b7 100644 (file)
@@ -120,4 +120,4 @@ the selector becomes safe to be discarded.
 .BR sel (3),
 .BR mLib (3).
 .SH AUTHOR
-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>
index 1e8bfb4..611a4c6 100644 (file)
@@ -163,5 +163,5 @@ an example of use, see the header file
 .I A painless guide to CRC error detection algorithms
 by Ross N. Williams.
 .SH "AUTHOR"
-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>
 
index dda3ad0..6eca843 100644 (file)
@@ -56,4 +56,4 @@ The return value is the 32-bit CRC of the input block.
 .BR unihash (3),
 .BR mLib (3).
 .SH AUTHOR
-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>
index db50fd1..8f7953c 100644 (file)
@@ -452,4 +452,4 @@ Reallocate the array to use the smallest amount of memory possible.
 .BR exc (3),
 .BR mLib (3).
 .SH "AUTHOR"
-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>
index 1b520c8..59e91b4 100644 (file)
@@ -91,4 +91,4 @@ is called before any strings are allocated from a string pool.
 .BR sub (3),
 .BR mLib (3).
 .SH AUTHOR
-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>
index 70d7292..b7c6cfb 100644 (file)
@@ -411,4 +411,4 @@ independent people who know what they're doing.
 .BR exc (3),
 .BR mLib (3).
 .SH AUTHOR
-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>
index b927ea2..1818b37 100644 (file)
--- a/man/env.3
+++ b/man/env.3
@@ -84,4 +84,4 @@ environment variables.
 .BR sym (3),
 .BR mLib (3).
 .SH "AUTHOR"
-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>
index dea64c3..d4c7eb9 100644 (file)
--- a/man/exc.3
+++ b/man/exc.3
@@ -264,4 +264,4 @@ recover from a signal.
 .SH "SEE ALSO"
 .BR mLib (3).
 .SH AUTHOR
-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>
index 4815488..81f3d83 100644 (file)
@@ -79,4 +79,4 @@ fdflags(fd, O_NONBLOCK, 0, FD_CLOEXEC, 0);
 .SH "SEE ALSO"
 .BR mLib (3).
 .SH "AUTHOR"
-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>
index 6a91ec1..c13859a 100644 (file)
@@ -51,4 +51,4 @@ and
 .BR mLib (3),
 .BR unix (7).
 .SH AUTHOR
-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>
index 20b9b84..c2329ea 100644 (file)
@@ -38,4 +38,4 @@ functions return zero if the file has not changed or nonzero if it has.
 .SH SEE ALSO
 .BR mLib (3).
 .SH AUTHOR
-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>
index d74edd4..5869d89 100644 (file)
@@ -291,4 +291,4 @@ The finalization code above contained an example of iteration.
 .BR sym (3),
 .BR mLib (3).
 .SH "AUTHOR"
-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>
index d4c4680..b4e58b5 100644 (file)
--- a/man/hex.3
+++ b/man/hex.3
@@ -88,4 +88,4 @@ Decoding ignores all whitespace characters in the encoded string.
 .BR dstr (3),
 .BR mLib (3).
 .SH AUTHOR
-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>
index 9486f92..5247bd4 100644 (file)
@@ -117,4 +117,4 @@ handler function.
 .BR sel (3),
 .BR mLib (3).
 .SH "AUTHOR"
-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>
index 29609fb..1c80f93 100644 (file)
@@ -237,4 +237,4 @@ general
 .BR selbuf (3),
 .BR mLib (3).
 .SH "AUTHOR"
-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>
index 2ef7860..75460b4 100644 (file)
@@ -58,4 +58,4 @@ is set to
 .BR fcntl (2),
 .BR mLib (3).
 .SH AUTHOR
-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>
index f7d5511..eab7780 100644 (file)
@@ -92,6 +92,11 @@ buffer-overflows.  Dynamic strings are used occasionally through the
 rest of the library, mainly as output arguments.
 .PP
 The
+.BR buf (3)
+module provides simple functions for reading and writing binary data to
+or from fixed-sized buffers.
+.PP
+The
 .BR dspool (3)
 module implements a `pool' of dynamic strings which saves lots of
 allocation and deallocation when a piece of code has high string
@@ -263,6 +268,7 @@ module does background hostname and address resolution.
 .BR atom (3),
 .BR base64 (3),
 .BR bits (3),
+.BR buf (3),
 .BR bres (3),
 .BR conn (3),
 .BR crc32 (3),
@@ -292,4 +298,4 @@ module does background hostname and address resolution.
 .BR tv (3),
 .BR url (3).
 .SH AUTHOR
-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>
index 93a58cb..962e81a 100644 (file)
@@ -17,4 +17,4 @@ macro returns the number of elements in the named
 .SH "SEE ALSO"
 .BR mLib (3).
 .SH "AUTHOR"
-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>
index 74dd15b..832f934 100644 (file)
@@ -430,4 +430,4 @@ function.
 .BR getopt (3),
 .BR mLib (3).
 .SH "AUTHOR"
-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>
index 4922b00..4bcc9d3 100644 (file)
@@ -222,4 +222,4 @@ general
 .BR selpk (3),
 .BR mLib (3).
 .SH "AUTHOR"
-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>
index 4c3dd5f..28e8012 100644 (file)
@@ -173,4 +173,4 @@ out; it's just not a disaster if you forget by accident.
 .BR mLib (3),
 .BR subarena (3).
 .SH AUTHOR
-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>
index ef510d6..bd19698 100644 (file)
@@ -61,4 +61,4 @@ functions.
 .BR report (3),
 .BR mLib (3).
 .SH AUTHOR
-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>
index 97b4ebc..1ccecb6 100644 (file)
@@ -41,4 +41,4 @@ program.
 .BR quis (3),
 .BR mLib (3).
 .SH AUTHOR
-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>
index eaf5b68..de62ed1 100644 (file)
--- a/man/sel.3
+++ b/man/sel.3
@@ -391,4 +391,4 @@ though.
 .BR selbuf (3),
 .BR mLib (3).
 .SH AUTHOR
-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>
index 5ff9f28..cdf561b 100644 (file)
@@ -103,4 +103,4 @@ calling
 .BR sel (3),
 .BR mLib (3).
 .SH AUTHOR
-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>
index 6502803..f0a56ee 100644 (file)
@@ -103,4 +103,4 @@ When it's finished with, a packet selector must be destroyed by calling
 .BR selbuf (3),
 .BR mLib (3).
 .SH AUTHOR
-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>
index 241c624..a176e12 100644 (file)
--- a/man/sig.3
+++ b/man/sig.3
@@ -90,4 +90,4 @@ The
 flag is also set, so that stopped child processes aren't reported by a
 signal.  This is normally right, but ought to be configurable.
 .SH "AUTHOR"
-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>
index 355bd8c..24a983c 100644 (file)
--- a/man/str.3
+++ b/man/str.3
@@ -195,4 +195,4 @@ will be null.
 .SH "SEE ALSO"
 .BR mLib (3).
 .SH AUTHOR
-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>
index ef61110..5251228 100644 (file)
--- a/man/sub.3
+++ b/man/sub.3
@@ -139,4 +139,4 @@ it's used.
 .BR alloc (3),
 .BR mLib (3).
 .SH AUTHOR
-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>
index 967d024..82953da 100644 (file)
--- a/man/sym.3
+++ b/man/sym.3
@@ -235,4 +235,4 @@ time.
 .BR hash (3),
 .BR mLib (3).
 .SH AUTHOR
-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>
index 190e732..c010cb0 100644 (file)
@@ -186,4 +186,4 @@ instead.
 .SH "SEE ALSO"
 .BR mLib (3).
 .SH "AUTHOR"
-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>
index 0318eb0..d1f08d7 100644 (file)
@@ -168,4 +168,4 @@ of course, the entire contents of the macro is ignored.
 .SH "SEE ALSO"
 .BR mLib (3).
 .SH "AUTHOR"
-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>
index 9196051..62d9189 100644 (file)
--- a/man/tv.3
+++ b/man/tv.3
@@ -171,4 +171,4 @@ document the restriction because I don't think it exists.)
 .SH "SEE ALSO"
 .BR mLib (3).
 .SH AUTHOR
-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>
index 94d2c44..74667bc 100644 (file)
@@ -116,5 +116,5 @@ which is, as far as the author knows, as good as any other fixed value.
 .BR crc-mktab (1),
 .BR unihash (3).
 .SH "AUTHOR"
-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>
 
index ddfb227..8e45c69 100644 (file)
@@ -194,4 +194,4 @@ construction to the security of its components).  It's just a fact.
 .BR crc32 (3),
 .BR mLib (3).
 .SH AUTHOR
-Mark Wooding (mdw@nsict.org).
+Mark Wooding (mdw@distorted.org.uk).
index a02443a..5a96403 100644 (file)
--- a/man/url.3
+++ b/man/url.3
@@ -124,4 +124,4 @@ void encode(sym_table *t, dstr *d)
 .SH "SEE ALSO"
 .BR mLib (3).
 .SH AUTHOR
-Mark Wooding, <mdw@nsict.org>.
+Mark Wooding, <mdw@distorted.org.uk>.