1 2============================================================================ 3LZO -- a real-time data compression library LIBRARY REFERENCE 4============================================================================ 5 6 7[ please read LZO.FAQ first ] 8 9 10Table of Contents 11================= 12 131 Introduction to the LZO Library Reference 141.1 Preliminary notes 151.2 Headers 162 General 172.1 The memory model 182.2 Public integral types 192.3 Public pointer types 202.4 Public function types 213 Function reference 223.1 Initialization 233.2 Compression 243.3 Decompression 253.4 Optimization 263.5 String functions 273.6 Checksum functions 283.7 Version functions 294 Variable reference 30 31 32 331 Introduction to the LZO Library Reference 34============================================= 35 36 371.1 Preliminary notes 38--------------------- 39 40- `C90' is short for ISO 9899-1990, the ANSI/ISO standard for the C 41 programming language 42 43 441.2 Headers 45----------- 46 47This section briefly describes the headers. 48 49<lzo/lzoconf.h> 50 51 Contains definitions for the basic integral and pointer types, 52 provides wrappers for the library calling conventions, defines 53 error codes and contains prototypes for the generic functions. 54 This file is automatically included by all LZO headers. 55 56<lzo/lzo1.h> 57<lzo/lzo1a.h> 58<lzo/lzo1b.h> 59<lzo/lzo1c.h> 60<lzo/lzo1f.h> 61<lzo/lzo1x.h> 62<lzo/lzo1y.h> 63<lzo/lzo1z.h> 64<lzo/lzo2a.h> 65 66 These files provide definitions and prototypes for the 67 actual (de-)compression functions. 68 69 70 712 General 72========= 73 74 752.1 The memory model 76-------------------- 77 78The documentation indicates that LZO requires 32-bit integers. It's 79not the integer size that really matters, though, but the memory 80model. If your memory model allows to access pointers at 32-bit 81offsets, then there is no problem at all - LZO works fine on my 82old Atari ST, which has 16 bit integers and a flat 32-bit memory model. 83Using 'huge' 32-bit pointers under 16-bit DOS is a workaround for this. 84 85While LZO also works with a strict 16-bit memory model, I don't officially 86support this because this limits the maximum block size to 64 kB - and this 87makes the library incompatible with other platforms, i.e. you cannot 88decompress larger blocks compressed on those platforms. 89 90 912.2 Public integral types 92------------------------- 93 94lzo_uint 95 96 used as size_t, must be 32 bits or more for compatibility reasons 97 98lzo_uint32 99 100 *must* be 32 bits or more 101 102lzo_bool 103 104 can store the values 0 ("false") and 1 ("true") 105 106lzo_byte 107 108 unsigned char (memory model specific) 109 110 1112.3 Public pointer types 112------------------------ 113 114All pointer types are memory model specific. 115 116lzo_voidp 117 118 pointer to void 119 120lzo_bytep 121 122 pointer to unsigned char 123 124lzo_bytepp 125 126 array of pointers to unsigned char 127 128 1292.4 Public function types 130------------------------- 131 132lzo_compress_t 133 134lzo_decompress_t 135 136lzo_optimize_t 137 138lzo_callback_t 139 140 141 1423 Function reference 143==================== 144 145 1463.1 Initialization 147------------------ 148 149int lzo_init ( void ); 150 151 This function initializes the LZO library. It must be the first LZO 152 function you call, and you cannot use any of the other LZO library 153 functions if the call fails. 154 155 Return value: 156 Returns LZO_E_OK on success, error code otherwise. 157 158 Note: 159 This function is actually implemented using a macro. 160 161 1623.2 Compression 163--------------- 164 165All compressors compress the memory block at `src' with the uncompressed 166length `src_len' to the address given by `dst'. 167The length of the compressed blocked will be returned in the variable 168pointed by `dst_len'. 169 170The two blocks may overlap under certain conditions (see examples/overlap.c), 171thereby allowing "in-place" compression. 172 173 174~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 175#include <lzo/lzo1x.h> 176 177int lzo1x_1_compress ( const lzo_bytep src, lzo_uint src_len, 178 lzo_bytep dst, lzo_uintp dst_len, 179 lzo_voidp wrkmem ); 180 181 Algorithm: LZO1X 182 Compression level: LZO1X-1 183 Memory requirements: LZO1X_1_MEM_COMPRESS (64 kB on 32-bit machines) 184 185 This compressor is pretty fast. 186 187 Return value: 188 Always returns LZO_E_OK (this function can never fail). 189 190~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 191#include <lzo/lzo1x.h> 192 193int lzo1x_999_compress ( const lzo_bytep src, lzo_uint src_len, 194 lzo_bytep dst, lzo_uintp dst_len, 195 lzo_voidp wrkmem ); 196 197 Algorithm: LZO1X 198 Compression level: LZO1X-999 199 Memory requirements: LZO1X_999_MEM_COMPRESS (448 kB on 32-bit machines) 200 201 This compressor is quite slow but achieves a good compression 202 ratio. It is mainly intended for generating pre-compressed data. 203 204 Return value: 205 Always returns LZO_E_OK (this function can never fail). 206 207 208[ ... lots of other compressors which all follow the same principle ... ] 209 210 211 2123.3 Decompression 213----------------- 214 215All decompressors decompress the memory block at `src' with the compressed 216length `src_len' to the address given by `dst'. 217The length of the decompressed block will be returned in the variable 218pointed by `dst_len' - on error the number of bytes that have 219been decompressed so far will be returned. 220 221The safe decompressors expect that the number of bytes available in 222the `dst' block is passed via the variable pointed by `dst_len'. 223 224The two blocks may overlap under certain conditions (see examples/overlap.c), 225thereby allowing "in-place" decompression. 226 227 228Description of return values: 229 230 LZO_E_OK 231 Success. 232 233 LZO_E_INPUT_NOT_CONSUMED 234 The end of the compressed block has been detected before all 235 bytes in the compressed block have been used. 236 This may actually not be an error (if `src_len' is too large). 237 238 LZO_E_INPUT_OVERRUN 239 The decompressor requested more bytes from the compressed 240 block than available. 241 Your data is corrupted (or `src_len' is too small). 242 243 LZO_E_OUTPUT_OVERRUN 244 The decompressor requested to write more bytes to the uncompressed 245 block than available. 246 Either your data is corrupted, or you should increase the number of 247 available bytes passed in the variable pointed by `dst_len'. 248 249 LZO_E_LOOKBEHIND_OVERRUN 250 Your data is corrupted. 251 252 LZO_E_EOF_NOT_FOUND 253 No EOF code was found in the compressed block. 254 Your data is corrupted (or `src_len' is too small). 255 256 LZO_E_ERROR 257 Any other error (data corrupted). 258 259 260~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 261#include <lzo1x.h> 262 263int lzo1x_decompress ( const lzo_bytep src, lzo_uint src_len, 264 lzo_bytep dst, lzo_uintp dst_len, 265 lzo_voidp wrkmem ); 266 267 Algorithm: LZO1X 268 Memory requirements: 0 269 270 271[ ... lots of other decompressors which all follow the same principle ... ] 272 273 274 2754 Variable reference 276==================== 277 278The variables are listed alphabetically. 279 280[ no public variables yet ] 281 282 283 284--------------------------- END OF LZOAPI.TXT ------------------------------ 285 286