tar — Manipulate the tar archive files to copy or back up a file
Format
- tar –cf[#sbvwlzOUXS] tarfile [blocksize] [–V volpat] [file [–C pathname] ...]
- tar –rf[#sbvwlzOUXS] tarfile [blocksize] [–V volpat] [file [–C pathname] ...]
- tar –tf[#sbvzEOUXS] tarfile [blocksize] [–L type] [–V volpat] [file [–C pathname] ...]
- tar –xf[#sAbvwpmozOUXS] tarfile [blocksize] [–V volpat] [file [–C pathname] ...]
Description
tar reads, writes, and lists archive files. An archive file is a single file containing one or more files, directories, or both. Archive files can be UNIX files or MVS™ data sets. A file stored inside an archive is called a component file; similarly, a directory stored inside an archive is called a component directory.
- MVS data sets cannot be specified for component files.
- tar does not support the use of generation data groups (GDGs).
Included with each component file and directory is recorded information such as owner and group name, permission bits, file attributes, and modification time. You can therefore use a single archive file to transfer a directory structure from one machine to another, or to back up or restore groups of files and directories.
Archives created by tar are interchangeable with those 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 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 this is not required.
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 |
In order 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 and z/OS-extended USTAR support 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: 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.
- -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.
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 z/OS UNIX System Services Planning.
Usage notes
- Use the pax command 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.Beginning with OS/390® Release 6, 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. See z/OS-extended USTAR support for more information.
- 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 during creation of an archive
- During writes while extracting files from an archive
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 have been 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
See Localization for more information.
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.