diff options
Diffstat (limited to 'doc/tarlz.texi')
| -rw-r--r-- | doc/tarlz.texi | 96 |
1 files changed, 63 insertions, 33 deletions
diff --git a/doc/tarlz.texi b/doc/tarlz.texi index 47f01a2..da7abfa 100644 --- a/doc/tarlz.texi +++ b/doc/tarlz.texi @@ -6,8 +6,8 @@ @finalout @c %**end of header -@set UPDATED 27 February 2019 -@set VERSION 0.13 +@set UPDATED 12 March 2019 +@set VERSION 0.14 @dircategory Data Compression @direntry @@ -69,7 +69,8 @@ tar, which treat it like any other tar.lz archive. Tarlz can append files to the end of such compressed archives. Tarlz can create tar archives with five levels of compression granularity; -per file, per block (default), per directory, appendable solid, and solid. +per file (---no-solid), per block (---bsolid, default), per directory +(---dsolid), appendable solid (---asolid), and solid (---solid). @noindent Of course, compressing each file (or each directory) individually can't @@ -140,8 +141,7 @@ equivalent to @samp{-1 --solid} tarlz supports the following options: @table @code -@item -h -@itemx --help +@item --help Print an informative help message describing the options and exit. @item -V @@ -151,13 +151,15 @@ This version number should be included in all bug reports. @item -A @itemx --concatenate -Append tar.lz archives to the end of a tar.lz archive. All the archives -involved must be regular (seekable) files compressed as multimember lzip -files, and the two end-of-file blocks plus any zero padding must be -contained in the last lzip member of each archive. The intermediate -end-of-file blocks are removed as each new archive is concatenated. Exit -with status 0 without modifying the archive if no @var{files} have been -specified. Tarlz can't concatenate uncompressed tar archives. +Append one or more archives to the end of an archive. All the archives +involved must be regular (seekable) files, and must be either all compressed +or all uncompressed. Compressed and uncompressed archives can't be mixed. +Compressed archives must be multimember lzip files with the two end-of-file +blocks plus any zero padding contained in the last lzip member of each +archive. The intermediate end-of-file blocks are removed as each new archive +is concatenated. If the archive is uncompressed, tarlz parses and skips tar +headers until it finds the end-of-file blocks. Exit with status 0 without +modifying the archive if no @var{files} have been specified. @anchor{--data-size} @item -B @var{bytes} @@ -190,19 +192,34 @@ option appears after a relative filename in the command line. @itemx --diff Find differences between archive and file system. For each tar member in the archive, verify that the corresponding file exists and is of the same type -(regular file, directory, etc). Report the differences found in type, mode -(permissions), owner and group IDs, modification time, file size, file -contents (of regular files), target (of symlinks) and device number (of -block/character special files). +(regular file, directory, etc). Report on standard output the differences +found in type, mode (permissions), owner and group IDs, modification time, +file size, file contents (of regular files), target (of symlinks) and device +number (of block/character special files). + +As tarlz removes leading slashes from member names, the @samp{-C} option may +be used in combination with @samp{--diff} when absolute filenames were used +on archive creation: @w{@samp{tarlz -C / -d}}. Alternatively, tarlz may be +run from the root directory to perform the comparison. @item --ignore-ids Make @samp{--diff} ignore differences in owner and group IDs. This option is useful when comparing an @samp{--anonymous} archive. +@item --exclude=@var{pattern} +Exclude files matching a shell pattern like @samp{*.o}. A file is considered +to match if any component of the filename matches. For example, @samp{*.o} +matches @samp{foo.o}, @samp{foo.o/bar} and @samp{foo/bar.o}. + @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. +Use archive file @var{archive}. @samp{-} used as an @var{archive} argument +reads from standard input or writes to standard output. + +@item -h +@itemx --dereference +Follow symbolic links during archive creation, appending or comparison. +Archive or compare the files they point to instead of the links themselves. @item -n @var{n} @itemx --threads=@var{n} @@ -226,14 +243,17 @@ Quiet operation. Suppress all messages. @item -r @itemx --append -Append files to the end of a tar.lz 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. +Append files to the end of an archive. The archive must be a regular +(seekable) file either compressed or uncompressed. Compressed members can't +be appended to an uncompressed archive, nor vice versa. If the archive is +compressed, it must be a multimember lzip file with the two end-of-file +blocks plus any zero padding contained in the last lzip member of the +archive. Appending works as follows; first the end-of-file blocks are +removed, then the new members are appended, and finally two new end-of-file +blocks are appended to the archive. If the archive is uncompressed, tarlz +parses and skips tar headers until it finds the end-of-file blocks. Exit +with status 0 without modifying the archive if no @var{files} have been +specified. @item -t @itemx --list @@ -250,9 +270,10 @@ Extract files from an archive. If @var{files} are given, extract only the @var{files} given. Else extract all the files in the archive. @item -0 .. -9 -Set the compression level. The default compression level is @samp{-6}. -Like lzip, tarlz also minimizes the dictionary size of the lzip members -it creates, reducing the amount of memory required for decompression. +Set the compression level for @samp{--create} and @samp{--append}. The +default compression level is @samp{-6}. Like lzip, tarlz also minimizes the +dictionary size of the lzip members it creates, reducing the amount of +memory required for decompression. @multitable {Level} {Dictionary size} {Match length limit} @item Level @tab Dictionary size @tab Match length limit @@ -269,8 +290,10 @@ it creates, reducing the amount of memory required for decompression. @end multitable @item --uncompressed -With @samp{--create}, don't compress the created tar archive. Create an -uncompressed tar archive instead. +With @samp{--create}, don't compress the tar archive created. Create an +uncompressed tar archive instead. With @samp{--append}, don't compress the +new members appended to the tar archive. Compressed members can't be +appended to an uncompressed archive, nor vice versa. @item --asolid When creating or appending to a compressed archive, use appendable solid @@ -340,6 +363,13 @@ missing CRC instead of as a corrupt record. This misleading format; i.e., the lack of a mandatory check sequence in the extended records. @xref{crc32}. +@item --out-slots=@var{n} +Number of @w{1 MiB} output packets buffered per worker thread during +multi-threaded creation or appending to compressed archives. Increasing the +number of packets may increase compression speed if the files being archived +are larger than @w{64 MiB} compressed, but requires more memory. Valid +values range from 1 to 1024. The default value is 64. + @ignore @item --permissive Allow some violations of the archive format, like consecutive extended @@ -382,7 +412,7 @@ The members simply appear one after another in the file, with no additional information before, between, or after them. Each lzip member contains one or more tar members in a simplified posix -pax interchange format; the only pax typeflag value supported by tarlz +pax interchange format. The only pax typeflag value supported by tarlz (in addition to the typeflag values defined by the ustar format) is @samp{x}. The pax format is an extension on top of the ustar format that removes the size limitations of the ustar format. @@ -766,7 +796,7 @@ the number of available processors), the uncompressed archive must be at least as large as the number of worker threads times the block size (@pxref{--data-size}). Else some processors will not get any data to compress, and compression will be proportionally slower. The maximum speed -increase achievable on a given file is limited by the ratio +increase achievable on a given archive is limited by the ratio @w{(uncompressed_size / data_size)}. For example, a tarball the size of gcc or linux will scale up to 10 or 12 processors at level -9. |