Merging upstream version 0.8.

Signed-off-by: Daniel Baumann <mail@daniel-baumann.ch>

2 files changed, 476 insertions, 149 deletions

diff --git a/doc/lzlib.info b/doc/lzlib.info
index 40862bd..9437d8c 100644
--- a/doc/lzlib.info
+++ b/doc/lzlib.info
@@ -12,23 +12,25 @@ File: lzlib.info,  Node: Top,  Next: Introduction,  Up: (dir)
 Lzlib Manual
 ************
 
-This manual is for Lzlib (version 0.7, 20 October 2009).
+This manual is for Lzlib (version 0.8, 17 January 2010).
 
 * Menu:
 
 * Introduction::		Purpose and features of Lzlib
 * Library Version::		Checking library version
 * Buffering::			Sizes of Lzlib's buffers
+* Parameter Limits::		Min / max values for some parameters
 * Compression Functions::	Descriptions of the compression functions
 * Decompression Functions::	Descriptions of the decompression functions
 * Error Codes::			Meaning of codes returned by functions
+* Error Messages::		Error messages corresponding to error codes
 * Data Format::			Detailed format of the compressed data
 * Examples::			A small tutorial with examples
 * Problems::			Reporting bugs
 * Concept Index::		Index of concepts
 
 
-   Copyright (C) 2009 Antonio Diaz Diaz.
+   Copyright (C) 2009, 2010 Antonio Diaz Diaz.
 
    This manual is free documentation: you have unlimited permission to
 copy, distribute and modify it.
@@ -95,7 +97,7 @@ application.
        error( "bad library version" );
 
 
-File: lzlib.info,  Node: Buffering,  Next: Compression Functions,  Prev: Library Version,  Up: Top
+File: lzlib.info,  Node: Buffering,  Next: Parameter Limits,  Prev: Library Version,  Up: Top
 
 3 Buffering
 ***********
@@ -119,24 +121,55 @@ minimum sizes:
      `LZ_decompress_write' function. Its size is 64KiB.
 
    * Output decompression buffer. Read from by the `LZ_decompress_read'
-     function. Its size is the dictionary size set with the
-     `LZ_decompress_open' function or 64KiB, whichever is larger.
+     function. Its size is the dictionary size set in the header of the
+     member currently being decompressed or 64KiB, whichever is larger.
 
 
-File: lzlib.info,  Node: Compression Functions,  Next: Decompression Functions,  Prev: Buffering,  Up: Top
+File: lzlib.info,  Node: Parameter Limits,  Next: Compression Functions,  Prev: Buffering,  Up: Top
 
-4 Compression Functions
+4 Parameter Limits
+******************
+
+These functions provide minimum and maximum values for some parameters.
+Current values are shown in square brackets.
+
+ -- Function: int LZ_min_dictionary_bits ( void )
+     Returns the base 2 logarithm of the smallest valid dictionary size
+     [12].
+
+ -- Function: int LZ_min_dictionary_size ( void )
+     Returns the smallest valid dictionary size [4KiB].
+
+ -- Function: int LZ_max_dictionary_bits ( void )
+     Returns the base 2 logarithm of the largest valid dictionary size
+     [29].
+
+ -- Function: int LZ_max_dictionary_size ( void )
+     Returns the largest valid dictionary size [512MiB].
+
+ -- Function: int LZ_min_match_len_limit ( void )
+     Returns the smallest valid match length limit [5].
+
+ -- Function: int LZ_max_match_len_limit ( void )
+     Returns the largest valid match length limit [273].
+
+
+File: lzlib.info,  Node: Compression Functions,  Next: Decompression Functions,  Prev: Parameter Limits,  Up: Top
+
+5 Compression Functions
 ***********************
 
 These are the functions used to compress data. In case of error, all of
 them return -1, except `LZ_compress_open' whose return value must be
 verified by calling `LZ_compress_errno' before using it.
 
- -- Function: void * LZ_compress_open ( const int DICTIONARY_SIZE,
-          const int MATCH_LEN_LIMIT, const long long MEMBER_SIZE )
+ -- Function: struct LZ_Encoder * LZ_compress_open ( const int
+          DICTIONARY_SIZE, const int MATCH_LEN_LIMIT, const long long
+          MEMBER_SIZE )
      Initializes the internal stream state for compression and returns a
      pointer that can only be used as the ENCODER argument for the
-     other LZ_compress functions.
+     other LZ_compress functions, or a null pointer if the encoder
+     could not be allocated.
 
      The returned pointer must be verified by calling
      `LZ_compress_errno' before using it. If `LZ_compress_errno' does
@@ -158,31 +191,37 @@ verified by calling `LZ_compress_errno' before using it.
      stream, give MEMBER_SIZE a value larger than the amount of data to
      be produced, for example LLONG_MAX.
 
- -- Function: int LZ_compress_restart_member ( void * const ENCODER,
-          const long long MEMBER_SIZE )
-     Use this function to start a new member, in a multimember 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).
-
- -- Function: int LZ_compress_close ( void * const ENCODER )
+ -- Function: int LZ_compress_close ( struct LZ_Encoder * const ENCODER
+          )
      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
      can no more be used as an argument to any LZ_compress function.
 
- -- Function: int LZ_compress_finish ( void * const ENCODER )
-     Use this function to tell `lzlib' that all the data for this stream
+ -- 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).
+     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'.
+
+ -- Function: int LZ_compress_restart_member ( struct LZ_Encoder *
+          const ENCODER, const long long MEMBER_SIZE )
+     Use this function to start a new member, in a multimember 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).
 
