17 \h'-\w'\\$1\ 'u'\\$1\ \c
23 .TH buf 3 "23 September 2005" "Straylight/Edgeware" "mLib utilities library"
26 buf \- reading and writing stuff in buffers
409 .\" @dbuf_vputstrf16b
410 .\" @dbuf_vputstrf16l
412 .\" @dbuf_vputstrf24b
413 .\" @dbuf_vputstrf24l
415 .\" @dbuf_vputstrf32b
416 .\" @dbuf_vputstrf32l
418 .\" @dbuf_vputstrf64b
419 .\" @dbuf_vputstrf64l
441 .\" @DBUF_ENCLOSEITAG
442 .\" @DBUF_ENCLOSEKTAG
443 .\" @DBUF_ENCLOSEZTAG
446 .\" @DBUF_ENCLOSE16_L
447 .\" @DBUF_ENCLOSE16_B
449 .\" @DBUF_ENCLOSE24_L
450 .\" @DBUF_ENCLOSE24_B
452 .\" @DBUF_ENCLOSE32_L
453 .\" @DBUF_ENCLOSE32_B
455 .\" @DBUF_ENCLOSE64_L
456 .\" @DBUF_ENCLOSE64_B
461 .B "#include <mLib/dstr.h>"
463 .B "typedef struct { ...\& } buf;"
464 .B "typedef struct { ...\& } dbuf;"
466 .BI "void buf_init(buf *" b ", void *" p ", size_t " sz );
467 .BI "void dbuf_create(dbuf *" db );
468 .BI "void dbuf_reset(dbuf *" db );
469 .BI "void dbuf_destroy(dbuf *" db );
470 .BI "buf *DBUF_BUF(dbuf *" db );
471 .BI "void DBCREATE(dbuf *" db );
472 .BI "void DBRESET(dbuf *" db );
473 .BI "void DBDESTROY(dbuf *" db );
474 .B "#define DBUF_INIT ..."
477 All of the following functions and macros exist in two variants:
478 one with a name beginning
483 and taking a first argument of type
485 and a corresponding similarly named version with name beginning instead
490 and taking a first argument of type
494 .BI "void buf_flip(buf *" b );
495 .BI "octet *BBASE(buf *" b );
496 .BI "octet *BLIM(buf *" b );
497 .BI "octet *BCUR(buf *" b );
498 .BI "ptrdiff_t BSZ(buf *" b );
499 .BI "ptrdiff_t BLEN(buf *" b );
500 .BI "ptrdiff_t BLEFT(buf *" b );
501 .BI "void BFLIP(buf *" b );
503 .BI "int buf_break(buf *" b );
504 .BI "int BBREAK(buf *" b );
505 .BI "int BBAD(buf *" b );
506 .BI "int BOK(buf *" b );
508 .BI "int buf_ensure(buf *" b ", size_t " sz );
509 .BI "int buf_tryextend(buf *" b ", size_t " sz );
510 .BI "int BENSURE(buf *" b ", size_t " sz );
511 .BI "octet *BSTEP(buf *" b ", size_t " sz );
513 .BI "void *buf_get(buf *" b ", size_t " sz );
514 .BI "void *buf_put(buf *" b ", const void *" p ", size_t " sz );
516 .BI "int buf_getbyte(buf *" b );
517 .BI "int buf_putbyte(buf *" b ", int " ch );
519 .BI "int buf_putstr(buf *" b ", const char *" p ", ...);"
520 .BI "int buf_vputstr(buf *" b ", const char *" p ", va_list *" ap );
537 and, if a 64-bit integer type is available,
543 .BI "int buf_putu" suff "(buf *" b ", uint" suff " " w );
544 .BI "int buf_getu" suff "(buf *" b ", uint" suff " *" w );
555 .BI "int buf_putk" suff "(buf *" b ", kludge64 " w );
556 .BI "int buf_getk" suff "(buf *" b ", kludge64 *" w );
559 .BI "BUF_ENCLOSETAG(" tag ", buf *" b ", size_t " mk ", " check ", " poke ", size_t " lensz )
561 .BI "BUF_ENCLOSEITAG(" tag ", buf *" b ", size_t " mk ", " W )
563 .BI "BUF_ENCLOSEKTAG(" tag ", buf *" b ", size_t " mk ", " W )
565 .BI "BUF_ENCLOSEZTAG(" tag ", buf *" b )
588 .BI "BUF_ENCLOSE" suff "(buf *" b ", size_t " mk )
591 .BI "BUF_ENCLOSEZ(buf *" b )
614 .BI "int buf_putstr" suff "(buf *" b ", const char *" p );
615 .BI "int dbuf_putstr" suff "(dbuf *" db ", const char *" p );
616 .BI "int buf_putstr" suff "(buf *" b ", const char *" p ", ...);"
617 .BI "int dbuf_putstr" suff "(dbuf *" db ", const char *" p ", ...);"
618 .BI "int buf_vputstr" suff "(buf *" b ", const char *" p ", va_list *" ap );
619 .BI "int dbuf_vputstr" suff "(dbuf *" db ", const char *" p ", va_list *" ap );
620 .BI "int buf_putdstr" suff "(buf *" b ", dstr *" d );
621 .BI "int dbuf_putdstr" suff "(dbuf *" db ", dstr *" d );
622 .BI "int buf_getdstr" suff "(buf *" b ", dstr *" d );
623 .BI "int dbuf_getdstr" suff "(dbuf *" db ", dstr *" d );
624 .BI "int buf_putbuf" suff "(buf *" b ", buf *" bb );
625 .BI "int dbuf_putbuf" suff "(dbuf *" db ", buf *" bb );
626 .BI "int buf_getbuf" suff "(buf *" b ", buf *" bb );
627 .BI "int dbuf_getbuf" suff "(dbuf *" db ", buf *" bb );
628 .BI "int buf_putmem" suff "(buf *" b ", const void *" p ", size_t " sz );
629 .BI "int dbuf_putmem" suff "(dbuf *" db ", const void *" p ", size_t " sz );
630 .BI "void *buf_getmem" suff "(buf *" b ", size_t *" sz );
631 .BI "void d*buf_getmem" suff "(dbuf *" db ", size_t *" sz );
642 .BI "int buf_putf" suff "(buf *" b ", double " x );
643 .BI "int dbuf_putf" suff "(dbuf *" db ", double " x );
644 .BI "int buf_getf" suff "(buf *" b ", double *" x );
645 .BI "int dbuf_getf" suff "(dbuf *" db ", double *" x );
651 interface allows relatively convenient reading and writing of structured
652 binary data from and to fixed-size memory buffers. It's useful for
653 formatting and parsing down network data packets, for example.
656 A buffer has three important pointers associated with it:
659 The base address of the buffer.
662 Just past the last usable byte in the buffer
665 The position in the buffer at which the next read or write will occur.
667 A buffer is created using the
669 function. You must pass it the buffer base address and size, and a
672 structure to fill in. It doesn't allocate any memory, so you don't need
675 structure in any way before forgetting about it.
677 A collection of macros is provided for finding the positions of the
678 various interesting pointers known about a buffer, and the sizes of the
679 regions of memory they imply.
697 The size of the buffer; i.e.,
703 The length of data in the buffer (if writing) or the amount of data
704 read (if reading); i.e.,
710 The amount of space left in the buffer (if writing) or the amount of
711 data yet to read (if reading); i.e.,
718 takes a buffer which has been used for writing, and makes it suitable
719 for reading. This turns out to be useful when building packets in
720 multi-layered networking software. Its precise behaviour is to preserve
730 There is a macro version,
732 which does the same thing,
733 but it may evaluate its buffer argument multiple times.
737 to indicate that it has overflowed or that its contents are otherwise
738 invalid. The various buffer access functions described below all fail
739 on a broken buffer, and any errors they encounter cause the buffer to
740 become broken. Most simple programs which only use the supplied buffer
741 access functions can avoid the tedium of error-checking every function
742 call and just check the brokenness state at the end of their run.
750 the function returns \-1 as a possible, but minor, convenience;
751 the macro expands to a statement and cannot return a value.
754 reports true (nonzero) if its buffer argument is broken, or false (zero)
755 otherwise; its counterpart
757 reports true if the buffer is OK, and false if it is broken.
759 .SS "Low-level buffer access"
760 Access to the data in the buffer is usually sequential. The
762 macro (or the equivalent
764 function) checks that the buffer is OK and that there is enough space
765 remaining in the buffer for
767 bytes: if so, it returns zero; otherwise it breaks the buffer and
772 macro advances the buffer's
776 bytes. It does no bounds checking. Together with
778 this provides sequential access to the buffer's contents.
782 function is the basis of most buffer access functions, whether for
783 reading or writing. If the buffer is OK, and there are
785 or more bytes remaining, it steps the buffer's
793 pointer; otherwise it breaks the buffer if necessary, and returns a null
800 bytes of data starting at
802 to the buffer. If it succeeded, it returns 0; otherwise it returns \-1.
804 .SS "Formatted buffer access"
807 returns the next byte from a buffer as a nonnegative integer, or \-1 on
810 writes its argument to a buffer, and returns 0 on succes; it returns \-1
813 Many of the remaining functions deal with integer formatting and buffer
814 lengths. The functions support 8-, 16-, 24- and 32-bit integers, in
815 big- or little-endian order; on platforms with 64-bit integers, these
816 are supported too. The functions' names carry a suffix which is the
817 width in bits of the integers they deal with and an optional
821 for big-endian byte order. (The variant with no letter uses big-endian
822 order. Use of these variants tends to mean `I don't really care, but be
823 consistent,' and is not recommended if you have an externally-defined
824 spec you're meant to be compatible with.)
828 reads an integer. On success, it stores the integer it read at the
831 given, and returns zero; on failure, it returns \-1. The function
833 write an integer. It returns zero on success or \-1 on failure.
835 For (portability to) platforms without 64-bit integers, the functions
843 variants) perform the necessary functionality, but acting on the
853 read 64-bit floating-point values
854 in IEEE\ 754 Binary64 format
856 as usual, the suffix indicates the byte ordering convention.
857 On success, they store the result in
860 on failure, they break the buffer and return zero.
866 write floating-point numbers
867 in IEEE\ 754 Binary64 format
869 On success, they return zero; on failure, they return \-1.
870 Note that these functions use IEEE\ 754 format
871 even if this is not the platform-native floating-point representation.
877 format string and arguments,
878 writing the output to the buffer.
882 except that it reads arguments from a
884 captured argument tail,
885 leaving the tail ready to read the next unprocessed argument.
886 Both functions return the number of bytes written on success
888 Note that these functions apply no length framing or termination.
890 Functions which deal with block lengths assume the length is prefixed to
891 the data, and don't include themselves. They come in all of the integer
892 size variants, including 64-bits even on platforms without 64-bit integers;
893 they also have an additional
895 variant, which deals with zero-terminated data. No checks are done on
896 writing that the data written contains no zero bytes.
900 fetches a block of data. On success, it returns its base address and
901 stores its length at the given address; on failure, it returns null.
904 writes a block of data; it return zero on success or \-1 on failure.
908 fetches a block of data and makes a second buffer point to it, i.e.,
913 pointers to the start of the block and its
915 pointer to just past the end. No copying of bulk data is performed.
918 writes the contents of a buffer (i.e., between its
922 pointers). The function
924 fetches a block of data and append it to a dynamic string (see
928 writes the contents of a dynamic string to a buffer. Finally, the
931 writes a standard C null-terminated string to a buffer. All these
932 functions return zero on success or \-1 on failure.
938 format string and arguments,
939 writing the output to the buffer.
941 .BI buf_vputstrf suff
943 except that it reads arguments from a
945 captured argument tail,
946 leaving the tail ready to read the next unprocessed argument.
947 Both functions return the number of bytes written on success
949 These functions add framing around the output:
950 either a length prefix, or a trailing zero byte.
954 macros are syntactically statement heads.
955 (Notice that these macros use
959 suffixes for little- and big-endian byte order.)
960 They leave space in the buffer for appropriate length framing,
961 and execute the following
964 (which, of course, can be a compound statement enclosed in braces).
967 completes, the macro fills in space
968 with the length of material written by the
972 argument should be a variable of type
974 which will be overwritten by the macro.
975 If the material is so large that its won't fit in the space
976 then the buffer is broken.
980 except that it just writes a terminating zero byte
981 after whatever material was written by the
985 .BR BUF_ENCLOSE ...\&
986 macros are based on lower-level machinery.
989 macro takes an additional argument
993 bytes for the length,
994 checks that the length doesn't exceed
996 and stores the length using
998 all of these constants and macros are defined in
1002 is similar, except that it uses the
1004 machinery to handle 64-bit length fields.
1007 macro is superficially similar,
1009 since it all it does is write a zero byte after its
1012 All of those macros also take an additional
1015 used to scope the internal labels they construct:
1018 for the details on how this works.
1024 macros are themselves built from a lower-level macro named
1025 .BR BUF_ENCLOSETAG .
1028 argument, it takes three arguments:
1030 is an expression which should evaluate true if the length
1034 is a macro, invoked as
1035 .IB poke "(unsigned char *" p ", " size_t n ")" \fR,
1040 formatted in whatever way is appropriate;
1043 is the amount of space, in bytes, to save for the length.
1045 .SS "Dynamic buffers"
1049 .IR "dynamic buffer" .
1050 It contains a buffer structure,
1051 accessible using the
1054 The ordinary buffer functions and macros can be used on this buffer,
1055 though, for convenience,
1056 there are similarly named functions and macros
1062 between the behaviour of the
1068 A dynamic buffer is created by statically initializing it with
1072 or its macro equivalent
1074 The memory backing a dynamic buffer can be freed by
1076 or the macro equivalent
1078 these leave the buffer in the state established by initialization:
1079 the buffer holds no resources, but is ready for immediate use.
1081 A dynamic buffer contains an
1087 The underlying buffer is accessible through the
1090 All of the above functions and macros can be applied
1091 to a dynamic buffer's underlying buffer.
1093 corresponding to each of the functions and macros described above,
1094 there is a version named with an initial
1099 which accepts a pointer to a dynamic buffer
1100 rather than an ordinary buffer,
1101 and acts on its underlying buffer.
1102 Note that these functions are in no way special.
1103 A dynamic buffer will grow automatically
1104 in response to either kind of functions.
1106 A freshly created buffer is in
1110 In this state, it will automatically extend its backing storage
1113 calls, rather than breaking.
1117 unpredictable amount of data can be written to a dynamic buffer
1118 and it will automatically grow as necessary to accommodate it.
1123 queries are somewhat meaningless when applied to dynamic buffers \(en
1124 though perfectly valid.
1125 The critical function for this is
1128 .BR dbuf_tryextend )
1129 which attempts to arrange that at least
1131 unused bytes are available in the buffer \(en
1134 would return at least
1136 If it succeeds, it returns zero;
1137 it will fail if the buffer is not in write mode,
1138 or if the buffer is not dynamic,
1139 in which case it returns \-1.
1140 It is unlikely that applications will call this function directly.
1144 (or its macro equivalent)
1145 switches the buffer to
1148 in addition to its usual behaviour of
1149 setting the buffer's limit to its current position
1150 and its current position to its base.
1151 In read mode, a dynamic buffer will no longer grow dynamically,
1152 as one would expect.
1157 and its macro equivalent
1159 (which may evaluate its argument multiple times)
1160 will return a dynamic buffer to write mode,
1161 and also restore its current position to its base and
1162 clear its broken flag.
1171 Mark Wooding, <mdw@distorted.org.uk>
~mdw / mLib / blob