summaryrefslogtreecommitdiffstats
path: root/lib
diff options
context:
space:
mode:
authorYann Collet <cyan@fb.com>2019-04-12 18:27:44 (GMT)
committerYann Collet <cyan@fb.com>2019-04-12 18:27:44 (GMT)
commit21ff1a839afcf18e68ee7dbb0ec0d6cccb4c1be0 (patch)
tree4318e6bcebc94455ed166cea1b096b7d9bc93fdb /lib
parent780aac520b69d6369f4e3995624c37e56d75498d (diff)
downloadlz4-21ff1a839afcf18e68ee7dbb0ec0d6cccb4c1be0.zip
lz4-21ff1a839afcf18e68ee7dbb0ec0d6cccb4c1be0.tar.gz
lz4-21ff1a839afcf18e68ee7dbb0ec0d6cccb4c1be0.tar.bz2
updated doc to underline difference between block and frame
as this is a very frequent source of confusion for new users.
Diffstat (limited to 'lib')
-rw-r--r--lib/README.md9
-rw-r--r--lib/lz4.h18
-rw-r--r--lib/lz4frame.h13
3 files changed, 24 insertions, 16 deletions
diff --git a/lib/README.md b/lib/README.md
index c6daaea..b753195 100644
--- a/lib/README.md
+++ b/lib/README.md
@@ -16,13 +16,14 @@ They generate and decode data using the [LZ4 block format].
For more compression ratio at the cost of compression speed,
the High Compression variant called **lz4hc** is available.
Add files **`lz4hc.c`** and **`lz4hc.h`**.
-This variant also depends on regular `lib/lz4.*` source files.
+This variant also compresses data using the [LZ4 block format],
+and depends on regular `lib/lz4.*` source files.
#### Frame support, for interoperability
In order to produce compressed data compatible with `lz4` command line utility,
-it's necessary to encode lz4-compressed blocks using the [official interoperable frame format].
+it's necessary to use the [official interoperable frame format].
This format is generated and decoded automatically by the **lz4frame** library.
Its public API is described in `lib/lz4frame.h`.
In order to work properly, lz4frame needs all other modules present in `/lib`,
@@ -44,7 +45,7 @@ by using build macro `LZ4_PUBLISH_STATIC_FUNCTIONS`.
#### Build macros
-The following build macro can be determined at compilation time :
+The following build macro can be selected at compilation time :
- `LZ4_FAST_DEC_LOOP` : this triggers the optimized decompression loop.
This loops works great on x86/x64 cpus, and is automatically enabled on this platform.
@@ -61,7 +62,7 @@ The following build macro can be determined at compilation time :
- `LZ4_DISABLE_DEPRECATE_WARNINGS` : invoking a deprecated function will make the compiler generate a warning.
This is meant to invite users to update their source code.
- Should this be a problem, it's generally to make the compiler ignore these warnings,
+ Should this be a problem, it's generally possible to make the compiler ignore these warnings,
for example with `-Wno-deprecated-declarations` on `gcc`,
or `_CRT_SECURE_NO_WARNINGS` for Visual Studio.
Another method is to define `LZ4_DISABLE_DEPRECATE_WARNINGS`
diff --git a/lib/lz4.h b/lib/lz4.h
index 935b55f..23b5ac5 100644
--- a/lib/lz4.h
+++ b/lib/lz4.h
@@ -51,19 +51,23 @@ extern "C" {
multiple GB/s per core, typically reaching RAM speed limits on multi-core systems.
The LZ4 compression library provides in-memory compression and decompression functions.
+ It gives full buffer control to user.
Compression can be done in:
- a single step (described as Simple Functions)
- a single step, reusing a context (described in Advanced Functions)
- unbounded multiple steps (described as Streaming compression)
- lz4.h provides block compression functions. It gives full buffer control to user.
- Decompressing an lz4-compressed block also requires metadata (such as compressed size).
- Each application is free to encode such metadata in whichever way it wants.
+ lz4.h generates and decodes LZ4-compressed blocks (doc/lz4_Block_format.md).
+ Decompressing a block requires additional metadata, such as its compressed size.
+ Each application is free to encode and pass such metadata in whichever way it wants.
- An additional format, called LZ4 frame specification (doc/lz4_Frame_format.md),
- take care of encoding standard metadata alongside LZ4-compressed blocks.
- Frame format is required for interoperability.
- It is delivered through a companion API, declared in lz4frame.h.
+ lz4.h only handle blocks, it can not generate Frames.
+
+ Blocks are different from Frames (doc/lz4_Frame_format.md).
+ Frames bundle both blocks and metadata in a specified manner.
+ This are required for compressed data to be self-contained and portable.
+ Frame format is delivered through a companion API, declared in lz4frame.h.
+ Note that the `lz4` CLI can only manage frames.
*/
/*^***************************************************************
diff --git a/lib/lz4frame.h b/lib/lz4frame.h
index 5c68628..ca20dc9 100644
--- a/lib/lz4frame.h
+++ b/lib/lz4frame.h
@@ -32,11 +32,14 @@
- LZ4 public forum : https://groups.google.com/forum/#!forum/lz4c
*/
-/* LZ4F is a stand-alone API to create LZ4-compressed frames
- * conformant with specification v1.6.1.
- * It also offers streaming capabilities.
+/* LZ4F is a stand-alone API able to create and decode LZ4 frames
+ * conformant with specification v1.6.1 in doc/lz4_Frame_format.md .
+ * Generated frames are compatible with `lz4` CLI.
+ *
+ * LZ4F also offers streaming capabilities.
+ *
* lz4.h is not required when using lz4frame.h,
- * except to get constant such as LZ4_VERSION_NUMBER.
+ * except to extract common constant such as LZ4_VERSION_NUMBER.
* */
#ifndef LZ4F_H_09782039843
@@ -195,7 +198,7 @@ typedef struct {
* Simple compression function
***********************************/
-LZ4FLIB_API int LZ4F_compressionLevel_max(void);
+LZ4FLIB_API int LZ4F_compressionLevel_max(void); /* v1.8.0+ */
/*! LZ4F_compressFrameBound() :
* Returns the maximum possible compressed size with LZ4F_compressFrame() given srcSize and preferences.