diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/tarlz.texi | 348 |
1 files changed, 348 insertions, 0 deletions
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 |