tar - Manipulate the tar archive files to copy or back up a file
Format
- tar -cf[#sbvwlzOUXSG] tarfile [blocksize] [-V volpat] [file [-C pathname] ...]
- tar -rf[#sbvwlzOUXSG] tarfile [blocksize] [-V volpat] [file [-C pathname] ...]
- tar -tf[#sbvzEOUXSG] tarfile [blocksize] [-L type] [-V volpat] [file [-C pathname] ...]
- tar -xf[#sAbvwpmozOUXSG] tarfile [blocksize] [-V volpat] [file [-C pathname] ...]
Description
tar reads, writes, and lists archive files. An archive file is a single file that contains one or more files, directories, or both. Archive files can be UNIX files or MVS™ data sets. A file that is stored inside an archive is called a component file. Similarly, a directory that is stored inside an archive is called a component directory.
- MVS data sets cannot be specified for component files.
- tar supports the use of generation data groups (GDGs) and tape data sets.
Included with each component file and directory is recorded information such as owner and group name, permission bits, file attributes, and modification time. Therefore, you can use a single archive file to transfer file directories or to back up or restore groups of files and directories.
Archives that are created by tar are interchangeable with archives that are
created with the pax utility. Both utilities can read and create archives
in the default format of the other (USTAR for pax and TAR for
tar). To save extended USTAR attributes, the USTAR format
(-U) must be used with -X option. Also, the
OS390 format can be used by using the -S option. In general, the USTAR
format with -X option and OS390 format records the most information and is
recommended. Archives are generally named with suffixes such as .pax
or
.tar
(or pax.Z
and tar.Z
for compressed files),
but that naming convention is not required.
tar can read and write the GNU tar format archives. For the special entry types in GNU tar format, tar only supports the read and write long pathname or long linkname entries. Other special entry types in the GNU tar, such as archiving the sparse file, are not supported.
Table 1 lists the recommended options for the USTAR format.
Intent | Option |
---|---|
To save only standard attributes. | tar -U |
To save all attributes to be restored on z/OS® system. | tar -S |
To save all attributes to be restored on z/OS and non-z/OS systems. | tar -UX |
To save in GNU tar format. | tar -G |
To preserve information such as extended attributes, external links, ACLs, file tag information, and links whose targets exceed 100 characters, either the USTAR format (-U) and -X option or the OS390 format using the -S option must be used. See the -U option for selecting the USTAR format. The -O and -X options contain information about enabling and disabling USTAR support.
You cannot use tar unless you specify -f.
Options
- -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: 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.
- -A
- Restores ACL information when used with -x option.
- -b
- Sets the number of 512-byte blocks that are 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 compatibility with z/OS UNIX, 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 was 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. - -G
- Creates an archive in GNU tar format. For the special entry types in GNU tar format, tar only supports the ability to create the long pathname or long linkname entries. Other special entry types in the GNU tar, such as archiving the sparse file, are not supported. The ability to save the extended USTAR attributes is not supported.
- -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 it lists 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 as
follows:
- 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 that are associated with the file.
For more information about ACLs, see Using access control lists (ACLs) 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
- When the file is extracted from an archive, its modification stamp is not restored. The default behavior is to restore the time stamp from information contained in the archive.
- -o
- When files are written to archives, the owner and modes of directories in the archive are not recorded. 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.
The -O option can be used to turn off the tar command to extract or list the GNU tar format with long file or linkname.
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 that is 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
and7
, inclusive, to select the tape unit. The density selector s can bel
(low),m
(medium), orh
(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
and GNU tar format to store long pathname or long linkname
entries. .
This
option has no effect for non-USTAR formatted archives except
the GNU tar format. tar -X functions in the following manner:
- During archive writing, -X causes tar to preserve extended USTAR information. For the GNU tar format, -X enables tar to store long pathname or long linkname.
- During archive listing, -X causes tar to display extended USTAR information and long pathname or long linkname for the GNU tar format. This is the default; -O can be used to disable extended USTAR support and long pathame or long linkname for the GNU tar format.
- During archive reading, -X enables tar to restore
extended USTAR information and long pathame or long linkname
for the GNU tar format. This is the default; -O can be used to
disable extended USTAR support
and long pathame or long linkname for the GNU tar format.
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.
- -U
- When a new tape archive is created with the -C option,
forces tar to use the USTAR format. The
default format that is used when a new archive is created 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.
Output
- The following notation is used to represent hard, symbolic, and external links:
indicates that hlink is a hard link to origfile.hlink external link to origfile
indicates that slink is a symbolic link to origfile.slink symbolic link to origfile
indicates that elink is an external link to ORIG.FILE.elink external link to ORIG.FILE
- For symbolic and external links, pax output always shows a file size of 0.
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.
/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 support for access control lists (ACLs)
tar -O can be used to disable the creation of special headers. This prevents tar from storing ACL data and other nonstandard information such as file tag data and long link names. However, there is no option to disable storing of ACL data only.
> tar -tvf acldata.tar
-rwx------ 1 STIERT SHUT 294912 Nov 9 09:57 file1
-rwx------+ 1 STIERT SHUT 294912 Nov 9 09:57 file2
drwxr-xr-x+ 2 STIERT SHUT 8192 Mar 20 2000 dir1/
For more information about access control lists, see Using access control lists (ACLs) in z/OS UNIX System Services Planning.
Usage notes
- Use the paxcommand if you need to use multibyte patterns when searching for file names.
- The POSIX 1003.1 standard defines formats for pax and tar
archives that limit the length of the target of a link file to 100 characters or less. Note: In the case of a hard link, the target is the first occurrence of the hard link which is archived. Subsequent hard links refer to the first instance.pax and tar provide extended USTAR support and the OS390 format that allows these links to be preserved when creating an archive and restored when reading an archive.
- The POSIX 1003.1 standard defines formats for pax and tar archives that limit the size of a file that can be stored in a pax and tar archive to less than 8 gigabytes in size. If a file being archived is 8 gigabytes or greater, an error message is issued, and the file is skipped. The command continues, but will end with a nonzero exit status.
- On the z/OS system, superuser privileges or read access to the appropriate FACILITY classes are required to create character special files, to restore user and group names, and to set certain extended attributes.
- Path names in the tape archive are normally restricted to a maximum length of 100 bytes. However, in USTAR (-U) and OS390(-O) format, path names can be up to 255 bytes long.
- When transferring archives between z/OS systems
and other UNIX systems, note the following:
- File transfers (for example, using OPUT/OGET or ftp put/get) must be done using binary or image format. This is true, even for archives consisting only of text files.
- You might need to convert text files from EBCDIC to ASCII (or some other character set). You can use the iconv utility to convert files before or after archiving. When text files are being created or extracted, you can use the pax -o option to convert them.
- Automatic conversion on files with file tag information is disabled when reading files while archives are being created, and during writes while files are being extracted from archives. That is, the settings of system and environment variables that turn automatic conversion on and off do not affect the reading and writing of files by tar. pax supports file tag options that support conversion of files based on their file tag settings.
-
The POSIX 1003.1 standard defines formats for tar and USTAR archives that limit the modification time to a maximum value of 77777777777 (octal). Modification times that are larger than the maximum value are not properly saved. Modification times beyond 03:14:07 UTC on January 19, 2038 but less than or equal to the maximum value, are not properly saved or restored on z/OS V2R2 and earlier systems. They also might not be properly saved or restored on non-z/OS systems. However, on systems later than z/OS V2R2, such values are properly saved and restored. Due to these restrictions, the pax utility with the pax interchange format is the preferred method for processing time values beyond 03:14:07 UTC on January 19, 2038.
Note: The OS390 format has the same maximum value as the USTAR format.
Examples
- The following command takes a directory and places it in an archive in compressed format:
tar -cvzf archive directory
- To identify all files that were changed in the last week (7 days), and to archive them to the
/tmp/posix/testpgm file, enter:
find /tmp/posix/testpgm -type f -mtime -7 | tar -cvf testpgm.tar -
-type -f tells find to select only files. This avoids duplicate input to tar.
- In the following examples, archive
acidata.tar
contains file1, file2, and dir1. file1 has no ACL data, file2 has an access ACL, and dir1 contains a file default, a directory default, and an access ACL. If you only specify option -f, your output will be:
If you also specify -L A, ACL information will be displayed:> tar -f acldata.tar file1 file2 dir1
Finally, if you add the verbose option, -v, you will see the chmod settings associated with the file:> tar -L A -f acldata.tar file1 file2 user:WELLIE2:rw- group:SYS1:rwx
> tar -L A -vf acldata.tar -rwx------ 1 STIERT SHUT 294912 Nov 9 09:57 file1 -rwx------+ 1 STIERT SHUT 294912 Nov 9 09:57 file2 user:WELLIE2:rw- group:SYS1:rwx drwxr-xr-x+ 2 STIERT SHUT 8192 Mar 20 2000 dir1/ user:RRAND:rwx user:WELLIE2:rw- group:SHUT:rwx fdefault:user:RRAND:rwx fdefault:group:SHUT:r-x default:user:ANGIEH:rwx default:group:SYS1:r--
Localization
- LANG
- LC_ALL
- LC_MESSAGES
- NLSPATH
Exit values
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.
Portability
4.2BSD
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. The -O, -X, and -S options are also extensions of POSIX standard.
Related information
cpio, pax
Also, see the pax file format description in File formats for more information.