Adding upstream version 0.4.upstream/0.4

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

3 files changed, 747 insertions, 0 deletions

diff --git a/doc/tarlz.1 b/doc/tarlz.1
new file mode 100644
index 0000000..6b685c5
--- /dev/null
+++ b/doc/tarlz.1
@@ -0,0 +1,88 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.46.1.
+.TH TARLZ "1" "April 2018" "tarlz 0.4" "User Commands"
+.SH NAME
+tarlz \- creates tar archives with multimember lzip compression
+.SH SYNOPSIS
+.B tarlz
+[\fI\,options\/\fR] [\fI\,files\/\fR]
+.SH DESCRIPTION
+Tarlz \- Archiver with multimember lzip compression.
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+output version information and exit
+.TP
+\fB\-c\fR, \fB\-\-create\fR
+create a new archive
+.TP
+\fB\-C\fR, \fB\-\-directory=\fR<dir>
+change to directory <dir>
+.TP
+\fB\-f\fR, \fB\-\-file=\fR<archive>
+use archive file <archive>
+.TP
+\fB\-q\fR, \fB\-\-quiet\fR
+suppress all messages
+.TP
+\fB\-r\fR, \fB\-\-append\fR
+append files to the end of an archive
+.TP
+\fB\-t\fR, \fB\-\-list\fR
+list the contents of an archive
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+verbosely list files processed
+.TP
+\fB\-x\fR, \fB\-\-extract\fR
+extract files from an archive
+.TP
+\fB\-0\fR .. \fB\-9\fR
+set compression level [default 6]
+.TP
+\fB\-\-asolid\fR
+create solidly compressed appendable archive
+.TP
+\fB\-\-dsolid\fR
+create per\-directory compressed archive
+.TP
+\fB\-\-solid\fR
+create solidly compressed archive
+.TP
+\fB\-\-group=\fR<group>
+use <group> name/id for added files
+.TP
+\fB\-\-owner=\fR<owner>
+use <owner> name/id for added files
+.TP
+\fB\-\-uncompressed\fR
+don't compress the created archive
+.PP
+Exit status: 0 for a normal exit, 1 for environmental problems (file
+not found, invalid flags, I/O errors, etc), 2 to indicate a corrupt or
+invalid input file, 3 for an internal consistency error (eg, bug) which
+caused tarlz to panic.
+.SH "REPORTING BUGS"
+Report bugs to lzip\-bug@nongnu.org
+.br
+Tarlz home page: http://www.nongnu.org/lzip/tarlz.html
+.SH COPYRIGHT
+Copyright \(co 2018 Antonio Diaz Diaz.
+License GPLv2+: GNU GPL version 2 or later <http://gnu.org/licenses/gpl.html>
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+The full documentation for
+.B tarlz
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B tarlz
+programs are properly installed at your site, the command
+.IP
+.B info tarlz
+.PP
+should give you access to the complete manual.
diff --git a/doc/tarlz.info b/doc/tarlz.info
new file mode 100644
index 0000000..140336b
--- /dev/null
+++ b/doc/tarlz.info
@@ -0,0 +1,311 @@
+This is tarlz.info, produced by makeinfo version 4.13+ from tarlz.texi.
+
+INFO-DIR-SECTION Data Compression
+START-INFO-DIR-ENTRY
+* Tarlz: (tarlz).               Archiver with multimember lzip compression
+END-INFO-DIR-ENTRY
+
+
+File: tarlz.info,  Node: Top,  Next: Introduction,  Up: (dir)
+
+Tarlz Manual
+************
+
+This manual is for Tarlz (version 0.4, 23 April 2018).
+
+* Menu:
+
+* Introduction::           Purpose and features of tarlz
+* Invoking tarlz::         Command line interface
+* Examples::               A small tutorial with examples
+* Problems::               Reporting bugs
+* Concept index::          Index of concepts
+
+
+   Copyright (C) 2013-2018 Antonio Diaz Diaz.
+
+   This manual is free documentation: you have unlimited permission to
+copy, distribute and modify it.
+
+
+File: tarlz.info,  Node: Introduction,  Next: Invoking tarlz,  Prev: Top,  Up: Top
+
+1 Introduction
+**************
+
+Tarlz is a small and simple implementation of the tar archiver. By
+default tarlz creates, lists and extracts archives in the 'ustar' format
+compressed with lzip on a per file basis. Tarlz can append files to the
+end of such compressed archives.
+
+   Each tar member is compressed in its own lzip member, as well as the
+end-of-file blocks. This same method works for any tar format (gnu,
+ustar, posix) and is fully backward compatible with standard tar tools
+like GNU tar, which treat the resulting multimember tar.lz archive like
+any other tar.lz archive.
+
+   Tarlz can create tar archives with four levels of compression
+granularity; per file, per directory, appendable solid, and solid.
+
+   Tarlz is intended as a showcase project for the maintainers of real
+tar programs to evaluate the format and perhaps implement it in their
+tools.
+
+   The diagram below shows the correspondence between tar members
+(formed by a header plus optional data) in the tar archive and lzip
+members in the resulting multimember tar.lz archive: *Note File format:
+(lzip)File format.
+
+tar
++========+======+========+======+========+======+========+
+| header | data | header | data | header | data |   eof  |
++========+======+========+======+========+======+========+
+
+tar.lz
++===============+===============+===============+========+
+|     member    |     member    |     member    | member |
++===============+===============+===============+========+
+
+Of course, compressing each file (or each directory) individually is
+less efficient than compressing the whole tar archive, but it has the
+following advantages:
+
+   * The resulting multimember tar.lz archive can be decompressed in
+     parallel with plzip, multiplying the decompression speed.
+
+   * New members can be appended to the archive (by removing the eof
+     member) just like to an uncompressed tar archive.
+
+   * It is a safe posix-style backup format. In case of corruption,
+     tarlz can extract all the undamaged members from the tar.lz
+     archive, skipping over the damaged members, just like the standard
+     (uncompressed) tar. Moreover, lziprecover can be used to recover at
+     least part of the contents of the damaged members.
+
+   * A multimember tar.lz archive is usually smaller than the
+     corresponding solidly compressed tar.gz archive, except when
+     individually compressing files smaller than about 32 KiB.
+
+
+File: tarlz.info,  Node: Invoking tarlz,  Next: Examples,  Prev: Introduction,  Up: Top
+
+2 Invoking tarlz
+****************
+
+The format for running tarlz is:
+
+     tarlz [OPTIONS] [FILES]
+
+On archive creation or appending, tarlz removes leading and trailing
+slashes from file names, as well as file name prefixes containing a
+'..' component. On extraction, archive members containing a '..'
+component are skipped.
+
+   tarlz supports the following options:
+
+'-h'
+'--help'
+     Print an informative help message describing the options and exit.
+
+'-V'
+'--version'
+     Print the version number of tarlz on the standard output and exit.
+
+'-c'
+'--create'
+     Create a new archive.
+
+'-C DIR'
+'--directory=DIR'
+     Change to directory DIR. When creating or appending, the position
+     of each '-C' option in the command line is significant; it will
+     change the current working directory for the following FILES until
+     a new '-C' option appears in the command line. When extracting, all
+     the '-C' options are executed in sequence before starting the
+     extraction. Listing ignores any '-C' options specified. DIR is
+     relative to the then current working directory, perhaps changed by
+     a previous '-C' option.
+
+'-f ARCHIVE'
+'--file=ARCHIVE'
+     Use archive file ARCHIVE. '-' used as an ARCHIVE argument reads
+     from standard input or writes to standard output.
+
+'-q'
+'--quiet'
+     Quiet operation. Suppress all messages.
+
+'-r'
+'--append'
+     Append files to the end of an archive. The archive must be a
+     regular (seekable) file compressed as a multimember lzip file, and
+     the two end-of-file blocks plus any zero padding must be contained
+     in the last lzip member of the archive. First this last member is
+     removed, then the new members are appended, and then a new
+     end-of-file member is appended to the archive. Exit with status 0
+     without modifying the archive if no FILES have been specified.
+     tarlz can't append files to an uncompressed tar archive.
+
+'-t'
+'--list'
+     List the contents of an archive.
+
+'-v'
+'--verbose'
+     Verbosely list files processed.
+
+'-x'
+'--extract'
+     Extract files from an archive.
+
+'-0 .. -9'
+     Set the compression level. The default compression level is '-6'.
+
+'--asolid'
+     When creating or appending to a compressed archive, use appendable
+     solid compression. All the files being added to the archive are
+     compressed into a single lzip member, but the end-of-file blocks
+     are compressed into a separate lzip member. This creates a solidly
+     compressed appendable archive.
+
+'--dsolid'
+     When creating or appending to a compressed archive, use solid
+     compression for each directory especified in the command line. The
+     end-of-file blocks are compressed into a separate lzip member. This
+     creates a compressed appendable archive with a separate lzip
+     member for each top-level directory.
+
+'--solid'
+     When creating or appending to a compressed archive, use solid
+     compression. The files being added to the archive, along with the
+     end-of-file blocks, are compressed into a single lzip member. The
+     resulting archive is not appendable. No more files can be later
+     appended to the archive without decompressing it first.
+
+'--group=GROUP'
+     When creating or appending, use GROUP for files added to the
+     archive. If GROUP is not a valid group name, it is decoded as a
+     decimal numeric group ID.
+
+'--owner=OWNER'
+     When creating or appending, use OWNER for files added to the
+     archive. If OWNER is not a valid user name, it is decoded as a
+     decimal numeric user ID.
+
+'--uncompressed'
+     With '--create', don't compress the created tar archive. Create an
+     uncompressed tar archive instead.
+
+
+   Exit status: 0 for a normal exit, 1 for environmental problems (file
+not found, invalid flags, I/O errors, etc), 2 to indicate a corrupt or
+invalid input file, 3 for an internal consistency error (eg, bug) which
+caused tarlz to panic.
+
+
+File: tarlz.info,  Node: Examples,  Next: Problems,  Prev: Invoking tarlz,  Up: Top
+
+3 A small tutorial with examples
+********************************
+
+Example 1: Create a multimember compressed archive 'archive.tar.lz'
+containing files 'a', 'b' and 'c'.
+
+     tarlz -cf archive.tar.lz a b c
+
+
+Example 2: Append files 'd' and 'e' to the multimember compressed
+archive 'archive.tar.lz'.
+
+     tarlz -rf archive.tar.lz d e
+
+
+Example 3: Create a solidly compressed appendable archive
+'archive.tar.lz' containing files 'a', 'b' and 'c'.  Then append files
+'d' and 'e' to the archive.
+
+     tarlz --asolid -cf archive.tar.lz a b c
+     tarlz --asolid -rf archive.tar.lz d e
+
+
+Example 4: Create a compressed appendable archive containing directories
+'dir1', 'dir2' and 'dir3' with a separate lzip member per directory.
+Then append files 'a', 'b', 'c', 'd' and 'e' to the archive, all of
+them contained in a single lzip member.  The resulting archive
+'archive.tar.lz' contains 5 lzip members (including the eof member).
+
+     tarlz --dsolid -cf archive.tar.lz dir1 dir2 dir3
+     tarlz --asolid -rf archive.tar.lz a b c d e
+
+
+Example 5: Create a solidly compressed archive 'archive.tar.lz'
+containing files 'a', 'b' and 'c'. Note that no more files can be later
+appended to the archive without decompressing it first.
+
+     tarlz --solid -cf archive.tar.lz a b c
+
+
+Example 6: Extract all files from archive 'archive.tar.lz'.
+
+     tarlz -xf archive.tar.lz
+
+
+Example 7: Extract files 'a' and 'c' from archive 'archive.tar.lz'.
+
+     tarlz -xf archive.tar.lz a c
+
+
+Example 8: Copy the contents of directory 'sourcedir' to the directory
+'targetdir'.
+
+     tarlz -C sourcedir -c . | tarlz -C targetdir -x
+
+
+File: tarlz.info,  Node: Problems,  Next: Concept index,  Prev: Examples,  Up: Top
+
+4 Reporting bugs
+****************
+
+There are probably bugs in tarlz. There are certainly errors and
+omissions in this manual. If you report them, they will get fixed. If
+you don't, no one will ever know about them and they will remain unfixed
+for all eternity, if not longer.
+
+   If you find a bug in tarlz, please send electronic mail to
+<lzip-bug@nongnu.org>. Include the version number, which you can find
+by running 'tarlz --version'.
+
+
+File: tarlz.info,  Node: Concept index,  Prev: Problems,  Up: Top
+
+Concept index
+*************
+
+
+* Menu:
+
+* bugs:                                  Problems.              (line 6)
+* examples:                              Examples.              (line 6)
+* getting help:                          Problems.              (line 6)
+* introduction:                          Introduction.          (line 6)
+* invoking:                              Invoking tarlz.        (line 6)
+* options:                               Invoking tarlz.        (line 6)
+* usage:                                 Invoking tarlz.        (line 6)
+* version:                               Invoking tarlz.        (line 6)
+
+
+
+Tag Table:
+Node: Top223
+Node: Introduction785
+Node: Invoking tarlz3280
+Node: Examples7278
+Node: Problems8975
+Node: Concept index9501
+
+End Tag Table
+
+
+Local Variables:
+coding: iso-8859-15
+End:
diff --git a/doc/tarlz.texi b/doc/tarlz.texi
new file mode 100644
index 0000000..db51dd6
--- /dev/null
+++ b/doc/tarlz.texi
@@ -0,0 +1,348 @@
+\input texinfo @c -*-texinfo-*-
+@c %**start of header
+@setfilename tarlz.info
+@documentencoding ISO-8859-15
+@settitle Tarlz Manual
+@finalout
+@c %**end of header
+
+@set UPDATED 23 April 2018
+@set VERSION 0.4
+
+@dircategory Data Compression
+@direntry
+* Tarlz: (tarlz).               Archiver with multimember lzip compression
+@end direntry
+
+
+@ifnothtml
+@titlepage
+@title Tarlz
+@subtitle Archiver with multimember lzip compression
+@subtitle for Tarlz version @value{VERSION}, @value{UPDATED}
+@author by Antonio Diaz Diaz
+
+@page
+@vskip 0pt plus 1filll
+@end titlepage
+
+@contents
+@end ifnothtml
+
+@node Top
+@top
+
+This manual is for Tarlz (version @value{VERSION}, @value{UPDATED}).
+
+@menu
+* Introduction::           Purpose and features of tarlz
+* Invoking tarlz::         Command line interface
+* Examples::               A small tutorial with examples
+* Problems::               Reporting bugs
+* Concept index::          Index of concepts
+@end menu
+
+@sp 1
+Copyright @copyright{} 2013-2018 Antonio Diaz Diaz.
+
+This manual is free documentation: you have unlimited permission
+to copy, distribute and modify it.
+
+
+@node Introduction
+@chapter Introduction
+@cindex introduction
+
+Tarlz is a small and simple implementation of the tar archiver. By
+default tarlz creates, lists and extracts archives in the 'ustar' format
+compressed with lzip on a per file basis. Tarlz can append files to the
+end of such compressed archives.
+
+Each tar member is compressed in its own lzip member, as well as the
+end-of-file blocks. This same method works for any tar format (gnu,
+ustar, posix) and is fully backward compatible with standard tar tools
+like GNU tar, which treat the resulting multimember tar.lz archive like
+any other tar.lz archive.
+
+Tarlz can create tar archives with four levels of compression
+granularity; per file, per directory, appendable solid, and solid.
+
+Tarlz is intended as a showcase project for the maintainers of real tar
+programs to evaluate the format and perhaps implement it in their tools.
+
+The diagram below shows the correspondence between tar members (formed
+by a header plus optional data) in the tar archive and
+@uref{http://www.nongnu.org/lzip/manual/lzip_manual.html#File-format,,lzip members}
+in the resulting multimember tar.lz archive:
+@ifnothtml
+@xref{File format,,,lzip}.
+@end ifnothtml
+
+@verbatim
+tar
++========+======+========+======+========+======+========+
+| header | data | header | data | header | data |   eof  |
++========+======+========+======+========+======+========+
+
+tar.lz
++===============+===============+===============+========+
+|     member    |     member    |     member    | member |
++===============+===============+===============+========+
+@end verbatim
+
+@noindent
+Of course, compressing each file (or each directory) individually is
+less efficient than compressing the whole tar archive, but it has the
+following advantages:
+
+@itemize @bullet
+@item
+The resulting multimember tar.lz archive can be decompressed in
+parallel with plzip, multiplying the decompression speed.
+
+@item
+New members can be appended to the archive (by removing the eof
+member) just like to an uncompressed tar archive.
+
+@item
+It is a safe posix-style backup format. In case of corruption,
+tarlz can extract all the undamaged members from the tar.lz
+archive, skipping over the damaged members, just like the standard
+(uncompressed) tar. Moreover, lziprecover can be used to recover at
+least part of the contents of the damaged members.
+
+@item
+A multimember tar.lz archive is usually smaller than the
+corresponding solidly compressed tar.gz archive, except when
+individually compressing files smaller than about 32 KiB.
+@end itemize
+
+
+@node Invoking tarlz
+@chapter Invoking tarlz
+@cindex invoking
+@cindex options
+@cindex usage
+@cindex version
+
+The format for running tarlz is:
+
+@example
+tarlz [@var{options}] [@var{files}]
+@end example
+
+@noindent
+On archive creation or appending, tarlz removes leading and trailing
+slashes from file names, as well as file name prefixes containing a
+@samp{..} component. On extraction, archive members containing a
+@samp{..} component are skipped.
+
+tarlz supports the following options:
+
+@table @code
+@item -h
+@itemx --help
+Print an informative help message describing the options and exit.
+
+@item -V
+@itemx --version
+Print the version number of tarlz on the standard output and exit.
+
+@item -c
+@itemx --create
+Create a new archive.
+
+@item -C @var{dir}
+@itemx --directory=@var{dir}
+Change to directory @var{dir}. When creating or appending, the position
+of each @code{-C} option in the command line is significant; it will
+change the current working directory for the following @var{files} until
+a new @code{-C} option appears in the command line. When extracting, all
+the @code{-C} options are executed in sequence before starting the
+extraction. Listing ignores any @code{-C} options specified. @var{dir}
+is relative to the then current working directory, perhaps changed by a
+previous @code{-C} option.
+
+@item -f @var{archive}
+@itemx --file=@var{archive}
+Use archive file @var{archive}. @samp{-} used as an @var{archive}
+argument reads from standard input or writes to standard output.
+
+@item -q
+@itemx --quiet
+Quiet operation. Suppress all messages.
+
+@item -r
+@itemx --append
+Append files to the end of an archive. The archive must be a regular
+(seekable) file compressed as a multimember lzip file, and the two
+end-of-file blocks plus any zero padding must be contained in the last
+lzip member of the archive. First this last member is removed, then the
+new members are appended, and then a new end-of-file member is appended
+to the archive. Exit with status 0 without modifying the archive if no
+@var{files} have been specified. tarlz can't append files to an
+uncompressed tar archive.
+
+@item -t
+@itemx --list
+List the contents of an archive.
+
+@item -v
+@itemx --verbose
+Verbosely list files processed.
+
+@item -x
+@itemx --extract
+Extract files from an archive.
+
+@item -0 .. -9
+Set the compression level. The default compression level is @samp{-6}.
+
+@item --asolid
+When creating or appending to a compressed archive, use appendable solid
+compression. All the files being added to the archive are compressed
+into a single lzip member, but the end-of-file blocks are compressed
+into a separate lzip member. This creates a solidly compressed
+appendable archive.
+
+@item --dsolid
+When creating or appending to a compressed archive, use solid
+compression for each directory especified in the command line. The
+end-of-file blocks are compressed into a separate lzip member. This
+creates a compressed appendable archive with a separate lzip member for
+each top-level directory.
+
+@item --solid
+When creating or appending to a compressed archive, use solid
+compression. The files being added to the archive, along with the
+end-of-file blocks, are compressed into a single lzip member. The
+resulting archive is not appendable. No more files can be later appended
+to the archive without decompressing it first.
+
+@item --group=@var{group}
+When creating or appending, use @var{group} for files added to the
+archive. If @var{group} is not a valid group name, it is decoded as a
+decimal numeric group ID.
+
+@item --owner=@var{owner}
+When creating or appending, use @var{owner} for files added to the
+archive. If @var{owner} is not a valid user name, it is decoded as a
+decimal numeric user ID.
+
+@item --uncompressed
+With @code{--create}, don't compress the created tar archive. Create an
+uncompressed tar archive instead.
+
+@end table
+
+Exit status: 0 for a normal exit, 1 for environmental problems (file not
+found, invalid flags, I/O errors, etc), 2 to indicate a corrupt or
+invalid input file, 3 for an internal consistency error (eg, bug) which
+caused tarlz to panic.
+
+
+@node Examples
+@chapter A small tutorial with examples
+@cindex examples
+
+@noindent
+Example 1: Create a multimember compressed archive @samp{archive.tar.lz}
+containing files @samp{a}, @samp{b} and @samp{c}.
+
+@example
+tarlz -cf archive.tar.lz a b c
+@end example
+
+@sp 1
+@noindent
+Example 2: Append files @samp{d} and @samp{e} to the multimember
+compressed archive @samp{archive.tar.lz}.
+
+@example
+tarlz -rf archive.tar.lz d e
+@end example
+
+@sp 1
+@noindent
+Example 3: Create a solidly compressed appendable archive
+@samp{archive.tar.lz} containing files @samp{a}, @samp{b} and @samp{c}.
+Then append files @samp{d} and @samp{e} to the archive.
+
+@example
+tarlz --asolid -cf archive.tar.lz a b c
+tarlz --asolid -rf archive.tar.lz d e
+@end example
+
+@sp 1
+@noindent
+Example 4: Create a compressed appendable archive containing directories
+@samp{dir1}, @samp{dir2} and @samp{dir3} with a separate lzip member per
+directory. Then append files @samp{a}, @samp{b}, @samp{c}, @samp{d} and
+@samp{e} to the archive, all of them contained in a single lzip member.
+The resulting archive @samp{archive.tar.lz} contains 5 lzip members
+(including the eof member).
+
+@example
+tarlz --dsolid -cf archive.tar.lz dir1 dir2 dir3
+tarlz --asolid -rf archive.tar.lz a b c d e
+@end example
+
+@sp 1
+@noindent
+Example 5: Create a solidly compressed archive @samp{archive.tar.lz}
+containing files @samp{a}, @samp{b} and @samp{c}. Note that no more
+files can be later appended to the archive without decompressing it
+first.
+
+@example
+tarlz --solid -cf archive.tar.lz a b c
+@end example
+
+@sp 1
+@noindent
+Example 6: Extract all files from archive @samp{archive.tar.lz}.
+
+@example
+tarlz -xf archive.tar.lz
+@end example
+
+@sp 1
+@noindent
+Example 7: Extract files @samp{a} and @samp{c} from archive
+@samp{archive.tar.lz}.
+
+@example
+tarlz -xf archive.tar.lz a c
+@end example
+
+@sp 1
+@noindent
+Example 8: Copy the contents of directory @samp{sourcedir} to the
+directory @samp{targetdir}.
+
+@example
+tarlz -C sourcedir -c . | tarlz -C targetdir -x
+@end example
+
+
+@node Problems
+@chapter Reporting bugs
+@cindex bugs
+@cindex getting help
+
+There are probably bugs in tarlz. There are certainly errors and
+omissions in this manual. If you report them, they will get fixed. If
+you don't, no one will ever know about them and they will remain unfixed
+for all eternity, if not longer.
+
+If you find a bug in tarlz, please send electronic mail to
+@email{lzip-bug@@nongnu.org}. Include the version number, which you can
+find by running @w{@code{tarlz --version}}.
+
+
+@node Concept index
+@unnumbered Concept index
+
+@printindex cp
+
+@bye