Next: , Up: (dir)

Tarlz Manual

This manual is for Tarlz (version 0.3, 19 March 2018).


Copyright © 2013-2018 Antonio Diaz Diaz.

This manual is free documentation: you have unlimited permission to copy, distribute and modify it.


Next: , Previous: 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:

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:


Next: , Previous: 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.


Next: , Previous: 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


Next: , Previous: 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.


Previous: Problems, Up: Top

Concept index