286 lines
6.9 KiB
Text
286 lines
6.9 KiB
Text
|
|
||
|
============================================================================
|
||
|
LZO -- a real-time data compression library LIBRARY REFERENCE
|
||
|
============================================================================
|
||
|
|
||
|
|
||
|
[ please read LZO.FAQ first ]
|
||
|
|
||
|
|
||
|
Table of Contents
|
||
|
=================
|
||
|
|
||
|
1 Introduction to the LZO Library Reference
|
||
|
1.1 Preliminary notes
|
||
|
1.2 Headers
|
||
|
2 General
|
||
|
2.1 The memory model
|
||
|
2.2 Public integral types
|
||
|
2.3 Public pointer types
|
||
|
2.4 Public function types
|
||
|
3 Function reference
|
||
|
3.1 Initialization
|
||
|
3.2 Compression
|
||
|
3.3 Decompression
|
||
|
3.4 Optimization
|
||
|
3.5 String functions
|
||
|
3.6 Checksum functions
|
||
|
3.7 Version functions
|
||
|
4 Variable reference
|
||
|
|
||
|
|
||
|
|
||
|
1 Introduction to the LZO Library Reference
|
||
|
=============================================
|
||
|
|
||
|
|
||
|
1.1 Preliminary notes
|
||
|
---------------------
|
||
|
|
||
|
- `C90' is short for ISO 9899-1990, the ANSI/ISO standard for the C
|
||
|
programming language
|
||
|
|
||
|
|
||
|
1.2 Headers
|
||
|
-----------
|
||
|
|
||
|
This section briefly describes the headers.
|
||
|
|
||
|
<lzo/lzoconf.h>
|
||
|
|
||
|
Contains definitions for the basic integral and pointer types,
|
||
|
provides wrappers for the library calling conventions, defines
|
||
|
error codes and contains prototypes for the generic functions.
|
||
|
This file is automatically included by all LZO headers.
|
||
|
|
||
|
<lzo/lzo1.h>
|
||
|
<lzo/lzo1a.h>
|
||
|
<lzo/lzo1b.h>
|
||
|
<lzo/lzo1c.h>
|
||
|
<lzo/lzo1f.h>
|
||
|
<lzo/lzo1x.h>
|
||
|
<lzo/lzo1y.h>
|
||
|
<lzo/lzo1z.h>
|
||
|
<lzo/lzo2a.h>
|
||
|
|
||
|
These files provide definitions and prototypes for the
|
||
|
actual (de-)compression functions.
|
||
|
|
||
|
|
||
|
|
||
|
2 General
|
||
|
=========
|
||
|
|
||
|
|
||
|
2.1 The memory model
|
||
|
--------------------
|
||
|
|
||
|
The documentation indicates that LZO requires 32-bit integers. It's
|
||
|
not the integer size that really matters, though, but the memory
|
||
|
model. If your memory model allows to access pointers at 32-bit
|
||
|
offsets, then there is no problem at all - LZO works fine on my
|
||
|
old Atari ST, which has 16 bit integers and a flat 32-bit memory model.
|
||
|
Using 'huge' 32-bit pointers under 16-bit DOS is a workaround for this.
|
||
|
|
||
|
While LZO also works with a strict 16-bit memory model, I don't officially
|
||
|
support this because this limits the maximum block size to 64 kB - and this
|
||
|
makes the library incompatible with other platforms, i.e. you cannot
|
||
|
decompress larger blocks compressed on those platforms.
|
||
|
|
||
|
|
||
|
2.2 Public integral types
|
||
|
-------------------------
|
||
|
|
||
|
lzo_uint
|
||
|
|
||
|
used as size_t, must be 32 bits or more for compatibility reasons
|
||
|
|
||
|
lzo_uint32
|
||
|
|
||
|
*must* be 32 bits or more
|
||
|
|
||
|
lzo_bool
|
||
|
|
||
|
can store the values 0 ("false") and 1 ("true")
|
||
|
|
||
|
lzo_byte
|
||
|
|
||
|
unsigned char (memory model specific)
|
||
|
|
||
|
|
||
|
2.3 Public pointer types
|
||
|
------------------------
|
||
|
|
||
|
All pointer types are memory model specific.
|
||
|
|
||
|
lzo_voidp
|
||
|
|
||
|
pointer to void
|
||
|
|
||
|
lzo_bytep
|
||
|
|
||
|
pointer to unsigned char
|
||
|
|
||
|
lzo_bytepp
|
||
|
|
||
|
array of pointers to unsigned char
|
||
|
|
||
|
|
||
|
2.4 Public function types
|
||
|
-------------------------
|
||
|
|
||
|
lzo_compress_t
|
||
|
|
||
|
lzo_decompress_t
|
||
|
|
||
|
lzo_optimize_t
|
||
|
|
||
|
lzo_callback_t
|
||
|
|
||
|
|
||
|
|
||
|
3 Function reference
|
||
|
====================
|
||
|
|
||
|
|
||
|
3.1 Initialization
|
||
|
------------------
|
||
|
|
||
|
int lzo_init ( void );
|
||
|
|
||
|
This function initializes the LZO library. It must be the first LZO
|
||
|
function you call, and you cannot use any of the other LZO library
|
||
|
functions if the call fails.
|
||
|
|
||
|
Return value:
|
||
|
Returns LZO_E_OK on success, error code otherwise.
|
||
|
|
||
|
Note:
|
||
|
This function is actually implemented using a macro.
|
||
|
|
||
|
|
||
|
3.2 Compression
|
||
|
---------------
|
||
|
|
||
|
All compressors compress the memory block at `src' with the uncompressed
|
||
|
length `src_len' to the address given by `dst'.
|
||
|
The length of the compressed blocked will be returned in the variable
|
||
|
pointed by `dst_len'.
|
||
|
|
||
|
The two blocks may overlap under certain conditions (see examples/overlap.c),
|
||
|
thereby allowing "in-place" compression.
|
||
|
|
||
|
|
||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
#include <lzo/lzo1x.h>
|
||
|
|
||
|
int lzo1x_1_compress ( const lzo_bytep src, lzo_uint src_len,
|
||
|
lzo_bytep dst, lzo_uintp dst_len,
|
||
|
lzo_voidp wrkmem );
|
||
|
|
||
|
Algorithm: LZO1X
|
||
|
Compression level: LZO1X-1
|
||
|
Memory requirements: LZO1X_1_MEM_COMPRESS (64 kB on 32-bit machines)
|
||
|
|
||
|
This compressor is pretty fast.
|
||
|
|
||
|
Return value:
|
||
|
Always returns LZO_E_OK (this function can never fail).
|
||
|
|
||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
#include <lzo/lzo1x.h>
|
||
|
|
||
|
int lzo1x_999_compress ( const lzo_bytep src, lzo_uint src_len,
|
||
|
lzo_bytep dst, lzo_uintp dst_len,
|
||
|
lzo_voidp wrkmem );
|
||
|
|
||
|
Algorithm: LZO1X
|
||
|
Compression level: LZO1X-999
|
||
|
Memory requirements: LZO1X_999_MEM_COMPRESS (448 kB on 32-bit machines)
|
||
|
|
||
|
This compressor is quite slow but achieves a good compression
|
||
|
ratio. It is mainly intended for generating pre-compressed data.
|
||
|
|
||
|
Return value:
|
||
|
Always returns LZO_E_OK (this function can never fail).
|
||
|
|
||
|
|
||
|
[ ... lots of other compressors which all follow the same principle ... ]
|
||
|
|
||
|
|
||
|
|
||
|
3.3 Decompression
|
||
|
-----------------
|
||
|
|
||
|
All decompressors decompress the memory block at `src' with the compressed
|
||
|
length `src_len' to the address given by `dst'.
|
||
|
The length of the decompressed block will be returned in the variable
|
||
|
pointed by `dst_len' - on error the number of bytes that have
|
||
|
been decompressed so far will be returned.
|
||
|
|
||
|
The safe decompressors expect that the number of bytes available in
|
||
|
the `dst' block is passed via the variable pointed by `dst_len'.
|
||
|
|
||
|
The two blocks may overlap under certain conditions (see examples/overlap.c),
|
||
|
thereby allowing "in-place" decompression.
|
||
|
|
||
|
|
||
|
Description of return values:
|
||
|
|
||
|
LZO_E_OK
|
||
|
Success.
|
||
|
|
||
|
LZO_E_INPUT_NOT_CONSUMED
|
||
|
The end of the compressed block has been detected before all
|
||
|
bytes in the compressed block have been used.
|
||
|
This may actually not be an error (if `src_len' is too large).
|
||
|
|
||
|
LZO_E_INPUT_OVERRUN
|
||
|
The decompressor requested more bytes from the compressed
|
||
|
block than available.
|
||
|
Your data is corrupted (or `src_len' is too small).
|
||
|
|
||
|
LZO_E_OUTPUT_OVERRUN
|
||
|
The decompressor requested to write more bytes to the uncompressed
|
||
|
block than available.
|
||
|
Either your data is corrupted, or you should increase the number of
|
||
|
available bytes passed in the variable pointed by `dst_len'.
|
||
|
|
||
|
LZO_E_LOOKBEHIND_OVERRUN
|
||
|
Your data is corrupted.
|
||
|
|
||
|
LZO_E_EOF_NOT_FOUND
|
||
|
No EOF code was found in the compressed block.
|
||
|
Your data is corrupted (or `src_len' is too small).
|
||
|
|
||
|
LZO_E_ERROR
|
||
|
Any other error (data corrupted).
|
||
|
|
||
|
|
||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
#include <lzo1x.h>
|
||
|
|
||
|
int lzo1x_decompress ( const lzo_bytep src, lzo_uint src_len,
|
||
|
lzo_bytep dst, lzo_uintp dst_len,
|
||
|
lzo_voidp wrkmem );
|
||
|
|
||
|
Algorithm: LZO1X
|
||
|
Memory requirements: 0
|
||
|
|
||
|
|
||
|
[ ... lots of other decompressors which all follow the same principle ... ]
|
||
|
|
||
|
|
||
|
|
||
|
4 Variable reference
|
||
|
====================
|
||
|
|
||
|
The variables are listed alphabetically.
|
||
|
|
||
|
[ no public variables yet ]
|
||
|
|
||
|
|
||
|
|
||
|
--------------------------- END OF LZOAPI.TXT ------------------------------
|
||
|
|