tar(1) tar(1)
NAME
tar - archive files and manipulate archives (tape archiver)
SYNOPSIS
tar option[modifier] file ... Format 1
tar t[modifier] [file ...] Format 2
tar x[modifier] [file ...] Format 3
DESCRIPTION
tar can be used to:
- archive files or directories on data storage media (Format 1).
- list the contents of an archive (Format 2).
- extract all or part of an archive created with tar (Format 3).
The system administrator may use tar to back up and restore all files
and directories. Non-privileged users can only back up files and
directories for which they have access permission (read permission for
files and execute permission for directories). Non-privileged users
wanting to restore archived files and directories require write per-
mission for the directory to be written to.
Note: tar archives can also be read and created using the pax(1) and
cpio(1) commands.
Functionality
tar processes files in archival form on a data storage medium. Only
one archive can be processed with a single invocation of tar.
It is not possible to create more than one archive on a floppy disk.
By contrast, you can create several archives on a magnetic tape or
tape cartridge and use the command mt(1) to wind to the start or end
of a particular archive. tar always reads from the archive at the
current tape position. If all of several archives are to be read from
a storage medium, a separate tar command must be given for each
archive.
If you use the appropriate special file when extracting an archive,
i.e. a special file without automatic rewinding, the tape position
will automatically be set to the start of the next archive after an
archive is read. The tape need not be repositioned with mt(1) in such
a case.
Page 1 Reliant UNIX 5.44 Printed 11/98
tar(1) tar(1)
Before the call
Before you execute tar, you must first load the storage medium in the
appropriate drive. If you wish to create a new archive, the write pro-
tect mechanism used on the device must be removed. See the operating
manual provided with your computer for more information. If the
archive is to be created on a floppy disk, the floppy disk will need
to be formatted. The dosformat(1) or flformat(1M) command is used for
this purpose.
After the call
It is advisable to remove the data medium from the drive after execut-
ing tar. Otherwise, another user might call tar again and inadver-
tently destroy or corrupt your archive.
In each of the three formats the main option can be combined with
various modifiers.
Format 1: Archiving files and directories
tar option[modifier] file ...
option
[-]c, [-]r, [-]u
modifier without argument
A, e, L, n, v, w, number
modifier with argument
b blocking-factor, f archive, F ffile, k kbytes, X xfile
If you are a normal user without system administrator privileges, you
may only archive files and directories for which you have access per-
mission. Read permission is required for files; execute permission for
directories.
Options
option is any one of the following letters, with or without a minus
sign:
[-]c
Floppy disks:
(create) tar creates a new archive on the floppy disk and writes
the specified files at the beginning of this archive, overwriting
any archive previously existing on the floppy disk in the pro-
cess. If you specify more than one file, they are entered sequen-
tially. If you specify a directory, all subtrees of the directory
are archived recursively.
Page 2 Reliant UNIX 5.44 Printed 11/98
tar(1) tar(1)
Magnetic tapes and tape cartridges:
tar writes the specified file or directory at the currently set
position of the storage medium. You can use the mt(1) command to
wind on to the end of an archive. Thus tar c allows you to append
several archives to one another. Note that you can prevent the
tape from being automatically rewound after being accessed by the
tar command by specifying a "no rewind" special file.
If there are several archives on a streamer tape, overwriting any
one of them will render all subsequently stored archives unread-
able.
Caution: If you need to archive more data than will fit on a
single volume, you must initialize continuation volume
processing using the k modifier.
[-]r This function applies only to floppy disk or hard disk archives.
The named files are appended to the end of an existing archive.
The appended files belong to the same archive.
If there are a number of files with the same name in an archive,
restoring files from that archive will produce only one instance
of a file with that name, earlier instances being successively
overwritten.
You can only use this option in conjunction with the n option.
[-]u (update) This function applies only to floppy disk or hard disk
archives.
The named files are appended to the end of an existing archive
only if
- they do not already exist in the archive
- or they have a more recent modification date than the archived
files.
The appended files belong to the same archive.
If there are a number of files with the same name in an archive,
restoring files from that archive will produce only one instance
of a file with that name, earlier instances being successively
overwritten.
You can only use this options in conjunction with the n option.
Page 3 Reliant UNIX 5.44 Printed 11/98
tar(1) tar(1)
Modifiers
The effect of the selected function can be influenced by specifying
function modifiers. These modifiers must be appended to the option
letter without intervening blanks and can in some cases also take
arguments. The following points must be observed:
1. All modifiers must be grouped together without blanks, followed by
2. all arguments, separated by blanks. The arguments must be in the
same order as the modifiers with which they are associated.
A If you specify the files to archive in the form of absolute path
names, tar suppresses the first slash.
Note: This modifier is a Reliant UNIX specific functional
enhancement of the tar command. There is no guarantee of
long-term support for this enhancement in future product
releases.
b blockingfactor
The blocking factor specifies the number of tape blocks to be
written by tar per tape or floppy disk access.
blockingfactor
Any number from 1 to 20 can be given as the blocking factor.
b blockingfactor not specified: Blocking factor = 1.
e Errors cause tar to abort immediately.
Note: This modifier is a Reliant UNIX specific functional
enhancement of the tar command. There is no guarantee of
long-term support for this enhancement in future product
releases.
f archive
tar expects you to specify an archive to write to.
archive may be one of the following:
specialfile
Name of the special file to which the archive is to be writ-
ten.
- (dash) If you use a dash as argument, tar writes to standard
output. This feature enables tar to be used in a pipe to
copy or move directories or file systems (see Example 5).
file If you specify a regular file as archive, a tar archive
named archive is created on the hard disk.
Page 4 Reliant UNIX 5.44 Printed 11/98
tar(1) tar(1)
f archive not specified:
If the TAPE shell variable is set, tar takes the value of
TAPE as the current special file. If TAPE is not set, tar
selects the file associated with 0 in the /etc/default/tar
file.
F ffile
tar reads the names of the files to archive from the file ffile.
ffile is a list of file names, one name per line. Any other files
you want to archive can be named on the command line in the usual
way.
This modifier cannot be combined with the X modifier.
Note: This modifier is a Reliant UNIX specific functional
enhancement of the tar command. There is no guarantee of
long-term support for this enhancement in future product
releases.
k kbytes
If you need to archive more data than will fit on a single
volume, you must initialize continuation tape processing using
the k modifier.
kbytes is the length of the volume to be used in kilobytes, minus
a safety margin in the case of tapes. During writing, any bad
spots on the tape will automatically be skipped, so less data
will fit on the tape. Thus if you want to use a 155K tape, you
could use a kbytes value of 140. You should choose the size of
the safety margin empirically on the basis of previous experience
with the tapes you use.
Once kbytes kilobytes have been written to the volume, you will
be requested to insert another volume and press RETURN.
Note: This modifier is a Reliant UNIX specific functional
enhancement of the tar command. There is no guarantee of
long-term support for this enhancement in future product
releases.
L (links) tar follows symbolic links. If this modifier is not
specified, tar writes the symbolic link only, and not the corre-
sponding files.
n (not tape) This modifier specifies that the argument in f archive
refers only to to a medium on which lseek(2) can be used for
positioning (hard disk, floppy disk). You must use this modifier
if you want to use the r or u options.
v (v - verbose) Activates verbose mode, in which tar outputs the
following information for each file it processes:
Page 5 Reliant UNIX 5.44 Printed 11/98
tar(1) tar(1)
a (append) the specified file has been added to the
archive.
pathname the path name under which the file was entered.
n blocks the number of blocks occupied by the file.
The size of a block depends on the medium used.
v not specified: tar operates silently, displaying no messages.
w (what) Confirmation mode; tar requests confirmation for each file
before archiving it. The following is displayed:
option filename:
You are expected to enter your answer after the colon. tar only
archives the file if you answer the locale's equivalent of yes.
w not specified: tar operates without requesting confirmation.
X xfile
tar excludes the files listed in xfile from the backup. This
applies even if such files are also specified on the command line
(either explicitly or as a result of file name expansion). xfile
is a list of file names, one name per line.
This modifier cannot be combined with the F modifier.
Note: This modifier is a Reliant UNIX specific functional
enhancement of the tar command. There is no guarantee of
long-term support for this enhancement in future product
releases.
number
Here you can enter a number between 0 and 9. tar then selects the
corresponding entry from the /etc/default/tar file as the special
file. In /etc/default/tar the system administrator can list ten
special files that you can then address in abbreviated form via
number, e.g. tar tv5.
If the TAPE shell variable is set, tar uses its value as the spe-
cial file.
file Names of the files or directories to be archived. You must give
at least one name.
If the specified file is a directory, tar recursively archives this
directory and all the files and subdirectories contained in it.
Shell file name generation metacharacters may also be used [see
specialchar(5)].
Page 6 Reliant UNIX 5.44 Printed 11/98
tar(1) tar(1)
Format 2: Listing the contents of an archive
tar t[modifier] [file ...]
modifier
f specialfile, v, number
Option
t (table) tar lists the name of the file specified if it exists in
the archive. If no file is specified, tar lists the contents of
the entire archive.
Modifiers
The effect of the tar t command can be influenced by specifying one or
more function modifiers. These modifiers must be appended to the
option letter without intervening blanks. The following points must be
observed when using more than one modifier:
1. All modifiers (including f) must be grouped together without
blanks, followed by
2. specialfile (with f), separated by blanks.
f specialfile
tar expects you to specify the special file it is to read from.
You also have the option of using the default special file.
specialfile
Name of the special file to read from.
f specialfile not specified:
tar selects entry 0 from the /etc/default/tar file (see
number modifier). If the TAPE shell variable is set, tar
takes the value of TAPE as the current special file.
v (verbose) Activates verbose mode, in which tar outputs the fol-
lowing information for each file:
- the access rights
- user and group IDs (UID/GID)
- size in bytes
- date and time the file was created
- name of the file.
v not specified: Only the names of the files are output.
Page 7 Reliant UNIX 5.44 Printed 11/98
tar(1) tar(1)
number
Here you can enter a number between 0 and 9. tar then selects the
corresponding entry from the /etc/default/tar file as the special
file. In /etc/default/tar the system administrator can list ten
special files that you can then address in abbreviated form via
number, e.g. tar tv5.
If the TAPE shell variable is set, tar uses its value as the spe-
cial file.
file Name of the file to be listed if in the archive. Several files
may be specified at the same time.
If the specified file is a directory, tar recursively lists the
contents of this directory and all the files and subdirectories
contained in it.
file not specified: tar lists the contents of the entire archive.
Format 3: Extracting files
tar x[modifier] [file ...]
modifier without argument
A, e, i, l, m, o, p, v, w, C, number
modifier with argument
f archive, F ffile, X xfile, I includefile
Option
x Extracts the specified file from the archive. If the file was
archived under its relative path name, it is restored in the
current directory; if the absolute path name is in the archive,
the file is restored in the appropriate directory, if present
(but also refer to modifier A).
If you are a normal user without system administrator privileges,
you will need write permission for the directory in which the
file is to be restored.
If the specified file is a directory, all the files and subdirec-
tories contained in it are restored.
If a given archived file does not exist in the directory in which
it is to be restored, the file is created.
The extracted files and directories are given the user ID and
group ID of the user who called tar x (but also refer to modifier
o).
Page 8 Reliant UNIX 5.44 Printed 11/98
tar(1) tar(1)
Access permissions are set as defined by umask (but also refer to
modifier p).
If the specified file already exists in the directory in which it
is to be restored, its access modes are not changed. The s bit is
not taken into account unless tar is invoked by the system
administrator. The owner, group, and modification time remain
unaltered.
If there are a number of files with the same name in an archive
(see Format 1, options r and u), restoring files from that
archive will produce only one instance of a file with that name,
earlier instances being successively overwritten. The modifica-
tion time is ignored in this case.
Modifiers
The effect of the tar x command can be influenced by specifying func-
tion modifiers. These modifiers must be appended to the option letter
without intervening blanks. The following points must be observed:
1. First group together all modifiers without separating blanks.
2. Then list all the arguments, separated by blanks. The order of the
arguments is determined by the order of the associated modifiers.
A If you specify the files to restore in the form of absolute path
names,or if the files are archived under absolute path names, tar
suppresses the first slash and restores the files to the current
directory.
Note: This modifier is a Reliant UNIX specific functional
enhancement of the tar command. There is no guarantee of
long-term support for this enhancement in future product
releases.
e Errors cause tar to abort immediately.
Note: This modifier is a Reliant UNIX specific functional
enhancement of the tar command. There is no guarantee of
long-term support for this enhancement in future product
releases.
f archive
tar expects you to specify an archive to read.
archive may be one of the following:
specialfile
Name of the special file to read.
Page 9 Reliant UNIX 5.44 Printed 11/98
tar(1) tar(1)
- (dash) If you use a dash as argument, tar reads from stan-
dard input. This feature enables tar to be used in a pipe,
for example to copy or move directories or file systems (see
Example 5).
file If you specify a regular file as archive, a tar archive
named archive is read from the hard disk.
f archive not specified:
If the TAPE shell variable is set, tar takes the value of
TAPE as the current special file. If TAPE is not set, tar
selects the file associated with 0 in the /etc/default/tar
file.
F ffile
tar reads the names of the files to extract from the file ffile.
ffile is a list of file names, one name per line. Any other files
you want to extract can be named on the command line in the usual
way.
This modifier cannot be combined with the X modifier.
Note: This modifier is a Reliant UNIX specific functional
enhancement of the tar command. There is no guarantee of
long-term support for this enhancement in future product
releases.
i tar attempts to continue extracting files from the archive in
spite of a bad file header checksum.
Note: This modifier is a Reliant UNIX specific functional en-
hancement of the tar command. There is no guarantee of
long-term support for this enhancement in future product
releases.
l tar reports when it cannot resolve all links to files being
archived. This does not apply to symbolic links.
l not specified: No error messages are issued if a link cannot be
resolved.
m (modify) Instructs tar to set the modification time of each file
extracted from the archive to the date and time of extraction.
m not specified: The modification time remains the same as in the
archive.
o (ownership) This option only works when selected by a user with
system administrator privileges.
Files extracted from the archive take on the UID and GID of root.
Page 10 Reliant UNIX 5.44 Printed 11/98
tar(1) tar(1)
o not specified:
An extracted file takes on the user and group IDs that appear in
the archive.
p The extracted files are given the same permissions as in the
archive, irrespective of how umask is set.
Note: This modifier is a Reliant UNIX specific functional
enhancement of the tar command. There is no guarantee of
long-term support for this enhancement in future product
releases.
v (verbose) Activates verbose mode, in which tar outputs the fol-
lowing information for each file or directory it extracts:
x The specified file has extracted and placed in the
appropriate directory.
k byte The size of the file is k bytes.
n tape blocks The file occupies n blocks. The block size depends
on the medium used.
v not specified: tar operates without reporting what it is doing.
w (what) Confirmation mode; tar requests confirmation for each file
before extracting it. The following is displayed:
x filename:
You are expected to enter your answer after the colon. tar only
performs the function if you answer the locale's equivalent of
yes.
w not specified: tar extracts the files without requesting con-
firmation.
X xfile
tar excludes the files listed in xfile. This applies even if such
files are also specified on the command line (either explicitly
or as a result of file name expansion). xfile is a list of file
names, one name per line.
This modifier cannot be combined with the F modifier.
Note: This modifier is a Reliant UNIX specific functional en-
hancement of the tar command. There is no guarantee of
long-term support for this enhancement in future product
releases.
Page 11 Reliant UNIX 5.44 Printed 11/98
tar(1) tar(1)
I includefile
(I - Include) Specifies a file includefile containing a file
list that is to be included in the list of files to be extracted.
As with the F and X options, specify one file per line in the
list.
C (C - Compatibility) This option is used for compatibility reasons
to create archives for systems which use signed char checksum
computing (e.g. the most Intel systems).
number
Here you can enter a number between 0 and 9. tar then selects the
corresponding entry from the /etc/default/tar file as the special
file. In /etc/default/tar the system administrator can list ten
special files that you can then address in abbreviated form via
number, e.g. tar tv5.
If the TAPE shell variable is set, tar takes the value of TAPE as
the current special file.
file Name of the file to be extracted if in the archive. Several
blank-separated files may be specified at the same time.
If the specified file is a directory, tar recursively extracts
this directory and all the files and subdirectories contained in
it.
If the file name includes shell metacharacters, they must be
enclosed in single quotes '...'. Otherwise, the shell tries to
substitute the metacharacters specified on the basis of the file
names in the current directory rather than those in the archive.
file not specified: tar extracts the entire archive.
MESSAGES
Warning: just archiving file filename > 2GB.
cannot open /dev/rts0
You have specified a special file that is not present. This error
message is also issued if you have specified the wrong special
file for a data medium.
tape write error
There are three types of error that can cause this error message:
- You are using an unformatted floppy disk. Use dosformat(1) or
flformat(1M) to format the disk.
- If this message appears when tar has already started, it is
likely that the specified files will not fit on the selected
medium. In this case the last few files have generally not
been correctly backed up.
Page 12 Reliant UNIX 5.44 Printed 11/98
tar(1) tar(1)
- The data medium is write-protected.
- The data medium is defective.
tape read error
- Your data medium is empty.
- There is no data medium in the drive.
- The data medium is defective.
directory checksum error
- Your data medium is empty.
- A file has been stored incorrectly.
- The archive has been corrupted.
blocked tapes cannot be updated
r or u has been specified without n.
device argument required
No special file has been specified.
ENVIRONMENT VARIABLES
TAPE You can define a special file to be used if the f modifier is
not specified.
TZ defines the time zone within date and time specifications.
LOCALE
The LCMESSAGES environment variable governs the language in which
message texts are displayed.
Answers to yes/no queries must be given in the language appropriate to
the current locale.
The LCTIME environment variable governs the format of date and time
strings in archive table-of-contents listings produced by the v
option.
If LCMESSAGES or LCTIME is undefined or is defined as the null
string, it defaults to the value of LANG. If LANG is likewise unde-
fined or null, the system acts as if it were not internationalized.
The LCALL environment variable governs the entire locale. LCALL
takes precedence over all the other environment variables which affect
internationalization.
Page 13 Reliant UNIX 5.44 Printed 11/98
tar(1) tar(1)
If any of the locale variables has an invalid value, the system acts
as if none of the variables were set.
The ISO 8859-1 character set [see meta-ascii(5)] is used for file
transfers between X/Open-compliant systems. 8-bit data and file names
are subject to certain restrictions in respect of porting to non-
internationalized systems. Thus when transferring data between systems
of different types it is advisable to use only 7-bit ASCII characters
[from the ISO 646 character set, see ascii(5)]. When choosing file
names make sure that you only use characters which are in the Portable
Filename Character Set.
EXAMPLES
1. Archiving on floppy disk
All files contained in the current directory and its subdirectories
are to be backed up on a floppy disk; the name of each file being
archived is to be displayed. Any previous archive on the floppy disk
is overwritten.
$ tar cvf /dev/ios0/sfdisk0053ht *
a john/letters/private/aunt 9 blocks
a john/letters/private/uncle 6 blocks
a john/letters/job/boss1 3 blocks
a john/book/manuscript 158 blocks
a john/book/errors 16 blocks
a john/tools/program 20 blocks
...
2. Archiving on tape cartridge
The directory documents is to be backed up in the second archive on a
tape cartridge with a blocking factor of 20. The tape has already been
positioned. Since it is not to be rewound after tape access, the spe-
cial file /dev/ios0/rstape004n is used.
$ tar cbf 20 /dev/ios0/rstape004n documents
3. Archiving on open-reel tape
The file letter is to be archived on a tape with a blocking factor of
20 and a recording density of 1600 bpi. The tape is then to be
rewound.
$ tar cfb /dev/ios0/rstape004 20 letter
4. Listing the contents of all archives on a tape
The contents of an entire tape are to be listed in detailed format.
Since three archives are stored on the tape, the special file without
rewinding is used, and tar is called a number of times.
Page 14 Reliant UNIX 5.44 Printed 11/98
tar(1) tar(1)
$ tar tvf /dev/ios0/rstape004n; tar tvf /dev/ios0/rstape004n; tar tvf
/dev/ios0/rstape004n
tar: blocksize = 20
rw------- 33/1 2024 Sep 19 15:23 1988 john/letters/private/uncle
rw-rw---- 33/1 1365 Oct 20 08:12 1988 john/letters/job/boss1
...
tar: blocksize = 20
rw-r--r-- 45/3 2345 Jan 18 13:20 1989 patty/test
rwxr-xr-x 45/3 800 Jan 27 12:50 1989 patty/program
...
tar: blocksize = 20
rw------- 40/3 4567 Apr 10 07:58 1988 frank/texts/chap1
rw------- 40/3 2367 Apr 10 08:50 1988 frank/texts/chap2
...
5. Using tar in a pipeline
The directory /home1/john is to be copied to /home/john.
$ (cd /home1/john; tar cf - .) | (cd /home/john; tar xf -)
Caution: Do not use the v option here, as it writes to standard out-
put.
FILES
/dev Directory containing all available special files.
/etc/default/tar
File containing a list of up to ten special files that can be
selected using the number modifier.
If the TAPE shell variable is set, tar takes the value of TAPE as
the current special file.
SEE ALSO
ar(1), cpio(1), dosformat(1), gettypes(1), ls(1), mt(1), pax(1),
flformat(1M).
Page 15 Reliant UNIX 5.44 Printed 11/98