+++ /dev/null
-.\" -*-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@nsict.org>