tar — Manipulate the tar archive files to copy or back up a file

The four forms of the command shown in the syntax represent the main functions of tar as follows:

–c

Creates an archive. Each named file is written into a newly created archive. Directories recursively include all components. Under the USTAR (–U) option, tar records directories and other special files in the tape archive; otherwise, it ignores such files. 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.

Tip: In order to preserve information about extended attributes and external links, the USTAR format (-U) must be used. Additionally, to preserve ACLs, file tag information, and link names greater than 100 characters, the USTAR format (-U) and -X option must be used. The OS390 archive format can also be used with the -S option to store all the file attributes.

–r

Writes the named files to the end of the archive. It is possible to have more than one copy of a file in a tape archive using this method. To use this form of the command with a tape, it must be possible to backspace the tape. Do not specify OS390 format to be appended to non-OS390 format archive or specify non-OS390 format to be appended to OS390 format archive.

Restriction: You cannot specify both the –r and the –z option at the same time.

–t

Displays a table of contents. This option displays 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. The verbose (-v) option can be used to show the attributes of each component. For USTAR or OS390 format archives, the -L E option can be used to show the attributes and extended attributes of each component.

–x

Extracts files from an archive. tar extracts each named file to a file of the same name. If you did not specify any files on the command line, all files in the archive are extracted. This extraction restores all file system attributes as controlled by other options.

You must specify one of the preceding basic options as the first character of an option string. You can add other characters to the option string. You can omit the leading dash on the first option string, but all subsequent options must be preceded with a dash. Other possible options in the option string are:

-A

Restores ACL information when used with –x option.

-b

Sets the number of 512-byte blocks used for tape archive read/write operations to blocksize. The blocksize argument must be specified, and blocksize can be specified only when b is in the option string. When reading from the tape archive, tar automatically determines the blocking factor by trying to read the largest permitted blocking factor and using the actual number read to be the blocksize.

For UNIX compatibility, the largest valid block size is 20 blocks; in USTAR mode, it is 63 blocks.

–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, it changes the working directory (for tar only) to pathname and treats all following entries in your file list (including another –C) as being relative to pathname.

–E

Although still supported for compatibility with previous versions of tar, this option has been replaced by –L E.

-f

You must specify -f. The -f option uses the file tarfile for the tape archive rather than using the default. The tarfile argument must be specified, and tarfile can be specified only when -f is in the option string. The tarfile argument must precede the blocksize argument if both are present. If tarfile is the character –, then the archive format defaults to USTAR, standard input is used for reading archives, and the standard output is used for writing archives.

-l

Writes an error message if all links are not resolved when files are added to the tape archive.

–L type

–L displays additional information when listing the contents of an archive. Only one type can be specified per –L option. However, –L can be specified multiple times. The types that can be displayed are:

A

Displays extended ACL (access control list) data.

Specifying tar –L A does not automatically turn on the verbose table of contents format. You must also specify –v to display the chmod settings associated with the file.

For more information about ACLs, see the section on controlling access control lists in z/OS UNIX System Services Planning and tar support for access control lists (ACLs).

E

Same as verbose (–v) output, but additionally displays extended attributes. See Output for more information. –L E is equivalent to the tar –E

T

Displays file tag information. Does not automatically turn on the verbose –v option but can be used with –v or any other combination of table of contents display options. See Output for more information.

-m

Does not restore a file's modification time stamp when extracting it from an archive. The default behavior is to restore the time stamp from information contained in the archive.

-o

When writing files to an archive, does not record owner and modes of directories in the archive. If this is specified when extracting from an existing ar archive, tar does not restore any owner and group information in the archive. The default is to record this information when creating a tar archive, and to restore it when extracting from the archive.

–O

For USTAR formatted archive, this option turns off the extended USTAR support. -O is the default and user needs to use -X option to turn on extended USTAR support for USTAR archive.

For more information, see z/OS-extended USTAR support.

-p

When extracting, restores the three high-order file permission bits, exactly as in the archive. They indicate the set-user-ID, set-group-ID, and sticky bit. For USTAR formatted archives, p also restores, if present, extended attributes and -A restores ACLs.

Tip: If -O is specified, it overrides -p for extended attributes. They will not be restored. tar restores the modes exactly as stored in the archive and ignores the UMASK. To use -p on UNIX systems, you must have appropriate privileges; tar restores the modes exactly as in the archive and ignores the UMASK.

-#s

-#s is not supported by z/OS UNIX. The default archive file name used by tar is /dev/mt/0m. This option is the least general way to override this default. For a more general method, see the -f option. The file name generated by this option has the form /dev/mt/#s. The # can be any digit between 0 and 7, inclusive, to select the tape unit. The density selector s can be l (low), m (medium), or h (high).

