17 \h'-\w'\\$1\ 'u'\\$1\ \c
22 .TH buf 3 "23 September 2005" "Straylight/Edgeware" "mLib utilities library"
24 buf \- reading and writing stuff in buffers
153 .B "#include <mLib/dstr.h>"
155 .B "typedef struct { ...\& } buf;"
157 .BI "void buf_init(buf *" b ", void *" p ", size_t " sz );
158 .BI "void buf_flip(buf *" b );
159 .BI "octet *BBASE(buf *" b );
160 .BI "octet *BLIM(buf *" b );
161 .BI "octet *BCUR(buf *" b );
162 .BI "ptrdiff_t BSZ(buf *" b );
163 .BI "ptrdiff_t BLEN(buf *" b );
164 .BI "ptrdiff_t BLEFT(buf *" b );
166 .BI "int buf_break(buf *" b );
167 .BI "int BBAD(buf *" b );
168 .BI "int BOK(buf *" b );
170 .BI "int buf_ensure(buf *" b ", size_t " sz );
171 .BI "int BENSURE(buf *" b ", size_t " sz );
172 .BI "octet *BSTEP(buf *" b ", size_t " sz );
174 .BI "void *buf_get(buf *" b ", size_t " sz );
175 .BI "void *buf_put(buf *" b ", const void *" p ", size_t " sz );
177 .BI "int buf_getbyte(buf *" b );
178 .BI "int buf_putbyte(buf *" b ", int ch" );
179 .BI "int buf_getu" suff "(buf *" b ", uint" suff " *" w );
180 .BI "int buf_putu" suff "(buf *" b ", uint" suff " " w );
181 .BI "void *buf_getmem" suff "(buf *" b ", size_t *" sz );
182 .BI "int buf_putmem" suff "(buf *" b ", const void *" p ", size_t " sz );
183 .BI "int buf_getbuf" suff "(buf *" b ", buf *" bb );
184 .BI "int buf_putbuf" suff "(buf *" b ", buf *" bb );
185 .BI "int buf_getdstr" suff "(buf *" b ", dstr *" d );
186 .BI "int buf_putdstr" suff "(buf *" b ", dstr *" d );
187 .BI "int buf_putstr" suff "(buf *" b ", const char *" p );
192 interface allows relatively convenient reading and writing of structured
193 binary data from and to fixed-size memory buffers. It's useful for
194 formatting and parsing down network data packets, for example.
196 A buffer has three important pointers associated with it:
199 The base address of the buffer.
202 Just past the last usable byte in the buffer
205 The position in the buffer at which the next read or write will occur.
207 A buffer is created using the
209 function. You must pass it the buffer base address and size, and a
212 structure to fill in. It doesn't allocate any memory, so you don't need
215 structure in any way before forgetting about it.
217 A collection of macros is provided for finding the positions of the
218 various interesting pointers known about a buffer, and the sizes of the
219 regions of memory they imply.
237 The size of the buffer; i.e.,
243 The length of data in the buffer (if writing) or the amount of data
244 read (if reading); i.e.,
250 The amount of space left in the buffer (if writing) or the amount of
251 data yet to read (if reading); i.e.,
258 takes a buffer which has been used for writing, and makes it suitable
259 for reading. This turns out to be useful when building packets in
260 multi-layered networking software. Its precise behaviour is to preserve
273 to indicate that it has overflowed or that its contents are otherwise
274 invalid. The various buffer access functions described below all fail
275 on a broken buffer, and any errors they encounter cause the buffer to
276 become broken. Most simple programs which only use the supplied buffer
277 access functions can avoid the tedium of error-checking every function
278 call and just check the brokenness state at the end of their run.
282 will break a buffer. The macro
284 reports true (nonzero) if its buffer argument is broken, or false (zero)
285 otherwise; its counterpart
287 reports true if the buffer is OK, and false if it is broken.
288 .SS "Low-level buffer access"
289 Access to the data in the buffer is usually sequential. The
291 macro (or the equivalent
293 function) checks that the buffer is OK and that there is enough space
294 remaining in the buffer for
296 bytes: if so, it returns zero; otherwise it breaks the buffer and
301 macro advances the buffer's
305 bytes. It does no bounds checking. Together with
307 this provides sequential access to the buffer's contents.
311 function is the basis of most buffer access functions, whether for
312 reading or writing. If the buffer is OK, and there are
314 or more bytes remaining, it steps the buffer's
322 pointer; otherwise it breaks the buffer if necessary, and returns a null
329 bytes of data starting at
331 to the buffer. If it succeeded, it returns 0; otherwise it returns \-1.
332 .SS "Formatted buffer access"
335 returns the next byte from a buffer as a nonnegative integer, or \-1 on
338 writes its argument to a buffer, and returns 0 on succes; it returns \-1
341 Many of the remaining functions deal with integer formatting and buffer
342 lengths. The functions support 8-, 16-, 24- and 32-bit integers, in
343 big- or little-endian order; on platforms with 64-bit integers, these
344 are supported too. The functions' names carry a suffix which is the
345 width in bits of the integers they deal with and an optional
349 for big-endian byte order. (The variant with no letter uses big-endian
350 order. Use of these variants tends to mean `I don't really care, but be
351 consistent,' and is not recommended if you have an externally-defined
352 spec you're meant to be compatible with.)
356 reads an integer. On success, it stores the integer it read at the
359 given, and returns zero; on failure, it returns \-1. The function
361 write an integer. It returns zero on success or \-1 on failure.
363 Functions which deal with block lengths assume the length is prefixed to
364 the data, and don't include themselves. They also have an additional
366 variant, which deals with zero-terminated data. No checks are done on
367 writing that the data written contains no zero bytes.
371 fetches a block of data. On success, it returns its base address and
372 stores its length at the given address; on failure, it returns null.
375 writes a block of data; it return zero on success or \-1 on failure.
379 fetches a block of data and makes a second buffer point to it, i.e.,
384 pointers to the start of the block and its
386 pointer to just past the end. No copying of bulk data is performed.
389 writes the contents of a buffer (i.e., between its
393 pointers). The function
395 fetches a block of data and append it to a dynamic string (see
399 writes the contents of a dynamic string to a buffer. Finally, the
402 writes a standard C null-terminated string to a buffer. All these
403 functions return zero on success or \-1 on failure.
408 Mark Wooding, <mdw@distorted.org.uk>