include/linux/zstd_lib.h

52   a dictionary. Dictionary compression can be performed in:
53     - a single step (described as Simple dictionary API)
54     - a single step, reusing a dictionary (described as Bulk-processing
55       dictionary API)
363 …ZSTD_c_dictIDFlag=202,   /* When applicable, dictionary's ID is written into frame header (default…
492  *                  Compression parameters and dictionary remain unchanged.
496  *                  This removes any reference to any dictionary too.
618 *  set more specific parameters, the pledged source size, or load a dictionary.
731  * Streaming in combination with advanced parameters and dictionary compression
739  *     ZSTD_CCtx_refCDict(zcs, NULL); // clear the dictionary (if any)
805 *  Simple dictionary API
808  *  Compression at an explicit compression level using a Dictionary.
809  *  A dictionary can be any arbitrary data segment (also called a prefix),
811  *  Note : This function loads the dictionary, resulting in significant startup delay.
812  *         It's intended for a dictionary used only once.
813  *  Note 2 : When `dict == NULL || dictSize < 8` no dictionary is used. */
821  *  Decompression using a known Dictionary.
822  *  Dictionary must be identical to the one used during compression.
823  *  Note : This function loads the dictionary, resulting in significant startup delay.
824  *         It's intended for a dictionary used only once.
825  *  Note : When `dict == NULL || dictSize < 8` no dictionary is used. */
833  *  Bulk processing dictionary API
838  *  When compressing multiple messages or blocks using the same dictionary,
839  *  it's recommended to digest the dictionary only once, since it's a costly operation.
840  *  ZSTD_createCDict() will create a state from digesting a dictionary.
848 …*      expecting a ZSTD_CDict parameter with any data, including those without a known dictionary.…
858  *  Compression using a digested Dictionary.
859  *  Recommended when same dictionary is used multiple times.
860  *  Note : compression level is _decided at dictionary creation time_,
871  *  Create a digested dictionary, ready to start decompression operation without startup delay.
881  *  Decompression using a digested Dictionary.
882  *  Recommended when same dictionary is used multiple times. */
890  *  Dictionary helper functions
894  *  Provides the dictID stored within dictionary.
895  *  if @return == 0, the dictionary is not conformant with Zstandard specification.
896  *  It can still be loaded, but as a content-only dictionary. */
900  *  Provides the dictID of the dictionary loaded into `cdict`.
901  *  If @return == 0, the dictionary is not conformant to Zstandard specification, or empty.
906  *  Provides the dictID of the dictionary loaded into `ddict`.
907  *  If @return == 0, the dictionary is not conformant to Zstandard specification, or empty.
915  *  - The frame does not require a dictionary to be decoded (most common case).
916 …*  - The frame was built with dictID intentionally removed. Whatever dictionary is necessary is a …
917  *    Note : this use case also happens when using a non-conformant dictionary.
925  * Advanced dictionary and prefix API (Requires v1.4.0+)
936  *  Decompression will have to use same dictionary.
938  *  Special: Loading a NULL (or 0-size) dictionary invalidates previous dictionary,
939  *           meaning "return to no-dictionary mode".
940  *  Note 1 : Dictionary is sticky, it will be used for all future compressed frames.
941  *           To return to "no-dictionary" situation, load a NULL dictionary (or reset parameters).
942  *  Note 2 : Loading a dictionary involves building tables.
945  *           compression parameters can no longer be changed after loading a dictionary.
948  *           In such a case, dictionary buffer must outlive its users.
950  *           to precisely select how dictionary content must be interpreted. */
954  *  Reference a prepared dictionary, to be used for all next compressed frames.
958  *  The ignored parameters will be used again if the CCtx is returned to no-dictionary mode.
959  *  The dictionary will remain valid for future compressed frames using same CCtx.
961  *  Special : Referencing a NULL CDict means "return to no-dictionary mode".
962  *  Note 1 : Currently, only one dictionary can be managed.
963  *           Referencing a new dictionary effectively "discards" any previous one.
968  *  Reference a prefix (single-usage dictionary) for next compressed frame.
974  *  Special: Adding any prefix (including NULL) invalidates any previous prefix or dictionary
984  *           Use experimental ZSTD_CCtx_refPrefix_advanced() to alter dictionary interpretation. */
991  *  The dictionary remains valid for all future frames, until explicitly invalidated.
993  *  Special : Adding a NULL (or 0-size) dictionary invalidates any previous dictionary,
994  *            meaning "return to no-dictionary mode".
995  *  Note 1 : Loading a dictionary involves building tables,
999  *           Use ZSTD_DCtx_loadDictionary_byReference() to reference dictionary content instead.
1001  *           how dictionary content is loaded and interpreted.
1006  *  Reference a prepared dictionary, to be used to decompress next frames.
1007  *  The dictionary remains active for decompression of future frames using same DCtx.
1016  *  Note 1 : Currently, only one dictionary can be managed.
1017  *           Referencing a new dictionary effectively "discards" any previous one.
1018  *  Special: referencing a NULL DDict means "return to no-dictionary mode".
1024  *  Reference a prefix (single-usage dictionary) to decompress next frame.
1030  *  Note 1 : Adding any prefix (including NULL) invalidates any previously set prefix or dictionary
1037  *           A full dictionary is more costly, as it requires building tables.
1209 … 1: no dictID will be saved into frame header (dictID is only useful for dictionary compression) */
1218 …ZSTD_dct_auto = 0,       /* dictionary is "full" when starting with ZSTD_MAGIC_DICTIONARY, otherwi…
1219 …ZSTD_dct_rawContent = 1, /* ensures dictionary is always loaded as rawContent, even if it starts w…
1220 …ZSTD_dct_fullDict = 2    /* refuses to load a dictionary if it does not respect Zstandard's specif…
1224     ZSTD_dlm_byCopy = 0,  /*< Copy dictionary content internally */
1225 …ZSTD_dlm_byRef = 1    /*< Reference dictionary content -- the dictionary buffer must outlive its u…
1256      *   means that the compression can search both the dictionary and input
1270      *   context alone to reload the dictionary and use params based on the source
1272      *   This method is effective when the dictionary sizes are very small relative
1281     ZSTD_dictForceAttach   = 1, /* Never copy the dictionary. */
1282     ZSTD_dictForceCopy     = 2, /* Always copy the dictionary. */
1283     ZSTD_dictForceLoad     = 3  /* Always reload the dictionary */
1392 …* If a dictionary is included, then the cctx should reference the dict. (see: ZSTD_CCtx_refCDict()…
1411 …*      is larger than what the spec allows for a given window log and dictionary (if present). See…
1536  *  Limitation 1 : currently not compatible with internal dictionary creation, triggered by
1622  *  Create a digested dictionary for compression
1623  *  Dictionary content is just referenced, not duplicated.
1647  * `dictSize` must be `0` when there is no dictionary.
1676 …*  Same as ZSTD_CCtx_loadDictionary(), but dictionary content is referenced, instead of being copi…
1682  *  how to load the dictionary (by copy ? by reference ?)
1719  * even when referencing into Dictionary content (default:0) */
1751 /* Controls whether the new and experimental "dedicated dictionary search
1763  * However, when a dictionary buffer is passed into a CCtx, such as via
1770  * would be stored in a CCtx after compressing the contents of a dictionary.
1771  * To an approximation, a compression using a dictionary can then use those
1773  * compression where the simulated compression of the dictionary left off.
1781  * structure for the dictionary that is read-optimized.
1799  * usable. The dictionary can only be attached or reloaded.
1922  * If you really care about determinism when using a dictionary or prefix,
1924  * at a speed penalty of about ~2.5% if the dictionary and data happened to be
1926  * intentionally making the dictionary and data contiguous will be worth the
2028  *  Create a digested dictionary, ready to start decompression operation without startup delay.
2029  *  Dictionary content is referenced, and therefore stays in dictBuffer.
2044  *  how to load the dictionary (by copy ? by reference ?)
2174  *     ZSTD_CCtx_refCDict(zcs, NULL); // clear the dictionary (if any)
2196  * Note: dict is loaded with ZSTD_dct_auto (treated as a full zstd dictionary if
2267  *  This is typically useful to skip dictionary loading stage, since it will re-use it in-place.
2321  * note: no dictionary will be used if dict == NULL or dictSize < 8
2342  * re-use decompression parameters from previous init; saves dictionary loading
2364   Use ZSTD_compressBegin(), or ZSTD_compressBegin_usingDict() for dictionary compression.
2416   such as the dictionary ID, content size, or maximum back-reference distance (`windowSize`).
2445 …If decompression requires a dictionary, use ZSTD_decompressBegin_usingDict() or ZSTD_decompressBeg…
2525       + compression : any ZSTD_compressBegin*() variant, including with dictionary
2526       + decompression : any ZSTD_decompressBegin*() variant, including with dictionary