Import buf from Catacomb; split out the dstr bits, and throw away the mp and

[mLib] / man / base64.3

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

.BI "void base64_encode(base64_ctx *" ctx ,
.BI "                   const void *" p ", size_t " sz ,
.BI "                   dstr *" d );
.BI "void base64_decode(base64_ctx *" ctx ,
.BI "                   const void *" p ", size_t " sz ,
.BI "                   dstr *" d );
.BI "void base64_init(base64_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.
.PP
Before encoding or decoding a string, a
.I context
(of type
.BR base64_ctx )
must be initialized, by passing it to
.BR base64_init .
The context contains data which must be retained between calls to encode
or decode substrings.  The
.B base64_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
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 base64_encode
it is necessary to flush the final few bytes of output.  This is
achieved by passing
.B base64_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
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 base64_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
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
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 base32 (3),
.BR dstr (3),
.BR hex (3),
.BR mLib (3).
.SH AUTHOR
Mark Wooding, <mdw@distorted.org.uk>