Imported to git.
authorLasse Collin <lasse.collin@tukaani.org>
Sat, 8 Dec 2007 22:42:33 +0000 (00:42 +0200)
committerLasse Collin <lasse.collin@tukaani.org>
Sat, 8 Dec 2007 22:42:33 +0000 (00:42 +0200)
240 files changed:
AUTHORS [new file with mode: 0644]
COPYING [new file with mode: 0644]
COPYING.GPLv2 [new file with mode: 0644]
COPYING.GPLv3 [new file with mode: 0644]
COPYING.LGPLv2.1 [new file with mode: 0644]
ChangeLog [new file with mode: 0644]
Doxyfile.in [new file with mode: 0644]
Makefile.am [new file with mode: 0644]
NEWS [new file with mode: 0644]
README [new file with mode: 0644]
THANKS [new file with mode: 0644]
TODO [new file with mode: 0644]
autogen.sh [new file with mode: 0755]
configure.ac [new file with mode: 0644]
doc/bugs.txt [new file with mode: 0644]
doc/faq.txt [new file with mode: 0644]
doc/file-format.txt [new file with mode: 0644]
doc/history.txt [new file with mode: 0644]
doc/liblzma-advanced.txt [new file with mode: 0644]
doc/liblzma-hacking.txt [new file with mode: 0644]
doc/liblzma-intro.txt [new file with mode: 0644]
doc/liblzma-security.txt [new file with mode: 0644]
doc/lzma-intro.txt [new file with mode: 0644]
extra/scanlzma/scanlzma.c [new file with mode: 0644]
lib/Makefile.am [new file with mode: 0644]
lib/getopt.c [new file with mode: 0644]
lib/getopt1.c [new file with mode: 0644]
lib/getopt_.h [new file with mode: 0644]
lib/getopt_int.h [new file with mode: 0644]
lib/gettext.h [new file with mode: 0644]
m4/acx_pthread.m4 [new file with mode: 0644]
m4/getopt.m4 [new file with mode: 0644]
po/LINGUAS [new file with mode: 0644]
po/Makevars [new file with mode: 0644]
po/POTFILES.in [new file with mode: 0644]
po/fi.po [new file with mode: 0644]
src/Makefile.am [new file with mode: 0644]
src/common/open_stdxxx.h [new file with mode: 0644]
src/common/physmem.h [new file with mode: 0644]
src/common/sysdefs.h [new file with mode: 0644]
src/liblzma/Makefile.am [new file with mode: 0644]
src/liblzma/api/Makefile.am [new file with mode: 0644]
src/liblzma/api/lzma.h [new file with mode: 0644]
src/liblzma/api/lzma/alignment.h [new file with mode: 0644]
src/liblzma/api/lzma/alone.h [new file with mode: 0644]
src/liblzma/api/lzma/auto.h [new file with mode: 0644]
src/liblzma/api/lzma/base.h [new file with mode: 0644]
src/liblzma/api/lzma/block.h [new file with mode: 0644]
src/liblzma/api/lzma/check.h [new file with mode: 0644]
src/liblzma/api/lzma/copy.h [new file with mode: 0644]
src/liblzma/api/lzma/delta.h [new file with mode: 0644]
src/liblzma/api/lzma/extra.h [new file with mode: 0644]
src/liblzma/api/lzma/filter.h [new file with mode: 0644]
src/liblzma/api/lzma/index.h [new file with mode: 0644]
src/liblzma/api/lzma/info.h [new file with mode: 0644]
src/liblzma/api/lzma/init.h [new file with mode: 0644]
src/liblzma/api/lzma/lzma.h [new file with mode: 0644]
src/liblzma/api/lzma/memlimit.h [new file with mode: 0644]
src/liblzma/api/lzma/metadata.h [new file with mode: 0644]
src/liblzma/api/lzma/raw.h [new file with mode: 0644]
src/liblzma/api/lzma/simple.h [new file with mode: 0644]
src/liblzma/api/lzma/stream.h [new file with mode: 0644]
src/liblzma/api/lzma/stream_flags.h [new file with mode: 0644]
src/liblzma/api/lzma/subblock.h [new file with mode: 0644]
src/liblzma/api/lzma/version.h [new file with mode: 0644]
src/liblzma/api/lzma/vli.h [new file with mode: 0644]
src/liblzma/check/Makefile.am [new file with mode: 0644]
src/liblzma/check/check.c [new file with mode: 0644]
src/liblzma/check/check.h [new file with mode: 0644]
src/liblzma/check/check_byteswap.h [new file with mode: 0644]
src/liblzma/check/check_init.c [new file with mode: 0644]
src/liblzma/check/crc32.c [new file with mode: 0644]
src/liblzma/check/crc32_init.c [new file with mode: 0644]
src/liblzma/check/crc32_table.c [new file with mode: 0644]
src/liblzma/check/crc32_table_be.h [new file with mode: 0644]
src/liblzma/check/crc32_table_le.h [new file with mode: 0644]
src/liblzma/check/crc32_tablegen.c [new file with mode: 0644]
src/liblzma/check/crc32_x86.s [new file with mode: 0644]
src/liblzma/check/crc64.c [new file with mode: 0644]
src/liblzma/check/crc64_init.c [new file with mode: 0644]
src/liblzma/check/crc64_table.c [new file with mode: 0644]
src/liblzma/check/crc64_table_be.h [new file with mode: 0644]
src/liblzma/check/crc64_table_le.h [new file with mode: 0644]
src/liblzma/check/crc64_tablegen.c [new file with mode: 0644]
src/liblzma/check/crc64_x86.s [new file with mode: 0644]
src/liblzma/check/crc_macros.h [new file with mode: 0644]
src/liblzma/check/sha256.c [new file with mode: 0644]
src/liblzma/common/Makefile.am [new file with mode: 0644]
src/liblzma/common/alignment.c [new file with mode: 0644]
src/liblzma/common/allocator.c [new file with mode: 0644]
src/liblzma/common/alone_decoder.c [new file with mode: 0644]
src/liblzma/common/alone_decoder.h [new file with mode: 0644]
src/liblzma/common/alone_encoder.c [new file with mode: 0644]
src/liblzma/common/auto_decoder.c [new file with mode: 0644]
src/liblzma/common/block_decoder.c [new file with mode: 0644]
src/liblzma/common/block_decoder.h [new file with mode: 0644]
src/liblzma/common/block_encoder.c [new file with mode: 0644]
src/liblzma/common/block_encoder.h [new file with mode: 0644]
src/liblzma/common/block_header_decoder.c [new file with mode: 0644]
src/liblzma/common/block_header_encoder.c [new file with mode: 0644]
src/liblzma/common/block_private.h [new file with mode: 0644]
src/liblzma/common/chunk_size.c [new file with mode: 0644]
src/liblzma/common/code.c [new file with mode: 0644]
src/liblzma/common/common.h [new file with mode: 0644]
src/liblzma/common/copy_coder.c [new file with mode: 0644]
src/liblzma/common/copy_coder.h [new file with mode: 0644]
src/liblzma/common/delta_coder.c [new file with mode: 0644]
src/liblzma/common/delta_coder.h [new file with mode: 0644]
src/liblzma/common/extra.c [new file with mode: 0644]
src/liblzma/common/features.c [new file with mode: 0644]
src/liblzma/common/filter_flags_decoder.c [new file with mode: 0644]
src/liblzma/common/filter_flags_encoder.c [new file with mode: 0644]
src/liblzma/common/index.c [new file with mode: 0644]
src/liblzma/common/info.c [new file with mode: 0644]
src/liblzma/common/init.c [new file with mode: 0644]
src/liblzma/common/init_decoder.c [new file with mode: 0644]
src/liblzma/common/init_encoder.c [new file with mode: 0644]
src/liblzma/common/memory_limitter.c [new file with mode: 0644]
src/liblzma/common/memory_usage.c [new file with mode: 0644]
src/liblzma/common/metadata_decoder.c [new file with mode: 0644]
src/liblzma/common/metadata_decoder.h [new file with mode: 0644]
src/liblzma/common/metadata_encoder.c [new file with mode: 0644]
src/liblzma/common/metadata_encoder.h [new file with mode: 0644]
src/liblzma/common/next_coder.c [new file with mode: 0644]
src/liblzma/common/raw_common.c [new file with mode: 0644]
src/liblzma/common/raw_common.h [new file with mode: 0644]
src/liblzma/common/raw_decoder.c [new file with mode: 0644]
src/liblzma/common/raw_decoder.h [new file with mode: 0644]
src/liblzma/common/raw_encoder.c [new file with mode: 0644]
src/liblzma/common/raw_encoder.h [new file with mode: 0644]
src/liblzma/common/stream_common.c [new file with mode: 0644]
src/liblzma/common/stream_common.h [new file with mode: 0644]
src/liblzma/common/stream_decoder.c [new file with mode: 0644]
src/liblzma/common/stream_encoder_multi.c [new file with mode: 0644]
src/liblzma/common/stream_encoder_single.c [new file with mode: 0644]
src/liblzma/common/stream_flags_decoder.c [new file with mode: 0644]
src/liblzma/common/stream_flags_decoder.h [new file with mode: 0644]
src/liblzma/common/stream_flags_encoder.c [new file with mode: 0644]
src/liblzma/common/sysdefs.h [new symlink]
src/liblzma/common/version.c [new file with mode: 0644]
src/liblzma/common/vli_decoder.c [new file with mode: 0644]
src/liblzma/common/vli_encoder.c [new file with mode: 0644]
src/liblzma/common/vli_reverse_decoder.c [new file with mode: 0644]
src/liblzma/lz/Makefile.am [new file with mode: 0644]
src/liblzma/lz/bt2.c [new file with mode: 0644]
src/liblzma/lz/bt2.h [new file with mode: 0644]
src/liblzma/lz/bt3.c [new file with mode: 0644]
src/liblzma/lz/bt3.h [new file with mode: 0644]
src/liblzma/lz/bt4.c [new file with mode: 0644]
src/liblzma/lz/bt4.h [new file with mode: 0644]
src/liblzma/lz/hc3.c [new file with mode: 0644]
src/liblzma/lz/hc3.h [new file with mode: 0644]
src/liblzma/lz/hc4.c [new file with mode: 0644]
src/liblzma/lz/hc4.h [new file with mode: 0644]
src/liblzma/lz/lz_decoder.c [new file with mode: 0644]
src/liblzma/lz/lz_decoder.h [new file with mode: 0644]
src/liblzma/lz/lz_encoder.c [new file with mode: 0644]
src/liblzma/lz/lz_encoder.h [new file with mode: 0644]
src/liblzma/lz/lz_encoder_private.h [new file with mode: 0644]
src/liblzma/lz/match_c.h [new file with mode: 0644]
src/liblzma/lz/match_h.h [new file with mode: 0644]
src/liblzma/lzma.pc.in [new file with mode: 0644]
src/liblzma/lzma/Makefile.am [new file with mode: 0644]
src/liblzma/lzma/lzma_common.h [new file with mode: 0644]
src/liblzma/lzma/lzma_decoder.c [new file with mode: 0644]
src/liblzma/lzma/lzma_decoder.h [new file with mode: 0644]
src/liblzma/lzma/lzma_encoder.c [new file with mode: 0644]
src/liblzma/lzma/lzma_encoder.h [new file with mode: 0644]
src/liblzma/lzma/lzma_encoder_features.c [new file with mode: 0644]
src/liblzma/lzma/lzma_encoder_getoptimum.c [new file with mode: 0644]
src/liblzma/lzma/lzma_encoder_getoptimumfast.c [new file with mode: 0644]
src/liblzma/lzma/lzma_encoder_init.c [new file with mode: 0644]
src/liblzma/lzma/lzma_encoder_presets.c [new file with mode: 0644]
src/liblzma/lzma/lzma_encoder_private.h [new file with mode: 0644]
src/liblzma/lzma/lzma_literal.c [new file with mode: 0644]
src/liblzma/lzma/lzma_literal.h [new file with mode: 0644]
src/liblzma/rangecoder/Makefile.am [new file with mode: 0644]
src/liblzma/rangecoder/range_common.h [new file with mode: 0644]
src/liblzma/rangecoder/range_decoder.h [new file with mode: 0644]
src/liblzma/rangecoder/range_encoder.c [new file with mode: 0644]
src/liblzma/rangecoder/range_encoder.h [new file with mode: 0644]
src/liblzma/simple/Makefile.am [new file with mode: 0644]
src/liblzma/simple/arm.c [new file with mode: 0644]
src/liblzma/simple/armthumb.c [new file with mode: 0644]
src/liblzma/simple/ia64.c [new file with mode: 0644]
src/liblzma/simple/powerpc.c [new file with mode: 0644]
src/liblzma/simple/simple_coder.c [new file with mode: 0644]
src/liblzma/simple/simple_coder.h [new file with mode: 0644]
src/liblzma/simple/simple_private.h [new file with mode: 0644]
src/liblzma/simple/sparc.c [new file with mode: 0644]
src/liblzma/simple/x86.c [new file with mode: 0644]
src/liblzma/subblock/Makefile.am [new file with mode: 0644]
src/liblzma/subblock/subblock_decoder.c [new file with mode: 0644]
src/liblzma/subblock/subblock_decoder.h [new file with mode: 0644]
src/liblzma/subblock/subblock_decoder_helper.c [new file with mode: 0644]
src/liblzma/subblock/subblock_decoder_helper.h [new file with mode: 0644]
src/liblzma/subblock/subblock_encoder.c [new file with mode: 0644]
src/liblzma/subblock/subblock_encoder.h [new file with mode: 0644]
src/lzma/Makefile.am [new file with mode: 0644]
src/lzma/alloc.c [new file with mode: 0644]
src/lzma/alloc.h [new file with mode: 0644]
src/lzma/args.c [new file with mode: 0644]
src/lzma/args.h [new file with mode: 0644]
src/lzma/error.c [new file with mode: 0644]
src/lzma/error.h [new file with mode: 0644]
src/lzma/hardware.c [new file with mode: 0644]
src/lzma/hardware.h [new file with mode: 0644]
src/lzma/help.c [new file with mode: 0644]
src/lzma/help.h [new file with mode: 0644]
src/lzma/io.c [new file with mode: 0644]
src/lzma/io.h [new file with mode: 0644]
src/lzma/list.c [new file with mode: 0644]
src/lzma/main.c [new file with mode: 0644]
src/lzma/options.c [new file with mode: 0644]
src/lzma/options.h [new file with mode: 0644]
src/lzma/private.h [new file with mode: 0644]
src/lzma/process.c [new file with mode: 0644]
src/lzma/process.h [new file with mode: 0644]
src/lzma/suffix.c [new file with mode: 0644]
src/lzma/suffix.h [new file with mode: 0644]
src/lzma/util.c [new file with mode: 0644]
src/lzma/util.h [new file with mode: 0644]
src/lzmadec/Makefile.am [new file with mode: 0644]
src/lzmadec/lzmadec.c [new file with mode: 0644]
src/scripts/Makefile.am [new file with mode: 0644]
src/scripts/lzdiff [new file with mode: 0755]
src/scripts/lzdiff.1 [new file with mode: 0644]
src/scripts/lzgrep [new file with mode: 0755]
src/scripts/lzgrep.1 [new file with mode: 0644]
src/scripts/lzmore [new file with mode: 0755]
src/scripts/lzmore.1 [new file with mode: 0644]
tests/Makefile.am [new file with mode: 0644]
tests/test_block.c [new file with mode: 0644]
tests/test_block_header.c [new file with mode: 0644]
tests/test_check.c [new file with mode: 0644]
tests/test_filter_flags.c [new file with mode: 0644]
tests/test_index.c [new file with mode: 0644]
tests/test_info.c [new file with mode: 0644]
tests/test_stream_flags.c [new file with mode: 0644]
tests/tests.h [new file with mode: 0644]

