3 .\" Manual for buffer handling
5 .\" (c) 2005, 2007, 2009, 2017, 2023, 2024 Straylight/Edgeware
8 .\"----- Licensing notice ---------------------------------------------------
10 .\" This file is part of the mLib utilities library.
12 .\" mLib is free software: you can redistribute it and/or modify it under
13 .\" the terms of the GNU Library General Public License as published by
14 .\" the Free Software Foundation; either version 2 of the License, or (at
15 .\" your option) any later version.
17 .\" mLib is distributed in the hope that it will be useful, but WITHOUT
18 .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
19 .\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
20 .\" License for more details.
22 .\" You should have received a copy of the GNU Library General Public
23 .\" License along with mLib. If not, write to the Free Software
24 .\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
27 .\"--------------------------------------------------------------------------
28 .so ../defs.man \" @@@PRE@@@
30 .\"--------------------------------------------------------------------------
31 .TH buf 3mLib "23 September 2005" "Straylight/Edgeware" "mLib utilities library"
415 .\" @dbuf_vputstrf16b
416 .\" @dbuf_vputstrf16l
418 .\" @dbuf_vputstrf24b
419 .\" @dbuf_vputstrf24l
421 .\" @dbuf_vputstrf32b
422 .\" @dbuf_vputstrf32l
424 .\" @dbuf_vputstrf64b
425 .\" @dbuf_vputstrf64l
447 .\" @DBUF_ENCLOSEITAG
448 .\" @DBUF_ENCLOSEKTAG
449 .\" @DBUF_ENCLOSEZTAG
452 .\" @DBUF_ENCLOSE16_L
453 .\" @DBUF_ENCLOSE16_B
455 .\" @DBUF_ENCLOSE24_L
456 .\" @DBUF_ENCLOSE24_B
458 .\" @DBUF_ENCLOSE32_L
459 .\" @DBUF_ENCLOSE32_B
461 .\" @DBUF_ENCLOSE64_L
462 .\" @DBUF_ENCLOSE64_B
465 .\"--------------------------------------------------------------------------
467 buf \- reading and writing stuff in buffers
469 .\"--------------------------------------------------------------------------
473 .B "#include <mLib/dstr.h>"
475 .B "typedef struct { ...\& } buf;"
476 .B "typedef struct { ...\& } dbuf;"
478 .BI "void buf_init(buf *" b ", void *" p ", size_t " sz );
479 .BI "void dbuf_create(dbuf *" db );
480 .BI "void dbuf_reset(dbuf *" db );
481 .BI "void dbuf_destroy(dbuf *" db );
482 .BI "buf *DBUF_BUF(dbuf *" db );
483 .BI "void DBCREATE(dbuf *" db );
484 .BI "void DBRESET(dbuf *" db );
485 .BI "void DBDESTROY(dbuf *" db );
486 .B "#define DBUF_INIT ..."
489 All of the following functions and macros exist in two variants:
490 one with a name beginning
495 and taking a first argument of type
497 and a corresponding similarly named version with name beginning instead
502 and taking a first argument of type
506 .BI "void buf_flip(buf *" b );
507 .BI "octet *BBASE(buf *" b );
508 .BI "octet *BLIM(buf *" b );
509 .BI "octet *BCUR(buf *" b );
510 .BI "ptrdiff_t BSZ(buf *" b );
511 .BI "ptrdiff_t BLEN(buf *" b );
512 .BI "ptrdiff_t BLEFT(buf *" b );
513 .BI "void BFLIP(buf *" b );
515 .BI "int buf_break(buf *" b );
516 .BI "int BBREAK(buf *" b );
517 .BI "int BBAD(buf *" b );
518 .BI "int BOK(buf *" b );
520 .BI "int buf_ensure(buf *" b ", size_t " sz );
521 .BI "int buf_tryextend(buf *" b ", size_t " sz );
522 .BI "int BENSURE(buf *" b ", size_t " sz );
523 .BI "octet *BSTEP(buf *" b ", size_t " sz );
525 .BI "void *buf_get(buf *" b ", size_t " sz );
526 .BI "void *buf_put(buf *" b ", const void *" p ", size_t " sz );
528 .BI "int buf_getbyte(buf *" b );
529 .BI "int buf_putbyte(buf *" b ", int " ch );
531 .BI "int buf_putstr(buf *" b ", const char *" p ", ...);"
532 .BI "int buf_vputstr(buf *" b ", const char *" p ", va_list *" ap );
549 and, if a 64-bit integer type is available,
555 .BI "int buf_putu" suff "(buf *" b ", uint" suff " " w );
556 .BI "int buf_getu" suff "(buf *" b ", uint" suff " *" w );
567 .BI "int buf_putk" suff "(buf *" b ", kludge64 " w );
568 .BI "int buf_getk" suff "(buf *" b ", kludge64 *" w );
571 .BI "BUF_ENCLOSETAG(" tag ", buf *" b ", size_t " mk ", " check ", " poke ", size_t " lensz )
573 .BI "BUF_ENCLOSEITAG(" tag ", buf *" b ", size_t " mk ", " W )
575 .BI "BUF_ENCLOSEKTAG(" tag ", buf *" b ", size_t " mk ", " W )
577 .BI "BUF_ENCLOSEZTAG(" tag ", buf *" b )
600 .BI "BUF_ENCLOSE" suff "(buf *" b ", size_t " mk )
603 .BI "BUF_ENCLOSEZ(buf *" b )
626 .BI "int buf_putstr" suff "(buf *" b ", const char *" p );
627 .BI "int dbuf_putstr" suff "(dbuf *" db ", const char *" p );
628 .BI "int buf_putstr" suff "(buf *" b ", const char *" p ", ...);"
629 .BI "int dbuf_putstr" suff "(dbuf *" db ", const char *" p ", ...);"
630 .BI "int buf_vputstr" suff "(buf *" b ", const char *" p ", va_list *" ap );
631 .BI "int dbuf_vputstr" suff "(dbuf *" db ", const char *" p ", va_list *" ap );
632 .BI "int buf_putdstr" suff "(buf *" b ", dstr *" d );
633 .BI "int dbuf_putdstr" suff "(dbuf *" db ", dstr *" d );
634 .BI "int buf_getdstr" suff "(buf *" b ", dstr *" d );
635 .BI "int dbuf_getdstr" suff "(dbuf *" db ", dstr *" d );
636 .BI "int buf_putbuf" suff "(buf *" b ", buf *" bb );
637 .BI "int dbuf_putbuf" suff "(dbuf *" db ", buf *" bb );
638 .BI "int buf_getbuf" suff "(buf *" b ", buf *" bb );
639 .BI "int dbuf_getbuf" suff "(dbuf *" db ", buf *" bb );
640 .BI "int buf_putmem" suff "(buf *" b ", const void *" p ", size_t " sz );
641 .BI "int dbuf_putmem" suff "(dbuf *" db ", const void *" p ", size_t " sz );
642 .BI "void *buf_getmem" suff "(buf *" b ", size_t *" sz );
643 .BI "void d*buf_getmem" suff "(dbuf *" db ", size_t *" sz );
654 .BI "int buf_putf" suff "(buf *" b ", double " x );
655 .BI "int dbuf_putf" suff "(dbuf *" db ", double " x );
656 .BI "int buf_getf" suff "(buf *" b ", double *" x );
657 .BI "int dbuf_getf" suff "(dbuf *" db ", double *" x );
660 .\"--------------------------------------------------------------------------
664 interface allows relatively convenient reading and writing of structured
665 binary data from and to fixed-size memory buffers. It's useful for
666 formatting and parsing down network data packets, for example.
669 A buffer has three important pointers associated with it:
672 The base address of the buffer.
675 Just past the last usable byte in the buffer
678 The position in the buffer at which the next read or write will occur.
680 A buffer is created using the
682 function. You must pass it the buffer base address and size, and a
685 structure to fill in. It doesn't allocate any memory, so you don't need
688 structure in any way before forgetting about it.
690 A collection of macros is provided for finding the positions of the
691 various interesting pointers known about a buffer, and the sizes of the
692 regions of memory they imply.
710 The size of the buffer; i.e.,
716 The length of data in the buffer (if writing) or the amount of data
717 read (if reading); i.e.,
723 The amount of space left in the buffer (if writing) or the amount of
724 data yet to read (if reading); i.e.,
731 takes a buffer which has been used for writing, and makes it suitable
732 for reading. This turns out to be useful when building packets in
733 multi-layered networking software. Its precise behaviour is to preserve
743 There is a macro version,
745 which does the same thing,
746 but it may evaluate its buffer argument multiple times.
750 to indicate that it has overflowed or that its contents are otherwise
751 invalid. The various buffer access functions described below all fail
752 on a broken buffer, and any errors they encounter cause the buffer to
753 become broken. Most simple programs which only use the supplied buffer
754 access functions can avoid the tedium of error-checking every function
755 call and just check the brokenness state at the end of their run.
763 the function returns \-1 as a possible, but minor, convenience;
764 the macro expands to a statement and cannot return a value.
767 reports true (nonzero) if its buffer argument is broken, or false (zero)
768 otherwise; its counterpart
770 reports true if the buffer is OK, and false if it is broken.
772 .SS "Low-level buffer access"
773 Access to the data in the buffer is usually sequential. The
775 macro (or the equivalent
777 function) checks that the buffer is OK and that there is enough space
778 remaining in the buffer for
780 bytes: if so, it returns zero; otherwise it breaks the buffer and
785 macro advances the buffer's
789 bytes. It does no bounds checking. Together with
791 this provides sequential access to the buffer's contents.
795 function is the basis of most buffer access functions, whether for
796 reading or writing. If the buffer is OK, and there are
798 or more bytes remaining, it steps the buffer's
806 pointer; otherwise it breaks the buffer if necessary, and returns a null
813 bytes of data starting at
815 to the buffer. If it succeeded, it returns 0; otherwise it returns \-1.
817 .SS "Formatted buffer access"
820 returns the next byte from a buffer as a nonnegative integer, or \-1 on
823 writes its argument to a buffer, and returns 0 on succes; it returns \-1
826 Many of the remaining functions deal with integer formatting and buffer
827 lengths. The functions support 8-, 16-, 24- and 32-bit integers, in
828 big- or little-endian order; on platforms with 64-bit integers, these
829 are supported too. The functions' names carry a suffix which is the
830 width in bits of the integers they deal with and an optional
834 for big-endian byte order. (The variant with no letter uses big-endian
835 order. Use of these variants tends to mean `I don't really care, but be
836 consistent,' and is not recommended if you have an externally-defined
837 spec you're meant to be compatible with.)
841 reads an integer. On success, it stores the integer it read at the
844 given, and returns zero; on failure, it returns \-1. The function
846 write an integer. It returns zero on success or \-1 on failure.
848 For (portability to) platforms without 64-bit integers, the functions
856 variants) perform the necessary functionality, but acting on the
866 read 64-bit floating-point values
867 in IEEE\ 754 Binary64 format
869 as usual, the suffix indicates the byte ordering convention.
870 On success, they store the result in
873 on failure, they break the buffer and return zero.
879 write floating-point numbers
880 in IEEE\ 754 Binary64 format
882 On success, they return zero; on failure, they return \-1.
883 Note that these functions use IEEE\ 754 format
884 even if this is not the platform-native floating-point representation.
890 format string and arguments,
891 writing the output to the buffer.
895 except that it reads arguments from a
897 captured argument tail,
898 leaving the tail ready to read the next unprocessed argument.
899 Both functions return the number of bytes written on success
901 Note that these functions apply no length framing or termination.
902 They are implemented using
904 the output operations table is exposed as
906 the functions expect the output pointer to be the address of the output
909 Functions which deal with block lengths assume the length is prefixed to
910 the data, and don't include themselves. They come in all of the integer
911 size variants, including 64-bits even on platforms without 64-bit integers;
912 they also have an additional
914 variant, which deals with zero-terminated data. No checks are done on
915 writing that the data written contains no zero bytes.
919 fetches a block of data. On success, it returns its base address and
920 stores its length at the given address; on failure, it returns null.
923 writes a block of data; it return zero on success or \-1 on failure.
927 fetches a block of data and makes a second buffer point to it, i.e.,
932 pointers to the start of the block and its
934 pointer to just past the end. No copying of bulk data is performed.
937 writes the contents of a buffer (i.e., between its
941 pointers). The function
943 fetches a block of data and append it to a dynamic string (see
947 writes the contents of a dynamic string to a buffer. Finally, the
950 writes a standard C null-terminated string to a buffer. All these
951 functions return zero on success or \-1 on failure.
957 format string and arguments,
958 writing the output to the buffer.
960 .BI buf_vputstrf suff
962 except that it reads arguments from a
964 captured argument tail,
965 leaving the tail ready to read the next unprocessed argument.
966 Both functions return the number of bytes written on success
968 These functions add framing around the output:
969 either a length prefix, or a trailing zero byte.
973 macros are syntactically statement heads.
974 (Notice that these macros use
978 suffixes for little- and big-endian byte order.)
979 They leave space in the buffer for appropriate length framing,
980 and execute the following
983 (which, of course, can be a compound statement enclosed in braces).
986 completes, the macro fills in space
987 with the length of material written by the
991 argument should be a variable of type
993 which will be overwritten by the macro.
994 If the material is so large that its won't fit in the space
995 then the buffer is broken.
999 except that it just writes a terminating zero byte
1000 after whatever material was written by the
1004 .BR BUF_ENCLOSE ...\&
1005 macros are based on lower-level machinery.
1008 macro takes an additional argument
1012 bytes for the length,
1013 checks that the length doesn't exceed
1015 and stores the length using
1017 all of these constants and macros are defined in
1021 is similar, except that it uses the
1023 machinery to handle 64-bit length fields.
1026 macro is superficially similar,
1028 since it all it does is write a zero byte after its
1031 All of those macros also take an additional
1034 used to scope the internal labels they construct:
1037 for the details on how this works.
1043 macros are themselves built from a lower-level macro named
1044 .BR BUF_ENCLOSETAG .
1047 argument, it takes three arguments:
1049 is an expression which should evaluate true if the length
1053 is a macro, invoked as
1054 .IB poke "(unsigned char *" p ", " size_t n ")" \fR,
1059 formatted in whatever way is appropriate;
1062 is the amount of space, in bytes, to save for the length.
1064 .SS "Dynamic buffers"
1068 .IR "dynamic buffer" .
1069 It contains a buffer structure,
1070 accessible using the
1073 The ordinary buffer functions and macros can be used on this buffer,
1074 though, for convenience,
1075 there are similarly named functions and macros
1081 between the behaviour of the
1087 A dynamic buffer is created by statically initializing it with
1091 or its macro equivalent
1093 The memory backing a dynamic buffer can be freed by
1095 or the macro equivalent
1097 these leave the buffer in the state established by initialization:
1098 the buffer holds no resources, but is ready for immediate use.
1100 A dynamic buffer contains a
1106 The underlying buffer is accessible through the
1109 All of the above functions and macros can be applied
1110 to a dynamic buffer's underlying buffer.
1112 corresponding to each of the functions and macros described above,
1113 there is a version named with an initial
1118 which accepts a pointer to a dynamic buffer
1119 rather than an ordinary buffer,
1120 and acts on its underlying buffer.
1121 Note that these functions are in no way special.
1122 A dynamic buffer will grow automatically
1123 in response to either kind of functions.
1125 A freshly created buffer is in
1129 In this state, it will automatically extend its backing storage
1132 calls, rather than breaking.
1136 unpredictable amount of data can be written to a dynamic buffer
1137 and it will automatically grow as necessary to accommodate it.
1142 queries are somewhat meaningless when applied to dynamic buffers \(en
1143 though perfectly valid.
1144 The critical function for this is
1147 .BR dbuf_tryextend )
1148 which attempts to arrange that at least
1150 unused bytes are available in the buffer \(en
1153 would return at least
1155 If it succeeds, it returns zero;
1156 it will fail if the buffer is not in write mode,
1157 or if the buffer is not dynamic,
1158 in which case it returns \-1.
1159 It is unlikely that applications will call this function directly.
1163 (or its macro equivalent)
1164 switches the buffer to
1167 in addition to its usual behaviour of
1168 setting the buffer's limit to its current position
1169 and its current position to its base.
1170 In read mode, a dynamic buffer will no longer grow dynamically,
1171 as one would expect.
1176 and its macro equivalent
1178 (which may evaluate its argument multiple times)
1179 will return a dynamic buffer to write mode,
1180 and also restore its current position to its base and
1181 clear its broken flag.
1183 .\"--------------------------------------------------------------------------
1192 .\"--------------------------------------------------------------------------
1195 Mark Wooding, <mdw@distorted.org.uk>
1197 .\"----- That's all, folks --------------------------------------------------
~mdw / mLib / blob