Adding upstream version 0.4.upstream/0.4

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

1 files changed, 61 insertions, 18 deletions

diff --git a/doc/lzlib.texinfo b/doc/lzlib.texinfo
index 69d96d4..044bd04 100644
--- a/doc/lzlib.texinfo
+++ b/doc/lzlib.texinfo
@@ -5,8 +5,8 @@
 @finalout
 @c %**end of header
 
-@set UPDATED 3 May 2009
-@set VERSION 0.3
+@set UPDATED 3 June 2009
+@set VERSION 0.4
 
 @dircategory Data Compression
 @direntry
@@ -34,6 +34,7 @@ This manual is for Lzlib (version @value{VERSION}, @value{UPDATED}).
 @menu
 * Introduction::		Purpose and features of Lzlib
 * Library Version::		Checking library version
+* Buffering::			Sizes of Lzlib's buffers
 * Compression Functions::	Descriptions of the compression functions
 * Decompression Functions::	Descriptions of the decompression functions
 * Error Codes::			Meaning of codes returned by functions
@@ -54,8 +55,8 @@ to copy, distribute and modify it.
 @chapter Introduction
 @cindex introduction
 
-The lzlib compression library provides in-memory LZMA compression and
-decompression functions, including integrity checking of the
+Lzlib is a data compression library providing in-memory LZMA compression
+and decompression functions, including integrity checking of the
 uncompressed data. The compressed data format used by the library is the
 lzip format.
 
@@ -106,6 +107,37 @@ if( LZ_version()[0] != LZ_version_string[0] )
 @end example
 
 
+@node Buffering
+@chapter Buffering
+@cindex buffering
+
+Lzlib internal functions need access to a memory chunk at least as large
+as the dictionary size (sliding window). For efficiency reasons, the
+input buffer for compression is twice as large as the dictionary size.
+Finally, for security reasons, lzlib uses two more internal buffers.
+
+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. Its size is two times the dictionary
+size set with the @samp{LZ_compress_open} function or 128KiB, whichever
+is larger.
+
+@item Output compression buffer. Read from by the
+@samp{LZ_compress_read} function. Its size is 64KiB.
+
+@item Input decompression buffer. Written to by the
+@samp{LZ_decompress_write} function. Its size is 64KiB.
+
+@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.
+@end itemize
+
+
 @node Compression Functions
 @chapter Compression Functions
 @cindex compression functions
@@ -142,6 +174,14 @@ 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} )
 Frees all dynamically allocated data structures for this stream. This
 function discards any unprocessed input and does not flush any pending
@@ -156,18 +196,11 @@ has already been written (with the @samp{LZ_compress_write} function).
 @end deftypefun
 
 
-@deftypefun int LZ_compress_finish_member ( void * const @var{encoder} )
-Use this function to tell @samp{lzlib} that all the data for the current
-member, in a multimember data stream, has already been written (with the
-@samp{LZ_compress_write} function).
-@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).
+@deftypefun int LZ_compress_sync_flush ( void * 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
+ratio, so use it only when needed.
 @end deftypefun
 
 
@@ -194,6 +227,16 @@ not an error.
 @end deftypefun
 
 
+@deftypefun int LZ_compress_write_size ( void * 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.
+
+It is guaranteed that an inmediate call to @samp{LZ_compress_write} will
+accept a @var{size} up to the returned number of bytes.
+@end deftypefun
+
+
 @deftypefun {enum LZ_errno} LZ_compress_errno ( void * const @var{encoder} )
 Returns the current error code for @var{encoder} (@pxref{Error Codes})
 @end deftypefun
@@ -340,8 +383,8 @@ what kind of error it was, you need to verify the error code by calling
 Library functions do not change the value returned by
 @samp{LZ_(de)compress_errno} when they succeed; thus, the value returned
 by @samp{LZ_(de)compress_errno} after a successful call is not
-necessarily zero, and you should not use @samp{LZ_(de)compress_errno} to
-determine whether a call failed. If the call failed, then you can
+necessarily LZ_ok, and you should not use @samp{LZ_(de)compress_errno}
+to determine whether a call failed. If the call failed, then you can
 examine @samp{LZ_(de)compress_errno}.
 
 The error codes are defined in the header file @samp{lzlib.h}.