1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> 4<title>1.8.3 Manual</title> 5</head> 6<body> 7<h1>1.8.3 Manual</h1> 8<hr> 9<a name="Contents"></a><h2>Contents</h2> 10<ol> 11<li><a href="#Chapter1">Introduction</a></li> 12<li><a href="#Chapter2">Compiler specifics</a></li> 13<li><a href="#Chapter3">Error management</a></li> 14<li><a href="#Chapter4">Frame compression types</a></li> 15<li><a href="#Chapter5">Simple compression function</a></li> 16<li><a href="#Chapter6">Advanced compression functions</a></li> 17<li><a href="#Chapter7">Resource Management</a></li> 18<li><a href="#Chapter8">Compression</a></li> 19<li><a href="#Chapter9">Decompression functions</a></li> 20<li><a href="#Chapter10">Streaming decompression functions</a></li> 21<li><a href="#Chapter11">Bulk processing dictionary API</a></li> 22</ol> 23<hr> 24<a name="Chapter1"></a><h2>Introduction</h2><pre> 25 lz4frame.h implements LZ4 frame specification (doc/lz4_Frame_format.md). 26 lz4frame.h provides frame compression functions that take care 27 of encoding standard metadata alongside LZ4-compressed blocks. 28<BR></pre> 29 30<a name="Chapter2"></a><h2>Compiler specifics</h2><pre></pre> 31 32<a name="Chapter3"></a><h2>Error management</h2><pre></pre> 33 34<pre><b>unsigned LZ4F_isError(LZ4F_errorCode_t code); </b>/**< tells when a function result is an error code */<b> 35</b></pre><BR> 36<pre><b>const char* LZ4F_getErrorName(LZ4F_errorCode_t code); </b>/**< return error code string; for debugging */<b> 37</b></pre><BR> 38<a name="Chapter4"></a><h2>Frame compression types</h2><pre></pre> 39 40<pre><b>typedef enum { 41 LZ4F_default=0, 42 LZ4F_max64KB=4, 43 LZ4F_max256KB=5, 44 LZ4F_max1MB=6, 45 LZ4F_max4MB=7 46 LZ4F_OBSOLETE_ENUM(max64KB) 47 LZ4F_OBSOLETE_ENUM(max256KB) 48 LZ4F_OBSOLETE_ENUM(max1MB) 49 LZ4F_OBSOLETE_ENUM(max4MB) 50} LZ4F_blockSizeID_t; 51</b></pre><BR> 52<pre><b>typedef enum { 53 LZ4F_blockLinked=0, 54 LZ4F_blockIndependent 55 LZ4F_OBSOLETE_ENUM(blockLinked) 56 LZ4F_OBSOLETE_ENUM(blockIndependent) 57} LZ4F_blockMode_t; 58</b></pre><BR> 59<pre><b>typedef enum { 60 LZ4F_noContentChecksum=0, 61 LZ4F_contentChecksumEnabled 62 LZ4F_OBSOLETE_ENUM(noContentChecksum) 63 LZ4F_OBSOLETE_ENUM(contentChecksumEnabled) 64} LZ4F_contentChecksum_t; 65</b></pre><BR> 66<pre><b>typedef enum { 67 LZ4F_noBlockChecksum=0, 68 LZ4F_blockChecksumEnabled 69} LZ4F_blockChecksum_t; 70</b></pre><BR> 71<pre><b>typedef enum { 72 LZ4F_frame=0, 73 LZ4F_skippableFrame 74 LZ4F_OBSOLETE_ENUM(skippableFrame) 75} LZ4F_frameType_t; 76</b></pre><BR> 77<pre><b>typedef struct { 78 LZ4F_blockSizeID_t blockSizeID; </b>/* max64KB, max256KB, max1MB, max4MB; 0 == default */<b> 79 LZ4F_blockMode_t blockMode; </b>/* LZ4F_blockLinked, LZ4F_blockIndependent; 0 == default */<b> 80 LZ4F_contentChecksum_t contentChecksumFlag; </b>/* 1: frame terminated with 32-bit checksum of decompressed data; 0: disabled (default) */<b> 81 LZ4F_frameType_t frameType; </b>/* read-only field : LZ4F_frame or LZ4F_skippableFrame */<b> 82 unsigned long long contentSize; </b>/* Size of uncompressed content ; 0 == unknown */<b> 83 unsigned dictID; </b>/* Dictionary ID, sent by compressor to help decoder select correct dictionary; 0 == no dictID provided */<b> 84 LZ4F_blockChecksum_t blockChecksumFlag; </b>/* 1: each block followed by a checksum of block's compressed data; 0: disabled (default) */<b> 85} LZ4F_frameInfo_t; 86</b><p> makes it possible to set or read frame parameters. 87 It's not required to set all fields, as long as the structure was initially memset() to zero. 88 For all fields, 0 sets it to default value 89</p></pre><BR> 90 91<pre><b>typedef struct { 92 LZ4F_frameInfo_t frameInfo; 93 int compressionLevel; </b>/* 0: default (fast mode); values > LZ4HC_CLEVEL_MAX count as LZ4HC_CLEVEL_MAX; values < 0 trigger "fast acceleration" */<b> 94 unsigned autoFlush; </b>/* 1: always flush, to reduce usage of internal buffers */<b> 95 unsigned favorDecSpeed; </b>/* 1: parser favors decompression speed vs compression ratio. Only works for high compression modes (>= LZ4LZ4HC_CLEVEL_OPT_MIN) */ /* >= v1.8.2 */<b> 96 unsigned reserved[3]; </b>/* must be zero for forward compatibility */<b> 97} LZ4F_preferences_t; 98</b><p> makes it possible to supply detailed compression parameters to the stream interface. 99 Structure is presumed initially memset() to zero, representing default settings. 100 All reserved fields must be set to zero. 101</p></pre><BR> 102 103<a name="Chapter5"></a><h2>Simple compression function</h2><pre></pre> 104 105<pre><b>size_t LZ4F_compressFrameBound(size_t srcSize, const LZ4F_preferences_t* preferencesPtr); 106</b><p> Returns the maximum possible compressed size with LZ4F_compressFrame() given srcSize and preferences. 107 `preferencesPtr` is optional. It can be replaced by NULL, in which case, the function will assume default preferences. 108 Note : this result is only usable with LZ4F_compressFrame(). 109 It may also be used with LZ4F_compressUpdate() _if no flush() operation_ is performed. 110 111</p></pre><BR> 112 113<pre><b>size_t LZ4F_compressFrame(void* dstBuffer, size_t dstCapacity, 114 const void* srcBuffer, size_t srcSize, 115 const LZ4F_preferences_t* preferencesPtr); 116</b><p> Compress an entire srcBuffer into a valid LZ4 frame. 117 dstCapacity MUST be >= LZ4F_compressFrameBound(srcSize, preferencesPtr). 118 The LZ4F_preferences_t structure is optional : you can provide NULL as argument. All preferences will be set to default. 119 @return : number of bytes written into dstBuffer. 120 or an error code if it fails (can be tested using LZ4F_isError()) 121 122</p></pre><BR> 123 124<a name="Chapter6"></a><h2>Advanced compression functions</h2><pre></pre> 125 126<pre><b>typedef struct { 127 unsigned stableSrc; </b>/* 1 == src content will remain present on future calls to LZ4F_compress(); skip copying src content within tmp buffer */<b> 128 unsigned reserved[3]; 129} LZ4F_compressOptions_t; 130</b></pre><BR> 131<a name="Chapter7"></a><h2>Resource Management</h2><pre></pre> 132 133<pre><b>LZ4F_errorCode_t LZ4F_createCompressionContext(LZ4F_cctx** cctxPtr, unsigned version); 134LZ4F_errorCode_t LZ4F_freeCompressionContext(LZ4F_cctx* cctx); 135</b><p> The first thing to do is to create a compressionContext object, which will be used in all compression operations. 136 This is achieved using LZ4F_createCompressionContext(), which takes as argument a version. 137 The version provided MUST be LZ4F_VERSION. It is intended to track potential version mismatch, notably when using DLL. 138 The function will provide a pointer to a fully allocated LZ4F_cctx object. 139 If @return != zero, there was an error during context creation. 140 Object can release its memory using LZ4F_freeCompressionContext(); 141 142</p></pre><BR> 143 144<a name="Chapter8"></a><h2>Compression</h2><pre></pre> 145 146<pre><b>size_t LZ4F_compressBegin(LZ4F_cctx* cctx, 147 void* dstBuffer, size_t dstCapacity, 148 const LZ4F_preferences_t* prefsPtr); 149</b><p> will write the frame header into dstBuffer. 150 dstCapacity must be >= LZ4F_HEADER_SIZE_MAX bytes. 151 `prefsPtr` is optional : you can provide NULL as argument, all preferences will then be set to default. 152 @return : number of bytes written into dstBuffer for the header 153 or an error code (which can be tested using LZ4F_isError()) 154 155</p></pre><BR> 156 157<pre><b>size_t LZ4F_compressBound(size_t srcSize, const LZ4F_preferences_t* prefsPtr); 158</b><p> Provides minimum dstCapacity required to guarantee compression success 159 given a srcSize and preferences, covering worst case scenario. 160 prefsPtr is optional : when NULL is provided, preferences will be set to cover worst case scenario. 161 Estimation is valid for either LZ4F_compressUpdate(), LZ4F_flush() or LZ4F_compressEnd(), 162 Estimation includes the possibility that internal buffer might already be filled by up to (blockSize-1) bytes. 163 It also includes frame footer (ending + checksum), which would have to be generated by LZ4F_compressEnd(). 164 Estimation doesn't include frame header, as it was already generated by LZ4F_compressBegin(). 165 Result is always the same for a srcSize and prefsPtr, so it can be trusted to size reusable buffers. 166 When srcSize==0, LZ4F_compressBound() provides an upper bound for LZ4F_flush() and LZ4F_compressEnd() operations. 167 168</p></pre><BR> 169 170<pre><b>size_t LZ4F_compressUpdate(LZ4F_cctx* cctx, 171 void* dstBuffer, size_t dstCapacity, 172 const void* srcBuffer, size_t srcSize, 173 const LZ4F_compressOptions_t* cOptPtr); 174</b><p> LZ4F_compressUpdate() can be called repetitively to compress as much data as necessary. 175 Important rule: dstCapacity MUST be large enough to ensure operation success even in worst case situations. 176 This value is provided by LZ4F_compressBound(). 177 If this condition is not respected, LZ4F_compress() will fail (result is an errorCode). 178 LZ4F_compressUpdate() doesn't guarantee error recovery. 179 When an error occurs, compression context must be freed or resized. 180 `cOptPtr` is optional : NULL can be provided, in which case all options are set to default. 181 @return : number of bytes written into `dstBuffer` (it can be zero, meaning input data was just buffered). 182 or an error code if it fails (which can be tested using LZ4F_isError()) 183 184</p></pre><BR> 185 186<pre><b>size_t LZ4F_flush(LZ4F_cctx* cctx, 187 void* dstBuffer, size_t dstCapacity, 188 const LZ4F_compressOptions_t* cOptPtr); 189</b><p> When data must be generated and sent immediately, without waiting for a block to be completely filled, 190 it's possible to call LZ4_flush(). It will immediately compress any data buffered within cctx. 191 `dstCapacity` must be large enough to ensure the operation will be successful. 192 `cOptPtr` is optional : it's possible to provide NULL, all options will be set to default. 193 @return : nb of bytes written into dstBuffer (can be zero, when there is no data stored within cctx) 194 or an error code if it fails (which can be tested using LZ4F_isError()) 195 196</p></pre><BR> 197 198<pre><b>size_t LZ4F_compressEnd(LZ4F_cctx* cctx, 199 void* dstBuffer, size_t dstCapacity, 200 const LZ4F_compressOptions_t* cOptPtr); 201</b><p> To properly finish an LZ4 frame, invoke LZ4F_compressEnd(). 202 It will flush whatever data remained within `cctx` (like LZ4_flush()) 203 and properly finalize the frame, with an endMark and a checksum. 204 `cOptPtr` is optional : NULL can be provided, in which case all options will be set to default. 205 @return : nb of bytes written into dstBuffer, necessarily >= 4 (endMark), 206 or an error code if it fails (which can be tested using LZ4F_isError()) 207 A successful call to LZ4F_compressEnd() makes `cctx` available again for another compression task. 208 209</p></pre><BR> 210 211<a name="Chapter9"></a><h2>Decompression functions</h2><pre></pre> 212 213<pre><b>typedef struct { 214 unsigned stableDst; </b>/* pledges that last 64KB decompressed data will remain available unmodified. This optimization skips storage operations in tmp buffers. */<b> 215 unsigned reserved[3]; </b>/* must be set to zero for forward compatibility */<b> 216} LZ4F_decompressOptions_t; 217</b></pre><BR> 218<pre><b>LZ4F_errorCode_t LZ4F_createDecompressionContext(LZ4F_dctx** dctxPtr, unsigned version); 219LZ4F_errorCode_t LZ4F_freeDecompressionContext(LZ4F_dctx* dctx); 220</b><p> Create an LZ4F_dctx object, to track all decompression operations. 221 The version provided MUST be LZ4F_VERSION. 222 The function provides a pointer to an allocated and initialized LZ4F_dctx object. 223 The result is an errorCode, which can be tested using LZ4F_isError(). 224 dctx memory can be released using LZ4F_freeDecompressionContext(); 225 Result of LZ4F_freeDecompressionContext() indicates current state of decompressionContext when being released. 226 That is, it should be == 0 if decompression has been completed fully and correctly. 227 228</p></pre><BR> 229 230<a name="Chapter10"></a><h2>Streaming decompression functions</h2><pre></pre> 231 232<pre><b>size_t LZ4F_getFrameInfo(LZ4F_dctx* dctx, 233 LZ4F_frameInfo_t* frameInfoPtr, 234 const void* srcBuffer, size_t* srcSizePtr); 235</b><p> This function extracts frame parameters (max blockSize, dictID, etc.). 236 Its usage is optional. 237 Extracted information is typically useful for allocation and dictionary. 238 This function works in 2 situations : 239 - At the beginning of a new frame, in which case 240 it will decode information from `srcBuffer`, starting the decoding process. 241 Input size must be large enough to successfully decode the entire frame header. 242 Frame header size is variable, but is guaranteed to be <= LZ4F_HEADER_SIZE_MAX bytes. 243 It's allowed to provide more input data than this minimum. 244 - After decoding has been started. 245 In which case, no input is read, frame parameters are extracted from dctx. 246 - If decoding has barely started, but not yet extracted information from header, 247 LZ4F_getFrameInfo() will fail. 248 The number of bytes consumed from srcBuffer will be updated within *srcSizePtr (necessarily <= original value). 249 Decompression must resume from (srcBuffer + *srcSizePtr). 250 @return : an hint about how many srcSize bytes LZ4F_decompress() expects for next call, 251 or an error code which can be tested using LZ4F_isError(). 252 note 1 : in case of error, dctx is not modified. Decoding operation can resume from beginning safely. 253 note 2 : frame parameters are *copied into* an already allocated LZ4F_frameInfo_t structure. 254 255</p></pre><BR> 256 257<pre><b>size_t LZ4F_decompress(LZ4F_dctx* dctx, 258 void* dstBuffer, size_t* dstSizePtr, 259 const void* srcBuffer, size_t* srcSizePtr, 260 const LZ4F_decompressOptions_t* dOptPtr); 261</b><p> Call this function repetitively to regenerate compressed data from `srcBuffer`. 262 The function will read up to *srcSizePtr bytes from srcBuffer, 263 and decompress data into dstBuffer, of capacity *dstSizePtr. 264 265 The nb of bytes consumed from srcBuffer will be written into *srcSizePtr (necessarily <= original value). 266 The nb of bytes decompressed into dstBuffer will be written into *dstSizePtr (necessarily <= original value). 267 268 The function does not necessarily read all input bytes, so always check value in *srcSizePtr. 269 Unconsumed source data must be presented again in subsequent invocations. 270 271 `dstBuffer` can freely change between each consecutive function invocation. 272 `dstBuffer` content will be overwritten. 273 274 @return : an hint of how many `srcSize` bytes LZ4F_decompress() expects for next call. 275 Schematically, it's the size of the current (or remaining) compressed block + header of next block. 276 Respecting the hint provides some small speed benefit, because it skips intermediate buffers. 277 This is just a hint though, it's always possible to provide any srcSize. 278 279 When a frame is fully decoded, @return will be 0 (no more data expected). 280 When provided with more bytes than necessary to decode a frame, 281 LZ4F_decompress() will stop reading exactly at end of current frame, and @return 0. 282 283 If decompression failed, @return is an error code, which can be tested using LZ4F_isError(). 284 After a decompression error, the `dctx` context is not resumable. 285 Use LZ4F_resetDecompressionContext() to return to clean state. 286 287 After a frame is fully decoded, dctx can be used again to decompress another frame. 288 289</p></pre><BR> 290 291<pre><b>void LZ4F_resetDecompressionContext(LZ4F_dctx* dctx); </b>/* always successful */<b> 292</b><p> In case of an error, the context is left in "undefined" state. 293 In which case, it's necessary to reset it, before re-using it. 294 This method can also be used to abruptly stop any unfinished decompression, 295 and start a new one using same context resources. 296</p></pre><BR> 297 298<pre><b>typedef enum { LZ4F_LIST_ERRORS(LZ4F_GENERATE_ENUM) } LZ4F_errorCodes; 299</b></pre><BR> 300<a name="Chapter11"></a><h2>Bulk processing dictionary API</h2><pre></pre> 301 302<pre><b>LZ4FLIB_STATIC_API LZ4F_CDict* LZ4F_createCDict(const void* dictBuffer, size_t dictSize); 303LZ4FLIB_STATIC_API void LZ4F_freeCDict(LZ4F_CDict* CDict); 304</b><p> When compressing multiple messages / blocks with the same dictionary, it's recommended to load it just once. 305 LZ4_createCDict() will create a digested dictionary, ready to start future compression operations without startup delay. 306 LZ4_CDict can be created once and shared by multiple threads concurrently, since its usage is read-only. 307 `dictBuffer` can be released after LZ4_CDict creation, since its content is copied within CDict 308</p></pre><BR> 309 310<pre><b>LZ4FLIB_STATIC_API size_t LZ4F_compressFrame_usingCDict( 311 LZ4F_cctx* cctx, 312 void* dst, size_t dstCapacity, 313 const void* src, size_t srcSize, 314 const LZ4F_CDict* cdict, 315 const LZ4F_preferences_t* preferencesPtr); 316</b><p> Compress an entire srcBuffer into a valid LZ4 frame using a digested Dictionary. 317 cctx must point to a context created by LZ4F_createCompressionContext(). 318 If cdict==NULL, compress without a dictionary. 319 dstBuffer MUST be >= LZ4F_compressFrameBound(srcSize, preferencesPtr). 320 If this condition is not respected, function will fail (@return an errorCode). 321 The LZ4F_preferences_t structure is optional : you may provide NULL as argument, 322 but it's not recommended, as it's the only way to provide dictID in the frame header. 323 @return : number of bytes written into dstBuffer. 324 or an error code if it fails (can be tested using LZ4F_isError()) 325</p></pre><BR> 326 327<pre><b>LZ4FLIB_STATIC_API size_t LZ4F_compressBegin_usingCDict( 328 LZ4F_cctx* cctx, 329 void* dstBuffer, size_t dstCapacity, 330 const LZ4F_CDict* cdict, 331 const LZ4F_preferences_t* prefsPtr); 332</b><p> Inits streaming dictionary compression, and writes the frame header into dstBuffer. 333 dstCapacity must be >= LZ4F_HEADER_SIZE_MAX bytes. 334 `prefsPtr` is optional : you may provide NULL as argument, 335 however, it's the only way to provide dictID in the frame header. 336 @return : number of bytes written into dstBuffer for the header, 337 or an error code (which can be tested using LZ4F_isError()) 338</p></pre><BR> 339 340<pre><b>LZ4FLIB_STATIC_API size_t LZ4F_decompress_usingDict( 341 LZ4F_dctx* dctxPtr, 342 void* dstBuffer, size_t* dstSizePtr, 343 const void* srcBuffer, size_t* srcSizePtr, 344 const void* dict, size_t dictSize, 345 const LZ4F_decompressOptions_t* decompressOptionsPtr); 346</b><p> Same as LZ4F_decompress(), using a predefined dictionary. 347 Dictionary is used "in place", without any preprocessing. 348 It must remain accessible throughout the entire frame decoding. 349</p></pre><BR> 350 351</html> 352</body> 353