TAR(1) TAR(1)
tar - tape archiver
tar key [ arguments ] [ name ... ]
tar saves and restores multiple files on a single file (usually a
magnetic tape, but it can be any file). This single logical file may
span multiple physical tapes (this is known as "multi-volume tar"). Such
tapes do not have a filemark at the end of intermediate volumes, and an
archived file may be split across multiple tapes. The second through
last tape may be read without earlier tapes (aside from the possible
first file split across the tape boundary) by using the e option.
The key argument controls tar's actions. The key is a string of
characters containing at most one function letter and possibly one or
more function modifiers. Other arguments to tar are file or directory
names specifying which files to dump or restore. The order must match
the order of the matching options in key. In all cases, appearance of a
directory name refers (recursively) to the files and subdirectories of
that directory. These files are dumped to tape in alphabetical order.
If name is -, the list of files is read from the standard input.
In order to create a tar archive that is portable to as many types of
systems as possible, use the fixed block, non-byte swapped device.
Historically, a blocking factor of 20 (with any type of tape device)
would have been more portable, but with newer tapes this is not
necessarily true. If the tape drive is a SCSI tape at ID 7 on bus 0, the
following command would do this:
tar cOdbf 20 /dev/rmt/tps0d7ns filelist
If you know the other system has a POSIX compatible version of tar, omit
the O and d options.
To extract tapes from other systems, use the variable block device, if
the device supports it, with a large blocking factor, otherwise specify
the blocking factor with which the tape was made (usually 20 on non-IRIX
systems, if the b option was not specified):
tar xbf 512 /dev/rmt/tps0d7nsv
Or, for fixed block only devices, such as QIC tape drives:
tar xbf 20 /dev/rmt/tps0d7ns
Also see the notes at the b option below.
If the O option is specified the maximum pathlength--including the
filename itself-- is 99 characters (NAMSIZ) not including the stringterminating
NULL character, and any archives created with non-POSIX
Page 1
TAR(1) TAR(1)
standard versions of tar will also obey this length rule. Otherwise,
(the [default] POSIX format), pathnames are limited to 255 total
characters (not including the NULL), subject to several caveats
necessitated by the requirement of total backward compatibility with
previous versions of tar. Referring to /usr/include/tar.h, there are two
storage fields for filenames name, (100 chars) and prefix (156 chars).
If the entire pathname is 100 characters or less including the NULL, it
will be stored in the name field. Otherwise the pathname is split
between the two fields, with the restriction that an implicit (i.e.,
unstored) '/' character separates the prefix and name fields. Upon
extraction, the full pathname is constructed by concatenating these
fields with the added '/'. Because of this requirement, files whose
actual names (not including the leading path) exceed 99 characters cannot
be archived. If the split field is used, and the tape is read on older,
non-POSIX capable tar, the file will be extracted in the current
directory, since no leading pathname information is located in the older
location in the header; this at least allows the file to be extracted on
older systems, but if multiple files with the same final component are
extracted, the earlier will be overwritten by the later file(s).
If the file is a symbolic link the link-name must obey the above rules;
however, the total pathlength of the target file may not exceed NAMSIZ
characters in either POSIX or non-POSIX format. See /usr/include/tar.h
for more detail about these length values.
A tar archive is a stream of 512-byte header structures which may be
followed by file data rounded up to the next 512-byte boundary. The end
of the archive is signaled by two header structures beginning with null
bytes.
The function portion of the key is specified by one of the following
letters:
r Append the named files at the end of the archive. On tape, named
files are appended at the end of the last archive on tape. See the
NOTES section below, for drives that support this operation, and
other limitations.
u Update; put the named files at the end of the archive if they are
not currently in the archive, or if the file has been modified more
recently than the file in the archive. Note that if the pathnames
do not exactly match those already in the archive, the files will
always be appended (e.g., don't use absolute pathnames one time,
and absolute the next). The same restrictions as for the r
function apply as to which drives support this.
x Extract the named files from the tape. If a named file matches a
directory whose contents had been written onto the tape, this
directory is (recursively) extracted. The owner, modification
time, and mode are restored, subject to umask(2). If no file
argument is given, the entire content of the tape is extracted.
Note that if multiple entries specifying the same file are on the
Page 2
TAR(1) TAR(1)
tape, the last entry overwrites all earlier entries.
X For each file to be extracted, if it is identical to the file in
the corresponding position in the comparison tree, link the
existing file to the new file. Otherwise, extract the new file as
a separate new file. X is like x but also takes the next argument
as the root of a directory tree for comparison.
t List the names of the specified files each time they occur on the
tape. If no file argument is given, list all of the names on the
tape.
c Create a new tape; writing starts at the beginning of the tape
instead of after the last file. This option assumes that you are
at the beginning of the tape.
C Compare files on tape against existing files. For each specified
file, print a line with a key character followed by the file name.
L linked to an earlier file on the tape
S symbolic link
B block special file
C character special file
P named pipe
D directory
? can't read the disk file, so can't compare
> disk file doesn't exist
= files compare
! files don't compare
In addition to the letter which selects the function desired the
following characters may be used:
d On output, tar normally places information specifying owner and
modes of directories in the archive. Former versions of tar, when
encountering this information print error messages of the form:
``<name>/: cannot create''.
This option suppresses the printing of the directory information.
This option implies the D option.
D On output, tar normally places information specifying the owner,
modes, and device numbers of character and block special files and
named pipes (fifos) in the archive. Former versions of tar, when
encountering this information create an ordinary file of the same
name whose contents is the device number, in binary. This option
suppresses the special file information.
N When extracting files, extract the file only if it is new; that is,
if the stat(2) system call fails on the pathname that is about to
be extracted. When listing files with the t key, only list them if
they would be extracted (that is, the file doesn't exist).
Page 3
TAR(1) TAR(1)
p This option restores files to their original modes, ignoring the
present umask(2). Setuid and sticky information are also restored
to the super-user. This is the default when run as super-user.
v Normally tar does its work silently. The v (verbose) option make
tar print the name of each file it treats preceded by the function
letter. With the t function, the verbose option gives more
information about the tape entries than just their names.
w tar prints the action to be taken followed by file name, then waits
for user confirmation. If a word beginning with `y' is given, the
action is done. Any other input means do not do it.
f tar uses the next argument as the name of the archive instead of
/dev/tape. If the f argument is not given, and $TAPE is set in the
environment, then that value is used instead of the default. If
the name of the file is `-', 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 specified archive name can also reference a remote tape device.
A remote tape device name has the form:
[user@]system:/dev/???
where system is the remote system, /dev/??? is the particular drive
on the remote system (raw, rewinding, non-rewinding, etc.), and the
optional user is the login name to be used on the remote system; if
not given, normal rsh(1C) semantics apply.
Tar can also be used to move hierarchies on the local machine with
the command
cd fromdir; tar cBf - . | (cd todir && tar xBf -)
To move hierarchies between machines, use the command
cd fromdir; tar cBf - . | rsh remote "(cd todir && tar xBf -)"
where remote is the host name of the remote machine.
b tar uses the next argument as the blocking factor for tape records.
The default is to use the results of the MTIOCGETBLKSIZE ioctl for
tape when creating a tape (and for reading on fixed blocksize
devices, such as QIC) and to determine the blocksize (for variable
blocksize devices) when reading. See the output of
mt blksize
for this information; the "recommended" default for SCSI tape
devices is set in /var/sysgen/master.d/tpsc. This default blocking
factor may be large enough that some non-SGI systems will either
not be able to determine the blocking factor automatically when
reading the tape, (thus requiring the b option be specified when
reading the tape), or in rare cases, to not be able to read the
tape at all. In the latter case, the b option with a smaller value
must be specified when writing the tape.
Page 4
TAR(1) TAR(1)
A blocking factor of 1 is normally used with standard input and
standard output, and 20 for files or devices not supporting the
ioctl (such as remote tape). If the tape was written with a
blocking factor that does not exceed the limit for that device, the
block size is determined automatically when reading a tape for
devices with variable block size.
When reading from fixed blocksize devices, tar cannot determine the
blocking factor used when the tape was created. This may lead to
tar incorrectly deciding that the tape is a multi-volume tape, if
the blocking factor when reading is not an integral divisor of the
block size used when the tape was written. If this occurs on tapes
that you believe are not multi-volume, simply press RETURN at the
"change tape" prompt, and tar will complete normally.
Due to the blocking algorithm, a tar tape created by writing to the
standard output should be read from standard input (if on the same
system; if on a different system, it may be necessary to specify a
blocking factor).
l If it cannot resolve all of the links to the files dumped, tar
prints error messages. If l is specified, no error messages are
printed.
m Do not restore the modification times. The modification time will
be the time of extraction.
e Force tar to continue reading past tape errors. tar continues
until no more data is left, or read returns an error; unlike some
other versions of tar, it does not stop when it sees the tar
internal EOF record (512 bytes of 0's).
L Force tar to follow symbolic links as if they were normal files or
directories.
h Force tar to not follow symbolic links, but to instead place the
symbolic link information in the archive. This is the default.
B Force input and output blocking to 20 blocks per record, and cause
the input processing to ignore input record boundaries,
concatenating all input into a contiguous stream. This option
allows tar to work through pipes, networks, and other
communications channels where the record blocking may not be
maintained.
E On output exclude non-local files, as defined by the statvfs(2)
ST_LOCAL flag. This applies to files and directories on the
command line, as well as those found descending the directory tree.
When the L key is also given, symbolic links to non-local files or
directories are also skipped. No message is issued for skipped
files unless the v key is given more than once.
Page 5
TAR(1) TAR(1)
R When extracting from tape, ignore leading slashes on file names,
i.e., extract all files relative to the current directory. This
also applies (as of IRIX 6.2) to any links that are restored (and
symbolic links if specified as RR). When specified as RRR, all
filenames (including the targets of symbolic links) are made
directory relative; that is, they are extracted as ./filename.
This mode is intended for the use of programs running as root, such
as tardist, that want to be sure that they do not overwrite system
files when extracting archives, either by accident, or through a
trojan horse attack. Since the t,x and other options referring to
specific files use pattern matching, you must omit the leading '/'
when specifying directory or filenames with those options when
using the R option. Thus, to extract /a/b/c with a relative
pathname, you would do:
tar xvR a/b/c
Earlier releases prepended a leading '.', requiring the use of:
tar xvR ./a/b/c
The way to check for sure is to use:
tar tvR | head -2
and then use whichever format is used in the output list.
If specified as RRR, all directory information is stripped from
pathnames in the archive, including the pathnames of symbolic
links. All files will be written to the current directory; no
directories will be created; symbolic links will only refer to
files in the current directory. Note that if two or more different
files in the archive have the same filename but have different
pathnames, the last file extracted will overwrite any earlier file
with the same filename.
U For each file extracted, unlink existing file (if any).
O Write old tapes in an older (pre-IRIX 4.0) format, as opposed to
the POSIX format. This will not archive or extract files with
pathnames > 99 characters (not including the string-terminating
NULL character), and store user and group ids by value rather than
by name. In addition, special files will be archived so that they
may be interpreted correctly by previous releases of tar that
understand only the old format. (Previous releases of tar will
understand the POSIX format, but will interpret special files as
regular files.)
o By default, tar will chown files to the owner (and group) stored in
the archive when invoked by the superuser. This flag will prevent
this behavior, leaving the newly created files owned by root. This
flag is ignored when tar is not invoked by the superuser.
S Use pre-IRIX 4.0 behavior, so that tar will perform a chown to the
owner (and group) specified in the archive, regardless of whether
the -o flag is specified, or whether tar is invoked by superuser.
Page 6
TAR(1) TAR(1)
V Variable blocking; the last tape block will not be filled to the
blocking size. Note that this may prevent the archive from being
updated with r or u. This option also prevents the blocksize from
being set to 1 when `-' is used as the archive name (i.e., the b
option will be honored).
a Reset access times of input files after they have been copied to
the archive.
q Turn on debugging and extra error diagnostics. Supplying this flag
multiple times increases debugging level.
K Required for files larger than 2 Gigabytes. Tar will issue a
warning and skip such files if an attempt is made to archive them
without the K option. Mutually exclusive with the O option.
Warning: Use of this option may result in the creation of an
archive that is not portable to other machines.
F Skip files named core and errs, and subdirectories named SCCS. If
specified as FF, also skip files with the .o suffix, and files
named a.out.
M By default extended attributes are not archived or restored using
tar (see attr(1)). The -M option allows files ACL's, capability
sets and MAC labels to be archived. The -M option must be be
specified with either the 'c', 't', or 'x' options and should be
specified during both archiving and restoring. Note that restoring
file capability sets will require the process to have the
capability of CAP_SETFCAP in the effective set, and restoring file
MAC labels may require the additional capability of CAP_MAC_UPGRADE
or CAP_MAC_DOWNGRADE (see capabilities(4)).
If a file name is preceded by -C, then tar will perform a chdir(2) to
that file name. This allows multiple directories not related by a close
common parent to be archived using short relative path names. This
provides a method to get around the limitation of filename length; note
that some care must be used when extracting a backup created in this
manner. For example, to archive files from /usr/include and from /etc,
one might use
tar c -C /usr include -C / etc
If a file name of - is given on the command line when making an archive
then tar will read its standard input for a list of files to back up, one
per line; files will be dumped in list order. For example, to back up
all files that have changed in the last week, one might use:
find / -local ! -type d -mtime -7 -type f -print | tar ca -
Are intended to be self-explanatory. For diagnostics other than those
about options, tar uses the perror(3) library routine to provide the
cause of the error. The message `Read-only file system' usually
indicates an attempt to write on a write-protected device.
Page 7
TAR(1) TAR(1)
Tar will now attempt to recognize byte swapped tapes, and will report
them with a message similar to:
tar: directory checksum error
tar: this appears to be a byte-swapped archive
In this case, if the byte swapping device is being used to read the tape,
the non-byteswapping device should be used instead, or vice-versa. If
the interface doesn't support driver byte swapping (as is typical on
non-SGI systems), a command similar to this should be used (with the
appropriate blocking factor):
dd if=/dev/rmt/tapedevice bs=20b conv=swab | tar vtf -
There is no way to ask for the n-th occurrence of a file.
The u option can be slow.
The data for a file with multiple links is output to tape with the first
link encountered. Thus, an attempt to extract a subsequent link by
itself will not have the desired result.
For the r and u options to work on multi-tapefile tapes (multiple
independent tar archives on the same tape). the tape must be positioned
to the last tapefile on the tape. This would typically be done with a
sequence such as:
mt feom; mt bsf 2; mt fsf 1; tar c ...
For multi-tapefile tapes there is no guarantee that after reading a
tapefile (c or t option) non-rewinding tape is positioned at the FM. In
this case, immediate execution of another tar may not succeed in reading
the next tapefile from the tape. One may need to use mt to position the
tape to the next tapefile before executing the next tar read. The surest
way to guarantee the position of the tape is to use mt rewind and mt fsf
to position the tape to the desired file before proceeding with the next
tar tapefile read.
The r and u options currently work only on tape drives that support the
MTAFILE ioctl; currently only 9 track and DAT (of the drives supported by
SGI) support this (see the MTCAN_APPEND capability for SCSI tape devices,
in /var/sysgen/master.d/tpsc). They are not supported on any variety of
quarter inch cartridge tape drive or on the Exabyte 8mm tape drive,
because the drive hardware does not allow this function to be
implemented, as they do not support data overwrite. These options are
supported on archives that are normal files, with the restriction that
the blocking factor must be the same when appending as when the archive
was created.
Since tar uses the MTBSR ioctl (for devices) to backspace over the last
Page 8
TAR(1) TAR(1)
record when appending, the blocksize used when updating must be the same
as that when creating the tape. In addition, if the fixed blocksize
device is being used (with SCSI tapes), the blocksize must be 1, in order
for the algorithm to work correctly.
If you open a remote tape device and receive an I/O error, it is possible
that the remote tape interface program is obsolete and not compatible
with the remote tape subroutine library that tar uses. It may also be
the case that shell startup files on the remote do output to the
terminal; see the notes on this on the rsh(1) man page (remote shell, not
restricted shell).
/dev/tape, /dev/tapens, /dev/rmt/*, /tmp/tar* (for r and u options).
$TAPE if set, is used instead of /dev/tape as the default when f not
given.
mtio(7), tps(7m), mt(1), attr(1), xfsdump(1m).
PPPPaaaaggggeeee 9999 [ Back ]
|
