Merging upstream version 1.12.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 595 insertions, 307 deletions

diff --git a/doc/lzlib.texi b/doc/lzlib.texi
index 55e80c2..644a3d7 100644
--- a/doc/lzlib.texi
+++ b/doc/lzlib.texi
@@ -6,8 +6,8 @@
 @finalout
 @c %**end of header
 
-@set UPDATED 2 January 2019
-@set VERSION 1.11
+@set UPDATED 2 January 2021
+@set VERSION 1.12
 
 @dircategory Data Compression
 @direntry
@@ -29,6 +29,7 @@
 @contents
 @end ifnothtml
 
+@ifnottex
 @node Top
 @top
 
@@ -51,20 +52,22 @@ This manual is for Lzlib (version @value{VERSION}, @value{UPDATED}).
 @end menu
 
 @sp 1
-Copyright @copyright{} 2009-2019 Antonio Diaz Diaz.
+Copyright @copyright{} 2009-2021 Antonio Diaz Diaz.
 
-This manual is free documentation: you have unlimited permission
-to copy, distribute and modify it.
+This manual is free documentation: you have unlimited permission to copy,
+distribute, and modify it.
+@end ifnottex
 
 
 @node Introduction
 @chapter Introduction
 @cindex introduction
 
-@uref{http://www.nongnu.org/lzip/lzlib.html,,Lzlib} is a data compression
-library providing in-memory LZMA compression and decompression functions,
-including integrity checking of the decompressed data. The compressed data
-format used by the library is the lzip format. Lzlib is written in C.
+@uref{http://www.nongnu.org/lzip/lzlib.html,,Lzlib}
+is a data compression library providing in-memory LZMA compression and
+decompression functions, including integrity checking of the decompressed
+data. The compressed data format used by the library is the lzip format.
+Lzlib is written in C.
 
 The lzip file format is designed for data sharing and long-term archiving,
 taking into account both data integrity and decoder availability:
@@ -72,9 +75,9 @@ taking into account both data integrity and decoder availability:
 @itemize @bullet
 @item
 The lzip format provides very safe integrity checking and some data
-recovery means. The
+recovery means. The program
 @uref{http://www.nongnu.org/lzip/manual/lziprecover_manual.html#Data-safety,,lziprecover}
-program can repair bit flip errors (one of the most common forms of data
+can repair bit flip errors (one of the most common forms of data
 corruption) in lzip files, and provides data recovery capabilities,
 including error-checked merging of damaged copies of a file.
 @ifnothtml
@@ -94,42 +97,42 @@ Additionally the lzip reference implementation is copylefted, which
 guarantees that it will remain free forever.
 @end itemize
 
-A nice feature of the lzip format is that a corrupt byte is easier to
-repair the nearer it is from the beginning of the file. Therefore, with
-the help of lziprecover, losing an entire archive just because of a
-corrupt byte near the beginning is a thing of the past.
+A nice feature of the lzip format is that a corrupt byte is easier to repair
+the nearer it is from the beginning of the file. Therefore, with the help of
+lziprecover, losing an entire archive just because of a corrupt byte near
+the beginning is a thing of the past.
 
-The functions and variables forming the interface of the compression
-library are declared in the file @samp{lzlib.h}. Usage examples of the
-library are given in the files @samp{main.c} and @samp{bbexample.c} from
-the source distribution.
+The functions and variables forming the interface of the compression library
+are declared in the file @samp{lzlib.h}. Usage examples of the library are
+given in the files @samp{bbexample.c}, @samp{ffexample.c}, and @samp{main.c}
+from the source distribution.
 
 Compression/decompression is done by repeatedly calling a couple of
-read/write functions until all the data have been processed by the
-library. This interface is safer and less error prone than the
-traditional zlib interface.
+read/write functions until all the data have been processed by the library.
+This interface is safer and less error prone than the traditional zlib
+interface.
 
 Compression/decompression is done when the read function is called. This
-means the value returned by the position functions will not be updated
-until a read call, even if a lot of data are written. If you want the
-data to be compressed in advance, just call the read function with a
-@var{size} equal to 0.
+means the value returned by the position functions will not be updated until
+a read call, even if a lot of data are written. If you want the data to be
+compressed in advance, just call the read function with a @var{size} equal
+to 0.
 
 If all the data to be compressed are written in advance, lzlib will
-automatically adjust the header of the compressed data to use the
-largest dictionary size that does not exceed neither the data size nor
-the limit given to @samp{LZ_compress_open}. This feature reduces the
-amount of memory needed for decompression and allows minilzip to produce
-identical compressed output as lzip.
+automatically adjust the header of the compressed data to use the largest
+dictionary size that does not exceed neither the data size nor the limit
+given to @samp{LZ_compress_open}. This feature reduces the amount of memory
+needed for decompression and allows minilzip to produce identical compressed
+output as lzip.
 
-Lzlib will correctly decompress a data stream which is the concatenation
-of two or more compressed data streams. The result is the concatenation
-of the corresponding decompressed data streams. Integrity testing of
-concatenated compressed data streams is also supported.
+Lzlib will correctly decompress a data stream which is the concatenation of
+two or more compressed data streams. The result is the concatenation of the
+corresponding decompressed data streams. Integrity testing of concatenated
+compressed data streams is also supported.
 
 Lzlib is able to compress and decompress streams of unlimited size by
-automatically creating multimember output. The members so created are
-large, about @w{2 PiB} each.
+automatically creating multimember output. The members so created are large,
+about @w{2 PiB} each.
 
 All the library functions are thread safe. The library does not install
 any signal handler. The decoder checks the consistency of the compressed
@@ -139,14 +142,14 @@ In spite of its name (Lempel-Ziv-Markov chain-Algorithm), LZMA is not a
 concrete algorithm; it is more like "any algorithm using the LZMA coding
 scheme". For example, the option @samp{-0} of lzip uses the scheme in almost
 the simplest way possible; issuing the longest match it can find, or a
-literal byte if it can't find a match. Inversely, a much more elaborated
-way of finding coding sequences of minimum size than the one currently
-used by lzip could be developed, and the resulting sequence could also
-be coded using the LZMA coding scheme.
+literal byte if it can't find a match. Inversely, a much more elaborated way
+of finding coding sequences of minimum size than the one currently used by
+lzip could be developed, and the resulting sequence could also be coded
+using the LZMA coding scheme.
 
-Lzlib currently implements two variants of the LZMA algorithm; fast
-(used by option @samp{-0} of minilzip) and normal (used by all other
-compression levels).
+Lzlib currently implements two variants of the LZMA algorithm; fast (used by
+option @samp{-0} of minilzip) and normal (used by all other compression
+levels).
 
 The high compression of LZMA comes from combining two basic, well-proven
 compression ideas: sliding dictionaries (LZ77/78) and markov models (the
@@ -155,37 +158,74 @@ similar order-0 entropy coder as its last stage) with segregation of
 contexts according to what the bits are used for.
 
 The ideas embodied in lzlib are due to (at least) the following people:
-Abraham Lempel and Jacob Ziv (for the LZ algorithm), Andrey Markov (for
-the definition of Markov chains), G.N.N. Martin (for the definition of
-range encoding), Igor Pavlov (for putting all the above together in
-LZMA), and Julian Seward (for bzip2's CLI).
+Abraham Lempel and Jacob Ziv (for the LZ algorithm), Andrey Markov (for the
+definition of Markov chains), G.N.N. Martin (for the definition of range
+encoding), Igor Pavlov (for putting all the above together in LZMA), and
+Julian Seward (for bzip2's CLI).
 
-LANGUAGE NOTE: Uncompressed = not compressed = plain data; it may never
-have been compressed. Decompressed is used to refer to data which have
-undergone the process of decompression.
+LANGUAGE NOTE: Uncompressed = not compressed = plain data; it may never have
+been compressed. Decompressed is used to refer to data which have undergone
+the process of decompression.
 
 
 @node Library version
 @chapter Library version
 @cindex library version
 
-@deftypefun {const char *} LZ_version ( void )
-Returns the library version as a string.
-@end deftypefun
+One goal of lzlib is to keep perfect backward compatibility with older
+versions of itself down to 1.0. Any application working with an older lzlib
+should work with a newer lzlib. Installing a newer lzlib should not break
+anything. This chapter describes the constants and functions that the
+application can use to discover the version of the library being used.
 
-@deftypevr Constant {const char *} LZ_version_string
-This constant is defined in the header file @samp{lzlib.h}.
-@end deftypevr
+@defvr Constant LZ_API_VERSION
+This constant is defined in @samp{lzlib.h} and works as a version test
+macro. The application should verify at compile time that LZ_API_VERSION is
+greater than or equal to the version required by the application:
 
-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 @samp{lzlib.h} header file used by the
-application.
+@example
+#if !defined LZ_API_VERSION || LZ_API_VERSION < 1012
+#error "lzlib 1.12 or newer needed."
+#endif
+@end example
+
+Before version 1.8, lzlib didn't define LZ_API_VERSION.@*
+LZ_API_VERSION was first defined in lzlib 1.8 to 1.@*
+Since lzlib 1.12, LZ_API_VERSION is defined as (major * 1000 + minor).
+@end defvr
+
+NOTE: Version test macros are the library's way of announcing functionality
+to the application. They should not be confused with feature test macros,
+which allow the application to announce to the library its desire to have
+certain symbols and prototypes exposed.
+
+@deftypefun int LZ_api_version ( void )
+If LZ_API_VERSION >= 1012, this function is declared in @samp{lzlib.h} (else
+it doesn't exist). It returns the LZ_API_VERSION of the library object code
+being used. The application should verify at run time that the value
+returned by @code{LZ_api_version} is greater than or equal to the version
+required by the application. An application may be dinamically linked at run
+time with a different version of lzlib than the one it was compiled for, and
+this should not break the program as long as the library used provides the
+functionality required by the application.
 
 @example
-if( LZ_version()[0] != LZ_version_string[0] )
-  error( "bad library version" );
+#if defined LZ_API_VERSION && LZ_API_VERSION >= 1012
+  if( LZ_api_version() < 1012 )
+    show_error( "lzlib 1.12 or newer needed." );
+#endif
 @end example
+@end deftypefun
+
+@deftypevr Constant {const char *} LZ_version_string
+This string constant is defined in the header file @samp{lzlib.h} and
+represents the version of the library being used at compile time.
+@end deftypevr
+
+@deftypefun {const char *} LZ_version ( void )
+This function returns a string representing the version of the library being
+used at run time.
+@end deftypefun
 
 
 @node Buffering
@@ -199,26 +239,23 @@ dictionary size.
 
 Finally, for safety reasons, lzlib uses two more internal buffers.
 
-These are the four buffers used by lzlib, and their guaranteed minimum
-sizes:
+These are the four buffers used by lzlib, and their guaranteed minimum sizes:
 
 @itemize @bullet
-@item Input compression buffer. Written to by the
-@samp{LZ_compress_write} function. For the normal variant of LZMA, its
-size is two times the dictionary size set with the
-@samp{LZ_compress_open} function or @w{64 KiB}, whichever is larger. For
-the fast variant, its size is @w{1 MiB}.
-
-@item Output compression buffer. Read from by the
-@samp{LZ_compress_read} function. Its size is @w{64 KiB}.
-
-@item Input decompression buffer. Written to by the
-@samp{LZ_decompress_write} function. Its size is @w{64 KiB}.
-
-@item Output decompression buffer. Read from by the
-@samp{LZ_decompress_read} function. Its size is the dictionary size set
-in the header of the member currently being decompressed or @w{64 KiB},
-whichever is larger.
+@item Input compression buffer. Written to by the function
+@samp{LZ_compress_write}. For the normal variant of LZMA, its size is two
+times the dictionary size set with the function @samp{LZ_compress_open} or
+@w{64 KiB}, whichever is larger. For the fast variant, its size is @w{1 MiB}.
+
+@item Output compression buffer. Read from by the function
+@samp{LZ_compress_read}. Its size is @w{64 KiB}.
+
+@item Input decompression buffer. Written to by the function
+@samp{LZ_decompress_write}. Its size is @w{64 KiB}.
+
+@item Output decompression buffer. Read from by the function
+@samp{LZ_decompress_read}. Its size is the dictionary size set in the header
+of the member currently being decompressed or @w{64 KiB}, whichever is larger.
 @end itemize
 
 
@@ -277,26 +314,26 @@ should be freed with @samp{LZ_compress_close} to avoid memory leaks.
 
 @var{dictionary_size} sets the dictionary size to be used, in bytes.
 Valid values range from @w{4 KiB} to @w{512 MiB}. Note that dictionary
-sizes are quantized. If the specified size does not match one of the
+sizes are quantized. If the size specified does not match one of the
 valid sizes, it will be rounded upwards by adding up to
 @w{(@var{dictionary_size} / 8)} to it.
 
 @var{match_len_limit} sets the match length limit in bytes. Valid values
-range from 5 to 273. Larger values usually give better compression
-ratios but longer compression times.
-
-If @var{dictionary_size} is 65535 and @var{match_len_limit} is 16, the
-fast variant of LZMA is chosen, which produces identical compressed
-output as @code{lzip -0}. (The dictionary size used will be rounded
-upwards to @w{64 KiB}).
-
-@var{member_size} sets the member size limit in bytes. Valid values
-range from @w{100 kB} to @w{2 PiB}. Small member size may degrade
-compression ratio, so use it only when needed. To produce a
-single-member data stream, give @var{member_size} a value larger than
-the amount of data to be produced. Values larger than @w{2 PiB} will be
-reduced to @w{2 PiB} to prevent the uncompressed size of the member from
-overflowing.
+range from 5 to 273. Larger values usually give better compression ratios
+but longer compression times.
+
+If @var{dictionary_size} is 65535 and @var{match_len_limit} is 16, the fast
+variant of LZMA is chosen, which produces identical compressed output as
+@w{@samp{lzip -0}}. (The dictionary size used will be rounded upwards to
+@w{64 KiB}).
+
+@anchor{member_size}
+@var{member_size} sets the member size limit in bytes. Valid values range
+from @w{4 KiB} to @w{2 PiB}. A small member size may degrade compression
+ratio, so use it only when needed. To produce a single-member data stream,
+give @var{member_size} a value larger than the amount of data to be
+produced. Values larger than @w{2 PiB} will be reduced to @w{2 PiB} to
+prevent the uncompressed size of the member from overflowing.
 @end deftypefun
 
 
@@ -305,53 +342,73 @@ 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
 longer be used as an argument to any LZ_compress function.
+It is safe to call @samp{LZ_compress_close} with a null argument.
 @end deftypefun
 
 
 @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
-have already been written (with the @samp{LZ_compress_write} function).
+have already been written (with the function @samp{LZ_compress_write}).
 It is safe to call @samp{LZ_compress_finish} as many times as needed.
-After all the produced compressed data have 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}.
+After all the compressed data have 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_restart_member ( struct LZ_Encoder * const @var{encoder}, const unsigned 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).
+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 function
+@samp{LZ_compress_read}). @xref{member_size}, for a description of
+@var{member_size}.
 @end deftypefun
 
 
+@anchor{sync_flush}
 @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. First
-call @samp{LZ_compress_sync_flush}. Then call @samp{LZ_compress_read}
-until it returns 0.
+Use this function to make available to @samp{LZ_compress_read} all the data
+already written with the function @samp{LZ_compress_write}. First call
+@samp{LZ_compress_sync_flush}. Then call @samp{LZ_compress_read} until it
+returns 0.
+
+This function writes a LZMA marker @samp{3} ("Sync Flush" marker) to the
+compressed output. Note that the sync flush marker is not allowed in lzip
+files; it is a device for interactive communication between applications
+using lzlib, but is useless and wasteful in a file, and is excluded from the
+media type @samp{application/lzip}. The LZMA marker @samp{2} ("End Of
+Stream" marker) is the only marker allowed in lzip files. @xref{Data format}.
 
 Repeated use of @samp{LZ_compress_sync_flush} may degrade compression
-ratio, so use it only when needed.
+ratio, so use it only when needed. If the interval between calls to
+@samp{LZ_compress_sync_flush} is large (comparable to dictionary size),
+creating a multimember data stream with @samp{LZ_compress_restart_member}
+may be an alternative.
+
+Combining multimember stream creation with flushing may be tricky. If there
+are more bytes available than those needed to complete @var{member_size},
+@samp{LZ_compress_restart_member} needs to be called when
+@samp{LZ_compress_member_finished} returns 1, followed by a new call to
+@samp{LZ_compress_sync_flush}.
 @end deftypefun
 
 
 @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}.
-
-The return value is the number of bytes actually read. This might be
-less than @var{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
-@samp{LZ_compress_write} function. Note that reading less than
-@var{size} bytes is not an error.
+The function @samp{LZ_compress_read} reads up to @var{size} bytes from the
+stream pointed to by @var{encoder}, storing the results in @var{buffer}.
+If @w{LZ_API_VERSION >= 1012}, @var{buffer} may be a null pointer, in which
+case the bytes read are discarded.
+
+The return value is the number of bytes actually read. This might be less
+than @var{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 function
+@samp{LZ_compress_write}. Note that reading less than @var{size} bytes is
+not an error.
 @end deftypefun
 
 
 @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
+The function @samp{LZ_compress_write} writes up to @var{size} bytes from
 @var{buffer} to the stream pointed to by @var{encoder}.
 
 The return value is the number of bytes actually written. This might be
@@ -361,9 +418,13 @@ not an error.
 
 
 @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 immediately written through the @samp{LZ_compress_write}
-function.
+The function @samp{LZ_compress_write_size} returns the maximum number of
+bytes that can be immediately written through @samp{LZ_compress_write}.
+For efficiency reasons, once the input buffer is full and
+@samp{LZ_compress_write_size} returns 0, almost all the buffer must be
+compressed before a size greater than 0 is returned again. (This is done to
+minimize the amount of data that must be copied to the beginning of the
+buffer before new data can be accepted).
 
 It is guaranteed that an immediate call to @samp{LZ_compress_write} will
 accept a @var{size} up to the returned number of bytes.
@@ -372,6 +433,8 @@ accept a @var{size} up to the returned number of bytes.
 
 @deftypefun {enum LZ_Errno} LZ_compress_errno ( struct LZ_Encoder * const @var{encoder} )
 Returns the current error code for @var{encoder}. @xref{Error codes}.
+It is safe to call @samp{LZ_compress_errno} with a null argument, in which
+case it returns @samp{LZ_bad_argument}.
 @end deftypefun
 
 
@@ -390,8 +453,7 @@ Otherwise it returns 0.
 
 
 @deftypefun {unsigned long long} LZ_compress_data_position ( struct LZ_Encoder * const @var{encoder} )
-Returns the number of input bytes already compressed in the current
-member.
+Returns the number of input bytes already compressed in the current member.
 @end deftypefun
 
 
@@ -441,19 +503,23 @@ 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
 longer be used as an argument to any LZ_decompress function.
+It is safe to call @samp{LZ_decompress_close} with a null argument.
 @end deftypefun
 
 
 @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
-have already been written (with the @samp{LZ_decompress_write} function).
+have already been written (with the function @samp{LZ_decompress_write}).
 It is safe to call @samp{LZ_decompress_finish} as many times as needed.
+It is not required to call @samp{LZ_decompress_finish} if the input stream
+only contains whole members, but not calling it prevents lzlib from
+detecting a truncated member.
 @end deftypefun
 
 
 @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
+it with the function @samp{LZ_decompress_open}. Data stored in the
 internal buffers is discarded. Position counters are set to 0.
 @end deftypefun
 
@@ -473,19 +539,28 @@ function does nothing.
 
 
 @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}.
+The function @samp{LZ_decompress_read} reads up to @var{size} bytes from the
+stream pointed to by @var{decoder}, storing the results in @var{buffer}.
+If @w{LZ_API_VERSION >= 1012}, @var{buffer} may be a null pointer, in which
+case the bytes read are discarded.
+
+The return value is the number of bytes actually read. This might be less
+than @var{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 function
+@samp{LZ_decompress_write}. Note that reading less than @var{size} bytes is
+not an error.
 
-The return value is the number of bytes actually read. This might be
-less than @var{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
-@samp{LZ_decompress_write} function. Note that reading less than
-@var{size} bytes is not an error.
+@samp{LZ_decompress_read} returns at least once per member so that
+@samp{LZ_decompress_member_finished} can be called (and trailer data
+retrieved) for each member, even for empty members. Therefore,
+@samp{LZ_decompress_read} returning 0 does not mean that the end of the
+stream has been reached. The increase in the value returned by
+@samp{LZ_decompress_total_in_size} can be used to tell the end of the stream
+from an empty member.
 
 In case of decompression error caused by corrupt or truncated data,
 @samp{LZ_decompress_read} does not signal the error immediately to the
-application, but waits until all decoded bytes have been read. This
+application, but waits until all the bytes decoded have been read. This
 allows tools like
 @uref{http://www.nongnu.org/lzip/manual/tarlz_manual.html,,tarlz} to
 recover as much data as possible from each damaged member.
@@ -496,7 +571,7 @@ recover as much data as possible from each damaged member.
 
 
 @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
+The function @samp{LZ_decompress_write} writes up to @var{size} bytes from
 @var{buffer} to the stream pointed to by @var{decoder}.
 
 The return value is the number of bytes actually written. This might be
@@ -506,32 +581,35 @@ not an error.
 
 
 @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 immediately written through the
-@samp{LZ_decompress_write} function.
+The function @samp{LZ_decompress_write_size} returns the maximum number of
+bytes that can be immediately written through @samp{LZ_decompress_write}.
+This number varies smoothly; each compressed byte consumed may be
+overwritten immediately, increasing by 1 the value returned.
 
-It is guaranteed that an immediate call to @samp{LZ_decompress_write}
-will accept a @var{size} up to the returned number of bytes.
+It is guaranteed that an immediate 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}. @xref{Error codes}.
+It is safe to call @samp{LZ_decompress_errno} with a null argument, in which
+case it returns @samp{LZ_bad_argument}.
 @end deftypefun
 
 
 @deftypefun int LZ_decompress_finished ( struct LZ_Decoder * const @var{decoder} )
 Returns 1 if all the data have been read and @samp{LZ_decompress_close}
-can be safely called. Otherwise it returns 0.
+can be safely called. Otherwise it returns 0. @samp{LZ_decompress_finished}
+does not imply @samp{LZ_decompress_member_finished}.
 @end deftypefun
 
 
 @deftypefun int LZ_decompress_member_finished ( struct LZ_Decoder * const @var{decoder} )
-Returns 1 if the previous call to @samp{LZ_decompress_read} finished
-reading the current member, indicating that final values for member are
-available through @samp{LZ_decompress_data_crc},
-@samp{LZ_decompress_data_position}, and
-@samp{LZ_decompress_member_position}. Otherwise it returns 0.
+Returns 1 if the previous call to @samp{LZ_decompress_read} finished reading
+the current member, indicating that final values for member are available
+through @samp{LZ_decompress_data_crc}, @samp{LZ_decompress_data_position},
+and @samp{LZ_decompress_member_position}. Otherwise it returns 0.
 @end deftypefun
 
 
@@ -541,7 +619,8 @@ Returns the version of current member from member header.
 
 
 @deftypefun int LZ_decompress_dictionary_size ( struct LZ_Decoder * const @var{decoder} )
-Returns the dictionary size of current member from member header.
+Returns the dictionary size of the current member, read from the member
+header.
 @end deftypefun
 
 
@@ -559,8 +638,7 @@ not yet read, in the current member.
 
 
 @deftypefun {unsigned long long} LZ_decompress_member_position ( struct LZ_Decoder * const @var{decoder} )
-Returns the number of input bytes already decompressed in the current
-member.
+Returns the number of input bytes already decompressed in the current member.
 @end deftypefun
 
 
@@ -599,8 +677,7 @@ error.
 @end deftypevr
 
 @deftypevr Constant {enum LZ_Errno} LZ_bad_argument
-At least one of the arguments passed to the library function was
-invalid.
+At least one of the arguments passed to the library function was invalid.
 @end deftypevr
 
 @deftypevr Constant {enum LZ_Errno} LZ_mem_error
@@ -617,8 +694,7 @@ finished.
 
 @deftypevr Constant {enum LZ_Errno} LZ_header_error
 An invalid member header (one with the wrong magic bytes) was read. If
-this happens at the end of the data stream it may indicate trailing
-data.
+this happens at the end of the data stream it may indicate trailing data.
 @end deftypevr
 
 @deftypevr Constant {enum LZ_Errno} LZ_unexpected_eof
@@ -658,9 +734,20 @@ The value of @var{lz_errno} normally comes from a call to
 @cindex invoking
 @cindex options
 
-Minilzip is a test program for the lzlib compression library, fully
+Minilzip is a test program for the compression library lzlib, fully
 compatible with lzip 1.4 or newer.
 
+@uref{http://www.nongnu.org/lzip/lzip.html,,Lzip} is a lossless data
+compressor with a user interface similar to the one of gzip or bzip2. Lzip
+uses a simplified form of the 'Lempel-Ziv-Markov chain-Algorithm' (LZMA)
+stream format, chosen to maximize safety and interoperability. Lzip can
+compress about as fast as gzip @w{(lzip -0)} or compress most files more
+than bzip2 @w{(lzip -9)}. Decompression speed is intermediate between gzip
+and bzip2. Lzip is better than gzip and bzip2 from a data recovery
+perspective. Lzip has been designed, written, and tested with great care to
+replace gzip and bzip2 as the standard general-purpose compressed format for
+unix-like systems.
+
 @noindent
 The format for running minilzip is:
 
@@ -669,11 +756,16 @@ minilzip [@var{options}] [@var{files}]
 @end example
 
 @noindent
-@samp{-} used as a @var{file} argument means standard input. It can be
-mixed with other @var{files} and is read just once, the first time it
-appears in the command line.
+If no file names are specified, minilzip compresses (or decompresses) from
+standard input to standard output. A hyphen @samp{-} used as a @var{file}
+argument means standard input. It can be mixed with other @var{files} and is
+read just once, the first time it appears in the command line.
 
-minilzip supports the following options:
+minilzip supports the following
+@uref{http://www.nongnu.org/arg-parser/manual/arg_parser_manual.html#Argument-syntax,,options}:
+@ifnothtml
+@xref{Argument syntax,,,arg_parser}.
+@end ifnothtml
 
 @table @code
 @item -h
@@ -685,7 +777,6 @@ Print an informative help message describing the options and exit.
 Print the version number of minilzip on the standard output and exit.
 This version number should be included in all bug reports.
 
-@anchor{--trailing-error}
 @item -a
 @itemx --trailing-error
 Exit with error status 2 if any remaining input is detected after
@@ -694,21 +785,25 @@ garbage that can be safely ignored.
 
 @item -b @var{bytes}
 @itemx --member-size=@var{bytes}
-When compressing, set the member size limit to @var{bytes}. A small
-member size may degrade compression ratio, so use it only when needed.
-Valid values range from @w{100 kB} to @w{2 PiB}. Defaults to @w{2 PiB}.
+When compressing, set the member size limit to @var{bytes}. It is advisable
+to keep members smaller than RAM size so that they can be repaired with
+lziprecover in case of corruption. A small member size may degrade
+compression ratio, so use it only when needed. Valid values range from
+@w{100 kB} to @w{2 PiB}. Defaults to @w{2 PiB}.
 
 @item -c
 @itemx --stdout
-Compress or decompress to standard output; keep input files unchanged.
-If compressing several files, each file is compressed independently.
-This option is needed when reading from a named pipe (fifo) or from a
-device. Use it also to recover as much of the decompressed data as
-possible when decompressing a corrupt file.
+Compress or decompress to standard output; keep input files unchanged. If
+compressing several files, each file is compressed independently. (The
+output consists of a sequence of independently compressed members). This
+option (or @samp{-o}) is needed when reading from a named pipe (fifo) or
+from a device. Use it also to recover as much of the decompressed data as
+possible when decompressing a corrupt file. @samp{-c} overrides @samp{-o}
+and @samp{-S}. @samp{-c} has no effect when testing or listing.
 
 @item -d
 @itemx --decompress
-Decompress the specified files. If a file does not exist or can't be
+Decompress the files specified. If a file does not exist or can't be
 opened, minilzip continues decompressing the rest of the files. If a file
 fails to decompress, or is a terminal, minilzip exits immediately without
 decompressing the rest of the files.
@@ -735,14 +830,17 @@ compression times.
 
 @item -o @var{file}
 @itemx --output=@var{file}
-When reading from standard input and @samp{--stdout} has not been
-specified, use @samp{@var{file}} as the virtual name of the uncompressed
-file. This produces a file named @samp{@var{file}} when decompressing,
-or a file named @samp{@var{file}.lz} when compressing. A second
-@samp{.lz} extension is not added if @samp{@var{file}} already ends in
-@samp{.lz} or @samp{.tlz}. When compressing and splitting the output in
-volumes, several files named @samp{@var{file}00001.lz},
-@samp{@var{file}00002.lz}, etc, are created.
+If @samp{-c} has not been also specified, write the (de)compressed output to
+@var{file}; keep input files unchanged. If compressing several files, each
+file is compressed independently. (The output consists of a sequence of
+independently compressed members). This option (or @samp{-c}) is needed when
+reading from a named pipe (fifo) or from a device. @w{@samp{-o -}} is
+equivalent to @samp{-c}. @samp{-o} has no effect when testing or listing.
+
+When compressing and splitting the output in volumes, @var{file} is used as
+a prefix, and several files named @samp{@var{file}00001.lz},
+@samp{@var{file}00002.lz}, etc, are created. In this case, only one input
+file is allowed.
 
 @item -q
 @itemx --quiet
@@ -755,7 +853,7 @@ for each file the largest dictionary size that does not exceed neither
 the file size nor this limit. Valid values range from @w{4 KiB} to
 @w{512 MiB}. Values 12 to 29 are interpreted as powers of two, meaning
 2^12 to 2^29 bytes. Dictionary sizes are quantized so that they can be
-coded in just one byte (@pxref{coded-dict-size}). If the specified size
+coded in just one byte (@pxref{coded-dict-size}). If the size specified
 does not match one of the valid sizes, it will be rounded upwards by
 adding up to @w{(@var{bytes} / 8)} to it.
 
@@ -765,16 +863,17 @@ is affected at compression time by the choice of dictionary size limit.
 
 @item -S @var{bytes}
 @itemx --volume-size=@var{bytes}
-When compressing, split the compressed output into several volume files
-with names @samp{original_name00001.lz}, @samp{original_name00002.lz},
-etc, and set the volume size limit to @var{bytes}. Input files are kept
-unchanged. Each volume is a complete, maybe multimember, lzip file. A
-small volume size may degrade compression ratio, so use it only when
-needed. Valid values range from @w{100 kB} to @w{4 EiB}.
+When compressing, and @samp{-c} has not been also specified, split the
+compressed output into several volume files with names
+@samp{original_name00001.lz}, @samp{original_name00002.lz}, etc, and set the
+volume size limit to @var{bytes}. Input files are kept unchanged. Each
+volume is a complete, maybe multimember, lzip file. A small volume size may
+degrade compression ratio, so use it only when needed. Valid values range
+from @w{100 kB} to @w{4 EiB}.
 
 @item -t
 @itemx --test
-Check integrity of the specified files, but don't decompress them. This
+Check integrity of the files specified, but don't decompress them. This
 really performs a trial decompression and throws away the result. Use it
 together with @samp{-v} to see information about the files. If a file
 fails the test, does not exist, can't be opened, or is a terminal, minilzip
@@ -800,8 +899,8 @@ effect when decompressing or testing.
 
 The bidimensional parameter space of LZMA can't be mapped to a linear
 scale optimal for all files. If your files are large, very repetitive,
-etc, you may need to use the @samp{--dictionary-size} and
-@samp{--match-length} options directly to achieve optimal performance.
+etc, you may need to use the options @samp{--dictionary-size} and
+@samp{--match-length} directly to achieve optimal performance.
 
 If several compression levels or @samp{-s} or @samp{-m} options are
 given, the last setting is used. For example @w{@samp{-9 -s64MiB}} is
@@ -831,6 +930,18 @@ so similar to the magic bytes of a lzip header that they can be confused
 with a corrupt header. Use this option if a file triggers a "corrupt
 header" error and the cause is not indeed a corrupt header.
 
+@item --check-lib
+Compare the @uref{#Library-version,,version of lzlib} used to compile
+minilzip with the version actually being used and exit. Report any
+differences found. Exit with error status 1 if differences are found. A
+mismatch may indicate that lzlib is not correctly installed or that a
+different version of lzlib has been installed after compiling the shared
+version of minilzip. @w{@samp{minilzip -v --check-lib}} shows the version of
+lzlib being used and the value of @samp{LZ_API_VERSION} (if defined).
+@ifnothtml
+@xref{Library version}.
+@end ifnothtml
+
 @end table
 
 Numbers given as arguments to options may be followed by a multiplier
@@ -867,6 +978,7 @@ when there is no longer anything to take away.@*
 
 @sp 1
 In the diagram below, a box like this:
+
 @verbatim
 +---+
 |   | <-- the vertical bars might be missing
@@ -874,6 +986,7 @@ In the diagram below, a box like this:
 @end verbatim
 
 represents one byte; a box like this:
+
 @verbatim
 +==============+
 |              |
@@ -888,6 +1001,7 @@ The members simply appear one after another in the data stream, with no
 additional information before, between, or after them.
 
 Each member has the following structure:
+
 @verbatim
 +--+--+--+--+----+----+=============+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 | ID string | VN | DS | LZMA stream | CRC32 |   Data size   |  Member size  |
@@ -907,8 +1021,7 @@ Just in case something needs to be modified in the future. 1 for now.
 @anchor{coded-dict-size}
 @item DS (coded dictionary size, 1 byte)
 The dictionary size is calculated by taking a power of 2 (the base size)
-and subtracting from it a fraction between 0/16 and 7/16 of the base
-size.@*
+and subtracting from it a fraction between 0/16 and 7/16 of the base size.@*
 Bits 4-0 contain the base 2 logarithm of the base size (12 to 29).@*
 Bits 7-5 contain the numerator of the fraction (0 to 7) to subtract
 from the base size to obtain the dictionary size.@*
@@ -916,8 +1029,8 @@ 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.
 
 @item LZMA stream
-The LZMA stream, finished by an end of stream marker. Uses default
-values for encoder properties.
+The LZMA stream, finished by an end of stream marker. Uses default values
+for encoder properties.
 @ifnothtml
 @xref{Stream format,,,lzip},
 @end ifnothtml
@@ -927,10 +1040,10 @@ See
 @end ifhtml
 for a complete description.@*
 Lzip only uses the LZMA marker @samp{2} ("End Of Stream" marker). Lzlib
-also uses the LZMA marker @samp{3} ("Sync Flush" marker).
+also uses the LZMA marker @samp{3} ("Sync Flush" marker). @xref{sync_flush}.
 
 @item CRC32 (4 bytes)
-CRC of the uncompressed original data.
+Cyclic Redundancy Check (CRC) of the uncompressed original data.
 
 @item Data size (8 bytes)
 Size of the uncompressed original data.
@@ -947,138 +1060,313 @@ facilitates safe recovery of undamaged members from multimember files.
 @chapter A small tutorial with examples
 @cindex examples
 
-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 @samp{bbexample.c} in the source distribution
-for an example of how buffer-to-buffer compression/decompression can be
-implemented using lzlib.
+This chapter provides real code examples for the most common uses of the
+library. See these examples in context in the files @samp{bbexample.c} and
+@samp{ffexample.c} from the source distribution of lzlib.
 
-Note that lzlib's interface is symmetrical. That is, the code for normal
-compression and decompression is identical except because one calls
+Note that the interface of lzlib is symmetrical. That is, the code for
+normal compression and decompression is identical except because one calls
 LZ_compress* functions while the other calls LZ_decompress* functions.
 
-@sp 1
-@noindent
-Example 1: Normal compression (@var{member_size} > total output).
+@menu
+* Buffer compression::    Buffer-to-buffer single-member compression
+* Buffer decompression::  Buffer-to-buffer decompression
+* File compression::      File-to-file single-member compression
+* File decompression::    File-to-file decompression
+* File compression mm::   File-to-file multimember compression
+* Skipping data errors::  Decompression with automatic resynchronization
+@end menu
 
-@example
-1) LZ_compress_open
-2) LZ_compress_write
-3) if no more data to write, call LZ_compress_finish
-4) LZ_compress_read
-5) go back to step 2 until LZ_compress_finished returns 1
-6) LZ_compress_close
-@end example
 
-@sp 1
-@noindent
-Example 2: Normal compression using LZ_compress_write_size.
+@node Buffer compression
+@section Buffer compression
+@cindex buffer compression
 
-@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
+Buffer-to-buffer single-member compression
+@w{(@var{member_size} > total output)}.
 
-@sp 1
-@noindent
-Example 3: Decompression.
+@verbatim
+/* Compresses 'insize' bytes from 'inbuf' to 'outbuf'.
+   Returns the size of the compressed data in '*outlenp'.
+   In case of error, or if 'outsize' is too small, returns false and does
+   not modify '*outlenp'.
+*/
+bool bbcompress( const uint8_t * const inbuf, const int insize,
+                 const int dictionary_size, const int match_len_limit,
+                 uint8_t * const outbuf, const int outsize,
+                 int * const outlenp )
+  {
+  int inpos = 0, outpos = 0;
+  bool error = false;
+  struct LZ_Encoder * const encoder =
+    LZ_compress_open( dictionary_size, match_len_limit, INT64_MAX );
+  if( !encoder || LZ_compress_errno( encoder ) != LZ_ok )
+    { LZ_compress_close( encoder ); return false; }
+
+  while( true )
+    {
+    int ret = LZ_compress_write( encoder, inbuf + inpos, insize - inpos );
+    if( ret < 0 ) { error = true; break; }
+    inpos += ret;
+    if( inpos >= insize ) LZ_compress_finish( encoder );
+    ret = LZ_compress_read( encoder, outbuf + outpos, outsize - outpos );
+    if( ret < 0 ) { error = true; break; }
+    outpos += ret;
+    if( LZ_compress_finished( encoder ) == 1 ) break;
+    if( outpos >= outsize ) { error = true; break; }
+    }
+
+  if( LZ_compress_close( encoder ) < 0 ) error = true;
+  if( error ) return false;
+  *outlenp = outpos;
+  return true;
+  }
+@end verbatim
 
-@example
-1) LZ_decompress_open
-2) LZ_decompress_write
-3) if no more data to write, call LZ_decompress_finish
-4) LZ_decompress_read
-5) go back to step 2 until LZ_decompress_finished returns 1
-6) LZ_decompress_close
-@end example
 
