diff options
Diffstat (limited to 'doc/lzlib.info')
| -rw-r--r-- | doc/lzlib.info | 184 |
1 files changed, 92 insertions, 92 deletions
diff --git a/doc/lzlib.info b/doc/lzlib.info index 683b18e..dd67c12 100644 --- a/doc/lzlib.info +++ b/doc/lzlib.info @@ -1,4 +1,4 @@ -This is lzlib.info, produced by makeinfo version 4.13 from +This is lzlib.info, produced by makeinfo version 4.13+ from lzlib.texinfo. INFO-DIR-SECTION Data Compression @@ -12,7 +12,7 @@ File: lzlib.info, Node: Top, Next: Introduction, Up: (dir) Lzlib Manual ************ -This manual is for Lzlib (version 1.5, 15 September 2013). +This manual is for Lzlib (version 1.6-pre1, 7 October 2013). * Menu: @@ -51,8 +51,8 @@ clean, provides very safe 4 factor integrity checking, and is backed by the recovery capabilities of lziprecover. The functions and variables forming the interface of the compression -library are declared in the file `lzlib.h'. Usage examples of the -library are given in the files `main.c' and `bbexample.c' from the +library are declared in the file 'lzlib.h'. Usage examples of the +library are given in the files 'main.c' and 'bbexample.c' from the source distribution. Compression/decompression is done by repeatedly calling a couple of @@ -100,11 +100,11 @@ File: lzlib.info, Node: Library version, Next: Buffering, Prev: Introduction, Returns the library version as a string. -- Constant: const char * LZ_version_string - This constant is defined in the header file `lzlib.h'. + This constant is defined in the header file 'lzlib.h'. The application should compare LZ_version and LZ_version_string for consistency. If the first character differs, the library code actually -used may be incompatible with the `lzlib.h' header file used by the +used may be incompatible with the 'lzlib.h' header file used by the application. if( LZ_version()[0] != LZ_version_string[0] ) @@ -124,17 +124,17 @@ Finally, for security reasons, lzlib uses two more internal buffers. These are the four buffers used by lzlib, and their guaranteed minimum sizes: - * Input compression buffer. Written to by the `LZ_compress_write' + * Input compression buffer. Written to by the 'LZ_compress_write' function. Its size is two times the dictionary size set with the - `LZ_compress_open' function or 64 KiB, whichever is larger. + 'LZ_compress_open' function or 64 KiB, whichever is larger. - * Output compression buffer. Read from by the `LZ_compress_read' + * Output compression buffer. Read from by the 'LZ_compress_read' function. Its size is 64 KiB. * Input decompression buffer. Written to by the - `LZ_decompress_write' function. Its size is 64 KiB. + 'LZ_decompress_write' function. Its size is 64 KiB. - * Output decompression buffer. Read from by the `LZ_decompress_read' + * Output decompression buffer. Read from by the 'LZ_decompress_read' function. Its size is the dictionary size set in the header of the member currently being decompressed or 64 KiB, whichever is larger. @@ -175,8 +175,8 @@ File: lzlib.info, Node: Compression functions, Next: Decompression functions, These are the functions used to compress data. In case of error, all of them return -1 or 0, for signed and unsigned return values respectively, -except `LZ_compress_open' whose return value must be verified by -calling `LZ_compress_errno' before using it. +except 'LZ_compress_open' whose return value must be verified by +calling 'LZ_compress_errno' before using it. -- Function: struct LZ_Encoder * LZ_compress_open ( const int DICTIONARY_SIZE, const int MATCH_LEN_LIMIT, const unsigned @@ -187,9 +187,9 @@ calling `LZ_compress_errno' before using it. could not be allocated. The returned pointer must be verified by calling - `LZ_compress_errno' before using it. If `LZ_compress_errno' does - not return `LZ_ok', the returned pointer must not be used and - should be freed with `LZ_compress_close' to avoid memory leaks. + 'LZ_compress_errno' before using it. If 'LZ_compress_errno' does + not return 'LZ_ok', the returned pointer must not be used and + should be freed with 'LZ_compress_close' to avoid memory leaks. DICTIONARY_SIZE sets the dictionary size to be used, in bytes. Valid values range from 4 KiB to 512 MiB. Note that dictionary @@ -211,45 +211,45 @@ calling `LZ_compress_errno' before using it. ) Frees all dynamically allocated data structures for this stream. This function discards any unprocessed input and does not flush - any pending output. After a call to `LZ_compress_close', ENCODER + any pending output. After a call to 'LZ_compress_close', ENCODER can no more be used as an argument to any LZ_compress function. -- Function: int LZ_compress_finish ( struct LZ_Encoder * const ENCODER ) - Use this function to tell `lzlib' that all the data for this member - has already been written (with the `LZ_compress_write' function). + Use this function to tell 'lzlib' that all the data for this member + has already been written (with the 'LZ_compress_write' function). After all the produced compressed data has been read with - `LZ_compress_read' and `LZ_compress_member_finished' returns 1, a - new member can be started with `LZ_compress_restart_member'. + 'LZ_compress_read' and 'LZ_compress_member_finished' returns 1, a + new member can be started with 'LZ_compress_restart_member'. -- Function: int LZ_compress_restart_member ( struct LZ_Encoder * const ENCODER, const unsigned long long MEMBER_SIZE ) Use this function to start a new member, in a multi-member data stream. Call this function only after - `LZ_compress_member_finished' indicates that the current member - has been fully read (with the `LZ_compress_read' function). + 'LZ_compress_member_finished' indicates that the current member + has been fully read (with the 'LZ_compress_read' function). -- Function: int LZ_compress_sync_flush ( struct LZ_Encoder * const ENCODER ) - Use this function to make available to `LZ_compress_read' all the - data already written with the `LZ_compress_write' function. - Repeated use of `LZ_compress_sync_flush' may degrade compression + Use this function to make available to 'LZ_compress_read' all the + data already written with the 'LZ_compress_write' function. + Repeated use of 'LZ_compress_sync_flush' may degrade compression ratio, so use it only when needed. -- Function: int LZ_compress_read ( struct LZ_Encoder * const ENCODER, uint8_t * const BUFFER, const int SIZE ) - The `LZ_compress_read' function reads up to SIZE bytes from the + The 'LZ_compress_read' function reads up to SIZE bytes from the stream pointed to by ENCODER, storing the results in BUFFER. The return value is the number of bytes actually read. This might be less than SIZE; for example, if there aren't that many bytes left in the stream or if more bytes have to be yet written with the - `LZ_compress_write' function. Note that reading less than SIZE + 'LZ_compress_write' function. Note that reading less than SIZE bytes is not an error. -- Function: int LZ_compress_write ( struct LZ_Encoder * const ENCODER, uint8_t * const BUFFER, const int SIZE ) - The `LZ_compress_write' function writes up to SIZE bytes from + The 'LZ_compress_write' function writes up to SIZE bytes from BUFFER to the stream pointed to by ENCODER. The return value is the number of bytes actually written. This @@ -258,11 +258,11 @@ calling `LZ_compress_errno' before using it. -- Function: int LZ_compress_write_size ( struct LZ_Encoder * const ENCODER ) - The `LZ_compress_write_size' function returns the maximum number of + The 'LZ_compress_write_size' function returns the maximum number of bytes that can be immediately written through the - `LZ_compress_write' function. + 'LZ_compress_write' function. - It is guaranteed that an immediate call to `LZ_compress_write' will + It is guaranteed that an immediate call to 'LZ_compress_write' will accept a SIZE up to the returned number of bytes. -- Function: enum LZ_Errno LZ_compress_errno ( struct LZ_Encoder * @@ -271,13 +271,13 @@ calling `LZ_compress_errno' before using it. -- Function: int LZ_compress_finished ( struct LZ_Encoder * const ENCODER ) - Returns 1 if all the data has been read and `LZ_compress_close' can + Returns 1 if all the data has been read and 'LZ_compress_close' can be safely called. Otherwise it returns 0. -- Function: int LZ_compress_member_finished ( struct LZ_Encoder * const ENCODER ) Returns 1 if the current member, in a multi-member data stream, - has been fully read and `LZ_compress_restart_member' can be safely + has been fully read and 'LZ_compress_restart_member' can be safely called. Otherwise it returns 0. -- Function: unsigned long long LZ_compress_data_position ( struct @@ -307,8 +307,8 @@ File: lzlib.info, Node: Decompression functions, Next: Error codes, Prev: Com These are the functions used to decompress data. In case of error, all of them return -1 or 0, for signed and unsigned return values -respectively, except `LZ_decompress_open' whose return value must be -verified by calling `LZ_decompress_errno' before using it. +respectively, except 'LZ_decompress_open' whose return value must be +verified by calling 'LZ_decompress_errno' before using it. -- Function: struct LZ_Decoder * LZ_decompress_open ( void ) Initializes the internal stream state for decompression and @@ -317,35 +317,35 @@ verified by calling `LZ_decompress_errno' before using it. decoder could not be allocated. The returned pointer must be verified by calling - `LZ_decompress_errno' before using it. If `LZ_decompress_errno' - does not return `LZ_ok', the returned pointer must not be used and - should be freed with `LZ_decompress_close' to avoid memory leaks. + 'LZ_decompress_errno' before using it. If 'LZ_decompress_errno' + does not return 'LZ_ok', the returned pointer must not be used and + should be freed with 'LZ_decompress_close' to avoid memory leaks. -- Function: int LZ_decompress_close ( struct LZ_Decoder * const DECODER ) Frees all dynamically allocated data structures for this stream. This function discards any unprocessed input and does not flush - any pending output. After a call to `LZ_decompress_close', DECODER + any pending output. After a call to 'LZ_decompress_close', DECODER can no more be used as an argument to any LZ_decompress function. -- Function: int LZ_decompress_finish ( struct LZ_Decoder * const DECODER ) - Use this function to tell `lzlib' that all the data for this stream - has already been written (with the `LZ_decompress_write' function). + Use this function to tell 'lzlib' that all the data for this stream + has already been written (with the 'LZ_decompress_write' function). -- Function: int LZ_decompress_reset ( struct LZ_Decoder * const DECODER ) Resets the internal state of DECODER as it was just after opening - it with the `LZ_decompress_open' function. Data stored in the + it with the 'LZ_decompress_open' function. Data stored in the internal buffers is discarded. Position counters are set to 0. -- Function: int LZ_decompress_sync_to_member ( struct LZ_Decoder * const DECODER ) Resets the error state of DECODER and enters a search state that lasts until a new member header (or the end of the stream) is - found. After a successful call to `LZ_decompress_sync_to_member', - data written with `LZ_decompress_write' will be consumed and - `LZ_decompress_read' will return 0 until a header is found. + found. After a successful call to 'LZ_decompress_sync_to_member', + data written with 'LZ_decompress_write' will be consumed and + 'LZ_decompress_read' will return 0 until a header is found. This function is useful to discard any data preceding the first member, or to discard the rest of the current member, for example @@ -354,18 +354,18 @@ verified by calling `LZ_decompress_errno' before using it. -- Function: int LZ_decompress_read ( struct LZ_Decoder * const DECODER, uint8_t * const BUFFER, const int SIZE ) - The `LZ_decompress_read' function reads up to SIZE bytes from the + The 'LZ_decompress_read' function reads up to SIZE bytes from the stream pointed to by DECODER, storing the results in BUFFER. The return value is the number of bytes actually read. This might be less than SIZE; for example, if there aren't that many bytes left in the stream or if more bytes have to be yet written with the - `LZ_decompress_write' function. Note that reading less than SIZE + 'LZ_decompress_write' function. Note that reading less than SIZE bytes is not an error. -- Function: int LZ_decompress_write ( struct LZ_Decoder * const DECODER, uint8_t * const BUFFER, const int SIZE ) - The `LZ_decompress_write' function writes up to SIZE bytes from + The 'LZ_decompress_write' function writes up to SIZE bytes from BUFFER to the stream pointed to by DECODER. The return value is the number of bytes actually written. This @@ -374,11 +374,11 @@ verified by calling `LZ_decompress_errno' before using it. -- Function: int LZ_decompress_write_size ( struct LZ_Decoder * const DECODER ) - The `LZ_decompress_write_size' function returns the maximum number + The 'LZ_decompress_write_size' function returns the maximum number of bytes that can be immediately written through the - `LZ_decompress_write' function. + 'LZ_decompress_write' function. - It is guaranteed that an immediate call to `LZ_decompress_write' + It is guaranteed that an immediate call to 'LZ_decompress_write' will accept a SIZE up to the returned number of bytes. -- Function: enum LZ_Errno LZ_decompress_errno ( struct LZ_Decoder * @@ -387,16 +387,16 @@ verified by calling `LZ_decompress_errno' before using it. -- Function: int LZ_decompress_finished ( struct LZ_Decoder * const DECODER ) - Returns 1 if all the data has been read and `LZ_decompress_close' + Returns 1 if all the data has been read and 'LZ_decompress_close' can be safely called. Otherwise it returns 0. -- Function: int LZ_decompress_member_finished ( struct LZ_Decoder * const DECODER ) - Returns 1 if the previous call to `LZ_decompress_read' finished + Returns 1 if the previous call to 'LZ_decompress_read' finished reading the current member, indicating that final values for - member are available through `LZ_decompress_data_crc', - `LZ_decompress_data_position', and - `LZ_decompress_member_position'. Otherwise it returns 0. + member are available through 'LZ_decompress_data_crc', + 'LZ_decompress_data_position', and + 'LZ_decompress_member_position'. Otherwise it returns 0. -- Function: int LZ_decompress_member_version ( struct LZ_Decoder * const DECODER ) @@ -410,7 +410,7 @@ verified by calling `LZ_decompress_errno' before using it. const DECODER ) Returns the 32 bit Cyclic Redundancy Check of the data decompressed from the current member. The returned value is valid - only when `LZ_decompress_member_finished' returns 1. + only when 'LZ_decompress_member_finished' returns 1. -- Function: unsigned long long LZ_decompress_data_position ( struct LZ_Decoder * const DECODER ) @@ -440,16 +440,16 @@ File: lzlib.info, Node: Error codes, Next: Error messages, Prev: Decompressio Most library functions return -1 to indicate that they have failed. But this return value only tells you that an error has occurred. To find out what kind of error it was, you need to verify the error code by calling -`LZ_(de)compress_errno'. +'LZ_(de)compress_errno'. Library functions do not change the value returned by -`LZ_(de)compress_errno' when they succeed; thus, the value returned by -`LZ_(de)compress_errno' after a successful call is not necessarily -LZ_ok, and you should not use `LZ_(de)compress_errno' to determine +'LZ_(de)compress_errno' when they succeed; thus, the value returned by +'LZ_(de)compress_errno' after a successful call is not necessarily +LZ_ok, and you should not use 'LZ_(de)compress_errno' to determine whether a call failed. If the call failed, then you can examine -`LZ_(de)compress_errno'. +'LZ_(de)compress_errno'. - The error codes are defined in the header file `lzlib.h'. + The error codes are defined in the header file 'lzlib.h'. -- Constant: enum LZ_Errno LZ_ok The value of this constant is 0 and is used to indicate that there @@ -465,8 +465,8 @@ whether a call failed. If the call failed, then you can examine -- Constant: enum LZ_Errno LZ_sequence_error A library function was called in the wrong order. For example - `LZ_compress_restart_member' was called before - `LZ_compress_member_finished' indicates that the current member is + 'LZ_compress_restart_member' was called before + 'LZ_compress_member_finished' indicates that the current member is finished. -- Constant: enum LZ_Errno LZ_header_error @@ -497,7 +497,7 @@ File: lzlib.info, Node: Error messages, Next: Data format, Prev: Error codes, library call. The value of LZ_ERRNO normally comes from a call to - `LZ_(de)compress_errno'. + 'LZ_(de)compress_errno'. File: lzlib.info, Node: Data format, Next: Examples, Prev: Error messages, Up: Top @@ -534,15 +534,15 @@ with no additional information before, between, or after them. All multibyte values are stored in little endian order. -`ID string' +'ID string' A four byte string, identifying the lzip format, with the value "LZIP" (0x4C, 0x5A, 0x49, 0x50). -`VN (version number, 1 byte)' +'VN (version number, 1 byte)' Just in case something needs to be modified in the future. 1 for now. -`DS (coded dictionary size, 1 byte)' +'DS (coded dictionary size, 1 byte)' Lzip divides the distance between any two powers of 2 into 8 equally spaced intervals, named "wedges". The dictionary size is calculated by taking a power of 2 (the base size) and substracting @@ -554,20 +554,20 @@ with no additional information before, between, or after them. Example: 0xD3 = 2^19 - 6 * 2^15 = 512 KiB - 6 * 32 KiB = 320 KiB Valid values for dictionary size range from 4 KiB to 512 MiB. -`Lzma stream' +'Lzma stream' The lzma stream, finished by an end of stream marker. Uses default values for encoder properties. See the lzip manual for a full description. - Lzip only uses the LZMA marker `2' ("End Of Stream" marker). Lzlib - also uses the LZMA marker `3' ("Sync Flush" marker). + Lzip only uses the LZMA marker '2' ("End Of Stream" marker). Lzlib + also uses the LZMA marker '3' ("Sync Flush" marker). -`CRC32 (4 bytes)' +'CRC32 (4 bytes)' CRC of the uncompressed original data. -`Data size (8 bytes)' +'Data size (8 bytes)' Size of the uncompressed original data. -`Member size (8 bytes)' +'Member size (8 bytes)' Total size of the member, including header and trailer. This field acts as a distributed index, allows the verification of stream integrity, and facilitates safe recovery of undamaged members from @@ -582,7 +582,7 @@ File: lzlib.info, Node: Examples, Next: Problems, Prev: Data format, Up: Top This chapter shows the order in which the library functions should be called depending on what kind of data stream you want to compress or -decompress. See the file `bbexample.c' in the source distribution for +decompress. See the file 'bbexample.c' in the source distribution for an example of how buffer-to-buffer compression/decompression can be implemented using lzlib. @@ -707,8 +707,8 @@ for all eternity, if not longer. If you find a bug in Lzlib, please send electronic mail to <lzip-bug@nongnu.org>. Include the version number, which you can find -by running `minilzip --version' or in `LZ_version_string' from -`lzlib.h'. +by running 'minilzip --version' or in 'LZ_version_string' from +'lzlib.h'. File: lzlib.info, Node: Concept index, Prev: Problems, Up: Top @@ -736,19 +736,19 @@ Concept index Tag Table: -Node: Top217 -Node: Introduction1323 -Node: Library version3904 -Node: Buffering4549 -Node: Parameter limits5672 -Node: Compression functions6631 -Node: Decompression functions12844 -Node: Error codes19005 -Node: Error messages20944 -Node: Data format21523 -Node: Examples24172 -Node: Problems28255 -Node: Concept index28827 +Node: Top218 +Node: Introduction1326 +Node: Library version3907 +Node: Buffering4552 +Node: Parameter limits5675 +Node: Compression functions6634 +Node: Decompression functions12847 +Node: Error codes19008 +Node: Error messages20947 +Node: Data format21526 +Node: Examples24175 +Node: Problems28258 +Node: Concept index28830 End Tag Table |