view libbase64.3 @ 38:c25a01b2229b

tests: switch to rexo
author David Demelier <markand@malikania.fr>
date Mon, 11 Oct 2021 17:03:45 +0200
parents e4a6c3f3d0f2
children 6d1a259f2a36
line wrap: on
line source

.\"
.\" Copyright (c) 2013-2021 David Demelier <markand@malikania.fr>
.\"
.\" Permission to use, copy, modify, and/or distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd June 2, 2021
.Dt LIBBASE64 3
.Os
.\" NAME
.Sh NAME
.Nm libbase64
.Nd encode and decode base64
.\" SYNOPSIS
.Sh SYNOPSIS
.In base64.h
.Fd #define B64_ENCODE_LENGTH(size)
.Fd #define B64_DECODE_LENGTH(size)
.Ft size_t
.Fn b64_encode "const char *src, size_t srcsz, char *dst, size_t dstsz"
.Ft size_t
.Fn b64_decode "const char *src, size_t srcsz, char *dst, size_t dstsz"
.\" DESCRIPTION
.Sh DESCRIPTION
This library exposes few functions to encode and decode any kind of input data
using base64 format.
.Pp
The
.Fn B64_ENCODE_LENGTH
and
.Fn B64_DECODE_LENGTH
macros can be used to compute the required size to encode or decode
respectively depending on the argument
.Fa size
expressed in bytes. They always return the number of bytes required at most
(depending on padding bytes) but the returned value
.Em doesn't
include the NUL terminator.
.Pp
The
.Fn b64_encode
function reads the input string
.Fa src
up to
.Fa srcsz
bytes (which can be -1 to read until NUL character) and stores the result into
argument
.Fa dst .
The function writes up to
.Fa dstsz
bytes at most (including the NUL terminator).
.Pp
The
.Fn b64_decode
functions read the base64 encoded (or base64url encoded) input string
.Fa src
up to
.Fa srcsz
(which can be -1 to read until NUL character) and stores the decoded result
into argument
.Fa dst .
Ths function writes up to
.Fa dstsz
bytes at most (including the NUL terminator). This function always append a NUL
terminator so make sure to use the return value to get the real binary size if
required.
.\" RETURN VALUES
.Sh RETURN VALUES
The functions
.Fn b64_encode
and
.Fn b64_decode
returns the number of bytes written into the
.Fa dst
argument (not including the NUL terminator) or (size_t)-1 on error. In that case
.Va errno
is set to indicate the error.
.\" ERRORS
.Sh ERRORS
.Bl -tag -width Er
.It Bq Er ERANGE
The output
.Fa dst
pointer wasn't large enough to store the encoded/decoded data.
.It Bq Er EILSEQ
Only set from
.Fn b64_decode .
The input string
.Fa src
did not contain valid base64 characters.
.El
.Sh AUTHORS
.Nm
was written by David Demelier <markand@malikania.fr>