aboutsummaryrefslogtreecommitdiff
path: root/doc/examples/01_compress_easy.c
diff options
context:
space:
mode:
authorLasse Collin <lasse.collin@tukaani.org>2012-06-14 10:52:33 +0300
committerLasse Collin <lasse.collin@tukaani.org>2012-06-14 10:52:33 +0300
commit3a0c5378abefaf86aa39a62a7c9682bdb21568a1 (patch)
tree2ce6cc67b02009b36955b7d6e9b134ae1ce40821 /doc/examples/01_compress_easy.c
parentDocs: Move xz_pipe_comp.c and xz_pipe_decomp.c to doc/examples_old. (diff)
downloadxz-3a0c5378abefaf86aa39a62a7c9682bdb21568a1.tar.xz
Docs: Add new example programs.
These have more comments than the old examples and human-readable error messages. More tutorial-like examples are needed but these are a start.
Diffstat (limited to 'doc/examples/01_compress_easy.c')
-rw-r--r--doc/examples/01_compress_easy.c297
1 files changed, 297 insertions, 0 deletions
diff --git a/doc/examples/01_compress_easy.c b/doc/examples/01_compress_easy.c
new file mode 100644
index 00000000..f79cade1
--- /dev/null
+++ b/doc/examples/01_compress_easy.c
@@ -0,0 +1,297 @@
+///////////////////////////////////////////////////////////////////////////////
+//
+/// \file 01_compress_easy.c
+/// \brief Compress from stdin to stdout in multi-call mode
+///
+/// Usage: ./01_compress_easy PRESET < INFILE > OUTFILE
+///
+/// Example: ./01_compress_easy 6 < foo > foo.xz
+//
+// Author: Lasse Collin
+//
+// This file has been put into the public domain.
+// You can do whatever you want with this file.
+//
+///////////////////////////////////////////////////////////////////////////////
+
+#include <stdbool.h>
+#include <stdlib.h>
+#include <stdio.h>
+#include <string.h>
+#include <errno.h>
+#include <lzma.h>
+
+
+static void
+show_usage_and_exit(const char *argv0)
+{
+ fprintf(stderr, "Usage: %s PRESET < INFILE > OUTFILE\n"
+ "PRESET is a number 0-9 and can optionally be "
+ "by `e' to indicate extreme preset\n",
+ argv0);
+ exit(EXIT_FAILURE);
+}
+
+
+static uint32_t
+get_preset(int argc, char **argv)
+{
+ // One argument whose first char must be 0-9.
+ if (argc != 2 || argv[1][0] < '0' || argv[1][0] > '9')
+ show_usage_and_exit(argv[0]);
+
+ // Calculate the preste level 0-9.
+ uint32_t preset = argv[1][0] - '0';
+
+ // If there is a second char, it must be 'e'. It will set
+ // the LZMA_PRESET_EXTREME flag.
+ if (argv[1][1] != '\0') {
+ if (argv[1][1] != 'e' || argv[1][2] != '\0')
+ show_usage_and_exit(argv[0]);
+
+ preset |= LZMA_PRESET_EXTREME;
+ }
+
+ return preset;
+}
+
+
+static bool
+init_encoder(lzma_stream *strm, uint32_t preset)
+{
+ // Initialize the encoder using a preset. Set the integrity to check
+ // to CRC64, which is the default in the xz command line tool. If
+ // the .xz file needs to be decompressed with XZ Embedded, use
+ // LZMA_CHECK_CRC32 instead.
+ lzma_ret ret = lzma_easy_encoder(strm, preset, LZMA_CHECK_CRC64);
+
+ // Return successfully if the initialization went fine.
+ if (ret == LZMA_OK)
+ return true;
+
+ // Something went wrong. The possible errors are documented in
+ // lzma/container.h (src/liblzma/api/lzma/container.h in the source
+ // package or e.g. /usr/include/lzma/container.h depending on the
+ // install prefix).
+ const char *msg;
+ switch (ret) {
+ case LZMA_MEM_ERROR:
+ msg = "Memory allocation failed";
+ break;
+
+ case LZMA_OPTIONS_ERROR:
+ msg = "Specified preset is not supported";
+ break;
+
+ case LZMA_UNSUPPORTED_CHECK:
+ msg = "Specified integrity check is not supported";
+ break;
+
+ default:
+ // This is most likely LZMA_PROG_ERROR indicating a bug in
+ // this program or in liblzma. It is inconvenient to have a
+ // separate error message for errors that should be impossible
+ // to occur, but knowing the error code is important for
+ // debugging. That's why it is good to print the error code
+ // at least when there is no good error message to show.
+ msg = "Unknown error, possibly a bug";
+ break;
+ }
+
+ fprintf(stderr, "Error initializing the encoder: %s (error code %u)\n",
+ msg, ret);
+ return false;
+}
+
+
+static bool
+compress(lzma_stream *strm, FILE *infile, FILE *outfile)
+{
+ // This will be LZMA_RUN until the end of the input file is reached.
+ // This tells lzma_code() when there will be no more input.
+ lzma_action action = LZMA_RUN;
+
+ // Buffers to temporarily hold uncompressed input
+ // and compressed output.
+ uint8_t inbuf[BUFSIZ];
+ uint8_t outbuf[BUFSIZ];
+
+ // Initialize the input and output pointers. Initializing next_in
+ // and avail_in isn't really necessary when we are going to encode
+ // just one file since LZMA_STREAM_INIT takes care of initializing
+ // those already. But it doesn't hurt much and it will be needed
+ // if encoding more than one file like we will in 02_decompress.c.
+ //
+ // While we don't care about strm->total_in or strm->total_out in this
+ // example, it is worth noting that initializing the encoder will
+ // always reset total_in and total_out to zero. But the encoder
+ // initialization doesn't touch next_in, avail_in, next_out, or
+ // avail_out.
+ strm->next_in = NULL;
+ strm->avail_in = 0;
+ strm->next_out = outbuf;
+ strm->avail_out = sizeof(outbuf);
+
+ // Loop until the file has been successfully compressed or until
+ // an error occurs.
+ while (true) {
+ // Fill the input buffer if it is empty.
+ if (strm->avail_in == 0 && !feof(infile)) {
+ strm->next_in = inbuf;
+ strm->avail_in = fread(inbuf, 1, sizeof(inbuf),
+ infile);
+
+ if (ferror(infile)) {
+ fprintf(stderr, "Read error: %s\n",
+ strerror(errno));
+ return false;
+ }
+
+ // Once the end of the input file has been reached,
+ // we need to tell lzma_code() that no more input
+ // will be coming and that it should finish the
+ // encoding.
+ if (feof(infile))
+ action = LZMA_FINISH;
+ }
+
+ // Tell liblzma do the actual encoding.
+ //
+ // This reads up to strm->avail_in bytes of input starting
+ // from strm->next_in. avail_in will be decremented and
+ // next_in incremented by an equal amount to match the
+ // number of input bytes consumed.
+ //
+ // Up to strm->avail_out bytes of compressed output will be
+ // written starting from strm->next_out. avail_out and next_out
+ // will be incremented by an equal amount to match the number
+ // of output bytes written.
+ //
+ // The encoder has to do internal buffering, which means that
+ // it may take quite a bit of input before the same data is
+ // available in compressed form in the output buffer.
+ lzma_ret ret = lzma_code(strm, action);
+
+ // If the output buffer is full or if the compression finished
+ // successfully, write the data from the output bufffer to
+ // the output file.
+ if (strm->avail_out == 0 || ret == LZMA_STREAM_END) {
+ // When lzma_code() has returned LZMA_STREAM_END,
+ // the output buffer is likely to be only partially
+ // full. Calculate how much new data there is to
+ // be written to the output file.
+ size_t write_size = sizeof(outbuf) - strm->avail_out;
+
+ if (fwrite(outbuf, 1, write_size, outfile)
+ != write_size) {
+ fprintf(stderr, "Write error: %s\n",
+ strerror(errno));
+ return false;
+ }
+
+ // Reset next_out and avail_out.
+ strm->next_out = outbuf;
+ strm->avail_out = sizeof(outbuf);
+ }
+
+ // Normally the return value of lzma_code() will be LZMA_OK
+ // until everything has been encoded.
+ if (ret != LZMA_OK) {
+ // Once everything has been encoded successfully, the
+ // return value of lzma_code() will be LZMA_STREAM_END.
+ //
+ // It is important to check for LZMA_STREAM_END. Do not
+ // assume that getting ret != LZMA_OK would mean that
+ // everything has gone well.
+ if (ret == LZMA_STREAM_END)
+ return true;
+
+ // It's not LZMA_OK nor LZMA_STREAM_END,
+ // so it must be an error code. See lzma/base.h
+ // (src/liblzma/api/lzma/base.h in the source package
+ // or e.g. /usr/include/lzma/base.h depending on the
+ // install prefix) for the list and documentation of
+ // possible values. Most values listen in lzma_ret
+ // enumeration aren't possible in this example.
+ const char *msg;
+ switch (ret) {
+ case LZMA_MEM_ERROR:
+ msg = "Memory allocation failed";
+ break;
+
+ case LZMA_DATA_ERROR:
+ // This error is returned if the compressed
+ // or uncompressed size get near 8 EiB
+ // (2^63 bytes) because that's where the .xz
+ // file format size limits currently are.
+ // That is, the possibility of this error
+ // is mostly theoretical unless you are doing
+ // something very unusual.
+ //
+ // Note that strm->total_in and strm->total_out
+ // have nothing to do with this error. Changing
+ // those variables won't increase or decrease
+ // the chance of getting this error.
+ msg = "File size limits exceeded";
+ break;
+
+ default:
+ // This is most likely LZMA_PROG_ERROR, but
+ // if this program is buggy (or liblzma has
+ // a bug), it may be e.g. LZMA_BUF_ERROR or
+ // LZMA_OPTIONS_ERROR too.
+ //
+ // It is inconvenient to have a separate
+ // error message for errors that should be
+ // impossible to occur, but knowing the error
+ // code is important for debugging. That's why
+ // it is good to print the error code at least
+ // when there is no good error message to show.
+ msg = "Unknown error, possibly a bug";
+ break;
+ }
+
+ fprintf(stderr, "Encoder error: %s (error code %u)\n",
+ msg, ret);
+ return false;
+ }
+ }
+}
+
+
+extern int
+main(int argc, char **argv)
+{
+ // Get the preset number from the command line.
+ uint32_t preset = get_preset(argc, argv);
+
+ // Initialize a lzma_stream structure. When it is allocated on stack,
+ // it is simplest to use LZMA_STREAM_INIT macro like below. When it
+ // is allocated on heap, using memset(strmptr, 0, sizeof(*strmptr))
+ // works (as long as NULL pointers are represented with zero bits
+ // as they are on practically all computers today).
+ lzma_stream strm = LZMA_STREAM_INIT;
+
+ // Initialize the encoder. If it succeeds, compress from
+ // stdin to stdout.
+ bool success = init_encoder(&strm, preset);
+ if (success)
+ success = compress(&strm, stdin, stdout);
+
+ // Free the memory allocated for the encoder. If we were encoding
+ // multiple files, this would only need to be done after the last
+ // file. See 02_decompress.c for handling of multiple files.
+ //
+ // It is OK to call lzma_end() multiple times or when it hasn't been
+ // actually used except initialized with LZMA_STREAM_INIT.
+ lzma_end(&strm);
+
+ // Close stdout to catch possible write errors that can occur
+ // when pending data is flushed from the stdio buffers.
+ if (fclose(stdout)) {
+ fprintf(stderr, "Write error: %s\n", strerror(errno));
+ success = false;
+ }
+
+ return success ? EXIT_SUCCESS : EXIT_FAILURE;
+}