SYNOPSIS
tar
tar
tar
tar
DESCRIPTION
tar manipulates archives. An archive is a single file that contains the complete contents of a set of other files; an archive preserves the directory hierarchy that contained the original files, in a manner similar to cpio. The name tar was derived from Tape ARchiver; however, you can use archives with any medium, including diskettes.
This version of the tar utility writes and reads the original tar format from UNIX systems as well as the USTAR format defined by the POSIX (IEEE P1003.1) standards group. It can also save and restore additional 8.1/2012R2/10/2016/2019/11/2022 attributes.
When tar adds a sparse file to an archive, it stores it
as a non-sparse file but also stores the sparse attribute. When a file with
a sparse attribute is extracted on a NTFS file system (which supports
sparse files), the file is extracted as a sparse file. On other file systems,
a warning is given and it is extracted as a non-sparse file. However, if the
Primary Options
The four forms of the command shown in the synopsis represent the main functions of tar . You must specify one of these primary options as the first character of an option string.
-c -
creates an archive. This command writes each named file into a newly-created archive. Directories recursively include all components. If
- appears in place of any file name, tar reads the standard input for a list of files, one per line. This allows other commands to generate lists of files for tar to archive. -r -
writes the named files to the end of the archive. It is possible to have more than one copy of a file in an archive using this method. To use this form of the command with a tape, it must be possible to backspace the tape.
-t -
displays a table of contents. This display contains the names of all the files in the archive, one per line. If you specify one or more files on the command line, tar prints only those file names. Under the verbose (
-v ) option, more information about each archive member is printed, in a format similar to that produced by ls-l .- Note:
-
When you specify a compression option (
-I ,-j , or-z ) with the-t option and the specified archive is not compressed, an error message results and no table of contents is displayed.
-x -
extracts files from an archive. tar extracts each named file to a file of the same name. If you do not specify any files on the command line, tar extracts all files in the archive. This extraction restores all file system attributes as controlled by other options.
- Note:
-
When you specify a compression option (
-I ,-j , or-z ) with the-x option and the specified archive is not compressed, an error message results and no files are extracted.
Secondary Options
-b -
sets the number of blocks used for tape archive read/write operations to blocking_factor. If you specify
-b , you must specify a blocking_factor argument. When reading from the tape archive, tar automatically determines the blocking factor by trying to read the largest legal blocking factor and using the actual number read to be the blocking_factor. For UNIX compatibility, the largest valid value for blocking_factor is 20 blocks; in USTAR mode, it is 60 blocks. Blocks are typically 512 bytes, although some tape drives support other sizes.- Note:
-
The
-b ,-C ,-f , and-V options pull their associated option arguments in order from all non-options arguments on the command line. For example, if-b comes before-f in the options string, the blocking_factor must come before the filename.
-C pathname-
is an unusual option because it is specified in the middle of your file list. When tar encounters a
-C pathname option while archiving files, tar treats pathname as the current directory and treats all following entries in your file list (including another-C ) as being relative to pathname.- Note:
-
The
-b ,-C ,-f , and-V options pull their associated option arguments in order from all non-options arguments on the command line. For example, if-b comes before-f in the options string, the blocking_factor must come before the filename.
-E -
when used with the
-c option, this option forces tar to use the POSIX pax format described on the pax reference page. -F filename-
Specifies a disk file which contains the list of files to be considered. This is used instead of specifying a list of input files on the command line. Thus the following two commands are equivalent:
$ tar cf foo.tar `cat files.txt` $ tar cf foo.tar -F files.txt
The format of the file is one filename per line. If you have filenames that you wish to specify which have special characters or whitespace in the name, using the
-C may be easier than quoting and escaping the filenames so they can be specified on the command line. -f -
uses the archivefile for the tape archive rather than the default device. If
-f is used, the archivefile argument must be specified. If archivefile is the character -, tar uses the standard input for reading and the standard output for writing archives.- Note:
-
The
-b ,-C ,-f , and-V options pull their associated option arguments in order from all non-options arguments on the command line. For example, if-b comes before-f in the options string, the blocking_factor must come before the filename.
- #s
-
sets the default archive file name to a specific tape unit number and density. On Windows systems, the default archive file name used by tar is /dev/mt. This option is the least general way to override this default. For a more general method, use the
-f option. The file name generated by the #s option has the form /dev/mt#s on Windows systems. The # may be any digit between 0 and 7, inclusive, to select the tape unit. The density selector s may be l(low), m(medium), or h(high). On Windows systems, the density is ignored and the drive's default density is used. For finer control over the density, use the-f or-V option with an archive name such as -f /dev/nmtdqic-150; see tape for information on SCSI tape device names. -I -j -
uses the bzip2 format to compress the tar archive being created. When you extract from a an archived compressed using this format, tar automatically detects the bzip2 format and decompresses it appropriately.
-l -
complains if all links are not resolved when adding files to the tape archive.
-m -
does not restore a file's modification time stamp when extracting it from an archive. By default, tar restores the time stamp from information contained in the archive.
-N -
handles additional 8.1/2012R2/10/2016/2019/11/2022 attributes for each file in the archive. For each file in the archive, these additional attributes are stored in a file .filename_MKS_ACL.ksh (note the leading dot). This option has no effect when the TK_NTSECURITYINFO_OFF environment variable is set, because this environment variable disables the use of access control lists.
For full details on the behavior of
-N and the handling of the additional attributes, see Handling Additional Attributes. -o -
when extracting files, does not attempt to assign owner and group information to extracted files. With this option, most operating systems assign your owner and group information to extracted files by default.
-p -
when extracting, preserves the three high-order file attribute bits, exactly as in the archive. Windows systems use these bits to indicate system, archive, and hidden attributes; see the stat reference page for more details. On UNIX and POSIX-compliant systems, they indicate the set-user-ID, set-group-ID, and saved-text attributes; to use
-p on these systems, you must have appropriate privileges. When-p is set, tar ignores the UMASK and restores the modes exactly as in the archive.- Note:
-
When this option is not specified, every file extracted on Windows systems has the archive attribute turned on.
-S -
uses signed checksums in file headers when creating archives and interprets the checksums in file headers when extracting archives as being signed checksums. This allows compatibility with some UNIX systems with tar utilities that use such checksums rather than the POSIX standard of unsigned checksums.
- Note:
-
Signed and unsigned checksums only differ when the checksum is higher than the signed maximum (in which case, the signed checksum becomes negative) or when the file header contains negative numbers. Archives which do not contain file headers with negative numbers, and whose checksums are low enough that the signed and unsigned checksums do not differ, can be read by all versions of tar. However, archives that were created using signed checksums and have negative checksums (that is, it is larger than the signed maximum), or contain file headers with negative numbers, cannot be read by versions of tar that cannot recognize signed checksums. Similarly, when the -S option is specified, the MKS Toolkit version of tar cannot read archives created using unsigned checksums if a checksum is larger than the signed maximum or a file header contains negative numbers.
-U -
when creating a new tape archive with the
-c option, forces tar to use the USTAR format. The default format used when creating a new archive is the original UNIX tar format. When you do not specify-c , tar determines whether or not the tape archive is in USTAR format by reading it, so the U option does not affect file extraction. tar displays an error message for a UNIX tar format file containing a bad file name;-U suppresses this message and still extracts the data if the file name is acceptable in USTAR format. -v -
displays each file name, along with the appropriate action key letter (a for add, x for extract) as it processes the archive. With the
-t form of the command, this option gives more detail about each archive member being listed. -V volpat-
provides automatic multi-volume support. tar writes output to files -- whose names are formatted using volpat. Any occurrence of # in volpat is replaced by the current volume number. When you invoke tar with this option, it asks you to insert the appropriate disk and then hit return before it proceeds with the operation. With this option set, tar issues the same sort of message when a write error or read error occurs on the archive. The reasoning is that this kind of error means that tar has reached the end of the volume and should go on to a new one.
- Note:
-
The
-b ,-C ,-f , and-V options pull their associated option arguments in order from all non-options arguments on the command line. For example, if-b comes before-f in the options string, the blocking_factor must come before the filename.
-w -
is used to confirm each operation, such as replacing or extracting. tar displays the operation and the file involved. You can then confirm whether or not you want the operation to take place. Typing in an affirmative answer (in the POSIX locale, one that begins with y or Y) tells tar to do the operation; anything else tells tar to go on to the next operation.
-X filename-
Specifies a disk file which contains a list of filename patterns to be excluded. Wildcards can be used, so patterns such as:
can be used to exclude files that you do not wish to be considered. The format of the file is one pattern per line.*.obj *.c~ */.cvsignore
- Note:
-
Pattern excludes through this option take precedence over any files that might be explicitly listed either on the command line or through
-F .
-z -
performs compression. Output is at compression level 5. On input, any compression level up to 9 is acceptable. In addition,
-z expands compressed archives on input.tar uses the gzip format to compress files.
Handling Additional Attributes
With the
The additional information for each file in the archive is stored in a file named .filename_MKS_ACL.ksh where filename is the name of the original file. This file (called a special file) is used to restore the additional attributes when the original file (called a regular file) is extracted. Archives containing special files are called enhanced archives.
When using
- Note:
-
Special files are created as temporary files and then added to the archive with the appropriate name. As a result, if a special file already exists when tar
-cN (or-rN ) is specified, that special file is ignored.
You can use
- Note:
-
To properly restore the ownership and group information for files being extracted from an enhanced archive, you must have the appropriate permissions as outlined in the chown reference page.
When using
When you use
For information on how DACLs are restored, see Restoring DACLs.
Using
You can use
Enhanced or hybrid archives to which files have been appended may include
multiple copies of regular or special files. The behavior of
tar
- Note:
-
If tar is interrupted while restoring an enhanced archive using
-N , special files (that is, files of the form .filename_MKS_ACL.ksh may be left behind. You can delete these files with no consequence.
Restoring DACLs
When enhanced archives are created using tar
However, the access controls may still be different on restoration than for the original file, if files are retrieved to a location with different inheritable access control entries (ACEs) than the original location. ACEs can either be assigned explicitly to a given file or can be inherited from a higher directory. Access to a file depends both on the ACEs associated directly with that file, and on the ACEs inherited from above.
Consider the following hierarchy, with ACEs assigned to files and directories. No two ACEs in this example apply to the same user.
dir1 (ACE1) dir4 (ACE4) | dir2 (ACE2) | file3 (ACE3)
Let ACE1 and ACE2 be inherited. Now run tar
To guarantee that all users have exactly the same access to restored files, no matter where they were restored in a directory tree, would require that all inheritance in the destination tree be overridden and that all inheritances in the source directory tree be expanded. In this example, it would require that ACE1 be assigned to dir2, and that ACE4 be ignored.
But this does not preserve the inheritance structure cleanly; restored files do not have the same ACEs that the original files did. Even if these files were restored to their original location under dir1, dir2 would have different ACEs, since ACE1 would have been assigned to dir2, and ignored the version of ACE1 associated with dir1. While users would have the same access as in the original case, the inheritance structure would be changed; in particular, dropping ACE1 from dir1 would have no effect in the restored setting, while it obviously would have in the original setting (and this gets far sloppier in a real example, where dir1 may contain many files, all of which would need to be assigned ACE1).
Instead, tar simply saves ACE2 with dir2 and ACE3 with file3. If the files are restored to dir1 (or any directory with inheritable ACE1), access rules are identical for saved and restored files. However, if dir2 and file3 are instead restored to dir4, with inheritable ACE4, the access rules are different.
This is right, though, in that the attributes have been retained for the files that tar saved and restored. Consider an analogy, where files are saved from a read-only file system (for example, a write-protected floppy disk), and restored to a read-write file system, such as the main hard drive. Here it seems clear that each file should be restored with its original permissions (which may well allow writing) instead of with read-only permission, based on an attribute that was set higher in the directory structure. Similarly, let the permissions on dir2 and file3 be wide open. If a user did not have read access to dir1 but did to dir4, restoring the archive to dir4 would give this user access to these files.
EXAMPLES
The compression option provides a more efficient way of expressing:
tar -cvf - directory | mkszip >archive
as the one command line:
tar -cvzf archive directory
To identify all files that have been changed in the last week (7 days), and to archive them to a file on diskette, you might type:
find directory -mtime -7 | tar -cvf a:archive -
ENVIRONMENT VARIABLES
- TK_ARCHIVE_CHARSET
-
Contains the format to be used by cpio, tar, pax, vpax, zip, or unzip when reading and writing file names to an archive. The value must be one of ASCII_ANSI, ASCII_OEM, or UTF-8 (or their equivalents) as described in the File Character Formats section of the unicode reference page.
When this variable is unset or it is set to a value other than those listed earlier, the default OEM character set is used.
- TK_ASPI_SUPPORT_OFF
-
If set, MKS Toolkit utilities do not use ASPI support if it is present and do not display warning messages if it is not.
- TK_CLEAR_ARCHIVE_BIT
-
When set, all files that are written to archives are stored in the archive with the archive bit cleared.
- TK_NTLINKS_OFF
-
MKS Toolkit supports hard links under 8.1/2012R2/10/2016/2019/11/2022 on NTFS file systems. There is a slight loss of performance for this support. If you do not require hard link support, you should set and export the environment variable TK_NTLINKS_OFF to disable this support.
- TK_NTSECURITYINFO_OFF
-
MKS Toolkit supports 8.1/2012R2/10/2016/2019/11/2022 security information on NTFS file systems. There is a slight loss of performance for this support. If you do not require any security information, you should set and export the environment variable TK_NTSECURITYINFO_OFF to disable this feature.
When this variable is set, the Enhanced UNIX Compatibility Mode is on and the virtual file system is in use.
When the Enhanced UNIX Compatibility Mode is on, tar stores all path names in an archive as virtual file system path names. This ensures that when such files are extracted on a system that uses a single-rooted file system similar to virtual file system (such as UNIX or Linux), they are put in the correct location. If you don't want virtual file system path names stored in the archives you create, turn off the Enhanced UNIX Compatibility Mode by unsetting the TK_UNIX_FILESYSTEM environment variable. As long as this environment variable is either set when performing both backup and restore operations, or unset when performing both, using tar to backup and restore should work as expected.
For details on the Enhanced UNIX Compatibility Mode and the virtual file system, see the EUCM reference page.
DIAGNOSTICS
Possible exit status values:
PORTABILITY
x/OPEN Portability Guide 4.0. 4.2 BSD UNIX. Windows 8.1. Windows Server 2012 R2. Windows 10. Windows Server 2016. Windows Server 2019. Windows 11. Windows Server 2022.
On 8.1/2012R2/10/2016/2019/11/2022, tar recognizes device names only if you apply the prefix //./ to every device reference, as follows:
//./TAPE0 instead of TAPE0
We strongly recommend, however, that you specify tape devices as described under tape in the PTC MKS Toolkit Reference Manual. For example
/dev/mt0
has the same effect as specifying //./TAPE0, with the added advantage that tar automatically senses and sets the correct block size of the tape.
The
The
The
These two options as well as the
Some features of the UNIX file system, such as links, have no analogs in the Windows file system. The default archive file /dev/mt is not very useful unless a tape drive is installed.
LIMITS
There is no practical limitation on the size of a tar archive; however, individual files in an archive must be less than 8 GB in size.
Path names in the tape archive are normally restricted to a maximum length of 100 bytes. However, in USTAR mode, path names may be up to 255 bytes long.
A description of the tape archive format is found in the tar file format reference page.
WARNING
Before performing a raw disk input/output operation on a given disk, you must first read a properly formatted disk of the same size in the same drive. For example, if you want to use a 1.44MB disk in drive A: for raw disk input, you first perform a command like ls or dir on a different, properly formatted 1.44 MB disk in that drive. Once this is done, place the disk that you want to use for raw disk input/output in the appropriate drive and issue the PTC MKS Toolkit command that you want to use.
NOTES
The tar utility cannot save files larger than eight gigabytes in size in an archive. However, other programs that extract files from tar archives may be unable to properly extract files larger than two gigabytes and tar issues a warning to that effect when you attempt to save such a file.
The file permission modes of UNIX systems are not the same as those of Windows systems. In particular, the archive, hidden, and system attributes of such a file mean something else on UNIX systems. See the stat reference page for more details.
AVAILABILITY
PTC MKS Toolkit for System Administrators
PTC MKS Toolkit for Developers
PTC MKS Toolkit for Interoperability
PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition
SEE ALSO
- Miscellaneous:
- stat
MKS Toolkit Backup and Tape Handling Solutions Guide
PTC MKS Toolkit 10.4 Documentation Build 39.