- -- Function: int LZ_compress_sync_flush ( void * const ENCODER )
+ -- 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
      ratio, so use it only when needed.
 
- -- Function: int LZ_compress_read ( void * const ENCODER, uint8_t *
-          const BUFFER, const int SIZE )
+ -- 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
      stream pointed to by ENCODER, storing the results in BUFFER.
 
@@ -192,8 +231,8 @@ verified by calling `LZ_compress_errno' before using it.
      `LZ_compress_write' function. Note that reading less than SIZE
      bytes is not an error.
 
- -- Function: int LZ_compress_write ( void * const ENCODER, uint8_t *
-          const BUFFER, const int SIZE )
+ -- 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
      BUFFER to the stream pointed to by ENCODER.
 
@@ -201,7 +240,8 @@ verified by calling `LZ_compress_errno' before using it.
      might be less than SIZE. Note that writing less than SIZE bytes is
      not an error.
 
- -- Function: int LZ_compress_write_size ( void * const ENCODER )
+ -- Function: int LZ_compress_write_size ( struct LZ_Encoder * const
+          ENCODER )
      The `LZ_compress_write_size' function returns the maximum number of
      bytes that can be inmediately written through the
      `LZ_compress_write' function.
@@ -209,69 +249,94 @@ verified by calling `LZ_compress_errno' before using it.
      It is guaranteed that an inmediate call to `LZ_compress_write' will
      accept a SIZE up to the returned number of bytes.
 
- -- Function: enum LZ_errno LZ_compress_errno ( void * const ENCODER )
+ -- Function: enum LZ_Errno LZ_compress_errno ( struct LZ_Encoder *
+          const ENCODER )
      Returns the current error code for ENCODER (*note Error Codes::)
 
- -- Function: int LZ_compress_finished ( void * const ENCODER )
+ -- Function: int LZ_compress_finished ( struct LZ_Encoder * const
+          ENCODER )
      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 ( void * const ENCODER )
+ -- Function: int LZ_compress_member_finished ( struct LZ_Encoder *
+          const ENCODER )
      Returns 1 if the current member, in a multimember data stream, has
      been fully read and `LZ_compress_restart_member' can be safely
      called.  Otherwise it returns 0.
 
- -- Function: long long LZ_compress_data_position ( void * const
-          ENCODER )
+ -- Function: long long LZ_compress_data_position ( struct LZ_Encoder *
+          const ENCODER )
      Returns the number of input bytes already compressed in the current
      member.
 
- -- Function: long long LZ_compress_member_position ( void * const
-          ENCODER )
+ -- Function: long long LZ_compress_member_position ( struct LZ_Encoder
+          * const ENCODER )
      Returns the number of compressed bytes already produced, but
      perhaps not yet read, in the current member.
 
- -- Function: long long LZ_compress_total_in_size ( void * const
-          ENCODER )
+ -- Function: long long LZ_compress_total_in_size ( struct LZ_Encoder *
+          const ENCODER )
      Returns the total number of input bytes already compressed.
 
- -- Function: long long LZ_compress_total_out_size ( void * const
-          ENCODER )
+ -- Function: long long LZ_compress_total_out_size ( struct LZ_Encoder
+          * const ENCODER )
      Returns the total number of compressed bytes already produced, but
      perhaps not yet read.
 
 
 File: lzlib.info,  Node: Decompression Functions,  Next: Error Codes,  Prev: Compression Functions,  Up: Top
 
-5 Decompression Functions
+6 Decompression Functions
 *************************
 
 These are the functions used to decompress data. In case of error, all
 of them return -1, except `LZ_decompress_open' whose return value must
 be verified by calling `LZ_decompress_errno' before using it.
 
- -- Function: void * LZ_decompress_open ( void )
+ -- Function: struct LZ_Decoder * LZ_decompress_open ( void )
      Initializes the internal stream state for decompression and
      returns a pointer that can only be used as the DECODER argument
-     for the other LZ_decompress functions.
+     for the other LZ_decompress functions, or a null pointer if the
+     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.
 
- -- Function: int LZ_decompress_close ( void * const DECODER )
+ -- 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
      can no more be used as an argument to any LZ_decompress function.
 
- -- Function: int LZ_decompress_finish ( void * const DECODER )
+ -- 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).
 
- -- Function: int LZ_decompress_read ( void * const DECODER, uint8_t *
-          const BUFFER, const int SIZE )
+ -- 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
+     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.
+
+     This function is useful to discard any data preceding the first
+     member, or to discard the rest of the current member, for example
+     in case of a data error. If the decoder is already at the
+     beginning of a member, this function does nothing.
+
+ -- 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
      stream pointed to by DECODER, storing the results in BUFFER.
 
@@ -281,8 +346,8 @@ be verified by calling `LZ_decompress_errno' before using it.
      `LZ_decompress_write' function. Note that reading less than SIZE
      bytes is not an error.
 
- -- Function: int LZ_decompress_write ( void * const DECODER, uint8_t *
-          const BUFFER, const int SIZE )
+ -- 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
      BUFFER to the stream pointed to by DECODER.
 
