home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
ftp.shrubbery.net
/
2015-02-07.ftp.shrubbery.net.tar
/
ftp.shrubbery.net
/
pub
/
pc
/
unix
/
tar4dos.exe
/
TAR.DOC
< prev
next >
Wrap
Text File
|
1990-08-23
|
26KB
|
539 lines
.nf
TAR(1) USER COMMANDS TAR(1)
NAME
tar - tape (or other media) file archiver
SYNOPSIS
tar -[BcdDhiklmopRstvxzZ] [-b N] [-f F] [-T F] [ filename or
regexp ... ]
DESCRIPTION
tar provides a way to store many files into a single
archive, which can be kept in another Unix file, stored on
an I/O device such as tape, floppy, cartridge, or disk, sent
over a network, or piped to another program. It is useful
for making backup copies, or for packaging up a set of files
to move them to another system.
tar has existed since Version 7 Unix with very little
change. It has been proposed as the standard format for
interchange of files among systems that conform to the IEEE
P1003 ``Portable Operating System'' standard.
This version of tar supports some of the extensions which
were proposed in the P1003 draft standards, including owner
and group names, and support for named pipes, fifos, con-
tiguous files, and block and character devices.
When reading an archive, this version of tar continues after
finding an error. Previous versions required the `i' option
to ignore checksum errors.
OPTIONS
tar options can be specified in either of two ways. The
usual Unix conventions can be used: each option is preceded
by `-'; arguments directly follow each option; multiple
options can be combined behind one `-' as long as they take
no arguments. For compatability with the Unix tar program,
the options may also be specified as ``keyletters,'' wherein
all the option letters occur in the first argument to tar,
with no `-', and their arguments, if any, occur in the
second, third, ... arguments. Examples:
Normal: tar -f arcname -cv file1 file2
Old: tar fcv arcname file1 file2
At least one of the -c, -t, -d, or -x options must be
included. The rest are optional.
Files to be operated upon are specified by a list of file
names, which follows the option specifications (or can be
read from a file by the -T option). Specifying a directory
name causes that directory and all the files it contains to
be (recursively) processed. If a full path name is
specified when creating an archive, it will be written to
the archive without the initial "/", to allow the files to
be later read into a different place than where they were
dumped from, and a warning will be printed. If files are
extracted from an archive which contains full path names,
they will be extracted relative to the current directory and
a warning message printed.
When extracting or listing files, the ``file names'' are
treated as regular expressions, using mostly the same syntax
as the shell. The shell actually matches each substring
between ``/''s separately, while tar matches the entire
string at once, so some anomalies will occur; e.g. ``*'' or
``?'' can match a ``/''. To specify a regular expression as
an argument to tar, quote it so the shell will not expand
it.
-b N Specify a blocking factor for the archive. The block
size will be N x 512 bytes. Larger blocks typically
run faster and let you fit more data on a tape. The
default blocking factor is set when tar is compiled,
and is typically 20. There is no limit to the maximum
block size, as long as enough memory can be allocated
for it, and as long as the device containing the
archive can read or write that block size.
-B When reading an archive, reblock it as we read it.
Normally, tar reads each block with a single read(2)
system call. This does not work when reading from a
pipe or network socket under Berkeley Unix; read(2)
only gives as much data as has arrived at the moment.
With this option, it will do multiple read(2)s to fill
out to a record boundary, rather than reporting an
error. This option is default when reading an archive
from standard input, or over a network.
-c Create an archive from a list of files.
-d Diff an archive against the files in the file system.
Reports differences in file size, mode, uid, gid, and
contents. If a file exists on the tape, but not in the
file system, that is reported. This option needs
further work to be really useful.
-D When creating an archive, only dump each directory
itself; don't dump all the files inside the directory.
In conjunction with find(1), this is useful in creating
incremental dumps for archival backups, similar to
those produced by dump(8).
-f F Specify the filename of the archive. If the specified
filename is ``-'', the archive is read from the
standard input or written to the standard output. If
the -f option is not used, and the environment variable
TAPE exists, its value will be used; otherwise, a
default archive name (which was picked when tar was
compiled) is used. The default is normally set to the
``first'' tape drive or other transportable I/O medium
on the system.
If the filename contains a colon before a slash, it is
interpreted as a ``hostname:/file/name'' pair. tar
will invoke the commands rsh and dd to access the
specified file or device on the system hostname. If
you need to do something unusual like rsh with a dif-
ferent user name, use ``-f -'' and pipe it to rsh manu-
ally.
-h When creating an archive, if a symbolic link is encoun-
tered, dump the file or directory to which it points,
rather than dumping it as a symbolic link.
-i When reading an archive, ignore blocks of zeros in the
archive. Normally a block of zeros indicates the end
of the archive, but in a damaged archive, or one which
was created by appending several archives, this option
allows tar to continue. It is not on by default
because there is garbage written after the zeroed
blocks by the Unix tar program. Note that with this
option set, tar will read all the way to the end of the
file, eliminating problems with multi-file tapes.
-k When extracting files from an archive, keep existing
files, rather than overwriting them with the version
from the archive.
-l When dumping the contents of a directory to an archive,
stay within the local file system of that directory.
This option only affects the files dumped because they
are in a dumped directory; files named on the command
line are always dumped, and they can be from various
file systems. This is useful for making ``full dump''
archival backups of a file system, as with the dump(8)
command. Files which are skipped due to this option
are mentioned on the standard error.
-m When extracting files from an archive, set each file's
modified timestamp to the current time, rather than
extracting each file's modified timestamp from the
archive.
-o When creating an archive, write an old format archive,
which does not include information about directories,
pipes, fifos, contiguous files, or device files, and
specifies file ownership by uid's and gid's rather than
by user names and group names. In most cases, a
``new'' format archive can be read by an ``old'' tar
program without serious trouble, so this option should
seldom be needed.
-p When extracting files from an archive, restore them to
the same permissions that they had in the archive. If
-p is not specified, the current umask limits the per-
missions of the extracted files. See umask(2).
-R With each message that tar produces, print the record
number within the archive where the message occurred.
This option is especially useful when reading damaged
archives, since it helps to pinpoint the damaged sec-
tion.
-s When specifying a list of filenames to be listed or
extracted from an archive, the -s flag specifies that
the list is sorted into the same order as the tape.
This allows a large list to be used, even on small
machines, because the entire list need not be read into
memory at once. Such a sorted list can easily be
created by running ``tar -t'' on the archive and edit-
ing its output.
-t List a table of contents of an existing archive. If
file names are specified, just list files matching the
specified names. The listing appears on the standard
output.
-T F Rather than specifying file names or regular expres-
sions as arguments to the tar command, this option
specifies that they should be read from the file F, one
per line. If the file name specified is ``-'', the
list is read from the standard input. This option, in
conjunction with the -s option, allows an arbitrarily
large list of files to be processed, and allows the
list to be piped to tar.
-v Be verbose about the files that are being processed or
listed. Normally, archive creation, file extraction,
and differencing are silent, and archive listing just
gives file names. The -v option causes an ``ls
-l''-like listing to be produced. The output from -v
appears on the standard output except when creating an
archive (since the new archive might be on standard
output), where it goes to the standard error output.
-x Extract files from an existing archive. If file names
are specified, just extract files matching the speci-
fied names, otherwise extract all the files in the
archive.
-z or -Z
The archive should be compressed as it is written, or
decompressed as it is read, using the compress(1) pro-
gram. This option works on I/O devices and over the
network, as well as on disk files; data to or from such
devices is reblocked using a ``dd'' command to enforce
the specified (or default) block size. The default
compression parameters are used; if you need to over-
ride them, avoid the ``z'' option and compress it your-
self.
SEE ALSO
shar(1), tar(5), compress(1), ar(1), arc(1), cpio(1),
dump(8), restore(8), restor(8), rsh(1), dd(1), find(1)
BUGS
The r, u, w, X, l, F, C, and digit options of Unix tar are
not supported.
Multiple-tape (or floppy) archives should be supported, but
so far no clean way has been implemented.
A bug in the Bourne Shell usually causes an extra newline to
be written to the standard error when using compressed or
remote archives.
A bug in ``dd'' prevents turning off the ``x+y records
in/out'' messages on the standard error when ``dd'' is used
to reblock or transport an archive.
TAR(5) FILE FORMATS TAR(5)
NAME
tar - tape (or other media) archive file format
DESCRIPTION
A ``tar tape'' or file contains a series of records. Each
record contains TRECORDSIZE bytes (see below). Although
this format may be thought of as being on magnetic tape,
other media are often used. Each file archived is
represented by a header record which describes the file,
followed by zero or more records which give the contents of
the file. At the end of the archive file there may be a
record filled with binary zeros as an end-of-file indicator.
A reasonable system should write a record of zeros at the
end, but must not assume that an end-of-file record exists
when reading an archive.
The records may be blocked for physical I/O operations.
Each block of N records (where N is set by the -b option to
tar) is written with a single write() operation. On mag-
netic tapes, the result of such a write is a single tape
record. When writing an archive, the last block of records
should be written at the full size, with records after the
zero record containing all zeroes. When reading an archive,
a reasonable system should properly handle an archive whose
last block is shorter than the rest, or which contains gar-
bage records after a zero record.
The header record is defined in the header file <tar.h> as
follows:
/*
* Standard Archive Format - Standard TAR - USTAR
*/
#define RECORDSIZE 512
#define NAMSIZ 100
#define TUNMLEN 32
#define TGNMLEN 32
union record {
char charptr[RECORDSIZE];
struct header {
char name[NAMSIZ];
char mode[8];
char uid[8];
char gid[8];
char size[12];
char mtime[12];
char chksum[8];
char linkflag;
char linkname[NAMSIZ];
char magic[8];
char uname[TUNMLEN];
char gname[TGNMLEN];
char devmajor[8];
char devminor[8];
} header;
};
/* The checksum field is filled with this while the checksum is computed. */
#define CHKBLANKS " " /* 8 blanks, no null */
/* The magic field is filled with this if uname and gname are valid. */
#define TMAGIC "ustar " /* 7 chars and a null */
/* The linkflag defines the type of file */
#define LF_OLDNORMAL '\0' /* Normal disk file, Unix compatible */
#define LF_NORMAL '0' /* Normal disk file */
#define LF_LINK '1' /* Link to previously dumped file */
#define LF_SYMLINK '2' /* Symbolic link */
#define LF_CHR '3' /* Character special file */
#define LF_BLK '4' /* Block special file */
#define LF_DIR '5' /* Directory */
#define LF_FIFO '6' /* FIFO special file */
#define LF_CONTIG '7' /* Contiguous file */
/* Further link types may be defined later. */
/* Bits used in the mode field - values in octal */
#define TSUID 04000 /* Set UID on execution */
#define TSGID 02000 /* Set GID on execution */
#define TSVTX 01000 /* Save text (sticky bit) */
/* File permissions */
#define TUREAD 00400 /* read by owner */
#define TUWRITE 00200 /* write by owner */
#define TUEXEC 00100 /* execute/search by owner */
#define TGREAD 00040 /* read by group */
#define TGWRITE 00020 /* write by group */
#define TGEXEC 00010 /* execute/search by group */
#define TOREAD 00004 /* read by other */
#define TOWRITE 00002 /* write by other */
#define TOEXEC 00001 /* execute/search by other */
All characters in header records are represented using 8-bit
characters in the local variant of ASCII. Each field within
the structure is contiguous; that is, there is no padding
used within the structure. Each character on the archive
medium is stored contiguously.
Bytes representing the contents of files (after the header
record of each file) are not translated in any way and are
not constrained to represent characters or to be in any
character set. The tar(5) format does not distinguish text
files from binary files, and no translation of file contents
should be performed.
The fields name, linkname, magic, uname, and gname are
null-terminated character strings. All other fields are
zero-filled octal numbers in ASCII. Each numeric field (of
width w) contains w-2 digits, a space, and a null, except
size and mtime, which do not contain the trailing null.
The name field is the pathname of the file, with directory
names (if any) preceding the file name, separated by
slashes.
The mode field provides nine bits specifying file permis-
sions and three bits to specify the Set UID, Set GID and
Save Text (TSVTX) modes. Values for these bits are defined
above. When special permissions are required to create a
file with a given mode, and the user restoring files from
the archive does not hold such permissions, the mode bit(s)
specifying those special permissions are ignored. Modes
which are not supported by the operating system restoring
files from the archive will be ignored. Unsupported modes
should be faked up when creating an archive; e.g. the group
permission could be copied from the `other' permission.
The uid and gid fields are the user and group ID of the file
owners, respectively.
The size field is the size of the file in bytes; linked
files are archived with this field specified as zero.
The mtime field is the modification time of the file at the
time it was archived. It is the ASCII representation of the
octal value of the last time the file was modified,
represented as in integer number of seconds since January 1,
1970, 00:00 Coordinated Universal Time.
The chksum field is the ASCII representaion of the octal
value of the simple sum of all bytes in the header record.
Each 8-bit byte in the header is treated as an unsigned
value. These values are added to an unsigned integer, ini-
tialized to zero, the precision of which shall be no less
than seventeen bits. When calculating the checksum, the
chksum field is treated as if it were all blanks.
The typeflag field specifies the type of file archived. If
a particular implementation does not recognize or permit the
specified type, the file will be extracted as if it were a
regular file. As this action occurs, tar issues a warning
to the standard error.
LF_NORMAL or LF_OLDNORMAL
represents a regular file. For backward compatibility,
a typeflag value of LF_OLDNORMAL should be silently
recognized as a regular file. New archives should be
created using LF_NORMAL. Also, for backward compata-
bility, tar treats a regular file whose name ends with
a slash as a directory.
LF_LINK
represents a file linked to another file, of any type,
previously archived. Such files are identified in Unix
by each file having the same device and inode number.
The linked-to name is specified in the linkname field
with a trailing null.
LF_SYMLINK
represents a symbolic link to another file. The
linked-to name is specified in the linkname field with
a trailing null.
LF_CHR or LF_BLK
represent character special files and block special
files respectively. In this case the devmajor and dev-
minor fields will contain the major and minor device
numbers respectively. Operating systems may map the
device specifications to their own local specification,
or may ignore the entry.
LF_DIR
specifies a directory or sub-directory. The directory
name in the name field should end with a slash. On
systems where disk allocation is performed on a direc-
tory basis the size field will contain the maximum
number of bytes (which may be rounded to the nearest
disk block allocation unit) which the directory may
hold. A size field of zero indicates no such limiting.
Systems which do not support limiting in this manner
should ignore the size field.
LF_FIFO
specifies a FIFO special file. Note that the archiving
of a FIFO file archives the existence of this file and
not its contents.
LF_CONTIG
specifies a contiguous file, which is the same as a
normal file except that, in operating systems which
support it, all its space is allocated contiguously on
the disk. Operating systems which do not allow con-
tiguous allocation should silently treat this type as a
normal file.
`A' - `Z'
are reserved for custom implementations. None are used
by this version of the tar program.
other
values are reserved for specification in future revi-
sions of the P1003 standard, and should not be used by
any tar program.
The magic field indicates that this archive was output in
the P1003 archive format. If this field contains TMAGIC,
then the uname and gname fields will contain the ASCII
representation of the owner and group of the file respec-
tively. If found, the user and group ID represented by
these names will be used rather than the values contained
within the uid and gid fields. User names longer than
TUNMLEN-1 or group names longer than TGNMLEN-1 characters
will be truncated.
SEE ALSO
tar(1), ar(5), cpio(5), dump(8), restor(8), restore(8)
BUGS
Names or link names longer than NAMSIZ-1 characters cannot
be archived.
This format does not yet address multi-volume archives.
NOTES
This manual page was adapted by John Gilmore from Draft 6 of
the P1003 specification
The README file from the source distribution follows:
This is the Nov87 release of a public domain tar(1) replacement. It
implements the 'c', 'x', and 't' commands of Unix tar, and many of the
options. It creates P1003 "Unix Standard" [draft 6] tapes by default,
and can read and write both old and new formats. It can compress or
decompress tar archives "on the fly" (using the 'z' option) as well as
accessing remote tape drives or files by specifying
"host:/dev/tapedrive". It lets you set the default tape drive by
setting TAPE in your environment. Its verbose output looks more like
"ls -l" than the Unix tar, the columns line up, and you can get verbose
listings from the 'cvv' option as well as from 'xvv' and 'tv'. It does
shell-globbing (regular expressions) for listing and extraction. It is
a little better at reading damaged tapes than Unix tar. There is a
half-baked "diff" option for comparing a tape against the file system.
And it's free.
It is designed to be a lot more efficient than the standard Unix tar;
it does as little bcopy-ing as possible, and does file I/O in large
blocks. On the other hand, it has not been timed or performance-tuned;
it's just *designed* to be faster.
On SunOS 3.3, the tar archives it creates under the 'old' option are
byte-for-byte the same as those created by /bin/tar, except the trash
at the end of each file and at the end of the archive has been replaced
by zeroes.
It was written and initially debugged on a Sun Workstation running
4.2BSD. It has been run on Xenix, Unisoft, Vax 4.2BSD, utzoonix, USG,
Masscomp, Minix, and MSDOS systems. I'm interested in finding people
who will port it to other types of (Unix and non-Unix) systems, use it,
and send back the changes; and people who will add the obscure tar
options that they happen to use and I don't. In particular, VMS, Mac,
Atari and Amiga versions would be handy.
It still has a number of loose ends, marked by "FIXME" comments in the
source. Fixes to these things are also welcome.
I am the author of all the code in this program, except some of the
subroutines, which are from contributors listed below. I hereby place
it in the public domain. If you modify it, or port it to another
system, please send me back a copy, so I can keep a master source.
This program is much better than it started, due to the effort and care
put in by Henry Spencer, Fred Fish, Ian Darwin, Geoff Collyer, Stan
Barber, Guy Harris, Dave Brower, Richard Todd, Michael Rendell, Stu
Heiss, and Rich $alz. Thank you, one and all.
John Gilmore
Nebula Consultants
PO Box 170608
San Francisco, California, USA 94117-0608
hoptoad!gnu or gnu@toad.com
Hoptoad talks to sun, ptsfa, ihnp4, utzoo, ucsfcgl.
@(#)README 1.14 87/11/11