2 * \file lzma/container.h
5 * \author Copyright (C) 1999-2008 Igor Pavlov
6 * \author Copyright (C) 2007-2008 Lasse Collin
8 * This library is free software; you can redistribute it and/or
9 * modify it under the terms of the GNU Lesser General Public
10 * License as published by the Free Software Foundation; either
11 * version 2.1 of the License, or (at your option) any later version.
13 * This library is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 * Lesser General Public License for more details.
19 #ifndef LZMA_H_INTERNAL
20 # error Never include this file directly. Use <lzma.h> instead.
29 * \brief Default compression preset
31 * It's not straightforward to recommend a default preset, because in some
32 * cases keeping the resource usage relatively low is more important that
33 * getting the maximum compression ratio.
35 #define LZMA_PRESET_DEFAULT UINT32_C(6)
39 * \brief Mask for preset level
41 * This is useful only if you need to extract the level from the preset
42 * variable. That should be rare.
44 #define LZMA_PRESET_LEVEL_MASK UINT32_C(0x1F)
50 * Currently only one flag is defined.
54 * \brief Extreme compression preset
56 * This flag modifies the preset to make the encoding significantly slower
57 * while improving the compression ratio only marginally. This is useful
58 * when you don't mind wasting time to get as small result as possible.
60 * This flag doesn't affect the memory usage requirements of the decoder (at
61 * least not significantly). The memory usage of the encoder may be increased
62 * a little but only at the lowest preset levels (0-4 or so).
64 #define LZMA_PRESET_EXTREME (UINT32_C(1) << 31)
68 * \brief Calculate rough memory usage of easy encoder
70 * This function is a wrapper for lzma_raw_encoder_memusage().
72 * \param preset Compression preset (level and possible flags)
74 extern uint64_t lzma_easy_encoder_memusage(uint32_t preset)
79 * \brief Calculate rough decoder memory usage of a preset
81 * This function is a wrapper for lzma_raw_decoder_memusage().
83 * \param preset Compression preset (level and possible flags)
85 extern uint64_t lzma_easy_decoder_memusage(uint32_t preset)
90 * \brief Initialize .xz Stream encoder using a preset number
92 * This function is intended for those who just want to use the basic features
93 * if liblzma (that is, most developers out there).
95 * \param strm Pointer to lzma_stream that is at least initialized
96 * with LZMA_STREAM_INIT.
97 * \param preset Compression preset to use. A preset consist of level
98 * number and zero or more flags. Usually flags aren't
99 * used, so preset is simply a number [0, 9] which match
100 * the options -0 .. -9 of the xz command line tool.
101 * Additional flags can be be set using bitwise-or with
102 * the preset level number, e.g. 6 | LZMA_PRESET_EXTREME.
103 * \param check Integrity check type to use. See check.h for available
104 * checks. If you are unsure, use LZMA_CHECK_CRC32.
106 * \return - LZMA_OK: Initialization succeeded. Use lzma_code() to
108 * - LZMA_MEM_ERROR: Memory allocation failed. All memory
109 * previously allocated for *strm is now freed.
110 * - LZMA_OPTIONS_ERROR: The given compression level is not
111 * supported by this build of liblzma.
112 * - LZMA_UNSUPPORTED_CHECK: The given check type is not
113 * supported by this liblzma build.
114 * - LZMA_PROG_ERROR: One or more of the parameters have values
115 * that will never be valid. For example, strm == NULL.
117 * If initialization succeeds, use lzma_code() to do the actual encoding.
118 * Valid values for `action' (the second argument of lzma_code()) are
119 * LZMA_RUN, LZMA_SYNC_FLUSH, LZMA_FULL_FLUSH, and LZMA_FINISH. In future,
120 * there may be compression levels or flags that don't support LZMA_SYNC_FLUSH.
122 extern lzma_ret lzma_easy_encoder(
123 lzma_stream *strm, uint32_t preset, lzma_check check)
124 lzma_attr_warn_unused_result;
128 * \brief Initialize .xz Stream encoder using a custom filter chain
130 * \param strm Pointer to properly prepared lzma_stream
131 * \param filters Array of filters. This must be terminated with
132 * filters[n].id = LZMA_VLI_UNKNOWN. See filter.h for
134 * \param check Type of the integrity check to calculate from
137 * \return - LZMA_OK: Initialization was successful.
139 * - LZMA_OPTIONS_ERROR
142 extern lzma_ret lzma_stream_encoder(lzma_stream *strm,
143 const lzma_filter *filters, lzma_check check)
144 lzma_attr_warn_unused_result;
148 * \brief Initialize .lzma encoder (legacy file format)
150 * The .lzma format is sometimes called the LZMA_Alone format, which is the
151 * reason for the name of this function. The .lzma format supports only the
152 * LZMA1 filter. There is no support for integrity checks like CRC32.
154 * Use this function if and only if you need to create files readable by
155 * legacy LZMA tools such as LZMA Utils 4.32.x. Moving to the .xz format
156 * is strongly recommended.
158 * The valid action values for lzma_code() are LZMA_RUN and LZMA_FINISH.
159 * No kind of flushing is supported, because the file format doesn't make
164 * - LZMA_OPTIONS_ERROR
167 extern lzma_ret lzma_alone_encoder(
168 lzma_stream *strm, const lzma_options_lzma *options)
169 lzma_attr_warn_unused_result;
177 * This flag makes lzma_code() return LZMA_NO_CHECK if the input stream
178 * being decoded has no integrity check. Note that when used with
179 * lzma_auto_decoder(), all .lzma files will trigger LZMA_NO_CHECK
180 * if LZMA_TELL_NO_CHECK is used.
182 #define LZMA_TELL_NO_CHECK UINT32_C(0x01)
186 * This flag makes lzma_code() return LZMA_UNSUPPORTED_CHECK if the input
187 * stream has an integrity check, but the type of the integrity check is not
188 * supported by this liblzma version or build. Such files can still be
189 * decoded, but the integrity check cannot be verified.
191 #define LZMA_TELL_UNSUPPORTED_CHECK UINT32_C(0x02)
195 * This flag makes lzma_code() return LZMA_GET_CHECK as soon as the type
196 * of the integrity check is known. The type can then be got with
199 #define LZMA_TELL_ANY_CHECK UINT32_C(0x04)
203 * This flag enables decoding of concatenated files with file formats that
204 * allow concatenating compressed files as is. From the formats currently
205 * supported by liblzma, only the .xz format allows concatenated files.
206 * Concatenated files are not allowed with the legacy .lzma format.
208 * This flag also affects the usage of the `action' argument for lzma_code().
209 * When LZMA_CONCATENATED is used, lzma_code() won't return LZMA_STREAM_END
210 * unless LZMA_FINISH is used as `action'. Thus, the application has to set
211 * LZMA_FINISH in the same way as it does when encoding.
213 * If LZMA_CONCATENATED is not used, the decoders still accept LZMA_FINISH
214 * as `action' for lzma_code(), but the usage of LZMA_FINISH isn't required.
216 #define LZMA_CONCATENATED UINT32_C(0x08)
220 * \brief Initialize .xz Stream decoder
222 * \param strm Pointer to properly prepared lzma_stream
223 * \param memlimit Rough memory usage limit as bytes
225 * \return - LZMA_OK: Initialization was successful.
226 * - LZMA_MEM_ERROR: Cannot allocate memory.
227 * - LZMA_OPTIONS_ERROR: Unsupported flags
229 extern lzma_ret lzma_stream_decoder(
230 lzma_stream *strm, uint64_t memlimit, uint32_t flags)
231 lzma_attr_warn_unused_result;
235 * \brief Decode .xz Streams and .lzma files with autodetection
237 * This decoder autodetects between the .xz and .lzma file formats, and
238 * calls lzma_stream_decoder() or lzma_alone_decoder() once the type
239 * of the input file has been detected.
241 * \param strm Pointer to properly prepared lzma_stream
242 * \param memlimit Rough memory usage limit as bytes
243 * \param flags Bitwise-or of flags, or zero for no flags.
245 * \return - LZMA_OK: Initialization was successful.
246 * - LZMA_MEM_ERROR: Cannot allocate memory.
247 * - LZMA_OPTIONS_ERROR: Unsupported flags
249 extern lzma_ret lzma_auto_decoder(
250 lzma_stream *strm, uint64_t memlimit, uint32_t flags)
251 lzma_attr_warn_unused_result;
255 * \brief Initialize .lzma decoder (legacy file format)
257 * Valid `action' arguments to lzma_code() are LZMA_RUN and LZMA_FINISH.
258 * There is no need to use LZMA_FINISH, but allowing it may simplify
259 * certain types of applications.
264 extern lzma_ret lzma_alone_decoder(lzma_stream *strm, uint64_t memlimit)
265 lzma_attr_warn_unused_result;