@@ -290,36 +355,47 @@ be verified by calling `LZ_decompress_errno' before using it.
      might be less than SIZE. Note that writing less than SIZE bytes is
      not an error.
 
- -- Function: enum LZ_errno LZ_decompress_errno ( void * const DECODER )
+ -- Function: int LZ_decompress_write_size ( struct LZ_Decoder * const
+          DECODER )
+     The `LZ_decompress_write_size' function returns the maximum number
+     of bytes that can be inmediately written through the
+     `LZ_decompress_write' function.
+
+     It is guaranteed that an inmediate 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 *
+          const DECODER )
      Returns the current error code for DECODER (*note Error Codes::)
 
- -- Function: int LZ_decompress_finished ( void * const DECODER )
+ -- Function: int LZ_decompress_finished ( struct LZ_Decoder * const
+          DECODER )
      Returns 1 if all the data has been read and `LZ_decompress_close'
      can be safely called. Otherwise it returns 0.
 
- -- Function: long long LZ_decompress_data_position ( void * const
-          DECODER )
+ -- Function: long long LZ_decompress_data_position ( struct LZ_Decoder
+          * const DECODER )
      Returns the number of decompressed bytes already produced, but
      perhaps not yet read, in the current member.
 
- -- Function: long long LZ_decompress_member_position ( void * const
-          DECODER )
+ -- Function: long long LZ_decompress_member_position ( struct
+          LZ_Decoder * const DECODER )
      Returns the number of input bytes already decompressed in the
      current member.
 
- -- Function: long long LZ_decompress_total_in_size ( void * const
-          DECODER )
+ -- Function: long long LZ_decompress_total_in_size ( struct LZ_Decoder
+          * const DECODER )
      Returns the total number of input bytes already decompressed.
 
- -- Function: long long LZ_decompress_total_out_size ( void * const
-          DECODER )
+ -- Function: long long LZ_decompress_total_out_size ( struct
+          LZ_Decoder * const DECODER )
      Returns the total number of decompressed bytes already produced,
      but perhaps not yet read.
 
 
-File: lzlib.info,  Node: Error Codes,  Next: Data Format,  Prev: Decompression Functions,  Up: Top
+File: lzlib.info,  Node: Error Codes,  Next: Error Messages,  Prev: Decompression Functions,  Up: Top
 
-6 Error Codes
+7 Error Codes
 *************
 
 Most library functions return -1 to indicate that they have failed. But
@@ -336,42 +412,58 @@ whether a call failed. If the call failed, then you can examine
 
    The error codes are defined in the header file `lzlib.h'.
 
- -- Constant: enum LZ_errno LZ_ok
+ -- Constant: enum LZ_Errno LZ_ok
      The value of this constant is 0 and is used to indicate that there
      is no error.
 
- -- Constant: enum LZ_errno LZ_bad_argument
+ -- Constant: enum LZ_Errno LZ_bad_argument
      At least one of the arguments passed to the library function was
      invalid.
 
- -- Constant: enum LZ_errno LZ_mem_error
+ -- Constant: enum LZ_Errno LZ_mem_error
      No memory available. The system cannot allocate more virtual memory
      because its capacity is full.
 
- -- Constant: enum LZ_errno LZ_sequence_error
+ -- 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
      finished.
 
- -- Constant: enum LZ_errno LZ_header_error
+ -- Constant: enum LZ_Errno LZ_header_error
      Reading of member header failed. If this happens at the end of the
      data stream it may indicate trailing garbage.
 
- -- Constant: enum LZ_errno LZ_unexpected_eof
+ -- Constant: enum LZ_Errno LZ_unexpected_eof
      The end of the data stream was reached in the middle of a member.
 
- -- Constant: enum LZ_errno LZ_data_error
+ -- Constant: enum LZ_Errno LZ_data_error
      The data stream is corrupt.
 
- -- Constant: enum LZ_errno LZ_library_error
+ -- Constant: enum LZ_Errno LZ_library_error
      A bug was detected in the library. Please, report it (*note
      Problems::).
 
 
-File: lzlib.info,  Node: Data Format,  Next: Examples,  Prev: Error Codes,  Up: Top
+File: lzlib.info,  Node: Error Messages,  Next: Data Format,  Prev: Error Codes,  Up: Top
+
+8 Error Messages
+****************
+
+ -- Function: const char * LZ_strerror ( const enum LZ_Errno LZ_ERRNO )
+     Returns the standard error message for a given error code. The
+     messages are fairly short; there are no multi-line messages or
+     embedded newlines.  This function makes it easy for your program
+     to report informative error messages about the failure of a
+     library call.
+
+     The value of LZ_ERRNO normally comes from a call to
+     `LZ_(de)compress_errno'.
+
+
+File: lzlib.info,  Node: Data Format,  Next: Examples,  Prev: Error Messages,  Up: Top
 
-7 Data Format
+9 Data Format
 *************
 
 In the diagram below, a box like this:
@@ -433,8 +525,8 @@ with no additional information before, between, or after them.
 
 File: lzlib.info,  Node: Examples,  Next: Problems,  Prev: Data Format,  Up: Top
 
-8 A small tutorial with examples
-********************************
+10 A small tutorial with examples
+*********************************
 
 This chaper shows the order in which the library functions should be
 called depending on what kind of data stream you want to compress or
@@ -453,7 +545,18 @@ Example 1: Normal compression (MEMBER_SIZE > total output).
      8) LZ_compress_close
 
 
