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
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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>