HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
blosc.h File Reference
#include <limits.h>
#include <stdlib.h>
+ Include dependency graph for blosc.h:
+ This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros

#define DLL_EXPORT
 
#define BLOSC_VERSION_MAJOR   1 /* for major interface/format changes */
 
#define BLOSC_VERSION_MINOR   5 /* for minor interface/format changes */
 
#define BLOSC_VERSION_RELEASE   0 /* for tweaks, bug-fixes, or development */
 
#define BLOSC_VERSION_STRING   "1.5.0" /* string version. Sync with above! */
 
#define BLOSC_VERSION_REVISION   "$Rev$" /* revision version */
 
#define BLOSC_VERSION_DATE   "$Date:: 2014-11-07 #$" /* date version */
 
#define BLOSCLZ_VERSION_STRING   "1.0.3" /* the internal compressor version */
 
#define BLOSC_VERSION_FORMAT   2 /* Blosc format version, starting at 1 */
 
#define BLOSC_MIN_HEADER_LENGTH   16
 
#define BLOSC_MAX_OVERHEAD   BLOSC_MIN_HEADER_LENGTH
 
#define BLOSC_MAX_BUFFERSIZE   (INT_MAX - BLOSC_MAX_OVERHEAD)
 
#define BLOSC_MAX_TYPESIZE   255 /* Cannot be larger than 255 */
 
#define BLOSC_MAX_THREADS   256
 
#define BLOSC_DOSHUFFLE   0x1
 
#define BLOSC_MEMCPYED   0x2
 
#define BLOSC_BLOSCLZ   0
 
#define BLOSC_LZ4   1
 
#define BLOSC_LZ4HC   2
 
#define BLOSC_SNAPPY   3
 
#define BLOSC_ZLIB   4
 
#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_BLOSCLZ_LIB   0
 
#define BLOSC_LZ4_LIB   1
 
#define BLOSC_SNAPPY_LIB   2
 
#define BLOSC_ZLIB_LIB   3
 
#define BLOSC_BLOSCLZ_LIBNAME   "BloscLZ"
 
#define BLOSC_LZ4_LIBNAME   "LZ4"
 
#define BLOSC_SNAPPY_LIBNAME   "Snappy"
 
#define BLOSC_ZLIB_LIBNAME   "Zlib"
 
#define BLOSC_BLOSCLZ_FORMAT   BLOSC_BLOSCLZ_LIB
 
#define BLOSC_LZ4_FORMAT   BLOSC_LZ4_LIB
 
#define BLOSC_LZ4HC_FORMAT   BLOSC_LZ4_LIB
 
#define BLOSC_SNAPPY_FORMAT   BLOSC_SNAPPY_LIB
 
#define BLOSC_ZLIB_FORMAT   BLOSC_ZLIB_LIB
 
#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
 

Functions

DLL_EXPORT void blosc_init (void)
 
DLL_EXPORT void blosc_destroy (void)
 
DLL_EXPORT int blosc_compress (int clevel, int doshuffle, size_t typesize, size_t nbytes, const void *src, void *dest, size_t destsize)
 
DLL_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)
 
DLL_EXPORT int blosc_decompress (const void *src, void *dest, size_t destsize)
 
DLL_EXPORT int blosc_decompress_ctx (const void *src, void *dest, size_t destsize, int numinternalthreads)
 
DLL_EXPORT int blosc_getitem (const void *src, int start, int nitems, void *dest)
 
DLL_EXPORT int blosc_set_nthreads (int nthreads)
 
DLL_EXPORT int blosc_set_compressor (const char *compname)
 
DLL_EXPORT int blosc_compcode_to_compname (int compcode, char **compname)
 
DLL_EXPORT int blosc_compname_to_compcode (const char *compname)
 
DLL_EXPORT char * blosc_list_compressors (void)
 
DLL_EXPORT int blosc_get_complib_info (char *compname, char **complib, char **version)
 
DLL_EXPORT int blosc_free_resources (void)
 
DLL_EXPORT void blosc_cbuffer_sizes (const void *cbuffer, size_t *nbytes, size_t *cbytes, size_t *blocksize)
 
DLL_EXPORT void blosc_cbuffer_metainfo (const void *cbuffer, size_t *typesize, int *flags)
 
DLL_EXPORT void blosc_cbuffer_versions (const void *cbuffer, int *version, int *versionlz)
 
