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"
434 .\" @dbuf_vputstrf16b
435 .\" @dbuf_vputstrf16l
437 .\" @dbuf_vputstrf24b
438 .\" @dbuf_vputstrf24l
440 .\" @dbuf_vputstrf32b
441 .\" @dbuf_vputstrf32l
443 .\" @dbuf_vputstrf64b
444 .\" @dbuf_vputstrf64l
466 .\" @DBUF_ENCLOSEITAG
467 .\" @DBUF_ENCLOSEKTAG
468 .\" @DBUF_ENCLOSEZTAG
471 .\" @DBUF_ENCLOSE16_L
472 .\" @DBUF_ENCLOSE16_B
474 .\" @DBUF_ENCLOSE24_L
475 .\" @DBUF_ENCLOSE24_B
477 .\" @DBUF_ENCLOSE32_L
478 .\" @DBUF_ENCLOSE32_B
480 .\" @DBUF_ENCLOSE64_L
481 .\" @DBUF_ENCLOSE64_B
484 .\"--------------------------------------------------------------------------
486 buf \- reading and writing stuff in buffers
488 .\"--------------------------------------------------------------------------
492 .B "#include <mLib/dstr.h>"
494 .B "typedef struct { ...\& } buf;"
495 .B "typedef struct { ...\& } dbuf;"
497 .BI "void buf_init(buf *" b ", void *" p ", size_t " sz );
498 .BI "void dbuf_create(dbuf *" db );
499 .BI "void dbuf_reset(dbuf *" db );
500 .BI "void dbuf_destroy(dbuf *" db );
501 .BI "buf *DBUF_BUF(dbuf *" db );
502 .BI "void DBCREATE(dbuf *" db );
503 .BI "void DBRESET(dbuf *" db );
504 .BI "void DBDESTROY(dbuf *" db );
505 .B "#define DBUF_INIT ..."
508 All of the following functions and macros exist in two variants:
509 one with a name beginning
514 and taking a first argument of type
516 and a corresponding similarly named version with name beginning instead
521 and taking a first argument of type
525 .BI "void buf_flip(buf *" b );
526 .BI "octet *BBASE(buf *" b );
527 .BI "octet *BLIM(buf *" b );
528 .BI "octet *BCUR(buf *" b );
529 .BI "ptrdiff_t BSZ(buf *" b );
530 .BI "ptrdiff_t BLEN(buf *" b );
531 .BI "ptrdiff_t BLEFT(buf *" b );
532 .BI "void BFLIP(buf *" b );
534 .BI "int buf_break(buf *" b );
535 .BI "int BBREAK(buf *" b );
536 .BI "int BBAD(buf *" b );
537 .BI "int BOK(buf *" b );
539 .BI "int buf_ensure(buf *" b ", size_t " sz );
540 .BI "int buf_tryextend(buf *" b ", size_t " sz );
541 .BI "int BENSURE(buf *" b ", size_t " sz );
542 .BI "octet *BSTEP(buf *" b ", size_t " sz );
544 .BI "void *buf_get(buf *" b ", size_t " sz );
545 .BI "int buf_put(buf *" b ", const void *" p ", size_t " sz );
546 .BI "int buf_fill(buf *" b ", int " ch ", size_t " sz );
548 .BI "int buf_alignskip(buf *" b ", size_t " m ", size_t " a );
549 .BI "int buf_alignfill(buf *" b ", int " ch ", size_t " m ", size_t " a );
551 .BI "int buf_getbyte(buf *" b );
552 .BI "int buf_putbyte(buf *" b ", int " ch );
554 .BI "int buf_putstr(buf *" b ", const char *" p ", ...);"
555 .BI "int buf_vputstr(buf *" b ", const char *" p ", va_list *" ap );
572 and, if a 64-bit integer type is available,
578 .BI "int buf_putu" suff "(buf *" b ", uint" suff " " w );
579 .BI "int buf_getu" suff "(buf *" b ", uint" suff " *" w );
590 .BI "int buf_putk" suff "(buf *" b ", kludge64 " w );
591 .BI "int buf_getk" suff "(buf *" b ", kludge64 *" w );
593 .BI "int buf_getf32(buf *" b ", float " x );
594 .BI "int buf_getf32l(buf *" b ", float " x );
595 .BI "int buf_getf32b(buf *" b ", float " x );
596 .BI "int buf_getf64(buf *" b ", double " x );
597 .BI "int buf_getf64l(buf *" b ", double " x );
598 .BI "int buf_getf64b(buf *" b ", double " x );
599 .BI "int buf_putf32(buf *" b ", float *" x_out );
600 .BI "int buf_putf32l(buf *" b ", float *" x_out );
601 .BI "int buf_putf32b(buf *" b ", float *" x_out );
602 .BI "int buf_putf64(buf *" b ", double *" x_out );
603 .BI "int buf_putf64l(buf *" b ", double *" x_out );
604 .BI "int buf_putf64b(buf *" b ", double *" x_out );
607 .BI "BUF_ENCLOSETAG(" tag ", buf *" b ", size_t " mk ", " check ", " poke ", size_t " lensz )
609 .BI "BUF_ENCLOSEITAG(" tag ", buf *" b ", size_t " mk ", " W )
611 .BI "BUF_ENCLOSEKTAG(" tag ", buf *" b ", size_t " mk ", " W )
613 .BI "BUF_ENCLOSEZTAG(" tag ", buf *" b )
636 .BI "BUF_ENCLOSE" suff "(buf *" b ", size_t " mk )
639 .BI "BUF_ENCLOSEZ(buf *" b )
662 .BI "int buf_putstr" suff "(buf *" b ", const char *" p );
663 .BI "int buf_putstr" suff "(buf *" b ", const char *" p ", ...);"
664 .BI "int buf_vputstr" suff "(buf *" b ", const char *" p ", va_list *" ap );
665 .BI "int buf_putdstr" suff "(buf *" b ", dstr *" d );
666 .BI "int buf_getdstr" suff "(buf *" b ", dstr *" d );
667 .BI "int buf_putbuf" suff "(buf *" b ", buf *" bb );
668 .BI "int buf_getbuf" suff "(buf *" b ", buf *" bb );
669 .BI "int buf_putmem" suff "(buf *" b ", const void *" p ", size_t " sz );
670 .BI "void *buf_getmem" suff "(buf *" b ", size_t *" sz );
681 .BI "int buf_putf" suff "(buf *" b ", double " x );
682 .BI "int buf_getf" suff "(buf *" b ", double *" x );
685 .\"--------------------------------------------------------------------------
689 interface allows relatively convenient reading and writing of structured
690 binary data from and to fixed-size memory buffers. It's useful for
691 formatting and parsing down network data packets, for example.
694 A buffer has three important pointers associated with it:
697 The base address of the buffer.
700 Just past the last usable byte in the buffer
703 The position in the buffer at which the next read or write will occur.
705 A buffer is created using the
707 function. You must pass it the buffer base address and size, and a
710 structure to fill in. It doesn't allocate any memory, so you don't need
713 structure in any way before forgetting about it.
715 A collection of macros is provided for finding the positions of the
716 various interesting pointers known about a buffer, and the sizes of the
717 regions of memory they imply.
735 The size of the buffer; i.e.,
741 The length of data in the buffer (if writing) or the amount of data
742 read (if reading); i.e.,
748 The amount of space left in the buffer (if writing) or the amount of
749 data yet to read (if reading); i.e.,
756 takes a buffer which has been used for writing, and makes it suitable
757 for reading. This turns out to be useful when building packets in
758 multi-layered networking software. Its precise behaviour is to preserve
768 There is a macro version,
770 which does the same thing,
771 but it may evaluate its buffer argument multiple times.
775 to indicate that it has overflowed or that its contents are otherwise
776 invalid. The various buffer access functions described below all fail
777 on a broken buffer, and any errors they encounter cause the buffer to
778 become broken. Most simple programs which only use the supplied buffer
779 access functions can avoid the tedium of error-checking every function
780 call and just check the brokenness state at the end of their run.
788 the function returns \-1 as a possible, but minor, convenience;
789 the macro expands to a statement and cannot return a value.
792 reports true (nonzero) if its buffer argument is broken, or false (zero)
793 otherwise; its counterpart
795 reports true if the buffer is OK, and false if it is broken.
797 .SS "Low-level buffer access"
798 Access to the data in the buffer is usually sequential. The
800 macro (or the equivalent
802 function) checks that the buffer is OK and that there is enough space
803 remaining in the buffer for
805 bytes: if so, it returns zero; otherwise it breaks the buffer and
810 macro advances the buffer's
814 bytes. It does no bounds checking. Together with
816 this provides sequential access to the buffer's contents.
820 function is the basis of most buffer access functions, whether for
821 reading or writing. If the buffer is OK, and there are
823 or more bytes remaining, it steps the buffer's
831 pointer; otherwise it breaks the buffer if necessary, and returns a null
838 bytes of data starting at
840 to the buffer. If it succeeded, it returns 0; otherwise it returns \-1.
848 to the buffer, as if by calling
850 If it succeeds, it returns 0; otherwise it returns \-1.
854 function advances the buffer's position as little as possible,
855 so as to cause the position to be
857 bytes more than a multiple of
861 is zero then nothing is done.
862 The buffer contents are not altered.
865 function is similar, except that it advances the buffer position by writing
876 .SS "Formatted buffer access"
879 returns the next byte from a buffer as a nonnegative integer, or \-1 on
882 writes its argument to a buffer, and returns 0 on succes; it returns \-1
885 Many of the remaining functions deal with integer formatting and buffer
886 lengths. The functions support 8-, 16-, 24- and 32-bit integers, in
887 big- or little-endian order; on platforms with 64-bit integers, these
888 are supported too. The functions' names carry a suffix which is the
889 width in bits of the integers they deal with and an optional
893 for big-endian byte order. (The variant with no letter uses big-endian
894 order. Use of these variants tends to mean `I don't really care, but be
895 consistent,' and is not recommended if you have an externally-defined
896 spec you're meant to be compatible with.)
900 reads an integer. On success, it stores the integer it read at the
903 given, and returns zero; on failure, it returns \-1. The function
905 write an integer. It returns zero on success or \-1 on failure.
907 For (portability to) platforms without 64-bit integers, the functions
915 variants) perform the necessary functionality, but acting on the
930 read floating-point values
931 in IEEE\ 754 Binary32 and Binary64 format
933 as usual, the suffix indicates the format and byte ordering convention.
934 On success, they store the result in
937 on failure, they break the buffer and return zero.
948 write floating-point numbers
949 in IEEE\ 754 Binary32 and Binary64 format
951 On success, they return zero; on failure, they return \-1.
952 Note that these functions use IEEE\ 754 format
953 even if this is not the platform-native floating-point representation:
956 functions to do their work.
972 If more subtle control over error handling is necessary,
981 format string and arguments,
982 writing the output to the buffer.
986 except that it reads arguments from a
988 captured argument tail,
989 leaving the tail ready to read the next unprocessed argument.
990 Both functions return the number of bytes written on success
992 Note that these functions apply no length framing or termination.
993 They are implemented using
995 the output operations table is exposed as
997 the functions expect the output pointer to be the address of the output
1000 Functions which deal with block lengths assume the length is prefixed to
1001 the data, and don't include themselves. They come in all of the integer
1002 size variants, including 64-bits even on platforms without 64-bit integers;
1003 they also have an additional
1005 variant, which deals with zero-terminated data. No checks are done on
1006 writing that the data written contains no zero bytes.
1010 fetches a block of data. On success, it returns its base address and
1011 stores its length at the given address; on failure, it returns null.
1014 writes a block of data; it return zero on success or \-1 on failure.
1018 fetches a block of data and makes a second buffer point to it, i.e.,
1023 pointers to the start of the block and its
1025 pointer to just past the end. No copying of bulk data is performed.
1028 writes the contents of a buffer (i.e., between its
1032 pointers). The function
1033 .BI buf_getdstr suff
1034 fetches a block of data and append it to a dynamic string (see
1037 .BI buf_putdstr suff
1038 writes the contents of a dynamic string to a buffer. Finally, the
1041 writes a standard C null-terminated string to a buffer. All these
1042 functions return zero on success or \-1 on failure.
1045 .BI buf_putstrf suff
1048 format string and arguments,
1049 writing the output to the buffer.
1051 .BI buf_vputstrf suff
1053 except that it reads arguments from a
1055 captured argument tail,
1056 leaving the tail ready to read the next unprocessed argument.
1057 Both functions return the number of bytes written on success
1059 These functions add framing around the output:
1060 either a length prefix, or a trailing zero byte.
1063 .BI BUF_ENCLOSE suff
1064 macros are syntactically statement heads.
1065 (Notice that these macros use
1069 suffixes for little- and big-endian byte order.)
1070 They leave space in the buffer for appropriate length framing,
1071 and execute the following
1074 (which, of course, can be a compound statement enclosed in braces).
1077 completes, the macro fills in space
1078 with the length of material written by the
1082 argument should be a variable of type
1084 which will be overwritten by the macro.
1085 If the material is so large that its won't fit in the space
1086 then the buffer is broken.
1090 except that it just writes a terminating zero byte
1091 after whatever material was written by the
1095 .BR BUF_ENCLOSE ...\&
1096 macros are based on lower-level machinery.
1099 macro takes an additional argument
1103 bytes for the length,
1104 checks that the length doesn't exceed
1106 and stores the length using
1108 all of these constants and macros are defined in
1112 is similar, except that it uses the
1114 machinery to handle 64-bit length fields.
1117 macro is superficially similar,
1119 since it all it does is write a zero byte after its
1122 All of those macros also take an additional
1125 used to scope the internal labels they construct:
1128 for the details on how this works.
1134 macros are themselves built from a lower-level macro named
1135 .BR BUF_ENCLOSETAG .
1138 argument, it takes three arguments:
1140 is an expression which should evaluate true if the length
1144 is a macro, invoked as
1145 .IB poke "(unsigned char *" p ", " size_t n ")" \fR,
1150 formatted in whatever way is appropriate;
1153 is the amount of space, in bytes, to save for the length.
1155 .SS "Dynamic buffers"
1159 .IR "dynamic buffer" .
1160 It contains a buffer structure,
1161 accessible using the
1164 The ordinary buffer functions and macros can be used on this buffer,
1165 though, for convenience,
1166 there are similarly named functions and macros
1172 between the behaviour of the
1178 A dynamic buffer is created by statically initializing it with
1182 or its macro equivalent
1184 The memory backing a dynamic buffer can be freed by
1186 or the macro equivalent
1188 these leave the buffer in the state established by initialization:
1189 the buffer holds no resources, but is ready for immediate use.
1191 A dynamic buffer contains a
1197 The underlying buffer is accessible through the
1200 All of the above functions and macros can be applied
1201 to a dynamic buffer's underlying buffer.
1203 corresponding to each of the functions and macros described above,
1204 there is a version named with an initial
1209 which accepts a pointer to a dynamic buffer
1210 rather than an ordinary buffer,
1211 and acts on its underlying buffer.
1212 Note that these functions are in no way special.
1213 A dynamic buffer will grow automatically
1214 in response to either kind of functions.
1216 A freshly created buffer is in
1220 In this state, it will automatically extend its backing storage
1223 calls, rather than breaking.
1227 unpredictable amount of data can be written to a dynamic buffer
1228 and it will automatically grow as necessary to accommodate it.
1233 queries are somewhat meaningless when applied to dynamic buffers \(en
1234 though perfectly valid.
1235 The critical function for this is
1238 .BR dbuf_tryextend )
1239 which attempts to arrange that at least
1241 unused bytes are available in the buffer \(en
1244 would return at least
1246 If it succeeds, it returns zero;
1247 it will fail if the buffer is not in write mode,
1248 or if the buffer is not dynamic,
1249 in which case it returns \-1.
1250 It is unlikely that applications will call this function directly.
1254 (or its macro equivalent)
1255 switches the buffer to
1258 in addition to its usual behaviour of
1259 setting the buffer's limit to its current position
1260 and its current position to its base.
1261 In read mode, a dynamic buffer will no longer grow dynamically,
1262 as one would expect.
1267 and its macro equivalent
1269 (which may evaluate its argument multiple times)
1270 will return a dynamic buffer to write mode,
1271 and also restore its current position to its base and
1272 clear its broken flag.
1274 .\"--------------------------------------------------------------------------
1284 .\"--------------------------------------------------------------------------
1287 Mark Wooding, <mdw@distorted.org.uk>
1289 .\"----- That's all, folks --------------------------------------------------
~mdw / mLib / blob