.\" -*-nroff-*-
.TH base32 3 "28 September 2004" "Straylight/Edgeware" "mLib utilities library"
.SH NAME
base32 \- conversion to and from base32 encoding
.\" @base32_encode
.\" @base32_decode
.\" @base32_init
.SH SYNOPSIS
.nf
.B "#include <mLib/base32.h>"

.BI "void base32_encode(base32_ctx *" ctx ,
.BI "                   const void *" p ", size_t " sz ,
.BI "                   dstr *" d );
.BI "void base32_decode(base32_ctx *" ctx ,
.BI "                   const void *" p ", size_t " sz ,
.BI "                   dstr *" d );
.BI "void base32_init(base32_ctx *" ctx );
.fi
.SH DESCRIPTION
The
.B base32
functions perform base32 encoding and decoding of arbitrary binary
strings.  The base32 encoding is defined by RFC2938.
.PP
Before encoding or decoding a string, a
.I context
(of type
.BR base32_ctx )
must be initialized, by passing it to
.BR base32_init .
The context contains data which must be retained between calls to encode
or decode substrings.  The
.B base32_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 base32_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 base32_encode
it is necessary to flush the final few bytes of output.  This is
achieved by passing
.B base32_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 base32_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 base32_encode
is allowed to produce.  If this is not a multiple of 4, it is rounded
up to the next highest multiple of four before use.  A value of zero
instructs
.B base32_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 base32_decode
function.  The comments above about flushing output apply equally to
decoding.
.PP
Decoding ignores all whitespace characters in the encoded string.  It
also ignores
.RB ` = '
characters in the string and works out the final block length
automatically based on the input size.
.SH "SEE ALSO"
.BR base64 (3),
.BR dstr (3),
.BR hex (3),
.BR mLib (3).
.SH AUTHOR
Mark Wooding, <mdw@distorted.org.uk>