diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/lzlib.info | 104 | ||||
| -rw-r--r-- | doc/lzlib.texinfo | 79 |
2 files changed, 133 insertions, 50 deletions
diff --git a/doc/lzlib.info b/doc/lzlib.info index 28aea4d..fff59c2 100644 --- a/doc/lzlib.info +++ b/doc/lzlib.info @@ -12,12 +12,13 @@ File: lzlib.info, Node: Top, Next: Introduction, Up: (dir) Lzlib ***** -This manual is for Lzlib (version 0.3, 3 May 2009). +This manual is for Lzlib (version 0.4, 3 June 2009). * 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 @@ -38,8 +39,8 @@ File: lzlib.info, Node: Introduction, Next: Library Version, Prev: Top, Up: 1 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. @@ -68,7 +69,7 @@ Igor Pavlov. For a description of the LZMA algorithm, see the Lzip manual. -File: lzlib.info, Node: Library Version, Next: Compression Functions, Prev: Introduction, Up: Top +File: lzlib.info, Node: Library Version, Next: Buffering, Prev: Introduction, Up: Top 2 Library Version ***************** @@ -88,9 +89,37 @@ application. error( "bad library version" ); -File: lzlib.info, Node: Compression Functions, Next: Decompression Functions, Prev: Library Version, Up: Top +File: lzlib.info, Node: Buffering, Next: Compression Functions, Prev: Library Version, Up: Top -3 Compression Functions +3 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: + + * Input compression buffer. Written to by the `LZ_compress_write' + function. Its size is two times the dictionary size set with the + `LZ_compress_open' function or 128KiB, whichever is larger. + + * Output compression buffer. Read from by the `LZ_compress_read' + function. Its size is 64KiB. + + * Input decompression buffer. Written to by the + `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. + + +File: lzlib.info, Node: Compression Functions, Next: Decompression Functions, Prev: Buffering, Up: Top + +4 Compression Functions *********************** These are the functions used to compress data. In case of error, all of @@ -123,6 +152,13 @@ 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 ) Frees all dynamically allocated data structures for this stream. This function discards any unprocessed input and does not flush @@ -133,17 +169,11 @@ verified by calling `LZ_compress_errno' before using it. Use this function to tell `lzlib' that all the data for this stream has already been written (with the `LZ_compress_write' function). - -- Function: int LZ_compress_finish_member ( void * const ENCODER ) - Use this function to tell `lzlib' that all the data for the current - member, in a multimember data stream, has already been written - (with the `LZ_compress_write' function). - - -- 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_sync_flush ( void * 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 ) @@ -165,6 +195,14 @@ 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 ) + The `LZ_compress_write_size' function returns the maximum number of + bytes that can be inmediately written through the + `LZ_compress_write' function. + + 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 ) Returns the current error code for ENCODER (*note Error Codes::) @@ -199,7 +237,7 @@ verified by calling `LZ_compress_errno' before using it. File: lzlib.info, Node: Decompression Functions, Next: Error Codes, Prev: Compression Functions, Up: Top -4 Decompression Functions +5 Decompression Functions ************************* These are the functions used to decompress data. In case of error, all @@ -275,7 +313,7 @@ be verified by calling `LZ_decompress_errno' before using it. File: lzlib.info, Node: Error Codes, Next: Data Format, Prev: Decompression Functions, Up: Top -5 Error Codes +6 Error Codes ************* Most library functions return -1 to indicate that they have failed. But @@ -286,7 +324,7 @@ what kind of error it was, you need to verify the error code by calling Library functions do not change the value returned by `LZ_(de)compress_errno' when they succeed; thus, the value returned by `LZ_(de)compress_errno' after a successful call is not necessarily -zero, and you should not use `LZ_(de)compress_errno' to determine +LZ_ok, and you should not use `LZ_(de)compress_errno' to determine whether a call failed. If the call failed, then you can examine `LZ_(de)compress_errno'. @@ -327,7 +365,7 @@ whether a call failed. If the call failed, then you can examine File: lzlib.info, Node: Data Format, Next: Examples, Prev: Error Codes, Up: Top -6 Data Format +7 Data Format ************* In the diagram below, a box like this: @@ -389,7 +427,7 @@ with no additional information before, between, or after them. File: lzlib.info, Node: Examples, Next: Problems, Prev: Data Format, Up: Top -7 A small tutorial with examples +8 A small tutorial with examples ******************************** This chaper shows the order in which the library functions should be @@ -437,7 +475,7 @@ Example 3: Multimember compression (MEMBER_SIZE < total output). File: lzlib.info, Node: Problems, Next: Concept Index, Prev: Examples, Up: Top -8 Reporting Bugs +9 Reporting Bugs **************** There are probably bugs in Lzlib. There are certainly errors and @@ -459,6 +497,7 @@ Concept Index * Menu: +* buffering: Buffering. (line 6) * bugs: Problems. (line 6) * compression functions: Compression Functions. (line 6) * data format: Data Format. (line 6) @@ -474,14 +513,15 @@ Concept Index Tag Table: Node: Top219 -Node: Introduction968 -Node: Library Version2428 -Node: Compression Functions3085 -Node: Decompression Functions8178 -Node: Error Codes11616 -Node: Data Format13551 -Node: Examples15518 -Node: Problems16940 -Node: Concept Index17510 +Node: Introduction1010 +Node: Library Version2477 +Node: Buffering3122 +Node: Compression Functions4229 +Node: Decompression Functions9731 +Node: Error Codes13169 +Node: Data Format15105 +Node: Examples17072 +Node: Problems18494 +Node: Concept Index19064 End Tag Table 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}. |