diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/tarlz.1 | 13 | ||||
| -rw-r--r-- | doc/tarlz.info | 127 | ||||
| -rw-r--r-- | doc/tarlz.texi | 96 |
3 files changed, 154 insertions, 82 deletions
diff --git a/doc/tarlz.1 b/doc/tarlz.1 index 47be9a8..a17e58d 100644 --- a/doc/tarlz.1 +++ b/doc/tarlz.1 @@ -1,5 +1,5 @@ .\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.46.1. -.TH TARLZ "1" "February 2019" "tarlz 0.13" "User Commands" +.TH TARLZ "1" "March 2019" "tarlz 0.14" "User Commands" .SH NAME tarlz \- creates tar archives with multimember lzip compression .SH SYNOPSIS @@ -24,7 +24,7 @@ recover as much data as possible from each damaged member, and lziprecover can be used to recover some of the damaged members. .SH OPTIONS .TP -\fB\-h\fR, \fB\-\-help\fR +\fB\-\-help\fR display this help and exit .TP \fB\-V\fR, \fB\-\-version\fR @@ -48,9 +48,15 @@ find differences between archive and file system \fB\-\-ignore\-ids\fR ignore differences in owner and group IDs .TP +\fB\-\-exclude=\fR<pattern> +exclude files matching a shell pattern +.TP \fB\-f\fR, \fB\-\-file=\fR<archive> use archive file <archive> .TP +\fB\-h\fR, \fB\-\-dereference\fR +follow symlinks; archive the files they point to +.TP \fB\-n\fR, \fB\-\-threads=\fR<n> set number of (de)compression threads [2] .TP @@ -104,6 +110,9 @@ don't delete partially extracted files .TP \fB\-\-missing\-crc\fR exit with error status if missing extended CRC +.TP +\fB\-\-out\-slots=\fR<n> +number of 1 MiB output packets buffered [64] .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 diff --git a/doc/tarlz.info b/doc/tarlz.info index fa8666c..fc1f092 100644 --- a/doc/tarlz.info +++ b/doc/tarlz.info @@ -11,7 +11,7 @@ File: tarlz.info, Node: Top, Next: Introduction, Up: (dir) Tarlz Manual ************ -This manual is for Tarlz (version 0.13, 27 February 2019). +This manual is for Tarlz (version 0.14, 12 March 2019). * Menu: @@ -48,8 +48,8 @@ tar tools like GNU 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. +granularity; per file (--no-solid), per block (--bsolid, default), per +directory (--dsolid), appendable solid (--asolid), and solid (--solid). Of course, compressing each file (or each directory) individually can't achieve a compression ratio as high as compressing solidly the whole tar @@ -107,7 +107,6 @@ equivalent to '-1 --solid' tarlz supports the following options: -'-h' '--help' Print an informative help message describing the options and exit. @@ -118,14 +117,17 @@ equivalent to '-1 --solid' '-A' '--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 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 FILES have been + specified. '-B BYTES' '--data-size=BYTES' @@ -158,21 +160,38 @@ equivalent to '-1 --solid' '--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). + and is of the same type (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 '-C' + option may be used in combination with '--diff' when absolute + filenames were used on archive creation: 'tarlz -C / -d'. + Alternatively, tarlz may be run from the root directory to perform + the comparison. '--ignore-ids' Make '--diff' ignore differences in owner and group IDs. This option is useful when comparing an '--anonymous' archive. +'--exclude=PATTERN' + Exclude files matching a shell pattern like '*.o'. A file is + considered to match if any component of the filename matches. For + example, '*.o' matches 'foo.o', 'foo.o/bar' and 'foo/bar.o'. + '-f ARCHIVE' '--file=ARCHIVE' Use archive file ARCHIVE. '-' used as an ARCHIVE argument reads from standard input or writes to standard output. +'-h' +'--dereference' + Follow symbolic links during archive creation, appending or + comparison. Archive or compare the files they point to instead of + the links themselves. + '-n N' '--threads=N' Set the number of (de)compression threads, overriding the system's @@ -197,14 +216,18 @@ equivalent to '-1 --solid' '-r' '--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 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 FILES have been specified. '-t' '--list' @@ -221,10 +244,10 @@ equivalent to '-1 --solid' the FILES given. Else extract all the files in the archive. '-0 .. -9' - Set the compression level. The default compression level is '-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 '--create' and '--append'. The + default compression level is '-6'. Like lzip, tarlz also minimizes + the dictionary size of the lzip members it creates, reducing the + amount of memory required for decompression. Level Dictionary size Match length limit -0 64 KiB 16 bytes @@ -239,8 +262,10 @@ equivalent to '-1 --solid' -9 32 MiB 273 bytes '--uncompressed' - With '--create', don't compress the created tar archive. Create an - uncompressed tar archive instead. + With '--create', don't compress the tar archive created. Create an + uncompressed tar archive instead. With '--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. '--asolid' When creating or appending to a compressed archive, use appendable @@ -314,6 +339,14 @@ equivalent to '-1 --solid' the posix pax format; i.e., the lack of a mandatory check sequence in the extended records. *Note crc32::. +'--out-slots=N' + Number of 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 64 MiB compressed, but + requires more memory. Valid values range from 1 to 1024. The + default value is 64. + 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 @@ -345,7 +378,7 @@ sets). 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 +posix pax interchange format. The only pax typeflag value supported by tarlz (in addition to the typeflag values defined by the ustar format) is 'x'. The pax format is an extension on top of the ustar format that removes the size limitations of the ustar format. @@ -714,7 +747,7 @@ speed by the number of available processors), the uncompressed archive must be at least as large as the number of worker threads times the block size (*note --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 +maximum speed increase achievable on a given archive is limited by the ratio (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. @@ -835,20 +868,20 @@ Concept index Tag Table: Node: Top223 -Node: Introduction1089 -Node: Invoking tarlz3228 -Ref: --data-size5107 -Ref: --bsolid10054 -Node: File format13298 -Ref: key_crc3218118 -Node: Amendments to pax format23535 -Ref: crc3224059 -Ref: flawed-compat25084 -Node: Multi-threaded tar27451 -Node: Minimum archive sizes29990 -Node: Examples32120 -Node: Problems33789 -Node: Concept index34315 +Node: Introduction1086 +Node: Invoking tarlz3280 +Ref: --data-size5339 +Ref: --bsolid11442 +Node: File format15072 +Ref: key_crc3219892 +Node: Amendments to pax format25309 +Ref: crc3225833 +Ref: flawed-compat26858 +Node: Multi-threaded tar29225 +Node: Minimum archive sizes31764 +Node: Examples33897 +Node: Problems35566 +Node: Concept index36092 End Tag Table 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. |