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.
Restrictions: Note
the following restrictions:
- 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. Recommended options for the USTAR formatIntent |
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 |
Tip: 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
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:
Tip: 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
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 support for access control lists (ACLs)
For Archive
Writing or Creating:
ACL data is stored in USTAR formatted
archives, when -X option is used. The OS390
format (-S option) also stores the ACL information.
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.
For Archive Reading or Restoring:
By default,
ACL data will not be restored when reading or restoring files from
an archive. However, for USTAR and OS390 formatted archives, you can
use tar –A to restore ACL data.
For Archive
Listing (Table of Contents):
For verbose output (
tar
–v),
+ is added to the end of the file permission
bits for all files with extended ACLs. For example,
file2 and
dir1 have
extended ACL entries:
> 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
That is, the settings of system and environment variables that
turn automatic conversion on and off will have no affect on tar's
reading and writing of files. pax supports
file tag options which support conversion of files based on their
file tag settings.
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:
> tar -f acldata.tar
file1
file2
dir1
If you also specify –L A,
ACL information will be displayed: > tar -L A -f acldata.tar
file1
file2
user:WELLIE2:rw-
group:SYS1:rwx
Finally, if you add the verbose option, –v,
you will see the chmod settings associated with the file: > 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
tar uses
the following localization environment variables:
- 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.