include/linux/zstd_lib.h

135  *  NOTE: Providing `dstCapacity >= ZSTD_compressBound(srcSize)` guarantees that zstd will have
165  *  note 1 : a 0 return value means the frame is valid but "empty".
167 …*  note 2 : decompressed size is an optional field, it may not be present (typically in streaming …
173 …*  note 3 : decompressed size is always present when compression is completed using single-pass fu…
175  *  note 4 : decompressed size can be very large (64-bits value),
178  *  note 5 : If source is untrusted, decompressed size could be wrong or intentionally modified.
181  *  note 6 : This function replaces ZSTD_getDecompressedSize() */
201  *  Note 1: this method is called _find*() because it's not enough to read the header,
203  *  Note 2: this method also works with Skippable Frames. In which case,
217  * Note : ZSTD_compressBound() itself can fail, if @srcSize >= ZSTD_MAX_INPUT_SIZE .
254  *  Note : re-using context is just a speed / resource optimization.
256  *  Note 2: For parallel execution in multi-threaded environments,
324                /* note : new strategies _might_ be added in the future.
331      * Note: When compressing with a ZSTD_CDict these parameters are superseded
335                               * Note that exact compression parameters are dynamically determined,
339                               * Note 1 : it's possible to pass a negative compression level.
340 …             * Note 2 : setting a level does not automatically set all other compression parameters
353                               * Note: Using a windowLog greater than ZSTD_WINDOWLOG_LIMIT_DEFAULT
374                               * Note that Zstandard can still find matches of smaller size,
378 …                         * Note that currently, for all strategies < btopt, effective minimum is 4.
397 …                           * Note that it's not a guarantee, just a convergence target (default:0).
401                                   * Note: this parameter is stable since v1.5.6.
411 …                       * Note: enabling this parameter increases default ZSTD_c_windowLog to 128 MB
413 …                               * Note: will be enabled by default if ZSTD_c_windowLog >= 128 MB and
454 …* (note : a strong exception to this rule is when first invocation of ZSTD_compressStream2() sets …
477     /* note : additional experimental parameters are also available
498      * note : never ever use experimentalParam? names directly;
556  *  Note 1 : pledgedSrcSize==0 actually means zero, aka an empty frame.
559  *  Note 2 : pledgedSrcSize is only valid once, for the next frame.
561  *  Note 3 : Whenever all input data is provided and consumed in a single round,
592  *  (note that this entry point doesn't even expose a compression level parameter).
597  *  NOTE: Providing `dstCapacity >= ZSTD_compressBound(srcSize)` guarantees that zstd will have
615  * Note : This API is compatible with existing ZSTD_decompressDCtx() and ZSTD_decompressStream().
628     /* note : additional experimental parameters are also available
638      * note : never ever use experimentalParam? names directly
704 *  note : since v1.3.0, ZSTD_CStream and ZSTD_CCtx are the same thing.
716 *  Note that the function may not consume the entire input, for example, because
721 *  note: ZSTD_e_continue is guaranteed to make some forward progress when called,
731 *  Note that, if `output->size` is too small, a single invocation with ZSTD_e_flush might not be en…
735 *  note: ZSTD_e_flush will flush as much output as possible, meaning when compressing with multiple…
747 *  note: ZSTD_e_end will flush as much output as possible, meaning when compressing with multiple t…
767 …              * note : multithreaded compression will block to flush as much output as possible. */
769 …       * note that frame is only closed after compressed data is fully flushed (return value == 0).
771 …           * note : each frame is independent (does not reference any content from previous frame).
772 …              : note : multithreaded compression will block to flush as much output as possible. */
796  *  - note: if an operation ends with an error, it may leave @cctx in an undefined state.
813  * However, note that these recommendations are from the perspective of a C caller program.
838  * Note that ZSTD_initCStream() clears any previously set dictionary. Use the new API
844  * NOTE: The return value is different. ZSTD_compressStream() returns a hint for
879 *  Note : with no additional input provided, amount of data flushed is necessarily <= ZSTD_BLOCKSIZ…
899  * Note : This function is redundant with the advanced API and equivalent to:
915  * Note : with no additional input, amount of data flushed <= ZSTD_BLOCKSIZE_MAX.
921 …* Note: when an operation returns with an error code, the @zds state may be left in undefined stat…
940  *  Note : This function loads the dictionary, resulting in significant startup delay.
942  *  Note 2 : When `dict == NULL || dictSize < 8` no dictionary is used. */
952  *  Note : This function loads the dictionary, resulting in significant startup delay.
954  *  Note : When `dict == NULL || dictSize < 8` no dictionary is used. */
973 …*  Note 1 : Consider experimental function `ZSTD_createCDict_byReference()` if you prefer to not d…
974  *  Note 2 : A ZSTD_CDict can be created from an empty @dictBuffer,
989  *  Note : compression level is _decided at dictionary creation time_,
1046  *    Note : this use case also happens when using a non-conformant dictionary.
1071  *  Note 1 : Dictionary is sticky, it will be used for all future compressed frames,
1074  *  Note 2 : Loading a dictionary involves building tables.
1078  *  Note 3 :`dict` content will be copied internally.
1081  *  Note 4 : Use ZSTD_CCtx_loadDictionary_advanced()
1083  *  Note 5 : This method does not benefit from LDM (long distance mode).
1091  *  Note that compression parameters are enforced from within CDict,
1098  *  Note 1 : Currently, only one dictionary can be managed.
1100  *  Note 2 : CDict is just referenced, its lifetime must outlive its usage within CCtx. */
1112  *  Note 1 : Prefix buffer is referenced. It **must** outlive compression.
1114  *  Note 2 : If the intention is to diff some large src data blob with some prior version of itself,
1117 …*  Note 3 : Referencing a prefix involves building tables, which are dependent on compression para…
1120  *  Note 4 : By default, the prefix is interpreted as raw content (ZSTD_dct_rawContent).
1132  *  Note 1 : Loading a dictionary involves building tables,
1135  *  Note 2 :`dict` content will be copied internally, so `dict` can be released after loading.
1137  *  Note 3 : Use ZSTD_DCtx_loadDictionary_advanced() to take control of
1157  *  Note 2 : DDict is just referenced, its lifetime must outlive its usage from DCtx.
1168  *  Note 1 : Adding any prefix (including NULL) invalidates any previously set prefix or dictionary
1169  *  Note 2 : Prefix buffer is referenced. It **must** outlive decompression.
1172  *  Note 3 : By default, the prefix is treated as raw content (ZSTD_dct_rawContent).
1174  *  Note 4 : Referencing a raw content prefix has almost no cpu nor memory cost.
1184  *  Note that object memory usage can evolve (increase or decrease) over time. */
1245 #define ZSTD_TARGETLENGTH_MIN     0   /* note : comparing this constant to an unsigned results in a…
1291 …    /* Note: Users of this API may provide a sequence with matchLength == litLength == offset == 0.
1312 …               * Note: This field is optional. ZSTD_generateSequences() will calculate the value of
1359     /* Note: this enum controls ZSTD_d_forceIgnoreChecksum */
1365     /* Note: this enum controls ZSTD_d_refMultipleDDicts */
1371     /* Note: this enum and the behavior it controls are effectively internal
1419   /* Note: This enum controls features which are conditionally beneficial.
1441 …*   note 1 : decompressed size is an optional field, that may not be present, especially in stream…
1444  *   note 2 : decompressed size is always present when compression is done with ZSTD_compress()
1445  *   note 3 : decompressed size can be very large (64-bits value),
1448  *   note 4 : If source is untrusted, decompressed size could be wrong or intentionally modified.
1451 …*   note 5 : ZSTD_findDecompressedSize handles multiple frames, and so it must traverse the input …
1463  *  note 1  : an error can occur if `src` contains an invalid or incorrectly formatted frame.
1464 …*  note 2  : the upper-bound is exact when the decompressed size field is available in every ZSTD …
1466 …*  note 3  : when the decompressed size field isn't available, the upper-bound for that frame is c…
1517  * NOTE: See also ZSTD_DECOMPRESSION_MARGIN().
1518  * NOTE: This applies only to single-pass decompression through ZSTD_decompress() or
1520  * NOTE: This function supports multi-frame input.
1559  *  note : returns number of sequences - to get bytes, multiply by sizeof(ZSTD_Sequence).
1641 …* Note: Repcodes are, as of now, always re-calculated within this function, ZSTD_Sequence.rep is e…
1642 …* Dev Note: Once ability to ingest repcodes become available, the explicit block delims mode must …
1734  *  Note that the size estimation is specific for one-shot compression,
1746  *  Note : only single-threaded compression is supported.
1761  *  Note : CStream size estimation is only correct for single-threaded compression.
1763 …*  Note 2 : ZSTD_estimateCStreamSize* functions are not compatible with the Block-Level Sequence P…
1770  *  Note : if streaming is init with function ZSTD_init?Stream_usingDict(),
1783  *  Note : dictionaries created by reference (`ZSTD_dlm_byRef`) are logically smaller.
1798  *  Note : zstd will never resize nor malloc() when using a static buffer.
1801  *  Note 2 : there is no corresponding "free" function.
1803  *  Note 3 : cParams : use ZSTD_getCParams() to convert a compression level
1866  *  Note that the lifetime of such pool must exist while being used.
1903  *  note: equivalent to ZSTD_createCDict_advanced(), with dictLoadMethod==ZSTD_dlm_byRef */
1931  *  Note : if modifying parameters during compression (MT mode only),
1932  *         note that changes to the .windowLog parameter will be ignored.
1951  *  Note : this function is now DEPRECATED.
1963  *  Note : this function is now DEPRECATED.
2003   * NOTE 1: rsyncable mode only works when multithreading is enabled.
2004   * NOTE 2: rsyncable performs poorly in combination with long range mode,
2007   * NOTE 3: Rsyncable mode limits maximum compression speed to ~400 MB/s.
2031  * Set to ZSTD_ps_enable to always compress literals. (Note: uncompressed literals
2080  * Note that some of the members of the ZSTD_compressionParameters struct have
2092  * Note that this means that the CDict tables can no longer be copied into the
2123  * NOTE: So long as the ZSTD_inBuffer always points to valid memory, using
2184  * note: this parameter only influences the first splitter stage,
2188  *       Note that both can be combined.
2194  * Note that currently the first block is never split,
2226  * Note that this only pertains to compression strategies: greedy, lazy, and lazy2
2266  * Note: for this parameter, ZSTD_ps_auto is currently equivalent to ZSTD_ps_disable,
2308  * the "rep" field. Note that this is the only way to exploit repcode matches
2415  *  Note : Frame Identifier is 4 bytes. If `size < 4`, @return will always be 0.
2416  *  Note 2 : Legacy Frame Identifiers are considered valid only if Legacy Support is enabled.
2417  *  Note 3 : Skippable Frame Identifiers are considered valid. */
2487  * NOTE: So long as the ZSTD_outBuffer always points to valid memory, using
2600  * ZSTD_CONTENTSIZE_UNKNOWN. Note that, for compatibility with older programs,
2618  * Note: dict is loaded with ZSTD_dct_auto (treated as a full zstd dictionary if
2652  * note : cdict will just be referenced, and must outlive compression session
2682  * Note: ZSTD_resetCStream() interprets pledgedSrcSize == 0 as ZSTD_CONTENTSIZE_UNKNOWN, but
2688  *  Note that zcs must be init at least once before using ZSTD_resetCStream().
2713  * Note : (ingested - consumed) is amount of input data buffered internally, not yet compressed.
2742  * note: no dictionary will be used if dict == NULL or dictSize < 8
2753  * note : ddict is referenced, it must outlive decompression session
2813  *     tradeoff. Note: the compression level does not reflect zstd parameters set
2817  *     sequences. Note that sequence offsets are sometimes allowed to exceed the
2841  * hold) if the ZSTD_c_validateSequences cParam is enabled. Note that sequence
2868  *   - Note that ZSTD_c_enableLongDistanceMatching is auto-enabled by default in some
2996 …D_compressBegin_usingCDict(ZSTD_CCtx* cctx, const ZSTD_CDict* cdict); /*< note: fails if cdict==NU…
3000 …, const ZSTD_CCtx* preparedCCtx, unsigned long long pledgedSrcSize); /*<  note: if pledgedSrcSize …
3031 …Note that these values could be wrong, either because of data corruption, or because a 3rd party d…
3050   Note that already decoded data stored in the buffer should be flushed before being overwritten.
3072 …Note : it's possible to know if next input to present is a header or a block, using ZSTD_nextInput…