-Example 2: Decompression.
+Example 2: Normal compression using LZ_compress_write_size.
+
+     1) LZ_compress_open
+     2) go to step 5 if LZ_compress_write_size returns 0
+     3) LZ_compress_write
+     4) if no more data to write, call LZ_compress_finish
+     5) LZ_compress_read
+     6) go back to step 2 until LZ_compress_finished returns 1
+     7) LZ_compress_close
+
+
+Example 3: Decompression.
 
      1) LZ_decompress_open
      2) LZ_decompress_write
@@ -465,24 +568,76 @@ Example 2: Decompression.
      8) LZ_decompress_close
 
 
-Example 3: Multimember compression (MEMBER_SIZE < total output).
+Example 4: Decompression using LZ_decompress_write_size.
+
+     1) LZ_decompress_open
+     2) go to step 5 if LZ_decompress_write_size returns 0
+     3) LZ_decompress_write
+     4) if no more data to write, call LZ_decompress_finish
+     5) LZ_decompress_read
+     6) go back to step 2 until LZ_decompress_finished returns 1
+     7) LZ_decompress_close
+
+
+Example 5: Multimember compression (MEMBER_SIZE < total output).
+
+      1) LZ_compress_open
+      2) go to step 5 if LZ_compress_write_size returns 0
+      3) LZ_compress_write
+      4) if no more data to write, call LZ_compress_finish
+      5) LZ_compress_read
+      6) go back to step 2 until LZ_compress_member_finished returns 1
+      7) go to step 10 if LZ_compress_finished() returns 1
+      8) LZ_compress_restart_member
+      9) go back to step 2
+     10) LZ_compress_close
+
+
+Example 6: Multimember compression (user-restarted members).
 
       1) LZ_compress_open
       2) LZ_compress_write
       3) LZ_compress_read
-      4) go back to step 2 until LZ_compress_member_finished returns 1
-      5) LZ_compress_restart_member
-      6) go back to step 2 until all input data has been written
-      7) LZ_compress_finish
-      8) LZ_compress_read
-      9) go back to step 8 until LZ_compress_finished returns 1
-     10) LZ_compress_close
+      4) go back to step 2 until member termination is desired
+      5) LZ_compress_finish
+      6) LZ_compress_read
+      7) go back to step 6 until LZ_compress_member_finished returns 1
+      8) verify that LZ_compress_finished returns 1
+      9) go to step 12 if all input data has been written
+     10) LZ_compress_restart_member
+     11) go back to step 2
+     12) LZ_compress_close
+
+
+Example 7: Decompression with automatic removal of leading garbage.
+
+     1) LZ_decompress_open
+     2) LZ_decompress_sync_to_member
+     3) go to step 6 if LZ_decompress_write_size returns 0
+     4) LZ_decompress_write
+     5) if no more data to write, call LZ_decompress_finish
+     6) LZ_decompress_read
+     7) go back to step 3 until LZ_decompress_finished returns 1
+     8) LZ_decompress_close
+
+
+Example 8: Streamed decompression with automatic resynchronization to
+next member in case of data error.
+
+     1) LZ_decompress_open
+     2) go to step 5 if LZ_decompress_write_size returns 0
+     3) LZ_decompress_write
+     4) if no more data to write, call LZ_decompress_finish
+     5) if LZ_decompress_read produces LZ_header_error or LZ_data_error,
+        call LZ_decompress_sync_to_member
+     6) go back to step 2 until LZ_decompress_finished returns 1
+     7) LZ_decompress_close
 
 
 File: lzlib.info,  Node: Problems,  Next: Concept Index,  Prev: Examples,  Up: Top
 
-9 Reporting Bugs
-****************
+11 Reporting Bugs
+*****************
 
 There are probably bugs in Lzlib. There are certainly errors and
 omissions in this manual. If you report them, they will get fixed. If
@@ -510,24 +665,28 @@ Concept Index
 * decompression functions:               Decompression Functions.
                                                                 (line 6)
 * error codes:                           Error Codes.           (line 6)
+* error messages:                        Error Messages.        (line 6)
 * examples:                              Examples.              (line 6)
 * getting help:                          Problems.              (line 6)
 * introduction:                          Introduction.          (line 6)
 * library version:                       Library Version.       (line 6)
+* parameter limits:                      Parameter Limits.      (line 6)
 
 
 
 Tag Table:
 Node: Top219
-Node: Introduction1028
-Node: Library Version2803
-Node: Buffering3448
-Node: Compression Functions4555
-Node: Decompression Functions10057
-Node: Error Codes13495
-Node: Data Format15431
-Node: Examples17398
-Node: Problems18832
-Node: Concept Index19402
+Node: Introduction1157
+Node: Library Version2932
+Node: Buffering3577
+Node: Parameter Limits4697
+Node: Compression Functions5654
+Node: Decompression Functions11700
+Node: Error Codes16762
+Node: Error Messages18701
+Node: Data Format19280
+Node: Examples21250
+Node: Problems24826
+Node: Concept Index25398
 
 End Tag Table
diff --git a/doc/lzlib.texinfo b/doc/lzlib.texinfo
index a824739..ae22e44 100644
--- a/doc/lzlib.texinfo
+++ b/doc/lzlib.texinfo
@@ -5,8 +5,8 @@
 @finalout
 @c %**end of header
 
-@set UPDATED 20 October 2009
-@set VERSION 0.7
+@set UPDATED 17 January 2010
+@set VERSION 0.8
 
 @dircategory Data Compression
 @direntry
