summaryrefslogtreecommitdiff
path: root/lzo/doc/LZOAPI.TXT
diff options
context:
space:
mode:
authorArne Schwabe <arne@rfc2549.org>2012-04-16 19:21:14 +0200
committerArne Schwabe <arne@rfc2549.org>2012-04-16 19:21:14 +0200
commit3e4d8f433239c40311037616b1b8833a06651ae0 (patch)
tree98ab7fce0d011d34677b0beb762d389cb5c39199 /lzo/doc/LZOAPI.TXT
Initial import
Diffstat (limited to 'lzo/doc/LZOAPI.TXT')
-rw-r--r--lzo/doc/LZOAPI.TXT285
1 files changed, 285 insertions, 0 deletions
diff --git a/lzo/doc/LZOAPI.TXT b/lzo/doc/LZOAPI.TXT
new file mode 100644
index 00000000..8d285845
--- /dev/null
+++ b/lzo/doc/LZOAPI.TXT
@@ -0,0 +1,285 @@
+
+============================================================================
+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 ------------------------------
+