-Hey! Emacs! Yo! This is -*- Text -*- !!!
+README for GNU tar
+See the end of file for copying conditions.
-This GNU tar 1.11. Please send bug reports, etc., to
-bug-gnu-utils@prep.ai.mit.edu. This is a beta-test release. Please
-try it out. After bug reports are processed for this release, version
-1.12 will be released.
+* Introduction
-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.
+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.
-This distribution also includes rmt, the remote tape server (which
-must reside in /etc). The mt program is in the GNU cpio distribution.
+If you got the 'tar' distribution in 'shar' format, time stamps ought to be
+properly restored; do not ignore such complaints at 'unshar' time.
-See the file INSTALL for compilation and installation instructions for Unix.
+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.
-makefile.pc is a makefile for Turbo C 2.0 on MS-DOS.
+GNU 'tar' is derived from John Gilmore's public domain 'tar'.
-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.
+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 'NEWS' for a list of major changes in the current release.
+See file 'THANKS' for a list of contributors.
-If you want to do incremental dumps, use the distributed backup
-scripts. They are what we use at the FSF to do all our backups. Most
-importantly, do not use +incremental (-G) or +after-date (-N) or
-+newer-mtime to do incremental dumps. The only option that works
-correctly for this purpose is +listed-incremental. (When extracting
-incremental dumps, use +incremental (-G).)
+Besides those configure options documented in files 'INSTALL' and
+'ABOUT-NLS', an extra option may be accepted after './configure':
-There is no tar manual in this release. The old manual has too many
-problems to make it usable. A new manual will appear in version 1.12.
+* Install
-User-visible changes since 1.10:
+** Selecting the default archive format.
-o Many bug fixes
+The default archive format is GNU, this can be overridden by
+presetting DEFAULT_ARCHIVE_FORMAT while configuring. The allowed
+values are GNU, V7, OLDGNU, USTAR and POSIX.
-o Now uses GNU standard configure, generated by Autoconf.
+** Selecting the default archive device
-o Long options now use `--'; use of `+' is deprecated and support for it
- will eventually be removed.
+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.
-o New option --null causes filenames read by -T to be null-terminated,
- and causes -C to be ignored.
+** Selecting full pathname of the "rmt" binary.
-o New option --remove-files deletes files (but not directories) after
- they are added to the archive.
+Previous versions of tar always looked for "rmt" binary in the
+directory "/etc/rmt". However, the "rmt" program included
+in the distribution was installed under "$prefix/libexec/rmt".
+To fix this discrepancy, tar now looks for "$prefix/libexec/rmt".
+If you do not want this behavior, specify full path name of
+"rmt" binary using DEFAULT_RMT_DIR variable, e.g.:
-o New option --ignore-failed-read prevents read-errors from affecting
- the exit status.
+./configure DEFAULT_RMT_DIR=/etc
-o New option --checkpoint prints occasional messages as the tape is
- being read or written.
+If you already have a copy of "rmt" installed and wish to use it
+instead of the version supplied with the distribution, use --with-rmt
+option:
-o New option --show-omitted-dirs prints the names of directories
- omitted from the archive.
+./configure --with-rmt=/etc/rmt
-o Some tape drives which use a non-standard method of indicating
- end-of-tape now work correctly with multi-tape archives.
+This will also disable building the included version of rmt.
-o --volno-file: Read the volume number used in prompting the user (but
- not in recording volume ID's on the archive) from a file.
+** Installing backup scripts.
-o When using --multi-volume, you can now give multiple -f arguments;
- the various tape drives will get used in sequence and then wrap
- around to the beginning.
+This version of tar is shipped with the shell scripts for producing
+incremental backups (dumps) and restoring filesystems from them.
+The name of the backup script is "backup". The name of the
+restore script is "restore". They are installed in "$prefix/sbin"
+directory.
-o Remote archive names no longer have to be in /dev: any file with a
- `:' is interpreted as remote. If new option --force-local is given,
- then even archive files with a `:' are considered local.
+Use option --enable-backup-scripts to compile and install these
+scripts.
-o New option --atime-preserve restores (if possible) atimes to their
- original values after dumping the file.
+** '--disable-largefile' omits support for large files, even if the
+operating system supports large files. Typically, large files are
+those larger than 2 GB on a 32-bit host.
-o No longer does tar confusingly dump "." when you don't tell it what
- to dump.
+* Installation hints
-o When extracting directories, tar now correctly restores their
- modification and access times.
+Here are a few hints which might help installing 'tar' on some systems.
-o Longnames support is redone differently--long name info directly
- precedes the long-named file or link in the archive, so you no
- longer have to wait for the extract to hit the end of the tape for
- long names to work.
+** gzip and bzip2.
+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:
+
+ftp://ftp.gnu.org/gnu/gzip/
+http://sourceware.cygnus.com/bzip2/
+
+If you see the following symptoms:
+
+ $ 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' is able to create archive in the following formats:
+
+ *** The format of UNIX version 7
+ *** POSIX.1-1988 format, also known as "ustar format"
+ *** POSIX.1-2001 format, also known as "pax format"
+ *** Old GNU format (described below)
+
+In addition to those, GNU 'tar' is also able to read archives
+produced by 'star' archiver.
+
+A so called 'Old GNU' format is based on an early draft of the
+POSIX 1003.1 'ustar' standard which is different from the final
+standard. It defines its extensions (such as incremental backups
+and handling of the long file names) in a way incompatible with
+any existing tar archive format, therefore the use of old GNU
+format is strongly discouraged.
+
+Please read the file NEWS for more information about POSIX compliance
+and new 'tar' features.
+
+* What's next?
+
+GNU tar will be merged into GNU paxutils: a project containing
+several utilities related to creating and handling archives in
+various formats. The project will include tar, cpio and pax
+utilities.
+
+* Bug reporting.
+
+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.
+
+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>.
+
+\f
+* Copying
+
+Copyright 1990-1992, 1994, 1997-2001, 2003-2004, 2007, 2012-2014 Free
+Software Foundation, Inc.
+
+This file is part of GNU tar.
+
+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 3 of the License, or
+(at your option) any later version.
+
+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.
+
+You should have received a copy of the GNU General Public License
+along with this program. If not, see <http://www.gnu.org/licenses/>.
+
+NOTE ON COPYRIGHT YEARS
+
+In copyright notices where the copyright holder is the Free Software
+Foundation, then where a range of years appears, this is an inclusive
+range that applies to every year in the range. For example: 2005-2008
+represents the years 2005, 2006, 2007, and 2008.
+\f
+Local Variables:
+mode: outline
+paragraph-separate: "[ \f]*$"
+version-control: never
+End:
projects / chaz / tar / blobdiff