This is Info file tar.info, produced by Makeinfo version 1.67 from the
input file tar.texi.

START-INFO-DIR-ENTRY
* tar: (tar).			Making tape (or disk) archives.
END-INFO-DIR-ENTRY

   This file documents GNU `tar', a utility used to store, backup, and
transport files.

   Copyright (C) 1992, 1994, 1995, 1996, 1997 Free Software Foundation,
Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.

   This file documents GNU `tar', which is a utility used to store,
backup, and transport files.  `tar' is a tape (or disk) archiver.  This
manual documents the release 1.12a.


File: tar.info,  Node: documentation and help,  Next: Index,  Prev: All Options,  Up: Top

Documentation and Troubleshooting
*********************************

   Being careful, the first thing is really checking that you are using
GNU `tar', indeed.  The `--version' option will generate a message
giving confirmation that you are using GNU `tar', with the precise
version of GNU `tar' you are using.  `tar' identifies itself and prints
the version number to the standard output, then immediately exits
successfully, without doing anything else, ignoring all other options.
For example, `tar --version' might return:

     tar (GNU tar) 1.12a

The first occurrence of `tar' in the result above is the program name
in the package (for example, `rmt' is another program), while the
second occurrence of `tar' is the name of the package itself,
containing possibly many programs.  The package is currently named
`tar', after the name of the main program it contains(1).

   Another thing you might want to do is checking the spelling or
meaning of some particular `tar' option, without resorting to this
manual, for once you have carefully read it.  GNU `tar' has a short help
feature, triggerable through the `--help' option.  By using this
option, `tar' will print a usage message listing all available options
on standard output, then exit successfully, without doing anything else
and ignoring all other options.  Even if this is only a brief summary,
it may be several screens long.  So, if you are not using some kind of
scrollable window, you might prefer to use something like:

     $ tar --help | less

presuming, here, that you like using `less' for a pager.  Other popular
pagers are `more' and `pg'.  If you know about some KEYWORD which
interests you and do not want to read all the `--help' output, another
common idiom is doing:

     tar --help | grep KEYWORD

for getting only the pertinent lines.

   The perceptive reader would have noticed some contradiction in the
previous paragraphs.  It is written that both `--version' and `--help'
print something, and have all other options ignored.  In fact, they
cannot ignore each other, and one of them has to win.  We do not
specify which is stronger, here; experiment if you really wonder!

   The short help output is quite succint, and you might have to get
back to the full documentation for precise points.  If you are reading
this paragraph, you already have the `tar' manual in some form.  This
manual is available in printed form, as a kind of small book.  It may be
printed out of the GNU `tar' distribution, provided you have TeX
already installed somewhere, and a laser printer around.  Just configure
the distribution, execute the command `make dvi', then print
`doc/tar.dvi' the usual way (contact your local guru to know how).  If
GNU `tar' has been conveniently installed at your place, this manual is
also available in interactive, hypertextual form as an Info file.  Just
call `info tar' or, if you do not have the `info' program handy, use
the Info reader provided within GNU Emacs, and choose `tar' from the
main Info menu (with `m tar <RET>').

   A short reference to `tar' in the form of a `man' page is also
provided.  Currently, it doesn't tell much more that `tar --help' does.

* Menu:

* verbose::
* interactive::

   ---------- Footnotes ----------

   (1)  There are plans to merge the `cpio' and `tar' packages into a
single one which would be called `paxutils'.  So, who knows if, one of
this days, the `--version' would not yield `tar (GNU paxutils) 3.2'


File: tar.info,  Node: verbose,  Next: interactive,  Prev: documentation and help,  Up: documentation and help

Checking `tar' progress
=======================

   Typically, `tar' performs most subcommands without reporting any
information to the user except error messages.  When using `tar' with
many options, particularly ones with complicated or
difficult-to-predict behavior, it is possible to make serious mistakes.
`tar' provides several options that make observing `tar' easier.  These
options cause `tar' to print information as it progresses in its job,
and you might want to use them just for being more careful about what
is going on, or merely for entertaining yourself.  If you have
encountered a problem when operating on an archive, however, you may
need more information than just an error message in order to solve the
problem.  The following options can be helpful diagnostic tools.

   Normally, the `--list' (`-t') command to list an archive prints just