@@ -35,9 +35,11 @@ This manual is for Lzlib (version @value{VERSION}, @value{UPDATED}).
 * Introduction::		Purpose and features of Lzlib
 * Library Version::		Checking library version
 * Buffering::			Sizes of Lzlib's buffers
+* Parameter Limits::		Min / max values for some parameters
 * Compression Functions::	Descriptions of the compression functions
 * Decompression Functions::	Descriptions of the decompression functions
 * Error Codes::			Meaning of codes returned by functions
+* Error Messages::		Error messages corresponding to error codes
 * Data Format::			Detailed format of the compressed data
 * Examples::			A small tutorial with examples
 * Problems::			Reporting bugs
@@ -45,7 +47,7 @@ This manual is for Lzlib (version @value{VERSION}, @value{UPDATED}).
 @end menu
 
 @sp 1
-Copyright @copyright{} 2009 Antonio Diaz Diaz.
+Copyright @copyright{} 2009, 2010 Antonio Diaz Diaz.
 
 This manual is free documentation: you have unlimited permission
 to copy, distribute and modify it.
@@ -139,11 +141,43 @@ is larger.
 
 @item Output decompression buffer. Read from by the
 @samp{LZ_decompress_read} function. Its size is the dictionary size set
-with the @samp{LZ_decompress_open} function or 64KiB, whichever is
-larger.
+in the header of the member currently being decompressed or 64KiB,
+whichever is larger.
 @end itemize
 
 
+@node Parameter Limits
+@chapter Parameter Limits
+@cindex parameter limits
+
+These functions provide minimum and maximum values for some parameters.
+Current values are shown in square brackets.
+
+@deftypefun int LZ_min_dictionary_bits ( void )
+Returns the base 2 logarithm of the smallest valid dictionary size [12].
+@end deftypefun
+
+@deftypefun int LZ_min_dictionary_size ( void )
+Returns the smallest valid dictionary size [4KiB].
+@end deftypefun
+
+@deftypefun int LZ_max_dictionary_bits ( void )
+Returns the base 2 logarithm of the largest valid dictionary size [29].
+@end deftypefun
+
+@deftypefun int LZ_max_dictionary_size ( void )
+Returns the largest valid dictionary size [512MiB].
+@end deftypefun
+
+@deftypefun int LZ_min_match_len_limit ( void )
+Returns the smallest valid match length limit [5].
+@end deftypefun
+
+@deftypefun int LZ_max_match_len_limit ( void )
+Returns the largest valid match length limit [273].
+@end deftypefun
+
+
 @node Compression Functions
 @chapter Compression Functions
 @cindex compression functions
@@ -153,10 +187,11 @@ them return -1, except @samp{LZ_compress_open} whose return value must
 be verified by calling @samp{LZ_compress_errno} before using it.
 
 
-@deftypefun {void *} LZ_compress_open ( const int @var{dictionary_size}, const int @var{match_len_limit}, const long long @var{member_size} )
+@deftypefun {struct LZ_Encoder *} LZ_compress_open ( const int @var{dictionary_size}, const int @var{match_len_limit}, const long long @var{member_size} )
 Initializes the internal stream state for compression and returns a
 pointer that can only be used as the @var{encoder} argument for the
-other LZ_compress functions.
+other LZ_compress functions, or a null pointer if the encoder could not
+be allocated.
 
 The returned pointer must be verified by calling
 @samp{LZ_compress_errno} before using it. If @samp{LZ_compress_errno}
@@ -180,15 +215,7 @@ for example LLONG_MAX.
 @end deftypefun
 
 
-@deftypefun int LZ_compress_restart_member ( void * const @var{encoder}, const long long @var{member_size} )
-Use this function to start a new member, in a multimember data stream.
-Call this function only after @samp{LZ_compress_member_finished}
-indicates that the current member has been fully read (with the
-@samp{LZ_compress_read} function).
-@end deftypefun
-
-
-@deftypefun int LZ_compress_close ( void * const @var{encoder} )
+@deftypefun int LZ_compress_close ( struct LZ_Encoder * const @var{encoder} )
 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 @samp{LZ_compress_close}, @var{encoder} can no
@@ -196,13 +223,24 @@ more be used as an argument to any LZ_compress function.
 @end deftypefun
 
 
-@deftypefun int LZ_compress_finish ( void * const @var{encoder} )
-Use this function to tell @samp{lzlib} that all the data for this stream
+@deftypefun int LZ_compress_finish ( struct LZ_Encoder * const @var{encoder} )
+Use this function to tell @samp{lzlib} that all the data for this member
 has already been written (with the @samp{LZ_compress_write} function).
+After all the produced compressed data has been read with
+@samp{LZ_compress_read} and @samp{LZ_compress_member_finished} returns
+1, a new member can be started with @samp{LZ_compress_restart_member}.
 @end deftypefun
 
 
-@deftypefun int LZ_compress_sync_flush ( void * const @var{encoder} )
+@deftypefun int LZ_compress_restart_member ( struct LZ_Encoder * const @var{encoder}, const long long @var{member_size} )
+Use this function to start a new member, in a multimember data stream.
+Call this function only after @samp{LZ_compress_member_finished}
+indicates that the current member has been fully read (with the
+@samp{LZ_compress_read} function).
+@end deftypefun
+
+
+@deftypefun int LZ_compress_sync_flush ( struct LZ_Encoder * const @var{encoder} )
 Use this function to make available to @samp{LZ_compress_read} all the
 data already written with the @samp{LZ_compress_write} function.
 Repeated use of @samp{LZ_compress_sync_flush} may degrade compression
