Merge branch 'work'

[mLib] / buf.3

.\" -*-nroff-*-
.de VS
.sp 1
.RS
.nf
.ft B
..
.de VE
.ft R
.fi
.RE
.sp 1
..
.de hP
.IP
.ft B
\h'-\w'\\$1\ 'u'\\$1\ \c
.ft P
..
.ie t .ds o \(bu
.el .ds o o
.TH buf 3 "23 September 2005" "Straylight/Edgeware" "mLib utilities library"
.SH NAME
buf \- reading and writing stuff in buffers
.\" @BBASE
.\" @BLIM
.\" @BCUR
.\" @BSZ
.\" @BLEN
.\" @BLEFT
.\" @BSTEP
.\" @BBAD
.\" @BOK
.\" @BENSURE
.
.\" @buf_init
.\" @buf_break
.\" @buf_flip
.\" @buf_ensure
.\" @buf_get
.\" @buf_put
.
.\" @buf_getbyte
.\" @buf_putbyte
.
.\" @buf_getu8
.\" @buf_getu16
.\" @buf_getu16b
.\" @buf_getu16l
.\" @buf_getu24
.\" @buf_getu24b
.\" @buf_getu24l
.\" @buf_getu32
.\" @buf_getu32b
.\" @buf_getu32l
.
.\" @buf_putu8
.\" @buf_putu16
.\" @buf_putu16b
.\" @buf_putu16l
.\" @buf_putu24
.\" @buf_putu24b
.\" @buf_putu24l
.\" @buf_putu32
.\" @buf_putu32b
.\" @buf_putu32l
.
.\" @buf_getbuf8
.\" @buf_getbuf16
.\" @buf_getbuf16b
.\" @buf_getbuf16l
.\" @buf_getbuf24
.\" @buf_getbuf24b
.\" @buf_getbuf24l
.\" @buf_getbuf32
.\" @buf_getbuf32b
.\" @buf_getbuf32l
.\" @buf_getbufz
.
.\" @buf_putbuf8
.\" @buf_putbuf16
.\" @buf_putbuf16b
.\" @buf_putbuf16l
.\" @buf_putbuf24
.\" @buf_putbuf24b
.\" @buf_putbuf24l
.\" @buf_putbuf32
.\" @buf_putbuf32b
.\" @buf_putbuf32l
.\" @buf_putbufz
.
.\" @buf_getmem16
.\" @buf_getmem16b
.\" @buf_getmem16l
.\" @buf_getmem24
.\" @buf_getmem24b
.\" @buf_getmem24l
.\" @buf_getmem32
.\" @buf_getmem32b
.\" @buf_getmem32l
.\" @buf_getmem8
.\" @buf_getmemz
.
.\" @buf_putmem8
.\" @buf_putmem16
.\" @buf_putmem16b
.\" @buf_putmem16l
.\" @buf_putmem24
.\" @buf_putmem24b
.\" @buf_putmem24l
.\" @buf_putmem32
.\" @buf_putmem32b
.\" @buf_putmem32l
.\" @buf_putmemz
.
.\" @buf_putstr8
.\" @buf_putstr16
.\" @buf_putstr16b
.\" @buf_putstr16l
.\" @buf_putstr24
.\" @buf_putstr24b
.\" @buf_putstr24l
.\" @buf_putstr32
.\" @buf_putstr32b
.\" @buf_putstr32l
.\" @buf_putstrz
.
.\" @buf_getdstr8
.\" @buf_getdstr16
.\" @buf_getdstr16b
.\" @buf_getdstr16l
.\" @buf_getdstr24
.\" @buf_getdstr24b
.\" @buf_getdstr24l
.\" @buf_getdstr32
.\" @buf_getdstr32b
.\" @buf_getdstr32l
.\" @buf_getdstrz
.
.\" @buf_putdstr8
.\" @buf_putdstr16
.\" @buf_putdstr16b
.\" @buf_putdstr16l
.\" @buf_putdstr24
.\" @buf_putdstr24b
.\" @buf_putdstr24l
.\" @buf_putdstr32
.\" @buf_putdstr32b
.\" @buf_putdstr32l
.\" @buf_putdstrz
.SH SYNOPSIS
.nf
.B "#include <mLib/dstr.h>"

.BI "void buf_init(buf *" b ", void *" p ", size_t " sz );
.BI "void buf_flip(buf *" b );
.BI "octet *BBASE(buf *" b );
.BI "octet *BLIM(buf *" b );
.BI "octet *BCUR(buf *" b );
.BI "ptrdiff_t BSZ(buf *" b );
.BI "ptrdiff_t BLEN(buf *" b );
.BI "ptrdiff_t BLEFT(buf *" b );

