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 */ 42 typedef 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 */ 77 extern 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 */ 91 extern 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 */ 131 extern 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 */ 158 extern 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 */ 176 extern 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 */ 193 extern 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 */ 216 extern 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 */ 240 extern 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 */ 283 extern 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 */ 315 extern 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 */ 347 extern 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 */ 373 extern 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 */ 399 extern 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 */ 426 extern 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 */ 451 extern 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 */ 475 extern 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 */ 506 extern 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 */ 676 extern 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 */ 723 extern 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 */ 767 extern 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