-S

Forces tar to use the OS390 format, which provides support to save all files attributes by default.

–X

For USTAR formatted archives, –X enables extended USTAR support. This option has no affect for non-USTAR formatted archives. tar –X functions in the following manner:

• During archive writing, -X causes tar to preserve extended USTAR information.
• During archive listing, -X causes tar to display extended USTAR information. This is the default; -O can be used to disable extended USTAR support.
• During archive reading, -X enables tar to restore extended USTAR information. This is the default; -O can be used to disable extended USTAR support.

  The environment variable _OS390_USTAR=Y, also turns on the extended USTAR information

To restore certain information, the user must also have the appropriate privileges and have specified the corresponding options. For example, you must specify –p to restore extended attributes and to restore ACLs.

For more information about extended attributes, see z/OS-extended USTAR support.

-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 can deduce whether the tape archive is in USTAR format by reading it, so you can use U to suppress a warning about USTAR format.

In order to save external links, extended attributes, and file tag information, and ACLs, the extended USTAR format must be used. To turn on the extended USTAR format, the -U and -X options must be specified. The OS390 format can also be used (-S option) to save all the file attributes by default.

-v

Displays each file name, along with the appropriate action key letter as it processes the archive. With the –t form of the command, this option gives more detail about each archive member being listed and shows information about the members in the same format used by the ls –l command. You can also use the –L type option which provides the ability to display additional information such as extended attributes and file tag information. See Output for more information.

–V volpat

Provides automatic multivolume support. tar writes output to files—the names of which are formatted with volpat. Any occurrence of # in volpat is replaced by the current volume number. When you invoke tar with this option, it prompts for the first number in the archive set, and waits for you to type the number and a carriage return before proceeding with the operation. tar issues the same sort of message when a write error or read error occurs on the archive; this kind of error means that tar has reached the end of the volume and should go on to a new one.

-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 you want the operation to take place. Typing in an answer that begins with “y” tells tar to do the operation; anything else tells tar to go on to the next operation.

-z

Reads or writes, or both reads and writes, the tape archive by first passing through a compression algorithm compatible with that of compress.

Restriction: You cannot specify both the –r option and the –z option at the same time.

When the –v or –L E ( or –E) option is used with –t (table of contents), tar produces a verbose table of contents for the archive. The –L T option can also be used to additionally, or without the verbose output, display file tag information. The output for –v is similar to the output from the ls –l command with following exceptions:

• The following notation is used to represent hard, symbolic, and external links:

  hlink external link to origfile

  indicates that hlink is a hard link to origfile.

  slink symbolic link to origfile

  indicates that slink is a symbolic link to origfile.

  elink external link to ORIG.FILE

  indicates that elink is an external link to ORIG.FILE.
• For symbolic and external links, pax output always shows a file size of 0.

Refer to the description of ls for an explanation of the ls –v.

The output from the –L E ( or –E) option has the same format as –v and additionally displays a column showing the extended attributes:

a

Program runs APF-authorized if linked AC=1

p

Program is considered program-controlled

s

Program runs in a shared address space

l

Program is loaded from the shared library region

Note: l is a lowercase L, not an uppercase i.

–

Attribute not set

The format of the tar –L E ( or –E) output is variable in length and will be extended as necessary to display additional file characteristics that are not supported by tar –v (ls –l).

The format of the tar –L T output is similar to the output from chtag –p. If specified with –v or –L E, the output will be displayed on the same line of and before the –v output. When used without –v, only the file tag information and file names are displayed. For example:

/tmp> tar -L T -tf asciitagged.tar
m ISO8859-1   T=off text_am
t ISO8859-1   T=on  text_at
- untagged    T=off text_au

This option can be used with either –v or –o E (or both) to display additional verbose output. For example:

/tmp> tar -L T -tvf asciitagged.tar
m ISO8859-1  T=off -rw-r--r--  1 SteveS  Kings   9 Apr 30 22:31 text_am
t ISO8859-1  T=on  -rw r--r--  1 SteveS  Kings   9 Apr 30 22:31 text_at
- untagged   T=off -rw-r--r--  1 SteveS  Kings   9 Apr 30 22:06 text_au

tar uses the following localization environment variables:

• LANG
• LC_ALL
• LC_MESSAGES
• NLSPATH

0

Successful completion

1

Failure due to any of the following:

• Incorrect option
• Incorrect command-line arguments
• Out of memory
• Compression error
• Failure on extraction
• Failure on creation