doc/examples/02_decompress.c

   1 // SPDX-License-Identifier: 0BSD
   2
   3 ///////////////////////////////////////////////////////////////////////////////
   4 //
   5 /// \file       02_decompress.c
   6 /// \brief      Decompress .xz files to stdout
   7 ///
   8 /// Usage:      ./02_decompress INPUT_FILES... > OUTFILE
   9 ///
  10 /// Example:    ./02_decompress foo.xz bar.xz > foobar
  11 //
  12 //  Author:     Lasse Collin
  13 //
  14 ///////////////////////////////////////////////////////////////////////////////
  15
  16 #include <stdbool.h>
  17 #include <stdlib.h>
  18 #include <stdio.h>
  19 #include <string.h>
  20 #include <errno.h>
  21 #include <lzma.h>
  22
  23
  24 static bool
  25 init_decoder(lzma_stream *strm)
  26 {
  27         // Initialize a .xz decoder. The decoder supports a memory usage limit
  28         // and a set of flags.
  29         //
  30         // The memory usage of the decompressor depends on the settings used
  31         // to compress a .xz file. It can vary from less than a megabyte to
  32         // a few gigabytes, but in practice (at least for now) it rarely
  33         // exceeds 65 MiB because that's how much memory is required to
  34         // decompress files created with "xz -9". Settings requiring more
  35         // memory take extra effort to use and don't (at least for now)
  36         // provide significantly better compression in most cases.
  37         //
  38         // Memory usage limit is useful if it is important that the
  39         // decompressor won't consume gigabytes of memory. The need
  40         // for limiting depends on the application. In this example,
  41         // no memory usage limiting is used. This is done by setting
  42         // the limit to UINT64_MAX.
  43         //
  44         // The .xz format allows concatenating compressed files as is:
  45         //
  46         //     echo foo | xz > foobar.xz
  47         //     echo bar | xz >> foobar.xz
  48         //
  49         // When decompressing normal standalone .xz files, LZMA_CONCATENATED
  50         // should always be used to support decompression of concatenated
  51         // .xz files. If LZMA_CONCATENATED isn't used, the decoder will stop
  52         // after the first .xz stream. This can be useful when .xz data has
  53         // been embedded inside another file format.
  54         //
  55         // Flags other than LZMA_CONCATENATED are supported too, and can
  56         // be combined with bitwise-or. See lzma/container.h
  57         // (src/liblzma/api/lzma/container.h in the source package or e.g.
  58         // /usr/include/lzma/container.h depending on the install prefix)
  59         // for details.
  60         lzma_ret ret = lzma_stream_decoder(
  61                         strm, UINT64_MAX, LZMA_CONCATENATED);
  62
  63         // Return successfully if the initialization went fine.
  64         if (ret == LZMA_OK)
  65                 return true;
  66
  67         // Something went wrong. The possible errors are documented in
  68         // lzma/container.h (src/liblzma/api/lzma/container.h in the source
  69         // package or e.g. /usr/include/lzma/container.h depending on the
  70         // install prefix).
  71         //
  72         // Note that LZMA_MEMLIMIT_ERROR is never possible here. If you
  73         // specify a very tiny limit, the error will be delayed until
  74         // the first headers have been parsed by a call to lzma_code().
  75         const char *msg;
  76         switch (ret) {
  77         case LZMA_MEM_ERROR:
  78                 msg = "Memory allocation failed";
  79                 break;
  80
  81         case LZMA_OPTIONS_ERROR:
  82                 msg = "Unsupported decompressor flags";
  83                 break;
  84
  85         default:
  86                 // This is most likely LZMA_PROG_ERROR indicating a bug in
  87                 // this program or in liblzma. It is inconvenient to have a
  88                 // separate error message for errors that should be impossible
  89                 // to occur, but knowing the error code is important for
  90                 // debugging. That's why it is good to print the error code
  91                 // at least when there is no good error message to show.
  92                 msg = "Unknown error, possibly a bug";
  93                 break;
  94         }
  95
  96         fprintf(stderr, "Error initializing the decoder: %s (error code %u)\n",
  97                         msg, ret);
  98         return false;
  99 }
 100
 101
 102 static bool
 103 decompress(lzma_stream *strm, const char *inname, FILE *infile, FILE *outfile)
 104 {
 105         // When LZMA_CONCATENATED flag was used when initializing the decoder,
 106         // we need to tell lzma_code() when there will be no more input.
 107         // This is done by setting action to LZMA_FINISH instead of LZMA_RUN
 108         // in the same way as it is done when encoding.
 109         //
 110         // When LZMA_CONCATENATED isn't used, there is no need to use
 111         // LZMA_FINISH to tell when all the input has been read, but it
 112         // is still OK to use it if you want. When LZMA_CONCATENATED isn't
 113         // used, the decoder will stop after the first .xz stream. In that
 114         // case some unused data may be left in strm->next_in.
 115         lzma_action action = LZMA_RUN;
 116
 117         uint8_t inbuf[BUFSIZ];
 118         uint8_t outbuf[BUFSIZ];
 119
 120         strm->next_in = NULL;
 121         strm->avail_in = 0;
 122         strm->next_out = outbuf;
 123         strm->avail_out = sizeof(outbuf);
 124
 125         while (true) {
 126                 if (strm->avail_in == 0 && !feof(infile)) {
 127                         strm->next_in = inbuf;
 128                         strm->avail_in = fread(inbuf, 1, sizeof(inbuf),
 129                                         infile);
 130
 131                         if (ferror(infile)) {
 132                                 fprintf(stderr, "%s: Read error: %s\n",
 133                                                 inname, strerror(errno));
 134                                 return false;
 135                         }
 136
 137                         // Once the end of the input file has been reached,
 138                         // we need to tell lzma_code() that no more input
 139                         // will be coming. As said before, this isn't required
 140                         // if the LZMA_CONCATENATED flag isn't used when
 141                         // initializing the decoder.
 142                         if (feof(infile))
 143                                 action = LZMA_FINISH;
 144                 }
 145
 146                 lzma_ret ret = lzma_code(strm, action);
 147
 148                 if (strm->avail_out == 0 || ret == LZMA_STREAM_END) {
 149                         size_t write_size = sizeof(outbuf) - strm->avail_out;
 150
 151                         if (fwrite(outbuf, 1, write_size, outfile)
 152                                         != write_size) {
 153                                 fprintf(stderr, "Write error: %s\n",
 154                                                 strerror(errno));
 155                                 return false;
 156                         }
 157
 158                         strm->next_out = outbuf;
 159                         strm->avail_out = sizeof(outbuf);
 160                 }
 161
 162                 if (ret != LZMA_OK) {
 163                         // Once everything has been decoded successfully, the
 164                         // return value of lzma_code() will be LZMA_STREAM_END.
 165                         //
 166                         // It is important to check for LZMA_STREAM_END. Do not
 167                         // assume that getting ret != LZMA_OK would mean that
 168                         // everything has gone well or that when you aren't
 169                         // getting more output it must have successfully
 170                         // decoded everything.
 171                         if (ret == LZMA_STREAM_END)
 172                                 return true;
 173
 174                         // It's not LZMA_OK nor LZMA_STREAM_END,
 175                         // so it must be an error code. See lzma/base.h
 176                         // (src/liblzma/api/lzma/base.h in the source package
 177                         // or e.g. /usr/include/lzma/base.h depending on the
 178                         // install prefix) for the list and documentation of
 179                         // possible values. Many values listen in lzma_ret
 180                         // enumeration aren't possible in this example, but
 181                         // can be made possible by enabling memory usage limit
 182                         // or adding flags to the decoder initialization.
 183                         const char *msg;
 184                         switch (ret) {
 185                         case LZMA_MEM_ERROR:
 186                                 msg = "Memory allocation failed";
 187                                 break;
 188
 189                         case LZMA_FORMAT_ERROR:
 190                                 // .xz magic bytes weren't found.
 191                                 msg = "The input is not in the .xz format";
 192                                 break;
 193
 194                         case LZMA_OPTIONS_ERROR:
 195                                 // For example, the headers specify a filter
 196                                 // that isn't supported by this liblzma
 197                                 // version (or it hasn't been enabled when
 198                                 // building liblzma, but no-one sane does
 199                                 // that unless building liblzma for an
 200                                 // embedded system). Upgrading to a newer
 201                                 // liblzma might help.
 202                                 //
 203                                 // Note that it is unlikely that the file has
 204                                 // accidentally became corrupt if you get this
 205                                 // error. The integrity of the .xz headers is
 206                                 // always verified with a CRC32, so
 207                                 // unintentionally corrupt files can be
 208                                 // distinguished from unsupported files.
 209                                 msg = "Unsupported compression options";
 210                                 break;
 211
 212                         case LZMA_DATA_ERROR:
 213                                 msg = "Compressed file is corrupt";
 214                                 break;
 215
 216                         case LZMA_BUF_ERROR:
 217                                 // Typically this error means that a valid
 218                                 // file has got truncated, but it might also
 219                                 // be a damaged part in the file that makes
 220                                 // the decoder think the file is truncated.
 221                                 // If you prefer, you can use the same error
 222                                 // message for this as for LZMA_DATA_ERROR.
 223                                 msg = "Compressed file is truncated or "
 224                                                 "otherwise corrupt";
 225                                 break;
 226
 227                         default:
 228                                 // This is most likely LZMA_PROG_ERROR.
 229                                 msg = "Unknown error, possibly a bug";
 230                                 break;
 231                         }
 232
 233                         fprintf(stderr, "%s: Decoder error: "
 234                                         "%s (error code %u)\n",
 235                                         inname, msg, ret);
 236                         return false;
 237                 }
 238         }
 239 }
 240
 241
 242 extern int
 243 main(int argc, char **argv)
 244 {
 245         if (argc <= 1) {
 246                 fprintf(stderr, "Usage: %s FILES...\n", argv[0]);
 247                 return EXIT_FAILURE;
 248         }
 249
 250         lzma_stream strm = LZMA_STREAM_INIT;
 251
 252         bool success = true;
 253
 254         // Try to decompress all files.
 255         for (int i = 1; i < argc; ++i) {
 256                 if (!init_decoder(&strm)) {
 257                         // Decoder initialization failed. There's no point
 258                         // to retry it so we need to exit.
 259                         success = false;
 260                         break;
 261                 }
 262
 263                 FILE *infile = fopen(argv[i], "rb");
 264
 265                 if (infile == NULL) {
 266                         fprintf(stderr, "%s: Error opening the "
 267                                         "input file: %s\n",
 268                                         argv[i], strerror(errno));
 269                         success = false;
 270                 } else {
 271                         success &= decompress(&strm, argv[i], infile, stdout);
 272                         fclose(infile);
 273                 }
 274         }
 275
 276         // Free the memory allocated for the decoder. This only needs to be
 277         // done after the last file.
 278         lzma_end(&strm);
 279
 280         if (fclose(stdout)) {
 281                 fprintf(stderr, "Write error: %s\n", strerror(errno));
 282                 success = false;
 283         }
 284
 285         return success ? EXIT_SUCCESS : EXIT_FAILURE;
 286 }