summaryrefslogtreecommitdiffstats
path: root/doc/lzlib.texinfo
diff options
context:
space:
mode:
authorDaniel Baumann <mail@daniel-baumann.ch>2015-11-07 13:49:18 +0000
committerDaniel Baumann <mail@daniel-baumann.ch>2015-11-07 13:49:18 +0000
commit3464658cfb26bfbc85ab6fa50185d503dcec4688 (patch)
tree0813dbfdfd5cb882816f532673abe404f32e2c5b /doc/lzlib.texinfo
parentAdding upstream version 1.4. (diff)
downloadlzlib-3464658cfb26bfbc85ab6fa50185d503dcec4688.tar.xz
lzlib-3464658cfb26bfbc85ab6fa50185d503dcec4688.zip
Adding upstream version 1.5~rc1.upstream/1.5_rc1
Signed-off-by: Daniel Baumann <mail@daniel-baumann.ch>
Diffstat (limited to '')
-rw-r--r--doc/lzlib.texinfo87
1 files changed, 51 insertions, 36 deletions
diff --git a/doc/lzlib.texinfo b/doc/lzlib.texinfo
index c08303e..2830694 100644
--- a/doc/lzlib.texinfo
+++ b/doc/lzlib.texinfo
@@ -6,19 +6,19 @@
@finalout
@c %**end of header
-@set UPDATED 28 May 2013
-@set VERSION 1.4
+@set UPDATED 28 July 2013
+@set VERSION 1.5-rc1
@dircategory Data Compression
@direntry
-* Lzlib: (lzlib). A compression library for lzip files
+* Lzlib: (lzlib). Compression library for lzip files
@end direntry
@ifnothtml
@titlepage
@title Lzlib
-@subtitle A compression library for lzip files
+@subtitle Compression library for lzip files
@subtitle for Lzlib version @value{VERSION}, @value{UPDATED}
@author by Antonio Diaz Diaz
@@ -36,17 +36,17 @@ This manual is for Lzlib (version @value{VERSION}, @value{UPDATED}).
@menu
* Introduction:: Purpose and features of Lzlib
-* Library Version:: Checking library version
+* 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
+* 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
+* Concept index:: Index of concepts
@end menu
@sp 1
@@ -65,6 +65,10 @@ 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 long-term data archiving. It is
+clean, provides very safe 4 factor integrity checking, and is backed by
+the recovery capabilities of lziprecover.
+
The functions and variables forming the interface of the compression
library are declared in the file @samp{lzlib.h}. Usage examples of the
library are given in the files @samp{main.c} and @samp{bbexample.c} from
@@ -91,13 +95,22 @@ any signal handler. The decoder checks the consistency of the compressed
data, so the library should never crash even in case of corrupted input.
Lzlib implements a simplified version of the LZMA (Lempel-Ziv-Markov
-chain-Algorithm) algorithm. The original LZMA algorithm was designed by
-Igor Pavlov. For a description of the LZMA algorithm, see the Lzip
-manual.
-
-
-@node Library Version
-@chapter Library Version
+chain-Algorithm) algorithm. The high compression of LZMA comes from
+combining two basic, well-proven compression ideas: sliding dictionaries
+(LZ77/78) and markov models (the thing used by every compression
+algorithm that uses a range encoder or 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).
+
+
+@node Library version
+@chapter Library version
@cindex library version
@deftypefun {const char *} LZ_version ( void )
@@ -150,8 +163,8 @@ whichever is larger.
@end itemize
-@node Parameter Limits
-@chapter Parameter Limits
+@node Parameter limits
+@chapter Parameter limits
@cindex parameter limits
These functions provide minimum and maximum values for some parameters.
@@ -182,8 +195,8 @@ Returns the largest valid match length limit [273].
@end deftypefun
-@node Compression Functions
-@chapter Compression Functions
+@node Compression functions
+@chapter Compression functions
@cindex compression functions
These are the functions used to compress data. In case of error, all of
@@ -288,7 +301,7 @@ 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} (@pxref{Error Codes}).
+Returns the current error code for @var{encoder} (@pxref{Error codes}).
@end deftypefun
@@ -328,8 +341,8 @@ perhaps not yet read.
@end deftypefun
-@node Decompression Functions
-@chapter Decompression Functions
+@node Decompression functions
+@chapter Decompression functions
@cindex decompression functions
These are the functions used to decompress data. In case of error, all
@@ -421,7 +434,7 @@ will accept a @var{size} up to the returned number of bytes.
@deftypefun {enum LZ_Errno} LZ_decompress_errno ( struct LZ_Decoder * const @var{decoder} )
-Returns the current error code for @var{decoder} (@pxref{Error Codes}).
+Returns the current error code for @var{decoder} (@pxref{Error codes}).
@end deftypefun
@@ -480,8 +493,8 @@ perhaps not yet read.
@end deftypefun
-@node Error Codes
-@chapter Error Codes
+@node Error codes
+@chapter Error codes
@cindex error codes
Most library functions return -1 to indicate that they have failed. But
@@ -538,8 +551,8 @@ A bug was detected in the library. Please, report it (@pxref{Problems}).
@end deftypevr
-@node Error Messages
-@chapter Error Messages
+@node Error messages
+@chapter Error messages
@cindex error messages
@deftypefun {const char *} LZ_strerror ( const enum LZ_Errno @var{lz_errno} )
@@ -553,8 +566,8 @@ The value of @var{lz_errno} normally comes from a call to
@end deftypefun
-@node Data Format
-@chapter Data Format
+@node Data format
+@chapter Data format
@cindex data format
Perfection is reached, not when there is no longer anything to add, but
@@ -612,7 +625,9 @@ Valid values for dictionary size range from 4KiB to 512MiB.
@item Lzma stream
The lzma stream, finished by an end of stream marker. Uses default values
-for encoder properties. See the lzip manual for a full description.
+for encoder properties. See the lzip manual for a full description.@*
+Lzip only uses the LZMA marker @samp{2} ("End Of Stream" marker). Lzlib
+also uses the LZMA marker @samp{3} ("Sync Flush" marker).
@item CRC32 (4 bytes)
CRC of the uncompressed original data.
@@ -793,8 +808,8 @@ find by running @w{@samp{minilzip --version}} or in
@samp{LZ_version_string} from @samp{lzlib.h}.
-@node Concept Index
-@unnumbered Concept Index
+@node Concept index
+@unnumbered Concept index
@printindex cp