.\" -*-nroff-*-
.TH base64 3 "20 June 1999" "Straylight/Edgeware" "mLib utilities library"
.SH NAME
-base64 \- conversion to and from base64 encoding
+base64, base32, hex \- obsolete binary encoding functions
.\" @base64_encode
.\" @base64_decode
.\" @base64_init
+.\" @base32_encode
+.\" @base32_decode
+.\" @base32_init
+.\" @hex_encode
+.\" @hex_decode
+.\" @hex_init
.SH SYNOPSIS
.nf
.B "#include <mLib/base64.h>"
+.B "#include <mLib/base32.h>"
+.B "#include <mLib/hex.h>"
.BI "void base64_encode(base64_ctx *" ctx ,
.BI " const void *" p ", size_t " sz ,
.BI " const void *" p ", size_t " sz ,
.BI " dstr *" d );
.BI "void base64_init(base64_ctx *" ctx );
+
+.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 );
+
+.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 base64
-functions perform base64 encoding and decoding of arbitrary binary
-strings. The base64 encoding is defined by RFC2045.
+.BR base64 ,
+.B base32
+and
+.B hex
+functions perform encoding and decoding of arbitrary binary strings, as
+defined by RFC4648, but without error reporting. These functions are
+obsolete, and new applications should use the
+.BR codec (3)
+interface, which provides more encoding and decoding options, and proper
+error detection.
+.PP
+The interfaces to these sets of functions is very similar: in
+the following description,
+.I prefix
+stands for one of
+.BR base64 ,
+.BR base32 ,
+or
+.BR hex .
.PP
Before encoding or decoding a string, a
.I context
(of type
-.BR base64_ctx )
+.IB prefix _ctx \fR)
must be initialized, by passing it to
-.BR base64_init .
+.IB prefix _init \fR.
The context contains data which must be retained between calls to encode
or decode substrings. The
-.B base64_init
+.IB prefix _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 base64_encode
+.IB prefix _encode
function. It is passed a pointer to a context block
.IR ctx ,
the input substring to encode passed by address
.BR dstr (3)
for details on dynamic strings). Once all the input data has been
passed through
-.B base64_encode
+.IB prefix _encode
it is necessary to flush the final few bytes of output. This is
achieved by passing
-.B base64_encode
+.I prefix _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 base64_encode
+.IB prefix _encode
function is formatted into lines using values from the context
structure. The
.B indent
newline character. The
.B maxline
member gives the maximum length of line that
-.B base64_encode
+.IB prefix _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 base64_encode
+.IB prefix _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 base64_decode
+.IB prefix _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
+Decoding ignores all errors. In particular, whitespace is ignored, and
+in the case of Base64 and Base32 encodings, it also ignores
.RB ` = '
-characters in the string and works out the final block length
-automatically based on the input size.
+characters in the string.
.SH "SEE ALSO"
-.BR base32 (3),
+.BR codec (3),
.BR dstr (3),
-.BR hex (3),
.BR mLib (3).
.SH AUTHOR
Mark Wooding, <mdw@distorted.org.uk>
~mdw / mLib / blobdiff