comparison libbase64.3 @ 33:01c29bee0c54

man: add libbase64.3 manual page
author David Demelier <markand@malikania.fr>
date Wed, 02 Jun 2021 16:37:59 +0200
parents
children e4a6c3f3d0f2
comparison
equal deleted inserted replaced
32:c96f2b26678a 33:01c29bee0c54
1 .\"
2 .\" Copyright (c) 2013-2021 David Demelier <markand@malikania.fr>
3 .\"
4 .\" Permission to use, copy, modify, and/or distribute this software for any
5 .\" purpose with or without fee is hereby granted, provided that the above
6 .\" copyright notice and this permission notice appear in all copies.
7 .\"
8 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
9 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
10 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
11 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
12 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
13 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
14 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
15 .\"
16 .Dd June 2, 2021
17 .Dt LIBBASE64 3
18 .Os
19 .\" NAME
20 .Sh NAME
21 .Nm libbase64
22 .Nd encode and decode base64
23 .\" SYNOPSIS
24 .Sh SYNOPSIS
25 .In base64.h
26 .Fd #define B64_ENCODE_LENGTH(size)
27 .Fd #define B64_DECODE_LENGTH(size)
28 .Ft size_t
29 .Fn b64_encode "const char *src, size_t srcsz, char *dst, size_t dstsz"
30 .Ft size_t
31 .Fn b64_decode "const char *src, size_t srcsz, char *dst, size_t dstsz"
32 .\" DESCRIPTION
33 .Sh DESCRIPTION
34 This library exposes few functions to encode and decode any kind of input data
35 using base64 format.
36 .Pp
37 The
38 .Fn B64_ENCODE_LENGTH
39 and
40 .Fn B64_DECODE_LENGTH
41 macros can be used to compute the required size to encode or decode
42 respectively depending on the argument
43 .Fa size
44 expressed in bytes. They always return the number of bytes required at most
45 (depending on padding bytes) but the returned value
46 .Em doesn't
47 include the NUL terminator.
48 .Pp
49 The
50 .Fn b64_encode
51 function reads the input string
52 .Fa src
53 up to
54 .Fa srcsz
55 bytes (which can be -1 to read until NUL character) and stores the result into
56 argument
57 .Fa dst .
58 The function writes up to
59 .Fa dstsz
60 bytes at most (including the NUL terminator).
61 .Pp
62 The
63 .Fn b64_decode
64 functions read the base64 encoded (or base64url encoded) input string
65 .Fa src
66 up to
67 .Fa srcsz (which can be -1 to read until NUL character) and stores the decoded
68 result into argument
69 .Fa dst .
70 Ths function writes up to
71 .Fa dstsz
72 bytes at most (including the NUL terminator). This function always append a NUL
73 terminator so make sure to use the return value to get the real binary size if
74 required.
75 .\" RETURN VALUES
76 .Sh RETURN VALUES
77 The functions
78 .Fn b64_encode
79 and
80 .Fn b64_decode
81 returns the number of bytes written into the
82 .Fa dst
83 argument (not including the NUL terminator) or (size_t)-1 on error. In that case
84 .Va errno
85 is set to indicate the error.
86 .\" ERRORS
87 .Sh ERRORS
88 .Bl -tag -width Er
89 .It Bq Er ERANGE
90 The output
91 .Fa dst
92 pointer wasn't large enough to store the encoded/decoded data.
93 .It Bq Er EILSEQ
94 Only set from
95 .Fn b64_decode .
96 The input string
97 .Fa src
98 did not contain valid base64 characters.
99 .El
100 .Sh AUTHORS
101 .Nm
102 was written by David Demelier <markand@malikania.fr>