the file names (one per line) and the other commands are silent.  When
used with most subcommands, the `--verbose' (`-v') option causes `tar'
to print the name of each file or archive member as it is processed.
This and the other options which make `tar' print status information
can be useful in monitoring `tar'.

   With `--create' (`-c') or `--extract' (`--get', `-x'), `--verbose'
(`-v') used once just prints the names of the files or members as they
are processed.  Using it twice causes `tar' to print a longer listing
(reminiscent of `ls -l') for each member.  Since `--list' (`-t')
already prints the names of the members, `--verbose' (`-v') used once
with `--list' (`-t') causes `tar' to print an `ls -l' type listing of
the files in the archive.  The following examples both extract members
with long list output:

     $ tar --extract --file=archive.tar --verbose --verbose
     $ tar xvv archive.tar

   Verbose output appears on the standard output except when an archive
is being written to the standard output, as with `tar --create --file=-
--verbose' (`tar cfv -', or even `tar cv'--if the installer let
standard output be the default archive).  In that case `tar' writes
verbose output to the standard error stream.

   The `--totals' option--which is only meaningful when used with
`--create' (`-c')--causes `tar' to print the total amount written to
the archive, after it has been fully created.

   The `--checkpoint' option prints an occasional message as `tar'
reads or writes the archive.  It is designed for those who don't need
the more detailed (and voluminous) output of `--block-number' (`-R'),
but do want visual confirmation that `tar' is actually making forward
progress.

   The `--show-omitted-dirs' option, when reading an archive--with
`--list' (`-t') or `--extract' (`--get', `-x'), for example--causes a
message to be printed for each directory in the archive which is
skipped.  This happens regardless of the reason for skipping: the
directory might not have been named on the command line (implicitly or
explicitly), it might be excluded by the use of the `--exclude=PATTERN'
option, or some other reason.

   If `--block-number' (`-R') is used, `tar' prints, along with every
message it would normally produce, the block number within the archive
where the message was triggered.  Also, supplementary messages are
triggered when reading blocks full of NULs, or when hitting end of file
on the archive.  As of now, if the archive is properly terminated with
a NUL block, the reading of the file may stop before end of file is
met, so the position of end of file will not usually show when
`--block-number' (`-R') is used.  Note that GNU `tar' drains the
archive before exiting when reading the archive from a pipe.

   This option is especially useful when reading damaged archives, since
it helps pinpoint the damaged sections.  It can also be used with
`--list' (`-t') when listing a file-system backup tape, allowing you to
choose among several backup tapes when retrieving a file later, in
favor of the tape where the file appears earliest (closest to the front
of the tape).


File: tar.info,  Node: interactive,  Prev: verbose,  Up: documentation and help

Asking for Confirmation During Subcommands
==========================================

   Typically, `tar' carries out a command without stopping for further
instructions.  In some situations however, you may want to exclude some
files and archive members from the operation (for instance if disk or
storage space is tight).  You can do this by excluding certain files
automatically (*note Choosing::.), or by performing a subcommand
interactively, using the `--interactive' (`-w') option.  `tar' also
accepts `--confirmation' for this option.

   When the `--interactive' (`-w') option is specified, before reading,
writing, or deleting files, `tar' first prints a message for each such
file, telling what action it intends to take, then asks for
confirmation on the terminal.  The actions which require confirmation
include adding a file to the archive, extracting a file from the
archive, deleting a file from the archive, and deleting a file from
disk.  To confirm the action, you must type a line of input beginning
with `y'.  If your input line begins with anything other than `y',
`tar' skips that file.

   If `tar' is reading the archive from the standard input, `tar' opens