@@ -210,7 +248,7 @@ ratio, so use it only when needed.
 @end deftypefun
 
 
-@deftypefun int LZ_compress_read ( void * const @var{encoder}, uint8_t * const @var{buffer}, const int @var{size} )
+@deftypefun int LZ_compress_read ( struct LZ_Encoder * const @var{encoder}, uint8_t * const @var{buffer}, const int @var{size} )
 The @samp{LZ_compress_read} function reads up to @var{size} bytes from
 the stream pointed to by @var{encoder}, storing the results in
 @var{buffer}.
@@ -223,7 +261,7 @@ in the stream or if more bytes have to be yet written with the
 @end deftypefun
 
 
-@deftypefun int LZ_compress_write ( void * const @var{encoder}, uint8_t * const @var{buffer}, const int @var{size} )
+@deftypefun int LZ_compress_write ( struct LZ_Encoder * const @var{encoder}, uint8_t * const @var{buffer}, const int @var{size} )
 The @samp{LZ_compress_write} function writes up to @var{size} bytes from
 @var{buffer} to the stream pointed to by @var{encoder}.
 
@@ -233,7 +271,7 @@ not an error.
 @end deftypefun
 
 
-@deftypefun int LZ_compress_write_size ( void * const @var{encoder} )
+@deftypefun int LZ_compress_write_size ( struct LZ_Encoder * const @var{encoder} )
 The @samp{LZ_compress_write_size} function returns the maximum number of
 bytes that can be inmediately written through the @samp{LZ_compress_write}
 function.
@@ -243,42 +281,42 @@ accept a @var{size} up to the returned number of bytes.
 @end deftypefun
 
 
-@deftypefun {enum LZ_errno} LZ_compress_errno ( void * const @var{encoder} )
+@deftypefun {enum LZ_Errno} LZ_compress_errno ( struct LZ_Encoder * const @var{encoder} )
 Returns the current error code for @var{encoder} (@pxref{Error Codes})
 @end deftypefun
 
 
-@deftypefun int LZ_compress_finished ( void * const @var{encoder} )
+@deftypefun int LZ_compress_finished ( struct LZ_Encoder * const @var{encoder} )
 Returns 1 if all the data has been read and @samp{LZ_compress_close} can
 be safely called. Otherwise it returns 0.
 @end deftypefun
 
 
-@deftypefun int LZ_compress_member_finished ( void * const @var{encoder} )
+@deftypefun int LZ_compress_member_finished ( struct LZ_Encoder * const @var{encoder} )
 Returns 1 if the current member, in a multimember data stream, has been
 fully read and @samp{LZ_compress_restart_member} can be safely called.
 Otherwise it returns 0.
 @end deftypefun
 
 
-@deftypefun {long long} LZ_compress_data_position ( void * const @var{encoder} )
+@deftypefun {long long} LZ_compress_data_position ( struct LZ_Encoder * const @var{encoder} )
 Returns the number of input bytes already compressed in the current
 member.
 @end deftypefun
 
 
-@deftypefun {long long} LZ_compress_member_position ( void * const @var{encoder} )
+@deftypefun {long long} LZ_compress_member_position ( struct LZ_Encoder * const @var{encoder} )
 Returns the number of compressed bytes already produced, but perhaps not
 yet read, in the current member.
 @end deftypefun
 
 
-@deftypefun {long long} LZ_compress_total_in_size ( void * const @var{encoder} )
+@deftypefun {long long} LZ_compress_total_in_size ( struct LZ_Encoder * const @var{encoder} )
 Returns the total number of input bytes already compressed.
 @end deftypefun
 
 
-@deftypefun {long long} LZ_compress_total_out_size ( void * const @var{encoder} )
+@deftypefun {long long} LZ_compress_total_out_size ( struct LZ_Encoder * const @var{encoder} )
 Returns the total number of compressed bytes already produced, but
 perhaps not yet read.
 @end deftypefun
@@ -293,10 +331,11 @@ of them return -1, except @samp{LZ_decompress_open} whose return value
 must be verified by calling @samp{LZ_decompress_errno} before using it.
 
 
-@deftypefun {void *} LZ_decompress_open ( void )
+@deftypefun {struct LZ_Decoder *} LZ_decompress_open ( void )
 Initializes the internal stream state for decompression and returns a
 pointer that can only be used as the @var{decoder} argument for the
-other LZ_decompress functions.
+other LZ_decompress functions, or a null pointer if the decoder could
+not be allocated.
 
 The returned pointer must be verified by calling
 @samp{LZ_decompress_errno} before using it. If
@@ -306,7 +345,7 @@ pointer must not be used and should be freed with
 @end deftypefun
 
 
