Tribblix: manual page: tar.1

TAR(1) User Commands TAR(1)

NAME

tar - create tape archives and add or extract files

SYNOPSIS

tar c[BDeEFhilnopPTvw@/[0-7]][bf][X...][a|j|J|z|Z] [blocksize]
[tarfile] [size] [exclude-file]...
{file | -I include-file | -C directory file}...

tar r[BDeEFhilnTvw@/[0-7]][bf][j|J|z|Z] [blocksize] [tarfile]
[size]
{file | -I include-file | -C directory file}...

tar t[BeFhilnTv[0-7]][f][X...][j|J|z|Z] [tarfile] [size]
[exclude-file]... {file | -I include-file}...

tar u[BDeEFhilnTvw@/[0-7]][bf][j|J|z|Z] [blocksize] [tarfile]
[size] file...

tar x[BeFhilmnopTvw@/[0-7]][f][X...][j|J|z|Z] [tarfile] [size]
[exclude-file]... [-C directory] [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
(recursively) 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.

This option may also be passed once to x (extract). In this case
the program will chdir to directory after opening the archive,
but before extracting its contents.

-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) is 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 is 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 (recursively) subdirectories of
that directory.

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 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 can 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 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
specified, the names of all files and any associated extended
attributes 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 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
written 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. Character-special and block-special devices (created by
mknod(8)) can only be extracted by the super-user. If no file
argument is specified, 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 can 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 can be used in conjunction with the letter that
selects the desired function.

a

During a create operation autodetect compression based on the
archive suffix.

b blocksize

Blocking Factor. Use when reading or writing to raw magnetic
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(4I) for details.) The maximum
cannot exceed INT_MAX/512 (4194303).

When a tape archive is being read, its actual blocking factor is
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 results. See Example 5 in EXAMPLES.

B

Block. Force tar to perform multiple reads (if necessary) 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.

D

Data change warnings. Used with c, r, or u function letters.
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 is still
written, but the exit status is not affected.

e

Error. Exit immediately with a positive exit status if any
unexpected errors occur.

E

Write a tarfile with extended headers. (Used with c, r, or u
function letters. Ignored with t or x function letters.) When a
tarfile is written with extended headers, the modification 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 uses the device indicated by the TAPE environment variable,
if set. Otherwise, tar uses 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, 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 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.

h

Follow symbolic links as if they were normal files or
directories. Normally, tar does not follow symbolic links.

i

Ignore directory checksum errors.

j

Use bzip2 for compressing or decompressing the archives.

J

Use xz for compressing or decompressing the archives.

l

Link. Output error message if unable to resolve all links to the
files being archived. If l is not specified, 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 takes on the group and user identifiers 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
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 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.

T

This modifier is only available if the system is configured 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 sensitivity label
specified in the archive equals the sensitivity 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 relative 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 archives from
Trusted Solaris 8. Only sensitivity labels, and multi-level
directory specifications are interpreted. Privilege
specifications and audit attribute flags are silently ignored.
Multilevel directory specifications 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 additional 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; otherwise, 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 containing 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) is used to match against the
initial string of files to exclude. Lines in the exclude file are
matched exactly, so an entry like "/var" does not exclude the
/var directory if tar is backing up relative 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" does 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 can 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 is
excluded.

z

Use gzip for compressing or decompressing the archives.

Z

Use compress for compressing or decompressing the archives.

@

Include extended attributes in archive. By default, tar does not
place extended attributes in the archive. With this flag, tar
looks 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 special 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.

/

Include extended system attributes in archive. By default, tar
does not place extended system attributes in the archive. With
this flag, tar looks for extended system attributes on the files
to be placed in the archive and adds them to the archive.
Extended system attributes go in the archive as special files
with a special type label. When this modifier is used with the x
function, extended system attributes are extracted from the tape
along with the normal file data. Extended system 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(7) 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 can 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
special 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 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 following
command:

example% tar tvf /dev/rmt/0

The output is 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 can 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 multiple 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%

Notice 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(4I) 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
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: 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
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 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
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

See environ(7) for descriptions of the following environment
variables that affect the execution of tar: LC_COLLATE, LC_CTYPE,
LC_MESSAGES, LC_TIME, TZ, and NLSPATH.

Affirmative responses are processed using the extended regular
expression defined for the yesexpr keyword in the LC_MESSAGES
category of the user's locale. The locale specified in the LC_COLLATE
category defines the behavior of ranges, equivalence classes, and
multi-character collating elements used in the expression defined for
yesexpr. The locale specified in LC_CTYPE determines the locale for
interpretation of sequences of bytes of text data a characters, the
behavior of character classes used in the expression defined for the
yesexpr. See locale(7).

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 might 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

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.

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 is 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
operands, 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 .

April 14, 2016 TAR(1)