Commit | Line | Data |
---|---|---|
b6b9d458 | 1 | .\" -*-nroff-*- |
c4ccbbf9 MW |
2 | .\" |
3 | .\" Manual for old-fashioned binary encoding and decoding | |
4 | .\" | |
5 | .\" (c) 1999, 2001, 2004, 2005, 2009, 2023, 2024 Straylight/Edgeware | |
6 | .\" | |
7 | . | |
8 | .\"----- Licensing notice --------------------------------------------------- | |
9 | .\" | |
10 | .\" This file is part of the mLib utilities library. | |
11 | .\" | |
12 | .\" mLib is free software: you can redistribute it and/or modify it under | |
13 | .\" the terms of the GNU Library General Public License as published by | |
14 | .\" the Free Software Foundation; either version 2 of the License, or (at | |
15 | .\" your option) any later version. | |
16 | .\" | |
17 | .\" mLib is distributed in the hope that it will be useful, but WITHOUT | |
18 | .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or | |
19 | .\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public | |
20 | .\" License for more details. | |
21 | .\" | |
22 | .\" You should have received a copy of the GNU Library General Public | |
23 | .\" License along with mLib. If not, write to the Free Software | |
24 | .\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, | |
25 | .\" USA. | |
26 | . | |
27 | .\"-------------------------------------------------------------------------- | |
28 | .so ../defs.man \" @@@PRE@@@ | |
29 | . | |
30 | .\"-------------------------------------------------------------------------- | |
31 | .TH base64 3mLib "20 June 1999" "Straylight/Edgeware" "mLib utilities library" | |
08da152e | 32 | .\" @base64_encode |
33 | .\" @base64_decode | |
34 | .\" @base64_init | |
236f657b MW |
35 | .\" @base32_encode |
36 | .\" @base32_decode | |
37 | .\" @base32_init | |
38 | .\" @hex_encode | |
39 | .\" @hex_decode | |
40 | .\" @hex_init | |
c4ccbbf9 MW |
41 | . |
42 | .\"-------------------------------------------------------------------------- | |
43 | .SH NAME | |
44 | base64, base32, hex \- obsolete binary encoding functions | |
45 | . | |
46 | .\"-------------------------------------------------------------------------- | |
b6b9d458 | 47 | .SH SYNOPSIS |
c4ccbbf9 | 48 | . |
b6b9d458 | 49 | .nf |
d2a91066 | 50 | .B "#include <mLib/base64.h>" |
236f657b MW |
51 | .B "#include <mLib/base32.h>" |
52 | .B "#include <mLib/hex.h>" | |
d056fbdf | 53 | .PP |
adec5584 | 54 | .ta 2n |
4729aa69 | 55 | .B "typedef struct {" |
adec5584 MW |
56 | .B " char *indent;" |
57 | .B " unsigned maxline;" | |
58 | .B " ..." | |
4729aa69 | 59 | .B "} base64_ctx;" |
d056fbdf | 60 | .PP |
adec5584 | 61 | .ta \w'\fBvoid base64_encode('u |
b6b9d458 | 62 | .BI "void base64_encode(base64_ctx *" ctx , |
adec5584 MW |
63 | .BI " const void *" p ", size_t " sz , |
64 | .BI " dstr *" d ); | |
b6b9d458 | 65 | .BI "void base64_decode(base64_ctx *" ctx , |
adec5584 MW |
66 | .BI " const void *" p ", size_t " sz , |
67 | .BI " dstr *" d ); | |
b6b9d458 | 68 | .BI "void base64_init(base64_ctx *" ctx ); |
d056fbdf | 69 | .PP |
adec5584 | 70 | .ta 2n |
4729aa69 | 71 | .B "typedef struct {" |
adec5584 MW |
72 | .B " char *indent;" |
73 | .B " unsigned maxline;" | |
74 | .B " ..." | |
4729aa69 | 75 | .B "} base32_ctx;" |
d056fbdf | 76 | .PP |
adec5584 | 77 | .ta \w'\fBvoid base32_encode('u |
236f657b | 78 | .BI "void base32_encode(base32_ctx *" ctx , |
adec5584 MW |
79 | .BI " const void *" p ", size_t " sz , |
80 | .BI " dstr *" d ); | |
236f657b | 81 | .BI "void base32_decode(base32_ctx *" ctx , |
adec5584 MW |
82 | .BI " const void *" p ", size_t " sz , |
83 | .BI " dstr *" d ); | |
236f657b | 84 | .BI "void base32_init(base32_ctx *" ctx ); |
d056fbdf | 85 | .PP |
adec5584 | 86 | .ta 2n |
4729aa69 | 87 | .B "typedef struct {" |
adec5584 MW |
88 | .B " char *indent;" |
89 | .B " unsigned maxline;" | |
90 | .B " ..." | |
4729aa69 | 91 | .B "} hex_ctx;" |
d056fbdf | 92 | .PP |
adec5584 | 93 | .ta \w'\fBvoid hex_encode('u |
236f657b | 94 | .BI "void hex_encode(hex_ctx *" ctx , |
adec5584 MW |
95 | .BI " const void *" p ", size_t " sz , |
96 | .BI " dstr *" d ); | |
236f657b | 97 | .BI "void hex_decode(hex_ctx *" ctx , |
adec5584 MW |
98 | .BI " const void *" p ", size_t " sz , |
99 | .BI " dstr *" d ); | |
236f657b | 100 | .BI "void hex_init(hex_ctx *" ctx ); |
b6b9d458 | 101 | .fi |
c4ccbbf9 MW |
102 | . |
103 | .\"-------------------------------------------------------------------------- | |
b6b9d458 | 104 | .SH DESCRIPTION |
c4ccbbf9 | 105 | . |
b6b9d458 | 106 | The |
236f657b | 107 | .BR base64 , |
e8d9f0df | 108 | .BR base32 , |
236f657b MW |
109 | and |
110 | .B hex | |
111 | functions perform encoding and decoding of arbitrary binary strings, as | |
112 | defined by RFC4648, but without error reporting. These functions are | |
113 | obsolete, and new applications should use the | |
114 | .BR codec (3) | |
115 | interface, which provides more encoding and decoding options, and proper | |
116 | error detection. | |
117 | .PP | |
118 | The interfaces to these sets of functions is very similar: in | |
119 | the following description, | |
120 | .I prefix | |
121 | stands for one of | |
122 | .BR base64 , | |
123 | .BR base32 , | |
124 | or | |
125 | .BR hex . | |
b6b9d458 | 126 | .PP |
127 | Before encoding or decoding a string, a | |
128 | .I context | |
129 | (of type | |
236f657b | 130 | .IB prefix _ctx \fR) |
b6b9d458 | 131 | must be initialized, by passing it to |
236f657b | 132 | .IB prefix _init \fR. |
b6b9d458 | 133 | The context contains data which must be retained between calls to encode |
134 | or decode substrings. The | |
236f657b | 135 | .IB prefix _init |
b6b9d458 | 136 | function sets up initial values for the data, and sets up defaults for |
137 | the output formatting settings (see below). | |
138 | .PP | |
139 | Encoding of a string is performed by the | |
236f657b | 140 | .IB prefix _encode |
b6b9d458 | 141 | function. It is passed a pointer to a context block |
142 | .IR ctx , | |
143 | the input substring to encode passed by address | |
144 | .I p | |
145 | and length | |
146 | .IR sz , | |
147 | and a pointer to a dynamic string | |
148 | .I d | |
149 | in which to write its output (see | |
08da152e | 150 | .BR dstr (3) |
b6b9d458 | 151 | for details on dynamic strings). Once all the input data has been |
152 | passed through | |
236f657b | 153 | .IB prefix _encode |
b6b9d458 | 154 | it is necessary to flush the final few bytes of output. This is |
155 | achieved by passing | |
236f657b | 156 | .I prefix _encode |
b6b9d458 | 157 | a null pointer as its source argument. It is an error to attempt to |
158 | continue encoding after flushing output. | |
159 | .PP | |
160 | The output of the | |
236f657b | 161 | .IB prefix _encode |
b6b9d458 | 162 | function is formatted into lines using values from the context |
163 | structure. The | |
164 | .B indent | |
165 | member is a pointer to a null-terminated string which is used to | |
166 | separate the output lines. The default indent string contains only a | |
167 | newline character. The | |
168 | .B maxline | |
d2a91066 | 169 | member gives the maximum length of line that |
236f657b | 170 | .IB prefix _encode |
b6b9d458 | 171 | is allowed to produce. If this is not a multiple of 4, it is rounded |
172 | up to the next highest multiple of four before use. A value of zero | |
173 | instructs | |
236f657b | 174 | .IB prefix _encode |
b6b9d458 | 175 | not to perform line splitting: the output will be a single (possibly |
176 | very long) output line. The default maximum line length is 72 | |
177 | characters. You may set these parameters by direct assignment to the | |
178 | context structure once it has been initialized. | |
179 | .PP | |
180 | Decoding is performed similarly by the | |
236f657b | 181 | .IB prefix _decode |
b6b9d458 | 182 | function. The comments above about flushing output apply equally to |
183 | decoding. | |
184 | .PP | |
236f657b MW |
185 | Decoding ignores all errors. In particular, whitespace is ignored, and |
186 | in the case of Base64 and Base32 encodings, it also ignores | |
b6b9d458 | 187 | .RB ` = ' |
236f657b | 188 | characters in the string. |
c4ccbbf9 MW |
189 | . |
190 | .\"-------------------------------------------------------------------------- | |
b6b9d458 | 191 | .SH "SEE ALSO" |
c4ccbbf9 | 192 | . |
236f657b | 193 | .BR codec (3), |
08da152e | 194 | .BR dstr (3), |
195 | .BR mLib (3). | |
c4ccbbf9 MW |
196 | . |
197 | .\"-------------------------------------------------------------------------- | |
b6b9d458 | 198 | .SH AUTHOR |
c4ccbbf9 | 199 | . |
9b5ac6ff | 200 | Mark Wooding, <mdw@distorted.org.uk> |
c4ccbbf9 MW |
201 | . |
202 | .\"----- That's all, folks -------------------------------------------------- |