diff options
-rw-r--r-- | Makefile | 2 | ||||
-rw-r--r-- | contrib/gen_manual/gen-lz4-manual.sh | 3 | ||||
-rw-r--r-- | contrib/gen_manual/gen_manual.cpp | 58 | ||||
-rw-r--r-- | doc/lz4_manual.html | 215 | ||||
-rw-r--r-- | doc/lz4frame_manual.html | 240 | ||||
-rw-r--r-- | lib/Makefile | 2 | ||||
-rw-r--r-- | lib/lz4.h | 16 | ||||
-rw-r--r-- | lib/lz4frame.h | 49 | ||||
-rw-r--r-- | programs/Makefile | 2 | ||||
-rw-r--r-- | tests/Makefile | 2 |
10 files changed, 446 insertions, 143 deletions
@@ -3,6 +3,8 @@ # Copyright (C) Yann Collet 2011-2016 # All rights reserved. # +# This Makefile is validated for Linux, macOS, *BSD, Hurd, Solaris, MSYS2 targets +# # BSD license # Redistribution and use in source and binary forms, with or without modification, # are permitted provided that the following conditions are met: diff --git a/contrib/gen_manual/gen-lz4-manual.sh b/contrib/gen_manual/gen-lz4-manual.sh index 55d31a4..73a7214 100644 --- a/contrib/gen_manual/gen-lz4-manual.sh +++ b/contrib/gen_manual/gen-lz4-manual.sh @@ -6,4 +6,5 @@ LIBVER_PATCH_SCRIPT=`sed -n '/define LZ4_VERSION_RELEASE/s/.*[[:blank:]]\([0-9][ LIBVER_SCRIPT=$LIBVER_MAJOR_SCRIPT.$LIBVER_MINOR_SCRIPT.$LIBVER_PATCH_SCRIPT echo LZ4_VERSION=$LIBVER_SCRIPT -./gen_manual $LIBVER_SCRIPT ../../lib/lz4.h ./lz4_manual.html +./gen_manual "lz4 $LIBVER_SCRIPT" ../../lib/lz4.h ./lz4_manual.html +./gen_manual "lz4frame $LIBVER_SCRIPT" ../../lib/lz4frame.h ./lz4frame_manual.html diff --git a/contrib/gen_manual/gen_manual.cpp b/contrib/gen_manual/gen_manual.cpp index 2df081d..65abd3a 100644 --- a/contrib/gen_manual/gen_manual.cpp +++ b/contrib/gen_manual/gen_manual.cpp @@ -89,11 +89,13 @@ vector<string> get_lines(vector<string>& input, int& linenum, string terminator) /* print line with LZ4LIB_API removed and C++ comments not bold */ void print_line(stringstream &sout, string line) { - size_t spos; + size_t spos, epos; if (line.substr(0,11) == "LZ4LIB_API ") line = line.substr(11); + if (line.substr(0,12) == "LZ4FLIB_API ") line = line.substr(12); spos = line.find("/*"); - if (spos!=string::npos) { + epos = line.find("*/"); + if (spos!=string::npos && epos!=string::npos) { sout << line.substr(0, spos); sout << "</b>" << line.substr(spos) << "<b>" << endl; } else { @@ -118,7 +120,7 @@ int main(int argc, char *argv[]) { return 1; } - version = "lz4 " + string(argv[1]) + " Manual"; + version = string(argv[1]) + " Manual"; istream.open(argv[2], ifstream::in); if (!istream.is_open()) { @@ -158,36 +160,28 @@ int main(int argc, char *argv[]) { continue; } - /* comments of type /*= and /**= mean: use a <H3> header and show also all functions until first empty line */ - if ((line.substr(0,3) == "/*=" || line.substr(0,4) == "/**=") && line.find("*/")!=string::npos) { - trim_comments(line); - trim(line, "= "); - sout << "<h3>" << line << "</h3><pre><b>"; - lines = get_lines(input, ++linenum, ""); - for (l=0; l<lines.size(); l++) { - print_line(sout, lines[l]); - } - sout << "</b></pre><BR>" << endl; - continue; + spos = line.find("/**="); + if (spos==string::npos) { + spos = line.find("/*!"); + if (spos==string::npos) + spos = line.find("/**"); + if (spos==string::npos) + spos = line.find("/*-"); + if (spos==string::npos) + spos = line.find("/*="); + if (spos==string::npos) + continue; + exclam = line[spos+2]; } + else exclam = '='; - spos = line.find("/*!"); - if (spos==string::npos) - spos = line.find("/**"); - if (spos==string::npos) - spos = line.find("/*-"); - - if (spos==string::npos) - continue; - - exclam = line[spos+2]; comments = get_lines(input, linenum, "*/"); if (!comments.empty()) comments[0] = line.substr(spos+3); if (!comments.empty()) comments[comments.size()-1] = comments[comments.size()-1].substr(0, comments[comments.size()-1].find("*/")); for (l=0; l<comments.size(); l++) { if (comments[l].find(" *")==0) comments[l] = comments[l].substr(2); else if (comments[l].find(" *")==0) comments[l] = comments[l].substr(3); - trim(comments[l], "*-"); + trim(comments[l], "*-="); } while (!comments.empty() && comments[comments.size()-1].empty()) comments.pop_back(); // remove empty line at the end while (!comments.empty() && comments[0].empty()) comments.erase(comments.begin()); // remove empty line at the start @@ -208,6 +202,18 @@ int main(int argc, char *argv[]) { print_line(sout, comments[l]); } sout << "</p></pre><BR>" << endl << endl; + } else if (exclam == '=') { /* comments of type /*= and /**= mean: use a <H3> header and show also all functions until first empty line */ + trim(comments[0], " "); + sout << "<h3>" << comments[0] << "</h3><pre>"; + for (l=1; l<comments.size(); l++) { + print_line(sout, comments[l]); + } + sout << "</pre><b><pre>"; + lines = get_lines(input, ++linenum, ""); + for (l=0; l<lines.size(); l++) { + print_line(sout, lines[l]); + } + sout << "</pre></b><BR>" << endl; } else { /* comments of type /** and /*- mean: this is a comment; use a <H2> header for the first line */ if (comments.empty()) continue; @@ -238,4 +244,4 @@ int main(int argc, char *argv[]) { ostream << "</html>" << endl << "</body>" << endl; return 0; -} +}
\ No newline at end of file diff --git a/doc/lz4_manual.html b/doc/lz4_manual.html index bc46645..ff6e149 100644 --- a/doc/lz4_manual.html +++ b/doc/lz4_manual.html @@ -1,20 +1,22 @@ <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> -<title>lz4 1.7.2 Manual</title> +<title>lz4 1.7.5 Manual</title> </head> <body> -<h1>lz4 1.7.2 Manual</h1> +<h1>lz4 1.7.5 Manual</h1> <hr> <a name="Contents"></a><h2>Contents</h2> <ol> <li><a href="#Chapter1">Introduction</a></li> -<li><a href="#Chapter2">Tuning parameter</a></li> -<li><a href="#Chapter3">Private definitions</a></li> +<li><a href="#Chapter2">Version</a></li> +<li><a href="#Chapter3">Tuning parameter</a></li> <li><a href="#Chapter4">Simple Functions</a></li> <li><a href="#Chapter5">Advanced Functions</a></li> <li><a href="#Chapter6">Streaming Compression Functions</a></li> <li><a href="#Chapter7">Streaming Decompression Functions</a></li> +<li><a href="#Chapter8">Private definitions</a></li> +<li><a href="#Chapter9">Obsolete Functions</a></li> </ol> <hr> <a name="Chapter1"></a><h2>Introduction</h2><pre> @@ -29,19 +31,26 @@ - unbounded multiple steps (described as Streaming compression) lz4.h provides block compression functions. It gives full buffer control to user. - Block compression functions are not-enough to send information, - since it's still necessary to provide metadata (such as compressed size), - and each application can do it in whichever way it wants. - For interoperability, there is LZ4 frame specification (doc/lz4_Frame_format.md). + 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. + + An additional format, called LZ4 frame specification (doc/lz4_Frame_format.md), + take care of encoding standard metadata alongside LZ4-compressed blocks. + If your application requires interoperability, it's recommended to use it. A library is provided to take care of it, see lz4frame.h. <BR></pre> -<h3>Version</h3><pre><b>int LZ4_versionNumber (void); -const char* LZ4_versionString (void); +<a name="Chapter2"></a><h2>Version</h2><pre></pre> + +<pre><b>int LZ4_versionNumber (void); </b>/**< library version number; to be used when checking dll version */<b> </b></pre><BR> -<a name="Chapter2"></a><h2>Tuning parameter</h2><pre></pre> +<pre><b>const char* LZ4_versionString (void); </b>/**< library version string; to be used when checking dll version */<b> +</b></pre><BR> +<a name="Chapter3"></a><h2>Tuning parameter</h2><pre></pre> -<pre><b>#define LZ4_MEMORY_USAGE 14 +<pre><b>#ifndef LZ4_MEMORY_USAGE +# define LZ4_MEMORY_USAGE 14 +#endif </b><p> Memory usage formula : N->2^N Bytes (examples : 10 -> 1KB; 12 -> 4KB ; 16 -> 64KB; 20 -> 1MB; etc.) Increasing memory usage improves compression ratio Reduced memory usage can improve speed, due to cache effect @@ -49,44 +58,6 @@ const char* LZ4_versionString (void); </p></pre><BR> -<a name="Chapter3"></a><h2>Private definitions</h2><pre> - Do not use these definitions. - They are exposed to allow static allocation of `LZ4_stream_t` and `LZ4_streamDecode_t`. - If you use these definitions in your code, it will break when you upgrade LZ4 to a new version. -<BR></pre> - -<pre><b>typedef struct { - uint32_t hashTable[LZ4_HASH_SIZE_U32]; - uint32_t currentOffset; - uint32_t initCheck; - const uint8_t* dictionary; - uint8_t* bufferStart; </b>/* obsolete, used for slideInputBuffer */<b> - uint32_t dictSize; -} LZ4_stream_t_internal; -</b></pre><BR> -<pre><b>typedef struct { - const uint8_t* externalDict; - size_t extDictSize; - const uint8_t* prefixEnd; - size_t prefixSize; -} LZ4_streamDecode_t_internal; -</b></pre><BR> -<pre><b>typedef struct { - unsigned int hashTable[LZ4_HASH_SIZE_U32]; - unsigned int currentOffset; - unsigned int initCheck; - const unsigned char* dictionary; - unsigned char* bufferStart; </b>/* obsolete, used for slideInputBuffer */<b> - unsigned int dictSize; -} LZ4_stream_t_internal; -</b></pre><BR> -<pre><b>typedef struct { - const unsigned char* externalDict; - size_t extDictSize; - const unsigned char* prefixEnd; - size_t prefixSize; -} LZ4_streamDecode_t_internal; -</b></pre><BR> <a name="Chapter4"></a><h2>Simple Functions</h2><pre></pre> <pre><b>int LZ4_compress_default(const char* source, char* dest, int sourceSize, int maxDestSize); @@ -178,30 +149,16 @@ int LZ4_compress_fast_extState (void* state, const char* source, char* dest, int <a name="Chapter6"></a><h2>Streaming Compression Functions</h2><pre></pre> -<pre><b>typedef struct { - union { - long long table[LZ4_STREAMSIZE_U64]; - LZ4_stream_t_internal internal_donotuse; - }; -} LZ4_stream_t; -</b><p> information structure to track an LZ4 stream. - important : init this structure content before first use ! - note : only allocated directly the structure if you are statically linking LZ4 - If you are using liblz4 as a DLL, please use below construction methods instead. - -</p></pre><BR> - -<pre><b>void LZ4_resetStream (LZ4_stream_t* streamPtr); -</b><p> Use this function to init an allocated `LZ4_stream_t` structure - -</p></pre><BR> - <pre><b>LZ4_stream_t* LZ4_createStream(void); int LZ4_freeStream (LZ4_stream_t* streamPtr); </b><p> LZ4_createStream() will allocate and initialize an `LZ4_stream_t` structure. LZ4_freeStream() releases its memory. - In the context of a DLL (liblz4), please use these methods rather than the static struct. - They are more future proof, in case of a change of `LZ4_stream_t` size. + +</p></pre><BR> + +<pre><b>void LZ4_resetStream (LZ4_stream_t* streamPtr); +</b><p> An LZ4_stream_t structure can be allocated once and re-used multiple times. + Use this function to init an allocated `LZ4_stream_t` structure and start a new compression. </p></pre><BR> @@ -231,24 +188,12 @@ int LZ4_freeStream (LZ4_stream_t* streamPtr); </p></pre><BR> -<a name="Chapter7"></a><h2>Streaming Decompression Functions</h2><pre></pre> +<a name="Chapter7"></a><h2>Streaming Decompression Functions</h2><pre> Bufferless synchronous API +<BR></pre> -<pre><b>typedef struct { - union { - unsigned long long table[LZ4_STREAMDECODESIZE_U64]; - LZ4_streamDecode_t_internal internal_donotuse; - }; -</b></pre><BR> <pre><b>LZ4_streamDecode_t* LZ4_createStreamDecode(void); int LZ4_freeStreamDecode (LZ4_streamDecode_t* LZ4_stream); -</b><p> information structure to track an LZ4 stream. - init this structure content using LZ4_setStreamDecode or memset() before first use ! - - In the context of a DLL (liblz4) please prefer usage of construction methods below. - They are more future proof, in case of a change of LZ4_streamDecode_t size in the future. - LZ4_createStreamDecode will allocate and initialize an LZ4_streamDecode_t structure - LZ4_freeStreamDecode releases its memory. - +</b><p> creation / destruction of streaming decompression tracking structure </p></pre><BR> <pre><b>int LZ4_setStreamDecode (LZ4_streamDecode_t* LZ4_streamDecode, const char* dictionary, int dictSize); @@ -278,10 +223,102 @@ int LZ4_decompress_fast_continue (LZ4_streamDecode_t* LZ4_streamDecode, const ch <pre><b>int LZ4_decompress_safe_usingDict (const char* source, char* dest, int compressedSize, int maxDecompressedSize, const char* dictStart, int dictSize); int LZ4_decompress_fast_usingDict (const char* source, char* dest, int originalSize, const char* dictStart, int dictSize); -</b><p>Advanced decoding functions : - These decoding functions work the same as - a combination of LZ4_setStreamDecode() followed by LZ4_decompress_x_continue() - They are stand-alone. They don't need nor update an LZ4_streamDecode_t structure. +</b><p> These decoding functions work the same as + a combination of LZ4_setStreamDecode() followed by LZ4_decompress_*_continue() + They are stand-alone, and don't need an LZ4_streamDecode_t structure. + +</p></pre><BR> + +<a name="Chapter8"></a><h2>Private definitions</h2><pre> + Do not use these definitions. + They are exposed to allow static allocation of `LZ4_stream_t` and `LZ4_streamDecode_t`. + Using these definitions will expose code to API and/or ABI break in future versions of the library. +<BR></pre> + +<pre><b>typedef struct { + uint32_t hashTable[LZ4_HASH_SIZE_U32]; + uint32_t currentOffset; + uint32_t initCheck; + const uint8_t* dictionary; + uint8_t* bufferStart; </b>/* obsolete, used for slideInputBuffer */<b> + uint32_t dictSize; +} LZ4_stream_t_internal; +</b></pre><BR> +<pre><b>typedef struct { + const uint8_t* externalDict; + size_t extDictSize; + const uint8_t* prefixEnd; + size_t prefixSize; +} LZ4_streamDecode_t_internal; +</b></pre><BR> +<pre><b>typedef struct { + unsigned int hashTable[LZ4_HASH_SIZE_U32]; + unsigned int currentOffset; + unsigned int initCheck; + const unsigned char* dictionary; + unsigned char* bufferStart; </b>/* obsolete, used for slideInputBuffer */<b> + unsigned int dictSize; +} LZ4_stream_t_internal; +</b></pre><BR> +<pre><b>typedef struct { + const unsigned char* externalDict; + size_t extDictSize; + const unsigned char* prefixEnd; + size_t prefixSize; +} LZ4_streamDecode_t_internal; +</b></pre><BR> +<pre><b>#define LZ4_STREAMSIZE_U64 ((1 << (LZ4_MEMORY_USAGE-3)) + 4) +#define LZ4_STREAMSIZE (LZ4_STREAMSIZE_U64 * sizeof(unsigned long long)) +union LZ4_stream_u { + unsigned long long table[LZ4_STREAMSIZE_U64]; + LZ4_stream_t_internal internal_donotuse; +} ; </b>/* previously typedef'd to LZ4_stream_t */<b> +</b><p> information structure to track an LZ4 stream. + init this structure before first use. + note : only use in association with static linking ! + this definition is not API/ABI safe, + and may change in a future version ! + +</p></pre><BR> + +<pre><b>#define LZ4_STREAMDECODESIZE_U64 4 +#define LZ4_STREAMDECODESIZE (LZ4_STREAMDECODESIZE_U64 * sizeof(unsigned long long)) +union LZ4_streamDecode_u { + unsigned long long table[LZ4_STREAMDECODESIZE_U64]; + LZ4_streamDecode_t_internal internal_donotuse; +} ; </b>/* previously typedef'd to LZ4_streamDecode_t */<b> +</b><p> information structure to track an LZ4 stream during decompression. + init this structure using LZ4_setStreamDecode (or memset()) before first use + note : only use in association with static linking ! + this definition is not API/ABI safe, + and may change in a future version ! + +</p></pre><BR> + +<a name="Chapter9"></a><h2>Obsolete Functions</h2><pre></pre> + +<pre><b>#ifdef LZ4_DISABLE_DEPRECATE_WARNINGS +# define LZ4_DEPRECATED(message) </b>/* disable deprecation warnings */<b> +#else +# define LZ4_GCC_VERSION (__GNUC__ * 100 + __GNUC_MINOR__) +# if defined (__cplusplus) && (__cplusplus >= 201402) </b>/* C++14 or greater */<b> +# define LZ4_DEPRECATED(message) [[deprecated(message)]] +# elif (LZ4_GCC_VERSION >= 405) || defined(__clang__) +# define LZ4_DEPRECATED(message) __attribute__((deprecated(message))) +# elif (LZ4_GCC_VERSION >= 301) +# define LZ4_DEPRECATED(message) __attribute__((deprecated)) +# elif defined(_MSC_VER) +# define LZ4_DEPRECATED(message) __declspec(deprecated(message)) +# else +# pragma message("WARNING: You need to implement LZ4_DEPRECATED for this compiler") +# define LZ4_DEPRECATED(message) +# endif +#endif </b>/* LZ4_DISABLE_DEPRECATE_WARNINGS */<b> +</b><p> Should deprecation warnings be a problem, + it is generally possible to disable them, + typically with -Wno-deprecated-declarations for gcc + or _CRT_SECURE_NO_WARNINGS in Visual. + Otherwise, it's also possible to define LZ4_DISABLE_DEPRECATE_WARNINGS </p></pre><BR> </html> diff --git a/doc/lz4frame_manual.html b/doc/lz4frame_manual.html new file mode 100644 index 0000000..f76ec3d --- /dev/null +++ b/doc/lz4frame_manual.html @@ -0,0 +1,240 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>lz4frame 1.7.5 Manual</title> +</head> +<body> +<h1>lz4frame 1.7.5 Manual</h1> +<hr> +<a name="Contents"></a><h2>Contents</h2> +<ol> +<li><a href="#Chapter1">Introduction</a></li> +<li><a href="#Chapter2">Error management</a></li> +<li><a href="#Chapter3">Frame compression types</a></li> +<li><a href="#Chapter4">Simple compression function</a></li> +<li><a href="#Chapter5">Advanced compression functions</a></li> +<li><a href="#Chapter6">Decompression functions</a></li> +</ol> +<hr> +<a name="Chapter1"></a><h2>Introduction</h2><pre> + lz4frame.h implements LZ4 frame specification (doc/lz4_Frame_format.md). + lz4frame.h provides frame compression functions that take care + of encoding standard metadata alongside LZ4-compressed blocks. +<BR></pre> + +<a name="Chapter2"></a><h2>Error management</h2><pre></pre> + +<pre><b>unsigned LZ4F_isError(LZ4F_errorCode_t code); </b>/**< tells if a `LZ4F_errorCode_t` function result is an error code */<b> +</b></pre><BR> +<pre><b>const char* LZ4F_getErrorName(LZ4F_errorCode_t code); </b>/**< return error code string; useful for debugging */<b> +</b></pre><BR> +<a name="Chapter3"></a><h2>Frame compression types</h2><pre></pre> + +<pre><b>typedef enum { + LZ4F_default=0, + LZ4F_max64KB=4, + LZ4F_max256KB=5, + LZ4F_max1MB=6, + LZ4F_max4MB=7 + LZ4F_OBSOLETE_ENUM(max64KB) + LZ4F_OBSOLETE_ENUM(max256KB) + LZ4F_OBSOLETE_ENUM(max1MB) + LZ4F_OBSOLETE_ENUM(max4MB) +} LZ4F_blockSizeID_t; +</b></pre><BR> +<pre><b>typedef enum { + LZ4F_blockLinked=0, + LZ4F_blockIndependent + LZ4F_OBSOLETE_ENUM(blockLinked) + LZ4F_OBSOLETE_ENUM(blockIndependent) +} LZ4F_blockMode_t; +</b></pre><BR> +<pre><b>typedef enum { + LZ4F_noContentChecksum=0, + LZ4F_contentChecksumEnabled + LZ4F_OBSOLETE_ENUM(noContentChecksum) + LZ4F_OBSOLETE_ENUM(contentChecksumEnabled) +} LZ4F_contentChecksum_t; +</b></pre><BR> +<pre><b>typedef enum { + LZ4F_frame=0, + LZ4F_skippableFrame + LZ4F_OBSOLETE_ENUM(skippableFrame) +} LZ4F_frameType_t; +</b></pre><BR> +<pre><b>typedef struct { + LZ4F_blockSizeID_t blockSizeID; </b>/* max64KB, max256KB, max1MB, max4MB ; 0 == default */<b> + LZ4F_blockMode_t blockMode; </b>/* blockLinked, blockIndependent ; 0 == default */<b> + LZ4F_contentChecksum_t contentChecksumFlag; </b>/* noContentChecksum, contentChecksumEnabled ; 0 == default */<b> + LZ4F_frameType_t frameType; </b>/* LZ4F_frame, skippableFrame ; 0 == default */<b> + unsigned long long contentSize; </b>/* Size of uncompressed (original) content ; 0 == unknown */<b> + unsigned reserved[2]; </b>/* must be zero for forward compatibility */<b> +} LZ4F_frameInfo_t; +</b><p> makes it possible to supply detailed frame parameters to the stream interface. + It's not required to set all fields, as long as the structure was initially memset() to zero. + All reserved fields must be set to zero. +</p></pre><BR> + +<pre><b>typedef struct { + LZ4F_frameInfo_t frameInfo; + int compressionLevel; </b>/* 0 == default (fast mode); values above 16 count as 16; values below 0 count as 0 */<b> + unsigned autoFlush; </b>/* 1 == always flush (reduce usage of tmp buffer) */<b> + unsigned reserved[4]; </b>/* must be zero for forward compatibility */<b> +} LZ4F_preferences_t; +</b><p> makes it possible to supply detailed compression parameters to the stream interface. + It's not required to set all fields, as long as the structure was initially memset() to zero. + All reserved fields must be set to zero. +</p></pre><BR> + +<a name="Chapter4"></a><h2>Simple compression function</h2><pre></pre> + +<pre><b>size_t LZ4F_compressFrameBound(size_t srcSize, const LZ4F_preferences_t* preferencesPtr); +</b><p> Returns the maximum possible size of a frame compressed with LZ4F_compressFrame() given srcSize content and preferences. + Note : this result is only usable with LZ4F_compressFrame(), not with multi-segments compression. + +</p></pre><BR> + +<pre><b>size_t LZ4F_compressFrame(void* dstBuffer, size_t dstCapacity, const void* srcBuffer, size_t srcSize, const LZ4F_preferences_t* preferencesPtr); +</b><p> Compress an entire srcBuffer into a valid LZ4 frame, as defined by specification v1.5.1 + An important rule is that dstBuffer MUST be large enough (dstCapacity) to store the result in worst case situation. + This value is supplied by LZ4F_compressFrameBound(). + If this condition is not respected, LZ4F_compressFrame() will fail (result is an errorCode). + The LZ4F_preferences_t structure is optional : you can provide NULL as argument. All preferences will be set to default. + @return : number of bytes written into dstBuffer. + or an error code if it fails (can be tested using LZ4F_isError()) + +</p></pre><BR> + +<a name="Chapter5"></a><h2>Advanced compression functions</h2><pre></pre> + +<pre><b>typedef struct { + unsigned stableSrc; </b>/* 1 == src content will remain present on future calls to LZ4F_compress(); skip copying src content within tmp buffer */<b> + unsigned reserved[3]; +} LZ4F_compressOptions_t; +</b></pre><BR> +<pre><b>LZ4F_errorCode_t LZ4F_createCompressionContext(LZ4F_cctx** cctxPtr, unsigned version); +LZ4F_errorCode_t LZ4F_freeCompressionContext(LZ4F_cctx* cctx); +</b><p> The first thing to do is to create a compressionContext object, which will be used in all compression operations. + This is achieved using LZ4F_createCompressionContext(), which takes as argument a version and an LZ4F_preferences_t structure. + The version provided MUST be LZ4F_VERSION. It is intended to track potential version mismatch, notably when using DLL. + The function will provide a pointer to a fully allocated LZ4F_cctx object. + If @return != zero, there was an error during context creation. + Object can release its memory using LZ4F_freeCompressionContext(); + +</p></pre><BR> + +<pre><b>size_t LZ4F_compressBegin(LZ4F_cctx* cctx, void* dstBuffer, size_t dstCapacity, const LZ4F_preferences_t* prefsPtr); +</b><p> will write the frame header into dstBuffer. + dstCapacity must be large enough to store the header. Maximum header size is LZ4F_HEADER_SIZE_MAX bytes. + `prefsPtr` is optional : you can provide NULL as argument, all preferences will then be set to default. + @return : number of bytes written into dstBuffer for the header + or an error code (which can be tested using LZ4F_isError()) + +</p></pre><BR> + +<pre><b>size_t LZ4F_compressBound(size_t srcSize, const LZ4F_preferences_t* prefsPtr); +</b><p> Provides dstCapacity given a srcSize to guarantee operation success in worst case situations. + prefsPtr is optional : you can provide NULL as argument, preferences will be set to cover worst case scenario. + Result is always the same for a srcSize and prefsPtr, so it can be trusted to size reusable buffers. + When srcSize==0, LZ4F_compressBound() provides an upper bound for LZ4F_flush() and LZ4F_compressEnd() operations. + +</p></pre><BR> + +<pre><b>size_t LZ4F_compressUpdate(LZ4F_cctx* cctx, void* dstBuffer, size_t dstCapacity, const void* srcBuffer, size_t srcSize, const LZ4F_compressOptions_t* cOptPtr); +</b><p> LZ4F_compressUpdate() can be called repetitively to compress as much data as necessary. + An important rule is that dstCapacity MUST be large enough to ensure operation success even in worst case situations. + This value is provided by LZ4F_compressBound(). + If this condition is not respected, LZ4F_compress() will fail (result is an errorCode). + LZ4F_compressUpdate() doesn't guarantee error recovery. When an error occurs, compression context must be freed or resized. + `cOptPtr` is optional : NULL can be provided, in which case all options are set to default. + @return : number of bytes written into `dstBuffer` (it can be zero, meaning input data was just buffered). + or an error code if it fails (which can be tested using LZ4F_isError()) + +</p></pre><BR> + +<pre><b>size_t LZ4F_flush(LZ4F_cctx* cctx, void* dstBuffer, size_t dstCapacity, const LZ4F_compressOptions_t* cOptPtr); +</b><p> When data must be generated and sent immediately, without waiting for a block to be completely filled, + it's possible to call LZ4_flush(). It will immediately compress any data buffered within cctx. + `dstCapacity` must be large enough to ensure the operation will be successful. + `cOptPtr` is optional : it's possible to provide NULL, all options will be set to default. + @return : number of bytes written into dstBuffer (it can be zero, which means there was no data stored within cctx) + or an error code if it fails (which can be tested using LZ4F_isError()) + +</p></pre><BR> + +<pre><b>size_t LZ4F_compressEnd(LZ4F_cctx* cctx, void* dstBuffer, size_t dstCapacity, const LZ4F_compressOptions_t* cOptPtr); +</b><p> To properly finish an LZ4 frame, invoke LZ4F_compressEnd(). + It will flush whatever data remained within `cctx` (like LZ4_flush()) + and properly finalize the frame, with an endMark and a checksum. + `cOptPtr` is optional : NULL can be provided, in which case all options will be set to default. + @return : number of bytes written into dstBuffer (necessarily >= 4 (endMark), or 8 if optional frame checksum is enabled) + or an error code if it fails (which can be tested using LZ4F_isError()) + A successful call to LZ4F_compressEnd() makes `cctx` available again for another compression task. + +</p></pre><BR> + +<a name="Chapter6"></a><h2>Decompression functions</h2><pre></pre> + +<pre><b>typedef struct { + unsigned stableDst; </b>/* guarantee that decompressed data will still be there on next function calls (avoid storage into tmp buffers) */<b> + unsigned reserved[3]; +} LZ4F_decompressOptions_t; +</b></pre><BR> +<pre><b>LZ4F_errorCode_t LZ4F_createDecompressionContext(LZ4F_dctx** dctxPtr, unsigned version); +LZ4F_errorCode_t LZ4F_freeDecompressionContext(LZ4F_dctx* const dctx); +</b><p> Create an LZ4F_decompressionContext_t object, which will be used to track all decompression operations. + The version provided MUST be LZ4F_VERSION. It is intended to track potential breaking differences between different versions. + The function will provide a pointer to a fully allocated and initialized LZ4F_decompressionContext_t object. + The result is an errorCode, which can be tested using LZ4F_isError(). + dctx memory can be released using LZ4F_freeDecompressionContext(); + The result of LZ4F_freeDecompressionContext() is indicative of the current state of decompressionContext when being released. + That is, it should be == 0 if decompression has been completed fully and correctly. + +</p></pre><BR> + +<pre><b>size_t LZ4F_getFrameInfo(LZ4F_dctx* dctx, + LZ4F_frameInfo_t* frameInfoPtr, + const void* srcBuffer, size_t* srcSizePtr); +</b><p> This function decodes frame header information (such as max blockSize, frame checksum, etc.). + Its usage is optional. The objective is to extract frame header information, typically for allocation purposes. + A header size is variable and can length from 7 to 15 bytes. It's possible to provide more input bytes than that. + The number of bytes consumed from srcBuffer will be updated within *srcSizePtr (necessarily <= original value). + Decompression must resume from this point (srcBuffer + *srcSizePtr). + Note that LZ4F_getFrameInfo() can also be used anytime *after* decompression is started, in which case 0 input byte can be enough. + Frame header info is *copied into* an already allocated LZ4F_frameInfo_t structure. + @return : an hint about how many srcSize bytes LZ4F_decompress() expects for next call, + or an error code which can be tested using LZ4F_isError() + (typically, when there is not enough src bytes to fully decode the frame header) + +</p></pre><BR> + +<pre><b>size_t LZ4F_decompress(LZ4F_dctx* dctx, + void* dstBuffer, size_t* dstSizePtr, + const void* srcBuffer, size_t* srcSizePtr, + const LZ4F_decompressOptions_t* dOptPtr); +</b><p> Call this function repetitively to regenerate data compressed within `srcBuffer`. + The function will attempt to decode up to *srcSizePtr bytes from srcBuffer, into dstBuffer of capacity *dstSizePtr. + + The number of bytes regenerated into dstBuffer will be provided within *dstSizePtr (necessarily <= original value). + + The number of bytes read from srcBuffer will be provided within *srcSizePtr (necessarily <= original value). + Number of bytes read can be < number of bytes provided, meaning there is some more data to decode. + It typically happens when dstBuffer is not large enough to contain all decoded data. + Remaining data will have to be presented again in a subsequent invocation. + + `dstBuffer` content is expected to be flushed between each invocation, as its content will be overwritten. + `dstBuffer` can be changed at will between each consecutive function invocation. + + @return is an hint of how many `srcSize` bytes LZ4F_decompress() expects for next call. + Schematically, it's the size of the current (or remaining) compressed block + header of next block. + Respecting the hint provides some boost to performance, since it does skip intermediate buffers. + This is just a hint though, it's always possible to provide any srcSize. + When a frame is fully decoded, @return will be 0 (no more data expected). + If decompression failed, @return is an error code, which can be tested using LZ4F_isError(). + + After a frame is fully decoded, dctx can be used again to decompress another frame. + +</p></pre><BR> + +</html> +</body> diff --git a/lib/Makefile b/lib/Makefile index 2d9c8f3..7ba9ccb 100644 --- a/lib/Makefile +++ b/lib/Makefile @@ -3,6 +3,8 @@ # Copyright (C) Yann Collet 2011-2016 # All rights reserved. # +# This Makefile is validated for Linux, macOS, *BSD, Hurd, Solaris, MSYS2 targets +# # BSD license # Redistribution and use in source and binary forms, with or without modification, # are permitted provided that the following conditions are met: @@ -82,7 +82,7 @@ extern "C" { #endif -/*========== Version =========== */ +/*------ Version ------*/ #define LZ4_VERSION_MAJOR 1 /* for breaking interface changes */ #define LZ4_VERSION_MINOR 7 /* for new (non-breaking) interface capabilities */ #define LZ4_VERSION_RELEASE 5 /* for tweaks, bug-fixes, or development */ @@ -94,8 +94,8 @@ extern "C" { #define LZ4_EXPAND_AND_QUOTE(str) LZ4_QUOTE(str) #define LZ4_VERSION_STRING LZ4_EXPAND_AND_QUOTE(LZ4_LIB_VERSION) -LZ4LIB_API int LZ4_versionNumber (void); -LZ4LIB_API const char* LZ4_versionString (void); +LZ4LIB_API int LZ4_versionNumber (void); /**< library version number; to be used when checking dll version */ +LZ4LIB_API const char* LZ4_versionString (void); /**< library version string; to be used when checking dll version */ /*-************************************ @@ -275,7 +275,8 @@ LZ4LIB_API int LZ4_saveDict (LZ4_stream_t* streamPtr, char* safeBuffer, int dict ************************************************/ typedef union LZ4_streamDecode_u LZ4_streamDecode_t; /* incomplete type (defined later) */ -/* creation / destruction of streaming decompression tracking structure */ +/*! LZ4_createStreamDecode() and LZ4_freeStreamDecode() : + * creation / destruction of streaming decompression tracking structure */ LZ4LIB_API LZ4_streamDecode_t* LZ4_createStreamDecode(void); LZ4LIB_API int LZ4_freeStreamDecode (LZ4_streamDecode_t* LZ4_stream); @@ -401,11 +402,12 @@ union LZ4_streamDecode_u { } ; /* previously typedef'd to LZ4_streamDecode_t */ -/*=************************************ +/*-************************************ * Obsolete Functions **************************************/ -/* Deprecation warnings */ -/* Should these warnings be a problem, + +/*! Deprecation warnings + Should deprecation warnings be a problem, it is generally possible to disable them, typically with -Wno-deprecated-declarations for gcc or _CRT_SECURE_NO_WARNINGS in Visual. diff --git a/lib/lz4frame.h b/lib/lz4frame.h index a4a4ce6..82fbeab 100644 --- a/lib/lz4frame.h +++ b/lib/lz4frame.h @@ -48,10 +48,19 @@ extern "C" { /* --- Dependency --- */ #include <stddef.h> /* size_t */ -/*-*************************************************************** + +/** + Introduction + + lz4frame.h implements LZ4 frame specification (doc/lz4_Frame_format.md). + lz4frame.h provides frame compression functions that take care + of encoding standard metadata alongside LZ4-compressed blocks. +*/ + +/*^*************************************************************** * Compiler specifics *****************************************************************/ -/*! +/* * LZ4_DLL_EXPORT : * Enable exporting of functions when building a Windows DLL */ @@ -77,8 +86,8 @@ extern "C" { **************************************/ typedef size_t LZ4F_errorCode_t; -LZ4FLIB_API unsigned LZ4F_isError(LZ4F_errorCode_t code); -LZ4FLIB_API const char* LZ4F_getErrorName(LZ4F_errorCode_t code); /* return error code string; useful for debugging */ +LZ4FLIB_API unsigned LZ4F_isError(LZ4F_errorCode_t code); /**< tells if a `LZ4F_errorCode_t` function result is an error code */ +LZ4FLIB_API const char* LZ4F_getErrorName(LZ4F_errorCode_t code); /**< return error code string; useful for debugging */ /*-************************************ @@ -130,7 +139,7 @@ typedef LZ4F_frameType_t frameType_t; typedef LZ4F_contentChecksum_t contentChecksum_t; #endif -/* LZ4F_frameInfo_t : +/*! LZ4F_frameInfo_t : * makes it possible to supply detailed frame parameters to the stream interface. * It's not required to set all fields, as long as the structure was initially memset() to zero. * All reserved fields must be set to zero. */ @@ -143,7 +152,7 @@ typedef struct { unsigned reserved[2]; /* must be zero for forward compatibility */ } LZ4F_frameInfo_t; -/* LZ4F_preferences_t : +/*! LZ4F_preferences_t : * makes it possible to supply detailed compression parameters to the stream interface. * It's not required to set all fields, as long as the structure was initially memset() to zero. * All reserved fields must be set to zero. */ @@ -192,9 +201,7 @@ typedef struct { #define LZ4F_VERSION 100 LZ4FLIB_API unsigned LZ4F_getVersion(void); -LZ4FLIB_API LZ4F_errorCode_t LZ4F_createCompressionContext(LZ4F_cctx** cctxPtr, unsigned version); -LZ4FLIB_API LZ4F_errorCode_t LZ4F_freeCompressionContext(LZ4F_cctx* cctx); -/* LZ4F_createCompressionContext() : +/*! LZ4F_createCompressionContext() : * The first thing to do is to create a compressionContext object, which will be used in all compression operations. * This is achieved using LZ4F_createCompressionContext(), which takes as argument a version and an LZ4F_preferences_t structure. * The version provided MUST be LZ4F_VERSION. It is intended to track potential version mismatch, notably when using DLL. @@ -202,30 +209,31 @@ LZ4FLIB_API LZ4F_errorCode_t LZ4F_freeCompressionContext(LZ4F_cctx* cctx); * If @return != zero, there was an error during context creation. * Object can release its memory using LZ4F_freeCompressionContext(); */ +LZ4FLIB_API LZ4F_errorCode_t LZ4F_createCompressionContext(LZ4F_cctx** cctxPtr, unsigned version); +LZ4FLIB_API LZ4F_errorCode_t LZ4F_freeCompressionContext(LZ4F_cctx* cctx); /* Compression */ #define LZ4F_HEADER_SIZE_MAX 15 -LZ4FLIB_API size_t LZ4F_compressBegin(LZ4F_cctx* cctx, void* dstBuffer, size_t dstCapacity, const LZ4F_preferences_t* prefsPtr); -/* LZ4F_compressBegin() : +/*! LZ4F_compressBegin() : * will write the frame header into dstBuffer. * dstCapacity must be large enough to store the header. Maximum header size is LZ4F_HEADER_SIZE_MAX bytes. * `prefsPtr` is optional : you can provide NULL as argument, all preferences will then be set to default. * @return : number of bytes written into dstBuffer for the header * or an error code (which can be tested using LZ4F_isError()) */ +LZ4FLIB_API size_t LZ4F_compressBegin(LZ4F_cctx* cctx, void* dstBuffer, size_t dstCapacity, const LZ4F_preferences_t* prefsPtr); -LZ4FLIB_API size_t LZ4F_compressBound(size_t srcSize, const LZ4F_preferences_t* prefsPtr); -/* LZ4F_compressBound() : +/*! LZ4F_compressBound() : * Provides dstCapacity given a srcSize to guarantee operation success in worst case situations. * prefsPtr is optional : you can provide NULL as argument, preferences will be set to cover worst case scenario. * Result is always the same for a srcSize and prefsPtr, so it can be trusted to size reusable buffers. * When srcSize==0, LZ4F_compressBound() provides an upper bound for LZ4F_flush() and LZ4F_compressEnd() operations. */ +LZ4FLIB_API size_t LZ4F_compressBound(size_t srcSize, const LZ4F_preferences_t* prefsPtr); -LZ4FLIB_API size_t LZ4F_compressUpdate(LZ4F_cctx* cctx, void* dstBuffer, size_t dstCapacity, const void* srcBuffer, size_t srcSize, const LZ4F_compressOptions_t* cOptPtr); -/* LZ4F_compressUpdate() : +/*! LZ4F_compressUpdate() : * LZ4F_compressUpdate() can be called repetitively to compress as much data as necessary. * An important rule is that dstCapacity MUST be large enough to ensure operation success even in worst case situations. * This value is provided by LZ4F_compressBound(). @@ -235,9 +243,9 @@ LZ4FLIB_API size_t LZ4F_compressUpdate(LZ4F_cctx* cctx, void* dstBuffer, size_t * @return : number of bytes written into `dstBuffer` (it can be zero, meaning input data was just buffered). * or an error code if it fails (which can be tested using LZ4F_isError()) */ +LZ4FLIB_API size_t LZ4F_compressUpdate(LZ4F_cctx* cctx, void* dstBuffer, size_t dstCapacity, const void* srcBuffer, size_t srcSize, const LZ4F_compressOptions_t* cOptPtr); -LZ4FLIB_API size_t LZ4F_flush(LZ4F_cctx* cctx, void* dstBuffer, size_t dstCapacity, const LZ4F_compressOptions_t* cOptPtr); -/* LZ4F_flush() : +/*! LZ4F_flush() : * When data must be generated and sent immediately, without waiting for a block to be completely filled, * it's possible to call LZ4_flush(). It will immediately compress any data buffered within cctx. * `dstCapacity` must be large enough to ensure the operation will be successful. @@ -245,9 +253,9 @@ LZ4FLIB_API size_t LZ4F_flush(LZ4F_cctx* cctx, void* dstBuffer, size_t dstCapaci * @return : number of bytes written into dstBuffer (it can be zero, which means there was no data stored within cctx) * or an error code if it fails (which can be tested using LZ4F_isError()) */ +LZ4FLIB_API size_t LZ4F_flush(LZ4F_cctx* cctx, void* dstBuffer, size_t dstCapacity, const LZ4F_compressOptions_t* cOptPtr); -LZ4FLIB_API size_t LZ4F_compressEnd(LZ4F_cctx* cctx, void* dstBuffer, size_t dstCapacity, const LZ4F_compressOptions_t* cOptPtr); -/* LZ4F_compressEnd() : +/*! LZ4F_compressEnd() : * To properly finish an LZ4 frame, invoke LZ4F_compressEnd(). * It will flush whatever data remained within `cctx` (like LZ4_flush()) * and properly finalize the frame, with an endMark and a checksum. @@ -256,6 +264,7 @@ LZ4FLIB_API size_t LZ4F_compressEnd(LZ4F_cctx* cctx, void* dstBuffer, size_t dst * or an error code if it fails (which can be tested using LZ4F_isError()) * A successful call to LZ4F_compressEnd() makes `cctx` available again for another compression task. */ +LZ4FLIB_API size_t LZ4F_compressEnd(LZ4F_cctx* cctx, void* dstBuffer, size_t dstCapacity, const LZ4F_compressOptions_t* cOptPtr); /*-********************************* @@ -285,7 +294,7 @@ LZ4FLIB_API LZ4F_errorCode_t LZ4F_createDecompressionContext(LZ4F_dctx** dctxPtr LZ4FLIB_API LZ4F_errorCode_t LZ4F_freeDecompressionContext(LZ4F_dctx* const dctx); -/*====== Decompression ======*/ +/* ====== Decompression ======*/ /*!LZ4F_getFrameInfo() : * This function decodes frame header information (such as max blockSize, frame checksum, etc.). diff --git a/programs/Makefile b/programs/Makefile index 060ce21..8a271c2 100644 --- a/programs/Makefile +++ b/programs/Makefile @@ -2,6 +2,8 @@ # LZ4 programs - Makefile # Copyright (C) Yann Collet 2011-2016 # +# This Makefile is validated for Linux, macOS, *BSD, Hurd, Solaris, MSYS2 targets +# # GPL v2 License # # This program is free software; you can redistribute it and/or modify diff --git a/tests/Makefile b/tests/Makefile index 97fa782..5f8efb7 100644 --- a/tests/Makefile +++ b/tests/Makefile @@ -2,6 +2,8 @@ # LZ4 programs - Makefile # Copyright (C) Yann Collet 2011-2016 # +# This Makefile is validated for Linux, macOS, *BSD, Hurd, Solaris, MSYS2 targets +# # GPL v2 License # # This program is free software; you can redistribute it and/or modify |