tar

USTAR-compatible tape archiver to copy and back up files 

Command


SYNOPSIS

tar -c[#sbEfNIjSvwlzU] [blocking_factor] [archivefile] [-V volpat] [-F filename] [-X filename] [file...] [-C pathname] [file...]

tar -r[#sbfNIjSvwlU] [blocking_factor] [archivefile] [-V volpat] [-F filename] [-X filename] [file...] [-C pathname] [file...]

tar -t[#sbfNIjSvzU] [blocking_factor] [archivefile] [-V volpat] [-F filename] [-X filename] [file ...]

tar -x[#sbfNIjSvwpmozU] [blocking_factor] [archivefile] [-V volpat] [-F filename] [-X filename] [file ...]


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 -w option is given, tar prompts you as to whether you want to extract the file as a non-sparse file or skip it. Sparse archive files are never created because most tapes, floppy disks, and other archiving media cannot understand them. It is recommended that you compress any archive which contain files with the sparse attribute set to keep the size of the archive reasonable.

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.

Note:

Some versions of the tar utility on other systems may not automatically detect and decompress bzip2-compressed archives. To extract files from these archives on such a system, you should first decompress the archive using the bunzip2 utility.

-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:

*.obj
*.c~
*/.cvsignore
can be used to exclude files that you do not wish to be considered. The format of the file is one pattern per line.

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 -N option, tar can handle saving and restoring additional 8.1/2012R2/10/2016/2019/11/2022 attributes. This option has no effect when the TK_NTSECURITYINFO_OFF environment variable is set.

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 -cN to create a new archive, for each file being added to the archive, tar also adds the corresponding special file. The special file has the same modification timestamp as the regular file and contains the chacl commands to restore the regular file's discretionary access control list (DACL), chown commands to set the owner and group information, and a chmod command to set the compressed attribute if the regular file has that attribute set.

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 -xN to extract files from an enhanced archive. For each regular file retrieved from the archive, the corresponding special file is also retrieved from the archive; the commands in this special file are then applied to the regular file and the special file is deleted (from the disk, but not from the archive).

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 -xN, the -p option (retain system, archive, and hidden attributes) is ignored, since all attributes including read-only and compression are retained when when the archive is created using -N. You can use the -o option (do not set owner) with -xN, but doing so may affect the permission of users to access retrieved files.

When you use -x without -N on an enhanced archive, tar extracts all files (both regular and special). Users with versions of MKS Toolkit that do not contain the -N feature of tar but do contain the chacl command can still make use of the special files in an enhanced archive. Such users can extract all the files in the archive with -x, and then use the find command to first execute the special files to restore the DACLs for the regular files and then delete those special files.

For information on how DACLs are restored, see Restoring DACLs.

Using -tN to display the table of contents of an enhanced archive displays only the regular files in the archive, unless you also specify -v. tar -tvN displays both regular and special files as does tar -t.

You can use -rN to append regular and special files to an existing archive. If the existing archive is not an enhanced archive (that is, not created with tar -cN), the resulting archive is a hybrid, where only some files in the archive have 8.1/2012R2/10/2016/2019/11/2022 attributes associated with them. Similarly, by using tar -r, you can append regular files without a corresponding special file to an existing enhanced archive.

Enhanced or hybrid archives to which files have been appended may include multiple copies of regular or special files. The behavior of tar -xN is undefined in this context; files may be inconsistent in the same way that is possible when multiple copies are included without the -N option. Appending files to an existing archive is not recommended when the append operation could result in multiple copies of a file in an archive.

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 -cN, the discretionary access control lists (DACLs) associated with file are preserved and these DACLs are restored when the files and directories are restored.

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 -cN in directory dir1, saving dir2 and file3. ACE2 is saved with dir2 and ACE3 with file3. Now restore this tar archive to dir4.

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.

TK_UNIX_FILESYSTEM

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:

0 

Successful completion.

1 

Failure due to any of the following:

— invalid option
— invalid command line arguments
— out of memory
— compression error
— failure on extraction
— failure on creation


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 -N option and the related handling of additional 8.1/2012R2/10/2016/2019/11/2022 attributes are MKS extensions. However, the resulting tar archives are in standard format and can be read by standard implementations of tar.

The -U option is an extension to provide POSIX USTAR format compatibility.

The -p option is a common extension on BSD UNIX systems that is not available on UNIX System V systems.

These two options as well as the -C, -V, and -z options are extensions to the x/OPEN standard. The -u option specified in XPG is not currently supported.

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

Commands:
chacl, chmod, chown, cpio, dd, mkszip, mt, pax, uncompress, vpax

File Formats:
cpio, pax, tape, tar

Miscellaneous:
stat

MKS Toolkit Backup and Tape Handling Solutions Guide


PTC MKS Toolkit 10.4 Documentation Build 39.