Adding upstream version 0.4.
Signed-off-by: Daniel Baumann <daniel@debian.org>
This commit is contained in:
parent
7b75053a36
commit
481ef88a11
GPG key ID:
FBB4F0E80A80222F
43 changed files with 4518 additions and 0 deletions
348
doc/tarlz.texi
Normal file
348
doc/tarlz.texi
Normal file
|
|
@ -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
|
||||
Loading…
Add table
Add a link
Reference in a new issue