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
285extern "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 */
329