Use Cases

The zstd compression algorithm offers two common types of APIs: CTX APIs and simple APIs. This section uses simple APIs as an example to demonstrate how to call the KZstar library.

CTX APIs provide higher flexibility, allowing users to perform fine-grained operations by managing compression and decompression contexts (ZSTD_CCtx and ZSTD_DCtx). You can configure the parameters in the compression process and adjust the compression behavior more precisely.
Simple APIs offer a concise and easy-to-use calling mode. You do not need to manage contexts and configure complex parameters.

CTX API Examples

char* zstd_init()
{
    zstd_params_s* zstd_params = (zstd_params_s*) malloc(sizeof(zstd_params_s));
    if (!zstd_params) return NULL;
    zstd_params->cctx = ZSTD_createCCtx();
    zstd_params->dctx = ZSTD_createDCtx();
    zstd_params->cdict = NULL;
    return (char*) zstd_params;
}

int64_t zstd_compress(char *inbuf, size_t insize, char *outbuf, size_t outsize, size_t level, char* workmem)
{
    size_t res;

    zstd_params_s* zstd_params = (zstd_params_s*) workmem;
    if (!zstd_params || !zstd_params->cctx) return 0;

    zstd_params->zparams = ZSTD_getParams(level, insize, 0);
    ZSTD_CCtx_setParameter(zstd_params->cctx, ZSTD_c_compressionLevel, level);
    zstd_params->zparams.fParams.contentSizeFlag = 1;

    res = ZSTD_compressCCtx(zstd_params->cctx, outbuf, outsize, inbuf, insize, level);
    if (ZSTD_isError(res)) return res;

    return res;
}

int64_t zstd_decompress(char *inbuf, size_t insize, char *outbuf, size_t outsize, char* workmem)
{
    zstd_params_s* zstd_params = (zstd_params_s*) workmem;
    if (!zstd_params || !zstd_params->dctx) return 0;

    return ZSTD_decompressDCtx(zstd_params->dctx, outbuf, outsize, inbuf, insize);
}

void zstd_deinit(char* workmem)
{
    zstd_params_s* zstd_params = (zstd_params_s*) workmem;
    if (!zstd_params) return;
    if (zstd_params->cctx) ZSTD_freeCCtx(zstd_params->cctx);
    if (zstd_params->dctx) ZSTD_freeDCtx(zstd_params->dctx);
    if (zstd_params->cdict) ZSTD_freeCDict(zstd_params->cdict);
    free(workmem);
}i

Simple API Examples

// 1. Input data.
const char *input_data = "This is the input data that we want to compress using ZSTAR!";
size_t insize = strlen(input_data) + 1;

// 2. Allocate memory.
size_t compress_bound = ZSTD_compressBound(insize);
void *outbuf = malloc(compress_bound);

// 3. Compress data.
size_t compressed_size = ZSTD_compress(outbuf, compress_bound, input_data, insize, 3);  // Use compression level 3.

// 4. Decompress data.
size_t dst_size = ZSTD_getFrameContentSize(outbuf, compressed_size); // Obtain the size of the decompressed data.
void *decompressed_data = malloc(dst_size);
size_t decompressed_size = ZSTD_decompress(decompressed_data, dst_size, outbuf, compressed_size);

Enabling KZstar Using Simple APIs

Write a program using simple APIs.

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <zstd.h> 

int main() {
    const char *input_data = "This is the input data that we want to compress using KZSTAR!";
    size_t insize = strlen(input_data) + 1; 

    size_t compress_bound = ZSTD_compressBound(insize); 
    void *outbuf = malloc(compress_bound);
    if (outbuf == NULL) {
        fprintf(stderr, "Failed to allocate memory for compression buffer.\n");
        return 1;
    }

    size_t compressed_size = ZSTD_compress(outbuf, compress_bound, input_data, insize, 3); 
    if (ZSTD_isError(compressed_size)) {
        fprintf(stderr, "Compression failed: %s\n", ZSTD_getErrorName(compressed_size));
        free(outbuf);
        return 1;
    }

    printf("Data successfully compressed! Compressed size: %zu\n", compressed_size);

    size_t dst_size = ZSTD_getFrameContentSize(outbuf, compressed_size);
    void *decompressed_data = malloc(dst_size); 
    if (decompressed_data == NULL) {
        fprintf(stderr, "Failed to allocate memory for decompression buffer.\n");
        free(outbuf);
        return 1;
    }

    size_t decompressed_size = ZSTD_decompress(decompressed_data, dst_size, outbuf, compressed_size);
    if (ZSTD_isError(decompressed_size)) {
        fprintf(stderr, "Decompression failed: %s\n", ZSTD_getErrorName(decompressed_size));
        free(outbuf);
        free(decompressed_data);
        return 1;
    }

    printf("Data successfully decompressed! Decompressed size: %zu\n", decompressed_size);
    printf("Decompressed data: %s\n", (char *)decompressed_data);

    free(outbuf);
    free(decompressed_data);

    return 0;
}

Configure the environment variable based on the installation directory of KZstar.
1
export LD_LIBRARY_PATH=/usr/local/kzstar/lib:$LD_LIBRARY_PATH

Compile the program.

gcc -o ZstdSimpleCompress ZstdSimpleCompress.c -lzstd

Check whether the KZstar library is linked.

1	ldd ZstdSimpleCompress

If the following information is displayed, the program has linked the KZstar library.

	linux-vdso.so.1 (0x0000ffff83646000)
	libzstd.so.1 => /usr/local/kzstar/lib/libzstd.so.1 (0x0000ffff83528000)
	libc.so.6 => /usr/lib64/libc.so.6 (0x0000ffff83379000)
	libzstar.so => /usr/local/kzstar/lib/libzstar.so (0x0000ffff83348000)
	/lib/ld-linux-aarch64.so.1 (0x0000ffff83609000)
	libsecurec.so => /usr/local/kzstar/lib/libsecurec.so (0x0000ffff83317000)

Run the executable program.

./ZstdSimpleCompress 

The output is as follows:

Data successfully compressed! Compressed size: 70
Data successfully decompressed! Decompressed size: 61
Decompressed data: This is the input data that we want to compress using KZSTAR!