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 */ 41 typedef 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 */ 76 extern 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 */ 90 extern 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 */ 130 extern 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 */ 157 extern 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 */ 175 extern 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 */ 192 extern 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 */ 215 extern 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 */ 239 extern 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 */ 282 extern 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 */ 314 extern 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 */ 346 extern 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 */ 372 extern 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 */ 398 extern 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 */ 425 extern 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 */ 450 extern 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 */ 474 extern 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 */ 505 extern 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 */ 675 extern 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 */ 722 extern 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 */ 766 extern 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