tar
Note: creating an archive file (``tar file'') does not delete the
original files+directories. Extracting files from a tar file
will overwrite any previously existing files of the same names.
man pages for tar
NAME
tar - create tape archives and add or extract files
SYNOPSIS
tar c [ bBeEfFhiklnopPqvwX [ 0-7 ] ] [ block ] [ tar-
file ] [ exclude-file ] { -I include-file | -C directory
| file | file } ...
tar r [ bBeEfFhiklnqvw [ 0-7 ] ] [ block ] {
-I include-file | -C directory | file | file } ...
tar t [ BefFhiklnqvX [ 0-7 ] ] [ tarfile ] [ exclude-
file ] { -I include-file | file } ...
tar u [ bBeEfFhiklnqvw [ 0-7 ] ] [ block ] [ tarfile ]
file ...
tar x [ BefFhiklmnopqvwX [ 0-7 ] ] [ tarfile ] [
exclude-file ] [ file ... ]
DESCRIPTION
The tar command archives and extracts files to and from a
single file called a tarfile. A tarfile is usually a mag-
netic tape, but it can be any file. tar's actions are con-
trolled by the key argument. The key is a string of charac-
ters containing exactly one function letter (c, r, t , u, or
x) and zero or more function modifiers (letters or digits),
depending on the function letter used. The key string con-
tains no SPACE characters. Function modifier arguments are
listed on the command line in the same order as their
corresponding function modifiers appear in the key string.
The -I include-file, -C directory file, and file arguments
specify which files or directories are to be archived or
extracted. In all cases, appearance of a directory name
refers to the files and (recursively) subdirectories of that
directory. Arguments appearing within braces ({}) indicate
that one of the arguments must be specified.
OPTIONS
The following options are supported:
-I include-file
Opens include-file containing a list of files, one per
line, and treats it as if each file appeared
separately on the command line. Be careful of trailing
white spaces. Also beware of leading white spaces,
since, for each line in the included file, the entire
line (apart from the newline) will be used to match
against the initial string of files to include. In the
case where excluded files (see X function modifier)
are also specified, they take precedence over all
included files. If a file is specified in both the
exclude-file and the include-file (or on the command
line), it will be excluded.
-C directory file
Performs a chdir (see cd(1)) operation on directory
and performs the c (create) or r (replace) operation
on file. Use short relative path names for file. If
file is `.', archive all files in directory. This
option enables archiving files from multiple direc-
tories not related by a close common parent.
OPERANDS
The following operands are supported:
file A path name of a regular file or directory to be
archived (when the c, r or u functions are specified),
extracted (x) or listed (t). When file is the path
name of a directory, the action applies to all of the
files and (recursively) subdirectories of that direc-
tory.
When a file is archived, and the E flag (see Function
Modifiers) is not specified, the filename cannot
exceed 256 characters. In addition, it must be possi-
ble to split the name between parent directory names
so that the prefix is no longer than 155 characters
and the name is no longer than 100 characters. If E is
specified, a name of up to PATH_MAX characters may be
specified.
For example, a file whose basename is longer than 100
characters could not be archived without using the E
flag. A file whose directory portion is 200 characters
and whose basename is 50 characters could be archived
(without using E) if a slash appears in the directory
name somewhere in character positions 151-156.
Function Letters
The function portion of the key is specified by one of the
following letters:
c Create. Writing begins at the beginning of the tar-
file, instead of at the end.
r Replace. The named files are written at the end of the
tarfile. A file created with extended headers must be
updated with extended headers (see E flag under Func-
tion Modifiers). A file created without extended
headers cannot be modified with extended headers.
t Table of Contents. The names of the specified files
are listed each time they occur in the tarfile. If no
file argument is given, the names of all files in the
tarfile are listed. With the v function modifier,
additional information for the specified files is
displayed.
u Update. The named files are written at the end of the
tarfile if they are not already in the tarfile, or if
they have been modified since last written to that
tarfile. An update can be rather slow. A tarfile
created on a 5.x system cannot be updated on a 4.x
system. A file created with extended headers must be
updated with extended headers (see E flag under Func-
tion Modifiers). A file created without extended
headers cannot be modified with extended headers.
x Extract or restore. The named files are extracted from
the tarfile and written to the directory specified in
the tarfile, relative to the current directory. Use
the relative path names of files and directories to be
extracted. If a named file matches a directory whose
contents has been written to the tarfile, this direc-
tory is recursively extracted. The owner, modification
time, and mode are restored (if possible); otherwise,
to restore owner, you must be the super-user.
Character-special and block-special devices (created
by mknod(1M)) can only be extracted by the super-user.
If no file argument is given, the entire content of
the tarfile is extracted. If the tarfile contains
several files with the same name, each file is written
to the appropriate directory, overwriting the previous
one. Filename substitution wildcards cannot be used
for extracting files from the archive; rather, use a
command of the form:
tar xvf... /dev/rmt/0 `tar tf... /dev/rmt/0 | grep 'pattern' `
When extracting tapes created with the r or u functions,
directory modification times may not be set correctly. These
same functions cannot be used with many tape drives due to
tape drive limitations such as the absence of backspace or
append capabilities.
When using the r, u, or x functions or the X function modif-
ier, the named files must match exactly the corresponding
files in the tarfile. For example, to extract ./thisfile,
you must specify ./thisfile, and not thisfile. The t func-
tion displays how each file was archived.
Function Modifiers
The characters below may be used in conjunction with the
letter that selects the desired function.
b Blocking Factor. Use when reading or writing to raw
magnetic archives (see f below). The block argument
specifies the number of 512-byte tape blocks to be
included in each read or write operation performed on
the tarfile. The minimum is 1, the default is 20. The
maximum value is a function of the amount of memory
available and the blocking requirements of the
specific tape device involved (see mtio(7I) for
details.) The maximum cannot exceed INT_MAX/512
(4194303).
When a tape archive is being read, its actual blocking
factor will be automatically detected, provided that
it is less than or equal to the nominal blocking fac-
tor (the value of the block argument, or the default
value if the b modifier is not specified). If the
actual blocking factor is greater than the nominal
blocking factor, a read error will result. See Exam-
ple 5 in EXAMPLES.
B Block. Force tar to perform multiple reads (if neces-
sary) to read exactly enough bytes to fill a block.
This function modifier enables tar to work across the
Ethernet, since pipes and sockets return partial
blocks even when more data is coming. When reading
from standard input, '-', this function modifier is
selected by default to ensure that tar can recover
from short reads.
e Error. Exit immediately with a positive exit status if
any unexpected errors occur. The SYSV3 environment
variable overrides the default behavior. (See ENVIRON-
MENT section below.)
E Write a tarfile with extended headers. (Used with c,
r, or u options; ignored with t or x options.) When a
tarfile is written with extended headers, the modifi-
cation time is maintained with a granularity of
microseconds rather than seconds. In addition,
filenames no longer than PATH_MAX characters that
could not be archived without E, and file sizes
greater than 8GB, are supported. The E flag is
required whenever the larger files and/or files with
longer names, or whose UID/GID exceed 2097151, are to
be archived, or if time granularity of microseconds is
desired.
f File. Use the tarfile argument as the name of the
tarfile. If f is specified, /etc/default/tar is not
searched. If f is omitted, tar will use the device
indicated by the TAPE environment variable, if set;
otherwise, it will use the default values defined in
/etc/default/tar. If the name of the tarfile is '-',
tar writes to the standard output or reads from the
standard input, whichever is appropriate. tar can be
used as the head or tail of a pipeline. tar can also
be used to move hierarchies with the command:
example% cd fromdir; tar cf - .| (cd todir; tar xfBp -)
F With one F argument, tar excludes all directories
named SCCS and RCS from the tarfile. With two argu-
ments, FF, tar excludes all directories named SCCS and
RCS, all files with .o as their suffix, and all files
named errs, core, and a.out. The SYSV3 environment
variable overrides the default behavior. (See ENVIRON-
MENT section below.)
h Follow symbolic links as if they were normal files or
directories. Normally, tar does not follow symbolic
links.
i Ignore directory checksum errors.
k size
Requires tar to use the size argument as the size of
an archive in kilobytes. This is useful when the
archive is intended for a fixed size device such as
floppy disks. Large files are then split across
volumes if they do not fit in the specified size.
l Link. Output error message if unable to resolve all
links to the files being archived. If l is not speci-
fied, no error messages are printed.
m Modify. The modification time of the file is the time
of extraction. This function modifier is valid only
with the x function.
n The file being read is a non-tape device. Reading of
the archive is faster since tar can randomly seek
around the archive.
o Ownership. Assign to extracted files the user and
group identifiers of the user running the program,
rather than those on tarfile. This is the default
behavior for users other than root. If the o function
modifier is not set and the user is root, the
extracted files will take on the group and user iden-
tifiers of the files on tarfile (see chown(1) for more
information). The o function modifier is only valid
with the x function.
p Restore the named files to their original modes, and
ACLs if applicable, ignoring the present umask(1).
This is the default behavior if invoked as super-user
with the x function letter specified. If super-user,
SETUID and sticky information are also extracted, and
files are restored with their original owners and per-
missions, rather than owned by root. When this func-
tion modifier is used with the c function, ACLs are
created in the tarfile along with other information.
Errors will occur when a tarfile with ACLs is
extracted by previous versions of tar.
P Suppress the addition of a trailing "/" on directory
entries in the archive.
q Stop after extracting the first occurrence of the
named file. tar will normally continue reading the
archive after finding an occurrence of a file.
v Verbose. Output the name of each file preceded by the
function letter. With the t function, v provides addi-
tional information about the tarfile entries. The
listing is similar to the format produced by the -l
option of the ls(1) command.
w What. Output the action to be taken and the name of
the file, then await the user's confirmation. If the
response is affirmative, the action is performed; oth-
erwise, the action is not performed. This function
modifier cannot be used with the t function.
X Exclude. Use the exclude-file argument as a file con-
taining a list of relative path names for files (or
directories) to be excluded from the tarfile when
using the functions c, x, or t. Be careful of trailing
white spaces. Also beware of leading white spaces,
since, for each line in the excluded file, the entire
line (apart from the newline) will be used to match
against the initial string of files to exclude. Multi-
ple X arguments may be used, with one exclude-file per
argument. In the case where included files (see -I
include-file option) are also specified, the excluded
files take precedence over all included files. If a
file is specified in both the exclude-file and the
include-file (or on the command line), it will be
excluded.
[0-7] Select an alternative drive on which the tape is
mounted. The default entries are specified in
/etc/default/tar. If no digit or f function modifier
is specified, the entry in /etc/default/tar with digit
"0" is the default.
USAGE
See largefile(5) for the description of the behavior of tar
when encountering files greater than or equal to 2 Gbyte ( 2
**31 bytes).
The automatic determination of the actual blocking factor
may be fooled when reading from a pipe or a socket (see the
B function modifier below).
1/4" streaming tape has an inherent blocking factor of one
512-byte block. It can be read or written using any block-
ing factor.
This function modifier works for archives on disk files and
block special devices, among others, but is intended princi-
pally for tape devices.
For information on tar header format, see archives(4).
EXAMPLES
Example 1: Using the tar Command to Create an Archive of
Your Home Directory
The following is an example using tar to create an archive
of your home directory on a tape mounted on drive
/dev/rmt/0:
example% cd
example% tar cvf /dev/rmt/0 .
messages from tar
The c function letter means create the archive; the v func-
tion modifier outputs messages explaining what tar is doing;
the f function modifier indicates that the tarfile is being
specified ( /dev/rmt/0 in this example). The dot (.) at the
end of the command line indicates the current directory and
is the argument of the f function modifier.
Display the table of contents of the tarfile with the fol-
lowing command:
example% tar tvf /dev/rmt/0
The output will be similar to the following for the POSIX
locale:
rw-r--r-- 1677/40 2123 Nov 7 18:15 1985 ./test.c
...
example%
The columns have the following meanings:
o column 1 is the access permissions to ./test.c
o column 2 is the user-id/group-id of ./test.c
o column 3 is the size of ./test.c in bytes
o column 4 is the modification date of ./test.c. When
the LC_TIME category is not set to the POSIX locale, a
different format and date order field may be used.
o column 5 is the name of ./test.c
To extract files from the archive:
example% tar xvf /dev/rmt/0
messages from tar
example%
If there are multiple archive files on a tape, each is
separated from the following one by an EOF marker. To have
tar read the first and second archives from a tape with mul-
tiple archives on it, the non-rewinding version of the tape
device name must be used with the f function modifier, as
follows:
example% tar xvfp /dev/rmt/0n read first archive from tape
messages from tar example% tar xvfp /dev/rmt/0n read second archive from tape
messages from tar example%
Note that in some earlier releases, the above scenario did
not work correctly, and intervention with mt(1) between tar
invocations was necessary. To emulate the old behavior, use
the non-rewind device name containing the letter b for BSD
behavior. See the Close Operations section of the mtio(7I)
manual page.
Example 2: Using Tar To Archive Files From /usr/include And
From /etc To Default Tape Drive 0:
To archive files from /usr/include and from /etc to default
tape drive 0:
example% tar c -C /usr include -C /etc .
The table of contents from the resulting tarfile would pro-
duce output like the following:
include/
include/a.out.h
and all the other files in /usr/include ...
./chown and all the other files in /etc
To extract all files in the include directory:
example% tar xv include
x include/, 0 bytes, 0 tape blocksand all files under include...
Example 3: Using tar to Transfer Files Across the Network
The following is an example using tar to transfer files
across the network. First, here is how to archive files from
the local machine ( example) to a tape on a remote system (
host):
example% tar cvfb - 20 files | rsh host dd of=/dev/rmt/0 obs=20b
messages from tar
example%
In the example above, we are creating a tarfile with the c
key letter, asking for verbose output from tar with the v
function modifier, specifying the name of the output tarfile
using the f function modifier (the standard output is where
the tarfile appears, as indicated by the `-' sign), and
specifying the blocksize (20) with the b function modifier.
If you want to change the blocksize, you must change the
blocksize arguments both on the tar command and on the dd
command.
Example 4: Using Tar To Retrieve Files From A Tape On The
Remote System Back To The Local System:
The following is an example that uses tar to retrieve files
from a tape on the remote system back to the local system:
example% rsh -n host dd if=/dev/rmt/0 bs=20b | tar xvBfb - 20 files
messages from tar
example%
In the example above, we are extracting from the tarfile
with the x key letter, asking for verbose output from tar
with the v function modifier, telling tar it is reading from
a pipe with the B function modifier, specifying the name of
the input tarfile using the f function modifier (the stan-
dard input is where the tarfile appears, as indicated by the
`-' sign), and specifying the blocksize (20) with the b
function modifier.
Example 5: Creating An Archive Of The Home Directory On
/dev/rmt/0 With ABlocking Factor Of 19
The following example creates an archive of the home direc-
tory on /dev/rmt/0 with an actual blocking factor of 19:
example% tar cvfb /dev/rmt/0 19 $HOME
To recognize this archive's actual blocking factor without
using the b function modifier:
example% tar tvf /dev/rmt/0
tar: blocksize = 19
...
To recognize this archive's actual blocking factor using a
larger nominal blocking factor:
example% tar tvf /dev/rmt/0 30
tar: blocksize = 19
...
Attempt to recognize this archive's actual blocking factor
using a nominal blocking factor that is too small:
example% tar tvf /dev/rmt/0 10
tar: tape read error
ENVIRONMENT VARIABLES
SYSV3 This variable is used to override the default behavior
of tar, provide compatibility with INTERACTIVE UNIX
Systems and SCO UNIX installation scripts, and should
not be used in new scripts. (It is intended for com-
patibility purposes only.) When set, the following
options behave differently:
-F filename
Uses filename to obtain a list of command line
switches and files on which to operate.
-e Prevents files from being split across volumes.
If there is insufficient room on one volume, tar
prompts for a new volume. If the file will not
fix on the new volume, tar exits with an error.
See environ(5) for descriptions of the following environment
variables that affect the execution of tar: LC_CTYPE,
LC_MESSAGES, LC_TIME, TZ, and NLSPATH.