 |
Index for Section 1 |
|
 |
Alphabetical listing for T |
|
tar(1)
NAME
tar - Manipulates tape archives
SYNOPSIS
tar function_key[bBfFEhilLmpPsSvVwzn] [n|o] [option_argument...] [-e
exception]... [-C directory]... [file...]
tar -function_key[options] [option_argument]... [n|o] [option_argument...]
[-e exception]... [-C directory]... [file...]
The tar command saves and restores multiple files on a single file (usually
a magnetic tape, but it can be any file).
Note
[Compaq] The syntax of the tar command has recently changed. The
minus sign (-) at the beginning of a key/option set is no longer
optional. If tar sees a minus sign in front of an option that
requires an argument, tar expects the argument to follow the option
immediately. In order to use the original tar syntax in existing
scripts, you must remove the minus sign if more than one option
requiring an argument is given. Consider this command in the old
form:
tar -xbfp 20 /dev/rmt1h
Under the new implementation, this command becomes
tar xbfp 20 /dev/rmt1h
or
tar -xb 20 -f /dev/rmt1h -p
STANDARDS
Interfaces documented on this reference page conform to industry standards
as follows:
tar: XPG4, XPG4-UNIX
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
FUNCTION KEYS
[Compaq] The function performed by tar is specified by one of the
following key letters:
c Creates a new archive. When writing to a tape device, tar begins from
the current tape position.
r Writes the named files at the end of the specified archive. If the
archive is on tape, tar expects that the tape is currently positioned
to the beginning of the archive.
t Lists the contents of the archive. If the file argument does not
restrict the operation to one or more specific directories or files,
tar lists all of the file names in the archive.
u Adds the named files to the tape, if the files are not already there or
if they were modified since last copied to the tape.
x Extracts the named files from the tape. If a named file matches a
directory whose contents were written to the tape, this directory is
(recursively) extracted. The owner, modification time, and mode are
restored (if possible). If no file argument is given, the entire
content of the tape is extracted. If multiple entries specifying the
same file are on the tape, the last one overwrites all earlier ones.
OPTIONS
[Compaq] The following options can be used with function keys:
b The tar command uses the next argument as the blocking factor for tape
records. The default is 20 (larger values can be specified at the risk
of creating a tape archive that some systems' tape drives might not be
able to restore). Use this option only with raw magnetic tape
archives. The block size is determined automatically when reading tapes
(key letters x and t).
B [Compaq] Forces input and output blocking to the blocking factor (see
the b option). The B option exists so that tar can work across a
communications channel where the blocking cannot be maintained.
e [Compaq] The tar command uses the next argument, exception, as the
name of the file to be excluded from the archive.
E Processes extended headers, allowing you to archive or extract extended
UIDs and GIDs, long filenames, link-names, large files, and long user
and group names
f The tar command uses the next argument as the name of the archive
instead of /dev/rmtnh. (See the entry for the n option.) If the name of
the file is - (dash), tar writes to standard output or reads from
standard input, whichever is appropriate. Thus, tar can be used as the
head or tail of a filter chain. The tar utility can also be used to
move hierarchies with the command:
cd fromdir; tar cf - . | (cd todir; tar xpf -)
F [Compaq] Checks certain file names before archiving. Source Code
Control System (SCCS), Revision Control System (RCS), files named core,
errs, a.out, and files ending in .o are not archived.
h [Compaq] Forces tar to follow symbolic links as if they were normal
files or directories. Normally, tar does not follow symbolic links,
but instead saves the link text in the archive.
i [Compaq] Ignores checksum errors. The tar command writes a file
header containing a checksum for each file in the archive. When this
option is not specified, the system verifies the contents of the header
blocks by recomputing the checksum and stops with a directory checksum
error when a mismatch occurs. When this option is specified, tar logs
the error and then scans forward until it finds a valid header block.
This permits restoring files from later volumes of a multivolume
archive without reading earlier volumes.
l [Compaq] Tells tar to complain if it cannot resolve all of the links
to the files dumped. If this option is not specified, no error
messages are printed.
L [Compaq] Tries to create a symbolic link if tar is unsuccessful in its
attempt to link (hard link) two files.
m Tells tar not to restore the modification times. The modification time
is the time of extraction. This is always the case with symbolic
links.
n [Compaq] Allows tar headers to be created with file names that cannot
be null-terminated if they are exactly the maximum length (as specified
in POSIX). This option is mutually exclusive with the o option (that
is, new versus old). When specified, each of these options turns off
the other; neither option is turned on by default, however.
o The o option is provided for backward compatibility. Specify this
option if the archive is to be restored on a system with an older
version of tar. On output, tar normally places information specifying
owner and modes of directories in the archive. Former versions of tar,
when encountering this information will give an error message of the
following form:
name: cannot create
[Compaq] This option suppresses the directory information. It also
prevents archiving special files and FIFOs that earlier versions of tar
would not be able to extract properly. (Although anyone can archive
special files, who has superuser authority can extract them from the
archives.)
When o is used for reading, it causes the extracted file to take on the
User and Group ID (UID and GID) of the user running the program, rather
than those of the tape. This is the default for the ordinary user.
[Compaq] This option is mutually exclusive with the n option (that is,
new vs. old). When specified, each of these options turns off the
other; neither option is turned on by default, however.
p [Compaq] Restores files to their original modes, ignoring the present
umask. Set-user-ID and sticky information will also be restored if the
user is superuser.
P [Compaq] Specifies the prefix that is to be stripped off of the file
names archived to or extracted from tape. (See also the s option.)
s [Compaq] Tells tar to strip off any leading slashes from pathnames
during extraction. This is useful when restoring a tape that was
created on a system with a different file system structure. (See also
the P option.)
R [Compaq] The named file immediately following this option contains a
list of file names separated by newlines. This list is added to (c
function key, r function key) or extracted from (x function key) the
archive. The -R option is incompatible with the -C option.
S blocksb | feet[@density]
[Compaq] Specifies the number of 512-byte blocks per volume (first
form), independent of the tape blocking factor. You can also specify
the size of the tape in feet, and optionally density, by using the
second form. Feet are assumed to be 11 inches long to be conservative.
This option lets you deal more easily with multivolume tape archives,
where tar must be able to determine how many blocks fit on each volume.
[Compaq] Tape drives vary in density capabilities. The density
argument is used in the amount of data that tar can fit on a tape.
v Normally tar does its work silently. The v (verbose) option makes tar
print the name of each file it processes as specified by the function
key. With the t function key, the verbose option gives more
information about the tape entries than just their names.
V [Compaq] Prevents any extended attributes from being archived with
associated files. This option is particularly useful for archiving
files that are to be restored with previous versions of tar and cpio.
w Causes tar to print the action to be taken followed by the name of the
file, and then to wait for the user's confirmation. If a word
beginning with y, or the locale's definition of an affirmative
response, is given, the action is performed. If any other input is
given, the action is not performed.
z [Compaq] Positions the tape after the EOF marker on extraction or
listing. The z option lets the user extract or list tapes that have
multiple archives on them one after the other without error as a result
of the tape not being positioned correctly for the next extraction or
listing.
n [Compaq] Selects /dev/rmtnh (the variable n means 0-9) as the tape
drive on which the tape is mounted. The default is drive 0
(/dev/rmt0h).
e [Compaq] Adds the following argument to a list of exception strings
that prevent files whose names match exactly from being archived. When
used with the -C option, the list of exceptions becomes relative to
each new directory.
C [Compaq] If a file name is preceded by -C, tar performs a chdir() to
that file name. This allows multiple directories not related by a
close common parent to be archived using short relative pathnames. For
example, to archive files from /usr/include and from /etc, one might
use the following command line:
tar c -C /usr/include . -C /etc .
[Compaq] Therefore, if you do not specify an absolute file name, the
file name is considered relative to the previous -C directory. When
you specify this option multiple times on the command line, make sure
to specify subsequent -C directories relative to the preceding -C
directories.
[Compaq] If an error occurs while trying to change to the requested
directory, subsequent file names on the command line that are not
absolute (that is, have no leading / (slash)) are skipped until the
next -C option is specified.
[Compaq] Only the -e and -C options must be preceded by a - (dash) and can
be specified more than once on a single command line or interspersed within
the list of file names. All other options must be specified together (with
no separating spaces) before -e, -C, and the file list. For all options
that require arguments, the arguments must follow the string of options and
be ordered in the same way as the specified options.
[Compaq] Previous restrictions on the tar command's ability to properly
handle blocked archives have been lifted.
DESCRIPTION
The tar command is used to save and restore data from traditional format
tar archives.
The actions of the tar command are controlled by a string containing, at
most, one function key and possibly one or more options. Other arguments
to tar are file or directory names specifying which files to dump or
restore. In all cases, appearance of a directory name refers to the files
and (recursively) subdirectories of that directory.
The LC_MESSAGES variable determines the locale's equivalent of y or n (for
yes/no responses).
NOTES
1. [Compaq] There is no way to ask for the nth occurrence of a file.
2. [Compaq] Tape errors are handled ungracefully.
3. [Compaq] The u function can be slow.
4. [Compaq] The current limit on file name length is 256 bytes. The
current limit on file links (hard or soft) is 100 bytes.
5. [Compaq] There is no way selectively to follow symbolic links.
6. [Compaq] When extracting tapes created with the r or u functions,
directory modification times might not be set correctly.
7. [Compaq] After encountering tape write errors, tar queries the
operator about performing a rewrite. If the operator requests a
rewrite, a rewind is performed, followed by an attempt to rewrite the
data. In the event the no-rewind device is used, the user should
always load a new tape to avoid the possibility of overwriting
previously written archives.
EXIT STATUS
The following exit values are returned:
0 Successful completion.
>0 An error occurred.
EXAMPLES
1. To create a tar archive to device /dev/rmt12, enter:
tar cvfb /dev/rmt12 20 -e ./foo -C /usr/glenn . \
-e ./bar -e ./logs/logfile -C /usr/gaston .
The preceding command line specifies a blocking factor of 20. The
resulting archive contains all files and directories in /usr/glenn
except for file ./foo and all files and directories in /usr/gaston
except for files ./foor, ./bar, and ./logs/logfile.
2. To create a tar archive as a disk file, enter:
tar cvf /tmp/mybackup.tar -e $HOME/zeugma $HOME
The preceding command line uses the f option to create a tar archive
named mybackup.tar in the /tmp directory. The archive contains the
user's home directory and its contents, including all subdirectories
and files except the zeugma subdirectory and its contents, which are
excluded by the -e (exception) option.
ENVIRONMENT VARIABLES
The following environment variables affect the execution of tar:
LANG
Provides a default value for the internationalization variables that
are unset or null. If LANG is unset or null, the corresponding value
from the default locale is used. If any of the internationalization
variables contain an invalid setting, the utility behaves as if none of
the variables had been defined.
LC_ALL
If set to a non-empty string value, overrides the values of all the
other internationalization variables.
LC_CTYPE
Determines the locale for the interpretation of sequences of bytes of
text data as characters (for example, single-byte as opposed to
multibyte characters in arguments).
LC_MESSAGES
Determines the locale for the format and contents of diagnostic
messages written to standard error.
LC_TIME
Determines the format of date and time strings output when listing the
contents of an archive.
NLSPATH
Determines the location of message catalogs for the processing of
LC_MESSAGES.
TZ Determines the time zone used with date and time strings.
FILES
/dev/rmtnh
Device name used with the n option.
/tmp/tar*
Temporary file used with the u function.
SEE ALSO
Commands: cpio(1), pax(1)
Functions: chdir(2), umask(2)
Files: tar(4)
Standards: standards(5)