2 .TH codec 3 "9 January 2009" "Straylight/Edgeware" "mLib utilities library"
4 codec \- binary encoding and decoding
16 .B "#include <mLib/codec.h>"
17 .B "#include <mLib/base64.h>"
18 .B "#include <mLib/base32.h>"
19 .B "#include <mLib/hex.h>"
21 .B "codec_class null_codec_class;"
22 .B "codec_class base64_class, file64_class, base64url_class;"
23 .B "codec_class base32_class, base32hex_class;"
24 .B "codec_class hex_class;"
26 .BI "const char *codec_strerror(int " err ");"
31 system provides an object-based interface to functions which encode
32 binary data as plain text and decode the result to recover the original
33 binary data. The interface makes it easy to support multiple encodings
34 and select an appropriate one at runtime.
35 .SS "The codec_class structure"
38 structure represents a particular encoding format. The structure has
39 the following members.
42 The name of the class, as a null-terminated string. The name should not
43 contain whitespace characters.
45 .BI "codec *(*encoder)(unsigned " flags ", const char *" indent ", unsigned " maxline ")"
46 Pointer to a function which constructs a new encoder object, of type
50 configure the behaviour of the object; the
52 string is written to separate lines of output; the integer
54 is the maximum length of line to be produced, or zero to forbid line
57 .BI "codec *(*decoder)(unsigned " flags ")"
58 Pointer to a function which constructs a new decoder object, also of
63 configure the behaviour of the object.
71 functions have the following meanings.
74 For codecs which produce output using a single alphabetic case (e.g.,
77 emit and accept only lower case; the default to emit and accept only
78 upper case, for compatibility with RFC4648. If the codec usually
79 produces mixed-case output, then this flag is ignored.
82 For codecs which produce output using a single alphabetic case, ignore
83 the case of the input when decoding. If the codec usually produces
84 mixed-case output, then this flag is ignored.
87 For codecs which usually pad their output (e.g.,
90 do not emit or accept padding characters. If the codec does not usually
91 produce padding, or the padding is not redundant, then this flag is
95 For codecs which usually pad their output, do not treat incorrect (e.g.,
96 missing or excessive) padding as an error when decoding. If the codec
97 does not usually produce padding, or the padding is required for
98 unambiguous decoding, then this flag is ignored.
101 For codecs which usually pad their output, ignore padding characters
102 wherever they may appear when decoding. Usually padding characters
103 indicate the end of the input, and further input characters are
104 considered erroneous. If the codec does not usually produce padding, or
105 it is impossible to resume decoding correctly having seen padding
106 characters, then this flag is ignored.
109 For codecs which need to pad their input, ignore unusual padding bits
110 when decoding. (This is not at all the same thing as the padding
111 characters controlled by the flags above: they deal with padding the
112 length of the encoding
114 up to a suitable multiple of characters; this option deals with padding
117 prior to encoding.) If the codec does not add padding bits, or specific
118 values are required for unambiguous decoding, then this flag is ignored.
121 Ignore newline (and carriage-return) characters when decoding: the
122 default for RFC4648 codecs is to reject newline characters. If these
123 characters are significant in the encoding, then this flag is ignored.
126 Ignore whitespace characters (other than newlines) when decoding: the
127 default for RFC4648 codecs is to reject whitespace characters. If these
128 characters are significant in the encoding, then this flag is ignored.
131 Ignore any other invalid characters appearing in the input when
135 Ignore all `junk' in the input. This should suppress almost all
138 If you do not set any of the
140 flags, a decoder should only accept the exact encoding that the
141 corresponding encoder would produce (with
143 = 0 to inhibit line-breaking).
144 .SS "The codec and codec_ops structures"
147 structure represents the state of an encoder or decoder, as returned by
152 functions described above, contains a single member.
154 .B "const codec_ops *ops"
157 structure which contains operations and metadata for use with the
162 structure contains the following members.
164 .B "const codec_class *c"
167 which was used to construct the
171 .BI "int (*code)(codec *" c ", const void *" p ", size_t " sz ", dstr *" d ")"
172 Encode or decode, using the codec
174 the data in the buffer at address
178 bytes, appending the output to the dynamic string
182 If the operation was successful, the function returns zero; otherwise it
183 returns a nonzero error code, as described below.
185 .BI "void (*destroy)(codec *" c ")"
186 Destroy the codec object
188 freeing any resources it may hold.
190 A codec may buffer its input (e.g., if needs to see more in order to
191 decide what output to produce next); it may also need to take special
192 action at the end of the input (e.g., flushing buffers, and applying
193 padding). To signal the codec that there is no more input, call the
197 pointer. It will then write any final output to
200 The following error conditions may be reported.
203 An invalid character was encountered while decoding. This includes
204 encoutering padding characters if padding is disabled using the
209 Invalid padding characters (e.g., wrong characters, or too few, too
210 many, or none at all) were found during decoding. This may also
211 indicate that the input is truncated, even if the codec does not usually
212 perform output padding.
215 Invalid padding bits were found during decoding.
219 function converts these error codes to brief, (moderately)
220 human-readable strings.
221 .SS "Provided codecs"
222 The library provides a number of standard codecs.
225 Implements Base64 encoding, as defined by RFC4648. Output is
233 Implements a variant of the Base64 encoding which uses
237 so that its output is suitable for use as a Unix filename.
240 Implements the filename- and URL-safe variant of Base64 encoding, as
244 Implements Base32 encoding, as defined by RFC4648. Output is in upper
248 Implements the extended-hex variant of Base32, as defined by RFC4648.
249 This encoding has the property that the encoding preserves the ordering
250 of messages if padding is suppressed.
253 Implements hex encoding, defined by RFC4648 under the name Base16. For
254 compatibility with that specification, output is in upper case by
261 Mark Wooding, <mdw@distorted.org.uk>
~mdw / mLib / blob