--- /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>
~mdw / mLib / blobdiff