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"
436 .\" @dbuf_vputstrf16b
437 .\" @dbuf_vputstrf16l
439 .\" @dbuf_vputstrf24b
440 .\" @dbuf_vputstrf24l
442 .\" @dbuf_vputstrf32b
443 .\" @dbuf_vputstrf32l
445 .\" @dbuf_vputstrf64b
446 .\" @dbuf_vputstrf64l
468 .\" @DBUF_ENCLOSEITAG
469 .\" @DBUF_ENCLOSEKTAG
470 .\" @DBUF_ENCLOSEZTAG
473 .\" @DBUF_ENCLOSE16_L
474 .\" @DBUF_ENCLOSE16_B
476 .\" @DBUF_ENCLOSE24_L
477 .\" @DBUF_ENCLOSE24_B
479 .\" @DBUF_ENCLOSE32_L
480 .\" @DBUF_ENCLOSE32_B
482 .\" @DBUF_ENCLOSE64_L
483 .\" @DBUF_ENCLOSE64_B
486 .\"--------------------------------------------------------------------------
488 buf \- reading and writing stuff in buffers
490 .\"--------------------------------------------------------------------------
494 .B "#include <mLib/dstr.h>"
496 .B "typedef struct { ...\& } buf;"
497 .B "typedef struct { ...\& } dbuf;"
499 .BI "void buf_init(buf *" b ", void *" p ", size_t " sz );
500 .BI "void dbuf_create(dbuf *" db );
501 .BI "void dbuf_reset(dbuf *" db );
502 .BI "void dbuf_destroy(dbuf *" db );
503 .BI "buf *DBUF_BUF(dbuf *" db );
504 .BI "void DBCREATE(dbuf *" db );
505 .BI "void DBRESET(dbuf *" db );
506 .BI "void DBDESTROY(dbuf *" db );
507 .B "#define DBUF_INIT ..."
510 All of the following functions and macros exist in two variants:
511 one with a name beginning
516 and taking a first argument of type
518 and a corresponding similarly named version with name beginning instead
523 and taking a first argument of type
527 .BI "void buf_flip(buf *" b );
528 .BI "octet *BBASE(buf *" b );
529 .BI "octet *BLIM(buf *" b );
530 .BI "octet *BCUR(buf *" b );
531 .BI "ptrdiff_t BSZ(buf *" b );
532 .BI "ptrdiff_t BLEN(buf *" b );
533 .BI "ptrdiff_t BLEFT(buf *" b );
534 .BI "void BFLIP(buf *" b );
536 .BI "int buf_break(buf *" b );
537 .BI "int BBREAK(buf *" b );
538 .BI "int BBAD(buf *" b );
539 .BI "int BOK(buf *" b );
541 .BI "int buf_ensure(buf *" b ", size_t " sz );
542 .BI "int buf_tryextend(buf *" b ", size_t " sz );
543 .BI "int BENSURE(buf *" b ", size_t " sz );
544 .BI "octet *BSTEP(buf *" b ", size_t " sz );
546 .BI "void *buf_get(buf *" b ", size_t " sz );
547 .BI "int buf_put(buf *" b ", const void *" p ", size_t " sz );
548 .BI "int buf_fill(buf *" b ", int " ch ", size_t " sz );
550 .BI "int buf_align(buf *" b ", size_t " m ", size_t " a ", size_t *" sz_out );
551 .BI "int buf_alignskip(buf *" b ", size_t " m ", size_t " a );
552 .BI "int buf_alignfill(buf *" b ", int " ch ", size_t " m ", size_t " a );
554 .BI "int buf_getbyte(buf *" b );
555 .BI "int buf_putbyte(buf *" b ", int " ch );
557 .BI "int buf_putstr(buf *" b ", const char *" p ", ...);"
558 .BI "int buf_vputstr(buf *" b ", const char *" p ", va_list *" ap );
575 and, if a 64-bit integer type is available,
581 .BI "int buf_putu" suff "(buf *" b ", uint" suff " " w );
582 .BI "int buf_getu" suff "(buf *" b ", uint" suff " *" w );
593 .BI "int buf_putk" suff "(buf *" b ", kludge64 " w );
594 .BI "int buf_getk" suff "(buf *" b ", kludge64 *" w );
596 .BI "int buf_getf32(buf *" b ", float " x );
597 .BI "int buf_getf32l(buf *" b ", float " x );
598 .BI "int buf_getf32b(buf *" b ", float " x );
599 .BI "int buf_getf64(buf *" b ", double " x );
600 .BI "int buf_getf64l(buf *" b ", double " x );
601 .BI "int buf_getf64b(buf *" b ", double " x );
602 .BI "int buf_putf32(buf *" b ", float *" x_out );
603 .BI "int buf_putf32l(buf *" b ", float *" x_out );
604 .BI "int buf_putf32b(buf *" b ", float *" x_out );
605 .BI "int buf_putf64(buf *" b ", double *" x_out );
606 .BI "int buf_putf64l(buf *" b ", double *" x_out );
607 .BI "int buf_putf64b(buf *" b ", double *" x_out );
610 .BI "BUF_ENCLOSETAG(" tag ", buf *" b ", size_t " mk ", " check ", " poke ", size_t " lensz )
612 .BI "BUF_ENCLOSEITAG(" tag ", buf *" b ", size_t " mk ", " W )
614 .BI "BUF_ENCLOSEKTAG(" tag ", buf *" b ", size_t " mk ", " W )
616 .BI "BUF_ENCLOSEZTAG(" tag ", buf *" b )
639 .BI "BUF_ENCLOSE" suff "(buf *" b ", size_t " mk )
642 .BI "BUF_ENCLOSEZ(buf *" b )
665 .BI "int buf_putstr" suff "(buf *" b ", const char *" p );
666 .BI "int buf_putstr" suff "(buf *" b ", const char *" p ", ...);"
667 .BI "int buf_vputstr" suff "(buf *" b ", const char *" p ", va_list *" ap );
668 .BI "int buf_putdstr" suff "(buf *" b ", dstr *" d );
669 .BI "int buf_getdstr" suff "(buf *" b ", dstr *" d );
670 .BI "int buf_putbuf" suff "(buf *" b ", buf *" bb );
671 .BI "int buf_getbuf" suff "(buf *" b ", buf *" bb );
672 .BI "int buf_putmem" suff "(buf *" b ", const void *" p ", size_t " sz );
673 .BI "void *buf_getmem" suff "(buf *" b ", size_t *" sz );
684 .BI "int buf_putf" suff "(buf *" b ", double " x );
685 .BI "int buf_getf" suff "(buf *" b ", double *" x );
688 .\"--------------------------------------------------------------------------
692 interface allows relatively convenient reading and writing of structured
693 binary data from and to fixed-size memory buffers. It's useful for
694 formatting and parsing down network data packets, for example.
697 A buffer has three important pointers associated with it:
700 The base address of the buffer.
703 Just past the last usable byte in the buffer
706 The position in the buffer at which the next read or write will occur.
708 A buffer is created using the
710 function. You must pass it the buffer base address and size, and a
713 structure to fill in. It doesn't allocate any memory, so you don't need
716 structure in any way before forgetting about it.
718 A collection of macros is provided for finding the positions of the
719 various interesting pointers known about a buffer, and the sizes of the
720 regions of memory they imply.
738 The size of the buffer; i.e.,
744 The length of data in the buffer (if writing) or the amount of data
745 read (if reading); i.e.,
751 The amount of space left in the buffer (if writing) or the amount of
752 data yet to read (if reading); i.e.,
759 takes a buffer which has been used for writing, and makes it suitable
760 for reading. This turns out to be useful when building packets in
761 multi-layered networking software. Its precise behaviour is to preserve
771 There is a macro version,
773 which does the same thing,
774 but it may evaluate its buffer argument multiple times.
778 to indicate that it has overflowed or that its contents are otherwise
779 invalid. The various buffer access functions described below all fail
780 on a broken buffer, and any errors they encounter cause the buffer to
781 become broken. Most simple programs which only use the supplied buffer
782 access functions can avoid the tedium of error-checking every function
783 call and just check the brokenness state at the end of their run.
791 the function returns \-1 as a possible, but minor, convenience;
792 the macro expands to a statement and cannot return a value.
795 reports true (nonzero) if its buffer argument is broken, or false (zero)
796 otherwise; its counterpart
798 reports true if the buffer is OK, and false if it is broken.
800 .SS "Low-level buffer access"
801 Access to the data in the buffer is usually sequential. The
803 macro (or the equivalent
805 function) checks that the buffer is OK and that there is enough space
806 remaining in the buffer for
808 bytes: if so, it returns zero; otherwise it breaks the buffer and
813 macro advances the buffer's
817 bytes. It does no bounds checking. Together with
819 this provides sequential access to the buffer's contents.
823 function is the basis of most buffer access functions, whether for
824 reading or writing. If the buffer is OK, and there are
826 or more bytes remaining, it steps the buffer's
834 pointer; otherwise it breaks the buffer if necessary, and returns a null
841 bytes of data starting at
843 to the buffer. If it succeeded, it returns 0; otherwise it returns \-1.
851 to the buffer, as if by calling
853 If it succeeds, it returns 0; otherwise it returns \-1.
857 function tries to advance the buffer's position as little as possible,
858 so as to cause the position to be
860 bytes more than a multiple of
864 is zero then no change is needed.
865 If the buffer is broken, then
867 immediately returns null.
870 to the number of bytes \(en possibly zero \(en
871 by which the position would have to advance
872 in order to achieve the requested alignment.
873 If there is sufficient space remaining in the buffer,
874 then the current position is advanced,
875 and the old position is returned;
876 otherwise, the buffer is broken and a null pointer is returned.
880 simply advances the buffer position
881 until the designed alignment is achieved:
882 the buffer contents are not altered.
885 function is similar, except that it advances the buffer position by writing
890 These functions return zero on success,
891 or \-1 if the buffer lacked enough space
892 or was already broken.
893 Usually, it's best to use
900 function can be used for either.
902 .SS "Formatted buffer access"
905 returns the next byte from a buffer as a nonnegative integer, or \-1 on
908 writes its argument to a buffer, and returns 0 on succes; it returns \-1
911 Many of the remaining functions deal with integer formatting and buffer
912 lengths. The functions support 8-, 16-, 24- and 32-bit integers, in
913 big- or little-endian order; on platforms with 64-bit integers, these
914 are supported too. The functions' names carry a suffix which is the
915 width in bits of the integers they deal with and an optional
919 for big-endian byte order. (The variant with no letter uses big-endian
920 order. Use of these variants tends to mean `I don't really care, but be
921 consistent,' and is not recommended if you have an externally-defined
922 spec you're meant to be compatible with.)
926 reads an integer. On success, it stores the integer it read at the
929 given, and returns zero; on failure, it returns \-1. The function
931 write an integer. It returns zero on success or \-1 on failure.
933 For (portability to) platforms without 64-bit integers, the functions
941 variants) perform the necessary functionality, but acting on the
956 read floating-point values
957 in IEEE\ 754 Binary32 and Binary64 format
959 as usual, the suffix indicates the format and byte ordering convention.
960 On success, they store the result in
963 on failure, they break the buffer and return zero.
974 write floating-point numbers
975 in IEEE\ 754 Binary32 and Binary64 format
977 On success, they return zero; on failure, they return \-1.
978 Note that these functions use IEEE\ 754 format
979 even if this is not the platform-native floating-point representation:
982 functions to do their work.
998 If more subtle control over error handling is necessary,
1007 format string and arguments,
1008 writing the output to the buffer.
1012 except that it reads arguments from a
1014 captured argument tail,
1015 leaving the tail ready to read the next unprocessed argument.
1016 Both functions return the number of bytes written on success
1018 Note that these functions apply no length framing or termination.
1019 They are implemented using
1021 the output operations table is exposed as
1023 the functions expect the output pointer to be the address of the output
1026 Functions which deal with block lengths assume the length is prefixed to
1027 the data, and don't include themselves. They come in all of the integer
1028 size variants, including 64-bits even on platforms without 64-bit integers;
1029 they also have an additional
1031 variant, which deals with zero-terminated data. No checks are done on
1032 writing that the data written contains no zero bytes.
1036 fetches a block of data. On success, it returns its base address and
1037 stores its length at the given address; on failure, it returns null.
1040 writes a block of data; it return zero on success or \-1 on failure.
1044 fetches a block of data and makes a second buffer point to it, i.e.,
1049 pointers to the start of the block and its
1051 pointer to just past the end. No copying of bulk data is performed.
1054 writes the contents of a buffer (i.e., between its
1058 pointers). The function
1059 .BI buf_getdstr suff
1060 fetches a block of data and append it to a dynamic string (see
1063 .BI buf_putdstr suff
1064 writes the contents of a dynamic string to a buffer. Finally, the
1067 writes a standard C null-terminated string to a buffer. All these
1068 functions return zero on success or \-1 on failure.
1071 .BI buf_putstrf suff
1074 format string and arguments,
1075 writing the output to the buffer.
1077 .BI buf_vputstrf suff
1079 except that it reads arguments from a
1081 captured argument tail,
1082 leaving the tail ready to read the next unprocessed argument.
1083 Both functions return the number of bytes written on success
1085 These functions add framing around the output:
1086 either a length prefix, or a trailing zero byte.
1089 .BI BUF_ENCLOSE suff
1090 macros are syntactically statement heads.
1091 (Notice that these macros use
1095 suffixes for little- and big-endian byte order.)
1096 They leave space in the buffer for appropriate length framing,
1097 and execute the following
1100 (which, of course, can be a compound statement enclosed in braces).
1103 completes, the macro fills in space
1104 with the length of material written by the
1108 argument should be a variable of type
1110 which will be overwritten by the macro.
1111 If the material is so large that its won't fit in the space
1112 then the buffer is broken.
1116 except that it just writes a terminating zero byte
1117 after whatever material was written by the
1121 .BR BUF_ENCLOSE ...\&
1122 macros are based on lower-level machinery.
1125 macro takes an additional argument
1129 bytes for the length,
1130 checks that the length doesn't exceed
1132 and stores the length using
1134 all of these constants and macros are defined in
1138 is similar, except that it uses the
1140 machinery to handle 64-bit length fields.
1143 macro is superficially similar,
1145 since it all it does is write a zero byte after its
1148 All of those macros also take an additional
1151 used to scope the internal labels they construct:
1154 for the details on how this works.
1160 macros are themselves built from a lower-level macro named
1161 .BR BUF_ENCLOSETAG .
1164 argument, it takes three arguments:
1166 is an expression which should evaluate true if the length
1170 is a macro, invoked as
1171 .IB poke "(unsigned char *" p ", " size_t n ")" \fR,
1176 formatted in whatever way is appropriate;
1179 is the amount of space, in bytes, to save for the length.
1181 .SS "Dynamic buffers"
1185 .IR "dynamic buffer" .
1186 It contains a buffer structure,
1187 accessible using the
1190 The ordinary buffer functions and macros can be used on this buffer,
1191 though, for convenience,
1192 there are similarly named functions and macros
1198 between the behaviour of the
1204 A dynamic buffer is created by statically initializing it with
1208 or its macro equivalent
1210 The memory backing a dynamic buffer can be freed by
1212 or the macro equivalent
1214 these leave the buffer in the state established by initialization:
1215 the buffer holds no resources, but is ready for immediate use.
1217 A dynamic buffer contains a
1223 The underlying buffer is accessible through the
1226 All of the above functions and macros can be applied
1227 to a dynamic buffer's underlying buffer.
1229 corresponding to each of the functions and macros described above,
1230 there is a version named with an initial
1235 which accepts a pointer to a dynamic buffer
1236 rather than an ordinary buffer,
1237 and acts on its underlying buffer.
1238 Note that these functions are in no way special.
1239 A dynamic buffer will grow automatically
1240 in response to either kind of functions.
1242 A freshly created buffer is in
1246 In this state, it will automatically extend its backing storage
1249 calls, rather than breaking.
1253 unpredictable amount of data can be written to a dynamic buffer
1254 and it will automatically grow as necessary to accommodate it.
1259 queries are somewhat meaningless when applied to dynamic buffers \(en
1260 though perfectly valid.
1261 The critical function for this is
1264 .BR dbuf_tryextend )
1265 which attempts to arrange that at least
1267 unused bytes are available in the buffer \(en
1270 would return at least
1272 If it succeeds, it returns zero;
1273 it will fail if the buffer is not in write mode,
1274 or if the buffer is not dynamic,
1275 in which case it returns \-1.
1276 It is unlikely that applications will call this function directly.
1280 (or its macro equivalent)
1281 switches the buffer to
1284 in addition to its usual behaviour of
1285 setting the buffer's limit to its current position
1286 and its current position to its base.
1287 In read mode, a dynamic buffer will no longer grow dynamically,
1288 as one would expect.
1293 and its macro equivalent
1295 (which may evaluate its argument multiple times)
1296 will return a dynamic buffer to write mode,
1297 and also restore its current position to its base and
1298 clear its broken flag.
1300 .\"--------------------------------------------------------------------------
1310 .\"--------------------------------------------------------------------------
1313 Mark Wooding, <mdw@distorted.org.uk>
1315 .\"----- That's all, folks --------------------------------------------------
~mdw / mLib / blob