libar2_encode_base64.3

.TH LIBAR2_ENCODE_BASE64 3 LIBAR2
.SH NAME
libar2_encode_base64 - Encode data to base64

.SH SYNOPSIS
.nf
#include <libar2.h>

size_t libar2_encode_base64(char *\fIbuf\fP, const void *\fIdata\fP, size_t \fIlen\fP);

#define libar2_encode_base64_overlap_support libar2_encode_base64
.fi
.PP
Link with
.IR -lar2 .

.SH DESCRIPTION
The
.BR libar2_encode_base64 ()
function encodes some binary data, provided
via the
.I data
parameter, into base64, and stores the base64
encoding in
.I buf
(unless
.I buf
is
.IR NULL ).
The number of bytes from
.I data
to encode shall be specified in the
.I len
parameter.
.PP
The encoding of
.I data
will
.B not
be padded to a length divisble by 4.
.PP
.I data
may only be
.I NULL
if
.I len
is 0 or if
.I buf
is
.IR NULL .

.PP
In previous versions of libar2, the
.BR libar2_encode_base64 (3)
did not support overlap in the
.I buf
and
.IR data ,
this was a bug. The existence of the
.B libar2_encode_base64_overlap_support
macro indicates that this bug has been fixed.
The
.B libar2_encode_base64_overlap_support
macro is defined as
.I libar2_encode_base64
so that it can be used in place of
.BR libar2_encode_base64 ()
if support of memory overlap is required; e.g.
when encoding directly into the read buffer.

.SH RETURN VALUES
The
.BR libar2_encode_base64 ()
function returns the number of bytes required
to encode the data to base64, plus one extra
byte for the NUL byte that is added to the to
terminate the string; that is, the number of
bytes written to
.I buf
or the required allocation size of
.IR buf .
If
.I buf
is
.RI non- NULL ,
a string will be stored in it according to the
specifications in the
.B DESCRIPTION
section.

.SH ERRORS
The
.BR libar2_encode_base64 ()
function cannot fail.

.SH EXAMPLES
The following example demonstrates how to
encode data to base64 and store it in a
dynamically allocated string.
.PP
.nf
#include <libar2.h>
#include <stdlib.h>

static char *
encode_base64(const void *data, size_t len)
{
    size_t n = libar2_encode_base64(NULL, data, len);
    char *buf = malloc(n);
    if (!buf)
        return NULL;
    if (libar2_encode_base64(buf, data, len) > n)
        abort();
    return buf;
}
.fi

.SH NOTES
The encoding specified for
.BR crypt (3)
is B64, which is similar to, but with significant
differences from, base64, which is the encoding
that is standardised for Argon2.

.SH SEE ALSO
.BR libar2 (7),
.BR libar2_decode_base64 (3)