xz-utils (5.4.5)
1 /**
2 * \file api/lzma.h
3 * \brief The public API of liblzma data compression library
4 * \mainpage
5 *
6 * liblzma is a public domain general-purpose data compression library with
7 * a zlib-like API. The native file format is .xz, but also the old .lzma
8 * format and raw (no headers) streams are supported. Multiple compression
9 * algorithms (filters) are supported. Currently LZMA2 is the primary filter.
10 *
11 * liblzma is part of XZ Utils <https://tukaani.org/xz/>. XZ Utils includes
12 * a gzip-like command line tool named xz and some other tools. XZ Utils
13 * is developed and maintained by Lasse Collin and Jia Tan.
14 *
15 * Major parts of liblzma are based on Igor Pavlov's public domain LZMA SDK
16 * <https://7-zip.org/sdk.html>.
17 *
18 * The SHA-256 implementation is based on the public domain code found from
19 * 7-Zip <https://7-zip.org/>, which has a modified version of the public
20 * domain SHA-256 code found from Crypto++ <https://www.cryptopp.com/>.
21 * The SHA-256 code in Crypto++ was written by Kevin Springle and Wei Dai.
22 */
23
24 /*
25 * Author: Lasse Collin
26 *
27 * This file has been put into the public domain.
28 * You can do whatever you want with this file.
29 */
30
31 #ifndef LZMA_H
32 #define LZMA_H
33
34 /*****************************
35 * Required standard headers *
36 *****************************/
37
38 /*
39 * liblzma API headers need some standard types and macros. To allow
40 * including lzma.h without requiring the application to include other
41 * headers first, lzma.h includes the required standard headers unless
42 * they already seem to be included already or if LZMA_MANUAL_HEADERS
43 * has been defined.
44 *
45 * Here's what types and macros are needed and from which headers:
46 * - stddef.h: size_t, NULL
47 * - stdint.h: uint8_t, uint32_t, uint64_t, UINT32_C(n), uint64_C(n),
48 * UINT32_MAX, UINT64_MAX
49 *
50 * However, inttypes.h is a little more portable than stdint.h, although
51 * inttypes.h declares some unneeded things compared to plain stdint.h.
52 *
53 * The hacks below aren't perfect, specifically they assume that inttypes.h
54 * exists and that it typedefs at least uint8_t, uint32_t, and uint64_t,
55 * and that, in case of incomplete inttypes.h, unsigned int is 32-bit.
56 * If the application already takes care of setting up all the types and
57 * macros properly (for example by using gnulib's stdint.h or inttypes.h),
58 * we try to detect that the macros are already defined and don't include
59 * inttypes.h here again. However, you may define LZMA_MANUAL_HEADERS to
60 * force this file to never include any system headers.
61 *
62 * Some could argue that liblzma API should provide all the required types,
63 * for example lzma_uint64, LZMA_UINT64_C(n), and LZMA_UINT64_MAX. This was
64 * seen as an unnecessary mess, since most systems already provide all the
65 * necessary types and macros in the standard headers.
66 *
67 * Note that liblzma API still has lzma_bool, because using stdbool.h would
68 * break C89 and C++ programs on many systems. sizeof(bool) in C99 isn't
69 * necessarily the same as sizeof(bool) in C++.
70 */
71
72 #ifndef LZMA_MANUAL_HEADERS
73 /*
74 * I suppose this works portably also in C++. Note that in C++,
75 * we need to get size_t into the global namespace.
76 */
77 # include <stddef.h>
78
79 /*
80 * Skip inttypes.h if we already have all the required macros. If we
81 * have the macros, we assume that we have the matching typedefs too.
82 */
83 # if !defined(UINT32_C) || !defined(UINT64_C) \
84 || !defined(UINT32_MAX) || !defined(UINT64_MAX)
85 /*
86 * MSVC versions older than 2013 have no C99 support, and
87 * thus they cannot be used to compile liblzma. Using an
88 * existing liblzma.dll with old MSVC can work though(*),
89 * but we need to define the required standard integer
90 * types here in a MSVC-specific way.
91 *
92 * (*) If you do this, the existing liblzma.dll probably uses
93 * a different runtime library than your MSVC-built
94 * application. Mixing runtimes is generally bad, but
95 * in this case it should work as long as you avoid
96 * the few rarely-needed liblzma functions that allocate
97 * memory and expect the caller to free it using free().
98 */
99 # if defined(_WIN32) && defined(_MSC_VER) && _MSC_VER < 1800
100 typedef unsigned __int8 uint8_t;
101 typedef unsigned __int32 uint32_t;
102 typedef unsigned __int64 uint64_t;
103 # else
104 /* Use the standard inttypes.h. */
105 # ifdef __cplusplus
106 /*
107 * C99 sections 7.18.2 and 7.18.4 specify
108 * that C++ implementations define the limit
109 * and constant macros only if specifically
110 * requested. Note that if you want the
111 * format macros (PRIu64 etc.) too, you need
112 * to define __STDC_FORMAT_MACROS before
113 * including lzma.h, since re-including
114 * inttypes.h with __STDC_FORMAT_MACROS
115 * defined doesn't necessarily work.
116 */
117 # ifndef __STDC_LIMIT_MACROS
118 # define __STDC_LIMIT_MACROS 1
119 # endif
120 # ifndef __STDC_CONSTANT_MACROS
121 # define __STDC_CONSTANT_MACROS 1
122 # endif
123 # endif
124
125 # include <inttypes.h>
126 # endif
127
128 /*
129 * Some old systems have only the typedefs in inttypes.h, and
130 * lack all the macros. For those systems, we need a few more
131 * hacks. We assume that unsigned int is 32-bit and unsigned
132 * long is either 32-bit or 64-bit. If these hacks aren't
133 * enough, the application has to setup the types manually
134 * before including lzma.h.
135 */
136 # ifndef UINT32_C
137 # if defined(_WIN32) && defined(_MSC_VER)
138 # define UINT32_C(n) n ## UI32
139 # else
140 # define UINT32_C(n) n ## U
141 # endif
142 # endif
143
144 # ifndef UINT64_C
145 # if defined(_WIN32) && defined(_MSC_VER)
146 # define UINT64_C(n) n ## UI64
147 # else
148 /* Get ULONG_MAX. */
149 # include <limits.h>
150 # if ULONG_MAX == 4294967295UL
151 # define UINT64_C(n) n ## ULL
152 # else
153 # define UINT64_C(n) n ## UL
154 # endif
155 # endif
156 # endif
157
158 # ifndef UINT32_MAX
159 # define UINT32_MAX (UINT32_C(4294967295))
160 # endif
161
162 # ifndef UINT64_MAX
163 # define UINT64_MAX (UINT64_C(18446744073709551615))
164 # endif
165 # endif
166 #endif /* ifdef LZMA_MANUAL_HEADERS */
167
168
169 /******************
170 * LZMA_API macro *
171 ******************/
172
173 /*
174 * Some systems require that the functions and function pointers are
175 * declared specially in the headers. LZMA_API_IMPORT is for importing
176 * symbols and LZMA_API_CALL is to specify the calling convention.
177 *
178 * By default it is assumed that the application will link dynamically
179 * against liblzma. #define LZMA_API_STATIC in your application if you
180 * want to link against static liblzma. If you don't care about portability
181 * to operating systems like Windows, or at least don't care about linking
182 * against static liblzma on them, don't worry about LZMA_API_STATIC. That
183 * is, most developers will never need to use LZMA_API_STATIC.
184 *
185 * The GCC variants are a special case on Windows (Cygwin and MinGW-w64).
186 * We rely on GCC doing the right thing with its auto-import feature,
187 * and thus don't use __declspec(dllimport). This way developers don't
188 * need to worry about LZMA_API_STATIC. Also the calling convention is
189 * omitted on Cygwin but not on MinGW-w64.
190 */
191 #ifndef LZMA_API_IMPORT
192 # if !defined(LZMA_API_STATIC) && defined(_WIN32) && !defined(__GNUC__)
193 # define LZMA_API_IMPORT __declspec(dllimport)
194 # else
195 # define LZMA_API_IMPORT
196 # endif
197 #endif
198
199 #ifndef LZMA_API_CALL
200 # if defined(_WIN32) && !defined(__CYGWIN__)
201 # define LZMA_API_CALL __cdecl
202 # else
203 # define LZMA_API_CALL
204 # endif
205 #endif
206
207 #ifndef LZMA_API
208 # define LZMA_API(type) LZMA_API_IMPORT type LZMA_API_CALL
209 #endif
210
211
212 /***********
213 * nothrow *
214 ***********/
215
216 /*
217 * None of the functions in liblzma may throw an exception. Even
218 * the functions that use callback functions won't throw exceptions,
219 * because liblzma would break if a callback function threw an exception.
220 */
221 #ifndef lzma_nothrow
222 # if defined(__cplusplus)
223 # if __cplusplus >= 201103L || (defined(_MSVC_LANG) \
224 && _MSVC_LANG >= 201103L)
225 # define lzma_nothrow noexcept
226 # else
227 # define lzma_nothrow throw()
228 # endif
229 # elif defined(__GNUC__) && (__GNUC__ > 3 \
230 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 3))
231 # define lzma_nothrow __attribute__((__nothrow__))
232 # else
233 # define lzma_nothrow
234 # endif
235 #endif
236
237
238 /********************
239 * GNU C extensions *
240 ********************/
241
242 /*
243 * GNU C extensions are used conditionally in the public API. It doesn't
244 * break anything if these are sometimes enabled and sometimes not, only
245 * affects warnings and optimizations.
246 */
247 #if defined(__GNUC__) && __GNUC__ >= 3
248 # ifndef lzma_attribute
249 # define lzma_attribute(attr) __attribute__(attr)
250 # endif
251
252 /* warn_unused_result was added in GCC 3.4. */
253 # ifndef lzma_attr_warn_unused_result
254 # if __GNUC__ == 3 && __GNUC_MINOR__ < 4
255 # define lzma_attr_warn_unused_result
256 # endif
257 # endif
258
259 #else
260 # ifndef lzma_attribute
261 # define lzma_attribute(attr)
262 # endif
263 #endif
264
265
266 #ifndef lzma_attr_pure
267 # define lzma_attr_pure lzma_attribute((__pure__))
268 #endif
269
270 #ifndef lzma_attr_const
271 # define lzma_attr_const lzma_attribute((__const__))
272 #endif
273
274 #ifndef lzma_attr_warn_unused_result
275 # define lzma_attr_warn_unused_result \
276 lzma_attribute((__warn_unused_result__))
277 #endif
278
279
280 /**************
281 * Subheaders *
282 **************/
283
284 #ifdef __cplusplus
285 extern "C" {
286 #endif
287
288 /*
289 * Subheaders check that this is defined. It is to prevent including
290 * them directly from applications.
291 */
292 #define LZMA_H_INTERNAL 1
293
294 /* Basic features */
295 #include "lzma/version.h"
296 #include "lzma/base.h"
297 #include "lzma/vli.h"
298 #include "lzma/check.h"
299
300 /* Filters */
301 #include "lzma/filter.h"
302 #include "lzma/bcj.h"
303 #include "lzma/delta.h"
304 #include "lzma/lzma12.h"
305
306 /* Container formats */
307 #include "lzma/container.h"
308
309 /* Advanced features */
310 #include "lzma/stream_flags.h"
311 #include "lzma/block.h"
312 #include "lzma/index.h"
313 #include "lzma/index_hash.h"
314
315 /* Hardware information */
316 #include "lzma/hardware.h"
317
318 /*
319 * All subheaders included. Undefine LZMA_H_INTERNAL to prevent applications
320 * re-including the subheaders.
321 */
322 #undef LZMA_H_INTERNAL
323
324 #ifdef __cplusplus
325 }
326 #endif
327
328 #endif /* ifndef LZMA_H */
Browse
Usage
Versions