container.h 24 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632
  1. /**
  2. * \file lzma/container.h
  3. * \brief File formats
  4. */
  5. /*
  6. * Author: Lasse Collin
  7. *
  8. * This file has been put into the public domain.
  9. * You can do whatever you want with this file.
  10. *
  11. * See ../lzma.h for information about liblzma as a whole.
  12. */
  13. #ifndef LZMA_H_INTERNAL
  14. # error Never include this file directly. Use <lzma.h> instead.
  15. #endif
  16. /************
  17. * Encoding *
  18. ************/
  19. /**
  20. * \brief Default compression preset
  21. *
  22. * It's not straightforward to recommend a default preset, because in some
  23. * cases keeping the resource usage relatively low is more important that
  24. * getting the maximum compression ratio.
  25. */
  26. #define LZMA_PRESET_DEFAULT UINT32_C(6)
  27. /**
  28. * \brief Mask for preset level
  29. *
  30. * This is useful only if you need to extract the level from the preset
  31. * variable. That should be rare.
  32. */
  33. #define LZMA_PRESET_LEVEL_MASK UINT32_C(0x1F)
  34. /*
  35. * Preset flags
  36. *
  37. * Currently only one flag is defined.
  38. */
  39. /**
  40. * \brief Extreme compression preset
  41. *
  42. * This flag modifies the preset to make the encoding significantly slower
  43. * while improving the compression ratio only marginally. This is useful
  44. * when you don't mind wasting time to get as small result as possible.
  45. *
  46. * This flag doesn't affect the memory usage requirements of the decoder (at
  47. * least not significantly). The memory usage of the encoder may be increased
  48. * a little but only at the lowest preset levels (0-3).
  49. */
  50. #define LZMA_PRESET_EXTREME (UINT32_C(1) << 31)
  51. /**
  52. * \brief Multithreading options
  53. */
  54. typedef struct {
  55. /**
  56. * \brief Flags
  57. *
  58. * Set this to zero if no flags are wanted.
  59. *
  60. * No flags are currently supported.
  61. */
  62. uint32_t flags;
  63. /**
  64. * \brief Number of worker threads to use
  65. */
  66. uint32_t threads;
  67. /**
  68. * \brief Maximum uncompressed size of a Block
  69. *
  70. * The encoder will start a new .xz Block every block_size bytes.
  71. * Using LZMA_FULL_FLUSH or LZMA_FULL_BARRIER with lzma_code()
  72. * the caller may tell liblzma to start a new Block earlier.
  73. *
  74. * With LZMA2, a recommended block size is 2-4 times the LZMA2
  75. * dictionary size. With very small dictionaries, it is recommended
  76. * to use at least 1 MiB block size for good compression ratio, even
  77. * if this is more than four times the dictionary size. Note that
  78. * these are only recommendations for typical use cases; feel free
  79. * to use other values. Just keep in mind that using a block size
  80. * less than the LZMA2 dictionary size is waste of RAM.
  81. *
  82. * Set this to 0 to let liblzma choose the block size depending
  83. * on the compression options. For LZMA2 it will be 3*dict_size
  84. * or 1 MiB, whichever is more.
  85. *
  86. * For each thread, about 3 * block_size bytes of memory will be
  87. * allocated. This may change in later liblzma versions. If so,
  88. * the memory usage will probably be reduced, not increased.
  89. */
  90. uint64_t block_size;
  91. /**
  92. * \brief Timeout to allow lzma_code() to return early
  93. *
  94. * Multithreading can make liblzma to consume input and produce
  95. * output in a very bursty way: it may first read a lot of input
  96. * to fill internal buffers, then no input or output occurs for
  97. * a while.
  98. *
  99. * In single-threaded mode, lzma_code() won't return until it has
  100. * either consumed all the input or filled the output buffer. If
  101. * this is done in multithreaded mode, it may cause a call
  102. * lzma_code() to take even tens of seconds, which isn't acceptable
  103. * in all applications.
  104. *
  105. * To avoid very long blocking times in lzma_code(), a timeout
  106. * (in milliseconds) may be set here. If lzma_code() would block
  107. * longer than this number of milliseconds, it will return with
  108. * LZMA_OK. Reasonable values are 100 ms or more. The xz command
  109. * line tool uses 300 ms.
  110. *
  111. * If long blocking times are fine for you, set timeout to a special
  112. * value of 0, which will disable the timeout mechanism and will make
  113. * lzma_code() block until all the input is consumed or the output
  114. * buffer has been filled.
  115. *
  116. * \note Even with a timeout, lzma_code() might sometimes take
  117. * somewhat long time to return. No timing guarantees
  118. * are made.
  119. */
  120. uint32_t timeout;
  121. /**
  122. * \brief Compression preset (level and possible flags)
  123. *
  124. * The preset is set just like with lzma_easy_encoder().
  125. * The preset is ignored if filters below is non-NULL.
  126. */
  127. uint32_t preset;
  128. /**
  129. * \brief Filter chain (alternative to a preset)
  130. *
  131. * If this is NULL, the preset above is used. Otherwise the preset
  132. * is ignored and the filter chain specified here is used.
  133. */
  134. const lzma_filter *filters;
  135. /**
  136. * \brief Integrity check type
  137. *
  138. * See check.h for available checks. The xz command line tool
  139. * defaults to LZMA_CHECK_CRC64, which is a good choice if you
  140. * are unsure.
  141. */
  142. lzma_check check;
  143. /*
  144. * Reserved space to allow possible future extensions without
  145. * breaking the ABI. You should not touch these, because the names
  146. * of these variables may change. These are and will never be used
  147. * with the currently supported options, so it is safe to leave these
  148. * uninitialized.
  149. */
  150. lzma_reserved_enum reserved_enum1;
  151. lzma_reserved_enum reserved_enum2;
  152. lzma_reserved_enum reserved_enum3;
  153. uint32_t reserved_int1;
  154. uint32_t reserved_int2;
  155. uint32_t reserved_int3;
  156. uint32_t reserved_int4;
  157. uint64_t reserved_int5;
  158. uint64_t reserved_int6;
  159. uint64_t reserved_int7;
  160. uint64_t reserved_int8;
  161. void *reserved_ptr1;
  162. void *reserved_ptr2;
  163. void *reserved_ptr3;
  164. void *reserved_ptr4;
  165. } lzma_mt;
  166. /**
  167. * \brief Calculate approximate memory usage of easy encoder
  168. *
  169. * This function is a wrapper for lzma_raw_encoder_memusage().
  170. *
  171. * \param preset Compression preset (level and possible flags)
  172. *
  173. * \return Number of bytes of memory required for the given
  174. * preset when encoding. If an error occurs, for example
  175. * due to unsupported preset, UINT64_MAX is returned.
  176. */
  177. extern LZMA_API(uint64_t) lzma_easy_encoder_memusage(uint32_t preset)
  178. lzma_nothrow lzma_attr_pure;
  179. /**
  180. * \brief Calculate approximate decoder memory usage of a preset
  181. *
  182. * This function is a wrapper for lzma_raw_decoder_memusage().
  183. *
  184. * \param preset Compression preset (level and possible flags)
  185. *
  186. * \return Number of bytes of memory required to decompress a file
  187. * that was compressed using the given preset. If an error
  188. * occurs, for example due to unsupported preset, UINT64_MAX
  189. * is returned.
  190. */
  191. extern LZMA_API(uint64_t) lzma_easy_decoder_memusage(uint32_t preset)
  192. lzma_nothrow lzma_attr_pure;
  193. /**
  194. * \brief Initialize .xz Stream encoder using a preset number
  195. *
  196. * This function is intended for those who just want to use the basic features
  197. * if liblzma (that is, most developers out there).
  198. *
  199. * \param strm Pointer to lzma_stream that is at least initialized
  200. * with LZMA_STREAM_INIT.
  201. * \param preset Compression preset to use. A preset consist of level
  202. * number and zero or more flags. Usually flags aren't
  203. * used, so preset is simply a number [0, 9] which match
  204. * the options -0 ... -9 of the xz command line tool.
  205. * Additional flags can be be set using bitwise-or with
  206. * the preset level number, e.g. 6 | LZMA_PRESET_EXTREME.
  207. * \param check Integrity check type to use. See check.h for available
  208. * checks. The xz command line tool defaults to
  209. * LZMA_CHECK_CRC64, which is a good choice if you are
  210. * unsure. LZMA_CHECK_CRC32 is good too as long as the
  211. * uncompressed file is not many gigabytes.
  212. *
  213. * \return - LZMA_OK: Initialization succeeded. Use lzma_code() to
  214. * encode your data.
  215. * - LZMA_MEM_ERROR: Memory allocation failed.
  216. * - LZMA_OPTIONS_ERROR: The given compression preset is not
  217. * supported by this build of liblzma.
  218. * - LZMA_UNSUPPORTED_CHECK: The given check type is not
  219. * supported by this liblzma build.
  220. * - LZMA_PROG_ERROR: One or more of the parameters have values
  221. * that will never be valid. For example, strm == NULL.
  222. *
  223. * If initialization fails (return value is not LZMA_OK), all the memory
  224. * allocated for *strm by liblzma is always freed. Thus, there is no need
  225. * to call lzma_end() after failed initialization.
  226. *
  227. * If initialization succeeds, use lzma_code() to do the actual encoding.
  228. * Valid values for `action' (the second argument of lzma_code()) are
  229. * LZMA_RUN, LZMA_SYNC_FLUSH, LZMA_FULL_FLUSH, and LZMA_FINISH. In future,
  230. * there may be compression levels or flags that don't support LZMA_SYNC_FLUSH.
  231. */
  232. extern LZMA_API(lzma_ret) lzma_easy_encoder(
  233. lzma_stream *strm, uint32_t preset, lzma_check check)
  234. lzma_nothrow lzma_attr_warn_unused_result;
  235. /**
  236. * \brief Single-call .xz Stream encoding using a preset number
  237. *
  238. * The maximum required output buffer size can be calculated with
  239. * lzma_stream_buffer_bound().
  240. *
  241. * \param preset Compression preset to use. See the description
  242. * in lzma_easy_encoder().
  243. * \param check Type of the integrity check to calculate from
  244. * uncompressed data.
  245. * \param allocator lzma_allocator for custom allocator functions.
  246. * Set to NULL to use malloc() and free().
  247. * \param in Beginning of the input buffer
  248. * \param in_size Size of the input buffer
  249. * \param out Beginning of the output buffer
  250. * \param out_pos The next byte will be written to out[*out_pos].
  251. * *out_pos is updated only if encoding succeeds.
  252. * \param out_size Size of the out buffer; the first byte into
  253. * which no data is written to is out[out_size].
  254. *
  255. * \return - LZMA_OK: Encoding was successful.
  256. * - LZMA_BUF_ERROR: Not enough output buffer space.
  257. * - LZMA_UNSUPPORTED_CHECK
  258. * - LZMA_OPTIONS_ERROR
  259. * - LZMA_MEM_ERROR
  260. * - LZMA_DATA_ERROR
  261. * - LZMA_PROG_ERROR
  262. */
  263. extern LZMA_API(lzma_ret) lzma_easy_buffer_encode(
  264. uint32_t preset, lzma_check check,
  265. const lzma_allocator *allocator,
  266. const uint8_t *in, size_t in_size,
  267. uint8_t *out, size_t *out_pos, size_t out_size) lzma_nothrow;
  268. /**
  269. * \brief Initialize .xz Stream encoder using a custom filter chain
  270. *
  271. * \param strm Pointer to properly prepared lzma_stream
  272. * \param filters Array of filters. This must be terminated with
  273. * filters[n].id = LZMA_VLI_UNKNOWN. See filter.h for
  274. * more information.
  275. * \param check Type of the integrity check to calculate from
  276. * uncompressed data.
  277. *
  278. * \return - LZMA_OK: Initialization was successful.
  279. * - LZMA_MEM_ERROR
  280. * - LZMA_UNSUPPORTED_CHECK
  281. * - LZMA_OPTIONS_ERROR
  282. * - LZMA_PROG_ERROR
  283. */
  284. extern LZMA_API(lzma_ret) lzma_stream_encoder(lzma_stream *strm,
  285. const lzma_filter *filters, lzma_check check)
  286. lzma_nothrow lzma_attr_warn_unused_result;
  287. /**
  288. * \brief Calculate approximate memory usage of multithreaded .xz encoder
  289. *
  290. * Since doing the encoding in threaded mode doesn't affect the memory
  291. * requirements of single-threaded decompressor, you can use
  292. * lzma_easy_decoder_memusage(options->preset) or
  293. * lzma_raw_decoder_memusage(options->filters) to calculate
  294. * the decompressor memory requirements.
  295. *
  296. * \param options Compression options
  297. *
  298. * \return Number of bytes of memory required for encoding with the
  299. * given options. If an error occurs, for example due to
  300. * unsupported preset or filter chain, UINT64_MAX is returned.
  301. */
  302. extern LZMA_API(uint64_t) lzma_stream_encoder_mt_memusage(
  303. const lzma_mt *options) lzma_nothrow lzma_attr_pure;
  304. /**
  305. * \brief Initialize multithreaded .xz Stream encoder
  306. *
  307. * This provides the functionality of lzma_easy_encoder() and
  308. * lzma_stream_encoder() as a single function for multithreaded use.
  309. *
  310. * The supported actions for lzma_code() are LZMA_RUN, LZMA_FULL_FLUSH,
  311. * LZMA_FULL_BARRIER, and LZMA_FINISH. Support for LZMA_SYNC_FLUSH might be
  312. * added in the future.
  313. *
  314. * \param strm Pointer to properly prepared lzma_stream
  315. * \param options Pointer to multithreaded compression options
  316. *
  317. * \return - LZMA_OK
  318. * - LZMA_MEM_ERROR
  319. * - LZMA_UNSUPPORTED_CHECK
  320. * - LZMA_OPTIONS_ERROR
  321. * - LZMA_PROG_ERROR
  322. */
  323. extern LZMA_API(lzma_ret) lzma_stream_encoder_mt(
  324. lzma_stream *strm, const lzma_mt *options)
  325. lzma_nothrow lzma_attr_warn_unused_result;
  326. /**
  327. * \brief Initialize .lzma encoder (legacy file format)
  328. *
  329. * The .lzma format is sometimes called the LZMA_Alone format, which is the
  330. * reason for the name of this function. The .lzma format supports only the
  331. * LZMA1 filter. There is no support for integrity checks like CRC32.
  332. *
  333. * Use this function if and only if you need to create files readable by
  334. * legacy LZMA tools such as LZMA Utils 4.32.x. Moving to the .xz format
  335. * is strongly recommended.
  336. *
  337. * The valid action values for lzma_code() are LZMA_RUN and LZMA_FINISH.
  338. * No kind of flushing is supported, because the file format doesn't make
  339. * it possible.
  340. *
  341. * \return - LZMA_OK
  342. * - LZMA_MEM_ERROR
  343. * - LZMA_OPTIONS_ERROR
  344. * - LZMA_PROG_ERROR
  345. */
  346. extern LZMA_API(lzma_ret) lzma_alone_encoder(
  347. lzma_stream *strm, const lzma_options_lzma *options)
  348. lzma_nothrow lzma_attr_warn_unused_result;
  349. /**
  350. * \brief Calculate output buffer size for single-call Stream encoder
  351. *
  352. * When trying to compress uncompressible data, the encoded size will be
  353. * slightly bigger than the input data. This function calculates how much
  354. * output buffer space is required to be sure that lzma_stream_buffer_encode()
  355. * doesn't return LZMA_BUF_ERROR.
  356. *
  357. * The calculated value is not exact, but it is guaranteed to be big enough.
  358. * The actual maximum output space required may be slightly smaller (up to
  359. * about 100 bytes). This should not be a problem in practice.
  360. *
  361. * If the calculated maximum size doesn't fit into size_t or would make the
  362. * Stream grow past LZMA_VLI_MAX (which should never happen in practice),
  363. * zero is returned to indicate the error.
  364. *
  365. * \note The limit calculated by this function applies only to
  366. * single-call encoding. Multi-call encoding may (and probably
  367. * will) have larger maximum expansion when encoding
  368. * uncompressible data. Currently there is no function to
  369. * calculate the maximum expansion of multi-call encoding.
  370. */
  371. extern LZMA_API(size_t) lzma_stream_buffer_bound(size_t uncompressed_size)
  372. lzma_nothrow;
  373. /**
  374. * \brief Single-call .xz Stream encoder
  375. *
  376. * \param filters Array of filters. This must be terminated with
  377. * filters[n].id = LZMA_VLI_UNKNOWN. See filter.h
  378. * for more information.
  379. * \param check Type of the integrity check to calculate from
  380. * uncompressed data.
  381. * \param allocator lzma_allocator for custom allocator functions.
  382. * Set to NULL to use malloc() and free().
  383. * \param in Beginning of the input buffer
  384. * \param in_size Size of the input buffer
  385. * \param out Beginning of the output buffer
  386. * \param out_pos The next byte will be written to out[*out_pos].
  387. * *out_pos is updated only if encoding succeeds.
  388. * \param out_size Size of the out buffer; the first byte into
  389. * which no data is written to is out[out_size].
  390. *
  391. * \return - LZMA_OK: Encoding was successful.
  392. * - LZMA_BUF_ERROR: Not enough output buffer space.
  393. * - LZMA_UNSUPPORTED_CHECK
  394. * - LZMA_OPTIONS_ERROR
  395. * - LZMA_MEM_ERROR
  396. * - LZMA_DATA_ERROR
  397. * - LZMA_PROG_ERROR
  398. */
  399. extern LZMA_API(lzma_ret) lzma_stream_buffer_encode(
  400. lzma_filter *filters, lzma_check check,
  401. const lzma_allocator *allocator,
  402. const uint8_t *in, size_t in_size,
  403. uint8_t *out, size_t *out_pos, size_t out_size)
  404. lzma_nothrow lzma_attr_warn_unused_result;
  405. /************
  406. * Decoding *
  407. ************/
  408. /**
  409. * This flag makes lzma_code() return LZMA_NO_CHECK if the input stream
  410. * being decoded has no integrity check. Note that when used with
  411. * lzma_auto_decoder(), all .lzma files will trigger LZMA_NO_CHECK
  412. * if LZMA_TELL_NO_CHECK is used.
  413. */
  414. #define LZMA_TELL_NO_CHECK UINT32_C(0x01)
  415. /**
  416. * This flag makes lzma_code() return LZMA_UNSUPPORTED_CHECK if the input
  417. * stream has an integrity check, but the type of the integrity check is not
  418. * supported by this liblzma version or build. Such files can still be
  419. * decoded, but the integrity check cannot be verified.
  420. */
  421. #define LZMA_TELL_UNSUPPORTED_CHECK UINT32_C(0x02)
  422. /**
  423. * This flag makes lzma_code() return LZMA_GET_CHECK as soon as the type
  424. * of the integrity check is known. The type can then be got with
  425. * lzma_get_check().
  426. */
  427. #define LZMA_TELL_ANY_CHECK UINT32_C(0x04)
  428. /**
  429. * This flag makes lzma_code() not calculate and verify the integrity check
  430. * of the compressed data in .xz files. This means that invalid integrity
  431. * check values won't be detected and LZMA_DATA_ERROR won't be returned in
  432. * such cases.
  433. *
  434. * This flag only affects the checks of the compressed data itself; the CRC32
  435. * values in the .xz headers will still be verified normally.
  436. *
  437. * Don't use this flag unless you know what you are doing. Possible reasons
  438. * to use this flag:
  439. *
  440. * - Trying to recover data from a corrupt .xz file.
  441. *
  442. * - Speeding up decompression, which matters mostly with SHA-256
  443. * or with files that have compressed extremely well. It's recommended
  444. * to not use this flag for this purpose unless the file integrity is
  445. * verified externally in some other way.
  446. *
  447. * Support for this flag was added in liblzma 5.1.4beta.
  448. */
  449. #define LZMA_IGNORE_CHECK UINT32_C(0x10)
  450. /**
  451. * This flag enables decoding of concatenated files with file formats that
  452. * allow concatenating compressed files as is. From the formats currently
  453. * supported by liblzma, only the .xz format allows concatenated files.
  454. * Concatenated files are not allowed with the legacy .lzma format.
  455. *
  456. * This flag also affects the usage of the `action' argument for lzma_code().
  457. * When LZMA_CONCATENATED is used, lzma_code() won't return LZMA_STREAM_END
  458. * unless LZMA_FINISH is used as `action'. Thus, the application has to set
  459. * LZMA_FINISH in the same way as it does when encoding.
  460. *
  461. * If LZMA_CONCATENATED is not used, the decoders still accept LZMA_FINISH
  462. * as `action' for lzma_code(), but the usage of LZMA_FINISH isn't required.
  463. */
  464. #define LZMA_CONCATENATED UINT32_C(0x08)
  465. /**
  466. * \brief Initialize .xz Stream decoder
  467. *
  468. * \param strm Pointer to properly prepared lzma_stream
  469. * \param memlimit Memory usage limit as bytes. Use UINT64_MAX
  470. * to effectively disable the limiter. liblzma
  471. * 5.2.3 and earlier don't allow 0 here and return
  472. * LZMA_PROG_ERROR; later versions treat 0 as if 1
  473. * had been specified.
  474. * \param flags Bitwise-or of zero or more of the decoder flags:
  475. * LZMA_TELL_NO_CHECK, LZMA_TELL_UNSUPPORTED_CHECK,
  476. * LZMA_TELL_ANY_CHECK, LZMA_CONCATENATED
  477. *
  478. * \return - LZMA_OK: Initialization was successful.
  479. * - LZMA_MEM_ERROR: Cannot allocate memory.
  480. * - LZMA_OPTIONS_ERROR: Unsupported flags
  481. * - LZMA_PROG_ERROR
  482. */
  483. extern LZMA_API(lzma_ret) lzma_stream_decoder(
  484. lzma_stream *strm, uint64_t memlimit, uint32_t flags)
  485. lzma_nothrow lzma_attr_warn_unused_result;
  486. /**
  487. * \brief Decode .xz Streams and .lzma files with autodetection
  488. *
  489. * This decoder autodetects between the .xz and .lzma file formats, and
  490. * calls lzma_stream_decoder() or lzma_alone_decoder() once the type
  491. * of the input file has been detected.
  492. *
  493. * \param strm Pointer to properly prepared lzma_stream
  494. * \param memlimit Memory usage limit as bytes. Use UINT64_MAX
  495. * to effectively disable the limiter. liblzma
  496. * 5.2.3 and earlier don't allow 0 here and return
  497. * LZMA_PROG_ERROR; later versions treat 0 as if 1
  498. * had been specified.
  499. * \param flags Bitwise-or of flags, or zero for no flags.
  500. *
  501. * \return - LZMA_OK: Initialization was successful.
  502. * - LZMA_MEM_ERROR: Cannot allocate memory.
  503. * - LZMA_OPTIONS_ERROR: Unsupported flags
  504. * - LZMA_PROG_ERROR
  505. */
  506. extern LZMA_API(lzma_ret) lzma_auto_decoder(
  507. lzma_stream *strm, uint64_t memlimit, uint32_t flags)
  508. lzma_nothrow lzma_attr_warn_unused_result;
  509. /**
  510. * \brief Initialize .lzma decoder (legacy file format)
  511. *
  512. * \param strm Pointer to properly prepared lzma_stream
  513. * \param memlimit Memory usage limit as bytes. Use UINT64_MAX
  514. * to effectively disable the limiter. liblzma
  515. * 5.2.3 and earlier don't allow 0 here and return
  516. * LZMA_PROG_ERROR; later versions treat 0 as if 1
  517. * had been specified.
  518. *
  519. * Valid `action' arguments to lzma_code() are LZMA_RUN and LZMA_FINISH.
  520. * There is no need to use LZMA_FINISH, but it's allowed because it may
  521. * simplify certain types of applications.
  522. *
  523. * \return - LZMA_OK
  524. * - LZMA_MEM_ERROR
  525. * - LZMA_PROG_ERROR
  526. */
  527. extern LZMA_API(lzma_ret) lzma_alone_decoder(
  528. lzma_stream *strm, uint64_t memlimit)
  529. lzma_nothrow lzma_attr_warn_unused_result;
  530. /**
  531. * \brief Single-call .xz Stream decoder
  532. *
  533. * \param memlimit Pointer to how much memory the decoder is allowed
  534. * to allocate. The value pointed by this pointer is
  535. * modified if and only if LZMA_MEMLIMIT_ERROR is
  536. * returned.
  537. * \param flags Bitwise-or of zero or more of the decoder flags:
  538. * LZMA_TELL_NO_CHECK, LZMA_TELL_UNSUPPORTED_CHECK,
  539. * LZMA_CONCATENATED. Note that LZMA_TELL_ANY_CHECK
  540. * is not allowed and will return LZMA_PROG_ERROR.
  541. * \param allocator lzma_allocator for custom allocator functions.
  542. * Set to NULL to use malloc() and free().
  543. * \param in Beginning of the input buffer
  544. * \param in_pos The next byte will be read from in[*in_pos].
  545. * *in_pos is updated only if decoding succeeds.
  546. * \param in_size Size of the input buffer; the first byte that
  547. * won't be read is in[in_size].
  548. * \param out Beginning of the output buffer
  549. * \param out_pos The next byte will be written to out[*out_pos].
  550. * *out_pos is updated only if decoding succeeds.
  551. * \param out_size Size of the out buffer; the first byte into
  552. * which no data is written to is out[out_size].
  553. *
  554. * \return - LZMA_OK: Decoding was successful.
  555. * - LZMA_FORMAT_ERROR
  556. * - LZMA_OPTIONS_ERROR
  557. * - LZMA_DATA_ERROR
  558. * - LZMA_NO_CHECK: This can be returned only if using
  559. * the LZMA_TELL_NO_CHECK flag.
  560. * - LZMA_UNSUPPORTED_CHECK: This can be returned only if using
  561. * the LZMA_TELL_UNSUPPORTED_CHECK flag.
  562. * - LZMA_MEM_ERROR
  563. * - LZMA_MEMLIMIT_ERROR: Memory usage limit was reached.
  564. * The minimum required memlimit value was stored to *memlimit.
  565. * - LZMA_BUF_ERROR: Output buffer was too small.
  566. * - LZMA_PROG_ERROR
  567. */
  568. extern LZMA_API(lzma_ret) lzma_stream_buffer_decode(
  569. uint64_t *memlimit, uint32_t flags,
  570. const lzma_allocator *allocator,
  571. const uint8_t *in, size_t *in_pos, size_t in_size,
  572. uint8_t *out, size_t *out_pos, size_t out_size)
  573. lzma_nothrow lzma_attr_warn_unused_result;