diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/tarlz.1 | 88 | ||||
| -rw-r--r-- | doc/tarlz.info | 311 | ||||
| -rw-r--r-- | doc/tarlz.texi | 348 |
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 |