-This GNU tar 1.10. Please send bug reports, etc., to
-bug-gnu-utils@prep.ai.mit.edu.
+README for GNU tar
-GNU tar is based heavily on John Gilmore's public domain tar, but with
-added features. The manual is currently being written. An old
-manual, surely riddled with errors, is in tar.texinfo. Please don't
-send in bug reports about that manual. In particular, the mechanism
-for doing incremental dumps has been significantly changed.
+ Copyright (C) 1990, 1991, 1992, 1994, 1997, 1998, 1999, 2000,
+ 2001, 2003 Free Software Foundation, Inc.
-This distribution also includes rmt, the remote tape server (which
-must reside in /etc). The mt program is in the GNU cpio distribution.
+ This file is part of GNU tar.
-To compile tar (and rmt, if your system has the needed features) on
-Unix-like systems:
+ GNU tar is free software; you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published by
+ the Free Software Foundation; either version 2, or (at your option)
+ any later version.
-1. Type `./configure'. This shell script attempts to guess correct
-values for various system-dependent variables used during compilation,
-and creates the file `Makefile'. This takes a couple of minutes.
+ GNU tar is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ GNU General Public License for more details.
-If you want to compile in a different directory from the one
-containing the source code, `cd' to that directory and run `configure'
-with the option `--srcdir=DIR', where DIR is the directory that
-contains the source code. The object files and executables will be
-put in the current directory. This option only works with versions of
-`make' that support the VPATH variable. `configure' ignores any other
-arguments you give it.
+ You should have received a copy of the GNU General Public License
+ along with tar; see the file COPYING. If not, write to
+ the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+ Boston, MA 02111-1307, USA.
-If your system requires unusual options for compilation or linking
-that `configure' doesn't know about, you can give `configure' initial
-values for variables by setting them in the environment; in
-Bourne-compatible shells, you can do that on the command line like
-this:
-$ CC='gcc -traditional' LIBS=-lposix ./configure
-2. If you want to change the directories where the programs will be
-installed, or the optimization options, edit `Makefile' and change
-those values. If you have an unusual system that needs special
-compilation options that `configure' doesn't know about, and you
-didn't pass them in the environment when running `configure', you
-should add them to `Makefile' now. Alternately, teach `configure' how
-to figure out that it is being run on a system where they are needed,
-and mail the diffs to the address listed at the top of this file so we
-can include them in the next release.
+Please glance through *all* sections of this
+`README' file before starting configuration. Also make sure you read files
+`ABOUT-NLS' and `INSTALL' if you are not familiar with them already.
-3. Type `make'.
+If you got the `tar' distribution in `shar' format, time stamps ought to be
+properly restored; do not ignore such complaints at `unshar' time.
-4. If your system needs to link with -lPW to get alloca, but has
-rename in the C library (so RENAME_MISSING is not used), -lPW might give
-you an incorrect version of rename. On HP-UX this manifests itself as
-an undefined data symbol called "Error" when linking tar. If this
-happens, use `ar x' to extract alloca.o from libPW.a and `ar rc' to
-put it in a library liballoca.a, and put that in LIBS instead of -lPW.
-This problem does not occur when using gcc, which has alloca built in.
+GNU `tar' saves many files together into a single tape or disk
+archive, and can restore individual files from the archive. It includes
+multivolume support, the ability to archive sparse files, automatic archive
+compression/decompression, remote archives and special features that allow
+`tar' to be used for incremental and full backups. This distribution
+also includes `rmt', the remote tape server. The `mt' tape drive control
+program is in the GNU `cpio' distribution.
-5. If the programs compile successfully, type `make install' to
-install them.
+GNU `tar' is derived from John Gilmore's public domain `tar'.
+
+See file `ABOUT-NLS' for how to customize this program to your language.
+See file `COPYING' for copying conditions.
+See file `INSTALL' for compilation and installation instructions.
+See file `PORTS' for various ports of GNU tar to non-Unix systems.
+See file `NEWS' for a list of major changes in the current release.
+See file `THANKS' for a list of contributors.
-6. After you have installed the programs, you can remove the binaries
-from the source directory by typing `make mostlyclean'. Type `make
-clean' if you also want to remove `Makefile', for instance if you
-are going to recompile tar next on another type of machine.
+Besides those configure options documented in files `INSTALL' and
+`ABOUT-NLS', an extra option may be accepted after `./configure':
-makefile.pc is a makefile for Turbo C 2.0 on MS-DOS.
+* `--disable-largefile' omits support for large files, even if the
+operating system supports large files. Typically, large files are
+those larger on 2 GB on a 32-bit host.
-Various people have been having problems using floppies on a NeXT.
-I've gotten conflicting reports about what should be done to solve the
-problems, and we have no way to test it ourselves.
+The default archive format is GNU, this can be overridden by
+presetting DEFAULT_ARCHIVE_FORMAT while configuring. The allowed
+values are GNU, V7, OLDGNU and POSIX.
+The default archive device is now `stdin' on read and `stdout' on write.
+The installer can still override this by presetting `DEFAULT_ARCHIVE'
+in the environment before configuring (the behavior of `-[0-7]' or
+`-[0-7]lmh' options in `tar' are then derived automatically). Similarly,
+`DEFAULT_BLOCKING' can be preset to something else than 20.
-User-visible changes since 1.09:
+For comprehensive modifications to GNU tar, you might need tools beyond
+those used in simple installations. Fully install GNU m4 1.4 first,
+and only then, Autoconf 2.57 or later. Install Perl, then Automake
+1.7.5 or later. Also, install gettext 0.12.1 or later. You might
+need Bison 1.875 or later, and GNU tar itself. All are available on
+GNU archive sites, like in ftp://ftp.gnu.org/pub/gnu/.
-Filename to -G is optional. -C works right.
-Names newer and --newer-mtime work right.
+Send bug reports to <bug-tar@gnu.org>. A bug report should contain
+an adequate description of the problem, your input, what you expected,
+what you got, and why this is wrong. Diffs are welcome, but they only
+describe a solution, from which the problem might be uneasy to infer.
+If needed, submit actual data files with your report. Small data files
+are preferred. Big files may sometimes be necessary, but do not send them
+to the report address; rather take special arrangement with the maintainer.
--g is now --incremental
--G is now --listed-incremental
+Your feedback will help us to make a better and more portable package.
+Consider documentation errors as bugs, and report them as such. If you
+develop anything pertaining to `tar' or have suggestions, let us know
+and share your findings by writing to <bug-tar@gnu.org>.
-Sparse files now work correctly.
---volume is now called --label.
+Installation hints
+------------------
---exclude now takes a filename argument, and --exclude-from does what
---exclude used to do.
+Here are a few hints which might help installing `tar' on some systems.
-Exit status is now correct.
+* gzip and bzip2.
---totals keeps track of total I/O and prints it when tar exits.
+GNU tar uses the gzip and bzip2 programs to read and write compressed
+archives. If you don't have these programs already, you need to
+install them. Their sources can be found at:
-When using --label with --extract, the label is now a regexp.
+ftp://ftp.gnu.org/gnu/gzip/
+http://sourceware.cygnus.com/bzip2/
-New option --tape-length (-L) does multi-volume handling like BSD dump:
-you tell tar how big the tape is and it will prompt at that point
-instead of waiting for a write error.
+If you see the following symptoms:
-New backup scripts level-0 and level-1 which might be useful to
-people. They use a file "backup-specs" for information, and shouldn't
-need local modification. These are what we use to do all our backups
-at the FSF.
+ $ tar -xzf file.tar.gz
+ gzip: stdin: decompression OK, trailing garbage ignored
+ tar: Child returned status 2
+
+then you have encountered a gzip incompatibility that should be fixed
+in gzip test version 1.3, which as of this writing is available at
+<ftp://alpha.gnu.org/gnu/gzip/>. You can work around the
+incompatibility by using a shell command like
+ `gzip -d <file.tar.gz | tar -xzf -'.
+
+* Solaris issues.
+
+GNU tar exercises many features that can cause problems with older GCC
+versions. In particular, GCC 2.8.1 (sparc, -O1 or -O2) is known to
+miscompile GNU tar. No compiler-related problems have been reported
+when using GCC 2.95.2 or later.
+
+Recent versions of Solaris tar sport a new -E option to generate
+extended headers in an undocumented format. GNU tar does not
+understand these headers.
+
+* Static linking.
+
+Some platform will, by default, prepare a smaller `tar' executable
+which depends on shared libraries. Since GNU `tar' may be used for
+system-level backups and disaster recovery, installers might prefer to
+force static linking, making a bigger `tar' executable maybe, but able to
+work standalone, in situations where shared libraries are not available.
+The way to achieve static linking varies between systems. Set LDFLAGS
+to a value from the table below, before configuration (see `INSTALL').
+
+ Platform Compiler LDFLAGS
+
+ (any) Gnu C -static
+ AIX (vendor) -bnso -bI:/lib/syscalls.exp
+ HPUX (vendor) -Wl,-a,archive
+ IRIX (vendor) -non_shared
+ OSF (vendor) -non_shared
+ SCO 3.2v5 (vendor) -dn
+ Solaris (vendor) -Bstatic
+ SunOS (vendor) -Bstatic
+
+* Failed tests `ignfail.sh' or `incremen.sh'.
+
+In an NFS environment, lack of synchronization between machine clocks
+might create difficulties to any tool comparing dates and file time stamps,
+like `tar' in incremental dumps. This has been a recurrent problem with
+GNU Make for the last few years. We would like a general solution.
+
+* BSD compatibility matters.
+
+Set LIBS to `-lbsd' before configuration (see `INSTALL') if the linker
+complains about `bsd_ioctl' (Slackware). Also set CPPFLAGS to
+`-I/usr/include/bsd' if <sgtty.h> is not found (Slackware).
+
+* OPENStep 4.2 swap files
+
+Tar cannot read the file /private/vm/swapfile.front (even as root).
+This file is not a real file, but some kind of uncompressed view of
+the real compressed swap file; there is no reason to back it up, so
+the simplest workaround is to avoid tarring this file.
+
+
+Special topics
+--------------
+
+Here are a few special matters about GNU `tar', not related to build
+matters. See previous section for such.
+
+* File attributes.
+
+About *security*, it is probable that future releases of `tar' will have
+some behavior changed. There are many pending suggestions to choose from.
+Today, extracting an archive not being `root', `tar' will restore suid/sgid
+bits on files but owned by the extracting user. `root' automatically gets
+a lot of special privileges, `-p' might later become required to get them.
+
+GNU `tar' does not properly restore symlink attributes. Various systems
+implement flavors of symbolic links showing different behavior and
+properties. We did not successfully sorted all these out yet. Currently,
+the `lchown' call will be used if available, but that's all.
+
+* POSIX compliance.
+
+GNU `tar' implements an early draft of the POSIX 1003.1 `ustar' standard
+which is different from the final standard. This will be progressively
+corrected over the incoming few years. Don't be mislead by the mere
+existence of the --posix option. Later releases will become able to
+read truly POSIX archives, and also to produce them under option. (Also,
+if you look at the internals, don't take the GNU extensions you see for
+granted, as they are planned to change.) GNU tar 2.0 will produce POSIX
+archives by default, but there is a long way before we get there.
+
+* What's next?
+
+In the future we will try to release tar-1.14 as soon as possible and
+start merging with paxutils afterwards. We'll also try to rewrite
+some parts of the documentation after paxutils has been merged.