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"
429 .\" @dbuf_vputstrf16b
430 .\" @dbuf_vputstrf16l
432 .\" @dbuf_vputstrf24b
433 .\" @dbuf_vputstrf24l
435 .\" @dbuf_vputstrf32b
436 .\" @dbuf_vputstrf32l
438 .\" @dbuf_vputstrf64b
439 .\" @dbuf_vputstrf64l
461 .\" @DBUF_ENCLOSEITAG
462 .\" @DBUF_ENCLOSEKTAG
463 .\" @DBUF_ENCLOSEZTAG
466 .\" @DBUF_ENCLOSE16_L
467 .\" @DBUF_ENCLOSE16_B
469 .\" @DBUF_ENCLOSE24_L
470 .\" @DBUF_ENCLOSE24_B
472 .\" @DBUF_ENCLOSE32_L
473 .\" @DBUF_ENCLOSE32_B
475 .\" @DBUF_ENCLOSE64_L
476 .\" @DBUF_ENCLOSE64_B
479 .\"--------------------------------------------------------------------------
481 buf \- reading and writing stuff in buffers
483 .\"--------------------------------------------------------------------------
487 .B "#include <mLib/dstr.h>"
489 .B "typedef struct { ...\& } buf;"
490 .B "typedef struct { ...\& } dbuf;"
492 .BI "void buf_init(buf *" b ", void *" p ", size_t " sz );
493 .BI "void dbuf_create(dbuf *" db );
494 .BI "void dbuf_reset(dbuf *" db );
495 .BI "void dbuf_destroy(dbuf *" db );
496 .BI "buf *DBUF_BUF(dbuf *" db );
497 .BI "void DBCREATE(dbuf *" db );
498 .BI "void DBRESET(dbuf *" db );
499 .BI "void DBDESTROY(dbuf *" db );
500 .B "#define DBUF_INIT ..."
503 All of the following functions and macros exist in two variants:
504 one with a name beginning
509 and taking a first argument of type
511 and a corresponding similarly named version with name beginning instead
516 and taking a first argument of type
520 .BI "void buf_flip(buf *" b );
521 .BI "octet *BBASE(buf *" b );
522 .BI "octet *BLIM(buf *" b );
523 .BI "octet *BCUR(buf *" b );
524 .BI "ptrdiff_t BSZ(buf *" b );
525 .BI "ptrdiff_t BLEN(buf *" b );
526 .BI "ptrdiff_t BLEFT(buf *" b );
527 .BI "void BFLIP(buf *" b );
529 .BI "int buf_break(buf *" b );
530 .BI "int BBREAK(buf *" b );
531 .BI "int BBAD(buf *" b );
532 .BI "int BOK(buf *" b );
534 .BI "int buf_ensure(buf *" b ", size_t " sz );
535 .BI "int buf_tryextend(buf *" b ", size_t " sz );
536 .BI "int BENSURE(buf *" b ", size_t " sz );
537 .BI "octet *BSTEP(buf *" b ", size_t " sz );
539 .BI "void *buf_get(buf *" b ", size_t " sz );
540 .BI "int buf_put(buf *" b ", const void *" p ", size_t " sz );
541 .BI "int buf_fill(buf *" b ", int " ch ", size_t " sz );
543 .BI "int buf_getbyte(buf *" b );
544 .BI "int buf_putbyte(buf *" b ", int " ch );
546 .BI "int buf_putstr(buf *" b ", const char *" p ", ...);"
547 .BI "int buf_vputstr(buf *" b ", const char *" p ", va_list *" ap );
564 and, if a 64-bit integer type is available,
570 .BI "int buf_putu" suff "(buf *" b ", uint" suff " " w );
571 .BI "int buf_getu" suff "(buf *" b ", uint" suff " *" w );
582 .BI "int buf_putk" suff "(buf *" b ", kludge64 " w );
583 .BI "int buf_getk" suff "(buf *" b ", kludge64 *" w );
585 .BI "int buf_getf32(buf *" b ", float " x );
586 .BI "int buf_getf32l(buf *" b ", float " x );
587 .BI "int buf_getf32b(buf *" b ", float " x );
588 .BI "int buf_getf64(buf *" b ", double " x );
589 .BI "int buf_getf64l(buf *" b ", double " x );
590 .BI "int buf_getf64b(buf *" b ", double " x );
591 .BI "int buf_putf32(buf *" b ", float *" x_out );
592 .BI "int buf_putf32l(buf *" b ", float *" x_out );
593 .BI "int buf_putf32b(buf *" b ", float *" x_out );
594 .BI "int buf_putf64(buf *" b ", double *" x_out );
595 .BI "int buf_putf64l(buf *" b ", double *" x_out );
596 .BI "int buf_putf64b(buf *" b ", double *" x_out );
599 .BI "BUF_ENCLOSETAG(" tag ", buf *" b ", size_t " mk ", " check ", " poke ", size_t " lensz )
601 .BI "BUF_ENCLOSEITAG(" tag ", buf *" b ", size_t " mk ", " W )
603 .BI "BUF_ENCLOSEKTAG(" tag ", buf *" b ", size_t " mk ", " W )
605 .BI "BUF_ENCLOSEZTAG(" tag ", buf *" b )
628 .BI "BUF_ENCLOSE" suff "(buf *" b ", size_t " mk )
631 .BI "BUF_ENCLOSEZ(buf *" b )
654 .BI "int buf_putstr" suff "(buf *" b ", const char *" p );
655 .BI "int buf_putstr" suff "(buf *" b ", const char *" p ", ...);"
656 .BI "int buf_vputstr" suff "(buf *" b ", const char *" p ", va_list *" ap );
657 .BI "int buf_putdstr" suff "(buf *" b ", dstr *" d );
658 .BI "int buf_getdstr" suff "(buf *" b ", dstr *" d );
659 .BI "int buf_putbuf" suff "(buf *" b ", buf *" bb );
660 .BI "int buf_getbuf" suff "(buf *" b ", buf *" bb );
661 .BI "int buf_putmem" suff "(buf *" b ", const void *" p ", size_t " sz );
662 .BI "void *buf_getmem" suff "(buf *" b ", size_t *" sz );
673 .BI "int buf_putf" suff "(buf *" b ", double " x );
674 .BI "int buf_getf" suff "(buf *" b ", double *" x );
677 .\"--------------------------------------------------------------------------
681 interface allows relatively convenient reading and writing of structured
682 binary data from and to fixed-size memory buffers. It's useful for
683 formatting and parsing down network data packets, for example.
686 A buffer has three important pointers associated with it:
689 The base address of the buffer.
692 Just past the last usable byte in the buffer
695 The position in the buffer at which the next read or write will occur.
697 A buffer is created using the
699 function. You must pass it the buffer base address and size, and a
702 structure to fill in. It doesn't allocate any memory, so you don't need
705 structure in any way before forgetting about it.
707 A collection of macros is provided for finding the positions of the
708 various interesting pointers known about a buffer, and the sizes of the
709 regions of memory they imply.
727 The size of the buffer; i.e.,
733 The length of data in the buffer (if writing) or the amount of data
734 read (if reading); i.e.,
740 The amount of space left in the buffer (if writing) or the amount of
741 data yet to read (if reading); i.e.,
748 takes a buffer which has been used for writing, and makes it suitable
749 for reading. This turns out to be useful when building packets in
750 multi-layered networking software. Its precise behaviour is to preserve
760 There is a macro version,
762 which does the same thing,
763 but it may evaluate its buffer argument multiple times.
767 to indicate that it has overflowed or that its contents are otherwise
768 invalid. The various buffer access functions described below all fail
769 on a broken buffer, and any errors they encounter cause the buffer to
770 become broken. Most simple programs which only use the supplied buffer
771 access functions can avoid the tedium of error-checking every function
772 call and just check the brokenness state at the end of their run.
780 the function returns \-1 as a possible, but minor, convenience;
781 the macro expands to a statement and cannot return a value.
784 reports true (nonzero) if its buffer argument is broken, or false (zero)
785 otherwise; its counterpart
787 reports true if the buffer is OK, and false if it is broken.
789 .SS "Low-level buffer access"
790 Access to the data in the buffer is usually sequential. The
792 macro (or the equivalent
794 function) checks that the buffer is OK and that there is enough space
795 remaining in the buffer for
797 bytes: if so, it returns zero; otherwise it breaks the buffer and
802 macro advances the buffer's
806 bytes. It does no bounds checking. Together with
808 this provides sequential access to the buffer's contents.
812 function is the basis of most buffer access functions, whether for
813 reading or writing. If the buffer is OK, and there are
815 or more bytes remaining, it steps the buffer's
823 pointer; otherwise it breaks the buffer if necessary, and returns a null
830 bytes of data starting at
832 to the buffer. If it succeeded, it returns 0; otherwise it returns \-1.
840 to the buffer, as if by calling
842 If it succeeds, it returns 0; otherwise it returns \-1.
844 .SS "Formatted buffer access"
847 returns the next byte from a buffer as a nonnegative integer, or \-1 on
850 writes its argument to a buffer, and returns 0 on succes; it returns \-1
853 Many of the remaining functions deal with integer formatting and buffer
854 lengths. The functions support 8-, 16-, 24- and 32-bit integers, in
855 big- or little-endian order; on platforms with 64-bit integers, these
856 are supported too. The functions' names carry a suffix which is the
857 width in bits of the integers they deal with and an optional
861 for big-endian byte order. (The variant with no letter uses big-endian
862 order. Use of these variants tends to mean `I don't really care, but be
863 consistent,' and is not recommended if you have an externally-defined
864 spec you're meant to be compatible with.)
868 reads an integer. On success, it stores the integer it read at the
871 given, and returns zero; on failure, it returns \-1. The function
873 write an integer. It returns zero on success or \-1 on failure.
875 For (portability to) platforms without 64-bit integers, the functions
883 variants) perform the necessary functionality, but acting on the
898 read floating-point values
899 in IEEE\ 754 Binary32 and Binary64 format
901 as usual, the suffix indicates the format and byte ordering convention.
902 On success, they store the result in
905 on failure, they break the buffer and return zero.
916 write floating-point numbers
917 in IEEE\ 754 Binary32 and Binary64 format
919 On success, they return zero; on failure, they return \-1.
920 Note that these functions use IEEE\ 754 format
921 even if this is not the platform-native floating-point representation:
924 functions to do their work.
940 If more subtle control over error handling is necessary,
949 format string and arguments,
950 writing the output to the buffer.
954 except that it reads arguments from a
956 captured argument tail,
957 leaving the tail ready to read the next unprocessed argument.
958 Both functions return the number of bytes written on success
960 Note that these functions apply no length framing or termination.
961 They are implemented using
963 the output operations table is exposed as
965 the functions expect the output pointer to be the address of the output
968 Functions which deal with block lengths assume the length is prefixed to
969 the data, and don't include themselves. They come in all of the integer
970 size variants, including 64-bits even on platforms without 64-bit integers;
971 they also have an additional
973 variant, which deals with zero-terminated data. No checks are done on
974 writing that the data written contains no zero bytes.
978 fetches a block of data. On success, it returns its base address and
979 stores its length at the given address; on failure, it returns null.
982 writes a block of data; it return zero on success or \-1 on failure.
986 fetches a block of data and makes a second buffer point to it, i.e.,
991 pointers to the start of the block and its
993 pointer to just past the end. No copying of bulk data is performed.
996 writes the contents of a buffer (i.e., between its
1000 pointers). The function
1001 .BI buf_getdstr suff
1002 fetches a block of data and append it to a dynamic string (see
1005 .BI buf_putdstr suff
1006 writes the contents of a dynamic string to a buffer. Finally, the
1009 writes a standard C null-terminated string to a buffer. All these
1010 functions return zero on success or \-1 on failure.
1013 .BI buf_putstrf suff
1016 format string and arguments,
1017 writing the output to the buffer.
1019 .BI buf_vputstrf suff
1021 except that it reads arguments from a
1023 captured argument tail,
1024 leaving the tail ready to read the next unprocessed argument.
1025 Both functions return the number of bytes written on success
1027 These functions add framing around the output:
1028 either a length prefix, or a trailing zero byte.
1031 .BI BUF_ENCLOSE suff
1032 macros are syntactically statement heads.
1033 (Notice that these macros use
1037 suffixes for little- and big-endian byte order.)
1038 They leave space in the buffer for appropriate length framing,
1039 and execute the following
1042 (which, of course, can be a compound statement enclosed in braces).
1045 completes, the macro fills in space
1046 with the length of material written by the
1050 argument should be a variable of type
1052 which will be overwritten by the macro.
1053 If the material is so large that its won't fit in the space
1054 then the buffer is broken.
1058 except that it just writes a terminating zero byte
1059 after whatever material was written by the
1063 .BR BUF_ENCLOSE ...\&
1064 macros are based on lower-level machinery.
1067 macro takes an additional argument
1071 bytes for the length,
1072 checks that the length doesn't exceed
1074 and stores the length using
1076 all of these constants and macros are defined in
1080 is similar, except that it uses the
1082 machinery to handle 64-bit length fields.
1085 macro is superficially similar,
1087 since it all it does is write a zero byte after its
1090 All of those macros also take an additional
1093 used to scope the internal labels they construct:
1096 for the details on how this works.
1102 macros are themselves built from a lower-level macro named
1103 .BR BUF_ENCLOSETAG .
1106 argument, it takes three arguments:
1108 is an expression which should evaluate true if the length
1112 is a macro, invoked as
1113 .IB poke "(unsigned char *" p ", " size_t n ")" \fR,
1118 formatted in whatever way is appropriate;
1121 is the amount of space, in bytes, to save for the length.
1123 .SS "Dynamic buffers"
1127 .IR "dynamic buffer" .
1128 It contains a buffer structure,
1129 accessible using the
1132 The ordinary buffer functions and macros can be used on this buffer,
1133 though, for convenience,
1134 there are similarly named functions and macros
1140 between the behaviour of the
1146 A dynamic buffer is created by statically initializing it with
1150 or its macro equivalent
1152 The memory backing a dynamic buffer can be freed by
1154 or the macro equivalent
1156 these leave the buffer in the state established by initialization:
1157 the buffer holds no resources, but is ready for immediate use.
1159 A dynamic buffer contains a
1165 The underlying buffer is accessible through the
1168 All of the above functions and macros can be applied
1169 to a dynamic buffer's underlying buffer.
1171 corresponding to each of the functions and macros described above,
1172 there is a version named with an initial
1177 which accepts a pointer to a dynamic buffer
1178 rather than an ordinary buffer,
1179 and acts on its underlying buffer.
1180 Note that these functions are in no way special.
1181 A dynamic buffer will grow automatically
1182 in response to either kind of functions.
1184 A freshly created buffer is in
1188 In this state, it will automatically extend its backing storage
1191 calls, rather than breaking.
1195 unpredictable amount of data can be written to a dynamic buffer
1196 and it will automatically grow as necessary to accommodate it.
1201 queries are somewhat meaningless when applied to dynamic buffers \(en
1202 though perfectly valid.
1203 The critical function for this is
1206 .BR dbuf_tryextend )
1207 which attempts to arrange that at least
1209 unused bytes are available in the buffer \(en
1212 would return at least
1214 If it succeeds, it returns zero;
1215 it will fail if the buffer is not in write mode,
1216 or if the buffer is not dynamic,
1217 in which case it returns \-1.
1218 It is unlikely that applications will call this function directly.
1222 (or its macro equivalent)
1223 switches the buffer to
1226 in addition to its usual behaviour of
1227 setting the buffer's limit to its current position
1228 and its current position to its base.
1229 In read mode, a dynamic buffer will no longer grow dynamically,
1230 as one would expect.
1235 and its macro equivalent
1237 (which may evaluate its argument multiple times)
1238 will return a dynamic buffer to write mode,
1239 and also restore its current position to its base and
1240 clear its broken flag.
1242 .\"--------------------------------------------------------------------------
1252 .\"--------------------------------------------------------------------------
1255 Mark Wooding, <mdw@distorted.org.uk>
1257 .\"----- That's all, folks --------------------------------------------------
~mdw / mLib / blob