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