123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512 |
- /*********************************************************************
- Blosc - Blocked Shuffling and Compression Library
- Author: Francesc Alted <francesc@blosc.org>
- See LICENSES/BLOSC.txt for details about copyright and rights to use.
- **********************************************************************/
- #ifndef BLOSC_H
- #define BLOSC_H
- #include <limits.h>
- #include <stdlib.h>
- #include "blosc-export.h"
- #ifdef __cplusplus
- extern "C" {
- #endif
- /* Version numbers */
- #define BLOSC_VERSION_MAJOR 1 /* for major interface/format changes */
- #define BLOSC_VERSION_MINOR 14 /* for minor interface/format changes */
- #define BLOSC_VERSION_RELEASE 3 /* for tweaks, bug-fixes, or development */
- #define BLOSC_VERSION_STRING "1.14.3" /* string version. Sync with above! */
- #define BLOSC_VERSION_REVISION "$Rev$" /* revision version */
- #define BLOSC_VERSION_DATE "$Date:: 2018-04-06 #$" /* date version */
- #define BLOSCLZ_VERSION_STRING "1.1.0" /* the internal compressor version */
- /* The *_FORMAT symbols should be just 1-byte long */
- #define BLOSC_VERSION_FORMAT 2 /* Blosc format version, starting at 1 */
- /* Minimum header length */
- #define BLOSC_MIN_HEADER_LENGTH 16
- /* The maximum overhead during compression in bytes. This equals to
- BLOSC_MIN_HEADER_LENGTH now, but can be higher in future
- implementations */
- #define BLOSC_MAX_OVERHEAD BLOSC_MIN_HEADER_LENGTH
- /* Maximum source buffer size to be compressed */
- #define BLOSC_MAX_BUFFERSIZE (INT_MAX - BLOSC_MAX_OVERHEAD)
- /* Maximum typesize before considering source buffer as a stream of bytes */
- #define BLOSC_MAX_TYPESIZE 255 /* Cannot be larger than 255 */
- /* The maximum number of threads (for some static arrays) */
- #define BLOSC_MAX_THREADS 256
- /* Codes for shuffling (see blosc_compress) */
- #define BLOSC_NOSHUFFLE 0 /* no shuffle */
- #define BLOSC_SHUFFLE 1 /* byte-wise shuffle */
- #define BLOSC_BITSHUFFLE 2 /* bit-wise shuffle */
- /* Codes for internal flags (see blosc_cbuffer_metainfo) */
- #define BLOSC_DOSHUFFLE 0x1 /* byte-wise shuffle */
- #define BLOSC_MEMCPYED 0x2 /* plain copy */
- #define BLOSC_DOBITSHUFFLE 0x4 /* bit-wise shuffle */
- /* Codes for the different compressors shipped with Blosc */
- #define BLOSC_BLOSCLZ 0
- #define BLOSC_LZ4 1
- #define BLOSC_LZ4HC 2
- #define BLOSC_SNAPPY 3
- #define BLOSC_ZLIB 4
- #define BLOSC_ZSTD 5
- /* Names for the different compressors shipped with Blosc */
- #define BLOSC_BLOSCLZ_COMPNAME "blosclz"
- #define BLOSC_LZ4_COMPNAME "lz4"
- #define BLOSC_LZ4HC_COMPNAME "lz4hc"
- #define BLOSC_SNAPPY_COMPNAME "snappy"
- #define BLOSC_ZLIB_COMPNAME "zlib"
- #define BLOSC_ZSTD_COMPNAME "zstd"
- /* Codes for compression libraries shipped with Blosc (code must be < 8) */
- #define BLOSC_BLOSCLZ_LIB 0
- #define BLOSC_LZ4_LIB 1
- #define BLOSC_SNAPPY_LIB 2
- #define BLOSC_ZLIB_LIB 3
- #define BLOSC_ZSTD_LIB 4
- /* Names for the different compression libraries shipped with Blosc */
- #define BLOSC_BLOSCLZ_LIBNAME "BloscLZ"
- #define BLOSC_LZ4_LIBNAME "LZ4"
- #define BLOSC_SNAPPY_LIBNAME "Snappy"
- #define BLOSC_ZLIB_LIBNAME "Zlib"
- #define BLOSC_ZSTD_LIBNAME "Zstd"
- /* The codes for compressor formats shipped with Blosc */
- #define BLOSC_BLOSCLZ_FORMAT BLOSC_BLOSCLZ_LIB
- #define BLOSC_LZ4_FORMAT BLOSC_LZ4_LIB
- #define BLOSC_LZ4HC_FORMAT BLOSC_LZ4_LIB /* LZ4HC and LZ4 share the same format */
- #define BLOSC_SNAPPY_FORMAT BLOSC_SNAPPY_LIB
- #define BLOSC_ZLIB_FORMAT BLOSC_ZLIB_LIB
- #define BLOSC_ZSTD_FORMAT BLOSC_ZSTD_LIB
- /* The version formats for compressors shipped with Blosc */
- /* All versions here starts at 1 */
- #define BLOSC_BLOSCLZ_VERSION_FORMAT 1
- #define BLOSC_LZ4_VERSION_FORMAT 1
- #define BLOSC_LZ4HC_VERSION_FORMAT 1 /* LZ4HC and LZ4 share the same format */
- #define BLOSC_SNAPPY_VERSION_FORMAT 1
- #define BLOSC_ZLIB_VERSION_FORMAT 1
- #define BLOSC_ZSTD_VERSION_FORMAT 1
- /* Split mode for blocks. NEVER and ALWAYS are for experimenting with best compression ratio,
- * AUTO for optimal behaviour (based on experiments), and FORWARD_COMPAT provides
- * best forward compatibility */
- #define BLOSC_ALWAYS_SPLIT 1
- #define BLOSC_NEVER_SPLIT 2
- #define BLOSC_AUTO_SPLIT 3
- #define BLOSC_FORWARD_COMPAT_SPLIT 4
- /**
- Initialize the Blosc library environment.
- You must call this previous to any other Blosc call, unless you want
- Blosc to be used simultaneously in a multi-threaded environment, in
- which case you should *exclusively* use the
- blosc_compress_ctx()/blosc_decompress_ctx() pair (see below).
- */
- BLOSC_EXPORT void blosc_init(void);
- /**
- Destroy the Blosc library environment.
- You must call this after to you are done with all the Blosc calls,
- unless you have not used blosc_init() before (see blosc_init()
- above).
- */
- BLOSC_EXPORT void blosc_destroy(void);
- /**
- Compress a block of data in the `src` buffer and returns the size of
- the compressed block. The size of `src` buffer is specified by
- `nbytes`. There is not a minimum for `src` buffer size (`nbytes`).
- `clevel` is the desired compression level and must be a number
- between 0 (no compression) and 9 (maximum compression).
- `doshuffle` specifies whether the shuffle compression filters
- should be applied or not. BLOSC_NOSHUFFLE means not applying it,
- BLOSC_SHUFFLE means applying it at a byte level and BLOSC_BITSHUFFLE
- at a bit level (slower but may achieve better entropy alignment).
- `typesize` is the number of bytes for the atomic type in binary
- `src` buffer. This is mainly useful for the shuffle filters.
- For implementation reasons, only a 1 < `typesize` < 256 will allow the
- shuffle filter to work. When `typesize` is not in this range, shuffle
- will be silently disabled.
- The `dest` buffer must have at least the size of `destsize`. Blosc
- guarantees that if you set `destsize` to, at least,
- (`nbytes` + BLOSC_MAX_OVERHEAD), the compression will always succeed.
- The `src` buffer and the `dest` buffer can not overlap.
- Compression is memory safe and guaranteed not to write the `dest`
- buffer beyond what is specified in `destsize`.
- If `src` buffer cannot be compressed into `destsize`, the return
- value is zero and you should discard the contents of the `dest`
- buffer.
- A negative return value means that an internal error happened. This
- should never happen. If you see this, please report it back
- together with the buffer data causing this and compression settings.
- Environment variables
- ---------------------
- blosc_compress() honors different environment variables to control
- internal parameters without the need of doing that programatically.
- Here are the ones supported:
- BLOSC_CLEVEL=(INTEGER): This will overwrite the `clevel` parameter
- before the compression process starts.
- BLOSC_SHUFFLE=[NOSHUFFLE | SHUFFLE | BITSHUFFLE]: This will
- overwrite the `doshuffle` parameter before the compression process
- starts.
- BLOSC_TYPESIZE=(INTEGER): This will overwrite the `typesize`
- parameter before the compression process starts.
- BLOSC_COMPRESSOR=[BLOSCLZ | LZ4 | LZ4HC | SNAPPY | ZLIB]: This will
- call blosc_set_compressor(BLOSC_COMPRESSOR) before the compression
- process starts.
- BLOSC_NTHREADS=(INTEGER): This will call
- blosc_set_nthreads(BLOSC_NTHREADS) before the compression process
- starts.
- BLOSC_BLOCKSIZE=(INTEGER): This will call
- blosc_set_blocksize(BLOSC_BLOCKSIZE) before the compression process
- starts. *NOTE:* The blocksize is a critical parameter with
- important restrictions in the allowed values, so use this with care.
- BLOSC_NOLOCK=(ANY VALUE): This will call blosc_compress_ctx() under
- the hood, with the `compressor`, `blocksize` and
- `numinternalthreads` parameters set to the same as the last calls to
- blosc_set_compressor(), blosc_set_blocksize() and
- blosc_set_nthreads(). BLOSC_CLEVEL, BLOSC_SHUFFLE, BLOSC_TYPESIZE
- environment vars will also be honored.
- BLOSC_SPLITMODE=[ FORWARD_COMPAT | AUTO | ALWAYS | NEVER ]:
- This will call blosc_set_splitmode() with the different supported values.
- See blosc_set_splitmode() docstrings for more info on each mode.
- */
- BLOSC_EXPORT int blosc_compress(int clevel, int doshuffle, size_t typesize,
- size_t nbytes, const void *src, void *dest,
- size_t destsize);
- /**
- Context interface to blosc compression. This does not require a call
- to blosc_init() and can be called from multithreaded applications
- without the global lock being used, so allowing Blosc be executed
- simultaneously in those scenarios.
- It uses the same parameters than the blosc_compress() function plus:
- `compressor`: the string representing the type of compressor to use.
- `blocksize`: the requested size of the compressed blocks. If 0, an
- automatic blocksize will be used.
- `numinternalthreads`: the number of threads to use internally.
- A negative return value means that an internal error happened. This
- should never happen. If you see this, please report it back
- together with the buffer data causing this and compression settings.
- */
- BLOSC_EXPORT int blosc_compress_ctx(int clevel, int doshuffle, size_t typesize,
- size_t nbytes, const void* src, void* dest,
- size_t destsize, const char* compressor,
- size_t blocksize, int numinternalthreads);
- /**
- Decompress a block of compressed data in `src`, put the result in
- `dest` and returns the size of the decompressed block.
- The `src` buffer and the `dest` buffer can not overlap.
- Decompression is memory safe and guaranteed not to write the `dest`
- buffer beyond what is specified in `destsize`.
- If an error occurs, e.g. the compressed data is corrupted or the
- output buffer is not large enough, then 0 (zero) or a negative value
- will be returned instead.
- Environment variables
- ---------------------
- blosc_decompress() honors different environment variables to control
- internal parameters without the need of doing that programatically.
- Here are the ones supported:
- BLOSC_NTHREADS=(INTEGER): This will call
- blosc_set_nthreads(BLOSC_NTHREADS) before the proper decompression
- process starts.
- BLOSC_NOLOCK=(ANY VALUE): This will call blosc_decompress_ctx()
- under the hood, with the `numinternalthreads` parameter set to the
- same value as the last call to blosc_set_nthreads().
- */
- BLOSC_EXPORT int blosc_decompress(const void *src, void *dest, size_t destsize);
- /**
- Context interface to blosc decompression. This does not require a
- call to blosc_init() and can be called from multithreaded
- applications without the global lock being used, so allowing Blosc
- be executed simultaneously in those scenarios.
- It uses the same parameters than the blosc_decompress() function plus:
- `numinternalthreads`: number of threads to use internally.
- Decompression is memory safe and guaranteed not to write the `dest`
- buffer more than what is specified in `destsize`.
- If an error occurs, e.g. the compressed data is corrupted or the
- output buffer is not large enough, then 0 (zero) or a negative value
- will be returned instead.
- */
- BLOSC_EXPORT int blosc_decompress_ctx(const void *src, void *dest,
- size_t destsize, int numinternalthreads);
- /**
- Get `nitems` (of typesize size) in `src` buffer starting in `start`.
- The items are returned in `dest` buffer, which has to have enough
- space for storing all items.
- Returns the number of bytes copied to `dest` or a negative value if
- some error happens.
- */
- BLOSC_EXPORT int blosc_getitem(const void *src, int start, int nitems, void *dest);
- /**
- Returns the current number of threads that are used for
- compression/decompression.
- */
- BLOSC_EXPORT int blosc_get_nthreads(void);
- /**
- Initialize a pool of threads for compression/decompression. If
- `nthreads` is 1, then the serial version is chosen and a possible
- previous existing pool is ended. If this is not called, `nthreads`
- is set to 1 internally.
- Returns the previous number of threads.
- */
- BLOSC_EXPORT int blosc_set_nthreads(int nthreads);
- /**
- Returns the current compressor that is being used for compression.
- */
- BLOSC_EXPORT const char* blosc_get_compressor(void);
- /**
- Select the compressor to be used. The supported ones are "blosclz",
- "lz4", "lz4hc", "snappy", "zlib" and "ztsd". If this function is not
- called, then "blosclz" will be used by default.
- In case the compressor is not recognized, or there is not support
- for it in this build, it returns a -1. Else it returns the code for
- the compressor (>=0).
- */
- BLOSC_EXPORT int blosc_set_compressor(const char* compname);
- /**
- Get the `compname` associated with the `compcode`.
- If the compressor code is not recognized, or there is not support
- for it in this build, -1 is returned. Else, the compressor code is
- returned.
- */
- BLOSC_EXPORT int blosc_compcode_to_compname(int compcode, const char **compname);
- /**
- Return the compressor code associated with the compressor name.
- If the compressor name is not recognized, or there is not support
- for it in this build, -1 is returned instead.
- */
- BLOSC_EXPORT int blosc_compname_to_compcode(const char *compname);
- /**
- Get a list of compressors supported in the current build. The
- returned value is a string with a concatenation of "blosclz", "lz4",
- "lz4hc", "snappy", "zlib" or "zstd "separated by commas, depending
- on which ones are present in the build.
- This function does not leak, so you should not free() the returned
- list.
- This function should always succeed.
- */
- BLOSC_EXPORT const char* blosc_list_compressors(void);
- /**
- Return the version of the C-Blosc library in string format.
- Useful for dynamic libraries.
- */
- BLOSC_EXPORT const char* blosc_get_version_string(void);
- /**
- Get info from compression libraries included in the current build.
- In `compname` you pass the compressor name that you want info from.
- In `complib` and `version` you get a pointer to the compressor
- library name and the version in string format respectively. After
- using the name and version, you should free() them so as to avoid
- leaks.
- If the compressor is supported, it returns the code for the library
- (>=0). If it is not supported, this function returns -1.
- */
- BLOSC_EXPORT int blosc_get_complib_info(const char *compname, char **complib, char **version);
- /**
- Free possible memory temporaries and thread resources. Use this
- when you are not going to use Blosc for a long while. In case of
- problems releasing the resources, it returns a negative number, else
- it returns 0.
- */
- BLOSC_EXPORT int blosc_free_resources(void);
- /**
- Return information about a compressed buffer, namely the number of
- uncompressed bytes (`nbytes`) and compressed (`cbytes`). It also
- returns the `blocksize` (which is used internally for doing the
- compression by blocks).
- You only need to pass the first BLOSC_MIN_HEADER_LENGTH bytes of a
- compressed buffer for this call to work.
- If the format is not supported by the library, all output arguments will be
- filled with zeros.
- */
- BLOSC_EXPORT void blosc_cbuffer_sizes(const void *cbuffer, size_t *nbytes,
- size_t *cbytes, size_t *blocksize);
- /**
- Return meta-information about a compressed buffer, namely the type size
- (`typesize`), as well as some internal `flags`.
- The `flags` is a set of bits, where the used ones are:
- * bit 0: whether the shuffle filter has been applied or not
- * bit 1: whether the internal buffer is a pure memcpy or not
- * bit 2: whether the bit shuffle filter has been applied or not
- You can use the `BLOSC_DOSHUFFLE`, `BLOSC_DOBITSHUFFLE` and
- `BLOSC_MEMCPYED` symbols for extracting the interesting bits
- (e.g. ``flags & BLOSC_DOSHUFFLE`` says whether the buffer is
- byte-shuffled or not).
- You only need to pass the first BLOSC_MIN_HEADER_LENGTH bytes of a
- compressed buffer for this call to work.
- If the format is not supported by the library, all output arguments will be
- filled with zeros.
- */
- BLOSC_EXPORT void blosc_cbuffer_metainfo(const void *cbuffer, size_t *typesize,
- int *flags);
- /**
- Return information about a compressed buffer, namely the internal
- Blosc format version (`version`) and the format for the internal
- compressor used (`compversion`).
- This function should always succeed.
- */
- BLOSC_EXPORT void blosc_cbuffer_versions(const void *cbuffer, int *version,
- int *compversion);
- /**
- Return the compressor library/format used in a compressed buffer.
- This function should always succeed.
- */
- BLOSC_EXPORT const char *blosc_cbuffer_complib(const void *cbuffer);
- /*********************************************************************
- Low-level functions follows. Use them only if you are an expert!
- *********************************************************************/
- /**
- Get the internal blocksize to be used during compression. 0 means
- that an automatic blocksize is computed internally (the default).
- */
- BLOSC_EXPORT int blosc_get_blocksize(void);
- /**
- Force the use of a specific blocksize. If 0, an automatic
- blocksize will be used (the default).
- The blocksize is a critical parameter with important restrictions in
- the allowed values, so use this with care.
- */
- BLOSC_EXPORT void blosc_set_blocksize(size_t blocksize);
- /**
- Set the split mode.
- This function can take the next values:
- * BLOSC_FORWARD_COMPAT_SPLIT
- * BLOSC_AUTO_SPLIT
- * BLOSC_NEVER_SPLIT
- * BLOSC_ALWAYS_SPLIT
- BLOSC_FORWARD_COMPAT offers reasonably forward compatibility,
- BLOSC_AUTO_SPLIT is for nearly optimal results (based on heuristics),
- BLOSC_NEVER_SPLIT and BLOSC_ALWAYS_SPLIT are for the user experimenting
- when trying to get best compression ratios and/or speed.
- If not called, the default mode is BLOSC_FORWARD_COMPAT_SPLIT.
- This function should always succeed.
- */
- BLOSC_EXPORT void blosc_set_splitmode(int splitmode);
- #ifdef __cplusplus
- }
- #endif
- #endif
|