-@deftypefun int LZ_decompress_close ( void * const @var{decoder} )
+@deftypefun int LZ_decompress_close ( struct LZ_Decoder * const @var{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 @samp{LZ_decompress_close}, @var{decoder} can no
@@ -314,13 +353,34 @@ more be used as an argument to any LZ_decompress function.
 @end deftypefun
 
 
-@deftypefun int LZ_decompress_finish ( void * const @var{decoder} )
+@deftypefun int LZ_decompress_finish ( struct LZ_Decoder * const @var{decoder} )
 Use this function to tell @samp{lzlib} that all the data for this stream
 has already been written (with the @samp{LZ_decompress_write} function).
 @end deftypefun
 
 
-@deftypefun int LZ_decompress_read ( void * const @var{decoder}, uint8_t * const @var{buffer}, const int @var{size} )
+@deftypefun int LZ_decompress_reset ( struct LZ_Decoder * const @var{decoder} )
+Resets the internal state of @var{decoder} as it was just after opening
+it with the @samp{LZ_decompress_open} function. Data stored in the
+internal buffers is discarded. Position counters are set to 0.
+@end deftypefun
+
+
+@deftypefun int LZ_decompress_sync_to_member ( struct LZ_Decoder * const @var{decoder} )
+Resets the error state of @var{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 @samp{LZ_decompress_sync_to_member}, data
+written with @samp{LZ_decompress_write} will be consumed and
+@samp{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 in case of a
+data error. If the decoder is already at the beginning of a member, this
+function does nothing.
+@end deftypefun
+
+
+@deftypefun int LZ_decompress_read ( struct LZ_Decoder * const @var{decoder}, uint8_t * const @var{buffer}, const int @var{size} )
 The @samp{LZ_decompress_read} function reads up to @var{size} bytes from
 the stream pointed to by @var{decoder}, storing the results in
 @var{buffer}.
@@ -333,7 +393,7 @@ in the stream or if more bytes have to be yet written with the
 @end deftypefun
 
 
-@deftypefun int LZ_decompress_write ( void * const @var{decoder}, uint8_t * const @var{buffer}, const int @var{size} )
+@deftypefun int LZ_decompress_write ( struct LZ_Decoder * const @var{decoder}, uint8_t * const @var{buffer}, const int @var{size} )
 The @samp{LZ_decompress_write} function writes up to @var{size} bytes from
 @var{buffer} to the stream pointed to by @var{decoder}.
 
@@ -343,35 +403,45 @@ not an error.
 @end deftypefun
 
 
-@deftypefun {enum LZ_errno} LZ_decompress_errno ( void * const @var{decoder} )
+@deftypefun int LZ_decompress_write_size ( struct LZ_Decoder * const @var{decoder} )
+The @samp{LZ_decompress_write_size} function returns the maximum number
+of bytes that can be inmediately written through the
+@samp{LZ_decompress_write} function.
+
+It is guaranteed that an inmediate call to @samp{LZ_decompress_write}
+will accept a @var{size} up to the returned number of bytes.
+@end deftypefun
+
+
+@deftypefun {enum LZ_Errno} LZ_decompress_errno ( struct LZ_Decoder * const @var{decoder} )
 Returns the current error code for @var{decoder} (@pxref{Error Codes})
 @end deftypefun
 
 
-@deftypefun int LZ_decompress_finished ( void * const @var{decoder} )
+@deftypefun int LZ_decompress_finished ( struct LZ_Decoder * const @var{decoder} )
 Returns 1 if all the data has been read and @samp{LZ_decompress_close}
 can be safely called. Otherwise it returns 0.
 @end deftypefun
 
 
-@deftypefun {long long} LZ_decompress_data_position ( void * const @var{decoder} )
+@deftypefun {long long} LZ_decompress_data_position ( struct LZ_Decoder * const @var{decoder} )
 Returns the number of decompressed bytes already produced, but perhaps
 not yet read, in the current member.
 @end deftypefun
 
 
-@deftypefun {long long} LZ_decompress_member_position ( void * const @var{decoder} )
+@deftypefun {long long} LZ_decompress_member_position ( struct LZ_Decoder * const @var{decoder} )
 Returns the number of input bytes already decompressed in the current
 member.
 @end deftypefun
 
 
-@deftypefun {long long} LZ_decompress_total_in_size ( void * const @var{decoder} )
+@deftypefun {long long} LZ_decompress_total_in_size ( struct LZ_Decoder * const @var{decoder} )
 Returns the total number of input bytes already decompressed.
 @end deftypefun
 
 
-@deftypefun {long long} LZ_decompress_total_out_size ( void * const @var{decoder} )
+@deftypefun {long long} LZ_decompress_total_out_size ( struct LZ_Decoder * const @var{decoder} )
 Returns the total number of decompressed bytes already produced, but
 perhaps not yet read.
 @end deftypefun
@@ -395,46 +465,61 @@ examine @samp{LZ_(de)compress_errno}.
 
 The error codes are defined in the header file @samp{lzlib.h}.
 
-@deftypevr Constant {enum LZ_errno} LZ_ok
+@deftypevr Constant {enum LZ_Errno} LZ_ok
 The value of this constant is 0 and is used to indicate that there is no
 error.
 @end deftypevr
 
-@deftypevr Constant {enum LZ_errno} LZ_bad_argument
+@deftypevr Constant {enum LZ_Errno} LZ_bad_argument
 At least one of the arguments passed to the library function was
 invalid.
 @end deftypevr
 
-@deftypevr Constant {enum LZ_errno} LZ_mem_error
+@deftypevr Constant {enum LZ_Errno} LZ_mem_error
 No memory available. The system cannot allocate more virtual memory
 because its capacity is full.
 @end deftypevr
 
-@deftypevr Constant {enum LZ_errno} LZ_sequence_error
+@deftypevr Constant {enum LZ_Errno} LZ_sequence_error
 A library function was called in the wrong order. For example
 @samp{LZ_compress_restart_member} was called before
 @samp{LZ_compress_member_finished} indicates that the current member is
 finished.
 @end deftypevr
 
-@deftypevr Constant {enum LZ_errno} LZ_header_error
+@deftypevr Constant {enum LZ_Errno} LZ_header_error
 Reading of member header failed. If this happens at the end of the data
 stream it may indicate trailing garbage.
 @end deftypevr
 
-@deftypevr Constant {enum LZ_errno} LZ_unexpected_eof
+@deftypevr Constant {enum LZ_Errno} LZ_unexpected_eof
 The end of the data stream was reached in the middle of a member.
 @end deftypevr
 
-@deftypevr Constant {enum LZ_errno} LZ_data_error
+@deftypevr Constant {enum LZ_Errno} LZ_data_error
 The data stream is corrupt.
 @end deftypevr
 
-@deftypevr Constant {enum LZ_errno} LZ_library_error
+@deftypevr Constant {enum LZ_Errno} LZ_library_error
 A bug was detected in the library. Please, report it (@pxref{Problems}).
 @end deftypevr
 
 
+@node Error Messages
+@chapter Error Messages
+@cindex error messages
+
+@deftypefun {const char *} LZ_strerror ( const enum LZ_Errno @var{lz_errno} )
+Returns the standard error message for a given error code. The messages
+are fairly short; there are no multi-line messages or embedded newlines.
+This function makes it easy for your program to report informative error
+messages about the failure of a library call.
+
+The value of @var{lz_errno} normally comes from a call to
+@samp{LZ_(de)compress_errno}.
+@end deftypefun
+
+
 @node Data Format
 @chapter Data Format
 @cindex data format
@@ -528,7 +613,22 @@ Example 1: Normal compression (@var{member_size} > total output).
 
 @sp 1
 @noindent
-Example 2: Decompression.
+Example 2: Normal compression using LZ_compress_write_size.
+
+@example
+1) LZ_compress_open
+2) go to step 5 if LZ_compress_write_size returns 0
+3) LZ_compress_write
+4) if no more data to write, call LZ_compress_finish
+5) LZ_compress_read
+6) go back to step 2 until LZ_compress_finished returns 1
+7) LZ_compress_close
+@end example
+
+
+@sp 1
+@noindent
+Example 3: Decompression.
 
 @example
 1) LZ_decompress_open
