release/src/router/lzo/doc/LZOAPI.TXT

   1
   2 ============================================================================
   3 LZO -- a real-time data compression library                LIBRARY REFERENCE
   4 ============================================================================
   5
   6
   7 [ please read LZO.FAQ first ]
   8
   9
  10 Table of Contents
  11 =================
  12
  13 1      Introduction to the LZO Library Reference
  14 1.1      Preliminary notes
  15 1.2      Headers
  16 2      General
  17 2.1      The memory model
  18 2.2      Public integral types
  19 2.3      Public pointer types
  20 2.4      Public function types
  21 3      Function reference
  22 3.1      Initialization
  23 3.2      Compression
  24 3.3      Decompression
  25 3.4      Optimization
  26 3.5      String functions
  27 3.6      Checksum functions
  28 3.7      Version functions
  29 4      Variable reference
  30
  31
  32
  33 1 Introduction to the LZO Library Reference
  34 =============================================
  35
  36
  37 1.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
  44 1.2 Headers
  45 -----------
  46
  47 This 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
  71 2 General
  72 =========
  73
  74
  75 2.1 The memory model
  76 --------------------
  77
  78 The documentation indicates that LZO requires 32-bit integers. It's
  79 not the integer size that really matters, though, but the memory
  80 model. If your memory model allows to access pointers at 32-bit
  81 offsets, then there is no problem at all - LZO works fine on my
  82 old Atari ST, which has 16 bit integers and a flat 32-bit memory model.
  83 Using 'huge' 32-bit pointers under 16-bit DOS is a workaround for this.
  84
  85 While LZO also works with a strict 16-bit memory model, I don't officially
  86 support this because this limits the maximum block size to 64 KiB - and this
  87 makes the library incompatible with other platforms, i.e. you cannot
  88 decompress larger blocks compressed on those platforms.
  89
  90
  91 2.2 Public integral types
  92 -------------------------
  93
  94 lzo_uint
  95
  96     used as size_t, must be 32 bits or more for compatibility reasons
  97
  98 lzo_uint32
  99
 100     *must* be 32 bits or more
 101
 102 lzo_bool
 103
 104     can store the values 0 ("false") and 1 ("true")
 105
 106 lzo_byte
 107
 108     unsigned char (memory model specific)
 109
 110
 111 2.3 Public pointer types
 112 ------------------------
 113
 114 All pointer types are memory model specific.
 115
 116 lzo_voidp
 117
 118     pointer to void
 119
 120 lzo_bytep
 121
 122     pointer to unsigned char
 123
 124 lzo_bytepp
 125
 126     array of pointers to unsigned char
 127
 128
 129 2.4 Public function types
 130 -------------------------
 131
 132 lzo_compress_t
 133
 134 lzo_decompress_t
 135
 136 lzo_optimize_t
 137
 138 lzo_callback_t
 139
 140
 141
 142 3 Function reference
 143 ====================
 144
 145
 146 3.1 Initialization
 147 ------------------
 148
 149 int 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
 162 3.2 Compression
 163 ---------------
 164
 165 All compressors compress the memory block at 'src' with the uncompressed
 166 length 'src_len' to the address given by 'dst'.
 167 The length of the compressed blocked will be returned in the variable
 168 pointed by 'dst_len'.
 169
 170 The two blocks may overlap under certain conditions (see examples/overlap.c),
 171 thereby allowing "in-place" compression.
 172
 173
 174 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 175 #include <lzo/lzo1x.h>
 176
 177 int 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 KiB 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
 193 int 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 KiB 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
 212 3.3 Decompression
 213 -----------------
 214
 215 All decompressors decompress the memory block at 'src' with the compressed
 216 length 'src_len' to the address given by 'dst'.
 217 The length of the decompressed block will be returned in the variable
 218 pointed by 'dst_len' - on error the number of bytes that have
 219 been decompressed so far will be returned.
 220
 221 The safe decompressors expect that the number of bytes available in
 222 the 'dst' block is passed via the variable pointed by 'dst_len'.
 223
 224 The two blocks may overlap under certain conditions (see examples/overlap.c),
 225 thereby allowing "in-place" decompression.
 226
 227
 228 Description 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
 263 int 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
 275 4 Variable reference
 276 ====================
 277
 278 The variables are listed alphabetically.
 279
 280 [ no public variables yet ]
 281
 282
 283
 284 --------------------------- END OF LZOAPI.TXT ------------------------------
 285