-@sp 1
-@noindent
-Example 4: Decompression using LZ_decompress_write_size.
+@node Buffer decompression
+@section Buffer decompression
+@cindex buffer decompression
 
-@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
-5a) optionally, if LZ_decompress_member_finished returns 1, read
-    final values for member with LZ_decompress_data_crc, etc.
-6) go back to step 2 until LZ_decompress_finished returns 1
-7) LZ_decompress_close
-@end example
+Buffer-to-buffer decompression.
 
-@sp 1
-@noindent
-Example 5: Multimember compression (@var{member_size} < total output).
+@verbatim
+/* Decompresses 'insize' bytes from 'inbuf' to 'outbuf'.
+   Returns the size of the decompressed data in '*outlenp'.
+   In case of error, or if 'outsize' is too small, returns false and does
+   not modify '*outlenp'.
+*/
+bool bbdecompress( const uint8_t * const inbuf, const int insize,
+                   uint8_t * const outbuf, const int outsize,
+                   int * const outlenp )
+  {
+  int inpos = 0, outpos = 0;
+  bool error = false;
+  struct LZ_Decoder * const decoder = LZ_decompress_open();
+  if( !decoder || LZ_decompress_errno( decoder ) != LZ_ok )
+    { LZ_decompress_close( decoder ); return false; }
+
+  while( true )
+    {
+    int ret = LZ_decompress_write( decoder, inbuf + inpos, insize - inpos );
+    if( ret < 0 ) { error = true; break; }
+    inpos += ret;
+    if( inpos >= insize ) LZ_decompress_finish( decoder );
+    ret = LZ_decompress_read( decoder, outbuf + outpos, outsize - outpos );
+    if( ret < 0 ) { error = true; break; }
+    outpos += ret;
+    if( LZ_decompress_finished( decoder ) == 1 ) break;
+    if( outpos >= outsize ) { error = true; break; }
+    }
+
+  if( LZ_decompress_close( decoder ) < 0 ) error = true;
+  if( error ) return false;
+  *outlenp = outpos;
+  return true;
+  }
+@end verbatim
 