the file `/dev/tty' to support the interactive communications.

   Verbose output is normally sent to standard output, separate from
other error messages.  However, if the archive is produced directly on
standard output, then verbose output is mixed with errors on `stderr'.
Producing the archive on standard output may be used as a way to avoid
using disk space, when the archive is soon to be consumed by another
process reading it, say.  Some people felt the need of producing an
archive on stdout, still willing to segregate between verbose output
and error output.  A possible approach would be using a named pipe to
receive the archive, and having the consumer process to read from that
named pipe.  This has the advantage of letting standard output free to
receive verbose output, all separate from errors.


File: tar.info,  Node: Index,  Prev: documentation and help,  Up: Top

Index
*****

* Menu:

* --list with file name arguments:       list.
* -backup:                               backup.
* -suffix:                               backup.
* -version-control:                      backup.
* abbreviations for months:              Calendar date item.
* absolute file names:                   Remote Tape Server.
* Acting interactively:                  interactive.
* Adding archives to an archive:         concatenate.
* Adding files to an Archive:            appending files.
* Age, excluding files by:               after.
* ago in date strings:                   Relative item in date strings.
* Alaska-Hawaii Time:                    Timezone item.
* am in date strings:                    Time of day item.
* Appending files to an Archive:         appending files.
* archive:                               Definitions.
* Archive creation:                      file.
* archive member:                        Definitions.
* Archive Name:                          file.
* Archives, Appending files to:          appending files.
* Archives, on remote machines:          file.
* Archiving Directories:                 create dir.
* Atlantic Standard Time:                Timezone item.
* Authors of getdate:                    Authors of getdate.
* Avoiding recursion in directories:     recurse.
* Azores Time:                           Timezone item.
* backup files, type made:               backup.
* backup options:                        backup.
* backup suffix:                         backup.
* backups, making:                       backup.
* Baghdad Time:                          Timezone item.
* beginning of time, for Unix:           Date input formats.
* Bellovin, Steven M.:                   Authors of getdate.
* Berets, Jim:                           Authors of getdate.
* Berry, K.:                             Authors of getdate.
* Block number where error occured:      verbose.
* Blocking Factor:                       Blocking Factor.
* blocking factor:                       Blocking Factor.
* Blocks per record:                     Blocking Factor.
* bug reports:                           Reports.
* Bytes per record:                      Blocking Factor.
* Calendar date item:                    Calendar date item.
* case, ignored in dates:                General date syntax.
* cat vs concatenate:                    concatenate.
* Central Alaska Time:                   Timezone item.
* Central European Time:                 Timezone item.
* Central Standard Time:                 Timezone item.
* Changing directory mid-stream:         directory.
* Character class, excluding characters from: Wildcards.
* China Coast Time:                      Timezone item.
* Choosing an archive file:              file.
* comments, in dates:                    General date syntax.
* Compressed archives:                   gzip.
* concatenate vs cat:                    concatenate.
* Concatenating Archives:                concatenate.
* corrupted archives <1>:                gzip.
* corrupted archives:                    Full Dumps.
* DAT blocking:                          Blocking Factor.
* date format, ISO 8601:                 Calendar date item.
* date input formats:                    Date input formats.
* day in date strings:                   Relative item in date strings.
* Day of week item:                      Day of week item.
* daylight savings time:                 Timezone item.
* Deleting files from an archive:        delete.
* Deleting from tape archives:           delete.
* Descending directories, avoiding:      recurse.
* Directing output:                      file.
* Directories, Archiving:                create dir.
* Directories, avoiding recursion:       recurse.
* Directory, changing mid-stream:        directory.
* Disk space, running out of:            Scarce.
* Displacement of dates:                 Relative item in date strings.
* Double-checking a write operation:     verify.
* dumps, full:                           Full Dumps.
* dumps, incremental:                    Inc Dumps.
* East Australian Standard Time:         Timezone item.
* Eastern European Time:                 Timezone item.
* Eastern Standard Time:                 Timezone item.
* End-of-archive entries, ignoring:      Reading.
* entry:                                 Naming tar Archives.
* epoch, for Unix:                       Date input formats.
* Error message, block number of:        verbose.
* Exabyte blocking:                      Blocking Factor.
* exclude:                               exclude.
* exclude-from:                          exclude.
* Excluding characters from a character class: Wildcards.
* Excluding file by age:                 after.
* Excluding files by file system:        exclude.
* Excluding files by name and pattern:   exclude.
* existing backup method:                backup.
* exit status:                           Synopsis.
* Extracting files on MS-DOS, illegal characters: Basic tar.
* extraction:                            Definitions.
* Extraction:                            extract.
* Feedback from tar:                     verbose.
* file name:                             Definitions.
* File Name arguments, alternatives:     files.
* File name arguments, using --list with: list.
* File names, excluding files by:        exclude.
* File names, terminated by NUL:         nul.
* File names, using symbolic links:      dereference.
* File system boundaries, not crossing:  one.
* File time stamp on MS-DOS/MS-Windows:  after.
* Filenames, illegal characters on MS-DOS: Basic tar.
* first in date strings:                 General date syntax.
* Format Options:                        Format Variations.
* Format Parameters:                     Format Variations.
* Format, old style:                     old.
* fortnight in date strings:             Relative item in date strings.
* French Winter Time:                    Timezone item.
* full dumps:                            Full Dumps.
* General date syntax:                   General date syntax.
* getdate:                               Date input formats.
* Getting more information:              verbose.
* Greenwich Mean Time:                   Timezone item.
* Guam Standard Time:                    Timezone item.
* Hawaii Standard Time:                  Timezone item.
* hour in date strings:                  Relative item in date strings.
* Ignoring end-of-archive entries:       Reading.
* incremental dumps:                     Inc Dumps.
* Information during operation:          verbose.
* Information on progress and status of subcommands: verbose.
* Interactive action:                    interactive.
* International Date Line East:          Timezone item.
* International Date Line West:          Timezone item.
* ISO 8601 date format:                  Calendar date item.
* items in date strings:                 General date syntax.
* Japan Standard Time:                   Timezone item.
* Labeling an archive:                   label.
* Labelling multi-volume archives:       Multi-Volume Archives.
* Labels on the archive media:           label.
* Large lists of file names on small machines: Reading.
* last DAY:                              Day of week item.
* last in date strings:                  General date syntax.
* Lists of file names:                   files.
* MacKenzie, David:                      Authors of getdate.
* member:                                Definitions.
* member name:                           Definitions.
* Members, replacing with other members: append.
* Meyering, Jim:                         Authors of getdate.
* Middle European Time:                  Timezone item.
* Middle European Winter Time:           Timezone item.
* Middle of the archive, starting in the: Scarce.
* midnight in date strings:              Time of day item.
* minute in date strings:                Relative item in date strings.
* minutes, timezone correction by:       Time of day item.
* Mod time differs message on MS-DOS disks: compare.
* Modes of extracted files:              Writing.
* Modification time, excluding files by: after.
* Modification time, on MS-DOS:          after.
* Modification times of extracted files: Writing.
* month in date strings:                 Relative item in date strings.
* month names in date strings:           Calendar date item.
* months, written-out:                   General date syntax.
* Mountain Standard Time:                Timezone item.
* Multi-volume archives:                 Multi-Volume Archives.
* Name Prefixes,:                        create prefix.
* Naming an archive:                     file.
* New Zealand Standard Time:             Timezone item.
* next DAY:                              Day of week item.
* next in date strings:                  General date syntax.
* Nome Standard Time:                    Timezone item.
* noon in date strings:                  Time of day item.
* now in date strings:                   Relative item in date strings.
* ntape device:                          Many.
* NUL terminated file names:             nul.
* Number of blocks per record:           Blocking Factor.
* Number of bytes per record:            Blocking Factor.
* numbered backup method:                backup.
* numbers, written-out:                  General date syntax.
* Old style archives:                    old.
* Old style format:                      old.
* option syntax, traditional:            Old Options.
* Options when reading archives:         Reading.
* Options, archive format specifying:    Format Variations.
* Options, format specifying:            Format Variations.
* ordinal numbers:                       General date syntax.
* Overwriting old files, prevention:     Writing.
* Overwriting prevention on MS-DOS and MS-Windows: Prevention Overwriting.
* Pacific Standard Time:                 Timezone item.
* Permissions of extracted files:        Writing.
* Pinard, F.:                            Authors of getdate.
* pm in date strings:                    Time of day item.
* Prefixes, Name:                        create prefix.
* Progress information:                  verbose.
* Protecting old files:                  Writing.
* Pure numbers in date strings:          Pure numbers in date strings.
* Reading file names from a file:        files.
* Reading incomplete records:            Reading.
* Record Size:                           Blocking Factor.
* Records, incomplete:                   Reading.
* Recursion in directories, avoiding:    recurse.
* Relative items in date strings:        Relative item in date strings.
* Remote archives and MS-DOS file names: file.
* Remote archives specification:         file.
* remote tape drive:                     Remote Tape Server.
* Removing existing files on MS-DOS:     Prevention Overwriting.
* Removing files from an archive:        delete.
* Replacing members with other members:  append.
* reporting bugs:                        Reports.
* Resurrecting files from an archive:    extract.
* Retrieving files from an archive:      extract.
* return status:                         Synopsis.
* rmt:                                   Remote Tape Server.
* Running out of space:                  Reading.
* Running out of space during extraction: Scarce.
* Salz, Rich:                            Authors of getdate.
* simple backup method:                  backup.
* SIMPLE_BACKUP_SUFFIX:                  backup.
* Small memory:                          Reading.
* Space on the disk, recovering from lack of: Scarce.
* Sparse Files:                          sparse.
* Specifying archive members:            Selecting Archive Members.
* Specifying files to act on:            Selecting Archive Members.
* Standard input and output:             file.
* Standard output, writing extracted files to: Writing.
* Status information:                    verbose.
* Storing archives in compressed format: gzip.
* Swedish Winter Time:                   Timezone item.
* Symbolic link as file name:            dereference.
* tape blocking:                         Blocking Factor.
* tape marks:                            Many.
* tape positioning:                      Many.
* Tapes, using --delete and:             delete.
* tar:                                   What tar Does.
* tar archive:                           Definitions.
* tar entry:                             Naming tar Archives.
* tar file:                              Naming tar Archives.
* tar to standard input and output:      file.
* this in date strings:                  Relative item in date strings.
* Time of day item:                      Time of day item.
* Timestamp differences, on MS-DOS/MS-Windows filesystems: compare.
* timezone correction:                   Time of day item.
* Timezone item:                         Timezone item.
* today in date strings:                 Relative item in date strings.
* tomorrow in date strings:              Relative item in date strings.
* Ultrix 3.1 and write failure:          Remote Tape Server.
* Universal Coordinated Time:            Timezone item.
* unpacking:                             Definitions.
* Updating an archive:                   update.
* USSR Zone:                             Timezone item.
* uuencode:                              Applications.
* Verbose subcommand:                    verbose.
* Verifying a write operation:           verify.
* Verifying the currency of an archive:  compare.
* Version of the tar program:            verbose.
* version-control Emacs variable:        backup.
* VERSION_CONTROL:                       backup.
* week in date strings:                  Relative item in date strings.
* West African Time:                     Timezone item.
* West Australian Standard Time:         Timezone item.
* Western European Time:                 Timezone item.
* Where is the archive?:                 file.
* Working directory, specifying:         directory.
* Writing extracted files to standard output: Writing.
* Writing new archives:                  file.
* year in date strings:                  Relative item in date strings.
* yesterday in date strings:             Relative item in date strings.
* Yukon Standard Time:                   Timezone item.


