From 351f0da2d06cbc2ea571a813f8ae05436472a8dd Mon Sep 17 00:00:00 2001 From: Bertrand Jacquin Date: Fri, 29 Mar 2024 19:53:25 +0000 Subject: CVE-2024-3094: doxygen --- doc/api/COPYING.CC-BY-SA-4.0 | 427 +++++ doc/api/annotated.html | 74 + doc/api/base_8h.html | 634 +++++++ doc/api/bc_s.png | Bin 0 -> 675 bytes doc/api/bc_sd.png | Bin 0 -> 604 bytes doc/api/bcj_8h.html | 115 ++ doc/api/block_8h.html | 860 +++++++++ doc/api/check_8h.html | 386 ++++ doc/api/classes.html | 66 + doc/api/closed.png | Bin 0 -> 132 bytes doc/api/container_8h.html | 1469 +++++++++++++++ doc/api/delta_8h.html | 138 ++ doc/api/dir_b17a1d403082bd69a703ed987cf158fb.html | 110 ++ doc/api/doc.svg | 12 + doc/api/docd.svg | 12 + doc/api/doxygen.css | 2045 +++++++++++++++++++++ doc/api/doxygen.svg | 28 + doc/api/files.html | 80 + doc/api/filter_8h.html | 1508 +++++++++++++++ doc/api/folderclosed.svg | 11 + doc/api/folderclosedd.svg | 11 + doc/api/folderopen.svg | 17 + doc/api/folderopend.svg | 12 + doc/api/functions.html | 216 +++ doc/api/functions_vars.html | 216 +++ doc/api/globals.html | 284 +++ doc/api/globals_defs.html | 130 ++ doc/api/globals_enum.html | 77 + doc/api/globals_eval.html | 109 ++ doc/api/globals_func.html | 184 ++ doc/api/globals_type.html | 74 + doc/api/hardware_8h.html | 145 ++ doc/api/index.html | 60 + doc/api/index_8h.html | 1519 +++++++++++++++ doc/api/index__hash_8h.html | 357 ++++ doc/api/lzma12_8h.html | 466 +++++ doc/api/lzma_8h.html | 115 ++ doc/api/minus.svg | 8 + doc/api/minusd.svg | 8 + doc/api/nav_f.png | Bin 0 -> 167 bytes doc/api/nav_fd.png | Bin 0 -> 144 bytes doc/api/nav_g.png | Bin 0 -> 95 bytes doc/api/nav_h.png | Bin 0 -> 97 bytes doc/api/nav_hd.png | Bin 0 -> 104 bytes doc/api/open.png | Bin 0 -> 121 bytes doc/api/plus.svg | 9 + doc/api/plusd.svg | 9 + doc/api/splitbar.png | Bin 0 -> 309 bytes doc/api/splitbard.png | Bin 0 -> 278 bytes doc/api/stream__flags_8h.html | 394 ++++ doc/api/structlzma__allocator.html | 159 ++ doc/api/structlzma__block.html | 353 ++++ doc/api/structlzma__filter.html | 120 ++ doc/api/structlzma__index__iter.html | 413 +++++ doc/api/structlzma__mt.html | 262 +++ doc/api/structlzma__options__bcj.html | 101 + doc/api/structlzma__options__delta.html | 119 ++ doc/api/structlzma__options__lzma.html | 369 ++++ doc/api/structlzma__stream.html | 257 +++ doc/api/structlzma__stream__flags.html | 140 ++ doc/api/sync_off.png | Bin 0 -> 857 bytes doc/api/sync_on.png | Bin 0 -> 851 bytes doc/api/tab_a.png | Bin 0 -> 135 bytes doc/api/tab_ad.png | Bin 0 -> 133 bytes doc/api/tab_b.png | Bin 0 -> 178 bytes doc/api/tab_bd.png | Bin 0 -> 157 bytes doc/api/tab_h.png | Bin 0 -> 179 bytes doc/api/tab_hd.png | Bin 0 -> 168 bytes doc/api/tab_s.png | Bin 0 -> 208 bytes doc/api/tab_sd.png | Bin 0 -> 171 bytes doc/api/tabs.css | 68 + doc/api/version_8h.html | 261 +++ doc/api/vli_8h.html | 353 ++++ doc/api/xz-logo.png | Bin 0 -> 6771 bytes 74 files changed, 15370 insertions(+) create mode 100644 doc/api/COPYING.CC-BY-SA-4.0 create mode 100644 doc/api/annotated.html create mode 100644 doc/api/base_8h.html create mode 100644 doc/api/bc_s.png create mode 100644 doc/api/bc_sd.png create mode 100644 doc/api/bcj_8h.html create mode 100644 doc/api/block_8h.html create mode 100644 doc/api/check_8h.html create mode 100644 doc/api/classes.html create mode 100644 doc/api/closed.png create mode 100644 doc/api/container_8h.html create mode 100644 doc/api/delta_8h.html create mode 100644 doc/api/dir_b17a1d403082bd69a703ed987cf158fb.html create mode 100644 doc/api/doc.svg create mode 100644 doc/api/docd.svg create mode 100644 doc/api/doxygen.css create mode 100644 doc/api/doxygen.svg create mode 100644 doc/api/files.html create mode 100644 doc/api/filter_8h.html create mode 100644 doc/api/folderclosed.svg create mode 100644 doc/api/folderclosedd.svg create mode 100644 doc/api/folderopen.svg create mode 100644 doc/api/folderopend.svg create mode 100644 doc/api/functions.html create mode 100644 doc/api/functions_vars.html create mode 100644 doc/api/globals.html create mode 100644 doc/api/globals_defs.html create mode 100644 doc/api/globals_enum.html create mode 100644 doc/api/globals_eval.html create mode 100644 doc/api/globals_func.html create mode 100644 doc/api/globals_type.html create mode 100644 doc/api/hardware_8h.html create mode 100644 doc/api/index.html create mode 100644 doc/api/index_8h.html create mode 100644 doc/api/index__hash_8h.html create mode 100644 doc/api/lzma12_8h.html create mode 100644 doc/api/lzma_8h.html create mode 100644 doc/api/minus.svg create mode 100644 doc/api/minusd.svg create mode 100644 doc/api/nav_f.png create mode 100644 doc/api/nav_fd.png create mode 100644 doc/api/nav_g.png create mode 100644 doc/api/nav_h.png create mode 100644 doc/api/nav_hd.png create mode 100644 doc/api/open.png create mode 100644 doc/api/plus.svg create mode 100644 doc/api/plusd.svg create mode 100644 doc/api/splitbar.png create mode 100644 doc/api/splitbard.png create mode 100644 doc/api/stream__flags_8h.html create mode 100644 doc/api/structlzma__allocator.html create mode 100644 doc/api/structlzma__block.html create mode 100644 doc/api/structlzma__filter.html create mode 100644 doc/api/structlzma__index__iter.html create mode 100644 doc/api/structlzma__mt.html create mode 100644 doc/api/structlzma__options__bcj.html create mode 100644 doc/api/structlzma__options__delta.html create mode 100644 doc/api/structlzma__options__lzma.html create mode 100644 doc/api/structlzma__stream.html create mode 100644 doc/api/structlzma__stream__flags.html create mode 100644 doc/api/sync_off.png create mode 100644 doc/api/sync_on.png create mode 100644 doc/api/tab_a.png create mode 100644 doc/api/tab_ad.png create mode 100644 doc/api/tab_b.png create mode 100644 doc/api/tab_bd.png create mode 100644 doc/api/tab_h.png create mode 100644 doc/api/tab_hd.png create mode 100644 doc/api/tab_s.png create mode 100644 doc/api/tab_sd.png create mode 100644 doc/api/tabs.css create mode 100644 doc/api/version_8h.html create mode 100644 doc/api/vli_8h.html create mode 100644 doc/api/xz-logo.png (limited to 'doc/api') diff --git a/doc/api/COPYING.CC-BY-SA-4.0 b/doc/api/COPYING.CC-BY-SA-4.0 new file mode 100644 index 00000000..7d4f96c5 --- /dev/null +++ b/doc/api/COPYING.CC-BY-SA-4.0 @@ -0,0 +1,427 @@ +Attribution-ShareAlike 4.0 International + +======================================================================= + +Creative Commons Corporation ("Creative Commons") is not a law firm and +does not provide legal services or legal advice. Distribution of +Creative Commons public licenses does not create a lawyer-client or +other relationship. Creative Commons makes its licenses and related +information available on an "as-is" basis. Creative Commons gives no +warranties regarding its licenses, any material licensed under their +terms and conditions, or any related information. Creative Commons +disclaims all liability for damages resulting from their use to the +fullest extent possible. + +Using Creative Commons Public Licenses + +Creative Commons public licenses provide a standard set of terms and +conditions that creators and other rights holders may use to share +original works of authorship and other material subject to copyright +and certain other rights specified in the public license below. The +following considerations are for informational purposes only, are not +exhaustive, and do not form part of our licenses. + + Considerations for licensors: Our public licenses are + intended for use by those authorized to give the public + permission to use material in ways otherwise restricted by + copyright and certain other rights. Our licenses are + irrevocable. Licensors should read and understand the terms + and conditions of the license they choose before applying it. + Licensors should also secure all rights necessary before + applying our licenses so that the public can reuse the + material as expected. Licensors should clearly mark any + material not subject to the license. This includes other CC- + licensed material, or material used under an exception or + limitation to copyright. More considerations for licensors: + wiki.creativecommons.org/Considerations_for_licensors + + Considerations for the public: By using one of our public + licenses, a licensor grants the public permission to use the + licensed material under specified terms and conditions. If + the licensor's permission is not necessary for any reason--for + example, because of any applicable exception or limitation to + copyright--then that use is not regulated by the license. Our + licenses grant only permissions under copyright and certain + other rights that a licensor has authority to grant. Use of + the licensed material may still be restricted for other + reasons, including because others have copyright or other + rights in the material. A licensor may make special requests, + such as asking that all changes be marked or described. + Although not required by our licenses, you are encouraged to + respect those requests where reasonable. More considerations + for the public: + wiki.creativecommons.org/Considerations_for_licensees + +======================================================================= + +Creative Commons Attribution-ShareAlike 4.0 International Public +License + +By exercising the Licensed Rights (defined below), You accept and agree +to be bound by the terms and conditions of this Creative Commons +Attribution-ShareAlike 4.0 International Public License ("Public +License"). To the extent this Public License may be interpreted as a +contract, You are granted the Licensed Rights in consideration of Your +acceptance of these terms and conditions, and the Licensor grants You +such rights in consideration of benefits the Licensor receives from +making the Licensed Material available under these terms and +conditions. + + +Section 1 -- Definitions. + + a. Adapted Material means material subject to Copyright and Similar + Rights that is derived from or based upon the Licensed Material + and in which the Licensed Material is translated, altered, + arranged, transformed, or otherwise modified in a manner requiring + permission under the Copyright and Similar Rights held by the + Licensor. For purposes of this Public License, where the Licensed + Material is a musical work, performance, or sound recording, + Adapted Material is always produced where the Licensed Material is + synched in timed relation with a moving image. + + b. Adapter's License means the license You apply to Your Copyright + and Similar Rights in Your contributions to Adapted Material in + accordance with the terms and conditions of this Public License. + + c. BY-SA Compatible License means a license listed at + creativecommons.org/compatiblelicenses, approved by Creative + Commons as essentially the equivalent of this Public License. + + d. Copyright and Similar Rights means copyright and/or similar rights + closely related to copyright including, without limitation, + performance, broadcast, sound recording, and Sui Generis Database + Rights, without regard to how the rights are labeled or + categorized. For purposes of this Public License, the rights + specified in Section 2(b)(1)-(2) are not Copyright and Similar + Rights. + + e. Effective Technological Measures means those measures that, in the + absence of proper authority, may not be circumvented under laws + fulfilling obligations under Article 11 of the WIPO Copyright + Treaty adopted on December 20, 1996, and/or similar international + agreements. + + f. Exceptions and Limitations means fair use, fair dealing, and/or + any other exception or limitation to Copyright and Similar Rights + that applies to Your use of the Licensed Material. + + g. License Elements means the license attributes listed in the name + of a Creative Commons Public License. The License Elements of this + Public License are Attribution and ShareAlike. + + h. Licensed Material means the artistic or literary work, database, + or other material to which the Licensor applied this Public + License. + + i. Licensed Rights means the rights granted to You subject to the + terms and conditions of this Public License, which are limited to + all Copyright and Similar Rights that apply to Your use of the + Licensed Material and that the Licensor has authority to license. + + j. Licensor means the individual(s) or entity(ies) granting rights + under this Public License. + + k. Share means to provide material to the public by any means or + process that requires permission under the Licensed Rights, such + as reproduction, public display, public performance, distribution, + dissemination, communication, or importation, and to make material + available to the public including in ways that members of the + public may access the material from a place and at a time + individually chosen by them. + + l. Sui Generis Database Rights means rights other than copyright + resulting from Directive 96/9/EC of the European Parliament and of + the Council of 11 March 1996 on the legal protection of databases, + as amended and/or succeeded, as well as other essentially + equivalent rights anywhere in the world. + + m. You means the individual or entity exercising the Licensed Rights + under this Public License. Your has a corresponding meaning. + + +Section 2 -- Scope. + + a. License grant. + + 1. Subject to the terms and conditions of this Public License, + the Licensor hereby grants You a worldwide, royalty-free, + non-sublicensable, non-exclusive, irrevocable license to + exercise the Licensed Rights in the Licensed Material to: + + a. reproduce and Share the Licensed Material, in whole or + in part; and + + b. produce, reproduce, and Share Adapted Material. + + 2. Exceptions and Limitations. For the avoidance of doubt, where + Exceptions and Limitations apply to Your use, this Public + License does not apply, and You do not need to comply with + its terms and conditions. + + 3. Term. The term of this Public License is specified in Section + 6(a). + + 4. Media and formats; technical modifications allowed. The + Licensor authorizes You to exercise the Licensed Rights in + all media and formats whether now known or hereafter created, + and to make technical modifications necessary to do so. The + Licensor waives and/or agrees not to assert any right or + authority to forbid You from making technical modifications + necessary to exercise the Licensed Rights, including + technical modifications necessary to circumvent Effective + Technological Measures. For purposes of this Public License, + simply making modifications authorized by this Section 2(a) + (4) never produces Adapted Material. + + 5. Downstream recipients. + + a. Offer from the Licensor -- Licensed Material. Every + recipient of the Licensed Material automatically + receives an offer from the Licensor to exercise the + Licensed Rights under the terms and conditions of this + Public License. + + b. Additional offer from the Licensor -- Adapted Material. + Every recipient of Adapted Material from You + automatically receives an offer from the Licensor to + exercise the Licensed Rights in the Adapted Material + under the conditions of the Adapter's License You apply. + + c. No downstream restrictions. You may not offer or impose + any additional or different terms or conditions on, or + apply any Effective Technological Measures to, the + Licensed Material if doing so restricts exercise of the + Licensed Rights by any recipient of the Licensed + Material. + + 6. No endorsement. Nothing in this Public License constitutes or + may be construed as permission to assert or imply that You + are, or that Your use of the Licensed Material is, connected + with, or sponsored, endorsed, or granted official status by, + the Licensor or others designated to receive attribution as + provided in Section 3(a)(1)(A)(i). + + b. Other rights. + + 1. Moral rights, such as the right of integrity, are not + licensed under this Public License, nor are publicity, + privacy, and/or other similar personality rights; however, to + the extent possible, the Licensor waives and/or agrees not to + assert any such rights held by the Licensor to the limited + extent necessary to allow You to exercise the Licensed + Rights, but not otherwise. + + 2. Patent and trademark rights are not licensed under this + Public License. + + 3. To the extent possible, the Licensor waives any right to + collect royalties from You for the exercise of the Licensed + Rights, whether directly or through a collecting society + under any voluntary or waivable statutory or compulsory + licensing scheme. In all other cases the Licensor expressly + reserves any right to collect such royalties. + + +Section 3 -- License Conditions. + +Your exercise of the Licensed Rights is expressly made subject to the +following conditions. + + a. Attribution. + + 1. If You Share the Licensed Material (including in modified + form), You must: + + a. retain the following if it is supplied by the Licensor + with the Licensed Material: + + i. identification of the creator(s) of the Licensed + Material and any others designated to receive + attribution, in any reasonable manner requested by + the Licensor (including by pseudonym if + designated); + + ii. a copyright notice; + + iii. a notice that refers to this Public License; + + iv. a notice that refers to the disclaimer of + warranties; + + v. a URI or hyperlink to the Licensed Material to the + extent reasonably practicable; + + b. indicate if You modified the Licensed Material and + retain an indication of any previous modifications; and + + c. indicate the Licensed Material is licensed under this + Public License, and include the text of, or the URI or + hyperlink to, this Public License. + + 2. You may satisfy the conditions in Section 3(a)(1) in any + reasonable manner based on the medium, means, and context in + which You Share the Licensed Material. For example, it may be + reasonable to satisfy the conditions by providing a URI or + hyperlink to a resource that includes the required + information. + + 3. If requested by the Licensor, You must remove any of the + information required by Section 3(a)(1)(A) to the extent + reasonably practicable. + + b. ShareAlike. + + In addition to the conditions in Section 3(a), if You Share + Adapted Material You produce, the following conditions also apply. + + 1. The Adapter's License You apply must be a Creative Commons + license with the same License Elements, this version or + later, or a BY-SA Compatible License. + + 2. You must include the text of, or the URI or hyperlink to, the + Adapter's License You apply. You may satisfy this condition + in any reasonable manner based on the medium, means, and + context in which You Share Adapted Material. + + 3. You may not offer or impose any additional or different terms + or conditions on, or apply any Effective Technological + Measures to, Adapted Material that restrict exercise of the + rights granted under the Adapter's License You apply. + + +Section 4 -- Sui Generis Database Rights. + +Where the Licensed Rights include Sui Generis Database Rights that +apply to Your use of the Licensed Material: + + a. for the avoidance of doubt, Section 2(a)(1) grants You the right + to extract, reuse, reproduce, and Share all or a substantial + portion of the contents of the database; + + b. if You include all or a substantial portion of the database + contents in a database in which You have Sui Generis Database + Rights, then the database in which You have Sui Generis Database + Rights (but not its individual contents) is Adapted Material, + including for purposes of Section 3(b); and + + c. You must comply with the conditions in Section 3(a) if You Share + all or a substantial portion of the contents of the database. + +For the avoidance of doubt, this Section 4 supplements and does not +replace Your obligations under this Public License where the Licensed +Rights include other Copyright and Similar Rights. + + +Section 5 -- Disclaimer of Warranties and Limitation of Liability. + + a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE + EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS + AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF + ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, + IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, + WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR + PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, + ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT + KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT + ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU. + + b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE + TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, + NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, + INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, + COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR + USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN + ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR + DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR + IN PART, THIS LIMITATION MAY NOT APPLY TO YOU. + + c. The disclaimer of warranties and limitation of liability provided + above shall be interpreted in a manner that, to the extent + possible, most closely approximates an absolute disclaimer and + waiver of all liability. + + +Section 6 -- Term and Termination. + + a. This Public License applies for the term of the Copyright and + Similar Rights licensed here. However, if You fail to comply with + this Public License, then Your rights under this Public License + terminate automatically. + + b. Where Your right to use the Licensed Material has terminated under + Section 6(a), it reinstates: + + 1. automatically as of the date the violation is cured, provided + it is cured within 30 days of Your discovery of the + violation; or + + 2. upon express reinstatement by the Licensor. + + For the avoidance of doubt, this Section 6(b) does not affect any + right the Licensor may have to seek remedies for Your violations + of this Public License. + + c. For the avoidance of doubt, the Licensor may also offer the + Licensed Material under separate terms or conditions or stop + distributing the Licensed Material at any time; however, doing so + will not terminate this Public License. + + d. Sections 1, 5, 6, 7, and 8 survive termination of this Public + License. + + +Section 7 -- Other Terms and Conditions. + + a. The Licensor shall not be bound by any additional or different + terms or conditions communicated by You unless expressly agreed. + + b. Any arrangements, understandings, or agreements regarding the + Licensed Material not stated herein are separate from and + independent of the terms and conditions of this Public License. + + +Section 8 -- Interpretation. + + a. For the avoidance of doubt, this Public License does not, and + shall not be interpreted to, reduce, limit, restrict, or impose + conditions on any use of the Licensed Material that could lawfully + be made without permission under this Public License. + + b. To the extent possible, if any provision of this Public License is + deemed unenforceable, it shall be automatically reformed to the + minimum extent necessary to make it enforceable. If the provision + cannot be reformed, it shall be severed from this Public License + without affecting the enforceability of the remaining terms and + conditions. + + c. No term or condition of this Public License will be waived and no + failure to comply consented to unless expressly agreed to by the + Licensor. + + d. Nothing in this Public License constitutes or may be interpreted + as a limitation upon, or waiver of, any privileges and immunities + that apply to the Licensor or You, including from the legal + processes of any jurisdiction or authority. + + +======================================================================= + +Creative Commons is not a party to its public +licenses. Notwithstanding, Creative Commons may elect to apply one of +its public licenses to material it publishes and in those instances +will be considered the “Licensor.” The text of the Creative Commons +public licenses is dedicated to the public domain under the CC0 Public +Domain Dedication. Except for the limited purpose of indicating that +material is shared under a Creative Commons public license or as +otherwise permitted by the Creative Commons policies published at +creativecommons.org/policies, Creative Commons does not authorize the +use of the trademark "Creative Commons" or any other trademark or logo +of Creative Commons without its prior written consent including, +without limitation, in connection with any unauthorized modifications +to any of its public licenses or any other arrangements, +understandings, or agreements concerning use of licensed material. For +the avoidance of doubt, this paragraph does not form part of the +public licenses. + +Creative Commons may be contacted at creativecommons.org. diff --git a/doc/api/annotated.html b/doc/api/annotated.html new file mode 100644 index 00000000..7a865ca2 --- /dev/null +++ b/doc/api/annotated.html @@ -0,0 +1,74 @@ + + + + + + + +liblzma (XZ Utils): Data Structures + + + + + + +
+
+ + + + + + + +
+
liblzma (XZ Utils) 5.6.0 +
+
+
+ + + + +
+
+
Data Structures
+
+
+
Here are the data structures with brief descriptions:
+ + + + + + + + + + + +
 Clzma_allocatorCustom functions for memory handling
 Clzma_blockOptions for the Block and Block Header encoders and decoders
 Clzma_filterFilter options
 Clzma_index_iterIterator to get information about Blocks and Streams
 Clzma_mtMultithreading options
 Clzma_options_bcjOptions for BCJ filters
 Clzma_options_deltaOptions for the Delta filter
 Clzma_options_lzmaOptions specific to the LZMA1 and LZMA2 filters
 Clzma_streamPassing data to and from liblzma
 Clzma_stream_flagsOptions for encoding/decoding Stream Header and Stream Footer
+
+
+
+

+ XZ logo © 2023 by Jia Tan is licensed under + + CC BY-SA 4.0 + +

+ + diff --git a/doc/api/base_8h.html b/doc/api/base_8h.html new file mode 100644 index 00000000..3b63ba73 --- /dev/null +++ b/doc/api/base_8h.html @@ -0,0 +1,634 @@ + + + + + + + +liblzma (XZ Utils): lzma/base.h File Reference + + + + + + +
+
+ + + + + + + +
+
liblzma (XZ Utils) 5.6.0 +
+
+
+ + + + + +
+
+
+Data Structures | +Macros | +Typedefs | +Enumerations | +Functions
+
base.h File Reference
+
+
+ +

Data types and functions used in many places in liblzma API. +More...

+ + + + + + + + +

+Data Structures

struct  lzma_allocator
 Custom functions for memory handling. More...
 
struct  lzma_stream
 Passing data to and from liblzma. More...
 
+ + + + +

+Macros

#define LZMA_STREAM_INIT
 Initialization for lzma_stream.
 
+ + + + + + + +

+Typedefs

typedef unsigned char lzma_bool
 Boolean.
 
typedef struct lzma_internal_s lzma_internal
 Internal data structure.
 
+ + + + + + + + + + +

+Enumerations

enum  lzma_reserved_enum { LZMA_RESERVED_ENUM = 0 + }
 Type of reserved enumeration variable in structures. More...
 
enum  lzma_ret {
+  LZMA_OK = 0 +, LZMA_STREAM_END = 1 +, LZMA_NO_CHECK = 2 +, LZMA_UNSUPPORTED_CHECK = 3 +,
+  LZMA_GET_CHECK = 4 +, LZMA_MEM_ERROR = 5 +, LZMA_MEMLIMIT_ERROR = 6 +, LZMA_FORMAT_ERROR = 7 +,
+  LZMA_OPTIONS_ERROR = 8 +, LZMA_DATA_ERROR = 9 +, LZMA_BUF_ERROR = 10 +, LZMA_PROG_ERROR = 11 +,
+  LZMA_SEEK_NEEDED = 12 +, LZMA_RET_INTERNAL1 = 101 +, LZMA_RET_INTERNAL2 = 102 +, LZMA_RET_INTERNAL3 = 103 +,
+  LZMA_RET_INTERNAL4 = 104 +, LZMA_RET_INTERNAL5 = 105 +, LZMA_RET_INTERNAL6 = 106 +, LZMA_RET_INTERNAL7 = 107 +,
+  LZMA_RET_INTERNAL8 = 108 +
+ }
 Return values used by several functions in liblzma. More...
 
enum  lzma_action {
+  LZMA_RUN = 0 +, LZMA_SYNC_FLUSH = 1 +, LZMA_FULL_FLUSH = 2 +, LZMA_FULL_BARRIER = 4 +,
+  LZMA_FINISH = 3 +
+ }
 The 'action' argument for lzma_code() More...
 
+ + + + + + + + + + + + + + + + + + + +

+Functions

lzma_ret lzma_code (lzma_stream *strm, lzma_action action) lzma_nothrow lzma_attr_warn_unused_result
 Encode or decode data.
 
void lzma_end (lzma_stream *strm) lzma_nothrow
 Free memory allocated for the coder data structures.
 
void lzma_get_progress (lzma_stream *strm, uint64_t *progress_in, uint64_t *progress_out) lzma_nothrow
 Get progress information.
 
uint64_t lzma_memusage (const lzma_stream *strm) lzma_nothrow lzma_attr_pure
 Get the memory usage of decoder filter chain.
 
uint64_t lzma_memlimit_get (const lzma_stream *strm) lzma_nothrow lzma_attr_pure
 Get the current memory usage limit.
 
lzma_ret lzma_memlimit_set (lzma_stream *strm, uint64_t memlimit) lzma_nothrow
 Set the memory usage limit.
 
+

Detailed Description

+

Data types and functions used in many places in liblzma API.

+
Note
Never include this file directly. Use <lzma.h> instead.
+

Macro Definition Documentation

+ +

◆ LZMA_STREAM_INIT

+ +
+
+ + + + +
#define LZMA_STREAM_INIT
+
+Value:
{ NULL, 0, 0, NULL, 0, 0, NULL, NULL, \
+
NULL, NULL, NULL, NULL, 0, 0, 0, 0, \
+
LZMA_RESERVED_ENUM, LZMA_RESERVED_ENUM }
+
+

Initialization for lzma_stream.

+

When you declare an instance of lzma_stream, you can immediately initialize it so that initialization functions know that no memory has been allocated yet:

+

lzma_stream strm = LZMA_STREAM_INIT;

+

If you need to initialize a dynamically allocated lzma_stream, you can use memset(strm_pointer, 0, sizeof(lzma_stream)). Strictly speaking, this violates the C standard since NULL may have different internal representation than zero, but it should be portable enough in practice. Anyway, for maximum portability, you can use something like this:

+

lzma_stream tmp = LZMA_STREAM_INIT; *strm = tmp;

+ +
+
+

Typedef Documentation

+ +

◆ lzma_bool

+ +
+
+ + + + +
typedef unsigned char lzma_bool
+
+ +

Boolean.

+

This is here because C89 doesn't have stdbool.h. To set a value for variables having type lzma_bool, you can use

    +
  • C99's 'true' and 'false' from stdbool.h;
    • +
  • C++'s internal 'true' and 'false'; or
    • +
  • integers one (true) and zero (false).
    • +
+ +
+
+ +

◆ lzma_internal

+ +
+
+ + + + +
typedef struct lzma_internal_s lzma_internal
+
+ +

Internal data structure.

+

The contents of this structure is not visible outside the library.

+ +
+
+

Enumeration Type Documentation

+ +

◆ lzma_reserved_enum

+ +
+
+ + + + +
enum lzma_reserved_enum
+
+ +

Type of reserved enumeration variable in structures.

+

To avoid breaking library ABI when new features are added, several structures contain extra variables that may be used in future. Since sizeof(enum) can be different than sizeof(int), and sizeof(enum) may even vary depending on the range of enumeration constants, we specify a separate type to be used for reserved enumeration variables. All enumeration constants in liblzma API will be non-negative and less than 128, which should guarantee that the ABI won't break even when new constants are added to existing enumerations.

+ +
+
+ +

◆ lzma_ret

+ +
+
+ + + + +
enum lzma_ret
+
+ +

Return values used by several functions in liblzma.

+

Check the descriptions of specific functions to find out which return values they can return. With some functions the return values may have more specific meanings than described here; those differences are described per-function basis.

+ + + + + + + + + + + + + + +
Enumerator
LZMA_OK 

Operation completed successfully.

+
LZMA_STREAM_END 

End of stream was reached.

+

In encoder, LZMA_SYNC_FLUSH, LZMA_FULL_FLUSH, or LZMA_FINISH was finished. In decoder, this indicates that all the data was successfully decoded.

+

In all cases, when LZMA_STREAM_END is returned, the last output bytes should be picked from strm->next_out.

+
LZMA_NO_CHECK 

Input stream has no integrity check.

+

This return value can be returned only if the LZMA_TELL_NO_CHECK flag was used when initializing the decoder. LZMA_NO_CHECK is just a warning, and the decoding can be continued normally.

+

It is possible to call lzma_get_check() immediately after lzma_code has returned LZMA_NO_CHECK. The result will naturally be LZMA_CHECK_NONE, but the possibility to call lzma_get_check() may be convenient in some applications.

+
LZMA_UNSUPPORTED_CHECK 

Cannot calculate the integrity check.

+

The usage of this return value is different in encoders and decoders.

+

Encoders can return this value only from the initialization function. If initialization fails with this value, the encoding cannot be done, because there's no way to produce output with the correct integrity check.

+

Decoders can return this value only from lzma_code() and only if the LZMA_TELL_UNSUPPORTED_CHECK flag was used when initializing the decoder. The decoding can still be continued normally even if the check type is unsupported, but naturally the check will not be validated, and possible errors may go undetected.

+

With decoder, it is possible to call lzma_get_check() immediately after lzma_code() has returned LZMA_UNSUPPORTED_CHECK. This way it is possible to find out what the unsupported Check ID was.

+
LZMA_GET_CHECK 

Integrity check type is now available.

+

This value can be returned only by the lzma_code() function and only if the decoder was initialized with the LZMA_TELL_ANY_CHECK flag. LZMA_GET_CHECK tells the application that it may now call lzma_get_check() to find out the Check ID. This can be used, for example, to implement a decoder that accepts only files that have strong enough integrity check.

+
LZMA_MEM_ERROR 

Cannot allocate memory.

+

Memory allocation failed, or the size of the allocation would be greater than SIZE_MAX.

+

Due to internal implementation reasons, the coding cannot be continued even if more memory were made available after LZMA_MEM_ERROR.

+
LZMA_MEMLIMIT_ERROR 

Memory usage limit was reached.

+

Decoder would need more memory than allowed by the specified memory usage limit. To continue decoding, the memory usage limit has to be increased with lzma_memlimit_set().

+

liblzma 5.2.6 and earlier had a bug in single-threaded .xz decoder (lzma_stream_decoder()) which made it impossible to continue decoding after LZMA_MEMLIMIT_ERROR even if the limit was increased using lzma_memlimit_set(). Other decoders worked correctly.

+
LZMA_FORMAT_ERROR 

File format not recognized.

+

The decoder did not recognize the input as supported file format. This error can occur, for example, when trying to decode .lzma format file with lzma_stream_decoder, because lzma_stream_decoder accepts only the .xz format.

+
LZMA_OPTIONS_ERROR 

Invalid or unsupported options.

+

Invalid or unsupported options, for example

    +
  • unsupported filter(s) or filter options; or
    • +
  • reserved bits set in headers (decoder only).
    • +
+

Rebuilding liblzma with more features enabled, or upgrading to a newer version of liblzma may help.

+
LZMA_DATA_ERROR 

Data is corrupt.

+

The usage of this return value is different in encoders and decoders. In both encoder and decoder, the coding cannot continue after this error.

+

Encoders return this if size limits of the target file format would be exceeded. These limits are huge, thus getting this error from an encoder is mostly theoretical. For example, the maximum compressed and uncompressed size of a .xz Stream is roughly 8 EiB (2^63 bytes).

+

Decoders return this error if the input data is corrupt. This can mean, for example, invalid CRC32 in headers or invalid check of uncompressed data.

+
LZMA_BUF_ERROR 

No progress is possible.

+

This error code is returned when the coder cannot consume any new input and produce any new output. The most common reason for this error is that the input stream being decoded is truncated or corrupt.

+

This error is not fatal. Coding can be continued normally by providing more input and/or more output space, if possible.

+

Typically the first call to lzma_code() that can do no progress returns LZMA_OK instead of LZMA_BUF_ERROR. Only the second consecutive call doing no progress will return LZMA_BUF_ERROR. This is intentional.

+

With zlib, Z_BUF_ERROR may be returned even if the application is doing nothing wrong, so apps will need to handle Z_BUF_ERROR specially. The above hack guarantees that liblzma never returns LZMA_BUF_ERROR to properly written applications unless the input file is truncated or corrupt. This should simplify the applications a little.

+
LZMA_PROG_ERROR 

Programming error.

+

This indicates that the arguments given to the function are invalid or the internal state of the decoder is corrupt.

    +
  • Function arguments are invalid or the structures pointed by the argument pointers are invalid e.g. if strm->next_out has been set to NULL and strm->avail_out > 0 when calling lzma_code().
    • +
  • lzma_* functions have been called in wrong order e.g. lzma_code() was called right after lzma_end().
    • +
  • If errors occur randomly, the reason might be flaky hardware.
    • +
+

If you think that your code is correct, this error code can be a sign of a bug in liblzma. See the documentation how to report bugs.

+
LZMA_SEEK_NEEDED 

Request to change the input file position.

+

Some coders can do random access in the input file. The initialization functions of these coders take the file size as an argument. No other coders can return LZMA_SEEK_NEEDED.

+

When this value is returned, the application must seek to the file position given in lzma_stream.seek_pos. This value is guaranteed to never exceed the file size that was specified at the coder initialization.

+

After seeking the application should read new input and pass it normally via lzma_stream.next_in and .avail_in.

+
+ +
+
+ +

◆ lzma_action

+ +
+
+ + + + +
enum lzma_action
+
+ +

The 'action' argument for lzma_code()

+

After the first use of LZMA_SYNC_FLUSH, LZMA_FULL_FLUSH, LZMA_FULL_BARRIER, or LZMA_FINISH, the same 'action' must be used until lzma_code() returns LZMA_STREAM_END. Also, the amount of input (that is, strm->avail_in) must not be modified by the application until lzma_code() returns LZMA_STREAM_END. Changing the 'action' or modifying the amount of input will make lzma_code() return LZMA_PROG_ERROR.

+ + + + + + +
Enumerator
LZMA_RUN 

Continue coding.

+

Encoder: Encode as much input as possible. Some internal buffering will probably be done (depends on the filter chain in use), which causes latency: the input used won't usually be decodeable from the output of the same lzma_code() call.

+

Decoder: Decode as much input as possible and produce as much output as possible.

+
LZMA_SYNC_FLUSH 

Make all the input available at output.

+

Normally the encoder introduces some latency. LZMA_SYNC_FLUSH forces all the buffered data to be available at output without resetting the internal state of the encoder. This way it is possible to use compressed stream for example for communication over network.

+

Only some filters support LZMA_SYNC_FLUSH. Trying to use LZMA_SYNC_FLUSH with filters that don't support it will make lzma_code() return LZMA_OPTIONS_ERROR. For example, LZMA1 doesn't support LZMA_SYNC_FLUSH but LZMA2 does.

+

Using LZMA_SYNC_FLUSH very often can dramatically reduce the compression ratio. With some filters (for example, LZMA2), fine-tuning the compression options may help mitigate this problem significantly (for example, match finder with LZMA2).

+

Decoders don't support LZMA_SYNC_FLUSH.

+
LZMA_FULL_FLUSH 

Finish encoding of the current Block.

+

All the input data going to the current Block must have been given to the encoder (the last bytes can still be pending in *next_in). Call lzma_code() with LZMA_FULL_FLUSH until it returns LZMA_STREAM_END. Then continue normally with LZMA_RUN or finish the Stream with LZMA_FINISH.

+

This action is currently supported only by Stream encoder and easy encoder (which uses Stream encoder). If there is no unfinished Block, no empty Block is created.

+
LZMA_FULL_BARRIER 

Finish encoding of the current Block.

+

This is like LZMA_FULL_FLUSH except that this doesn't necessarily wait until all the input has been made available via the output buffer. That is, lzma_code() might return LZMA_STREAM_END as soon as all the input has been consumed (avail_in == 0).

+

LZMA_FULL_BARRIER is useful with a threaded encoder if one wants to split the .xz Stream into Blocks at specific offsets but doesn't care if the output isn't flushed immediately. Using LZMA_FULL_BARRIER allows keeping the threads busy while LZMA_FULL_FLUSH would make lzma_code() wait until all the threads have finished until more data could be passed to the encoder.

+

With a lzma_stream initialized with the single-threaded lzma_stream_encoder() or lzma_easy_encoder(), LZMA_FULL_BARRIER is an alias for LZMA_FULL_FLUSH.

+
LZMA_FINISH 

Finish the coding operation.

+

All the input data must have been given to the encoder (the last bytes can still be pending in next_in). Call lzma_code() with LZMA_FINISH until it returns LZMA_STREAM_END. Once LZMA_FINISH has been used, the amount of input must no longer be changed by the application.

+

When decoding, using LZMA_FINISH is optional unless the LZMA_CONCATENATED flag was used when the decoder was initialized. When LZMA_CONCATENATED was not used, the only effect of LZMA_FINISH is that the amount of input must not be changed just like in the encoder.

+
+ +
+
+

Function Documentation

+ +

◆ lzma_code()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + +
lzma_ret lzma_code (lzma_stream * strm,
lzma_action action 
)
+ 		+extern
+
+ +

Encode or decode data.

+

Once the lzma_stream has been successfully initialized (e.g. with lzma_stream_encoder()), the actual encoding or decoding is done using this function. The application has to update strm->next_in, strm->avail_in, strm->next_out, and strm->avail_out to pass input to and get output from liblzma.

+

See the description of the coder-specific initialization function to find out what 'action' values are supported by the coder.

+
Parameters
+ + + +
strmPointer to lzma_stream that is at least initialized with LZMA_STREAM_INIT.
actionAction for this function to take. Must be a valid lzma_action enum value.
+
+
+
Returns
Any valid lzma_ret. See the lzma_ret enum description for more information.
+ +
+
+ +

◆ lzma_end()

+ +
+
+ + + + + +
+ + + + + + + + +
void lzma_end (lzma_stream * strm)
+ 		+extern
+
+ +

Free memory allocated for the coder data structures.

+

After lzma_end(strm), strm->internal is guaranteed to be NULL. No other members of the lzma_stream structure are touched.

+
Note
zlib indicates an error if application end()s unfinished stream structure. liblzma doesn't do this, and assumes that application knows what it is doing.
+
Parameters
+ + +
strmPointer to lzma_stream that is at least initialized with LZMA_STREAM_INIT.
+
+
+ +
+
+ +

◆ lzma_get_progress()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + +
void lzma_get_progress (lzma_stream * strm,
uint64_t * progress_in,
uint64_t * progress_out 
)
+ 		+extern
+
+ +

Get progress information.

+

In single-threaded mode, applications can get progress information from strm->total_in and strm->total_out. In multi-threaded mode this is less useful because a significant amount of both input and output data gets buffered internally by liblzma. This makes total_in and total_out give misleading information and also makes the progress indicator updates non-smooth.

+

This function gives realistic progress information also in multi-threaded mode by taking into account the progress made by each thread. In single-threaded mode *progress_in and *progress_out are set to strm->total_in and strm->total_out, respectively.

+
Parameters
+ + + + +
strmPointer to lzma_stream that is at least initialized with LZMA_STREAM_INIT.
[out]progress_inPointer to the number of input bytes processed.
[out]progress_outPointer to the number of output bytes processed.
+
+
+ +
+
+ +

◆ lzma_memusage()

+ +
+
+ + + + + +
+ + + + + + + + +
uint64_t lzma_memusage (const lzma_stream * strm)
+ 		+extern
+
+ +

Get the memory usage of decoder filter chain.

+

This function is currently supported only when *strm has been initialized with a function that takes a memlimit argument. With other functions, you should use e.g. lzma_raw_encoder_memusage() or lzma_raw_decoder_memusage() to estimate the memory requirements.

+

This function is useful e.g. after LZMA_MEMLIMIT_ERROR to find out how big the memory usage limit should have been to decode the input. Note that this may give misleading information if decoding .xz Streams that have multiple Blocks, because each Block can have different memory requirements.

+
Parameters
+ + +
strmPointer to lzma_stream that is at least initialized with LZMA_STREAM_INIT.
+
+
+
Returns
How much memory is currently allocated for the filter decoders. If no filter chain is currently allocated, some non-zero value is still returned, which is less than or equal to what any filter chain would indicate as its memory requirement.
+

If this function isn't supported by *strm or some other error occurs, zero is returned.

+ +
+
+ +

◆ lzma_memlimit_get()

+ +
+
+ + + + + +
+ + + + + + + + +
uint64_t lzma_memlimit_get (const lzma_stream * strm)
+ 		+extern
+
+ +

Get the current memory usage limit.

+

This function is supported only when *strm has been initialized with a function that takes a memlimit argument.

+
Parameters
+ + +
strmPointer to lzma_stream that is at least initialized with LZMA_STREAM_INIT.
+
+
+
Returns
On success, the current memory usage limit is returned (always non-zero). On error, zero is returned.
+ +
+
+ +

◆ lzma_memlimit_set()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + +
lzma_ret lzma_memlimit_set (lzma_stream * strm,
uint64_t memlimit 
)
+ 		+extern
+
+ +

Set the memory usage limit.

+

This function is supported only when *strm has been initialized with a function that takes a memlimit argument.

+

liblzma 5.2.3 and earlier has a bug where memlimit value of 0 causes this function to do nothing (leaving the limit unchanged) and still return LZMA_OK. Later versions treat 0 as if 1 had been specified (so lzma_memlimit_get() will return 1 even if you specify 0 here).

+

liblzma 5.2.6 and earlier had a bug in single-threaded .xz decoder (lzma_stream_decoder()) which made it impossible to continue decoding after LZMA_MEMLIMIT_ERROR even if the limit was increased using lzma_memlimit_set(). Other decoders worked correctly.

+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: New memory usage limit successfully set.
    • +
  • LZMA_MEMLIMIT_ERROR: The new limit is too small. The limit was not changed.
    • +
  • LZMA_PROG_ERROR: Invalid arguments, e.g. *strm doesn't support memory usage limit.
    • +
+
+ +
+
+
+
+

+ XZ logo © 2023 by Jia Tan is licensed under + + CC BY-SA 4.0 + +

+ + diff --git a/doc/api/bc_s.png b/doc/api/bc_s.png new file mode 100644 index 00000000..bb50b827 Binary files /dev/null and b/doc/api/bc_s.png differ diff --git a/doc/api/bc_sd.png b/doc/api/bc_sd.png new file mode 100644 index 00000000..8d8be4c2 Binary files /dev/null and b/doc/api/bc_sd.png differ diff --git a/doc/api/bcj_8h.html b/doc/api/bcj_8h.html new file mode 100644 index 00000000..3271b72a --- /dev/null +++ b/doc/api/bcj_8h.html @@ -0,0 +1,115 @@ + + + + + + + +liblzma (XZ Utils): lzma/bcj.h File Reference + + + + + + +
+
+ + + + + + + +
+
liblzma (XZ Utils) 5.6.0 +
+
+
+ + + + + +
+
+
+Data Structures | +Macros
+
bcj.h File Reference
+
+
+ +

Branch/Call/Jump conversion filters. +More...

+ + + + + +

+Data Structures

struct  lzma_options_bcj
 Options for BCJ filters. More...
 
+ + + + + + + + + + + + + + + + + + + + + + + + + +

+Macros

+#define LZMA_FILTER_X86   LZMA_VLI_C(0x04)
 Filter for x86 binaries.
 
+#define LZMA_FILTER_POWERPC   LZMA_VLI_C(0x05)
 Filter for Big endian PowerPC binaries.
 
+#define LZMA_FILTER_IA64   LZMA_VLI_C(0x06)
 Filter for IA-64 (Itanium) binaries.
 
+#define LZMA_FILTER_ARM   LZMA_VLI_C(0x07)
 Filter for ARM binaries.
 
+#define LZMA_FILTER_ARMTHUMB   LZMA_VLI_C(0x08)
 Filter for ARM-Thumb binaries.
 
+#define LZMA_FILTER_SPARC   LZMA_VLI_C(0x09)
 Filter for SPARC binaries.
 
+#define LZMA_FILTER_ARM64   LZMA_VLI_C(0x0A)
 Filter for ARM64 binaries.
 
+#define LZMA_FILTER_RISCV   LZMA_VLI_C(0x0B)
 Filter for RISC-V binaries.
 
+

Detailed Description

+

Branch/Call/Jump conversion filters.

+
Note
Never include this file directly. Use <lzma.h> instead.
+
+
+

+ XZ logo © 2023 by Jia Tan is licensed under + + CC BY-SA 4.0 + +

+ + diff --git a/doc/api/block_8h.html b/doc/api/block_8h.html new file mode 100644 index 00000000..bc0991e9 --- /dev/null +++ b/doc/api/block_8h.html @@ -0,0 +1,860 @@ + + + + + + + +liblzma (XZ Utils): lzma/block.h File Reference + + + + + + +
+
+ + + + + + + +
+
liblzma (XZ Utils) 5.6.0 +
+
+
+ + + + + +
+
+
+Data Structures | +Macros | +Functions
+
block.h File Reference
+
+
+ +

.xz Block handling +More...

+ + + + + +

+Data Structures

struct  lzma_block
 Options for the Block and Block Header encoders and decoders. More...
 
+ + + + + + + + +

+Macros

+#define LZMA_BLOCK_HEADER_SIZE_MIN   8
 
+#define LZMA_BLOCK_HEADER_SIZE_MAX   1024
 
#define lzma_block_header_size_decode(b)   (((uint32_t)(b) + 1) * 4)
 Decode the Block Header Size field.
 
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+Functions

lzma_ret lzma_block_header_size (lzma_block *block) lzma_nothrow lzma_attr_warn_unused_result
 Calculate Block Header Size.
 
lzma_ret lzma_block_header_encode (const lzma_block *block, uint8_t *out) lzma_nothrow lzma_attr_warn_unused_result
 Encode Block Header.
 
lzma_ret lzma_block_header_decode (lzma_block *block, const lzma_allocator *allocator, const uint8_t *in) lzma_nothrow lzma_attr_warn_unused_result
 Decode Block Header.
 
lzma_ret lzma_block_compressed_size (lzma_block *block, lzma_vli unpadded_size) lzma_nothrow lzma_attr_warn_unused_result
 Validate and set Compressed Size according to Unpadded Size.
 
lzma_vli lzma_block_unpadded_size (const lzma_block *block) lzma_nothrow lzma_attr_pure
 Calculate Unpadded Size.
 
lzma_vli lzma_block_total_size (const lzma_block *block) lzma_nothrow lzma_attr_pure
 Calculate the total encoded size of a Block.
 
lzma_ret lzma_block_encoder (lzma_stream *strm, lzma_block *block) lzma_nothrow lzma_attr_warn_unused_result
 Initialize .xz Block encoder.
 
lzma_ret lzma_block_decoder (lzma_stream *strm, lzma_block *block) lzma_nothrow lzma_attr_warn_unused_result
 Initialize .xz Block decoder.
 
size_t lzma_block_buffer_bound (size_t uncompressed_size) lzma_nothrow
 Calculate maximum output size for single-call Block encoding.
 
lzma_ret lzma_block_buffer_encode (lzma_block *block, const lzma_allocator *allocator, const uint8_t *in, size_t in_size, uint8_t *out, size_t *out_pos, size_t out_size) lzma_nothrow lzma_attr_warn_unused_result
 Single-call .xz Block encoder.
 
lzma_ret lzma_block_uncomp_encode (lzma_block *block, const uint8_t *in, size_t in_size, uint8_t *out, size_t *out_pos, size_t out_size) lzma_nothrow lzma_attr_warn_unused_result
 Single-call uncompressed .xz Block encoder.
 
lzma_ret lzma_block_buffer_decode (lzma_block *block, const lzma_allocator *allocator, const uint8_t *in, size_t *in_pos, size_t in_size, uint8_t *out, size_t *out_pos, size_t out_size) lzma_nothrow
 Single-call .xz Block decoder.
 
+

Detailed Description

+

.xz Block handling

+
Note
Never include this file directly. Use <lzma.h> instead.
+

Macro Definition Documentation

+ +

◆ lzma_block_header_size_decode

+ +
+
+ + + + + + + + +
#define lzma_block_header_size_decode( b)   (((uint32_t)(b) + 1) * 4)
+
+ +

Decode the Block Header Size field.

+

To decode Block Header using lzma_block_header_decode(), the size of the Block Header has to be known and stored into lzma_block.header_size. The size can be calculated from the first byte of a Block using this macro. Note that if the first byte is 0x00, it indicates beginning of Index; use this macro only when the byte is not 0x00.

+

There is no encoding macro because lzma_block_header_size() and lzma_block_header_encode() should be used.

+ +
+
+

Function Documentation

+ +

◆ lzma_block_header_size()

+ +
+
+ + + + + +
+ + + + + + + + +
lzma_ret lzma_block_header_size (lzma_block * block)
+ 		+extern
+
+ +

Calculate Block Header Size.

+

Calculate the minimum size needed for the Block Header field using the settings specified in the lzma_block structure. Note that it is OK to increase the calculated header_size value as long as it is a multiple of four and doesn't exceed LZMA_BLOCK_HEADER_SIZE_MAX. Increasing header_size just means that lzma_block_header_encode() will add Header Padding.

+
Note
This doesn't check that all the options are valid i.e. this may return LZMA_OK even if lzma_block_header_encode() or lzma_block_encoder() would fail. If you want to validate the filter chain, consider using lzma_memlimit_encoder() which as a side-effect validates the filter chain.
+
Parameters
+ + +
blockBlock options
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: Size calculated successfully and stored to block->header_size.
    • +
  • LZMA_OPTIONS_ERROR: Unsupported version, filters or filter options.
    • +
  • LZMA_PROG_ERROR: Invalid values like compressed_size == 0.
    • +
+
+ +
+
+ +

◆ lzma_block_header_encode()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + +
lzma_ret lzma_block_header_encode (const lzma_block * block,
uint8_t * out 
)
+ 		+extern
+
+ +

Encode Block Header.

+

The caller must have calculated the size of the Block Header already with lzma_block_header_size(). If a value larger than the one calculated by lzma_block_header_size() is used, the Block Header will be padded to the specified size.

+
Parameters
+ + + +
blockBlock options to be encoded.
[out]outBeginning of the output buffer. This must be at least block->header_size bytes.
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: Encoding was successful. block->header_size bytes were written to output buffer.
    • +
  • LZMA_OPTIONS_ERROR: Invalid or unsupported options.
    • +
  • LZMA_PROG_ERROR: Invalid arguments, for example block->header_size is invalid or block->filters is NULL.
    • +
+
+ +
+
+ +

◆ lzma_block_header_decode()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_block_header_decode (lzma_block * block,
const lzma_allocator * allocator,
const uint8_t * in 
)
+ 		+extern
+
+ +

Decode Block Header.

+

block->version should (usually) be set to the highest value supported by the application. If the application sets block->version to a value higher than supported by the current liblzma version, this function will downgrade block->version to the highest value supported by it. Thus one should check the value of block->version after calling this function if block->version was set to a non-zero value and the application doesn't otherwise know that the liblzma version being used is new enough to support the specified block->version.

+

The size of the Block Header must have already been decoded with lzma_block_header_size_decode() macro and stored to block->header_size.

+

The integrity check type from Stream Header must have been stored to block->check.

+

block->filters must have been allocated, but they don't need to be initialized (possible existing filter options are not freed).

+
Parameters
+ + + + +
[out]blockDestination for Block options
allocatorlzma_allocator for custom allocator functions. Set to NULL to use malloc() (and also free() if an error occurs).
inBeginning of the input buffer. This must be at least block->header_size bytes.
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: Decoding was successful. block->header_size bytes were read from the input buffer.
    • +
  • LZMA_OPTIONS_ERROR: The Block Header specifies some unsupported options such as unsupported filters. This can happen also if block->version was set to a too low value compared to what would be required to properly represent the information stored in the Block Header.
    • +
  • LZMA_DATA_ERROR: Block Header is corrupt, for example, the CRC32 doesn't match.
    • +
  • LZMA_PROG_ERROR: Invalid arguments, for example block->header_size is invalid or block->filters is NULL.
    • +
+
+ +
+
+ +

◆ lzma_block_compressed_size()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + +
lzma_ret lzma_block_compressed_size (lzma_block * block,
lzma_vli unpadded_size 
)
+ 		+extern
+
+ +

Validate and set Compressed Size according to Unpadded Size.

+

Block Header stores Compressed Size, but Index has Unpadded Size. If the application has already parsed the Index and is now decoding Blocks, it can calculate Compressed Size from Unpadded Size. This function does exactly that with error checking:

+
    +
  • Compressed Size calculated from Unpadded Size must be positive integer, that is, Unpadded Size must be big enough that after Block Header and Check fields there's still at least one byte for Compressed Size.
    • +
  • If Compressed Size was present in Block Header, the new value calculated from Unpadded Size is compared against the value from Block Header.
    • +
+
Note
This function must be called _after_ decoding the Block Header field so that it can properly validate Compressed Size if it was present in Block Header.
+
Parameters
+ + + +
blockBlock options: block->header_size must already be set with lzma_block_header_size().
unpadded_sizeUnpadded Size from the Index field in bytes
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: block->compressed_size was set successfully.
    • +
  • LZMA_DATA_ERROR: unpadded_size is too small compared to block->header_size and lzma_check_size(block->check).
    • +
  • LZMA_PROG_ERROR: Some values are invalid. For example, block->header_size must be a multiple of four and between 8 and 1024 inclusive.
    • +
+
+ +
+
+ +

◆ lzma_block_unpadded_size()

+ +
+
+ + + + + +
+ + + + + + + + +
lzma_vli lzma_block_unpadded_size (const lzma_block * block)
+ 		+extern
+
+ +

Calculate Unpadded Size.

+

The Index field stores Unpadded Size and Uncompressed Size. The latter can be taken directly from the lzma_block structure after coding a Block, but Unpadded Size needs to be calculated from Block Header Size, Compressed Size, and size of the Check field. This is where this function is needed.

+
Parameters
+ + +
blockBlock options: block->header_size must already be set with lzma_block_header_size().
+
+
+
Returns
Unpadded Size on success, or zero on error.
+ +
+
+ +

◆ lzma_block_total_size()

+ +
+
+ + + + + +
+ + + + + + + + +
lzma_vli lzma_block_total_size (const lzma_block * block)
+ 		+extern
+
+ +

Calculate the total encoded size of a Block.

+

This is equivalent to lzma_block_unpadded_size() except that the returned value includes the size of the Block Padding field.

+
Parameters
+ + +
blockBlock options: block->header_size must already be set with lzma_block_header_size().
+
+
+
Returns
On success, total encoded size of the Block. On error, zero is returned.
+ +
+
+ +

◆ lzma_block_encoder()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + +
lzma_ret lzma_block_encoder (lzma_stream * strm,
lzma_block * block 
)
+ 		+extern
+
+ +

Initialize .xz Block encoder.

+

Valid actions for lzma_code() are LZMA_RUN, LZMA_SYNC_FLUSH (only if the filter chain supports it), and LZMA_FINISH.

+

The Block encoder encodes the Block Data, Block Padding, and Check value. It does NOT encode the Block Header which can be encoded with lzma_block_header_encode().

+
Parameters
+ + + +
strmPointer to lzma_stream that is at least initialized with LZMA_STREAM_INIT.
blockBlock options: block->version, block->check, and block->filters must have been initialized.
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: All good, continue with lzma_code().
    • +
  • LZMA_MEM_ERROR
    • +
  • LZMA_OPTIONS_ERROR
    • +
  • LZMA_UNSUPPORTED_CHECK: block->check specifies a Check ID that is not supported by this build of liblzma. Initializing the encoder failed.
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+ +

◆ lzma_block_decoder()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + +
lzma_ret lzma_block_decoder (lzma_stream * strm,
lzma_block * block 
)
+ 		+extern
+
+ +

Initialize .xz Block decoder.

+

Valid actions for lzma_code() are LZMA_RUN and LZMA_FINISH. Using LZMA_FINISH is not required. It is supported only for convenience.

+

The Block decoder decodes the Block Data, Block Padding, and Check value. It does NOT decode the Block Header which can be decoded with lzma_block_header_decode().

+
Parameters
+ + + +
strmPointer to lzma_stream that is at least initialized with LZMA_STREAM_INIT.
blockBlock options
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: All good, continue with lzma_code().
    • +
  • LZMA_PROG_ERROR
    • +
  • LZMA_MEM_ERROR
    • +
+
+ +
+
+ +

◆ lzma_block_buffer_bound()

+ +
+
+ + + + + +
+ + + + + + + + +
size_t lzma_block_buffer_bound (size_t uncompressed_size)
+ 		+extern
+
+ +

Calculate maximum output size for single-call Block encoding.

+

This is equivalent to lzma_stream_buffer_bound() but for .xz Blocks. See the documentation of lzma_stream_buffer_bound().

+
Parameters
+ + +
uncompressed_sizeSize of the data to be encoded with the single-call Block encoder.
+
+
+
Returns
Maximum output size in bytes for single-call Block encoding.
+ +
+
+ +

◆ lzma_block_buffer_encode()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_block_buffer_encode (lzma_block * block,
const lzma_allocator * allocator,
const uint8_t * in,
size_t in_size,
uint8_t * out,
size_t * out_pos,
size_t out_size 
)
+ 		+extern
+
+ +

Single-call .xz Block encoder.

+

In contrast to the multi-call encoder initialized with lzma_block_encoder(), this function encodes also the Block Header. This is required to make it possible to write appropriate Block Header also in case the data isn't compressible, and different filter chain has to be used to encode the data in uncompressed form using uncompressed chunks of the LZMA2 filter.

+

When the data isn't compressible, header_size, compressed_size, and uncompressed_size are set just like when the data was compressible, but it is possible that header_size is too small to hold the filter chain specified in block->filters, because that isn't necessarily the filter chain that was actually used to encode the data. lzma_block_unpadded_size() still works normally, because it doesn't read the filters array.

+
Parameters
+ + + + + + + + +
blockBlock options: block->version, block->check, and block->filters must have been initialized.
allocatorlzma_allocator for custom allocator functions. Set to NULL to use malloc() and free().
inBeginning of the input buffer
in_sizeSize of the input buffer
[out]outBeginning of the output buffer
[out]out_posThe next byte will be written to out[*out_pos]. *out_pos is updated only if encoding succeeds.
out_sizeSize of the out buffer; the first byte into which no data is written to is out[out_size].
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: Encoding was successful.
    • +
  • LZMA_BUF_ERROR: Not enough output buffer space.
    • +
  • LZMA_UNSUPPORTED_CHECK
    • +
  • LZMA_OPTIONS_ERROR
    • +
  • LZMA_MEM_ERROR
    • +
  • LZMA_DATA_ERROR
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+ +

◆ lzma_block_uncomp_encode()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_block_uncomp_encode (lzma_block * block,
const uint8_t * in,
size_t in_size,
uint8_t * out,
size_t * out_pos,
size_t out_size 
)
+ 		+extern
+
+ +

Single-call uncompressed .xz Block encoder.

+

This is like lzma_block_buffer_encode() except this doesn't try to compress the data and instead encodes the data using LZMA2 uncompressed chunks. The required output buffer size can be determined with lzma_block_buffer_bound().

+

Since the data won't be compressed, this function ignores block->filters. This function doesn't take lzma_allocator because this function doesn't allocate any memory from the heap.

+
Parameters
+ + + + + + + +
blockBlock options: block->version, block->check, and block->filters must have been initialized.
inBeginning of the input buffer
in_sizeSize of the input buffer
[out]outBeginning of the output buffer
[out]out_posThe next byte will be written to out[*out_pos]. *out_pos is updated only if encoding succeeds.
out_sizeSize of the out buffer; the first byte into which no data is written to is out[out_size].
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: Encoding was successful.
    • +
  • LZMA_BUF_ERROR: Not enough output buffer space.
    • +
  • LZMA_UNSUPPORTED_CHECK
    • +
  • LZMA_OPTIONS_ERROR
    • +
  • LZMA_MEM_ERROR
    • +
  • LZMA_DATA_ERROR
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+ +

◆ lzma_block_buffer_decode()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_block_buffer_decode (lzma_block * block,
const lzma_allocator * allocator,
const uint8_t * in,
size_t * in_pos,
size_t in_size,
uint8_t * out,
size_t * out_pos,
size_t out_size 
)
+ 		+extern
+
+ +

Single-call .xz Block decoder.

+

This is single-call equivalent of lzma_block_decoder(), and requires that the caller has already decoded Block Header and checked its memory usage.

+
Parameters
+ + + + + + + + + +
blockBlock options
allocatorlzma_allocator for custom allocator functions. Set to NULL to use malloc() and free().
inBeginning of the input buffer
in_posThe next byte will be read from in[*in_pos]. *in_pos is updated only if decoding succeeds.
in_sizeSize of the input buffer; the first byte that won't be read is in[in_size].
[out]outBeginning of the output buffer
[out]out_posThe next byte will be written to out[*out_pos]. *out_pos is updated only if encoding succeeds.
out_sizeSize of the out buffer; the first byte into which no data is written to is out[out_size].
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: Decoding was successful.
    • +
  • LZMA_OPTIONS_ERROR
    • +
  • LZMA_DATA_ERROR
    • +
  • LZMA_MEM_ERROR
    • +
  • LZMA_BUF_ERROR: Output buffer was too small.
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+
+
+

+ XZ logo © 2023 by Jia Tan is licensed under + + CC BY-SA 4.0 + +

+ + diff --git a/doc/api/check_8h.html b/doc/api/check_8h.html new file mode 100644 index 00000000..2204e996 --- /dev/null +++ b/doc/api/check_8h.html @@ -0,0 +1,386 @@ + + + + + + + +liblzma (XZ Utils): lzma/check.h File Reference + + + + + + +
+
+ + + + + + + +
+
liblzma (XZ Utils) 5.6.0 +
+
+
+ + + + + +
+
+
+Macros | +Enumerations | +Functions
+
check.h File Reference
+
+
+ +

Integrity checks. +More...

+ + + + + + + + +

+Macros

#define LZMA_CHECK_ID_MAX   15
 Maximum valid Check ID.
 
+#define LZMA_CHECK_SIZE_MAX   64
 Maximum size of a Check field.
 
+ + + + +

+Enumerations

enum  lzma_check { LZMA_CHECK_NONE = 0 +, LZMA_CHECK_CRC32 = 1 +, LZMA_CHECK_CRC64 = 4 +, LZMA_CHECK_SHA256 = 10 + }
 Type of the integrity check (Check ID) More...
 
+ + + + + + + + + + + + + + + + +

+Functions

lzma_bool lzma_check_is_supported (lzma_check check) lzma_nothrow lzma_attr_const
 Test if the given Check ID is supported.
 
uint32_t lzma_check_size (lzma_check check) lzma_nothrow lzma_attr_const
 Get the size of the Check field with the given Check ID.
 
uint32_t lzma_crc32 (const uint8_t *buf, size_t size, uint32_t crc) lzma_nothrow lzma_attr_pure
 Calculate CRC32.
 
uint64_t lzma_crc64 (const uint8_t *buf, size_t size, uint64_t crc) lzma_nothrow lzma_attr_pure
 Calculate CRC64.
 
lzma_check lzma_get_check (const lzma_stream *strm) lzma_nothrow
 Get the type of the integrity check.
 
+

Detailed Description

+

Integrity checks.

+
Note
Never include this file directly. Use <lzma.h> instead.
+

Macro Definition Documentation

+ +

◆ LZMA_CHECK_ID_MAX

+ +
+
+ + + + +
#define LZMA_CHECK_ID_MAX   15
+
+ +

Maximum valid Check ID.

+

The .xz file format specification specifies 16 Check IDs (0-15). Some of them are only reserved, that is, no actual Check algorithm has been assigned. When decoding, liblzma still accepts unknown Check IDs for future compatibility. If a valid but unsupported Check ID is detected, liblzma can indicate a warning; see the flags LZMA_TELL_NO_CHECK, LZMA_TELL_UNSUPPORTED_CHECK, and LZMA_TELL_ANY_CHECK in container.h.

+ +
+
+

Enumeration Type Documentation

+ +

◆ lzma_check

+ +
+
+ + + + +
enum lzma_check
+
+ +

Type of the integrity check (Check ID)

+

The .xz format supports multiple types of checks that are calculated from the uncompressed data. They vary in both speed and ability to detect errors.

+ + + + + +
Enumerator
LZMA_CHECK_NONE 

No Check is calculated.

+

Size of the Check field: 0 bytes

+
LZMA_CHECK_CRC32 

CRC32 using the polynomial from the IEEE 802.3 standard

+

Size of the Check field: 4 bytes

+
LZMA_CHECK_CRC64 

CRC64 using the polynomial from the ECMA-182 standard

+

Size of the Check field: 8 bytes

+
LZMA_CHECK_SHA256 

SHA-256

+

Size of the Check field: 32 bytes

+
+ +
+
+

Function Documentation

+ +

◆ lzma_check_is_supported()

+ +
+
+ + + + + +
+ + + + + + + + +
lzma_bool lzma_check_is_supported (lzma_check check) const
+ 		+extern
+
+ +

Test if the given Check ID is supported.

+

LZMA_CHECK_NONE and LZMA_CHECK_CRC32 are always supported (even if liblzma is built with limited features).

+
Note
It is safe to call this with a value that is not in the range [0, 15]; in that case the return value is always false.
+
Parameters
+ + +
checkCheck ID
+
+
+
Returns
lzma_bool:
    +
  • true if Check ID is supported by this liblzma build.
    • +
  • false otherwise.
    • +
+
+ +
+
+ +

◆ lzma_check_size()

+ +
+
+ + + + + +
+ + + + + + + + +
uint32_t lzma_check_size (lzma_check check) const
+ 		+extern
+
+ +

Get the size of the Check field with the given Check ID.

+

Although not all Check IDs have a check algorithm associated, the size of every Check is already frozen. This function returns the size (in bytes) of the Check field with the specified Check ID. The values are: { 0, 4, 4, 4, 8, 8, 8, 16, 16, 16, 32, 32, 32, 64, 64, 64 }

+
Parameters
+ + +
checkCheck ID
+
+
+
Returns
Size of the Check field in bytes. If the argument is not in the range [0, 15], UINT32_MAX is returned.
+ +
+
+ +

◆ lzma_crc32()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + +
uint32_t lzma_crc32 (const uint8_t * buf,
size_t size,
uint32_t crc 
)
+ 		+extern
+
+ +

Calculate CRC32.

+

Calculate CRC32 using the polynomial from the IEEE 802.3 standard.

+
Parameters
+ + + + +
bufPointer to the input buffer
sizeSize of the input buffer
crcPreviously returned CRC value. This is used to calculate the CRC of a big buffer in smaller chunks. Set to zero when starting a new calculation.
+
+
+
Returns
Updated CRC value, which can be passed to this function again to continue CRC calculation.
+ +
+
+ +

◆ lzma_crc64()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + +
uint64_t lzma_crc64 (const uint8_t * buf,
size_t size,
uint64_t crc 
)
+ 		+extern
+
+ +

Calculate CRC64.

+

Calculate CRC64 using the polynomial from the ECMA-182 standard.

+

This function is used similarly to lzma_crc32().

+
Parameters
+ + + + +
bufPointer to the input buffer
sizeSize of the input buffer
crcPreviously returned CRC value. This is used to calculate the CRC of a big buffer in smaller chunks. Set to zero when starting a new calculation.
+
+
+
Returns
Updated CRC value, which can be passed to this function again to continue CRC calculation.
+ +
+
+ +

◆ lzma_get_check()

+ +
+
+ + + + + +
+ + + + + + + + +
lzma_check lzma_get_check (const lzma_stream * strm)
+ 		+extern
+
+ +

Get the type of the integrity check.

+

This function can be called only immediately after lzma_code() has returned LZMA_NO_CHECK, LZMA_UNSUPPORTED_CHECK, or LZMA_GET_CHECK. Calling this function in any other situation has undefined behavior.

+
Parameters
+ + +
strmPointer to lzma_stream meeting the above conditions.
+
+
+
Returns
Check ID in the lzma_stream, or undefined if called improperly.
+ +
+
+
+
+

+ XZ logo © 2023 by Jia Tan is licensed under + + CC BY-SA 4.0 + +

+ + diff --git a/doc/api/classes.html b/doc/api/classes.html new file mode 100644 index 00000000..003589c6 --- /dev/null +++ b/doc/api/classes.html @@ -0,0 +1,66 @@ + + + + + + + +liblzma (XZ Utils): Data Structure Index + + + + + + +
+
+ + + + + + + +
+
liblzma (XZ Utils) 5.6.0 +
+
+
+ + + + +
+
+
Data Structure Index
+
+
+
L
+
+
+
L
+
lzma_allocator
lzma_block
lzma_filter
lzma_index_iter
lzma_mt
lzma_options_bcj
lzma_options_delta
lzma_options_lzma
lzma_stream
lzma_stream_flags
+
+
+
+

+ XZ logo © 2023 by Jia Tan is licensed under + + CC BY-SA 4.0 + +

+ + diff --git a/doc/api/closed.png b/doc/api/closed.png new file mode 100644 index 00000000..91f4888e Binary files /dev/null and b/doc/api/closed.png differ diff --git a/doc/api/container_8h.html b/doc/api/container_8h.html new file mode 100644 index 00000000..583ed64d --- /dev/null +++ b/doc/api/container_8h.html @@ -0,0 +1,1469 @@ + + + + + + + +liblzma (XZ Utils): lzma/container.h File Reference + + + + + + +
+
+ + + + + + + +
+
liblzma (XZ Utils) 5.6.0 +
+
+
+ + + + + +
+
+
+Data Structures | +Macros | +Functions
+
container.h File Reference
+
+
+ +

File formats. +More...

+ + + + + +

+Data Structures

struct  lzma_mt
 Multithreading options. More...
 
+ + + + + + + + + + + + + + + + + + + + + + +

+Macros

#define LZMA_PRESET_DEFAULT   UINT32_C(6)
 Default compression preset.
 
#define LZMA_PRESET_LEVEL_MASK   UINT32_C(0x1F)
 Mask for preset level.
 
#define LZMA_PRESET_EXTREME   (UINT32_C(1) << 31)
 Extreme compression preset.
 
#define LZMA_TELL_NO_CHECK   UINT32_C(0x01)
 
#define LZMA_TELL_UNSUPPORTED_CHECK   UINT32_C(0x02)
 
#define LZMA_TELL_ANY_CHECK   UINT32_C(0x04)
 
#define LZMA_IGNORE_CHECK   UINT32_C(0x10)
 
#define LZMA_CONCATENATED   UINT32_C(0x08)
 
#define LZMA_FAIL_FAST   UINT32_C(0x20)
 
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+Functions

uint64_t lzma_easy_encoder_memusage (uint32_t preset) lzma_nothrow lzma_attr_pure
 Calculate approximate memory usage of easy encoder.
 
uint64_t lzma_easy_decoder_memusage (uint32_t preset) lzma_nothrow lzma_attr_pure
 Calculate approximate decoder memory usage of a preset.
 
lzma_ret lzma_easy_encoder (lzma_stream *strm, uint32_t preset, lzma_check check) lzma_nothrow lzma_attr_warn_unused_result
 Initialize .xz Stream encoder using a preset number.
 
lzma_ret lzma_easy_buffer_encode (uint32_t preset, lzma_check check, const lzma_allocator *allocator, const uint8_t *in, size_t in_size, uint8_t *out, size_t *out_pos, size_t out_size) lzma_nothrow
 Single-call .xz Stream encoding using a preset number.
 
lzma_ret lzma_stream_encoder (lzma_stream *strm, const lzma_filter *filters, lzma_check check) lzma_nothrow lzma_attr_warn_unused_result
 Initialize .xz Stream encoder using a custom filter chain.
 
uint64_t lzma_stream_encoder_mt_memusage (const lzma_mt *options) lzma_nothrow lzma_attr_pure
 Calculate approximate memory usage of multithreaded .xz encoder.
 
lzma_ret lzma_stream_encoder_mt (lzma_stream *strm, const lzma_mt *options) lzma_nothrow lzma_attr_warn_unused_result
 Initialize multithreaded .xz Stream encoder.
 
uint64_t lzma_mt_block_size (const lzma_filter *filters) lzma_nothrow
 Calculate recommended Block size for multithreaded .xz encoder.
 
lzma_ret lzma_alone_encoder (lzma_stream *strm, const lzma_options_lzma *options) lzma_nothrow lzma_attr_warn_unused_result
 Initialize .lzma encoder (legacy file format)
 
size_t lzma_stream_buffer_bound (size_t uncompressed_size) lzma_nothrow
 Calculate output buffer size for single-call Stream encoder.
 
lzma_ret lzma_stream_buffer_encode (lzma_filter *filters, lzma_check check, const lzma_allocator *allocator, const uint8_t *in, size_t in_size, uint8_t *out, size_t *out_pos, size_t out_size) lzma_nothrow lzma_attr_warn_unused_result
 Single-call .xz Stream encoder.
 
lzma_ret lzma_microlzma_encoder (lzma_stream *strm, const lzma_options_lzma *options) lzma_nothrow
 MicroLZMA encoder.
 
lzma_ret lzma_stream_decoder (lzma_stream *strm, uint64_t memlimit, uint32_t flags) lzma_nothrow lzma_attr_warn_unused_result
 Initialize .xz Stream decoder.
 
lzma_ret lzma_stream_decoder_mt (lzma_stream *strm, const lzma_mt *options) lzma_nothrow lzma_attr_warn_unused_result
 Initialize multithreaded .xz Stream decoder.
 
lzma_ret lzma_auto_decoder (lzma_stream *strm, uint64_t memlimit, uint32_t flags) lzma_nothrow lzma_attr_warn_unused_result
 Decode .xz, .lzma, and .lz (lzip) files with autodetection.
 
lzma_ret lzma_alone_decoder (lzma_stream *strm, uint64_t memlimit) lzma_nothrow lzma_attr_warn_unused_result
 Initialize .lzma decoder (legacy file format)
 
lzma_ret lzma_lzip_decoder (lzma_stream *strm, uint64_t memlimit, uint32_t flags) lzma_nothrow lzma_attr_warn_unused_result
 Initialize .lz (lzip) decoder (a foreign file format)
 
lzma_ret lzma_stream_buffer_decode (uint64_t *memlimit, uint32_t flags, const lzma_allocator *allocator, const uint8_t *in, size_t *in_pos, size_t in_size, uint8_t *out, size_t *out_pos, size_t out_size) lzma_nothrow lzma_attr_warn_unused_result
 Single-call .xz Stream decoder.
 
lzma_ret lzma_microlzma_decoder (lzma_stream *strm, uint64_t comp_size, uint64_t uncomp_size, lzma_bool uncomp_size_is_exact, uint32_t dict_size) lzma_nothrow
 MicroLZMA decoder.
 
+

Detailed Description

+

File formats.

+
Note
Never include this file directly. Use <lzma.h> instead.
+

Macro Definition Documentation

+ +

◆ LZMA_PRESET_DEFAULT

+ +
+
+ + + + +
#define LZMA_PRESET_DEFAULT   UINT32_C(6)
+
+ +

Default compression preset.

+

It's not straightforward to recommend a default preset, because in some cases keeping the resource usage relatively low is more important that getting the maximum compression ratio.

+ +
+
+ +

◆ LZMA_PRESET_LEVEL_MASK

+ +
+
+ + + + +
#define LZMA_PRESET_LEVEL_MASK   UINT32_C(0x1F)
+
+ +

Mask for preset level.

+

This is useful only if you need to extract the level from the preset variable. That should be rare.

+ +
+
+ +

◆ LZMA_PRESET_EXTREME

+ +
+
+ + + + +
#define LZMA_PRESET_EXTREME   (UINT32_C(1) << 31)
+
+ +

Extreme compression preset.

+

This flag modifies the preset to make the encoding significantly slower while improving the compression ratio only marginally. This is useful when you don't mind spending time to get as small result as possible.

+

This flag doesn't affect the memory usage requirements of the decoder (at least not significantly). The memory usage of the encoder may be increased a little but only at the lowest preset levels (0-3).

+ +
+
+ +

◆ LZMA_TELL_NO_CHECK

+ +
+
+ + + + +
#define LZMA_TELL_NO_CHECK   UINT32_C(0x01)
+
+

This flag makes lzma_code() return LZMA_NO_CHECK if the input stream being decoded has no integrity check. Note that when used with lzma_auto_decoder(), all .lzma files will trigger LZMA_NO_CHECK if LZMA_TELL_NO_CHECK is used.

+ +
+
+ +

◆ LZMA_TELL_UNSUPPORTED_CHECK

+ +
+
+ + + + +
#define LZMA_TELL_UNSUPPORTED_CHECK   UINT32_C(0x02)
+
+

This flag makes lzma_code() return LZMA_UNSUPPORTED_CHECK if the input stream has an integrity check, but the type of the integrity check is not supported by this liblzma version or build. Such files can still be decoded, but the integrity check cannot be verified.

+ +
+
+ +

◆ LZMA_TELL_ANY_CHECK

+ +
+
+ + + + +
#define LZMA_TELL_ANY_CHECK   UINT32_C(0x04)
+
+

This flag makes lzma_code() return LZMA_GET_CHECK as soon as the type of the integrity check is known. The type can then be got with lzma_get_check().

+ +
+
+ +

◆ LZMA_IGNORE_CHECK

+ +
+
+ + + + +
#define LZMA_IGNORE_CHECK   UINT32_C(0x10)
+
+

This flag makes lzma_code() not calculate and verify the integrity check of the compressed data in .xz files. This means that invalid integrity check values won't be detected and LZMA_DATA_ERROR won't be returned in such cases.

+

This flag only affects the checks of the compressed data itself; the CRC32 values in the .xz headers will still be verified normally.

+

Don't use this flag unless you know what you are doing. Possible reasons to use this flag:

+
    +
  • Trying to recover data from a corrupt .xz file.
    • +
  • Speeding up decompression, which matters mostly with SHA-256 or with files that have compressed extremely well. It's recommended to not use this flag for this purpose unless the file integrity is verified externally in some other way.
    • +
+

Support for this flag was added in liblzma 5.1.4beta.

+ +
+
+ +

◆ LZMA_CONCATENATED

+ +
+
+ + + + +
#define LZMA_CONCATENATED   UINT32_C(0x08)
+
+

This flag enables decoding of concatenated files with file formats that allow concatenating compressed files as is. From the formats currently supported by liblzma, only the .xz and .lz formats allow concatenated files. Concatenated files are not allowed with the legacy .lzma format.

+

This flag also affects the usage of the 'action' argument for lzma_code(). When LZMA_CONCATENATED is used, lzma_code() won't return LZMA_STREAM_END unless LZMA_FINISH is used as 'action'. Thus, the application has to set LZMA_FINISH in the same way as it does when encoding.

+

If LZMA_CONCATENATED is not used, the decoders still accept LZMA_FINISH as 'action' for lzma_code(), but the usage of LZMA_FINISH isn't required.

+ +
+
+ +

◆ LZMA_FAIL_FAST

+ +
+
+ + + + +
#define LZMA_FAIL_FAST   UINT32_C(0x20)
+
+

This flag makes the threaded decoder report errors (like LZMA_DATA_ERROR) as soon as they are detected. This saves time when the application has no interest in a partially decompressed truncated or corrupt file. Note that due to timing randomness, if the same truncated or corrupt input is decompressed multiple times with this flag, a different amount of output may be produced by different runs, and even the error code might vary.

+

When using LZMA_FAIL_FAST, it is recommended to use LZMA_FINISH to tell the decoder when no more input will be coming because it can help fast detection and reporting of truncated files. Note that in this situation truncated files might be diagnosed with LZMA_DATA_ERROR instead of LZMA_OK or LZMA_BUF_ERROR!

+

Without this flag the threaded decoder will provide as much output as possible at first and then report the pending error. This default behavior matches the single-threaded decoder and provides repeatable behavior with truncated or corrupt input. There are a few special cases where the behavior can still differ like memory allocation failures (LZMA_MEM_ERROR).

+

Single-threaded decoders currently ignore this flag.

+

Support for this flag was added in liblzma 5.3.3alpha. Note that in older versions this flag isn't supported (LZMA_OPTIONS_ERROR) even by functions that ignore this flag in newer liblzma versions.

+ +
+
+

Function Documentation

+ +

◆ lzma_easy_encoder_memusage()

+ +
+
+ + + + + +
+ + + + + + + + +
uint64_t lzma_easy_encoder_memusage (uint32_t preset)
+ 		+extern
+
+ +

Calculate approximate memory usage of easy encoder.

+

This function is a wrapper for lzma_raw_encoder_memusage().

+
Parameters
+ + +
presetCompression preset (level and possible flags)
+
+
+
Returns
Number of bytes of memory required for the given preset when encoding or UINT64_MAX on error.
+ +
+
+ +

◆ lzma_easy_decoder_memusage()

+ +
+
+ + + + + +
+ + + + + + + + +
uint64_t lzma_easy_decoder_memusage (uint32_t preset)
+ 		+extern
+
+ +

Calculate approximate decoder memory usage of a preset.

+

This function is a wrapper for lzma_raw_decoder_memusage().

+
Parameters
+ + +
presetCompression preset (level and possible flags)
+
+
+
Returns
Number of bytes of memory required to decompress a file that was compressed using the given preset or UINT64_MAX on error.
+ +
+
+ +

◆ lzma_easy_encoder()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_easy_encoder (lzma_stream * strm,
uint32_t preset,
lzma_check check 
)
+ 		+extern
+
+ +

Initialize .xz Stream encoder using a preset number.

+

This function is intended for those who just want to use the basic features of liblzma (that is, most developers out there).

+

If initialization fails (return value is not LZMA_OK), all the memory allocated for *strm by liblzma is always freed. Thus, there is no need to call lzma_end() after failed initialization.

+

If initialization succeeds, use lzma_code() to do the actual encoding. Valid values for 'action' (the second argument of lzma_code()) are LZMA_RUN, LZMA_SYNC_FLUSH, LZMA_FULL_FLUSH, and LZMA_FINISH. In future, there may be compression levels or flags that don't support LZMA_SYNC_FLUSH.

+
Parameters
+ + + + +
strmPointer to lzma_stream that is at least initialized with LZMA_STREAM_INIT.
presetCompression preset to use. A preset consist of level number and zero or more flags. Usually flags aren't used, so preset is simply a number [0, 9] which match the options -0 ... -9 of the xz command line tool. Additional flags can be be set using bitwise-or with the preset level number, e.g. 6 | LZMA_PRESET_EXTREME.
checkIntegrity check type to use. See check.h for available checks. The xz command line tool defaults to LZMA_CHECK_CRC64, which is a good choice if you are unsure. LZMA_CHECK_CRC32 is good too as long as the uncompressed file is not many gigabytes.
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: Initialization succeeded. Use lzma_code() to encode your data.
    • +
  • LZMA_MEM_ERROR: Memory allocation failed.
    • +
  • LZMA_OPTIONS_ERROR: The given compression preset is not supported by this build of liblzma.
    • +
  • LZMA_UNSUPPORTED_CHECK: The given check type is not supported by this liblzma build.
    • +
  • LZMA_PROG_ERROR: One or more of the parameters have values that will never be valid. For example, strm == NULL.
    • +
+
+ +
+
+ +

◆ lzma_easy_buffer_encode()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_easy_buffer_encode (uint32_t preset,
lzma_check check,
const lzma_allocator * allocator,
const uint8_t * in,
size_t in_size,
uint8_t * out,
size_t * out_pos,
size_t out_size 
)
+ 		+extern
+
+ +

Single-call .xz Stream encoding using a preset number.

+

The maximum required output buffer size can be calculated with lzma_stream_buffer_bound().

+
Parameters
+ + + + + + + + + +
presetCompression preset to use. See the description in lzma_easy_encoder().
checkType of the integrity check to calculate from uncompressed data.
allocatorlzma_allocator for custom allocator functions. Set to NULL to use malloc() and free().
inBeginning of the input buffer
in_sizeSize of the input buffer
[out]outBeginning of the output buffer
[out]out_posThe next byte will be written to out[*out_pos]. *out_pos is updated only if encoding succeeds.
out_sizeSize of the out buffer; the first byte into which no data is written to is out[out_size].
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: Encoding was successful.
    • +
  • LZMA_BUF_ERROR: Not enough output buffer space.
    • +
  • LZMA_UNSUPPORTED_CHECK
    • +
  • LZMA_OPTIONS_ERROR
    • +
  • LZMA_MEM_ERROR
    • +
  • LZMA_DATA_ERROR
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+ +

◆ lzma_stream_encoder()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_stream_encoder (lzma_stream * strm,
const lzma_filter * filters,
lzma_check check 
)
+ 		+extern
+
+ +

Initialize .xz Stream encoder using a custom filter chain.

+
Parameters
+ + + + +
strmPointer to lzma_stream that is at least initialized with LZMA_STREAM_INIT.
filtersArray of filters terminated with .id == LZMA_VLI_UNKNOWN. See filters.h for more information.
checkType of the integrity check to calculate from uncompressed data.
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: Initialization was successful.
    • +
  • LZMA_MEM_ERROR
    • +
  • LZMA_UNSUPPORTED_CHECK
    • +
  • LZMA_OPTIONS_ERROR
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+ +

◆ lzma_stream_encoder_mt_memusage()

+ +
+
+ + + + + +
+ + + + + + + + +
uint64_t lzma_stream_encoder_mt_memusage (const lzma_mt * options)
+ 		+extern
+
+ +

Calculate approximate memory usage of multithreaded .xz encoder.

+

Since doing the encoding in threaded mode doesn't affect the memory requirements of single-threaded decompressor, you can use lzma_easy_decoder_memusage(options->preset) or lzma_raw_decoder_memusage(options->filters) to calculate the decompressor memory requirements.

+
Parameters
+ + +
optionsCompression options
+
+
+
Returns
Number of bytes of memory required for encoding with the given options. If an error occurs, for example due to unsupported preset or filter chain, UINT64_MAX is returned.
+ +
+
+ +

◆ lzma_stream_encoder_mt()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + +
lzma_ret lzma_stream_encoder_mt (lzma_stream * strm,
const lzma_mt * options 
)
+ 		+extern
+
+ +

Initialize multithreaded .xz Stream encoder.

+

This provides the functionality of lzma_easy_encoder() and lzma_stream_encoder() as a single function for multithreaded use.

+

The supported actions for lzma_code() are LZMA_RUN, LZMA_FULL_FLUSH, LZMA_FULL_BARRIER, and LZMA_FINISH. Support for LZMA_SYNC_FLUSH might be added in the future.

+
Parameters
+ + + +
strmPointer to lzma_stream that is at least initialized with LZMA_STREAM_INIT.
optionsPointer to multithreaded compression options
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK
    • +
  • LZMA_MEM_ERROR
    • +
  • LZMA_UNSUPPORTED_CHECK
    • +
  • LZMA_OPTIONS_ERROR
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+ +

◆ lzma_mt_block_size()

+ +
+
+ + + + + +
+ + + + + + + + +
uint64_t lzma_mt_block_size (const lzma_filter * filters)
+ 		+extern
+
+ +

Calculate recommended Block size for multithreaded .xz encoder.

+

This calculates a recommended Block size for multithreaded encoding given a filter chain. This is used internally by lzma_stream_encoder_mt() to determine the Block size if the block_size member is not set to the special value of 0 in the lzma_mt options struct.

+

If one wishes to change the filters between Blocks, this function is helpful to set the block_size member of the lzma_mt struct before calling lzma_stream_encoder_mt(). Since the block_size member represents the maximum possible Block size for the multithreaded .xz encoder, one can use this function to find the maximum recommended Block size based on all planned filter chains. Otherwise, the multithreaded encoder will base its maximum Block size on the first filter chain used (if the block_size member is not set), which may unnecessarily limit the Block size for a later filter chain.

+
Parameters
+ + +
filtersArray of filters terminated with .id == LZMA_VLI_UNKNOWN.
+
+
+
Returns
Recommended Block size in bytes, or UINT64_MAX if an error occurred.
+ +
+
+ +

◆ lzma_alone_encoder()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + +
lzma_ret lzma_alone_encoder (lzma_stream * strm,
const lzma_options_lzma * options 
)
+ 		+extern
+
+ +

Initialize .lzma encoder (legacy file format)

+

The .lzma format is sometimes called the LZMA_Alone format, which is the reason for the name of this function. The .lzma format supports only the LZMA1 filter. There is no support for integrity checks like CRC32.

+

Use this function if and only if you need to create files readable by legacy LZMA tools such as LZMA Utils 4.32.x. Moving to the .xz format is strongly recommended.

+

The valid action values for lzma_code() are LZMA_RUN and LZMA_FINISH. No kind of flushing is supported, because the file format doesn't make it possible.

+
Parameters
+ + + +
strmPointer to lzma_stream that is at least initialized with LZMA_STREAM_INIT.
optionsPointer to encoder options
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK
    • +
  • LZMA_MEM_ERROR
    • +
  • LZMA_OPTIONS_ERROR
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+ +

◆ lzma_stream_buffer_bound()

+ +
+
+ + + + + +
+ + + + + + + + +
size_t lzma_stream_buffer_bound (size_t uncompressed_size)
+ 		+extern
+
+ +

Calculate output buffer size for single-call Stream encoder.

+

When trying to compress incompressible data, the encoded size will be slightly bigger than the input data. This function calculates how much output buffer space is required to be sure that lzma_stream_buffer_encode() doesn't return LZMA_BUF_ERROR.

+

The calculated value is not exact, but it is guaranteed to be big enough. The actual maximum output space required may be slightly smaller (up to about 100 bytes). This should not be a problem in practice.

+

If the calculated maximum size doesn't fit into size_t or would make the Stream grow past LZMA_VLI_MAX (which should never happen in practice), zero is returned to indicate the error.

+
Note
The limit calculated by this function applies only to single-call encoding. Multi-call encoding may (and probably will) have larger maximum expansion when encoding incompressible data. Currently there is no function to calculate the maximum expansion of multi-call encoding.
+
Parameters
+ + +
uncompressed_sizeSize in bytes of the uncompressed input data
+
+
+
Returns
Maximum number of bytes needed to store the compressed data.
+ +
+
+ +

◆ lzma_stream_buffer_encode()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_stream_buffer_encode (lzma_filter * filters,
lzma_check check,
const lzma_allocator * allocator,
const uint8_t * in,
size_t in_size,
uint8_t * out,
size_t * out_pos,
size_t out_size 
)
+ 		+extern
+
+ +

Single-call .xz Stream encoder.

+
Parameters
+ + + + + + + + + +
filtersArray of filters terminated with .id == LZMA_VLI_UNKNOWN. See filters.h for more information.
checkType of the integrity check to calculate from uncompressed data.
allocatorlzma_allocator for custom allocator functions. Set to NULL to use malloc() and free().
inBeginning of the input buffer
in_sizeSize of the input buffer
[out]outBeginning of the output buffer
[out]out_posThe next byte will be written to out[*out_pos]. *out_pos is updated only if encoding succeeds.
out_sizeSize of the out buffer; the first byte into which no data is written to is out[out_size].
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: Encoding was successful.
    • +
  • LZMA_BUF_ERROR: Not enough output buffer space.
    • +
  • LZMA_UNSUPPORTED_CHECK
    • +
  • LZMA_OPTIONS_ERROR
    • +
  • LZMA_MEM_ERROR
    • +
  • LZMA_DATA_ERROR
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+ +

◆ lzma_microlzma_encoder()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + +
lzma_ret lzma_microlzma_encoder (lzma_stream * strm,
const lzma_options_lzma * options 
)
+ 		+extern
+
+ +

MicroLZMA encoder.

+

The MicroLZMA format is a raw LZMA stream whose first byte (always 0x00) has been replaced with bitwise-negation of the LZMA properties (lc/lp/pb). This encoding ensures that the first byte of MicroLZMA stream is never 0x00. There is no end of payload marker and thus the uncompressed size must be stored separately. For the best error detection the dictionary size should be stored separately as well but alternatively one may use the uncompressed size as the dictionary size when decoding.

+

With the MicroLZMA encoder, lzma_code() behaves slightly unusually. The action argument must be LZMA_FINISH and the return value will never be LZMA_OK. Thus the encoding is always done with a single lzma_code() after the initialization. The benefit of the combination of initialization function and lzma_code() is that memory allocations can be re-used for better performance.

+

lzma_code() will try to encode as much input as is possible to fit into the given output buffer. If not all input can be encoded, the stream will be finished without encoding all the input. The caller must check both input and output buffer usage after lzma_code() (total_in and total_out in lzma_stream can be convenient). Often lzma_code() can fill the output buffer completely if there is a lot of input, but sometimes a few bytes may remain unused because the next LZMA symbol would require more space.

+

lzma_stream.avail_out must be at least 6. Otherwise LZMA_PROG_ERROR will be returned.

+

The LZMA dictionary should be reasonably low to speed up the encoder re-initialization. A good value is bigger than the resulting uncompressed size of most of the output chunks. For example, if output size is 4 KiB, dictionary size of 32 KiB or 64 KiB is good. If the data compresses extremely well, even 128 KiB may be useful.

+

The MicroLZMA format and this encoder variant were made with the EROFS file system in mind. This format may be convenient in other embedded uses too where many small streams are needed. XZ Embedded includes a decoder for this format.

+
Parameters
+ + + +
strmPointer to lzma_stream that is at least initialized with LZMA_STREAM_INIT.
optionsPointer to encoder options
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_STREAM_END: All good. Check the amounts of input used and output produced. Store the amount of input used (uncompressed size) as it needs to be known to decompress the data.
    • +
  • LZMA_OPTIONS_ERROR
    • +
  • LZMA_MEM_ERROR
    • +
  • LZMA_PROG_ERROR: In addition to the generic reasons for this error code, this may also be returned if there isn't enough output space (6 bytes) to create a valid MicroLZMA stream.
    • +
+
+ +
+
+ +

◆ lzma_stream_decoder()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_stream_decoder (lzma_stream * strm,
uint64_t memlimit,
uint32_t flags 
)
+ 		+extern
+
+ +

Initialize .xz Stream decoder.

+
Parameters
+ + + + +
strmPointer to lzma_stream that is at least initialized with LZMA_STREAM_INIT.
memlimitMemory usage limit as bytes. Use UINT64_MAX to effectively disable the limiter. liblzma 5.2.3 and earlier don't allow 0 here and return LZMA_PROG_ERROR; later versions treat 0 as if 1 had been specified.
flagsBitwise-or of zero or more of the decoder flags: LZMA_TELL_NO_CHECK, LZMA_TELL_UNSUPPORTED_CHECK, LZMA_TELL_ANY_CHECK, LZMA_IGNORE_CHECK, LZMA_CONCATENATED, LZMA_FAIL_FAST
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: Initialization was successful.
    • +
  • LZMA_MEM_ERROR: Cannot allocate memory.
    • +
  • LZMA_OPTIONS_ERROR: Unsupported flags
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+ +

◆ lzma_stream_decoder_mt()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + +
lzma_ret lzma_stream_decoder_mt (lzma_stream * strm,
const lzma_mt * options 
)
+ 		+extern
+
+ +

Initialize multithreaded .xz Stream decoder.

+

The decoder can decode multiple Blocks in parallel. This requires that each Block Header contains the Compressed Size and Uncompressed size fields which are added by the multi-threaded encoder, see lzma_stream_encoder_mt().

+

A Stream with one Block will only utilize one thread. A Stream with multiple Blocks but without size information in Block Headers will be processed in single-threaded mode in the same way as done by lzma_stream_decoder(). Concatenated Streams are processed one Stream at a time; no inter-Stream parallelization is done.

+

This function behaves like lzma_stream_decoder() when options->threads == 1 and options->memlimit_threading <= 1.

+
Parameters
+ + + +
strmPointer to lzma_stream that is at least initialized with LZMA_STREAM_INIT.
optionsPointer to multithreaded compression options
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: Initialization was successful.
    • +
  • LZMA_MEM_ERROR: Cannot allocate memory.
    • +
  • LZMA_MEMLIMIT_ERROR: Memory usage limit was reached.
    • +
  • LZMA_OPTIONS_ERROR: Unsupported flags.
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+ +

◆ lzma_auto_decoder()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_auto_decoder (lzma_stream * strm,
uint64_t memlimit,
uint32_t flags 
)
+ 		+extern
+
+ +

Decode .xz, .lzma, and .lz (lzip) files with autodetection.

+

This decoder autodetects between the .xz, .lzma, and .lz file formats, and calls lzma_stream_decoder(), lzma_alone_decoder(), or lzma_lzip_decoder() once the type of the input file has been detected.

+

Support for .lz was added in 5.4.0.

+

If the flag LZMA_CONCATENATED is used and the input is a .lzma file: For historical reasons concatenated .lzma files aren't supported. If there is trailing data after one .lzma stream, lzma_code() will return LZMA_DATA_ERROR. (lzma_alone_decoder() doesn't have such a check as it doesn't support any decoder flags. It will return LZMA_STREAM_END after one .lzma stream.)

+
Parameters
+ + + + +
strmPointer to lzma_stream that is at least initialized with LZMA_STREAM_INIT.
memlimitMemory usage limit as bytes. Use UINT64_MAX to effectively disable the limiter. liblzma 5.2.3 and earlier don't allow 0 here and return LZMA_PROG_ERROR; later versions treat 0 as if 1 had been specified.
flagsBitwise-or of zero or more of the decoder flags: LZMA_TELL_NO_CHECK, LZMA_TELL_UNSUPPORTED_CHECK, LZMA_TELL_ANY_CHECK, LZMA_IGNORE_CHECK, LZMA_CONCATENATED, LZMA_FAIL_FAST
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: Initialization was successful.
    • +
  • LZMA_MEM_ERROR: Cannot allocate memory.
    • +
  • LZMA_OPTIONS_ERROR: Unsupported flags
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+ +

◆ lzma_alone_decoder()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + +
lzma_ret lzma_alone_decoder (lzma_stream * strm,
uint64_t memlimit 
)
+ 		+extern
+
+ +

Initialize .lzma decoder (legacy file format)

+

Valid 'action' arguments to lzma_code() are LZMA_RUN and LZMA_FINISH. There is no need to use LZMA_FINISH, but it's allowed because it may simplify certain types of applications.

+
Parameters
+ + + +
strmPointer to lzma_stream that is at least initialized with LZMA_STREAM_INIT.
memlimitMemory usage limit as bytes. Use UINT64_MAX to effectively disable the limiter. liblzma 5.2.3 and earlier don't allow 0 here and return LZMA_PROG_ERROR; later versions treat 0 as if 1 had been specified.
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK
    • +
  • LZMA_MEM_ERROR
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+ +

◆ lzma_lzip_decoder()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_lzip_decoder (lzma_stream * strm,
uint64_t memlimit,
uint32_t flags 
)
+ 		+extern
+
+ +

Initialize .lz (lzip) decoder (a foreign file format)

+

This decoder supports the .lz format version 0 and the unextended .lz format version 1:

+
    +
  • Files in the format version 0 were produced by lzip 1.3 and older. Such files aren't common but may be found from file archives as a few source packages were released in this format. People might have old personal files in this format too. Decompression support for the format version 0 was removed in lzip 1.18.
    • +
  • lzip 1.3 added decompression support for .lz format version 1 files. Compression support was added in lzip 1.4. In lzip 1.6 the .lz format version 1 was extended to support the Sync Flush marker. This extension is not supported by liblzma. lzma_code() will return LZMA_DATA_ERROR at the location of the Sync Flush marker. In practice files with the Sync Flush marker are very rare and thus liblzma can decompress almost all .lz files.
    • +
+

Just like with lzma_stream_decoder() for .xz files, LZMA_CONCATENATED should be used when decompressing normal standalone .lz files.

+

The .lz format allows putting non-.lz data at the end of a file after at least one valid .lz member. That is, one can append custom data at the end of a .lz file and the decoder is required to ignore it. In liblzma this is relevant only when LZMA_CONCATENATED is used. In that case lzma_code() will return LZMA_STREAM_END and leave lzma_stream.next_in pointing to the first byte of the non-.lz data. An exception to this is if the first 1-3 bytes of the non-.lz data are identical to the .lz magic bytes (0x4C, 0x5A, 0x49, 0x50; "LZIP" in US-ASCII). In such a case the 1-3 bytes will have been ignored by lzma_code(). If one wishes to locate the non-.lz data reliably, one must ensure that the first byte isn't 0x4C. Actually one should ensure that none of the first four bytes of trailing data are equal to the magic bytes because lzip >= 1.20 requires it by default.

+
Parameters
+ + + + +
strmPointer to lzma_stream that is at least initialized with LZMA_STREAM_INIT.
memlimitMemory usage limit as bytes. Use UINT64_MAX to effectively disable the limiter.
flagsBitwise-or of flags, or zero for no flags. All decoder flags listed above are supported although only LZMA_CONCATENATED and (in very rare cases) LZMA_IGNORE_CHECK are actually useful. LZMA_TELL_NO_CHECK, LZMA_TELL_UNSUPPORTED_CHECK, and LZMA_FAIL_FAST do nothing. LZMA_TELL_ANY_CHECK is supported for consistency only as CRC32 is always used in the .lz format.
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: Initialization was successful.
    • +
  • LZMA_MEM_ERROR: Cannot allocate memory.
    • +
  • LZMA_OPTIONS_ERROR: Unsupported flags
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+ +

◆ lzma_stream_buffer_decode()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_stream_buffer_decode (uint64_t * memlimit,
uint32_t flags,
const lzma_allocator * allocator,
const uint8_t * in,
size_t * in_pos,
size_t in_size,
uint8_t * out,
size_t * out_pos,
size_t out_size 
)
+ 		+extern
+
+ +

Single-call .xz Stream decoder.

+
Parameters
+ + + + + + + + + + +
memlimitPointer to how much memory the decoder is allowed to allocate. The value pointed by this pointer is modified if and only if LZMA_MEMLIMIT_ERROR is returned.
flagsBitwise-or of zero or more of the decoder flags: LZMA_TELL_NO_CHECK, LZMA_TELL_UNSUPPORTED_CHECK, LZMA_IGNORE_CHECK, LZMA_CONCATENATED, LZMA_FAIL_FAST. Note that LZMA_TELL_ANY_CHECK is not allowed and will return LZMA_PROG_ERROR.
allocatorlzma_allocator for custom allocator functions. Set to NULL to use malloc() and free().
inBeginning of the input buffer
in_posThe next byte will be read from in[*in_pos]. *in_pos is updated only if decoding succeeds.
in_sizeSize of the input buffer; the first byte that won't be read is in[in_size].
[out]outBeginning of the output buffer
[out]out_posThe next byte will be written to out[*out_pos]. *out_pos is updated only if decoding succeeds.
out_sizeSize of the out buffer; the first byte into which no data is written to is out[out_size].
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: Decoding was successful.
    • +
  • LZMA_FORMAT_ERROR
    • +
  • LZMA_OPTIONS_ERROR
    • +
  • LZMA_DATA_ERROR
    • +
  • LZMA_NO_CHECK: This can be returned only if using the LZMA_TELL_NO_CHECK flag.
    • +
  • LZMA_UNSUPPORTED_CHECK: This can be returned only if using the LZMA_TELL_UNSUPPORTED_CHECK flag.
    • +
  • LZMA_MEM_ERROR
    • +
  • LZMA_MEMLIMIT_ERROR: Memory usage limit was reached. The minimum required memlimit value was stored to *memlimit.
    • +
  • LZMA_BUF_ERROR: Output buffer was too small.
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+ +

◆ lzma_microlzma_decoder()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_microlzma_decoder (lzma_stream * strm,
uint64_t comp_size,
uint64_t uncomp_size,
lzma_bool uncomp_size_is_exact,
uint32_t dict_size 
)
+ 		+extern
+
+ +

MicroLZMA decoder.

+

See lzma_microlzma_encoder() for more information.

+

The lzma_code() usage with this decoder is completely normal. The special behavior of lzma_code() applies to lzma_microlzma_encoder() only.

+
Parameters
+ + + + + + +
strmPointer to lzma_stream that is at least initialized with LZMA_STREAM_INIT.
comp_sizeCompressed size of the MicroLZMA stream. The caller must somehow know this exactly.
uncomp_sizeUncompressed size of the MicroLZMA stream. If the exact uncompressed size isn't known, this can be set to a value that is at most as big as the exact uncompressed size would be, but then the next argument uncomp_size_is_exact must be false.
uncomp_size_is_exactIf true, uncomp_size must be exactly correct. This will improve error detection at the end of the stream. If the exact uncompressed size isn't known, this must be false. uncomp_size must still be at most as big as the exact uncompressed size is. Setting this to false when the exact size is known will work but error detection at the end of the stream will be weaker.
dict_sizeLZMA dictionary size that was used when compressing the data. It is OK to use a bigger value too but liblzma will then allocate more memory than would actually be required and error detection will be slightly worse. (Note that with the implementation in XZ Embedded it doesn't affect the memory usage if one specifies bigger dictionary than actually required.)
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK
    • +
  • LZMA_MEM_ERROR
    • +
  • LZMA_OPTIONS_ERROR
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+
+
+

+ XZ logo © 2023 by Jia Tan is licensed under + + CC BY-SA 4.0 + +

+ + diff --git a/doc/api/delta_8h.html b/doc/api/delta_8h.html new file mode 100644 index 00000000..ad7b3ceb --- /dev/null +++ b/doc/api/delta_8h.html @@ -0,0 +1,138 @@ + + + + + + + +liblzma (XZ Utils): lzma/delta.h File Reference + + + + + + +
+
+ + + + + + + +
+
liblzma (XZ Utils) 5.6.0 +
+
+
+ + + + + +
+
+
+Data Structures | +Macros | +Enumerations
+
delta.h File Reference
+
+
+ +

Delta filter. +More...

+ + + + + +

+Data Structures

struct  lzma_options_delta
 Options for the Delta filter. More...
 
+ + + + + + + + + + +

+Macros

#define LZMA_FILTER_DELTA   LZMA_VLI_C(0x03)
 Filter ID.
 
+#define LZMA_DELTA_DIST_MIN   1
 Minimum value for lzma_options_delta.dist.
 
+#define LZMA_DELTA_DIST_MAX   256
 Maximum value for lzma_options_delta.dist.
 
+ + + + +

+Enumerations

enum  lzma_delta_type { LZMA_DELTA_TYPE_BYTE + }
 Type of the delta calculation. More...
 
+

Detailed Description

+

Delta filter.

+
Note
Never include this file directly. Use <lzma.h> instead.
+

Macro Definition Documentation

+ +

◆ LZMA_FILTER_DELTA

+ +
+
+ + + + +
#define LZMA_FILTER_DELTA   LZMA_VLI_C(0x03)
+
+ +

Filter ID.

+

Filter ID of the Delta filter. This is used as lzma_filter.id.

+ +
+
+

Enumeration Type Documentation

+ +

◆ lzma_delta_type

+ +
+
+ + + + +
enum lzma_delta_type
+
+ +

Type of the delta calculation.

+

Currently only byte-wise delta is supported. Other possible types could be, for example, delta of 16/32/64-bit little/big endian integers, but these are not currently planned since byte-wise delta is almost as good.

+ +
+
+
+
+

+ XZ logo © 2023 by Jia Tan is licensed under + + CC BY-SA 4.0 + +

+ + diff --git a/doc/api/dir_b17a1d403082bd69a703ed987cf158fb.html b/doc/api/dir_b17a1d403082bd69a703ed987cf158fb.html new file mode 100644 index 00000000..0d1bcc0b --- /dev/null +++ b/doc/api/dir_b17a1d403082bd69a703ed987cf158fb.html @@ -0,0 +1,110 @@ + + + + + + + +liblzma (XZ Utils): lzma Directory Reference + + + + + + +
+
+ + + + + + + +
+
liblzma (XZ Utils) 5.6.0 +
+
+
+ + + + + +
+
+
lzma Directory Reference
+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+Files

 base.h
 Data types and functions used in many places in liblzma API.
 
 bcj.h
 Branch/Call/Jump conversion filters.
 
 block.h
 .xz Block handling
 
 check.h
 Integrity checks.
 
 container.h
 File formats.
 
 delta.h
 Delta filter.
 
 filter.h
 Common filter related types and functions.
 
 hardware.h
 Hardware information.
 
 index.h
 Handling of .xz Index and related information.
 
 index_hash.h
 Validate Index by using a hash function.
 
 lzma12.h
 LZMA1 and LZMA2 filters.
 
 stream_flags.h
 .xz Stream Header and Stream Footer encoder and decoder
 
 version.h
 Version number.
 
 vli.h
 Variable-length integer handling.
 
+
+
+

+ XZ logo © 2023 by Jia Tan is licensed under + + CC BY-SA 4.0 + +

+ + diff --git a/doc/api/doc.svg b/doc/api/doc.svg new file mode 100644 index 00000000..296728b1 --- /dev/null +++ b/doc/api/doc.svg @@ -0,0 +1,12 @@ + + + + + + + + + + + diff --git a/doc/api/docd.svg b/doc/api/docd.svg new file mode 100644 index 00000000..65cf4b50 --- /dev/null +++ b/doc/api/docd.svg @@ -0,0 +1,12 @@ + + + + + + + + + + + diff --git a/doc/api/doxygen.css b/doc/api/doxygen.css new file mode 100644 index 00000000..43bca01f --- /dev/null +++ b/doc/api/doxygen.css @@ -0,0 +1,2045 @@ +/* The standard CSS for doxygen 1.9.8*/ + +html { +/* page base colors */ +--page-background-color: white; +--page-foreground-color: black; +--page-link-color: #144779; +--page-visited-link-color: #195794; + +/* index */ +--index-odd-item-bg-color: #F3F8FD; +--index-even-item-bg-color: white; +--index-header-color: black; +--index-separator-color: #A0A0A0; + +/* header */ +--header-background-color: #F5F9FD; +--header-separator-color: #A0C7EE; +--header-gradient-image: url('nav_h.png'); +--group-header-separator-color: #4491DE; +--group-header-color: #113B65; +--inherit-header-color: gray; + +--footer-foreground-color: #0C2B4A; +--footer-logo-width: 104px; +--citation-label-color: #10375F; +--glow-color: cyan; + +--title-background-color: white; +--title-separator-color: #1E67AF; +--directory-separator-color: #62A3E4; +--separator-color: #1B5D9E; + +--blockquote-background-color: #F1F7FC; +--blockquote-border-color: #62A3E4; + +--scrollbar-thumb-color: #62A3E4; +--scrollbar-background-color: #F5F9FD; + +--icon-background-color: #257FD9; +--icon-foreground-color: white; +--icon-doc-image: url('doc.svg'); +--icon-folder-open-image: url('folderopen.svg'); +--icon-folder-closed-image: url('folderclosed.svg'); + +/* brief member declaration list */ +--memdecl-background-color: #F5F9FD; +--memdecl-separator-color: #C8DFF5; +--memdecl-foreground-color: #555; +--memdecl-template-color: #195794; + +/* detailed member list */ +--memdef-border-color: #74ADE7; +--memdef-title-background-color: #D0E3F6; +--memdef-title-gradient-image: url('nav_f.png'); +--memdef-proto-background-color: #CAE0F5; +--memdef-proto-text-color: #0A233D; +--memdef-proto-text-shadow: 0px 1px 1px rgba(255, 255, 255, 0.9); +--memdef-doc-background-color: white; +--memdef-param-name-color: #602020; +--memdef-template-color: #195794; + +/* tables */ +--table-cell-border-color: #0D2F50; +--table-header-background-color: #123E6A; +--table-header-foreground-color: #FFFFFF; + +/* labels */ +--label-background-color: #257FD9; +--label-left-top-border-color: #1E67AF; +--label-right-bottom-border-color: #A0C7EE; +--label-foreground-color: white; + +/** navigation bar/tree/menu */ +--nav-background-color: #F5F9FD; +--nav-foreground-color: #113C67; +--nav-gradient-image: url('tab_b.png'); +--nav-gradient-hover-image: url('tab_h.png'); +--nav-gradient-active-image: url('tab_a.png'); +--nav-gradient-active-image-parent: url("../tab_a.png"); +--nav-separator-image: url('tab_s.png'); +--nav-breadcrumb-image: url('bc_s.png'); +--nav-breadcrumb-border-color: #9CC5EE; +--nav-splitbar-image: url('splitbar.png'); +--nav-font-size-level1: 13px; +--nav-font-size-level2: 10px; +--nav-font-size-level3: 9px; +--nav-text-normal-color: #0B2845; +--nav-text-hover-color: white; +--nav-text-active-color: white; +--nav-text-normal-shadow: 0px 1px 1px rgba(255, 255, 255, 0.9); +--nav-text-hover-shadow: 0px 1px 1px rgba(0, 0, 0, 1.0); +--nav-text-active-shadow: 0px 1px 1px rgba(0, 0, 0, 1.0); +--nav-menu-button-color: #113C67; +--nav-menu-background-color: white; +--nav-menu-foreground-color: #555555; +--nav-menu-toggle-color: rgba(255, 255, 255, 0.5); +--nav-arrow-color: #62A3E4; +--nav-arrow-selected-color: #62A3E4; + +/* table of contents */ +--toc-background-color: #EEF5FC; +--toc-border-color: #BFD9F4; +--toc-header-color: #195794; +--toc-down-arrow-image: url("data:image/svg+xml;utf8,&%238595;"); + +/** search field */ +--search-background-color: white; +--search-foreground-color: #909090; +--search-magnification-image: url('mag.svg'); +--search-magnification-select-image: url('mag_sel.svg'); +--search-active-color: black; +--search-filter-background-color: #F5F9FD; +--search-filter-foreground-color: black; +--search-filter-border-color: #5098E0; +--search-filter-highlight-text-color: white; +--search-filter-highlight-bg-color: #144779; +--search-results-foreground-color: #174F86; +--search-results-background-color: #E2EEFA; +--search-results-border-color: black; +--search-box-shadow: inset 0.5px 0.5px 3px 0px #555; + +/** code fragments */ +--code-keyword-color: #008000; +--code-type-keyword-color: #604020; +--code-flow-keyword-color: #E08000; +--code-comment-color: #800000; +--code-preprocessor-color: #806020; +--code-string-literal-color: #002080; +--code-char-literal-color: #008080; +--code-xml-cdata-color: black; +--code-vhdl-digit-color: #FF00FF; +--code-vhdl-char-color: #000000; +--code-vhdl-keyword-color: #700070; +--code-vhdl-logic-color: #FF0000; +--code-link-color: #195794; +--code-external-link-color: #195794; +--fragment-foreground-color: black; +--fragment-background-color: #F9FBFE; +--fragment-border-color: #A0C7EE; +--fragment-lineno-border-color: #00FF00; +--fragment-lineno-background-color: #E8E8E8; +--fragment-lineno-foreground-color: black; +--fragment-lineno-link-fg-color: #195794; +--fragment-lineno-link-bg-color: #D8D8D8; +--fragment-lineno-link-hover-fg-color: #195794; +--fragment-lineno-link-hover-bg-color: #C8C8C8; +--tooltip-foreground-color: black; +--tooltip-background-color: white; +--tooltip-border-color: gray; +--tooltip-doc-color: grey; +--tooltip-declaration-color: #006318; +--tooltip-link-color: #195794; +--tooltip-shadow: 1px 1px 7px gray; +--fold-line-color: #808080; +--fold-minus-image: url('minus.svg'); +--fold-plus-image: url('plus.svg'); +--fold-minus-image-relpath: url('../../minus.svg'); +--fold-plus-image-relpath: url('../../plus.svg'); + +/** font-family */ +--font-family-normal: Roboto,sans-serif; +--font-family-monospace: 'JetBrains Mono',Consolas,Monaco,'Andale Mono','Ubuntu Mono',monospace,fixed; +--font-family-nav: 'Lucida Grande',Geneva,Helvetica,Arial,sans-serif; +--font-family-title: Tahoma,Arial,sans-serif; +--font-family-toc: Verdana,'DejaVu Sans',Geneva,sans-serif; +--font-family-search: Arial,Verdana,sans-serif; +--font-family-icon: Arial,Helvetica; +--font-family-tooltip: Roboto,sans-serif; + +} + +@media (prefers-color-scheme: dark) { + html:not(.dark-mode) { + color-scheme: dark; + +/* page base colors */ +--page-background-color: black; +--page-foreground-color: #C9D1D9; +--page-link-color: #5098E0; +--page-visited-link-color: #6DA9E5; + +/* index */ +--index-odd-item-bg-color: #02070C; +--index-even-item-bg-color: black; +--index-header-color: #A0C7EE; +--index-separator-color: #10375F; + +/* header */ +--header-background-color: #010407; +--header-separator-color: #040F1A; +--header-gradient-image: url('nav_hd.png'); +--group-header-separator-color: #0B2845; +--group-header-color: #5098E0; +--inherit-header-color: #A0A0A0; + +--footer-foreground-color: #206DBA; +--footer-logo-width: 60px; +--citation-label-color: #5098E0; +--glow-color: cyan; + +--title-background-color: #010509; +--title-separator-color: #113A63; +--directory-separator-color: #0B2845; +--separator-color: #0B2845; + +--blockquote-background-color: #030C14; +--blockquote-border-color: #0B2845; + +--scrollbar-thumb-color: #0B2845; +--scrollbar-background-color: #010407; + +--icon-background-color: #10375F; +--icon-foreground-color: #A0C7EE; +--icon-doc-image: url('docd.svg'); +--icon-folder-open-image: url('folderopend.svg'); +--icon-folder-closed-image: url('folderclosedd.svg'); + +/* brief member declaration list */ +--memdecl-background-color: #02070C; +--memdecl-separator-color: #0D2D4D; +--memdecl-foreground-color: #BBB; +--memdecl-template-color: #3488DC; + +/* detailed member list */ +--memdef-border-color: #092138; +--memdef-title-background-color: #071829; +--memdef-title-gradient-image: url('nav_fd.png'); +--memdef-proto-background-color: #061524; +--memdef-proto-text-color: #64A4E4; +--memdef-proto-text-shadow: 0px 1px 1px rgba(0, 0, 0, 0.9); +--memdef-doc-background-color: black; +--memdef-param-name-color: #D28757; +--memdef-template-color: #3488DC; + +/* tables */ +--table-cell-border-color: #0B2845; +--table-header-background-color: #0B2845; +--table-header-foreground-color: #A0C7EE; + +/* labels */ +--label-background-color: #113B65; +--label-left-top-border-color: #195794; +--label-right-bottom-border-color: #0B2845; +--label-foreground-color: #CCCCCC; + +/** navigation bar/tree/menu */ +--nav-background-color: #030C14; +--nav-foreground-color: #113C67; +--nav-gradient-image: url('tab_bd.png'); +--nav-gradient-hover-image: url('tab_hd.png'); +--nav-gradient-active-image: url('tab_ad.png'); +--nav-gradient-active-image-parent: url("../tab_ad.png"); +--nav-separator-image: url('tab_sd.png'); +--nav-breadcrumb-image: url('bc_sd.png'); +--nav-breadcrumb-border-color: #0C2B4A; +--nav-splitbar-image: url('splitbard.png'); +--nav-font-size-level1: 13px; +--nav-font-size-level2: 10px; +--nav-font-size-level3: 9px; +--nav-text-normal-color: #8ABAEA; +--nav-text-hover-color: #C5DDF5; +--nav-text-active-color: #C5DDF5; +--nav-text-normal-shadow: 0px 1px 1px black; +--nav-text-hover-shadow: 0px 1px 1px rgba(0, 0, 0, 1.0); +--nav-text-active-shadow: 0px 1px 1px rgba(0, 0, 0, 1.0); +--nav-menu-button-color: #8ABAEA; +--nav-menu-background-color: #000204; +--nav-menu-foreground-color: #BBBBBB; +--nav-menu-toggle-color: rgba(255, 255, 255, 0.2); +--nav-arrow-color: #10375F; +--nav-arrow-selected-color: #5098E0; + +/* table of contents */ +--toc-background-color: #04101B; +--toc-border-color: #081D32; +--toc-header-color: #6DA9E5; +--toc-down-arrow-image: url("data:image/svg+xml;utf8,&%238595;"); + +/** search field */ +--search-background-color: black; +--search-foreground-color: #C5C5C5; +--search-magnification-image: url('mag_d.svg'); +--search-magnification-select-image: url('mag_seld.svg'); +--search-active-color: #C5C5C5; +--search-filter-background-color: #030C14; +--search-filter-foreground-color: #5098E0; +--search-filter-border-color: #3488DC; +--search-filter-highlight-text-color: #93BFEC; +--search-filter-highlight-bg-color: #0B2845; +--search-results-background-color: #030C14; +--search-results-foreground-color: #5098E0; +--search-results-border-color: #3488DC; +--search-box-shadow: inset 0.5px 0.5px 3px 0px #0E3255; + +/** code fragments */ +--code-keyword-color: #CC99CD; +--code-type-keyword-color: #AB99CD; +--code-flow-keyword-color: #E08000; +--code-comment-color: #717790; +--code-preprocessor-color: #65CABE; +--code-string-literal-color: #7EC699; +--code-char-literal-color: #00E0F0; +--code-xml-cdata-color: #C9D1D9; +--code-vhdl-digit-color: #FF00FF; +--code-vhdl-char-color: #C0C0C0; +--code-vhdl-keyword-color: #CF53C9; +--code-vhdl-logic-color: #FF0000; +--code-link-color: #79C0FF; +--code-external-link-color: #79C0FF; +--fragment-foreground-color: #C9D1D9; +--fragment-background-color: black; +--fragment-border-color: #30363D; +--fragment-lineno-border-color: #30363D; +--fragment-lineno-background-color: black; +--fragment-lineno-foreground-color: #6E7681; +--fragment-lineno-link-fg-color: #6E7681; +--fragment-lineno-link-bg-color: #303030; +--fragment-lineno-link-hover-fg-color: #8E96A1; +--fragment-lineno-link-hover-bg-color: #505050; +--tooltip-foreground-color: #C9D1D9; +--tooltip-background-color: #202020; +--tooltip-border-color: #C9D1D9; +--tooltip-doc-color: #D9E1E9; +--tooltip-declaration-color: #20C348; +--tooltip-link-color: #79C0FF; +--tooltip-shadow: none; +--fold-line-color: #808080; +--fold-minus-image: url('minusd.svg'); +--fold-plus-image: url('plusd.svg'); +--fold-minus-image-relpath: url('../../minusd.svg'); +--fold-plus-image-relpath: url('../../plusd.svg'); + +/** font-family */ +--font-family-normal: Roboto,sans-serif; +--font-family-monospace: 'JetBrains Mono',Consolas,Monaco,'Andale Mono','Ubuntu Mono',monospace,fixed; +--font-family-nav: 'Lucida Grande',Geneva,Helvetica,Arial,sans-serif; +--font-family-title: Tahoma,Arial,sans-serif; +--font-family-toc: Verdana,'DejaVu Sans',Geneva,sans-serif; +--font-family-search: Arial,Verdana,sans-serif; +--font-family-icon: Arial,Helvetica; +--font-family-tooltip: Roboto,sans-serif; + +}} +body { + background-color: var(--page-background-color); + color: var(--page-foreground-color); +} + +body, table, div, p, dl { + font-weight: 400; + font-size: 14px; + font-family: var(--font-family-normal); + line-height: 22px; +} + +/* @group Heading Levels */ + +.title { + font-weight: 400; + font-size: 14px; + font-family: var(--font-family-normal); + line-height: 28px; + font-size: 150%; + font-weight: bold; + margin: 10px 2px; +} + +h1.groupheader { + font-size: 150%; +} + +h2.groupheader { + border-bottom: 1px solid var(--group-header-separator-color); + color: var(--group-header-color); + font-size: 150%; + font-weight: normal; + margin-top: 1.75em; + padding-top: 8px; + padding-bottom: 4px; + width: 100%; +} + +h3.groupheader { + font-size: 100%; +} + +h1, h2, h3, h4, h5, h6 { + -webkit-transition: text-shadow 0.5s linear; + -moz-transition: text-shadow 0.5s linear; + -ms-transition: text-shadow 0.5s linear; + -o-transition: text-shadow 0.5s linear; + transition: text-shadow 0.5s linear; + margin-right: 15px; +} + +h1.glow, h2.glow, h3.glow, h4.glow, h5.glow, h6.glow { + text-shadow: 0 0 15px var(--glow-color); +} + +dt { + font-weight: bold; +} + +p.startli, p.startdd { + margin-top: 2px; +} + +th p.starttd, th p.intertd, th p.endtd { + font-size: 100%; + font-weight: 700; +} + +p.starttd { + margin-top: 0px; +} + +p.endli { + margin-bottom: 0px; +} + +p.enddd { + margin-bottom: 4px; +} + +p.endtd { + margin-bottom: 2px; +} + +p.interli { +} + +p.interdd { +} + +p.intertd { +} + +/* @end */ + +caption { + font-weight: bold; +} + +span.legend { + font-size: 70%; + text-align: center; +} + +h3.version { + font-size: 90%; + text-align: center; +} + +div.navtab { + padding-right: 15px; + text-align: right; + line-height: 110%; +} + +div.navtab table { + border-spacing: 0; +} + +td.navtab { + padding-right: 6px; + padding-left: 6px; +} + +td.navtabHL { + background-image: var(--nav-gradient-active-image); + background-repeat:repeat-x; + padding-right: 6px; + padding-left: 6px; +} + +td.navtabHL a, td.navtabHL a:visited { + color: var(--nav-text-hover-color); + text-shadow: var(--nav-text-hover-shadow); +} + +a.navtab { + font-weight: bold; +} + +div.qindex{ + text-align: center; + width: 100%; + line-height: 140%; + font-size: 130%; + color: var(--index-separator-color); +} + +#main-menu a:focus { + outline: auto; + z-index: 10; + position: relative; +} + +dt.alphachar{ + font-size: 180%; + font-weight: bold; +} + +.alphachar a{ + color: var(--index-header-color); +} + +.alphachar a:hover, .alphachar a:visited{ + text-decoration: none; +} + +.classindex dl { + padding: 25px; + column-count:1 +} + +.classindex dd { + display:inline-block; + margin-left: 50px; + width: 90%; + line-height: 1.15em; +} + +.classindex dl.even { + background-color: var(--index-even-item-bg-color); +} + +.classindex dl.odd { + background-color: var(--index-odd-item-bg-color); +} + +@media(min-width: 1120px) { + .classindex dl { + column-count:2 + } +} + +@media(min-width: 1320px) { + .classindex dl { + column-count:3 + } +} + + +/* @group Link Styling */ + +a { + color: var(--page-link-color); + font-weight: normal; + text-decoration: none; +} + +.contents a:visited { + color: var(--page-visited-link-color); +} + +a:hover { + text-decoration: underline; +} + +a.el { + font-weight: bold; +} + +a.elRef { +} + +a.code, a.code:visited, a.line, a.line:visited { + color: var(--code-link-color); +} + +a.codeRef, a.codeRef:visited, a.lineRef, a.lineRef:visited { + color: var(--code-external-link-color); +} + +a.code.hl_class { /* style for links to class names in code snippets */ } +a.code.hl_struct { /* style for links to struct names in code snippets */ } +a.code.hl_union { /* style for links to union names in code snippets */ } +a.code.hl_interface { /* style for links to interface names in code snippets */ } +a.code.hl_protocol { /* style for links to protocol names in code snippets */ } +a.code.hl_category { /* style for links to category names in code snippets */ } +a.code.hl_exception { /* style for links to exception names in code snippets */ } +a.code.hl_service { /* style for links to service names in code snippets */ } +a.code.hl_singleton { /* style for links to singleton names in code snippets */ } +a.code.hl_concept { /* style for links to concept names in code snippets */ } +a.code.hl_namespace { /* style for links to namespace names in code snippets */ } +a.code.hl_package { /* style for links to package names in code snippets */ } +a.code.hl_define { /* style for links to macro names in code snippets */ } +a.code.hl_function { /* style for links to function names in code snippets */ } +a.code.hl_variable { /* style for links to variable names in code snippets */ } +a.code.hl_typedef { /* style for links to typedef names in code snippets */ } +a.code.hl_enumvalue { /* style for links to enum value names in code snippets */ } +a.code.hl_enumeration { /* style for links to enumeration names in code snippets */ } +a.code.hl_signal { /* style for links to Qt signal names in code snippets */ } +a.code.hl_slot { /* style for links to Qt slot names in code snippets */ } +a.code.hl_friend { /* style for links to friend names in code snippets */ } +a.code.hl_dcop { /* style for links to KDE3 DCOP names in code snippets */ } +a.code.hl_property { /* style for links to property names in code snippets */ } +a.code.hl_event { /* style for links to event names in code snippets */ } +a.code.hl_sequence { /* style for links to sequence names in code snippets */ } +a.code.hl_dictionary { /* style for links to dictionary names in code snippets */ } + +/* @end */ + +dl.el { + margin-left: -1cm; +} + +ul { + overflow: visible; +} + +ul.multicol { + -moz-column-gap: 1em; + -webkit-column-gap: 1em; + column-gap: 1em; + -moz-column-count: 3; + -webkit-column-count: 3; + column-count: 3; + list-style-type: none; +} + +#side-nav ul { + overflow: visible; /* reset ul rule for scroll bar in GENERATE_TREEVIEW window */ +} + +#main-nav ul { + overflow: visible; /* reset ul rule for the navigation bar drop down lists */ +} + +.fragment { + text-align: left; + direction: ltr; + overflow-x: auto; /*Fixed: fragment lines overlap floating elements*/ + overflow-y: hidden; +} + +pre.fragment { + border: 1px solid var(--fragment-border-color); + background-color: var(--fragment-background-color); + color: var(--fragment-foreground-color); + padding: 4px 6px; + margin: 4px 8px 4px 2px; + overflow: auto; + word-wrap: break-word; + font-size: 9pt; + line-height: 125%; + font-family: var(--font-family-monospace); + font-size: 105%; +} + +div.fragment { + padding: 0 0 1px 0; /*Fixed: last line underline overlap border*/ + margin: 4px 8px 4px 2px; + color: var(--fragment-foreground-color); + background-color: var(--fragment-background-color); + border: 1px solid var(--fragment-border-color); +} + +div.line { + font-family: var(--font-family-monospace); + font-size: 13px; + min-height: 13px; + line-height: 1.2; + text-wrap: unrestricted; + white-space: -moz-pre-wrap; /* Moz */ + white-space: -pre-wrap; /* Opera 4-6 */ + white-space: -o-pre-wrap; /* Opera 7 */ + white-space: pre-wrap; /* CSS3 */ + word-wrap: break-word; /* IE 5.5+ */ + text-indent: -53px; + padding-left: 53px; + padding-bottom: 0px; + margin: 0px; + -webkit-transition-property: background-color, box-shadow; + -webkit-transition-duration: 0.5s; + -moz-transition-property: background-color, box-shadow; + -moz-transition-duration: 0.5s; + -ms-transition-property: background-color, box-shadow; + -ms-transition-duration: 0.5s; + -o-transition-property: background-color, box-shadow; + -o-transition-duration: 0.5s; + transition-property: background-color, box-shadow; + transition-duration: 0.5s; +} + +div.line:after { + content:"\000A"; + white-space: pre; +} + +div.line.glow { + background-color: var(--glow-color); + box-shadow: 0 0 10px var(--glow-color); +} + +span.fold { + margin-left: 5px; + margin-right: 1px; + margin-top: 0px; + margin-bottom: 0px; + padding: 0px; + display: inline-block; + width: 12px; + height: 12px; + background-repeat:no-repeat; + background-position:center; +} + +span.lineno { + padding-right: 4px; + margin-right: 9px; + text-align: right; + border-right: 2px solid var(--fragment-lineno-border-color); + color: var(--fragment-lineno-foreground-color); + background-color: var(--fragment-lineno-background-color); + white-space: pre; +} +span.lineno a, span.lineno a:visited { + color: var(--fragment-lineno-link-fg-color); + background-color: var(--fragment-lineno-link-bg-color); +} + +span.lineno a:hover { + color: var(--fragment-lineno-link-hover-fg-color); + background-color: var(--fragment-lineno-link-hover-bg-color); +} + +.lineno { + -webkit-touch-callout: none; + -webkit-user-select: none; + -khtml-user-select: none; + -moz-user-select: none; + -ms-user-select: none; + user-select: none; +} + +div.classindex ul { + list-style: none; + padding-left: 0; +} + +div.classindex span.ai { + display: inline-block; +} + +div.groupHeader { + margin-left: 16px; + margin-top: 12px; + font-weight: bold; +} + +div.groupText { + margin-left: 16px; + font-style: italic; +} + +body { + color: var(--page-foreground-color); + margin: 0; +} + +div.contents { + margin-top: 10px; + margin-left: 12px; + margin-right: 8px; +} + +p.formulaDsp { + text-align: center; +} + +img.dark-mode-visible { + display: none; +} +img.light-mode-visible { + display: none; +} + +img.formulaDsp { + +} + +img.formulaInl, img.inline { + vertical-align: middle; +} + +div.center { + text-align: center; + margin-top: 0px; + margin-bottom: 0px; + padding: 0px; +} + +div.center img { + border: 0px; +} + +address.footer { + text-align: right; + padding-right: 12px; +} + +img.footer { + border: 0px; + vertical-align: middle; + width: var(--footer-logo-width); +} + +.compoundTemplParams { + color: var(--memdecl-template-color); + font-size: 80%; + line-height: 120%; +} + +/* @group Code Colorization */ + +span.keyword { + color: var(--code-keyword-color); +} + +span.keywordtype { + color: var(--code-type-keyword-color); +} + +span.keywordflow { + color: var(--code-flow-keyword-color); +} + +span.comment { + color: var(--code-comment-color); +} + +span.preprocessor { + color: var(--code-preprocessor-color); +} + +span.stringliteral { + color: var(--code-string-literal-color); +} + +span.charliteral { + color: var(--code-char-literal-color); +} + +span.xmlcdata { + color: var(--code-xml-cdata-color); +} + +span.vhdldigit { + color: var(--code-vhdl-digit-color); +} + +span.vhdlchar { + color: var(--code-vhdl-char-color); +} + +span.vhdlkeyword { + color: var(--code-vhdl-keyword-color); +} + +span.vhdllogic { + color: var(--code-vhdl-logic-color); +} + +blockquote { + background-color: var(--blockquote-background-color); + border-left: 2px solid var(--blockquote-border-color); + margin: 0 24px 0 4px; + padding: 0 12px 0 16px; +} + +/* @end */ + +td.tiny { + font-size: 75%; +} + +.dirtab { + padding: 4px; + border-collapse: collapse; + border: 1px solid var(--table-cell-border-color); +} + +th.dirtab { + background-color: var(--table-header-background-color); + color: var(--table-header-foreground-color); + font-weight: bold; +} + +hr { + height: 0px; + border: none; + border-top: 1px solid var(--separator-color); +} + +hr.footer { + height: 1px; +} + +/* @group Member Descriptions */ + +table.memberdecls { + border-spacing: 0px; + padding: 0px; +} + +.memberdecls td, .fieldtable tr { + -webkit-transition-property: background-color, box-shadow; + -webkit-transition-duration: 0.5s; + -moz-transition-property: background-color, box-shadow; + -moz-transition-duration: 0.5s; + -ms-transition-property: background-color, box-shadow; + -ms-transition-duration: 0.5s; + -o-transition-property: background-color, box-shadow; + -o-transition-duration: 0.5s; + transition-property: background-color, box-shadow; + transition-duration: 0.5s; +} + +.memberdecls td.glow, .fieldtable tr.glow { + background-color: var(--glow-color); + box-shadow: 0 0 15px var(--glow-color); +} + +.mdescLeft, .mdescRight, +.memItemLeft, .memItemRight, +.memTemplItemLeft, .memTemplItemRight, .memTemplParams { + background-color: var(--memdecl-background-color); + border: none; + margin: 4px; + padding: 1px 0 0 8px; +} + +.mdescLeft, .mdescRight { + padding: 0px 8px 4px 8px; + color: var(--memdecl-foreground-color); +} + +.memSeparator { + border-bottom: 1px solid var(--memdecl-separator-color); + line-height: 1px; + margin: 0px; + padding: 0px; +} + +.memItemLeft, .memTemplItemLeft { + white-space: nowrap; +} + +.memItemRight, .memTemplItemRight { + width: 100%; +} + +.memTemplParams { + color: var(--memdecl-template-color); + white-space: nowrap; + font-size: 80%; +} + +/* @end */ + +/* @group Member Details */ + +/* Styles for detailed member documentation */ + +.memtitle { + padding: 8px; + border-top: 1px solid var(--memdef-border-color); + border-left: 1px solid var(--memdef-border-color); + border-right: 1px solid var(--memdef-border-color); + border-top-right-radius: 4px; + border-top-left-radius: 4px; + margin-bottom: -1px; + background-image: var(--memdef-title-gradient-image); + background-repeat: repeat-x; + background-color: var(--memdef-title-background-color); + line-height: 1.25; + font-weight: 300; + float:left; +} + +.permalink +{ + font-size: 65%; + display: inline-block; + vertical-align: middle; +} + +.memtemplate { + font-size: 80%; + color: var(--memdef-template-color); + font-weight: normal; + margin-left: 9px; +} + +.mempage { + width: 100%; +} + +.memitem { + padding: 0; + margin-bottom: 10px; + margin-right: 5px; + -webkit-transition: box-shadow 0.5s linear; + -moz-transition: box-shadow 0.5s linear; + -ms-transition: box-shadow 0.5s linear; + -o-transition: box-shadow 0.5s linear; + transition: box-shadow 0.5s linear; + display: table !important; + width: 100%; +} + +.memitem.glow { + box-shadow: 0 0 15px var(--glow-color); +} + +.memname { + font-weight: 400; + margin-left: 6px; +} + +.memname td { + vertical-align: bottom; +} + +.memproto, dl.reflist dt { + border-top: 1px solid var(--memdef-border-color); + border-left: 1px solid var(--memdef-border-color); + border-right: 1px solid var(--memdef-border-color); + padding: 6px 0px 6px 0px; + color: var(--memdef-proto-text-color); + font-weight: bold; + text-shadow: var(--memdef-proto-text-shadow); + background-color: var(--memdef-proto-background-color); + box-shadow: 5px 5px 5px rgba(0, 0, 0, 0.15); + border-top-right-radius: 4px; +} + +.overload { + font-family: var(--font-family-monospace); + font-size: 65%; +} + +.memdoc, dl.reflist dd { + border-bottom: 1px solid var(--memdef-border-color); + border-left: 1px solid var(--memdef-border-color); + border-right: 1px solid var(--memdef-border-color); + padding: 6px 10px 2px 10px; + border-top-width: 0; + background-image:url('nav_g.png'); + background-repeat:repeat-x; + background-color: var(--memdef-doc-background-color); + /* opera specific markup */ + border-bottom-left-radius: 4px; + border-bottom-right-radius: 4px; + box-shadow: 5px 5px 5px rgba(0, 0, 0, 0.15); + /* firefox specific markup */ + -moz-border-radius-bottomleft: 4px; + -moz-border-radius-bottomright: 4px; + -moz-box-shadow: rgba(0, 0, 0, 0.15) 5px 5px 5px; + /* webkit specific markup */ + -webkit-border-bottom-left-radius: 4px; + -webkit-border-bottom-right-radius: 4px; + -webkit-box-shadow: 5px 5px 5px rgba(0, 0, 0, 0.15); +} + +dl.reflist dt { + padding: 5px; +} + +dl.reflist dd { + margin: 0px 0px 10px 0px; + padding: 5px; +} + +.paramkey { + text-align: right; +} + +.paramtype { + white-space: nowrap; +} + +.paramname { + color: var(--memdef-param-name-color); + white-space: nowrap; +} +.paramname em { + font-style: normal; +} +.paramname code { + line-height: 14px; +} + +.params, .retval, .exception, .tparams { + margin-left: 0px; + padding-left: 0px; +} + +.params .paramname, .retval .paramname, .tparams .paramname, .exception .paramname { + font-weight: bold; + vertical-align: top; +} + +.params .paramtype, .tparams .paramtype { + font-style: italic; + vertical-align: top; +} + +.params .paramdir, .tparams .paramdir { + font-family: var(--font-family-monospace); + vertical-align: top; +} + +table.mlabels { + border-spacing: 0px; +} + +td.mlabels-left { + width: 100%; + padding: 0px; +} + +td.mlabels-right { + vertical-align: bottom; + padding: 0px; + white-space: nowrap; +} + +span.mlabels { + margin-left: 8px; +} + +span.mlabel { + background-color: var(--label-background-color); + border-top:1px solid var(--label-left-top-border-color); + border-left:1px solid var(--label-left-top-border-color); + border-right:1px solid var(--label-right-bottom-border-color); + border-bottom:1px solid var(--label-right-bottom-border-color); + text-shadow: none; + color: var(--label-foreground-color); + margin-right: 4px; + padding: 2px 3px; + border-radius: 3px; + font-size: 7pt; + white-space: nowrap; + vertical-align: middle; +} + + + +/* @end */ + +/* these are for tree view inside a (index) page */ + +div.directory { + margin: 10px 0px; + border-top: 1px solid var(--directory-separator-color); + border-bottom: 1px solid var(--directory-separator-color); + width: 100%; +} + +.directory table { + border-collapse:collapse; +} + +.directory td { + margin: 0px; + padding: 0px; + vertical-align: top; +} + +.directory td.entry { + white-space: nowrap; + padding-right: 6px; + padding-top: 3px; +} + +.directory td.entry a { + outline:none; +} + +.directory td.entry a img { + border: none; +} + +.directory td.desc { + width: 100%; + padding-left: 6px; + padding-right: 6px; + padding-top: 3px; + border-left: 1px solid rgba(0,0,0,0.05); +} + +.directory tr.odd { + padding-left: 6px; + background-color: var(--index-odd-item-bg-color); +} + +.directory tr.even { + padding-left: 6px; + background-color: var(--index-even-item-bg-color); +} + +.directory img { + vertical-align: -30%; +} + +.directory .levels { + white-space: nowrap; + width: 100%; + text-align: right; + font-size: 9pt; +} + +.directory .levels span { + cursor: pointer; + padding-left: 2px; + padding-right: 2px; + color: var(--page-link-color); +} + +.arrow { + color: var(--nav-arrow-color); + -webkit-user-select: none; + -khtml-user-select: none; + -moz-user-select: none; + -ms-user-select: none; + user-select: none; + cursor: pointer; + font-size: 80%; + display: inline-block; + width: 16px; + height: 22px; +} + +.icon { + font-family: var(--font-family-icon); + line-height: normal; + font-weight: bold; + font-size: 12px; + height: 14px; + width: 16px; + display: inline-block; + background-color: var(--icon-background-color); + color: var(--icon-foreground-color); + text-align: center; + border-radius: 4px; + margin-left: 2px; + margin-right: 2px; +} + +.icona { + width: 24px; + height: 22px; + display: inline-block; +} + +.iconfopen { + width: 24px; + height: 18px; + margin-bottom: 4px; + background-image:var(--icon-folder-open-image); + background-repeat: repeat-y; + vertical-align:top; + display: inline-block; +} + +.iconfclosed { + width: 24px; + height: 18px; + margin-bottom: 4px; + background-image:var(--icon-folder-closed-image); + background-repeat: repeat-y; + vertical-align:top; + display: inline-block; +} + +.icondoc { + width: 24px; + height: 18px; + margin-bottom: 4px; + background-image:var(--icon-doc-image); + background-position: 0px -4px; + background-repeat: repeat-y; + vertical-align:top; + display: inline-block; +} + +/* @end */ + +div.dynheader { + margin-top: 8px; + -webkit-touch-callout: none; + -webkit-user-select: none; + -khtml-user-select: none; + -moz-user-select: none; + -ms-user-select: none; + user-select: none; +} + +address { + font-style: normal; + color: var(--footer-foreground-color); +} + +table.doxtable caption { + caption-side: top; +} + +table.doxtable { + border-collapse:collapse; + margin-top: 4px; + margin-bottom: 4px; +} + +table.doxtable td, table.doxtable th { + border: 1px solid var(--table-cell-border-color); + padding: 3px 7px 2px; +} + +table.doxtable th { + background-color: var(--table-header-background-color); + color: var(--table-header-foreground-color); + font-size: 110%; + padding-bottom: 4px; + padding-top: 5px; +} + +table.fieldtable { + margin-bottom: 10px; + border: 1px solid var(--memdef-border-color); + border-spacing: 0px; + border-radius: 4px; + box-shadow: 2px 2px 2px rgba(0, 0, 0, 0.15); +} + +.fieldtable td, .fieldtable th { + padding: 3px 7px 2px; +} + +.fieldtable td.fieldtype, .fieldtable td.fieldname { + white-space: nowrap; + border-right: 1px solid var(--memdef-border-color); + border-bottom: 1px solid var(--memdef-border-color); + vertical-align: top; +} + +.fieldtable td.fieldname { + padding-top: 3px; +} + +.fieldtable td.fielddoc { + border-bottom: 1px solid var(--memdef-border-color); +} + +.fieldtable td.fielddoc p:first-child { + margin-top: 0px; +} + +.fieldtable td.fielddoc p:last-child { + margin-bottom: 2px; +} + +.fieldtable tr:last-child td { + border-bottom: none; +} + +.fieldtable th { + background-image: var(--memdef-title-gradient-image); + background-repeat:repeat-x; + background-color: var(--memdef-title-background-color); + font-size: 90%; + color: var(--memdef-proto-text-color); + padding-bottom: 4px; + padding-top: 5px; + text-align:left; + font-weight: 400; + border-top-left-radius: 4px; + border-top-right-radius: 4px; + border-bottom: 1px solid var(--memdef-border-color); +} + + +.tabsearch { + top: 0px; + left: 10px; + height: 36px; + background-image: var(--nav-gradient-image); + z-index: 101; + overflow: hidden; + font-size: 13px; +} + +.navpath ul +{ + font-size: 11px; + background-image: var(--nav-gradient-image); + background-repeat:repeat-x; + background-position: 0 -5px; + height:30px; + line-height:30px; + color:var(--nav-text-normal-color); + border:solid 1px var(--nav-breadcrumb-border-color); + overflow:hidden; + margin:0px; + padding:0px; +} + +.navpath li +{ + list-style-type:none; + float:left; + padding-left:10px; + padding-right:15px; + background-image:var(--nav-breadcrumb-image); + background-repeat:no-repeat; + background-position:right; + color: var(--nav-foreground-color); +} + +.navpath li.navelem a +{ + height:32px; + display:block; + text-decoration: none; + outline: none; + color: var(--nav-text-normal-color); + font-family: var(--font-family-nav); + text-shadow: var(--nav-text-normal-shadow); + text-decoration: none; +} + +.navpath li.navelem a:hover +{ + color: var(--nav-text-hover-color); + text-shadow: var(--nav-text-hover-shadow); +} + +.navpath li.footer +{ + list-style-type:none; + float:right; + padding-left:10px; + padding-right:15px; + background-image:none; + background-repeat:no-repeat; + background-position:right; + color: var(--footer-foreground-color); + font-size: 8pt; +} + + +div.summary +{ + float: right; + font-size: 8pt; + padding-right: 5px; + width: 50%; + text-align: right; +} + +div.summary a +{ + white-space: nowrap; +} + +table.classindex +{ + margin: 10px; + white-space: nowrap; + margin-left: 3%; + margin-right: 3%; + width: 94%; + border: 0; + border-spacing: 0; + padding: 0; +} + +div.ingroups +{ + font-size: 8pt; + width: 50%; + text-align: left; +} + +div.ingroups a +{ + white-space: nowrap; +} + +div.header +{ + background-image: var(--header-gradient-image); + background-repeat:repeat-x; + background-color: var(--header-background-color); + margin: 0px; + border-bottom: 1px solid var(--header-separator-color); +} + +div.headertitle +{ + padding: 5px 5px 5px 10px; +} + +.PageDocRTL-title div.headertitle { + text-align: right; + direction: rtl; +} + +dl { + padding: 0 0 0 0; +} + +/* dl.note, dl.warning, dl.attention, dl.pre, dl.post, dl.invariant, dl.deprecated, dl.todo, dl.test, dl.bug, dl.examples */ +dl.section { + margin-left: 0px; + padding-left: 0px; +} + +dl.note { + margin-left: -7px; + padding-left: 3px; + border-left: 4px solid; + border-color: #D0C000; +} + +dl.warning, dl.attention { + margin-left: -7px; + padding-left: 3px; + border-left: 4px solid; + border-color: #FF0000; +} + +dl.pre, dl.post, dl.invariant { + margin-left: -7px; + padding-left: 3px; + border-left: 4px solid; + border-color: #00D000; +} + +dl.deprecated { + margin-left: -7px; + padding-left: 3px; + border-left: 4px solid; + border-color: #505050; +} + +dl.todo { + margin-left: -7px; + padding-left: 3px; + border-left: 4px solid; + border-color: #00C0E0; +} + +dl.test { + margin-left: -7px; + padding-left: 3px; + border-left: 4px solid; + border-color: #3030E0; +} + +dl.bug { + margin-left: -7px; + padding-left: 3px; + border-left: 4px solid; + border-color: #C08050; +} + +dl.section dd { + margin-bottom: 6px; +} + + +#projectrow +{ + height: 56px; +} + +#projectlogo +{ + text-align: center; + vertical-align: bottom; + border-collapse: separate; +} + +#projectlogo img +{ + border: 0px none; +} + +#projectalign +{ + vertical-align: middle; + padding-left: 0.5em; +} + +#projectname +{ + font-size: 200%; + font-family: var(--font-family-title); + margin: 0px; + padding: 2px 0px; +} + +#projectbrief +{ + font-size: 90%; + font-family: var(--font-family-title); + margin: 0px; + padding: 0px; +} + +#projectnumber +{ + font-size: 50%; + font-family: 50% var(--font-family-title); + margin: 0px; + padding: 0px; +} + +#titlearea +{ + padding: 0px; + margin: 0px; + width: 100%; + border-bottom: 1px solid var(--title-separator-color); + background-color: var(--title-background-color); +} + +.image +{ + text-align: center; +} + +.dotgraph +{ + text-align: center; +} + +.mscgraph +{ + text-align: center; +} + +.plantumlgraph +{ + text-align: center; +} + +.diagraph +{ + text-align: center; +} + +.caption +{ + font-weight: bold; +} + +dl.citelist { + margin-bottom:50px; +} + +dl.citelist dt { + color:var(--citation-label-color); + float:left; + font-weight:bold; + margin-right:10px; + padding:5px; + text-align:right; + width:52px; +} + +dl.citelist dd { + margin:2px 0 2px 72px; + padding:5px 0; +} + +div.toc { + padding: 14px 25px; + background-color: var(--toc-background-color); + border: 1px solid var(--toc-border-color); + border-radius: 7px 7px 7px 7px; + float: right; + height: auto; + margin: 0 8px 10px 10px; + width: 200px; +} + +div.toc li { + background: var(--toc-down-arrow-image) no-repeat scroll 0 5px transparent; + font: 10px/1.2 var(--font-family-toc); + margin-top: 5px; + padding-left: 10px; + padding-top: 2px; +} + +div.toc h3 { + font: bold 12px/1.2 var(--font-family-toc); + color: var(--toc-header-color); + border-bottom: 0 none; + margin: 0; +} + +div.toc ul { + list-style: none outside none; + border: medium none; + padding: 0px; +} + +div.toc li.level1 { + margin-left: 0px; +} + +div.toc li.level2 { + margin-left: 15px; +} + +div.toc li.level3 { + margin-left: 15px; +} + +div.toc li.level4 { + margin-left: 15px; +} + +span.emoji { + /* font family used at the site: https://unicode.org/emoji/charts/full-emoji-list.html + * font-family: "Noto Color Emoji", "Apple Color Emoji", "Segoe UI Emoji", Times, Symbola, Aegyptus, Code2000, Code2001, Code2002, Musica, serif, LastResort; + */ +} + +span.obfuscator { + display: none; +} + +.inherit_header { + font-weight: bold; + color: var(--inherit-header-color); + cursor: pointer; + -webkit-touch-callout: none; + -webkit-user-select: none; + -khtml-user-select: none; + -moz-user-select: none; + -ms-user-select: none; + user-select: none; +} + +.inherit_header td { + padding: 6px 0px 2px 5px; +} + +.inherit { + display: none; +} + +tr.heading h2 { + margin-top: 12px; + margin-bottom: 4px; +} + +/* tooltip related style info */ + +.ttc { + position: absolute; + display: none; +} + +#powerTip { + cursor: default; + /*white-space: nowrap;*/ + color: var(--tooltip-foreground-color); + background-color: var(--tooltip-background-color); + border: 1px solid var(--tooltip-border-color); + border-radius: 4px 4px 4px 4px; + box-shadow: var(--tooltip-shadow); + display: none; + font-size: smaller; + max-width: 80%; + opacity: 0.9; + padding: 1ex 1em 1em; + position: absolute; + z-index: 2147483647; +} + +#powerTip div.ttdoc { + color: var(--tooltip-doc-color); + font-style: italic; +} + +#powerTip div.ttname a { + font-weight: bold; +} + +#powerTip a { + color: var(--tooltip-link-color); +} + +#powerTip div.ttname { + font-weight: bold; +} + +#powerTip div.ttdeci { + color: var(--tooltip-declaration-color); +} + +#powerTip div { + margin: 0px; + padding: 0px; + font-size: 12px; + font-family: var(--font-family-tooltip); + line-height: 16px; +} + +#powerTip:before, #powerTip:after { + content: ""; + position: absolute; + margin: 0px; +} + +#powerTip.n:after, #powerTip.n:before, +#powerTip.s:after, #powerTip.s:before, +#powerTip.w:after, #powerTip.w:before, +#powerTip.e:after, #powerTip.e:before, +#powerTip.ne:after, #powerTip.ne:before, +#powerTip.se:after, #powerTip.se:before, +#powerTip.nw:after, #powerTip.nw:before, +#powerTip.sw:after, #powerTip.sw:before { + border: solid transparent; + content: " "; + height: 0; + width: 0; + position: absolute; +} + +#powerTip.n:after, #powerTip.s:after, +#powerTip.w:after, #powerTip.e:after, +#powerTip.nw:after, #powerTip.ne:after, +#powerTip.sw:after, #powerTip.se:after { + border-color: rgba(255, 255, 255, 0); +} + +#powerTip.n:before, #powerTip.s:before, +#powerTip.w:before, #powerTip.e:before, +#powerTip.nw:before, #powerTip.ne:before, +#powerTip.sw:before, #powerTip.se:before { + border-color: rgba(128, 128, 128, 0); +} + +#powerTip.n:after, #powerTip.n:before, +#powerTip.ne:after, #powerTip.ne:before, +#powerTip.nw:after, #powerTip.nw:before { + top: 100%; +} + +#powerTip.n:after, #powerTip.ne:after, #powerTip.nw:after { + border-top-color: var(--tooltip-background-color); + border-width: 10px; + margin: 0px -10px; +} +#powerTip.n:before, #powerTip.ne:before, #powerTip.nw:before { + border-top-color: var(--tooltip-border-color); + border-width: 11px; + margin: 0px -11px; +} +#powerTip.n:after, #powerTip.n:before { + left: 50%; +} + +#powerTip.nw:after, #powerTip.nw:before { + right: 14px; +} + +#powerTip.ne:after, #powerTip.ne:before { + left: 14px; +} + +#powerTip.s:after, #powerTip.s:before, +#powerTip.se:after, #powerTip.se:before, +#powerTip.sw:after, #powerTip.sw:before { + bottom: 100%; +} + +#powerTip.s:after, #powerTip.se:after, #powerTip.sw:after { + border-bottom-color: var(--tooltip-background-color); + border-width: 10px; + margin: 0px -10px; +} + +#powerTip.s:before, #powerTip.se:before, #powerTip.sw:before { + border-bottom-color: var(--tooltip-border-color); + border-width: 11px; + margin: 0px -11px; +} + +#powerTip.s:after, #powerTip.s:before { + left: 50%; +} + +#powerTip.sw:after, #powerTip.sw:before { + right: 14px; +} + +#powerTip.se:after, #powerTip.se:before { + left: 14px; +} + +#powerTip.e:after, #powerTip.e:before { + left: 100%; +} +#powerTip.e:after { + border-left-color: var(--tooltip-border-color); + border-width: 10px; + top: 50%; + margin-top: -10px; +} +#powerTip.e:before { + border-left-color: var(--tooltip-border-color); + border-width: 11px; + top: 50%; + margin-top: -11px; +} + +#powerTip.w:after, #powerTip.w:before { + right: 100%; +} +#powerTip.w:after { + border-right-color: var(--tooltip-border-color); + border-width: 10px; + top: 50%; + margin-top: -10px; +} +#powerTip.w:before { + border-right-color: var(--tooltip-border-color); + border-width: 11px; + top: 50%; + margin-top: -11px; +} + +@media print +{ + #top { display: none; } + #side-nav { display: none; } + #nav-path { display: none; } + body { overflow:visible; } + h1, h2, h3, h4, h5, h6 { page-break-after: avoid; } + .summary { display: none; } + .memitem { page-break-inside: avoid; } + #doc-content + { + margin-left:0 !important; + height:auto !important; + width:auto !important; + overflow:inherit; + display:inline; + } +} + +/* @group Markdown */ + +table.markdownTable { + border-collapse:collapse; + margin-top: 4px; + margin-bottom: 4px; +} + +table.markdownTable td, table.markdownTable th { + border: 1px solid var(--table-cell-border-color); + padding: 3px 7px 2px; +} + +table.markdownTable tr { +} + +th.markdownTableHeadLeft, th.markdownTableHeadRight, th.markdownTableHeadCenter, th.markdownTableHeadNone { + background-color: var(--table-header-background-color); + color: var(--table-header-foreground-color); + font-size: 110%; + padding-bottom: 4px; + padding-top: 5px; +} + +th.markdownTableHeadLeft, td.markdownTableBodyLeft { + text-align: left +} + +th.markdownTableHeadRight, td.markdownTableBodyRight { + text-align: right +} + +th.markdownTableHeadCenter, td.markdownTableBodyCenter { + text-align: center +} + +tt, code, kbd, samp +{ + display: inline-block; +} +/* @end */ + +u { + text-decoration: underline; +} + +details>summary { + list-style-type: none; +} + +details > summary::-webkit-details-marker { + display: none; +} + +details>summary::before { + content: "\25ba"; + padding-right:4px; + font-size: 80%; +} + +details[open]>summary::before { + content: "\25bc"; + padding-right:4px; + font-size: 80%; +} + +body { + scrollbar-color: var(--scrollbar-thumb-color) var(--scrollbar-background-color); +} + +::-webkit-scrollbar { + background-color: var(--scrollbar-background-color); + height: 12px; + width: 12px; +} +::-webkit-scrollbar-thumb { + border-radius: 6px; + box-shadow: inset 0 0 12px 12px var(--scrollbar-thumb-color); + border: solid 2px transparent; +} +::-webkit-scrollbar-corner { + background-color: var(--scrollbar-background-color); +} + diff --git a/doc/api/doxygen.svg b/doc/api/doxygen.svg new file mode 100644 index 00000000..363aa45f --- /dev/null +++ b/doc/api/doxygen.svg @@ -0,0 +1,28 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/api/files.html b/doc/api/files.html new file mode 100644 index 00000000..ee2f316e --- /dev/null +++ b/doc/api/files.html @@ -0,0 +1,80 @@ + + + + + + + +liblzma (XZ Utils): File List + + + + + + +
+
+ + + + + + + +
+
liblzma (XZ Utils) 5.6.0 +
+
+
+ + + + +
+
+
File List
+
+
+
Here is a list of all documented files with brief descriptions:
+
[detail level 12]
+ + + + + + + + + + + + + + + + +
 ▼ lzma
 base.hData types and functions used in many places in liblzma API
 bcj.hBranch/Call/Jump conversion filters
 block.h.xz Block handling
 check.hIntegrity checks
 container.hFile formats
 delta.hDelta filter
 filter.hCommon filter related types and functions
 hardware.hHardware information
 index.hHandling of .xz Index and related information
 index_hash.hValidate Index by using a hash function
 lzma12.hLZMA1 and LZMA2 filters
 stream_flags.h.xz Stream Header and Stream Footer encoder and decoder
 version.hVersion number
 vli.hVariable-length integer handling
 lzma.hThe public API of liblzma data compression library
+
+
+
+

+ XZ logo © 2023 by Jia Tan is licensed under + + CC BY-SA 4.0 + +

+ + diff --git a/doc/api/filter_8h.html b/doc/api/filter_8h.html new file mode 100644 index 00000000..47ec448b --- /dev/null +++ b/doc/api/filter_8h.html @@ -0,0 +1,1508 @@ + + + + + + + +liblzma (XZ Utils): lzma/filter.h File Reference + + + + + + +
+
+ + + + + + + +
+
liblzma (XZ Utils) 5.6.0 +
+
+
+ + + + + +
+
+
+Data Structures | +Macros | +Functions
+
filter.h File Reference
+
+
+ +

Common filter related types and functions. +More...

+ + + + + +

+Data Structures

struct  lzma_filter
 Filter options. More...
 
+ + + + + + + + + + + + + + + + + + + + + + +

+Macros

#define LZMA_FILTERS_MAX   4
 Maximum number of filters in a chain.
 
#define LZMA_STR_ALL_FILTERS   UINT32_C(0x01)
 Allow or show all filters.
 
#define LZMA_STR_NO_VALIDATION   UINT32_C(0x02)
 Do not validate the filter chain in lzma_str_to_filters()
 
#define LZMA_STR_ENCODER   UINT32_C(0x10)
 Stringify encoder options.
 
#define LZMA_STR_DECODER   UINT32_C(0x20)
 Stringify decoder options.
 
#define LZMA_STR_GETOPT_LONG   UINT32_C(0x40)
 Produce xz-compatible getopt_long() syntax.
 
#define LZMA_STR_NO_SPACES   UINT32_C(0x80)
 Use two dashes "--" instead of a space to separate filters.
 
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+Functions

lzma_bool lzma_filter_encoder_is_supported (lzma_vli id) lzma_nothrow lzma_attr_const
 Test if the given Filter ID is supported for encoding.
 
lzma_bool lzma_filter_decoder_is_supported (lzma_vli id) lzma_nothrow lzma_attr_const
 Test if the given Filter ID is supported for decoding.
 
lzma_ret lzma_filters_copy (const lzma_filter *src, lzma_filter *dest, const lzma_allocator *allocator) lzma_nothrow lzma_attr_warn_unused_result
 Copy the filters array.
 
void lzma_filters_free (lzma_filter *filters, const lzma_allocator *allocator) lzma_nothrow
 Free the options in the array of lzma_filter structures.
 
uint64_t lzma_raw_encoder_memusage (const lzma_filter *filters) lzma_nothrow lzma_attr_pure
 Calculate approximate memory requirements for raw encoder.
 
uint64_t lzma_raw_decoder_memusage (const lzma_filter *filters) lzma_nothrow lzma_attr_pure
 Calculate approximate memory requirements for raw decoder.
 
lzma_ret lzma_raw_encoder (lzma_stream *strm, const lzma_filter *filters) lzma_nothrow lzma_attr_warn_unused_result
 Initialize raw encoder.
 
lzma_ret lzma_raw_decoder (lzma_stream *strm, const lzma_filter *filters) lzma_nothrow lzma_attr_warn_unused_result
 Initialize raw decoder.
 
lzma_ret lzma_filters_update (lzma_stream *strm, const lzma_filter *filters) lzma_nothrow
 Update the filter chain in the encoder.
 
lzma_ret lzma_raw_buffer_encode (const lzma_filter *filters, const lzma_allocator *allocator, const uint8_t *in, size_t in_size, uint8_t *out, size_t *out_pos, size_t out_size) lzma_nothrow
 Single-call raw encoder.
 
lzma_ret lzma_raw_buffer_decode (const lzma_filter *filters, const lzma_allocator *allocator, const uint8_t *in, size_t *in_pos, size_t in_size, uint8_t *out, size_t *out_pos, size_t out_size) lzma_nothrow
 Single-call raw decoder.
 
lzma_ret lzma_properties_size (uint32_t *size, const lzma_filter *filter) lzma_nothrow
 Get the size of the Filter Properties field.
 
lzma_ret lzma_properties_encode (const lzma_filter *filter, uint8_t *props) lzma_nothrow
 Encode the Filter Properties field.
 
lzma_ret lzma_properties_decode (lzma_filter *filter, const lzma_allocator *allocator, const uint8_t *props, size_t props_size) lzma_nothrow
 Decode the Filter Properties field.
 
lzma_ret lzma_filter_flags_size (uint32_t *size, const lzma_filter *filter) lzma_nothrow lzma_attr_warn_unused_result
 Calculate encoded size of a Filter Flags field.
 
lzma_ret lzma_filter_flags_encode (const lzma_filter *filter, uint8_t *out, size_t *out_pos, size_t out_size) lzma_nothrow lzma_attr_warn_unused_result
 Encode Filter Flags into given buffer.
 
lzma_ret lzma_filter_flags_decode (lzma_filter *filter, const lzma_allocator *allocator, const uint8_t *in, size_t *in_pos, size_t in_size) lzma_nothrow lzma_attr_warn_unused_result
 Decode Filter Flags from given buffer.
 
const char * lzma_str_to_filters (const char *str, int *error_pos, lzma_filter *filters, uint32_t flags, const lzma_allocator *allocator) lzma_nothrow lzma_attr_warn_unused_result
 Convert a string to a filter chain.
 
lzma_ret lzma_str_from_filters (char **str, const lzma_filter *filters, uint32_t flags, const lzma_allocator *allocator) lzma_nothrow lzma_attr_warn_unused_result
 Convert a filter chain to a string.
 
lzma_ret lzma_str_list_filters (char **str, lzma_vli filter_id, uint32_t flags, const lzma_allocator *allocator) lzma_nothrow lzma_attr_warn_unused_result
 List available filters and/or their options (for help message)
 
+

Detailed Description

+

Common filter related types and functions.

+
Note
Never include this file directly. Use <lzma.h> instead.
+

Macro Definition Documentation

+ +

◆ LZMA_FILTERS_MAX

+ +
+
+ + + + +
#define LZMA_FILTERS_MAX   4
+
+ +

Maximum number of filters in a chain.

+

A filter chain can have 1-4 filters, of which three are allowed to change the size of the data. Usually only one or two filters are needed.

+ +
+
+ +

◆ LZMA_STR_ALL_FILTERS

+ +
+
+ + + + +
#define LZMA_STR_ALL_FILTERS   UINT32_C(0x01)
+
+ +

Allow or show all filters.

+

By default only the filters supported in the .xz format are accept by lzma_str_to_filters() or shown by lzma_str_list_filters().

+ +
+
+ +

◆ LZMA_STR_NO_VALIDATION

+ +
+
+ + + + +
#define LZMA_STR_NO_VALIDATION   UINT32_C(0x02)
+
+ +

Do not validate the filter chain in lzma_str_to_filters()

+

By default lzma_str_to_filters() can return an error if the filter chain as a whole isn't usable in the .xz format or in the raw encoder or decoder. With this flag, this validation is skipped. This flag doesn't affect the handling of the individual filter options. To allow non-.xz filters also LZMA_STR_ALL_FILTERS is needed.

+ +
+
+ +

◆ LZMA_STR_ENCODER

+ +
+
+ + + + +
#define LZMA_STR_ENCODER   UINT32_C(0x10)
+
+ +

Stringify encoder options.

+

Show the filter-specific options that the encoder will use. This may be useful for verbose diagnostic messages.

+

Note that if options were decoded from .xz headers then the encoder options may be undefined. This flag shouldn't be used in such a situation.

+ +
+
+ +

◆ LZMA_STR_DECODER

+ +
+
+ + + + +
#define LZMA_STR_DECODER   UINT32_C(0x20)
+
+ +

Stringify decoder options.

+

Show the filter-specific options that the decoder will use. This may be useful for showing what filter options were decoded from file headers.

+ +
+
+ +

◆ LZMA_STR_GETOPT_LONG

+ +
+
+ + + + +
#define LZMA_STR_GETOPT_LONG   UINT32_C(0x40)
+
+ +

Produce xz-compatible getopt_long() syntax.

+

That is, "delta:dist=2 lzma2:dict=4MiB,pb=1,lp=1" becomes "--delta=dist=2 --lzma2=dict=4MiB,pb=1,lp=1".

+

This syntax is compatible with xz 5.0.0 as long as the filters and their options are supported too.

+ +
+
+ +

◆ LZMA_STR_NO_SPACES

+ +
+
+ + + + +
#define LZMA_STR_NO_SPACES   UINT32_C(0x80)
+
+ +

Use two dashes "--" instead of a space to separate filters.

+

That is, "delta:dist=2 lzma2:pb=1,lp=1" becomes "delta:dist=2--lzma2:pb=1,lp=1". This looks slightly odd but this kind of strings should be usable on the command line without quoting. However, it is possible that future versions with new filter options might produce strings that require shell quoting anyway as the exact set of possible characters isn't frozen for now.

+

It is guaranteed that the single quote (') will never be used in filter chain strings (even if LZMA_STR_NO_SPACES isn't used).

+ +
+
+

Function Documentation

+ +

◆ lzma_filter_encoder_is_supported()

+ +
+
+ + + + + +
+ + + + + + + + +
lzma_bool lzma_filter_encoder_is_supported (lzma_vli id) const
+ 		+extern
+
+ +

Test if the given Filter ID is supported for encoding.

+
Parameters
+ + +
idFilter ID
+
+
+
Returns
lzma_bool:
    +
  • true if the Filter ID is supported for encoding by this liblzma build.
    • +
  • false otherwise.
    • +
+
+ +
+
+ +

◆ lzma_filter_decoder_is_supported()

+ +
+
+ + + + + +
+ + + + + + + + +
lzma_bool lzma_filter_decoder_is_supported (lzma_vli id) const
+ 		+extern
+
+ +

Test if the given Filter ID is supported for decoding.

+
Parameters
+ + +
idFilter ID
+
+
+
Returns
lzma_bool:
    +
  • true if the Filter ID is supported for decoding by this liblzma build.
    • +
  • false otherwise.
    • +
+
+ +
+
+ +

◆ lzma_filters_copy()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_filters_copy (const lzma_filter * src,
lzma_filter * dest,
const lzma_allocator * allocator 
)
+ 		+extern
+
+ +

Copy the filters array.

+

Copy the Filter IDs and filter-specific options from src to dest. Up to LZMA_FILTERS_MAX filters are copied, plus the terminating .id == LZMA_VLI_UNKNOWN. Thus, dest should have at least LZMA_FILTERS_MAX + 1 elements space unless the caller knows that src is smaller than that.

+

Unless the filter-specific options is NULL, the Filter ID has to be supported by liblzma, because liblzma needs to know the size of every filter-specific options structure. The filter-specific options are not validated. If options is NULL, any unsupported Filter IDs are copied without returning an error.

+

Old filter-specific options in dest are not freed, so dest doesn't need to be initialized by the caller in any way.

+

If an error occurs, memory possibly already allocated by this function is always freed. liblzma versions older than 5.2.7 may modify the dest array and leave its contents in an undefined state if an error occurs. liblzma 5.2.7 and newer only modify the dest array when returning LZMA_OK.

+
Parameters
+ + + + +
srcArray of filters terminated with .id == LZMA_VLI_UNKNOWN.
[out]destDestination filter array
allocatorlzma_allocator for custom allocator functions. Set to NULL to use malloc() and free().
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK
    • +
  • LZMA_MEM_ERROR
    • +
  • LZMA_OPTIONS_ERROR: Unsupported Filter ID and its options is not NULL.
    • +
  • LZMA_PROG_ERROR: src or dest is NULL.
    • +
+
+ +
+
+ +

◆ lzma_filters_free()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + +
void lzma_filters_free (lzma_filter * filters,
const lzma_allocator * allocator 
)
+ 		+extern
+
+ +

Free the options in the array of lzma_filter structures.

+

This frees the filter chain options. The filters array itself is not freed.

+

The filters array must have at most LZMA_FILTERS_MAX + 1 elements including the terminating element which must have .id = LZMA_VLI_UNKNOWN. For all elements before the terminating element:

    +
  • options will be freed using the given lzma_allocator or, if allocator is NULL, using free().
    • +
  • options will be set to NULL.
    • +
  • id will be set to LZMA_VLI_UNKNOWN.
    • +
+

If filters is NULL, this does nothing. Again, this never frees the filters array itself.

+
Parameters
+ + + +
filtersArray of filters terminated with .id == LZMA_VLI_UNKNOWN.
allocatorlzma_allocator for custom allocator functions. Set to NULL to use malloc() and free().
+
+
+ +
+
+ +

◆ lzma_raw_encoder_memusage()

+ +
+
+ + + + + +
+ + + + + + + + +
uint64_t lzma_raw_encoder_memusage (const lzma_filter * filters)
+ 		+extern
+
+ +

Calculate approximate memory requirements for raw encoder.

+

This function can be used to calculate the memory requirements for Block and Stream encoders too because Block and Stream encoders don't need significantly more memory than raw encoder.

+
Parameters
+ + +
filtersArray of filters terminated with .id == LZMA_VLI_UNKNOWN.
+
+
+
Returns
Number of bytes of memory required for the given filter chain when encoding or UINT64_MAX on error.
+ +
+
+ +

◆ lzma_raw_decoder_memusage()

+ +
+
+ + + + + +
+ + + + + + + + +
uint64_t lzma_raw_decoder_memusage (const lzma_filter * filters)
+ 		+extern
+
+ +

Calculate approximate memory requirements for raw decoder.

+

This function can be used to calculate the memory requirements for Block and Stream decoders too because Block and Stream decoders don't need significantly more memory than raw decoder.

+
Parameters
+ + +
filtersArray of filters terminated with .id == LZMA_VLI_UNKNOWN.
+
+
+
Returns
Number of bytes of memory required for the given filter chain when decoding or UINT64_MAX on error.
+ +
+
+ +

◆ lzma_raw_encoder()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + +
lzma_ret lzma_raw_encoder (lzma_stream * strm,
const lzma_filter * filters 
)
+ 		+extern
+
+ +

Initialize raw encoder.

+

This function may be useful when implementing custom file formats.

+

The 'action' with lzma_code() can be LZMA_RUN, LZMA_SYNC_FLUSH (if the filter chain supports it), or LZMA_FINISH.

+
Parameters
+ + + +
strmPointer to lzma_stream that is at least initialized with LZMA_STREAM_INIT.
filtersArray of filters terminated with .id == LZMA_VLI_UNKNOWN.
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK
    • +
  • LZMA_MEM_ERROR
    • +
  • LZMA_OPTIONS_ERROR
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+ +

◆ lzma_raw_decoder()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + +
lzma_ret lzma_raw_decoder (lzma_stream * strm,
const lzma_filter * filters 
)
+ 		+extern
+
+ +

Initialize raw decoder.

+

The initialization of raw decoder goes similarly to raw encoder.

+

The 'action' with lzma_code() can be LZMA_RUN or LZMA_FINISH. Using LZMA_FINISH is not required, it is supported just for convenience.

+
Parameters
+ + + +
strmPointer to lzma_stream that is at least initialized with LZMA_STREAM_INIT.
filtersArray of filters terminated with .id == LZMA_VLI_UNKNOWN.
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK
    • +
  • LZMA_MEM_ERROR
    • +
  • LZMA_OPTIONS_ERROR
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+ +

◆ lzma_filters_update()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + +
lzma_ret lzma_filters_update (lzma_stream * strm,
const lzma_filter * filters 
)
+ 		+extern
+
+ +

Update the filter chain in the encoder.

+

This function may be called after lzma_code() has returned LZMA_STREAM_END when LZMA_FULL_BARRIER, LZMA_FULL_FLUSH, or LZMA_SYNC_FLUSH was used:

+
    +
  • After LZMA_FULL_BARRIER or LZMA_FULL_FLUSH: Single-threaded .xz Stream encoder (lzma_stream_encoder()) and (since liblzma 5.4.0) multi-threaded Stream encoder (lzma_stream_encoder_mt()) allow setting a new filter chain to be used for the next Block(s).
    • +
  • After LZMA_SYNC_FLUSH: Raw encoder (lzma_raw_encoder()), Block encoder (lzma_block_encoder()), and single-threaded .xz Stream encoder (lzma_stream_encoder()) allow changing certain filter-specific options in the middle of encoding. The actual filters in the chain (Filter IDs) must not be changed! Currently only the lc, lp, and pb options of LZMA2 (not LZMA1) can be changed this way.
    • +
  • In the future some filters might allow changing some of their options without any barrier or flushing but currently such filters don't exist.
    • +
+

This function may also be called when no data has been compressed yet although this is rarely useful. In that case, this function will behave as if LZMA_FULL_FLUSH (Stream encoders) or LZMA_SYNC_FLUSH (Raw or Block encoder) had been used right before calling this function.

+
Parameters
+ + + +
strmPointer to lzma_stream that is at least initialized with LZMA_STREAM_INIT.
filtersArray of filters terminated with .id == LZMA_VLI_UNKNOWN.
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK
    • +
  • LZMA_MEM_ERROR
    • +
  • LZMA_MEMLIMIT_ERROR
    • +
  • LZMA_OPTIONS_ERROR
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+ +

◆ lzma_raw_buffer_encode()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_raw_buffer_encode (const lzma_filter * filters,
const lzma_allocator * allocator,
const uint8_t * in,
size_t in_size,
uint8_t * out,
size_t * out_pos,
size_t out_size 
)
+ 		+extern
+
+ +

Single-call raw encoder.

+
Note
There is no function to calculate how big output buffer would surely be big enough. (lzma_stream_buffer_bound() works only for lzma_stream_buffer_encode(); raw encoder won't necessarily meet that bound.)
+
Parameters
+ + + + + + + + +
filtersArray of filters terminated with .id == LZMA_VLI_UNKNOWN.
allocatorlzma_allocator for custom allocator functions. Set to NULL to use malloc() and free().
inBeginning of the input buffer
in_sizeSize of the input buffer
[out]outBeginning of the output buffer
[out]out_posThe next byte will be written to out[*out_pos]. *out_pos is updated only if encoding succeeds.
out_sizeSize of the out buffer; the first byte into which no data is written to is out[out_size].
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: Encoding was successful.
    • +
  • LZMA_BUF_ERROR: Not enough output buffer space.
    • +
  • LZMA_OPTIONS_ERROR
    • +
  • LZMA_MEM_ERROR
    • +
  • LZMA_DATA_ERROR
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+ +

◆ lzma_raw_buffer_decode()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_raw_buffer_decode (const lzma_filter * filters,
const lzma_allocator * allocator,
const uint8_t * in,
size_t * in_pos,
size_t in_size,
uint8_t * out,
size_t * out_pos,
size_t out_size 
)
+ 		+extern
+
+ +

Single-call raw decoder.

+
Parameters
+ + + + + + + + + +
filtersArray of filters terminated with .id == LZMA_VLI_UNKNOWN.
allocatorlzma_allocator for custom allocator functions. Set to NULL to use malloc() and free().
inBeginning of the input buffer
in_posThe next byte will be read from in[*in_pos]. *in_pos is updated only if decoding succeeds.
in_sizeSize of the input buffer; the first byte that won't be read is in[in_size].
[out]outBeginning of the output buffer
[out]out_posThe next byte will be written to out[*out_pos]. *out_pos is updated only if encoding succeeds.
out_sizeSize of the out buffer; the first byte into which no data is written to is out[out_size].
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: Decoding was successful.
    • +
  • LZMA_BUF_ERROR: Not enough output buffer space.
    • +
  • LZMA_OPTIONS_ERROR
    • +
  • LZMA_MEM_ERROR
    • +
  • LZMA_DATA_ERROR
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+ +

◆ lzma_properties_size()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + +
lzma_ret lzma_properties_size (uint32_t * size,
const lzma_filter * filter 
)
+ 		+extern
+
+ +

Get the size of the Filter Properties field.

+

This function may be useful when implementing custom file formats using the raw encoder and decoder.

+
Note
This function validates the Filter ID, but does not necessarily validate the options. Thus, it is possible that this returns LZMA_OK while the following call to lzma_properties_encode() returns LZMA_OPTIONS_ERROR.
+
Parameters
+ + + +
[out]sizePointer to uint32_t to hold the size of the properties
filterFilter ID and options (the size of the properties may vary depending on the options)
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK
    • +
  • LZMA_OPTIONS_ERROR
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+ +

◆ lzma_properties_encode()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + +
lzma_ret lzma_properties_encode (const lzma_filter * filter,
uint8_t * props 
)
+ 		+extern
+
+ +

Encode the Filter Properties field.

+
Note
Even this function won't validate more options than actually necessary. Thus, it is possible that encoding the properties succeeds but using the same options to initialize the encoder will fail.
+
+If lzma_properties_size() indicated that the size of the Filter Properties field is zero, calling lzma_properties_encode() is not required, but it won't do any harm either.
+
Parameters
+ + + +
filterFilter ID and options
[out]propsBuffer to hold the encoded options. The size of the buffer must have been already determined with lzma_properties_size().
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+ +

◆ lzma_properties_decode()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_properties_decode (lzma_filter * filter,
const lzma_allocator * allocator,
const uint8_t * props,
size_t props_size 
)
+ 		+extern
+
+ +

Decode the Filter Properties field.

+
Parameters
+ + + + + +
filterfilter->id must have been set to the correct Filter ID. filter->options doesn't need to be initialized (it's not freed by this function). The decoded options will be stored in filter->options; it's application's responsibility to free it when appropriate. filter->options is set to NULL if there are no properties or if an error occurs.
allocatorlzma_allocator for custom allocator functions. Set to NULL to use malloc() and free(). and in case of an error, also free().
propsInput buffer containing the properties.
props_sizeSize of the properties. This must be the exact size; giving too much or too little input will return LZMA_OPTIONS_ERROR.
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK
    • +
  • LZMA_OPTIONS_ERROR
    • +
  • LZMA_MEM_ERROR
    • +
+
+ +
+
+ +

◆ lzma_filter_flags_size()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + +
lzma_ret lzma_filter_flags_size (uint32_t * size,
const lzma_filter * filter 
)
+ 		+extern
+
+ +

Calculate encoded size of a Filter Flags field.

+

Knowing the size of Filter Flags is useful to know when allocating memory to hold the encoded Filter Flags.

+
Note
If you need to calculate size of List of Filter Flags, you need to loop over every lzma_filter entry.
+
Parameters
+ + + +
[out]sizePointer to integer to hold the calculated size
filterFilter ID and associated options whose encoded size is to be calculated
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: *size set successfully. Note that this doesn't guarantee that filter->options is valid, thus lzma_filter_flags_encode() may still fail.
    • +
  • LZMA_OPTIONS_ERROR: Unknown Filter ID or unsupported options.
    • +
  • LZMA_PROG_ERROR: Invalid options
    • +
+
+ +
+
+ +

◆ lzma_filter_flags_encode()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_filter_flags_encode (const lzma_filter * filter,
uint8_t * out,
size_t * out_pos,
size_t out_size 
)
+ 		+extern
+
+ +

Encode Filter Flags into given buffer.

+

In contrast to some functions, this doesn't allocate the needed buffer. This is due to how this function is used internally by liblzma.

+
Parameters
+ + + + + +
filterFilter ID and options to be encoded
[out]outBeginning of the output buffer
[out]out_posout[*out_pos] is the next write position. This is updated by the encoder.
out_sizeout[out_size] is the first byte to not write.
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: Encoding was successful.
    • +
  • LZMA_OPTIONS_ERROR: Invalid or unsupported options.
    • +
  • LZMA_PROG_ERROR: Invalid options or not enough output buffer space (you should have checked it with lzma_filter_flags_size()).
    • +
+
+ +
+
+ +

◆ lzma_filter_flags_decode()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_filter_flags_decode (lzma_filter * filter,
const lzma_allocator * allocator,
const uint8_t * in,
size_t * in_pos,
size_t in_size 
)
+ 		+extern
+
+ +

Decode Filter Flags from given buffer.

+

The decoded result is stored into *filter. The old value of filter->options is not free()d. If anything other than LZMA_OK is returned, filter->options is set to NULL.

+
Parameters
+ + + + + + +
[out]filterDestination filter. The decoded Filter ID will be stored in filter->id. If options are needed they will be allocated and the pointer will be stored in filter->options.
allocatorlzma_allocator for custom allocator functions. Set to NULL to use malloc() and free().
inBeginning of the input buffer
[out]in_posThe next byte will be read from in[*in_pos]. *in_pos is updated only if decoding succeeds.
in_sizeSize of the input buffer; the first byte that won't be read is in[in_size].
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK
    • +
  • LZMA_OPTIONS_ERROR
    • +
  • LZMA_MEM_ERROR
    • +
  • LZMA_DATA_ERROR
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+ +

◆ lzma_str_to_filters()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
const char * lzma_str_to_filters (const char * str,
int * error_pos,
lzma_filter * filters,
uint32_t flags,
const lzma_allocator * allocator 
)
+ 		+extern
+
+ +

Convert a string to a filter chain.

+

This tries to make it easier to write applications that allow users to set custom compression options. This only handles the filter configuration (including presets) but not the number of threads, block size, check type, or memory limits.

+

The input string can be either a preset or a filter chain. Presets begin with a digit 0-9 and may be followed by zero or more flags which are lower-case letters. Currently only "e" is supported, matching LZMA_PRESET_EXTREME. For partial xz command line syntax compatibility, a preset string may start with a single dash "-".

+

A filter chain consists of one or more "filtername:opt1=value1,opt2=value2" strings separated by one or more spaces. Leading and trailing spaces are ignored. All names and values must be lower-case. Extra commas in the option list are ignored. The order of filters is significant: when encoding, the uncompressed input data goes to the leftmost filter first. Normally "lzma2" is the last filter in the chain.

+

If one wishes to avoid spaces, for example, to avoid shell quoting, it is possible to use two dashes "--" instead of spaces to separate the filters.

+

For xz command line compatibility, each filter may be prefixed with two dashes "--" and the colon ":" separating the filter name from the options may be replaced with an equals sign "=".

+

By default, only filters that can be used in the .xz format are accepted. To allow all filters (LZMA1) use the flag LZMA_STR_ALL_FILTERS.

+

By default, very basic validation is done for the filter chain as a whole, for example, that LZMA2 is only used as the last filter in the chain. The validation isn't perfect though and it's possible that this function succeeds but using the filter chain for encoding or decoding will still result in LZMA_OPTIONS_ERROR. To disable this validation, use the flag LZMA_STR_NO_VALIDATION.

+

The available filter names and their options are available via lzma_str_list_filters(). See the xz man page for the description of filter names and options.

+

For command line applications, below is an example how an error message can be displayed. Note the use of an empty string for the field width. If "^" was used there it would create an off-by-one error except at the very beginning of the line.

+
const char *str = ...; // From user
+
lzma_filter filters[LZMA_FILTERS_MAX + 1];
+
int pos;
+
const char *msg = lzma_str_to_filters(str, &pos, filters, 0, NULL);
+
if (msg != NULL) {
+
printf("%s: Error in XZ compression options:\n", argv[0]);
+
printf("%s: %s\n", argv[0], str);
+
printf("%s: %*s^\n", argv[0], errpos, "");
+
printf("%s: %s\n", argv[0], msg);
+
}
+
Parameters
+ + + + + + +
strUser-supplied string describing a preset or a filter chain. If a default value is needed and you don't know what would be good, use "6" since that is the default preset in xz too.
[out]error_posIf this isn't NULL, this value will be set on both success and on all errors. This tells the location of the error in the string. This is an int to make it straightforward to use this as printf() field width. The value is guaranteed to be in the range [0, INT_MAX] even if strlen(str) somehow was greater than INT_MAX.
[out]filtersAn array of lzma_filter structures. There must be LZMA_FILTERS_MAX + 1 (that is, five) elements in the array. The old contents are ignored so it doesn't need to be initialized. This array is modified only if this function returns NULL. Once the allocated filter options are no longer needed, lzma_filters_free() can be used to free the options (it doesn't free the filters array itself).
flagsBitwise-or of zero or more of the flags LZMA_STR_ALL_FILTERS and LZMA_STR_NO_VALIDATION.
allocatorlzma_allocator for custom allocator functions. Set to NULL to use malloc() and free().
+
+
+
Returns
On success, NULL is returned. On error, a statically-allocated error message is returned which together with the error_pos should give some idea what is wrong.
+ +
+
+ +

◆ lzma_str_from_filters()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_str_from_filters (char ** str,
const lzma_filter * filters,
uint32_t flags,
const lzma_allocator * allocator 
)
+ 		+extern
+
+ +

Convert a filter chain to a string.

+

Use cases:

+
    +
  • Verbose output showing the full encoder options to the user (use LZMA_STR_ENCODER in flags)
    • +
  • Showing the filters and options that are required to decode a file (use LZMA_STR_DECODER in flags)
    • +
  • Showing the filter names without any options in informational messages where the technical details aren't important (no flags). In this case the .options in the filters array are ignored and may be NULL even if a filter has a mandatory options structure.
    • +
+

Note that even if the filter chain was specified using a preset, the resulting filter chain isn't reversed to a preset. So if you specify "6" to lzma_str_to_filters() then lzma_str_from_filters() will produce a string containing "lzma2".

+
Parameters
+ + + + + +
[out]strOn success *str will be set to point to an allocated string describing the given filter chain. Old value is ignored. On error *str is always set to NULL.
filtersArray of filters terminated with .id == LZMA_VLI_UNKNOWN.
flagsBitwise-or of zero or more of the flags LZMA_STR_ENCODER, LZMA_STR_DECODER, LZMA_STR_GETOPT_LONG, and LZMA_STR_NO_SPACES.
allocatorlzma_allocator for custom allocator functions. Set to NULL to use malloc() and free().
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK
    • +
  • LZMA_OPTIONS_ERROR: Empty filter chain (filters[0].id == LZMA_VLI_UNKNOWN) or the filter chain includes a Filter ID that is not supported by this function.
    • +
  • LZMA_MEM_ERROR
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+ +

◆ lzma_str_list_filters()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_str_list_filters (char ** str,
lzma_vli filter_id,
uint32_t flags,
const lzma_allocator * allocator 
)
+ 		+extern
+
+ +

List available filters and/or their options (for help message)

+

If a filter_id is given then only one line is created which contains the filter name. If LZMA_STR_ENCODER or LZMA_STR_DECODER is used then the options read by the encoder or decoder are printed on the same line.

+

If filter_id is LZMA_VLI_UNKNOWN then all supported .xz-compatible filters are listed:

+
    +
  • If neither LZMA_STR_ENCODER nor LZMA_STR_DECODER is used then the supported filter names are listed on a single line separated by spaces.
    • +
  • If LZMA_STR_ENCODER or LZMA_STR_DECODER is used then filters and the supported options are listed one filter per line. There won't be a newline after the last filter.
    • +
  • If LZMA_STR_ALL_FILTERS is used then the list will include also those filters that cannot be used in the .xz format (LZMA1).
    • +
+
Parameters
+ + + + + +
strOn success *str will be set to point to an allocated string listing the filters and options. Old value is ignored. On error *str is always set to NULL.
filter_idFilter ID or LZMA_VLI_UNKNOWN.
flagsBitwise-or of zero or more of the flags LZMA_STR_ALL_FILTERS, LZMA_STR_ENCODER, LZMA_STR_DECODER, and LZMA_STR_GETOPT_LONG.
allocatorlzma_allocator for custom allocator functions. Set to NULL to use malloc() and free().
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK
    • +
  • LZMA_OPTIONS_ERROR: Unsupported filter_id or flags
    • +
  • LZMA_MEM_ERROR
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+
+
+

+ XZ logo © 2023 by Jia Tan is licensed under + + CC BY-SA 4.0 + +

+ + diff --git a/doc/api/folderclosed.svg b/doc/api/folderclosed.svg new file mode 100644 index 00000000..47d22df8 --- /dev/null +++ b/doc/api/folderclosed.svg @@ -0,0 +1,11 @@ + + + + + + + + + + diff --git a/doc/api/folderclosedd.svg b/doc/api/folderclosedd.svg new file mode 100644 index 00000000..8fe00312 --- /dev/null +++ b/doc/api/folderclosedd.svg @@ -0,0 +1,11 @@ + + + + + + + + + + diff --git a/doc/api/folderopen.svg b/doc/api/folderopen.svg new file mode 100644 index 00000000..9565570f --- /dev/null +++ b/doc/api/folderopen.svg @@ -0,0 +1,17 @@ + + + + + + + + + + diff --git a/doc/api/folderopend.svg b/doc/api/folderopend.svg new file mode 100644 index 00000000..e72e2259 --- /dev/null +++ b/doc/api/folderopend.svg @@ -0,0 +1,12 @@ + + + + + + + + + + + diff --git a/doc/api/functions.html b/doc/api/functions.html new file mode 100644 index 00000000..ae7cb617 --- /dev/null +++ b/doc/api/functions.html @@ -0,0 +1,216 @@ + + + + + + + +liblzma (XZ Utils): Data Fields + + + + + + +
+
+ + + + + + + +
+
liblzma (XZ Utils) 5.6.0 +
+
+
+ + + + + + +
+
+
Here is a list of all documented struct and union fields with links to the struct/union documentation for each field:
+ +

- a -

+ + +

- b -

+ + +

- c -

+ + +

- d -

+ + +

- e -

+ + +

- f -

+ + +

- h -

+ + +

- i -

+ + +

- l -

+ + +

- m -

+ + +

- n -

+ + +

- o -

+ + +

- p -

+ + +

- r -

+ + +

- s -

+ + +

- t -

+ + +

- u -

+ + +

- v -

+
+
+

+ XZ logo © 2023 by Jia Tan is licensed under + + CC BY-SA 4.0 + +

+ + diff --git a/doc/api/functions_vars.html b/doc/api/functions_vars.html new file mode 100644 index 00000000..fcf673dd --- /dev/null +++ b/doc/api/functions_vars.html @@ -0,0 +1,216 @@ + + + + + + + +liblzma (XZ Utils): Data Fields - Variables + + + + + + +
+
+ + + + + + + +
+
liblzma (XZ Utils) 5.6.0 +
+
+
+ + + + + + +
+
+
Here is a list of all documented variables with links to the struct/union documentation for each field:
+ +

- a -

+ + +

- b -

+ + +

- c -

+ + +

- d -

+ + +

- e -

+ + +

- f -

+ + +

- h -

+ + +

- i -

+ + +

- l -

+ + +

- m -

+ + +

- n -

+ + +

- o -

+ + +

- p -

+ + +

- r -

+ + +

- s -

+ + +

- t -

+ + +

- u -

+ + +

- v -

+
+
+

+ XZ logo © 2023 by Jia Tan is licensed under + + CC BY-SA 4.0 + +

+ + diff --git a/doc/api/globals.html b/doc/api/globals.html new file mode 100644 index 00000000..0fb10014 --- /dev/null +++ b/doc/api/globals.html @@ -0,0 +1,284 @@ + + + + + + + +liblzma (XZ Utils): Globals + + + + + + +
+
+ + + + + + + +
+
liblzma (XZ Utils) 5.6.0 +
+
+
+ + + + + + +
+
+
Here is a list of all documented functions, variables, defines, enums, and typedefs with links to the documentation:
+ +

- l -

+
+
+

+ XZ logo © 2023 by Jia Tan is licensed under + + CC BY-SA 4.0 + +

+ + diff --git a/doc/api/globals_defs.html b/doc/api/globals_defs.html new file mode 100644 index 00000000..3883d0b6 --- /dev/null +++ b/doc/api/globals_defs.html @@ -0,0 +1,130 @@ + + + + + + + +liblzma (XZ Utils): Globals + + + + + + +
+
+ + + + + + + +
+
liblzma (XZ Utils) 5.6.0 +
+
+
+ + + + + + +
+
+
Here is a list of all documented macros with links to the documentation:
+ +

- l -

+
+
+

+ XZ logo © 2023 by Jia Tan is licensed under + + CC BY-SA 4.0 + +

+ + diff --git a/doc/api/globals_enum.html b/doc/api/globals_enum.html new file mode 100644 index 00000000..0a91b020 --- /dev/null +++ b/doc/api/globals_enum.html @@ -0,0 +1,77 @@ + + + + + + + +liblzma (XZ Utils): Globals + + + + + + +
+
+ + + + + + + +
+
liblzma (XZ Utils) 5.6.0 +
+
+
+ + + + + +
+
+
Here is a list of all documented enums with links to the documentation:
+
+
+

+ XZ logo © 2023 by Jia Tan is licensed under + + CC BY-SA 4.0 + +

+ + diff --git a/doc/api/globals_eval.html b/doc/api/globals_eval.html new file mode 100644 index 00000000..0d44c068 --- /dev/null +++ b/doc/api/globals_eval.html @@ -0,0 +1,109 @@ + + + + + + + +liblzma (XZ Utils): Globals + + + + + + +
+
+ + + + + + + +
+
liblzma (XZ Utils) 5.6.0 +
+
+
+ + + + + + +
+
+
Here is a list of all documented enum values with links to the documentation:
+ +

- l -

+
+
+

+ XZ logo © 2023 by Jia Tan is licensed under + + CC BY-SA 4.0 + +

+ + diff --git a/doc/api/globals_func.html b/doc/api/globals_func.html new file mode 100644 index 00000000..d3e6ebdb --- /dev/null +++ b/doc/api/globals_func.html @@ -0,0 +1,184 @@ + + + + + + + +liblzma (XZ Utils): Globals + + + + + + +
+
+ + + + + + + +
+
liblzma (XZ Utils) 5.6.0 +
+
+
+ + + + + + +
+
+
Here is a list of all documented functions with links to the documentation:
+ +

- l -

+
+
+

+ XZ logo © 2023 by Jia Tan is licensed under + + CC BY-SA 4.0 + +

+ + diff --git a/doc/api/globals_type.html b/doc/api/globals_type.html new file mode 100644 index 00000000..0ece9839 --- /dev/null +++ b/doc/api/globals_type.html @@ -0,0 +1,74 @@ + + + + + + + +liblzma (XZ Utils): Globals + + + + + + +
+
+ + + + + + + +
+
liblzma (XZ Utils) 5.6.0 +
+
+
+ + + + + +
+
+
Here is a list of all documented typedefs with links to the documentation:
+
+
+

+ XZ logo © 2023 by Jia Tan is licensed under + + CC BY-SA 4.0 + +

+ + diff --git a/doc/api/hardware_8h.html b/doc/api/hardware_8h.html new file mode 100644 index 00000000..2566fbbd --- /dev/null +++ b/doc/api/hardware_8h.html @@ -0,0 +1,145 @@ + + + + + + + +liblzma (XZ Utils): lzma/hardware.h File Reference + + + + + + +
+
+ + + + + + + +
+
liblzma (XZ Utils) 5.6.0 +
+
+
+ + + + + +
+
+
+Functions
+
hardware.h File Reference
+
+
+ +

Hardware information. +More...

+ + + + + + + + +

+Functions

uint64_t lzma_physmem (void) lzma_nothrow
 Get the total amount of physical memory (RAM) in bytes.
 
uint32_t lzma_cputhreads (void) lzma_nothrow
 Get the number of processor cores or threads.
 
+

Detailed Description

+

Hardware information.

+
Note
Never include this file directly. Use <lzma.h> instead.
+

Since liblzma can consume a lot of system resources, it also provides ways to limit the resource usage. Applications linking against liblzma need to do the actual decisions how much resources to let liblzma to use. To ease making these decisions, liblzma provides functions to find out the relevant capabilities of the underlying hardware. Currently there is only a function to find out the amount of RAM, but in the future there will be also a function to detect how many concurrent threads the system can run.

+
Note
On some operating systems, these function may temporarily load a shared library or open file descriptor(s) to find out the requested hardware information. Unless the application assumes that specific file descriptors are not touched by other threads, this should have no effect on thread safety. Possible operations involving file descriptors will restart the syscalls if they return EINTR.
+

Function Documentation

+ +

◆ lzma_physmem()

+ +
+
+ + + + + +
+ + + + + + + + +
uint64_t lzma_physmem (void )
+ 		+extern
+
+ +

Get the total amount of physical memory (RAM) in bytes.

+

This function may be useful when determining a reasonable memory usage limit for decompressing or how much memory it is OK to use for compressing.

+
Returns
On success, the total amount of physical memory in bytes is returned. If the amount of RAM cannot be determined, zero is returned. This can happen if an error occurs or if there is no code in liblzma to detect the amount of RAM on the specific operating system.
+ +
+
+ +

◆ lzma_cputhreads()

+ +
+
+ + + + + +
+ + + + + + + + +
uint32_t lzma_cputhreads (void )
+ 		+extern
+
+ +

Get the number of processor cores or threads.

+

This function may be useful when determining how many threads to use. If the hardware supports more than one thread per CPU core, the number of hardware threads is returned if that information is available.

+
Returns
On success, the number of available CPU threads or cores is returned. If this information isn't available or an error occurs, zero is returned.
+ +
+
+
+
+

+ XZ logo © 2023 by Jia Tan is licensed under + + CC BY-SA 4.0 + +

+ + diff --git a/doc/api/index.html b/doc/api/index.html new file mode 100644 index 00000000..739e8522 --- /dev/null +++ b/doc/api/index.html @@ -0,0 +1,60 @@ + + + + + + + +liblzma (XZ Utils): liblzma (XZ Utils) + + + + + + +
+
+ + + + + + + +
+
liblzma (XZ Utils) 5.6.0 +
+
+
+ + + +
+
+
liblzma (XZ Utils)
+
+
+

liblzma is a general-purpose data compression library with a zlib-like API. The native file format is .xz, but also the old .lzma format and raw (no headers) streams are supported. Multiple compression algorithms (filters) are supported. Currently LZMA2 is the primary filter.

+

liblzma is part of XZ Utils https://xz.tukaani.org/xz-utils/. XZ Utils includes a gzip-like command line tool named xz and some other tools. XZ Utils is developed and maintained by Lasse Collin and Jia Tan.

+

Major parts of liblzma are based on code written by Igor Pavlov, specifically the LZMA SDK https://7-zip.org/sdk.html.

+

The SHA-256 implementation in liblzma is based on code written by Wei Dai in Crypto++ Library https://www.cryptopp.com/.

+

liblzma is distributed under the BSD Zero Clause License (0BSD).

+
+
+
+

+ XZ logo © 2023 by Jia Tan is licensed under + + CC BY-SA 4.0 + +

+ + diff --git a/doc/api/index_8h.html b/doc/api/index_8h.html new file mode 100644 index 00000000..42b4dda6 --- /dev/null +++ b/doc/api/index_8h.html @@ -0,0 +1,1519 @@ + + + + + + + +liblzma (XZ Utils): lzma/index.h File Reference + + + + + + +
+
+ + + + + + + +
+
liblzma (XZ Utils) 5.6.0 +
+
+
+ + + + + +
+
+
+Data Structures | +Macros | +Typedefs | +Enumerations | +Functions
+
index.h File Reference
+
+
+ +

Handling of .xz Index and related information. +More...

+ + + + + +

+Data Structures

struct  lzma_index_iter
 Iterator to get information about Blocks and Streams. More...
 
+ + + + + + + + + + + + + +

+Macros

#define LZMA_INDEX_CHECK_MASK_NONE   (UINT32_C(1) << LZMA_CHECK_NONE)
 Mask for return value from lzma_index_checks() for check none.
 
+#define LZMA_INDEX_CHECK_MASK_CRC32   (UINT32_C(1) << LZMA_CHECK_CRC32)
 Mask for return value from lzma_index_checks() for check CRC32.
 
+#define LZMA_INDEX_CHECK_MASK_CRC64   (UINT32_C(1) << LZMA_CHECK_CRC64)
 Mask for return value from lzma_index_checks() for check CRC64.
 
+#define LZMA_INDEX_CHECK_MASK_SHA256   (UINT32_C(1) << LZMA_CHECK_SHA256)
 Mask for return value from lzma_index_checks() for check SHA256.
 
+ + + + +

+Typedefs

typedef struct lzma_index_s lzma_index
 Opaque data type to hold the Index(es) and other information.
 
+ + + + +

+Enumerations

enum  lzma_index_iter_mode { LZMA_INDEX_ITER_ANY = 0 +, LZMA_INDEX_ITER_STREAM = 1 +, LZMA_INDEX_ITER_BLOCK = 2 +, LZMA_INDEX_ITER_NONEMPTY_BLOCK = 3 + }
 Operation mode for lzma_index_iter_next() More...
 
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+Functions

uint64_t lzma_index_memusage (lzma_vli streams, lzma_vli blocks) lzma_nothrow
 Calculate memory usage of lzma_index.
 
uint64_t lzma_index_memused (const lzma_index *i) lzma_nothrow
 Calculate the memory usage of an existing lzma_index.
 
lzma_index * lzma_index_init (const lzma_allocator *allocator) lzma_nothrow
 Allocate and initialize a new lzma_index structure.
 
void lzma_index_end (lzma_index *i, const lzma_allocator *allocator) lzma_nothrow
 Deallocate lzma_index.
 
lzma_ret lzma_index_append (lzma_index *i, const lzma_allocator *allocator, lzma_vli unpadded_size, lzma_vli uncompressed_size) lzma_nothrow lzma_attr_warn_unused_result
 Add a new Block to lzma_index.
 
lzma_ret lzma_index_stream_flags (lzma_index *i, const lzma_stream_flags *stream_flags) lzma_nothrow lzma_attr_warn_unused_result
 Set the Stream Flags.
 
uint32_t lzma_index_checks (const lzma_index *i) lzma_nothrow lzma_attr_pure
 Get the types of integrity Checks.
 
lzma_ret lzma_index_stream_padding (lzma_index *i, lzma_vli stream_padding) lzma_nothrow lzma_attr_warn_unused_result
 Set the amount of Stream Padding.
 
lzma_vli lzma_index_stream_count (const lzma_index *i) lzma_nothrow lzma_attr_pure
 Get the number of Streams.
 
lzma_vli lzma_index_block_count (const lzma_index *i) lzma_nothrow lzma_attr_pure
 Get the number of Blocks.
 
lzma_vli lzma_index_size (const lzma_index *i) lzma_nothrow lzma_attr_pure
 Get the size of the Index field as bytes.
 
lzma_vli lzma_index_stream_size (const lzma_index *i) lzma_nothrow lzma_attr_pure
 Get the total size of the Stream.
 
lzma_vli lzma_index_total_size (const lzma_index *i) lzma_nothrow lzma_attr_pure
 Get the total size of the Blocks.
 
lzma_vli lzma_index_file_size (const lzma_index *i) lzma_nothrow lzma_attr_pure
 Get the total size of the file.
 
lzma_vli lzma_index_uncompressed_size (const lzma_index *i) lzma_nothrow lzma_attr_pure
 Get the uncompressed size of the file.
 
void lzma_index_iter_init (lzma_index_iter *iter, const lzma_index *i) lzma_nothrow
 Initialize an iterator.
 
void lzma_index_iter_rewind (lzma_index_iter *iter) lzma_nothrow
 Rewind the iterator.
 
lzma_bool lzma_index_iter_next (lzma_index_iter *iter, lzma_index_iter_mode mode) lzma_nothrow lzma_attr_warn_unused_result
 Get the next Block or Stream.
 
lzma_bool lzma_index_iter_locate (lzma_index_iter *iter, lzma_vli target) lzma_nothrow
 Locate a Block.
 
lzma_ret lzma_index_cat (lzma_index *dest, lzma_index *src, const lzma_allocator *allocator) lzma_nothrow lzma_attr_warn_unused_result
 Concatenate lzma_indexes.
 
lzma_index * lzma_index_dup (const lzma_index *i, const lzma_allocator *allocator) lzma_nothrow lzma_attr_warn_unused_result
 Duplicate lzma_index.
 
lzma_ret lzma_index_encoder (lzma_stream *strm, const lzma_index *i) lzma_nothrow lzma_attr_warn_unused_result
 Initialize .xz Index encoder.
 
lzma_ret lzma_index_decoder (lzma_stream *strm, lzma_index **i, uint64_t memlimit) lzma_nothrow lzma_attr_warn_unused_result
 Initialize .xz Index decoder.
 
lzma_ret lzma_index_buffer_encode (const lzma_index *i, uint8_t *out, size_t *out_pos, size_t out_size) lzma_nothrow
 Single-call .xz Index encoder.
 
lzma_ret lzma_index_buffer_decode (lzma_index **i, uint64_t *memlimit, const lzma_allocator *allocator, const uint8_t *in, size_t *in_pos, size_t in_size) lzma_nothrow
 Single-call .xz Index decoder.
 
lzma_ret lzma_file_info_decoder (lzma_stream *strm, lzma_index **dest_index, uint64_t memlimit, uint64_t file_size) lzma_nothrow
 Initialize a .xz file information decoder.
 
+

Detailed Description

+

Handling of .xz Index and related information.

+
Note
Never include this file directly. Use <lzma.h> instead.
+

Macro Definition Documentation

+ +

◆ LZMA_INDEX_CHECK_MASK_NONE

+ +
+
+ + + + +
#define LZMA_INDEX_CHECK_MASK_NONE   (UINT32_C(1) << LZMA_CHECK_NONE)
+
+ +

Mask for return value from lzma_index_checks() for check none.

+
Note
This and the other CHECK_MASK macros were added in 5.5.1alpha.
+ +
+
+

Typedef Documentation

+ +

◆ lzma_index

+ +
+
+ + + + +
typedef struct lzma_index_s lzma_index
+
+ +

Opaque data type to hold the Index(es) and other information.

+

lzma_index often holds just one .xz Index and possibly the Stream Flags of the same Stream and size of the Stream Padding field. However, multiple lzma_indexes can be concatenated with lzma_index_cat() and then there may be information about multiple Streams in the same lzma_index.

+

Notes about thread safety: Only one thread may modify lzma_index at a time. All functions that take non-const pointer to lzma_index modify it. As long as no thread is modifying the lzma_index, getting information from the same lzma_index can be done from multiple threads at the same time with functions that take a const pointer to lzma_index or use lzma_index_iter. The same iterator must be used only by one thread at a time, of course, but there can be as many iterators for the same lzma_index as needed.

+ +
+
+

Enumeration Type Documentation

+ +

◆ lzma_index_iter_mode

+ +
+
+ + + + +
enum lzma_index_iter_mode
+
+ +

Operation mode for lzma_index_iter_next()

+ + + + + +
Enumerator
LZMA_INDEX_ITER_ANY 

Get the next Block or Stream.

+

Go to the next Block if the current Stream has at least one Block left. Otherwise go to the next Stream even if it has no Blocks. If the Stream has no Blocks (lzma_index_iter.stream.block_count == 0), lzma_index_iter.block will have undefined values.

+
LZMA_INDEX_ITER_STREAM 

Get the next Stream.

+

Go to the next Stream even if the current Stream has unread Blocks left. If the next Stream has at least one Block, the iterator will point to the first Block. If there are no Blocks, lzma_index_iter.block will have undefined values.

+
LZMA_INDEX_ITER_BLOCK 

Get the next Block.

+

Go to the next Block if the current Stream has at least one Block left. If the current Stream has no Blocks left, the next Stream with at least one Block is located and the iterator will be made to point to the first Block of that Stream.

+
LZMA_INDEX_ITER_NONEMPTY_BLOCK 

Get the next non-empty Block.

+

This is like LZMA_INDEX_ITER_BLOCK except that it will skip Blocks whose Uncompressed Size is zero.

+
+ +
+
+

Function Documentation

+ +

◆ lzma_index_memusage()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + +
uint64_t lzma_index_memusage (lzma_vli streams,
lzma_vli blocks 
)
+ 		+extern
+
+ +

Calculate memory usage of lzma_index.

+

On disk, the size of the Index field depends on both the number of Records stored and the size of the Records (due to variable-length integer encoding). When the Index is kept in lzma_index structure, the memory usage depends only on the number of Records/Blocks stored in the Index(es), and in case of concatenated lzma_indexes, the number of Streams. The size in RAM is almost always significantly bigger than in the encoded form on disk.

+

This function calculates an approximate amount of memory needed to hold the given number of Streams and Blocks in lzma_index structure. This value may vary between CPU architectures and also between liblzma versions if the internal implementation is modified.

+
Parameters
+ + + +
streamsNumber of Streams
blocksNumber of Blocks
+
+
+
Returns
Approximate memory in bytes needed in a lzma_index structure.
+ +
+
+ +

◆ lzma_index_memused()

+ +
+
+ + + + + +
+ + + + + + + + +
uint64_t lzma_index_memused (const lzma_index * i)
+ 		+extern
+
+ +

Calculate the memory usage of an existing lzma_index.

+

This is a shorthand for lzma_index_memusage(lzma_index_stream_count(i), lzma_index_block_count(i)).

+
Parameters
+ + +
iPointer to lzma_index structure
+
+
+
Returns
Approximate memory in bytes used by the lzma_index structure.
+ +
+
+ +

◆ lzma_index_init()

+ +
+
+ + + + + +
+ + + + + + + + +
lzma_index * lzma_index_init (const lzma_allocator * allocator)
+ 		+extern
+
+ +

Allocate and initialize a new lzma_index structure.

+
Parameters
+ + +
allocatorlzma_allocator for custom allocator functions. Set to NULL to use malloc() and free().
+
+
+
Returns
On success, a pointer to an empty initialized lzma_index is returned. If allocation fails, NULL is returned.
+ +
+
+ +

◆ lzma_index_end()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + +
void lzma_index_end (lzma_index * i,
const lzma_allocator * allocator 
)
+ 		+extern
+
+ +

Deallocate lzma_index.

+

If i is NULL, this does nothing.

+
Parameters
+ + + +
iPointer to lzma_index structure to deallocate
allocatorlzma_allocator for custom allocator functions. Set to NULL to use malloc() and free().
+
+
+ +
+
+ +

◆ lzma_index_append()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_index_append (lzma_index * i,
const lzma_allocator * allocator,
lzma_vli unpadded_size,
lzma_vli uncompressed_size 
)
+ 		+extern
+
+ +

Add a new Block to lzma_index.

+
Parameters
+ + + + + +
iPointer to a lzma_index structure
allocatorlzma_allocator for custom allocator functions. Set to NULL to use malloc() and free().
unpadded_sizeUnpadded Size of a Block. This can be calculated with lzma_block_unpadded_size() after encoding or decoding the Block.
uncompressed_sizeUncompressed Size of a Block. This can be taken directly from lzma_block structure after encoding or decoding the Block.
+
+
+

Appending a new Block does not invalidate iterators. For example, if an iterator was pointing to the end of the lzma_index, after lzma_index_append() it is possible to read the next Block with an existing iterator.

+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK
    • +
  • LZMA_MEM_ERROR
    • +
  • LZMA_DATA_ERROR: Compressed or uncompressed size of the Stream or size of the Index field would grow too big.
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+ +

◆ lzma_index_stream_flags()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + +
lzma_ret lzma_index_stream_flags (lzma_index * i,
const lzma_stream_flags * stream_flags 
)
+ 		+extern
+
+ +

Set the Stream Flags.

+

Set the Stream Flags of the last (and typically the only) Stream in lzma_index. This can be useful when reading information from the lzma_index, because to decode Blocks, knowing the integrity check type is needed.

+
Parameters
+ + + +
iPointer to lzma_index structure
stream_flagsPointer to lzma_stream_flags structure. This is copied into the internal preallocated structure, so the caller doesn't need to keep the flags' data available after calling this function.
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK
    • +
  • LZMA_OPTIONS_ERROR: Unsupported stream_flags->version.
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+ +

◆ lzma_index_checks()

+ +
+
+ + + + + +
+ + + + + + + + +
uint32_t lzma_index_checks (const lzma_index * i)
+ 		+extern
+
+ +

Get the types of integrity Checks.

+

If lzma_index_stream_flags() is used to set the Stream Flags for every Stream, lzma_index_checks() can be used to get a bitmask to indicate which Check types have been used. It can be useful e.g. if showing the Check types to the user.

+

The bitmask is 1 << check_id, e.g. CRC32 is 1 << 1 and SHA-256 is 1 << 10. These masks are defined for convenience as LZMA_INDEX_CHECK_MASK_XXX

+
Parameters
+ + +
iPointer to lzma_index structure
+
+
+
Returns
Bitmask indicating which Check types are used in the lzma_index
+ +
+
+ +

◆ lzma_index_stream_padding()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + +
lzma_ret lzma_index_stream_padding (lzma_index * i,
lzma_vli stream_padding 
)
+ 		+extern
+
+ +

Set the amount of Stream Padding.

+

Set the amount of Stream Padding of the last (and typically the only) Stream in the lzma_index. This is needed when planning to do random-access reading within multiple concatenated Streams.

+

By default, the amount of Stream Padding is assumed to be zero bytes.

+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK
    • +
  • LZMA_DATA_ERROR: The file size would grow too big.
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+ +

◆ lzma_index_stream_count()

+ +
+
+ + + + + +
+ + + + + + + + +
lzma_vli lzma_index_stream_count (const lzma_index * i)
+ 		+extern
+
+ +

Get the number of Streams.

+
Parameters
+ + +
iPointer to lzma_index structure
+
+
+
Returns
Number of Streams in the lzma_index
+ +
+
+ +

◆ lzma_index_block_count()

+ +
+
+ + + + + +
+ + + + + + + + +
lzma_vli lzma_index_block_count (const lzma_index * i)
+ 		+extern
+
+ +

Get the number of Blocks.

+

This returns the total number of Blocks in lzma_index. To get number of Blocks in individual Streams, use lzma_index_iter.

+
Parameters
+ + +
iPointer to lzma_index structure
+
+
+
Returns
Number of blocks in the lzma_index
+ +
+
+ +

◆ lzma_index_size()

+ +
+
+ + + + + +
+ + + + + + + + +
lzma_vli lzma_index_size (const lzma_index * i)
+ 		+extern
+
+ +

Get the size of the Index field as bytes.

+

This is needed to verify the Backward Size field in the Stream Footer.

+
Parameters
+ + +
iPointer to lzma_index structure
+
+
+
Returns
Size in bytes of the Index
+ +
+
+ +

◆ lzma_index_stream_size()

+ +
+
+ + + + + +
+ + + + + + + + +
lzma_vli lzma_index_stream_size (const lzma_index * i)
+ 		+extern
+
+ +

Get the total size of the Stream.

+

If multiple lzma_indexes have been combined, this works as if the Blocks were in a single Stream. This is useful if you are going to combine Blocks from multiple Streams into a single new Stream.

+
Parameters
+ + +
iPointer to lzma_index structure
+
+
+
Returns
Size in bytes of the Stream (if all Blocks are combined into one Stream).
+ +
+
+ +

◆ lzma_index_total_size()

+ +
+
+ + + + + +
+ + + + + + + + +
lzma_vli lzma_index_total_size (const lzma_index * i)
+ 		+extern
+
+ +

Get the total size of the Blocks.

+

This doesn't include the Stream Header, Stream Footer, Stream Padding, or Index fields.

+
Parameters
+ + +
iPointer to lzma_index structure
+
+
+
Returns
Size in bytes of all Blocks in the Stream(s)
+ +
+
+ +

◆ lzma_index_file_size()

+ +
+
+ + + + + +
+ + + + + + + + +
lzma_vli lzma_index_file_size (const lzma_index * i)
+ 		+extern
+
+ +

Get the total size of the file.

+

When no lzma_indexes have been combined with lzma_index_cat() and there is no Stream Padding, this function is identical to lzma_index_stream_size(). If multiple lzma_indexes have been combined, this includes also the headers of each separate Stream and the possible Stream Padding fields.

+
Parameters
+ + +
iPointer to lzma_index structure
+
+
+
Returns
Total size of the .xz file in bytes
+ +
+
+ +

◆ lzma_index_uncompressed_size()

+ +
+
+ + + + + +
+ + + + + + + + +
lzma_vli lzma_index_uncompressed_size (const lzma_index * i)
+ 		+extern
+
+ +

Get the uncompressed size of the file.

+
Parameters
+ + +
iPointer to lzma_index structure
+
+
+
Returns
Size in bytes of the uncompressed data in the file
+ +
+
+ +

◆ lzma_index_iter_init()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + +
void lzma_index_iter_init (lzma_index_iter * iter,
const lzma_index * i 
)
+ 		+extern
+
+ +

Initialize an iterator.

+

This function associates the iterator with the given lzma_index, and calls lzma_index_iter_rewind() on the iterator.

+

This function doesn't allocate any memory, thus there is no lzma_index_iter_end(). The iterator is valid as long as the associated lzma_index is valid, that is, until lzma_index_end() or using it as source in lzma_index_cat(). Specifically, lzma_index doesn't become invalid if new Blocks are added to it with lzma_index_append() or if it is used as the destination in lzma_index_cat().

+

It is safe to make copies of an initialized lzma_index_iter, for example, to easily restart reading at some particular position.

+
Parameters
+ + + +
iterPointer to a lzma_index_iter structure
ilzma_index to which the iterator will be associated
+
+
+ +
+
+ +

◆ lzma_index_iter_rewind()

+ +
+
+ + + + + +
+ + + + + + + + +
void lzma_index_iter_rewind (lzma_index_iter * iter)
+ 		+extern
+
+ +

Rewind the iterator.

+

Rewind the iterator so that next call to lzma_index_iter_next() will return the first Block or Stream.

+
Parameters
+ + +
iterPointer to a lzma_index_iter structure
+
+
+ +
+
+ +

◆ lzma_index_iter_next()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + +
lzma_bool lzma_index_iter_next (lzma_index_iter * iter,
lzma_index_iter_mode mode 
)
+ 		+extern
+
+ +

Get the next Block or Stream.

+
Parameters
+ + + +
iterIterator initialized with lzma_index_iter_init()
modeSpecify what kind of information the caller wants to get. See lzma_index_iter_mode for details.
+
+
+
Returns
lzma_bool:
    +
  • true if no Block or Stream matching the mode is found. *iter is not updated (failure).
    • +
  • false if the next Block or Stream matching the mode was found. *iter is updated (success).
    • +
+
+ +
+
+ +

◆ lzma_index_iter_locate()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + +
lzma_bool lzma_index_iter_locate (lzma_index_iter * iter,
lzma_vli target 
)
+ 		+extern
+
+ +

Locate a Block.

+

If it is possible to seek in the .xz file, it is possible to parse the Index field(s) and use lzma_index_iter_locate() to do random-access reading with granularity of Block size.

+

If the target is smaller than the uncompressed size of the Stream (can be checked with lzma_index_uncompressed_size()):

    +
  • Information about the Stream and Block containing the requested uncompressed offset is stored into *iter.
    • +
  • Internal state of the iterator is adjusted so that lzma_index_iter_next() can be used to read subsequent Blocks or Streams.
    • +
+

If the target is greater than the uncompressed size of the Stream, *iter is not modified.

+
Parameters
+ + + +
iterIterator that was earlier initialized with lzma_index_iter_init().
targetUncompressed target offset which the caller would like to locate from the Stream
+
+
+
Returns
lzma_bool:
    +
  • true if the target is greater than or equal to the uncompressed size of the Stream (failure)
    • +
  • false if the target is smaller than the uncompressed size of the Stream (success)
    • +
+
+ +
+
+ +

◆ lzma_index_cat()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_index_cat (lzma_index * dest,
lzma_index * src,
const lzma_allocator * allocator 
)
+ 		+extern
+
+ +

Concatenate lzma_indexes.

+

Concatenating lzma_indexes is useful when doing random-access reading in multi-Stream .xz file, or when combining multiple Streams into single Stream.

+
Parameters
+ + + + +
[out]destlzma_index after which src is appended
srclzma_index to be appended after dest. If this function succeeds, the memory allocated for src is freed or moved to be part of dest, and all iterators pointing to src will become invalid.
allocatorlzma_allocator for custom allocator functions. Set to NULL to use malloc() and free().
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: lzma_indexes were concatenated successfully. src is now a dangling pointer.
    • +
  • LZMA_DATA_ERROR: *dest would grow too big.
    • +
  • LZMA_MEM_ERROR
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+ +

◆ lzma_index_dup()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + +
lzma_index * lzma_index_dup (const lzma_index * i,
const lzma_allocator * allocator 
)
+ 		+extern
+
+ +

Duplicate lzma_index.

+
Parameters
+ + + +
iPointer to lzma_index structure to be duplicated
allocatorlzma_allocator for custom allocator functions. Set to NULL to use malloc() and free().
+
+
+
Returns
A copy of the lzma_index, or NULL if memory allocation failed.
+ +
+
+ +

◆ lzma_index_encoder()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + +
lzma_ret lzma_index_encoder (lzma_stream * strm,
const lzma_index * i 
)
+ 		+extern
+
+ +

Initialize .xz Index encoder.

+
Parameters
+ + + +
strmPointer to properly prepared lzma_stream
iPointer to lzma_index which should be encoded.
+
+
+

The valid 'action' values for lzma_code() are LZMA_RUN and LZMA_FINISH. It is enough to use only one of them (you can choose freely).

+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: Initialization succeeded, continue with lzma_code().
    • +
  • LZMA_MEM_ERROR
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+ +

◆ lzma_index_decoder()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_index_decoder (lzma_stream * strm,
lzma_index ** i,
uint64_t memlimit 
)
+ 		+extern
+
+ +

Initialize .xz Index decoder.

+
Parameters
+ + + + +
strmPointer to properly prepared lzma_stream
[out]iThe decoded Index will be made available via this pointer. Initially this function will set *i to NULL (the old value is ignored). If decoding succeeds (lzma_code() returns LZMA_STREAM_END), *i will be set to point to a new lzma_index, which the application has to later free with lzma_index_end().
memlimitHow much memory the resulting lzma_index is allowed to require. liblzma 5.2.3 and earlier don't allow 0 here and return LZMA_PROG_ERROR; later versions treat 0 as if 1 had been specified.
+
+
+

Valid 'action' arguments to lzma_code() are LZMA_RUN and LZMA_FINISH. There is no need to use LZMA_FINISH, but it's allowed because it may simplify certain types of applications.

+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: Initialization succeeded, continue with lzma_code().
    • +
  • LZMA_MEM_ERROR
    • +
  • LZMA_PROG_ERROR
    • +
+
+
Note
liblzma 5.2.3 and older list also LZMA_MEMLIMIT_ERROR here but that error code has never been possible from this initialization function.
+ +
+
+ +

◆ lzma_index_buffer_encode()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_index_buffer_encode (const lzma_index * i,
uint8_t * out,
size_t * out_pos,
size_t out_size 
)
+ 		+extern
+
+ +

Single-call .xz Index encoder.

+
Note
This function doesn't take allocator argument since all the internal data is allocated on stack.
+
Parameters
+ + + + + +
ilzma_index to be encoded
[out]outBeginning of the output buffer
[out]out_posThe next byte will be written to out[*out_pos]. *out_pos is updated only if encoding succeeds.
out_sizeSize of the out buffer; the first byte into which no data is written to is out[out_size].
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: Encoding was successful.
    • +
  • LZMA_BUF_ERROR: Output buffer is too small. Use lzma_index_size() to find out how much output space is needed.
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+ +

◆ lzma_index_buffer_decode()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_index_buffer_decode (lzma_index ** i,
uint64_t * memlimit,
const lzma_allocator * allocator,
const uint8_t * in,
size_t * in_pos,
size_t in_size 
)
+ 		+extern
+
+ +

Single-call .xz Index decoder.

+
Parameters
+ + + + + + + +
[out]iIf decoding succeeds, *i will point to a new lzma_index, which the application has to later free with lzma_index_end(). If an error occurs, *i will be NULL. The old value of *i is always ignored and thus doesn't need to be initialized by the caller.
[out]memlimitPointer to how much memory the resulting lzma_index is allowed to require. The value pointed by this pointer is modified if and only if LZMA_MEMLIMIT_ERROR is returned.
allocatorlzma_allocator for custom allocator functions. Set to NULL to use malloc() and free().
inBeginning of the input buffer
in_posThe next byte will be read from in[*in_pos]. *in_pos is updated only if decoding succeeds.
in_sizeSize of the input buffer; the first byte that won't be read is in[in_size].
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: Decoding was successful.
    • +
  • LZMA_MEM_ERROR
    • +
  • LZMA_MEMLIMIT_ERROR: Memory usage limit was reached. The minimum required memlimit value was stored to *memlimit.
    • +
  • LZMA_DATA_ERROR
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+ +

◆ lzma_file_info_decoder()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_file_info_decoder (lzma_stream * strm,
lzma_index ** dest_index,
uint64_t memlimit,
uint64_t file_size 
)
+ 		+extern
+
+ +

Initialize a .xz file information decoder.

+

This decoder decodes the Stream Header, Stream Footer, Index, and Stream Padding field(s) from the input .xz file and stores the resulting combined index in *dest_index. This information can be used to get the uncompressed file size with lzma_index_uncompressed_size(*dest_index) or, for example, to implement random access reading by locating the Blocks in the Streams.

+

To get the required information from the .xz file, lzma_code() may ask the application to seek in the input file by returning LZMA_SEEK_NEEDED and having the target file position specified in lzma_stream.seek_pos. The number of seeks required depends on the input file and how big buffers the application provides. When possible, the decoder will seek backward and forward in the given buffer to avoid useless seek requests. Thus, if the application provides the whole file at once, no external seeking will be required (that is, lzma_code() won't return LZMA_SEEK_NEEDED).

+

The value in lzma_stream.total_in can be used to estimate how much data liblzma had to read to get the file information. However, due to seeking and the way total_in is updated, the value of total_in will be somewhat inaccurate (a little too big). Thus, total_in is a good estimate but don't expect to see the same exact value for the same file if you change the input buffer size or switch to a different liblzma version.

+

Valid 'action' arguments to lzma_code() are LZMA_RUN and LZMA_FINISH. You only need to use LZMA_RUN; LZMA_FINISH is only supported because it might be convenient for some applications. If you use LZMA_FINISH and if lzma_code() asks the application to seek, remember to reset 'action' back to LZMA_RUN unless you hit the end of the file again.

+

Possible return values from lzma_code():

    +
  • LZMA_OK: All OK so far, more input needed
    • +
  • LZMA_SEEK_NEEDED: Provide more input starting from the absolute file position strm->seek_pos
    • +
  • LZMA_STREAM_END: Decoding was successful, *dest_index has been set
    • +
  • LZMA_FORMAT_ERROR: The input file is not in the .xz format (the expected magic bytes were not found from the beginning of the file)
    • +
  • LZMA_OPTIONS_ERROR: File looks valid but contains headers that aren't supported by this version of liblzma
    • +
  • LZMA_DATA_ERROR: File is corrupt
    • +
  • LZMA_BUF_ERROR
    • +
  • LZMA_MEM_ERROR
    • +
  • LZMA_MEMLIMIT_ERROR
    • +
  • LZMA_PROG_ERROR
    • +
+
Parameters
+ + + + + +
strmPointer to a properly prepared lzma_stream
[out]dest_indexPointer to a pointer where the decoder will put the decoded lzma_index. The old value of *dest_index is ignored (not freed).
memlimitHow much memory the resulting lzma_index is allowed to require. Use UINT64_MAX to effectively disable the limiter.
file_sizeSize of the input .xz file
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK
    • +
  • LZMA_MEM_ERROR
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+
+
+

+ XZ logo © 2023 by Jia Tan is licensed under + + CC BY-SA 4.0 + +

+ + diff --git a/doc/api/index__hash_8h.html b/doc/api/index__hash_8h.html new file mode 100644 index 00000000..47206e84 --- /dev/null +++ b/doc/api/index__hash_8h.html @@ -0,0 +1,357 @@ + + + + + + + +liblzma (XZ Utils): lzma/index_hash.h File Reference + + + + + + +
+
+ + + + + + + +
+
liblzma (XZ Utils) 5.6.0 +
+
+
+ + + + + +
+
+
+Typedefs | +Functions
+
index_hash.h File Reference
+
+
+ +

Validate Index by using a hash function. +More...

+ + + + + +

+Typedefs

+typedef struct lzma_index_hash_s lzma_index_hash
 Opaque data type to hold the Index hash.
 
+ + + + + + + + + + + + + + + + +

+Functions

lzma_index_hash * lzma_index_hash_init (lzma_index_hash *index_hash, const lzma_allocator *allocator) lzma_nothrow lzma_attr_warn_unused_result
 Allocate and initialize a new lzma_index_hash structure.
 
void lzma_index_hash_end (lzma_index_hash *index_hash, const lzma_allocator *allocator) lzma_nothrow
 Deallocate lzma_index_hash structure.
 
lzma_ret lzma_index_hash_append (lzma_index_hash *index_hash, lzma_vli unpadded_size, lzma_vli uncompressed_size) lzma_nothrow lzma_attr_warn_unused_result
 Add a new Record to an Index hash.
 
lzma_ret lzma_index_hash_decode (lzma_index_hash *index_hash, const uint8_t *in, size_t *in_pos, size_t in_size) lzma_nothrow lzma_attr_warn_unused_result
 Decode and validate the Index field.
 
lzma_vli lzma_index_hash_size (const lzma_index_hash *index_hash) lzma_nothrow lzma_attr_pure
 Get the size of the Index field as bytes.
 
+

Detailed Description

+

Validate Index by using a hash function.

+
Note
Never include this file directly. Use <lzma.h> instead.
+

Hashing makes it possible to use constant amount of memory to validate Index of arbitrary size.

+

Function Documentation

+ +

◆ lzma_index_hash_init()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + +
lzma_index_hash * lzma_index_hash_init (lzma_index_hash * index_hash,
const lzma_allocator * allocator 
)
+ 		+extern
+
+ +

Allocate and initialize a new lzma_index_hash structure.

+

If index_hash is NULL, this function allocates and initializes a new lzma_index_hash structure and returns a pointer to it. If allocation fails, NULL is returned.

+

If index_hash is non-NULL, this function reinitializes the lzma_index_hash structure and returns the same pointer. In this case, return value cannot be NULL or a different pointer than the index_hash that was given as an argument.

+
Parameters
+ + + +
index_hashPointer to a lzma_index_hash structure or NULL.
allocatorlzma_allocator for custom allocator functions. Set to NULL to use malloc() and free().
+
+
+
Returns
Initialized lzma_index_hash structure on success or NULL on failure.
+ +
+
+ +

◆ lzma_index_hash_end()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + +
void lzma_index_hash_end (lzma_index_hash * index_hash,
const lzma_allocator * allocator 
)
+ 		+extern
+
+ +

Deallocate lzma_index_hash structure.

+
Parameters
+ + + +
index_hashPointer to a lzma_index_hash structure to free.
allocatorlzma_allocator for custom allocator functions. Set to NULL to use malloc() and free().
+
+
+ +
+
+ +

◆ lzma_index_hash_append()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_index_hash_append (lzma_index_hash * index_hash,
lzma_vli unpadded_size,
lzma_vli uncompressed_size 
)
+ 		+extern
+
+ +

Add a new Record to an Index hash.

+
Parameters
+ + + + +
index_hashPointer to a lzma_index_hash structure
unpadded_sizeUnpadded Size of a Block
uncompressed_sizeUncompressed Size of a Block
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK
    • +
  • LZMA_DATA_ERROR: Compressed or uncompressed size of the Stream or size of the Index field would grow too big.
    • +
  • LZMA_PROG_ERROR: Invalid arguments or this function is being used when lzma_index_hash_decode() has already been used.
    • +
+
+ +
+
+ +

◆ lzma_index_hash_decode()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_index_hash_decode (lzma_index_hash * index_hash,
const uint8_t * in,
size_t * in_pos,
size_t in_size 
)
+ 		+extern
+
+ +

Decode and validate the Index field.

+

After telling the sizes of all Blocks with lzma_index_hash_append(), the actual Index field is decoded with this function. Specifically, once decoding of the Index field has been started, no more Records can be added using lzma_index_hash_append().

+

This function doesn't use lzma_stream structure to pass the input data. Instead, the input buffer is specified using three arguments. This is because it matches better the internal APIs of liblzma.

+
Parameters
+ + + + + +
index_hashPointer to a lzma_index_hash structure
inPointer to the beginning of the input buffer
[out]in_posin[*in_pos] is the next byte to process
in_sizein[in_size] is the first byte not to process
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: So far good, but more input is needed.
    • +
  • LZMA_STREAM_END: Index decoded successfully and it matches the Records given with lzma_index_hash_append().
    • +
  • LZMA_DATA_ERROR: Index is corrupt or doesn't match the information given with lzma_index_hash_append().
    • +
  • LZMA_BUF_ERROR: Cannot progress because *in_pos >= in_size.
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+ +

◆ lzma_index_hash_size()

+ +
+
+ + + + + +
+ + + + + + + + +
lzma_vli lzma_index_hash_size (const lzma_index_hash * index_hash)
+ 		+extern
+
+ +

Get the size of the Index field as bytes.

+

This is needed to verify the Backward Size field in the Stream Footer.

+
Parameters
+ + +
index_hashPointer to a lzma_index_hash structure
+
+
+
Returns
Size of the Index field in bytes.
+ +
+
+
+
+

+ XZ logo © 2023 by Jia Tan is licensed under + + CC BY-SA 4.0 + +

+ + diff --git a/doc/api/lzma12_8h.html b/doc/api/lzma12_8h.html new file mode 100644 index 00000000..ea254b44 --- /dev/null +++ b/doc/api/lzma12_8h.html @@ -0,0 +1,466 @@ + + + + + + + +liblzma (XZ Utils): lzma/lzma12.h File Reference + + + + + + +
+
+ + + + + + + +
+
liblzma (XZ Utils) 5.6.0 +
+
+
+ + + + + +
+
+
+Data Structures | +Macros | +Enumerations | +Functions
+
lzma12.h File Reference
+
+
+ +

LZMA1 and LZMA2 filters. +More...

+ + + + + +

+Data Structures

struct  lzma_options_lzma
 Options specific to the LZMA1 and LZMA2 filters. More...
 
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+Macros

#define LZMA_FILTER_LZMA1   LZMA_VLI_C(0x4000000000000001)
 LZMA1 Filter ID (for raw encoder/decoder only, not in .xz)
 
#define LZMA_FILTER_LZMA1EXT   LZMA_VLI_C(0x4000000000000002)
 LZMA1 Filter ID with extended options (for raw encoder/decoder)
 
#define LZMA_FILTER_LZMA2   LZMA_VLI_C(0x21)
 LZMA2 Filter ID.
 
+#define LZMA_DICT_SIZE_MIN   UINT32_C(4096)
 
+#define LZMA_DICT_SIZE_DEFAULT   (UINT32_C(1) << 23)
 
+#define LZMA_LCLP_MIN   0
 
+#define LZMA_LCLP_MAX   4
 
+#define LZMA_LC_DEFAULT   3
 
+#define LZMA_LP_DEFAULT   0
 
+#define LZMA_PB_MIN   0
 
+#define LZMA_PB_MAX   4
 
+#define LZMA_PB_DEFAULT   2
 
+#define LZMA_LZMA1EXT_ALLOW_EOPM   UINT32_C(0x01)
 
#define lzma_set_ext_size(opt_lzma2, u64size)
 Macro to set the 64-bit uncompressed size in ext_size_*.
 
+ + + + + + + +

+Enumerations

enum  lzma_match_finder {
+  LZMA_MF_HC3 = 0x03 +, LZMA_MF_HC4 = 0x04 +, LZMA_MF_BT2 = 0x12 +, LZMA_MF_BT3 = 0x13 +,
+  LZMA_MF_BT4 = 0x14 +
+ }
 Match finders. More...
 
enum  lzma_mode { LZMA_MODE_FAST = 1 +, LZMA_MODE_NORMAL = 2 + }
 Compression modes. More...
 
+ + + + + + + + + + +

+Functions

lzma_bool lzma_mf_is_supported (lzma_match_finder match_finder) lzma_nothrow lzma_attr_const
 Test if given match finder is supported.
 
lzma_bool lzma_mode_is_supported (lzma_mode mode) lzma_nothrow lzma_attr_const
 Test if given compression mode is supported.
 
lzma_bool lzma_lzma_preset (lzma_options_lzma *options, uint32_t preset) lzma_nothrow
 Set a compression preset to lzma_options_lzma structure.
 
+

Detailed Description

+

LZMA1 and LZMA2 filters.

+
Note
Never include this file directly. Use <lzma.h> instead.
+

Macro Definition Documentation

+ +

◆ LZMA_FILTER_LZMA1

+ +
+
+ + + + +
#define LZMA_FILTER_LZMA1   LZMA_VLI_C(0x4000000000000001)
+
+ +

LZMA1 Filter ID (for raw encoder/decoder only, not in .xz)

+

LZMA1 is the very same thing as what was called just LZMA in LZMA Utils, 7-Zip, and LZMA SDK. It's called LZMA1 here to prevent developers from accidentally using LZMA when they actually want LZMA2.

+ +
+
+ +

◆ LZMA_FILTER_LZMA1EXT

+ +
+
+ + + + +
#define LZMA_FILTER_LZMA1EXT   LZMA_VLI_C(0x4000000000000002)
+
+ +

LZMA1 Filter ID with extended options (for raw encoder/decoder)

+

This is like LZMA_FILTER_LZMA1 but with this ID a few extra options are supported in the lzma_options_lzma structure:

+
    +
  • A flag to tell the encoder if the end of payload marker (EOPM) alias end of stream (EOS) marker must be written at the end of the stream. In contrast, LZMA_FILTER_LZMA1 always writes the end marker.
    • +
  • Decoder needs to be told the uncompressed size of the stream or that it is unknown (using the special value UINT64_MAX). If the size is known, a flag can be set to allow the presence of the end marker anyway. In contrast, LZMA_FILTER_LZMA1 always behaves as if the uncompressed size was unknown.
    • +
+

This allows handling file formats where LZMA1 streams are used but where the end marker isn't allowed or where it might not (always) be present. This extended LZMA1 functionality is provided as a Filter ID for raw encoder and decoder instead of adding new encoder and decoder initialization functions because this way it is possible to also use extra filters, for example, LZMA_FILTER_X86 in a filter chain with LZMA_FILTER_LZMA1EXT, which might be needed to handle some file formats.

+ +
+
+ +

◆ LZMA_FILTER_LZMA2

+ +
+
+ + + + +
#define LZMA_FILTER_LZMA2   LZMA_VLI_C(0x21)
+
+ +

LZMA2 Filter ID.

+

Usually you want this instead of LZMA1. Compared to LZMA1, LZMA2 adds support for LZMA_SYNC_FLUSH, uncompressed chunks (smaller expansion when trying to compress incompressible data), possibility to change lc/lp/pb in the middle of encoding, and some other internal improvements.

+ +
+
+ +

◆ lzma_set_ext_size

+ +
+
+ + + + + + + + + + + + + + + + + + +
#define lzma_set_ext_size( opt_lzma2,
 u64size 
)
+
+Value:
do { \
+
(opt_lzma2).ext_size_low = (uint32_t)(u64size); \
+
(opt_lzma2).ext_size_high = (uint32_t)((uint64_t)(u64size) >> 32); \
+
} while (0)
+
+

Macro to set the 64-bit uncompressed size in ext_size_*.

+

This might be convenient when decoding using LZMA_FILTER_LZMA1EXT. This isn't used with LZMA_FILTER_LZMA1 or LZMA_FILTER_LZMA2.

+ +
+
+

Enumeration Type Documentation

+ +

◆ lzma_match_finder

+ +
+
+ + + + +
enum lzma_match_finder
+
+ +

Match finders.

+

Match finder has major effect on both speed and compression ratio. Usually hash chains are faster than binary trees.

+

If you will use LZMA_SYNC_FLUSH often, the hash chains may be a better choice, because binary trees get much higher compression ratio penalty with LZMA_SYNC_FLUSH.

+

The memory usage formulas are only rough estimates, which are closest to reality when dict_size is a power of two. The formulas are more complex in reality, and can also change a little between liblzma versions. Use lzma_raw_encoder_memusage() to get more accurate estimate of memory usage.

+ + + + + + +
Enumerator
LZMA_MF_HC3 

Hash Chain with 2- and 3-byte hashing.

+

Minimum nice_len: 3

+

Memory usage:

    +
  • dict_size <= 16 MiB: dict_size * 7.5
    • +
  • dict_size > 16 MiB: dict_size * 5.5 + 64 MiB
    • +
+
LZMA_MF_HC4 

Hash Chain with 2-, 3-, and 4-byte hashing.

+

Minimum nice_len: 4

+

Memory usage:

    +
  • dict_size <= 32 MiB: dict_size * 7.5
    • +
  • dict_size > 32 MiB: dict_size * 6.5
    • +
+
LZMA_MF_BT2 

Binary Tree with 2-byte hashing.

+

Minimum nice_len: 2

+

Memory usage: dict_size * 9.5

+
LZMA_MF_BT3 

Binary Tree with 2- and 3-byte hashing.

+

Minimum nice_len: 3

+

Memory usage:

    +
  • dict_size <= 16 MiB: dict_size * 11.5
    • +
  • dict_size > 16 MiB: dict_size * 9.5 + 64 MiB
    • +
+
LZMA_MF_BT4 

Binary Tree with 2-, 3-, and 4-byte hashing.

+

Minimum nice_len: 4

+

Memory usage:

    +
  • dict_size <= 32 MiB: dict_size * 11.5
    • +
  • dict_size > 32 MiB: dict_size * 10.5
    • +
+
+ +
+
+ +

◆ lzma_mode

+ +
+
+ + + + +
enum lzma_mode
+
+ +

Compression modes.

+

This selects the function used to analyze the data produced by the match finder.

+ + + +
Enumerator
LZMA_MODE_FAST 

Fast compression.

+

Fast mode is usually at its best when combined with a hash chain match finder.

+
LZMA_MODE_NORMAL 

Normal compression.

+

This is usually notably slower than fast mode. Use this together with binary tree match finders to expose the full potential of the LZMA1 or LZMA2 encoder.

+
+ +
+
+

Function Documentation

+ +

◆ lzma_mf_is_supported()

+ +
+
+ + + + + +
+ + + + + + + + +
lzma_bool lzma_mf_is_supported (lzma_match_finder match_finder) const
+ 		+extern
+
+ +

Test if given match finder is supported.

+

It is safe to call this with a value that isn't listed in lzma_match_finder enumeration; the return value will be false.

+

There is no way to list which match finders are available in this particular liblzma version and build. It would be useless, because a new match finder, which the application developer wasn't aware, could require giving additional options to the encoder that the older match finders don't need.

+
Parameters
+ + +
match_finderMatch finder ID
+
+
+
Returns
lzma_bool:
    +
  • true if the match finder is supported by this liblzma build.
    • +
  • false otherwise.
    • +
+
+ +
+
+ +

◆ lzma_mode_is_supported()

+ +
+
+ + + + + +
+ + + + + + + + +
lzma_bool lzma_mode_is_supported (lzma_mode mode) const
+ 		+extern
+
+ +

Test if given compression mode is supported.

+

It is safe to call this with a value that isn't listed in lzma_mode enumeration; the return value will be false.

+

There is no way to list which modes are available in this particular liblzma version and build. It would be useless, because a new compression mode, which the application developer wasn't aware, could require giving additional options to the encoder that the older modes don't need.

+
Parameters
+ + +
modeMode ID.
+
+
+
Returns
lzma_bool:
    +
  • true if the compression mode is supported by this liblzma build.
    • +
  • false otherwise.
    • +
+
+ +
+
+ +

◆ lzma_lzma_preset()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + +
lzma_bool lzma_lzma_preset (lzma_options_lzma * options,
uint32_t preset 
)
+ 		+extern
+
+ +

Set a compression preset to lzma_options_lzma structure.

+

0 is the fastest and 9 is the slowest. These match the switches -0 .. -9 of the xz command line tool. In addition, it is possible to bitwise-or flags to the preset. Currently only LZMA_PRESET_EXTREME is supported. The flags are defined in container.h, because the flags are used also with lzma_easy_encoder().

+

The preset levels are subject to changes between liblzma versions.

+

This function is available only if LZMA1 or LZMA2 encoder has been enabled when building liblzma.

+

If features (like certain match finders) have been disabled at build time, then the function may return success (false) even though the resulting LZMA1/LZMA2 options may not be usable for encoder initialization (LZMA_OPTIONS_ERROR).

+
Parameters
+ + + +
[out]optionsPointer to LZMA1 or LZMA2 options to be filled
presetPreset level bitwse-ORed with preset flags
+
+
+
Returns
lzma_bool:
    +
  • true if the preset is not supported (failure).
    • +
  • false otherwise (success).
    • +
+
+ +
+
+
+
+

+ XZ logo © 2023 by Jia Tan is licensed under + + CC BY-SA 4.0 + +

+ + diff --git a/doc/api/lzma_8h.html b/doc/api/lzma_8h.html new file mode 100644 index 00000000..f0eb486b --- /dev/null +++ b/doc/api/lzma_8h.html @@ -0,0 +1,115 @@ + + + + + + + +liblzma (XZ Utils): lzma.h File Reference + + + + + + +
+
+ + + + + + + +
+
liblzma (XZ Utils) 5.6.0 +
+
+
+ + + + +
+
+
+Macros
+
lzma.h File Reference
+
+
+ +

The public API of liblzma data compression library. +More...

+
#include <stddef.h>
+#include <inttypes.h>
+#include <limits.h>
+#include "lzma/version.h"
+#include "lzma/base.h"
+#include "lzma/vli.h"
+#include "lzma/check.h"
+#include "lzma/filter.h"
+#include "lzma/bcj.h"
+#include "lzma/delta.h"
+#include "lzma/lzma12.h"
+#include "lzma/container.h"
+#include "lzma/stream_flags.h"
+#include "lzma/block.h"
+#include "lzma/index.h"
+#include "lzma/index_hash.h"
+#include "lzma/hardware.h"
+
+ + + + + + + + + + + + + + + + + + + +

+Macros

+#define UINT32_C(n)   n ## U
 
+#define UINT64_C(n)   n ## UL
 
+#define UINT32_MAX   (UINT32_C(4294967295))
 
+#define UINT64_MAX   (UINT64_C(18446744073709551615))
 
+#define lzma_nothrow
 
+#define lzma_attr_pure   lzma_attribute((__pure__))
 
+#define lzma_attr_const   lzma_attribute((__const__))
 
+#define lzma_attr_warn_unused_result    lzma_attribute((__warn_unused_result__))
 
+#define LZMA_H_INTERNAL   1
 
+

Detailed Description

+

The public API of liblzma data compression library.

+
+
+

+ XZ logo © 2023 by Jia Tan is licensed under + + CC BY-SA 4.0 + +

+ + diff --git a/doc/api/minus.svg b/doc/api/minus.svg new file mode 100644 index 00000000..f70d0c1a --- /dev/null +++ b/doc/api/minus.svg @@ -0,0 +1,8 @@ + + + + + + + + diff --git a/doc/api/minusd.svg b/doc/api/minusd.svg new file mode 100644 index 00000000..5f8e8796 --- /dev/null +++ b/doc/api/minusd.svg @@ -0,0 +1,8 @@ + + + + + + + + diff --git a/doc/api/nav_f.png b/doc/api/nav_f.png new file mode 100644 index 00000000..113913ea Binary files /dev/null and b/doc/api/nav_f.png differ diff --git a/doc/api/nav_fd.png b/doc/api/nav_fd.png new file mode 100644 index 00000000..978df01c Binary files /dev/null and b/doc/api/nav_fd.png differ diff --git a/doc/api/nav_g.png b/doc/api/nav_g.png new file mode 100644 index 00000000..2093a237 Binary files /dev/null and b/doc/api/nav_g.png differ diff --git a/doc/api/nav_h.png b/doc/api/nav_h.png new file mode 100644 index 00000000..4e34efd8 Binary files /dev/null and b/doc/api/nav_h.png differ diff --git a/doc/api/nav_hd.png b/doc/api/nav_hd.png new file mode 100644 index 00000000..b717d931 Binary files /dev/null and b/doc/api/nav_hd.png differ diff --git a/doc/api/open.png b/doc/api/open.png new file mode 100644 index 00000000..b4e49d8d Binary files /dev/null and b/doc/api/open.png differ diff --git a/doc/api/plus.svg b/doc/api/plus.svg new file mode 100644 index 00000000..07520165 --- /dev/null +++ b/doc/api/plus.svg @@ -0,0 +1,9 @@ + + + + + + + + + diff --git a/doc/api/plusd.svg b/doc/api/plusd.svg new file mode 100644 index 00000000..0c65bfe9 --- /dev/null +++ b/doc/api/plusd.svg @@ -0,0 +1,9 @@ + + + + + + + + + diff --git a/doc/api/splitbar.png b/doc/api/splitbar.png new file mode 100644 index 00000000..ee781cf3 Binary files /dev/null and b/doc/api/splitbar.png differ diff --git a/doc/api/splitbard.png b/doc/api/splitbard.png new file mode 100644 index 00000000..aa4d0290 Binary files /dev/null and b/doc/api/splitbard.png differ diff --git a/doc/api/stream__flags_8h.html b/doc/api/stream__flags_8h.html new file mode 100644 index 00000000..4ea53748 --- /dev/null +++ b/doc/api/stream__flags_8h.html @@ -0,0 +1,394 @@ + + + + + + + +liblzma (XZ Utils): lzma/stream_flags.h File Reference + + + + + + +
+
+ + + + + + + +
+
liblzma (XZ Utils) 5.6.0 +
+
+
+ + + + + +
+
+
+Data Structures | +Macros | +Functions
+
stream_flags.h File Reference
+
+
+ +

.xz Stream Header and Stream Footer encoder and decoder +More...

+ + + + + +

+Data Structures

struct  lzma_stream_flags
 Options for encoding/decoding Stream Header and Stream Footer. More...
 
+ + + + + + + + + + +

+Macros

#define LZMA_STREAM_HEADER_SIZE   12
 Size of Stream Header and Stream Footer.
 
+#define LZMA_BACKWARD_SIZE_MIN   4
 Minimum value for lzma_stream_flags.backward_size.
 
+#define LZMA_BACKWARD_SIZE_MAX   (LZMA_VLI_C(1) << 34)
 Maximum value for lzma_stream_flags.backward_size.
 
+ + + + + + + + + + + + + + + + +

+Functions

lzma_ret lzma_stream_header_encode (const lzma_stream_flags *options, uint8_t *out) lzma_nothrow lzma_attr_warn_unused_result
 Encode Stream Header.
 
lzma_ret lzma_stream_footer_encode (const lzma_stream_flags *options, uint8_t *out) lzma_nothrow lzma_attr_warn_unused_result
 Encode Stream Footer.
 
lzma_ret lzma_stream_header_decode (lzma_stream_flags *options, const uint8_t *in) lzma_nothrow lzma_attr_warn_unused_result
 Decode Stream Header.
 
lzma_ret lzma_stream_footer_decode (lzma_stream_flags *options, const uint8_t *in) lzma_nothrow lzma_attr_warn_unused_result
 Decode Stream Footer.
 
lzma_ret lzma_stream_flags_compare (const lzma_stream_flags *a, const lzma_stream_flags *b) lzma_nothrow lzma_attr_pure
 Compare two lzma_stream_flags structures.
 
+

Detailed Description

+

.xz Stream Header and Stream Footer encoder and decoder

+
Note
Never include this file directly. Use <lzma.h> instead.
+

Macro Definition Documentation

+ +

◆ LZMA_STREAM_HEADER_SIZE

+ +
+
+ + + + +
#define LZMA_STREAM_HEADER_SIZE   12
+
+ +

Size of Stream Header and Stream Footer.

+

Stream Header and Stream Footer have the same size and they are not going to change even if a newer version of the .xz file format is developed in future.

+ +
+
+

Function Documentation

+ +

◆ lzma_stream_header_encode()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + +
lzma_ret lzma_stream_header_encode (const lzma_stream_flags * options,
uint8_t * out 
)
+ 		+extern
+
+ +

Encode Stream Header.

+
Parameters
+ + + +
optionsStream Header options to be encoded. options->backward_size is ignored and doesn't need to be initialized.
[out]outBeginning of the output buffer of LZMA_STREAM_HEADER_SIZE bytes.
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: Encoding was successful.
    • +
  • LZMA_OPTIONS_ERROR: options->version is not supported by this liblzma version.
    • +
  • LZMA_PROG_ERROR: Invalid options.
    • +
+
+ +
+
+ +

◆ lzma_stream_footer_encode()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + +
lzma_ret lzma_stream_footer_encode (const lzma_stream_flags * options,
uint8_t * out 
)
+ 		+extern
+
+ +

Encode Stream Footer.

+
Parameters
+ + + +
optionsStream Footer options to be encoded.
[out]outBeginning of the output buffer of LZMA_STREAM_HEADER_SIZE bytes.
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: Encoding was successful.
    • +
  • LZMA_OPTIONS_ERROR: options->version is not supported by this liblzma version.
    • +
  • LZMA_PROG_ERROR: Invalid options.
    • +
+
+ +
+
+ +

◆ lzma_stream_header_decode()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + +
lzma_ret lzma_stream_header_decode (lzma_stream_flags * options,
const uint8_t * in 
)
+ 		+extern
+
+ +

Decode Stream Header.

+

options->backward_size is always set to LZMA_VLI_UNKNOWN. This is to help comparing Stream Flags from Stream Header and Stream Footer with lzma_stream_flags_compare().

+
Note
When decoding .xz files that contain multiple Streams, it may make sense to print "file format not recognized" only if decoding of the Stream Header of the first Stream gives LZMA_FORMAT_ERROR. If non-first Stream Header gives LZMA_FORMAT_ERROR, the message used for LZMA_DATA_ERROR is probably more appropriate. For example, the Stream decoder in liblzma uses LZMA_DATA_ERROR if LZMA_FORMAT_ERROR is returned by lzma_stream_header_decode() when decoding non-first Stream.
+
Parameters
+ + + +
[out]optionsTarget for the decoded Stream Header options.
inBeginning of the input buffer of LZMA_STREAM_HEADER_SIZE bytes.
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: Decoding was successful.
    • +
  • LZMA_FORMAT_ERROR: Magic bytes don't match, thus the given buffer cannot be Stream Header.
    • +
  • LZMA_DATA_ERROR: CRC32 doesn't match, thus the header is corrupt.
    • +
  • LZMA_OPTIONS_ERROR: Unsupported options are present in the header.
    • +
+
+ +
+
+ +

◆ lzma_stream_footer_decode()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + +
lzma_ret lzma_stream_footer_decode (lzma_stream_flags * options,
const uint8_t * in 
)
+ 		+extern
+
+ +

Decode Stream Footer.

+
Note
If Stream Header was already decoded successfully, but decoding Stream Footer returns LZMA_FORMAT_ERROR, the application should probably report some other error message than "file format not recognized". The file likely is corrupt (possibly truncated). The Stream decoder in liblzma uses LZMA_DATA_ERROR in this situation.
+
Parameters
+ + + +
[out]optionsTarget for the decoded Stream Footer options.
inBeginning of the input buffer of LZMA_STREAM_HEADER_SIZE bytes.
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: Decoding was successful.
    • +
  • LZMA_FORMAT_ERROR: Magic bytes don't match, thus the given buffer cannot be Stream Footer.
    • +
  • LZMA_DATA_ERROR: CRC32 doesn't match, thus the Stream Footer is corrupt.
    • +
  • LZMA_OPTIONS_ERROR: Unsupported options are present in Stream Footer.
    • +
+
+ +
+
+ +

◆ lzma_stream_flags_compare()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + +
lzma_ret lzma_stream_flags_compare (const lzma_stream_flags * a,
const lzma_stream_flags * b 
)
+ 		+extern
+
+ +

Compare two lzma_stream_flags structures.

+

backward_size values are compared only if both are not LZMA_VLI_UNKNOWN.

+
Parameters
+ + + +
aPointer to lzma_stream_flags structure
bPointer to lzma_stream_flags structure
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: Both are equal. If either had backward_size set to LZMA_VLI_UNKNOWN, backward_size values were not compared or validated.
    • +
  • LZMA_DATA_ERROR: The structures differ.
    • +
  • LZMA_OPTIONS_ERROR: version in either structure is greater than the maximum supported version (currently zero).
    • +
  • LZMA_PROG_ERROR: Invalid value, e.g. invalid check or backward_size.
    • +
+
+ +
+
+
+
+

+ XZ logo © 2023 by Jia Tan is licensed under + + CC BY-SA 4.0 + +

+ + diff --git a/doc/api/structlzma__allocator.html b/doc/api/structlzma__allocator.html new file mode 100644 index 00000000..db809c9e --- /dev/null +++ b/doc/api/structlzma__allocator.html @@ -0,0 +1,159 @@ + + + + + + + +liblzma (XZ Utils): lzma_allocator Struct Reference + + + + + + +
+
+ + + + + + + +
+
liblzma (XZ Utils) 5.6.0 +
+
+
+ + + + +
+
+
+Data Fields
+
lzma_allocator Struct Reference
+
+
+ +

Custom functions for memory handling. + More...

+ +

#include <base.h>

+ + + + + + + + + + + +

+Data Fields

void *(* alloc )(void *opaque, size_t nmemb, size_t size)
 Pointer to a custom memory allocation function.
 
void(* free )(void *opaque, void *ptr)
 Pointer to a custom memory freeing function.
 
void * opaque
 Pointer passed to .alloc() and .free()
 
+

Detailed Description

+

Custom functions for memory handling.

+

A pointer to lzma_allocator may be passed via lzma_stream structure to liblzma, and some advanced functions take a pointer to lzma_allocator as a separate function argument. The library will use the functions specified in lzma_allocator for memory handling instead of the default malloc() and free(). C++ users should note that the custom memory handling functions must not throw exceptions.

+

Single-threaded mode only: liblzma doesn't make an internal copy of lzma_allocator. Thus, it is OK to change these function pointers in the middle of the coding process, but obviously it must be done carefully to make sure that the replacement 'free' can deallocate memory allocated by the earlier 'alloc' function(s).

+

Multithreaded mode: liblzma might internally store pointers to the lzma_allocator given via the lzma_stream structure. The application must not change the allocator pointer in lzma_stream or the contents of the pointed lzma_allocator structure until lzma_end() has been used to free the memory associated with that lzma_stream. The allocation functions might be called simultaneously from multiple threads, and thus they must be thread safe.

+

Field Documentation

+ +

◆ alloc

+ +
+
+ + + + +
void *(* lzma_allocator::alloc) (void *opaque, size_t nmemb, size_t size)
+
+ +

Pointer to a custom memory allocation function.

+

If you don't want a custom allocator, but still want custom free(), set this to NULL and liblzma will use the standard malloc().

+
Parameters
+ + + + +
opaquelzma_allocator.opaque (see below)
nmembNumber of elements like in calloc(). liblzma will always set nmemb to 1, so it is safe to ignore nmemb in a custom allocator if you like. The nmemb argument exists only for compatibility with zlib and libbzip2.
sizeSize of an element in bytes. liblzma never sets this to zero.
+
+
+
Returns
Pointer to the beginning of a memory block of 'size' bytes, or NULL if allocation fails for some reason. When allocation fails, functions of liblzma return LZMA_MEM_ERROR.
+

The allocator should not waste time zeroing the allocated buffers. This is not only about speed, but also memory usage, since the operating system kernel doesn't necessarily allocate the requested memory in physical memory until it is actually used. With small input files, liblzma may actually need only a fraction of the memory that it requested for allocation.

+
Note
LZMA_MEM_ERROR is also used when the size of the allocation would be greater than SIZE_MAX. Thus, don't assume that the custom allocator must have returned NULL if some function from liblzma returns LZMA_MEM_ERROR.
+ +
+
+ +

◆ free

+ +
+
+ + + + +
void(* lzma_allocator::free) (void *opaque, void *ptr)
+
+ +

Pointer to a custom memory freeing function.

+

If you don't want a custom freeing function, but still want a custom allocator, set this to NULL and liblzma will use the standard free().

+
Parameters
+ + + +
opaquelzma_allocator.opaque (see below)
ptrPointer returned by lzma_allocator.alloc(), or when it is set to NULL, a pointer returned by the standard malloc().
+
+
+ +
+
+ +

◆ opaque

+ +
+
+ + + + +
void* lzma_allocator::opaque
+
+ +

Pointer passed to .alloc() and .free()

+

opaque is passed as the first argument to lzma_allocator.alloc() and lzma_allocator.free(). This intended to ease implementing custom memory allocation functions for use with liblzma.

+

If you don't need this, you should set this to NULL.

+ +
+
+
The documentation for this struct was generated from the following file: +
+
+

+ XZ logo © 2023 by Jia Tan is licensed under + + CC BY-SA 4.0 + +

+ + diff --git a/doc/api/structlzma__block.html b/doc/api/structlzma__block.html new file mode 100644 index 00000000..54d6dc6b --- /dev/null +++ b/doc/api/structlzma__block.html @@ -0,0 +1,353 @@ + + + + + + + +liblzma (XZ Utils): lzma_block Struct Reference + + + + + + +
+
+ + + + + + + +
+
liblzma (XZ Utils) 5.6.0 +
+
+
+ + + + +
+
+
+Data Fields
+
lzma_block Struct Reference
+
+
+ +

Options for the Block and Block Header encoders and decoders. + More...

+ +

#include <block.h>

+ + + + + + + + + + + + + + + + + + + + + + + + + + +

+Data Fields

uint32_t version
 Block format version.
 
uint32_t header_size
 Size of the Block Header field in bytes.
 
lzma_check check
 Type of integrity Check.
 
lzma_vli compressed_size
 Size of the Compressed Data in bytes.
 
lzma_vli uncompressed_size
 Uncompressed Size in bytes.
 
lzma_filter * filters
 Array of filters.
 
uint8_t raw_check [LZMA_CHECK_SIZE_MAX]
 Raw value stored in the Check field.
 
lzma_bool ignore_check
 A flag to Block decoder to not verify the Check field.
 
+

Detailed Description

+

Options for the Block and Block Header encoders and decoders.

+

Different Block handling functions use different parts of this structure. Some read some members, other functions write, and some do both. Only the members listed for reading need to be initialized when the specified functions are called. The members marked for writing will be assigned new values at some point either by calling the given function or by later calls to lzma_code().

+

Field Documentation

+ +

◆ version

+ +
+
+ + + + +
uint32_t lzma_block::version
+
+ +

Block format version.

+

To prevent API and ABI breakages when new features are needed, a version number is used to indicate which members in this structure are in use:

    +
  • liblzma >= 5.0.0: version = 0 is supported.
    • +
  • liblzma >= 5.1.4beta: Support for version = 1 was added, which adds the ignore_check member.
    • +
+

If version is greater than one, most Block related functions will return LZMA_OPTIONS_ERROR (lzma_block_header_decode() works with any version value).

+

Read by:

+

Written by:

+ +
+
+ +

◆ header_size

+ +
+
+ + + + +
uint32_t lzma_block::header_size
+
+ +

Size of the Block Header field in bytes.

+

This is always a multiple of four.

+

Read by:

+

Written by:

+ +
+
+ +

◆ check

+ +
+
+ + + + +
lzma_check lzma_block::check
+
+ +

Type of integrity Check.

+

The Check ID is not stored into the Block Header, thus its value must be provided also when decoding.

+

Read by:

+ +
+
+ +

◆ compressed_size

+ +
+
+ + + + +
lzma_vli lzma_block::compressed_size
+
+ +

Size of the Compressed Data in bytes.

+

Encoding: If this is not LZMA_VLI_UNKNOWN, Block Header encoder will store this value to the Block Header. Block encoder doesn't care about this value, but will set it once the encoding has been finished.

+

Decoding: If this is not LZMA_VLI_UNKNOWN, Block decoder will verify that the size of the Compressed Data field matches compressed_size.

+

Usually you don't know this value when encoding in streamed mode, and thus cannot write this field into the Block Header.

+

In non-streamed mode you can reserve space for this field before encoding the actual Block. After encoding the data, finish the Block by encoding the Block Header. Steps in detail:

+
    +
  • Set compressed_size to some big enough value. If you don't know better, use LZMA_VLI_MAX, but remember that bigger values take more space in Block Header.
    • +
  • Call lzma_block_header_size() to see how much space you need to reserve for the Block Header.
    • +
  • Encode the Block using lzma_block_encoder() and lzma_code(). It sets compressed_size to the correct value.
    • +
  • Use lzma_block_header_encode() to encode the Block Header. Because space was reserved in the first step, you don't need to call lzma_block_header_size() anymore, because due to reserving, header_size has to be big enough. If it is "too big", lzma_block_header_encode() will add enough Header Padding to make Block Header to match the size specified by header_size.
    • +
+

Read by:

+

Written by:

+ +
+
+ +

◆ uncompressed_size

+ +
+
+ + + + +
lzma_vli lzma_block::uncompressed_size
+
+ +

Uncompressed Size in bytes.

+

This is handled very similarly to compressed_size above.

+

uncompressed_size is needed by fewer functions than compressed_size. This is because uncompressed_size isn't needed to validate that Block stays within proper limits.

+

Read by:

+

Written by:

+ +
+
+ +

◆ filters

+ +
+
+ + + + +
lzma_filter* lzma_block::filters
+
+ +

Array of filters.

+

There can be 1-4 filters. The end of the array is marked with .id = LZMA_VLI_UNKNOWN.

+

Read by:

+

Written by:

    +
  • lzma_block_header_decode(): Note that this does NOT free() the old filter options structures. All unused filters[] will have .id == LZMA_VLI_UNKNOWN and .options == NULL. If decoding fails, all filters[] are guaranteed to be LZMA_VLI_UNKNOWN and NULL.
    • +
+
Note
Because of the array is terminated with .id = LZMA_VLI_UNKNOWN, the actual array must have LZMA_FILTERS_MAX + 1 members or the Block Header decoder will overflow the buffer.
+ +
+
+ +

◆ raw_check

+ +
+
+ + + + +
uint8_t lzma_block::raw_check[LZMA_CHECK_SIZE_MAX]
+
+ +

Raw value stored in the Check field.

+

After successful coding, the first lzma_check_size(check) bytes of this array contain the raw value stored in the Check field.

+

Note that CRC32 and CRC64 are stored in little endian byte order. Take it into account if you display the Check values to the user.

+

Written by:

+ +
+
+ +

◆ ignore_check

+ +
+
+ + + + +
lzma_bool lzma_block::ignore_check
+
+ +

A flag to Block decoder to not verify the Check field.

+

This member is supported by liblzma >= 5.1.4beta if .version >= 1.

+

If this is set to true, the integrity check won't be calculated and verified. Unless you know what you are doing, you should leave this to false. (A reason to set this to true is when the file integrity is verified externally anyway and you want to speed up the decompression, which matters mostly when using SHA-256 as the integrity check.)

+

If .version >= 1, read by:

+

Written by (.version is ignored):

+ +
+
+
The documentation for this struct was generated from the following file: +
+
+

+ XZ logo © 2023 by Jia Tan is licensed under + + CC BY-SA 4.0 + +

+ + diff --git a/doc/api/structlzma__filter.html b/doc/api/structlzma__filter.html new file mode 100644 index 00000000..7affbd0a --- /dev/null +++ b/doc/api/structlzma__filter.html @@ -0,0 +1,120 @@ + + + + + + + +liblzma (XZ Utils): lzma_filter Struct Reference + + + + + + +
+
+ + + + + + + +
+
liblzma (XZ Utils) 5.6.0 +
+
+
+ + + + +
+
+
+Data Fields
+
lzma_filter Struct Reference
+
+
+ +

Filter options. + More...

+ +

#include <filter.h>

+ + + + + + + + +

+Data Fields

lzma_vli id
 Filter ID.
 
void * options
 Pointer to filter-specific options structure.
 
+

Detailed Description

+

Filter options.

+

This structure is used to pass a Filter ID and a pointer to the filter's options to liblzma. A few functions work with a single lzma_filter structure, while most functions expect a filter chain.

+

A filter chain is indicated with an array of lzma_filter structures. The array is terminated with .id = LZMA_VLI_UNKNOWN. Thus, the filter array must have LZMA_FILTERS_MAX + 1 elements (that is, five) to be able to hold any arbitrary filter chain. This is important when using lzma_block_header_decode() from block.h, because a filter array that is too small would make liblzma write past the end of the array.

+

Field Documentation

+ +

◆ id

+ +
+
+ + + + +
lzma_vli lzma_filter::id
+
+ +

Filter ID.

+

Use constants whose name begin with 'LZMA_FILTER_' to specify different filters. In an array of lzma_filter structures, use LZMA_VLI_UNKNOWN to indicate end of filters.

+
Note
This is not an enum, because on some systems enums cannot be 64-bit.
+ +
+
+ +

◆ options

+ +
+
+ + + + +
void* lzma_filter::options
+
+ +

Pointer to filter-specific options structure.

+

If the filter doesn't need options, set this to NULL. If id is set to LZMA_VLI_UNKNOWN, options is ignored, and thus doesn't need be initialized.

+ +
+
+
The documentation for this struct was generated from the following file: +
+
+

+ XZ logo © 2023 by Jia Tan is licensed under + + CC BY-SA 4.0 + +

+ + diff --git a/doc/api/structlzma__index__iter.html b/doc/api/structlzma__index__iter.html new file mode 100644 index 00000000..f7d140da --- /dev/null +++ b/doc/api/structlzma__index__iter.html @@ -0,0 +1,413 @@ + + + + + + + +liblzma (XZ Utils): lzma_index_iter Struct Reference + + + + + + +
+
+ + + + + + + +
+
liblzma (XZ Utils) 5.6.0 +
+
+
+ + + + +
+
+
+Data Fields
+
lzma_index_iter Struct Reference
+
+
+ +

Iterator to get information about Blocks and Streams. + More...

+ +

#include <index.h>

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+Data Fields

+struct { 
 
   const lzma_stream_flags *   flags 
 Pointer to Stream Flags. More...
 
   lzma_vli   number 
 Stream number in the lzma_index. More...
 
   lzma_vli   block_count 
 Number of Blocks in the Stream. More...
 
   lzma_vli   compressed_offset 
 Compressed start offset of this Stream. More...
 
   lzma_vli   uncompressed_offset 
 Uncompressed start offset of this Stream. More...
 
   lzma_vli   compressed_size 
 Compressed size of this Stream. More...
 
+   lzma_vli   uncompressed_size 
 Uncompressed size of this Stream.
 
   lzma_vli   padding 
 Size of Stream Padding after this Stream. More...
 
} stream 
 
+struct { 
 
   lzma_vli   number_in_file 
 Block number in the file. More...
 
   lzma_vli   compressed_file_offset 
 Compressed start offset of this Block. More...
 
   lzma_vli   uncompressed_file_offset 
 Uncompressed start offset of this Block. More...
 
   lzma_vli   number_in_stream 
 Block number in this Stream. More...
 
   lzma_vli   compressed_stream_offset 
 Compressed start offset of this Block. More...
 
   lzma_vli   uncompressed_stream_offset 
 Uncompressed start offset of this Block. More...
 
   lzma_vli   uncompressed_size 
 Uncompressed size of this Block. More...
 
   lzma_vli   unpadded_size 
 Unpadded size of this Block. More...
 
   lzma_vli   total_size 
 Total compressed size. More...
 
} block 
 
+

Detailed Description

+

Iterator to get information about Blocks and Streams.

+

Field Documentation

+ +

◆ flags

+ +
+
+ + + + +
const lzma_stream_flags* lzma_index_iter::flags
+
+ +

Pointer to Stream Flags.

+

This is NULL if Stream Flags have not been set for this Stream with lzma_index_stream_flags().

+ +
+
+ +

◆ number

+ +
+
+ + + + +
lzma_vli lzma_index_iter::number
+
+ +

Stream number in the lzma_index.

+

The first Stream is 1.

+ +
+
+ +

◆ block_count

+ +
+
+ + + + +
lzma_vli lzma_index_iter::block_count
+
+ +

Number of Blocks in the Stream.

+

If this is zero, the block structure below has undefined values.

+ +
+
+ +

◆ compressed_offset

+ +
+
+ + + + +
lzma_vli lzma_index_iter::compressed_offset
+
+ +

Compressed start offset of this Stream.

+

The offset is relative to the beginning of the lzma_index (i.e. usually the beginning of the .xz file).

+ +
+
+ +

◆ uncompressed_offset

+ +
+
+ + + + +
lzma_vli lzma_index_iter::uncompressed_offset
+
+ +

Uncompressed start offset of this Stream.

+

The offset is relative to the beginning of the lzma_index (i.e. usually the beginning of the .xz file).

+ +
+
+ +

◆ compressed_size

+ +
+
+ + + + +
lzma_vli lzma_index_iter::compressed_size
+
+ +

Compressed size of this Stream.

+

This includes all headers except the possible Stream Padding after this Stream.

+ +
+
+ +

◆ uncompressed_size

+ +
+
+ + + + +
lzma_vli lzma_index_iter::uncompressed_size
+
+ +

Uncompressed size of this Stream.

+

Uncompressed size of this Block.

+

You should pass this to the Block decoder if you will decode this Block. It will allow the Block decoder to validate the uncompressed size.

+ +
+
+ +

◆ padding

+ +
+
+ + + + +
lzma_vli lzma_index_iter::padding
+
+ +

Size of Stream Padding after this Stream.

+

If it hasn't been set with lzma_index_stream_padding(), this defaults to zero. Stream Padding is always a multiple of four bytes.

+ +
+
+ +

◆ number_in_file

+ +
+
+ + + + +
lzma_vli lzma_index_iter::number_in_file
+
+ +

Block number in the file.

+

The first Block is 1.

+ +
+
+ +

◆ compressed_file_offset

+ +
+
+ + + + +
lzma_vli lzma_index_iter::compressed_file_offset
+
+ +

Compressed start offset of this Block.

+

This offset is relative to the beginning of the lzma_index (i.e. usually the beginning of the .xz file). Normally this is where you should seek in the .xz file to start decompressing this Block.

+ +
+
+ +

◆ uncompressed_file_offset

+ +
+
+ + + + +
lzma_vli lzma_index_iter::uncompressed_file_offset
+
+ +

Uncompressed start offset of this Block.

+

This offset is relative to the beginning of the lzma_index (i.e. usually the beginning of the .xz file).

+

When doing random-access reading, it is possible that the target offset is not exactly at Block boundary. One will need to compare the target offset against uncompressed_file_offset or uncompressed_stream_offset, and possibly decode and throw away some amount of data before reaching the target offset.

+ +
+
+ +

◆ number_in_stream

+ +
+
+ + + + +
lzma_vli lzma_index_iter::number_in_stream
+
+ +

Block number in this Stream.

+

The first Block is 1.

+ +
+
+ +

◆ compressed_stream_offset

+ +
+
+ + + + +
lzma_vli lzma_index_iter::compressed_stream_offset
+
+ +

Compressed start offset of this Block.

+

This offset is relative to the beginning of the Stream containing this Block.

+ +
+
+ +

◆ uncompressed_stream_offset

+ +
+
+ + + + +
lzma_vli lzma_index_iter::uncompressed_stream_offset
+
+ +

Uncompressed start offset of this Block.

+

This offset is relative to the beginning of the Stream containing this Block.

+ +
+
+ +

◆ unpadded_size

+ +
+
+ + + + +
lzma_vli lzma_index_iter::unpadded_size
+
+ +

Unpadded size of this Block.

+

You should pass this to the Block decoder if you will decode this Block. It will allow the Block decoder to validate the unpadded size.

+ +
+
+ +

◆ total_size

+ +
+
+ + + + +
lzma_vli lzma_index_iter::total_size
+
+ +

Total compressed size.

+

This includes all headers and padding in this Block. This is useful if you need to know how many bytes the Block decoder will actually read.

+ +
+
+
The documentation for this struct was generated from the following file: +
+
+

+ XZ logo © 2023 by Jia Tan is licensed under + + CC BY-SA 4.0 + +

+ + diff --git a/doc/api/structlzma__mt.html b/doc/api/structlzma__mt.html new file mode 100644 index 00000000..106ceb5d --- /dev/null +++ b/doc/api/structlzma__mt.html @@ -0,0 +1,262 @@ + + + + + + + +liblzma (XZ Utils): lzma_mt Struct Reference + + + + + + +
+
+ + + + + + + +
+
liblzma (XZ Utils) 5.6.0 +
+
+
+ + + + +
+
+
+Data Fields
+
lzma_mt Struct Reference
+
+
+ +

Multithreading options. + More...

+ +

#include <container.h>

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+Data Fields

uint32_t flags
 Flags.
 
+uint32_t threads
 Number of worker threads to use.
 
uint64_t block_size
 Encoder only: Maximum uncompressed size of a Block.
 
uint32_t timeout
 Timeout to allow lzma_code() to return early.
 
uint32_t preset
 Encoder only: Compression preset.
 
const lzma_filter * filters
 Encoder only: Filter chain (alternative to a preset)
 
lzma_check check
 Encoder only: Integrity check type.
 
uint64_t memlimit_threading
 Memory usage limit to reduce the number of threads.
 
uint64_t memlimit_stop
 Memory usage limit that should never be exceeded.
 
+

Detailed Description

+

Multithreading options.

+

Field Documentation

+ +

◆ flags

+ +
+
+ + + + +
uint32_t lzma_mt::flags
+
+ +

Flags.

+

Set this to zero if no flags are wanted.

+

Encoder: No flags are currently supported.

+

Decoder: Bitwise-or of zero or more of the decoder flags:

    +
  • LZMA_TELL_NO_CHECK
    • +
  • LZMA_TELL_UNSUPPORTED_CHECK
    • +
  • LZMA_TELL_ANY_CHECK
    • +
  • LZMA_IGNORE_CHECK
    • +
  • LZMA_CONCATENATED
    • +
  • LZMA_FAIL_FAST
    • +
+ +
+
+ +

◆ block_size

+ +
+
+ + + + +
uint64_t lzma_mt::block_size
+
+ +

Encoder only: Maximum uncompressed size of a Block.

+

The encoder will start a new .xz Block every block_size bytes. Using LZMA_FULL_FLUSH or LZMA_FULL_BARRIER with lzma_code() the caller may tell liblzma to start a new Block earlier.

+

With LZMA2, a recommended block size is 2-4 times the LZMA2 dictionary size. With very small dictionaries, it is recommended to use at least 1 MiB block size for good compression ratio, even if this is more than four times the dictionary size. Note that these are only recommendations for typical use cases; feel free to use other values. Just keep in mind that using a block size less than the LZMA2 dictionary size is waste of RAM.

+

Set this to 0 to let liblzma choose the block size depending on the compression options. For LZMA2 it will be 3*dict_size or 1 MiB, whichever is more.

+

For each thread, about 3 * block_size bytes of memory will be allocated. This may change in later liblzma versions. If so, the memory usage will probably be reduced, not increased.

+ +
+
+ +

◆ timeout

+ +
+
+ + + + +
uint32_t lzma_mt::timeout
+
+ +

Timeout to allow lzma_code() to return early.

+

Multithreading can make liblzma consume input and produce output in a very bursty way: it may first read a lot of input to fill internal buffers, then no input or output occurs for a while.

+

In single-threaded mode, lzma_code() won't return until it has either consumed all the input or filled the output buffer. If this is done in multithreaded mode, it may cause a call lzma_code() to take even tens of seconds, which isn't acceptable in all applications.

+

To avoid very long blocking times in lzma_code(), a timeout (in milliseconds) may be set here. If lzma_code() would block longer than this number of milliseconds, it will return with LZMA_OK. Reasonable values are 100 ms or more. The xz command line tool uses 300 ms.

+

If long blocking times are acceptable, set timeout to a special value of 0. This will disable the timeout mechanism and will make lzma_code() block until all the input is consumed or the output buffer has been filled.

+
Note
Even with a timeout, lzma_code() might sometimes take a long time to return. No timing guarantees are made.
+ +
+
+ +

◆ preset

+ +
+
+ + + + +
uint32_t lzma_mt::preset
+
+ +

Encoder only: Compression preset.

+

The preset is set just like with lzma_easy_encoder(). The preset is ignored if filters below is non-NULL.

+ +
+
+ +

◆ filters

+ +
+
+ + + + +
const lzma_filter* lzma_mt::filters
+
+ +

Encoder only: Filter chain (alternative to a preset)

+

If this is NULL, the preset above is used. Otherwise the preset is ignored and the filter chain specified here is used.

+ +
+
+ +

◆ check

+ +
+
+ + + + +
lzma_check lzma_mt::check
+
+ +

Encoder only: Integrity check type.

+

See check.h for available checks. The xz command line tool defaults to LZMA_CHECK_CRC64, which is a good choice if you are unsure.

+ +
+
+ +

◆ memlimit_threading

+ +
+
+ + + + +
uint64_t lzma_mt::memlimit_threading
+
+ +

Memory usage limit to reduce the number of threads.

+

Encoder: Ignored.

+

Decoder:

+

If the number of threads has been set so high that more than memlimit_threading bytes of memory would be needed, the number of threads will be reduced so that the memory usage will not exceed memlimit_threading bytes. However, if memlimit_threading cannot be met even in single-threaded mode, then decoding will continue in single-threaded mode and memlimit_threading may be exceeded even by a large amount. That is, memlimit_threading will never make lzma_code() return LZMA_MEMLIMIT_ERROR. To truly cap the memory usage, see memlimit_stop below.

+

Setting memlimit_threading to UINT64_MAX or a similar huge value means that liblzma is allowed to keep the whole compressed file and the whole uncompressed file in memory in addition to the memory needed by the decompressor data structures used by each thread! In other words, a reasonable value limit must be set here or it will cause problems sooner or later. If you have no idea what a reasonable value could be, try lzma_physmem() / 4 as a starting point. Setting this limit will never prevent decompression of a file; this will only reduce the number of threads.

+

If memlimit_threading is greater than memlimit_stop, then the value of memlimit_stop will be used for both.

+ +
+
+ +

◆ memlimit_stop

+ +
+
+ + + + +
uint64_t lzma_mt::memlimit_stop
+
+ +

Memory usage limit that should never be exceeded.

+

Encoder: Ignored.

+

Decoder: If decompressing will need more than this amount of memory even in the single-threaded mode, then lzma_code() will return LZMA_MEMLIMIT_ERROR.

+ +
+
+
The documentation for this struct was generated from the following file: +
+
+

+ XZ logo © 2023 by Jia Tan is licensed under + + CC BY-SA 4.0 + +

+ + diff --git a/doc/api/structlzma__options__bcj.html b/doc/api/structlzma__options__bcj.html new file mode 100644 index 00000000..7d978c0b --- /dev/null +++ b/doc/api/structlzma__options__bcj.html @@ -0,0 +1,101 @@ + + + + + + + +liblzma (XZ Utils): lzma_options_bcj Struct Reference + + + + + + +
+
+ + + + + + + +
+
liblzma (XZ Utils) 5.6.0 +
+
+
+ + + + +
+
+
+Data Fields
+
lzma_options_bcj Struct Reference
+
+
+ +

Options for BCJ filters. + More...

+ +

#include <bcj.h>

+ + + + + +

+Data Fields

uint32_t start_offset
 Start offset for conversions.
 
+

Detailed Description

+

Options for BCJ filters.

+

The BCJ filters never change the size of the data. Specifying options for them is optional: if pointer to options is NULL, default value is used. You probably never need to specify options to BCJ filters, so just set the options pointer to NULL and be happy.

+

If options with non-default values have been specified when encoding, the same options must also be specified when decoding.

+
Note
At the moment, none of the BCJ filters support LZMA_SYNC_FLUSH. If LZMA_SYNC_FLUSH is specified, LZMA_OPTIONS_ERROR will be returned. If there is need, partial support for LZMA_SYNC_FLUSH can be added in future. Partial means that flushing would be possible only at offsets that are multiple of 2, 4, or 16 depending on the filter, except x86 which cannot be made to support LZMA_SYNC_FLUSH predictably.
+

Field Documentation

+ +

◆ start_offset

+ +
+
+ + + + +
uint32_t lzma_options_bcj::start_offset
+
+ +

Start offset for conversions.

+

This setting is useful only when the same filter is used _separately_ for multiple sections of the same executable file, and the sections contain cross-section branch/call/jump instructions. In that case it is beneficial to set the start offset of the non-first sections so that the relative addresses of the cross-section branch/call/jump instructions will use the same absolute addresses as in the first section.

+

When the pointer to options is NULL, the default value (zero) is used.

+ +
+
+
The documentation for this struct was generated from the following file: +
+
+

+ XZ logo © 2023 by Jia Tan is licensed under + + CC BY-SA 4.0 + +

+ + diff --git a/doc/api/structlzma__options__delta.html b/doc/api/structlzma__options__delta.html new file mode 100644 index 00000000..1c003e6a --- /dev/null +++ b/doc/api/structlzma__options__delta.html @@ -0,0 +1,119 @@ + + + + + + + +liblzma (XZ Utils): lzma_options_delta Struct Reference + + + + + + +
+
+ + + + + + + +
+
liblzma (XZ Utils) 5.6.0 +
+
+
+ + + + +
+
+
+Data Fields
+
lzma_options_delta Struct Reference
+
+
+ +

Options for the Delta filter. + More...

+ +

#include <delta.h>

+ + + + + + + +

+Data Fields

lzma_delta_type type
 
uint32_t dist
 Delta distance.
 
+

Detailed Description

+

Options for the Delta filter.

+

These options are needed by both encoder and decoder.

+

Field Documentation

+ +

◆ type

+ +
+
+ + + + +
lzma_delta_type lzma_options_delta::type
+
+

For now, this must always be LZMA_DELTA_TYPE_BYTE.

+ +
+
+ +

◆ dist

+ +
+
+ + + + +
uint32_t lzma_options_delta::dist
+
+ +

Delta distance.

+

With the only currently supported type, LZMA_DELTA_TYPE_BYTE, the distance is as bytes.

+

Examples:

    +
  • 16-bit stereo audio: distance = 4 bytes
    • +
  • 24-bit RGB image data: distance = 3 bytes
    • +
+ +
+
+
The documentation for this struct was generated from the following file: +
+
+

+ XZ logo © 2023 by Jia Tan is licensed under + + CC BY-SA 4.0 + +

+ + diff --git a/doc/api/structlzma__options__lzma.html b/doc/api/structlzma__options__lzma.html new file mode 100644 index 00000000..4b9d0779 --- /dev/null +++ b/doc/api/structlzma__options__lzma.html @@ -0,0 +1,369 @@ + + + + + + + +liblzma (XZ Utils): lzma_options_lzma Struct Reference + + + + + + +
+
+ + + + + + + +
+
liblzma (XZ Utils) 5.6.0 +
+
+
+ + + + +
+
+
+Data Fields
+
lzma_options_lzma Struct Reference
+
+
+ +

Options specific to the LZMA1 and LZMA2 filters. + More...

+ +

#include <lzma12.h>

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+Data Fields

uint32_t dict_size
 Dictionary size in bytes.
 
const uint8_t * preset_dict
 Pointer to an initial dictionary.
 
uint32_t preset_dict_size
 Size of the preset dictionary.
 
uint32_t lc
 Number of literal context bits.
 
uint32_t lp
 Number of literal position bits.
 
uint32_t pb
 Number of position bits.
 
lzma_mode mode
 
uint32_t nice_len
 Nice length of a match.
 
lzma_match_finder mf
 
uint32_t depth
 Maximum search depth in the match finder.
 
uint32_t ext_flags
 For LZMA_FILTER_LZMA1EXT: Extended flags.
 
uint32_t ext_size_low
 For LZMA_FILTER_LZMA1EXT: Uncompressed size (low bits)
 
uint32_t ext_size_high
 For LZMA_FILTER_LZMA1EXT: Uncompressed size (high bits)
 
+

Detailed Description

+

Options specific to the LZMA1 and LZMA2 filters.

+

Since LZMA1 and LZMA2 share most of the code, it's simplest to share the options structure too. For encoding, all but the reserved variables need to be initialized unless specifically mentioned otherwise. lzma_lzma_preset() can be used to get a good starting point.

+

For raw decoding, both LZMA1 and LZMA2 need dict_size, preset_dict, and preset_dict_size (if preset_dict != NULL). LZMA1 needs also lc, lp, and pb.

+

Field Documentation

+ +

◆ dict_size

+ +
+
+ + + + +
uint32_t lzma_options_lzma::dict_size
+
+ +

Dictionary size in bytes.

+

Dictionary size indicates how many bytes of the recently processed uncompressed data is kept in memory. One method to reduce size of the uncompressed data is to store distance-length pairs, which indicate what data to repeat from the dictionary buffer. Thus, the bigger the dictionary, the better the compression ratio usually is.

+

Maximum size of the dictionary depends on multiple things:

    +
  • Memory usage limit
    • +
  • Available address space (not a problem on 64-bit systems)
    • +
  • Selected match finder (encoder only)
    • +
+

Currently the maximum dictionary size for encoding is 1.5 GiB (i.e. (UINT32_C(1) << 30) + (UINT32_C(1) << 29)) even on 64-bit systems for certain match finder implementation reasons. In the future, there may be match finders that support bigger dictionaries.

+

Decoder already supports dictionaries up to 4 GiB - 1 B (i.e. UINT32_MAX), so increasing the maximum dictionary size of the encoder won't cause problems for old decoders.

+

Because extremely small dictionaries sizes would have unneeded overhead in the decoder, the minimum dictionary size is 4096 bytes.

+
Note
When decoding, too big dictionary does no other harm than wasting memory.
+ +
+
+ +

◆ preset_dict

+ +
+
+ + + + +
const uint8_t* lzma_options_lzma::preset_dict
+
+ +

Pointer to an initial dictionary.

+

It is possible to initialize the LZ77 history window using a preset dictionary. It is useful when compressing many similar, relatively small chunks of data independently from each other. The preset dictionary should contain typical strings that occur in the files being compressed. The most probable strings should be near the end of the preset dictionary.

+

This feature should be used only in special situations. For now, it works correctly only with raw encoding and decoding. Currently none of the container formats supported by liblzma allow preset dictionary when decoding, thus if you create a .xz or .lzma file with preset dictionary, it cannot be decoded with the regular decoder functions. In the future, the .xz format will likely get support for preset dictionary though.

+ +
+
+ +

◆ preset_dict_size

+ +
+
+ + + + +
uint32_t lzma_options_lzma::preset_dict_size
+
+ +

Size of the preset dictionary.

+

Specifies the size of the preset dictionary. If the size is bigger than dict_size, only the last dict_size bytes are processed.

+

This variable is read only when preset_dict is not NULL. If preset_dict is not NULL but preset_dict_size is zero, no preset dictionary is used (identical to only setting preset_dict to NULL).

+ +
+
+ +

◆ lc

+ +
+
+ + + + +
uint32_t lzma_options_lzma::lc
+
+ +

Number of literal context bits.

+

How many of the highest bits of the previous uncompressed eight-bit byte (also known as 'literal') are taken into account when predicting the bits of the next literal.

+

E.g. in typical English text, an upper-case letter is often followed by a lower-case letter, and a lower-case letter is usually followed by another lower-case letter. In the US-ASCII character set, the highest three bits are 010 for upper-case letters and 011 for lower-case letters. When lc is at least 3, the literal coding can take advantage of this property in the uncompressed data.

+

There is a limit that applies to literal context bits and literal position bits together: lc + lp <= 4. Without this limit the decoding could become very slow, which could have security related results in some cases like email servers doing virus scanning. This limit also simplifies the internal implementation in liblzma.

+

There may be LZMA1 streams that have lc + lp > 4 (maximum possible lc would be 8). It is not possible to decode such streams with liblzma.

+ +
+
+ +

◆ lp

+ +
+
+ + + + +
uint32_t lzma_options_lzma::lp
+
+ +

Number of literal position bits.

+

lp affects what kind of alignment in the uncompressed data is assumed when encoding literals. A literal is a single 8-bit byte. See pb below for more information about alignment.

+ +
+
+ +

◆ pb

+ +
+
+ + + + +
uint32_t lzma_options_lzma::pb
+
+ +

Number of position bits.

+

pb affects what kind of alignment in the uncompressed data is assumed in general. The default means four-byte alignment (2^ pb =2^2=4), which is often a good choice when there's no better guess.

+

When the alignment is known, setting pb accordingly may reduce the file size a little. E.g. with text files having one-byte alignment (US-ASCII, ISO-8859-*, UTF-8), setting pb=0 can improve compression slightly. For UTF-16 text, pb=1 is a good choice. If the alignment is an odd number like 3 bytes, pb=0 might be the best choice.

+

Even though the assumed alignment can be adjusted with pb and lp, LZMA1 and LZMA2 still slightly favor 16-byte alignment. It might be worth taking into account when designing file formats that are likely to be often compressed with LZMA1 or LZMA2.

+ +
+
+ +

◆ mode

+ +
+
+ + + + +
lzma_mode lzma_options_lzma::mode
+
+

Compression mode

+ +
+
+ +

◆ nice_len

+ +
+
+ + + + +
uint32_t lzma_options_lzma::nice_len
+
+ +

Nice length of a match.

+

This determines how many bytes the encoder compares from the match candidates when looking for the best match. Once a match of at least nice_len bytes long is found, the encoder stops looking for better candidates and encodes the match. (Naturally, if the found match is actually longer than nice_len, the actual length is encoded; it's not truncated to nice_len.)

+

Bigger values usually increase the compression ratio and compression time. For most files, 32 to 128 is a good value, which gives very good compression ratio at good speed.

+

The exact minimum value depends on the match finder. The maximum is 273, which is the maximum length of a match that LZMA1 and LZMA2 can encode.

+ +
+
+ +

◆ mf

+ +
+
+ + + + +
lzma_match_finder lzma_options_lzma::mf
+
+

Match finder ID

+ +
+
+ +

◆ depth

+ +
+
+ + + + +
uint32_t lzma_options_lzma::depth
+
+ +

Maximum search depth in the match finder.

+

For every input byte, match finder searches through the hash chain or binary tree in a loop, each iteration going one step deeper in the chain or tree. The searching stops if

    +
  • a match of at least nice_len bytes long is found;
    • +
  • all match candidates from the hash chain or binary tree have been checked; or
    • +
  • maximum search depth is reached.
    • +
+

Maximum search depth is needed to prevent the match finder from wasting too much time in case there are lots of short match candidates. On the other hand, stopping the search before all candidates have been checked can reduce compression ratio.

+

Setting depth to zero tells liblzma to use an automatic default value, that depends on the selected match finder and nice_len. The default is in the range [4, 200] or so (it may vary between liblzma versions).

+

Using a bigger depth value than the default can increase compression ratio in some cases. There is no strict maximum value, but high values (thousands or millions) should be used with care: the encoder could remain fast enough with typical input, but malicious input could cause the match finder to slow down dramatically, possibly creating a denial of service attack.

+ +
+
+ +

◆ ext_flags

+ +
+
+ + + + +
uint32_t lzma_options_lzma::ext_flags
+
+ +

For LZMA_FILTER_LZMA1EXT: Extended flags.

+

This is used only with LZMA_FILTER_LZMA1EXT.

+

Currently only one flag is supported, LZMA_LZMA1EXT_ALLOW_EOPM:

+
    +
  • Encoder: If the flag is set, then end marker is written just like it is with LZMA_FILTER_LZMA1. Without this flag the end marker isn't written and the application has to store the uncompressed size somewhere outside the compressed stream. To decompress streams without the end marker, the application has to set the correct uncompressed size in ext_size_low and ext_size_high.
    • +

  • Decoder: If the uncompressed size in ext_size_low and ext_size_high is set to the special value UINT64_MAX (indicating unknown uncompressed size) then this flag is ignored and the end marker must always be present, that is, the behavior is identical to LZMA_FILTER_LZMA1.

    +

    Otherwise, if this flag isn't set, then the input stream must not have the end marker; if the end marker is detected then it will result in LZMA_DATA_ERROR. This is useful when it is known that the stream must not have the end marker and strict validation is wanted.

    +

    If this flag is set, then it is autodetected if the end marker is present after the specified number of uncompressed bytes has been decompressed (ext_size_low and ext_size_high). The end marker isn't allowed in any other position. This behavior is useful when uncompressed size is known but the end marker may or may not be present. This is the case, for example, in .7z files (valid .7z files that have the end marker in LZMA1 streams are rare but they do exist).

    +
    • +
+ +
+
+ +

◆ ext_size_low

+ +
+
+ + + + +
uint32_t lzma_options_lzma::ext_size_low
+
+ +

For LZMA_FILTER_LZMA1EXT: Uncompressed size (low bits)

+

The 64-bit uncompressed size is needed for decompression with LZMA_FILTER_LZMA1EXT. The size is ignored by the encoder.

+

The special value UINT64_MAX indicates that the uncompressed size is unknown and that the end of payload marker (also known as end of stream marker) must be present to indicate the end of the LZMA1 stream. Any other value indicates the expected uncompressed size of the LZMA1 stream. (If LZMA1 was used together with filters that change the size of the data then the uncompressed size of the LZMA1 stream could be different than the final uncompressed size of the filtered stream.)

+

ext_size_low holds the least significant 32 bits of the uncompressed size. The most significant 32 bits must be set in ext_size_high. The macro lzma_ext_size_set(opt_lzma, u64size) can be used to set these members.

+

The 64-bit uncompressed size is split into two uint32_t variables because there were no reserved uint64_t members and using the same options structure for LZMA_FILTER_LZMA1, LZMA_FILTER_LZMA1EXT, and LZMA_FILTER_LZMA2 was otherwise more convenient than having a new options structure for LZMA_FILTER_LZMA1EXT. (Replacing two uint32_t members with one uint64_t changes the ABI on some systems as the alignment of this struct can increase from 4 bytes to 8.)

+ +
+
+ +

◆ ext_size_high

+ +
+
+ + + + +
uint32_t lzma_options_lzma::ext_size_high
+
+ +

For LZMA_FILTER_LZMA1EXT: Uncompressed size (high bits)

+

This holds the most significant 32 bits of the uncompressed size.

+ +
+
+
The documentation for this struct was generated from the following file: +
+
+

+ XZ logo © 2023 by Jia Tan is licensed under + + CC BY-SA 4.0 + +

+ + diff --git a/doc/api/structlzma__stream.html b/doc/api/structlzma__stream.html new file mode 100644 index 00000000..5a2981e5 --- /dev/null +++ b/doc/api/structlzma__stream.html @@ -0,0 +1,257 @@ + + + + + + + +liblzma (XZ Utils): lzma_stream Struct Reference + + + + + + +
+
+ + + + + + + +
+
liblzma (XZ Utils) 5.6.0 +
+
+
+ + + + +
+
+
+Data Fields
+
lzma_stream Struct Reference
+
+
+ +

Passing data to and from liblzma. + More...

+ +

#include <base.h>

+ + + + + + + + + + + + + + + + + + + + + + +

+Data Fields

const uint8_t * next_in
 
size_t avail_in
 
uint64_t total_in
 
uint8_t * next_out
 
size_t avail_out
 
uint64_t total_out
 
const lzma_allocator * allocator
 Custom memory allocation functions.
 
lzma_internal * internal
 
uint64_t seek_pos
 New seek input position for LZMA_SEEK_NEEDED.
 
+

Detailed Description

+

Passing data to and from liblzma.

+

The lzma_stream structure is used for

    +
  • passing pointers to input and output buffers to liblzma;
    • +
  • defining custom memory handler functions; and
    • +
  • holding a pointer to coder-specific internal data structures.
    • +
+

Typical usage:

+
    +
  • After allocating lzma_stream (on stack or with malloc()), it must be initialized to LZMA_STREAM_INIT (see LZMA_STREAM_INIT for details).
    • +
  • Initialize a coder to the lzma_stream, for example by using lzma_easy_encoder() or lzma_auto_decoder(). Some notes:
      +
    • In contrast to zlib, strm->next_in and strm->next_out are ignored by all initialization functions, thus it is safe to not initialize them yet.
      • +
    • The initialization functions always set strm->total_in and strm->total_out to zero.
      • +
    • If the initialization function fails, no memory is left allocated that would require freeing with lzma_end() even if some memory was associated with the lzma_stream structure when the initialization function was called.
      • +
    +
    • +
  • Use lzma_code() to do the actual work.
    • +
  • Once the coding has been finished, the existing lzma_stream can be reused. It is OK to reuse lzma_stream with different initialization function without calling lzma_end() first. Old allocations are automatically freed.
    • +
  • Finally, use lzma_end() to free the allocated memory. lzma_end() never frees the lzma_stream structure itself.
    • +
+

Application may modify the values of total_in and total_out as it wants. They are updated by liblzma to match the amount of data read and written but aren't used for anything else except as a possible return values from lzma_get_progress().

+

Field Documentation

+ +

◆ next_in

+ +
+
+ + + + +
const uint8_t* lzma_stream::next_in
+
+

Pointer to the next input byte.

+ +
+
+ +

◆ avail_in

+ +
+
+ + + + +
size_t lzma_stream::avail_in
+
+

Number of available input bytes in next_in.

+ +
+
+ +

◆ total_in

+ +
+
+ + + + +
uint64_t lzma_stream::total_in
+
+

Total number of bytes read by liblzma.

+ +
+
+ +

◆ next_out

+ +
+
+ + + + +
uint8_t* lzma_stream::next_out
+
+

Pointer to the next output position.

+ +
+
+ +

◆ avail_out

+ +
+
+ + + + +
size_t lzma_stream::avail_out
+
+

Amount of free space in next_out.

+ +
+
+ +

◆ total_out

+ +
+
+ + + + +
uint64_t lzma_stream::total_out
+
+

Total number of bytes written by liblzma.

+ +
+
+ +

◆ allocator

+ +
+
+ + + + +
const lzma_allocator* lzma_stream::allocator
+
+ +

Custom memory allocation functions.

+

In most cases this is NULL which makes liblzma use the standard malloc() and free().

+
Note
In 5.0.x this is not a const pointer.
+ +
+
+ +

◆ internal

+ +
+
+ + + + +
lzma_internal* lzma_stream::internal
+
+

Internal state is not visible to applications.

+ +
+
+ +

◆ seek_pos

+ +
+
+ + + + +
uint64_t lzma_stream::seek_pos
+
+ +

New seek input position for LZMA_SEEK_NEEDED.

+

When lzma_code() returns LZMA_SEEK_NEEDED, the new input position needed by liblzma will be available seek_pos. The value is guaranteed to not exceed the file size that was specified when this lzma_stream was initialized.

+

In all other situations the value of this variable is undefined.

+ +
+
+
The documentation for this struct was generated from the following file: +
+
+

+ XZ logo © 2023 by Jia Tan is licensed under + + CC BY-SA 4.0 + +

+ + diff --git a/doc/api/structlzma__stream__flags.html b/doc/api/structlzma__stream__flags.html new file mode 100644 index 00000000..725cd1e3 --- /dev/null +++ b/doc/api/structlzma__stream__flags.html @@ -0,0 +1,140 @@ + + + + + + + +liblzma (XZ Utils): lzma_stream_flags Struct Reference + + + + + + +
+
+ + + + + + + +
+
liblzma (XZ Utils) 5.6.0 +
+
+
+ + + + +
+
+
+Data Fields
+
lzma_stream_flags Struct Reference
+
+
+ +

Options for encoding/decoding Stream Header and Stream Footer. + More...

+ +

#include <stream_flags.h>

+ + + + + + + + + + + +

+Data Fields

uint32_t version
 Stream Flags format version.
 
lzma_vli backward_size
 Backward Size.
 
lzma_check check
 Check ID.
 
+

Detailed Description

+

Options for encoding/decoding Stream Header and Stream Footer.

+

Field Documentation

+ +

◆ version

+ +
+
+ + + + +
uint32_t lzma_stream_flags::version
+
+ +

Stream Flags format version.

+

To prevent API and ABI breakages if new features are needed in Stream Header or Stream Footer, a version number is used to indicate which members in this structure are in use. For now, version must always be zero. With non-zero version, the lzma_stream_header_encode() and lzma_stream_footer_encode() will return LZMA_OPTIONS_ERROR.

+

lzma_stream_header_decode() and lzma_stream_footer_decode() will always set this to the lowest value that supports all the features indicated by the Stream Flags field. The application must check that the version number set by the decoding functions is supported by the application. Otherwise it is possible that the application will decode the Stream incorrectly.

+ +
+
+ +

◆ backward_size

+ +
+
+ + + + +
lzma_vli lzma_stream_flags::backward_size
+
+ +

Backward Size.

+

Backward Size must be a multiple of four bytes. In this Stream format version, Backward Size is the size of the Index field.

+

Backward Size isn't actually part of the Stream Flags field, but it is convenient to include in this structure anyway. Backward Size is present only in the Stream Footer. There is no need to initialize backward_size when encoding Stream Header.

+

lzma_stream_header_decode() always sets backward_size to LZMA_VLI_UNKNOWN so that it is convenient to use lzma_stream_flags_compare() when both Stream Header and Stream Footer have been decoded.

+ +
+
+ +

◆ check

+ +
+
+ + + + +
lzma_check lzma_stream_flags::check
+
+ +

Check ID.

+

This indicates the type of the integrity check calculated from uncompressed data.

+ +
+
+
The documentation for this struct was generated from the following file: +
+
+

+ XZ logo © 2023 by Jia Tan is licensed under + + CC BY-SA 4.0 + +

+ + diff --git a/doc/api/sync_off.png b/doc/api/sync_off.png new file mode 100644 index 00000000..9b04abe7 Binary files /dev/null and b/doc/api/sync_off.png differ diff --git a/doc/api/sync_on.png b/doc/api/sync_on.png new file mode 100644 index 00000000..34a5b8b9 Binary files /dev/null and b/doc/api/sync_on.png differ diff --git a/doc/api/tab_a.png b/doc/api/tab_a.png new file mode 100644 index 00000000..3181cdfe Binary files /dev/null and b/doc/api/tab_a.png differ diff --git a/doc/api/tab_ad.png b/doc/api/tab_ad.png new file mode 100644 index 00000000..36153864 Binary files /dev/null and b/doc/api/tab_ad.png differ diff --git a/doc/api/tab_b.png b/doc/api/tab_b.png new file mode 100644 index 00000000..3feec4f7 Binary files /dev/null and b/doc/api/tab_b.png differ diff --git a/doc/api/tab_bd.png b/doc/api/tab_bd.png new file mode 100644 index 00000000..9fd66352 Binary files /dev/null and b/doc/api/tab_bd.png differ diff --git a/doc/api/tab_h.png b/doc/api/tab_h.png new file mode 100644 index 00000000..abb3d3dc Binary files /dev/null and b/doc/api/tab_h.png differ diff --git a/doc/api/tab_hd.png b/doc/api/tab_hd.png new file mode 100644 index 00000000..c59e4135 Binary files /dev/null and b/doc/api/tab_hd.png differ diff --git a/doc/api/tab_s.png b/doc/api/tab_s.png new file mode 100644 index 00000000..a3f26f55 Binary files /dev/null and b/doc/api/tab_s.png differ diff --git a/doc/api/tab_sd.png b/doc/api/tab_sd.png new file mode 100644 index 00000000..5d4917ae Binary files /dev/null and b/doc/api/tab_sd.png differ diff --git a/doc/api/tabs.css b/doc/api/tabs.css new file mode 100644 index 00000000..2c664da1 --- /dev/null +++ b/doc/api/tabs.css @@ -0,0 +1,68 @@ +.tabs, .tabs2, .tabs3 { + background-image: var(--nav-gradient-image); + width: 100%; + z-index: 101; + font-size: var(--nav-font-size-level1); + font-family: var(--font-family-nav); + display: table; +} + +.tabs2 { + font-size: var(--nav-font-size-level2); +} +.tabs3 { + font-size: var(--nav-font-size-level3); +} + +.tablist { + margin: 0; + padding: 0; + display: block; +} + +.tablist li { + float: left; + display: table-cell; + background-image: var(--nav-gradient-image); + line-height: 36px; + list-style: none; +} + +.tablist a { + display: block; + padding: 0 20px; + font-weight: bold; + background-image:var(--nav-separator-image); + background-repeat:no-repeat; + background-position:right; + color: var(--nav-text-normal-color); + text-shadow: var(--nav-text-normal-shadow); + text-decoration: none; + outline: none; +} + +.tablist a:focus { + outline: auto; + z-index: 10; + position: relative; +} + +.tabs3 .tablist a { + padding: 0 10px; +} + +.tablist a:hover { + background-image: var(--nav-gradient-hover-image); + background-repeat:repeat-x; + color: var(--nav-text-hover-color); + text-shadow: var(--nav-text-hover-shadow); + text-decoration: none; +} + +.tablist li.current a { + background-image: var(--nav-gradient-active-image); + background-repeat:repeat-x; + color: var(--nav-text-active-color); + text-shadow: var(--nav-text-active-shadow); +} + diff --git a/doc/api/version_8h.html b/doc/api/version_8h.html new file mode 100644 index 00000000..f21dea7a --- /dev/null +++ b/doc/api/version_8h.html @@ -0,0 +1,261 @@ + + + + + + + +liblzma (XZ Utils): lzma/version.h File Reference + + + + + + +
+
+ + + + + + + +
+
liblzma (XZ Utils) 5.6.0 +
+
+
+ + + + + +
+
+
+Macros | +Functions
+
version.h File Reference
+
+
+ +

Version number. +More...

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+Macros

+#define LZMA_VERSION_MAJOR   5
 Major version number of the liblzma release.
 
+#define LZMA_VERSION_MINOR   6
 Minor version number of the liblzma release.
 
+#define LZMA_VERSION_PATCH   0
 Patch version number of the liblzma release.
 
#define LZMA_VERSION_STABILITY   LZMA_VERSION_STABILITY_STABLE
 Version stability marker.
 
+#define LZMA_VERSION_COMMIT   ""
 Commit version number of the liblzma release.
 
+#define LZMA_VERSION_STABILITY_ALPHA   0
 
+#define LZMA_VERSION_STABILITY_BETA   1
 
+#define LZMA_VERSION_STABILITY_STABLE   2
 
#define LZMA_VERSION
 Compile-time version number.
 
+#define LZMA_VERSION_STABILITY_STRING   "alpha"
 
+#define LZMA_VERSION_STRING_C_(major, minor, patch, stability, commit)    #major "." #minor "." #patch stability commit
 
+#define LZMA_VERSION_STRING_C(major, minor, patch, stability, commit)    LZMA_VERSION_STRING_C_(major, minor, patch, stability, commit)
 
#define LZMA_VERSION_STRING
 Compile-time version as a string.
 
+ + + + + + + +

+Functions

uint32_t lzma_version_number (void) lzma_nothrow lzma_attr_const
 Run-time version number as an integer.
 
const char * lzma_version_string (void) lzma_nothrow lzma_attr_const
 Run-time version as a string.
 
+

Detailed Description

+

Version number.

+
Note
Never include this file directly. Use <lzma.h> instead.
+

Macro Definition Documentation

+ +

◆ LZMA_VERSION_STABILITY

+ +
+
+ + + + +
#define LZMA_VERSION_STABILITY   LZMA_VERSION_STABILITY_STABLE
+
+ +

Version stability marker.

+

This will always be one of three values:

    +
  • LZMA_VERSION_STABILITY_ALPHA
    • +
  • LZMA_VERSION_STABILITY_BETA
    • +
  • LZMA_VERSION_STABILITY_STABLE
    • +
+ +
+
+ +

◆ LZMA_VERSION

+ +
+
+ + + + +
#define LZMA_VERSION
+
+Value:
(LZMA_VERSION_MAJOR * UINT32_C(10000000) \
+
+ LZMA_VERSION_MINOR * UINT32_C(10000) \
+
+ LZMA_VERSION_PATCH * UINT32_C(10) \
+
+ LZMA_VERSION_STABILITY)
+
+

Compile-time version number.

+

The version number is of format xyyyzzzs where

    +
  • x = major
    • +
  • yyy = minor
    • +
  • zzz = revision
    • +
  • s indicates stability: 0 = alpha, 1 = beta, 2 = stable
    • +
+

The same xyyyzzz triplet is never reused with different stability levels. For example, if 5.1.0alpha has been released, there will never be 5.1.0beta or 5.1.0 stable.

+
Note
The version number of liblzma has nothing to with the version number of Igor Pavlov's LZMA SDK.
+ +
+
+ +

◆ LZMA_VERSION_STRING

+ +
+
+ + + + +
#define LZMA_VERSION_STRING
+
+Value:
LZMA_VERSION_STRING_C( \
+
LZMA_VERSION_MAJOR, LZMA_VERSION_MINOR, \
+
LZMA_VERSION_PATCH, LZMA_VERSION_STABILITY_STRING, \
+
LZMA_VERSION_COMMIT)
+
+

Compile-time version as a string.

+

This can be for example "4.999.5alpha", "4.999.8beta", or "5.0.0" (stable versions don't have any "stable" suffix). In future, a snapshot built from source code repository may include an additional suffix, for example "4.999.8beta-21-g1d92". The commit ID won't be available in numeric form in LZMA_VERSION macro.

+ +
+
+

Function Documentation

+ +

◆ lzma_version_number()

+ +
+
+ + + + + +
+ + + + + + + + +
uint32_t lzma_version_number (void ) const
+ 		+extern
+
+ +

Run-time version number as an integer.

+

This allows an application to compare if it was built against the same, older, or newer version of liblzma that is currently running.

+
Returns
The value of LZMA_VERSION macro at the compile time of liblzma
+ +
+
+ +

◆ lzma_version_string()

+ +
+
+ + + + + +
+ + + + + + + + +
const char * lzma_version_string (void ) const
+ 		+extern
+
+ +

Run-time version as a string.

+

This function may be useful to display which version of liblzma an application is currently using.

+
Returns
Run-time version of liblzma
+ +
+
+
+
+

+ XZ logo © 2023 by Jia Tan is licensed under + + CC BY-SA 4.0 + +

+ + diff --git a/doc/api/vli_8h.html b/doc/api/vli_8h.html new file mode 100644 index 00000000..ca5bd157 --- /dev/null +++ b/doc/api/vli_8h.html @@ -0,0 +1,353 @@ + + + + + + + +liblzma (XZ Utils): lzma/vli.h File Reference + + + + + + +
+
+ + + + + + + +
+
liblzma (XZ Utils) 5.6.0 +
+
+
+ + + + + +
+
+
+Macros | +Typedefs | +Functions
+
vli.h File Reference
+
+
+ +

Variable-length integer handling. +More...

+ + + + + + + + + + + + + + + + + +

+Macros

+#define LZMA_VLI_MAX   (UINT64_MAX / 2)
 Maximum supported value of a variable-length integer.
 
+#define LZMA_VLI_UNKNOWN   UINT64_MAX
 VLI value to denote that the value is unknown.
 
+#define LZMA_VLI_BYTES_MAX   9
 Maximum supported encoded length of variable length integers.
 
+#define LZMA_VLI_C(n)   UINT64_C(n)
 VLI constant suffix.
 
#define lzma_vli_is_valid(vli)    ((vli) <= LZMA_VLI_MAX || (vli) == LZMA_VLI_UNKNOWN)
 Validate a variable-length integer.
 
+ + + + +

+Typedefs

typedef uint64_t lzma_vli
 Variable-length integer type.
 
+ + + + + + + + + + +

+Functions

lzma_ret lzma_vli_encode (lzma_vli vli, size_t *vli_pos, uint8_t *out, size_t *out_pos, size_t out_size) lzma_nothrow
 Encode a variable-length integer.
 
lzma_ret lzma_vli_decode (lzma_vli *vli, size_t *vli_pos, const uint8_t *in, size_t *in_pos, size_t in_size) lzma_nothrow
 Decode a variable-length integer.
 
uint32_t lzma_vli_size (lzma_vli vli) lzma_nothrow lzma_attr_pure
 Get the number of bytes required to encode a VLI.
 
+

Detailed Description

+

Variable-length integer handling.

+
Note
Never include this file directly. Use <lzma.h> instead.
+

In the .xz format, most integers are encoded in a variable-length representation, which is sometimes called little endian base-128 encoding. This saves space when smaller values are more likely than bigger values.

+

The encoding scheme encodes seven bits to every byte, using minimum number of bytes required to represent the given value. Encodings that use non-minimum number of bytes are invalid, thus every integer has exactly one encoded representation. The maximum number of bits in a VLI is 63, thus the vli argument must be less than or equal to UINT64_MAX / 2. You should use LZMA_VLI_MAX for clarity.

+

Macro Definition Documentation

+ +

◆ lzma_vli_is_valid

+ +
+
+ + + + + + + + +
#define lzma_vli_is_valid( vli)    ((vli) <= LZMA_VLI_MAX || (vli) == LZMA_VLI_UNKNOWN)
+
+ +

Validate a variable-length integer.

+

This is useful to test that application has given acceptable values for example in the uncompressed_size and compressed_size variables.

+
Returns
True if the integer is representable as VLI or if it indicates unknown value. False if the integer cannot be represented as VLI.
+ +
+
+

Typedef Documentation

+ +

◆ lzma_vli

+ +
+
+ + + + +
typedef uint64_t lzma_vli
+
+ +

Variable-length integer type.

+

Valid VLI values are in the range [0, LZMA_VLI_MAX]. Unknown value is indicated with LZMA_VLI_UNKNOWN, which is the maximum value of the underlying integer type.

+

lzma_vli will be uint64_t for the foreseeable future. If a bigger size is needed in the future, it is guaranteed that 2 * LZMA_VLI_MAX will not overflow lzma_vli. This simplifies integer overflow detection.

+ +
+
+

Function Documentation

+ +

◆ lzma_vli_encode()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_vli_encode (lzma_vli vli,
size_t * vli_pos,
uint8_t * out,
size_t * out_pos,
size_t out_size 
)
+ 		+extern
+
+ +

Encode a variable-length integer.

+

This function has two modes: single-call and multi-call. Single-call mode encodes the whole integer at once; it is an error if the output buffer is too small. Multi-call mode saves the position in *vli_pos, and thus it is possible to continue encoding if the buffer becomes full before the whole integer has been encoded.

+
Parameters
+ + + + + + +
vliInteger to be encoded
[out]vli_posHow many VLI-encoded bytes have already been written out. When starting to encode a new integer in multi-call mode, *vli_pos must be set to zero. To use single-call encoding, set vli_pos to NULL.
[out]outBeginning of the output buffer
[out]out_posThe next byte will be written to out[*out_pos].
out_sizeSize of the out buffer; the first byte into which no data is written to is out[out_size].
+
+
+
Returns
Slightly different return values are used in multi-call and single-call modes.
+

Single-call (vli_pos == NULL):

    +
  • LZMA_OK: Integer successfully encoded.
    • +
  • LZMA_PROG_ERROR: Arguments are not sane. This can be due to too little output space; single-call mode doesn't use LZMA_BUF_ERROR, since the application should have checked the encoded size with lzma_vli_size().
    • +
+

Multi-call (vli_pos != NULL):

    +
  • LZMA_OK: So far all OK, but the integer is not completely written out yet.
    • +
  • LZMA_STREAM_END: Integer successfully encoded.
    • +
  • LZMA_BUF_ERROR: No output space was provided.
    • +
  • LZMA_PROG_ERROR: Arguments are not sane.
    • +
+ +
+
+ +

◆ lzma_vli_decode()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_vli_decode (lzma_vli * vli,
size_t * vli_pos,
const uint8_t * in,
size_t * in_pos,
size_t in_size 
)
+ 		+extern
+
+ +

Decode a variable-length integer.

+

Like lzma_vli_encode(), this function has single-call and multi-call modes.

+
Parameters
+ + + + + + +
[out]vliPointer to decoded integer. The decoder will initialize it to zero when *vli_pos == 0, so application isn't required to initialize *vli.
[out]vli_posHow many bytes have already been decoded. When starting to decode a new integer in multi-call mode, *vli_pos must be initialized to zero. To use single-call decoding, set vli_pos to NULL.
inBeginning of the input buffer
[out]in_posThe next byte will be read from in[*in_pos].
in_sizeSize of the input buffer; the first byte that won't be read is in[in_size].
+
+
+
Returns
Slightly different return values are used in multi-call and single-call modes.
+

Single-call (vli_pos == NULL):

    +
  • LZMA_OK: Integer successfully decoded.
    • +
  • LZMA_DATA_ERROR: Integer is corrupt. This includes hitting the end of the input buffer before the whole integer was decoded; providing no input at all will use LZMA_DATA_ERROR.
    • +
  • LZMA_PROG_ERROR: Arguments are not sane.
    • +
+

Multi-call (vli_pos != NULL):

    +
  • LZMA_OK: So far all OK, but the integer is not completely decoded yet.
    • +
  • LZMA_STREAM_END: Integer successfully decoded.
    • +
  • LZMA_DATA_ERROR: Integer is corrupt.
    • +
  • LZMA_BUF_ERROR: No input was provided.
    • +
  • LZMA_PROG_ERROR: Arguments are not sane.
    • +
+ +
+
+ +

◆ lzma_vli_size()

+ +
+
+ + + + + +
+ + + + + + + + +
uint32_t lzma_vli_size (lzma_vli vli)
+ 		+extern
+
+ +

Get the number of bytes required to encode a VLI.

+
Parameters
+ + +
vliInteger whose encoded size is to be determined
+
+
+
Returns
Number of bytes on success (1-9). If vli isn't valid, zero is returned.
+ +
+
+
+
+

+ XZ logo © 2023 by Jia Tan is licensed under + + CC BY-SA 4.0 + +

+ + diff --git a/doc/api/xz-logo.png b/doc/api/xz-logo.png new file mode 100644 index 00000000..f9d6313d Binary files /dev/null and b/doc/api/xz-logo.png differ -- cgit v1.2.3