From: Michal Vaner <vorner@ucw.cz>
Date: Fri, 28 Nov 2008 12:21:19 +0000 (+0100)
Subject: ucw docs: lizard_decompress_save update
X-Git-Tag: holmes-import~139
X-Git-Url: http://mj.ucw.cz/gitweb/?a=commitdiff_plain;h=801ff5b509d35e6fefdacc3f3c5a0ddaba16b17b;p=libucw.git

ucw docs: lizard_decompress_save update

Describes more clearly, why it exists and that it is not reentrant.
---

diff --git a/ucw/doc/compress.txt b/ucw/doc/compress.txt
index 7e950997..d4527636 100644
--- a/ucw/doc/compress.txt
+++ b/ucw/doc/compress.txt
@@ -3,10 +3,12 @@ Compression
 
 The library contains a compression routine, called LiZaRd.  It is
 modified Lempel-Ziv 77 method with slightly worse compression ratio,
-but with faster compression and decompression.
+but with faster compression and decompression (compression is few times
+faster than zlib, decompression is slightly slower than memcpy()).
 
-// TODO Meaning of the abbreviation
-// TODO Actual numbers how fast it is?
+The data format and inspiration for code comes from the LZO project
+(which couldn't be used due to licence problems). They might be
+compatible, but no-one tested that.
 
 - <<basic,Basic application>>
 - <<safe,Safe decompression>>
diff --git a/ucw/lizard.h b/ucw/lizard.h
index f4520725..84ed001a 100644
--- a/ucw/lizard.h
+++ b/ucw/lizard.h
@@ -87,18 +87,35 @@ int lizard_decompress(const byte *in, byte *out);
 struct lizard_buffer;	/** Type of the output buffer for @lizard_decompress_safe(). **/
 
 struct lizard_buffer *lizard_alloc(void);	/** Get me a new <<struct_lizard_buffer,`lizard_buffer`>>. **/
-void lizard_free(struct lizard_buffer *buf);	/** Return memory used by a <<struct_lizard_buffer,`lizard_buffer`>>. **/
+/**
+ * Return memory used by a <<struct_lizard_buffer,`lizard_buffer`>>.
+ * It frees even the data stored in it (the result of
+ * @lizard_decompress_safe() call that used this buffer).
+ **/
+void lizard_free(struct lizard_buffer *buf);
 
 /**
- * Decompress data previously compressed by @lizard_compress().
- * Input is taken from @in. @buf is used to store the output.
- * You need to provide the length of the uncompressed data in @expected_length.
+ * This one acts much like @lizard_decompress(). The difference is it
+ * checks the data to be of correct length (therefore it will not
+ * crash on invalid data).
+ *
+ * It decompresses data provided by @in. The @buf is used to get the
+ * memory for output (you get one by @lizard_alloc()).
+ *
+ * The pointer to decompressed data is returned. To free it, free the
+ * buffer by @lizard_free().
+ *
+ * In the case of error, NULL is returned. In that case, `errno` is
+ * set either to `EINVAL` (expected_length does not match) or to
+ * `EFAULT` (a segfault has been caught while decompressing -- it
+ * probably means expected_length was set way too low). Both cases
+ * suggest either wrongly computed length or data corruption.
  *
- * The pointer to data is returned.
+ * The @buf argument may be reused for multiple decompresses. However,
+ * the data will be overwritten by the next call.
  *
- * If an error occurs, NULL is returned and `errno` is set.
- * `EINVAL` means the actual length does not match @expected_length.
- * `EFAULT` means a segfault was encountered while decompressing (probably @expected_length was way too low).
+ * Beware this function is not thread-safe and is not even reentrant
+ * (because of internal segfault handling).
  **/
 byte *lizard_decompress_safe(const byte *in, struct lizard_buffer *buf, uns expected_length);
 
@@ -128,4 +145,8 @@ static inline uns adler32(const byte *buf, uns len)
   return adler32_update(1, buf, len);
 }
 
+a
+a
+a
+a
 #endif