-@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).
+@node File compression
+@section File compression
+@cindex file compression
 
-@example
- 1) LZ_compress_open       (with @var{member_size} > largest member).
- 2) LZ_compress_write
- 3) LZ_compress_read
- 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
- 9) go to step 12 if all input data have been written and
-    LZ_compress_finished returns 1
-10) LZ_compress_restart_member
-11) go back to step 2
-12) LZ_compress_close
-@end example
+File-to-file compression using LZ_compress_write_size.
 
-@sp 1
-@noindent
-Example 7: Decompression with automatic removal of leading data.
+@verbatim
+int ffcompress( struct LZ_Encoder * const encoder,
+                FILE * const infile, FILE * const outfile )
+  {
+  enum { buffer_size = 16384 };
+  uint8_t buffer[buffer_size];
+  while( true )
+    {
+    int len, ret;
+    int size = min( buffer_size, LZ_compress_write_size( encoder ) );
+    if( size > 0 )
+      {
+      len = fread( buffer, 1, size, infile );
+      ret = LZ_compress_write( encoder, buffer, len );
+      if( ret < 0 || ferror( infile ) ) break;
+      if( feof( infile ) ) LZ_compress_finish( encoder );
+      }
+    ret = LZ_compress_read( encoder, buffer, buffer_size );
+    if( ret < 0 ) break;
+    len = fwrite( buffer, 1, ret, outfile );
+    if( len < ret ) break;
+    if( LZ_compress_finished( encoder ) == 1 ) return 0;
+    }
+  return 1;
+  }
+@end verbatim
 
