
Library to encode/decode Base XX encodings (RFC 4648)
=====================================================

SPDX-FileType: DOCUMENTATION
SPDX-FileCopyrightText: NONE
SPDX-License-Identifier: CC0-1.0


General
-------
This library provides Base 64 encoding and decoding functions.
Conversion from/to URL and IMAP Base 64 dialects is supported.
Conversion from/to EBCDIC encoding is supported.

Future versions may support other Base XX encodings too.

The development goals of this implementation are:
- C90 conformance
- Performance
- No memory (re)allocation
- Support for reproducible builds

Functionality is implemented with separate objects.
The linker should only pull in the code that is really needed.

Metadata for pkg-config is provided.


API
---
This library occupies the namespaces with "bxx0_" and "BXX0_" prefix.
The namespaces with "bxx0_i_" and "BXX0_I_" prefix are reserved for internal
use, never use it outside of the library (the shared library may not even
export such symbols).

All Base XX encoded data is generated and expected with US-ASCII encoding,
regardless of the execution character set used by the C compiler.
Functions to convert from/to EBCDIC are provided by the library.

Input and output data buffers use bytes in the sense of C, values for CHAR_BIT
other than 8 are supported.
The API use pointers to "unsigned char" for data buffers (with C99 this is the
only integer type that is guaranteed to have no padding bits).

No global context is used, therefore no initialization or shutdown
functions are present.


Error handling
--------------
Some fatal errors can be internally handled via assert(). Such errors, like
internal data corruption, indicate bugs in the library.
For maximum performance internal checks can be disabled with:

   CPPFLAGS=-DNDEBUG

The build system of the library enables the checks by default.


Thread safety
-------------
All API functions are thread-safe if "assert()" is thread-safe.
Otherwise "NDEBUG" must be defined to compile a thread-safe library.


Versioning scheme
-----------------
The release version contains 3 numbers "x.y.z":

- Major (x)
  The major number is incremented for every API/ABI change that is not backward
  compatible (with exception for version 0).

- Minor (y)
  The minor number is incremented for API/ABI extensions that are backward
  compatible.

- Patch (z)
  The patch number is incremented for changes that don't change the API/ABI.

In other words:
Releases with the same major and minor numbers are drop-in replacements.
Up- and downgrades between such versions are possible without touching programs
that use the library.
Releases with the same major, but different minor numbers are backward, but not
forward compatible. Upgrades are possible, downgrades can break programs that
use the library.
Releases with different major numbers require changes in all programs that use
the library.

Versions with different major numbers can be installed in parallel (including
header files).
Binaries can be linked against multiple instances of the library with different
major versions (e.g. if dependencies are using different versions).
