tar(1) User Commands tar(1)NAMEtar - create tape archives and add or extract files
SYNOPSIStar c[BDeEFhilnopPqTvw@[0-7]][bfk][X...] [blocksize]
[tarfile] [size] [exclude-file]...
{file | −I include-file | −C directory file}...
tar r[BDeEFhilnqTvw@[0-7]][bfk] [blocksize] [tarfile]
[size]
{file | −I include-file | −C directory file}...
tar t[BeFhilnqTv[0-7]][fk][X...] [tarfile] [size]
[exclude-file]... {file | −I include-file}...
tar u[BDeEFhilnqTvw@[0-7]][bfk] [blocksize] [tarfile]
[size] file...
tar x[BeFhilmnopqTvw[0-7]][fk][X...] [tarfile] [size]
[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 magnetic tape, but it can be
any file. tar's actions are controlled by the key argument. The key is
a string of characters 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 contains 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 (recur‐
sively) subdirectories of that directory. Arguments appearing within
braces ({ }) indicate that one of the arguments must be specified.
OPERANDS
The following operands are supported:
−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 operand enables
archiving files from multiple directories not
related by a close common parent.
−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 modi‐
fier) 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.
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 (recur‐
sively) subdirectories of that directory.
When a file is archived, and the E flag (see
Function Modifiers) is not specified, the file‐
name cannot exceed 256 characters. In addition,
it must be possible 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 with‐
out 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 tarfile, 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 Function 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 and any associated extended
attributes in the tarfile are listed. With the v function modi‐
fier, 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 sys‐
tem. A file created with extended headers must be updated with
extended headers (see E flag under Function 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.
Absolute path names contained in the tar archive are unpacked
using the absolute path names, that is, the leading forward slash
(/) is not stripped off.
If a named file matches a directory whose contents has been writ‐
ten to the tarfile, this directory is recursively extracted. The
owner, modification time, and mode are restored (if possible);
otherwise, to restore owner, you must be the super-user. Charac‐
ter-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 mod‐
ification 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 modifier, 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 function 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 blocksize Blocking Factor. Use when reading or writing to raw mag‐
netic archives (see f below). The blocksize 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 factor
(the value of the blocksize 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 Example 5 in EXAM‐
PLES.
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 Ether‐
net, 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.
D Data change warnings. Used with c, r, or u function let‐
ters. Ignored with t or x function letters. If the size
of a file changes while the file is being archived,
treat this condition as a warning instead of as an
error. A warning message will still be written, but the
exit status is not affected.
e Error. Exit immediately with a positive exit status if
any unexpected errors occur. The SYSV3 environment vari‐
able overrides the default behavior. (See ENVIRONMENT
VARIABLES section below.)
E Write a tarfile with extended headers. (Used with c, r,
or u function letters. Ignored with t or x function let‐
ters.) When a tarfile is written with extended headers,
the modification time is maintained with a granularity
of microseconds rather than seconds. In addition, file‐
names 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 indi‐
cated by the TAPE environment variable, if set. Other‐
wise, tar will use the default values defined in
/etc/default/tar. The number matching the archiveN
string is used as the output device with the blocking
and size specifications from the file. For example,
tar-c 2/tmp/*
writes the output to the device specified as archive2 in
/etc/default/tar.
If the name of the tarfile is "−", tar writes to the
standard output or reads from the standard input, which‐
ever 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 arguments, 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 over‐
rides the default behavior. (See ENVIRONMENT VARIABLES
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 identifiers of the files on tarfile
(see chown(1) for more information). The o function mod‐
ifier 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 permissions,
rather than owned by root. When this function 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 ver‐
sions 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.
T This modifier is only available if the system is config‐
ured with Trusted Extensions.
When this modifier is used with the function letter c,
r, or u for creating, replacing or updating a tarfile,
the sensitivity label associated with each archived file
and directory is stored in the tarfile.
Specifying T implies the function modifier p.
When used with the function letter x for extracting a
tarfile, the tar program verifies that the file's sensi‐
tivity label specified in the archive equals the sensi‐
tivity label of the destination directory. If not, the
file is not restored. This operation must be invoked
from the global zone. If the archived file has a rela‐
tive pathname, it is restored to the corresponding
directory with the same label, if available. This is
done by prepending to the current destination directory
the root pathname of the zone whose label equals the
file. If no such zone exists, the file is not restored.
Limited support is provided for extracting labeled ar‐
chives from Trusted Solaris 8. Only sensitivity labels,
and multi-level directory specifications are inter‐
preted. Privilege specifications and audit attribute
flags are silently ignored. Multilevel directory speci‐
fications including symbolic links to single level
directories are are mapped into zone-relative pathnames
if a zone with the same label is available. This support
is intended to facilitate migration of home directories.
Architectural differences preclude the extraction of
arbitrarily labeled files from Trusted Solaris 8 into
identical pathnames in Trusted Extensions. Files cannot
be extracted unless their archived label matches the
destination label.
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 list‐
ing 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; other‐
wise, the action is not performed. This function modi‐
fier 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 ini‐
tial string of files to exclude. Lines in the exclude
file are matched exactly, so an entry like "/var" will
not exclude the /var directory if tar is backing up rel‐
ative pathnames. The entry should read "./var" under
these circumstances. The tar command does not expand
shell metacharacters in the exclude file, so specifying
entries like "*.o" will not have the effect of excluding
all files with names suffixed with ".o". If a complex
list of files is to be excluded, the exclude file should
be generated by some means such as the find(1) command
with appropriate conditions.
Multiple X arguments may be used, with one exclude-file
per argument. In the case where included files (see −I
include-file operand) 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.
@ Include extended attributes in archive. By default, tar
does not place extended attributes in the archive. With
this flag, tar will look for extended attributes on the
files to be placed in the archive and add them to the
archive. Extended attributes go in the archive as spe‐
cial files with a special type label. When this modifier
is used with the x function, extended attributes are
extracted from the tape along with the normal file data.
Extended attribute files can only be extracted from an
archive as part of a normal file extract. Attempts to
explicitly extract attribute records are ignored.
[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 blocking factor.
This function modifier works for archives on disk files and block spe‐
cial devices, among others, but is intended principally for tape
devices.
For information on tar header format, see archives.h(3HEAD).
EXAMPLES
Example 1 Creating 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 function modifier
outputs messages explaining what tar is doing. The f function modifier
indicates that the tarfile is being specified (/dev/rmt/0 in this exam‐
ple). 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 following com‐
mand:
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 sec‐
ond archives from a tape with multiple archives on it, the non-rewind‐
ing 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%
Notice that in some earlier releases, the above scenario did not work
correctly, and intervention with mt(1) between tar invocations was nec‐
essary. To emulate the old behavior, use the non-rewind device name
containing the letter b for BSD behavior. See the Close Operations sec‐
tion of the mtio(7I) manual page.
Example 2 Archiving 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 produce 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 blocks \
and all files under include ...
Example 3 Transferring files across the network
The following is an example using tar to transfer files across the net‐
work. First, here is how to archive files from the local machine (exam‐
ple) 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, speci‐
fying 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 Retrieving 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 modi‐
fier, telling tar it is reading from a pipe with the B function modi‐
fier, specifying the name of the input tarfile using the f function
modifier (the standard 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
The following example creates an archive of the home directory 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 nomi‐
nal blocking factor:
example% tar tvf /dev/rmt/0 30
tar: blocksize = 19
...
Attempt to recognize this archive's actual blocking factor using a nom‐
inal 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 compatibility purposes only.)
When set, the following function modifiers 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
fit 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.
EXIT STATUS
The following exit values are returned:
0 Successful completion.
>0 An error occurred.
FILES
/dev/rmt/[0-7][b][n]
/dev/rmt/[0-7]l[b][n]
/dev/rmt/[0-7]m[b][n]
/dev/rmt/[0-7]h[b][n]
/dev/rmt/[0-7]u[b][n]
/dev/rmt/[0-7]c[b][n]
/etc/default/tar Settings may look like this:
archive0=/dev/rmt/0
archive1=/dev/rmt/0n
archive2=/dev/rmt/1
archive3=/dev/rmt/1n
archive4=/dev/rmt/0
archive5=/dev/rmt/0n
archive6=/dev/rmt/1
archive7=/dev/rmt/1n
/tmp/tar*
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
┌─────────────────────────────┬─────────────────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├─────────────────────────────┼─────────────────────────────┤
│Availability │SUNWcsu │
├─────────────────────────────┼─────────────────────────────┤
│CSI │Enabled │
├─────────────────────────────┼─────────────────────────────┤
│Interface Stability │Stable │
└─────────────────────────────┴─────────────────────────────┘
SEE ALSOar(1), basename(1), cd(1), chown(1), cpio(1), csh(1), dirname(1),
find(1), ls(1), mt(1), pax(1), setfacl(1), umask(1), mknod(1M),
vold(1M), archives.h(3HEAD), attributes(5), environ(5), fsattr(5),
largefile(5), mtio(7I)DIAGNOSTICS
Diagnostic messages are output for bad key characters and tape
read/write errors, and for insufficient memory to hold the link tables.
NOTES
There is no way to access the n-th occurrence of a file.
Tape errors are handled ungracefully.
When the Volume Management daemon is running, accesses to floppy
devices through the conventional device names (for example,
/dev/rdiskette) may not succeed. See vold(1M) for further details.
The tar archive format allows UIDs and GIDs up to 2097151 to be stored
in the archive header. Files with UIDs and GIDs greater than this value
will be archived with the UID and GID of 60001.
If an archive is created that contains files whose names were created
by processes running in multiple locales, a single locale that uses a
full 8-bit codeset (for example, the en_US locale) should be used both
to create the archive and to extract files from the archive.
Neither the r function letter nor the u function letter can be used
with quarter-inch archive tapes, since these tape drives cannot
backspace.
Since tar has no options, the standard "−−" argument that is normally
used in other utilities to terminate recognition of options is not
needed. If used, it is recognized only as the first argument and is
ignored.
Since −C directory file and −I include-file are multi-argument oper‐
ands, any of the following methods can be used to archive or extract a
file named −C or −I:
1. Specify them using file operands containing a / character on
the command line (such as /home/joe/−C or ./−I).
2. Include them in an include file with −I include-file.
3. Specify the directory in which the file resides:
-C directory -C
or
-C directory -I
4. Specify the entire directory in which the file resides:
-C directory .
SunOS 5.10 18 Mar 2006 tar(1)
