summaryrefslogtreecommitdiff
path: root/lzo/doc/LZOAPI.TXT
blob: 5ae735328cd00f666dcc64b62a0346da0518210b (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
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 KiB - 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 KiB 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 KiB 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 ------------------------------