.TH gtar "" "" Command
.PC "Archiving/backup utility"
\fBgtar \fIoptions\fR
.PP
.HS
.SH Options:
.IC \fB\-A\fR
.IC \fB\-\-catenate\fR
.IC \fB\-\-concatenate\fR
Append files to an archive
.IC \fB\-\-atime\-preserve\fR
Don't change access times on dumped files
.IC \fB\-b\fR
.IC "\fB\-\-block\-size \fIN\fR"
Block size of \fIN\fR\(mu512 bytes (default, \fIN\fR=20)
.IC \fB\-B\fR
.IC \fB\-\-read\-full\-blocks\fR
Reblock as we read (for reading 4.2BSD pipes)
.IC \fB\-\-block\-compress\fR
Block the output of compression program for tapes
.IC \fB\-c\fR
.IC \fB\-\-create\fR
Create a new archive
.IC \fB\-C\fR
.IC "\fB\-\-directory \fIdir\fR"
Change to directory \fIdir\fR
.IC \fB\-\-checkpoint\fR
Print directory names while reading the archive
.IC \fB\-d\fR
.IC \fB\-\-diff\fR
.IC \fB\-\-compare\fR
Find differences between archive and file system
.IC \fB\-\-delete\fR
Delete from the archive
.IC "\fB\-\-exclude \fIfile\fR"
Exclude \fIfile\fR; \fIfile\fR can be a regular expression
.IC "\fB\-f \fIfile\fR"
.IC "\fB\-\-file \fIfile\fR"
Use archive file or device \fIfile\fR (default, the standard input)
.IC \fB\-\-force\-local\fR
Archive file is local even if has a colon
.IC "\fB\-F \fIscript\fR"
.IC "\fB\-\-info\-script \fIscript\fR"
.IC "\fB\-\-new\-volume\-script \fIscript\fR"
Run \fIscript\fR at end of each tape (implies \fB\-M\fR option)
.IC \fB\-G\fR
.IC \fB\-\-incremental\fR
Create/list/extract old GNU\-format incremental backup
.IC "\fB\-g \fIfile\fR"
.IC "\fB\-\-listed\-incremental \fIfile\fR"
Create/list/extract new GNU\-format incremental backup
.\".IC \-h
.\".IC \-\-dereference
.\"don't dump symlinks; dump the files they point to
.IC \fB\-i\fR
.IC \fB\-\-ignore\-zeros\fR
Ignore blocks of zeros in archive (normally mean EOF)
.IC \fB\-\-ignore\-failed\-read\fR
Don't exit with non\-zero status when an unreadable file is encountered
.IC \fB\-k\fR
.IC \fB\-\-keep\-old\-files\fR
Keep existing files; don't overwrite them from archive
.IC "\fB\-K \fIfile\fR"
.IC "\fB\-\-starting\-file \fIfile\fR"
Begin at \fIfile\fR in the archive
.IC \fB\-l\fR
.IC \fB\-\-one\-file\-system\fR
Stay in local file system when creating an archive
.IC "\fB\-L \fIN\fR"
.IC "\fB\-\-tape\-length \fIN\fR"
Change tapes after writing \fIN\fR\(mu1024 bytes
.IC \fB\-m\fR
.IC \fB\-\-modification\-time\fR
Don't extract file modified time
.IC \fB\-M\fR
.IC \fB\-\-multi\-volume\fR
Create/list/extract multi\-volume archive
.IC "\fB\-N \fIdate\fR"
.IC "\fB\-\-after\-date \fIdate\fR"
.IC "\fB\-\-newer \fIdate\fR"
Store only the files newer than \fIdate\fR
.IC \fB\-\-null\fR
\fB\-T\fR reads null\-terminated names, disable \fB\-C\fR
.IC \fB\-o\fR
.IC \fB\-\-old\-archive\fR
.IC \fB\-\-portability\fR
Write a V7 format archive, rather than ANSI format
.IC \fB\-O\fR
.IC \fB\-\-to\-stdout\fR
Extract files to standard output
.IC \fB\-p\fR
.IC \fB\-\-same\-permissions\fR
.IC \fB\-\-preserve\-permissions\fR
Extract all protection information
.IC \fB\-P\fR
.IC \fB\-\-absolute\-paths\fR
Don't strip leading `/'s from file names
.IC \fB\-\-preserve\fR
Combine options \fB\-p\fR and \fB\-s\fR
.IC \fB\-r\fR
.IC \fB\-\-append\fR
Append files to the end of an archive
.IC \fB\-R\fR
.IC \fB\-\-record\-number\fR
Show record number within archive with each message
.IC \fB\-\-remove\-files\fR
Remove files after adding them to the archive
.IC \fB\-s\fR
.IC \fB\-\-same\-order\fR
.IC \fB\-\-preserve\-order\fR
List of names to extract is sorted to match archive
.IC \fB\-\-same\-owner\fR
Create extracted files with the same ownership
.IC \fB\-S\fR
.IC \fB\-\-sparse\fR
Handle sparse files efficiently
.IC \fB\-t\fR
.IC \fB\-\-list\fR
List the contents of an archive
.IC "\fB\-T \fIfile\fR"
.IC "\fB\-\-files\-from \fIfile\fR"
Get names to extract or create from \fIfile\fR
.IC \fB\-\-totals\fR
Print total bytes written with \fB\-c\fR
.IC \fB\-u\fR
.IC \fB\-\-update\fR
Only append files that are newer than copy in archive
.IC "\fB\-\-use\-compress\-program \fIprogram\fR"
Filter the archive through \fIprogram\fR (which must accept \fB\-d\fR)
.IC \fB\-v\fR
.IC \fB\-\-verbose\fR
Verbosely list files processed
.IC "\fB\-V \fIname\fR"
.IC "\fB\-\-label \fIname\fR"
Create archive with volume \fIname\fR
.IC \fB\-\-version\fR
Print \fBgtar\fR version number
.IC \fB\-w\fR
.IC \fB\-\-interactive\fR
.IC \fB\-\-confirmation\fR
Ask for confirmation for every action
.IC \fB\-W\fR
.IC \fB\-\-verify\fR
Attempt to verify the archive after writing it
.IC \fB\-x\fR
.IC \fB\-\-extract\fR
.IC \fB\-\-get\fR
Extract files from an archive
.IC "\fB\-X \fIfile\fR"
.IC "\fB\-\-exclude\-from \fIfile\fR"
Exclude all files listed in \fIfile\fR
.IC \fB\-z\fR
.IC \fB\-\-gzip\fR
.IC \fB\-\-ungzip\fR
Filter the archive through \fBgzip\fR
.IC \fB\-Z\fR
.IC \fB\-\-compress\fR
.IC \fB\-\-uncompress\fR
Filter the archive through \fBcompress\fR
.\".IC \fB\-[0\-7][lmh]\fR
.\"Specify drive and density
.HE
.B gtar
is the GNU version of the archiving utility
.BR tar .
It copies files into or out of a
.B tar
archive, reads the contents of a
.B tar
archive, and replaces files within an archive.
It can also perform additional tasks such as compressing files as they
are added to an archive, or uncompressing them as they are read out.
.PP
.B gtar
works in either of two modes:
.IP "\fICopy-in Mode\fR"
.B gtar
copies files from an archive or lists the archive's contents.
By default, it reads the archive from the standard input; you
can also use the option
.B \-f
(described below) to name the file or device that holds the archive
you want read.
.IP
.B gtar
regards any non-option argument as a shell wild-card pattern;
and it copies from the archive only those files
whose names match one or more of those patterns.
Unlike the shell, an initial `.' in a file name
matches a wildcard at the start of a pattern, and a `/' in a file name
can match a wildcard.
If the command line contains no pattern,
.B gtar
extracts all files.
.IP "\fICopy-out Mode\fR"
.B gtar
copies files into an archive.
By default,
.B gtar
reads a list of file names, one per line,
from the standard input.
However, if the command line contains non-option arguments,
.B gtar
regards each as a shell wild-card pattern that names one or more files to
copy into the archive.
If an argument names a directory, then
.B gtar
recursively copies all files within that directory into the archive.
.IP
By default,
.B gtar
writes its newly built archive to the standard output.
However, you can use the option
.B \-f
(described below) to name the file or device into
.B gtar
writes the new archive.
.IP
.B gtar
normally writes into the local directory all files that it reads from
an archive.
If files were archived using absolute path names,
.B gtar
by default drops the leading `/' from the path name;
to suppress this behavior, use the option
.BR \-P ,
described below.
If a file being extracted resides within a directory that does not
exist in the current directory,
.B gtar
will create that directory.
.B gtar
will fail, of course, if you do not have write permission in the current
directory.
.SH Options
.B gtar
recognizes the following options.
Please note that not every option applies to both modes.
.PP
Please note, too, that some options have more than one name.
Every option has a multi-character name that begins with with two
hyphens
.BR \-\- ;
some commonly used options also have a one-character name that begins
with a single hyphen.
This convention may appear clumsy, but it does permit option names to
have hyphens embedded within them.
.\" so get used to it.
.PP
The following command-line options govern the mode in which
.B gtar
works:
.IP \fB\-A\fR
.IS \fB\-\-catenate\fR
.IS \fB\-\-concatenate\fR
Append files onto an archive.
.IP \fB\-c\fR
.IS \fB\-\-create\fR
Create a new archive.
.IP \fB\-d\fR
.IS \fB\-\-diff\fR
.IS \fB\-\-compare\fR
Find the differences between the files in an archive and the identically
named files in the file system.
This is very useful in verifying that a new archive was built correctly.
.IP \fB\-\-delete\fR
Delete files from the archive.
Do not for use this option with an archive that is on a magnetic tape.
.IP \fB\-r\fR
.IS \fB\-\-append\fR
Replace files within an archive.
If a file does not exist within an archive, append it onto the archive.
.IP \fB\-t\fR
.IS \fB\-\-list\fR
List the contents of an archive.
.IP \fB\-u\fR
.IS \fB\-\-update\fR
Append a file onto an archive only if it is younger than the identically named
file within the archive.
.IP \fB\-\-use-compress-program\fR
Specify the compression program to use.
By default,
.B gtar
invokes
.B gzip
to compress files.
.IP \fB\-x\fR
.IS \fB\-\-extract\fR
.IS \fB\-\-get\fR
Extract files from the archive.
.PP
The following options modify other aspects of
.BR gtar 's
behavior:
.IP \fB\-\-atime\-preserve\fR
Do not change the access times on files, whether copying into or out of
an archive.
.IP "\fB\-b \fIN\fR"
.IS "\fB\-\-block\-size \fIN\fR"
Use a block size of \fIN\fR\(mu512 bytes.
By default,
.B gtar
uses an
.I N
of 20 \(em that is, a block size of ten kilobytes.
.IP \fB\-B\fR
.IS \fB\-\-read\-full\-blocks\fR
Tell
.B gtar
to reblock as it reads.
This is required for reading pipes under Berkeley \*(UN release 4.2, and does
not apply to \*(CO.
.IP "\fB\-\-block\-compress [compress|gzip]\fR"
Block the output of the compression program for tapes.
You must name one of the compression options to use:
either
.B compress
or
.BR gzip .
.IP "\fB\-C \fIdirectory\fR"
.IS "\fB\-\-directory \fIdirectory\fR"
Change to
.IR directory .
.IP \fB\-\-checkpoint\fR
Print directory names while reading the archive.
.IP "\fB\-\-exclude \fIfile\fR"
Do not include
.I file
when archiving or de-archiving files.
.I file
can be a regular expression.
.IP "\fB\-f \fIfile\fR"
.\".IS "\fB\-\-file [\fIHOSTNAME\^\fB:]\fR"
.IS "\fB\-\-file \fIfile\fR"
Read the input from, or write the output to,
.IR file .
.I file
can name an ordinary file or a device.
File name `-' indicates the standard input or standard output
(depending upon whether an archive is being read or written).
When this option is not used,
.B gtar
by default reads from the standard input and writes to the standard output.
.IP \fB\-\-force\-local\fR
The archive file is local even if its name contains a colon.
.B gtar
usually interprets a file name that contains a colon as naming a file on
a remote system that is connected via a network.
.IP "\fB\-F \fIscript\fR"
.IS "\fB\-\-info\-script \fIscript\fR"
.IS "\fB\-\-new\-volume\-script \fIscript\fR"
At the end of each tape (or disk), run
.IR script .
Note that this option implies that you are also using option
.BR \-M .
.IP "\fB\-G [\fIfile ...\^\fB]\fR
.IS \fB\-\-incremental\fR
Create, list, or extract every
.I file
that is in an archive
written in the format of the old GNU incremental backup.
If no
.I file
is named, all
.B gtar
extracts all files.
.IP \fB\-g\fR
.IS \fB\-\-listed\-incremental\fR
Create, list, or extract files that are in an archive
written in the format of the new GNU incremental backup.
create/list/extract new GNU\-format incremental backup
.\".IP \fB\-h\fR
.\".IS \fB\-\-dereference\fR
.\"Do not dump symbolic links; that is,
.\"copy the files to which they point rather than copying the links.
.IP \fB\-i\fR
.IS \fB\-\-ignore\-zeros\fR
Ignore blocks of zeros in archive.
.IP \fB\-\-ignore\-failed\-read\fR
.B gtar
normally exits with non-zero status when it encounters an unreadable file.
With this option,
.B gtar
ignores the unreadable file and continues to work.
.IP \fB\-k\fR
.IS \fB\-\-keep\-old\-files\fR
If a file being extracted from an archive has an identically named analogue
in the file system,
.B gtar
normally overwrites the file in the file system with the file withdrawn from
the archive.
This option tells
.B gtar
to rename the file that is in the file system, rather than overwrite it.
.IP "\fB\-K \fIfile\fR"
.IS "\fB\-\-starting\-file \fIfile\fR"
Keep option:
begin work with
.I file
in the archive.
.IP \fB\-l\fR
.IS \fB\-\-one\-file\-system\fR
Stay in the local file system when creating an archive.
.IP "\fB\-L \fIN\fR"
.IS "\fB\-\-tape\-length \fIN\fR"
Change tapes after writing \fIN\fR\(mu1,024 bytes.
.B gtar
normally reads or writes until it reaches the end of the medium, then
prompts for the name of the next device.
This option, of course, normally does not apply to archives being written
to or read from disk.
.IP \fB\-m\fR
.IS \fB\-\-modification\-time\fR
Do not extract file modified time.
.IP \fB\-M\fR
.IS \fB\-\-multi\-volume\fR
Create, list, or extract a multi-volume archive.
You can use this option with multiple
.B \-f
options.
.B gtar
uses the output devices in sequence, then wraps around to the beginning.
This lets you, say, write output to two different tape drives or floppy-disk
drives; you can loading blank media into one while
.B gtar
is writing to the other.
Note that if you are using this option to create an archive, be
.I very
careful to label disks or tapes correctly to note the order in which
they were written.
.IP "\fB\-N \fIdate\fR"
.IS "\fB\-\-after\-date \fIdate\fR"
.IS "\fB\-\-newer \fIdate\fR"
Only store files newer than
.IR date .
.IP \fB\-o\fR
.IS \fB\-\-old\-archive\fR
.IS \fB\-\-portability\fR
Write a V7-format archive, rather than an ANSI-format archive.
.IP \fB\-O\fR
.IS \fB\-\-to\-stdout\fR
Write files to the standard output.
.IP \fB\-p\fR
.IS \fB\-\-same\-permissions\fR
.IS \fB\-\-preserve\-permissions\fR
Preserve the permissions that the file had originally.
.\"When it is in copy-out mode,
.\".B gtar
.\"by default gives files the permissions set by the umask of the
.\"user who is extracting them.
.IP \fB\-P\fR
.IS \fB\-\-absolute\-paths\fR
Do not strip leading `/'s from file names.
.IP \fB\-\-preserve\fR
This option is identical to
.B \-p
plus
.BR \-s .
.IP \fB\-R\fR
.IS \fB\-\-record\-number\fR
Show record number within archive with each message.
.IP \fB\-\-remove\-files\fR
Remove files after adding them to the archive.
.IP \fB\-s\fR
.IS \fB\-\-same\-order\fR
.IS \fB\-\-preserve\-order\fR
Sort the list of names to extract to match their order within the archive.
.IP \fB\-\-same\-owner\fR
Create extracted files with the same ownership they had within the archive.
.IP \fB\-S\fR
.IS \fB\-\-sparse\fR
Handle sparse files efficiently.
For a description of what a
.I "sparse file"
is, see the Lexicon entry for
.BR chsize() .
.IP \fB\-\-show\-omitted\-dirs\fR
Print the names of directories omitted from the archive.
.IP "\fB\-T file\fR"
.IS "\fB\-\-files\-from \fIfile\fR"
Read from
.I file
the names of all files to archive or extract.
.IP \fB\-\-null\fR
Modify option
.B \-T
so that it reads null\-terminated names.
This option
disables option
.BR \-C .
.\" huh?
.IP \fB\-\-totals\fR
Print the number of bytes written with option
.BR \-c .
.IP "\fB\-\-use\-compress\-program \fIprogram\fR"
Filter the archive through
.IR program .
Note that
.I program
must accept option
.BR \-d .
.IP \fB\-v\fR
.IS \fB\-\-verbose\fR
Write the names of all files archived or extracted.
When you also use the option
.BR \-f ,
.B gtar
writes the names to the standard output;
however, when you do not use
.BR \-f ,
it writes them to the standard error.
.IP "\fB\-V \fIname\fR"
.IS "\fB\-\-label \fIname\fR"
Name the archive
.IR name .
When used with the option
.BR \-\-extract ,
.I name
can be a regular expression.
.IP \fB\-\-version\fR
Print the version of
.B gtar
that you are using.
.IP "\fB\-\-volno\-file \fIfile\fR"
Read from
.I file
the volume number used when prompting the user.
Note that
.B gtar
does not use the contents of
.I file
when it records volume identifiers on the archive.
.IP \fB\-w\fR
.IS \fB\-\-interactive\fR
.IS \fB\-\-confirmation\fR
Ask the user to confirm every action.
.IP \fB\-W\fR
.IS \fB\-\-verify\fR
Attempt to verify the archive after writing it.
.IP "\fB\-X \fIfile\fR"
.IS "\fB\-\-exclude\-from \fIfile\fR"
Do
.I not
archive or de-archive all of the files named in
.IR file .
.IP \fB\-Z\fR
.IS \fB\-\-compress\fR
.IS \fB\-\-uncompress\fR
Filter files being archived or de-archived through
.BR compress .
.IP \fB\-z\fR
.IS \fB\-\-gzip\fR
.IS \fB\-\-ungzip\fR
Filter files being archived or de-archived through
.BR gzip .
.\".IP \fB\-[0\-7][lmh]\fR
.\"Specify the tape drive that holds the archive, and density of the tape
.\"(low, medium, or high).
.SH Examples
The first example archives \fBpiggy\fR,
into archive \fBpiggy.tar\fR:
.DM
	gtar \-cf piggy.tar piggy
.DE
.PP
To simultaneously compress
.B piggy
with the utility
.BR gzip ,
use the command:
.DM
	gtar -czf piggy.gtz piggy
.DE
.PP
Note that the suffix
.B .gtz
is used by convention to mark archives whose contents are compressed.
This is not required, but it is a good idea to use this or some similar
suffix to mark compressed archives:
if you do not remember to use the
.B \-z
option to de-archive a compress archive,
.B gtar
will fail.
So, to extract file
.B piggy
from its compressed archive, use the command:
.DM
	gtar -xzf piggy.gtz piggy
.DE
.PP
The
.B \-z
is recommended:
it speeds archiving of large files or file systems, and increases
their accuracy \(em because the archives are smaller, there are
fewer opportunities for errors to occur.
.PP
To write an archive onto a device, use the option
.B \-f
to name that device instead of a file.
You must, of course, have write permission on that device.
If you are writing onto a floppy disk, the disk must have been
formatted with the command
.BR fdformat ,
but does not need to have a \*(CO file system on it;
in fact,
.B gtar
will overwrite all file-system information that may reside on a disk.
For example, to write file
.B piggy
onto a high-density,
5.25-inch, formatted floppy disk in drive 0, use the following command:
.DM
	gtar \-czf /dev/fha0 piggy
.DE
.PP
To copy
.B piggy
back from this archive, use the command:
.DM
	gtar \-xzf /dev/fha0
.DE
.PP
As noted above, you must remember to use the
.B \-z
option to de-archive files from a compressed archive.
.PP
As noted above, if you name a directory on
.BR gtar 's
command line,
.B gtar
will archive or de-archive that directory and all files that it contains,
including its sub-directories and their contents.
For example, to archive all of your personal files, use the command:
.DM
	gtar -cvzf backup.gtz $HOME
.DE
.PP
The option
.B \-v
tells
.B gtar
to name every file that it is copying into its archive.
Note, too, that
.B gtar
is smart enough not to copy an archive into itself, so you can execute
the above command while still within your home directory.
.PP
The following backs up your personal files onto a high-density, 3.5-inch
disk in drive 0:
.DM
	gtar -cvzf /dev/fva0 $HOME
.DE
.PP
NB, if you are backing up a directory that will require more than one
floppy disk, you should consider using the utility
.B cpio
instead:
it is somewhat easier to use when you are handling multiple-volume
archives.
.PP
To copy directory
.B src
to the SCSI tape device with SCSI identifier 2, use the command:
.DM
	tar cvzf /dev/rStp2 src
.DE
.PP
To archive
.B src
to a tape and then confirm it, use the command
.DM
	tar cvzf /dev/rStp2 src ; tar dvzf /dev/rStp2 src
.DE
.PP
Note that this can be time consuming, but will confirm the integrity
of backups of vital files.
To restore
.B src
from its tape, use the command:
.DM
	tar xvzf /dev/rStp2
.DE
.PP
.B gtar
by default saves files with their original ownerships and permissions;
however, when it restores files, it may modify them.
To restore files with their original permissions, use the option
.BR \-p .
For example, to restore
.B src
and restore the original ownership and permissions of its files, use the
command:
.DM
	tar xvpzf /dev/rStp2
.DE
.SH "See Also"
.Xr "commands," commands
.Xr "compression," compressi
.Xr "gnucpio," gnucpio
.Xr "tar" tar
.br
\*(PX Standard, \(sc10.1.1
.SH Notes
\*(CO does not yet support networking.
The above descriptions of host addressing do not yet apply.
.PP
.II "Free Software Foundation"
.B gtar
is released under the conditions of the Free Software Foundation's
``copyleft''.
Full source code is available through the Mark Williams bulletin board.