.BI "int buf_break(buf *" b );
.BI "int BBAD(buf *" b );
.BI "int BOK(buf *" b );

.BI "int buf_ensure(buf *" b ", size_t " sz );
.BI "int BENSURE(buf *" b ", size_t " sz );
.BI "octet *BSTEP(buf *" b );

.BI "void *buf_get(buf *" b ", size_t " sz );
.BI "void *buf_put(buf *" b ", const void *" p ", size_t " sz );

.BI "int buf_getbyte(buf *" b );
.BI "int buf_putbyte(buf *" b ", int ch" );
.BI "int buf_getu" suff "(buf *" b ", uint" suff " *" w );
.BI "int buf_putu" suff "(buf *" b ", uint" suff " " w );
.BI "void *buf_getmem" suff "(buf *" b ", size_t *" sz );
.BI "int buf_putmem" suff "(buf *" b ", const void *" p ", size_t " sz );
.BI "int buf_getbuf" suff "(buf *" b ", buf *" bb );
.BI "int buf_putbuf" suff "(buf *" b ", buf *" bb );
.BI "int buf_getdstr" suff "(buf *" b ", dstr *" d );
.BI "int buf_putdstr" suff "(buf *" b ", dstr *" d );
.BI "int buf_putstr" suff "(buf *" b ", const char *" p );
.fi
.SH DESCRIPTION
The
.B buf
interface allows relatively convenient reading and writing of structured
binary data from and to fixed-size memory buffers.  It's useful for
formatting and parsing down network data packets, for example.
.SS "Buffer basics"
A buffer has three important pointers associated with it:
.TP
.I base
The base address of the buffer.
.TP
.I limit
Just past the last usable byte in the buffer
.TP
.I current
The position in the buffer at which the next read or write will occur.
.PP
A buffer is created using the
.B buf_init
function.  You must pass it the buffer base address and size, and a
pointer to a
.B buf
structure to fill in.  It doesn't allocate any memory, so you don't need
to dispose of the
.B buf
structure in any way before forgetting about it.
.PP
A collection of macros is provided for finding the positions of the
various interesting pointers known about a buffer, and the sizes of the
regions of memory they imply.
.TP
.B BBASE
The buffer's
.I base
pointer.
.TP
.B BLIM
The buffer's
.I limit
pointer.
.TP
.B BCUR
The buffer's
.I current
pointer.
.TP
.B BSZ
The size of the buffer; i.e.,
.I limit
\-
.IR base .
.TP
.B BLEN
The length of data in the buffer (if writing) or the amount of data
read (if reading); i.e.,
.I current
\-
.IR base .
.TP
.B BLEFT
The amount of space left in the buffer (if writing) or the amount of
data yet to read (if reading); i.e.,
.I limit
\-
.IR current .
.PP
The function
.B buf_flip
takes a buffer which has been used for writing, and makes it suitable
for reading.  This turns out to be useful when building packets in
multi-layered networking software.  Its precise behaviour is to preserve
.IR base ,
to set
.I limit
to
.IR current ,
and to set
.I current
to
.IR base .
.PP
A buffer can be
.IR broken ,
to indicate that it has overflowed or that its contents are otherwise
invalid.  The various buffer access functions described below all fail
on a broken buffer, and any errors they encounter cause the buffer to
become broken.  Most simple programs which only use the supplied buffer
access functions can avoid the tedium of error-checking every function
call and just check the brokenness state at the end of their run.
.PP
The function
.B buf_break
will break a buffer.  The macro
.B BBAD
reports true (nonzero) if its buffer argument is broken, or false (zero)
otherwise; its counterpart
.B BOK
reports true if the buffer is OK, and false if it is broken.
.SS "Low-level buffer access"
Access to the data in the buffer is usually sequential.  The
.B BENSURE
macro (or the equivalent
.B buf_ensure
function) checks that the buffer is OK and that there is enough space
remaining in the buffer for
.I sz
bytes: if so, it returns zero; otherwise it breaks the buffer and
returns \-1.
.PP
The
.B BSTEP
macro advances the buffer's
.I current
pointer by
.I sz
bytes.  It does no bounds checking.  Together with
.BR BENSURE ,
this provides sequential access to the buffer's contents.
.PP
The
.B buf_get
function is the basis of most buffer access functions, whether for
reading or writing.  If the buffer is OK, and there are
.I sz
or more bytes remaining, it steps the buffer's
.I current
pointer by
.I sz
and returns the
.I original
(pre-stepping)
.I current
pointer; otherwise it breaks the buffer if necessary, and returns a null
pointer.
.PP
The
.B buf_put
function writes
.I sz
bytes of data starting at
.I p
to the buffer.  If it succeeded, it returns 0; otherwise it returns \-1.
.SS "Formatted buffer access"
The function
.B buf_getbyte
returns the next byte from a buffer as a nonnegative integer, or \-1 on
error.  The function
.B buf_putbyte
writes its argument to a buffer, and returns 0 on succes; it returns \-1
if it failed.
.PP
Many of the remaining functions deal with integer formatting and buffer
lengths.  The functions support 8-, 16-, 24- and 32-bit integers, in
big- or little-endian order; on platforms with 64-bit integers, these
are supported too.  The functions' names carry a suffix which is the
width in bits of the integers they deal with and an optional
.RB ` l '
for little- or
.RB ` b '
for big-endian byte order.  (The variant with no letter uses big-endian
order.  Use of these variants tends to mean `I don't really care, but be
consistent,' and is not recommended if you have an externally-defined
spec you're meant to be compatible with.)
.PP
The function
.BI buf_getu suff
reads an integer.  On success, it stores the integer it read at the
address
.I w
given, and returns zero; on failure, it returns \-1.  The function
.BI buf_putu suff
write an integer.  It returns zero on success or \-1 on failure.
.PP
Functions which deal with block lengths assume the length is prefixed to
the data, and don't include themselves.  They also have an additional
.RB ` z '
variant, which deals with zero-terminated data.  No checks are done on
writing that the data written contains no zero bytes.
.PP
The function
.BI buf_getmem suff
fetches a block of data.  On success, it returns its base address and
stores its length at the given address; on failure, it returns null.
The function
.BI buf_putmem suff
writes a block of data; it return zero on success or \-1 on failure.
.PP
The functon
.BI buf_getbuf suff
fetches a block of data and makes a second buffer point to it, i.e.,
setting its
.I base
and
.I current
pointers to the start of the block and its
.I limit
pointer to just past the end.  No copying of bulk data is performed.
The function
.BI buf_putbuf suff
writes the contents of a buffer (i.e., between its
.I base
and
.I current
pointers).  The function
.BI buf_getdstr suff
fetches a block of data and append it to a dynamic string (see
.BR dstr (3)).
The function
.BI buf_putdstr suff
writes the contents of a dynamic string to a buffer.  Finally, the
function
.BI buf_putstr suff
writes a standard C null-terminated string to a buffer.  All these
functions return zero on success or \-1 on failure.
.SH "SEE ALSO"
.BR dstr (3),
.BR mLib (3).
.SH AUTHOR
Mark Wooding, <mdw@distorted.org.uk>