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