X-Git-Url: http://mj.ucw.cz/gitweb/?a=blobdiff_plain;f=ucw%2Flizard.h;h=526fd5b5cee5519b5da9d8c01419749e0de00d92;hb=5959916922193dea72ec0f74fa0a5211ca68f9c4;hp=f45207251c9d73feb4e7af3bcb02fc50962ee6d6;hpb=fdb438738b41d339e87aaa0c93620a45660ffa5d;p=libucw.git

diff --git a/ucw/lizard.h b/ucw/lizard.h
index f4520725..526fd5b5 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);