-@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
+
+@node File decompression
+@section File decompression
+@cindex file decompression
+
+File-to-file decompression using LZ_decompress_write_size.
+
+@verbatim
+int ffdecompress( struct LZ_Decoder * const decoder,
+                  FILE * const infile, FILE * const outfile )
+  {
+  enum { buffer_size = 16384 };
+  uint8_t buffer[buffer_size];
+  while( true )
+    {
+    int len, ret;
+    int size = min( buffer_size, LZ_decompress_write_size( decoder ) );
+    if( size > 0 )
+      {
+      len = fread( buffer, 1, size, infile );
+      ret = LZ_decompress_write( decoder, buffer, len );
+      if( ret < 0 || ferror( infile ) ) break;
+      if( feof( infile ) ) LZ_decompress_finish( decoder );
+      }
+    ret = LZ_decompress_read( decoder, buffer, buffer_size );
+    if( ret < 0 ) break;
+    len = fwrite( buffer, 1, ret, outfile );
+    if( len < ret ) break;
+    if( LZ_decompress_finished( decoder ) == 1 ) return 0;
+    }
+  return 1;
+  }
+@end verbatim
+
+
+@node File compression mm
+@section File-to-file multimember compression
+@cindex multimember compression
+
+Example 1: Multimember compression with members of fixed size
+@w{(@var{member_size} < total output)}.
+
+@verbatim
+int ffmmcompress( FILE * const infile, FILE * const outfile )
+  {
+  enum { buffer_size = 16384, member_size = 4096 };
+  uint8_t buffer[buffer_size];
+  bool done = false;
+  struct LZ_Encoder * const encoder =
+    LZ_compress_open( 65535, 16, member_size );
+  if( !encoder || LZ_compress_errno( encoder ) != LZ_ok  )
+    { fputs( "ffexample: Not enough memory.\n", stderr );
+      LZ_compress_close( encoder ); return 1; }
+  while( true )
+    {
+    int len, ret;
+    int size = min( buffer_size, LZ_compress_write_size( encoder ) );
+    if( size > 0 )
+      {
+      len = fread( buffer, 1, size, infile );
+      ret = LZ_compress_write( encoder, buffer, len );
+      if( ret < 0 || ferror( infile ) ) break;
+      if( feof( infile ) ) LZ_compress_finish( encoder );
+      }
+    ret = LZ_compress_read( encoder, buffer, buffer_size );
+    if( ret < 0 ) break;
+    len = fwrite( buffer, 1, ret, outfile );
+    if( len < ret ) break;
+    if( LZ_compress_member_finished( encoder ) == 1 )
+      {
+      if( LZ_compress_finished( encoder ) == 1 ) { done = true; break; }
+      if( LZ_compress_restart_member( encoder, member_size ) < 0 ) break;
+      }
+    }
+  if( LZ_compress_close( encoder ) < 0 ) done = false;
+  return done;
+  }
+@end verbatim
 
 @sp 1
 @noindent
