--- tar.1 2024-05-30 16:22:37.950249152 +0000 +++ tar.1.new 2024-05-30 18:45:39.823463611 +0000 @@ -21,7 +21,6 @@ tar \- an archiving utility \fBtar\fR {\fBA\fR|\fBc\fR|\fBd\fR|\fBr\fR|\fBt\fR|\fBu\fR|\fBx\fR}\ [\fBGnSkUWOmpsMBiajJzZhPlRvwo\fR] [\fIARG\fR...] .SS UNIX-style usage -.sp \fBtar\fR \fB\-A\fR [\fIOPTIONS\fR] \fB\-f\fR \fIARCHIVE\fR \fIARCHIVE\fR... .sp \fBtar\fR \fB\-c\fR [\fB\-f\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIFILE\fR...] @@ -36,24 +35,32 @@ tar \- an archiving utility .sp \fBtar\fR \fB\-x\fR [\fB\-f\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIMEMBER\fR...] .SS GNU-style usage +\fBtar\fR {\fB\-\-catenate\fR|\fB\-\-concatenate\fR} [\fIOPTIONS\fR] \ +\fB\-\-file\fR \fIARCHIVE\fR \fIARCHIVE\fR... .sp -\fBtar\fR {\fB\-\-catenate\fR|\fB\-\-concatenate\fR} [\fIOPTIONS\fR] \fB\-\-file\fR \fIARCHIVE\fR \fIARCHIVE\fR... -.sp -\fBtar\fR \fB\-\-create\fR [\fB\-\-file\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIFILE\fR...] +\fBtar\fR \fB\-\-create\fR [\fB\-\-file\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] \ +[\fIFILE\fR...] .sp -\fBtar\fR {\fB\-\-diff\fR|\fB\-\-compare\fR} [\fB\-\-file\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIFILE\fR...] +\fBtar\fR {\fB\-\-diff\fR|\fB\-\-compare\fR} [\fB\-\-file\fR \fIARCHIVE\fR] \ +[\fIOPTIONS\fR] [\fIFILE\fR...] .sp -\fBtar\fR \fB\-\-delete\fR [\fB\-\-file\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIMEMBER\fR...] +\fBtar\fR \fB\-\-delete\fR [\fB\-\-file\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] \ +[\fIMEMBER\fR...] .sp -\fBtar\fR \fB\-\-append\fR [\fB\-\-file\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIFILE\fR...] +\fBtar\fR \fB\-\-append\fR [\fB\-\-file\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] \ +[\fIFILE\fR...] .sp -\fBtar\fR \fB\-\-list\fR [\fB\-\-file\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIMEMBER\fR...] +\fBtar\fR \fB\-\-list\fR [\fB\-\-file\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] \ +[\fIMEMBER\fR...] .sp -\fBtar\fR \fB\-\-test\-label\fR [\fB\-\-file\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fILABEL\fR...] +\fBtar\fR \fB\-\-test\-label\fR [\fB\-\-file\fR \fIARCHIVE\fR] \ +[\fIOPTIONS\fR] [\fILABEL\fR...] .sp -\fBtar\fR \fB\-\-update\fR [\fB\-\-file\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIFILE\fR...] +\fBtar\fR \fB\-\-update\fR [\fB\-\-file\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] \ +[\fIFILE\fR...] .sp -\fBtar\fR {\fB\-\-extract\fR|\fB\-\-get\fR} [\fB\-\-file\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIMEMBER\fR...] +\fBtar\fR {\fB\-\-extract\fR|\fB\-\-get\fR} [\fB\-\-file\fR \fIARCHIVE\fR] \ +[\fIOPTIONS\fR] [\fIMEMBER\fR...] .SH NOTE This manpage is a short description of GNU \fBtar\fR. For a detailed discussion, including examples and usage recommendations, refer to the @@ -83,11 +90,10 @@ GNU .B tar is an archiving program designed to store multiple files in a single file (an \fBarchive\fR), and to manipulate such archives. The archive -can be either a regular file or a device (e.g. a tape drive, hence the name +can be either a regular file or a device (e.g., a tape drive), hence the name of the program, which stands for \fBt\fRape \fBar\fRchiver), which can be located either on the local or on a remote machine. -.PP - +. .SS Option styles Options to GNU \fBtar\fR can be given in three different styles. In @@ -122,20 +128,20 @@ argument must follow the option letter w whitespace, as in \fB\-g/tmp/snar.db\fR. .PP Any number of options not taking arguments can be -clustered together after a single dash, e.g. \fB\-vkp\fR. An option +clustered together after a single dash, e.g.\& \fB\-vkp\fR. An option that takes an argument (whether mandatory or optional) can appear at -the end of such a cluster, e.g. \fB\-vkpf a.tar\fR. +the end of such a cluster, e.g.\& \fB\-vkpf a.tar\fR. .PP The example command above written in the .B short-option style could look like: .PP .EX -tar -cvf etc.tar /etc +tar \-cvf etc.tar /etc .EE or .EX -tar -c -v -f etc.tar /etc +tar \-c \-v \-f etc.tar /etc .EE .PP In @@ -152,11 +158,11 @@ method. Here are several ways of writing the example command in this style: .PP .EX -tar --create --file etc.tar --verbose /etc +tar \-\-create \-\-file etc.tar \-\-verbose /etc .EE or (abbreviating some options): .EX -tar --cre --file=etc.tar --verb /etc +tar \-\-cre \-\-file=etc.tar \-\-verb /etc .EE .PP The options in all three styles can be intermixed, although doing so @@ -228,7 +234,6 @@ same name, corresponding to various vers Extract files from an archive. Arguments are optional. When given, they specify names of the archive members to be extracted. .TP -.TP \fB\-\-show\-defaults\fR Show built-in defaults for various \fBtar\fR options and exit. .TP @@ -254,7 +259,7 @@ dump and, consequently, must be dumped a exist when creating an archive, it will be created and all files will be added to the resulting archive (the \fBlevel 0\fR dump). To create incremental archives of non-zero level \fBN\fR, you need a copy of the -snapshot file created for level \fBN-1\fR, and use it as \fIFILE\fR. +snapshot file created for level \fBN\-1\fR, and use it as \fIFILE\fR. When listing or extracting, the actual content of \fIFILE\fR is not inspected, it is needed only due to syntactical requirements. It is @@ -281,7 +286,7 @@ the snapshot file before dumping, thereb Assume the archive is seekable. Normally \fBtar\fR determines automatically whether the archive can be seeked or not. This option is intended for use in cases when such recognition fails. It takes -effect only if the archive is open for reading (e.g. with +effect only if the archive is open for reading (e.g., with .B \-\-list or .B \-\-extract @@ -385,7 +390,8 @@ supplied via the following environment v .RS .TP .B TAR_FILETYPE -Type of the file. It is a single letter with the following meaning: +Type of the file. +It is a single letter with the following meaning: .sp .nf .ta 8n 20n @@ -415,10 +421,11 @@ Name of the file owner. Name of the file owner group. .TP .B TAR_ATIME -Time of last access. It is a decimal number, representing seconds -since the Epoch. If the archive provides times with nanosecond -precision, the nanoseconds are appended to the timestamp after a -decimal point. +Time of last access. +It is a decimal number, +representing seconds since the Epoch. +If the archive provides times with nanosecond precision, +the nanoseconds are appended to the timestamp after a decimal point. .TP .B TAR_MTIME Time of last modification. @@ -447,7 +454,7 @@ GNU \fBtar\fR version number. The name of the archive \fBtar\fR is processing. .TP .B TAR_BLOCKING_FACTOR -Current blocking factor, i.e. number of 512-byte blocks in a record. +Current blocking factor, i.e., number of 512-byte blocks in a record. .TP .B TAR_VOLUME Ordinal number of the volume \fBtar\fR is processing (set if @@ -597,7 +604,7 @@ Disable POSIX ACLs support. .B \-\-selinux Enable SELinux context support. .TP -.B \-\-no-selinux +.B \-\-no\-selinux Disable SELinux context support. .TP .B \-\-xattrs @@ -608,7 +615,7 @@ Disable extended attributes support. .TP .BI \-\-xattrs\-exclude= PATTERN Specify the exclude pattern for xattr keys. \fIPATTERN\fR is a globbing -pattern, e.g. \fB\-\-xattrs\-exclude='user.*'\fR to include only +pattern, e.g., \fB\-\-xattrs\-exclude='user.*'\fR to include only attributes from the user namespace. .TP .BI \-\-xattrs\-include= PATTERN @@ -631,7 +638,7 @@ name or IP address, and the part after i pathname, e.g.: .EX ---file=remotehost:/dev/sr0 +\-\-file=remotehost:/dev/sr0 .EE An optional username can be prefixed to the hostname, placing a \fB@\fR @@ -644,7 +651,7 @@ command. Nowadays it is common to use instead. You can do so by giving the following command line option: .EX ---rsh-command=/usr/bin/ssh +\-\-rsh-command=/usr/bin/ssh .EE The remote machine should have the @@ -657,7 +664,8 @@ option. \fB\-\-force\-local\fR Archive file is local even if it has a colon. .TP -\fB\-F\fR, \fB\-\-info\-script\fR=\fICOMMAND\fR, \fB\-\-new\-volume\-script\fR=\fICOMMAND\fR +\fB\-F\fR, \fB\-\-info\-script\fR=\fICOMMAND\fR, \ +\fB\-\-new\-volume\-script\fR=\fICOMMAND\fR Run \fICOMMAND\fR at the end of each tape (implies \fB\-M\fR). The command can include arguments. When started, it will inherit \fBtar\fR's environment plus the following variables: @@ -670,7 +678,7 @@ GNU \fBtar\fR version number. The name of the archive \fBtar\fR is processing. .TP .B TAR_BLOCKING_FACTOR -Current blocking factor, i.e. number of 512-byte blocks in a record. +Current blocking factor, i.e., number of 512-byte blocks in a record. .TP .B TAR_VOLUME Ordinal number of the volume \fBtar\fR is processing (set if @@ -747,8 +755,8 @@ reading archives created with the \fB\-A .TP \fB\-\-record\-size\fR=\fINUMBER\fR Set record size. \fINUMBER\fR is the number of bytes per record. It -must be multiple of \fB512\fR. It can can be suffixed with a \fBsize -suffix\fR, e.g. \fB\-\-record-size=10K\fR, for 10 Kilobytes. See the +must be multiple of \fB512\fR. It can be suffixed with a \fBsize +suffix\fR, e.g., \fB\-\-record\-size=10K\fR, for 10 kibibytes. See the subsection .BR "Size suffixes" , for a list of valid suffixes. @@ -777,7 +785,8 @@ Old V7 tar format. \fB\-\-old\-archive\fR, \fB\-\-portability\fR Same as \fB\-\-format=v7\fR. .TP -\fB\-\-pax\-option\fR=\fIkeyword\fR[[:]=\fIvalue\fR][,\fIkeyword\fR[[:]=\fIvalue\fR]]... +\fB\-\-pax\-option\fR=\fIkeyword\fR[[:]=\fIvalue\fR][,\ +\fIkeyword\fR[[:]=\fIvalue\fR]]... Control pax keywords when creating \fBPAX\fR archives (\fB\-H pax\fR). This option is equivalent to the \fB\-o\fR option of the .BR pax (1) @@ -854,9 +863,7 @@ Make numbered backups if numbered backup .TP .BR never ", " simple Always make simple backups -.RS -.RE - +.LP If \fICONTROL\fR is not given, the value is taken from the .B VERSION_CONTROL environment variable. If it is not set, \fBexisting\fR is assumed. @@ -864,7 +871,7 @@ environment variable. If it is not set, .TP \fB\-C\fR, \fB\-\-directory\fR=\fIDIR\fR Change to \fIDIR\fR before performing any operations. This option is -order-sensitive, i.e. it affects all options that follow. +order-sensitive, i.e., it affects all options that follow. .TP \fB\-\-exclude\fR=\fIPATTERN\fR Exclude files matching \fIPATTERN\fR, a @@ -981,7 +988,7 @@ unless overridden by environment variabl Get names to extract or create from \fIFILE\fR. Unless specified otherwise, the \fIFILE\fR must contain a list of -names separated by ASCII \fBLF\fR (i.e. one name per line). The +names separated by ASCII \fBLF\fR (i.e., one name per line). The names read are handled the same way as command line arguments. They undergo quote removal and word splitting, and any string that starts with a \fB\-\fR is handled as \fBtar\fR command line option. @@ -1004,7 +1011,7 @@ Treat each line obtained from a file lis starts with a dash. File lists are supplied with the \fB\-\-files\-from\fR (\fB\-T\fR) option. The default behavior is to handle names supplied in file lists as if they were typed in the -command line, i.e. any names starting with a dash are treated as +command line, i.e., any names starting with a dash are treated as \fBtar\fR options. The \fB\-\-verbatim\-files\-from\fR option disables this behavior. @@ -1138,49 +1145,49 @@ Enable all warning messages. This is th .B none Disable all warning messages. .TP -.B filename-with-nuls +.B filename\-with\-nuls "%s: file name read contains nul character" .TP -.B alone-zero-block +.B alone\-zero\-block "A lone zero block at %s" .HP -Keywords applicable for \fBtar --create\fR: +Keywords applicable for \fBtar \-\-create\fR: .TP .B cachedir "%s: contains a cache directory tag %s; %s" .TP -.B file-shrank +.B file\-shrank "%s: File shrank by %s bytes; padding with zeros" .TP .B xdev "%s: file is on a different filesystem; not dumped" .TP -.B file-ignored +.B file\-ignored "%s: Unknown file type; file ignored" .br "%s: socket ignored" .br "%s: door ignored" .TP -.B file-unchanged +.B file\-unchanged "%s: file is unchanged; not dumped" .TP -.B ignore-archive +.B ignore\-archive "%s: archive cannot contain itself; not dumped" .TP -.B file-removed +.B file\-removed "%s: File removed before we read it" .TP -.B file-changed +.B file\-changed "%s: file changed as we read it" .TP -.B failed-read +.B failed\-read Suppresses warnings about unreadable files or directories. This keyword applies only if used together with the .B \-\-ignore\-failed\-read option. .HP -Keywords applicable for \fBtar --extract\fR: +Keywords applicable for \fBtar \-\-extract\fR: .TP .B existing\-file "%s: skipping existing file" @@ -1190,29 +1197,29 @@ Keywords applicable for \fBtar --extract .br "%s: time stamp %s is %s s in the future" .TP -.B contiguous-cast +.B contiguous\-cast "Extracting contiguous files as regular files" .TP -.B symlink-cast +.B symlink\-cast "Attempting extraction of symbolic links as hard links" .TP -.B unknown-cast +.B unknown\-cast "%s: Unknown file type '%c', extracted as normal file" .TP -.B ignore-newer +.B ignore\-newer "Current %s is newer or same age" .TP -.B unknown-keyword +.B unknown\-keyword "Ignoring unknown extended header keyword '%s'" .TP -.B decompress-program +.B decompress\-program Controls verbose description of failures occurring when trying to run alternative decompressor programs. This warning is disabled by default (unless \fB\-\-verbose\fR is used). A common example of what you can get when using this warning is: .EX -$ tar --warning=decompress-program -x -f archive.Z +$ tar \-\-warning=decompress\-program \-x \-f archive.Z tar (child): cannot run compress: No such file or directory tar (child): trying gzip .EE @@ -1221,23 +1228,23 @@ This means that \fBtar\fR first tried to \fBarchive.Z\fR using \fBcompress\fR, and, when that failed, switched to \fBgzip\fR. .TP -.B record-size +.B record\-size "Record size = %lu blocks" .HP Keywords controlling incremental extraction: .TP -.B rename-directory +.B rename\-directory "%s: Directory has been renamed from %s" .br "%s: Directory has been renamed" .TP -.B new-directory +.B new\-directory "%s: Directory is new" .TP .B xdev "%s: directory is on a different device: not purging" .TP -.B bad-dumpdir +.B bad\-dumpdir "Malformed dumpdir: 'X' never used" .RE .TP @@ -1249,21 +1256,20 @@ Ask for confirmation for every action. When creating, same as \fB\-\-old\-archive\fR. When extracting, same as \fB\-\-no\-same\-owner\fR. .SS Size suffixes -.sp .nf .ta 8n 18n 42n .ul Suffix Units Byte Equivalent - b Blocks \fISIZE\fR x 512 - B Kilobytes \fISIZE\fR x 1024 - c Bytes \fISIZE\fR - G Gigabytes \fISIZE\fR x 1024^3 - K Kilobytes \fISIZE\fR x 1024 - k Kilobytes \fISIZE\fR x 1024 - M Megabytes \fISIZE\fR x 1024^2 - P Petabytes \fISIZE\fR x 1024^5 - T Terabytes \fISIZE\fR x 1024^4 - w Words \fISIZE\fR x 2 + b blocks \fISIZE\fR x 512 + B kibibytes \fISIZE\fR x 1024 + c bytes \fISIZE\fR + G gibibytes \fISIZE\fR x 1024^3 + K kibibytes \fISIZE\fR x 1024 + k kibibytes \fISIZE\fR x 1024 + M mebibytes \fISIZE\fR x 1024^2 + P pebibytes \fISIZE\fR x 1024^5 + T tebibytes \fISIZE\fR x 1024^4 + w words \fISIZE\fR x 2 .fi .PP .SH "RETURN VALUE" @@ -1275,9 +1281,11 @@ Successful termination. .TP .B 1 .I Some files differ. -If \fBtar\fR was invoked with the \fB\-\-compare\fR (\fB\-\-diff\fR, \fB\-d\fR) +If \fBtar\fR was invoked with the \fB\-\-compare\fR (\fB\-\-diff\fR, +\fB\-d\fR) command line option, this means that some files in the archive differ -from their disk counterparts. If \fBtar\fR was given one of the \fB\-\-create\fR, +from their disk counterparts. +If \fBtar\fR was given one of the \fB\-\-create\fR, \fB\-\-append\fR or \fB\-\-update\fR options, this exit code means that some files were changed while being archived and so the resulting archive does not contain the exact copy of the file set. @@ -1291,7 +1299,7 @@ If a subprocess that had been invoked by exited with a nonzero exit code, .B tar itself exits with that code as well. This can happen, for example, if -a compression option (e.g. \fB\-z\fR) was used and the external +a compression option (e.g.\& \fB\-z\fR) was used and the external compressor program failed. Another example is .B rmt failure during backup to a remote device.