.\" -*-nroff-*-
.TH hex 3 "20 June 1999" "Straylight/Edgeware" "mLib utilities library"
.SH NAME
base64 \- conversion to and from base64 encoding
.\" @hex_encode
.\" @hex_decode
.\" @hex_init
.SH SYNOPSIS
.nf
.B "#include <mLib/hex.h>"

.BI "void hex_encode(hex_ctx *" ctx ,
.BI "                const void *" p ", size_t " sz ,
.BI "                dstr *" d );
.BI "void hex_decode(hex_ctx *" ctx ,
.BI "                const void *" p ", size_t " sz ,
.BI "                dstr *" d );
.BI "void hex_init(hex_ctx *" ctx );
.fi
.SH DESCRIPTION
The
.B hex
functions perform hex encoding and decoding of arbitrary binary
strings.
.PP
Before encoding or decoding a string, a
.I context
(of type
.BR hex_ctx )
must be initialized, by passing it to
.BR hex_init .
The context contains data which must be retained between calls to encode
or decode substrings.  The
.B hex_init
function sets up initial values for the data, and sets up defaults for
the output formatting settings (see below).
.PP
Encoding of a string is performed by the
.B hex_encode
function.  It is passed a pointer to a context block
.IR ctx ,
the input substring to encode passed by address
.I p
and length
.IR sz ,
and a pointer to a dynamic string
.I d
in which to write its output (see
.BR dstr (3)
for details on dynamic strings).  Once all the input data has been
passed through
.B hex_encode
it is necessary to flush the final few bytes of output.  This is
achieved by passing
.B hex_encode
a null pointer as its source argument.  It is an error to attempt to
continue encoding after flushing output.
.PP
The output of the
.B hex_encode
function is formatted into lines using values from the context
structure.  The
.B indent
member is a pointer to a null-terminated string which is used to
separate the output lines.  The default indent string contains only a
newline character.  The
.B maxline
member gives the maximum length of line that
.B hex_encode
is allowed to produce.  If this is not a multiple of 2, it is rounded
up to the next highest multiple of two before use.  A value of zero
instructs
.B hex_encode
not to perform line splitting: the output will be a single (possibly
very long) output line.  The default maximum line length is 72
characters.  You may set these parameters by direct assignment to the
context structure once it has been initialized.
.PP
Decoding is performed similarly by the
.B hex_decode
function.  The comments above about flushing output apply equally to
decoding.
.PP
Decoding ignores all whitespace characters in the encoded string.
.SH "SEE ALSO"
.BR base34 (3),
.BR base64 (3),
.BR dstr (3),
.BR mLib (3).
.SH AUTHOR
Mark Wooding, <mdw@distorted.org.uk>