-Example 8: Streamed decompression with automatic resynchronization to
-next member in case of data error.
+Example 2: Multimember compression (user-restarted members).
+(Call LZ_compress_open with @var{member_size} > largest member).
 
-@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
+@verbatim
+/* Compresses 'infile' to 'outfile' as a multimember stream with one member
+   for each line of text terminated by a newline character or by EOF.
+   Returns 0 if success, 1 if error.
+*/
+int fflfcompress( struct LZ_Encoder * const encoder,
+                  FILE * const infile, FILE * const outfile )
+  {
+  enum { buffer_size = 16384 };
+  uint8_t buffer[buffer_size];
+  while( true )
+    {
+    int len, ret;
+    int size = min( buffer_size, LZ_compress_write_size( encoder ) );
+    if( size > 0 )
+      {
+      for( len = 0; len < size; )
+        {
+        int ch = getc( infile );
+        if( ch == EOF || ( buffer[len++] = ch ) == '\n' ) break;
+        }
+      /* avoid writing an empty member to outfile */
+      if( len == 0 && LZ_compress_data_position( encoder ) == 0 ) return 0;
+      ret = LZ_compress_write( encoder, buffer, len );
+      if( ret < 0 || ferror( infile ) ) break;
+      if( feof( infile ) || buffer[len-1] == '\n' )
+        LZ_compress_finish( encoder );
+      }
+    ret = LZ_compress_read( encoder, buffer, buffer_size );
+    if( ret < 0 ) break;
+    len = fwrite( buffer, 1, ret, outfile );
+    if( len < ret ) break;
+    if( LZ_compress_member_finished( encoder ) == 1 )
+      {
+      if( feof( infile ) && LZ_compress_finished( encoder ) == 1 ) return 0;
+      if( LZ_compress_restart_member( encoder, INT64_MAX ) < 0 ) break;
+      }
+    }
+  return 1;
+  }
+@end verbatim
+
+
+@node Skipping data errors
+@section Skipping data errors
+@cindex skipping data errors
+
+@verbatim
+/* Decompresses 'infile' to 'outfile' with automatic resynchronization to
+   next member in case of data error, including the automatic removal of
+   leading garbage.
+*/
+int ffrsdecompress( struct LZ_Decoder * const decoder,
+                    FILE * const infile, FILE * const outfile )
+  {
+  enum { buffer_size = 16384 };
+  uint8_t buffer[buffer_size];
+  while( true )
+    {
+    int len, ret;
+    int size = min( buffer_size, LZ_decompress_write_size( decoder ) );
+    if( size > 0 )
+      {
+      len = fread( buffer, 1, size, infile );
+      ret = LZ_decompress_write( decoder, buffer, len );
+      if( ret < 0 || ferror( infile ) ) break;
+      if( feof( infile ) ) LZ_decompress_finish( decoder );
+      }
+    ret = LZ_decompress_read( decoder, buffer, buffer_size );
+    if( ret < 0 )
+      {
+      if( LZ_decompress_errno( decoder ) == LZ_header_error ||
+          LZ_decompress_errno( decoder ) == LZ_data_error )
+        { LZ_decompress_sync_to_member( decoder ); continue; }
+      else break;
+      }
+    len = fwrite( buffer, 1, ret, outfile );
+    if( len < ret ) break;
+    if( LZ_decompress_finished( decoder ) == 1 ) return 0;
+    }
+  return 1;
+  }
+@end verbatim
 
 
 @node Problems
@@ -1093,7 +1381,7 @@ for all eternity, if not longer.
 
 If you find a bug in lzlib, please send electronic mail to
 @email{lzip-bug@@nongnu.org}. Include the version number, which you can
-find by running @w{@code{minilzip --version}} or in
+find by running @w{@samp{minilzip --version}} or in
 @samp{LZ_version_string} from @samp{lzlib.h}.