1 /*
2 * simple_buffer.c
3 * Copyright : Kyle Harper
4 * License : Follows same licensing as the lz4.c/lz4.h program at any given time. Currently, BSD 2.
5 * Description: Example program to demonstrate the basic usage of the compress/decompress functions within lz4.c/lz4.h.
6 * The functions you'll likely want are LZ4_compress_default and LZ4_decompress_safe.
7 * Both of these are documented in the lz4.h header file; I recommend reading them.
8 */
9
10 /* Dependencies */
11 #include <stdio.h> // For printf()
12 #include <string.h> // For memcmp()
13 #include <stdlib.h> // For exit()
14 #include "lz4.h" // This is all that is required to expose the prototypes for basic compression and decompression.
15
16 /*
17 * Simple show-error-and-bail function.
18 */
run_screaming(const char * message,const int code)19 void run_screaming(const char* message, const int code) {
20 printf("%s \n", message);
21 exit(code);
22 }
23
24
25 /*
26 * main
27 */
main(void)28 int main(void) {
29 /* Introduction */
30 // Below we will have a Compression and Decompression section to demonstrate.
31 // There are a few important notes before we start:
32 // 1) The return codes of LZ4_ functions are important.
33 // Read lz4.h if you're unsure what a given code means.
34 // 2) LZ4 uses char* pointers in all LZ4_ functions.
35 // This is baked into the API and not going to change, for consistency.
36 // If your program uses different pointer types,
37 // you may need to do some casting or set the right -Wno compiler flags to ignore those warnings (e.g.: -Wno-pointer-sign).
38
39 /* Compression */
40 // We'll store some text into a variable pointed to by *src to be compressed later.
41 const char* const src = "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Lorem ipsum dolor site amat.";
42 // The compression function needs to know how many bytes exist. Since we're using a string, we can use strlen() + 1 (for \0).
43 const int src_size = (int)(strlen(src) + 1);
44 // LZ4 provides a function that will tell you the maximum size of compressed output based on input data via LZ4_compressBound().
45 const int max_dst_size = LZ4_compressBound(src_size);
46 // We will use that size for our destination boundary when allocating space.
47 char* compressed_data = malloc((size_t)max_dst_size);
48 if (compressed_data == NULL)
49 run_screaming("Failed to allocate memory for *compressed_data.", 1);
50 // That's all the information and preparation LZ4 needs to compress *src into *compressed_data.
51 // Invoke LZ4_compress_default now with our size values and pointers to our memory locations.
52 // Save the return value for error checking.
53 const int compressed_data_size = LZ4_compress_default(src, compressed_data, src_size, max_dst_size);
54 // Check return_value to determine what happened.
55 if (compressed_data_size <= 0)
56 run_screaming("A 0 or negative result from LZ4_compress_default() indicates a failure trying to compress the data. ", 1);
57 if (compressed_data_size > 0)
58 printf("We successfully compressed some data! Ratio: %.2f\n",
59 (float) compressed_data_size/src_size);
60 // Not only does a positive return_value mean success, the value returned == the number of bytes required.
61 // You can use this to realloc() *compress_data to free up memory, if desired. We'll do so just to demonstrate the concept.
62 compressed_data = (char *)realloc(compressed_data, (size_t)compressed_data_size);
63 if (compressed_data == NULL)
64 run_screaming("Failed to re-alloc memory for compressed_data. Sad :(", 1);
65
66
67 /* Decompression */
68 // Now that we've successfully compressed the information from *src to *compressed_data, let's do the opposite!
69 // The decompression will need to know the compressed size, and an upper bound of the decompressed size.
70 // In this example, we just re-use this information from previous section,
71 // but in a real-world scenario, metadata must be transmitted to the decompression side.
72 // Each implementation is in charge of this part. Oftentimes, it adds some header of its own.
73 // Sometimes, the metadata can be extracted from the local context.
74
75 // First, let's create a *new_src location of size src_size since we know that value.
76 char* const regen_buffer = malloc(src_size);
77 if (regen_buffer == NULL)
78 run_screaming("Failed to allocate memory for *regen_buffer.", 1);
79 // The LZ4_decompress_safe function needs to know where the compressed data is, how many bytes long it is,
80 // where the regen_buffer memory location is, and how large regen_buffer (uncompressed) output will be.
81 // Again, save the return_value.
82 const int decompressed_size = LZ4_decompress_safe(compressed_data, regen_buffer, compressed_data_size, src_size);
83 free(compressed_data); /* no longer useful */
84 if (decompressed_size < 0)
85 run_screaming("A negative result from LZ4_decompress_safe indicates a failure trying to decompress the data. See exit code (echo $?) for value returned.", decompressed_size);
86 if (decompressed_size >= 0)
87 printf("We successfully decompressed some data!\n");
88 // Not only does a positive return value mean success,
89 // value returned == number of bytes regenerated from compressed_data stream.
90 if (decompressed_size != src_size)
91 run_screaming("Decompressed data is different from original! \n", 1);
92
93 /* Validation */
94 // We should be able to compare our original *src with our *new_src and be byte-for-byte identical.
95 if (memcmp(src, regen_buffer, src_size) != 0)
96 run_screaming("Validation failed. *src and *new_src are not identical.", 1);
97 printf("Validation done. The string we ended up with is:\n%s\n", regen_buffer);
98 return 0;
99 }
100