diff options
Diffstat (limited to 'doc/tarlz.info')
| -rw-r--r-- | doc/tarlz.info | 179 |
1 files changed, 97 insertions, 82 deletions
diff --git a/doc/tarlz.info b/doc/tarlz.info index d71c0a3..25ba882 100644 --- a/doc/tarlz.info +++ b/doc/tarlz.info @@ -11,12 +11,12 @@ File: tarlz.info, Node: Top, Next: Introduction, Up: (dir) Tarlz Manual ************ -This manual is for Tarlz (version 0.23, 23 September 2022). +This manual is for Tarlz (version 0.25, 3 January 2024). * Menu: * Introduction:: Purpose and features of tarlz -* Invoking tarlz:: Command line interface +* Invoking tarlz:: Command-line interface * Portable character set:: POSIX portable filename character set * File format:: Detailed format of the compressed archive * Amendments to pax format:: The reasons for the differences with pax @@ -28,7 +28,7 @@ This manual is for Tarlz (version 0.23, 23 September 2022). * Concept index:: Index of concepts - Copyright (C) 2013-2022 Antonio Diaz Diaz. + Copyright (C) 2013-2024 Antonio Diaz Diaz. This manual is free documentation: you have unlimited permission to copy, distribute, and modify it. @@ -46,8 +46,8 @@ library lzlib. Tarlz creates tar archives using a simplified and safer variant of the POSIX pax format compressed in lzip format, keeping the alignment between tar members and lzip members. The resulting multimember tar.lz archive is -fully backward compatible with standard tar tools like GNU tar, which treat -it like any other tar.lz archive. Tarlz can append files to the end of such +backward compatible with standard 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. Keeping the alignment between tar members and lzip members has two @@ -58,9 +58,9 @@ plzip may even double the amount of files lost for each lzip member damaged because it does not keep the members aligned. Tarlz can create tar archives with five levels of compression -granularity: per file (--no-solid), per block (--bsolid, default), per -directory (--dsolid), appendable solid (--asolid), and solid (--solid). It -can also create uncompressed tar archives. +granularity: per file ('--no-solid'), per block ('--bsolid', default), per +directory ('--dsolid'), appendable solid ('--asolid'), and solid +('--solid'). It can also create uncompressed tar archives. Of course, compressing each file (or each directory) individually can't achieve a compression ratio as high as compressing solidly the whole tar @@ -87,9 +87,9 @@ archive, but it has the following advantages: Tarlz protects the extended records with a Cyclic Redundancy Check (CRC) in a way compatible with standard tar tools. *Note crc32::. - Tarlz does not understand other tar formats like 'gnu', 'oldgnu', 'star' -or 'v7'. The command 'tarlz -tf archive.tar.lz > /dev/null' can be used to -verify that the format of the archive is compatible with tarlz. + Tarlz does not understand other tar formats like 'gnu', 'oldgnu', +'star', or 'v7'. The command 'tarlz -t -f archive.tar.lz > /dev/null' can +be used to check that the format of the archive is compatible with tarlz. File: tarlz.info, Node: Invoking tarlz, Next: Portable character set, Prev: Introduction, Up: Top @@ -140,7 +140,7 @@ to '-1 --solid'. '-A' '--concatenate' Append one or more archives to the end of an archive. If no archive is - specified with the option '-f', the input archives are concatenated to + specified with the option '-f', concatenate the input archives to standard output. 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 @@ -163,7 +163,7 @@ to '-1 --solid'. '-d' '--diff' Compare and report differences between archive and file system. For - each tar member in the archive, verify that the corresponding file in + each tar member in the archive, check that the corresponding file in the file system exists 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 @@ -224,22 +224,25 @@ to '-1 --solid'. directory without extracting the files under it, use 'tarlz -xf foo --exclude='dir/*' dir'. Tarlz removes files and empty directories unconditionally before extracting over them. Other than - that, it will not make any special effort to extract a file over an + that, it does not make any special effort to extract a file over an incompatible type of file. For example, extracting a file over a - non-empty directory will usually fail. + non-empty directory usually fails. '-z' '--compress' Compress existing POSIX tar archives aligning the lzip members to the - tar members with choice of granularity (--bsolid by default, --dsolid - works like --asolid). The input archives are kept unchanged. Existing - compressed archives are not overwritten. A hyphen '-' used as the name - of an input archive reads from standard input and writes to standard - output (unless the option '--output' is used). Tarlz can be used as - compressor for GNU tar using a command like - 'tar -c -Hustar foo | tarlz -z -o foo.tar.lz'. Note that tarlz only - works reliably on archives without global headers, or with global - headers whose content can be ignored. + tar members with choice of granularity ('--bsolid' by default, + '--dsolid' works like '--asolid'). Exit with error status 2 if any + input archive is an empty file. The input archives are kept unchanged. + Existing compressed archives are not overwritten. A hyphen '-' used as + the name of an input archive reads from standard input and writes to + standard output (unless the option '--output' is used). Tarlz can be + used as compressor for GNU tar by using a command like + 'tar -c -Hustar foo | tarlz -z -o foo.tar.lz'. Tarlz can be used as + compressor for zupdate (zutils) by using a command like + 'zupdate --lz="tarlz -z" foo.tar.gz'. Note that tarlz only works + reliably on archives without global headers, or with global headers + whose content can be ignored. The compression is reversible, including any garbage present after the end-of-archive blocks. Tarlz stops parsing after the first @@ -277,18 +280,18 @@ to '-1 --solid'. '-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 or comparing, all - the '-C' options are executed in sequence before reading the archive. - Listing ignores any '-C' options specified. DIR is relative to the - then current working directory, perhaps changed by a previous '-C' + Change to directory DIR. When creating, appending, comparing, or + extracting, the position of each '-C' option in the command line is + significant; it changes the current working directory for the following + FILES until a new '-C' option appears in the command line. '--list' + and '--delete' ignore any '-C' options specified. DIR is relative to + the then current working directory, perhaps changed by a previous '-C' option. Note that a process can only have one current working directory (CWD). - Therefore multi-threading can't be used to create an archive if a '-C' - option appears after a relative file name in the command line. + Therefore multi-threading can't be used to create or decode an archive + if a '-C' option appears after a (relative) file name in the command + line. (All file names are made relative when decoding). '-f ARCHIVE' '--file=ARCHIVE' @@ -308,8 +311,7 @@ to '-1 --solid'. support". A value of 0 disables threads entirely. If this option is not used, tarlz tries to detect the number of processors in the system and use it as default value. 'tarlz --help' shows the system's default - value. See the note about multi-threaded archive creation in the - option '-C' above. + value. See the note about multi-threading in the option '-C' above. Note that the number of usable threads is limited during compression to ceil( uncompressed_size / data_size ) (*note Minimum archive sizes::), @@ -360,7 +362,9 @@ to '-1 --solid'. 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. + appended to an uncompressed archive, nor vice versa. '--uncompressed' + can be omitted if it can be deduced from the archive name. (An + uncompressed archive name lacks a '.lz' or '.tlz' extension). '--asolid' When creating or appending to a compressed archive, use appendable @@ -429,6 +433,12 @@ to '-1 --solid'. Make '--diff' ignore differences in owner and group IDs. This option is useful when comparing an '--anonymous' archive. +'--ignore-metadata' + Make '--diff' ignore any differences in metadata (file permissions, + owner and group IDs, modification time). Compare only file type, file + size, and file content. This option is useful when file permissions + have not been fully restored because uid/gid changed on extraction. + '--ignore-overflow' Make '--diff' ignore differences in mtime caused by overflow on 32-bit systems with a 32-bit time_t. @@ -438,13 +448,13 @@ to '-1 --solid'. happens while extracting a file, keep the partial data extracted. Use this option to recover as much data as possible from each damaged member. It is recommended to run tarlz in single-threaded mode - (--threads=0) when using this option. + ('--threads=0') when using this option. '--missing-crc' Exit with error status 2 if the CRC of the extended records is missing. When this option is used, tarlz detects any corruption in the extended records (only limited by CRC collisions). But note that a - corrupt 'GNU.crc32' keyword, for example 'GNU.crc33', is reported as a + corrupt 'GNU.crc32' keyword, for example 'GNU.crc30', is reported as a missing CRC instead of as a corrupt record. This misleading 'Missing CRC' message is the consequence of a flaw in the POSIX pax format; i.e., the lack of a mandatory check sequence of the extended @@ -481,7 +491,7 @@ to '-1 --solid'. Exit status: 0 for a normal exit, 1 for environmental problems (file not -found, files differ, invalid command line options, I/O errors, etc), 2 to +found, files differ, invalid command-line options, I/O errors, etc), 2 to indicate a corrupt or invalid input file, 3 for an internal consistency error (e.g., bug) which caused tarlz to panic. @@ -525,7 +535,7 @@ In the diagram below, a box like this: bytes (for example 512). - A tar.lz file consists of a series of lzip members (compressed data + A tar.lz file consists of one or more lzip members (compressed data sets). The members simply appear one after another in the file, with no additional information before, between, or after them. @@ -560,7 +570,7 @@ binary zeros, interpreted as an end-of-archive indicator. These EOA blocks are either compressed in a separate lzip member or compressed along with the tar members contained in the last lzip member. For a compressed archive to be recognized by tarlz as appendable, the last lzip member must contain -between 512 and 32256 zeros alone. +between 512 and 32256 zeros alone (without any non-zero bytes). The diagram below shows the correspondence between each tar member (formed by one or two headers plus optional data) in the tar archive and @@ -588,6 +598,10 @@ header block are zeroed on archive creation to prevent trouble if the archive is read by an ustar tool, and are ignored by tarlz on archive extraction. *Note flawed-compat::. + Tarlz limits the size of the pax extended header data so that the whole +header set (extended header + extended data + ustar header) can be read and +decoded in a buffer of size INT_MAX. + The pax extended header data consists of one or more records, each of them constructed as follows: '"%d %s=%s\n", <length>, <keyword>, <value>' @@ -610,7 +624,7 @@ space, equal-sign, and newline. 'gid' The unsigned decimal representation of the group ID of the group that owns the following file. The gid record is created only for files with - a group ID greater than 2_097_151 (octal 7777777). *Note + a group ID greater than 2_097_151 (octal 7_777_777). *Note ustar-uid-gid::. 'linkpath' @@ -618,11 +632,11 @@ space, equal-sign, and newline. previously archived. This record overrides the field 'linkname' in the following ustar header block. The following ustar header block determines the type of link created. If typeflag of the following - header block is 1, it will be a hard link. If typeflag is 2, it will - be a symbolic link and the linkpath value will be used as the contents - of the symbolic link. The linkpath record is created only for links - with a link name that does not fit in the space provided by the ustar - header. + header block is 1, a hard link is created. If typeflag is 2, a + symbolic link is created and the linkpath value is used as the + contents of the symbolic link. The linkpath record is created only for + links with a link name that does not fit in the space provided by the + ustar header. 'mtime' The signed decimal representation of the modification time of the @@ -645,19 +659,20 @@ space, equal-sign, and newline. digits from the ISO/IEC 646:1991 (ASCII) standard. This record overrides the field 'size' in the following ustar header block. The size record is created only for files with a size value greater than - 8_589_934_591 (octal 77777777777); that is, 8 GiB (2^33 bytes) or + 8_589_934_591 (octal 77_777_777_777); that is, 8 GiB (2^33 bytes) or larger. 'uid' The unsigned decimal representation of the user ID of the file owner of the following file. The uid record is created only for files with a - user ID greater than 2_097_151 (octal 7777777). *Note ustar-uid-gid::. + user ID greater than 2_097_151 (octal 7_777_777). *Note + ustar-uid-gid::. 'GNU.crc32' CRC32-C (Castagnoli) of the extended header data excluding the 8 bytes representing the CRC <value> itself. The <value> is represented as 8 hexadecimal digits in big endian order, '22 GNU.crc32=00000000\n'. The - keyword of the CRC record is protected by the CRC to guarante that + keyword of the CRC record is protected by the CRC to guarantee that corruption is always detected when using '--missing-crc' (except in case of CRC collision). A CRC was chosen because a checksum is too weak for a potentially large list of variable sized records. A @@ -729,7 +744,7 @@ S_IROTH 00004 S_IWOTH 00002 S_IXOTH 00001 The fields 'uid' and 'gid' are the user and group IDs of the owner and group of the file, respectively. If the file uid or gid are greater than -2_097_151 (octal 7777777), an extended record is used to store the uid or +2_097_151 (octal 7_777_777), an extended record is used to store the uid or gid. The field 'size' contains the octal representation of the size of the @@ -739,13 +754,13 @@ records following the header is (size / 512) rounded to the next integer. For all other values of typeflag, tarlz either sets the size field to 0 or ignores it, and does not store or expect any logical records following the header. If the file size is larger than 8_589_934_591 bytes -(octal 77777777777), an extended record is used to store the file size. +(octal 77_777_777_777), an extended record is used to store the file size. The field 'mtime' contains the octal representation of the modification time of the file at the time it was archived, obtained from the function 'stat'. If the modification time is negative or larger than 8_589_934_591 -(octal 77777777777) seconds since the epoch, an extended record is used to -store the modification time. The ustar range of mtime goes from +(octal 77_777_777_777) seconds since the epoch, an extended record is used +to store the modification time. The ustar range of mtime goes from '1970-01-01 00:00:00 UTC' to '2242-03-16 12:56:31 UTC'. The field 'chksum' contains the octal representation of the value of the @@ -827,7 +842,7 @@ more probable. Headers and metadata must be protected separately from data because the integrity checking of lzip may not be able to detect the corruption before -the metadata has been used, for example, to create a new file in the wrong +the metadata have been used, for example, to create a new file in the wrong place. Because of the above, tarlz protects the extended records with a Cyclic @@ -843,11 +858,11 @@ to the POSIX-2:1993 standard, POSIX.1-2008 recommends selecting extended header field values that allow such tar to create a regular file containing the extended header records as data. This approach is broken because if the extended header is needed because of a long file name, the fields 'name' -and 'prefix' will be unable to contain the full file name. (Some tar +and 'prefix' are unable to contain the full file name. (Some tar implementations store the truncated name in the field 'name' alone, truncating the name to only 100 bytes instead of 256). Therefore the files corresponding to both the extended header and the overridden ustar header -will be extracted using truncated file names, perhaps overwriting existing +are extracted using truncated file names, perhaps overwriting existing files or directories. It may be a security risk to extract a file with a truncated file name. @@ -915,7 +930,7 @@ There is no portable way to tell what charset a text string is coded into. Therefore, tarlz stores all fields representing text strings unmodified, without conversion to UTF-8 nor any other transformation. This prevents accidental double UTF-8 conversions. If the need arises this behavior will -be adjusted with a command line option in the future. +be adjusted with a command-line option in the future. File: tarlz.info, Node: Program design, Next: Multi-threaded decoding, Prev: Amendments to pax format, Up: Top @@ -1098,11 +1113,11 @@ multimember compressed archive. For this to work as expected (and roughly multiply the compression 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 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 14 processors at level -9. +--data-size::). Else some processors do not get any data to compress, and +compression is proportionally slower. 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 scales up to 10 or 14 +processors at level -9. The following table shows the minimum uncompressed archive size needed for full use of N processors at a given compression level, using the default @@ -1244,25 +1259,25 @@ Concept index Tag Table: Node: Top216 -Node: Introduction1210 -Node: Invoking tarlz4029 -Ref: --data-size12880 -Ref: --bsolid17192 -Node: Portable character set22788 -Node: File format23431 -Ref: key_crc3230188 -Ref: ustar-uid-gid33452 -Ref: ustar-mtime34254 -Node: Amendments to pax format36254 -Ref: crc3236963 -Ref: flawed-compat38274 -Node: Program design42364 -Node: Multi-threaded decoding46289 -Ref: mt-extraction49570 -Node: Minimum archive sizes50876 -Node: Examples53014 -Node: Problems55381 -Node: Concept index55936 +Node: Introduction1207 +Node: Invoking tarlz4032 +Ref: --data-size13076 +Ref: --bsolid17512 +Node: Portable character set23425 +Node: File format24068 +Ref: key_crc3231050 +Ref: ustar-uid-gid34315 +Ref: ustar-mtime35122 +Node: Amendments to pax format37125 +Ref: crc3237834 +Ref: flawed-compat39146 +Node: Program design43228 +Node: Multi-threaded decoding47153 +Ref: mt-extraction50434 +Node: Minimum archive sizes51740 +Node: Examples53867 +Node: Problems56234 +Node: Concept index56789 End Tag Table |