1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
/*
* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at https://mozilla.org/MPL/2.0/.
*/
/*
* base85n.h - C API for the Rust implementation of Base85N.
*
* This header declares the same API as the C implementation's
* c/include/base85n.h -- same function names, same status codes with the
* same numeric values, same ownership rules -- but the library behind it
* is the memory-safe Rust one (rust/src/ffi.rs). The two libraries are
* interchangeable at the ABI level: code written against either header
* links against either library.
*
* Prefer this one when you decode input you did not produce. The parsing
* is bounds-checked by the Rust compiler, so the failure modes a
* hand-written C parser has to be audited for -- out-of-bounds reads,
* pointer arithmetic overflow, use of an uninitialised length -- are not
* reachable, whatever the input. See SECURITY.md.
*
* Base85N encodes data for embedding in text-based formats -- JSON, XML,
* HTML, configuration files -- where Base64 would otherwise be used and the
* size or the cleanliness of the result matters. It is a Base85 variant
* using a single 85-character "protocol
* friendly" alphabet (Alphabet-N), with two adaptive modes on top of the
* usual 4-byte-to-5-character block expansion.
*
* Dynamic Passthrough (DP) represents a run of text-like bytes at exactly
* one output character per input byte. Its signal names which of the 13
* substitutable punctuation/whitespace characters (the R-Set) the segment
* contains, and which donor profile lends the Alphabet-N characters that
* stand in for them, so the substitution is built per segment and is
* injective -- DP needs no escape mechanism.
*
* Solid Fill represents a run of up to 2048 identical bytes in the five
* characters of its signal alone.
*
* See spec/base85n-v0.5.0.md for the full specification.
*
* Building
* --------
* cd rust && cargo build --release
*
* produces target/release/libbase85n.so (or .dylib/.dll) and
* target/release/libbase85n.a. Link either, and add this directory to
* your include path:
*
* cc app.c -Irust/include rust/target/release/libbase85n.a -lpthread -ldl -lm
*
* Ownership / memory model
* -------------------------
* Identical to the C implementation's, deliberately.
*
* - base85n_encode() allocates the output string with malloc(). On
* BASE85N_OK, the caller owns *out_str and must release it with
* free() when done. On any error return, *out_str and *out_len are
* left unmodified.
*
* - base85n_decode() allocates the output byte buffer with malloc().
* On BASE85N_OK, the caller owns *out_data and must release it with
* free() when done. On any error return, *out_data and *out_len are
* left unmodified.
*
* The output buffers come from the C allocator, not from Rust's, so
* free() is correct and no library-specific deallocator is needed. The
* decoded buffer is *not* NUL-terminated; the encoded string is, with
* the terminator not counted in *out_len.
*
* The library keeps no global state and retains no pointer the caller
* passed in after a call returns. All functions are re-entrant and
* thread-safe, perform no I/O, and call nothing outside malloc().
*
* One behavioural difference from the C library, and it is a difference
* in what cannot happen rather than in what does: a Rust allocation
* failure inside the encoder or decoder aborts the process instead of
* returning BASE85N_ERR_ALLOC, because aborting on allocation failure is
* Rust's global policy. BASE85N_ERR_ALLOC is still returned when the
* caller-owned output buffer cannot be allocated.
*/
extern "C" __cplusplus
}
/* BASE85N_H */