@@ -544,19 +644,87 @@ Example 2: Decompression.
 
 @sp 1
 @noindent
-Example 3: Multimember compression (@var{member_size} < total output).
+Example 4: Decompression using LZ_decompress_write_size.
+
+@example
+1) LZ_decompress_open
+2) go to step 5 if LZ_decompress_write_size returns 0
+3) LZ_decompress_write
+4) if no more data to write, call LZ_decompress_finish
+5) LZ_decompress_read
+6) go back to step 2 until LZ_decompress_finished returns 1
+7) LZ_decompress_close
+@end example
+
+
+@sp 1
+@noindent
+Example 5: Multimember compression (@var{member_size} < total output).
+
+@example
+ 1) LZ_compress_open
+ 2) go to step 5 if LZ_compress_write_size returns 0
+ 3) LZ_compress_write
+ 4) if no more data to write, call LZ_compress_finish
+ 5) LZ_compress_read
+ 6) go back to step 2 until LZ_compress_member_finished returns 1
+ 7) go to step 10 if LZ_compress_finished() returns 1
+ 8) LZ_compress_restart_member
+ 9) go back to step 2
+10) LZ_compress_close
+@end example
+
+
+@sp 1
+@noindent
+Example 6: Multimember compression (user-restarted members).
 
 @example
  1) LZ_compress_open
  2) LZ_compress_write
  3) LZ_compress_read
- 4) go back to step 2 until LZ_compress_member_finished returns 1
- 5) LZ_compress_restart_member
- 6) go back to step 2 until all input data has been written
- 7) LZ_compress_finish
- 8) LZ_compress_read
- 9) go back to step 8 until LZ_compress_finished returns 1
-10) LZ_compress_close
+ 4) go back to step 2 until member termination is desired
+ 5) LZ_compress_finish
+ 6) LZ_compress_read
+ 7) go back to step 6 until LZ_compress_member_finished returns 1
+ 8) verify that LZ_compress_finished returns 1
+ 9) go to step 12 if all input data has been written
+10) LZ_compress_restart_member
+11) go back to step 2
+12) LZ_compress_close
+@end example
+
+
+@sp 1
+@noindent
+Example 7: Decompression with automatic removal of leading garbage.
+
+@example
+1) LZ_decompress_open
+2) LZ_decompress_sync_to_member
+3) go to step 6 if LZ_decompress_write_size returns 0
+4) LZ_decompress_write
+5) if no more data to write, call LZ_decompress_finish
+6) LZ_decompress_read
+7) go back to step 3 until LZ_decompress_finished returns 1
+8) LZ_decompress_close
+@end example
+
+
+@sp 1
+@noindent
+Example 8: Streamed decompression with automatic resynchronization to
+next member in case of data error.
+
+@example
+1) LZ_decompress_open
+2) go to step 5 if LZ_decompress_write_size returns 0
+3) LZ_decompress_write
+4) if no more data to write, call LZ_decompress_finish
+5) if LZ_decompress_read produces LZ_header_error or LZ_data_error,
+   call LZ_decompress_sync_to_member
+6) go back to step 2 until LZ_decompress_finished returns 1
+7) LZ_decompress_close
 @end example