summaryrefslogtreecommitdiffstats
path: root/doc/lzlib.info
blob: e502f6bb00033514c3b1aae8bceca0a4d70322f2 (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
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
This is lzlib.info, produced by makeinfo version 4.13 from
lzlib.texinfo.

INFO-DIR-SECTION Data Compression
START-INFO-DIR-ENTRY
* Lzlib: (lzlib).               A compression library for lzip files
END-INFO-DIR-ENTRY


File: lzlib.info,  Node: Top,  Next: Introduction,  Up: (dir)

Lzlib Manual
************

This manual is for Lzlib (version 1.2, 25 October 2011).

* Menu:

* Introduction::                Purpose and features of Lzlib
* Library Version::             Checking library version
* Buffering::                   Sizes of Lzlib's buffers
* Parameter Limits::            Min / max values for some parameters
* Compression Functions::       Descriptions of the compression functions
* Decompression Functions::     Descriptions of the decompression functions
* Error Codes::                 Meaning of codes returned by functions
* Error Messages::              Error messages corresponding to error codes
* Data Format::                 Detailed format of the compressed data
* Examples::                    A small tutorial with examples
* Problems::                    Reporting bugs
* Concept Index::               Index of concepts


   Copyright (C) 2009, 2010, 2011 Antonio Diaz Diaz.

   This manual is free documentation: you have unlimited permission to
copy, distribute and modify it.


File: lzlib.info,  Node: Introduction,  Next: Library Version,  Prev: Top,  Up: Top

1 Introduction
**************

Lzlib is a data compression library providing in-memory LZMA compression
and decompression functions, including integrity checking of the
decompressed data. The compressed data format used by the library is the
lzip format.

   The functions and variables forming the interface of the compression
library are declared in the file `lzlib.h'. Usage examples of the
library are given in the files `main.cc' and `bbexample.cc' from the
source distribution.

   Compression/decompression is done by repeatedly calling a couple of
read/write functions until all the data has been processed by the
library. This interface is safer and less error prone than the
traditional zlib interface.

   Compression/decompression is done when the read function is called.
This means the value returned by the position functions will not be
updated until some data is read, even if you write a lot of data. If
you want the data to be compressed in advance, just call the read
function with a SIZE equal to 0.

   Lzlib will correctly decompress a data stream which is the
concatenation of two or more compressed data streams. The result is the
concatenation of the corresponding decompressed data streams. Integrity
testing of concatenated compressed data streams is also supported.

   All the library functions are thread safe. The library does not
install any signal handler. The decoder checks the consistency of the
compressed data, so the library should never crash even in case of
corrupted input.

   Lzlib implements a simplified version of the LZMA (Lempel-Ziv-Markov
chain-Algorithm) algorithm. The original LZMA algorithm was designed by
Igor Pavlov. For a description of the LZMA algorithm, see the Lzip
manual.


File: lzlib.info,  Node: Library Version,  Next: Buffering,  Prev: Introduction,  Up: Top

2 Library Version
*****************

 -- Function: const char * LZ_version ( void )
     Returns the library version as a string.

 -- Constant: const char * LZ_version_string
     This constant is defined in the header file `lzlib.h'.

   The application should compare LZ_version and LZ_version_string for
consistency. If the first character differs, the library code actually
used may be incompatible with the `lzlib.h' header file used by the
application.

     if( LZ_version()[0] != LZ_version_string[0] )
       error( "bad library version" );


File: lzlib.info,  Node: Buffering,  Next: Parameter Limits,  Prev: Library Version,  Up: Top

3 Buffering
***********

Lzlib internal functions need access to a memory chunk at least as large
as the dictionary size (sliding window). For efficiency reasons, the
input buffer for compression is twice as large as the dictionary size.
Finally, for security reasons, lzlib uses two more internal buffers.

   These are the four buffers used by lzlib, and their guaranteed
minimum sizes:

   * Input compression buffer. Written to by the `LZ_compress_write'
     function. Its size is two times the dictionary size set with the
     `LZ_compress_open' function or 128KiB, whichever is larger.

   * Output compression buffer. Read from by the `LZ_compress_read'
     function. Its size is 64KiB.

   * Input decompression buffer. Written to by the
     `LZ_decompress_write' function. Its size is 64KiB.

   * Output decompression buffer. Read from by the `LZ_decompress_read'
     function. Its size is the dictionary size set in the header of the
     member currently being decompressed or 64KiB, whichever is larger.


File: lzlib.info,  Node: Parameter Limits,  Next: Compression Functions,  Prev: Buffering,  Up: Top

4 Parameter Limits
******************

These functions provide minimum and maximum values for some parameters.
Current values are shown in square brackets.

 -- Function: int LZ_min_dictionary_bits ( void )
     Returns the base 2 logarithm of the smallest valid dictionary size
     [12].

 -- Function: int LZ_min_dictionary_size ( void )
     Returns the smallest valid dictionary size [4KiB].

 -- Function: int LZ_max_dictionary_bits ( void )
     Returns the base 2 logarithm of the largest valid dictionary size
     [29].

 -- Function: int LZ_max_dictionary_size ( void )
     Returns the largest valid dictionary size [512MiB].

 -- Function: int LZ_min_match_len_limit ( void )
     Returns the smallest valid match length limit [5].

 -- Function: int LZ_max_match_len_limit ( void )
     Returns the largest valid match length limit [273].


File: lzlib.info,  Node: Compression Functions,  Next: Decompression Functions,  Prev: Parameter Limits,  Up: Top

5 Compression Functions
***********************

These are the functions used to compress data. In case of error, all of
them return -1, except `LZ_compress_open' whose return value must be
verified by calling `LZ_compress_errno' before using it.

 -- Function: struct LZ_Encoder * LZ_compress_open ( const int
          DICTIONARY_SIZE, const int MATCH_LEN_LIMIT, const long long
          MEMBER_SIZE )
     Initializes the internal stream state for compression and returns a
     pointer that can only be used as the ENCODER argument for the
     other LZ_compress functions, or a null pointer if the encoder
     could not be allocated.

     The returned pointer must be verified by calling
     `LZ_compress_errno' before using it. If `LZ_compress_errno' does
     not return `LZ_ok', the returned pointer must not be used and
     should be freed with `LZ_compress_close' to avoid memory leaks.

     DICTIONARY_SIZE sets the dictionary size to be used, in bytes.
     Valid values range from 4KiB to 512MiB. Note that dictionary sizes
     are quantized. If the specified size does not match one of the
     valid sizes, it will be rounded upwards by adding up to
     (DICTIONARY_SIZE / 16) to it.

     MATCH_LEN_LIMIT sets the match length limit in bytes. Valid values
     range from 5 to 273. Larger values usually give better compression
     ratios but longer compression times.

     MEMBER_SIZE sets the member size limit in bytes. Minimum member
     size limit is 100kB. Small member size may degrade compression
     ratio, so use it only when needed. To produce a single member data
     stream, give MEMBER_SIZE a value larger than the amount of data to
     be produced, for example LLONG_MAX.

 -- Function: int LZ_compress_close ( struct LZ_Encoder * const ENCODER
          )
     Frees all dynamically allocated data structures for this stream.
     This function discards any unprocessed input and does not flush
     any pending output. After a call to `LZ_compress_close', ENCODER
     can no more be used as an argument to any LZ_compress function.

 -- Function: int LZ_compress_finish ( struct LZ_Encoder * const
          ENCODER )
     Use this function to tell `lzlib' that all the data for this member
     has already been written (with the `LZ_compress_write' function).
     After all the produced compressed data has been read with
     `LZ_compress_read' and `LZ_compress_member_finished' returns 1, a
     new member can be started with `LZ_compress_restart_member'.

 -- Function: int LZ_compress_restart_member ( struct LZ_Encoder *
          const ENCODER, const long long MEMBER_SIZE )
     Use this function to start a new member, in a multimember data
     stream.  Call this function only after
     `LZ_compress_member_finished' indicates that the current member
     has been fully read (with the `LZ_compress_read' function).

 -- Function: int LZ_compress_sync_flush ( struct LZ_Encoder * const
          ENCODER )
     Use this function to make available to `LZ_compress_read' all the
     data already written with the `LZ_compress_write' function.
     Repeated use of `LZ_compress_sync_flush' may degrade compression
     ratio, so use it only when needed.

 -- Function: int LZ_compress_read ( struct LZ_Encoder * const ENCODER,
          uint8_t * const BUFFER, const int SIZE )
     The `LZ_compress_read' function reads up to SIZE bytes from the
     stream pointed to by ENCODER, storing the results in BUFFER.

     The return value is the number of bytes actually read. This might
     be less than SIZE; for example, if there aren't that many bytes
     left in the stream or if more bytes have to be yet written with the
     `LZ_compress_write' function. Note that reading less than SIZE
     bytes is not an error.

 -- Function: int LZ_compress_write ( struct LZ_Encoder * const
          ENCODER, uint8_t * const BUFFER, const int SIZE )
     The `LZ_compress_write' function writes up to SIZE bytes from
     BUFFER to the stream pointed to by ENCODER.

     The return value is the number of bytes actually written. This
     might be less than SIZE. Note that writing less than SIZE bytes is
     not an error.

 -- Function: int LZ_compress_write_size ( struct LZ_Encoder * const
          ENCODER )
     The `LZ_compress_write_size' function returns the maximum number of
     bytes that can be inmediately written through the
     `LZ_compress_write' function.

     It is guaranteed that an inmediate call to `LZ_compress_write' will
     accept a SIZE up to the returned number of bytes.

 -- Function: enum LZ_Errno LZ_compress_errno ( struct LZ_Encoder *
          const ENCODER )
     Returns the current error code for ENCODER (*note Error Codes::).

 -- Function: int LZ_compress_finished ( struct LZ_Encoder * const
          ENCODER )
     Returns 1 if all the data has been read and `LZ_compress_close' can
     be safely called. Otherwise it returns 0.

 -- Function: int LZ_compress_member_finished ( struct LZ_Encoder *
          const ENCODER )
     Returns 1 if the current member, in a multimember data stream, has
     been fully read and `LZ_compress_restart_member' can be safely
     called.  Otherwise it returns 0.

 -- Function: long long LZ_compress_data_position ( struct LZ_Encoder *
          const ENCODER )
     Returns the number of input bytes already compressed in the current
     member.

 -- Function: long long LZ_compress_member_position ( struct LZ_Encoder
          * const ENCODER )
     Returns the number of compressed bytes already produced, but
     perhaps not yet read, in the current member.

 -- Function: long long LZ_compress_total_in_size ( struct LZ_Encoder *
          const ENCODER )
     Returns the total number of input bytes already compressed.

 -- Function: long long LZ_compress_total_out_size ( struct LZ_Encoder
          * const ENCODER )
     Returns the total number of compressed bytes already produced, but
     perhaps not yet read.


File: lzlib.info,  Node: Decompression Functions,  Next: Error Codes,  Prev: Compression Functions,  Up: Top

6 Decompression Functions
*************************

These are the functions used to decompress data. In case of error, all
of them return -1, except `LZ_decompress_open' whose return value must
be verified by calling `LZ_decompress_errno' before using it.

 -- Function: struct LZ_Decoder * LZ_decompress_open ( void )
     Initializes the internal stream state for decompression and
     returns a pointer that can only be used as the DECODER argument
     for the other LZ_decompress functions, or a null pointer if the
     decoder could not be allocated.

     The returned pointer must be verified by calling
     `LZ_decompress_errno' before using it. If `LZ_decompress_errno'
     does not return `LZ_ok', the returned pointer must not be used and
     should be freed with `LZ_decompress_close' to avoid memory leaks.

 -- Function: int LZ_decompress_close ( struct LZ_Decoder * const
          DECODER )
     Frees all dynamically allocated data structures for this stream.
     This function discards any unprocessed input and does not flush
     any pending output. After a call to `LZ_decompress_close', DECODER
     can no more be used as an argument to any LZ_decompress function.

 -- Function: int LZ_decompress_finish ( struct LZ_Decoder * const
          DECODER )
     Use this function to tell `lzlib' that all the data for this stream
     has already been written (with the `LZ_decompress_write' function).

 -- Function: int LZ_decompress_reset ( struct LZ_Decoder * const
          DECODER )
     Resets the internal state of DECODER as it was just after opening
     it with the `LZ_decompress_open' function. Data stored in the
     internal buffers is discarded. Position counters are set to 0.

 -- Function: int LZ_decompress_sync_to_member ( struct LZ_Decoder *
          const DECODER )
     Resets the error state of DECODER and enters a search state that
     lasts until a new member header (or the end of the stream) is
     found.  After a successful call to `LZ_decompress_sync_to_member',
     data written with `LZ_decompress_write' will be consumed and
     `LZ_decompress_read' will return 0 until a header is found.

     This function is useful to discard any data preceding the first
     member, or to discard the rest of the current member, for example
     in case of a data error. If the decoder is already at the
     beginning of a member, this function does nothing.

 -- Function: int LZ_decompress_read ( struct LZ_Decoder * const
          DECODER, uint8_t * const BUFFER, const int SIZE )
     The `LZ_decompress_read' function reads up to SIZE bytes from the
     stream pointed to by DECODER, storing the results in BUFFER.

     The return value is the number of bytes actually read. This might
     be less than SIZE; for example, if there aren't that many bytes
     left in the stream or if more bytes have to be yet written with the
     `LZ_decompress_write' function. Note that reading less than SIZE
     bytes is not an error.

 -- Function: int LZ_decompress_write ( struct LZ_Decoder * const
          DECODER, uint8_t * const BUFFER, const int SIZE )
     The `LZ_decompress_write' function writes up to SIZE bytes from
     BUFFER to the stream pointed to by DECODER.

     The return value is the number of bytes actually written. This
     might be less than SIZE. Note that writing less than SIZE bytes is
     not an error.

 -- Function: int LZ_decompress_write_size ( struct LZ_Decoder * const
          DECODER )
     The `LZ_decompress_write_size' function returns the maximum number
     of bytes that can be inmediately written through the
     `LZ_decompress_write' function.

     It is guaranteed that an inmediate call to `LZ_decompress_write'
     will accept a SIZE up to the returned number of bytes.

 -- Function: enum LZ_Errno LZ_decompress_errno ( struct LZ_Decoder *
          const DECODER )
     Returns the current error code for DECODER (*note Error Codes::).

 -- Function: int LZ_decompress_finished ( struct LZ_Decoder * const
          DECODER )
     Returns 1 if all the data has been read and `LZ_decompress_close'
     can be safely called. Otherwise it returns 0.

 -- Function: int LZ_decompress_member_finished ( struct LZ_Decoder *
          const DECODER )
     Returns 1 if the previous call to `LZ_decompress_read' finished
     reading the current member, indicating that final values for
     member are available through `LZ_decompress_data_crc',
     `LZ_decompress_data_position', and
     `LZ_decompress_member_position'. Otherwise it returns 0.

 -- Function: int LZ_decompress_member_version ( struct LZ_Decoder *
          const DECODER )
     Returns the version of current member from member header.

 -- Function: int LZ_decompress_dictionary_size ( struct LZ_Decoder *
          const DECODER )
     Returns the dictionary size of current member from member header.

 -- Function: unsigned int LZ_decompress_data_crc ( struct LZ_Decoder *
          const DECODER )
     Returns the 32 bit Cyclic Redundancy Check of the data
     decompressed from the current member. The returned value is valid
     only when `LZ_decompress_member_finished' returns 1.

 -- Function: long long LZ_decompress_data_position ( struct LZ_Decoder
          * const DECODER )
     Returns the number of decompressed bytes already produced, but
     perhaps not yet read, in the current member.

 -- Function: long long LZ_decompress_member_position ( struct
          LZ_Decoder * const DECODER )
     Returns the number of input bytes already decompressed in the
     current member.

 -- Function: long long LZ_decompress_total_in_size ( struct LZ_Decoder
          * const DECODER )
     Returns the total number of input bytes already decompressed.

 -- Function: long long LZ_decompress_total_out_size ( struct
          LZ_Decoder * const DECODER )
     Returns the total number of decompressed bytes already produced,
     but perhaps not yet read.


File: lzlib.info,  Node: Error Codes,  Next: Error Messages,  Prev: Decompression Functions,  Up: Top

7 Error Codes
*************

Most library functions return -1 to indicate that they have failed. But
this return value only tells you that an error has occurred. To find out
what kind of error it was, you need to verify the error code by calling
`LZ_(de)compress_errno'.

   Library functions do not change the value returned by
`LZ_(de)compress_errno' when they succeed; thus, the value returned by
`LZ_(de)compress_errno' after a successful call is not necessarily
LZ_ok, and you should not use `LZ_(de)compress_errno' to determine
whether a call failed. If the call failed, then you can examine
`LZ_(de)compress_errno'.

   The error codes are defined in the header file `lzlib.h'.

 -- Constant: enum LZ_Errno LZ_ok
     The value of this constant is 0 and is used to indicate that there
     is no error.

 -- Constant: enum LZ_Errno LZ_bad_argument
     At least one of the arguments passed to the library function was
     invalid.

 -- Constant: enum LZ_Errno LZ_mem_error
     No memory available. The system cannot allocate more virtual memory
     because its capacity is full.

 -- Constant: enum LZ_Errno LZ_sequence_error
     A library function was called in the wrong order. For example
     `LZ_compress_restart_member' was called before
     `LZ_compress_member_finished' indicates that the current member is
     finished.

 -- Constant: enum LZ_Errno LZ_header_error
     Reading of member header failed. If this happens at the end of the
     data stream it may indicate trailing garbage.

 -- Constant: enum LZ_Errno LZ_unexpected_eof
     The end of the data stream was reached in the middle of a member.

 -- Constant: enum LZ_Errno LZ_data_error
     The data stream is corrupt.

 -- Constant: enum LZ_Errno LZ_library_error
     A bug was detected in the library. Please, report it (*note
     Problems::).


File: lzlib.info,  Node: Error Messages,  Next: Data Format,  Prev: Error Codes,  Up: Top

8 Error Messages
****************

 -- Function: const char * LZ_strerror ( const enum LZ_Errno LZ_ERRNO )
     Returns the standard error message for a given error code. The
     messages are fairly short; there are no multi-line messages or
     embedded newlines.  This function makes it easy for your program
     to report informative error messages about the failure of a
     library call.

     The value of LZ_ERRNO normally comes from a call to
     `LZ_(de)compress_errno'.


File: lzlib.info,  Node: Data Format,  Next: Examples,  Prev: Error Messages,  Up: Top

9 Data Format
*************

In the diagram below, a box like this:
+---+
|   | <-- the vertical bars might be missing
+---+

   represents one byte; a box like this:
+==============+
|              |
+==============+

   represents a variable number of bytes.


   A lzip data stream consists of a series of "members" (compressed data
sets). The members simply appear one after another in the data stream,
with no additional information before, between, or after them.

   Each member has the following structure:
+--+--+--+--+----+----+=============+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| ID string | VN | DS | Lzma stream | CRC32 |   Data size   |  Member size  |
+--+--+--+--+----+----+=============+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

   All multibyte values are stored in little endian order.

`ID string'
     A four byte string, identifying the lzip format, with the value
     "LZIP".

`VN (version number, 1 byte)'
     Just in case something needs to be modified in the future. Valid
     values are 0 and 1. Version 0 files are deprecated. They can
     contain only one member and lack the `Member size' field.

`DS (coded dictionary size, 1 byte)'
     Bits 4-0 contain the base 2 logarithm of the base dictionary size.
     Bits 7-5 contain the number of "wedges" to substract from the base
     dictionary size to obtain the dictionary size. The size of a wedge
     is (base dictionary size / 16).
     Valid values for dictionary size range from 4KiB to 512MiB.

`Lzma stream'
     The lzma stream, finished by an end of stream marker. Uses default
     values for encoder properties.

`CRC32 (4 bytes)'
     CRC of the uncompressed original data.

`Data size (8 bytes)'
     Size of the uncompressed original data.

`Member size (8 bytes)'
     Total size of the member, including header and trailer. This
     facilitates safe recovery of undamaged members from multimember
     files.



File: lzlib.info,  Node: Examples,  Next: Problems,  Prev: Data Format,  Up: Top

10 A small tutorial with examples
*********************************

This chapter shows the order in which the library functions should be
called depending on what kind of data stream you want to compress or
decompress. See the file `bbexample.cc' in the source distribution for
an example of how buffer-to-buffer compression/decompression can be
implemented using lzlib.


Example 1: Normal compression (MEMBER_SIZE > total output).

     1) LZ_compress_open
     2) LZ_compress_write
     3) LZ_compress_read
     4) go back to step 2 until all input data has been written
     5) LZ_compress_finish
     6) LZ_compress_read
     7) go back to step 6 until LZ_compress_finished returns 1
     8) LZ_compress_close


Example 2: Normal compression using LZ_compress_write_size.

     1) LZ_compress_open
     2) go to step 5 if LZ_compress_write_size returns 0
     3) LZ_compress_write
     4) if no more data to write, call LZ_compress_finish
     5) LZ_compress_read
     6) go back to step 2 until LZ_compress_finished returns 1
     7) LZ_compress_close


Example 3: Decompression.

     1) LZ_decompress_open
     2) LZ_decompress_write
     3) LZ_decompress_read
     4) go back to step 2 until all input data has been written
     5) LZ_decompress_finish
     6) LZ_decompress_read
     7) go back to step 6 until LZ_decompress_finished returns 1
     8) LZ_decompress_close


Example 4: Decompression using LZ_decompress_write_size.

     1) LZ_decompress_open
     2) go to step 5 if LZ_decompress_write_size returns 0
     3) LZ_decompress_write
     4) if no more data to write, call LZ_decompress_finish
     5) LZ_decompress_read
     5a) optionally, if LZ_decompress_member_finished returns 1, read
         final values for member with LZ_decompress_data_crc, etc.
     6) go back to step 2 until LZ_decompress_finished returns 1
     7) LZ_decompress_close


Example 5: Multimember compression (MEMBER_SIZE < total output).

      1) LZ_compress_open
      2) go to step 5 if LZ_compress_write_size returns 0
      3) LZ_compress_write
      4) if no more data to write, call LZ_compress_finish
      5) LZ_compress_read
      6) go back to step 2 until LZ_compress_member_finished returns 1
      7) go to step 10 if LZ_compress_finished() returns 1
      8) LZ_compress_restart_member
      9) go back to step 2
     10) LZ_compress_close


Example 6: Multimember compression (user-restarted members).

      1) LZ_compress_open
      2) LZ_compress_write
      3) LZ_compress_read
      4) go back to step 2 until member termination is desired
      5) LZ_compress_finish
      6) LZ_compress_read
      7) go back to step 6 until LZ_compress_member_finished returns 1
      8) verify that LZ_compress_finished returns 1
      9) go to step 12 if all input data has been written
     10) LZ_compress_restart_member
     11) go back to step 2
     12) LZ_compress_close


Example 7: Decompression with automatic removal of leading garbage.

     1) LZ_decompress_open
     2) LZ_decompress_sync_to_member
     3) go to step 6 if LZ_decompress_write_size returns 0
     4) LZ_decompress_write
     5) if no more data to write, call LZ_decompress_finish
     6) LZ_decompress_read
     7) go back to step 3 until LZ_decompress_finished returns 1
     8) LZ_decompress_close


Example 8: Streamed decompression with automatic resynchronization to
next member in case of data error.

     1) LZ_decompress_open
     2) go to step 5 if LZ_decompress_write_size returns 0
     3) LZ_decompress_write
     4) if no more data to write, call LZ_decompress_finish
     5) if LZ_decompress_read produces LZ_header_error or LZ_data_error,
        call LZ_decompress_sync_to_member
     6) go back to step 2 until LZ_decompress_finished returns 1
     7) LZ_decompress_close


File: lzlib.info,  Node: Problems,  Next: Concept Index,  Prev: Examples,  Up: Top

11 Reporting Bugs
*****************

There are probably bugs in Lzlib. There are certainly errors and
omissions in this manual. If you report them, they will get fixed. If
you don't, no one will ever know about them and they will remain unfixed
for all eternity, if not longer.

   If you find a bug in Lzlib, please send electronic mail to
<lzip-bug@nongnu.org>. Include the version number, which you can find
by running `minilzip --version' or in `LZ_version_string' from
`lzlib.h'.


File: lzlib.info,  Node: Concept Index,  Prev: Problems,  Up: Top

Concept Index
*************

[index]
* Menu:

* buffering:                             Buffering.             (line 6)
* bugs:                                  Problems.              (line 6)
* compression functions:                 Compression Functions. (line 6)
* data format:                           Data Format.           (line 6)
* decompression functions:               Decompression Functions.
                                                                (line 6)
* error codes:                           Error Codes.           (line 6)
* error messages:                        Error Messages.        (line 6)
* examples:                              Examples.              (line 6)
* getting help:                          Problems.              (line 6)
* introduction:                          Introduction.          (line 6)
* library version:                       Library Version.       (line 6)
* parameter limits:                      Parameter Limits.      (line 6)



Tag Table:
Node: Top219
Node: Introduction1311
Node: Library Version3136
Node: Buffering3781
Node: Parameter Limits4901
Node: Compression Functions5858
Node: Decompression Functions11955
Node: Error Codes18027
Node: Error Messages19966
Node: Data Format20545
Node: Examples22553
Node: Problems26419
Node: Concept Index26991

End Tag Table