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

source code of include/lzma/filter.h