DLL_EXPORT char * blosc_cbuffer_complib (const void *cbuffer)
 
DLL_EXPORT void blosc_set_blocksize (size_t blocksize)
 

Macro Definition Documentation

#define BLOSC_BLOSCLZ   0

Definition at line 61 of file blosc.h.

#define BLOSC_BLOSCLZ_COMPNAME   "blosclz"

Definition at line 68 of file blosc.h.

#define BLOSC_BLOSCLZ_FORMAT   BLOSC_BLOSCLZ_LIB

Definition at line 87 of file blosc.h.

#define BLOSC_BLOSCLZ_LIB   0

Definition at line 75 of file blosc.h.

#define BLOSC_BLOSCLZ_LIBNAME   "BloscLZ"

Definition at line 81 of file blosc.h.

#define BLOSC_BLOSCLZ_VERSION_FORMAT   1

Definition at line 97 of file blosc.h.

#define BLOSC_DOSHUFFLE   0x1

Definition at line 57 of file blosc.h.

#define BLOSC_LZ4   1

Definition at line 62 of file blosc.h.

#define BLOSC_LZ4_COMPNAME   "lz4"

Definition at line 69 of file blosc.h.

#define BLOSC_LZ4_FORMAT   BLOSC_LZ4_LIB

Definition at line 88 of file blosc.h.

#define BLOSC_LZ4_LIB   1

Definition at line 76 of file blosc.h.

#define BLOSC_LZ4_LIBNAME   "LZ4"

Definition at line 82 of file blosc.h.

#define BLOSC_LZ4_VERSION_FORMAT   1

Definition at line 98 of file blosc.h.

#define BLOSC_LZ4HC   2

Definition at line 63 of file blosc.h.

#define BLOSC_LZ4HC_COMPNAME   "lz4hc"

Definition at line 70 of file blosc.h.

#define BLOSC_LZ4HC_FORMAT   BLOSC_LZ4_LIB

Definition at line 90 of file blosc.h.

#define BLOSC_LZ4HC_VERSION_FORMAT   1 /* LZ4HC and LZ4 share the same format */

Definition at line 99 of file blosc.h.

#define BLOSC_MAX_BUFFERSIZE   (INT_MAX - BLOSC_MAX_OVERHEAD)

Definition at line 48 of file blosc.h.

#define BLOSC_MAX_OVERHEAD   BLOSC_MIN_HEADER_LENGTH

Definition at line 45 of file blosc.h.

#define BLOSC_MAX_THREADS   256

Definition at line 54 of file blosc.h.

#define BLOSC_MAX_TYPESIZE   255 /* Cannot be larger than 255 */

Definition at line 51 of file blosc.h.

#define BLOSC_MEMCPYED   0x2

Definition at line 58 of file blosc.h.

#define BLOSC_MIN_HEADER_LENGTH   16

Definition at line 40 of file blosc.h.

#define BLOSC_SNAPPY   3

Definition at line 64 of file blosc.h.

#define BLOSC_SNAPPY_COMPNAME   "snappy"

Definition at line 71 of file blosc.h.

#define BLOSC_SNAPPY_FORMAT   BLOSC_SNAPPY_LIB

Definition at line 91 of file blosc.h.

#define BLOSC_SNAPPY_LIB   2

Definition at line 77 of file blosc.h.

#define BLOSC_SNAPPY_LIBNAME   "Snappy"

Definition at line 83 of file blosc.h.

#define BLOSC_SNAPPY_VERSION_FORMAT   1

Definition at line 100 of file blosc.h.

#define BLOSC_VERSION_DATE   "$Date:: 2014-11-07 #$" /* date version */

Definition at line 32 of file blosc.h.

#define BLOSC_VERSION_FORMAT   2 /* Blosc format version, starting at 1 */

Definition at line 37 of file blosc.h.

#define BLOSC_VERSION_MAJOR   1 /* for major interface/format changes */

Definition at line 26 of file blosc.h.

#define BLOSC_VERSION_MINOR   5 /* for minor interface/format changes */

Definition at line 27 of file blosc.h.

#define BLOSC_VERSION_RELEASE   0 /* for tweaks, bug-fixes, or development */

Definition at line 28 of file blosc.h.

#define BLOSC_VERSION_REVISION   "$Rev$" /* revision version */

Definition at line 31 of file blosc.h.

