tar(1) manual page
Table of Contents
tar - create tape archives and add or extract files
tar
c [bBefFhiloPvwX [ 0-7 ]] [ block ] [ tarfile ] [ exclude-file ] { -I include-file
| -C directory file | file } ...
tar r [ bBefFhilvw [ 0-7 ]] [ block ] {
-I include-file | -C directory file | file } ...
tar t [ BefFhilvX [ 0-7 ]] [ tarfile
] [ exclude-file ] { -I include-file | file } ...
tar u [ bBefFhilvw [ 0-7
]] [ block ] [ tarfile ] file ...
tar x [ BefFhilmopvwX [ 0-7 ]] [ tarfile
] [ exclude-file ] [ file ... ]
SUNWcsu
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.
The following options are supported:
- -I include-file
- Open include-file
containing a list of files, one per line, and treat as if each file appeared
separately on the command line. Be careful of trailing white spaces. 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
- Perform a chdir (see cd(1)
) operation on directory
and perform 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 directories not related by a close
common parent.
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 directory. The directory portion of file (see dirname(1)
)
cannot exceed 155 characters. The file name portion (see basename(1)
) cannot
exceed 100 characters.
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.
- 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.
- 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 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(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 gatar tf... /dev/rmt/0 | grep
’pattern’ga
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 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.
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.)
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 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 Example 5 in EXAMPLES below.
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 special devices, among others, but is intended principally
for tape devices.
- 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.
- e
- Error. Exit immediately with a positive exit
status if any unexpected errors occur.
- 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 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.
- 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.
- 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
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)
.
SETUID
and sticky information are also extracted for the super-user. 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 versions of tar.
- P
- Suppress the addition
of a trailing "/" on directory entries in the archive.
- 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 first keystroke is y, 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. Multiple 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.
.- 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 will be similar to the following:
rw-r--r-- 1677/40 2123 Nov 7 18:15 1985 ./test.c
...
example%
The columns have the following meanings:
· column 1 is the access permissions
to ./test.c
· column 2 is the user-id/group-id of ./test.c
· column 3 is the size of ./test.c in bytes
· column 4 is the modification date of ./test.c
· column 5 is the name of ./test.c
To extract files from the archive:
example% tar xvf /dev/rmt/0messages from tarexample%
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 tapemessages from
tarexample% tar xvfp /dev/rmt/0n read second archive from tapemessages from
tarexample%
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.
.- 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.hand all the other files in /usr/include ..../chownand
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...
.- The following is an example using tar to transfer files across the Ethernet.
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 tarexample%
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.
.- 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.
.
- 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
See environ(5)
for descriptions of the following environment
variables that affect the execution of tar: LC_COLLATE
, LC_CTYPE
, LC_MESSAGES
,
LC_TIME
, TZ
, and NLSPATH
.
The following exit values are returned:
- Successful completion.
- >0
- An error occurred.
- /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*
ar(1)
, basename(1)
, cd(1)
, chown(1)
,
cpio(1)
, csh(1)
, dirname(1)
, ls(1)
, mt(1)
, pax(1)
, setfacl(1)
, umask(1)
,
mknod(1M)
, vold(1M)
, environ(5)
, mtio(7I)
Diagnostic messages
are output for bad key characters and tape read/write errors, and for insufficient
memory to hold the link tables.
There is no way to access for 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 UID
s and GID
s up to
2097151 to be stored in the archive header. Files with UID
s and GID
s greater
than this value will be archived with the UID
and GID
of 60001.
Table of Contents
![[Go to CFHT Home Page]](/images/cfht-icon.gif){kind=icon}
Man Pages 
Back to Software Index 
Manpage Top Level