1/* SPDX-License-Identifier: 0BSD */
2
3/**
4 * \file lzma/filter.h
5 * \brief Common filter related types and functions
6 * \note Never include this file directly. Use <lzma.h> instead.
7 */
8
9/*
10 * Author: Lasse Collin
11 */
12
13#ifndef LZMA_H_INTERNAL
14# error Never include this file directly. Use <lzma.h> instead.
15#endif
16
17
18/**
19 * \brief Maximum number of filters in a chain
20 *
21 * A filter chain can have 1-4 filters, of which three are allowed to change
22 * the size of the data. Usually only one or two filters are needed.
23 */
24#define LZMA_FILTERS_MAX 4
25
26
27/**
28 * \brief Filter options
29 *
30 * This structure is used to pass a Filter ID and a pointer to the filter's
31 * options to liblzma. A few functions work with a single lzma_filter
32 * structure, while most functions expect a filter chain.
33 *
34 * A filter chain is indicated with an array of lzma_filter structures.
35 * The array is terminated with .id = LZMA_VLI_UNKNOWN. Thus, the filter
36 * array must have LZMA_FILTERS_MAX + 1 elements (that is, five) to
37 * be able to hold any arbitrary filter chain. This is important when
38 * using lzma_block_header_decode() from block.h, because a filter array
39 * that is too small would make liblzma write past the end of the array.
40 */
41typedef struct {
42 /**
43 * \brief Filter ID
44 *
45 * Use constants whose name begin with 'LZMA_FILTER_' to specify
46 * different filters. In an array of lzma_filter structures, use
47 * LZMA_VLI_UNKNOWN to indicate end of filters.
48 *
49 * \note This is not an enum, because on some systems enums
50 * cannot be 64-bit.
51 */
52 lzma_vli id;
53
54 /**
55 * \brief Pointer to filter-specific options structure
56 *
57 * If the filter doesn't need options, set this to NULL. If id is
58 * set to LZMA_VLI_UNKNOWN, options is ignored, and thus
59 * doesn't need be initialized.
60 */
61 void *options;
62
63} lzma_filter;
64
65
66/**
67 * \brief Test if the given Filter ID is supported for encoding
68 *
69 * \param id Filter ID
70 *
71 * \return lzma_bool:
72 * - true if the Filter ID is supported for encoding by this
73 * liblzma build.
74 * - false otherwise.
75 */
76extern LZMA_API(lzma_bool) lzma_filter_encoder_is_supported(lzma_vli id)
77 lzma_nothrow lzma_attr_const;
78
79
80/**
81 * \brief Test if the given Filter ID is supported for decoding
82 *
83 * \param id Filter ID
84 *
85 * \return lzma_bool:
86 * - true if the Filter ID is supported for decoding by this
87 * liblzma build.
88 * - false otherwise.
89 */
90extern LZMA_API(lzma_bool) lzma_filter_decoder_is_supported(lzma_vli id)
91 lzma_nothrow lzma_attr_const;
92
93
94/**
95 * \brief Copy the filters array
96 *
97 * Copy the Filter IDs and filter-specific options from src to dest.
98 * Up to LZMA_FILTERS_MAX filters are copied, plus the terminating
99 * .id == LZMA_VLI_UNKNOWN. Thus, dest should have at least
100 * LZMA_FILTERS_MAX + 1 elements space unless the caller knows that
101 * src is smaller than that.
102 *
103 * Unless the filter-specific options is NULL, the Filter ID has to be
104 * supported by liblzma, because liblzma needs to know the size of every
105 * filter-specific options structure. The filter-specific options are not
106 * validated. If options is NULL, any unsupported Filter IDs are copied
107 * without returning an error.
108 *
109 * Old filter-specific options in dest are not freed, so dest doesn't
110 * need to be initialized by the caller in any way.
111 *
112 * If an error occurs, memory possibly already allocated by this function
113 * is always freed. liblzma versions older than 5.2.7 may modify the dest
114 * array and leave its contents in an undefined state if an error occurs.
115 * liblzma 5.2.7 and newer only modify the dest array when returning LZMA_OK.
116 *
117 * \param src Array of filters terminated with
118 * .id == LZMA_VLI_UNKNOWN.
119 * \param[out] dest Destination filter array
120 * \param allocator lzma_allocator for custom allocator functions.
121 * Set to NULL to use malloc() and free().
122 *
123 * \return Possible lzma_ret values:
124 * - LZMA_OK
125 * - LZMA_MEM_ERROR
126 * - LZMA_OPTIONS_ERROR: Unsupported Filter ID and its options
127 * is not NULL.
128 * - LZMA_PROG_ERROR: src or dest is NULL.
129 */
130extern LZMA_API(lzma_ret) lzma_filters_copy(
131 const lzma_filter *src, lzma_filter *dest,
132 const lzma_allocator *allocator)
133 lzma_nothrow lzma_attr_warn_unused_result;
134
135
136/**
137 * \brief Free the options in the array of lzma_filter structures
138 *
139 * This frees the filter chain options. The filters array itself is not freed.
140 *
141 * The filters array must have at most LZMA_FILTERS_MAX + 1 elements
142 * including the terminating element which must have .id = LZMA_VLI_UNKNOWN.
143 * For all elements before the terminating element:
144 * - options will be freed using the given lzma_allocator or,
145 * if allocator is NULL, using free().
146 * - options will be set to NULL.
147 * - id will be set to LZMA_VLI_UNKNOWN.
148 *
149 * If filters is NULL, this does nothing. Again, this never frees the
150 * filters array itself.
151 *
152 * \param filters Array of filters terminated with
153 * .id == LZMA_VLI_UNKNOWN.
154 * \param allocator lzma_allocator for custom allocator functions.
155 * Set to NULL to use malloc() and free().
156 */
157extern LZMA_API(void) lzma_filters_free(
158 lzma_filter *filters, const lzma_allocator *allocator)
159 lzma_nothrow;
160
161
162/**
163 * \brief Calculate approximate memory requirements for raw encoder
164 *
165 * This function can be used to calculate the memory requirements for
166 * Block and Stream encoders too because Block and Stream encoders don't
167 * need significantly more memory than raw encoder.
168 *
169 * \param filters Array of filters terminated with
170 * .id == LZMA_VLI_UNKNOWN.
171 *
172 * \return Number of bytes of memory required for the given
173 * filter chain when encoding or UINT64_MAX on error.
174 */
175extern LZMA_API(uint64_t) lzma_raw_encoder_memusage(const lzma_filter *filters)
176 lzma_nothrow lzma_attr_pure;
177
178
179/**
180 * \brief Calculate approximate memory requirements for raw decoder
181 *
182 * This function can be used to calculate the memory requirements for
183 * Block and Stream decoders too because Block and Stream decoders don't
184 * need significantly more memory than raw decoder.
185 *
186 * \param filters Array of filters terminated with
187 * .id == LZMA_VLI_UNKNOWN.
188 *
189 * \return Number of bytes of memory required for the given
190 * filter chain when decoding or UINT64_MAX on error.
191 */
192extern LZMA_API(uint64_t) lzma_raw_decoder_memusage(const lzma_filter *filters)
193 lzma_nothrow lzma_attr_pure;
194
195
196/**
197 * \brief Initialize raw encoder
198 *
199 * This function may be useful when implementing custom file formats.
200 *
201 * The 'action' with lzma_code() can be LZMA_RUN, LZMA_SYNC_FLUSH (if the
202 * filter chain supports it), or LZMA_FINISH.
203 *
204 * \param strm Pointer to lzma_stream that is at least
205 * initialized with LZMA_STREAM_INIT.
206 * \param filters Array of filters terminated with
207 * .id == LZMA_VLI_UNKNOWN.
208 *
209 * \return Possible lzma_ret values:
210 * - LZMA_OK
211 * - LZMA_MEM_ERROR
212 * - LZMA_OPTIONS_ERROR
213 * - LZMA_PROG_ERROR
214 */
215extern LZMA_API(lzma_ret) lzma_raw_encoder(
216 lzma_stream *strm, const lzma_filter *filters)
217 lzma_nothrow lzma_attr_warn_unused_result;
218
219
220/**
221 * \brief Initialize raw decoder
222 *
223 * The initialization of raw decoder goes similarly to raw encoder.
224 *
225 * The 'action' with lzma_code() can be LZMA_RUN or LZMA_FINISH. Using
226 * LZMA_FINISH is not required, it is supported just for convenience.
227 *
228 * \param strm Pointer to lzma_stream that is at least
229 * initialized with LZMA_STREAM_INIT.
230 * \param filters Array of filters terminated with
231 * .id == LZMA_VLI_UNKNOWN.
232 *
233 * \return Possible lzma_ret values:
234 * - LZMA_OK
235 * - LZMA_MEM_ERROR
236 * - LZMA_OPTIONS_ERROR
237 * - LZMA_PROG_ERROR
238 */
239extern LZMA_API(lzma_ret) lzma_raw_decoder(
240 lzma_stream *strm, const lzma_filter *filters)
241 lzma_nothrow lzma_attr_warn_unused_result;
242
243
244/**
245 * \brief Update the filter chain in the encoder
246 *
247 * This function may be called after lzma_code() has returned LZMA_STREAM_END
248 * when LZMA_FULL_BARRIER, LZMA_FULL_FLUSH, or LZMA_SYNC_FLUSH was used:
249 *
250 * - After LZMA_FULL_BARRIER or LZMA_FULL_FLUSH: Single-threaded .xz Stream
251 * encoder (lzma_stream_encoder()) and (since liblzma 5.4.0) multi-threaded
252 * Stream encoder (lzma_stream_encoder_mt()) allow setting a new filter
253 * chain to be used for the next Block(s).
254 *
255 * - After LZMA_SYNC_FLUSH: Raw encoder (lzma_raw_encoder()),
256 * Block encoder (lzma_block_encoder()), and single-threaded .xz Stream
257 * encoder (lzma_stream_encoder()) allow changing certain filter-specific
258 * options in the middle of encoding. The actual filters in the chain
259 * (Filter IDs) must not be changed! Currently only the lc, lp, and pb
260 * options of LZMA2 (not LZMA1) can be changed this way.
261 *
262 * - In the future some filters might allow changing some of their options
263 * without any barrier or flushing but currently such filters don't exist.
264 *
265 * This function may also be called when no data has been compressed yet
266 * although this is rarely useful. In that case, this function will behave
267 * as if LZMA_FULL_FLUSH (Stream encoders) or LZMA_SYNC_FLUSH (Raw or Block
268 * encoder) had been used right before calling this function.
269 *
270 * \param strm Pointer to lzma_stream that is at least
271 * initialized with LZMA_STREAM_INIT.
272 * \param filters Array of filters terminated with
273 * .id == LZMA_VLI_UNKNOWN.
274 *
275 * \return Possible lzma_ret values:
276 * - LZMA_OK
277 * - LZMA_MEM_ERROR
278 * - LZMA_MEMLIMIT_ERROR
279 * - LZMA_OPTIONS_ERROR
280 * - LZMA_PROG_ERROR
281 */
282extern LZMA_API(lzma_ret) lzma_filters_update(
283 lzma_stream *strm, const lzma_filter *filters) lzma_nothrow;
284
285
286/**
287 * \brief Single-call raw encoder
288 *
289 * \note There is no function to calculate how big output buffer
290 * would surely be big enough. (lzma_stream_buffer_bound()
291 * works only for lzma_stream_buffer_encode(); raw encoder
292 * won't necessarily meet that bound.)
293 *
294 * \param filters Array of filters terminated with
295 * .id == LZMA_VLI_UNKNOWN.
296 * \param allocator lzma_allocator for custom allocator functions.
297 * Set to NULL to use malloc() and free().
298 * \param in Beginning of the input buffer
299 * \param in_size Size of the input buffer
300 * \param[out] out Beginning of the output buffer
301 * \param[out] out_pos The next byte will be written to out[*out_pos].
302 * *out_pos is updated only if encoding succeeds.
303 * \param out_size Size of the out buffer; the first byte into
304 * which no data is written to is out[out_size].
305 *
306 * \return Possible lzma_ret values:
307 * - LZMA_OK: Encoding was successful.
308 * - LZMA_BUF_ERROR: Not enough output buffer space.
309 * - LZMA_OPTIONS_ERROR
310 * - LZMA_MEM_ERROR
311 * - LZMA_DATA_ERROR
312 * - LZMA_PROG_ERROR
313 */
314extern LZMA_API(lzma_ret) lzma_raw_buffer_encode(
315 const lzma_filter *filters, const lzma_allocator *allocator,
316 const uint8_t *in, size_t in_size, uint8_t *out,
317 size_t *out_pos, size_t out_size) lzma_nothrow;
318
319
320/**
321 * \brief Single-call raw decoder
322 *
323 * \param filters Array of filters terminated with
324 * .id == LZMA_VLI_UNKNOWN.
325 * \param allocator lzma_allocator for custom allocator functions.
326 * Set to NULL to use malloc() and free().
327 * \param in Beginning of the input buffer
328 * \param in_pos The next byte will be read from in[*in_pos].
329 * *in_pos is updated only if decoding succeeds.
330 * \param in_size Size of the input buffer; the first byte that
331 * won't be read is in[in_size].
332 * \param[out] out Beginning of the output buffer
333 * \param[out] out_pos The next byte will be written to out[*out_pos].
334 * *out_pos is updated only if encoding succeeds.
335 * \param out_size Size of the out buffer; the first byte into
336 * which no data is written to is out[out_size].
337 *
338 * \return Possible lzma_ret values:
339 * - LZMA_OK: Decoding was successful.
340 * - LZMA_BUF_ERROR: Not enough output buffer space.
341 * - LZMA_OPTIONS_ERROR
342 * - LZMA_MEM_ERROR
343 * - LZMA_DATA_ERROR
344 * - LZMA_PROG_ERROR
345 */
346extern LZMA_API(lzma_ret) lzma_raw_buffer_decode(
347 const lzma_filter *filters, const lzma_allocator *allocator,
348 const uint8_t *in, size_t *in_pos, size_t in_size,
349 uint8_t *out, size_t *out_pos, size_t out_size) lzma_nothrow;
350
351
352/**
353 * \brief Get the size of the Filter Properties field
354 *
355 * This function may be useful when implementing custom file formats
356 * using the raw encoder and decoder.
357 *
358 * \note This function validates the Filter ID, but does not
359 * necessarily validate the options. Thus, it is possible
360 * that this returns LZMA_OK while the following call to
361 * lzma_properties_encode() returns LZMA_OPTIONS_ERROR.
362 *
363 * \param[out] size Pointer to uint32_t to hold the size of the properties
364 * \param filter Filter ID and options (the size of the properties may
365 * vary depending on the options)
366 *
367 * \return Possible lzma_ret values:
368 * - LZMA_OK
369 * - LZMA_OPTIONS_ERROR
370 * - LZMA_PROG_ERROR
371 */
372extern LZMA_API(lzma_ret) lzma_properties_size(
373 uint32_t *size, const lzma_filter *filter) lzma_nothrow;
374
375
376/**
377 * \brief Encode the Filter Properties field
378 *
379 * \note Even this function won't validate more options than actually
380 * necessary. Thus, it is possible that encoding the properties
381 * succeeds but using the same options to initialize the encoder
382 * will fail.
383 *
384 * \note If lzma_properties_size() indicated that the size
385 * of the Filter Properties field is zero, calling
386 * lzma_properties_encode() is not required, but it
387 * won't do any harm either.
388 *
389 * \param filter Filter ID and options
390 * \param[out] props Buffer to hold the encoded options. The size of
391 * the buffer must have been already determined with
392 * lzma_properties_size().
393 *
394 * \return Possible lzma_ret values:
395 * - LZMA_OK
396 * - LZMA_PROG_ERROR
397 */
398extern LZMA_API(lzma_ret) lzma_properties_encode(
399 const lzma_filter *filter, uint8_t *props) lzma_nothrow;
400
401
402/**
403 * \brief Decode the Filter Properties field
404 *
405 * \param filter filter->id must have been set to the correct
406 * Filter ID. filter->options doesn't need to be
407 * initialized (it's not freed by this function). The
408 * decoded options will be stored in filter->options;
409 * it's application's responsibility to free it when
410 * appropriate. filter->options is set to NULL if
411 * there are no properties or if an error occurs.
412 * \param allocator lzma_allocator for custom allocator functions.
413 * Set to NULL to use malloc() and free().
414 * and in case of an error, also free().
415 * \param props Input buffer containing the properties.
416 * \param props_size Size of the properties. This must be the exact
417 * size; giving too much or too little input will
418 * return LZMA_OPTIONS_ERROR.
419 *
420 * \return Possible lzma_ret values:
421 * - LZMA_OK
422 * - LZMA_OPTIONS_ERROR
423 * - LZMA_MEM_ERROR
424 */
425extern LZMA_API(lzma_ret) lzma_properties_decode(
426 lzma_filter *filter, const lzma_allocator *allocator,
427 const uint8_t *props, size_t props_size) lzma_nothrow;
428
429
430/**
431 * \brief Calculate encoded size of a Filter Flags field
432 *
433 * Knowing the size of Filter Flags is useful to know when allocating
434 * memory to hold the encoded Filter Flags.
435 *
436 * \note If you need to calculate size of List of Filter Flags,
437 * you need to loop over every lzma_filter entry.
438 *
439 * \param[out] size Pointer to integer to hold the calculated size
440 * \param filter Filter ID and associated options whose encoded
441 * size is to be calculated
442 *
443 * \return Possible lzma_ret values:
444 * - LZMA_OK: *size set successfully. Note that this doesn't
445 * guarantee that filter->options is valid, thus
446 * lzma_filter_flags_encode() may still fail.
447 * - LZMA_OPTIONS_ERROR: Unknown Filter ID or unsupported options.
448 * - LZMA_PROG_ERROR: Invalid options
449 */
450extern LZMA_API(lzma_ret) lzma_filter_flags_size(
451 uint32_t *size, const lzma_filter *filter)
452 lzma_nothrow lzma_attr_warn_unused_result;
453
454
455/**
456 * \brief Encode Filter Flags into given buffer
457 *
458 * In contrast to some functions, this doesn't allocate the needed buffer.
459 * This is due to how this function is used internally by liblzma.
460 *
461 * \param filter Filter ID and options to be encoded
462 * \param[out] out Beginning of the output buffer
463 * \param[out] out_pos out[*out_pos] is the next write position. This
464 * is updated by the encoder.
465 * \param out_size out[out_size] is the first byte to not write.
466 *
467 * \return Possible lzma_ret values:
468 * - LZMA_OK: Encoding was successful.
469 * - LZMA_OPTIONS_ERROR: Invalid or unsupported options.
470 * - LZMA_PROG_ERROR: Invalid options or not enough output
471 * buffer space (you should have checked it with
472 * lzma_filter_flags_size()).
473 */
474extern LZMA_API(lzma_ret) lzma_filter_flags_encode(const lzma_filter *filter,
475 uint8_t *out, size_t *out_pos, size_t out_size)
476 lzma_nothrow lzma_attr_warn_unused_result;
477
478
479/**
480 * \brief Decode Filter Flags from given buffer
481 *
482 * The decoded result is stored into *filter. The old value of
483 * filter->options is not free()d. If anything other than LZMA_OK
484 * is returned, filter->options is set to NULL.
485 *
486 * \param[out] filter Destination filter. The decoded Filter ID will
487 * be stored in filter->id. If options are needed
488 * they will be allocated and the pointer will be
489 * stored in filter->options.
490 * \param allocator lzma_allocator for custom allocator functions.
491 * Set to NULL to use malloc() and free().
492 * \param in Beginning of the input buffer
493 * \param[out] in_pos The next byte will be read from in[*in_pos].
494 * *in_pos is updated only if decoding succeeds.
495 * \param in_size Size of the input buffer; the first byte that
496 * won't be read is in[in_size].
497 *
498 * \return Possible lzma_ret values:
499 * - LZMA_OK
500 * - LZMA_OPTIONS_ERROR
501 * - LZMA_MEM_ERROR
502 * - LZMA_DATA_ERROR
503 * - LZMA_PROG_ERROR
504 */
505extern LZMA_API(lzma_ret) lzma_filter_flags_decode(
506 lzma_filter *filter, const lzma_allocator *allocator,
507 const uint8_t *in, size_t *in_pos, size_t in_size)
508 lzma_nothrow lzma_attr_warn_unused_result;
509
510
511/***********
512 * Strings *
513 ***********/
514
515/**
516 * \brief Allow or show all filters
517 *
518 * By default only the filters supported in the .xz format are accept by
519 * lzma_str_to_filters() or shown by lzma_str_list_filters().
520 */
521#define LZMA_STR_ALL_FILTERS UINT32_C(0x01)
522
523
524/**
525 * \brief Do not validate the filter chain in lzma_str_to_filters()
526 *
527 * By default lzma_str_to_filters() can return an error if the filter chain
528 * as a whole isn't usable in the .xz format or in the raw encoder or decoder.
529 * With this flag, this validation is skipped. This flag doesn't affect the
530 * handling of the individual filter options. To allow non-.xz filters also
531 * LZMA_STR_ALL_FILTERS is needed.
532 */
533#define LZMA_STR_NO_VALIDATION UINT32_C(0x02)
534
535
536/**
537 * \brief Stringify encoder options
538 *
539 * Show the filter-specific options that the encoder will use.
540 * This may be useful for verbose diagnostic messages.
541 *
542 * Note that if options were decoded from .xz headers then the encoder options
543 * may be undefined. This flag shouldn't be used in such a situation.
544 */
545#define LZMA_STR_ENCODER UINT32_C(0x10)
546
547
548/**
549 * \brief Stringify decoder options
550 *
551 * Show the filter-specific options that the decoder will use.
552 * This may be useful for showing what filter options were decoded
553 * from file headers.
554 */
555#define LZMA_STR_DECODER UINT32_C(0x20)
556
557
558/**
559 * \brief Produce xz-compatible getopt_long() syntax
560 *
561 * That is, "delta:dist=2 lzma2:dict=4MiB,pb=1,lp=1" becomes
562 * "--delta=dist=2 --lzma2=dict=4MiB,pb=1,lp=1".
563 *
564 * This syntax is compatible with xz 5.0.0 as long as the filters and
565 * their options are supported too.
566 */
567#define LZMA_STR_GETOPT_LONG UINT32_C(0x40)
568
569
570/**
571 * \brief Use two dashes "--" instead of a space to separate filters
572 *
573 * That is, "delta:dist=2 lzma2:pb=1,lp=1" becomes
574 * "delta:dist=2--lzma2:pb=1,lp=1". This looks slightly odd but this
575 * kind of strings should be usable on the command line without quoting.
576 * However, it is possible that future versions with new filter options
577 * might produce strings that require shell quoting anyway as the exact
578 * set of possible characters isn't frozen for now.
579 *
580 * It is guaranteed that the single quote (') will never be used in
581 * filter chain strings (even if LZMA_STR_NO_SPACES isn't used).
582 */
583#define LZMA_STR_NO_SPACES UINT32_C(0x80)
584
585
586/**
587 * \brief Convert a string to a filter chain
588 *
589 * This tries to make it easier to write applications that allow users
590 * to set custom compression options. This only handles the filter
591 * configuration (including presets) but not the number of threads,
592 * block size, check type, or memory limits.
593 *
594 * The input string can be either a preset or a filter chain. Presets
595 * begin with a digit 0-9 and may be followed by zero or more flags
596 * which are lower-case letters. Currently only "e" is supported, matching
597 * LZMA_PRESET_EXTREME. For partial xz command line syntax compatibility,
598 * a preset string may start with a single dash "-".
599 *
600 * A filter chain consists of one or more "filtername:opt1=value1,opt2=value2"
601 * strings separated by one or more spaces. Leading and trailing spaces are
602 * ignored. All names and values must be lower-case. Extra commas in the
603 * option list are ignored. The order of filters is significant: when
604 * encoding, the uncompressed input data goes to the leftmost filter first.
605 * Normally "lzma2" is the last filter in the chain.
606 *
607 * If one wishes to avoid spaces, for example, to avoid shell quoting,
608 * it is possible to use two dashes "--" instead of spaces to separate
609 * the filters.
610 *
611 * For xz command line compatibility, each filter may be prefixed with
612 * two dashes "--" and the colon ":" separating the filter name from
613 * the options may be replaced with an equals sign "=".
614 *
615 * By default, only filters that can be used in the .xz format are accepted.
616 * To allow all filters (LZMA1) use the flag LZMA_STR_ALL_FILTERS.
617 *
618 * By default, very basic validation is done for the filter chain as a whole,
619 * for example, that LZMA2 is only used as the last filter in the chain.
620 * The validation isn't perfect though and it's possible that this function
621 * succeeds but using the filter chain for encoding or decoding will still
622 * result in LZMA_OPTIONS_ERROR. To disable this validation, use the flag
623 * LZMA_STR_NO_VALIDATION.
624 *
625 * The available filter names and their options are available via
626 * lzma_str_list_filters(). See the xz man page for the description
627 * of filter names and options.
628 *
629 * For command line applications, below is an example how an error message
630 * can be displayed. Note the use of an empty string for the field width.
631 * If "^" was used there it would create an off-by-one error except at
632 * the very beginning of the line.
633 *
634 * \code{.c}
635 * const char *str = ...; // From user
636 * lzma_filter filters[LZMA_FILTERS_MAX + 1];
637 * int pos;
638 * const char *msg = lzma_str_to_filters(str, &pos, filters, 0, NULL);
639 * if (msg != NULL) {
640 * printf("%s: Error in XZ compression options:\n", argv[0]);
641 * printf("%s: %s\n", argv[0], str);
642 * printf("%s: %*s^\n", argv[0], errpos, "");
643 * printf("%s: %s\n", argv[0], msg);
644 * }
645 * \endcode
646 *
647 * \param str User-supplied string describing a preset or
648 * a filter chain. If a default value is needed and
649 * you don't know what would be good, use "6" since
650 * that is the default preset in xz too.
651 * \param[out] error_pos If this isn't NULL, this value will be set on
652 * both success and on all errors. This tells the
653 * location of the error in the string. This is
654 * an int to make it straightforward to use this
655 * as printf() field width. The value is guaranteed
656 * to be in the range [0, INT_MAX] even if strlen(str)
657 * somehow was greater than INT_MAX.
658 * \param[out] filters An array of lzma_filter structures. There must
659 * be LZMA_FILTERS_MAX + 1 (that is, five) elements
660 * in the array. The old contents are ignored so it
661 * doesn't need to be initialized. This array is
662 * modified only if this function returns NULL.
663 * Once the allocated filter options are no longer
664 * needed, lzma_filters_free() can be used to free the
665 * options (it doesn't free the filters array itself).
666 * \param flags Bitwise-or of zero or more of the flags
667 * LZMA_STR_ALL_FILTERS and LZMA_STR_NO_VALIDATION.
668 * \param allocator lzma_allocator for custom allocator functions.
669 * Set to NULL to use malloc() and free().
670 *
671 * \return On success, NULL is returned. On error, a statically-allocated
672 * error message is returned which together with the error_pos
673 * should give some idea what is wrong.
674 */
675extern LZMA_API(const char *) lzma_str_to_filters(
676 const char *str, int *error_pos, lzma_filter *filters,
677 uint32_t flags, const lzma_allocator *allocator)
678 lzma_nothrow lzma_attr_warn_unused_result;
679
680
681/**
682 * \brief Convert a filter chain to a string
683 *
684 * Use cases:
685 *
686 * - Verbose output showing the full encoder options to the user
687 * (use LZMA_STR_ENCODER in flags)
688 *
689 * - Showing the filters and options that are required to decode a file
690 * (use LZMA_STR_DECODER in flags)
691 *
692 * - Showing the filter names without any options in informational messages
693 * where the technical details aren't important (no flags). In this case
694 * the .options in the filters array are ignored and may be NULL even if
695 * a filter has a mandatory options structure.
696 *
697 * Note that even if the filter chain was specified using a preset,
698 * the resulting filter chain isn't reversed to a preset. So if you
699 * specify "6" to lzma_str_to_filters() then lzma_str_from_filters()
700 * will produce a string containing "lzma2".
701 *
702 * \param[out] str On success *str will be set to point to an
703 * allocated string describing the given filter
704 * chain. Old value is ignored. On error *str is
705 * always set to NULL.
706 * \param filters Array of filters terminated with
707 * .id == LZMA_VLI_UNKNOWN.
708 * \param flags Bitwise-or of zero or more of the flags
709 * LZMA_STR_ENCODER, LZMA_STR_DECODER,
710 * LZMA_STR_GETOPT_LONG, and LZMA_STR_NO_SPACES.
711 * \param allocator lzma_allocator for custom allocator functions.
712 * Set to NULL to use malloc() and free().
713 *
714 * \return Possible lzma_ret values:
715 * - LZMA_OK
716 * - LZMA_OPTIONS_ERROR: Empty filter chain
717 * (filters[0].id == LZMA_VLI_UNKNOWN) or the filter chain
718 * includes a Filter ID that is not supported by this function.
719 * - LZMA_MEM_ERROR
720 * - LZMA_PROG_ERROR
721 */
722extern LZMA_API(lzma_ret) lzma_str_from_filters(
723 char **str, const lzma_filter *filters, uint32_t flags,
724 const lzma_allocator *allocator)
725 lzma_nothrow lzma_attr_warn_unused_result;
726
727
728/**
729 * \brief List available filters and/or their options (for help message)
730 *
731 * If a filter_id is given then only one line is created which contains the
732 * filter name. If LZMA_STR_ENCODER or LZMA_STR_DECODER is used then the
733 * options read by the encoder or decoder are printed on the same line.
734 *
735 * If filter_id is LZMA_VLI_UNKNOWN then all supported .xz-compatible filters
736 * are listed:
737 *
738 * - If neither LZMA_STR_ENCODER nor LZMA_STR_DECODER is used then
739 * the supported filter names are listed on a single line separated
740 * by spaces.
741 *
742 * - If LZMA_STR_ENCODER or LZMA_STR_DECODER is used then filters and
743 * the supported options are listed one filter per line. There won't
744 * be a newline after the last filter.
745 *
746 * - If LZMA_STR_ALL_FILTERS is used then the list will include also
747 * those filters that cannot be used in the .xz format (LZMA1).
748 *
749 * \param str On success *str will be set to point to an
750 * allocated string listing the filters and options.
751 * Old value is ignored. On error *str is always set
752 * to NULL.
753 * \param filter_id Filter ID or LZMA_VLI_UNKNOWN.
754 * \param flags Bitwise-or of zero or more of the flags
755 * LZMA_STR_ALL_FILTERS, LZMA_STR_ENCODER,
756 * LZMA_STR_DECODER, and LZMA_STR_GETOPT_LONG.
757 * \param allocator lzma_allocator for custom allocator functions.
758 * Set to NULL to use malloc() and free().
759 *
760 * \return Possible lzma_ret values:
761 * - LZMA_OK
762 * - LZMA_OPTIONS_ERROR: Unsupported filter_id or flags
763 * - LZMA_MEM_ERROR
764 * - LZMA_PROG_ERROR
765 */
766extern LZMA_API(lzma_ret) lzma_str_list_filters(
767 char **str, lzma_vli filter_id, uint32_t flags,
768 const lzma_allocator *allocator)
769 lzma_nothrow lzma_attr_warn_unused_result;
770