#define BLOSC_VERSION_STRING   "1.5.0" /* string version. Sync with above! */

Definition at line 30 of file blosc.h.

#define BLOSC_ZLIB   4

Definition at line 65 of file blosc.h.

#define BLOSC_ZLIB_COMPNAME   "zlib"

Definition at line 72 of file blosc.h.

#define BLOSC_ZLIB_FORMAT   BLOSC_ZLIB_LIB

Definition at line 92 of file blosc.h.

#define BLOSC_ZLIB_LIB   3

Definition at line 78 of file blosc.h.

#define BLOSC_ZLIB_LIBNAME   "Zlib"

Definition at line 84 of file blosc.h.

#define BLOSC_ZLIB_VERSION_FORMAT   1

Definition at line 101 of file blosc.h.

#define BLOSCLZ_VERSION_STRING   "1.0.3" /* the internal compressor version */

Definition at line 34 of file blosc.h.

#define DLL_EXPORT

Definition at line 22 of file blosc.h.

Function Documentation

DLL_EXPORT char* blosc_cbuffer_complib ( const void cbuffer)

Return the compressor library/format used in a compressed buffer.

This function should always succeed.

DLL_EXPORT void blosc_cbuffer_metainfo ( const void cbuffer,
size_t *  typesize,
int flags 
)

Return 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 currently 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

You can use the BLOSC_DOSHUFFLE and BLOSC_MEMCPYED symbols for extracting the interesting bits (e.g. flags & BLOSC_DOSHUFFLE says whether the buffer is shuffled or not).

This function should always succeed.

DLL_EXPORT void blosc_cbuffer_sizes ( const void cbuffer,
size_t *  nbytes,
size_t *  cbytes,
size_t *  blocksize 
)

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.

This function should always succeed.

DLL_EXPORT void blosc_cbuffer_versions ( const void cbuffer,
int version,
int versionlz 
)

Return information about a compressed buffer, namely the internal Blosc format version (version) and the format for the internal Lempel-Ziv compressor used (versionlz).

This function should always succeed.

DLL_EXPORT int blosc_compcode_to_compname ( int  compcode,
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.

DLL_EXPORT int blosc_compname_to_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.

DLL_EXPORT int blosc_compress ( int  clevel,
int  doshuffle,
size_t  typesize,
size_t  nbytes,
const void src,
void dest,
size_t  destsize 
)

Compress a block of data in the src buffer and returns the size of 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 preconditioner should be applied or not. 0 means not applying it and 1 means applying it.

typesize is the number of bytes for the atomic type in binary src buffer. This is mainly useful for the shuffle preconditioner. 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 more than 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.

DLL_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 
)

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.

numinternalthreads: the number of threads to use internally.

Note: This call may be removed in Blosc 2.0, but a proper replacement for the same functionality should be in place by then.

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.

DLL_EXPORT int blosc_decompress ( const void src,
void dest,
size_t  destsize 
)

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 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.

DLL_EXPORT int blosc_decompress_ctx ( const void src,
void dest,
size_t  destsize,
int  numinternalthreads 
)

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.

Note: This call may be removed in Blosc 2.0, but a proper replacement for the same functionality should be in place by then.

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.

DLL_EXPORT void blosc_destroy ( 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).

DLL_EXPORT int blosc_free_resources ( void  )

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.

DLL_EXPORT int blosc_get_complib_info ( char *  compname,
char **  complib,
char **  version 
)

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 the compression library name and version (if available) as output.

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.

DLL_EXPORT int blosc_getitem ( const void src,
int  start,
int  nitems,
void dest 
)

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.

DLL_EXPORT void blosc_init ( void  )

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).

DLL_EXPORT char* blosc_list_compressors ( void  )

Get a list of compressors supported in the current build. The returned value is a string with a concatenation of "blosclz", "lz4", "lz4hc", "snappy" or "zlib" 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.

DLL_EXPORT void blosc_set_blocksize ( size_t  blocksize)

Force the use of a specific blocksize. If 0, an automatic blocksize will be used (the default).

DLL_EXPORT int blosc_set_compressor ( const char *  compname)

Select the compressor to be used. The supported ones are "blosclz", "lz4", "lz4hc", "snappy" and "zlib". If this function is not called, then "blosclz" will be used.

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).

DLL_EXPORT int blosc_set_nthreads ( int  nthreads)

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.