diff --git a/AUTHORS b/AUTHORS
new file mode 100644 (file)
index 0000000..1bacbd6
--- /dev/null
+++ b/AUTHORS
@@ -0,0 +1,18 @@
+
+Authors of LZMA Utils
+---------------------
+
+Igor Pavlov
+  * designed LZMA as an algorithm;
+  * wrote an implementation known as LZMA SDK, which is part of
+    the bigger 7-Zip project.
+
+Ville Koskinen
+  * wrote the first version of the gzip-like lzma command line
+    utility (C++)
+  * helped a lot with the documentation.
+
+Lasse Collin
+  * ported LZMA SDK to C and zlib-like API (liblzma);
+  * rewrote the command line tool again to use liblzma and pthreads.
+
diff --git a/COPYING b/COPYING
new file mode 100644 (file)
index 0000000..a17989d
--- /dev/null
+++ b/COPYING
@@ -0,0 +1,24 @@
+
+LZMA Utils Licenses
+-------------------
+
+    Different licenses apply to different files in this package. Here
+    is a rough summary of which license apply to which parts of this
+    package (but check the individual files to be sure!):
+      - Everything under src/liblzma/check is public domain.
+      - Everything else under the src directory is under the GNU LGPL
+        2.1 or (at your opinion) any later version.
+      - Outside the src directory, there are some files that are under
+        the GNU GPL 2 or (at your opinion) any later version, or under
+        the GNU GPL 3 or (at your opinion) any later version.
+      - Most documentation files are under an all-permissive license.
+
+    The following license texts are included in the following files
+    in this package:
+      - COPYING.LGPLv2.1: GNU Lesser General Public License version 2.1
+      - COPYING.GPLv2: GNU General Public License version 2
+      - COPYING.GPLv3: GNU General Public License version 3
+
+    If you have questions, don't hesitate to ask the copyright holder(s)
+    for more information.
+
diff --git a/COPYING.GPLv2 b/COPYING.GPLv2
new file mode 100644 (file)
index 0000000..d511905
--- /dev/null
@@ -0,0 +1,339 @@
+                   GNU GENERAL PUBLIC LICENSE
+                      Version 2, June 1991
+
+ Copyright (C) 1989, 1991 Free Software Foundation, Inc.,
+ 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                           Preamble
+
+  The licenses for most software are designed to take away your
+freedom to share and change it.  By contrast, the GNU General Public
+License is intended to guarantee your freedom to share and change free
+software--to make sure the software is free for all its users.  This
+General Public License applies to most of the Free Software
+Foundation's software and to any other program whose authors commit to
+using it.  (Some other Free Software Foundation software is covered by
+the GNU Lesser General Public License instead.)  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+this service if you wish), that you receive source code or can get it
+if you want it, that you can change the software or use pieces of it
+in new free programs; and that you know you can do these things.
+
+  To protect your rights, we need to make restrictions that forbid
+anyone to deny you these rights or to ask you to surrender the rights.
+These restrictions translate to certain responsibilities for you if you
+distribute copies of the software, or if you modify it.
+
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must give the recipients all the rights that
+you have.  You must make sure that they, too, receive or can get the
+source code.  And you must show them these terms so they know their
+rights.
+
+  We protect your rights with two steps: (1) copyright the software, and
+(2) offer you this license which gives you legal permission to copy,
+distribute and/or modify the software.
+
+  Also, for each author's protection and ours, we want to make certain
+that everyone understands that there is no warranty for this free
+software.  If the software is modified by someone else and passed on, we
+want its recipients to know that what they have is not the original, so
+that any problems introduced by others will not reflect on the original
+authors' reputations.
+
+  Finally, any free program is threatened constantly by software
+patents.  We wish to avoid the danger that redistributors of a free
+program will individually obtain patent licenses, in effect making the
+program proprietary.  To prevent this, we have made it clear that any
+patent must be licensed for everyone's free use or not licensed at all.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                   GNU GENERAL PUBLIC LICENSE
+   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+  0. This License applies to any program or other work which contains
+a notice placed by the copyright holder saying it may be distributed
+under the terms of this General Public License.  The "Program", below,
+refers to any such program or work, and a "work based on the Program"
+means either the Program or any derivative work under copyright law:
+that is to say, a work containing the Program or a portion of it,
+either verbatim or with modifications and/or translated into another
+language.  (Hereinafter, translation is included without limitation in
+the term "modification".)  Each licensee is addressed as "you".
+
+Activities other than copying, distribution and modification are not
+covered by this License; they are outside its scope.  The act of
+running the Program is not restricted, and the output from the Program
+is covered only if its contents constitute a work based on the
+Program (independent of having been made by running the Program).
+Whether that is true depends on what the Program does.
+
+  1. You may copy and distribute verbatim copies of the Program's
+source code as you receive it, in any medium, provided that you
+conspicuously and appropriately publish on each copy an appropriate
+copyright notice and disclaimer of warranty; keep intact all the
+notices that refer to this License and to the absence of any warranty;
+and give any other recipients of the Program a copy of this License
+along with the Program.
+
+You may charge a fee for the physical act of transferring a copy, and
+you may at your option offer warranty protection in exchange for a fee.
+
+  2. You may modify your copy or copies of the Program or any portion
+of it, thus forming a work based on the Program, and copy and
+distribute such modifications or work under the terms of Section 1
+above, provided that you also meet all of these conditions:
+
+    a) You must cause the modified files to carry prominent notices
+    stating that you changed the files and the date of any change.
+
+    b) You must cause any work that you distribute or publish, that in
+    whole or in part contains or is derived from the Program or any
+    part thereof, to be licensed as a whole at no charge to all third
+    parties under the terms of this License.
+
+    c) If the modified program normally reads commands interactively
+    when run, you must cause it, when started running for such
+    interactive use in the most ordinary way, to print or display an
+    announcement including an appropriate copyright notice and a
+    notice that there is no warranty (or else, saying that you provide
+    a warranty) and that users may redistribute the program under
+    these conditions, and telling the user how to view a copy of this
+    License.  (Exception: if the Program itself is interactive but
+    does not normally print such an announcement, your work based on
+    the Program is not required to print an announcement.)
+
+These requirements apply to the modified work as a whole.  If
+identifiable sections of that work are not derived from the Program,
+and can be reasonably considered independent and separate works in
+themselves, then this License, and its terms, do not apply to those
+sections when you distribute them as separate works.  But when you
+distribute the same sections as part of a whole which is a work based
+on the Program, the distribution of the whole must be on the terms of
+this License, whose permissions for other licensees extend to the
+entire whole, and thus to each and every part regardless of who wrote it.
+
+Thus, it is not the intent of this section to claim rights or contest
+your rights to work written entirely by you; rather, the intent is to
+exercise the right to control the distribution of derivative or
+collective works based on the Program.
+
+In addition, mere aggregation of another work not based on the Program
+with the Program (or with a work based on the Program) on a volume of
+a storage or distribution medium does not bring the other work under
+the scope of this License.
+
+  3. You may copy and distribute the Program (or a work based on it,
+under Section 2) in object code or executable form under the terms of
+Sections 1 and 2 above provided that you also do one of the following:
+
+    a) Accompany it with the complete corresponding machine-readable
+    source code, which must be distributed under the terms of Sections
+    1 and 2 above on a medium customarily used for software interchange; or,
+
+    b) Accompany it with a written offer, valid for at least three
+    years, to give any third party, for a charge no more than your
+    cost of physically performing source distribution, a complete
+    machine-readable copy of the corresponding source code, to be
+    distributed under the terms of Sections 1 and 2 above on a medium
+    customarily used for software interchange; or,
+
+    c) Accompany it with the information you received as to the offer
+    to distribute corresponding source code.  (This alternative is
+    allowed only for noncommercial distribution and only if you
+    received the program in object code or executable form with such
+    an offer, in accord with Subsection b above.)
+
+The source code for a work means the preferred form of the work for
+making modifications to it.  For an executable work, complete source
+code means all the source code for all modules it contains, plus any
+associated interface definition files, plus the scripts used to
+control compilation and installation of the executable.  However, as a
+special exception, the source code distributed need not include
+anything that is normally distributed (in either source or binary
+form) with the major components (compiler, kernel, and so on) of the
+operating system on which the executable runs, unless that component
+itself accompanies the executable.
+
+If distribution of executable or object code is made by offering
+access to copy from a designated place, then offering equivalent
+access to copy the source code from the same place counts as
+distribution of the source code, even though third parties are not
+compelled to copy the source along with the object code.
+
+  4. You may not copy, modify, sublicense, or distribute the Program
+except as expressly provided under this License.  Any attempt
+otherwise to copy, modify, sublicense or distribute the Program is
+void, and will automatically terminate your rights under this License.
+However, parties who have received copies, or rights, from you under
+this License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+  5. You are not required to accept this License, since you have not
+signed it.  However, nothing else grants you permission to modify or
+distribute the Program or its derivative works.  These actions are
+prohibited by law if you do not accept this License.  Therefore, by
+modifying or distributing the Program (or any work based on the
+Program), you indicate your acceptance of this License to do so, and
+all its terms and conditions for copying, distributing or modifying
+the Program or works based on it.
+
+  6. Each time you redistribute the Program (or any work based on the
+Program), the recipient automatically receives a license from the
+original licensor to copy, distribute or modify the Program subject to
+these terms and conditions.  You may not impose any further
+restrictions on the recipients' exercise of the rights granted herein.
+You are not responsible for enforcing compliance by third parties to
+this License.
+
+  7. If, as a consequence of a court judgment or allegation of patent
+infringement or for any other reason (not limited to patent issues),
+conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot
+distribute so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you
+may not distribute the Program at all.  For example, if a patent
+license would not permit royalty-free redistribution of the Program by
+all those who receive copies directly or indirectly through you, then
+the only way you could satisfy both it and this License would be to
+refrain entirely from distribution of the Program.
+
+If any portion of this section is held invalid or unenforceable under
+any particular circumstance, the balance of the section is intended to
+apply and the section as a whole is intended to apply in other
+circumstances.
+
+It is not the purpose of this section to induce you to infringe any
+patents or other property right claims or to contest validity of any
+such claims; this section has the sole purpose of protecting the
+integrity of the free software distribution system, which is
+implemented by public license practices.  Many people have made
+generous contributions to the wide range of software distributed
+through that system in reliance on consistent application of that
+system; it is up to the author/donor to decide if he or she is willing
+to distribute software through any other system and a licensee cannot
+impose that choice.
+
+This section is intended to make thoroughly clear what is believed to
+be a consequence of the rest of this License.
+
+  8. If the distribution and/or use of the Program is restricted in
+certain countries either by patents or by copyrighted interfaces, the
+original copyright holder who places the Program under this License
+may add an explicit geographical distribution limitation excluding
+those countries, so that distribution is permitted only in or among
+countries not thus excluded.  In such case, this License incorporates
+the limitation as if written in the body of this License.
+
+  9. The Free Software Foundation may publish revised and/or new versions
+of the General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+Each version is given a distinguishing version number.  If the Program
+specifies a version number of this License which applies to it and "any
+later version", you have the option of following the terms and conditions
+either of that version or of any later version published by the Free
+Software Foundation.  If the Program does not specify a version number of
+this License, you may choose any version ever published by the Free Software
+Foundation.
+
+  10. If you wish to incorporate parts of the Program into other free
+programs whose distribution conditions are different, write to the author
+to ask for permission.  For software which is copyrighted by the Free
+Software Foundation, write to the Free Software Foundation; we sometimes
+make exceptions for this.  Our decision will be guided by the two goals
+of preserving the free status of all derivatives of our free software and
+of promoting the sharing and reuse of software generally.
+
+                           NO WARRANTY
+
+  11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
+FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
+OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
+PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
+OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
+TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
+PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
+REPAIR OR CORRECTION.
+
+  12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
+REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
+INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
+OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
+TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
+YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
+PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGES.
+
+                    END OF TERMS AND CONDITIONS
+
+           How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+convey the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software; you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation; either version 2 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License along
+    with this program; if not, write to the Free Software Foundation, Inc.,
+    51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+Also add information on how to contact you by electronic and paper mail.
+
+If the program is interactive, make it output a short notice like this
+when it starts in an interactive mode:
+
+    Gnomovision version 69, Copyright (C) year name of author
+    Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+    This is free software, and you are welcome to redistribute it
+    under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License.  Of course, the commands you use may
+be called something other than `show w' and `show c'; they could even be
+mouse-clicks or menu items--whatever suits your program.
+
+You should also get your employer (if you work as a programmer) or your
+school, if any, to sign a "copyright disclaimer" for the program, if
+necessary.  Here is a sample; alter the names:
+
+  Yoyodyne, Inc., hereby disclaims all copyright interest in the program
+  `Gnomovision' (which makes passes at compilers) written by James Hacker.
+
+  <signature of Ty Coon>, 1 April 1989
+  Ty Coon, President of Vice
+
+This General Public License does not permit incorporating your program into
+proprietary programs.  If your program is a subroutine library, you may
+consider it more useful to permit linking proprietary applications with the
+library.  If this is what you want to do, use the GNU Lesser General
+Public License instead of this License.
diff --git a/COPYING.GPLv3 b/COPYING.GPLv3
new file mode 100644 (file)
index 0000000..94a9ed0
--- /dev/null
@@ -0,0 +1,674 @@
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU General Public License is a free, copyleft license for
+software and other kinds of works.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+the GNU General Public License is intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.  We, the Free Software Foundation, use the
+GNU General Public License for most of our software; it applies also to
+any other work released this way by its authors.  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+  To protect your rights, we need to prevent others from denying you
+these rights or asking you to surrender the rights.  Therefore, you have
+certain responsibilities if you distribute copies of the software, or if
+you modify it: responsibilities to respect the freedom of others.
+
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must pass on to the recipients the same
+freedoms that you received.  You must make sure that they, too, receive
+or can get the source code.  And you must show them these terms so they
+know their rights.
+
+  Developers that use the GNU GPL protect your rights with two steps:
+(1) assert copyright on the software, and (2) offer you this License
+giving you legal permission to copy, distribute and/or modify it.
+
+  For the developers' and authors' protection, the GPL clearly explains
+that there is no warranty for this free software.  For both users' and
+authors' sake, the GPL requires that modified versions be marked as
+changed, so that their problems will not be attributed erroneously to
+authors of previous versions.
+
+  Some devices are designed to deny users access to install or run
+modified versions of the software inside them, although the manufacturer
+can do so.  This is fundamentally incompatible with the aim of
+protecting users' freedom to change the software.  The systematic
+pattern of such abuse occurs in the area of products for individuals to
+use, which is precisely where it is most unacceptable.  Therefore, we
+have designed this version of the GPL to prohibit the practice for those
+products.  If such problems arise substantially in other domains, we
+stand ready to extend this provision to those domains in future versions
+of the GPL, as needed to protect the freedom of users.
+
+  Finally, every program is threatened constantly by software patents.
+States should not allow patents to restrict development and use of
+software on general-purpose computers, but in those that do, we wish to
+avoid the special danger that patents applied to a free program could
+make it effectively proprietary.  To prevent this, the GPL assures that
+patents cannot be used to render the program non-free.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                       TERMS AND CONDITIONS
+
+  0. Definitions.
+
+  "This License" refers to version 3 of the GNU General Public License.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+  "The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+  To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+  A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+  To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+  To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+  An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+  1. Source Code.
+
+  The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
+
+  A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+  The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+  The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+  The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+  The Corresponding Source for a work in source code form is that
+same work.
+
+  2. Basic Permissions.
+
+  All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+  You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force.  You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright.  Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+  Conveying under any other circumstances is permitted solely under
+the conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+  No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+  When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+  4. Conveying Verbatim Copies.
+
+  You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+  You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+  5. Conveying Modified Source Versions.
+
+  You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+    a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+
+    b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under section
+    7.  This requirement modifies the requirement in section 4 to
+    "keep intact all notices".
+
+    c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy.  This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged.  This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+
+    d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+  A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit.  Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+  6. Conveying Non-Source Forms.
+
+  You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+    a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+
+    b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for as
+    long as you offer spare parts or customer support for that product
+    model, to give anyone who possesses the object code either (1) a
+    copy of the Corresponding Source for all the software in the
+    product that is covered by this License, on a durable physical
+    medium customarily used for software interchange, for a price no
+    more than your reasonable cost of physically performing this
+    conveying of source, or (2) access to copy the
+    Corresponding Source from a network server at no charge.
+
+    c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source.  This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in accord
+    with subsection 6b.
+
+    d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to the
+    Corresponding Source in the same way through the same place at no
+    further charge.  You need not require recipients to copy the
+    Corresponding Source along with the object code.  If the place to
+    copy the object code is a network server, the Corresponding Source
+    may be on a different server (operated by you or a third party)
+    that supports equivalent copying facilities, provided you maintain
+    clear directions next to the object code saying where to find the
+    Corresponding Source.  Regardless of what server hosts the
+    Corresponding Source, you remain obligated to ensure that it is
+    available for as long as needed to satisfy these requirements.
+
+    e) Convey the object code using peer-to-peer transmission, provided
+    you inform other peers where the object code and Corresponding
+    Source of the work are being offered to the general public at no
+    charge under subsection 6d.
+
+  A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+  A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling.  In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage.  For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product.  A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+  "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source.  The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+  If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information.  But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+  The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed.  Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+  Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+  7. Additional Terms.
+
+  "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law.  If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+  When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it.  (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.)  You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+  Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+    a) Disclaiming warranty or limiting liability differently from the
+    terms of sections 15 and 16 of this License; or
+
+    b) Requiring preservation of specified reasonable legal notices or
+    author attributions in that material or in the Appropriate Legal
+    Notices displayed by works containing it; or
+
+    c) Prohibiting misrepresentation of the origin of that material, or
+    requiring that modified versions of such material be marked in
+    reasonable ways as different from the original version; or
+
+    d) Limiting the use for publicity purposes of names of licensors or
+    authors of the material; or
+
+    e) Declining to grant rights under trademark law for use of some
+    trade names, trademarks, or service marks; or
+
+    f) Requiring indemnification of licensors and authors of that
+    material by anyone who conveys the material (or modified versions of
+    it) with contractual assumptions of liability to the recipient, for
+    any liability that these contractual assumptions directly impose on
+    those licensors and authors.
+
+  All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10.  If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term.  If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+  If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+  Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+  8. Termination.
+
+  You may not propagate or modify a covered work except as expressly
+provided under this License.  Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+  However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+  Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+  Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+  9. Acceptance Not Required for Having Copies.
+
+  You are not required to accept this License in order to receive or
+run a copy of the Program.  Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance.  However,
+nothing other than this License grants you permission to propagate or
+modify any covered work.  These actions infringe copyright if you do
+not accept this License.  Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+  10. Automatic Licensing of Downstream Recipients.
+
+  Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.  You are not responsible
+for enforcing compliance by third parties with this License.
+
+  An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations.  If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+  You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License.  For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+  11. Patents.
+
+  A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.  The
+work thus licensed is called the contributor's "contributor version".
+
+  A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version.  For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+  Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+  In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement).  To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+  If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients.  "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+  If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+  A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License.  You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+  Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+  12. No Surrender of Others' Freedom.
+
+  If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all.  For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+  13. Use with the GNU Affero General Public License.
+
+  Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU Affero General Public License into a single
+combined work, and to convey the resulting work.  The terms of this
+License will continue to apply to the part which is the covered work,
+but the special requirements of the GNU Affero General Public License,
+section 13, concerning interaction through a network will apply to the
+combination as such.
+
+  14. Revised Versions of this License.
+
+  The Free Software Foundation may publish revised and/or new versions of
+the GNU General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+  Each version is given a distinguishing version number.  If the
+Program specifies that a certain numbered version of the GNU General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation.  If the Program does not specify a version number of the
+GNU General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+  If the Program specifies that a proxy can decide which future
+versions of the GNU General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+  Later license versions may give you additional or different
+permissions.  However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+  15. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+  17. Interpretation of Sections 15 and 16.
+
+  If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+  If the program does terminal interaction, make it output a short
+notice like this when it starts in an interactive mode:
+
+    <program>  Copyright (C) <year>  <name of author>
+    This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+    This is free software, and you are welcome to redistribute it
+    under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License.  Of course, your program's commands
+might be different; for a GUI interface, you would use an "about box".
+
+  You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU GPL, see
+<http://www.gnu.org/licenses/>.
+
+  The GNU General Public License does not permit incorporating your program
+into proprietary programs.  If your program is a subroutine library, you
+may consider it more useful to permit linking proprietary applications with
+the library.  If this is what you want to do, use the GNU Lesser General
+Public License instead of this License.  But first, please read
+<http://www.gnu.org/philosophy/why-not-lgpl.html>.
diff --git a/COPYING.LGPLv2.1 b/COPYING.LGPLv2.1
new file mode 100644 (file)
index 0000000..5ab7695
--- /dev/null
@@ -0,0 +1,504 @@
+                 GNU LESSER GENERAL PUBLIC LICENSE
+                      Version 2.1, February 1999
+
+ Copyright (C) 1991, 1999 Free Software Foundation, Inc.
+ 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+[This is the first released version of the Lesser GPL.  It also counts
+ as the successor of the GNU Library Public License, version 2, hence
+ the version number 2.1.]
+
+                           Preamble
+
+  The licenses for most software are designed to take away your
+freedom to share and change it.  By contrast, the GNU General Public
+Licenses are intended to guarantee your freedom to share and change
+free software--to make sure the software is free for all its users.
+
+  This license, the Lesser General Public License, applies to some
+specially designated software packages--typically libraries--of the
+Free Software Foundation and other authors who decide to use it.  You
+can use it too, but we suggest you first think carefully about whether
+this license or the ordinary General Public License is the better
+strategy to use in any particular case, based on the explanations below.
+
+  When we speak of free software, we are referring to freedom of use,
+not price.  Our General Public Licenses are designed to make sure that
+you have the freedom to distribute copies of free software (and charge
+for this service if you wish); that you receive source code or can get
+it if you want it; that you can change the software and use pieces of
+it in new free programs; and that you are informed that you can do
+these things.
+
+  To protect your rights, we need to make restrictions that forbid
+distributors to deny you these rights or to ask you to surrender these
+rights.  These restrictions translate to certain responsibilities for
+you if you distribute copies of the library or if you modify it.
+
+  For example, if you distribute copies of the library, whether gratis
+or for a fee, you must give the recipients all the rights that we gave
+you.  You must make sure that they, too, receive or can get the source
+code.  If you link other code with the library, you must provide
+complete object files to the recipients, so that they can relink them
+with the library after making changes to the library and recompiling
+it.  And you must show them these terms so they know their rights.
+
+  We protect your rights with a two-step method: (1) we copyright the
+library, and (2) we offer you this license, which gives you legal
+permission to copy, distribute and/or modify the library.
+
+  To protect each distributor, we want to make it very clear that
+there is no warranty for the free library.  Also, if the library is
+modified by someone else and passed on, the recipients should know
+that what they have is not the original version, so that the original
+author's reputation will not be affected by problems that might be
+introduced by others.
+\f
+  Finally, software patents pose a constant threat to the existence of
+any free program.  We wish to make sure that a company cannot
+effectively restrict the users of a free program by obtaining a
+restrictive license from a patent holder.  Therefore, we insist that
+any patent license obtained for a version of the library must be
+consistent with the full freedom of use specified in this license.
+
+  Most GNU software, including some libraries, is covered by the
+ordinary GNU General Public License.  This license, the GNU Lesser
+General Public License, applies to certain designated libraries, and
+is quite different from the ordinary General Public License.  We use
+this license for certain libraries in order to permit linking those
+libraries into non-free programs.
+
+  When a program is linked with a library, whether statically or using
+a shared library, the combination of the two is legally speaking a
+combined work, a derivative of the original library.  The ordinary
+General Public License therefore permits such linking only if the
+entire combination fits its criteria of freedom.  The Lesser General
+Public License permits more lax criteria for linking other code with
+the library.
+
+  We call this license the "Lesser" General Public License because it
+does Less to protect the user's freedom than the ordinary General
+Public License.  It also provides other free software developers Less
+of an advantage over competing non-free programs.  These disadvantages
+are the reason we use the ordinary General Public License for many
+libraries.  However, the Lesser license provides advantages in certain
+special circumstances.
+
+  For example, on rare occasions, there may be a special need to
+encourage the widest possible use of a certain library, so that it becomes
+a de-facto standard.  To achieve this, non-free programs must be
+allowed to use the library.  A more frequent case is that a free
+library does the same job as widely used non-free libraries.  In this
+case, there is little to gain by limiting the free library to free
+software only, so we use the Lesser General Public License.
+
+  In other cases, permission to use a particular library in non-free
+programs enables a greater number of people to use a large body of
+free software.  For example, permission to use the GNU C Library in
+non-free programs enables many more people to use the whole GNU
+operating system, as well as its variant, the GNU/Linux operating
+system.
+
+  Although the Lesser General Public License is Less protective of the
+users' freedom, it does ensure that the user of a program that is
+linked with the Library has the freedom and the wherewithal to run
+that program using a modified version of the Library.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.  Pay close attention to the difference between a
+"work based on the library" and a "work that uses the library".  The
+former contains code derived from the library, whereas the latter must
+be combined with the library in order to run.
+\f
+                 GNU LESSER GENERAL PUBLIC LICENSE
+   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+  0. This License Agreement applies to any software library or other
+program which contains a notice placed by the copyright holder or
+other authorized party saying it may be distributed under the terms of
+this Lesser General Public License (also called "this License").
+Each licensee is addressed as "you".
+
+  A "library" means a collection of software functions and/or data
+prepared so as to be conveniently linked with application programs
+(which use some of those functions and data) to form executables.
+
+  The "Library", below, refers to any such software library or work
+which has been distributed under these terms.  A "work based on the
+Library" means either the Library or any derivative work under
+copyright law: that is to say, a work containing the Library or a
+portion of it, either verbatim or with modifications and/or translated
+straightforwardly into another language.  (Hereinafter, translation is
+included without limitation in the term "modification".)
+
+  "Source code" for a work means the preferred form of the work for
+making modifications to it.  For a library, complete source code means
+all the source code for all modules it contains, plus any associated
+interface definition files, plus the scripts used to control compilation
+and installation of the library.
+
+  Activities other than copying, distribution and modification are not
+covered by this License; they are outside its scope.  The act of
+running a program using the Library is not restricted, and output from
+such a program is covered only if its contents constitute a work based
+on the Library (independent of the use of the Library in a tool for
+writing it).  Whether that is true depends on what the Library does
+and what the program that uses the Library does.
+  
+  1. You may copy and distribute verbatim copies of the Library's
+complete source code as you receive it, in any medium, provided that
+you conspicuously and appropriately publish on each copy an
+appropriate copyright notice and disclaimer of warranty; keep intact
+all the notices that refer to this License and to the absence of any
+warranty; and distribute a copy of this License along with the
+Library.
+
+  You may charge a fee for the physical act of transferring a copy,
+and you may at your option offer warranty protection in exchange for a
+fee.
+\f
+  2. You may modify your copy or copies of the Library or any portion
+of it, thus forming a work based on the Library, and copy and
+distribute such modifications or work under the terms of Section 1
+above, provided that you also meet all of these conditions:
+
+    a) The modified work must itself be a software library.
+
+    b) You must cause the files modified to carry prominent notices
+    stating that you changed the files and the date of any change.
+
+    c) You must cause the whole of the work to be licensed at no
+    charge to all third parties under the terms of this License.
+
+    d) If a facility in the modified Library refers to a function or a
+    table of data to be supplied by an application program that uses
+    the facility, other than as an argument passed when the facility
+    is invoked, then you must make a good faith effort to ensure that,
+    in the event an application does not supply such function or
+    table, the facility still operates, and performs whatever part of
+    its purpose remains meaningful.
+
+    (For example, a function in a library to compute square roots has
+    a purpose that is entirely well-defined independent of the
+    application.  Therefore, Subsection 2d requires that any
+    application-supplied function or table used by this function must
+    be optional: if the application does not supply it, the square
+    root function must still compute square roots.)
+
+These requirements apply to the modified work as a whole.  If
+identifiable sections of that work are not derived from the Library,
+and can be reasonably considered independent and separate works in
+themselves, then this License, and its terms, do not apply to those
+sections when you distribute them as separate works.  But when you
+distribute the same sections as part of a whole which is a work based
+on the Library, the distribution of the whole must be on the terms of
+this License, whose permissions for other licensees extend to the
+entire whole, and thus to each and every part regardless of who wrote
+it.
+
+Thus, it is not the intent of this section to claim rights or contest
+your rights to work written entirely by you; rather, the intent is to
+exercise the right to control the distribution of derivative or
+collective works based on the Library.
+
+In addition, mere aggregation of another work not based on the Library
+with the Library (or with a work based on the Library) on a volume of
+a storage or distribution medium does not bring the other work under
+the scope of this License.
+
+  3. You may opt to apply the terms of the ordinary GNU General Public
+License instead of this License to a given copy of the Library.  To do
+this, you must alter all the notices that refer to this License, so
+that they refer to the ordinary GNU General Public License, version 2,
+instead of to this License.  (If a newer version than version 2 of the
+ordinary GNU General Public License has appeared, then you can specify
+that version instead if you wish.)  Do not make any other change in
+these notices.
+\f
+  Once this change is made in a given copy, it is irreversible for
+that copy, so the ordinary GNU General Public License applies to all
+subsequent copies and derivative works made from that copy.
+
+  This option is useful when you wish to copy part of the code of
+the Library into a program that is not a library.
+
+  4. You may copy and distribute the Library (or a portion or
+derivative of it, under Section 2) in object code or executable form
+under the terms of Sections 1 and 2 above provided that you accompany
+it with the complete corresponding machine-readable source code, which
+must be distributed under the terms of Sections 1 and 2 above on a
+medium customarily used for software interchange.
+
+  If distribution of object code is made by offering access to copy
+from a designated place, then offering equivalent access to copy the
+source code from the same place satisfies the requirement to
+distribute the source code, even though third parties are not
+compelled to copy the source along with the object code.
+
+  5. A program that contains no derivative of any portion of the
+Library, but is designed to work with the Library by being compiled or
+linked with it, is called a "work that uses the Library".  Such a
+work, in isolation, is not a derivative work of the Library, and
+therefore falls outside the scope of this License.
+
+  However, linking a "work that uses the Library" with the Library
+creates an executable that is a derivative of the Library (because it
+contains portions of the Library), rather than a "work that uses the
+library".  The executable is therefore covered by this License.
+Section 6 states terms for distribution of such executables.
+
+  When a "work that uses the Library" uses material from a header file
+that is part of the Library, the object code for the work may be a
+derivative work of the Library even though the source code is not.
+Whether this is true is especially significant if the work can be
+linked without the Library, or if the work is itself a library.  The
+threshold for this to be true is not precisely defined by law.
+
+  If such an object file uses only numerical parameters, data
+structure layouts and accessors, and small macros and small inline
+functions (ten lines or less in length), then the use of the object
+file is unrestricted, regardless of whether it is legally a derivative
+work.  (Executables containing this object code plus portions of the
+Library will still fall under Section 6.)
+
+  Otherwise, if the work is a derivative of the Library, you may
+distribute the object code for the work under the terms of Section 6.
+Any executables containing that work also fall under Section 6,
+whether or not they are linked directly with the Library itself.
+\f
+  6. As an exception to the Sections above, you may also combine or
+link a "work that uses the Library" with the Library to produce a
+work containing portions of the Library, and distribute that work
+under terms of your choice, provided that the terms permit
+modification of the work for the customer's own use and reverse
+engineering for debugging such modifications.
+
+  You must give prominent notice with each copy of the work that the
+Library is used in it and that the Library and its use are covered by
+this License.  You must supply a copy of this License.  If the work
+during execution displays copyright notices, you must include the
+copyright notice for the Library among them, as well as a reference
+directing the user to the copy of this License.  Also, you must do one
+of these things:
+
+    a) Accompany the work with the complete corresponding
+    machine-readable source code for the Library including whatever
+    changes were used in the work (which must be distributed under
+    Sections 1 and 2 above); and, if the work is an executable linked
+    with the Library, with the complete machine-readable "work that
+    uses the Library", as object code and/or source code, so that the
+    user can modify the Library and then relink to produce a modified
+    executable containing the modified Library.  (It is understood
+    that the user who changes the contents of definitions files in the
+    Library will not necessarily be able to recompile the application
+    to use the modified definitions.)
+
+    b) Use a suitable shared library mechanism for linking with the
+    Library.  A suitable mechanism is one that (1) uses at run time a
+    copy of the library already present on the user's computer system,
+    rather than copying library functions into the executable, and (2)
+    will operate properly with a modified version of the library, if
+    the user installs one, as long as the modified version is
+    interface-compatible with the version that the work was made with.
+
+    c) Accompany the work with a written offer, valid for at
+    least three years, to give the same user the materials
+    specified in Subsection 6a, above, for a charge no more
+    than the cost of performing this distribution.
+
+    d) If distribution of the work is made by offering access to copy
+    from a designated place, offer equivalent access to copy the above
+    specified materials from the same place.
+
+    e) Verify that the user has already received a copy of these
+    materials or that you have already sent this user a copy.
+
+  For an executable, the required form of the "work that uses the
+Library" must include any data and utility programs needed for
+reproducing the executable from it.  However, as a special exception,
+the materials to be distributed need not include anything that is
+normally distributed (in either source or binary form) with the major
+components (compiler, kernel, and so on) of the operating system on
+which the executable runs, unless that component itself accompanies
+the executable.
+
+  It may happen that this requirement contradicts the license
+restrictions of other proprietary libraries that do not normally
+accompany the operating system.  Such a contradiction means you cannot
+use both them and the Library together in an executable that you
+distribute.
+\f
+  7. You may place library facilities that are a work based on the
+Library side-by-side in a single library together with other library
+facilities not covered by this License, and distribute such a combined
+library, provided that the separate distribution of the work based on
+the Library and of the other library facilities is otherwise
+permitted, and provided that you do these two things:
+
+    a) Accompany the combined library with a copy of the same work
+    based on the Library, uncombined with any other library
+    facilities.  This must be distributed under the terms of the
+    Sections above.
+
+    b) Give prominent notice with the combined library of the fact
+    that part of it is a work based on the Library, and explaining
+    where to find the accompanying uncombined form of the same work.
+
+  8. You may not copy, modify, sublicense, link with, or distribute
+the Library except as expressly provided under this License.  Any
+attempt otherwise to copy, modify, sublicense, link with, or
+distribute the Library is void, and will automatically terminate your
+rights under this License.  However, parties who have received copies,
+or rights, from you under this License will not have their licenses
+terminated so long as such parties remain in full compliance.
+
+  9. You are not required to accept this License, since you have not
+signed it.  However, nothing else grants you permission to modify or
+distribute the Library or its derivative works.  These actions are
+prohibited by law if you do not accept this License.  Therefore, by
+modifying or distributing the Library (or any work based on the
+Library), you indicate your acceptance of this License to do so, and
+all its terms and conditions for copying, distributing or modifying
+the Library or works based on it.
+
+  10. Each time you redistribute the Library (or any work based on the
+Library), the recipient automatically receives a license from the
+original licensor to copy, distribute, link with or modify the Library
+subject to these terms and conditions.  You may not impose any further
+restrictions on the recipients' exercise of the rights granted herein.
+You are not responsible for enforcing compliance by third parties with
+this License.
+\f
+  11. If, as a consequence of a court judgment or allegation of patent
+infringement or for any other reason (not limited to patent issues),
+conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot
+distribute so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you
+may not distribute the Library at all.  For example, if a patent
+license would not permit royalty-free redistribution of the Library by
+all those who receive copies directly or indirectly through you, then
+the only way you could satisfy both it and this License would be to
+refrain entirely from distribution of the Library.
+
+If any portion of this section is held invalid or unenforceable under any
+particular circumstance, the balance of the section is intended to apply,
+and the section as a whole is intended to apply in other circumstances.
+
+It is not the purpose of this section to induce you to infringe any
+patents or other property right claims or to contest validity of any
+such claims; this section has the sole purpose of protecting the
+integrity of the free software distribution system which is
+implemented by public license practices.  Many people have made
+generous contributions to the wide range of software distributed
+through that system in reliance on consistent application of that
+system; it is up to the author/donor to decide if he or she is willing
+to distribute software through any other system and a licensee cannot
+impose that choice.
+
+This section is intended to make thoroughly clear what is believed to
+be a consequence of the rest of this License.
+
+  12. If the distribution and/or use of the Library is restricted in
+certain countries either by patents or by copyrighted interfaces, the
+original copyright holder who places the Library under this License may add
+an explicit geographical distribution limitation excluding those countries,
+so that distribution is permitted only in or among countries not thus
+excluded.  In such case, this License incorporates the limitation as if
+written in the body of this License.
+
+  13. The Free Software Foundation may publish revised and/or new
+versions of the Lesser General Public License from time to time.
+Such new versions will be similar in spirit to the present version,
+but may differ in detail to address new problems or concerns.
+
+Each version is given a distinguishing version number.  If the Library
+specifies a version number of this License which applies to it and
+"any later version", you have the option of following the terms and
+conditions either of that version or of any later version published by
+the Free Software Foundation.  If the Library does not specify a
+license version number, you may choose any version ever published by
+the Free Software Foundation.
+\f
+  14. If you wish to incorporate parts of the Library into other free
+programs whose distribution conditions are incompatible with these,
+write to the author to ask for permission.  For software which is
+copyrighted by the Free Software Foundation, write to the Free
+Software Foundation; we sometimes make exceptions for this.  Our
+decision will be guided by the two goals of preserving the free status
+of all derivatives of our free software and of promoting the sharing
+and reuse of software generally.
+
+                           NO WARRANTY
+
+  15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO
+WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
+EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
+OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY
+KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
+LIBRARY IS WITH YOU.  SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME
+THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
+WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
+AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU
+FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
+CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
+LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
+RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
+FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
+SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
+DAMAGES.
+
+                    END OF TERMS AND CONDITIONS
+\f
+           How to Apply These Terms to Your New Libraries
+
+  If you develop a new library, and you want it to be of the greatest
+possible use to the public, we recommend making it free software that
+everyone can redistribute and change.  You can do so by permitting
+redistribution under these terms (or, alternatively, under the terms of the
+ordinary General Public License).
+
+  To apply these terms, attach the following notices to the library.  It is
+safest to attach them to the start of each source file to most effectively
+convey the exclusion of warranty; and each file should have at least the
+"copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the library's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This library is free software; you can redistribute it and/or
+    modify it under the terms of the GNU Lesser General Public
+    License as published by the Free Software Foundation; either
+    version 2.1 of the License, or (at your option) any later version.
+
+    This library is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+    Lesser General Public License for more details.
+
+    You should have received a copy of the GNU Lesser General Public
+    License along with this library; if not, write to the Free Software
+    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
+
+Also add information on how to contact you by electronic and paper mail.
+
+You should also get your employer (if you work as a programmer) or your
+school, if any, to sign a "copyright disclaimer" for the library, if
+necessary.  Here is a sample; alter the names:
+
+  Yoyodyne, Inc., hereby disclaims all copyright interest in the
+  library `Frob' (a library for tweaking knobs) written by James Random Hacker.
+
+  <signature of Ty Coon>, 1 April 1990
+  Ty Coon, President of Vice
+
+That's all there is to it!
+
+
diff --git a/ChangeLog b/ChangeLog
new file mode 100644 (file)
index 0000000..c6de9ba
--- /dev/null
+++ b/ChangeLog
@@ -0,0 +1,2 @@
+See the commit log in the git repository:
+git://ctrl.tukaani.org/lzma-utils.git
diff --git a/Doxyfile.in b/Doxyfile.in
new file mode 100644 (file)
index 0000000..8ca611b
--- /dev/null
@@ -0,0 +1,1229 @@
+# Doxyfile 1.4.7
+
+# This file describes the settings to be used by the documentation system
+# doxygen (www.doxygen.org) for a project
+#
+# All text after a hash (#) is considered a comment and will be ignored
+# The format is:
+#       TAG = value [value, ...]
+# For lists items can also be appended using:
+#       TAG += value [value, ...]
+# Values that contain spaces should be placed between quotes (" ")
+
+#---------------------------------------------------------------------------
+# Project related configuration options
+#---------------------------------------------------------------------------
+
+# The PROJECT_NAME tag is a single word (or a sequence of words surrounded
+# by quotes) that should identify the project.
+
+PROJECT_NAME           = "@PACKAGE_NAME@"
+
+# The PROJECT_NUMBER tag can be used to enter a project or revision number.
+# This could be handy for archiving the generated documentation or
+# if some version control system is used.
+
+PROJECT_NUMBER         = "@PACKAGE_VERSION@"
+
+# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute)
+# base path where the generated documentation will be put.
+# If a relative path is entered, it will be relative to the location
+# where doxygen was started. If left blank the current directory will be used.
+
+OUTPUT_DIRECTORY       = doc
+
+# If the CREATE_SUBDIRS tag is set to YES, then doxygen will create
+# 4096 sub-directories (in 2 levels) under the output directory of each output
+# format and will distribute the generated files over these directories.
+# Enabling this option can be useful when feeding doxygen a huge amount of
+# source files, where putting all generated files in the same directory would
+# otherwise cause performance problems for the file system.
+
+CREATE_SUBDIRS         = NO
+
+# The OUTPUT_LANGUAGE tag is used to specify the language in which all
+# documentation generated by doxygen is written. Doxygen will use this
+# information to generate all constant output in the proper language.
+# The default language is English, other supported languages are:
+# Brazilian, Catalan, Chinese, Chinese-Traditional, Croatian, Czech, Danish,
+# Dutch, Finnish, French, German, Greek, Hungarian, Italian, Japanese,
+# Japanese-en (Japanese with English messages), Korean, Korean-en, Norwegian,
+# Polish, Portuguese, Romanian, Russian, Serbian, Slovak, Slovene, Spanish,
+# Swedish, and Ukrainian.
+
+OUTPUT_LANGUAGE        = English
+
+# This tag can be used to specify the encoding used in the generated output.
+# The encoding is not always determined by the language that is chosen,
+# but also whether or not the output is meant for Windows or non-Windows users.
+# In case there is a difference, setting the USE_WINDOWS_ENCODING tag to YES
+# forces the Windows encoding (this is the default for the Windows binary),
+# whereas setting the tag to NO uses a Unix-style encoding (the default for
+# all platforms other than Windows).
+
+USE_WINDOWS_ENCODING   = NO
+
+# If the BRIEF_MEMBER_DESC tag is set to YES (the default) Doxygen will
+# include brief member descriptions after the members that are listed in
+# the file and class documentation (similar to JavaDoc).
+# Set to NO to disable this.
+
+BRIEF_MEMBER_DESC      = YES
+
+# If the REPEAT_BRIEF tag is set to YES (the default) Doxygen will prepend
+# the brief description of a member or function before the detailed description.
+# Note: if both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the
+# brief descriptions will be completely suppressed.
+
+REPEAT_BRIEF           = YES
+
+# This tag implements a quasi-intelligent brief description abbreviator
+# that is used to form the text in various listings. Each string
+# in this list, if found as the leading text of the brief description, will be
+# stripped from the text and the result after processing the whole list, is
+# used as the annotated text. Otherwise, the brief description is used as-is.
+# If left blank, the following values are used ("$name" is automatically
+# replaced with the name of the entity): "The $name class" "The $name widget"
+# "The $name file" "is" "provides" "specifies" "contains"
+# "represents" "a" "an" "the"
+
+ABBREVIATE_BRIEF       =
+
+# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then
+# Doxygen will generate a detailed section even if there is only a brief
+# description.
+
+ALWAYS_DETAILED_SEC    = YES
+
+# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all
+# inherited members of a class in the documentation of that class as if those
+# members were ordinary class members. Constructors, destructors and assignment
+# operators of the base classes will not be shown.
+
+INLINE_INHERITED_MEMB  = NO
+
+# If the FULL_PATH_NAMES tag is set to YES then Doxygen will prepend the full
+# path before files name in the file list and in the header files. If set
+# to NO the shortest path that makes the file name unique will be used.
+
+FULL_PATH_NAMES        = YES
+
+# If the FULL_PATH_NAMES tag is set to YES then the STRIP_FROM_PATH tag
+# can be used to strip a user-defined part of the path. Stripping is
+# only done if one of the specified strings matches the left-hand part of
+# the path. The tag can be used to show relative paths in the file list.
+# If left blank the directory from which doxygen is run is used as the
+# path to strip.
+
+STRIP_FROM_PATH        =
+
+# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of
+# the path mentioned in the documentation of a class, which tells
+# the reader which header file to include in order to use a class.
+# If left blank only the name of the header file containing the class
+# definition is used. Otherwise one should specify the include paths that
+# are normally passed to the compiler using the -I flag.
+
+STRIP_FROM_INC_PATH    =
+
+# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter
+# (but less readable) file names. This can be useful is your file systems
+# doesn't support long names like on DOS, Mac, or CD-ROM.
+
+SHORT_NAMES            = NO
+
+# If the JAVADOC_AUTOBRIEF tag is set to YES then Doxygen
+# will interpret the first line (until the first dot) of a JavaDoc-style
+# comment as the brief description. If set to NO, the JavaDoc
+# comments will behave just like the Qt-style comments (thus requiring an
+# explicit @brief command for a brief description.
+
+JAVADOC_AUTOBRIEF      = NO
+
+# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make Doxygen
+# treat a multi-line C++ special comment block (i.e. a block of //! or ///
+# comments) as a brief description. This used to be the default behaviour.
+# The new default is to treat a multi-line C++ comment block as a detailed
+# description. Set this tag to YES if you prefer the old behaviour instead.
+
+MULTILINE_CPP_IS_BRIEF = NO
+
+# If the DETAILS_AT_TOP tag is set to YES then Doxygen
+# will output the detailed description near the top, like JavaDoc.
+# If set to NO, the detailed description appears after the member
+# documentation.
+
+DETAILS_AT_TOP         = NO
+
+# If the INHERIT_DOCS tag is set to YES (the default) then an undocumented
+# member inherits the documentation from any documented member that it
+# re-implements.
+
+INHERIT_DOCS           = YES
+
+# If the SEPARATE_MEMBER_PAGES tag is set to YES, then doxygen will produce
+# a new page for each member. If set to NO, the documentation of a member will
+# be part of the file/class/namespace that contains it.
+
+SEPARATE_MEMBER_PAGES  = NO
+
+# The TAB_SIZE tag can be used to set the number of spaces in a tab.
+# Doxygen uses this value to replace tabs by spaces in code fragments.
+
+TAB_SIZE               = 8
+
+# This tag can be used to specify a number of aliases that acts
+# as commands in the documentation. An alias has the form "name=value".
+# For example adding "sideeffect=\par Side Effects:\n" will allow you to
+# put the command \sideeffect (or @sideeffect) in the documentation, which
+# will result in a user-defined paragraph with heading "Side Effects:".
+# You can put \n's in the value part of an alias to insert newlines.
+
+ALIASES                =
+
+# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C
+# sources only. Doxygen will then generate output that is more tailored for C.
+# For instance, some of the names that are used will be different. The list
+# of all members will be omitted, etc.
+
+OPTIMIZE_OUTPUT_FOR_C  = YES
+
+# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC
+# tag is set to YES, then doxygen will reuse the documentation of the first
+# member in the group (if any) for the other members of the group. By default
+# all members of a group must be documented explicitly.
+
+DISTRIBUTE_GROUP_DOC   = NO
+
+# Set the SUBGROUPING tag to YES (the default) to allow class member groups of
+# the same type (for instance a group of public functions) to be put as a
+# subgroup of that type (e.g. under the Public Functions section). Set it to
+# NO to prevent subgrouping. Alternatively, this can be done per class using
+# the \nosubgrouping command.
+
+SUBGROUPING            = YES
+
+#---------------------------------------------------------------------------
+# Build related configuration options
+#---------------------------------------------------------------------------
+
+# If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in
+# documentation are documented, even if no documentation was available.
+# Private class members and static file members will be hidden unless
+# the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES
+
+EXTRACT_ALL            = NO
+
+# If the EXTRACT_PRIVATE tag is set to YES all private members of a class
+# will be included in the documentation.
+
+EXTRACT_PRIVATE        = YES
+
+# If the EXTRACT_STATIC tag is set to YES all static members of a file
+# will be included in the documentation.
+
+EXTRACT_STATIC         = YES
+
+# If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs)
+# defined locally in source files will be included in the documentation.
+# If set to NO only classes defined in header files are included.
+
+EXTRACT_LOCAL_CLASSES  = YES
+
+# If the HIDE_UNDOC_MEMBERS tag is set to YES, Doxygen will hide all
+# undocumented members of documented classes, files or namespaces.
+# If set to NO (the default) these members will be included in the
+# various overviews, but no documentation section is generated.
+# This option has no effect if EXTRACT_ALL is enabled.
+
+HIDE_UNDOC_MEMBERS     = NO
+
+# If the HIDE_UNDOC_CLASSES tag is set to YES, Doxygen will hide all
+# undocumented classes that are normally visible in the class hierarchy.
+# If set to NO (the default) these classes will be included in the various
+# overviews. This option has no effect if EXTRACT_ALL is enabled.
+
+HIDE_UNDOC_CLASSES     = NO
+
+# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, Doxygen will hide all
+# friend (class|struct|union) declarations.
+# If set to NO (the default) these declarations will be included in the
+# documentation.
+
+HIDE_FRIEND_COMPOUNDS  = NO
+
+# If the HIDE_IN_BODY_DOCS tag is set to YES, Doxygen will hide any
+# documentation blocks found inside the body of a function.
+# If set to NO (the default) these blocks will be appended to the
+# function's detailed documentation block.
+
+HIDE_IN_BODY_DOCS      = NO
+
+# The INTERNAL_DOCS tag determines if documentation
+# that is typed after a \internal command is included. If the tag is set
+# to NO (the default) then the documentation will be excluded.
+# Set it to YES to include the internal documentation.
+
+INTERNAL_DOCS          = NO
+
+# If the CASE_SENSE_NAMES tag is set to NO then Doxygen will only generate
+# file names in lower-case letters. If set to YES upper-case letters are also
+# allowed. This is useful if you have classes or files whose names only differ
+# in case and if your file system supports case sensitive file names. Windows
+# and Mac users are advised to set this option to NO.
+
+CASE_SENSE_NAMES       = YES
+
+# If the HIDE_SCOPE_NAMES tag is set to NO (the default) then Doxygen
+# will show members with their full class and namespace scopes in the
+# documentation. If set to YES the scope will be hidden.
+
+HIDE_SCOPE_NAMES       = NO
+
+# If the SHOW_INCLUDE_FILES tag is set to YES (the default) then Doxygen
+# will put a list of the files that are included by a file in the documentation
+# of that file.
+
+SHOW_INCLUDE_FILES     = YES
+
+# If the INLINE_INFO tag is set to YES (the default) then a tag [inline]
+# is inserted in the documentation for inline members.
+
+INLINE_INFO            = YES
+
+# If the SORT_MEMBER_DOCS tag is set to YES (the default) then doxygen
+# will sort the (detailed) documentation of file and class members
+# alphabetically by member name. If set to NO the members will appear in
+# declaration order.
+
+SORT_MEMBER_DOCS       = NO
+
+# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the
+# brief documentation of file, namespace and class members alphabetically
+# by member name. If set to NO (the default) the members will appear in
+# declaration order.
+
+SORT_BRIEF_DOCS        = NO
+
+# If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be
+# sorted by fully-qualified names, including namespaces. If set to
+# NO (the default), the class list will be sorted only by class name,
+# not including the namespace part.
+# Note: This option is not very useful if HIDE_SCOPE_NAMES is set to YES.
+# Note: This option applies only to the class list, not to the
+# alphabetical list.
+
+SORT_BY_SCOPE_NAME     = NO
+
+# The GENERATE_TODOLIST tag can be used to enable (YES) or
+# disable (NO) the todo list. This list is created by putting \todo
+# commands in the documentation.
+
+GENERATE_TODOLIST      = YES
+
+# The GENERATE_TESTLIST tag can be used to enable (YES) or
+# disable (NO) the test list. This list is created by putting \test
+# commands in the documentation.
+
+GENERATE_TESTLIST      = YES
+
+# The GENERATE_BUGLIST tag can be used to enable (YES) or
+# disable (NO) the bug list. This list is created by putting \bug
+# commands in the documentation.
+
+GENERATE_BUGLIST       = YES
+
+# The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or
+# disable (NO) the deprecated list. This list is created by putting
+# \deprecated commands in the documentation.
+
+GENERATE_DEPRECATEDLIST= YES
+
+# The ENABLED_SECTIONS tag can be used to enable conditional
+# documentation sections, marked by \if sectionname ... \endif.
+
+ENABLED_SECTIONS       =
+
+# The MAX_INITIALIZER_LINES tag determines the maximum number of lines
+# the initial value of a variable or define consists of for it to appear in
+# the documentation. If the initializer consists of more lines than specified
+# here it will be hidden. Use a value of 0 to hide initializers completely.
+# The appearance of the initializer of individual variables and defines in the
+# documentation can be controlled using \showinitializer or \hideinitializer
+# command in the documentation regardless of this setting.
+
+MAX_INITIALIZER_LINES  = 30
+
+# Set the SHOW_USED_FILES tag to NO to disable the list of files generated
+# at the bottom of the documentation of classes and structs. If set to YES the
+# list will mention the files that were used to generate the documentation.
+
+SHOW_USED_FILES        = YES
+
+# If the sources in your project are distributed over multiple directories
+# then setting the SHOW_DIRECTORIES tag to YES will show the directory hierarchy
+# in the documentation. The default is NO.
+
+SHOW_DIRECTORIES       = NO
+
+# The FILE_VERSION_FILTER tag can be used to specify a program or script that
+# doxygen should invoke to get the current version for each file (typically from the
+# version control system). Doxygen will invoke the program by executing (via
+# popen()) the command <command> <input-file>, where <command> is the value of
+# the FILE_VERSION_FILTER tag, and <input-file> is the name of an input file
+# provided by doxygen. Whatever the program writes to standard output
+# is used as the file version. See the manual for examples.
+
+FILE_VERSION_FILTER    =
+
+#---------------------------------------------------------------------------
+# configuration options related to warning and progress messages
+#---------------------------------------------------------------------------
+
+# The QUIET tag can be used to turn on/off the messages that are generated
+# by doxygen. Possible values are YES and NO. If left blank NO is used.
+
+QUIET                  = NO
+
+# The WARNINGS tag can be used to turn on/off the warning messages that are
+# generated by doxygen. Possible values are YES and NO. If left blank
+# NO is used.
+
+WARNINGS               = YES
+
+# If WARN_IF_UNDOCUMENTED is set to YES, then doxygen will generate warnings
+# for undocumented members. If EXTRACT_ALL is set to YES then this flag will
+# automatically be disabled.
+
+WARN_IF_UNDOCUMENTED   = YES
+
+# If WARN_IF_DOC_ERROR is set to YES, doxygen will generate warnings for
+# potential errors in the documentation, such as not documenting some
+# parameters in a documented function, or documenting parameters that
+# don't exist or using markup commands wrongly.
+
+WARN_IF_DOC_ERROR      = YES
+
+# This WARN_NO_PARAMDOC option can be abled to get warnings for
+# functions that are documented, but have no documentation for their parameters
+# or return value. If set to NO (the default) doxygen will only warn about
+# wrong or incomplete parameter documentation, but not about the absence of
+# documentation.
+
+WARN_NO_PARAMDOC       = NO
+
+# The WARN_FORMAT tag determines the format of the warning messages that
+# doxygen can produce. The string should contain the $file, $line, and $text
+# tags, which will be replaced by the file and line number from which the
+# warning originated and the warning text. Optionally the format may contain
+# $version, which will be replaced by the version of the file (if it could
+# be obtained via FILE_VERSION_FILTER)
+
+WARN_FORMAT            = "$file:$line: $text"
+
+# The WARN_LOGFILE tag can be used to specify a file to which warning
+# and error messages should be written. If left blank the output is written
+# to stderr.
+
+WARN_LOGFILE           =
+
+#---------------------------------------------------------------------------
+# configuration options related to the input files
+#---------------------------------------------------------------------------
+
+# The INPUT tag can be used to specify the files and/or directories that contain
+# documented source files. You may enter file names like "myfile.cpp" or
+# directories like "/usr/src/myproject". Separate the files or directories
+# with spaces.
+
+INPUT                  = @top_srcdir@/src
+
+# If the value of the INPUT tag contains directories, you can use the
+# FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp
+# and *.h) to filter out the source-files in the directories. If left
+# blank the following patterns are tested:
+# *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx
+# *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm *.py
+
+FILE_PATTERNS          = *.h *.c
+
+# The RECURSIVE tag can be used to turn specify whether or not subdirectories
+# should be searched for input files as well. Possible values are YES and NO.
+# If left blank NO is used.
+
+RECURSIVE              = YES
+
+# The EXCLUDE tag can be used to specify files and/or directories that should
+# excluded from the INPUT source files. This way you can easily exclude a
+# subdirectory from a directory tree whose root is specified with the INPUT tag.
+
+EXCLUDE                =
+
+# The EXCLUDE_SYMLINKS tag can be used select whether or not files or
+# directories that are symbolic links (a Unix filesystem feature) are excluded
+# from the input.
+
+EXCLUDE_SYMLINKS       = YES
+
+# If the value of the INPUT tag contains directories, you can use the
+# EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude
+# certain files from those directories. Note that the wildcards are matched
+# against the file with absolute path, so to exclude all test directories
+# for example use the pattern */test/*
+
+EXCLUDE_PATTERNS       =
+
+# The EXAMPLE_PATH tag can be used to specify one or more files or
+# directories that contain example code fragments that are included (see
+# the \include command).
+
+EXAMPLE_PATH           =
+
+# If the value of the EXAMPLE_PATH tag contains directories, you can use the
+# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp
+# and *.h) to filter out the source-files in the directories. If left
+# blank all files are included.
+
+EXAMPLE_PATTERNS       =
+
+# If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be
+# searched for input files to be used with the \include or \dontinclude
+# commands irrespective of the value of the RECURSIVE tag.
+# Possible values are YES and NO. If left blank NO is used.
+
+EXAMPLE_RECURSIVE      = NO
+
+# The IMAGE_PATH tag can be used to specify one or more files or
+# directories that contain image that are included in the documentation (see
+# the \image command).
+
+IMAGE_PATH             =
+
+# The INPUT_FILTER tag can be used to specify a program that doxygen should
+# invoke to filter for each input file. Doxygen will invoke the filter program
+# by executing (via popen()) the command <filter> <input-file>, where <filter>
+# is the value of the INPUT_FILTER tag, and <input-file> is the name of an
+# input file. Doxygen will then use the output that the filter program writes
+# to standard output.  If FILTER_PATTERNS is specified, this tag will be
+# ignored.
+
+INPUT_FILTER           =
+
+# The FILTER_PATTERNS tag can be used to specify filters on a per file pattern
+# basis.  Doxygen will compare the file name with each pattern and apply the
+# filter if there is a match.  The filters are a list of the form:
+# pattern=filter (like *.cpp=my_cpp_filter). See INPUT_FILTER for further
+# info on how filters are used. If FILTER_PATTERNS is empty, INPUT_FILTER
+# is applied to all files.
+
+FILTER_PATTERNS        =
+
+# If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using
+# INPUT_FILTER) will be used to filter the input files when producing source
+# files to browse (i.e. when SOURCE_BROWSER is set to YES).
+
+FILTER_SOURCE_FILES    = NO
+
+#---------------------------------------------------------------------------
+# configuration options related to source browsing
+#---------------------------------------------------------------------------
+
+# If the SOURCE_BROWSER tag is set to YES then a list of source files will
+# be generated. Documented entities will be cross-referenced with these sources.
+# Note: To get rid of all source code in the generated output, make sure also
+# VERBATIM_HEADERS is set to NO.
+
+SOURCE_BROWSER         = NO
+
+# Setting the INLINE_SOURCES tag to YES will include the body
+# of functions and classes directly in the documentation.
+
+INLINE_SOURCES         = NO
+
+# Setting the STRIP_CODE_COMMENTS tag to YES (the default) will instruct
+# doxygen to hide any special comment blocks from generated source code
+# fragments. Normal C and C++ comments will always remain visible.
+
+STRIP_CODE_COMMENTS    = YES
+
+# If the REFERENCED_BY_RELATION tag is set to YES (the default)
+# then for each documented function all documented
+# functions referencing it will be listed.
+
+REFERENCED_BY_RELATION = YES
+
+# If the REFERENCES_RELATION tag is set to YES (the default)
+# then for each documented function all documented entities
+# called/used by that function will be listed.
+
+REFERENCES_RELATION    = YES
+
+# If the REFERENCES_LINK_SOURCE tag is set to YES (the default)
+# and SOURCE_BROWSER tag is set to YES, then the hyperlinks from
+# functions in REFERENCES_RELATION and REFERENCED_BY_RELATION lists will
+# link to the source code.  Otherwise they will link to the documentstion.
+
+REFERENCES_LINK_SOURCE = YES
+
+# If the USE_HTAGS tag is set to YES then the references to source code
+# will point to the HTML generated by the htags(1) tool instead of doxygen
+# built-in source browser. The htags tool is part of GNU's global source
+# tagging system (see http://www.gnu.org/software/global/global.html). You
+# will need version 4.8.6 or higher.
+
+USE_HTAGS              = NO
+
+# If the VERBATIM_HEADERS tag is set to YES (the default) then Doxygen
+# will generate a verbatim copy of the header file for each class for
+# which an include is specified. Set to NO to disable this.
+
+VERBATIM_HEADERS       = NO
+
+#---------------------------------------------------------------------------
+# configuration options related to the alphabetical class index
+#---------------------------------------------------------------------------
+
+# If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index
+# of all compounds will be generated. Enable this if the project
+# contains a lot of classes, structs, unions or interfaces.
+
+ALPHABETICAL_INDEX     = NO
+
+# If the alphabetical index is enabled (see ALPHABETICAL_INDEX) then
+# the COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns
+# in which this list will be split (can be a number in the range [1..20])
+
+COLS_IN_ALPHA_INDEX    = 5
+
+# In case all classes in a project start with a common prefix, all
+# classes will be put under the same header in the alphabetical index.
+# The IGNORE_PREFIX tag can be used to specify one or more prefixes that
+# should be ignored while generating the index headers.
+
+IGNORE_PREFIX          =
+
+#---------------------------------------------------------------------------
+# configuration options related to the HTML output
+#---------------------------------------------------------------------------
+
+# If the GENERATE_HTML tag is set to YES (the default) Doxygen will
+# generate HTML output.
+
+GENERATE_HTML          = YES
+
+# The HTML_OUTPUT tag is used to specify where the HTML docs will be put.
+# If a relative path is entered the value of OUTPUT_DIRECTORY will be
+# put in front of it. If left blank `html' will be used as the default path.
+
+HTML_OUTPUT            = html
+
+# The HTML_FILE_EXTENSION tag can be used to specify the file extension for
+# each generated HTML page (for example: .htm,.php,.asp). If it is left blank
+# doxygen will generate files with .html extension.
+
+HTML_FILE_EXTENSION    = .html
+
+# The HTML_HEADER tag can be used to specify a personal HTML header for
+# each generated HTML page. If it is left blank doxygen will generate a
+# standard header.
+
+HTML_HEADER            =
+
+# The HTML_FOOTER tag can be used to specify a personal HTML footer for
+# each generated HTML page. If it is left blank doxygen will generate a
+# standard footer.
+
+HTML_FOOTER            =
+
+# The HTML_STYLESHEET tag can be used to specify a user-defined cascading
+# style sheet that is used by each HTML page. It can be used to
+# fine-tune the look of the HTML output. If the tag is left blank doxygen
+# will generate a default style sheet. Note that doxygen will try to copy
+# the style sheet file to the HTML output directory, so don't put your own
+# stylesheet in the HTML output directory as well, or it will be erased!
+
+HTML_STYLESHEET        =
+
+# If the HTML_ALIGN_MEMBERS tag is set to YES, the members of classes,
+# files or namespaces will be aligned in HTML using tables. If set to
+# NO a bullet list will be used.
+
+HTML_ALIGN_MEMBERS     = YES
+
+# If the GENERATE_HTMLHELP tag is set to YES, additional index files
+# will be generated that can be used as input for tools like the
+# Microsoft HTML help workshop to generate a compressed HTML help file (.chm)
+# of the generated HTML documentation.
+
+GENERATE_HTMLHELP      = NO
+
+# If the GENERATE_HTMLHELP tag is set to YES, the CHM_FILE tag can
+# be used to specify the file name of the resulting .chm file. You
+# can add a path in front of the file if the result should not be
+# written to the html output directory.
+
+CHM_FILE               =
+
+# If the GENERATE_HTMLHELP tag is set to YES, the HHC_LOCATION tag can
+# be used to specify the location (absolute path including file name) of
+# the HTML help compiler (hhc.exe). If non-empty doxygen will try to run
+# the HTML help compiler on the generated index.hhp.
+
+HHC_LOCATION           =
+
+# If the GENERATE_HTMLHELP tag is set to YES, the GENERATE_CHI flag
+# controls if a separate .chi index file is generated (YES) or that
+# it should be included in the master .chm file (NO).
+
+GENERATE_CHI           = NO
+
+# If the GENERATE_HTMLHELP tag is set to YES, the BINARY_TOC flag
+# controls whether a binary table of contents is generated (YES) or a
+# normal table of contents (NO) in the .chm file.
+
+BINARY_TOC             = NO
+
+# The TOC_EXPAND flag can be set to YES to add extra items for group members
+# to the contents of the HTML help documentation and to the tree view.
+
+TOC_EXPAND             = NO
+
+# The DISABLE_INDEX tag can be used to turn on/off the condensed index at
+# top of each HTML page. The value NO (the default) enables the index and
+# the value YES disables it.
+
+DISABLE_INDEX          = NO
+
+# This tag can be used to set the number of enum values (range [1..20])
+# that doxygen will group on one line in the generated HTML documentation.
+
+ENUM_VALUES_PER_LINE   = 4
+
+# If the GENERATE_TREEVIEW tag is set to YES, a side panel will be
+# generated containing a tree-like index structure (just like the one that
+# is generated for HTML Help). For this to work a browser that supports
+# JavaScript, DHTML, CSS and frames is required (for instance Mozilla 1.0+,
+# Netscape 6.0+, Internet explorer 5.0+, or Konqueror). Windows users are
+# probably better off using the HTML help feature.
+
+GENERATE_TREEVIEW      = NO
+
+# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be
+# used to set the initial width (in pixels) of the frame in which the tree
+# is shown.
+
+TREEVIEW_WIDTH         = 250
+
+#---------------------------------------------------------------------------
+# configuration options related to the LaTeX output
+#---------------------------------------------------------------------------
+
+# If the GENERATE_LATEX tag is set to YES (the default) Doxygen will
+# generate Latex output.
+
+GENERATE_LATEX         = YES
+
+# The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put.
+# If a relative path is entered the value of OUTPUT_DIRECTORY will be
+# put in front of it. If left blank `latex' will be used as the default path.
+
+LATEX_OUTPUT           = latex
+
+# The LATEX_CMD_NAME tag can be used to specify the LaTeX command name to be
+# invoked. If left blank `latex' will be used as the default command name.
+
+LATEX_CMD_NAME         = latex
+
+# The MAKEINDEX_CMD_NAME tag can be used to specify the command name to
+# generate index for LaTeX. If left blank `makeindex' will be used as the
+# default command name.
+
+MAKEINDEX_CMD_NAME     = makeindex
+
+# If the COMPACT_LATEX tag is set to YES Doxygen generates more compact
+# LaTeX documents. This may be useful for small projects and may help to
+# save some trees in general.
+
+COMPACT_LATEX          = NO
+
+# The PAPER_TYPE tag can be used to set the paper type that is used
+# by the printer. Possible values are: a4, a4wide, letter, legal and
+# executive. If left blank a4wide will be used.
+
+PAPER_TYPE             = a4wide
+
+# The EXTRA_PACKAGES tag can be to specify one or more names of LaTeX
+# packages that should be included in the LaTeX output.
+
+EXTRA_PACKAGES         =
+
+# The LATEX_HEADER tag can be used to specify a personal LaTeX header for
+# the generated latex document. The header should contain everything until
+# the first chapter. If it is left blank doxygen will generate a
+# standard header. Notice: only use this tag if you know what you are doing!
+
+LATEX_HEADER           =
+
+# If the PDF_HYPERLINKS tag is set to YES, the LaTeX that is generated
+# is prepared for conversion to pdf (using ps2pdf). The pdf file will
+# contain links (just like the HTML output) instead of page references
+# This makes the output suitable for online browsing using a pdf viewer.
+
+PDF_HYPERLINKS         = NO
+
+# If the USE_PDFLATEX tag is set to YES, pdflatex will be used instead of
+# plain latex in the generated Makefile. Set this option to YES to get a
+# higher quality PDF documentation.
+
+USE_PDFLATEX           = YES
+
+# If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \\batchmode.
+# command to the generated LaTeX files. This will instruct LaTeX to keep
+# running if errors occur, instead of asking the user for help.
+# This option is also used when generating formulas in HTML.
+
+LATEX_BATCHMODE        = NO
+
+# If LATEX_HIDE_INDICES is set to YES then doxygen will not
+# include the index chapters (such as File Index, Compound Index, etc.)
+# in the output.
+
+LATEX_HIDE_INDICES     = NO
+
+#---------------------------------------------------------------------------
+# configuration options related to the RTF output
+#---------------------------------------------------------------------------
+
+# If the GENERATE_RTF tag is set to YES Doxygen will generate RTF output
+# The RTF output is optimized for Word 97 and may not look very pretty with
+# other RTF readers or editors.
+
+GENERATE_RTF           = NO
+
+# The RTF_OUTPUT tag is used to specify where the RTF docs will be put.
+# If a relative path is entered the value of OUTPUT_DIRECTORY will be
+# put in front of it. If left blank `rtf' will be used as the default path.
+
+RTF_OUTPUT             = rtf
+
+# If the COMPACT_RTF tag is set to YES Doxygen generates more compact
+# RTF documents. This may be useful for small projects and may help to
+# save some trees in general.
+
+COMPACT_RTF            = NO
+
+# If the RTF_HYPERLINKS tag is set to YES, the RTF that is generated
+# will contain hyperlink fields. The RTF file will
+# contain links (just like the HTML output) instead of page references.
+# This makes the output suitable for online browsing using WORD or other
+# programs which support those fields.
+# Note: wordpad (write) and others do not support links.
+
+RTF_HYPERLINKS         = NO
+
+# Load stylesheet definitions from file. Syntax is similar to doxygen's
+# config file, i.e. a series of assignments. You only have to provide
+# replacements, missing definitions are set to their default value.
+
+RTF_STYLESHEET_FILE    =
+
+# Set optional variables used in the generation of an rtf document.
+# Syntax is similar to doxygen's config file.
+
+RTF_EXTENSIONS_FILE    =
+
+#---------------------------------------------------------------------------
+# configuration options related to the man page output
+#---------------------------------------------------------------------------
+
+# If the GENERATE_MAN tag is set to YES (the default) Doxygen will
+# generate man pages
+
+GENERATE_MAN           = NO
+
+# The MAN_OUTPUT tag is used to specify where the man pages will be put.
+# If a relative path is entered the value of OUTPUT_DIRECTORY will be
+# put in front of it. If left blank `man' will be used as the default path.
+
+MAN_OUTPUT             = man
+
+# The MAN_EXTENSION tag determines the extension that is added to
+# the generated man pages (default is the subroutine's section .3)
+
+MAN_EXTENSION          = .3
+
+# If the MAN_LINKS tag is set to YES and Doxygen generates man output,
+# then it will generate one additional man file for each entity
+# documented in the real man page(s). These additional files
+# only source the real man page, but without them the man command
+# would be unable to find the correct page. The default is NO.
+
+MAN_LINKS              = NO
+
+#---------------------------------------------------------------------------
+# configuration options related to the XML output
+#---------------------------------------------------------------------------
+
+# If the GENERATE_XML tag is set to YES Doxygen will
+# generate an XML file that captures the structure of
+# the code including all documentation.
+
+GENERATE_XML           = NO
+
+# The XML_OUTPUT tag is used to specify where the XML pages will be put.
+# If a relative path is entered the value of OUTPUT_DIRECTORY will be
+# put in front of it. If left blank `xml' will be used as the default path.
+
+XML_OUTPUT             = xml
+
+# The XML_SCHEMA tag can be used to specify an XML schema,
+# which can be used by a validating XML parser to check the
+# syntax of the XML files.
+
+XML_SCHEMA             =
+
+# The XML_DTD tag can be used to specify an XML DTD,
+# which can be used by a validating XML parser to check the
+# syntax of the XML files.
+
+XML_DTD                =
+
+# If the XML_PROGRAMLISTING tag is set to YES Doxygen will
+# dump the program listings (including syntax highlighting
+# and cross-referencing information) to the XML output. Note that
+# enabling this will significantly increase the size of the XML output.
+
+XML_PROGRAMLISTING     = YES
+
+#---------------------------------------------------------------------------
+# configuration options for the AutoGen Definitions output
+#---------------------------------------------------------------------------
+
+# If the GENERATE_AUTOGEN_DEF tag is set to YES Doxygen will
+# generate an AutoGen Definitions (see autogen.sf.net) file
+# that captures the structure of the code including all
+# documentation. Note that this feature is still experimental
+# and incomplete at the moment.
+
+GENERATE_AUTOGEN_DEF   = NO
+
+#---------------------------------------------------------------------------
+# configuration options related to the Perl module output
+#---------------------------------------------------------------------------
+
+# If the GENERATE_PERLMOD tag is set to YES Doxygen will
+# generate a Perl module file that captures the structure of
+# the code including all documentation. Note that this
+# feature is still experimental and incomplete at the
+# moment.
+
+GENERATE_PERLMOD       = NO
+
+# If the PERLMOD_LATEX tag is set to YES Doxygen will generate
+# the necessary Makefile rules, Perl scripts and LaTeX code to be able
+# to generate PDF and DVI output from the Perl module output.
+
+PERLMOD_LATEX          = NO
+
+# If the PERLMOD_PRETTY tag is set to YES the Perl module output will be
+# nicely formatted so it can be parsed by a human reader.  This is useful
+# if you want to understand what is going on.  On the other hand, if this
+# tag is set to NO the size of the Perl module output will be much smaller
+# and Perl will parse it just the same.
+
+PERLMOD_PRETTY         = YES
+
+# The names of the make variables in the generated doxyrules.make file
+# are prefixed with the string contained in PERLMOD_MAKEVAR_PREFIX.
+# This is useful so different doxyrules.make files included by the same
+# Makefile don't overwrite each other's variables.
+
+PERLMOD_MAKEVAR_PREFIX =
+
+#---------------------------------------------------------------------------
+# Configuration options related to the preprocessor
+#---------------------------------------------------------------------------
+
+# If the ENABLE_PREPROCESSING tag is set to YES (the default) Doxygen will
+# evaluate all C-preprocessor directives found in the sources and include
+# files.
+
+ENABLE_PREPROCESSING   = YES
+
+# If the MACRO_EXPANSION tag is set to YES Doxygen will expand all macro
+# names in the source code. If set to NO (the default) only conditional
+# compilation will be performed. Macro expansion can be done in a controlled
+# way by setting EXPAND_ONLY_PREDEF to YES.
+
+MACRO_EXPANSION        = NO
+
+# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES
+# then the macro expansion is limited to the macros specified with the
+# PREDEFINED and EXPAND_AS_DEFINED tags.
+
+EXPAND_ONLY_PREDEF     = NO
+
+# If the SEARCH_INCLUDES tag is set to YES (the default) the includes files
+# in the INCLUDE_PATH (see below) will be search if a #include is found.
+
+SEARCH_INCLUDES        = YES
+
+# The INCLUDE_PATH tag can be used to specify one or more directories that
+# contain include files that are not input files but should be processed by
+# the preprocessor.
+
+INCLUDE_PATH           =
+
+# You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard
+# patterns (like *.h and *.hpp) to filter out the header-files in the
+# directories. If left blank, the patterns specified with FILE_PATTERNS will
+# be used.
+
+INCLUDE_FILE_PATTERNS  =
+
+# The PREDEFINED tag can be used to specify one or more macro names that
+# are defined before the preprocessor is started (similar to the -D option of
+# gcc). The argument of the tag is a list of macros of the form: name
+# or name=definition (no spaces). If the definition and the = are
+# omitted =1 is assumed. To prevent a macro definition from being
+# undefined via #undef or recursively expanded use the := operator
+# instead of the = operator.
+
+PREDEFINED             =
+
+# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then
+# this tag can be used to specify a list of macro names that should be expanded.
+# The macro definition that is found in the sources will be used.
+# Use the PREDEFINED tag if you want to use a different macro definition.
+
+EXPAND_AS_DEFINED      =
+
+# If the SKIP_FUNCTION_MACROS tag is set to YES (the default) then
+# doxygen's preprocessor will remove all function-like macros that are alone
+# on a line, have an all uppercase name, and do not end with a semicolon. Such
+# function macros are typically used for boiler-plate code, and will confuse
+# the parser if not removed.
+
+SKIP_FUNCTION_MACROS   = YES
+
+#---------------------------------------------------------------------------
+# Configuration::additions related to external references
+#---------------------------------------------------------------------------
+
+# The TAGFILES option can be used to specify one or more tagfiles.
+# Optionally an initial location of the external documentation
+# can be added for each tagfile. The format of a tag file without
+# this location is as follows:
+#   TAGFILES = file1 file2 ...
+# Adding location for the tag files is done as follows:
+#   TAGFILES = file1=loc1 "file2 = loc2" ...
+# where "loc1" and "loc2" can be relative or absolute paths or
+# URLs. If a location is present for each tag, the installdox tool
+# does not have to be run to correct the links.
+# Note that each tag file must have a unique name
+# (where the name does NOT include the path)
+# If a tag file is not located in the directory in which doxygen
+# is run, you must also specify the path to the tagfile here.
+
+TAGFILES               =
+
+# When a file name is specified after GENERATE_TAGFILE, doxygen will create
+# a tag file that is based on the input files it reads.
+
+GENERATE_TAGFILE       =
+
+# If the ALLEXTERNALS tag is set to YES all external classes will be listed
+# in the class index. If set to NO only the inherited external classes
+# will be listed.
+
+ALLEXTERNALS           = NO
+
+# If the EXTERNAL_GROUPS tag is set to YES all external groups will be listed
+# in the modules index. If set to NO, only the current project's groups will
+# be listed.
+
+EXTERNAL_GROUPS        = YES
+
+# The PERL_PATH should be the absolute path and name of the perl script
+# interpreter (i.e. the result of `which perl').
+
+PERL_PATH              = /usr/bin/perl
+
+#---------------------------------------------------------------------------
+# Configuration options related to the dot tool
+#---------------------------------------------------------------------------
+
+# If the CLASS_DIAGRAMS tag is set to YES (the default) Doxygen will
+# generate a inheritance diagram (in HTML, RTF and LaTeX) for classes with base
+# or super classes. Setting the tag to NO turns the diagrams off. Note that
+# this option is superseded by the HAVE_DOT option below. This is only a
+# fallback. It is recommended to install and use dot, since it yields more
+# powerful graphs.
+
+CLASS_DIAGRAMS         = YES
+
+# If set to YES, the inheritance and collaboration graphs will hide
+# inheritance and usage relations if the target is undocumented
+# or is not a class.
+
+HIDE_UNDOC_RELATIONS   = YES
+
+# If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is
+# available from the path. This tool is part of Graphviz, a graph visualization
+# toolkit from AT&T and Lucent Bell Labs. The other options in this section
+# have no effect if this option is set to NO (the default)
+
+HAVE_DOT               = NO
+
+# If the CLASS_GRAPH and HAVE_DOT tags are set to YES then doxygen
+# will generate a graph for each documented class showing the direct and
+# indirect inheritance relations. Setting this tag to YES will force the
+# the CLASS_DIAGRAMS tag to NO.
+
+CLASS_GRAPH            = YES
+
+# If the COLLABORATION_GRAPH and HAVE_DOT tags are set to YES then doxygen
+# will generate a graph for each documented class showing the direct and
+# indirect implementation dependencies (inheritance, containment, and
+# class references variables) of the class with other documented classes.
+
+COLLABORATION_GRAPH    = YES
+
+# If the GROUP_GRAPHS and HAVE_DOT tags are set to YES then doxygen
+# will generate a graph for groups, showing the direct groups dependencies
+
+GROUP_GRAPHS           = YES
+
+# If the UML_LOOK tag is set to YES doxygen will generate inheritance and
+# collaboration diagrams in a style similar to the OMG's Unified Modeling
+# Language.
+
+UML_LOOK               = NO
+
+# If set to YES, the inheritance and collaboration graphs will show the
+# relations between templates and their instances.
+
+TEMPLATE_RELATIONS     = NO
+
+# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDE_GRAPH, and HAVE_DOT
+# tags are set to YES then doxygen will generate a graph for each documented
+# file showing the direct and indirect include dependencies of the file with
+# other documented files.
+
+INCLUDE_GRAPH          = YES
+
+# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDED_BY_GRAPH, and
+# HAVE_DOT tags are set to YES then doxygen will generate a graph for each
+# documented header file showing the documented files that directly or
+# indirectly include this file.
+
+INCLUDED_BY_GRAPH      = YES
+
+# If the CALL_GRAPH and HAVE_DOT tags are set to YES then doxygen will
+# generate a call dependency graph for every global function or class method.
+# Note that enabling this option will significantly increase the time of a run.
+# So in most cases it will be better to enable call graphs for selected
+# functions only using the \callgraph command.
+
+CALL_GRAPH             = NO
+
+# If the CALLER_GRAPH and HAVE_DOT tags are set to YES then doxygen will
+# generate a caller dependency graph for every global function or class method.
+# Note that enabling this option will significantly increase the time of a run.
+# So in most cases it will be better to enable caller graphs for selected
+# functions only using the \callergraph command.
+
+CALLER_GRAPH           = NO
+
+# If the GRAPHICAL_HIERARCHY and HAVE_DOT tags are set to YES then doxygen
+# will graphical hierarchy of all classes instead of a textual one.
+
+GRAPHICAL_HIERARCHY    = YES
+
+# If the DIRECTORY_GRAPH, SHOW_DIRECTORIES and HAVE_DOT tags are set to YES
+# then doxygen will show the dependencies a directory has on other directories
+# in a graphical way. The dependency relations are determined by the #include
+# relations between the files in the directories.
+
+DIRECTORY_GRAPH        = YES
+
+# The DOT_IMAGE_FORMAT tag can be used to set the image format of the images
+# generated by dot. Possible values are png, jpg, or gif
+# If left blank png will be used.
+
+DOT_IMAGE_FORMAT       = png
+
+# The tag DOT_PATH can be used to specify the path where the dot tool can be
+# found. If left blank, it is assumed the dot tool can be found in the path.
+
+DOT_PATH               =
+
+# The DOTFILE_DIRS tag can be used to specify one or more directories that
+# contain dot files that are included in the documentation (see the
+# \dotfile command).
+
+DOTFILE_DIRS           =
+
+# The MAX_DOT_GRAPH_WIDTH tag can be used to set the maximum allowed width
+# (in pixels) of the graphs generated by dot. If a graph becomes larger than
+# this value, doxygen will try to truncate the graph, so that it fits within
+# the specified constraint. Beware that most browsers cannot cope with very
+# large images.
+
+MAX_DOT_GRAPH_WIDTH    = 1024
+
+# The MAX_DOT_GRAPH_HEIGHT tag can be used to set the maximum allows height
+# (in pixels) of the graphs generated by dot. If a graph becomes larger than
+# this value, doxygen will try to truncate the graph, so that it fits within
+# the specified constraint. Beware that most browsers cannot cope with very
+# large images.
+
+MAX_DOT_GRAPH_HEIGHT   = 1024
+
+# The MAX_DOT_GRAPH_DEPTH tag can be used to set the maximum depth of the
+# graphs generated by dot. A depth value of 3 means that only nodes reachable
+# from the root by following a path via at most 3 edges will be shown. Nodes
+# that lay further from the root node will be omitted. Note that setting this
+# option to 1 or 2 may greatly reduce the computation time needed for large
+# code bases. Also note that a graph may be further truncated if the graph's
+# image dimensions are not sufficient to fit the graph (see MAX_DOT_GRAPH_WIDTH
+# and MAX_DOT_GRAPH_HEIGHT). If 0 is used for the depth value (the default),
+# the graph is not depth-constrained.
+
+MAX_DOT_GRAPH_DEPTH    = 0
+
+# Set the DOT_TRANSPARENT tag to YES to generate images with a transparent
+# background. This is disabled by default, which results in a white background.
+# Warning: Depending on the platform used, enabling this option may lead to
+# badly anti-aliased labels on the edges of a graph (i.e. they become hard to
+# read).
+
+DOT_TRANSPARENT        = NO
+
+# Set the DOT_MULTI_TARGETS tag to YES allow dot to generate multiple output
+# files in one run (i.e. multiple -o and -T options on the command line). This
+# makes dot run faster, but since only newer versions of dot (>1.8.10)
+# support this, this feature is disabled by default.
+
+DOT_MULTI_TARGETS      = NO
+
+# If the GENERATE_LEGEND tag is set to YES (the default) Doxygen will
+# generate a legend page explaining the meaning of the various boxes and
+# arrows in the dot generated graphs.
+
+GENERATE_LEGEND        = YES
+
+# If the DOT_CLEANUP tag is set to YES (the default) Doxygen will
+# remove the intermediate dot files that are used to generate
+# the various graphs.
+
+DOT_CLEANUP            = YES
+
+#---------------------------------------------------------------------------
+# Configuration::additions related to the search engine
+#---------------------------------------------------------------------------
+
+# The SEARCHENGINE tag specifies whether or not a search engine should be
+# used. If set to NO the values of all tags below this one will be ignored.
+
+SEARCHENGINE           = NO
diff --git a/Makefile.am b/Makefile.am
new file mode 100644 (file)
index 0000000..df3d07d
--- /dev/null
@@ -0,0 +1,38 @@
+##
+##  Copyright (C) 2007 Lasse Collin
+##
+##  This library is free software; you can redistribute it and/or
+##  modify it under the terms of the GNU Lesser General Public
+##  License as published by the Free Software Foundation; either
+##  version 2.1 of the License, or (at your option) any later version.
+##
+##  This library is distributed in the hope that it will be useful,
+##  but WITHOUT ANY WARRANTY; without even the implied warranty of
+##  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+##  Lesser General Public License for more details.
+##
+
+SUBDIRS =
+
+if COND_GNULIB
+SUBDIRS += lib
+endif
+
+SUBDIRS += src po tests
+
+
+EXTRA_DIST = \
+       m4 \
+       extra \
+       config.rpath  \
+       Doxyfile.in \
+       FAQ \
+       INSTALL.generic \
+       COPYING.GPLv2 \
+       COPYING.GPLv3 \
+       COPYING.LGPLv2.1 \
+       README-liblzma \
+       README-lzma
+
+ACLOCAL_AMFLAGS = -I m4
+AUTOMAKE_OPTIONS = foreign
diff --git a/NEWS b/NEWS
new file mode 100644 (file)
index 0000000..e69de29
diff --git a/README b/README
new file mode 100644 (file)
index 0000000..b56331a
--- /dev/null
+++ b/README
@@ -0,0 +1,151 @@
+
+LZMA Utils
+----------
+
+Warning
+
+    This is an early alpha version. Don't trust the files produced by
+    this version of the software - not even if the software can
+    uncompress the files properly! This is because the file format
+    isn't completely frozen yet.
+
+    So please test a lot, but don't use for anything serious yet.
+
+
+Overview
+
+    LZMA is a general purporse compression algorithm designed by
+    Igor Pavlov as part of 7-Zip. It provides high compression ratio
+    while keeping the decompression speed fast.
+
+    LZMA Utils are an attempt to make LZMA compression easy to use
+    on free (as in freedom) operating systems. This is achieved by
+    providing tools and libraries which are similar to use than the
+    equivalents of the most popular existing compression algorithms.
+
+    LZMA Utils consist of a few relatively separate parts:
+      * liblzma is an encoder/decoder library with support for several
+        filters (algorithm implementations). The primary filter is LZMA.
+      * libzfile enables reading from and writing to gzip, bzip2 and
+        LZMA compressed and uncompressed files with an API similar to
+        the standard ANSI-C file I/O.
+        [ NOTE: libzfile is not implemented yet. ]
+      * lzma command line tool has almost identical syntax than gzip
+        and bzip2. It makes LZMA easy for average users, but also
+        provides advanced options to finetune the compression settings.
+      * A few shell scripts make diffing and grepping LZMA compressed
+        files easy. The scripts were adapted from gzip and bzip2.
+
+
+Supported platforms
+
+    LZMA Utils are developed on GNU+Linux, but they should work at
+    least on *BSDs and Solaris. They probably work on some other
+    POSIX-like operating systems too.
+
+    If you use GCC to compile LZMA Utils, you need at least version
+    3.x.x. GCC version 2.xx.x doesn't support some C99 features used
+    in LZMA Utils source code, thus GCC 2 won't compile LZMA Utils.
+
+    If you have written patches to make LZMA Utils to work on previously
+    unsupported platform, please send the patches to me! I will consider
+    including them to the official version. It's nice to minimize the
+    need of third-party patching.
+
+    One exception: Don't request or send patches to change the whole
+    source package to C89. I find C99 substantially nicer to write and
+    maintain. However, the public library headers must be in C89 to
+    avoid frustrating those who maintain programs, which are strictly
+    in C89 or C++.
+
+
+configure options
+
+    If you are not familiar with `configure' scripts, read the file
+    INSTALL first.
+
+    In most cases, the default --enable/--disable/--with/--without options
+    are what you want. Don't touch them if you are unsure.
+
+    --disable-encoder
+                Do not compile the encoder component of liblzma. This
+                implies --disable-match-finders. If you need only
+                the decoder, you can decrease the library size
+                dramatically with this option.
+
+                The default is to build the encoder.
+
+    --disable-decoder
+                Do not compile the decoder component of liblzma.
+
+                The default is to build the decoder.
+
+    --enable-filters=
+                liblzma supports several filters. See liblzma-intro.txt
+                for a little more information about these.
+
+                The default is to build all the filters.
+
+    --enable-match-finders=
+                liblzma includes two categories of match finders:
+                hash chains and binary trees. Hash chains (hc3 and hc4)
+                are quite fast but they don't provide the best compression
+                ratio. Binary trees (bt2, bt3 and bt4) give excellent
+                compression ratio, but they are slower and need more
+                memory than hash chains.
+
+                You need to enable at least one match finder to build the
+                LZMA filter encoder. Usually hash chains are used only in
+                the fast mode, while binary trees are used to when the best
+                compression ratio is wanted.
+
+                The default is to build all the match finders.
+
+    --enable-checks=
+                liblzma support multiple integrity checks. CRC32 is
+                mandatory, and cannot be omitted. See liblzma-intro.txt
+                for more information about usage of the integrity checks.
+
+    --disable-assembler
+                liblzma includes some assembler optimizations. Currently
+                there is only assembler code for CRC32 and CRC64 for
+                32-bit x86.
+
+                All the assembler code in liblzma is position-independent
+                code, which is suitable for use in shared libraries and
+                position-independent executables.
+
+    --enable-small
+                Omits precomputed tables. This makes liblzma a few KiB
+                smaller. Startup time increases, because the tables need
+                to be computed first.
+
+    --enable-debug
+                This enables the assert() macro and possibly some other
+                run-time consistency checks. It slows down things somewhat,
+                so you normally don't want to have this enabled.
+
+    --enable-werror
+                Makes all compiler warnings an error, that abort the
+                compilation. This may help catching bugs, and should work
+                on most systems. This has no effect on the resulting
+                binaries.
+
+
+Static vs. dynamic linking of the command line tools
+
+    By default, the command line tools are linked statically against
+    liblzma. There a are a few reasons:
+
+      - The executable(s) can be in /bin while the shared liblzma can still
+        be in /usr/lib (if the distro uses such file system hierachy).
+
+      - It's easier to copy the executables to other systems, since they
+        depend only on libc.
+
+      - It's slightly faster on some architectures like x86.
+
+    If you don't like this, you can get the command line tools linked
+    against the shared liblzma by specifying --disable-static to configure.
+    This disables building static liblzma completely.
+
diff --git a/THANKS b/THANKS
new file mode 100644 (file)
index 0000000..56e18dc
--- /dev/null
+++ b/THANKS
@@ -0,0 +1,23 @@
+
+Thanks
+------
+
+Some people have helped more, some less, some don't even know they have
+been helpful, but nevertheless everyone's help has been important. :-)
+In alphabetical order:
+  - Mark Adler
+  - Anders F. Björklund
+  - İsmail Dönmez
+  - Jean-loup Gailly
+  - Per Øyvind Karlsen
+  - Ville Koskinen
+  - Jim Meyering
+  - Igor Pavlov
+  - Mikko Pouru
+  - Alexandre Sauvé
+  - Julian Seward
+  - Mohammed Adnène Trojette
+
+Also thanks to all the people who have participated the Tukaani project
+and others who I have forgot.
+
diff --git a/TODO b/TODO
new file mode 100644 (file)
index 0000000..61b2e3f
--- /dev/null
+++ b/TODO
@@ -0,0 +1,109 @@
+
+LZMA Utils TODO List
+--------------------
+
+Major missing features
+
+    Memory limits in the command line tool apply only to compression.
+
+    Threading support in the lzma command line tool is still primitive.
+    It cannot split a file in pieces yet.
+
+    The --list mode isn't implemented in the command line tool.
+
+    Handling of Multi-Block Stream information should be separated
+    from Stream encoder and decoder. Those would be useful to implement
+    multi-threaded coding in applications.
+
+    Buffer to buffer coding is not implemented in liblzma. Probably
+    a naive version should be written first, which would simply wrap
+    things around lzma_stream. Later, there should be separate buffer
+    coding functions, that are slightly faster (less memcpy()) and
+    have smaller memory usage than the functions using lzma_stream.
+
+    libzfile is not implemented.
+
+    LZMA filter doesn't support predefined history buffer.
+
+
+Security
+
+    Search for bugs, especially security related issues. Security is
+    important in every piece of code in LZMA Utils, but it is extremely
+    important in the decoder part of liblzma.
+
+    Subblock: If there is LZMA as a Subfilter but without EOPM, can it
+    trigger infinite loop when Subblock's "Unset Subfilter" flag is hit?
+
+    Similarly, can LZ decoder get stuck in infinite loop if the next
+    filter in the chain returns LZMA_STREAM_END but the decoded data
+    doesn't allow finishing the LZ decoding?
+
+
+Reliability
+
+    Create a test suite to be run with "make check".
+
+    Should we use strlimit() and getrlimit() for memory usage limitting?
+
+
+Performance
+
+    Benchmark the CRC code on non-x86 CPUs. Won't have huge effect on
+    overall speed, but it would still be nice to know what algorithm
+    variant is the best on different CPUs.
+
+
+Third party support
+
+    Add support for LZMA to various applications. This naturally requires
+    cooperating with the authors of the specific applications.
+      * GNU grep and GNU diffutils: BSD grep already uses zlib directly
+        instead of ugly shell scripts. It would be nice to get similar
+        feature into relevant GNU tools. With libzfile, multiple
+        compression formats would be easy to support.
+      * kioslave for KDE
+      * Magic for the `file' command
+      * GNU Midnight Commander
+      * GNU Texinfo
+      * The `man' command
+      * Package managers
+
+    Test the patches already written. The patches should be sent to
+    upstream developers _once_ LZMA Utils APIs are stable enough (so
+    people don't need to fix those patches all the time).
+
+    Mandriva has quite a few patches. Some of them are OK, some need
+    adapting for new LZMA Utils.
+
+
+Documentation
+
+    Revise the man page of lzma command line tool.
+
+    If the Doxygen docs aren't enough, write good Texinfo manual for
+    liblzma. It's been a long time I've even tried to build the Doxygen
+    docs, so they may look quite bad at the moment.
+
+    Document LZMA as an algorithm. It would be great to have detailed
+    description of the algorithm in English. Many people think, that
+    reading the source code is not the optimal way to learn how LZMA
+    works.
+
+
+Other
+
+    Some things return LZMA_PROG_ERROR with invalid options, some
+    LZMA_HEADER_ERROR. These must be checked carefully and made so
+    that LZMA_HEADER_ERROR is used only when the given option could
+    make sense in future version of libzma.
+
+    lzma_restrict vs. restrict
+
+    Usage of LZMA_RUN vs. LZMA_FINISH with Metadata coders.
+
+    Port the Deflate implementation from 7-Zip into liblzma. 7-Zip's
+    Deflate compresses better than zlib, gzip or Info-ZIP. I don't
+    know if Deflate will be included in .lzma format (probably not),
+    but it's still useful once we also add support for .gz file format.
+
diff --git a/autogen.sh b/autogen.sh
new file mode 100755 (executable)
index 0000000..beddf73
--- /dev/null
@@ -0,0 +1,38 @@
+#!/bin/sh
+
+set -e -x
+
+# autooint copies all kinds of crap even though we have told in
+# configure.ac that we don't want the intl directory. It is able
+# to omit the intl directory but still copies the m4 files needed
+# only by the stuff in the non-existing intl directory.
+autopoint -f
+rm -f \
+       codeset.m4 \
+       glibc2.m4 \
+       glibc21.m4 \
+       intdiv0.m4 \
+       intl.m4 \
+       intldir.m4 \
+       intmax.m4 \
+       inttypes-pri.m4 \
+       inttypes_h.m4 \
+       lcmessage.m4 \
+       lock.m4 \
+       longdouble.m4 \
+       longlong.m4 \
+       printf-posix.m4 \
+       size_max.m4 \
+       stdint_h.m4 \
+       uintmax_t.m4 \
+       ulonglong.m4 \
+       visibility.m4 \
+       wchar_t.m4 \
+       wint_t.m4 \
+       xsize.m4
+
+aclocal -I m4
+libtoolize -c -f || glibtoolize -c -f
+autoconf
+autoheader
+automake -acf --foreign
diff --git a/configure.ac b/configure.ac
new file mode 100644 (file)
index 0000000..3f9ad53
--- /dev/null
@@ -0,0 +1,611 @@
+#                                               -*- Autoconf -*-
+# Process this file with autoconf to produce a configure script.
+
+###############################################################################
+#
+#   Copyright (C) 2007 Lasse Collin
+#
+#   This library is free software; you can redistribute it and/or
+#   modify it under the terms of the GNU Lesser General Public
+#   License as published by the Free Software Foundation; either
+#   version 2.1 of the License, or (at your option) any later version.
+#
+#   This library is distributed in the hope that it will be useful,
+#   but WITHOUT ANY WARRANTY; without even the implied warranty of
+#   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+#   Lesser General Public License for more details.
+#
+###############################################################################
+
+# NOTE: Don't add useless checks. autoscan detects this and that, but don't
+# let it confuse you. For example, we don't care about checking for behavior
+# of malloc(), stat(), or lstat(), since we don't use those functions in
+# a way that would cause the problems the autoconf macros check.
+
+AC_PREREQ(2.61)
+
+# [LZMA] instead of [LZMA utils] since I prefer to have lzma-version.tar.gz
+# instead of lzma-utils-version.tar.gz.
+AC_INIT([LZMA], [4.42.2alpha], [lasse.collin@tukaani.org])
+
+AC_CONFIG_SRCDIR([src/liblzma/common/common.h])
+AC_CONFIG_HEADER([config.h])
+
+echo
+echo "LZMA Utils $PACKAGE_VERSION"
+
+echo
+echo "System type:"
+# This is needed to know if assembler optimizations can be used.
+AC_CANONICAL_HOST
+
+echo
+echo "Configure options:"
+
+# Enable/disable debugging code:
+AC_MSG_CHECKING([if debugging code should be compiled])
+AC_ARG_ENABLE(debug, AC_HELP_STRING([--enable-debug], [Enable debugging code.]),
+       [], enable_debug=no)
+if test "x$enable_debug" = xyes; then
+       CFLAGS="-g $CFLAGS"
+       AC_MSG_RESULT([yes])
+else
+       AC_DEFINE(NDEBUG, 1, [Define to disable debugging code.])
+       AC_MSG_RESULT([no])
+fi
+
+# Enable/disable the encoder components:
+AC_MSG_CHECKING([if encoder components should be built])
+AC_ARG_ENABLE(encoder, AC_HELP_STRING([--disable-encoder],
+               [Do not build the encoder components.]),
+       [], enable_encoder=yes)
+if test "x$enable_encoder" = xyes; then
+       AC_DEFINE([HAVE_ENCODER], 1,
+               [Define to 1 if encoder components are enabled.])
+       AC_MSG_RESULT([yes])
+else
+       AC_MSG_RESULT([no])
+fi
+AM_CONDITIONAL(COND_MAIN_ENCODER, test "x$enable_encoder" = xyes)
+
+# Enable/disable the decoder components:
+AC_MSG_CHECKING([if decoder components should be built])
+AC_ARG_ENABLE(decoder, AC_HELP_STRING([--disable-decoder],
+               [Do not build the decoder components.]),
+       [], enable_decoder=yes)
+if test "x$enable_decoder" = xyes; then
+       AC_DEFINE([HAVE_DECODER], 1,
+               [Define to 1 if decoder components are enabled.])
+       AC_MSG_RESULT([yes])
+else
+       AC_MSG_RESULT([no])
+       if test "x$enable_encoder" = xno; then
+               AC_MSG_ERROR([Do not disable both encoder and decoder.])
+       fi
+fi
+AM_CONDITIONAL(COND_MAIN_DECODER, test "x$enable_decoder" = xyes)
+
+# Filters
+AC_MSG_CHECKING([which filters to build])
+AC_ARG_ENABLE(filters, AC_HELP_STRING([--enable-filters=],
+               [Comma-separated list of filters to build. Default=all.
+               Filters used in encoding are needed also in decoding.
+               Available filters: copy subblock x86 powerpc ia64
+               arm armthumb sparc delta lzma]),
+               [], [enable_filters=copy,subblock,x86,powerpc,ia64,arm,armthumb,sparc,delta,lzma])
+enable_filters=`echo "$enable_filters" | sed 's/,/ /g'`
+enable_filters_copy=no
+enable_filters_subblock=no
+enable_filters_x86=no
+enable_filters_powerpc=no
+enable_filters_ia64=no
+enable_filters_arm=no
+enable_filters_armthumb=no
+enable_filters_sparc=no
+enable_filters_delta=no
+enable_filters_lzma=no
+enable_simple_filters=no
+if test "x$enable_filters" = xno || test "x$enable_filters" = x; then
+       AC_MSG_RESULT([])
+       AC_MSG_ERROR([Please enable at least one filter.])
+else
+       for arg in $enable_filters
+       do
+               case $arg in
+                       copy)
+                               enable_filters_copy=yes
+                               AC_DEFINE([HAVE_FILTER_COPY], 1,
+                                       [Define to 1 if support for the
+                                       Copy filter is enabled.])
+                               ;;
+                       subblock)
+                               enable_filters_subblock=yes
+                               AC_DEFINE([HAVE_FILTER_SUBBLOCK], 1,
+                                       [Define to 1 if support for the
+                                       Subblock filter is enabled.])
+                               ;;
+                       x86)
+                               enable_filters_x86=yes
+                               enable_simple_filters=yes
+                               AC_DEFINE([HAVE_FILTER_X86], 1,
+                                       [Define to 1 if support for the
+                                       x86 (BCJ) filter is enabled.])
+                               ;;
+                       powerpc)
+                               enable_filters_powerpc=yes
+                               enable_simple_filters=yes
+                               AC_DEFINE([HAVE_FILTER_POWERPC], 1,
+                                       [Define to 1 if support for the
+                                       PowerPC filter is enabled.])
+                               ;;
+                       ia64)
+                               enable_filters_ia64=yes
+                               enable_simple_filters=yes
+                               AC_DEFINE([HAVE_FILTER_IA64], 1,
+                                       [Define to 1 if support for the
+                                       IA64 filter is enabled.])
+                               ;;
+                       arm)
+                               enable_filters_arm=yes
+                               enable_simple_filters=yes
+                               AC_DEFINE([HAVE_FILTER_ARM], 1,
+                                       [Define to 1 if support for the
+                                       ARM filter is enabled.])
+                               ;;
+                       armthumb)
+                               enable_filters_armthumb=yes
+                               enable_simple_filters=yes
+                               AC_DEFINE([HAVE_FILTER_ARMTHUMB], 1,
+                                       [Define to 1 if support for the
+                                       ARMThumb filter is enabled.])
+                               ;;
+                       sparc)
+                               enable_filters_sparc=yes
+                               enable_simple_filters=yes
+                               AC_DEFINE([HAVE_FILTER_SPARC], 1,
+                                       [Define to 1 if support for the
+                                       SPARC filter is enabled.])
+                               ;;
+                       delta)
+                               enable_filters_delta=yes
+                               AC_DEFINE([HAVE_FILTER_DELTA], 1,
+                                       [Define to 1 if support for the
+                                       Delta filter is enabled.])
+                               ;;
+                       lzma)
+                               enable_filters_lzma=yes
+                               AC_DEFINE([HAVE_FILTER_LZMA], 1,
+                                       [Define to 1 if support for the
+                                       LZMA filter is enabled.])
+                               ;;
+                       *)
+                               AC_MSG_RESULT([])
+                               AC_MSG_ERROR([unknown filter: $arg])
+                               ;;
+               esac
+       done
+       AC_MSG_RESULT([$enable_filters])
+fi
+if test "x$enable_simple_filters" = xyes ; then
+       AC_DEFINE([HAVE_FILTER_SIMPLE], 1, [Define to 1 if support for any
+               of the so called simple filters is enabled.])
+fi
+AM_CONDITIONAL(COND_FILTER_COPY, test "x$enable_filters_copy" = xyes)
+AM_CONDITIONAL(COND_FILTER_SUBBLOCK, test "x$enable_filters_subblock" = xyes)
+AM_CONDITIONAL(COND_FILTER_X86, test "x$enable_filters_x86" = xyes)
+AM_CONDITIONAL(COND_FILTER_POWERPC, test "x$enable_filters_powerpc" = xyes)
+AM_CONDITIONAL(COND_FILTER_IA64, test "x$enable_filters_ia64" = xyes)
+AM_CONDITIONAL(COND_FILTER_ARM, test "x$enable_filters_arm" = xyes)
+AM_CONDITIONAL(COND_FILTER_ARMTHUMB, test "x$enable_filters_armthumb" = xyes)
+AM_CONDITIONAL(COND_FILTER_SPARC, test "x$enable_filters_sparc" = xyes)
+AM_CONDITIONAL(COND_FILTER_DELTA, test "x$enable_filters_delta" = xyes)
+AM_CONDITIONAL(COND_FILTER_LZMA, test "x$enable_filters_lzma" = xyes)
+AM_CONDITIONAL(COND_MAIN_SIMPLE, test "x$enable_simple_filters" = xyes)
+
+# Which match finders should be enabled:
+AC_MSG_CHECKING([which match finders to build])
+AC_ARG_ENABLE(match-finders, AC_HELP_STRING([--enable-match-finders=],
+               [Comma-separated list of match finders to build. Default=all.
+               At least one match finder is required for encoding with
+               the LZMA filter.
+               Available match finders: hc3 hc4 bt2 bt3 bt4]), [],
+       [enable_match_finders=hc3,hc4,bt2,bt3,bt4])
+enable_match_finders=`echo "$enable_match_finders" | sed 's/,/ /g'`
+enable_match_finders_hc3=no
+enable_match_finders_hc4=no
+enable_match_finders_bt2=no
+enable_match_finders_bt3=no
+enable_match_finders_bt4=no
+if test "x$enable_encoder" = xyes && test "x$enable_filters_lzma" = xyes ; then
+       for arg in $enable_match_finders
+               do
+               case $arg in
+                       hc3) enable_match_finders_hc3=yes ;;
+                       hc4) enable_match_finders_hc4=yes ;;
+                       bt2) enable_match_finders_bt2=yes ;;
+                       bt3) enable_match_finders_bt3=yes ;;
+                       bt4) enable_match_finders_bt4=yes ;;
+                       *)
+                               AC_MSG_RESULT([])
+                               AC_MSG_ERROR([unknown match finder: $arg])
+                               ;;
+               esac
+       done
+       AC_MSG_RESULT([$enable_match_finders])
+else
+       AC_MSG_RESULT([(none because not building the LZMA encoder)])
+fi
+AM_CONDITIONAL(COND_MF_HC3, test "x$enable_match_finders_hc3" = xyes)
+AM_CONDITIONAL(COND_MF_HC4, test "x$enable_match_finders_hc4" = xyes)
+AM_CONDITIONAL(COND_MF_BT2, test "x$enable_match_finders_bt2" = xyes)
+AM_CONDITIONAL(COND_MF_BT3, test "x$enable_match_finders_bt3" = xyes)
+AM_CONDITIONAL(COND_MF_BT4, test "x$enable_match_finders_bt4" = xyes)
+
+# Which integrity checks to build
+AC_MSG_CHECKING([which integrity checks to build])
+AC_ARG_ENABLE(checks, AC_HELP_STRING([--enable-checks=],
+               [Comma-separated list of integrity checks to build.
+               Default=all. Available integrity checks: crc32 crc64 sha256]),
+               [], [enable_checks=crc32,crc64,sha256])
+enable_checks=`echo "$enable_checks" | sed 's/,/ /g'`
+enable_checks_crc32=no
+enable_checks_crc64=no
+enable_checks_sha256=no
+if test "x$enable_checks" = xno || test "x$enable_checks" = x; then
+       AC_MSG_RESULT([(none)])
+else
+       for arg in $enable_checks
+       do
+               case $arg in
+                       crc32)
+                               enable_checks_crc32=yes
+                               AC_DEFINE([HAVE_CHECK_CRC32], 1,
+                                       [Define to 1 if CRC32 support
+                                       is enabled.])
+                               ;;
+                       crc64)
+                               enable_checks_crc64=yes
+                               AC_DEFINE([HAVE_CHECK_CRC64], 1,
+                                       [Define to 1 if CRC64 support
+                                       is enabled.])
+                               ;;
+                       sha256)
+                               enable_checks_sha256=yes
+                               AC_DEFINE([HAVE_CHECK_SHA256], 1,
+                                       [Define to 1 if SHA256 support
+                                       is enabled.])
+                               ;;
+                       *)
+                               AC_MSG_RESULT([])
+                               AC_MSG_ERROR([unknown integrity check: $arg])
+                               ;;
+               esac
+       done
+       AC_MSG_RESULT([$enable_checks])
+fi
+if test "x$enable_checks_crc32" = xno ; then
+       AC_MSG_ERROR([For now, the CRC32 check must always be enabled.])
+fi
+AM_CONDITIONAL(COND_CHECK_CRC32, test "x$enable_checks_crc32" = xyes)
+AM_CONDITIONAL(COND_CHECK_CRC64, test "x$enable_checks_crc64" = xyes)
+AM_CONDITIONAL(COND_CHECK_SHA256, test "x$enable_checks_sha256" = xyes)
+
+# Assembler optimizations
+AC_MSG_CHECKING([if assembler optimizations should be used])
+AC_ARG_ENABLE(assembler, AC_HELP_STRING([--disable-assembler],
+               [Do not use assembler optimizations even if such exist
+               for the architecture.]),
+               [], [enable_assembler=yes])
+if test "x$enable_assembler" = xyes; then
+       case $host_cpu in
+               i?86)   enable_assembler=x86 ;;
+               *)      enable_assembler=no ;;
+       esac
+fi
+case $enable_assembler in
+       x86|no) ;;
+       *)
+               AC_MSG_RESULT([])
+               AC_MSG_ERROR([--enable-assembler accepts only \`yes', \`no', or \`x86'.])
+               ;;
+esac
+AC_MSG_RESULT([$enable_assembler])
+AM_CONDITIONAL(COND_ASM_X86, test "x$enable_assembler" = xx86)
+
+# Size optimization
+AC_MSG_CHECKING([if small size is preferred over speed])
+AC_ARG_ENABLE(small, AC_HELP_STRING([--enable-small],
+               [Omit precomputed tables to make liblzma a few kilobytes
+               smaller. This will increase startup time of applications
+               slightly, because the tables need to be computed first.]),
+               [], [enable_small=no])
+if test "x$enable_small" = xyes; then
+       AC_DEFINE([HAVE_SMALL], 1, [Define to 1 if optimizing for size.])
+elif test "x$enable_small" != xno; then
+       AC_MSG_RESULT([])
+       AC_MSG_ERROR([--enable-small accepts only \`yes' or \`no'])
+fi
+AC_MSG_RESULT([$enable_small])
+AM_CONDITIONAL(COND_SMALL, test "x$enable_small" = xyes)
+
+echo
+echo "Initializing Automake:"
+
+# There's no C++ or Fortran in LZMA Utils:
+CXX=no
+F77=no
+
+AM_INIT_AUTOMAKE
+
+AC_USE_SYSTEM_EXTENSIONS
+
+###############################################################################
+# Checks for programs.
+###############################################################################
+
+AM_PROG_CC_C_O
+AM_PROG_AS
+AC_PROG_LN_S
+
+echo
+echo "Threading support:"
+ACX_PTHREAD
+CC="$PTHREAD_CC"
+
+echo
+echo "Initializing Libtool:"
+AC_PROG_LIBTOOL
+
+
+###############################################################################
+# Checks for libraries.
+###############################################################################
+
+echo
+echo "Initializing gettext:"
+AM_GNU_GETTEXT_VERSION([0.16.1])
+AM_GNU_GETTEXT([external])
+
+###############################################################################
+# Checks for header files.
+###############################################################################
+
+echo
+echo "System headers and functions:"
+
+# There is currently no workarounds in this package if some of
+# these headers are missing.
+AC_CHECK_HEADERS([fcntl.h limits.h sys/time.h],
+       [],
+       [AC_MSG_ERROR([Required header file(s) are missing.])])
+
+# If any of these headers are missing, things should still work correctly:
+AC_CHECK_HEADERS([assert.h errno.h byteswap.h sys/param.h sys/sysctl.h],
+       [], [], [
+#ifdef HAVE_SYS_PARAM_H
+#      include <sys/param.h>
+#endif
+])
+
+
+###############################################################################
+# Checks for typedefs, structures, and compiler characteristics.
+###############################################################################
+
+AC_HEADER_STDBOOL
+AC_C_INLINE
+AC_C_RESTRICT
+
+# The command line tool can copy high resolution timestamps if such
+# information is availabe in struct stat. Otherwise one second accuracy
+# is used. Most systems seem to have st_xtim but BSDs have st_xtimespec.
+AC_CHECK_MEMBERS([struct stat.st_atim.tv_nsec, struct stat.st_mtim.tv_nsec,
+       struct stat.st_atimespec.tv_nsec, struct stat.st_mtimespec.tv_nsec])
+
+# It is very unlikely that you want to build liblzma without
+# large file support.
+AC_SYS_LARGEFILE
+
+# At the moment, the only endian-dependent part should be the integrity checks.
+AC_C_BIGENDIAN
+
+
+###############################################################################
+# Checks for library functions.
+###############################################################################
+
+# Gnulib replacements as needed
+gl_GETOPT
+
+# Functions that are not mandatory i.e. we have alternatives for them
+# or we can just drop some functionality:
+AC_CHECK_FUNCS([memcpy memmove memset futimes futimesat])
+
+# Check how to find out the amount of physical memory in the system. The
+# lzma command line tool uses this to automatically limits its memory usage.
+# - sysconf() gives all the needed info on GNU+Linux and Solaris.
+# - BSDs use sysctl().
+AC_MSG_CHECKING([how to detect the amount of physical memory])
+AC_COMPILE_IFELSE([
+#include <unistd.h>
+int
+main()
+{
+       long i;
+       i = sysconf(_SC_PAGESIZE);
+       i = sysconf(_SC_PHYS_PAGES);
+       return 0;
+}
+], [
+       AC_DEFINE([HAVE_PHYSMEM_SYSCONF], 1,
+               [Define to 1 if the amount of physical memory can be detected
+               with sysconf(_SC_PAGESIZE) and sysconf(_SC_PHYS_PAGES).])
+       AC_MSG_RESULT([sysconf])
+], [
+AC_COMPILE_IFELSE([AC_LANG_SOURCE([[
+#include <sys/types.h>
+#ifdef HAVE_SYS_PARAM_H
+#      include <sys/param.h>
+#endif
+#include <sys/sysctl.h>
+int
+main()
+{
+       int name[2] = { CTL_HW, HW_PHYSMEM };
+       unsigned long mem;
+       size_t mem_ptr_size = sizeof(mem);
+       sysctl(name, 2, &mem, &mem_ptr_size, NULL, NULL);
+       return 0;
+}
+]])], [
+       AC_DEFINE([HAVE_PHYSMEM_SYSCTL], 1,
+               [Define to 1 if the amount of physical memory can be detected
+               with sysctl().])
+       AC_MSG_RESULT([sysctl])
+], [
+       AC_MSG_RESULT([unknown])
+])])
+
+# Check how to find out the number of available CPU cores in the system.
+# sysconf(_SC_NPROCESSORS_ONLN) works on most systems, except that BSDs
+# use sysctl().
+AC_MSG_CHECKING([how to detect the number of available CPU cores])
+AC_COMPILE_IFELSE([
+#include <unistd.h>
+int
+main()
+{
+       long i;
+       i = sysconf(_SC_NPROCESSORS_ONLN);
+       return 0;
+}
+], [
+       AC_DEFINE([HAVE_NCPU_SYSCONF], 1,
+               [Define to 1 if the number of available CPU cores can be
+               detected with sysconf(_SC_NPROCESSORS_ONLN).])
+       AC_MSG_RESULT([sysconf])
+], [
+AC_COMPILE_IFELSE([AC_LANG_SOURCE([[
+#include <sys/types.h>
+#ifdef HAVE_SYS_PARAM_H
+#      include <sys/param.h>
+#endif
+#include <sys/sysctl.h>
+int
+main()
+{
+       int name[2] = { CTL_HW, HW_NCPU };
+       int cpus;
+       size_t cpus_size = sizeof(cpus);
+       sysctl(name, 2, &cpus, &cpus_size, NULL, NULL);
+       return 0;
+}
+]])], [
+       AC_DEFINE([HAVE_NCPU_SYSCTL], 1,
+               [Define to 1 if the number of available CPU cores can be
+               detected with sysctl().])
+       AC_MSG_RESULT([sysctl])
+], [
+       AC_MSG_RESULT([unknown])
+])])
+
+
+###############################################################################
+# If using GCC, set some additional CFLAGS:
+###############################################################################
+
+Wno_uninitialized=no
+
+if test -n "$GCC" ; then
+       echo
+       echo "GCC extensions:"
+       gl_VISIBILITY
+       if test -n "$CFLAG_VISIBILITY" ; then
+               CFLAGS="$CFLAG_VISIBILITY $CFLAGS"
+       fi
+
+       # -Wno-uninitialized is needed with -Werror with SHA256 code
+       # to omit a bogus warning.
+       AC_MSG_CHECKING([if $CC accepts -Wno-uninitialized])
+       OLD_CFLAGS="$CFLAGS"
+       CFLAGS="$CFLAGS -Wno-uninitialized"
+       AC_COMPILE_IFELSE([void foo(void) { }], [Wno_uninitialized=yes])
+       CFLAGS="$OLD_CFLAGS"
+       AC_MSG_RESULT([$Wno_uninitialized])
+
+       # Enable as much warnings as possible. These commented warnings won't
+       # work for LZMA Utils though:
+       #   * -Wunreachable-code breaks several assert(0) cases, which are
+       #     backed up with "return LZMA_PROG_ERROR".
+       #   * -Wcast-qual would break various things where we need a non-const
+       #     pointer although we don't modify anything through it.
+       #   * -Wcast-align breaks optimized CRC32 and CRC64 implementation
+       #     on some architectures (not on x86), where this warning is bogus,
+       #     because we take care of correct alignment.
+       for NEW_FLAG in -Wextra -Wformat=2 -Winit-self -Wstrict-aliasing=2 \
+                       -Wfloat-equal -Wshadow -Wunsafe-loop-optimizations \
+                       -Wpointer-arith -Wbad-function-cast -Wwrite-strings \
+                       -Waggregate-return -Wstrict-prototypes \
+                       -Wold-style-definition -Wmissing-prototypes \
+                       -Wmissing-declarations -Wmissing-noreturn \
+                       -Wredundant-decls -Winline -Wdisabled-optimization
+       do
+               AC_MSG_CHECKING([if $CC accepts $NEW_FLAG])
+               OLD_CFLAGS="$CFLAGS"
+               CFLAGS="$NEW_FLAG $CFLAGS"
+               AC_COMPILE_IFELSE([void foo(void) { }], [
+                       AC_MSG_RESULT([yes])
+               ], [
+                       CFLAGS="$OLD_CFLAGS"
+                       AC_MSG_RESULT([no])
+               ])
+       done
+
+       AC_ARG_ENABLE([werror],
+               AC_HELP_STRING([--enable-werror], [Enable -Werror to abort
+                       compilation on all compiler warnings.]),
+               [], [enable_werror=no])
+       if test "x$enable_werror" = "xyes"; then
+               CFLAGS="-Werror $CFLAGS"
+       fi
+
+       # IIRC these work with all GCC versions that support -std=c99:
+       CFLAGS="-std=c99 -pedantic -Wall $CFLAGS"
+fi
+
+AM_CONDITIONAL([COND_WNO_UNINITIALIZED], test "x$Wno_uninitialized" = "xyes")
+
+
+###############################################################################
+# Create the makefiles and config.h
+###############################################################################
+
+echo
+
+# Don't build the lib directory at all if we don't need any replacement
+# functions.
+AM_CONDITIONAL([COND_GNULIB], test -n "$LIBOBJS")
+
+AC_CONFIG_FILES([
+       Doxyfile
+       Makefile
+       po/Makefile.in
+       lib/Makefile
+       src/Makefile
+       src/liblzma/lzma.pc
+       src/liblzma/Makefile
+       src/liblzma/api/Makefile
+       src/liblzma/common/Makefile
+       src/liblzma/check/Makefile
+       src/liblzma/lz/Makefile
+       src/liblzma/lzma/Makefile
+       src/liblzma/simple/Makefile
+       src/liblzma/subblock/Makefile
+       src/liblzma/rangecoder/Makefile
+       src/lzma/Makefile
+       src/lzmadec/Makefile
+       src/scripts/Makefile
+       tests/Makefile
+])
+
+AC_OUTPUT
diff --git a/doc/bugs.txt b/doc/bugs.txt
new file mode 100644 (file)
index 0000000..5557934
--- /dev/null
@@ -0,0 +1,46 @@
+
+Reporting bugs
+--------------
+
+    Naturally it is easiest for me if you already know what causes the
+    unexpected behavior. Even better if you have a patch to propose.
+    However, quite often the reason for unexpected behavior is unknown,
+    so below are a few things what to do before sending a bug report.
+
+    In case of a crash (usually segmentation violation):
+
+      1. Try to create a small example how to reprocude the issue.
+
+      2. If you are writing an application using liblzma or libzfile,
+         double check that you are using the libraries correctly (for
+         example, that you didn't forget to call lzma_init()). If it is
+         the command line tool included in LZMA Utils that is crashing,
+         ignore this step.
+
+      3. Compile LZMA Utils with debugging code using configure switch
+         `--enable-debug'. If you are using GCC as the compiler, use
+         CFLAGS='-O0 -ggdb'. Don't strip the resulting binaries.
+
+      4. Turn on core dumps. The exact command depends on your shell;
+         for example in GNU bash it is done with `ulimit -c unlimited',
+         and in tcsh with `limit coredumpsize unlimited'.
+
+      5. Try to reproduce the suspected bug. If you get `assertion failed'
+         message, be sure to include the complete message in your bug
+         report. If the application leaves a coredump, get a backtrace
+         using gdb:
+           $ gdb /path/to/app-binary   # Loads the app to the debugger.
+           (gdb) core core   # Opens the coredump.
+           (gdb) bt   # Prints the backtrace. Copy & paste to bug report.
+           (gdb) quit   # Quits gdb.
+
+    Send your bug report to Lasse Collin <lasse.collin@tukaani.org>. Don't
+    send the core dump file or the actual executables. If you have a small
+    example file(s) (total size less than 100 KiB), please include it/them
+    as an attachment.
+
+    Do NOT complain about problems with LZMA Utils to Igor Pavlov.
+    Although the code of LZMA Utils is derived from his code, there are
+    a lot of changes, which may have introduced bugs not present in
+    the original version.
+
diff --git a/doc/faq.txt b/doc/faq.txt
new file mode 100644 (file)
index 0000000..d01cf91
--- /dev/null
@@ -0,0 +1,247 @@
+
+LZMA Utils FAQ
+--------------
+
+    Copyright (C) 2007 Lasse Collin
+
+    Copying and distribution of this file, with or without modification,
+    are permitted in any medium without royalty provided the copyright
+    notice and this notice are preserved.
+
+
+Q:  What are LZMA, LZMA Utils, lzma, .lzma, liblzma, LZMA SDK, LZMA_Alone,
+    7-Zip and p7zip?
+
+A:  LZMA stands for Lempel-Ziv-Markov chain-Algorithm. LZMA is the name
+    of the compression algorithm designed by Igor Pavlov. He is the author
+    of 7-Zip, which is a great LGPL'd compression tool for Microsoft
+    Windows operating systems. In addition to 7-Zip itself, also LZMA SDK
+    is available on the website of 7-Zip. LZMA SDK contains LZMA
+    implementations in C++, Java and C#. The C++ version is the original
+    implementation which is used also in 7-Zip itself.
+
+    Excluding the unrar plugin, 7-Zip is free software (free as in
+    freedom). Thanks to this, it was possible to port it to POSIX
+    platforms. The port was done and is maintained by myspace (TODO:
+    myspace's real name?). p7zip is a port of 7-Zip's command line version;
+    p7zip doesn't include the 7-Zip's GUI.
+
+    In POSIX world, users are used to gzip and bzip2 command line tools.
+    Developers know APIs of zlib and libbzip2. LZMA Utils try to ease
+    adoption of LZMA on free operating systems by providing a compression
+    library and a set of command line tools. The library is called liblzma.
+    It provides a zlib-like API making it easy to adapt LZMA compression in
+    existing applications. The main command line tool is known as lzma,
+    whose command line syntax is very similar to that of gzip and bzip2.
+
+    The original command line tool from LZMA SDK (lzma.exe) was found from
+    a directory called LZMA_Alone in the LZMA SDK. It used a simple header
+    format in .lzma files. This format was also used by LZMA Utils up to
+    and including 4.32.x. In LZMA Utils documentation, LZMA_Alone refers
+    to both the file format and the command line tool from LZMA SDK.
+
+    Because of various limitations of the LZMA_Alone file format, a new
+    file format was developed. Extending some existing format such as .gz
+    used by gzip was considered, but these formats were found to be too
+    limited. The filename suffix for the new .lzma format is `.lzma'. The
+    same suffix is also used for files in the LZMA_Alone format. To make
+    the transition to the new format as transparent as possible, LZMA Utils
+    support both the new and old formats transparently.
+
+    7-Zip and LZMA SDK: <http://7-zip.org/>
+    p7zip: <http://p7zip.sourceforge.net/>
+    LZMA Utils: <http://tukaani.org/lzma/>
+
+
+Q:  What LZMA implementations there are available?
+
+A:  LZMA SDK contains implementations in C++, Java and C#. The C++ version
+    is the original implementation which is part of 7-Zip. LZMA SDK
+    contains also a small LZMA decoder in C.
+
+    A port of LZMA SDK to Pascal was made by Alan Birtles
+    <http://www.birtles.org.uk/programming/>. It should work with
+    multiple Pascal programming language implementations.
+
+    LZMA Utils includes liblzma, which is directly based on LZMA SDK.
+    liblzma is written in C (C99, not C89). In contrast to C++ callback
+    API used by LZMA SDK, liblzma uses zlib-like stateful C API. I do not
+    want to comment whether both/former/latter/neither API(s) are good or
+    bad. The only reason to implement a zlib-like API was, that many
+    developers are already familiar with zlib, and very many applications
+    already use zlib. Having a similar API makes it easier to include LZMA
+    support in existing applications.
+
+    See also <http://en.wikipedia.org/wiki/LZMA#External_links>.
+
+
+Q:  Which file formats are supported by LZMA Utils?
+
+A:  Even when the raw LZMA stream is always the same, it can be wrapped
+    in different container formats. The preferred format is the new .lzma
+    format. It has magic bytes (the first six bytes: 0xFF 'L' 'Z' 'M'
+    'A' 0x00). The format supports chaining up to seven filters filters,
+    splitting data to multiple blocks for easier multi-threading and rough
+    random-access reading. The file integrity is verified using CRC32,
+    CRC64, or SHA256, and by verifying the uncompressed size of the file.
+
+    LZMA SDK includes a tool called LZMA_Alone. It supports uses a
+    primitive header which includes only the mandatory stream information
+    required by the LZMA decoder. This format can be both read and
+    written by liblzma and the command line tool (use --format=alone to
+    create such files).
+
+    .7z is the native archive format used by 7-Zip. This format is not
+    supported by liblzma, and probably will never be supported. You
+    should use e.g. p7zip to extract .7z files.
+
+    It is possible to implement custom file formats by using raw filter
+    mode in liblzma. In this mode the application needs to store the filter
+    properties and provide them to liblzma before starting to uncompress
+    the data.
+
+
+Q:  How can I identify files containing LZMA compressed data?
+
+A:  The preferred filename suffix for .lzma files is `.lzma'. `.tar.lzma'
+    may be abbreviated to `.tlz'. The same suffixes are used for files in
+    LZMA_Alone format. In practice this should be no problem since tools
+    included in LZMA Utils support both formats transparently.
+
+    Checking the magic bytes is easy way to detect files in the new .lzma
+    format (the first six bytes: 0xFF 'L' 'Z' 'M' 'A' 0x00). The "file"
+    command version FIXME contains magic strings for this format.
+
+    The old LZMA_Alone format has no magic bytes. Its header cannot contain
+    arbitrary bytes, thus it is possible to make a guess. Unfortunately the
+    guessing is usually too hard to be reliable, so don't try it unless you
+    are desperate.
+
+
+Q:  Does the lzma command line tool support sparse files?
+
+A:  Sparse files can (of course) be compressed like normal files, but
+    uncompression will not restore sparseness of the file. Use an archiver
+    tool to take care of sparseness before compressing the data with lzma.
+
+    The reason for this is that archiver tools handle files, while
+    compression tools handle streams or buffers. Being a sparse file is
+    a property of the file on the disk, not a property of the stream or
+    buffer.
+
+
+Q:  Can I recover parts of a broken LZMA file (e.g. corrupted CD-R)?
+
+A:  With LZMA_Alone and single-block .lzma files, you can uncompress the
+    file until you hit the first broken byte. The data after the broken
+    position is lost. LZMA relies on the uncompression history, and if
+    bytes are missing in the middle of the file, it is impossible to
+    reliably continue after the broken section.
+
+    With multi-block .lzma files it may be possible to locale the next
+    block in the file and continue decoding there. A limited recovery
+    tool for this kind of situations is planned.
+
+
+Q:  Is LZMA patented?
+
+A:  No, the authors are not aware of any patents that could affect LZMA.
+    However, due to nature of software patents, the authors cannot
+    guarantee, that LZMA isn't affected by any third party patent.
+
+
+Q:  Where can I find documentation about how LZMA works as an algorithm?
+
+A:  Read the source code, Luke. There is no documentation about LZMA
+    internals. It is possible that Igor Pavlov is the only person on
+    the Earth that completely knows and understands the algorithm.
+
+    You could begin by downloading LZMA SDK, and start reading from
+    the LZMA decoder to get some idea about the bitstream format.
+    Before you begin, you should know the basics of LZ77 and
+    range coding algorithms. LZMA is based on LZ77, but LZMA is
+    *a lot* more complex. Range coding is used to compress the
+    final bitstream like Huffman coding is used in Deflate.
+
+
+Q:  What are filters?
+
+A:  In context of .lzma files, a filter means an implementation of a
+    compression algorithm. The primary filter is LZMA, which is why
+    the names of the tools contain the letters LZMA.
+
+    liblzma and the new .lzma format support also other filters than LZMA.
+    There are different types of filters, which are suitable for different
+    types of data. Thus, to select the optimal filter and settings, the
+    type of the input data being compressed needs to be known.
+
+    Some filters are most useful when combined with another filter like
+    LZMA. These filters increase redundancy in the data, without changing
+    the size of the data, by taking advantage of properties specific to
+    the data being compressed.
+
+    So far, all the filters are always reversible. That is, no matter what
+    data you pass to a filter encoder, it can be always defiltered back to
+    the original form. Because of this, it is safe to compress for example
+    a software package that contains other file types than executables
+    using a filter specific to the architechture of the package being
+    compressed.
+
+    The old LZMA_Alone format supports only the LZMA filter.
+
+
+Q:  I cannot find BCJ and BCJ2 filters. Don't they exist in liblzma?
+
+A:  BCJ filter is called "x86" in liblzma. BCJ2 is not included,
+    because it requires using more than one encoded output stream.
+
+
+Q:  Can I use LZMA in proprietary, non-free applications?
+
+A:  liblzma is under the GNU LGPL version 2.1 or (at your opinion) any
+    later version. To summarise (*NOTE* This summary is not legally
+    binding, that is, it doesn't give you any extra permissions compared
+    to the LGPL. Read the GNU LGPL carefully for the exact license
+    conditions.):
+      * All the changes made into the library itself must be published
+        under the same license.
+      * End users must be able to replace the used liblzma. Easiest way
+        to assure this is to link dynamically against liblzma so users
+        can replace the shared library file if they want.
+      * You must make it clear to your users, that your application uses
+        liblzma, and that liblzma is free software under the GNU LGPL.
+        A copy of GNU LGPL must be included.
+
+    LZMA SDK contains a special exception which allows linking *unmodified*
+    code statically with a non-free application. This exception does *not*
+    apply to liblzma.
+
+    As an alternative, you can support the development of LZMA and 7-Zip
+    by buying a proprietary license from Igor Pavlov. See homepage of
+    LZMA SDK <http://7-zip.org/sdk.html> for more information. Note that
+    having a proprietary license from Igor Pavlov doesn't allow you to use
+    liblzma in a way that contradicts with the GNU LGPL, because liblzma
+    contains code that is not copyrighted by Igor Pavlov. Please contact
+    both Lasse Collin and Igor Pavlov if the license conditions of liblzma
+    are not suitable for you.
+
+
+Q:  I would like to help. What can I do?
+
+A:  See the TODO file. Please contact Lasse Collin before starting to do
+    anything, because it is possible that someone else is already working
+    on the same thing.
+
+
+Q:  How can I contact the authors?
+
+A:  Lasse Collin is the maintainer of LZMA Utils. You can contact him
+    either via IRC (Larhzu on #tukaani at Freenode or IRCnet). Email
+    should work too, <lasse.collin@tukaani.org>.
+
+    Igor Pavlov is the father of LZMA. He is the author of 7-Zip
+    and LZMA SDK. <http://7-zip.org/>
+
+    NOTE: Please don't bother Igor Pavlov with questions specific
+    to LZMA Utils.
+
diff --git a/doc/file-format.txt b/doc/file-format.txt
new file mode 100644 (file)
index 0000000..4a90a67
--- /dev/null
@@ -0,0 +1,1861 @@
+
+The .lzma File Format
+---------------------
+
+        0. Preface
+          0.1. Copyright Notices
+          0.2. Changes
+        1. Conventions
+          1.1. Byte and Its Representation
+          1.2. Multibyte Integers
+        2. Stream
+          2.1. Stream Types
+            2.1.1. Single-Block Stream
+            2.1.2. Multi-Block Stream
+          2.2. Stream Header
+            2.2.1. Header Magic Bytes
+            2.2.2. Stream Flags
+            2.2.3. CRC32
+        3. Block
+          3.1. Block Header
+            3.1.1. Block Flags
+            3.1.2. Compressed Size
+            3.1.3. Uncompressed Size
+            3.1.4. List of Filter Flags
+              3.1.4.1. Misc
+              3.1.4.2. External ID
+              3.1.4.3. External Size of Properties
+              3.1.4.4. Filter Properties
+            3.1.5. CRC32
+            3.1.6. Header Padding
+          3.2. Compressed Data
+          3.3. Block Footer
+            3.3.1. Check
+            3.3.2. Stream Footer
+              3.3.2.1. Uncompressed Size
+              3.3.2.2. Backward Size
+              3.3.2.3. Stream Flags
+              3.3.2.4. Footer Magic Bytes
+            3.3.3. Footer Padding
+        4. Filters
+          4.1. Detecting when All Data Has Been Decoded
+            4.1.1. With Uncompressed Size
+            4.1.2. With End of Input
+            4.1.3. With End of Payload Marker
+          4.2. Alignment
+          4.3. Filters
+            4.3.1. Copy
+            4.3.2. Subblock
+              4.3.2.1. Format of the Encoded Output
+            4.3.3. Delta
+              4.3.3.1. Format of the Encoded Output
+            4.3.4. LZMA
+              4.3.4.1. LZMA Properties
+              4.3.4.2. Dictionary Flags
+            4.3.5. Branch/Call/Jump Filters for Executables
+        5. Metadata
+          5.1. Metadata Flags
+          5.2. Size of Header Metadata Block
+          5.3. Total Size
+          5.4. Uncompressed Size
+          5.5. Index
+            5.5.1. Number of Data Blocks
+            5.5.2. Total Sizes
+            5.5.3. Uncompressed Sizes
+          5.6. Extra
+            5.6.1. 0x00: Dummy/Padding
+            5.6.2. 0x01: OpenPGP Signature
+            5.6.3. 0x02: Filter Information
+            5.6.4. 0x03: Comment
+            5.6.5. 0x04: List of Checks
+            5.6.6. 0x05: Original Filename
+            5.6.7. 0x07: Modification Time
+            5.6.8. 0x09: High-Resolution Modification Time
+            5.6.9. 0x0B: MIME Type
+            5.6.10. 0x0D: Homepage URL
+        6. Custom Filter and Extra Record IDs
+          6.1. Reserved Custom Filter ID Ranges
+        7. Cyclic Redundancy Checks
+        8. References
+          8.1. Normative References
+          8.2. Informative References
+
+
+0. Preface
+
+        This document describes the .lzma file format (filename suffix
+        `.lzma', MIME type `application/x-lzma'). It is intended that
+        this format replace the format used by the LZMA_Alone tool
+        included in LZMA SDK up to and including version 4.43.
+
+        IMPORTANT:  The version described in this document is a
+                    draft, NOT a final, official version. Changes
+                    are possible.
+
+
+0.1. Copyright Notices
+
+        Copyright (C) 2006, 2007 Lasse Collin <lasse.collin@tukaani.org>
+        Copyright (C) 2006 Ville Koskinen <w-ber@iki.fi>
+
+        Copying and distribution of this file, with or without
+        modification, are permitted in any medium without royalty
+        provided the copyright notice and this notice are preserved.
+        Modified versions must be marked as such.
+
+        All source code examples given in this document are put into
+        the public domain by the authors of this document.
+
+        Thanks for helping with this document goes to Igor Pavlov,
+        Mark Adler and Mikko Pouru.
+
+
+0.2. Changes
+
+        Last modified: 2007-12-02 22:40+0200
+
+        (A changelog will be kept once the first official version
+        is made.)
+
+
+1. Conventions
+
+        The keywords `must', `must not', `required', `should',
+        `should not', `recommended', `may', and `optional' in this
+        document are to be interpreted as described in [RFC-2119].
+        These words are not capitalized in this document.
+
+        Indicating a warning means displaying a message, returning
+        appropriate exit status, or something else to let the user
+        know that something worth warning occurred. The operation
+        should still finish if a warning is indicated.
+
+        Indicating an error means displaying a message, returning
+        appropriate exit status, or something else to let the user
+        know that something prevented successfully finishing the
+        operation. The operation must be aborted once an error has
+        been indicated.
+
+
+1.1. Byte and Its Representation
+
+        In this document, byte is always 8 bits.
+
+        A `nul byte' has all bits unset. That is, the value of a nul
+        byte is 0x00.
+
+        To represent byte blocks, this document uses notation that
+        is similar to the notation used in [RFC-1952]:
+
+            +-------+
+            |  Foo  |   One byte.
+            +-------+
+
+            +---+---+
+            |  Foo  |   Two bytes; that is, some of the vertical bars
+            +---+---+   can be missing.
+
+            +=======+
+            |  Foo  |   Zero or more bytes.
+            +=======+
+
+        In this document, a boxed byte or a byte sequence declared
+        using this notation is called `a field'. The example field
+        above would be called called `the Foo field' or plain `Foo'.
+
+
+1.2. Multibyte Integers
+
+        Multibyte integers of static length, such as CRC values,
+        are stored in little endian byte order (least significant
+        byte first).
+
+        When smaller values are more likely than bigger values (e.g.
+        file sizes), multibyte integers are encoded in a simple
+        variable-length representation:
+          - Numbers in the range [0, 127] are copied as is, and take
+            one byte of space.
+          - Bigger numbers will occupy two or more bytes. The lowest
+            seven bits of every byte are used for data; the highest
+            (eighth) bit indicates either that
+              0) the byte is in the middle of the byte sequence, or
+              1) the byte is the first or the last byte.
+
+        For now, the value of the variable-length integers is limited
+        to 63 bits, which limits the encoded size of the integer to
+        nine bytes. These limits may be increased in future if needed.
+
+        Note that the encoding is not as optimal as it could be. For
+        example, it is possible to encode the number 42 using any
+        number of bytes between one and nine. This is convenient
+        for non-streamed encoders, that write Compressed Size or
+        Uncompressed Size fields to the Block Header (see Section 3.1)
+        after the Compressed Data field is written to the disk.
+
+        In several situations, the decoder needs to compare that two
+        fields contain identical information. When comparing fields
+        using the encoding described in this Section, the decoder must
+        consider two fields identical if their decoded values are
+        identical; it does not matter if the encoded variable-length
+        representations differ.
+
+        The following C code illustrates encoding and decoding 63-bit
+        variables; the highest bit of uint64_t must be unset. The
+        functions return the number of bytes occupied by the integer
+        (1-9), or zero on error.
+
+            #include <sys/types.h>
+            #include <inttypes.h>
+
+            size_t
+            encode(uint8_t buf[static 9], uint64_t num)
+            {
+                if (num >= (UINT64_C(1) << (9 * 7)))
+                    return 0;
+                if (num <= 0x7F) {
+                    buf[0] = num;
+                    return 1;
+                }
+                buf[0] = (num & 0x7F) | 0x80;
+                num >>= 7;
+                size_t i = 1;
+                while (num >= 0x80) {
+                    buf[i++] = num & 0x7F;
+                    num >>= 7;
+                }
+                buf[i++] = num | 0x80;
+                return i;
+            }
+
+            size_t
+            decode(const uint8_t buf[], size_t size_max, uint64_t *num)
+            {
+                if (size_max == 0)
+                    return 0;
+                if (size_max > 9)
+                    size_max = 9;
+                *num = buf[0] & 0x7F;
+                if (!(buf[0] & 0x80))
+                    return 1;
+                size_t i = 1;
+                do {
+                    if (i == size_max)
+                        return 0;
+                    *num |= (uint64_t)(buf[i] & 0x7F) << (7 * i);
+                } while (!(buf[i++] & 0x80));
+                return i;
+            }
+
+            size_t
+            decode_reverse(const uint8_t buf[], size_t size_max,
+                    uint64_t *num)
+            {
+                if (size_max == 0)
+                    return 0;
+                const size_t end = size_max > 9 ? size_max - 9 : 0;
+                size_t i = size_max - 1;
+                *num = buf[i] & 0x7F;
+                if (!(buf[i] & 0x80))
+                    return 1;
+                do {
+                    if (i-- == end)
+                        return 0;
+                    *num <<= 7;
+                    *num |= buf[i] & 0x7F;
+                } while (!(buf[i] & 0x80));
+                return size_max - i;
+            }
+
+
+2. Stream
+
+        +========+========+========+
+        | Stream | Stream | Stream | ...
+        +========+========+========+
+
+        A file contains usually only one Stream. However, it is
+        possible to concatenate multiple Streams together with no
+        additional processing. It is up to the implementation to
+        decide if the decoder will continue decoding from the next
+        Stream once the end of the first Stream has been reached.
+
+
+2.1. Stream Types
+
+        There are two types of Streams: Single-Block Streams and
+        Multi-Block Streams. Decoders conforming to this specification
+        must support at least Single-Block Streams. Supporting
+        Multi-Block Streams is optional. If the decoder supports only
+        Single-Block Streams, the documentation of the decoder should
+        mention this fact clearly.
+
+
+2.1.1. Single-Block Stream
+
+        +===============+============+
+        | Stream Header | Data Block |
+        +===============+============+
+
+        As the name says, a Single-Block Stream has exactly one Block.
+        The Block must be a Data Block; Metadata Blocks are not allowed
+        in Single-Block Streams.
+
+
+2.1.2. Multi-Block Stream
+
+        +===============+=======================+
+        | Stream Header | Header Metadata Block |
+        +===============+=======================+
+
+             +============+     +============+=======================+
+        ---> | Data Block | ... | Data Block | Footer Metadata Block |
+             +============+     +============+=======================+
+
+        Notes:
+          - Stream Header is mandatory.
+          - Header Metadata Block is optional.
+          - Each Multi-Block Stream has at least one Data Block. The
+            maximum number of Data Blocks is not limited.
+          - Footer Metadata Block is mandatory.
+
+
+2.2. Stream Header
+
+        +---+---+---+---+---+---+--------------+--+--+--+--+
+        |  Header Magic Bytes   | Stream Flags |   CRC32   |
+        +---+---+---+---+---+---+--------------+--+--+--+--+
+
+
+2.2.1. Header Magic Bytes
+
+        The first six (6) bytes of the Stream are so called Header
+        Magic Bytes. They can be used to identify the file type.
+
+            Using a C array and ASCII:
+            const uint8_t HEADER_MAGIC[6]
+                    = { 0xFF, 'L', 'Z', 'M', 'A', 0x00 };
+
+            In plain hexadecimal:
+            FF 4C 5A 4D 41 00
+
+        Notes:
+          - The first byte (0xFF) was chosen so that the files cannot
+            be erroneously detected as being in LZMA_Alone format, in
+            which the first byte is in the the range [0x00, 0xE0].
+          - The sixth byte (0x00) was chosen to prevent applications
+            from misdetecting the file as a text file.
+
+
+2.2.2. Stream Flags
+
+        Bit(s)  Mask  Description
+         0-2    0x07  Type of Check (see Section 3.3.1):
+                          ID    Size      Check name
+                          0x00   0 bytes  None
+                          0x01   4 bytes  CRC32
+                          0x02   4 bytes  (Reserved)
+                          0x03   8 bytes  CRC64
+                          0x04  16 bytes  (Reserved)
+                          0x05  32 bytes  SHA-256
+                          0x06  32 bytes  (Reserved)
+                          0x07  64 bytes  (Reserved)
+          3     0x08  The CRC32 field is present in Block Headers.
+          4     0x10  If unset, this is a Single-Block Stream; if set,
+                      this is a Multi-Block Stream.
+         5-7    0xE0  Reserved for future use; must be zero for now.
+
+        Implementations must support at least the Check IDs 0x00 (None)
+        and 0x01 (CRC32). Supporting other Check IDs is optional. If an
+        unsupported Check is used, the decoder must indicate a warning
+        or error.
+
+        If any reserved bit is set, the decoder must indicate an error.
+        It is possible that there is a new field present which the
+        decoder is not aware of, and can thus parse the Stream Header
+        incorrectly.
+
+
+2.2.3. CRC32
+
+        The CRC32 is calculated from the Stream Flags field. It is
+        stored as an unsigned 32-bit little endian integer. If the
+        calculated value does not match the stored one, the decoder
+        must indicate an error.
+
+        Note that this field is always present; the bit in Stream Flags
+        controls only presence of CRC32 in Block Headers.
+
+
+3. Block
+
+        +==============+=================+==============+
+        | Block Header | Compressed Data | Block Footer |
+        +==============+=================+==============+
+
+        There are two types of Blocks:
+          - Data Blocks hold the actual compressed data.
+          - Metadata Blocks hold the Index, Extra, and a few other
+            non-data fields (see Section 5).
+
+        The type of the Block is indicated by the corresponding bit
+        in the Block Flags field (see Section 3.1.1).
+
+
+3.1. Block Header
+
+        +------+------+=================+===================+
+        | Block Flags | Compressed Size | Uncompressed Size |
+        +------+------+=================+===================+
+
+             +======================+--+--+--+--+================+
+        ---> | List of Filter Flags |   CRC32   | Header Padding |
+             +======================+--+--+--+--+================+
+
+
+3.1.1. Block Flags
+
+        The first byte of the Block Flags field is a bit field:
+
+            Bit(s)  Mask  Description
+             0-2    0x07  Number of filters (0-7)
+              3     0x08  Use End of Payload Marker (even if
+                          Uncompressed Size is stored to Block Header).
+              4     0x10  The Compressed Size field is present.
+              5     0x20  The Uncompressed Size field is present.
+              6     0x40  Reserved for future use; must be zero for now.
+              7     0x80  This is a Metadata Block.
+
+        The second byte of the Block Flags field is also a bit field:
+
+            Bit(s)  Mask  Description
+             0-4    0x1F  Size of the Header Padding field (0-31 bytes)
+             5-7    0xE0  Reserved for future use; must be zero for now.
+
+        The decoder must indicate an error if End of Payload Marker
+        is not used and Uncompressed Size is not stored to the Block
+        Header. Because of this, the first byte of Block Flags can
+        never be a nul byte. This is useful when detecting beginning
+        of the Block after Footer Padding (see Section 3.3.3).
+
+        If any reserved bit is set, the decoder must indicate an error.
+        It is possible that there is a new field present which the
+        decoder is not aware of, and can thus parse the Block Header
+        incorrectly.
+
+
+3.1.2. Compressed Size
+
+        This field is present only if the appropriate bit is set in
+        the Block Flags field (see Section 3.1.1).
+
+        This field contains the size of the Compressed Data field.
+        The size is stored using the encoding described in Section 1.2.
+        If the Compressed Size does not match the real size of the
+        Compressed Data field, the decoder must indicate an error.
+
+        Having the Compressed Size field in the Block Header can be
+        useful for multithreaded decoding when seeking is not possible.
+        If the Blocks are small enough, the decoder can read multiple
+        Blocks into its internal buffer, and decode the Blocks in
+        parallel.
+
+        Compressed Size can also be useful when seeking forwards to
+        a specific location in streamed mode: the decoder can quickly
+        skip over irrelevant Blocks, without decoding them.
+
+
+3.1.3. Uncompressed Size
+
+        This field is present only if the appropriate bit is set in
+        the Block Flags field (see Section 3.1.1).
+
+        The Uncompressed Size field contains the size of the Block
+        after uncompressing.
+
+        Storing Uncompressed Size serves several purposes:
+          - The decoder will know when all of the data has been
+            decoded without an explicit End of Payload Marker.
+          - The decoder knows how much memory it needs to allocate
+            for a temporary buffer in multithreaded mode.
+          - Simple error detection: wrong size indicates a broken file.
+          - Sometimes it is useful to know the file size without
+            uncompressing the file.
+
+        It should be noted that the only reliable way to find out what
+        the real uncompressed size is is to uncompress the Block,
+        because the Block Header and Metadata Block fields may contain
+        (intentionally or unintentionally) invalid information.
+
+        Uncompressed Size is stored using the encoding described in
+        Section 1.2. If the Uncompressed Size does not match the
+        real uncompressed size, the decoder must indicate an error.
+
+
+3.1.4. List of Filter Flags
+
+        +================+================+     +================+
+        | Filter 0 Flags | Filter 1 Flags | ... | Filter n Flags |
+        +================+================+     +================+
+
+        The number of Filter Flags fields is stored in the Block Flags
+        field (see Section 3.1.1). As a special case, if the number of
+        Filter Flags fields is zero, it is equivalent to having the
+        Copy filter as the only filter.
+
+        The format of each Filter Flags field is as follows:
+
+            +------+=============+=============================+
+            | Misc | External ID | External Size of Properties |
+            +------+=============+=============================+
+
+                 +===================+
+            ---> | Filter Properties |
+                 +===================+
+
+        The list of officially defined Filter IDs and the formats of
+        their Filter Properties are described in Section 4.3.
+
+
+3.1.4.1. Misc
+
+        To save space, the most commonly used Filter IDs and the
+        Size of Filter Properties are encoded in a single byte.
+        Depending on the contents of the Misc field, Filter ID is
+        the value of the Misc or External ID field.
+
+            Value          Filter ID        Size of Filter Properties
+            0x00 - 0x1F    Misc             0 bytes
+            0x20 - 0x3F    Misc             1 byte
+            0x40 - 0x5F    Misc             2 bytes
+            0x60 - 0x7F    Misc             3 bytes
+            0x80 - 0x9F    Misc             4 bytes
+            0xA0 - 0xBF    Misc             5 bytes
+            0xC0 - 0xDF    Misc             6 bytes
+            0xE0 - 0xFE    External ID      0-30 bytes
+            0xFF           External ID      External Size of Properties
+
+        The following code demonstrates parsing the Misc field and,
+        when needed, the External ID and External Size of Properties
+        fields.
+
+            uint64_t id;
+            uint64_t properties_size;
+            uint8_t misc = read_byte();
+
+            if (misc >= 0xE0) {
+                id = read_variable_length_integer();
+
+                if (misc == 0xFF)
+                    properties_size = read_variable_length_integer();
+                else
+                    properties_size = misc - 0xE0;
+
+            } else {
+                id = misc;
+                properties_size = misc / 0x20;
+            }
+
+
+3.1.4.2. External ID
+
+        This field is present only if the Misc field contains a value
+        that indicates usage of External ID. The External ID is stored
+        using the encoding described in Section 1.2.
+
+
+3.1.4.3. External Size of Properties
+
+        This field is present only if the Misc field contains a value
+        that indicates usage of External Size of Properties. The size
+        of Filter Properties is stored using the encoding described in
+        Section 1.2.
+
+
+3.1.4.4. Filter Properties
+
+        Size of this field depends on the Misc field (Section 3.1.4.1)
+        and, if present, External Size of Properties field (Section
+        3.1.4.3). The format of this field is depends on the selected
+        filter; see Section 4.3 for details.
+
+
+3.1.5. CRC32
+
+        This field is present only if the appropriate bit is set in
+        the Stream Flags field (see Section 2.2.2).
+
+        The CRC32 is calculated over everything in the Block Header
+        field except the Header Padding field and the CRC32 field
+        itself. It is stored as an unsigned 32-bit little endian
+        integer. If the calculated value does not match the stored
+        one, the decoder must indicate an error.
+
+
+3.1.6. Header Padding
+
+        This field contains as many nul bytes as indicated by the value
+        stored in the Header Flags field. If the Header Padding field
+        contains any non-nul bytes, the decoder must indicate an error.
+
+        The intent of the Header Padding field is to allow alignment
+        of Compressed Data. The usefulness of alignment is described
+        in Section 4.3.
+
+
+3.2. Compressed Data
+
+        The format of Compressed Data depends on Block Flags and List
+        of Filter Flags. Excluding the descriptions of the simplest
+        filters in Section 4, the format of the filter-specific encoded
+        data is out of scope of this document.
+
+        Note a special case: if End of Payload Marker (see Section
+        3.1.1) is not used and Uncompressed Size is zero, the size
+        of the Compressed Data field is always zero.
+
+
+3.3. Block Footer
+
+        +=======+===============+================+
+        | Check | Stream Footer | Footer Padding |
+        +=======+===============+================+
+
+
+3.3.1. Check
+
+        The type and size of the Check field depends on which bits
+        are set in the Stream Flags field (see Section 2.2.2).
+
+        The Check, when used, is calculated from the original
+        uncompressed data. If the calculated Check does not match the
+        stored one, the decoder must indicate an error. If the selected
+        type of Check is not supported by the decoder, it must indicate
+        a warning or error.
+
+
+3.3.2. Stream Footer
+
+        +===================+===============+--------------+
+        | Uncompressed Size | Backward Size | Stream Flags |
+        +===================+===============+--------------+
+
+             +----------+---------+
+        ---> | Footer Magic Bytes |
+             +----------+---------+
+
+        Stream Footer is present only in
+          - Data Block of a Single-Block Stream; and
+          - Footer Metadata Block of a Multi-Block Stream.
+
+        The Stream Footer field is placed inside Block Footer, because
+        no padding is allowed between Check and Stream Footer.
+
+
+3.3.2.1. Uncompressed Size
+
+        This field is present only in the Data Block of a Single-Block
+        Stream if Uncompressed Size is not stored to the Block Header
+        (see Section 3.1.1). Without the Uncompressed Size field in
+        Stream Footer it would not be possible to quickly find out
+        the Uncompressed Size of the Stream in all cases.
+
+        Uncompressed Size is stored using the encoding described in
+        Section 1.2. If the stored value does not match the real
+        uncompressed size of the Single-Block Stream, the decoder must
+        indicate an error.
+
+
+3.3.2.2. Backward Size
+
+        This field contains the total size of the Block Header,
+        Compressed Data, Check, and Uncompressed Size fields. The
+        value is stored using the encoding described in Section 1.2.
+        If the Backward Size does not match the real total size of
+        the appropriate fields, the decoder must indicate an error.
+
+        Implementations reading the Stream backwards should notice
+        that the value in this field can never be zero.
+
+
+3.3.2.3. Stream Flags
+
+        This is a copy of the Stream Flags field from the Stream
+        Header. The information stored to Stream Flags is needed
+        when parsing the Stream backwards.
+
+
+3.3.2.4. Footer Magic Bytes
+
+        As the last step of the decoding process, the decoder must
+        verify the existence of Footer Magic Bytes. If they are not
+        found, an error must be indicated.
+
+            Using a C array and ASCII:
+            const uint8_t FOOTER_MAGIC[2] = { 'Y', 'Z' };
+
+            In hexadecimal:
+            59 5A
+
+        The primary reason to have Footer Magic Bytes is to make
+        it easier to detect incomplete files quickly, without
+        uncompressing. If the file does not end with Footer Magic Bytes
+        (excluding Footer Padding described in Section 3.3.3), it
+        cannot be undamaged, unless someone has intentionally appended
+        garbage after the end of the Stream. (Appending garbage at the
+        end of the file does not prevent uncompressing the file, but
+        may give a warning or error depending on the decoder
+        implementation.)
+
+
+3.3.3. Footer Padding
+
+        In certain situations it is convenient to be able to pad
+        Blocks or Streams to be multiples of, for example, 512 bytes.
+        Footer Padding makes this possible. Note that this is in no
+        way required to enforce alignment in the way described in
+        Section 4.3; the Header Padding field is enough for that.
+
+        When Footer Padding is used, it must contain only nul bytes.
+        Any non-nul byte should be considered as the beginning of
+        a new Block or Stream.
+
+        The possibility of Padding should be taken into account when
+        designing an application that wants to find out information
+        about a Stream by parsing Footer Metadata Block.
+
+        Support for Padding was inspired by a related note in
+        [GNU-tar].
+
+
+4. Filters
+
+        The Block Flags field defines how many filters are used. When
+        more than one filter is used, the filters are chained; that is,
+        the output of one filter is the input of another filter. The
+        following figure illustrates the direction of data flow.
+
+                    v   Uncompressed Data   ^
+                    |       Filter 0        |
+            Encoder |       Filter 1        | Decoder
+                    |         ...           |
+                    |       Filter n        |
+                    v    Compressed Data    ^
+
+        The filters are independent from each other, except that they
+        must cooperate a little to make it possible, in all cases, to
+        detect when all of the data has been decoded. In addition, the
+        filters should cooperate in the encoder to keep the alignment
+        optimal.
+
+
+4.1. Detecting when All Data Has Been Decoded
+
+        There must be a way for the decoder to detect when all of the
+        Compressed Data has been decoded. This is simple when only
+        one filter is used, but a bit more complex when multiple
+        filters are chained.
+
+        This file format supports three methods to detect when all of
+        the data has been decoded:
+          - Uncompressed size
+          - End of Input
+          - End of Payload Marker
+
+        In both encoder and decoder, filters are initialized starting
+        from the first filter in the chain. For each filter, one of
+        these three methods is used.
+
+
+4.1.1. With Uncompressed Size
+
+        This method is the only method supported by all filters.
+        It must be used when uncompressed size is known by the
+        filter-specific encoder or decoder. In practice this means
+        that Uncompressed Size has been stored to the Block Header.
+
+        In case of the first filter in the chain, the uncompressed size
+        given to the filter-specific encoder or decoder equals the
+        Uncompressed Size stored in the Block Header. For the rest of
+        the filters in the chain, uncompressed size is the size of the
+        output data of the previous filter in the chain.
+
+        Note that when Use End of Payload Marker bit is set in Block
+        Flags, Uncompressed Size is considered to be unknown even if
+        it was present in the Block Header. Thus, if End of Payload
+        Marker is used, uncompressed size of all of the filters in
+        the chain is unknown, and can never be used to detect when
+        all of the data has been decoded.
+
+        Once the correct number of bytes has been written out, the
+        filter-specific decoder indicates to its caller that all of
+        the data has been decoded. If the filter-specific decoder
+        detects End of Input or End of Payload Marker before the
+        correct number of bytes is decoded, the decoder must indicate
+        an error.
+
+
+4.1.2. With End of Input
+
+        Most filters will know that all of the data has been decoded
+        when the End of Input data has been reached. Once the filter
+        knows that it has received the input data in its entirety,
+        it finishes its job, and indicates to its caller that all of
+        the data has been decoded. The filter-specific decoder must
+        indicate an error if it detects End of Payload Marker.
+
+        Note that this method can work only when the filter is not
+        the last filter in the chain, because only another filter
+        can indicate the End of Input data. In practice this means,
+        that a filter later in the chain must support embedding
+        End of Payload Marker.
+
+        When a filter that cannot embed End of Payload Marker is the
+        last filter in the chain, Subblock filter is appended to the
+        chain as an implicit filter. In the simplest case, this occurs
+        when no filters are specified, and Uncompressed Size is unknown
+        or the End of Payload Marker bit is set in Block Flags.
+
+
+4.1.3. With End of Payload Marker
+
+        End of Payload Marker is a filter-specific bit sequence that
+        indicates the end of data. It is supported by only a few
+        filters. It is used when uncompressed size is unknown, and
+        the filter
+          - doesn't support End of Input; or
+          - is the last filter in the chain.
+
+        End of Payload Marker is embedded at the end of the encoded
+        data by the filter-specific encoder. When the filter-specific
+        decoder detects the embedded End of Payload Marker, the decoder
+        knows that all of the data has been decoded. Then it finishes
+        its job, and indicates to its caller that all of the data has
+        been decoded. If the filter-specific decoder detects End of
+        Input before End of Payload Marker, the decoder must indicate
+        an error.
+
+        If the filter supports both End of Input and End of Payload
+        Marker, the former is used, unless the filter is the last
+        filter in the chain.
+
+
+4.2. Alignment
+
+        Some filters give better compression ratio or are faster
+        when the input or output data is aligned. For optimal results,
+        the encoder should try to enforce proper alignment when
+        possible. Not enforcing alignment in the encoder is not
+        an error. Thus, the decoder must be able to handle files with
+        suboptimal alignment.
+
+        Alignment of uncompressed input data is usually the job of
+        the application producing the data. For example, to get the
+        best results, an archiver tool should make sure that all
+        PowerPC executable files in the archive stream start at
+        offsets that are multiples of four bytes.
+
+        Some filters, for example LZMA, can be configured to take
+        advantage of specified alignment of input data. Note that
+        taking advantage of aligned input can be benefical also when
+        a filter is not the first filter in the chain. For example,
+        if you compress PowerPC executables, you may want to use the
+        PowerPC filter and chain that with the LZMA filter. Because not
+        only the input but also the output alignment of the PowerPC
+        filter is four bytes, it is now benefical to set LZMA settings
+        so that the LZMA encoder can take advantage of its
+        four-byte-aligned input data.
+
+        The output of the last filter in the chain is stored to the
+        Compressed Data field. Aligning Compressed Data appropriately
+        can increase
+          - speed, if the filtered data is handled multiple bytes at
+            a time by the filter-specific encoder and decoder,
+            because accessing aligned data in computer memory is
+            usually faster; and
+          - compression ratio, if the output data is later compressed
+            with an external compression tool.
+
+        Compressed Data in a Stream can be aligned by using the Header
+        Padding field in the Block Header.
+
+
+4.3. Filters
+
+4.3.1. Copy
+
+        This is a dummy filter that simply copies all data from input
+        to output unmodified.
+
+            Filter ID:                  0x00
+            Size of Filter Properties:  0 bytes
+            Changes size of data:       No
+
+            Detecting when all of the data has been decoded:
+                Uncompressed size:      Yes
+                End of Payload Marker:  No
+                End of Input:           Yes
+
+            Preferred alignment:
+                Input data:             1 byte
+                Output data:            1 byte
+
+
+4.3.2. Subblock
+
+        The Subblock filter can be used to
+          - embed End of Payload Marker when the otherwise last
+            filter in the chain does not support embedding it; and
+          - apply additional filters in the middle of a Block.
+
+            Filter ID:                  0x01
+            Size of Filter Properties:  0 bytes
+            Changes size of data:       Yes, unpredictably
+
+            Detecting when all of the data has been decoded:
+                Uncompressed size:      Yes
+                End of Payload Marker:  Yes
+                End of Input:           Yes
+
+            Preferred alignment:
+                Input data:             1 byte
+                Output data:            Freely adjustable
+
+
+4.3.2.1. Format of the Encoded Output
+
+        The encoded data from the Subblock filter consist of zero or
+        more Subblocks:
+
+            +==========+==========+
+            | Subblock | Subblock | ...
+            +==========+==========+
+
+        Each Subblock contains two fields:
+
+            +----------------+===============+
+            | Subblock Flags | Subblock Data |
+            +----------------+===============+
+
+        Subblock Flags is a bitfield:
+
+            Bits   Mask   Description
+            0-3    0x0F   The interpretation of these bits depend on
+                          the Subblock Type:
+                            - 0x20    Bits 0-3 for Size
+                            - 0x30    Bits 0-3 for Repeat Count
+                            - Other   These bits must be zero.
+            4-7    0xF0   Subblock Type:
+                            - 0x00: Padding
+                            - 0x10: End of Payload Marker
+                            - 0x20: Data
+                            - 0x30: Repeating Data
+                            - 0x40: Set Subfilter
+                            - 0x50: Unset Subfilter
+                          If some other value is detected, the decoder
+                          must indicate an error.
+
+        The format of the Subblock Data field depends on Subblock Type.
+
+        Subblocks with the Subblock Type 0x00 (Padding) don't have a
+        Subblock Data field. These Subblocks can be useful for fixing
+        alignment. There can be at maximum of 31 consecutive Subblocks
+        with this Subblock Type; if there are more, the decoder must
+        indicate an error.
+
+        Subblock with the Subblock Type 0x10 (End of Payload Marker)
+        doesn't have a Subblock Data field. The decoder must indicate
+        an error if this Subblock Type is detected when Subfilter is
+        enabled, or when the Subblock filter is not supposed to embed
+        the End of Payload Marker.
+
+        Subblocks with the Subblock Type 0x20 (Data) contain the rest
+        of the Size, which is followed by Size + 1 bytes in the Data
+        field (that is, Data can never be empty):
+
+            +------+------+------+======+
+            | Bits 4-27 for Size | Data |
+            +------+------+------+======+
+
+        Subblocks with the Subblock Type 0x30 (Repeating Data) contain
+        the rest of the Repeat Count, the Size of the Data, and finally
+        the actual Data to be repeated:
+
+            +---------+---------+--------+------+======+
+            | Bits 4-27 for Repeat Count | Size | Data |
+            +---------+---------+--------+------+======+
+
+        The size of the Data field is Size + 1. It is repeated Repeat
+        Count + 1 times. That is, the minimum size of Data is one byte;
+        the maximum size of Data is 256 bytes. The minimum number of
+        repeats is one; the maximum number of repeats is 2^28.
+
+        If Subfilter is not used, the Data field of Subblock Types 0x20
+        and 0x30 is the output of the decoded Subblock filter. If
+        Subfilter is used, Data is the input of the Subfilter, and the
+        decoded output of the Subfilter is the decoded output of the
+        Subblock filter.
+
+        Subblocks with the Subblock Type 0x40 (Set Subfilter) contain
+        a Filter Flags field in Subblock Data:
+
+            +==============+
+            | Filter Flags |
+            +==============+
+
+        It is an error to set the Subfilter to Filter ID 0x00 (Copy)
+        or 0x01 (Subblock). All the other Filter IDs are allowed.
+        The decoder must indicate an error if this Subblock Type is
+        detected when a Subfilter is already enabled.
+
+        Subblocks with the Subblock Type 0x50 (Unset Subfilter) don't
+        have a Subblock Data field. There must be at least one Subblock
+        with Subblock Type 0x20 or 0x30 between Subblocks with Subblock
+        Type 0x40 and 0x50; if there isn't, the decoder must indicate
+        an error.
+
+        Subblock Types 0x40 and 0x50 are always used as a pair: If the
+        Subblock filter has been enabled with Subblock Type 0x40, it
+        must always be disabled later with Subblock Type 0x50.
+        Disabling must be done even if the Subfilter used End of
+        Payload Marker; after the Subfilter has detected End of Payload
+        Marker, the next Subblock that is not Padding must unset the
+        Subfilter.
+
+        When the Subblock filter is used as an implicit filter to embed
+        End of Payload marker, the Subblock Types 0x40 and 0x50 (Set or
+        Unset Subfilter) must not be used. The decoder must indicate an
+        error if it detects any of these Subblock Types in an implicit
+        Subblock filter.
+
+        The following code illustrates the basic structure of a
+        Subblock decoder.
+
+            uint32_t consecutive_padding = 0;
+            bool got_output_with_subfilter = false;
+
+            while (true) {
+                uint32_t size;
+                uint32_t repeat;
+                uint8_t flags = read_byte();
+
+                if (flags != 0)
+                    consecutive_padding = 0;
+
+                switch (flags >> 4) {
+                    case 0:
+                        // Padding
+                        if (flags & 0x0F)
+                            return DATA_ERROR;
+                        if (++consecutive_padding == 32)
+                            return DATA_ERROR;
+                        break;
+
+                    case 1:
+                        // End of Payload Marker
+                        if (flags & 0x0F)
+                            return DATA_ERROR;
+                        if (subfilter_enabled || !allow_eopm)
+                            return DATA_ERROR;
+                        break;
+
+                    case 2:
+                        // Data
+                        size = flags & 0x0F;
+                        for (size_t i = 4; i < 28; i += 8)
+                            size |= (uint32_t)(read_byte()) << i;
+
+                        // If any output is produced, this will
+                        // set got_output_with_subfilter to true.
+                        copy_data(size);
+                        break;
+
+                    case 3:
+                        // Repeating Data
+                        repeat = flags & 0x0F;
+                        for (size_t i = 4; i < 28; i += 8)
+                            repeat |= (uint32_t)(read_byte()) << i;
+                        size = read_byte();
+
+                        // If any output is produced, this will
+                        // set got_output_with_subfilter to true.
+                        copy_repeating_data(size, repeat);
+                        break;
+
+                    case 4:
+                        // Set Subfilter
+                        if (flags & 0x0F)
+                            return DATA_ERROR;
+                        if (subfilter_enabled)
+                            return DATA_ERROR;
+                        got_output_with_subfilter = false;
+                        set_subfilter();
+                        break;
+
+                    case 5:
+                        // Unset Subfilter
+                        if (flags & 0x0F)
+                            return DATA_ERROR;
+                        if (!subfilter_enabled)
+                            return DATA_ERROR;
+                        if (!got_output_with_subfilter)
+                            return DATA_ERROR;
+                        unset_subfilter();
+                        break;
+
+                    default:
+                        return DATA_ERROR;
+                }
+            }
+
+
+4.3.3. Delta
+
+        The Delta filter may increase compression ratio when the value
+        of the next byte correlates with the value of an earlier byte
+        at specified distance.
+
+            Filter ID:                  0x20
+            Size of Filter Properties:  1 byte
+            Changes size of data:       No
+
+            Detecting when all of the data has been decoded:
+                Uncompressed size:      Yes
+                End of Payload Marker:  No
+                End of Input:           Yes
+
+            Preferred alignment:
+                Input data:             1 byte
+                Output data:            Same as the original input data
+
+        The Properties byte indicates the delta distance, which can be
+        1-256 bytes backwards from the current byte: 0x00 indicates
+        distance of 1 byte and 0xFF distance of 256 bytes.
+
+
+4.3.3.1. Format of the Encoded Output
+
+        The code below illustrates both encoding and decoding with
+        the Delta filter.
+
+            // Distance is in the range [1, 256].
+            const unsigned int distance = get_properties_byte() + 1;
+            uint8_t pos = 0;
+            uint8_t delta[256];
+
+            memset(delta, 0, sizeof(delta));
+
+            while (1) {
+                const int byte = read_byte();
+                if (byte == EOF)
+                    break;
+
+                uint8_t tmp = delta[(uint8_t)(distance + pos)];
+                if (is_encoder) {
+                    tmp = (uint8_t)(byte) - tmp;
+                    delta[pos] = (uint8_t)(byte);
+                } else {
+                    tmp = (uint8_t)(byte) + tmp;
+                    delta[pos] = tmp;
+                }
+
+                write_byte(tmp);
+                --pos;
+            }
+
+
+4.3.4. LZMA
+
+        LZMA (Lempel-Ziv-Markov chain-Algorithm) is a general-purporse
+        compression algorithm with high compression ratio and fast
+        decompression. LZMA based on LZ77 and range coding algorithms.
+
+            Filter ID:                  0x40
+            Size of Filter Properties:  2 bytes
+            Changes size of data:       Yes, unpredictably
+
+            Detecting when all of the data has been decoded:
+                Uncompressed size:      Yes
+                End of Payload Marker:  Yes
+                End of Input:           No
+
+            Preferred alignment:
+                Input data:             Adjustable to 1/2/4/8/16 byte(s)
+                Output data:            1 byte
+
+        At the time of writing, there is no other documentation about
+        how LZMA works than the source code in LZMA SDK. Once such
+        documentation gets written, it will probably be published as
+        a separate document, because including the documentation here
+        would lengthen this document considerably.
+
+        The format of the Filter Properties field is as follows:
+
+            +-----------------+------------------+
+            | LZMA Properties | Dictionary Flags |
+            +-----------------+------------------+
+
+
+4.3.4.1. LZMA Properties
+
+        The LZMA Properties bits contain three properties. An
+        abbreviation is given in parentheses, followed by the value
+        range of the property. The field consists of
+
+            1) the number of literal context bits (lc, [0, 8]);
+            2) the number of literal position bits (lp, [0, 4]); and
+            3) the number of position bits (pb, [0, 4]).
+
+        They are encoded using the following formula:
+
+            LZMA Properties = (pb * 5 + lp) * 9 + lc
+
+        The following C code illustrates a straightforward way to
+        decode the properties:
+
+            uint8_t lc, lp, pb;
+            uint8_t prop = get_lzma_properties() & 0xFF;
+            if (prop > (4 * 5 + 4) * 9 + 8)
+                return LZMA_PROPERTIES_ERROR;
+
+            pb = prop / (9 * 5);
+            prop -= pb * 9 * 5;
+            lp = prop / 9;
+            lc = prop - lp * 9;
+
+
+4.3.4.2. Dictionary Flags
+
+        Currently the lowest six bits of the Dictionary Flags field
+        are in use:
+
+            Bits   Mask   Description
+            0-5    0x3F   Dictionary Size
+            6-7    0xC0   Reserved for future use; must be zero for now.
+
+        Dictionary Size is encoded with one-bit mantissa and five-bit
+        exponent. To avoid wasting space, one-byte dictionary has its
+        own special value.
+
+            Raw value   Mantissa   Exponent   Dictionary size
+                0           1          0      1 byte
+                1           2          0      2 bytes
+                2           3          0      3 bytes
+                3           2          1      4 bytes
+                4           3          1      6 bytes
+                5           2          2      8 bytes
+                6           3          2      12 bytes
+                7           2          3      16 bytes
+                8           3          3      24 bytes
+                9           2          4      32 bytes
+              ...         ...        ...      ...
+               61           2         30      2 GiB
+               62           3         30      3 GiB
+               63           2         31      4 GiB (*)
+
+            (*) The real maximum size of the dictionary is one byte
+                less than 4 GiB, because the distance of 4 GiB is
+                reserved for End of Payload Marker.
+
+        Instead of having a table in the decoder, the dictionary size
+        can be decoded using the following C code:
+
+            uint64_t dictionary_size;
+            const uint8_t bits = get_dictionary_flags() & 0x3F;
+            if (bits == 0) {
+                dictionary_size = 1;
+            } else {
+                dictionary_size = 2 | ((bits + 1) & 1);
+                dictionary_size = dictionary_size << ((bits - 1)  / 2);
+            }
+
+
+4.3.5. Branch/Call/Jump Filters for Executables
+
+        These filters convert relative branch, call, and jump
+        instructions to their absolute counterparts in executable
+        files. This conversion increases redundancy and thus
+        compression ratio.
+
+            Size of Filter Properties:  0 or 4 bytes
+            Changes size of data:       No
+
+            Detecting when all of the data has been decoded:
+                Uncompressed size:      Yes
+                End of Payload Marker:  No
+                End of Input:           Yes
+
+        Below is the list of filters in this category. The alignment
+        is the same for both input and output data.
+
+            Filter ID   Alignment   Description
+              0x04       1 byte     x86 filter (BCJ)
+              0x05       4 bytes    PowerPC (big endian) filter
+              0x06      16 bytes    IA64 filter
+              0x07       4 bytes    ARM (little endian) filter
+              0x08       2 bytes    ARM Thumb (little endian) filter
+              0x09       4 bytes    SPARC filter
+
+        If the size of Filter Properties is four bytes, the Filter
+        Properties field contains the start offset used for address
+        conversions. It is stored as an unsigned 32-bit little endian
+        integer. If the size of Filter Properties is zero, the start
+        offset is zero.
+
+        Setting the start offset may be useful if an executable has
+        multiple sections, and there are many cross-section calls.
+        Taking advantage of this feature usually requires usage of
+        the Subblock filter.
+
+
+5. Metadata
+
+        Metadata is stored in Metadata Blocks, which can be in the
+        beginning or at the end of a Multi-Block Stream. Because of
+        Blocks, it is possible to compress Metadata in the same way
+        as the actual data is compressed. This Section describes the
+        format of the data stored in Metadata Blocks.
+
+            +----------------+===============================+
+            | Metadata Flags | Size of Header Metadata Block |
+            +----------------+===============================+
+
+                 +============+===================+=======+=======+
+            ---> | Total Size | Uncompressed Size | Index | Extra |
+                 +============+===================+=======+=======+
+
+        Stream must be parseable backwards. That is, there must be
+        a way to locate the beginning of the Stream by starting from
+        the end of the Stream. Thus, the Footer Metadata Block must
+        contain the Total Size field or the Index field. If the Stream
+        has Header Metadata Block, also the Size of Header Metadata
+        Block field must be present in Footer Metadata Block.
+
+        It must be possible to quickly locate the Blocks in
+        non-streamed mode. Thus, the Index field must be present
+        at least in one Metadata Block.
+
+        If the above conditions are not met, the decoder must indicate
+        an error.
+
+        There should be no additional data after the last field. If
+        there is, the the decoder should indicate an error.
+
+
+5.1. Metadata Flags
+
+        This field describes which fields are present in a Metadata
+        Block:
+
+            Bit(s)  Mask   Desription
+              0     0x01   Size of Header Metadata Block is present.
+              1     0x02   Total Size is present.
+              2     0x04   Uncompressed Size is present.
+              3     0x08   Index is present.
+             4-6    0x70   Reserve for future use; must be zero for now.
+              7     0x80   Extra is present.
+
+        If any reserved bit is set, the decoder must indicate an error.
+        It is possible that there is a new field present which the
+        decoder is not aware of, and can thus parse the Metadata
+        incorrectly.
+
+
+5.2. Size of Header Metadata Block
+
+        This field is present only if the appropriate bit is set in
+        the Metadata Flags field (see Section 5.1).
+
+        Size of Header Metadata Block is needed to make it possible to
+        parse the Stream backwards. The size is stored using the
+        encoding described in Section 1.2. The decoder must verify that
+        that the value stored in this field is non-zero. In Footer
+        Metadata Block, the decoder must also verify that the stored
+        size matches the real size of Header Metadata Block. In the
+        Header Meatadata Block, the value of this field is ignored as
+        long as it is not zero.
+
+
+5.3. Total Size
+
+        This field is present only if the appropriate bit is set in the
+        Metadata Flags field (see Section 5.1).
+
+        This field contains the total size of the Data Blocks in the
+        Stream. Total Size is stored using the encoding described in
+        Section 1.2. If the stored value does not match the real total
+        size of the Data Blocks, the decoder must indicate an error.
+        The value of this field must be non-zero.
+
+        Total Size can be used to quickly locate the beginning or end
+        of the Stream. This can be useful for example when doing
+        random-access reading, and the Index field is not in the
+        Metadata Block currently being read.
+
+        It is useless to have both Total Size and Index in the same
+        Metadata Block, because Total Size can be calculated from the
+        Index field.
+
+
+5.4. Uncompressed Size
+
+        This field is present only if the appropriate bit is set in the
+        Metadata Flags field (see Section 5.1).
+
+        This field contains the total uncompressed size of the Data
+        Blocks in the Stream. Uncompresssed Size is stored using the
+        encoding described in Section 1.2. If the stored value does not
+        match the real uncompressed size of the Data Blocks, the
+        decoder must indicate an error.
+
+        It is useless to have both Uncompressed Size and Index in
+        the same Metadata Block, because Uncompressed Size can be
+        calculated from the Index field.
+
+
+5.5. Index
+
+        +=======================+=============+====================+
+        | Number of Data Blocks | Total Sizes | Uncompressed Sizes |
+        +=======================+=============+====================+
+
+        Index serves several purporses. Using it, one can
+          - verify that all Blocks in a Stream have been processed;
+          - find out the Uncompressed Size of a Stream; and
+          - quickly access the beginning of any Block (random access).
+
+
+5.5.1. Number of Data Blocks
+
+        This field contains the number of Data Blocks in the Stream.
+        The value is stored using the encoding described in Section
+        1.2. If the decoder has decoded all the Data Blocks of the
+        Stream, and then notices that the Number of Records doesn't
+        match the real number of Data Blocks, the decoder must
+        indicate an error. The value of this field must be non-zero.
+
+
+5.5.2. Total Sizes
+
+        +============+============+
+        | Total Size | Total Size | ...
+        +============+============+
+
+        This field lists the Total Sizes of every Data Block in the
+        Stream. There are as many Total Size fields as indicated by
+        the Number of Data Blocks field.
+
+        Total Size is the size of Block Header, Compressed Data, and
+        Block Footer. It is stored using the encoding described in
+        Section 1.2. If the Total Sizes do not match the real sizes
+        of respective Blocks, the decoder should indicate an error.
+        All the Total Size fields must have a non-zero value.
+
+
+5.5.3. Uncompressed Sizes
+
+        +===================+===================+
+        | Uncompressed Size | Uncompressed Size | ...
+        +===================+===================+
+
+        This field lists the Uncompressed Sizes of every Data Block
+        in the Stream. There are as many Uncompressed Size fields as
+        indicated by the Number of Records field.
+
+        Uncompressed Sizes are stored using the encoding described
+        in Section 1.2. If the Uncompressed Sizes do not match the
+        real sizes of respective Blocks, the decoder shoud indicate
+        an error.
+
+
+5.6. Extra
+
+        This field is present only if the appropriate bit is set in the
+        Metadata Flags field (see Section 5.1). Note that the bit does
+        not indicate that there is any data in the Extra field; it only
+        indicates that Extra may be non-empty.
+
+        The Extra field contains only information that is not required
+        to properly uncompress the Stream or to do random-access
+        reading. Supporting the Extra field is optional. In case the
+        decoder doesn't support the Extra field, it should silently
+        ignore it.
+
+        Extra consists of zero or more Records:
+
+            +========+========+
+            | Record | Record | ...
+            +========+========+
+
+        Excluding Records with Record ID 0x00, each Record contains
+        three fields:
+
+            +==========+==============+======+
+            | Reord ID | Size of Data | Data |
+            +==========+==============+======+
+
+        The Record ID and Size of Data are stored using the encoding
+        described in Section 1.2. Data can be binary or UTF-8
+        [RFC-3629] strings. Non-UTF-8 strings should be avoided.
+        Because the Size of Data is known, there is no need to
+        terminate strings with a nul byte, although doing so should
+        not be considered an error.
+
+        The Record IDs are divided in two categories:
+          - Safe-to-Copy Records may be preserved as is when the
+            Stream is modified in ways that don't change the actual
+            uncompressed data. Examples of such operatings include
+            recompressing and adding, modifying, or deleting unrelated
+            Extra Records.
+          - Unsafe-to-Copy Records should be removed (and possibly
+            recreated) when any kind of changes are made to the Stream.
+
+        When the actual uncompressed data is modified, all Records
+        should be removed (and possibly recreated), unless the
+        application knows that the Data stored to the Record(s) is
+        still valid.
+
+        The following subsections describe the standard Record IDs and
+        the format of their Data fields. Safe-to-Copy Records have an
+        odd ID, while Unsafe-to-Copy Records have an even ID.
+
+
+5.6.1. 0x00: Dummy/Padding
+
+        This Record is special, because it doesn't have the Size of
+        Data or Data fields.
+
+        Dummy Records can be used, for example, to fill Metadata Block
+        when a few bytes of extra space has been reserved for it. There
+        can be any number of Dummy Records.
+
+
+5.6.2. 0x01: OpenPGP Signature
+
+        OpenPGP signature is computed from uncompressed data. The
+        signature can be used to verify that the contents of a Stream
+        has been created by a trustworthy source.
+
+        If the decoder supports decoding concatenated Streams, it
+        must indicate an error when verifying OpenPGP signatures if
+        there is more than one Stream.
+
+        OpenPGP format is documented in [RFC-2440].
+
+
+5.6.3. 0x02: Filter Information
+
+        The Filter Information Record contains information about the
+        filters used in the Stream. This field can be used to quickly
+          - display which filters are used in each Block;
+          - check if all the required filters are supported by the
+            current decoder version; and
+          - check how much memory is required to decode each Block.
+
+        The format of the Filter Information field is as follows:
+
+            +=================+=================+
+            | Block 0 Filters | Block 1 Filters | ...
+            +=================+=================+
+
+        There can be at maximum of as many Block Filters fields as
+        there are Data Blocks in the Stream. The format of the Block
+        Filters field is as follows:
+
+            +------------------+======================+============+
+            | Block Properties | List of Filter Flags | Subfilters |
+            +------------------+======================+============+
+
+        Block Properties is a bitfield:
+
+            Bit(s)  Mask  Description
+             0-2    0x07  Number of filters (0-7)
+              3     0x08  End of Payload Marker is used.
+              4     0x10  The Subfilters field is present.
+             5-7    0xE0  Reserved for future use; must be zero for now.
+
+        The contents of the List of Filter Flags field must match the
+        List of Filter Flags field in the respective Block Header.
+
+        The Subfilters field may be present only if the List of Filter
+        Flags contains a Filter Flags field for a Subblock filter. The
+        format of the Subfilters field is as follows:
+
+            +======================+=========================+
+            | Number of Subfilters | List of Subfilter Flags |
+            +======================+=========================+
+
+        The value stored in the Number of Subfilters field is stored
+        using the encoding described in Section 1.2. The List of
+        Subfilter Flags field contains as many Filter Flags fields
+        as indicated by the Number of Subfilters field. These Filter
+        Flags fields list some or all the Subfilters used via the
+        Subblock filter. The order of the listed Subfilters is not
+        significant.
+
+        Decoders supporting this Record should indicate a warning or
+        error if this Record contains Filter Flags that are not
+        actually used by the respective Blocks.
+
+
+5.6.4. 0x03: Comment
+
+        Free-form comment is stored in UTF-8 [RFC-3629] encoding.
+
+        The beginning of a new line should be indicated using the
+        ASCII Line Feed character (0x0A). When the Line Feed character
+        is not the native way to indicate new line in the underlying
+        operating system, the encoder and decoder should convert the
+        newline characters to and from Line Feeds.
+
+
+5.6.5. 0x04: List of Checks
+
+        +=======+=======+
+        | Check | Check | ...
+        +=======+=======+
+
+        There are as many Check fields as there are Blocks in the
+        Stream. The size of Check fields depend on Stream Flags
+        (see Section 2.2.2).
+
+        Decoders supporting this Record should indicate a warning or
+        error if the Checks don't match the respective Blocks.
+
+
+5.6.6. 0x05: Original Filename
+
+        Original filename is stored in UTF-8 [RFC-3629] encoding.
+
+        The filename must not include any path, only the filename
+        itself. Special care must be taken to prevent directory
+        traversal vulnerabilities.
+
+        When files are moved between different operating systems, it
+        is possible that filename valid in the source system is not
+        valid in the target system. It is implementation defined how
+        the decoder handles this kind of situations.
+
+
+5.6.7. 0x07: Modification Time
+
+        Modification time is stored as POSIX time, as an unsigned
+        little endian integer. The number of bits depends on the
+        Size of Data field. Note that the usage of unsigned integer
+        limits the earliest representable time to 1970-01-01T00:00:00.
+
+
+5.6.8. 0x09: High-Resolution Modification Time
+
+        This Record extends the `0x04: Modification time' Record with
+        a subsecond time information. There are two supported formats
+        of this field, which can be distinguished by looking at the
+        Size of Data field.
+
+        Size  Data
+          3   [0; 9,999,999] times 100 nanoseconds
+          4   [0; 999,999,999] nanoseconds
+
+        The value is stored as an unsigned 24-bit or 32-bit little
+        endian integer.
+
+
+5.6.9. 0x0B: MIME Type
+
+        MIME type of the uncompressed Stream. This can be used to
+        detect the content type. [IANA-MIME]
+
+
+5.6.10. 0x0D: Homepage URL
+
+        This field can be used, for example, when distributing software
+        packages (sources or binaries). The field would indicate the
+        homepage of the program.
+
+        For details on how to encode URLs, see [RFC-1738].
+
+
+6. Custom Filter and Extra Record IDs
+
+        If a developer wants to use custom Filter or Extra Record IDs,
+        he has two choices. The first choice is to contact Lasse Collin
+        and ask him to allocate a range of IDs for the developer.
+
+        The second choice is to generate a 40-bit random integer,
+        which the developer can use as his personal Developer ID.
+        To minimalize the risk of collisions, Developer ID has to be
+        a randomly generated integer, not manually selected "hex word".
+        The following command, which works on many free operating
+        systems, can be used to generate Developer ID:
+
+            dd if=/dev/urandom bs=5 count=1 | hexdump
+
+        The developer can then use his Developer ID to create unique
+        (well, hopefully unique) Filter and Extra Record IDs.
+
+            Bits    Mask                    Description
+             0-15   0x0000_0000_0000_FFFF   Filter or Extra Record ID
+            16-55   0x00FF_FFFF_FFFF_0000   Developer ID
+            56-62   0x7F00_0000_0000_0000   Static prefix: 0x7F
+
+        The resulting 63-bit integer will use 9 bytes of space when
+        stored using the encoding described in Section 1.2. To get
+        a shorter ID, see the beginning of this Section how to
+        request a custom ID range.
+
+        Note that Filter and Metadata Record IDs are in their own
+        namespaces. That is, you can use the same ID value as Filter ID
+        and Metadata Record ID, and the meanings of the IDs do not need
+        to be related to each other.
+
+
+6.1. Reserved Custom Filter ID Ranges
+
+        Range                       Description
+        0x0000_0000 - 0x0000_00DF   IDs fitting into the Misc field
+        0x0002_0000 - 0x0007_FFFF   Reserved to ease .7z compatibility
+        0x0200_0000 - 0x07FF_FFFF   Reserved to ease .7z compatibility
+
+
+7. Cyclic Redundancy Checks
+
+        There are several incompatible variations to calculate CRC32
+        and CRC64. For simplicity and clarity, complete examples are
+        provided to calculate the checks as they are used in this file
+        format. Implementations may use different code as long as it
+        gives identical results.
+
+        The program below reads data from standard input, calculates
+        the CRC32 and CRC64 values, and prints the calculated values
+        as big endian hexadecimal strings to standard output.
+
+            #include <sys/types.h>
+            #include <inttypes.h>
+            #include <stdio.h>
+
+            uint32_t crc32_table[256];
+            uint64_t crc64_table[256];
+
+            void
+            init(void)
+            {
+                static const uint32_t poly32 = UINT32_C(0xEDB88320);
+                static const uint64_t poly64
+                        = UINT64_C(0xC96C5795D7870F42);
+
+                for (size_t i = 0; i < 256; ++i) {
+                    uint32_t crc32 = i;
+                    uint64_t crc64 = i;
+
+                    for (size_t j = 0; j < 8; ++j) {
+                        if (crc32 & 1)
+                            crc32 = (crc32 >> 1) ^ poly32;
+                        else
+                            crc32 >>= 1;
+
+                        if (crc64 & 1)
+                            crc64 = (crc64 >> 1) ^ poly64;
+                        else
+                            crc64 >>= 1;
+                    }
+
+                    crc32_table[i] = crc32;
+                    crc64_table[i] = crc64;
+                }
+            }
+
+            uint32_t
+            crc32(const uint8_t *buf, size_t size, uint32_t crc)
+            {
+                crc = ~crc;
+                for (size_t i = 0; i < size; ++i)
+                    crc = crc32_table[buf[i] ^ (crc & 0xFF)]
+                            ^ (crc >> 8);
+                return ~crc;
+            }
+
+            uint64_t
+            crc64(const uint8_t *buf, size_t size, uint64_t crc)
+            {
+                crc = ~crc;
+                for (size_t i = 0; i < size; ++i)
+                    crc = crc64_table[buf[i] ^ (crc & 0xFF)]
+                            ^ (crc >> 8);
+                return ~crc;
+            }
+
+            int
+            main()
+            {
+                init();
+
+                uint32_t value32 = 0;
+                uint64_t value64 = 0;
+                uint64_t total_size = 0;
+                uint8_t buf[8192];
+
+                while (1) {
+                    const size_t buf_size = fread(buf, 1, 8192, stdin);
+                    if (buf_size == 0)
+                        break;
+
+                    total_size += buf_size;
+                    value32 = crc32(buf, buf_size, value32);
+                    value64 = crc64(buf, buf_size, value64);
+                }
+
+                printf("Bytes:  %" PRIu64 "\n", total_size);
+                printf("CRC-32: 0x%08" PRIX32 "\n", value32);
+                printf("CRC-64: 0x%016" PRIX64 "\n", value64);
+
+                return 0;
+            }
+
+
+8. References
+
+8.1. Normative References
+
+        [RFC-1738]
+        Uniform Resource Locators (URL)
+        http://www.ietf.org/rfc/rfc1738.txt
+
+        [RFC-2119]
+        Key words for use in RFCs to Indicate Requirement Levels
+        http://www.ietf.org/rfc/rfc2119.txt
+
+        [RFC-2440]
+        OpenPGP Message Format
+        http://www.ietf.org/rfc/rfc2440.txt
+
+        [RFC-3629]
+        UTF-8, a transformation format of ISO 10646
+        http://www.ietf.org/rfc/rfc3629.txt
+
+        [IANA-MIME]
+        MIME Media Types
+        http://www.iana.org/assignments/media-types/
+
+
+8.2. Informative References
+
+        LZMA SDK - The original LZMA implementation
+        http://7-zip.org/sdk.html
+
+        LZMA Utils - LZMA adapted to POSIX-like systems
+        http://tukaani.org/lzma/
+
+        [RFC-1952]
+        GZIP file format specification version 4.3
+        http://www.ietf.org/rfc/rfc1952.txt
+          - Notation of byte boxes in section `2.1. Overall conventions'
+
+        [GNU-tar]
+        GNU tar 1.16.1 manual
+        http://www.gnu.org/software/tar/manual/html_node/Blocking-Factor.html
+          - Node 9.4.2 `Blocking Factor', paragraph that begins
+            `gzip will complain about trailing garbage'
+          - Note that this URL points to the latest version of the
+            manual, and may some day not contain the note which is in
+            1.16.1. For the exact version of the manual, download GNU
+            tar 1.16.1: ftp://ftp.gnu.org/pub/gnu/tar/tar-1.16.1.tar.gz
+
diff --git a/doc/history.txt b/doc/history.txt
new file mode 100644 (file)
index 0000000..5529306
--- /dev/null
@@ -0,0 +1,140 @@
+
+LZMA Utils history
+------------------
+
+Tukaani distribution
+
+    In 2005, there was a small group working on Tukaani distribution, which
+    was a Slackware fork. One of the project goals was to fit the distro on
+    a single 700 MiB ISO-9660 image. Using LZMA instead of gzip helped a
+    lot. Roughly speaking, one could fit data that took 1000 MiB in gzipped
+    form into 700 MiB with LZMA. Naturally compression ratio varied across
+    packages, but this was what we got on average.
+
+    Slackware packages have traditionally had .tgz as the filename suffix,
+    which is an abbreviation of .tar.gz. A logical naming for LZMA
+    compressed packages was .tlz, being an abbreviation of .tar.lzma.
+
+    At the end of the year 2007, there's no distribution under the Tukaani
+    project anymore. Development of LZMA Utils still continues. Still,
+    there are .tlz packages around, because at least Vector Linux (a
+    Slackware based distribution) uses LZMA for its packages.
+
+    First versions of the modified pkgtools used the LZMA_Alone tool from
+    Igor Pavlov's LZMA SDK as is. It was fine, because users wouldn't need
+    to interact with LZMA_Alone directly. But people soon wanted to use
+    LZMA for other files too, and the interface of LZMA_Alone wasn't
+    comfortable for those used to gzip and bzip2.
+
+
+First steps of LZMA Utils
+
+    The first version of LZMA Utils (4.22.0) included a shell script called
+    lzmash. It was wrapper that had gzip-like command line interface. It
+    used the LZMA_Alone tool from LZMA SDK to do all the real work. zgrep,
+    zdiff, and related scripts from gzip were adapted work with LZMA and
+    were part of the first LZMA Utils release too.
+
+    LZMA Utils 4.22.0 included also lzmadec, which was a small (less than
+    10 KiB) decoder-only command line tool. It was written on top of the
+    decoder-only C code found from the LZMA SDK. lzmadec was convenient in
+    situations where LZMA_Alone (a few hundred KiB) would be too big.
+
+    lzmash and lzmadec were written by Lasse Collin.
+
+
+Second generation
+
+    The lzmash script was an ugly and not very secure hack. The last
+    version of LZMA Utils to use lzmash was 4.27.1.
+
+    LZMA Utils 4.32.0beta1 introduced a new lzma command line tool written
+    by Ville Koskinen. It was written in C++, and used the encoder and
+    decoder from C++ LZMA SDK with little modifications. This tool replaced
+    both the lzmash script and the LZMA_Alone command line tool in LZMA
+    Utils.
+
+    Introducing this new tool caused some temporary incompatibilities,
+    because LZMA_Alone executable was simply named lzma like the new
+    command line tool, but they had completely different command line
+    interface. The file format was still the same.
+
+    Lasse wrote liblzmadec, which was a small decoder-only library based on
+    the C code found from LZMA SDK. liblzmadec had API similar to zlib,
+    although there were some significant differences, which made it
+    non-trivial to use it in some applications designed for zlib and
+    libbzip2.
+
+    The lzmadec command line tool was converted to use liblzmadec.
+
+    Alexandre Sauvé helped converting build system to use GNU Autotools.
+    This made is easier to test for certain less portable features needed
+    by the new command line tool.
+
+    Since the new command line tool never got completely finished (for
+    example, it didn't support LZMA_OPT environment variable), the intent
+    was to not call 4.32.x stable. Similarly, liblzmadec wasn't polished,
+    but appeared to work well enough, so some people started using it too.
+
+    Because the development of the third generation of LZMA Utils was
+    delayed considerably (roughly two years), the 4.32.x branch had to be
+    kept maintained. It got some bug fixes now and then, and finally it was
+    decided to call it stable, although most of the missing features were
+    never added.
+
+
+File format problems
+
+    The file format used by LZMA_Alone was primitive. It was designed for
+    embedded systems in mind, and thus provided only minimal set of
+    features. The two biggest problems for non-embedded use were lack of
+    magic bytes and integrity check.
+
+    Igor and Lasse started developing a new file format with some help from
+    Ville Koskinen, Mark Adler and Mikko Pouru. Designing the new format
+    took quite a long time. It was mostly because Lasse was quite slow at
+    getting things done due to personal reasons.
+
+    Near the end of the year 2007 the new format was practically finished.
+    Compared to LZMA_Alone format and the .gz format used by gzip, the new
+    .lzma format is quite complex as a whole. This means that tools having
+    *full* support for the new format would be larger and more complex than
+    the tools supporting only the old LZMA_Alone format.
+
+    For the situations where the full support for the .lzma format wouldn't
+    be required (embedded systems, operating system kernels), the new
+    format has a well-defined subset, which is easy to support with small
+    amount of code. It wouldn't be as small as an implementation using the
+    LZMA_Alone format, but the difference shouldn't be significant.
+
+    The new .lzma format allows dividing the data in multiple independent
+    blocks, which can be compressed and uncompressed independenly. This
+    makes multi-threading possible with algorithms that aren't inherently
+    parallel (such as LZMA). There's also a central index of the sizes of
+    the blocks, which makes it possible to do limited random-access reading
+    with granularity of the block size.
+
+    The new .lzma format uses the same filename suffix that was used for
+    LZMA_Alone files. The advantage is that users using the new tools won't
+    notice the change to the new format. The disadvantage is that the old
+    tools won't work with the new files.
+
+
+Third generation
+
+    LZMA Utils 4.42.0alphas drop the rest of the C++ LZMA SDK. The LZMA and
+    other included filters (algorithm implementations) are still directly
+    based on LZMA SDK, but ported to C.
+
+    liblzma is now the core of LZMA Utils. It has zlib-like API, which
+    doesn't suffer from the problems of the API of liblzmadec. liblzma
+    supports not only LZMA, but several other filters, which together
+    can improve compression ratio even further with certain file types.
+
+    The lzma and lzmadec command line tools have been rewritten. They uses
+    liblzma to do the actual compressing or uncompressing.
+
+    The development of LZMA Utils 4.42.x is still in alpha stage. Several
+    features are still missing or don't fully work yet. Documentation is
+    also very minimal.
+
diff --git a/doc/liblzma-advanced.txt b/doc/liblzma-advanced.txt
new file mode 100644 (file)
index 0000000..d829a33
--- /dev/null
@@ -0,0 +1,324 @@
+
+Advanced features of liblzma
+----------------------------
+
+0. Introduction
+
+    Most developers need only the basic features of liblzma. These
+    features allow single-threaded encoding and decoding of .lzma files
+    in streamed mode.
+
+    In some cases developers want more. The .lzma file format is
+    designed to allow multi-threaded encoding and decoding and limited
+    random-access reading. These features are possible in non-streamed
+    mode and limitedly also in streamed mode.
+
+    To take advange of these features, the application needs a custom
+    .lzma file format handler. liblzma provides a set of tools to ease
+    this task, but it's still quite a bit of work to get a good custom
+    .lzma handler done.
+
+
+1. Where to begin
+
+    Start by reading the .lzma file format specification. Understanding
+    the basics of the .lzma file structure is required to implement a
+    custom .lzma file handler and to understand the rest of this document.
+
+
+2. The basic components
+
+2.1. Stream Header and tail
+
+    Stream Header begins the .lzma Stream and Stream tail ends it. Stream
+    Header is defined in the file format specification, but Stream tail
+    isn't (thus I write "tail" with a lower-case letter). Stream tail is
+    simply the Stream Flags and the Footer Magic Bytes fields together.
+    It was done this way in liblzma, because the Block coders take care
+    of the rest of the stuff in the Stream Footer.
+
+    For now, the size of Stream Header is fixed to 11 bytes. The header
+    <lzma/stream_flags.h> defines LZMA_STREAM_HEADER_SIZE, which you
+    should use instead of a hardcoded number. Similarly, Stream tail
+    is fixed to 3 bytes, and there is a constant LZMA_STREAM_TAIL_SIZE.
+
+    It is possible, that a future version of the .lzma format will have
+    variable-sized Stream Header and tail. As of writing, this seems so
+    unlikely though, that it was considered simplest to just use a
+    constant instead of providing a functions to get and store the sizes
+    of the Stream Header and tail.
+
+
+2.x. Stream tail
+
+    For now, the size of Stream tail is fixed to 3 bytes. The header
+    <lzma/stream_flags.h> defines LZMA_STREAM_TAIL_SIZE, which you
+    should use instead of a hardcoded number.
+
+
+3. Keeping track of size information
+
+    The lzma_info_* functions found from <lzma/info.h> should ease the
+    task of keeping track of sizes of the Blocks and also the Stream
+    as a whole. Using these functions is strongly recommended, because
+    there are surprisingly many situations where an error can occur,
+    and these functions check for possible errors every time some new
+    information becomes available.
+
+    If you find lzma_info_* functions lacking something that you would
+    find useful, please contact the author.
+
+
+3.1. Start offset of the Stream
+
+    If you are storing the .lzma Stream inside anothe file format, or
+    for some other reason are placing the .lzma Stream to somewhere
+    else than to the beginning of the file, you should tell the starting
+    offset of the Stream using lzma_info_start_offset_set().
+
+    The start offset of the Stream is used for two distinct purporses.
+    First, knowing the start offset of the Stream allows
+    lzma_info_alignment_get() to correctly calculate the alignment of
+    every Block. This information is given to the Block encoder, which
+    will calculate the size of Header Padding so that Compressed Data
+    is alignment at an optimal offset.
+
+    Another use for start offset of the Stream is in random-access
+    reading. If you set the start offset of the Stream, lzma_info_locate()
+    will be able to calculate the offset relative to the beginning of the
+    file containing the Stream (instead of offset relative to the
+    beginning of the Stream).
+
+
+3.2. Size of Stream Header
+
+    While the size of Stream Header is constant (11 bytes) in the current
+    version of the .lzma file format, this may change in future.
+
+
+3.3. Size of Header Metadata Block
+
+    This information is needed when doing random-access reading, and
+    to verify the value of this field stored in Footer Metadata Block.
+
+
+3.4. Total Size of the Data Blocks
+
+
+3.5. Uncompressed Size of Data Blocks
+
+
+3.6. Index
+
+
+
+
+x. Alignment
+
+    There are a few slightly different types of alignment issues when
+    working with .lzma files.
+
+    The .lzma format doesn't strictly require any kind of alignment.
+    However, if the encoder carefully optimizes the alignment in all
+    situations, it can improve compression ratio, speed of the encoder
+    and decoder, and slightly help if the files get damaged and need
+    recovery.
+
+    Alignment has the most significant effect compression ratio FIXME
+
+
+x.1. Compression ratio
+
+    Some filters take advantage of the alignment of the input data.
+    To get the best compression ratio, make sure that you feed these
+    filters correctly aligned data.
+
+    Some filters (e.g. LZMA) don't necessarily mind too much if the
+    input doesn't match the preferred alignment. With these filters
+    the penalty in compression ratio depends on the specific type of
+    data being compressed.
+
+    Other filters (e.g. PowerPC executable filter) won't work at all
+    with data that is improperly aligned. While the data can still
+    be de-filtered back to its original form, the benefit of the
+    filtering (better compression ratio) is completely lost, because
+    these filters expect certain patterns at properly aligned offsets.
+    The compression ratio may even worse with incorrectly aligned input
+    than without the filter.
+
+
+x.1.1. Inter-filter alignment
+
+    When there are multiple filters chained, checking the alignment can
+    be useful not only with the input of the first filter and output of
+    the last filter, but also between the filters.
+
+    Inter-filter alignment important especially with the Subblock filter.
+
+
+x.1.2. Further compression with external tools
+
+    This is relatively rare situation in practice, but still worth
+    understanding.
+
+    Let's say that there are several SPARC executables, which are each
+    filtered to separate .lzma files using only the SPARC filter. If
+    Uncompressed Size is written to the Block Header, the size of Block
+    Header may vary between the .lzma files. If no Padding is used in
+    the Block Header to correct the alignment, the starting offset of
+    the Compressed Data field will be differently aligned in different
+    .lzma files.
+
+    All these .lzma files are archived into a single .tar archive. Due
+    to nature of the .tar format, every file is aligned inside the
+    archive to an offset that is a multiple of 512 bytes.
+
+    The .tar archive is compressed into a new .lzma file using the LZMA
+    filter with options, that prefer input alignment of four bytes. Now
+    if the independent .lzma files don't have the same alignment of
+    the Compressed Data fields, the LZMA filter will be unable to take
+    advantage of the input alignment between the files in the .tar
+    archive, which reduces compression ratio.
+
+    Thus, even if you have only single Block per file, it can be good for
+    compression ratio to align the Compressed Data to optimal offset.
+
+
+x.2. Speed
+
+    Most modern computers are faster when multi-byte data is located
+    at aligned offsets in RAM. Proper alignment of the Compressed Data
+    fields can slightly increase the speed of some filters.
+
+
+x.3. Recovery
+
+    Aligning every Block Header to start at an offset with big enough
+    alignment may ease or at least speed up recovery of broken files.
+
+
+y. Typical usage cases
+
+y.x. Parsing the Stream backwards
+
+    You may need to parse the Stream backwards if you need to get
+    information such as the sizes of the Stream, Index, or Extra.
+    The basic procedure to do this follows.
+
+    Locate the end of the Stream. If the Stream is stored as is in a
+    standalone .lzma file, simply seek to the end of the file and start
+    reading backwards using appropriate buffer size. The file format
+    specification allows arbitrary amount of Footer Padding (zero or more
+    NUL bytes), which you skip before trying to decode the Stream tail.
+
+    Once you have located the end of the Stream (a non-NULL byte), make
+    sure you have at least the last LZMA_STREAM_TAIL_SIZE bytes of the
+    Stream in a buffer. If there isn't enough bytes left from the file,
+    the file is too small to contain a valid Stream. Decode the Stream
+    tail using lzma_stream_tail_decoder(). Store the offset of the first
+    byte of the Stream tail; you will need it later.
+
+    You may now want to do some internal verifications e.g. if the Check
+    type is supported by the liblzma build you are using.
+
+    Decode the Backward Size field with lzma_vli_reverse_decode(). The
+    field is at maximum of LZMA_VLI_BYTES_MAX bytes long. Check that
+    Backward Size is not zero. Store the offset of the first byte of
+    the Backward Size; you will need it later.
+
+    Now you know the Total Size of the last Block of the Stream. It's the
+    value of Backward Size plus the size of the Backward Size field. Note
+    that you cannot use lzma_vli_size() to calculate the size since there
+    might be padding; you need to use the real observed size of the
+    Backward Size field.
+
+    At this point, the operation continues differently for Single-Block
+    and Multi-Block Streams.
+
+
+y.x.1. Single-Block Stream
+
+    There might be Uncompressed Size field present in the Stream Footer.
+    You cannot know it for sure unless you have already parsed the Block
+    Header earlier. For security reasons, you probably want to try to
+    decode the Uncompressed Size field, but you must not indicate any
+    error if decoding fails. Later you can give the decoded Uncompressed
+    Size to Block decoder if Uncopmressed Size isn't otherwise known;
+    this prevents it from producing too much output in case of (possibly
+    intentionally) corrupt file.
+
+    Calculate the the start offset of the Stream:
+
+        backward_offset - backward_size - LZMA_STREAM_HEADER_SIZE
+
+    backward_offset is the offset of the first byte of the Backward Size
+    field. Remember to check for integer overflows, which can occur with
+    invalid input files.
+
+    Seek to the beginning of the Stream. Decode the Stream Header using
+    lzma_stream_header_decoder(). Verify that the decoded Stream Flags
+    match the values found from Stream tail. You can use the
+    lzma_stream_flags_is_equal() macro for this.
+
+    Decode the Block Header. Verify that it isn't a Metadata Block, since
+    Single-Block Streams cannot have Metadata. If Uncompressed Size is
+    present in the Block Header, the value you tried to decode from the
+    Stream Footer must be ignored, since Uncompressed Size wasn't actually
+    present there. If Block Header doesn't have Uncompressed Size, and
+    decoding the Uncompressed Size field from the Stream Footer failed,
+    the file is corrupt.
+
+    If you were only looking for the Uncompressed Size of the Stream,
+    you now got that information, and you can stop processing the Stream.
+
+    To decode the Block, the same instructions apply as described in
+    FIXME. However, because you have some extra known information decoded
+    from the Stream Footer, you should give this information to the Block
+    decoder so that it can verify it while decoding:
+      - If Uncompressed Size is not present in the Block Header, set
+        lzma_options_block.uncompressed_size to the value you decoded
+        from the Stream Footer.
+      - Always set lzma_options_block.total_size to backward_size +
+        size_of_backward_size (you calculated this sum earlier already).
+
+
+y.x.2. Multi-Block Stream
+
+    Calculate the start offset of the Footer Metadata Block:
+
+        backward_offset - backward_size
+
+    backward_offset is the offset of the first byte of the Backward Size
+    field. Remember to check for integer overflows, which can occur with
+    broken input files.
+
+    Decode the Block Header. Verify that it is a Metadata Block. Set
+    lzma_options_block.total_size to backward_size + size_of_backward_size
+    (you calculated this sum earlier already). Then decode the Footer
+    Metadata Block.
+
+    Store the decoded Footer Metadata to lzma_info structure using
+    lzma_info_set_metadata(). Set also the offset of the Backward Size
+    field using lzma_info_size_set(). Then you can get the start offset
+    of the Stream using lzma_info_size_get(). Note that any of these steps
+    may fail so don't omit error checking.
+
+    Seek to the beginning of the Stream. Decode the Stream Header using
+    lzma_stream_header_decoder(). Verify that the decoded Stream Flags
+    match the values found from Stream tail. You can use the
+    lzma_stream_flags_is_equal() macro for this.
+
+    If you were only looking for the Uncompressed Size of the Stream,
+    it's possible that you already have it now. If Uncompressed Size (or
+    whatever information you were looking for) isn't available yet,
+    continue by decoding also the Header Metadata Block. (If some
+    information is missing, the Header Metadata Block has to be present.)
+
+    Decoding the Data Blocks goes the same way as described in FIXME.
+
+
+y.x.3. Variations
+
+    If you know the offset of the beginning of the Stream, you may want
+    to parse the Stream Header before parsing the Stream tail.
+
diff --git a/doc/liblzma-hacking.txt b/doc/liblzma-hacking.txt
new file mode 100644 (file)
index 0000000..64390bc
--- /dev/null
@@ -0,0 +1,112 @@
+
+Hacking liblzma
+---------------
+
+0. Preface
+
+    This document gives some overall information about the internals of
+    liblzma, which should make it easier to start reading and modifying
+    the code.
+
+
+1. Programming language
+
+    liblzma was written in C99. If you use GCC, this means that you need
+    at least GCC 3.x.x. GCC 2 isn't and won't be supported.
+
+    Some GCC-specific extensions are used *conditionally*. They aren't
+    required to build a full-featured library. Don't make the code rely
+    on any non-standard compiler extensions or even C99 features that
+    aren't portable between almost-C99 compatible compilers (for example
+    non-static inlines).
+
+    The public API headers are in C89. This is to avoid frustrating those
+    who maintain programs, which are strictly in C89 or C++.
+
+    An assumption about sizeof(size_t) is made. If this assumption is
+    wrong, some porting is probably needed:
+
+        sizeof(uint32_t) <= sizeof(size_t) <= sizeof(uint64_t)
+
+
+2. Internal vs. external API
+
+
+
+        Input                         Output
+          v     Application             ^
+          |     liblzma public API      |
+          |     Stream coder            |
+          |     Block coder             |
+          |     Filter coder            |
+          |     ...                     |
+          v     Filter coder            ^
+
+
+        Application
+          `-- liblzma public API
+                `-- Stream coder
+                      |-- Stream info handler
+                      |-- Stream Header coder
+                      |-- Block Header coder
+                      |     `-- Filter Flags coder
+                      |-- Metadata coder
+                      |     `-- Block coder
+                      |           `-- Filter 0
+                      |                 `-- Filter 1
+                      |                     ...
+                      |-- Data Block coder
+                      |     `-- Filter 0
+                      |           `-- Filter 1
+                      |               ...
+                      `-- Stream tail coder
+
+
+
+x. Designing new filters
+
+    All filters must be designed so that the decoder cannot consume
+    arbitrary amount input without producing any decoded output. Failing
+    to follow this rule makes liblzma vulnerable to DoS attacks if
+    untrusted files are decoded (usually they are untrusted).
+
+    An example should clarify the reason behind this requirement: There
+    are two filters in the chain. The decoder of the first filter produces
+    huge amount of output (many gigabytes or more) with a few bytes of
+    input, which gets passed to the decoder of the second filter. If the
+    data passed to the second filter is interpreted as something that
+    produces no output (e.g. padding), the filter chain as a whole
+    produces no output and consumes no input for a long period of time.
+
+    The above problem was present in the first versions of the Subblock
+    filter. A tiny .lzma file could have taken several years to decode
+    while it wouldn't produce any output at all. The problem was fixed
+    by adding limits for number of consecutive Padding bytes, and requiring
+    that some decoded output must be produced between Set Subfilter and
+    Unset Subfilter.
+
+
+x. Implementing new filters
+
+    If the filter supports embedding End of Payload Marker, make sure that
+    when your filter detects End of Payload Marker,
+      - the usage of End of Payload Marker is actually allowed (i.e. End
+        of Input isn't used); and
+      - it also checks that there is no more input coming from the next
+        filter in the chain.
+
+    The second requirement is slightly tricky. It's possible that the next
+    filter hasn't returned LZMA_STREAM_END yet. It may even need a few
+    bytes more input before it will do so. You need to give it as much
+    input as it needs, and verify that it doesn't produce any output.
+
+    Don't call the next filter in the chain after it has returned
+    LZMA_STREAM_END (except in encoder if action == LZMA_SYNC_FLUSH).
+    It will result undefined behavior.
+
+    Be pedantic. If the input data isn't exactly valid, reject it.
+
+    At the moment, liblzma isn't modular. You will need to edit several
+    files in src/liblzma/common to include support for a new filter. grep
+    for LZMA_FILTER_LZMA to locate the files needing changes.
+
diff --git a/doc/liblzma-intro.txt b/doc/liblzma-intro.txt
new file mode 100644 (file)
index 0000000..9cbd63a
--- /dev/null
@@ -0,0 +1,188 @@
+
+Introduction to liblzma
+-----------------------
+
+Writing applications to work with liblzma
+
+    liblzma API is split in several subheaders to improve readability and
+    maintainance. The subheaders must not be #included directly; simply
+    use `#include <lzma.h>' instead.
+
+    Those who have used zlib should find liblzma's API easy to use.
+    To developers who haven't used zlib before, I recommend learning
+    zlib first, because zlib has excellent documentation.
+
+    While the API is similar to that of zlib, there are some major
+    differences, which are summarized below.
+
+    For basic stream encoding, zlib has three functions (deflateInit(),
+    deflate(), and deflateEnd()). Similarly, there are three functions
+    for stream decoding (inflateInit(), inflate(), and inflateEnd()).
+    liblzma has only single coding and ending function. Thus, to
+    encode one may use, for example, lzma_stream_encoder_single(),
+    lzma_code(), and lzma_end(). Simlarly for decoding, one may
+    use lzma_auto_decoder(), lzma_code(), and lzma_end().
+
+    zlib has deflateReset() and inflateReset() to reset the stream
+    structure without reallocating all the memory. In liblzma, all
+    coder initialization functions are like zlib's reset functions:
+    the first-time initializations are done with the same functions
+    as the reinitializations (resetting).
+
+    To make all this work, liblzma needs to know when lzma_stream
+    doesn't already point to an allocated and initialized coder.
+    This is achieved by initializing lzma_stream structure with
+    LZMA_STREAM_INIT (static initialization) or LZMA_STREAM_INIT_VAR
+    (for exampple when new lzma_stream has been allocated with malloc()).
+    This initialization should be done exactly once per lzma_stream
+    structure to avoid leaking memory. Calling lzma_end() will leave
+    lzma_stream into a state comparable to the state achieved with
+    LZMA_STREAM_INIT and LZMA_STREAM_INIT_VAR.
+
+    Example probably clarifies a lot. With zlib, compression goes
+    roughly like this:
+
+        z_stream strm;
+        deflateInit(&strm, level);
+        deflate(&strm, Z_RUN);
+        deflate(&strm, Z_RUN);
+        ...
+        deflate(&strm, Z_FINISH);
+        deflateEnd(&strm) or deflateReset(&strm)
+
+    With liblzma, it's slightly different:
+
+        lzma_stream strm = LZMA_STREAM_INIT;
+        lzma_stream_encoder_single(&strm, &options);
+        lzma_code(&strm, LZMA_RUN);
+        lzma_code(&strm, LZMA_RUN);
+        ...
+        lzma_code(&strm, LZMA_FINISH);
+        lzma_end(&strm) or reinitialize for new coding work
+
+     Reinitialization in the last step can be any function that can
+     initialize lzma_stream; it doesn't need to be the same function
+     that was used for the previous initialization. If it is the same
+     function, liblzma will usually be able to re-use most of the
+     existing memory allocations (depends on how much the initialization
+     options change). If you reinitialize with different function,
+     liblzma will automatically free the memory of the previous coder.
+
+
+File formats
+
+    liblzma supports multiple container formats for the compressed data.
+    Different initialization functions initialize the lzma_stream to
+    process different container formats. See the details from the public
+    header files.
+
+    The following functions are the most commonly used:
+
+      - lzma_stream_encoder_single(): Encodes Single-Block Stream; this
+        the recommended format for most purporses.
+
+      - lzma_alone_encoder(): Useful if you need to encode into the
+        legacy LZMA_Alone format.
+
+      - lzma_auto_decoder(): Decoder that automatically detects the
+        file format; recommended when you decode compressed files on
+        disk, because this way compatibility with the legacy LZMA_Alone
+        format is transparent.
+
+      - lzma_stream_decoder(): Decoder for Single- and Multi-Block
+        Streams; this is good if you want to accept only .lzma Streams.
+
+
+Filters
+
+    liblzma supports multiple filters (algorithm implementations). The new
+    .lzma format supports filter-chain having up to seven filters. In the
+    filter chain, the output of one filter is input of the next filter in
+    the chain. The legacy LZMA_Alone format supports only one filter, and
+    that must always be LZMA.
+
+        General-purporse compression:
+
+            LZMA        The main algorithm of liblzma (surprise!)
+
+        Branch/Call/Jump filters for executables:
+
+            x86         This filter is known as BCJ in 7-Zip
+            IA64        IA-64 (Itanium)
+            PowerPC     Big endian PowerPC
+            ARM
+            ARM-Thumb
+            SPARC
+
+        Other filters:
+
+            Copy        Dummy filter that simply copies all the data
+                        from input to output.
+
+            Subblock    Multi-purporse filter, that can
+                          - embed End of Payload Marker if the previous
+                            filter in the chain doesn't support it; and
+                          - apply Subfilters, which filter only part
+                            of the same compressed Block in the Stream.
+
+    Branch/Call/Jump filters never change the size of the data. They
+    should usually be used as a pre-filter for some compression filter
+    like LZMA.
+
+
+Integrity checks
+
+    The .lzma Stream format uses CRC32 as the integrity check for
+    different file format headers. It is possible to omit CRC32 from
+    the Block Headers, but not from Stream Header. This is the reason
+    why CRC32 code cannot be disabled when building liblzma (in addition,
+    the LZMA encoder uses CRC32 for hashing, so that's another reason).
+
+    The integrity check of the actual data is calculated from the
+    uncompressed data. This check can be CRC32, CRC64, or SHA256.
+    It can also be omitted completely, although that usually is not
+    a good thing to do. There are free IDs left, so support for new
+    checks algorithms can be added later.
+
+
+API and ABI stability
+
+    The API and ABI of liblzma isn't stable yet, although no huge
+    changes should happen. One potential place for change is the
+    lzma_options_subblock structure.
+
+    In the 4.42.0alpha phase, the shared library version number won't
+    be updated even if ABI breaks. I don't want to track the ABI changes
+    yet. Just rebuild everything when you upgrade liblzma until we get
+    to the beta stage.
+
+
+Size of the library
+
+    While liblzma isn't huge, it is quite far from the smallest possible
+    LZMA implementation: full liblzma binary (with support for all
+    filters and other features) is way over 100 KiB, but the plain raw
+    LZMA decoder is only 5-10 KiB.
+
+    To decrease the size of the library, you can omit parts of the library
+    by passing certain options to the `configure' script. Disabling
+    everything but the decoders of the require filters will usually give
+    you a small enough library, but if you need a decoder for example
+    embedded in the operating system kernel, the code from liblzma probably
+    isn't suitable as is.
+
+    If you need a minimal implementation supporting .lzma Streams, you
+    may need to do partial rewrite. liblzma uses stateful API like zlib.
+    That increases the size of the library. Using callback API or even
+    simpler buffer-to-buffer API would allow smaller implementation.
+
+    LZMA SDK contains smaller LZMA decoder written in ANSI-C than
+    liblzma, so you may want to take a look at that code. However,
+    it doesn't (at least not yet) support the new .lzma Stream format.
+
+
+Documentation
+
+    There's no other documentation than the public headers and this
+    text yet. Real docs will be written some day, I hope.
+
diff --git a/doc/liblzma-security.txt b/doc/liblzma-security.txt
new file mode 100644 (file)
index 0000000..487637e
--- /dev/null
@@ -0,0 +1,219 @@
+
+Using liblzma securely
+----------------------
+
+0. Introduction
+
+    This document discusses how to use liblzma securely. There are issues
+    that don't apply to zlib or libbzip2, so reading this document is
+    strongly recommended even for those who are very familiar with zlib
+    or libbzip2.
+
+    While making liblzma itself as secure as possible is essential, it's
+    out of scope of this document.
+
+
+1. Memory usage
+
+    The memory usage of liblzma varies a lot.
+
+
+1.1. Problem sources
+
+1.1.1. Block coder
+
+    The memory requirements of Block encoder depend on the used filters
+    and their settings. The memory requirements of the Block decoder
+    depend on the which filters and with which filter settings the Block
+    was encoded. Usually the memory requirements of a decoder are equal
+    or less than the requirements of the encoder with the same settings.
+
+    While the typical memory requirements to decode a Block is from a few
+    hundred kilobytes to tens of megabytes, a maliciously constructed
+    files can require a lot more RAM to decode. With the current filters,
+    the maximum amount is about 7 GiB. If you use multi-threaded decoding,
+    every Block can require this amount of RAM, thus a four-threaded
+    decoder could suddenly try to allocate 28 GiB of RAM.
+
+    If you don't limit the maximum memory usage in any way, and there are
+    no resource limits set on the operating system side, one malicious
+    input file can run the system out of memory, or at least make it swap
+    badly for a long time. This is exceptionally bad on servers e.g.
+    email server doing virus scanning on incoming messages.
+
+
+1.1.2. Metadata decoder
+
+    Multi-Block .lzma files contain at least one Metadata Block.
+    Externally the Metadata Blocks are similar to Data Blocks, so all
+    the issues mentioned about memory usage of Data Blocks applies to
+    Metadata Blocks too.
+
+    The uncompressed content of Metadata Blocks contain information about
+    the Stream as a whole, and optionally some Extra Records. The
+    information about the Stream is kept in liblzma's internal data
+    structures in RAM. Extra Records can contain arbitrary data. They are
+    not interpreted by liblzma, but liblzma will provide them to the
+    application in uninterpreted form if the application wishes so.
+
+    Usually the Uncompressed Size of a Metadata Block is small. Even on
+    extreme cases, it shouldn't be much bigger than a few megabytes. Once
+    the Metadata has been parsed into native data structures in liblzma,
+    it usually takes a little more memory than in the encoded form. For
+    all normal files, this is no problem, since the resulting memory usage
+    won't be too much.
+
+    The problem is that a maliciously constructed Metadata Block can
+    contain huge amount of "information", which liblzma will try to store
+    in its internal data structures. This may cause liblzma to allocate
+    all the available RAM unless some kind of resource usage limits are
+    applied.
+
+    Note that the Extra Records in Metadata are always parsed but, but
+    memory is allocated for them only if the application has requested
+    liblzma to provide the Extra Records to the application.
+
+
+1.2. Solutions
+
+    If you need to decode files from untrusted sources (most people do),
+    you must limit the memory usage to avoid denial of service (DoS)
+    conditions caused by malicious input files.
+
+    The first step is to find out how much memory you are allowed consume
+    at maximum. This may be a hardcoded constant or derived from the
+    available RAM; whatever is appropriate in the application.
+
+    The simplest solution is to use setrlimit() if the kernel supports
+    RLIMIT_AS, which limits the memory usage of the whole process.
+    For more portable and fine-grained limitting, you can use
+    memory limitter functions found from <lzma/memlimit.h>.
+
+
+1.2.1. Encoder
+
+    lzma_memory_usage() will give you a rough estimate about the memory
+    usage of the given filter chain. To dramatically simplify the internal
+    implementation, this function doesn't take into account all the small
+    helper data structures needed in various places; only the structures
+    with significant memory usage are taken into account. Still, the
+    accuracy of this function should be well within a mebibyte.
+
+    The Subblock filter is a special case. If a Subfilter has been
+    specified, it isn't taken into account when lzma_memory_usage()
+    calculates the memory usage. You need to calculate the memory usage
+    of the Subfilter separately.
+
+    Keeping track of Blocks in a Multi-Block Stream takes a few dozen
+    bytes of RAM per Block (size of the lzma_index structure plus overhead
+    of malloc()). It isn't a good idea to put tens of thousands of Blocks
+    into a Stream unless you have a very good reason to do so (compressed
+    dictionary could be an example of such situation).
+
+    Also keep the number and sizes of Extra Records sane. If you produce
+    the list of Extra Records automatically from some untrusted source,
+    you should not only validate the content of these Records, but also
+    their memory usage.
+
+
+1.2.2. Decoder
+
+    A single-threaded decoder should simply use a memory limitter and
+    indicate an error if it runs out of memory.
+
+    Memory-limitting with multi-threaded decoding is tricky. The simple
+    solution is to divide the maximum allowed memory usage with the
+    maximum allowed threads, and give each Block decoder their own
+    independent lzma_memory_limitter. The drawback is that if one Block
+    needs notably more RAM than any other Block, the decoder will run out
+    of memory when in reality there would be plenty of free RAM.
+
+    An attractive alternative would be using shared lzma_memory_limitter.
+    Depending on the application and the expected type of input, this may
+    either be the best solution or a source of hard-to-repeat problems.
+    Consider the following requirements:
+      - You use at maximum of n threads.
+      - x(i) is the decoder memory requirements of the Block number i
+        in an expected input Stream.
+      - The memory limitter is set to higher value than the sum of n
+        highest values x(i).
+
+    (If you are better at explaining the above conditions, please
+    contribute your improved version.)
+
+    If the above conditions aren't met, it is possible that the decoding
+    will fail unpredictably. That is, on the same machine using the same
+    settings, the decoding may sometimes succeed and sometimes fail. This
+    is because sometimes threads may run so that the Blocks with highest
+    memory usage are tried to be decoded at the same time.
+
+    Most .lzma files have all the Blocks encoded with identical settings,
+    or at least the memory usage won't vary dramatically. That's why most
+    multi-threaded decoders probably want to use the simple "separate
+    lzma_memory_limitter for each thread" solution, possibly fallbacking
+    to single-threaded mode in case the per-thread memory limits aren't
+    enough in multi-threaded mode.
+
+FIXME: Memory usage of Stream info.
+
+[
+
+]
+
+
+2. Huge uncompressed output
+
+2.1. Data Blocks
+
+    Decoding a tiny .lzma file can produce huge amount of uncompressed
+    output. There is an example file of 45 bytes, which decodes to 64 PiB
+    (that's 2^56 bytes). Uncompressing such a file to disk is likely to
+    fill even a bigger disk array. If the data is written to a pipe, it
+    may not fill the disk, but would still take very long time to finish.
+
+    To avoid denial of service conditions caused by huge amount of
+    uncompressed output, applications using liblzma should use some method
+    to limit the amount of output produced. The exact method depends on
+    the application.
+
+    All valid .lzma Streams make it possible to find out the uncompressed
+    size of the Stream without actually uncompressing the data. This
+    information is available in at least one of the Metadata Blocks.
+    Once the uncompressed size is parsed, the decoder can verify that
+    it doesn't exceed certain limits (e.g. available disk space).
+
+    When the uncompressed size is known, the decoder can actively keep
+    track of the amount of output produced so far, and that it doesn't
+    exceed the known uncompressed size. If it does exceed, the file is
+    known to be corrupt and an error should be indicated without
+    continuing to decode the rest of the file.
+
+    Unfortunately, finding the uncompressed size beforehand is often
+    possible only in non-streamed mode, because the needed information
+    could be in the Footer Metdata Block, which (obviously) is at the
+    end of the Stream. In purely streamed mode decoding, one may need to
+    use some rough arbitrary limits to prevent the problems described in
+    the beginning of this section.
+
+
+2.2. Metadata
+
+    Metadata is stored in Metadata Blocks, which are very similar to
+    Data Blocks. Thus, the uncompressed size can be huge just like with
+    Data Blocks. The difference is, that the contents of Metadata Blocks
+    aren't given to the application as is, but parsed by liblzma. Still,
+    reading through a huge Metadata can take very long time, effectively
+    creating a denial of service like piping decoded a Data Block to
+    another process would do.
+
+    At first it would seem that using a memory limitter would prevent
+    this issue as a side effect. But it does so only if the application
+    requests liblzma to allocate the Extra Records and provide them to
+    the application. If Extra Records aren't requested, they aren't
+    allocated either. Still, the Extra Records are being read through
+    to validate that the Metadata is in proper format.
+
+    The solution is to limit the Uncompressed Size of a Metadata Block
+    to some relatively large value. This will make liblzma to give an
+    error when the given limit is reached.
+
diff --git a/doc/lzma-intro.txt b/doc/lzma-intro.txt
new file mode 100644 (file)
index 0000000..bde8a05
--- /dev/null
@@ -0,0 +1,107 @@
+
+Introduction to the lzma command line tool
+------------------------------------------
+
+Overview
+
+    The lzma command line tool is similar to gzip and bzip2, but for
+    compressing and uncompressing .lzma files.
+
+
+Supported file formats
+
+    By default, the tool creates files in the new .lzma format. This can
+    be overriden with --format=FMT command line option. Use --format=alone
+    to create files in the old LZMA_Alone format.
+
+    By default, the tool uncompresses both the new .lzma format and
+    LZMA_Alone format. This is to make it transparent to switch from
+    the old LZMA_Alone format to the new .lzma format. Since both
+    formats use the same filename suffix, average user should never
+    notice which format was used.
+
+
+Differences to gzip and bzip2
+
+  Standard input and output
+
+    Both gzip and bzip2 refuse to write compressed data to a terminal and
+    read compressed data from a terminal. With gzip (but not with bzip2),
+    this can be overriden with the `--force' option. lzma follows the
+    behavior of gzip here.
+
+  Usage of LZMA_OPT environment variable
+
+    gzip and bzip2 read GZIP and BZIP2 environment variables at startup.
+    These variables may contain extra command line options.
+
+    gzip and bzip2 allow passing not only options, but also end-of-options
+    indicator (`--') and filenames via the environment variable. No quoting
+    is supported with the filenames.
+
+    Here are examples with gzip. bzip2 behaves identically.
+
+        bash$ echo asdf > 'foo bar'
+        bash$ GZIP='"foo bar"' gzip
+        gzip: "foo: No such file or directory
+        gzip: bar": No such file or directory
+
+        bash$ GZIP=-- gzip --help
+        gzip: --help: No such file or directory
+
+    lzma silently ignores all non-option arguments given via the
+    environment variable LZMA_OPT. Like on the command line, everything
+    after `--' is taken as non-options, and thus ignored in LZMA_OPT.
+
+        bash$ LZMA_OPT='--help' lzma --version     # Displays help
+        bash$ LZMA_OPT='-- --help' lzma --version  # Displays version
+
+
+Filter chain presets
+
+    Like in gzip and bzip2, lzma supports numbered presets from 1 to 9
+    where 1 is the fastest and 9 the best compression. 1 and 2 are for
+    fast compressing with small memory usage, 3 to 6 for good compression
+    ratio with medium memory usage, and 7 to 9 for excellent compression
+    ratio with higher memory requirements. The default is 7 if memory
+    usage limit allows.
+
+    In future, there will probably be an option like --preset=NAME, which
+    will contain more special presets for specific file types.
+
+    It's also possible that there will be some heuristics to select good
+    filters. For example, the tool could detect when a .tar archive is
+    being compressed, and enable x86 filter only for those files in the
+    .tar archive that are ELF or PE executables for x86.
+
+
+Specifying custom filter chains
+
+    Custom filter chains are specified by using long options with the name
+    of the filters in correct order. For example, to pass the input data to
+    the x86 filter and the output of that to the LZMA filter, the following
+    command will do:
+
+        lzma --x86 --lzma filename
+
+    Some filters accept options, which are specified as a comma-separated
+    list of key=value pairs:
+
+        lzma --delta=distance=4 --lzma=dict=4Mi,lc=8,lp=2 filename
+
+
+Memory usage control
+
+    By default, the command line tool limits memory usage to 1/3 of the
+    available physical RAM. If no preset or custom filter chain has been
+    given, the default preset will be used. If the memory limit is too
+    low for the default preset, the tool will silently switch to lower
+    preset.
+
+    When a preset or a custom filter chain has been specified and the
+    memory limit is too low, an error message is displayed and no files
+    are processed.
+
+    If the decoder hits the memory usage limit, an error is displayed and
+    no more files are processed.
+
diff --git a/extra/scanlzma/scanlzma.c b/extra/scanlzma/scanlzma.c
new file mode 100644 (file)
index 0000000..3612f9d
--- /dev/null
@@ -0,0 +1,85 @@
+/*
+    scanlzma, scan for lzma compressed data in stdin and echo it to stdout.
+    Copyright (C) 2006 Timo Lindfors
+
+    This program is free software; you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation; either version 2 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+*/
+
+/* Usage example:
+
+   $ wget http://www.wifi-shop.cz/Files/produkty/wa2204/wa2204av1.4.1.zip
+   $ unzip wa2204av1.4.1.zip
+   $ gcc scanlzma.c -o scanlzma -Wall
+   $ ./scanlzma 0 < WA2204-FW1.4.1/linux-1.4.bin | lzma -c -d | strings | grep -i "copyright"
+   UpdateDD version 2.5, Copyright (C) 2005 Philipp Benner.
+   Copyright (C) 2005 Philipp Benner.
+   Copyright (C) 2005 Philipp Benner.
+   mawk 1.3%s%s %s, Copyright (C) Michael D. Brennan
+   # Copyright (C) 1998, 1999, 2001  Henry Spencer.
+   ...
+
+*/
+
+
+/* LZMA compressed file format */
+/* --------------------------- */
+/* Offset Size Description */
+/*   0     1   Special LZMA properties for compressed data */
+/*   1     4   Dictionary size (little endian) */
+/*   5     8   Uncompressed size (little endian). -1 means unknown size */
+/*  13         Compressed data */
+
+#define BUFSIZE 4096
+
+int find_lzma_header(unsigned char *buf) {
+       return (buf[0] < 0xE1
+               && buf[0] == 0x5d
+               && buf[4] < 0x20
+               && (memcmp (buf + 10 , "\x00\x00\x00", 3) == 0
+                   || (memcmp (buf + 5, "\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF", 8) == 0)));
+}
+
+int main(int argc, char *argv[]) {
+       char buf[BUFSIZE];
+       int ret, i, numlzma, blocks=0;
+
+       if (argc != 2) {
+               printf("usage: %s numlzma < infile | lzma -c -d > outfile\n"
+                      "where numlzma is index of lzma file to extract, starting from zero.\n",
+                      argv[0]);
+               exit(1);
+       }
+       numlzma = atoi(argv[1]);
+
+       for (;;) {
+               /* Read data. */
+               ret = fread(buf, BUFSIZE, 1, stdin);
+               if (ret != 1)
+                       break;
+               
+               /* Scan for signature. */
+               for (i = 0; i<BUFSIZE-23; i++) {
+                       if (find_lzma_header(buf+i) && numlzma-- <= 0) {
+                               fwrite(buf+i, (BUFSIZE-i), 1, stdout); 
+                               for (;;) {
+                                       int ch;
+                                       ch = getchar();
+                                       if (ch == EOF)
+                                               exit(0);
+                                       putchar(ch);
+                               }
+                                       
+                       }
+               }
+               blocks++;
+       }
+       return 1;
+}
diff --git a/lib/Makefile.am b/lib/Makefile.am
new file mode 100644 (file)
index 0000000..46e3a4a
--- /dev/null
@@ -0,0 +1,40 @@
+##
+##  Copyright (C) 2004-2007 Free Software Foundation, Inc.
+##  Copyright (C) 2007 Lasse Collin
+##
+##  This program is free software; you can redistribute it and/or modify
+##  it under the terms of the GNU General Public License as published by
+##  the Free Software Foundation; either version 2 of the License, or
+##  (at your option) any later version.
+##
+##  This program is distributed in the hope that it will be useful,
+##  but WITHOUT ANY WARRANTY; without even the implied warranty of
+##  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+##  GNU General Public License for more details.
+##
+
+## Not using gnulib-tool, at least for now. Less mess this way.
+
+## We need two builds of libgnu: one with NLS and one without.
+## This is because lzma uses NLS but lzmadec doesn't, while
+## both need GNU getopt_long().
+noinst_LIBRARIES = libgnu.a libgnu_nls.a
+
+libgnu_a_SOURCES =
+libgnu_a_DEPENDENCIES = $(LIBOBJS)
+libgnu_a_LIBADD = $(LIBOBJS)
+libgnu_a_CPPFLAGS = -DDISABLE_NLS=1
+
+libgnu_nls_a_SOURCES =
+libgnu_nls_a_DEPENDENCIES = $(LIBOBJS)
+libgnu_nls_a_LIBADD = $(LIBOBJS)
+
+EXTRA_DIST = gettext.h getopt_.h getopt.c getopt1.c getopt_int.h
+BUILT_SOURCES = $(GETOPT_H)
+MOSTLYCLEANFILES = getopt.h getopt.h-t
+
+getopt.h: getopt_.h
+       { echo '/* DO NOT EDIT! GENERATED AUTOMATICALLY! */'; \
+         cat $(srcdir)/getopt_.h; \
+       } > $@-t
+       mv -f $@-t $@
diff --git a/lib/getopt.c b/lib/getopt.c
new file mode 100644 (file)
index 0000000..3580ad8
--- /dev/null
@@ -0,0 +1,1191 @@
+/* Getopt for GNU.
+   NOTE: getopt is now part of the C library, so if you don't know what
+   "Keep this file name-space clean" means, talk to drepper@gnu.org
+   before changing it!
+   Copyright (C) 1987,88,89,90,91,92,93,94,95,96,98,99,2000,2001,2002,2003,2004,2006
+       Free Software Foundation, Inc.
+   This file is part of the GNU C Library.
+
+   This program is free software; you can redistribute it and/or modify
+   it under the terms of the GNU General Public License as published by
+   the Free Software Foundation; either version 2, or (at your option)
+   any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU General Public License for more details.
+
+   You should have received a copy of the GNU General Public License along
+   with this program; if not, write to the Free Software Foundation,
+   Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.  */
+\f
+#ifndef _LIBC
+# include <config.h>
+#endif
+
+#include "getopt.h"
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <unistd.h>
+
+#ifdef __VMS
+# include <unixlib.h>
+#endif
+
+#ifdef _LIBC
+# include <libintl.h>
+#else
+# include "gettext.h"
+# define _(msgid) gettext (msgid)
+#endif
+
+#if defined _LIBC && defined USE_IN_LIBIO
+# include <wchar.h>
+#endif
+
+#ifndef attribute_hidden
+# define attribute_hidden
+#endif
+
+/* Unlike standard Unix `getopt', functions like `getopt_long'
+   let the user intersperse the options with the other arguments.
+
+   As `getopt_long' works, it permutes the elements of ARGV so that,
+   when it is done, all the options precede everything else.  Thus
+   all application programs are extended to handle flexible argument order.
+
+   Using `getopt' or setting the environment variable POSIXLY_CORRECT
+   disables permutation.
+   Then the application's behavior is completely standard.
+
+   GNU application programs can use a third alternative mode in which
+   they can distinguish the relative order of options and other arguments.  */
+
+#include "getopt_int.h"
+
+/* For communication from `getopt' to the caller.
+   When `getopt' finds an option that takes an argument,
+   the argument value is returned here.
+   Also, when `ordering' is RETURN_IN_ORDER,
+   each non-option ARGV-element is returned here.  */
+
+char *optarg;
+
+/* Index in ARGV of the next element to be scanned.
+   This is used for communication to and from the caller
+   and for communication between successive calls to `getopt'.
+
+   On entry to `getopt', zero means this is the first call; initialize.
+
+   When `getopt' returns -1, this is the index of the first of the
+   non-option elements that the caller should itself scan.
+
+   Otherwise, `optind' communicates from one call to the next
+   how much of ARGV has been scanned so far.  */
+
+/* 1003.2 says this must be 1 before any call.  */
+int optind = 1;
+
+/* Callers store zero here to inhibit the error message
+   for unrecognized options.  */
+
+int opterr = 1;
+
+/* Set to an option character which was unrecognized.
+   This must be initialized on some systems to avoid linking in the
+   system's own getopt implementation.  */
+
+int optopt = '?';
+
+/* Keep a global copy of all internal members of getopt_data.  */
+
+static struct _getopt_data getopt_data;
+
+\f
+#if defined HAVE_DECL_GETENV && !HAVE_DECL_GETENV
+extern char *getenv ();
+#endif
+\f
+#ifdef _LIBC
+/* Stored original parameters.
+   XXX This is no good solution.  We should rather copy the args so
+   that we can compare them later.  But we must not use malloc(3).  */
+extern int __libc_argc;
+extern char **__libc_argv;
+
+/* Bash 2.0 gives us an environment variable containing flags
+   indicating ARGV elements that should not be considered arguments.  */
+
+# ifdef USE_NONOPTION_FLAGS
+/* Defined in getopt_init.c  */
+extern char *__getopt_nonoption_flags;
+# endif
+
+# ifdef USE_NONOPTION_FLAGS
+#  define SWAP_FLAGS(ch1, ch2) \
+  if (d->__nonoption_flags_len > 0)                                          \
+    {                                                                        \
+      char __tmp = __getopt_nonoption_flags[ch1];                            \
+      __getopt_nonoption_flags[ch1] = __getopt_nonoption_flags[ch2];         \
+      __getopt_nonoption_flags[ch2] = __tmp;                                 \
+    }
+# else
+#  define SWAP_FLAGS(ch1, ch2)
+# endif
+#else  /* !_LIBC */
+# define SWAP_FLAGS(ch1, ch2)
+#endif /* _LIBC */
+
+/* Exchange two adjacent subsequences of ARGV.
+   One