Mercurial > libbase64
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> |