summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/Makefile.am153
-rw-r--r--doc/Makefile.in1893
-rw-r--r--doc/dumpdir.texi132
-rw-r--r--doc/fdl.texi507
-rw-r--r--doc/freemanuals.texi89
-rwxr-xr-xdoc/gendocs_template125
-rw-r--r--doc/genfile.texi367
-rw-r--r--doc/header.texi243
-rw-r--r--doc/intern.texi332
-rw-r--r--doc/mastermenu.el90
-rw-r--r--doc/parse-datetime.texi594
-rw-r--r--doc/rendition.texi99
-rw-r--r--doc/rmt.8254
-rw-r--r--doc/snapshot.texi164
-rw-r--r--doc/sparse.texi234
-rw-r--r--doc/stamp-vti4
-rw-r--r--doc/tar-snapshot-edit.texi91
-rw-r--r--doc/tar.11319
-rw-r--r--doc/tar.info466
-rw-r--r--doc/tar.info-17890
-rw-r--r--doc/tar.info-27007
-rw-r--r--doc/tar.texi13252
-rw-r--r--doc/texify.sed27
-rw-r--r--doc/untabify.el13
-rw-r--r--doc/value.texi20
-rw-r--r--doc/version.texi4
26 files changed, 35369 insertions, 0 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am
new file mode 100644
index 0000000..a84e0e3
--- /dev/null
+++ b/doc/Makefile.am
@@ -0,0 +1,153 @@
+# Makefile for GNU tar documentation.
+
+# Copyright 1994-1997, 1999-2001, 2003, 2006-2007, 2013-2014, 2016 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/>.
+
+info_TEXINFOS = tar.texi
+tar_TEXINFOS = \
+ dumpdir.texi\
+ tar-snapshot-edit.texi\
+ fdl.texi\
+ freemanuals.texi\
+ genfile.texi\
+ header.texi\
+ intern.texi\
+ parse-datetime.texi\
+ rendition.texi\
+ snapshot.texi\
+ sparse.texi\
+ value.texi
+
+dist_man_MANS=tar.1 $(RMT_8)
+if PU_RMT_COND
+ RMT_8=rmt.8
+endif
+
+EXTRA_DIST = gendocs_template mastermenu.el texify.sed untabify.el rmt.8
+
+# The rendering level is anyone of PUBLISH, DISTRIB or PROOF.
+# Just call 'make RENDITION=PROOF [target]' if you want PROOF rendition.
+RENDITION = DISTRIB
+
+MAKEINFOFLAGS=-D$(RENDITION)
+
+header.texi: $(top_srcdir)/src/tar.h
+ sed -f $(srcdir)/texify.sed $(top_srcdir)/src/tar.h \
+ | expand >$@
+
+master-menu: $(tar_TEXINFOS)
+ emacs -batch -l mastermenu.el -f make-master-menu $(info_TEXINFOS)
+
+untabify:
+ emacs -batch -l untabify.el $(info_TEXINFOS) $(tar_TEXINFOS)
+
+final: untabify master-menu
+
+# Checking
+check-format:
+ @if test -n "`cat $(info_TEXINFOS) $(tar_TEXINFOS) | tr -d -c '\t'`"; then \
+ echo "Sources contain tabs; run make untabify"; \
+ false; \
+ fi
+
+check-options:
+ @ARGP_HELP_FMT='usage-indent=0,short-opt-col=0,long-opt-col=0,doc-opt-col=0,opt-doc-col=0,header-col=0,rmargin=1' \
+ $(top_builddir)/src/tar --usage | \
+ sed -n 's/^\[--\([^]\=\[]*\).*/\1/p' | sort | uniq > opts.$$$$;\
+ $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) -E - \
+ $(info_TEXINFOS) | \
+ sed -n '/^@macro/,/^@end macro/d;s/@opindex *\([^@,]*\).*/\1/p' \
+ | sort | uniq > docs.$$$$;\
+ status=0;\
+ join -v1 opts.$$$$ docs.$$$$ > report.$$$$;\
+ if test -s report.$$$$; then \
+ echo 'Not documented options:'; \
+ cat report.$$$$; \
+ status=1; \
+ fi; \
+ join -v2 opts.$$$$ docs.$$$$ > report.$$$$;\
+ if test -s report.$$$$; then \
+ echo 'Non-existing options:';\
+ cat report.$$$$; \
+ status=1; \
+ fi; \
+ rm opts.$$$$ docs.$$$$ report.$$$$;\
+ test $$status -ne 0 && exit $$status
+
+check-refs:
+ @for file in $(info_TEXINFOS) $(tar_TEXINFOS); \
+ do \
+ sed -e = $$file | \
+ sed -n 'N;/@FIXME-.*ref/{s/\(^[0-9][0-9]*\).*@FIXME-.*ref{\([^}]*\).*/'$$file':\1: \2/gp}'; \
+ done > $@-t; \
+ if [ -s $@-t ]; then \
+ echo "Unresolved cross-references:"; \
+ cat $@-t;\
+ rm $@-t; \
+ else \
+ rm -f $@-t; \
+ fi
+
+check-fixmes:
+ @for file in $(info_TEXINFOS); \
+ do \
+ sed -e = $$file | \
+ sed -n 'N;/@FIXME{/{s/\(^[0-9][0-9]*\).*@FIXME{\([^}]*\).*/'$$file':\1: \2/gp}'; \
+ done > $@-t; \
+ if [ -s $@-t ]; then \
+ echo "Unresolved FIXMEs:"; \
+ cat $@-t; \
+ rm $@-t; \
+ false; \
+ else \
+ rm -f $@-t; \
+ fi
+
+check-unrevised:
+ @grep -Hn @UNREVISED $(info_TEXINFOS) > $@-t; \
+ if [ -s $@-t ]; then \
+ echo "Unrevised nodes:"; \
+ cat $@-t; \
+ rm $@-t; \
+ false;\
+ else \
+ rm $@-t; \
+ fi
+
+all-check-docs: check-format check-options check-refs check-fixmes check-unrevised
+
+check-docs:
+ $(MAKE) -k all-check-docs
+
+#
+
+clean-local:
+ rm -rf manual
+
+GENDOCS=gendocs.sh
+
+TEXI2DVI=texi2dvi -t '@set $(RENDITION)' -E
+
+# Make sure you set TEXINPUTS
+# Usual value is:
+# /usr/share/texmf/pdftex/plain/misc:/usr/share/texmf/pdftex/config
+manual:
+ TEXINPUTS=$(srcdir):$(top_srcdir)/build-tex:$(TEXINPUTS) \
+ MAKEINFO="$(MAKEINFO) $(MAKEINFOFLAGS)" \
+ TEXI2DVI="$(TEXI2DVI) -t @finalout" \
+ $(GENDOCS) --texi2html tar 'GNU tar manual'
diff --git a/doc/Makefile.in b/doc/Makefile.in
new file mode 100644
index 0000000..9afbf82
--- /dev/null
+++ b/doc/Makefile.in
@@ -0,0 +1,1893 @@
+# Makefile.in generated by automake 1.14 from Makefile.am.
+# @configure_input@
+
+# Copyright (C) 1994-2013 Free Software Foundation, Inc.
+
+# This Makefile.in is free software; the Free Software Foundation
+# gives unlimited permission to copy and/or distribute it,
+# with or without modifications, as long as this notice is preserved.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY, to the extent permitted by law; without
+# even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+# PARTICULAR PURPOSE.
+
+@SET_MAKE@
+
+# Makefile for GNU tar documentation.
+
+# Copyright 1994-1997, 1999-2001, 2003, 2006-2007, 2013-2014, 2016 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/>.
+VPATH = @srcdir@
+am__is_gnu_make = test -n '$(MAKEFILE_LIST)' && test -n '$(MAKELEVEL)'
+am__make_running_with_option = \
+ case $${target_option-} in \
+ ?) ;; \
+ *) echo "am__make_running_with_option: internal error: invalid" \
+ "target option '$${target_option-}' specified" >&2; \
+ exit 1;; \
+ esac; \
+ has_opt=no; \
+ sane_makeflags=$$MAKEFLAGS; \
+ if $(am__is_gnu_make); then \
+ sane_makeflags=$$MFLAGS; \
+ else \
+ case $$MAKEFLAGS in \
+ *\\[\ \ ]*) \
+ bs=\\; \
+ sane_makeflags=`printf '%s\n' "$$MAKEFLAGS" \
+ | sed "s/$$bs$$bs[$$bs $$bs ]*//g"`;; \
+ esac; \
+ fi; \
+ skip_next=no; \
+ strip_trailopt () \
+ { \
+ flg=`printf '%s\n' "$$flg" | sed "s/$$1.*$$//"`; \
+ }; \
+ for flg in $$sane_makeflags; do \
+ test $$skip_next = yes && { skip_next=no; continue; }; \
+ case $$flg in \
+ *=*|--*) continue;; \
+ -*I) strip_trailopt 'I'; skip_next=yes;; \
+ -*I?*) strip_trailopt 'I';; \
+ -*O) strip_trailopt 'O'; skip_next=yes;; \
+ -*O?*) strip_trailopt 'O';; \
+ -*l) strip_trailopt 'l'; skip_next=yes;; \
+ -*l?*) strip_trailopt 'l';; \
+ -[dEDm]) skip_next=yes;; \
+ -[JT]) skip_next=yes;; \
+ esac; \
+ case $$flg in \
+ *$$target_option*) has_opt=yes; break;; \
+ esac; \
+ done; \
+ test $$has_opt = yes
+am__make_dryrun = (target_option=n; $(am__make_running_with_option))
+am__make_keepgoing = (target_option=k; $(am__make_running_with_option))
+pkgdatadir = $(datadir)/@PACKAGE@
+pkgincludedir = $(includedir)/@PACKAGE@
+pkglibdir = $(libdir)/@PACKAGE@
+am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd
+install_sh_DATA = $(install_sh) -c -m 644
+install_sh_PROGRAM = $(install_sh) -c
+install_sh_SCRIPT = $(install_sh) -c
+INSTALL_HEADER = $(INSTALL_DATA)
+transform = $(program_transform_name)
+NORMAL_INSTALL = :
+PRE_INSTALL = :
+POST_INSTALL = :
+NORMAL_UNINSTALL = :
+PRE_UNINSTALL = :
+POST_UNINSTALL = :
+build_triplet = @build@
+host_triplet = @host@
+subdir = doc
+DIST_COMMON = $(srcdir)/Makefile.in $(srcdir)/Makefile.am \
+ $(tar_TEXINFOS) $(top_srcdir)/build-aux/mdate-sh \
+ $(srcdir)/version.texi $(srcdir)/stamp-vti \
+ $(top_srcdir)/build-aux/texinfo.tex $(dist_man_MANS)
+ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
+am__aclocal_m4_deps = $(top_srcdir)/m4/00gnulib.m4 \
+ $(top_srcdir)/m4/absolute-header.m4 $(top_srcdir)/m4/acl.m4 \
+ $(top_srcdir)/m4/alloca.m4 $(top_srcdir)/m4/argp.m4 \
+ $(top_srcdir)/m4/backupfile.m4 $(top_srcdir)/m4/bison.m4 \
+ $(top_srcdir)/m4/btowc.m4 $(top_srcdir)/m4/canonicalize.m4 \
+ $(top_srcdir)/m4/chdir-long.m4 $(top_srcdir)/m4/chown.m4 \
+ $(top_srcdir)/m4/clock_time.m4 \
+ $(top_srcdir)/m4/close-stream.m4 $(top_srcdir)/m4/close.m4 \
+ $(top_srcdir)/m4/closedir.m4 $(top_srcdir)/m4/closeout.m4 \
+ $(top_srcdir)/m4/codeset.m4 $(top_srcdir)/m4/configmake.m4 \
+ $(top_srcdir)/m4/d-ino.m4 $(top_srcdir)/m4/dirent-safer.m4 \
+ $(top_srcdir)/m4/dirent_h.m4 $(top_srcdir)/m4/dirfd.m4 \
+ $(top_srcdir)/m4/dirname.m4 \
+ $(top_srcdir)/m4/double-slash-root.m4 $(top_srcdir)/m4/dup.m4 \
+ $(top_srcdir)/m4/dup2.m4 $(top_srcdir)/m4/eealloc.m4 \
+ $(top_srcdir)/m4/environ.m4 $(top_srcdir)/m4/errno_h.m4 \
+ $(top_srcdir)/m4/error.m4 $(top_srcdir)/m4/euidaccess.m4 \
+ $(top_srcdir)/m4/exponentd.m4 $(top_srcdir)/m4/extensions.m4 \
+ $(top_srcdir)/m4/extern-inline.m4 \
+ $(top_srcdir)/m4/faccessat.m4 $(top_srcdir)/m4/fchdir.m4 \
+ $(top_srcdir)/m4/fchmodat.m4 $(top_srcdir)/m4/fchownat.m4 \
+ $(top_srcdir)/m4/fcntl-o.m4 $(top_srcdir)/m4/fcntl.m4 \
+ $(top_srcdir)/m4/fcntl_h.m4 $(top_srcdir)/m4/fdopendir.m4 \
+ $(top_srcdir)/m4/fileblocks.m4 $(top_srcdir)/m4/filenamecat.m4 \
+ $(top_srcdir)/m4/flexmember.m4 $(top_srcdir)/m4/float_h.m4 \
+ $(top_srcdir)/m4/fnmatch.m4 $(top_srcdir)/m4/fpending.m4 \
+ $(top_srcdir)/m4/fseek.m4 $(top_srcdir)/m4/fseeko.m4 \
+ $(top_srcdir)/m4/fstat.m4 $(top_srcdir)/m4/fstatat.m4 \
+ $(top_srcdir)/m4/futimens.m4 \
+ $(top_srcdir)/m4/getcwd-abort-bug.m4 \
+ $(top_srcdir)/m4/getcwd-path-max.m4 $(top_srcdir)/m4/getcwd.m4 \
+ $(top_srcdir)/m4/getdelim.m4 $(top_srcdir)/m4/getdtablesize.m4 \
+ $(top_srcdir)/m4/getgroups.m4 $(top_srcdir)/m4/getline.m4 \
+ $(top_srcdir)/m4/getopt.m4 $(top_srcdir)/m4/getpagesize.m4 \
+ $(top_srcdir)/m4/gettext.m4 $(top_srcdir)/m4/gettime.m4 \
+ $(top_srcdir)/m4/gettimeofday.m4 $(top_srcdir)/m4/glibc21.m4 \
+ $(top_srcdir)/m4/gnulib-common.m4 \
+ $(top_srcdir)/m4/gnulib-comp.m4 \
+ $(top_srcdir)/m4/group-member.m4 $(top_srcdir)/m4/human.m4 \
+ $(top_srcdir)/m4/iconv.m4 $(top_srcdir)/m4/include_next.m4 \
+ $(top_srcdir)/m4/intlmacosx.m4 $(top_srcdir)/m4/intmax_t.m4 \
+ $(top_srcdir)/m4/inttostr.m4 $(top_srcdir)/m4/inttypes-pri.m4 \
+ $(top_srcdir)/m4/inttypes.m4 $(top_srcdir)/m4/inttypes_h.m4 \
+ $(top_srcdir)/m4/iswblank.m4 $(top_srcdir)/m4/langinfo_h.m4 \
+ $(top_srcdir)/m4/largefile.m4 $(top_srcdir)/m4/lchown.m4 \
+ $(top_srcdir)/m4/lib-ld.m4 $(top_srcdir)/m4/lib-link.m4 \
+ $(top_srcdir)/m4/lib-prefix.m4 \
+ $(top_srcdir)/m4/libunistring-base.m4 \
+ $(top_srcdir)/m4/link-follow.m4 $(top_srcdir)/m4/link.m4 \
+ $(top_srcdir)/m4/linkat.m4 $(top_srcdir)/m4/localcharset.m4 \
+ $(top_srcdir)/m4/locale-fr.m4 $(top_srcdir)/m4/locale-ja.m4 \
+ $(top_srcdir)/m4/locale-zh.m4 $(top_srcdir)/m4/locale_h.m4 \
+ $(top_srcdir)/m4/localeconv.m4 $(top_srcdir)/m4/longlong.m4 \
+ $(top_srcdir)/m4/lseek.m4 $(top_srcdir)/m4/lstat.m4 \
+ $(top_srcdir)/m4/malloc.m4 $(top_srcdir)/m4/malloca.m4 \
+ $(top_srcdir)/m4/manywarnings.m4 $(top_srcdir)/m4/mbchar.m4 \
+ $(top_srcdir)/m4/mbiter.m4 $(top_srcdir)/m4/mbrtowc.m4 \
+ $(top_srcdir)/m4/mbsinit.m4 $(top_srcdir)/m4/mbsrtowcs.m4 \
+ $(top_srcdir)/m4/mbstate_t.m4 $(top_srcdir)/m4/mbtowc.m4 \
+ $(top_srcdir)/m4/memchr.m4 $(top_srcdir)/m4/mempcpy.m4 \
+ $(top_srcdir)/m4/memrchr.m4 $(top_srcdir)/m4/mkdir.m4 \
+ $(top_srcdir)/m4/mkdirat.m4 $(top_srcdir)/m4/mkdtemp.m4 \
+ $(top_srcdir)/m4/mkfifo.m4 $(top_srcdir)/m4/mkfifoat.m4 \
+ $(top_srcdir)/m4/mknod.m4 $(top_srcdir)/m4/mktime.m4 \
+ $(top_srcdir)/m4/mmap-anon.m4 $(top_srcdir)/m4/mode_t.m4 \
+ $(top_srcdir)/m4/modechange.m4 $(top_srcdir)/m4/msvc-inval.m4 \
+ $(top_srcdir)/m4/msvc-nothrow.m4 $(top_srcdir)/m4/multiarch.m4 \
+ $(top_srcdir)/m4/nl_langinfo.m4 $(top_srcdir)/m4/nls.m4 \
+ $(top_srcdir)/m4/nocrash.m4 $(top_srcdir)/m4/obstack.m4 \
+ $(top_srcdir)/m4/off_t.m4 $(top_srcdir)/m4/open.m4 \
+ $(top_srcdir)/m4/openat.m4 $(top_srcdir)/m4/opendir.m4 \
+ $(top_srcdir)/m4/parse-datetime.m4 $(top_srcdir)/m4/pathmax.m4 \
+ $(top_srcdir)/m4/paxutils.m4 $(top_srcdir)/m4/po.m4 \
+ $(top_srcdir)/m4/printf.m4 $(top_srcdir)/m4/priv-set.m4 \
+ $(top_srcdir)/m4/progtest.m4 $(top_srcdir)/m4/quote.m4 \
+ $(top_srcdir)/m4/quotearg.m4 $(top_srcdir)/m4/raise.m4 \
+ $(top_srcdir)/m4/rawmemchr.m4 $(top_srcdir)/m4/read.m4 \
+ $(top_srcdir)/m4/readdir.m4 $(top_srcdir)/m4/readlink.m4 \
+ $(top_srcdir)/m4/readlinkat.m4 $(top_srcdir)/m4/realloc.m4 \
+ $(top_srcdir)/m4/regex.m4 $(top_srcdir)/m4/rename.m4 \
+ $(top_srcdir)/m4/renameat.m4 $(top_srcdir)/m4/rewinddir.m4 \
+ $(top_srcdir)/m4/rmdir.m4 $(top_srcdir)/m4/rmt.m4 \
+ $(top_srcdir)/m4/rpmatch.m4 $(top_srcdir)/m4/rtapelib.m4 \
+ $(top_srcdir)/m4/safe-read.m4 $(top_srcdir)/m4/safe-write.m4 \
+ $(top_srcdir)/m4/save-cwd.m4 $(top_srcdir)/m4/savedir.m4 \
+ $(top_srcdir)/m4/secure_getenv.m4 \
+ $(top_srcdir)/m4/selinux-context-h.m4 \
+ $(top_srcdir)/m4/selinux-selinux-h.m4 \
+ $(top_srcdir)/m4/setenv.m4 $(top_srcdir)/m4/signal_h.m4 \
+ $(top_srcdir)/m4/size_max.m4 $(top_srcdir)/m4/sleep.m4 \
+ $(top_srcdir)/m4/snprintf.m4 $(top_srcdir)/m4/ssize_t.m4 \
+ $(top_srcdir)/m4/stat-time.m4 $(top_srcdir)/m4/stat.m4 \
+ $(top_srcdir)/m4/stdalign.m4 $(top_srcdir)/m4/stdarg.m4 \
+ $(top_srcdir)/m4/stdbool.m4 $(top_srcdir)/m4/stddef_h.m4 \
+ $(top_srcdir)/m4/stdint.m4 $(top_srcdir)/m4/stdint_h.m4 \
+ $(top_srcdir)/m4/stdio_h.m4 $(top_srcdir)/m4/stdlib_h.m4 \
+ $(top_srcdir)/m4/stpcpy.m4 $(top_srcdir)/m4/strcase.m4 \
+ $(top_srcdir)/m4/strchrnul.m4 $(top_srcdir)/m4/strdup.m4 \
+ $(top_srcdir)/m4/strerror.m4 $(top_srcdir)/m4/strftime.m4 \
+ $(top_srcdir)/m4/string_h.m4 $(top_srcdir)/m4/strings_h.m4 \
+ $(top_srcdir)/m4/strndup.m4 $(top_srcdir)/m4/strnlen.m4 \
+ $(top_srcdir)/m4/strtoimax.m4 $(top_srcdir)/m4/strtol.m4 \
+ $(top_srcdir)/m4/strtoll.m4 $(top_srcdir)/m4/strtoul.m4 \
+ $(top_srcdir)/m4/strtoull.m4 $(top_srcdir)/m4/strtoumax.m4 \
+ $(top_srcdir)/m4/symlink.m4 $(top_srcdir)/m4/symlinkat.m4 \
+ $(top_srcdir)/m4/sys_socket_h.m4 \
+ $(top_srcdir)/m4/sys_stat_h.m4 $(top_srcdir)/m4/sys_time_h.m4 \
+ $(top_srcdir)/m4/sys_types_h.m4 $(top_srcdir)/m4/sysexits.m4 \
+ $(top_srcdir)/m4/system.m4 $(top_srcdir)/m4/tempname.m4 \
+ $(top_srcdir)/m4/time_h.m4 $(top_srcdir)/m4/time_r.m4 \
+ $(top_srcdir)/m4/time_rz.m4 $(top_srcdir)/m4/timegm.m4 \
+ $(top_srcdir)/m4/timespec.m4 $(top_srcdir)/m4/tm_gmtoff.m4 \
+ $(top_srcdir)/m4/ulonglong.m4 $(top_srcdir)/m4/unistd-safer.m4 \
+ $(top_srcdir)/m4/unistd_h.m4 $(top_srcdir)/m4/unlink.m4 \
+ $(top_srcdir)/m4/unlinkat.m4 $(top_srcdir)/m4/unlinkdir.m4 \
+ $(top_srcdir)/m4/unlocked-io.m4 $(top_srcdir)/m4/utimbuf.m4 \
+ $(top_srcdir)/m4/utimens.m4 $(top_srcdir)/m4/utimensat.m4 \
+ $(top_srcdir)/m4/utimes.m4 $(top_srcdir)/m4/vasnprintf.m4 \
+ $(top_srcdir)/m4/vasprintf.m4 $(top_srcdir)/m4/version-etc.m4 \
+ $(top_srcdir)/m4/vsnprintf.m4 $(top_srcdir)/m4/warn-on-use.m4 \
+ $(top_srcdir)/m4/warnings.m4 $(top_srcdir)/m4/wchar_h.m4 \
+ $(top_srcdir)/m4/wchar_t.m4 $(top_srcdir)/m4/wcrtomb.m4 \
+ $(top_srcdir)/m4/wctype_h.m4 $(top_srcdir)/m4/wcwidth.m4 \
+ $(top_srcdir)/m4/wint_t.m4 $(top_srcdir)/m4/write.m4 \
+ $(top_srcdir)/m4/xalloc.m4 $(top_srcdir)/m4/xgetcwd.m4 \
+ $(top_srcdir)/m4/xsize.m4 $(top_srcdir)/m4/xstrndup.m4 \
+ $(top_srcdir)/m4/xstrtol.m4 $(top_srcdir)/m4/xvasprintf.m4 \
+ $(top_srcdir)/acinclude.m4 $(top_srcdir)/configure.ac
+am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \
+ $(ACLOCAL_M4)
+mkinstalldirs = $(install_sh) -d
+CONFIG_HEADER = $(top_builddir)/config.h
+CONFIG_CLEAN_FILES =
+CONFIG_CLEAN_VPATH_FILES =
+AM_V_P = $(am__v_P_@AM_V@)
+am__v_P_ = $(am__v_P_@AM_DEFAULT_V@)
+am__v_P_0 = false
+am__v_P_1 = :
+AM_V_GEN = $(am__v_GEN_@AM_V@)
+am__v_GEN_ = $(am__v_GEN_@AM_DEFAULT_V@)
+am__v_GEN_0 = @echo " GEN " $@;
+am__v_GEN_1 =
+AM_V_at = $(am__v_at_@AM_V@)
+am__v_at_ = $(am__v_at_@AM_DEFAULT_V@)
+am__v_at_0 = @
+am__v_at_1 =
+SOURCES =
+DIST_SOURCES =
+AM_V_DVIPS = $(am__v_DVIPS_@AM_V@)
+am__v_DVIPS_ = $(am__v_DVIPS_@AM_DEFAULT_V@)
+am__v_DVIPS_0 = @echo " DVIPS " $@;
+am__v_DVIPS_1 =
+AM_V_MAKEINFO = $(am__v_MAKEINFO_@AM_V@)
+am__v_MAKEINFO_ = $(am__v_MAKEINFO_@AM_DEFAULT_V@)
+am__v_MAKEINFO_0 = @echo " MAKEINFO" $@;
+am__v_MAKEINFO_1 =
+AM_V_INFOHTML = $(am__v_INFOHTML_@AM_V@)
+am__v_INFOHTML_ = $(am__v_INFOHTML_@AM_DEFAULT_V@)
+am__v_INFOHTML_0 = @echo " INFOHTML" $@;
+am__v_INFOHTML_1 =
+AM_V_TEXI2DVI = $(am__v_TEXI2DVI_@AM_V@)
+am__v_TEXI2DVI_ = $(am__v_TEXI2DVI_@AM_DEFAULT_V@)
+am__v_TEXI2DVI_0 = @echo " TEXI2DVI" $@;
+am__v_TEXI2DVI_1 =
+AM_V_TEXI2PDF = $(am__v_TEXI2PDF_@AM_V@)
+am__v_TEXI2PDF_ = $(am__v_TEXI2PDF_@AM_DEFAULT_V@)
+am__v_TEXI2PDF_0 = @echo " TEXI2PDF" $@;
+am__v_TEXI2PDF_1 =
+AM_V_texinfo = $(am__v_texinfo_@AM_V@)
+am__v_texinfo_ = $(am__v_texinfo_@AM_DEFAULT_V@)
+am__v_texinfo_0 = -q
+am__v_texinfo_1 =
+AM_V_texidevnull = $(am__v_texidevnull_@AM_V@)
+am__v_texidevnull_ = $(am__v_texidevnull_@AM_DEFAULT_V@)
+am__v_texidevnull_0 = > /dev/null
+am__v_texidevnull_1 =
+INFO_DEPS = $(srcdir)/tar.info
+TEXINFO_TEX = $(top_srcdir)/build-aux/texinfo.tex
+am__TEXINFO_TEX_DIR = $(top_srcdir)/build-aux
+DVIS = tar.dvi
+PDFS = tar.pdf
+PSS = tar.ps
+HTMLS = tar.html
+TEXINFOS = tar.texi
+TEXI2PDF = $(TEXI2DVI) --pdf --batch
+MAKEINFOHTML = $(MAKEINFO) --html
+AM_MAKEINFOHTMLFLAGS = $(AM_MAKEINFOFLAGS)
+DVIPS = dvips
+am__can_run_installinfo = \
+ case $$AM_UPDATE_INFO_DIR in \
+ n|no|NO) false;; \
+ *) (install-info --version) >/dev/null 2>&1;; \
+ esac
+am__installdirs = "$(DESTDIR)$(infodir)" "$(DESTDIR)$(man1dir)" \
+ "$(DESTDIR)$(man8dir)"
+am__vpath_adj_setup = srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`;
+am__vpath_adj = case $$p in \
+ $(srcdir)/*) f=`echo "$$p" | sed "s|^$$srcdirstrip/||"`;; \
+ *) f=$$p;; \
+ esac;
+am__strip_dir = f=`echo $$p | sed -e 's|^.*/||'`;
+am__install_max = 40
+am__nobase_strip_setup = \
+ srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*|]/\\\\&/g'`
+am__nobase_strip = \
+ for p in $$list; do echo "$$p"; done | sed -e "s|$$srcdirstrip/||"
+am__nobase_list = $(am__nobase_strip_setup); \
+ for p in $$list; do echo "$$p $$p"; done | \
+ sed "s| $$srcdirstrip/| |;"' / .*\//!s/ .*/ ./; s,\( .*\)/[^/]*$$,\1,' | \
+ $(AWK) 'BEGIN { files["."] = "" } { files[$$2] = files[$$2] " " $$1; \
+ if (++n[$$2] == $(am__install_max)) \
+ { print $$2, files[$$2]; n[$$2] = 0; files[$$2] = "" } } \
+ END { for (dir in files) print dir, files[dir] }'
+am__base_list = \
+ sed '$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;s/\n/ /g' | \
+ sed '$$!N;$$!N;$$!N;$$!N;s/\n/ /g'
+am__uninstall_files_from_dir = { \
+ test -z "$$files" \
+ || { test ! -d "$$dir" && test ! -f "$$dir" && test ! -r "$$dir"; } \
+ || { echo " ( cd '$$dir' && rm -f" $$files ")"; \
+ $(am__cd) "$$dir" && rm -f $$files; }; \
+ }
+man1dir = $(mandir)/man1
+man8dir = $(mandir)/man8
+NROFF = nroff
+MANS = $(dist_man_MANS)
+am__tagged_files = $(HEADERS) $(SOURCES) $(TAGS_FILES) $(LISP)
+DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST)
+pkglibexecdir = @pkglibexecdir@
+ACLOCAL = @ACLOCAL@
+ALLOCA = @ALLOCA@
+ALLOCA_H = @ALLOCA_H@
+AMTAR = @AMTAR@
+AM_DEFAULT_VERBOSITY = @AM_DEFAULT_VERBOSITY@
+APPLE_UNIVERSAL_BUILD = @APPLE_UNIVERSAL_BUILD@
+AR = @AR@
+ARFLAGS = @ARFLAGS@
+AUTOCONF = @AUTOCONF@
+AUTOHEADER = @AUTOHEADER@
+AUTOM4TE = @AUTOM4TE@
+AUTOMAKE = @AUTOMAKE@
+AWK = @AWK@
+BACKUP_LIBEXEC_SCRIPTS = @BACKUP_LIBEXEC_SCRIPTS@
+BACKUP_SBIN_SCRIPTS = @BACKUP_SBIN_SCRIPTS@
+BACKUP_SED_COND = @BACKUP_SED_COND@
+BITSIZEOF_PTRDIFF_T = @BITSIZEOF_PTRDIFF_T@
+BITSIZEOF_SIG_ATOMIC_T = @BITSIZEOF_SIG_ATOMIC_T@
+BITSIZEOF_SIZE_T = @BITSIZEOF_SIZE_T@
+BITSIZEOF_WCHAR_T = @BITSIZEOF_WCHAR_T@
+BITSIZEOF_WINT_T = @BITSIZEOF_WINT_T@
+CC = @CC@
+CCDEPMODE = @CCDEPMODE@
+CFLAGS = @CFLAGS@
+CPP = @CPP@
+CPPFLAGS = @CPPFLAGS@
+CYGPATH_W = @CYGPATH_W@
+DEFAULT_ARCHIVE = @DEFAULT_ARCHIVE@
+DEFAULT_ARCHIVE_FORMAT = @DEFAULT_ARCHIVE_FORMAT@
+DEFAULT_BLOCKING = @DEFAULT_BLOCKING@
+DEFAULT_QUOTING_STYLE = @DEFAULT_QUOTING_STYLE@
+DEFAULT_RMT_COMMAND = @DEFAULT_RMT_COMMAND@
+DEFAULT_RMT_DIR = @DEFAULT_RMT_DIR@
+DEFS = @DEFS@
+DEPDIR = @DEPDIR@
+ECHO_C = @ECHO_C@
+ECHO_N = @ECHO_N@
+ECHO_T = @ECHO_T@
+EGREP = @EGREP@
+EMULTIHOP_HIDDEN = @EMULTIHOP_HIDDEN@
+EMULTIHOP_VALUE = @EMULTIHOP_VALUE@
+ENOLINK_HIDDEN = @ENOLINK_HIDDEN@
+ENOLINK_VALUE = @ENOLINK_VALUE@
+EOVERFLOW_HIDDEN = @EOVERFLOW_HIDDEN@
+EOVERFLOW_VALUE = @EOVERFLOW_VALUE@
+ERRNO_H = @ERRNO_H@
+EXEEXT = @EXEEXT@
+FLOAT_H = @FLOAT_H@
+FNMATCH_H = @FNMATCH_H@
+GETOPT_H = @GETOPT_H@
+GETTEXT_MACRO_VERSION = @GETTEXT_MACRO_VERSION@
+GLIBC21 = @GLIBC21@
+GMSGFMT = @GMSGFMT@
+GMSGFMT_015 = @GMSGFMT_015@
+GNULIB_ALPHASORT = @GNULIB_ALPHASORT@
+GNULIB_ATOLL = @GNULIB_ATOLL@
+GNULIB_BTOWC = @GNULIB_BTOWC@
+GNULIB_CALLOC_POSIX = @GNULIB_CALLOC_POSIX@
+GNULIB_CANONICALIZE_FILE_NAME = @GNULIB_CANONICALIZE_FILE_NAME@
+GNULIB_CHDIR = @GNULIB_CHDIR@
+GNULIB_CHOWN = @GNULIB_CHOWN@
+GNULIB_CLOSE = @GNULIB_CLOSE@
+GNULIB_CLOSEDIR = @GNULIB_CLOSEDIR@
+GNULIB_DIRFD = @GNULIB_DIRFD@
+GNULIB_DPRINTF = @GNULIB_DPRINTF@
+GNULIB_DUP = @GNULIB_DUP@
+GNULIB_DUP2 = @GNULIB_DUP2@
+GNULIB_DUP3 = @GNULIB_DUP3@
+GNULIB_DUPLOCALE = @GNULIB_DUPLOCALE@
+GNULIB_ENVIRON = @GNULIB_ENVIRON@
+GNULIB_EUIDACCESS = @GNULIB_EUIDACCESS@
+GNULIB_FACCESSAT = @GNULIB_FACCESSAT@
+GNULIB_FCHDIR = @GNULIB_FCHDIR@
+GNULIB_FCHMODAT = @GNULIB_FCHMODAT@
+GNULIB_FCHOWNAT = @GNULIB_FCHOWNAT@
+GNULIB_FCLOSE = @GNULIB_FCLOSE@
+GNULIB_FCNTL = @GNULIB_FCNTL@
+GNULIB_FDATASYNC = @GNULIB_FDATASYNC@
+GNULIB_FDOPEN = @GNULIB_FDOPEN@
+GNULIB_FDOPENDIR = @GNULIB_FDOPENDIR@
+GNULIB_FFLUSH = @GNULIB_FFLUSH@
+GNULIB_FFS = @GNULIB_FFS@
+GNULIB_FFSL = @GNULIB_FFSL@
+GNULIB_FFSLL = @GNULIB_FFSLL@
+GNULIB_FGETC = @GNULIB_FGETC@
+GNULIB_FGETS = @GNULIB_FGETS@
+GNULIB_FOPEN = @GNULIB_FOPEN@
+GNULIB_FPRINTF = @GNULIB_FPRINTF@
+GNULIB_FPRINTF_POSIX = @GNULIB_FPRINTF_POSIX@
+GNULIB_FPURGE = @GNULIB_FPURGE@
+GNULIB_FPUTC = @GNULIB_FPUTC@
+GNULIB_FPUTS = @GNULIB_FPUTS@
+GNULIB_FREAD = @GNULIB_FREAD@
+GNULIB_FREOPEN = @GNULIB_FREOPEN@
+GNULIB_FSCANF = @GNULIB_FSCANF@
+GNULIB_FSEEK = @GNULIB_FSEEK@
+GNULIB_FSEEKO = @GNULIB_FSEEKO@
+GNULIB_FSTAT = @GNULIB_FSTAT@
+GNULIB_FSTATAT = @GNULIB_FSTATAT@
+GNULIB_FSYNC = @GNULIB_FSYNC@
+GNULIB_FTELL = @GNULIB_FTELL@
+GNULIB_FTELLO = @GNULIB_FTELLO@
+GNULIB_FTRUNCATE = @GNULIB_FTRUNCATE@
+GNULIB_FUTIMENS = @GNULIB_FUTIMENS@
+GNULIB_FWRITE = @GNULIB_FWRITE@
+GNULIB_GETC = @GNULIB_GETC@
+GNULIB_GETCHAR = @GNULIB_GETCHAR@
+GNULIB_GETCWD = @GNULIB_GETCWD@
+GNULIB_GETDELIM = @GNULIB_GETDELIM@
+GNULIB_GETDOMAINNAME = @GNULIB_GETDOMAINNAME@
+GNULIB_GETDTABLESIZE = @GNULIB_GETDTABLESIZE@
+GNULIB_GETGROUPS = @GNULIB_GETGROUPS@
+GNULIB_GETHOSTNAME = @GNULIB_GETHOSTNAME@
+GNULIB_GETLINE = @GNULIB_GETLINE@
+GNULIB_GETLOADAVG = @GNULIB_GETLOADAVG@
+GNULIB_GETLOGIN = @GNULIB_GETLOGIN@
+GNULIB_GETLOGIN_R = @GNULIB_GETLOGIN_R@
+GNULIB_GETPAGESIZE = @GNULIB_GETPAGESIZE@
+GNULIB_GETSUBOPT = @GNULIB_GETSUBOPT@
+GNULIB_GETTIMEOFDAY = @GNULIB_GETTIMEOFDAY@
+GNULIB_GETUSERSHELL = @GNULIB_GETUSERSHELL@
+GNULIB_GL_UNISTD_H_GETOPT = @GNULIB_GL_UNISTD_H_GETOPT@
+GNULIB_GRANTPT = @GNULIB_GRANTPT@
+GNULIB_GROUP_MEMBER = @GNULIB_GROUP_MEMBER@
+GNULIB_IMAXABS = @GNULIB_IMAXABS@
+GNULIB_IMAXDIV = @GNULIB_IMAXDIV@
+GNULIB_ISATTY = @GNULIB_ISATTY@
+GNULIB_ISWBLANK = @GNULIB_ISWBLANK@
+GNULIB_ISWCTYPE = @GNULIB_ISWCTYPE@
+GNULIB_LCHMOD = @GNULIB_LCHMOD@
+GNULIB_LCHOWN = @GNULIB_LCHOWN@
+GNULIB_LINK = @GNULIB_LINK@
+GNULIB_LINKAT = @GNULIB_LINKAT@
+GNULIB_LOCALECONV = @GNULIB_LOCALECONV@
+GNULIB_LSEEK = @GNULIB_LSEEK@
+GNULIB_LSTAT = @GNULIB_LSTAT@
+GNULIB_MALLOC_POSIX = @GNULIB_MALLOC_POSIX@
+GNULIB_MBRLEN = @GNULIB_MBRLEN@
+GNULIB_MBRTOWC = @GNULIB_MBRTOWC@
+GNULIB_MBSCASECMP = @GNULIB_MBSCASECMP@
+GNULIB_MBSCASESTR = @GNULIB_MBSCASESTR@
+GNULIB_MBSCHR = @GNULIB_MBSCHR@
+GNULIB_MBSCSPN = @GNULIB_MBSCSPN@
+GNULIB_MBSINIT = @GNULIB_MBSINIT@
+GNULIB_MBSLEN = @GNULIB_MBSLEN@
+GNULIB_MBSNCASECMP = @GNULIB_MBSNCASECMP@
+GNULIB_MBSNLEN = @GNULIB_MBSNLEN@
+GNULIB_MBSNRTOWCS = @GNULIB_MBSNRTOWCS@
+GNULIB_MBSPBRK = @GNULIB_MBSPBRK@
+GNULIB_MBSPCASECMP = @GNULIB_MBSPCASECMP@
+GNULIB_MBSRCHR = @GNULIB_MBSRCHR@
+GNULIB_MBSRTOWCS = @GNULIB_MBSRTOWCS@
+GNULIB_MBSSEP = @GNULIB_MBSSEP@
+GNULIB_MBSSPN = @GNULIB_MBSSPN@
+GNULIB_MBSSTR = @GNULIB_MBSSTR@
+GNULIB_MBSTOK_R = @GNULIB_MBSTOK_R@
+GNULIB_MBTOWC = @GNULIB_MBTOWC@
+GNULIB_MEMCHR = @GNULIB_MEMCHR@
+GNULIB_MEMMEM = @GNULIB_MEMMEM@
+GNULIB_MEMPCPY = @GNULIB_MEMPCPY@
+GNULIB_MEMRCHR = @GNULIB_MEMRCHR@
+GNULIB_MKDIRAT = @GNULIB_MKDIRAT@
+GNULIB_MKDTEMP = @GNULIB_MKDTEMP@
+GNULIB_MKFIFO = @GNULIB_MKFIFO@
+GNULIB_MKFIFOAT = @GNULIB_MKFIFOAT@
+GNULIB_MKNOD = @GNULIB_MKNOD@
+GNULIB_MKNODAT = @GNULIB_MKNODAT@
+GNULIB_MKOSTEMP = @GNULIB_MKOSTEMP@
+GNULIB_MKOSTEMPS = @GNULIB_MKOSTEMPS@
+GNULIB_MKSTEMP = @GNULIB_MKSTEMP@
+GNULIB_MKSTEMPS = @GNULIB_MKSTEMPS@
+GNULIB_MKTIME = @GNULIB_MKTIME@
+GNULIB_NANOSLEEP = @GNULIB_NANOSLEEP@
+GNULIB_NL_LANGINFO = @GNULIB_NL_LANGINFO@
+GNULIB_NONBLOCKING = @GNULIB_NONBLOCKING@
+GNULIB_OBSTACK_PRINTF = @GNULIB_OBSTACK_PRINTF@
+GNULIB_OBSTACK_PRINTF_POSIX = @GNULIB_OBSTACK_PRINTF_POSIX@
+GNULIB_OPEN = @GNULIB_OPEN@
+GNULIB_OPENAT = @GNULIB_OPENAT@
+GNULIB_OPENDIR = @GNULIB_OPENDIR@
+GNULIB_PCLOSE = @GNULIB_PCLOSE@
+GNULIB_PERROR = @GNULIB_PERROR@
+GNULIB_PIPE = @GNULIB_PIPE@
+GNULIB_PIPE2 = @GNULIB_PIPE2@
+GNULIB_POPEN = @GNULIB_POPEN@
+GNULIB_POSIX_OPENPT = @GNULIB_POSIX_OPENPT@
+GNULIB_PREAD = @GNULIB_PREAD@
+GNULIB_PRINTF = @GNULIB_PRINTF@
+GNULIB_PRINTF_POSIX = @GNULIB_PRINTF_POSIX@
+GNULIB_PTHREAD_SIGMASK = @GNULIB_PTHREAD_SIGMASK@
+GNULIB_PTSNAME = @GNULIB_PTSNAME@
+GNULIB_PTSNAME_R = @GNULIB_PTSNAME_R@
+GNULIB_PUTC = @GNULIB_PUTC@
+GNULIB_PUTCHAR = @GNULIB_PUTCHAR@
+GNULIB_PUTENV = @GNULIB_PUTENV@
+GNULIB_PUTS = @GNULIB_PUTS@
+GNULIB_PWRITE = @GNULIB_PWRITE@
+GNULIB_QSORT_R = @GNULIB_QSORT_R@
+GNULIB_RAISE = @GNULIB_RAISE@
+GNULIB_RANDOM = @GNULIB_RANDOM@
+GNULIB_RANDOM_R = @GNULIB_RANDOM_R@
+GNULIB_RAWMEMCHR = @GNULIB_RAWMEMCHR@
+GNULIB_READ = @GNULIB_READ@
+GNULIB_READDIR = @GNULIB_READDIR@
+GNULIB_READLINK = @GNULIB_READLINK@
+GNULIB_READLINKAT = @GNULIB_READLINKAT@
+GNULIB_REALLOC_POSIX = @GNULIB_REALLOC_POSIX@
+GNULIB_REALPATH = @GNULIB_REALPATH@
+GNULIB_REMOVE = @GNULIB_REMOVE@
+GNULIB_RENAME = @GNULIB_RENAME@
+GNULIB_RENAMEAT = @GNULIB_RENAMEAT@
+GNULIB_REWINDDIR = @GNULIB_REWINDDIR@
+GNULIB_RMDIR = @GNULIB_RMDIR@
+GNULIB_RPMATCH = @GNULIB_RPMATCH@
+GNULIB_SCANDIR = @GNULIB_SCANDIR@
+GNULIB_SCANF = @GNULIB_SCANF@
+GNULIB_SECURE_GETENV = @GNULIB_SECURE_GETENV@
+GNULIB_SETENV = @GNULIB_SETENV@
+GNULIB_SETHOSTNAME = @GNULIB_SETHOSTNAME@
+GNULIB_SETLOCALE = @GNULIB_SETLOCALE@
+GNULIB_SIGACTION = @GNULIB_SIGACTION@
+GNULIB_SIGNAL_H_SIGPIPE = @GNULIB_SIGNAL_H_SIGPIPE@
+GNULIB_SIGPROCMASK = @GNULIB_SIGPROCMASK@
+GNULIB_SLEEP = @GNULIB_SLEEP@
+GNULIB_SNPRINTF = @GNULIB_SNPRINTF@
+GNULIB_SPRINTF_POSIX = @GNULIB_SPRINTF_POSIX@
+GNULIB_STAT = @GNULIB_STAT@
+GNULIB_STDIO_H_NONBLOCKING = @GNULIB_STDIO_H_NONBLOCKING@
+GNULIB_STDIO_H_SIGPIPE = @GNULIB_STDIO_H_SIGPIPE@
+GNULIB_STPCPY = @GNULIB_STPCPY@
+GNULIB_STPNCPY = @GNULIB_STPNCPY@
+GNULIB_STRCASESTR = @GNULIB_STRCASESTR@
+GNULIB_STRCHRNUL = @GNULIB_STRCHRNUL@
+GNULIB_STRDUP = @GNULIB_STRDUP@
+GNULIB_STRERROR = @GNULIB_STRERROR@
+GNULIB_STRERROR_R = @GNULIB_STRERROR_R@
+GNULIB_STRNCAT = @GNULIB_STRNCAT@
+GNULIB_STRNDUP = @GNULIB_STRNDUP@
+GNULIB_STRNLEN = @GNULIB_STRNLEN@
+GNULIB_STRPBRK = @GNULIB_STRPBRK@
+GNULIB_STRPTIME = @GNULIB_STRPTIME@
+GNULIB_STRSEP = @GNULIB_STRSEP@
+GNULIB_STRSIGNAL = @GNULIB_STRSIGNAL@
+GNULIB_STRSTR = @GNULIB_STRSTR@
+GNULIB_STRTOD = @GNULIB_STRTOD@
+GNULIB_STRTOIMAX = @GNULIB_STRTOIMAX@
+GNULIB_STRTOK_R = @GNULIB_STRTOK_R@
+GNULIB_STRTOLL = @GNULIB_STRTOLL@
+GNULIB_STRTOULL = @GNULIB_STRTOULL@
+GNULIB_STRTOUMAX = @GNULIB_STRTOUMAX@
+GNULIB_STRVERSCMP = @GNULIB_STRVERSCMP@
+GNULIB_SYMLINK = @GNULIB_SYMLINK@
+GNULIB_SYMLINKAT = @GNULIB_SYMLINKAT@
+GNULIB_SYSTEM_POSIX = @GNULIB_SYSTEM_POSIX@
+GNULIB_TEST_WARN_CFLAGS = @GNULIB_TEST_WARN_CFLAGS@
+GNULIB_TIMEGM = @GNULIB_TIMEGM@
+GNULIB_TIME_R = @GNULIB_TIME_R@
+GNULIB_TIME_RZ = @GNULIB_TIME_RZ@
+GNULIB_TMPFILE = @GNULIB_TMPFILE@
+GNULIB_TOWCTRANS = @GNULIB_TOWCTRANS@
+GNULIB_TTYNAME_R = @GNULIB_TTYNAME_R@
+GNULIB_UNISTD_H_NONBLOCKING = @GNULIB_UNISTD_H_NONBLOCKING@
+GNULIB_UNISTD_H_SIGPIPE = @GNULIB_UNISTD_H_SIGPIPE@
+GNULIB_UNLINK = @GNULIB_UNLINK@
+GNULIB_UNLINKAT = @GNULIB_UNLINKAT@
+GNULIB_UNLOCKPT = @GNULIB_UNLOCKPT@
+GNULIB_UNSETENV = @GNULIB_UNSETENV@
+GNULIB_USLEEP = @GNULIB_USLEEP@
+GNULIB_UTIMENSAT = @GNULIB_UTIMENSAT@
+GNULIB_VASPRINTF = @GNULIB_VASPRINTF@
+GNULIB_VDPRINTF = @GNULIB_VDPRINTF@
+GNULIB_VFPRINTF = @GNULIB_VFPRINTF@
+GNULIB_VFPRINTF_POSIX = @GNULIB_VFPRINTF_POSIX@
+GNULIB_VFSCANF = @GNULIB_VFSCANF@
+GNULIB_VPRINTF = @GNULIB_VPRINTF@
+GNULIB_VPRINTF_POSIX = @GNULIB_VPRINTF_POSIX@
+GNULIB_VSCANF = @GNULIB_VSCANF@
+GNULIB_VSNPRINTF = @GNULIB_VSNPRINTF@
+GNULIB_VSPRINTF_POSIX = @GNULIB_VSPRINTF_POSIX@
+GNULIB_WARN_CFLAGS = @GNULIB_WARN_CFLAGS@
+GNULIB_WCPCPY = @GNULIB_WCPCPY@
+GNULIB_WCPNCPY = @GNULIB_WCPNCPY@
+GNULIB_WCRTOMB = @GNULIB_WCRTOMB@
+GNULIB_WCSCASECMP = @GNULIB_WCSCASECMP@
+GNULIB_WCSCAT = @GNULIB_WCSCAT@
+GNULIB_WCSCHR = @GNULIB_WCSCHR@
+GNULIB_WCSCMP = @GNULIB_WCSCMP@
+GNULIB_WCSCOLL = @GNULIB_WCSCOLL@
+GNULIB_WCSCPY = @GNULIB_WCSCPY@
+GNULIB_WCSCSPN = @GNULIB_WCSCSPN@
+GNULIB_WCSDUP = @GNULIB_WCSDUP@
+GNULIB_WCSLEN = @GNULIB_WCSLEN@
+GNULIB_WCSNCASECMP = @GNULIB_WCSNCASECMP@
+GNULIB_WCSNCAT = @GNULIB_WCSNCAT@
+GNULIB_WCSNCMP = @GNULIB_WCSNCMP@
+GNULIB_WCSNCPY = @GNULIB_WCSNCPY@
+GNULIB_WCSNLEN = @GNULIB_WCSNLEN@
+GNULIB_WCSNRTOMBS = @GNULIB_WCSNRTOMBS@
+GNULIB_WCSPBRK = @GNULIB_WCSPBRK@
+GNULIB_WCSRCHR = @GNULIB_WCSRCHR@
+GNULIB_WCSRTOMBS = @GNULIB_WCSRTOMBS@
+GNULIB_WCSSPN = @GNULIB_WCSSPN@
+GNULIB_WCSSTR = @GNULIB_WCSSTR@
+GNULIB_WCSTOK = @GNULIB_WCSTOK@
+GNULIB_WCSWIDTH = @GNULIB_WCSWIDTH@
+GNULIB_WCSXFRM = @GNULIB_WCSXFRM@
+GNULIB_WCTOB = @GNULIB_WCTOB@
+GNULIB_WCTOMB = @GNULIB_WCTOMB@
+GNULIB_WCTRANS = @GNULIB_WCTRANS@
+GNULIB_WCTYPE = @GNULIB_WCTYPE@
+GNULIB_WCWIDTH = @GNULIB_WCWIDTH@
+GNULIB_WMEMCHR = @GNULIB_WMEMCHR@
+GNULIB_WMEMCMP = @GNULIB_WMEMCMP@
+GNULIB_WMEMCPY = @GNULIB_WMEMCPY@
+GNULIB_WMEMMOVE = @GNULIB_WMEMMOVE@
+GNULIB_WMEMSET = @GNULIB_WMEMSET@
+GNULIB_WRITE = @GNULIB_WRITE@
+GNULIB__EXIT = @GNULIB__EXIT@
+GREP = @GREP@
+HAVE_ALPHASORT = @HAVE_ALPHASORT@
+HAVE_ATOLL = @HAVE_ATOLL@
+HAVE_BTOWC = @HAVE_BTOWC@
+HAVE_CANONICALIZE_FILE_NAME = @HAVE_CANONICALIZE_FILE_NAME@
+HAVE_CHOWN = @HAVE_CHOWN@
+HAVE_CLOSEDIR = @HAVE_CLOSEDIR@
+HAVE_DECL_DIRFD = @HAVE_DECL_DIRFD@
+HAVE_DECL_ENVIRON = @HAVE_DECL_ENVIRON@
+HAVE_DECL_FCHDIR = @HAVE_DECL_FCHDIR@
+HAVE_DECL_FDATASYNC = @HAVE_DECL_FDATASYNC@
+HAVE_DECL_FDOPENDIR = @HAVE_DECL_FDOPENDIR@
+HAVE_DECL_FPURGE = @HAVE_DECL_FPURGE@
+HAVE_DECL_FSEEKO = @HAVE_DECL_FSEEKO@
+HAVE_DECL_FTELLO = @HAVE_DECL_FTELLO@
+HAVE_DECL_GETDELIM = @HAVE_DECL_GETDELIM@
+HAVE_DECL_GETDOMAINNAME = @HAVE_DECL_GETDOMAINNAME@
+HAVE_DECL_GETLINE = @HAVE_DECL_GETLINE@
+HAVE_DECL_GETLOADAVG = @HAVE_DECL_GETLOADAVG@
+HAVE_DECL_GETLOGIN_R = @HAVE_DECL_GETLOGIN_R@
+HAVE_DECL_GETPAGESIZE = @HAVE_DECL_GETPAGESIZE@
+HAVE_DECL_GETUSERSHELL = @HAVE_DECL_GETUSERSHELL@
+HAVE_DECL_IMAXABS = @HAVE_DECL_IMAXABS@
+HAVE_DECL_IMAXDIV = @HAVE_DECL_IMAXDIV@
+HAVE_DECL_LOCALTIME_R = @HAVE_DECL_LOCALTIME_R@
+HAVE_DECL_MEMMEM = @HAVE_DECL_MEMMEM@
+HAVE_DECL_MEMRCHR = @HAVE_DECL_MEMRCHR@
+HAVE_DECL_OBSTACK_PRINTF = @HAVE_DECL_OBSTACK_PRINTF@
+HAVE_DECL_SETENV = @HAVE_DECL_SETENV@
+HAVE_DECL_SETHOSTNAME = @HAVE_DECL_SETHOSTNAME@
+HAVE_DECL_SNPRINTF = @HAVE_DECL_SNPRINTF@
+HAVE_DECL_STRDUP = @HAVE_DECL_STRDUP@
+HAVE_DECL_STRERROR_R = @HAVE_DECL_STRERROR_R@
+HAVE_DECL_STRNCASECMP = @HAVE_DECL_STRNCASECMP@
+HAVE_DECL_STRNDUP = @HAVE_DECL_STRNDUP@
+HAVE_DECL_STRNLEN = @HAVE_DECL_STRNLEN@
+HAVE_DECL_STRSIGNAL = @HAVE_DECL_STRSIGNAL@
+HAVE_DECL_STRTOIMAX = @HAVE_DECL_STRTOIMAX@
+HAVE_DECL_STRTOK_R = @HAVE_DECL_STRTOK_R@
+HAVE_DECL_STRTOUMAX = @HAVE_DECL_STRTOUMAX@
+HAVE_DECL_TTYNAME_R = @HAVE_DECL_TTYNAME_R@
+HAVE_DECL_UNSETENV = @HAVE_DECL_UNSETENV@
+HAVE_DECL_VSNPRINTF = @HAVE_DECL_VSNPRINTF@
+HAVE_DECL_WCTOB = @HAVE_DECL_WCTOB@
+HAVE_DECL_WCWIDTH = @HAVE_DECL_WCWIDTH@
+HAVE_DIRENT_H = @HAVE_DIRENT_H@
+HAVE_DPRINTF = @HAVE_DPRINTF@
+HAVE_DUP2 = @HAVE_DUP2@
+HAVE_DUP3 = @HAVE_DUP3@
+HAVE_DUPLOCALE = @HAVE_DUPLOCALE@
+HAVE_EUIDACCESS = @HAVE_EUIDACCESS@
+HAVE_FACCESSAT = @HAVE_FACCESSAT@
+HAVE_FCHDIR = @HAVE_FCHDIR@
+HAVE_FCHMODAT = @HAVE_FCHMODAT@
+HAVE_FCHOWNAT = @HAVE_FCHOWNAT@
+HAVE_FCNTL = @HAVE_FCNTL@
+HAVE_FDATASYNC = @HAVE_FDATASYNC@
+HAVE_FDOPENDIR = @HAVE_FDOPENDIR@
+HAVE_FEATURES_H = @HAVE_FEATURES_H@
+HAVE_FFS = @HAVE_FFS@
+HAVE_FFSL = @HAVE_FFSL@
+HAVE_FFSLL = @HAVE_FFSLL@
+HAVE_FSEEKO = @HAVE_FSEEKO@
+HAVE_FSTATAT = @HAVE_FSTATAT@
+HAVE_FSYNC = @HAVE_FSYNC@
+HAVE_FTELLO = @HAVE_FTELLO@
+HAVE_FTRUNCATE = @HAVE_FTRUNCATE@
+HAVE_FUTIMENS = @HAVE_FUTIMENS@
+HAVE_GETDTABLESIZE = @HAVE_GETDTABLESIZE@
+HAVE_GETGROUPS = @HAVE_GETGROUPS@
+HAVE_GETHOSTNAME = @HAVE_GETHOSTNAME@
+HAVE_GETLOGIN = @HAVE_GETLOGIN@
+HAVE_GETOPT_H = @HAVE_GETOPT_H@
+HAVE_GETPAGESIZE = @HAVE_GETPAGESIZE@
+HAVE_GETSUBOPT = @HAVE_GETSUBOPT@
+HAVE_GETTIMEOFDAY = @HAVE_GETTIMEOFDAY@
+HAVE_GRANTPT = @HAVE_GRANTPT@
+HAVE_GROUP_MEMBER = @HAVE_GROUP_MEMBER@
+HAVE_INTTYPES_H = @HAVE_INTTYPES_H@
+HAVE_ISWBLANK = @HAVE_ISWBLANK@
+HAVE_ISWCNTRL = @HAVE_ISWCNTRL@
+HAVE_LANGINFO_CODESET = @HAVE_LANGINFO_CODESET@
+HAVE_LANGINFO_ERA = @HAVE_LANGINFO_ERA@
+HAVE_LANGINFO_H = @HAVE_LANGINFO_H@
+HAVE_LANGINFO_T_FMT_AMPM = @HAVE_LANGINFO_T_FMT_AMPM@
+HAVE_LANGINFO_YESEXPR = @HAVE_LANGINFO_YESEXPR@
+HAVE_LCHMOD = @HAVE_LCHMOD@
+HAVE_LCHOWN = @HAVE_LCHOWN@
+HAVE_LINK = @HAVE_LINK@
+HAVE_LINKAT = @HAVE_LINKAT@
+HAVE_LONG_LONG_INT = @HAVE_LONG_LONG_INT@
+HAVE_LSTAT = @HAVE_LSTAT@
+HAVE_MAX_ALIGN_T = @HAVE_MAX_ALIGN_T@
+HAVE_MBRLEN = @HAVE_MBRLEN@
+HAVE_MBRTOWC = @HAVE_MBRTOWC@
+HAVE_MBSINIT = @HAVE_MBSINIT@
+HAVE_MBSLEN = @HAVE_MBSLEN@
+HAVE_MBSNRTOWCS = @HAVE_MBSNRTOWCS@
+HAVE_MBSRTOWCS = @HAVE_MBSRTOWCS@
+HAVE_MEMCHR = @HAVE_MEMCHR@
+HAVE_MEMPCPY = @HAVE_MEMPCPY@
+HAVE_MKDIRAT = @HAVE_MKDIRAT@
+HAVE_MKDTEMP = @HAVE_MKDTEMP@
+HAVE_MKFIFO = @HAVE_MKFIFO@
+HAVE_MKFIFOAT = @HAVE_MKFIFOAT@
+HAVE_MKNOD = @HAVE_MKNOD@
+HAVE_MKNODAT = @HAVE_MKNODAT@
+HAVE_MKOSTEMP = @HAVE_MKOSTEMP@
+HAVE_MKOSTEMPS = @HAVE_MKOSTEMPS@
+HAVE_MKSTEMP = @HAVE_MKSTEMP@
+HAVE_MKSTEMPS = @HAVE_MKSTEMPS@
+HAVE_MSVC_INVALID_PARAMETER_HANDLER = @HAVE_MSVC_INVALID_PARAMETER_HANDLER@
+HAVE_NANOSLEEP = @HAVE_NANOSLEEP@
+HAVE_NL_LANGINFO = @HAVE_NL_LANGINFO@
+HAVE_OPENAT = @HAVE_OPENAT@
+HAVE_OPENDIR = @HAVE_OPENDIR@
+HAVE_OS_H = @HAVE_OS_H@
+HAVE_PCLOSE = @HAVE_PCLOSE@
+HAVE_PIPE = @HAVE_PIPE@
+HAVE_PIPE2 = @HAVE_PIPE2@
+HAVE_POPEN = @HAVE_POPEN@
+HAVE_POSIX_OPENPT = @HAVE_POSIX_OPENPT@
+HAVE_POSIX_SIGNALBLOCKING = @HAVE_POSIX_SIGNALBLOCKING@
+HAVE_PREAD = @HAVE_PREAD@
+HAVE_PTHREAD_SIGMASK = @HAVE_PTHREAD_SIGMASK@
+HAVE_PTSNAME = @HAVE_PTSNAME@
+HAVE_PTSNAME_R = @HAVE_PTSNAME_R@
+HAVE_PWRITE = @HAVE_PWRITE@
+HAVE_RAISE = @HAVE_RAISE@
+HAVE_RANDOM = @HAVE_RANDOM@
+HAVE_RANDOM_H = @HAVE_RANDOM_H@
+HAVE_RANDOM_R = @HAVE_RANDOM_R@
+HAVE_RAWMEMCHR = @HAVE_RAWMEMCHR@
+HAVE_READDIR = @HAVE_READDIR@
+HAVE_READLINK = @HAVE_READLINK@
+HAVE_READLINKAT = @HAVE_READLINKAT@
+HAVE_REALPATH = @HAVE_REALPATH@
+HAVE_RENAMEAT = @HAVE_RENAMEAT@
+HAVE_REWINDDIR = @HAVE_REWINDDIR@
+HAVE_RPMATCH = @HAVE_RPMATCH@
+HAVE_SCANDIR = @HAVE_SCANDIR@
+HAVE_SECURE_GETENV = @HAVE_SECURE_GETENV@
+HAVE_SETENV = @HAVE_SETENV@
+HAVE_SETHOSTNAME = @HAVE_SETHOSTNAME@
+HAVE_SIGACTION = @HAVE_SIGACTION@
+HAVE_SIGHANDLER_T = @HAVE_SIGHANDLER_T@
+HAVE_SIGINFO_T = @HAVE_SIGINFO_T@
+HAVE_SIGNED_SIG_ATOMIC_T = @HAVE_SIGNED_SIG_ATOMIC_T@
+HAVE_SIGNED_WCHAR_T = @HAVE_SIGNED_WCHAR_T@
+HAVE_SIGNED_WINT_T = @HAVE_SIGNED_WINT_T@
+HAVE_SIGSET_T = @HAVE_SIGSET_T@
+HAVE_SLEEP = @HAVE_SLEEP@
+HAVE_STDINT_H = @HAVE_STDINT_H@
+HAVE_STPCPY = @HAVE_STPCPY@
+HAVE_STPNCPY = @HAVE_STPNCPY@
+HAVE_STRCASECMP = @HAVE_STRCASECMP@
+HAVE_STRCASESTR = @HAVE_STRCASESTR@
+HAVE_STRCHRNUL = @HAVE_STRCHRNUL@
+HAVE_STRINGS_H = @HAVE_STRINGS_H@
+HAVE_STRPBRK = @HAVE_STRPBRK@
+HAVE_STRPTIME = @HAVE_STRPTIME@
+HAVE_STRSEP = @HAVE_STRSEP@
+HAVE_STRTOD = @HAVE_STRTOD@
+HAVE_STRTOLL = @HAVE_STRTOLL@
+HAVE_STRTOULL = @HAVE_STRTOULL@
+HAVE_STRUCT_RANDOM_DATA = @HAVE_STRUCT_RANDOM_DATA@
+HAVE_STRUCT_SIGACTION_SA_SIGACTION = @HAVE_STRUCT_SIGACTION_SA_SIGACTION@
+HAVE_STRUCT_TIMEVAL = @HAVE_STRUCT_TIMEVAL@
+HAVE_STRVERSCMP = @HAVE_STRVERSCMP@
+HAVE_SYMLINK = @HAVE_SYMLINK@
+HAVE_SYMLINKAT = @HAVE_SYMLINKAT@
+HAVE_SYSEXITS_H = @HAVE_SYSEXITS_H@
+HAVE_SYS_BITYPES_H = @HAVE_SYS_BITYPES_H@
+HAVE_SYS_INTTYPES_H = @HAVE_SYS_INTTYPES_H@
+HAVE_SYS_LOADAVG_H = @HAVE_SYS_LOADAVG_H@
+HAVE_SYS_PARAM_H = @HAVE_SYS_PARAM_H@
+HAVE_SYS_TIME_H = @HAVE_SYS_TIME_H@
+HAVE_SYS_TYPES_H = @HAVE_SYS_TYPES_H@
+HAVE_TIMEGM = @HAVE_TIMEGM@
+HAVE_TIMEZONE_T = @HAVE_TIMEZONE_T@
+HAVE_TYPE_VOLATILE_SIG_ATOMIC_T = @HAVE_TYPE_VOLATILE_SIG_ATOMIC_T@
+HAVE_UNISTD_H = @HAVE_UNISTD_H@
+HAVE_UNLINKAT = @HAVE_UNLINKAT@
+HAVE_UNLOCKPT = @HAVE_UNLOCKPT@
+HAVE_UNSIGNED_LONG_LONG_INT = @HAVE_UNSIGNED_LONG_LONG_INT@
+HAVE_USLEEP = @HAVE_USLEEP@
+HAVE_UTIMENSAT = @HAVE_UTIMENSAT@
+HAVE_VASPRINTF = @HAVE_VASPRINTF@
+HAVE_VDPRINTF = @HAVE_VDPRINTF@
+HAVE_WCHAR_H = @HAVE_WCHAR_H@
+HAVE_WCHAR_T = @HAVE_WCHAR_T@
+HAVE_WCPCPY = @HAVE_WCPCPY@
+HAVE_WCPNCPY = @HAVE_WCPNCPY@
+HAVE_WCRTOMB = @HAVE_WCRTOMB@
+HAVE_WCSCASECMP = @HAVE_WCSCASECMP@
+HAVE_WCSCAT = @HAVE_WCSCAT@
+HAVE_WCSCHR = @HAVE_WCSCHR@
+HAVE_WCSCMP = @HAVE_WCSCMP@
+HAVE_WCSCOLL = @HAVE_WCSCOLL@
+HAVE_WCSCPY = @HAVE_WCSCPY@
+HAVE_WCSCSPN = @HAVE_WCSCSPN@
+HAVE_WCSDUP = @HAVE_WCSDUP@
+HAVE_WCSLEN = @HAVE_WCSLEN@
+HAVE_WCSNCASECMP = @HAVE_WCSNCASECMP@
+HAVE_WCSNCAT = @HAVE_WCSNCAT@
+HAVE_WCSNCMP = @HAVE_WCSNCMP@
+HAVE_WCSNCPY = @HAVE_WCSNCPY@
+HAVE_WCSNLEN = @HAVE_WCSNLEN@
+HAVE_WCSNRTOMBS = @HAVE_WCSNRTOMBS@
+HAVE_WCSPBRK = @HAVE_WCSPBRK@
+HAVE_WCSRCHR = @HAVE_WCSRCHR@
+HAVE_WCSRTOMBS = @HAVE_WCSRTOMBS@
+HAVE_WCSSPN = @HAVE_WCSSPN@
+HAVE_WCSSTR = @HAVE_WCSSTR@
+HAVE_WCSTOK = @HAVE_WCSTOK@
+HAVE_WCSWIDTH = @HAVE_WCSWIDTH@
+HAVE_WCSXFRM = @HAVE_WCSXFRM@
+HAVE_WCTRANS_T = @HAVE_WCTRANS_T@
+HAVE_WCTYPE_H = @HAVE_WCTYPE_H@
+HAVE_WCTYPE_T = @HAVE_WCTYPE_T@
+HAVE_WINSOCK2_H = @HAVE_WINSOCK2_H@
+HAVE_WINT_T = @HAVE_WINT_T@
+HAVE_WMEMCHR = @HAVE_WMEMCHR@
+HAVE_WMEMCMP = @HAVE_WMEMCMP@
+HAVE_WMEMCPY = @HAVE_WMEMCPY@
+HAVE_WMEMMOVE = @HAVE_WMEMMOVE@
+HAVE_WMEMSET = @HAVE_WMEMSET@
+HAVE_XLOCALE_H = @HAVE_XLOCALE_H@
+HAVE__BOOL = @HAVE__BOOL@
+HAVE__EXIT = @HAVE__EXIT@
+INCLUDE_NEXT = @INCLUDE_NEXT@
+INCLUDE_NEXT_AS_FIRST_DIRECTIVE = @INCLUDE_NEXT_AS_FIRST_DIRECTIVE@
+INSTALL = @INSTALL@
+INSTALL_DATA = @INSTALL_DATA@
+INSTALL_PROGRAM = @INSTALL_PROGRAM@
+INSTALL_SCRIPT = @INSTALL_SCRIPT@
+INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@
+INT32_MAX_LT_INTMAX_MAX = @INT32_MAX_LT_INTMAX_MAX@
+INT64_MAX_EQ_LONG_MAX = @INT64_MAX_EQ_LONG_MAX@
+INTLLIBS = @INTLLIBS@
+INTL_MACOSX_LIBS = @INTL_MACOSX_LIBS@
+LDFLAGS = @LDFLAGS@
+LIBGNU_LIBDEPS = @LIBGNU_LIBDEPS@
+LIBGNU_LTLIBDEPS = @LIBGNU_LTLIBDEPS@
+LIBICONV = @LIBICONV@
+LIBINTL = @LIBINTL@
+LIBOBJS = @LIBOBJS@
+LIBS = @LIBS@
+LIBUNISTRING_UNITYPES_H = @LIBUNISTRING_UNITYPES_H@
+LIBUNISTRING_UNIWIDTH_H = @LIBUNISTRING_UNIWIDTH_H@
+LIB_ACL = @LIB_ACL@
+LIB_CLOCK_GETTIME = @LIB_CLOCK_GETTIME@
+LIB_EACCESS = @LIB_EACCESS@
+LIB_HAS_ACL = @LIB_HAS_ACL@
+LIB_SELINUX = @LIB_SELINUX@
+LIB_SETSOCKOPT = @LIB_SETSOCKOPT@
+LOCALCHARSET_TESTS_ENVIRONMENT = @LOCALCHARSET_TESTS_ENVIRONMENT@
+LOCALE_FR = @LOCALE_FR@
+LOCALE_FR_UTF8 = @LOCALE_FR_UTF8@
+LOCALE_JA = @LOCALE_JA@
+LOCALE_ZH_CN = @LOCALE_ZH_CN@
+LTLIBICONV = @LTLIBICONV@
+LTLIBINTL = @LTLIBINTL@
+LTLIBOBJS = @LTLIBOBJS@
+MAKEINFO = @MAKEINFO@
+MKDIR_P = @MKDIR_P@
+MSGFMT = @MSGFMT@
+MSGFMT_015 = @MSGFMT_015@
+MSGMERGE = @MSGMERGE@
+NEXT_AS_FIRST_DIRECTIVE_DIRENT_H = @NEXT_AS_FIRST_DIRECTIVE_DIRENT_H@
+NEXT_AS_FIRST_DIRECTIVE_ERRNO_H = @NEXT_AS_FIRST_DIRECTIVE_ERRNO_H@
+NEXT_AS_FIRST_DIRECTIVE_FCNTL_H = @NEXT_AS_FIRST_DIRECTIVE_FCNTL_H@
+NEXT_AS_FIRST_DIRECTIVE_FLOAT_H = @NEXT_AS_FIRST_DIRECTIVE_FLOAT_H@
+NEXT_AS_FIRST_DIRECTIVE_GETOPT_H = @NEXT_AS_FIRST_DIRECTIVE_GETOPT_H@
+NEXT_AS_FIRST_DIRECTIVE_INTTYPES_H = @NEXT_AS_FIRST_DIRECTIVE_INTTYPES_H@
+NEXT_AS_FIRST_DIRECTIVE_LANGINFO_H = @NEXT_AS_FIRST_DIRECTIVE_LANGINFO_H@
+NEXT_AS_FIRST_DIRECTIVE_LOCALE_H = @NEXT_AS_FIRST_DIRECTIVE_LOCALE_H@
+NEXT_AS_FIRST_DIRECTIVE_SELINUX_SELINUX_H = @NEXT_AS_FIRST_DIRECTIVE_SELINUX_SELINUX_H@
+NEXT_AS_FIRST_DIRECTIVE_SIGNAL_H = @NEXT_AS_FIRST_DIRECTIVE_SIGNAL_H@
+NEXT_AS_FIRST_DIRECTIVE_STDARG_H = @NEXT_AS_FIRST_DIRECTIVE_STDARG_H@
+NEXT_AS_FIRST_DIRECTIVE_STDDEF_H = @NEXT_AS_FIRST_DIRECTIVE_STDDEF_H@
+NEXT_AS_FIRST_DIRECTIVE_STDINT_H = @NEXT_AS_FIRST_DIRECTIVE_STDINT_H@
+NEXT_AS_FIRST_DIRECTIVE_STDIO_H = @NEXT_AS_FIRST_DIRECTIVE_STDIO_H@
+NEXT_AS_FIRST_DIRECTIVE_STDLIB_H = @NEXT_AS_FIRST_DIRECTIVE_STDLIB_H@
+NEXT_AS_FIRST_DIRECTIVE_STRINGS_H = @NEXT_AS_FIRST_DIRECTIVE_STRINGS_H@
+NEXT_AS_FIRST_DIRECTIVE_STRING_H = @NEXT_AS_FIRST_DIRECTIVE_STRING_H@
+NEXT_AS_FIRST_DIRECTIVE_SYSEXITS_H = @NEXT_AS_FIRST_DIRECTIVE_SYSEXITS_H@
+NEXT_AS_FIRST_DIRECTIVE_SYS_STAT_H = @NEXT_AS_FIRST_DIRECTIVE_SYS_STAT_H@
+NEXT_AS_FIRST_DIRECTIVE_SYS_TIME_H = @NEXT_AS_FIRST_DIRECTIVE_SYS_TIME_H@
+NEXT_AS_FIRST_DIRECTIVE_SYS_TYPES_H = @NEXT_AS_FIRST_DIRECTIVE_SYS_TYPES_H@
+NEXT_AS_FIRST_DIRECTIVE_TIME_H = @NEXT_AS_FIRST_DIRECTIVE_TIME_H@
+NEXT_AS_FIRST_DIRECTIVE_UNISTD_H = @NEXT_AS_FIRST_DIRECTIVE_UNISTD_H@
+NEXT_AS_FIRST_DIRECTIVE_WCHAR_H = @NEXT_AS_FIRST_DIRECTIVE_WCHAR_H@
+NEXT_AS_FIRST_DIRECTIVE_WCTYPE_H = @NEXT_AS_FIRST_DIRECTIVE_WCTYPE_H@
+NEXT_DIRENT_H = @NEXT_DIRENT_H@
+NEXT_ERRNO_H = @NEXT_ERRNO_H@
+NEXT_FCNTL_H = @NEXT_FCNTL_H@
+NEXT_FLOAT_H = @NEXT_FLOAT_H@
+NEXT_GETOPT_H = @NEXT_GETOPT_H@
+NEXT_INTTYPES_H = @NEXT_INTTYPES_H@
+NEXT_LANGINFO_H = @NEXT_LANGINFO_H@
+NEXT_LOCALE_H = @NEXT_LOCALE_H@
+NEXT_SELINUX_SELINUX_H = @NEXT_SELINUX_SELINUX_H@
+NEXT_SIGNAL_H = @NEXT_SIGNAL_H@
+NEXT_STDARG_H = @NEXT_STDARG_H@
+NEXT_STDDEF_H = @NEXT_STDDEF_H@
+NEXT_STDINT_H = @NEXT_STDINT_H@
+NEXT_STDIO_H = @NEXT_STDIO_H@
+NEXT_STDLIB_H = @NEXT_STDLIB_H@
+NEXT_STRINGS_H = @NEXT_STRINGS_H@
+NEXT_STRING_H = @NEXT_STRING_H@
+NEXT_SYSEXITS_H = @NEXT_SYSEXITS_H@
+NEXT_SYS_STAT_H = @NEXT_SYS_STAT_H@
+NEXT_SYS_TIME_H = @NEXT_SYS_TIME_H@
+NEXT_SYS_TYPES_H = @NEXT_SYS_TYPES_H@
+NEXT_TIME_H = @NEXT_TIME_H@
+NEXT_UNISTD_H = @NEXT_UNISTD_H@
+NEXT_WCHAR_H = @NEXT_WCHAR_H@
+NEXT_WCTYPE_H = @NEXT_WCTYPE_H@
+OBJEXT = @OBJEXT@
+PACKAGE = @PACKAGE@
+PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@
+PACKAGE_NAME = @PACKAGE_NAME@
+PACKAGE_STRING = @PACKAGE_STRING@
+PACKAGE_TARNAME = @PACKAGE_TARNAME@
+PACKAGE_URL = @PACKAGE_URL@
+PACKAGE_VERSION = @PACKAGE_VERSION@
+PATH_SEPARATOR = @PATH_SEPARATOR@
+POSUB = @POSUB@
+PRAGMA_COLUMNS = @PRAGMA_COLUMNS@
+PRAGMA_SYSTEM_HEADER = @PRAGMA_SYSTEM_HEADER@
+PRIPTR_PREFIX = @PRIPTR_PREFIX@
+PRI_MACROS_BROKEN = @PRI_MACROS_BROKEN@
+PTHREAD_H_DEFINES_STRUCT_TIMESPEC = @PTHREAD_H_DEFINES_STRUCT_TIMESPEC@
+PTRDIFF_T_SUFFIX = @PTRDIFF_T_SUFFIX@
+PU_RMT_PROG = @PU_RMT_PROG@
+RANLIB = @RANLIB@
+REPLACE_BTOWC = @REPLACE_BTOWC@
+REPLACE_CALLOC = @REPLACE_CALLOC@
+REPLACE_CANONICALIZE_FILE_NAME = @REPLACE_CANONICALIZE_FILE_NAME@
+REPLACE_CHOWN = @REPLACE_CHOWN@
+REPLACE_CLOSE = @REPLACE_CLOSE@
+REPLACE_CLOSEDIR = @REPLACE_CLOSEDIR@
+REPLACE_DIRFD = @REPLACE_DIRFD@
+REPLACE_DPRINTF = @REPLACE_DPRINTF@
+REPLACE_DUP = @REPLACE_DUP@
+REPLACE_DUP2 = @REPLACE_DUP2@
+REPLACE_DUPLOCALE = @REPLACE_DUPLOCALE@
+REPLACE_FCHOWNAT = @REPLACE_FCHOWNAT@
+REPLACE_FCLOSE = @REPLACE_FCLOSE@
+REPLACE_FCNTL = @REPLACE_FCNTL@
+REPLACE_FDOPEN = @REPLACE_FDOPEN@
+REPLACE_FDOPENDIR = @REPLACE_FDOPENDIR@
+REPLACE_FFLUSH = @REPLACE_FFLUSH@
+REPLACE_FOPEN = @REPLACE_FOPEN@
+REPLACE_FPRINTF = @REPLACE_FPRINTF@
+REPLACE_FPURGE = @REPLACE_FPURGE@
+REPLACE_FREOPEN = @REPLACE_FREOPEN@
+REPLACE_FSEEK = @REPLACE_FSEEK@
+REPLACE_FSEEKO = @REPLACE_FSEEKO@
+REPLACE_FSTAT = @REPLACE_FSTAT@
+REPLACE_FSTATAT = @REPLACE_FSTATAT@
+REPLACE_FTELL = @REPLACE_FTELL@
+REPLACE_FTELLO = @REPLACE_FTELLO@
+REPLACE_FTRUNCATE = @REPLACE_FTRUNCATE@
+REPLACE_FUTIMENS = @REPLACE_FUTIMENS@
+REPLACE_GETCWD = @REPLACE_GETCWD@
+REPLACE_GETDELIM = @REPLACE_GETDELIM@
+REPLACE_GETDOMAINNAME = @REPLACE_GETDOMAINNAME@
+REPLACE_GETDTABLESIZE = @REPLACE_GETDTABLESIZE@
+REPLACE_GETGROUPS = @REPLACE_GETGROUPS@
+REPLACE_GETLINE = @REPLACE_GETLINE@
+REPLACE_GETLOGIN_R = @REPLACE_GETLOGIN_R@
+REPLACE_GETPAGESIZE = @REPLACE_GETPAGESIZE@
+REPLACE_GETTIMEOFDAY = @REPLACE_GETTIMEOFDAY@
+REPLACE_GMTIME = @REPLACE_GMTIME@
+REPLACE_ISATTY = @REPLACE_ISATTY@
+REPLACE_ISWBLANK = @REPLACE_ISWBLANK@
+REPLACE_ISWCNTRL = @REPLACE_ISWCNTRL@
+REPLACE_ITOLD = @REPLACE_ITOLD@
+REPLACE_LCHOWN = @REPLACE_LCHOWN@
+REPLACE_LINK = @REPLACE_LINK@
+REPLACE_LINKAT = @REPLACE_LINKAT@
+REPLACE_LOCALECONV = @REPLACE_LOCALECONV@
+REPLACE_LOCALTIME = @REPLACE_LOCALTIME@
+REPLACE_LOCALTIME_R = @REPLACE_LOCALTIME_R@
+REPLACE_LSEEK = @REPLACE_LSEEK@
+REPLACE_LSTAT = @REPLACE_LSTAT@
+REPLACE_MALLOC = @REPLACE_MALLOC@
+REPLACE_MBRLEN = @REPLACE_MBRLEN@
+REPLACE_MBRTOWC = @REPLACE_MBRTOWC@
+REPLACE_MBSINIT = @REPLACE_MBSINIT@
+REPLACE_MBSNRTOWCS = @REPLACE_MBSNRTOWCS@
+REPLACE_MBSRTOWCS = @REPLACE_MBSRTOWCS@
+REPLACE_MBSTATE_T = @REPLACE_MBSTATE_T@
+REPLACE_MBTOWC = @REPLACE_MBTOWC@
+REPLACE_MEMCHR = @REPLACE_MEMCHR@
+REPLACE_MEMMEM = @REPLACE_MEMMEM@
+REPLACE_MKDIR = @REPLACE_MKDIR@
+REPLACE_MKFIFO = @REPLACE_MKFIFO@
+REPLACE_MKNOD = @REPLACE_MKNOD@
+REPLACE_MKSTEMP = @REPLACE_MKSTEMP@
+REPLACE_MKTIME = @REPLACE_MKTIME@
+REPLACE_NANOSLEEP = @REPLACE_NANOSLEEP@
+REPLACE_NL_LANGINFO = @REPLACE_NL_LANGINFO@
+REPLACE_NULL = @REPLACE_NULL@
+REPLACE_OBSTACK_PRINTF = @REPLACE_OBSTACK_PRINTF@
+REPLACE_OPEN = @REPLACE_OPEN@
+REPLACE_OPENAT = @REPLACE_OPENAT@
+REPLACE_OPENDIR = @REPLACE_OPENDIR@
+REPLACE_PERROR = @REPLACE_PERROR@
+REPLACE_POPEN = @REPLACE_POPEN@
+REPLACE_PREAD = @REPLACE_PREAD@
+REPLACE_PRINTF = @REPLACE_PRINTF@
+REPLACE_PTHREAD_SIGMASK = @REPLACE_PTHREAD_SIGMASK@
+REPLACE_PTSNAME = @REPLACE_PTSNAME@
+REPLACE_PTSNAME_R = @REPLACE_PTSNAME_R@
+REPLACE_PUTENV = @REPLACE_PUTENV@
+REPLACE_PWRITE = @REPLACE_PWRITE@
+REPLACE_QSORT_R = @REPLACE_QSORT_R@
+REPLACE_RAISE = @REPLACE_RAISE@
+REPLACE_RANDOM_R = @REPLACE_RANDOM_R@
+REPLACE_READ = @REPLACE_READ@
+REPLACE_READLINK = @REPLACE_READLINK@
+REPLACE_READLINKAT = @REPLACE_READLINKAT@
+REPLACE_REALLOC = @REPLACE_REALLOC@
+REPLACE_REALPATH = @REPLACE_REALPATH@
+REPLACE_REMOVE = @REPLACE_REMOVE@
+REPLACE_RENAME = @REPLACE_RENAME@
+REPLACE_RENAMEAT = @REPLACE_RENAMEAT@
+REPLACE_RMDIR = @REPLACE_RMDIR@
+REPLACE_SETENV = @REPLACE_SETENV@
+REPLACE_SETLOCALE = @REPLACE_SETLOCALE@
+REPLACE_SLEEP = @REPLACE_SLEEP@
+REPLACE_SNPRINTF = @REPLACE_SNPRINTF@
+REPLACE_SPRINTF = @REPLACE_SPRINTF@
+REPLACE_STAT = @REPLACE_STAT@
+REPLACE_STDIO_READ_FUNCS = @REPLACE_STDIO_READ_FUNCS@
+REPLACE_STDIO_WRITE_FUNCS = @REPLACE_STDIO_WRITE_FUNCS@
+REPLACE_STPNCPY = @REPLACE_STPNCPY@
+REPLACE_STRCASESTR = @REPLACE_STRCASESTR@
+REPLACE_STRCHRNUL = @REPLACE_STRCHRNUL@
+REPLACE_STRDUP = @REPLACE_STRDUP@
+REPLACE_STRERROR = @REPLACE_STRERROR@
+REPLACE_STRERROR_R = @REPLACE_STRERROR_R@
+REPLACE_STRNCAT = @REPLACE_STRNCAT@
+REPLACE_STRNDUP = @REPLACE_STRNDUP@
+REPLACE_STRNLEN = @REPLACE_STRNLEN@
+REPLACE_STRSIGNAL = @REPLACE_STRSIGNAL@
+REPLACE_STRSTR = @REPLACE_STRSTR@
+REPLACE_STRTOD = @REPLACE_STRTOD@
+REPLACE_STRTOIMAX = @REPLACE_STRTOIMAX@
+REPLACE_STRTOK_R = @REPLACE_STRTOK_R@
+REPLACE_STRTOUMAX = @REPLACE_STRTOUMAX@
+REPLACE_STRUCT_LCONV = @REPLACE_STRUCT_LCONV@
+REPLACE_STRUCT_TIMEVAL = @REPLACE_STRUCT_TIMEVAL@
+REPLACE_SYMLINK = @REPLACE_SYMLINK@
+REPLACE_SYMLINKAT = @REPLACE_SYMLINKAT@
+REPLACE_TIMEGM = @REPLACE_TIMEGM@
+REPLACE_TMPFILE = @REPLACE_TMPFILE@
+REPLACE_TOWLOWER = @REPLACE_TOWLOWER@
+REPLACE_TTYNAME_R = @REPLACE_TTYNAME_R@
+REPLACE_UNLINK = @REPLACE_UNLINK@
+REPLACE_UNLINKAT = @REPLACE_UNLINKAT@
+REPLACE_UNSETENV = @REPLACE_UNSETENV@
+REPLACE_USLEEP = @REPLACE_USLEEP@
+REPLACE_UTIMENSAT = @REPLACE_UTIMENSAT@
+REPLACE_VASPRINTF = @REPLACE_VASPRINTF@
+REPLACE_VDPRINTF = @REPLACE_VDPRINTF@
+REPLACE_VFPRINTF = @REPLACE_VFPRINTF@
+REPLACE_VPRINTF = @REPLACE_VPRINTF@
+REPLACE_VSNPRINTF = @REPLACE_VSNPRINTF@
+REPLACE_VSPRINTF = @REPLACE_VSPRINTF@
+REPLACE_WCRTOMB = @REPLACE_WCRTOMB@
+REPLACE_WCSNRTOMBS = @REPLACE_WCSNRTOMBS@
+REPLACE_WCSRTOMBS = @REPLACE_WCSRTOMBS@
+REPLACE_WCSWIDTH = @REPLACE_WCSWIDTH@
+REPLACE_WCTOB = @REPLACE_WCTOB@
+REPLACE_WCTOMB = @REPLACE_WCTOMB@
+REPLACE_WCWIDTH = @REPLACE_WCWIDTH@
+REPLACE_WRITE = @REPLACE_WRITE@
+RSH = @RSH@
+SED = @SED@
+SELINUX_CONTEXT_H = @SELINUX_CONTEXT_H@
+SET_MAKE = @SET_MAKE@
+SHELL = @SHELL@
+SIG_ATOMIC_T_SUFFIX = @SIG_ATOMIC_T_SUFFIX@
+SIZE_T_SUFFIX = @SIZE_T_SUFFIX@
+STDALIGN_H = @STDALIGN_H@
+STDARG_H = @STDARG_H@
+STDBOOL_H = @STDBOOL_H@
+STDDEF_H = @STDDEF_H@
+STDINT_H = @STDINT_H@
+STRIP = @STRIP@
+SYSEXITS_H = @SYSEXITS_H@
+SYS_TIME_H_DEFINES_STRUCT_TIMESPEC = @SYS_TIME_H_DEFINES_STRUCT_TIMESPEC@
+TIME_H_DEFINES_STRUCT_TIMESPEC = @TIME_H_DEFINES_STRUCT_TIMESPEC@
+UINT32_MAX_LT_UINTMAX_MAX = @UINT32_MAX_LT_UINTMAX_MAX@
+UINT64_MAX_EQ_ULONG_MAX = @UINT64_MAX_EQ_ULONG_MAX@
+UNDEFINE_STRTOK_R = @UNDEFINE_STRTOK_R@
+UNISTD_H_DEFINES_STRUCT_TIMESPEC = @UNISTD_H_DEFINES_STRUCT_TIMESPEC@
+UNISTD_H_HAVE_WINSOCK2_H = @UNISTD_H_HAVE_WINSOCK2_H@
+UNISTD_H_HAVE_WINSOCK2_H_AND_USE_SOCKETS = @UNISTD_H_HAVE_WINSOCK2_H_AND_USE_SOCKETS@
+USE_ACL = @USE_ACL@
+USE_NLS = @USE_NLS@
+VERSION = @VERSION@
+WARN_CFLAGS = @WARN_CFLAGS@
+WCHAR_T_SUFFIX = @WCHAR_T_SUFFIX@
+WERROR_CFLAGS = @WERROR_CFLAGS@
+WINDOWS_64_BIT_OFF_T = @WINDOWS_64_BIT_OFF_T@
+WINDOWS_64_BIT_ST_SIZE = @WINDOWS_64_BIT_ST_SIZE@
+WINT_T_SUFFIX = @WINT_T_SUFFIX@
+XGETTEXT = @XGETTEXT@
+XGETTEXT_015 = @XGETTEXT_015@
+XGETTEXT_EXTRA_OPTIONS = @XGETTEXT_EXTRA_OPTIONS@
+YACC = @YACC@
+YFLAGS = @YFLAGS@
+abs_builddir = @abs_builddir@
+abs_srcdir = @abs_srcdir@
+abs_top_builddir = @abs_top_builddir@
+abs_top_srcdir = @abs_top_srcdir@
+ac_ct_AR = @ac_ct_AR@
+ac_ct_CC = @ac_ct_CC@
+am__include = @am__include@
+am__leading_dot = @am__leading_dot@
+am__quote = @am__quote@
+am__tar = @am__tar@
+am__untar = @am__untar@
+bindir = @bindir@
+build = @build@
+build_alias = @build_alias@
+build_cpu = @build_cpu@
+build_os = @build_os@
+build_vendor = @build_vendor@
+builddir = @builddir@
+datadir = @datadir@
+datarootdir = @datarootdir@
+docdir = @docdir@
+dvidir = @dvidir@
+exec_prefix = @exec_prefix@
+gl_LIBOBJS = @gl_LIBOBJS@
+gl_LTLIBOBJS = @gl_LTLIBOBJS@
+gltests_LIBOBJS = @gltests_LIBOBJS@
+gltests_LTLIBOBJS = @gltests_LTLIBOBJS@
+gltests_WITNESS = @gltests_WITNESS@
+host = @host@
+host_alias = @host_alias@
+host_cpu = @host_cpu@
+host_os = @host_os@
+host_vendor = @host_vendor@
+htmldir = @htmldir@
+includedir = @includedir@
+infodir = @infodir@
+install_sh = @install_sh@
+libdir = @libdir@
+libexecdir = @libexecdir@
+lispdir = @lispdir@
+localedir = @localedir@
+localstatedir = @localstatedir@
+mandir = @mandir@
+mkdir_p = @mkdir_p@
+oldincludedir = @oldincludedir@
+pdfdir = @pdfdir@
+prefix = @prefix@
+program_transform_name = @program_transform_name@
+psdir = @psdir@
+runstatedir = @runstatedir@
+sbindir = @sbindir@
+sharedstatedir = @sharedstatedir@
+srcdir = @srcdir@
+sysconfdir = @sysconfdir@
+target_alias = @target_alias@
+top_build_prefix = @top_build_prefix@
+top_builddir = @top_builddir@
+top_srcdir = @top_srcdir@
+info_TEXINFOS = tar.texi
+tar_TEXINFOS = \
+ dumpdir.texi\
+ tar-snapshot-edit.texi\
+ fdl.texi\
+ freemanuals.texi\
+ genfile.texi\
+ header.texi\
+ intern.texi\
+ parse-datetime.texi\
+ rendition.texi\
+ snapshot.texi\
+ sparse.texi\
+ value.texi
+
+dist_man_MANS = tar.1 $(RMT_8)
+@PU_RMT_COND_TRUE@RMT_8 = rmt.8
+EXTRA_DIST = gendocs_template mastermenu.el texify.sed untabify.el rmt.8
+
+# The rendering level is anyone of PUBLISH, DISTRIB or PROOF.
+# Just call 'make RENDITION=PROOF [target]' if you want PROOF rendition.
+RENDITION = DISTRIB
+MAKEINFOFLAGS = -D$(RENDITION)
+GENDOCS = gendocs.sh
+TEXI2DVI = texi2dvi -t '@set $(RENDITION)' -E
+all: all-am
+
+.SUFFIXES:
+.SUFFIXES: .dvi .html .info .pdf .ps .texi
+$(srcdir)/Makefile.in: $(srcdir)/Makefile.am $(am__configure_deps)
+ @for dep in $?; do \
+ case '$(am__configure_deps)' in \
+ *$$dep*) \
+ ( cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh ) \
+ && { if test -f $@; then exit 0; else break; fi; }; \
+ exit 1;; \
+ esac; \
+ done; \
+ echo ' cd $(top_srcdir) && $(AUTOMAKE) --gnits doc/Makefile'; \
+ $(am__cd) $(top_srcdir) && \
+ $(AUTOMAKE) --gnits doc/Makefile
+.PRECIOUS: Makefile
+Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status
+ @case '$?' in \
+ *config.status*) \
+ cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \
+ *) \
+ echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \
+ cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \
+ esac;
+
+$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES)
+ cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
+
+$(top_srcdir)/configure: $(am__configure_deps)
+ cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
+$(ACLOCAL_M4): $(am__aclocal_m4_deps)
+ cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
+$(am__aclocal_m4_deps):
+
+.texi.info:
+ $(AM_V_MAKEINFO)restore=: && backupdir="$(am__leading_dot)am$$$$" && \
+ am__cwd=`pwd` && $(am__cd) $(srcdir) && \
+ rm -rf $$backupdir && mkdir $$backupdir && \
+ if ($(MAKEINFO) --version) >/dev/null 2>&1; then \
+ for f in $@ $@-[0-9] $@-[0-9][0-9] $(@:.info=).i[0-9] $(@:.info=).i[0-9][0-9]; do \
+ if test -f $$f; then mv $$f $$backupdir; restore=mv; else :; fi; \
+ done; \
+ else :; fi && \
+ cd "$$am__cwd"; \
+ if $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \
+ -o $@ $<; \
+ then \
+ rc=0; \
+ $(am__cd) $(srcdir); \
+ else \
+ rc=$$?; \
+ $(am__cd) $(srcdir) && \
+ $$restore $$backupdir/* `echo "./$@" | sed 's|[^/]*$$||'`; \
+ fi; \
+ rm -rf $$backupdir; exit $$rc
+
+.texi.dvi:
+ $(AM_V_TEXI2DVI)TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \
+ MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \
+ $(TEXI2DVI) $(AM_V_texinfo) --build-dir=$(@:.dvi=.t2d) -o $@ $(AM_V_texidevnull) \
+ $<
+
+.texi.pdf:
+ $(AM_V_TEXI2PDF)TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \
+ MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \
+ $(TEXI2PDF) $(AM_V_texinfo) --build-dir=$(@:.pdf=.t2p) -o $@ $(AM_V_texidevnull) \
+ $<
+
+.texi.html:
+ $(AM_V_MAKEINFO)rm -rf $(@:.html=.htp)
+ $(AM_V_at)if $(MAKEINFOHTML) $(AM_MAKEINFOHTMLFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \
+ -o $(@:.html=.htp) $<; \
+ then \
+ rm -rf $@ && mv $(@:.html=.htp) $@; \
+ else \
+ rm -rf $(@:.html=.htp); exit 1; \
+ fi
+$(srcdir)/tar.info: tar.texi $(srcdir)/version.texi $(tar_TEXINFOS)
+tar.dvi: tar.texi $(srcdir)/version.texi $(tar_TEXINFOS)
+tar.pdf: tar.texi $(srcdir)/version.texi $(tar_TEXINFOS)
+tar.html: tar.texi $(srcdir)/version.texi $(tar_TEXINFOS)
+$(srcdir)/version.texi: $(srcdir)/stamp-vti
+$(srcdir)/stamp-vti: tar.texi $(top_srcdir)/configure
+ @(dir=.; test -f ./tar.texi || dir=$(srcdir); \
+ set `$(SHELL) $(top_srcdir)/build-aux/mdate-sh $$dir/tar.texi`; \
+ echo "@set UPDATED $$1 $$2 $$3"; \
+ echo "@set UPDATED-MONTH $$2 $$3"; \
+ echo "@set EDITION $(VERSION)"; \
+ echo "@set VERSION $(VERSION)") > vti.tmp
+ @cmp -s vti.tmp $(srcdir)/version.texi \
+ || (echo "Updating $(srcdir)/version.texi"; \
+ cp vti.tmp $(srcdir)/version.texi)
+ -@rm -f vti.tmp
+ @cp $(srcdir)/version.texi $@
+
+mostlyclean-vti:
+ -rm -f vti.tmp
+
+maintainer-clean-vti:
+ -rm -f $(srcdir)/stamp-vti $(srcdir)/version.texi
+.dvi.ps:
+ $(AM_V_DVIPS)TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \
+ $(DVIPS) $(AM_V_texinfo) -o $@ $<
+
+uninstall-dvi-am:
+ @$(NORMAL_UNINSTALL)
+ @list='$(DVIS)'; test -n "$(dvidir)" || list=; \
+ for p in $$list; do \
+ $(am__strip_dir) \
+ echo " rm -f '$(DESTDIR)$(dvidir)/$$f'"; \
+ rm -f "$(DESTDIR)$(dvidir)/$$f"; \
+ done
+
+uninstall-html-am:
+ @$(NORMAL_UNINSTALL)
+ @list='$(HTMLS)'; test -n "$(htmldir)" || list=; \
+ for p in $$list; do \
+ $(am__strip_dir) \
+ echo " rm -rf '$(DESTDIR)$(htmldir)/$$f'"; \
+ rm -rf "$(DESTDIR)$(htmldir)/$$f"; \
+ done
+
+uninstall-info-am:
+ @$(PRE_UNINSTALL)
+ @if test -d '$(DESTDIR)$(infodir)' && $(am__can_run_installinfo); then \
+ list='$(INFO_DEPS)'; \
+ for file in $$list; do \
+ relfile=`echo "$$file" | sed 's|^.*/||'`; \
+ echo " install-info --info-dir='$(DESTDIR)$(infodir)' --remove '$(DESTDIR)$(infodir)/$$relfile'"; \
+ if install-info --info-dir="$(DESTDIR)$(infodir)" --remove "$(DESTDIR)$(infodir)/$$relfile"; \
+ then :; else test ! -f "$(DESTDIR)$(infodir)/$$relfile" || exit 1; fi; \
+ done; \
+ else :; fi
+ @$(NORMAL_UNINSTALL)
+ @list='$(INFO_DEPS)'; \
+ for file in $$list; do \
+ relfile=`echo "$$file" | sed 's|^.*/||'`; \
+ relfile_i=`echo "$$relfile" | sed 's|\.info$$||;s|$$|.i|'`; \
+ (if test -d "$(DESTDIR)$(infodir)" && cd "$(DESTDIR)$(infodir)"; then \
+ echo " cd '$(DESTDIR)$(infodir)' && rm -f $$relfile $$relfile-[0-9] $$relfile-[0-9][0-9] $$relfile_i[0-9] $$relfile_i[0-9][0-9]"; \
+ rm -f $$relfile $$relfile-[0-9] $$relfile-[0-9][0-9] $$relfile_i[0-9] $$relfile_i[0-9][0-9]; \
+ else :; fi); \
+ done
+
+uninstall-pdf-am:
+ @$(NORMAL_UNINSTALL)
+ @list='$(PDFS)'; test -n "$(pdfdir)" || list=; \
+ for p in $$list; do \
+ $(am__strip_dir) \
+ echo " rm -f '$(DESTDIR)$(pdfdir)/$$f'"; \
+ rm -f "$(DESTDIR)$(pdfdir)/$$f"; \
+ done
+
+uninstall-ps-am:
+ @$(NORMAL_UNINSTALL)
+ @list='$(PSS)'; test -n "$(psdir)" || list=; \
+ for p in $$list; do \
+ $(am__strip_dir) \
+ echo " rm -f '$(DESTDIR)$(psdir)/$$f'"; \
+ rm -f "$(DESTDIR)$(psdir)/$$f"; \
+ done
+
+dist-info: $(INFO_DEPS)
+ @srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \
+ list='$(INFO_DEPS)'; \
+ for base in $$list; do \
+ case $$base in \
+ $(srcdir)/*) base=`echo "$$base" | sed "s|^$$srcdirstrip/||"`;; \
+ esac; \
+ if test -f $$base; then d=.; else d=$(srcdir); fi; \
+ base_i=`echo "$$base" | sed 's|\.info$$||;s|$$|.i|'`; \
+ for file in $$d/$$base $$d/$$base-[0-9] $$d/$$base-[0-9][0-9] $$d/$$base_i[0-9] $$d/$$base_i[0-9][0-9]; do \
+ if test -f $$file; then \
+ relfile=`expr "$$file" : "$$d/\(.*\)"`; \
+ test -f "$(distdir)/$$relfile" || \
+ cp -p $$file "$(distdir)/$$relfile"; \
+ else :; fi; \
+ done; \
+ done
+
+mostlyclean-aminfo:
+ -rm -rf tar.t2d tar.t2p
+
+clean-aminfo:
+ -test -z "tar.dvi tar.pdf tar.ps tar.html" \
+ || rm -rf tar.dvi tar.pdf tar.ps tar.html
+
+maintainer-clean-aminfo:
+ @list='$(INFO_DEPS)'; for i in $$list; do \
+ i_i=`echo "$$i" | sed 's|\.info$$||;s|$$|.i|'`; \
+ echo " rm -f $$i $$i-[0-9] $$i-[0-9][0-9] $$i_i[0-9] $$i_i[0-9][0-9]"; \
+ rm -f $$i $$i-[0-9] $$i-[0-9][0-9] $$i_i[0-9] $$i_i[0-9][0-9]; \
+ done
+install-man1: $(dist_man_MANS)
+ @$(NORMAL_INSTALL)
+ @list1=''; \
+ list2='$(dist_man_MANS)'; \
+ test -n "$(man1dir)" \
+ && test -n "`echo $$list1$$list2`" \
+ || exit 0; \
+ echo " $(MKDIR_P) '$(DESTDIR)$(man1dir)'"; \
+ $(MKDIR_P) "$(DESTDIR)$(man1dir)" || exit 1; \
+ { for i in $$list1; do echo "$$i"; done; \
+ if test -n "$$list2"; then \
+ for i in $$list2; do echo "$$i"; done \
+ | sed -n '/\.1[a-z]*$$/p'; \
+ fi; \
+ } | while read p; do \
+ if test -f $$p; then d=; else d="$(srcdir)/"; fi; \
+ echo "$$d$$p"; echo "$$p"; \
+ done | \
+ sed -e 'n;s,.*/,,;p;h;s,.*\.,,;s,^[^1][0-9a-z]*$$,1,;x' \
+ -e 's,\.[0-9a-z]*$$,,;$(transform);G;s,\n,.,' | \
+ sed 'N;N;s,\n, ,g' | { \
+ list=; while read file base inst; do \
+ if test "$$base" = "$$inst"; then list="$$list $$file"; else \
+ echo " $(INSTALL_DATA) '$$file' '$(DESTDIR)$(man1dir)/$$inst'"; \
+ $(INSTALL_DATA) "$$file" "$(DESTDIR)$(man1dir)/$$inst" || exit $$?; \
+ fi; \
+ done; \
+ for i in $$list; do echo "$$i"; done | $(am__base_list) | \
+ while read files; do \
+ test -z "$$files" || { \
+ echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(man1dir)'"; \
+ $(INSTALL_DATA) $$files "$(DESTDIR)$(man1dir)" || exit $$?; }; \
+ done; }
+
+uninstall-man1:
+ @$(NORMAL_UNINSTALL)
+ @list=''; test -n "$(man1dir)" || exit 0; \
+ files=`{ for i in $$list; do echo "$$i"; done; \
+ l2='$(dist_man_MANS)'; for i in $$l2; do echo "$$i"; done | \
+ sed -n '/\.1[a-z]*$$/p'; \
+ } | sed -e 's,.*/,,;h;s,.*\.,,;s,^[^1][0-9a-z]*$$,1,;x' \
+ -e 's,\.[0-9a-z]*$$,,;$(transform);G;s,\n,.,'`; \
+ dir='$(DESTDIR)$(man1dir)'; $(am__uninstall_files_from_dir)
+install-man8: $(dist_man_MANS)
+ @$(NORMAL_INSTALL)
+ @list1=''; \
+ list2='$(dist_man_MANS)'; \
+ test -n "$(man8dir)" \
+ && test -n "`echo $$list1$$list2`" \
+ || exit 0; \
+ echo " $(MKDIR_P) '$(DESTDIR)$(man8dir)'"; \
+ $(MKDIR_P) "$(DESTDIR)$(man8dir)" || exit 1; \
+ { for i in $$list1; do echo "$$i"; done; \
+ if test -n "$$list2"; then \
+ for i in $$list2; do echo "$$i"; done \
+ | sed -n '/\.8[a-z]*$$/p'; \
+ fi; \
+ } | while read p; do \
+ if test -f $$p; then d=; else d="$(srcdir)/"; fi; \
+ echo "$$d$$p"; echo "$$p"; \
+ done | \
+ sed -e 'n;s,.*/,,;p;h;s,.*\.,,;s,^[^8][0-9a-z]*$$,8,;x' \
+ -e 's,\.[0-9a-z]*$$,,;$(transform);G;s,\n,.,' | \
+ sed 'N;N;s,\n, ,g' | { \
+ list=; while read file base inst; do \
+ if test "$$base" = "$$inst"; then list="$$list $$file"; else \
+ echo " $(INSTALL_DATA) '$$file' '$(DESTDIR)$(man8dir)/$$inst'"; \
+ $(INSTALL_DATA) "$$file" "$(DESTDIR)$(man8dir)/$$inst" || exit $$?; \
+ fi; \
+ done; \
+ for i in $$list; do echo "$$i"; done | $(am__base_list) | \
+ while read files; do \
+ test -z "$$files" || { \
+ echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(man8dir)'"; \
+ $(INSTALL_DATA) $$files "$(DESTDIR)$(man8dir)" || exit $$?; }; \
+ done; }
+
+uninstall-man8:
+ @$(NORMAL_UNINSTALL)
+ @list=''; test -n "$(man8dir)" || exit 0; \
+ files=`{ for i in $$list; do echo "$$i"; done; \
+ l2='$(dist_man_MANS)'; for i in $$l2; do echo "$$i"; done | \
+ sed -n '/\.8[a-z]*$$/p'; \
+ } | sed -e 's,.*/,,;h;s,.*\.,,;s,^[^8][0-9a-z]*$$,8,;x' \
+ -e 's,\.[0-9a-z]*$$,,;$(transform);G;s,\n,.,'`; \
+ dir='$(DESTDIR)$(man8dir)'; $(am__uninstall_files_from_dir)
+tags TAGS:
+
+ctags CTAGS:
+
+cscope cscopelist:
+
+
+distdir: $(DISTFILES)
+ @srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \
+ topsrcdirstrip=`echo "$(top_srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \
+ list='$(DISTFILES)'; \
+ dist_files=`for file in $$list; do echo $$file; done | \
+ sed -e "s|^$$srcdirstrip/||;t" \
+ -e "s|^$$topsrcdirstrip/|$(top_builddir)/|;t"`; \
+ case $$dist_files in \
+ */*) $(MKDIR_P) `echo "$$dist_files" | \
+ sed '/\//!d;s|^|$(distdir)/|;s,/[^/]*$$,,' | \
+ sort -u` ;; \
+ esac; \
+ for file in $$dist_files; do \
+ if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \
+ if test -d $$d/$$file; then \
+ dir=`echo "/$$file" | sed -e 's,/[^/]*$$,,'`; \
+ if test -d "$(distdir)/$$file"; then \
+ find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \
+ fi; \
+ if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \
+ cp -fpR $(srcdir)/$$file "$(distdir)$$dir" || exit 1; \
+ find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \
+ fi; \
+ cp -fpR $$d/$$file "$(distdir)$$dir" || exit 1; \
+ else \
+ test -f "$(distdir)/$$file" \
+ || cp -p $$d/$$file "$(distdir)/$$file" \
+ || exit 1; \
+ fi; \
+ done
+ $(MAKE) $(AM_MAKEFLAGS) \
+ top_distdir="$(top_distdir)" distdir="$(distdir)" \
+ dist-info
+check-am: all-am
+check: check-am
+all-am: Makefile $(INFO_DEPS) $(MANS)
+installdirs:
+ for dir in "$(DESTDIR)$(infodir)" "$(DESTDIR)$(man1dir)" "$(DESTDIR)$(man8dir)"; do \
+ test -z "$$dir" || $(MKDIR_P) "$$dir"; \
+ done
+install: install-am
+install-exec: install-exec-am
+install-data: install-data-am
+uninstall: uninstall-am
+
+install-am: all-am
+ @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am
+
+installcheck: installcheck-am
+install-strip:
+ if test -z '$(STRIP)'; then \
+ $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \
+ install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \
+ install; \
+ else \
+ $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \
+ install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \
+ "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'" install; \
+ fi
+mostlyclean-generic:
+
+clean-generic:
+
+distclean-generic:
+ -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES)
+ -test . = "$(srcdir)" || test -z "$(CONFIG_CLEAN_VPATH_FILES)" || rm -f $(CONFIG_CLEAN_VPATH_FILES)
+
+maintainer-clean-generic:
+ @echo "This command is intended for maintainers to use"
+ @echo "it deletes files that may require special tools to rebuild."
+clean: clean-am
+
+clean-am: clean-aminfo clean-generic clean-local mostlyclean-am
+
+distclean: distclean-am
+ -rm -f Makefile
+distclean-am: clean-am distclean-generic
+
+dvi: dvi-am
+
+dvi-am: $(DVIS)
+
+html: html-am
+
+html-am: $(HTMLS)
+
+info: info-am
+
+info-am: $(INFO_DEPS)
+
+install-data-am: install-info-am install-man
+
+install-dvi: install-dvi-am
+
+install-dvi-am: $(DVIS)
+ @$(NORMAL_INSTALL)
+ @list='$(DVIS)'; test -n "$(dvidir)" || list=; \
+ if test -n "$$list"; then \
+ echo " $(MKDIR_P) '$(DESTDIR)$(dvidir)'"; \
+ $(MKDIR_P) "$(DESTDIR)$(dvidir)" || exit 1; \
+ fi; \
+ for p in $$list; do \
+ if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \
+ echo "$$d$$p"; \
+ done | $(am__base_list) | \
+ while read files; do \
+ echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(dvidir)'"; \
+ $(INSTALL_DATA) $$files "$(DESTDIR)$(dvidir)" || exit $$?; \
+ done
+install-exec-am:
+
+install-html: install-html-am
+
+install-html-am: $(HTMLS)
+ @$(NORMAL_INSTALL)
+ @list='$(HTMLS)'; list2=; test -n "$(htmldir)" || list=; \
+ if test -n "$$list"; then \
+ echo " $(MKDIR_P) '$(DESTDIR)$(htmldir)'"; \
+ $(MKDIR_P) "$(DESTDIR)$(htmldir)" || exit 1; \
+ fi; \
+ for p in $$list; do \
+ if test -f "$$p" || test -d "$$p"; then d=; else d="$(srcdir)/"; fi; \
+ $(am__strip_dir) \
+ d2=$$d$$p; \
+ if test -d "$$d2"; then \
+ echo " $(MKDIR_P) '$(DESTDIR)$(htmldir)/$$f'"; \
+ $(MKDIR_P) "$(DESTDIR)$(htmldir)/$$f" || exit 1; \
+ echo " $(INSTALL_DATA) '$$d2'/* '$(DESTDIR)$(htmldir)/$$f'"; \
+ $(INSTALL_DATA) "$$d2"/* "$(DESTDIR)$(htmldir)/$$f" || exit $$?; \
+ else \
+ list2="$$list2 $$d2"; \
+ fi; \
+ done; \
+ test -z "$$list2" || { echo "$$list2" | $(am__base_list) | \
+ while read files; do \
+ echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(htmldir)'"; \
+ $(INSTALL_DATA) $$files "$(DESTDIR)$(htmldir)" || exit $$?; \
+ done; }
+install-info: install-info-am
+
+install-info-am: $(INFO_DEPS)
+ @$(NORMAL_INSTALL)
+ @srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \
+ list='$(INFO_DEPS)'; test -n "$(infodir)" || list=; \
+ if test -n "$$list"; then \
+ echo " $(MKDIR_P) '$(DESTDIR)$(infodir)'"; \
+ $(MKDIR_P) "$(DESTDIR)$(infodir)" || exit 1; \
+ fi; \
+ for file in $$list; do \
+ case $$file in \
+ $(srcdir)/*) file=`echo "$$file" | sed "s|^$$srcdirstrip/||"`;; \
+ esac; \
+ if test -f $$file; then d=.; else d=$(srcdir); fi; \
+ file_i=`echo "$$file" | sed 's|\.info$$||;s|$$|.i|'`; \
+ for ifile in $$d/$$file $$d/$$file-[0-9] $$d/$$file-[0-9][0-9] \
+ $$d/$$file_i[0-9] $$d/$$file_i[0-9][0-9] ; do \
+ if test -f $$ifile; then \
+ echo "$$ifile"; \
+ else : ; fi; \
+ done; \
+ done | $(am__base_list) | \
+ while read files; do \
+ echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(infodir)'"; \
+ $(INSTALL_DATA) $$files "$(DESTDIR)$(infodir)" || exit $$?; done
+ @$(POST_INSTALL)
+ @if $(am__can_run_installinfo); then \
+ list='$(INFO_DEPS)'; test -n "$(infodir)" || list=; \
+ for file in $$list; do \
+ relfile=`echo "$$file" | sed 's|^.*/||'`; \
+ echo " install-info --info-dir='$(DESTDIR)$(infodir)' '$(DESTDIR)$(infodir)/$$relfile'";\
+ install-info --info-dir="$(DESTDIR)$(infodir)" "$(DESTDIR)$(infodir)/$$relfile" || :;\
+ done; \
+ else : ; fi
+install-man: install-man1 install-man8
+
+install-pdf: install-pdf-am
+
+install-pdf-am: $(PDFS)
+ @$(NORMAL_INSTALL)
+ @list='$(PDFS)'; test -n "$(pdfdir)" || list=; \
+ if test -n "$$list"; then \
+ echo " $(MKDIR_P) '$(DESTDIR)$(pdfdir)'"; \
+ $(MKDIR_P) "$(DESTDIR)$(pdfdir)" || exit 1; \
+ fi; \
+ for p in $$list; do \
+ if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \
+ echo "$$d$$p"; \
+ done | $(am__base_list) | \
+ while read files; do \
+ echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(pdfdir)'"; \
+ $(INSTALL_DATA) $$files "$(DESTDIR)$(pdfdir)" || exit $$?; done
+install-ps: install-ps-am
+
+install-ps-am: $(PSS)
+ @$(NORMAL_INSTALL)
+ @list='$(PSS)'; test -n "$(psdir)" || list=; \
+ if test -n "$$list"; then \
+ echo " $(MKDIR_P) '$(DESTDIR)$(psdir)'"; \
+ $(MKDIR_P) "$(DESTDIR)$(psdir)" || exit 1; \
+ fi; \
+ for p in $$list; do \
+ if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \
+ echo "$$d$$p"; \
+ done | $(am__base_list) | \
+ while read files; do \
+ echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(psdir)'"; \
+ $(INSTALL_DATA) $$files "$(DESTDIR)$(psdir)" || exit $$?; done
+installcheck-am:
+
+maintainer-clean: maintainer-clean-am
+ -rm -f Makefile
+maintainer-clean-am: distclean-am maintainer-clean-aminfo \
+ maintainer-clean-generic maintainer-clean-vti
+
+mostlyclean: mostlyclean-am
+
+mostlyclean-am: mostlyclean-aminfo mostlyclean-generic mostlyclean-vti
+
+pdf: pdf-am
+
+pdf-am: $(PDFS)
+
+ps: ps-am
+
+ps-am: $(PSS)
+
+uninstall-am: uninstall-dvi-am uninstall-html-am uninstall-info-am \
+ uninstall-man uninstall-pdf-am uninstall-ps-am
+
+uninstall-man: uninstall-man1 uninstall-man8
+
+.MAKE: install-am install-strip
+
+.PHONY: all all-am check check-am clean clean-aminfo clean-generic \
+ clean-local cscopelist-am ctags-am dist-info distclean \
+ distclean-generic distdir dvi dvi-am html html-am info info-am \
+ install install-am install-data install-data-am install-dvi \
+ install-dvi-am install-exec install-exec-am install-html \
+ install-html-am install-info install-info-am install-man \
+ install-man1 install-man8 install-pdf install-pdf-am \
+ install-ps install-ps-am install-strip installcheck \
+ installcheck-am installdirs maintainer-clean \
+ maintainer-clean-aminfo maintainer-clean-generic \
+ maintainer-clean-vti mostlyclean mostlyclean-aminfo \
+ mostlyclean-generic mostlyclean-vti pdf pdf-am ps ps-am \
+ tags-am uninstall uninstall-am uninstall-dvi-am \
+ uninstall-html-am uninstall-info-am uninstall-man \
+ uninstall-man1 uninstall-man8 uninstall-pdf-am uninstall-ps-am
+
+
+header.texi: $(top_srcdir)/src/tar.h
+ sed -f $(srcdir)/texify.sed $(top_srcdir)/src/tar.h \
+ | expand >$@
+
+master-menu: $(tar_TEXINFOS)
+ emacs -batch -l mastermenu.el -f make-master-menu $(info_TEXINFOS)
+
+untabify:
+ emacs -batch -l untabify.el $(info_TEXINFOS) $(tar_TEXINFOS)
+
+final: untabify master-menu
+
+# Checking
+check-format:
+ @if test -n "`cat $(info_TEXINFOS) $(tar_TEXINFOS) | tr -d -c '\t'`"; then \
+ echo "Sources contain tabs; run make untabify"; \
+ false; \
+ fi
+
+check-options:
+ @ARGP_HELP_FMT='usage-indent=0,short-opt-col=0,long-opt-col=0,doc-opt-col=0,opt-doc-col=0,header-col=0,rmargin=1' \
+ $(top_builddir)/src/tar --usage | \
+ sed -n 's/^\[--\([^]\=\[]*\).*/\1/p' | sort | uniq > opts.$$$$;\
+ $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) -E - \
+ $(info_TEXINFOS) | \
+ sed -n '/^@macro/,/^@end macro/d;s/@opindex *\([^@,]*\).*/\1/p' \
+ | sort | uniq > docs.$$$$;\
+ status=0;\
+ join -v1 opts.$$$$ docs.$$$$ > report.$$$$;\
+ if test -s report.$$$$; then \
+ echo 'Not documented options:'; \
+ cat report.$$$$; \
+ status=1; \
+ fi; \
+ join -v2 opts.$$$$ docs.$$$$ > report.$$$$;\
+ if test -s report.$$$$; then \
+ echo 'Non-existing options:';\
+ cat report.$$$$; \
+ status=1; \
+ fi; \
+ rm opts.$$$$ docs.$$$$ report.$$$$;\
+ test $$status -ne 0 && exit $$status
+
+check-refs:
+ @for file in $(info_TEXINFOS) $(tar_TEXINFOS); \
+ do \
+ sed -e = $$file | \
+ sed -n 'N;/@FIXME-.*ref/{s/\(^[0-9][0-9]*\).*@FIXME-.*ref{\([^}]*\).*/'$$file':\1: \2/gp}'; \
+ done > $@-t; \
+ if [ -s $@-t ]; then \
+ echo "Unresolved cross-references:"; \
+ cat $@-t;\
+ rm $@-t; \
+ else \
+ rm -f $@-t; \
+ fi
+
+check-fixmes:
+ @for file in $(info_TEXINFOS); \
+ do \
+ sed -e = $$file | \
+ sed -n 'N;/@FIXME{/{s/\(^[0-9][0-9]*\).*@FIXME{\([^}]*\).*/'$$file':\1: \2/gp}'; \
+ done > $@-t; \
+ if [ -s $@-t ]; then \
+ echo "Unresolved FIXMEs:"; \
+ cat $@-t; \
+ rm $@-t; \
+ false; \
+ else \
+ rm -f $@-t; \
+ fi
+
+check-unrevised:
+ @grep -Hn @UNREVISED $(info_TEXINFOS) > $@-t; \
+ if [ -s $@-t ]; then \
+ echo "Unrevised nodes:"; \
+ cat $@-t; \
+ rm $@-t; \
+ false;\
+ else \
+ rm $@-t; \
+ fi
+
+all-check-docs: check-format check-options check-refs check-fixmes check-unrevised
+
+check-docs:
+ $(MAKE) -k all-check-docs
+
+#
+
+clean-local:
+ rm -rf manual
+
+# Make sure you set TEXINPUTS
+# Usual value is:
+# /usr/share/texmf/pdftex/plain/misc:/usr/share/texmf/pdftex/config
+manual:
+ TEXINPUTS=$(srcdir):$(top_srcdir)/build-tex:$(TEXINPUTS) \
+ MAKEINFO="$(MAKEINFO) $(MAKEINFOFLAGS)" \
+ TEXI2DVI="$(TEXI2DVI) -t @finalout" \
+ $(GENDOCS) --texi2html tar 'GNU tar manual'
+
+# Tell versions [3.59,3.63) of GNU make to not export all variables.
+# Otherwise a system limit (for SysV at least) may be exceeded.
+.NOEXPORT:
diff --git a/doc/dumpdir.texi b/doc/dumpdir.texi
new file mode 100644
index 0000000..9ded73d
--- /dev/null
+++ b/doc/dumpdir.texi
@@ -0,0 +1,132 @@
+@c This is part of the paxutils manual.
+@c Copyright (C) 2006-2007, 2014, 2016 Free Software Foundation, Inc.
+@c Written by Sergey Poznyakoff
+@c This file is distributed under GFDL 1.1 or any later version
+@c published by the Free Software Foundation.
+
+ Incremental archives keep information about contents of each
+dumped directory in special data blocks called @dfn{dumpdirs}.
+
+ Dumpdir is a sequence of entries of the following form:
+
+@smallexample
+@var{C} @var{filename} \0
+@end smallexample
+
+@noindent
+where @var{C} is one of the @dfn{control codes} described below,
+@var{filename} is the name of the file @var{C} operates upon, and
+@samp{\0} represents a nul character (ASCII 0). The white space
+characters were added for readability, real dumpdirs do not contain
+them.
+
+ Each dumpdir ends with a single nul character.
+
+ The following table describes control codes and their meanings:
+
+@table @samp
+@item Y
+@var{filename} is contained in the archive.
+
+@item N
+@var{filename} was present in the directory at the time the archive
+was made, yet it was not dumped to the archive, because it had not
+changed since the last backup.
+
+@item D
+@var{filename} is a directory.
+
+@item R
+This code requests renaming of the @var{filename} to the name
+specified with the @samp{T} command, that immediately follows it.
+
+@item T
+Specify target file name for @samp{R} command (see below).
+
+@item X
+Specify @dfn{temporary directory} name for a rename operation (see below).
+@end table
+
+ Codes @samp{Y}, @samp{N} and @samp{D} require @var{filename} argument
+to be a relative file name to the directory this dumpdir describes,
+whereas codes @samp{R}, @samp{T} and @samp{X} require their argument
+to be an absolute file name.
+
+ The three codes @samp{R}, @samp{T} and @samp{X} specify a
+@dfn{renaming operation}. In the simplest case it is:
+
+@smallexample
+R@file{source}\0T@file{dest}\0
+@end smallexample
+
+@noindent
+which means ``rename file @file{source} to file @file{dest}''.
+
+ However, there are cases that require using a @dfn{temporary
+directory}. For example, consider the following scenario:
+
+@enumerate 1
+@item
+Previous run dumped a directory @file{foo} which contained the
+following three directories:
+
+@smallexample
+a
+b
+c
+@end smallexample
+
+@item
+They were renamed @emph{cyclically}, so that:
+
+@example
+@file{a} became @file{b}
+@file{b} became @file{c}
+@file{c} became @file{a}
+@end example
+
+@item
+New incremental dump was made.
+@end enumerate
+
+ This case cannot be handled by three successive renames, since
+renaming @file{a} to @file{b} will destroy the existing directory.
+To correctly process it, @GNUTAR{} needs a temporary directory, so
+it creates the following dumpdir (newlines have been added for
+readability):
+
+@smallexample
+@group
+Xfoo\0
+Rfoo/a\0T\0
+Rfoo/b\0Tfoo/c\0
+Rfoo/c\0Tfoo/a\0
+R\0Tfoo/a\0
+@end group
+@end smallexample
+
+ The first command, @samp{Xfoo\0}, instructs the extractor to create a
+temporary directory in the directory @file{foo}. Second command,
+@samp{Rfoo/aT\0}, says ``rename file @file{foo/a} to the temporary
+directory that has just been created'' (empty file name after a
+command means use temporary directory). Third and fourth commands
+work as usual, and, finally, the last command, @samp{R\0Tfoo/a\0}
+tells tar to rename the temporary directory to @file{foo/a}.
+
+ The exact placement of a dumpdir in the archive depends on the
+archive format (@pxref{Formats}):
+
+@itemize
+@item PAX archives
+
+In PAX archives, dumpdir is stored in the extended header of the
+corresponding directory, in variable @code{GNU.dumpdir}.
+
+@item GNU and old GNU archives
+
+These formats implement special header type @samp{D}, which is similar
+to ustar header @samp{5} (directory), except that it precedes a data
+block containing the dumpdir.
+@end itemize
+
+@c End of dumpdir.texi
diff --git a/doc/fdl.texi b/doc/fdl.texi
new file mode 100644
index 0000000..1246eb2
--- /dev/null
+++ b/doc/fdl.texi
@@ -0,0 +1,507 @@
+@c The GNU Free Documentation License.
+@center Version 1.3, 3 November 2008
+
+@c This file is intended to be included within another document,
+@c hence no sectioning command or @node.
+
+@display
+Copyright @copyright{} 2000-2002, 2007-2008, 2014, 2016 Free Software
+Foundation, Inc.
+@uref{http://fsf.org/}
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+@end display
+
+@enumerate 0
+@item
+PREAMBLE
+
+The purpose of this License is to make a manual, textbook, or other
+functional and useful document @dfn{free} in the sense of freedom: to
+assure everyone the effective freedom to copy and redistribute it,
+with or without modifying it, either commercially or noncommercially.
+Secondarily, this License preserves for the author and publisher a way
+to get credit for their work, while not being considered responsible
+for modifications made by others.
+
+This License is a kind of ``copyleft'', which means that derivative
+works of the document must themselves be free in the same sense. It
+complements the GNU General Public License, which is a copyleft
+license designed for free software.
+
+We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a free
+program should come with manuals providing the same freedoms that the
+software does. But this License is not limited to software manuals;
+it can be used for any textual work, regardless of subject matter or
+whether it is published as a printed book. We recommend this License
+principally for works whose purpose is instruction or reference.
+
+@item
+APPLICABILITY AND DEFINITIONS
+
+This License applies to any manual or other work, in any medium, that
+contains a notice placed by the copyright holder saying it can be
+distributed under the terms of this License. Such a notice grants a
+world-wide, royalty-free license, unlimited in duration, to use that
+work under the conditions stated herein. The ``Document'', below,
+refers to any such manual or work. Any member of the public is a
+licensee, and is addressed as ``you''. You accept the license if you
+copy, modify or distribute the work in a way requiring permission
+under copyright law.
+
+A ``Modified Version'' of the Document means any work containing the
+Document or a portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+
+A ``Secondary Section'' is a named appendix or a front-matter section
+of the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document's overall
+subject (or to related matters) and contains nothing that could fall
+directly within that overall subject. (Thus, if the Document is in
+part a textbook of mathematics, a Secondary Section may not explain
+any mathematics.) The relationship could be a matter of historical
+connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding
+them.
+
+The ``Invariant Sections'' are certain Secondary Sections whose titles
+are designated, as being those of Invariant Sections, in the notice
+that says that the Document is released under this License. If a
+section does not fit the above definition of Secondary then it is not
+allowed to be designated as Invariant. The Document may contain zero
+Invariant Sections. If the Document does not identify any Invariant
+Sections then there are none.
+
+The ``Cover Texts'' are certain short passages of text that are listed,
+as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+the Document is released under this License. A Front-Cover Text may
+be at most 5 words, and a Back-Cover Text may be at most 25 words.
+
+A ``Transparent'' copy of the Document means a machine-readable copy,
+represented in a format whose specification is available to the
+general public, that is suitable for revising the document
+straightforwardly with generic text editors or (for images composed of
+pixels) generic paint programs or (for drawings) some widely available
+drawing editor, and that is suitable for input to text formatters or
+for automatic translation to a variety of formats suitable for input
+to text formatters. A copy made in an otherwise Transparent file
+format whose markup, or absence of markup, has been arranged to thwart
+or discourage subsequent modification by readers is not Transparent.
+An image format is not Transparent if used for any substantial amount
+of text. A copy that is not ``Transparent'' is called ``Opaque''.
+
+Examples of suitable formats for Transparent copies include plain
+ASCII without markup, Texinfo input format, La@TeX{} input
+format, SGML or XML using a publicly available
+DTD, and standard-conforming simple HTML,
+PostScript or PDF designed for human modification. Examples
+of transparent image formats include PNG, XCF and
+JPG. Opaque formats include proprietary formats that can be
+read and edited only by proprietary word processors, SGML or
+XML for which the DTD and/or processing tools are
+not generally available, and the machine-generated HTML,
+PostScript or PDF produced by some word processors for
+output purposes only.
+
+The ``Title Page'' means, for a printed book, the title page itself,
+plus such following pages as are needed to hold, legibly, the material
+this License requires to appear in the title page. For works in
+formats which do not have any title page as such, ``Title Page'' means
+the text near the most prominent appearance of the work's title,
+preceding the beginning of the body of the text.
+
+The ``publisher'' means any person or entity that distributes copies
+of the Document to the public.
+
+A section ``Entitled XYZ'' means a named subunit of the Document whose
+title either is precisely XYZ or contains XYZ in parentheses following
+text that translates XYZ in another language. (Here XYZ stands for a
+specific section name mentioned below, such as ``Acknowledgements'',
+``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title''
+of such a section when you modify the Document means that it remains a
+section ``Entitled XYZ'' according to this definition.
+
+The Document may include Warranty Disclaimers next to the notice which
+states that this License applies to the Document. These Warranty
+Disclaimers are considered to be included by reference in this
+License, but only as regards disclaiming warranties: any other
+implication that these Warranty Disclaimers may have is void and has
+no effect on the meaning of this License.
+
+@item
+VERBATIM COPYING
+
+You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License applies
+to the Document are reproduced in all copies, and that you add no other
+conditions whatsoever to those of this License. You may not use
+technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute. However, you may accept
+compensation in exchange for copies. If you distribute a large enough
+number of copies you must also follow the conditions in section 3.
+
+You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+
+@item
+COPYING IN QUANTITY
+
+If you publish printed copies (or copies in media that commonly have
+printed covers) of the Document, numbering more than 100, and the
+Document's license notice requires Cover Texts, you must enclose the
+copies in covers that carry, clearly and legibly, all these Cover
+Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+the back cover. Both covers must also clearly and legibly identify
+you as the publisher of these copies. The front cover must present
+the full title with all words of the title equally prominent and
+visible. You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve
+the title of the Document and satisfy these conditions, can be treated
+as verbatim copying in other respects.
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+
+If you publish or distribute Opaque copies of the Document numbering
+more than 100, you must either include a machine-readable Transparent
+copy along with each Opaque copy, or state in or with each Opaque copy
+a computer-network location from which the general network-using
+public has access to download using public-standard network protocols
+a complete Transparent copy of the Document, free of added material.
+If you use the latter option, you must take reasonably prudent steps,
+when you begin distribution of Opaque copies in quantity, to ensure
+that this Transparent copy will remain thus accessible at the stated
+location until at least one year after the last time you distribute an
+Opaque copy (directly or through your agents or retailers) of that
+edition to the public.
+
+It is requested, but not required, that you contact the authors of the
+Document well before redistributing any large number of copies, to give
+them a chance to provide you with an updated version of the Document.
+
+@item
+MODIFICATIONS
+
+You may copy and distribute a Modified Version of the Document under
+the conditions of sections 2 and 3 above, provided that you release
+the Modified Version under precisely this License, with the Modified
+Version filling the role of the Document, thus licensing distribution
+and modification of the Modified Version to whoever possesses a copy
+of it. In addition, you must do these things in the Modified Version:
+
+@enumerate A
+@item
+Use in the Title Page (and on the covers, if any) a title distinct
+from that of the Document, and from those of previous versions
+(which should, if there were any, be listed in the History section
+of the Document). You may use the same title as a previous version
+if the original publisher of that version gives permission.
+
+@item
+List on the Title Page, as authors, one or more persons or entities
+responsible for authorship of the modifications in the Modified
+Version, together with at least five of the principal authors of the
+Document (all of its principal authors, if it has fewer than five),
+unless they release you from this requirement.
+
+@item
+State on the Title page the name of the publisher of the
+Modified Version, as the publisher.
+
+@item
+Preserve all the copyright notices of the Document.
+
+@item
+Add an appropriate copyright notice for your modifications
+adjacent to the other copyright notices.
+
+@item
+Include, immediately after the copyright notices, a license notice
+giving the public permission to use the Modified Version under the
+terms of this License, in the form shown in the Addendum below.
+
+@item
+Preserve in that license notice the full lists of Invariant Sections
+and required Cover Texts given in the Document's license notice.
+
+@item
+Include an unaltered copy of this License.
+
+@item
+Preserve the section Entitled ``History'', Preserve its Title, and add
+to it an item stating at least the title, year, new authors, and
+publisher of the Modified Version as given on the Title Page. If
+there is no section Entitled ``History'' in the Document, create one
+stating the title, year, authors, and publisher of the Document as
+given on its Title Page, then add an item describing the Modified
+Version as stated in the previous sentence.
+
+@item
+Preserve the network location, if any, given in the Document for
+public access to a Transparent copy of the Document, and likewise
+the network locations given in the Document for previous versions
+it was based on. These may be placed in the ``History'' section.
+You may omit a network location for a work that was published at
+least four years before the Document itself, or if the original
+publisher of the version it refers to gives permission.
+
+@item
+For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve
+the Title of the section, and preserve in the section all the
+substance and tone of each of the contributor acknowledgements and/or
+dedications given therein.
+
+@item
+Preserve all the Invariant Sections of the Document,
+unaltered in their text and in their titles. Section numbers
+or the equivalent are not considered part of the section titles.
+
+@item
+Delete any section Entitled ``Endorsements''. Such a section
+may not be included in the Modified Version.
+
+@item
+Do not retitle any existing section to be Entitled ``Endorsements'' or
+to conflict in title with any Invariant Section.
+
+@item
+Preserve any Warranty Disclaimers.
+@end enumerate
+
+If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant. To do this, add their titles to the
+list of Invariant Sections in the Modified Version's license notice.
+These titles must be distinct from any other section titles.
+
+You may add a section Entitled ``Endorsements'', provided it contains
+nothing but endorsements of your Modified Version by various
+parties---for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of a
+standard.
+
+You may add a passage of up to five words as a Front-Cover Text, and a
+passage of up to 25 words as a Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version. Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity. If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+
+The author(s) and publisher(s) of the Document do not by this License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+
+@item
+COMBINING DOCUMENTS
+
+You may combine the Document with other documents released under this
+License, under the terms defined in section 4 above for modified
+versions, provided that you include in the combination all of the
+Invariant Sections of all of the original documents, unmodified, and
+list them all as Invariant Sections of your combined work in its
+license notice, and that you preserve all their Warranty Disclaimers.
+
+The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a single
+copy. If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+author or publisher of that section if known, or else a unique number.
+Make the same adjustment to the section titles in the list of
+Invariant Sections in the license notice of the combined work.
+
+In the combination, you must combine any sections Entitled ``History''
+in the various original documents, forming one section Entitled
+``History''; likewise combine any sections Entitled ``Acknowledgements'',
+and any sections Entitled ``Dedications''. You must delete all
+sections Entitled ``Endorsements.''
+
+@item
+COLLECTIONS OF DOCUMENTS
+
+You may make a collection consisting of the Document and other documents
+released under this License, and replace the individual copies of this
+License in the various documents with a single copy that is included in
+the collection, provided that you follow the rules of this License for
+verbatim copying of each of the documents in all other respects.
+
+You may extract a single document from such a collection, and distribute
+it individually under this License, provided you insert a copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+
+@item
+AGGREGATION WITH INDEPENDENT WORKS
+
+A compilation of the Document or its derivatives with other separate
+and independent documents or works, in or on a volume of a storage or
+distribution medium, is called an ``aggregate'' if the copyright
+resulting from the compilation is not used to limit the legal rights
+of the compilation's users beyond what the individual works permit.
+When the Document is included in an aggregate, this License does not
+apply to the other works in the aggregate which are not themselves
+derivative works of the Document.
+
+If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one half of
+the entire aggregate, the Document's Cover Texts may be placed on
+covers that bracket the Document within the aggregate, or the
+electronic equivalent of covers if the Document is in electronic form.
+Otherwise they must appear on printed covers that bracket the whole
+aggregate.
+
+@item
+TRANSLATION
+
+Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+Replacing Invariant Sections with translations requires special
+permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections. You may include a
+translation of this License, and all the license notices in the
+Document, and any Warranty Disclaimers, provided that you also include
+the original English version of this License and the original versions
+of those notices and disclaimers. In case of a disagreement between
+the translation and the original version of this License or a notice
+or disclaimer, the original version will prevail.
+
+If a section in the Document is Entitled ``Acknowledgements'',
+``Dedications'', or ``History'', the requirement (section 4) to Preserve
+its Title (section 1) will typically require changing the actual
+title.
+
+@item
+TERMINATION
+
+You may not copy, modify, sublicense, or distribute the Document
+except as expressly provided under this License. Any attempt
+otherwise to copy, modify, sublicense, or distribute it is void, and
+will automatically terminate your rights under this License.
+
+However, if you cease all violation of this License, then your license
+from a particular copyright holder is reinstated (a) provisionally,
+unless and until the copyright holder explicitly and finally
+terminates your license, and (b) permanently, if the copyright holder
+fails to notify you of the violation by some reasonable means prior to
+60 days after the cessation.
+
+Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License. If your rights have been terminated and not permanently
+reinstated, receipt of a copy of some or all of the same material does
+not give you any rights to use it.
+
+@item
+FUTURE REVISIONS OF THIS LICENSE
+
+The Free Software Foundation may publish new, revised versions
+of the GNU Free Documentation License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns. See
+@uref{http://www.gnu.org/copyleft/}.
+
+Each version of the License is given a distinguishing version number.
+If the Document specifies that a particular numbered version of this
+License ``or any later version'' applies to it, you have the option of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a draft) by the
+Free Software Foundation. If the Document does not specify a version
+number of this License, you may choose any version ever published (not
+as a draft) by the Free Software Foundation. If the Document
+specifies that a proxy can decide which future versions of this
+License can be used, that proxy's public statement of acceptance of a
+version permanently authorizes you to choose that version for the
+Document.
+
+@item
+RELICENSING
+
+``Massive Multiauthor Collaboration Site'' (or ``MMC Site'') means any
+World Wide Web server that publishes copyrightable works and also
+provides prominent facilities for anybody to edit those works. A
+public wiki that anybody can edit is an example of such a server. A
+``Massive Multiauthor Collaboration'' (or ``MMC'') contained in the
+site means any set of copyrightable works thus published on the MMC
+site.
+
+``CC-BY-SA'' means the Creative Commons Attribution-Share Alike 3.0
+license published by Creative Commons Corporation, a not-for-profit
+corporation with a principal place of business in San Francisco,
+California, as well as future copyleft versions of that license
+published by that same organization.
+
+``Incorporate'' means to publish or republish a Document, in whole or
+in part, as part of another Document.
+
+An MMC is ``eligible for relicensing'' if it is licensed under this
+License, and if all works that were first published under this License
+somewhere other than this MMC, and subsequently incorporated in whole
+or in part into the MMC, (1) had no cover texts or invariant sections,
+and (2) were thus incorporated prior to November 1, 2008.
+
+The operator of an MMC Site may republish an MMC contained in the site
+under CC-BY-SA on the same site at any time before August 1, 2009,
+provided the MMC is eligible for relicensing.
+
+@end enumerate
+
+@page
+@heading ADDENDUM: How to use this License for your documents
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+
+@smallexample
+@group
+ Copyright (C) @var{year} @var{your name}.
+ Permission is granted to copy, distribute and/or modify this document
+ under the terms of the GNU Free Documentation License, Version 1.3
+ or any later version published by the Free Software Foundation;
+ with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
+ Texts. A copy of the license is included in the section entitled ``GNU
+ Free Documentation License''.
+@end group
+@end smallexample
+
+If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
+replace the ``with@dots{}Texts.'' line with this:
+
+@smallexample
+@group
+ with the Invariant Sections being @var{list their titles}, with
+ the Front-Cover Texts being @var{list}, and with the Back-Cover Texts
+ being @var{list}.
+@end group
+@end smallexample
+
+If you have Invariant Sections without Cover Texts, or some other
+combination of the three, merge those two alternatives to suit the
+situation.
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License,
+to permit their use in free software.
+
+@c Local Variables:
+@c ispell-local-pdict: "ispell-dict"
+@c End:
+
diff --git a/doc/freemanuals.texi b/doc/freemanuals.texi
new file mode 100644
index 0000000..25343f9
--- /dev/null
+++ b/doc/freemanuals.texi
@@ -0,0 +1,89 @@
+@cindex free documentation
+
+The biggest deficiency in the free software community today is not in
+the software---it is the lack of good free documentation that we can
+include with the free software. Many of our most important
+programs do not come with free reference manuals and free introductory
+texts. Documentation is an essential part of any software package;
+when an important free software package does not come with a free
+manual and a free tutorial, that is a major gap. We have many such
+gaps today.
+
+Consider Perl, for instance. The tutorial manuals that people
+normally use are non-free. How did this come about? Because the
+authors of those manuals published them with restrictive terms---no
+copying, no modification, source files not available---which exclude
+them from the free software world.
+
+That wasn't the first time this sort of thing happened, and it was far
+from the last. Many times we have heard a GNU user eagerly describe a
+manual that he is writing, his intended contribution to the community,
+only to learn that he had ruined everything by signing a publication
+contract to make it non-free.
+
+Free documentation, like free software, is a matter of freedom, not
+price. The problem with the non-free manual is not that publishers
+charge a price for printed copies---that in itself is fine. (The Free
+Software Foundation sells printed copies of manuals, too.) The
+problem is the restrictions on the use of the manual. Free manuals
+are available in source code form, and give you permission to copy and
+modify. Non-free manuals do not allow this.
+
+The criteria of freedom for a free manual are roughly the same as for
+free software. Redistribution (including the normal kinds of
+commercial redistribution) must be permitted, so that the manual can
+accompany every copy of the program, both on-line and on paper.
+
+Permission for modification of the technical content is crucial too.
+When people modify the software, adding or changing features, if they
+are conscientious they will change the manual too---so they can
+provide accurate and clear documentation for the modified program. A
+manual that leaves you no choice but to write a new manual to document
+a changed version of the program is not really available to our
+community.
+
+Some kinds of limits on the way modification is handled are
+acceptable. For example, requirements to preserve the original
+author's copyright notice, the distribution terms, or the list of
+authors, are ok. It is also no problem to require modified versions
+to include notice that they were modified. Even entire sections that
+may not be deleted or changed are acceptable, as long as they deal
+with nontechnical topics (like this one). These kinds of restrictions
+are acceptable because they don't obstruct the community's normal use
+of the manual.
+
+However, it must be possible to modify all the @emph{technical}
+content of the manual, and then distribute the result in all the usual
+media, through all the usual channels. Otherwise, the restrictions
+obstruct the use of the manual, it is not free, and we need another
+manual to replace it.
+
+Please spread the word about this issue. Our community continues to
+lose manuals to proprietary publishing. If we spread the word that
+free software needs free reference manuals and free tutorials, perhaps
+the next person who wants to contribute by writing documentation will
+realize, before it is too late, that only free manuals contribute to
+the free software community.
+
+If you are writing documentation, please insist on publishing it under
+the GNU Free Documentation License or another free documentation
+license. Remember that this decision requires your approval---you
+don't have to let the publisher decide. Some commercial publishers
+will use a free license if you insist, but they will not propose the
+option; it is up to you to raise the issue and say firmly that this is
+what you want. If the publisher you are dealing with refuses, please
+try other publishers. If you're not sure whether a proposed license
+is free, write to @email{licensing@@gnu.org}.
+
+You can encourage commercial publishers to sell more free, copylefted
+manuals and tutorials by buying them, and particularly by buying
+copies from the publishers that paid for their writing or for major
+improvements. Meanwhile, try to avoid buying non-free documentation
+at all. Check the distribution terms of a manual before you buy it,
+and insist that whoever seeks your business must respect your freedom.
+Check the history of the book, and try reward the publishers that have
+paid or pay the authors to work on it.
+
+The Free Software Foundation maintains a list of free documentation
+published by other publishers, at
+@url{http://www.fsf.org/doc/other-free-books.html}.
diff --git a/doc/gendocs_template b/doc/gendocs_template
new file mode 100755
index 0000000..d67f898
--- /dev/null
+++ b/doc/gendocs_template
@@ -0,0 +1,125 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<!-- $Id: gendocs_template,v 1.5 2007/10/30 14:58:52 gray Exp $ -->
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
+
+<head>
+<title>%%TITLE%% - GNU Project - Free Software Foundation (FSF)</title>
+<meta http-equiv="content-type" content='text/html; charset=utf-8' />
+<link rel="stylesheet" type="text/css" href="/gnu.css" />
+<link rev="made" href="mailto:gray@gnu.org" />
+ <link rel="icon" type="image/png" href="/graphics/gnu-head-icon.png" />
+</head>
+
+<!-- This document is in XML, and xhtml 1.0 -->
+<!-- Please make sure to properly nest your tags -->
+<!-- and ensure that your final document validates -->
+<!-- consistent with W3C xhtml 1.0 and CSS standards -->
+<!-- See validator.w3.org -->
+
+<body>
+
+<h3>%%TITLE%%</h3>
+
+<address>Free Software Foundation</address>
+<address>last updated %%DATE%%</address>
+<p>
+<a href="/graphics/gnu-head.jpg">
+ <img src="/graphics/gnu-head-sm.jpg"
+ alt=" [image of the head of a GNU] "
+ width="129" height="122" />
+</a>
+</p>
+<hr />
+
+<p>The manual for %%PACKAGE%% is available in the following formats:</p>
+
+<ul>
+ <li><a href="%%PACKAGE%%.html">HTML
+ (%%HTML_MONO_SIZE%%K bytes)</a> - entirely on one web page.</li>
+ <li><a href="html_node/index.html">HTML</a> - with one web page per
+ node.</li>
+%%IF HTML_SECTION%%
+ <li><a href="html_section/index.html">HTML</a> - with one web page per
+ section.</li>
+%%ENDIF HTML_SECTION%%
+%%IF HTML_CHAPTER%%
+ <li><a href="html_chapter/index.html">HTML</a> - with one web page per
+ chapter.</li>
+%%ENDIF HTML_CHAPTER%%
+ <li><a href="%%PACKAGE%%.html.gz">HTML compressed
+ (%%HTML_MONO_GZ_SIZE%%K gzipped characters)</a> - entirely on
+ one web page.</li>
+ <li><a href="%%PACKAGE%%.html_node.tar.gz">HTML compressed
+ (%%HTML_NODE_TGZ_SIZE%%K gzipped tar file)</a> -
+ with one web page per node.</li>
+%%IF HTML_SECTION%%
+ <li><a href="%%PACKAGE%%.html_section.tar.gz">HTML compressed
+ (%%HTML_SECTION_TGZ_SIZE%%K gzipped tar file)</a> -
+ with one web page per section.</li>
+%%ENDIF HTML_SECTION%%
+%%IF HTML_CHAPTER%%
+ <li><a href="%%PACKAGE%%.html_chapter.tar.gz">HTML compressed
+ (%%HTML_CHAPTER_TGZ_SIZE%%K gzipped tar file)</a> -
+ with one web page per chapter.</li>
+%%ENDIF HTML_CHAPTER%%
+ <li><a href="%%PACKAGE%%.info.tar.gz">Info document
+ (%%INFO_TGZ_SIZE%%K characters gzipped tar file)</a>.</li>
+ <li><a href="%%PACKAGE%%.txt">ASCII text
+ (%%ASCII_SIZE%%K characters)</a>.</li>
+ <li><a href="%%PACKAGE%%.txt.gz">ASCII text compressed
+ (%%ASCII_GZ_SIZE%%K gzipped characters)</a>.</li>
+ <li><a href="%%PACKAGE%%.dvi.gz">TeX dvi file
+ (%%DVI_GZ_SIZE%%K characters gzipped)</a>.</li>
+ <li><a href="%%PACKAGE%%.ps.gz">PostScript file
+ (%%PS_GZ_SIZE%%K characters gzipped)</a>.</li>
+ <li><a href="%%PACKAGE%%.pdf">PDF file
+ (%%PDF_SIZE%%K characters)</a>.</li>
+ <li><a href="%%PACKAGE%%.texi.tar.gz">Texinfo source
+ (%%TEXI_TGZ_SIZE%%K characters gzipped tar file)</a></li>
+</ul>
+
+<p>(This page generated by the <a
+href="%%SCRIPTURL%%">%%SCRIPTNAME%%</a> script.)
+</p>
+
+<p>
+<a href="http://validator.w3.org/check?uri=referer"><img
+ src="http://www.w3.org/Icons/valid-xhtml10"
+ alt="Valid XHTML 1.0!" height="31" width="88" /></a>
+</p>
+
+<div class="copyright">
+<p>
+Return to the <a href="/home.html">GNU Project home page</a>.
+</p>
+
+<p>
+Please send FSF &amp; GNU inquiries to
+<a href="mailto:gnu@gnu.org"><em>gnu@gnu.org</em></a>.
+There are also <a href="/home.html#ContactInfo">other ways to contact</a>
+the FSF.
+<br />
+Please send broken links and other corrections (or suggestions) to
+<a href="mailto:webmasters@gnu.org"><em>webmasters@gnu.org</em></a>.
+</p>
+
+<p>
+Copyright 2004, 2013-2014, 2016 Free Software Foundation, Inc.,
+51 Franklin Street, Fifth Floor, Boston, MA 02111, USA
+<br />
+Verbatim copying and distribution of this entire article is
+permitted in any medium, provided this notice is preserved.
+</p>
+
+<p>
+Updated:
+<!-- timestamp start -->
+$Date: 2007/10/30 14:58:52 $ $Author: gray $
+<!-- timestamp end -->
+</p>
+</div>
+
+</body>
+</html>
diff --git a/doc/genfile.texi b/doc/genfile.texi
new file mode 100644
index 0000000..e35f34b
--- /dev/null
+++ b/doc/genfile.texi
@@ -0,0 +1,367 @@
+@c This is part of the paxutils manual.
+@c Copyright (C) 2005, 2006, 2009 Free Software Foundation, Inc.
+@c Written by Sergey Poznyakoff
+@c This file is distributed under GFDL 1.1 or any later version
+@c published by the Free Software Foundation.
+
+@cindex genfile
+ This appendix describes @command{genfile}, an auxiliary program
+used in the GNU tar testsuite. If you are not interested in developing
+GNU tar, skip this appendix.
+
+ Initially, @command{genfile} was used to generate data files for
+the testsuite, hence its name. However, new operation modes were being
+implemented as the testsuite grew more sophisticated, and now
+@command{genfile} is a multi-purpose instrument.
+
+ There are three basic operation modes:
+
+@table @asis
+@item File Generation
+ This is the default mode. In this mode, @command{genfile}
+generates data files.
+
+@item File Status
+ In this mode @command{genfile} displays status of specified files.
+
+@item Synchronous Execution.
+ In this mode @command{genfile} executes the given program with
+@option{--checkpoint} option and executes a set of actions when
+specified checkpoints are reached.
+@end table
+
+@menu
+* Generate Mode:: File Generation Mode.
+* Status Mode:: File Status Mode.
+* Exec Mode:: Synchronous Execution mode.
+@end menu
+
+@node Generate Mode
+@appendixsec Generate Mode
+
+@cindex Generate Mode, @command{genfile}
+@cindex @command{genfile}, generate mode
+@cindex @command{genfile}, create file
+ In this mode @command{genfile} creates a data file for the test
+suite. The size of the file is given with the @option{--length}
+(@option{-l}) option. By default the file contents is written to the
+standard output, this can be changed using @option{--file}
+(@option{-f}) command line option. Thus, the following two commands
+are equivalent:
+
+@smallexample
+@group
+genfile --length 100 > outfile
+genfile --length 100 --file outfile
+@end group
+@end smallexample
+
+ If @option{--length} is not given, @command{genfile} will
+generate an empty (zero-length) file.
+
+@cindex @command{genfile}, seeking to a given offset
+ The command line option @option{--seek=@var{N}} istructs @command{genfile}
+to skip the given number of bytes (@var{N}) in the output file before
+writing to it. It is similar to the @option{seek=@var{N}} of the
+@command{dd} utility.
+
+@cindex @command{genfile}, reading a list of file names
+ You can instruct @command{genfile} to create several files at one
+go, by giving it @option{--files-from} (@option{-T}) option followed
+by a name of file containing a list of file names. Using dash
+(@samp{-}) instead of the file name causes @command{genfile} to read
+file list from the standard input. For example:
+
+@smallexample
+@group
+# Read file names from file @file{file.list}
+genfile --files-from file.list
+# Read file names from standard input
+genfile --files-from -
+@end group
+@end smallexample
+
+@cindex File lists separated by NUL characters
+ The list file is supposed to contain one file name per line. To
+use file lists separated by ASCII NUL character, use @option{--null}
+(@option{-0}) command line option:
+
+@smallexample
+genfile --null --files-from file.list
+@end smallexample
+
+@cindex pattern, @command{genfile}
+ The default data pattern for filling the generated file consists
+of first 256 letters of ASCII code, repeated enough times to fill the
+entire file. This behavior can be changed with @option{--pattern}
+option. This option takes a mandatory argument, specifying pattern
+name to use. Currently two patterns are implemented:
+
+@table @option
+@item --pattern=default
+ The default pattern as described above.
+
+@item --pattern=zero
+ Fills the file with zeroes.
+@end table
+
+ If no file name was given, the program exits with the code
+@code{0}. Otherwise, it exits with @code{0} only if it was able to
+create a file of the specified length.
+
+@cindex Sparse files, creating using @command{genfile}
+@cindex @command{genfile}, creating sparse files
+ Special option @option{--sparse} (@option{-s}) instructs
+@command{genfile} to create a sparse file. Sparse files consist of
+@dfn{data fragments}, separated by @dfn{holes} or blocks of zeros. On
+many operating systems, actual disk storage is not allocated for
+holes, but they are counted in the length of the file. To create a
+sparse file, @command{genfile} should know where to put data fragments,
+and what data to use to fill them. So, when @option{--sparse} is given
+the rest of the command line specifies a so-called @dfn{file map}.
+
+ The file map consists of any number of @dfn{fragment
+descriptors}. Each descriptor is composed of two values: a number,
+specifying fragment offset from the end of the previous fragment or,
+for the very first fragment, from the beginning of the file, and
+@dfn{contents string}, that specifies the pattern to fill the fragment
+with. File offset can be suffixed with the following quantifiers:
+
+@table @samp
+@item k
+@itemx K
+The number is expressed in kilobytes.
+@item m
+@itemx M
+The number is expressed in megabytes.
+@item g
+@itemx G
+The number is expressed in gigabytes.
+@end table
+
+ Contents string can be either a fragment size or a pattern.
+Fragment size is a decimal number, prefixed with an equals sign. It
+can be suffixed with a quantifier, as discussed above. If fragment
+size is given, the fragment of that size will be filled with the
+currently selected pattern (@pxref{Generate Mode, --pattern}) and
+written to the file.
+
+ A pattern is a string of arbitrary ASCII characters. For each
+of them, @command{genfile} will generate a @dfn{block} of data,
+filled with that character and will write it to the fragment. The size
+of block is given by @option{--block-size} option. It defaults to 512.
+Thus, if pattern consists of @var{n} characters, the resulting file
+fragment will contain @code{@var{n}*@var{block-size}} bytes of data.
+
+ The last fragment descriptor can have only file offset part. In this
+case @command{genfile} will create a hole at the end of the file up to
+the given offset.
+
+ A dash appearing as a fragment descriptor instructs
+@command{genfile} to read file map from the standard input. Each line
+of input should consist of fragment offset and contents string,
+separated by any amount of whitespace.
+
+ For example, consider the following invocation:
+
+@smallexample
+genfile --sparse --file sparsefile 0 ABCD 1M EFGHI 2000K
+@end smallexample
+
+@noindent
+It will create 3101184-bytes long file of the following structure:
+
+@multitable @columnfractions .35 .20 .45
+@item Offset @tab Length @tab Contents
+@item 0 @tab 4*512=2048 @tab Four 512-byte blocks, filled with
+letters @samp{A}, @samp{B}, @samp{C} and @samp{D}.
+@item 2048 @tab 1046528 @tab Zero bytes
+@item 1050624 @tab 5*512=2560 @tab Five blocks, filled with letters
+@samp{E}, @samp{F}, @samp{G}, @samp{H}, @samp{I}.
+@item 1053184 @tab 2048000 @tab Zero bytes
+@end multitable
+
+@cindex --quite, option
+ The exit code of @command{genfile --sparse} command is @code{0}
+only if created file is actually sparse. If it is not, the
+appropriate error message is displayed and the command exists with
+code @code{1}. The @option{--quite} (@option{-q}) option suppresses
+this behavior. If @option{--quite} is given, @command{genfile
+--sparse} exits with code @code{0} if it was able to create the file,
+whether the resulting file is sparse or not.
+
+@node Status Mode
+@appendixsec Status Mode
+
+ In status mode, @command{genfile} prints file system status for
+each file specified in the command line. This mode is toggled by
+@option{--stat} (@option{-S}) command line option. An optional argument to this
+option specifies output @dfn{format}: a comma-separated list of
+@code{struct stat} fields to be displayed. This list can contain
+following identifiers:
+
+@table @asis
+@item name
+ The file name.
+
+@item dev
+@itemx st_dev
+ Device number in decimal.
+
+@item ino
+@itemx st_ino
+ Inode number.
+
+@item mode[.@var{number}]
+@itemx st_mode[.@var{number}]
+
+@FIXME{Should we also support @samp{%} notations as in stat(1)?}
+
+ File mode in octal. Optional @var{number} specifies octal mask to
+be applied to the mode before outputting. For example, @code{--stat
+mode.777} will preserve lower nine bits of it. Notice, that you can
+use any punctuation character in place of @samp{.}.
+
+@item nlink
+@itemx st_nlink
+ Number of hard links.
+
+@item uid
+@itemx st_uid
+ User ID of owner.
+
+@item gid
+@itemx st_gid
+ Group ID of owner.
+
+@item size
+@itemx st_size
+ File size in decimal.
+
+@item blksize
+@itemx st_blksize
+ The size in bytes of each file block.
+
+@item blocks
+@itemx st_blocks
+ Number of blocks allocated.
+
+@item atime
+@itemx st_atime
+ Time of last access.
+
+@item mtime
+@itemx st_mtime
+ Time of last modification
+
+@item ctime
+@itemx st_ctime
+ Time of last status change
+
+@item sparse
+ A boolean value indicating whether the file is @samp{sparse}.
+@end table
+
+ Modification times are displayed in @acronym{UTC} as
+@acronym{UNIX} timestamps, unless suffixed with @samp{H} (for
+``human-readable''), as in @samp{ctimeH}, in which case usual
+@code{tar tv} output format is used.
+
+ The default output format is: @samp{name,dev,ino,mode,
+nlink,uid,gid,size,blksize,blocks,atime,mtime,ctime}.
+
+ For example, the following command will display file names and
+corresponding times of last access for each file in the current working
+directory:
+
+@smallexample
+genfile --stat=name,atime *
+@end smallexample
+
+@node Exec Mode
+@appendixsec Exec Mode
+
+@cindex Exec Mode, @command{genfile}
+ This mode is designed for testing the behavior of @code{paxutils}
+commands when some of the files change during archiving. It is an
+experimental mode.
+
+ The @samp{Exec Mode} is toggled by @option{--run} command line
+option (or its alias @option{-r}). The non-optional arguments to
+@command{getopt} give the command line to be executed. Normally,
+it should contain at least the @option{--checkpoint} option.
+
+ A set of options is provided for defining checkpoint values and
+actions to be executed upon reaching them. Checkpoint values are
+introduced with the @option{--checkpoint} command line
+option. Argument to this option is the number of checkpoint in decimal.
+
+ Any number of @dfn{actions} may be specified after a
+checkpoint. Available actions are
+
+@table @option
+@item --cut @var{file}
+@itemx --truncate @var{file}
+ Truncate @var{file} to the size specified by previous
+@option{--length} option (or 0, if it is not given).
+
+@item --append @var{file}
+ Append data to @var{file}. The size of data and its pattern are
+given by previous @option{--length} and @option{pattern} options.
+
+@item --touch @var{file}
+ Update the access and modification times of @var{file}. These
+timestamps are changed to the current time, unless @option{--date}
+option was given, in which case they are changed to the specified
+time. Argument to @option{--date} option is a date specification in
+an almost arbitrary format (@pxref{Date input formats}).
+
+@item --exec @var{command}
+ Execute given shell command.
+
+@item --unlink @var{file}
+ Unlink the @var{file}.
+@end table
+
+ Option @option{--verbose} instructs @command{genfile} to print on
+standard output notifications about checkpoints being executed and to
+verbosely describe exit status of the command.
+
+ While the command is being executed its standard output remains
+connected to descriptor 1. All messages it prints to file descriptor
+2, except checkpoint notifications, are forwarded to standard
+error.
+
+ @command{Genfile} exits with the exit status of the executed command.
+
+ For compatibility with previous @command{genfile} versions, the
+@option{--run} option takes an optional argument. If used this way,
+its argument supplies the command line to be executed. There should
+be no non-optional arguments in the @command{genfile} command line.
+
+ The actual command line is constructed by inserting
+the @option{--checkpoint} option between the command name and its
+first argument (if any). Due to this, the argument to @option{--run}
+may not use traditional @command{tar} option syntax, i.e., the
+following is wrong:
+
+@smallexample
+# Wrong!
+genfile --run='tar cf foo bar'
+@end smallexample
+
+@noindent
+
+Use the following syntax instead:
+
+@smallexample
+genfile --run='tar -cf foo bar' @var{actions}...
+@end smallexample
+
+The above command line is equivalent to
+
+@smallexample
+genfile @var{actions}... -- tar -cf foo bar
+@end smallexample
+
+Notice, that the use of compatibility mode is deprecated.
diff --git a/doc/header.texi b/doc/header.texi
new file mode 100644
index 0000000..b35b6d4
--- /dev/null
+++ b/doc/header.texi
@@ -0,0 +1,243 @@
+@comment GNU tar Archive Format description.
+@comment
+@comment Copyright 1988-1989, 1991-1997, 2000-2001, 2003-2007, 2012-2014, 2016
+@comment Free Software Foundation, Inc.
+@comment
+@comment This file is part of GNU tar.
+@comment
+@comment GNU tar is free software; you can redistribute it and/or modify
+@comment it under the terms of the GNU General Public License as published by
+@comment the Free Software Foundation; either version 3 of the License, or
+@comment (at your option) any later version.
+@comment
+@comment GNU tar is distributed in the hope that it will be useful,
+@comment but WITHOUT ANY WARRANTY; without even the implied warranty of
+@comment MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+@comment GNU General Public License for more details.
+@comment
+@comment You should have received a copy of the GNU General Public License
+@comment along with this program. If not, see <http://www.gnu.org/licenses/>.
+
+/*@r{ tar Header Block, from POSIX 1003.1-1990. }*/
+
+/*@r{ POSIX header. }*/
+
+struct posix_header
+@{ /*@r{ byte offset }*/
+ char name[100]; /*@r{ 0 }*/
+ char mode[8]; /*@r{ 100 }*/
+ char uid[8]; /*@r{ 108 }*/
+ char gid[8]; /*@r{ 116 }*/
+ char size[12]; /*@r{ 124 }*/
+ char mtime[12]; /*@r{ 136 }*/
+ char chksum[8]; /*@r{ 148 }*/
+ char typeflag; /*@r{ 156 }*/
+ char linkname[100]; /*@r{ 157 }*/
+ char magic[6]; /*@r{ 257 }*/
+ char version[2]; /*@r{ 263 }*/
+ char uname[32]; /*@r{ 265 }*/
+ char gname[32]; /*@r{ 297 }*/
+ char devmajor[8]; /*@r{ 329 }*/
+ char devminor[8]; /*@r{ 337 }*/
+ char prefix[155]; /*@r{ 345 }*/
+ /*@r{ 500 }*/
+@};
+
+#define TMAGIC "ustar" /*@r{ ustar and a null }*/
+#define TMAGLEN 6
+#define TVERSION "00" /*@r{ 00 and no null }*/
+#define TVERSLEN 2
+
+/*@r{ Values used in typeflag field. }*/
+#define REGTYPE '0' /*@r{ regular file }*/
+#define AREGTYPE '\0' /*@r{ regular file }*/
+#define LNKTYPE '1' /*@r{ link }*/
+#define SYMTYPE '2' /*@r{ reserved }*/
+#define CHRTYPE '3' /*@r{ character special }*/
+#define BLKTYPE '4' /*@r{ block special }*/
+#define DIRTYPE '5' /*@r{ directory }*/
+#define FIFOTYPE '6' /*@r{ FIFO special }*/
+#define CONTTYPE '7' /*@r{ reserved }*/
+
+#define XHDTYPE 'x' /*@r{ Extended header referring to the
+ next file in the archive }*/
+#define XGLTYPE 'g' /*@r{ Global extended header }*/
+
+/*@r{ Bits used in the mode field, values in octal. }*/
+#define TSUID 04000 /*@r{ set UID on execution }*/
+#define TSGID 02000 /*@r{ set GID on execution }*/
+#define TSVTX 01000 /*@r{ reserved }*/
+ /*@r{ file permissions }*/
+#define TUREAD 00400 /*@r{ read by owner }*/
+#define TUWRITE 00200 /*@r{ write by owner }*/
+#define TUEXEC 00100 /*@r{ execute/search by owner }*/
+#define TGREAD 00040 /*@r{ read by group }*/
+#define TGWRITE 00020 /*@r{ write by group }*/
+#define TGEXEC 00010 /*@r{ execute/search by group }*/
+#define TOREAD 00004 /*@r{ read by other }*/
+#define TOWRITE 00002 /*@r{ write by other }*/
+#define TOEXEC 00001 /*@r{ execute/search by other }*/
+
+/*@r{ tar Header Block, GNU extensions. }*/
+
+/*@r{ In GNU tar, SYMTYPE is for to symbolic links, and CONTTYPE is for
+ contiguous files, so maybe disobeying the "reserved" comment in POSIX
+ header description. I suspect these were meant to be used this way, and
+ should not have really been "reserved" in the published standards. }*/
+
+/*@r{ *BEWARE* *BEWARE* *BEWARE* that the following information is still
+ boiling, and may change. Even if the OLDGNU format description should be
+ accurate, the so-called GNU format is not yet fully decided. It is
+ surely meant to use only extensions allowed by POSIX, but the sketch
+ below repeats some ugliness from the OLDGNU format, which should rather
+ go away. Sparse files should be saved in such a way that they do *not*
+ require two passes at archive creation time. Huge files get some POSIX
+ fields to overflow, alternate solutions have to be sought for this. }*/
+
+/*@r{ Descriptor for a single file hole. }*/
+
+struct sparse
+@{ /*@r{ byte offset }*/
+ char offset[12]; /*@r{ 0 }*/
+ char numbytes[12]; /*@r{ 12 }*/
+ /*@r{ 24 }*/
+@};
+
+/*@r{ Sparse files are not supported in POSIX ustar format. For sparse files
+ with a POSIX header, a GNU extra header is provided which holds overall
+ sparse information and a few sparse descriptors. When an old GNU header
+ replaces both the POSIX header and the GNU extra header, it holds some
+ sparse descriptors too. Whether POSIX or not, if more sparse descriptors
+ are still needed, they are put into as many successive sparse headers as
+ necessary. The following constants tell how many sparse descriptors fit
+ in each kind of header able to hold them. }*/
+
+#define SPARSES_IN_EXTRA_HEADER 16
+#define SPARSES_IN_OLDGNU_HEADER 4
+#define SPARSES_IN_SPARSE_HEADER 21
+
+/*@r{ Extension header for sparse files, used immediately after the GNU extra
+ header, and used only if all sparse information cannot fit into that
+ extra header. There might even be many such extension headers, one after
+ the other, until all sparse information has been recorded. }*/
+
+struct sparse_header
+@{ /*@r{ byte offset }*/
+ struct sparse sp[SPARSES_IN_SPARSE_HEADER];
+ /*@r{ 0 }*/
+ char isextended; /*@r{ 504 }*/
+ /*@r{ 505 }*/
+@};
+
+/*@r{ The old GNU format header conflicts with POSIX format in such a way that
+ POSIX archives may fool old GNU tar's, and POSIX tar's might well be
+ fooled by old GNU tar archives. An old GNU format header uses the space
+ used by the prefix field in a POSIX header, and cumulates information
+ normally found in a GNU extra header. With an old GNU tar header, we
+ never see any POSIX header nor GNU extra header. Supplementary sparse
+ headers are allowed, however. }*/
+
+struct oldgnu_header
+@{ /*@r{ byte offset }*/
+ char unused_pad1[345]; /*@r{ 0 }*/
+ char atime[12]; /*@r{ 345 Incr. archive: atime of the file }*/
+ char ctime[12]; /*@r{ 357 Incr. archive: ctime of the file }*/
+ char offset[12]; /*@r{ 369 Multivolume archive: the offset of
+ the start of this volume }*/
+ char longnames[4]; /*@r{ 381 Not used }*/
+ char unused_pad2; /*@r{ 385 }*/
+ struct sparse sp[SPARSES_IN_OLDGNU_HEADER];
+ /*@r{ 386 }*/
+ char isextended; /*@r{ 482 Sparse file: Extension sparse header
+ follows }*/
+ char realsize[12]; /*@r{ 483 Sparse file: Real size}*/
+ /*@r{ 495 }*/
+@};
+
+/*@r{ OLDGNU_MAGIC uses both magic and version fields, which are contiguous.
+ Found in an archive, it indicates an old GNU header format, which will be
+ hopefully become obsolescent. With OLDGNU_MAGIC, uname and gname are
+ valid, though the header is not truly POSIX conforming. }*/
+#define OLDGNU_MAGIC "ustar " /*@r{ 7 chars and a null }*/
+
+/*@r{ The standards committee allows only capital A through capital Z for
+ user-defined expansion. Other letters in use include:
+
+ 'A' Solaris Access Control List
+ 'E' Solaris Extended Attribute File
+ 'I' Inode only, as in 'star'
+ 'N' Obsolete GNU tar, for file names that do not fit into the main header.
+ 'X' POSIX 1003.1-2001 eXtended (VU version) }*/
+
+/*@r{ This is a dir entry that contains the names of files that were in the
+ dir at the time the dump was made. }*/
+#define GNUTYPE_DUMPDIR 'D'
+
+/*@r{ Identifies the *next* file on the tape as having a long linkname. }*/
+#define GNUTYPE_LONGLINK 'K'
+
+/*@r{ Identifies the *next* file on the tape as having a long name. }*/
+#define GNUTYPE_LONGNAME 'L'
+
+/*@r{ This is the continuation of a file that began on another volume. }*/
+#define GNUTYPE_MULTIVOL 'M'
+
+/*@r{ This is for sparse files. }*/
+#define GNUTYPE_SPARSE 'S'
+
+/*@r{ This file is a tape/volume header. Ignore it on extraction. }*/
+#define GNUTYPE_VOLHDR 'V'
+
+/*@r{ Solaris extended header }*/
+#define SOLARIS_XHDTYPE 'X'
+
+/*@r{ J@"org Schilling star header }*/
+
+struct star_header
+@{ /*@r{ byte offset }*/
+ char name[100]; /*@r{ 0 }*/
+ char mode[8]; /*@r{ 100 }*/
+ char uid[8]; /*@r{ 108 }*/
+ char gid[8]; /*@r{ 116 }*/
+ char size[12]; /*@r{ 124 }*/
+ char mtime[12]; /*@r{ 136 }*/
+ char chksum[8]; /*@r{ 148 }*/
+ char typeflag; /*@r{ 156 }*/
+ char linkname[100]; /*@r{ 157 }*/
+ char magic[6]; /*@r{ 257 }*/
+ char version[2]; /*@r{ 263 }*/
+ char uname[32]; /*@r{ 265 }*/
+ char gname[32]; /*@r{ 297 }*/
+ char devmajor[8]; /*@r{ 329 }*/
+ char devminor[8]; /*@r{ 337 }*/
+ char prefix[131]; /*@r{ 345 }*/
+ char atime[12]; /*@r{ 476 }*/
+ char ctime[12]; /*@r{ 488 }*/
+ /*@r{ 500 }*/
+@};
+
+#define SPARSES_IN_STAR_HEADER 4
+#define SPARSES_IN_STAR_EXT_HEADER 21
+
+struct star_in_header
+@{
+ char fill[345]; /*@r{ 0 Everything that is before t_prefix }*/
+ char prefix[1]; /*@r{ 345 t_name prefix }*/
+ char fill2; /*@r{ 346 }*/
+ char fill3[8]; /*@r{ 347 }*/
+ char isextended; /*@r{ 355 }*/
+ struct sparse sp[SPARSES_IN_STAR_HEADER]; /*@r{ 356 }*/
+ char realsize[12]; /*@r{ 452 Actual size of the file }*/
+ char offset[12]; /*@r{ 464 Offset of multivolume contents }*/
+ char atime[12]; /*@r{ 476 }*/
+ char ctime[12]; /*@r{ 488 }*/
+ char mfill[8]; /*@r{ 500 }*/
+ char xmagic[4]; /*@r{ 508 "tar" }*/
+@};
+
+struct star_ext_header
+@{
+ struct sparse sp[SPARSES_IN_STAR_EXT_HEADER];
+ char isextended;
+@};
+
diff --git a/doc/intern.texi b/doc/intern.texi
new file mode 100644
index 0000000..e5a8bd1
--- /dev/null
+++ b/doc/intern.texi
@@ -0,0 +1,332 @@
+@c This is part of the paxutils manual.
+@c Copyright (C) 2006, 2014, 2016 Free Software Foundation, Inc.
+@c This file is distributed under GFDL 1.1 or any later version
+@c published by the Free Software Foundation.
+
+@menu
+* Standard:: Basic Tar Format
+* Extensions:: @acronym{GNU} Extensions to the Archive Format
+* Sparse Formats:: Storing Sparse Files
+* Snapshot Files::
+* Dumpdir::
+@end menu
+
+@node Standard
+@unnumberedsec Basic Tar Format
+@UNREVISED
+
+While an archive may contain many files, the archive itself is a
+single ordinary file. Like any other file, an archive file can be
+written to a storage device such as a tape or disk, sent through a
+pipe or over a network, saved on the active file system, or even
+stored in another archive. An archive file is not easy to read or
+manipulate without using the @command{tar} utility or Tar mode in
+@acronym{GNU} Emacs.
+
+Physically, an archive consists of a series of file entries terminated
+by an end-of-archive entry, which consists of two 512 blocks of zero
+bytes. A file
+entry usually describes one of the files in the archive (an
+@dfn{archive member}), and consists of a file header and the contents
+of the file. File headers contain file names and statistics, checksum
+information which @command{tar} uses to detect file corruption, and
+information about file types.
+
+Archives are permitted to have more than one member with the same
+member name. One way this situation can occur is if more than one
+version of a file has been stored in the archive. For information
+about adding new versions of a file to an archive, see @ref{update}.
+
+In addition to entries describing archive members, an archive may
+contain entries which @command{tar} itself uses to store information.
+@xref{label}, for an example of such an archive entry.
+
+A @command{tar} archive file contains a series of blocks. Each block
+contains @code{BLOCKSIZE} bytes. 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 block which describes
+the file, followed by zero or more blocks which give the contents
+of the file. At the end of the archive file there are two 512-byte blocks
+filled with binary zeros as an end-of-file marker. A reasonable system
+should write such end-of-file marker at the end of an archive, but
+must not assume that such a block exists when reading an archive. In
+particular @GNUTAR{} always issues a warning if it does not encounter it.
+
+The blocks may be @dfn{blocked} for physical I/O operations.
+Each record of @var{n} blocks (where @var{n} is set by the
+@option{--blocking-factor=@var{512-size}} (@option{-b @var{512-size}}) option to @command{tar}) is written with a single
+@w{@samp{write ()}} operation. On magnetic tapes, the result of
+such a write is a single record. When writing an archive,
+the last record of blocks should be written at the full size, with
+blocks after the zero block containing all zeros. When reading
+an archive, a reasonable system should properly handle an archive
+whose last record is shorter than the rest, or which contains garbage
+records after a zero block.
+
+The header block is defined in C as follows. In the @GNUTAR{}
+distribution, this is part of file @file{src/tar.h}:
+
+@smallexample
+@include header.texi
+@end smallexample
+
+All characters in header blocks are represented by 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 block
+of each file) are not translated in any way and are not constrained
+to represent characters in any character set. The @command{tar} format
+does not distinguish text files from binary files, and no translation
+of file contents is performed.
+
+The @code{name}, @code{linkname}, @code{magic}, @code{uname}, and
+@code{gname} are null-terminated character strings. All other fields
+are zero-filled octal numbers in ASCII. Each numeric field of width
+@var{w} contains @var{w} minus 1 digits, and a null.
+
+The @code{name} field is the file name of the file, with directory names
+(if any) preceding the file name, separated by slashes.
+
+@FIXME{how big a name before field overflows?}
+
+The @code{mode} field provides nine bits specifying file permissions
+and three bits to specify the Set @acronym{UID}, Set @acronym{GID}, and Save Text
+(@dfn{sticky}) 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 or updating an archive; e.g., the
+group permission could be copied from the @emph{other} permission.
+
+The @code{uid} and @code{gid} fields are the numeric user and group
+@acronym{ID} of the file owners, respectively. If the operating system does
+not support numeric user or group @acronym{ID}s, these fields should
+be ignored.
+
+The @code{size} field is the size of the file in bytes; linked files
+are archived with this field specified as zero.
+
+The @code{mtime} field is the data 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's contents were modified, represented
+as an integer number of
+seconds since January 1, 1970, 00:00 Coordinated Universal Time.
+
+The @code{chksum} field is the ASCII representation of the octal value
+of the simple sum of all bytes in the header block. Each 8-bit
+byte in the header is added to an unsigned integer, initialized to
+zero, the precision of which shall be no less than seventeen bits.
+When calculating the checksum, the @code{chksum} field is treated as
+if it were all blanks.
+
+The @code{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, @command{tar} issues a warning to the standard error.
+
+The @code{atime} and @code{ctime} fields are used in making incremental
+backups; they store, respectively, the particular file's access and
+status change times.
+
+The @code{offset} is used by the @option{--multi-volume} (@option{-M}) option, when
+making a multi-volume archive. The offset is number of bytes into
+the file that we need to restart at to continue the file on the next
+tape, i.e., where we store the location that a continued file is
+continued at.
+
+The following fields were added to deal with sparse files. A file
+is @dfn{sparse} if it takes in unallocated blocks which end up being
+represented as zeros, i.e., no useful data. A test to see if a file
+is sparse is to look at the number blocks allocated for it versus the
+number of characters in the file; if there are fewer blocks allocated
+for the file than would normally be allocated for a file of that
+size, then the file is sparse. This is the method @command{tar} uses to
+detect a sparse file, and once such a file is detected, it is treated
+differently from non-sparse files.
+
+Sparse files are often @code{dbm} files, or other database-type files
+which have data at some points and emptiness in the greater part of
+the file. Such files can appear to be very large when an @samp{ls
+-l} is done on them, when in truth, there may be a very small amount
+of important data contained in the file. It is thus undesirable
+to have @command{tar} think that it must back up this entire file, as
+great quantities of room are wasted on empty blocks, which can lead
+to running out of room on a tape far earlier than is necessary.
+Thus, sparse files are dealt with so that these empty blocks are
+not written to the tape. Instead, what is written to the tape is a
+description, of sorts, of the sparse file: where the holes are, how
+big the holes are, and how much data is found at the end of the hole.
+This way, the file takes up potentially far less room on the tape,
+and when the file is extracted later on, it will look exactly the way
+it looked beforehand. The following is a description of the fields
+used to handle a sparse file:
+
+The @code{sp} is an array of @code{struct sparse}. Each @code{struct
+sparse} contains two 12-character strings which represent an offset
+into the file and a number of bytes to be written at that offset.
+The offset is absolute, and not relative to the offset in preceding
+array element.
+
+The header can hold four of these @code{struct sparse} at the moment;
+if more are needed, they are not stored in the header.
+
+The @code{isextended} flag is set when an @code{extended_header}
+is needed to deal with a file. Note that this means that this flag
+can only be set when dealing with a sparse file, and it is only set
+in the event that the description of the file will not fit in the
+allotted room for sparse structures in the header. In other words,
+an extended_header is needed.
+
+The @code{extended_header} structure is used for sparse files which
+need more sparse structures than can fit in the header. The header can
+fit 4 such structures; if more are needed, the flag @code{isextended}
+gets set and the next block is an @code{extended_header}.
+
+Each @code{extended_header} structure contains an array of 21
+sparse structures, along with a similar @code{isextended} flag
+that the header had. There can be an indeterminate number of such
+@code{extended_header}s to describe a sparse file.
+
+@table @asis
+
+@item @code{REGTYPE}
+@itemx @code{AREGTYPE}
+These flags represent a regular file. In order to be compatible
+with older versions of @command{tar}, a @code{typeflag} value of
+@code{AREGTYPE} should be silently recognized as a regular file.
+New archives should be created using @code{REGTYPE}. Also, for
+backward compatibility, @command{tar} treats a regular file whose name
+ends with a slash as a directory.
+
+@item @code{LNKTYPE}
+This flag 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 @code{linkname} field with a trailing null.
+
+@item @code{SYMTYPE}
+This represents a symbolic link to another file. The linked-to name
+is specified in the @code{linkname} field with a trailing null.
+
+@item @code{CHRTYPE}
+@itemx @code{BLKTYPE}
+These represent character special files and block special files
+respectively. In this case the @code{devmajor} and @code{devminor}
+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.
+
+@item @code{DIRTYPE}
+This flag specifies a directory or sub-directory. The directory
+name in the @code{name} field should end with a slash. On systems where
+disk allocation is performed on a directory basis, the @code{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 @code{size} field of zero indicates no such limiting. Systems
+which do not support limiting in this manner should ignore the
+@code{size} field.
+
+@item @code{FIFOTYPE}
+This specifies a FIFO special file. Note that the archiving of a
+FIFO file archives the existence of this file and not its contents.
+
+@item @code{CONTTYPE}
+This 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 contiguous allocation should silently treat this
+type as a normal file.
+
+@item @code{A} @dots{} @code{Z}
+These are reserved for custom implementations. Some of these are
+used in the @acronym{GNU} modified format, as described below.
+
+@end table
+
+Other values are reserved for specification in future revisions of
+the P1003 standard, and should not be used by any @command{tar} program.
+
+The @code{magic} field indicates that this archive was output in
+the P1003 archive format. If this field contains @code{TMAGIC},
+the @code{uname} and @code{gname} fields will contain the ASCII
+representation of the owner and group of the file respectively.
+If found, the user and group @acronym{ID}s are used rather than the values in
+the @code{uid} and @code{gid} fields.
+
+For references, see ISO/IEC 9945-1:1990 or IEEE Std 1003.1-1990, pages
+169-173 (section 10.1) for @cite{Archive/Interchange File Format}; and
+IEEE Std 1003.2-1992, pages 380-388 (section 4.48) and pages 936-940
+(section E.4.48) for @cite{pax - Portable archive interchange}.
+
+@node Extensions
+@unnumberedsec @acronym{GNU} Extensions to the Archive Format
+@UNREVISED
+
+The @acronym{GNU} format uses additional file types to describe new types of
+files in an archive. These are listed below.
+
+@table @code
+@item GNUTYPE_DUMPDIR
+@itemx 'D'
+This represents a directory and a list of files created by the
+@option{--incremental} (@option{-G}) option. The @code{size} field gives the total
+size of the associated list of files. Each file name is preceded by
+either a @samp{Y} (the file should be in this archive) or an @samp{N}.
+(The file is a directory, or is not stored in the archive.) Each file
+name is terminated by a null. There is an additional null after the
+last file name.
+
+@item GNUTYPE_MULTIVOL
+@itemx 'M'
+This represents a file continued from another volume of a multi-volume
+archive created with the @option{--multi-volume} (@option{-M}) option. The original
+type of the file is not given here. The @code{size} field gives the
+maximum size of this piece of the file (assuming the volume does
+not end before the file is written out). The @code{offset} field
+gives the offset from the beginning of the file where this part of
+the file begins. Thus @code{size} plus @code{offset} should equal
+the original size of the file.
+
+@item GNUTYPE_SPARSE
+@itemx 'S'
+This flag indicates that we are dealing with a sparse file. Note
+that archiving a sparse file requires special operations to find
+holes in the file, which mark the positions of these holes, along
+with the number of bytes of data to be found after the hole.
+
+@item GNUTYPE_VOLHDR
+@itemx 'V'
+This file type is used to mark the volume header that was given with
+the @option{--label=@var{archive-label}} (@option{-V @var{archive-label}}) option when the archive was created. The @code{name}
+field contains the @code{name} given after the @option{--label=@var{archive-label}} (@option{-V @var{archive-label}}) option.
+The @code{size} field is zero. Only the first file in each volume
+of an archive should have this type.
+
+@end table
+
+You may have trouble reading a @acronym{GNU} format archive on a
+non-@acronym{GNU} system if the options @option{--incremental} (@option{-G}),
+@option{--multi-volume} (@option{-M}), @option{--sparse} (@option{-S}), or @option{--label=@var{archive-label}} (@option{-V @var{archive-label}}) were
+used when writing the archive. In general, if @command{tar} does not
+use the @acronym{GNU}-added fields of the header, other versions of
+@command{tar} should be able to read the archive. Otherwise, the
+@command{tar} program will give an error, the most likely one being a
+checksum error.
+
+@node Sparse Formats
+@unnumberedsec Storing Sparse Files
+@include sparse.texi
+
+@node Snapshot Files
+@unnumberedsec Format of the Incremental Snapshot Files
+@include snapshot.texi
+
+@node Dumpdir
+@unnumberedsec Dumpdir
+@include dumpdir.texi
diff --git a/doc/mastermenu.el b/doc/mastermenu.el
new file mode 100644
index 0000000..6f5ea87
--- /dev/null
+++ b/doc/mastermenu.el
@@ -0,0 +1,90 @@
+;;; mastermenu.el --- Redefinition of texinfo-master-menu-list
+
+;; Copyright 2006-2007, 2013-2014, 2016 Free Software Foundation, Inc.
+
+;; Author: Sergey Poznyakoff
+;; Maintainer: bug-tar@gnu.org
+;; Keywords: maint, tex, docs
+
+;; 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/>.
+
+;;; Commentary:
+
+;; This file redefines texinfo-master-menu-list so that it takes into
+;; account included files.
+
+;; Known bugs: @menu without previous sectioning command will inherit
+;; documentation string from the previous menu. However, since such a
+;; menu is illegal in a texinfo file, we can live with it.
+
+(require 'texinfo)
+(require 'texnfo-upd)
+
+(defun texinfo-master-menu-list-recursive (title)
+ "Auxiliary function used by `texinfo-master-menu-list'."
+ (save-excursion
+ (let (master-menu-list)
+ (while (re-search-forward "\\(^@menu\\|^@include\\)" nil t)
+ (cond
+ ((string= (match-string 0) "@include")
+ (skip-chars-forward " \t")
+ (let ((included-name (let ((start (point)))
+ (end-of-line)
+ (skip-chars-backward " \t")
+ (buffer-substring start (point)))))
+ (end-of-line)
+ (let ((prev-title (texinfo-copy-menu-title)))
+ (save-excursion
+ (set-buffer (find-file-noselect included-name))
+ (setq master-menu-list
+ (append (texinfo-master-menu-list-recursive prev-title)
+ master-menu-list))))))
+ (t
+ (setq master-menu-list
+ (cons (list
+ (texinfo-copy-menu)
+ (let ((menu-title (texinfo-copy-menu-title)))
+ (if (string= menu-title "")
+ title
+ menu-title)))
+ master-menu-list)))))
+ master-menu-list)))
+
+(defun texinfo-master-menu-list ()
+ "Return a list of menu entries and header lines for the master menu,
+recursing into included files.
+
+Start with the menu for chapters and indices and then find each
+following menu and the title of the node preceding that menu.
+
+The master menu list has this form:
+
+ \(\(\(... \"entry-1-2\" \"entry-1\"\) \"title-1\"\)
+ \(\(... \"entry-2-2\" \"entry-2-1\"\) \"title-2\"\)
+ ...\)
+
+However, there does not need to be a title field."
+
+ (reverse (texinfo-master-menu-list-recursive "")))
+
+(defun make-master-menu ()
+ "Create master menu in the first Emacs argument."
+ (find-file (car command-line-args-left))
+ (texinfo-master-menu nil)
+ (save-buffer))
+
+
+;;; mastermenu.el ends here
diff --git a/doc/parse-datetime.texi b/doc/parse-datetime.texi
new file mode 100644
index 0000000..34e9ede
--- /dev/null
+++ b/doc/parse-datetime.texi
@@ -0,0 +1,594 @@
+@c GNU date syntax documentation
+
+@c Copyright (C) 1994-2006, 2009-2015 Free Software Foundation, Inc.
+
+@c Permission is granted to copy, distribute and/or modify this document
+@c under the terms of the GNU Free Documentation License, Version 1.3 or
+@c any later version published by the Free Software Foundation; with no
+@c Invariant Sections, no Front-Cover Texts, and no Back-Cover
+@c Texts. A copy of the license is included in the ``GNU Free
+@c Documentation License'' file as part of this distribution.
+
+@node Date input formats
+@chapter Date input formats
+
+@cindex date input formats
+@findex parse_datetime
+
+First, a quote:
+
+@quotation
+Our units of temporal measurement, from seconds on up to months, are so
+complicated, asymmetrical and disjunctive so as to make coherent mental
+reckoning in time all but impossible. Indeed, had some tyrannical god
+contrived to enslave our minds to time, to make it all but impossible
+for us to escape subjection to sodden routines and unpleasant surprises,
+he could hardly have done better than handing down our present system.
+It is like a set of trapezoidal building blocks, with no vertical or
+horizontal surfaces, like a language in which the simplest thought
+demands ornate constructions, useless particles and lengthy
+circumlocutions. Unlike the more successful patterns of language and
+science, which enable us to face experience boldly or at least
+level-headedly, our system of temporal calculation silently and
+persistently encourages our terror of time.
+
+@dots{} It is as though architects had to measure length in feet, width
+in meters and height in ells; as though basic instruction manuals
+demanded a knowledge of five different languages. It is no wonder then
+that we often look into our own immediate past or future, last Tuesday
+or a week from Sunday, with feelings of helpless confusion. @dots{}
+
+---Robert Grudin, @cite{Time and the Art of Living}.
+@end quotation
+
+This section describes the textual date representations that GNU
+programs accept. These are the strings you, as a user, can supply as
+arguments to the various programs. The C interface (via the
+@code{parse_datetime} function) is not described here.
+
+@menu
+* General date syntax:: Common rules.
+* Calendar date items:: 19 Dec 1994.
+* Time of day items:: 9:20pm.
+* Time zone items:: EST, PDT, UTC, @dots{}
+* Combined date and time of day items:: 1972-09-24T20:02:00,000000-0500.
+* Day of week items:: Monday and others.
+* Relative items in date strings:: next tuesday, 2 years ago.
+* Pure numbers in date strings:: 19931219, 1440.
+* Seconds since the Epoch:: @@1078100502.
+* Specifying time zone rules:: TZ="America/New_York", TZ="UTC0".
+* Authors of parse_datetime:: Bellovin, Eggert, Salz, Berets, et al.
+@end menu
+
+
+@node General date syntax
+@section General date syntax
+
+@cindex general date syntax
+
+@cindex items in date strings
+A @dfn{date} is a string, possibly empty, containing many items
+separated by whitespace. The whitespace may be omitted when no
+ambiguity arises. The empty string means the beginning of today (i.e.,
+midnight). Order of the items is immaterial. A date string may contain
+many flavors of items:
+
+@itemize @bullet
+@item calendar date items
+@item time of day items
+@item time zone items
+@item combined date and time of day items
+@item day of the week items
+@item relative items
+@item pure numbers.
+@end itemize
+
+@noindent We describe each of these item types in turn, below.
+
+@cindex numbers, written-out
+@cindex ordinal numbers
+@findex first @r{in date strings}
+@findex next @r{in date strings}
+@findex last @r{in date strings}
+A few ordinal numbers may be written out in words in some contexts. This is
+most useful for specifying day of the week items or relative items (see
+below). Among the most commonly used ordinal numbers, the word
+@samp{last} stands for @math{-1}, @samp{this} stands for 0, and
+@samp{first} and @samp{next} both stand for 1. Because the word
+@samp{second} stands for the unit of time there is no way to write the
+ordinal number 2, but for convenience @samp{third} stands for 3,
+@samp{fourth} for 4, @samp{fifth} for 5,
+@samp{sixth} for 6, @samp{seventh} for 7, @samp{eighth} for 8,
+@samp{ninth} for 9, @samp{tenth} for 10, @samp{eleventh} for 11 and
+@samp{twelfth} for 12.
+
+@cindex months, written-out
+When a month is written this way, it is still considered to be written
+numerically, instead of being ``spelled in full''; this changes the
+allowed strings.
+
+@cindex language, in dates
+In the current implementation, only English is supported for words and
+abbreviations like @samp{AM}, @samp{DST}, @samp{EST}, @samp{first},
+@samp{January}, @samp{Sunday}, @samp{tomorrow}, and @samp{year}.
+
+@cindex language, in dates
+@cindex time zone item
+The output of the @command{date} command
+is not always acceptable as a date string,
+not only because of the language problem, but also because there is no
+standard meaning for time zone items like @samp{IST}@. When using
+@command{date} to generate a date string intended to be parsed later,
+specify a date format that is independent of language and that does not
+use time zone items other than @samp{UTC} and @samp{Z}@. Here are some
+ways to do this:
+
+@example
+$ LC_ALL=C TZ=UTC0 date
+Mon Mar 1 00:21:42 UTC 2004
+$ TZ=UTC0 date +'%Y-%m-%d %H:%M:%SZ'
+2004-03-01 00:21:42Z
+$ date --rfc-3339=ns # --rfc-3339 is a GNU extension.
+2004-02-29 16:21:42.692722128-08:00
+$ date --rfc-2822 # a GNU extension
+Sun, 29 Feb 2004 16:21:42 -0800
+$ date +'%Y-%m-%d %H:%M:%S %z' # %z is a GNU extension.
+2004-02-29 16:21:42 -0800
+$ date +'@@%s.%N' # %s and %N are GNU extensions.
+@@1078100502.692722128
+@end example
+
+@cindex case, ignored in dates
+@cindex comments, in dates
+Alphabetic case is completely ignored in dates. Comments may be introduced
+between round parentheses, as long as included parentheses are properly
+nested. Hyphens not followed by a digit are currently ignored. Leading
+zeros on numbers are ignored.
+
+@cindex leap seconds
+Invalid dates like @samp{2005-02-29} or times like @samp{24:00} are
+rejected. In the typical case of a host that does not support leap
+seconds, a time like @samp{23:59:60} is rejected even if it
+corresponds to a valid leap second.
+
+
+@node Calendar date items
+@section Calendar date items
+
+@cindex calendar date item
+
+A @dfn{calendar date item} specifies a day of the year. It is
+specified differently, depending on whether the month is specified
+numerically or literally. All these strings specify the same calendar date:
+
+@example
+1972-09-24 # ISO 8601.
+72-9-24 # Assume 19xx for 69 through 99,
+ # 20xx for 00 through 68.
+72-09-24 # Leading zeros are ignored.
+9/24/72 # Common U.S. writing.
+24 September 1972
+24 Sept 72 # September has a special abbreviation.
+24 Sep 72 # Three-letter abbreviations always allowed.
+Sep 24, 1972
+24-sep-72
+24sep72
+@end example
+
+The year can also be omitted. In this case, the last specified year is
+used, or the current year if none. For example:
+
+@example
+9/24
+sep 24
+@end example
+
+Here are the rules.
+
+@cindex ISO 8601 date format
+@cindex date format, ISO 8601
+For numeric months, the ISO 8601 format
+@samp{@var{year}-@var{month}-@var{day}} is allowed, where @var{year} is
+any positive number, @var{month} is a number between 01 and 12, and
+@var{day} is a number between 01 and 31. A leading zero must be present
+if a number is less than ten. If @var{year} is 68 or smaller, then 2000
+is added to it; otherwise, if @var{year} is less than 100,
+then 1900 is added to it. The construct
+@samp{@var{month}/@var{day}/@var{year}}, popular in the United States,
+is accepted. Also @samp{@var{month}/@var{day}}, omitting the year.
+
+@cindex month names in date strings
+@cindex abbreviations for months
+Literal months may be spelled out in full: @samp{January},
+@samp{February}, @samp{March}, @samp{April}, @samp{May}, @samp{June},
+@samp{July}, @samp{August}, @samp{September}, @samp{October},
+@samp{November} or @samp{December}. Literal months may be abbreviated
+to their first three letters, possibly followed by an abbreviating dot.
+It is also permitted to write @samp{Sept} instead of @samp{September}.
+
+When months are written literally, the calendar date may be given as any
+of the following:
+
+@example
+@var{day} @var{month} @var{year}
+@var{day} @var{month}
+@var{month} @var{day} @var{year}
+@var{day}-@var{month}-@var{year}
+@end example
+
+Or, omitting the year:
+
+@example
+@var{month} @var{day}
+@end example
+
+
+@node Time of day items
+@section Time of day items
+
+@cindex time of day item
+
+A @dfn{time of day item} in date strings specifies the time on a given
+day. Here are some examples, all of which represent the same time:
+
+@example
+20:02:00.000000
+20:02
+8:02pm
+20:02-0500 # In EST (U.S. Eastern Standard Time).
+@end example
+
+@cindex leap seconds
+More generally, the time of day may be given as
+@samp{@var{hour}:@var{minute}:@var{second}}, where @var{hour} is
+a number between 0 and 23, @var{minute} is a number between 0 and
+59, and @var{second} is a number between 0 and 59 possibly followed by
+@samp{.} or @samp{,} and a fraction containing one or more digits.
+Alternatively,
+@samp{:@var{second}} can be omitted, in which case it is taken to
+be zero. On the rare hosts that support leap seconds, @var{second}
+may be 60.
+
+@findex am @r{in date strings}
+@findex pm @r{in date strings}
+@findex midnight @r{in date strings}
+@findex noon @r{in date strings}
+If the time is followed by @samp{am} or @samp{pm} (or @samp{a.m.}
+or @samp{p.m.}), @var{hour} is restricted to run from 1 to 12, and
+@samp{:@var{minute}} may be omitted (taken to be zero). @samp{am}
+indicates the first half of the day, @samp{pm} indicates the second
+half of the day. In this notation, 12 is the predecessor of 1:
+midnight is @samp{12am} while noon is @samp{12pm}.
+(This is the zero-oriented interpretation of @samp{12am} and @samp{12pm},
+as opposed to the old tradition derived from Latin
+which uses @samp{12m} for noon and @samp{12pm} for midnight.)
+
+@cindex time zone correction
+@cindex minutes, time zone correction by
+The time may alternatively be followed by a time zone correction,
+expressed as @samp{@var{s}@var{hh}@var{mm}}, where @var{s} is @samp{+}
+or @samp{-}, @var{hh} is a number of zone hours and @var{mm} is a number
+of zone minutes.
+The zone minutes term, @var{mm}, may be omitted, in which case
+the one- or two-digit correction is interpreted as a number of hours.
+You can also separate @var{hh} from @var{mm} with a colon.
+When a time zone correction is given this way, it
+forces interpretation of the time relative to
+Coordinated Universal Time (UTC), overriding any previous
+specification for the time zone or the local time zone. For example,
+@samp{+0530} and @samp{+05:30} both stand for the time zone 5.5 hours
+ahead of UTC (e.g., India).
+This is the best way to
+specify a time zone correction by fractional parts of an hour.
+The maximum zone correction is 24 hours.
+
+Either @samp{am}/@samp{pm} or a time zone correction may be specified,
+but not both.
+
+
+@node Time zone items
+@section Time zone items
+
+@cindex time zone item
+
+A @dfn{time zone item} specifies an international time zone, indicated
+by a small set of letters, e.g., @samp{UTC} or @samp{Z}
+for Coordinated Universal
+Time. Any included periods are ignored. By following a
+non-daylight-saving time zone by the string @samp{DST} in a separate
+word (that is, separated by some white space), the corresponding
+daylight saving time zone may be specified.
+Alternatively, a non-daylight-saving time zone can be followed by a
+time zone correction, to add the two values. This is normally done
+only for @samp{UTC}; for example, @samp{UTC+05:30} is equivalent to
+@samp{+05:30}.
+
+Time zone items other than @samp{UTC} and @samp{Z}
+are obsolescent and are not recommended, because they
+are ambiguous; for example, @samp{EST} has a different meaning in
+Australia than in the United States. Instead, it's better to use
+unambiguous numeric time zone corrections like @samp{-0500}, as
+described in the previous section.
+
+If neither a time zone item nor a time zone correction is supplied,
+time stamps are interpreted using the rules of the default time zone
+(@pxref{Specifying time zone rules}).
+
+
+@node Combined date and time of day items
+@section Combined date and time of day items
+
+@cindex combined date and time of day item
+@cindex ISO 8601 date and time of day format
+@cindex date and time of day format, ISO 8601
+
+The ISO 8601 date and time of day extended format consists of an ISO
+8601 date, a @samp{T} character separator, and an ISO 8601 time of
+day. This format is also recognized if the @samp{T} is replaced by a
+space.
+
+In this format, the time of day should use 24-hour notation.
+Fractional seconds are allowed, with either comma or period preceding
+the fraction. ISO 8601 fractional minutes and hours are not
+supported. Typically, hosts support nanosecond timestamp resolution;
+excess precision is silently discarded.
+
+Here are some examples:
+
+@example
+2012-09-24T20:02:00.052-0500
+2012-12-31T23:59:59,999999999+1100
+1970-01-01 00:00Z
+@end example
+
+@node Day of week items
+@section Day of week items
+
+@cindex day of week item
+
+The explicit mention of a day of the week will forward the date
+(only if necessary) to reach that day of the week in the future.
+
+Days of the week may be spelled out in full: @samp{Sunday},
+@samp{Monday}, @samp{Tuesday}, @samp{Wednesday}, @samp{Thursday},
+@samp{Friday} or @samp{Saturday}. Days may be abbreviated to their
+first three letters, optionally followed by a period. The special
+abbreviations @samp{Tues} for @samp{Tuesday}, @samp{Wednes} for
+@samp{Wednesday} and @samp{Thur} or @samp{Thurs} for @samp{Thursday} are
+also allowed.
+
+@findex next @var{day}
+@findex last @var{day}
+A number may precede a day of the week item to move forward
+supplementary weeks. It is best used in expression like @samp{third
+monday}. In this context, @samp{last @var{day}} or @samp{next
+@var{day}} is also acceptable; they move one week before or after
+the day that @var{day} by itself would represent.
+
+A comma following a day of the week item is ignored.
+
+
+@node Relative items in date strings
+@section Relative items in date strings
+
+@cindex relative items in date strings
+@cindex displacement of dates
+
+@dfn{Relative items} adjust a date (or the current date if none) forward
+or backward. The effects of relative items accumulate. Here are some
+examples:
+
+@example
+1 year
+1 year ago
+3 years
+2 days
+@end example
+
+@findex year @r{in date strings}
+@findex month @r{in date strings}
+@findex fortnight @r{in date strings}
+@findex week @r{in date strings}
+@findex day @r{in date strings}
+@findex hour @r{in date strings}
+@findex minute @r{in date strings}
+The unit of time displacement may be selected by the string @samp{year}
+or @samp{month} for moving by whole years or months. These are fuzzy
+units, as years and months are not all of equal duration. More precise
+units are @samp{fortnight} which is worth 14 days, @samp{week} worth 7
+days, @samp{day} worth 24 hours, @samp{hour} worth 60 minutes,
+@samp{minute} or @samp{min} worth 60 seconds, and @samp{second} or
+@samp{sec} worth one second. An @samp{s} suffix on these units is
+accepted and ignored.
+
+@findex ago @r{in date strings}
+The unit of time may be preceded by a multiplier, given as an optionally
+signed number. Unsigned numbers are taken as positively signed. No
+number at all implies 1 for a multiplier. Following a relative item by
+the string @samp{ago} is equivalent to preceding the unit by a
+multiplier with value @math{-1}.
+
+@findex day @r{in date strings}
+@findex tomorrow @r{in date strings}
+@findex yesterday @r{in date strings}
+The string @samp{tomorrow} is worth one day in the future (equivalent
+to @samp{day}), the string @samp{yesterday} is worth
+one day in the past (equivalent to @samp{day ago}).
+
+@findex now @r{in date strings}
+@findex today @r{in date strings}
+@findex this @r{in date strings}
+The strings @samp{now} or @samp{today} are relative items corresponding
+to zero-valued time displacement, these strings come from the fact
+a zero-valued time displacement represents the current time when not
+otherwise changed by previous items. They may be used to stress other
+items, like in @samp{12:00 today}. The string @samp{this} also has
+the meaning of a zero-valued time displacement, but is preferred in
+date strings like @samp{this thursday}.
+
+When a relative item causes the resulting date to cross a boundary
+where the clocks were adjusted, typically for daylight saving time,
+the resulting date and time are adjusted accordingly.
+
+The fuzz in units can cause problems with relative items. For
+example, @samp{2003-07-31 -1 month} might evaluate to 2003-07-01,
+because 2003-06-31 is an invalid date. To determine the previous
+month more reliably, you can ask for the month before the 15th of the
+current month. For example:
+
+@example
+$ date -R
+Thu, 31 Jul 2003 13:02:39 -0700
+$ date --date='-1 month' +'Last month was %B?'
+Last month was July?
+$ date --date="$(date +%Y-%m-15) -1 month" +'Last month was %B!'
+Last month was June!
+@end example
+
+Also, take care when manipulating dates around clock changes such as
+daylight saving leaps. In a few cases these have added or subtracted
+as much as 24 hours from the clock, so it is often wise to adopt
+universal time by setting the @env{TZ} environment variable to
+@samp{UTC0} before embarking on calendrical calculations.
+
+@node Pure numbers in date strings
+@section Pure numbers in date strings
+
+@cindex pure numbers in date strings
+
+The precise interpretation of a pure decimal number depends
+on the context in the date string.
+
+If the decimal number is of the form @var{yyyy}@var{mm}@var{dd} and no
+other calendar date item (@pxref{Calendar date items}) appears before it
+in the date string, then @var{yyyy} is read as the year, @var{mm} as the
+month number and @var{dd} as the day of the month, for the specified
+calendar date.
+
+If the decimal number is of the form @var{hh}@var{mm} and no other time
+of day item appears before it in the date string, then @var{hh} is read
+as the hour of the day and @var{mm} as the minute of the hour, for the
+specified time of day. @var{mm} can also be omitted.
+
+If both a calendar date and a time of day appear to the left of a number
+in the date string, but no relative item, then the number overrides the
+year.
+
+
+@node Seconds since the Epoch
+@section Seconds since the Epoch
+
+If you precede a number with @samp{@@}, it represents an internal time
+stamp as a count of seconds. The number can contain an internal
+decimal point (either @samp{.} or @samp{,}); any excess precision not
+supported by the internal representation is truncated toward minus
+infinity. Such a number cannot be combined with any other date
+item, as it specifies a complete time stamp.
+
+@cindex beginning of time, for POSIX
+@cindex epoch, for POSIX
+Internally, computer times are represented as a count of seconds since
+an epoch---a well-defined point of time. On GNU and
+POSIX systems, the epoch is 1970-01-01 00:00:00 UTC, so
+@samp{@@0} represents this time, @samp{@@1} represents 1970-01-01
+00:00:01 UTC, and so forth. GNU and most other
+POSIX-compliant systems support such times as an extension
+to POSIX, using negative counts, so that @samp{@@-1}
+represents 1969-12-31 23:59:59 UTC.
+
+Traditional Unix systems count seconds with 32-bit two's-complement
+integers and can represent times from 1901-12-13 20:45:52 through
+2038-01-19 03:14:07 UTC@. More modern systems use 64-bit counts
+of seconds with nanosecond subcounts, and can represent all the times
+in the known lifetime of the universe to a resolution of 1 nanosecond.
+
+@cindex leap seconds
+On most hosts, these counts ignore the presence of leap seconds.
+For example, on most hosts @samp{@@915148799} represents 1998-12-31
+23:59:59 UTC, @samp{@@915148800} represents 1999-01-01 00:00:00
+UTC, and there is no way to represent the intervening leap second
+1998-12-31 23:59:60 UTC.
+
+@node Specifying time zone rules
+@section Specifying time zone rules
+
+@vindex TZ
+Normally, dates are interpreted using the rules of the current time
+zone, which in turn are specified by the @env{TZ} environment
+variable, or by a system default if @env{TZ} is not set. To specify a
+different set of default time zone rules that apply just to one date,
+start the date with a string of the form @samp{TZ="@var{rule}"}. The
+two quote characters (@samp{"}) must be present in the date, and any
+quotes or backslashes within @var{rule} must be escaped by a
+backslash.
+
+For example, with the GNU @command{date} command you can
+answer the question ``What time is it in New York when a Paris clock
+shows 6:30am on October 31, 2004?'' by using a date beginning with
+@samp{TZ="Europe/Paris"} as shown in the following shell transcript:
+
+@example
+$ export TZ="America/New_York"
+$ date --date='TZ="Europe/Paris" 2004-10-31 06:30'
+Sun Oct 31 01:30:00 EDT 2004
+@end example
+
+In this example, the @option{--date} operand begins with its own
+@env{TZ} setting, so the rest of that operand is processed according
+to @samp{Europe/Paris} rules, treating the string @samp{2004-10-31
+06:30} as if it were in Paris. However, since the output of the
+@command{date} command is processed according to the overall time zone
+rules, it uses New York time. (Paris was normally six hours ahead of
+New York in 2004, but this example refers to a brief Halloween period
+when the gap was five hours.)
+
+A @env{TZ} value is a rule that typically names a location in the
+@uref{http://www.twinsun.com/tz/tz-link.htm, @samp{tz} database}.
+A recent catalog of location names appears in the
+@uref{http://twiki.org/cgi-bin/xtra/tzdate, TWiki Date and Time
+Gateway}. A few non-GNU hosts require a colon before a
+location name in a @env{TZ} setting, e.g.,
+@samp{TZ=":America/New_York"}.
+
+The @samp{tz} database includes a wide variety of locations ranging
+from @samp{Arctic/Longyearbyen} to @samp{Antarctica/South_Pole}, but
+if you are at sea and have your own private time zone, or if you are
+using a non-GNU host that does not support the @samp{tz}
+database, you may need to use a POSIX rule instead. Simple
+POSIX rules like @samp{UTC0} specify a time zone without
+daylight saving time; other rules can specify simple daylight saving
+regimes. @xref{TZ Variable,, Specifying the Time Zone with @code{TZ},
+libc, The GNU C Library}.
+
+@node Authors of parse_datetime
+@section Authors of @code{parse_datetime}
+@c the anchor keeps the old node name, to try to avoid breaking links
+@anchor{Authors of get_date}
+
+@cindex authors of @code{parse_datetime}
+
+@cindex Bellovin, Steven M.
+@cindex Salz, Rich
+@cindex Berets, Jim
+@cindex MacKenzie, David
+@cindex Meyering, Jim
+@cindex Eggert, Paul
+@code{parse_datetime} started life as @code{getdate}, as originally
+implemented by Steven M. Bellovin
+(@email{smb@@research.att.com}) while at the University of North Carolina
+at Chapel Hill. The code was later tweaked by a couple of people on
+Usenet, then completely overhauled by Rich $alz (@email{rsalz@@bbn.com})
+and Jim Berets (@email{jberets@@bbn.com}) in August, 1990. Various
+revisions for the GNU system were made by David MacKenzie, Jim Meyering,
+Paul Eggert and others, including renaming it to @code{get_date} to
+avoid a conflict with the alternative Posix function @code{getdate},
+and a later rename to @code{parse_datetime}. The Posix function
+@code{getdate} can parse more locale-specific dates using
+@code{strptime}, but relies on an environment variable and external
+file, and lacks the thread-safety of @code{parse_datetime}.
+
+@cindex Pinard, F.
+@cindex Berry, K.
+This chapter was originally produced by Fran@,{c}ois Pinard
+(@email{pinard@@iro.umontreal.ca}) from the @file{parse_datetime.y} source code,
+and then edited by K. Berry (@email{kb@@cs.umb.edu}).
diff --git a/doc/rendition.texi b/doc/rendition.texi
new file mode 100644
index 0000000..453c4e8
--- /dev/null
+++ b/doc/rendition.texi
@@ -0,0 +1,99 @@
+@c This is part of GNU tar manual.
+@c Copyright 1992, 1994-1997, 1999-2004, 2006, 2013-2014, 2016 Free
+@c Software Foundation, Inc.
+@c See file tar.texi for copying conditions.
+
+@c This file contains support for 'renditions' by Fran@,{c}ois Pinard
+@c I extended it by adding a FIXME_FOOTNOTE variable, which controls
+@c whether FIXME information should be placed in footnotes or
+@c inlined. --gray
+
+@c ======================================================================
+@c This document has three levels of rendition: PUBLISH, DISTRIB or PROOF,
+@c as decided by @set symbols. The PUBLISH rendition does not show
+@c notes or marks asking for revision. Most users will prefer having more
+@c information, even if this information is not fully revised for adequacy,
+@c so DISTRIB is the default for distributions. The PROOF rendition
+@c show all marks to the point of ugliness, but is nevertheless useful to
+@c those working on the manual itself.
+@c ======================================================================
+
+@c Set this symbol if you wish FIXMEs to appear in footnotes, instead
+@c of being inserted into the text.
+@c @set PROOF_FOOTNOTED
+
+@ifclear PUBLISH
+@ifclear DISTRIB
+@ifclear PROOF
+@set DISTRIB
+@end ifclear
+@end ifclear
+@end ifclear
+
+@ifset PUBLISH
+@set RENDITION The book, version
+@end ifset
+
+@ifset DISTRIB
+@set RENDITION FTP release, version
+@end ifset
+
+@ifset PROOF
+@set RENDITION Proof reading version
+@end ifset
+
+@c Output marks for nodes needing revision, but not in PUBLISH rendition.
+
+@macro UNREVISED
+@ifclear PUBLISH
+@quotation
+@emph{(This message will disappear, once this node revised.)}
+@end quotation
+@end ifclear
+@end macro
+
+@c Output various FIXME information only in PROOF rendition.
+
+@macro FIXME{string}
+@ifset PROOF
+@ifset PROOF_FOOTNOTED
+@footnote{@strong{FIXME:} \string\}
+@end ifset
+@ifclear PROOF_FOOTNOTED
+@cartouche
+@strong{<FIXME>} \string\ @strong{</>}
+@end cartouche
+@end ifclear
+@end ifset
+
+@end macro
+
+@macro FIXME-ref{string}
+@ifset PROOF
+@strong{<REF>} \string\ @strong{</>}
+@end ifset
+@ifclear PROOF
+@cite{\string\}
+@end ifclear
+@end macro
+
+@macro FIXME-pxref{string}
+@ifset PROOF
+See @strong{<PXREF>} \string\ @strong{</>}
+@end ifset
+@ifclear PROOF
+See @cite{\string\}
+@end ifclear
+
+@end macro
+
+@macro FIXME-xref{string}
+@ifset PROOF
+See @strong{<XREF>} \string\ @strong{</>}
+@end ifset
+@ifclear PROOF
+See @cite{\string\}
+@end ifclear
+@end macro
+
+@c End of rendition.texi
diff --git a/doc/rmt.8 b/doc/rmt.8
new file mode 100644
index 0000000..7550277
--- /dev/null
+++ b/doc/rmt.8
@@ -0,0 +1,254 @@
+.\" This file is part of GNU tar. -*- nroff -*-
+.\" Copyright 2013 Free Software Foundation, Inc.
+.\"
+.\" 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/>.
+.TH RMT 1 "January 27, 2014" "RMT" "GNU TAR Manual"
+.SH NAME
+rmt \- remote magnetic tape server
+.SH SYNOPSIS
+.B rmt
+.SH DESCRIPTION
+.B Rmt
+provides remote access to files and devices for
+.BR tar (1),
+.BR cpio (1),
+and similar backup utilities. It is normally called by running
+.BR rsh (1)
+or
+.BR ssh (1)
+to the remote machine, optionally using a different
+login name if one is supplied.
+.PP
+The calling program communicates with
+.B rmt
+by sending requests on its standard input and reading replies from the
+standard output. A request consists of a request letter followed by
+an argument (if required) and a newline character. Additional data,
+if any, are sent after the newline. On success,
+.B rmt
+returns
+.PP
+.in +4
+.BI A number \en
+.PP
+where \fInumber\fR is an ASCII representation of a decimal return
+code. Additional data are returned after this line. On error, the
+following response is returned:
+.PP
+.in +4
+.BI E errno \en error-message \en
+.PP
+where \fIerrno\fR is one of the system error codes, as described in
+.BR errno (3),
+and \fIerror-message\fR is a one-line human-readable description of
+the error, as printed by
+.BR perror (3).
+.PP
+Available commands and possible responses are discussed in detail in
+the subsequent section.
+.SH COMMANDS
+.TP
+.BI O device \en flags \en
+Opens the \fIdevice\fR with given \fIflags\fR. If a
+device had already been opened, it is closed before opening the new one.
+.sp
+.B Arguments
+.RS
+.TP
+.I device
+The name of the device to open.
+.TP
+.I flags
+Flags for
+.BR open (2):
+a decimal number, or any valid \fBO_*\fR constant from
+.B fcntl.h
+(the initial \fBO_\fR may be omitted), or a bitwise or (using \fB|\fR)
+of any number of these, e.g.:
+.in +4
+.EX
+576
+64|512
+CREAT|TRUNC
+.EE
+.RS
+In addition, a combined form is also allowed, i.e. a decimal mode followed
+by its symbolic representation. In this case the symbolic representation
+is given preference.
+.RE
+.sp
+.B Reply
+.RS
+.B A0\en
+on success.
+.RE
+.sp
+.B Extensions
+.RS
+BSD version allows only decimal number as \fIflags\fR.
+.RE 1
+.TP
+\fBC\fR[\fIdevice\fR]\fB\en\fR
+Close the currently open device.
+.RS
+.TP
+.B Arguments
+.br
+Any arguments are silently ignored.
+.TP
+.B Reply
+.br
+.B A0\en
+on success.
+.RE
+.TP
+.BI L whence \en offset \en
+.RS
+Performs an
+.BR lseek (2)
+on the currently open device with the specified
+parameters.
+.TP
+.B Arguments
+.RS
+.TP
+.I whence
+Where to measure offset from. Valid values are:
+.sp
+.nf
+.ta 1n 20n
+ 0, SET, SEEK_SET seek from the file beginning
+ 1, CUR, SEEK_CUR seek from the current location
+ 2, END, SEEK_END seek from the file end
+.fi
+.RE
+.TP
+.B Reply
+.br
+.BI A offset \en
+on success. The \fIoffset\fR is the new offset in file.
+.TP
+.B Extensions
+BSD version allows only 0,1,2 as \fIwhence\fR.
+.RE
+.TP
+.BI R count \en
+.br
+Read \fIcount\fR bytes of data from the current device.
+.RS
+.TP
+.B Arguments
+.RS
+.TP
+.I count
+number of bytes to read.
+.RE
+.TP
+.B Reply
+.br
+On success:
+.sp
+.in +4
+.BI A rdcount \en
+.in
+.sp
+followed by \fIrdcount\fR bytes of data read from the device.
+.RE
+.TP
+.BI W count \en
+Writes data onto the current device. The command is followed by
+\fIcount\fR bytes of input data.
+.RS
+.TP
+.B Arguments
+.RS
+.TP
+.I count
+Number of bytes to write.
+.RE
+.TP
+.B Reply
+.br
+On success: \fBA\fIwrcount\fB\en\fR, where \fIwrcount\fR is the number of
+bytes actually written.
+.RE
+.TP
+.BI I opcode \en count \en
+Perform a
+.B MTIOCOP
+.BR ioctl (2)
+command with the specified paramedters.
+.RS
+.TP
+.B Arguments
+.RS
+.TP
+.I opcode
+.B MTIOCOP
+operation code.
+.TP
+.I count
+mt_count.
+.RE
+.TP
+.B Reply
+.br
+On success: \fBA0\en\fR.
+.RE
+.TP
+.B S\en
+Returns the status of the currently open device, as obtained from a
+.B MTIOCGET
+.BR ioctl (2)
+call.
+.RS
+.TP
+.B Arguments
+.br
+None
+.TP
+.B Reply
+.br
+On success: \fBA\fIcount\fB\en\fR followed by \fIcount\fR bytes of
+data.
+.RE
+.SH "SEE ALSO"
+.BR tar (1).
+.SH BUGS
+Using this utility as a general-purpose remote file access tool is
+discouraged.
+.SH "BUG REPORTS"
+Report bugs to <bug\-tar@gnu.org>.
+.SH HISTORY
+The
+.B rmt
+command appeared in 4.2BSD. The GNU
+.BR rmt
+is written from scratch, using the BSD specification.
+.SH COPYRIGHT
+Copyright \(co 2013 Free Software Foundation, Inc.
+.br
+.na
+License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
+.br
+.ad
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.\" Local variables:
+.\" eval: (add-hook 'write-file-hooks 'time-stamp)
+.\" time-stamp-start: ".TH [A-Z_][A-Z0-9_.\\-]* [0-9] \""
+.\" time-stamp-format: "%:B %:d, %:y"
+.\" time-stamp-end: "\""
+.\" time-stamp-line-limit: 20
+.\" end:
diff --git a/doc/snapshot.texi b/doc/snapshot.texi
new file mode 100644
index 0000000..ad3d398
--- /dev/null
+++ b/doc/snapshot.texi
@@ -0,0 +1,164 @@
+@c This is part of the paxutils manual.
+@c Copyright (C) 2005, 2007, 2014, 2016 Free Software Foundation, Inc.
+@c Written by Sergey Poznyakoff
+@c This file is distributed under GFDL 1.1 or any later version
+@c published by the Free Software Foundation.
+
+ A @dfn{snapshot file} (or @dfn{directory file}) is created during
+incremental backups (@pxref{Incremental Dumps}). It
+contains the status of the file system at the time of the dump and is
+used to determine which files were modified since the last backup.
+
+ @GNUTAR{} version @value{VERSION} supports three snapshot file
+formats. The first format, called @dfn{format 0}, is the one used by
+@GNUTAR{} versions up to and including 1.15.1. The second format, called
+@dfn{format 1} is an extended version of this format, that contains more
+metadata and allows for further extensions. It was used by alpha release
+version 1.15.90. For alpha version 1.15.91 and stable releases
+version 1.16 up through @value{VERSION}, the @dfn{format 2} is used.
+
+ @GNUTAR{} is able to read all three formats, but will create
+snapshots only in format 2.
+
+ This appendix describes all three formats in detail.
+
+@enumerate 0
+@cindex format 0, snapshot file
+@cindex snapshot file, format 0
+@item
+ @samp{Format 0} snapshot file begins with a line containing a
+decimal number that represents a @acronym{UNIX} timestamp of the
+beginning of the last archivation. This line is followed by directory
+metadata descriptions, one per line. Each description has the
+following format:
+
+@smallexample
+[@var{nfs}]@var{dev} @var{inode} @var{name}
+@end smallexample
+
+@noindent
+where:
+
+@table @var
+@item nfs
+A single plus character (@samp{+}), if this directory is located on
+an @acronym{NFS}-mounted partition, otherwise empty.
+
+(That is, for non-NFS directories, the first character on the
+description line contains the start of the @var{dev} field.)
+
+@item dev
+Device number of the directory;
+
+@item inode
+I-node number of the directory;
+
+@item name
+Name of the directory. Any special characters (white-space,
+backslashes, etc.) are quoted.
+@end table
+
+@cindex format 1, snapshot file
+@cindex snapshot file, format 1
+@item
+ @samp{Format 1} snapshot file begins with a line specifying the
+format of the file. This line has the following structure:
+
+@smallexample
+@samp{GNU tar-}@var{tar-version}@samp{-}@var{incr-format-version}
+@end smallexample
+
+@noindent
+where @var{tar-version} is the version number of @GNUTAR{}
+implementation that created this snapshot, and
+@var{incr-format-version} is the version number of the snapshot format
+(in this case @samp{1}).
+
+ Next line contains two decimal numbers, representing the
+time of the last backup. First number is the number of seconds, the
+second one is the number of nanoseconds, since the beginning of the
+epoch.
+
+ Lines that follow contain directory metadata, one line per
+directory. Each line is formatted as follows:
+
+@smallexample
+[@var{nfs}]@var{mtime-sec} @var{mtime-nsec} @var{dev} @var{inode} @var{name}
+@end smallexample
+
+@noindent
+where @var{mtime-sec} and @var{mtime-nsec} represent last
+modification time of this directory with nanosecond precision;
+@var{nfs}, @var{dev}, @var{inode} and @var{name} have the same meaning
+as with @samp{format 0}.
+
+@cindex format 2, snapshot file
+@cindex snapshot file, format 2
+@item
+ @samp{Format 2} snapshot file begins with a format identifier, as described for
+version 1, e.g.:
+
+@smallexample
+GNU tar-@value{VERSION}-2
+@end smallexample
+
+ This line is followed by newline. Rest of file consists of
+records, separated by null (@acronym{ASCII} 0)
+characters. Thus, in contrast to the previous formats, format 2
+snapshot is a binary file.
+
+ First two records are decimal integers, representing the
+time of the last backup. First number is the number of seconds, the
+second one is the number of nanoseconds, since the beginning of the
+epoch. These are followed by arbitrary number of directory records.
+
+ Each @dfn{directory record} contains a set of metadata describing a
+particular directory. Parts of a directory record are delimited with
+@acronym{ASCII} 0 characters. The following table describes each
+part. The @dfn{Number} type in this table stands for a decimal integer
+in @acronym{ASCII} notation. (Negative values are preceded with a "-"
+character, while positive values have no leading punctuation.)
+
+@multitable @columnfractions 0.25 0.15 0.6
+@headitem Field @tab Type @tab Description
+@item nfs @tab Character @tab @samp{1} if the directory is located on
+an @acronym{NFS}-mounted partition, or @samp{0} otherwise;
+@item timestamp_sec @tab Number @tab Modification time, seconds;
+@item timestamp_nsec @tab Number @tab Modification time, nanoseconds;
+@item dev @tab Number @tab Device number;
+@item ino @tab Number @tab I-node number;
+@item name @tab String @tab Directory name; in contrast to the
+previous versions it is not quoted;
+@item contents @tab Dumpdir @tab Contents of the directory;
+@xref{Dumpdir}, for a description of its format.
+@item
+@end multitable
+
+ Dumpdirs stored in snapshot files contain only records of types
+@samp{Y}, @samp{N} and @samp{D}.
+
+@cindex snapshot file field ranges
+@opindex show-snapshot-field-ranges
+The specific range of values allowed in each of the @dfn{Number} fields
+depends on the underlying C datatypes as determined when @command{tar}
+is compiled. To see the specific ranges allowed for a particular
+@command{tar} binary, you can use the
+@option{--show-snapshot-field-ranges} option:
+
+@smallexample
+$ @kbd{tar --show-shapshot-field-ranges}
+This tar's snapshot file field ranges are
+ (field name => [ min, max ]):
+
+ nfs => [ 0, 1 ],
+ timestamp_sec => [ -9223372036854775808, 9223372036854775807 ],
+ timestamp_nsec => [ 0, 999999999 ],
+ dev => [ 0, 18446744073709551615 ],
+ ino => [ 0, 18446744073709551615 ],
+@end smallexample
+
+(This example is from a GNU/Linux x86_64 system.)
+
+@end enumerate
+
+@c End of snapshot.texi
diff --git a/doc/sparse.texi b/doc/sparse.texi
new file mode 100644
index 0000000..2b07063
--- /dev/null
+++ b/doc/sparse.texi
@@ -0,0 +1,234 @@
+@c This is part of the paxutils manual.
+@c Copyright (C) 2006, 2014, 2016 Free Software Foundation, Inc.
+@c This file is distributed under GFDL 1.1 or any later version
+@c published by the Free Software Foundation.
+
+@cindex sparse formats
+@cindex sparse versions
+The notion of sparse file, and the ways of handling it from the point
+of view of @GNUTAR{} user have been described in detail in
+@ref{sparse}. This chapter describes the internal format @GNUTAR{}
+uses to store such files.
+
+The support for sparse files in @GNUTAR{} has a long history. The
+earliest version featuring this support that I was able to find was 1.09,
+released in November, 1990. The format introduced back then is called
+@dfn{old GNU} sparse format and in spite of the fact that its design
+contained many flaws, it was the only format @GNUTAR{} supported
+until version 1.14 (May, 2004), which introduced initial support for
+sparse archives in @acronym{PAX} archives (@pxref{posix}). This
+format was not free from design flaws, either and it was subsequently
+improved in versions 1.15.2 (November, 2005) and 1.15.92 (June,
+2006).
+
+In addition to GNU sparse format, @GNUTAR{} is able to read and
+extract sparse files archived by @command{star}.
+
+The following subsections describe each format in detail.
+
+@menu
+* Old GNU Format::
+* PAX 0:: PAX Format, Versions 0.0 and 0.1
+* PAX 1:: PAX Format, Version 1.0
+@end menu
+
+@node Old GNU Format
+@appendixsubsec Old GNU Format
+
+@cindex sparse formats, Old GNU
+@cindex Old GNU sparse format
+The format introduced in November 1990 (v. 1.09) was
+designed on top of standard @code{ustar} headers in such an
+unfortunate way that some of its fields overwrote fields required by
+POSIX.
+
+An old GNU sparse header is designated by type @samp{S}
+(@code{GNUTYPE_SPARSE}) and has the following layout:
+
+@multitable @columnfractions 0.10 0.10 0.20 0.20 0.40
+@headitem Offset @tab Size @tab Name @tab Data type @tab Contents
+@item 0 @tab 345 @tab @tab N/A @tab Not used.
+@item 345 @tab 12 @tab atime @tab Number @tab @code{atime} of the file.
+@item 357 @tab 12 @tab ctime @tab Number @tab @code{ctime} of the file .
+@item 369 @tab 12 @tab offset @tab Number @tab For
+multivolume archives: the offset of the start of this volume.
+@item 381 @tab 4 @tab @tab N/A @tab Not used.
+@item 385 @tab 1 @tab @tab N/A @tab Not used.
+@item 386 @tab 96 @tab sp @tab @code{sparse_header} @tab (4 entries) File map.
+@item 482 @tab 1 @tab isextended @tab Bool @tab @code{1} if an
+extension sparse header follows, @code{0} otherwise.
+@item 483 @tab 12 @tab realsize @tab Number @tab Real size of the file.
+@end multitable
+
+Each of @code{sparse_header} object at offset 386 describes a single
+data chunk. It has the following structure:
+
+@multitable @columnfractions 0.10 0.10 0.20 0.60
+@headitem Offset @tab Size @tab Data type @tab Contents
+@item 0 @tab 12 @tab Number @tab Offset of the
+beginning of the chunk.
+@item 12 @tab 12 @tab Number @tab Size of the chunk.
+@end multitable
+
+If the member contains more than four chunks, the @code{isextended}
+field of the header has the value @code{1} and the main header is
+followed by one or more @dfn{extension headers}. Each such header has
+the following structure:
+
+@multitable @columnfractions 0.10 0.10 0.20 0.20 0.40
+@headitem Offset @tab Size @tab Name @tab Data type @tab Contents
+@item 0 @tab 21 @tab sp @tab @code{sparse_header} @tab
+(21 entries) File map.
+@item 504 @tab 1 @tab isextended @tab Bool @tab @code{1} if an
+extension sparse header follows, or @code{0} otherwise.
+@end multitable
+
+A header with @code{isextended=0} ends the map.
+
+@node PAX 0
+@appendixsubsec PAX Format, Versions 0.0 and 0.1
+
+@cindex sparse formats, v.0.0
+There are two formats available in this branch. The version @code{0.0}
+is the initial version of sparse format used by @command{tar}
+versions 1.14--1.15.1. The sparse file map is kept in extended
+(@code{x}) PAX header variables:
+
+@table @code
+@vrindex GNU.sparse.size, extended header variable
+@item GNU.sparse.size
+Real size of the stored file;
+
+@item GNU.sparse.numblocks
+@vrindex GNU.sparse.numblocks, extended header variable
+Number of blocks in the sparse map;
+
+@item GNU.sparse.offset
+@vrindex GNU.sparse.offset, extended header variable
+Offset of the data block;
+
+@item GNU.sparse.numbytes
+@vrindex GNU.sparse.numbytes, extended header variable
+Size of the data block.
+@end table
+
+The latter two variables repeat for each data block, so the overall
+structure is like this:
+
+@smallexample
+@group
+GNU.sparse.size=@var{size}
+GNU.sparse.numblocks=@var{numblocks}
+repeat @var{numblocks} times
+ GNU.sparse.offset=@var{offset}
+ GNU.sparse.numbytes=@var{numbytes}
+end repeat
+@end group
+@end smallexample
+
+This format presented the following two problems:
+
+@enumerate 1
+@item
+Whereas the POSIX specification allows a variable to appear multiple
+times in a header, it requires that only the last occurrence be
+meaningful. Thus, multiple occurrences of @code{GNU.sparse.offset} and
+@code{GNU.sparse.numbytes} are conflicting with the POSIX specs.
+
+@item
+Attempting to extract such archives using a third-party's @command{tar}
+results in extraction of sparse files in @emph{condensed form}. If
+the @command{tar} implementation in question does not support POSIX
+format, it will also extract a file containing extension header
+attributes. This file can be used to expand the file to its original
+state. However, posix-aware @command{tar}s will usually ignore the
+unknown variables, which makes restoring the file more
+difficult. @xref{extracting sparse v.0.x, Extraction of sparse
+members in v.0.0 format}, for the detailed description of how to
+restore such members using non-GNU @command{tar}s.
+@end enumerate
+
+@cindex sparse formats, v.0.1
+@GNUTAR{} 1.15.2 introduced sparse format version @code{0.1}, which
+attempted to solve these problems. As its predecessor, this format
+stores sparse map in the extended POSIX header. It retains
+@code{GNU.sparse.size} and @code{GNU.sparse.numblocks} variables, but
+instead of @code{GNU.sparse.offset}/@code{GNU.sparse.numbytes} pairs
+it uses a single variable:
+
+@table @code
+@item GNU.sparse.map
+@vrindex GNU.sparse.map, extended header variable
+Map of non-null data chunks. It is a string consisting of
+comma-separated values "@var{offset},@var{size}[,@var{offset-1},@var{size-1}...]"
+@end table
+
+To address the 2nd problem, the @code{name} field in @code{ustar}
+is replaced with a special name, constructed using the following pattern:
+
+@smallexample
+%d/GNUSparseFile.%p/%f
+@end smallexample
+
+@vrindex GNU.sparse.name, extended header variable
+The real name of the sparse file is stored in the variable
+@code{GNU.sparse.name}. Thus, those @command{tar} implementations
+that are not aware of GNU extensions will at least extract the files
+into separate directories, giving the user a possibility to expand it
+afterwards. @xref{extracting sparse v.0.x, Extraction of sparse
+members in v.0.1 format}, for the detailed description of how to
+restore such members using non-GNU @command{tar}s.
+
+The resulting @code{GNU.sparse.map} string can be @emph{very} long.
+Although POSIX does not impose any limit on the length of a @code{x}
+header variable, this possibly can confuse some @command{tar}s.
+
+@node PAX 1
+@appendixsubsec PAX Format, Version 1.0
+
+@cindex sparse formats, v.1.0
+The version @code{1.0} of sparse format was introduced with @GNUTAR{}
+1.15.92. Its main objective was to make the resulting file
+extractable with little effort even by non-posix aware @command{tar}
+implementations. Starting from this version, the extended header
+preceding a sparse member always contains the following variables that
+identify the format being used:
+
+@table @code
+@item GNU.sparse.major
+@vrindex GNU.sparse.major, extended header variable
+Major version
+
+@item GNU.sparse.minor
+@vrindex GNU.sparse.minor, extended header variable
+Minor version
+@end table
+
+The @code{name} field in @code{ustar} header contains a special name,
+constructed using the following pattern:
+
+@smallexample
+%d/GNUSparseFile.%p/%f
+@end smallexample
+
+@vrindex GNU.sparse.name, extended header variable, in v.1.0
+@vrindex GNU.sparse.realsize, extended header variable
+The real name of the sparse file is stored in the variable
+@code{GNU.sparse.name}. The real size of the file is stored in the
+variable @code{GNU.sparse.realsize}.
+
+The sparse map itself is stored in the file data block, preceding the actual
+file data. It consists of a series of octal numbers of arbitrary length, delimited
+by newlines. The map is padded with nulls to the nearest block boundary.
+
+The first number gives the number of entries in the map. Following are map entries,
+each one consisting of two numbers giving the offset and size of the
+data block it describes.
+
+The format is designed in such a way that non-posix aware @command{tar}s and @command{tar}s not
+supporting @code{GNU.sparse.*} keywords will extract each sparse file
+in its condensed form with the file map prepended and will place it
+into a separate directory. Then, using a simple program it would be
+possible to expand the file to its original form even without @GNUTAR{}.
+@xref{Sparse Recovery}, for the detailed information on how to extract
+sparse members without @GNUTAR{}.
diff --git a/doc/stamp-vti b/doc/stamp-vti
new file mode 100644
index 0000000..eacd45d
--- /dev/null
+++ b/doc/stamp-vti
@@ -0,0 +1,4 @@
+@set UPDATED 14 April 2016
+@set UPDATED-MONTH April 2016
+@set EDITION 1.29
+@set VERSION 1.29
diff --git a/doc/tar-snapshot-edit.texi b/doc/tar-snapshot-edit.texi
new file mode 100644
index 0000000..b93639f
--- /dev/null
+++ b/doc/tar-snapshot-edit.texi
@@ -0,0 +1,91 @@
+@c This is part of the paxutils manual.
+@c Copyright (C) 2007, 2014, 2016 Free Software Foundation, Inc.
+@c This file is distributed under GFDL 1.1 or any later version
+@c published by the Free Software Foundation.
+
+@cindex Device numbers, changing
+@cindex snapshot files, editing
+@cindex snapshot files, fixing device numbers
+ Various situations can cause device numbers to change: upgrading your
+kernel version, reconfiguring your hardware, loading kernel modules in a
+different order, using virtual volumes that are assembled dynamically
+(such as with @acronym{LVM} or @acronym{RAID}), hot-plugging drives
+(e.g. external USB or Firewire drives), etc. In the majority of
+cases this change is unnoticed by the users. However, it influences
+@command{tar} incremental backups: the device number is stored in tar
+snapshot files (@pxref{Snapshot Files}) and is used to determine whether
+the file has changed since the last backup. If the device numbers
+change for some reason, by default the next backup you run will be a
+full backup.
+
+
+@pindex tar-snapshot-edit
+ To minimize the impact in these cases, GNU @command{tar} comes with
+the @command{tar-snapshot-edit} utility for inspecting and updating
+device numbers in snapshot files. (The utility, written by
+Dustin J.@: Mitchell, is also available from the
+@uref{http://www.gnu.org/@/software/@/tar/@/utils/@/tar-snapshot-edit.html,
+@GNUTAR{} home page}.)
+
+ To obtain a summary of the device numbers found in the snapshot file, run
+
+@smallexample
+$ @kbd{tar-snapshot-edit @var{snapfile}}
+@end smallexample
+
+@noindent
+where @var{snapfile} is the name of the snapshot file (you can supply as many
+files as you wish in a single command line). You can then compare the
+numbers across snapshot files, or against those currently in use on the
+live filesystem (using @command{ls -l} or @command{stat}).
+
+ Assuming the device numbers have indeed changed, it's often possible
+to simply tell @GNUTAR{} to ignore the device number when processing the
+incremental snapshot files for these backups, using the
+@option{--no-check-device} option (@pxref{device numbers}).
+
+ Alternatively, you can use the @command{tar-edit-snapshot} script's
+@option{-r} option to update all occurrences of the given device
+number in the snapshot file(s). It takes a single argument
+of the form
+@samp{@var{olddev}-@var{newdev}}, where @var{olddev} is the device number
+used in the snapshot file, and @var{newdev} is the corresponding new device
+number. Both numbers may be specified in hex (e.g., @samp{0xfe01}),
+decimal (e.g., @samp{65025}), or as a major:minor number pair (e.g.,
+@samp{254:1}). To change several device numbers at once, specify them
+in a single comma-separated list, as in
+@option{-r 0x3060-0x4500,0x307-0x4600}.
+
+Before updating the snapshot file, it is a good idea to create a backup
+copy of it. This is accomplished by @samp{-b} option. The name of the
+backup file is obtained by appending @samp{~} to the original file name.
+
+An example session:
+@smallexample
+$ @kbd{tar-snapshot-edit root_snap.0 boot_snap.0}
+File: root_snap.0
+ Detected snapshot file version: 2
+
+ Device 0x0000 occurs 1 times.
+ Device 0x0003 occurs 1 times.
+ Device 0x0005 occurs 1 times.
+ Device 0x0013 occurs 1 times.
+ Device 0x6801 occurs 1 times.
+ Device 0x6803 occurs 6626 times.
+ Device 0xfb00 occurs 1 times.
+
+File: boot_snap.0
+ Detected snapshot file version: 2
+
+ Device 0x6801 occurs 3 times.
+$ @kbd{tar-snapshot-edit -b -r 0x6801-0x6901,0x6803-0x6903 root_snap.0 boot_snap.0}
+File: root_snap.0
+ Detected snapshot file version: 2
+
+ Updated 6627 records.
+
+File: boot_snap.0
+ Detected snapshot file version: 2
+
+ Updated 3 records.
+@end smallexample
diff --git a/doc/tar.1 b/doc/tar.1
new file mode 100644
index 0000000..b72f28e
--- /dev/null
+++ b/doc/tar.1
@@ -0,0 +1,1319 @@
+.\" This file is part of GNU tar. -*- nroff -*-
+.\" Copyright 2013-2014, 2016 Free Software Foundation, Inc.
+.\"
+.\" 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/>.
+.TH TAR 1 "March 23, 2016" "TAR" "GNU TAR Manual"
+.SH NAME
+tar \- an archiving utility
+.SH SYNOPSIS
+.SS Traditional usage
+\fBtar\fR {\fBA\fR|\fBc\fR|\fBd\fR|\fBr\fR|\fBt\fR|\fBu\fR|\fBx\fR}\
+[\fBGnSkUWOmpsMBiajJzZhPlRvwo\fR] [\fIARG\fR...]
+.SS UNIX-style usage
+.sp
+\fBtar\fR \fB\-A\fR [\fIOPTIONS\fR] \fIARCHIVE\fR \fIARCHIVE\fR
+.sp
+\fBtar\fR \fB\-c\fR [\fB\-f\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIFILE\fR...]
+.sp
+\fBtar\fR \fB\-d\fR [\fB\-f\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIFILE\fR...]
+.sp
+\fBtar\fR \fB\-t\fR [\fB\-f\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIMEMBER\fR...]
+.sp
+\fBtar\fR \fB\-r\fR [\fB\-f\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIFILE\fR...]
+.sp
+\fBtar\fR \fB\-u\fR [\fB\-f\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIFILE\fR...]
+.sp
+\fBtar\fR \fB\-x\fR [\fB\-f\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIMEMBER\fR...]
+.SS GNU-style usage
+.sp
+\fBtar\fR {\fB\-\-catenate\fR|\fB\-\-concatenate\fR} [\fIOPTIONS\fR] \fIARCHIVE\fR \fIARCHIVE\fR
+.sp
+\fBtar\fR \fB\-\-create\fR [\fB\-\-file\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIFILE\fR...]
+.sp
+\fBtar\fR {\fB\-\-diff\fR|\fB\-\-compare\fR} [\fB\-\-file\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIFILE\fR...]
+.sp
+\fBtar\fR \fB\-\-delete\fR [\fB\-\-file\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIMEMBER\fR...]
+.sp
+\fBtar\fR \fB\-\-append\fR [\fB\-f\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIFILE\fR...]
+.sp
+\fBtar\fR \fB\-\-list\fR [\fB\-f\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIMEMBER\fR...]
+.sp
+\fBtar\fR \fB\-\-test\-label\fR [\fB\-\-file\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fILABEL\fR...]
+.sp
+\fBtar\fR \fB\-\-update\fR [\fB\-\-file\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIFILE\fR...]
+.sp
+\fBtar\fR \fB\-\-update\fR [\fB\-f\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIFILE\fR...]
+.sp
+\fBtar\fR {\fB\-\-extract\fR|\fB\-\-get\fR} [\fB\-f\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIMEMBER\fR...]
+.SH NOTE
+This manpage is a short description of GNU \fBtar\fR. For a detailed
+discussion, including examples and usage recommendations, refer to the
+\fBGNU Tar Manual\fR available in texinfo format. If the \fBinfo\fR
+reader and the tar documentation are properly installed on your
+system, the command
+.PP
+.RS +4
+.B info tar
+.RE
+.PP
+should give you access to the complete manual.
+.PP
+You can also view the manual using the info mode in
+.BR emacs (1),
+or find it in various formats online at
+.PP
+.RS +4
+.B http://www.gnu.org/software/tar/manual
+.RE
+.PP
+If any discrepancies occur between this manpage and the
+\fBGNU Tar Manual\fR, the later shall be considered the authoritative
+source.
+.SH DESCRIPTION
+GNU
+.B tar
+is an archiving program designed to store multiple files in a single
+file (an \fBarchive\fR), and to manipulate such archives. The archive
+can be either a regular file or a device (e.g. a tape drive, hence the name
+of the program, which stands for \fBt\fRape \fBar\fRchiver), which can
+be located either on the local or on a remote machine.
+.PP
+
+.SS Option styles
+Options to GNU \fBtar\fR can be given in three different styles.
+In
+.BR "traditional style" ,
+the first argument is a cluster of option letters and all subsequent
+arguments supply arguments to those options that require them. The
+arguments are read in the same order as the option letters. Any
+command line words that remain after all options has been processed
+are treated as non-optional arguments: file or archive member names.
+.PP
+For example, the \fBc\fR option requires creating the archive, the
+\fBv\fR option requests the verbose operation, and the \fBf\fR option
+takes an argument that sets the name of the archive to operate upon.
+The following command, written in the traditional style, instructs tar
+to store all files from the directory
+.B /etc
+into the archive file
+.B etc.tar
+verbosely listing the files being archived:
+.PP
+.EX
+.B tar cfv a.tar /etc
+.EE
+.PP
+In
+.BR "UNIX " or " short-option style" ,
+each option letter is prefixed with a single dash, as in other command
+line utilities. If an option takes argument, the argument follows it,
+either as a separate command line word, or immediately following the
+option. However, if the option takes an \fBoptional\fR argument, the
+argument must follow the option letter without any intervening
+whitespace, as in \fB\-g/tmp/snar.db\fR.
+.PP
+Any number of options not taking arguments can be
+clustered together after a single dash, e.g. \fB\-vkp\fR. Options
+that take arguments (whether mandatory or optional), can appear at
+the end of such a cluster, e.g. \fB\-vkpf a.tar\fR.
+.PP
+The example command above written in the
+.B short-option style
+could look like:
+.PP
+.EX
+.B tar -cvf a.tar /etc
+or
+.B tar -c -v -f a.tar /etc
+.EE
+.PP
+In
+.BR "GNU " or " long-option style" ,
+each option begins with two dashes and has a meaningful name,
+consisting of lower-case letters and dashes. When used, the long
+option can be abbreviated to its initial letters, provided that
+this does not create ambiguity. Arguments to long options are
+supplied either as a separate command line word, immediately following
+the option, or separated from the option by an equals sign with no
+intervening whitespace. Optional arguments must always use the latter
+method.
+.PP
+Here are several ways of writing the example command in this style:
+.PP
+.EX
+.B tar --create --file a.tar --verbose /etc
+.EE
+or (abbreviating some options):
+.EX
+.B tar --cre --file=a.tar --verb /etc
+.EE
+.PP
+The options in all three styles can be intermixed, although doing so
+with old options is not encouraged.
+.SS Operation mode
+The options listed in the table below tell GNU \fBtar\fR what
+operation it is to perform. Exactly one of them must be given.
+Meaning of non-optional arguments depends on the operation mode
+requested.
+.TP
+\fB\-A\fR, \fB\-\-catenate\fR, \fB\-\-concatenate\fR
+Append archive to the end of another archive. The arguments are
+treated as the names of archives to append. All archives must be of
+the same format as the archive they are appended to, otherwise the
+resulting archive might be unusable with non-GNU implementations of
+\fBtar\fR. Notice also that when more than one archive is given, the
+members from archives other than the first one will be accessible in
+the resulting archive only if using the \fB\-i\fR
+(\fB\-\-ignore\-zeros\fR) option.
+
+Compressed archives cannot be concatenated.
+.TP
+\fB\-c\fR, \fB\-\-create\fR
+Create a new archive. Arguments supply the names of the files to be
+archived. Directories are archived recursively, unless the
+\fB\-\-no\-recursion\fR option is given.
+.TP
+\fB\-d\fR, \fB\-\-diff\fR, \fB\-\-compare\fR
+Find differences between archive and file system. The arguments are
+optional and specify archive members to compare. If not given, the
+current working directory is assumed.
+.TP
+\fB\-\-delete\fR
+Delete from the archive. The arguments supply names of the archive
+members to be removed. At least one argument must be given.
+
+This option does not operate on compressed archives. There is no
+short option equivalent.
+.TP
+\fB\-r\fR, \fB\-\-append\fR
+Append files to the end of an archive. Arguments have the same
+meaning as for \fB\-c\fR (\fB\-\-create\fR).
+.TP
+\fB\-t\fR, \fB\-\-list\fR
+List the contents of an archive. Arguments are optional. When given,
+they specify the names of the members to list.
+.TP
+\fB\-\-test\-label
+Test the archive volume label and exit. When used without arguments,
+it prints the volume label (if any) and exits with status \fB0\fR.
+When one or more command line arguments are given.
+.B tar
+compares the volume label with each argument. It exits with code
+\fB0\fR if a match is found, and with code \fB1\fR otherwise. No
+output is displayed, unless used together with the \fB\-v\fR
+(\fB\-\-verbose\fR) option.
+
+There is no short option equivalent for this option.
+.TP
+\fB\-u\fR, \fB\-\-update\fR
+Append files which are newer than the corresponding copy in the
+archive. Arguments have the same meaning as with \fB\-c\fR and
+\fB\-r\fR options.
+.TP
+\fB\-x\fR, \fB\-\-extract\fR, \fB\-\-get\fR
+Extract files from an archive. Arguments are optional. When given,
+they specify names of the archive members to be extracted.
+.TP
+.TP
+\fB\-\-show\-defaults\fR
+Show built-in defaults for various \fBtar\fR options and exit. No
+arguments are allowed.
+.TP
+\fB\-?\fR, \fB\-\-help
+Display a short option summary and exit. No arguments allowed.
+.TP
+\fB\-\-usage\fR
+Display a list of available options and exit. No arguments allowed.
+.TP
+\fB\-\-version\fR
+Print program version and copyright information and exit.
+.SH OPTIONS
+.SS Operation modifiers
+.TP
+\fB\-\-check\-device\fR
+Check device numbers when creating incremental archives (default).
+.TP
+\fB\-g\fR, \fB\-\-listed\-incremental\fR=\fIFILE\fR
+Handle new GNU-format incremental backups. \fIFILE\fR is the name of
+a \fBsnapshot file\fR, where tar stores additional information which
+is used to decide which files changed since the previous incremental
+dump and, consequently, must be dumped again. If \fIFILE\fR does not
+exist when creating an archive, it will be created and all files will
+be added to the resulting archive (the \fBlevel 0\fR dump). To create
+incremental archives of non-zero level \fBN\fR, create a copy of the
+snapshot file created during the level \fBN-1\fR, and use it as
+\fIFILE\fR.
+
+When listing or extracting, the actual contents of \fIFILE\fR is not
+inspected, it is needed only due to syntactical requirements. It is
+therefore common practice to use \fB/dev/null\fR in its place.
+.TP
+\fB\-\-hole\-detection\fR=\fIMETHOD\fR
+Use \fIMETHOD\fR to detect holes in sparse files. This option implies
+\fB\-\-sparse\fR. Valid values for \fIMETHOD\fR are \fBseek\fR and
+\fBraw\fR. Default is \fBseek\fR with fallback to \fBraw\fR when not
+applicable.
+.TP
+\fB\-G\fR, \fB\-\-incremental\fR
+Handle old GNU-format incremental backups.
+.TP
+\fB\-\-ignore\-failed\-read\fR
+Do not exit with nonzero on unreadable files.
+.TP
+\fB\-\-level\fR=\fINUMBER\fR
+Set dump level for created listed-incremental archive. Currently only
+\fB\-\-level=0\fR is meaningful: it instructs \fBtar\fR to truncate
+the snapshot file before dumping, thereby forcing a level 0 dump.
+.TP
+\fB\-n\fR, \fB\-\-seek\fR
+Assume the archive is seekable. Normally \fBtar\fR determines
+automatically whether the archive can be seeked or not. This option
+is intended for use in cases when such recognition fails. It takes
+effect only if the archive is open for reading (e.g. with
+.B \-\-list
+or
+.B \-\-extract
+options).
+.TP
+\fB\-\-no\-check\-device\fR
+Do not check device numbers when creating incremental archives.
+.TP
+\fB\-\-no\-seek\fR
+Assume the archive is not seekable.
+.TP
+\fB\-\-occurrence\fR[=\fIN\fR]
+Process only the \fIN\fRth occurrence of each file in the
+archive. This option is valid only when used with one of the
+following subcommands: \fB\-\-delete\fR, \fB\-\-diff\fR,
+\fB\-\-extract\fR or \fB\-\-list\fR and when a list of files is given
+either on the command line or via the \fB\-T\fR option. The default
+\fIN\fR is \fB1\fR.
+.TP
+\fB\-\-restrict\fR
+Disable the use of some potentially harmful options.
+.TP
+\fB\-\-sparse\-version\fR=\fIMAJOR\fR[.\fIMINOR\fR]
+Set version of the sparse format to use (implies \fB\-\-sparse\fR).
+This option implies
+.BR \-\-sparse .
+Valid argument values are
+.BR 0.0 ,
+.BR 0.1 ", and"
+.BR 1.0 .
+For a detailed discussion of sparse formats, refer to the \fBGNU Tar
+Manual\fR, appendix \fBD\fR, "\fBSparse Formats\fR". Using \fBinfo\fR
+reader, it can be accessed running the following command:
+.BR "info tar 'Sparse Formats'" .
+.TP
+\fB\-S\fR, \fB\-\-sparse\fR
+Handle sparse files efficiently. Some files in the file system may
+have segments which were actually never written (quite often these are
+database files created by such systems as \fBDBM\fR). When given this
+option, \fBtar\fR attempts to determine if the file is sparse prior to
+archiving it, and if so, to reduce the resulting archive size by not
+dumping empty parts of the file.
+.SS Overwrite control
+These options control \fBtar\fR actions when extracting a file over
+an existing copy on disk.
+.TP
+\fB\-k\fR, \fB\-\-keep\-old\-files\fR
+Don't replace existing files when extracting.
+.TP
+\fB\-\-keep\-newer\-files\fR
+Don't replace existing files that are newer than their archive copies.
+.TP
+\fB\-\-no\-overwrite\-dir\fR
+Preserve metadata of existing directories.
+.TP
+\fB\-\-one\-top\-level\fR[\fB=\fIDIR\fR]
+Extract all files into \fIDIR\fR, or, if used without argument, into a
+subdirectory named by the base name of the archive (minus standard
+compression suffixes recognizable by \fB\-\-auto\-compress).
+.TP
+\fB\-\-overwrite\fR
+Overwrite existing files when extracting.
+.TP
+\fB\-\-overwrite\-dir\fR
+Overwrite metadata of existing directories when extracting (default).
+.TP
+\fB\-\-recursive\-unlink\fR
+Recursively remove all files in the directory prior to extracting it.
+.TP
+\fB\-\-remove\-files\fR
+Remove files from disk after adding them to the archive.
+.TP
+\fB\-\-skip\-old\-files
+Don't replace existing files when extracting, silently skip over them.
+.TP
+\fB\-U\fR, \fB\-\-unlink\-first\fR
+Remove each file prior to extracting over it.
+.TP
+\fB\-W\fR, \fB\-\-verify\fR
+Verify the archive after writing it.
+.SS Output stream selection
+.TP
+\fB\-\-ignore\-command\-error\fR
+.TP
+Ignore subprocess exit codes.
+.TP
+\fB\-\-no\-ignore\-command\-error\fR
+Treat non-zero exit codes of children as error (default).
+.TP
+\fB\-O\fR, \fB\-\-to\-stdout\fR
+Extract files to standard output.
+.TP
+\fB\-\-to\-command\fR=\fICOMMAND\fR
+Pipe extracted files to \fICOMMAND\fR. The argument is the pathname
+of an external program, optionally with command line arguments. The
+program will be invoked and the contents of the file being extracted
+supplied to it on its standard output. Additional data will be
+supplied via the following environment variables:
+.RS
+.TP
+.B TAR_FILETYPE
+Type of the file. It is a single letter with the following meaning:
+.sp
+.nf
+.ta 8n 20n
+ f Regular file
+ d Directory
+ l Symbolic link
+ h Hard link
+ b Block device
+ c Character device
+.fi
+
+Currently only regular files are supported.
+.TP
+.B TAR_MODE
+File mode, an octal number.
+.TP
+.B TAR_FILENAME
+The name of the file.
+.TP
+.B TAR_REALNAME
+Name of the file as stored in the archive.
+.TP
+.B TAR_UNAME
+Name of the file owner.
+.TP
+.B TAR_GNAME
+Name of the file owner group.
+.TP
+.B TAR_ATIME
+Time of last access. It is a decimal number, representing seconds
+since the Epoch. If the archive provides times with nanosecond
+precision, the nanoseconds are appended to the timestamp after a
+decimal point.
+.TP
+.B TAR_MTIME
+Time of last modification.
+.TP
+.B TAR_CTIME
+Time of last status change.
+.TP
+.B TAR_SIZE
+Size of the file.
+.TP
+.B TAR_UID
+UID of the file owner.
+.TP
+.B TAR_GID
+GID of the file owner.
+.RE
+.RS
+
+Additionally, the following variables contain information about
+\fBtar\fR operation mode and the archive being processed:
+.TP
+.B TAR_VERSION
+GNU \fBtar\fR version number.
+.TP
+.B TAR_ARCHIVE
+The name of the archive \fBtar\fR is processing.
+.TP
+.B TAR_BLOCKING_FACTOR
+Current blocking factor, i.e. number of 512-byte blocks in a record.
+.TP
+.B TAR_VOLUME
+Ordinal number of the volume \fBtar\fR is processing (set if
+reading a multi-volume archive).
+.TP
+.B TAR_FORMAT
+Format of the archive being processed. One of:
+.BR gnu ,
+.BR oldgnu ,
+.BR posix ,
+.BR ustar ,
+.BR v7 .
+.B TAR_SUBCOMMAND
+A short option (with a leading dash) describing the operation \fBtar\fR is
+executing.
+.RE
+.SS Handling of file attributes
+.TP
+\fB\-\-atime\-preserve\fR[=\fIMETHOD\fR]
+Preserve access times on dumped files, either by restoring the times
+after reading (\fIMETHOD\fR=\fBreplace\fR, this is the default) or by
+not setting the times in the first place (\fIMETHOD\fR=\fBsystem\fR)
+.TP
+\fB\-\-delay\-directory\-restore\fR
+Delay setting modification times and permissions of extracted
+directories until the end of extraction. Use this option when
+extracting from an archive which has unusual member ordering.
+.TP
+\fB\-\-group\fR=\fINAME\fR[:\fIGID\fR]
+Force \fINAME\fR as group for added files. If \fIGID\fR is not
+supplied, \fINAME\fR can be either a user name or numeric GID. In
+this case the missing part (GID or name) will be inferred from the
+current host's group database.
+
+When used with \fB\-\-group\-map\fR=\fIFILE\fR, affects only those
+files whose owner group is not listed in \fIFILE\fR.
+.TP
+\fB\-\-group\-map\fR=\fIFILE\fR
+Read group translation map from \fIFILE\fR. Empty lines are ignored.
+Comments are introduced with \fB#\fR sign and extend to the end of line.
+Each non-empty line in \fIFILE\fR defines translation for a single
+group. It must consist of two fields, delimited by any amount of whitespace:
+
+.EX
+\fIOLDGRP\fR \fINEWGRP\fR[\fB:\fINEWGID\fR]
+.EE
+
+\fIOLDGRP\fR is either a valid group name or a GID prefixed with
+\fB+\fR. Unless \fINEWGID\fR is supplied, \fINEWGRP\fR must also be
+either a valid group name or a \fB+\fIGID\fR. Otherwise, both
+\fINEWGRP\fR and \fINEWGID\fR need not be listed in the system group
+database.
+
+As a result, each input file with owner group \fIOLDGRP\fR will be
+stored in archive with owner group \fINEWGRP\fR and GID \fINEWGID\fR.
+.TP
+\fB\-\-mode\fR=\fICHANGES\fR
+Force symbolic mode \fICHANGES\fR for added files.
+.TP
+\fB\-\-mtime\fR=\fIDATE-OR-FILE\fR
+Set mtime for added files. \fIDATE-OR-FILE\fR is either a date/time
+in almost arbitrary format, or the name of an existing file. In the
+latter case the mtime of that file will be used.
+.TP
+\fB\-m\fR, \fB\-\-touch\fR
+Don't extract file modified time.
+.TP
+\fB\-\-no\-delay\-directory\-restore\fR
+Cancel the effect of the prior \fB\-\-delay\-directory\-restore\fR option.
+.TP
+\fB\-\-no\-same\-owner\fR
+Extract files as yourself (default for ordinary users).
+.TP
+\fB\-\-no\-same\-permissions\fR
+Apply the user's umask when extracting permissions from the archive
+(default for ordinary users).
+.TP
+\fB\-\-numeric\-owner\fR
+Always use numbers for user/group names.
+.TP
+\fB\-\-owner\fR=\fINAME\fR[:\fIUID\fR]
+Force \fINAME\fR as owner for added files. If \fIUID\fR is not
+supplied, \fINAME\fR can be either a user name or numeric UID. In
+this case the missing part (UID or name) will be inferred from the
+current host's user database.
+
+When used with \fB\-\-owner\-map\fR=\fIFILE\fR, affects only those
+files whose owner is not listed in \fIFILE\fR.
+.TP
+\fB\-\-owner\-map\fR=\fIFILE\fR
+Read owner translation map from \fIFILE\fR. Empty lines are ignored.
+Comments are introduced with \fB#\fR sign and extend to the end of line.
+Each non-empty line in \fIFILE\fR defines translation for a single
+UID. It must consist of two fields, delimited by any amount of whitespace:
+
+.EX
+\fIOLDUSR\fR \fINEWUSR\fR[\fB:\fINEWUID\fR]
+.EE
+
+\fIOLDUSR\fR is either a valid user name or a UID prefixed with
+\fB+\fR. Unless \fINEWUID\fR is supplied, \fINEWUSR\fR must also be
+either a valid user name or a \fB+\fIUID\fR. Otherwise, both
+\fINEWUSR\fR and \fINEWUID\fR need not be listed in the system user
+database.
+
+As a result, each input file owned by \fIOLDUSR\fR will be
+stored in archive with owner name \fINEWUSR\fR and UID \fINEWUID\fR.
+.TP
+\fB\-p\fR, \fB\-\-preserve\-permissions\fR, \fB\-\-same\-permissions\fR
+extract information about file permissions (default for superuser)
+.TP
+\fB\-\-preserve\fR
+Same as both \fB\-p\fR and \fB\-s\fR.
+.TP
+\fB\-\-same\-owner\fR
+Try extracting files with the same ownership as exists in the archive
+(default for superuser).
+.TP
+\fB\-s\fR, \fB\-\-preserve\-order\fR, \fB\-\-same\-order\fR
+Sort names to extract to match archive
+.TP
+\fB\-\-sort=\fIORDER\fR
+When creating an archive, sort directory entries according to
+\fIORDER\fR, which is one of
+.BR none ,
+.BR name ", or"
+.BR inode .
+
+The default is \fB\-\-sort=none\fR, which stores archive members in
+the same order as returned by the operating system.
+
+Using \fB\-\-sort=name\fR ensures the member ordering in the created archive
+is uniform and reproducible.
+
+Using \fB\-\-sort=inode\fR reduces the number of disk seeks made when
+creating the archive and thus can considerably speed up archivation.
+This sorting order is supported only if the underlying system provides
+the necessary information.
+.SS Extended file attributes
+.TP
+.B \-\-acls
+Enable POSIX ACLs support.
+.TP
+.B \-\-no\-acls
+Disable POSIX ACLs support.
+.TP
+.B \-\-selinux
+Enable SELinux context support.
+.TP
+.B \-\-no-selinux
+Disable SELinux context support.
+.TP
+.B \-\-xattrs
+Enable extended attributes support.
+.TP
+.B \-\-no\-xattrs
+Disable extended attributes support.
+.TP
+.BI \-\-xattrs\-exclude= PATTERN
+Specify the exclude pattern for xattr keys. \fIPATTERN\fR is a POSIX
+regular expression, e.g. \fB\-\-xattrs\-exclude='^user\.'\fR, to exclude
+attributes from the user namespace.
+.TP
+.BI \-\-xattrs\-include= PATTERN
+Specify the include pattern for xattr keys. \fIPATTERN\fR is a POSIX
+regular expression.
+.SS Device selection and switching
+.TP
+\fB\-f\fR, \fB\-\-file\fR=\fIARCHIVE\fR
+Use archive file or device \fIARCHIVE\fR. If this option is not
+given, \fBtar\fR will first examine the environment variable `TAPE'.
+If it is set, its value will be used as the archive name. Otherwise,
+\fBtar\fR will assume the compiled-in default. The default
+value can be inspected either using the
+.B \-\-show\-defaults
+option, or at the end of the \fBtar \-\-help\fR output.
+
+An archive name that has a colon in it specifies a file or device on a
+remote machine. The part before the colon is taken as the machine
+name or IP address, and the part after it as the file or device
+pathname, e.g.:
+
+.EX
+--file=remotehost:/dev/sr0
+.EE
+
+An optional username can be prefixed to the hostname, placing a \fB@\fR
+sign between them.
+
+By default, the remote host is accessed via the
+.BR rsh (1)
+command. Nowadays it is common to use
+.BR ssh (1)
+instead. You can do so by giving the following command line option:
+
+.EX
+--rsh-command=/usr/bin/ssh
+.EE
+
+The remote machine should have the
+.BR rmt (8)
+command installed. If its pathname does not match \fBtar\fR's
+default, you can inform \fBtar\fR about the correct pathname using the
+.B \-\-rmt\-command
+option.
+.TP
+\fB\-\-force\-local\fR
+Archive file is local even if it has a colon.
+.TP
+\fB\-F\fR, \fB\-\-info\-script\fR=\fICOMMAND\fR, \fB\-\-new\-volume\-script\fR=\fICOMMAND\fR
+Run \fICOMMAND\fR at the end of each tape (implies \fB\-M\fR). The
+command can include arguments. When started, it will inherit \fBtar\fR's
+environment plus the following variables:
+.RS
+.TP
+.B TAR_VERSION
+GNU \fBtar\fR version number.
+.TP
+.B TAR_ARCHIVE
+The name of the archive \fBtar\fR is processing.
+.TP
+.B TAR_BLOCKING_FACTOR
+Current blocking factor, i.e. number of 512-byte blocks in a record.
+.TP
+.B TAR_VOLUME
+Ordinal number of the volume \fBtar\fR is processing (set if
+reading a multi-volume archive).
+.TP
+.B TAR_FORMAT
+Format of the archive being processed. One of:
+.BR gnu ,
+.BR oldgnu ,
+.BR posix ,
+.BR ustar ,
+.BR v7 .
+.TP
+.B TAR_SUBCOMMAND
+A short option (with a leading dash) describing the operation \fBtar\fR is
+executing.
+.TP
+.B TAR_FD
+File descriptor which can be used to communicate the new volume name
+to
+.BR tar .
+.RE
+.RS
+
+If the info script fails, \fBtar\fR exits; otherwise, it begins writing
+the next volume.
+.RE
+.TP
+\fB\-L\fR, \fB\-\-tape\-length\fR=\fIN\fR
+Change tape after writing \fIN\fRx1024 bytes. If \fIN\fR is followed
+by a size suffix (see the subsection
+.B Size suffixes
+below), the suffix specifies the multiplicative factor to be used
+instead of 1024.
+
+This option implies
+.BR \-M .
+.TP
+\fB\-M\fR, \fB\-\-multi\-volume\fR
+Create/list/extract multi-volume archive.
+.TP
+\fB\-\-rmt\-command\fR=\fICOMMAND\fR
+Use \fICOMMAND\fR instead of \fBrmt\fR when accessing remote
+archives. See the description of the
+.B \-f
+option, above.
+.TP
+\fB\-\-rsh\-command\fR=\fICOMMAND\fR
+Use \fICOMMAND\fR instead of \fBrsh\fR when accessing remote
+archives. See the description of the
+.B \-f
+option, above.
+.TP
+\fB\-\-volno\-file\fR=\fIFILE\fR
+When this option is used in conjunction with
+.BR \-\-multi\-volume ,
+.B tar
+will keep track of which volume of a multi-volume archive it is
+working in \fIFILE\fR.
+.SS Device blocking
+.TP
+\fB\-b\fR, \fB\-\-blocking\-factor\fR=\fIBLOCKS\fR
+Set record size to \fIBLOCKS\fRx\fB512\fR bytes.
+.TP
+\fB\-B\fR, \fB\-\-read\-full\-records\fR
+When listing or extracting, accept incomplete input records after
+end-of-file marker.
+.TP
+\fB\-i\fR, \fB\-\-ignore\-zeros\fR
+Ignore zeroed blocks in archive. Normally two consecutive 512-blocks
+filled with zeroes mean EOF and tar stops reading after encountering
+them. This option instructs it to read further and is useful when
+reading archives created with the \fB\-A\fR option.
+.TP
+\fB\-\-record\-size\fR=\fINUMBER\fR
+Set record size. \fINUMBER\fR is the number of bytes per record. It
+must be multiple of \fB512\fR. It can can be suffixed with a \fBsize
+suffix\fR, e.g. \fB\-\-record-size=10K\fR, for 10 Kilobytes. See the
+subsection
+.BR "Size suffixes" ,
+for a list of valid suffixes.
+.SS Archive format selection
+.TP
+\fB\-H\fR, \fB\-\-format\fR=\fIFORMAT\fR
+Create archive of the given format. Valid formats are:
+.RS
+.TP
+.B gnu
+GNU tar 1.13.x format
+.TP
+.B oldgnu
+GNU format as per tar <= 1.12.
+.TP
+\fBpax\fR, \fBposix\fR
+POSIX 1003.1-2001 (pax) format.
+.TP
+.B ustar
+POSIX 1003.1-1988 (ustar) format.
+.TP
+.B v7
+Old V7 tar format.
+.RE
+.TP
+\fB\-\-old\-archive\fR, \fB\-\-portability\fR
+Same as \fB\-\-format=v7\fR.
+.TP
+\fB\-\-pax\-option\fR=\fIkeyword\fR[[:]=\fIvalue\fR][,\fIkeyword\fR[[:]=\fIvalue\fR]]...
+Control pax keywords when creating \fBPAX\fR archives (\fB\-H
+pax\fR). This option is equivalent to the \fB\-o\fR option of the
+.BR pax (1) utility.
+.TP
+\fB\-\-posix\fR
+Same as \fB\-\-format=posix\fR.
+.TP
+\fB\-V\fR, \fB\-\-label\fR=\fITEXT\fR
+Create archive with volume name \fITEXT\fR. If listing or extracting,
+use \fITEXT\fR as a globbing pattern for volume name.
+.SS Compression options
+.TP
+\fB\-a\fR, \fB\-\-auto\-compress\fR
+Use archive suffix to determine the compression program.
+.TP
+\fB\-I\fR, \fB\-\-use\-compress\-program\fI=\fICOMMAND\fR
+Filter data through \fICOMMAND\fR. It must accept the \fB\-d\fR
+option, for decompression. The argument can contain command line
+options.
+.TP
+\fB\-j\fR, \fB\-\-bzip2\fR
+Filter the archive through
+.BR bzip2 (1).
+.TP
+\fB\-J\fR, \fB\-\-xz\fR
+Filter the archive through
+.BR xz (1).
+.TP
+\fB\-\-lzip\fR
+Filter the archive through
+.BR lzip (1).
+.TP
+\fB\-\-lzma\fR
+Filter the archive through
+.BR lzma (1).
+.TP
+\fB\-\-lzop\fR
+Filter the archive through
+.BR lzop (1).
+.TP
+\fB\-\-no\-auto\-compress\fR
+Do not use archive suffix to determine the compression program.
+.TP
+\fB\-z\fR, \fB\-\-gzip\fR, \fB\-\-gunzip\fR, \fB\-\-ungzip\fR
+Filter the archive through
+.BR gzip (1).
+.TP
+\fB\-Z\fR, \fB\-\-compress\fR, \fB\-\-uncompress\fR
+Filter the archive through
+.BR compress (1).
+.SS Local file selection
+.TP
+\fB\-\-add\-file\fR=\fIFILE\fR
+Add \fIFILE\fR to the archive (useful if its name starts with a dash).
+.TP
+\fB\-\-backup\fR[=\fICONTROL\fR]
+Backup before removal. The \fICONTROL\fR argument, if supplied,
+controls the backup policy. Its valid values are:
+.RS
+.TP
+.BR none ", " off
+Never make backups.
+.TP
+.BR t ", " numbered
+Make numbered backups.
+.TP
+.BR nil ", " existing
+Make numbered backups if numbered backups exist, simple backups otherwise.
+.TP
+.BR never ", " simple
+Always make simple backups
+.RS
+.RE
+
+If \fICONTROL\fR is not given, the value is taken from the
+.B VERSION_CONTROL
+environment variable. If it is not set, \fBexisting\fR is assumed.
+.RE
+.TP
+\fB\-C\fR, \fB\-\-directory\fR=\fIDIR\fR
+Change to \fIDIR\fR before performing any operations. This option is
+order-sensitive, i.e. it affects all options that follow.
+.TP
+\fB\-\-exclude\fR=\fIPATTERN\fR
+Exclude files matching \fIPATTERN\fR, a
+.BR glob (3)-style
+wildcard pattern.
+.TP
+\fB\-\-exclude\-backups\fR
+Exclude backup and lock files.
+.TP
+\fB\-\-exclude\-caches\fR
+Exclude contents of directories containing file \fBCACHEDIR.TAG\fR,
+except for the tag file itself.
+.TP
+\fB\-\-exclude\-caches\-all\fR
+Exclude directories containing file \fBCACHEDIR.TAG\fR and the file itself.
+.TP
+\fB\-\-exclude\-caches\-under\fR
+Exclude everything under directories containing \fBCACHEDIR.TAG\fR
+.TP
+\fB\-\-exclude\-ignore=\fIFILE\fR
+Before dumping a directory, see if it contains \fIFILE\fR.
+If so, read exclusion patterns from this file. The patterns affect
+only the directory itself.
+.TP
+\fB\-\-exclude\-ignore\-recursive=\fIFILE\fR
+Same as \fB\-\-exclude\-ignore\fR, except that patterns from
+\fIFILE\fR affect both the directory and all its subdirectories.
+.TP
+\fB\-\-exclude\-tag\fR=\fIFILE\fR
+Exclude contents of directories containing \fIFILE\fR, except for
+\fIFILE\fR itself.
+.TP
+\fB\-\-exclude\-tag\-all\fR=\fIFILE\fR
+Exclude directories containing \fIFILE\fR.
+.TP
+\fB\-\-exclude\-tag\-under\fR=\fIFILE\fR
+Exclude everything under directories containing \fIFILE\fR.
+.TP
+\fB\-\-exclude\-vcs\fR
+Exclude version control system directories.
+.TP
+\fB\-\-exclude\-vcs\-ignores\fR
+Exclude files that match patterns read from VCS-specific ignore
+files. Supported files are:
+.BR .cvsignore ,
+.BR .gitignore ,
+.BR .bzrignore ", and"
+.BR .hgignore .
+.TP
+\fB\-h\fR, \fB\-\-dereference\fR
+Follow symlinks; archive and dump the files they point to.
+.TP
+\fB\-\-hard\-dereference\fR
+Follow hard links; archive and dump the files they refer to.
+.TP
+\fB\-K\fR, \fB\-\-starting\-file\fR=\fIMEMBER\fR
+Begin at the given member in the archive.
+.TP
+\fB\-\-newer\-mtime\fR=\fIDATE\fR
+Work on files whose data changed after the \fIDATE\fR. If \fIDATE\fR
+starts with \fB/\fR or \fB.\fR it is taken to be a file name; the
+mtime of that file is used as the date.
+.TP
+\fB\-\-no\-null\fR
+Disable the effect of the previous \fB\-\-null\fR option.
+.TP
+\fB\-\-no\-recursion\fR
+Avoid descending automatically in directories.
+.TP
+\fB\-\-no\-unquote\fR
+Do not unquote input file or member names.
+.TP
+\fB\-\-no\-verbatim\-files\-from\fR
+Treat each line read from a file list as if it were supplied in the
+command line. I.e., leading and trailing whitespace is removed and,
+if the resulting string begins with a dash, it is treated as \fBtar\fR
+command line option.
+
+This is the default behavior. The \fB\-\-no\-verbatim\-files\-from\fR
+option is provided as a way to restore it after
+\fB\-\-verbatim\-files\-from\fR option.
+
+This option is positional: it affects all \fB\-\-files\-from\fR
+options that occur after it in, until \fB\-\-verbatim\-files\-from\fR
+option or end of line, whichever occurs first.
+
+It is implied by the \fB\-\-no\-null\fR option.
+.TP
+\fB\-\-null\fR
+Instruct subsequent \fB\-T\fR options to read null-terminated names
+verbatim (disables special handling of names that start with a dash).
+
+See also \fB\-\-verbatim\-files\-from\fR.
+.TP
+\fB\-N\fR, \fB\-\-newer\fR=\fIDATE\fR, \fB\-\-after\-date\fR=\fIDATE\fR
+Only store files newer than DATE. If \fIDATE\fR starts with \fB/\fR
+or \fB.\fR it is taken to be a file name; the ctime of that file is
+used as the date.
+.TP
+\fB\-\-one\-file\-system\fR
+Stay in local file system when creating archive.
+.TP
+\fB\-P\fR, \fB\-\-absolute\-names\fR
+Don't strip leading slashes from file names when creating archives.
+.TP
+\fB\-\-recursion\fR
+Recurse into directories (default).
+.TP
+\fB\-\-suffix\fR=\fISTRING\fR
+Backup before removal, override usual suffix. Default suffix is \fB~\fR,
+unless overridden by environment variable \fBSIMPLE_BACKUP_SUFFIX\fR.
+.TP
+\fB\-T\fR, \fB\-\-files\-from\fR=\fIFILE\fR
+Get names to extract or create from \fIFILE\fR.
+
+Unless specified otherwise, the \fIFILE\fR must contain a list of
+names separated by ASCII \fBLF\fR (i.e. one name per line). The
+names read are handled the same way as command line arguments. They
+undergo quote removal and word splitting, and any string that starts
+with a \fB\-\fR is handled as \fBtar\fR command line option.
+
+If this behavior is undesirable, it can be turned off using the
+\fB\-\-verbatim\-files\-from\fR option.
+
+The \fB\-\-null\fR option instructs \fBtar\fR that the names in
+\fIFILE\fR are separated by ASCII \fBNUL\fR character, instead of
+\fBLF\fR. It is useful if the list is generated by
+.BR find (1)
+.B \-print0
+predicate.
+.TP
+\fB\-\-unquote\fR
+Unquote file or member names (default).
+.TP
+\fB\-\-verbatim\-files\-from\fR
+Treat each line obtained from a file list as a file name, even if it
+starts with a dash. File lists are supplied with the
+\fB\-\-files\-from\fR (\fB\-T\fR) option. The default behavior is to
+handle names supplied in file lists as if they were typed in the
+command line, i.e. any names starting with a dash are treated as
+\fBtar\fR options. The \fB\-\-verbatim\-files\-from\fR option
+disables this behavior.
+
+This option affects all \fB\-\-files\-from\fR options that occur after
+it in the command line. Its effect is reverted by the
+\fB\-\-no\-verbatim\-files\-from} option.
+
+This option is implied by the \fB\-\-null\fR option.
+
+See also \fB\-\-add\-file\fR.
+.TP
+\fB\-X\fR, \fB\-\-exclude\-from\fR=\fIFILE\fR
+Exclude files matching patterns listed in FILE.
+.SS File name transformations
+.TP
+\fB\-\-strip\-components\fR=\fINUMBER\fR
+Strip \fINUMBER\fR leading components from file names on extraction.
+.TP
+\fB\-\-transform\fR=\fIEXPRESSION\fR, \fB\-\-xform\fR=\fIEXPRESSION\fR
+Use sed replace \fIEXPRESSION\fR to transform file names.
+.SS File name matching options
+These options affect both exclude and include patterns.
+.TP
+\fB\-\-anchored\fR
+Patterns match file name start.
+.TP
+\fB\-\-ignore\-case\fR
+Ignore case.
+.TP
+\fB\-\-no\-anchored\fR
+Patterns match after any \fB/\fR (default for exclusion).
+.TP
+\fB\-\-no\-ignore\-case\fR
+Case sensitive matching (default).
+.TP
+\fB\-\-no\-wildcards\fR
+Verbatim string matching.
+.TP
+\fB\-\-no\-wildcards\-match\-slash\fR
+Wildcards do not match \fB/\fR.
+.TP
+\fB\-\-wildcards\fR
+Use wildcards (default for exclusion).
+.TP
+\fB\-\-wildcards\-match\-slash\fR
+Wildcards match \fB/\fR (default for exclusion).
+.SS Informative output
+.TP
+\fB\-\-checkpoint\fR[=\fIN\fR]
+Display progress messages every \fIN\fRth record (default 10).
+.TP
+\fB\-\-checkpoint\-action\fR=\fIACTION\fR
+Run \fIACTION\fR on each checkpoint.
+.TP
+\fB\-\-clamp\-mtime\fR
+Only set time when the file is more recent than what was given with \-\-mtime.
+.TP
+\fB\-\-full\-time\fR
+Print file time to its full resolution.
+.TP
+\fB\-\-index\-file\fR=\fIFILE\fR
+Send verbose output to \fIFILE\fR.
+.TP
+\fB\-l\fR, \fB\-\-check\-links\fR
+Print a message if not all links are dumped.
+.TP
+\fB\-\-no\-quote\-chars\fR=\fISTRING\fR
+Disable quoting for characters from \fISTRING\fR.
+.TP
+\fB\-\-quote\-chars\fR=\fISTRING\fR
+Additionally quote characters from \fISTRING\fR.
+.TP
+\fB\-\-quoting\-style\fR=\fISTYLE\fR
+Set quoting style for file and member names. Valid values for
+\fISTYLE\fR are
+.BR literal ,
+.BR shell ,
+.BR shell-always ,
+.BR c ,
+.BR c-maybe ,
+.BR escape ,
+.BR locale ,
+.BR clocale .
+.TP
+\fB\-R\fR, \fB\-\-block\-number\fR
+Show block number within archive with each message.
+.TP
+\fB\-\-show\-omitted\-dirs\fR
+When listing or extracting, list each directory that does not match
+search criteria.
+.TP
+\fB\-\-show\-transformed\-names\fR, \fB\-\-show\-stored\-names\fR
+Show file or archive names after transformation by \fB\-\-strip\fR and
+\fB\-\-transform\fR options.
+.TP
+\fB\-\-totals\fR[=\fISIGNAL\fR]
+Print total bytes after processing the archive. If \fISIGNAL\fR is
+given, print total bytes when this signal is delivered. Allowed
+signals are:
+.BR SIGHUP ,
+.BR SIGQUIT ,
+.BR SIGINT ,
+.BR SIGUSR1 ", and"
+.BR SIGUSR2 .
+The \fBSIG\fR prefix can be omitted.
+.TP
+\fB\-\-utc\fR
+Print file modification times in UTC.
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+Verbosely list files processed.
+.TP
+\fB\-\-warning\fR=\fIKEYWORD\fR
+Enable or disable warning messages identified by \fIKEYWORD\fR. The
+messages are suppressed if \fIKEYWORD\fR is prefixed with \fBno\-\fR
+and enabled otherwise.
+
+Multiple \fB\-\-warning\fR messages accumulate.
+
+Keywords controlling general \fBtar\fR operation:
+.RS
+.TP
+.B all
+Enable all warning messages. This is the default.
+.TP
+.B none
+Disable all warning messages.
+.TP
+.B filename-with-nuls
+"%s: file name read contains nul character"
+.TP
+.B alone-zero-block
+"A lone zero block at %s"
+.HP
+Keywords applicable for \fBtar --create\fR:
+.TP
+.B cachedir
+"%s: contains a cache directory tag %s; %s"
+.TP
+.B file-shrank
+"%s: File shrank by %s bytes; padding with zeros"
+.TP
+.B xdev
+"%s: file is on a different filesystem; not dumped"
+.TP
+.B file-ignored
+"%s: Unknown file type; file ignored"
+.br
+"%s: socket ignored"
+.br
+"%s: door ignored"
+.TP
+.B file-unchanged
+"%s: file is unchanged; not dumped"
+.TP
+.B ignore-archive
+"%s: file is the archive; not dumped"
+.TP
+.B file-removed
+"%s: File removed before we read it"
+.TP
+.B file-changed
+"%s: file changed as we read it"
+.HP
+Keywords applicable for \fBtar --extract\fR:
+.TP
+.B existing\-file
+"%s: skipping existing file"
+.TP
+.B timestamp
+"%s: implausibly old time stamp %s"
+.br
+"%s: time stamp %s is %s s in the future"
+.TP
+.B contiguous-cast
+"Extracting contiguous files as regular files"
+.TP
+.B symlink-cast
+"Attempting extraction of symbolic links as hard links"
+.TP
+.B unknown-cast
+"%s: Unknown file type '%c', extracted as normal file"
+.TP
+.B ignore-newer
+"Current %s is newer or same age"
+.TP
+.B unknown-keyword
+"Ignoring unknown extended header keyword '%s'"
+.TP
+.B decompress-program
+Controls verbose description of failures occurring when trying to run
+alternative decompressor programs. This warning is disabled by
+default (unless \fB\-\-verbose\fR is used). A common example of what
+you can get when using this warning is:
+
+.EX
+$ \fBtar --warning=decompress-program -x -f archive.Z
+tar (child): cannot run compress: No such file or directory
+tar (child): trying gzip
+.EE
+
+This means that \fBtar\fR first tried to decompress
+\fBarchive.Z\fR using \fBcompress\fR, and, when that
+failed, switched to \fBgzip\fR.
+.TP
+.B record-size
+"Record size = %lu blocks"
+.HP
+Keywords controlling incremental extraction:
+.TP
+.B rename-directory
+"%s: Directory has been renamed from %s"
+.br
+"%s: Directory has been renamed"
+.TP
+.B new-directory
+"%s: Directory is new"
+.TP
+.B xdev
+"%s: directory is on a different device: not purging"
+.TP
+.B bad-dumpdir
+"Malformed dumpdir: 'X' never used"
+.RE
+.TP
+\fB\-w\fR, \fB\-\-interactive\fR, \fB\-\-confirmation\fR
+Ask for confirmation for every action.
+.SS Compatibility options
+.TP
+\fB\-o\fR
+When creating, same as \fB\-\-old\-archive\fR. When extracting, same
+as \fB\-\-no\-same\-owner\fR.
+.SS Size suffixes
+.sp
+.nf
+.ta 8n 18n 42n
+.ul
+ Suffix Units Byte Equivalent
+ b Blocks \fISIZE\fR x 512
+ B Kilobytes \fISIZE\fR x 1024
+ c Bytes \fISIZE\fR
+ G Gigabytes \fISIZE\fR x 1024^3
+ K Kilobytes \fISIZE\fR x 1024
+ k Kilobytes \fISIZE\fR x 1024
+ M Megabytes \fISIZE\fR x 1024^2
+ P Petabytes \fISIZE\fR x 1024^5
+ T Terabytes \fISIZE\fR x 1024^4
+ w Words \fISIZE\fR x 2
+.fi
+.PP
+.SH "RETURN VALUE"
+Tar exit code indicates whether it was able to successfully perform
+the requested operation, and if not, what kind of error occurred.
+.TP
+.B 0
+Successful termination.
+.TP
+.B 1
+.I Some files differ.
+If tar was invoked with the \fB\-\-compare\fR (\fB\-\-diff\fR, \fB\-d\fR)
+command line option, this means that some files in the archive differ
+from their disk counterparts. If tar was given one of the \fB\-\-create\fR,
+\fB\-\-append\fR or \fB\-\-update\fR options, this exit code means
+that some files were changed while being archived and so the resulting
+archive does not contain the exact copy of the file set.
+.TP
+.B 2
+.I Fatal error.
+This means that some fatal, unrecoverable error occurred.
+.PP
+If a subprocess that had been invoked by
+.B tar
+exited with a nonzero exit code,
+.B tar
+itself exits with that code as well. This can happen, for example, if
+a compression option (e.g. \fB\-z\fR) was used and the external
+compressor program failed. Another example is
+.B rmt
+failure during backup to a remote device.
+.SH "SEE ALSO"
+.BR bzip2 (1),
+.BR compress (1),
+.BR gzip (1),
+.BR lzma (1),
+.BR lzop (1),
+.BR rmt (8),
+.BR symlink (7),
+.BR tar (5),
+.BR xz (1).
+.PP
+Complete \fBtar\fR manual: run
+.B info tar
+or use
+.BR emacs (1)
+info mode to read it.
+.PP
+Online copies of \fBGNU tar\fR documentation in various formats can be
+found at:
+.PP
+.in +4
+.B http://www.gnu.org/software/tar/manual
+.SH "BUG REPORTS"
+Report bugs to <bug\-tar@gnu.org>.
+.SH COPYRIGHT
+Copyright \(co 2013 Free Software Foundation, Inc.
+.br
+.na
+License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
+.br
+.ad
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.\" Local variables:
+.\" eval: (add-hook 'write-file-hooks 'time-stamp)
+.\" time-stamp-start: ".TH [A-Z_][A-Z0-9_.\\-]* [0-9] \""
+.\" time-stamp-format: "%:B %:d, %:y"
+.\" time-stamp-end: "\""
+.\" time-stamp-line-limit: 20
+.\" end:
+
diff --git a/doc/tar.info b/doc/tar.info
new file mode 100644
index 0000000..9488af3
--- /dev/null
+++ b/doc/tar.info
@@ -0,0 +1,466 @@
+This is tar.info, produced by makeinfo version 5.9.93 from tar.texi.
+
+This manual is for GNU 'tar' (version 1.29, 14 April 2016), which
+creates and extracts files from archives.
+
+ Copyright (C) 1992, 1994-1997, 1999-2001, 2003-2016 Free Software
+Foundation, Inc.
+
+ Permission is granted to copy, distribute and/or modify this
+ document under the terms of the GNU Free Documentation License,
+ Version 1.3 or any later version published by the Free Software
+ Foundation; with the Invariant Sections being "GNU General Public
+ License", with the Front-Cover Texts being "A GNU Manual", and with
+ the Back-Cover Texts as in (a) below. A copy of the license is
+ included in the section entitled "GNU Free Documentation License".
+
+ (a) The FSF's Back-Cover Text is: "You have the freedom to copy and
+ modify this GNU manual."
+INFO-DIR-SECTION Archiving
+START-INFO-DIR-ENTRY
+* Tar: (tar). Making tape (or disk) archives.
+END-INFO-DIR-ENTRY
+
+INFO-DIR-SECTION Individual utilities
+START-INFO-DIR-ENTRY
+* tar: (tar)tar invocation. Invoking GNU 'tar'.
+END-INFO-DIR-ENTRY
+
+
+Indirect:
+tar.info-1: 1138
+tar.info-2: 302896
+
+Tag Table:
+(Indirect)
+Node: Top1138
+Node: Introduction10495
+Node: Book Contents11282
+Node: Definitions13454
+Node: What tar Does15257
+Node: Naming tar Archives18024
+Node: Authors18745
+Node: Reports20558
+Node: Tutorial20915
+Node: assumptions21728
+Node: stylistic conventions24202
+Node: basic tar options24645
+Node: frequent operations28284
+Node: Two Frequent Options28934
+Node: file tutorial29565
+Node: verbose tutorial30923
+Ref: verbose member listing33137
+Node: help tutorial35905
+Node: create36260
+Node: prepare for examples37698
+Node: Creating the archive39467
+Node: create verbose43054
+Node: short create43874
+Node: create dir46609
+Node: list49317
+Ref: listing member and file names50852
+Node: list dir53471
+Node: extract54483
+Node: extracting archives55597
+Node: extracting files56102
+Ref: extracting files-Footnote-157988
+Node: extract dir58368
+Node: extracting untrusted archives60760
+Node: failing commands61640
+Node: going further63225
+Node: tar invocation63438
+Node: Synopsis65218
+Ref: exit status68540
+Node: using tar options70173
+Ref: TAR_OPTIONS71753
+Node: Styles72772
+Ref: Styles-Footnote-174271
+Node: Long Options74527
+Node: Short Options76699
+Ref: Short Options-Footnote-178507
+Node: Old Options78724
+Node: Mixing81487
+Ref: Mixing-Footnote-183853
+Node: All Options83973
+Node: Operation Summary84609
+Ref: --append84729
+Ref: --catenate84810
+Ref: --compare84882
+Ref: --concatenate85086
+Ref: --create85197
+Ref: --delete85266
+Ref: --diff85381
+Ref: --extract85438
+Ref: --get85541
+Ref: --list85600
+Ref: --update85669
+Node: Option Summary85880
+Ref: --absolute-names86035
+Ref: --acls86327
+Ref: --after-date86408
+Ref: --anchored86461
+Ref: --atime-preserve86594
+Ref: --auto-compress89110
+Ref: --backup89338
+Ref: --block-number89530
+Ref: --blocking-factor89705
+Ref: --bzip289858
+Ref: --check-device89966
+Ref: --checkpoint90161
+Ref: --checkpoint-action90604
+Ref: --check-links91763
+Ref: --compress92040
+Ref: --uncompress92040
+Ref: --clamp-mtime92245
+Ref: --confirmation92285
+Ref: --delay-directory-restore92354
+Ref: --dereference92557
+Ref: --directory92752
+Ref: --exclude93006
+Ref: --exclude-backups93126
+Ref: --exclude-from93216
+Ref: --exclude-caches93363
+Ref: --exclude-caches-under93572
+Ref: --exclude-caches-all93751
+Ref: --exclude-ignore93881
+Ref: --exclude-ignore-recursive94101
+Ref: --exclude-tag94345
+Ref: --exclude-tag-under94517
+Ref: --exclude-tag-all94708
+Ref: --exclude-vcs94838
+Ref: --exclude-vcs-ignores94998
+Ref: --file95391
+Ref: --files-from95592
+Ref: --force-local95796
+Ref: --format95988
+Ref: --full-time96663
+Ref: --group97343
+Ref: --group-map97670
+Ref: --gzip98062
+Ref: --gunzip98062
+Ref: --ungzip98062
+Ref: --hard-dereference98286
+Ref: --help98473
+Ref: --hole-detection98609
+Ref: --ignore-case98845
+Ref: --ignore-command-error98972
+Ref: --ignore-failed-read99084
+Ref: --ignore-zeros99226
+Ref: --incremental99371
+Ref: --index-file99637
+Ref: --info-script99723
+Ref: --new-volume-script99723
+Ref: --interactive100021
+Ref: --keep-directory-symlink100234
+Ref: --keep-newer-files100783
+Ref: --keep-old-files100926
+Ref: --label101139
+Ref: --level101428
+Ref: --listed-incremental101868
+Ref: --lzip102233
+Ref: --lzma102334
+Ref: --mode102536
+Ref: --mtime102829
+Ref: --multi-volume103509
+Ref: --newer103715
+Ref: --newer-mtime103994
+Ref: --no-acls104219
+Ref: --no-anchored104313
+Ref: --no-auto-compress104450
+Ref: --no-check-device104602
+Ref: --no-delay-directory-restore104785
+Ref: --no-ignore-case105034
+Ref: --no-ignore-command-error105127
+Ref: --no-null105283
+Ref: --no-overwrite-dir105489
+Ref: --no-quote-chars105633
+Ref: --no-recursion105814
+Ref: --no-same-owner105920
+Ref: --no-same-permissions106104
+Ref: --no-seek106307
+Ref: --no-selinux106526
+Ref: --no-unquote106627
+Ref: --no-verbatim-files-from106765
+Ref: --no-wildcards107266
+Ref: --no-wildcards-match-slash107350
+Ref: --no-xattrs107452
+Ref: --null107555
+Ref: --numeric-owner107906
+Ref: --occurrence108558
+Ref: --old-archive109126
+Ref: --one-file-system109175
+Ref: --one-top-level109353
+Ref: --overwrite109989
+Ref: --overwrite-dir110132
+Ref: --owner110278
+Ref: --owner-map110641
+Ref: --pax-option111017
+Ref: --portability111324
+Ref: --posix111389
+Ref: --preserve-order111431
+Ref: --preserve-permissions111496
+Ref: --same-permissions111496
+Ref: --quote-chars111911
+Ref: --quoting-style112064
+Ref: --read-full-records112387
+Ref: --record-size112553
+Ref: --recursion112906
+Ref: --recursive-unlink113011
+Ref: --remove-files113174
+Ref: --restrict113321
+Ref: --rmt-command113510
+Ref: --rsh-command113652
+Ref: --same-order113775
+Ref: --same-owner114068
+Ref: --seek114447
+Ref: --selinux114818
+Ref: --show-defaults114919
+Ref: --show-omitted-dirs115429
+Ref: --show-snapshot-field-ranges115584
+Ref: --show-transformed-names115781
+Ref: --show-stored-names115781
+Ref: --skip-old-files116171
+Ref: --sort116622
+Ref: --sparse117261
+Ref: --sparse-version117401
+Ref: --starting-file117627
+Ref: --strip-components117817
+Ref: --suffix118154
+Ref: --tape-length118274
+Ref: --test-label118699
+Ref: --to-command118852
+Ref: --to-stdout119012
+Ref: --totals119166
+Ref: --touch119398
+Ref: --transform119601
+Ref: --xform119601
+Ref: --unlink-first120215
+Ref: --unquote120379
+Ref: --use-compress-program120486
+Ref: --utc120665
+Ref: --verbatim-files-from120759
+Ref: --verbose121603
+Ref: --verify121856
+Ref: --version121975
+Ref: --volno-file122148
+Ref: --warning122336
+Ref: --wildcards122514
+Ref: --wildcards-match-slash122634
+Ref: --xattrs122726
+Ref: --xattrs-exclude122825
+Ref: --xattrs-include122952
+Ref: --xz123217
+Ref: Option Summary-Footnote-1123347
+Node: Short Option Summary123566
+Node: Position-Sensitive Options126469
+Ref: Position-Sensitive Options-Footnote-1129341
+Node: help129503
+Ref: help-Footnote-1133338
+Node: defaults133549
+Node: verbose134568
+Ref: totals136871
+Ref: Progress information138461
+Ref: show-omitted-dirs139440
+Ref: block-number139859
+Ref: verbose-Footnote-1140886
+Node: checkpoints140993
+Ref: checkpoint exec147058
+Node: warnings149087
+Node: interactive152490
+Node: external154589
+Node: operations156177
+Node: Basic tar156436
+Ref: Basic tar-Footnote-1159543
+Node: Advanced tar159687
+Node: Operations160532
+Node: append162427
+Ref: append-Footnote-1165524
+Node: appending files165711
+Node: multiple167448
+Node: update170170
+Node: how to update171147
+Node: concatenate172931
+Ref: concatenate-Footnote-1176179
+Node: delete176322
+Node: compare178096
+Node: create options179530
+Node: override180017
+Node: Extended File Attributes187078
+Node: Ignore Failed Read191713
+Node: extract options191949
+Node: Reading192782
+Node: read full records194282
+Node: Ignore Zeros194617
+Node: Writing195608
+Node: Dealing with Old Files196165
+Node: Overwrite Old Files198967
+Node: Keep Old Files200424
+Node: Keep Newer Files201231
+Node: Unlink First201521
+Node: Recursive Unlink201925
+Node: Data Modification Times202478
+Node: Setting Access Permissions203288
+Node: Directory Modification Times and Permissions203920
+Node: Writing to Standard Output207533
+Node: Writing to an External Program209068
+Node: remove files212658
+Node: Scarce212851
+Node: Starting File213099
+Node: Same Order213900
+Node: backup214736
+Node: Applications217827
+Node: looking ahead219291
+Node: Backups220117
+Node: Full Dumps221698
+Node: Incremental Dumps223507
+Ref: --level=0226421
+Ref: device numbers226954
+Ref: incremental-op230937
+Ref: Incremental Dumps-Footnote-1231311
+Ref: Incremental Dumps-Footnote-2231461
+Node: Backup Levels231949
+Node: Backup Parameters234336
+Node: General-Purpose Variables235517
+Ref: RSH238685
+Node: Magnetic Tape Control240569
+Node: User Hooks241908
+Node: backup-specs example243241
+Node: Scripted Backups244381
+Ref: Scripted Backups-Footnote-1247246
+Node: Scripted Restoration247630
+Node: Choosing250236
+Node: file251358
+Ref: remote-dev253994
+Ref: local and remote archives254379
+Node: Selecting Archive Members255410
+Ref: input name quoting256091
+Node: files258066
+Ref: verbatim-files-from260773
+Ref: no-verbatim-files-from261033
+Ref: files-Footnote-1261775
+Node: nul261933
+Node: exclude264391
+Ref: exclude-vcs-ignores265949
+Ref: exclude-vcs267662
+Ref: exclude-Footnote-1271598
+Ref: exclude-Footnote-2271852
+Node: problems with exclude271923
+Node: wildcards273973
+Node: controlling pattern-matching276556
+Ref: anchored patterns279197
+Ref: case-insensitive matches279467
+Ref: controlling pattern-matching-Footnote-1280544
+Node: quoting styles280761
+Ref: escape sequences281106
+Node: transform287250
+Ref: show-transformed-names289241
+Node: after295433
+Node: recurse299035
+Node: one302896
+Node: directory304329
+Node: absolute307428
+Ref: absolute-Footnote-1310755
+Node: Date input formats311106
+Node: General date syntax313502
+Node: Calendar date items316479
+Node: Time of day items318476
+Node: Time zone items320672
+Node: Combined date and time of day items321923
+Node: Day of week items322776
+Node: Relative items in date strings323784
+Node: Pure numbers in date strings326586
+Node: Seconds since the Epoch327567
+Node: Specifying time zone rules329189
+Node: Authors of parse_datetime331562
+Ref: Authors of get_date331741
+Node: Formats332704
+Node: Compression337379
+Node: gzip337671
+Ref: alternative decompression programs339882
+Ref: auto-compress343431
+Ref: use-compress-program344196
+Ref: gzip-Footnote-1346163
+Ref: gzip-Footnote-2346212
+Node: lbzip2346352
+Node: sparse347449
+Node: Attributes351993
+Node: Portability357655
+Node: Portable Names359141
+Node: dereference359846
+Node: hard links360973
+Ref: hard links-Footnote-1363858
+Node: old363914
+Node: ustar365097
+Node: gnu365700
+Node: posix366577
+Node: PAX keywords367058
+Node: Checksumming373056
+Node: Large or Negative Values375000
+Node: Other Tars376601
+Node: Split Recovery377737
+Node: Sparse Recovery381486
+Ref: extracting sparse v.0.x385115
+Ref: Sparse Recovery-Footnote-1388404
+Ref: Sparse Recovery-Footnote-2388427
+Node: cpio388548
+Node: Media393309
+Node: Device395260
+Ref: size-suffixes400051
+Node: Remote Tape Server401191
+Node: Common Problems and Solutions404855
+Node: Blocking405247
+Ref: Blocking-Footnote-1411731
+Node: Format Variations411835
+Node: Blocking Factor412750
+Node: Many424401
+Node: Tape Positioning428195
+Node: mt430071
+Node: Using Multiple Tapes431628
+Node: Multi-Volume Archives433694
+Ref: tape-length435179
+Ref: change volume prompt435734
+Ref: volno-file436601
+Ref: info-script437154
+Ref: Multi-Volume Archives-Footnote-1442739
+Ref: Multi-Volume Archives-Footnote-2442849
+Node: Tape Files442917
+Node: Tarcat444402
+Node: label445447
+Ref: --test-label option447035
+Ref: label-Footnote-1450486
+Ref: label-Footnote-2450595
+Ref: label-Footnote-3450728
+Node: verify450963
+Node: Write Protection454263
+Node: Reliability and security455093
+Node: Reliability455481
+Node: Permissions problems456259
+Node: Data corruption and repair456698
+Node: Race conditions457625
+Node: Security459364
+Node: Privacy459967
+Node: Integrity461216
+Node: Live untrusted data463427
+Node: Security rules of thumb465766
+Node: Changes467294
+Node: Configuring Help Summary470915
+Node: Fixing Snapshot Files477431
+Node: Tar Internals480800
+Node: Standard481132
+Node: Extensions503335
+Node: Sparse Formats505897
+Node: Old GNU Format507186
+Node: PAX 0509573
+Node: PAX 1512691
+Node: Snapshot Files514419
+Node: Dumpdir520017
+Node: Genfile523247
+Node: Generate Mode524343
+Node: Status Mode529583
+Node: Exec Mode531385
+Node: Free Software Needs Free Documentation534145
+Node: GNU Free Documentation License539126
+Node: Index of Command Line Options564329
+Node: Index592555
+
+End Tag Table
diff --git a/doc/tar.info-1 b/doc/tar.info-1
new file mode 100644
index 0000000..ac57a2f
--- /dev/null
+++ b/doc/tar.info-1
@@ -0,0 +1,7890 @@
+This is tar.info, produced by makeinfo version 5.9.93 from tar.texi.
+
+This manual is for GNU 'tar' (version 1.29, 14 April 2016), which
+creates and extracts files from archives.
+
+ Copyright (C) 1992, 1994-1997, 1999-2001, 2003-2016 Free Software
+Foundation, Inc.
+
+ Permission is granted to copy, distribute and/or modify this
+ document under the terms of the GNU Free Documentation License,
+ Version 1.3 or any later version published by the Free Software
+ Foundation; with the Invariant Sections being "GNU General Public
+ License", with the Front-Cover Texts being "A GNU Manual", and with
+ the Back-Cover Texts as in (a) below. A copy of the license is
+ included in the section entitled "GNU Free Documentation License".
+
+ (a) The FSF's Back-Cover Text is: "You have the freedom to copy and
+ modify this GNU manual."
+INFO-DIR-SECTION Archiving
+START-INFO-DIR-ENTRY
+* Tar: (tar). Making tape (or disk) archives.
+END-INFO-DIR-ENTRY
+
+INFO-DIR-SECTION Individual utilities
+START-INFO-DIR-ENTRY
+* tar: (tar)tar invocation. Invoking GNU 'tar'.
+END-INFO-DIR-ENTRY
+
+
+File: tar.info, Node: Top, Next: Introduction, Up: (dir)
+
+GNU tar: an archiver tool
+*************************
+
+This manual is for GNU 'tar' (version 1.29, 14 April 2016), which
+creates and extracts files from archives.
+
+ Copyright (C) 1992, 1994-1997, 1999-2001, 2003-2016 Free Software
+Foundation, Inc.
+
+ Permission is granted to copy, distribute and/or modify this
+ document under the terms of the GNU Free Documentation License,
+ Version 1.3 or any later version published by the Free Software
+ Foundation; with the Invariant Sections being "GNU General Public
+ License", with the Front-Cover Texts being "A GNU Manual", and with
+ the Back-Cover Texts as in (a) below. A copy of the license is
+ included in the section entitled "GNU Free Documentation License".
+
+ (a) The FSF's Back-Cover Text is: "You have the freedom to copy and
+ modify this GNU manual."
+
+ The first part of this master menu lists the major nodes in this Info
+document. The rest of the menu lists all the lower level nodes.
+
+* Menu:
+
+* Introduction::
+* Tutorial::
+* tar invocation::
+* operations::
+* Backups::
+* Choosing::
+* Date input formats::
+* Formats::
+* Media::
+* Reliability and security::
+
+Appendices
+
+* Changes::
+* Configuring Help Summary::
+* Fixing Snapshot Files::
+* Tar Internals::
+* Genfile::
+* Free Software Needs Free Documentation::
+* GNU Free Documentation License::
+* Index of Command Line Options::
+* Index::
+
+ -- The Detailed Node Listing --
+
+Introduction
+
+* Book Contents:: What this Book Contains
+* Definitions:: Some Definitions
+* What tar Does:: What 'tar' Does
+* Naming tar Archives:: How 'tar' Archives are Named
+* Authors:: GNU 'tar' Authors
+* Reports:: Reporting bugs or suggestions
+
+Tutorial Introduction to 'tar'
+
+* assumptions::
+* stylistic conventions::
+* basic tar options:: Basic 'tar' Operations and Options
+* frequent operations::
+* Two Frequent Options::
+* create:: How to Create Archives
+* list:: How to List Archives
+* extract:: How to Extract Members from an Archive
+* going further::
+
+Two Frequently Used Options
+
+* file tutorial::
+* verbose tutorial::
+* help tutorial::
+
+How to Create Archives
+
+* prepare for examples::
+* Creating the archive::
+* create verbose::
+* short create::
+* create dir::
+
+How to List Archives
+
+* list dir::
+
+How to Extract Members from an Archive
+
+* extracting archives::
+* extracting files::
+* extract dir::
+* extracting untrusted archives::
+* failing commands::
+
+Invoking GNU 'tar'
+
+* Synopsis::
+* using tar options::
+* Styles::
+* All Options::
+* help::
+* defaults::
+* verbose::
+* checkpoints::
+* warnings::
+* interactive::
+
+The Three Option Styles
+
+* Long Options:: Long Option Style
+* Short Options:: Short Option Style
+* Old Options:: Old Option Style
+* Mixing:: Mixing Option Styles
+
+All 'tar' Options
+
+* Operation Summary::
+* Option Summary::
+* Short Option Summary::
+* Position-Sensitive Options::
+
+GNU 'tar' Operations
+
+* Basic tar::
+* Advanced tar::
+* create options::
+* extract options::
+* backup::
+* Applications::
+* looking ahead::
+
+Advanced GNU 'tar' Operations
+
+* Operations::
+* append::
+* update::
+* concatenate::
+* delete::
+* compare::
+
+How to Add Files to Existing Archives: '--append'
+
+* appending files:: Appending Files to an Archive
+* multiple::
+
+Updating an Archive
+
+* how to update::
+
+Options Used by '--create'
+
+* override:: Overriding File Metadata.
+* Extended File Attributes::
+* Ignore Failed Read::
+
+Options Used by '--extract'
+
+* Reading:: Options to Help Read Archives
+* Writing:: Changing How 'tar' Writes Files
+* Scarce:: Coping with Scarce Resources
+
+Options to Help Read Archives
+
+* read full records::
+* Ignore Zeros::
+
+Changing How 'tar' Writes Files
+
+* Dealing with Old Files::
+* Overwrite Old Files::
+* Keep Old Files::
+* Keep Newer Files::
+* Unlink First::
+* Recursive Unlink::
+* Data Modification Times::
+* Setting Access Permissions::
+* Directory Modification Times and Permissions::
+* Writing to Standard Output::
+* Writing to an External Program::
+* remove files::
+
+Coping with Scarce Resources
+
+* Starting File::
+* Same Order::
+
+Performing Backups and Restoring Files
+
+* Full Dumps:: Using 'tar' to Perform Full Dumps
+* Incremental Dumps:: Using 'tar' to Perform Incremental Dumps
+* Backup Levels:: Levels of Backups
+* Backup Parameters:: Setting Parameters for Backups and Restoration
+* Scripted Backups:: Using the Backup Scripts
+* Scripted Restoration:: Using the Restore Script
+
+Setting Parameters for Backups and Restoration
+
+* General-Purpose Variables::
+* Magnetic Tape Control::
+* User Hooks::
+* backup-specs example:: An Example Text of 'Backup-specs'
+
+Choosing Files and Names for 'tar'
+
+* file:: Choosing the Archive's Name
+* Selecting Archive Members::
+* files:: Reading Names from a File
+* exclude:: Excluding Some Files
+* wildcards:: Wildcards Patterns and Matching
+* quoting styles:: Ways of Quoting Special Characters in Names
+* transform:: Modifying File and Member Names
+* after:: Operating Only on New Files
+* recurse:: Descending into Directories
+* one:: Crossing File System Boundaries
+
+Reading Names from a File
+
+* nul::
+
+Excluding Some Files
+
+* problems with exclude::
+
+Wildcards Patterns and Matching
+
+* controlling pattern-matching::
+
+Crossing File System Boundaries
+
+* directory:: Changing Directory
+* absolute:: Absolute File Names
+
+Date input formats
+
+* General date syntax:: Common rules.
+* Calendar date items:: 19 Dec 1994.
+* Time of day items:: 9:20pm.
+* Time zone items:: EST, PDT, GMT.
+* Day of week items:: Monday and others.
+* Relative items in date strings:: next tuesday, 2 years ago.
+* Pure numbers in date strings:: 19931219, 1440.
+* Seconds since the Epoch:: @1078100502.
+* Specifying time zone rules:: TZ="America/New_York", TZ="UTC0".
+* Authors of parse_datetime:: Bellovin, Eggert, Salz, Berets, et al.
+
+Controlling the Archive Format
+
+* Compression:: Using Less Space through Compression
+* Attributes:: Handling File Attributes
+* Portability:: Making 'tar' Archives More Portable
+* cpio:: Comparison of 'tar' and 'cpio'
+
+Using Less Space through Compression
+
+* gzip:: Creating and Reading Compressed Archives
+* sparse:: Archiving Sparse Files
+
+Creating and Reading Compressed Archives
+
+* lbzip2:: Using lbzip2 with GNU 'tar'.
+
+Making 'tar' Archives More Portable
+
+* Portable Names:: Portable Names
+* dereference:: Symbolic Links
+* hard links:: Hard Links
+* old:: Old V7 Archives
+* ustar:: Ustar Archives
+* gnu:: GNU and old GNU format archives.
+* posix:: POSIX archives
+* Checksumming:: Checksumming Problems
+* Large or Negative Values:: Large files, negative time stamps, etc.
+* Other Tars:: How to Extract GNU-Specific Data Using
+ Other 'tar' Implementations
+
+GNU 'tar' and POSIX 'tar'
+
+* PAX keywords:: Controlling Extended Header Keywords.
+
+How to Extract GNU-Specific Data Using Other 'tar' Implementations
+
+* Split Recovery:: Members Split Between Volumes
+* Sparse Recovery:: Sparse Members
+
+Tapes and Other Archive Media
+
+* Device:: Device selection and switching
+* Remote Tape Server::
+* Common Problems and Solutions::
+* Blocking:: Blocking
+* Many:: Many archives on one tape
+* Using Multiple Tapes:: Using Multiple Tapes
+* label:: Including a Label in the Archive
+* verify::
+* Write Protection::
+
+Blocking
+
+* Format Variations:: Format Variations
+* Blocking Factor:: The Blocking Factor of an Archive
+
+Many Archives on One Tape
+
+* Tape Positioning:: Tape Positions and Tape Marks
+* mt:: The 'mt' Utility
+
+Using Multiple Tapes
+
+* Multi-Volume Archives:: Archives Longer than One Tape or Disk
+* Tape Files:: Tape Files
+* Tarcat:: Concatenate Volumes into a Single Archive
+
+
+Tar Internals
+
+* Standard:: Basic Tar Format
+* Extensions:: GNU Extensions to the Archive Format
+* Sparse Formats:: Storing Sparse Files
+* Snapshot Files::
+* Dumpdir::
+
+Storing Sparse Files
+
+* Old GNU Format::
+* PAX 0:: PAX Format, Versions 0.0 and 0.1
+* PAX 1:: PAX Format, Version 1.0
+
+Genfile
+
+* Generate Mode:: File Generation Mode.
+* Status Mode:: File Status Mode.
+* Exec Mode:: Synchronous Execution mode.
+
+Copying This Manual
+
+* GNU Free Documentation License:: License for copying this manual
+
+
+
+File: tar.info, Node: Introduction, Next: Tutorial, Prev: Top, Up: Top
+
+1 Introduction
+**************
+
+GNU 'tar' creates and manipulates "archives" which are actually
+collections of many other files; the program provides users with an
+organized and systematic method for controlling a large amount of data.
+The name "tar" originally came from the phrase "Tape ARchive", but
+archives need not (and these days, typically do not) reside on tapes.
+
+* Menu:
+
+* Book Contents:: What this Book Contains
+* Definitions:: Some Definitions
+* What tar Does:: What 'tar' Does
+* Naming tar Archives:: How 'tar' Archives are Named
+* Authors:: GNU 'tar' Authors
+* Reports:: Reporting bugs or suggestions
+
+
+File: tar.info, Node: Book Contents, Next: Definitions, Up: Introduction
+
+1.1 What this Book Contains
+===========================
+
+The first part of this chapter introduces you to various terms that will
+recur throughout the book. It also tells you who has worked on GNU
+'tar' and its documentation, and where you should send bug reports or
+comments.
+
+ The second chapter is a tutorial (*note Tutorial::) which provides a
+gentle introduction for people who are new to using 'tar'. It is meant
+to be self-contained, not requiring any reading from subsequent chapters
+to make sense. It moves from topic to topic in a logical, progressive
+order, building on information already explained.
+
+ Although the tutorial is paced and structured to allow beginners to
+learn how to use 'tar', it is not intended solely for beginners. The
+tutorial explains how to use the three most frequently used operations
+('create', 'list', and 'extract') as well as two frequently used options
+('file' and 'verbose'). The other chapters do not refer to the tutorial
+frequently; however, if a section discusses something which is a complex
+variant of a basic concept, there may be a cross-reference to that basic
+concept. (The entire book, including the tutorial, assumes that the
+reader understands some basic concepts of using a Unix-type operating
+system; *note Tutorial::.)
+
+ The third chapter presents the remaining five operations, and
+information about using 'tar' options and option syntax.
+
+ The other chapters are meant to be used as a reference. Each chapter
+presents everything that needs to be said about a specific topic.
+
+ One of the chapters (*note Date input formats::) exists in its
+entirety in other GNU manuals, and is mostly self-contained. In
+addition, one section of this manual (*note Standard::) contains a big
+quote which is taken directly from 'tar' sources.
+
+ In general, we give both long and short (abbreviated) option names at
+least once in each section where the relevant option is covered, so that
+novice readers will become familiar with both styles. (A few options
+have no short versions, and the relevant sections will indicate this.)
+
+
+File: tar.info, Node: Definitions, Next: What tar Does, Prev: Book Contents, Up: Introduction
+
+1.2 Some Definitions
+====================
+
+The 'tar' program is used to create and manipulate 'tar' archives. An
+"archive" is a single file which contains the contents of many files,
+while still identifying the names of the files, their owner(s), and so
+forth. (In addition, archives record access permissions, user and
+group, size in bytes, and data modification time. Some archives also
+record the file names in each archived directory, as well as other file
+and directory information.) You can use 'tar' to "create" a new archive
+in a specified directory.
+
+ The files inside an archive are called "members". Within this
+manual, we use the term "file" to refer only to files accessible in the
+normal ways (by 'ls', 'cat', and so forth), and the term "member" to
+refer only to the members of an archive. Similarly, a "file name" is
+the name of a file, as it resides in the file system, and a "member
+name" is the name of an archive member within the archive.
+
+ The term "extraction" refers to the process of copying an archive
+member (or multiple members) into a file in the file system. Extracting
+all the members of an archive is often called "extracting the archive".
+The term "unpack" can also be used to refer to the extraction of many or
+all the members of an archive. Extracting an archive does not destroy
+the archive's structure, just as creating an archive does not destroy
+the copies of the files that exist outside of the archive. You may also
+"list" the members in a given archive (this is often thought of as
+"printing" them to the standard output, or the command line), or
+"append" members to a pre-existing archive. All of these operations can
+be performed using 'tar'.
+
+
+File: tar.info, Node: What tar Does, Next: Naming tar Archives, Prev: Definitions, Up: Introduction
+
+1.3 What 'tar' Does
+===================
+
+The 'tar' program provides the ability to create 'tar' archives, as well
+as various other kinds of manipulation. For example, you can use 'tar'
+on previously created archives to extract files, to store additional
+files, or to update or list files which were already stored.
+
+ Initially, 'tar' archives were used to store files conveniently on
+magnetic tape. The name 'tar' comes from this use; it stands for 't'ape
+'ar'chiver. Despite the utility's name, 'tar' can direct its output to
+available devices, files, or other programs (using pipes). 'tar' may
+even access remote devices or files (as archives).
+
+ You can use 'tar' archives in many ways. We want to stress a few of
+them: storage, backup, and transportation.
+
+Storage
+ Often, 'tar' archives are used to store related files for
+ convenient file transfer over a network. For example, the GNU
+ Project distributes its software bundled into 'tar' archives, so
+ that all the files relating to a particular program (or set of
+ related programs) can be transferred as a single unit.
+
+ A magnetic tape can store several files in sequence. However, the
+ tape has no names for these files; it only knows their relative
+ position on the tape. One way to store several files on one tape
+ and retain their names is by creating a 'tar' archive. Even when
+ the basic transfer mechanism can keep track of names, as FTP can,
+ the nuisance of handling multiple files, directories, and multiple
+ links makes 'tar' archives useful.
+
+ Archive files are also used for long-term storage. You can think
+ of this as transportation from the present into the future. (It is
+ a science-fiction idiom that you can move through time as well as
+ in space; the idea here is that 'tar' can be used to move archives
+ in all dimensions, even time!)
+
+Backup
+ Because the archive created by 'tar' is capable of preserving file
+ information and directory structure, 'tar' is commonly used for
+ performing full and incremental backups of disks. A backup puts a
+ collection of files (possibly pertaining to many users and
+ projects) together on a disk or a tape. This guards against
+ accidental destruction of the information in those files. GNU
+ 'tar' has special features that allow it to be used to make
+ incremental and full dumps of all the files in a file system.
+
+Transportation
+ You can create an archive on one system, transfer it to another
+ system, and extract the contents there. This allows you to
+ transport a group of files from one system to another.
+
+
+File: tar.info, Node: Naming tar Archives, Next: Authors, Prev: What tar Does, Up: Introduction
+
+1.4 How 'tar' Archives are Named
+================================
+
+Conventionally, 'tar' archives are given names ending with '.tar'. This
+is not necessary for 'tar' to operate properly, but this manual follows
+that convention in order to accustom readers to it and to make examples
+more clear.
+
+ Often, people refer to 'tar' archives as "'tar' files," and archive
+members as "files" or "entries". For people familiar with the operation
+of 'tar', this causes no difficulty. However, in this manual, we
+consistently refer to "archives" and "archive members" to make learning
+to use 'tar' easier for novice users.
+
+
+File: tar.info, Node: Authors, Next: Reports, Prev: Naming tar Archives, Up: Introduction
+
+1.5 GNU 'tar' Authors
+=====================
+
+GNU 'tar' was originally written by John Gilmore, and modified by many
+people. The GNU enhancements were written by Jay Fenlason, then Joy
+Kendall, and the whole package has been further maintained by Thomas
+Bushnell, n/BSG, Franc,ois Pinard, Paul Eggert, and finally Sergey
+Poznyakoff with the help of numerous and kind users.
+
+ We wish to stress that 'tar' is a collective work, and owes much to
+all those people who reported problems, offered solutions and other
+insights, or shared their thoughts and suggestions. An impressive, yet
+partial list of those contributors can be found in the 'THANKS' file
+from the GNU 'tar' distribution.
+
+ Jay Fenlason put together a draft of a GNU 'tar' manual, borrowing
+notes from the original man page from John Gilmore. This was withdrawn
+in version 1.11. Thomas Bushnell, n/BSG and Amy Gorin worked on a
+tutorial and manual for GNU 'tar'. Franc,ois Pinard put version 1.11.8
+of the manual together by taking information from all these sources and
+merging them. Melissa Weisshaus finally edited and redesigned the book
+to create version 1.12. The book for versions from 1.14 up to 1.29 were
+edited by the current maintainer, Sergey Poznyakoff.
+
+ For version 1.12, Daniel Hagerty contributed a great deal of
+technical consulting. In particular, he is the primary author of *note
+Backups::.
+
+ In July, 2003 GNU 'tar' was put on CVS at savannah.gnu.org (see
+<http://savannah.gnu.org/projects/tar>), and active development and
+maintenance work has started again. Currently GNU 'tar' is being
+maintained by Paul Eggert, Sergey Poznyakoff and Jeff Bailey.
+
+ Support for POSIX archives was added by Sergey Poznyakoff.
+
+
+File: tar.info, Node: Reports, Prev: Authors, Up: Introduction
+
+1.6 Reporting bugs or suggestions
+=================================
+
+If you find problems or have suggestions about this program or manual,
+please report them to 'bug-tar@gnu.org'.
+
+ When reporting a bug, please be sure to include as much detail as
+possible, in order to reproduce it.
+
+
+File: tar.info, Node: Tutorial, Next: tar invocation, Prev: Introduction, Up: Top
+
+2 Tutorial Introduction to 'tar'
+********************************
+
+This chapter guides you through some basic examples of three 'tar'
+operations: '--create', '--list', and '--extract'. If you already know
+how to use some other version of 'tar', then you may not need to read
+this chapter. This chapter omits most complicated details about how
+'tar' works.
+
+* Menu:
+
+* assumptions::
+* stylistic conventions::
+* basic tar options:: Basic 'tar' Operations and Options
+* frequent operations::
+* Two Frequent Options::
+* create:: How to Create Archives
+* list:: How to List Archives
+* extract:: How to Extract Members from an Archive
+* going further::
+
+
+File: tar.info, Node: assumptions, Next: stylistic conventions, Up: Tutorial
+
+2.1 Assumptions this Tutorial Makes
+===================================
+
+This chapter is paced to allow beginners to learn about 'tar' slowly.
+At the same time, we will try to cover all the basic aspects of these
+three operations. In order to accomplish both of these tasks, we have
+made certain assumptions about your knowledge before reading this
+manual, and the hardware you will be using:
+
+ * Before you start to work through this tutorial, you should
+ understand what the terms "archive" and "archive member" mean
+ (*note Definitions::). In addition, you should understand
+ something about how Unix-type operating systems work, and you
+ should know how to use some basic utilities. For example, you
+ should know how to create, list, copy, rename, edit, and delete
+ files and directories; how to change between directories; and how
+ to figure out where you are in the file system. You should have
+ some basic understanding of directory structure and how files are
+ named according to which directory they are in. You should
+ understand concepts such as standard output and standard input,
+ what various definitions of the term 'argument' mean, and the
+ differences between relative and absolute file names.
+
+ * This manual assumes that you are working from your own home
+ directory (unless we state otherwise). In this tutorial, you will
+ create a directory to practice 'tar' commands in. When we show
+ file names, we will assume that those names are relative to your
+ home directory. For example, my home directory is
+ '/home/fsf/melissa'. All of my examples are in a subdirectory of
+ the directory named by that file name; the subdirectory is called
+ 'practice'.
+
+ * In general, we show examples of archives which exist on (or can be
+ written to, or worked with from) a directory on a hard disk. In
+ most cases, you could write those archives to, or work with them on
+ any other device, such as a tape drive. However, some of the later
+ examples in the tutorial and next chapter will not work on tape
+ drives. Additionally, working with tapes is much more complicated
+ than working with hard disks. For these reasons, the tutorial does
+ not cover working with tape drives. *Note Media::, for complete
+ information on using 'tar' archives with tape drives.
+
+
+File: tar.info, Node: stylistic conventions, Next: basic tar options, Prev: assumptions, Up: Tutorial
+
+2.2 Stylistic Conventions
+=========================
+
+In the examples, '$' represents a typical shell prompt. It precedes
+lines you should type; to make this more clear, those lines are shown in
+'this font', as opposed to lines which represent the computer's
+response; those lines are shown in 'this font', or sometimes 'like
+this'.
+
+
+File: tar.info, Node: basic tar options, Next: frequent operations, Prev: stylistic conventions, Up: Tutorial
+
+2.3 Basic 'tar' Operations and Options
+======================================
+
+'tar' can take a wide variety of arguments which specify and define the
+actions it will have on the particular set of files or the archive. The
+main types of arguments to 'tar' fall into one of two classes:
+operations, and options.
+
+ Some arguments fall into a class called "operations"; exactly one of
+these is both allowed and required for any instance of using 'tar'; you
+may _not_ specify more than one. People sometimes speak of "operating
+modes". You are in a particular operating mode when you have specified
+the operation which specifies it; there are eight operations in total,
+and thus there are eight operating modes.
+
+ The other arguments fall into the class known as "options". You are
+not required to specify any options, and you are allowed to specify more
+than one at a time (depending on the way you are using 'tar' at that
+time). Some options are used so frequently, and are so useful for
+helping you type commands more carefully that they are effectively
+"required". We will discuss them in this chapter.
+
+ You can write most of the 'tar' operations and options in any of
+three forms: long (mnemonic) form, short form, and old style. Some of
+the operations and options have no short or "old" forms; however, the
+operations and options which we will cover in this tutorial have
+corresponding abbreviations. We will indicate those abbreviations
+appropriately to get you used to seeing them. Note, that the "old
+style" option forms exist in GNU 'tar' for compatibility with Unix
+'tar'. In this book we present a full discussion of this way of writing
+options and operations (*note Old Options::), and we discuss the other
+two styles of writing options (*Note Long Options::, and *note Short
+Options::).
+
+ In the examples and in the text of this tutorial, we usually use the
+long forms of operations and options; but the "short" forms produce the
+same result and can make typing long 'tar' commands easier. For
+example, instead of typing
+
+ tar --create --verbose --file=afiles.tar apple angst aspic
+
+you can type
+ tar -c -v -f afiles.tar apple angst aspic
+
+or even
+ tar -cvf afiles.tar apple angst aspic
+
+For more information on option syntax, see *note Advanced tar::. In
+discussions in the text, when we name an option by its long form, we
+also give the corresponding short option in parentheses.
+
+ The term, "option", can be confusing at times, since "operations" are
+often lumped in with the actual, _optional_ "options" in certain general
+class statements. For example, we just talked about "short and long
+forms of options and operations". However, experienced 'tar' users
+often refer to these by shorthand terms such as, "short and long
+options". This term assumes that the "operations" are included, also.
+Context will help you determine which definition of "options" to use.
+
+ Similarly, the term "command" can be confusing, as it is often used
+in two different ways. People sometimes refer to 'tar' "commands". A
+'tar' "command" is the entire command line of user input which tells
+'tar' what to do -- including the operation, options, and any arguments
+(file names, pipes, other commands, etc.). However, you will also
+sometimes hear the term "the 'tar' command". When the word "command" is
+used specifically like this, a person is usually referring to the 'tar'
+_operation_, not the whole line. Again, use context to figure out which
+of the meanings the speaker intends.
+
+
+File: tar.info, Node: frequent operations, Next: Two Frequent Options, Prev: basic tar options, Up: Tutorial
+
+2.4 The Three Most Frequently Used Operations
+=============================================
+
+Here are the three most frequently used operations (both short and long
+forms), as well as a brief description of their meanings. The rest of
+this chapter will cover how to use these operations in detail. We will
+present the rest of the operations in the next chapter.
+
+'--create'
+'-c'
+ Create a new 'tar' archive.
+'--list'
+'-t'
+ List the contents of an archive.
+'--extract'
+'-x'
+ Extract one or more members from an archive.
+
+
+File: tar.info, Node: Two Frequent Options, Next: create, Prev: frequent operations, Up: Tutorial
+
+2.5 Two Frequently Used Options
+===============================
+
+To understand how to run 'tar' in the three operating modes listed
+previously, you also need to understand how to use two of the options to
+'tar': '--file' (which takes an archive file as an argument) and
+'--verbose'. (You are usually not _required_ to specify either of these
+options when you run 'tar', but they can be very useful in making things
+more clear and helping you avoid errors.)
+
+* Menu:
+
+* file tutorial::
+* verbose tutorial::
+* help tutorial::
+
+
+File: tar.info, Node: file tutorial, Next: verbose tutorial, Up: Two Frequent Options
+
+The '--file' Option
+-------------------
+
+'--file=ARCHIVE-NAME'
+'-f ARCHIVE-NAME'
+ Specify the name of an archive file.
+
+ You can specify an argument for the '--file=ARCHIVE-NAME' ('-f
+ARCHIVE-NAME') option whenever you use 'tar'; this option determines the
+name of the archive file that 'tar' will work on.
+
+ If you don't specify this argument, then 'tar' will examine the
+environment variable 'TAPE'. If it is set, its value will be used as
+the archive name. Otherwise, 'tar' will use the default archive,
+determined at compile time. Usually it is standard output or some
+physical tape drive attached to your machine (you can verify what the
+default is by running 'tar --show-defaults', *note defaults::). If
+there is no tape drive attached, or the default is not meaningful, then
+'tar' will print an error message. The error message might look roughly
+like one of the following:
+
+ tar: can't open /dev/rmt8 : No such device or address
+ tar: can't open /dev/rsmt0 : I/O error
+
+To avoid confusion, we recommend that you always specify an archive file
+name by using '--file=ARCHIVE-NAME' ('-f ARCHIVE-NAME') when writing
+your 'tar' commands. For more information on using the
+'--file=ARCHIVE-NAME' ('-f ARCHIVE-NAME') option, see *note file::.
+
+
+File: tar.info, Node: verbose tutorial, Next: help tutorial, Prev: file tutorial, Up: Two Frequent Options
+
+The '--verbose' Option
+----------------------
+
+'--verbose'
+'-v'
+ Show the files being worked on as 'tar' is running.
+
+ '--verbose' ('-v') shows details about the results of running 'tar'.
+This can be especially useful when the results might not be obvious.
+For example, if you want to see the progress of 'tar' as it writes files
+into the archive, you can use the '--verbose' option. In the beginning,
+you may find it useful to use '--verbose' at all times; when you are
+more accustomed to 'tar', you will likely want to use it at certain
+times but not at others. We will use '--verbose' at times to help make
+something clear, and we will give many examples both using and not using
+'--verbose' to show the differences.
+
+ Each instance of '--verbose' on the command line increases the
+verbosity level by one, so if you need more details on the output,
+specify it twice.
+
+ When reading archives ('--list', '--extract', '--diff'), 'tar' by
+default prints only the names of the members being extracted. Using
+'--verbose' will show a full, 'ls' style member listing.
+
+ In contrast, when writing archives ('--create', '--append',
+'--update'), 'tar' does not print file names by default. So, a single
+'--verbose' option shows the file names being added to the archive,
+while two '--verbose' options enable the full listing.
+
+ For example, to create an archive in verbose mode:
+
+ $ tar -cvf afiles.tar apple angst aspic
+ apple
+ angst
+ aspic
+
+Creating the same archive with the verbosity level 2 could give:
+
+ $ tar -cvvf afiles.tar apple angst aspic
+ -rw-r--r-- gray/staff 62373 2006-06-09 12:06 apple
+ -rw-r--r-- gray/staff 11481 2006-06-09 12:06 angst
+ -rw-r--r-- gray/staff 23152 2006-06-09 12:06 aspic
+
+This works equally well using short or long forms of options. Using
+long forms, you would simply write out the mnemonic form of the option
+twice, like this:
+
+ $ tar --create --verbose --verbose ...
+
+Note that you must double the hyphens properly each time.
+
+ Later in the tutorial, we will give examples using
+'--verbose --verbose'.
+
+ The full output consists of six fields:
+
+ * File type and permissions in symbolic form. These are displayed in
+ the same format as the first column of 'ls -l' output (*note
+ format=verbose: (fileutils)What information is listed.).
+
+ * Owner name and group separated by a slash character. If these data
+ are not available (for example, when listing a 'v7' format
+ archive), numeric ID values are printed instead.
+
+ * Size of the file, in bytes.
+
+ * File modification date in ISO 8601 format.
+
+ * File modification time.
+
+ * File name. If the name contains any special characters (white
+ space, newlines, etc.) these are displayed in an unambiguous form
+ using so called "quoting style". For the detailed discussion of
+ available styles and on how to use them, see *note quoting
+ styles::.
+
+ Depending on the file type, the name can be followed by some
+ additional information, described in the following table:
+
+ '-> LINK-NAME'
+ The file or archive member is a "symbolic link" and LINK-NAME
+ is the name of file it links to.
+
+ 'link to LINK-NAME'
+ The file or archive member is a "hard link" and LINK-NAME is
+ the name of file it links to.
+
+ '--Long Link--'
+ The archive member is an old GNU format long link. You will
+ normally not encounter this.
+
+ '--Long Name--'
+ The archive member is an old GNU format long name. You will
+ normally not encounter this.
+
+ '--Volume Header--'
+ The archive member is a GNU "volume header" (*note Tape
+ Files::).
+
+ '--Continued at byte N--'
+ Encountered only at the beginning of a multi-volume archive
+ (*note Using Multiple Tapes::). This archive member is a
+ continuation from the previous volume. The number N gives the
+ offset where the original file was split.
+
+ 'unknown file type C'
+ An archive member of unknown type. C is the type character
+ from the archive header. If you encounter such a message, it
+ means that either your archive contains proprietary member
+ types GNU 'tar' is not able to handle, or the archive is
+ corrupted.
+
+ For example, here is an archive listing containing most of the
+special suffixes explained above:
+
+ V--------- 0/0 1536 2006-06-09 13:07 MyVolume--Volume Header--
+ -rw-r--r-- gray/staff 456783 2006-06-09 12:06 aspic--Continued at byte 32456--
+ -rw-r--r-- gray/staff 62373 2006-06-09 12:06 apple
+ lrwxrwxrwx gray/staff 0 2006-06-09 13:01 angst -> apple
+ -rw-r--r-- gray/staff 35793 2006-06-09 12:06 blues
+ hrw-r--r-- gray/staff 0 2006-06-09 12:06 music link to blues
+
+
+
+File: tar.info, Node: help tutorial, Prev: verbose tutorial, Up: Two Frequent Options
+
+Getting Help: Using the '--help' Option
+---------------------------------------
+
+'--help'
+
+ The '--help' option to 'tar' prints out a very brief list of all
+ operations and option available for the current version of 'tar'
+ available on your system.
+
+
+File: tar.info, Node: create, Next: list, Prev: Two Frequent Options, Up: Tutorial
+
+2.6 How to Create Archives
+==========================
+
+One of the basic operations of 'tar' is '--create' ('-c'), which you use
+to create a 'tar' archive. We will explain '--create' first because, in
+order to learn about the other operations, you will find it useful to
+have an archive available to practice on.
+
+ To make this easier, in this section you will first create a
+directory containing three files. Then, we will show you how to create
+an _archive_ (inside the new directory). Both the directory, and the
+archive are specifically for you to practice on. The rest of this
+chapter and the next chapter will show many examples using this
+directory and the files you will create: some of those files may be
+other directories and other archives.
+
+ The three files you will archive in this example are called 'blues',
+'folk', and 'jazz'. The archive is called 'collection.tar'.
+
+ This section will proceed slowly, detailing how to use '--create' in
+'verbose' mode, and showing examples using both short and long forms.
+In the rest of the tutorial, and in the examples in the next chapter, we
+will proceed at a slightly quicker pace. This section moves more slowly
+to allow beginning users to understand how 'tar' works.
+
+* Menu:
+
+* prepare for examples::
+* Creating the archive::
+* create verbose::
+* short create::
+* create dir::
+
+
+File: tar.info, Node: prepare for examples, Next: Creating the archive, Up: create
+
+2.6.1 Preparing a Practice Directory for Examples
+-------------------------------------------------
+
+To follow along with this and future examples, create a new directory
+called 'practice' containing files called 'blues', 'folk' and 'jazz'.
+The files can contain any information you like: ideally, they should
+contain information which relates to their names, and be of different
+lengths. Our examples assume that 'practice' is a subdirectory of your
+home directory.
+
+ Now 'cd' to the directory named 'practice'; 'practice' is now your
+"working directory". (_Please note_: Although the full file name of
+this directory is '/HOMEDIR/practice', in our examples we will refer to
+this directory as 'practice'; the HOMEDIR is presumed.)
+
+ In general, you should check that the files to be archived exist
+where you think they do (in the working directory) by running 'ls'.
+Because you just created the directory and the files and have changed to
+that directory, you probably don't need to do that this time.
+
+ It is very important to make sure there isn't already a file in the
+working directory with the archive name you intend to use (in this case,
+'collection.tar'), or that you don't care about its contents. Whenever
+you use 'create', 'tar' will erase the current contents of the file
+named by '--file=ARCHIVE-NAME' ('-f ARCHIVE-NAME') if it exists. 'tar'
+will not tell you if you are about to overwrite an archive unless you
+specify an option which does this (*note backup::, for the information
+on how to do so). To add files to an existing archive, you need to use
+a different option, such as '--append' ('-r'); see *note append:: for
+information on how to do this.
+
+
+File: tar.info, Node: Creating the archive, Next: create verbose, Prev: prepare for examples, Up: create
+
+2.6.2 Creating the Archive
+--------------------------
+
+To place the files 'blues', 'folk', and 'jazz' into an archive named
+'collection.tar', use the following command:
+
+ $ tar --create --file=collection.tar blues folk jazz
+
+ The order of the arguments is not very important, _when using long
+option forms_, however you should always remember to use option as the
+first argument to tar. For example, the following is wrong:
+
+ $ tar blues -c folk -f collection.tar jazz
+ tar: -c: Invalid blocking factor
+ Try 'tar --help' or 'tar --usage' for more information.
+
+ The error message is produced because 'tar' always treats its first
+argument as an option (or cluster of options), even if it does not start
+with dash. This is "traditional" or "old option" style, called so
+because all implementations of 'tar' have used it since the very
+inception of the tar archiver in 1970s. This option style will be
+explained later (*note Old Options::), for now just remember to always
+place option as the first argument.
+
+ That being said, you could issue the following command:
+
+ $ tar --create folk blues --file=collection.tar jazz
+
+However, you can see that this order is harder to understand; this is
+why we will list the arguments in the order that makes the commands
+easiest to understand (and we encourage you to do the same when you use
+'tar', to avoid errors).
+
+ Note that the sequence '--file=collection.tar' is considered to be
+_one_ argument. If you substituted any other string of characters for
+'collection.tar', then that string would become the name of the archive
+file you create.
+
+ The order of the options becomes more important when you begin to use
+short forms. With short forms, if you type commands in the wrong order
+(even if you type them correctly in all other ways), you may end up with
+results you don't expect. For this reason, it is a good idea to get
+into the habit of typing options in the order that makes inherent sense.
+*Note short create::, for more information on this.
+
+ In this example, you type the command as shown above: '--create' is
+the operation which creates the new archive ('collection.tar'), and
+'--file' is the option which lets you give it the name you chose. The
+files, 'blues', 'folk', and 'jazz', are now members of the archive,
+'collection.tar' (they are "file name arguments" to the '--create'
+operation. *Note Choosing::, for the detailed discussion on these.)
+Now that they are in the archive, they are called _archive members_, not
+files. (*note members: Definitions.).
+
+ When you create an archive, you _must_ specify which files you want
+placed in the archive. If you do not specify any archive members, GNU
+'tar' will complain.
+
+ If you now list the contents of the working directory ('ls'), you
+will find the archive file listed as well as the files you saw
+previously:
+
+ blues folk jazz collection.tar
+
+Creating the archive 'collection.tar' did not destroy the copies of the
+files in the directory.
+
+ Keep in mind that if you don't indicate an operation, 'tar' will not
+run and will prompt you for one. If you don't name any files, 'tar'
+will complain. You must have write access to the working directory, or
+else you will not be able to create an archive in that directory.
+
+ _Caution_: Do not attempt to use '--create' ('-c') to add files to an
+existing archive; it will delete the archive and write a new one. Use
+'--append' ('-r') instead. *Note append::.
+
+
+File: tar.info, Node: create verbose, Next: short create, Prev: Creating the archive, Up: create
+
+2.6.3 Running '--create' with '--verbose'
+-----------------------------------------
+
+If you include the '--verbose' ('-v') option on the command line, 'tar'
+will list the files it is acting on as it is working. In verbose mode,
+the 'create' example above would appear as:
+
+ $ tar --create --verbose --file=collection.tar blues folk jazz
+ blues
+ folk
+ jazz
+
+ This example is just like the example we showed which did not use
+'--verbose', except that 'tar' generated the remaining lines.
+
+ In the rest of the examples in this chapter, we will frequently use
+'verbose' mode so we can show actions or 'tar' responses that you would
+otherwise not see, and which are important for you to understand.
+
+
+File: tar.info, Node: short create, Next: create dir, Prev: create verbose, Up: create
+
+2.6.4 Short Forms with 'create'
+-------------------------------
+
+As we said before, the '--create' ('-c') operation is one of the most
+basic uses of 'tar', and you will use it countless times. Eventually,
+you will probably want to use abbreviated (or "short") forms of options.
+A full discussion of the three different forms that options can take
+appears in *note Styles::; for now, here is what the previous example
+(including the '--verbose' ('-v') option) looks like using short option
+forms:
+
+ $ tar -cvf collection.tar blues folk jazz
+ blues
+ folk
+ jazz
+
+As you can see, the system responds the same no matter whether you use
+long or short option forms.
+
+ One difference between using short and long option forms is that,
+although the exact placement of arguments following options is no more
+specific when using short forms, it is easier to become confused and
+make a mistake when using short forms. For example, suppose you
+attempted the above example in the following way:
+
+ $ tar -cfv collection.tar blues folk jazz
+
+In this case, 'tar' will make an archive file called 'v', containing the
+files 'blues', 'folk', and 'jazz', because the 'v' is the closest "file
+name" to the '-f' option, and is thus taken to be the chosen archive
+file name. 'tar' will try to add a file called 'collection.tar' to the
+'v' archive file; if the file 'collection.tar' did not already exist,
+'tar' will report an error indicating that this file does not exist. If
+the file 'collection.tar' does already exist (e.g., from a previous
+command you may have run), then 'tar' will add this file to the archive.
+Because the '-v' option did not get registered, 'tar' will not run under
+'verbose' mode, and will not report its progress.
+
+ The end result is that you may be quite confused about what happened,
+and possibly overwrite a file. To illustrate this further, we will show
+you how an example we showed previously would look using short forms.
+
+ This example,
+
+ $ tar --create folk blues --file=collection.tar jazz
+
+is confusing as it is. It becomes even more so when using short forms:
+
+ $ tar -c folk blues -f collection.tar jazz
+
+It would be very easy to put the wrong string of characters immediately
+following the '-f', but doing that could sacrifice valuable data.
+
+ For this reason, we recommend that you pay very careful attention to
+the order of options and placement of file and archive names, especially
+when using short option forms. Not having the option name written out
+mnemonically can affect how well you remember which option does what,
+and therefore where different names have to be placed.
+
+
+File: tar.info, Node: create dir, Prev: short create, Up: create
+
+2.6.5 Archiving Directories
+---------------------------
+
+You can archive a directory by specifying its directory name as a file
+name argument to 'tar'. The files in the directory will be archived
+relative to the working directory, and the directory will be re-created
+along with its contents when the archive is extracted.
+
+ To archive a directory, first move to its superior directory. If you
+have followed the previous instructions in this tutorial, you should
+type:
+
+ $ cd ..
+ $
+
+This will put you into the directory which contains 'practice', i.e.,
+your home directory. Once in the superior directory, you can specify
+the subdirectory, 'practice', as a file name argument. To store
+'practice' in the new archive file 'music.tar', type:
+
+ $ tar --create --verbose --file=music.tar practice
+
+'tar' should output:
+
+ practice/
+ practice/blues
+ practice/folk
+ practice/jazz
+ practice/collection.tar
+
+ Note that the archive thus created is not in the subdirectory
+'practice', but rather in the current working directory--the directory
+from which 'tar' was invoked. Before trying to archive a directory from
+its superior directory, you should make sure you have write access to
+the superior directory itself, not only the directory you are trying
+archive with 'tar'. For example, you will probably not be able to store
+your home directory in an archive by invoking 'tar' from the root
+directory; *Note absolute::. (Note also that 'collection.tar', the
+original archive file, has itself been archived. 'tar' will accept any
+file as a file to be archived, regardless of its content. When
+'music.tar' is extracted, the archive file 'collection.tar' will be
+re-written into the file system).
+
+ If you give 'tar' a command such as
+
+ $ tar --create --file=foo.tar .
+
+'tar' will report 'tar: ./foo.tar is the archive; not dumped'. This
+happens because 'tar' creates the archive 'foo.tar' in the current
+directory before putting any files into it. Then, when 'tar' attempts
+to add all the files in the directory '.' to the archive, it notices
+that the file './foo.tar' is the same as the archive 'foo.tar', and
+skips it. (It makes no sense to put an archive into itself.) GNU 'tar'
+will continue in this case, and create the archive normally, except for
+the exclusion of that one file. (_Please note:_ Other implementations
+of 'tar' may not be so clever; they will enter an infinite loop when
+this happens, so you should not depend on this behavior unless you are
+certain you are running GNU 'tar'. In general, it is wise to always
+place the archive outside of the directory being dumped.)
+
+
+File: tar.info, Node: list, Next: extract, Prev: create, Up: Tutorial
+
+2.7 How to List Archives
+========================
+
+Frequently, you will find yourself wanting to determine exactly what a
+particular archive contains. You can use the '--list' ('-t') operation
+to get the member names as they currently appear in the archive, as well
+as various attributes of the files at the time they were archived. For
+example, assuming 'practice' is your working directory, you can examine
+the archive 'collection.tar' that you created in the last section with
+the command,
+
+ $ tar --list --file=collection.tar
+
+The output of 'tar' would then be:
+
+ blues
+ folk
+ jazz
+
+Be sure to use a '--file=ARCHIVE-NAME' ('-f ARCHIVE-NAME') option just
+as with '--create' ('-c') to specify the name of the archive.
+
+ You can specify one or more individual member names as arguments when
+using 'list'. In this case, 'tar' will only list the names of members
+you identify. For example, 'tar --list --file=collection.tar folk'
+would only print 'folk':
+
+ $ tar --list --file=collection.tar folk
+ folk
+
+ If you use the '--verbose' ('-v') option with '--list', then 'tar'
+will print out a listing reminiscent of 'ls -l', showing owner, file
+size, and so forth. This output is described in detail in *note verbose
+member listing::.
+
+ If you had used '--verbose' ('-v') mode, the example above would look
+like:
+
+ $ tar --list --verbose --file=collection.tar folk
+ -rw-r--r-- myself/user 62 1990-05-23 10:55 folk
+
+ It is important to notice that the output of 'tar --list --verbose'
+does not necessarily match that produced by 'tar --create --verbose'
+while creating the archive. It is because GNU 'tar', unless told
+explicitly not to do so, removes some directory prefixes from file names
+before storing them in the archive (*Note absolute::, for more
+information). In other words, in verbose mode GNU 'tar' shows "file
+names" when creating an archive and "member names" when listing it.
+Consider this example, run from your home directory:
+
+ $ tar --create --verbose --file practice.tar ~/practice
+ tar: Removing leading '/' from member names
+ /home/myself/practice/
+ /home/myself/practice/blues
+ /home/myself/practice/folk
+ /home/myself/practice/jazz
+ /home/myself/practice/collection.tar
+ $ tar --test --file practice.tar
+ home/myself/practice/
+ home/myself/practice/blues
+ home/myself/practice/folk
+ home/myself/practice/jazz
+ home/myself/practice/collection.tar
+
+ This default behavior can sometimes be inconvenient. You can force
+GNU 'tar' show member names when creating archive by supplying
+'--show-stored-names' option.
+
+'--show-stored-names'
+ Print member (as opposed to _file_) names when creating the
+ archive.
+
+ With this option, both commands produce the same output:
+
+ $ tar --create --verbose --show-stored-names \
+ --file practice.tar ~/practice
+ tar: Removing leading '/' from member names
+ home/myself/practice/
+ home/myself/practice/blues
+ home/myself/practice/folk
+ home/myself/practice/jazz
+ home/myself/practice/collection.tar
+ $ tar --test --file practice.tar
+ home/myself/practice/
+ home/myself/practice/blues
+ home/myself/practice/folk
+ home/myself/practice/jazz
+ home/myself/practice/collection.tar
+
+ Since 'tar' preserves file names, those you wish to list must be
+specified as they appear in the archive (i.e., relative to the directory
+from which the archive was created). Continuing the example above:
+
+ $ tar --list --file=practice.tar folk
+ tar: folk: Not found in archive
+ tar: Exiting with failure status due to previous errors
+
+ the error message is produced because there is no member named
+'folk', only one named 'home/myself/folk'.
+
+ If you are not sure of the exact file name, use "globbing patterns",
+for example:
+
+ $ tar --list --file=practice.tar --wildcards '*/folk'
+ home/myself/practice/folk
+
+*Note wildcards::, for a detailed discussion of globbing patterns and
+related 'tar' command line options.
+
+* Menu:
+
+* list dir::
+
+
+File: tar.info, Node: list dir, Up: list
+
+Listing the Contents of a Stored Directory
+------------------------------------------
+
+To get information about the contents of an archived directory, use the
+directory name as a file name argument in conjunction with '--list'
+('-t'). To find out file attributes, include the '--verbose' ('-v')
+option.
+
+ For example, to find out about files in the directory 'practice', in
+the archive file 'music.tar', type:
+
+ $ tar --list --verbose --file=music.tar practice
+
+ 'tar' responds:
+
+ drwxrwxrwx myself/user 0 1990-05-31 21:49 practice/
+ -rw-r--r-- myself/user 42 1990-05-21 13:29 practice/blues
+ -rw-r--r-- myself/user 62 1990-05-23 10:55 practice/folk
+ -rw-r--r-- myself/user 40 1990-05-21 13:30 practice/jazz
+ -rw-r--r-- myself/user 10240 1990-05-31 21:49 practice/collection.tar
+
+ When you use a directory name as a file name argument, 'tar' acts on
+all the files (including sub-directories) in that directory.
+
+
+File: tar.info, Node: extract, Next: going further, Prev: list, Up: Tutorial
+
+2.8 How to Extract Members from an Archive
+==========================================
+
+Creating an archive is only half the job--there is no point in storing
+files in an archive if you can't retrieve them. The act of retrieving
+members from an archive so they can be used and manipulated as
+unarchived files again is called "extraction". To extract files from an
+archive, use the '--extract' ('--get' or '-x') operation. As with
+'--create', specify the name of the archive with '--file' ('-f') option.
+Extracting an archive does not modify the archive in any way; you can
+extract it multiple times if you want or need to.
+
+ Using '--extract', you can extract an entire archive, or specific
+files. The files can be directories containing other files, or not. As
+with '--create' ('-c') and '--list' ('-t'), you may use the short or the
+long form of the operation without affecting the performance.
+
+* Menu:
+
+* extracting archives::
+* extracting files::
+* extract dir::
+* extracting untrusted archives::
+* failing commands::
+
+
+File: tar.info, Node: extracting archives, Next: extracting files, Up: extract
+
+2.8.1 Extracting an Entire Archive
+----------------------------------
+
+To extract an entire archive, specify the archive file name only, with
+no individual file names as arguments. For example,
+
+ $ tar -xvf collection.tar
+
+produces this:
+
+ -rw-r--r-- myself/user 28 1996-10-18 16:31 jazz
+ -rw-r--r-- myself/user 21 1996-09-23 16:44 blues
+ -rw-r--r-- myself/user 20 1996-09-23 16:44 folk
+
+
+File: tar.info, Node: extracting files, Next: extract dir, Prev: extracting archives, Up: extract
+
+2.8.2 Extracting Specific Files
+-------------------------------
+
+To extract specific archive members, give their exact member names as
+arguments, as printed by '--list' ('-t'). If you had mistakenly deleted
+one of the files you had placed in the archive 'collection.tar' earlier
+(say, 'blues'), you can extract it from the archive without changing the
+archive's structure. Its contents will be identical to the original
+file 'blues' that you deleted.
+
+ First, make sure you are in the 'practice' directory, and list the
+files in the directory. Now, delete the file, 'blues', and list the
+files in the directory again.
+
+ You can now extract the member 'blues' from the archive file
+'collection.tar' like this:
+
+ $ tar --extract --file=collection.tar blues
+
+If you list the files in the directory again, you will see that the file
+'blues' has been restored, with its original permissions, data
+modification times, and owner.(1) (These parameters will be identical
+to those which the file had when you originally placed it in the
+archive; any changes you may have made before deleting the file from the
+file system, however, will _not_ have been made to the archive member.)
+The archive file, 'collection.tar', is the same as it was before you
+extracted 'blues'. You can confirm this by running 'tar' with '--list'
+('-t').
+
+ Remember that as with other operations, specifying the exact member
+name is important (*Note failing commands::, for more examples).
+
+ You can extract a file to standard output by combining the above
+options with the '--to-stdout' ('-O') option (*note Writing to Standard
+Output::).
+
+ If you give the '--verbose' option, then '--extract' will print the
+names of the archive members as it extracts them.
+
+ ---------- Footnotes ----------
+
+ (1) This is only accidentally true, but not in general. Whereas
+modification times are always restored, in most cases, one has to be
+root for restoring the owner, and use a special option for restoring
+permissions. Here, it just happens that the restoring user is also the
+owner of the archived members, and that the current 'umask' is
+compatible with original permissions.
+
+
+File: tar.info, Node: extract dir, Next: extracting untrusted archives, Prev: extracting files, Up: extract
+
+2.8.3 Extracting Files that are Directories
+-------------------------------------------
+
+Extracting directories which are members of an archive is similar to
+extracting other files. The main difference to be aware of is that if
+the extracted directory has the same name as any directory already in
+the working directory, then files in the extracted directory will be
+placed into the directory of the same name. Likewise, if there are
+files in the pre-existing directory with the same names as the members
+which you extract, the files from the extracted archive will replace the
+files already in the working directory (and possible subdirectories).
+This will happen regardless of whether or not the files in the working
+directory were more recent than those extracted (there exist, however,
+special options that alter this behavior *note Writing::).
+
+ However, if a file was stored with a directory name as part of its
+file name, and that directory does not exist under the working directory
+when the file is extracted, 'tar' will create the directory.
+
+ We can demonstrate how to use '--extract' to extract a directory file
+with an example. Change to the 'practice' directory if you weren't
+there, and remove the files 'folk' and 'jazz'. Then, go back to the
+parent directory and extract the archive 'music.tar'. You may either
+extract the entire archive, or you may extract only the files you just
+deleted. To extract the entire archive, don't give any file names as
+arguments after the archive name 'music.tar'. To extract only the files
+you deleted, use the following command:
+
+ $ tar -xvf music.tar practice/folk practice/jazz
+ practice/folk
+ practice/jazz
+
+If you were to specify two '--verbose' ('-v') options, 'tar' would have
+displayed more detail about the extracted files, as shown in the example
+below:
+
+ $ tar -xvvf music.tar practice/folk practice/jazz
+ -rw-r--r-- me/user 28 1996-10-18 16:31 practice/jazz
+ -rw-r--r-- me/user 20 1996-09-23 16:44 practice/folk
+
+Because you created the directory with 'practice' as part of the file
+names of each of the files by archiving the 'practice' directory as
+'practice', you must give 'practice' as part of the file names when you
+extract those files from the archive.
+
+
+File: tar.info, Node: extracting untrusted archives, Next: failing commands, Prev: extract dir, Up: extract
+
+2.8.4 Extracting Archives from Untrusted Sources
+------------------------------------------------
+
+Extracting files from archives can overwrite files that already exist.
+If you receive an archive from an untrusted source, you should make a
+new directory and extract into that directory, so that you don't have to
+worry about the extraction overwriting one of your existing files. For
+example, if 'untrusted.tar' came from somewhere else on the Internet,
+and you don't necessarily trust its contents, you can extract it as
+follows:
+
+ $ mkdir newdir
+ $ cd newdir
+ $ tar -xvf ../untrusted.tar
+
+ It is also a good practice to examine contents of the archive before
+extracting it, using '--list' ('-t') option, possibly combined with
+'--verbose' ('-v').
+
+
+File: tar.info, Node: failing commands, Prev: extracting untrusted archives, Up: extract
+
+2.8.5 Commands That Will Fail
+-----------------------------
+
+Here are some sample commands you might try which will not work, and why
+they won't work.
+
+ If you try to use this command,
+
+ $ tar -xvf music.tar folk jazz
+
+you will get the following response:
+
+ tar: folk: Not found in archive
+ tar: jazz: Not found in archive
+
+This is because these files were not originally _in_ the parent
+directory '..', where the archive is located; they were in the
+'practice' directory, and their file names reflect this:
+
+ $ tar -tvf music.tar
+ practice/blues
+ practice/folk
+ practice/jazz
+
+Likewise, if you try to use this command,
+
+ $ tar -tvf music.tar folk jazz
+
+you would get a similar response. Members with those names are not in
+the archive. You must use the correct member names, or wildcards, in
+order to extract the files from the archive.
+
+ If you have forgotten the correct names of the files in the archive,
+use 'tar --list --verbose' to list them correctly.
+
+ To extract the member named 'practice/folk', you must specify
+
+ $ tar --extract --file=music.tar practice/folk
+
+Notice also, that as explained above, the 'practice' directory will be
+created, if it didn't already exist. There are options that allow you
+to strip away a certain number of leading directory components (*note
+transform::). For example,
+
+ $ tar --extract --file=music.tar --strip-components=1 folk
+
+will extract the file 'folk' into the current working directory.
+
+
+File: tar.info, Node: going further, Prev: extract, Up: Tutorial
+
+2.9 Going Further Ahead in this Manual
+======================================
+
+ _(This message will disappear, once this node revised.)_
+
+
+File: tar.info, Node: tar invocation, Next: operations, Prev: Tutorial, Up: Top
+
+3 Invoking GNU 'tar'
+********************
+
+This chapter is about how one invokes the GNU 'tar' command, from the
+command synopsis (*note Synopsis::). There are numerous options, and
+many styles for writing them. One mandatory option specifies the
+operation 'tar' should perform (*note Operation Summary::), other
+options are meant to detail how this operation should be performed
+(*note Option Summary::). Non-option arguments are not always
+interpreted the same way, depending on what the operation is.
+
+ You will find in this chapter everything about option styles and
+rules for writing them (*note Styles::). On the other hand, operations
+and options are fully described elsewhere, in other chapters. Here, you
+will find only synthetic descriptions for operations and options,
+together with pointers to other parts of the 'tar' manual.
+
+ Some options are so special they are fully described right in this
+chapter. They have the effect of inhibiting the normal operation of
+'tar' or else, they globally alter the amount of feedback the user
+receives about what is going on. These are the '--help' and '--version'
+(*note help::), '--verbose' (*note verbose::) and '--interactive'
+options (*note interactive::).
+
+* Menu:
+
+* Synopsis::
+* using tar options::
+* Styles::
+* All Options:: All 'tar' Options.
+* help:: Where to Get Help.
+* defaults:: What are the Default Values.
+* verbose:: Checking 'tar' progress.
+* checkpoints:: Checkpoints.
+* warnings:: Controlling Warning Messages.
+* interactive:: Asking for Confirmation During Operations.
+* external:: Running External Commands.
+
+
+File: tar.info, Node: Synopsis, Next: using tar options, Up: tar invocation
+
+3.1 General Synopsis of 'tar'
+=============================
+
+The GNU 'tar' program is invoked as either one of:
+
+ tar OPTION... [NAME]...
+ tar LETTER... [ARGUMENT]... [OPTION]... [NAME]...
+
+ The second form is for when old options are being used.
+
+ You can use 'tar' to store files in an archive, to extract them from
+an archive, and to do other types of archive manipulation. The primary
+argument to 'tar', which is called the "operation", specifies which
+action to take. The other arguments to 'tar' are either "options",
+which change the way 'tar' performs an operation, or file names or
+archive members, which specify the files or members 'tar' is to act on.
+
+ You can actually type in arguments in any order, even if in this
+manual the options always precede the other arguments, to make examples
+easier to understand. Further, the option stating the main operation
+mode (the 'tar' main command) is usually given first.
+
+ Each NAME in the synopsis above is interpreted as an archive member
+name when the main command is one of '--compare' ('--diff', '-d'),
+'--delete', '--extract' ('--get', '-x'), '--list' ('-t') or '--update'
+('-u'). When naming archive members, you must give the exact name of
+the member in the archive, as it is printed by '--list'. For '--append'
+('-r') and '--create' ('-c'), these NAME arguments specify the names of
+either files or directory hierarchies to place in the archive. These
+files or hierarchies should already exist in the file system, prior to
+the execution of the 'tar' command.
+
+ 'tar' interprets relative file names as being relative to the working
+directory. 'tar' will make all file names relative (by removing leading
+slashes when archiving or restoring files), unless you specify otherwise
+(using the '--absolute-names' option). *Note absolute::, for more
+information about '--absolute-names'.
+
+ If you give the name of a directory as either a file name or a member
+name, then 'tar' acts recursively on all the files and directories
+beneath that directory. For example, the name '/' identifies all the
+files in the file system to 'tar'.
+
+ The distinction between file names and archive member names is
+especially important when shell globbing is used, and sometimes a source
+of confusion for newcomers. *Note wildcards::, for more information
+about globbing. The problem is that shells may only glob using existing
+files in the file system. Only 'tar' itself may glob on archive
+members, so when needed, you must ensure that wildcard characters reach
+'tar' without being interpreted by the shell first. Using a backslash
+before '*' or '?', or putting the whole argument between quotes, is
+usually sufficient for this.
+
+ Even if NAMEs are often specified on the command line, they can also
+be read from a text file in the file system, using the
+'--files-from=FILE-OF-NAMES' ('-T FILE-OF-NAMES') option.
+
+ If you don't use any file name arguments, '--append' ('-r'),
+'--delete' and '--concatenate' ('--catenate', '-A') will do nothing,
+while '--create' ('-c') will usually yield a diagnostic and inhibit
+'tar' execution. The other operations of 'tar' ('--list', '--extract',
+'--compare', and '--update') will act on the entire contents of the
+archive.
+
+ Besides successful exits, GNU 'tar' may fail for many reasons. Some
+reasons correspond to bad usage, that is, when the 'tar' command line is
+improperly written. Errors may be encountered later, while processing
+the archive or the files. Some errors are recoverable, in which case
+the failure is delayed until 'tar' has completed all its work. Some
+errors are such that it would be not meaningful, or at least risky, to
+continue processing: 'tar' then aborts processing immediately. All
+abnormal exits, whether immediate or delayed, should always be clearly
+diagnosed on 'stderr', after a line stating the nature of the error.
+
+ Possible exit codes of GNU 'tar' are summarized in the following
+table:
+
+0
+ 'Successful termination'.
+
+1
+ 'Some files differ'. If tar was invoked with '--compare'
+ ('--diff', '-d') command line option, this means that some files in
+ the archive differ from their disk counterparts (*note compare::).
+ If tar was given '--create', '--append' or '--update' option, this
+ exit code means that some files were changed while being archived
+ and so the resulting archive does not contain the exact copy of the
+ file set.
+
+2
+ 'Fatal error'. This means that some fatal, unrecoverable error
+ occurred.
+
+ If 'tar' has invoked a subprocess and that subprocess exited with a
+nonzero exit code, 'tar' exits with that code as well. This can happen,
+for example, if 'tar' was given some compression option (*note gzip::)
+and the external compressor program failed. Another example is 'rmt'
+failure during backup to the remote device (*note Remote Tape Server::).
+
+
+File: tar.info, Node: using tar options, Next: Styles, Prev: Synopsis, Up: tar invocation
+
+3.2 Using 'tar' Options
+=======================
+
+GNU 'tar' has a total of eight operating modes which allow you to
+perform a variety of tasks. You are required to choose one operating
+mode each time you employ the 'tar' program by specifying one, and only
+one operation as an argument to the 'tar' command (the corresponding
+options may be found at *note frequent operations:: and *note
+Operations::). Depending on circumstances, you may also wish to
+customize how the chosen operating mode behaves. For example, you may
+wish to change the way the output looks, or the format of the files that
+you wish to archive may require you to do something special in order to
+make the archive look right.
+
+ You can customize and control 'tar''s performance by running 'tar'
+with one or more options (such as '--verbose' ('-v'), which we used in
+the tutorial). As we said in the tutorial, "options" are arguments to
+'tar' which are (as their name suggests) optional. Depending on the
+operating mode, you may specify one or more options. Different options
+will have different effects, but in general they all change details of
+the operation, such as archive format, archive name, or level of user
+interaction. Some options make sense with all operating modes, while
+others are meaningful only with particular modes. You will likely use
+some options frequently, while you will only use others infrequently, or
+not at all. (A full list of options is available in *note All
+Options::.)
+
+ The 'TAR_OPTIONS' environment variable specifies default options to
+be placed in front of any explicit options. For example, if
+'TAR_OPTIONS' is '-v --unlink-first', 'tar' behaves as if the two
+options '-v' and '--unlink-first' had been specified before any explicit
+options. Option specifications are separated by whitespace. A
+backslash escapes the next character, so it can be used to specify an
+option containing whitespace or a backslash.
+
+ Note that 'tar' options are case sensitive. For example, the options
+'-T' and '-t' are different; the first requires an argument for stating
+the name of a file providing a list of NAMEs, while the second does not
+require an argument and is another way to write '--list' ('-t').
+
+ In addition to the eight operations, there are many options to 'tar',
+and three different styles for writing both: long (mnemonic) form, short
+form, and old style. These styles are discussed below. Both the
+options and the operations can be written in any of these three styles.
+
+
+File: tar.info, Node: Styles, Next: All Options, Prev: using tar options, Up: tar invocation
+
+3.3 The Three Option Styles
+===========================
+
+There are three styles for writing operations and options to the command
+line invoking 'tar'. The different styles were developed at different
+times during the history of 'tar'. These styles will be presented
+below, from the most recent to the oldest.
+
+ Some options must take an argument(1). Where you _place_ the
+arguments generally depends on which style of options you choose. We
+will detail specific information relevant to each option style in the
+sections on the different option styles, below. The differences are
+subtle, yet can often be very important; incorrect option placement can
+cause you to overwrite a number of important files. We urge you to note
+these differences, and only use the option style(s) which makes the most
+sense to you until you feel comfortable with the others.
+
+ Some options _may_ take an argument. Such options may have at most
+long and short forms, they do not have old style equivalent. The rules
+for specifying an argument for such options are stricter than those for
+specifying mandatory arguments. Please, pay special attention to them.
+
+* Menu:
+
+* Long Options:: Long Option Style
+* Short Options:: Short Option Style
+* Old Options:: Old Option Style
+* Mixing:: Mixing Option Styles
+
+ ---------- Footnotes ----------
+
+ (1) For example, '--file' ('-f') takes the name of an archive file as
+an argument. If you do not supply an archive file name, 'tar' will use
+a default, but this can be confusing; thus, we recommend that you always
+supply a specific archive file name.
+
+
+File: tar.info, Node: Long Options, Next: Short Options, Up: Styles
+
+3.3.1 Long Option Style
+-----------------------
+
+Each option has at least one "long" (or "mnemonic") name starting with
+two dashes in a row, e.g., '--list'. The long names are more clear than
+their corresponding short or old names. It sometimes happens that a
+single long option has many different names which are synonymous, such
+as '--compare' and '--diff'. In addition, long option names can be
+given unique abbreviations. For example, '--cre' can be used in place
+of '--create' because there is no other long option which begins with
+'cre'. (One way to find this out is by trying it and seeing what
+happens; if a particular abbreviation could represent more than one
+option, 'tar' will tell you that that abbreviation is ambiguous and
+you'll know that that abbreviation won't work. You may also choose to
+run 'tar --help' to see a list of options. Be aware that if you run
+'tar' with a unique abbreviation for the long name of an option you
+didn't want to use, you are stuck; 'tar' will perform the command as
+ordered.)
+
+ Long options are meant to be obvious and easy to remember, and their
+meanings are generally easier to discern than those of their
+corresponding short options (see below). For example:
+
+ $ tar --create --verbose --blocking-factor=20 --file=/dev/rmt0
+
+gives a fairly good set of hints about what the command does, even for
+those not fully acquainted with 'tar'.
+
+ Long options which require arguments take those arguments immediately
+following the option name. There are two ways of specifying a mandatory
+argument. It can be separated from the option name either by an equal
+sign, or by any amount of white space characters. For example, the
+'--file' option (which tells the name of the 'tar' archive) is given a
+file such as 'archive.tar' as argument by using any of the following
+notations: '--file=archive.tar' or '--file archive.tar'.
+
+ In contrast, optional arguments must always be introduced using an
+equal sign. For example, the '--backup' option takes an optional
+argument specifying backup type. It must be used as
+'--backup=BACKUP-TYPE'.
+
+
+File: tar.info, Node: Short Options, Next: Old Options, Prev: Long Options, Up: Styles
+
+3.3.2 Short Option Style
+------------------------
+
+Most options also have a "short option" name. Short options start with
+a single dash, and are followed by a single character, e.g., '-t' (which
+is equivalent to '--list'). The forms are absolutely identical in
+function; they are interchangeable.
+
+ The short option names are faster to type than long option names.
+
+ Short options which require arguments take their arguments
+immediately following the option, usually separated by white space. It
+is also possible to stick the argument right after the short option
+name, using no intervening space. For example, you might write
+'-f archive.tar' or '-farchive.tar' instead of using
+'--file=archive.tar'. Both '--file=ARCHIVE-NAME' and '-f ARCHIVE-NAME'
+denote the option which indicates a specific archive, here named
+'archive.tar'.
+
+ Short options which take optional arguments take their arguments
+immediately following the option letter, _without any intervening white
+space characters_.
+
+ Short options' letters may be clumped together, but you are not
+required to do this (as compared to old options; see below). When short
+options are clumped as a set, use one (single) dash for them all, e.g.,
+''tar' -cvf'. Only the last option in such a set is allowed to have an
+argument(1).
+
+ When the options are separated, the argument for each option which
+requires an argument directly follows that option, as is usual for Unix
+programs. For example:
+
+ $ tar -c -v -b 20 -f /dev/rmt0
+
+ If you reorder short options' locations, be sure to move any
+arguments that belong to them. If you do not move the arguments
+properly, you may end up overwriting files.
+
+ ---------- Footnotes ----------
+
+ (1) Clustering many options, the last of which has an argument, is a
+rather opaque way to write options. Some wonder if GNU 'getopt' should
+not even be made helpful enough for considering such usages as invalid.
+
+
+File: tar.info, Node: Old Options, Next: Mixing, Prev: Short Options, Up: Styles
+
+3.3.3 Old Option Style
+----------------------
+
+As far as we know, all 'tar' programs, GNU and non-GNU, support "old
+options": that is, if the first argument does not start with '-', it is
+assumed to specify option letters. GNU 'tar' supports old options not
+only for historical reasons, but also because many people are used to
+them. If the first argument does not start with a dash, you are
+announcing the old option style instead of the short option style; old
+options are decoded differently.
+
+ Like short options, old options are single letters. However, old
+options must be written together as a single clumped set, without spaces
+separating them or dashes preceding them. This set of letters must be
+the first to appear on the command line, after the 'tar' program name
+and some white space; old options cannot appear anywhere else. The
+letter of an old option is exactly the same letter as the corresponding
+short option. For example, the old option 't' is the same as the short
+option '-t', and consequently, the same as the long option '--list'. So
+for example, the command 'tar cv' specifies the option '-v' in addition
+to the operation '-c'.
+
+ When options that need arguments are given together with the command,
+all the associated arguments follow, in the same order as the options.
+Thus, the example given previously could also be written in the old
+style as follows:
+
+ $ tar cvbf 20 /dev/rmt0
+
+Here, '20' is the argument of '-b' and '/dev/rmt0' is the argument of
+'-f'.
+
+ The old style syntax can make it difficult to match option letters
+with their corresponding arguments, and is often confusing. In the
+command 'tar cvbf 20 /dev/rmt0', for example, '20' is the argument for
+'-b', '/dev/rmt0' is the argument for '-f', and '-v' does not have a
+corresponding argument. Even using short options like in
+'tar -c -v -b 20 -f /dev/rmt0' is clearer, putting all arguments next to
+the option they pertain to.
+
+ If you want to reorder the letters in the old option argument, be
+sure to reorder any corresponding argument appropriately.
+
+ This old way of writing 'tar' options can surprise even experienced
+users. For example, the two commands:
+
+ tar cfz archive.tar.gz file
+ tar -cfz archive.tar.gz file
+
+are quite different. The first example uses 'archive.tar.gz' as the
+value for option 'f' and recognizes the option 'z'. The second example,
+however, uses 'z' as the value for option 'f' -- probably not what was
+intended.
+
+ This second example could be corrected in many ways, among which the
+following are equivalent:
+
+ tar -czf archive.tar.gz file
+ tar -cf archive.tar.gz -z file
+ tar cf archive.tar.gz -z file
+
+
+File: tar.info, Node: Mixing, Prev: Old Options, Up: Styles
+
+3.3.4 Mixing Option Styles
+--------------------------
+
+All three styles may be intermixed in a single 'tar' command, so long as
+the rules for each style are fully respected(1). Old style options and
+either of the modern styles of options may be mixed within a single
+'tar' command. However, old style options must be introduced as the
+first arguments only, following the rule for old options (old options
+must appear directly after the 'tar' command and some white space).
+Modern options may be given only after all arguments to the old options
+have been collected. If this rule is not respected, a modern option
+might be falsely interpreted as the value of the argument to one of the
+old style options.
+
+ For example, all the following commands are wholly equivalent, and
+illustrate the many combinations and orderings of option styles.
+
+ tar --create --file=archive.tar
+ tar --create -f archive.tar
+ tar --create -farchive.tar
+ tar --file=archive.tar --create
+ tar --file=archive.tar -c
+ tar -c --file=archive.tar
+ tar -c -f archive.tar
+ tar -c -farchive.tar
+ tar -cf archive.tar
+ tar -cfarchive.tar
+ tar -f archive.tar --create
+ tar -f archive.tar -c
+ tar -farchive.tar --create
+ tar -farchive.tar -c
+ tar c --file=archive.tar
+ tar c -f archive.tar
+ tar c -farchive.tar
+ tar cf archive.tar
+ tar f archive.tar --create
+ tar f archive.tar -c
+ tar fc archive.tar
+
+ On the other hand, the following commands are _not_ equivalent to the
+previous set:
+
+ tar -f -c archive.tar
+ tar -fc archive.tar
+ tar -fcarchive.tar
+ tar -farchive.tarc
+ tar cfarchive.tar
+
+These last examples mean something completely different from what the
+user intended (judging based on the example in the previous set which
+uses long options, whose intent is therefore very clear). The first
+four specify that the 'tar' archive would be a file named '-c', 'c',
+'carchive.tar' or 'archive.tarc', respectively. The first two examples
+also specify a single non-option, NAME argument having the value
+'archive.tar'. The last example contains only old style option letters
+(repeating option 'c' twice), not all of which are meaningful (eg., '.',
+'h', or 'i'), with no argument value.
+
+ ---------- Footnotes ----------
+
+ (1) Before GNU 'tar' version 1.11.6, a bug prevented intermixing old
+style options with long options in some cases.
+
+
+File: tar.info, Node: All Options, Next: help, Prev: Styles, Up: tar invocation
+
+3.4 All 'tar' Options
+=====================
+
+The coming manual sections contain an alphabetical listing of all 'tar'
+operations and options, with brief descriptions and cross-references to
+more in-depth explanations in the body of the manual. They also contain
+an alphabetically arranged table of the short option forms with their
+corresponding long option. You can use this table as a reference for
+deciphering 'tar' commands in scripts.
+
+* Menu:
+
+* Operation Summary::
+* Option Summary::
+* Short Option Summary::
+* Position-Sensitive Options::
+
+
+File: tar.info, Node: Operation Summary, Next: Option Summary, Up: All Options
+
+3.4.1 Operations
+----------------
+
+'--append'
+'-r'
+
+ Appends files to the end of the archive. *Note append::.
+
+'--catenate'
+'-A'
+
+ Same as '--concatenate'. *Note concatenate::.
+
+'--compare'
+'-d'
+
+ Compares archive members with their counterparts in the file
+ system, and reports differences in file size, mode, owner,
+ modification date and contents. *Note compare::.
+
+'--concatenate'
+'-A'
+
+ Appends other 'tar' archives to the end of the archive. *Note
+ concatenate::.
+
+'--create'
+'-c'
+
+ Creates a new 'tar' archive. *Note create::.
+
+'--delete'
+
+ Deletes members from the archive. Don't try this on an archive on
+ a tape! *Note delete::.
+
+'--diff'
+'-d'
+
+ Same '--compare'. *Note compare::.
+
+'--extract'
+'-x'
+
+ Extracts members from the archive into the file system. *Note
+ extract::.
+
+'--get'
+'-x'
+
+ Same as '--extract'. *Note extract::.
+
+'--list'
+'-t'
+
+ Lists the members in an archive. *Note list::.
+
+'--update'
+'-u'
+
+ Adds files to the end of the archive, but only if they are newer
+ than their counterparts already in the archive, or if they do not
+ already exist in the archive. *Note update::.
+
+
+File: tar.info, Node: Option Summary, Next: Short Option Summary, Prev: Operation Summary, Up: All Options
+
+3.4.2 'tar' Options
+-------------------
+
+'--absolute-names'
+'-P'
+
+ Normally when creating an archive, 'tar' strips an initial '/' from
+ member names, and when extracting from an archive 'tar' treats
+ names specially if they have initial '/' or internal '..'. This
+ option disables that behavior. *Note absolute::.
+
+'--acls'
+ Enable POSIX ACLs support. *Note acls: Extended File Attributes.
+
+'--after-date'
+
+ (See '--newer', *note after::)
+
+'--anchored'
+ A pattern must match an initial subsequence of the name's
+ components. *Note controlling pattern-matching::.
+
+'--atime-preserve'
+'--atime-preserve=replace'
+'--atime-preserve=system'
+
+ Attempt to preserve the access time of files when reading them.
+ This option currently is effective only on files that you own,
+ unless you have superuser privileges.
+
+ '--atime-preserve=replace' remembers the access time of a file
+ before reading it, and then restores the access time afterwards.
+ This may cause problems if other programs are reading the file at
+ the same time, as the times of their accesses will be lost. On
+ most platforms restoring the access time also requires 'tar' to
+ restore the data modification time too, so this option may also
+ cause problems if other programs are writing the file at the same
+ time ('tar' attempts to detect this situation, but cannot do so
+ reliably due to race conditions). Worse, on most platforms
+ restoring the access time also updates the status change time,
+ which means that this option is incompatible with incremental
+ backups.
+
+ '--atime-preserve=system' avoids changing time stamps on files,
+ without interfering with time stamp updates caused by other
+ programs, so it works better with incremental backups. However, it
+ requires a special 'O_NOATIME' option from the underlying operating
+ and file system implementation, and it also requires that searching
+ directories does not update their access times. As of this writing
+ (November 2005) this works only with Linux, and only with Linux
+ kernels 2.6.8 and later. Worse, there is currently no reliable way
+ to know whether this feature actually works. Sometimes 'tar' knows
+ that it does not work, and if you use '--atime-preserve=system'
+ then 'tar' complains and exits right away. But other times 'tar'
+ might think that the option works when it actually does not.
+
+ Currently '--atime-preserve' with no operand defaults to
+ '--atime-preserve=replace', but this may change in the future as
+ support for '--atime-preserve=system' improves.
+
+ If your operating or file system does not support
+ '--atime-preserve=system', you might be able to preserve access
+ times reliably by using the 'mount' command. For example, you can
+ mount the file system read-only, or access the file system via a
+ read-only loopback mount, or use the 'noatime' mount option
+ available on some systems. However, mounting typically requires
+ superuser privileges and can be a pain to manage.
+
+'--auto-compress'
+'-a'
+
+ During a '--create' operation, enables automatic compressed format
+ recognition based on the archive suffix. The effect of this option
+ is cancelled by '--no-auto-compress'. *Note gzip::.
+
+'--backup=BACKUP-TYPE'
+
+ Rather than deleting files from the file system, 'tar' will back
+ them up using simple or numbered backups, depending upon
+ BACKUP-TYPE. *Note backup::.
+
+'--block-number'
+'-R'
+
+ With this option present, 'tar' prints error messages for read
+ errors with the block number in the archive file. *Note
+ block-number::.
+
+'--blocking-factor=BLOCKING'
+'-b BLOCKING'
+
+ Sets the blocking factor 'tar' uses to BLOCKING x 512 bytes per
+ record. *Note Blocking Factor::.
+
+'--bzip2'
+'-j'
+
+ This option tells 'tar' to read or write archives through 'bzip2'.
+ *Note gzip::.
+
+'--check-device'
+ Check device numbers when creating a list of modified files for
+ incremental archiving. This is the default. *Note device
+ numbers::, for a detailed description.
+
+'--checkpoint[=NUMBER]'
+
+ This option directs 'tar' to print periodic checkpoint messages as
+ it reads through the archive. It is intended for when you want a
+ visual indication that 'tar' is still running, but don't want to
+ see '--verbose' output. You can also instruct 'tar' to execute a
+ list of actions on each checkpoint, see '--checkpoint-action'
+ below. For a detailed description, see *note checkpoints::.
+
+'--checkpoint-action=ACTION'
+ Instruct 'tar' to execute an action upon hitting a breakpoint.
+ Here we give only a brief outline. *Note checkpoints::, for a
+ complete description.
+
+ The ACTION argument can be one of the following:
+
+ bell
+ Produce an audible bell on the console.
+
+ dot
+ .
+ Print a single dot on the standard listing stream.
+
+ echo
+ Display a textual message on the standard error, with the
+ status and number of the checkpoint. This is the default.
+
+ echo=STRING
+ Display STRING on the standard error. Before output, the
+ string is subject to meta-character expansion.
+
+ exec=COMMAND
+ Execute the given COMMAND.
+
+ sleep=TIME
+ Wait for TIME seconds.
+
+ ttyout=STRING
+ Output STRING on the current console ('/dev/tty').
+
+ Several '--checkpoint-action' options can be specified. The
+ supplied actions will be executed in order of their appearance in
+ the command line.
+
+ Using '--checkpoint-action' without '--checkpoint' assumes default
+ checkpoint frequency of one checkpoint per 10 records.
+
+'--check-links'
+'-l'
+ If this option was given, 'tar' will check the number of links
+ dumped for each processed file. If this number does not match the
+ total number of hard links for the file, a warning message will be
+ output (1).
+
+ *Note hard links::.
+
+'--compress'
+'--uncompress'
+'-Z'
+
+ 'tar' will use the 'compress' program when reading or writing the
+ archive. This allows you to directly act on archives while saving
+ space. *Note gzip::.
+
+'--clamp-mtime'
+
+ (See '--mtime'.)
+
+'--confirmation'
+
+ (See '--interactive'.) *Note interactive::.
+
+'--delay-directory-restore'
+
+ Delay setting modification times and permissions of extracted
+ directories until the end of extraction. *Note Directory
+ Modification Times and Permissions::.
+
+'--dereference'
+'-h'
+
+ When reading or writing a file to be archived, 'tar' accesses the
+ file that a symbolic link points to, rather than the symlink
+ itself. *Note dereference::.
+
+'--directory=DIR'
+'-C DIR'
+
+ When this option is specified, 'tar' will change its current
+ directory to DIR before performing any operations. When this
+ option is used during archive creation, it is order sensitive.
+ *Note directory::.
+
+'--exclude=PATTERN'
+
+ When performing operations, 'tar' will skip files that match
+ PATTERN. *Note exclude::.
+
+'--exclude-backups'
+ Exclude backup and lock files. *Note exclude-backups: exclude.
+
+'--exclude-from=FILE'
+'-X FILE'
+
+ Similar to '--exclude', except 'tar' will use the list of patterns
+ in the file FILE. *Note exclude::.
+
+'--exclude-caches'
+
+ Exclude from dump any directory containing a valid cache directory
+ tag file, but still dump the directory node and the tag file
+ itself.
+
+ *Note exclude-caches: exclude.
+
+'--exclude-caches-under'
+
+ Exclude from dump any directory containing a valid cache directory
+ tag file, but still dump the directory node itself.
+
+ *Note exclude::.
+
+'--exclude-caches-all'
+
+ Exclude from dump any directory containing a valid cache directory
+ tag file. *Note exclude::.
+
+'--exclude-ignore=FILE'
+ Before dumping a directory, 'tar' checks if it contains FILE. If
+ so, exclusion patterns are read from this file. The patterns
+ affect only the directory itself. *Note exclude::.
+
+'--exclude-ignore-recursive=FILE'
+ Before dumping a directory, 'tar' checks if it contains FILE. If
+ so, exclusion patterns are read from this file. The patterns
+ affect the directory and all itssubdirectories. *Note exclude::.
+
+'--exclude-tag=FILE'
+
+ Exclude from dump any directory containing file named FILE, but
+ dump the directory node and FILE itself. *Note exclude-tag:
+ exclude.
+
+'--exclude-tag-under=FILE'
+
+ Exclude from dump the contents of any directory containing file
+ named FILE, but dump the directory node itself. *Note
+ exclude-tag-under: exclude.
+
+'--exclude-tag-all=FILE'
+
+ Exclude from dump any directory containing file named FILE. *Note
+ exclude-tag-all: exclude.
+
+'--exclude-vcs'
+
+ Exclude from dump directories and files, that are internal for some
+ widely used version control systems.
+
+ *Note exclude-vcs::.
+
+'--exclude-vcs-ignores'
+ Exclude files that match patterns read from VCS-specific ignore
+ files. Supported files are: '.cvsignore', '.gitignore',
+ '.bzrignore', and '.hgignore'. The semantics of each file is the
+ same as for the corresponding VCS, e.g. patterns read from
+ '.gitignore' affect the directory and all its subdirectories.
+ *Note exclude-vcs-ignores::.
+
+'--file=ARCHIVE'
+'-f ARCHIVE'
+
+ 'tar' will use the file ARCHIVE as the 'tar' archive it performs
+ operations on, rather than 'tar''s compilation dependent default.
+ *Note file tutorial::.
+
+'--files-from=FILE'
+'-T FILE'
+
+ 'tar' will use the contents of FILE as a list of archive members or
+ files to operate on, in addition to those specified on the
+ command-line. *Note files::.
+
+'--force-local'
+
+ Forces 'tar' to interpret the file name given to '--file' as a
+ local file, even if it looks like a remote tape drive name. *Note
+ local and remote archives::.
+
+'--format=FORMAT'
+'-H FORMAT'
+
+ Selects output archive format. FORMAT may be one of the following:
+
+ 'v7'
+ Creates an archive that is compatible with Unix V7 'tar'.
+
+ 'oldgnu'
+ Creates an archive that is compatible with GNU 'tar' version
+ 1.12 or earlier.
+
+ 'gnu'
+ Creates archive in GNU tar 1.13 format. Basically it is the
+ same as 'oldgnu' with the only difference in the way it
+ handles long numeric fields.
+
+ 'ustar'
+ Creates a POSIX.1-1988 compatible archive.
+
+ 'posix'
+ Creates a POSIX.1-2001 archive.
+
+ *Note Formats::, for a detailed discussion of these formats.
+
+'--full-time'
+ This option instructs 'tar' to print file times to their full
+ resolution. Usually this means 1-second resolution, but that
+ depends on the underlying file system. The '--full-time' option
+ takes effect only when detailed output (verbosity level 2 or
+ higher) has been requested using the '--verbose' option, e.g., when
+ listing or extracting archives:
+
+ $ tar -t -v --full-time -f archive.tar
+
+ or, when creating an archive:
+
+ $ tar -c -vv --full-time -f archive.tar .
+
+ Notice, thar when creating the archive you need to specify
+ '--verbose' twice to get a detailed output (*note verbose
+ tutorial::).
+
+'--group=GROUP'
+
+ Files added to the 'tar' archive will have a group ID of GROUP,
+ rather than the group from the source file. GROUP can specify a
+ symbolic name, or a numeric ID, or both as NAME:ID. *Note
+ override::.
+
+ Also see the '--group-map' option and comments for the
+ '--owner=USER' option.
+
+'--group-map=FILE'
+
+ Read owner group translation map from FILE. This option allows to
+ translate only certain group names and/or UIDs. *Note override::,
+ for a detailed description. When used together with '--group'
+ option, the latter affects only those files whose owner group is
+ not listed in the FILE.
+
+ This option does not affect extraction from archives.
+
+'--gzip'
+'--gunzip'
+'--ungzip'
+'-z'
+
+ This option tells 'tar' to read or write archives through 'gzip',
+ allowing 'tar' to directly operate on several kinds of compressed
+ archives transparently. *Note gzip::.
+
+'--hard-dereference'
+ When creating an archive, dereference hard links and store the
+ files they refer to, instead of creating usual hard link members.
+
+ *Note hard links::.
+
+'--help'
+'-?'
+
+ 'tar' will print out a short message summarizing the operations and
+ options to 'tar' and exit. *Note help::.
+
+'--hole-detection=METHOD'
+ Use METHOD to detect holes in sparse files. This option implies
+ '--sparse'. Valid methods are 'seek' and 'raw'. Default is 'seek'
+ with fallback to 'raw' when not applicable. *Note sparse::.
+
+'--ignore-case'
+ Ignore case when matching member or file names with patterns.
+ *Note controlling pattern-matching::.
+
+'--ignore-command-error'
+ Ignore exit codes of subprocesses. *Note Writing to an External
+ Program::.
+
+'--ignore-failed-read'
+
+ Do not exit unsuccessfully merely because an unreadable file was
+ encountered. *Note Ignore Failed Read::.
+
+'--ignore-zeros'
+'-i'
+
+ With this option, 'tar' will ignore zeroed blocks in the archive,
+ which normally signals EOF. *Note Reading::.
+
+'--incremental'
+'-G'
+
+ Informs 'tar' that it is working with an old GNU-format incremental
+ backup archive. It is intended primarily for backwards
+ compatibility only. *Note Incremental Dumps::, for a detailed
+ discussion of incremental archives.
+
+'--index-file=FILE'
+
+ Send verbose output to FILE instead of to standard output.
+
+'--info-script=COMMAND'
+'--new-volume-script=COMMAND'
+'-F COMMAND'
+
+ When 'tar' is performing multi-tape backups, COMMAND is run at the
+ end of each tape. If it exits with nonzero status, 'tar' fails
+ immediately. *Note info-script::, for a detailed discussion of
+ this feature.
+
+'--interactive'
+'--confirmation'
+'-w'
+
+ Specifies that 'tar' should ask the user for confirmation before
+ performing potentially destructive options, such as overwriting
+ files. *Note interactive::.
+
+'--keep-directory-symlink'
+
+ This option changes the behavior of tar when it encounters a
+ symlink with the same name as the directory that it is about to
+ extract. By default, in this case tar would first remove the
+ symlink and then proceed extracting the directory.
+
+ The '--keep-directory-symlink' option disables this behavior and
+ instructs tar to follow symlinks to directories when extracting
+ from the archive.
+
+ It is mainly intended to provide compatibility with the Slackware
+ installation scripts.
+
+'--keep-newer-files'
+
+ Do not replace existing files that are newer than their archive
+ copies when extracting files from an archive.
+
+'--keep-old-files'
+'-k'
+
+ Do not overwrite existing files when extracting files from an
+ archive. Return error if such files exist. See also *note
+ --skip-old-files::.
+
+ *Note Keep Old Files::.
+
+'--label=NAME'
+'-V NAME'
+
+ When creating an archive, instructs 'tar' to write NAME as a name
+ record in the archive. When extracting or listing archives, 'tar'
+ will only operate on archives that have a label matching the
+ pattern specified in NAME. *Note Tape Files::.
+
+'--level=N'
+ Force incremental backup of level N. As of GNU 'tar' version 1.29,
+ the option '--level=0' truncates the snapshot file, thereby forcing
+ the level 0 dump. Other values of N are effectively ignored.
+ *Note --level=0::, for details and examples.
+
+ The use of this option is valid only in conjunction with the
+ '--listed-incremental' option. *Note Incremental Dumps::, for a
+ detailed description.
+
+'--listed-incremental=SNAPSHOT-FILE'
+'-g SNAPSHOT-FILE'
+
+ During a '--create' operation, specifies that the archive that
+ 'tar' creates is a new GNU-format incremental backup, using
+ SNAPSHOT-FILE to determine which files to backup. With other
+ operations, informs 'tar' that the archive is in incremental
+ format. *Note Incremental Dumps::.
+
+'--lzip'
+
+ This option tells 'tar' to read or write archives through 'lzip'.
+ *Note gzip::.
+
+'--lzma'
+
+ This option tells 'tar' to read or write archives through 'lzma'.
+ *Note gzip::.
+
+'--lzop'
+
+ This option tells 'tar' to read or write archives through 'lzop'.
+ *Note gzip::.
+
+'--mode=PERMISSIONS'
+
+ When adding files to an archive, 'tar' will use PERMISSIONS for the
+ archive members, rather than the permissions from the files.
+ PERMISSIONS can be specified either as an octal number or as
+ symbolic permissions, like with 'chmod'. *Note override::.
+
+'--mtime=DATE'
+
+ When adding files to an archive, 'tar' will use DATE as the
+ modification time of members when creating archives, instead of
+ their actual modification times. The value of DATE can be either a
+ textual date representation (*note Date input formats::) or a name
+ of the existing file, starting with '/' or '.'. In the latter
+ case, the modification time of that file is used. *Note
+ override::.
+
+ When '--clamp-mtime' is also specified, files with modification
+ times earlier than DATE will retain their actual modification
+ times, and DATE will only be used for files whose modification
+ times are later than DATE.
+
+'--multi-volume'
+'-M'
+
+ Informs 'tar' that it should create or otherwise operate on a
+ multi-volume 'tar' archive. *Note Using Multiple Tapes::.
+
+'--new-volume-script'
+
+ (see '--info-script')
+
+'--newer=DATE'
+'--after-date=DATE'
+'-N'
+
+ When creating an archive, 'tar' will only add files that have
+ changed since DATE. If DATE begins with '/' or '.', it is taken to
+ be the name of a file whose data modification time specifies the
+ date. *Note after::.
+
+'--newer-mtime=DATE'
+
+ Like '--newer', but add only files whose contents have changed (as
+ opposed to just '--newer', which will also back up files for which
+ any status information has changed). *Note after::.
+
+'--no-acls'
+ Disable the POSIX ACLs support. *Note acls: Extended File
+ Attributes.
+
+'--no-anchored'
+ An exclude pattern can match any subsequence of the name's
+ components. *Note controlling pattern-matching::.
+
+'--no-auto-compress'
+
+ Disables automatic compressed format recognition based on the
+ archive suffix. *Note --auto-compress::. *Note gzip::.
+
+'--no-check-device'
+ Do not check device numbers when creating a list of modified files
+ for incremental archiving. *Note device numbers::, for a detailed
+ description.
+
+'--no-delay-directory-restore'
+
+ Modification times and permissions of extracted directories are set
+ when all files from this directory have been extracted. This is
+ the default. *Note Directory Modification Times and Permissions::.
+
+'--no-ignore-case'
+ Use case-sensitive matching. *Note controlling pattern-matching::.
+
+'--no-ignore-command-error'
+ Print warnings about subprocesses that terminated with a nonzero
+ exit code. *Note Writing to an External Program::.
+
+'--no-null'
+
+ If the '--null' option was given previously, this option cancels
+ its effect, so that any following '--files-from' options will
+ expect their file lists to be newline-terminated.
+
+'--no-overwrite-dir'
+
+ Preserve metadata of existing directories when extracting files
+ from an archive. *Note Overwrite Old Files::.
+
+'--no-quote-chars=STRING'
+ Remove characters listed in STRING from the list of quoted
+ characters set by the previous '--quote-chars' option (*note
+ quoting styles::).
+
+'--no-recursion'
+
+ With this option, 'tar' will not recurse into directories. *Note
+ recurse::.
+
+'--no-same-owner'
+'-o'
+
+ When extracting an archive, do not attempt to preserve the owner
+ specified in the 'tar' archive. This the default behavior for
+ ordinary users.
+
+'--no-same-permissions'
+
+ When extracting an archive, subtract the user's umask from files
+ from the permissions specified in the archive. This is the default
+ behavior for ordinary users.
+
+'--no-seek'
+
+ The archive media does not support seeks to arbitrary locations.
+ Usually 'tar' determines automatically whether the archive can be
+ seeked or not. Use this option to disable this mechanism.
+
+'--no-selinux'
+ Disable SELinux context support. *Note SELinux: Extended File
+ Attributes.
+
+'--no-unquote'
+ Treat all input file or member names literally, do not interpret
+ escape sequences. *Note input name quoting::.
+
+'--no-verbatim-files-from'
+
+ Instructs GNU 'tar' to treat each line read from a file list as if
+ it were supplied in the command line. I.e., leading and trailing
+ whitespace is removed and, if the result begins with a dash, it is
+ treated as a GNU 'tar' command line option.
+
+ This is default behavior. This option is provided as a way to
+ restore it after '--verbatim-files-from' option.
+
+ It is implied by the '--no-null' option.
+
+ *Note no-verbatim-files-from::.
+
+'--no-wildcards'
+ Do not use wildcards. *Note controlling pattern-matching::.
+
+'--no-wildcards-match-slash'
+ Wildcards do not match '/'. *Note controlling pattern-matching::.
+
+'--no-xattrs'
+ Disable extended attributes support. *Note xattrs: Extended File
+ Attributes.
+
+'--null'
+
+ When 'tar' is using the '--files-from' option, this option
+ instructs 'tar' to expect file names terminated with NUL, and to
+ process file names verbatim.
+
+ This means that 'tar' correctly works with file names that contain
+ newlines or begin with a dash.
+
+ *Note nul::.
+
+ See also *note verbatim-files-from::.
+
+'--numeric-owner'
+
+ This option will notify 'tar' that it should use numeric user and
+ group IDs when creating a 'tar' file, rather than names. *Note
+ Attributes::.
+
+'-o'
+ The function of this option depends on the action 'tar' is
+ performing. When extracting files, '-o' is a synonym for
+ '--no-same-owner', i.e., it prevents 'tar' from restoring ownership
+ of files being extracted.
+
+ When creating an archive, it is a synonym for '--old-archive'.
+ This behavior is for compatibility with previous versions of GNU
+ 'tar', and will be removed in future releases.
+
+ *Note Changes::, for more information.
+
+'--occurrence[=NUMBER]'
+
+ This option can be used in conjunction with one of the subcommands
+ '--delete', '--diff', '--extract' or '--list' when a list of files
+ is given either on the command line or via '-T' option.
+
+ This option instructs 'tar' to process only the NUMBERth occurrence
+ of each named file. NUMBER defaults to 1, so
+
+ tar -x -f archive.tar --occurrence filename
+
+ will extract the first occurrence of the member 'filename' from
+ 'archive.tar' and will terminate without scanning to the end of the
+ archive.
+
+'--old-archive'
+ Synonym for '--format=v7'.
+
+'--one-file-system'
+ Used when creating an archive. Prevents 'tar' from recursing into
+ directories that are on different file systems from the current
+ directory.
+
+'--one-top-level[=DIR]'
+ Tells 'tar' to create a new directory beneath the extraction
+ directory (or the one passed to '-C') and use it to guard against
+ tarbombs. In the absence of DIR argument, the name of the new
+ directory will be equal to the base name of the archive (file name
+ minus the archive suffix, if recognized). Any member names that do
+ not begin with that directory name (after transformations from
+ '--transform' and '--strip-components') will be prefixed with it.
+ Recognized file name suffixes are '.tar', and any compression
+ suffixes recognizable by *Note --auto-compress::.
+
+'--overwrite'
+
+ Overwrite existing files and directory metadata when extracting
+ files from an archive. *Note Overwrite Old Files::.
+
+'--overwrite-dir'
+
+ Overwrite the metadata of existing directories when extracting
+ files from an archive. *Note Overwrite Old Files::.
+
+'--owner=USER'
+
+ Specifies that 'tar' should use USER as the owner of members when
+ creating archives, instead of the user associated with the source
+ file. USER can specify a symbolic name, or a numeric ID, or both
+ as NAME:ID. *Note override::.
+
+ This option does not affect extraction from archives. See also
+ '--owner-map', below.
+
+'--owner-map=FILE'
+
+ Read owner translation map from FILE. This option allows to
+ translate only certain owner names or UIDs. *Note override::, for
+ a detailed description. When used together with '--owner' option,
+ the latter affects only those files whose owner is not listed in
+ the FILE.
+
+ This option does not affect extraction from archives.
+
+'--pax-option=KEYWORD-LIST'
+ This option enables creation of the archive in POSIX.1-2001 format
+ (*note posix::) and modifies the way 'tar' handles the extended
+ header keywords. KEYWORD-LIST is a comma-separated list of keyword
+ options. *Note PAX keywords::, for a detailed discussion.
+
+'--portability'
+'--old-archive'
+ Synonym for '--format=v7'.
+
+'--posix'
+ Same as '--format=posix'.
+
+'--preserve-order'
+
+ (See '--same-order'; *note Reading::.)
+
+'--preserve-permissions'
+'--same-permissions'
+'-p'
+
+ When 'tar' is extracting an archive, it normally subtracts the
+ users' umask from the permissions specified in the archive and uses
+ that number as the permissions to create the destination file.
+ Specifying this option instructs 'tar' that it should use the
+ permissions directly from the archive. *Note Setting Access
+ Permissions::.
+
+'--quote-chars=STRING'
+ Always quote characters from STRING, even if the selected quoting
+ style would not quote them (*note quoting styles::).
+
+'--quoting-style=STYLE'
+ Set quoting style to use when printing member and file names (*note
+ quoting styles::). Valid STYLE values are: 'literal', 'shell',
+ 'shell-always', 'c', 'escape', 'locale', and 'clocale'. Default
+ quoting style is 'escape', unless overridden while configuring the
+ package.
+
+'--read-full-records'
+'-B'
+
+ Specifies that 'tar' should reblock its input, for reading from
+ pipes on systems with buggy implementations. *Note Reading::.
+
+'--record-size=SIZE[SUF]'
+
+ Instructs 'tar' to use SIZE bytes per record when accessing the
+ archive. The argument can be suffixed with a "size suffix", e.g.
+ '--record-size=10K' for 10 Kilobytes. *Note Table 9.1:
+ size-suffixes, for a list of valid suffixes. *Note Blocking
+ Factor::, for a detailed description of this option.
+
+'--recursion'
+
+ With this option, 'tar' recurses into directories (default). *Note
+ recurse::.
+
+'--recursive-unlink'
+
+ Remove existing directory hierarchies before extracting directories
+ of the same name from the archive. *Note Recursive Unlink::.
+
+'--remove-files'
+
+ Directs 'tar' to remove the source file from the file system after
+ appending it to an archive. *Note remove files::.
+
+'--restrict'
+
+ Disable use of some potentially harmful 'tar' options. Currently
+ this option disables shell invocation from multi-volume menu (*note
+ Using Multiple Tapes::).
+
+'--rmt-command=CMD'
+
+ Notifies 'tar' that it should use CMD instead of the default
+ '/usr/libexec/rmt' (*note Remote Tape Server::).
+
+'--rsh-command=CMD'
+
+ Notifies 'tar' that is should use CMD to communicate with remote
+ devices. *Note Device::.
+
+'--same-order'
+'--preserve-order'
+'-s'
+
+ This option is an optimization for 'tar' when running on machines
+ with small amounts of memory. It informs 'tar' that the list of
+ file arguments has already been sorted to match the order of files
+ in the archive. *Note Reading::.
+
+'--same-owner'
+
+ When extracting an archive, 'tar' will attempt to preserve the
+ owner specified in the 'tar' archive with this option present.
+ This is the default behavior for the superuser; this option has an
+ effect only for ordinary users. *Note Attributes::.
+
+'--same-permissions'
+
+ (See '--preserve-permissions'; *note Setting Access Permissions::.)
+
+'--seek'
+'-n'
+
+ Assume that the archive media supports seeks to arbitrary
+ locations. Usually 'tar' determines automatically whether the
+ archive can be seeked or not. This option is intended for use in
+ cases when such recognition fails. It takes effect only if the
+ archive is open for reading (e.g. with '--list' or '--extract'
+ options).
+
+'--selinux'
+ Enable the SELinux context support. *Note selinux: Extended File
+ Attributes.
+
+'--show-defaults'
+
+ Displays the default options used by 'tar' and exits successfully.
+ This option is intended for use in shell scripts. Here is an
+ example of what you can see using this option:
+
+ $ tar --show-defaults
+ --format=gnu -f- -b20 --quoting-style=escape
+ --rmt-command=/usr/libexec/rmt --rsh-command=/usr/bin/rsh
+
+ Notice, that this option outputs only one line. The example output
+ above has been split to fit page boundaries. *Note defaults::.
+
+'--show-omitted-dirs'
+
+ Instructs 'tar' to mention the directories it is skipping when
+ operating on a 'tar' archive. *Note show-omitted-dirs::.
+
+'--show-snapshot-field-ranges'
+
+ Displays the range of values allowed by this version of 'tar' for
+ each field in the snapshot file, then exits successfully. *Note
+ Snapshot Files::.
+
+'--show-transformed-names'
+'--show-stored-names'
+
+ Display file or member names after applying any transformations
+ (*note transform::). In particular, when used in conjunction with
+ one of the archive creation operations it instructs 'tar' to list
+ the member names stored in the archive, as opposed to the actual
+ file names. *Note listing member and file names::.
+
+'--skip-old-files'
+
+ Do not overwrite existing files when extracting files from an
+ archive. *Note Keep Old Files::.
+
+ This option differs from '--keep-old-files' in that it does not
+ treat such files as an error, instead it just silently avoids
+ overwriting them.
+
+ The '--warning=existing-file' option can be used together with this
+ option to produce warning messages about existing old files (*note
+ warnings::).
+
+'--sort=ORDER'
+ Specify the directory sorting order when reading directories.
+ ORDER may be one of the following:
+
+ 'none'
+ No directory sorting is performed. This is the default.
+
+ 'name'
+ Sort the directory entries on name. The operating system may
+ deliver directory entries in a more or less random order, and
+ sorting them makes archive creation reproducible.
+
+ 'inode'
+ Sort the directory entries on inode number. Sorting
+ directories on inode number may reduce the amount of disk seek
+ operations when creating an archive for some file systems.
+
+'--sparse'
+'-S'
+
+ Invokes a GNU extension when adding files to an archive that
+ handles sparse files efficiently. *Note sparse::.
+
+'--sparse-version=VERSION'
+
+ Specifies the "format version" to use when archiving sparse files.
+ Implies '--sparse'. *Note sparse::. For the description of the
+ supported sparse formats, *Note Sparse Formats::.
+
+'--starting-file=NAME'
+'-K NAME'
+
+ This option affects extraction only; 'tar' will skip extracting
+ files in the archive until it finds one that matches NAME. *Note
+ Scarce::.
+
+'--strip-components=NUMBER'
+ Strip given NUMBER of leading components from file names before
+ extraction. For example, if archive 'archive.tar' contained
+ '/some/file/name', then running
+
+ tar --extract --file archive.tar --strip-components=2
+
+ would extract this file to file 'name'.
+
+ *Note transform::.
+
+'--suffix=SUFFIX'
+
+ Alters the suffix 'tar' uses when backing up files from the default
+ '~'. *Note backup::.
+
+'--tape-length=NUM[SUF]'
+'-L NUM[SUF]'
+
+ Specifies the length of tapes that 'tar' is writing as being
+ NUM x 1024 bytes long. If optional SUF is given, it specifies a
+ multiplicative factor to be used instead of 1024. For example,
+ '-L2M' means 2 megabytes. *Note Table 9.1: size-suffixes, for a
+ list of allowed suffixes. *Note Using Multiple Tapes::, for a
+ detailed discussion of this option.
+
+'--test-label'
+
+ Reads the volume label. If an argument is specified, test whether
+ it matches the volume label. *Note --test-label option::.
+
+'--to-command=COMMAND'
+
+ During extraction 'tar' will pipe extracted files to the standard
+ input of COMMAND. *Note Writing to an External Program::.
+
+'--to-stdout'
+'-O'
+
+ During extraction, 'tar' will extract files to stdout rather than
+ to the file system. *Note Writing to Standard Output::.
+
+'--totals[=SIGNO]'
+
+ Displays the total number of bytes transferred when processing an
+ archive. If an argument is given, these data are displayed on
+ request, when signal SIGNO is delivered to 'tar'. *Note totals::.
+
+'--touch'
+'-m'
+
+ Sets the data modification time of extracted files to the
+ extraction time, rather than the data modification time stored in
+ the archive. *Note Data Modification Times::.
+
+'--transform=SED-EXPR'
+'--xform=SED-EXPR'
+ Transform file or member names using 'sed' replacement expression
+ SED-EXPR. For example,
+
+ $ tar cf archive.tar --transform 's,^\./,usr/,' .
+
+ will add to 'archive' files from the current working directory,
+ replacing initial './' prefix with 'usr/'. For the detailed
+ discussion, *Note transform::.
+
+ To see transformed member names in verbose listings, use
+ '--show-transformed-names' option (*note show-transformed-names::).
+
+'--uncompress'
+
+ (See '--compress', *note gzip::)
+
+'--ungzip'
+
+ (See '--gzip', *note gzip::)
+
+'--unlink-first'
+'-U'
+
+ Directs 'tar' to remove the corresponding file from the file system
+ before extracting it from the archive. *Note Unlink First::.
+
+'--unquote'
+ Enable unquoting input file or member names (default). *Note input
+ name quoting::.
+
+'--use-compress-program=PROG'
+'-I=PROG'
+
+ Instructs 'tar' to access the archive through PROG, which is
+ presumed to be a compression program of some sort. *Note gzip::.
+
+'--utc'
+
+ Display file modification dates in UTC. This option implies
+ '--verbose'.
+
+'--verbatim-files-from'
+
+ Instructs GNU 'tar' to treat each line read from a file list as a
+ file name, even if it starts with a dash.
+
+ File lists are supplied with the '--files-from' ('-T') option. By
+ default, each line read from a file list is first trimmed off the
+ leading and trailing whitespace and, if the result begins with a
+ dash, it is treated as a GNU 'tar' command line option.
+
+ Use the '--verbatim-files-from' option to disable this special
+ handling. This facilitates the use of 'tar' with file lists
+ created by 'file' command.
+
+ This option affects all '--files-from' options that occur after it
+ in the command line. Its effect is reverted by the
+ '--no-verbatim-files-from' option.
+
+ This option is implied by the '--null' option.
+
+ *Note verbatim-files-from::.
+
+'--verbose'
+'-v'
+
+ Specifies that 'tar' should be more verbose about the operations it
+ is performing. This option can be specified multiple times for
+ some operations to increase the amount of information displayed.
+ *Note verbose::.
+
+'--verify'
+'-W'
+
+ Verifies that the archive was correctly written when creating an
+ archive. *Note verify::.
+
+'--version'
+
+ Print information about the program's name, version, origin and
+ legal status, all on standard output, and then exit successfully.
+ *Note help::.
+
+'--volno-file=FILE'
+
+ Used in conjunction with '--multi-volume'. 'tar' will keep track
+ of which volume of a multi-volume archive it is working in FILE.
+ *Note volno-file::.
+
+'--warning=KEYWORD'
+
+ Enable or disable warning messages identified by KEYWORD. The
+ messages are suppressed if KEYWORD is prefixed with 'no-'. *Note
+ warnings::.
+
+'--wildcards'
+ Use wildcards when matching member names with patterns. *Note
+ controlling pattern-matching::.
+
+'--wildcards-match-slash'
+ Wildcards match '/'. *Note controlling pattern-matching::.
+
+'--xattrs'
+ Enable extended attributes support. *Note xattrs: Extended File
+ Attributes.
+
+'--xattrs-exclude=PATTERN'
+ Specify exclude pattern for xattr keys. *Note xattrs-exclude:
+ Extended File Attributes.
+
+'--xattrs-include=PATTERN.'
+ Specify include pattern for xattr keys. PATTERN is a POSIX regular
+ expression, e.g. '--xattrs-exclude='^user\.'' to include only
+ attributes from the user namespace. *Note xattrs-include: Extended
+ File Attributes.
+
+'--xz'
+'-J'
+ Use 'xz' for compressing or decompressing the archives. *Note
+ gzip::.
+
+ ---------- Footnotes ----------
+
+ (1) Earlier versions of GNU 'tar' understood '-l' as a synonym for
+'--one-file-system'. The current semantics, which complies to UNIX98,
+was introduced with version 1.15.91. *Note Changes::, for more
+information.
+
+
+File: tar.info, Node: Short Option Summary, Next: Position-Sensitive Options, Prev: Option Summary, Up: All Options
+
+3.4.3 Short Options Cross Reference
+-----------------------------------
+
+Here is an alphabetized list of all of the short option forms, matching
+them with the equivalent long option.
+
+Short Option Reference
+
+--------------------------------------------------------------------------
+-A *note --concatenate::.
+
+-B *note --read-full-records::.
+
+-C *note --directory::.
+
+-F *note --info-script::.
+
+-G *note --incremental::.
+
+-J *note --xz::.
+
+-K *note --starting-file::.
+
+-L *note --tape-length::.
+
+-M *note --multi-volume::.
+
+-N *note --newer::.
+
+-O *note --to-stdout::.
+
+-P *note --absolute-names::.
+
+-R *note --block-number::.
+
+-S *note --sparse::.
+
+-T *note --files-from::.
+
+-U *note --unlink-first::.
+
+-V *note --label::.
+
+-W *note --verify::.
+
+-X *note --exclude-from::.
+
+-Z *note --compress::.
+
+-b *note --blocking-factor::.
+
+-c *note --create::.
+
+-d *note --compare::.
+
+-f *note --file::.
+
+-g *note --listed-incremental::.
+
+-h *note --dereference::.
+
+-i *note --ignore-zeros::.
+
+-j *note --bzip2::.
+
+-k *note --keep-old-files::.
+
+-l *note --check-links::.
+
+-m *note --touch::.
+
+-o When creating, *note --no-same-owner::, when extracting
+ -- *note --portability::.
+
+ The latter usage is deprecated. It is retained for
+ compatibility with the earlier versions of GNU 'tar'.
+ In future releases '-o' will be equivalent to
+ '--no-same-owner' only.
+
+-p *note --preserve-permissions::.
+
+-r *note --append::.
+
+-s *note --same-order::.
+
+-t *note --list::.
+
+-u *note --update::.
+
+-v *note --verbose::.
+
+-w *note --interactive::.
+
+-x *note --extract::.
+
+-z *note --gzip::.
+
+
+
+File: tar.info, Node: Position-Sensitive Options, Prev: Short Option Summary, Up: All Options
+
+3.4.4 Position-Sensitive Options
+--------------------------------
+
+Some GNU 'tar' options can be used multiple times in the same invocation
+and affect all arguments that appear after them. These are options that
+control how file names are selected and what kind of pattern matching is
+used.
+
+ The most obvious example is the '-C' option. It instructs 'tar' to
+change to the directory given as its argument prior to processing the
+rest of command line (*note directory::). Thus, in the following
+command:
+
+ tar -c -f a.tar -C /etc passwd -C /var log spool
+
+the file 'passwd' will be searched in the directory '/etc', and files
+'log' and 'spool' - in '/var'.
+
+ These options can also be used in a file list supplied with the
+'--files-from' ('-T') option (*note files::). In that case they affect
+all files (patterns) appearing in that file after them and remain in
+effect for any arguments processed after that file. For example, if the
+file 'list.txt' contained:
+
+ README
+ -C src
+ main.c
+
+and 'tar' were invoked as follows:
+
+ tar -c -f a.tar -T list.txt Makefile
+
+then the file 'README' would be looked up in the current working
+directory, and files 'main.c' and 'Makefile' would be looked up in the
+directory 'src'.
+
+ Many options can be prefixed with '--no-' to cancel the effect of the
+original option.
+
+ For example, the '--recursion' option controls whether to recurse in
+the subdirectories. It's counterpart '--no-recursion' disables this.
+Consider the command below. It will store in the archive the directory
+'/usr' with all files and directories that are located in it as well as
+any files and directories in '/var', without recursing into them(1):
+
+ tar -cf a.tar --recursion /usr --no-recursion /var/*
+
+ The following table summarizes all position-sensitive options.
+
+'--directory=DIR'
+'-C DIR'
+ *Note directory::.
+
+'--null'
+'--no-null'
+ *Note nul::.
+
+'--unquote'
+'--no-unquote'
+ *Note input name quoting::.
+
+'--verbatim-files-from'
+'--no-verbatim-files-from'
+ *Note verbatim-files-from::.
+
+'--recursion'
+'--no-recursion'
+ *Note recurse::.
+
+'--anchored'
+'--no-anchored'
+ *Note anchored patterns::.
+
+'--ignore-case'
+'--no-ignore-case'
+ *Note case-insensitive matches::.
+
+'--wildcards'
+'--no-wildcards'
+ *Note controlling pattern-matching::.
+
+'--wildcards-match-slash'
+'--no-wildcards-match-slash'
+ *Note controlling pattern-matching::.
+
+'--exclude'
+ *Note exclude::.
+
+'--exclude-from'
+'-X'
+'--exclude-caches'
+'--exclude-caches-under'
+'--exclude-caches-all'
+'--exclude-tag'
+'--exclude-ignore'
+'--exclude-ignore-recursive'
+'--exclude-tag-under'
+'--exclude-tag-all'
+'--exclude-vcs'
+'--exclude-vcs-ignores'
+'--exclude-backups'
+ *Note exclude::.
+
+ ---------- Footnotes ----------
+
+ (1) The '--recursion' option is the default and is used here for
+clarity. The same example can be written as:
+
+ tar -cf a.tar /usr --no-recursion /var/*
+
+
+File: tar.info, Node: help, Next: defaults, Prev: All Options, Up: tar invocation
+
+3.5 GNU 'tar' documentation
+===========================
+
+Being careful, the first thing is really checking that you are using GNU
+'tar', indeed. The '--version' option causes 'tar' to print information
+about its name, version, origin and legal status, all on standard
+output, and then exit successfully. For example, 'tar --version' might
+print:
+
+ tar (GNU tar) 1.29
+ Copyright (C) 2013-2016 Free Software Foundation, Inc.
+ License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.
+ This is free software: you are free to change and redistribute it.
+ There is NO WARRANTY, to the extent permitted by law.
+
+ Written by John Gilmore and Jay Fenlason.
+
+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. Notice, however, that some 'tar'
+options have long description lines and the above command will list only
+the first of them.
+
+ The exact look of the option summary displayed by 'tar --help' is
+configurable. *Note Configuring Help Summary::, for a detailed
+description.
+
+ If you only wish to check the spelling of an option, running 'tar
+--usage' may be a better choice. This will display a terse list of
+'tar' options without accompanying explanations.
+
+ The short help output is quite succinct, 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 a variety of forms from
+<http://www.gnu.org/software/tar/manual>. 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, calling 'tar' from the main Info menu.
+
+ There is currently no 'man' page for GNU 'tar'. If you observe such
+a 'man' page on the system you are running, either it does not belong to
+GNU 'tar', or it has not been produced by GNU. Some package maintainers
+convert 'tar --help' output to a man page, using 'help2man'. In any
+case, please bear in mind that the authoritative source of information
+about GNU 'tar' is this Texinfo documentation.
+
+ ---------- 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 output 'tar (GNU paxutils) 3.2'.
+
+
+File: tar.info, Node: defaults, Next: verbose, Prev: help, Up: tar invocation
+
+3.6 Obtaining GNU 'tar' default values
+======================================
+
+GNU 'tar' has some predefined defaults that are used when you do not
+explicitly specify another values. To obtain a list of such defaults,
+use '--show-defaults' option. This will output the values in the form
+of 'tar' command line options:
+
+ $ tar --show-defaults
+ --format=gnu -f- -b20 --quoting-style=escape
+ --rmt-command=/etc/rmt --rsh-command=/usr/bin/rsh
+
+Notice, that this option outputs only one line. The example output
+above has been split to fit page boundaries.
+
+The above output shows that this version of GNU 'tar' defaults to using
+'gnu' archive format (*note Formats::), it uses standard output as the
+archive, if no '--file' option has been given (*note file tutorial::),
+the default blocking factor is 20 (*note Blocking Factor::). It also
+shows the default locations where 'tar' will look for 'rmt' and 'rsh'
+binaries.
+
+
+File: tar.info, Node: verbose, Next: checkpoints, Prev: defaults, Up: tar invocation
+
+3.7 Checking 'tar' progress
+===========================
+
+Typically, 'tar' performs most operations 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 operations, 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' or '--extract', '--verbose' 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 (*Note verbose member listing::,
+for the description) for each member. Since '--list' already prints the
+names of the members, '--verbose' used once with '--list' 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 xvvf 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 cvf -', 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.
+
+ If '--index-file=FILE' is specified, 'tar' sends verbose output to
+FILE rather than to standard output or standard error.
+
+ The '--totals' option causes 'tar' to print on the standard error the
+total amount of bytes transferred when processing an archive. When
+creating or appending to an archive, this option prints the number of
+bytes written to the archive and the average speed at which they have
+been written, e.g.:
+
+ $ tar -c -f archive.tar --totals /home
+ Total bytes written: 7924664320 (7.4GiB, 85MiB/s)
+
+ When reading an archive, this option displays the number of bytes
+read:
+
+ $ tar -x -f archive.tar --totals
+ Total bytes read: 7924664320 (7.4GiB, 95MiB/s)
+
+ Finally, when deleting from an archive, the '--totals' option
+displays both numbers plus number of bytes removed from the archive:
+
+ $ tar --delete -f foo.tar --totals --wildcards '*~'
+ Total bytes read: 9543680 (9.2MiB, 201MiB/s)
+ Total bytes written: 3829760 (3.7MiB, 81MiB/s)
+ Total bytes deleted: 1474048
+
+ You can also obtain this information on request. When '--totals' is
+used with an argument, this argument is interpreted as a symbolic name
+of a signal, upon delivery of which the statistics is to be printed:
+
+'--totals=SIGNO'
+ Print statistics upon delivery of signal SIGNO. Valid arguments
+ are: 'SIGHUP', 'SIGQUIT', 'SIGINT', 'SIGUSR1' and 'SIGUSR2'.
+ Shortened names without 'SIG' prefix are also accepted.
+
+ Both forms of '--totals' option can be used simultaneously. Thus,
+'tar -x --totals --totals=USR1' instructs 'tar' to extract all members
+from its default archive and print statistics after finishing the
+extraction, as well as when receiving signal 'SIGUSR1'.
+
+ 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. By
+default it prints a message each 10 records read or written. This can
+be changed by giving it a numeric argument after an equal sign:
+
+ $ tar -c --checkpoint=1000 /var
+ tar: Write checkpoint 1000
+ tar: Write checkpoint 2000
+ tar: Write checkpoint 3000
+
+ This example shows the default checkpoint message used by 'tar'. If
+you place a dot immediately after the equal sign, it will print a '.' at
+each checkpoint(1). For example:
+
+ $ tar -c --checkpoint=.1000 /var
+ ...
+
+ The '--checkpoint' option provides a flexible mechanism for executing
+arbitrary actions upon hitting checkpoints, see the next section (*note
+checkpoints::), for more information on it.
+
+ The '--show-omitted-dirs' option, when reading an archive--with
+'--list' or '--extract', 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). *Note backup::.
+
+ ---------- Footnotes ----------
+
+ (1) This is actually a shortcut for '--checkpoint=N
+--checkpoint-action=dot'. *Note dot: checkpoints.
+
+
+File: tar.info, Node: checkpoints, Next: warnings, Prev: verbose, Up: tar invocation
+
+3.8 Checkpoints
+===============
+
+A "checkpoint" is a moment of time before writing Nth record to the
+archive (a "write checkpoint"), or before reading Nth record from the
+archive (a "read checkpoint"). Checkpoints allow to periodically
+execute arbitrary actions.
+
+ The checkpoint facility is enabled using the following option:
+
+'--checkpoint[=N]'
+ Schedule checkpoints before writing or reading each Nth record.
+ The default value for N is 10.
+
+ A list of arbitrary "actions" can be executed at each checkpoint.
+These actions include: pausing, displaying textual messages, and
+executing arbitrary external programs. Actions are defined using the
+'--checkpoint-action' option.
+
+'--checkpoint-action=ACTION'
+ Execute an ACTION at each checkpoint.
+
+ The simplest value of ACTION is 'echo'. It instructs 'tar' to
+display the default message on the standard error stream upon arriving
+at each checkpoint. The default message is (in POSIX locale) 'Write
+checkpoint N', for write checkpoints, and 'Read checkpoint N', for read
+checkpoints. Here, N represents ordinal number of the checkpoint.
+
+ In another locales, translated versions of this message are used.
+
+ This is the default action, so running:
+
+ $ tar -c --checkpoint=1000 --checkpoint-action=echo /var
+
+is equivalent to:
+
+ $ tar -c --checkpoint=1000 /var
+
+ The 'echo' action also allows to supply a customized message. You do
+so by placing an equals sign and the message right after it, e.g.:
+
+ --checkpoint-action="echo=Hit %s checkpoint #%u"
+
+ The '%s' and '%u' in the above example are "format specifiers". The
+'%s' specifier is replaced with the "type" of the checkpoint: 'write' or
+'read' (or a corresponding translated version in locales other than
+POSIX). The '%u' specifier is replaced with the ordinal number of the
+checkpoint. Thus, the above example could produce the following output
+when used with the '--create' option:
+
+ tar: Hit write checkpoint #10
+ tar: Hit write checkpoint #20
+ tar: Hit write checkpoint #30
+
+ The complete list of available format specifiers follows. Some of
+them can take optional arguments. These arguments, if given, are
+supplied in curly braces between the percent sign and the specifier
+letter.
+
+'%s'
+ Print type of the checkpoint ('write' or 'read').
+
+'%u'
+ Print number of the checkpoint.
+
+'%{r,w,d}T'
+ Print number of bytes transferred so far and approximate transfer
+ speed. Optional arguments supply prefixes to be used before number
+ of bytes read, written and deleted, correspondingly. If absent,
+ they default to 'R'. 'W', 'D'. Any or all of them can be omitted,
+ so, that e.g. '%{}T' means to print corresponding statistics
+ without any prefixes. Any surplus arguments, if present, are
+ silently ignored.
+
+ $ tar --delete -f f.tar --checkpoint-action=echo="#%u: %T" main.c
+ tar: #1: R: 0 (0B, 0B/s),W: 0 (0B, 0B/s),D: 0
+ tar: #2: R: 10240 (10KiB, 19MiB/s),W: 0 (0B, 0B/s),D: 10240
+
+ See also the 'totals' action, described below.
+
+'%{FMT}t'
+ Output current local time using FMT as format for 'strftime' (*note
+ strftime: (strftime(3))strftime.). The '{FMT}' part is optional.
+ If not present, the default format is '%c', i.e. the preferred
+ date and time representation for the current locale.
+
+'%{N}*'
+ Pad output with spaces to the Nth column. If the '{N}' part is
+ omitted, the current screen width is assumed.
+
+'%c'
+ This is a shortcut for '%{%Y-%m-%d %H:%M:%S}t: %ds,
+ %{read,wrote}T%*\r', intended mainly for use with 'ttyout' action
+ (see below).
+
+ Aside from format expansion, the message string is subject to
+"unquoting", during which the backslash "escape sequences" are replaced
+with their corresponding ASCII characters (*note escape sequences::).
+E.g. the following action will produce an audible bell and the message
+described above at each checkpoint:
+
+ --checkpoint-action='echo=\aHit %s checkpoint #%u'
+
+ There is also a special action which produces an audible signal:
+'bell'. It is not equivalent to 'echo='\a'', because 'bell' sends the
+bell directly to the console ('/dev/tty'), whereas 'echo='\a'' sends it
+to the standard error.
+
+ The 'ttyout=STRING' action outputs STRING to '/dev/tty', so it can be
+used even if the standard output is redirected elsewhere. The STRING is
+subject to the same modifications as with 'echo' action. In contrast to
+the latter, 'ttyout' does not prepend 'tar' executable name to the
+string, nor does it output a newline after it. For example, the
+following action will print the checkpoint message at the same screen
+line, overwriting any previous message:
+
+ --checkpoint-action="ttyout=Hit %s checkpoint #%u%*\r"
+
+Notice the use of '%*' specifier to clear out any eventual remains of
+the prior output line. As as more complex example, consider this:
+
+ --checkpoint-action=ttyout='%{%Y-%m-%d %H:%M:%S}t (%d sec): #%u, %T%*\r'
+
+This prints the current local time, number of seconds expired since tar
+was started, the checkpoint ordinal number, transferred bytes and
+average computed I/O speed.
+
+ Another available checkpoint action is 'dot' (or '.'). It instructs
+'tar' to print a single dot on the standard listing stream, e.g.:
+
+ $ tar -c --checkpoint=1000 --checkpoint-action=dot /var
+ ...
+
+ For compatibility with previous GNU 'tar' versions, this action can
+be abbreviated by placing a dot in front of the checkpoint frequency, as
+shown in the previous section.
+
+ The 'totals' action prints the total number of bytes transferred so
+far. The format of the data is the same as for the '--totals' option
+(*note totals::). See also '%T' format specifier of the 'echo' or
+'ttyout' action.
+
+ Yet another action, 'sleep', pauses 'tar' for a specified amount of
+seconds. The following example will stop for 30 seconds at each
+checkpoint:
+
+ $ tar -c --checkpoint=1000 --checkpoint-action=sleep=30
+
+ Finally, the 'exec' action executes a given external command. For
+example:
+
+ $ tar -c --checkpoint=1000 --checkpoint-action=exec=/sbin/cpoint
+
+ The supplied command can be any valid command invocation, with or
+without additional command line arguments. If it does contain
+arguments, don't forget to quote it to prevent it from being split by
+the shell. *Note Running External Commands: external, for more detail.
+
+ The command gets a copy of 'tar''s environment plus the following
+variables:
+
+'TAR_VERSION'
+ GNU 'tar' version number.
+
+'TAR_ARCHIVE'
+ The name of the archive 'tar' is processing.
+
+'TAR_BLOCKING_FACTOR'
+ Current blocking factor (*note Blocking::).
+
+'TAR_CHECKPOINT'
+ Number of the checkpoint.
+
+'TAR_SUBCOMMAND'
+ A short option describing the operation 'tar' is executing. *Note
+ Operations::, for a complete list of subcommand options.
+
+'TAR_FORMAT'
+ Format of the archive being processed. *Note Formats::, for a
+ complete list of archive format names.
+
+ These environment variables can also be passed as arguments to the
+command, provided that they are properly escaped, for example:
+
+ tar -c -f arc.tar \
+ --checkpoint-action='exec=/sbin/cpoint $TAR_CHECKPOINT'
+
+Notice single quotes to prevent variable names from being expanded by
+the shell when invoking 'tar'.
+
+ Any number of actions can be defined, by supplying several
+'--checkpoint-action' options in the command line. For example, the
+command below displays two messages, pauses execution for 30 seconds and
+executes the '/sbin/cpoint' script:
+
+ $ tar -c -f arc.tar \
+ --checkpoint-action='\aecho=Hit %s checkpoint #%u' \
+ --checkpoint-action='echo=Sleeping for 30 seconds' \
+ --checkpoint-action='sleep=30' \
+ --checkpoint-action='exec=/sbin/cpoint'
+
+ This example also illustrates the fact that '--checkpoint-action' can
+be used without '--checkpoint'. In this case, the default checkpoint
+frequency (at each 10th record) is assumed.
+
+
+File: tar.info, Node: warnings, Next: interactive, Prev: checkpoints, Up: tar invocation
+
+3.9 Controlling Warning Messages
+================================
+
+Sometimes, while performing the requested task, GNU 'tar' notices some
+conditions that are not exactly errors, but which the user should be
+aware of. When this happens, 'tar' issues a "warning message"
+describing the condition. Warning messages are output to the standard
+error and they do not affect the exit code of 'tar' command.
+
+ GNU 'tar' allows the user to suppress some or all of its warning
+messages:
+
+'--warning=KEYWORD'
+ Control display of the warning messages identified by KEYWORD. If
+ KEYWORD starts with the prefix 'no-', such messages are suppressed.
+ Otherwise, they are enabled.
+
+ Multiple '--warning' messages accumulate.
+
+ The tables below list allowed values for KEYWORD along with the
+ warning messages they control.
+
+Keywords controlling 'tar' operation
+------------------------------------
+
+all
+ Enable all warning messages. This is the default.
+none
+ Disable all warning messages.
+filename-with-nuls
+ '%s: file name read contains nul character'
+alone-zero-block
+ 'A lone zero block at %s'
+
+Keywords applicable for 'tar --create'
+--------------------------------------
+
+cachedir
+ '%s: contains a cache directory tag %s; %s'
+file-shrank
+ '%s: File shrank by %s bytes; padding with zeros'
+xdev
+ '%s: file is on a different filesystem; not dumped'
+file-ignored
+ '%s: Unknown file type; file ignored'
+ '%s: socket ignored'
+ '%s: door ignored'
+file-unchanged
+ '%s: file is unchanged; not dumped'
+ignore-archive
+ '%s: file is the archive; not dumped'
+file-removed
+ '%s: File removed before we read it'
+file-changed
+ '%s: file changed as we read it'
+
+Keywords applicable for 'tar --extract'
+---------------------------------------
+
+existing-file
+ '%s: skipping existing file'
+timestamp
+ '%s: implausibly old time stamp %s'
+ '%s: time stamp %s is %s s in the future'
+contiguous-cast
+ 'Extracting contiguous files as regular files'
+symlink-cast
+ 'Attempting extraction of symbolic links as hard links'
+unknown-cast
+ '%s: Unknown file type '%c', extracted as normal file'
+ignore-newer
+ 'Current %s is newer or same age'
+unknown-keyword
+ 'Ignoring unknown extended header keyword '%s''
+decompress-program
+ Controls verbose description of failures occurring when trying to
+ run alternative decompressor programs (*note alternative
+ decompression programs::). This warning is disabled by default
+ (unless '--verbose' is used). A common example of what you can get
+ when using this warning is:
+
+ $ tar --warning=decompress-program -x -f archive.Z
+ tar (child): cannot run compress: No such file or directory
+ tar (child): trying gzip
+
+ This means that 'tar' first tried to decompress 'archive.Z' using
+ 'compress', and, when that failed, switched to 'gzip'.
+record-size
+ 'Record size = %lu blocks'
+
+Keywords controlling incremental extraction:
+--------------------------------------------
+
+rename-directory
+ '%s: Directory has been renamed from %s'
+ '%s: Directory has been renamed'
+new-directory
+ '%s: Directory is new'
+xdev
+ '%s: directory is on a different device: not purging'
+bad-dumpdir
+ 'Malformed dumpdir: 'X' never used'
+
+
+File: tar.info, Node: interactive, Next: external, Prev: warnings, Up: tar invocation
+
+3.10 Asking for Confirmation During Operations
+==============================================
+
+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 an operation
+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 operation 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: external, Prev: interactive, Up: tar invocation
+
+3.11 Running External Commands
+==============================
+
+Certain GNU 'tar' operations imply running external commands that you
+supply on the command line. One of such operations is checkpointing,
+described above (*note checkpoint exec::). Another example of this
+feature is the '-I' option, which allows you to supply the program to
+use for compressing or decompressing the archive (*note
+use-compress-program::).
+
+ Whenever such operation is requested, 'tar' first splits the supplied
+command into words much like the shell does. It then treats the first
+word as the name of the program or the shell script to execute and the
+rest of words as its command line arguments. The program, unless given
+as an absolute file name, is searched in the shell's 'PATH'.
+
+ Any additional information is normally supplied to external commands
+in environment variables, specific to each particular operation. For
+example, the '--checkpoint-action=exec' option, defines the
+'TAR_ARCHIVE' variable to the name of the archive being worked upon.
+You can, should the need be, use these variables in the command line of
+the external command. For example:
+
+ $ tar -x -f archive.tar \
+ --checkpoint-action=exec='printf "%04d in %32s\r" $TAR_CHECKPOINT $TAR_ARCHIVE'
+
+This command prints for each checkpoint its number and the name of the
+archive, using the same output line on the screen.
+
+ Notice the use of single quotes to prevent variable names from being
+expanded by the shell when invoking 'tar'.
+
+
+File: tar.info, Node: operations, Next: Backups, Prev: tar invocation, Up: Top
+
+4 GNU 'tar' Operations
+**********************
+
+* Menu:
+
+* Basic tar::
+* Advanced tar::
+* create options::
+* extract options::
+* backup::
+* Applications::
+* looking ahead::
+
+
+File: tar.info, Node: Basic tar, Next: Advanced tar, Up: operations
+
+4.1 Basic GNU 'tar' Operations
+==============================
+
+The basic 'tar' operations, '--create' ('-c'), '--list' ('-t') and
+'--extract' ('--get', '-x'), are currently presented and described in
+the tutorial chapter of this manual. This section provides some
+complementary notes for these operations.
+
+'--create'
+'-c'
+
+ Creating an empty archive would have some kind of elegance. One
+ can initialize an empty archive and later use '--append' ('-r') for
+ adding all members. Some applications would not welcome making an
+ exception in the way of adding the first archive member. On the
+ other hand, many people reported that it is dangerously too easy
+ for 'tar' to destroy a magnetic tape with an empty archive(1). The
+ two most common errors are:
+
+ 1. Mistakingly using 'create' instead of 'extract', when the
+ intent was to extract the full contents of an archive. This
+ error is likely: keys 'c' and 'x' are right next to each other
+ on the QWERTY keyboard. Instead of being unpacked, the
+ archive then gets wholly destroyed. When users speak about
+ "exploding" an archive, they usually mean something else :-).
+
+ 2. Forgetting the argument to 'file', when the intent was to
+ create an archive with a single file in it. This error is
+ likely because a tired user can easily add the 'f' key to the
+ cluster of option letters, by the mere force of habit, without
+ realizing the full consequence of doing so. The usual
+ consequence is that the single file, which was meant to be
+ saved, is rather destroyed.
+
+ So, recognizing the likelihood and the catastrophic nature of these
+ errors, GNU 'tar' now takes some distance from elegance, and
+ cowardly refuses to create an archive when '--create' option is
+ given, there are no arguments besides options, and '--files-from'
+ ('-T') option is _not_ used. To get around the cautiousness of GNU
+ 'tar' and nevertheless create an archive with nothing in it, one
+ may still use, as the value for the '--files-from' option, a file
+ with no names in it, as shown in the following commands:
+
+ tar --create --file=empty-archive.tar --files-from=/dev/null
+ tar -cf empty-archive.tar -T /dev/null
+
+'--extract'
+'--get'
+'-x'
+
+ A socket is stored, within a GNU 'tar' archive, as a pipe.
+
+'--list (-t)'
+
+ GNU 'tar' now shows dates as '1996-08-30', while it used to show
+ them as 'Aug 30 1996'. Preferably, people should get used to ISO
+ 8601 dates. Local American dates should be made available again
+ with full date localization support, once ready. In the meantime,
+ programs not being localizable for dates should prefer
+ international dates, that's really the way to go.
+
+ Look up <http://www.cl.cam.ac.uk/~mgk25/iso-time.html> if you are
+ curious, it contains a detailed explanation of the ISO 8601
+ standard.
+
+ ---------- Footnotes ----------
+
+ (1) This is well described in 'Unix-haters Handbook', by Simson
+Garfinkel, Daniel Weise & Steven Strassmann, IDG Books, ISBN
+1-56884-203-1.
+
+
+File: tar.info, Node: Advanced tar, Next: create options, Prev: Basic tar, Up: operations
+
+4.2 Advanced GNU 'tar' Operations
+=================================
+
+Now that you have learned the basics of using GNU 'tar', you may want to
+learn about further ways in which 'tar' can help you.
+
+ This chapter presents five, more advanced operations which you
+probably won't use on a daily basis, but which serve more specialized
+functions. We also explain the different styles of options and why you
+might want to use one or another, or a combination of them in your 'tar'
+commands. Additionally, this chapter includes options which allow you
+to define the output from 'tar' more carefully, and provide help and
+error correction in special circumstances.
+
+* Menu:
+
+* Operations::
+* append::
+* update::
+* concatenate::
+* delete::
+* compare::
+
+
+File: tar.info, Node: Operations, Next: append, Up: Advanced tar
+
+4.2.1 The Five Advanced 'tar' Operations
+----------------------------------------
+
+In the last chapter, you learned about the first three operations to
+'tar'. This chapter presents the remaining five operations to 'tar':
+'--append', '--update', '--concatenate', '--delete', and '--compare'.
+
+ You are not likely to use these operations as frequently as those
+covered in the last chapter; however, since they perform specialized
+functions, they are quite useful when you do need to use them. We will
+give examples using the same directory and files that you created in the
+last chapter. As you may recall, the directory is called 'practice',
+the files are 'jazz', 'blues', 'folk', and the two archive files you
+created are 'collection.tar' and 'music.tar'.
+
+ We will also use the archive files 'afiles.tar' and 'bfiles.tar'.
+The archive 'afiles.tar' contains the members 'apple', 'angst', and
+'aspic'; 'bfiles.tar' contains the members './birds', 'baboon', and
+'./box'.
+
+ Unless we state otherwise, all practicing you do and examples you
+follow in this chapter will take place in the 'practice' directory that
+you created in the previous chapter; see *note prepare for examples::.
+(Below in this section, we will remind you of the state of the examples
+where the last chapter left them.)
+
+ The five operations that we will cover in this chapter are:
+
+'--append'
+'-r'
+ Add new entries to an archive that already exists.
+'--update'
+'-u'
+ Add more recent copies of archive members to the end of an archive,
+ if they exist.
+'--concatenate'
+'--catenate'
+'-A'
+ Add one or more pre-existing archives to the end of another
+ archive.
+'--delete'
+ Delete items from an archive (does not work on tapes).
+'--compare'
+'--diff'
+'-d'
+ Compare archive members to their counterparts in the file system.
+
+
+File: tar.info, Node: append, Next: update, Prev: Operations, Up: Advanced tar
+
+4.2.2 How to Add Files to Existing Archives: '--append'
+-------------------------------------------------------
+
+If you want to add files to an existing archive, you don't need to
+create a new archive; you can use '--append' ('-r'). The archive must
+already exist in order to use '--append'. (A related operation is the
+'--update' operation; you can use this to add newer versions of archive
+members to an existing archive. To learn how to do this with
+'--update', *note update::.)
+
+ If you use '--append' to add a file that has the same name as an
+archive member to an archive containing that archive member, then the
+old member is not deleted. What does happen, however, is somewhat
+complex. 'tar' _allows_ you to have infinite number of files with the
+same name. Some operations treat these same-named members no
+differently than any other set of archive members: for example, if you
+view an archive with '--list' ('-t'), you will see all of those members
+listed, with their data modification times, owners, etc.
+
+ Other operations don't deal with these members as perfectly as you
+might prefer; if you were to use '--extract' to extract the archive,
+only the most recently added copy of a member with the same name as
+other members would end up in the working directory. This is because
+'--extract' extracts an archive in the order the members appeared in the
+archive; the most recently archived members will be extracted last.
+Additionally, an extracted member will _replace_ a file of the same name
+which existed in the directory already, and 'tar' will not prompt you
+about this(1). Thus, only the most recently archived member will end up
+being extracted, as it will replace the one extracted before it, and so
+on.
+
+ There exists a special option that allows you to get around this
+behavior and extract (or list) only a particular copy of the file. This
+is '--occurrence' option. If you run 'tar' with this option, it will
+extract only the first copy of the file. You may also give this option
+an argument specifying the number of copy to be extracted. Thus, for
+example if the archive 'archive.tar' contained three copies of file
+'myfile', then the command
+
+ tar --extract --file archive.tar --occurrence=2 myfile
+
+would extract only the second copy. *Note --occurrence: Option Summary,
+for the description of '--occurrence' option.
+
+ If you want to replace an archive member, use '--delete' to delete
+the member you want to remove from the archive, and then use '--append'
+to add the member you want to be in the archive. Note that you can not
+change the order of the archive; the most recently added member will
+still appear last. In this sense, you cannot truly "replace" one member
+with another. (Replacing one member with another will not work on
+certain types of media, such as tapes; see *note delete:: and *note
+Media::, for more information.)
+
+* Menu:
+
+* appending files:: Appending Files to an Archive
+* multiple::
+
+ ---------- Footnotes ----------
+
+ (1) Unless you give it '--keep-old-files' (or '--skip-old-files')
+option, or the disk copy is newer than the one in the archive and you
+invoke 'tar' with '--keep-newer-files' option.
+
+
+File: tar.info, Node: appending files, Next: multiple, Up: append
+
+4.2.2.1 Appending Files to an Archive
+.....................................
+
+The simplest way to add a file to an already existing archive is the
+'--append' ('-r') operation, which writes specified files into the
+archive whether or not they are already among the archived files.
+
+ When you use '--append', you _must_ specify file name arguments, as
+there is no default. If you specify a file that already exists in the
+archive, another copy of the file will be added to the end of the
+archive. As with other operations, the member names of the newly added
+files will be exactly the same as their names given on the command line.
+The '--verbose' ('-v') option will print out the names of the files as
+they are written into the archive.
+
+ '--append' cannot be performed on some tape drives, unfortunately,
+due to deficiencies in the formats those tape drives use. The archive
+must be a valid 'tar' archive, or else the results of using this
+operation will be unpredictable. *Note Media::.
+
+ To demonstrate using '--append' to add a file to an archive, create a
+file called 'rock' in the 'practice' directory. Make sure you are in
+the 'practice' directory. Then, run the following 'tar' command to add
+'rock' to 'collection.tar':
+
+ $ tar --append --file=collection.tar rock
+
+If you now use the '--list' ('-t') operation, you will see that 'rock'
+has been added to the archive:
+
+ $ tar --list --file=collection.tar
+ -rw-r--r-- me/user 28 1996-10-18 16:31 jazz
+ -rw-r--r-- me/user 21 1996-09-23 16:44 blues
+ -rw-r--r-- me/user 20 1996-09-23 16:44 folk
+ -rw-r--r-- me/user 20 1996-09-23 16:44 rock
+
+
+File: tar.info, Node: multiple, Prev: appending files, Up: append
+
+4.2.2.2 Multiple Members with the Same Name
+...........................................
+
+You can use '--append' ('-r') to add copies of files which have been
+updated since the archive was created. (However, we do not recommend
+doing this since there is another 'tar' option called '--update'; *Note
+update::, for more information. We describe this use of '--append' here
+for the sake of completeness.) When you extract the archive, the older
+version will be effectively lost. This works because files are
+extracted from an archive in the order in which they were archived.
+Thus, when the archive is extracted, a file archived later in time will
+replace a file of the same name which was archived earlier, even though
+the older version of the file will remain in the archive unless you
+delete all versions of the file.
+
+ Supposing you change the file 'blues' and then append the changed
+version to 'collection.tar'. As you saw above, the original 'blues' is
+in the archive 'collection.tar'. If you change the file and append the
+new version of the file to the archive, there will be two copies in the
+archive. When you extract the archive, the older version of the file
+will be extracted first, and then replaced by the newer version when it
+is extracted.
+
+ You can append the new, changed copy of the file 'blues' to the
+archive in this way:
+
+ $ tar --append --verbose --file=collection.tar blues
+ blues
+
+Because you specified the '--verbose' option, 'tar' has printed the name
+of the file being appended as it was acted on. Now list the contents of
+the archive:
+
+ $ tar --list --verbose --file=collection.tar
+ -rw-r--r-- me/user 28 1996-10-18 16:31 jazz
+ -rw-r--r-- me/user 21 1996-09-23 16:44 blues
+ -rw-r--r-- me/user 20 1996-09-23 16:44 folk
+ -rw-r--r-- me/user 20 1996-09-23 16:44 rock
+ -rw-r--r-- me/user 58 1996-10-24 18:30 blues
+
+The newest version of 'blues' is now at the end of the archive (note the
+different creation dates and file sizes). If you extract the archive,
+the older version of the file 'blues' will be replaced by the newer
+version. You can confirm this by extracting the archive and running
+'ls' on the directory.
+
+ If you wish to extract the first occurrence of the file 'blues' from
+the archive, use '--occurrence' option, as shown in the following
+example:
+
+ $ tar --extract -vv --occurrence --file=collection.tar blues
+ -rw-r--r-- me/user 21 1996-09-23 16:44 blues
+
+ *Note Writing::, for more information on '--extract' and see *note
+-occurrence: Option Summary, for a description of '--occurrence' option.
+
+
+File: tar.info, Node: update, Next: concatenate, Prev: append, Up: Advanced tar
+
+4.2.3 Updating an Archive
+-------------------------
+
+In the previous section, you learned how to use '--append' to add a file
+to an existing archive. A related operation is '--update' ('-u'). The
+'--update' operation updates a 'tar' archive by comparing the date of
+the specified archive members against the date of the file with the same
+name. If the file has been modified more recently than the archive
+member, then the newer version of the file is added to the archive (as
+with '--append').
+
+ Unfortunately, you cannot use '--update' with magnetic tape drives.
+The operation will fail.
+
+ Both '--update' and '--append' work by adding to the end of the
+archive. When you extract a file from the archive, only the version
+stored last will wind up in the file system, unless you use the
+'--backup' option. *Note multiple::, for a detailed discussion.
+
+* Menu:
+
+* how to update::
+
+
+File: tar.info, Node: how to update, Up: update
+
+4.2.3.1 How to Update an Archive Using '--update'
+.................................................
+
+You must use file name arguments with the '--update' ('-u') operation.
+If you don't specify any files, 'tar' won't act on any files and won't
+tell you that it didn't do anything (which may end up confusing you).
+
+ To see the '--update' option at work, create a new file, 'classical',
+in your practice directory, and some extra text to the file 'blues',
+using any text editor. Then invoke 'tar' with the 'update' operation
+and the '--verbose' ('-v') option specified, using the names of all the
+files in the 'practice' directory as file name arguments:
+
+ $ tar --update -v -f collection.tar blues folk rock classical
+ blues
+ classical
+ $
+
+Because we have specified verbose mode, 'tar' prints out the names of
+the files it is working on, which in this case are the names of the
+files that needed to be updated. If you run 'tar --list' and look at
+the archive, you will see 'blues' and 'classical' at its end. There
+will be a total of two versions of the member 'blues'; the one at the
+end will be newer and larger, since you added text before updating it.
+
+ The reason 'tar' does not overwrite the older file when updating it
+is because writing to the middle of a section of tape is a difficult
+process. Tapes are not designed to go backward. *Note Media::, for
+more information about tapes.
+
+ '--update' ('-u') is not suitable for performing backups for two
+reasons: it does not change directory content entries, and it lengthens
+the archive every time it is used. The GNU 'tar' options intended
+specifically for backups are more efficient. If you need to run
+backups, please consult *note Backups::.
+
+
+File: tar.info, Node: concatenate, Next: delete, Prev: update, Up: Advanced tar
+
+4.2.4 Combining Archives with '--concatenate'
+---------------------------------------------
+
+Sometimes it may be convenient to add a second archive onto the end of
+an archive rather than adding individual files to the archive. To add
+one or more archives to the end of another archive, you should use the
+'--concatenate' ('--catenate', '-A') operation.
+
+ To use '--concatenate', give the first archive with '--file' option
+and name the rest of archives to be concatenated on the command line.
+The members, and their member names, will be copied verbatim from those
+archives to the first one(1). The new, concatenated archive will be
+called by the same name as the one given with the '--file' option. As
+usual, if you omit '--file', 'tar' will use the value of the environment
+variable 'TAPE', or, if this has not been set, the default archive name.
+
+ To demonstrate how '--concatenate' works, create two small archives
+called 'bluesrock.tar' and 'folkjazz.tar', using the relevant files from
+'practice':
+
+ $ tar -cvf bluesrock.tar blues rock
+ blues
+ rock
+ $ tar -cvf folkjazz.tar folk jazz
+ folk
+ jazz
+
+If you like, You can run 'tar --list' to make sure the archives contain
+what they are supposed to:
+
+ $ tar -tvf bluesrock.tar
+ -rw-r--r-- melissa/user 105 1997-01-21 19:42 blues
+ -rw-r--r-- melissa/user 33 1997-01-20 15:34 rock
+ $ tar -tvf jazzfolk.tar
+ -rw-r--r-- melissa/user 20 1996-09-23 16:44 folk
+ -rw-r--r-- melissa/user 65 1997-01-30 14:15 jazz
+
+ We can concatenate these two archives with 'tar':
+
+ $ cd ..
+ $ tar --concatenate --file=bluesrock.tar jazzfolk.tar
+
+ If you now list the contents of the 'bluesrock.tar', you will see
+that now it also contains the archive members of 'jazzfolk.tar':
+
+ $ tar --list --file=bluesrock.tar
+ blues
+ rock
+ folk
+ jazz
+
+ When you use '--concatenate', the source and target archives must
+already exist and must have been created using compatible format
+parameters. Notice, that 'tar' does not check whether the archives it
+concatenates have compatible formats, it does not even check if the
+files are really tar archives.
+
+ Like '--append' ('-r'), this operation cannot be performed on some
+tape drives, due to deficiencies in the formats those tape drives use.
+
+ It may seem more intuitive to you to want or try to use 'cat' to
+concatenate two archives instead of using the '--concatenate' operation;
+after all, 'cat' is the utility for combining files.
+
+ However, 'tar' archives incorporate an end-of-file marker which must
+be removed if the concatenated archives are to be read properly as one
+archive. '--concatenate' removes the end-of-archive marker from the
+target archive before each new archive is appended. If you use 'cat' to
+combine the archives, the result will not be a valid 'tar' format
+archive. If you need to retrieve files from an archive that was added
+to using the 'cat' utility, use the '--ignore-zeros' ('-i') option.
+*Note Ignore Zeros::, for further information on dealing with archives
+improperly combined using the 'cat' shell utility.
+
+ ---------- Footnotes ----------
+
+ (1) This can cause multiple members to have the same name. For
+information on how this affects reading the archive, see *note
+multiple::.
+
+
+File: tar.info, Node: delete, Next: compare, Prev: concatenate, Up: Advanced tar
+
+4.2.5 Removing Archive Members Using '--delete'
+-----------------------------------------------
+
+You can remove members from an archive by using the '--delete' option.
+Specify the name of the archive with '--file' ('-f') and then specify
+the names of the members to be deleted; if you list no member names,
+nothing will be deleted. The '--verbose' option will cause 'tar' to
+print the names of the members as they are deleted. As with
+'--extract', you must give the exact member names when using 'tar
+--delete'. '--delete' will remove all versions of the named file from
+the archive. The '--delete' operation can run very slowly.
+
+ Unlike other operations, '--delete' has no short form.
+
+ This operation will rewrite the archive. You can only use '--delete'
+on an archive if the archive device allows you to write to any point on
+the media, such as a disk; because of this, it does not work on magnetic
+tapes. Do not try to delete an archive member from a magnetic tape; the
+action will not succeed, and you will be likely to scramble the archive
+and damage your tape. There is no safe way (except by completely
+re-writing the archive) to delete files from most kinds of magnetic
+tape. *Note Media::.
+
+ To delete all versions of the file 'blues' from the archive
+'collection.tar' in the 'practice' directory, make sure you are in that
+directory, and then,
+
+ $ tar --list --file=collection.tar
+ blues
+ folk
+ jazz
+ rock
+ $ tar --delete --file=collection.tar blues
+ $ tar --list --file=collection.tar
+ folk
+ jazz
+ rock
+
+ The '--delete' option has been reported to work properly when 'tar'
+acts as a filter from 'stdin' to 'stdout'.
+
+
+File: tar.info, Node: compare, Prev: delete, Up: Advanced tar
+
+4.2.6 Comparing Archive Members with the File System
+----------------------------------------------------
+
+The '--compare' ('-d'), or '--diff' operation compares specified archive
+members against files with the same names, and then reports differences
+in file size, mode, owner, modification date and contents. You should
+_only_ specify archive member names, not file names. If you do not name
+any members, then 'tar' will compare the entire archive. If a file is
+represented in the archive but does not exist in the file system, 'tar'
+reports a difference.
+
+ You have to specify the record size of the archive when modifying an
+archive with a non-default record size.
+
+ 'tar' ignores files in the file system that do not have corresponding
+members in the archive.
+
+ The following example compares the archive members 'rock', 'blues'
+and 'funk' in the archive 'bluesrock.tar' with files of the same name in
+the file system. (Note that there is no file, 'funk'; 'tar' will report
+an error message.)
+
+ $ tar --compare --file=bluesrock.tar rock blues funk
+ rock
+ blues
+ tar: funk not found in archive
+
+ The spirit behind the '--compare' ('--diff', '-d') option is to check
+whether the archive represents the current state of files on disk, more
+than validating the integrity of the archive media. For this latter
+goal, see *note verify::.
+
+
+File: tar.info, Node: create options, Next: extract options, Prev: Advanced tar, Up: operations
+
+4.3 Options Used by '--create'
+==============================
+
+The previous chapter described the basics of how to use '--create'
+('-c') to create an archive from a set of files. *Note create::. This
+section described advanced options to be used with '--create'.
+
+* Menu:
+
+* override:: Overriding File Metadata.
+* Extended File Attributes::
+* Ignore Failed Read::
+
+
+File: tar.info, Node: override, Next: Extended File Attributes, Up: create options
+
+4.3.1 Overriding File Metadata
+------------------------------
+
+As described above, a 'tar' archive keeps, for each member it contains,
+its "metadata", such as modification time, mode and ownership of the
+file. GNU 'tar' allows to replace these data with other values when
+adding files to the archive. The options described in this section
+affect creation of archives of any type. For POSIX archives, see also
+*note PAX keywords::, for additional ways of controlling metadata,
+stored in the archive.
+
+'--mode=PERMISSIONS'
+
+ When adding files to an archive, 'tar' will use PERMISSIONS for the
+ archive members, rather than the permissions from the files.
+ PERMISSIONS can be specified either as an octal number or as
+ symbolic permissions, like with 'chmod' (*Note Permissions:
+ (fileutils)File permissions. This reference also has useful
+ information for those not being overly familiar with the UNIX
+ permission system). Using latter syntax allows for more
+ flexibility. For example, the value 'a+rw' adds read and write
+ permissions for everybody, while retaining executable bits on
+ directories or on any other file already marked as executable:
+
+ $ tar -c -f archive.tar --mode='a+rw' .
+
+'--mtime=DATE'
+
+ When adding files to an archive, 'tar' will use DATE as the
+ modification time of members when creating archives, instead of
+ their actual modification times. The argument DATE can be either a
+ textual date representation in almost arbitrary format (*note Date
+ input formats::) or a name of an existing file, starting with '/'
+ or '.'. In the latter case, the modification time of that file
+ will be used.
+
+ The following example will set the modification date to 00:00:00,
+ January 1, 1970:
+
+ $ tar -c -f archive.tar --mtime='1970-01-01' .
+
+ When used with '--verbose' (*note verbose tutorial::) GNU 'tar'
+ will try to convert the specified date back to its textual
+ representation and compare it with the one given with '--mtime'
+ options. If the two dates differ, 'tar' will print a warning
+ saying what date it will use. This is to help user ensure he is
+ using the right date.
+
+ For example:
+
+ $ tar -c -f archive.tar -v --mtime=yesterday .
+ tar: Option --mtime: Treating date 'yesterday' as 2006-06-20
+ 13:06:29.152478
+ ...
+
+ When used with '--clamp-mtime' GNU 'tar' will only set the
+ modification date to DATE on files whose actual modification date
+ is later than DATE. This is to make it easy to build reproducible
+ archives given a common timestamp for generated files while still
+ retaining the original timestamps of untouched files.
+
+ $ tar -c -f archive.tar --clamp-mtime --mtime=@$SOURCE_DATE_EPOCH .
+
+'--owner=USER'
+
+ Specifies that 'tar' should use USER as the owner of members when
+ creating archives, instead of the user associated with the source
+ file.
+
+ If USER contains a colon, it is taken to be of the form NAME:ID
+ where a nonempty NAME specifies the user name and a nonempty ID
+ specifies the decimal numeric user ID. If USER does not contain a
+ colon, it is taken to be a user number if it is one or more decimal
+ digits; otherwise it is taken to be a user name.
+
+ If a name is given but no number, the number is inferred from the
+ current host's user database if possible, and the file's user
+ number is used otherwise. If a number is given but no name, the
+ name is inferred from the number if possible, and an empty name is
+ used otherwise. If both name and number are given, the user
+ database is not consulted, and the name and number need not be
+ valid on the current host.
+
+ There is no value indicating a missing number, and '0' usually
+ means 'root'. Some people like to force '0' as the value to offer
+ in their distributions for the owner of files, because the 'root'
+ user is anonymous anyway, so that might as well be the owner of
+ anonymous archives. For example:
+
+ $ tar -c -f archive.tar --owner=0 .
+
+ or:
+
+ $ tar -c -f archive.tar --owner=root .
+
+'--group=GROUP'
+
+ Files added to the 'tar' archive will have a group ID of GROUP,
+ rather than the group from the source file. As with '--owner', the
+ argument GROUP can be an existing group symbolic name, or a decimal
+ numeric group ID, or NAME:ID.
+
+ The '--owner' and '--group' options affect all files added to the
+archive. GNU 'tar' provides also two options that allow for more
+detailed control over owner translation:
+
+'--owner-map=FILE'
+ Read UID translation map from FILE.
+
+ When reading, empty lines are ignored. The '#' sign, unless
+ quoted, introduces a comment, which extends to the end of the line.
+ Each nonempty line defines mapping for a single UID. It must
+ consist of two fields separated by any amount of whitespace. The
+ first field defines original username and UID. It can be a valid
+ user name or a valid UID prefixed with a plus sign. In both cases
+ the corresponding UID or user name is inferred from the current
+ host's user database.
+
+ The second field defines the UID and username to map the original
+ one to. Its format can be the same as described above. Otherwise,
+ it can have the form NEWNAME:NEWUID, in which case neither NEWNAME
+ nor NEWUID are required to be valid as per the user database.
+
+ For example, consider the following file:
+
+ +10 bin
+ smith root:0
+
+ Given this file, each input file that is owner by UID 10 will be
+ stored in archive with owner name 'bin' and owner UID corresponding
+ to 'bin'. Each file owned by user 'smith' will be stored with
+ owner name 'root' and owner ID 0. Other files will remain
+ unchanged.
+
+ When used together with '--owner-map', the '--owner' option affects
+ only files whose owner is not listed in the map file.
+
+'--group-map=FILE'
+ Read GID translation map from FILE.
+
+ The format of FILE is the same as for '--owner-map' option:
+
+ Each nonempty line defines mapping for a single GID. It must
+ consist of two fields separated by any amount of whitespace. The
+ first field defines original group name and GID. It can be a valid
+ group name or a valid GID prefixed with a plus sign. In both cases
+ the corresponding GID or user name is inferred from the current
+ host's group database.
+
+ The second field defines the GID and group name to map the original
+ one to. Its format can be the same as described above. Otherwise,
+ it can have the form NEWNAME:NEWGID, in which case neither NEWNAME
+ nor NEWGID are required to be valid as per the group database.
+
+ When used together with '--group-map', the '--group' option affects
+ only files whose owner group is not rewritten using the map file.
+
+
+File: tar.info, Node: Extended File Attributes, Next: Ignore Failed Read, Prev: override, Up: create options
+
+4.3.2 Extended File Attributes
+------------------------------
+
+Extended file attributes are name-value pairs that can be associated
+with each node in a file system. Despite the fact that POSIX.1e draft
+which proposed them has been withdrawn, the extended file attributes are
+supported by many file systems. GNU 'tar' can store extended file
+attributes along with the files. This feature is controlled by the
+following command line arguments:
+
+'--xattrs'
+ Enable extended attributes support. When used with '--create',
+ this option instructs GNU 'tar' to store extended file attribute in
+ the created archive. This implies POSIX.1-2001 archive format
+ ('--format=pax').
+
+ When used with '--extract', this option tells 'tar', for each file
+ extracted, to read stored attributes from the archive and to apply
+ them to the file.
+
+'--no-xattrs'
+ Disable extended attributes support. This is the default.
+
+ Attribute names are strings prefixed by a "namespace" name and a dot.
+Currently, four namespaces exist: 'user', 'trusted', 'security' and
+'system'. By default, when '--xattr' is used, all names are stored in
+the archive (or extracted, if using '--extract'). This can be
+controlled using the following options:
+
+'--xattrs-exclude=PATTERN'
+ Specify exclude pattern for extended attributes.
+
+'--xattrs-include=PATTERN'
+ Specify include pattern for extended attributes.
+
+ Here, the PATTERN is POSIX regular expression. For example, the
+following command:
+
+ $ tar --xattrs --xattrs-exclude='^user\.' -c a.tar .
+
+ will include in the archive 'a.tar' all attributes, except those from
+the 'user' namespace.
+
+ Any number of these options can be given, thereby creating lists of
+include and exclude patterns.
+
+ When both options are used, first '--xattrs-inlcude' is applied to
+select the set of attribute names to keep, and then '--xattrs-exclude'
+is applied to the resulting set. In other words, only those attributes
+will be stored, whose names match one of the regexps in
+'--xattrs-inlcude' and don't match any of the regexps from
+'--xattrs-exclude'.
+
+ When listing the archive, if both '--xattrs' and '--verbose' options
+are given, files that have extended attributes are marked with an
+asterisk following their permission mask. For example:
+
+ -rw-r--r--* smith/users 110 2016-03-16 16:07 file
+
+ When two or more '--verbose' options are given, a detailed listing of
+extended attributes is printed after each file entry. Each attribute is
+listed on a separate line, which begins with two spaces and the letter
+'x' indicating extended attribute. It is followed by a colon, length of
+the attribute and its name, e.g.:
+
+ -rw-r--r--* smith/users 110 2016-03-16 16:07 file
+ x: 7 user.mime_type
+ x: 32 trusted.md5sum
+
+ File access control lists ("ACL") are another actively used feature
+proposed by the POSIX.1e standard. Each ACL consists of a set of ACL
+entries, each of which describes the access permissions on the file for
+an individual user or a group of users as a combination of read, write
+and search/execute permissions.
+
+ Whether or not to use ACLs is controlled by the following two
+options:
+
+'--acls'
+ Enable POSIX ACLs support. When used with '--create', this option
+ instructs GNU 'tar' to store ACLs in the created archive. This
+ implies POSIX.1-2001 archive format ('--format=pax').
+
+ When used with '--extract', this option tells 'tar', to restore
+ ACLs for each file extracted (provided they are present in the
+ archive).
+
+'--no-acls'
+ Disable POSIX ACLs support. This is the default.
+
+ When listing the archive, if both '--acls' and '--verbose' options
+are given, files that have ACLs are marked with a plus sing following
+their permission mask. For example:
+
+ -rw-r--r--+ smith/users 110 2016-03-16 16:07 file
+
+ When two or more '--verbose' options are given, a detailed listing of
+ACL is printed after each file entry:
+
+ -rw-r--r--+ smith/users 110 2016-03-16 16:07 file
+ a: user::rw-,user:gray:-w-,group::r--,mask::rw-,other::r--
+
+ "Security-Enhanced Linux" ("SELinux" for short) is a Linux kernel
+security module that provides a mechanism for supporting access control
+security policies, including so-called mandatory access controls
+("MAC"). Support for SELinux attributes is controlled by the following
+command line options:
+
+'--selinux'
+ Enable the SELinux context support.
+
+'--no-selinux'
+ Disable SELinux context support.
+
+
+File: tar.info, Node: Ignore Failed Read, Prev: Extended File Attributes, Up: create options
+
+4.3.3 Ignore Fail Read
+----------------------
+
+'--ignore-failed-read'
+ Do not exit with nonzero on unreadable files or directories.
+
+
+File: tar.info, Node: extract options, Next: backup, Prev: create options, Up: operations
+
+4.4 Options Used by '--extract'
+===============================
+
+The previous chapter showed how to use '--extract' to extract an archive
+into the file system. Various options cause 'tar' to extract more
+information than just file contents, such as the owner, the permissions,
+the modification date, and so forth. This section presents options to
+be used with '--extract' when certain special considerations arise. You
+may review the information presented in *note extract:: for more basic
+information about the '--extract' operation.
+
+* Menu:
+
+* Reading:: Options to Help Read Archives
+* Writing:: Changing How 'tar' Writes Files
+* Scarce:: Coping with Scarce Resources
+
+
+File: tar.info, Node: Reading, Next: Writing, Up: extract options
+
+4.4.1 Options to Help Read Archives
+-----------------------------------
+
+Normally, 'tar' will request data in full record increments from an
+archive storage device. If the device cannot return a full record,
+'tar' will report an error. However, some devices do not always return
+full records, or do not require the last record of an archive to be
+padded out to the next record boundary. To keep reading until you
+obtain a full record, or to accept an incomplete record if it contains
+an end-of-archive marker, specify the '--read-full-records' ('-B')
+option in conjunction with the '--extract' or '--list' operations.
+*Note Blocking::.
+
+ The '--read-full-records' ('-B') option is turned on by default when
+'tar' reads an archive from standard input, or from a remote machine.
+This is because on BSD Unix systems, attempting to read a pipe returns
+however much happens to be in the pipe, even if it is less than was
+requested. If this option were not enabled, 'tar' would fail as soon as
+it read an incomplete record from the pipe.
+
+ If you're not sure of the blocking factor of an archive, you can read
+the archive by specifying '--read-full-records' ('-B') and
+'--blocking-factor=512-SIZE' ('-b 512-SIZE'), using a blocking factor
+larger than what the archive uses. This lets you avoid having to
+determine the blocking factor of an archive. *Note Blocking Factor::.
+
+* Menu:
+
+* read full records::
+* Ignore Zeros::
+
+
+File: tar.info, Node: read full records, Next: Ignore Zeros, Up: Reading
+
+Reading Full Records
+....................
+
+'--read-full-records'
+'-B'
+ Use in conjunction with '--extract' ('--get', '-x') to read an
+ archive which contains incomplete records, or one which has a
+ blocking factor less than the one specified.
+
+
+File: tar.info, Node: Ignore Zeros, Prev: read full records, Up: Reading
+
+Ignoring Blocks of Zeros
+........................
+
+Normally, 'tar' stops reading when it encounters a block of zeros
+between file entries (which usually indicates the end of the archive).
+'--ignore-zeros' ('-i') allows 'tar' to completely read an archive which
+contains a block of zeros before the end (i.e., a damaged archive, or
+one that was created by concatenating several archives together).
+
+ The '--ignore-zeros' ('-i') option is turned off by default because
+many versions of 'tar' write garbage after the end-of-archive entry,
+since that part of the media is never supposed to be read. GNU 'tar'
+does not write after the end of an archive, but seeks to maintain
+compatibility among archiving utilities.
+
+'--ignore-zeros'
+'-i'
+ To ignore blocks of zeros (i.e., end-of-archive entries) which may
+ be encountered while reading an archive. Use in conjunction with
+ '--extract' or '--list'.
+
+
+File: tar.info, Node: Writing, Next: Scarce, Prev: Reading, Up: extract options
+
+4.4.2 Changing How 'tar' Writes Files
+-------------------------------------
+
+ _(This message will disappear, once this node revised.)_
+
+* Menu:
+
+* Dealing with Old Files::
+* Overwrite Old Files::
+* Keep Old Files::
+* Keep Newer Files::
+* Unlink First::
+* Recursive Unlink::
+* Data Modification Times::
+* Setting Access Permissions::
+* Directory Modification Times and Permissions::
+* Writing to Standard Output::
+* Writing to an External Program::
+* remove files::
+
+
+File: tar.info, Node: Dealing with Old Files, Next: Overwrite Old Files, Up: Writing
+
+Options Controlling the Overwriting of Existing Files
+.....................................................
+
+When extracting files, if 'tar' discovers that the extracted file
+already exists, it normally replaces the file by removing it before
+extracting it, to prevent confusion in the presence of hard or symbolic
+links. (If the existing file is a symbolic link, it is removed, not
+followed.) However, if a directory cannot be removed because it is
+nonempty, 'tar' normally overwrites its metadata (ownership, permission,
+etc.). The '--overwrite-dir' option enables this default behavior. To
+be more cautious and preserve the metadata of such a directory, use the
+'--no-overwrite-dir' option.
+
+ To be even more cautious and prevent existing files from being
+replaced, use the '--keep-old-files' ('-k') option. It causes 'tar' to
+refuse to replace or update a file that already exists, i.e., a file
+with the same name as an archive member prevents extraction of that
+archive member. Instead, it reports an error. For example:
+
+ $ ls
+ blues
+ $ tar -x -k -f archive.tar
+ tar: blues: Cannot open: File exists
+ tar: Exiting with failure status due to previous errors
+
+ If you wish to preserve old files untouched, but don't want 'tar' to
+treat them as errors, use the '--skip-old-files' option. This option
+causes 'tar' to silently skip extracting over existing files.
+
+ To be more aggressive about altering existing files, use the
+'--overwrite' option. It causes 'tar' to overwrite existing files and
+to follow existing symbolic links when extracting.
+
+ Some people argue that GNU 'tar' should not hesitate to overwrite
+files with other files when extracting. When extracting a 'tar'
+archive, they expect to see a faithful copy of the state of the file
+system when the archive was created. It is debatable that this would
+always be a proper behavior. For example, suppose one has an archive in
+which 'usr/local' is a link to 'usr/local2'. Since then, maybe the site
+removed the link and renamed the whole hierarchy from '/usr/local2' to
+'/usr/local'. Such things happen all the time. I guess it would not be
+welcome at all that GNU 'tar' removes the whole hierarchy just to make
+room for the link to be reinstated (unless it _also_ simultaneously
+restores the full '/usr/local2', of course!) GNU 'tar' is indeed able
+to remove a whole hierarchy to reestablish a symbolic link, for example,
+but _only if_ '--recursive-unlink' is specified to allow this behavior.
+In any case, single files are silently removed.
+
+ Finally, the '--unlink-first' ('-U') option can improve performance
+in some cases by causing 'tar' to remove files unconditionally before
+extracting them.
+
+
+File: tar.info, Node: Overwrite Old Files, Next: Keep Old Files, Prev: Dealing with Old Files, Up: Writing
+
+Overwrite Old Files
+...................
+
+'--overwrite'
+ Overwrite existing files and directory metadata when extracting
+ files from an archive.
+
+ This causes 'tar' to write extracted files into the file system
+ without regard to the files already on the system; i.e., files with
+ the same names as archive members are overwritten when the archive
+ is extracted. It also causes 'tar' to extract the ownership,
+ permissions, and time stamps onto any preexisting files or
+ directories. If the name of a corresponding file name is a
+ symbolic link, the file pointed to by the symbolic link will be
+ overwritten instead of the symbolic link itself (if this is
+ possible). Moreover, special devices, empty directories and even
+ symbolic links are automatically removed if they are in the way of
+ extraction.
+
+ Be careful when using the '--overwrite' option, particularly when
+ combined with the '--absolute-names' ('-P') option, as this
+ combination can change the contents, ownership or permissions of
+ any file on your system. Also, many systems do not take kindly to
+ overwriting files that are currently being executed.
+
+'--overwrite-dir'
+ Overwrite the metadata of directories when extracting files from an
+ archive, but remove other files before extracting.
+
+
+File: tar.info, Node: Keep Old Files, Next: Keep Newer Files, Prev: Overwrite Old Files, Up: Writing
+
+Keep Old Files
+..............
+
+GNU 'tar' provides two options to control its actions in a situation
+when it is about to extract a file which already exists on disk.
+
+'--keep-old-files'
+'-k'
+ Do not replace existing files from archive. When such a file is
+ encountered, 'tar' issues an error message. Upon end of
+ extraction, 'tar' exits with code 2 (*note exit status::).
+
+'--skip-old-files'
+ Do not replace existing files from archive, but do not treat that
+ as error. Such files are silently skipped and do not affect 'tar'
+ exit status.
+
+ Additional verbosity can be obtained using
+ '--warning=existing-file' together with that option (*note
+ warnings::).
+
+
+File: tar.info, Node: Keep Newer Files, Next: Unlink First, Prev: Keep Old Files, Up: Writing
+
+Keep Newer Files
+................
+
+'--keep-newer-files'
+ Do not replace existing files that are newer than their archive
+ copies. This option is meaningless with '--list' ('-t').
+
+
+File: tar.info, Node: Unlink First, Next: Recursive Unlink, Prev: Keep Newer Files, Up: Writing
+
+Unlink First
+............
+
+'--unlink-first'
+'-U'
+ Remove files before extracting over them. This can make 'tar' run
+ a bit faster if you know in advance that the extracted files all
+ need to be removed. Normally this option slows 'tar' down
+ slightly, so it is disabled by default.
+
+
+File: tar.info, Node: Recursive Unlink, Next: Data Modification Times, Prev: Unlink First, Up: Writing
+
+Recursive Unlink
+................
+
+'--recursive-unlink'
+ When this option is specified, try removing files and directory
+ hierarchies before extracting over them. _This is a dangerous
+ option!_
+
+ If you specify the '--recursive-unlink' option, 'tar' removes
+_anything_ that keeps you from extracting a file as far as current
+permissions will allow it. This could include removal of the contents
+of a full directory hierarchy.
+
+
+File: tar.info, Node: Data Modification Times, Next: Setting Access Permissions, Prev: Recursive Unlink, Up: Writing
+
+Setting Data Modification Times
+...............................
+
+Normally, 'tar' sets the data modification times of extracted files to
+the corresponding times recorded for the files in the archive, but
+limits the permissions of extracted files by the current 'umask'
+setting.
+
+ To set the data modification times of extracted files to the time
+when the files were extracted, use the '--touch' ('-m') option in
+conjunction with '--extract' ('--get', '-x').
+
+'--touch'
+'-m'
+ Sets the data modification time of extracted archive members to the
+ time they were extracted, not the time recorded for them in the
+ archive. Use in conjunction with '--extract' ('--get', '-x').
+
+
+File: tar.info, Node: Setting Access Permissions, Next: Directory Modification Times and Permissions, Prev: Data Modification Times, Up: Writing
+
+Setting Access Permissions
+..........................
+
+To set the modes (access permissions) of extracted files to those
+recorded for those files in the archive, use '--same-permissions' in
+conjunction with the '--extract' ('--get', '-x') operation.
+
+'--preserve-permissions'
+'--same-permissions'
+'-p'
+ Set modes of extracted archive members to those recorded in the
+ archive, instead of current umask settings. Use in conjunction
+ with '--extract' ('--get', '-x').
+
+
+File: tar.info, Node: Directory Modification Times and Permissions, Next: Writing to Standard Output, Prev: Setting Access Permissions, Up: Writing
+
+Directory Modification Times and Permissions
+............................................
+
+After successfully extracting a file member, GNU 'tar' normally restores
+its permissions and modification times, as described in the previous
+sections. This cannot be done for directories, because after extracting
+a directory 'tar' will almost certainly extract files into that
+directory and this will cause the directory modification time to be
+updated. Moreover, restoring that directory permissions may not permit
+file creation within it. Thus, restoring directory permissions and
+modification times must be delayed at least until all files have been
+extracted into that directory. GNU 'tar' restores directories using the
+following approach.
+
+ The extracted directories are created with the mode specified in the
+archive, as modified by the umask of the user, which gives sufficient
+permissions to allow file creation. The meta-information about the
+directory is recorded in the temporary list of directories. When
+preparing to extract next archive member, GNU 'tar' checks if the
+directory prefix of this file contains the remembered directory. If it
+does not, the program assumes that all files have been extracted into
+that directory, restores its modification time and permissions and
+removes its entry from the internal list. This approach allows to
+correctly restore directory meta-information in the majority of cases,
+while keeping memory requirements sufficiently small. It is based on
+the fact, that most 'tar' archives use the predefined order of members:
+first the directory, then all the files and subdirectories in that
+directory.
+
+ However, this is not always true. The most important exception are
+incremental archives (*note Incremental Dumps::). The member order in
+an incremental archive is reversed: first all directory members are
+stored, followed by other (non-directory) members. So, when extracting
+from incremental archives, GNU 'tar' alters the above procedure. It
+remembers all restored directories, and restores their meta-data only
+after the entire archive has been processed. Notice, that you do not
+need to specify any special options for that, as GNU 'tar' automatically
+detects archives in incremental format.
+
+ There may be cases, when such processing is required for normal
+archives too. Consider the following example:
+
+ $ tar --no-recursion -cvf archive \
+ foo foo/file1 bar bar/file foo/file2
+ foo/
+ foo/file1
+ bar/
+ bar/file
+ foo/file2
+
+ During the normal operation, after encountering 'bar' GNU 'tar' will
+assume that all files from the directory 'foo' were already extracted
+and will therefore restore its timestamp and permission bits. However,
+after extracting 'foo/file2' the directory timestamp will be offset
+again.
+
+ To correctly restore directory meta-information in such cases, use
+the '--delay-directory-restore' command line option:
+
+'--delay-directory-restore'
+ Delays restoring of the modification times and permissions of
+ extracted directories until the end of extraction. This way,
+ correct meta-information is restored even if the archive has
+ unusual member ordering.
+
+'--no-delay-directory-restore'
+ Cancel the effect of the previous '--delay-directory-restore'. Use
+ this option if you have used '--delay-directory-restore' in
+ 'TAR_OPTIONS' variable (*note TAR_OPTIONS::) and wish to
+ temporarily disable it.
+
+
+File: tar.info, Node: Writing to Standard Output, Next: Writing to an External Program, Prev: Directory Modification Times and Permissions, Up: Writing
+
+Writing to Standard Output
+..........................
+
+To write the extracted files to the standard output, instead of creating
+the files on the file system, use '--to-stdout' ('-O') in conjunction
+with '--extract' ('--get', '-x'). This option is useful if you are
+extracting files to send them through a pipe, and do not need to
+preserve them in the file system. If you extract multiple members, they
+appear on standard output concatenated, in the order they are found in
+the archive.
+
+'--to-stdout'
+'-O'
+ Writes files to the standard output. Use only in conjunction with
+ '--extract' ('--get', '-x'). When this option is used, instead of
+ creating the files specified, 'tar' writes the contents of the
+ files extracted to its standard output. This may be useful if you
+ are only extracting the files in order to send them through a pipe.
+ This option is meaningless with '--list' ('-t').
+
+ This can be useful, for example, if you have a tar archive containing
+a big file and don't want to store the file on disk before processing
+it. You can use a command like this:
+
+ tar -xOzf foo.tgz bigfile | process
+
+ or even like this if you want to process the concatenation of the
+files:
+
+ tar -xOzf foo.tgz bigfile1 bigfile2 | process
+
+ However, '--to-command' may be more convenient for use with multiple
+files. See the next section.
+
+
+File: tar.info, Node: Writing to an External Program, Next: remove files, Prev: Writing to Standard Output, Up: Writing
+
+Writing to an External Program
+..............................
+
+You can instruct 'tar' to send the contents of each extracted file to
+the standard input of an external program:
+
+'--to-command=COMMAND'
+ Extract files and pipe their contents to the standard input of
+ COMMAND. When this option is used, instead of creating the files
+ specified, 'tar' invokes COMMAND and pipes the contents of the
+ files to its standard output. The COMMAND may contain command line
+ arguments (see *note Running External Commands: external, for more
+ detail).
+
+ Notice, that COMMAND is executed once for each regular file
+ extracted. Non-regular files (directories, etc.) are ignored when
+ this option is used.
+
+ The command can obtain the information about the file it processes
+from the following environment variables:
+
+'TAR_FILETYPE'
+ Type of the file. It is a single letter with the following
+ meaning:
+
+ f Regular file
+ d Directory
+ l Symbolic link
+ h Hard link
+ b Block device
+ c Character device
+
+ Currently only regular files are supported.
+
+'TAR_MODE'
+ File mode, an octal number.
+
+'TAR_FILENAME'
+ The name of the file.
+
+'TAR_REALNAME'
+ Name of the file as stored in the archive.
+
+'TAR_UNAME'
+ Name of the file owner.
+
+'TAR_GNAME'
+ Name of the file owner group.
+
+'TAR_ATIME'
+ Time of last access. It is a decimal number, representing seconds
+ since the Epoch. If the archive provides times with nanosecond
+ precision, the nanoseconds are appended to the timestamp after a
+ decimal point.
+
+'TAR_MTIME'
+ Time of last modification.
+
+'TAR_CTIME'
+ Time of last status change.
+
+'TAR_SIZE'
+ Size of the file.
+
+'TAR_UID'
+ UID of the file owner.
+
+'TAR_GID'
+ GID of the file owner.
+
+ Additionally, the following variables contain information about tar
+mode and the archive being processed:
+
+'TAR_VERSION'
+ GNU 'tar' version number.
+
+'TAR_ARCHIVE'
+ The name of the archive 'tar' is processing.
+
+'TAR_BLOCKING_FACTOR'
+ Current blocking factor (*note Blocking::).
+
+'TAR_VOLUME'
+ Ordinal number of the volume 'tar' is processing.
+
+'TAR_FORMAT'
+ Format of the archive being processed. *Note Formats::, for a
+ complete list of archive format names.
+
+ These variables are defined prior to executing the command, so you
+can pass them as arguments, if you prefer. For example, if the command
+PROC takes the member name and size as its arguments, then you could do:
+
+ $ tar -x -f archive.tar \
+ --to-command='proc $TAR_FILENAME $TAR_SIZE'
+
+Notice single quotes to prevent variable names from being expanded by
+the shell when invoking 'tar'.
+
+ If COMMAND exits with a non-0 status, 'tar' will print an error
+message similar to the following:
+
+ tar: 2345: Child returned status 1
+
+ Here, '2345' is the PID of the finished process.
+
+ If this behavior is not wanted, use '--ignore-command-error':
+
+'--ignore-command-error'
+ Ignore exit codes of subprocesses. Notice that if the program
+ exits on signal or otherwise terminates abnormally, the error
+ message will be printed even if this option is used.
+
+'--no-ignore-command-error'
+ Cancel the effect of any previous '--ignore-command-error' option.
+ This option is useful if you have set '--ignore-command-error' in
+ 'TAR_OPTIONS' (*note TAR_OPTIONS::) and wish to temporarily cancel
+ it.
+
+
+File: tar.info, Node: remove files, Prev: Writing to an External Program, Up: Writing
+
+Removing Files
+..............
+
+'--remove-files'
+ Remove files after adding them to the archive.
+
+
+File: tar.info, Node: Scarce, Prev: Writing, Up: extract options
+
+4.4.3 Coping with Scarce Resources
+----------------------------------
+
+ _(This message will disappear, once this node revised.)_
+
+* Menu:
+
+* Starting File::
+* Same Order::
+
+
+File: tar.info, Node: Starting File, Next: Same Order, Up: Scarce
+
+Starting File
+.............
+
+'--starting-file=NAME'
+'-K NAME'
+ Starts an operation in the middle of an archive. Use in
+ conjunction with '--extract' ('--get', '-x') or '--list' ('-t').
+
+ If a previous attempt to extract files failed due to lack of disk
+space, you can use '--starting-file=NAME' ('-K NAME') to start
+extracting only after member NAME of the archive. This assumes, of
+course, that there is now free space, or that you are now extracting
+into a different file system. (You could also choose to suspend 'tar',
+remove unnecessary files from the file system, and then resume the same
+'tar' operation. In this case, '--starting-file' is not necessary.)
+See also *note interactive::, and *note exclude::.
+
+
+File: tar.info, Node: Same Order, Prev: Starting File, Up: Scarce
+
+Same Order
+..........
+
+'--same-order'
+'--preserve-order'
+'-s'
+ To process large lists of file names on machines with small amounts
+ of memory. Use in conjunction with '--compare' ('--diff', '-d'),
+ '--list' ('-t') or '--extract' ('--get', '-x').
+
+ The '--same-order' ('--preserve-order', '-s') option tells 'tar' that
+the list of file names to be listed or extracted is sorted in the same
+order as the files in the archive. This allows a large list of names to
+be used, even on a small machine that would not otherwise be able to
+hold all the names in memory at the same time. Such a sorted list can
+easily be created by running 'tar -t' on the archive and editing its
+output.
+
+ This option is probably never needed on modern computer systems.
+
+
+File: tar.info, Node: backup, Next: Applications, Prev: extract options, Up: operations
+
+4.5 Backup options
+==================
+
+GNU 'tar' offers options for making backups of files before writing new
+versions. These options control the details of these backups. They may
+apply to the archive itself before it is created or rewritten, as well
+as individual extracted members. Other GNU programs ('cp', 'install',
+'ln', and 'mv', for example) offer similar options.
+
+ Backup options may prove unexpectedly useful when extracting archives
+containing many members having identical name, or when extracting
+archives on systems having file name limitations, making different
+members appear as having similar names through the side-effect of name
+truncation.
+
+ When any existing file is backed up before being overwritten by
+extraction, then clashing files are automatically be renamed to be
+unique, and the true name is kept for only the last file of a series of
+clashing files. By using verbose mode, users may track exactly what
+happens.
+
+ At the detail level, some decisions are still experimental, and may
+change in the future, we are waiting comments from our users. So,
+please do not learn to depend blindly on the details of the backup
+features. For example, currently, directories themselves are never
+renamed through using these options, so, extracting a file over a
+directory still has good chances to fail. Also, backup options apply to
+created archives, not only to extracted members. For created archives,
+backups will not be attempted when the archive is a block or character
+device, or when it refers to a remote file.
+
+ For the sake of simplicity and efficiency, backups are made by
+renaming old files prior to creation or extraction, and not by copying.
+The original name is restored if the file creation fails. If a failure
+occurs after a partial extraction of a file, both the backup and the
+partially extracted file are kept.
+
+'--backup[=METHOD]'
+ Back up files that are about to be overwritten or removed. Without
+ this option, the original versions are destroyed.
+
+ Use METHOD to determine the type of backups made. If METHOD is not
+ specified, use the value of the 'VERSION_CONTROL' environment
+ variable. And if 'VERSION_CONTROL' is not set, use the 'existing'
+ method.
+
+ This option corresponds to the Emacs variable 'version-control';
+ the same values for METHOD are accepted as in Emacs. This option
+ also allows more descriptive names. The valid METHODs are:
+
+ 't'
+ 'numbered'
+ Always make numbered backups.
+
+ 'nil'
+ 'existing'
+ Make numbered backups of files that already have them, simple
+ backups of the others.
+
+ 'never'
+ 'simple'
+ Always make simple backups.
+
+'--suffix=SUFFIX'
+ Append SUFFIX to each backup file made with '--backup'. If this
+ option is not specified, the value of the 'SIMPLE_BACKUP_SUFFIX'
+ environment variable is used. And if 'SIMPLE_BACKUP_SUFFIX' is not
+ set, the default is '~', just as in Emacs.
+
+
+File: tar.info, Node: Applications, Next: looking ahead, Prev: backup, Up: operations
+
+4.6 Notable 'tar' Usages
+========================
+
+ _(This message will disappear, once this node revised.)_
+
+ You can easily use archive files to transport a group of files from
+one system to another: put all relevant files into an archive on one
+computer system, transfer the archive to another system, and extract the
+contents there. The basic transfer medium might be magnetic tape,
+Internet FTP, or even electronic mail (though you must encode the
+archive with 'uuencode' in order to transport it properly by mail).
+Both machines do not have to use the same operating system, as long as
+they both support the 'tar' program.
+
+ For example, here is how you might copy a directory's contents from
+one disk to another, while preserving the dates, modes, owners and
+link-structure of all the files therein. In this case, the transfer
+medium is a "pipe":
+
+ $ (cd sourcedir; tar -cf - .) | (cd targetdir; tar -xf -)
+
+You can avoid subshells by using '-C' option:
+
+ $ tar -C sourcedir -cf - . | tar -C targetdir -xf -
+
+The command also works using long option forms:
+
+ $ (cd sourcedir; tar --create --file=- . ) \
+ | (cd targetdir; tar --extract --file=-)
+
+or
+
+ $ tar --directory sourcedir --create --file=- . \
+ | tar --directory targetdir --extract --file=-
+
+This is one of the easiest methods to transfer a 'tar' archive.
+
+
+File: tar.info, Node: looking ahead, Prev: Applications, Up: operations
+
+4.7 Looking Ahead: The Rest of this Manual
+==========================================
+
+You have now seen how to use all eight of the operations available to
+'tar', and a number of the possible options. The next chapter explains
+how to choose and change file and archive names, how to use files to
+store names of other files which you can then call as arguments to 'tar'
+(this can help you save time if you expect to archive the same list of
+files a number of times), and so forth.
+
+ If there are too many files to conveniently list on the command line,
+you can list the names in a file, and 'tar' will read that file. *Note
+files::.
+
+ There are various ways of causing 'tar' to skip over some files, and
+not archive them. *Note Choosing::.
+
+
+File: tar.info, Node: Backups, Next: Choosing, Prev: operations, Up: Top
+
+5 Performing Backups and Restoring Files
+****************************************
+
+GNU 'tar' is distributed along with the scripts for performing backups
+and restores. Even if there is a good chance those scripts may be
+satisfying to you, they are not the only scripts or methods available
+for doing backups and restore. You may well create your own, or use
+more sophisticated packages dedicated to that purpose.
+
+ Some users are enthusiastic about 'Amanda' (The Advanced Maryland
+Automatic Network Disk Archiver), a backup system developed by James da
+Silva 'jds@cs.umd.edu' and available on many Unix systems. This is free
+software, and it is available from <http://www.amanda.org>.
+
+ This chapter documents both the provided shell scripts and 'tar'
+options which are more specific to usage as a backup tool.
+
+ To "back up" a file system means to create archives that contain all
+the files in that file system. Those archives can then be used to
+restore any or all of those files (for instance if a disk crashes or a
+file is accidentally deleted). File system "backups" are also called
+"dumps".
+
+* Menu:
+
+* Full Dumps:: Using 'tar' to Perform Full Dumps
+* Incremental Dumps:: Using 'tar' to Perform Incremental Dumps
+* Backup Levels:: Levels of Backups
+* Backup Parameters:: Setting Parameters for Backups and Restoration
+* Scripted Backups:: Using the Backup Scripts
+* Scripted Restoration:: Using the Restore Script
+
+
+File: tar.info, Node: Full Dumps, Next: Incremental Dumps, Up: Backups
+
+5.1 Using 'tar' to Perform Full Dumps
+=====================================
+
+ _(This message will disappear, once this node revised.)_
+
+ Full dumps should only be made when no other people or programs are
+modifying files in the file system. If files are modified while 'tar'
+is making the backup, they may not be stored properly in the archive, in
+which case you won't be able to restore them if you have to. (Files not
+being modified are written with no trouble, and do not corrupt the
+entire archive.)
+
+ You will want to use the '--label=ARCHIVE-LABEL' ('-V ARCHIVE-LABEL')
+option to give the archive a volume label, so you can tell what this
+archive is even if the label falls off the tape, or anything like that.
+
+ Unless the file system you are dumping is guaranteed to fit on one
+volume, you will need to use the '--multi-volume' ('-M') option. Make
+sure you have enough tapes on hand to complete the backup.
+
+ If you want to dump each file system separately you will need to use
+the '--one-file-system' option to prevent 'tar' from crossing file
+system boundaries when storing (sub)directories.
+
+ The '--incremental' ('-G') (*note Incremental Dumps::) option is not
+needed, since this is a complete copy of everything in the file system,
+and a full restore from this backup would only be done onto a completely
+empty disk.
+
+ Unless you are in a hurry, and trust the 'tar' program (and your
+tapes), it is a good idea to use the '--verify' ('-W') option, to make
+sure your files really made it onto the dump properly. This will also
+detect cases where the file was modified while (or just after) it was
+being archived. Not all media (notably cartridge tapes) are capable of
+being verified, unfortunately.
+
+
+File: tar.info, Node: Incremental Dumps, Next: Backup Levels, Prev: Full Dumps, Up: Backups
+
+5.2 Using 'tar' to Perform Incremental Dumps
+============================================
+
+"Incremental backup" is a special form of GNU 'tar' archive that stores
+additional metadata so that exact state of the file system can be
+restored when extracting the archive.
+
+ GNU 'tar' currently offers two options for handling incremental
+backups: '--listed-incremental=SNAPSHOT-FILE' ('-g SNAPSHOT-FILE') and
+'--incremental' ('-G').
+
+ The option '--listed-incremental' instructs tar to operate on an
+incremental archive with additional metadata stored in a standalone
+file, called a "snapshot file". The purpose of this file is to help
+determine which files have been changed, added or deleted since the last
+backup, so that the next incremental backup will contain only modified
+files. The name of the snapshot file is given as an argument to the
+option:
+
+'--listed-incremental=FILE'
+'-g FILE'
+ Handle incremental backups with snapshot data in FILE.
+
+ To create an incremental backup, you would use '--listed-incremental'
+together with '--create' (*note create::). For example:
+
+ $ tar --create \
+ --file=archive.1.tar \
+ --listed-incremental=/var/log/usr.snar \
+ /usr
+
+ This will create in 'archive.1.tar' an incremental backup of the
+'/usr' file system, storing additional metadata in the file
+'/var/log/usr.snar'. If this file does not exist, it will be created.
+The created archive will then be a "level 0 backup"; please see the next
+section for more on backup levels.
+
+ Otherwise, if the file '/var/log/usr.snar' exists, it determines
+which files are modified. In this case only these files will be stored
+in the archive. Suppose, for example, that after running the above
+command, you delete file '/usr/doc/old' and create directory
+'/usr/local/db' with the following contents:
+
+ $ ls /usr/local/db
+ /usr/local/db/data
+ /usr/local/db/index
+
+ Some time later you create another incremental backup. You will then
+see:
+
+ $ tar --create \
+ --file=archive.2.tar \
+ --listed-incremental=/var/log/usr.snar \
+ /usr
+ tar: usr/local/db: Directory is new
+ usr/local/db/
+ usr/local/db/data
+ usr/local/db/index
+
+The created archive 'archive.2.tar' will contain only these three
+members. This archive is called a "level 1 backup". Notice that
+'/var/log/usr.snar' will be updated with the new data, so if you plan to
+create more 'level 1' backups, it is necessary to create a working copy
+of the snapshot file before running 'tar'. The above example will then
+be modified as follows:
+
+ $ cp /var/log/usr.snar /var/log/usr.snar-1
+ $ tar --create \
+ --file=archive.2.tar \
+ --listed-incremental=/var/log/usr.snar-1 \
+ /usr
+
+ You can force 'level 0' backups either by removing the snapshot file
+before running 'tar', or by supplying the '--level=0' option, e.g.:
+
+ $ tar --create \
+ --file=archive.2.tar \
+ --listed-incremental=/var/log/usr.snar-0 \
+ --level=0 \
+ /usr
+
+ Incremental dumps depend crucially on time stamps, so the results are
+unreliable if you modify a file's time stamps during dumping (e.g., with
+the '--atime-preserve=replace' option), or if you set the clock
+backwards.
+
+ Metadata stored in snapshot files include device numbers, which,
+obviously are supposed to be non-volatile values. However, it turns out
+that NFS devices have undependable values when an automounter gets in
+the picture. This can lead to a great deal of spurious redumping in
+incremental dumps, so it is somewhat useless to compare two NFS devices
+numbers over time. The solution implemented currently is to consider
+all NFS devices as being equal when it comes to comparing directories;
+this is fairly gross, but there does not seem to be a better way to go.
+
+ Apart from using NFS, there are a number of cases where relying on
+device numbers can cause spurious redumping of unmodified files. For
+example, this occurs when archiving LVM snapshot volumes. To avoid
+this, use '--no-check-device' option:
+
+'--no-check-device'
+ Do not rely on device numbers when preparing a list of changed
+ files for an incremental dump.
+
+'--check-device'
+ Use device numbers when preparing a list of changed files for an
+ incremental dump. This is the default behavior. The purpose of
+ this option is to undo the effect of the '--no-check-device' if it
+ was given in 'TAR_OPTIONS' environment variable (*note
+ TAR_OPTIONS::).
+
+ There is also another way to cope with changing device numbers. It
+is described in detail in *note Fixing Snapshot Files::.
+
+ Note that incremental archives use 'tar' extensions and may not be
+readable by non-GNU versions of the 'tar' program.
+
+ To extract from the incremental dumps, use '--listed-incremental'
+together with '--extract' option (*note extracting files::). In this
+case, 'tar' does not need to access snapshot file, since all the data
+necessary for extraction are stored in the archive itself. So, when
+extracting, you can give whatever argument to '--listed-incremental',
+the usual practice is to use '--listed-incremental=/dev/null'.
+Alternatively, you can use '--incremental', which needs no arguments.
+In general, '--incremental' ('-G') can be used as a shortcut for
+'--listed-incremental' when listing or extracting incremental backups
+(for more information regarding this option, *note incremental-op::).
+
+ When extracting from the incremental backup GNU 'tar' attempts to
+restore the exact state the file system had when the archive was
+created. In particular, it will _delete_ those files in the file system
+that did not exist in their directories when the archive was created.
+If you have created several levels of incremental files, then in order
+to restore the exact contents the file system had when the last level
+was created, you will need to restore from all backups in turn.
+Continuing our example, to restore the state of '/usr' file system, one
+would do(1):
+
+ $ tar --extract \
+ --listed-incremental=/dev/null \
+ --file archive.1.tar
+ $ tar --extract \
+ --listed-incremental=/dev/null \
+ --file archive.2.tar
+
+ To list the contents of an incremental archive, use '--list' (*note
+list::), as usual. To obtain more information about the archive, use
+'--listed-incremental' or '--incremental' combined with two '--verbose'
+options(2):
+
+ tar --list --incremental --verbose --verbose --file archive.tar
+
+ This command will print, for each directory in the archive, the list
+of files in that directory at the time the archive was created. This
+information is put out in a format which is both human-readable and
+unambiguous for a program: each file name is printed as
+
+ X FILE
+
+where X is a letter describing the status of the file: 'Y' if the file
+is present in the archive, 'N' if the file is not included in the
+archive, or a 'D' if the file is a directory (and is included in the
+archive). *Note Dumpdir::, for the detailed description of dumpdirs and
+status codes. Each such line is terminated by a newline character. The
+last line is followed by an additional newline to indicate the end of
+the data.
+
+ The option '--incremental' ('-G') gives the same behavior as
+'--listed-incremental' when used with '--list' and '--extract' options.
+When used with '--create' option, it creates an incremental archive
+without creating snapshot file. Thus, it is impossible to create
+several levels of incremental backups with '--incremental' option.
+
+ ---------- Footnotes ----------
+
+ (1) Notice, that since both archives were created without '-P' option
+(*note absolute::), these commands should be run from the root file
+system.
+
+ (2) Two '--verbose' options were selected to avoid breaking usual
+verbose listing output ('--list --verbose') when using in scripts.
+
+ Versions of GNU 'tar' up to 1.15.1 used to dump verbatim binary
+contents of the DUMPDIR header (with terminating nulls) when
+'--incremental' or '--listed-incremental' option was given, no matter
+what the verbosity level. This behavior, and, especially, the binary
+output it produced were considered inconvenient and were changed in
+version 1.16.
+
+
+File: tar.info, Node: Backup Levels, Next: Backup Parameters, Prev: Incremental Dumps, Up: Backups
+
+5.3 Levels of Backups
+=====================
+
+An archive containing all the files in the file system is called a "full
+backup" or "full dump". You could insure your data by creating a full
+dump every day. This strategy, however, would waste a substantial
+amount of archive media and user time, as unchanged files are daily
+re-archived.
+
+ It is more efficient to do a full dump only occasionally. To back up
+files between full dumps, you can use "incremental dumps". A "level
+one" dump archives all the files that have changed since the last full
+dump.
+
+ A typical dump strategy would be to perform a full dump once a week,
+and a level one dump once a day. This means some versions of files will
+in fact be archived more than once, but this dump strategy makes it
+possible to restore a file system to within one day of accuracy by only
+extracting two archives--the last weekly (full) dump and the last daily
+(level one) dump. The only information lost would be in files changed
+or created since the last daily backup. (Doing dumps more than once a
+day is usually not worth the trouble.)
+
+ GNU 'tar' comes with scripts you can use to do full and level-one
+(actually, even level-two and so on) dumps. Using scripts (shell
+programs) to perform backups and restoration is a convenient and
+reliable alternative to typing out file name lists and 'tar' commands by
+hand.
+
+ Before you use these scripts, you need to edit the file
+'backup-specs', which specifies parameters used by the backup scripts
+and by the restore script. This file is usually located in
+'/etc/backup' directory. *Note Backup Parameters::, for its detailed
+description. Once the backup parameters are set, you can perform
+backups or restoration by running the appropriate script.
+
+ The name of the backup script is 'backup'. The name of the restore
+script is 'restore'. The following sections describe their use in
+detail.
+
+ _Please Note:_ The backup and restoration scripts are designed to be
+used together. While it is possible to restore files by hand from an
+archive which was created using a backup script, and to create an
+archive by hand which could then be extracted using the restore script,
+it is easier to use the scripts. *Note Incremental Dumps::, before
+making such an attempt.
+
+
+File: tar.info, Node: Backup Parameters, Next: Scripted Backups, Prev: Backup Levels, Up: Backups
+
+5.4 Setting Parameters for Backups and Restoration
+==================================================
+
+The file 'backup-specs' specifies backup parameters for the backup and
+restoration scripts provided with 'tar'. You must edit 'backup-specs'
+to fit your system configuration and schedule before using these
+scripts.
+
+ Syntactically, 'backup-specs' is a shell script, containing mainly
+variable assignments. However, any valid shell construct is allowed in
+this file. Particularly, you may wish to define functions within that
+script (e.g., see 'RESTORE_BEGIN' below). For more information about
+shell script syntax, please refer to the definition of the Shell Command
+Language
+(http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html#ta
+g_02). See also *note Bash Features: (bashref)Top.
+
+ The shell variables controlling behavior of 'backup' and 'restore'
+are described in the following subsections.
+
+* Menu:
+
+* General-Purpose Variables::
+* Magnetic Tape Control::
+* User Hooks::
+* backup-specs example:: An Example Text of 'Backup-specs'
+
+
+File: tar.info, Node: General-Purpose Variables, Next: Magnetic Tape Control, Up: Backup Parameters
+
+5.4.1 General-Purpose Variables
+-------------------------------
+
+ -- Backup variable: ADMINISTRATOR
+ The user name of the backup administrator. 'Backup' scripts sends
+ a backup report to this address.
+
+ -- Backup variable: BACKUP_HOUR
+ The hour at which the backups are done. This can be a number from
+ 0 to 23, or the time specification in form HOURS:MINUTES, or the
+ string 'now'.
+
+ This variable is used by 'backup'. Its value may be overridden
+ using '--time' option (*note Scripted Backups::).
+
+ -- Backup variable: TAPE_FILE
+
+ The device 'tar' writes the archive to. If TAPE_FILE is a remote
+ archive (*note remote-dev::), backup script will suppose that your
+ 'mt' is able to access remote devices. If RSH (*note RSH::) is
+ set, '--rsh-command' option will be added to invocations of 'mt'.
+
+ -- Backup variable: BLOCKING
+
+ The blocking factor 'tar' will use when writing the dump archive.
+ *Note Blocking Factor::.
+
+ -- Backup variable: BACKUP_DIRS
+
+ A list of file systems to be dumped (for 'backup'), or restored
+ (for 'restore'). You can include any directory name in the list --
+ subdirectories on that file system will be included, regardless of
+ how they may look to other networked machines. Subdirectories on
+ other file systems will be ignored.
+
+ The host name specifies which host to run 'tar' on, and should
+ normally be the host that actually contains the file system.
+ However, the host machine must have GNU 'tar' installed, and must
+ be able to access the directory containing the backup scripts and
+ their support files using the same file name that is used on the
+ machine where the scripts are run (i.e., what 'pwd' will print when
+ in that directory on that machine). If the host that contains the
+ file system does not have this capability, you can specify another
+ host as long as it can access the file system through NFS.
+
+ If the list of file systems is very long you may wish to put it in
+ a separate file. This file is usually named '/etc/backup/dirs',
+ but this name may be overridden in 'backup-specs' using 'DIRLIST'
+ variable.
+
+ -- Backup variable: DIRLIST
+
+ The name of the file that contains a list of file systems to backup
+ or restore. By default it is '/etc/backup/dirs'.
+
+ -- Backup variable: BACKUP_FILES
+
+ A list of individual files to be dumped (for 'backup'), or restored
+ (for 'restore'). These should be accessible from the machine on
+ which the backup script is run.
+
+ If the list of individual files is very long you may wish to store
+ it in a separate file. This file is usually named
+ '/etc/backup/files', but this name may be overridden in
+ 'backup-specs' using 'FILELIST' variable.
+
+ -- Backup variable: FILELIST
+
+ The name of the file that contains a list of individual files to
+ backup or restore. By default it is '/etc/backup/files'.
+
+ -- Backup variable: MT
+
+ Full file name of 'mt' binary.
+
+ -- Backup variable: RSH
+ Full file name of 'rsh' binary or its equivalent. You may wish to
+ set it to 'ssh', to improve security. In this case you will have
+ to use public key authentication.
+
+ -- Backup variable: RSH_COMMAND
+
+ Full file name of 'rsh' binary on remote machines. This will be
+ passed via '--rsh-command' option to the remote invocation of GNU
+ 'tar'.
+
+ -- Backup variable: VOLNO_FILE
+
+ Name of temporary file to hold volume numbers. This needs to be
+ accessible by all the machines which have file systems to be
+ dumped.
+
+ -- Backup variable: XLIST
+
+ Name of "exclude file list". An "exclude file list" is a file
+ located on the remote machine and containing the list of files to
+ be excluded from the backup. Exclude file lists are searched in
+ /etc/tar-backup directory. A common use for exclude file lists is
+ to exclude files containing security-sensitive information (e.g.,
+ '/etc/shadow' from backups).
+
+ This variable affects only 'backup'.
+
+ -- Backup variable: SLEEP_TIME
+
+ Time to sleep between dumps of any two successive file systems
+
+ This variable affects only 'backup'.
+
+ -- Backup variable: DUMP_REMIND_SCRIPT
+
+ Script to be run when it's time to insert a new tape in for the
+ next volume. Administrators may want to tailor this script for
+ their site. If this variable isn't set, GNU 'tar' will display its
+ built-in prompt, and will expect confirmation from the console.
+ For the description of the default prompt, see *note change volume
+ prompt::.
+
+ -- Backup variable: SLEEP_MESSAGE
+
+ Message to display on the terminal while waiting for dump time.
+ Usually this will just be some literal text.
+
+ -- Backup variable: TAR
+
+ Full file name of the GNU 'tar' executable. If this is not set,
+ backup scripts will search 'tar' in the current shell path.
+
+
+File: tar.info, Node: Magnetic Tape Control, Next: User Hooks, Prev: General-Purpose Variables, Up: Backup Parameters
+
+5.4.2 Magnetic Tape Control
+---------------------------
+
+Backup scripts access tape device using special "hook functions". These
+functions take a single argument -- the name of the tape device. Their
+names are kept in the following variables:
+
+ -- Backup variable: MT_BEGIN
+ The name of "begin" function. This function is called before
+ accessing the drive. By default it retensions the tape:
+
+ MT_BEGIN=mt_begin
+
+ mt_begin() {
+ mt -f "$1" retension
+ }
+
+ -- Backup variable: MT_REWIND
+ The name of "rewind" function. The default definition is as
+ follows:
+
+ MT_REWIND=mt_rewind
+
+ mt_rewind() {
+ mt -f "$1" rewind
+ }
+
+ -- Backup variable: MT_OFFLINE
+ The name of the function switching the tape off line. By default
+ it is defined as follows:
+
+ MT_OFFLINE=mt_offline
+
+ mt_offline() {
+ mt -f "$1" offl
+ }
+
+ -- Backup variable: MT_STATUS
+ The name of the function used to obtain the status of the archive
+ device, including error count. Default definition:
+
+ MT_STATUS=mt_status
+
+ mt_status() {
+ mt -f "$1" status
+ }
+
+
+File: tar.info, Node: User Hooks, Next: backup-specs example, Prev: Magnetic Tape Control, Up: Backup Parameters
+
+5.4.3 User Hooks
+----------------
+
+"User hooks" are shell functions executed before and after each 'tar'
+invocation. Thus, there are "backup hooks", which are executed before
+and after dumping each file system, and "restore hooks", executed before
+and after restoring a file system. Each user hook is a shell function
+taking four arguments:
+
+ -- User Hook Function: hook LEVEL HOST FS FSNAME
+ Its arguments are:
+
+ LEVEL
+ Current backup or restore level.
+
+ HOST
+ Name or IP address of the host machine being dumped or
+ restored.
+
+ FS
+ Full file name of the file system being dumped or restored.
+
+ FSNAME
+ File system name with directory separators replaced with
+ colons. This is useful, e.g., for creating unique files.
+
+ Following variables keep the names of user hook functions:
+
+ -- Backup variable: DUMP_BEGIN
+ Dump begin function. It is executed before dumping the file
+ system.
+
+ -- Backup variable: DUMP_END
+ Executed after dumping the file system.
+
+ -- Backup variable: RESTORE_BEGIN
+ Executed before restoring the file system.
+
+ -- Backup variable: RESTORE_END
+ Executed after restoring the file system.
+
+
+File: tar.info, Node: backup-specs example, Prev: User Hooks, Up: Backup Parameters
+
+5.4.4 An Example Text of 'Backup-specs'
+---------------------------------------
+
+The following is an example of 'backup-specs':
+
+ # site-specific parameters for file system backup.
+
+ ADMINISTRATOR=friedman
+ BACKUP_HOUR=1
+ TAPE_FILE=/dev/nrsmt0
+
+ # Use ssh instead of the less secure rsh
+ RSH=/usr/bin/ssh
+ RSH_COMMAND=/usr/bin/ssh
+
+ # Override MT_STATUS function:
+ my_status() {
+ mts -t $TAPE_FILE
+ }
+ MT_STATUS=my_status
+
+ # Disable MT_OFFLINE function
+ MT_OFFLINE=:
+
+ BLOCKING=124
+ BACKUP_DIRS="
+ albert:/fs/fsf
+ apple-gunkies:/gd
+ albert:/fs/gd2
+ albert:/fs/gp
+ geech:/usr/jla
+ churchy:/usr/roland
+ albert:/
+ albert:/usr
+ apple-gunkies:/
+ apple-gunkies:/usr
+ gnu:/hack
+ gnu:/u
+ apple-gunkies:/com/mailer/gnu
+ apple-gunkies:/com/archive/gnu"
+
+ BACKUP_FILES="/com/mailer/aliases /com/mailer/league*[a-z]"
+
+
+
+File: tar.info, Node: Scripted Backups, Next: Scripted Restoration, Prev: Backup Parameters, Up: Backups
+
+5.5 Using the Backup Scripts
+============================
+
+The syntax for running a backup script is:
+
+ backup --level=LEVEL --time=TIME
+
+ The '--level' option requests the dump level. Thus, to produce a
+full dump, specify '--level=0' (this is the default, so '--level' may be
+omitted if its value is '0')(1).
+
+ The '--time' option determines when should the backup be run. TIME
+may take three forms:
+
+HH:MM
+
+ The dump must be run at HH hours MM minutes.
+
+HH
+
+ The dump must be run at HH hours.
+
+now
+
+ The dump must be run immediately.
+
+ You should start a script with a tape or disk mounted. Once you
+start a script, it prompts you for new tapes or disks as it needs them.
+Media volumes don't have to correspond to archive files -- a
+multi-volume archive can be started in the middle of a tape that already
+contains the end of another multi-volume archive. The 'restore' script
+prompts for media by its archive volume, so to avoid an error message
+you should keep track of which tape (or disk) contains which volume of
+the archive (*note Scripted Restoration::).
+
+ The backup scripts write two files on the file system. The first is
+a record file in '/etc/tar-backup/', which is used by the scripts to
+store and retrieve information about which files were dumped. This file
+is not meant to be read by humans, and should not be deleted by them.
+*Note Snapshot Files::, for a more detailed explanation of this file.
+
+ The second file is a log file containing the names of the file
+systems and files dumped, what time the backup was made, and any error
+messages that were generated, as well as how much space was left in the
+media volume after the last volume of the archive was written. You
+should check this log file after every backup. The file name is
+'log-MM-DD-YYYY-level-N', where MM-DD-YYYY represents current date, and
+N represents current dump level number.
+
+ The script also prints the name of each system being dumped to the
+standard output.
+
+ Following is the full list of options accepted by 'backup' script:
+
+'-l LEVEL'
+'--level=LEVEL'
+ Do backup level LEVEL (default 0).
+
+'-f'
+'--force'
+ Force backup even if today's log file already exists.
+
+'-v[LEVEL]'
+'--verbose[=LEVEL]'
+ Set verbosity level. The higher the level is, the more debugging
+ information will be output during execution. Default LEVEL is 100,
+ which means the highest debugging level.
+
+'-t START-TIME'
+'--time=START-TIME'
+ Wait till TIME, then do backup.
+
+'-h'
+'--help'
+ Display short help message and exit.
+
+'-V'
+'--version'
+ Display information about the program's name, version, origin and
+ legal status, all on standard output, and then exit successfully.
+
+ ---------- Footnotes ----------
+
+ (1) For backward compatibility, the 'backup' will also try to deduce
+the requested dump level from the name of the script itself. If the
+name consists of a string 'level-' followed by a single decimal digit,
+that digit is taken as the dump level number. Thus, you may create a
+link from 'backup' to 'level-1' and then run 'level-1' whenever you need
+to create a level one dump.
+
+
+File: tar.info, Node: Scripted Restoration, Prev: Scripted Backups, Up: Backups
+
+5.6 Using the Restore Script
+============================
+
+To restore files that were archived using a scripted backup, use the
+'restore' script. Its usage is quite straightforward. In the simplest
+form, invoke 'restore --all', it will then restore all the file systems
+and files specified in 'backup-specs' (*note BACKUP_DIRS:
+General-Purpose Variables.).
+
+ You may select the file systems (and/or files) to restore by giving
+'restore' a list of "patterns" in its command line. For example,
+running
+
+ restore 'albert:*'
+
+will restore all file systems on the machine 'albert'. A more
+complicated example:
+
+ restore 'albert:*' '*:/var'
+
+This command will restore all file systems on the machine 'albert' as
+well as '/var' file system on all machines.
+
+ By default 'restore' will start restoring files from the lowest
+available dump level (usually zero) and will continue through all
+available dump levels. There may be situations where such a thorough
+restore is not necessary. For example, you may wish to restore only
+files from the recent level one backup. To do so, use '--level' option,
+as shown in the example below:
+
+ restore --level=1
+
+ The full list of options accepted by 'restore' follows:
+
+'-a'
+'--all'
+ Restore all file systems and files specified in 'backup-specs'.
+
+'-l LEVEL'
+'--level=LEVEL'
+ Start restoring from the given backup level, instead of the default
+ 0.
+
+'-v[LEVEL]'
+'--verbose[=LEVEL]'
+ Set verbosity level. The higher the level is, the more debugging
+ information will be output during execution. Default LEVEL is 100,
+ which means the highest debugging level.
+
+'-h'
+'--help'
+ Display short help message and exit.
+
+'-V'
+'--version'
+ Display information about the program's name, version, origin and
+ legal status, all on standard output, and then exit successfully.
+
+ You should start the restore script with the media containing the
+first volume of the archive mounted. The script will prompt for other
+volumes as they are needed. If the archive is on tape, you don't need
+to rewind the tape to to its beginning--if the tape head is positioned
+past the beginning of the archive, the script will rewind the tape as
+needed. *Note Tape Positioning::, for a discussion of tape positioning.
+
+ *Warning:* The script will delete files from the active file system
+ if they were not in the file system when the archive was made.
+
+ *Note Incremental Dumps::, for an explanation of how the script makes
+that determination.
+
+
+File: tar.info, Node: Choosing, Next: Date input formats, Prev: Backups, Up: Top
+
+6 Choosing Files and Names for 'tar'
+************************************
+
+Certain options to 'tar' enable you to specify a name for your archive.
+Other options let you decide which files to include or exclude from the
+archive, based on when or whether files were modified, whether the file
+names do or don't match specified patterns, or whether files are in
+specified directories.
+
+ This chapter discusses these options in detail.
+
+* Menu:
+
+* file:: Choosing the Archive's Name
+* Selecting Archive Members::
+* files:: Reading Names from a File
+* exclude:: Excluding Some Files
+* wildcards:: Wildcards Patterns and Matching
+* quoting styles:: Ways of Quoting Special Characters in Names
+* transform:: Modifying File and Member Names
+* after:: Operating Only on New Files
+* recurse:: Descending into Directories
+* one:: Crossing File System Boundaries
+
+
+File: tar.info, Node: file, Next: Selecting Archive Members, Up: Choosing
+
+6.1 Choosing and Naming Archive Files
+=====================================
+
+By default, 'tar' uses an archive file name that was compiled when it
+was built on the system; usually this name refers to some physical tape
+drive on the machine. However, the person who installed 'tar' on the
+system may not have set the default to a meaningful value as far as most
+users are concerned. As a result, you will usually want to tell 'tar'
+where to find (or create) the archive. The '--file=ARCHIVE-NAME' ('-f
+ARCHIVE-NAME') option allows you to either specify or name a file to use
+as the archive instead of the default archive file location.
+
+'--file=ARCHIVE-NAME'
+'-f ARCHIVE-NAME'
+ Name the archive to create or operate on. Use in conjunction with
+ any operation.
+
+ For example, in this 'tar' command,
+
+ $ tar -cvf collection.tar blues folk jazz
+
+'collection.tar' is the name of the archive. It must directly follow
+the '-f' option, since whatever directly follows '-f' _will_ end up
+naming the archive. If you neglect to specify an archive name, you may
+end up overwriting a file in the working directory with the archive you
+create since 'tar' will use this file's name for the archive name.
+
+ An archive can be saved as a file in the file system, sent through a
+pipe or over a network, or written to an I/O device such as a tape,
+floppy disk, or CD write drive.
+
+ If you do not name the archive, 'tar' uses the value of the
+environment variable 'TAPE' as the file name for the archive. If that
+is not available, 'tar' uses a default, compiled-in archive name,
+usually that for tape unit zero (i.e., '/dev/tu00').
+
+ If you use '-' as an ARCHIVE-NAME, 'tar' reads the archive from
+standard input (when listing or extracting files), or writes it to
+standard output (when creating an archive). If you use '-' as an
+ARCHIVE-NAME when modifying an archive, 'tar' reads the original archive
+from its standard input and writes the entire new archive to its
+standard output.
+
+ The following example is a convenient way of copying directory
+hierarchy from 'sourcedir' to 'targetdir'.
+
+ $ (cd sourcedir; tar -cf - .) | (cd targetdir; tar -xpf -)
+
+ The '-C' option allows to avoid using subshells:
+
+ $ tar -C sourcedir -cf - . | tar -C targetdir -xpf -
+
+ In both examples above, the leftmost 'tar' invocation archives the
+contents of 'sourcedir' to the standard output, while the rightmost one
+reads this archive from its standard input and extracts it. The '-p'
+option tells it to restore permissions of the extracted files.
+
+ To specify an archive file on a device attached to a remote machine,
+use the following:
+
+ --file=HOSTNAME:/DEV/FILE-NAME
+
+'tar' will set up the remote connection, if possible, and prompt you for
+a username and password. If you use '--file=@HOSTNAME:/DEV/FILE-NAME',
+'tar' will attempt to set up the remote connection using your username
+as the username on the remote machine.
+
+ If the archive file name includes a colon (':'), then it is assumed
+to be a file on another machine. If the archive file is
+'USER@HOST:FILE', then FILE is used on the host HOST. The remote host
+is accessed using the 'rsh' program, with a username of USER. If the
+username is omitted (along with the '@' sign), then your user name will
+be used. (This is the normal 'rsh' behavior.) It is necessary for the
+remote machine, in addition to permitting your 'rsh' access, to have the
+'rmt' program installed (this command is included in the GNU 'tar'
+distribution and by default is installed under 'PREFIX/libexec/rmt',
+where PREFIX means your installation prefix). If you need to use a file
+whose name includes a colon, then the remote tape drive behavior can be
+inhibited by using the '--force-local' option.
+
+ When the archive is being created to '/dev/null', GNU 'tar' tries to
+minimize input and output operations. The Amanda backup system, when
+used with GNU 'tar', has an initial sizing pass which uses this feature.
+
+
+File: tar.info, Node: Selecting Archive Members, Next: files, Prev: file, Up: Choosing
+
+6.2 Selecting Archive Members
+=============================
+
+"File Name arguments" specify which files in the file system 'tar'
+operates on, when creating or adding to an archive, or which archive
+members 'tar' operates on, when reading or deleting from an archive.
+*Note Operations::.
+
+ To specify file names, you can include them as the last arguments on
+the command line, as follows:
+ tar OPERATION [OPTION1 OPTION2 ...] [FILE NAME-1 FILE NAME-2 ...]
+
+ If a file name begins with dash ('-'), precede it with '--add-file'
+option to prevent it from being treated as an option.
+
+ By default GNU 'tar' attempts to "unquote" each file or member name,
+replacing "escape sequences" according to the following table:
+
+Escape Replaced with
+-----------------------------------------------------------
+\a Audible bell (ASCII 7)
+\b Backspace (ASCII 8)
+\f Form feed (ASCII 12)
+\n New line (ASCII 10)
+\r Carriage return (ASCII 13)
+\t Horizontal tabulation (ASCII 9)
+\v Vertical tabulation (ASCII 11)
+\? ASCII 127
+\N ASCII N (N should be an octal number of
+ up to 3 digits)
+
+ A backslash followed by any other symbol is retained.
+
+ This default behavior is controlled by the following command line
+option:
+
+'--unquote'
+ Enable unquoting input file or member names (default).
+
+'--no-unquote'
+ Disable unquoting input file or member names.
+
+ If you specify a directory name as a file name argument, all the
+files in that directory are operated on by 'tar'.
+
+ If you do not specify files, 'tar' behavior differs depending on the
+operation mode as described below:
+
+ When 'tar' is invoked with '--create' ('-c'), 'tar' will stop
+immediately, reporting the following:
+
+ $ tar cf a.tar
+ tar: Cowardly refusing to create an empty archive
+ Try 'tar --help' or 'tar --usage' for more information.
+
+ If you specify either '--list' ('-t') or '--extract' ('--get', '-x'),
+'tar' operates on all the archive members in the archive.
+
+ If run with '--diff' option, tar will compare the archive with the
+contents of the current working directory.
+
+ If you specify any other operation, 'tar' does nothing.
+
+ By default, 'tar' takes file names from the command line. However,
+there are other ways to specify file or member names, or to modify the
+manner in which 'tar' selects the files or members upon which to
+operate. In general, these methods work both for specifying the names
+of files and archive members.
+
+
+File: tar.info, Node: files, Next: exclude, Prev: Selecting Archive Members, Up: Choosing
+
+6.3 Reading Names from a File
+=============================
+
+Instead of giving the names of files or archive members on the command
+line, you can put the names into a file, and then use the
+'--files-from=FILE-OF-NAMES' ('-T FILE-OF-NAMES') option to 'tar'. Give
+the name of the file which contains the list of files to include as the
+argument to '--files-from'. In the list, the file names should be
+separated by newlines. You will frequently use this option when you
+have generated the list of files to archive with the 'find' utility.
+
+'--files-from=FILE-NAME'
+'-T FILE-NAME'
+ Get names to extract or create from file FILE-NAME.
+
+ If you give a single dash as a file name for '--files-from', (i.e.,
+you specify either '--files-from=-' or '-T -'), then the file names are
+read from standard input.
+
+ Unless you are running 'tar' with '--create', you cannot use both
+'--files-from=-' and '--file=-' ('-f -') in the same command.
+
+ Any number of '-T' options can be given in the command line.
+
+ The following example shows how to use 'find' to generate a list of
+files smaller than 400K in length and put that list into a file called
+'small-files'. You can then use the '-T' option to 'tar' to specify the
+files from that file, 'small-files', to create the archive 'little.tgz'.
+(The '-z' option to 'tar' compresses the archive with 'gzip'; *note
+gzip:: for more information.)
+
+ $ find . -size -400 -print > small-files
+ $ tar -c -v -z -T small-files -f little.tgz
+
+By default, each line read from the file list is first stripped off any
+leading and trailing whitespace. If the resulting string begins with
+'-' character, it is considered a 'tar' option and is processed
+accordingly(1). For example, the common use of this feature is to
+change to another directory by specifying '-C' option:
+
+ $ cat list
+ -C/etc
+ passwd
+ hosts
+ -C/lib
+ libc.a
+ $ tar -c -f foo.tar --files-from list
+
+In this example, 'tar' will first switch to '/etc' directory and add
+files 'passwd' and 'hosts' to the archive. Then it will change to
+'/lib' directory and will archive the file 'libc.a'. Thus, the
+resulting archive 'foo.tar' will contain:
+
+ $ tar tf foo.tar
+ passwd
+ hosts
+ libc.a
+
+ Note, that any options used in the file list remain in effect for the
+rest of the command line. For example, using the same 'list' file as
+above, the following command
+
+ $ tar -c -f foo.tar --files-from list libcurses.a
+
+will look for file 'libcurses.a' in the directory '/lib', because it was
+used with the last '-C' option (*note Position-Sensitive Options::).
+
+ If such option handling is undesirable, use the
+'--verbatim-files-from' option. When this option is in effect, each
+line read from the file list is treated as a file name. Notice, that
+this means, in particular, that no whitespace trimming is performed.
+
+ The '--verbatim-files-from' affects all '-T' options that follow it
+in the command line. The default behavior can be restored using
+'--no-verbatim-files-from' option.
+
+ To disable option handling for a single file name, use the
+'--add-file' option, e.g.: '--add-file=--my-file'.
+
+ You can use any GNU 'tar' command line options in the file list file,
+including '--files-from' option itself. This allows for including
+contents of a file list into another file list file. Note however, that
+options that control file list processing, such as
+'--verbatim-files-from' or '--null' won't affect the file they appear
+in. They will affect next '--files-from' option, if there is any.
+
+* Menu:
+
+* nul::
+
+ ---------- Footnotes ----------
+
+ (1) Versions of GNU 'tar' up to 1.15.1 recognized only '-C' option in
+file lists, and only if the option and its argument occupied two
+consecutive lines.
+
+
+File: tar.info, Node: nul, Up: files
+
+6.3.1 'NUL'-Terminated File Names
+---------------------------------
+
+The '--null' option causes '--files-from=FILE-OF-NAMES' ('-T
+FILE-OF-NAMES') to read file names terminated by a 'NUL' instead of a
+newline, so files whose names contain newlines can be archived using
+'--files-from'.
+
+'--null'
+ Only consider 'NUL'-terminated file names, instead of files that
+ terminate in a newline.
+
+'--no-null'
+ Undo the effect of any previous '--null' option.
+
+ The '--null' option is just like the one in GNU 'xargs' and 'cpio',
+and is useful with the '-print0' predicate of GNU 'find'. In 'tar',
+'--null' also disables special handling for file names that begin with
+dash (similar to '--verbatim-files-from' option).
+
+ This example shows how to use 'find' to generate a list of files
+larger than 800K in length and put that list into a file called
+'long-files'. The '-print0' option to 'find' is just like '-print',
+except that it separates files with a 'NUL' rather than with a newline.
+You can then run 'tar' with both the '--null' and '-T' options to
+specify that 'tar' gets the files from that file, 'long-files', to
+create the archive 'big.tgz'. The '--null' option to 'tar' will cause
+'tar' to recognize the 'NUL' separator between files.
+
+ $ find . -size +800 -print0 > long-files
+ $ tar -c -v --null --files-from=long-files --file=big.tar
+
+ The '--no-null' option can be used if you need to read both
+'NUL'-terminated and newline-terminated files on the same command line.
+For example, if 'flist' is a newline-terminated file, then the following
+command can be used to combine it with the above command:
+
+ $ find . -size +800 -print0 |
+ tar -c -f big.tar --null -T - --no-null -T flist
+
+ This example uses short options for typographic reasons, to avoid
+very long lines.
+
+ GNU 'tar' is tries to automatically detect 'NUL'-terminated file
+lists, so in many cases it is safe to use them even without the '--null'
+option. In this case 'tar' will print a warning and continue reading
+such a file as if '--null' were actually given:
+
+ $ find . -size +800 -print0 | tar -c -f big.tar -T -
+ tar: -: file name read contains nul character
+
+ The null terminator, however, remains in effect only for this
+particular file, any following '-T' options will assume newline
+termination. Of course, the null autodetection applies to these
+eventual surplus '-T' options as well.
+
+
+File: tar.info, Node: exclude, Next: wildcards, Prev: files, Up: Choosing
+
+6.4 Excluding Some Files
+========================
+
+To avoid operating on files whose names match a particular pattern, use
+the '--exclude' or '--exclude-from' options.
+
+'--exclude=PATTERN'
+ Causes 'tar' to ignore files that match the PATTERN.
+
+ The '--exclude=PATTERN' option prevents any file or member whose name
+matches the shell wildcard (PATTERN) from being operated on. For
+example, to create an archive with all the contents of the directory
+'src' except for files whose names end in '.o', use the command 'tar -cf
+src.tar --exclude='*.o' src'.
+
+ You may give multiple '--exclude' options.
+
+'--exclude-from=FILE'
+'-X FILE'
+ Causes 'tar' to ignore files that match the patterns listed in
+ FILE.
+
+ Use the '--exclude-from' option to read a list of patterns, one per
+line, from FILE; 'tar' will ignore files matching those patterns. Thus
+if 'tar' is called as 'tar -c -X foo .' and the file 'foo' contains a
+single line '*.o', no files whose names end in '.o' will be added to the
+archive.
+
+ Notice, that lines from FILE are read verbatim. One of the frequent
+errors is leaving some extra whitespace after a file name, which is
+difficult to catch using text editors.
+
+ However, empty lines are OK.
+
+ When archiving directories that are under some version control system
+(VCS), it is often convenient to read exclusion patterns from this VCS'
+ignore files (e.g. '.cvsignore', '.gitignore', etc.) The following
+options provide such possibility:
+
+'--exclude-vcs-ignores'
+ Before archiving a directory, see if it contains any of the
+ following files: 'cvsignore', '.gitignore', '.bzrignore', or
+ '.hgignore'. If so, read ignore patterns from these files.
+
+ The patterns are treated much as the corresponding VCS would treat
+ them, i.e.:
+
+ '.cvsignore'
+ Contains shell-style globbing patterns that apply only to the
+ directory where this file resides. No comments are allowed in
+ the file. Empty lines are ignored.
+
+ '.gitignore'
+ Contains shell-style globbing patterns. Applies to the
+ directory where '.gitfile' is located and all its
+ subdirectories.
+
+ Any line beginning with a '#' is a comment. Backslash escapes
+ the comment character.
+
+ '.bzrignore'
+ Contains shell globbing-patterns and regular expressions (if
+ prefixed with 'RE:'(1). Patterns affect the directory and all
+ its subdirectories.
+
+ Any line beginning with a '#' is a comment.
+
+ '.hgignore'
+ Contains posix regular expressions(2). The line 'syntax:
+ glob' switches to shell globbing patterns. The line 'syntax:
+ regexp' switches back. Comments begin with a '#'. Patterns
+ affect the directory and all its subdirectories.
+
+'--exclude-ignore=FILE'
+ Before dumping a directory, 'tar' checks if it contains FILE. If
+ so, exclusion patterns are read from this file. The patterns
+ affect only the directory itself.
+
+'--exclude-ignore-recursive=FILE'
+ Same as '--exclude-ignore', except that the patterns read affect
+ both the directory where FILE resides and all its subdirectories.
+
+'--exclude-vcs'
+ Exclude files and directories used by following version control
+ systems: 'CVS', 'RCS', 'SCCS', 'SVN', 'Arch', 'Bazaar',
+ 'Mercurial', and 'Darcs'.
+
+ As of version 1.29, the following files are excluded:
+
+ * 'CVS/', and everything under it
+ * 'RCS/', and everything under it
+ * 'SCCS/', and everything under it
+ * '.git/', and everything under it
+ * '.gitignore'
+ * '.gitmodules'
+ * '.gitattributes'
+ * '.cvsignore'
+ * '.svn/', and everything under it
+ * '.arch-ids/', and everything under it
+ * '{arch}/', and everything under it
+ * '=RELEASE-ID'
+ * '=meta-update'
+ * '=update'
+ * '.bzr'
+ * '.bzrignore'
+ * '.bzrtags'
+ * '.hg'
+ * '.hgignore'
+ * '.hgrags'
+ * '_darcs'
+
+'--exclude-backups'
+ Exclude backup and lock files. This option causes exclusion of
+ files that match the following shell globbing patterns:
+
+ .#*
+ *~
+ #*#
+
+ When creating an archive, the '--exclude-caches' option family causes
+'tar' to exclude all directories that contain a "cache directory tag".
+A cache directory tag is a short file with the well-known name
+'CACHEDIR.TAG' and having a standard header specified in
+<http://www.brynosaurus.com/cachedir/spec.html>. Various applications
+write cache directory tags into directories they use to hold
+regenerable, non-precious data, so that such data can be more easily
+excluded from backups.
+
+ There are three 'exclude-caches' options, each providing a different
+exclusion semantics:
+
+'--exclude-caches'
+ Do not archive the contents of the directory, but archive the
+ directory itself and the 'CACHEDIR.TAG' file.
+
+'--exclude-caches-under'
+ Do not archive the contents of the directory, nor the
+ 'CACHEDIR.TAG' file, archive only the directory itself.
+
+'--exclude-caches-all'
+ Omit directories containing 'CACHEDIR.TAG' file entirely.
+
+ Another option family, '--exclude-tag', provides a generalization of
+this concept. It takes a single argument, a file name to look for. Any
+directory that contains this file will be excluded from the dump.
+Similarly to 'exclude-caches', there are three options in this option
+family:
+
+'--exclude-tag=FILE'
+ Do not dump the contents of the directory, but dump the directory
+ itself and the FILE.
+
+'--exclude-tag-under=FILE'
+ Do not dump the contents of the directory, nor the FILE, archive
+ only the directory itself.
+
+'--exclude-tag-all=FILE'
+ Omit directories containing FILE file entirely.
+
+ Multiple '--exclude-tag*' options can be given.
+
+ For example, given this directory:
+
+ $ find dir
+ dir
+ dir/blues
+ dir/jazz
+ dir/folk
+ dir/folk/tagfile
+ dir/folk/sanjuan
+ dir/folk/trote
+
+ The '--exclude-tag' will produce the following:
+
+ $ tar -cf archive.tar --exclude-tag=tagfile -v dir
+ dir/
+ dir/blues
+ dir/jazz
+ dir/folk/
+ tar: dir/folk/: contains a cache directory tag tagfile;
+ contents not dumped
+ dir/folk/tagfile
+
+ Both the 'dir/folk' directory and its tagfile are preserved in the
+archive, however the rest of files in this directory are not.
+
+ Now, using the '--exclude-tag-under' option will exclude 'tagfile'
+from the dump, while still preserving the directory itself, as shown in
+this example:
+
+ $ tar -cf archive.tar --exclude-tag-under=tagfile -v dir
+ dir/
+ dir/blues
+ dir/jazz
+ dir/folk/
+ ./tar: dir/folk/: contains a cache directory tag tagfile;
+ contents not dumped
+
+ Finally, using '--exclude-tag-all' omits the 'dir/folk' directory
+entirely:
+
+ $ tar -cf archive.tar --exclude-tag-all=tagfile -v dir
+ dir/
+ dir/blues
+ dir/jazz
+ ./tar: dir/folk/: contains a cache directory tag tagfile;
+ directory not dumped
+
+* Menu:
+
+* problems with exclude::
+
+ ---------- Footnotes ----------
+
+ (1) According to the Bazaar docs, globbing-patterns are Korn-shell
+style and regular expressions are perl-style. As of GNU 'tar' version
+1.29, these are treated as shell-style globs and posix extended regexps.
+This will be fixed in future releases.
+
+ (2) Support for perl-style regexps will appear in future releases.
+
+
+File: tar.info, Node: problems with exclude, Up: exclude
+
+Problems with Using the 'exclude' Options
+-----------------------------------------
+
+Some users find 'exclude' options confusing. Here are some common
+pitfalls:
+
+ * The main operating mode of 'tar' does not act on a file name
+ explicitly listed on the command line, if one of its file name
+ components is excluded. In the example above, if you create an
+ archive and exclude files that end with '*.o', but explicitly name
+ the file 'dir.o/foo' after all the options have been listed,
+ 'dir.o/foo' will be excluded from the archive.
+
+ * You can sometimes confuse the meanings of '--exclude' and
+ '--exclude-from'. Be careful: use '--exclude' when files to be
+ excluded are given as a pattern on the command line. Use
+ '--exclude-from' to introduce the name of a file which contains a
+ list of patterns, one per line; each of these patterns can exclude
+ zero, one, or many files.
+
+ * When you use '--exclude=PATTERN', be sure to quote the PATTERN
+ parameter, so GNU 'tar' sees wildcard characters like '*'. If you
+ do not do this, the shell might expand the '*' itself using files
+ at hand, so 'tar' might receive a list of files instead of one
+ pattern, or none at all, making the command somewhat illegal. This
+ might not correspond to what you want.
+
+ For example, write:
+
+ $ tar -c -f ARCHIVE.TAR --exclude '*.o' DIRECTORY
+
+ rather than:
+
+ # _Wrong!_
+ $ tar -c -f ARCHIVE.TAR --exclude *.o DIRECTORY
+
+ * You must use use shell syntax, or globbing, rather than 'regexp'
+ syntax, when using exclude options in 'tar'. If you try to use
+ 'regexp' syntax to describe files to be excluded, your command
+ might fail.
+
+ *
+ In earlier versions of 'tar', what is now the '--exclude-from'
+ option was called '--exclude' instead. Now, '--exclude' applies to
+ patterns listed on the command line and '--exclude-from' applies to
+ patterns listed in a file.
+
+
+File: tar.info, Node: wildcards, Next: quoting styles, Prev: exclude, Up: Choosing
+
+6.5 Wildcards Patterns and Matching
+===================================
+
+"Globbing" is the operation by which "wildcard" characters, '*' or '?'
+for example, are replaced and expanded into all existing files matching
+the given pattern. GNU 'tar' can use wildcard patterns for matching (or
+globbing) archive members when extracting from or listing an archive.
+Wildcard patterns are also used for verifying volume labels of 'tar'
+archives. This section has the purpose of explaining wildcard syntax
+for 'tar'.
+
+ A PATTERN should be written according to shell syntax, using wildcard
+characters to effect globbing. Most characters in the pattern stand for
+themselves in the matched string, and case is significant: 'a' will
+match only 'a', and not 'A'. The character '?' in the pattern matches
+any single character in the matched string. The character '*' in the
+pattern matches zero, one, or more single characters in the matched
+string. The character '\' says to take the following character of the
+pattern _literally_; it is useful when one needs to match the '?', '*',
+'[' or '\' characters, themselves.
+
+ The character '[', up to the matching ']', introduces a character
+class. A "character class" is a list of acceptable characters for the
+next single character of the matched string. For example, '[abcde]'
+would match any of the first five letters of the alphabet. Note that
+within a character class, all of the "special characters" listed above
+other than '\' lose their special meaning; for example, '[-\\[*?]]'
+would match any of the characters, '-', '\', '[', '*', '?', or ']'.
+(Due to parsing constraints, the characters '-' and ']' must either come
+_first_ or _last_ in a character class.)
+
+ If the first character of the class after the opening '[' is '!' or
+'^', then the meaning of the class is reversed. Rather than listing
+character to match, it lists those characters which are _forbidden_ as
+the next single character of the matched string.
+
+ Other characters of the class stand for themselves. The special
+construction '[A-E]', using an hyphen between two letters, is meant to
+represent all characters between A and E, inclusive.
+
+ Periods ('.') or forward slashes ('/') are not considered special for
+wildcard matches. However, if a pattern completely matches a directory
+prefix of a matched string, then it matches the full matched string:
+thus, excluding a directory also excludes all the files beneath it.
+
+* Menu:
+
+* controlling pattern-matching::
+
+
+File: tar.info, Node: controlling pattern-matching, Up: wildcards
+
+Controlling Pattern-Matching
+----------------------------
+
+For the purposes of this section, we call "exclusion members" all member
+names obtained while processing '--exclude' and '--exclude-from'
+options, and "inclusion members" those member names that were given in
+the command line or read from the file specified with '--files-from'
+option.
+
+ These two pairs of member lists are used in the following operations:
+'--diff', '--extract', '--list', '--update'.
+
+ There are no inclusion members in create mode ('--create' and
+'--append'), since in this mode the names obtained from the command line
+refer to _files_, not archive members.
+
+ By default, inclusion members are compared with archive members
+literally (1) and exclusion members are treated as globbing patterns.
+For example:
+
+ $ tar tf foo.tar
+ a.c
+ b.c
+ a.txt
+ [remarks]
+ # Member names are used verbatim:
+ $ tar -xf foo.tar -v '[remarks]'
+ [remarks]
+ # Exclude member names are globbed:
+ $ tar -xf foo.tar -v --exclude '*.c'
+ a.txt
+ [remarks]
+
+ This behavior can be altered by using the following options:
+
+'--wildcards'
+ Treat all member names as wildcards.
+
+'--no-wildcards'
+ Treat all member names as literal strings.
+
+ Thus, to extract files whose names end in '.c', you can use:
+
+ $ tar -xf foo.tar -v --wildcards '*.c'
+ a.c
+ b.c
+
+Notice quoting of the pattern to prevent the shell from interpreting it.
+
+ The effect of '--wildcards' option is canceled by '--no-wildcards'.
+This can be used to pass part of the command line arguments verbatim and
+other part as globbing patterns. For example, the following invocation:
+
+ $ tar -xf foo.tar --wildcards '*.txt' --no-wildcards '[remarks]'
+
+instructs 'tar' to extract from 'foo.tar' all files whose names end in
+'.txt' and the file named '[remarks]'.
+
+ Normally, a pattern matches a name if an initial subsequence of the
+name's components matches the pattern, where '*', '?', and '[...]' are
+the usual shell wildcards, '\' escapes wildcards, and wildcards can
+match '/'.
+
+ Other than optionally stripping leading '/' from names (*note
+absolute::), patterns and names are used as-is. For example, trailing
+'/' is not trimmed from a user-specified name before deciding whether to
+exclude it.
+
+ However, this matching procedure can be altered by the options listed
+below. These options accumulate. For example:
+
+ --ignore-case --exclude='makefile' --no-ignore-case ---exclude='readme'
+
+ignores case when excluding 'makefile', but not when excluding 'readme'.
+
+'--anchored'
+'--no-anchored'
+ If anchored, a pattern must match an initial subsequence of the
+ name's components. Otherwise, the pattern can match any
+ subsequence. Default is '--no-anchored' for exclusion members and
+ '--anchored' inclusion members.
+
+'--ignore-case'
+'--no-ignore-case'
+ When ignoring case, upper-case patterns match lower-case names and
+ vice versa. When not ignoring case (the default), matching is
+ case-sensitive.
+
+'--wildcards-match-slash'
+'--no-wildcards-match-slash'
+ When wildcards match slash (the default for exclusion members), a
+ wildcard like '*' in the pattern can match a '/' in the name.
+ Otherwise, '/' is matched only by '/'.
+
+ The '--recursion' and '--no-recursion' options (*note recurse::) also
+affect how member patterns are interpreted. If recursion is in effect,
+a pattern matches a name if it matches any of the name's parent
+directories.
+
+ The following table summarizes pattern-matching default values:
+
+Members Default settings
+--------------------------------------------------------------------------
+Inclusion '--no-wildcards --anchored
+ --no-wildcards-match-slash'
+Exclusion '--wildcards --no-anchored
+ --wildcards-match-slash'
+
+ ---------- Footnotes ----------
+
+ (1) Notice that earlier GNU 'tar' versions used globbing for
+inclusion members, which contradicted to UNIX98 specification and was
+not documented. *Note Changes::, for more information on this and other
+changes.
+
+
+File: tar.info, Node: quoting styles, Next: transform, Prev: wildcards, Up: Choosing
+
+6.6 Quoting Member Names
+========================
+
+When displaying member names, 'tar' takes care to avoid ambiguities
+caused by certain characters. This is called "name quoting". The
+characters in question are:
+
+ * Non-printable control characters:
+ Character ASCII Character name
+ -------------------------------------------------------------------
+ \a 7 Audible bell
+ \b 8 Backspace
+ \f 12 Form feed
+ \n 10 New line
+ \r 13 Carriage return
+ \t 9 Horizontal tabulation
+ \v 11 Vertical tabulation
+
+ * Space (ASCII 32)
+
+ * Single and double quotes (''' and '"')
+
+ * Backslash ('\')
+
+ The exact way 'tar' uses to quote these characters depends on the
+"quoting style". The default quoting style, called "escape" (see
+below), uses backslash notation to represent control characters, space
+and backslash. Using this quoting style, control characters are
+represented as listed in column 'Character' in the above table, a space
+is printed as '\ ' and a backslash as '\\'.
+
+ GNU 'tar' offers seven distinct quoting styles, which can be selected
+using '--quoting-style' option:
+
+'--quoting-style=STYLE'
+
+ Sets quoting style. Valid values for STYLE argument are: literal,
+ shell, shell-always, c, escape, locale, clocale.
+
+ These styles are described in detail below. To illustrate their
+effect, we will use an imaginary tar archive 'arch.tar' containing the
+following members:
+
+ # 1. Contains horizontal tabulation character.
+ a tab
+ # 2. Contains newline character
+ a
+ newline
+ # 3. Contains a space
+ a space
+ # 4. Contains double quotes
+ a"double"quote
+ # 5. Contains single quotes
+ a'single'quote
+ # 6. Contains a backslash character:
+ a\backslash
+
+ Here is how usual 'ls' command would have listed them, if they had
+existed in the current working directory:
+
+ $ ls
+ a\ttab
+ a\nnewline
+ a\ space
+ a"double"quote
+ a'single'quote
+ a\\backslash
+
+ Quoting styles:
+
+'literal'
+ No quoting, display each character as is:
+
+ $ tar tf arch.tar --quoting-style=literal
+ ./
+ ./a space
+ ./a'single'quote
+ ./a"double"quote
+ ./a\backslash
+ ./a tab
+ ./a
+ newline
+
+'shell'
+ Display characters the same way Bourne shell does: control
+ characters, except '\t' and '\n', are printed using backslash
+ escapes, '\t' and '\n' are printed as is, and a single quote is
+ printed as '\''. If a name contains any quoted characters, it is
+ enclosed in single quotes. In particular, if a name contains
+ single quotes, it is printed as several single-quoted strings:
+
+ $ tar tf arch.tar --quoting-style=shell
+ ./
+ './a space'
+ './a'\''single'\''quote'
+ './a"double"quote'
+ './a\backslash'
+ './a tab'
+ './a
+ newline'
+
+'shell-always'
+ Same as 'shell', but the names are always enclosed in single
+ quotes:
+
+ $ tar tf arch.tar --quoting-style=shell-always
+ './'
+ './a space'
+ './a'\''single'\''quote'
+ './a"double"quote'
+ './a\backslash'
+ './a tab'
+ './a
+ newline'
+
+'c'
+ Use the notation of the C programming language. All names are
+ enclosed in double quotes. Control characters are quoted using
+ backslash notations, double quotes are represented as '\"',
+ backslash characters are represented as '\\'. Single quotes and
+ spaces are not quoted:
+
+ $ tar tf arch.tar --quoting-style=c
+ "./"
+ "./a space"
+ "./a'single'quote"
+ "./a\"double\"quote"
+ "./a\\backslash"
+ "./a\ttab"
+ "./a\nnewline"
+
+'escape'
+ Control characters are printed using backslash notation, a space is
+ printed as '\ ' and a backslash as '\\'. This is the default
+ quoting style, unless it was changed when configured the package.
+
+ $ tar tf arch.tar --quoting-style=escape
+ ./
+ ./a space
+ ./a'single'quote
+ ./a"double"quote
+ ./a\\backslash
+ ./a\ttab
+ ./a\nnewline
+
+'locale'
+ Control characters, single quote and backslash are printed using
+ backslash notation. All names are quoted using left and right
+ quotation marks, appropriate to the current locale. If it does not
+ define quotation marks, use ''' as left and as right quotation
+ marks. Any occurrences of the right quotation mark in a name are
+ escaped with '\', for example:
+
+ For example:
+
+ $ tar tf arch.tar --quoting-style=locale
+ './'
+ './a space'
+ './a\'single\'quote'
+ './a"double"quote'
+ './a\\backslash'
+ './a\ttab'
+ './a\nnewline'
+
+'clocale'
+ Same as 'locale', but '"' is used for both left and right quotation
+ marks, if not provided by the currently selected locale:
+
+ $ tar tf arch.tar --quoting-style=clocale
+ "./"
+ "./a space"
+ "./a'single'quote"
+ "./a\"double\"quote"
+ "./a\\backslash"
+ "./a\ttab"
+ "./a\nnewline"
+
+ You can specify which characters should be quoted in addition to
+those implied by the current quoting style:
+
+'--quote-chars=STRING'
+ Always quote characters from STRING, even if the selected quoting
+ style would not quote them.
+
+ For example, using 'escape' quoting (compare with the usual escape
+listing above):
+
+ $ tar tf arch.tar --quoting-style=escape --quote-chars=' "'
+ ./
+ ./a\ space
+ ./a'single'quote
+ ./a\"double\"quote
+ ./a\\backslash
+ ./a\ttab
+ ./a\nnewline
+
+ To disable quoting of such additional characters, use the following
+option:
+
+'--no-quote-chars=STRING'
+ Remove characters listed in STRING from the list of quoted
+ characters set by the previous '--quote-chars' option.
+
+ This option is particularly useful if you have added '--quote-chars'
+to your 'TAR_OPTIONS' (*note TAR_OPTIONS::) and wish to disable it for
+the current invocation.
+
+ Note, that '--no-quote-chars' does _not_ disable those characters
+that are quoted by default in the selected quoting style.
+
+
+File: tar.info, Node: transform, Next: after, Prev: quoting styles, Up: Choosing
+
+6.7 Modifying File and Member Names
+===================================
+
+'Tar' archives contain detailed information about files stored in them
+and full file names are part of that information. When storing a file
+to an archive, its file name is recorded in it, along with the actual
+file contents. When restoring from an archive, a file is created on
+disk with exactly the same name as that stored in the archive. In the
+majority of cases this is the desired behavior of a file archiver.
+However, there are some cases when it is not.
+
+ First of all, it is often unsafe to extract archive members with
+absolute file names or those that begin with a '../'. GNU 'tar' takes
+special precautions when extracting such names and provides a special
+option for handling them, which is described in *note absolute::.
+
+ Secondly, you may wish to extract file names without some leading
+directory components, or with otherwise modified names. In other cases
+it is desirable to store files under differing names in the archive.
+
+ GNU 'tar' provides several options for these needs.
+
+'--strip-components=NUMBER'
+ Strip given NUMBER of leading components from file names before
+ extraction.
+
+ For example, suppose you have archived whole '/usr' hierarchy to a
+tar archive named 'usr.tar'. Among other files, this archive contains
+'usr/include/stdlib.h', which you wish to extract to the current working
+directory. To do so, you type:
+
+ $ tar -xf usr.tar --strip=2 usr/include/stdlib.h
+
+ The option '--strip=2' instructs 'tar' to strip the two leading
+components ('usr/' and 'include/') off the file name.
+
+ If you add the '--verbose' ('-v') option to the invocation above, you
+will note that the verbose listing still contains the full file name,
+with the two removed components still in place. This can be
+inconvenient, so 'tar' provides a special option for altering this
+behavior:
+
+'--show-transformed-names'
+ Display file or member names with all requested transformations
+ applied.
+
+For example:
+
+ $ tar -xf usr.tar -v --strip=2 usr/include/stdlib.h
+ usr/include/stdlib.h
+ $ tar -xf usr.tar -v --strip=2 --show-transformed usr/include/stdlib.h
+ stdlib.h
+
+ Notice that in both cases the file 'stdlib.h' is extracted to the
+current working directory, '--show-transformed-names' affects only the
+way its name is displayed.
+
+ This option is especially useful for verifying whether the invocation
+will have the desired effect. Thus, before running
+
+ $ tar -x --strip=N
+
+it is often advisable to run
+
+ $ tar -t -v --show-transformed --strip=N
+
+to make sure the command will produce the intended results.
+
+ In case you need to apply more complex modifications to the file
+name, GNU 'tar' provides a general-purpose transformation option:
+
+'--transform=EXPRESSION'
+'--xform=EXPRESSION'
+ Modify file names using supplied EXPRESSION.
+
+The EXPRESSION is a 'sed'-like replace expression of the form:
+
+ s/REGEXP/REPLACE/[FLAGS]
+
+where REGEXP is a "regular expression", REPLACE is a replacement for
+each file name part that matches REGEXP. Both REGEXP and REPLACE are
+described in detail in *note The "s" Command: (sed)The "s" Command.
+
+ Any delimiter can be used in lieu of '/', the only requirement being
+that it be used consistently throughout the expression. For example,
+the following two expressions are equivalent:
+
+ s/one/two/
+ s,one,two,
+
+ Changing delimiters is often useful when the REGEX contains slashes.
+For example, it is more convenient to write 's,/,-,' than 's/\//-/'.
+
+ As in 'sed', you can give several replace expressions, separated by a
+semicolon.
+
+ Supported FLAGS are:
+
+'g'
+ Apply the replacement to _all_ matches to the REGEXP, not just the
+ first.
+
+'i'
+ Use case-insensitive matching.
+
+'x'
+ REGEXP is an "extended regular expression" (*note Extended regular
+ expressions: (sed)Extended regexps.).
+
+'NUMBER'
+ Only replace the NUMBERth match of the REGEXP.
+
+ Note: the POSIX standard does not specify what should happen when
+ you mix the 'g' and NUMBER modifiers. GNU 'tar' follows the GNU
+ 'sed' implementation in this regard, so the interaction is defined
+ to be: ignore matches before the NUMBERth, and then match and
+ replace all matches from the NUMBERth on.
+
+ In addition, several "transformation scope" flags are supported, that
+control to what files transformations apply. These are:
+
+'r'
+ Apply transformation to regular archive members.
+
+'R'
+ Do not apply transformation to regular archive members.
+
+'s'
+ Apply transformation to symbolic link targets.
+
+'S'
+ Do not apply transformation to symbolic link targets.
+
+'h'
+ Apply transformation to hard link targets.
+
+'H'
+ Do not apply transformation to hard link targets.
+
+ Default is 'rsh', which means to apply transformations to both
+archive members and targets of symbolic and hard links.
+
+ Default scope flags can also be changed using 'flags=' statement in
+the transform expression. The flags set this way remain in force until
+next 'flags=' statement or end of expression, whichever occurs first.
+For example:
+
+ --transform 'flags=S;s|^|/usr/local/|'
+
+ Here are several examples of '--transform' usage:
+
+ 1. Extract 'usr/' hierarchy into 'usr/local/':
+
+ $ tar --transform='s,usr/,usr/local/,' -x -f arch.tar
+
+ 2. Strip two leading directory components (equivalent to
+ '--strip-components=2'):
+
+ $ tar --transform='s,/*[^/]*/[^/]*/,,' -x -f arch.tar
+
+ 3. Convert each file name to lower case:
+
+ $ tar --transform 's/.*/\L&/' -x -f arch.tar
+
+ 4. Prepend '/prefix/' to each file name:
+
+ $ tar --transform 's,^,/prefix/,' -x -f arch.tar
+
+ 5. Archive the '/lib' directory, prepending '/usr/local' to each
+ archive member:
+
+ $ tar --transform 's,^,/usr/local/,S' -c -f arch.tar /lib
+
+ Notice the use of flags in the last example. The '/lib' directory
+often contains many symbolic links to files within it. It may look, for
+example, like this:
+
+ $ ls -l
+ drwxr-xr-x root/root 0 2008-07-08 16:20 /lib/
+ -rwxr-xr-x root/root 1250840 2008-05-25 07:44 /lib/libc-2.3.2.so
+ lrwxrwxrwx root/root 0 2008-06-24 17:12 /lib/libc.so.6 -> libc-2.3.2.so
+ ...
+
+ Using the expression 's,^,/usr/local/,' would mean adding
+'/usr/local' to both regular archive members and to link targets. In
+this case, '/lib/libc.so.6' would become:
+
+ /usr/local/lib/libc.so.6 -> /usr/local/libc-2.3.2.so
+
+ This is definitely not desired. To avoid this, the 'S' flag is used,
+which excludes symbolic link targets from filename transformations. The
+result is:
+
+ $ tar --transform 's,^,/usr/local/,S', -c -v -f arch.tar \
+ --show-transformed /lib
+ drwxr-xr-x root/root 0 2008-07-08 16:20 /usr/local/lib/
+ -rwxr-xr-x root/root 1250840 2008-05-25 07:44 /usr/local/lib/libc-2.3.2.so
+ lrwxrwxrwx root/root 0 2008-06-24 17:12 /usr/local/lib/libc.so.6 \
+ -> libc-2.3.2.so
+
+ Unlike '--strip-components', '--transform' can be used in any GNU
+'tar' operation mode. For example, the following command adds files to
+the archive while replacing the leading 'usr/' component with 'var/':
+
+ $ tar -cf arch.tar --transform='s,^usr/,var/,' /
+
+ To test '--transform' effect we suggest using
+'--show-transformed-names' option:
+
+ $ tar -cf arch.tar --transform='s,^usr/,var/,' \
+ --verbose --show-transformed-names /
+
+ If both '--strip-components' and '--transform' are used together,
+then '--transform' is applied first, and the required number of
+components is then stripped from its result.
+
+ You can use as many '--transform' options in a single command line as
+you want. The specified expressions will then be applied in order of
+their appearance. For example, the following two invocations are
+equivalent:
+
+ $ tar -cf arch.tar --transform='s,/usr/var,/var/' \
+ --transform='s,/usr/local,/usr/,'
+ $ tar -cf arch.tar \
+ --transform='s,/usr/var,/var/;s,/usr/local,/usr/,'
+
+
+File: tar.info, Node: after, Next: recurse, Prev: transform, Up: Choosing
+
+6.8 Operating Only on New Files
+===============================
+
+The '--after-date=DATE' ('--newer=DATE', '-N DATE') option causes 'tar'
+to only work on files whose data modification or status change times are
+newer than the DATE given. If DATE starts with '/' or '.', it is taken
+to be a file name; the data modification time of that file is used as
+the date. If you use this option when creating or appending to an
+archive, the archive will only include new files. If you use
+'--after-date' when extracting an archive, 'tar' will only extract files
+newer than the DATE you specify.
+
+ If you only want 'tar' to make the date comparison based on
+modification of the file's data (rather than status changes), then use
+the '--newer-mtime=DATE' option.
+
+ You may use these options with any operation. Note that these
+options differ from the '--update' ('-u') operation in that they allow
+you to specify a particular date against which 'tar' can compare when
+deciding whether or not to archive the files.
+
+'--after-date=DATE'
+'--newer=DATE'
+'-N DATE'
+ Only store files newer than DATE.
+
+ Acts on files only if their data modification or status change
+ times are later than DATE. Use in conjunction with any operation.
+
+ If DATE starts with '/' or '.', it is taken to be a file name; the
+ data modification time of that file is used as the date.
+
+'--newer-mtime=DATE'
+ Acts like '--after-date', but only looks at data modification
+ times.
+
+ These options limit 'tar' to operate only on files which have been
+modified after the date specified. A file's status is considered to
+have changed if its contents have been modified, or if its owner,
+permissions, and so forth, have been changed. (For more information on
+how to specify a date, see *note Date input formats::; remember that the
+entire date argument must be quoted if it contains any spaces.)
+
+ Gurus would say that '--after-date' tests both the data modification
+time ('mtime', the time the contents of the file were last modified) and
+the status change time ('ctime', the time the file's status was last
+changed: owner, permissions, etc.) fields, while '--newer-mtime' tests
+only the 'mtime' field.
+
+ To be precise, '--after-date' checks _both_ 'mtime' and 'ctime' and
+processes the file if either one is more recent than DATE, while
+'--newer-mtime' only checks 'mtime' and disregards 'ctime'. Neither
+does it use 'atime' (the last time the contents of the file were looked
+at).
+
+ Date specifiers can have embedded spaces. Because of this, you may
+need to quote date arguments to keep the shell from parsing them as
+separate arguments. For example, the following command will add to the
+archive all the files modified less than two days ago:
+
+ $ tar -cf foo.tar --newer-mtime '2 days ago'
+
+ When any of these options is used with the option '--verbose' (*note
+verbose tutorial::) GNU 'tar' will try to convert the specified date
+back to its textual representation and compare that with the one given
+with the option. If the two dates differ, 'tar' will print a warning
+saying what date it will use. This is to help user ensure he is using
+the right date. For example:
+
+ $ tar -c -f archive.tar --after-date='10 days ago' .
+ tar: Option --after-date: Treating date '10 days ago' as 2006-06-11
+ 13:19:37.232434
+
+ *Please Note:* '--after-date' and '--newer-mtime' should not be
+ used for incremental backups. *Note Incremental Dumps::, for
+ proper way of creating incremental backups.
+
+
+File: tar.info, Node: recurse, Next: one, Prev: after, Up: Choosing
+
+6.9 Descending into Directories
+===============================
+
+Usually, 'tar' will recursively explore all directories (either those
+given on the command line or through the '--files-from' option) for the
+various files they contain. However, you may not always want 'tar' to
+act this way.
+
+ The '--no-recursion' option inhibits 'tar''s recursive descent into
+specified directories. If you specify '--no-recursion', you can use the
+'find' (*note find: (find)Top.) utility for hunting through levels of
+directories to construct a list of file names which you could then pass
+to 'tar'. 'find' allows you to be more selective when choosing which
+files to archive; see *note files::, for more information on using
+'find' with 'tar'.
+
+'--no-recursion'
+ Prevents 'tar' from recursively descending directories.
+
+'--recursion'
+ Requires 'tar' to recursively descend directories. This is the
+ default.
+
+ When you use '--no-recursion', GNU 'tar' grabs directory entries
+themselves, but does not descend on them recursively. Many people use
+'find' for locating files they want to back up, and since 'tar'
+_usually_ recursively descends on directories, they have to use the
+'-not -type d' test in their 'find' invocation (*note Type:
+(find)Type.), as they usually do not want all the files in a directory.
+They then use the '--files-from' option to archive the files located via
+'find'.
+
+ The problem when restoring files archived in this manner is that the
+directories themselves are not in the archive; so the
+'--same-permissions' ('--preserve-permissions', '-p') option does not
+affect them--while users might really like it to. Specifying
+'--no-recursion' is a way to tell 'tar' to grab only the directory
+entries given to it, adding no new files on its own. To summarize, if
+you use 'find' to create a list of files to be stored in an archive, use
+it as follows:
+
+ $ find DIR TESTS | \
+ tar -cf ARCHIVE -T - --no-recursion
+
+ The '--no-recursion' option also applies when extracting: it causes
+'tar' to extract only the matched directory entries, not the files under
+those directories.
+
+ The '--no-recursion' option also affects how globbing patterns are
+interpreted (*note controlling pattern-matching::).
+
+ The '--no-recursion' and '--recursion' options apply to later options
+and operands, and can be overridden by later occurrences of
+'--no-recursion' and '--recursion'. For example:
+
+ $ tar -cf jams.tar --no-recursion grape --recursion grape/concord
+
+creates an archive with one entry for 'grape', and the recursive
+contents of 'grape/concord', but no entries under 'grape' other than
+'grape/concord'.
+
diff --git a/doc/tar.info-2 b/doc/tar.info-2
new file mode 100644
index 0000000..9dc6a87
--- /dev/null
+++ b/doc/tar.info-2
@@ -0,0 +1,7007 @@
+This is tar.info, produced by makeinfo version 5.9.93 from tar.texi.
+
+This manual is for GNU 'tar' (version 1.29, 14 April 2016), which
+creates and extracts files from archives.
+
+ Copyright (C) 1992, 1994-1997, 1999-2001, 2003-2016 Free Software
+Foundation, Inc.
+
+ Permission is granted to copy, distribute and/or modify this
+ document under the terms of the GNU Free Documentation License,
+ Version 1.3 or any later version published by the Free Software
+ Foundation; with the Invariant Sections being "GNU General Public
+ License", with the Front-Cover Texts being "A GNU Manual", and with
+ the Back-Cover Texts as in (a) below. A copy of the license is
+ included in the section entitled "GNU Free Documentation License".
+
+ (a) The FSF's Back-Cover Text is: "You have the freedom to copy and
+ modify this GNU manual."
+INFO-DIR-SECTION Archiving
+START-INFO-DIR-ENTRY
+* Tar: (tar). Making tape (or disk) archives.
+END-INFO-DIR-ENTRY
+
+INFO-DIR-SECTION Individual utilities
+START-INFO-DIR-ENTRY
+* tar: (tar)tar invocation. Invoking GNU 'tar'.
+END-INFO-DIR-ENTRY
+
+
+File: tar.info, Node: one, Prev: recurse, Up: Choosing
+
+6.10 Crossing File System Boundaries
+====================================
+
+'tar' will normally automatically cross file system boundaries in order
+to archive files which are part of a directory tree. You can change
+this behavior by running 'tar' and specifying '--one-file-system'. This
+option only affects files that are archived because they are in a
+directory that is being archived; 'tar' will still archive files
+explicitly named on the command line or through '--files-from',
+regardless of where they reside.
+
+'--one-file-system'
+ Prevents 'tar' from crossing file system boundaries when archiving.
+ Use in conjunction with any write operation.
+
+ The '--one-file-system' option causes 'tar' to modify its normal
+behavior in archiving the contents of directories. If a file in a
+directory is not on the same file system as the directory itself, then
+'tar' will not archive that file. If the file is a directory itself,
+'tar' will not archive anything beneath it; in other words, 'tar' will
+not cross mount points.
+
+ This option is useful for making full or incremental archival backups
+of a file system. If this option is used in conjunction with
+'--verbose' ('-v'), files that are excluded are mentioned by name on the
+standard error.
+
+* Menu:
+
+* directory:: Changing Directory
+* absolute:: Absolute File Names
+
+
+File: tar.info, Node: directory, Next: absolute, Up: one
+
+6.10.1 Changing the Working Directory
+-------------------------------------
+
+To change the working directory in the middle of a list of file names,
+either on the command line or in a file specified using '--files-from'
+('-T'), use '--directory' ('-C'). This will change the working
+directory to the specified directory after that point in the list.
+
+'--directory=DIRECTORY'
+'-C DIRECTORY'
+ Changes the working directory in the middle of a command line.
+
+ For example,
+
+ $ tar -c -f jams.tar grape prune -C food cherry
+
+will place the files 'grape' and 'prune' from the current directory into
+the archive 'jams.tar', followed by the file 'cherry' from the directory
+'food'. This option is especially useful when you have several widely
+separated files that you want to store in the same archive.
+
+ Note that the file 'cherry' is recorded in the archive under the
+precise name 'cherry', _not_ 'food/cherry'. Thus, the archive will
+contain three files that all appear to have come from the same
+directory; if the archive is extracted with plain 'tar --extract', all
+three files will be written in the current directory.
+
+ Contrast this with the command,
+
+ $ tar -c -f jams.tar grape prune -C food red/cherry
+
+which records the third file in the archive under the name 'red/cherry'
+so that, if the archive is extracted using 'tar --extract', the third
+file will be written in a subdirectory named 'red'.
+
+ You can use the '--directory' option to make the archive independent
+of the original name of the directory holding the files. The following
+command places the files '/etc/passwd', '/etc/hosts', and '/lib/libc.a'
+into the archive 'foo.tar':
+
+ $ tar -c -f foo.tar -C /etc passwd hosts -C /lib libc.a
+
+However, the names of the archive members will be exactly what they were
+on the command line: 'passwd', 'hosts', and 'libc.a'. They will not
+appear to be related by file name to the original directories where
+those files were located.
+
+ Note that '--directory' options are interpreted consecutively. If
+'--directory' specifies a relative file name, it is interpreted relative
+to the then current directory, which might not be the same as the
+original current working directory of 'tar', due to a previous
+'--directory' option.
+
+ When using '--files-from' (*note files::), you can put various 'tar'
+options (including '-C') in the file list. Notice, however, that in
+this case the option and its argument may not be separated by
+whitespace. If you use short option, its argument must either follow
+the option letter immediately, without any intervening whitespace, or
+occupy the next line. Otherwise, if you use long option, separate its
+argument by an equal sign.
+
+ For instance, the file list for the above example will be:
+
+ -C/etc
+ passwd
+ hosts
+ --directory=/lib
+ libc.a
+
+To use it, you would invoke 'tar' as follows:
+
+ $ tar -c -f foo.tar --files-from list
+
+ The interpretation of options in file lists is disabled by
+'--verbatim-files-from' and '--null' options.
+
+
+File: tar.info, Node: absolute, Prev: directory, Up: one
+
+6.10.2 Absolute File Names
+--------------------------
+
+By default, GNU 'tar' drops a leading '/' on input or output, and
+complains about file names containing a '..' component. There is an
+option that turns off this behavior:
+
+'--absolute-names'
+'-P'
+ Do not strip leading slashes from file names, and permit file names
+ containing a '..' file name component.
+
+ When 'tar' extracts archive members from an archive, it strips any
+leading slashes ('/') from the member name. This causes absolute member
+names in the archive to be treated as relative file names. This allows
+you to have such members extracted wherever you want, instead of being
+restricted to extracting the member in the exact directory named in the
+archive. For example, if the archive member has the name '/etc/passwd',
+'tar' will extract it as if the name were really 'etc/passwd'.
+
+ File names containing '..' can cause problems when extracting, so
+'tar' normally warns you about such files when creating an archive, and
+rejects attempts to extracts such files.
+
+ Other 'tar' programs do not do this. As a result, if you create an
+archive whose member names start with a slash, they will be difficult
+for other people with a non-GNU 'tar' program to use. Therefore, GNU
+'tar' also strips leading slashes from member names when putting members
+into the archive. For example, if you ask 'tar' to add the file
+'/bin/ls' to an archive, it will do so, but the member name will be
+'bin/ls'(1).
+
+ Symbolic links containing '..' or leading '/' can also cause problems
+when extracting, so 'tar' normally extracts them last; it may create
+empty files as placeholders during extraction.
+
+ If you use the '--absolute-names' ('-P') option, 'tar' will do none
+of these transformations.
+
+ To archive or extract files relative to the root directory, specify
+the '--absolute-names' ('-P') option.
+
+ Normally, 'tar' acts on files relative to the working
+directory--ignoring superior directory names when archiving, and
+ignoring leading slashes when extracting.
+
+ When you specify '--absolute-names' ('-P'), 'tar' stores file names
+including all superior directory names, and preserves leading slashes.
+If you only invoked 'tar' from the root directory you would never need
+the '--absolute-names' option, but using this option may be more
+convenient than switching to root.
+
+'--absolute-names'
+ Preserves full file names (including superior directory names) when
+ archiving and extracting files.
+
+ 'tar' prints out a message about removing the '/' from file names.
+This message appears once per GNU 'tar' invocation. It represents
+something which ought to be told; ignoring what it means can cause very
+serious surprises, later.
+
+ Some people, nevertheless, do not want to see this message. Wanting
+to play really dangerously, one may of course redirect 'tar' standard
+error to the sink. For example, under 'sh':
+
+ $ tar -c -f archive.tar /home 2> /dev/null
+
+Another solution, both nicer and simpler, would be to change to the '/'
+directory first, and then avoid absolute notation. For example:
+
+ $ tar -c -f archive.tar -C / home
+
+ *Note Integrity::, for some of the security-related implications of
+using this option.
+
+ ---------- Footnotes ----------
+
+ (1) A side effect of this is that when '--create' is used with
+'--verbose' the resulting output is not, generally speaking, the same as
+the one you'd get running 'tar --list' command. This may be important
+if you use some scripts for comparing both outputs. *Note listing
+member and file names::, for the information on how to handle this case.
+
+
+File: tar.info, Node: Date input formats, Next: Formats, Prev: Choosing, Up: Top
+
+7 Date input formats
+********************
+
+First, a quote:
+
+ Our units of temporal measurement, from seconds on up to months,
+ are so complicated, asymmetrical and disjunctive so as to make
+ coherent mental reckoning in time all but impossible. Indeed, had
+ some tyrannical god contrived to enslave our minds to time, to make
+ it all but impossible for us to escape subjection to sodden
+ routines and unpleasant surprises, he could hardly have done better
+ than handing down our present system. It is like a set of
+ trapezoidal building blocks, with no vertical or horizontal
+ surfaces, like a language in which the simplest thought demands
+ ornate constructions, useless particles and lengthy
+ circumlocutions. Unlike the more successful patterns of language
+ and science, which enable us to face experience boldly or at least
+ level-headedly, our system of temporal calculation silently and
+ persistently encourages our terror of time.
+
+ ... It is as though architects had to measure length in feet, width
+ in meters and height in ells; as though basic instruction manuals
+ demanded a knowledge of five different languages. It is no wonder
+ then that we often look into our own immediate past or future, last
+ Tuesday or a week from Sunday, with feelings of helpless confusion.
+ ...
+
+ --Robert Grudin, 'Time and the Art of Living'.
+
+ This section describes the textual date representations that GNU
+programs accept. These are the strings you, as a user, can supply as
+arguments to the various programs. The C interface (via the
+'parse_datetime' function) is not described here.
+
+* Menu:
+
+* General date syntax:: Common rules.
+* Calendar date items:: 19 Dec 1994.
+* Time of day items:: 9:20pm.
+* Time zone items:: EST, PDT, UTC, ...
+* Combined date and time of day items:: 1972-09-24T20:02:00,000000-0500.
+* Day of week items:: Monday and others.
+* Relative items in date strings:: next tuesday, 2 years ago.
+* Pure numbers in date strings:: 19931219, 1440.
+* Seconds since the Epoch:: @1078100502.
+* Specifying time zone rules:: TZ="America/New_York", TZ="UTC0".
+* Authors of parse_datetime:: Bellovin, Eggert, Salz, Berets, et al.
+
+
+File: tar.info, Node: General date syntax, Next: Calendar date items, Up: Date input formats
+
+7.1 General date syntax
+=======================
+
+A "date" is a string, possibly empty, containing many items separated by
+whitespace. The whitespace may be omitted when no ambiguity arises.
+The empty string means the beginning of today (i.e., midnight). Order
+of the items is immaterial. A date string may contain many flavors of
+items:
+
+ * calendar date items
+ * time of day items
+ * time zone items
+ * combined date and time of day items
+ * day of the week items
+ * relative items
+ * pure numbers.
+
+We describe each of these item types in turn, below.
+
+ A few ordinal numbers may be written out in words in some contexts.
+This is most useful for specifying day of the week items or relative
+items (see below). Among the most commonly used ordinal numbers, the
+word 'last' stands for -1, 'this' stands for 0, and 'first' and 'next'
+both stand for 1. Because the word 'second' stands for the unit of time
+there is no way to write the ordinal number 2, but for convenience
+'third' stands for 3, 'fourth' for 4, 'fifth' for 5, 'sixth' for 6,
+'seventh' for 7, 'eighth' for 8, 'ninth' for 9, 'tenth' for 10,
+'eleventh' for 11 and 'twelfth' for 12.
+
+ When a month is written this way, it is still considered to be
+written numerically, instead of being "spelled in full"; this changes
+the allowed strings.
+
+ In the current implementation, only English is supported for words
+and abbreviations like 'AM', 'DST', 'EST', 'first', 'January', 'Sunday',
+'tomorrow', and 'year'.
+
+ The output of the 'date' command is not always acceptable as a date
+string, not only because of the language problem, but also because there
+is no standard meaning for time zone items like 'IST'. When using
+'date' to generate a date string intended to be parsed later, specify a
+date format that is independent of language and that does not use time
+zone items other than 'UTC' and 'Z'. Here are some ways to do this:
+
+ $ LC_ALL=C TZ=UTC0 date
+ Mon Mar 1 00:21:42 UTC 2004
+ $ TZ=UTC0 date +'%Y-%m-%d %H:%M:%SZ'
+ 2004-03-01 00:21:42Z
+ $ date --rfc-3339=ns # --rfc-3339 is a GNU extension.
+ 2004-02-29 16:21:42.692722128-08:00
+ $ date --rfc-2822 # a GNU extension
+ Sun, 29 Feb 2004 16:21:42 -0800
+ $ date +'%Y-%m-%d %H:%M:%S %z' # %z is a GNU extension.
+ 2004-02-29 16:21:42 -0800
+ $ date +'@%s.%N' # %s and %N are GNU extensions.
+ @1078100502.692722128
+
+ Alphabetic case is completely ignored in dates. Comments may be
+introduced between round parentheses, as long as included parentheses
+are properly nested. Hyphens not followed by a digit are currently
+ignored. Leading zeros on numbers are ignored.
+
+ Invalid dates like '2005-02-29' or times like '24:00' are rejected.
+In the typical case of a host that does not support leap seconds, a time
+like '23:59:60' is rejected even if it corresponds to a valid leap
+second.
+
+
+File: tar.info, Node: Calendar date items, Next: Time of day items, Prev: General date syntax, Up: Date input formats
+
+7.2 Calendar date items
+=======================
+
+A "calendar date item" specifies a day of the year. It is specified
+differently, depending on whether the month is specified numerically or
+literally. All these strings specify the same calendar date:
+
+ 1972-09-24 # ISO 8601.
+ 72-9-24 # Assume 19xx for 69 through 99,
+ # 20xx for 00 through 68.
+ 72-09-24 # Leading zeros are ignored.
+ 9/24/72 # Common U.S. writing.
+ 24 September 1972
+ 24 Sept 72 # September has a special abbreviation.
+ 24 Sep 72 # Three-letter abbreviations always allowed.
+ Sep 24, 1972
+ 24-sep-72
+ 24sep72
+
+ The year can also be omitted. In this case, the last specified year
+is used, or the current year if none. For example:
+
+ 9/24
+ sep 24
+
+ Here are the rules.
+
+ For numeric months, the ISO 8601 format 'YEAR-MONTH-DAY' is allowed,
+where YEAR is any positive number, MONTH is a number between 01 and 12,
+and DAY is a number between 01 and 31. A leading zero must be present
+if a number is less than ten. If YEAR is 68 or smaller, then 2000 is
+added to it; otherwise, if YEAR is less than 100, then 1900 is added to
+it. The construct 'MONTH/DAY/YEAR', popular in the United States, is
+accepted. Also 'MONTH/DAY', omitting the year.
+
+ Literal months may be spelled out in full: 'January', 'February',
+'March', 'April', 'May', 'June', 'July', 'August', 'September',
+'October', 'November' or 'December'. Literal months may be abbreviated
+to their first three letters, possibly followed by an abbreviating dot.
+It is also permitted to write 'Sept' instead of 'September'.
+
+ When months are written literally, the calendar date may be given as
+any of the following:
+
+ DAY MONTH YEAR
+ DAY MONTH
+ MONTH DAY YEAR
+ DAY-MONTH-YEAR
+
+ Or, omitting the year:
+
+ MONTH DAY
+
+
+File: tar.info, Node: Time of day items, Next: Time zone items, Prev: Calendar date items, Up: Date input formats
+
+7.3 Time of day items
+=====================
+
+A "time of day item" in date strings specifies the time on a given day.
+Here are some examples, all of which represent the same time:
+
+ 20:02:00.000000
+ 20:02
+ 8:02pm
+ 20:02-0500 # In EST (U.S. Eastern Standard Time).
+
+ More generally, the time of day may be given as 'HOUR:MINUTE:SECOND',
+where HOUR is a number between 0 and 23, MINUTE is a number between 0
+and 59, and SECOND is a number between 0 and 59 possibly followed by '.'
+or ',' and a fraction containing one or more digits. Alternatively,
+':SECOND' can be omitted, in which case it is taken to be zero. On the
+rare hosts that support leap seconds, SECOND may be 60.
+
+ If the time is followed by 'am' or 'pm' (or 'a.m.' or 'p.m.'), HOUR
+is restricted to run from 1 to 12, and ':MINUTE' may be omitted (taken
+to be zero). 'am' indicates the first half of the day, 'pm' indicates
+the second half of the day. In this notation, 12 is the predecessor of
+1: midnight is '12am' while noon is '12pm'. (This is the zero-oriented
+interpretation of '12am' and '12pm', as opposed to the old tradition
+derived from Latin which uses '12m' for noon and '12pm' for midnight.)
+
+ The time may alternatively be followed by a time zone correction,
+expressed as 'SHHMM', where S is '+' or '-', HH is a number of zone
+hours and MM is a number of zone minutes. The zone minutes term, MM,
+may be omitted, in which case the one- or two-digit correction is
+interpreted as a number of hours. You can also separate HH from MM with
+a colon. When a time zone correction is given this way, it forces
+interpretation of the time relative to Coordinated Universal Time (UTC),
+overriding any previous specification for the time zone or the local
+time zone. For example, '+0530' and '+05:30' both stand for the time
+zone 5.5 hours ahead of UTC (e.g., India). This is the best way to
+specify a time zone correction by fractional parts of an hour. The
+maximum zone correction is 24 hours.
+
+ Either 'am'/'pm' or a time zone correction may be specified, but not
+both.
+
+
+File: tar.info, Node: Time zone items, Next: Combined date and time of day items, Prev: Time of day items, Up: Date input formats
+
+7.4 Time zone items
+===================
+
+A "time zone item" specifies an international time zone, indicated by a
+small set of letters, e.g., 'UTC' or 'Z' for Coordinated Universal Time.
+Any included periods are ignored. By following a non-daylight-saving
+time zone by the string 'DST' in a separate word (that is, separated by
+some white space), the corresponding daylight saving time zone may be
+specified. Alternatively, a non-daylight-saving time zone can be
+followed by a time zone correction, to add the two values. This is
+normally done only for 'UTC'; for example, 'UTC+05:30' is equivalent to
+'+05:30'.
+
+ Time zone items other than 'UTC' and 'Z' are obsolescent and are not
+recommended, because they are ambiguous; for example, 'EST' has a
+different meaning in Australia than in the United States. Instead, it's
+better to use unambiguous numeric time zone corrections like '-0500', as
+described in the previous section.
+
+ If neither a time zone item nor a time zone correction is supplied,
+time stamps are interpreted using the rules of the default time zone
+(*note Specifying time zone rules::).
+
+
+File: tar.info, Node: Combined date and time of day items, Next: Day of week items, Prev: Time zone items, Up: Date input formats
+
+7.5 Combined date and time of day items
+=======================================
+
+The ISO 8601 date and time of day extended format consists of an ISO
+8601 date, a 'T' character separator, and an ISO 8601 time of day. This
+format is also recognized if the 'T' is replaced by a space.
+
+ In this format, the time of day should use 24-hour notation.
+Fractional seconds are allowed, with either comma or period preceding
+the fraction. ISO 8601 fractional minutes and hours are not supported.
+Typically, hosts support nanosecond timestamp resolution; excess
+precision is silently discarded.
+
+ Here are some examples:
+
+ 2012-09-24T20:02:00.052-0500
+ 2012-12-31T23:59:59,999999999+1100
+ 1970-01-01 00:00Z
+
+
+File: tar.info, Node: Day of week items, Next: Relative items in date strings, Prev: Combined date and time of day items, Up: Date input formats
+
+7.6 Day of week items
+=====================
+
+The explicit mention of a day of the week will forward the date (only if
+necessary) to reach that day of the week in the future.
+
+ Days of the week may be spelled out in full: 'Sunday', 'Monday',
+'Tuesday', 'Wednesday', 'Thursday', 'Friday' or 'Saturday'. Days may be
+abbreviated to their first three letters, optionally followed by a
+period. The special abbreviations 'Tues' for 'Tuesday', 'Wednes' for
+'Wednesday' and 'Thur' or 'Thurs' for 'Thursday' are also allowed.
+
+ A number may precede a day of the week item to move forward
+supplementary weeks. It is best used in expression like 'third monday'.
+In this context, 'last DAY' or 'next DAY' is also acceptable; they move
+one week before or after the day that DAY by itself would represent.
+
+ A comma following a day of the week item is ignored.
+
+
+File: tar.info, Node: Relative items in date strings, Next: Pure numbers in date strings, Prev: Day of week items, Up: Date input formats
+
+7.7 Relative items in date strings
+==================================
+
+"Relative items" adjust a date (or the current date if none) forward or
+backward. The effects of relative items accumulate. Here are some
+examples:
+
+ 1 year
+ 1 year ago
+ 3 years
+ 2 days
+
+ The unit of time displacement may be selected by the string 'year' or
+'month' for moving by whole years or months. These are fuzzy units, as
+years and months are not all of equal duration. More precise units are
+'fortnight' which is worth 14 days, 'week' worth 7 days, 'day' worth 24
+hours, 'hour' worth 60 minutes, 'minute' or 'min' worth 60 seconds, and
+'second' or 'sec' worth one second. An 's' suffix on these units is
+accepted and ignored.
+
+ The unit of time may be preceded by a multiplier, given as an
+optionally signed number. Unsigned numbers are taken as positively
+signed. No number at all implies 1 for a multiplier. Following a
+relative item by the string 'ago' is equivalent to preceding the unit by
+a multiplier with value -1.
+
+ The string 'tomorrow' is worth one day in the future (equivalent to
+'day'), the string 'yesterday' is worth one day in the past (equivalent
+to 'day ago').
+
+ The strings 'now' or 'today' are relative items corresponding to
+zero-valued time displacement, these strings come from the fact a
+zero-valued time displacement represents the current time when not
+otherwise changed by previous items. They may be used to stress other
+items, like in '12:00 today'. The string 'this' also has the meaning of
+a zero-valued time displacement, but is preferred in date strings like
+'this thursday'.
+
+ When a relative item causes the resulting date to cross a boundary
+where the clocks were adjusted, typically for daylight saving time, the
+resulting date and time are adjusted accordingly.
+
+ The fuzz in units can cause problems with relative items. For
+example, '2003-07-31 -1 month' might evaluate to 2003-07-01, because
+2003-06-31 is an invalid date. To determine the previous month more
+reliably, you can ask for the month before the 15th of the current
+month. For example:
+
+ $ date -R
+ Thu, 31 Jul 2003 13:02:39 -0700
+ $ date --date='-1 month' +'Last month was %B?'
+ Last month was July?
+ $ date --date="$(date +%Y-%m-15) -1 month" +'Last month was %B!'
+ Last month was June!
+
+ Also, take care when manipulating dates around clock changes such as
+daylight saving leaps. In a few cases these have added or subtracted as
+much as 24 hours from the clock, so it is often wise to adopt universal
+time by setting the 'TZ' environment variable to 'UTC0' before embarking
+on calendrical calculations.
+
+
+File: tar.info, Node: Pure numbers in date strings, Next: Seconds since the Epoch, Prev: Relative items in date strings, Up: Date input formats
+
+7.8 Pure numbers in date strings
+================================
+
+The precise interpretation of a pure decimal number depends on the
+context in the date string.
+
+ If the decimal number is of the form YYYYMMDD and no other calendar
+date item (*note Calendar date items::) appears before it in the date
+string, then YYYY is read as the year, MM as the month number and DD as
+the day of the month, for the specified calendar date.
+
+ If the decimal number is of the form HHMM and no other time of day
+item appears before it in the date string, then HH is read as the hour
+of the day and MM as the minute of the hour, for the specified time of
+day. MM can also be omitted.
+
+ If both a calendar date and a time of day appear to the left of a
+number in the date string, but no relative item, then the number
+overrides the year.
+
+
+File: tar.info, Node: Seconds since the Epoch, Next: Specifying time zone rules, Prev: Pure numbers in date strings, Up: Date input formats
+
+7.9 Seconds since the Epoch
+===========================
+
+If you precede a number with '@', it represents an internal time stamp
+as a count of seconds. The number can contain an internal decimal point
+(either '.' or ','); any excess precision not supported by the internal
+representation is truncated toward minus infinity. Such a number cannot
+be combined with any other date item, as it specifies a complete time
+stamp.
+
+ Internally, computer times are represented as a count of seconds
+since an epoch--a well-defined point of time. On GNU and POSIX systems,
+the epoch is 1970-01-01 00:00:00 UTC, so '@0' represents this time, '@1'
+represents 1970-01-01 00:00:01 UTC, and so forth. GNU and most other
+POSIX-compliant systems support such times as an extension to POSIX,
+using negative counts, so that '@-1' represents 1969-12-31 23:59:59 UTC.
+
+ Traditional Unix systems count seconds with 32-bit two's-complement
+integers and can represent times from 1901-12-13 20:45:52 through
+2038-01-19 03:14:07 UTC. More modern systems use 64-bit counts of
+seconds with nanosecond subcounts, and can represent all the times in
+the known lifetime of the universe to a resolution of 1 nanosecond.
+
+ On most hosts, these counts ignore the presence of leap seconds. For
+example, on most hosts '@915148799' represents 1998-12-31 23:59:59 UTC,
+'@915148800' represents 1999-01-01 00:00:00 UTC, and there is no way to
+represent the intervening leap second 1998-12-31 23:59:60 UTC.
+
+
+File: tar.info, Node: Specifying time zone rules, Next: Authors of parse_datetime, Prev: Seconds since the Epoch, Up: Date input formats
+
+7.10 Specifying time zone rules
+===============================
+
+Normally, dates are interpreted using the rules of the current time
+zone, which in turn are specified by the 'TZ' environment variable, or
+by a system default if 'TZ' is not set. To specify a different set of
+default time zone rules that apply just to one date, start the date with
+a string of the form 'TZ="RULE"'. The two quote characters ('"') must
+be present in the date, and any quotes or backslashes within RULE must
+be escaped by a backslash.
+
+ For example, with the GNU 'date' command you can answer the question
+"What time is it in New York when a Paris clock shows 6:30am on October
+31, 2004?" by using a date beginning with 'TZ="Europe/Paris"' as shown
+in the following shell transcript:
+
+ $ export TZ="America/New_York"
+ $ date --date='TZ="Europe/Paris" 2004-10-31 06:30'
+ Sun Oct 31 01:30:00 EDT 2004
+
+ In this example, the '--date' operand begins with its own 'TZ'
+setting, so the rest of that operand is processed according to
+'Europe/Paris' rules, treating the string '2004-10-31 06:30' as if it
+were in Paris. However, since the output of the 'date' command is
+processed according to the overall time zone rules, it uses New York
+time. (Paris was normally six hours ahead of New York in 2004, but this
+example refers to a brief Halloween period when the gap was five hours.)
+
+ A 'TZ' value is a rule that typically names a location in the 'tz'
+database (http://www.twinsun.com/tz/tz-link.htm). A recent catalog of
+location names appears in the TWiki Date and Time Gateway
+(http://twiki.org/cgi-bin/xtra/tzdate). A few non-GNU hosts require a
+colon before a location name in a 'TZ' setting, e.g.,
+'TZ=":America/New_York"'.
+
+ The 'tz' database includes a wide variety of locations ranging from
+'Arctic/Longyearbyen' to 'Antarctica/South_Pole', but if you are at sea
+and have your own private time zone, or if you are using a non-GNU host
+that does not support the 'tz' database, you may need to use a POSIX
+rule instead. Simple POSIX rules like 'UTC0' specify a time zone
+without daylight saving time; other rules can specify simple daylight
+saving regimes. *Note Specifying the Time Zone with 'TZ': (libc)TZ
+Variable.
+
+
+File: tar.info, Node: Authors of parse_datetime, Prev: Specifying time zone rules, Up: Date input formats
+
+7.11 Authors of 'parse_datetime'
+================================
+
+'parse_datetime' started life as 'getdate', as originally implemented by
+Steven M. Bellovin (<smb@research.att.com>) while at the University of
+North Carolina at Chapel Hill. The code was later tweaked by a couple
+of people on Usenet, then completely overhauled by Rich $alz
+(<rsalz@bbn.com>) and Jim Berets (<jberets@bbn.com>) in August, 1990.
+Various revisions for the GNU system were made by David MacKenzie, Jim
+Meyering, Paul Eggert and others, including renaming it to 'get_date' to
+avoid a conflict with the alternative Posix function 'getdate', and a
+later rename to 'parse_datetime'. The Posix function 'getdate' can
+parse more locale-specific dates using 'strptime', but relies on an
+environment variable and external file, and lacks the thread-safety of
+'parse_datetime'.
+
+ This chapter was originally produced by Franc,ois Pinard
+(<pinard@iro.umontreal.ca>) from the 'parse_datetime.y' source code, and
+then edited by K. Berry (<kb@cs.umb.edu>).
+
+
+File: tar.info, Node: Formats, Next: Media, Prev: Date input formats, Up: Top
+
+8 Controlling the Archive Format
+********************************
+
+Due to historical reasons, there are several formats of tar archives.
+All of them are based on the same principles, but have some subtle
+differences that often make them incompatible with each other.
+
+ GNU tar is able to create and handle archives in a variety of
+formats. The most frequently used formats are (in alphabetical order):
+
+gnu
+ Format used by GNU 'tar' versions up to 1.13.25. This format
+ derived from an early POSIX standard, adding some improvements such
+ as sparse file handling and incremental archives. Unfortunately
+ these features were implemented in a way incompatible with other
+ archive formats.
+
+ Archives in 'gnu' format are able to hold file names of unlimited
+ length.
+
+oldgnu
+ Format used by GNU 'tar' of versions prior to 1.12.
+
+v7
+ Archive format, compatible with the V7 implementation of tar. This
+ format imposes a number of limitations. The most important of them
+ are:
+
+ 1. The maximum length of a file name is limited to 99 characters.
+ 2. The maximum length of a symbolic link is limited to 99
+ characters.
+ 3. It is impossible to store special files (block and character
+ devices, fifos etc.)
+ 4. Maximum value of user or group ID is limited to 2097151
+ (7777777 octal)
+ 5. V7 archives do not contain symbolic ownership information
+ (user and group name of the file owner).
+
+ This format has traditionally been used by Automake when producing
+ Makefiles. This practice will change in the future, in the
+ meantime, however this means that projects containing file names
+ more than 99 characters long will not be able to use GNU 'tar' 1.29
+ and Automake prior to 1.9.
+
+ustar
+ Archive format defined by POSIX.1-1988 specification. It stores
+ symbolic ownership information. It is also able to store special
+ files. However, it imposes several restrictions as well:
+
+ 1. The maximum length of a file name is limited to 256
+ characters, provided that the file name can be split at a
+ directory separator in two parts, first of them being at most
+ 155 bytes long. So, in most cases the maximum file name
+ length will be shorter than 256 characters.
+ 2. The maximum length of a symbolic link name is limited to 100
+ characters.
+ 3. Maximum size of a file the archive is able to accommodate is
+ 8GB
+ 4. Maximum value of UID/GID is 2097151.
+ 5. Maximum number of bits in device major and minor numbers is
+ 21.
+
+star
+ Format used by Jo"rg Schilling 'star' implementation. GNU 'tar' is
+ able to read 'star' archives but currently does not produce them.
+
+posix
+ Archive format defined by POSIX.1-2001 specification. This is the
+ most flexible and feature-rich format. It does not impose any
+ restrictions on file sizes or file name lengths. This format is
+ quite recent, so not all tar implementations are able to handle it
+ properly. However, this format is designed in such a way that any
+ tar implementation able to read 'ustar' archives will be able to
+ read most 'posix' archives as well, with the only exception that
+ any additional information (such as long file names etc.) will in
+ such case be extracted as plain text files along with the files it
+ refers to.
+
+ This archive format will be the default format for future versions
+ of GNU 'tar'.
+
+ The following table summarizes the limitations of each of these
+formats:
+
+Format UID File Size File Name Devn
+--------------------------------------------------------------------
+gnu 1.8e19 Unlimited Unlimited 63
+oldgnu 1.8e19 Unlimited Unlimited 63
+v7 2097151 8GB 99 n/a
+ustar 2097151 8GB 256 21
+posix Unlimited Unlimited Unlimited Unlimited
+
+ The default format for GNU 'tar' is defined at compilation time. You
+may check it by running 'tar --help', and examining the last lines of
+its output. Usually, GNU 'tar' is configured to create archives in
+'gnu' format, however, future version will switch to 'posix'.
+
+* Menu:
+
+* Compression:: Using Less Space through Compression
+* Attributes:: Handling File Attributes
+* Portability:: Making 'tar' Archives More Portable
+* cpio:: Comparison of 'tar' and 'cpio'
+
+
+File: tar.info, Node: Compression, Next: Attributes, Up: Formats
+
+8.1 Using Less Space through Compression
+========================================
+
+* Menu:
+
+* gzip:: Creating and Reading Compressed Archives
+* sparse:: Archiving Sparse Files
+
+
+File: tar.info, Node: gzip, Next: sparse, Up: Compression
+
+8.1.1 Creating and Reading Compressed Archives
+----------------------------------------------
+
+GNU 'tar' is able to create and read compressed archives. It supports a
+wide variety of compression programs, namely: 'gzip', 'bzip2', 'lzip',
+'lzma', 'lzop', 'xz' and traditional 'compress'. The latter is
+supported mostly for backward compatibility, and we recommend against
+using it, because it is by far less effective than the other compression
+programs(1).
+
+ Creating a compressed archive is simple: you just specify a
+"compression option" along with the usual archive creation commands.
+The compression option is '-z' ('--gzip') to create a 'gzip' compressed
+archive, '-j' ('--bzip2') to create a 'bzip2' compressed archive,
+'--lzip' to create an lzip compressed archive, '-J' ('--xz') to create
+an XZ archive, '--lzma' to create an LZMA compressed archive, '--lzop'
+to create an LSOP archive, and '-Z' ('--compress') to use 'compress'
+program. For example:
+
+ $ tar czf archive.tar.gz .
+
+ You can also let GNU 'tar' select the compression program based on
+the suffix of the archive file name. This is done using
+'--auto-compress' ('-a') command line option. For example, the
+following invocation will use 'bzip2' for compression:
+
+ $ tar caf archive.tar.bz2 .
+
+whereas the following one will use 'lzma':
+
+ $ tar caf archive.tar.lzma .
+
+ For a complete list of file name suffixes recognized by GNU 'tar',
+see *note auto-compress::.
+
+ Reading compressed archive is even simpler: you don't need to specify
+any additional options as GNU 'tar' recognizes its format automatically.
+Thus, the following commands will list and extract the archive created
+in previous example:
+
+ # List the compressed archive
+ $ tar tf archive.tar.gz
+ # Extract the compressed archive
+ $ tar xf archive.tar.gz
+
+ The format recognition algorithm is based on "signatures", a special
+byte sequences in the beginning of file, that are specific for certain
+compression formats. If this approach fails, 'tar' falls back to using
+archive name suffix to determine its format (*note auto-compress::, for
+a list of recognized suffixes).
+
+ Some compression programs are able to handle different compression
+formats. GNU 'tar' uses this, if the principal decompressor for the
+given format is not available. For example, if 'compress' is not
+installed, 'tar' will try to use 'gzip'. As of version 1.29 the
+following alternatives are tried(2):
+
+Format Main decompressor Alternatives
+---------------------------------------------------------------------
+compress compress gzip
+lzma lzma xz
+bzip2 bzip2 lbzip2
+
+ The only case when you have to specify a decompression option while
+reading the archive is when reading from a pipe or from a tape drive
+that does not support random access. However, in this case GNU 'tar'
+will indicate which option you should use. For example:
+
+ $ cat archive.tar.gz | tar tf -
+ tar: Archive is compressed. Use -z option
+ tar: Error is not recoverable: exiting now
+
+ If you see such diagnostics, just add the suggested option to the
+invocation of GNU 'tar':
+
+ $ cat archive.tar.gz | tar tzf -
+
+ Notice also, that there are several restrictions on operations on
+compressed archives. First of all, compressed archives cannot be
+modified, i.e., you cannot update ('--update', alias '-u') them or
+delete ('--delete') members from them or add ('--append', alias '-r')
+members to them. Likewise, you cannot append another 'tar' archive to a
+compressed archive using '--concatenate' ('-A'). Secondly, multi-volume
+archives cannot be compressed.
+
+ The following options allow to select a particular compressor
+program:
+
+'-z'
+'--gzip'
+'--ungzip'
+ Filter the archive through 'gzip'.
+
+'-J'
+'--xz'
+ Filter the archive through 'xz'.
+
+'-j'
+'--bzip2'
+ Filter the archive through 'bzip2'.
+
+'--lzip'
+ Filter the archive through 'lzip'.
+
+'--lzma'
+ Filter the archive through 'lzma'.
+
+'--lzop'
+ Filter the archive through 'lzop'.
+
+'-Z'
+'--compress'
+'--uncompress'
+ Filter the archive through 'compress'.
+
+ When any of these options is given, GNU 'tar' searches the compressor
+binary in the current path and invokes it. The name of the compressor
+program is specified at compilation time using a corresponding
+'--with-COMPNAME' option to 'configure', e.g. '--with-bzip2' to select
+a specific 'bzip2' binary. *Note lbzip2::, for a detailed discussion.
+
+ The output produced by 'tar --help' shows the actual compressor names
+along with each of these options.
+
+ You can use any of these options on physical devices (tape drives,
+etc.) and remote files as well as on normal files; data to or from such
+devices or remote files is reblocked by another copy of the 'tar'
+program to enforce the specified (or default) record size. The default
+compression parameters are used. You can override them by using the
+'-I' option (see below), e.g.:
+
+ $ tar -cf archive.tar.gz -I 'gzip -9 -n' subdir
+
+A more traditional way to do this is to use a pipe:
+
+ $ tar cf - subdir | gzip -9 -n > archive.tar.gz
+
+ Compressed archives are easily corrupted, because compressed files
+have little redundancy. The adaptive nature of the compression scheme
+means that the compression tables are implicitly spread all over the
+archive. If you lose a few blocks, the dynamic construction of the
+compression tables becomes unsynchronized, and there is little chance
+that you could recover later in the archive.
+
+ Other compression options provide better control over creating
+compressed archives. These are:
+
+'--auto-compress'
+'-a'
+ Select a compression program to use by the archive file name
+ suffix. The following suffixes are recognized:
+
+ Suffix Compression program
+ -------------------------------------------------------------------
+ '.gz' 'gzip'
+ '.tgz' 'gzip'
+ '.taz' 'gzip'
+ '.Z' 'compress'
+ '.taZ' 'compress'
+ '.bz2' 'bzip2'
+ '.tz2' 'bzip2'
+ '.tbz2' 'bzip2'
+ '.tbz' 'bzip2'
+ '.lz' 'lzip'
+ '.lzma' 'lzma'
+ '.tlz' 'lzma'
+ '.lzo' 'lzop'
+ '.xz' 'xz'
+
+'--use-compress-program=COMMAND'
+'-I=COMMAND'
+ Use external compression program COMMAND. Use this option if you
+ want to specify options for the compression program, or if you are
+ not happy with the compression program associated with the suffix
+ at compile time, or if you have a compression program that GNU
+ 'tar' does not support. The COMMAND argument is a valid command
+ invocation, as you would type it at the command line prompt, with
+ any additional options as needed. Enclose it in quotes if it
+ contains white space (*note Running External Commands: external.).
+
+ The COMMAND should follow two conventions:
+
+ First, when invoked without additional options, it should read data
+ from standard input, compress it and output it on standard output.
+
+ Secondly, if invoked with the additional '-d' option, it should do
+ exactly the opposite, i.e., read the compressed data from the
+ standard input and produce uncompressed data on the standard
+ output.
+
+ The latter requirement means that you must not use the '-d' option
+ as a part of the COMMAND itself.
+
+ The '--use-compress-program' option, in particular, lets you
+implement your own filters, not necessarily dealing with
+compression/decompression. For example, suppose you wish to implement
+PGP encryption on top of compression, using 'gpg' (*note gpg:
+(gpg)Top.). The following script does that:
+
+ #! /bin/sh
+ case $1 in
+ -d) gpg --decrypt - | gzip -d -c;;
+ '') gzip -c | gpg -s;;
+ *) echo "Unknown option $1">&2; exit 1;;
+ esac
+
+ Suppose you name it 'gpgz' and save it somewhere in your 'PATH'.
+Then the following command will create a compressed archive signed with
+your private key:
+
+ $ tar -cf foo.tar.gpgz -Igpgz .
+
+Likewise, the command below will list its contents:
+
+ $ tar -tf foo.tar.gpgz -Igpgz .
+
+* Menu:
+
+* lbzip2:: Using lbzip2 with GNU 'tar'.
+
+ ---------- Footnotes ----------
+
+ (1) It also had patent problems in the past.
+
+ (2) To verbosely trace the decompressor selection, use the
+'--warning=decompress-program' option (*note decompress-program:
+warnings.).
+
+
+File: tar.info, Node: lbzip2, Up: gzip
+
+8.1.1.1 Using lbzip2 with GNU 'tar'.
+....................................
+
+'Lbzip2' is a multithreaded utility for handling 'bzip2' compression,
+written by Laszlo Ersek. It makes use of multiple processors to speed
+up its operation and in general works considerably faster than 'bzip2'.
+For a detailed description of 'lbzip2' see
+<http://freshmeat.net/projects/lbzip2> and lbzip2: parallel bzip2
+utility
+(http://www.linuxinsight.com/lbzip2-parallel-bzip2-utility.html).
+
+ Recent versions of 'lbzip2' are mostly command line compatible with
+'bzip2', which makes it possible to automatically invoke it via the
+'--bzip2' GNU 'tar' command line option. To do so, GNU 'tar' must be
+configured with the '--with-bzip2' command line option, like this:
+
+ $ ./configure --with-bzip2=lbzip2 [OTHER-OPTIONS]
+
+ Once configured and compiled this way, 'tar --help' will show the
+following:
+
+ $ tar --help | grep -- --bzip2
+ -j, --bzip2 filter the archive through lbzip2
+
+which means that running 'tar --bzip2' will invoke 'lbzip2'.
+
+
+File: tar.info, Node: sparse, Prev: gzip, Up: Compression
+
+8.1.2 Archiving Sparse Files
+----------------------------
+
+Files in the file system occasionally have "holes". A "hole" in a file
+is a section of the file's contents which was never written. The
+contents of a hole reads as all zeros. On many operating systems,
+actual disk storage is not allocated for holes, but they are counted in
+the length of the file. If you archive such a file, 'tar' could create
+an archive longer than the original. To have 'tar' attempt to recognize
+the holes in a file, use '--sparse' ('-S'). When you use this option,
+then, for any file using less disk space than would be expected from its
+length, 'tar' searches the file for holes. It then records in the
+archive for the file where the holes (consecutive stretches of zeros)
+are, and only archives the "real contents" of the file. On extraction
+(using '--sparse' is not needed on extraction) any such files have also
+holes created wherever the holes were found. Thus, if you use
+'--sparse', 'tar' archives won't take more space than the original.
+
+ GNU 'tar' uses two methods for detecting holes in sparse files.
+These methods are described later in this subsection.
+
+'-S'
+'--sparse'
+ This option instructs 'tar' to test each file for sparseness before
+ attempting to archive it. If the file is found to be sparse it is
+ treated specially, thus allowing to decrease the amount of space
+ used by its image in the archive.
+
+ This option is meaningful only when creating or updating archives.
+ It has no effect on extraction.
+
+ Consider using '--sparse' when performing file system backups, to
+avoid archiving the expanded forms of files stored sparsely in the
+system.
+
+ Even if your system has no sparse files currently, some may be
+created in the future. If you use '--sparse' while making file system
+backups as a matter of course, you can be assured the archive will never
+take more space on the media than the files take on disk (otherwise,
+archiving a disk filled with sparse files might take hundreds of tapes).
+*Note Incremental Dumps::.
+
+ However, be aware that '--sparse' option may present a serious
+drawback. Namely, in order to determine the positions of holes in a
+file 'tar' may have to read it before trying to archive it, so in total
+the file may be read *twice*. This may happen when your OS or your FS
+does not support "SEEK_HOLE/SEEK_DATA" feature in "lseek" (See
+'--hole-detection', below).
+
+ When using 'POSIX' archive format, GNU 'tar' is able to store sparse
+files using in three distinct ways, called "sparse formats". A sparse
+format is identified by its "number", consisting, as usual of two
+decimal numbers, delimited by a dot. By default, format '1.0' is used.
+If, for some reason, you wish to use an earlier format, you can select
+it using '--sparse-version' option.
+
+'--sparse-version=VERSION'
+ Select the format to store sparse files in. Valid VERSION values
+ are: '0.0', '0.1' and '1.0'. *Note Sparse Formats::, for a
+ detailed description of each format.
+
+ Using '--sparse-format' option implies '--sparse'.
+
+'--hole-detection=METHOD'
+ Enforce concrete hole detection method. Before the real contents
+ of sparse file are stored, 'tar' needs to gather knowledge about
+ file sparseness. This is because it needs to have the file's map
+ of holes stored into tar header before it starts archiving the file
+ contents. Currently, two methods of hole detection are
+ implemented:
+
+ * '--hole-detection=seek' Seeking the file for data and holes.
+ It uses enhancement of the 'lseek' system call ('SEEK_HOLE'
+ and 'SEEK_DATA') which is able to reuse file system knowledge
+ about sparse file contents - so the detection is usually very
+ fast. To use this feature, your file system and operating
+ system must support it. At the time of this writing (2015)
+ this feature, in spite of not being accepted by POSIX, is
+ fairly widely supported by different operating systems.
+
+ * '--hole-detection=raw' Reading byte-by-byte the whole sparse
+ file before the archiving. This method detects holes like
+ consecutive stretches of zeroes. Comparing to the previous
+ method, it is usually much slower, although more portable.
+
+ When no '--hole-detection' option is given, 'tar' uses the 'seek', if
+supported by the operating system.
+
+ Using '--hole-detection' option implies '--sparse'.
+
+
+File: tar.info, Node: Attributes, Next: Portability, Prev: Compression, Up: Formats
+
+8.2 Handling File Attributes
+============================
+
+When 'tar' reads files, it updates their access times. To avoid this,
+use the '--atime-preserve[=METHOD]' option, which can either reset the
+access time retroactively or avoid changing it in the first place.
+
+'--atime-preserve'
+'--atime-preserve=replace'
+'--atime-preserve=system'
+ Preserve the access times of files that are read. This works only
+ for files that you own, unless you have superuser privileges.
+
+ '--atime-preserve=replace' works on most systems, but it also
+ restores the data modification time and updates the status change
+ time. Hence it doesn't interact with incremental dumps nicely
+ (*note Incremental Dumps::), and it can set access or data
+ modification times incorrectly if other programs access the file
+ while 'tar' is running.
+
+ '--atime-preserve=system' avoids changing the access time in the
+ first place, if the operating system supports this. Unfortunately,
+ this may or may not work on any given operating system or file
+ system. If 'tar' knows for sure it won't work, it complains right
+ away.
+
+ Currently '--atime-preserve' with no operand defaults to
+ '--atime-preserve=replace', but this is intended to change to
+ '--atime-preserve=system' when the latter is better-supported.
+
+'-m'
+'--touch'
+ Do not extract data modification time.
+
+ When this option is used, 'tar' leaves the data modification times
+ of the files it extracts as the times when the files were
+ extracted, instead of setting it to the times recorded in the
+ archive.
+
+ This option is meaningless with '--list' ('-t').
+
+'--same-owner'
+ Create extracted files with the same ownership they have in the
+ archive.
+
+ This is the default behavior for the superuser, so this option is
+ meaningful only for non-root users, when 'tar' is executed on those
+ systems able to give files away. This is considered as a security
+ flaw by many people, at least because it makes quite difficult to
+ correctly account users for the disk space they occupy. Also, the
+ 'suid' or 'sgid' attributes of files are easily and silently lost
+ when files are given away.
+
+ When writing an archive, 'tar' writes the user ID and user name
+ separately. If it can't find a user name (because the user ID is
+ not in '/etc/passwd'), then it does not write one. When restoring,
+ it tries to look the name (if one was written) up in '/etc/passwd'.
+ If it fails, then it uses the user ID stored in the archive
+ instead.
+
+'--no-same-owner'
+'-o'
+ Do not attempt to restore ownership when extracting. This is the
+ default behavior for ordinary users, so this option has an effect
+ only for the superuser.
+
+'--numeric-owner'
+ The '--numeric-owner' option allows (ANSI) archives to be written
+ without user/group name information or such information to be
+ ignored when extracting. It effectively disables the generation
+ and/or use of user/group name information. This option forces
+ extraction using the numeric ids from the archive, ignoring the
+ names.
+
+ This is useful in certain circumstances, when restoring a backup
+ from an emergency floppy with different passwd/group files for
+ example. It is otherwise impossible to extract files with the
+ right ownerships if the password file in use during the extraction
+ does not match the one belonging to the file system(s) being
+ extracted. This occurs, for example, if you are restoring your
+ files after a major crash and had booted from an emergency floppy
+ with no password file or put your disk into another machine to do
+ the restore.
+
+ The numeric ids are _always_ saved into 'tar' archives. The
+ identifying names are added at create time when provided by the
+ system, unless '--format=oldgnu' is used. Numeric ids could be
+ used when moving archives between a collection of machines using a
+ centralized management for attribution of numeric ids to users and
+ groups. This is often made through using the NIS capabilities.
+
+ When making a 'tar' file for distribution to other sites, it is
+ sometimes cleaner to use a single owner for all files in the
+ distribution, and nicer to specify the write permission bits of the
+ files as stored in the archive independently of their actual value
+ on the file system. The way to prepare a clean distribution is
+ usually to have some Makefile rule creating a directory, copying
+ all needed files in that directory, then setting ownership and
+ permissions as wanted (there are a lot of possible schemes), and
+ only then making a 'tar' archive out of this directory, before
+ cleaning everything out. Of course, we could add a lot of options
+ to GNU 'tar' for fine tuning permissions and ownership. This is
+ not the good way, I think. GNU 'tar' is already crowded with
+ options and moreover, the approach just explained gives you a great
+ deal of control already.
+
+'-p'
+'--same-permissions'
+'--preserve-permissions'
+ Extract all protection information.
+
+ This option causes 'tar' to set the modes (access permissions) of
+ extracted files exactly as recorded in the archive. If this option
+ is not used, the current 'umask' setting limits the permissions on
+ extracted files. This option is by default enabled when 'tar' is
+ executed by a superuser.
+
+ This option is meaningless with '--list' ('-t').
+
+
+File: tar.info, Node: Portability, Next: cpio, Prev: Attributes, Up: Formats
+
+8.3 Making 'tar' Archives More Portable
+=======================================
+
+Creating a 'tar' archive on a particular system that is meant to be
+useful later on many other machines and with other versions of 'tar' is
+more challenging than you might think. 'tar' archive formats have been
+evolving since the first versions of Unix. Many such formats are
+around, and are not always compatible with each other. This section
+discusses a few problems, and gives some advice about making 'tar'
+archives more portable.
+
+ One golden rule is simplicity. For example, limit your 'tar'
+archives to contain only regular files and directories, avoiding other
+kind of special files. Do not attempt to save sparse files or
+contiguous files as such. Let's discuss a few more problems, in turn.
+
+* Menu:
+
+* Portable Names:: Portable Names
+* dereference:: Symbolic Links
+* hard links:: Hard Links
+* old:: Old V7 Archives
+* ustar:: Ustar Archives
+* gnu:: GNU and old GNU format archives.
+* posix:: POSIX archives
+* Checksumming:: Checksumming Problems
+* Large or Negative Values:: Large files, negative time stamps, etc.
+* Other Tars:: How to Extract GNU-Specific Data Using
+ Other 'tar' Implementations
+
+
+File: tar.info, Node: Portable Names, Next: dereference, Up: Portability
+
+8.3.1 Portable Names
+--------------------
+
+Use portable file and member names. A name is portable if it contains
+only ASCII letters and digits, '/', '.', '_', and '-'; it cannot be
+empty, start with '-' or '//', or contain '/-'. Avoid deep directory
+nesting. For portability to old Unix hosts, limit your file name
+components to 14 characters or less.
+
+ If you intend to have your 'tar' archives to be read under MSDOS, you
+should not rely on case distinction for file names, and you might use
+the GNU 'doschk' program for helping you further diagnosing illegal
+MSDOS names, which are even more limited than System V's.
+
+
+File: tar.info, Node: dereference, Next: hard links, Prev: Portable Names, Up: Portability
+
+8.3.2 Symbolic Links
+--------------------
+
+Normally, when 'tar' archives a symbolic link, it writes a block to the
+archive naming the target of the link. In that way, the 'tar' archive
+is a faithful record of the file system contents. When '--dereference'
+('-h') is used with '--create' ('-c'), 'tar' archives the files symbolic
+links point to, instead of the links themselves.
+
+ When creating portable archives, use '--dereference' ('-h'): some
+systems do not support symbolic links, and moreover, your distribution
+might be unusable if it contains unresolved symbolic links.
+
+ When reading from an archive, the '--dereference' ('-h') option
+causes 'tar' to follow an already-existing symbolic link when 'tar'
+writes or reads a file named in the archive. Ordinarily, 'tar' does not
+follow such a link, though it may remove the link before writing a new
+file. *Note Dealing with Old Files::.
+
+ The '--dereference' option is unsafe if an untrusted user can modify
+directories while 'tar' is running. *Note Security::.
+
+
+File: tar.info, Node: hard links, Next: old, Prev: dereference, Up: Portability
+
+8.3.3 Hard Links
+----------------
+
+Normally, when 'tar' archives a hard link, it writes a block to the
+archive naming the target of the link (a '1' type block). In that way,
+the actual file contents is stored in file only once. For example,
+consider the following two files:
+
+ $ ls -l
+ -rw-r--r-- 2 gray staff 4 2007-10-30 15:11 one
+ -rw-r--r-- 2 gray staff 4 2007-10-30 15:11 jeden
+
+ Here, 'jeden' is a link to 'one'. When archiving this directory with
+a verbose level 2, you will get an output similar to the following:
+
+ $ tar cvvf ../archive.tar .
+ drwxr-xr-x gray/staff 0 2007-10-30 15:13 ./
+ -rw-r--r-- gray/staff 4 2007-10-30 15:11 ./jeden
+ hrw-r--r-- gray/staff 0 2007-10-30 15:11 ./one link to ./jeden
+
+ The last line shows that, instead of storing two copies of the file,
+'tar' stored it only once, under the name 'jeden', and stored file 'one'
+as a hard link to this file.
+
+ It may be important to know that all hard links to the given file are
+stored in the archive. For example, this may be necessary for exact
+reproduction of the file system. The following option does that:
+
+'--check-links'
+'-l'
+ Check the number of links dumped for each processed file. If this
+ number does not match the total number of hard links for the file,
+ print a warning message.
+
+ For example, trying to archive only file 'jeden' with this option
+produces the following diagnostics:
+
+ $ tar -c -f ../archive.tar -l jeden
+ tar: Missing links to 'jeden'.
+
+ Although creating special records for hard links helps keep a
+faithful record of the file system contents and makes archives more
+compact, it may present some difficulties when extracting individual
+members from the archive. For example, trying to extract file 'one'
+from the archive created in previous examples produces, in the absence
+of file 'jeden':
+
+ $ tar xf archive.tar ./one
+ tar: ./one: Cannot hard link to './jeden': No such file or directory
+ tar: Error exit delayed from previous errors
+
+ The reason for this behavior is that 'tar' cannot seek back in the
+archive to the previous member (in this case, 'one'), to extract it(1).
+If you wish to avoid such problems at the cost of a bigger archive, use
+the following option:
+
+'--hard-dereference'
+ Dereference hard links and store the files they refer to.
+
+ For example, trying this option on our two sample files, we get two
+copies in the archive, each of which can then be extracted independently
+of the other:
+
+ $ tar -c -vv -f ../archive.tar --hard-dereference .
+ drwxr-xr-x gray/staff 0 2007-10-30 15:13 ./
+ -rw-r--r-- gray/staff 4 2007-10-30 15:11 ./jeden
+ -rw-r--r-- gray/staff 4 2007-10-30 15:11 ./one
+
+ ---------- Footnotes ----------
+
+ (1) There are plans to fix this in future releases.
+
+
+File: tar.info, Node: old, Next: ustar, Prev: hard links, Up: Portability
+
+8.3.4 Old V7 Archives
+---------------------
+
+Certain old versions of 'tar' cannot handle additional information
+recorded by newer 'tar' programs. To create an archive in V7 format
+(not ANSI), which can be read by these old versions, specify the
+'--format=v7' option in conjunction with the '--create' ('-c') ('tar'
+also accepts '--portability' or '--old-archive' for this option). When
+you specify it, 'tar' leaves out information about directories, pipes,
+fifos, contiguous files, and device files, and specifies file ownership
+by group and user IDs instead of group and user names.
+
+ When updating an archive, do not use '--format=v7' unless the archive
+was created using this option.
+
+ 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.
+On the other hand, most modern 'tar's are able to read old format
+archives, so it might be safer for you to always use '--format=v7' for
+your distributions. Notice, however, that 'ustar' format is a better
+alternative, as it is free from many of 'v7''s drawbacks.
+
+
+File: tar.info, Node: ustar, Next: gnu, Prev: old, Up: Portability
+
+8.3.5 Ustar Archive Format
+--------------------------
+
+The archive format defined by the POSIX.1-1988 specification is called
+'ustar'. Although it is more flexible than the V7 format, it still has
+many restrictions (*note ustar: Formats, for the detailed description of
+'ustar' format). Along with V7 format, 'ustar' format is a good choice
+for archives intended to be read with other implementations of 'tar'.
+
+ To create an archive in 'ustar' format, use the '--format=ustar'
+option in conjunction with '--create' ('-c').
+
+
+File: tar.info, Node: gnu, Next: posix, Prev: ustar, Up: Portability
+
+8.3.6 GNU and old GNU 'tar' format
+----------------------------------
+
+GNU 'tar' was based on an early draft of the POSIX 1003.1 'ustar'
+standard. GNU extensions to 'tar', such as the support for file names
+longer than 100 characters, use portions of the 'tar' header record
+which were specified in that POSIX draft as unused. Subsequent changes
+in POSIX have allocated the same parts of the header record for other
+purposes. As a result, GNU 'tar' format is incompatible with the
+current POSIX specification, and with 'tar' programs that follow it.
+
+ In the majority of cases, 'tar' will be configured to create this
+format by default. This will change in future releases, since we plan
+to make 'POSIX' format the default.
+
+ To force creation a GNU 'tar' archive, use option '--format=gnu'.
+
+
+File: tar.info, Node: posix, Next: Checksumming, Prev: gnu, Up: Portability
+
+8.3.7 GNU 'tar' and POSIX 'tar'
+-------------------------------
+
+Starting from version 1.14 GNU 'tar' features full support for
+POSIX.1-2001 archives.
+
+ A POSIX conformant archive will be created if 'tar' was given
+'--format=posix' ('--format=pax') option. No special option is required
+to read and extract from a POSIX archive.
+
+* Menu:
+
+* PAX keywords:: Controlling Extended Header Keywords.
+
+
+File: tar.info, Node: PAX keywords, Up: posix
+
+8.3.7.1 Controlling Extended Header Keywords
+............................................
+
+'--pax-option=KEYWORD-LIST'
+ Handle keywords in PAX extended headers. This option is equivalent
+ to '-o' option of the 'pax' utility.
+
+ KEYWORD-LIST is a comma-separated list of keyword options, each
+keyword option taking one of the following forms:
+
+'delete=PATTERN'
+ When used with one of archive-creation commands, this option
+ instructs 'tar' to omit from extended header records that it
+ produces any keywords matching the string PATTERN.
+
+ When used in extract or list mode, this option instructs tar to
+ ignore any keywords matching the given PATTERN in the extended
+ header records. In both cases, matching is performed using the
+ pattern matching notation described in POSIX 1003.2, 3.13 (*note
+ wildcards::). For example:
+
+ --pax-option delete=security.*
+
+ would suppress security-related information.
+
+'exthdr.name=STRING'
+
+ This keyword allows user control over the name that is written into
+ the ustar header blocks for the extended headers. The name is
+ obtained from STRING after making the following substitutions:
+
+ Meta-character Replaced By
+ ------------------------------------------------------------
+ %d The directory name of the file,
+ equivalent to the result of the
+ 'dirname' utility on the translated
+ file name.
+ %f The name of the file with the
+ directory information stripped,
+ equivalent to the result of the
+ 'basename' utility on the translated
+ file name.
+ %p The process ID of the 'tar' process.
+ %% A '%' character.
+
+ Any other '%' characters in STRING produce undefined results.
+
+ If no option 'exthdr.name=string' is specified, 'tar' will use the
+ following default value:
+
+ %d/PaxHeaders.%p/%f
+
+'exthdr.mtime=VALUE'
+
+ This keyword defines the value of the 'mtime' field that is written
+ into the ustar header blocks for the extended headers. By default,
+ the 'mtime' field is set to the modification time of the archive
+ member described by that extended header (or to the value of the
+ '--mtime' option, if supplied).
+
+'globexthdr.name=STRING'
+ This keyword allows user control over the name that is written into
+ the ustar header blocks for global extended header records. The
+ name is obtained from the contents of STRING, after making the
+ following substitutions:
+
+ Meta-character Replaced By
+ ------------------------------------------------------------
+ %n An integer that represents the
+ sequence number of the global extended
+ header record in the archive, starting
+ at 1.
+ %p The process ID of the 'tar' process.
+ %% A '%' character.
+
+ Any other '%' characters in STRING produce undefined results.
+
+ If no option 'globexthdr.name=string' is specified, 'tar' will use
+ the following default value:
+
+ $TMPDIR/GlobalHead.%p.%n
+
+ where '$TMPDIR' represents the value of the TMPDIR environment
+ variable. If TMPDIR is not set, 'tar' uses '/tmp'.
+
+'globexthdr.mtime=VALUE'
+
+ This keyword defines the value of the 'mtime' field that is written
+ into the ustar header blocks for the global extended headers. By
+ default, the 'mtime' field is set to the time when 'tar' was
+ invoked.
+
+'KEYWORD=VALUE'
+ When used with one of archive-creation commands, these
+ keyword/value pairs will be included at the beginning of the
+ archive in a global extended header record. When used with one of
+ archive-reading commands, 'tar' will behave as if it has
+ encountered these keyword/value pairs at the beginning of the
+ archive in a global extended header record.
+
+'KEYWORD:=VALUE'
+ When used with one of archive-creation commands, these
+ keyword/value pairs will be included as records at the beginning of
+ an extended header for each file. This is effectively equivalent
+ to KEYWORD=VALUE form except that it creates no global extended
+ header records.
+
+ When used with one of archive-reading commands, 'tar' will behave
+ as if these keyword/value pairs were included as records at the end
+ of each extended header; thus, they will override any global or
+ file-specific extended header record keywords of the same names.
+ For example, in the command:
+
+ tar --format=posix --create \
+ --file archive --pax-option gname:=user .
+
+ the group name will be forced to a new value for all files stored
+ in the archive.
+
+ In any of the forms described above, the VALUE may be a string
+enclosed in curly braces. In that case, the string between the braces
+is understood either as a textual time representation, as described in
+*note Date input formats::, or a name of the existing file, starting
+with '/' or '.'. In the latter case, the modification time of that file
+is used.
+
+ For example, to set all modification times to the current date, you
+use the following option:
+
+ --pax-option='mtime:={now}'
+
+ Note quoting of the option's argument.
+
+ As another example, here is the option that ensures that any two
+archives created using it, will be binary equivalent if they have the
+same contents:
+
+ --pax-option=exthdr.name=%d/PaxHeaders/%f,atime:=0
+
+If you extract files from such an archive and recreate the archive from
+them, you will also need to eliminate changes due to ctime, as shown in
+examples below:
+
+ --pax-option=exthdr.name=%d/PaxHeaders/%f,atime:=0,ctime:=0
+
+or
+
+ --pax-option=exthdr.name=%d/PaxHeaders/%f,atime:=0,delete=ctime
+
+
+File: tar.info, Node: Checksumming, Next: Large or Negative Values, Prev: posix, Up: Portability
+
+8.3.8 Checksumming Problems
+---------------------------
+
+SunOS and HP-UX 'tar' fail to accept archives created using GNU 'tar'
+and containing non-ASCII file names, that is, file names having
+characters with the eighth bit set, because they use signed checksums,
+while GNU 'tar' uses unsigned checksums while creating archives, as per
+POSIX standards. On reading, GNU 'tar' computes both checksums and
+accepts either of them. It is somewhat worrying that a lot of people
+may go around doing backup of their files using faulty (or at least
+non-standard) software, not learning about it until it's time to restore
+their missing files with an incompatible file extractor, or vice versa.
+
+ GNU 'tar' computes checksums both ways, and accepts either of them on
+read, so GNU tar can read Sun tapes even with their wrong checksums.
+GNU 'tar' produces the standard checksum, however, raising
+incompatibilities with Sun. That is to say, GNU 'tar' has not been
+modified to _produce_ incorrect archives to be read by buggy 'tar''s.
+I've been told that more recent Sun 'tar' now read standard archives, so
+maybe Sun did a similar patch, after all?
+
+ The story seems to be that when Sun first imported 'tar' sources on
+their system, they recompiled it without realizing that the checksums
+were computed differently, because of a change in the default signing of
+'char''s in their compiler. So they started computing checksums
+wrongly. When they later realized their mistake, they merely decided to
+stay compatible with it, and with themselves afterwards. Presumably,
+but I do not really know, HP-UX has chosen their 'tar' archives to be
+compatible with Sun's. The current standards do not favor Sun 'tar'
+format. In any case, it now falls on the shoulders of SunOS and HP-UX
+users to get a 'tar' able to read the good archives they receive.
+
+
+File: tar.info, Node: Large or Negative Values, Next: Other Tars, Prev: Checksumming, Up: Portability
+
+8.3.9 Large or Negative Values
+------------------------------
+
+ _(This message will disappear, once this node revised.)_
+
+ The above sections suggest to use 'oldest possible' archive format if
+in doubt. However, sometimes it is not possible. If you attempt to
+archive a file whose metadata cannot be represented using required
+format, GNU 'tar' will print error message and ignore such a file. You
+will than have to switch to a format that is able to handle such values.
+The format summary table (*note Formats::) will help you to do so.
+
+ In particular, when trying to archive files larger than 8GB or with
+timestamps not in the range 1970-01-01 00:00:00 through 2242-03-16
+12:56:31 UTC, you will have to chose between GNU and POSIX archive
+formats. When considering which format to choose, bear in mind that the
+GNU format uses two's-complement base-256 notation to store values that
+do not fit into standard ustar range. Such archives can generally be
+read only by a GNU 'tar' implementation. Moreover, they sometimes
+cannot be correctly restored on another hosts even by GNU 'tar'. For
+example, using two's complement representation for negative time stamps
+that assumes a signed 32-bit 'time_t' generates archives that are not
+portable to hosts with differing 'time_t' representations.
+
+ On the other hand, POSIX archives, generally speaking, can be
+extracted by any tar implementation that understands older ustar format.
+The only exception are files larger than 8GB.
+
+
+File: tar.info, Node: Other Tars, Prev: Large or Negative Values, Up: Portability
+
+8.3.10 How to Extract GNU-Specific Data Using Other 'tar' Implementations
+-------------------------------------------------------------------------
+
+In previous sections you became acquainted with various quirks necessary
+to make your archives portable. Sometimes you may need to extract
+archives containing GNU-specific members using some third-party 'tar'
+implementation or an older version of GNU 'tar'. Of course your best
+bet is to have GNU 'tar' installed, but if it is for some reason
+impossible, this section will explain how to cope without it.
+
+ When we speak about "GNU-specific" members we mean two classes of
+them: members split between the volumes of a multi-volume archive and
+sparse members. You will be able to always recover such members if the
+archive is in PAX format. In addition split members can be recovered
+from archives in old GNU format. The following subsections describe the
+required procedures in detail.
+
+* Menu:
+
+* Split Recovery:: Members Split Between Volumes
+* Sparse Recovery:: Sparse Members
+
+
+File: tar.info, Node: Split Recovery, Next: Sparse Recovery, Up: Other Tars
+
+8.3.10.1 Extracting Members Split Between Volumes
+.................................................
+
+If a member is split between several volumes of an old GNU format
+archive most third party 'tar' implementation will fail to extract it.
+To extract it, use 'tarcat' program (*note Tarcat::). This program is
+available from GNU 'tar' home page
+(http://www.gnu.org/software/tar/utils/tarcat.html). It concatenates
+several archive volumes into a single valid archive. For example, if
+you have three volumes named from 'vol-1.tar' to 'vol-3.tar', you can do
+the following to extract them using a third-party 'tar':
+
+ $ tarcat vol-1.tar vol-2.tar vol-3.tar | tar xf -
+
+ You could use this approach for most (although not all) PAX format
+archives as well. However, extracting split members from a PAX archive
+is a much easier task, because PAX volumes are constructed in such a way
+that each part of a split member is extracted to a different file by
+'tar' implementations that are not aware of GNU extensions. More
+specifically, the very first part retains its original name, and all
+subsequent parts are named using the pattern:
+
+ %d/GNUFileParts.%p/%f.%n
+
+where symbols preceded by '%' are "macro characters" that have the
+following meaning:
+
+Meta-character Replaced By
+------------------------------------------------------------
+%d The directory name of the file,
+ equivalent to the result of the
+ 'dirname' utility on its full name.
+%f The file name of the file, equivalent
+ to the result of the 'basename'
+ utility on its full name.
+%p The process ID of the 'tar' process
+ that created the archive.
+%n Ordinal number of this particular
+ part.
+
+ For example, if the file 'var/longfile' was split during archive
+creation between three volumes, and the creator 'tar' process had
+process ID '27962', then the member names will be:
+
+ var/longfile
+ var/GNUFileParts.27962/longfile.1
+ var/GNUFileParts.27962/longfile.2
+
+ When you extract your archive using a third-party 'tar', these files
+will be created on your disk, and the only thing you will need to do to
+restore your file in its original form is concatenate them in the proper
+order, for example:
+
+ $ cd var
+ $ cat GNUFileParts.27962/longfile.1 \
+ GNUFileParts.27962/longfile.2 >> longfile
+ $ rm -f GNUFileParts.27962
+
+ Notice, that if the 'tar' implementation you use supports PAX format
+archives, it will probably emit warnings about unknown keywords during
+extraction. They will look like this:
+
+ Tar file too small
+ Unknown extended header keyword 'GNU.volume.filename' ignored.
+ Unknown extended header keyword 'GNU.volume.size' ignored.
+ Unknown extended header keyword 'GNU.volume.offset' ignored.
+
+You can safely ignore these warnings.
+
+ If your 'tar' implementation is not PAX-aware, you will get more
+warnings and more files generated on your disk, e.g.:
+
+ $ tar xf vol-1.tar
+ var/PaxHeaders.27962/longfile: Unknown file type 'x', extracted as
+ normal file
+ Unexpected EOF in archive
+ $ tar xf vol-2.tar
+ tmp/GlobalHead.27962.1: Unknown file type 'g', extracted as normal file
+ GNUFileParts.27962/PaxHeaders.27962/sparsefile.1: Unknown file type
+ 'x', extracted as normal file
+
+ Ignore these warnings. The 'PaxHeaders.*' directories created will
+contain files with "extended header keywords" describing the extracted
+files. You can delete them, unless they describe sparse members. Read
+further to learn more about them.
+
+
+File: tar.info, Node: Sparse Recovery, Prev: Split Recovery, Up: Other Tars
+
+8.3.10.2 Extracting Sparse Members
+..................................
+
+Any 'tar' implementation will be able to extract sparse members from a
+PAX archive. However, the extracted files will be "condensed", i.e.,
+any zero blocks will be removed from them. When we restore such a
+condensed file to its original form, by adding zero blocks (or "holes")
+back to their original locations, we call this process "expanding" a
+compressed sparse file.
+
+ To expand a file, you will need a simple auxiliary program called
+'xsparse'. It is available in source form from GNU 'tar' home page
+(http://www.gnu.org/software/tar/utils/xsparse.html).
+
+ Let's begin with archive members in "sparse format version 1.0"(1),
+which are the easiest to expand. The condensed file will contain both
+file map and file data, so no additional data will be needed to restore
+it. If the original file name was 'DIR/NAME', then the condensed file
+will be named 'DIR/GNUSparseFile.N/NAME', where N is a decimal
+number(2).
+
+ To expand a version 1.0 file, run 'xsparse' as follows:
+
+ $ xsparse cond-file
+
+where 'cond-file' is the name of the condensed file. The utility will
+deduce the name for the resulting expanded file using the following
+algorithm:
+
+ 1. If 'cond-file' does not contain any directories, '../cond-file'
+ will be used;
+
+ 2. If 'cond-file' has the form 'DIR/T/NAME', where both T and NAME are
+ simple names, with no '/' characters in them, the output file name
+ will be 'DIR/NAME'.
+
+ 3. Otherwise, if 'cond-file' has the form 'DIR/NAME', the output file
+ name will be 'NAME'.
+
+ In the unlikely case when this algorithm does not suit your needs,
+you can explicitly specify output file name as a second argument to the
+command:
+
+ $ xsparse cond-file out-file
+
+ It is often a good idea to run 'xsparse' in "dry run" mode first. In
+this mode, the command does not actually expand the file, but verbosely
+lists all actions it would be taking to do so. The dry run mode is
+enabled by '-n' command line argument:
+
+ $ xsparse -n /home/gray/GNUSparseFile.6058/sparsefile
+ Reading v.1.0 sparse map
+ Expanding file '/home/gray/GNUSparseFile.6058/sparsefile' to
+ '/home/gray/sparsefile'
+ Finished dry run
+
+ To actually expand the file, you would run:
+
+ $ xsparse /home/gray/GNUSparseFile.6058/sparsefile
+
+The program behaves the same way all UNIX utilities do: it will keep
+quiet unless it has something important to tell you (e.g. an error
+condition or something). If you wish it to produce verbose output,
+similar to that from the dry run mode, use '-v' option:
+
+ $ xsparse -v /home/gray/GNUSparseFile.6058/sparsefile
+ Reading v.1.0 sparse map
+ Expanding file '/home/gray/GNUSparseFile.6058/sparsefile' to
+ '/home/gray/sparsefile'
+ Done
+
+ Additionally, if your 'tar' implementation has extracted the
+"extended headers" for this file, you can instruct 'xstar' to use them
+in order to verify the integrity of the expanded file. The option '-x'
+sets the name of the extended header file to use. Continuing our
+example:
+
+ $ xsparse -v -x /home/gray/PaxHeaders.6058/sparsefile \
+ /home/gray/GNUSparseFile.6058/sparsefile
+ Reading extended header file
+ Found variable GNU.sparse.major = 1
+ Found variable GNU.sparse.minor = 0
+ Found variable GNU.sparse.name = sparsefile
+ Found variable GNU.sparse.realsize = 217481216
+ Reading v.1.0 sparse map
+ Expanding file '/home/gray/GNUSparseFile.6058/sparsefile' to
+ '/home/gray/sparsefile'
+ Done
+
+ An "extended header" is a special 'tar' archive header that precedes
+an archive member and contains a set of "variables", describing the
+member properties that cannot be stored in the standard 'ustar' header.
+While optional for expanding sparse version 1.0 members, the use of
+extended headers is mandatory when expanding sparse members in older
+sparse formats: v.0.0 and v.0.1 (The sparse formats are described in
+detail in *note Sparse Formats::.) So, for these formats, the question
+is: how to obtain extended headers from the archive?
+
+ If you use a 'tar' implementation that does not support PAX format,
+extended headers for each member will be extracted as a separate file.
+If we represent the member name as 'DIR/NAME', then the extended header
+file will be named 'DIR/PaxHeaders.N/NAME', where N is an integer
+number.
+
+ Things become more difficult if your 'tar' implementation does
+support PAX headers, because in this case you will have to manually
+extract the headers. We recommend the following algorithm:
+
+ 1. Consult the documentation of your 'tar' implementation for an
+ option that prints "block numbers" along with the archive listing
+ (analogous to GNU 'tar''s '-R' option). For example, 'star' has
+ '-block-number'.
+
+ 2. Obtain verbose listing using the 'block number' option, and find
+ block numbers of the sparse member in question and the member
+ immediately following it. For example, running 'star' on our
+ archive we obtain:
+
+ $ star -t -v -block-number -f arc.tar
+ ...
+ star: Unknown extended header keyword 'GNU.sparse.size' ignored.
+ star: Unknown extended header keyword 'GNU.sparse.numblocks' ignored.
+ star: Unknown extended header keyword 'GNU.sparse.name' ignored.
+ star: Unknown extended header keyword 'GNU.sparse.map' ignored.
+ block 56: 425984 -rw-r--r-- gray/users Jun 25 14:46 2006 GNUSparseFile.28124/sparsefile
+ block 897: 65391 -rw-r--r-- gray/users Jun 24 20:06 2006 README
+ ...
+
+ (as usual, ignore the warnings about unknown keywords.)
+
+ 3. Let SIZE be the size of the sparse member, BS be its block number
+ and BN be the block number of the next member. Compute:
+
+ N = BS - BN - SIZE/512 - 2
+
+ This number gives the size of the extended header part in tar
+ "blocks". In our example, this formula gives: '897 - 56 - 425984 /
+ 512 - 2 = 7'.
+
+ 4. Use 'dd' to extract the headers:
+
+ dd if=ARCHIVE of=HNAME bs=512 skip=BS count=N
+
+ where ARCHIVE is the archive name, HNAME is a name of the file to
+ store the extended header in, BS and N are computed in previous
+ steps.
+
+ In our example, this command will be
+
+ $ dd if=arc.tar of=xhdr bs=512 skip=56 count=7
+
+ Finally, you can expand the condensed file, using the obtained
+header:
+
+ $ xsparse -v -x xhdr GNUSparseFile.6058/sparsefile
+ Reading extended header file
+ Found variable GNU.sparse.size = 217481216
+ Found variable GNU.sparse.numblocks = 208
+ Found variable GNU.sparse.name = sparsefile
+ Found variable GNU.sparse.map = 0,2048,1050624,2048,...
+ Expanding file 'GNUSparseFile.28124/sparsefile' to 'sparsefile'
+ Done
+
+ ---------- Footnotes ----------
+
+ (1) *Note PAX 1::.
+
+ (2) Technically speaking, N is a "process ID" of the 'tar' process
+which created the archive (*note PAX keywords::).
+
+
+File: tar.info, Node: cpio, Prev: Portability, Up: Formats
+
+8.4 Comparison of 'tar' and 'cpio'
+==================================
+
+ _(This message will disappear, once this node revised.)_
+
+ The 'cpio' archive formats, like 'tar', do have maximum file name
+lengths. The binary and old ASCII formats have a maximum file length of
+256, and the new ASCII and CRC ASCII formats have a max file length of
+1024. GNU 'cpio' can read and write archives with arbitrary file name
+lengths, but other 'cpio' implementations may crash unexplainedly trying
+to read them.
+
+ 'tar' handles symbolic links in the form in which it comes in BSD;
+'cpio' doesn't handle symbolic links in the form in which it comes in
+System V prior to SVR4, and some vendors may have added symlinks to
+their system without enhancing 'cpio' to know about them. Others may
+have enhanced it in a way other than the way I did it at Sun, and which
+was adopted by AT&T (and which is, I think, also present in the 'cpio'
+that Berkeley picked up from AT&T and put into a later BSD release--I
+think I gave them my changes).
+
+ (SVR4 does some funny stuff with 'tar'; basically, its 'cpio' can
+handle 'tar' format input, and write it on output, and it probably
+handles symbolic links. They may not have bothered doing anything to
+enhance 'tar' as a result.)
+
+ 'cpio' handles special files; traditional 'tar' doesn't.
+
+ 'tar' comes with V7, System III, System V, and BSD source; 'cpio'
+comes only with System III, System V, and later BSD (4.3-tahoe and
+later).
+
+ 'tar''s way of handling multiple hard links to a file can handle file
+systems that support 32-bit i-numbers (e.g., the BSD file system);
+'cpio's way requires you to play some games (in its "binary" format,
+i-numbers are only 16 bits, and in its "portable ASCII" format, they're
+18 bits--it would have to play games with the "file system ID" field of
+the header to make sure that the file system ID/i-number pairs of
+different files were always different), and I don't know which 'cpio's,
+if any, play those games. Those that don't might get confused and think
+two files are the same file when they're not, and make hard links
+between them.
+
+ 'tar's way of handling multiple hard links to a file places only one
+copy of the link on the tape, but the name attached to that copy is the
+_only_ one you can use to retrieve the file; 'cpio's way puts one copy
+for every link, but you can retrieve it using any of the names.
+
+ What type of check sum (if any) is used, and how is this
+ calculated.
+
+ See the attached manual pages for 'tar' and 'cpio' format. 'tar'
+uses a checksum which is the sum of all the bytes in the 'tar' header
+for a file; 'cpio' uses no checksum.
+
+ If anyone knows why 'cpio' was made when 'tar' was present at the
+ unix scene,
+
+ It wasn't. 'cpio' first showed up in PWB/UNIX 1.0; no
+generally-available version of UNIX had 'tar' at the time. I don't know
+whether any version that was generally available _within AT&T_ had
+'tar', or, if so, whether the people within AT&T who did 'cpio' knew
+about it.
+
+ On restore, if there is a corruption on a tape 'tar' will stop at
+that point, while 'cpio' will skip over it and try to restore the rest
+of the files.
+
+ The main difference is just in the command syntax and header format.
+
+ 'tar' is a little more tape-oriented in that everything is blocked to
+start on a record boundary.
+
+ Is there any differences between the ability to recover crashed
+ archives between the two of them. (Is there any chance of
+ recovering crashed archives at all.)
+
+ Theoretically it should be easier under 'tar' since the blocking lets
+you find a header with some variation of 'dd skip=NN'. However, modern
+'cpio''s and variations have an option to just search for the next file
+header after an error with a reasonable chance of resyncing. However,
+lots of tape driver software won't allow you to continue past a media
+error which should be the only reason for getting out of sync unless a
+file changed sizes while you were writing the archive.
+
+ If anyone knows why 'cpio' was made when 'tar' was present at the
+ unix scene, please tell me about this too.
+
+ Probably because it is more media efficient (by not blocking
+everything and using only the space needed for the headers where 'tar'
+always uses 512 bytes per file header) and it knows how to archive
+special files.
+
+ You might want to look at the freely available alternatives. The
+major ones are 'afio', GNU 'tar', and 'pax', each of which have their
+own extensions with some backwards compatibility.
+
+ Sparse files were 'tar'red as sparse files (which you can easily
+test, because the resulting archive gets smaller, and GNU 'cpio' can no
+longer read it).
+
+
+File: tar.info, Node: Media, Next: Reliability and security, Prev: Formats, Up: Top
+
+9 Tapes and Other Archive Media
+*******************************
+
+ _(This message will disappear, once this node revised.)_
+
+ A few special cases about tape handling warrant more detailed
+description. These special cases are discussed below.
+
+ Many complexities surround the use of 'tar' on tape drives. Since
+the creation and manipulation of archives located on magnetic tape was
+the original purpose of 'tar', it contains many features making such
+manipulation easier.
+
+ Archives are usually written on dismountable media--tape cartridges,
+mag tapes, or floppy disks.
+
+ The amount of data a tape or disk holds depends not only on its size,
+but also on how it is formatted. A 2400 foot long reel of mag tape
+holds 40 megabytes of data when formatted at 1600 bits per inch. The
+physically smaller EXABYTE tape cartridge holds 2.3 gigabytes.
+
+ Magnetic media are re-usable--once the archive on a tape is no longer
+needed, the archive can be erased and the tape or disk used over. Media
+quality does deteriorate with use, however. Most tapes or disks should
+be discarded when they begin to produce data errors. EXABYTE tape
+cartridges should be discarded when they generate an "error count"
+(number of non-usable bits) of more than 10k.
+
+ Magnetic media are written and erased using magnetic fields, and
+should be protected from such fields to avoid damage to stored data.
+Sticking a floppy disk to a filing cabinet using a magnet is probably
+not a good idea.
+
+* Menu:
+
+* Device:: Device selection and switching
+* Remote Tape Server::
+* Common Problems and Solutions::
+* Blocking:: Blocking
+* Many:: Many archives on one tape
+* Using Multiple Tapes:: Using Multiple Tapes
+* label:: Including a Label in the Archive
+* verify::
+* Write Protection::
+
+
+File: tar.info, Node: Device, Next: Remote Tape Server, Up: Media
+
+9.1 Device Selection and Switching
+==================================
+
+ _(This message will disappear, once this node revised.)_
+
+'-f [HOSTNAME:]FILE'
+'--file=[HOSTNAME:]FILE'
+ Use archive file or device FILE on HOSTNAME.
+
+ This option is used to specify the file name of the archive 'tar'
+works on.
+
+ If the file name is '-', 'tar' reads the archive from standard input
+(when listing or extracting), or writes it to standard output (when
+creating). If the '-' file name is given when updating an archive,
+'tar' will read the original archive from its standard input, and will
+write the entire new archive to its standard output.
+
+ If the file name contains a ':', it is interpreted as 'hostname:file
+name'. If the HOSTNAME contains an "at" sign ('@'), it is treated as
+'user@hostname:file name'. In either case, 'tar' will invoke the
+command 'rsh' (or 'remsh') to start up an '/usr/libexec/rmt' on the
+remote machine. If you give an alternate login name, it will be given
+to the 'rsh'. Naturally, the remote machine must have an executable
+'/usr/libexec/rmt'. This program is free software from the University
+of California, and a copy of the source code can be found with the
+sources for 'tar'; it's compiled and installed by default. The exact
+path to this utility is determined when configuring the package. It is
+'PREFIX/libexec/rmt', where PREFIX stands for your installation prefix.
+This location may also be overridden at runtime by using the
+'--rmt-command=COMMAND' option (*Note --rmt-command: Option Summary, for
+detailed description of this option. *Note Remote Tape Server::, for
+the description of 'rmt' command).
+
+ If this option is not given, but the environment variable 'TAPE' is
+set, its value is used; otherwise, old versions of 'tar' used a default
+archive name (which was picked when 'tar' was compiled). The default is
+normally set up to be the "first" tape drive or other transportable I/O
+medium on the system.
+
+ Starting with version 1.11.5, GNU 'tar' uses standard input and
+standard output as the default device, and I will not try anymore
+supporting automatic device detection at installation time. This was
+failing really in too many cases, it was hopeless. This is now
+completely left to the installer to override standard input and standard
+output for default device, if this seems preferable. Further, I think
+_most_ actual usages of 'tar' are done with pipes or disks, not really
+tapes, cartridges or diskettes.
+
+ Some users think that using standard input and output is running
+after trouble. This could lead to a nasty surprise on your screen if
+you forget to specify an output file name--especially if you are going
+through a network or terminal server capable of buffering large amounts
+of output. We had so many bug reports in that area of configuring
+default tapes automatically, and so many contradicting requests, that we
+finally consider the problem to be portably intractable. We could of
+course use something like '/dev/tape' as a default, but this is _also_
+running after various kind of trouble, going from hung processes to
+accidental destruction of real tapes. After having seen all this mess,
+using standard input and output as a default really sounds like the only
+clean choice left, and a very useful one too.
+
+ GNU 'tar' reads and writes archive in records, I suspect this is the
+main reason why block devices are preferred over character devices.
+Most probably, block devices are more efficient too. The installer
+could also check for 'DEFTAPE' in '<sys/mtio.h>'.
+
+'--force-local'
+ Archive file is local even if it contains a colon.
+
+'--rsh-command=COMMAND'
+ Use remote COMMAND instead of 'rsh'. This option exists so that
+ people who use something other than the standard 'rsh' (e.g., a
+ Kerberized 'rsh') can access a remote device.
+
+ When this command is not used, the shell command found when the
+ 'tar' program was installed is used instead. This is the first
+ found of '/usr/ucb/rsh', '/usr/bin/remsh', '/usr/bin/rsh',
+ '/usr/bsd/rsh' or '/usr/bin/nsh'. The installer may have
+ overridden this by defining the environment variable 'RSH' _at
+ installation time_.
+
+'-[0-7][lmh]'
+ Specify drive and density.
+
+'-M'
+'--multi-volume'
+ Create/list/extract multi-volume archive.
+
+ This option causes 'tar' to write a "multi-volume" archive--one
+ that may be larger than will fit on the medium used to hold it.
+ *Note Multi-Volume Archives::.
+
+'-L NUM'
+'--tape-length=SIZE[SUF]'
+ Change tape after writing SIZE units of data. Unless SUF is given,
+ SIZE is treated as kilobytes, i.e. 'SIZE x 1024' bytes. The
+ following suffixes alter this behavior:
+
+ Suffix Units Byte Equivalent
+ -------------------------------------------------------------
+ b Blocks SIZE x 512
+ B Kilobytes SIZE x 1024
+ c Bytes SIZE
+ G Gigabytes SIZE x 1024^3
+ K Kilobytes SIZE x 1024
+ k Kilobytes SIZE x 1024
+ M Megabytes SIZE x 1024^2
+ P Petabytes SIZE x 1024^5
+ T Terabytes SIZE x 1024^4
+ w Words SIZE x 2
+
+ Table 9.1: Size Suffixes
+
+ This option might be useful when your tape drivers do not properly
+ detect end of physical tapes. By being slightly conservative on
+ the maximum tape length, you might avoid the problem entirely.
+
+'-F COMMAND'
+'--info-script=COMMAND'
+'--new-volume-script=COMMAND'
+ Execute COMMAND at end of each tape. This implies '--multi-volume'
+ ('-M'). *Note info-script::, for a detailed description of this
+ option.
+
+
+File: tar.info, Node: Remote Tape Server, Next: Common Problems and Solutions, Prev: Device, Up: Media
+
+9.2 Remote Tape Server
+======================
+
+In order to access the tape drive on a remote machine, 'tar' uses the
+remote tape server written at the University of California at Berkeley.
+The remote tape server must be installed as 'PREFIX/libexec/rmt' on any
+machine whose tape drive you want to use. 'tar' calls 'rmt' by running
+an 'rsh' or 'remsh' to the remote machine, optionally using a different
+login name if one is supplied.
+
+ A copy of the source for the remote tape server is provided. Its
+source code can be freely distributed. It is compiled and installed by
+default.
+
+ Unless you use the '--absolute-names' ('-P') option, GNU 'tar' will
+not allow you to create an archive that contains absolute file names (a
+file name beginning with '/'). If you try, 'tar' will automatically
+remove the leading '/' from the file names it stores in the archive. It
+will also type a warning message telling you what it is doing.
+
+ When reading an archive that was created with a different 'tar'
+program, GNU 'tar' automatically extracts entries in the archive which
+have absolute file names as if the file names were not absolute. This
+is an important feature. A visitor here once gave a 'tar' tape to an
+operator to restore; the operator used Sun 'tar' instead of GNU 'tar',
+and the result was that it replaced large portions of our '/bin' and
+friends with versions from the tape; needless to say, we were unhappy
+about having to recover the file system from backup tapes.
+
+ For example, if the archive contained a file '/usr/bin/computoy', GNU
+'tar' would extract the file to 'usr/bin/computoy', relative to the
+current directory. If you want to extract the files in an archive to
+the same absolute names that they had when the archive was created, you
+should do a 'cd /' before extracting the files from the archive, or you
+should either use the '--absolute-names' option, or use the command 'tar
+-C / ...'.
+
+ Some versions of Unix (Ultrix 3.1 is known to have this problem), can
+claim that a short write near the end of a tape succeeded, when it
+actually failed. This will result in the -M option not working
+correctly. The best workaround at the moment is to use a significantly
+larger blocking factor than the default 20.
+
+ In order to update an archive, 'tar' must be able to backspace the
+archive in order to reread or rewrite a record that was just read (or
+written). This is currently possible only on two kinds of files: normal
+disk files (or any other file that can be backspaced with 'lseek'), and
+industry-standard 9-track magnetic tape (or any other kind of tape that
+can be backspaced with the 'MTIOCTOP' 'ioctl').
+
+ This means that the '--append', '--concatenate', and '--delete'
+commands will not work on any other kind of file. Some media simply
+cannot be backspaced, which means these commands and options will never
+be able to work on them. These non-backspacing media include pipes and
+cartridge tape drives.
+
+ Some other media can be backspaced, and 'tar' will work on them once
+'tar' is modified to do so.
+
+ Archives created with the '--multi-volume', '--label', and
+'--incremental' ('-G') options may not be readable by other version of
+'tar'. In particular, restoring a file that was split over a volume
+boundary will require some careful work with 'dd', if it can be done at
+all. Other versions of 'tar' may also create an empty file whose name
+is that of the volume header. Some versions of 'tar' may create normal
+files instead of directories archived with the '--incremental' ('-G')
+option.
+
+
+File: tar.info, Node: Common Problems and Solutions, Next: Blocking, Prev: Remote Tape Server, Up: Media
+
+9.3 Some Common Problems and their Solutions
+============================================
+
+errors from system:
+permission denied
+no such file or directory
+not owner
+
+errors from 'tar':
+directory checksum error
+header format error
+
+errors from media/system:
+i/o error
+device busy
+
+
+File: tar.info, Node: Blocking, Next: Many, Prev: Common Problems and Solutions, Up: Media
+
+9.4 Blocking
+============
+
+"Block" and "record" terminology is rather confused, and it is also
+confusing to the expert reader. On the other hand, readers who are new
+to the field have a fresh mind, and they may safely skip the next two
+paragraphs, as the remainder of this manual uses those two terms in a
+quite consistent way.
+
+ John Gilmore, the writer of the public domain 'tar' from which GNU
+'tar' was originally derived, wrote (June 1995):
+
+ The nomenclature of tape drives comes from IBM, where I believe
+ they were invented for the IBM 650 or so. On IBM mainframes, what
+ is recorded on tape are tape blocks. The logical organization of
+ data is into records. There are various ways of putting records
+ into blocks, including 'F' (fixed sized records), 'V' (variable
+ sized records), 'FB' (fixed blocked: fixed size records, N to a
+ block), 'VB' (variable size records, N to a block), 'VSB' (variable
+ spanned blocked: variable sized records that can occupy more than
+ one block), etc. The 'JCL' 'DD RECFORM=' parameter specified this
+ to the operating system.
+
+ The Unix man page on 'tar' was totally confused about this. When I
+ wrote 'PD TAR', I used the historically correct terminology ('tar'
+ writes data records, which are grouped into blocks). It appears
+ that the bogus terminology made it into POSIX (no surprise here),
+ and now Franc,ois has migrated that terminology back into the
+ source code too.
+
+ The term "physical block" means the basic transfer chunk from or to a
+device, after which reading or writing may stop without anything being
+lost. In this manual, the term "block" usually refers to a disk
+physical block, _assuming_ that each disk block is 512 bytes in length.
+It is true that some disk devices have different physical blocks, but
+'tar' ignore these differences in its own format, which is meant to be
+portable, so a 'tar' block is always 512 bytes in length, and "block"
+always mean a 'tar' block. The term "logical block" often represents
+the basic chunk of allocation of many disk blocks as a single entity,
+which the operating system treats somewhat atomically; this concept is
+only barely used in GNU 'tar'.
+
+ The term "physical record" is another way to speak of a physical
+block, those two terms are somewhat interchangeable. In this manual,
+the term "record" usually refers to a tape physical block, _assuming_
+that the 'tar' archive is kept on magnetic tape. It is true that
+archives may be put on disk or used with pipes, but nevertheless, 'tar'
+tries to read and write the archive one "record" at a time, whatever the
+medium in use. One record is made up of an integral number of blocks,
+and this operation of putting many disk blocks into a single tape block
+is called "reblocking", or more simply, "blocking". The term "logical
+record" refers to the logical organization of many characters into
+something meaningful to the application. The term "unit record"
+describes a small set of characters which are transmitted whole to or by
+the application, and often refers to a line of text. Those two last
+terms are unrelated to what we call a "record" in GNU 'tar'.
+
+ When writing to tapes, 'tar' writes the contents of the archive in
+chunks known as "records". To change the default blocking factor, use
+the '--blocking-factor=512-SIZE' ('-b 512-SIZE') option. Each record
+will then be composed of 512-SIZE blocks. (Each 'tar' block is 512
+bytes. *Note Standard::.) Each file written to the archive uses at
+least one full record. As a result, using a larger record size can
+result in more wasted space for small files. On the other hand, a
+larger record size can often be read and written much more efficiently.
+
+ Further complicating the problem is that some tape drives ignore the
+blocking entirely. For these, a larger record size can still improve
+performance (because the software layers above the tape drive still
+honor the blocking), but not as dramatically as on tape drives that
+honor blocking.
+
+ When reading an archive, 'tar' can usually figure out the record size
+on itself. When this is the case, and a non-standard record size was
+used when the archive was created, 'tar' will print a message about a
+non-standard blocking factor, and then operate normally(1). On some
+tape devices, however, 'tar' cannot figure out the record size itself.
+On most of those, you can specify a blocking factor (with
+'--blocking-factor') larger than the actual blocking factor, and then
+use the '--read-full-records' ('-B') option. (If you specify a blocking
+factor with '--blocking-factor' and don't use the '--read-full-records'
+option, then 'tar' will not attempt to figure out the recording size
+itself.) On some devices, you must always specify the record size
+exactly with '--blocking-factor' when reading, because 'tar' cannot
+figure it out. In any case, use '--list' ('-t') before doing any
+extractions to see whether 'tar' is reading the archive correctly.
+
+ 'tar' blocks are all fixed size (512 bytes), and its scheme for
+putting them into records is to put a whole number of them (one or more)
+into each record. 'tar' records are all the same size; at the end of
+the file there's a block containing all zeros, which is how you tell
+that the remainder of the last record(s) are garbage.
+
+ In a standard 'tar' file (no options), the block size is 512 and the
+record size is 10240, for a blocking factor of 20. What the
+'--blocking-factor' option does is sets the blocking factor, changing
+the record size while leaving the block size at 512 bytes. 20 was fine
+for ancient 800 or 1600 bpi reel-to-reel tape drives; most tape drives
+these days prefer much bigger records in order to stream and not waste
+tape. When writing tapes for myself, some tend to use a factor of the
+order of 2048, say, giving a record size of around one megabyte.
+
+ If you use a blocking factor larger than 20, older 'tar' programs
+might not be able to read the archive, so we recommend this as a limit
+to use in practice. GNU 'tar', however, will support arbitrarily large
+record sizes, limited only by the amount of virtual memory or the
+physical characteristics of the tape device.
+
+* Menu:
+
+* Format Variations:: Format Variations
+* Blocking Factor:: The Blocking Factor of an Archive
+
+ ---------- Footnotes ----------
+
+ (1) If this message is not needed, you can turn it off using the
+'--warning=no-record-size' option.
+
+
+File: tar.info, Node: Format Variations, Next: Blocking Factor, Up: Blocking
+
+9.4.1 Format Variations
+-----------------------
+
+ _(This message will disappear, once this node revised.)_
+
+ Format parameters specify how an archive is written on the archive
+media. The best choice of format parameters will vary depending on the
+type and number of files being archived, and on the media used to store
+the archive.
+
+ To specify format parameters when accessing or creating an archive,
+you can use the options described in the following sections. If you do
+not specify any format parameters, 'tar' uses default parameters. You
+cannot modify a compressed archive. If you create an archive with the
+'--blocking-factor' option specified (*note Blocking Factor::), you must
+specify that blocking-factor when operating on the archive. *Note
+Formats::, for other examples of format parameter considerations.
+
+
+File: tar.info, Node: Blocking Factor, Prev: Format Variations, Up: Blocking
+
+9.4.2 The Blocking Factor of an Archive
+---------------------------------------
+
+ _(This message will disappear, once this node revised.)_
+
+ The data in an archive is grouped into blocks, which are 512 bytes.
+Blocks are read and written in whole number multiples called "records".
+The number of blocks in a record (i.e., the size of a record in units of
+512 bytes) is called the "blocking factor". The
+'--blocking-factor=512-SIZE' ('-b 512-SIZE') option specifies the
+blocking factor of an archive. The default blocking factor is typically
+20 (i.e., 10240 bytes), but can be specified at installation. To find
+out the blocking factor of an existing archive, use 'tar --list
+--file=ARCHIVE-NAME'. This may not work on some devices.
+
+ Records are separated by gaps, which waste space on the archive
+media. If you are archiving on magnetic tape, using a larger blocking
+factor (and therefore larger records) provides faster throughput and
+allows you to fit more data on a tape (because there are fewer gaps).
+If you are archiving on cartridge, a very large blocking factor (say 126
+or more) greatly increases performance. A smaller blocking factor, on
+the other hand, may be useful when archiving small files, to avoid
+archiving lots of nulls as 'tar' fills out the archive to the end of the
+record. In general, the ideal record size depends on the size of the
+inter-record gaps on the tape you are using, and the average size of the
+files you are archiving. *Note create::, for information on writing
+archives.
+
+ Archives with blocking factors larger than 20 cannot be read by very
+old versions of 'tar', or by some newer versions of 'tar' running on old
+machines with small address spaces. With GNU 'tar', the blocking factor
+of an archive is limited only by the maximum record size of the device
+containing the archive, or by the amount of available virtual memory.
+
+ Also, on some systems, not using adequate blocking factors, as
+sometimes imposed by the device drivers, may yield unexpected
+diagnostics. For example, this has been reported:
+
+ Cannot write to /dev/dlt: Invalid argument
+
+In such cases, it sometimes happen that the 'tar' bundled by the system
+is aware of block size idiosyncrasies, while GNU 'tar' requires an
+explicit specification for the block size, which it cannot guess. This
+yields some people to consider GNU 'tar' is misbehaving, because by
+comparison, 'the bundle 'tar' works OK'. Adding '-b 256', for example,
+might resolve the problem.
+
+ If you use a non-default blocking factor when you create an archive,
+you must specify the same blocking factor when you modify that archive.
+Some archive devices will also require you to specify the blocking
+factor when reading that archive, however this is not typically the
+case. Usually, you can use '--list' ('-t') without specifying a
+blocking factor--'tar' reports a non-default record size and then lists
+the archive members as it would normally. To extract files from an
+archive with a non-standard blocking factor (particularly if you're not
+sure what the blocking factor is), you can usually use the
+'--read-full-records' ('-B') option while specifying a blocking factor
+larger then the blocking factor of the archive (i.e., 'tar --extract
+--read-full-records --blocking-factor=300'). *Note list::, for more
+information on the '--list' ('-t') operation. *Note Reading::, for a
+more detailed explanation of that option.
+
+'--blocking-factor=NUMBER'
+'-b NUMBER'
+ Specifies the blocking factor of an archive. Can be used with any
+ operation, but is usually not necessary with '--list' ('-t').
+
+ Device blocking
+
+'-b BLOCKS'
+'--blocking-factor=BLOCKS'
+ Set record size to BLOCKS*512 bytes.
+
+ This option is used to specify a "blocking factor" for the archive.
+ When reading or writing the archive, 'tar', will do reads and
+ writes of the archive in records of BLOCK*512 bytes. This is true
+ even when the archive is compressed. Some devices requires that
+ all write operations be a multiple of a certain size, and so, 'tar'
+ pads the archive out to the next record boundary.
+
+ The default blocking factor is set when 'tar' is compiled, and is
+ typically 20. Blocking factors larger than 20 cannot be read by
+ very old versions of 'tar', or by some newer versions of 'tar'
+ running on old machines with small address spaces.
+
+ With a magnetic tape, larger records give faster throughput and fit
+ more data on a tape (because there are fewer inter-record gaps).
+ If the archive is in a disk file or a pipe, you may want to specify
+ a smaller blocking factor, since a large one will result in a large
+ number of null bytes at the end of the archive.
+
+ When writing cartridge or other streaming tapes, a much larger
+ blocking factor (say 126 or more) will greatly increase
+ performance. However, you must specify the same blocking factor
+ when reading or updating the archive.
+
+ Apparently, Exabyte drives have a physical block size of 8K bytes.
+ If we choose our blocksize as a multiple of 8k bytes, then the
+ problem seems to disappear. Id est, we are using block size of 112
+ right now, and we haven't had the problem since we switched...
+
+ With GNU 'tar' the blocking factor is limited only by the maximum
+ record size of the device containing the archive, or by the amount
+ of available virtual memory.
+
+ However, deblocking or reblocking is virtually avoided in a special
+ case which often occurs in practice, but which requires all the
+ following conditions to be simultaneously true:
+ * the archive is subject to a compression option,
+ * the archive is not handled through standard input or output,
+ nor redirected nor piped,
+ * the archive is directly handled to a local disk, instead of
+ any special device,
+ * '--blocking-factor' is not explicitly specified on the 'tar'
+ invocation.
+
+ If the output goes directly to a local disk, and not through
+ stdout, then the last write is not extended to a full record size.
+ Otherwise, reblocking occurs. Here are a few other remarks on this
+ topic:
+
+ * 'gzip' will complain about trailing garbage if asked to
+ uncompress a compressed archive on tape, there is an option to
+ turn the message off, but it breaks the regularity of simply
+ having to use 'PROG -d' for decompression. It would be nice
+ if gzip was silently ignoring any number of trailing zeros.
+ I'll ask Jean-loup Gailly, by sending a copy of this message
+ to him.
+
+ * 'compress' does not show this problem, but as Jean-loup
+ pointed out to Michael, 'compress -d' silently adds garbage
+ after the result of decompression, which tar ignores because
+ it already recognized its end-of-file indicator. So this bug
+ may be safely ignored.
+
+ * 'gzip -d -q' will be silent about the trailing zeros indeed,
+ but will still return an exit status of 2 which tar reports in
+ turn. 'tar' might ignore the exit status returned, but I hate
+ doing that, as it weakens the protection 'tar' offers users
+ against other possible problems at decompression time. If
+ 'gzip' was silently skipping trailing zeros _and_ also
+ avoiding setting the exit status in this innocuous case, that
+ would solve this situation.
+
+ * 'tar' should become more solid at not stopping to read a pipe
+ at the first null block encountered. This inelegantly breaks
+ the pipe. 'tar' should rather drain the pipe out before
+ exiting itself.
+
+'-i'
+'--ignore-zeros'
+ Ignore blocks of zeros in archive (means EOF).
+
+ The '--ignore-zeros' ('-i') option causes 'tar' to ignore blocks of
+ zeros in the archive. Normally a block of zeros indicates the end
+ of the archive, but when reading a damaged archive, or one which
+ was created by concatenating several archives together, this option
+ allows 'tar' to read the entire archive. This option is not on by
+ default because many versions of 'tar' write garbage after the
+ zeroed blocks.
+
+ Note that this option causes 'tar' to read to the end of the
+ archive file, which may sometimes avoid problems when multiple
+ files are stored on a single physical tape.
+
+'-B'
+'--read-full-records'
+ Reblock as we read (for reading 4.2BSD pipes).
+
+ If '--read-full-records' is used, 'tar' will not panic if an
+ attempt to read a record from the archive does not return a full
+ record. Instead, 'tar' will keep reading until it has obtained a
+ full record.
+
+ This option is turned on by default when 'tar' is reading an
+ archive from standard input, or from a remote machine. This is
+ because on BSD Unix systems, a read of a pipe will return however
+ much happens to be in the pipe, even if it is less than 'tar'
+ requested. If this option was not used, 'tar' would fail as soon
+ as it read an incomplete record from the pipe.
+
+ This option is also useful with the commands for updating an
+ archive.
+
+ Tape blocking
+
+ When handling various tapes or cartridges, you have to take care of
+selecting a proper blocking, that is, the number of disk blocks you put
+together as a single tape block on the tape, without intervening tape
+gaps. A "tape gap" is a small landing area on the tape with no
+information on it, used for decelerating the tape to a full stop, and
+for later regaining the reading or writing speed. When the tape driver
+starts reading a record, the record has to be read whole without
+stopping, as a tape gap is needed to stop the tape motion without losing
+information.
+
+ Using higher blocking (putting more disk blocks per tape block) will
+use the tape more efficiently as there will be less tape gaps. But
+reading such tapes may be more difficult for the system, as more memory
+will be required to receive at once the whole record. Further, if there
+is a reading error on a huge record, this is less likely that the system
+will succeed in recovering the information. So, blocking should not be
+too low, nor it should be too high. 'tar' uses by default a blocking of
+20 for historical reasons, and it does not really matter when reading or
+writing to disk. Current tape technology would easily accommodate
+higher blockings. Sun recommends a blocking of 126 for Exabytes and 96
+for DATs. We were told that for some DLT drives, the blocking should be
+a multiple of 4Kb, preferably 64Kb ('-b 128') or 256 for decent
+performance. Other manufacturers may use different recommendations for
+the same tapes. This might also depends of the buffering techniques
+used inside modern tape controllers. Some imposes a minimum blocking,
+or a maximum blocking. Others request blocking to be some exponent of
+two.
+
+ So, there is no fixed rule for blocking. But blocking at read time
+should ideally be the same as blocking used at write time. At one place
+I know, with a wide variety of equipment, they found it best to use a
+blocking of 32 to guarantee that their tapes are fully interchangeable.
+
+ I was also told that, for recycled tapes, prior erasure (by the same
+drive unit that will be used to create the archives) sometimes lowers
+the error rates observed at rewriting time.
+
+ I might also use '--number-blocks' instead of '--block-number', so
+'--block' will then expand to '--blocking-factor' unambiguously.
+
+
+File: tar.info, Node: Many, Next: Using Multiple Tapes, Prev: Blocking, Up: Media
+
+9.5 Many Archives on One Tape
+=============================
+
+Most tape devices have two entries in the '/dev' directory, or entries
+that come in pairs, which differ only in the minor number for this
+device. Let's take for example '/dev/tape', which often points to the
+only or usual tape device of a given system. There might be a
+corresponding '/dev/nrtape' or '/dev/ntape'. The simpler name is the
+_rewinding_ version of the device, while the name having 'nr' in it is
+the _no rewinding_ version of the same device.
+
+ A rewinding tape device will bring back the tape to its beginning
+point automatically when this device is opened or closed. Since 'tar'
+opens the archive file before using it and closes it afterwards, this
+means that a simple:
+
+ $ tar cf /dev/tape DIRECTORY
+
+will reposition the tape to its beginning both prior and after saving
+DIRECTORY contents to it, thus erasing prior tape contents and making it
+so that any subsequent write operation will destroy what has just been
+saved.
+
+ So, a rewinding device is normally meant to hold one and only one
+file. If you want to put more than one 'tar' archive on a given tape,
+you will need to avoid using the rewinding version of the tape device.
+You will also have to pay special attention to tape positioning. Errors
+in positioning may overwrite the valuable data already on your tape.
+Many people, burnt by past experiences, will only use rewinding devices
+and limit themselves to one file per tape, precisely to avoid the risk
+of such errors. Be fully aware that writing at the wrong position on a
+tape loses all information past this point and most probably until the
+end of the tape, and this destroyed information _cannot_ be recovered.
+
+ To save DIRECTORY-1 as a first archive at the beginning of a tape,
+and leave that tape ready for a second archive, you should use:
+
+ $ mt -f /dev/nrtape rewind
+ $ tar cf /dev/nrtape DIRECTORY-1
+
+ "Tape marks" are special magnetic patterns written on the tape media,
+which are later recognizable by the reading hardware. These marks are
+used after each file, when there are many on a single tape. An empty
+file (that is to say, two tape marks in a row) signal the logical end of
+the tape, after which no file exist. Usually, non-rewinding tape device
+drivers will react to the close request issued by 'tar' by first writing
+two tape marks after your archive, and by backspacing over one of these.
+So, if you remove the tape at that time from the tape drive, it is
+properly terminated. But if you write another file at the current
+position, the second tape mark will be erased by the new information,
+leaving only one tape mark between files.
+
+ So, you may now save DIRECTORY-2 as a second archive after the first
+on the same tape by issuing the command:
+
+ $ tar cf /dev/nrtape DIRECTORY-2
+
+and so on for all the archives you want to put on the same tape.
+
+ Another usual case is that you do not write all the archives the same
+day, and you need to remove and store the tape between two archive
+sessions. In general, you must remember how many files are already
+saved on your tape. Suppose your tape already has 16 files on it, and
+that you are ready to write the 17th. You have to take care of skipping
+the first 16 tape marks before saving DIRECTORY-17, say, by using these
+commands:
+
+ $ mt -f /dev/nrtape rewind
+ $ mt -f /dev/nrtape fsf 16
+ $ tar cf /dev/nrtape DIRECTORY-17
+
+ In all the previous examples, we put aside blocking considerations,
+but you should do the proper things for that as well. *Note Blocking::.
+
+* Menu:
+
+* Tape Positioning:: Tape Positions and Tape Marks
+* mt:: The 'mt' Utility
+
+
+File: tar.info, Node: Tape Positioning, Next: mt, Up: Many
+
+9.5.1 Tape Positions and Tape Marks
+-----------------------------------
+
+ _(This message will disappear, once this node revised.)_
+
+ Just as archives can store more than one file from the file system,
+tapes can store more than one archive file. To keep track of where
+archive files (or any other type of file stored on tape) begin and end,
+tape archive devices write magnetic "tape marks" on the archive media.
+Tape drives write one tape mark between files, two at the end of all the
+file entries.
+
+ If you think of data as a series of records "rrrr"'s, and tape marks
+as "*"'s, a tape might look like the following:
+
+ rrrr*rrrrrr*rrrrr*rr*rrrrr**-------------------------
+
+ Tape devices read and write tapes using a read/write "tape head"--a
+physical part of the device which can only access one point on the tape
+at a time. When you use 'tar' to read or write archive data from a tape
+device, the device will begin reading or writing from wherever on the
+tape the tape head happens to be, regardless of which archive or what
+part of the archive the tape head is on. Before writing an archive, you
+should make sure that no data on the tape will be overwritten (unless it
+is no longer needed). Before reading an archive, you should make sure
+the tape head is at the beginning of the archive you want to read. You
+can do it manually via 'mt' utility (*note mt::). The 'restore' script
+does that automatically (*note Scripted Restoration::).
+
+ If you want to add new archive file entries to a tape, you should
+advance the tape to the end of the existing file entries, backspace over
+the last tape mark, and write the new archive file. If you were to add
+two archives to the example above, the tape might look like the
+following:
+
+ rrrr*rrrrrr*rrrrr*rr*rrrrr*rrr*rrrr**----------------
+
+
+File: tar.info, Node: mt, Prev: Tape Positioning, Up: Many
+
+9.5.2 The 'mt' Utility
+----------------------
+
+ _(This message will disappear, once this node revised.)_
+
+ *Note Blocking Factor::.
+
+ You can use the 'mt' utility to advance or rewind a tape past a
+specified number of archive files on the tape. This will allow you to
+move to the beginning of an archive before extracting or reading it, or
+to the end of all the archives before writing a new one.
+
+ The syntax of the 'mt' command is:
+
+ mt [-f TAPENAME] OPERATION [NUMBER]
+
+ where TAPENAME is the name of the tape device, NUMBER is the number
+of times an operation is performed (with a default of one), and
+OPERATION is one of the following:
+
+'eof'
+'weof'
+ Writes NUMBER tape marks at the current position on the tape.
+
+'fsf'
+ Moves tape position forward NUMBER files.
+
+'bsf'
+ Moves tape position back NUMBER files.
+
+'rewind'
+ Rewinds the tape. (Ignores NUMBER.)
+
+'offline'
+'rewoff1'
+ Rewinds the tape and takes the tape device off-line. (Ignores
+ NUMBER.)
+
+'status'
+ Prints status information about the tape unit.
+
+ If you don't specify a TAPENAME, 'mt' uses the environment variable
+'TAPE'; if 'TAPE' is not set, 'mt' will use the default device specified
+in your 'sys/mtio.h' file ('DEFTAPE' variable). If this is not defined,
+the program will display a descriptive error message and exit with code
+1.
+
+ 'mt' returns a 0 exit status when the operation(s) were successful, 1
+if the command was unrecognized, and 2 if an operation failed.
+
+
+File: tar.info, Node: Using Multiple Tapes, Next: label, Prev: Many, Up: Media
+
+9.6 Using Multiple Tapes
+========================
+
+Often you might want to write a large archive, one larger than will fit
+on the actual tape you are using. In such a case, you can run multiple
+'tar' commands, but this can be inconvenient, particularly if you are
+using options like '--exclude=PATTERN' or dumping entire file systems.
+Therefore, 'tar' provides a special mode for creating multi-volume
+archives.
+
+ "Multi-volume" archive is a single 'tar' archive, stored on several
+media volumes of fixed size. Although in this section we will often
+call 'volume' a "tape", there is absolutely no requirement for
+multi-volume archives to be stored on tapes. Instead, they can use
+whatever media type the user finds convenient, they can even be located
+on files.
+
+ When creating a multi-volume archive, GNU 'tar' continues to fill
+current volume until it runs out of space, then it switches to next
+volume (usually the operator is queried to replace the tape on this
+point), and continues working on the new volume. This operation
+continues until all requested files are dumped. If GNU 'tar' detects
+end of media while dumping a file, such a file is archived in split
+form. Some very big files can even be split across several volumes.
+
+ Each volume is itself a valid GNU 'tar' archive, so it can be read
+without any special options. Consequently any file member residing
+entirely on one volume can be extracted or otherwise operated upon
+without needing the other volume. Sure enough, to extract a split
+member you would need all volumes its parts reside on.
+
+ Multi-volume archives suffer from several limitations. In
+particular, they cannot be compressed.
+
+ GNU 'tar' is able to create multi-volume archives of two formats
+(*note Formats::): 'GNU' and 'POSIX'.
+
+* Menu:
+
+* Multi-Volume Archives:: Archives Longer than One Tape or Disk
+* Tape Files:: Tape Files
+* Tarcat:: Concatenate Volumes into a Single Archive
+
+
+File: tar.info, Node: Multi-Volume Archives, Next: Tape Files, Up: Using Multiple Tapes
+
+9.6.1 Archives Longer than One Tape or Disk
+-------------------------------------------
+
+To create an archive that is larger than will fit on a single unit of
+the media, use the '--multi-volume' ('-M') option in conjunction with
+the '--create' option (*note create::). A "multi-volume" archive can be
+manipulated like any other archive (provided the '--multi-volume' option
+is specified), but is stored on more than one tape or file.
+
+ When you specify '--multi-volume', 'tar' does not report an error
+when it comes to the end of an archive volume (when reading), or the end
+of the media (when writing). Instead, it prompts you to load a new
+storage volume. If the archive is on a magnetic tape, you should change
+tapes when you see the prompt; if the archive is on a floppy disk, you
+should change disks; etc.
+
+'--multi-volume'
+'-M'
+ Creates a multi-volume archive, when used in conjunction with
+ '--create' ('-c'). To perform any other operation on a
+ multi-volume archive, specify '--multi-volume' in conjunction with
+ that operation. For example:
+
+ $ tar --create --multi-volume --file=/dev/tape FILES
+
+ The method 'tar' uses to detect end of tape is not perfect, and fails
+on some operating systems or on some devices. If 'tar' cannot detect
+the end of the tape itself, you can use '--tape-length' option to inform
+it about the capacity of the tape:
+
+'--tape-length=SIZE[SUF]'
+'-L SIZE[SUF]'
+ Set maximum length of a volume. The SUF, if given, specifies units
+ in which SIZE is expressed, e.g. '2M' mean 2 megabytes (*note
+ Table 9.1: size-suffixes, for a list of allowed size suffixes).
+ Without SUF, units of 1024 bytes (kilobyte) are assumed.
+
+ This option selects '--multi-volume' automatically. For example:
+
+ $ tar --create --tape-length=41943040 --file=/dev/tape FILES
+
+ or, which is equivalent:
+
+ $ tar --create --tape-length=4G --file=/dev/tape FILES
+
+ When GNU 'tar' comes to the end of a storage media, it asks you to
+change the volume. The built-in prompt for POSIX locale is(1):
+
+ Prepare volume #N for 'ARCHIVE' and hit return:
+
+where N is the ordinal number of the volume to be created and ARCHIVE is
+archive file or device name.
+
+ When prompting for a new tape, 'tar' accepts any of the following
+responses:
+
+'?'
+ Request 'tar' to explain possible responses.
+'q'
+ Request 'tar' to exit immediately.
+'n FILE-NAME'
+ Request 'tar' to write the next volume on the file FILE-NAME.
+'!'
+ Request 'tar' to run a subshell. This option can be disabled by
+ giving '--restrict' command line option to 'tar'(2).
+'y'
+ Request 'tar' to begin writing the next volume.
+
+ (You should only type 'y' after you have changed the tape; otherwise
+'tar' will write over the volume it just finished.)
+
+ The volume number used by 'tar' in its tape-changing prompt can be
+changed; if you give the '--volno-file=FILE-OF-NUMBER' option, then
+FILE-OF-NUMBER should be an non-existing file to be created, or else, a
+file already containing a decimal number. That number will be used as
+the volume number of the first volume written. When 'tar' is finished,
+it will rewrite the file with the now-current volume number. (This does
+not change the volume number written on a tape label, as per *note
+label::, it _only_ affects the number used in the prompt.)
+
+ If you want more elaborate behavior than this, you can write a
+special "new volume script", that will be responsible for changing the
+volume, and instruct 'tar' to use it instead of its normal prompting
+procedure:
+
+'--info-script=COMMAND'
+'--new-volume-script=COMMAND'
+'-F COMMAND'
+ Specify the command to invoke when switching volumes. The COMMAND
+ can be used to eject cassettes, or to broadcast messages such as
+ 'Someone please come change my tape' when performing unattended
+ backups.
+
+ The COMMAND can contain additional options, if such are needed.
+*Note Running External Commands: external, for a detailed discussion of
+the way GNU 'tar' runs external commands. It inherits 'tar''s shell
+environment. Additional data is passed to it via the following
+environment variables:
+
+'TAR_VERSION'
+ GNU 'tar' version number.
+
+'TAR_ARCHIVE'
+ The name of the archive 'tar' is processing.
+
+'TAR_BLOCKING_FACTOR'
+ Current blocking factor (*note Blocking::).
+
+'TAR_VOLUME'
+ Ordinal number of the volume 'tar' is about to start.
+
+'TAR_SUBCOMMAND'
+ A short option describing the operation 'tar' is executing. *Note
+ Operations::, for a complete list of subcommand options.
+
+'TAR_FORMAT'
+ Format of the archive being processed. *Note Formats::, for a
+ complete list of archive format names.
+
+'TAR_FD'
+ File descriptor which can be used to communicate the new volume
+ name to 'tar'.
+
+ These variables can be used in the COMMAND itself, provided that they
+are properly quoted to prevent them from being expanded by the shell
+that invokes 'tar'.
+
+ The volume script can instruct 'tar' to use new archive name, by
+writing in to file descriptor '$TAR_FD' (see below for an example).
+
+ If the info script fails, 'tar' exits; otherwise, it begins writing
+the next volume.
+
+ If you want 'tar' to cycle through a series of files or tape drives,
+there are three approaches to choose from. First of all, you can give
+'tar' multiple '--file' options. In this case the specified files will
+be used, in sequence, as the successive volumes of the archive. Only
+when the first one in the sequence needs to be used again will 'tar'
+prompt for a tape change (or run the info script). For example, suppose
+someone has two tape drives on a system named '/dev/tape0' and
+'/dev/tape1'. For having GNU 'tar' to switch to the second drive when
+it needs to write the second tape, and then back to the first tape,
+etc., just do either of:
+
+ $ tar --create --multi-volume --file=/dev/tape0 --file=/dev/tape1 FILES
+ $ tar -cM -f /dev/tape0 -f /dev/tape1 FILES
+
+ The second method is to use the 'n' response to the tape-change
+prompt.
+
+ Finally, the most flexible approach is to use a volume script, that
+writes new archive name to the file descriptor '$TAR_FD'. For example,
+the following volume script will create a series of archive files, named
+'ARCHIVE-VOL', where ARCHIVE is the name of the archive being created
+(as given by '--file' option) and VOL is the ordinal number of the
+archive being created:
+
+ #! /bin/bash
+ # For this script it's advisable to use a shell, such as Bash,
+ # that supports a TAR_FD value greater than 9.
+
+ echo Preparing volume $TAR_VOLUME of $TAR_ARCHIVE.
+
+ name=`expr $TAR_ARCHIVE : '\(.*\)-.*'`
+ case $TAR_SUBCOMMAND in
+ -c) ;;
+ -d|-x|-t) test -r ${name:-$TAR_ARCHIVE}-$TAR_VOLUME || exit 1
+ ;;
+ *) exit 1
+ esac
+
+ echo ${name:-$TAR_ARCHIVE}-$TAR_VOLUME >&$TAR_FD
+
+ The same script can be used while listing, comparing or extracting
+from the created archive. For example:
+
+ # Create a multi-volume archive:
+ $ tar -c -L1024 -f archive.tar -F new-volume .
+ # Extract from the created archive:
+ $ tar -x -f archive.tar -F new-volume .
+
+Notice, that the first command had to use '-L' option, since otherwise
+GNU 'tar' will end up writing everything to file 'archive.tar'.
+
+ You can read each individual volume of a multi-volume archive as if
+it were an archive by itself. For example, to list the contents of one
+volume, use '--list', without '--multi-volume' specified. To extract an
+archive member from one volume (assuming it is described that volume),
+use '--extract', again without '--multi-volume'.
+
+ If an archive member is split across volumes (i.e., its entry begins
+on one volume of the media and ends on another), you need to specify
+'--multi-volume' to extract it successfully. In this case, you should
+load the volume where the archive member starts, and use 'tar --extract
+--multi-volume'--'tar' will prompt for later volumes as it needs them.
+*Note extracting archives::, for more information about extracting
+archives.
+
+ Multi-volume archives can be modified like any other archive. To add
+files to a multi-volume archive, you need to only mount the last volume
+of the archive media (and new volumes, if needed). For all other
+operations, you need to use the entire archive.
+
+ If a multi-volume archive was labeled using '--label=ARCHIVE-LABEL'
+(*note label::) when it was created, 'tar' will not automatically label
+volumes which are added later. To label subsequent volumes, specify
+'--label=ARCHIVE-LABEL' again in conjunction with the '--append',
+'--update' or '--concatenate' operation.
+
+ Notice that multi-volume support is a GNU extension and the archives
+created in this mode should be read only using GNU 'tar'. If you
+absolutely have to process such archives using a third-party 'tar'
+implementation, read *note Split Recovery::.
+
+ ---------- Footnotes ----------
+
+ (1) If you run GNU 'tar' under a different locale, the translation to
+the locale's language will be used.
+
+ (2) *Note --restrict::, for more information about this option.
+
+
+File: tar.info, Node: Tape Files, Next: Tarcat, Prev: Multi-Volume Archives, Up: Using Multiple Tapes
+
+9.6.2 Tape Files
+----------------
+
+ _(This message will disappear, once this node revised.)_
+
+ To give the archive a name which will be recorded in it, use the
+'--label=VOLUME-LABEL' ('-V VOLUME-LABEL') option. This will write a
+special block identifying VOLUME-LABEL as the name of the archive to the
+front of the archive which will be displayed when the archive is listed
+with '--list'. If you are creating a multi-volume archive with
+'--multi-volume' (*note Using Multiple Tapes::), then the volume label
+will have 'Volume NNN' appended to the name you give, where NNN is the
+number of the volume of the archive. If you use the
+'--label=VOLUME-LABEL' option when reading an archive, it checks to make
+sure the label on the tape matches the one you gave. *Note label::.
+
+ When 'tar' writes an archive to tape, it creates a single tape file.
+If multiple archives are written to the same tape, one after the other,
+they each get written as separate tape files. When extracting, it is
+necessary to position the tape at the right place before running 'tar'.
+To do this, use the 'mt' command. For more information on the 'mt'
+command and on the organization of tapes into a sequence of tape files,
+see *note mt::.
+
+ People seem to often do:
+
+ --label="SOME-PREFIX `date +SOME-FORMAT`"
+
+ or such, for pushing a common date in all volumes or an archive set.
+
+
+File: tar.info, Node: Tarcat, Prev: Tape Files, Up: Using Multiple Tapes
+
+9.6.3 Concatenate Volumes into a Single Archive
+-----------------------------------------------
+
+Sometimes it is necessary to convert existing GNU 'tar' multi-volume
+archive to a single 'tar' archive. Simply concatenating all volumes
+into one will not work, since each volume carries an additional
+information at the beginning. GNU 'tar' is shipped with the shell
+script 'tarcat' designed for this purpose.
+
+ The script takes a list of files comprising a multi-volume archive
+and creates the resulting archive at the standard output. For example:
+
+ tarcat vol.1 vol.2 vol.3 | tar tf -
+
+ The script implements a simple heuristics to determine the format of
+the first volume file and to decide how to process the rest of the
+files. However, it makes no attempt to verify whether the files are
+given in order or even if they are valid 'tar' archives. It uses 'dd'
+and does not filter its standard error, so you will usually see lots of
+spurious messages.
+
+
+File: tar.info, Node: label, Next: verify, Prev: Using Multiple Tapes, Up: Media
+
+9.7 Including a Label in the Archive
+====================================
+
+To avoid problems caused by misplaced paper labels on the archive media,
+you can include a "label" entry -- an archive member which contains the
+name of the archive -- in the archive itself. Use the
+'--label=ARCHIVE-LABEL' ('-V ARCHIVE-LABEL') option(1) in conjunction
+with the '--create' operation to include a label entry in the archive as
+it is being created.
+
+'--label=ARCHIVE-LABEL'
+'-V ARCHIVE-LABEL'
+ Includes an "archive-label" at the beginning of the archive when
+ the archive is being created, when used in conjunction with the
+ '--create' operation. Checks to make sure the archive label
+ matches the one specified (when used in conjunction with any other
+ operation).
+
+ If you create an archive using both '--label=ARCHIVE-LABEL' ('-V
+ARCHIVE-LABEL') and '--multi-volume' ('-M'), each volume of the archive
+will have an archive label of the form 'ARCHIVE-LABEL Volume N', where N
+is 1 for the first volume, 2 for the next, and so on. *Note Using
+Multiple Tapes::, for information on creating multiple volume archives.
+
+ The volume label will be displayed by '--list' along with the file
+contents. If verbose display is requested, it will also be explicitly
+marked as in the example below:
+
+ $ tar --verbose --list --file=iamanarchive
+ V--------- 0/0 0 1992-03-07 12:01 iamalabel--Volume Header--
+ -rw-r--r-- ringo/user 40 1990-05-21 13:30 iamafilename
+
+ However, '--list' option will cause listing entire contents of the
+archive, which may be undesirable (for example, if the archive is stored
+on a tape). You can request checking only the volume label by
+specifying '--test-label' option. This option reads only the first
+block of an archive, so it can be used with slow storage devices. For
+example:
+
+ $ tar --test-label --file=iamanarchive
+ iamalabel
+
+ If '--test-label' is used with one or more command line arguments,
+'tar' compares the volume label with each argument. It exits with code
+0 if a match is found, and with code 1 otherwise(2). No output is
+displayed, unless you also used the '--verbose' option. For example:
+
+ $ tar --test-label --file=iamanarchive 'iamalabel'
+ => 0
+ $ tar --test-label --file=iamanarchive 'alabel'
+ => 1
+
+ When used with the '--verbose' option, 'tar' prints the actual volume
+label (if any), and a verbose diagnostics in case of a mismatch:
+
+ $ tar --test-label --verbose --file=iamanarchive 'iamalabel'
+ iamalabel
+ => 0
+ $ tar --test-label --verbose --file=iamanarchive 'alabel'
+ iamalabel
+ tar: Archive label mismatch
+ => 1
+
+ If you request any operation, other than '--create', along with using
+'--label' option, 'tar' will first check if the archive label matches
+the one specified and will refuse to proceed if it does not. Use this
+as a safety precaution to avoid accidentally overwriting existing
+archives. For example, if you wish to add files to 'archive',
+presumably labeled with string 'My volume', you will get:
+
+ $ tar -rf archive --label 'My volume' .
+ tar: Archive not labeled to match 'My volume'
+
+in case its label does not match. This will work even if 'archive' is
+not labeled at all.
+
+ Similarly, 'tar' will refuse to list or extract the archive if its
+label doesn't match the ARCHIVE-LABEL specified. In those cases,
+ARCHIVE-LABEL argument is interpreted as a globbing-style pattern which
+must match the actual magnetic volume label. *Note exclude::, for a
+precise description of how match is attempted(3). If the switch
+'--multi-volume' ('-M') is being used, the volume label matcher will
+also suffix ARCHIVE-LABEL by ' Volume [1-9]*' if the initial match
+fails, before giving up. Since the volume numbering is automatically
+added in labels at creation time, it sounded logical to equally help the
+user taking care of it when the archive is being read.
+
+ You can also use '--label' to get a common information on all tapes
+of a series. For having this information different in each series
+created through a single script used on a regular basis, just manage to
+get some date string as part of the label. For example:
+
+ $ tar -cM -f /dev/tape -V "Daily backup for `date +%Y-%m-%d`"
+ $ tar --create --file=/dev/tape --multi-volume \
+ --label="Daily backup for `date +%Y-%m-%d`"
+
+ Some more notes about volume labels:
+
+ * Each label has its own date and time, which corresponds to the time
+ when GNU 'tar' initially attempted to write it, often soon after
+ the operator launches 'tar' or types the carriage return telling
+ that the next tape is ready.
+
+ * Comparing date labels to get an idea of tape throughput is
+ unreliable. It gives correct results only if the delays for
+ rewinding tapes and the operator switching them were negligible,
+ which is usually not the case.
+
+ ---------- Footnotes ----------
+
+ (1) Until version 1.10, that option was called '--volume', but is not
+available under that name anymore.
+
+ (2) Note that GNU 'tar' versions up to 1.23 indicated mismatch with
+an exit code 2 and printed a spurious diagnostics on stderr.
+
+ (3) Previous versions of 'tar' used full regular expression matching,
+or before that, only exact string matching, instead of wildcard
+matchers. We decided for the sake of simplicity to use a uniform
+matching device through 'tar'.
+
+
+File: tar.info, Node: verify, Next: Write Protection, Prev: label, Up: Media
+
+9.8 Verifying Data as It is Stored
+==================================
+
+'-W'
+'--verify'
+ Attempt to verify the archive after writing.
+
+ This option causes 'tar' to verify the archive after writing it.
+Each volume is checked after it is written, and any discrepancies are
+recorded on the standard error output.
+
+ Verification requires that the archive be on a back-space-able
+medium. This means pipes, some cartridge tape drives, and some other
+devices cannot be verified.
+
+ You can insure the accuracy of an archive by comparing files in the
+system with archive members. 'tar' can compare an archive to the file
+system as the archive is being written, to verify a write operation, or
+can compare a previously written archive, to insure that it is up to
+date.
+
+ To check for discrepancies in an archive immediately after it is
+written, use the '--verify' ('-W') option in conjunction with the
+'--create' operation. When this option is specified, 'tar' checks
+archive members against their counterparts in the file system, and
+reports discrepancies on the standard error.
+
+ To verify an archive, you must be able to read it from before the end
+of the last written entry. This option is useful for detecting data
+errors on some tapes. Archives written to pipes, some cartridge tape
+drives, and some other devices cannot be verified.
+
+ One can explicitly compare an already made archive with the file
+system by using the '--compare' ('--diff', '-d') option, instead of
+using the more automatic '--verify' option. *Note compare::.
+
+ Note that these two options have a slightly different intent. The
+'--compare' option checks how identical are the logical contents of some
+archive with what is on your disks, while the '--verify' option is
+really for checking if the physical contents agree and if the recording
+media itself is of dependable quality. So, for the '--verify'
+operation, 'tar' tries to defeat all in-memory cache pertaining to the
+archive, while it lets the speed optimization undisturbed for the
+'--compare' option. If you nevertheless use '--compare' for media
+verification, you may have to defeat the in-memory cache yourself, maybe
+by opening and reclosing the door latch of your recording unit, forcing
+some doubt in your operating system about the fact this is really the
+same volume as the one just written or read.
+
+ The '--verify' option would not be necessary if drivers were indeed
+able to detect dependably all write failures. This sometimes require
+many magnetic heads, some able to read after the writes occurred. One
+would not say that drivers unable to detect all cases are necessarily
+flawed, as long as programming is concerned.
+
+ The '--verify' ('-W') option will not work in conjunction with the
+'--multi-volume' ('-M') option or the '--append' ('-r'), '--update'
+('-u') and '--delete' operations. *Note Operations::, for more
+information on these operations.
+
+ Also, since 'tar' normally strips leading '/' from file names (*note
+absolute::), a command like 'tar --verify -cf /tmp/foo.tar /etc' will
+work as desired only if the working directory is '/', as 'tar' uses the
+archive's relative member names (e.g., 'etc/motd') when verifying the
+archive.
+
+
+File: tar.info, Node: Write Protection, Prev: verify, Up: Media
+
+9.9 Write Protection
+====================
+
+Almost all tapes and diskettes, and in a few rare cases, even disks can
+be "write protected", to protect data on them from being changed. Once
+an archive is written, you should write protect the media to prevent the
+archive from being accidentally overwritten or deleted. (This will
+protect the archive from being changed with a tape or floppy drive--it
+will not protect it from magnet fields or other physical hazards.)
+
+ The write protection device itself is usually an integral part of the
+physical media, and can be a two position (write enabled/write disabled)
+switch, a notch which can be popped out or covered, a ring which can be
+removed from the center of a tape reel, or some other changeable
+feature.
+
+
+File: tar.info, Node: Reliability and security, Next: Changes, Prev: Media, Up: Top
+
+10 Reliability and Security
+***************************
+
+The 'tar' command reads and writes files as any other application does,
+and is subject to the usual caveats about reliability and security.
+This section contains some commonsense advice on the topic.
+
+* Menu:
+
+* Reliability::
+* Security::
+
+
+File: tar.info, Node: Reliability, Next: Security, Up: Reliability and security
+
+10.1 Reliability
+================
+
+Ideally, when 'tar' is creating an archive, it reads from a file system
+that is not being modified, and encounters no errors or inconsistencies
+while reading and writing. If this is the case, the archive should
+faithfully reflect what was read. Similarly, when extracting from an
+archive, ideally 'tar' ideally encounters no errors and the extracted
+files faithfully reflect what was in the archive.
+
+ However, when reading or writing real-world file systems, several
+things can go wrong; these include permissions problems, corruption of
+data, and race conditions.
+
+* Menu:
+
+* Permissions problems::
+* Data corruption and repair::
+* Race conditions::
+
+
+File: tar.info, Node: Permissions problems, Next: Data corruption and repair, Up: Reliability
+
+10.1.1 Permissions Problems
+---------------------------
+
+If 'tar' encounters errors while reading or writing files, it normally
+reports an error and exits with nonzero status. The work it does may
+therefore be incomplete. For example, when creating an archive, if
+'tar' cannot read a file then it cannot copy the file into the archive.
+
+
+File: tar.info, Node: Data corruption and repair, Next: Race conditions, Prev: Permissions problems, Up: Reliability
+
+10.1.2 Data Corruption and Repair
+---------------------------------
+
+If an archive becomes corrupted by an I/O error, this may corrupt the
+data in an extracted file. Worse, it may corrupt the file's metadata,
+which may cause later parts of the archive to become misinterpreted. An
+tar-format archive contains a checksum that most likely will detect
+errors in the metadata, but it will not detect errors in the data.
+
+ If data corruption is a concern, you can compute and check your own
+checksums of an archive by using other programs, such as 'cksum'.
+
+ When attempting to recover from a read error or data corruption in an
+archive, you may need to skip past the questionable data and read the
+rest of the archive. This requires some expertise in the archive format
+and in other software tools.
+
+
+File: tar.info, Node: Race conditions, Prev: Data corruption and repair, Up: Reliability
+
+10.1.3 Race conditions
+----------------------
+
+If some other process is modifying the file system while 'tar' is
+reading or writing files, the result may well be inconsistent due to
+race conditions. For example, if another process creates some files in
+a directory while 'tar' is creating an archive containing the
+directory's files, 'tar' may see some of the files but not others, or it
+may see a file that is in the process of being created. The resulting
+archive may not be a snapshot of the file system at any point in time.
+If an application such as a database system depends on an accurate
+snapshot, restoring from the 'tar' archive of a live file system may
+therefore break that consistency and may break the application. The
+simplest way to avoid the consistency issues is to avoid making other
+changes to the file system while tar is reading it or writing it.
+
+ When creating an archive, several options are available to avoid race
+conditions. Some hosts have a way of snapshotting a file system, or of
+temporarily suspending all changes to a file system, by (say) suspending
+the only virtual machine that can modify a file system; if you use these
+facilities and have 'tar -c' read from a snapshot when creating an
+archive, you can avoid inconsistency problems. More drastically, before
+starting 'tar' you could suspend or shut down all processes other than
+'tar' that have access to the file system, or you could unmount the file
+system and then mount it read-only.
+
+ When extracting from an archive, one approach to avoid race
+conditions is to create a directory that no other process can write to,
+and extract into that.
+
+
+File: tar.info, Node: Security, Prev: Reliability, Up: Reliability and security
+
+10.2 Security
+=============
+
+In some cases 'tar' may be used in an adversarial situation, where an
+untrusted user is attempting to gain information about or modify
+otherwise-inaccessible files. Dealing with untrusted data (that is,
+data generated by an untrusted user) typically requires extra care,
+because even the smallest mistake in the use of 'tar' is more likely to
+be exploited by an adversary than by a race condition.
+
+* Menu:
+
+* Privacy::
+* Integrity::
+* Live untrusted data::
+* Security rules of thumb::
+
+
+File: tar.info, Node: Privacy, Next: Integrity, Up: Security
+
+10.2.1 Privacy
+--------------
+
+Standard privacy concerns apply when using 'tar'. For example, suppose
+you are archiving your home directory into a file '/archive/myhome.tar'.
+Any secret information in your home directory, such as your SSH secret
+keys, are copied faithfully into the archive. Therefore, if your home
+directory contains any file that should not be read by some other user,
+the archive itself should be not be readable by that user. And even if
+the archive's data are inaccessible to untrusted users, its metadata
+(such as size or last-modified date) may reveal some information about
+your home directory; if the metadata are intended to be private, the
+archive's parent directory should also be inaccessible to untrusted
+users.
+
+ One precaution is to create '/archive' so that it is not accessible
+to any user, unless that user also has permission to access all the
+files in your home directory.
+
+ Similarly, when extracting from an archive, take care that the
+permissions of the extracted files are not more generous than what you
+want. Even if the archive itself is readable only to you, files
+extracted from it have their own permissions that may differ.
+
+
+File: tar.info, Node: Integrity, Next: Live untrusted data, Prev: Privacy, Up: Security
+
+10.2.2 Integrity
+----------------
+
+When creating archives, take care that they are not writable by a
+untrusted user; otherwise, that user could modify the archive, and when
+you later extract from the archive you will get incorrect data.
+
+ When 'tar' extracts from an archive, by default it writes into files
+relative to the working directory. If the archive was generated by an
+untrusted user, that user therefore can write into any file under the
+working directory. If the working directory contains a symbolic link to
+another directory, the untrusted user can also write into any file under
+the referenced directory. When extracting from an untrusted archive, it
+is therefore good practice to create an empty directory and run 'tar' in
+that directory.
+
+ When extracting from two or more untrusted archives, each one should
+be extracted independently, into different empty directories.
+Otherwise, the first archive could create a symbolic link into an area
+outside the working directory, and the second one could follow the link
+and overwrite data that is not under the working directory. For
+example, when restoring from a series of incremental dumps, the archives
+should have been created by a trusted process, as otherwise the
+incremental restores might alter data outside the working directory.
+
+ If you use the '--absolute-names' ('-P') option when extracting,
+'tar' respects any file names in the archive, even file names that begin
+with '/' or contain '..'. As this lets the archive overwrite any file
+in your system that you can write, the '--absolute-names' ('-P') option
+should be used only for trusted archives.
+
+ Conversely, with the '--keep-old-files' ('-k') and '--skip-old-files'
+options, 'tar' refuses to replace existing files when extracting. The
+difference between the two options is that the former treats existing
+files as errors whereas the latter just silently ignores them.
+
+ Finally, with the '--no-overwrite-dir' option, 'tar' refuses to
+replace the permissions or ownership of already-existing directories.
+These options may help when extracting from untrusted archives.
+
+
+File: tar.info, Node: Live untrusted data, Next: Security rules of thumb, Prev: Integrity, Up: Security
+
+10.2.3 Dealing with Live Untrusted Data
+---------------------------------------
+
+Extra care is required when creating from or extracting into a file
+system that is accessible to untrusted users. For example, superusers
+who invoke 'tar' must be wary about its actions being hijacked by an
+adversary who is reading or writing the file system at the same time
+that 'tar' is operating.
+
+ When creating an archive from a live file system, 'tar' is vulnerable
+to denial-of-service attacks. For example, an adversarial user could
+create the illusion of an indefinitely-deep directory hierarchy
+'d/e/f/g/...' by creating directories one step ahead of 'tar', or the
+illusion of an indefinitely-long file by creating a sparse file but
+arranging for blocks to be allocated just before 'tar' reads them.
+There is no easy way for 'tar' to distinguish these scenarios from
+legitimate uses, so you may need to monitor 'tar', just as you'd need to
+monitor any other system service, to detect such attacks.
+
+ While a superuser is extracting from an archive into a live file
+system, an untrusted user might replace a directory with a symbolic
+link, in hopes that 'tar' will follow the symbolic link and extract data
+into files that the untrusted user does not have access to. Even if the
+archive was generated by the superuser, it may contain a file such as
+'d/etc/passwd' that the untrusted user earlier created in order to break
+in; if the untrusted user replaces the directory 'd/etc' with a symbolic
+link to '/etc' while 'tar' is running, 'tar' will overwrite
+'/etc/passwd'. This attack can be prevented by extracting into a
+directory that is inaccessible to untrusted users.
+
+ Similar attacks via symbolic links are also possible when creating an
+archive, if the untrusted user can modify an ancestor of a top-level
+argument of 'tar'. For example, an untrusted user that can modify
+'/home/eve' can hijack a running instance of 'tar -cf -
+/home/eve/Documents/yesterday' by replacing '/home/eve/Documents' with a
+symbolic link to some other location. Attacks like these can be
+prevented by making sure that untrusted users cannot modify any files
+that are top-level arguments to 'tar', or any ancestor directories of
+these files.
+
+
+File: tar.info, Node: Security rules of thumb, Prev: Live untrusted data, Up: Security
+
+10.2.4 Security Rules of Thumb
+------------------------------
+
+This section briefly summarizes rules of thumb for avoiding security
+pitfalls.
+
+ * Protect archives at least as much as you protect any of the files
+ being archived.
+
+ * Extract from an untrusted archive only into an otherwise-empty
+ directory. This directory and its parent should be accessible only
+ to trusted users. For example:
+
+ $ chmod go-rwx .
+ $ mkdir -m go-rwx dir
+ $ cd dir
+ $ tar -xvf /archives/got-it-off-the-net.tar.gz
+
+ As a corollary, do not do an incremental restore from an untrusted
+ archive.
+
+ * Do not let untrusted users access files extracted from untrusted
+ archives without checking first for problems such as setuid
+ programs.
+
+ * Do not let untrusted users modify directories that are ancestors of
+ top-level arguments of 'tar'. For example, while you are executing
+ 'tar -cf /archive/u-home.tar /u/home', do not let an untrusted user
+ modify '/', '/archive', or '/u'.
+
+ * Pay attention to the diagnostics and exit status of 'tar'.
+
+ * When archiving live file systems, monitor running instances of
+ 'tar' to detect denial-of-service attacks.
+
+ * Avoid unusual options such as '--absolute-names' ('-P'),
+ '--dereference' ('-h'), '--overwrite', '--recursive-unlink', and
+ '--remove-files' unless you understand their security implications.
+
+
+File: tar.info, Node: Changes, Next: Configuring Help Summary, Prev: Reliability and security, Up: Top
+
+Appendix A Changes
+******************
+
+This appendix lists some important user-visible changes between version
+GNU 'tar' 1.29 and previous versions. An up-to-date version of this
+document is available at the GNU 'tar' documentation page
+(http://www.gnu.org/software/tar/manual/changes.html).
+
+Use of globbing patterns when listing and extracting.
+
+ Previous versions of GNU tar assumed shell-style globbing when
+ extracting from or listing an archive. For example:
+
+ $ tar xf foo.tar '*.c'
+
+ would extract all files whose names end in '.c'. This behavior was
+ not documented and was incompatible with traditional tar
+ implementations. Therefore, starting from version 1.15.91, GNU tar
+ no longer uses globbing by default. For example, the above
+ invocation is now interpreted as a request to extract from the
+ archive the file named '*.c'.
+
+ To facilitate transition to the new behavior for those users who
+ got used to the previous incorrect one, 'tar' will print a warning
+ if it finds out that a requested member was not found in the
+ archive and its name looks like a globbing pattern. For example:
+
+ $ tar xf foo.tar '*.c'
+ tar: Pattern matching characters used in file names. Please,
+ tar: use --wildcards to enable pattern matching, or --no-wildcards to
+ tar: suppress this warning.
+ tar: *.c: Not found in archive
+ tar: Error exit delayed from previous errors
+
+ To treat member names as globbing patterns, use the '--wildcards'
+ option. If you want to tar to mimic the behavior of versions prior
+ to 1.15.91, add this option to your 'TAR_OPTIONS' variable.
+
+ *Note wildcards::, for the detailed discussion of the use of
+ globbing patterns by GNU 'tar'.
+
+Use of short option '-o'.
+
+ Earlier versions of GNU 'tar' understood '-o' command line option
+ as a synonym for '--old-archive'.
+
+ GNU 'tar' starting from version 1.13.90 understands this option as
+ a synonym for '--no-same-owner'. This is compatible with UNIX98
+ 'tar' implementations.
+
+ However, to facilitate transition, '-o' option retains its old
+ semantics when it is used with one of archive-creation commands.
+ Users are encouraged to use '--format=oldgnu' instead.
+
+ It is especially important, since versions of GNU Automake up to
+ and including 1.8.4 invoke tar with this option to produce
+ distribution tarballs. *Note v7: Formats, for the detailed
+ discussion of this issue and its implications.
+
+ *Note tar-formats: (automake)Options, for a description on how to
+ use various archive formats with 'automake'.
+
+ Future versions of GNU 'tar' will understand '-o' only as a synonym
+ for '--no-same-owner'.
+
+Use of short option '-l'
+
+ Earlier versions of GNU 'tar' understood '-l' option as a synonym
+ for '--one-file-system'. Since such usage contradicted to UNIX98
+ specification and harmed compatibility with other implementations,
+ it was declared deprecated in version 1.14. However, to facilitate
+ transition to its new semantics, it was supported by versions 1.15
+ and 1.15.90. The present use of '-l' as a short variant of
+ '--check-links' was introduced in version 1.15.91.
+
+Use of options '--portability' and '--old-archive'
+
+ These options are deprecated. Please use '--format=v7' instead.
+
+Use of option '--posix'
+
+ This option is deprecated. Please use '--format=posix' instead.
+
+
+File: tar.info, Node: Configuring Help Summary, Next: Fixing Snapshot Files, Prev: Changes, Up: Top
+
+Appendix B Configuring Help Summary
+***********************************
+
+Running 'tar --help' displays the short 'tar' option summary (*note
+help::). This summary is organized by "groups" of semantically close
+options. The options within each group are printed in the following
+order: a short option, eventually followed by a list of corresponding
+long option names, followed by a short description of the option. For
+example, here is an excerpt from the actual 'tar --help' output:
+
+ Main operation mode:
+
+ -A, --catenate, --concatenate append tar files to an archive
+ -c, --create create a new archive
+ -d, --diff, --compare find differences between archive and
+ file system
+ --delete delete from the archive
+
+ The exact visual representation of the help output is configurable
+via 'ARGP_HELP_FMT' environment variable. The value of this variable is
+a comma-separated list of "format variable" assignments. There are two
+kinds of format variables. An "offset variable" keeps the offset of
+some part of help output text from the leftmost column on the screen. A
+"boolean" variable is a flag that toggles some output feature on or off.
+Depending on the type of the corresponding variable, there are two kinds
+of assignments:
+
+Offset assignment
+
+ The assignment to an offset variable has the following syntax:
+
+ VARIABLE=VALUE
+
+ where VARIABLE is the variable name, and VALUE is a numeric value
+ to be assigned to the variable.
+
+Boolean assignment
+
+ To assign 'true' value to a variable, simply put this variable
+ name. To assign 'false' value, prefix the variable name with
+ 'no-'. For example:
+
+ # Assign true value:
+ dup-args
+ # Assign false value:
+ no-dup-args
+
+ Following variables are declared:
+
+ -- Help Output: boolean dup-args
+ If true, arguments for an option are shown with both short and long
+ options, even when a given option has both forms, for example:
+
+ -f ARCHIVE, --file=ARCHIVE use archive file or device ARCHIVE
+
+ If false, then if an option has both short and long forms, the
+ argument is only shown with the long one, for example:
+
+ -f, --file=ARCHIVE use archive file or device ARCHIVE
+
+ and a message indicating that the argument is applicable to both
+ forms is printed below the options. This message can be disabled
+ using 'dup-args-note' (see below).
+
+ The default is false.
+
+ -- Help Output: boolean dup-args-note
+ If this variable is true, which is the default, the following
+ notice is displayed at the end of the help output:
+
+ Mandatory or optional arguments to long options are also
+ mandatory or optional for any corresponding short options.
+
+ Setting 'no-dup-args-note' inhibits this message. Normally, only
+ one of variables 'dup-args' or 'dup-args-note' should be set.
+
+ -- Help Output: offset short-opt-col
+ Column in which short options start. Default is 2.
+
+ $ tar --help|grep ARCHIVE
+ -f, --file=ARCHIVE use archive file or device ARCHIVE
+ $ ARGP_HELP_FMT=short-opt-col=6 tar --help|grep ARCHIVE
+ -f, --file=ARCHIVE use archive file or device ARCHIVE
+
+ -- Help Output: offset long-opt-col
+ Column in which long options start. Default is 6. For example:
+
+ $ tar --help|grep ARCHIVE
+ -f, --file=ARCHIVE use archive file or device ARCHIVE
+ $ ARGP_HELP_FMT=long-opt-col=16 tar --help|grep ARCHIVE
+ -f, --file=ARCHIVE use archive file or device ARCHIVE
+
+ -- Help Output: offset doc-opt-col
+ Column in which "doc options" start. A doc option isn't actually
+ an option, but rather an arbitrary piece of documentation that is
+ displayed in much the same manner as the options. For example, in
+ the description of '--format' option:
+
+ -H, --format=FORMAT create archive of the given format.
+
+ FORMAT is one of the following:
+
+ gnu GNU tar 1.13.x format
+ oldgnu GNU format as per tar <= 1.12
+ pax POSIX 1003.1-2001 (pax) format
+ posix same as pax
+ ustar POSIX 1003.1-1988 (ustar) format
+ v7 old V7 tar format
+
+ the format names are doc options. Thus, if you set
+ 'ARGP_HELP_FMT=doc-opt-col=6' the above part of the help output
+ will look as follows:
+
+ -H, --format=FORMAT create archive of the given format.
+
+ FORMAT is one of the following:
+
+ gnu GNU tar 1.13.x format
+ oldgnu GNU format as per tar <= 1.12
+ pax POSIX 1003.1-2001 (pax) format
+ posix same as pax
+ ustar POSIX 1003.1-1988 (ustar) format
+ v7 old V7 tar format
+
+ -- Help Output: offset opt-doc-col
+ Column in which option description starts. Default is 29.
+
+ $ tar --help|grep ARCHIVE
+ -f, --file=ARCHIVE use archive file or device ARCHIVE
+ $ ARGP_HELP_FMT=opt-doc-col=19 tar --help|grep ARCHIVE
+ -f, --file=ARCHIVE use archive file or device ARCHIVE
+ $ ARGP_HELP_FMT=opt-doc-col=9 tar --help|grep ARCHIVE
+ -f, --file=ARCHIVE
+ use archive file or device ARCHIVE
+
+ Notice, that the description starts on a separate line if
+ 'opt-doc-col' value is too small.
+
+ -- Help Output: offset header-col
+ Column in which "group headers" are printed. A group header is a
+ descriptive text preceding an option group. For example, in the
+ following text:
+
+ Main operation mode:
+
+ -A, --catenate, --concatenate append tar files to
+ an archive
+ -c, --create create a new archive
+ 'Main operation mode:' is the group header.
+
+ The default value is 1.
+
+ -- Help Output: offset usage-indent
+ Indentation of wrapped usage lines. Affects '--usage' output.
+ Default is 12.
+
+ -- Help Output: offset rmargin
+ Right margin of the text output. Used for wrapping.
+
+
+File: tar.info, Node: Fixing Snapshot Files, Next: Tar Internals, Prev: Configuring Help Summary, Up: Top
+
+Appendix C Fixing Snapshot Files
+********************************
+
+Various situations can cause device numbers to change: upgrading your
+kernel version, reconfiguring your hardware, loading kernel modules in a
+different order, using virtual volumes that are assembled dynamically
+(such as with LVM or RAID), hot-plugging drives (e.g. external USB or
+Firewire drives), etc. In the majority of cases this change is
+unnoticed by the users. However, it influences 'tar' incremental
+backups: the device number is stored in tar snapshot files (*note
+Snapshot Files::) and is used to determine whether the file has changed
+since the last backup. If the device numbers change for some reason, by
+default the next backup you run will be a full backup.
+
+ To minimize the impact in these cases, GNU 'tar' comes with the
+'tar-snapshot-edit' utility for inspecting and updating device numbers
+in snapshot files. (The utility, written by Dustin J. Mitchell, is also
+available from the GNU 'tar' home page
+(http://www.gnu.org/software/tar/utils/tar-snapshot-edit.html).)
+
+ To obtain a summary of the device numbers found in the snapshot file,
+run
+
+ $ tar-snapshot-edit SNAPFILE
+
+where SNAPFILE is the name of the snapshot file (you can supply as many
+files as you wish in a single command line). You can then compare the
+numbers across snapshot files, or against those currently in use on the
+live filesystem (using 'ls -l' or 'stat').
+
+ Assuming the device numbers have indeed changed, it's often possible
+to simply tell GNU 'tar' to ignore the device number when processing the
+incremental snapshot files for these backups, using the
+'--no-check-device' option (*note device numbers::).
+
+ Alternatively, you can use the 'tar-edit-snapshot' script's '-r'
+option to update all occurrences of the given device number in the
+snapshot file(s). It takes a single argument of the form
+'OLDDEV-NEWDEV', where OLDDEV is the device number used in the snapshot
+file, and NEWDEV is the corresponding new device number. Both numbers
+may be specified in hex (e.g., '0xfe01'), decimal (e.g., '65025'), or as
+a major:minor number pair (e.g., '254:1'). To change several device
+numbers at once, specify them in a single comma-separated list, as in
+'-r 0x3060-0x4500,0x307-0x4600'.
+
+ Before updating the snapshot file, it is a good idea to create a
+backup copy of it. This is accomplished by '-b' option. The name of
+the backup file is obtained by appending '~' to the original file name.
+
+ An example session:
+ $ tar-snapshot-edit root_snap.0 boot_snap.0
+ File: root_snap.0
+ Detected snapshot file version: 2
+
+ Device 0x0000 occurs 1 times.
+ Device 0x0003 occurs 1 times.
+ Device 0x0005 occurs 1 times.
+ Device 0x0013 occurs 1 times.
+ Device 0x6801 occurs 1 times.
+ Device 0x6803 occurs 6626 times.
+ Device 0xfb00 occurs 1 times.
+
+ File: boot_snap.0
+ Detected snapshot file version: 2
+
+ Device 0x6801 occurs 3 times.
+ $ tar-snapshot-edit -b -r 0x6801-0x6901,0x6803-0x6903 root_snap.0 boot_snap.0
+ File: root_snap.0
+ Detected snapshot file version: 2
+
+ Updated 6627 records.
+
+ File: boot_snap.0
+ Detected snapshot file version: 2
+
+ Updated 3 records.
+
+
+File: tar.info, Node: Tar Internals, Next: Genfile, Prev: Fixing Snapshot Files, Up: Top
+
+Appendix D Tar Internals
+************************
+
+* Menu:
+
+* Standard:: Basic Tar Format
+* Extensions:: GNU Extensions to the Archive Format
+* Sparse Formats:: Storing Sparse Files
+* Snapshot Files::
+* Dumpdir::
+
+
+File: tar.info, Node: Standard, Next: Extensions, Up: Tar Internals
+
+Basic Tar Format
+================
+
+ _(This message will disappear, once this node revised.)_
+
+ While an archive may contain many files, the archive itself is a
+single ordinary file. Like any other file, an archive file can be
+written to a storage device such as a tape or disk, sent through a pipe
+or over a network, saved on the active file system, or even stored in
+another archive. An archive file is not easy to read or manipulate
+without using the 'tar' utility or Tar mode in GNU Emacs.
+
+ Physically, an archive consists of a series of file entries
+terminated by an end-of-archive entry, which consists of two 512 blocks
+of zero bytes. A file entry usually describes one of the files in the
+archive (an "archive member"), and consists of a file header and the
+contents of the file. File headers contain file names and statistics,
+checksum information which 'tar' uses to detect file corruption, and
+information about file types.
+
+ Archives are permitted to have more than one member with the same
+member name. One way this situation can occur is if more than one
+version of a file has been stored in the archive. For information about
+adding new versions of a file to an archive, see *note update::.
+
+ In addition to entries describing archive members, an archive may
+contain entries which 'tar' itself uses to store information. *Note
+label::, for an example of such an archive entry.
+
+ A 'tar' archive file contains a series of blocks. Each block
+contains 'BLOCKSIZE' bytes. 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 block which describes
+the file, followed by zero or more blocks which give the contents of the
+file. At the end of the archive file there are two 512-byte blocks
+filled with binary zeros as an end-of-file marker. A reasonable system
+should write such end-of-file marker at the end of an archive, but must
+not assume that such a block exists when reading an archive. In
+particular GNU 'tar' always issues a warning if it does not encounter
+it.
+
+ The blocks may be "blocked" for physical I/O operations. Each record
+of N blocks (where N is set by the '--blocking-factor=512-SIZE' ('-b
+512-SIZE') option to 'tar') is written with a single 'write ()'
+operation. On magnetic tapes, the result of such a write is a single
+record. When writing an archive, the last record of blocks should be
+written at the full size, with blocks after the zero block containing
+all zeros. When reading an archive, a reasonable system should properly
+handle an archive whose last record is shorter than the rest, or which
+contains garbage records after a zero block.
+
+ The header block is defined in C as follows. In the GNU 'tar'
+distribution, this is part of file 'src/tar.h':
+
+
+ /* tar Header Block, from POSIX 1003.1-1990. */
+
+ /* POSIX header. */
+
+ struct posix_header
+ { /* byte offset */
+ char name[100]; /* 0 */
+ char mode[8]; /* 100 */
+ char uid[8]; /* 108 */
+ char gid[8]; /* 116 */
+ char size[12]; /* 124 */
+ char mtime[12]; /* 136 */
+ char chksum[8]; /* 148 */
+ char typeflag; /* 156 */
+ char linkname[100]; /* 157 */
+ char magic[6]; /* 257 */
+ char version[2]; /* 263 */
+ char uname[32]; /* 265 */
+ char gname[32]; /* 297 */
+ char devmajor[8]; /* 329 */
+ char devminor[8]; /* 337 */
+ char prefix[155]; /* 345 */
+ /* 500 */
+ };
+
+ #define TMAGIC "ustar" /* ustar and a null */
+ #define TMAGLEN 6
+ #define TVERSION "00" /* 00 and no null */
+ #define TVERSLEN 2
+
+ /* Values used in typeflag field. */
+ #define REGTYPE '0' /* regular file */
+ #define AREGTYPE '\0' /* regular file */
+ #define LNKTYPE '1' /* link */
+ #define SYMTYPE '2' /* reserved */
+ #define CHRTYPE '3' /* character special */
+ #define BLKTYPE '4' /* block special */
+ #define DIRTYPE '5' /* directory */
+ #define FIFOTYPE '6' /* FIFO special */
+ #define CONTTYPE '7' /* reserved */
+
+ #define XHDTYPE 'x' /* Extended header referring to the
+ next file in the archive */
+ #define XGLTYPE 'g' /* Global extended header */
+
+ /* 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 /* reserved */
+ /* 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 */
+
+ /* tar Header Block, GNU extensions. */
+
+ /* In GNU tar, SYMTYPE is for to symbolic links, and CONTTYPE is for
+ contiguous files, so maybe disobeying the "reserved" comment in POSIX
+ header description. I suspect these were meant to be used this way, and
+ should not have really been "reserved" in the published standards. */
+
+ /* *BEWARE* *BEWARE* *BEWARE* that the following information is still
+ boiling, and may change. Even if the OLDGNU format description should be
+ accurate, the so-called GNU format is not yet fully decided. It is
+ surely meant to use only extensions allowed by POSIX, but the sketch
+ below repeats some ugliness from the OLDGNU format, which should rather
+ go away. Sparse files should be saved in such a way that they do *not*
+ require two passes at archive creation time. Huge files get some POSIX
+ fields to overflow, alternate solutions have to be sought for this. */
+
+ /* Descriptor for a single file hole. */
+
+ struct sparse
+ { /* byte offset */
+ char offset[12]; /* 0 */
+ char numbytes[12]; /* 12 */
+ /* 24 */
+ };
+
+ /* Sparse files are not supported in POSIX ustar format. For sparse files
+ with a POSIX header, a GNU extra header is provided which holds overall
+ sparse information and a few sparse descriptors. When an old GNU header
+ replaces both the POSIX header and the GNU extra header, it holds some
+ sparse descriptors too. Whether POSIX or not, if more sparse descriptors
+ are still needed, they are put into as many successive sparse headers as
+ necessary. The following constants tell how many sparse descriptors fit
+ in each kind of header able to hold them. */
+
+ #define SPARSES_IN_EXTRA_HEADER 16
+ #define SPARSES_IN_OLDGNU_HEADER 4
+ #define SPARSES_IN_SPARSE_HEADER 21
+
+ /* Extension header for sparse files, used immediately after the GNU extra
+ header, and used only if all sparse information cannot fit into that
+ extra header. There might even be many such extension headers, one after
+ the other, until all sparse information has been recorded. */
+
+ struct sparse_header
+ { /* byte offset */
+ struct sparse sp[SPARSES_IN_SPARSE_HEADER];
+ /* 0 */
+ char isextended; /* 504 */
+ /* 505 */
+ };
+
+ /* The old GNU format header conflicts with POSIX format in such a way that
+ POSIX archives may fool old GNU tar's, and POSIX tar's might well be
+ fooled by old GNU tar archives. An old GNU format header uses the space
+ used by the prefix field in a POSIX header, and cumulates information
+ normally found in a GNU extra header. With an old GNU tar header, we
+ never see any POSIX header nor GNU extra header. Supplementary sparse
+ headers are allowed, however. */
+
+ struct oldgnu_header
+ { /* byte offset */
+ char unused_pad1[345]; /* 0 */
+ char atime[12]; /* 345 Incr. archive: atime of the file */
+ char ctime[12]; /* 357 Incr. archive: ctime of the file */
+ char offset[12]; /* 369 Multivolume archive: the offset of
+ the start of this volume */
+ char longnames[4]; /* 381 Not used */
+ char unused_pad2; /* 385 */
+ struct sparse sp[SPARSES_IN_OLDGNU_HEADER];
+ /* 386 */
+ char isextended; /* 482 Sparse file: Extension sparse header
+ follows */
+ char realsize[12]; /* 483 Sparse file: Real size*/
+ /* 495 */
+ };
+
+ /* OLDGNU_MAGIC uses both magic and version fields, which are contiguous.
+ Found in an archive, it indicates an old GNU header format, which will be
+ hopefully become obsolescent. With OLDGNU_MAGIC, uname and gname are
+ valid, though the header is not truly POSIX conforming. */
+ #define OLDGNU_MAGIC "ustar " /* 7 chars and a null */
+
+ /* The standards committee allows only capital A through capital Z for
+ user-defined expansion. Other letters in use include:
+
+ 'A' Solaris Access Control List
+ 'E' Solaris Extended Attribute File
+ 'I' Inode only, as in 'star'
+ 'N' Obsolete GNU tar, for file names that do not fit into the main header.
+ 'X' POSIX 1003.1-2001 eXtended (VU version) */
+
+ /* This is a dir entry that contains the names of files that were in the
+ dir at the time the dump was made. */
+ #define GNUTYPE_DUMPDIR 'D'
+
+ /* Identifies the *next* file on the tape as having a long linkname. */
+ #define GNUTYPE_LONGLINK 'K'
+
+ /* Identifies the *next* file on the tape as having a long name. */
+ #define GNUTYPE_LONGNAME 'L'
+
+ /* This is the continuation of a file that began on another volume. */
+ #define GNUTYPE_MULTIVOL 'M'
+
+ /* This is for sparse files. */
+ #define GNUTYPE_SPARSE 'S'
+
+ /* This file is a tape/volume header. Ignore it on extraction. */
+ #define GNUTYPE_VOLHDR 'V'
+
+ /* Solaris extended header */
+ #define SOLARIS_XHDTYPE 'X'
+
+ /* Jo"rg Schilling star header */
+
+ struct star_header
+ { /* byte offset */
+ char name[100]; /* 0 */
+ char mode[8]; /* 100 */
+ char uid[8]; /* 108 */
+ char gid[8]; /* 116 */
+ char size[12]; /* 124 */
+ char mtime[12]; /* 136 */
+ char chksum[8]; /* 148 */
+ char typeflag; /* 156 */
+ char linkname[100]; /* 157 */
+ char magic[6]; /* 257 */
+ char version[2]; /* 263 */
+ char uname[32]; /* 265 */
+ char gname[32]; /* 297 */
+ char devmajor[8]; /* 329 */
+ char devminor[8]; /* 337 */
+ char prefix[131]; /* 345 */
+ char atime[12]; /* 476 */
+ char ctime[12]; /* 488 */
+ /* 500 */
+ };
+
+ #define SPARSES_IN_STAR_HEADER 4
+ #define SPARSES_IN_STAR_EXT_HEADER 21
+
+ struct star_in_header
+ {
+ char fill[345]; /* 0 Everything that is before t_prefix */
+ char prefix[1]; /* 345 t_name prefix */
+ char fill2; /* 346 */
+ char fill3[8]; /* 347 */
+ char isextended; /* 355 */
+ struct sparse sp[SPARSES_IN_STAR_HEADER]; /* 356 */
+ char realsize[12]; /* 452 Actual size of the file */
+ char offset[12]; /* 464 Offset of multivolume contents */
+ char atime[12]; /* 476 */
+ char ctime[12]; /* 488 */
+ char mfill[8]; /* 500 */
+ char xmagic[4]; /* 508 "tar" */
+ };
+
+ struct star_ext_header
+ {
+ struct sparse sp[SPARSES_IN_STAR_EXT_HEADER];
+ char isextended;
+ };
+
+
+ All characters in header blocks are represented by 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 block of
+each file) are not translated in any way and are not constrained to
+represent characters in any character set. The 'tar' format does not
+distinguish text files from binary files, and no translation of file
+contents is performed.
+
+ The '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 minus 1
+digits, and a null.
+
+ The 'name' field is the file name of the file, with directory names
+(if any) preceding the file name, separated by slashes.
+
+ The 'mode' field provides nine bits specifying file permissions and
+three bits to specify the Set UID, Set GID, and Save Text ("sticky")
+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 or updating an archive; e.g., the group permission could be
+copied from the _other_ permission.
+
+ The 'uid' and 'gid' fields are the numeric user and group ID of the
+file owners, respectively. If the operating system does not support
+numeric user or group IDs, these fields should be ignored.
+
+ 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 data 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's contents were modified, represented as an
+integer number of seconds since January 1, 1970, 00:00 Coordinated
+Universal Time.
+
+ The 'chksum' field is the ASCII representation of the octal value of
+the simple sum of all bytes in the header block. Each 8-bit byte in the
+header is added to an unsigned integer, initialized 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.
+
+ The 'atime' and 'ctime' fields are used in making incremental
+backups; they store, respectively, the particular file's access and
+status change times.
+
+ The 'offset' is used by the '--multi-volume' ('-M') option, when
+making a multi-volume archive. The offset is number of bytes into the
+file that we need to restart at to continue the file on the next tape,
+i.e., where we store the location that a continued file is continued at.
+
+ The following fields were added to deal with sparse files. A file is
+"sparse" if it takes in unallocated blocks which end up being
+represented as zeros, i.e., no useful data. A test to see if a file is
+sparse is to look at the number blocks allocated for it versus the
+number of characters in the file; if there are fewer blocks allocated
+for the file than would normally be allocated for a file of that size,
+then the file is sparse. This is the method 'tar' uses to detect a
+sparse file, and once such a file is detected, it is treated differently
+from non-sparse files.
+
+ Sparse files are often 'dbm' files, or other database-type files
+which have data at some points and emptiness in the greater part of the
+file. Such files can appear to be very large when an 'ls -l' is done on
+them, when in truth, there may be a very small amount of important data
+contained in the file. It is thus undesirable to have 'tar' think that
+it must back up this entire file, as great quantities of room are wasted
+on empty blocks, which can lead to running out of room on a tape far
+earlier than is necessary. Thus, sparse files are dealt with so that
+these empty blocks are not written to the tape. Instead, what is
+written to the tape is a description, of sorts, of the sparse file:
+where the holes are, how big the holes are, and how much data is found
+at the end of the hole. This way, the file takes up potentially far
+less room on the tape, and when the file is extracted later on, it will
+look exactly the way it looked beforehand. The following is a
+description of the fields used to handle a sparse file:
+
+ The 'sp' is an array of 'struct sparse'. Each 'struct sparse'
+contains two 12-character strings which represent an offset into the
+file and a number of bytes to be written at that offset. The offset is
+absolute, and not relative to the offset in preceding array element.
+
+ The header can hold four of these 'struct sparse' at the moment; if
+more are needed, they are not stored in the header.
+
+ The 'isextended' flag is set when an 'extended_header' is needed to
+deal with a file. Note that this means that this flag can only be set
+when dealing with a sparse file, and it is only set in the event that
+the description of the file will not fit in the allotted room for sparse
+structures in the header. In other words, an extended_header is needed.
+
+ The 'extended_header' structure is used for sparse files which need
+more sparse structures than can fit in the header. The header can fit 4
+such structures; if more are needed, the flag 'isextended' gets set and
+the next block is an 'extended_header'.
+
+ Each 'extended_header' structure contains an array of 21 sparse
+structures, along with a similar 'isextended' flag that the header had.
+There can be an indeterminate number of such 'extended_header's to
+describe a sparse file.
+
+'REGTYPE'
+'AREGTYPE'
+ These flags represent a regular file. In order to be compatible
+ with older versions of 'tar', a 'typeflag' value of 'AREGTYPE'
+ should be silently recognized as a regular file. New archives
+ should be created using 'REGTYPE'. Also, for backward
+ compatibility, 'tar' treats a regular file whose name ends with a
+ slash as a directory.
+
+'LNKTYPE'
+ This flag 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.
+
+'SYMTYPE'
+ This represents a symbolic link to another file. The linked-to
+ name is specified in the 'linkname' field with a trailing null.
+
+'CHRTYPE'
+'BLKTYPE'
+ These represent character special files and block special files
+ respectively. In this case the 'devmajor' and 'devminor' 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.
+
+'DIRTYPE'
+ This flag 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 directory 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.
+
+'FIFOTYPE'
+ This specifies a FIFO special file. Note that the archiving of a
+ FIFO file archives the existence of this file and not its contents.
+
+'CONTTYPE'
+ This 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 contiguous allocation should silently treat this
+ type as a normal file.
+
+'A' ... 'Z'
+ These are reserved for custom implementations. Some of these are
+ used in the GNU modified format, as described below.
+
+ Other values are reserved for specification in future revisions 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', the 'uname' and
+'gname' fields will contain the ASCII representation of the owner and
+group of the file respectively. If found, the user and group IDs are
+used rather than the values in the 'uid' and 'gid' fields.
+
+ For references, see ISO/IEC 9945-1:1990 or IEEE Std 1003.1-1990,
+pages 169-173 (section 10.1) for 'Archive/Interchange File Format'; and
+IEEE Std 1003.2-1992, pages 380-388 (section 4.48) and pages 936-940
+(section E.4.48) for 'pax - Portable archive interchange'.
+
+
+File: tar.info, Node: Extensions, Next: Sparse Formats, Prev: Standard, Up: Tar Internals
+
+GNU Extensions to the Archive Format
+====================================
+
+ _(This message will disappear, once this node revised.)_
+
+ The GNU format uses additional file types to describe new types of
+files in an archive. These are listed below.
+
+'GNUTYPE_DUMPDIR'
+''D''
+ This represents a directory and a list of files created by the
+ '--incremental' ('-G') option. The 'size' field gives the total
+ size of the associated list of files. Each file name is preceded
+ by either a 'Y' (the file should be in this archive) or an 'N'.
+ (The file is a directory, or is not stored in the archive.) Each
+ file name is terminated by a null. There is an additional null
+ after the last file name.
+
+'GNUTYPE_MULTIVOL'
+''M''
+ This represents a file continued from another volume of a
+ multi-volume archive created with the '--multi-volume' ('-M')
+ option. The original type of the file is not given here. The
+ 'size' field gives the maximum size of this piece of the file
+ (assuming the volume does not end before the file is written out).
+ The 'offset' field gives the offset from the beginning of the file
+ where this part of the file begins. Thus 'size' plus 'offset'
+ should equal the original size of the file.
+
+'GNUTYPE_SPARSE'
+''S''
+ This flag indicates that we are dealing with a sparse file. Note
+ that archiving a sparse file requires special operations to find
+ holes in the file, which mark the positions of these holes, along
+ with the number of bytes of data to be found after the hole.
+
+'GNUTYPE_VOLHDR'
+''V''
+ This file type is used to mark the volume header that was given
+ with the '--label=ARCHIVE-LABEL' ('-V ARCHIVE-LABEL') option when
+ the archive was created. The 'name' field contains the 'name'
+ given after the '--label=ARCHIVE-LABEL' ('-V ARCHIVE-LABEL')
+ option. The 'size' field is zero. Only the first file in each
+ volume of an archive should have this type.
+
+ You may have trouble reading a GNU format archive on a non-GNU system
+if the options '--incremental' ('-G'), '--multi-volume' ('-M'),
+'--sparse' ('-S'), or '--label=ARCHIVE-LABEL' ('-V ARCHIVE-LABEL') were
+used when writing the archive. In general, if 'tar' does not use the
+GNU-added fields of the header, other versions of 'tar' should be able
+to read the archive. Otherwise, the 'tar' program will give an error,
+the most likely one being a checksum error.
+
+
+File: tar.info, Node: Sparse Formats, Next: Snapshot Files, Prev: Extensions, Up: Tar Internals
+
+Storing Sparse Files
+====================
+
+The notion of sparse file, and the ways of handling it from the point of
+view of GNU 'tar' user have been described in detail in *note sparse::.
+This chapter describes the internal format GNU 'tar' uses to store such
+files.
+
+ The support for sparse files in GNU 'tar' has a long history. The
+earliest version featuring this support that I was able to find was
+1.09, released in November, 1990. The format introduced back then is
+called "old GNU" sparse format and in spite of the fact that its design
+contained many flaws, it was the only format GNU 'tar' supported until
+version 1.14 (May, 2004), which introduced initial support for sparse
+archives in PAX archives (*note posix::). This format was not free from
+design flaws, either and it was subsequently improved in versions 1.15.2
+(November, 2005) and 1.15.92 (June, 2006).
+
+ In addition to GNU sparse format, GNU 'tar' is able to read and
+extract sparse files archived by 'star'.
+
+ The following subsections describe each format in detail.
+
+* Menu:
+
+* Old GNU Format::
+* PAX 0:: PAX Format, Versions 0.0 and 0.1
+* PAX 1:: PAX Format, Version 1.0
+
+
+File: tar.info, Node: Old GNU Format, Next: PAX 0, Up: Sparse Formats
+
+Old GNU Format
+--------------
+
+The format introduced in November 1990 (v. 1.09) was designed on top of
+standard 'ustar' headers in such an unfortunate way that some of its
+fields overwrote fields required by POSIX.
+
+ An old GNU sparse header is designated by type 'S' ('GNUTYPE_SPARSE')
+and has the following layout:
+
+Offset Size Name Data type Contents
+----------------------------------------------------------------------------
+0 345 N/A Not used.
+345 12 atime Number 'atime' of the file.
+357 12 ctime Number 'ctime' of the file .
+369 12 offset Number For multivolume archives:
+ the offset of the start of
+ this volume.
+381 4 N/A Not used.
+385 1 N/A Not used.
+386 96 sp 'sparse_header'(4 entries) File map.
+482 1 isextended Bool '1' if an extension sparse
+ header follows, '0'
+ otherwise.
+483 12 realsize Number Real size of the file.
+
+ Each of 'sparse_header' object at offset 386 describes a single data
+chunk. It has the following structure:
+
+Offset Size Data type Contents
+---------------------------------------------------------------------------
+0 12 Number Offset of the beginning of the chunk.
+12 12 Number Size of the chunk.
+
+ If the member contains more than four chunks, the 'isextended' field
+of the header has the value '1' and the main header is followed by one
+or more "extension headers". Each such header has the following
+structure:
+
+Offset Size Name Data type Contents
+----------------------------------------------------------------------------
+0 21 sp 'sparse_header'(21 entries) File map.
+504 1 isextended Bool '1' if an extension sparse
+ header follows, or '0'
+ otherwise.
+
+ A header with 'isextended=0' ends the map.
+
+
+File: tar.info, Node: PAX 0, Next: PAX 1, Prev: Old GNU Format, Up: Sparse Formats
+
+PAX Format, Versions 0.0 and 0.1
+--------------------------------
+
+There are two formats available in this branch. The version '0.0' is
+the initial version of sparse format used by 'tar' versions 1.14-1.15.1.
+The sparse file map is kept in extended ('x') PAX header variables:
+
+'GNU.sparse.size'
+ Real size of the stored file;
+
+'GNU.sparse.numblocks'
+ Number of blocks in the sparse map;
+
+'GNU.sparse.offset'
+ Offset of the data block;
+
+'GNU.sparse.numbytes'
+ Size of the data block.
+
+ The latter two variables repeat for each data block, so the overall
+structure is like this:
+
+ GNU.sparse.size=SIZE
+ GNU.sparse.numblocks=NUMBLOCKS
+ repeat NUMBLOCKS times
+ GNU.sparse.offset=OFFSET
+ GNU.sparse.numbytes=NUMBYTES
+ end repeat
+
+ This format presented the following two problems:
+
+ 1. Whereas the POSIX specification allows a variable to appear
+ multiple times in a header, it requires that only the last
+ occurrence be meaningful. Thus, multiple occurrences of
+ 'GNU.sparse.offset' and 'GNU.sparse.numbytes' are conflicting with
+ the POSIX specs.
+
+ 2. Attempting to extract such archives using a third-party's 'tar'
+ results in extraction of sparse files in _condensed form_. If the
+ 'tar' implementation in question does not support POSIX format, it
+ will also extract a file containing extension header attributes.
+ This file can be used to expand the file to its original state.
+ However, posix-aware 'tar's will usually ignore the unknown
+ variables, which makes restoring the file more difficult. *Note
+ Extraction of sparse members in v.0.0 format: extracting sparse
+ v.0.x, for the detailed description of how to restore such members
+ using non-GNU 'tar's.
+
+ GNU 'tar' 1.15.2 introduced sparse format version '0.1', which
+attempted to solve these problems. As its predecessor, this format
+stores sparse map in the extended POSIX header. It retains
+'GNU.sparse.size' and 'GNU.sparse.numblocks' variables, but instead of
+'GNU.sparse.offset'/'GNU.sparse.numbytes' pairs it uses a single
+variable:
+
+'GNU.sparse.map'
+ Map of non-null data chunks. It is a string consisting of
+ comma-separated values "OFFSET,SIZE[,OFFSET-1,SIZE-1...]"
+
+ To address the 2nd problem, the 'name' field in 'ustar' is replaced
+with a special name, constructed using the following pattern:
+
+ %d/GNUSparseFile.%p/%f
+
+ The real name of the sparse file is stored in the variable
+'GNU.sparse.name'. Thus, those 'tar' implementations that are not aware
+of GNU extensions will at least extract the files into separate
+directories, giving the user a possibility to expand it afterwards.
+*Note Extraction of sparse members in v.0.1 format: extracting sparse
+v.0.x, for the detailed description of how to restore such members using
+non-GNU 'tar's.
+
+ The resulting 'GNU.sparse.map' string can be _very_ long. Although
+POSIX does not impose any limit on the length of a 'x' header variable,
+this possibly can confuse some 'tar's.
+
+
+File: tar.info, Node: PAX 1, Prev: PAX 0, Up: Sparse Formats
+
+PAX Format, Version 1.0
+-----------------------
+
+The version '1.0' of sparse format was introduced with GNU 'tar'
+1.15.92. Its main objective was to make the resulting file extractable
+with little effort even by non-posix aware 'tar' implementations.
+Starting from this version, the extended header preceding a sparse
+member always contains the following variables that identify the format
+being used:
+
+'GNU.sparse.major'
+ Major version
+
+'GNU.sparse.minor'
+ Minor version
+
+ The 'name' field in 'ustar' header contains a special name,
+constructed using the following pattern:
+
+ %d/GNUSparseFile.%p/%f
+
+ The real name of the sparse file is stored in the variable
+'GNU.sparse.name'. The real size of the file is stored in the variable
+'GNU.sparse.realsize'.
+
+ The sparse map itself is stored in the file data block, preceding the
+actual file data. It consists of a series of octal numbers of arbitrary
+length, delimited by newlines. The map is padded with nulls to the
+nearest block boundary.
+
+ The first number gives the number of entries in the map. Following
+are map entries, each one consisting of two numbers giving the offset
+and size of the data block it describes.
+
+ The format is designed in such a way that non-posix aware 'tar's and
+'tar's not supporting 'GNU.sparse.*' keywords will extract each sparse
+file in its condensed form with the file map prepended and will place it
+into a separate directory. Then, using a simple program it would be
+possible to expand the file to its original form even without GNU 'tar'.
+*Note Sparse Recovery::, for the detailed information on how to extract
+sparse members without GNU 'tar'.
+
+
+File: tar.info, Node: Snapshot Files, Next: Dumpdir, Prev: Sparse Formats, Up: Tar Internals
+
+Format of the Incremental Snapshot Files
+========================================
+
+A "snapshot file" (or "directory file") is created during incremental
+backups (*note Incremental Dumps::). It contains the status of the file
+system at the time of the dump and is used to determine which files were
+modified since the last backup.
+
+ GNU 'tar' version 1.29 supports three snapshot file formats. The
+first format, called "format 0", is the one used by GNU 'tar' versions
+up to and including 1.15.1. The second format, called "format 1" is an
+extended version of this format, that contains more metadata and allows
+for further extensions. It was used by alpha release version 1.15.90.
+For alpha version 1.15.91 and stable releases version 1.16 up through
+1.29, the "format 2" is used.
+
+ GNU 'tar' is able to read all three formats, but will create
+snapshots only in format 2.
+
+ This appendix describes all three formats in detail.
+
+ 0. 'Format 0' snapshot file begins with a line containing a decimal
+ number that represents a UNIX timestamp of the beginning of the
+ last archivation. This line is followed by directory metadata
+ descriptions, one per line. Each description has the following
+ format:
+
+ [NFS]DEV INODE NAME
+
+ where:
+
+ NFS
+ A single plus character ('+'), if this directory is located on
+ an NFS-mounted partition, otherwise empty.
+
+ (That is, for non-NFS directories, the first character on the
+ description line contains the start of the DEV field.)
+
+ DEV
+ Device number of the directory;
+
+ INODE
+ I-node number of the directory;
+
+ NAME
+ Name of the directory. Any special characters (white-space,
+ backslashes, etc.) are quoted.
+
+ 1. 'Format 1' snapshot file begins with a line specifying the format
+ of the file. This line has the following structure:
+
+ 'GNU tar-'TAR-VERSION'-'INCR-FORMAT-VERSION
+
+ where TAR-VERSION is the version number of GNU 'tar' implementation
+ that created this snapshot, and INCR-FORMAT-VERSION is the version
+ number of the snapshot format (in this case '1').
+
+ Next line contains two decimal numbers, representing the time of
+ the last backup. First number is the number of seconds, the second
+ one is the number of nanoseconds, since the beginning of the epoch.
+
+ Lines that follow contain directory metadata, one line per
+ directory. Each line is formatted as follows:
+
+ [NFS]MTIME-SEC MTIME-NSEC DEV INODE NAME
+
+ where MTIME-SEC and MTIME-NSEC represent last modification time of
+ this directory with nanosecond precision; NFS, DEV, INODE and NAME
+ have the same meaning as with 'format 0'.
+
+ 2. 'Format 2' snapshot file begins with a format identifier, as
+ described for version 1, e.g.:
+
+ GNU tar-1.29-2
+
+ This line is followed by newline. Rest of file consists of
+ records, separated by null (ASCII 0) characters. Thus, in contrast
+ to the previous formats, format 2 snapshot is a binary file.
+
+ First two records are decimal integers, representing the time of
+ the last backup. First number is the number of seconds, the second
+ one is the number of nanoseconds, since the beginning of the epoch.
+ These are followed by arbitrary number of directory records.
+
+ Each "directory record" contains a set of metadata describing a
+ particular directory. Parts of a directory record are delimited
+ with ASCII 0 characters. The following table describes each part.
+ The "Number" type in this table stands for a decimal integer in
+ ASCII notation. (Negative values are preceded with a "-"
+ character, while positive values have no leading punctuation.)
+
+ Field Type Description
+ ---------------------------------------------------------------------------
+ nfs Character '1' if the directory is located on an
+ NFS-mounted partition, or '0' otherwise;
+ timestamp_sec Number Modification time, seconds;
+ timestamp_nsec Number Modification time, nanoseconds;
+ dev Number Device number;
+ ino Number I-node number;
+ name String Directory name; in contrast to the
+ previous versions it is not quoted;
+ contents Dumpdir Contents of the directory;
+ *Note Dumpdir::, for a description of its
+ format.
+
+ Dumpdirs stored in snapshot files contain only records of types
+ 'Y', 'N' and 'D'.
+
+ The specific range of values allowed in each of the "Number" fields
+ depends on the underlying C datatypes as determined when 'tar' is
+ compiled. To see the specific ranges allowed for a particular
+ 'tar' binary, you can use the '--show-snapshot-field-ranges'
+ option:
+
+ $ tar --show-shapshot-field-ranges
+ This tar's snapshot file field ranges are
+ (field name => [ min, max ]):
+
+ nfs => [ 0, 1 ],
+ timestamp_sec => [ -9223372036854775808, 9223372036854775807 ],
+ timestamp_nsec => [ 0, 999999999 ],
+ dev => [ 0, 18446744073709551615 ],
+ ino => [ 0, 18446744073709551615 ],
+
+ (This example is from a GNU/Linux x86_64 system.)
+
+
+File: tar.info, Node: Dumpdir, Prev: Snapshot Files, Up: Tar Internals
+
+Dumpdir
+=======
+
+Incremental archives keep information about contents of each dumped
+directory in special data blocks called "dumpdirs".
+
+ Dumpdir is a sequence of entries of the following form:
+
+ C FILENAME \0
+
+where C is one of the "control codes" described below, FILENAME is the
+name of the file C operates upon, and '\0' represents a nul character
+(ASCII 0). The white space characters were added for readability, real
+dumpdirs do not contain them.
+
+ Each dumpdir ends with a single nul character.
+
+ The following table describes control codes and their meanings:
+
+'Y'
+ FILENAME is contained in the archive.
+
+'N'
+ FILENAME was present in the directory at the time the archive was
+ made, yet it was not dumped to the archive, because it had not
+ changed since the last backup.
+
+'D'
+ FILENAME is a directory.
+
+'R'
+ This code requests renaming of the FILENAME to the name specified
+ with the 'T' command, that immediately follows it.
+
+'T'
+ Specify target file name for 'R' command (see below).
+
+'X'
+ Specify "temporary directory" name for a rename operation (see
+ below).
+
+ Codes 'Y', 'N' and 'D' require FILENAME argument to be a relative
+file name to the directory this dumpdir describes, whereas codes 'R',
+'T' and 'X' require their argument to be an absolute file name.
+
+ The three codes 'R', 'T' and 'X' specify a "renaming operation". In
+the simplest case it is:
+
+ Rsource\0Tdest\0
+
+which means "rename file 'source' to file 'dest'".
+
+ However, there are cases that require using a "temporary directory".
+For example, consider the following scenario:
+
+ 1. Previous run dumped a directory 'foo' which contained the following
+ three directories:
+
+ a
+ b
+ c
+
+ 2. They were renamed _cyclically_, so that:
+
+ a became b
+ b became c
+ c became a
+
+ 3. New incremental dump was made.
+
+ This case cannot be handled by three successive renames, since
+renaming 'a' to 'b' will destroy the existing directory. To correctly
+process it, GNU 'tar' needs a temporary directory, so it creates the
+following dumpdir (newlines have been added for readability):
+
+ Xfoo\0
+ Rfoo/a\0T\0
+ Rfoo/b\0Tfoo/c\0
+ Rfoo/c\0Tfoo/a\0
+ R\0Tfoo/a\0
+
+ The first command, 'Xfoo\0', instructs the extractor to create a
+temporary directory in the directory 'foo'. Second command,
+'Rfoo/aT\0', says "rename file 'foo/a' to the temporary directory that
+has just been created" (empty file name after a command means use
+temporary directory). Third and fourth commands work as usual, and,
+finally, the last command, 'R\0Tfoo/a\0' tells tar to rename the
+temporary directory to 'foo/a'.
+
+ The exact placement of a dumpdir in the archive depends on the
+archive format (*note Formats::):
+
+ * PAX archives
+
+ In PAX archives, dumpdir is stored in the extended header of the
+ corresponding directory, in variable 'GNU.dumpdir'.
+
+ * GNU and old GNU archives
+
+ These formats implement special header type 'D', which is similar
+ to ustar header '5' (directory), except that it precedes a data
+ block containing the dumpdir.
+
+
+File: tar.info, Node: Genfile, Next: Free Software Needs Free Documentation, Prev: Tar Internals, Up: Top
+
+Appendix E Genfile
+******************
+
+This appendix describes 'genfile', an auxiliary program used in the GNU
+tar testsuite. If you are not interested in developing GNU tar, skip
+this appendix.
+
+ Initially, 'genfile' was used to generate data files for the
+testsuite, hence its name. However, new operation modes were being
+implemented as the testsuite grew more sophisticated, and now 'genfile'
+is a multi-purpose instrument.
+
+ There are three basic operation modes:
+
+File Generation
+ This is the default mode. In this mode, 'genfile' generates data
+ files.
+
+File Status
+ In this mode 'genfile' displays status of specified files.
+
+Synchronous Execution.
+ In this mode 'genfile' executes the given program with
+ '--checkpoint' option and executes a set of actions when specified
+ checkpoints are reached.
+
+* Menu:
+
+* Generate Mode:: File Generation Mode.
+* Status Mode:: File Status Mode.
+* Exec Mode:: Synchronous Execution mode.
+
+
+File: tar.info, Node: Generate Mode, Next: Status Mode, Up: Genfile
+
+E.1 Generate Mode
+=================
+
+In this mode 'genfile' creates a data file for the test suite. The size
+of the file is given with the '--length' ('-l') option. By default the
+file contents is written to the standard output, this can be changed
+using '--file' ('-f') command line option. Thus, the following two
+commands are equivalent:
+
+ genfile --length 100 > outfile
+ genfile --length 100 --file outfile
+
+ If '--length' is not given, 'genfile' will generate an empty
+(zero-length) file.
+
+ The command line option '--seek=N' istructs 'genfile' to skip the
+given number of bytes (N) in the output file before writing to it. It
+is similar to the 'seek=N' of the 'dd' utility.
+
+ You can instruct 'genfile' to create several files at one go, by
+giving it '--files-from' ('-T') option followed by a name of file
+containing a list of file names. Using dash ('-') instead of the file
+name causes 'genfile' to read file list from the standard input. For
+example:
+
+ # Read file names from file file.list
+ genfile --files-from file.list
+ # Read file names from standard input
+ genfile --files-from -
+
+ The list file is supposed to contain one file name per line. To use
+file lists separated by ASCII NUL character, use '--null' ('-0') command
+line option:
+
+ genfile --null --files-from file.list
+
+ The default data pattern for filling the generated file consists of
+first 256 letters of ASCII code, repeated enough times to fill the
+entire file. This behavior can be changed with '--pattern' option.
+This option takes a mandatory argument, specifying pattern name to use.
+Currently two patterns are implemented:
+
+'--pattern=default'
+ The default pattern as described above.
+
+'--pattern=zero'
+ Fills the file with zeroes.
+
+ If no file name was given, the program exits with the code '0'.
+Otherwise, it exits with '0' only if it was able to create a file of the
+specified length.
+
+ Special option '--sparse' ('-s') instructs 'genfile' to create a
+sparse file. Sparse files consist of "data fragments", separated by
+"holes" or blocks of zeros. On many operating systems, actual disk
+storage is not allocated for holes, but they are counted in the length
+of the file. To create a sparse file, 'genfile' should know where to
+put data fragments, and what data to use to fill them. So, when
+'--sparse' is given the rest of the command line specifies a so-called
+"file map".
+
+ The file map consists of any number of "fragment descriptors". Each
+descriptor is composed of two values: a number, specifying fragment
+offset from the end of the previous fragment or, for the very first
+fragment, from the beginning of the file, and "contents string", that
+specifies the pattern to fill the fragment with. File offset can be
+suffixed with the following quantifiers:
+
+'k'
+'K'
+ The number is expressed in kilobytes.
+'m'
+'M'
+ The number is expressed in megabytes.
+'g'
+'G'
+ The number is expressed in gigabytes.
+
+ Contents string can be either a fragment size or a pattern. Fragment
+size is a decimal number, prefixed with an equals sign. It can be
+suffixed with a quantifier, as discussed above. If fragment size is
+given, the fragment of that size will be filled with the currently
+selected pattern (*note -pattern: Generate Mode.) and written to the
+file.
+
+ A pattern is a string of arbitrary ASCII characters. For each of
+them, 'genfile' will generate a "block" of data, filled with that
+character and will write it to the fragment. The size of block is given
+by '--block-size' option. It defaults to 512. Thus, if pattern
+consists of N characters, the resulting file fragment will contain
+'N*BLOCK-SIZE' bytes of data.
+
+ The last fragment descriptor can have only file offset part. In this
+case 'genfile' will create a hole at the end of the file up to the given
+offset.
+
+ A dash appearing as a fragment descriptor instructs 'genfile' to read
+file map from the standard input. Each line of input should consist of
+fragment offset and contents string, separated by any amount of
+whitespace.
+
+ For example, consider the following invocation:
+
+ genfile --sparse --file sparsefile 0 ABCD 1M EFGHI 2000K
+
+It will create 3101184-bytes long file of the following structure:
+
+Offset Length Contents
+0 4*512=2048 Four 512-byte blocks, filled
+ with letters 'A', 'B', 'C' and
+ 'D'.
+2048 1046528 Zero bytes
+1050624 5*512=2560 Five blocks, filled with
+ letters 'E', 'F', 'G', 'H',
+ 'I'.
+1053184 2048000 Zero bytes
+
+ The exit code of 'genfile --sparse' command is '0' only if created
+file is actually sparse. If it is not, the appropriate error message is
+displayed and the command exists with code '1'. The '--quite' ('-q')
+option suppresses this behavior. If '--quite' is given, 'genfile
+--sparse' exits with code '0' if it was able to create the file, whether
+the resulting file is sparse or not.
+
+
+File: tar.info, Node: Status Mode, Next: Exec Mode, Prev: Generate Mode, Up: Genfile
+
+E.2 Status Mode
+===============
+
+In status mode, 'genfile' prints file system status for each file
+specified in the command line. This mode is toggled by '--stat' ('-S')
+command line option. An optional argument to this option specifies
+output "format": a comma-separated list of 'struct stat' fields to be
+displayed. This list can contain following identifiers:
+
+name
+ The file name.
+
+dev
+st_dev
+ Device number in decimal.
+
+ino
+st_ino
+ Inode number.
+
+mode[.NUMBER]
+st_mode[.NUMBER]
+
+ File mode in octal. Optional NUMBER specifies octal mask to be
+ applied to the mode before outputting. For example, '--stat
+ mode.777' will preserve lower nine bits of it. Notice, that you
+ can use any punctuation character in place of '.'.
+
+nlink
+st_nlink
+ Number of hard links.
+
+uid
+st_uid
+ User ID of owner.
+
+gid
+st_gid
+ Group ID of owner.
+
+size
+st_size
+ File size in decimal.
+
+blksize
+st_blksize
+ The size in bytes of each file block.
+
+blocks
+st_blocks
+ Number of blocks allocated.
+
+atime
+st_atime
+ Time of last access.
+
+mtime
+st_mtime
+ Time of last modification
+
+ctime
+st_ctime
+ Time of last status change
+
+sparse
+ A boolean value indicating whether the file is 'sparse'.
+
+ Modification times are displayed in UTC as UNIX timestamps, unless
+suffixed with 'H' (for "human-readable"), as in 'ctimeH', in which case
+usual 'tar tv' output format is used.
+
+ The default output format is: 'name,dev,ino,mode,
+nlink,uid,gid,size,blksize,blocks,atime,mtime,ctime'.
+
+ For example, the following command will display file names and
+corresponding times of last access for each file in the current working
+directory:
+
+ genfile --stat=name,atime *
+
+
+File: tar.info, Node: Exec Mode, Prev: Status Mode, Up: Genfile
+
+E.3 Exec Mode
+=============
+
+This mode is designed for testing the behavior of 'paxutils' commands
+when some of the files change during archiving. It is an experimental
+mode.
+
+ The 'Exec Mode' is toggled by '--run' command line option (or its
+alias '-r'). The non-optional arguments to 'getopt' give the command
+line to be executed. Normally, it should contain at least the
+'--checkpoint' option.
+
+ A set of options is provided for defining checkpoint values and
+actions to be executed upon reaching them. Checkpoint values are
+introduced with the '--checkpoint' command line option. Argument to
+this option is the number of checkpoint in decimal.
+
+ Any number of "actions" may be specified after a checkpoint.
+Available actions are
+
+'--cut FILE'
+'--truncate FILE'
+ Truncate FILE to the size specified by previous '--length' option
+ (or 0, if it is not given).
+
+'--append FILE'
+ Append data to FILE. The size of data and its pattern are given by
+ previous '--length' and 'pattern' options.
+
+'--touch FILE'
+ Update the access and modification times of FILE. These timestamps
+ are changed to the current time, unless '--date' option was given,
+ in which case they are changed to the specified time. Argument to
+ '--date' option is a date specification in an almost arbitrary
+ format (*note Date input formats::).
+
+'--exec COMMAND'
+ Execute given shell command.
+
+'--unlink FILE'
+ Unlink the FILE.
+
+ Option '--verbose' instructs 'genfile' to print on standard output
+notifications about checkpoints being executed and to verbosely describe
+exit status of the command.
+
+ While the command is being executed its standard output remains
+connected to descriptor 1. All messages it prints to file descriptor 2,
+except checkpoint notifications, are forwarded to standard error.
+
+ 'Genfile' exits with the exit status of the executed command.
+
+ For compatibility with previous 'genfile' versions, the '--run'
+option takes an optional argument. If used this way, its argument
+supplies the command line to be executed. There should be no
+non-optional arguments in the 'genfile' command line.
+
+ The actual command line is constructed by inserting the
+'--checkpoint' option between the command name and its first argument
+(if any). Due to this, the argument to '--run' may not use traditional
+'tar' option syntax, i.e., the following is wrong:
+
+ # Wrong!
+ genfile --run='tar cf foo bar'
+
+ Use the following syntax instead:
+
+ genfile --run='tar -cf foo bar' ACTIONS...
+
+ The above command line is equivalent to
+
+ genfile ACTIONS... -- tar -cf foo bar
+
+ Notice, that the use of compatibility mode is deprecated.
+
+
+File: tar.info, Node: Free Software Needs Free Documentation, Next: GNU Free Documentation License, Prev: Genfile, Up: Top
+
+Appendix F Free Software Needs Free Documentation
+*************************************************
+
+The biggest deficiency in the free software community today is not in
+the software--it is the lack of good free documentation that we can
+include with the free software. Many of our most important programs do
+not come with free reference manuals and free introductory texts.
+Documentation is an essential part of any software package; when an
+important free software package does not come with a free manual and a
+free tutorial, that is a major gap. We have many such gaps today.
+
+ Consider Perl, for instance. The tutorial manuals that people
+normally use are non-free. How did this come about? Because the
+authors of those manuals published them with restrictive terms--no
+copying, no modification, source files not available--which exclude them
+from the free software world.
+
+ That wasn't the first time this sort of thing happened, and it was
+far from the last. Many times we have heard a GNU user eagerly describe
+a manual that he is writing, his intended contribution to the community,
+only to learn that he had ruined everything by signing a publication
+contract to make it non-free.
+
+ Free documentation, like free software, is a matter of freedom, not
+price. The problem with the non-free manual is not that publishers
+charge a price for printed copies--that in itself is fine. (The Free
+Software Foundation sells printed copies of manuals, too.) The problem
+is the restrictions on the use of the manual. Free manuals are
+available in source code form, and give you permission to copy and
+modify. Non-free manuals do not allow this.
+
+ The criteria of freedom for a free manual are roughly the same as for
+free software. Redistribution (including the normal kinds of commercial
+redistribution) must be permitted, so that the manual can accompany
+every copy of the program, both on-line and on paper.
+
+ Permission for modification of the technical content is crucial too.
+When people modify the software, adding or changing features, if they
+are conscientious they will change the manual too--so they can provide
+accurate and clear documentation for the modified program. A manual
+that leaves you no choice but to write a new manual to document a
+changed version of the program is not really available to our community.
+
+ Some kinds of limits on the way modification is handled are
+acceptable. For example, requirements to preserve the original author's
+copyright notice, the distribution terms, or the list of authors, are
+ok. It is also no problem to require modified versions to include
+notice that they were modified. Even entire sections that may not be
+deleted or changed are acceptable, as long as they deal with
+nontechnical topics (like this one). These kinds of restrictions are
+acceptable because they don't obstruct the community's normal use of the
+manual.
+
+ However, it must be possible to modify all the _technical_ content of
+the manual, and then distribute the result in all the usual media,
+through all the usual channels. Otherwise, the restrictions obstruct
+the use of the manual, it is not free, and we need another manual to
+replace it.
+
+ Please spread the word about this issue. Our community continues to
+lose manuals to proprietary publishing. If we spread the word that free
+software needs free reference manuals and free tutorials, perhaps the
+next person who wants to contribute by writing documentation will
+realize, before it is too late, that only free manuals contribute to the
+free software community.
+
+ If you are writing documentation, please insist on publishing it
+under the GNU Free Documentation License or another free documentation
+license. Remember that this decision requires your approval--you don't
+have to let the publisher decide. Some commercial publishers will use a
+free license if you insist, but they will not propose the option; it is
+up to you to raise the issue and say firmly that this is what you want.
+If the publisher you are dealing with refuses, please try other
+publishers. If you're not sure whether a proposed license is free,
+write to <licensing@gnu.org>.
+
+ You can encourage commercial publishers to sell more free, copylefted
+manuals and tutorials by buying them, and particularly by buying copies
+from the publishers that paid for their writing or for major
+improvements. Meanwhile, try to avoid buying non-free documentation at
+all. Check the distribution terms of a manual before you buy it, and
+insist that whoever seeks your business must respect your freedom.
+Check the history of the book, and try reward the publishers that have
+paid or pay the authors to work on it.
+
+ The Free Software Foundation maintains a list of free documentation
+published by other publishers, at
+<http://www.fsf.org/doc/other-free-books.html>.
+
+
+File: tar.info, Node: GNU Free Documentation License, Next: Index of Command Line Options, Prev: Free Software Needs Free Documentation, Up: Top
+
+Appendix G GNU Free Documentation License
+*****************************************
+
+ Version 1.3, 3 November 2008
+
+ Copyright (C) 2000-2002, 2007-2008, 2014, 2016 Free Software
+ Foundation, Inc.
+ <http://fsf.org/>
+
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+ 0. PREAMBLE
+
+ The purpose of this License is to make a manual, textbook, or other
+ functional and useful document "free" in the sense of freedom: to
+ assure everyone the effective freedom to copy and redistribute it,
+ with or without modifying it, either commercially or
+ noncommercially. Secondarily, this License preserves for the
+ author and publisher a way to get credit for their work, while not
+ being considered responsible for modifications made by others.
+
+ This License is a kind of "copyleft", which means that derivative
+ works of the document must themselves be free in the same sense.
+ It complements the GNU General Public License, which is a copyleft
+ license designed for free software.
+
+ We have designed this License in order to use it for manuals for
+ free software, because free software needs free documentation: a
+ free program should come with manuals providing the same freedoms
+ that the software does. But this License is not limited to
+ software manuals; it can be used for any textual work, regardless
+ of subject matter or whether it is published as a printed book. We
+ recommend this License principally for works whose purpose is
+ instruction or reference.
+
+ 1. APPLICABILITY AND DEFINITIONS
+
+ This License applies to any manual or other work, in any medium,
+ that contains a notice placed by the copyright holder saying it can
+ be distributed under the terms of this License. Such a notice
+ grants a world-wide, royalty-free license, unlimited in duration,
+ to use that work under the conditions stated herein. The
+ "Document", below, refers to any such manual or work. Any member
+ of the public is a licensee, and is addressed as "you". You accept
+ the license if you copy, modify or distribute the work in a way
+ requiring permission under copyright law.
+
+ A "Modified Version" of the Document means any work containing the
+ Document or a portion of it, either copied verbatim, or with
+ modifications and/or translated into another language.
+
+ A "Secondary Section" is a named appendix or a front-matter section
+ of the Document that deals exclusively with the relationship of the
+ publishers or authors of the Document to the Document's overall
+ subject (or to related matters) and contains nothing that could
+ fall directly within that overall subject. (Thus, if the Document
+ is in part a textbook of mathematics, a Secondary Section may not
+ explain any mathematics.) The relationship could be a matter of
+ historical connection with the subject or with related matters, or
+ of legal, commercial, philosophical, ethical or political position
+ regarding them.
+
+ The "Invariant Sections" are certain Secondary Sections whose
+ titles are designated, as being those of Invariant Sections, in the
+ notice that says that the Document is released under this License.
+ If a section does not fit the above definition of Secondary then it
+ is not allowed to be designated as Invariant. The Document may
+ contain zero Invariant Sections. If the Document does not identify
+ any Invariant Sections then there are none.
+
+ The "Cover Texts" are certain short passages of text that are
+ listed, as Front-Cover Texts or Back-Cover Texts, in the notice
+ that says that the Document is released under this License. A
+ Front-Cover Text may be at most 5 words, and a Back-Cover Text may
+ be at most 25 words.
+
+ A "Transparent" copy of the Document means a machine-readable copy,
+ represented in a format whose specification is available to the
+ general public, that is suitable for revising the document
+ straightforwardly with generic text editors or (for images composed
+ of pixels) generic paint programs or (for drawings) some widely
+ available drawing editor, and that is suitable for input to text
+ formatters or for automatic translation to a variety of formats
+ suitable for input to text formatters. A copy made in an otherwise
+ Transparent file format whose markup, or absence of markup, has
+ been arranged to thwart or discourage subsequent modification by
+ readers is not Transparent. An image format is not Transparent if
+ used for any substantial amount of text. A copy that is not
+ "Transparent" is called "Opaque".
+
+ Examples of suitable formats for Transparent copies include plain
+ ASCII without markup, Texinfo input format, LaTeX input format,
+ SGML or XML using a publicly available DTD, and standard-conforming
+ simple HTML, PostScript or PDF designed for human modification.
+ Examples of transparent image formats include PNG, XCF and JPG.
+ Opaque formats include proprietary formats that can be read and
+ edited only by proprietary word processors, SGML or XML for which
+ the DTD and/or processing tools are not generally available, and
+ the machine-generated HTML, PostScript or PDF produced by some word
+ processors for output purposes only.
+
+ The "Title Page" means, for a printed book, the title page itself,
+ plus such following pages as are needed to hold, legibly, the
+ material this License requires to appear in the title page. For
+ works in formats which do not have any title page as such, "Title
+ Page" means the text near the most prominent appearance of the
+ work's title, preceding the beginning of the body of the text.
+
+ The "publisher" means any person or entity that distributes copies
+ of the Document to the public.
+
+ A section "Entitled XYZ" means a named subunit of the Document
+ whose title either is precisely XYZ or contains XYZ in parentheses
+ following text that translates XYZ in another language. (Here XYZ
+ stands for a specific section name mentioned below, such as
+ "Acknowledgements", "Dedications", "Endorsements", or "History".)
+ To "Preserve the Title" of such a section when you modify the
+ Document means that it remains a section "Entitled XYZ" according
+ to this definition.
+
+ The Document may include Warranty Disclaimers next to the notice
+ which states that this License applies to the Document. These
+ Warranty Disclaimers are considered to be included by reference in
+ this License, but only as regards disclaiming warranties: any other
+ implication that these Warranty Disclaimers may have is void and
+ has no effect on the meaning of this License.
+
+ 2. VERBATIM COPYING
+
+ You may copy and distribute the Document in any medium, either
+ commercially or noncommercially, provided that this License, the
+ copyright notices, and the license notice saying this License
+ applies to the Document are reproduced in all copies, and that you
+ add no other conditions whatsoever to those of this License. You
+ may not use technical measures to obstruct or control the reading
+ or further copying of the copies you make or distribute. However,
+ you may accept compensation in exchange for copies. If you
+ distribute a large enough number of copies you must also follow the
+ conditions in section 3.
+
+ You may also lend copies, under the same conditions stated above,
+ and you may publicly display copies.
+
+ 3. COPYING IN QUANTITY
+
+ If you publish printed copies (or copies in media that commonly
+ have printed covers) of the Document, numbering more than 100, and
+ the Document's license notice requires Cover Texts, you must
+ enclose the copies in covers that carry, clearly and legibly, all
+ these Cover Texts: Front-Cover Texts on the front cover, and
+ Back-Cover Texts on the back cover. Both covers must also clearly
+ and legibly identify you as the publisher of these copies. The
+ front cover must present the full title with all words of the title
+ equally prominent and visible. You may add other material on the
+ covers in addition. Copying with changes limited to the covers, as
+ long as they preserve the title of the Document and satisfy these
+ conditions, can be treated as verbatim copying in other respects.
+
+ If the required texts for either cover are too voluminous to fit
+ legibly, you should put the first ones listed (as many as fit
+ reasonably) on the actual cover, and continue the rest onto
+ adjacent pages.
+
+ If you publish or distribute Opaque copies of the Document
+ numbering more than 100, you must either include a machine-readable
+ Transparent copy along with each Opaque copy, or state in or with
+ each Opaque copy a computer-network location from which the general
+ network-using public has access to download using public-standard
+ network protocols a complete Transparent copy of the Document, free
+ of added material. If you use the latter option, you must take
+ reasonably prudent steps, when you begin distribution of Opaque
+ copies in quantity, to ensure that this Transparent copy will
+ remain thus accessible at the stated location until at least one
+ year after the last time you distribute an Opaque copy (directly or
+ through your agents or retailers) of that edition to the public.
+
+ It is requested, but not required, that you contact the authors of
+ the Document well before redistributing any large number of copies,
+ to give them a chance to provide you with an updated version of the
+ Document.
+
+ 4. MODIFICATIONS
+
+ You may copy and distribute a Modified Version of the Document
+ under the conditions of sections 2 and 3 above, provided that you
+ release the Modified Version under precisely this License, with the
+ Modified Version filling the role of the Document, thus licensing
+ distribution and modification of the Modified Version to whoever
+ possesses a copy of it. In addition, you must do these things in
+ the Modified Version:
+
+ A. Use in the Title Page (and on the covers, if any) a title
+ distinct from that of the Document, and from those of previous
+ versions (which should, if there were any, be listed in the
+ History section of the Document). You may use the same title
+ as a previous version if the original publisher of that
+ version gives permission.
+
+ B. List on the Title Page, as authors, one or more persons or
+ entities responsible for authorship of the modifications in
+ the Modified Version, together with at least five of the
+ principal authors of the Document (all of its principal
+ authors, if it has fewer than five), unless they release you
+ from this requirement.
+
+ C. State on the Title page the name of the publisher of the
+ Modified Version, as the publisher.
+
+ D. Preserve all the copyright notices of the Document.
+
+ E. Add an appropriate copyright notice for your modifications
+ adjacent to the other copyright notices.
+
+ F. Include, immediately after the copyright notices, a license
+ notice giving the public permission to use the Modified
+ Version under the terms of this License, in the form shown in
+ the Addendum below.
+
+ G. Preserve in that license notice the full lists of Invariant
+ Sections and required Cover Texts given in the Document's
+ license notice.
+
+ H. Include an unaltered copy of this License.
+
+ I. Preserve the section Entitled "History", Preserve its Title,
+ and add to it an item stating at least the title, year, new
+ authors, and publisher of the Modified Version as given on the
+ Title Page. If there is no section Entitled "History" in the
+ Document, create one stating the title, year, authors, and
+ publisher of the Document as given on its Title Page, then add
+ an item describing the Modified Version as stated in the
+ previous sentence.
+
+ J. Preserve the network location, if any, given in the Document
+ for public access to a Transparent copy of the Document, and
+ likewise the network locations given in the Document for
+ previous versions it was based on. These may be placed in the
+ "History" section. You may omit a network location for a work
+ that was published at least four years before the Document
+ itself, or if the original publisher of the version it refers
+ to gives permission.
+
+ K. For any section Entitled "Acknowledgements" or "Dedications",
+ Preserve the Title of the section, and preserve in the section
+ all the substance and tone of each of the contributor
+ acknowledgements and/or dedications given therein.
+
+ L. Preserve all the Invariant Sections of the Document, unaltered
+ in their text and in their titles. Section numbers or the
+ equivalent are not considered part of the section titles.
+
+ M. Delete any section Entitled "Endorsements". Such a section
+ may not be included in the Modified Version.
+
+ N. Do not retitle any existing section to be Entitled
+ "Endorsements" or to conflict in title with any Invariant
+ Section.
+
+ O. Preserve any Warranty Disclaimers.
+
+ If the Modified Version includes new front-matter sections or
+ appendices that qualify as Secondary Sections and contain no
+ material copied from the Document, you may at your option designate
+ some or all of these sections as invariant. To do this, add their
+ titles to the list of Invariant Sections in the Modified Version's
+ license notice. These titles must be distinct from any other
+ section titles.
+
+ You may add a section Entitled "Endorsements", provided it contains
+ nothing but endorsements of your Modified Version by various
+ parties--for example, statements of peer review or that the text
+ has been approved by an organization as the authoritative
+ definition of a standard.
+
+ You may add a passage of up to five words as a Front-Cover Text,
+ and a passage of up to 25 words as a Back-Cover Text, to the end of
+ the list of Cover Texts in the Modified Version. Only one passage
+ of Front-Cover Text and one of Back-Cover Text may be added by (or
+ through arrangements made by) any one entity. If the Document
+ already includes a cover text for the same cover, previously added
+ by you or by arrangement made by the same entity you are acting on
+ behalf of, you may not add another; but you may replace the old
+ one, on explicit permission from the previous publisher that added
+ the old one.
+
+ The author(s) and publisher(s) of the Document do not by this
+ License give permission to use their names for publicity for or to
+ assert or imply endorsement of any Modified Version.
+
+ 5. COMBINING DOCUMENTS
+
+ You may combine the Document with other documents released under
+ this License, under the terms defined in section 4 above for
+ modified versions, provided that you include in the combination all
+ of the Invariant Sections of all of the original documents,
+ unmodified, and list them all as Invariant Sections of your
+ combined work in its license notice, and that you preserve all
+ their Warranty Disclaimers.
+
+ The combined work need only contain one copy of this License, and
+ multiple identical Invariant Sections may be replaced with a single
+ copy. If there are multiple Invariant Sections with the same name
+ but different contents, make the title of each such section unique
+ by adding at the end of it, in parentheses, the name of the
+ original author or publisher of that section if known, or else a
+ unique number. Make the same adjustment to the section titles in
+ the list of Invariant Sections in the license notice of the
+ combined work.
+
+ In the combination, you must combine any sections Entitled
+ "History" in the various original documents, forming one section
+ Entitled "History"; likewise combine any sections Entitled
+ "Acknowledgements", and any sections Entitled "Dedications". You
+ must delete all sections Entitled "Endorsements."
+
+ 6. COLLECTIONS OF DOCUMENTS
+
+ You may make a collection consisting of the Document and other
+ documents released under this License, and replace the individual
+ copies of this License in the various documents with a single copy
+ that is included in the collection, provided that you follow the
+ rules of this License for verbatim copying of each of the documents
+ in all other respects.
+
+ You may extract a single document from such a collection, and
+ distribute it individually under this License, provided you insert
+ a copy of this License into the extracted document, and follow this
+ License in all other respects regarding verbatim copying of that
+ document.
+
+ 7. AGGREGATION WITH INDEPENDENT WORKS
+
+ A compilation of the Document or its derivatives with other
+ separate and independent documents or works, in or on a volume of a
+ storage or distribution medium, is called an "aggregate" if the
+ copyright resulting from the compilation is not used to limit the
+ legal rights of the compilation's users beyond what the individual
+ works permit. When the Document is included in an aggregate, this
+ License does not apply to the other works in the aggregate which
+ are not themselves derivative works of the Document.
+
+ If the Cover Text requirement of section 3 is applicable to these
+ copies of the Document, then if the Document is less than one half
+ of the entire aggregate, the Document's Cover Texts may be placed
+ on covers that bracket the Document within the aggregate, or the
+ electronic equivalent of covers if the Document is in electronic
+ form. Otherwise they must appear on printed covers that bracket
+ the whole aggregate.
+
+ 8. TRANSLATION
+
+ Translation is considered a kind of modification, so you may
+ distribute translations of the Document under the terms of section
+ 4. Replacing Invariant Sections with translations requires special
+ permission from their copyright holders, but you may include
+ translations of some or all Invariant Sections in addition to the
+ original versions of these Invariant Sections. You may include a
+ translation of this License, and all the license notices in the
+ Document, and any Warranty Disclaimers, provided that you also
+ include the original English version of this License and the
+ original versions of those notices and disclaimers. In case of a
+ disagreement between the translation and the original version of
+ this License or a notice or disclaimer, the original version will
+ prevail.
+
+ If a section in the Document is Entitled "Acknowledgements",
+ "Dedications", or "History", the requirement (section 4) to
+ Preserve its Title (section 1) will typically require changing the
+ actual title.
+
+ 9. TERMINATION
+
+ You may not copy, modify, sublicense, or distribute the Document
+ except as expressly provided under this License. Any attempt
+ otherwise to copy, modify, sublicense, or distribute it is void,
+ and will automatically terminate your rights under this License.
+
+ However, if you cease all violation of this License, then your
+ license from a particular copyright holder is reinstated (a)
+ provisionally, unless and until the copyright holder explicitly and
+ finally terminates your license, and (b) permanently, if the
+ copyright holder fails to notify you of the violation by some
+ reasonable means prior to 60 days after the cessation.
+
+ Moreover, your license from a particular copyright holder is
+ reinstated permanently if the copyright holder notifies you of the
+ violation by some reasonable means, this is the first time you have
+ received notice of violation of this License (for any work) from
+ that copyright holder, and you cure the violation prior to 30 days
+ after your receipt of the notice.
+
+ Termination of your rights under this section does not terminate
+ the licenses of parties who have received copies or rights from you
+ under this License. If your rights have been terminated and not
+ permanently reinstated, receipt of a copy of some or all of the
+ same material does not give you any rights to use it.
+
+ 10. FUTURE REVISIONS OF THIS LICENSE
+
+ The Free Software Foundation may publish new, revised versions of
+ the GNU Free Documentation License from time to time. Such new
+ versions will be similar in spirit to the present version, but may
+ differ in detail to address new problems or concerns. See
+ <http://www.gnu.org/copyleft/>.
+
+ Each version of the License is given a distinguishing version
+ number. If the Document specifies that a particular numbered
+ version of this License "or any later version" applies to it, you
+ have the option of following the terms and conditions either of
+ that specified version or of any later version that has been
+ published (not as a draft) by the Free Software Foundation. If the
+ Document does not specify a version number of this License, you may
+ choose any version ever published (not as a draft) by the Free
+ Software Foundation. If the Document specifies that a proxy can
+ decide which future versions of this License can be used, that
+ proxy's public statement of acceptance of a version permanently
+ authorizes you to choose that version for the Document.
+
+ 11. RELICENSING
+
+ "Massive Multiauthor Collaboration Site" (or "MMC Site") means any
+ World Wide Web server that publishes copyrightable works and also
+ provides prominent facilities for anybody to edit those works. A
+ public wiki that anybody can edit is an example of such a server.
+ A "Massive Multiauthor Collaboration" (or "MMC") contained in the
+ site means any set of copyrightable works thus published on the MMC
+ site.
+
+ "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0
+ license published by Creative Commons Corporation, a not-for-profit
+ corporation with a principal place of business in San Francisco,
+ California, as well as future copyleft versions of that license
+ published by that same organization.
+
+ "Incorporate" means to publish or republish a Document, in whole or
+ in part, as part of another Document.
+
+ An MMC is "eligible for relicensing" if it is licensed under this
+ License, and if all works that were first published under this
+ License somewhere other than this MMC, and subsequently
+ incorporated in whole or in part into the MMC, (1) had no cover
+ texts or invariant sections, and (2) were thus incorporated prior
+ to November 1, 2008.
+
+ The operator of an MMC Site may republish an MMC contained in the
+ site under CC-BY-SA on the same site at any time before August 1,
+ 2009, provided the MMC is eligible for relicensing.
+
+ADDENDUM: How to use this License for your documents
+====================================================
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and license
+notices just after the title page:
+
+ Copyright (C) YEAR YOUR NAME.
+ Permission is granted to copy, distribute and/or modify this document
+ under the terms of the GNU Free Documentation License, Version 1.3
+ or any later version published by the Free Software Foundation;
+ with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
+ Texts. A copy of the license is included in the section entitled ``GNU
+ Free Documentation License''.
+
+ If you have Invariant Sections, Front-Cover Texts and Back-Cover
+Texts, replace the "with...Texts." line with this:
+
+ with the Invariant Sections being LIST THEIR TITLES, with
+ the Front-Cover Texts being LIST, and with the Back-Cover Texts
+ being LIST.
+
+ If you have Invariant Sections without Cover Texts, or some other
+combination of the three, merge those two alternatives to suit the
+situation.
+
+ If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of free
+software license, such as the GNU General Public License, to permit
+their use in free software.
+
+
+File: tar.info, Node: Index of Command Line Options, Next: Index, Prev: GNU Free Documentation License, Up: Top
+
+Appendix H Index of Command Line Options
+****************************************
+
+This appendix contains an index of all GNU 'tar' long command line
+options. The options are listed without the preceding double-dash. For
+a cross-reference of short command line options, see *note Short Option
+Summary::.
+
+
+* Menu:
+
+* absolute-names: absolute. (line 10)
+* absolute-names, summary: Option Summary. (line 6)
+* acls, summary: Option Summary. (line 14)
+* add-file: files. (line 79)
+* after-date: after. (line 24)
+* after-date, summary: Option Summary. (line 17)
+* anchored: controlling pattern-matching.
+ (line 78)
+* anchored, summary: Option Summary. (line 21)
+* append: append. (line 6)
+* append <1>: appending files. (line 6)
+* append, summary: Operation Summary. (line 6)
+* atime-preserve: Attributes. (line 10)
+* atime-preserve, summary: Option Summary. (line 25)
+* auto-compress: gzip. (line 150)
+* auto-compress, summary: Option Summary. (line 71)
+* backup: backup. (line 41)
+* backup, summary: Option Summary. (line 78)
+* block-number: verbose. (line 112)
+* block-number, summary: Option Summary. (line 84)
+* blocking-factor: Blocking Factor. (line 8)
+* blocking-factor, summary: Option Summary. (line 91)
+* bzip2, summary: Option Summary. (line 97)
+* catenate: concatenate. (line 6)
+* catenate, summary: Operation Summary. (line 11)
+* check-device, described: Incremental Dumps. (line 107)
+* check-device, summary: Option Summary. (line 103)
+* check-links, described: hard links. (line 31)
+* check-links, summary: Option Summary. (line 155)
+* checkpoint: checkpoints. (line 6)
+* checkpoint, defined: checkpoints. (line 13)
+* checkpoint, summary: Option Summary. (line 108)
+* checkpoint-action: checkpoints. (line 6)
+* checkpoint-action, defined: checkpoints. (line 22)
+* checkpoint-action, summary: Option Summary. (line 117)
+* clamp-mtime, summary: Option Summary. (line 172)
+* compare: compare. (line 6)
+* compare, summary: Operation Summary. (line 16)
+* compress: gzip. (line 113)
+* compress, summary: Option Summary. (line 164)
+* concatenate: concatenate. (line 6)
+* concatenate, summary: Operation Summary. (line 23)
+* confirmation, summary: Option Summary. (line 176)
+* create, additional options: create options. (line 6)
+* create, complementary notes: Basic tar. (line 11)
+* create, introduced: Creating the archive.
+ (line 6)
+* create, summary: Operation Summary. (line 29)
+* create, using with '--verbose': create verbose. (line 6)
+* create, using with '--verify': verify. (line 24)
+* delay-directory-restore: Directory Modification Times and Permissions.
+ (line 62)
+* delay-directory-restore, summary: Option Summary. (line 180)
+* delete: delete. (line 6)
+* delete, summary: Operation Summary. (line 34)
+* delete, using before -append: append. (line 47)
+* dereference: dereference. (line 6)
+* dereference, summary: Option Summary. (line 186)
+* diff, summary: Operation Summary. (line 39)
+* directory: directory. (line 11)
+* directory, summary: Option Summary. (line 193)
+* exclude: exclude. (line 6)
+* exclude <1>: exclude. (line 9)
+* exclude, potential problems with: problems with exclude.
+ (line 6)
+* exclude, summary: Option Summary. (line 201)
+* exclude-backups: exclude. (line 114)
+* exclude-backups, summary: Option Summary. (line 206)
+* exclude-caches: exclude. (line 134)
+* exclude-caches, summary: Option Summary. (line 215)
+* exclude-caches-all: exclude. (line 142)
+* exclude-caches-all, summary: Option Summary. (line 230)
+* exclude-caches-under: exclude. (line 138)
+* exclude-caches-under, summary: Option Summary. (line 223)
+* exclude-from: exclude. (line 6)
+* exclude-from <1>: exclude. (line 20)
+* exclude-from, summary: Option Summary. (line 209)
+* exclude-ignore: exclude. (line 76)
+* exclude-ignore, summary: Option Summary. (line 235)
+* exclude-ignore-recursive: exclude. (line 81)
+* exclude-ignore-recursive, summary: Option Summary. (line 240)
+* exclude-tag: exclude. (line 151)
+* exclude-tag, summary: Option Summary. (line 245)
+* exclude-tag-all: exclude. (line 159)
+* exclude-tag-all, summary: Option Summary. (line 257)
+* exclude-tag-under: exclude. (line 155)
+* exclude-tag-under, summary: Option Summary. (line 251)
+* exclude-vcs: exclude. (line 85)
+* exclude-vcs, summary: Option Summary. (line 262)
+* exclude-vcs-ignores: exclude. (line 42)
+* exclude-vcs-ignores, summary: Option Summary. (line 269)
+* extract: extract. (line 6)
+* extract, additional options: extract options. (line 6)
+* extract, complementary notes: Basic tar. (line 49)
+* extract, summary: Operation Summary. (line 44)
+* extract, using with '--listed-incremental': Incremental Dumps.
+ (line 120)
+* file: file. (line 6)
+* file, short description: file. (line 15)
+* file, summary: Option Summary. (line 277)
+* file, tutorial: file tutorial. (line 6)
+* files-from: files. (line 14)
+* files-from, summary: Option Summary. (line 284)
+* force-local, short description: Device. (line 70)
+* force-local, summary: Option Summary. (line 291)
+* format, summary: Option Summary. (line 297)
+* full-time, summary: Option Summary. (line 322)
+* get, summary: Operation Summary. (line 50)
+* group: override. (line 99)
+* group, summary: Option Summary. (line 340)
+* group-map, summary: Option Summary. (line 350)
+* gunzip, summary: Option Summary. (line 360)
+* gzip: gzip. (line 91)
+* gzip, summary: Option Summary. (line 360)
+* hard-dereference, described: hard links. (line 59)
+* hard-dereference, summary: Option Summary. (line 369)
+* help: help tutorial. (line 6)
+* help, introduction: help. (line 26)
+* help, summary: Option Summary. (line 375)
+* hole-detection: sparse. (line 66)
+* hole-detection, summary: Option Summary. (line 381)
+* ignore-case: controlling pattern-matching.
+ (line 85)
+* ignore-case, summary: Option Summary. (line 386)
+* ignore-command-error: Writing to an External Program.
+ (line 111)
+* ignore-command-error, summary: Option Summary. (line 390)
+* ignore-failed-read: Ignore Failed Read. (line 7)
+* ignore-failed-read, summary: Option Summary. (line 394)
+* ignore-zeros: Ignore Zeros. (line 6)
+* ignore-zeros, short description: Blocking Factor. (line 152)
+* ignore-zeros, summary: Option Summary. (line 399)
+* incremental, summary: Option Summary. (line 405)
+* incremental, using with '--list': Incremental Dumps. (line 185)
+* index-file, summary: Option Summary. (line 413)
+* info-script: Multi-Volume Archives.
+ (line 83)
+* info-script, short description: Device. (line 121)
+* info-script, summary: Option Summary. (line 417)
+* interactive: interactive. (line 14)
+* interactive, summary: Option Summary. (line 426)
+* keep-directory-symlink, summary: Option Summary. (line 434)
+* keep-newer-files: Keep Newer Files. (line 6)
+* keep-newer-files, summary: Option Summary. (line 448)
+* keep-old-files: Keep Old Files. (line 9)
+* keep-old-files, introduced: Dealing with Old Files.
+ (line 16)
+* keep-old-files, summary: Option Summary. (line 453)
+* label: Tape Files. (line 6)
+* label <1>: label. (line 6)
+* label, summary: Option Summary. (line 462)
+* level, described: Incremental Dumps. (line 75)
+* level, summary: Option Summary. (line 470)
+* list: list. (line 6)
+* list, summary: Operation Summary. (line 55)
+* list, using with '--incremental': Incremental Dumps. (line 185)
+* list, using with '--listed-incremental': Incremental Dumps.
+ (line 185)
+* list, using with '--verbose': list. (line 34)
+* list, using with file name arguments: list. (line 25)
+* listed-incremental, described: Incremental Dumps. (line 14)
+* listed-incremental, summary: Option Summary. (line 480)
+* listed-incremental, using with '--extract': Incremental Dumps.
+ (line 120)
+* listed-incremental, using with '--list': Incremental Dumps.
+ (line 185)
+* lzip: gzip. (line 104)
+* lzip, summary: Option Summary. (line 489)
+* lzma: gzip. (line 107)
+* lzma, summary: Option Summary. (line 494)
+* lzop: gzip. (line 110)
+* mode: override. (line 14)
+* mode, summary: Option Summary. (line 504)
+* mtime: override. (line 30)
+* mtime, summary: Option Summary. (line 511)
+* multi-volume: Multi-Volume Archives.
+ (line 6)
+* multi-volume, short description: Device. (line 88)
+* multi-volume, summary: Option Summary. (line 526)
+* new-volume-script: Multi-Volume Archives.
+ (line 83)
+* new-volume-script, short description: Device. (line 121)
+* new-volume-script, summary: Option Summary. (line 417)
+* new-volume-script, summary <1>: Option Summary. (line 532)
+* newer: after. (line 24)
+* newer, summary: Option Summary. (line 536)
+* newer-mtime: after. (line 35)
+* newer-mtime, summary: Option Summary. (line 545)
+* no-acls, summary: Option Summary. (line 551)
+* no-anchored: controlling pattern-matching.
+ (line 78)
+* no-anchored, summary: Option Summary. (line 555)
+* no-auto-compress, summary: Option Summary. (line 559)
+* no-check-device, described: Incremental Dumps. (line 103)
+* no-check-device, summary: Option Summary. (line 564)
+* no-delay-directory-restore: Directory Modification Times and Permissions.
+ (line 68)
+* no-delay-directory-restore, summary: Option Summary. (line 569)
+* no-ignore-case: controlling pattern-matching.
+ (line 85)
+* no-ignore-case, summary: Option Summary. (line 575)
+* no-ignore-command-error: Writing to an External Program.
+ (line 116)
+* no-ignore-command-error, summary: Option Summary. (line 578)
+* no-null, described: nul. (line 15)
+* no-null, summary: Option Summary. (line 582)
+* no-overwrite-dir, summary: Option Summary. (line 588)
+* no-quote-chars, summary: Option Summary. (line 593)
+* no-recursion: recurse. (line 11)
+* no-recursion, summary: Option Summary. (line 598)
+* no-same-owner: Attributes. (line 63)
+* no-same-owner, summary: Option Summary. (line 603)
+* no-same-permissions, summary: Option Summary. (line 610)
+* no-seek, summary: Option Summary. (line 616)
+* no-selinux, summary: Option Summary. (line 622)
+* no-unquote: Selecting Archive Members.
+ (line 42)
+* no-unquote, summary: Option Summary. (line 626)
+* no-verbatim-files-from: files. (line 75)
+* no-verbatim-files-from, summary: Option Summary. (line 630)
+* no-wildcards: controlling pattern-matching.
+ (line 41)
+* no-wildcards, summary: Option Summary. (line 644)
+* no-wildcards-match-slash: controlling pattern-matching.
+ (line 91)
+* no-wildcards-match-slash, summary: Option Summary. (line 647)
+* no-xattrs, summary: Option Summary. (line 650)
+* null, described: nul. (line 11)
+* null, summary: Option Summary. (line 654)
+* numeric-owner: Attributes. (line 69)
+* numeric-owner, summary: Option Summary. (line 667)
+* occurrence, described: append. (line 34)
+* occurrence, summary: Option Summary. (line 685)
+* old-archive, summary: Option Summary. (line 700)
+* one-file-system: one. (line 14)
+* one-file-system, summary: Option Summary. (line 703)
+* one-top-level, summary: Option Summary. (line 708)
+* overwrite: Overwrite Old Files.
+ (line 6)
+* overwrite, introduced: Dealing with Old Files.
+ (line 32)
+* overwrite, summary: Option Summary. (line 719)
+* overwrite-dir: Overwrite Old Files.
+ (line 28)
+* overwrite-dir, introduced: Dealing with Old Files.
+ (line 6)
+* overwrite-dir, summary: Option Summary. (line 724)
+* owner: override. (line 67)
+* owner, summary: Option Summary. (line 729)
+* owner-map, summary: Option Summary. (line 739)
+* pax-option: PAX keywords. (line 6)
+* pax-option, summary: Option Summary. (line 749)
+* portability, summary: Option Summary. (line 755)
+* posix, summary: Option Summary. (line 759)
+* preserve-order: Same Order. (line 6)
+* preserve-order, summary: Option Summary. (line 762)
+* preserve-permissions: Setting Access Permissions.
+ (line 10)
+* preserve-permissions, short description: Attributes. (line 109)
+* preserve-permissions, summary: Option Summary. (line 766)
+* quote-chars, summary: Option Summary. (line 777)
+* quoting-style: quoting styles. (line 38)
+* quoting-style, summary: Option Summary. (line 781)
+* read-full-records: Reading. (line 6)
+* read-full-records <1>: read full records. (line 6)
+* read-full-records, short description: Blocking Factor. (line 168)
+* read-full-records, summary: Option Summary. (line 788)
+* record-size, summary: Option Summary. (line 794)
+* recursion: recurse. (line 22)
+* recursion, summary: Option Summary. (line 802)
+* recursive-unlink: Recursive Unlink. (line 6)
+* recursive-unlink, summary: Option Summary. (line 807)
+* remove-files: remove files. (line 6)
+* remove-files, summary: Option Summary. (line 812)
+* restrict, summary: Option Summary. (line 817)
+* rmt-command, summary: Option Summary. (line 823)
+* rsh-command: Device. (line 73)
+* rsh-command, summary: Option Summary. (line 828)
+* same-order: Same Order. (line 6)
+* same-order, summary: Option Summary. (line 833)
+* same-owner: Attributes. (line 44)
+* same-owner, summary: Option Summary. (line 842)
+* same-permissions: Setting Access Permissions.
+ (line 10)
+* same-permissions, short description: Attributes. (line 109)
+* same-permissions, summary: Option Summary. (line 766)
+* same-permissions, summary <1>: Option Summary. (line 849)
+* seek, summary: Option Summary. (line 853)
+* selinux, summary: Option Summary. (line 863)
+* show-defaults: defaults. (line 6)
+* show-defaults, summary: Option Summary. (line 867)
+* show-omitted-dirs: verbose. (line 105)
+* show-omitted-dirs, summary: Option Summary. (line 880)
+* show-snapshot-field-ranges: Snapshot Files. (line 111)
+* show-snapshot-field-ranges, summary: Option Summary. (line 885)
+* show-stored-names: list. (line 68)
+* show-stored-names, summary: Option Summary. (line 891)
+* show-transformed-names: transform. (line 45)
+* show-transformed-names, summary: Option Summary. (line 891)
+* skip-old-files, introduced: Dealing with Old Files.
+ (line 28)
+* skip-old-files, summary: Option Summary. (line 900)
+* sort, summary: Option Summary. (line 913)
+* sparse: sparse. (line 24)
+* sparse, summary: Option Summary. (line 930)
+* sparse-version: sparse. (line 59)
+* sparse-version, summary: Option Summary. (line 936)
+* starting-file: Starting File. (line 6)
+* starting-file, summary: Option Summary. (line 942)
+* strip-components: transform. (line 25)
+* strip-components, summary: Option Summary. (line 949)
+* suffix: backup. (line 67)
+* suffix, summary: Option Summary. (line 960)
+* tape-length: Multi-Volume Archives.
+ (line 33)
+* tape-length, short description: Device. (line 96)
+* tape-length, summary: Option Summary. (line 965)
+* test-label: label. (line 35)
+* test-label, summary: Option Summary. (line 976)
+* to-command: Writing to an External Program.
+ (line 9)
+* to-command, summary: Option Summary. (line 981)
+* to-stdout: Writing to Standard Output.
+ (line 14)
+* to-stdout, summary: Option Summary. (line 986)
+* totals: verbose. (line 45)
+* totals, summary: Option Summary. (line 992)
+* touch: Data Modification Times.
+ (line 15)
+* touch <1>: Attributes. (line 33)
+* touch, summary: Option Summary. (line 998)
+* transform: transform. (line 74)
+* transform, summary: Option Summary. (line 1005)
+* uncompress: gzip. (line 113)
+* uncompress, summary: Option Summary. (line 164)
+* uncompress, summary <1>: Option Summary. (line 1019)
+* ungzip: gzip. (line 91)
+* ungzip, summary: Option Summary. (line 360)
+* ungzip, summary <1>: Option Summary. (line 1023)
+* unlink-first: Unlink First. (line 6)
+* unlink-first, introduced: Dealing with Old Files.
+ (line 51)
+* unlink-first, summary: Option Summary. (line 1027)
+* unquote: Selecting Archive Members.
+ (line 39)
+* unquote, summary: Option Summary. (line 1033)
+* update: update. (line 6)
+* update <1>: how to update. (line 6)
+* update, summary: Operation Summary. (line 60)
+* usage: help. (line 53)
+* use-compress-program: gzip. (line 172)
+* use-compress-program, summary: Option Summary. (line 1037)
+* utc, summary: Option Summary. (line 1043)
+* verbatim-files-from: files. (line 70)
+* verbatim-files-from, summary: Option Summary. (line 1048)
+* verbose: verbose. (line 18)
+* verbose, introduced: verbose tutorial. (line 6)
+* verbose, summary: Option Summary. (line 1070)
+* verbose, using with '--create': create verbose. (line 6)
+* verbose, using with '--list': list. (line 34)
+* verify, short description: verify. (line 8)
+* verify, summary: Option Summary. (line 1078)
+* verify, using with '--create': verify. (line 24)
+* version: help. (line 6)
+* version, summary: Option Summary. (line 1084)
+* volno-file: Multi-Volume Archives.
+ (line 74)
+* volno-file, summary: Option Summary. (line 1090)
+* warning, explained: warnings. (line 12)
+* warning, summary: Option Summary. (line 1096)
+* wildcards: controlling pattern-matching.
+ (line 38)
+* wildcards, summary: Option Summary. (line 1102)
+* wildcards-match-slash: controlling pattern-matching.
+ (line 91)
+* wildcards-match-slash, summary: Option Summary. (line 1106)
+* xattrs, summary: Option Summary. (line 1109)
+* xattrs-exclude, summary: Option Summary. (line 1113)
+* xattrs-include, summary: Option Summary. (line 1117)
+* xform: transform. (line 74)
+* xform, summary: Option Summary. (line 1005)
+* xz: gzip. (line 96)
+* xz, summary: Option Summary. (line 1123)
+
+
+File: tar.info, Node: Index, Prev: Index of Command Line Options, Up: Top
+
+Appendix I Index
+****************
+
+
+* Menu:
+
+* '%s: Directory has been renamed from %s', warning message: warnings.
+ (line 96)
+* '%s: Directory has been renamed', warning message: warnings.
+ (line 96)
+* '%s: Directory is new', warning message: warnings. (line 98)
+* '%s: directory is on a different device: not purging', warning message: warnings.
+ (line 100)
+* '%s: skipping existing file', warning message: warnings. (line 62)
+* -after-date and -update compared: after. (line 19)
+* -newer-mtime and -update compared: after. (line 19)
+* -quite, option: Generate Mode. (line 120)
+* .bzrignore: exclude. (line 63)
+* .cvsignore: exclude. (line 50)
+* .gitignore: exclude. (line 55)
+* .hgignore: exclude. (line 70)
+* 'A lone zero block at', warning message: warnings. (line 33)
+* abbreviations for months: Calendar date items. (line 38)
+* absolute file names: absolute. (line 6)
+* absolute file names <1>: Remote Tape Server. (line 17)
+* Adding archives to an archive: concatenate. (line 6)
+* Adding files to an Archive: appending files. (line 6)
+* ADMINISTRATOR: General-Purpose Variables.
+ (line 6)
+* Age, excluding files by: after. (line 6)
+* ago in date strings: Relative items in date strings.
+ (line 23)
+* all: warnings. (line 28)
+* alone-zero-block: warnings. (line 33)
+* alternative decompression programs: gzip. (line 54)
+* am in date strings: Time of day items. (line 21)
+* Appending files to an Archive: appending files. (line 6)
+* appending files to existing archive: append. (line 6)
+* Arch, excluding files: exclude. (line 85)
+* archive: Definitions. (line 6)
+* Archive creation: file. (line 34)
+* archive member: Definitions. (line 15)
+* Archive Name: file. (line 6)
+* Archive, creation of: create. (line 6)
+* Archives, Appending files to: appending files. (line 6)
+* archives, binary equivalent: PAX keywords. (line 136)
+* Archiving Directories: create dir. (line 6)
+* archiving files: Top. (line 23)
+* ARGP_HELP_FMT, environment variable: Configuring Help Summary.
+ (line 21)
+* arguments to long options: Long Options. (line 31)
+* arguments to old options: Old Options. (line 26)
+* arguments to short options: Short Options. (line 13)
+* 'Attempting extraction of symbolic links as hard links', warning message: warnings.
+ (line 68)
+* attributes, files: Attributes. (line 6)
+* authors of 'parse_datetime': Authors of parse_datetime.
+ (line 6)
+* Avoiding recursion in directories: recurse. (line 6)
+* backup options: backup. (line 6)
+* backup suffix: backup. (line 67)
+* backups: backup. (line 41)
+* backups <1>: Backups. (line 6)
+* BACKUP_DIRS: General-Purpose Variables.
+ (line 30)
+* BACKUP_FILES: General-Purpose Variables.
+ (line 58)
+* BACKUP_HOUR: General-Purpose Variables.
+ (line 10)
+* bad-dumpdir: warnings. (line 102)
+* basic operations: Operations. (line 6)
+* Bazaar, excluding files: exclude. (line 85)
+* Bazaar, ignore files: exclude. (line 37)
+* beginning of time, for POSIX: Seconds since the Epoch.
+ (line 13)
+* 'bell', checkpoint action: checkpoints. (line 106)
+* Bellovin, Steven M.: Authors of parse_datetime.
+ (line 6)
+* Berets, Jim: Authors of parse_datetime.
+ (line 6)
+* Berry, K.: Authors of parse_datetime.
+ (line 19)
+* binary equivalent archives, creating: PAX keywords. (line 136)
+* block: Blocking. (line 6)
+* Block number where error occurred: verbose. (line 112)
+* BLOCKING: General-Purpose Variables.
+ (line 25)
+* Blocking Factor: Blocking Factor. (line 6)
+* blocking factor: Blocking Factor. (line 189)
+* Blocks per record: Blocking Factor. (line 6)
+* bug reports: Reports. (line 6)
+* Bytes per record: Blocking Factor. (line 6)
+* bzip2: gzip. (line 6)
+* cachedir: warnings. (line 40)
+* calendar date item: Calendar date items. (line 6)
+* case, ignored in dates: General date syntax. (line 60)
+* 'cat' vs 'concatenate': concatenate. (line 63)
+* Changing directory mid-stream: directory. (line 6)
+* Character class, excluding characters from: wildcards. (line 34)
+* checkpoints, defined: checkpoints. (line 6)
+* Choosing an archive file: file. (line 6)
+* combined date and time of day item: Combined date and time of day items.
+ (line 6)
+* comments, in dates: General date syntax. (line 60)
+* compress: gzip. (line 6)
+* Compressed archives: gzip. (line 6)
+* 'concatenate' vs 'cat': concatenate. (line 63)
+* Concatenating Archives: concatenate. (line 6)
+* 'contains a cache directory tag', warning message: warnings.
+ (line 40)
+* contiguous-cast: warnings. (line 66)
+* corrupted archives: Full Dumps. (line 8)
+* corrupted archives <1>: gzip. (line 140)
+* Creation of the archive: create. (line 6)
+* 'Current %s is newer or same age', warning message: warnings.
+ (line 72)
+* CVS, excluding files: exclude. (line 85)
+* CVS, ignore files: exclude. (line 37)
+* Darcs, excluding files: exclude. (line 85)
+* DAT blocking: Blocking Factor. (line 199)
+* Data Modification time, excluding files by: after. (line 6)
+* Data modification times of extracted files: Data Modification Times.
+ (line 6)
+* date and time of day format, ISO 8601: Combined date and time of day items.
+ (line 6)
+* date format, ISO 8601: Calendar date items. (line 30)
+* date input formats: Date input formats. (line 6)
+* day in date strings: Relative items in date strings.
+ (line 15)
+* day in date strings <1>: Relative items in date strings.
+ (line 29)
+* day of week item: Day of week items. (line 6)
+* decompress-program: warnings. (line 76)
+* Deleting files from an archive: delete. (line 6)
+* Deleting from tape archives: delete. (line 17)
+* dereferencing hard links: hard links. (line 6)
+* Descending directories, avoiding: recurse. (line 6)
+* Device numbers, changing: Fixing Snapshot Files.
+ (line 6)
+* Device numbers, using in incremental backups: Incremental Dumps.
+ (line 89)
+* Directories, Archiving: create dir. (line 6)
+* Directories, avoiding recursion: recurse. (line 6)
+* Directory, changing mid-stream: directory. (line 6)
+* DIRLIST: General-Purpose Variables.
+ (line 53)
+* displacement of dates: Relative items in date strings.
+ (line 6)
+* doc-opt-col: Configuring Help Summary.
+ (line 95)
+* 'door ignored', warning message: warnings. (line 45)
+* 'dot', checkpoint action: checkpoints. (line 130)
+* Double-checking a write operation: verify. (line 6)
+* dumps, full: Full Dumps. (line 8)
+* DUMP_BEGIN: User Hooks. (line 31)
+* DUMP_END: User Hooks. (line 35)
+* DUMP_REMIND_SCRIPT: General-Purpose Variables.
+ (line 112)
+* dup-args: Configuring Help Summary.
+ (line 52)
+* dup-args-note: Configuring Help Summary.
+ (line 69)
+* 'echo', checkpoint action: checkpoints. (line 25)
+* Eggert, Paul: Authors of parse_datetime.
+ (line 6)
+* End-of-archive blocks, ignoring: Ignore Zeros. (line 6)
+* End-of-archive info script: Multi-Volume Archives.
+ (line 83)
+* entry: Naming tar Archives. (line 11)
+* epoch, for POSIX: Seconds since the Epoch.
+ (line 13)
+* Error message, block number of: verbose. (line 122)
+* Exabyte blocking: Blocking Factor. (line 199)
+* exclude: exclude. (line 12)
+* exclude-caches: exclude. (line 122)
+* exclude-from: exclude. (line 25)
+* exclude-tag: exclude. (line 145)
+* Excluding characters from a character class: wildcards. (line 34)
+* Excluding file by age: after. (line 6)
+* Excluding files by file system: exclude. (line 6)
+* Excluding files by name and pattern: exclude. (line 6)
+* Exec Mode, 'genfile': Exec Mode. (line 6)
+* 'exec', checkpoint action: checkpoints. (line 151)
+* existing backup method: backup. (line 59)
+* existing-file: warnings. (line 62)
+* exit status: Synopsis. (line 67)
+* 'Extracting contiguous files as regular files', warning message: warnings.
+ (line 66)
+* extracting Nth copy of the file: append. (line 34)
+* extraction: Definitions. (line 22)
+* Extraction: extract. (line 6)
+* file archival: Top. (line 23)
+* file attributes: Attributes. (line 6)
+* 'file changed as we read it', warning message: warnings. (line 55)
+* 'file is on a different filesystem', warning message: warnings.
+ (line 43)
+* 'file is the archive; not dumped', warning message: warnings.
+ (line 51)
+* 'file is the archive; not dumped', warning message <1>: warnings.
+ (line 51)
+* 'file is unchanged; not dumped', warning message: warnings. (line 49)
+* File lists separated by NUL characters: Generate Mode. (line 33)
+* file name: Definitions. (line 15)
+* File Name arguments, alternatives: files. (line 6)
+* File name arguments, using '--list' with: list. (line 25)
+* 'file name read contains nul character', warning message: warnings.
+ (line 31)
+* file names, absolute: absolute. (line 6)
+* File names, excluding files by: exclude. (line 6)
+* File names, terminated by 'NUL': nul. (line 6)
+* File names, using hard links: hard links. (line 6)
+* File names, using symbolic links: dereference. (line 6)
+* 'File removed before we read it', warning message: warnings.
+ (line 53)
+* 'File shrank by %s bytes', warning message: warnings. (line 41)
+* File system boundaries, not crossing: one. (line 6)
+* file-changed: warnings. (line 55)
+* file-ignored: warnings. (line 45)
+* file-removed: warnings. (line 53)
+* file-shrank: warnings. (line 41)
+* file-unchanged: warnings. (line 49)
+* FILELIST: General-Purpose Variables.
+ (line 69)
+* filename-with-nuls: warnings. (line 31)
+* 'find', using with 'tar': files. (line 6)
+* 'find', using with 'tar' <1>: recurse. (line 11)
+* first in date strings: General date syntax. (line 22)
+* format 0, snapshot file: Snapshot Files. (line 24)
+* format 1, snapshot file: Snapshot Files. (line 51)
+* format 2, snapshot file: Snapshot Files. (line 73)
+* Format Options: Format Variations. (line 6)
+* Format Parameters: Format Variations. (line 6)
+* Format, old style: old. (line 6)
+* fortnight in date strings: Relative items in date strings.
+ (line 15)
+* free documentation: Free Software Needs Free Documentation.
+ (line 6)
+* full dumps: Full Dumps. (line 8)
+* future time stamps: Large or Negative Values.
+ (line 6)
+* general date syntax: General date syntax. (line 6)
+* Generate Mode, 'genfile': Generate Mode. (line 6)
+* genfile: Genfile. (line 6)
+* 'genfile', create file: Generate Mode. (line 6)
+* 'genfile', creating sparse files: Generate Mode. (line 55)
+* 'genfile', generate mode: Generate Mode. (line 6)
+* 'genfile', reading a list of file names: Generate Mode. (line 22)
+* 'genfile', seeking to a given offset: Generate Mode. (line 18)
+* Getting program version number: help. (line 6)
+* git, excluding files: exclude. (line 85)
+* Git, ignore files: exclude. (line 37)
+* GNU archive format: gnu. (line 6)
+* GNU.sparse.major, extended header variable: PAX 1. (line 14)
+* GNU.sparse.map, extended header variable: PAX 0. (line 59)
+* GNU.sparse.minor, extended header variable: PAX 1. (line 17)
+* GNU.sparse.name, extended header variable: PAX 0. (line 67)
+* GNU.sparse.name, extended header variable, in v.1.0: PAX 1. (line 24)
+* GNU.sparse.numblocks, extended header variable: PAX 0. (line 14)
+* GNU.sparse.numbytes, extended header variable: PAX 0. (line 20)
+* GNU.sparse.offset, extended header variable: PAX 0. (line 17)
+* GNU.sparse.realsize, extended header variable: PAX 1. (line 24)
+* GNU.sparse.size, extended header variable: PAX 0. (line 10)
+* gnupg, using with tar: gzip. (line 196)
+* gpg, using with tar: gzip. (line 196)
+* gzip: gzip. (line 6)
+* hard links, dereferencing: hard links. (line 6)
+* header-col: Configuring Help Summary.
+ (line 141)
+* hole detection: sparse. (line 66)
+* hook: User Hooks. (line 12)
+* hour in date strings: Relative items in date strings.
+ (line 15)
+* ignore-archive: warnings. (line 51)
+* ignore-archive <1>: warnings. (line 51)
+* ignore-newer: warnings. (line 72)
+* Ignoring end-of-archive blocks: Ignore Zeros. (line 6)
+* 'Ignoring unknown extended header keyword '%s'', warning message: warnings.
+ (line 74)
+* 'implausibly old time stamp %s', warning message: warnings. (line 63)
+* Info script: Multi-Volume Archives.
+ (line 83)
+* Interactive operation: interactive. (line 6)
+* ISO 8601 date and time of day format: Combined date and time of day items.
+ (line 6)
+* ISO 8601 date format: Calendar date items. (line 30)
+* items in date strings: General date syntax. (line 6)
+* Labeling an archive: label. (line 6)
+* labeling archives: Tape Files. (line 6)
+* Labeling multi-volume archives: label. (line 6)
+* Labels on the archive media: label. (line 6)
+* language, in dates: General date syntax. (line 36)
+* language, in dates <1>: General date syntax. (line 40)
+* Large lists of file names on small machines: Same Order. (line 6)
+* large values: Large or Negative Values.
+ (line 6)
+* last DAY: Day of week items. (line 15)
+* last in date strings: General date syntax. (line 22)
+* Laszlo Ersek: lbzip2. (line 6)
+* lbzip2: lbzip2. (line 6)
+* leap seconds: General date syntax. (line 65)
+* leap seconds <1>: Time of day items. (line 14)
+* leap seconds <2>: Seconds since the Epoch.
+ (line 26)
+* Listing all 'tar' options: help. (line 26)
+* listing member and file names: list. (line 45)
+* Listing volume label: label. (line 27)
+* Lists of file names: files. (line 6)
+* Local and remote archives: file. (line 70)
+* long options: Long Options. (line 6)
+* long options with mandatory arguments: Long Options. (line 31)
+* long options with optional arguments: Long Options. (line 39)
+* long-opt-col: Configuring Help Summary.
+ (line 87)
+* lzip: gzip. (line 6)
+* lzma: gzip. (line 6)
+* lzop: gzip. (line 6)
+* MacKenzie, David: Authors of parse_datetime.
+ (line 6)
+* 'Malformed dumpdir: 'X' never used', warning message: warnings.
+ (line 102)
+* member: Definitions. (line 15)
+* member name: Definitions. (line 15)
+* members, multiple: multiple. (line 6)
+* Members, replacing with other members: append. (line 47)
+* Mercurial, excluding files: exclude. (line 85)
+* Mercurial, ignore files: exclude. (line 37)
+* Meyering, Jim: Authors of parse_datetime.
+ (line 6)
+* Middle of the archive, starting in the: Starting File. (line 11)
+* midnight in date strings: Time of day items. (line 21)
+* minute in date strings: Relative items in date strings.
+ (line 15)
+* minutes, time zone correction by: Time of day items. (line 29)
+* Modes of extracted files: Setting Access Permissions.
+ (line 6)
+* Modification time, excluding files by: after. (line 6)
+* Modification times of extracted files: Data Modification Times.
+ (line 6)
+* month in date strings: Relative items in date strings.
+ (line 15)
+* month names in date strings: Calendar date items. (line 38)
+* months, written-out: General date syntax. (line 32)
+* MT: General-Purpose Variables.
+ (line 74)
+* MT_BEGIN: Magnetic Tape Control.
+ (line 10)
+* MT_OFFLINE: Magnetic Tape Control.
+ (line 30)
+* MT_REWIND: Magnetic Tape Control.
+ (line 20)
+* MT_STATUS: Magnetic Tape Control.
+ (line 40)
+* Multi-volume archives: Multi-Volume Archives.
+ (line 6)
+* Multi-volume archives in PAX format, extracting using non-GNU tars: Split Recovery.
+ (line 17)
+* Multi-volume archives, extracting using non-GNU tars: Split Recovery.
+ (line 6)
+* multiple members: multiple. (line 6)
+* Naming an archive: file. (line 6)
+* negative time stamps: Large or Negative Values.
+ (line 6)
+* new-directory: warnings. (line 98)
+* next DAY: Day of week items. (line 15)
+* next in date strings: General date syntax. (line 22)
+* none: warnings. (line 29)
+* noon in date strings: Time of day items. (line 21)
+* now in date strings: Relative items in date strings.
+ (line 33)
+* ntape device: Many. (line 6)
+* 'NUL'-terminated file names: nul. (line 6)
+* Number of blocks per record: Blocking Factor. (line 6)
+* Number of bytes per record: Blocking Factor. (line 6)
+* numbered backup method: backup. (line 55)
+* numbers, written-out: General date syntax. (line 22)
+* Obtaining help: help. (line 26)
+* Obtaining total status information: verbose. (line 45)
+* Old GNU archive format: gnu. (line 6)
+* Old GNU sparse format: Old GNU Format. (line 6)
+* old option style: Old Options. (line 6)
+* old options with mandatory arguments: Old Options. (line 26)
+* Old style archives: old. (line 6)
+* Old style format: old. (line 6)
+* opt-doc-col: Configuring Help Summary.
+ (line 127)
+* option syntax, traditional: Old Options. (line 6)
+* optional arguments to long options: Long Options. (line 39)
+* optional arguments to short options: Short Options. (line 22)
+* options for use with '--extract': extract options. (line 6)
+* Options when reading archives: Reading. (line 6)
+* Options, archive format specifying: Format Variations. (line 6)
+* Options, format specifying: Format Variations. (line 6)
+* options, GNU style: Long Options. (line 6)
+* options, long style: Long Options. (line 6)
+* options, mixing different styles: Mixing. (line 6)
+* options, mnemonic names: Long Options. (line 6)
+* options, old style: Old Options. (line 6)
+* options, short style: Short Options. (line 6)
+* options, traditional: Short Options. (line 6)
+* ordinal numbers: General date syntax. (line 22)
+* Overwriting old files, prevention: Dealing with Old Files.
+ (line 16)
+* parse_datetime: Date input formats. (line 6)
+* pattern, 'genfile': Generate Mode. (line 39)
+* PAX archive format: posix. (line 6)
+* Permissions of extracted files: Setting Access Permissions.
+ (line 6)
+* Pinard, F.: Authors of parse_datetime.
+ (line 19)
+* pm in date strings: Time of day items. (line 21)
+* POSIX archive format: posix. (line 6)
+* Progress information: verbose. (line 82)
+* Protecting old files: Dealing with Old Files.
+ (line 36)
+* pure numbers in date strings: Pure numbers in date strings.
+ (line 6)
+* RCS, excluding files: exclude. (line 85)
+* Reading file names from a file: files. (line 6)
+* Reading incomplete records: Reading. (line 6)
+* record: Blocking. (line 6)
+* Record Size: Blocking Factor. (line 6)
+* 'Record size = %lu blocks', warning message: warnings. (line 89)
+* record-size: warnings. (line 89)
+* Records, incomplete: Reading. (line 6)
+* Recursion in directories, avoiding: recurse. (line 6)
+* relative items in date strings: Relative items in date strings.
+ (line 6)
+* Remote devices: file. (line 60)
+* remote tape drive: Remote Tape Server. (line 6)
+* Removing files from an archive: delete. (line 6)
+* rename-directory: warnings. (line 96)
+* Replacing members with other members: append. (line 47)
+* reporting bugs: Reports. (line 6)
+* RESTORE_BEGIN: User Hooks. (line 38)
+* RESTORE_END: User Hooks. (line 41)
+* Resurrecting files from an archive: extract. (line 6)
+* Retrieving files from an archive: extract. (line 6)
+* return status: Synopsis. (line 67)
+* rmargin: Configuring Help Summary.
+ (line 159)
+* rmt: Remote Tape Server. (line 6)
+* RSH: General-Purpose Variables.
+ (line 78)
+* RSH_COMMAND: General-Purpose Variables.
+ (line 83)
+* Running out of space: Scarce. (line 8)
+* Salz, Rich: Authors of parse_datetime.
+ (line 6)
+* SCCS, excluding files: exclude. (line 85)
+* short options: Short Options. (line 6)
+* short options with mandatory arguments: Short Options. (line 13)
+* short options with optional arguments: Short Options. (line 22)
+* short-opt-col: Configuring Help Summary.
+ (line 79)
+* simple backup method: backup. (line 64)
+* SIMPLE_BACKUP_SUFFIX: backup. (line 67)
+* 'sleep', checkpoint action: checkpoints. (line 145)
+* SLEEP_MESSAGE: General-Purpose Variables.
+ (line 121)
+* SLEEP_TIME: General-Purpose Variables.
+ (line 106)
+* Small memory: Scarce. (line 8)
+* snapshot file field ranges: Snapshot Files. (line 111)
+* snapshot file, format 0: Snapshot Files. (line 24)
+* snapshot file, format 1: Snapshot Files. (line 51)
+* snapshot file, format 2: Snapshot Files. (line 73)
+* snapshot files, editing: Fixing Snapshot Files.
+ (line 6)
+* snapshot files, fixing device numbers: Fixing Snapshot Files.
+ (line 6)
+* 'socket ignored', warning message: warnings. (line 45)
+* Sparse Files: sparse. (line 6)
+* sparse files v.0.0, extracting with non-GNU tars: Sparse Recovery.
+ (line 92)
+* sparse files v.0.1, extracting with non-GNU tars: Sparse Recovery.
+ (line 92)
+* sparse files v.1.0, extracting with non-GNU tars: Sparse Recovery.
+ (line 17)
+* Sparse files, creating using 'genfile': Generate Mode. (line 55)
+* sparse files, extracting with non-GNU tars: Sparse Recovery.
+ (line 6)
+* sparse formats: Sparse Formats. (line 6)
+* sparse formats, defined: sparse. (line 52)
+* sparse formats, Old GNU: Old GNU Format. (line 6)
+* sparse formats, v.0.0: PAX 0. (line 6)
+* sparse formats, v.0.1: PAX 0. (line 51)
+* sparse formats, v.1.0: PAX 1. (line 6)
+* sparse versions: Sparse Formats. (line 6)
+* Specifying archive members: Selecting Archive Members.
+ (line 6)
+* Specifying files to act on: Selecting Archive Members.
+ (line 6)
+* Standard input and output: file. (line 39)
+* Standard output, writing extracted files to: Writing to Standard Output.
+ (line 6)
+* Storing archives in compressed format: gzip. (line 6)
+* SVN, excluding files: exclude. (line 85)
+* Symbolic link as file name: dereference. (line 6)
+* symlink-cast: warnings. (line 68)
+* TAPE: file tutorial. (line 14)
+* tape blocking: Blocking Factor. (line 189)
+* tape marks: Many. (line 43)
+* tape positioning: Many. (line 26)
+* Tapes, using '--delete' and: delete. (line 17)
+* TAPE_FILE: General-Purpose Variables.
+ (line 18)
+* tar: What tar Does. (line 6)
+* TAR: General-Purpose Variables.
+ (line 126)
+* tar archive: Definitions. (line 6)
+* Tar archive formats: Formats. (line 6)
+* tar entry: Naming tar Archives. (line 11)
+* tar file: Naming tar Archives. (line 11)
+* tar to a remote device: file. (line 60)
+* tar to standard input and output: file. (line 39)
+* tar-snapshot-edit: Fixing Snapshot Files.
+ (line 17)
+* tarcat: Tarcat. (line 6)
+* TAR_ARCHIVE, checkpoint script environment: checkpoints. (line 167)
+* TAR_ARCHIVE, info script environment variable: Multi-Volume Archives.
+ (line 105)
+* TAR_ARCHIVE, to-command environment: Writing to an External Program.
+ (line 79)
+* TAR_ATIME, to-command environment: Writing to an External Program.
+ (line 52)
+* TAR_BLOCKING_FACTOR, checkpoint script environment: checkpoints.
+ (line 170)
+* TAR_BLOCKING_FACTOR, info script environment variable: Multi-Volume Archives.
+ (line 108)
+* TAR_BLOCKING_FACTOR, to-command environment: Writing to an External Program.
+ (line 82)
+* TAR_CHECKPOINT, checkpoint script environment: checkpoints. (line 173)
+* TAR_CTIME, to-command environment: Writing to an External Program.
+ (line 61)
+* TAR_FD, info script environment variable: Multi-Volume Archives.
+ (line 122)
+* TAR_FILENAME, to-command environment: Writing to an External Program.
+ (line 40)
+* TAR_FILETYPE, to-command environment: Writing to an External Program.
+ (line 24)
+* TAR_FORMAT, checkpoint script environment: checkpoints. (line 180)
+* TAR_FORMAT, info script environment variable: Multi-Volume Archives.
+ (line 118)
+* TAR_FORMAT, to-command environment: Writing to an External Program.
+ (line 88)
+* TAR_GID, to-command environment: Writing to an External Program.
+ (line 70)
+* TAR_GNAME, to-command environment: Writing to an External Program.
+ (line 49)
+* TAR_MODE, to-command environment: Writing to an External Program.
+ (line 37)
+* TAR_MTIME, to-command environment: Writing to an External Program.
+ (line 58)
+* TAR_OPTIONS, environment variable: using tar options. (line 30)
+* TAR_REALNAME, to-command environment: Writing to an External Program.
+ (line 43)
+* TAR_SIZE, to-command environment: Writing to an External Program.
+ (line 64)
+* TAR_SUBCOMMAND, checkpoint script environment: checkpoints. (line 176)
+* TAR_SUBCOMMAND, info script environment variable: Multi-Volume Archives.
+ (line 114)
+* TAR_UID, to-command environment: Writing to an External Program.
+ (line 67)
+* TAR_UNAME, to-command environment: Writing to an External Program.
+ (line 46)
+* TAR_VERSION, checkpoint script environment: checkpoints. (line 164)
+* TAR_VERSION, info script environment variable: Multi-Volume Archives.
+ (line 102)
+* TAR_VERSION, to-command environment: Writing to an External Program.
+ (line 76)
+* TAR_VOLUME, info script environment variable: Multi-Volume Archives.
+ (line 111)
+* TAR_VOLUME, to-command environment: Writing to an External Program.
+ (line 85)
+* this in date strings: Relative items in date strings.
+ (line 33)
+* time of day item: Time of day items. (line 6)
+* 'time stamp %s is %s s in the future', warning message: warnings.
+ (line 63)
+* time zone correction: Time of day items. (line 29)
+* time zone item: General date syntax. (line 40)
+* time zone item <1>: Time zone items. (line 6)
+* timestamp: warnings. (line 63)
+* today in date strings: Relative items in date strings.
+ (line 33)
+* tomorrow in date strings: Relative items in date strings.
+ (line 29)
+* 'totals', checkpoint action: checkpoints. (line 140)
+* 'ttyout', checkpoint action: checkpoints. (line 111)
+* TZ: Specifying time zone rules.
+ (line 6)
+* Ultrix 3.1 and write failure: Remote Tape Server. (line 40)
+* 'Unknown file type '%c', extracted as normal file', warning message: warnings.
+ (line 70)
+* 'Unknown file type; file ignored', warning message: warnings.
+ (line 45)
+* unknown-cast: warnings. (line 70)
+* unknown-keyword: warnings. (line 74)
+* unpacking: Definitions. (line 22)
+* Updating an archive: update. (line 6)
+* usage-indent: Configuring Help Summary.
+ (line 155)
+* Using encrypted archives: gzip. (line 196)
+* ustar archive format: ustar. (line 6)
+* uuencode: Applications. (line 8)
+* v7 archive format: old. (line 6)
+* VCS, excluding files: exclude. (line 85)
+* VCS, excluding patterns from ignore files: exclude. (line 37)
+* VCS, ignore files: exclude. (line 37)
+* Verbose operation: verbose. (line 18)
+* Verifying a write operation: verify. (line 6)
+* Verifying the currency of an archive: compare. (line 6)
+* version control system, excluding files: exclude. (line 85)
+* Version of the 'tar' program: help. (line 6)
+* version-control Emacs variable: backup. (line 49)
+* VERSION_CONTROL: backup. (line 41)
+* volno file: Multi-Volume Archives.
+ (line 74)
+* VOLNO_FILE: General-Purpose Variables.
+ (line 89)
+* Volume label, listing: label. (line 27)
+* Volume number file: Multi-Volume Archives.
+ (line 74)
+* week in date strings: Relative items in date strings.
+ (line 15)
+* Where is the archive?: file. (line 6)
+* Working directory, specifying: directory. (line 6)
+* Writing extracted files to standard output: Writing to Standard Output.
+ (line 6)
+* Writing new archives: file. (line 34)
+* xdev: warnings. (line 43)
+* xdev <1>: warnings. (line 100)
+* XLIST: General-Purpose Variables.
+ (line 95)
+* xsparse: Sparse Recovery. (line 13)
+* year in date strings: Relative items in date strings.
+ (line 15)
+* yesterday in date strings: Relative items in date strings.
+ (line 29)
+
diff --git a/doc/tar.texi b/doc/tar.texi
new file mode 100644
index 0000000..a8969e0
--- /dev/null
+++ b/doc/tar.texi
@@ -0,0 +1,13252 @@
+\input texinfo @c -*-texinfo-*-
+@comment %**start of header
+@setfilename tar.info
+@include version.texi
+@settitle GNU tar @value{VERSION}
+@setchapternewpage odd
+
+@finalout
+
+@smallbook
+@c %**end of header
+
+@c Maintenance notes:
+@c 1. Pay attention to @FIXME{}s and @UNREVISED{}s
+@c 2. Before creating final variant:
+@c 2.1. Run 'make check-options' to make sure all options are properly
+@c documented;
+@c 2.2. Run 'make master-menu' (see comment before the master menu).
+
+@include rendition.texi
+@include value.texi
+
+@defcodeindex op
+@defcodeindex kw
+
+@c Put everything in one index (arbitrarily chosen to be the concept index).
+@syncodeindex fn cp
+@syncodeindex ky cp
+@syncodeindex pg cp
+@syncodeindex vr cp
+@syncodeindex kw cp
+
+@copying
+
+This manual is for @acronym{GNU} @command{tar} (version
+@value{VERSION}, @value{UPDATED}), which creates and extracts files
+from archives.
+
+Copyright @copyright{} 1992, 1994--1997, 1999--2001, 2003--2016 Free
+Software Foundation, Inc.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with the
+Invariant Sections being ``GNU General Public License'', with the
+Front-Cover Texts being ``A GNU Manual'', and with the Back-Cover Texts
+as in (a) below. A copy of the license is included in the section
+entitled ``GNU Free Documentation License''.
+
+(a) The FSF's Back-Cover Text is: ``You have the freedom to
+copy and modify this GNU manual.''
+@end quotation
+@end copying
+
+@dircategory Archiving
+@direntry
+* Tar: (tar). Making tape (or disk) archives.
+@end direntry
+
+@dircategory Individual utilities
+@direntry
+* tar: (tar)tar invocation. Invoking @GNUTAR{}.
+@end direntry
+
+@shorttitlepage @acronym{GNU} @command{tar}
+
+@titlepage
+@title @acronym{GNU} tar: an archiver tool
+@subtitle @value{RENDITION} @value{VERSION}, @value{UPDATED}
+@author John Gilmore, Jay Fenlason et al.
+
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@ifnottex
+@node Top
+@top @acronym{GNU} tar: an archiver tool
+
+@insertcopying
+
+@cindex file archival
+@cindex archiving files
+
+The first part of this master menu lists the major nodes in this Info
+document. The rest of the menu lists all the lower level nodes.
+@end ifnottex
+
+@c The master menu goes here.
+@c
+@c NOTE: To update it from within Emacs, make sure mastermenu.el is
+@c loaded and run texinfo-master-menu.
+@c To update it from the command line, run
+@c
+@c make master-menu
+
+@menu
+* Introduction::
+* Tutorial::
+* tar invocation::
+* operations::
+* Backups::
+* Choosing::
+* Date input formats::
+* Formats::
+* Media::
+* Reliability and security::
+
+Appendices
+
+* Changes::
+* Configuring Help Summary::
+* Fixing Snapshot Files::
+* Tar Internals::
+* Genfile::
+* Free Software Needs Free Documentation::
+* GNU Free Documentation License::
+* Index of Command Line Options::
+* Index::
+
+@detailmenu
+ --- The Detailed Node Listing ---
+
+Introduction
+
+* Book Contents:: What this Book Contains
+* Definitions:: Some Definitions
+* What tar Does:: What @command{tar} Does
+* Naming tar Archives:: How @command{tar} Archives are Named
+* Authors:: @GNUTAR{} Authors
+* Reports:: Reporting bugs or suggestions
+
+Tutorial Introduction to @command{tar}
+
+* assumptions::
+* stylistic conventions::
+* basic tar options:: Basic @command{tar} Operations and Options
+* frequent operations::
+* Two Frequent Options::
+* create:: How to Create Archives
+* list:: How to List Archives
+* extract:: How to Extract Members from an Archive
+* going further::
+
+Two Frequently Used Options
+
+* file tutorial::
+* verbose tutorial::
+* help tutorial::
+
+How to Create Archives
+
+* prepare for examples::
+* Creating the archive::
+* create verbose::
+* short create::
+* create dir::
+
+How to List Archives
+
+* list dir::
+
+How to Extract Members from an Archive
+
+* extracting archives::
+* extracting files::
+* extract dir::
+* extracting untrusted archives::
+* failing commands::
+
+Invoking @GNUTAR{}
+
+* Synopsis::
+* using tar options::
+* Styles::
+* All Options::
+* help::
+* defaults::
+* verbose::
+* checkpoints::
+* warnings::
+* interactive::
+
+The Three Option Styles
+
+* Long Options:: Long Option Style
+* Short Options:: Short Option Style
+* Old Options:: Old Option Style
+* Mixing:: Mixing Option Styles
+
+All @command{tar} Options
+
+* Operation Summary::
+* Option Summary::
+* Short Option Summary::
+* Position-Sensitive Options::
+
+@GNUTAR{} Operations
+
+* Basic tar::
+* Advanced tar::
+* create options::
+* extract options::
+* backup::
+* Applications::
+* looking ahead::
+
+Advanced @GNUTAR{} Operations
+
+* Operations::
+* append::
+* update::
+* concatenate::
+* delete::
+* compare::
+
+How to Add Files to Existing Archives: @option{--append}
+
+* appending files:: Appending Files to an Archive
+* multiple::
+
+Updating an Archive
+
+* how to update::
+
+Options Used by @option{--create}
+
+* override:: Overriding File Metadata.
+* Extended File Attributes::
+* Ignore Failed Read::
+
+Options Used by @option{--extract}
+
+* Reading:: Options to Help Read Archives
+* Writing:: Changing How @command{tar} Writes Files
+* Scarce:: Coping with Scarce Resources
+
+Options to Help Read Archives
+
+* read full records::
+* Ignore Zeros::
+
+Changing How @command{tar} Writes Files
+
+* Dealing with Old Files::
+* Overwrite Old Files::
+* Keep Old Files::
+* Keep Newer Files::
+* Unlink First::
+* Recursive Unlink::
+* Data Modification Times::
+* Setting Access Permissions::
+* Directory Modification Times and Permissions::
+* Writing to Standard Output::
+* Writing to an External Program::
+* remove files::
+
+Coping with Scarce Resources
+
+* Starting File::
+* Same Order::
+
+Performing Backups and Restoring Files
+
+* Full Dumps:: Using @command{tar} to Perform Full Dumps
+* Incremental Dumps:: Using @command{tar} to Perform Incremental Dumps
+* Backup Levels:: Levels of Backups
+* Backup Parameters:: Setting Parameters for Backups and Restoration
+* Scripted Backups:: Using the Backup Scripts
+* Scripted Restoration:: Using the Restore Script
+
+Setting Parameters for Backups and Restoration
+
+* General-Purpose Variables::
+* Magnetic Tape Control::
+* User Hooks::
+* backup-specs example:: An Example Text of @file{Backup-specs}
+
+Choosing Files and Names for @command{tar}
+
+* file:: Choosing the Archive's Name
+* Selecting Archive Members::
+* files:: Reading Names from a File
+* exclude:: Excluding Some Files
+* wildcards:: Wildcards Patterns and Matching
+* quoting styles:: Ways of Quoting Special Characters in Names
+* transform:: Modifying File and Member Names
+* after:: Operating Only on New Files
+* recurse:: Descending into Directories
+* one:: Crossing File System Boundaries
+
+Reading Names from a File
+
+* nul::
+
+Excluding Some Files
+
+* problems with exclude::
+
+Wildcards Patterns and Matching
+
+* controlling pattern-matching::
+
+Crossing File System Boundaries
+
+* directory:: Changing Directory
+* absolute:: Absolute File Names
+
+Date input formats
+
+* General date syntax:: Common rules.
+* Calendar date items:: 19 Dec 1994.
+* Time of day items:: 9:20pm.
+* Time zone items:: @sc{est}, @sc{pdt}, @sc{gmt}.
+* Day of week items:: Monday and others.
+* Relative items in date strings:: next tuesday, 2 years ago.
+* Pure numbers in date strings:: 19931219, 1440.
+* Seconds since the Epoch:: @@1078100502.
+* Specifying time zone rules:: TZ="America/New_York", TZ="UTC0".
+* Authors of parse_datetime:: Bellovin, Eggert, Salz, Berets, et al.
+
+Controlling the Archive Format
+
+* Compression:: Using Less Space through Compression
+* Attributes:: Handling File Attributes
+* Portability:: Making @command{tar} Archives More Portable
+* cpio:: Comparison of @command{tar} and @command{cpio}
+
+Using Less Space through Compression
+
+* gzip:: Creating and Reading Compressed Archives
+* sparse:: Archiving Sparse Files
+
+Creating and Reading Compressed Archives
+
+* lbzip2:: Using lbzip2 with @GNUTAR{}.
+
+Making @command{tar} Archives More Portable
+
+* Portable Names:: Portable Names
+* dereference:: Symbolic Links
+* hard links:: Hard Links
+* old:: Old V7 Archives
+* ustar:: Ustar Archives
+* gnu:: GNU and old GNU format archives.
+* posix:: @acronym{POSIX} archives
+* Checksumming:: Checksumming Problems
+* Large or Negative Values:: Large files, negative time stamps, etc.
+* Other Tars:: How to Extract GNU-Specific Data Using
+ Other @command{tar} Implementations
+
+@GNUTAR{} and @acronym{POSIX} @command{tar}
+
+* PAX keywords:: Controlling Extended Header Keywords.
+
+How to Extract GNU-Specific Data Using Other @command{tar} Implementations
+
+* Split Recovery:: Members Split Between Volumes
+* Sparse Recovery:: Sparse Members
+
+Tapes and Other Archive Media
+
+* Device:: Device selection and switching
+* Remote Tape Server::
+* Common Problems and Solutions::
+* Blocking:: Blocking
+* Many:: Many archives on one tape
+* Using Multiple Tapes:: Using Multiple Tapes
+* label:: Including a Label in the Archive
+* verify::
+* Write Protection::
+
+Blocking
+
+* Format Variations:: Format Variations
+* Blocking Factor:: The Blocking Factor of an Archive
+
+Many Archives on One Tape
+
+* Tape Positioning:: Tape Positions and Tape Marks
+* mt:: The @command{mt} Utility
+
+Using Multiple Tapes
+
+* Multi-Volume Archives:: Archives Longer than One Tape or Disk
+* Tape Files:: Tape Files
+* Tarcat:: Concatenate Volumes into a Single Archive
+
+
+Tar Internals
+
+* Standard:: Basic Tar Format
+* Extensions:: @acronym{GNU} Extensions to the Archive Format
+* Sparse Formats:: Storing Sparse Files
+* Snapshot Files::
+* Dumpdir::
+
+Storing Sparse Files
+
+* Old GNU Format::
+* PAX 0:: PAX Format, Versions 0.0 and 0.1
+* PAX 1:: PAX Format, Version 1.0
+
+Genfile
+
+* Generate Mode:: File Generation Mode.
+* Status Mode:: File Status Mode.
+* Exec Mode:: Synchronous Execution mode.
+
+Copying This Manual
+
+* GNU Free Documentation License:: License for copying this manual
+
+@end detailmenu
+@end menu
+
+@node Introduction
+@chapter Introduction
+
+@GNUTAR{} creates
+and manipulates @dfn{archives} which are actually collections of
+many other files; the program provides users with an organized and
+systematic method for controlling a large amount of data.
+The name ``tar'' originally came from the phrase ``Tape ARchive'', but
+archives need not (and these days, typically do not) reside on tapes.
+
+@menu
+* Book Contents:: What this Book Contains
+* Definitions:: Some Definitions
+* What tar Does:: What @command{tar} Does
+* Naming tar Archives:: How @command{tar} Archives are Named
+* Authors:: @GNUTAR{} Authors
+* Reports:: Reporting bugs or suggestions
+@end menu
+
+@node Book Contents
+@section What this Book Contains
+
+The first part of this chapter introduces you to various terms that will
+recur throughout the book. It also tells you who has worked on @GNUTAR{}
+and its documentation, and where you should send bug reports
+or comments.
+
+The second chapter is a tutorial (@pxref{Tutorial}) which provides a
+gentle introduction for people who are new to using @command{tar}. It is
+meant to be self-contained, not requiring any reading from subsequent
+chapters to make sense. It moves from topic to topic in a logical,
+progressive order, building on information already explained.
+
+Although the tutorial is paced and structured to allow beginners to
+learn how to use @command{tar}, it is not intended solely for beginners.
+The tutorial explains how to use the three most frequently used
+operations (@samp{create}, @samp{list}, and @samp{extract}) as well as
+two frequently used options (@samp{file} and @samp{verbose}). The other
+chapters do not refer to the tutorial frequently; however, if a section
+discusses something which is a complex variant of a basic concept, there
+may be a cross-reference to that basic concept. (The entire book,
+including the tutorial, assumes that the reader understands some basic
+concepts of using a Unix-type operating system; @pxref{Tutorial}.)
+
+The third chapter presents the remaining five operations, and
+information about using @command{tar} options and option syntax.
+
+The other chapters are meant to be used as a reference. Each chapter
+presents everything that needs to be said about a specific topic.
+
+One of the chapters (@pxref{Date input formats}) exists in its
+entirety in other @acronym{GNU} manuals, and is mostly self-contained.
+In addition, one section of this manual (@pxref{Standard}) contains a
+big quote which is taken directly from @command{tar} sources.
+
+In general, we give both long and short (abbreviated) option names
+at least once in each section where the relevant option is covered, so
+that novice readers will become familiar with both styles. (A few
+options have no short versions, and the relevant sections will
+indicate this.)
+
+@node Definitions
+@section Some Definitions
+
+@cindex archive
+@cindex tar archive
+The @command{tar} program is used to create and manipulate @command{tar}
+archives. An @dfn{archive} is a single file which contains the contents
+of many files, while still identifying the names of the files, their
+owner(s), and so forth. (In addition, archives record access
+permissions, user and group, size in bytes, and data modification time.
+Some archives also record the file names in each archived directory, as
+well as other file and directory information.) You can use @command{tar}
+to @dfn{create} a new archive in a specified directory.
+
+@cindex member
+@cindex archive member
+@cindex file name
+@cindex member name
+The files inside an archive are called @dfn{members}. Within this
+manual, we use the term @dfn{file} to refer only to files accessible in
+the normal ways (by @command{ls}, @command{cat}, and so forth), and the term
+@dfn{member} to refer only to the members of an archive. Similarly, a
+@dfn{file name} is the name of a file, as it resides in the file system,
+and a @dfn{member name} is the name of an archive member within the
+archive.
+
+@cindex extraction
+@cindex unpacking
+The term @dfn{extraction} refers to the process of copying an archive
+member (or multiple members) into a file in the file system. Extracting
+all the members of an archive is often called @dfn{extracting the
+archive}. The term @dfn{unpack} can also be used to refer to the
+extraction of many or all the members of an archive. Extracting an
+archive does not destroy the archive's structure, just as creating an
+archive does not destroy the copies of the files that exist outside of
+the archive. You may also @dfn{list} the members in a given archive
+(this is often thought of as ``printing'' them to the standard output,
+or the command line), or @dfn{append} members to a pre-existing archive.
+All of these operations can be performed using @command{tar}.
+
+@node What tar Does
+@section What @command{tar} Does
+
+@cindex tar
+The @command{tar} program provides the ability to create @command{tar}
+archives, as well as various other kinds of manipulation. For example,
+you can use @command{tar} on previously created archives to extract files,
+to store additional files, or to update or list files which were already
+stored.
+
+Initially, @command{tar} archives were used to store files conveniently on
+magnetic tape. The name @command{tar} comes from this use; it stands for
+@code{t}ape @code{ar}chiver. Despite the utility's name, @command{tar} can
+direct its output to available devices, files, or other programs (using
+pipes). @command{tar} may even access remote devices or files (as archives).
+
+You can use @command{tar} archives in many ways. We want to stress a few
+of them: storage, backup, and transportation.
+
+@FIXME{the following table entries need a bit of work.}
+@table @asis
+@item Storage
+Often, @command{tar} archives are used to store related files for
+convenient file transfer over a network. For example, the
+@acronym{GNU} Project distributes its software bundled into
+@command{tar} archives, so that all the files relating to a particular
+program (or set of related programs) can be transferred as a single
+unit.
+
+A magnetic tape can store several files in sequence. However, the tape
+has no names for these files; it only knows their relative position on
+the tape. One way to store several files on one tape and retain their
+names is by creating a @command{tar} archive. Even when the basic transfer
+mechanism can keep track of names, as FTP can, the nuisance of handling
+multiple files, directories, and multiple links makes @command{tar}
+archives useful.
+
+Archive files are also used for long-term storage. You can think of
+this as transportation from the present into the future. (It is a
+science-fiction idiom that you can move through time as well as in
+space; the idea here is that @command{tar} can be used to move archives in
+all dimensions, even time!)
+
+@item Backup
+Because the archive created by @command{tar} is capable of preserving
+file information and directory structure, @command{tar} is commonly
+used for performing full and incremental backups of disks. A backup
+puts a collection of files (possibly pertaining to many users and
+projects) together on a disk or a tape. This guards against
+accidental destruction of the information in those files.
+@GNUTAR{} has special features that allow it to be
+used to make incremental and full dumps of all the files in a
+file system.
+
+@item Transportation
+You can create an archive on one system, transfer it to another system,
+and extract the contents there. This allows you to transport a group of
+files from one system to another.
+@end table
+
+@node Naming tar Archives
+@section How @command{tar} Archives are Named
+
+Conventionally, @command{tar} archives are given names ending with
+@samp{.tar}. This is not necessary for @command{tar} to operate properly,
+but this manual follows that convention in order to accustom readers to
+it and to make examples more clear.
+
+@cindex tar file
+@cindex entry
+@cindex tar entry
+Often, people refer to @command{tar} archives as ``@command{tar} files,'' and
+archive members as ``files'' or ``entries''. For people familiar with
+the operation of @command{tar}, this causes no difficulty. However, in
+this manual, we consistently refer to ``archives'' and ``archive
+members'' to make learning to use @command{tar} easier for novice users.
+
+@node Authors
+@section @GNUTAR{} Authors
+
+@GNUTAR{} was originally written by John Gilmore,
+and modified by many people. The @acronym{GNU} enhancements were
+written by Jay Fenlason, then Joy Kendall, and the whole package has
+been further maintained by Thomas Bushnell, n/BSG, Fran@,{c}ois
+Pinard, Paul Eggert, and finally Sergey Poznyakoff with the help of
+numerous and kind users.
+
+We wish to stress that @command{tar} is a collective work, and owes much to
+all those people who reported problems, offered solutions and other
+insights, or shared their thoughts and suggestions. An impressive, yet
+partial list of those contributors can be found in the @file{THANKS}
+file from the @GNUTAR{} distribution.
+
+@FIXME{i want all of these names mentioned, Absolutely. BUT, i'm not
+sure i want to spell out the history in this detail, at least not for
+the printed book. i'm just not sure it needs to be said this way.
+i'll think about it.}
+
+@FIXME{History is more important, and surely more interesting, than
+actual names. Quoting names without history would be meaningless. FP}
+
+Jay Fenlason put together a draft of a @GNUTAR{}
+manual, borrowing notes from the original man page from John Gilmore.
+This was withdrawn in version 1.11. Thomas Bushnell, n/BSG and Amy
+Gorin worked on a tutorial and manual for @GNUTAR{}.
+Fran@,{c}ois Pinard put version 1.11.8 of the manual together by
+taking information from all these sources and merging them. Melissa
+Weisshaus finally edited and redesigned the book to create version
+1.12. The book for versions from 1.14 up to @value{VERSION} were edited
+by the current maintainer, Sergey Poznyakoff.
+
+For version 1.12, Daniel Hagerty contributed a great deal of technical
+consulting. In particular, he is the primary author of @ref{Backups}.
+
+In July, 2003 @GNUTAR{} was put on CVS at savannah.gnu.org
+(see @url{http://savannah.gnu.org/projects/tar}), and
+active development and maintenance work has started
+again. Currently @GNUTAR{} is being maintained by Paul Eggert, Sergey
+Poznyakoff and Jeff Bailey.
+
+Support for @acronym{POSIX} archives was added by Sergey Poznyakoff.
+
+@node Reports
+@section Reporting bugs or suggestions
+
+@cindex bug reports
+@cindex reporting bugs
+If you find problems or have suggestions about this program or manual,
+please report them to @file{bug-tar@@gnu.org}.
+
+When reporting a bug, please be sure to include as much detail as
+possible, in order to reproduce it.
+@FIXME{Be more specific, I'd like to make this node as detailed as
+'Bug reporting' node in Emacs manual.}
+
+@node Tutorial
+@chapter Tutorial Introduction to @command{tar}
+
+This chapter guides you through some basic examples of three @command{tar}
+operations: @option{--create}, @option{--list}, and @option{--extract}. If
+you already know how to use some other version of @command{tar}, then you
+may not need to read this chapter. This chapter omits most complicated
+details about how @command{tar} works.
+
+@menu
+* assumptions::
+* stylistic conventions::
+* basic tar options:: Basic @command{tar} Operations and Options
+* frequent operations::
+* Two Frequent Options::
+* create:: How to Create Archives
+* list:: How to List Archives
+* extract:: How to Extract Members from an Archive
+* going further::
+@end menu
+
+@node assumptions
+@section Assumptions this Tutorial Makes
+
+This chapter is paced to allow beginners to learn about @command{tar}
+slowly. At the same time, we will try to cover all the basic aspects of
+these three operations. In order to accomplish both of these tasks, we
+have made certain assumptions about your knowledge before reading this
+manual, and the hardware you will be using:
+
+@itemize @bullet
+@item
+Before you start to work through this tutorial, you should understand
+what the terms ``archive'' and ``archive member'' mean
+(@pxref{Definitions}). In addition, you should understand something
+about how Unix-type operating systems work, and you should know how to
+use some basic utilities. For example, you should know how to create,
+list, copy, rename, edit, and delete files and directories; how to
+change between directories; and how to figure out where you are in the
+file system. You should have some basic understanding of directory
+structure and how files are named according to which directory they are
+in. You should understand concepts such as standard output and standard
+input, what various definitions of the term @samp{argument} mean, and the
+differences between relative and absolute file names.
+@FIXME{and what else?}
+
+@item
+This manual assumes that you are working from your own home directory
+(unless we state otherwise). In this tutorial, you will create a
+directory to practice @command{tar} commands in. When we show file names,
+we will assume that those names are relative to your home directory.
+For example, my home directory is @file{/home/fsf/melissa}. All of
+my examples are in a subdirectory of the directory named by that file
+name; the subdirectory is called @file{practice}.
+
+@item
+In general, we show examples of archives which exist on (or can be
+written to, or worked with from) a directory on a hard disk. In most
+cases, you could write those archives to, or work with them on any other
+device, such as a tape drive. However, some of the later examples in
+the tutorial and next chapter will not work on tape drives.
+Additionally, working with tapes is much more complicated than working
+with hard disks. For these reasons, the tutorial does not cover working
+with tape drives. @xref{Media}, for complete information on using
+@command{tar} archives with tape drives.
+
+@FIXME{this is a cop out. need to add some simple tape drive info.}
+@end itemize
+
+@node stylistic conventions
+@section Stylistic Conventions
+
+In the examples, @samp{$} represents a typical shell prompt. It
+precedes lines you should type; to make this more clear, those lines are
+shown in @kbd{this font}, as opposed to lines which represent the
+computer's response; those lines are shown in @code{this font}, or
+sometimes @samp{like this}.
+
+@c When we have lines which are too long to be
+@c displayed in any other way, we will show them like this:
+
+@node basic tar options
+@section Basic @command{tar} Operations and Options
+
+@command{tar} can take a wide variety of arguments which specify and define
+the actions it will have on the particular set of files or the archive.
+The main types of arguments to @command{tar} fall into one of two classes:
+operations, and options.
+
+Some arguments fall into a class called @dfn{operations}; exactly one of
+these is both allowed and required for any instance of using @command{tar};
+you may @emph{not} specify more than one. People sometimes speak of
+@dfn{operating modes}. You are in a particular operating mode when you
+have specified the operation which specifies it; there are eight
+operations in total, and thus there are eight operating modes.
+
+The other arguments fall into the class known as @dfn{options}. You are
+not required to specify any options, and you are allowed to specify more
+than one at a time (depending on the way you are using @command{tar} at
+that time). Some options are used so frequently, and are so useful for
+helping you type commands more carefully that they are effectively
+``required''. We will discuss them in this chapter.
+
+You can write most of the @command{tar} operations and options in any
+of three forms: long (mnemonic) form, short form, and old style. Some
+of the operations and options have no short or ``old'' forms; however,
+the operations and options which we will cover in this tutorial have
+corresponding abbreviations. We will indicate those abbreviations
+appropriately to get you used to seeing them. Note, that the ``old
+style'' option forms exist in @GNUTAR{} for compatibility with Unix
+@command{tar}. In this book we present a full discussion of this way
+of writing options and operations (@pxref{Old Options}), and we discuss
+the other two styles of writing options (@xref{Long Options}, and
+@pxref{Short Options}).
+
+In the examples and in the text of this tutorial, we usually use the
+long forms of operations and options; but the ``short'' forms produce
+the same result and can make typing long @command{tar} commands easier.
+For example, instead of typing
+
+@smallexample
+@kbd{tar --create --verbose --file=afiles.tar apple angst aspic}
+@end smallexample
+
+@noindent
+you can type
+@smallexample
+@kbd{tar -c -v -f afiles.tar apple angst aspic}
+@end smallexample
+
+@noindent
+or even
+@smallexample
+@kbd{tar -cvf afiles.tar apple angst aspic}
+@end smallexample
+
+@noindent
+For more information on option syntax, see @ref{Advanced tar}. In
+discussions in the text, when we name an option by its long form, we
+also give the corresponding short option in parentheses.
+
+The term, ``option'', can be confusing at times, since ``operations''
+are often lumped in with the actual, @emph{optional} ``options'' in certain
+general class statements. For example, we just talked about ``short and
+long forms of options and operations''. However, experienced @command{tar}
+users often refer to these by shorthand terms such as, ``short and long
+options''. This term assumes that the ``operations'' are included, also.
+Context will help you determine which definition of ``options'' to use.
+
+Similarly, the term ``command'' can be confusing, as it is often used in
+two different ways. People sometimes refer to @command{tar} ``commands''.
+A @command{tar} @dfn{command} is the entire command line of user input
+which tells @command{tar} what to do --- including the operation, options,
+and any arguments (file names, pipes, other commands, etc.). However,
+you will also sometimes hear the term ``the @command{tar} command''. When
+the word ``command'' is used specifically like this, a person is usually
+referring to the @command{tar} @emph{operation}, not the whole line.
+Again, use context to figure out which of the meanings the speaker
+intends.
+
+@node frequent operations
+@section The Three Most Frequently Used Operations
+
+Here are the three most frequently used operations (both short and long
+forms), as well as a brief description of their meanings. The rest of
+this chapter will cover how to use these operations in detail. We will
+present the rest of the operations in the next chapter.
+
+@table @option
+@item --create
+@itemx -c
+Create a new @command{tar} archive.
+@item --list
+@itemx -t
+List the contents of an archive.
+@item --extract
+@itemx -x
+Extract one or more members from an archive.
+@end table
+
+@node Two Frequent Options
+@section Two Frequently Used Options
+
+To understand how to run @command{tar} in the three operating modes listed
+previously, you also need to understand how to use two of the options to
+@command{tar}: @option{--file} (which takes an archive file as an argument)
+and @option{--verbose}. (You are usually not @emph{required} to specify
+either of these options when you run @command{tar}, but they can be very
+useful in making things more clear and helping you avoid errors.)
+
+@menu
+* file tutorial::
+* verbose tutorial::
+* help tutorial::
+@end menu
+
+@node file tutorial
+@unnumberedsubsec The @option{--file} Option
+
+@table @option
+@xopindex{file, tutorial}
+@item --file=@var{archive-name}
+@itemx -f @var{archive-name}
+Specify the name of an archive file.
+@end table
+
+You can specify an argument for the @option{--file=@var{archive-name}} (@option{-f @var{archive-name}}) option whenever you
+use @command{tar}; this option determines the name of the archive file
+that @command{tar} will work on.
+
+@vrindex TAPE
+If you don't specify this argument, then @command{tar} will examine
+the environment variable @env{TAPE}. If it is set, its value will be
+used as the archive name. Otherwise, @command{tar} will use the
+default archive, determined at compile time. Usually it is
+standard output or some physical tape drive attached to your machine
+(you can verify what the default is by running @kbd{tar
+--show-defaults}, @pxref{defaults}). If there is no tape drive
+attached, or the default is not meaningful, then @command{tar} will
+print an error message. The error message might look roughly like one
+of the following:
+
+@smallexample
+tar: can't open /dev/rmt8 : No such device or address
+tar: can't open /dev/rsmt0 : I/O error
+@end smallexample
+
+@noindent
+To avoid confusion, we recommend that you always specify an archive file
+name by using @option{--file=@var{archive-name}} (@option{-f @var{archive-name}}) when writing your @command{tar} commands.
+For more information on using the @option{--file=@var{archive-name}} (@option{-f @var{archive-name}}) option, see
+@ref{file}.
+
+@node verbose tutorial
+@unnumberedsubsec The @option{--verbose} Option
+
+@table @option
+@xopindex{verbose, introduced}
+@item --verbose
+@itemx -v
+Show the files being worked on as @command{tar} is running.
+@end table
+
+@option{--verbose} (@option{-v}) shows details about the results of running
+@command{tar}. This can be especially useful when the results might not be
+obvious. For example, if you want to see the progress of @command{tar} as
+it writes files into the archive, you can use the @option{--verbose}
+option. In the beginning, you may find it useful to use
+@option{--verbose} at all times; when you are more accustomed to
+@command{tar}, you will likely want to use it at certain times but not at
+others. We will use @option{--verbose} at times to help make something
+clear, and we will give many examples both using and not using
+@option{--verbose} to show the differences.
+
+Each instance of @option{--verbose} on the command line increases the
+verbosity level by one, so if you need more details on the output,
+specify it twice.
+
+When reading archives (@option{--list}, @option{--extract},
+@option{--diff}), @command{tar} by default prints only the names of
+the members being extracted. Using @option{--verbose} will show a full,
+@command{ls} style member listing.
+
+In contrast, when writing archives (@option{--create}, @option{--append},
+@option{--update}), @command{tar} does not print file names by
+default. So, a single @option{--verbose} option shows the file names
+being added to the archive, while two @option{--verbose} options
+enable the full listing.
+
+For example, to create an archive in verbose mode:
+
+@smallexample
+$ @kbd{tar -cvf afiles.tar apple angst aspic}
+apple
+angst
+aspic
+@end smallexample
+
+@noindent
+Creating the same archive with the verbosity level 2 could give:
+
+@smallexample
+$ @kbd{tar -cvvf afiles.tar apple angst aspic}
+-rw-r--r-- gray/staff 62373 2006-06-09 12:06 apple
+-rw-r--r-- gray/staff 11481 2006-06-09 12:06 angst
+-rw-r--r-- gray/staff 23152 2006-06-09 12:06 aspic
+@end smallexample
+
+@noindent
+This works equally well using short or long forms of options. Using
+long forms, you would simply write out the mnemonic form of the option
+twice, like this:
+
+@smallexample
+$ @kbd{tar --create --verbose --verbose @dots{}}
+@end smallexample
+
+@noindent
+Note that you must double the hyphens properly each time.
+
+Later in the tutorial, we will give examples using @w{@option{--verbose
+--verbose}}.
+
+@anchor{verbose member listing}
+The full output consists of six fields:
+
+@itemize @bullet
+@item File type and permissions in symbolic form.
+These are displayed in the same format as the first column of
+@command{ls -l} output (@pxref{What information is listed,
+format=verbose, Verbose listing, fileutils, GNU file utilities}).
+
+@item Owner name and group separated by a slash character.
+If these data are not available (for example, when listing a @samp{v7} format
+archive), numeric @acronym{ID} values are printed instead.
+
+@item Size of the file, in bytes.
+
+@item File modification date in ISO 8601 format.
+
+@item File modification time.
+
+@item File name.
+If the name contains any special characters (white space, newlines,
+etc.)@: these are displayed in an unambiguous form using so called
+@dfn{quoting style}. For the detailed discussion of available styles
+and on how to use them, see @ref{quoting styles}.
+
+Depending on the file type, the name can be followed by some
+additional information, described in the following table:
+
+@table @samp
+@item -> @var{link-name}
+The file or archive member is a @dfn{symbolic link} and
+@var{link-name} is the name of file it links to.
+
+@item link to @var{link-name}
+The file or archive member is a @dfn{hard link} and @var{link-name} is
+the name of file it links to.
+
+@item --Long Link--
+The archive member is an old GNU format long link. You will normally
+not encounter this.
+
+@item --Long Name--
+The archive member is an old GNU format long name. You will normally
+not encounter this.
+
+@item --Volume Header--
+The archive member is a GNU @dfn{volume header} (@pxref{Tape Files}).
+
+@item --Continued at byte @var{n}--
+Encountered only at the beginning of a multi-volume archive
+(@pxref{Using Multiple Tapes}). This archive member is a continuation
+from the previous volume. The number @var{n} gives the offset where
+the original file was split.
+
+@item unknown file type @var{c}
+An archive member of unknown type. @var{c} is the type character from
+the archive header. If you encounter such a message, it means that
+either your archive contains proprietary member types @GNUTAR{} is not
+able to handle, or the archive is corrupted.
+@end table
+
+@end itemize
+
+For example, here is an archive listing containing most of the special
+suffixes explained above:
+
+@smallexample
+@group
+V--------- 0/0 1536 2006-06-09 13:07 MyVolume--Volume Header--
+-rw-r--r-- gray/staff 456783 2006-06-09 12:06 aspic--Continued at byte 32456--
+-rw-r--r-- gray/staff 62373 2006-06-09 12:06 apple
+lrwxrwxrwx gray/staff 0 2006-06-09 13:01 angst -> apple
+-rw-r--r-- gray/staff 35793 2006-06-09 12:06 blues
+hrw-r--r-- gray/staff 0 2006-06-09 12:06 music link to blues
+@end group
+@end smallexample
+
+@smallexample
+@end smallexample
+
+@node help tutorial
+@unnumberedsubsec Getting Help: Using the @option{--help} Option
+
+@table @option
+@opindex help
+@item --help
+
+The @option{--help} option to @command{tar} prints out a very brief list of
+all operations and option available for the current version of
+@command{tar} available on your system.
+@end table
+
+@node create
+@section How to Create Archives
+
+@cindex Creation of the archive
+@cindex Archive, creation of
+One of the basic operations of @command{tar} is @option{--create} (@option{-c}), which
+you use to create a @command{tar} archive. We will explain
+@option{--create} first because, in order to learn about the other
+operations, you will find it useful to have an archive available to
+practice on.
+
+To make this easier, in this section you will first create a directory
+containing three files. Then, we will show you how to create an
+@emph{archive} (inside the new directory). Both the directory, and
+the archive are specifically for you to practice on. The rest of this
+chapter and the next chapter will show many examples using this
+directory and the files you will create: some of those files may be
+other directories and other archives.
+
+The three files you will archive in this example are called
+@file{blues}, @file{folk}, and @file{jazz}. The archive is called
+@file{collection.tar}.
+
+This section will proceed slowly, detailing how to use @option{--create}
+in @code{verbose} mode, and showing examples using both short and long
+forms. In the rest of the tutorial, and in the examples in the next
+chapter, we will proceed at a slightly quicker pace. This section
+moves more slowly to allow beginning users to understand how
+@command{tar} works.
+
+@menu
+* prepare for examples::
+* Creating the archive::
+* create verbose::
+* short create::
+* create dir::
+@end menu
+
+@node prepare for examples
+@subsection Preparing a Practice Directory for Examples
+
+To follow along with this and future examples, create a new directory
+called @file{practice} containing files called @file{blues}, @file{folk}
+and @file{jazz}. The files can contain any information you like:
+ideally, they should contain information which relates to their names,
+and be of different lengths. Our examples assume that @file{practice}
+is a subdirectory of your home directory.
+
+Now @command{cd} to the directory named @file{practice}; @file{practice}
+is now your @dfn{working directory}. (@emph{Please note}: Although
+the full file name of this directory is
+@file{/@var{homedir}/practice}, in our examples we will refer to
+this directory as @file{practice}; the @var{homedir} is presumed.)
+
+In general, you should check that the files to be archived exist where
+you think they do (in the working directory) by running @command{ls}.
+Because you just created the directory and the files and have changed to
+that directory, you probably don't need to do that this time.
+
+It is very important to make sure there isn't already a file in the
+working directory with the archive name you intend to use (in this case,
+@samp{collection.tar}), or that you don't care about its contents.
+Whenever you use @samp{create}, @command{tar} will erase the current
+contents of the file named by @option{--file=@var{archive-name}} (@option{-f @var{archive-name}}) if it exists. @command{tar}
+will not tell you if you are about to overwrite an archive unless you
+specify an option which does this (@pxref{backup}, for the
+information on how to do so). To add files to an existing archive,
+you need to use a different option, such as @option{--append} (@option{-r}); see
+@ref{append} for information on how to do this.
+
+@node Creating the archive
+@subsection Creating the Archive
+
+@xopindex{create, introduced}
+To place the files @file{blues}, @file{folk}, and @file{jazz} into an
+archive named @file{collection.tar}, use the following command:
+
+@smallexample
+$ @kbd{tar --create --file=collection.tar blues folk jazz}
+@end smallexample
+
+The order of the arguments is not very important, @emph{when using long
+option forms}, however you should always remember to use option as the
+first argument to tar. For example, the following is wrong:
+
+@smallexample
+$ @kbd{tar blues -c folk -f collection.tar jazz}
+tar: -c: Invalid blocking factor
+Try 'tar --help' or 'tar --usage' for more information.
+@end smallexample
+
+The error message is produced because @command{tar} always treats its
+first argument as an option (or cluster of options), even if it does
+not start with dash. This is @dfn{traditional} or @dfn{old option}
+style, called so because all implementations of @command{tar} have
+used it since the very inception of the tar archiver in 1970s. This
+option style will be explained later (@pxref{Old Options}), for now
+just remember to always place option as the first argument.
+
+That being said, you could issue the following command:
+
+@smallexample
+$ @kbd{tar --create folk blues --file=collection.tar jazz}
+@end smallexample
+
+@noindent
+However, you can see that this order is harder to understand; this is
+why we will list the arguments in the order that makes the commands
+easiest to understand (and we encourage you to do the same when you use
+@command{tar}, to avoid errors).
+
+Note that the sequence
+@option{--file=@-collection.tar} is considered to be @emph{one} argument.
+If you substituted any other string of characters for
+@kbd{collection.tar}, then that string would become the name of the
+archive file you create.
+
+The order of the options becomes more important when you begin to use
+short forms. With short forms, if you type commands in the wrong order
+(even if you type them correctly in all other ways), you may end up with
+results you don't expect. For this reason, it is a good idea to get
+into the habit of typing options in the order that makes inherent sense.
+@xref{short create}, for more information on this.
+
+In this example, you type the command as shown above: @option{--create}
+is the operation which creates the new archive
+(@file{collection.tar}), and @option{--file} is the option which lets
+you give it the name you chose. The files, @file{blues}, @file{folk},
+and @file{jazz}, are now members of the archive, @file{collection.tar}
+(they are @dfn{file name arguments} to the @option{--create} operation.
+@xref{Choosing}, for the detailed discussion on these.) Now that they are
+in the archive, they are called @emph{archive members}, not files.
+(@pxref{Definitions,members}).
+
+When you create an archive, you @emph{must} specify which files you
+want placed in the archive. If you do not specify any archive
+members, @GNUTAR{} will complain.
+
+If you now list the contents of the working directory (@command{ls}), you will
+find the archive file listed as well as the files you saw previously:
+
+@smallexample
+blues folk jazz collection.tar
+@end smallexample
+
+@noindent
+Creating the archive @samp{collection.tar} did not destroy the copies of
+the files in the directory.
+
+Keep in mind that if you don't indicate an operation, @command{tar} will not
+run and will prompt you for one. If you don't name any files, @command{tar}
+will complain. You must have write access to the working directory,
+or else you will not be able to create an archive in that directory.
+
+@emph{Caution}: Do not attempt to use @option{--create} (@option{-c}) to add files to
+an existing archive; it will delete the archive and write a new one.
+Use @option{--append} (@option{-r}) instead. @xref{append}.
+
+@node create verbose
+@subsection Running @option{--create} with @option{--verbose}
+
+@xopindex{create, using with @option{--verbose}}
+@xopindex{verbose, using with @option{--create}}
+If you include the @option{--verbose} (@option{-v}) option on the command line,
+@command{tar} will list the files it is acting on as it is working. In
+verbose mode, the @code{create} example above would appear as:
+
+@smallexample
+$ @kbd{tar --create --verbose --file=collection.tar blues folk jazz}
+blues
+folk
+jazz
+@end smallexample
+
+This example is just like the example we showed which did not use
+@option{--verbose}, except that @command{tar} generated the remaining
+@iftex
+lines (note the different font styles).
+@end iftex
+@ifinfo
+lines.
+@end ifinfo
+
+In the rest of the examples in this chapter, we will frequently use
+@code{verbose} mode so we can show actions or @command{tar} responses that
+you would otherwise not see, and which are important for you to
+understand.
+
+@node short create
+@subsection Short Forms with @samp{create}
+
+As we said before, the @option{--create} (@option{-c}) operation is one of the most
+basic uses of @command{tar}, and you will use it countless times.
+Eventually, you will probably want to use abbreviated (or ``short'')
+forms of options. A full discussion of the three different forms that
+options can take appears in @ref{Styles}; for now, here is what the
+previous example (including the @option{--verbose} (@option{-v}) option) looks like
+using short option forms:
+
+@smallexample
+$ @kbd{tar -cvf collection.tar blues folk jazz}
+blues
+folk
+jazz
+@end smallexample
+
+@noindent
+As you can see, the system responds the same no matter whether you use
+long or short option forms.
+
+@FIXME{i don't like how this is worded:} One difference between using
+short and long option forms is that, although the exact placement of
+arguments following options is no more specific when using short forms,
+it is easier to become confused and make a mistake when using short
+forms. For example, suppose you attempted the above example in the
+following way:
+
+@smallexample
+$ @kbd{tar -cfv collection.tar blues folk jazz}
+@end smallexample
+
+@noindent
+In this case, @command{tar} will make an archive file called @file{v},
+containing the files @file{blues}, @file{folk}, and @file{jazz}, because
+the @samp{v} is the closest ``file name'' to the @option{-f} option, and
+is thus taken to be the chosen archive file name. @command{tar} will try
+to add a file called @file{collection.tar} to the @file{v} archive file;
+if the file @file{collection.tar} did not already exist, @command{tar} will
+report an error indicating that this file does not exist. If the file
+@file{collection.tar} does already exist (e.g., from a previous command
+you may have run), then @command{tar} will add this file to the archive.
+Because the @option{-v} option did not get registered, @command{tar} will not
+run under @samp{verbose} mode, and will not report its progress.
+
+The end result is that you may be quite confused about what happened,
+and possibly overwrite a file. To illustrate this further, we will show
+you how an example we showed previously would look using short forms.
+
+This example,
+
+@smallexample
+$ @kbd{tar --create folk blues --file=collection.tar jazz}
+@end smallexample
+
+@noindent
+is confusing as it is. It becomes even more so when using short forms:
+
+@smallexample
+$ @kbd{tar -c folk blues -f collection.tar jazz}
+@end smallexample
+
+@noindent
+It would be very easy to put the wrong string of characters
+immediately following the @option{-f}, but doing that could sacrifice
+valuable data.
+
+For this reason, we recommend that you pay very careful attention to
+the order of options and placement of file and archive names,
+especially when using short option forms. Not having the option name
+written out mnemonically can affect how well you remember which option
+does what, and therefore where different names have to be placed.
+
+@node create dir
+@subsection Archiving Directories
+
+@cindex Archiving Directories
+@cindex Directories, Archiving
+You can archive a directory by specifying its directory name as a
+file name argument to @command{tar}. The files in the directory will be
+archived relative to the working directory, and the directory will be
+re-created along with its contents when the archive is extracted.
+
+To archive a directory, first move to its superior directory. If you
+have followed the previous instructions in this tutorial, you should
+type:
+
+@smallexample
+$ @kbd{cd ..}
+$
+@end smallexample
+
+@noindent
+This will put you into the directory which contains @file{practice},
+i.e., your home directory. Once in the superior directory, you can
+specify the subdirectory, @file{practice}, as a file name argument. To
+store @file{practice} in the new archive file @file{music.tar}, type:
+
+@smallexample
+$ @kbd{tar --create --verbose --file=music.tar practice}
+@end smallexample
+
+@noindent
+@command{tar} should output:
+
+@smallexample
+practice/
+practice/blues
+practice/folk
+practice/jazz
+practice/collection.tar
+@end smallexample
+
+Note that the archive thus created is not in the subdirectory
+@file{practice}, but rather in the current working directory---the
+directory from which @command{tar} was invoked. Before trying to archive a
+directory from its superior directory, you should make sure you have
+write access to the superior directory itself, not only the directory
+you are trying archive with @command{tar}. For example, you will probably
+not be able to store your home directory in an archive by invoking
+@command{tar} from the root directory; @xref{absolute}. (Note
+also that @file{collection.tar}, the original archive file, has itself
+been archived. @command{tar} will accept any file as a file to be
+archived, regardless of its content. When @file{music.tar} is
+extracted, the archive file @file{collection.tar} will be re-written
+into the file system).
+
+If you give @command{tar} a command such as
+
+@smallexample
+$ @kbd{tar --create --file=foo.tar .}
+@end smallexample
+
+@noindent
+@command{tar} will report @samp{tar: ./foo.tar is the archive; not
+dumped}. This happens because @command{tar} creates the archive
+@file{foo.tar} in the current directory before putting any files into
+it. Then, when @command{tar} attempts to add all the files in the
+directory @file{.} to the archive, it notices that the file
+@file{./foo.tar} is the same as the archive @file{foo.tar}, and skips
+it. (It makes no sense to put an archive into itself.) @GNUTAR{}
+will continue in this case, and create the archive
+normally, except for the exclusion of that one file. (@emph{Please
+note:} Other implementations of @command{tar} may not be so clever;
+they will enter an infinite loop when this happens, so you should not
+depend on this behavior unless you are certain you are running
+@GNUTAR{}. In general, it is wise to always place the archive outside
+of the directory being dumped.)
+
+@node list
+@section How to List Archives
+
+@opindex list
+Frequently, you will find yourself wanting to determine exactly what a
+particular archive contains. You can use the @option{--list}
+(@option{-t}) operation to get the member names as they currently
+appear in the archive, as well as various attributes of the files at
+the time they were archived. For example, assuming @file{practice} is
+your working directory, you can examine the archive
+@file{collection.tar} that you created in the last section with the
+command,
+
+@smallexample
+$ @kbd{tar --list --file=collection.tar}
+@end smallexample
+
+@noindent
+The output of @command{tar} would then be:
+
+@smallexample
+blues
+folk
+jazz
+@end smallexample
+
+@noindent
+Be sure to use a @option{--file=@var{archive-name}} (@option{-f
+@var{archive-name}}) option just as with @option{--create}
+(@option{-c}) to specify the name of the archive.
+
+@cindex File name arguments, using @option{--list} with
+@xopindex{list, using with file name arguments}
+You can specify one or more individual member names as arguments when
+using @samp{list}. In this case, @command{tar} will only list the
+names of members you identify. For example, @w{@kbd{tar --list
+--file=collection.tar folk}} would only print @file{folk}:
+
+@smallexample
+$ @kbd{tar --list --file=collection.tar folk}
+folk
+@end smallexample
+
+@xopindex{list, using with @option{--verbose}}
+@xopindex{verbose, using with @option{--list}}
+If you use the @option{--verbose} (@option{-v}) option with
+@option{--list}, then @command{tar} will print out a listing
+reminiscent of @w{@samp{ls -l}}, showing owner, file size, and so
+forth. This output is described in detail in @ref{verbose member listing}.
+
+If you had used @option{--verbose} (@option{-v}) mode, the example
+above would look like:
+
+@smallexample
+$ @kbd{tar --list --verbose --file=collection.tar folk}
+-rw-r--r-- myself/user 62 1990-05-23 10:55 folk
+@end smallexample
+
+@cindex listing member and file names
+@anchor{listing member and file names}
+It is important to notice that the output of @kbd{tar --list
+--verbose} does not necessarily match that produced by @kbd{tar
+--create --verbose} while creating the archive. It is because
+@GNUTAR{}, unless told explicitly not to do so, removes some directory
+prefixes from file names before storing them in the archive
+(@xref{absolute}, for more information). In other
+words, in verbose mode @GNUTAR{} shows @dfn{file names} when creating
+an archive and @dfn{member names} when listing it. Consider this
+example, run from your home directory:
+
+@smallexample
+@group
+$ @kbd{tar --create --verbose --file practice.tar ~/practice}
+tar: Removing leading '/' from member names
+/home/myself/practice/
+/home/myself/practice/blues
+/home/myself/practice/folk
+/home/myself/practice/jazz
+/home/myself/practice/collection.tar
+$ @kbd{tar --test --file practice.tar}
+home/myself/practice/
+home/myself/practice/blues
+home/myself/practice/folk
+home/myself/practice/jazz
+home/myself/practice/collection.tar
+@end group
+@end smallexample
+
+@opindex show-stored-names
+ This default behavior can sometimes be inconvenient. You can force
+@GNUTAR{} show member names when creating archive by supplying
+@option{--show-stored-names} option.
+
+@table @option
+@item --show-stored-names
+Print member (as opposed to @emph{file}) names when creating the archive.
+@end table
+
+With this option, both commands produce the same output:
+
+@smallexample
+@group
+$ @kbd{tar --create --verbose --show-stored-names \
+ --file practice.tar ~/practice}
+tar: Removing leading '/' from member names
+home/myself/practice/
+home/myself/practice/blues
+home/myself/practice/folk
+home/myself/practice/jazz
+home/myself/practice/collection.tar
+$ @kbd{tar --test --file practice.tar}
+home/myself/practice/
+home/myself/practice/blues
+home/myself/practice/folk
+home/myself/practice/jazz
+home/myself/practice/collection.tar
+@end group
+@end smallexample
+
+Since @command{tar} preserves file names, those you wish to list must be
+specified as they appear in the archive (i.e., relative to the
+directory from which the archive was created). Continuing the example
+above:
+
+@smallexample
+@group
+$ @kbd{tar --list --file=practice.tar folk}
+tar: folk: Not found in archive
+tar: Exiting with failure status due to previous errors
+@end group
+@end smallexample
+
+the error message is produced because there is no member named
+@file{folk}, only one named @file{home/myself/folk}.
+
+If you are not sure of the exact file name, use @dfn{globbing
+patterns}, for example:
+
+@smallexample
+$ @kbd{tar --list --file=practice.tar --wildcards '*/folk'}
+home/myself/practice/folk
+@end smallexample
+
+@noindent
+@xref{wildcards}, for a detailed discussion of globbing patterns and related
+@command{tar} command line options.
+
+@menu
+* list dir::
+@end menu
+
+@node list dir
+@unnumberedsubsec Listing the Contents of a Stored Directory
+
+To get information about the contents of an archived directory,
+use the directory name as a file name argument in conjunction with
+@option{--list} (@option{-t}). To find out file attributes, include the
+@option{--verbose} (@option{-v}) option.
+
+For example, to find out about files in the directory @file{practice}, in
+the archive file @file{music.tar}, type:
+
+@smallexample
+$ @kbd{tar --list --verbose --file=music.tar practice}
+@end smallexample
+
+@command{tar} responds:
+
+@smallexample
+drwxrwxrwx myself/user 0 1990-05-31 21:49 practice/
+-rw-r--r-- myself/user 42 1990-05-21 13:29 practice/blues
+-rw-r--r-- myself/user 62 1990-05-23 10:55 practice/folk
+-rw-r--r-- myself/user 40 1990-05-21 13:30 practice/jazz
+-rw-r--r-- myself/user 10240 1990-05-31 21:49 practice/collection.tar
+@end smallexample
+
+When you use a directory name as a file name argument, @command{tar} acts on
+all the files (including sub-directories) in that directory.
+
+@node extract
+@section How to Extract Members from an Archive
+@cindex Extraction
+@cindex Retrieving files from an archive
+@cindex Resurrecting files from an archive
+
+@opindex extract
+Creating an archive is only half the job---there is no point in storing
+files in an archive if you can't retrieve them. The act of retrieving
+members from an archive so they can be used and manipulated as
+unarchived files again is called @dfn{extraction}. To extract files
+from an archive, use the @option{--extract} (@option{--get} or
+@option{-x}) operation. As with @option{--create}, specify the name
+of the archive with @option{--file} (@option{-f}) option. Extracting
+an archive does not modify the archive in any way; you can extract it
+multiple times if you want or need to.
+
+Using @option{--extract}, you can extract an entire archive, or specific
+files. The files can be directories containing other files, or not. As
+with @option{--create} (@option{-c}) and @option{--list} (@option{-t}), you may use the short or the
+long form of the operation without affecting the performance.
+
+@menu
+* extracting archives::
+* extracting files::
+* extract dir::
+* extracting untrusted archives::
+* failing commands::
+@end menu
+
+@node extracting archives
+@subsection Extracting an Entire Archive
+
+To extract an entire archive, specify the archive file name only, with
+no individual file names as arguments. For example,
+
+@smallexample
+$ @kbd{tar -xvf collection.tar}
+@end smallexample
+
+@noindent
+produces this:
+
+@smallexample
+-rw-r--r-- myself/user 28 1996-10-18 16:31 jazz
+-rw-r--r-- myself/user 21 1996-09-23 16:44 blues
+-rw-r--r-- myself/user 20 1996-09-23 16:44 folk
+@end smallexample
+
+@node extracting files
+@subsection Extracting Specific Files
+
+To extract specific archive members, give their exact member names as
+arguments, as printed by @option{--list} (@option{-t}). If you had
+mistakenly deleted one of the files you had placed in the archive
+@file{collection.tar} earlier (say, @file{blues}), you can extract it
+from the archive without changing the archive's structure. Its
+contents will be identical to the original file @file{blues} that you
+deleted.
+
+First, make sure you are in the @file{practice} directory, and list the
+files in the directory. Now, delete the file, @samp{blues}, and list
+the files in the directory again.
+
+You can now extract the member @file{blues} from the archive file
+@file{collection.tar} like this:
+
+@smallexample
+$ @kbd{tar --extract --file=collection.tar blues}
+@end smallexample
+
+@noindent
+If you list the files in the directory again, you will see that the file
+@file{blues} has been restored, with its original permissions, data
+modification times, and owner.@footnote{This is only accidentally
+true, but not in general. Whereas modification times are always
+restored, in most cases, one has to be root for restoring the owner,
+and use a special option for restoring permissions. Here, it just
+happens that the restoring user is also the owner of the archived
+members, and that the current @code{umask} is compatible with original
+permissions.} (These parameters will be identical to those which
+the file had when you originally placed it in the archive; any changes
+you may have made before deleting the file from the file system,
+however, will @emph{not} have been made to the archive member.) The
+archive file, @samp{collection.tar}, is the same as it was before you
+extracted @samp{blues}. You can confirm this by running @command{tar} with
+@option{--list} (@option{-t}).
+
+Remember that as with other operations, specifying the exact member
+name is important (@xref{failing commands}, for more examples).
+
+You can extract a file to standard output by combining the above options
+with the @option{--to-stdout} (@option{-O}) option (@pxref{Writing to Standard
+Output}).
+
+If you give the @option{--verbose} option, then @option{--extract}
+will print the names of the archive members as it extracts them.
+
+@node extract dir
+@subsection Extracting Files that are Directories
+
+Extracting directories which are members of an archive is similar to
+extracting other files. The main difference to be aware of is that if
+the extracted directory has the same name as any directory already in
+the working directory, then files in the extracted directory will be
+placed into the directory of the same name. Likewise, if there are
+files in the pre-existing directory with the same names as the members
+which you extract, the files from the extracted archive will replace
+the files already in the working directory (and possible
+subdirectories). This will happen regardless of whether or not the
+files in the working directory were more recent than those extracted
+(there exist, however, special options that alter this behavior
+@pxref{Writing}).
+
+However, if a file was stored with a directory name as part of its file
+name, and that directory does not exist under the working directory when
+the file is extracted, @command{tar} will create the directory.
+
+We can demonstrate how to use @option{--extract} to extract a directory
+file with an example. Change to the @file{practice} directory if you
+weren't there, and remove the files @file{folk} and @file{jazz}. Then,
+go back to the parent directory and extract the archive
+@file{music.tar}. You may either extract the entire archive, or you may
+extract only the files you just deleted. To extract the entire archive,
+don't give any file names as arguments after the archive name
+@file{music.tar}. To extract only the files you deleted, use the
+following command:
+
+@smallexample
+$ @kbd{tar -xvf music.tar practice/folk practice/jazz}
+practice/folk
+practice/jazz
+@end smallexample
+
+@noindent
+If you were to specify two @option{--verbose} (@option{-v}) options, @command{tar}
+would have displayed more detail about the extracted files, as shown
+in the example below:
+
+@smallexample
+$ @kbd{tar -xvvf music.tar practice/folk practice/jazz}
+-rw-r--r-- me/user 28 1996-10-18 16:31 practice/jazz
+-rw-r--r-- me/user 20 1996-09-23 16:44 practice/folk
+@end smallexample
+
+@noindent
+Because you created the directory with @file{practice} as part of the
+file names of each of the files by archiving the @file{practice}
+directory as @file{practice}, you must give @file{practice} as part
+of the file names when you extract those files from the archive.
+
+@node extracting untrusted archives
+@subsection Extracting Archives from Untrusted Sources
+
+Extracting files from archives can overwrite files that already exist.
+If you receive an archive from an untrusted source, you should make a
+new directory and extract into that directory, so that you don't have
+to worry about the extraction overwriting one of your existing files.
+For example, if @file{untrusted.tar} came from somewhere else on the
+Internet, and you don't necessarily trust its contents, you can
+extract it as follows:
+
+@smallexample
+$ @kbd{mkdir newdir}
+$ @kbd{cd newdir}
+$ @kbd{tar -xvf ../untrusted.tar}
+@end smallexample
+
+It is also a good practice to examine contents of the archive
+before extracting it, using @option{--list} (@option{-t}) option, possibly combined
+with @option{--verbose} (@option{-v}).
+
+@node failing commands
+@subsection Commands That Will Fail
+
+Here are some sample commands you might try which will not work, and why
+they won't work.
+
+If you try to use this command,
+
+@smallexample
+$ @kbd{tar -xvf music.tar folk jazz}
+@end smallexample
+
+@noindent
+you will get the following response:
+
+@smallexample
+tar: folk: Not found in archive
+tar: jazz: Not found in archive
+@end smallexample
+
+@noindent
+This is because these files were not originally @emph{in} the parent
+directory @file{..}, where the archive is located; they were in the
+@file{practice} directory, and their file names reflect this:
+
+@smallexample
+$ @kbd{tar -tvf music.tar}
+practice/blues
+practice/folk
+practice/jazz
+@end smallexample
+
+@noindent
+Likewise, if you try to use this command,
+
+@smallexample
+$ @kbd{tar -tvf music.tar folk jazz}
+@end smallexample
+
+@noindent
+you would get a similar response. Members with those names are not in the
+archive. You must use the correct member names, or wildcards, in order
+to extract the files from the archive.
+
+If you have forgotten the correct names of the files in the archive,
+use @w{@kbd{tar --list --verbose}} to list them correctly.
+
+To extract the member named @file{practice/folk}, you must specify
+
+@smallexample
+$ @kbd{tar --extract --file=music.tar practice/folk}
+@end smallexample
+
+@noindent
+Notice also, that as explained above, the @file{practice} directory
+will be created, if it didn't already exist. There are options that
+allow you to strip away a certain number of leading directory
+components (@pxref{transform}). For example,
+
+@smallexample
+$ @kbd{tar --extract --file=music.tar --strip-components=1 folk}
+@end smallexample
+
+@noindent
+will extract the file @file{folk} into the current working directory.
+
+@node going further
+@section Going Further Ahead in this Manual
+@UNREVISED
+
+@FIXME{need to write up a node here about the things that are going to
+be in the rest of the manual.}
+
+@node tar invocation
+@chapter Invoking @GNUTAR{}
+
+This chapter is about how one invokes the @GNUTAR{}
+command, from the command synopsis (@pxref{Synopsis}). There are
+numerous options, and many styles for writing them. One mandatory
+option specifies the operation @command{tar} should perform
+(@pxref{Operation Summary}), other options are meant to detail how
+this operation should be performed (@pxref{Option Summary}).
+Non-option arguments are not always interpreted the same way,
+depending on what the operation is.
+
+You will find in this chapter everything about option styles and rules for
+writing them (@pxref{Styles}). On the other hand, operations and options
+are fully described elsewhere, in other chapters. Here, you will find
+only synthetic descriptions for operations and options, together with
+pointers to other parts of the @command{tar} manual.
+
+Some options are so special they are fully described right in this
+chapter. They have the effect of inhibiting the normal operation of
+@command{tar} or else, they globally alter the amount of feedback the user
+receives about what is going on. These are the @option{--help} and
+@option{--version} (@pxref{help}), @option{--verbose} (@pxref{verbose})
+and @option{--interactive} options (@pxref{interactive}).
+
+@menu
+* Synopsis::
+* using tar options::
+* Styles::
+* All Options:: All @command{tar} Options.
+* help:: Where to Get Help.
+* defaults:: What are the Default Values.
+* verbose:: Checking @command{tar} progress.
+* checkpoints:: Checkpoints.
+* warnings:: Controlling Warning Messages.
+* interactive:: Asking for Confirmation During Operations.
+* external:: Running External Commands.
+@end menu
+
+@node Synopsis
+@section General Synopsis of @command{tar}
+
+The @GNUTAR{} program is invoked as either one of:
+
+@smallexample
+@kbd{tar @var{option}@dots{} [@var{name}]@dots{}}
+@kbd{tar @var{letter}@dots{} [@var{argument}]@dots{} [@var{option}]@dots{} [@var{name}]@dots{}}
+@end smallexample
+
+The second form is for when old options are being used.
+
+You can use @command{tar} to store files in an archive, to extract them from
+an archive, and to do other types of archive manipulation. The primary
+argument to @command{tar}, which is called the @dfn{operation}, specifies
+which action to take. The other arguments to @command{tar} are either
+@dfn{options}, which change the way @command{tar} performs an operation,
+or file names or archive members, which specify the files or members
+@command{tar} is to act on.
+
+You can actually type in arguments in any order, even if in this manual
+the options always precede the other arguments, to make examples easier
+to understand. Further, the option stating the main operation mode
+(the @command{tar} main command) is usually given first.
+
+Each @var{name} in the synopsis above is interpreted as an archive member
+name when the main command is one of @option{--compare}
+(@option{--diff}, @option{-d}), @option{--delete}, @option{--extract}
+(@option{--get}, @option{-x}), @option{--list} (@option{-t}) or
+@option{--update} (@option{-u}). When naming archive members, you
+must give the exact name of the member in the archive, as it is
+printed by @option{--list}. For @option{--append} (@option{-r}) and
+@option{--create} (@option{-c}), these @var{name} arguments specify
+the names of either files or directory hierarchies to place in the archive.
+These files or hierarchies should already exist in the file system,
+prior to the execution of the @command{tar} command.
+
+@command{tar} interprets relative file names as being relative to the
+working directory. @command{tar} will make all file names relative
+(by removing leading slashes when archiving or restoring files),
+unless you specify otherwise (using the @option{--absolute-names}
+option). @xref{absolute}, for more information about
+@option{--absolute-names}.
+
+If you give the name of a directory as either a file name or a member
+name, then @command{tar} acts recursively on all the files and directories
+beneath that directory. For example, the name @file{/} identifies all
+the files in the file system to @command{tar}.
+
+The distinction between file names and archive member names is especially
+important when shell globbing is used, and sometimes a source of confusion
+for newcomers. @xref{wildcards}, for more information about globbing.
+The problem is that shells may only glob using existing files in the
+file system. Only @command{tar} itself may glob on archive members, so when
+needed, you must ensure that wildcard characters reach @command{tar} without
+being interpreted by the shell first. Using a backslash before @samp{*}
+or @samp{?}, or putting the whole argument between quotes, is usually
+sufficient for this.
+
+Even if @var{name}s are often specified on the command line, they
+can also be read from a text file in the file system, using the
+@option{--files-from=@var{file-of-names}} (@option{-T @var{file-of-names}}) option.
+
+If you don't use any file name arguments, @option{--append} (@option{-r}),
+@option{--delete} and @option{--concatenate} (@option{--catenate},
+@option{-A}) will do nothing, while @option{--create} (@option{-c})
+will usually yield a diagnostic and inhibit @command{tar} execution.
+The other operations of @command{tar} (@option{--list},
+@option{--extract}, @option{--compare}, and @option{--update})
+will act on the entire contents of the archive.
+
+@anchor{exit status}
+@cindex exit status
+@cindex return status
+Besides successful exits, @GNUTAR{} may fail for
+many reasons. Some reasons correspond to bad usage, that is, when the
+@command{tar} command line is improperly written. Errors may be
+encountered later, while processing the archive or the files. Some
+errors are recoverable, in which case the failure is delayed until
+@command{tar} has completed all its work. Some errors are such that
+it would be not meaningful, or at least risky, to continue processing:
+@command{tar} then aborts processing immediately. All abnormal exits,
+whether immediate or delayed, should always be clearly diagnosed on
+@code{stderr}, after a line stating the nature of the error.
+
+Possible exit codes of @GNUTAR{} are summarized in the following
+table:
+
+@table @asis
+@item 0
+@samp{Successful termination}.
+
+@item 1
+@samp{Some files differ}. If tar was invoked with @option{--compare}
+(@option{--diff}, @option{-d}) command line option, this means that
+some files in the archive differ from their disk counterparts
+(@pxref{compare}). If tar was given @option{--create},
+@option{--append} or @option{--update} option, this exit code means
+that some files were changed while being archived and so the resulting
+archive does not contain the exact copy of the file set.
+
+@item 2
+@samp{Fatal error}. This means that some fatal, unrecoverable error
+occurred.
+@end table
+
+If @command{tar} has invoked a subprocess and that subprocess exited with a
+nonzero exit code, @command{tar} exits with that code as well.
+This can happen, for example, if @command{tar} was given some
+compression option (@pxref{gzip}) and the external compressor program
+failed. Another example is @command{rmt} failure during backup to the
+remote device (@pxref{Remote Tape Server}).
+
+@node using tar options
+@section Using @command{tar} Options
+
+@GNUTAR{} has a total of eight operating modes which
+allow you to perform a variety of tasks. You are required to choose
+one operating mode each time you employ the @command{tar} program by
+specifying one, and only one operation as an argument to the
+@command{tar} command (the corresponding options may be found
+at @ref{frequent operations} and @ref{Operations}). Depending on
+circumstances, you may also wish to customize how the chosen operating
+mode behaves. For example, you may wish to change the way the output
+looks, or the format of the files that you wish to archive may require
+you to do something special in order to make the archive look right.
+
+You can customize and control @command{tar}'s performance by running
+@command{tar} with one or more options (such as @option{--verbose}
+(@option{-v}), which we used in the tutorial). As we said in the
+tutorial, @dfn{options} are arguments to @command{tar} which are (as
+their name suggests) optional. Depending on the operating mode, you
+may specify one or more options. Different options will have different
+effects, but in general they all change details of the operation, such
+as archive format, archive name, or level of user interaction. Some
+options make sense with all operating modes, while others are
+meaningful only with particular modes. You will likely use some
+options frequently, while you will only use others infrequently, or
+not at all. (A full list of options is available in @pxref{All Options}.)
+
+@vrindex TAR_OPTIONS, environment variable
+@anchor{TAR_OPTIONS}
+The @env{TAR_OPTIONS} environment variable specifies default options to
+be placed in front of any explicit options. For example, if
+@code{TAR_OPTIONS} is @samp{-v --unlink-first}, @command{tar} behaves as
+if the two options @option{-v} and @option{--unlink-first} had been
+specified before any explicit options. Option specifications are
+separated by whitespace. A backslash escapes the next character, so it
+can be used to specify an option containing whitespace or a backslash.
+
+Note that @command{tar} options are case sensitive. For example, the
+options @option{-T} and @option{-t} are different; the first requires an
+argument for stating the name of a file providing a list of @var{name}s,
+while the second does not require an argument and is another way to
+write @option{--list} (@option{-t}).
+
+In addition to the eight operations, there are many options to
+@command{tar}, and three different styles for writing both: long (mnemonic)
+form, short form, and old style. These styles are discussed below.
+Both the options and the operations can be written in any of these three
+styles.
+
+@FIXME{menu at end of this node. need to think of an actual outline
+for this chapter; probably do that after stuff from chapter 4 is
+incorporated.}
+
+@node Styles
+@section The Three Option Styles
+
+There are three styles for writing operations and options to the command
+line invoking @command{tar}. The different styles were developed at
+different times during the history of @command{tar}. These styles will be
+presented below, from the most recent to the oldest.
+
+Some options must take an argument@footnote{For example, @option{--file}
+(@option{-f}) takes the name of an archive file as an argument. If
+you do not supply an archive file name, @command{tar} will use a
+default, but this can be confusing; thus, we recommend that you always
+supply a specific archive file name.}. Where you @emph{place} the
+arguments generally depends on which style of options you choose. We
+will detail specific information relevant to each option style in the
+sections on the different option styles, below. The differences are
+subtle, yet can often be very important; incorrect option placement
+can cause you to overwrite a number of important files. We urge you
+to note these differences, and only use the option style(s) which
+makes the most sense to you until you feel comfortable with the others.
+
+Some options @emph{may} take an argument. Such options may have at
+most long and short forms, they do not have old style equivalent. The
+rules for specifying an argument for such options are stricter than
+those for specifying mandatory arguments. Please, pay special
+attention to them.
+
+@menu
+* Long Options:: Long Option Style
+* Short Options:: Short Option Style
+* Old Options:: Old Option Style
+* Mixing:: Mixing Option Styles
+@end menu
+
+@node Long Options
+@subsection Long Option Style
+
+@cindex long options
+@cindex options, long style
+@cindex options, GNU style
+@cindex options, mnemonic names
+Each option has at least one @dfn{long} (or @dfn{mnemonic}) name starting with two
+dashes in a row, e.g., @option{--list}. The long names are more clear than
+their corresponding short or old names. It sometimes happens that a
+single long option has many different names which are
+synonymous, such as @option{--compare} and @option{--diff}. In addition,
+long option names can be given unique abbreviations. For example,
+@option{--cre} can be used in place of @option{--create} because there is no
+other long option which begins with @samp{cre}. (One way to find
+this out is by trying it and seeing what happens; if a particular
+abbreviation could represent more than one option, @command{tar} will tell
+you that that abbreviation is ambiguous and you'll know that that
+abbreviation won't work. You may also choose to run @samp{tar --help}
+to see a list of options. Be aware that if you run @command{tar} with a
+unique abbreviation for the long name of an option you didn't want to
+use, you are stuck; @command{tar} will perform the command as ordered.)
+
+Long options are meant to be obvious and easy to remember, and their
+meanings are generally easier to discern than those of their
+corresponding short options (see below). For example:
+
+@smallexample
+$ @kbd{tar --create --verbose --blocking-factor=20 --file=/dev/rmt0}
+@end smallexample
+
+@noindent
+gives a fairly good set of hints about what the command does, even
+for those not fully acquainted with @command{tar}.
+
+@cindex arguments to long options
+@cindex long options with mandatory arguments
+Long options which require arguments take those arguments
+immediately following the option name. There are two ways of
+specifying a mandatory argument. It can be separated from the
+option name either by an equal sign, or by any amount of
+white space characters. For example, the @option{--file} option (which
+tells the name of the @command{tar} archive) is given a file such as
+@file{archive.tar} as argument by using any of the following notations:
+@option{--file=archive.tar} or @option{--file archive.tar}.
+
+@cindex optional arguments to long options
+@cindex long options with optional arguments
+In contrast, optional arguments must always be introduced using
+an equal sign. For example, the @option{--backup} option takes
+an optional argument specifying backup type. It must be used
+as @option{--backup=@var{backup-type}}.
+
+@node Short Options
+@subsection Short Option Style
+
+@cindex short options
+@cindex options, short style
+@cindex options, traditional
+Most options also have a @dfn{short option} name. Short options start with
+a single dash, and are followed by a single character, e.g., @option{-t}
+(which is equivalent to @option{--list}). The forms are absolutely
+identical in function; they are interchangeable.
+
+The short option names are faster to type than long option names.
+
+@cindex arguments to short options
+@cindex short options with mandatory arguments
+Short options which require arguments take their arguments immediately
+following the option, usually separated by white space. It is also
+possible to stick the argument right after the short option name, using
+no intervening space. For example, you might write @w{@option{-f
+archive.tar}} or @option{-farchive.tar} instead of using
+@option{--file=archive.tar}. Both @option{--file=@var{archive-name}} and
+@w{@option{-f @var{archive-name}}} denote the option which indicates a
+specific archive, here named @file{archive.tar}.
+
+@cindex optional arguments to short options
+@cindex short options with optional arguments
+Short options which take optional arguments take their arguments
+immediately following the option letter, @emph{without any intervening
+white space characters}.
+
+Short options' letters may be clumped together, but you are not
+required to do this (as compared to old options; see below). When
+short options are clumped as a set, use one (single) dash for them
+all, e.g., @w{@samp{@command{tar} -cvf}}. Only the last option in
+such a set is allowed to have an argument@footnote{Clustering many
+options, the last of which has an argument, is a rather opaque way to
+write options. Some wonder if @acronym{GNU} @code{getopt} should not
+even be made helpful enough for considering such usages as invalid.}.
+
+When the options are separated, the argument for each option which requires
+an argument directly follows that option, as is usual for Unix programs.
+For example:
+
+@smallexample
+$ @kbd{tar -c -v -b 20 -f /dev/rmt0}
+@end smallexample
+
+If you reorder short options' locations, be sure to move any arguments
+that belong to them. If you do not move the arguments properly, you may
+end up overwriting files.
+
+@node Old Options
+@subsection Old Option Style
+@cindex options, old style
+@cindex old option style
+@cindex option syntax, traditional
+
+As far as we know, all @command{tar} programs, @acronym{GNU} and
+non-@acronym{GNU}, support @dfn{old options}: that is, if the first
+argument does not start with @samp{-}, it is assumed to specify option
+letters. @GNUTAR{} supports old options not only for historical
+reasons, but also because many people are used to them. If the first
+argument does not start with a dash, you are announcing the old option
+style instead of the short option style; old options are decoded
+differently.
+
+Like short options, old options are single letters. However, old options
+must be written together as a single clumped set, without spaces separating
+them or dashes preceding them. This set
+of letters must be the first to appear on the command line, after the
+@command{tar} program name and some white space; old options cannot appear
+anywhere else. The letter of an old option is exactly the same letter as
+the corresponding short option. For example, the old option @samp{t} is
+the same as the short option @option{-t}, and consequently, the same as the
+long option @option{--list}. So for example, the command @w{@samp{tar
+cv}} specifies the option @option{-v} in addition to the operation @option{-c}.
+
+@cindex arguments to old options
+@cindex old options with mandatory arguments
+When options that need arguments are given together with the command,
+all the associated arguments follow, in the same order as the options.
+Thus, the example given previously could also be written in the old
+style as follows:
+
+@smallexample
+$ @kbd{tar cvbf 20 /dev/rmt0}
+@end smallexample
+
+@noindent
+Here, @samp{20} is the argument of @option{-b} and @samp{/dev/rmt0} is
+the argument of @option{-f}.
+
+The old style syntax can make it difficult to match
+option letters with their corresponding arguments, and is often
+confusing. In the command @w{@samp{tar cvbf 20 /dev/rmt0}}, for example,
+@samp{20} is the argument for @option{-b}, @samp{/dev/rmt0} is the
+argument for @option{-f}, and @option{-v} does not have a corresponding
+argument. Even using short options like in @w{@samp{tar -c -v -b 20 -f
+/dev/rmt0}} is clearer, putting all arguments next to the option they
+pertain to.
+
+If you want to reorder the letters in the old option argument, be
+sure to reorder any corresponding argument appropriately.
+
+This old way of writing @command{tar} options can surprise even experienced
+users. For example, the two commands:
+
+@smallexample
+@kbd{tar cfz archive.tar.gz file}
+@kbd{tar -cfz archive.tar.gz file}
+@end smallexample
+
+@noindent
+are quite different. The first example uses @file{archive.tar.gz} as
+the value for option @samp{f} and recognizes the option @samp{z}. The
+second example, however, uses @file{z} as the value for option
+@samp{f} --- probably not what was intended.
+
+This second example could be corrected in many ways, among which the
+following are equivalent:
+
+@smallexample
+@kbd{tar -czf archive.tar.gz file}
+@kbd{tar -cf archive.tar.gz -z file}
+@kbd{tar cf archive.tar.gz -z file}
+@end smallexample
+
+@node Mixing
+@subsection Mixing Option Styles
+
+@cindex options, mixing different styles
+All three styles may be intermixed in a single @command{tar} command,
+so long as the rules for each style are fully
+respected@footnote{Before @GNUTAR{} version 1.11.6,
+a bug prevented intermixing old style options with long options in
+some cases.}. Old style options and either of the modern styles of
+options may be mixed within a single @command{tar} command. However,
+old style options must be introduced as the first arguments only,
+following the rule for old options (old options must appear directly
+after the @command{tar} command and some white space). Modern options
+may be given only after all arguments to the old options have been
+collected. If this rule is not respected, a modern option might be
+falsely interpreted as the value of the argument to one of the old
+style options.
+
+For example, all the following commands are wholly equivalent, and
+illustrate the many combinations and orderings of option styles.
+
+@smallexample
+@kbd{tar --create --file=archive.tar}
+@kbd{tar --create -f archive.tar}
+@kbd{tar --create -farchive.tar}
+@kbd{tar --file=archive.tar --create}
+@kbd{tar --file=archive.tar -c}
+@kbd{tar -c --file=archive.tar}
+@kbd{tar -c -f archive.tar}
+@kbd{tar -c -farchive.tar}
+@kbd{tar -cf archive.tar}
+@kbd{tar -cfarchive.tar}
+@kbd{tar -f archive.tar --create}
+@kbd{tar -f archive.tar -c}
+@kbd{tar -farchive.tar --create}
+@kbd{tar -farchive.tar -c}
+@kbd{tar c --file=archive.tar}
+@kbd{tar c -f archive.tar}
+@kbd{tar c -farchive.tar}
+@kbd{tar cf archive.tar}
+@kbd{tar f archive.tar --create}
+@kbd{tar f archive.tar -c}
+@kbd{tar fc archive.tar}
+@end smallexample
+
+On the other hand, the following commands are @emph{not} equivalent to
+the previous set:
+
+@smallexample
+@kbd{tar -f -c archive.tar}
+@kbd{tar -fc archive.tar}
+@kbd{tar -fcarchive.tar}
+@kbd{tar -farchive.tarc}
+@kbd{tar cfarchive.tar}
+@end smallexample
+
+@noindent
+These last examples mean something completely different from what the
+user intended (judging based on the example in the previous set which
+uses long options, whose intent is therefore very clear). The first
+four specify that the @command{tar} archive would be a file named
+@option{-c}, @samp{c}, @samp{carchive.tar} or @samp{archive.tarc},
+respectively. The first two examples also specify a single non-option,
+@var{name} argument having the value @samp{archive.tar}. The last
+example contains only old style option letters (repeating option
+@samp{c} twice), not all of which are meaningful (eg., @samp{.},
+@samp{h}, or @samp{i}), with no argument value.
+@FIXME{not sure i liked
+the first sentence of this paragraph..}
+
+@node All Options
+@section All @command{tar} Options
+
+The coming manual sections contain an alphabetical listing of all
+@command{tar} operations and options, with brief descriptions and
+cross-references to more in-depth explanations in the body of the manual.
+They also contain an alphabetically arranged table of the short option
+forms with their corresponding long option. You can use this table as
+a reference for deciphering @command{tar} commands in scripts.
+
+@menu
+* Operation Summary::
+* Option Summary::
+* Short Option Summary::
+* Position-Sensitive Options::
+@end menu
+
+@node Operation Summary
+@subsection Operations
+
+@table @option
+
+@opsummary{append}
+@item --append
+@itemx -r
+
+Appends files to the end of the archive. @xref{append}.
+
+@opsummary{catenate}
+@item --catenate
+@itemx -A
+
+Same as @option{--concatenate}. @xref{concatenate}.
+
+@opsummary{compare}
+@item --compare
+@itemx -d
+
+Compares archive members with their counterparts in the file
+system, and reports differences in file size, mode, owner,
+modification date and contents. @xref{compare}.
+
+@opsummary{concatenate}
+@item --concatenate
+@itemx -A
+
+Appends other @command{tar} archives to the end of the archive.
+@xref{concatenate}.
+
+@opsummary{create}
+@item --create
+@itemx -c
+
+Creates a new @command{tar} archive. @xref{create}.
+
+@opsummary{delete}
+@item --delete
+
+Deletes members from the archive. Don't try this on an archive on a
+tape! @xref{delete}.
+
+@opsummary{diff}
+@item --diff
+@itemx -d
+
+Same @option{--compare}. @xref{compare}.
+
+@opsummary{extract}
+@item --extract
+@itemx -x
+
+Extracts members from the archive into the file system. @xref{extract}.
+
+@opsummary{get}
+@item --get
+@itemx -x
+
+Same as @option{--extract}. @xref{extract}.
+
+@opsummary{list}
+@item --list
+@itemx -t
+
+Lists the members in an archive. @xref{list}.
+
+@opsummary{update}
+@item --update
+@itemx -u
+
+Adds files to the end of the archive, but only if they are newer than
+their counterparts already in the archive, or if they do not already
+exist in the archive. @xref{update}.
+
+@end table
+
+@node Option Summary
+@subsection @command{tar} Options
+
+@table @option
+
+@opsummary{absolute-names}
+@item --absolute-names
+@itemx -P
+
+Normally when creating an archive, @command{tar} strips an initial
+@samp{/} from member names, and when extracting from an archive @command{tar}
+treats names specially if they have initial @samp{/} or internal
+@samp{..}. This option disables that behavior. @xref{absolute}.
+
+@opsummary{acls}
+@item --acls
+Enable POSIX ACLs support. @xref{Extended File Attributes, acls}.
+
+@opsummary{after-date}
+@item --after-date
+
+(See @option{--newer}, @pxref{after})
+
+@opsummary{anchored}
+@item --anchored
+A pattern must match an initial subsequence of the name's components.
+@xref{controlling pattern-matching}.
+
+@opsummary{atime-preserve}
+@item --atime-preserve
+@itemx --atime-preserve=replace
+@itemx --atime-preserve=system
+
+Attempt to preserve the access time of files when reading them. This
+option currently is effective only on files that you own, unless you
+have superuser privileges.
+
+@option{--atime-preserve=replace} remembers the access time of a file
+before reading it, and then restores the access time afterwards. This
+may cause problems if other programs are reading the file at the same
+time, as the times of their accesses will be lost. On most platforms
+restoring the access time also requires @command{tar} to restore the
+data modification time too, so this option may also cause problems if
+other programs are writing the file at the same time (@command{tar} attempts
+to detect this situation, but cannot do so reliably due to race
+conditions). Worse, on most platforms restoring the access time also
+updates the status change time, which means that this option is
+incompatible with incremental backups.
+
+@option{--atime-preserve=system} avoids changing time stamps on files,
+without interfering with time stamp updates
+caused by other programs, so it works better with incremental backups.
+However, it requires a special @code{O_NOATIME} option from the
+underlying operating and file system implementation, and it also requires
+that searching directories does not update their access times. As of
+this writing (November 2005) this works only with Linux, and only with
+Linux kernels 2.6.8 and later. Worse, there is currently no reliable
+way to know whether this feature actually works. Sometimes
+@command{tar} knows that it does not work, and if you use
+@option{--atime-preserve=system} then @command{tar} complains and
+exits right away. But other times @command{tar} might think that the
+option works when it actually does not.
+
+Currently @option{--atime-preserve} with no operand defaults to
+@option{--atime-preserve=replace}, but this may change in the future
+as support for @option{--atime-preserve=system} improves.
+
+If your operating or file system does not support
+@option{--atime-preserve=@-system}, you might be able to preserve access
+times reliably by using the @command{mount} command. For example,
+you can mount the file system read-only, or access the file system via
+a read-only loopback mount, or use the @samp{noatime} mount option
+available on some systems. However, mounting typically requires
+superuser privileges and can be a pain to manage.
+
+@opsummary{auto-compress}
+@item --auto-compress
+@itemx -a
+
+During a @option{--create} operation, enables automatic compressed
+format recognition based on the archive suffix. The effect of this
+option is cancelled by @option{--no-auto-compress}. @xref{gzip}.
+
+@opsummary{backup}
+@item --backup=@var{backup-type}
+
+Rather than deleting files from the file system, @command{tar} will
+back them up using simple or numbered backups, depending upon
+@var{backup-type}. @xref{backup}.
+
+@opsummary{block-number}
+@item --block-number
+@itemx -R
+
+With this option present, @command{tar} prints error messages for read errors
+with the block number in the archive file. @xref{block-number}.
+
+@opsummary{blocking-factor}
+@item --blocking-factor=@var{blocking}
+@itemx -b @var{blocking}
+
+Sets the blocking factor @command{tar} uses to @var{blocking} x 512 bytes per
+record. @xref{Blocking Factor}.
+
+@opsummary{bzip2}
+@item --bzip2
+@itemx -j
+
+This option tells @command{tar} to read or write archives through
+@code{bzip2}. @xref{gzip}.
+
+@opsummary{check-device}
+@item --check-device
+Check device numbers when creating a list of modified files for
+incremental archiving. This is the default. @xref{device numbers},
+for a detailed description.
+
+@opsummary{checkpoint}
+@item --checkpoint[=@var{number}]
+
+This option directs @command{tar} to print periodic checkpoint
+messages as it reads through the archive. It is intended for when you
+want a visual indication that @command{tar} is still running, but
+don't want to see @option{--verbose} output. You can also instruct
+@command{tar} to execute a list of actions on each checkpoint, see
+@option{--checkpoint-action} below. For a detailed description, see
+@ref{checkpoints}.
+
+@opsummary{checkpoint-action}
+@item --checkpoint-action=@var{action}
+Instruct @command{tar} to execute an action upon hitting a
+breakpoint. Here we give only a brief outline. @xref{checkpoints},
+for a complete description.
+
+The @var{action} argument can be one of the following:
+
+@table @asis
+@item bell
+Produce an audible bell on the console.
+
+@item dot
+@itemx .
+Print a single dot on the standard listing stream.
+
+@item echo
+Display a textual message on the standard error, with the status and
+number of the checkpoint. This is the default.
+
+@item echo=@var{string}
+Display @var{string} on the standard error. Before output, the string
+is subject to meta-character expansion.
+
+@item exec=@var{command}
+Execute the given @var{command}.
+
+@item sleep=@var{time}
+Wait for @var{time} seconds.
+
+@item ttyout=@var{string}
+Output @var{string} on the current console (@file{/dev/tty}).
+@end table
+
+Several @option{--checkpoint-action} options can be specified. The
+supplied actions will be executed in order of their appearance in the
+command line.
+
+Using @option{--checkpoint-action} without @option{--checkpoint}
+assumes default checkpoint frequency of one checkpoint per 10 records.
+
+@opsummary{check-links}
+@item --check-links
+@itemx -l
+If this option was given, @command{tar} will check the number of links
+dumped for each processed file. If this number does not match the
+total number of hard links for the file, a warning message will be
+output @footnote{Earlier versions of @GNUTAR{} understood @option{-l} as a
+synonym for @option{--one-file-system}. The current semantics, which
+complies to UNIX98, was introduced with version
+1.15.91. @xref{Changes}, for more information.}.
+
+@xref{hard links}.
+
+@opsummary{compress}
+@opsummary{uncompress}
+@item --compress
+@itemx --uncompress
+@itemx -Z
+
+@command{tar} will use the @command{compress} program when reading or
+writing the archive. This allows you to directly act on archives
+while saving space. @xref{gzip}.
+
+@opsummary{clamp-mtime}
+@item --clamp-mtime
+
+(See @option{--mtime}.)
+
+@opsummary{confirmation}
+@item --confirmation
+
+(See @option{--interactive}.) @xref{interactive}.
+
+@opsummary{delay-directory-restore}
+@item --delay-directory-restore
+
+Delay setting modification times and permissions of extracted
+directories until the end of extraction. @xref{Directory Modification Times and Permissions}.
+
+@opsummary{dereference}
+@item --dereference
+@itemx -h
+
+When reading or writing a file to be archived, @command{tar} accesses
+the file that a symbolic link points to, rather than the symlink
+itself. @xref{dereference}.
+
+@opsummary{directory}
+@item --directory=@var{dir}
+@itemx -C @var{dir}
+
+When this option is specified, @command{tar} will change its current directory
+to @var{dir} before performing any operations. When this option is used
+during archive creation, it is order sensitive. @xref{directory}.
+
+@opsummary{exclude}
+@item --exclude=@var{pattern}
+
+When performing operations, @command{tar} will skip files that match
+@var{pattern}. @xref{exclude}.
+
+@opsummary{exclude-backups}
+@item --exclude-backups
+Exclude backup and lock files. @xref{exclude,, exclude-backups}.
+
+@opsummary{exclude-from}
+@item --exclude-from=@var{file}
+@itemx -X @var{file}
+
+Similar to @option{--exclude}, except @command{tar} will use the list of
+patterns in the file @var{file}. @xref{exclude}.
+
+@opsummary{exclude-caches}
+@item --exclude-caches
+
+Exclude from dump any directory containing a valid cache directory
+tag file, but still dump the directory node and the tag file itself.
+
+@xref{exclude,, exclude-caches}.
+
+@opsummary{exclude-caches-under}
+@item --exclude-caches-under
+
+Exclude from dump any directory containing a valid cache directory
+tag file, but still dump the directory node itself.
+
+@xref{exclude}.
+
+@opsummary{exclude-caches-all}
+@item --exclude-caches-all
+
+Exclude from dump any directory containing a valid cache directory
+tag file. @xref{exclude}.
+
+@opsummary{exclude-ignore}
+@item --exclude-ignore=@var{file}
+Before dumping a directory, @command{tar} checks if it contains
+@var{file}. If so, exclusion patterns are read from this file.
+The patterns affect only the directory itself. @xref{exclude}.
+
+@opsummary{exclude-ignore-recursive}
+@item --exclude-ignore-recursive=@var{file}
+Before dumping a directory, @command{tar} checks if it contains
+@var{file}. If so, exclusion patterns are read from this file.
+The patterns affect the directory and all itssubdirectories.
+@xref{exclude}.
+
+@opsummary{exclude-tag}
+@item --exclude-tag=@var{file}
+
+Exclude from dump any directory containing file named @var{file}, but
+dump the directory node and @var{file} itself. @xref{exclude,, exclude-tag}.
+
+@opsummary{exclude-tag-under}
+@item --exclude-tag-under=@var{file}
+
+Exclude from dump the contents of any directory containing file
+named @var{file}, but dump the directory node itself. @xref{exclude,,
+exclude-tag-under}.
+
+@opsummary{exclude-tag-all}
+@item --exclude-tag-all=@var{file}
+
+Exclude from dump any directory containing file named @var{file}.
+@xref{exclude,,exclude-tag-all}.
+
+@opsummary{exclude-vcs}
+@item --exclude-vcs
+
+Exclude from dump directories and files, that are internal for some
+widely used version control systems.
+
+@xref{exclude-vcs}.
+
+@opsummary{exclude-vcs-ignores}
+@item --exclude-vcs-ignores
+Exclude files that match patterns read from VCS-specific ignore
+files. Supported files are: @file{.cvsignore}, @file{.gitignore},
+@file{.bzrignore}, and @file{.hgignore}. The semantics of each file
+is the same as for the corresponding VCS, e.g. patterns read from
+@file{.gitignore} affect the directory and all its subdirectories.
+@xref{exclude-vcs-ignores}.
+
+@opsummary{file}
+@item --file=@var{archive}
+@itemx -f @var{archive}
+
+@command{tar} will use the file @var{archive} as the @command{tar} archive it
+performs operations on, rather than @command{tar}'s compilation dependent
+default. @xref{file tutorial}.
+
+@opsummary{files-from}
+@item --files-from=@var{file}
+@itemx -T @var{file}
+
+@command{tar} will use the contents of @var{file} as a list of archive members
+or files to operate on, in addition to those specified on the
+command-line. @xref{files}.
+
+@opsummary{force-local}
+@item --force-local
+
+Forces @command{tar} to interpret the file name given to @option{--file}
+as a local file, even if it looks like a remote tape drive name.
+@xref{local and remote archives}.
+
+@opsummary{format}
+@item --format=@var{format}
+@itemx -H @var{format}
+
+Selects output archive format. @var{Format} may be one of the
+following:
+
+@table @samp
+@item v7
+Creates an archive that is compatible with Unix V7 @command{tar}.
+
+@item oldgnu
+Creates an archive that is compatible with GNU @command{tar} version
+1.12 or earlier.
+
+@item gnu
+Creates archive in GNU tar 1.13 format. Basically it is the same as
+@samp{oldgnu} with the only difference in the way it handles long
+numeric fields.
+
+@item ustar
+Creates a @acronym{POSIX.1-1988} compatible archive.
+
+@item posix
+Creates a @acronym{POSIX.1-2001 archive}.
+
+@end table
+
+@xref{Formats}, for a detailed discussion of these formats.
+
+@opsummary{full-time}
+@item --full-time
+This option instructs @command{tar} to print file times to their full
+resolution. Usually this means 1-second resolution, but that depends
+on the underlying file system. The @option{--full-time} option takes
+effect only when detailed output (verbosity level 2 or higher) has
+been requested using the @option{--verbose} option, e.g., when listing
+or extracting archives:
+
+@smallexample
+$ @kbd{tar -t -v --full-time -f archive.tar}
+@end smallexample
+
+@noindent
+or, when creating an archive:
+
+@smallexample
+$ @kbd{tar -c -vv --full-time -f archive.tar .}
+@end smallexample
+
+Notice, thar when creating the archive you need to specify
+@option{--verbose} twice to get a detailed output (@pxref{verbose
+tutorial}).
+
+@opsummary{group}
+@item --group=@var{group}
+
+Files added to the @command{tar} archive will have a group @acronym{ID} of @var{group},
+rather than the group from the source file. @var{group} can specify a
+symbolic name, or a numeric @acronym{ID}, or both as
+@var{name}:@var{id}. @xref{override}.
+
+Also see the @option{--group-map} option and comments for the
+@option{--owner=@var{user}} option.
+
+@opsummary{group-map}
+@item --group-map=@var{file}
+
+Read owner group translation map from @var{file}. This option allows to
+translate only certain group names and/or UIDs. @xref{override}, for a
+detailed description. When used together with @option{--group}
+option, the latter affects only those files whose owner group is not listed
+in the @var{file}.
+
+This option does not affect extraction from archives.
+
+@opsummary{gzip}
+@opsummary{gunzip}
+@opsummary{ungzip}
+@item --gzip
+@itemx --gunzip
+@itemx --ungzip
+@itemx -z
+
+This option tells @command{tar} to read or write archives through
+@command{gzip}, allowing @command{tar} to directly operate on several
+kinds of compressed archives transparently. @xref{gzip}.
+
+@opsummary{hard-dereference}
+@item --hard-dereference
+When creating an archive, dereference hard links and store the files
+they refer to, instead of creating usual hard link members.
+
+@xref{hard links}.
+
+@opsummary{help}
+@item --help
+@itemx -?
+
+@command{tar} will print out a short message summarizing the operations and
+options to @command{tar} and exit. @xref{help}.
+
+@opsummary{hole-detection}
+@item --hole-detection=@var{method}
+Use @var{method} to detect holes in sparse files. This option implies
+@option{--sparse}. Valid methods are @samp{seek} and @samp{raw}.
+Default is @samp{seek} with fallback to @samp{raw} when not
+applicable. @xref{sparse}.
+
+@opsummary{ignore-case}
+@item --ignore-case
+Ignore case when matching member or file names with
+patterns. @xref{controlling pattern-matching}.
+
+@opsummary{ignore-command-error}
+@item --ignore-command-error
+Ignore exit codes of subprocesses. @xref{Writing to an External Program}.
+
+@opsummary{ignore-failed-read}
+@item --ignore-failed-read
+
+Do not exit unsuccessfully merely because an unreadable file was encountered.
+@xref{Ignore Failed Read}.
+
+@opsummary{ignore-zeros}
+@item --ignore-zeros
+@itemx -i
+
+With this option, @command{tar} will ignore zeroed blocks in the
+archive, which normally signals EOF. @xref{Reading}.
+
+@opsummary{incremental}
+@item --incremental
+@itemx -G
+
+Informs @command{tar} that it is working with an old
+@acronym{GNU}-format incremental backup archive. It is intended
+primarily for backwards compatibility only. @xref{Incremental Dumps},
+for a detailed discussion of incremental archives.
+
+@opsummary{index-file}
+@item --index-file=@var{file}
+
+Send verbose output to @var{file} instead of to standard output.
+
+@opsummary{info-script}
+@opsummary{new-volume-script}
+@item --info-script=@var{command}
+@itemx --new-volume-script=@var{command}
+@itemx -F @var{command}
+
+When @command{tar} is performing multi-tape backups, @var{command} is run
+at the end of each tape. If it exits with nonzero status,
+@command{tar} fails immediately. @xref{info-script}, for a detailed
+discussion of this feature.
+
+@opsummary{interactive}
+@item --interactive
+@itemx --confirmation
+@itemx -w
+
+Specifies that @command{tar} should ask the user for confirmation before
+performing potentially destructive options, such as overwriting files.
+@xref{interactive}.
+
+@opsummary{keep-directory-symlink}
+@item --keep-directory-symlink
+
+This option changes the behavior of tar when it encounters a symlink
+with the same name as the directory that it is about to extract. By
+default, in this case tar would first remove the symlink and then
+proceed extracting the directory.
+
+The @option{--keep-directory-symlink} option disables this behavior
+and instructs tar to follow symlinks to directories when extracting
+from the archive.
+
+It is mainly intended to provide compatibility with the Slackware
+installation scripts.
+
+@opsummary{keep-newer-files}
+@item --keep-newer-files
+
+Do not replace existing files that are newer than their archive copies
+when extracting files from an archive.
+
+@opsummary{keep-old-files}
+@item --keep-old-files
+@itemx -k
+
+Do not overwrite existing files when extracting files from an
+archive. Return error if such files exist. See also
+@ref{--skip-old-files}.
+
+@xref{Keep Old Files}.
+
+@opsummary{label}
+@item --label=@var{name}
+@itemx -V @var{name}
+
+When creating an archive, instructs @command{tar} to write @var{name}
+as a name record in the archive. When extracting or listing archives,
+@command{tar} will only operate on archives that have a label matching
+the pattern specified in @var{name}. @xref{Tape Files}.
+
+@opsummary{level}
+@item --level=@var{n}
+Force incremental backup of level @var{n}. As of @GNUTAR version
+@value{VERSION}, the option @option{--level=0} truncates the snapshot
+file, thereby forcing the level 0 dump. Other values of @var{n} are
+effectively ignored. @xref{--level=0}, for details and examples.
+
+The use of this option is valid only in conjunction with the
+@option{--listed-incremental} option. @xref{Incremental Dumps},
+for a detailed description.
+
+@opsummary{listed-incremental}
+@item --listed-incremental=@var{snapshot-file}
+@itemx -g @var{snapshot-file}
+
+During a @option{--create} operation, specifies that the archive that
+@command{tar} creates is a new @acronym{GNU}-format incremental
+backup, using @var{snapshot-file} to determine which files to backup.
+With other operations, informs @command{tar} that the archive is in
+incremental format. @xref{Incremental Dumps}.
+
+@opsummary{lzip}
+@item --lzip
+
+This option tells @command{tar} to read or write archives through
+@command{lzip}. @xref{gzip}.
+
+@opsummary{lzma}
+@item --lzma
+
+This option tells @command{tar} to read or write archives through
+@command{lzma}. @xref{gzip}.
+
+@item --lzop
+
+This option tells @command{tar} to read or write archives through
+@command{lzop}. @xref{gzip}.
+
+@opsummary{mode}
+@item --mode=@var{permissions}
+
+When adding files to an archive, @command{tar} will use
+@var{permissions} for the archive members, rather than the permissions
+from the files. @var{permissions} can be specified either as an octal
+number or as symbolic permissions, like with
+@command{chmod}. @xref{override}.
+
+@opsummary{mtime}
+@item --mtime=@var{date}
+
+When adding files to an archive, @command{tar} will use @var{date} as
+the modification time of members when creating archives, instead of
+their actual modification times. The value of @var{date} can be
+either a textual date representation (@pxref{Date input formats}) or a
+name of the existing file, starting with @samp{/} or @samp{.}. In the
+latter case, the modification time of that file is used. @xref{override}.
+
+When @command{--clamp-mtime} is also specified, files with
+modification times earlier than @var{date} will retain their actual
+modification times, and @var{date} will only be used for files whose
+modification times are later than @var{date}.
+
+@opsummary{multi-volume}
+@item --multi-volume
+@itemx -M
+
+Informs @command{tar} that it should create or otherwise operate on a
+multi-volume @command{tar} archive. @xref{Using Multiple Tapes}.
+
+@opsummary{new-volume-script}
+@item --new-volume-script
+
+(see @option{--info-script})
+
+@opsummary{newer}
+@item --newer=@var{date}
+@itemx --after-date=@var{date}
+@itemx -N
+
+When creating an archive, @command{tar} will only add files that have changed
+since @var{date}. If @var{date} begins with @samp{/} or @samp{.}, it
+is taken to be the name of a file whose data modification time specifies
+the date. @xref{after}.
+
+@opsummary{newer-mtime}
+@item --newer-mtime=@var{date}
+
+Like @option{--newer}, but add only files whose
+contents have changed (as opposed to just @option{--newer}, which will
+also back up files for which any status information has
+changed). @xref{after}.
+
+@opsummary{no-acls}
+@item --no-acls
+Disable the POSIX ACLs support. @xref{Extended File Attributes, acls}.
+
+@opsummary{no-anchored}
+@item --no-anchored
+An exclude pattern can match any subsequence of the name's components.
+@xref{controlling pattern-matching}.
+
+@opsummary{no-auto-compress}
+@item --no-auto-compress
+
+Disables automatic compressed format recognition based on the archive
+suffix. @xref{--auto-compress}. @xref{gzip}.
+
+@opsummary{no-check-device}
+@item --no-check-device
+Do not check device numbers when creating a list of modified files
+for incremental archiving. @xref{device numbers}, for
+a detailed description.
+
+@opsummary{no-delay-directory-restore}
+@item --no-delay-directory-restore
+
+Modification times and permissions of extracted
+directories are set when all files from this directory have been
+extracted. This is the default.
+@xref{Directory Modification Times and Permissions}.
+
+@opsummary{no-ignore-case}
+@item --no-ignore-case
+Use case-sensitive matching.
+@xref{controlling pattern-matching}.
+
+@opsummary{no-ignore-command-error}
+@item --no-ignore-command-error
+Print warnings about subprocesses that terminated with a nonzero exit
+code. @xref{Writing to an External Program}.
+
+@opsummary{no-null}
+@item --no-null
+
+If the @option{--null} option was given previously, this option
+cancels its effect, so that any following @option{--files-from}
+options will expect their file lists to be newline-terminated.
+
+@opsummary{no-overwrite-dir}
+@item --no-overwrite-dir
+
+Preserve metadata of existing directories when extracting files
+from an archive. @xref{Overwrite Old Files}.
+
+@opsummary{no-quote-chars}
+@item --no-quote-chars=@var{string}
+Remove characters listed in @var{string} from the list of quoted
+characters set by the previous @option{--quote-chars} option
+(@pxref{quoting styles}).
+
+@opsummary{no-recursion}
+@item --no-recursion
+
+With this option, @command{tar} will not recurse into directories.
+@xref{recurse}.
+
+@opsummary{no-same-owner}
+@item --no-same-owner
+@itemx -o
+
+When extracting an archive, do not attempt to preserve the owner
+specified in the @command{tar} archive. This the default behavior
+for ordinary users.
+
+@opsummary{no-same-permissions}
+@item --no-same-permissions
+
+When extracting an archive, subtract the user's umask from files from
+the permissions specified in the archive. This is the default behavior
+for ordinary users.
+
+@opsummary{no-seek}
+@item --no-seek
+
+The archive media does not support seeks to arbitrary
+locations. Usually @command{tar} determines automatically whether
+the archive can be seeked or not. Use this option to disable this
+mechanism.
+
+@opsummary{no-selinux}
+@item --no-selinux
+Disable SELinux context support. @xref{Extended File Attributes, SELinux}.
+
+@opsummary{no-unquote}
+@item --no-unquote
+Treat all input file or member names literally, do not interpret
+escape sequences. @xref{input name quoting}.
+
+@opsummary{no-verbatim-files-from}
+@item --no-verbatim-files-from
+
+Instructs @GNUTAR{} to treat each line read from a file list as if it
+were supplied in the command line. I.e., leading and trailing
+whitespace is removed and, if the result begins with a dash, it is
+treated as a @GNUTAR{} command line option.
+
+This is default behavior. This option is provided as a way to restore
+it after @option{--verbatim-files-from} option.
+
+It is implied by the @option{--no-null} option.
+
+@xref{no-verbatim-files-from}.
+
+@opsummary{no-wildcards}
+@item --no-wildcards
+Do not use wildcards.
+@xref{controlling pattern-matching}.
+
+@opsummary{no-wildcards-match-slash}
+@item --no-wildcards-match-slash
+Wildcards do not match @samp{/}.
+@xref{controlling pattern-matching}.
+
+@opsummary{no-xattrs}
+@item --no-xattrs
+Disable extended attributes support. @xref{Extended File Attributes, xattrs}.
+
+@opsummary{null}
+@item --null
+
+When @command{tar} is using the @option{--files-from} option, this option
+instructs @command{tar} to expect file names terminated with
+@acronym{NUL}, and to process file names verbatim.
+
+This means that @command{tar} correctly works with file names that
+contain newlines or begin with a dash.
+
+@xref{nul}.
+
+See also @ref{verbatim-files-from}.
+
+@opsummary{numeric-owner}
+@item --numeric-owner
+
+This option will notify @command{tar} that it should use numeric user
+and group IDs when creating a @command{tar} file, rather than names.
+@xref{Attributes}.
+
+@item -o
+The function of this option depends on the action @command{tar} is
+performing. When extracting files, @option{-o} is a synonym for
+@option{--no-same-owner}, i.e., it prevents @command{tar} from
+restoring ownership of files being extracted.
+
+When creating an archive, it is a synonym for
+@option{--old-archive}. This behavior is for compatibility
+with previous versions of @GNUTAR{}, and will be
+removed in future releases.
+
+@xref{Changes}, for more information.
+
+@opsummary{occurrence}
+@item --occurrence[=@var{number}]
+
+This option can be used in conjunction with one of the subcommands
+@option{--delete}, @option{--diff}, @option{--extract} or
+@option{--list} when a list of files is given either on the command
+line or via @option{-T} option.
+
+This option instructs @command{tar} to process only the @var{number}th
+occurrence of each named file. @var{Number} defaults to 1, so
+
+@smallexample
+tar -x -f archive.tar --occurrence filename
+@end smallexample
+
+@noindent
+will extract the first occurrence of the member @file{filename} from @file{archive.tar}
+and will terminate without scanning to the end of the archive.
+
+@opsummary{old-archive}
+@item --old-archive
+Synonym for @option{--format=v7}.
+
+@opsummary{one-file-system}
+@item --one-file-system
+Used when creating an archive. Prevents @command{tar} from recursing into
+directories that are on different file systems from the current
+directory.
+
+@opsummary{one-top-level}
+@item --one-top-level[=@var{dir}]
+Tells @command{tar} to create a new directory beneath the extraction directory
+(or the one passed to @option{-C}) and use it to guard against
+tarbombs. In the absence of @var{dir} argument, the name of the new directory
+will be equal to the base name of the archive (file name minus the
+archive suffix, if recognized). Any member names that do not begin
+with that directory name (after
+transformations from @option{--transform} and
+@option{--strip-components}) will be prefixed with it. Recognized
+file name suffixes are @samp{.tar}, and any compression suffixes
+recognizable by @xref{--auto-compress}.
+
+@opsummary{overwrite}
+@item --overwrite
+
+Overwrite existing files and directory metadata when extracting files
+from an archive. @xref{Overwrite Old Files}.
+
+@opsummary{overwrite-dir}
+@item --overwrite-dir
+
+Overwrite the metadata of existing directories when extracting files
+from an archive. @xref{Overwrite Old Files}.
+
+@opsummary{owner}
+@item --owner=@var{user}
+
+Specifies that @command{tar} should use @var{user} as the owner of members
+when creating archives, instead of the user associated with the source
+file. @var{user} can specify a symbolic name, or a numeric
+@acronym{ID}, or both as @var{name}:@var{id}.
+@xref{override}.
+
+This option does not affect extraction from archives. See also
+@option{--owner-map}, below.
+
+@opsummary{owner-map}
+@item --owner-map=@var{file}
+
+Read owner translation map from @var{file}. This option allows to
+translate only certain owner names or UIDs. @xref{override}, for a
+detailed description. When used together with @option{--owner}
+option, the latter affects only those files whose owner is not listed
+in the @var{file}.
+
+This option does not affect extraction from archives.
+
+@opsummary{pax-option}
+@item --pax-option=@var{keyword-list}
+This option enables creation of the archive in @acronym{POSIX.1-2001}
+format (@pxref{posix}) and modifies the way @command{tar} handles the
+extended header keywords. @var{Keyword-list} is a comma-separated
+list of keyword options. @xref{PAX keywords}, for a detailed
+discussion.
+
+@opsummary{portability}
+@item --portability
+@itemx --old-archive
+Synonym for @option{--format=v7}.
+
+@opsummary{posix}
+@item --posix
+Same as @option{--format=posix}.
+
+@opsummary{preserve-order}
+@item --preserve-order
+
+(See @option{--same-order}; @pxref{Reading}.)
+
+@opsummary{preserve-permissions}
+@opsummary{same-permissions}
+@item --preserve-permissions
+@itemx --same-permissions
+@itemx -p
+
+When @command{tar} is extracting an archive, it normally subtracts the
+users' umask from the permissions specified in the archive and uses
+that number as the permissions to create the destination file.
+Specifying this option instructs @command{tar} that it should use the
+permissions directly from the archive. @xref{Setting Access Permissions}.
+
+@opsummary{quote-chars}
+@item --quote-chars=@var{string}
+Always quote characters from @var{string}, even if the selected
+quoting style would not quote them (@pxref{quoting styles}).
+
+@opsummary{quoting-style}
+@item --quoting-style=@var{style}
+Set quoting style to use when printing member and file names
+(@pxref{quoting styles}). Valid @var{style} values are:
+@code{literal}, @code{shell}, @code{shell-always}, @code{c},
+@code{escape}, @code{locale}, and @code{clocale}. Default quoting
+style is @code{escape}, unless overridden while configuring the
+package.
+
+@opsummary{read-full-records}
+@item --read-full-records
+@itemx -B
+
+Specifies that @command{tar} should reblock its input, for reading
+from pipes on systems with buggy implementations. @xref{Reading}.
+
+@opsummary{record-size}
+@item --record-size=@var{size}[@var{suf}]
+
+Instructs @command{tar} to use @var{size} bytes per record when accessing the
+archive. The argument can be suffixed with a @dfn{size suffix}, e.g.
+@option{--record-size=10K} for 10 Kilobytes. @xref{size-suffixes},
+for a list of valid suffixes. @xref{Blocking Factor}, for a detailed
+description of this option.
+
+@opsummary{recursion}
+@item --recursion
+
+With this option, @command{tar} recurses into directories (default).
+@xref{recurse}.
+
+@opsummary{recursive-unlink}
+@item --recursive-unlink
+
+Remove existing
+directory hierarchies before extracting directories of the same name
+from the archive. @xref{Recursive Unlink}.
+
+@opsummary{remove-files}
+@item --remove-files
+
+Directs @command{tar} to remove the source file from the file system after
+appending it to an archive. @xref{remove files}.
+
+@opsummary{restrict}
+@item --restrict
+
+Disable use of some potentially harmful @command{tar} options.
+Currently this option disables shell invocation from multi-volume menu
+(@pxref{Using Multiple Tapes}).
+
+@opsummary{rmt-command}
+@item --rmt-command=@var{cmd}
+
+Notifies @command{tar} that it should use @var{cmd} instead of
+the default @file{/usr/libexec/rmt} (@pxref{Remote Tape Server}).
+
+@opsummary{rsh-command}
+@item --rsh-command=@var{cmd}
+
+Notifies @command{tar} that is should use @var{cmd} to communicate with remote
+devices. @xref{Device}.
+
+@opsummary{same-order}
+@item --same-order
+@itemx --preserve-order
+@itemx -s
+
+This option is an optimization for @command{tar} when running on machines with
+small amounts of memory. It informs @command{tar} that the list of file
+arguments has already been sorted to match the order of files in the
+archive. @xref{Reading}.
+
+@opsummary{same-owner}
+@item --same-owner
+
+When extracting an archive, @command{tar} will attempt to preserve the owner
+specified in the @command{tar} archive with this option present.
+This is the default behavior for the superuser; this option has an
+effect only for ordinary users. @xref{Attributes}.
+
+@opsummary{same-permissions}
+@item --same-permissions
+
+(See @option{--preserve-permissions}; @pxref{Setting Access Permissions}.)
+
+@opsummary{seek}
+@item --seek
+@itemx -n
+
+Assume that the archive media supports seeks to arbitrary
+locations. Usually @command{tar} determines automatically whether
+the archive can be seeked or not. This option is intended for use
+in cases when such recognition fails. It takes effect only if the
+archive is open for reading (e.g. with @option{--list} or
+@option{--extract} options).
+
+@opsummary{selinux}
+@item --selinux
+Enable the SELinux context support.
+@xref{Extended File Attributes, selinux}.
+
+@opsummary{show-defaults}
+@item --show-defaults
+
+Displays the default options used by @command{tar} and exits
+successfully. This option is intended for use in shell scripts.
+Here is an example of what you can see using this option:
+
+@smallexample
+$ @kbd{tar --show-defaults}
+--format=gnu -f- -b20 --quoting-style=escape
+--rmt-command=/usr/libexec/rmt --rsh-command=/usr/bin/rsh
+@end smallexample
+
+@noindent
+Notice, that this option outputs only one line. The example output
+above has been split to fit page boundaries. @xref{defaults}.
+
+@opsummary{show-omitted-dirs}
+@item --show-omitted-dirs
+
+Instructs @command{tar} to mention the directories it is skipping when
+operating on a @command{tar} archive. @xref{show-omitted-dirs}.
+
+@opsummary{show-snapshot-field-ranges}
+@item --show-snapshot-field-ranges
+
+Displays the range of values allowed by this version of @command{tar}
+for each field in the snapshot file, then exits successfully.
+@xref{Snapshot Files}.
+
+@opsummary{show-transformed-names}
+@opsummary{show-stored-names}
+@item --show-transformed-names
+@itemx --show-stored-names
+
+Display file or member names after applying any transformations
+(@pxref{transform}). In particular, when used in conjunction with one of
+the archive creation operations it instructs @command{tar} to list the
+member names stored in the archive, as opposed to the actual file
+names. @xref{listing member and file names}.
+
+@opsummary{skip-old-files}
+@item --skip-old-files
+
+Do not overwrite existing files when extracting files from an
+archive. @xref{Keep Old Files}.
+
+This option differs from @option{--keep-old-files} in that it does not
+treat such files as an error, instead it just silently avoids
+overwriting them.
+
+The @option{--warning=existing-file} option can be used together with
+this option to produce warning messages about existing old files
+(@pxref{warnings}).
+
+@opsummary{sort}
+@item --sort=@var{order}
+Specify the directory sorting order when reading directories.
+@var{Order} may be one of the following:
+
+@table @samp
+@item none
+No directory sorting is performed. This is the default.
+
+@item name
+Sort the directory entries on name. The operating system may deliver
+directory entries in a more or less random order, and sorting them
+makes archive creation reproducible.
+
+@item inode
+Sort the directory entries on inode number. Sorting directories on
+inode number may reduce the amount of disk seek operations when
+creating an archive for some file systems.
+
+@end table
+
+@opsummary{sparse}
+@item --sparse
+@itemx -S
+
+Invokes a @acronym{GNU} extension when adding files to an archive that handles
+sparse files efficiently. @xref{sparse}.
+
+@opsummary{sparse-version}
+@item --sparse-version=@var{version}
+
+Specifies the @dfn{format version} to use when archiving sparse
+files. Implies @option{--sparse}. @xref{sparse}. For the description
+of the supported sparse formats, @xref{Sparse Formats}.
+
+@opsummary{starting-file}
+@item --starting-file=@var{name}
+@itemx -K @var{name}
+
+This option affects extraction only; @command{tar} will skip extracting
+files in the archive until it finds one that matches @var{name}.
+@xref{Scarce}.
+
+@opsummary{strip-components}
+@item --strip-components=@var{number}
+Strip given @var{number} of leading components from file names before
+extraction. For example, if archive @file{archive.tar} contained
+@file{/some/file/name}, then running
+
+@smallexample
+tar --extract --file archive.tar --strip-components=2
+@end smallexample
+
+@noindent
+would extract this file to file @file{name}.
+
+@xref{transform}.
+
+@opsummary{suffix}
+@item --suffix=@var{suffix}
+
+Alters the suffix @command{tar} uses when backing up files from the default
+@samp{~}. @xref{backup}.
+
+@opsummary{tape-length}
+@item --tape-length=@var{num}[@var{suf}]
+@itemx -L @var{num}[@var{suf}]
+
+Specifies the length of tapes that @command{tar} is writing as being
+@w{@var{num} x 1024} bytes long. If optional @var{suf} is given, it
+specifies a multiplicative factor to be used instead of 1024. For
+example, @samp{-L2M} means 2 megabytes. @xref{size-suffixes}, for a
+list of allowed suffixes. @xref{Using Multiple Tapes}, for a detailed
+discussion of this option.
+
+@opsummary{test-label}
+@item --test-label
+
+Reads the volume label. If an argument is specified, test whether it
+matches the volume label. @xref{--test-label option}.
+
+@opsummary{to-command}
+@item --to-command=@var{command}
+
+During extraction @command{tar} will pipe extracted files to the
+standard input of @var{command}. @xref{Writing to an External Program}.
+
+@opsummary{to-stdout}
+@item --to-stdout
+@itemx -O
+
+During extraction, @command{tar} will extract files to stdout rather
+than to the file system. @xref{Writing to Standard Output}.
+
+@opsummary{totals}
+@item --totals[=@var{signo}]
+
+Displays the total number of bytes transferred when processing an
+archive. If an argument is given, these data are displayed on
+request, when signal @var{signo} is delivered to @command{tar}.
+@xref{totals}.
+
+@opsummary{touch}
+@item --touch
+@itemx -m
+
+Sets the data modification time of extracted files to the extraction time,
+rather than the data modification time stored in the archive.
+@xref{Data Modification Times}.
+
+@opsummary{transform}
+@opsummary{xform}
+@item --transform=@var{sed-expr}
+@itemx --xform=@var{sed-expr}
+Transform file or member names using @command{sed} replacement expression
+@var{sed-expr}. For example,
+
+@smallexample
+$ @kbd{tar cf archive.tar --transform 's,^\./,usr/,' .}
+@end smallexample
+
+@noindent
+will add to @file{archive} files from the current working directory,
+replacing initial @samp{./} prefix with @samp{usr/}. For the detailed
+discussion, @xref{transform}.
+
+To see transformed member names in verbose listings, use
+@option{--show-transformed-names} option
+(@pxref{show-transformed-names}).
+
+@opsummary{uncompress}
+@item --uncompress
+
+(See @option{--compress}, @pxref{gzip})
+
+@opsummary{ungzip}
+@item --ungzip
+
+(See @option{--gzip}, @pxref{gzip})
+
+@opsummary{unlink-first}
+@item --unlink-first
+@itemx -U
+
+Directs @command{tar} to remove the corresponding file from the file
+system before extracting it from the archive. @xref{Unlink First}.
+
+@opsummary{unquote}
+@item --unquote
+Enable unquoting input file or member names (default). @xref{input
+name quoting}.
+
+@opsummary{use-compress-program}
+@item --use-compress-program=@var{prog}
+@itemx -I=@var{prog}
+
+Instructs @command{tar} to access the archive through @var{prog}, which is
+presumed to be a compression program of some sort. @xref{gzip}.
+
+@opsummary{utc}
+@item --utc
+
+Display file modification dates in @acronym{UTC}. This option implies
+@option{--verbose}.
+
+@opsummary{verbatim-files-from}
+@item --verbatim-files-from
+
+Instructs @GNUTAR{} to treat each line read from a file list as a file
+name, even if it starts with a dash.
+
+File lists are supplied with the @option{--files-from} (@option{-T})
+option. By default, each line read from a file list is first trimmed
+off the leading and trailing whitespace and, if the result begins with
+a dash, it is treated as a @GNUTAR{} command line option.
+
+Use the @option{--verbatim-files-from} option to disable this special
+handling. This facilitates the use of @command{tar} with file lists
+created by @command{file} command.
+
+This option affects all @option{--files-from} options that occur after
+it in the command line. Its effect is reverted by the
+@option{--no-verbatim-files-from} option.
+
+This option is implied by the @option{--null} option.
+
+@xref{verbatim-files-from}.
+
+@opsummary{verbose}
+@item --verbose
+@itemx -v
+
+Specifies that @command{tar} should be more verbose about the
+operations it is performing. This option can be specified multiple
+times for some operations to increase the amount of information displayed.
+@xref{verbose}.
+
+@opsummary{verify}
+@item --verify
+@itemx -W
+
+Verifies that the archive was correctly written when creating an
+archive. @xref{verify}.
+
+@opsummary{version}
+@item --version
+
+Print information about the program's name, version, origin and legal
+status, all on standard output, and then exit successfully.
+@xref{help}.
+
+@opsummary{volno-file}
+@item --volno-file=@var{file}
+
+Used in conjunction with @option{--multi-volume}. @command{tar} will
+keep track of which volume of a multi-volume archive it is working in
+@var{file}. @xref{volno-file}.
+
+@opsummary{warning}
+@item --warning=@var{keyword}
+
+Enable or disable warning messages identified by @var{keyword}. The
+messages are suppressed if @var{keyword} is prefixed with @samp{no-}.
+@xref{warnings}.
+
+@opsummary{wildcards}
+@item --wildcards
+Use wildcards when matching member names with patterns.
+@xref{controlling pattern-matching}.
+
+@opsummary{wildcards-match-slash}
+@item --wildcards-match-slash
+Wildcards match @samp{/}.
+@xref{controlling pattern-matching}.
+
+@opsummary{xattrs}
+@item --xattrs
+Enable extended attributes support. @xref{Extended File Attributes, xattrs}.
+
+@opsummary{xattrs-exclude}
+@item --xattrs-exclude=@var{pattern}
+Specify exclude pattern for xattr keys.
+@xref{Extended File Attributes, xattrs-exclude}.
+
+@opsummary{xattrs-include}
+@item --xattrs-include=@var{pattern}.
+Specify include pattern for xattr keys. @var{pattern} is a POSIX
+regular expression, e.g. @samp{--xattrs-exclude='^user\.'} to include
+only attributes from the user namespace.
+@xref{Extended File Attributes, xattrs-include}.
+
+@opsummary{xz}
+@item --xz
+@itemx -J
+Use @command{xz} for compressing or decompressing the archives. @xref{gzip}.
+
+@end table
+
+@node Short Option Summary
+@subsection Short Options Cross Reference
+
+Here is an alphabetized list of all of the short option forms, matching
+them with the equivalent long option.
+
+@multitable @columnfractions 0.20 0.80
+@headitem Short Option @tab Reference
+
+@item -A @tab @ref{--concatenate}.
+
+@item -B @tab @ref{--read-full-records}.
+
+@item -C @tab @ref{--directory}.
+
+@item -F @tab @ref{--info-script}.
+
+@item -G @tab @ref{--incremental}.
+
+@item -J @tab @ref{--xz}.
+
+@item -K @tab @ref{--starting-file}.
+
+@item -L @tab @ref{--tape-length}.
+
+@item -M @tab @ref{--multi-volume}.
+
+@item -N @tab @ref{--newer}.
+
+@item -O @tab @ref{--to-stdout}.
+
+@item -P @tab @ref{--absolute-names}.
+
+@item -R @tab @ref{--block-number}.
+
+@item -S @tab @ref{--sparse}.
+
+@item -T @tab @ref{--files-from}.
+
+@item -U @tab @ref{--unlink-first}.
+
+@item -V @tab @ref{--label}.
+
+@item -W @tab @ref{--verify}.
+
+@item -X @tab @ref{--exclude-from}.
+
+@item -Z @tab @ref{--compress}.
+
+@item -b @tab @ref{--blocking-factor}.
+
+@item -c @tab @ref{--create}.
+
+@item -d @tab @ref{--compare}.
+
+@item -f @tab @ref{--file}.
+
+@item -g @tab @ref{--listed-incremental}.
+
+@item -h @tab @ref{--dereference}.
+
+@item -i @tab @ref{--ignore-zeros}.
+
+@item -j @tab @ref{--bzip2}.
+
+@item -k @tab @ref{--keep-old-files}.
+
+@item -l @tab @ref{--check-links}.
+
+@item -m @tab @ref{--touch}.
+
+@item -o @tab When creating, @ref{--no-same-owner}, when extracting ---
+@ref{--portability}.
+
+The latter usage is deprecated. It is retained for compatibility with
+the earlier versions of @GNUTAR{}. In future releases
+@option{-o} will be equivalent to @option{--no-same-owner} only.
+
+@item -p @tab @ref{--preserve-permissions}.
+
+@item -r @tab @ref{--append}.
+
+@item -s @tab @ref{--same-order}.
+
+@item -t @tab @ref{--list}.
+
+@item -u @tab @ref{--update}.
+
+@item -v @tab @ref{--verbose}.
+
+@item -w @tab @ref{--interactive}.
+
+@item -x @tab @ref{--extract}.
+
+@item -z @tab @ref{--gzip}.
+
+@end multitable
+
+@node Position-Sensitive Options
+@subsection Position-Sensitive Options
+
+Some @GNUTAR{} options can be used multiple times in the same
+invocation and affect all arguments that appear after them. These are
+options that control how file names are selected and what kind of
+pattern matching is used.
+
+The most obvious example is the @option{-C} option. It instructs @command{tar}
+to change to the directory given as its argument prior to processing
+the rest of command line (@pxref{directory}). Thus, in the following
+command:
+
+@example
+@kbd{tar -c -f a.tar -C /etc passwd -C /var log spool}
+@end example
+
+@noindent
+the file @file{passwd} will be searched in the directory @file{/etc},
+and files @file{log} and @file{spool} -- in @file{/var}.
+
+These options can also be used in a file list supplied with the
+@option{--files-from} (@option{-T}) option (@pxref{files}). In that
+case they affect all files (patterns) appearing in that file after
+them and remain in effect for any arguments processed after that file.
+For example, if the file @file{list.txt} contained:
+
+@example
+README
+-C src
+main.c
+@end example
+
+@noindent
+and @command{tar} were invoked as follows:
+
+@example
+@kbd{tar -c -f a.tar -T list.txt Makefile}
+@end example
+
+@noindent
+then the file @file{README} would be looked up in the current working
+directory, and files @file{main.c} and @file{Makefile} would be looked
+up in the directory @file{src}.
+
+Many options can be prefixed with @option{--no-} to cancel the effect
+of the original option.
+
+For example, the @option{--recursion} option controls whether to
+recurse in the subdirectories. It's counterpart
+@option{--no-recursion} disables this. Consider the command below. It will
+store in the archive the directory @file{/usr} with all files and
+directories that are located in it as well as any files and
+directories in @file{/var}, without recursing into them@footnote{The @option{--recursion}
+option is the default and is used here for clarity. The same example
+can be written as:
+
+@example
+tar -cf a.tar /usr --no-recursion /var/*
+@end example
+}:
+
+@example
+tar -cf a.tar --recursion /usr --no-recursion /var/*
+@end example
+
+The following table summarizes all position-sensitive options.
+
+@table @option
+@item --directory=@var{dir}
+@itemx -C @var{dir}
+@xref{directory}.
+
+@item --null
+@itemx --no-null
+@xref{nul}.
+
+@item --unquote
+@itemx --no-unquote
+@xref{input name quoting}.
+
+@item --verbatim-files-from
+@itemx --no-verbatim-files-from
+@xref{verbatim-files-from}.
+
+@item --recursion
+@itemx --no-recursion
+@xref{recurse}.
+
+@item --anchored
+@itemx --no-anchored
+@xref{anchored patterns}.
+
+@item --ignore-case
+@itemx --no-ignore-case
+@xref{case-insensitive matches}.
+
+@item --wildcards
+@itemx --no-wildcards
+@xref{controlling pattern-matching}.
+
+@item --wildcards-match-slash
+@itemx --no-wildcards-match-slash
+@xref{controlling pattern-matching}.
+
+@item --exclude
+@xref{exclude}.
+
+@item --exclude-from
+@itemx -X
+@itemx --exclude-caches
+@itemx --exclude-caches-under
+@itemx --exclude-caches-all
+@itemx --exclude-tag
+@itemx --exclude-ignore
+@itemx --exclude-ignore-recursive
+@itemx --exclude-tag-under
+@itemx --exclude-tag-all
+@itemx --exclude-vcs
+@itemx --exclude-vcs-ignores
+@itemx --exclude-backups
+@xref{exclude}.
+@end table
+
+@node help
+@section @GNUTAR{} documentation
+
+@cindex Getting program version number
+@opindex version
+@cindex Version of the @command{tar} program
+Being careful, the first thing is really checking that you are using
+@GNUTAR{}, indeed. The @option{--version} option
+causes @command{tar} to print information about its name, version,
+origin and legal status, all on standard output, and then exit
+successfully. For example, @w{@samp{tar --version}} might print:
+
+@smallexample
+tar (GNU tar) @value{VERSION}
+Copyright (C) 2013-2016 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+
+Written by John Gilmore and Jay Fenlason.
+@end smallexample
+
+@noindent
+The first occurrence of @samp{tar} in the result above is the program
+name in the package (for example, @command{rmt} is another program),
+while the second occurrence of @samp{tar} is the name of the package
+itself, containing possibly many programs. The package is currently
+named @samp{tar}, after the name of the main program it
+contains@footnote{There are plans to merge the @command{cpio} and
+@command{tar} packages into a single one which would be called
+@code{paxutils}. So, who knows if, one of this days, the
+@option{--version} would not output @w{@samp{tar (@acronym{GNU}
+paxutils) 3.2}}.}.
+
+@cindex Obtaining help
+@cindex Listing all @command{tar} options
+@xopindex{help, introduction}
+Another thing you might want to do is checking the spelling or meaning
+of some particular @command{tar} option, without resorting to this
+manual, for once you have carefully read it. @GNUTAR{}
+has a short help feature, triggerable through the
+@option{--help} option. By using this option, @command{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:
+
+@smallexample
+$ @kbd{tar --help | less}
+@end smallexample
+
+@noindent
+presuming, here, that you like using @command{less} for a pager. Other
+popular pagers are @command{more} and @command{pg}. If you know about some
+@var{keyword} which interests you and do not want to read all the
+@option{--help} output, another common idiom is doing:
+
+@smallexample
+tar --help | grep @var{keyword}
+@end smallexample
+
+@noindent
+for getting only the pertinent lines. Notice, however, that some
+@command{tar} options have long description lines and the above
+command will list only the first of them.
+
+The exact look of the option summary displayed by @kbd{tar --help} is
+configurable. @xref{Configuring Help Summary}, for a detailed description.
+
+@opindex usage
+If you only wish to check the spelling of an option, running @kbd{tar
+--usage} may be a better choice. This will display a terse list of
+@command{tar} options without accompanying explanations.
+
+The short help output is quite succinct, and you might have to get
+back to the full documentation for precise points. If you are reading
+this paragraph, you already have the @command{tar} manual in some
+form. This manual is available in a variety of forms from
+@url{http://www.gnu.org/software/tar/manual}. It may be printed out of the @GNUTAR{}
+distribution, provided you have @TeX{} already installed somewhere,
+and a laser printer around. Just configure the distribution, execute
+the command @w{@samp{make dvi}}, then print @file{doc/tar.dvi} the
+usual way (contact your local guru to know how). If @GNUTAR{}
+has been conveniently installed at your place, this
+manual is also available in interactive, hypertextual form as an Info
+file. Just call @w{@samp{info tar}} or, if you do not have the
+@command{info} program handy, use the Info reader provided within
+@acronym{GNU} Emacs, calling @samp{tar} from the main Info menu.
+
+There is currently no @code{man} page for @GNUTAR{}.
+If you observe such a @code{man} page on the system you are running,
+either it does not belong to @GNUTAR{}, or it has not
+been produced by @acronym{GNU}. Some package maintainers convert
+@kbd{tar --help} output to a man page, using @command{help2man}. In
+any case, please bear in mind that the authoritative source of
+information about @GNUTAR{} is this Texinfo documentation.
+
+@node defaults
+@section Obtaining @GNUTAR{} default values
+
+@opindex show-defaults
+@GNUTAR{} has some predefined defaults that are used when you do not
+explicitly specify another values. To obtain a list of such
+defaults, use @option{--show-defaults} option. This will output the
+values in the form of @command{tar} command line options:
+
+@smallexample
+@group
+$ @kbd{tar --show-defaults}
+--format=gnu -f- -b20 --quoting-style=escape
+--rmt-command=/etc/rmt --rsh-command=/usr/bin/rsh
+@end group
+@end smallexample
+
+@noindent
+Notice, that this option outputs only one line. The example output above
+has been split to fit page boundaries.
+
+@noindent
+The above output shows that this version of @GNUTAR{} defaults to
+using @samp{gnu} archive format (@pxref{Formats}), it uses standard
+output as the archive, if no @option{--file} option has been given
+(@pxref{file tutorial}), the default blocking factor is 20
+(@pxref{Blocking Factor}). It also shows the default locations where
+@command{tar} will look for @command{rmt} and @command{rsh} binaries.
+
+@node verbose
+@section Checking @command{tar} progress
+
+Typically, @command{tar} performs most operations without reporting any
+information to the user except error messages. When using @command{tar}
+with many options, particularly ones with complicated or
+difficult-to-predict behavior, it is possible to make serious mistakes.
+@command{tar} provides several options that make observing @command{tar}
+easier. These options cause @command{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.
+
+@cindex Verbose operation
+@opindex verbose
+Normally, the @option{--list} (@option{-t}) command to list an archive
+prints just the file names (one per line) and the other commands are
+silent. When used with most operations, the @option{--verbose}
+(@option{-v}) option causes @command{tar} to print the name of each
+file or archive member as it is processed. This and the other options
+which make @command{tar} print status information can be useful in
+monitoring @command{tar}.
+
+With @option{--create} or @option{--extract}, @option{--verbose} used
+once just prints the names of the files or members as they are processed.
+Using it twice causes @command{tar} to print a longer listing
+(@xref{verbose member listing}, for the description) for each member.
+Since @option{--list} already prints the names of the members,
+@option{--verbose} used once with @option{--list} causes @command{tar}
+to print an @samp{ls -l} type listing of the files in the archive.
+The following examples both extract members with long list output:
+
+@smallexample
+$ @kbd{tar --extract --file=archive.tar --verbose --verbose}
+$ @kbd{tar xvvf archive.tar}
+@end smallexample
+
+Verbose output appears on the standard output except when an archive is
+being written to the standard output, as with @samp{tar --create
+--file=- --verbose} (@samp{tar cvf -}, or even @samp{tar cv}---if the
+installer let standard output be the default archive). In that case
+@command{tar} writes verbose output to the standard error stream.
+
+If @option{--index-file=@var{file}} is specified, @command{tar} sends
+verbose output to @var{file} rather than to standard output or standard
+error.
+
+@anchor{totals}
+@cindex Obtaining total status information
+@opindex totals
+The @option{--totals} option causes @command{tar} to print on the
+standard error the total amount of bytes transferred when processing
+an archive. When creating or appending to an archive, this option
+prints the number of bytes written to the archive and the average
+speed at which they have been written, e.g.:
+
+@smallexample
+@group
+$ @kbd{tar -c -f archive.tar --totals /home}
+Total bytes written: 7924664320 (7.4GiB, 85MiB/s)
+@end group
+@end smallexample
+
+When reading an archive, this option displays the number of bytes
+read:
+
+@smallexample
+@group
+$ @kbd{tar -x -f archive.tar --totals}
+Total bytes read: 7924664320 (7.4GiB, 95MiB/s)
+@end group
+@end smallexample
+
+Finally, when deleting from an archive, the @option{--totals} option
+displays both numbers plus number of bytes removed from the archive:
+
+@smallexample
+@group
+$ @kbd{tar --delete -f foo.tar --totals --wildcards '*~'}
+Total bytes read: 9543680 (9.2MiB, 201MiB/s)
+Total bytes written: 3829760 (3.7MiB, 81MiB/s)
+Total bytes deleted: 1474048
+@end group
+@end smallexample
+
+You can also obtain this information on request. When
+@option{--totals} is used with an argument, this argument is
+interpreted as a symbolic name of a signal, upon delivery of which the
+statistics is to be printed:
+
+@table @option
+@item --totals=@var{signo}
+Print statistics upon delivery of signal @var{signo}. Valid arguments
+are: @code{SIGHUP}, @code{SIGQUIT}, @code{SIGINT}, @code{SIGUSR1} and
+@code{SIGUSR2}. Shortened names without @samp{SIG} prefix are also
+accepted.
+@end table
+
+Both forms of @option{--totals} option can be used simultaneously.
+Thus, @kbd{tar -x --totals --totals=USR1} instructs @command{tar} to
+extract all members from its default archive and print statistics
+after finishing the extraction, as well as when receiving signal
+@code{SIGUSR1}.
+
+@anchor{Progress information}
+@cindex Progress information
+The @option{--checkpoint} option prints an occasional message
+as @command{tar} reads or writes the archive. It is designed for
+those who don't need the more detailed (and voluminous) output of
+@option{--block-number} (@option{-R}), but do want visual confirmation
+that @command{tar} is actually making forward progress. By default it
+prints a message each 10 records read or written. This can be changed
+by giving it a numeric argument after an equal sign:
+
+@smallexample
+$ @kbd{tar -c --checkpoint=1000} /var
+tar: Write checkpoint 1000
+tar: Write checkpoint 2000
+tar: Write checkpoint 3000
+@end smallexample
+
+This example shows the default checkpoint message used by
+@command{tar}. If you place a dot immediately after the equal
+sign, it will print a @samp{.} at each checkpoint@footnote{This is
+actually a shortcut for @option{--checkpoint=@var{n}
+--checkpoint-action=dot}. @xref{checkpoints, dot}.}. For example:
+
+@smallexample
+$ @kbd{tar -c --checkpoint=.1000} /var
+...
+@end smallexample
+
+The @option{--checkpoint} option provides a flexible mechanism for
+executing arbitrary actions upon hitting checkpoints, see the next
+section (@pxref{checkpoints}), for more information on it.
+
+@opindex show-omitted-dirs
+@anchor{show-omitted-dirs}
+The @option{--show-omitted-dirs} option, when reading an archive---with
+@option{--list} or @option{--extract}, 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
+@option{--exclude=@var{pattern}} option, or some other reason.
+
+@opindex block-number
+@cindex Block number where error occurred
+@anchor{block-number}
+If @option{--block-number} (@option{-R}) is used, @command{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
+@option{--block-number} (@option{-R}) is used. Note that @GNUTAR{}
+drains the archive before exiting when reading the
+archive from a pipe.
+
+@cindex Error message, block number of
+This option is especially useful when reading damaged archives, since
+it helps pinpoint the damaged sections. It can also be used with
+@option{--list} (@option{-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). @xref{backup}.
+
+@node checkpoints
+@section Checkpoints
+@cindex checkpoints, defined
+@opindex checkpoint
+@opindex checkpoint-action
+
+A @dfn{checkpoint} is a moment of time before writing @var{n}th record to
+the archive (a @dfn{write checkpoint}), or before reading @var{n}th record
+from the archive (a @dfn{read checkpoint}). Checkpoints allow to
+periodically execute arbitrary actions.
+
+The checkpoint facility is enabled using the following option:
+
+@table @option
+@xopindex{checkpoint, defined}
+@item --checkpoint[=@var{n}]
+Schedule checkpoints before writing or reading each @var{n}th record.
+The default value for @var{n} is 10.
+@end table
+
+A list of arbitrary @dfn{actions} can be executed at each checkpoint.
+These actions include: pausing, displaying textual messages, and
+executing arbitrary external programs. Actions are defined using
+the @option{--checkpoint-action} option.
+
+@table @option
+@xopindex{checkpoint-action, defined}
+@item --checkpoint-action=@var{action}
+Execute an @var{action} at each checkpoint.
+@end table
+
+@cindex @code{echo}, checkpoint action
+The simplest value of @var{action} is @samp{echo}. It instructs
+@command{tar} to display the default message on the standard error
+stream upon arriving at each checkpoint. The default message is (in
+@acronym{POSIX} locale) @samp{Write checkpoint @var{n}}, for write
+checkpoints, and @samp{Read checkpoint @var{n}}, for read checkpoints.
+Here, @var{n} represents ordinal number of the checkpoint.
+
+In another locales, translated versions of this message are used.
+
+This is the default action, so running:
+
+@smallexample
+$ @kbd{tar -c --checkpoint=1000 --checkpoint-action=echo} /var
+@end smallexample
+
+@noindent
+is equivalent to:
+
+@smallexample
+$ @kbd{tar -c --checkpoint=1000} /var
+@end smallexample
+
+The @samp{echo} action also allows to supply a customized message.
+You do so by placing an equals sign and the message right after it,
+e.g.:
+
+@smallexample
+--checkpoint-action="echo=Hit %s checkpoint #%u"
+@end smallexample
+
+The @samp{%s} and @samp{%u} in the above example are
+@dfn{format specifiers}. The @samp{%s} specifier is replaced with
+the @dfn{type} of the checkpoint: @samp{write} or
+@samp{read} (or a corresponding translated version in locales other
+than @acronym{POSIX}). The @samp{%u} specifier is replaced with
+the ordinal number of the checkpoint. Thus, the above example could
+produce the following output when used with the @option{--create}
+option:
+
+@smallexample
+tar: Hit write checkpoint #10
+tar: Hit write checkpoint #20
+tar: Hit write checkpoint #30
+@end smallexample
+
+The complete list of available format specifiers follows. Some of
+them can take optional arguments. These arguments, if given, are
+supplied in curly braces between the percent sign and the specifier
+letter.
+
+@table @samp
+@item %s
+Print type of the checkpoint (@samp{write} or @samp{read}).
+
+@item %u
+Print number of the checkpoint.
+
+@item %@{r,w,d@}T
+Print number of bytes transferred so far and approximate transfer
+speed. Optional arguments supply prefixes to be used before number
+of bytes read, written and deleted, correspondingly. If absent,
+they default to @samp{R}. @samp{W}, @samp{D}. Any or all of them can
+be omitted, so, that e.g. @samp{%@{@}T} means to print corresponding
+statistics without any prefixes. Any surplus arguments, if present,
+are silently ignored.
+
+@example
+$ @kbd{tar --delete -f f.tar --checkpoint-action=echo="#%u: %T" main.c}
+tar: #1: R: 0 (0B, 0B/s),W: 0 (0B, 0B/s),D: 0
+tar: #2: R: 10240 (10KiB, 19MiB/s),W: 0 (0B, 0B/s),D: 10240
+@end example
+
+@noindent
+See also the @samp{totals} action, described below.
+
+@item %@{@var{fmt}@}t
+Output current local time using @var{fmt} as format for @command{strftime}
+(@pxref{strftime, strftime,,strftime(3), strftime(3) man page}). The
+@samp{@{@var{fmt}@}} part is optional. If not present, the default
+format is @samp{%c}, i.e. the preferred date and time representation
+for the current locale.
+
+@item %@{@var{n}@}*
+Pad output with spaces to the @var{n}th column. If the
+@samp{@{@var{n}@}} part is omitted, the current screen width
+is assumed.
+
+@item %c
+This is a shortcut for @samp{%@{%Y-%m-%d %H:%M:%S@}t: %ds, %@{read,wrote@}T%*\r},
+intended mainly for use with @samp{ttyout} action (see below).
+@end table
+
+Aside from format expansion, the message string is subject to
+@dfn{unquoting}, during which the backslash @dfn{escape sequences} are
+replaced with their corresponding @acronym{ASCII} characters
+(@pxref{escape sequences}). E.g. the following action will produce an
+audible bell and the message described above at each checkpoint:
+
+@smallexample
+--checkpoint-action='echo=\aHit %s checkpoint #%u'
+@end smallexample
+
+@cindex @code{bell}, checkpoint action
+There is also a special action which produces an audible signal:
+@samp{bell}. It is not equivalent to @samp{echo='\a'}, because
+@samp{bell} sends the bell directly to the console (@file{/dev/tty}),
+whereas @samp{echo='\a'} sends it to the standard error.
+
+@cindex @code{ttyout}, checkpoint action
+The @samp{ttyout=@var{string}} action outputs @var{string} to
+@file{/dev/tty}, so it can be used even if the standard output is
+redirected elsewhere. The @var{string} is subject to the same
+modifications as with @samp{echo} action. In contrast to the latter,
+@samp{ttyout} does not prepend @command{tar} executable name to the
+string, nor does it output a newline after it. For example, the
+following action will print the checkpoint message at the same screen
+line, overwriting any previous message:
+
+@smallexample
+--checkpoint-action="ttyout=Hit %s checkpoint #%u%*\r"
+@end smallexample
+
+@noindent
+Notice the use of @samp{%*} specifier to clear out any eventual
+remains of the prior output line. As as more complex example,
+consider this:
+
+@smallexample
+--checkpoint-action=ttyout='%@{%Y-%m-%d %H:%M:%S@}t (%d sec): #%u, %T%*\r'
+@end smallexample
+
+@noindent
+This prints the current local time, number of seconds expired since
+tar was started, the checkpoint ordinal number, transferred bytes and
+average computed I/O speed.
+
+@cindex @code{dot}, checkpoint action
+Another available checkpoint action is @samp{dot} (or @samp{.}). It
+instructs @command{tar} to print a single dot on the standard listing
+stream, e.g.:
+
+@smallexample
+$ @kbd{tar -c --checkpoint=1000 --checkpoint-action=dot} /var
+...
+@end smallexample
+
+For compatibility with previous @GNUTAR{} versions, this action can
+be abbreviated by placing a dot in front of the checkpoint frequency,
+as shown in the previous section.
+
+@cindex @code{totals}, checkpoint action
+The @samp{totals} action prints the total number of bytes transferred
+so far. The format of the data is the same as for the
+@option{--totals} option (@pxref{totals}). See also @samp{%T} format
+specifier of the @samp{echo} or @samp{ttyout} action.
+
+@cindex @code{sleep}, checkpoint action
+Yet another action, @samp{sleep}, pauses @command{tar} for a specified
+amount of seconds. The following example will stop for 30 seconds at each
+checkpoint:
+
+@smallexample
+$ @kbd{tar -c --checkpoint=1000 --checkpoint-action=sleep=30}
+@end smallexample
+
+@anchor{checkpoint exec}
+@cindex @code{exec}, checkpoint action
+Finally, the @code{exec} action executes a given external command.
+For example:
+
+@smallexample
+$ @kbd{tar -c --checkpoint=1000 --checkpoint-action=exec=/sbin/cpoint}
+@end smallexample
+
+The supplied command can be any valid command invocation, with or
+without additional command line arguments. If it does contain
+arguments, don't forget to quote it to prevent it from being split by
+the shell. @xref{external, Running External Commands}, for more detail.
+
+The command gets a copy of @command{tar}'s environment plus the
+following variables:
+
+@table @env
+@vrindex TAR_VERSION, checkpoint script environment
+@item TAR_VERSION
+@GNUTAR{} version number.
+
+@vrindex TAR_ARCHIVE, checkpoint script environment
+@item TAR_ARCHIVE
+The name of the archive @command{tar} is processing.
+
+@vrindex TAR_BLOCKING_FACTOR, checkpoint script environment
+@item TAR_BLOCKING_FACTOR
+Current blocking factor (@pxref{Blocking}).
+
+@vrindex TAR_CHECKPOINT, checkpoint script environment
+@item TAR_CHECKPOINT
+Number of the checkpoint.
+
+@vrindex TAR_SUBCOMMAND, checkpoint script environment
+@item TAR_SUBCOMMAND
+A short option describing the operation @command{tar} is executing.
+@xref{Operations}, for a complete list of subcommand options.
+
+@vrindex TAR_FORMAT, checkpoint script environment
+@item TAR_FORMAT
+Format of the archive being processed. @xref{Formats}, for a complete
+list of archive format names.
+@end table
+
+These environment variables can also be passed as arguments to the
+command, provided that they are properly escaped, for example:
+
+@smallexample
+@kbd{tar -c -f arc.tar \
+ --checkpoint-action='exec=/sbin/cpoint $TAR_CHECKPOINT'}
+@end smallexample
+
+@noindent
+Notice single quotes to prevent variable names from being expanded by
+the shell when invoking @command{tar}.
+
+Any number of actions can be defined, by supplying several
+@option{--checkpoint-action} options in the command line. For
+example, the command below displays two messages, pauses
+execution for 30 seconds and executes the @file{/sbin/cpoint} script:
+
+@example
+@group
+$ @kbd{tar -c -f arc.tar \
+ --checkpoint-action='\aecho=Hit %s checkpoint #%u' \
+ --checkpoint-action='echo=Sleeping for 30 seconds' \
+ --checkpoint-action='sleep=30' \
+ --checkpoint-action='exec=/sbin/cpoint'}
+@end group
+@end example
+
+This example also illustrates the fact that
+@option{--checkpoint-action} can be used without
+@option{--checkpoint}. In this case, the default checkpoint frequency
+(at each 10th record) is assumed.
+
+@node warnings
+@section Controlling Warning Messages
+
+Sometimes, while performing the requested task, @GNUTAR{} notices
+some conditions that are not exactly errors, but which the user
+should be aware of. When this happens, @command{tar} issues a
+@dfn{warning message} describing the condition. Warning messages
+are output to the standard error and they do not affect the exit
+code of @command{tar} command.
+
+@xopindex{warning, explained}
+@GNUTAR{} allows the user to suppress some or all of its warning
+messages:
+
+@table @option
+@item --warning=@var{keyword}
+Control display of the warning messages identified by @var{keyword}.
+If @var{keyword} starts with the prefix @samp{no-}, such messages are
+suppressed. Otherwise, they are enabled.
+
+Multiple @option{--warning} messages accumulate.
+
+The tables below list allowed values for @var{keyword} along with the
+warning messages they control.
+@end table
+
+@subheading Keywords controlling @command{tar} operation
+@table @asis
+@kwindex all
+@item all
+Enable all warning messages. This is the default.
+@kwindex none
+@item none
+Disable all warning messages.
+@kwindex filename-with-nuls
+@cindex @samp{file name read contains nul character}, warning message
+@item filename-with-nuls
+@samp{%s: file name read contains nul character}
+@kwindex alone-zero-block
+@cindex @samp{A lone zero block at}, warning message
+@item alone-zero-block
+@samp{A lone zero block at %s}
+@end table
+
+@subheading Keywords applicable for @command{tar --create}
+@table @asis
+@kwindex cachedir
+@cindex @samp{contains a cache directory tag}, warning message
+@item cachedir
+@samp{%s: contains a cache directory tag %s; %s}
+@kwindex file-shrank
+@cindex @samp{File shrank by %s bytes}, warning message
+@item file-shrank
+@samp{%s: File shrank by %s bytes; padding with zeros}
+@kwindex xdev
+@cindex @samp{file is on a different filesystem}, warning message
+@item xdev
+@samp{%s: file is on a different filesystem; not dumped}
+@kwindex file-ignored
+@cindex @samp{Unknown file type; file ignored}, warning message
+@cindex @samp{socket ignored}, warning message
+@cindex @samp{door ignored}, warning message
+@item file-ignored
+@samp{%s: Unknown file type; file ignored}
+@*@samp{%s: socket ignored}
+@*@samp{%s: door ignored}
+@kwindex file-unchanged
+@cindex @samp{file is unchanged; not dumped}, warning message
+@item file-unchanged
+@samp{%s: file is unchanged; not dumped}
+@kwindex ignore-archive
+@cindex @samp{file is the archive; not dumped}, warning message
+@kwindex ignore-archive
+@cindex @samp{file is the archive; not dumped}, warning message
+@item ignore-archive
+@samp{%s: file is the archive; not dumped}
+@kwindex file-removed
+@cindex @samp{File removed before we read it}, warning message
+@item file-removed
+@samp{%s: File removed before we read it}
+@kwindex file-changed
+@cindex @samp{file changed as we read it}, warning message
+@item file-changed
+@samp{%s: file changed as we read it}
+@end table
+
+@subheading Keywords applicable for @command{tar --extract}
+@table @asis
+@kwindex existing-file
+@cindex @samp{%s: skipping existing file}, warning message
+@item existing-file
+@samp{%s: skipping existing file}
+@kwindex timestamp
+@cindex @samp{implausibly old time stamp %s}, warning message
+@cindex @samp{time stamp %s is %s s in the future}, warning message
+@item timestamp
+@samp{%s: implausibly old time stamp %s}
+@*@samp{%s: time stamp %s is %s s in the future}
+@kwindex contiguous-cast
+@cindex @samp{Extracting contiguous files as regular files}, warning message
+@item contiguous-cast
+@samp{Extracting contiguous files as regular files}
+@kwindex symlink-cast
+@cindex @samp{Attempting extraction of symbolic links as hard links}, warning message
+@item symlink-cast
+@samp{Attempting extraction of symbolic links as hard links}
+@kwindex unknown-cast
+@cindex @samp{Unknown file type '%c', extracted as normal file}, warning message
+@item unknown-cast
+@samp{%s: Unknown file type '%c', extracted as normal file}
+@kwindex ignore-newer
+@cindex @samp{Current %s is newer or same age}, warning message
+@item ignore-newer
+@samp{Current %s is newer or same age}
+@kwindex unknown-keyword
+@cindex @samp{Ignoring unknown extended header keyword '%s'}, warning message
+@item unknown-keyword
+@samp{Ignoring unknown extended header keyword '%s'}
+@kwindex decompress-program
+@item decompress-program
+Controls verbose description of failures occurring when trying to run
+alternative decompressor programs (@pxref{alternative decompression
+programs}). This warning is disabled by default (unless
+@option{--verbose} is used). A common example of what you can get
+when using this warning is:
+
+@smallexample
+$ @kbd{tar --warning=decompress-program -x -f archive.Z}
+tar (child): cannot run compress: No such file or directory
+tar (child): trying gzip
+@end smallexample
+
+This means that @command{tar} first tried to decompress
+@file{archive.Z} using @command{compress}, and, when that
+failed, switched to @command{gzip}.
+@kwindex record-size
+@cindex @samp{Record size = %lu blocks}, warning message
+@item record-size
+@samp{Record size = %lu blocks}
+@end table
+
+@subheading Keywords controlling incremental extraction:
+@table @asis
+@kwindex rename-directory
+@cindex @samp{%s: Directory has been renamed from %s}, warning message
+@cindex @samp{%s: Directory has been renamed}, warning message
+@item rename-directory
+@samp{%s: Directory has been renamed from %s}
+@*@samp{%s: Directory has been renamed}
+@kwindex new-directory
+@cindex @samp{%s: Directory is new}, warning message
+@item new-directory
+@samp{%s: Directory is new}
+@kwindex xdev
+@cindex @samp{%s: directory is on a different device: not purging}, warning message
+@item xdev
+@samp{%s: directory is on a different device: not purging}
+@kwindex bad-dumpdir
+@cindex @samp{Malformed dumpdir: 'X' never used}, warning message
+@item bad-dumpdir
+@samp{Malformed dumpdir: 'X' never used}
+@end table
+
+@node interactive
+@section Asking for Confirmation During Operations
+@cindex Interactive operation
+
+Typically, @command{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 (@pxref{Choosing}), or by performing
+an operation interactively, using the @option{--interactive} (@option{-w}) option.
+@command{tar} also accepts @option{--confirmation} for this option.
+
+@opindex interactive
+When the @option{--interactive} (@option{-w}) option is specified, before
+reading, writing, or deleting files, @command{tar} first prints a message
+for each such file, telling what operation 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 @samp{y}. If your input line begins with anything other
+than @samp{y}, @command{tar} skips that file.
+
+If @command{tar} is reading the archive from the standard input,
+@command{tar} opens the file @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
+@code{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.
+
+@node external
+@section Running External Commands
+
+Certain @GNUTAR{} operations imply running external commands that you
+supply on the command line. One of such operations is checkpointing,
+described above (@pxref{checkpoint exec}). Another example of this
+feature is the @option{-I} option, which allows you to supply the
+program to use for compressing or decompressing the archive
+(@pxref{use-compress-program}).
+
+Whenever such operation is requested, @command{tar} first splits the
+supplied command into words much like the shell does. It then treats
+the first word as the name of the program or the shell script to execute
+and the rest of words as its command line arguments. The program,
+unless given as an absolute file name, is searched in the shell's
+@env{PATH}.
+
+Any additional information is normally supplied to external commands
+in environment variables, specific to each particular operation. For
+example, the @option{--checkpoint-action=exec} option, defines the
+@env{TAR_ARCHIVE} variable to the name of the archive being worked
+upon. You can, should the need be, use these variables in the
+command line of the external command. For example:
+
+@smallexample
+$ @kbd{tar -x -f archive.tar \
+ --checkpoint-action=exec='printf "%04d in %32s\r" $TAR_CHECKPOINT $TAR_ARCHIVE'}
+@end smallexample
+
+@noindent
+This command prints for each checkpoint its number and the name of the
+archive, using the same output line on the screen.
+
+Notice the use of single quotes to prevent variable names from being
+expanded by the shell when invoking @command{tar}.
+
+@node operations
+@chapter @GNUTAR{} Operations
+
+@menu
+* Basic tar::
+* Advanced tar::
+* create options::
+* extract options::
+* backup::
+* Applications::
+* looking ahead::
+@end menu
+
+@node Basic tar
+@section Basic @GNUTAR{} Operations
+
+The basic @command{tar} operations, @option{--create} (@option{-c}),
+@option{--list} (@option{-t}) and @option{--extract} (@option{--get},
+@option{-x}), are currently presented and described in the tutorial
+chapter of this manual. This section provides some complementary notes
+for these operations.
+
+@table @option
+@xopindex{create, complementary notes}
+@item --create
+@itemx -c
+
+Creating an empty archive would have some kind of elegance. One can
+initialize an empty archive and later use @option{--append}
+(@option{-r}) for adding all members. Some applications would not
+welcome making an exception in the way of adding the first archive
+member. On the other hand, many people reported that it is
+dangerously too easy for @command{tar} to destroy a magnetic tape with
+an empty archive@footnote{This is well described in @cite{Unix-haters
+Handbook}, by Simson Garfinkel, Daniel Weise & Steven Strassmann, IDG
+Books, ISBN 1-56884-203-1.}. The two most common errors are:
+
+@enumerate
+@item
+Mistakingly using @code{create} instead of @code{extract}, when the
+intent was to extract the full contents of an archive. This error
+is likely: keys @kbd{c} and @kbd{x} are right next to each other on
+the QWERTY keyboard. Instead of being unpacked, the archive then
+gets wholly destroyed. When users speak about @dfn{exploding} an
+archive, they usually mean something else :-).
+
+@item
+Forgetting the argument to @code{file}, when the intent was to create
+an archive with a single file in it. This error is likely because a
+tired user can easily add the @kbd{f} key to the cluster of option
+letters, by the mere force of habit, without realizing the full
+consequence of doing so. The usual consequence is that the single
+file, which was meant to be saved, is rather destroyed.
+@end enumerate
+
+So, recognizing the likelihood and the catastrophic nature of these
+errors, @GNUTAR{} now takes some distance from elegance, and
+cowardly refuses to create an archive when @option{--create} option is
+given, there are no arguments besides options, and
+@option{--files-from} (@option{-T}) option is @emph{not} used. To get
+around the cautiousness of @GNUTAR{} and nevertheless create an
+archive with nothing in it, one may still use, as the value for the
+@option{--files-from} option, a file with no names in it, as shown in
+the following commands:
+
+@smallexample
+@kbd{tar --create --file=empty-archive.tar --files-from=/dev/null}
+@kbd{tar -cf empty-archive.tar -T /dev/null}
+@end smallexample
+
+@xopindex{extract, complementary notes}
+@item --extract
+@itemx --get
+@itemx -x
+
+A socket is stored, within a @GNUTAR{} archive, as a pipe.
+
+@item @option{--list} (@option{-t})
+
+@GNUTAR{} now shows dates as @samp{1996-08-30},
+while it used to show them as @samp{Aug 30 1996}. Preferably,
+people should get used to ISO 8601 dates. Local American dates should
+be made available again with full date localization support, once
+ready. In the meantime, programs not being localizable for dates
+should prefer international dates, that's really the way to go.
+
+Look up @url{http://www.cl.cam.ac.uk/@/~mgk25/@/iso-time.html} if you
+are curious, it contains a detailed explanation of the ISO 8601 standard.
+
+@end table
+
+@node Advanced tar
+@section Advanced @GNUTAR{} Operations
+
+Now that you have learned the basics of using @GNUTAR{}, you may want
+to learn about further ways in which @command{tar} can help you.
+
+This chapter presents five, more advanced operations which you probably
+won't use on a daily basis, but which serve more specialized functions.
+We also explain the different styles of options and why you might want
+to use one or another, or a combination of them in your @command{tar}
+commands. Additionally, this chapter includes options which allow you to
+define the output from @command{tar} more carefully, and provide help and
+error correction in special circumstances.
+
+@FIXME{check this after the chapter is actually revised to make sure
+it still introduces the info in the chapter correctly : ).}
+
+@menu
+* Operations::
+* append::
+* update::
+* concatenate::
+* delete::
+* compare::
+@end menu
+
+@node Operations
+@subsection The Five Advanced @command{tar} Operations
+
+@cindex basic operations
+In the last chapter, you learned about the first three operations to
+@command{tar}. This chapter presents the remaining five operations to
+@command{tar}: @option{--append}, @option{--update}, @option{--concatenate},
+@option{--delete}, and @option{--compare}.
+
+You are not likely to use these operations as frequently as those
+covered in the last chapter; however, since they perform specialized
+functions, they are quite useful when you do need to use them. We
+will give examples using the same directory and files that you created
+in the last chapter. As you may recall, the directory is called
+@file{practice}, the files are @samp{jazz}, @samp{blues}, @samp{folk},
+and the two archive files you created are
+@samp{collection.tar} and @samp{music.tar}.
+
+We will also use the archive files @samp{afiles.tar} and
+@samp{bfiles.tar}. The archive @samp{afiles.tar} contains the members @samp{apple},
+@samp{angst}, and @samp{aspic}; @samp{bfiles.tar} contains the members
+@samp{./birds}, @samp{baboon}, and @samp{./box}.
+
+Unless we state otherwise, all practicing you do and examples you follow
+in this chapter will take place in the @file{practice} directory that
+you created in the previous chapter; see @ref{prepare for examples}.
+(Below in this section, we will remind you of the state of the examples
+where the last chapter left them.)
+
+The five operations that we will cover in this chapter are:
+
+@table @option
+@item --append
+@itemx -r
+Add new entries to an archive that already exists.
+@item --update
+@itemx -u
+Add more recent copies of archive members to the end of an archive, if
+they exist.
+@item --concatenate
+@itemx --catenate
+@itemx -A
+Add one or more pre-existing archives to the end of another archive.
+@item --delete
+Delete items from an archive (does not work on tapes).
+@item --compare
+@itemx --diff
+@itemx -d
+Compare archive members to their counterparts in the file system.
+@end table
+
+@node append
+@subsection How to Add Files to Existing Archives: @option{--append}
+
+@cindex appending files to existing archive
+@opindex append
+If you want to add files to an existing archive, you don't need to
+create a new archive; you can use @option{--append} (@option{-r}).
+The archive must already exist in order to use @option{--append}. (A
+related operation is the @option{--update} operation; you can use this
+to add newer versions of archive members to an existing archive. To learn how to
+do this with @option{--update}, @pxref{update}.)
+
+If you use @option{--append} to add a file that has the same name as an
+archive member to an archive containing that archive member, then the
+old member is not deleted. What does happen, however, is somewhat
+complex. @command{tar} @emph{allows} you to have infinite number of files
+with the same name. Some operations treat these same-named members no
+differently than any other set of archive members: for example, if you
+view an archive with @option{--list} (@option{-t}), you will see all
+of those members listed, with their data modification times, owners, etc.
+
+Other operations don't deal with these members as perfectly as you might
+prefer; if you were to use @option{--extract} to extract the archive,
+only the most recently added copy of a member with the same name as
+other members would end up in the working directory. This is because
+@option{--extract} extracts an archive in the order the members appeared
+in the archive; the most recently archived members will be extracted
+last. Additionally, an extracted member will @emph{replace} a file of
+the same name which existed in the directory already, and @command{tar}
+will not prompt you about this@footnote{Unless you give it
+@option{--keep-old-files} (or @option{--skip-old-files}) option, or
+the disk copy is newer than the one in the archive and you invoke
+@command{tar} with @option{--keep-newer-files} option.}. Thus, only
+the most recently archived member will end up being extracted, as it
+will replace the one extracted before it, and so on.
+
+@cindex extracting @var{n}th copy of the file
+@xopindex{occurrence, described}
+There exists a special option that allows you to get around this
+behavior and extract (or list) only a particular copy of the file.
+This is @option{--occurrence} option. If you run @command{tar} with
+this option, it will extract only the first copy of the file. You
+may also give this option an argument specifying the number of
+copy to be extracted. Thus, for example if the archive
+@file{archive.tar} contained three copies of file @file{myfile}, then
+the command
+
+@smallexample
+tar --extract --file archive.tar --occurrence=2 myfile
+@end smallexample
+
+@noindent
+would extract only the second copy. @xref{Option
+Summary,---occurrence}, for the description of @option{--occurrence}
+option.
+
+@FIXME{ hag -- you might want to incorporate some of the above into the
+MMwtSN node; not sure. i didn't know how to make it simpler...
+
+There are a few ways to get around this. Xref to Multiple Members
+with the Same Name, maybe.}
+
+@cindex Members, replacing with other members
+@cindex Replacing members with other members
+@xopindex{delete, using before --append}
+If you want to replace an archive member, use @option{--delete} to
+delete the member you want to remove from the archive, and then use
+@option{--append} to add the member you want to be in the archive. Note
+that you can not change the order of the archive; the most recently
+added member will still appear last. In this sense, you cannot truly
+``replace'' one member with another. (Replacing one member with another
+will not work on certain types of media, such as tapes; see @ref{delete}
+and @ref{Media}, for more information.)
+
+@menu
+* appending files:: Appending Files to an Archive
+* multiple::
+@end menu
+
+@node appending files
+@subsubsection Appending Files to an Archive
+@cindex Adding files to an Archive
+@cindex Appending files to an Archive
+@cindex Archives, Appending files to
+@opindex append
+
+The simplest way to add a file to an already existing archive is the
+@option{--append} (@option{-r}) operation, which writes specified
+files into the archive whether or not they are already among the
+archived files.
+
+When you use @option{--append}, you @emph{must} specify file name
+arguments, as there is no default. If you specify a file that already
+exists in the archive, another copy of the file will be added to the
+end of the archive. As with other operations, the member names of the
+newly added files will be exactly the same as their names given on the
+command line. The @option{--verbose} (@option{-v}) option will print
+out the names of the files as they are written into the archive.
+
+@option{--append} cannot be performed on some tape drives, unfortunately,
+due to deficiencies in the formats those tape drives use. The archive
+must be a valid @command{tar} archive, or else the results of using this
+operation will be unpredictable. @xref{Media}.
+
+To demonstrate using @option{--append} to add a file to an archive,
+create a file called @file{rock} in the @file{practice} directory.
+Make sure you are in the @file{practice} directory. Then, run the
+following @command{tar} command to add @file{rock} to
+@file{collection.tar}:
+
+@smallexample
+$ @kbd{tar --append --file=collection.tar rock}
+@end smallexample
+
+@noindent
+If you now use the @option{--list} (@option{-t}) operation, you will see that
+@file{rock} has been added to the archive:
+
+@smallexample
+$ @kbd{tar --list --file=collection.tar}
+-rw-r--r-- me/user 28 1996-10-18 16:31 jazz
+-rw-r--r-- me/user 21 1996-09-23 16:44 blues
+-rw-r--r-- me/user 20 1996-09-23 16:44 folk
+-rw-r--r-- me/user 20 1996-09-23 16:44 rock
+@end smallexample
+
+@node multiple
+@subsubsection Multiple Members with the Same Name
+@cindex members, multiple
+@cindex multiple members
+
+You can use @option{--append} (@option{-r}) to add copies of files
+which have been updated since the archive was created. (However, we
+do not recommend doing this since there is another @command{tar}
+option called @option{--update}; @xref{update}, for more information.
+We describe this use of @option{--append} here for the sake of
+completeness.) When you extract the archive, the older version will
+be effectively lost. This works because files are extracted from an
+archive in the order in which they were archived. Thus, when the
+archive is extracted, a file archived later in time will replace a
+file of the same name which was archived earlier, even though the
+older version of the file will remain in the archive unless you delete
+all versions of the file.
+
+Supposing you change the file @file{blues} and then append the changed
+version to @file{collection.tar}. As you saw above, the original
+@file{blues} is in the archive @file{collection.tar}. If you change the
+file and append the new version of the file to the archive, there will
+be two copies in the archive. When you extract the archive, the older
+version of the file will be extracted first, and then replaced by the
+newer version when it is extracted.
+
+You can append the new, changed copy of the file @file{blues} to the
+archive in this way:
+
+@smallexample
+$ @kbd{tar --append --verbose --file=collection.tar blues}
+blues
+@end smallexample
+
+@noindent
+Because you specified the @option{--verbose} option, @command{tar} has
+printed the name of the file being appended as it was acted on. Now
+list the contents of the archive:
+
+@smallexample
+$ @kbd{tar --list --verbose --file=collection.tar}
+-rw-r--r-- me/user 28 1996-10-18 16:31 jazz
+-rw-r--r-- me/user 21 1996-09-23 16:44 blues
+-rw-r--r-- me/user 20 1996-09-23 16:44 folk
+-rw-r--r-- me/user 20 1996-09-23 16:44 rock
+-rw-r--r-- me/user 58 1996-10-24 18:30 blues
+@end smallexample
+
+@noindent
+The newest version of @file{blues} is now at the end of the archive
+(note the different creation dates and file sizes). If you extract
+the archive, the older version of the file @file{blues} will be
+replaced by the newer version. You can confirm this by extracting
+the archive and running @samp{ls} on the directory.
+
+If you wish to extract the first occurrence of the file @file{blues}
+from the archive, use @option{--occurrence} option, as shown in
+the following example:
+
+@smallexample
+$ @kbd{tar --extract -vv --occurrence --file=collection.tar blues}
+-rw-r--r-- me/user 21 1996-09-23 16:44 blues
+@end smallexample
+
+@xref{Writing}, for more information on @option{--extract} and
+see @ref{Option Summary, --occurrence}, for a description of
+@option{--occurrence} option.
+
+@node update
+@subsection Updating an Archive
+@cindex Updating an archive
+@opindex update
+
+In the previous section, you learned how to use @option{--append} to
+add a file to an existing archive. A related operation is
+@option{--update} (@option{-u}). The @option{--update} operation
+updates a @command{tar} archive by comparing the date of the specified
+archive members against the date of the file with the same name. If
+the file has been modified more recently than the archive member, then
+the newer version of the file is added to the archive (as with
+@option{--append}).
+
+Unfortunately, you cannot use @option{--update} with magnetic tape drives.
+The operation will fail.
+
+@FIXME{other examples of media on which --update will fail? need to ask
+charles and/or mib/thomas/dave shevett..}
+
+Both @option{--update} and @option{--append} work by adding to the end
+of the archive. When you extract a file from the archive, only the
+version stored last will wind up in the file system, unless you use
+the @option{--backup} option. @xref{multiple}, for a detailed discussion.
+
+@menu
+* how to update::
+@end menu
+
+@node how to update
+@subsubsection How to Update an Archive Using @option{--update}
+@opindex update
+
+You must use file name arguments with the @option{--update}
+(@option{-u}) operation. If you don't specify any files,
+@command{tar} won't act on any files and won't tell you that it didn't
+do anything (which may end up confusing you).
+
+@c note: the above parenthetical added because in fact, this
+@c behavior just confused the author. :-)
+
+To see the @option{--update} option at work, create a new file,
+@file{classical}, in your practice directory, and some extra text to the
+file @file{blues}, using any text editor. Then invoke @command{tar} with
+the @samp{update} operation and the @option{--verbose} (@option{-v})
+option specified, using the names of all the files in the @file{practice}
+directory as file name arguments:
+
+@smallexample
+$ @kbd{tar --update -v -f collection.tar blues folk rock classical}
+blues
+classical
+$
+@end smallexample
+
+@noindent
+Because we have specified verbose mode, @command{tar} prints out the names
+of the files it is working on, which in this case are the names of the
+files that needed to be updated. If you run @samp{tar --list} and look
+at the archive, you will see @file{blues} and @file{classical} at its
+end. There will be a total of two versions of the member @samp{blues};
+the one at the end will be newer and larger, since you added text before
+updating it.
+
+The reason @command{tar} does not overwrite the older file when updating
+it is because writing to the middle of a section of tape is a difficult
+process. Tapes are not designed to go backward. @xref{Media}, for more
+information about tapes.
+
+@option{--update} (@option{-u}) is not suitable for performing backups for two
+reasons: it does not change directory content entries, and it
+lengthens the archive every time it is used. The @GNUTAR{}
+options intended specifically for backups are more
+efficient. If you need to run backups, please consult @ref{Backups}.
+
+@node concatenate
+@subsection Combining Archives with @option{--concatenate}
+
+@cindex Adding archives to an archive
+@cindex Concatenating Archives
+@opindex concatenate
+@opindex catenate
+@c @cindex @option{-A} described
+Sometimes it may be convenient to add a second archive onto the end of
+an archive rather than adding individual files to the archive. To add
+one or more archives to the end of another archive, you should use the
+@option{--concatenate} (@option{--catenate}, @option{-A}) operation.
+
+To use @option{--concatenate}, give the first archive with
+@option{--file} option and name the rest of archives to be
+concatenated on the command line. The members, and their member
+names, will be copied verbatim from those archives to the first
+one@footnote{This can cause multiple members to have the same name. For
+information on how this affects reading the archive, see @ref{multiple}.}.
+The new, concatenated archive will be called by the same name as the
+one given with the @option{--file} option. As usual, if you omit
+@option{--file}, @command{tar} will use the value of the environment
+variable @env{TAPE}, or, if this has not been set, the default archive name.
+
+@FIXME{There is no way to specify a new name...}
+
+To demonstrate how @option{--concatenate} works, create two small archives
+called @file{bluesrock.tar} and @file{folkjazz.tar}, using the relevant
+files from @file{practice}:
+
+@smallexample
+$ @kbd{tar -cvf bluesrock.tar blues rock}
+blues
+rock
+$ @kbd{tar -cvf folkjazz.tar folk jazz}
+folk
+jazz
+@end smallexample
+
+@noindent
+If you like, You can run @samp{tar --list} to make sure the archives
+contain what they are supposed to:
+
+@smallexample
+$ @kbd{tar -tvf bluesrock.tar}
+-rw-r--r-- melissa/user 105 1997-01-21 19:42 blues
+-rw-r--r-- melissa/user 33 1997-01-20 15:34 rock
+$ @kbd{tar -tvf jazzfolk.tar}
+-rw-r--r-- melissa/user 20 1996-09-23 16:44 folk
+-rw-r--r-- melissa/user 65 1997-01-30 14:15 jazz
+@end smallexample
+
+We can concatenate these two archives with @command{tar}:
+
+@smallexample
+$ @kbd{cd ..}
+$ @kbd{tar --concatenate --file=bluesrock.tar jazzfolk.tar}
+@end smallexample
+
+If you now list the contents of the @file{bluesrock.tar}, you will see
+that now it also contains the archive members of @file{jazzfolk.tar}:
+
+@smallexample
+$ @kbd{tar --list --file=bluesrock.tar}
+blues
+rock
+folk
+jazz
+@end smallexample
+
+When you use @option{--concatenate}, the source and target archives must
+already exist and must have been created using compatible format
+parameters. Notice, that @command{tar} does not check whether the
+archives it concatenates have compatible formats, it does not
+even check if the files are really tar archives.
+
+Like @option{--append} (@option{-r}), this operation cannot be performed on some
+tape drives, due to deficiencies in the formats those tape drives use.
+
+@cindex @code{concatenate} vs @command{cat}
+@cindex @command{cat} vs @code{concatenate}
+It may seem more intuitive to you to want or try to use @command{cat} to
+concatenate two archives instead of using the @option{--concatenate}
+operation; after all, @command{cat} is the utility for combining files.
+
+However, @command{tar} archives incorporate an end-of-file marker which
+must be removed if the concatenated archives are to be read properly as
+one archive. @option{--concatenate} removes the end-of-archive marker
+from the target archive before each new archive is appended. If you use
+@command{cat} to combine the archives, the result will not be a valid
+@command{tar} format archive. If you need to retrieve files from an
+archive that was added to using the @command{cat} utility, use the
+@option{--ignore-zeros} (@option{-i}) option. @xref{Ignore Zeros}, for further
+information on dealing with archives improperly combined using the
+@command{cat} shell utility.
+
+@node delete
+@subsection Removing Archive Members Using @option{--delete}
+@cindex Deleting files from an archive
+@cindex Removing files from an archive
+
+@opindex delete
+You can remove members from an archive by using the @option{--delete}
+option. Specify the name of the archive with @option{--file}
+(@option{-f}) and then specify the names of the members to be deleted;
+if you list no member names, nothing will be deleted. The
+@option{--verbose} option will cause @command{tar} to print the names
+of the members as they are deleted. As with @option{--extract}, you
+must give the exact member names when using @samp{tar --delete}.
+@option{--delete} will remove all versions of the named file from the
+archive. The @option{--delete} operation can run very slowly.
+
+Unlike other operations, @option{--delete} has no short form.
+
+@cindex Tapes, using @option{--delete} and
+@cindex Deleting from tape archives
+This operation will rewrite the archive. You can only use
+@option{--delete} on an archive if the archive device allows you to
+write to any point on the media, such as a disk; because of this, it
+does not work on magnetic tapes. Do not try to delete an archive member
+from a magnetic tape; the action will not succeed, and you will be
+likely to scramble the archive and damage your tape. There is no safe
+way (except by completely re-writing the archive) to delete files from
+most kinds of magnetic tape. @xref{Media}.
+
+To delete all versions of the file @file{blues} from the archive
+@file{collection.tar} in the @file{practice} directory, make sure you
+are in that directory, and then,
+
+@smallexample
+$ @kbd{tar --list --file=collection.tar}
+blues
+folk
+jazz
+rock
+$ @kbd{tar --delete --file=collection.tar blues}
+$ @kbd{tar --list --file=collection.tar}
+folk
+jazz
+rock
+@end smallexample
+
+@FIXME{Check if the above listing is actually produced after running
+all the examples on collection.tar.}
+
+The @option{--delete} option has been reported to work properly when
+@command{tar} acts as a filter from @code{stdin} to @code{stdout}.
+
+@node compare
+@subsection Comparing Archive Members with the File System
+@cindex Verifying the currency of an archive
+
+@opindex compare
+The @option{--compare} (@option{-d}), or @option{--diff} operation compares
+specified archive members against files with the same names, and then
+reports differences in file size, mode, owner, modification date and
+contents. You should @emph{only} specify archive member names, not file
+names. If you do not name any members, then @command{tar} will compare the
+entire archive. If a file is represented in the archive but does not
+exist in the file system, @command{tar} reports a difference.
+
+You have to specify the record size of the archive when modifying an
+archive with a non-default record size.
+
+@command{tar} ignores files in the file system that do not have
+corresponding members in the archive.
+
+The following example compares the archive members @file{rock},
+@file{blues} and @file{funk} in the archive @file{bluesrock.tar} with
+files of the same name in the file system. (Note that there is no file,
+@file{funk}; @command{tar} will report an error message.)
+
+@smallexample
+$ @kbd{tar --compare --file=bluesrock.tar rock blues funk}
+rock
+blues
+tar: funk not found in archive
+@end smallexample
+
+The spirit behind the @option{--compare} (@option{--diff},
+@option{-d}) option is to check whether the archive represents the
+current state of files on disk, more than validating the integrity of
+the archive media. For this latter goal, see @ref{verify}.
+
+@node create options
+@section Options Used by @option{--create}
+
+@xopindex{create, additional options}
+The previous chapter described the basics of how to use
+@option{--create} (@option{-c}) to create an archive from a set of files.
+@xref{create}. This section described advanced options to be used with
+@option{--create}.
+
+@menu
+* override:: Overriding File Metadata.
+* Extended File Attributes::
+* Ignore Failed Read::
+@end menu
+
+@node override
+@subsection Overriding File Metadata
+
+As described above, a @command{tar} archive keeps, for each member it contains,
+its @dfn{metadata}, such as modification time, mode and ownership of
+the file. @GNUTAR{} allows to replace these data with other values
+when adding files to the archive. The options described in this
+section affect creation of archives of any type. For POSIX archives,
+see also @ref{PAX keywords}, for additional ways of controlling
+metadata, stored in the archive.
+
+@table @option
+@opindex mode
+@item --mode=@var{permissions}
+
+When adding files to an archive, @command{tar} will use
+@var{permissions} for the archive members, rather than the permissions
+from the files. @var{permissions} can be specified either as an octal
+number or as symbolic permissions, like with
+@command{chmod} (@xref{File permissions, Permissions, File
+permissions, fileutils, @acronym{GNU} file utilities}. This reference
+also has useful information for those not being overly familiar with
+the UNIX permission system). Using latter syntax allows for
+more flexibility. For example, the value @samp{a+rw} adds read and write
+permissions for everybody, while retaining executable bits on directories
+or on any other file already marked as executable:
+
+@smallexample
+$ @kbd{tar -c -f archive.tar --mode='a+rw' .}
+@end smallexample
+
+@item --mtime=@var{date}
+@opindex mtime
+
+When adding files to an archive, @command{tar} will use @var{date} as
+the modification time of members when creating archives, instead of
+their actual modification times. The argument @var{date} can be
+either a textual date representation in almost arbitrary format
+(@pxref{Date input formats}) or a name of an existing file, starting
+with @samp{/} or @samp{.}. In the latter case, the modification time
+of that file will be used.
+
+The following example will set the modification date to 00:00:00,
+January 1, 1970:
+
+@smallexample
+$ @kbd{tar -c -f archive.tar --mtime='1970-01-01' .}
+@end smallexample
+
+@noindent
+When used with @option{--verbose} (@pxref{verbose tutorial}) @GNUTAR{}
+will try to convert the specified date back to its textual
+representation and compare it with the one given with
+@option{--mtime} options. If the two dates differ, @command{tar} will
+print a warning saying what date it will use. This is to help user
+ensure he is using the right date.
+
+For example:
+
+@smallexample
+$ @kbd{tar -c -f archive.tar -v --mtime=yesterday .}
+tar: Option --mtime: Treating date 'yesterday' as 2006-06-20
+13:06:29.152478
+@dots{}
+@end smallexample
+
+@noindent
+When used with @option{--clamp-mtime} @GNUTAR{} will only set the
+modification date to @var{date} on files whose actual modification
+date is later than @var{date}. This is to make it easy to build
+reproducible archives given a common timestamp for generated files
+while still retaining the original timestamps of untouched files.
+
+@smallexample
+$ @kbd{tar -c -f archive.tar --clamp-mtime --mtime=@atchar{}$SOURCE_DATE_EPOCH .}
+@end smallexample
+
+@item --owner=@var{user}
+@opindex owner
+
+Specifies that @command{tar} should use @var{user} as the owner of members
+when creating archives, instead of the user associated with the source
+file.
+
+If @var{user} contains a colon, it is taken to be of the form
+@var{name}:@var{id} where a nonempty @var{name} specifies the user
+name and a nonempty @var{id} specifies the decimal numeric user
+@acronym{ID}. If @var{user} does not contain a colon, it is taken to
+be a user number if it is one or more decimal digits; otherwise it is
+taken to be a user name.
+
+If a name is given but no number, the number is inferred from the
+current host's user database if possible, and the file's user number
+is used otherwise. If a number is given but no name, the name is
+inferred from the number if possible, and an empty name is used
+otherwise. If both name and number are given, the user database is
+not consulted, and the name and number need not be valid on the
+current host.
+
+There is no value indicating a missing number, and @samp{0} usually means
+@code{root}. Some people like to force @samp{0} as the value to offer in
+their distributions for the owner of files, because the @code{root} user is
+anonymous anyway, so that might as well be the owner of anonymous
+archives. For example:
+
+@smallexample
+$ @kbd{tar -c -f archive.tar --owner=0 .}
+@end smallexample
+
+@noindent
+or:
+
+@smallexample
+$ @kbd{tar -c -f archive.tar --owner=root .}
+@end smallexample
+
+@item --group=@var{group}
+@opindex group
+
+Files added to the @command{tar} archive will have a group @acronym{ID} of @var{group},
+rather than the group from the source file. As with @option{--owner},
+the argument @var{group} can be an existing group symbolic name, or a
+decimal numeric group @acronym{ID}, or @var{name}:@var{id}.
+@end table
+
+The @option{--owner} and @option{--group} options affect all files
+added to the archive. @GNUTAR{} provides also two options that allow
+for more detailed control over owner translation:
+
+@table @option
+@item --owner-map=@var{file}
+Read UID translation map from @var{file}.
+
+When reading, empty lines are ignored. The @samp{#} sign, unless
+quoted, introduces a comment, which extends to the end of the line.
+Each nonempty line defines mapping for a single UID. It must consist
+of two fields separated by any amount of whitespace. The first field
+defines original username and UID. It can be a valid user name or
+a valid UID prefixed with a plus sign. In both cases the
+corresponding UID or user name is inferred from the current host's
+user database.
+
+The second field defines the UID and username to map the original one
+to. Its format can be the same as described above. Otherwise, it can
+have the form @var{newname}:@var{newuid}, in which case neither
+@var{newname} nor @var{newuid} are required to be valid as per the
+user database.
+
+For example, consider the following file:
+
+@example
++10 bin
+smith root:0
+@end example
+
+@noindent
+Given this file, each input file that is owner by UID 10 will be
+stored in archive with owner name @samp{bin} and owner UID
+corresponding to @samp{bin}. Each file owned by user @samp{smith}
+will be stored with owner name @samp{root} and owner ID 0. Other
+files will remain unchanged.
+
+When used together with @option{--owner-map}, the @option{--owner}
+option affects only files whose owner is not listed in the map file.
+
+@item --group-map=@var{file}
+Read GID translation map from @var{file}.
+
+The format of @var{file} is the same as for @option{--owner-map}
+option:
+
+Each nonempty line defines mapping for a single GID. It must consist
+of two fields separated by any amount of whitespace. The first field
+defines original group name and GID. It can be a valid group name or
+a valid GID prefixed with a plus sign. In both cases the
+corresponding GID or user name is inferred from the current host's
+group database.
+
+The second field defines the GID and group name to map the original one
+to. Its format can be the same as described above. Otherwise, it can
+have the form @var{newname}:@var{newgid}, in which case neither
+@var{newname} nor @var{newgid} are required to be valid as per the
+group database.
+
+When used together with @option{--group-map}, the @option{--group}
+option affects only files whose owner group is not rewritten using the
+map file.
+@end table
+
+@node Extended File Attributes
+@subsection Extended File Attributes
+
+Extended file attributes are name-value pairs that can be
+associated with each node in a file system. Despite the fact that
+POSIX.1e draft which proposed them has been withdrawn, the extended
+file attributes are supported by many file systems. @GNUTAR{} can
+store extended file attributes along with the files. This feature is
+controlled by the following command line arguments:
+
+@table @option
+@item --xattrs
+Enable extended attributes support. When used with @option{--create},
+this option instructs @GNUTAR to store extended file attribute in the
+created archive. This implies POSIX.1-2001 archive format
+(@option{--format=pax}).
+
+When used with @option{--extract}, this option tells @command{tar},
+for each file extracted, to read stored attributes from the archive
+and to apply them to the file.
+
+@item --no-xattrs
+Disable extended attributes support. This is the default.
+@end table
+
+Attribute names are strings prefixed by a @dfn{namespace} name and a dot.
+Currently, four namespaces exist: @samp{user}, @samp{trusted},
+@samp{security} and @samp{system}. By default, when @option{--xattr}
+is used, all names are stored in the archive (or extracted, if using
+@option{--extract}). This can be controlled using the following
+options:
+
+@table @option
+@item --xattrs-exclude=@var{pattern}
+Specify exclude pattern for extended attributes.
+
+@item --xattrs-include=@var{pattern}
+Specify include pattern for extended attributes.
+@end table
+
+Here, the @var{pattern} is POSIX regular expression. For example, the
+following command:
+
+@example
+$ @kbd{tar --xattrs --xattrs-exclude='^user\.' -c a.tar .}
+@end example
+
+will include in the archive @file{a.tar} all attributes, except those
+from the @samp{user} namespace.
+
+Any number of these options can be given, thereby creating lists of
+include and exclude patterns.
+
+When both options are used, first @option{--xattrs-inlcude} is applied
+to select the set of attribute names to keep, and then
+@option{--xattrs-exclude} is applied to the resulting set. In other
+words, only those attributes will be stored, whose names match one
+of the regexps in @option{--xattrs-inlcude} and don't match any of
+the regexps from @option{--xattrs-exclude}.
+
+When listing the archive, if both @option{--xattrs} and
+@option{--verbose} options are given, files that have extended
+attributes are marked with an asterisk following their permission
+mask. For example:
+
+@example
+-rw-r--r--* smith/users 110 2016-03-16 16:07 file
+@end example
+
+When two or more @option{--verbose} options are given, a detailed
+listing of extended attributes is printed after each file entry. Each
+attribute is listed on a separate line, which begins with two spaces
+and the letter @samp{x} indicating extended attribute. It is followed
+by a colon, length of the attribute and its name, e.g.:
+
+@example
+-rw-r--r--* smith/users 110 2016-03-16 16:07 file
+ x: 7 user.mime_type
+ x: 32 trusted.md5sum
+@end example
+
+File access control lists (@dfn{ACL}) are another actively used feature
+proposed by the POSIX.1e standard. Each ACL consists of a set of ACL
+entries, each of which describes the access permissions on the file for
+an individual user or a group of users as a combination of read, write
+and search/execute permissions.
+
+Whether or not to use ACLs is controlled by the following two options:
+
+@table @option
+@item --acls
+Enable POSIX ACLs support. When used with @option{--create},
+this option instructs @GNUTAR{} to store ACLs in the
+created archive. This implies POSIX.1-2001 archive format
+(@option{--format=pax}).
+
+When used with @option{--extract}, this option tells @command{tar},
+to restore ACLs for each file extracted (provided they are present
+in the archive).
+
+@item --no-acls
+Disable POSIX ACLs support. This is the default.
+@end table
+
+When listing the archive, if both @option{--acls} and
+@option{--verbose} options are given, files that have ACLs are marked
+with a plus sing following their permission mask. For example:
+
+@example
+-rw-r--r--+ smith/users 110 2016-03-16 16:07 file
+@end example
+
+When two or more @option{--verbose} options are given, a detailed
+listing of ACL is printed after each file entry:
+
+@example
+@group
+-rw-r--r--+ smith/users 110 2016-03-16 16:07 file
+ a: user::rw-,user:gray:-w-,group::r--,mask::rw-,other::r--
+@end group
+@end example
+
+@dfn{Security-Enhanced Linux} (@dfn{SELinux} for short) is a Linux
+kernel security module that provides a mechanism for supporting access
+control security policies, including so-called mandatory access
+controls (@dfn{MAC}). Support for SELinux attributes is controlled by
+the following command line options:
+
+@table @option
+@item --selinux
+Enable the SELinux context support.
+
+@item --no-selinux
+Disable SELinux context support.
+@end table
+
+@node Ignore Failed Read
+@subsection Ignore Fail Read
+
+@table @option
+@item --ignore-failed-read
+@opindex ignore-failed-read
+Do not exit with nonzero on unreadable files or directories.
+@end table
+
+@node extract options
+@section Options Used by @option{--extract}
+@cindex options for use with @option{--extract}
+
+@xopindex{extract, additional options}
+The previous chapter showed how to use @option{--extract} to extract
+an archive into the file system. Various options cause @command{tar} to
+extract more information than just file contents, such as the owner,
+the permissions, the modification date, and so forth. This section
+presents options to be used with @option{--extract} when certain special
+considerations arise. You may review the information presented in
+@ref{extract} for more basic information about the
+@option{--extract} operation.
+
+@menu
+* Reading:: Options to Help Read Archives
+* Writing:: Changing How @command{tar} Writes Files
+* Scarce:: Coping with Scarce Resources
+@end menu
+
+@node Reading
+@subsection Options to Help Read Archives
+@cindex Options when reading archives
+
+@cindex Reading incomplete records
+@cindex Records, incomplete
+@opindex read-full-records
+Normally, @command{tar} will request data in full record increments from
+an archive storage device. If the device cannot return a full record,
+@command{tar} will report an error. However, some devices do not always
+return full records, or do not require the last record of an archive to
+be padded out to the next record boundary. To keep reading until you
+obtain a full record, or to accept an incomplete record if it contains
+an end-of-archive marker, specify the @option{--read-full-records} (@option{-B}) option
+in conjunction with the @option{--extract} or @option{--list} operations.
+@xref{Blocking}.
+
+The @option{--read-full-records} (@option{-B}) option is turned on by default when
+@command{tar} reads an archive from standard input, or from a remote
+machine. This is because on @acronym{BSD} Unix systems, attempting to read a
+pipe returns however much happens to be in the pipe, even if it is
+less than was requested. If this option were not enabled, @command{tar}
+would fail as soon as it read an incomplete record from the pipe.
+
+If you're not sure of the blocking factor of an archive, you can
+read the archive by specifying @option{--read-full-records} (@option{-B}) and
+@option{--blocking-factor=@var{512-size}} (@option{-b
+@var{512-size}}), using a blocking factor larger than what the archive
+uses. This lets you avoid having to determine the blocking factor
+of an archive. @xref{Blocking Factor}.
+
+@menu
+* read full records::
+* Ignore Zeros::
+@end menu
+
+@node read full records
+@unnumberedsubsubsec Reading Full Records
+
+@FIXME{need sentence or so of intro here}
+
+@table @option
+@opindex read-full-records
+@item --read-full-records
+@item -B
+Use in conjunction with @option{--extract} (@option{--get},
+@option{-x}) to read an archive which contains incomplete records, or
+one which has a blocking factor less than the one specified.
+@end table
+
+@node Ignore Zeros
+@unnumberedsubsubsec Ignoring Blocks of Zeros
+
+@cindex End-of-archive blocks, ignoring
+@cindex Ignoring end-of-archive blocks
+@opindex ignore-zeros
+Normally, @command{tar} stops reading when it encounters a block of zeros
+between file entries (which usually indicates the end of the archive).
+@option{--ignore-zeros} (@option{-i}) allows @command{tar} to
+completely read an archive which contains a block of zeros before the
+end (i.e., a damaged archive, or one that was created by concatenating
+several archives together).
+
+The @option{--ignore-zeros} (@option{-i}) option is turned off by default because many
+versions of @command{tar} write garbage after the end-of-archive entry,
+since that part of the media is never supposed to be read. @GNUTAR{}
+does not write after the end of an archive, but seeks to
+maintain compatibility among archiving utilities.
+
+@table @option
+@item --ignore-zeros
+@itemx -i
+To ignore blocks of zeros (i.e., end-of-archive entries) which may be
+encountered while reading an archive. Use in conjunction with
+@option{--extract} or @option{--list}.
+@end table
+
+@node Writing
+@subsection Changing How @command{tar} Writes Files
+@UNREVISED
+
+@FIXME{Introductory paragraph}
+
+@menu
+* Dealing with Old Files::
+* Overwrite Old Files::
+* Keep Old Files::
+* Keep Newer Files::
+* Unlink First::
+* Recursive Unlink::
+* Data Modification Times::
+* Setting Access Permissions::
+* Directory Modification Times and Permissions::
+* Writing to Standard Output::
+* Writing to an External Program::
+* remove files::
+@end menu
+
+@node Dealing with Old Files
+@unnumberedsubsubsec Options Controlling the Overwriting of Existing Files
+
+@xopindex{overwrite-dir, introduced}
+When extracting files, if @command{tar} discovers that the extracted
+file already exists, it normally replaces the file by removing it before
+extracting it, to prevent confusion in the presence of hard or symbolic
+links. (If the existing file is a symbolic link, it is removed, not
+followed.) However, if a directory cannot be removed because it is
+nonempty, @command{tar} normally overwrites its metadata (ownership,
+permission, etc.). The @option{--overwrite-dir} option enables this
+default behavior. To be more cautious and preserve the metadata of
+such a directory, use the @option{--no-overwrite-dir} option.
+
+@cindex Overwriting old files, prevention
+@xopindex{keep-old-files, introduced}
+To be even more cautious and prevent existing files from being replaced, use
+the @option{--keep-old-files} (@option{-k}) option. It causes
+@command{tar} to refuse to replace or update a file that already
+exists, i.e., a file with the same name as an archive member prevents
+extraction of that archive member. Instead, it reports an error. For
+example:
+
+@example
+$ @kbd{ls}
+blues
+$ @kbd{tar -x -k -f archive.tar}
+tar: blues: Cannot open: File exists
+tar: Exiting with failure status due to previous errors
+@end example
+
+@xopindex{skip-old-files, introduced}
+If you wish to preserve old files untouched, but don't want
+@command{tar} to treat them as errors, use the
+@option{--skip-old-files} option. This option causes @command{tar} to
+silently skip extracting over existing files.
+
+@xopindex{overwrite, introduced}
+To be more aggressive about altering existing files, use the
+@option{--overwrite} option. It causes @command{tar} to overwrite
+existing files and to follow existing symbolic links when extracting.
+
+@cindex Protecting old files
+Some people argue that @GNUTAR{} should not hesitate
+to overwrite files with other files when extracting. When extracting
+a @command{tar} archive, they expect to see a faithful copy of the
+state of the file system when the archive was created. It is debatable
+that this would always be a proper behavior. For example, suppose one
+has an archive in which @file{usr/local} is a link to
+@file{usr/local2}. Since then, maybe the site removed the link and
+renamed the whole hierarchy from @file{/usr/local2} to
+@file{/usr/local}. Such things happen all the time. I guess it would
+not be welcome at all that @GNUTAR{} removes the
+whole hierarchy just to make room for the link to be reinstated
+(unless it @emph{also} simultaneously restores the full
+@file{/usr/local2}, of course!) @GNUTAR{} is indeed
+able to remove a whole hierarchy to reestablish a symbolic link, for
+example, but @emph{only if} @option{--recursive-unlink} is specified
+to allow this behavior. In any case, single files are silently
+removed.
+
+@xopindex{unlink-first, introduced}
+Finally, the @option{--unlink-first} (@option{-U}) option can improve performance in
+some cases by causing @command{tar} to remove files unconditionally
+before extracting them.
+
+@node Overwrite Old Files
+@unnumberedsubsubsec Overwrite Old Files
+
+@table @option
+@opindex overwrite
+@item --overwrite
+Overwrite existing files and directory metadata when extracting files
+from an archive.
+
+This causes @command{tar} to write extracted files into the file system without
+regard to the files already on the system; i.e., files with the same
+names as archive members are overwritten when the archive is extracted.
+It also causes @command{tar} to extract the ownership, permissions,
+and time stamps onto any preexisting files or directories.
+If the name of a corresponding file name is a symbolic link, the file
+pointed to by the symbolic link will be overwritten instead of the
+symbolic link itself (if this is possible). Moreover, special devices,
+empty directories and even symbolic links are automatically removed if
+they are in the way of extraction.
+
+Be careful when using the @option{--overwrite} option, particularly when
+combined with the @option{--absolute-names} (@option{-P}) option, as this combination
+can change the contents, ownership or permissions of any file on your
+system. Also, many systems do not take kindly to overwriting files that
+are currently being executed.
+
+@opindex overwrite-dir
+@item --overwrite-dir
+Overwrite the metadata of directories when extracting files from an
+archive, but remove other files before extracting.
+@end table
+
+@node Keep Old Files
+@unnumberedsubsubsec Keep Old Files
+
+@GNUTAR{} provides two options to control its actions in a situation
+when it is about to extract a file which already exists on disk.
+
+@table @option
+@opindex keep-old-files
+@item --keep-old-files
+@itemx -k
+Do not replace existing files from archive. When such a file is
+encountered, @command{tar} issues an error message. Upon end of
+extraction, @command{tar} exits with code 2 (@pxref{exit status}).
+
+@item --skip-old-files
+Do not replace existing files from archive, but do not treat that
+as error. Such files are silently skipped and do not affect
+@command{tar} exit status.
+
+Additional verbosity can be obtained using @option{--warning=existing-file}
+together with that option (@pxref{warnings}).
+@end table
+
+@node Keep Newer Files
+@unnumberedsubsubsec Keep Newer Files
+
+@table @option
+@opindex keep-newer-files
+@item --keep-newer-files
+Do not replace existing files that are newer than their archive
+copies. This option is meaningless with @option{--list} (@option{-t}).
+@end table
+
+@node Unlink First
+@unnumberedsubsubsec Unlink First
+
+@table @option
+@opindex unlink-first
+@item --unlink-first
+@itemx -U
+Remove files before extracting over them.
+This can make @command{tar} run a bit faster if you know in advance
+that the extracted files all need to be removed. Normally this option
+slows @command{tar} down slightly, so it is disabled by default.
+@end table
+
+@node Recursive Unlink
+@unnumberedsubsubsec Recursive Unlink
+
+@table @option
+@opindex recursive-unlink
+@item --recursive-unlink
+When this option is specified, try removing files and directory hierarchies
+before extracting over them. @emph{This is a dangerous option!}
+@end table
+
+If you specify the @option{--recursive-unlink} option,
+@command{tar} removes @emph{anything} that keeps you from extracting a file
+as far as current permissions will allow it. This could include removal
+of the contents of a full directory hierarchy.
+
+@node Data Modification Times
+@unnumberedsubsubsec Setting Data Modification Times
+
+@cindex Data modification times of extracted files
+@cindex Modification times of extracted files
+Normally, @command{tar} sets the data modification times of extracted
+files to the corresponding times recorded for the files in the archive, but
+limits the permissions of extracted files by the current @code{umask}
+setting.
+
+To set the data modification times of extracted files to the time when
+the files were extracted, use the @option{--touch} (@option{-m}) option in
+conjunction with @option{--extract} (@option{--get}, @option{-x}).
+
+@table @option
+@opindex touch
+@item --touch
+@itemx -m
+Sets the data modification time of extracted archive members to the time
+they were extracted, not the time recorded for them in the archive.
+Use in conjunction with @option{--extract} (@option{--get}, @option{-x}).
+@end table
+
+@node Setting Access Permissions
+@unnumberedsubsubsec Setting Access Permissions
+
+@cindex Permissions of extracted files
+@cindex Modes of extracted files
+To set the modes (access permissions) of extracted files to those
+recorded for those files in the archive, use @option{--same-permissions}
+in conjunction with the @option{--extract} (@option{--get},
+@option{-x}) operation.
+
+@table @option
+@opindex preserve-permissions
+@opindex same-permissions
+@item --preserve-permissions
+@itemx --same-permissions
+@c @itemx --ignore-umask
+@itemx -p
+Set modes of extracted archive members to those recorded in the
+archive, instead of current umask settings. Use in conjunction with
+@option{--extract} (@option{--get}, @option{-x}).
+@end table
+
+@node Directory Modification Times and Permissions
+@unnumberedsubsubsec Directory Modification Times and Permissions
+
+After successfully extracting a file member, @GNUTAR{} normally
+restores its permissions and modification times, as described in the
+previous sections. This cannot be done for directories, because
+after extracting a directory @command{tar} will almost certainly
+extract files into that directory and this will cause the directory
+modification time to be updated. Moreover, restoring that directory
+permissions may not permit file creation within it. Thus, restoring
+directory permissions and modification times must be delayed at least
+until all files have been extracted into that directory. @GNUTAR{}
+restores directories using the following approach.
+
+The extracted directories are created with the mode specified in the
+archive, as modified by the umask of the user, which gives sufficient
+permissions to allow file creation. The meta-information about the
+directory is recorded in the temporary list of directories. When
+preparing to extract next archive member, @GNUTAR{} checks if the
+directory prefix of this file contains the remembered directory. If
+it does not, the program assumes that all files have been extracted
+into that directory, restores its modification time and permissions
+and removes its entry from the internal list. This approach allows
+to correctly restore directory meta-information in the majority of
+cases, while keeping memory requirements sufficiently small. It is
+based on the fact, that most @command{tar} archives use the predefined
+order of members: first the directory, then all the files and
+subdirectories in that directory.
+
+However, this is not always true. The most important exception are
+incremental archives (@pxref{Incremental Dumps}). The member order in
+an incremental archive is reversed: first all directory members are
+stored, followed by other (non-directory) members. So, when extracting
+from incremental archives, @GNUTAR{} alters the above procedure. It
+remembers all restored directories, and restores their meta-data
+only after the entire archive has been processed. Notice, that you do
+not need to specify any special options for that, as @GNUTAR{}
+automatically detects archives in incremental format.
+
+There may be cases, when such processing is required for normal archives
+too. Consider the following example:
+
+@smallexample
+@group
+$ @kbd{tar --no-recursion -cvf archive \
+ foo foo/file1 bar bar/file foo/file2}
+foo/
+foo/file1
+bar/
+bar/file
+foo/file2
+@end group
+@end smallexample
+
+During the normal operation, after encountering @file{bar}
+@GNUTAR{} will assume that all files from the directory @file{foo}
+were already extracted and will therefore restore its timestamp and
+permission bits. However, after extracting @file{foo/file2} the
+directory timestamp will be offset again.
+
+To correctly restore directory meta-information in such cases, use
+the @option{--delay-directory-restore} command line option:
+
+@table @option
+@opindex delay-directory-restore
+@item --delay-directory-restore
+Delays restoring of the modification times and permissions of extracted
+directories until the end of extraction. This way, correct
+meta-information is restored even if the archive has unusual member
+ordering.
+
+@opindex no-delay-directory-restore
+@item --no-delay-directory-restore
+Cancel the effect of the previous @option{--delay-directory-restore}.
+Use this option if you have used @option{--delay-directory-restore} in
+@env{TAR_OPTIONS} variable (@pxref{TAR_OPTIONS}) and wish to
+temporarily disable it.
+@end table
+
+@node Writing to Standard Output
+@unnumberedsubsubsec Writing to Standard Output
+
+@cindex Writing extracted files to standard output
+@cindex Standard output, writing extracted files to
+To write the extracted files to the standard output, instead of
+creating the files on the file system, use @option{--to-stdout} (@option{-O}) in
+conjunction with @option{--extract} (@option{--get}, @option{-x}). This option is useful if you are
+extracting files to send them through a pipe, and do not need to
+preserve them in the file system. If you extract multiple members,
+they appear on standard output concatenated, in the order they are
+found in the archive.
+
+@table @option
+@opindex to-stdout
+@item --to-stdout
+@itemx -O
+Writes files to the standard output. Use only in conjunction with
+@option{--extract} (@option{--get}, @option{-x}). When this option is
+used, instead of creating the files specified, @command{tar} writes
+the contents of the files extracted to its standard output. This may
+be useful if you are only extracting the files in order to send them
+through a pipe. This option is meaningless with @option{--list}
+(@option{-t}).
+@end table
+
+This can be useful, for example, if you have a tar archive containing
+a big file and don't want to store the file on disk before processing
+it. You can use a command like this:
+
+@smallexample
+tar -xOzf foo.tgz bigfile | process
+@end smallexample
+
+or even like this if you want to process the concatenation of the files:
+
+@smallexample
+tar -xOzf foo.tgz bigfile1 bigfile2 | process
+@end smallexample
+
+However, @option{--to-command} may be more convenient for use with
+multiple files. See the next section.
+
+@node Writing to an External Program
+@unnumberedsubsubsec Writing to an External Program
+
+You can instruct @command{tar} to send the contents of each extracted
+file to the standard input of an external program:
+
+@table @option
+@opindex to-command
+@item --to-command=@var{command}
+Extract files and pipe their contents to the standard input of
+@var{command}. When this option is used, instead of creating the
+files specified, @command{tar} invokes @var{command} and pipes the
+contents of the files to its standard output. The @var{command} may
+contain command line arguments (see @ref{external, Running External Commands},
+for more detail).
+
+Notice, that @var{command} is executed once for each regular file
+extracted. Non-regular files (directories, etc.)@: are ignored when this
+option is used.
+@end table
+
+The command can obtain the information about the file it processes
+from the following environment variables:
+
+@table @env
+@vrindex TAR_FILETYPE, to-command environment
+@item TAR_FILETYPE
+Type of the file. It is a single letter with the following meaning:
+
+@multitable @columnfractions 0.10 0.90
+@item f @tab Regular file
+@item d @tab Directory
+@item l @tab Symbolic link
+@item h @tab Hard link
+@item b @tab Block device
+@item c @tab Character device
+@end multitable
+
+Currently only regular files are supported.
+
+@vrindex TAR_MODE, to-command environment
+@item TAR_MODE
+File mode, an octal number.
+
+@vrindex TAR_FILENAME, to-command environment
+@item TAR_FILENAME
+The name of the file.
+
+@vrindex TAR_REALNAME, to-command environment
+@item TAR_REALNAME
+Name of the file as stored in the archive.
+
+@vrindex TAR_UNAME, to-command environment
+@item TAR_UNAME
+Name of the file owner.
+
+@vrindex TAR_GNAME, to-command environment
+@item TAR_GNAME
+Name of the file owner group.
+
+@vrindex TAR_ATIME, to-command environment
+@item TAR_ATIME
+Time of last access. It is a decimal number, representing seconds
+since the Epoch. If the archive provides times with nanosecond
+precision, the nanoseconds are appended to the timestamp after a
+decimal point.
+
+@vrindex TAR_MTIME, to-command environment
+@item TAR_MTIME
+Time of last modification.
+
+@vrindex TAR_CTIME, to-command environment
+@item TAR_CTIME
+Time of last status change.
+
+@vrindex TAR_SIZE, to-command environment
+@item TAR_SIZE
+Size of the file.
+
+@vrindex TAR_UID, to-command environment
+@item TAR_UID
+UID of the file owner.
+
+@vrindex TAR_GID, to-command environment
+@item TAR_GID
+GID of the file owner.
+@end table
+
+Additionally, the following variables contain information about
+tar mode and the archive being processed:
+
+@table @env
+@vrindex TAR_VERSION, to-command environment
+@item TAR_VERSION
+@GNUTAR{} version number.
+
+@vrindex TAR_ARCHIVE, to-command environment
+@item TAR_ARCHIVE
+The name of the archive @command{tar} is processing.
+
+@vrindex TAR_BLOCKING_FACTOR, to-command environment
+@item TAR_BLOCKING_FACTOR
+Current blocking factor (@pxref{Blocking}).
+
+@vrindex TAR_VOLUME, to-command environment
+@item TAR_VOLUME
+Ordinal number of the volume @command{tar} is processing.
+
+@vrindex TAR_FORMAT, to-command environment
+@item TAR_FORMAT
+Format of the archive being processed. @xref{Formats}, for a complete
+list of archive format names.
+@end table
+
+These variables are defined prior to executing the command, so you can
+pass them as arguments, if you prefer. For example, if the command
+@var{proc} takes the member name and size as its arguments, then you
+could do:
+
+@smallexample
+$ @kbd{tar -x -f archive.tar \
+ --to-command='proc $TAR_FILENAME $TAR_SIZE'}
+@end smallexample
+
+@noindent
+Notice single quotes to prevent variable names from being expanded by
+the shell when invoking @command{tar}.
+
+If @var{command} exits with a non-0 status, @command{tar} will print
+an error message similar to the following:
+
+@smallexample
+tar: 2345: Child returned status 1
+@end smallexample
+
+Here, @samp{2345} is the PID of the finished process.
+
+If this behavior is not wanted, use @option{--ignore-command-error}:
+
+@table @option
+@opindex ignore-command-error
+@item --ignore-command-error
+Ignore exit codes of subprocesses. Notice that if the program
+exits on signal or otherwise terminates abnormally, the error message
+will be printed even if this option is used.
+
+@opindex no-ignore-command-error
+@item --no-ignore-command-error
+Cancel the effect of any previous @option{--ignore-command-error}
+option. This option is useful if you have set
+@option{--ignore-command-error} in @env{TAR_OPTIONS}
+(@pxref{TAR_OPTIONS}) and wish to temporarily cancel it.
+@end table
+
+@node remove files
+@unnumberedsubsubsec Removing Files
+
+@FIXME{The section is too terse. Something more to add? An example,
+maybe?}
+
+@table @option
+@opindex remove-files
+@item --remove-files
+Remove files after adding them to the archive.
+@end table
+
+@node Scarce
+@subsection Coping with Scarce Resources
+@UNREVISED
+
+@cindex Small memory
+@cindex Running out of space
+
+@menu
+* Starting File::
+* Same Order::
+@end menu
+
+@node Starting File
+@unnumberedsubsubsec Starting File
+
+@table @option
+@opindex starting-file
+@item --starting-file=@var{name}
+@itemx -K @var{name}
+Starts an operation in the middle of an archive. Use in conjunction
+with @option{--extract} (@option{--get}, @option{-x}) or @option{--list} (@option{-t}).
+@end table
+
+@cindex Middle of the archive, starting in the
+If a previous attempt to extract files failed due to lack of disk
+space, you can use @option{--starting-file=@var{name}} (@option{-K
+@var{name}}) to start extracting only after member @var{name} of the
+archive. This assumes, of course, that there is now free space, or
+that you are now extracting into a different file system. (You could
+also choose to suspend @command{tar}, remove unnecessary files from
+the file system, and then resume the same @command{tar} operation.
+In this case, @option{--starting-file} is not necessary.) See also
+@ref{interactive}, and @ref{exclude}.
+
+@node Same Order
+@unnumberedsubsubsec Same Order
+
+@table @option
+@cindex Large lists of file names on small machines
+@opindex same-order
+@opindex preserve-order
+@item --same-order
+@itemx --preserve-order
+@itemx -s
+To process large lists of file names on machines with small amounts of
+memory. Use in conjunction with @option{--compare} (@option{--diff},
+@option{-d}), @option{--list} (@option{-t}) or @option{--extract}
+(@option{--get}, @option{-x}).
+@end table
+
+The @option{--same-order} (@option{--preserve-order}, @option{-s}) option tells @command{tar} that the list of file
+names to be listed or extracted is sorted in the same order as the
+files in the archive. This allows a large list of names to be used,
+even on a small machine that would not otherwise be able to hold all
+the names in memory at the same time. Such a sorted list can easily be
+created by running @samp{tar -t} on the archive and editing its output.
+
+This option is probably never needed on modern computer systems.
+
+@node backup
+@section Backup options
+
+@cindex backup options
+
+@GNUTAR{} offers options for making backups of files
+before writing new versions. These options control the details of
+these backups. They may apply to the archive itself before it is
+created or rewritten, as well as individual extracted members. Other
+@acronym{GNU} programs (@command{cp}, @command{install}, @command{ln},
+and @command{mv}, for example) offer similar options.
+
+Backup options may prove unexpectedly useful when extracting archives
+containing many members having identical name, or when extracting archives
+on systems having file name limitations, making different members appear
+as having similar names through the side-effect of name truncation.
+@FIXME{This is true only if we have a good scheme for truncated backup names,
+which I'm not sure at all: I suspect work is needed in this area.}
+When any existing file is backed up before being overwritten by extraction,
+then clashing files are automatically be renamed to be unique, and the
+true name is kept for only the last file of a series of clashing files.
+By using verbose mode, users may track exactly what happens.
+
+At the detail level, some decisions are still experimental, and may
+change in the future, we are waiting comments from our users. So, please
+do not learn to depend blindly on the details of the backup features.
+For example, currently, directories themselves are never renamed through
+using these options, so, extracting a file over a directory still has
+good chances to fail. Also, backup options apply to created archives,
+not only to extracted members. For created archives, backups will not
+be attempted when the archive is a block or character device, or when it
+refers to a remote file.
+
+For the sake of simplicity and efficiency, backups are made by renaming old
+files prior to creation or extraction, and not by copying. The original
+name is restored if the file creation fails. If a failure occurs after a
+partial extraction of a file, both the backup and the partially extracted
+file are kept.
+
+@table @samp
+@item --backup[=@var{method}]
+@opindex backup
+@vindex VERSION_CONTROL
+@cindex backups
+Back up files that are about to be overwritten or removed.
+Without this option, the original versions are destroyed.
+
+Use @var{method} to determine the type of backups made.
+If @var{method} is not specified, use the value of the @env{VERSION_CONTROL}
+environment variable. And if @env{VERSION_CONTROL} is not set,
+use the @samp{existing} method.
+
+@vindex version-control @r{Emacs variable}
+This option corresponds to the Emacs variable @samp{version-control};
+the same values for @var{method} are accepted as in Emacs. This option
+also allows more descriptive names. The valid @var{method}s are:
+
+@table @samp
+@item t
+@itemx numbered
+@cindex numbered @r{backup method}
+Always make numbered backups.
+
+@item nil
+@itemx existing
+@cindex existing @r{backup method}
+Make numbered backups of files that already have them, simple backups
+of the others.
+
+@item never
+@itemx simple
+@cindex simple @r{backup method}
+Always make simple backups.
+
+@end table
+
+@item --suffix=@var{suffix}
+@opindex suffix
+@cindex backup suffix
+@vindex SIMPLE_BACKUP_SUFFIX
+Append @var{suffix} to each backup file made with @option{--backup}. If this
+option is not specified, the value of the @env{SIMPLE_BACKUP_SUFFIX}
+environment variable is used. And if @env{SIMPLE_BACKUP_SUFFIX} is not
+set, the default is @samp{~}, just as in Emacs.
+
+@end table
+
+@node Applications
+@section Notable @command{tar} Usages
+@UNREVISED
+
+@FIXME{Using Unix file linking capability to recreate directory
+structures---linking files into one subdirectory and then
+@command{tar}ring that directory.}
+
+@FIXME{Nice hairy example using absolute-names, newer, etc.}
+
+@findex uuencode
+You can easily use archive files to transport a group of files from
+one system to another: put all relevant files into an archive on one
+computer system, transfer the archive to another system, and extract
+the contents there. The basic transfer medium might be magnetic tape,
+Internet FTP, or even electronic mail (though you must encode the
+archive with @command{uuencode} in order to transport it properly by
+mail). Both machines do not have to use the same operating system, as
+long as they both support the @command{tar} program.
+
+For example, here is how you might copy a directory's contents from
+one disk to another, while preserving the dates, modes, owners and
+link-structure of all the files therein. In this case, the transfer
+medium is a @dfn{pipe}:
+
+@smallexample
+$ @kbd{(cd sourcedir; tar -cf - .) | (cd targetdir; tar -xf -)}
+@end smallexample
+
+@noindent
+You can avoid subshells by using @option{-C} option:
+
+@smallexample
+$ @kbd{tar -C sourcedir -cf - . | tar -C targetdir -xf -}
+@end smallexample
+
+@noindent
+The command also works using long option forms:
+
+@smallexample
+@group
+$ @kbd{(cd sourcedir; tar --create --file=- . ) \
+ | (cd targetdir; tar --extract --file=-)}
+@end group
+@end smallexample
+
+@noindent
+or
+
+@smallexample
+@group
+$ @kbd{tar --directory sourcedir --create --file=- . \
+ | tar --directory targetdir --extract --file=-}
+@end group
+@end smallexample
+
+@noindent
+This is one of the easiest methods to transfer a @command{tar} archive.
+
+@node looking ahead
+@section Looking Ahead: The Rest of this Manual
+
+You have now seen how to use all eight of the operations available to
+@command{tar}, and a number of the possible options. The next chapter
+explains how to choose and change file and archive names, how to use
+files to store names of other files which you can then call as
+arguments to @command{tar} (this can help you save time if you expect to
+archive the same list of files a number of times), and so forth.
+@FIXME{in case it's not obvious, i'm making this up in some sense
+based on my limited memory of what the next chapter *really* does. i
+just wanted to flesh out this final section a little bit so i'd
+remember to stick it in here. :-)}
+
+If there are too many files to conveniently list on the command line,
+you can list the names in a file, and @command{tar} will read that file.
+@xref{files}.
+
+There are various ways of causing @command{tar} to skip over some files,
+and not archive them. @xref{Choosing}.
+
+@node Backups
+@chapter Performing Backups and Restoring Files
+@cindex backups
+
+@GNUTAR{} is distributed along with the scripts for performing backups
+and restores. Even if there is a good chance those scripts may be
+satisfying to you, they are not the only scripts or methods available for doing
+backups and restore. You may well create your own, or use more
+sophisticated packages dedicated to that purpose.
+
+Some users are enthusiastic about @code{Amanda} (The Advanced Maryland
+Automatic Network Disk Archiver), a backup system developed by James
+da Silva @file{jds@@cs.umd.edu} and available on many Unix systems.
+This is free software, and it is available from @uref{http://www.amanda.org}.
+
+@FIXME{
+
+Here is a possible plan for a future documentation about the backuping
+scripts which are provided within the @GNUTAR{}
+distribution.
+
+@itemize @bullet
+@item dumps
+ @itemize @minus
+ @item what are dumps
+ @item different levels of dumps
+ @itemize +
+ @item full dump = dump everything
+ @item level 1, level 2 dumps etc
+ A level @var{n} dump dumps everything changed since the last level
+ @var{n}-1 dump (?)
+ @end itemize
+ @item how to use scripts for dumps (ie, the concept)
+ @itemize +
+ @item scripts to run after editing backup specs (details)
+ @end itemize
+ @item Backup Specs, what is it.
+ @itemize +
+ @item how to customize
+ @item actual text of script [/sp/dump/backup-specs]
+ @end itemize
+ @item Problems
+ @itemize +
+ @item rsh doesn't work
+ @item rtape isn't installed
+ @item (others?)
+ @end itemize
+ @item the @option{--incremental} option of tar
+ @item tapes
+ @itemize +
+ @item write protection
+ @item types of media, different sizes and types, useful for different things
+ @item files and tape marks
+ one tape mark between files, two at end.
+ @item positioning the tape
+ MT writes two at end of write,
+ backspaces over one when writing again.
+ @end itemize
+ @end itemize
+@end itemize
+}
+
+This chapter documents both the provided shell scripts and @command{tar}
+options which are more specific to usage as a backup tool.
+
+To @dfn{back up} a file system means to create archives that contain
+all the files in that file system. Those archives can then be used to
+restore any or all of those files (for instance if a disk crashes or a
+file is accidentally deleted). File system @dfn{backups} are also
+called @dfn{dumps}.
+
+@menu
+* Full Dumps:: Using @command{tar} to Perform Full Dumps
+* Incremental Dumps:: Using @command{tar} to Perform Incremental Dumps
+* Backup Levels:: Levels of Backups
+* Backup Parameters:: Setting Parameters for Backups and Restoration
+* Scripted Backups:: Using the Backup Scripts
+* Scripted Restoration:: Using the Restore Script
+@end menu
+
+@node Full Dumps
+@section Using @command{tar} to Perform Full Dumps
+@UNREVISED
+
+@cindex full dumps
+@cindex dumps, full
+
+@cindex corrupted archives
+Full dumps should only be made when no other people or programs
+are modifying files in the file system. If files are modified while
+@command{tar} is making the backup, they may not be stored properly in
+the archive, in which case you won't be able to restore them if you
+have to. (Files not being modified are written with no trouble, and do
+not corrupt the entire archive.)
+
+You will want to use the @option{--label=@var{archive-label}}
+(@option{-V @var{archive-label}}) option to give the archive a
+volume label, so you can tell what this archive is even if the label
+falls off the tape, or anything like that.
+
+Unless the file system you are dumping is guaranteed to fit on
+one volume, you will need to use the @option{--multi-volume} (@option{-M}) option.
+Make sure you have enough tapes on hand to complete the backup.
+
+If you want to dump each file system separately you will need to use
+the @option{--one-file-system} option to prevent
+@command{tar} from crossing file system boundaries when storing
+(sub)directories.
+
+The @option{--incremental} (@option{-G}) (@pxref{Incremental Dumps})
+option is not needed, since this is a complete copy of everything in
+the file system, and a full restore from this backup would only be
+done onto a completely
+empty disk.
+
+Unless you are in a hurry, and trust the @command{tar} program (and your
+tapes), it is a good idea to use the @option{--verify} (@option{-W})
+option, to make sure your files really made it onto the dump properly.
+This will also detect cases where the file was modified while (or just
+after) it was being archived. Not all media (notably cartridge tapes)
+are capable of being verified, unfortunately.
+
+@node Incremental Dumps
+@section Using @command{tar} to Perform Incremental Dumps
+
+@dfn{Incremental backup} is a special form of @GNUTAR{} archive that
+stores additional metadata so that exact state of the file system
+can be restored when extracting the archive.
+
+@GNUTAR{} currently offers two options for handling incremental
+backups: @option{--listed-incremental=@var{snapshot-file}} (@option{-g
+@var{snapshot-file}}) and @option{--incremental} (@option{-G}).
+
+@xopindex{listed-incremental, described}
+The option @option{--listed-incremental} instructs tar to operate on
+an incremental archive with additional metadata stored in a standalone
+file, called a @dfn{snapshot file}. The purpose of this file is to help
+determine which files have been changed, added or deleted since the
+last backup, so that the next incremental backup will contain only
+modified files. The name of the snapshot file is given as an argument
+to the option:
+
+@table @option
+@item --listed-incremental=@var{file}
+@itemx -g @var{file}
+ Handle incremental backups with snapshot data in @var{file}.
+@end table
+
+To create an incremental backup, you would use
+@option{--listed-incremental} together with @option{--create}
+(@pxref{create}). For example:
+
+@smallexample
+$ @kbd{tar --create \
+ --file=archive.1.tar \
+ --listed-incremental=/var/log/usr.snar \
+ /usr}
+@end smallexample
+
+This will create in @file{archive.1.tar} an incremental backup of
+the @file{/usr} file system, storing additional metadata in the file
+@file{/var/log/usr.snar}. If this file does not exist, it will be
+created. The created archive will then be a @dfn{level 0 backup};
+please see the next section for more on backup levels.
+
+Otherwise, if the file @file{/var/log/usr.snar} exists, it
+determines which files are modified. In this case only these files will be
+stored in the archive. Suppose, for example, that after running the
+above command, you delete file @file{/usr/doc/old} and create
+directory @file{/usr/local/db} with the following contents:
+
+@smallexample
+$ @kbd{ls /usr/local/db}
+/usr/local/db/data
+/usr/local/db/index
+@end smallexample
+
+Some time later you create another incremental backup. You will
+then see:
+
+@smallexample
+$ @kbd{tar --create \
+ --file=archive.2.tar \
+ --listed-incremental=/var/log/usr.snar \
+ /usr}
+tar: usr/local/db: Directory is new
+usr/local/db/
+usr/local/db/data
+usr/local/db/index
+@end smallexample
+
+@noindent
+The created archive @file{archive.2.tar} will contain only these
+three members. This archive is called a @dfn{level 1 backup}. Notice
+that @file{/var/log/usr.snar} will be updated with the new data, so if
+you plan to create more @samp{level 1} backups, it is necessary to
+create a working copy of the snapshot file before running
+@command{tar}. The above example will then be modified as follows:
+
+@smallexample
+$ @kbd{cp /var/log/usr.snar /var/log/usr.snar-1}
+$ @kbd{tar --create \
+ --file=archive.2.tar \
+ --listed-incremental=/var/log/usr.snar-1 \
+ /usr}
+@end smallexample
+
+@anchor{--level=0}
+@xopindex{level, described}
+You can force @samp{level 0} backups either by removing the snapshot
+file before running @command{tar}, or by supplying the
+@option{--level=0} option, e.g.:
+
+@smallexample
+$ @kbd{tar --create \
+ --file=archive.2.tar \
+ --listed-incremental=/var/log/usr.snar-0 \
+ --level=0 \
+ /usr}
+@end smallexample
+
+Incremental dumps depend crucially on time stamps, so the results are
+unreliable if you modify a file's time stamps during dumping (e.g.,
+with the @option{--atime-preserve=replace} option), or if you set the clock
+backwards.
+
+@anchor{device numbers}
+@cindex Device numbers, using in incremental backups
+Metadata stored in snapshot files include device numbers, which,
+obviously are supposed to be non-volatile values. However, it turns
+out that @acronym{NFS} devices have undependable values when an automounter
+gets in the picture. This can lead to a great deal of spurious
+redumping in incremental dumps, so it is somewhat useless to compare
+two @acronym{NFS} devices numbers over time. The solution implemented
+currently is to consider all @acronym{NFS} devices as being equal
+when it comes to comparing directories; this is fairly gross, but
+there does not seem to be a better way to go.
+
+Apart from using @acronym{NFS}, there are a number of cases where
+relying on device numbers can cause spurious redumping of unmodified
+files. For example, this occurs when archiving @acronym{LVM} snapshot
+volumes. To avoid this, use @option{--no-check-device} option:
+
+@table @option
+@xopindex{no-check-device, described}
+@item --no-check-device
+Do not rely on device numbers when preparing a list of changed files
+for an incremental dump.
+
+@xopindex{check-device, described}
+@item --check-device
+Use device numbers when preparing a list of changed files
+for an incremental dump. This is the default behavior. The purpose
+of this option is to undo the effect of the @option{--no-check-device}
+if it was given in @env{TAR_OPTIONS} environment variable
+(@pxref{TAR_OPTIONS}).
+@end table
+
+There is also another way to cope with changing device numbers. It is
+described in detail in @ref{Fixing Snapshot Files}.
+
+Note that incremental archives use @command{tar} extensions and may
+not be readable by non-@acronym{GNU} versions of the @command{tar} program.
+
+@xopindex{listed-incremental, using with @option{--extract}}
+@xopindex{extract, using with @option{--listed-incremental}}
+To extract from the incremental dumps, use
+@option{--listed-incremental} together with @option{--extract}
+option (@pxref{extracting files}). In this case, @command{tar} does
+not need to access snapshot file, since all the data necessary for
+extraction are stored in the archive itself. So, when extracting, you
+can give whatever argument to @option{--listed-incremental}, the usual
+practice is to use @option{--listed-incremental=/dev/null}.
+Alternatively, you can use @option{--incremental}, which needs no
+arguments. In general, @option{--incremental} (@option{-G}) can be
+used as a shortcut for @option{--listed-incremental} when listing or
+extracting incremental backups (for more information regarding this
+option, @pxref{incremental-op}).
+
+When extracting from the incremental backup @GNUTAR{} attempts to
+restore the exact state the file system had when the archive was
+created. In particular, it will @emph{delete} those files in the file
+system that did not exist in their directories when the archive was
+created. If you have created several levels of incremental files,
+then in order to restore the exact contents the file system had when
+the last level was created, you will need to restore from all backups
+in turn. Continuing our example, to restore the state of @file{/usr}
+file system, one would do@footnote{Notice, that since both archives
+were created without @option{-P} option (@pxref{absolute}), these
+commands should be run from the root file system.}:
+
+@smallexample
+$ @kbd{tar --extract \
+ --listed-incremental=/dev/null \
+ --file archive.1.tar}
+$ @kbd{tar --extract \
+ --listed-incremental=/dev/null \
+ --file archive.2.tar}
+@end smallexample
+
+To list the contents of an incremental archive, use @option{--list}
+(@pxref{list}), as usual. To obtain more information about the
+archive, use @option{--listed-incremental} or @option{--incremental}
+combined with two @option{--verbose} options@footnote{Two
+@option{--verbose} options were selected to avoid breaking usual
+verbose listing output (@option{--list --verbose}) when using in
+scripts.
+
+@xopindex{incremental, using with @option{--list}}
+@xopindex{listed-incremental, using with @option{--list}}
+@xopindex{list, using with @option{--incremental}}
+@xopindex{list, using with @option{--listed-incremental}}
+Versions of @GNUTAR{} up to 1.15.1 used to dump verbatim binary
+contents of the DUMPDIR header (with terminating nulls) when
+@option{--incremental} or @option{--listed-incremental} option was
+given, no matter what the verbosity level. This behavior, and,
+especially, the binary output it produced were considered inconvenient
+and were changed in version 1.16.}:
+
+@smallexample
+@kbd{tar --list --incremental --verbose --verbose --file archive.tar}
+@end smallexample
+
+This command will print, for each directory in the archive, the list
+of files in that directory at the time the archive was created. This
+information is put out in a format which is both human-readable and
+unambiguous for a program: each file name is printed as
+
+@smallexample
+@var{x} @var{file}
+@end smallexample
+
+@noindent
+where @var{x} is a letter describing the status of the file: @samp{Y}
+if the file is present in the archive, @samp{N} if the file is not
+included in the archive, or a @samp{D} if the file is a directory (and
+is included in the archive). @xref{Dumpdir}, for the detailed
+description of dumpdirs and status codes. Each such
+line is terminated by a newline character. The last line is followed
+by an additional newline to indicate the end of the data.
+
+@anchor{incremental-op}The option @option{--incremental} (@option{-G})
+gives the same behavior as @option{--listed-incremental} when used
+with @option{--list} and @option{--extract} options. When used with
+@option{--create} option, it creates an incremental archive without
+creating snapshot file. Thus, it is impossible to create several
+levels of incremental backups with @option{--incremental} option.
+
+@node Backup Levels
+@section Levels of Backups
+
+An archive containing all the files in the file system is called a
+@dfn{full backup} or @dfn{full dump}. You could insure your data by
+creating a full dump every day. This strategy, however, would waste a
+substantial amount of archive media and user time, as unchanged files
+are daily re-archived.
+
+It is more efficient to do a full dump only occasionally. To back up
+files between full dumps, you can use @dfn{incremental dumps}. A @dfn{level
+one} dump archives all the files that have changed since the last full
+dump.
+
+A typical dump strategy would be to perform a full dump once a week,
+and a level one dump once a day. This means some versions of files
+will in fact be archived more than once, but this dump strategy makes
+it possible to restore a file system to within one day of accuracy by
+only extracting two archives---the last weekly (full) dump and the
+last daily (level one) dump. The only information lost would be in
+files changed or created since the last daily backup. (Doing dumps
+more than once a day is usually not worth the trouble.)
+
+@GNUTAR{} comes with scripts you can use to do full
+and level-one (actually, even level-two and so on) dumps. Using
+scripts (shell programs) to perform backups and restoration is a
+convenient and reliable alternative to typing out file name lists
+and @command{tar} commands by hand.
+
+Before you use these scripts, you need to edit the file
+@file{backup-specs}, which specifies parameters used by the backup
+scripts and by the restore script. This file is usually located
+in @file{/etc/backup} directory. @xref{Backup Parameters}, for its
+detailed description. Once the backup parameters are set, you can
+perform backups or restoration by running the appropriate script.
+
+The name of the backup script is @code{backup}. The name of the
+restore script is @code{restore}. The following sections describe
+their use in detail.
+
+@emph{Please Note:} The backup and restoration scripts are
+designed to be used together. While it is possible to restore files by
+hand from an archive which was created using a backup script, and to create
+an archive by hand which could then be extracted using the restore script,
+it is easier to use the scripts. @xref{Incremental Dumps}, before
+making such an attempt.
+
+@node Backup Parameters
+@section Setting Parameters for Backups and Restoration
+
+The file @file{backup-specs} specifies backup parameters for the
+backup and restoration scripts provided with @command{tar}. You must
+edit @file{backup-specs} to fit your system configuration and schedule
+before using these scripts.
+
+Syntactically, @file{backup-specs} is a shell script, containing
+mainly variable assignments. However, any valid shell construct
+is allowed in this file. Particularly, you may wish to define
+functions within that script (e.g., see @code{RESTORE_BEGIN} below).
+For more information about shell script syntax, please refer to
+@url{http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html#ta
+g_02, the definition of the Shell Command Language}. See also
+@ref{Top,,Bash Features,bashref,Bash Reference Manual}.
+
+The shell variables controlling behavior of @code{backup} and
+@code{restore} are described in the following subsections.
+
+@menu
+* General-Purpose Variables::
+* Magnetic Tape Control::
+* User Hooks::
+* backup-specs example:: An Example Text of @file{Backup-specs}
+@end menu
+
+@node General-Purpose Variables
+@subsection General-Purpose Variables
+
+@defvr {Backup variable} ADMINISTRATOR
+The user name of the backup administrator. @code{Backup} scripts
+sends a backup report to this address.
+@end defvr
+
+@defvr {Backup variable} BACKUP_HOUR
+The hour at which the backups are done. This can be a number from 0
+to 23, or the time specification in form @var{hours}:@var{minutes},
+or the string @samp{now}.
+
+This variable is used by @code{backup}. Its value may be overridden
+using @option{--time} option (@pxref{Scripted Backups}).
+@end defvr
+
+@defvr {Backup variable} TAPE_FILE
+
+The device @command{tar} writes the archive to. If @var{TAPE_FILE}
+is a remote archive (@pxref{remote-dev}), backup script will suppose
+that your @command{mt} is able to access remote devices. If @var{RSH}
+(@pxref{RSH}) is set, @option{--rsh-command} option will be added to
+invocations of @command{mt}.
+@end defvr
+
+@defvr {Backup variable} BLOCKING
+
+The blocking factor @command{tar} will use when writing the dump archive.
+@xref{Blocking Factor}.
+@end defvr
+
+@defvr {Backup variable} BACKUP_DIRS
+
+A list of file systems to be dumped (for @code{backup}), or restored
+(for @code{restore}). You can include any directory
+name in the list --- subdirectories on that file system will be
+included, regardless of how they may look to other networked machines.
+Subdirectories on other file systems will be ignored.
+
+The host name specifies which host to run @command{tar} on, and should
+normally be the host that actually contains the file system. However,
+the host machine must have @GNUTAR{} installed, and
+must be able to access the directory containing the backup scripts and
+their support files using the same file name that is used on the
+machine where the scripts are run (i.e., what @command{pwd} will print
+when in that directory on that machine). If the host that contains
+the file system does not have this capability, you can specify another
+host as long as it can access the file system through @acronym{NFS}.
+
+If the list of file systems is very long you may wish to put it
+in a separate file. This file is usually named
+@file{/etc/backup/dirs}, but this name may be overridden in
+@file{backup-specs} using @code{DIRLIST} variable.
+@end defvr
+
+@defvr {Backup variable} DIRLIST
+
+The name of the file that contains a list of file systems to backup
+or restore. By default it is @file{/etc/backup/dirs}.
+@end defvr
+
+@defvr {Backup variable} BACKUP_FILES
+
+A list of individual files to be dumped (for @code{backup}), or restored
+(for @code{restore}). These should be accessible from the machine on
+which the backup script is run.
+
+If the list of individual files is very long you may wish to store it
+in a separate file. This file is usually named
+@file{/etc/backup/files}, but this name may be overridden in
+@file{backup-specs} using @code{FILELIST} variable.
+@end defvr
+
+@defvr {Backup variable} FILELIST
+
+The name of the file that contains a list of individual files to backup
+or restore. By default it is @file{/etc/backup/files}.
+@end defvr
+
+@defvr {Backup variable} MT
+
+Full file name of @command{mt} binary.
+@end defvr
+
+@defvr {Backup variable} RSH
+@anchor{RSH}
+Full file name of @command{rsh} binary or its equivalent. You may wish to
+set it to @code{ssh}, to improve security. In this case you will have
+to use public key authentication.
+@end defvr
+
+@defvr {Backup variable} RSH_COMMAND
+
+Full file name of @command{rsh} binary on remote machines. This will
+be passed via @option{--rsh-command} option to the remote invocation
+of @GNUTAR{}.
+@end defvr
+
+@defvr {Backup variable} VOLNO_FILE
+
+Name of temporary file to hold volume numbers. This needs to be accessible
+by all the machines which have file systems to be dumped.
+@end defvr
+
+@defvr {Backup variable} XLIST
+
+Name of @dfn{exclude file list}. An @dfn{exclude file list} is a file
+located on the remote machine and containing the list of files to
+be excluded from the backup. Exclude file lists are searched in
+/etc/tar-backup directory. A common use for exclude file lists
+is to exclude files containing security-sensitive information
+(e.g., @file{/etc/shadow} from backups).
+
+This variable affects only @code{backup}.
+@end defvr
+
+@defvr {Backup variable} SLEEP_TIME
+
+Time to sleep between dumps of any two successive file systems
+
+This variable affects only @code{backup}.
+@end defvr
+
+@defvr {Backup variable} DUMP_REMIND_SCRIPT
+
+Script to be run when it's time to insert a new tape in for the next
+volume. Administrators may want to tailor this script for their site.
+If this variable isn't set, @GNUTAR{} will display its built-in
+prompt, and will expect confirmation from the console. For the
+description of the default prompt, see @ref{change volume prompt}.
+
+@end defvr
+
+@defvr {Backup variable} SLEEP_MESSAGE
+
+Message to display on the terminal while waiting for dump time. Usually
+this will just be some literal text.
+@end defvr
+
+@defvr {Backup variable} TAR
+
+Full file name of the @GNUTAR{} executable. If this is not set, backup
+scripts will search @command{tar} in the current shell path.
+@end defvr
+
+@node Magnetic Tape Control
+@subsection Magnetic Tape Control
+
+Backup scripts access tape device using special @dfn{hook functions}.
+These functions take a single argument --- the name of the tape
+device. Their names are kept in the following variables:
+
+@defvr {Backup variable} MT_BEGIN
+The name of @dfn{begin} function. This function is called before
+accessing the drive. By default it retensions the tape:
+
+@smallexample
+MT_BEGIN=mt_begin
+
+mt_begin() @{
+ mt -f "$1" retension
+@}
+@end smallexample
+@end defvr
+
+@defvr {Backup variable} MT_REWIND
+The name of @dfn{rewind} function. The default definition is as
+follows:
+
+@smallexample
+MT_REWIND=mt_rewind
+
+mt_rewind() @{
+ mt -f "$1" rewind
+@}
+@end smallexample
+
+@end defvr
+
+@defvr {Backup variable} MT_OFFLINE
+The name of the function switching the tape off line. By default
+it is defined as follows:
+
+@smallexample
+MT_OFFLINE=mt_offline
+
+mt_offline() @{
+ mt -f "$1" offl
+@}
+@end smallexample
+@end defvr
+
+@defvr {Backup variable} MT_STATUS
+The name of the function used to obtain the status of the archive device,
+including error count. Default definition:
+
+@smallexample
+MT_STATUS=mt_status
+
+mt_status() @{
+ mt -f "$1" status
+@}
+@end smallexample
+@end defvr
+
+@node User Hooks
+@subsection User Hooks
+
+@dfn{User hooks} are shell functions executed before and after
+each @command{tar} invocation. Thus, there are @dfn{backup
+hooks}, which are executed before and after dumping each file
+system, and @dfn{restore hooks}, executed before and
+after restoring a file system. Each user hook is a shell function
+taking four arguments:
+
+@deffn {User Hook Function} hook @var{level} @var{host} @var{fs} @var{fsname}
+Its arguments are:
+
+@table @var
+@item level
+Current backup or restore level.
+
+@item host
+Name or IP address of the host machine being dumped or restored.
+
+@item fs
+Full file name of the file system being dumped or restored.
+
+@item fsname
+File system name with directory separators replaced with colons. This
+is useful, e.g., for creating unique files.
+@end table
+@end deffn
+
+Following variables keep the names of user hook functions:
+
+@defvr {Backup variable} DUMP_BEGIN
+Dump begin function. It is executed before dumping the file system.
+@end defvr
+
+@defvr {Backup variable} DUMP_END
+Executed after dumping the file system.
+@end defvr
+
+@defvr {Backup variable} RESTORE_BEGIN
+Executed before restoring the file system.
+@end defvr
+
+@defvr {Backup variable} RESTORE_END
+Executed after restoring the file system.
+@end defvr
+
+@node backup-specs example
+@subsection An Example Text of @file{Backup-specs}
+
+The following is an example of @file{backup-specs}:
+
+@smallexample
+# site-specific parameters for file system backup.
+
+ADMINISTRATOR=friedman
+BACKUP_HOUR=1
+TAPE_FILE=/dev/nrsmt0
+
+# Use @code{ssh} instead of the less secure @code{rsh}
+RSH=/usr/bin/ssh
+RSH_COMMAND=/usr/bin/ssh
+
+# Override MT_STATUS function:
+my_status() @{
+ mts -t $TAPE_FILE
+@}
+MT_STATUS=my_status
+
+# Disable MT_OFFLINE function
+MT_OFFLINE=:
+
+BLOCKING=124
+BACKUP_DIRS="
+ albert:/fs/fsf
+ apple-gunkies:/gd
+ albert:/fs/gd2
+ albert:/fs/gp
+ geech:/usr/jla
+ churchy:/usr/roland
+ albert:/
+ albert:/usr
+ apple-gunkies:/
+ apple-gunkies:/usr
+ gnu:/hack
+ gnu:/u
+ apple-gunkies:/com/mailer/gnu
+ apple-gunkies:/com/archive/gnu"
+
+BACKUP_FILES="/com/mailer/aliases /com/mailer/league*[a-z]"
+
+@end smallexample
+
+@node Scripted Backups
+@section Using the Backup Scripts
+
+The syntax for running a backup script is:
+
+@smallexample
+backup --level=@var{level} --time=@var{time}
+@end smallexample
+
+The @option{--level} option requests the dump level. Thus, to produce
+a full dump, specify @code{--level=0} (this is the default, so
+@option{--level} may be omitted if its value is
+@code{0})@footnote{For backward compatibility, the @code{backup} will also
+try to deduce the requested dump level from the name of the
+script itself. If the name consists of a string @samp{level-}
+followed by a single decimal digit, that digit is taken as
+the dump level number. Thus, you may create a link from @code{backup}
+to @code{level-1} and then run @code{level-1} whenever you need to
+create a level one dump.}.
+
+The @option{--time} option determines when should the backup be
+run. @var{Time} may take three forms:
+
+@table @asis
+@item @var{hh}:@var{mm}
+
+The dump must be run at @var{hh} hours @var{mm} minutes.
+
+@item @var{hh}
+
+The dump must be run at @var{hh} hours.
+
+@item now
+
+The dump must be run immediately.
+@end table
+
+You should start a script with a tape or disk mounted. Once you
+start a script, it prompts you for new tapes or disks as it
+needs them. Media volumes don't have to correspond to archive
+files --- a multi-volume archive can be started in the middle of a
+tape that already contains the end of another multi-volume archive.
+The @code{restore} script prompts for media by its archive volume,
+so to avoid an error message you should keep track of which tape
+(or disk) contains which volume of the archive (@pxref{Scripted
+Restoration}).
+
+The backup scripts write two files on the file system. The first is a
+record file in @file{/etc/tar-backup/}, which is used by the scripts
+to store and retrieve information about which files were dumped. This
+file is not meant to be read by humans, and should not be deleted by
+them. @xref{Snapshot Files}, for a more detailed explanation of this
+file.
+
+The second file is a log file containing the names of the file systems
+and files dumped, what time the backup was made, and any error
+messages that were generated, as well as how much space was left in
+the media volume after the last volume of the archive was written.
+You should check this log file after every backup. The file name is
+@file{log-@var{mm-dd-yyyy}-level-@var{n}}, where @var{mm-dd-yyyy}
+represents current date, and @var{n} represents current dump level number.
+
+The script also prints the name of each system being dumped to the
+standard output.
+
+Following is the full list of options accepted by @code{backup}
+script:
+
+@table @option
+@item -l @var{level}
+@itemx --level=@var{level}
+Do backup level @var{level} (default 0).
+
+@item -f
+@itemx --force
+Force backup even if today's log file already exists.
+
+@item -v[@var{level}]
+@itemx --verbose[=@var{level}]
+Set verbosity level. The higher the level is, the more debugging
+information will be output during execution. Default @var{level}
+is 100, which means the highest debugging level.
+
+@item -t @var{start-time}
+@itemx --time=@var{start-time}
+Wait till @var{time}, then do backup.
+
+@item -h
+@itemx --help
+Display short help message and exit.
+
+@item -V
+@itemx --version
+Display information about the program's name, version, origin and legal
+status, all on standard output, and then exit successfully.
+@end table
+
+
+@node Scripted Restoration
+@section Using the Restore Script
+
+To restore files that were archived using a scripted backup, use the
+@code{restore} script. Its usage is quite straightforward. In the
+simplest form, invoke @code{restore --all}, it will
+then restore all the file systems and files specified in
+@file{backup-specs} (@pxref{General-Purpose Variables,BACKUP_DIRS}).
+
+You may select the file systems (and/or files) to restore by
+giving @code{restore} a list of @dfn{patterns} in its command
+line. For example, running
+
+@smallexample
+restore 'albert:*'
+@end smallexample
+
+@noindent
+will restore all file systems on the machine @samp{albert}. A more
+complicated example:
+
+@smallexample
+restore 'albert:*' '*:/var'
+@end smallexample
+
+@noindent
+This command will restore all file systems on the machine @samp{albert}
+as well as @file{/var} file system on all machines.
+
+By default @code{restore} will start restoring files from the lowest
+available dump level (usually zero) and will continue through
+all available dump levels. There may be situations where such a
+thorough restore is not necessary. For example, you may wish to
+restore only files from the recent level one backup. To do so,
+use @option{--level} option, as shown in the example below:
+
+@smallexample
+restore --level=1
+@end smallexample
+
+The full list of options accepted by @code{restore} follows:
+
+@table @option
+@item -a
+@itemx --all
+Restore all file systems and files specified in @file{backup-specs}.
+
+@item -l @var{level}
+@itemx --level=@var{level}
+Start restoring from the given backup level, instead of the default 0.
+
+@item -v[@var{level}]
+@itemx --verbose[=@var{level}]
+Set verbosity level. The higher the level is, the more debugging
+information will be output during execution. Default @var{level}
+is 100, which means the highest debugging level.
+
+@item -h
+@itemx --help
+Display short help message and exit.
+
+@item -V
+@itemx --version
+Display information about the program's name, version, origin and legal
+status, all on standard output, and then exit successfully.
+@end table
+
+You should start the restore script with the media containing the
+first volume of the archive mounted. The script will prompt for other
+volumes as they are needed. If the archive is on tape, you don't need
+to rewind the tape to to its beginning---if the tape head is
+positioned past the beginning of the archive, the script will rewind
+the tape as needed. @xref{Tape Positioning}, for a discussion of tape
+positioning.
+
+@quotation
+@strong{Warning:} The script will delete files from the active file
+system if they were not in the file system when the archive was made.
+@end quotation
+
+@xref{Incremental Dumps}, for an explanation of how the script makes
+that determination.
+
+@node Choosing
+@chapter Choosing Files and Names for @command{tar}
+
+Certain options to @command{tar} enable you to specify a name for your
+archive. Other options let you decide which files to include or exclude
+from the archive, based on when or whether files were modified, whether
+the file names do or don't match specified patterns, or whether files
+are in specified directories.
+
+This chapter discusses these options in detail.
+
+@menu
+* file:: Choosing the Archive's Name
+* Selecting Archive Members::
+* files:: Reading Names from a File
+* exclude:: Excluding Some Files
+* wildcards:: Wildcards Patterns and Matching
+* quoting styles:: Ways of Quoting Special Characters in Names
+* transform:: Modifying File and Member Names
+* after:: Operating Only on New Files
+* recurse:: Descending into Directories
+* one:: Crossing File System Boundaries
+@end menu
+
+@node file
+@section Choosing and Naming Archive Files
+
+@cindex Naming an archive
+@cindex Archive Name
+@cindex Choosing an archive file
+@cindex Where is the archive?
+@opindex file
+By default, @command{tar} uses an archive file name that was compiled when
+it was built on the system; usually this name refers to some physical
+tape drive on the machine. However, the person who installed @command{tar}
+on the system may not have set the default to a meaningful value as far as
+most users are concerned. As a result, you will usually want to tell
+@command{tar} where to find (or create) the archive. The
+@option{--file=@var{archive-name}} (@option{-f @var{archive-name}})
+option allows you to either specify or name a file to use as the archive
+instead of the default archive file location.
+
+@table @option
+@xopindex{file, short description}
+@item --file=@var{archive-name}
+@itemx -f @var{archive-name}
+Name the archive to create or operate on. Use in conjunction with
+any operation.
+@end table
+
+For example, in this @command{tar} command,
+
+@smallexample
+$ @kbd{tar -cvf collection.tar blues folk jazz}
+@end smallexample
+
+@noindent
+@file{collection.tar} is the name of the archive. It must directly
+follow the @option{-f} option, since whatever directly follows @option{-f}
+@emph{will} end up naming the archive. If you neglect to specify an
+archive name, you may end up overwriting a file in the working directory
+with the archive you create since @command{tar} will use this file's name
+for the archive name.
+
+An archive can be saved as a file in the file system, sent through a
+pipe or over a network, or written to an I/O device such as a tape,
+floppy disk, or CD write drive.
+
+@cindex Writing new archives
+@cindex Archive creation
+If you do not name the archive, @command{tar} uses the value of the
+environment variable @env{TAPE} as the file name for the archive. If
+that is not available, @command{tar} uses a default, compiled-in archive
+name, usually that for tape unit zero (i.e., @file{/dev/tu00}).
+
+@cindex Standard input and output
+@cindex tar to standard input and output
+If you use @file{-} as an @var{archive-name}, @command{tar} reads the
+archive from standard input (when listing or extracting files), or
+writes it to standard output (when creating an archive). If you use
+@file{-} as an @var{archive-name} when modifying an archive,
+@command{tar} reads the original archive from its standard input and
+writes the entire new archive to its standard output.
+
+The following example is a convenient way of copying directory
+hierarchy from @file{sourcedir} to @file{targetdir}.
+
+@smallexample
+$ @kbd{(cd sourcedir; tar -cf - .) | (cd targetdir; tar -xpf -)}
+@end smallexample
+
+The @option{-C} option allows to avoid using subshells:
+
+@smallexample
+$ @kbd{tar -C sourcedir -cf - . | tar -C targetdir -xpf -}
+@end smallexample
+
+In both examples above, the leftmost @command{tar} invocation archives
+the contents of @file{sourcedir} to the standard output, while the
+rightmost one reads this archive from its standard input and
+extracts it. The @option{-p} option tells it to restore permissions
+of the extracted files.
+
+@cindex Remote devices
+@cindex tar to a remote device
+@anchor{remote-dev}
+To specify an archive file on a device attached to a remote machine,
+use the following:
+
+@smallexample
+@kbd{--file=@var{hostname}:/@var{dev}/@var{file-name}}
+@end smallexample
+
+@noindent
+@command{tar} will set up the remote connection, if possible, and
+prompt you for a username and password. If you use
+@option{--file=@@@var{hostname}:/@var{dev}/@var{file-name}}, @command{tar}
+will attempt to set up the remote connection using your username
+as the username on the remote machine.
+
+@cindex Local and remote archives
+@anchor{local and remote archives}
+If the archive file name includes a colon (@samp{:}), then it is assumed
+to be a file on another machine. If the archive file is
+@samp{@var{user}@@@var{host}:@var{file}}, then @var{file} is used on the
+host @var{host}. The remote host is accessed using the @command{rsh}
+program, with a username of @var{user}. If the username is omitted
+(along with the @samp{@@} sign), then your user name will be used.
+(This is the normal @command{rsh} behavior.) It is necessary for the
+remote machine, in addition to permitting your @command{rsh} access, to
+have the @file{rmt} program installed (this command is included in
+the @GNUTAR{} distribution and by default is installed under
+@file{@var{prefix}/libexec/rmt}, where @var{prefix} means your
+installation prefix). If you need to use a file whose name includes a
+colon, then the remote tape drive behavior
+can be inhibited by using the @option{--force-local} option.
+
+When the archive is being created to @file{/dev/null}, @GNUTAR{}
+tries to minimize input and output operations. The Amanda backup
+system, when used with @GNUTAR{}, has an initial sizing pass which
+uses this feature.
+
+@node Selecting Archive Members
+@section Selecting Archive Members
+@cindex Specifying files to act on
+@cindex Specifying archive members
+
+@dfn{File Name arguments} specify which files in the file system
+@command{tar} operates on, when creating or adding to an archive, or which
+archive members @command{tar} operates on, when reading or deleting from
+an archive. @xref{Operations}.
+
+To specify file names, you can include them as the last arguments on
+the command line, as follows:
+@smallexample
+@kbd{tar} @var{operation} [@var{option1} @var{option2} @dots{}] [@var{file name-1} @var{file name-2} @dots{}]
+@end smallexample
+
+If a file name begins with dash (@samp{-}), precede it with
+@option{--add-file} option to prevent it from being treated as an
+option.
+
+@anchor{input name quoting}
+By default @GNUTAR{} attempts to @dfn{unquote} each file or member
+name, replacing @dfn{escape sequences} according to the following
+table:
+
+@multitable @columnfractions 0.20 0.60
+@headitem Escape @tab Replaced with
+@item \a @tab Audible bell (@acronym{ASCII} 7)
+@item \b @tab Backspace (@acronym{ASCII} 8)
+@item \f @tab Form feed (@acronym{ASCII} 12)
+@item \n @tab New line (@acronym{ASCII} 10)
+@item \r @tab Carriage return (@acronym{ASCII} 13)
+@item \t @tab Horizontal tabulation (@acronym{ASCII} 9)
+@item \v @tab Vertical tabulation (@acronym{ASCII} 11)
+@item \? @tab @acronym{ASCII} 127
+@item \@var{n} @tab @acronym{ASCII} @var{n} (@var{n} should be an octal number
+ of up to 3 digits)
+@end multitable
+
+A backslash followed by any other symbol is retained.
+
+This default behavior is controlled by the following command line
+option:
+
+@table @option
+@opindex unquote
+@item --unquote
+Enable unquoting input file or member names (default).
+
+@opindex no-unquote
+@item --no-unquote
+Disable unquoting input file or member names.
+@end table
+
+If you specify a directory name as a file name argument, all the files
+in that directory are operated on by @command{tar}.
+
+If you do not specify files, @command{tar} behavior differs depending
+on the operation mode as described below:
+
+When @command{tar} is invoked with @option{--create} (@option{-c}),
+@command{tar} will stop immediately, reporting the following:
+
+@smallexample
+@group
+$ @kbd{tar cf a.tar}
+tar: Cowardly refusing to create an empty archive
+Try 'tar --help' or 'tar --usage' for more information.
+@end group
+@end smallexample
+
+If you specify either @option{--list} (@option{-t}) or
+@option{--extract} (@option{--get}, @option{-x}), @command{tar}
+operates on all the archive members in the archive.
+
+If run with @option{--diff} option, tar will compare the archive with
+the contents of the current working directory.
+
+If you specify any other operation, @command{tar} does nothing.
+
+By default, @command{tar} takes file names from the command line. However,
+there are other ways to specify file or member names, or to modify the
+manner in which @command{tar} selects the files or members upon which to
+operate. In general, these methods work both for specifying the names
+of files and archive members.
+
+@node files
+@section Reading Names from a File
+
+@cindex Reading file names from a file
+@cindex Lists of file names
+@cindex File Name arguments, alternatives
+@cindex @command{find}, using with @command{tar}
+Instead of giving the names of files or archive members on the command
+line, you can put the names into a file, and then use the
+@option{--files-from=@var{file-of-names}} (@option{-T
+@var{file-of-names}}) option to @command{tar}. Give the name of the
+file which contains the list of files to include as the argument to
+@option{--files-from}. In the list, the file names should be separated by
+newlines. You will frequently use this option when you have generated
+the list of files to archive with the @command{find} utility.
+
+@table @option
+@opindex files-from
+@item --files-from=@var{file-name}
+@itemx -T @var{file-name}
+Get names to extract or create from file @var{file-name}.
+@end table
+
+If you give a single dash as a file name for @option{--files-from}, (i.e.,
+you specify either @code{--files-from=-} or @code{-T -}), then the file
+names are read from standard input.
+
+Unless you are running @command{tar} with @option{--create}, you cannot use
+both @code{--files-from=-} and @code{--file=-} (@code{-f -}) in the same
+command.
+
+Any number of @option{-T} options can be given in the command line.
+
+The following example shows how to use @command{find} to generate a list of
+files smaller than 400K in length and put that list into a file
+called @file{small-files}. You can then use the @option{-T} option to
+@command{tar} to specify the files from that file, @file{small-files}, to
+create the archive @file{little.tgz}. (The @option{-z} option to
+@command{tar} compresses the archive with @command{gzip}; @pxref{gzip} for
+more information.)
+
+@smallexample
+$ @kbd{find . -size -400 -print > small-files}
+$ @kbd{tar -c -v -z -T small-files -f little.tgz}
+@end smallexample
+
+@noindent
+By default, each line read from the file list is first stripped off
+any leading and trailing whitespace. If the resulting string begins
+with @samp{-} character, it is considered a @command{tar} option and is
+processed accordingly@footnote{Versions of @GNUTAR{} up to 1.15.1
+recognized only @option{-C} option in file lists, and only if the
+option and its argument occupied two consecutive lines.}. For example,
+the common use of this feature is to change to another directory by
+specifying @option{-C} option:
+
+@smallexample
+@group
+$ @kbd{cat list}
+-C/etc
+passwd
+hosts
+-C/lib
+libc.a
+$ @kbd{tar -c -f foo.tar --files-from list}
+@end group
+@end smallexample
+
+@noindent
+In this example, @command{tar} will first switch to @file{/etc}
+directory and add files @file{passwd} and @file{hosts} to the
+archive. Then it will change to @file{/lib} directory and will archive
+the file @file{libc.a}. Thus, the resulting archive @file{foo.tar} will
+contain:
+
+@smallexample
+@group
+$ @kbd{tar tf foo.tar}
+passwd
+hosts
+libc.a
+@end group
+@end smallexample
+
+Note, that any options used in the file list remain in effect for the
+rest of the command line. For example, using the same @file{list}
+file as above, the following command
+
+@smallexample
+$ @kbd{tar -c -f foo.tar --files-from list libcurses.a}
+@end smallexample
+
+@noindent
+will look for file @file{libcurses.a} in the directory @file{/lib},
+because it was used with the last @option{-C} option
+(@pxref{Position-Sensitive Options}).
+
+@anchor{verbatim-files-from}
+@opindex verbatim-files-from
+If such option handling is undesirable, use the
+@option{--verbatim-files-from} option. When this option is in effect,
+each line read from the file list is treated as a file name. Notice,
+that this means, in particular, that no whitespace trimming is
+performed.
+
+@anchor{no-verbatim-files-from}
+@opindex no-verbatim-files-from
+The @option{--verbatim-files-from} affects all @option{-T} options
+that follow it in the command line. The default behavior can be
+restored using @option{--no-verbatim-files-from} option.
+
+@opindex add-file
+To disable option handling for a single file name, use the
+@option{--add-file} option, e.g.: @code{--add-file=--my-file}.
+
+You can use any @GNUTAR{} command line options in the file list file,
+including @option{--files-from} option itself. This allows for
+including contents of a file list into another file list file.
+Note however, that options that control file list processing, such as
+@option{--verbatim-files-from} or @option{--null} won't affect the
+file they appear in. They will affect next @option{--files-from}
+option, if there is any.
+
+@menu
+* nul::
+@end menu
+
+@node nul
+@subsection @code{NUL}-Terminated File Names
+
+@cindex File names, terminated by @code{NUL}
+@cindex @code{NUL}-terminated file names
+The @option{--null} option causes
+@option{--files-from=@var{file-of-names}} (@option{-T @var{file-of-names}})
+to read file names terminated by a @code{NUL} instead of a newline, so
+files whose names contain newlines can be archived using
+@option{--files-from}.
+
+@table @option
+@xopindex{null, described}
+@item --null
+Only consider @code{NUL}-terminated file names, instead of files that
+terminate in a newline.
+
+@xopindex{no-null, described}
+@item --no-null
+Undo the effect of any previous @option{--null} option.
+@end table
+
+The @option{--null} option is just like the one in @acronym{GNU}
+@command{xargs} and @command{cpio}, and is useful with the
+@option{-print0} predicate of @acronym{GNU} @command{find}. In
+@command{tar}, @option{--null} also disables special handling for
+file names that begin with dash (similar to
+@option{--verbatim-files-from} option).
+
+This example shows how to use @command{find} to generate a list of files
+larger than 800K in length and put that list into a file called
+@file{long-files}. The @option{-print0} option to @command{find} is just
+like @option{-print}, except that it separates files with a @code{NUL}
+rather than with a newline. You can then run @command{tar} with both the
+@option{--null} and @option{-T} options to specify that @command{tar} gets the
+files from that file, @file{long-files}, to create the archive
+@file{big.tgz}. The @option{--null} option to @command{tar} will cause
+@command{tar} to recognize the @code{NUL} separator between files.
+
+@smallexample
+$ @kbd{find . -size +800 -print0 > long-files}
+$ @kbd{tar -c -v --null --files-from=long-files --file=big.tar}
+@end smallexample
+
+The @option{--no-null} option can be used if you need to read both
+@code{NUL}-terminated and newline-terminated files on the same command line.
+For example, if @file{flist} is a newline-terminated file, then the
+following command can be used to combine it with the above command:
+
+@smallexample
+@group
+$ @kbd{find . -size +800 -print0 |
+ tar -c -f big.tar --null -T - --no-null -T flist}
+@end group
+@end smallexample
+
+This example uses short options for typographic reasons, to avoid
+very long lines.
+
+@GNUTAR is tries to automatically detect @code{NUL}-terminated file
+lists, so in many cases it is safe to use them even without the
+@option{--null} option. In this case @command{tar} will print a
+warning and continue reading such a file as if @option{--null} were
+actually given:
+
+@smallexample
+@group
+$ @kbd{find . -size +800 -print0 | tar -c -f big.tar -T -}
+tar: -: file name read contains nul character
+@end group
+@end smallexample
+
+The null terminator, however, remains in effect only for this
+particular file, any following @option{-T} options will assume
+newline termination. Of course, the null autodetection applies
+to these eventual surplus @option{-T} options as well.
+
+@node exclude
+@section Excluding Some Files
+
+@cindex File names, excluding files by
+@cindex Excluding files by name and pattern
+@cindex Excluding files by file system
+@opindex exclude
+@opindex exclude-from
+To avoid operating on files whose names match a particular pattern,
+use the @option{--exclude} or @option{--exclude-from} options.
+
+@table @option
+@opindex exclude
+@item --exclude=@var{pattern}
+Causes @command{tar} to ignore files that match the @var{pattern}.
+@end table
+
+@findex exclude
+The @option{--exclude=@var{pattern}} option prevents any file or
+member whose name matches the shell wildcard (@var{pattern}) from
+being operated on.
+For example, to create an archive with all the contents of the directory
+@file{src} except for files whose names end in @file{.o}, use the
+command @samp{tar -cf src.tar --exclude='*.o' src}.
+
+You may give multiple @option{--exclude} options.
+
+@table @option
+@opindex exclude-from
+@item --exclude-from=@var{file}
+@itemx -X @var{file}
+Causes @command{tar} to ignore files that match the patterns listed in
+@var{file}.
+@end table
+
+@findex exclude-from
+Use the @option{--exclude-from} option to read a
+list of patterns, one per line, from @var{file}; @command{tar} will
+ignore files matching those patterns. Thus if @command{tar} is
+called as @w{@samp{tar -c -X foo .}} and the file @file{foo} contains a
+single line @file{*.o}, no files whose names end in @file{.o} will be
+added to the archive.
+
+Notice, that lines from @var{file} are read verbatim. One of the
+frequent errors is leaving some extra whitespace after a file name,
+which is difficult to catch using text editors.
+
+However, empty lines are OK.
+
+@cindex VCS, excluding patterns from ignore files
+@cindex VCS, ignore files
+@cindex CVS, ignore files
+@cindex Git, ignore files
+@cindex Bazaar, ignore files
+@cindex Mercurial, ignore files
+When archiving directories that are under some version control system (VCS),
+it is often convenient to read exclusion patterns from this VCS'
+ignore files (e.g. @file{.cvsignore}, @file{.gitignore}, etc.) The
+following options provide such possibility:
+
+@table @option
+@anchor{exclude-vcs-ignores}
+@opindex exclude-vcs-ignores
+@item --exclude-vcs-ignores
+Before archiving a directory, see if it contains any of the following
+files: @file{cvsignore}, @file{.gitignore}, @file{.bzrignore}, or
+@file{.hgignore}. If so, read ignore patterns from these files.
+
+The patterns are treated much as the corresponding VCS would treat
+them, i.e.:
+
+@table @file
+@findex .cvsignore
+@item .cvsignore
+Contains shell-style globbing patterns that apply only to the
+directory where this file resides. No comments are allowed in the
+file. Empty lines are ignored.
+
+@findex .gitignore
+@item .gitignore
+Contains shell-style globbing patterns. Applies to the directory
+where @file{.gitfile} is located and all its subdirectories.
+
+Any line beginning with a @samp{#} is a comment. Backslash escapes
+the comment character.
+
+@findex .bzrignore
+@item .bzrignore
+Contains shell globbing-patterns and regular expressions (if prefixed
+with @samp{RE:}@footnote{According to the Bazaar docs,
+globbing-patterns are Korn-shell style and regular expressions are
+perl-style. As of @GNUTAR{} version @value{VERSION}, these are
+treated as shell-style globs and posix extended regexps. This will be
+fixed in future releases.}. Patterns affect the directory and all its
+subdirectories.
+
+Any line beginning with a @samp{#} is a comment.
+
+@findex .hgignore
+@item .hgignore
+Contains posix regular expressions@footnote{Support for perl-style
+regexps will appear in future releases.}. The line @samp{syntax:
+glob} switches to shell globbing patterns. The line @samp{syntax:
+regexp} switches back. Comments begin with a @samp{#}. Patterns
+affect the directory and all its subdirectories.
+@end table
+
+@opindex exclude-ignore
+@item --exclude-ignore=@var{file}
+Before dumping a directory, @command{tar} checks if it contains
+@var{file}. If so, exclusion patterns are read from this file.
+The patterns affect only the directory itself.
+
+@opindex exclude-ignore-recursive
+@item --exclude-ignore-recursive=@var{file}
+Same as @option{--exclude-ignore}, except that the patterns read
+affect both the directory where @var{file} resides and all its
+subdirectories.
+@end table
+
+@table @option
+@cindex version control system, excluding files
+@cindex VCS, excluding files
+@cindex SCCS, excluding files
+@cindex RCS, excluding files
+@cindex CVS, excluding files
+@cindex SVN, excluding files
+@cindex git, excluding files
+@cindex Bazaar, excluding files
+@cindex Arch, excluding files
+@cindex Mercurial, excluding files
+@cindex Darcs, excluding files
+@anchor{exclude-vcs}
+@opindex exclude-vcs
+@item --exclude-vcs
+Exclude files and directories used by following version control
+systems: @samp{CVS}, @samp{RCS}, @samp{SCCS}, @samp{SVN}, @samp{Arch},
+@samp{Bazaar}, @samp{Mercurial}, and @samp{Darcs}.
+
+As of version @value{VERSION}, the following files are excluded:
+
+@itemize @bullet
+@item @file{CVS/}, and everything under it
+@item @file{RCS/}, and everything under it
+@item @file{SCCS/}, and everything under it
+@item @file{.git/}, and everything under it
+@item @file{.gitignore}
+@item @file{.gitmodules}
+@item @file{.gitattributes}
+@item @file{.cvsignore}
+@item @file{.svn/}, and everything under it
+@item @file{.arch-ids/}, and everything under it
+@item @file{@{arch@}/}, and everything under it
+@item @file{=RELEASE-ID}
+@item @file{=meta-update}
+@item @file{=update}
+@item @file{.bzr}
+@item @file{.bzrignore}
+@item @file{.bzrtags}
+@item @file{.hg}
+@item @file{.hgignore}
+@item @file{.hgrags}
+@item @file{_darcs}
+@end itemize
+
+@opindex exclude-backups
+@item --exclude-backups
+Exclude backup and lock files. This option causes exclusion of files
+that match the following shell globbing patterns:
+
+@table @asis
+@item .#*
+@item *~
+@item #*#
+@end table
+
+@end table
+
+@findex exclude-caches
+When creating an archive, the @option{--exclude-caches} option family
+causes @command{tar} to exclude all directories that contain a @dfn{cache
+directory tag}. A cache directory tag is a short file with the
+well-known name @file{CACHEDIR.TAG} and having a standard header
+specified in @url{http://www.brynosaurus.com/cachedir/spec.html}.
+Various applications write cache directory tags into directories they
+use to hold regenerable, non-precious data, so that such data can be
+more easily excluded from backups.
+
+There are three @samp{exclude-caches} options, each providing a different
+exclusion semantics:
+
+@table @option
+@opindex exclude-caches
+@item --exclude-caches
+Do not archive the contents of the directory, but archive the
+directory itself and the @file{CACHEDIR.TAG} file.
+
+@opindex exclude-caches-under
+@item --exclude-caches-under
+Do not archive the contents of the directory, nor the
+@file{CACHEDIR.TAG} file, archive only the directory itself.
+
+@opindex exclude-caches-all
+@item --exclude-caches-all
+Omit directories containing @file{CACHEDIR.TAG} file entirely.
+@end table
+
+@findex exclude-tag
+Another option family, @option{--exclude-tag}, provides a generalization of
+this concept. It takes a single argument, a file name to look for.
+Any directory that contains this file will be excluded from the dump.
+Similarly to @samp{exclude-caches}, there are three options in this
+option family:
+
+@table @option
+@opindex exclude-tag
+@item --exclude-tag=@var{file}
+Do not dump the contents of the directory, but dump the
+directory itself and the @var{file}.
+
+@opindex exclude-tag-under
+@item --exclude-tag-under=@var{file}
+Do not dump the contents of the directory, nor the
+@var{file}, archive only the directory itself.
+
+@opindex exclude-tag-all
+@item --exclude-tag-all=@var{file}
+Omit directories containing @var{file} file entirely.
+@end table
+
+Multiple @option{--exclude-tag*} options can be given.
+
+For example, given this directory:
+
+@smallexample
+@group
+$ @kbd{find dir}
+dir
+dir/blues
+dir/jazz
+dir/folk
+dir/folk/tagfile
+dir/folk/sanjuan
+dir/folk/trote
+@end group
+@end smallexample
+
+The @option{--exclude-tag} will produce the following:
+
+@smallexample
+$ @kbd{tar -cf archive.tar --exclude-tag=tagfile -v dir}
+dir/
+dir/blues
+dir/jazz
+dir/folk/
+tar: dir/folk/: contains a cache directory tag tagfile;
+ contents not dumped
+dir/folk/tagfile
+@end smallexample
+
+Both the @file{dir/folk} directory and its tagfile are preserved in
+the archive, however the rest of files in this directory are not.
+
+Now, using the @option{--exclude-tag-under} option will exclude
+@file{tagfile} from the dump, while still preserving the directory
+itself, as shown in this example:
+
+@smallexample
+$ @kbd{tar -cf archive.tar --exclude-tag-under=tagfile -v dir}
+dir/
+dir/blues
+dir/jazz
+dir/folk/
+./tar: dir/folk/: contains a cache directory tag tagfile;
+ contents not dumped
+@end smallexample
+
+Finally, using @option{--exclude-tag-all} omits the @file{dir/folk}
+directory entirely:
+
+@smallexample
+$ @kbd{tar -cf archive.tar --exclude-tag-all=tagfile -v dir}
+dir/
+dir/blues
+dir/jazz
+./tar: dir/folk/: contains a cache directory tag tagfile;
+ directory not dumped
+@end smallexample
+
+@menu
+* problems with exclude::
+@end menu
+
+@node problems with exclude
+@unnumberedsubsec Problems with Using the @code{exclude} Options
+
+@xopindex{exclude, potential problems with}
+Some users find @samp{exclude} options confusing. Here are some common
+pitfalls:
+
+@itemize @bullet
+@item
+The main operating mode of @command{tar} does not act on a file name
+explicitly listed on the command line, if one of its file name
+components is excluded. In the example above, if
+you create an archive and exclude files that end with @samp{*.o}, but
+explicitly name the file @samp{dir.o/foo} after all the options have been
+listed, @samp{dir.o/foo} will be excluded from the archive.
+
+@item
+You can sometimes confuse the meanings of @option{--exclude} and
+@option{--exclude-from}. Be careful: use @option{--exclude} when files
+to be excluded are given as a pattern on the command line. Use
+@option{--exclude-from} to introduce the name of a file which contains
+a list of patterns, one per line; each of these patterns can exclude
+zero, one, or many files.
+
+@item
+When you use @option{--exclude=@var{pattern}}, be sure to quote the
+@var{pattern} parameter, so @GNUTAR{} sees wildcard characters
+like @samp{*}. If you do not do this, the shell might expand the
+@samp{*} itself using files at hand, so @command{tar} might receive a
+list of files instead of one pattern, or none at all, making the
+command somewhat illegal. This might not correspond to what you want.
+
+For example, write:
+
+@smallexample
+$ @kbd{tar -c -f @var{archive.tar} --exclude '*.o' @var{directory}}
+@end smallexample
+
+@noindent
+rather than:
+
+@smallexample
+# @emph{Wrong!}
+$ @kbd{tar -c -f @var{archive.tar} --exclude *.o @var{directory}}
+@end smallexample
+
+@item
+You must use use shell syntax, or globbing, rather than @code{regexp}
+syntax, when using exclude options in @command{tar}. If you try to use
+@code{regexp} syntax to describe files to be excluded, your command
+might fail.
+
+@item
+@FIXME{The change in semantics must have occurred before 1.11,
+so I doubt if it is worth mentioning at all. Anyway, should at
+least specify in which version the semantics changed.}
+In earlier versions of @command{tar}, what is now the
+@option{--exclude-from} option was called @option{--exclude} instead.
+Now, @option{--exclude} applies to patterns listed on the command
+line and @option{--exclude-from} applies to patterns listed in a
+file.
+
+@end itemize
+
+@node wildcards
+@section Wildcards Patterns and Matching
+
+@dfn{Globbing} is the operation by which @dfn{wildcard} characters,
+@samp{*} or @samp{?} for example, are replaced and expanded into all
+existing files matching the given pattern. @GNUTAR{} can use wildcard
+patterns for matching (or globbing) archive members when extracting
+from or listing an archive. Wildcard patterns are also used for
+verifying volume labels of @command{tar} archives. This section has the
+purpose of explaining wildcard syntax for @command{tar}.
+
+@FIXME{the next few paragraphs need work.}
+
+A @var{pattern} should be written according to shell syntax, using wildcard
+characters to effect globbing. Most characters in the pattern stand
+for themselves in the matched string, and case is significant: @samp{a}
+will match only @samp{a}, and not @samp{A}. The character @samp{?} in the
+pattern matches any single character in the matched string. The character
+@samp{*} in the pattern matches zero, one, or more single characters in
+the matched string. The character @samp{\} says to take the following
+character of the pattern @emph{literally}; it is useful when one needs to
+match the @samp{?}, @samp{*}, @samp{[} or @samp{\} characters, themselves.
+
+The character @samp{[}, up to the matching @samp{]}, introduces a character
+class. A @dfn{character class} is a list of acceptable characters
+for the next single character of the matched string. For example,
+@samp{[abcde]} would match any of the first five letters of the alphabet.
+Note that within a character class, all of the ``special characters''
+listed above other than @samp{\} lose their special meaning; for example,
+@samp{[-\\[*?]]} would match any of the characters, @samp{-}, @samp{\},
+@samp{[}, @samp{*}, @samp{?}, or @samp{]}. (Due to parsing constraints,
+the characters @samp{-} and @samp{]} must either come @emph{first} or
+@emph{last} in a character class.)
+
+@cindex Excluding characters from a character class
+@cindex Character class, excluding characters from
+If the first character of the class after the opening @samp{[}
+is @samp{!} or @samp{^}, then the meaning of the class is reversed.
+Rather than listing character to match, it lists those characters which
+are @emph{forbidden} as the next single character of the matched string.
+
+Other characters of the class stand for themselves. The special
+construction @samp{[@var{a}-@var{e}]}, using an hyphen between two
+letters, is meant to represent all characters between @var{a} and
+@var{e}, inclusive.
+
+@FIXME{need to add a sentence or so here to make this clear for those
+who don't have dan around.}
+
+Periods (@samp{.}) or forward slashes (@samp{/}) are not considered
+special for wildcard matches. However, if a pattern completely matches
+a directory prefix of a matched string, then it matches the full matched
+string: thus, excluding a directory also excludes all the files beneath it.
+
+@menu
+* controlling pattern-matching::
+@end menu
+
+@node controlling pattern-matching
+@unnumberedsubsec Controlling Pattern-Matching
+
+For the purposes of this section, we call @dfn{exclusion members} all
+member names obtained while processing @option{--exclude} and
+@option{--exclude-from} options, and @dfn{inclusion members} those
+member names that were given in the command line or read from the file
+specified with @option{--files-from} option.
+
+These two pairs of member lists are used in the following operations:
+@option{--diff}, @option{--extract}, @option{--list},
+@option{--update}.
+
+There are no inclusion members in create mode (@option{--create} and
+@option{--append}), since in this mode the names obtained from the
+command line refer to @emph{files}, not archive members.
+
+By default, inclusion members are compared with archive members
+literally @footnote{Notice that earlier @GNUTAR{} versions used
+globbing for inclusion members, which contradicted to UNIX98
+specification and was not documented. @xref{Changes}, for more
+information on this and other changes.} and exclusion members are
+treated as globbing patterns. For example:
+
+@smallexample
+@group
+$ @kbd{tar tf foo.tar}
+a.c
+b.c
+a.txt
+[remarks]
+# @i{Member names are used verbatim:}
+$ @kbd{tar -xf foo.tar -v '[remarks]'}
+[remarks]
+# @i{Exclude member names are globbed:}
+$ @kbd{tar -xf foo.tar -v --exclude '*.c'}
+a.txt
+[remarks]
+@end group
+@end smallexample
+
+This behavior can be altered by using the following options:
+
+@table @option
+@opindex wildcards
+@item --wildcards
+Treat all member names as wildcards.
+
+@opindex no-wildcards
+@item --no-wildcards
+Treat all member names as literal strings.
+@end table
+
+Thus, to extract files whose names end in @samp{.c}, you can use:
+
+@smallexample
+$ @kbd{tar -xf foo.tar -v --wildcards '*.c'}
+a.c
+b.c
+@end smallexample
+
+@noindent
+Notice quoting of the pattern to prevent the shell from interpreting
+it.
+
+The effect of @option{--wildcards} option is canceled by
+@option{--no-wildcards}. This can be used to pass part of
+the command line arguments verbatim and other part as globbing
+patterns. For example, the following invocation:
+
+@smallexample
+$ @kbd{tar -xf foo.tar --wildcards '*.txt' --no-wildcards '[remarks]'}
+@end smallexample
+
+@noindent
+instructs @command{tar} to extract from @file{foo.tar} all files whose
+names end in @samp{.txt} and the file named @file{[remarks]}.
+
+Normally, a pattern matches a name if an initial subsequence of the
+name's components matches the pattern, where @samp{*}, @samp{?}, and
+@samp{[...]} are the usual shell wildcards, @samp{\} escapes wildcards,
+and wildcards can match @samp{/}.
+
+Other than optionally stripping leading @samp{/} from names
+(@pxref{absolute}), patterns and names are used as-is. For
+example, trailing @samp{/} is not trimmed from a user-specified name
+before deciding whether to exclude it.
+
+However, this matching procedure can be altered by the options listed
+below. These options accumulate. For example:
+
+@smallexample
+--ignore-case --exclude='makefile' --no-ignore-case ---exclude='readme'
+@end smallexample
+
+@noindent
+ignores case when excluding @samp{makefile}, but not when excluding
+@samp{readme}.
+
+@table @option
+@anchor{anchored patterns}
+@opindex anchored
+@opindex no-anchored
+@item --anchored
+@itemx --no-anchored
+If anchored, a pattern must match an initial subsequence
+of the name's components. Otherwise, the pattern can match any
+subsequence. Default is @option{--no-anchored} for exclusion members
+and @option{--anchored} inclusion members.
+
+@anchor{case-insensitive matches}
+@opindex ignore-case
+@opindex no-ignore-case
+@item --ignore-case
+@itemx --no-ignore-case
+When ignoring case, upper-case patterns match lower-case names and vice versa.
+When not ignoring case (the default), matching is case-sensitive.
+
+@opindex wildcards-match-slash
+@opindex no-wildcards-match-slash
+@item --wildcards-match-slash
+@itemx --no-wildcards-match-slash
+When wildcards match slash (the default for exclusion members), a
+wildcard like @samp{*} in the pattern can match a @samp{/} in the
+name. Otherwise, @samp{/} is matched only by @samp{/}.
+
+@end table
+
+The @option{--recursion} and @option{--no-recursion} options
+(@pxref{recurse}) also affect how member patterns are interpreted. If
+recursion is in effect, a pattern matches a name if it matches any of
+the name's parent directories.
+
+The following table summarizes pattern-matching default values:
+
+@multitable @columnfractions .3 .7
+@headitem Members @tab Default settings
+@item Inclusion @tab @option{--no-wildcards --anchored --no-wildcards-match-slash}
+@item Exclusion @tab @option{--wildcards --no-anchored --wildcards-match-slash}
+@end multitable
+
+@node quoting styles
+@section Quoting Member Names
+
+When displaying member names, @command{tar} takes care to avoid
+ambiguities caused by certain characters. This is called @dfn{name
+quoting}. The characters in question are:
+
+@itemize @bullet
+@item Non-printable control characters:
+@anchor{escape sequences}
+@multitable @columnfractions 0.20 0.10 0.60
+@headitem Character @tab @acronym{ASCII} @tab Character name
+@item \a @tab 7 @tab Audible bell
+@item \b @tab 8 @tab Backspace
+@item \f @tab 12 @tab Form feed
+@item \n @tab 10 @tab New line
+@item \r @tab 13 @tab Carriage return
+@item \t @tab 9 @tab Horizontal tabulation
+@item \v @tab 11 @tab Vertical tabulation
+@end multitable
+
+@item Space (@acronym{ASCII} 32)
+
+@item Single and double quotes (@samp{'} and @samp{"})
+
+@item Backslash (@samp{\})
+@end itemize
+
+The exact way @command{tar} uses to quote these characters depends on
+the @dfn{quoting style}. The default quoting style, called
+@dfn{escape} (see below), uses backslash notation to represent control
+characters, space and backslash. Using this quoting style, control
+characters are represented as listed in column @samp{Character} in the
+above table, a space is printed as @samp{\ } and a backslash as @samp{\\}.
+
+@GNUTAR{} offers seven distinct quoting styles, which can be selected
+using @option{--quoting-style} option:
+
+@table @option
+@item --quoting-style=@var{style}
+@opindex quoting-style
+
+Sets quoting style. Valid values for @var{style} argument are:
+literal, shell, shell-always, c, escape, locale, clocale.
+@end table
+
+These styles are described in detail below. To illustrate their
+effect, we will use an imaginary tar archive @file{arch.tar}
+containing the following members:
+
+@smallexample
+@group
+# 1. Contains horizontal tabulation character.
+a tab
+# 2. Contains newline character
+a
+newline
+# 3. Contains a space
+a space
+# 4. Contains double quotes
+a"double"quote
+# 5. Contains single quotes
+a'single'quote
+# 6. Contains a backslash character:
+a\backslash
+@end group
+@end smallexample
+
+Here is how usual @command{ls} command would have listed them, if they
+had existed in the current working directory:
+
+@smallexample
+@group
+$ @kbd{ls}
+a\ttab
+a\nnewline
+a\ space
+a"double"quote
+a'single'quote
+a\\backslash
+@end group
+@end smallexample
+
+Quoting styles:
+
+@table @samp
+@item literal
+No quoting, display each character as is:
+
+@smallexample
+@group
+$ @kbd{tar tf arch.tar --quoting-style=literal}
+./
+./a space
+./a'single'quote
+./a"double"quote
+./a\backslash
+./a tab
+./a
+newline
+@end group
+@end smallexample
+
+@item shell
+Display characters the same way Bourne shell does:
+control characters, except @samp{\t} and @samp{\n}, are printed using
+backslash escapes, @samp{\t} and @samp{\n} are printed as is, and a
+single quote is printed as @samp{\'}. If a name contains any quoted
+characters, it is enclosed in single quotes. In particular, if a name
+contains single quotes, it is printed as several single-quoted strings:
+
+@smallexample
+@group
+$ @kbd{tar tf arch.tar --quoting-style=shell}
+./
+'./a space'
+'./a'\''single'\''quote'
+'./a"double"quote'
+'./a\backslash'
+'./a tab'
+'./a
+newline'
+@end group
+@end smallexample
+
+@item shell-always
+Same as @samp{shell}, but the names are always enclosed in single
+quotes:
+
+@smallexample
+@group
+$ @kbd{tar tf arch.tar --quoting-style=shell-always}
+'./'
+'./a space'
+'./a'\''single'\''quote'
+'./a"double"quote'
+'./a\backslash'
+'./a tab'
+'./a
+newline'
+@end group
+@end smallexample
+
+@item c
+Use the notation of the C programming language. All names are
+enclosed in double quotes. Control characters are quoted using
+backslash notations, double quotes are represented as @samp{\"},
+backslash characters are represented as @samp{\\}. Single quotes and
+spaces are not quoted:
+
+@smallexample
+@group
+$ @kbd{tar tf arch.tar --quoting-style=c}
+"./"
+"./a space"
+"./a'single'quote"
+"./a\"double\"quote"
+"./a\\backslash"
+"./a\ttab"
+"./a\nnewline"
+@end group
+@end smallexample
+
+@item escape
+Control characters are printed using backslash notation, a space is
+printed as @samp{\ } and a backslash as @samp{\\}. This is the
+default quoting style, unless it was changed when configured the
+package.
+
+@smallexample
+@group
+$ @kbd{tar tf arch.tar --quoting-style=escape}
+./
+./a space
+./a'single'quote
+./a"double"quote
+./a\\backslash
+./a\ttab
+./a\nnewline
+@end group
+@end smallexample
+
+@item locale
+Control characters, single quote and backslash are printed using
+backslash notation. All names are quoted using left and right
+quotation marks, appropriate to the current locale. If it does not
+define quotation marks, use @samp{'} as left and as right
+quotation marks. Any occurrences of the right quotation mark in a
+name are escaped with @samp{\}, for example:
+
+For example:
+
+@smallexample
+@group
+$ @kbd{tar tf arch.tar --quoting-style=locale}
+'./'
+'./a space'
+'./a\'single\'quote'
+'./a"double"quote'
+'./a\\backslash'
+'./a\ttab'
+'./a\nnewline'
+@end group
+@end smallexample
+
+@item clocale
+Same as @samp{locale}, but @samp{"} is used for both left and right
+quotation marks, if not provided by the currently selected locale:
+
+@smallexample
+@group
+$ @kbd{tar tf arch.tar --quoting-style=clocale}
+"./"
+"./a space"
+"./a'single'quote"
+"./a\"double\"quote"
+"./a\\backslash"
+"./a\ttab"
+"./a\nnewline"
+@end group
+@end smallexample
+@end table
+
+You can specify which characters should be quoted in addition to those
+implied by the current quoting style:
+
+@table @option
+@item --quote-chars=@var{string}
+Always quote characters from @var{string}, even if the selected
+quoting style would not quote them.
+@end table
+
+For example, using @samp{escape} quoting (compare with the usual
+escape listing above):
+
+@smallexample
+@group
+$ @kbd{tar tf arch.tar --quoting-style=escape --quote-chars=' "'}
+./
+./a\ space
+./a'single'quote
+./a\"double\"quote
+./a\\backslash
+./a\ttab
+./a\nnewline
+@end group
+@end smallexample
+
+To disable quoting of such additional characters, use the following
+option:
+
+@table @option
+@item --no-quote-chars=@var{string}
+Remove characters listed in @var{string} from the list of quoted
+characters set by the previous @option{--quote-chars} option.
+@end table
+
+This option is particularly useful if you have added
+@option{--quote-chars} to your @env{TAR_OPTIONS} (@pxref{TAR_OPTIONS})
+and wish to disable it for the current invocation.
+
+Note, that @option{--no-quote-chars} does @emph{not} disable those
+characters that are quoted by default in the selected quoting style.
+
+@node transform
+@section Modifying File and Member Names
+
+@command{Tar} archives contain detailed information about files stored
+in them and full file names are part of that information. When
+storing a file to an archive, its file name is recorded in it,
+along with the actual file contents. When restoring from an archive,
+a file is created on disk with exactly the same name as that stored
+in the archive. In the majority of cases this is the desired behavior
+of a file archiver. However, there are some cases when it is not.
+
+First of all, it is often unsafe to extract archive members with
+absolute file names or those that begin with a @file{../}. @GNUTAR{}
+takes special precautions when extracting such names and provides a
+special option for handling them, which is described in
+@ref{absolute}.
+
+Secondly, you may wish to extract file names without some leading
+directory components, or with otherwise modified names. In other
+cases it is desirable to store files under differing names in the
+archive.
+
+@GNUTAR{} provides several options for these needs.
+
+@table @option
+@opindex strip-components
+@item --strip-components=@var{number}
+Strip given @var{number} of leading components from file names before
+extraction.
+@end table
+
+For example, suppose you have archived whole @file{/usr} hierarchy to
+a tar archive named @file{usr.tar}. Among other files, this archive
+contains @file{usr/include/stdlib.h}, which you wish to extract to
+the current working directory. To do so, you type:
+
+@smallexample
+$ @kbd{tar -xf usr.tar --strip=2 usr/include/stdlib.h}
+@end smallexample
+
+The option @option{--strip=2} instructs @command{tar} to strip the
+two leading components (@file{usr/} and @file{include/}) off the file
+name.
+
+If you add the @option{--verbose} (@option{-v}) option to the invocation
+above, you will note that the verbose listing still contains the
+full file name, with the two removed components still in place. This
+can be inconvenient, so @command{tar} provides a special option for
+altering this behavior:
+
+@anchor{show-transformed-names}
+@table @option
+@opindex show-transformed-names
+@item --show-transformed-names
+Display file or member names with all requested transformations
+applied.
+@end table
+
+@noindent
+For example:
+
+@smallexample
+@group
+$ @kbd{tar -xf usr.tar -v --strip=2 usr/include/stdlib.h}
+usr/include/stdlib.h
+$ @kbd{tar -xf usr.tar -v --strip=2 --show-transformed usr/include/stdlib.h}
+stdlib.h
+@end group
+@end smallexample
+
+Notice that in both cases the file @file{stdlib.h} is extracted to the
+current working directory, @option{--show-transformed-names} affects
+only the way its name is displayed.
+
+This option is especially useful for verifying whether the invocation
+will have the desired effect. Thus, before running
+
+@smallexample
+$ @kbd{tar -x --strip=@var{n}}
+@end smallexample
+
+@noindent
+it is often advisable to run
+
+@smallexample
+$ @kbd{tar -t -v --show-transformed --strip=@var{n}}
+@end smallexample
+
+@noindent
+to make sure the command will produce the intended results.
+
+In case you need to apply more complex modifications to the file name,
+@GNUTAR{} provides a general-purpose transformation option:
+
+@table @option
+@opindex transform
+@opindex xform
+@item --transform=@var{expression}
+@itemx --xform=@var{expression}
+Modify file names using supplied @var{expression}.
+@end table
+
+@noindent
+The @var{expression} is a @command{sed}-like replace expression of the
+form:
+
+@smallexample
+s/@var{regexp}/@var{replace}/[@var{flags}]
+@end smallexample
+
+@noindent
+where @var{regexp} is a @dfn{regular expression}, @var{replace} is a
+replacement for each file name part that matches @var{regexp}. Both
+@var{regexp} and @var{replace} are described in detail in
+@ref{The "s" Command, The "s" Command, The `s' Command, sed, GNU sed}.
+
+Any delimiter can be used in lieu of @samp{/}, the only requirement being
+that it be used consistently throughout the expression. For example,
+the following two expressions are equivalent:
+
+@smallexample
+@group
+s/one/two/
+s,one,two,
+@end group
+@end smallexample
+
+Changing delimiters is often useful when the @var{regex} contains
+slashes. For example, it is more convenient to write @code{s,/,-,} than
+@code{s/\//-/}.
+
+As in @command{sed}, you can give several replace expressions,
+separated by a semicolon.
+
+Supported @var{flags} are:
+
+@table @samp
+@item g
+Apply the replacement to @emph{all} matches to the @var{regexp}, not
+just the first.
+
+@item i
+Use case-insensitive matching.
+
+@item x
+@var{regexp} is an @dfn{extended regular expression} (@pxref{Extended
+regexps, Extended regular expressions, Extended regular expressions,
+sed, GNU sed}).
+
+@item @var{number}
+Only replace the @var{number}th match of the @var{regexp}.
+
+Note: the @acronym{POSIX} standard does not specify what should happen
+when you mix the @samp{g} and @var{number} modifiers. @GNUTAR{}
+follows the GNU @command{sed} implementation in this regard, so
+the interaction is defined to be: ignore matches before the
+@var{number}th, and then match and replace all matches from the
+@var{number}th on.
+
+@end table
+
+In addition, several @dfn{transformation scope} flags are supported,
+that control to what files transformations apply. These are:
+
+@table @samp
+@item r
+Apply transformation to regular archive members.
+
+@item R
+Do not apply transformation to regular archive members.
+
+@item s
+Apply transformation to symbolic link targets.
+
+@item S
+Do not apply transformation to symbolic link targets.
+
+@item h
+Apply transformation to hard link targets.
+
+@item H
+Do not apply transformation to hard link targets.
+@end table
+
+Default is @samp{rsh}, which means to apply transformations to both archive
+members and targets of symbolic and hard links.
+
+Default scope flags can also be changed using @samp{flags=} statement
+in the transform expression. The flags set this way remain in force
+until next @samp{flags=} statement or end of expression, whichever
+occurs first. For example:
+
+@smallexample
+ --transform 'flags=S;s|^|/usr/local/|'
+@end smallexample
+
+Here are several examples of @option{--transform} usage:
+
+@enumerate
+@item Extract @file{usr/} hierarchy into @file{usr/local/}:
+
+@smallexample
+$ @kbd{tar --transform='s,usr/,usr/local/,' -x -f arch.tar}
+@end smallexample
+
+@item Strip two leading directory components (equivalent to
+@option{--strip-components=2}):
+
+@smallexample
+$ @kbd{tar --transform='s,/*[^/]*/[^/]*/,,' -x -f arch.tar}
+@end smallexample
+
+@item Convert each file name to lower case:
+
+@smallexample
+$ @kbd{tar --transform 's/.*/\L&/' -x -f arch.tar}
+@end smallexample
+
+@item Prepend @file{/prefix/} to each file name:
+
+@smallexample
+$ @kbd{tar --transform 's,^,/prefix/,' -x -f arch.tar}
+@end smallexample
+
+@item Archive the @file{/lib} directory, prepending @samp{/usr/local}
+to each archive member:
+
+@smallexample
+$ @kbd{tar --transform 's,^,/usr/local/,S' -c -f arch.tar /lib}
+@end smallexample
+@end enumerate
+
+Notice the use of flags in the last example. The @file{/lib}
+directory often contains many symbolic links to files within it.
+It may look, for example, like this:
+
+@smallexample
+$ @kbd{ls -l}
+drwxr-xr-x root/root 0 2008-07-08 16:20 /lib/
+-rwxr-xr-x root/root 1250840 2008-05-25 07:44 /lib/libc-2.3.2.so
+lrwxrwxrwx root/root 0 2008-06-24 17:12 /lib/libc.so.6 -> libc-2.3.2.so
+...
+@end smallexample
+
+Using the expression @samp{s,^,/usr/local/,} would mean adding
+@samp{/usr/local} to both regular archive members and to link
+targets. In this case, @file{/lib/libc.so.6} would become:
+
+@smallexample
+ /usr/local/lib/libc.so.6 -> /usr/local/libc-2.3.2.so
+@end smallexample
+
+This is definitely not desired. To avoid this, the @samp{S} flag
+is used, which excludes symbolic link targets from filename
+transformations. The result is:
+
+@smallexample
+$ @kbd{tar --transform 's,^,/usr/local/,S', -c -v -f arch.tar \
+ --show-transformed /lib}
+drwxr-xr-x root/root 0 2008-07-08 16:20 /usr/local/lib/
+-rwxr-xr-x root/root 1250840 2008-05-25 07:44 /usr/local/lib/libc-2.3.2.so
+lrwxrwxrwx root/root 0 2008-06-24 17:12 /usr/local/lib/libc.so.6 \
+ -> libc-2.3.2.so
+@end smallexample
+
+Unlike @option{--strip-components}, @option{--transform} can be used
+in any @GNUTAR{} operation mode. For example, the following command
+adds files to the archive while replacing the leading @file{usr/}
+component with @file{var/}:
+
+@smallexample
+$ @kbd{tar -cf arch.tar --transform='s,^usr/,var/,' /}
+@end smallexample
+
+To test @option{--transform} effect we suggest using
+@option{--show-transformed-names} option:
+
+@smallexample
+$ @kbd{tar -cf arch.tar --transform='s,^usr/,var/,' \
+ --verbose --show-transformed-names /}
+@end smallexample
+
+If both @option{--strip-components} and @option{--transform} are used
+together, then @option{--transform} is applied first, and the required
+number of components is then stripped from its result.
+
+You can use as many @option{--transform} options in a single command
+line as you want. The specified expressions will then be applied in
+order of their appearance. For example, the following two invocations
+are equivalent:
+
+@smallexample
+$ @kbd{tar -cf arch.tar --transform='s,/usr/var,/var/' \
+ --transform='s,/usr/local,/usr/,'}
+$ @kbd{tar -cf arch.tar \
+ --transform='s,/usr/var,/var/;s,/usr/local,/usr/,'}
+@end smallexample
+
+@node after
+@section Operating Only on New Files
+
+@cindex Excluding file by age
+@cindex Data Modification time, excluding files by
+@cindex Modification time, excluding files by
+@cindex Age, excluding files by
+The @option{--after-date=@var{date}} (@option{--newer=@var{date}},
+@option{-N @var{date}}) option causes @command{tar} to only work on
+files whose data modification or status change times are newer than
+the @var{date} given. If @var{date} starts with @samp{/} or @samp{.},
+it is taken to be a file name; the data modification time of that file
+is used as the date. If you use this option when creating or appending
+to an archive, the archive will only include new files. If you use
+@option{--after-date} when extracting an archive, @command{tar} will
+only extract files newer than the @var{date} you specify.
+
+If you only want @command{tar} to make the date comparison based on
+modification of the file's data (rather than status
+changes), then use the @option{--newer-mtime=@var{date}} option.
+
+@cindex --after-date and --update compared
+@cindex --newer-mtime and --update compared
+You may use these options with any operation. Note that these options
+differ from the @option{--update} (@option{-u}) operation in that they
+allow you to specify a particular date against which @command{tar} can
+compare when deciding whether or not to archive the files.
+
+@table @option
+@opindex after-date
+@opindex newer
+@item --after-date=@var{date}
+@itemx --newer=@var{date}
+@itemx -N @var{date}
+Only store files newer than @var{date}.
+
+Acts on files only if their data modification or status change times are
+later than @var{date}. Use in conjunction with any operation.
+
+If @var{date} starts with @samp{/} or @samp{.}, it is taken to be a file
+name; the data modification time of that file is used as the date.
+
+@opindex newer-mtime
+@item --newer-mtime=@var{date}
+Acts like @option{--after-date}, but only looks at data modification times.
+@end table
+
+These options limit @command{tar} to operate only on files which have
+been modified after the date specified. A file's status is considered to have
+changed if its contents have been modified, or if its owner,
+permissions, and so forth, have been changed. (For more information on
+how to specify a date, see @ref{Date input formats}; remember that the
+entire date argument must be quoted if it contains any spaces.)
+
+Gurus would say that @option{--after-date} tests both the data
+modification time (@code{mtime}, the time the contents of the file
+were last modified) and the status change time (@code{ctime}, the time
+the file's status was last changed: owner, permissions, etc.@:)
+fields, while @option{--newer-mtime} tests only the @code{mtime}
+field.
+
+To be precise, @option{--after-date} checks @emph{both} @code{mtime} and
+@code{ctime} and processes the file if either one is more recent than
+@var{date}, while @option{--newer-mtime} only checks @code{mtime} and
+disregards @code{ctime}. Neither does it use @code{atime} (the last time the
+contents of the file were looked at).
+
+Date specifiers can have embedded spaces. Because of this, you may need
+to quote date arguments to keep the shell from parsing them as separate
+arguments. For example, the following command will add to the archive
+all the files modified less than two days ago:
+
+@smallexample
+$ @kbd{tar -cf foo.tar --newer-mtime '2 days ago'}
+@end smallexample
+
+When any of these options is used with the option @option{--verbose}
+(@pxref{verbose tutorial}) @GNUTAR{} will try to convert the specified
+date back to its textual representation and compare that with the
+one given with the option. If the two dates differ, @command{tar} will
+print a warning saying what date it will use. This is to help user
+ensure he is using the right date. For example:
+
+@smallexample
+@group
+$ @kbd{tar -c -f archive.tar --after-date='10 days ago' .}
+tar: Option --after-date: Treating date '10 days ago' as 2006-06-11
+13:19:37.232434
+@end group
+@end smallexample
+
+@quotation
+@strong{Please Note:} @option{--after-date} and @option{--newer-mtime}
+should not be used for incremental backups. @xref{Incremental Dumps},
+for proper way of creating incremental backups.
+@end quotation
+
+@node recurse
+@section Descending into Directories
+@cindex Avoiding recursion in directories
+@cindex Descending directories, avoiding
+@cindex Directories, avoiding recursion
+@cindex Recursion in directories, avoiding
+
+Usually, @command{tar} will recursively explore all directories (either
+those given on the command line or through the @option{--files-from}
+option) for the various files they contain. However, you may not always
+want @command{tar} to act this way.
+
+@opindex no-recursion
+@cindex @command{find}, using with @command{tar}
+The @option{--no-recursion} option inhibits @command{tar}'s recursive descent
+into specified directories. If you specify @option{--no-recursion}, you can
+use the @command{find} (@pxref{Top,, find, find, GNU Find Manual})
+utility for hunting through levels of directories to
+construct a list of file names which you could then pass to @command{tar}.
+@command{find} allows you to be more selective when choosing which files to
+archive; see @ref{files}, for more information on using @command{find} with
+@command{tar}.
+
+@table @option
+@item --no-recursion
+Prevents @command{tar} from recursively descending directories.
+
+@opindex recursion
+@item --recursion
+Requires @command{tar} to recursively descend directories.
+This is the default.
+@end table
+
+When you use @option{--no-recursion}, @GNUTAR{} grabs
+directory entries themselves, but does not descend on them
+recursively. Many people use @command{find} for locating files they
+want to back up, and since @command{tar} @emph{usually} recursively
+descends on directories, they have to use the @samp{@w{-not -type d}}
+test in their @command{find} invocation (@pxref{Type, Type, Type test,
+find, Finding Files}), as they usually do not want all the files in a
+directory. They then use the @option{--files-from} option to archive
+the files located via @command{find}.
+
+The problem when restoring files archived in this manner is that the
+directories themselves are not in the archive; so the
+@option{--same-permissions} (@option{--preserve-permissions},
+@option{-p}) option does not affect them---while users might really
+like it to. Specifying @option{--no-recursion} is a way to tell
+@command{tar} to grab only the directory entries given to it, adding
+no new files on its own. To summarize, if you use @command{find} to
+create a list of files to be stored in an archive, use it as follows:
+
+@smallexample
+@group
+$ @kbd{find @var{dir} @var{tests} | \
+ tar -cf @var{archive} -T - --no-recursion}
+@end group
+@end smallexample
+
+The @option{--no-recursion} option also applies when extracting: it
+causes @command{tar} to extract only the matched directory entries, not
+the files under those directories.
+
+The @option{--no-recursion} option also affects how globbing patterns
+are interpreted (@pxref{controlling pattern-matching}).
+
+The @option{--no-recursion} and @option{--recursion} options apply to
+later options and operands, and can be overridden by later occurrences
+of @option{--no-recursion} and @option{--recursion}. For example:
+
+@smallexample
+$ @kbd{tar -cf jams.tar --no-recursion grape --recursion grape/concord}
+@end smallexample
+
+@noindent
+creates an archive with one entry for @file{grape}, and the recursive
+contents of @file{grape/concord}, but no entries under @file{grape}
+other than @file{grape/concord}.
+
+@node one
+@section Crossing File System Boundaries
+@cindex File system boundaries, not crossing
+
+@command{tar} will normally automatically cross file system boundaries in
+order to archive files which are part of a directory tree. You can
+change this behavior by running @command{tar} and specifying
+@option{--one-file-system}. This option only affects files that are
+archived because they are in a directory that is being archived;
+@command{tar} will still archive files explicitly named on the command line
+or through @option{--files-from}, regardless of where they reside.
+
+@table @option
+@opindex one-file-system
+@item --one-file-system
+Prevents @command{tar} from crossing file system boundaries when
+archiving. Use in conjunction with any write operation.
+@end table
+
+The @option{--one-file-system} option causes @command{tar} to modify its
+normal behavior in archiving the contents of directories. If a file in
+a directory is not on the same file system as the directory itself, then
+@command{tar} will not archive that file. If the file is a directory
+itself, @command{tar} will not archive anything beneath it; in other words,
+@command{tar} will not cross mount points.
+
+This option is useful for making full or incremental archival backups of
+a file system. If this option is used in conjunction with
+@option{--verbose} (@option{-v}), files that are excluded are
+mentioned by name on the standard error.
+
+@menu
+* directory:: Changing Directory
+* absolute:: Absolute File Names
+@end menu
+
+@node directory
+@subsection Changing the Working Directory
+
+@FIXME{need to read over this node now for continuity; i've switched
+things around some.}
+
+@cindex Changing directory mid-stream
+@cindex Directory, changing mid-stream
+@cindex Working directory, specifying
+To change the working directory in the middle of a list of file names,
+either on the command line or in a file specified using
+@option{--files-from} (@option{-T}), use @option{--directory} (@option{-C}).
+This will change the working directory to the specified directory
+after that point in the list.
+
+@table @option
+@opindex directory
+@item --directory=@var{directory}
+@itemx -C @var{directory}
+Changes the working directory in the middle of a command line.
+@end table
+
+For example,
+
+@smallexample
+$ @kbd{tar -c -f jams.tar grape prune -C food cherry}
+@end smallexample
+
+@noindent
+will place the files @file{grape} and @file{prune} from the current
+directory into the archive @file{jams.tar}, followed by the file
+@file{cherry} from the directory @file{food}. This option is especially
+useful when you have several widely separated files that you want to
+store in the same archive.
+
+Note that the file @file{cherry} is recorded in the archive under the
+precise name @file{cherry}, @emph{not} @file{food/cherry}. Thus, the
+archive will contain three files that all appear to have come from the
+same directory; if the archive is extracted with plain @samp{tar
+--extract}, all three files will be written in the current directory.
+
+Contrast this with the command,
+
+@smallexample
+$ @kbd{tar -c -f jams.tar grape prune -C food red/cherry}
+@end smallexample
+
+@noindent
+which records the third file in the archive under the name
+@file{red/cherry} so that, if the archive is extracted using
+@samp{tar --extract}, the third file will be written in a subdirectory
+named @file{red}.
+
+You can use the @option{--directory} option to make the archive
+independent of the original name of the directory holding the files.
+The following command places the files @file{/etc/passwd},
+@file{/etc/hosts}, and @file{/lib/libc.a} into the archive
+@file{foo.tar}:
+
+@smallexample
+$ @kbd{tar -c -f foo.tar -C /etc passwd hosts -C /lib libc.a}
+@end smallexample
+
+@noindent
+However, the names of the archive members will be exactly what they were
+on the command line: @file{passwd}, @file{hosts}, and @file{libc.a}.
+They will not appear to be related by file name to the original
+directories where those files were located.
+
+Note that @option{--directory} options are interpreted consecutively. If
+@option{--directory} specifies a relative file name, it is interpreted
+relative to the then current directory, which might not be the same as
+the original current working directory of @command{tar}, due to a previous
+@option{--directory} option.
+
+When using @option{--files-from} (@pxref{files}), you can put various
+@command{tar} options (including @option{-C}) in the file list. Notice,
+however, that in this case the option and its argument may not be
+separated by whitespace. If you use short option, its argument must
+either follow the option letter immediately, without any intervening
+whitespace, or occupy the next line. Otherwise, if you use long
+option, separate its argument by an equal sign.
+
+For instance, the file list for the above example will be:
+
+@smallexample
+@group
+-C/etc
+passwd
+hosts
+--directory=/lib
+libc.a
+@end group
+@end smallexample
+
+@noindent
+To use it, you would invoke @command{tar} as follows:
+
+@smallexample
+$ @kbd{tar -c -f foo.tar --files-from list}
+@end smallexample
+
+The interpretation of options in file lists is disabled by
+@option{--verbatim-files-from} and @option{--null} options.
+
+@node absolute
+@subsection Absolute File Names
+@cindex absolute file names
+@cindex file names, absolute
+
+By default, @GNUTAR{} drops a leading @samp{/} on
+input or output, and complains about file names containing a @file{..}
+component. There is an option that turns off this behavior:
+
+@table @option
+@opindex absolute-names
+@item --absolute-names
+@itemx -P
+Do not strip leading slashes from file names, and permit file names
+containing a @file{..} file name component.
+@end table
+
+When @command{tar} extracts archive members from an archive, it strips any
+leading slashes (@samp{/}) from the member name. This causes absolute
+member names in the archive to be treated as relative file names. This
+allows you to have such members extracted wherever you want, instead of
+being restricted to extracting the member in the exact directory named
+in the archive. For example, if the archive member has the name
+@file{/etc/passwd}, @command{tar} will extract it as if the name were
+really @file{etc/passwd}.
+
+File names containing @file{..} can cause problems when extracting, so
+@command{tar} normally warns you about such files when creating an
+archive, and rejects attempts to extracts such files.
+
+Other @command{tar} programs do not do this. As a result, if you
+create an archive whose member names start with a slash, they will be
+difficult for other people with a non-@GNUTAR{}
+program to use. Therefore, @GNUTAR{} also strips
+leading slashes from member names when putting members into the
+archive. For example, if you ask @command{tar} to add the file
+@file{/bin/ls} to an archive, it will do so, but the member name will
+be @file{bin/ls}@footnote{A side effect of this is that when
+@option{--create} is used with @option{--verbose} the resulting output
+is not, generally speaking, the same as the one you'd get running
+@kbd{tar --list} command. This may be important if you use some
+scripts for comparing both outputs. @xref{listing member and file names},
+for the information on how to handle this case.}.
+
+Symbolic links containing @file{..} or leading @samp{/} can also cause
+problems when extracting, so @command{tar} normally extracts them last;
+it may create empty files as placeholders during extraction.
+
+If you use the @option{--absolute-names} (@option{-P}) option,
+@command{tar} will do none of these transformations.
+
+To archive or extract files relative to the root directory, specify
+the @option{--absolute-names} (@option{-P}) option.
+
+Normally, @command{tar} acts on files relative to the working
+directory---ignoring superior directory names when archiving, and
+ignoring leading slashes when extracting.
+
+When you specify @option{--absolute-names} (@option{-P}),
+@command{tar} stores file names including all superior directory
+names, and preserves leading slashes. If you only invoked
+@command{tar} from the root directory you would never need the
+@option{--absolute-names} option, but using this option
+may be more convenient than switching to root.
+
+@FIXME{Should be an example in the tutorial/wizardry section using this
+to transfer files between systems.}
+
+@table @option
+@item --absolute-names
+Preserves full file names (including superior directory names) when
+archiving and extracting files.
+
+@end table
+
+@command{tar} prints out a message about removing the @samp{/} from
+file names. This message appears once per @GNUTAR{}
+invocation. It represents something which ought to be told; ignoring
+what it means can cause very serious surprises, later.
+
+Some people, nevertheless, do not want to see this message. Wanting to
+play really dangerously, one may of course redirect @command{tar} standard
+error to the sink. For example, under @command{sh}:
+
+@smallexample
+$ @kbd{tar -c -f archive.tar /home 2> /dev/null}
+@end smallexample
+
+@noindent
+Another solution, both nicer and simpler, would be to change to
+the @file{/} directory first, and then avoid absolute notation.
+For example:
+
+@smallexample
+$ @kbd{tar -c -f archive.tar -C / home}
+@end smallexample
+
+@xref{Integrity}, for some of the security-related implications
+of using this option.
+
+@include parse-datetime.texi
+
+@node Formats
+@chapter Controlling the Archive Format
+
+@cindex Tar archive formats
+Due to historical reasons, there are several formats of tar archives.
+All of them are based on the same principles, but have some subtle
+differences that often make them incompatible with each other.
+
+GNU tar is able to create and handle archives in a variety of formats.
+The most frequently used formats are (in alphabetical order):
+
+@table @asis
+@item gnu
+Format used by @GNUTAR{} versions up to 1.13.25. This format derived
+from an early @acronym{POSIX} standard, adding some improvements such as
+sparse file handling and incremental archives. Unfortunately these
+features were implemented in a way incompatible with other archive
+formats.
+
+Archives in @samp{gnu} format are able to hold file names of unlimited
+length.
+
+@item oldgnu
+Format used by @GNUTAR{} of versions prior to 1.12.
+
+@item v7
+Archive format, compatible with the V7 implementation of tar. This
+format imposes a number of limitations. The most important of them
+are:
+
+@enumerate
+@item The maximum length of a file name is limited to 99 characters.
+@item The maximum length of a symbolic link is limited to 99 characters.
+@item It is impossible to store special files (block and character
+devices, fifos etc.)
+@item Maximum value of user or group @acronym{ID} is limited to 2097151 (7777777
+octal)
+@item V7 archives do not contain symbolic ownership information (user
+and group name of the file owner).
+@end enumerate
+
+This format has traditionally been used by Automake when producing
+Makefiles. This practice will change in the future, in the meantime,
+however this means that projects containing file names more than 99
+characters long will not be able to use @GNUTAR{} @value{VERSION} and
+Automake prior to 1.9.
+
+@item ustar
+Archive format defined by @acronym{POSIX.1-1988} specification. It stores
+symbolic ownership information. It is also able to store
+special files. However, it imposes several restrictions as well:
+
+@enumerate
+@item The maximum length of a file name is limited to 256 characters,
+provided that the file name can be split at a directory separator in
+two parts, first of them being at most 155 bytes long. So, in most
+cases the maximum file name length will be shorter than 256
+characters.
+@item The maximum length of a symbolic link name is limited to
+100 characters.
+@item Maximum size of a file the archive is able to accommodate
+is 8GB
+@item Maximum value of UID/GID is 2097151.
+@item Maximum number of bits in device major and minor numbers is 21.
+@end enumerate
+
+@item star
+Format used by J@"org Schilling @command{star}
+implementation. @GNUTAR{} is able to read @samp{star} archives but
+currently does not produce them.
+
+@item posix
+Archive format defined by @acronym{POSIX.1-2001} specification. This is the
+most flexible and feature-rich format. It does not impose any
+restrictions on file sizes or file name lengths. This format is quite
+recent, so not all tar implementations are able to handle it properly.
+However, this format is designed in such a way that any tar
+implementation able to read @samp{ustar} archives will be able to read
+most @samp{posix} archives as well, with the only exception that any
+additional information (such as long file names etc.)@: will in such
+case be extracted as plain text files along with the files it refers to.
+
+This archive format will be the default format for future versions
+of @GNUTAR{}.
+
+@end table
+
+The following table summarizes the limitations of each of these
+formats:
+
+@multitable @columnfractions .10 .20 .20 .20 .20
+@headitem Format @tab UID @tab File Size @tab File Name @tab Devn
+@item gnu @tab 1.8e19 @tab Unlimited @tab Unlimited @tab 63
+@item oldgnu @tab 1.8e19 @tab Unlimited @tab Unlimited @tab 63
+@item v7 @tab 2097151 @tab 8GB @tab 99 @tab n/a
+@item ustar @tab 2097151 @tab 8GB @tab 256 @tab 21
+@item posix @tab Unlimited @tab Unlimited @tab Unlimited @tab Unlimited
+@end multitable
+
+The default format for @GNUTAR{} is defined at compilation
+time. You may check it by running @command{tar --help}, and examining
+the last lines of its output. Usually, @GNUTAR{} is configured
+to create archives in @samp{gnu} format, however, future version will
+switch to @samp{posix}.
+
+@menu
+* Compression:: Using Less Space through Compression
+* Attributes:: Handling File Attributes
+* Portability:: Making @command{tar} Archives More Portable
+* cpio:: Comparison of @command{tar} and @command{cpio}
+@end menu
+
+@node Compression
+@section Using Less Space through Compression
+
+@menu
+* gzip:: Creating and Reading Compressed Archives
+* sparse:: Archiving Sparse Files
+@end menu
+
+@node gzip
+@subsection Creating and Reading Compressed Archives
+@cindex Compressed archives
+@cindex Storing archives in compressed format
+
+@cindex gzip
+@cindex bzip2
+@cindex lzip
+@cindex lzma
+@cindex lzop
+@cindex compress
+@GNUTAR{} is able to create and read compressed archives. It supports
+a wide variety of compression programs, namely: @command{gzip},
+@command{bzip2}, @command{lzip}, @command{lzma}, @command{lzop},
+@command{xz} and traditional @command{compress}. The latter is
+supported mostly for backward compatibility, and we recommend
+against using it, because it is by far less effective than the other
+compression programs@footnote{It also had patent problems in the past.}.
+
+Creating a compressed archive is simple: you just specify a
+@dfn{compression option} along with the usual archive creation
+commands. The compression option is @option{-z} (@option{--gzip}) to
+create a @command{gzip} compressed archive, @option{-j}
+(@option{--bzip2}) to create a @command{bzip2} compressed archive,
+@option{--lzip} to create an @asis{lzip} compressed archive,
+@option{-J} (@option{--xz}) to create an @asis{XZ} archive,
+@option{--lzma} to create an @asis{LZMA} compressed
+archive, @option{--lzop} to create an @asis{LSOP} archive, and
+@option{-Z} (@option{--compress}) to use @command{compress} program.
+For example:
+
+@smallexample
+$ @kbd{tar czf archive.tar.gz .}
+@end smallexample
+
+You can also let @GNUTAR{} select the compression program based on
+the suffix of the archive file name. This is done using
+@option{--auto-compress} (@option{-a}) command line option. For
+example, the following invocation will use @command{bzip2} for
+compression:
+
+@smallexample
+$ @kbd{tar caf archive.tar.bz2 .}
+@end smallexample
+
+@noindent
+whereas the following one will use @command{lzma}:
+
+@smallexample
+$ @kbd{tar caf archive.tar.lzma .}
+@end smallexample
+
+For a complete list of file name suffixes recognized by @GNUTAR{},
+see @ref{auto-compress}.
+
+Reading compressed archive is even simpler: you don't need to specify
+any additional options as @GNUTAR{} recognizes its format
+automatically. Thus, the following commands will list and extract the
+archive created in previous example:
+
+@smallexample
+# List the compressed archive
+$ @kbd{tar tf archive.tar.gz}
+# Extract the compressed archive
+$ @kbd{tar xf archive.tar.gz}
+@end smallexample
+
+The format recognition algorithm is based on @dfn{signatures}, a
+special byte sequences in the beginning of file, that are specific for
+certain compression formats. If this approach fails, @command{tar}
+falls back to using archive name suffix to determine its format
+(@pxref{auto-compress}, for a list of recognized suffixes).
+
+@anchor{alternative decompression programs}
+@cindex alternative decompression programs
+Some compression programs are able to handle different compression
+formats. @GNUTAR{} uses this, if the principal decompressor for the
+given format is not available. For example, if @command{compress} is
+not installed, @command{tar} will try to use @command{gzip}. As of
+version @value{VERSION} the following alternatives are
+tried@footnote{To verbosely trace the decompressor selection, use the
+@option{--warning=decompress-program} option
+(@pxref{warnings,decompress-program}).}:
+
+@multitable @columnfractions 0.3 0.3 0.3
+@headitem Format @tab Main decompressor @tab Alternatives
+@item compress @tab compress @tab gzip
+@item lzma @tab lzma @tab xz
+@item bzip2 @tab bzip2 @tab lbzip2
+@end multitable
+
+The only case when you have to specify a decompression option while
+reading the archive is when reading from a pipe or from a tape drive
+that does not support random access. However, in this case @GNUTAR{}
+will indicate which option you should use. For example:
+
+@smallexample
+$ @kbd{cat archive.tar.gz | tar tf -}
+tar: Archive is compressed. Use -z option
+tar: Error is not recoverable: exiting now
+@end smallexample
+
+If you see such diagnostics, just add the suggested option to the
+invocation of @GNUTAR{}:
+
+@smallexample
+$ @kbd{cat archive.tar.gz | tar tzf -}
+@end smallexample
+
+Notice also, that there are several restrictions on operations on
+compressed archives. First of all, compressed archives cannot be
+modified, i.e., you cannot update (@option{--update}, alias @option{-u})
+them or delete (@option{--delete}) members from them or
+add (@option{--append}, alias @option{-r}) members to them. Likewise, you
+cannot append another @command{tar} archive to a compressed archive using
+@option{--concatenate} (@option{-A}). Secondly, multi-volume
+archives cannot be compressed.
+
+The following options allow to select a particular compressor program:
+
+@table @option
+@opindex gzip
+@opindex ungzip
+@item -z
+@itemx --gzip
+@itemx --ungzip
+Filter the archive through @command{gzip}.
+
+@opindex xz
+@item -J
+@itemx --xz
+Filter the archive through @code{xz}.
+
+@item -j
+@itemx --bzip2
+Filter the archive through @code{bzip2}.
+
+@opindex lzip
+@item --lzip
+Filter the archive through @command{lzip}.
+
+@opindex lzma
+@item --lzma
+Filter the archive through @command{lzma}.
+
+@opindex lzop
+@item --lzop
+Filter the archive through @command{lzop}.
+
+@opindex compress
+@opindex uncompress
+@item -Z
+@itemx --compress
+@itemx --uncompress
+Filter the archive through @command{compress}.
+@end table
+
+When any of these options is given, @GNUTAR{} searches the compressor
+binary in the current path and invokes it. The name of the compressor
+program is specified at compilation time using a corresponding
+@option{--with-@var{compname}} option to @command{configure}, e.g.
+@option{--with-bzip2} to select a specific @command{bzip2} binary.
+@xref{lbzip2}, for a detailed discussion.
+
+The output produced by @command{tar --help} shows the actual
+compressor names along with each of these options.
+
+You can use any of these options on physical devices (tape drives,
+etc.)@: and remote files as well as on normal files; data to or from
+such devices or remote files is reblocked by another copy of the
+@command{tar} program to enforce the specified (or default) record
+size. The default compression parameters are used.
+You can override them by using the @option{-I} option (see
+below), e.g.:
+
+@smallexample
+$ @kbd{tar -cf archive.tar.gz -I 'gzip -9 -n' subdir}
+@end smallexample
+
+@noindent
+A more traditional way to do this is to use a pipe:
+
+@smallexample
+$ @kbd{tar cf - subdir | gzip -9 -n > archive.tar.gz}
+@end smallexample
+
+@cindex corrupted archives
+Compressed archives are easily corrupted, because compressed files
+have little redundancy. The adaptive nature of the
+compression scheme means that the compression tables are implicitly
+spread all over the archive. If you lose a few blocks, the dynamic
+construction of the compression tables becomes unsynchronized, and there
+is little chance that you could recover later in the archive.
+
+Other compression options provide better control over creating
+compressed archives. These are:
+
+@table @option
+@anchor{auto-compress}
+@opindex auto-compress
+@item --auto-compress
+@itemx -a
+Select a compression program to use by the archive file name
+suffix. The following suffixes are recognized:
+
+@multitable @columnfractions 0.3 0.6
+@headitem Suffix @tab Compression program
+@item @samp{.gz} @tab @command{gzip}
+@item @samp{.tgz} @tab @command{gzip}
+@item @samp{.taz} @tab @command{gzip}
+@item @samp{.Z} @tab @command{compress}
+@item @samp{.taZ} @tab @command{compress}
+@item @samp{.bz2} @tab @command{bzip2}
+@item @samp{.tz2} @tab @command{bzip2}
+@item @samp{.tbz2} @tab @command{bzip2}
+@item @samp{.tbz} @tab @command{bzip2}
+@item @samp{.lz} @tab @command{lzip}
+@item @samp{.lzma} @tab @command{lzma}
+@item @samp{.tlz} @tab @command{lzma}
+@item @samp{.lzo} @tab @command{lzop}
+@item @samp{.xz} @tab @command{xz}
+@end multitable
+
+@anchor{use-compress-program}
+@opindex use-compress-program
+@item --use-compress-program=@var{command}
+@itemx -I=@var{command}
+Use external compression program @var{command}. Use this option if you
+want to specify options for the compression program, or if you
+are not happy with the compression program associated with the suffix
+at compile time, or if you have a compression program that @GNUTAR{}
+does not support. The @var{command} argument is a valid command
+invocation, as you would type it at the command line prompt, with any
+additional options as needed. Enclose it in quotes if it contains
+white space (@pxref{external, Running External Commands}).
+
+The @var{command} should follow two conventions:
+
+First, when invoked without additional options, it should read data
+from standard input, compress it and output it on standard output.
+
+Secondly, if invoked with the additional @option{-d} option, it should
+do exactly the opposite, i.e., read the compressed data from the
+standard input and produce uncompressed data on the standard output.
+
+The latter requirement means that you must not use the @option{-d}
+option as a part of the @var{command} itself.
+@end table
+
+@cindex gpg, using with tar
+@cindex gnupg, using with tar
+@cindex Using encrypted archives
+The @option{--use-compress-program} option, in particular, lets you
+implement your own filters, not necessarily dealing with
+compression/decompression. For example, suppose you wish to implement
+PGP encryption on top of compression, using @command{gpg} (@pxref{Top,
+gpg, gpg ---- encryption and signing tool, gpg, GNU Privacy Guard
+Manual}). The following script does that:
+
+@smallexample
+@group
+#! /bin/sh
+case $1 in
+-d) gpg --decrypt - | gzip -d -c;;
+'') gzip -c | gpg -s;;
+*) echo "Unknown option $1">&2; exit 1;;
+esac
+@end group
+@end smallexample
+
+Suppose you name it @file{gpgz} and save it somewhere in your
+@env{PATH}. Then the following command will create a compressed
+archive signed with your private key:
+
+@smallexample
+$ @kbd{tar -cf foo.tar.gpgz -Igpgz .}
+@end smallexample
+
+@noindent
+Likewise, the command below will list its contents:
+
+@smallexample
+$ @kbd{tar -tf foo.tar.gpgz -Igpgz .}
+@end smallexample
+
+@ignore
+The above is based on the following discussion:
+
+ I have one question, or maybe it's a suggestion if there isn't a way
+ to do it now. I would like to use @option{--gzip}, but I'd also like
+ the output to be fed through a program like @acronym{GNU}
+ @command{ecc} (actually, right now that's @samp{exactly} what I'd like
+ to use :-)), basically adding ECC protection on top of compression.
+ It seems as if this should be quite easy to do, but I can't work out
+ exactly how to go about it. Of course, I can pipe the standard output
+ of @command{tar} through @command{ecc}, but then I lose (though I
+ haven't started using it yet, I confess) the ability to have
+ @command{tar} use @command{rmt} for it's I/O (I think).
+
+ I think the most straightforward thing would be to let me specify a
+ general set of filters outboard of compression (preferably ordered,
+ so the order can be automatically reversed on input operations, and
+ with the options they require specifiable), but beggars shouldn't be
+ choosers and anything you decide on would be fine with me.
+
+ By the way, I like @command{ecc} but if (as the comments say) it can't
+ deal with loss of block sync, I'm tempted to throw some time at adding
+ that capability. Supposing I were to actually do such a thing and
+ get it (apparently) working, do you accept contributed changes to
+ utilities like that? (Leigh Clayton @file{loc@@soliton.com}, May 1995).
+
+ Isn't that exactly the role of the
+ @option{--use-compress-prog=@var{program}} option?
+ I never tried it myself, but I suspect you may want to write a
+ @var{prog} script or program able to filter stdin to stdout to
+ way you want. It should recognize the @option{-d} option, for when
+ extraction is needed rather than creation.
+
+ It has been reported that if one writes compressed data (through the
+ @option{--gzip} or @option{--compress} options) to a DLT and tries to use
+ the DLT compression mode, the data will actually get bigger and one will
+ end up with less space on the tape.
+@end ignore
+
+@menu
+* lbzip2:: Using lbzip2 with @GNUTAR{}.
+@end menu
+
+@node lbzip2
+@subsubsection Using lbzip2 with @GNUTAR{}.
+@cindex lbzip2
+@cindex Laszlo Ersek
+ @command{Lbzip2} is a multithreaded utility for handling
+@samp{bzip2} compression, written by Laszlo Ersek. It makes use of
+multiple processors to speed up its operation and in general works
+considerably faster than @command{bzip2}. For a detailed description
+of @command{lbzip2} see @uref{http://freshmeat.net/@/projects/@/lbzip2} and
+@uref{http://www.linuxinsight.com/@/lbzip2-parallel-bzip2-utility.html,
+lbzip2: parallel bzip2 utility}.
+
+ Recent versions of @command{lbzip2} are mostly command line compatible
+with @command{bzip2}, which makes it possible to automatically invoke
+it via the @option{--bzip2} @GNUTAR{} command line option. To do so,
+@GNUTAR{} must be configured with the @option{--with-bzip2} command
+line option, like this:
+
+@smallexample
+$ @kbd{./configure --with-bzip2=lbzip2 [@var{other-options}]}
+@end smallexample
+
+ Once configured and compiled this way, @command{tar --help} will show the
+following:
+
+@smallexample
+@group
+$ @kbd{tar --help | grep -- --bzip2}
+ -j, --bzip2 filter the archive through lbzip2
+@end group
+@end smallexample
+
+@noindent
+which means that running @command{tar --bzip2} will invoke @command{lbzip2}.
+
+@node sparse
+@subsection Archiving Sparse Files
+@cindex Sparse Files
+
+Files in the file system occasionally have @dfn{holes}. A @dfn{hole}
+in a file is a section of the file's contents which was never written.
+The contents of a hole reads as all zeros. On many operating systems,
+actual disk storage is not allocated for holes, but they are counted
+in the length of the file. If you archive such a file, @command{tar}
+could create an archive longer than the original. To have @command{tar}
+attempt to recognize the holes in a file, use @option{--sparse}
+(@option{-S}). When you use this option, then, for any file using
+less disk space than would be expected from its length, @command{tar}
+searches the file for holes. It then records in the archive for the file where
+the holes (consecutive stretches of zeros) are, and only archives the
+``real contents'' of the file. On extraction (using @option{--sparse} is not
+needed on extraction) any such files have also holes created wherever the holes
+were found. Thus, if you use @option{--sparse}, @command{tar} archives won't
+take more space than the original.
+
+@GNUTAR{} uses two methods for detecting holes in sparse files. These
+methods are described later in this subsection.
+
+@table @option
+@opindex sparse
+@item -S
+@itemx --sparse
+This option instructs @command{tar} to test each file for sparseness
+before attempting to archive it. If the file is found to be sparse it
+is treated specially, thus allowing to decrease the amount of space
+used by its image in the archive.
+
+This option is meaningful only when creating or updating archives. It
+has no effect on extraction.
+@end table
+
+Consider using @option{--sparse} when performing file system backups,
+to avoid archiving the expanded forms of files stored sparsely in the
+system.
+
+Even if your system has no sparse files currently, some may be
+created in the future. If you use @option{--sparse} while making file
+system backups as a matter of course, you can be assured the archive
+will never take more space on the media than the files take on disk
+(otherwise, archiving a disk filled with sparse files might take
+hundreds of tapes). @xref{Incremental Dumps}.
+
+However, be aware that @option{--sparse} option may present a serious
+drawback. Namely, in order to determine the positions of holes in a file
+@command{tar} may have to read it before trying to archive it, so in total
+the file may be read @strong{twice}. This may happen when your OS or your FS
+does not support @dfn{SEEK_HOLE/SEEK_DATA} feature in @dfn{lseek} (See
+@option{--hole-detection}, below).
+
+@cindex sparse formats, defined
+When using @samp{POSIX} archive format, @GNUTAR{} is able to store
+sparse files using in three distinct ways, called @dfn{sparse
+formats}. A sparse format is identified by its @dfn{number},
+consisting, as usual of two decimal numbers, delimited by a dot. By
+default, format @samp{1.0} is used. If, for some reason, you wish to
+use an earlier format, you can select it using
+@option{--sparse-version} option.
+
+@table @option
+@opindex sparse-version
+@item --sparse-version=@var{version}
+Select the format to store sparse files in. Valid @var{version} values
+are: @samp{0.0}, @samp{0.1} and @samp{1.0}. @xref{Sparse Formats},
+for a detailed description of each format.
+@end table
+
+Using @option{--sparse-format} option implies @option{--sparse}.
+
+@table @option
+@opindex hole-detection
+@cindex hole detection
+@item --hole-detection=@var{method}
+Enforce concrete hole detection method. Before the real contents of sparse
+file are stored, @command{tar} needs to gather knowledge about file
+sparseness. This is because it needs to have the file's map of holes
+stored into tar header before it starts archiving the file contents.
+Currently, two methods of hole detection are implemented:
+
+@itemize @bullet
+@item @option{--hole-detection=seek}
+Seeking the file for data and holes. It uses enhancement of the @code{lseek}
+system call (@code{SEEK_HOLE} and @code{SEEK_DATA}) which is able to
+reuse file system knowledge about sparse file contents - so the
+detection is usually very fast. To use this feature, your file system
+and operating system must support it. At the time of this writing
+(2015) this feature, in spite of not being accepted by POSIX, is
+fairly widely supported by different operating systems.
+
+@item @option{--hole-detection=raw}
+Reading byte-by-byte the whole sparse file before the archiving. This
+method detects holes like consecutive stretches of zeroes. Comparing to
+the previous method, it is usually much slower, although more
+portable.
+@end itemize
+@end table
+
+When no @option{--hole-detection} option is given, @command{tar} uses
+the @samp{seek}, if supported by the operating system.
+
+Using @option{--hole-detection} option implies @option{--sparse}.
+
+@node Attributes
+@section Handling File Attributes
+@cindex attributes, files
+@cindex file attributes
+
+When @command{tar} reads files, it updates their access times. To
+avoid this, use the @option{--atime-preserve[=METHOD]} option, which can either
+reset the access time retroactively or avoid changing it in the first
+place.
+
+@table @option
+@opindex atime-preserve
+@item --atime-preserve
+@itemx --atime-preserve=replace
+@itemx --atime-preserve=system
+Preserve the access times of files that are read. This works only for
+files that you own, unless you have superuser privileges.
+
+@option{--atime-preserve=replace} works on most systems, but it also
+restores the data modification time and updates the status change
+time. Hence it doesn't interact with incremental dumps nicely
+(@pxref{Incremental Dumps}), and it can set access or data modification times
+incorrectly if other programs access the file while @command{tar} is
+running.
+
+@option{--atime-preserve=system} avoids changing the access time in
+the first place, if the operating system supports this.
+Unfortunately, this may or may not work on any given operating system
+or file system. If @command{tar} knows for sure it won't work, it
+complains right away.
+
+Currently @option{--atime-preserve} with no operand defaults to
+@option{--atime-preserve=replace}, but this is intended to change to
+@option{--atime-preserve=system} when the latter is better-supported.
+
+@opindex touch
+@item -m
+@itemx --touch
+Do not extract data modification time.
+
+When this option is used, @command{tar} leaves the data modification times
+of the files it extracts as the times when the files were extracted,
+instead of setting it to the times recorded in the archive.
+
+This option is meaningless with @option{--list} (@option{-t}).
+
+@opindex same-owner
+@item --same-owner
+Create extracted files with the same ownership they have in the
+archive.
+
+This is the default behavior for the superuser,
+so this option is meaningful only for non-root users, when @command{tar}
+is executed on those systems able to give files away. This is
+considered as a security flaw by many people, at least because it
+makes quite difficult to correctly account users for the disk space
+they occupy. Also, the @code{suid} or @code{sgid} attributes of
+files are easily and silently lost when files are given away.
+
+When writing an archive, @command{tar} writes the user @acronym{ID} and user name
+separately. If it can't find a user name (because the user @acronym{ID} is not
+in @file{/etc/passwd}), then it does not write one. When restoring,
+it tries to look the name (if one was written) up in
+@file{/etc/passwd}. If it fails, then it uses the user @acronym{ID} stored in
+the archive instead.
+
+@opindex no-same-owner
+@item --no-same-owner
+@itemx -o
+Do not attempt to restore ownership when extracting. This is the
+default behavior for ordinary users, so this option has an effect
+only for the superuser.
+
+@opindex numeric-owner
+@item --numeric-owner
+The @option{--numeric-owner} option allows (ANSI) archives to be written
+without user/group name information or such information to be ignored
+when extracting. It effectively disables the generation and/or use
+of user/group name information. This option forces extraction using
+the numeric ids from the archive, ignoring the names.
+
+This is useful in certain circumstances, when restoring a backup from
+an emergency floppy with different passwd/group files for example.
+It is otherwise impossible to extract files with the right ownerships
+if the password file in use during the extraction does not match the
+one belonging to the file system(s) being extracted. This occurs,
+for example, if you are restoring your files after a major crash and
+had booted from an emergency floppy with no password file or put your
+disk into another machine to do the restore.
+
+The numeric ids are @emph{always} saved into @command{tar} archives.
+The identifying names are added at create time when provided by the
+system, unless @option{--format=oldgnu} is used. Numeric ids could be
+used when moving archives between a collection of machines using
+a centralized management for attribution of numeric ids to users
+and groups. This is often made through using the NIS capabilities.
+
+When making a @command{tar} file for distribution to other sites, it
+is sometimes cleaner to use a single owner for all files in the
+distribution, and nicer to specify the write permission bits of the
+files as stored in the archive independently of their actual value on
+the file system. The way to prepare a clean distribution is usually
+to have some Makefile rule creating a directory, copying all needed
+files in that directory, then setting ownership and permissions as
+wanted (there are a lot of possible schemes), and only then making a
+@command{tar} archive out of this directory, before cleaning
+everything out. Of course, we could add a lot of options to
+@GNUTAR{} for fine tuning permissions and ownership.
+This is not the good way, I think. @GNUTAR{} is
+already crowded with options and moreover, the approach just explained
+gives you a great deal of control already.
+
+@xopindex{same-permissions, short description}
+@xopindex{preserve-permissions, short description}
+@item -p
+@itemx --same-permissions
+@itemx --preserve-permissions
+Extract all protection information.
+
+This option causes @command{tar} to set the modes (access permissions) of
+extracted files exactly as recorded in the archive. If this option
+is not used, the current @code{umask} setting limits the permissions
+on extracted files. This option is by default enabled when
+@command{tar} is executed by a superuser.
+
+
+This option is meaningless with @option{--list} (@option{-t}).
+@end table
+
+@node Portability
+@section Making @command{tar} Archives More Portable
+
+Creating a @command{tar} archive on a particular system that is meant to be
+useful later on many other machines and with other versions of @command{tar}
+is more challenging than you might think. @command{tar} archive formats
+have been evolving since the first versions of Unix. Many such formats
+are around, and are not always compatible with each other. This section
+discusses a few problems, and gives some advice about making @command{tar}
+archives more portable.
+
+One golden rule is simplicity. For example, limit your @command{tar}
+archives to contain only regular files and directories, avoiding
+other kind of special files. Do not attempt to save sparse files or
+contiguous files as such. Let's discuss a few more problems, in turn.
+
+@FIXME{Discuss GNU extensions (incremental backups, multi-volume
+archives and archive labels) in GNU and PAX formats.}
+
+@menu
+* Portable Names:: Portable Names
+* dereference:: Symbolic Links
+* hard links:: Hard Links
+* old:: Old V7 Archives
+* ustar:: Ustar Archives
+* gnu:: GNU and old GNU format archives.
+* posix:: @acronym{POSIX} archives
+* Checksumming:: Checksumming Problems
+* Large or Negative Values:: Large files, negative time stamps, etc.
+* Other Tars:: How to Extract GNU-Specific Data Using
+ Other @command{tar} Implementations
+@end menu
+
+@node Portable Names
+@subsection Portable Names
+
+Use portable file and member names. A name is portable if it contains
+only @acronym{ASCII} letters and digits, @samp{/}, @samp{.}, @samp{_}, and
+@samp{-}; it cannot be empty, start with @samp{-} or @samp{//}, or
+contain @samp{/-}. Avoid deep directory nesting. For portability to
+old Unix hosts, limit your file name components to 14 characters or
+less.
+
+If you intend to have your @command{tar} archives to be read under
+MSDOS, you should not rely on case distinction for file names, and you
+might use the @acronym{GNU} @command{doschk} program for helping you
+further diagnosing illegal MSDOS names, which are even more limited
+than System V's.
+
+@node dereference
+@subsection Symbolic Links
+@cindex File names, using symbolic links
+@cindex Symbolic link as file name
+
+@opindex dereference
+Normally, when @command{tar} archives a symbolic link, it writes a
+block to the archive naming the target of the link. In that way, the
+@command{tar} archive is a faithful record of the file system contents.
+When @option{--dereference} (@option{-h}) is used with
+@option{--create} (@option{-c}), @command{tar} archives the files
+symbolic links point to, instead of
+the links themselves.
+
+When creating portable archives, use @option{--dereference}
+(@option{-h}): some systems do not support
+symbolic links, and moreover, your distribution might be unusable if
+it contains unresolved symbolic links.
+
+When reading from an archive, the @option{--dereference} (@option{-h})
+option causes @command{tar} to follow an already-existing symbolic
+link when @command{tar} writes or reads a file named in the archive.
+Ordinarily, @command{tar} does not follow such a link, though it may
+remove the link before writing a new file. @xref{Dealing with Old
+Files}.
+
+The @option{--dereference} option is unsafe if an untrusted user can
+modify directories while @command{tar} is running. @xref{Security}.
+
+@node hard links
+@subsection Hard Links
+@cindex File names, using hard links
+@cindex hard links, dereferencing
+@cindex dereferencing hard links
+
+Normally, when @command{tar} archives a hard link, it writes a
+block to the archive naming the target of the link (a @samp{1} type
+block). In that way, the actual file contents is stored in file only
+once. For example, consider the following two files:
+
+@smallexample
+@group
+$ ls -l
+-rw-r--r-- 2 gray staff 4 2007-10-30 15:11 one
+-rw-r--r-- 2 gray staff 4 2007-10-30 15:11 jeden
+@end group
+@end smallexample
+
+Here, @file{jeden} is a link to @file{one}. When archiving this
+directory with a verbose level 2, you will get an output similar to
+the following:
+
+@smallexample
+$ tar cvvf ../archive.tar .
+drwxr-xr-x gray/staff 0 2007-10-30 15:13 ./
+-rw-r--r-- gray/staff 4 2007-10-30 15:11 ./jeden
+hrw-r--r-- gray/staff 0 2007-10-30 15:11 ./one link to ./jeden
+@end smallexample
+
+The last line shows that, instead of storing two copies of the file,
+@command{tar} stored it only once, under the name @file{jeden}, and
+stored file @file{one} as a hard link to this file.
+
+It may be important to know that all hard links to the given file are
+stored in the archive. For example, this may be necessary for exact
+reproduction of the file system. The following option does that:
+
+@table @option
+@xopindex{check-links, described}
+@item --check-links
+@itemx -l
+Check the number of links dumped for each processed file. If this
+number does not match the total number of hard links for the file, print
+a warning message.
+@end table
+
+For example, trying to archive only file @file{jeden} with this option
+produces the following diagnostics:
+
+@smallexample
+$ tar -c -f ../archive.tar -l jeden
+tar: Missing links to 'jeden'.
+@end smallexample
+
+Although creating special records for hard links helps keep a faithful
+record of the file system contents and makes archives more compact, it
+may present some difficulties when extracting individual members from
+the archive. For example, trying to extract file @file{one} from the
+archive created in previous examples produces, in the absence of file
+@file{jeden}:
+
+@smallexample
+$ tar xf archive.tar ./one
+tar: ./one: Cannot hard link to './jeden': No such file or directory
+tar: Error exit delayed from previous errors
+@end smallexample
+
+The reason for this behavior is that @command{tar} cannot seek back in
+the archive to the previous member (in this case, @file{one}), to
+extract it@footnote{There are plans to fix this in future releases.}.
+If you wish to avoid such problems at the cost of a bigger archive,
+use the following option:
+
+@table @option
+@xopindex{hard-dereference, described}
+@item --hard-dereference
+Dereference hard links and store the files they refer to.
+@end table
+
+For example, trying this option on our two sample files, we get two
+copies in the archive, each of which can then be extracted
+independently of the other:
+
+@smallexample
+@group
+$ tar -c -vv -f ../archive.tar --hard-dereference .
+drwxr-xr-x gray/staff 0 2007-10-30 15:13 ./
+-rw-r--r-- gray/staff 4 2007-10-30 15:11 ./jeden
+-rw-r--r-- gray/staff 4 2007-10-30 15:11 ./one
+@end group
+@end smallexample
+
+@node old
+@subsection Old V7 Archives
+@cindex Format, old style
+@cindex Old style format
+@cindex Old style archives
+@cindex v7 archive format
+
+Certain old versions of @command{tar} cannot handle additional
+information recorded by newer @command{tar} programs. To create an
+archive in V7 format (not ANSI), which can be read by these old
+versions, specify the @option{--format=v7} option in
+conjunction with the @option{--create} (@option{-c}) (@command{tar} also
+accepts @option{--portability} or @option{--old-archive} for this
+option). When you specify it,
+@command{tar} leaves out information about directories, pipes, fifos,
+contiguous files, and device files, and specifies file ownership by
+group and user IDs instead of group and user names.
+
+When updating an archive, do not use @option{--format=v7}
+unless the archive was created using this option.
+
+In most cases, a @emph{new} format archive can be read by an @emph{old}
+@command{tar} program without serious trouble, so this option should
+seldom be needed. On the other hand, most modern @command{tar}s are
+able to read old format archives, so it might be safer for you to
+always use @option{--format=v7} for your distributions. Notice,
+however, that @samp{ustar} format is a better alternative, as it is
+free from many of @samp{v7}'s drawbacks.
+
+@node ustar
+@subsection Ustar Archive Format
+
+@cindex ustar archive format
+The archive format defined by the @acronym{POSIX}.1-1988 specification is
+called @code{ustar}. Although it is more flexible than the V7 format, it
+still has many restrictions (@pxref{Formats,ustar}, for the detailed
+description of @code{ustar} format). Along with V7 format,
+@code{ustar} format is a good choice for archives intended to be read
+with other implementations of @command{tar}.
+
+To create an archive in @code{ustar} format, use the @option{--format=ustar}
+option in conjunction with @option{--create} (@option{-c}).
+
+@node gnu
+@subsection @acronym{GNU} and old @GNUTAR{} format
+
+@cindex GNU archive format
+@cindex Old GNU archive format
+@GNUTAR{} was based on an early draft of the
+@acronym{POSIX} 1003.1 @code{ustar} standard. @acronym{GNU} extensions to
+@command{tar}, such as the support for file names longer than 100
+characters, use portions of the @command{tar} header record which were
+specified in that @acronym{POSIX} draft as unused. Subsequent changes in
+@acronym{POSIX} have allocated the same parts of the header record for
+other purposes. As a result, @GNUTAR{} format is
+incompatible with the current @acronym{POSIX} specification, and with
+@command{tar} programs that follow it.
+
+In the majority of cases, @command{tar} will be configured to create
+this format by default. This will change in future releases, since
+we plan to make @samp{POSIX} format the default.
+
+To force creation a @GNUTAR{} archive, use option
+@option{--format=gnu}.
+
+@node posix
+@subsection @GNUTAR{} and @acronym{POSIX} @command{tar}
+
+@cindex POSIX archive format
+@cindex PAX archive format
+Starting from version 1.14 @GNUTAR{} features full support for
+@acronym{POSIX.1-2001} archives.
+
+A @acronym{POSIX} conformant archive will be created if @command{tar}
+was given @option{--format=posix} (@option{--format=pax}) option. No
+special option is required to read and extract from a @acronym{POSIX}
+archive.
+
+@menu
+* PAX keywords:: Controlling Extended Header Keywords.
+@end menu
+
+@node PAX keywords
+@subsubsection Controlling Extended Header Keywords
+
+@table @option
+@opindex pax-option
+@item --pax-option=@var{keyword-list}
+Handle keywords in @acronym{PAX} extended headers. This option is
+equivalent to @option{-o} option of the @command{pax} utility.
+@end table
+
+@var{Keyword-list} is a comma-separated
+list of keyword options, each keyword option taking one of
+the following forms:
+
+@table @code
+@item delete=@var{pattern}
+When used with one of archive-creation commands,
+this option instructs @command{tar} to omit from extended header records
+that it produces any keywords matching the string @var{pattern}.
+
+When used in extract or list mode, this option instructs tar
+to ignore any keywords matching the given @var{pattern} in the extended
+header records. In both cases, matching is performed using the pattern
+matching notation described in @acronym{POSIX 1003.2}, 3.13
+(@pxref{wildcards}). For example:
+
+@smallexample
+--pax-option delete=security.*
+@end smallexample
+
+would suppress security-related information.
+
+@item exthdr.name=@var{string}
+
+This keyword allows user control over the name that is written into the
+ustar header blocks for the extended headers. The name is obtained
+from @var{string} after making the following substitutions:
+
+@multitable @columnfractions .25 .55
+@headitem Meta-character @tab Replaced By
+@item %d @tab The directory name of the file, equivalent to the
+result of the @command{dirname} utility on the translated file name.
+@item %f @tab The name of the file with the directory information
+stripped, equivalent to the result of the @command{basename} utility
+on the translated file name.
+@item %p @tab The process @acronym{ID} of the @command{tar} process.
+@item %% @tab A @samp{%} character.
+@end multitable
+
+Any other @samp{%} characters in @var{string} produce undefined
+results.
+
+If no option @samp{exthdr.name=string} is specified, @command{tar}
+will use the following default value:
+
+@smallexample
+%d/PaxHeaders.%p/%f
+@end smallexample
+
+@item exthdr.mtime=@var{value}
+
+This keyword defines the value of the @samp{mtime} field that
+is written into the ustar header blocks for the extended headers.
+By default, the @samp{mtime} field is set to the modification time
+of the archive member described by that extended header (or to the
+value of the @option{--mtime} option, if supplied).
+
+@item globexthdr.name=@var{string}
+This keyword allows user control over the name that is written into
+the ustar header blocks for global extended header records. The name
+is obtained from the contents of @var{string}, after making
+the following substitutions:
+
+@multitable @columnfractions .25 .55
+@headitem Meta-character @tab Replaced By
+@item %n @tab An integer that represents the
+sequence number of the global extended header record in the archive,
+starting at 1.
+@item %p @tab The process @acronym{ID} of the @command{tar} process.
+@item %% @tab A @samp{%} character.
+@end multitable
+
+Any other @samp{%} characters in @var{string} produce undefined results.
+
+If no option @samp{globexthdr.name=string} is specified, @command{tar}
+will use the following default value:
+
+@smallexample
+$TMPDIR/GlobalHead.%p.%n
+@end smallexample
+
+@noindent
+where @samp{$TMPDIR} represents the value of the @var{TMPDIR}
+environment variable. If @var{TMPDIR} is not set, @command{tar}
+uses @samp{/tmp}.
+
+@item globexthdr.mtime=@var{value}
+
+This keyword defines the value of the @samp{mtime} field that
+is written into the ustar header blocks for the global extended headers.
+By default, the @samp{mtime} field is set to the time when
+@command{tar} was invoked.
+
+@item @var{keyword}=@var{value}
+When used with one of archive-creation commands, these keyword/value pairs
+will be included at the beginning of the archive in a global extended
+header record. When used with one of archive-reading commands,
+@command{tar} will behave as if it has encountered these keyword/value
+pairs at the beginning of the archive in a global extended header
+record.
+
+@item @var{keyword}:=@var{value}
+When used with one of archive-creation commands, these keyword/value pairs
+will be included as records at the beginning of an extended header for
+each file. This is effectively equivalent to @var{keyword}=@var{value}
+form except that it creates no global extended header records.
+
+When used with one of archive-reading commands, @command{tar} will
+behave as if these keyword/value pairs were included as records at the
+end of each extended header; thus, they will override any global or
+file-specific extended header record keywords of the same names.
+For example, in the command:
+
+@smallexample
+tar --format=posix --create \
+ --file archive --pax-option gname:=user .
+@end smallexample
+
+the group name will be forced to a new value for all files
+stored in the archive.
+@end table
+
+In any of the forms described above, the @var{value} may be
+a string enclosed in curly braces. In that case, the string
+between the braces is understood either as a textual time
+representation, as described in @ref{Date input formats}, or a name of
+the existing file, starting with @samp{/} or @samp{.}. In the latter
+case, the modification time of that file is used.
+
+For example, to set all modification times to the current date, you
+use the following option:
+
+@smallexample
+--pax-option='mtime:=@{now@}'
+@end smallexample
+
+Note quoting of the option's argument.
+
+@cindex archives, binary equivalent
+@cindex binary equivalent archives, creating
+As another example, here is the option that ensures that any two
+archives created using it, will be binary equivalent if they have the
+same contents:
+
+@smallexample
+--pax-option=exthdr.name=%d/PaxHeaders/%f,atime:=0
+@end smallexample
+
+@noindent
+If you extract files from such an archive and recreate the archive
+from them, you will also need to eliminate changes due to ctime, as
+shown in examples below:
+
+@smallexample
+--pax-option=exthdr.name=%d/PaxHeaders/%f,atime:=0,ctime:=0
+@end smallexample
+
+@noindent
+or
+
+@smallexample
+--pax-option=exthdr.name=%d/PaxHeaders/%f,atime:=0,delete=ctime
+@end smallexample
+
+@node Checksumming
+@subsection Checksumming Problems
+
+SunOS and HP-UX @command{tar} fail to accept archives created using
+@GNUTAR{} and containing non-@acronym{ASCII} file names, that
+is, file names having characters with the eighth bit set, because they
+use signed checksums, while @GNUTAR{} uses unsigned
+checksums while creating archives, as per @acronym{POSIX} standards. On
+reading, @GNUTAR{} computes both checksums and accepts either of them.
+It is somewhat worrying that a lot of people may go
+around doing backup of their files using faulty (or at least
+non-standard) software, not learning about it until it's time to
+restore their missing files with an incompatible file extractor, or
+vice versa.
+
+@GNUTAR{} computes checksums both ways, and accepts either of them
+on read, so @acronym{GNU} tar can read Sun tapes even with their
+wrong checksums. @GNUTAR{} produces the standard
+checksum, however, raising incompatibilities with Sun. That is to
+say, @GNUTAR{} has not been modified to
+@emph{produce} incorrect archives to be read by buggy @command{tar}'s.
+I've been told that more recent Sun @command{tar} now read standard
+archives, so maybe Sun did a similar patch, after all?
+
+The story seems to be that when Sun first imported @command{tar}
+sources on their system, they recompiled it without realizing that
+the checksums were computed differently, because of a change in
+the default signing of @code{char}'s in their compiler. So they
+started computing checksums wrongly. When they later realized their
+mistake, they merely decided to stay compatible with it, and with
+themselves afterwards. Presumably, but I do not really know, HP-UX
+has chosen their @command{tar} archives to be compatible with Sun's.
+The current standards do not favor Sun @command{tar} format. In any
+case, it now falls on the shoulders of SunOS and HP-UX users to get
+a @command{tar} able to read the good archives they receive.
+
+@node Large or Negative Values
+@subsection Large or Negative Values
+@cindex large values
+@cindex future time stamps
+@cindex negative time stamps
+@UNREVISED
+
+The above sections suggest to use @samp{oldest possible} archive
+format if in doubt. However, sometimes it is not possible. If you
+attempt to archive a file whose metadata cannot be represented using
+required format, @GNUTAR{} will print error message and ignore such a
+file. You will than have to switch to a format that is able to
+handle such values. The format summary table (@pxref{Formats}) will
+help you to do so.
+
+In particular, when trying to archive files larger than 8GB or with
+timestamps not in the range 1970-01-01 00:00:00 through 2242-03-16
+12:56:31 @sc{utc}, you will have to chose between @acronym{GNU} and
+@acronym{POSIX} archive formats. When considering which format to
+choose, bear in mind that the @acronym{GNU} format uses
+two's-complement base-256 notation to store values that do not fit
+into standard @acronym{ustar} range. Such archives can generally be
+read only by a @GNUTAR{} implementation. Moreover, they sometimes
+cannot be correctly restored on another hosts even by @GNUTAR{}. For
+example, using two's complement representation for negative time
+stamps that assumes a signed 32-bit @code{time_t} generates archives
+that are not portable to hosts with differing @code{time_t}
+representations.
+
+On the other hand, @acronym{POSIX} archives, generally speaking, can
+be extracted by any tar implementation that understands older
+@acronym{ustar} format. The only exception are files larger than 8GB.
+
+@FIXME{Describe how @acronym{POSIX} archives are extracted by non
+POSIX-aware tars.}
+
+@node Other Tars
+@subsection How to Extract GNU-Specific Data Using Other @command{tar} Implementations
+
+In previous sections you became acquainted with various quirks
+necessary to make your archives portable. Sometimes you may need to
+extract archives containing GNU-specific members using some
+third-party @command{tar} implementation or an older version of
+@GNUTAR{}. Of course your best bet is to have @GNUTAR{} installed,
+but if it is for some reason impossible, this section will explain
+how to cope without it.
+
+When we speak about @dfn{GNU-specific} members we mean two classes of
+them: members split between the volumes of a multi-volume archive and
+sparse members. You will be able to always recover such members if
+the archive is in PAX format. In addition split members can be
+recovered from archives in old GNU format. The following subsections
+describe the required procedures in detail.
+
+@menu
+* Split Recovery:: Members Split Between Volumes
+* Sparse Recovery:: Sparse Members
+@end menu
+
+@node Split Recovery
+@subsubsection Extracting Members Split Between Volumes
+
+@cindex Multi-volume archives, extracting using non-GNU tars
+If a member is split between several volumes of an old GNU format archive
+most third party @command{tar} implementation will fail to extract
+it. To extract it, use @command{tarcat} program (@pxref{Tarcat}).
+This program is available from
+@uref{http://www.gnu.org/@/software/@/tar/@/utils/@/tarcat.html, @GNUTAR{}
+home page}. It concatenates several archive volumes into a single
+valid archive. For example, if you have three volumes named from
+@file{vol-1.tar} to @file{vol-3.tar}, you can do the following to
+extract them using a third-party @command{tar}:
+
+@smallexample
+$ @kbd{tarcat vol-1.tar vol-2.tar vol-3.tar | tar xf -}
+@end smallexample
+
+@cindex Multi-volume archives in PAX format, extracting using non-GNU tars
+You could use this approach for most (although not all) PAX
+format archives as well. However, extracting split members from a PAX
+archive is a much easier task, because PAX volumes are constructed in
+such a way that each part of a split member is extracted to a
+different file by @command{tar} implementations that are not aware of
+GNU extensions. More specifically, the very first part retains its
+original name, and all subsequent parts are named using the pattern:
+
+@smallexample
+%d/GNUFileParts.%p/%f.%n
+@end smallexample
+
+@noindent
+where symbols preceded by @samp{%} are @dfn{macro characters} that
+have the following meaning:
+
+@multitable @columnfractions .25 .55
+@headitem Meta-character @tab Replaced By
+@item %d @tab The directory name of the file, equivalent to the
+result of the @command{dirname} utility on its full name.
+@item %f @tab The file name of the file, equivalent to the result
+of the @command{basename} utility on its full name.
+@item %p @tab The process @acronym{ID} of the @command{tar} process that
+created the archive.
+@item %n @tab Ordinal number of this particular part.
+@end multitable
+
+For example, if the file @file{var/longfile} was split during archive
+creation between three volumes, and the creator @command{tar} process
+had process @acronym{ID} @samp{27962}, then the member names will be:
+
+@smallexample
+var/longfile
+var/GNUFileParts.27962/longfile.1
+var/GNUFileParts.27962/longfile.2
+@end smallexample
+
+When you extract your archive using a third-party @command{tar}, these
+files will be created on your disk, and the only thing you will need
+to do to restore your file in its original form is concatenate them in
+the proper order, for example:
+
+@smallexample
+@group
+$ @kbd{cd var}
+$ @kbd{cat GNUFileParts.27962/longfile.1 \
+ GNUFileParts.27962/longfile.2 >> longfile}
+$ rm -f GNUFileParts.27962
+@end group
+@end smallexample
+
+Notice, that if the @command{tar} implementation you use supports PAX
+format archives, it will probably emit warnings about unknown keywords
+during extraction. They will look like this:
+
+@smallexample
+@group
+Tar file too small
+Unknown extended header keyword 'GNU.volume.filename' ignored.
+Unknown extended header keyword 'GNU.volume.size' ignored.
+Unknown extended header keyword 'GNU.volume.offset' ignored.
+@end group
+@end smallexample
+
+@noindent
+You can safely ignore these warnings.
+
+If your @command{tar} implementation is not PAX-aware, you will get
+more warnings and more files generated on your disk, e.g.:
+
+@smallexample
+@group
+$ @kbd{tar xf vol-1.tar}
+var/PaxHeaders.27962/longfile: Unknown file type 'x', extracted as
+normal file
+Unexpected EOF in archive
+$ @kbd{tar xf vol-2.tar}
+tmp/GlobalHead.27962.1: Unknown file type 'g', extracted as normal file
+GNUFileParts.27962/PaxHeaders.27962/sparsefile.1: Unknown file type
+'x', extracted as normal file
+@end group
+@end smallexample
+
+Ignore these warnings. The @file{PaxHeaders.*} directories created
+will contain files with @dfn{extended header keywords} describing the
+extracted files. You can delete them, unless they describe sparse
+members. Read further to learn more about them.
+
+@node Sparse Recovery
+@subsubsection Extracting Sparse Members
+
+@cindex sparse files, extracting with non-GNU tars
+Any @command{tar} implementation will be able to extract sparse members from a
+PAX archive. However, the extracted files will be @dfn{condensed},
+i.e., any zero blocks will be removed from them. When we restore such
+a condensed file to its original form, by adding zero blocks (or
+@dfn{holes}) back to their original locations, we call this process
+@dfn{expanding} a compressed sparse file.
+
+@pindex xsparse
+To expand a file, you will need a simple auxiliary program called
+@command{xsparse}. It is available in source form from
+@uref{http://www.gnu.org/@/software/@/tar/@/utils/@/xsparse.html, @GNUTAR{}
+home page}.
+
+@cindex sparse files v.1.0, extracting with non-GNU tars
+Let's begin with archive members in @dfn{sparse format
+version 1.0}@footnote{@xref{PAX 1}.}, which are the easiest to expand.
+The condensed file will contain both file map and file data, so no
+additional data will be needed to restore it. If the original file
+name was @file{@var{dir}/@var{name}}, then the condensed file will be
+named @file{@var{dir}/@/GNUSparseFile.@var{n}/@/@var{name}}, where
+@var{n} is a decimal number@footnote{Technically speaking, @var{n} is a
+@dfn{process @acronym{ID}} of the @command{tar} process which created the
+archive (@pxref{PAX keywords}).}.
+
+To expand a version 1.0 file, run @command{xsparse} as follows:
+
+@smallexample
+$ @kbd{xsparse @file{cond-file}}
+@end smallexample
+
+@noindent
+where @file{cond-file} is the name of the condensed file. The utility
+will deduce the name for the resulting expanded file using the
+following algorithm:
+
+@enumerate 1
+@item If @file{cond-file} does not contain any directories,
+@file{../cond-file} will be used;
+
+@item If @file{cond-file} has the form
+@file{@var{dir}/@var{t}/@var{name}}, where both @var{t} and @var{name}
+are simple names, with no @samp{/} characters in them, the output file
+name will be @file{@var{dir}/@var{name}}.
+
+@item Otherwise, if @file{cond-file} has the form
+@file{@var{dir}/@var{name}}, the output file name will be
+@file{@var{name}}.
+@end enumerate
+
+In the unlikely case when this algorithm does not suit your needs,
+you can explicitly specify output file name as a second argument to
+the command:
+
+@smallexample
+$ @kbd{xsparse @file{cond-file} @file{out-file}}
+@end smallexample
+
+It is often a good idea to run @command{xsparse} in @dfn{dry run} mode
+first. In this mode, the command does not actually expand the file,
+but verbosely lists all actions it would be taking to do so. The dry
+run mode is enabled by @option{-n} command line argument:
+
+@smallexample
+@group
+$ @kbd{xsparse -n /home/gray/GNUSparseFile.6058/sparsefile}
+Reading v.1.0 sparse map
+Expanding file '/home/gray/GNUSparseFile.6058/sparsefile' to
+'/home/gray/sparsefile'
+Finished dry run
+@end group
+@end smallexample
+
+To actually expand the file, you would run:
+
+@smallexample
+$ @kbd{xsparse /home/gray/GNUSparseFile.6058/sparsefile}
+@end smallexample
+
+@noindent
+The program behaves the same way all UNIX utilities do: it will keep
+quiet unless it has something important to tell you (e.g. an error
+condition or something). If you wish it to produce verbose output,
+similar to that from the dry run mode, use @option{-v} option:
+
+@smallexample
+@group
+$ @kbd{xsparse -v /home/gray/GNUSparseFile.6058/sparsefile}
+Reading v.1.0 sparse map
+Expanding file '/home/gray/GNUSparseFile.6058/sparsefile' to
+'/home/gray/sparsefile'
+Done
+@end group
+@end smallexample
+
+Additionally, if your @command{tar} implementation has extracted the
+@dfn{extended headers} for this file, you can instruct @command{xstar}
+to use them in order to verify the integrity of the expanded file.
+The option @option{-x} sets the name of the extended header file to
+use. Continuing our example:
+
+@smallexample
+@group
+$ @kbd{xsparse -v -x /home/gray/PaxHeaders.6058/sparsefile \
+ /home/gray/GNUSparseFile.6058/sparsefile}
+Reading extended header file
+Found variable GNU.sparse.major = 1
+Found variable GNU.sparse.minor = 0
+Found variable GNU.sparse.name = sparsefile
+Found variable GNU.sparse.realsize = 217481216
+Reading v.1.0 sparse map
+Expanding file '/home/gray/GNUSparseFile.6058/sparsefile' to
+'/home/gray/sparsefile'
+Done
+@end group
+@end smallexample
+
+@anchor{extracting sparse v.0.x}
+@cindex sparse files v.0.1, extracting with non-GNU tars
+@cindex sparse files v.0.0, extracting with non-GNU tars
+An @dfn{extended header} is a special @command{tar} archive header
+that precedes an archive member and contains a set of
+@dfn{variables}, describing the member properties that cannot be
+stored in the standard @code{ustar} header. While optional for
+expanding sparse version 1.0 members, the use of extended headers is
+mandatory when expanding sparse members in older sparse formats: v.0.0
+and v.0.1 (The sparse formats are described in detail in @ref{Sparse
+Formats}.) So, for these formats, the question is: how to obtain
+extended headers from the archive?
+
+If you use a @command{tar} implementation that does not support PAX
+format, extended headers for each member will be extracted as a
+separate file. If we represent the member name as
+@file{@var{dir}/@var{name}}, then the extended header file will be
+named @file{@var{dir}/@/PaxHeaders.@var{n}/@/@var{name}}, where
+@var{n} is an integer number.
+
+Things become more difficult if your @command{tar} implementation
+does support PAX headers, because in this case you will have to
+manually extract the headers. We recommend the following algorithm:
+
+@enumerate 1
+@item
+Consult the documentation of your @command{tar} implementation for an
+option that prints @dfn{block numbers} along with the archive
+listing (analogous to @GNUTAR{}'s @option{-R} option). For example,
+@command{star} has @option{-block-number}.
+
+@item
+Obtain verbose listing using the @samp{block number} option, and
+find block numbers of the sparse member in question and the member
+immediately following it. For example, running @command{star} on our
+archive we obtain:
+
+@smallexample
+@group
+$ @kbd{star -t -v -block-number -f arc.tar}
+@dots{}
+star: Unknown extended header keyword 'GNU.sparse.size' ignored.
+star: Unknown extended header keyword 'GNU.sparse.numblocks' ignored.
+star: Unknown extended header keyword 'GNU.sparse.name' ignored.
+star: Unknown extended header keyword 'GNU.sparse.map' ignored.
+block 56: 425984 -rw-r--r-- gray/users Jun 25 14:46 2006 GNUSparseFile.28124/sparsefile
+block 897: 65391 -rw-r--r-- gray/users Jun 24 20:06 2006 README
+@dots{}
+@end group
+@end smallexample
+
+@noindent
+(as usual, ignore the warnings about unknown keywords.)
+
+@item
+Let @var{size} be the size of the sparse member, @var{Bs} be its block number
+and @var{Bn} be the block number of the next member.
+Compute:
+
+@smallexample
+@var{N} = @var{Bs} - @var{Bn} - @var{size}/512 - 2
+@end smallexample
+
+@noindent
+This number gives the size of the extended header part in tar @dfn{blocks}.
+In our example, this formula gives: @code{897 - 56 - 425984 / 512 - 2
+= 7}.
+
+@item
+Use @command{dd} to extract the headers:
+
+@smallexample
+@kbd{dd if=@var{archive} of=@var{hname} bs=512 skip=@var{Bs} count=@var{N}}
+@end smallexample
+
+@noindent
+where @var{archive} is the archive name, @var{hname} is a name of the
+file to store the extended header in, @var{Bs} and @var{N} are
+computed in previous steps.
+
+In our example, this command will be
+
+@smallexample
+$ @kbd{dd if=arc.tar of=xhdr bs=512 skip=56 count=7}
+@end smallexample
+@end enumerate
+
+Finally, you can expand the condensed file, using the obtained header:
+
+@smallexample
+@group
+$ @kbd{xsparse -v -x xhdr GNUSparseFile.6058/sparsefile}
+Reading extended header file
+Found variable GNU.sparse.size = 217481216
+Found variable GNU.sparse.numblocks = 208
+Found variable GNU.sparse.name = sparsefile
+Found variable GNU.sparse.map = 0,2048,1050624,2048,@dots{}
+Expanding file 'GNUSparseFile.28124/sparsefile' to 'sparsefile'
+Done
+@end group
+@end smallexample
+
+@node cpio
+@section Comparison of @command{tar} and @command{cpio}
+@UNREVISED
+
+@FIXME{Reorganize the following material}
+
+The @command{cpio} archive formats, like @command{tar}, do have maximum
+file name lengths. The binary and old @acronym{ASCII} formats have a maximum file
+length of 256, and the new @acronym{ASCII} and @acronym{CRC ASCII} formats have a max
+file length of 1024. @acronym{GNU} @command{cpio} can read and write archives
+with arbitrary file name lengths, but other @command{cpio} implementations
+may crash unexplainedly trying to read them.
+
+@command{tar} handles symbolic links in the form in which it comes in @acronym{BSD};
+@command{cpio} doesn't handle symbolic links in the form in which it comes
+in System V prior to SVR4, and some vendors may have added symlinks
+to their system without enhancing @command{cpio} to know about them.
+Others may have enhanced it in a way other than the way I did it
+at Sun, and which was adopted by AT&T (and which is, I think, also
+present in the @command{cpio} that Berkeley picked up from AT&T and put
+into a later @acronym{BSD} release---I think I gave them my changes).
+
+(SVR4 does some funny stuff with @command{tar}; basically, its @command{cpio}
+can handle @command{tar} format input, and write it on output, and it
+probably handles symbolic links. They may not have bothered doing
+anything to enhance @command{tar} as a result.)
+
+@command{cpio} handles special files; traditional @command{tar} doesn't.
+
+@command{tar} comes with V7, System III, System V, and @acronym{BSD} source;
+@command{cpio} comes only with System III, System V, and later @acronym{BSD}
+(4.3-tahoe and later).
+
+@command{tar}'s way of handling multiple hard links to a file can handle
+file systems that support 32-bit i-numbers (e.g., the @acronym{BSD} file system);
+@command{cpio}s way requires you to play some games (in its ``binary''
+format, i-numbers are only 16 bits, and in its ``portable @acronym{ASCII}'' format,
+they're 18 bits---it would have to play games with the "file system @acronym{ID}"
+field of the header to make sure that the file system @acronym{ID}/i-number pairs
+of different files were always different), and I don't know which
+@command{cpio}s, if any, play those games. Those that don't might get
+confused and think two files are the same file when they're not, and
+make hard links between them.
+
+@command{tar}s way of handling multiple hard links to a file places only
+one copy of the link on the tape, but the name attached to that copy
+is the @emph{only} one you can use to retrieve the file; @command{cpio}s
+way puts one copy for every link, but you can retrieve it using any
+of the names.
+
+@quotation
+What type of check sum (if any) is used, and how is this calculated.
+@end quotation
+
+See the attached manual pages for @command{tar} and @command{cpio} format.
+@command{tar} uses a checksum which is the sum of all the bytes in the
+@command{tar} header for a file; @command{cpio} uses no checksum.
+
+@quotation
+If anyone knows why @command{cpio} was made when @command{tar} was present
+at the unix scene,
+@end quotation
+
+It wasn't. @command{cpio} first showed up in PWB/UNIX 1.0; no
+generally-available version of UNIX had @command{tar} at the time. I don't
+know whether any version that was generally available @emph{within AT&T}
+had @command{tar}, or, if so, whether the people within AT&T who did
+@command{cpio} knew about it.
+
+On restore, if there is a corruption on a tape @command{tar} will stop at
+that point, while @command{cpio} will skip over it and try to restore the
+rest of the files.
+
+The main difference is just in the command syntax and header format.
+
+@command{tar} is a little more tape-oriented in that everything is blocked
+to start on a record boundary.
+
+@quotation
+Is there any differences between the ability to recover crashed
+archives between the two of them. (Is there any chance of recovering
+crashed archives at all.)
+@end quotation
+
+Theoretically it should be easier under @command{tar} since the blocking
+lets you find a header with some variation of @samp{dd skip=@var{nn}}.
+However, modern @command{cpio}'s and variations have an option to just
+search for the next file header after an error with a reasonable chance
+of resyncing. However, lots of tape driver software won't allow you to
+continue past a media error which should be the only reason for getting
+out of sync unless a file changed sizes while you were writing the
+archive.
+
+@quotation
+If anyone knows why @command{cpio} was made when @command{tar} was present
+at the unix scene, please tell me about this too.
+@end quotation
+
+Probably because it is more media efficient (by not blocking everything
+and using only the space needed for the headers where @command{tar}
+always uses 512 bytes per file header) and it knows how to archive
+special files.
+
+You might want to look at the freely available alternatives. The
+major ones are @command{afio}, @GNUTAR{}, and
+@command{pax}, each of which have their own extensions with some
+backwards compatibility.
+
+Sparse files were @command{tar}red as sparse files (which you can
+easily test, because the resulting archive gets smaller, and
+@acronym{GNU} @command{cpio} can no longer read it).
+
+@node Media
+@chapter Tapes and Other Archive Media
+@UNREVISED
+
+A few special cases about tape handling warrant more detailed
+description. These special cases are discussed below.
+
+Many complexities surround the use of @command{tar} on tape drives. Since
+the creation and manipulation of archives located on magnetic tape was
+the original purpose of @command{tar}, it contains many features making
+such manipulation easier.
+
+Archives are usually written on dismountable media---tape cartridges,
+mag tapes, or floppy disks.
+
+The amount of data a tape or disk holds depends not only on its size,
+but also on how it is formatted. A 2400 foot long reel of mag tape
+holds 40 megabytes of data when formatted at 1600 bits per inch. The
+physically smaller EXABYTE tape cartridge holds 2.3 gigabytes.
+
+Magnetic media are re-usable---once the archive on a tape is no longer
+needed, the archive can be erased and the tape or disk used over.
+Media quality does deteriorate with use, however. Most tapes or disks
+should be discarded when they begin to produce data errors. EXABYTE
+tape cartridges should be discarded when they generate an @dfn{error
+count} (number of non-usable bits) of more than 10k.
+
+Magnetic media are written and erased using magnetic fields, and
+should be protected from such fields to avoid damage to stored data.
+Sticking a floppy disk to a filing cabinet using a magnet is probably
+not a good idea.
+
+@menu
+* Device:: Device selection and switching
+* Remote Tape Server::
+* Common Problems and Solutions::
+* Blocking:: Blocking
+* Many:: Many archives on one tape
+* Using Multiple Tapes:: Using Multiple Tapes
+* label:: Including a Label in the Archive
+* verify::
+* Write Protection::
+@end menu
+
+@node Device
+@section Device Selection and Switching
+@UNREVISED
+
+@table @option
+@item -f [@var{hostname}:]@var{file}
+@itemx --file=[@var{hostname}:]@var{file}
+Use archive file or device @var{file} on @var{hostname}.
+@end table
+
+This option is used to specify the file name of the archive @command{tar}
+works on.
+
+If the file name is @samp{-}, @command{tar} reads the archive from standard
+input (when listing or extracting), or writes it to standard output
+(when creating). If the @samp{-} file name is given when updating an
+archive, @command{tar} will read the original archive from its standard
+input, and will write the entire new archive to its standard output.
+
+If the file name contains a @samp{:}, it is interpreted as
+@samp{hostname:file name}. If the @var{hostname} contains an @dfn{at}
+sign (@samp{@@}), it is treated as @samp{user@@hostname:file name}. In
+either case, @command{tar} will invoke the command @command{rsh} (or
+@command{remsh}) to start up an @command{/usr/libexec/rmt} on the remote
+machine. If you give an alternate login name, it will be given to the
+@command{rsh}.
+Naturally, the remote machine must have an executable
+@command{/usr/libexec/rmt}. This program is free software from the
+University of California, and a copy of the source code can be found
+with the sources for @command{tar}; it's compiled and installed by default.
+The exact path to this utility is determined when configuring the package.
+It is @file{@var{prefix}/libexec/rmt}, where @var{prefix} stands for
+your installation prefix. This location may also be overridden at
+runtime by using the @option{--rmt-command=@var{command}} option (@xref{Option Summary,
+---rmt-command}, for detailed description of this option. @xref{Remote
+Tape Server}, for the description of @command{rmt} command).
+
+If this option is not given, but the environment variable @env{TAPE}
+is set, its value is used; otherwise, old versions of @command{tar}
+used a default archive name (which was picked when @command{tar} was
+compiled). The default is normally set up to be the @dfn{first} tape
+drive or other transportable I/O medium on the system.
+
+Starting with version 1.11.5, @GNUTAR{} uses
+standard input and standard output as the default device, and I will
+not try anymore supporting automatic device detection at installation
+time. This was failing really in too many cases, it was hopeless.
+This is now completely left to the installer to override standard
+input and standard output for default device, if this seems
+preferable. Further, I think @emph{most} actual usages of
+@command{tar} are done with pipes or disks, not really tapes,
+cartridges or diskettes.
+
+Some users think that using standard input and output is running
+after trouble. This could lead to a nasty surprise on your screen if
+you forget to specify an output file name---especially if you are going
+through a network or terminal server capable of buffering large amounts
+of output. We had so many bug reports in that area of configuring
+default tapes automatically, and so many contradicting requests, that
+we finally consider the problem to be portably intractable. We could
+of course use something like @samp{/dev/tape} as a default, but this
+is @emph{also} running after various kind of trouble, going from hung
+processes to accidental destruction of real tapes. After having seen
+all this mess, using standard input and output as a default really
+sounds like the only clean choice left, and a very useful one too.
+
+@GNUTAR{} reads and writes archive in records, I
+suspect this is the main reason why block devices are preferred over
+character devices. Most probably, block devices are more efficient
+too. The installer could also check for @samp{DEFTAPE} in
+@file{<sys/mtio.h>}.
+
+@table @option
+@xopindex{force-local, short description}
+@item --force-local
+Archive file is local even if it contains a colon.
+
+@opindex rsh-command
+@item --rsh-command=@var{command}
+Use remote @var{command} instead of @command{rsh}. This option exists
+so that people who use something other than the standard @command{rsh}
+(e.g., a Kerberized @command{rsh}) can access a remote device.
+
+When this command is not used, the shell command found when
+the @command{tar} program was installed is used instead. This is
+the first found of @file{/usr/ucb/rsh}, @file{/usr/bin/remsh},
+@file{/usr/bin/rsh}, @file{/usr/bsd/rsh} or @file{/usr/bin/nsh}.
+The installer may have overridden this by defining the environment
+variable @env{RSH} @emph{at installation time}.
+
+@item -[0-7][lmh]
+Specify drive and density.
+
+@xopindex{multi-volume, short description}
+@item -M
+@itemx --multi-volume
+Create/list/extract multi-volume archive.
+
+This option causes @command{tar} to write a @dfn{multi-volume} archive---one
+that may be larger than will fit on the medium used to hold it.
+@xref{Multi-Volume Archives}.
+
+@xopindex{tape-length, short description}
+@item -L @var{num}
+@itemx --tape-length=@var{size}[@var{suf}]
+Change tape after writing @var{size} units of data. Unless @var{suf} is
+given, @var{size} is treated as kilobytes, i.e. @samp{@var{size} x
+1024} bytes. The following suffixes alter this behavior:
+
+@float Table, size-suffixes
+@caption{Size Suffixes}
+@multitable @columnfractions 0.2 0.3 0.3
+@headitem Suffix @tab Units @tab Byte Equivalent
+@item b @tab Blocks @tab @var{size} x 512
+@item B @tab Kilobytes @tab @var{size} x 1024
+@item c @tab Bytes @tab @var{size}
+@item G @tab Gigabytes @tab @var{size} x 1024^3
+@item K @tab Kilobytes @tab @var{size} x 1024
+@item k @tab Kilobytes @tab @var{size} x 1024
+@item M @tab Megabytes @tab @var{size} x 1024^2
+@item P @tab Petabytes @tab @var{size} x 1024^5
+@item T @tab Terabytes @tab @var{size} x 1024^4
+@item w @tab Words @tab @var{size} x 2
+@end multitable
+@end float
+
+This option might be useful when your tape drivers do not properly
+detect end of physical tapes. By being slightly conservative on the
+maximum tape length, you might avoid the problem entirely.
+
+@xopindex{info-script, short description}
+@xopindex{new-volume-script, short description}
+@item -F @var{command}
+@itemx --info-script=@var{command}
+@itemx --new-volume-script=@var{command}
+Execute @var{command} at end of each tape. This implies
+@option{--multi-volume} (@option{-M}). @xref{info-script}, for a detailed
+description of this option.
+@end table
+
+@node Remote Tape Server
+@section Remote Tape Server
+
+@cindex remote tape drive
+@pindex rmt
+In order to access the tape drive on a remote machine, @command{tar}
+uses the remote tape server written at the University of California at
+Berkeley. The remote tape server must be installed as
+@file{@var{prefix}/libexec/rmt} on any machine whose tape drive you
+want to use. @command{tar} calls @command{rmt} by running an
+@command{rsh} or @command{remsh} to the remote machine, optionally
+using a different login name if one is supplied.
+
+A copy of the source for the remote tape server is provided. Its
+source code can be freely distributed. It is compiled and
+installed by default.
+
+@cindex absolute file names
+Unless you use the @option{--absolute-names} (@option{-P}) option,
+@GNUTAR{} will not allow you to create an archive that contains
+absolute file names (a file name beginning with @samp{/}). If you try,
+@command{tar} will automatically remove the leading @samp{/} from the
+file names it stores in the archive. It will also type a warning
+message telling you what it is doing.
+
+When reading an archive that was created with a different
+@command{tar} program, @GNUTAR{} automatically
+extracts entries in the archive which have absolute file names as if
+the file names were not absolute. This is an important feature. A
+visitor here once gave a @command{tar} tape to an operator to restore;
+the operator used Sun @command{tar} instead of @GNUTAR{},
+and the result was that it replaced large portions of
+our @file{/bin} and friends with versions from the tape; needless to
+say, we were unhappy about having to recover the file system from
+backup tapes.
+
+For example, if the archive contained a file @file{/usr/bin/computoy},
+@GNUTAR{} would extract the file to @file{usr/bin/computoy},
+relative to the current directory. If you want to extract the files in
+an archive to the same absolute names that they had when the archive
+was created, you should do a @samp{cd /} before extracting the files
+from the archive, or you should either use the @option{--absolute-names}
+option, or use the command @samp{tar -C / @dots{}}.
+
+@cindex Ultrix 3.1 and write failure
+Some versions of Unix (Ultrix 3.1 is known to have this problem),
+can claim that a short write near the end of a tape succeeded,
+when it actually failed. This will result in the -M option not
+working correctly. The best workaround at the moment is to use a
+significantly larger blocking factor than the default 20.
+
+In order to update an archive, @command{tar} must be able to backspace the
+archive in order to reread or rewrite a record that was just read (or
+written). This is currently possible only on two kinds of files: normal
+disk files (or any other file that can be backspaced with @samp{lseek}),
+and industry-standard 9-track magnetic tape (or any other kind of tape
+that can be backspaced with the @code{MTIOCTOP} @code{ioctl}).
+
+This means that the @option{--append}, @option{--concatenate}, and
+@option{--delete} commands will not work on any other kind of file.
+Some media simply cannot be backspaced, which means these commands and
+options will never be able to work on them. These non-backspacing
+media include pipes and cartridge tape drives.
+
+Some other media can be backspaced, and @command{tar} will work on them
+once @command{tar} is modified to do so.
+
+Archives created with the @option{--multi-volume}, @option{--label}, and
+@option{--incremental} (@option{-G}) options may not be readable by other version
+of @command{tar}. In particular, restoring a file that was split over
+a volume boundary will require some careful work with @command{dd}, if
+it can be done at all. Other versions of @command{tar} may also create
+an empty file whose name is that of the volume header. Some versions
+of @command{tar} may create normal files instead of directories archived
+with the @option{--incremental} (@option{-G}) option.
+
+@node Common Problems and Solutions
+@section Some Common Problems and their Solutions
+
+@ifclear PUBLISH
+
+@format
+errors from system:
+permission denied
+no such file or directory
+not owner
+
+errors from @command{tar}:
+directory checksum error
+header format error
+
+errors from media/system:
+i/o error
+device busy
+@end format
+
+@end ifclear
+
+@node Blocking
+@section Blocking
+@cindex block
+@cindex record
+
+@dfn{Block} and @dfn{record} terminology is rather confused, and it
+is also confusing to the expert reader. On the other hand, readers
+who are new to the field have a fresh mind, and they may safely skip
+the next two paragraphs, as the remainder of this manual uses those
+two terms in a quite consistent way.
+
+John Gilmore, the writer of the public domain @command{tar} from which
+@GNUTAR{} was originally derived, wrote (June 1995):
+
+@quotation
+The nomenclature of tape drives comes from IBM, where I believe
+they were invented for the IBM 650 or so. On IBM mainframes, what
+is recorded on tape are tape blocks. The logical organization of
+data is into records. There are various ways of putting records into
+blocks, including @code{F} (fixed sized records), @code{V} (variable
+sized records), @code{FB} (fixed blocked: fixed size records, @var{n}
+to a block), @code{VB} (variable size records, @var{n} to a block),
+@code{VSB} (variable spanned blocked: variable sized records that can
+occupy more than one block), etc. The @code{JCL} @samp{DD RECFORM=}
+parameter specified this to the operating system.
+
+The Unix man page on @command{tar} was totally confused about this.
+When I wrote @code{PD TAR}, I used the historically correct terminology
+(@command{tar} writes data records, which are grouped into blocks).
+It appears that the bogus terminology made it into @acronym{POSIX} (no surprise
+here), and now Fran@,{c}ois has migrated that terminology back
+into the source code too.
+@end quotation
+
+The term @dfn{physical block} means the basic transfer chunk from or
+to a device, after which reading or writing may stop without anything
+being lost. In this manual, the term @dfn{block} usually refers to
+a disk physical block, @emph{assuming} that each disk block is 512
+bytes in length. It is true that some disk devices have different
+physical blocks, but @command{tar} ignore these differences in its own
+format, which is meant to be portable, so a @command{tar} block is always
+512 bytes in length, and @dfn{block} always mean a @command{tar} block.
+The term @dfn{logical block} often represents the basic chunk of
+allocation of many disk blocks as a single entity, which the operating
+system treats somewhat atomically; this concept is only barely used
+in @GNUTAR{}.
+
+The term @dfn{physical record} is another way to speak of a physical
+block, those two terms are somewhat interchangeable. In this manual,
+the term @dfn{record} usually refers to a tape physical block,
+@emph{assuming} that the @command{tar} archive is kept on magnetic tape.
+It is true that archives may be put on disk or used with pipes,
+but nevertheless, @command{tar} tries to read and write the archive one
+@dfn{record} at a time, whatever the medium in use. One record is made
+up of an integral number of blocks, and this operation of putting many
+disk blocks into a single tape block is called @dfn{reblocking}, or
+more simply, @dfn{blocking}. The term @dfn{logical record} refers to
+the logical organization of many characters into something meaningful
+to the application. The term @dfn{unit record} describes a small set
+of characters which are transmitted whole to or by the application,
+and often refers to a line of text. Those two last terms are unrelated
+to what we call a @dfn{record} in @GNUTAR{}.
+
+When writing to tapes, @command{tar} writes the contents of the archive
+in chunks known as @dfn{records}. To change the default blocking
+factor, use the @option{--blocking-factor=@var{512-size}} (@option{-b
+@var{512-size}}) option. Each record will then be composed of
+@var{512-size} blocks. (Each @command{tar} block is 512 bytes.
+@xref{Standard}.) Each file written to the archive uses at least one
+full record. As a result, using a larger record size can result in
+more wasted space for small files. On the other hand, a larger record
+size can often be read and written much more efficiently.
+
+Further complicating the problem is that some tape drives ignore the
+blocking entirely. For these, a larger record size can still improve
+performance (because the software layers above the tape drive still
+honor the blocking), but not as dramatically as on tape drives that
+honor blocking.
+
+When reading an archive, @command{tar} can usually figure out the
+record size on itself. When this is the case, and a non-standard
+record size was used when the archive was created, @command{tar} will
+print a message about a non-standard blocking factor, and then operate
+normally@footnote{If this message is not needed, you can turn it off
+using the @option{--warning=no-record-size} option.}. On some tape
+devices, however, @command{tar} cannot figure out the record size
+itself. On most of those, you can specify a blocking factor (with
+@option{--blocking-factor}) larger than the actual blocking factor,
+and then use the @option{--read-full-records} (@option{-B}) option.
+(If you specify a blocking factor with @option{--blocking-factor} and
+don't use the @option{--read-full-records} option, then @command{tar}
+will not attempt to figure out the recording size itself.) On some
+devices, you must always specify the record size exactly with
+@option{--blocking-factor} when reading, because @command{tar} cannot
+figure it out. In any case, use @option{--list} (@option{-t}) before
+doing any extractions to see whether @command{tar} is reading the archive
+correctly.
+
+@command{tar} blocks are all fixed size (512 bytes), and its scheme for
+putting them into records is to put a whole number of them (one or
+more) into each record. @command{tar} records are all the same size;
+at the end of the file there's a block containing all zeros, which
+is how you tell that the remainder of the last record(s) are garbage.
+
+In a standard @command{tar} file (no options), the block size is 512
+and the record size is 10240, for a blocking factor of 20. What the
+@option{--blocking-factor} option does is sets the blocking factor,
+changing the record size while leaving the block size at 512 bytes.
+20 was fine for ancient 800 or 1600 bpi reel-to-reel tape drives;
+most tape drives these days prefer much bigger records in order to
+stream and not waste tape. When writing tapes for myself, some tend
+to use a factor of the order of 2048, say, giving a record size of
+around one megabyte.
+
+If you use a blocking factor larger than 20, older @command{tar}
+programs might not be able to read the archive, so we recommend this
+as a limit to use in practice. @GNUTAR{}, however,
+will support arbitrarily large record sizes, limited only by the
+amount of virtual memory or the physical characteristics of the tape
+device.
+
+@menu
+* Format Variations:: Format Variations
+* Blocking Factor:: The Blocking Factor of an Archive
+@end menu
+
+@node Format Variations
+@subsection Format Variations
+@cindex Format Parameters
+@cindex Format Options
+@cindex Options, archive format specifying
+@cindex Options, format specifying
+@UNREVISED
+
+Format parameters specify how an archive is written on the archive
+media. The best choice of format parameters will vary depending on
+the type and number of files being archived, and on the media used to
+store the archive.
+
+To specify format parameters when accessing or creating an archive,
+you can use the options described in the following sections.
+If you do not specify any format parameters, @command{tar} uses
+default parameters. You cannot modify a compressed archive.
+If you create an archive with the @option{--blocking-factor} option
+specified (@pxref{Blocking Factor}), you must specify that
+blocking-factor when operating on the archive. @xref{Formats}, for other
+examples of format parameter considerations.
+
+@node Blocking Factor
+@subsection The Blocking Factor of an Archive
+@cindex Blocking Factor
+@cindex Record Size
+@cindex Number of blocks per record
+@cindex Number of bytes per record
+@cindex Bytes per record
+@cindex Blocks per record
+@UNREVISED
+
+@opindex blocking-factor
+The data in an archive is grouped into blocks, which are 512 bytes.
+Blocks are read and written in whole number multiples called
+@dfn{records}. The number of blocks in a record (i.e., the size of a
+record in units of 512 bytes) is called the @dfn{blocking factor}.
+The @option{--blocking-factor=@var{512-size}} (@option{-b
+@var{512-size}}) option specifies the blocking factor of an archive.
+The default blocking factor is typically 20 (i.e., 10240 bytes), but
+can be specified at installation. To find out the blocking factor of
+an existing archive, use @samp{tar --list --file=@var{archive-name}}.
+This may not work on some devices.
+
+Records are separated by gaps, which waste space on the archive media.
+If you are archiving on magnetic tape, using a larger blocking factor
+(and therefore larger records) provides faster throughput and allows you
+to fit more data on a tape (because there are fewer gaps). If you are
+archiving on cartridge, a very large blocking factor (say 126 or more)
+greatly increases performance. A smaller blocking factor, on the other
+hand, may be useful when archiving small files, to avoid archiving lots
+of nulls as @command{tar} fills out the archive to the end of the record.
+In general, the ideal record size depends on the size of the
+inter-record gaps on the tape you are using, and the average size of the
+files you are archiving. @xref{create}, for information on
+writing archives.
+
+@FIXME{Need example of using a cartridge with blocking factor=126 or more.}
+
+Archives with blocking factors larger than 20 cannot be read
+by very old versions of @command{tar}, or by some newer versions
+of @command{tar} running on old machines with small address spaces.
+With @GNUTAR{}, the blocking factor of an archive is limited
+only by the maximum record size of the device containing the archive,
+or by the amount of available virtual memory.
+
+Also, on some systems, not using adequate blocking factors, as sometimes
+imposed by the device drivers, may yield unexpected diagnostics. For
+example, this has been reported:
+
+@smallexample
+Cannot write to /dev/dlt: Invalid argument
+@end smallexample
+
+@noindent
+In such cases, it sometimes happen that the @command{tar} bundled by
+the system is aware of block size idiosyncrasies, while @GNUTAR{}
+requires an explicit specification for the block size,
+which it cannot guess. This yields some people to consider
+@GNUTAR{} is misbehaving, because by comparison,
+@cite{the bundle @command{tar} works OK}. Adding @w{@kbd{-b 256}},
+for example, might resolve the problem.
+
+If you use a non-default blocking factor when you create an archive, you
+must specify the same blocking factor when you modify that archive. Some
+archive devices will also require you to specify the blocking factor when
+reading that archive, however this is not typically the case. Usually, you
+can use @option{--list} (@option{-t}) without specifying a blocking factor---@command{tar}
+reports a non-default record size and then lists the archive members as
+it would normally. To extract files from an archive with a non-standard
+blocking factor (particularly if you're not sure what the blocking factor
+is), you can usually use the @option{--read-full-records} (@option{-B}) option while
+specifying a blocking factor larger then the blocking factor of the archive
+(i.e., @samp{tar --extract --read-full-records --blocking-factor=300}).
+@xref{list}, for more information on the @option{--list} (@option{-t})
+operation. @xref{Reading}, for a more detailed explanation of that option.
+
+@table @option
+@item --blocking-factor=@var{number}
+@itemx -b @var{number}
+Specifies the blocking factor of an archive. Can be used with any
+operation, but is usually not necessary with @option{--list} (@option{-t}).
+@end table
+
+Device blocking
+
+@table @option
+@item -b @var{blocks}
+@itemx --blocking-factor=@var{blocks}
+Set record size to @math{@var{blocks}*512} bytes.
+
+This option is used to specify a @dfn{blocking factor} for the archive.
+When reading or writing the archive, @command{tar}, will do reads and writes
+of the archive in records of @math{@var{block}*512} bytes. This is true
+even when the archive is compressed. Some devices requires that all
+write operations be a multiple of a certain size, and so, @command{tar}
+pads the archive out to the next record boundary.
+
+The default blocking factor is set when @command{tar} is compiled, and is
+typically 20. Blocking factors larger than 20 cannot be read by very
+old versions of @command{tar}, or by some newer versions of @command{tar}
+running on old machines with small address spaces.
+
+With a magnetic tape, larger records give faster throughput and fit
+more data on a tape (because there are fewer inter-record gaps).
+If the archive is in a disk file or a pipe, you may want to specify
+a smaller blocking factor, since a large one will result in a large
+number of null bytes at the end of the archive.
+
+When writing cartridge or other streaming tapes, a much larger
+blocking factor (say 126 or more) will greatly increase performance.
+However, you must specify the same blocking factor when reading or
+updating the archive.
+
+Apparently, Exabyte drives have a physical block size of 8K bytes.
+If we choose our blocksize as a multiple of 8k bytes, then the problem
+seems to disappear. Id est, we are using block size of 112 right
+now, and we haven't had the problem since we switched@dots{}
+
+With @GNUTAR{} the blocking factor is limited only
+by the maximum record size of the device containing the archive, or by
+the amount of available virtual memory.
+
+However, deblocking or reblocking is virtually avoided in a special
+case which often occurs in practice, but which requires all the
+following conditions to be simultaneously true:
+@itemize @bullet
+@item
+the archive is subject to a compression option,
+@item
+the archive is not handled through standard input or output, nor
+redirected nor piped,
+@item
+the archive is directly handled to a local disk, instead of any special
+device,
+@item
+@option{--blocking-factor} is not explicitly specified on the @command{tar}
+invocation.
+@end itemize
+
+If the output goes directly to a local disk, and not through
+stdout, then the last write is not extended to a full record size.
+Otherwise, reblocking occurs. Here are a few other remarks on this
+topic:
+
+@itemize @bullet
+
+@item
+@command{gzip} will complain about trailing garbage if asked to
+uncompress a compressed archive on tape, there is an option to turn
+the message off, but it breaks the regularity of simply having to use
+@samp{@var{prog} -d} for decompression. It would be nice if gzip was
+silently ignoring any number of trailing zeros. I'll ask Jean-loup
+Gailly, by sending a copy of this message to him.
+
+@item
+@command{compress} does not show this problem, but as Jean-loup pointed
+out to Michael, @samp{compress -d} silently adds garbage after
+the result of decompression, which tar ignores because it already
+recognized its end-of-file indicator. So this bug may be safely
+ignored.
+
+@item
+@samp{gzip -d -q} will be silent about the trailing zeros indeed,
+but will still return an exit status of 2 which tar reports in turn.
+@command{tar} might ignore the exit status returned, but I hate doing
+that, as it weakens the protection @command{tar} offers users against
+other possible problems at decompression time. If @command{gzip} was
+silently skipping trailing zeros @emph{and} also avoiding setting the
+exit status in this innocuous case, that would solve this situation.
+
+@item
+@command{tar} should become more solid at not stopping to read a pipe at
+the first null block encountered. This inelegantly breaks the pipe.
+@command{tar} should rather drain the pipe out before exiting itself.
+@end itemize
+
+@xopindex{ignore-zeros, short description}
+@item -i
+@itemx --ignore-zeros
+Ignore blocks of zeros in archive (means EOF).
+
+The @option{--ignore-zeros} (@option{-i}) option causes @command{tar} to ignore blocks
+of zeros in the archive. Normally a block of zeros indicates the
+end of the archive, but when reading a damaged archive, or one which
+was created by concatenating several archives together, this option
+allows @command{tar} to read the entire archive. This option is not on
+by default because many versions of @command{tar} write garbage after
+the zeroed blocks.
+
+Note that this option causes @command{tar} to read to the end of the
+archive file, which may sometimes avoid problems when multiple files
+are stored on a single physical tape.
+
+@xopindex{read-full-records, short description}
+@item -B
+@itemx --read-full-records
+Reblock as we read (for reading 4.2@acronym{BSD} pipes).
+
+If @option{--read-full-records} is used, @command{tar}
+will not panic if an attempt to read a record from the archive does
+not return a full record. Instead, @command{tar} will keep reading
+until it has obtained a full
+record.
+
+This option is turned on by default when @command{tar} is reading
+an archive from standard input, or from a remote machine. This is
+because on @acronym{BSD} Unix systems, a read of a pipe will return however
+much happens to be in the pipe, even if it is less than @command{tar}
+requested. If this option was not used, @command{tar} would fail as
+soon as it read an incomplete record from the pipe.
+
+This option is also useful with the commands for updating an archive.
+
+@end table
+
+Tape blocking
+
+@FIXME{Appropriate options should be moved here from elsewhere.}
+
+@cindex blocking factor
+@cindex tape blocking
+
+When handling various tapes or cartridges, you have to take care of
+selecting a proper blocking, that is, the number of disk blocks you
+put together as a single tape block on the tape, without intervening
+tape gaps. A @dfn{tape gap} is a small landing area on the tape
+with no information on it, used for decelerating the tape to a
+full stop, and for later regaining the reading or writing speed.
+When the tape driver starts reading a record, the record has to
+be read whole without stopping, as a tape gap is needed to stop the
+tape motion without losing information.
+
+@cindex Exabyte blocking
+@cindex DAT blocking
+Using higher blocking (putting more disk blocks per tape block) will use
+the tape more efficiently as there will be less tape gaps. But reading
+such tapes may be more difficult for the system, as more memory will be
+required to receive at once the whole record. Further, if there is a
+reading error on a huge record, this is less likely that the system will
+succeed in recovering the information. So, blocking should not be too
+low, nor it should be too high. @command{tar} uses by default a blocking of
+20 for historical reasons, and it does not really matter when reading or
+writing to disk. Current tape technology would easily accommodate higher
+blockings. Sun recommends a blocking of 126 for Exabytes and 96 for DATs.
+We were told that for some DLT drives, the blocking should be a multiple
+of 4Kb, preferably 64Kb (@w{@kbd{-b 128}}) or 256 for decent performance.
+Other manufacturers may use different recommendations for the same tapes.
+This might also depends of the buffering techniques used inside modern
+tape controllers. Some imposes a minimum blocking, or a maximum blocking.
+Others request blocking to be some exponent of two.
+
+So, there is no fixed rule for blocking. But blocking at read time
+should ideally be the same as blocking used at write time. At one place
+I know, with a wide variety of equipment, they found it best to use a
+blocking of 32 to guarantee that their tapes are fully interchangeable.
+
+I was also told that, for recycled tapes, prior erasure (by the same
+drive unit that will be used to create the archives) sometimes lowers
+the error rates observed at rewriting time.
+
+I might also use @option{--number-blocks} instead of
+@option{--block-number}, so @option{--block} will then expand to
+@option{--blocking-factor} unambiguously.
+
+@node Many
+@section Many Archives on One Tape
+
+@FIXME{Appropriate options should be moved here from elsewhere.}
+
+@findex ntape @r{device}
+Most tape devices have two entries in the @file{/dev} directory, or
+entries that come in pairs, which differ only in the minor number for
+this device. Let's take for example @file{/dev/tape}, which often
+points to the only or usual tape device of a given system. There might
+be a corresponding @file{/dev/nrtape} or @file{/dev/ntape}. The simpler
+name is the @emph{rewinding} version of the device, while the name
+having @samp{nr} in it is the @emph{no rewinding} version of the same
+device.
+
+A rewinding tape device will bring back the tape to its beginning point
+automatically when this device is opened or closed. Since @command{tar}
+opens the archive file before using it and closes it afterwards, this
+means that a simple:
+
+@smallexample
+$ @kbd{tar cf /dev/tape @var{directory}}
+@end smallexample
+
+@noindent
+will reposition the tape to its beginning both prior and after saving
+@var{directory} contents to it, thus erasing prior tape contents and
+making it so that any subsequent write operation will destroy what has
+just been saved.
+
+@cindex tape positioning
+So, a rewinding device is normally meant to hold one and only one file.
+If you want to put more than one @command{tar} archive on a given tape, you
+will need to avoid using the rewinding version of the tape device. You
+will also have to pay special attention to tape positioning. Errors in
+positioning may overwrite the valuable data already on your tape. Many
+people, burnt by past experiences, will only use rewinding devices and
+limit themselves to one file per tape, precisely to avoid the risk of
+such errors. Be fully aware that writing at the wrong position on a
+tape loses all information past this point and most probably until the
+end of the tape, and this destroyed information @emph{cannot} be
+recovered.
+
+To save @var{directory-1} as a first archive at the beginning of a
+tape, and leave that tape ready for a second archive, you should use:
+
+@smallexample
+$ @kbd{mt -f /dev/nrtape rewind}
+$ @kbd{tar cf /dev/nrtape @var{directory-1}}
+@end smallexample
+
+@cindex tape marks
+@dfn{Tape marks} are special magnetic patterns written on the tape
+media, which are later recognizable by the reading hardware. These
+marks are used after each file, when there are many on a single tape.
+An empty file (that is to say, two tape marks in a row) signal the
+logical end of the tape, after which no file exist. Usually,
+non-rewinding tape device drivers will react to the close request issued
+by @command{tar} by first writing two tape marks after your archive, and by
+backspacing over one of these. So, if you remove the tape at that time
+from the tape drive, it is properly terminated. But if you write
+another file at the current position, the second tape mark will be
+erased by the new information, leaving only one tape mark between files.
+
+So, you may now save @var{directory-2} as a second archive after the
+first on the same tape by issuing the command:
+
+@smallexample
+$ @kbd{tar cf /dev/nrtape @var{directory-2}}
+@end smallexample
+
+@noindent
+and so on for all the archives you want to put on the same tape.
+
+Another usual case is that you do not write all the archives the same
+day, and you need to remove and store the tape between two archive
+sessions. In general, you must remember how many files are already
+saved on your tape. Suppose your tape already has 16 files on it, and
+that you are ready to write the 17th. You have to take care of skipping
+the first 16 tape marks before saving @var{directory-17}, say, by using
+these commands:
+
+@smallexample
+$ @kbd{mt -f /dev/nrtape rewind}
+$ @kbd{mt -f /dev/nrtape fsf 16}
+$ @kbd{tar cf /dev/nrtape @var{directory-17}}
+@end smallexample
+
+In all the previous examples, we put aside blocking considerations, but
+you should do the proper things for that as well. @xref{Blocking}.
+
+@menu
+* Tape Positioning:: Tape Positions and Tape Marks
+* mt:: The @command{mt} Utility
+@end menu
+
+@node Tape Positioning
+@subsection Tape Positions and Tape Marks
+@UNREVISED
+
+Just as archives can store more than one file from the file system,
+tapes can store more than one archive file. To keep track of where
+archive files (or any other type of file stored on tape) begin and
+end, tape archive devices write magnetic @dfn{tape marks} on the
+archive media. Tape drives write one tape mark between files,
+two at the end of all the file entries.
+
+If you think of data as a series of records "rrrr"'s, and tape marks as
+"*"'s, a tape might look like the following:
+
+@smallexample
+rrrr*rrrrrr*rrrrr*rr*rrrrr**-------------------------
+@end smallexample
+
+Tape devices read and write tapes using a read/write @dfn{tape
+head}---a physical part of the device which can only access one
+point on the tape at a time. When you use @command{tar} to read or
+write archive data from a tape device, the device will begin reading
+or writing from wherever on the tape the tape head happens to be,
+regardless of which archive or what part of the archive the tape
+head is on. Before writing an archive, you should make sure that no
+data on the tape will be overwritten (unless it is no longer needed).
+Before reading an archive, you should make sure the tape head is at
+the beginning of the archive you want to read. You can do it manually
+via @code{mt} utility (@pxref{mt}). The @code{restore} script does
+that automatically (@pxref{Scripted Restoration}).
+
+If you want to add new archive file entries to a tape, you should
+advance the tape to the end of the existing file entries, backspace
+over the last tape mark, and write the new archive file. If you were
+to add two archives to the example above, the tape might look like the
+following:
+
+@smallexample
+rrrr*rrrrrr*rrrrr*rr*rrrrr*rrr*rrrr**----------------
+@end smallexample
+
+@node mt
+@subsection The @command{mt} Utility
+@UNREVISED
+
+@FIXME{Is it true that this only works on non-block devices?
+should explain the difference, (fixed or variable).}
+@xref{Blocking Factor}.
+
+You can use the @command{mt} utility to advance or rewind a tape past a
+specified number of archive files on the tape. This will allow you
+to move to the beginning of an archive before extracting or reading
+it, or to the end of all the archives before writing a new one.
+@FIXME{Why isn't there an "advance 'til you find two tape marks
+together"?}
+
+The syntax of the @command{mt} command is:
+
+@smallexample
+@kbd{mt [-f @var{tapename}] @var{operation} [@var{number}]}
+@end smallexample
+
+where @var{tapename} is the name of the tape device, @var{number} is
+the number of times an operation is performed (with a default of one),
+and @var{operation} is one of the following:
+
+@FIXME{is there any use for record operations?}
+
+@table @option
+@item eof
+@itemx weof
+Writes @var{number} tape marks at the current position on the tape.
+
+@item fsf
+Moves tape position forward @var{number} files.
+
+@item bsf
+Moves tape position back @var{number} files.
+
+@item rewind
+Rewinds the tape. (Ignores @var{number}.)
+
+@item offline
+@itemx rewoff1
+Rewinds the tape and takes the tape device off-line. (Ignores @var{number}.)
+
+@item status
+Prints status information about the tape unit.
+
+@end table
+
+If you don't specify a @var{tapename}, @command{mt} uses the environment
+variable @env{TAPE}; if @env{TAPE} is not set, @command{mt} will use
+the default device specified in your @file{sys/mtio.h} file
+(@code{DEFTAPE} variable). If this is not defined, the program will
+display a descriptive error message and exit with code 1.
+
+@command{mt} returns a 0 exit status when the operation(s) were
+successful, 1 if the command was unrecognized, and 2 if an operation
+failed.
+
+@node Using Multiple Tapes
+@section Using Multiple Tapes
+
+Often you might want to write a large archive, one larger than will fit
+on the actual tape you are using. In such a case, you can run multiple
+@command{tar} commands, but this can be inconvenient, particularly if you
+are using options like @option{--exclude=@var{pattern}} or dumping entire file systems.
+Therefore, @command{tar} provides a special mode for creating
+multi-volume archives.
+
+@dfn{Multi-volume} archive is a single @command{tar} archive, stored
+on several media volumes of fixed size. Although in this section we will
+often call @samp{volume} a @dfn{tape}, there is absolutely no
+requirement for multi-volume archives to be stored on tapes. Instead,
+they can use whatever media type the user finds convenient, they can
+even be located on files.
+
+When creating a multi-volume archive, @GNUTAR{} continues to fill
+current volume until it runs out of space, then it switches to
+next volume (usually the operator is queried to replace the tape on
+this point), and continues working on the new volume. This operation
+continues until all requested files are dumped. If @GNUTAR{} detects
+end of media while dumping a file, such a file is archived in split
+form. Some very big files can even be split across several volumes.
+
+Each volume is itself a valid @GNUTAR{} archive, so it can be read
+without any special options. Consequently any file member residing
+entirely on one volume can be extracted or otherwise operated upon
+without needing the other volume. Sure enough, to extract a split
+member you would need all volumes its parts reside on.
+
+Multi-volume archives suffer from several limitations. In particular,
+they cannot be compressed.
+
+@GNUTAR{} is able to create multi-volume archives of two formats
+(@pxref{Formats}): @samp{GNU} and @samp{POSIX}.
+
+@menu
+* Multi-Volume Archives:: Archives Longer than One Tape or Disk
+* Tape Files:: Tape Files
+* Tarcat:: Concatenate Volumes into a Single Archive
+
+@end menu
+
+@node Multi-Volume Archives
+@subsection Archives Longer than One Tape or Disk
+@cindex Multi-volume archives
+
+@opindex multi-volume
+To create an archive that is larger than will fit on a single unit of
+the media, use the @option{--multi-volume} (@option{-M}) option in conjunction with
+the @option{--create} option (@pxref{create}). A @dfn{multi-volume}
+archive can be manipulated like any other archive (provided the
+@option{--multi-volume} option is specified), but is stored on more
+than one tape or file.
+
+When you specify @option{--multi-volume}, @command{tar} does not report an
+error when it comes to the end of an archive volume (when reading), or
+the end of the media (when writing). Instead, it prompts you to load
+a new storage volume. If the archive is on a magnetic tape, you
+should change tapes when you see the prompt; if the archive is on a
+floppy disk, you should change disks; etc.
+
+@table @option
+@item --multi-volume
+@itemx -M
+Creates a multi-volume archive, when used in conjunction with
+@option{--create} (@option{-c}). To perform any other operation on a multi-volume
+archive, specify @option{--multi-volume} in conjunction with that
+operation.
+For example:
+
+@smallexample
+$ @kbd{tar --create --multi-volume --file=/dev/tape @var{files}}
+@end smallexample
+@end table
+
+The method @command{tar} uses to detect end of tape is not perfect, and
+fails on some operating systems or on some devices. If @command{tar}
+cannot detect the end of the tape itself, you can use
+@option{--tape-length} option to inform it about the capacity of the
+tape:
+
+@anchor{tape-length}
+@table @option
+@opindex tape-length
+@item --tape-length=@var{size}[@var{suf}]
+@itemx -L @var{size}[@var{suf}]
+Set maximum length of a volume. The @var{suf}, if given, specifies
+units in which @var{size} is expressed, e.g. @samp{2M} mean 2
+megabytes (@pxref{size-suffixes}, for a list of allowed size
+suffixes). Without @var{suf}, units of 1024 bytes (kilobyte) are
+assumed.
+
+This option selects @option{--multi-volume} automatically. For example:
+
+@smallexample
+$ @kbd{tar --create --tape-length=41943040 --file=/dev/tape @var{files}}
+@end smallexample
+
+@noindent
+or, which is equivalent:
+
+@smallexample
+$ @kbd{tar --create --tape-length=4G --file=/dev/tape @var{files}}
+@end smallexample
+@end table
+
+@anchor{change volume prompt}
+When @GNUTAR{} comes to the end of a storage media, it asks you to
+change the volume. The built-in prompt for POSIX locale
+is@footnote{If you run @GNUTAR{} under a different locale, the
+translation to the locale's language will be used.}:
+
+@smallexample
+Prepare volume #@var{n} for '@var{archive}' and hit return:
+@end smallexample
+
+@noindent
+where @var{n} is the ordinal number of the volume to be created and
+@var{archive} is archive file or device name.
+
+When prompting for a new tape, @command{tar} accepts any of the following
+responses:
+
+@table @kbd
+@item ?
+Request @command{tar} to explain possible responses.
+@item q
+Request @command{tar} to exit immediately.
+@item n @var{file-name}
+Request @command{tar} to write the next volume on the file @var{file-name}.
+@item !
+Request @command{tar} to run a subshell. This option can be disabled
+by giving @option{--restrict} command line option to
+@command{tar}@footnote{@xref{--restrict}, for more information about
+this option.}.
+@item y
+Request @command{tar} to begin writing the next volume.
+@end table
+
+(You should only type @samp{y} after you have changed the tape;
+otherwise @command{tar} will write over the volume it just finished.)
+
+@cindex Volume number file
+@cindex volno file
+@anchor{volno-file}
+@opindex volno-file
+The volume number used by @command{tar} in its tape-changing prompt
+can be changed; if you give the
+@option{--volno-file=@var{file-of-number}} option, then
+@var{file-of-number} should be an non-existing file to be created, or
+else, a file already containing a decimal number. That number will be
+used as the volume number of the first volume written. When
+@command{tar} is finished, it will rewrite the file with the
+now-current volume number. (This does not change the volume number
+written on a tape label, as per @ref{label}, it @emph{only} affects
+the number used in the prompt.)
+
+@cindex End-of-archive info script
+@cindex Info script
+@anchor{info-script}
+@opindex info-script
+@opindex new-volume-script
+If you want more elaborate behavior than this, you can write a special
+@dfn{new volume script}, that will be responsible for changing the
+volume, and instruct @command{tar} to use it instead of its normal
+prompting procedure:
+
+@table @option
+@item --info-script=@var{command}
+@itemx --new-volume-script=@var{command}
+@itemx -F @var{command}
+Specify the command to invoke when switching volumes. The @var{command}
+can be used to eject cassettes, or to broadcast messages such as
+@samp{Someone please come change my tape} when performing unattended
+backups.
+@end table
+
+The @var{command} can contain additional options, if such are needed.
+@xref{external, Running External Commands}, for a detailed discussion
+of the way @GNUTAR{} runs external commands. It inherits
+@command{tar}'s shell environment. Additional data is passed to it
+via the following environment variables:
+
+@table @env
+@vrindex TAR_VERSION, info script environment variable
+@item TAR_VERSION
+@GNUTAR{} version number.
+
+@vrindex TAR_ARCHIVE, info script environment variable
+@item TAR_ARCHIVE
+The name of the archive @command{tar} is processing.
+
+@vrindex TAR_BLOCKING_FACTOR, info script environment variable
+@item TAR_BLOCKING_FACTOR
+Current blocking factor (@pxref{Blocking}).
+
+@vrindex TAR_VOLUME, info script environment variable
+@item TAR_VOLUME
+Ordinal number of the volume @command{tar} is about to start.
+
+@vrindex TAR_SUBCOMMAND, info script environment variable
+@item TAR_SUBCOMMAND
+A short option describing the operation @command{tar} is executing.
+@xref{Operations}, for a complete list of subcommand options.
+
+@vrindex TAR_FORMAT, info script environment variable
+@item TAR_FORMAT
+Format of the archive being processed. @xref{Formats}, for a complete
+list of archive format names.
+
+@vrindex TAR_FD, info script environment variable
+@item TAR_FD
+File descriptor which can be used to communicate the new volume
+name to @command{tar}.
+@end table
+
+These variables can be used in the @var{command} itself, provided that
+they are properly quoted to prevent them from being expanded by the
+shell that invokes @command{tar}.
+
+The volume script can instruct @command{tar} to use new archive name,
+by writing in to file descriptor @env{$TAR_FD} (see below for an example).
+
+If the info script fails, @command{tar} exits; otherwise, it begins
+writing the next volume.
+
+If you want @command{tar} to cycle through a series of files or tape
+drives, there are three approaches to choose from. First of all, you
+can give @command{tar} multiple @option{--file} options. In this case
+the specified files will be used, in sequence, as the successive
+volumes of the archive. Only when the first one in the sequence needs
+to be used again will @command{tar} prompt for a tape change (or run
+the info script). For example, suppose someone has two tape drives on
+a system named @file{/dev/tape0} and @file{/dev/tape1}. For having
+@GNUTAR{} to switch to the second drive when it needs to write the
+second tape, and then back to the first tape, etc., just do either of:
+
+@smallexample
+$ @kbd{tar --create --multi-volume --file=/dev/tape0 --file=/dev/tape1 @var{files}}
+$ @kbd{tar -cM -f /dev/tape0 -f /dev/tape1 @var{files}}
+@end smallexample
+
+The second method is to use the @samp{n} response to the tape-change
+prompt.
+
+Finally, the most flexible approach is to use a volume script, that
+writes new archive name to the file descriptor @env{$TAR_FD}. For example, the
+following volume script will create a series of archive files, named
+@file{@var{archive}-@var{vol}}, where @var{archive} is the name of the
+archive being created (as given by @option{--file} option) and
+@var{vol} is the ordinal number of the archive being created:
+
+@smallexample
+@group
+#! /bin/bash
+# For this script it's advisable to use a shell, such as Bash,
+# that supports a TAR_FD value greater than 9.
+
+echo Preparing volume $TAR_VOLUME of $TAR_ARCHIVE.
+
+name=`expr $TAR_ARCHIVE : '\(.*\)-.*'`
+case $TAR_SUBCOMMAND in
+-c) ;;
+-d|-x|-t) test -r $@{name:-$TAR_ARCHIVE@}-$TAR_VOLUME || exit 1
+ ;;
+*) exit 1
+esac
+
+echo $@{name:-$TAR_ARCHIVE@}-$TAR_VOLUME >&$TAR_FD
+@end group
+@end smallexample
+
+The same script can be used while listing, comparing or extracting
+from the created archive. For example:
+
+@smallexample
+@group
+# @r{Create a multi-volume archive:}
+$ @kbd{tar -c -L1024 -f archive.tar -F new-volume .}
+# @r{Extract from the created archive:}
+$ @kbd{tar -x -f archive.tar -F new-volume .}
+@end group
+@end smallexample
+
+@noindent
+Notice, that the first command had to use @option{-L} option, since
+otherwise @GNUTAR{} will end up writing everything to file
+@file{archive.tar}.
+
+You can read each individual volume of a multi-volume archive as if it
+were an archive by itself. For example, to list the contents of one
+volume, use @option{--list}, without @option{--multi-volume} specified.
+To extract an archive member from one volume (assuming it is described
+that volume), use @option{--extract}, again without
+@option{--multi-volume}.
+
+If an archive member is split across volumes (i.e., its entry begins on
+one volume of the media and ends on another), you need to specify
+@option{--multi-volume} to extract it successfully. In this case, you
+should load the volume where the archive member starts, and use
+@samp{tar --extract --multi-volume}---@command{tar} will prompt for later
+volumes as it needs them. @xref{extracting archives}, for more
+information about extracting archives.
+
+Multi-volume archives can be modified like any other archive. To add
+files to a multi-volume archive, you need to only mount the last
+volume of the archive media (and new volumes, if needed). For all
+other operations, you need to use the entire archive.
+
+If a multi-volume archive was labeled using
+@option{--label=@var{archive-label}} (@pxref{label}) when it was
+created, @command{tar} will not automatically label volumes which are
+added later. To label subsequent volumes, specify
+@option{--label=@var{archive-label}} again in conjunction with the
+@option{--append}, @option{--update} or @option{--concatenate} operation.
+
+Notice that multi-volume support is a GNU extension and the archives
+created in this mode should be read only using @GNUTAR{}. If you
+absolutely have to process such archives using a third-party @command{tar}
+implementation, read @ref{Split Recovery}.
+
+@node Tape Files
+@subsection Tape Files
+@cindex labeling archives
+@opindex label
+@UNREVISED
+
+To give the archive a name which will be recorded in it, use the
+@option{--label=@var{volume-label}} (@option{-V @var{volume-label}})
+option. This will write a special block identifying
+@var{volume-label} as the name of the archive to the front of the
+archive which will be displayed when the archive is listed with
+@option{--list}. If you are creating a multi-volume archive with
+@option{--multi-volume} (@pxref{Using Multiple Tapes}), then the
+volume label will have @samp{Volume @var{nnn}} appended to the name
+you give, where @var{nnn} is the number of the volume of the archive.
+If you use the @option{--label=@var{volume-label}} option when
+reading an archive, it checks to make sure the label on the tape
+matches the one you gave. @xref{label}.
+
+When @command{tar} writes an archive to tape, it creates a single
+tape file. If multiple archives are written to the same tape, one
+after the other, they each get written as separate tape files. When
+extracting, it is necessary to position the tape at the right place
+before running @command{tar}. To do this, use the @command{mt} command.
+For more information on the @command{mt} command and on the organization
+of tapes into a sequence of tape files, see @ref{mt}.
+
+People seem to often do:
+
+@smallexample
+@kbd{--label="@var{some-prefix} `date +@var{some-format}`"}
+@end smallexample
+
+or such, for pushing a common date in all volumes or an archive set.
+
+@node Tarcat
+@subsection Concatenate Volumes into a Single Archive
+
+@pindex tarcat
+ Sometimes it is necessary to convert existing @GNUTAR{} multi-volume
+archive to a single @command{tar} archive. Simply concatenating all
+volumes into one will not work, since each volume carries an additional
+information at the beginning. @GNUTAR{} is shipped with the shell
+script @command{tarcat} designed for this purpose.
+
+ The script takes a list of files comprising a multi-volume archive
+and creates the resulting archive at the standard output. For example:
+
+@smallexample
+@kbd{tarcat vol.1 vol.2 vol.3 | tar tf -}
+@end smallexample
+
+ The script implements a simple heuristics to determine the format of
+the first volume file and to decide how to process the rest of the
+files. However, it makes no attempt to verify whether the files are
+given in order or even if they are valid @command{tar} archives.
+It uses @command{dd} and does not filter its standard error, so you
+will usually see lots of spurious messages.
+
+@FIXME{The script is not installed. Should we install it?}
+
+@node label
+@section Including a Label in the Archive
+@cindex Labeling an archive
+@cindex Labels on the archive media
+@cindex Labeling multi-volume archives
+
+@opindex label
+ To avoid problems caused by misplaced paper labels on the archive
+media, you can include a @dfn{label} entry --- an archive member which
+contains the name of the archive --- in the archive itself. Use the
+@option{--label=@var{archive-label}} (@option{-V @var{archive-label}})
+option@footnote{Until version 1.10, that option was called
+@option{--volume}, but is not available under that name anymore.} in
+conjunction with the @option{--create} operation to include a label
+entry in the archive as it is being created.
+
+@table @option
+@item --label=@var{archive-label}
+@itemx -V @var{archive-label}
+Includes an @dfn{archive-label} at the beginning of the archive when
+the archive is being created, when used in conjunction with the
+@option{--create} operation. Checks to make sure the archive label
+matches the one specified (when used in conjunction with any other
+operation).
+@end table
+
+ If you create an archive using both
+@option{--label=@var{archive-label}} (@option{-V @var{archive-label}})
+and @option{--multi-volume} (@option{-M}), each volume of the archive
+will have an archive label of the form @samp{@var{archive-label}
+Volume @var{n}}, where @var{n} is 1 for the first volume, 2 for the
+next, and so on. @xref{Using Multiple Tapes}, for information on
+creating multiple volume archives.
+
+@cindex Volume label, listing
+@cindex Listing volume label
+ The volume label will be displayed by @option{--list} along with
+the file contents. If verbose display is requested, it will also be
+explicitly marked as in the example below:
+
+@smallexample
+@group
+$ @kbd{tar --verbose --list --file=iamanarchive}
+V--------- 0/0 0 1992-03-07 12:01 iamalabel--Volume Header--
+-rw-r--r-- ringo/user 40 1990-05-21 13:30 iamafilename
+@end group
+@end smallexample
+
+@opindex test-label
+@anchor{--test-label option}
+ However, @option{--list} option will cause listing entire
+contents of the archive, which may be undesirable (for example, if the
+archive is stored on a tape). You can request checking only the volume
+label by specifying @option{--test-label} option. This option reads only the
+first block of an archive, so it can be used with slow storage
+devices. For example:
+
+@smallexample
+@group
+$ @kbd{tar --test-label --file=iamanarchive}
+iamalabel
+@end group
+@end smallexample
+
+ If @option{--test-label} is used with one or more command line
+arguments, @command{tar} compares the volume label with each
+argument. It exits with code 0 if a match is found, and with code 1
+otherwise@footnote{Note that @GNUTAR{} versions up to 1.23 indicated
+mismatch with an exit code 2 and printed a spurious diagnostics on
+stderr.}. No output is displayed, unless you also used the
+@option{--verbose} option. For example:
+
+@smallexample
+@group
+$ @kbd{tar --test-label --file=iamanarchive 'iamalabel'}
+@result{} 0
+$ @kbd{tar --test-label --file=iamanarchive 'alabel'}
+@result{} 1
+@end group
+@end smallexample
+
+ When used with the @option{--verbose} option, @command{tar}
+prints the actual volume label (if any), and a verbose diagnostics in
+case of a mismatch:
+
+@smallexample
+@group
+$ @kbd{tar --test-label --verbose --file=iamanarchive 'iamalabel'}
+iamalabel
+@result{} 0
+$ @kbd{tar --test-label --verbose --file=iamanarchive 'alabel'}
+iamalabel
+tar: Archive label mismatch
+@result{} 1
+@end group
+@end smallexample
+
+ If you request any operation, other than @option{--create}, along
+with using @option{--label} option, @command{tar} will first check if
+the archive label matches the one specified and will refuse to proceed
+if it does not. Use this as a safety precaution to avoid accidentally
+overwriting existing archives. For example, if you wish to add files
+to @file{archive}, presumably labeled with string @samp{My volume},
+you will get:
+
+@smallexample
+@group
+$ @kbd{tar -rf archive --label 'My volume' .}
+tar: Archive not labeled to match 'My volume'
+@end group
+@end smallexample
+
+@noindent
+in case its label does not match. This will work even if
+@file{archive} is not labeled at all.
+
+ Similarly, @command{tar} will refuse to list or extract the
+archive if its label doesn't match the @var{archive-label}
+specified. In those cases, @var{archive-label} argument is interpreted
+as a globbing-style pattern which must match the actual magnetic
+volume label. @xref{exclude}, for a precise description of how match
+is attempted@footnote{Previous versions of @command{tar} used full
+regular expression matching, or before that, only exact string
+matching, instead of wildcard matchers. We decided for the sake of
+simplicity to use a uniform matching device through
+@command{tar}.}. If the switch @option{--multi-volume} (@option{-M}) is being used,
+the volume label matcher will also suffix @var{archive-label} by
+@w{@samp{ Volume [1-9]*}} if the initial match fails, before giving
+up. Since the volume numbering is automatically added in labels at
+creation time, it sounded logical to equally help the user taking care
+of it when the archive is being read.
+
+ You can also use @option{--label} to get a common information on
+all tapes of a series. For having this information different in each
+series created through a single script used on a regular basis, just
+manage to get some date string as part of the label. For example:
+
+@smallexample
+@group
+$ @kbd{tar -cM -f /dev/tape -V "Daily backup for `date +%Y-%m-%d`"}
+$ @kbd{tar --create --file=/dev/tape --multi-volume \
+ --label="Daily backup for `date +%Y-%m-%d`"}
+@end group
+@end smallexample
+
+ Some more notes about volume labels:
+
+@itemize @bullet
+@item Each label has its own date and time, which corresponds
+to the time when @GNUTAR{} initially attempted to write it,
+often soon after the operator launches @command{tar} or types the
+carriage return telling that the next tape is ready.
+
+@item Comparing date labels to get an idea of tape throughput is
+unreliable. It gives correct results only if the delays for rewinding
+tapes and the operator switching them were negligible, which is
+usually not the case.
+@end itemize
+
+@node verify
+@section Verifying Data as It is Stored
+@cindex Verifying a write operation
+@cindex Double-checking a write operation
+
+@table @option
+@item -W
+@itemx --verify
+@opindex verify, short description
+Attempt to verify the archive after writing.
+@end table
+
+This option causes @command{tar} to verify the archive after writing it.
+Each volume is checked after it is written, and any discrepancies
+are recorded on the standard error output.
+
+Verification requires that the archive be on a back-space-able medium.
+This means pipes, some cartridge tape drives, and some other devices
+cannot be verified.
+
+You can insure the accuracy of an archive by comparing files in the
+system with archive members. @command{tar} can compare an archive to the
+file system as the archive is being written, to verify a write
+operation, or can compare a previously written archive, to insure that
+it is up to date.
+
+@xopindex{verify, using with @option{--create}}
+@xopindex{create, using with @option{--verify}}
+To check for discrepancies in an archive immediately after it is
+written, use the @option{--verify} (@option{-W}) option in conjunction with
+the @option{--create} operation. When this option is
+specified, @command{tar} checks archive members against their counterparts
+in the file system, and reports discrepancies on the standard error.
+
+To verify an archive, you must be able to read it from before the end
+of the last written entry. This option is useful for detecting data
+errors on some tapes. Archives written to pipes, some cartridge tape
+drives, and some other devices cannot be verified.
+
+One can explicitly compare an already made archive with the file
+system by using the @option{--compare} (@option{--diff}, @option{-d})
+option, instead of using the more automatic @option{--verify} option.
+@xref{compare}.
+
+Note that these two options have a slightly different intent. The
+@option{--compare} option checks how identical are the logical contents of some
+archive with what is on your disks, while the @option{--verify} option is
+really for checking if the physical contents agree and if the recording
+media itself is of dependable quality. So, for the @option{--verify}
+operation, @command{tar} tries to defeat all in-memory cache pertaining to
+the archive, while it lets the speed optimization undisturbed for the
+@option{--compare} option. If you nevertheless use @option{--compare} for
+media verification, you may have to defeat the in-memory cache yourself,
+maybe by opening and reclosing the door latch of your recording unit,
+forcing some doubt in your operating system about the fact this is really
+the same volume as the one just written or read.
+
+The @option{--verify} option would not be necessary if drivers were indeed
+able to detect dependably all write failures. This sometimes require many
+magnetic heads, some able to read after the writes occurred. One would
+not say that drivers unable to detect all cases are necessarily flawed,
+as long as programming is concerned.
+
+The @option{--verify} (@option{-W}) option will not work in
+conjunction with the @option{--multi-volume} (@option{-M}) option or
+the @option{--append} (@option{-r}), @option{--update} (@option{-u})
+and @option{--delete} operations. @xref{Operations}, for more
+information on these operations.
+
+Also, since @command{tar} normally strips leading @samp{/} from file
+names (@pxref{absolute}), a command like @samp{tar --verify -cf
+/tmp/foo.tar /etc} will work as desired only if the working directory is
+@file{/}, as @command{tar} uses the archive's relative member names
+(e.g., @file{etc/motd}) when verifying the archive.
+
+@node Write Protection
+@section Write Protection
+
+Almost all tapes and diskettes, and in a few rare cases, even disks can
+be @dfn{write protected}, to protect data on them from being changed.
+Once an archive is written, you should write protect the media to prevent
+the archive from being accidentally overwritten or deleted. (This will
+protect the archive from being changed with a tape or floppy drive---it
+will not protect it from magnet fields or other physical hazards.)
+
+The write protection device itself is usually an integral part of the
+physical media, and can be a two position (write enabled/write
+disabled) switch, a notch which can be popped out or covered, a ring
+which can be removed from the center of a tape reel, or some other
+changeable feature.
+
+@node Reliability and security
+@chapter Reliability and Security
+
+The @command{tar} command reads and writes files as any other
+application does, and is subject to the usual caveats about
+reliability and security. This section contains some commonsense
+advice on the topic.
+
+@menu
+* Reliability::
+* Security::
+@end menu
+
+@node Reliability
+@section Reliability
+
+Ideally, when @command{tar} is creating an archive, it reads from a
+file system that is not being modified, and encounters no errors or
+inconsistencies while reading and writing. If this is the case, the
+archive should faithfully reflect what was read. Similarly, when
+extracting from an archive, ideally @command{tar} ideally encounters
+no errors and the extracted files faithfully reflect what was in the
+archive.
+
+However, when reading or writing real-world file systems, several
+things can go wrong; these include permissions problems, corruption of
+data, and race conditions.
+
+@menu
+* Permissions problems::
+* Data corruption and repair::
+* Race conditions::
+@end menu
+
+@node Permissions problems
+@subsection Permissions Problems
+
+If @command{tar} encounters errors while reading or writing files, it
+normally reports an error and exits with nonzero status. The work it
+does may therefore be incomplete. For example, when creating an
+archive, if @command{tar} cannot read a file then it cannot copy the
+file into the archive.
+
+@node Data corruption and repair
+@subsection Data Corruption and Repair
+
+If an archive becomes corrupted by an I/O error, this may corrupt the
+data in an extracted file. Worse, it may corrupt the file's metadata,
+which may cause later parts of the archive to become misinterpreted.
+An tar-format archive contains a checksum that most likely will detect
+errors in the metadata, but it will not detect errors in the data.
+
+If data corruption is a concern, you can compute and check your own
+checksums of an archive by using other programs, such as
+@command{cksum}.
+
+When attempting to recover from a read error or data corruption in an
+archive, you may need to skip past the questionable data and read the
+rest of the archive. This requires some expertise in the archive
+format and in other software tools.
+
+@node Race conditions
+@subsection Race conditions
+
+If some other process is modifying the file system while @command{tar}
+is reading or writing files, the result may well be inconsistent due
+to race conditions. For example, if another process creates some
+files in a directory while @command{tar} is creating an archive
+containing the directory's files, @command{tar} may see some of the
+files but not others, or it may see a file that is in the process of
+being created. The resulting archive may not be a snapshot of the
+file system at any point in time. If an application such as a
+database system depends on an accurate snapshot, restoring from the
+@command{tar} archive of a live file system may therefore break that
+consistency and may break the application. The simplest way to avoid
+the consistency issues is to avoid making other changes to the file
+system while tar is reading it or writing it.
+
+When creating an archive, several options are available to avoid race
+conditions. Some hosts have a way of snapshotting a file system, or
+of temporarily suspending all changes to a file system, by (say)
+suspending the only virtual machine that can modify a file system; if
+you use these facilities and have @command{tar -c} read from a
+snapshot when creating an archive, you can avoid inconsistency
+problems. More drastically, before starting @command{tar} you could
+suspend or shut down all processes other than @command{tar} that have
+access to the file system, or you could unmount the file system and
+then mount it read-only.
+
+When extracting from an archive, one approach to avoid race conditions
+is to create a directory that no other process can write to, and
+extract into that.
+
+@node Security
+@section Security
+
+In some cases @command{tar} may be used in an adversarial situation,
+where an untrusted user is attempting to gain information about or
+modify otherwise-inaccessible files. Dealing with untrusted data
+(that is, data generated by an untrusted user) typically requires
+extra care, because even the smallest mistake in the use of
+@command{tar} is more likely to be exploited by an adversary than by a
+race condition.
+
+@menu
+* Privacy::
+* Integrity::
+* Live untrusted data::
+* Security rules of thumb::
+@end menu
+
+@node Privacy
+@subsection Privacy
+
+Standard privacy concerns apply when using @command{tar}. For
+example, suppose you are archiving your home directory into a file
+@file{/archive/myhome.tar}. Any secret information in your home
+directory, such as your SSH secret keys, are copied faithfully into
+the archive. Therefore, if your home directory contains any file that
+should not be read by some other user, the archive itself should be
+not be readable by that user. And even if the archive's data are
+inaccessible to untrusted users, its metadata (such as size or
+last-modified date) may reveal some information about your home
+directory; if the metadata are intended to be private, the archive's
+parent directory should also be inaccessible to untrusted users.
+
+One precaution is to create @file{/archive} so that it is not
+accessible to any user, unless that user also has permission to access
+all the files in your home directory.
+
+Similarly, when extracting from an archive, take care that the
+permissions of the extracted files are not more generous than what you
+want. Even if the archive itself is readable only to you, files
+extracted from it have their own permissions that may differ.
+
+@node Integrity
+@subsection Integrity
+
+When creating archives, take care that they are not writable by a
+untrusted user; otherwise, that user could modify the archive, and
+when you later extract from the archive you will get incorrect data.
+
+When @command{tar} extracts from an archive, by default it writes into
+files relative to the working directory. If the archive was generated
+by an untrusted user, that user therefore can write into any file
+under the working directory. If the working directory contains a
+symbolic link to another directory, the untrusted user can also write
+into any file under the referenced directory. When extracting from an
+untrusted archive, it is therefore good practice to create an empty
+directory and run @command{tar} in that directory.
+
+When extracting from two or more untrusted archives, each one should
+be extracted independently, into different empty directories.
+Otherwise, the first archive could create a symbolic link into an area
+outside the working directory, and the second one could follow the
+link and overwrite data that is not under the working directory. For
+example, when restoring from a series of incremental dumps, the
+archives should have been created by a trusted process, as otherwise
+the incremental restores might alter data outside the working
+directory.
+
+If you use the @option{--absolute-names} (@option{-P}) option when
+extracting, @command{tar} respects any file names in the archive, even
+file names that begin with @file{/} or contain @file{..}. As this
+lets the archive overwrite any file in your system that you can write,
+the @option{--absolute-names} (@option{-P}) option should be used only
+for trusted archives.
+
+Conversely, with the @option{--keep-old-files} (@option{-k}) and
+@option{--skip-old-files} options, @command{tar} refuses to replace
+existing files when extracting. The difference between the two
+options is that the former treats existing files as errors whereas the
+latter just silently ignores them.
+
+Finally, with the @option{--no-overwrite-dir} option, @command{tar}
+refuses to replace the permissions or ownership of already-existing
+directories. These options may help when extracting from untrusted
+archives.
+
+@node Live untrusted data
+@subsection Dealing with Live Untrusted Data
+
+Extra care is required when creating from or extracting into a file
+system that is accessible to untrusted users. For example, superusers
+who invoke @command{tar} must be wary about its actions being hijacked
+by an adversary who is reading or writing the file system at the same
+time that @command{tar} is operating.
+
+When creating an archive from a live file system, @command{tar} is
+vulnerable to denial-of-service attacks. For example, an adversarial
+user could create the illusion of an indefinitely-deep directory
+hierarchy @file{d/e/f/g/...} by creating directories one step ahead of
+@command{tar}, or the illusion of an indefinitely-long file by
+creating a sparse file but arranging for blocks to be allocated just
+before @command{tar} reads them. There is no easy way for
+@command{tar} to distinguish these scenarios from legitimate uses, so
+you may need to monitor @command{tar}, just as you'd need to monitor
+any other system service, to detect such attacks.
+
+While a superuser is extracting from an archive into a live file
+system, an untrusted user might replace a directory with a symbolic
+link, in hopes that @command{tar} will follow the symbolic link and
+extract data into files that the untrusted user does not have access
+to. Even if the archive was generated by the superuser, it may
+contain a file such as @file{d/etc/passwd} that the untrusted user
+earlier created in order to break in; if the untrusted user replaces
+the directory @file{d/etc} with a symbolic link to @file{/etc} while
+@command{tar} is running, @command{tar} will overwrite
+@file{/etc/passwd}. This attack can be prevented by extracting into a
+directory that is inaccessible to untrusted users.
+
+Similar attacks via symbolic links are also possible when creating an
+archive, if the untrusted user can modify an ancestor of a top-level
+argument of @command{tar}. For example, an untrusted user that can
+modify @file{/home/eve} can hijack a running instance of @samp{tar -cf
+- /home/eve/Documents/yesterday} by replacing
+@file{/home/eve/Documents} with a symbolic link to some other
+location. Attacks like these can be prevented by making sure that
+untrusted users cannot modify any files that are top-level arguments
+to @command{tar}, or any ancestor directories of these files.
+
+@node Security rules of thumb
+@subsection Security Rules of Thumb
+
+This section briefly summarizes rules of thumb for avoiding security
+pitfalls.
+
+@itemize @bullet
+
+@item
+Protect archives at least as much as you protect any of the files
+being archived.
+
+@item
+Extract from an untrusted archive only into an otherwise-empty
+directory. This directory and its parent should be accessible only to
+trusted users. For example:
+
+@example
+@group
+$ @kbd{chmod go-rwx .}
+$ @kbd{mkdir -m go-rwx dir}
+$ @kbd{cd dir}
+$ @kbd{tar -xvf /archives/got-it-off-the-net.tar.gz}
+@end group
+@end example
+
+As a corollary, do not do an incremental restore from an untrusted archive.
+
+@item
+Do not let untrusted users access files extracted from untrusted
+archives without checking first for problems such as setuid programs.
+
+@item
+Do not let untrusted users modify directories that are ancestors of
+top-level arguments of @command{tar}. For example, while you are
+executing @samp{tar -cf /archive/u-home.tar /u/home}, do not let an
+untrusted user modify @file{/}, @file{/archive}, or @file{/u}.
+
+@item
+Pay attention to the diagnostics and exit status of @command{tar}.
+
+@item
+When archiving live file systems, monitor running instances of
+@command{tar} to detect denial-of-service attacks.
+
+@item
+Avoid unusual options such as @option{--absolute-names} (@option{-P}),
+@option{--dereference} (@option{-h}), @option{--overwrite},
+@option{--recursive-unlink}, and @option{--remove-files} unless you
+understand their security implications.
+
+@end itemize
+
+@node Changes
+@appendix Changes
+
+This appendix lists some important user-visible changes between
+version @GNUTAR{} @value{VERSION} and previous versions. An up-to-date
+version of this document is available at
+@uref{http://www.gnu.org/@/software/@/tar/manual/changes.html,the
+@GNUTAR{} documentation page}.
+
+@table @asis
+@item Use of globbing patterns when listing and extracting.
+
+Previous versions of GNU tar assumed shell-style globbing when
+extracting from or listing an archive. For example:
+
+@smallexample
+$ @kbd{tar xf foo.tar '*.c'}
+@end smallexample
+
+would extract all files whose names end in @samp{.c}. This behavior
+was not documented and was incompatible with traditional tar
+implementations. Therefore, starting from version 1.15.91, GNU tar
+no longer uses globbing by default. For example, the above invocation
+is now interpreted as a request to extract from the archive the file
+named @file{*.c}.
+
+To facilitate transition to the new behavior for those users who got
+used to the previous incorrect one, @command{tar} will print a warning
+if it finds out that a requested member was not found in the archive
+and its name looks like a globbing pattern. For example:
+
+@smallexample
+$ @kbd{tar xf foo.tar '*.c'}
+tar: Pattern matching characters used in file names. Please,
+tar: use --wildcards to enable pattern matching, or --no-wildcards to
+tar: suppress this warning.
+tar: *.c: Not found in archive
+tar: Error exit delayed from previous errors
+@end smallexample
+
+To treat member names as globbing patterns, use the @option{--wildcards} option.
+If you want to tar to mimic the behavior of versions prior to 1.15.91,
+add this option to your @env{TAR_OPTIONS} variable.
+
+@xref{wildcards}, for the detailed discussion of the use of globbing
+patterns by @GNUTAR{}.
+
+@item Use of short option @option{-o}.
+
+Earlier versions of @GNUTAR{} understood @option{-o} command line
+option as a synonym for @option{--old-archive}.
+
+@GNUTAR{} starting from version 1.13.90 understands this option as
+a synonym for @option{--no-same-owner}. This is compatible with
+UNIX98 @command{tar} implementations.
+
+However, to facilitate transition, @option{-o} option retains its
+old semantics when it is used with one of archive-creation commands.
+Users are encouraged to use @option{--format=oldgnu} instead.
+
+It is especially important, since versions of @acronym{GNU} Automake
+up to and including 1.8.4 invoke tar with this option to produce
+distribution tarballs. @xref{Formats,v7}, for the detailed discussion
+of this issue and its implications.
+
+@xref{Options, tar-formats, Changing Automake's Behavior,
+automake, GNU Automake}, for a description on how to use various
+archive formats with @command{automake}.
+
+Future versions of @GNUTAR{} will understand @option{-o} only as a
+synonym for @option{--no-same-owner}.
+
+@item Use of short option @option{-l}
+
+Earlier versions of @GNUTAR{} understood @option{-l} option as a
+synonym for @option{--one-file-system}. Since such usage contradicted
+to UNIX98 specification and harmed compatibility with other
+implementations, it was declared deprecated in version 1.14. However,
+to facilitate transition to its new semantics, it was supported by
+versions 1.15 and 1.15.90. The present use of @option{-l} as a short
+variant of @option{--check-links} was introduced in version 1.15.91.
+
+@item Use of options @option{--portability} and @option{--old-archive}
+
+These options are deprecated. Please use @option{--format=v7} instead.
+
+@item Use of option @option{--posix}
+
+This option is deprecated. Please use @option{--format=posix} instead.
+@end table
+
+@node Configuring Help Summary
+@appendix Configuring Help Summary
+
+Running @kbd{tar --help} displays the short @command{tar} option
+summary (@pxref{help}). This summary is organized by @dfn{groups} of
+semantically close options. The options within each group are printed
+in the following order: a short option, eventually followed by a list
+of corresponding long option names, followed by a short description of
+the option. For example, here is an excerpt from the actual @kbd{tar
+--help} output:
+
+@verbatim
+ Main operation mode:
+
+ -A, --catenate, --concatenate append tar files to an archive
+ -c, --create create a new archive
+ -d, --diff, --compare find differences between archive and
+ file system
+ --delete delete from the archive
+@end verbatim
+
+@vrindex ARGP_HELP_FMT, environment variable
+The exact visual representation of the help output is configurable via
+@env{ARGP_HELP_FMT} environment variable. The value of this variable
+is a comma-separated list of @dfn{format variable} assignments. There
+are two kinds of format variables. An @dfn{offset variable} keeps the
+offset of some part of help output text from the leftmost column on
+the screen. A @dfn{boolean} variable is a flag that toggles some
+output feature on or off. Depending on the type of the corresponding
+variable, there are two kinds of assignments:
+
+@table @asis
+@item Offset assignment
+
+The assignment to an offset variable has the following syntax:
+
+@smallexample
+@var{variable}=@var{value}
+@end smallexample
+
+@noindent
+where @var{variable} is the variable name, and @var{value} is a
+numeric value to be assigned to the variable.
+
+@item Boolean assignment
+
+To assign @code{true} value to a variable, simply put this variable name. To
+assign @code{false} value, prefix the variable name with @samp{no-}. For
+example:
+
+@smallexample
+@group
+# Assign @code{true} value:
+dup-args
+# Assign @code{false} value:
+no-dup-args
+@end group
+@end smallexample
+@end table
+
+Following variables are declared:
+
+@deftypevr {Help Output} boolean dup-args
+If true, arguments for an option are shown with both short and long
+options, even when a given option has both forms, for example:
+
+@smallexample
+ -f ARCHIVE, --file=ARCHIVE use archive file or device ARCHIVE
+@end smallexample
+
+If false, then if an option has both short and long forms, the
+argument is only shown with the long one, for example:
+
+@smallexample
+ -f, --file=ARCHIVE use archive file or device ARCHIVE
+@end smallexample
+
+@noindent
+and a message indicating that the argument is applicable to both
+forms is printed below the options. This message can be disabled
+using @code{dup-args-note} (see below).
+
+The default is false.
+@end deftypevr
+
+@deftypevr {Help Output} boolean dup-args-note
+If this variable is true, which is the default, the following notice
+is displayed at the end of the help output:
+
+@quotation
+Mandatory or optional arguments to long options are also mandatory or
+optional for any corresponding short options.
+@end quotation
+
+Setting @code{no-dup-args-note} inhibits this message. Normally, only one of
+variables @code{dup-args} or @code{dup-args-note} should be set.
+@end deftypevr
+
+@deftypevr {Help Output} offset short-opt-col
+Column in which short options start. Default is 2.
+
+@smallexample
+@group
+$ @kbd{tar --help|grep ARCHIVE}
+ -f, --file=ARCHIVE use archive file or device ARCHIVE
+$ @kbd{ARGP_HELP_FMT=short-opt-col=6 tar --help|grep ARCHIVE}
+ -f, --file=ARCHIVE use archive file or device ARCHIVE
+@end group
+@end smallexample
+@end deftypevr
+
+@deftypevr {Help Output} offset long-opt-col
+Column in which long options start. Default is 6. For example:
+
+@smallexample
+@group
+$ @kbd{tar --help|grep ARCHIVE}
+ -f, --file=ARCHIVE use archive file or device ARCHIVE
+$ @kbd{ARGP_HELP_FMT=long-opt-col=16 tar --help|grep ARCHIVE}
+ -f, --file=ARCHIVE use archive file or device ARCHIVE
+@end group
+@end smallexample
+@end deftypevr
+
+@deftypevr {Help Output} offset doc-opt-col
+Column in which @dfn{doc options} start. A doc option isn't actually
+an option, but rather an arbitrary piece of documentation that is
+displayed in much the same manner as the options. For example, in
+the description of @option{--format} option:
+
+@smallexample
+@group
+ -H, --format=FORMAT create archive of the given format.
+
+ FORMAT is one of the following:
+
+ gnu GNU tar 1.13.x format
+ oldgnu GNU format as per tar <= 1.12
+ pax POSIX 1003.1-2001 (pax) format
+ posix same as pax
+ ustar POSIX 1003.1-1988 (ustar) format
+ v7 old V7 tar format
+@end group
+@end smallexample
+
+@noindent
+the format names are doc options. Thus, if you set
+@kbd{ARGP_HELP_FMT=doc-opt-col=6} the above part of the help output
+will look as follows:
+
+@smallexample
+@group
+ -H, --format=FORMAT create archive of the given format.
+
+ FORMAT is one of the following:
+
+ gnu GNU tar 1.13.x format
+ oldgnu GNU format as per tar <= 1.12
+ pax POSIX 1003.1-2001 (pax) format
+ posix same as pax
+ ustar POSIX 1003.1-1988 (ustar) format
+ v7 old V7 tar format
+@end group
+@end smallexample
+@end deftypevr
+
+@deftypevr {Help Output} offset opt-doc-col
+Column in which option description starts. Default is 29.
+
+@smallexample
+@group
+$ @kbd{tar --help|grep ARCHIVE}
+ -f, --file=ARCHIVE use archive file or device ARCHIVE
+$ @kbd{ARGP_HELP_FMT=opt-doc-col=19 tar --help|grep ARCHIVE}
+ -f, --file=ARCHIVE use archive file or device ARCHIVE
+$ @kbd{ARGP_HELP_FMT=opt-doc-col=9 tar --help|grep ARCHIVE}
+ -f, --file=ARCHIVE
+ use archive file or device ARCHIVE
+@end group
+@end smallexample
+
+@noindent
+Notice, that the description starts on a separate line if
+@code{opt-doc-col} value is too small.
+@end deftypevr
+
+@deftypevr {Help Output} offset header-col
+Column in which @dfn{group headers} are printed. A group header is a
+descriptive text preceding an option group. For example, in the
+following text:
+
+@verbatim
+ Main operation mode:
+
+ -A, --catenate, --concatenate append tar files to
+ an archive
+ -c, --create create a new archive
+@end verbatim
+@noindent
+@samp{Main operation mode:} is the group header.
+
+The default value is 1.
+@end deftypevr
+
+@deftypevr {Help Output} offset usage-indent
+Indentation of wrapped usage lines. Affects @option{--usage}
+output. Default is 12.
+@end deftypevr
+
+@deftypevr {Help Output} offset rmargin
+Right margin of the text output. Used for wrapping.
+@end deftypevr
+
+@node Fixing Snapshot Files
+@appendix Fixing Snapshot Files
+@include tar-snapshot-edit.texi
+
+@node Tar Internals
+@appendix Tar Internals
+@include intern.texi
+
+@node Genfile
+@appendix Genfile
+@include genfile.texi
+
+@node Free Software Needs Free Documentation
+@appendix Free Software Needs Free Documentation
+@include freemanuals.texi
+
+@node GNU Free Documentation License
+@appendix GNU Free Documentation License
+
+@include fdl.texi
+
+@node Index of Command Line Options
+@appendix Index of Command Line Options
+
+This appendix contains an index of all @GNUTAR{} long command line
+options. The options are listed without the preceding double-dash.
+For a cross-reference of short command line options, see
+@ref{Short Option Summary}.
+
+@printindex op
+
+@node Index
+@appendix Index
+
+@printindex cp
+
+@summarycontents
+@contents
+@bye
+
+@c Local variables:
+@c texinfo-column-for-description: 32
+@c End:
diff --git a/doc/texify.sed b/doc/texify.sed
new file mode 100644
index 0000000..fed0d4e
--- /dev/null
+++ b/doc/texify.sed
@@ -0,0 +1,27 @@
+# Copyright 2006-2007, 2013-2014, 2016 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/>.
+
+1{s,/\*,@comment ,
+b
+}
+2,/.*\*\//{s,\*/,,;s/^/@comment/
+b
+}
+/\/* END \*\//,$d
+s/\([{}]\)/@\1/g
+s,/\*,&@r{,
+s,\*/,}&,
diff --git a/doc/untabify.el b/doc/untabify.el
new file mode 100644
index 0000000..77dd5c0
--- /dev/null
+++ b/doc/untabify.el
@@ -0,0 +1,13 @@
+;;;; Untabify the sources.
+;;;; Usage: emacs -batch -l untabify.el [file ...]
+
+(defun global-untabify (buflist)
+ (mapcar
+ (lambda (bufname)
+ (set-buffer (find-file bufname))
+ (untabify (point-min) (point-max))
+ (save-buffer)
+ (kill-buffer (current-buffer)))
+ buflist))
+
+(global-untabify command-line-args-left)
diff --git a/doc/value.texi b/doc/value.texi
new file mode 100644
index 0000000..1f47c83
--- /dev/null
+++ b/doc/value.texi
@@ -0,0 +1,20 @@
+@c This is part of GNU tar manual.
+@c Copyright 1992, 1994-1997, 1999-2006, 2013-2014, 2016 Free Software
+@c Foundation, Inc.
+@c See file tar.texi for copying conditions.
+
+@macro GNUTAR
+@acronym{GNU} @command{tar}
+@end macro
+
+@macro xopindex{option,text}
+@opindex \option\@r{, \text\}
+@end macro
+
+@macro opsummary{option}
+@ifclear ANCHOR--\option\
+@set ANCHOR--\option\ 1
+@anchor{--\option\}
+@end ifclear
+@xopindex{\option\, summary}
+@end macro
diff --git a/doc/version.texi b/doc/version.texi
new file mode 100644
index 0000000..eacd45d
--- /dev/null
+++ b/doc/version.texi
@@ -0,0 +1,4 @@
+@set UPDATED 14 April 2016
+@set UPDATED-MONTH April 2016
+@set EDITION 1.29
+@set VERSION 1.29
View Lorry Controller Status