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"
427 .\" @dbuf_vputstrf16b
428 .\" @dbuf_vputstrf16l
430 .\" @dbuf_vputstrf24b
431 .\" @dbuf_vputstrf24l
433 .\" @dbuf_vputstrf32b
434 .\" @dbuf_vputstrf32l
436 .\" @dbuf_vputstrf64b
437 .\" @dbuf_vputstrf64l
459 .\" @DBUF_ENCLOSEITAG
460 .\" @DBUF_ENCLOSEKTAG
461 .\" @DBUF_ENCLOSEZTAG
464 .\" @DBUF_ENCLOSE16_L
465 .\" @DBUF_ENCLOSE16_B
467 .\" @DBUF_ENCLOSE24_L
468 .\" @DBUF_ENCLOSE24_B
470 .\" @DBUF_ENCLOSE32_L
471 .\" @DBUF_ENCLOSE32_B
473 .\" @DBUF_ENCLOSE64_L
474 .\" @DBUF_ENCLOSE64_B
477 .\"--------------------------------------------------------------------------
479 buf \- reading and writing stuff in buffers
481 .\"--------------------------------------------------------------------------
485 .B "#include <mLib/dstr.h>"
487 .B "typedef struct { ...\& } buf;"
488 .B "typedef struct { ...\& } dbuf;"
490 .BI "void buf_init(buf *" b ", void *" p ", size_t " sz );
491 .BI "void dbuf_create(dbuf *" db );
492 .BI "void dbuf_reset(dbuf *" db );
493 .BI "void dbuf_destroy(dbuf *" db );
494 .BI "buf *DBUF_BUF(dbuf *" db );
495 .BI "void DBCREATE(dbuf *" db );
496 .BI "void DBRESET(dbuf *" db );
497 .BI "void DBDESTROY(dbuf *" db );
498 .B "#define DBUF_INIT ..."
501 All of the following functions and macros exist in two variants:
502 one with a name beginning
507 and taking a first argument of type
509 and a corresponding similarly named version with name beginning instead
514 and taking a first argument of type
518 .BI "void buf_flip(buf *" b );
519 .BI "octet *BBASE(buf *" b );
520 .BI "octet *BLIM(buf *" b );
521 .BI "octet *BCUR(buf *" b );
522 .BI "ptrdiff_t BSZ(buf *" b );
523 .BI "ptrdiff_t BLEN(buf *" b );
524 .BI "ptrdiff_t BLEFT(buf *" b );
525 .BI "void BFLIP(buf *" b );
527 .BI "int buf_break(buf *" b );
528 .BI "int BBREAK(buf *" b );
529 .BI "int BBAD(buf *" b );
530 .BI "int BOK(buf *" b );
532 .BI "int buf_ensure(buf *" b ", size_t " sz );
533 .BI "int buf_tryextend(buf *" b ", size_t " sz );
534 .BI "int BENSURE(buf *" b ", size_t " sz );
535 .BI "octet *BSTEP(buf *" b ", size_t " sz );
537 .BI "void *buf_get(buf *" b ", size_t " sz );
538 .BI "int buf_put(buf *" b ", const void *" p ", size_t " sz );
540 .BI "int buf_getbyte(buf *" b );
541 .BI "int buf_putbyte(buf *" b ", int " ch );
543 .BI "int buf_putstr(buf *" b ", const char *" p ", ...);"
544 .BI "int buf_vputstr(buf *" b ", const char *" p ", va_list *" ap );
561 and, if a 64-bit integer type is available,
567 .BI "int buf_putu" suff "(buf *" b ", uint" suff " " w );
568 .BI "int buf_getu" suff "(buf *" b ", uint" suff " *" w );
579 .BI "int buf_putk" suff "(buf *" b ", kludge64 " w );
580 .BI "int buf_getk" suff "(buf *" b ", kludge64 *" w );
582 .BI "int buf_getf32(buf *" b ", float " x );
583 .BI "int buf_getf32l(buf *" b ", float " x );
584 .BI "int buf_getf32b(buf *" b ", float " x );
585 .BI "int buf_getf64(buf *" b ", double " x );
586 .BI "int buf_getf64l(buf *" b ", double " x );
587 .BI "int buf_getf64b(buf *" b ", double " x );
588 .BI "int buf_putf32(buf *" b ", float *" x_out );
589 .BI "int buf_putf32l(buf *" b ", float *" x_out );
590 .BI "int buf_putf32b(buf *" b ", float *" x_out );
591 .BI "int buf_putf64(buf *" b ", double *" x_out );
592 .BI "int buf_putf64l(buf *" b ", double *" x_out );
593 .BI "int buf_putf64b(buf *" b ", double *" x_out );
596 .BI "BUF_ENCLOSETAG(" tag ", buf *" b ", size_t " mk ", " check ", " poke ", size_t " lensz )
598 .BI "BUF_ENCLOSEITAG(" tag ", buf *" b ", size_t " mk ", " W )
600 .BI "BUF_ENCLOSEKTAG(" tag ", buf *" b ", size_t " mk ", " W )
602 .BI "BUF_ENCLOSEZTAG(" tag ", buf *" b )
625 .BI "BUF_ENCLOSE" suff "(buf *" b ", size_t " mk )
628 .BI "BUF_ENCLOSEZ(buf *" b )
651 .BI "int buf_putstr" suff "(buf *" b ", const char *" p );
652 .BI "int buf_putstr" suff "(buf *" b ", const char *" p ", ...);"
653 .BI "int buf_vputstr" suff "(buf *" b ", const char *" p ", va_list *" ap );
654 .BI "int buf_putdstr" suff "(buf *" b ", dstr *" d );
655 .BI "int buf_getdstr" suff "(buf *" b ", dstr *" d );
656 .BI "int buf_putbuf" suff "(buf *" b ", buf *" bb );
657 .BI "int buf_getbuf" suff "(buf *" b ", buf *" bb );
658 .BI "int buf_putmem" suff "(buf *" b ", const void *" p ", size_t " sz );
659 .BI "void *buf_getmem" suff "(buf *" b ", size_t *" sz );
670 .BI "int buf_putf" suff "(buf *" b ", double " x );
671 .BI "int buf_getf" suff "(buf *" b ", double *" x );
674 .\"--------------------------------------------------------------------------
678 interface allows relatively convenient reading and writing of structured
679 binary data from and to fixed-size memory buffers. It's useful for
680 formatting and parsing down network data packets, for example.
683 A buffer has three important pointers associated with it:
686 The base address of the buffer.
689 Just past the last usable byte in the buffer
692 The position in the buffer at which the next read or write will occur.
694 A buffer is created using the
696 function. You must pass it the buffer base address and size, and a
699 structure to fill in. It doesn't allocate any memory, so you don't need
702 structure in any way before forgetting about it.
704 A collection of macros is provided for finding the positions of the
705 various interesting pointers known about a buffer, and the sizes of the
706 regions of memory they imply.
724 The size of the buffer; i.e.,
730 The length of data in the buffer (if writing) or the amount of data
731 read (if reading); i.e.,
737 The amount of space left in the buffer (if writing) or the amount of
738 data yet to read (if reading); i.e.,
745 takes a buffer which has been used for writing, and makes it suitable
746 for reading. This turns out to be useful when building packets in
747 multi-layered networking software. Its precise behaviour is to preserve
757 There is a macro version,
759 which does the same thing,
760 but it may evaluate its buffer argument multiple times.
764 to indicate that it has overflowed or that its contents are otherwise
765 invalid. The various buffer access functions described below all fail
766 on a broken buffer, and any errors they encounter cause the buffer to
767 become broken. Most simple programs which only use the supplied buffer
768 access functions can avoid the tedium of error-checking every function
769 call and just check the brokenness state at the end of their run.
777 the function returns \-1 as a possible, but minor, convenience;
778 the macro expands to a statement and cannot return a value.
781 reports true (nonzero) if its buffer argument is broken, or false (zero)
782 otherwise; its counterpart
784 reports true if the buffer is OK, and false if it is broken.
786 .SS "Low-level buffer access"
787 Access to the data in the buffer is usually sequential. The
789 macro (or the equivalent
791 function) checks that the buffer is OK and that there is enough space
792 remaining in the buffer for
794 bytes: if so, it returns zero; otherwise it breaks the buffer and
799 macro advances the buffer's
803 bytes. It does no bounds checking. Together with
805 this provides sequential access to the buffer's contents.
809 function is the basis of most buffer access functions, whether for
810 reading or writing. If the buffer is OK, and there are
812 or more bytes remaining, it steps the buffer's
820 pointer; otherwise it breaks the buffer if necessary, and returns a null
827 bytes of data starting at
829 to the buffer. If it succeeded, it returns 0; otherwise it returns \-1.
831 .SS "Formatted buffer access"
834 returns the next byte from a buffer as a nonnegative integer, or \-1 on
837 writes its argument to a buffer, and returns 0 on succes; it returns \-1
840 Many of the remaining functions deal with integer formatting and buffer
841 lengths. The functions support 8-, 16-, 24- and 32-bit integers, in
842 big- or little-endian order; on platforms with 64-bit integers, these
843 are supported too. The functions' names carry a suffix which is the
844 width in bits of the integers they deal with and an optional
848 for big-endian byte order. (The variant with no letter uses big-endian
849 order. Use of these variants tends to mean `I don't really care, but be
850 consistent,' and is not recommended if you have an externally-defined
851 spec you're meant to be compatible with.)
855 reads an integer. On success, it stores the integer it read at the
858 given, and returns zero; on failure, it returns \-1. The function
860 write an integer. It returns zero on success or \-1 on failure.
862 For (portability to) platforms without 64-bit integers, the functions
870 variants) perform the necessary functionality, but acting on the
885 read floating-point values
886 in IEEE\ 754 Binary32 and Binary64 format
888 as usual, the suffix indicates the format and byte ordering convention.
889 On success, they store the result in
892 on failure, they break the buffer and return zero.
903 write floating-point numbers
904 in IEEE\ 754 Binary32 and Binary64 format
906 On success, they return zero; on failure, they return \-1.
907 Note that these functions use IEEE\ 754 format
908 even if this is not the platform-native floating-point representation:
911 functions to do their work.
927 If more subtle control over error handling is necessary,
936 format string and arguments,
937 writing the output to the buffer.
941 except that it reads arguments from a
943 captured argument tail,
944 leaving the tail ready to read the next unprocessed argument.
945 Both functions return the number of bytes written on success
947 Note that these functions apply no length framing or termination.
948 They are implemented using
950 the output operations table is exposed as
952 the functions expect the output pointer to be the address of the output
955 Functions which deal with block lengths assume the length is prefixed to
956 the data, and don't include themselves. They come in all of the integer
957 size variants, including 64-bits even on platforms without 64-bit integers;
958 they also have an additional
960 variant, which deals with zero-terminated data. No checks are done on
961 writing that the data written contains no zero bytes.
965 fetches a block of data. On success, it returns its base address and
966 stores its length at the given address; on failure, it returns null.
969 writes a block of data; it return zero on success or \-1 on failure.
973 fetches a block of data and makes a second buffer point to it, i.e.,
978 pointers to the start of the block and its
980 pointer to just past the end. No copying of bulk data is performed.
983 writes the contents of a buffer (i.e., between its
987 pointers). The function
989 fetches a block of data and append it to a dynamic string (see
993 writes the contents of a dynamic string to a buffer. Finally, the
996 writes a standard C null-terminated string to a buffer. All these
997 functions return zero on success or \-1 on failure.
1000 .BI buf_putstrf suff
1003 format string and arguments,
1004 writing the output to the buffer.
1006 .BI buf_vputstrf suff
1008 except that it reads arguments from a
1010 captured argument tail,
1011 leaving the tail ready to read the next unprocessed argument.
1012 Both functions return the number of bytes written on success
1014 These functions add framing around the output:
1015 either a length prefix, or a trailing zero byte.
1018 .BI BUF_ENCLOSE suff
1019 macros are syntactically statement heads.
1020 (Notice that these macros use
1024 suffixes for little- and big-endian byte order.)
1025 They leave space in the buffer for appropriate length framing,
1026 and execute the following
1029 (which, of course, can be a compound statement enclosed in braces).
1032 completes, the macro fills in space
1033 with the length of material written by the
1037 argument should be a variable of type
1039 which will be overwritten by the macro.
1040 If the material is so large that its won't fit in the space
1041 then the buffer is broken.
1045 except that it just writes a terminating zero byte
1046 after whatever material was written by the
1050 .BR BUF_ENCLOSE ...\&
1051 macros are based on lower-level machinery.
1054 macro takes an additional argument
1058 bytes for the length,
1059 checks that the length doesn't exceed
1061 and stores the length using
1063 all of these constants and macros are defined in
1067 is similar, except that it uses the
1069 machinery to handle 64-bit length fields.
1072 macro is superficially similar,
1074 since it all it does is write a zero byte after its
1077 All of those macros also take an additional
1080 used to scope the internal labels they construct:
1083 for the details on how this works.
1089 macros are themselves built from a lower-level macro named
1090 .BR BUF_ENCLOSETAG .
1093 argument, it takes three arguments:
1095 is an expression which should evaluate true if the length
1099 is a macro, invoked as
1100 .IB poke "(unsigned char *" p ", " size_t n ")" \fR,
1105 formatted in whatever way is appropriate;
1108 is the amount of space, in bytes, to save for the length.
1110 .SS "Dynamic buffers"
1114 .IR "dynamic buffer" .
1115 It contains a buffer structure,
1116 accessible using the
1119 The ordinary buffer functions and macros can be used on this buffer,
1120 though, for convenience,
1121 there are similarly named functions and macros
1127 between the behaviour of the
1133 A dynamic buffer is created by statically initializing it with
1137 or its macro equivalent
1139 The memory backing a dynamic buffer can be freed by
1141 or the macro equivalent
1143 these leave the buffer in the state established by initialization:
1144 the buffer holds no resources, but is ready for immediate use.
1146 A dynamic buffer contains a
1152 The underlying buffer is accessible through the
1155 All of the above functions and macros can be applied
1156 to a dynamic buffer's underlying buffer.
1158 corresponding to each of the functions and macros described above,
1159 there is a version named with an initial
1164 which accepts a pointer to a dynamic buffer
1165 rather than an ordinary buffer,
1166 and acts on its underlying buffer.
1167 Note that these functions are in no way special.
1168 A dynamic buffer will grow automatically
1169 in response to either kind of functions.
1171 A freshly created buffer is in
1175 In this state, it will automatically extend its backing storage
1178 calls, rather than breaking.
1182 unpredictable amount of data can be written to a dynamic buffer
1183 and it will automatically grow as necessary to accommodate it.
1188 queries are somewhat meaningless when applied to dynamic buffers \(en
1189 though perfectly valid.
1190 The critical function for this is
1193 .BR dbuf_tryextend )
1194 which attempts to arrange that at least
1196 unused bytes are available in the buffer \(en
1199 would return at least
1201 If it succeeds, it returns zero;
1202 it will fail if the buffer is not in write mode,
1203 or if the buffer is not dynamic,
1204 in which case it returns \-1.
1205 It is unlikely that applications will call this function directly.
1209 (or its macro equivalent)
1210 switches the buffer to
1213 in addition to its usual behaviour of
1214 setting the buffer's limit to its current position
1215 and its current position to its base.
1216 In read mode, a dynamic buffer will no longer grow dynamically,
1217 as one would expect.
1222 and its macro equivalent
1224 (which may evaluate its argument multiple times)
1225 will return a dynamic buffer to write mode,
1226 and also restore its current position to its base and
1227 clear its broken flag.
1229 .\"--------------------------------------------------------------------------
1239 .\"--------------------------------------------------------------------------
1242 Mark Wooding, <mdw@distorted.org.uk>
1244 .\"----- That's all, folks --------------------------------------------------
~mdw / mLib / blob