1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> 4<title>1.9.3 Manual</title> 5</head> 6<body> 7<h1>1.9.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 Structure must be first init to 0, using memset() or LZ4F_INIT_FRAMEINFO, 88 setting all parameters to default. 89 It's then possible to update selectively some parameters 90</p></pre><BR> 91 92<pre><b>typedef struct { 93 LZ4F_frameInfo_t frameInfo; 94 int compressionLevel; </b>/* 0: default (fast mode); values > LZ4HC_CLEVEL_MAX count as LZ4HC_CLEVEL_MAX; values < 0 trigger "fast acceleration" */<b> 95 unsigned autoFlush; </b>/* 1: always flush; reduces usage of internal buffers */<b> 96 unsigned favorDecSpeed; </b>/* 1: parser favors decompression speed vs compression ratio. Only works for high compression modes (>= LZ4HC_CLEVEL_OPT_MIN) */ /* v1.8.2+ */<b> 97 unsigned reserved[3]; </b>/* must be zero for forward compatibility */<b> 98} LZ4F_preferences_t; 99</b><p> makes it possible to supply advanced compression instructions to streaming interface. 100 Structure must be first init to 0, using memset() or LZ4F_INIT_PREFERENCES, 101 setting all parameters to default. 102 All reserved fields must be set to zero. 103</p></pre><BR> 104 105<a name="Chapter5"></a><h2>Simple compression function</h2><pre></pre> 106 107<pre><b>size_t LZ4F_compressFrameBound(size_t srcSize, const LZ4F_preferences_t* preferencesPtr); 108</b><p> Returns the maximum possible compressed size with LZ4F_compressFrame() given srcSize and preferences. 109 `preferencesPtr` is optional. It can be replaced by NULL, in which case, the function will assume default preferences. 110 Note : this result is only usable with LZ4F_compressFrame(). 111 It may also be used with LZ4F_compressUpdate() _if no flush() operation_ is performed. 112 113</p></pre><BR> 114 115<pre><b>size_t LZ4F_compressFrame(void* dstBuffer, size_t dstCapacity, 116 const void* srcBuffer, size_t srcSize, 117 const LZ4F_preferences_t* preferencesPtr); 118</b><p> Compress an entire srcBuffer into a valid LZ4 frame. 119 dstCapacity MUST be >= LZ4F_compressFrameBound(srcSize, preferencesPtr). 120 The LZ4F_preferences_t structure is optional : you can provide NULL as argument. All preferences will be set to default. 121 @return : number of bytes written into dstBuffer. 122 or an error code if it fails (can be tested using LZ4F_isError()) 123 124</p></pre><BR> 125 126<a name="Chapter6"></a><h2>Advanced compression functions</h2><pre></pre> 127 128<pre><b>typedef struct { 129 unsigned stableSrc; </b>/* 1 == src content will remain present on future calls to LZ4F_compress(); skip copying src content within tmp buffer */<b> 130 unsigned reserved[3]; 131} LZ4F_compressOptions_t; 132</b></pre><BR> 133<a name="Chapter7"></a><h2>Resource Management</h2><pre></pre> 134 135<pre><b>LZ4F_errorCode_t LZ4F_createCompressionContext(LZ4F_cctx** cctxPtr, unsigned version); 136LZ4F_errorCode_t LZ4F_freeCompressionContext(LZ4F_cctx* cctx); 137</b><p> The first thing to do is to create a compressionContext object, which will be used in all compression operations. 138 This is achieved using LZ4F_createCompressionContext(), which takes as argument a version. 139 The version provided MUST be LZ4F_VERSION. It is intended to track potential version mismatch, notably when using DLL. 140 The function will provide a pointer to a fully allocated LZ4F_cctx object. 141 If @return != zero, there was an error during context creation. 142 Object can release its memory using LZ4F_freeCompressionContext(); 143 144</p></pre><BR> 145 146<a name="Chapter8"></a><h2>Compression</h2><pre></pre> 147 148<pre><b>size_t LZ4F_compressBegin(LZ4F_cctx* cctx, 149 void* dstBuffer, size_t dstCapacity, 150 const LZ4F_preferences_t* prefsPtr); 151</b><p> will write the frame header into dstBuffer. 152 dstCapacity must be >= LZ4F_HEADER_SIZE_MAX bytes. 153 `prefsPtr` is optional : you can provide NULL as argument, all preferences will then be set to default. 154 @return : number of bytes written into dstBuffer for the header 155 or an error code (which can be tested using LZ4F_isError()) 156 157</p></pre><BR> 158 159<pre><b>size_t LZ4F_compressBound(size_t srcSize, const LZ4F_preferences_t* prefsPtr); 160</b><p> Provides minimum dstCapacity required to guarantee success of 161 LZ4F_compressUpdate(), given a srcSize and preferences, for a worst case scenario. 162 When srcSize==0, LZ4F_compressBound() provides an upper bound for LZ4F_flush() and LZ4F_compressEnd() instead. 163 Note that the result is only valid for a single invocation of LZ4F_compressUpdate(). 164 When invoking LZ4F_compressUpdate() multiple times, 165 if the output buffer is gradually filled up instead of emptied and re-used from its start, 166 one must check if there is enough remaining capacity before each invocation, using LZ4F_compressBound(). 167 @return is always the same for a srcSize and prefsPtr. 168 prefsPtr is optional : when NULL is provided, preferences will be set to cover worst case scenario. 169 tech details : 170 @return if automatic flushing is not enabled, includes the possibility that internal buffer might already be filled by up to (blockSize-1) bytes. 171 It also includes frame footer (ending + checksum), since it might be generated by LZ4F_compressEnd(). 172 @return doesn't include frame header, as it was already generated by LZ4F_compressBegin(). 173 174</p></pre><BR> 175 176<pre><b>size_t LZ4F_compressUpdate(LZ4F_cctx* cctx, 177 void* dstBuffer, size_t dstCapacity, 178 const void* srcBuffer, size_t srcSize, 179 const LZ4F_compressOptions_t* cOptPtr); 180</b><p> LZ4F_compressUpdate() can be called repetitively to compress as much data as necessary. 181 Important rule: dstCapacity MUST be large enough to ensure operation success even in worst case situations. 182 This value is provided by LZ4F_compressBound(). 183 If this condition is not respected, LZ4F_compress() will fail (result is an errorCode). 184 LZ4F_compressUpdate() doesn't guarantee error recovery. 185 When an error occurs, compression context must be freed or resized. 186 `cOptPtr` is optional : NULL can be provided, in which case all options are set to default. 187 @return : number of bytes written into `dstBuffer` (it can be zero, meaning input data was just buffered). 188 or an error code if it fails (which can be tested using LZ4F_isError()) 189 190</p></pre><BR> 191 192<pre><b>size_t LZ4F_flush(LZ4F_cctx* cctx, 193 void* dstBuffer, size_t dstCapacity, 194 const LZ4F_compressOptions_t* cOptPtr); 195</b><p> When data must be generated and sent immediately, without waiting for a block to be completely filled, 196 it's possible to call LZ4_flush(). It will immediately compress any data buffered within cctx. 197 `dstCapacity` must be large enough to ensure the operation will be successful. 198 `cOptPtr` is optional : it's possible to provide NULL, all options will be set to default. 199 @return : nb of bytes written into dstBuffer (can be zero, when there is no data stored within cctx) 200 or an error code if it fails (which can be tested using LZ4F_isError()) 201 Note : LZ4F_flush() is guaranteed to be successful when dstCapacity >= LZ4F_compressBound(0, prefsPtr). 202 203</p></pre><BR> 204 205<pre><b>size_t LZ4F_compressEnd(LZ4F_cctx* cctx, 206 void* dstBuffer, size_t dstCapacity, 207 const LZ4F_compressOptions_t* cOptPtr); 208</b><p> To properly finish an LZ4 frame, invoke LZ4F_compressEnd(). 209 It will flush whatever data remained within `cctx` (like LZ4_flush()) 210 and properly finalize the frame, with an endMark and a checksum. 211 `cOptPtr` is optional : NULL can be provided, in which case all options will be set to default. 212 @return : nb of bytes written into dstBuffer, necessarily >= 4 (endMark), 213 or an error code if it fails (which can be tested using LZ4F_isError()) 214 Note : LZ4F_compressEnd() is guaranteed to be successful when dstCapacity >= LZ4F_compressBound(0, prefsPtr). 215 A successful call to LZ4F_compressEnd() makes `cctx` available again for another compression task. 216 217</p></pre><BR> 218 219<a name="Chapter9"></a><h2>Decompression functions</h2><pre></pre> 220 221<pre><b>typedef struct { 222 unsigned stableDst; </b>/* pledges that last 64KB decompressed data will remain available unmodified. This optimization skips storage operations in tmp buffers. */<b> 223 unsigned reserved[3]; </b>/* must be set to zero for forward compatibility */<b> 224} LZ4F_decompressOptions_t; 225</b></pre><BR> 226<pre><b>LZ4F_errorCode_t LZ4F_createDecompressionContext(LZ4F_dctx** dctxPtr, unsigned version); 227LZ4F_errorCode_t LZ4F_freeDecompressionContext(LZ4F_dctx* dctx); 228</b><p> Create an LZ4F_dctx object, to track all decompression operations. 229 The version provided MUST be LZ4F_VERSION. 230 The function provides a pointer to an allocated and initialized LZ4F_dctx object. 231 The result is an errorCode, which can be tested using LZ4F_isError(). 232 dctx memory can be released using LZ4F_freeDecompressionContext(); 233 Result of LZ4F_freeDecompressionContext() indicates current state of decompressionContext when being released. 234 That is, it should be == 0 if decompression has been completed fully and correctly. 235 236</p></pre><BR> 237 238<a name="Chapter10"></a><h2>Streaming decompression functions</h2><pre></pre> 239 240<pre><b>size_t LZ4F_headerSize(const void* src, size_t srcSize); 241</b><p> Provide the header size of a frame starting at `src`. 242 `srcSize` must be >= LZ4F_MIN_SIZE_TO_KNOW_HEADER_LENGTH, 243 which is enough to decode the header length. 244 @return : size of frame header 245 or an error code, which can be tested using LZ4F_isError() 246 note : Frame header size is variable, but is guaranteed to be 247 >= LZ4F_HEADER_SIZE_MIN bytes, and <= LZ4F_HEADER_SIZE_MAX bytes. 248 249</p></pre><BR> 250 251<pre><b>size_t LZ4F_getFrameInfo(LZ4F_dctx* dctx, 252 LZ4F_frameInfo_t* frameInfoPtr, 253 const void* srcBuffer, size_t* srcSizePtr); 254</b><p> This function extracts frame parameters (max blockSize, dictID, etc.). 255 Its usage is optional: user can call LZ4F_decompress() directly. 256 257 Extracted information will fill an existing LZ4F_frameInfo_t structure. 258 This can be useful for allocation and dictionary identification purposes. 259 260 LZ4F_getFrameInfo() can work in the following situations : 261 262 1) At the beginning of a new frame, before any invocation of LZ4F_decompress(). 263 It will decode header from `srcBuffer`, 264 consuming the header and starting the decoding process. 265 266 Input size must be large enough to contain the full frame header. 267 Frame header size can be known beforehand by LZ4F_headerSize(). 268 Frame header size is variable, but is guaranteed to be >= LZ4F_HEADER_SIZE_MIN bytes, 269 and not more than <= LZ4F_HEADER_SIZE_MAX bytes. 270 Hence, blindly providing LZ4F_HEADER_SIZE_MAX bytes or more will always work. 271 It's allowed to provide more input data than the header size, 272 LZ4F_getFrameInfo() will only consume the header. 273 274 If input size is not large enough, 275 aka if it's smaller than header size, 276 function will fail and return an error code. 277 278 2) After decoding has been started, 279 it's possible to invoke LZ4F_getFrameInfo() anytime 280 to extract already decoded frame parameters stored within dctx. 281 282 Note that, if decoding has barely started, 283 and not yet read enough information to decode the header, 284 LZ4F_getFrameInfo() will fail. 285 286 The number of bytes consumed from srcBuffer will be updated in *srcSizePtr (necessarily <= original value). 287 LZ4F_getFrameInfo() only consumes bytes when decoding has not yet started, 288 and when decoding the header has been successful. 289 Decompression must then resume from (srcBuffer + *srcSizePtr). 290 291 @return : a hint about how many srcSize bytes LZ4F_decompress() expects for next call, 292 or an error code which can be tested using LZ4F_isError(). 293 note 1 : in case of error, dctx is not modified. Decoding operation can resume from beginning safely. 294 note 2 : frame parameters are *copied into* an already allocated LZ4F_frameInfo_t structure. 295 296</p></pre><BR> 297 298<pre><b>size_t LZ4F_decompress(LZ4F_dctx* dctx, 299 void* dstBuffer, size_t* dstSizePtr, 300 const void* srcBuffer, size_t* srcSizePtr, 301 const LZ4F_decompressOptions_t* dOptPtr); 302</b><p> Call this function repetitively to regenerate data compressed in `srcBuffer`. 303 304 The function requires a valid dctx state. 305 It will read up to *srcSizePtr bytes from srcBuffer, 306 and decompress data into dstBuffer, of capacity *dstSizePtr. 307 308 The nb of bytes consumed from srcBuffer will be written into *srcSizePtr (necessarily <= original value). 309 The nb of bytes decompressed into dstBuffer will be written into *dstSizePtr (necessarily <= original value). 310 311 The function does not necessarily read all input bytes, so always check value in *srcSizePtr. 312 Unconsumed source data must be presented again in subsequent invocations. 313 314 `dstBuffer` can freely change between each consecutive function invocation. 315 `dstBuffer` content will be overwritten. 316 317 @return : an hint of how many `srcSize` bytes LZ4F_decompress() expects for next call. 318 Schematically, it's the size of the current (or remaining) compressed block + header of next block. 319 Respecting the hint provides some small speed benefit, because it skips intermediate buffers. 320 This is just a hint though, it's always possible to provide any srcSize. 321 322 When a frame is fully decoded, @return will be 0 (no more data expected). 323 When provided with more bytes than necessary to decode a frame, 324 LZ4F_decompress() will stop reading exactly at end of current frame, and @return 0. 325 326 If decompression failed, @return is an error code, which can be tested using LZ4F_isError(). 327 After a decompression error, the `dctx` context is not resumable. 328 Use LZ4F_resetDecompressionContext() to return to clean state. 329 330 After a frame is fully decoded, dctx can be used again to decompress another frame. 331 332</p></pre><BR> 333 334<pre><b>void LZ4F_resetDecompressionContext(LZ4F_dctx* dctx); </b>/* always successful */<b> 335</b><p> In case of an error, the context is left in "undefined" state. 336 In which case, it's necessary to reset it, before re-using it. 337 This method can also be used to abruptly stop any unfinished decompression, 338 and start a new one using same context resources. 339</p></pre><BR> 340 341<pre><b>typedef enum { LZ4F_LIST_ERRORS(LZ4F_GENERATE_ENUM) 342 _LZ4F_dummy_error_enum_for_c89_never_used } LZ4F_errorCodes; 343</b></pre><BR> 344<a name="Chapter11"></a><h2>Bulk processing dictionary API</h2><pre></pre> 345 346<pre><b>LZ4FLIB_STATIC_API LZ4F_CDict* LZ4F_createCDict(const void* dictBuffer, size_t dictSize); 347LZ4FLIB_STATIC_API void LZ4F_freeCDict(LZ4F_CDict* CDict); 348</b><p> When compressing multiple messages / blocks using the same dictionary, it's recommended to load it just once. 349 LZ4_createCDict() will create a digested dictionary, ready to start future compression operations without startup delay. 350 LZ4_CDict can be created once and shared by multiple threads concurrently, since its usage is read-only. 351 `dictBuffer` can be released after LZ4_CDict creation, since its content is copied within CDict 352</p></pre><BR> 353 354<pre><b>LZ4FLIB_STATIC_API size_t LZ4F_compressFrame_usingCDict( 355 LZ4F_cctx* cctx, 356 void* dst, size_t dstCapacity, 357 const void* src, size_t srcSize, 358 const LZ4F_CDict* cdict, 359 const LZ4F_preferences_t* preferencesPtr); 360</b><p> Compress an entire srcBuffer into a valid LZ4 frame using a digested Dictionary. 361 cctx must point to a context created by LZ4F_createCompressionContext(). 362 If cdict==NULL, compress without a dictionary. 363 dstBuffer MUST be >= LZ4F_compressFrameBound(srcSize, preferencesPtr). 364 If this condition is not respected, function will fail (@return an errorCode). 365 The LZ4F_preferences_t structure is optional : you may provide NULL as argument, 366 but it's not recommended, as it's the only way to provide dictID in the frame header. 367 @return : number of bytes written into dstBuffer. 368 or an error code if it fails (can be tested using LZ4F_isError()) 369</p></pre><BR> 370 371<pre><b>LZ4FLIB_STATIC_API size_t LZ4F_compressBegin_usingCDict( 372 LZ4F_cctx* cctx, 373 void* dstBuffer, size_t dstCapacity, 374 const LZ4F_CDict* cdict, 375 const LZ4F_preferences_t* prefsPtr); 376</b><p> Inits streaming dictionary compression, and writes the frame header into dstBuffer. 377 dstCapacity must be >= LZ4F_HEADER_SIZE_MAX bytes. 378 `prefsPtr` is optional : you may provide NULL as argument, 379 however, it's the only way to provide dictID in the frame header. 380 @return : number of bytes written into dstBuffer for the header, 381 or an error code (which can be tested using LZ4F_isError()) 382</p></pre><BR> 383 384<pre><b>LZ4FLIB_STATIC_API size_t LZ4F_decompress_usingDict( 385 LZ4F_dctx* dctxPtr, 386 void* dstBuffer, size_t* dstSizePtr, 387 const void* srcBuffer, size_t* srcSizePtr, 388 const void* dict, size_t dictSize, 389 const LZ4F_decompressOptions_t* decompressOptionsPtr); 390</b><p> Same as LZ4F_decompress(), using a predefined dictionary. 391 Dictionary is used "in place", without any preprocessing. 392 It must remain accessible throughout the entire frame decoding. 393</p></pre><BR> 394 395</html> 396</body> 397