--- /dev/null
+#!/bin/sh
+#
+# clean upstream source to achieve DFSG compliance
+# Copyright 2009 by Bdale Garbee. GPL v2 or any later version.
+#
+
+rm -rf doc
+++ /dev/null
-# Makefile for GNU tar documentation.
-
-# Copyright (C) 1994, 1995, 1996, 1997, 1999, 2000, 2001, 2003, 2006,
-# 2007 Free Software Foundation, Inc.
-
-## This program 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, or (at your option)
-## any later version.
-
-## This program 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, write to the Free Software Foundation,
-## Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
-
-info_TEXINFOS = tar.texi
-tar_TEXINFOS = \
- dumpdir.texi\
- tar-snapshot-edit.texi\
- fdl.texi\
- freemanuals.texi\
- genfile.texi\
- getdate.texi\
- header.texi\
- intern.texi\
- rendition.texi\
- snapshot.texi\
- sparse.texi\
- value.texi
-EXTRA_DIST = gendocs_template mastermenu.el texify.sed untabify.el
-
-# 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.$$$$;\
- (echo 'Not documented options:';\
- join -v1 opts.$$$$ docs.$$$$;\
- echo 'Non-existing options:';\
- join -v2 opts.$$$$ docs.$$$$) > report.$$$$;\
- rm opts.$$$$ docs.$$$$;\
- if [ -n "`sed '1,2d' report.$$$$`" ]; then \
- cat report.$$$$;\
- rm report.$$$$;\
- exit 1;\
- fi;\
- rm report.$$$$
-
-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'
-
+++ /dev/null
-# Makefile.in generated by automake 1.10.1 from Makefile.am.
-# @configure_input@
-
-# Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
-# 2003, 2004, 2005, 2006, 2007, 2008 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 (C) 1994, 1995, 1996, 1997, 1999, 2000, 2001, 2003, 2006,
-# 2007 Free Software Foundation, Inc.
-VPATH = @srcdir@
-pkgdatadir = $(datadir)/@PACKAGE@
-pkglibdir = $(libdir)/@PACKAGE@
-pkgincludedir = $(includedir)/@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.am $(srcdir)/Makefile.in \
- $(srcdir)/stamp-vti $(srcdir)/version.texi $(tar_TEXINFOS)
-ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
-am__aclocal_m4_deps = $(top_srcdir)/m4/alloca.m4 \
- $(top_srcdir)/m4/argmatch.m4 $(top_srcdir)/m4/argp.m4 \
- $(top_srcdir)/m4/backupfile.m4 $(top_srcdir)/m4/bison.m4 \
- $(top_srcdir)/m4/canonicalize-lgpl.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/closeout.m4 \
- $(top_srcdir)/m4/codeset.m4 $(top_srcdir)/m4/d-ino.m4 \
- $(top_srcdir)/m4/dirfd.m4 $(top_srcdir)/m4/dirname.m4 \
- $(top_srcdir)/m4/dos.m4 $(top_srcdir)/m4/double-slash-root.m4 \
- $(top_srcdir)/m4/dup2.m4 $(top_srcdir)/m4/eealloc.m4 \
- $(top_srcdir)/m4/environ.m4 $(top_srcdir)/m4/eoverflow.m4 \
- $(top_srcdir)/m4/error.m4 $(top_srcdir)/m4/exclude.m4 \
- $(top_srcdir)/m4/exitfail.m4 $(top_srcdir)/m4/extensions.m4 \
- $(top_srcdir)/m4/fchdir.m4 $(top_srcdir)/m4/fcntl-safer.m4 \
- $(top_srcdir)/m4/fcntl_h.m4 $(top_srcdir)/m4/fileblocks.m4 \
- $(top_srcdir)/m4/float_h.m4 $(top_srcdir)/m4/fnmatch.m4 \
- $(top_srcdir)/m4/fpending.m4 $(top_srcdir)/m4/fseeko.m4 \
- $(top_srcdir)/m4/ftruncate.m4 \
- $(top_srcdir)/m4/getcwd-abort-bug.m4 \
- $(top_srcdir)/m4/getcwd-path-max.m4 $(top_srcdir)/m4/getcwd.m4 \
- $(top_srcdir)/m4/getdate.m4 $(top_srcdir)/m4/getdelim.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/hash.m4 \
- $(top_srcdir)/m4/human.m4 $(top_srcdir)/m4/iconv.m4 \
- $(top_srcdir)/m4/include_next.m4 $(top_srcdir)/m4/inline.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/lchown.m4 $(top_srcdir)/m4/lib-ld.m4 \
- $(top_srcdir)/m4/lib-link.m4 $(top_srcdir)/m4/lib-prefix.m4 \
- $(top_srcdir)/m4/localcharset.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/mbchar.m4 $(top_srcdir)/m4/mbiter.m4 \
- $(top_srcdir)/m4/mbrtowc.m4 $(top_srcdir)/m4/mbscasecmp.m4 \
- $(top_srcdir)/m4/mbstate_t.m4 $(top_srcdir)/m4/memchr.m4 \
- $(top_srcdir)/m4/mempcpy.m4 $(top_srcdir)/m4/memrchr.m4 \
- $(top_srcdir)/m4/memset.m4 $(top_srcdir)/m4/mkdtemp.m4 \
- $(top_srcdir)/m4/mktime.m4 $(top_srcdir)/m4/modechange.m4 \
- $(top_srcdir)/m4/nls.m4 $(top_srcdir)/m4/openat.m4 \
- $(top_srcdir)/m4/pathmax.m4 $(top_srcdir)/m4/paxutils.m4 \
- $(top_srcdir)/m4/po.m4 $(top_srcdir)/m4/progtest.m4 \
- $(top_srcdir)/m4/quote.m4 $(top_srcdir)/m4/quotearg.m4 \
- $(top_srcdir)/m4/readlink.m4 $(top_srcdir)/m4/realloc.m4 \
- $(top_srcdir)/m4/regex.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/setenv.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/stdarg.m4 $(top_srcdir)/m4/stdbool.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/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/sys_stat_h.m4 \
- $(top_srcdir)/m4/sys_time_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/timespec.m4 $(top_srcdir)/m4/tm_gmtoff.m4 \
- $(top_srcdir)/m4/unistd-safer.m4 $(top_srcdir)/m4/unistd_h.m4 \
- $(top_srcdir)/m4/unlinkdir.m4 $(top_srcdir)/m4/unlocked-io.m4 \
- $(top_srcdir)/m4/utimbuf.m4 $(top_srcdir)/m4/utime.m4 \
- $(top_srcdir)/m4/utimens.m4 $(top_srcdir)/m4/utimes-null.m4 \
- $(top_srcdir)/m4/utimes.m4 $(top_srcdir)/m4/vasnprintf.m4 \
- $(top_srcdir)/m4/vsnprintf.m4 $(top_srcdir)/m4/wchar.m4 \
- $(top_srcdir)/m4/wchar_t.m4 $(top_srcdir)/m4/wctype.m4 \
- $(top_srcdir)/m4/wcwidth.m4 $(top_srcdir)/m4/wint_t.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)/configure.ac
-am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \
- $(ACLOCAL_M4)
-mkinstalldirs = $(SHELL) $(top_srcdir)/build-aux/mkinstalldirs
-CONFIG_HEADER = $(top_builddir)/config.h
-CONFIG_CLEAN_FILES =
-SOURCES =
-DIST_SOURCES =
-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__installdirs = "$(DESTDIR)$(infodir)"
-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 = `echo $$p | sed -e 's|^.*/||'`;
-DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST)
-ACLOCAL = @ACLOCAL@
-ALLOCA = @ALLOCA@
-ALLOCA_H = @ALLOCA_H@
-AMTAR = @AMTAR@
-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@
-DIRENT_H = @DIRENT_H@
-ECHO_C = @ECHO_C@
-ECHO_N = @ECHO_N@
-ECHO_T = @ECHO_T@
-EGREP = @EGREP@
-EOVERFLOW = @EOVERFLOW@
-EXEEXT = @EXEEXT@
-FCNTL_H = @FCNTL_H@
-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_CALLOC_POSIX = @GNULIB_CALLOC_POSIX@
-GNULIB_CHOWN = @GNULIB_CHOWN@
-GNULIB_DUP2 = @GNULIB_DUP2@
-GNULIB_ENVIRON = @GNULIB_ENVIRON@
-GNULIB_FCHDIR = @GNULIB_FCHDIR@
-GNULIB_FFLUSH = @GNULIB_FFLUSH@
-GNULIB_FOPEN = @GNULIB_FOPEN@
-GNULIB_FPRINTF_POSIX = @GNULIB_FPRINTF_POSIX@
-GNULIB_FREOPEN = @GNULIB_FREOPEN@
-GNULIB_FSEEK = @GNULIB_FSEEK@
-GNULIB_FSEEKO = @GNULIB_FSEEKO@
-GNULIB_FTELL = @GNULIB_FTELL@
-GNULIB_FTELLO = @GNULIB_FTELLO@
-GNULIB_FTRUNCATE = @GNULIB_FTRUNCATE@
-GNULIB_GETCWD = @GNULIB_GETCWD@
-GNULIB_GETDELIM = @GNULIB_GETDELIM@
-GNULIB_GETLINE = @GNULIB_GETLINE@
-GNULIB_GETLOGIN_R = @GNULIB_GETLOGIN_R@
-GNULIB_GETPAGESIZE = @GNULIB_GETPAGESIZE@
-GNULIB_GETSUBOPT = @GNULIB_GETSUBOPT@
-GNULIB_IMAXABS = @GNULIB_IMAXABS@
-GNULIB_IMAXDIV = @GNULIB_IMAXDIV@
-GNULIB_LCHOWN = @GNULIB_LCHOWN@
-GNULIB_LSEEK = @GNULIB_LSEEK@
-GNULIB_MALLOC_POSIX = @GNULIB_MALLOC_POSIX@
-GNULIB_MBSCASECMP = @GNULIB_MBSCASECMP@
-GNULIB_MBSCASESTR = @GNULIB_MBSCASESTR@
-GNULIB_MBSCHR = @GNULIB_MBSCHR@
-GNULIB_MBSCSPN = @GNULIB_MBSCSPN@
-GNULIB_MBSLEN = @GNULIB_MBSLEN@
-GNULIB_MBSNCASECMP = @GNULIB_MBSNCASECMP@
-GNULIB_MBSNLEN = @GNULIB_MBSNLEN@
-GNULIB_MBSPBRK = @GNULIB_MBSPBRK@
-GNULIB_MBSPCASECMP = @GNULIB_MBSPCASECMP@
-GNULIB_MBSRCHR = @GNULIB_MBSRCHR@
-GNULIB_MBSSEP = @GNULIB_MBSSEP@
-GNULIB_MBSSPN = @GNULIB_MBSSPN@
-GNULIB_MBSSTR = @GNULIB_MBSSTR@
-GNULIB_MBSTOK_R = @GNULIB_MBSTOK_R@
-GNULIB_MEMMEM = @GNULIB_MEMMEM@
-GNULIB_MEMPCPY = @GNULIB_MEMPCPY@
-GNULIB_MEMRCHR = @GNULIB_MEMRCHR@
-GNULIB_MKDTEMP = @GNULIB_MKDTEMP@
-GNULIB_MKSTEMP = @GNULIB_MKSTEMP@
-GNULIB_OPEN = @GNULIB_OPEN@
-GNULIB_PRINTF_POSIX = @GNULIB_PRINTF_POSIX@
-GNULIB_PUTENV = @GNULIB_PUTENV@
-GNULIB_READLINK = @GNULIB_READLINK@
-GNULIB_REALLOC_POSIX = @GNULIB_REALLOC_POSIX@
-GNULIB_SETENV = @GNULIB_SETENV@
-GNULIB_SLEEP = @GNULIB_SLEEP@
-GNULIB_SNPRINTF = @GNULIB_SNPRINTF@
-GNULIB_SPRINTF_POSIX = @GNULIB_SPRINTF_POSIX@
-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_STRNDUP = @GNULIB_STRNDUP@
-GNULIB_STRNLEN = @GNULIB_STRNLEN@
-GNULIB_STRPBRK = @GNULIB_STRPBRK@
-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_STRTOUMAX = @GNULIB_STRTOUMAX@
-GNULIB_UNSETENV = @GNULIB_UNSETENV@
-GNULIB_VASPRINTF = @GNULIB_VASPRINTF@
-GNULIB_VFPRINTF_POSIX = @GNULIB_VFPRINTF_POSIX@
-GNULIB_VPRINTF_POSIX = @GNULIB_VPRINTF_POSIX@
-GNULIB_VSNPRINTF = @GNULIB_VSNPRINTF@
-GNULIB_VSPRINTF_POSIX = @GNULIB_VSPRINTF_POSIX@
-GNULIB_WCWIDTH = @GNULIB_WCWIDTH@
-GREP = @GREP@
-HAVE_CALLOC_POSIX = @HAVE_CALLOC_POSIX@
-HAVE_DECL_ENVIRON = @HAVE_DECL_ENVIRON@
-HAVE_DECL_GETDELIM = @HAVE_DECL_GETDELIM@
-HAVE_DECL_GETLINE = @HAVE_DECL_GETLINE@
-HAVE_DECL_GETLOGIN_R = @HAVE_DECL_GETLOGIN_R@
-HAVE_DECL_IMAXABS = @HAVE_DECL_IMAXABS@
-HAVE_DECL_IMAXDIV = @HAVE_DECL_IMAXDIV@
-HAVE_DECL_MEMMEM = @HAVE_DECL_MEMMEM@
-HAVE_DECL_MEMRCHR = @HAVE_DECL_MEMRCHR@
-HAVE_DECL_MKDIR = @HAVE_DECL_MKDIR@
-HAVE_DECL_SNPRINTF = @HAVE_DECL_SNPRINTF@
-HAVE_DECL_STRDUP = @HAVE_DECL_STRDUP@
-HAVE_DECL_STRERROR = @HAVE_DECL_STRERROR@
-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_VSNPRINTF = @HAVE_DECL_VSNPRINTF@
-HAVE_DECL_WCWIDTH = @HAVE_DECL_WCWIDTH@
-HAVE_DUP2 = @HAVE_DUP2@
-HAVE_FSEEKO = @HAVE_FSEEKO@
-HAVE_FTELLO = @HAVE_FTELLO@
-HAVE_FTRUNCATE = @HAVE_FTRUNCATE@
-HAVE_GETPAGESIZE = @HAVE_GETPAGESIZE@
-HAVE_GETSUBOPT = @HAVE_GETSUBOPT@
-HAVE_INTTYPES_H = @HAVE_INTTYPES_H@
-HAVE_IO_H = @HAVE_IO_H@
-HAVE_ISWCNTRL = @HAVE_ISWCNTRL@
-HAVE_LONG_LONG_INT = @HAVE_LONG_LONG_INT@
-HAVE_LSTAT = @HAVE_LSTAT@
-HAVE_MALLOC_POSIX = @HAVE_MALLOC_POSIX@
-HAVE_MEMPCPY = @HAVE_MEMPCPY@
-HAVE_MKDTEMP = @HAVE_MKDTEMP@
-HAVE_OS_H = @HAVE_OS_H@
-HAVE_READLINK = @HAVE_READLINK@
-HAVE_REALLOC_POSIX = @HAVE_REALLOC_POSIX@
-HAVE_SETENV = @HAVE_SETENV@
-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_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_STRNDUP = @HAVE_STRNDUP@
-HAVE_STRPBRK = @HAVE_STRPBRK@
-HAVE_STRSEP = @HAVE_STRSEP@
-HAVE_STRTOD = @HAVE_STRTOD@
-HAVE_STRUCT_TIMEVAL = @HAVE_STRUCT_TIMEVAL@
-HAVE_SYSEXITS_H = @HAVE_SYSEXITS_H@
-HAVE_SYS_BITYPES_H = @HAVE_SYS_BITYPES_H@
-HAVE_SYS_INTTYPES_H = @HAVE_SYS_INTTYPES_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_UNISTD_H = @HAVE_UNISTD_H@
-HAVE_UNSETENV = @HAVE_UNSETENV@
-HAVE_UNSIGNED_LONG_LONG_INT = @HAVE_UNSIGNED_LONG_LONG_INT@
-HAVE_VASPRINTF = @HAVE_VASPRINTF@
-HAVE_WCHAR_H = @HAVE_WCHAR_H@
-HAVE_WCTYPE_H = @HAVE_WCTYPE_H@
-HAVE_WINT_T = @HAVE_WINT_T@
-HAVE__BOOL = @HAVE__BOOL@
-INCLUDE_NEXT = @INCLUDE_NEXT@
-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@
-INTTYPES_H = @INTTYPES_H@
-LDFLAGS = @LDFLAGS@
-LIBICONV = @LIBICONV@
-LIBINTL = @LIBINTL@
-LIBOBJS = @LIBOBJS@
-LIBS = @LIBS@
-LIBTAR_LIBDEPS = @LIBTAR_LIBDEPS@
-LIBTAR_LTLIBDEPS = @LIBTAR_LTLIBDEPS@
-LIB_CLOCK_GETTIME = @LIB_CLOCK_GETTIME@
-LIB_SETSOCKOPT = @LIB_SETSOCKOPT@
-LOCALCHARSET_TESTS_ENVIRONMENT = @LOCALCHARSET_TESTS_ENVIRONMENT@
-LTLIBICONV = @LTLIBICONV@
-LTLIBINTL = @LTLIBINTL@
-LTLIBOBJS = @LTLIBOBJS@
-MAKEINFO = @MAKEINFO@
-MKDIR_P = @MKDIR_P@
-MSGFMT = @MSGFMT@
-MSGFMT_015 = @MSGFMT_015@
-MSGMERGE = @MSGMERGE@
-NEXT_DIRENT_H = @NEXT_DIRENT_H@
-NEXT_FCNTL_H = @NEXT_FCNTL_H@
-NEXT_FLOAT_H = @NEXT_FLOAT_H@
-NEXT_INTTYPES_H = @NEXT_INTTYPES_H@
-NEXT_STDARG_H = @NEXT_STDARG_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_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_VERSION = @PACKAGE_VERSION@
-PATH_SEPARATOR = @PATH_SEPARATOR@
-POSUB = @POSUB@
-PRIPTR_PREFIX = @PRIPTR_PREFIX@
-PRI_MACROS_BROKEN = @PRI_MACROS_BROKEN@
-PTRDIFF_T_SUFFIX = @PTRDIFF_T_SUFFIX@
-PU_RMT_PROG = @PU_RMT_PROG@
-RANLIB = @RANLIB@
-REPLACE_CHOWN = @REPLACE_CHOWN@
-REPLACE_FCHDIR = @REPLACE_FCHDIR@
-REPLACE_FFLUSH = @REPLACE_FFLUSH@
-REPLACE_FOPEN = @REPLACE_FOPEN@
-REPLACE_FPRINTF = @REPLACE_FPRINTF@
-REPLACE_FREOPEN = @REPLACE_FREOPEN@
-REPLACE_FSEEK = @REPLACE_FSEEK@
-REPLACE_FSEEKO = @REPLACE_FSEEKO@
-REPLACE_FTELL = @REPLACE_FTELL@
-REPLACE_FTELLO = @REPLACE_FTELLO@
-REPLACE_GETCWD = @REPLACE_GETCWD@
-REPLACE_GETLINE = @REPLACE_GETLINE@
-REPLACE_GETPAGESIZE = @REPLACE_GETPAGESIZE@
-REPLACE_GETTIMEOFDAY = @REPLACE_GETTIMEOFDAY@
-REPLACE_LCHOWN = @REPLACE_LCHOWN@
-REPLACE_LOCALTIME_R = @REPLACE_LOCALTIME_R@
-REPLACE_LSEEK = @REPLACE_LSEEK@
-REPLACE_MEMMEM = @REPLACE_MEMMEM@
-REPLACE_MKSTEMP = @REPLACE_MKSTEMP@
-REPLACE_NANOSLEEP = @REPLACE_NANOSLEEP@
-REPLACE_OPEN = @REPLACE_OPEN@
-REPLACE_PRINTF = @REPLACE_PRINTF@
-REPLACE_PUTENV = @REPLACE_PUTENV@
-REPLACE_SNPRINTF = @REPLACE_SNPRINTF@
-REPLACE_SPRINTF = @REPLACE_SPRINTF@
-REPLACE_STRCASESTR = @REPLACE_STRCASESTR@
-REPLACE_STRERROR = @REPLACE_STRERROR@
-REPLACE_STRPTIME = @REPLACE_STRPTIME@
-REPLACE_STRSIGNAL = @REPLACE_STRSIGNAL@
-REPLACE_STRSTR = @REPLACE_STRSTR@
-REPLACE_STRTOD = @REPLACE_STRTOD@
-REPLACE_TIMEGM = @REPLACE_TIMEGM@
-REPLACE_VASPRINTF = @REPLACE_VASPRINTF@
-REPLACE_VFPRINTF = @REPLACE_VFPRINTF@
-REPLACE_VPRINTF = @REPLACE_VPRINTF@
-REPLACE_VSNPRINTF = @REPLACE_VSNPRINTF@
-REPLACE_VSPRINTF = @REPLACE_VSPRINTF@
-REPLACE_WCWIDTH = @REPLACE_WCWIDTH@
-SET_MAKE = @SET_MAKE@
-SHELL = @SHELL@
-SIG_ATOMIC_T_SUFFIX = @SIG_ATOMIC_T_SUFFIX@
-SIZE_T_SUFFIX = @SIZE_T_SUFFIX@
-STDARG_H = @STDARG_H@
-STDBOOL_H = @STDBOOL_H@
-STDINT_H = @STDINT_H@
-STRIP = @STRIP@
-SYSEXITS_H = @SYSEXITS_H@
-SYS_STAT_H = @SYS_STAT_H@
-SYS_TIME_H = @SYS_TIME_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@
-USE_NLS = @USE_NLS@
-VERSION = @VERSION@
-VOID_UNSETENV = @VOID_UNSETENV@
-WCHAR_H = @WCHAR_H@
-WCHAR_T_SUFFIX = @WCHAR_T_SUFFIX@
-WCTYPE_H = @WCTYPE_H@
-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_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@
-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@
-localedir = @localedir@
-localstatedir = @localstatedir@
-mandir = @mandir@
-mkdir_p = @mkdir_p@
-oldincludedir = @oldincludedir@
-pdfdir = @pdfdir@
-prefix = @prefix@
-program_transform_name = @program_transform_name@
-psdir = @psdir@
-sbindir = @sbindir@
-sharedstatedir = @sharedstatedir@
-srcdir = @srcdir@
-sysconfdir = @sysconfdir@
-target_alias = @target_alias@
-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\
- getdate.texi\
- header.texi\
- intern.texi\
- rendition.texi\
- snapshot.texi\
- sparse.texi\
- value.texi
-
-EXTRA_DIST = gendocs_template mastermenu.el texify.sed untabify.el
-
-# 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 \
- && exit 0; \
- exit 1;; \
- esac; \
- done; \
- echo ' cd $(top_srcdir) && $(AUTOMAKE) --gnits doc/Makefile'; \
- 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
-
-.texi.info:
- restore=: && backupdir="$(am__leading_dot)am$$$$" && \
- am__cwd=`pwd` && 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; \
- cd $(srcdir); \
- else \
- rc=$$?; \
- cd $(srcdir) && \
- $$restore $$backupdir/* `echo "./$@" | sed 's|[^/]*$$||'`; \
- fi; \
- rm -rf $$backupdir; exit $$rc
-
-.texi.dvi:
- TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \
- MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \
- $(TEXI2DVI) $<
-
-.texi.pdf:
- TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \
- MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \
- $(TEXI2PDF) $<
-
-.texi.html:
- rm -rf $(@:.html=.htp)
- if $(MAKEINFOHTML) $(AM_MAKEINFOHTMLFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \
- -o $(@:.html=.htp) $<; \
- then \
- rm -rf $@; \
- if test ! -d $(@:.html=.htp) && test -d $(@:.html=); then \
- mv $(@:.html=) $@; else mv $(@:.html=.htp) $@; fi; \
- else \
- if test ! -d $(@:.html=.htp) && test -d $(@:.html=); then \
- rm -rf $(@:.html=); else rm -Rf $(@:.html=.htp) $@; fi; \
- 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:
- TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \
- $(DVIPS) -o $@ $<
-
-uninstall-dvi-am:
- @$(NORMAL_UNINSTALL)
- @list='$(DVIS)'; for p in $$list; do \
- f=$(am__strip_dir) \
- echo " rm -f '$(DESTDIR)$(dvidir)/$$f'"; \
- rm -f "$(DESTDIR)$(dvidir)/$$f"; \
- done
-
-uninstall-html-am:
- @$(NORMAL_UNINSTALL)
- @list='$(HTMLS)'; for p in $$list; do \
- f=$(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)' && \
- (install-info --version && \
- install-info --version 2>&1 | sed 1q | grep -i -v debian) >/dev/null 2>&1; 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'"; \
- install-info --info-dir="$(DESTDIR)$(infodir)" --remove "$(DESTDIR)$(infodir)/$$relfile"; \
- 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)'; for p in $$list; do \
- f=$(am__strip_dir) \
- echo " rm -f '$(DESTDIR)$(pdfdir)/$$f'"; \
- rm -f "$(DESTDIR)$(pdfdir)/$$f"; \
- done
-
-uninstall-ps-am:
- @$(NORMAL_UNINSTALL)
- @list='$(PSS)'; for p in $$list; do \
- f=$(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.aux tar.cp tar.cps tar.fn tar.ky tar.log tar.op tar.ops tar.pg \
- tar.tmp tar.toc tar.tp tar.tps tar.vr 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
-tags: TAGS
-TAGS:
-
-ctags: CTAGS
-CTAGS:
-
-
-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 $(srcdir)/$$file && test $$d != $(srcdir); then \
- cp -pR $(srcdir)/$$file $(distdir)$$dir || exit 1; \
- fi; \
- cp -pR $$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)
-installdirs:
- for dir in "$(DESTDIR)$(infodir)"; 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:
- $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \
- install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \
- `test -z '$(STRIP)' || \
- echo "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'"` install
-mostlyclean-generic:
-
-clean-generic:
-
-distclean-generic:
- -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_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-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-dvi: install-dvi-am
-
-install-dvi-am: $(DVIS)
- @$(NORMAL_INSTALL)
- test -z "$(dvidir)" || $(MKDIR_P) "$(DESTDIR)$(dvidir)"
- @list='$(DVIS)'; for p in $$list; do \
- if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \
- f=$(am__strip_dir) \
- echo " $(INSTALL_DATA) '$$d$$p' '$(DESTDIR)$(dvidir)/$$f'"; \
- $(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(dvidir)/$$f"; \
- done
-install-exec-am:
-
-install-html: install-html-am
-
-install-html-am: $(HTMLS)
- @$(NORMAL_INSTALL)
- test -z "$(htmldir)" || $(MKDIR_P) "$(DESTDIR)$(htmldir)"
- @list='$(HTMLS)'; for p in $$list; do \
- if test -f "$$p" || test -d "$$p"; then d=; else d="$(srcdir)/"; fi; \
- f=$(am__strip_dir) \
- if test -d "$$d$$p"; then \
- echo " $(MKDIR_P) '$(DESTDIR)$(htmldir)/$$f'"; \
- $(MKDIR_P) "$(DESTDIR)$(htmldir)/$$f" || exit 1; \
- echo " $(INSTALL_DATA) '$$d$$p'/* '$(DESTDIR)$(htmldir)/$$f'"; \
- $(INSTALL_DATA) "$$d$$p"/* "$(DESTDIR)$(htmldir)/$$f"; \
- else \
- echo " $(INSTALL_DATA) '$$d$$p' '$(DESTDIR)$(htmldir)/$$f'"; \
- $(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(htmldir)/$$f"; \
- fi; \
- done
-install-info: install-info-am
-
-install-info-am: $(INFO_DEPS)
- @$(NORMAL_INSTALL)
- test -z "$(infodir)" || $(MKDIR_P) "$(DESTDIR)$(infodir)"
- @srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \
- list='$(INFO_DEPS)'; \
- 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 \
- relfile=`echo "$$ifile" | sed 's|^.*/||'`; \
- echo " $(INSTALL_DATA) '$$ifile' '$(DESTDIR)$(infodir)/$$relfile'"; \
- $(INSTALL_DATA) "$$ifile" "$(DESTDIR)$(infodir)/$$relfile"; \
- else : ; fi; \
- done; \
- done
- @$(POST_INSTALL)
- @if (install-info --version && \
- install-info --version 2>&1 | sed 1q | grep -i -v debian) >/dev/null 2>&1; then \
- list='$(INFO_DEPS)'; \
- 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-pdf: install-pdf-am
-
-install-pdf-am: $(PDFS)
- @$(NORMAL_INSTALL)
- test -z "$(pdfdir)" || $(MKDIR_P) "$(DESTDIR)$(pdfdir)"
- @list='$(PDFS)'; for p in $$list; do \
- if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \
- f=$(am__strip_dir) \
- echo " $(INSTALL_DATA) '$$d$$p' '$(DESTDIR)$(pdfdir)/$$f'"; \
- $(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(pdfdir)/$$f"; \
- done
-install-ps: install-ps-am
-
-install-ps-am: $(PSS)
- @$(NORMAL_INSTALL)
- test -z "$(psdir)" || $(MKDIR_P) "$(DESTDIR)$(psdir)"
- @list='$(PSS)'; for p in $$list; do \
- if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \
- f=$(am__strip_dir) \
- echo " $(INSTALL_DATA) '$$d$$p' '$(DESTDIR)$(psdir)/$$f'"; \
- $(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(psdir)/$$f"; \
- 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-pdf-am uninstall-ps-am
-
-.MAKE: install-am install-strip
-
-.PHONY: all all-am check check-am clean clean-generic clean-local \
- 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-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 \
- uninstall uninstall-am uninstall-dvi-am uninstall-html-am \
- uninstall-info-am 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.$$$$;\
- (echo 'Not documented options:';\
- join -v1 opts.$$$$ docs.$$$$;\
- echo 'Non-existing options:';\
- join -v2 opts.$$$$ docs.$$$$) > report.$$$$;\
- rm opts.$$$$ docs.$$$$;\
- if [ -n "`sed '1,2d' report.$$$$`" ]; then \
- cat report.$$$$;\
- rm report.$$$$;\
- exit 1;\
- fi;\
- rm report.$$$$
-
-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:
+++ /dev/null
-@c This is part of the paxutils manual.
-@c Copyright (C) 2006, 2007 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
+++ /dev/null
-
-@node GNU Free Documentation License
-@appendixsec GNU Free Documentation License
-
-@cindex FDL, GNU Free Documentation License
-@center Version 1.2, November 2002
-
-@display
-Copyright @copyright{} 2000,2001,2002 Free Software Foundation, Inc.
-51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
-
-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
-@sc{ascii} without markup, Texinfo input format, La@TeX{} input
-format, @acronym{SGML} or @acronym{XML} using a publicly available
-@acronym{DTD}, and standard-conforming simple @acronym{HTML},
-PostScript or @acronym{PDF} designed for human modification. Examples
-of transparent image formats include @acronym{PNG}, @acronym{XCF} and
-@acronym{JPG}. Opaque formats include proprietary formats that can be
-read and edited only by proprietary word processors, @acronym{SGML} or
-@acronym{XML} for which the @acronym{DTD} and/or processing tools are
-not generally available, and the machine-generated @acronym{HTML},
-PostScript or @acronym{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.
-
-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 for under this License. Any other attempt to
-copy, modify, sublicense or distribute the Document is void, and will
-automatically terminate your rights under this License. However,
-parties who have received copies, or rights, from you under this
-License will not have their licenses terminated so long as such
-parties remain in full compliance.
-
-@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.
-@end enumerate
-
-@page
-@appendixsubsec 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.2
- 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...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:
-
+++ /dev/null
-@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}.
+++ /dev/null
-<?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 & 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 (C) 2004 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>
+++ /dev/null
-@c This is part of the paxutils manual.
-@c Copyright (C) 2005, 2006 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}, i.e., a string of characters, specifying 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
-
- For each letter in contents string @command{genfile} will generate
-a @dfn{block} of data, filled with this letter and will write it to
-the fragment. The size of block is given by @option{--block-size}
-option. It defaults to 512. Thus, if the string consists of @var{n}
-characters, the resulting file fragment will contain
-@code{@var{n}*@var{block-size}} of data.
-
- 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.
-
- 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
-
- The exit code of @command{genfile --status} command is @code{0}
-only if created file is actually sparse.
-
-@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 @FIXME{should we also support @samp{%} notations
-as in stat(1)??}:
-
-@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}]
- 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 argument to this option gives
-the command line to be executed. The actual command line is
-constructed by inserting @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'
-@end smallexample
-
- The rest of command line after @option{--run} or its equivalent
-specifies checkpoint values and actions to be executed upon reaching
-them. Checkpoint values are introduced with @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.
-
-@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.
+++ /dev/null
-@c GNU date syntax documentation
-
-@c Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
-@c 2003, 2004, 2005, 2006 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.2 or
-@c any later version published by the Free Software Foundation; with no
-@c Invariant Sections, with no Front-Cover Texts, and with 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 get_date
-
-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 @sc{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{get_date} 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:: @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 get_date:: 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 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 --iso-8601=ns | tr T ' ' # --iso-8601 is a GNU extension.
-2004-02-29 16:21:42,692722128-0800
-$ 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.
-
-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 # @sc{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 @sc{iso} 8601 date format
-@cindex date format, @sc{iso} 8601
-For numeric months, the @sc{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 @sc{est} (U.S. Eastern Standard Time).
-@end example
-
-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. 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 (@sc{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 @sc{utc} (e.g., India). The @var{minute}
-part of the time of day may not be elided when a time zone correction
-is used. This is the best way to specify a time zone correction by
-fractional parts of an hour.
-
-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 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 @acronym{POSIX}
-@cindex epoch, for @acronym{POSIX}
-Internally, computer times are represented as a count of seconds since
-an epoch---a well-defined point of time. On @acronym{GNU} and
-@acronym{POSIX} systems, the epoch is 1970-01-01 00:00:00 @sc{utc}, so
-@samp{@@0} represents this time, @samp{@@1} represents 1970-01-01
-00:00:01 @sc{utc}, and so forth. @acronym{GNU} and most other
-@acronym{POSIX}-compliant systems support such times as an extension
-to @acronym{POSIX}, using negative counts, so that @samp{@@-1}
-represents 1969-12-31 23:59:59 @sc{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 @sc{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 @samp{@@915148799} represents 1998-12-31
-23:59:59 @sc{utc}, @samp{@@915148800} represents 1999-01-01 00:00:00
-@sc{utc}, and there is no way to represent the intervening leap second
-1998-12-31 23:59:60 @sc{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 @acronym{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-@acronym{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-@acronym{GNU} host that does not support the @samp{tz}
-database, you may need to use a @acronym{POSIX} rule instead. Simple
-@acronym{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 get_date
-@section Authors of @code{get_date}
-
-@cindex authors of @code{get_date}
-
-@cindex Bellovin, Steven M.
-@cindex Salz, Rich
-@cindex Berets, Jim
-@cindex MacKenzie, David
-@cindex Meyering, Jim
-@cindex Eggert, Paul
-@code{get_date} was 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 @sc{gnu} system were made by David MacKenzie, Jim Meyering,
-Paul Eggert and others.
-
-@cindex Pinard, F.
-@cindex Berry, K.
-This chapter was originally produced by Fran@,{c}ois Pinard
-(@email{pinard@@iro.umontreal.ca}) from the @file{getdate.y} source code,
-and then edited by K.@: Berry (@email{kb@@cs.umb.edu}).
+++ /dev/null
-@comment GNU tar Archive Format description.
-@comment
-@comment Copyright (C) 1988, 1989, 1991, 1992, 1993, 1994, 1995, 1996, 1997,
-@comment 2000, 2001, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@comment
-@comment This program is free software; you can redistribute it and/or modify it
-@comment under the terms of the GNU General Public License as published by the
-@comment Free Software Foundation; either version 3, or (at your option) any later
-@comment version.
-@comment
-@comment This program is distributed in the hope that it will be useful, but
-@comment WITHOUT ANY WARRANTY; without even the implied warranty of
-@comment MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
-@comment Public License for more details.
-@comment
-@comment You should have received a copy of the GNU General Public License along
-@comment with this program; if not, write to the Free Software Foundation, Inc.,
-@comment 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
-
-/*@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;
-@};
-
+++ /dev/null
-@c This is part of the paxutils manual.
-@c Copyright (C) 2006 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
-
+++ /dev/null
-;;; mastermenu.el --- Redefinition of texinfo-master-menu-list
-
-;; Copyright (C) 2006, 2007 Free Software Foundation, Inc.
-
-;; Author: Sergey Poznyakoff
-;; Maintainer: bug-tar@gnu.org
-;; Keywords: maint, tex, docs
-
-;; This file is part of GNU tar documentation suite
-
-;; This program 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, or (at your option)
-;; any later version.
-
-;; This program 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, write to the Free Software Foundation,
-;; Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
-
-;;; 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
+++ /dev/null
-@c This is part of GNU tar manual.
-@c Copyright (C) 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001,
-@c 2003, 2004, 2006 Free 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
+++ /dev/null
-@c This is part of the paxutils manual.
-@c Copyright (C) 2005, 2007 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 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 version
-1.15.1. Starting from version 1.16 and up to @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, or a single space otherwise;
-
-@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
-@FIXME{}
- A 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 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. 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 number
-in @acronym{ASCII} notation.
-
-@multitable @columnfractions 0.2 0.2 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 mtime-sec @tab Number @tab Modification time, seconds;
-@item mtime-nano @tab Number @tab Modification time, nanoseconds;
-@item dev-no @tab Number @tab Device number;
-@item i-no @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}.
-
-@end enumerate
-
-@c End of snapshot.texi
-
-
+++ /dev/null
-@c This is part of the paxutils manual.
-@c Copyright (C) 2006 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 flows, 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 some time around 1990 (v. 1.09). It 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 entires) 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 @command{tar}s
-results in extraction of sparse files in @emph{compressed 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 tars.
-
-@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 tars and tars 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{}.
-
+++ /dev/null
-@set UPDATED 14 April 2008
-@set UPDATED-MONTH April 2008
-@set EDITION 1.20
-@set VERSION 1.20
+++ /dev/null
-@c This is part of the paxutils manual.
-@c Copyright (C) 2007 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
- Sometimes device numbers can change after upgrading your kernel
-version or recofiguring the harvare. Reportedly this is the case with
-some newer @i{Linux} kernels, when using @acronym{LVM}. In 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, 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 available from
-@uref{http://www.gnu.org/@/software/@/tar/@/utils/@/tar-snapshot-edit.html,
-@GNUTAR{} home page}.
-
- To obtain the device numbers used 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 ).
-
-To update all occurrences of the given device number in the file, use
-@option{-r} option. 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 /var/backup/snap.a}
-file version 2
-/tmp/snap: Device 0x0306 occurs 634 times.
-$ @kbd{tar-snapshot-edit -b -r 0x0306-0x4500 /var/backup/snap.a}
-file version 2
-@end smallexample
-
+++ /dev/null
-This is tar.info, produced by makeinfo version 4.8.90 from tar.texi.
-
- This manual is for GNU `tar' (version 1.20, 14 April 2008), which
-creates and extracts files from archives.
-
- Copyright (C) 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001, 2003,
-2004, 2005, 2006, 2007, 2008 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.1 or any later version published by the Free Software
- Foundation; with no Invariant Sections, 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. Buying copies from the FSF supports
- it in developing GNU and promoting software freedom."
-
-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
-
-\1f
-Indirect:
-tar.info-1: 1246
-tar.info-2: 303205
-\1f
-Tag Table:
-(Indirect)
-Node: Top\7f1246
-Node: Introduction\7f10511
-Node: Book Contents\7f11298
-Node: Definitions\7f13470
-Node: What tar Does\7f15273
-Node: Naming tar Archives\7f18039
-Node: Authors\7f18759
-Node: Reports\7f20572
-Node: Tutorial\7f20932
-Node: assumptions\7f21745
-Node: stylistic conventions\7f24220
-Node: basic tar options\7f24663
-Node: frequent operations\7f28301
-Node: Two Frequent Options\7f28953
-Node: file tutorial\7f29584
-Node: verbose tutorial\7f30945
-Ref: verbose member listing\7f33159
-Node: help tutorial\7f35912
-Node: create\7f36266
-Node: prepare for examples\7f37767
-Node: Creating the archive\7f39535
-Node: create verbose\7f42367
-Node: short create\7f43188
-Node: create dir\7f45941
-Node: list\7f48648
-Ref: listing member and file names\7f49922
-Node: list dir\7f52203
-Node: extract\7f53192
-Node: extracting archives\7f54369
-Node: extracting files\7f54859
-Ref: extracting files-Footnote-1\7f57506
-Node: extract dir\7f57886
-Node: extracting untrusted archives\7f60269
-Node: failing commands\7f61148
-Node: going further\7f62248
-Node: tar invocation\7f62461
-Node: Synopsis\7f63973
-Node: using tar options\7f68942
-Ref: TAR_OPTIONS\7f70527
-Node: Styles\7f71544
-Node: Long Options\7f73256
-Node: Short Options\7f75428
-Ref: Short Options-Footnote-1\7f77236
-Node: Old Options\7f77453
-Ref: Old Options-Footnote-1\7f80403
-Node: Mixing\7f80573
-Ref: Mixing-Footnote-1\7f82939
-Node: All Options\7f83059
-Node: Operation Summary\7f83664
-Ref: --append\7f83784
-Ref: --catenate\7f83864
-Ref: --compare\7f83935
-Ref: --concatenate\7f84138
-Ref: --create\7f84248
-Ref: --delete\7f84316
-Ref: --diff\7f84429
-Ref: --extract\7f84485
-Ref: --get\7f84587
-Ref: --list\7f84645
-Ref: --update\7f84713
-Node: Option Summary\7f84923
-Ref: --absolute-names\7f85078
-Ref: --after-date\7f85256
-Ref: --anchored\7f85308
-Ref: --atime-preserve\7f85441
-Ref: --auto-compress\7f87956
-Ref: --backup\7f88112
-Ref: --block-number\7f88303
-Ref: --blocking-factor\7f88477
-Ref: --bzip2\7f88629
-Ref: --check-device\7f88736
-Ref: --checkpoint\7f88931
-Ref: --checkpoint-action\7f89372
-Ref: --check-links\7f90523
-Ref: --compress\7f90800
-Ref: --uncompress\7f90800
-Ref: --confirmation\7f91004
-Ref: --delay-directory-restore\7f91072
-Ref: --dereference\7f91273
-Ref: --directory\7f91458
-Ref: --exclude\7f91711
-Ref: --exclude-from\7f91830
-Ref: --exclude-caches\7f91976
-Ref: --exclude-caches-under\7f92170
-Ref: --exclude-caches-all\7f92348
-Ref: --exclude-tag\7f92477
-Ref: --exclude-tag-under\7f92632
-Ref: --exclude-tag-all\7f92800
-Ref: --exclude-vcs\7f92914
-Ref: --file\7f93069
-Ref: --files-from\7f93269
-Ref: --force-local\7f93472
-Ref: --format\7f93663
-Ref: --group\7f94333
-Ref: --gzip\7f94681
-Ref: --gunzip\7f94681
-Ref: --ungzip\7f94681
-Ref: --hard-dereference\7f94904
-Ref: --help\7f95091
-Ref: --ignore-case\7f95225
-Ref: --ignore-command-error\7f95352
-Ref: --ignore-failed-read\7f95463
-Ref: --ignore-zeros\7f95593
-Ref: --incremental\7f95738
-Ref: --index-file\7f96003
-Ref: --info-script\7f96088
-Ref: --new-volume-script\7f96088
-Ref: --interactive\7f96409
-Ref: --keep-newer-files\7f96621
-Ref: --keep-old-files\7f96763
-Ref: --label\7f96894
-Ref: --listed-incremental\7f97182
-Ref: --lzma\7f97546
-Ref: --mode\7f97646
-Ref: --mtime\7f97937
-Ref: --multi-volume\7f98378
-Ref: --newer\7f98579
-Ref: --newer-mtime\7f98857
-Ref: --no-anchored\7f99081
-Ref: --no-check-device\7f99218
-Ref: --no-delay-directory-restore\7f99401
-Ref: --no-ignore-case\7f99654
-Ref: --no-ignore-command-error\7f99747
-Ref: --no-overwrite-dir\7f99902
-Ref: --no-quote-chars\7f100045
-Ref: --no-recursion\7f100226
-Ref: --no-same-owner\7f100331
-Ref: --no-same-permissions\7f100514
-Ref: --no-unquote\7f100716
-Ref: --no-wildcards\7f100854
-Ref: --no-wildcards-match-slash\7f100938
-Ref: --null\7f101040
-Ref: --numeric-owner\7f101268
-Ref: --occurrence\7f101919
-Ref: --old-archive\7f102486
-Ref: --one-file-system\7f102535
-Ref: --overwrite\7f102713
-Ref: --overwrite-dir\7f102855
-Ref: --owner\7f103000
-Ref: --pax-option\7f103379
-Ref: --portability\7f103678
-Ref: --posix\7f103743
-Ref: --preserve\7f103785
-Ref: --preserve-order\7f103923
-Ref: --preserve-permissions\7f103987
-Ref: --same-permissions\7f103987
-Ref: --quote-chars\7f104401
-Ref: --quoting-style\7f104554
-Ref: --read-full-records\7f104875
-Ref: --record-size\7f105040
-Ref: --recursion\7f105171
-Ref: --recursive-unlink\7f105274
-Ref: --remove-files\7f105441
-Ref: --restrict\7f105587
-Ref: --rmt-command\7f105775
-Ref: --rsh-command\7f105916
-Ref: --same-order\7f106038
-Ref: --same-owner\7f106330
-Ref: --seek\7f106707
-Ref: --show-defaults\7f106964
-Ref: --show-omitted-dirs\7f107332
-Ref: --show-transformed-names\7f107486
-Ref: --show-stored-names\7f107486
-Ref: --sparse\7f107875
-Ref: --sparse-version\7f108014
-Ref: --starting-file\7f108238
-Ref: --strip-components\7f108427
-Ref: --suffix\7f108739
-Ref: --tape-length\7f108874
-Ref: --test-label\7f109029
-Ref: --to-command\7f109181
-Ref: --to-stdout\7f109340
-Ref: --totals\7f109493
-Ref: --touch\7f109724
-Ref: --transform\7f109926
-Ref: --unlink-first\7f110518
-Ref: --unquote\7f110686
-Ref: --use-compress-program\7f110793
-Ref: --utc\7f110961
-Ref: --verbose\7f111054
-Ref: --verify\7f111306
-Ref: --version\7f111424
-Ref: --volno-file\7f111596
-Ref: --wildcards\7f111783
-Ref: --wildcards-match-slash\7f111903
-Ref: Option Summary-Footnote-1\7f112031
-Node: Short Option Summary\7f112249
-Node: help\7f114420
-Ref: help-Footnote-1\7f118250
-Node: defaults\7f118460
-Node: verbose\7f119477
-Ref: totals\7f121778
-Ref: Progress information\7f123368
-Ref: show-omitted-dirs\7f124347
-Ref: block-number\7f124766
-Ref: verbose-Footnote-1\7f125793
-Node: checkpoints\7f125900
-Node: interactive\7f131291
-Node: operations\7f133374
-Node: Basic tar\7f133633
-Ref: Basic tar-Footnote-1\7f136737
-Node: Advanced tar\7f136881
-Node: Operations\7f137726
-Node: append\7f139696
-Ref: append-Footnote-1\7f142861
-Node: appending files\7f143027
-Node: multiple\7f144808
-Node: update\7f147498
-Node: how to update\7f148537
-Node: concatenate\7f150320
-Ref: concatenate-Footnote-1\7f153569
-Node: delete\7f153707
-Node: compare\7f155550
-Node: create options\7f157040
-Node: override\7f157498
-Node: Ignore Failed Read\7f160936
-Node: extract options\7f161156
-Node: Reading\7f162052
-Node: read full records\7f163615
-Node: Ignore Zeros\7f163951
-Node: Writing\7f164942
-Node: Dealing with Old Files\7f165499
-Node: Overwrite Old Files\7f167926
-Node: Keep Old Files\7f169383
-Node: Keep Newer Files\7f169893
-Node: Unlink First\7f170183
-Node: Recursive Unlink\7f170587
-Node: Data Modification Times\7f171140
-Node: Setting Access Permissions\7f171950
-Node: Directory Modification Times and Permissions\7f172582
-Node: Writing to Standard Output\7f176188
-Node: Writing to an External Program\7f177723
-Node: remove files\7f180460
-Node: Scarce\7f180653
-Node: Starting File\7f180901
-Node: Same Order\7f181721
-Node: backup\7f182557
-Node: Applications\7f185781
-Node: looking ahead\7f187294
-Node: Backups\7f188120
-Node: Full Dumps\7f189952
-Node: Incremental Dumps\7f191758
-Ref: device numbers\7f194894
-Ref: incremental-op\7f198876
-Ref: Incremental Dumps-Footnote-1\7f199250
-Ref: Incremental Dumps-Footnote-2\7f199400
-Node: Backup Levels\7f199887
-Node: Backup Parameters\7f202274
-Node: General-Purpose Variables\7f203455
-Ref: RSH\7f206612
-Node: Magnetic Tape Control\7f208491
-Node: User Hooks\7f209828
-Node: backup-specs example\7f211156
-Node: Scripted Backups\7f212299
-Ref: Scripted Backups-Footnote-1\7f215161
-Node: Scripted Restoration\7f215545
-Node: Choosing\7f218153
-Node: file\7f219338
-Ref: remote-dev\7f222037
-Ref: local and remote archives\7f222429
-Node: Selecting Archive Members\7f223459
-Ref: input name quoting\7f224140
-Node: files\7f226126
-Ref: files-Footnote-1\7f229400
-Node: nul\7f229558
-Node: exclude\7f230855
-Node: problems with exclude\7f235619
-Node: wildcards\7f237664
-Node: controlling pattern-matching\7f240248
-Ref: controlling pattern-matching-Footnote-1\7f244238
-Node: quoting styles\7f244454
-Ref: escape sequences\7f244800
-Node: transform\7f250936
-Ref: show-transformed-names\7f252926
-Node: after\7f256915
-Node: recurse\7f260580
-Node: one\7f263349
-Node: directory\7f264845
-Node: absolute\7f267918
-Ref: absolute-Footnote-1\7f271108
-Node: Date input formats\7f271459
-Node: General date syntax\7f273775
-Node: Calendar date items\7f276726
-Node: Time of day items\7f278723
-Node: Time zone items\7f280839
-Node: Day of week items\7f282073
-Node: Relative items in date strings\7f283062
-Node: Pure numbers in date strings\7f285864
-Node: Seconds since the Epoch\7f286845
-Node: Specifying time zone rules\7f288466
-Node: Authors of get_date\7f290830
-Node: Formats\7f291582
-Node: Compression\7f296270
-Node: gzip\7f296562
-Ref: auto-compress\7f299320
-Ref: gzip-Footnote-1\7f303156
-Node: sparse\7f303205
-Node: Attributes\7f306259
-Node: Portability\7f312230
-Node: Portable Names\7f313716
-Node: dereference\7f314421
-Node: hard links\7f315822
-Ref: hard links-Footnote-1\7f318780
-Node: old\7f318836
-Node: ustar\7f320020
-Node: gnu\7f320611
-Node: posix\7f321488
-Node: PAX keywords\7f321969
-Node: Checksumming\7f326297
-Node: Large or Negative Values\7f328221
-Node: Other Tars\7f329821
-Node: Split Recovery\7f330957
-Node: Sparse Recovery\7f334689
-Ref: extracting sparse v.0.x\7f338322
-Ref: Sparse Recovery-Footnote-1\7f341611
-Ref: Sparse Recovery-Footnote-2\7f341634
-Node: cpio\7f341755
-Node: Media\7f346511
-Node: Device\7f348441
-Node: Remote Tape Server\7f353509
-Node: Common Problems and Solutions\7f357239
-Node: Blocking\7f357631
-Node: Format Variations\7f364138
-Node: Blocking Factor\7f365050
-Node: Many\7f376704
-Node: Tape Positioning\7f380498
-Node: mt\7f382371
-Node: Using Multiple Tapes\7f383926
-Node: Multi-Volume Archives\7f385992
-Ref: tape-length\7f387477
-Ref: change volume prompt\7f387781
-Ref: volno-file\7f388651
-Ref: info-script\7f389203
-Ref: Multi-Volume Archives-Footnote-1\7f394387
-Ref: Multi-Volume Archives-Footnote-2\7f394497
-Node: Tape Files\7f394564
-Node: Tarcat\7f396048
-Node: label\7f397093
-Ref: --test-label option\7f398722
-Ref: label-Footnote-1\7f401767
-Node: verify\7f402002
-Node: Write Protection\7f405302
-Node: Changes\7f406132
-Node: Configuring Help Summary\7f409717
-Node: Fixing Snapshot Files\7f416220
-Node: Tar Internals\7f418405
-Node: Standard\7f418737
-Node: Extensions\7f440938
-Node: Sparse Formats\7f443498
-Node: Old GNU Format\7f444788
-Node: PAX 0\7f447199
-Node: PAX 1\7f450326
-Node: Snapshot Files\7f452060
-Node: Dumpdir\7f456513
-Node: Genfile\7f459759
-Node: Generate Mode\7f460852
-Node: Status Mode\7f465149
-Node: Exec Mode\7f466948
-Node: Free Software Needs Free Documentation\7f469184
-Node: Copying This Manual\7f474155
-Node: GNU Free Documentation License\7f474437
-Node: Index of Command Line Options\7f496844
-Node: Index\7f520649
-\1f
-End Tag Table
+++ /dev/null
-This is tar.info, produced by makeinfo version 4.8.90 from tar.texi.
-
- This manual is for GNU `tar' (version 1.20, 14 April 2008), which
-creates and extracts files from archives.
-
- Copyright (C) 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001, 2003,
-2004, 2005, 2006, 2007, 2008 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.1 or any later version published by the Free Software
- Foundation; with no Invariant Sections, 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. Buying copies from the FSF supports
- it in developing GNU and promoting software freedom."
-
-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
-
-\1f
-File: tar.info, Node: Top, Next: Introduction, Up: (dir)
-
-GNU tar: an archiver tool
-*************************
-
-This manual is for GNU `tar' (version 1.20, 14 April 2008), which
-creates and extracts files from archives.
-
- Copyright (C) 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001, 2003,
-2004, 2005, 2006, 2007, 2008 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.1 or any later version published by the Free Software
- Foundation; with no Invariant Sections, 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. Buying copies from the FSF supports
- it in developing GNU and promoting software freedom."
-
- 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::
-
-Appendices
-
-* Changes::
-* Configuring Help Summary::
-* Fixing Snapshot Files::
-* Tar Internals::
-* Genfile::
-* Free Software Needs Free Documentation::
-* Copying This Manual::
-* 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::
-* 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::
-
-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.
-* 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 get_date:: 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
-
-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
-
-\1f
-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
-
-\1f
-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.)
-
-\1f
-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'.
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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.20
-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.
-
-\1f
-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. .
-
-\1f
-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::
-
-\1f
-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.
-
-
-\1f
-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'.
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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::
-
-\1f
-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 the 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::.
-
-\1f
-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
-
-
-\1f
-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.
-
-\1f
-File: tar.info, Node: create, Next: list, Prev: Two Frequent Options, Up: Tutorial
-
-2.6 How to Create Archives
-==========================
-
- _(This message will disappear, once this node revised.)_
-
-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::
-
-\1f
-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.
-
-\1f
-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_. You could also say:
-
- $ tar blues --create folk --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::.
-
-\1f
-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.
-
-\1f
-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 blues --create folk --file=collection.tar jazz
-
-is confusing as it is. When shown using short forms, however, it
-becomes much more so:
-
- $ tar blues -c folk -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.
-
-\1f
-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.
-
-\1f
-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, 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
-
-The archive `bfiles.tar' would list as follows:
-
- ./birds
- baboon
- ./box
-
-Be sure to use a `--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME') option just
-as with `--create' (`-c') to specify the name of the archive.
-
- 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:
-
- $ tar cfv archive /etc/mail
- tar: Removing leading `/' from member names
- /etc/mail/
- /etc/mail/sendmail.cf
- /etc/mail/aliases
- $ tar tf archive
- etc/mail/
- etc/mail/sendmail.cf
- etc/mail/aliases
-
- 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.
-
- 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=afiles.tar apple' would
-only print `apple'.
-
- Because `tar' preserves file names, these must be specified as they
-appear in the archive (i.e., relative to the directory from which the
-archive was created). Therefore, it is essential when specifying
-member names to `tar' that you give the exact member names. For
-example, `tar --list --file=bfiles.tar birds' would produce an error
-message something like `tar: birds: Not found in archive', because
-there is no member named `birds', only one named `./birds'. While the
-names `birds' and `./birds' name the same file, _member_ names by
-default are compared verbatim.
-
- However, `tar --list --file=bfiles.tar baboon' would respond with
-`baboon', because this exact member name is in the archive file
-`bfiles.tar'. If you are not sure of the exact file name, use
-"globbing patterns", for example:
-
- $ tar --list --file=bfiles.tar --wildcards '*b*'
-
-will list all members whose name contains `b'. *Note wildcards::, for
-a detailed discussion of globbing patterns and related `tar' command
-line options.
-
-* Menu:
-
-* list dir::
-
-\1f
-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.
-
-\1f
-File: tar.info, Node: extract, Next: going further, Prev: list, Up: Tutorial
-
-2.8 How to Extract Members from an Archive
-==========================================
-
- _(This message will disappear, once this node revised.)_
-
-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::
-
-\1f
-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-- 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
-
-\1f
-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. `tar --extract --file=bfiles.tar birds' will fail,
-because there is no member named `birds'. To extract the member named
-`./birds', you must specify `tar --extract --file=bfiles.tar ./birds'.
-If you don't remember the exact member names, use `--list' (`-t') option
-(*note list::). You can also extract those members that match a
-specific "globbing pattern". For example, to extract from `bfiles.tar'
-all files that begin with `b', no matter their directory prefix, you
-could type:
-
- $ tar -x -f bfiles.tar --wildcards --no-anchored 'b*'
-
-Here, `--wildcards' instructs `tar' to treat command line arguments as
-globbing patterns and `--no-anchored' informs it that the patterns
-apply to member names after any `/' delimiter. The use of globbing
-patterns is discussed in detail in *Note wildcards::.
-
- 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.
-
-\1f
-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.
-
-\1f
-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').
-
-\1f
-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/folk
- practice/jazz
- practice/rock
-
-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.
-
-\1f
-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.)_
-
-\1f
-File: tar.info, Node: tar invocation, Next: operations, Prev: Tutorial, Up: Top
-
-3 Invoking GNU `tar'
-********************
-
- _(This message will disappear, once this node revised.)_
-
-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::
-* help::
-* defaults::
-* verbose::
-* checkpoints::
-* interactive::
-
-\1f
-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 is
-improperly written. Errors may be encountered later, while
-encountering an error 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 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::).
-
-\1f
-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 (two lists of four
-operations each 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.
-
-\1f
-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. (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.) 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
-
-\1f
-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'.
-
-\1f
-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.
-
-\1f
-File: tar.info, Node: Old Options, Next: Mixing, Prev: Short Options, Up: Styles
-
-3.3.3 Old Option Style
-----------------------
-
- _(This message will disappear, once this node revised.)_
-
-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(1). 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'.
-
- On the other hand, this old style syntax makes 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.
-
- Old options are kept for compatibility with old versions of `tar'.
-
- 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
-
- As far as we know, all `tar' programs, GNU and non-GNU, support old
-options. GNU `tar' supports them not only for historical reasons, but
-also because many people are used to them. For compatibility with Unix
-`tar', the first argument is always treated as containing command and
-option letters even if it doesn't start with `-'. Thus, `tar c' is
-equivalent to `tar -c': both of them specify the `--create' (`-c')
-command to create an archive.
-
- ---------- Footnotes ----------
-
- (1) Beware that if you precede options with a dash, you are
-announcing the short option style instead of the old option style;
-short options are decoded differently.
-
-\1f
-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.
-
-\1f
-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::
-
-\1f
-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 a 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::.
-
-
-\1f
-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. This option disables that behavior. *Note
- absolute::.
-
-`--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 system does not support
- `--atime-preserve=system', you might be able to preserve access
- times reliably by 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. *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 `--checklist-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::.
-
-`--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 creating a `tar' archive, `tar' will archive the file that a
- symbolic link points to, rather than archiving the symlink. *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-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::.
-
-`--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-tag=FILE'
- Exclude from dump any directory containing file named FILE, but
- dump the directory node and FILE itself. *Note 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::.
-
-`--exclude-tag-all=FILE'
- Exclude from dump any directory containing file named FILE. *Note
- exclude::.
-
-`--exclude-vcs'
- Exclude from dump directories and files, that are internal for some
- widely used version control systems.
-
- *Note exclude::.
-
-`--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.
-
-`--group=GROUP'
- Files added to the `tar' archive will have a group ID of GROUP,
- rather than the group from the source file. GROUP is first decoded
- as a group symbolic name, but if this interpretation fails, it has
- to be a decimal numeric group ID. *Note override::.
-
- Also see the comments for the `--owner=USER' option.
-
-`--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::.
-
-`--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 Reading::.
-
-`--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=SCRIPT-FILE'
-`--new-volume-script=SCRIPT-FILE'
-`-F SCRIPT-FILE'
- When `tar' is performing multi-tape backups, SCRIPT-FILE is run at
- the end of each tape. If SCRIPT-FILE exits with nonzero status,
- `tar' fails immediately. *Note info-script::, for a detailed
- discussion of SCRIPT-FILE.
-
-`--interactive'
-`--confirmation'
-`-w'
- Specifies that `tar' should ask the user for confirmation before
- performing potentially destructive options, such as overwriting
- files. *Note interactive::.
-
-`--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. *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::.
-
-`--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::.
-
-`--lzma'
- This option tells `tar' to read or write archives through `lzma'.
- *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::.
-
-`--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-anchored'
- An exclude pattern can match any subsequence of the name's
- components. *Note controlling pattern-matching::.
-
-`--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-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-unquote'
- Treat all input file or member names literally, do not interpret
- escape sequences. *Note input name quoting::.
-
-`--no-wildcards'
- Do not use wildcards. *Note controlling pattern-matching::.
-
-`--no-wildcards-match-slash'
- Wildcards do not match `/'. *Note controlling pattern-matching::.
-
-`--null'
- When `tar' is using the `--files-from' option, this option
- instructs `tar' to expect file names terminated with NUL, so `tar'
- can correctly work with file names that contain newlines. *Note
- nul::.
-
-`--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.
-
-`--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 is first decoded as a user symbolic name, but if this
- interpretation fails, it has to be a decimal numeric user ID.
- *Note override::.
-
- This option does not affect extraction from archives.
-
-`--pax-option=KEYWORD-LIST'
- This option is meaningful only with POSIX.1-2001 archives (*note
- posix::). It 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'
- Synonymous with specifying both `--preserve-permissions' and
- `--same-order'. *Note Setting Access Permissions::.
-
-`--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'
- Instructs `tar' to use SIZE bytes per record when accessing the
- archive. *Note Blocking Factor::.
-
-`--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.
-
-`--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
-
-`--show-omitted-dirs'
- Instructs `tar' to mention the directories it is skipping when
- operating on a `tar' archive. *Note show-omitted-dirs::.
-
-`--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::.
-
-`--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'.
-
- , summary
-
-`--suffix=SUFFIX'
- Alters the suffix `tar' uses when backing up files from the default
- `~'. *Note backup::.
-
-`--tape-length=NUM'
-`-L NUM'
- Specifies the length of tapes that `tar' is writing as being
- NUM x 1024 bytes long. *Note Using Multiple Tapes::.
-
-`--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'
- 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'
- 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'.
-
-`--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::.
-
-`--wildcards'
- Use wildcards when matching member names with patterns. *Note
- controlling pattern-matching::.
-
-`--wildcards-match-slash'
- Wildcards match `/'. *Note controlling pattern-matching::.
-
- ---------- 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.
-
-\1f
-File: tar.info, Node: Short Option Summary, 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::.
--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 later 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::.
-
-\1f
-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.20
- Copyright (C) 2008 Free Software Foundation, Inc.
- This is free software. You may redistribute copies of it under the terms
- of the GNU General Public License <http://www.gnu.org/licenses/gpl.html>.
- 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' option 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'
-
-\1f
-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.
-
-\1f
-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 cfv -', or even `tar cv'--if the installer let
-standard output be the default archive). In that case `tar' writes
-verbose output to the standard error stream.
-
- 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 if 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.
-
-\1f
-File: tar.info, Node: checkpoints, Next: interactive, 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 "meta-characters". The
-`%s' meta-character is replaced with the "type" of the checkpoint:
-`write' or `read' (or a corresponding translated version in locales
-other than POSIX). The `%u' meta-character 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
-
- Aside from meta-character 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=\rHit %s checkpoint #%u"
-
- 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.
-
- 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 program. For
-example:
-
- $ tar -c --checkpoint=1000 --checkpoint-action=exec=/sbin/cpoint
-
- This program is executed using `/bin/sh -c', with no additional
-arguments. Its exit code is ignored. It 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'
- The checkpoint number.
-
-`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.
-
- 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.
-
-\1f
-File: tar.info, Node: interactive, Prev: checkpoints, Up: tar invocation
-
-3.9 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.
-
-\1f
-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::
-
-\1f
-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 cfT empty-archive.tar /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.
-
-\1f
-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::
-
-\1f
-File: tar.info, Node: Operations, Next: append, Up: Advanced tar
-
-4.2.1 The Five Advanced `tar' Operations
-----------------------------------------
-
- _(This message will disappear, once this node revised.)_
-
-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', `rock', 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'
-`-r'
- 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.
-
-\1f
-File: tar.info, Node: append, Next: update, Prev: Operations, Up: Advanced tar
-
-4.2.2 How to Add Files to Existing Archives: `--append'
--------------------------------------------------------
-
- _(This message will disappear, once this node revised.)_
-
-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 four
-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' option, or the disk copy
-is newer than the the one in the archive and you invoke `tar' with
-`--keep-newer-files' option
-
-\1f
-File: tar.info, Node: appending files, Next: multiple, Up: append
-
-4.2.2.1 Appending Files to an Archive
-.....................................
-
- _(This message will disappear, once this node revised.)_
-
-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
-
-\1f
-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 *Note
--occurrence: Option Summary, for the description of `--occurrence'
-option.
-
-\1f
-File: tar.info, Node: update, Next: concatenate, Prev: append, Up: Advanced tar
-
-4.2.3 Updating an Archive
--------------------------
-
- _(This message will disappear, once this node revised.)_
-
-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::
-
-\1f
-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::.
-
-\1f
-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, *note multiple::.
-
-\1f
-File: tar.info, Node: delete, Next: compare, Prev: concatenate, Up: Advanced tar
-
-4.2.5 Removing Archive Members Using `--delete'
------------------------------------------------
-
- _(This message will disappear, once this node revised.)_
-
-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'.
-
-\1f
-File: tar.info, Node: compare, Prev: delete, Up: Advanced tar
-
-4.2.6 Comparing Archive Members with the File System
-----------------------------------------------------
-
- _(This message will disappear, once this node revised.)_
-
-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 later goal, *Note verify::.
-
-\1f
-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.
-* Ignore Failed Read::
-
-\1f
-File: tar.info, Node: override, Next: Ignore Failed Read, 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 the 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
- UTC, 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
- ...
-
-`--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. The argument USER can be either an existing user symbolic
- name, or a decimal numeric user ID.
-
- 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. The argument GROUP
- can be either an existing group symbolic name, or a decimal
- numeric group ID.
-
-\1f
-File: tar.info, Node: Ignore Failed Read, Prev: override, Up: create options
-
-4.3.2 Ignore Fail Read
-----------------------
-
-`--ignore-failed-read'
- Do not exit with nonzero on unreadable files or directories.
-
-\1f
-File: tar.info, Node: extract options, Next: backup, Prev: create options, Up: operations
-
-4.4 Options Used by `--extract'
-===============================
-
- _(This message will disappear, once this node revised.)_
-
-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
-
-\1f
-File: tar.info, Node: Reading, Next: Writing, Up: extract options
-
-4.4.1 Options to Help Read Archives
------------------------------------
-
- _(This message will disappear, once this node revised.)_
-
-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::
-
-\1f
-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.
-
-\1f
-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'.
-
-\1f
-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::
-
-\1f
-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.
-
- 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.
-
-\1f
-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.
-
-\1f
-File: tar.info, Node: Keep Old Files, Next: Keep Newer Files, Prev: Overwrite Old Files, Up: Writing
-
-Keep Old Files
-..............
-
-`--keep-old-files'
-`-k'
- Do not replace existing files from archive. The
- `--keep-old-files' (`-k') option prevents `tar' from replacing
- existing files with files with the same name from the archive. The
- `--keep-old-files' option is meaningless with `--list' (`-t').
- Prevents `tar' from replacing files in the file system during
- extraction.
-
-\1f
-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').
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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').
-
-\1f
-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').
-
-\1f
-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
-`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.
-
-\1f
-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.
-
-\1f
-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. COMMAND may contain command line
- arguments. The program is executed via `sh -c'. 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.
-
- In addition to these variables, `TAR_VERSION' contains the GNU `tar'
-version number.
-
- 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.
-
-\1f
-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.
-
-\1f
-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::
-
-\1f
-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 restart the
-same `tar' operation. In this case, `--starting-file' is not necessary.
-*Note Incremental Dumps::, *Note interactive::, and *note exclude::.)
-
-\1f
-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.
-
-\1f
-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 has having similar names through the side-effect of name
-truncation. (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.
-
-`--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.
-
-
-\1f
-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", which is one a Unix redirection mechanism:
-
- $ (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 short 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.
-
-\1f
-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::.
-
-\1f
-File: tar.info, Node: Backups, Next: Choosing, Prev: operations, Up: Top
-
-5 Performing Backups and Restoring Files
-****************************************
-
- _(This message will disappear, once this node revised.)_
-
-GNU `tar' is distributed along with the scripts which the Free Software
-Foundation uses for performing backups. There is no corresponding
-scripts available yet for doing restoration of files. 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 at these places:
-
- http://www.cs.umd.edu/projects/amanda/amanda.html
- ftp://ftp.cs.umd.edu/pub/amanda
-
- 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
-
-\1f
-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.
-
-\1f
-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
-
- 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 a 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 considers
-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 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
-
-\1f
-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.
-
-\1f
-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'
-
-\1f
-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 file systems 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.
-
-\1f
-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
- }
-
-\1f
-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.
-
-\1f
-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]"
-
-\1f
-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.
-
-\1f
-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' 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.
-
-\1f
-File: tar.info, Node: Choosing, Next: Date input formats, Prev: Backups, Up: Top
-
-6 Choosing Files and Names for `tar'
-************************************
-
- _(This message will disappear, once this node revised.)_
-
-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
-
-\1f
-File: tar.info, Node: file, Next: Selecting Archive Members, Up: Choosing
-
-6.1 Choosing and Naming Archive Files
-=====================================
-
- _(This message will disappear, once this node revised.)_
-
-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 complete the remote connection, if possible, and prompt you
-for a username and password. If you use
-`--file=@HOSTNAME:/DEV/FILE-NAME', `tar' will complete the remote
-connection, if possible, 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',
-were 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.
-
-\1f
-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.
-
-\1f
-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 can not 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
-
-In the file list given by `-T' option, any file name beginning with `-'
-character 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
-
-
- Notice that the option parsing algorithm used with `-T' is stricter
-than the one used by shell. Namely, when specifying option arguments,
-you should observe the following rules:
-
- * When using short (single-letter) option form, its argument must
- immediately follow the option letter, without any intervening
- whitespace. For example: `-Cdir'.
-
- * When using long option form, the option argument must be separated
- from the option by a single equal sign. No whitespace is allowed
- on any side of the equal sign. For example: `--directory=dir'.
-
- * For both short and long option forms, the option argument can be
- given on the next line after the option name, e.g.:
-
- --directory
- dir
-
- and
-
- -C
- dir
-
- If you happen to have a file whose name starts with `-', precede it
-with `--add-file' option to prevent it from being recognized as an
-option. For example: `--add-file=--my-file'.
-
-* 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.
-
-\1f
-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.
-
- 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.
-
- 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' get 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
-
-\1f
-File: tar.info, Node: exclude, Next: wildcards, Prev: files, Up: Choosing
-
-6.4 Excluding Some Files
-========================
-
- _(This message will disappear, once this node revised.)_
-
-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.
-
-`--exclude-vcs'
- Exclude files and directories used by some version control systems.
-
- As of version 1.20, 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'
-
- * `.cvsignore'
-
- * `.svn/', and everything under it
-
- * `.arch-ids/', and everything under it
-
- * `{arch}/', and everything under it
-
- * `=RELEASE-ID'
-
- * `=meta-update'
-
- * `=update'
-
- 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::
-
-\1f
-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.
-
-
-\1f
-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::
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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 file to
-an archive, its file name is recorded in the archive 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 two 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 to the above invocation `--verbose' (`-v') option, 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 is `stdlib.h' 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'
- 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.
-
- 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.
-
-
- Any delimiter can be used in lieue 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/\//-/'.
-
- 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. Prepend `/prefix/' to each file name:
-
- $ tar --transform 's,^,/prefix/,' -x -f arch.tar
-
- 4. Convert each file name to lower case:
-
- $ tar --transform 's/.*/\L&/' -x -f arch.tar
-
-
- 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/,'
-
-\1f
-File: tar.info, Node: after, Next: recurse, Prev: transform, Up: Choosing
-
-6.8 Operating Only on New Files
-===============================
-
- _(This message will disappear, once this node revised.)_
-
-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.
-
-\1f
-File: tar.info, Node: recurse, Next: one, Prev: after, Up: Choosing
-
-6.9 Descending into Directories
-===============================
-
- _(This message will disappear, once this node revised.)_
-
-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' 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', or look.
-
-`--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'.
-
-\1f
-File: tar.info, Node: one, Prev: recurse, Up: Choosing
-
-6.10 Crossing File System Boundaries
-====================================
-
- _(This message will disappear, once this node revised.)_
-
-`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
-
-\1f
-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 `orange-colored'.
-
- 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 `--directory' is disabled by `--null' option.
-
-\1f
-File: tar.info, Node: absolute, Prev: directory, Up: one
-
-6.10.2 Absolute File Names
---------------------------
-
- _(This message will disappear, once this node revised.)_
-
-`--absolute-names'
-`-P'
- Do not strip leading slashes from file names, and permit file names
- containing a `..' file name component.
-
- By default, GNU `tar' drops a leading `/' on input or output, and
-complains about file names containing a `..' component. This option
-turns off this behavior.
-
- 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)
-
- 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 files. Preserves leading slash when 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:
-
- $ (cd / && tar -c -f archive.tar home)
- # or:
- $ tar -c -f archive.tar -C / home
-
- ---------- 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.
-
-\1f
-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 `get_date'
-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, 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 get_date:: Bellovin, Eggert, Salz, Berets, et al.
-
-\1f
-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
-
- * 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 --iso-8601=ns | tr T ' ' # --iso-8601 is a GNU extension.
- 2004-02-29 16:21:42,692722128-0800
- $ 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.
-
-\1f
-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
-
-\1f
-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. 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). The MINUTE part of
-the time of day may not be elided when a time zone correction is used.
-This is the best way to specify a time zone correction by fractional
-parts of an hour.
-
- Either `am'/`pm' or a time zone correction may be specified, but not
-both.
-
-\1f
-File: tar.info, Node: Time zone items, Next: Day of week 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::).
-
-\1f
-File: tar.info, Node: Day of week items, Next: Relative items in date strings, Prev: Time zone items, Up: Date input formats
-
-7.5 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.
-
-\1f
-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.6 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.
-
-\1f
-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.7 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.
-
-\1f
-File: tar.info, Node: Seconds since the Epoch, Next: Specifying time zone rules, Prev: Pure numbers in date strings, Up: Date input formats
-
-7.8 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.
-
-\1f
-File: tar.info, Node: Specifying time zone rules, Next: Authors of get_date, Prev: Seconds since the Epoch, Up: Date input formats
-
-7.9 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.
-
-\1f
-File: tar.info, Node: Authors of get_date, Prev: Specifying time zone rules, Up: Date input formats
-
-7.10 Authors of `get_date'
-==========================
-
-`get_date' was 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.
-
- This chapter was originally produced by Franc,ois Pinard
-(<pinard@iro.umontreal.ca>) from the `getdate.y' source code, and then
-edited by K. Berry (<kb@cs.umb.edu>).
-
-\1f
-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.20 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'
-
-\1f
-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
-
-\1f
-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
-`gzip', `bzip2' and `lzma' compression programs. For backward
-compatibility, it also supports `compress' command, although we
-strongly recommend against using it, because it is by far less
-effective than 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,
-`--lzma' to create an LZMA compressed archive and `-Z' (`--compress')
-to use `compress' program. For example:
-
- $ tar cfz archive.tar.gz .
-
- You can also let GNU `tar' select the compression program basing 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 cfa archive.tar.bz2 .
-
-whereas the following one will use `lzma':
-
- $ tar cfa archive.tar.lzma .
-
- For a complete list of file name suffixes recognized by GNU `tar',
-*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 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 tfz -
-
- 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' (`-u')) them or delete
-(`--delete') members from them or add (`--append' (`-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 table summarizes compression options used by GNU `tar'.
-
-`--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'
- `.lzma' `lzma'
- `.tlz' `lzma'
-
-`-z'
-`--gzip'
-`--ungzip'
- Filter the archive through `gzip'.
-
- You can use `--gzip' and `--gunzip' 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; if you need to
- override them, set `GZIP' environment variable, e.g.:
-
- $ GZIP=--best tar cfz archive.tar.gz subdir
-
- Another way would be to avoid the `--gzip' (`--gunzip',
- `--ungzip', `-z') option and run `gzip' explicitly:
-
- $ tar cf - subdir | gzip --best -c - > archive.tar.gz
-
- About corrupted compressed archives: `gzip''ed files have no
- redundancy, for maximum compression. 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.
-
- There are pending suggestions for having a per-volume or per-file
- compression in GNU `tar'. This would allow for viewing the
- contents without decompression, and for resynchronizing
- decompression at every volume or file, in case of corrupted
- archives. Doing so, we might lose some compressibility. But this
- would have make recovering easier. So, there are pros and cons.
- We'll see!
-
-`-j'
-`--bzip2'
- Filter the archive through `bzip2'. Otherwise like `--gzip'.
-
-`--lzma'
- Filter the archive through `lzma'. Otherwise like `--gzip'.
-
-`-Z'
-`--compress'
-`--uncompress'
- Filter the archive through `compress'. Otherwise like `--gzip'.
-
-`--use-compress-program=PROG'
- Use external compression program PROG. Use this option if you
- have a compression program that GNU `tar' does not support. There
- are two requirements to which PROG should comply:
-
- First, when called without options, it should read data from
- standard input, compress it and output it on standard output.
-
- Secondly, if called with `-d' argument, 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 `--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 --use-compress=gpgz .
-
-Likewise, the following command will list its contents:
-
- $ tar -tf foo.tar.gpgz --use-compress=gpgz .
-
- ---------- Footnotes ----------
-
- (1) It also had patent problems in the past.
-
+++ /dev/null
-This is tar.info, produced by makeinfo version 4.8.90 from tar.texi.
-
- This manual is for GNU `tar' (version 1.20, 14 April 2008), which
-creates and extracts files from archives.
-
- Copyright (C) 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001, 2003,
-2004, 2005, 2006, 2007, 2008 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.1 or any later version published by the Free Software
- Foundation; with no Invariant Sections, 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. Buying copies from the FSF supports
- it in developing GNU and promoting software freedom."
-
-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
-
-\1f
-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 consecutive
-stretches of zeros. It then records in the archive for the file where
-the 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 holes created wherever the
-continuous stretches of zeros were found. Thus, if you use `--sparse',
-`tar' archives won't take more space than the original.
-
-`-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 presents a serious
-drawback. Namely, in order to determine if the file is sparse `tar'
-has to read it before trying to archive it, so in total the file is
-read *twice*. So, always bear in mind that the time needed to process
-all files with this option is roughly twice the time needed to archive
-them without it.
-
- 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'.
-
-\1f
-File: tar.info, Node: Attributes, Next: Portability, Prev: Compression, Up: Formats
-
-8.2 Handling File Attributes
-============================
-
- _(This message will disappear, once this node revised.)_
-
-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.
-
- Handling of file attributes
-
-`--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 `--old-archive' (`-o') 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').
-
-`--preserve'
- Same as both `--same-permissions' and `--same-order'.
-
- The `--preserve' option has no equivalent short option name. It
- is equivalent to `--same-permissions' plus `--same-order'.
-
-
-\1f
-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
-
-\1f
-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.
-
-\1f
-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. `--dereference'
-(`-h') is used with `--create' (`-c'), and causes `tar' to archive the
-files symbolic links point to, instead of the links themselves. When
-this option is used, when `tar' encounters a symbolic link, it will
-archive the linked-to file, instead of simply recording the presence of
-a symbolic link.
-
- The name under which the file is stored in the file system is not
-recorded in the archive. To record both the symbolic link name and the
-file name in the system, archive the file under both names. If all
-links were recorded automatically by `tar', an extracted file might be
-linked to a file name that no longer exists in the file system.
-
- If a linked-to file is encountered again by `tar' while creating the
-same archive, an entire second copy of it will be stored. (This
-_might_ be considered a bug.)
-
- So, for portable archives, do not archive symbolic links as such,
-and use `--dereference' (`-h'): many systems do not support symbolic
-links, and moreover, your distribution might be unusable if it contains
-unresolved symbolic links.
-
-\1f
-File: tar.info, Node: hard links, Next: old, Prev: dereference, Up: Portability
-
-8.3.3 Hard Links
-----------------
-
- _(This message will disappear, once this node revised.)_
-
-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
- -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 cfvv ../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 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 absense
-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.
-
-\1f
-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.
-
-\1f
-File: tar.info, Node: ustar, Next: gnu, Prev: old, Up: Portability
-
-8.3.5 Ustar Archive Format
---------------------------
-
-Archive format defined by 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 archive in `ustar' format, use `--format=ustar' option in
-conjunction with the `--create' (`-c').
-
-\1f
-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'.
-
-\1f
-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.
-
-\1f
-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
-
-`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'.
-
-`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.
-
-\1f
-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 eight 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
-accept any. 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' compute checksums both ways, and accept any 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 that 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.
-
-\1f
-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.
-
-\1f
-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
-
-\1f
-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 preceeded 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.
-
-\1f
-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 simething 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::).
-
-\1f
-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 inumbers (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).
-
-\1f
-File: tar.info, Node: Media, Next: Changes, 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::
-
-\1f
-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
-`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=NUM'
- Change tape after writing NUM x 1024 bytes.
-
- 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 FILE'
-`--info-script=FILE'
-`--new-volume-script=FILE'
- Execute `file' at end of each tape. This implies `--multi-volume'
- (`-M'). *Note info-script::, for a detailed description of this
- option.
-
-\1f
-File: tar.info, Node: Remote Tape Server, Next: Common Problems and Solutions, Prev: Device, Up: Media
-
-9.2 The 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. It is
-Copyright (C) 1983 by the Regents of the University of California, but
-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.
-
-\1f
-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
-
-\1f
-File: tar.info, Node: Blocking, Next: Many, Prev: Common Problems and Solutions, Up: Media
-
-9.4 Blocking
-============
-
- _(This message will disappear, once this node revised.)_
-
-"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. 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
-
-\1f
-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.
-
-\1f
-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
-loosing 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.
-
-\1f
-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
-
-\1f
-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**----------------
-
-\1f
-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.
-
-\1f
-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
-
-\1f
-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 disk.
-
- 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'
-`-L SIZE'
- Set maximum length of a volume. The SIZE argument should then be
- the usable size of the tape in units of 1024 bytes. This option
- selects `--multi-volume' automatically. For example:
-
- $ tar --create --tape-length=41943040 --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=SCRIPT-NAME'
-`--new-volume-script=SCRIPT-NAME'
-`-F SCRIPT-NAME'
- Specify the full name of the volume script to use. The script can
- be used to eject cassettes, or to broadcast messages such as
- `Someone please come change my tape' when performing unattended
- backups.
-
- The SCRIPT-NAME is executed without any command line arguments. 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'.
-
- 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 cMff /dev/tape0 /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/sh
- 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
-
-\1f
-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 give. *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.
-
-\1f
-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.
-
-\1f
-File: tar.info, Node: label, Next: verify, Prev: Using Multiple Tapes, Up: Media
-
-9.7 Including a Label in the Archive
-====================================
-
- _(This message will disappear, once this node revised.)_
-
-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 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 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 a single command line argument, `tar'
-compares the volume label with the argument. It exits with code 0 if
-the two strings match, and with code 2 otherwise. In this case no
-output is displayed. For example:
-
- $ tar --test-label --file=iamanarchive 'iamalable'
- => 0
- $ tar --test-label --file=iamanarchive 'iamalable' alabel
- => 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(1). 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.
-
- The `--label' was once called `--volume', but is not available under
-that name anymore.
-
- 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 cfMV /dev/tape "Daily backup for `date +%Y-%m-%d`"
- $ tar --create --file=/dev/tape --multi-volume \
- --volume="Daily backup for `date +%Y-%m-%d`"
-
- Also note that each label has its own date and time, which
-corresponds to 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 does give
-an idea of tape throughput only if the delays for rewinding tapes and
-the operator switching them were negligible, which is usually not the
-case.
-
- ---------- Footnotes ----------
-
- (1) 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'.
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-File: tar.info, Node: Changes, Next: Configuring Help Summary, Prev: Media, Up: Top
-
-Appendix A Changes
-******************
-
-This appendix lists some important user-visible changes between version
-GNU `tar' 1.20 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 -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-v7: (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 implementation,
- 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.
-
-\1f
-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.
-
-\1f
-File: tar.info, Node: Fixing Snapshot Files, Next: Tar Internals, Prev: Configuring Help Summary, Up: Top
-
-Appendix C Fixing Snapshot Files
-********************************
-
-Sometimes device numbers can change after upgrading your kernel version
-or recofiguring the harvare. Reportedly this is the case with some
-newer Linux kernels, when using LVM. In 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,
-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
-available from GNU `tar' home page
-(http://www.gnu.org/software/tar/utils/tar-snapshot-edit.html).
-
- To obtain the device numbers used 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 ).
-
- To update all occurrences of the given device number in the file, use
-`-r' option. 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 /var/backup/snap.a
- file version 2
- /tmp/snap: Device 0x0306 occurs 634 times.
- $ tar-snapshot-edit -b -r 0x0306-0x4500 /var/backup/snap.a
- file version 2
-
-\1f
-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::
-
-\1f
-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'.
-
-\1f
-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.
-
-\1f
-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 flows, 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
-
-\1f
-File: tar.info, Node: Old GNU Format, Next: PAX 0, Up: Sparse Formats
-
-D.0.1 Old GNU Format
---------------------
-
-The format introduced some time around 1990 (v. 1.09). It 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 entires) File map.
-504 1 isextended Bool `1' if an extension sparse
- header follows, or `0'
- otherwise.
-
- A header with `isextended=0' ends the map.
-
-\1f
-File: tar.info, Node: PAX 0, Next: PAX 1, Prev: Old GNU Format, Up: Sparse Formats
-
-D.0.2 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 `tar's
- results in extraction of sparse files in _compressed 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 tars.
-
-\1f
-File: tar.info, Node: PAX 1, Prev: PAX 0, Up: Sparse Formats
-
-D.0.3 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 tars and
-tars 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'.
-
-\1f
-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.20 supports three snapshot file formats. The
-first format, called "format 0", is the one used by GNU `tar' versions
-up to 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 version 1.15.1. Starting from
-version 1.16 and up to 1.20, 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:
-
- NFSDEV INODE NAME
-
- where:
-
- NFS
- A single plus character (`+'), if this directory is located on
- an NFS-mounted partition, or a single space otherwise;
-
- 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. A snapshot file begins with a format identifier, as described
- for version 1, e.g.:
-
- GNU tar-1.20-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 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. 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 number in
- ASCII notation.
-
- Field Type Description
- ---------------------------------------------------------------------
- nfs Character `1' if the directory is located on an
- NFS-mounted partition, or `0' otherwise;
- mtime-sec Number Modification time, seconds;
- mtime-nano Number Modification time, nanoseconds;
- dev-no Number Device number;
- i-no 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'.
-
-
-\1f
-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:
-
- R`source'\0T`dest'\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.
-
-\1f
-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.
-
-\1f
-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", i.e.,
-a string of characters, specifying 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.
-
- For each letter in contents string `genfile' will generate a "block"
-of data, filled with this letter and will write it to the fragment. The
-size of block is given by `--block-size' option. It defaults to 512.
-Thus, if the string consists of N characters, the resulting file
-fragment will contain `N*BLOCK-SIZE' of data.
-
- 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.
-
- 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 --status' command is `0' only if created
-file is actually sparse.
-
-\1f
-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 *
-
-\1f
-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 argument to this option gives the command line to be
-executed. The actual command line is constructed by inserting
-`--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'
-
- The rest of command line after `--run' or its equivalent specifies
-checkpoint values and actions to be executed upon reaching them.
-Checkpoint values are introduced with `--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.
-
-
- 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.
-
-\1f
-File: tar.info, Node: Free Software Needs Free Documentation, Next: Copying This Manual, 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'.
-
-\1f
-File: tar.info, Node: Copying This Manual, Next: Index of Command Line Options, Prev: Free Software Needs Free Documentation, Up: Top
-
-Appendix G Copying This Manual
-******************************
-
-* Menu:
-
-* GNU Free Documentation License:: License for copying this manual
-
-\1f
-File: tar.info, Node: GNU Free Documentation License, Up: Copying This Manual
-
-G.1 GNU Free Documentation License
-==================================
-
- Version 1.2, November 2002
-
- Copyright (C) 2000,2001,2002 Free Software Foundation, Inc.
- 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
-
- 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.
-
- 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 for under this License. Any other
- attempt to copy, modify, sublicense or distribute the Document is
- void, and will automatically terminate your rights under this
- License. However, parties who have received copies, or rights,
- from you under this License will not have their licenses
- terminated so long as such parties remain in full compliance.
-
- 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.
-
-G.1.1 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.2
- 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.
-
-\1f
-File: tar.info, Node: Index of Command Line Options, Next: Index, Prev: Copying This Manual, 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, *note Short Option
-Summary::.
-
-\0\b[index\0\b]
-* Menu:
-
-* absolute-names: absolute. (line 8)
-* absolute-names, summary: Option Summary. (line 6)
-* add-file: files. (line 84)
-* after-date: after. (line 26)
-* after-date, summary: Option Summary. (line 12)
-* anchored: controlling pattern-matching.
- (line 79)
-* anchored, summary: Option Summary. (line 15)
-* append: append. (line 8)
-* append, summary: Operation Summary. (line 6)
-* atime-preserve: Attributes. (line 14)
-* atime-preserve, summary: Option Summary. (line 19)
-* auto-compress: gzip. (line 69)
-* auto-compress, summary: Option Summary. (line 65)
-* backup: backup. (line 41)
-* backup, summary: Option Summary. (line 70)
-* block-number: verbose. (line 115)
-* block-number, summary: Option Summary. (line 75)
-* blocking-factor: Blocking Factor. (line 8)
-* blocking-factor, summary: Option Summary. (line 81)
-* bzip2: gzip. (line 122)
-* bzip2, summary: Option Summary. (line 86)
-* catenate: concatenate. (line 6)
-* catenate, summary: Operation Summary. (line 10)
-* check-device, described: Incremental Dumps. (line 99)
-* check-device, summary: Option Summary. (line 91)
-* check-links, described: hard links. (line 33)
-* check-links, summary: Option Summary. (line 142)
-* checkpoint: checkpoints. (line 6)
-* checkpoint, defined: checkpoints. (line 13)
-* checkpoint, summary: Option Summary. (line 96)
-* checkpoint-action: checkpoints. (line 6)
-* checkpoint-action, defined: checkpoints. (line 22)
-* checkpoint-action, summary: Option Summary. (line 104)
-* compare: compare. (line 8)
-* compare, summary: Operation Summary. (line 14)
-* compress: gzip. (line 129)
-* compress, summary: Option Summary. (line 151)
-* concatenate: concatenate. (line 6)
-* concatenate, summary: Operation Summary. (line 20)
-* confirmation, summary: Option Summary. (line 158)
-* 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 25)
-* 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 161)
-* delete: delete. (line 8)
-* delete, summary: Operation Summary. (line 29)
-* dereference: dereference. (line 6)
-* dereference, summary: Option Summary. (line 166)
-* diff, summary: Operation Summary. (line 33)
-* directory: directory. (line 11)
-* directory, summary: Option Summary. (line 172)
-* directory, using in --files-from argument: files. (line 60)
-* exclude: exclude. (line 11)
-* exclude, potential problems with: problems with exclude.
- (line 6)
-* exclude, summary: Option Summary. (line 179)
-* exclude-caches: exclude. (line 80)
-* exclude-caches, summary: Option Summary. (line 188)
-* exclude-caches-all: exclude. (line 88)
-* exclude-caches-all, summary: Option Summary. (line 201)
-* exclude-caches-under: exclude. (line 84)
-* exclude-caches-under, summary: Option Summary. (line 195)
-* exclude-from: exclude. (line 22)
-* exclude-from, summary: Option Summary. (line 183)
-* exclude-tag: exclude. (line 97)
-* exclude-tag, summary: Option Summary. (line 205)
-* exclude-tag-all: exclude. (line 105)
-* exclude-tag-all, summary: Option Summary. (line 213)
-* exclude-tag-under: exclude. (line 101)
-* exclude-tag-under, summary: Option Summary. (line 209)
-* exclude-vcs: exclude. (line 39)
-* exclude-vcs, summary: Option Summary. (line 217)
-* extract: extract. (line 8)
-* extract, additional options: extract options. (line 8)
-* extract, complementary notes: Basic tar. (line 48)
-* extract, summary: Operation Summary. (line 37)
-* extract, using with --listed-incremental: Incremental Dumps.
- (line 112)
-* file, short description: file. (line 17)
-* file, summary: Option Summary. (line 223)
-* file, tutorial: file tutorial. (line 6)
-* files-from: files. (line 14)
-* files-from, summary: Option Summary. (line 229)
-* force-local, short description: Device. (line 70)
-* force-local, summary: Option Summary. (line 235)
-* format, summary: Option Summary. (line 240)
-* get, summary: Operation Summary. (line 42)
-* group: override. (line 73)
-* group, summary: Option Summary. (line 265)
-* gunzip, summary: Option Summary. (line 273)
-* gzip: gzip. (line 88)
-* gzip, summary: Option Summary. (line 273)
-* hard-dereference, described: hard links. (line 61)
-* hard-dereference, summary: Option Summary. (line 281)
-* help: help tutorial. (line 6)
-* help, introduction: help. (line 26)
-* help, summary: Option Summary. (line 287)
-* ignore-case: controlling pattern-matching.
- (line 86)
-* ignore-case, summary: Option Summary. (line 292)
-* ignore-command-error: Writing to an External Program.
- (line 82)
-* ignore-command-error, summary: Option Summary. (line 296)
-* ignore-failed-read: Ignore Failed Read. (line 7)
-* ignore-failed-read, summary: Option Summary. (line 300)
-* ignore-zeros: Ignore Zeros. (line 6)
-* ignore-zeros, short description: Blocking Factor. (line 156)
-* ignore-zeros, summary: Option Summary. (line 304)
-* incremental, summary: Option Summary. (line 309)
-* incremental, using with --list: Incremental Dumps. (line 177)
-* index-file, summary: Option Summary. (line 316)
-* info-script: Multi-Volume Archives.
- (line 80)
-* info-script, short description: Device. (line 104)
-* info-script, summary: Option Summary. (line 319)
-* interactive: interactive. (line 14)
-* interactive, summary: Option Summary. (line 327)
-* keep-newer-files: Keep Newer Files. (line 6)
-* keep-newer-files, summary: Option Summary. (line 334)
-* keep-old-files: Keep Old Files. (line 6)
-* keep-old-files, introduced: Dealing with Old Files.
- (line 16)
-* keep-old-files, summary: Option Summary. (line 338)
-* label: label. (line 8)
-* label, summary: Option Summary. (line 343)
-* list: list. (line 6)
-* list, summary: Operation Summary. (line 46)
-* list, using with --incremental: Incremental Dumps. (line 177)
-* list, using with --listed-incremental: Incremental Dumps. (line 177)
-* list, using with --verbose: list. (line 30)
-* list, using with file name arguments: list. (line 68)
-* listed-incremental: Incremental Dumps. (line 14)
-* listed-incremental, summary: Option Summary. (line 350)
-* listed-incremental, using with --extract: Incremental Dumps.
- (line 112)
-* listed-incremental, using with --list: Incremental Dumps. (line 177)
-* lzma: gzip. (line 126)
-* lzma, summary: Option Summary. (line 358)
-* mode: override. (line 14)
-* mode, summary: Option Summary. (line 362)
-* mtime: override. (line 29)
-* mtime, summary: Option Summary. (line 368)
-* multi-volume: Multi-Volume Archives.
- (line 6)
-* multi-volume, short description: Device. (line 88)
-* multi-volume, summary: Option Summary. (line 377)
-* new-volume-script: Multi-Volume Archives.
- (line 80)
-* new-volume-script, short description: Device. (line 104)
-* new-volume-script, summary: Option Summary. (line 319)
-* newer: after. (line 26)
-* newer, summary: Option Summary. (line 385)
-* newer-mtime: after. (line 37)
-* newer-mtime, summary: Option Summary. (line 393)
-* no-anchored: controlling pattern-matching.
- (line 79)
-* no-anchored, summary: Option Summary. (line 398)
-* no-check-device, described: Incremental Dumps. (line 95)
-* no-check-device, summary: Option Summary. (line 402)
-* no-delay-directory-restore: Directory Modification Times and Permissions.
- (line 68)
-* no-delay-directory-restore, summary: Option Summary. (line 407)
-* no-ignore-case: controlling pattern-matching.
- (line 86)
-* no-ignore-case, summary: Option Summary. (line 413)
-* no-ignore-command-error: Writing to an External Program.
- (line 87)
-* no-ignore-command-error, summary: Option Summary. (line 416)
-* no-overwrite-dir, summary: Option Summary. (line 420)
-* no-quote-chars, summary: Option Summary. (line 424)
-* no-recursion: recurse. (line 13)
-* no-recursion, summary: Option Summary. (line 429)
-* no-same-owner: Attributes. (line 67)
-* no-same-owner, summary: Option Summary. (line 433)
-* no-same-permissions, summary: Option Summary. (line 439)
-* no-unquote: Selecting Archive Members.
- (line 42)
-* no-unquote, summary: Option Summary. (line 444)
-* no-wildcards: controlling pattern-matching.
- (line 41)
-* no-wildcards, summary: Option Summary. (line 448)
-* no-wildcards-match-slash: controlling pattern-matching.
- (line 92)
-* no-wildcards-match-slash, summary: Option Summary. (line 451)
-* null: nul. (line 11)
-* null, summary: Option Summary. (line 454)
-* numeric-owner: Attributes. (line 73)
-* numeric-owner, summary: Option Summary. (line 460)
-* occurrence, summary: Option Summary. (line 477)
-* old-archive, summary: Option Summary. (line 491)
-* one-file-system: one. (line 16)
-* one-file-system, summary: Option Summary. (line 494)
-* overwrite: Overwrite Old Files. (line 6)
-* overwrite, introduced: Dealing with Old Files.
- (line 22)
-* overwrite, summary: Option Summary. (line 499)
-* overwrite-dir: Overwrite Old Files. (line 28)
-* overwrite-dir, introduced: Dealing with Old Files.
- (line 6)
-* overwrite-dir, summary: Option Summary. (line 503)
-* owner: override. (line 57)
-* owner, summary: Option Summary. (line 507)
-* pax-option: PAX keywords. (line 6)
-* pax-option, summary: Option Summary. (line 516)
-* portability, summary: Option Summary. (line 522)
-* posix, summary: Option Summary. (line 526)
-* preserve: Attributes. (line 126)
-* preserve, summary: Option Summary. (line 529)
-* preserve-order: Same Order. (line 6)
-* preserve-order, summary: Option Summary. (line 533)
-* preserve-permissions: Setting Access Permissions.
- (line 10)
-* preserve-permissions, short description: Attributes. (line 113)
-* preserve-permissions, summary: Option Summary. (line 536)
-* quote-chars, summary: Option Summary. (line 546)
-* quoting-style: quoting styles. (line 39)
-* quoting-style, summary: Option Summary. (line 550)
-* read-full-records <1>: read full records. (line 6)
-* read-full-records: Reading. (line 8)
-* read-full-records, short description: Blocking Factor. (line 172)
-* read-full-records, summary: Option Summary. (line 557)
-* record-size, summary: Option Summary. (line 562)
-* recursion: recurse. (line 24)
-* recursion, summary: Option Summary. (line 566)
-* recursive-unlink: Recursive Unlink. (line 6)
-* recursive-unlink, summary: Option Summary. (line 570)
-* remove-files: remove files. (line 6)
-* remove-files, summary: Option Summary. (line 575)
-* restrict, summary: Option Summary. (line 579)
-* rmt-command, summary: Option Summary. (line 584)
-* rsh-command: Device. (line 73)
-* rsh-command, summary: Option Summary. (line 588)
-* same-order: Same Order. (line 6)
-* same-order, summary: Option Summary. (line 592)
-* same-owner: Attributes. (line 48)
-* same-owner, summary: Option Summary. (line 600)
-* same-permissions: Setting Access Permissions.
- (line 10)
-* same-permissions, short description: Attributes. (line 113)
-* same-permissions, summary: Option Summary. (line 536)
-* seek, summary: Option Summary. (line 609)
-* show-defaults: defaults. (line 6)
-* show-defaults, summary: Option Summary. (line 616)
-* show-omitted-dirs: verbose. (line 107)
-* show-omitted-dirs, summary: Option Summary. (line 625)
-* show-stored-names: list. (line 60)
-* show-stored-names, summary: Option Summary. (line 629)
-* show-transformed-names: transform. (line 45)
-* show-transformed-names, summary: Option Summary. (line 629)
-* sparse: sparse. (line 22)
-* sparse, summary: Option Summary. (line 637)
-* sparse-version: sparse. (line 57)
-* sparse-version, summary: Option Summary. (line 642)
-* starting-file: Starting File. (line 6)
-* starting-file, summary: Option Summary. (line 647)
-* strip-components: transform. (line 25)
-* strip-components, summary: Option Summary. (line 653)
-* suffix: backup. (line 68)
-* suffix, summary: Option Summary. (line 662)
-* tape-length: Multi-Volume Archives.
- (line 33)
-* tape-length, short description: Device. (line 96)
-* tape-length, summary: Option Summary. (line 668)
-* test-label: label. (line 37)
-* test-label, summary: Option Summary. (line 673)
-* to-command: Writing to an External Program.
- (line 9)
-* to-command, summary: Option Summary. (line 677)
-* to-stdout: Writing to Standard Output.
- (line 14)
-* to-stdout, summary: Option Summary. (line 681)
-* totals: verbose. (line 46)
-* totals, summary: Option Summary. (line 686)
-* touch <1>: Attributes. (line 37)
-* touch: Data Modification Times.
- (line 15)
-* touch, summary: Option Summary. (line 691)
-* transform: transform. (line 74)
-* transform, summary: Option Summary. (line 697)
-* uncompress: gzip. (line 129)
-* uncompress, summary: Option Summary. (line 151)
-* ungzip: gzip. (line 88)
-* ungzip, summary: Option Summary. (line 273)
-* unlink-first: Unlink First. (line 6)
-* unlink-first, introduced: Dealing with Old Files.
- (line 42)
-* unlink-first, summary: Option Summary. (line 716)
-* unquote: Selecting Archive Members.
- (line 39)
-* unquote, summary: Option Summary. (line 722)
-* update: update. (line 8)
-* update, summary: Operation Summary. (line 50)
-* usage: help. (line 53)
-* use-compress-program: gzip. (line 134)
-* use-compress-program, summary: Option Summary. (line 726)
-* utc, summary: Option Summary. (line 730)
-* verbose: verbose. (line 18)
-* verbose, introduced: verbose tutorial. (line 6)
-* verbose, summary: Option Summary. (line 734)
-* verbose, using with --create: create verbose. (line 6)
-* verbose, using with --list: list. (line 30)
-* verify, short description: verify. (line 8)
-* verify, summary: Option Summary. (line 741)
-* verify, using with --create: verify. (line 24)
-* version: help. (line 6)
-* version, summary: Option Summary. (line 746)
-* volno-file: Multi-Volume Archives.
- (line 71)
-* volno-file, summary: Option Summary. (line 751)
-* wildcards: controlling pattern-matching.
- (line 38)
-* wildcards, summary: Option Summary. (line 756)
-* wildcards-match-slash: controlling pattern-matching.
- (line 92)
-* wildcards-match-slash, summary: Option Summary. (line 760)
-
-\1f
-File: tar.info, Node: Index, Prev: Index of Command Line Options, Up: Top
-
-Appendix I Index
-****************
-
-\0\b[index\0\b]
-* Menu:
-
-* abbreviations for months: Calendar date items. (line 38)
-* absolute file names: Remote Tape Server. (line 17)
-* Adding archives to an archive: concatenate. (line 6)
-* Adding files to an Archive: appending files. (line 8)
-* ADMINISTRATOR: General-Purpose Variables.
- (line 7)
-* Age, excluding files by: after. (line 8)
-* ago in date strings: Relative items in date strings.
- (line 23)
-* am in date strings: Time of day items. (line 22)
-* Appending files to an Archive: appending files. (line 8)
-* archive: Definitions. (line 6)
-* Archive creation: file. (line 36)
-* archive member: Definitions. (line 15)
-* Archive Name: file. (line 8)
-* Archive, creation of: create. (line 8)
-* Archives, Appending files to: appending files. (line 8)
-* Archiving Directories: create dir. (line 6)
-* archiving files: Top. (line 24)
-* ARGP_HELP_FMT, environment variable: Configuring Help Summary.
- (line 22)
-* authors of get_date: Authors of get_date. (line 6)
-* Avoiding recursion in directories: recurse. (line 8)
-* backup options: backup. (line 6)
-* backup suffix: backup. (line 68)
-* BACKUP_DIRS: General-Purpose Variables.
- (line 29)
-* BACKUP_FILES: General-Purpose Variables.
- (line 55)
-* BACKUP_HOUR: General-Purpose Variables.
- (line 11)
-* backups: backup. (line 41)
-* beginning of time, for POSIX: Seconds since the Epoch.
- (line 13)
-* bell, checkpoint action: checkpoints. (line 65)
-* Bellovin, Steven M.: Authors of get_date. (line 6)
-* Berets, Jim: Authors of get_date. (line 6)
-* Berry, K.: Authors of get_date. (line 14)
-* Block number where error occurred: verbose. (line 115)
-* BLOCKING: General-Purpose Variables.
- (line 25)
-* blocking factor: Blocking Factor. (line 194)
-* Blocking Factor: Blocking Factor. (line 6)
-* Blocks per record: Blocking Factor. (line 6)
-* bug reports: Reports. (line 6)
-* Bytes per record: Blocking Factor. (line 6)
-* calendar date item: Calendar date items. (line 6)
-* case, ignored in dates: General date syntax. (line 64)
-* 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 8)
-* comments, in dates: General date syntax. (line 64)
-* Compressed archives: gzip. (line 6)
-* concatenate vs cat: concatenate. (line 63)
-* Concatenating Archives: concatenate. (line 6)
-* corrupted archives <1>: gzip. (line 107)
-* corrupted archives: Full Dumps. (line 8)
-* Creation of the archive: create. (line 8)
-* CVS, excluding files: exclude. (line 39)
-* DAT blocking: Blocking Factor. (line 204)
-* Data Modification time, excluding files by: after. (line 8)
-* Data modification times of extracted files: Data Modification Times.
- (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 of week item: Day of week items. (line 6)
-* Deleting files from an archive: delete. (line 8)
-* Deleting from tape archives: delete. (line 19)
-* dereferencing hard links: hard links. (line 8)
-* Descending directories, avoiding: recurse. (line 8)
-* Device numbers, changing: Fixing Snapshot Files.
- (line 6)
-* Device numbers, using in incremental backups: Incremental Dumps.
- (line 81)
-* Directories, Archiving: create dir. (line 6)
-* Directories, avoiding recursion: recurse. (line 8)
-* Directory, changing mid-stream: directory. (line 6)
-* DIRLIST: General-Purpose Variables.
- (line 51)
-* displacement of dates: Relative items in date strings.
- (line 6)
-* doc-opt-col: Configuring Help Summary.
- (line 95)
-* dot, checkpoint action: checkpoints. (line 80)
-* Double-checking a write operation: verify. (line 6)
-* DUMP_BEGIN: User Hooks. (line 32)
-* DUMP_END: User Hooks. (line 36)
-* DUMP_REMIND_SCRIPT: General-Purpose Variables.
- (line 102)
-* dumps, full: Full Dumps. (line 8)
-* 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 get_date. (line 6)
-* End-of-archive blocks, ignoring: Ignore Zeros. (line 6)
-* End-of-archive info script: Multi-Volume Archives.
- (line 80)
-* entry: Naming tar Archives. (line 11)
-* epoch, for POSIX: Seconds since the Epoch.
- (line 13)
-* Error message, block number of: verbose. (line 125)
-* Exabyte blocking: Blocking Factor. (line 204)
-* exclude: exclude. (line 14)
-* exclude-caches: exclude. (line 68)
-* exclude-from: exclude. (line 27)
-* exclude-tag: exclude. (line 91)
-* Excluding characters from a character class: wildcards. (line 34)
-* Excluding file by age: after. (line 8)
-* Excluding files by file system: exclude. (line 8)
-* Excluding files by name and pattern: exclude. (line 8)
-* Exec Mode, genfile: Exec Mode. (line 6)
-* exec, checkpoint action: checkpoints. (line 96)
-* existing backup method: backup. (line 59)
-* exit status: Synopsis. (line 67)
-* Extraction: extract. (line 8)
-* extraction: Definitions. (line 22)
-* FDL, GNU Free Documentation License: GNU Free Documentation License.
- (line 6)
-* file archival: Top. (line 24)
-* 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 68)
-* File names, excluding files by: exclude. (line 8)
-* File names, terminated by NUL: nul. (line 6)
-* File names, using hard links: hard links. (line 8)
-* File names, using symbolic links: dereference. (line 6)
-* File system boundaries, not crossing: one. (line 6)
-* FILELIST: General-Purpose Variables.
- (line 65)
-* first in date strings: General date syntax. (line 26)
-* format 0, snapshot file: Snapshot Files. (line 23)
-* format 1, snapshot file: Snapshot Files. (line 47)
-* format 2, snapshot file: Snapshot Files. (line 69)
-* 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)
-* get_date: Date input formats. (line 6)
-* Getting program version number: help. (line 6)
-* git, excluding files: exclude. (line 39)
-* 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 60)
-* GNU.sparse.minor, extended header variable: PAX 1. (line 17)
-* GNU.sparse.name, extended header variable: PAX 0. (line 68)
-* GNU.sparse.name, extended header variable, in v.1.0: PAX 1. (line 24)
-* GNU.sparse.numblocks, extended header variable: PAX 0. (line 15)
-* GNU.sparse.numbytes, extended header variable: PAX 0. (line 21)
-* GNU.sparse.offset, extended header variable: PAX 0. (line 18)
-* GNU.sparse.realsize, extended header variable: PAX 1. (line 24)
-* GNU.sparse.size, extended header variable: PAX 0. (line 11)
-* gnupg, using with tar: gzip. (line 146)
-* gpg, using with tar: gzip. (line 146)
-* hard links, dereferencing: hard links. (line 8)
-* header-col: Configuring Help Summary.
- (line 141)
-* hook: User Hooks. (line 13)
-* hour in date strings: Relative items in date strings.
- (line 15)
-* Ignoring end-of-archive blocks: Ignore Zeros. (line 6)
-* Info script: Multi-Volume Archives.
- (line 80)
-* Interactive operation: interactive. (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 multi-volume archives: label. (line 6)
-* Labels on the archive media: label. (line 6)
-* language, in dates: 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 26)
-* Listing all tar options: help. (line 26)
-* listing member and file names: list. (line 41)
-* Listing volume label: label. (line 29)
-* Lists of file names: files. (line 6)
-* Local and remote archives: file. (line 73)
-* long-opt-col: Configuring Help Summary.
- (line 87)
-* MacKenzie, David: Authors of get_date. (line 6)
-* member: Definitions. (line 15)
-* member name: Definitions. (line 15)
-* Members, replacing with other members: append. (line 49)
-* Meyering, Jim: Authors of get_date. (line 6)
-* Middle of the archive, starting in the: Starting File. (line 11)
-* midnight in date strings: Time of day items. (line 22)
-* minute in date strings: Relative items in date strings.
- (line 15)
-* minutes, time zone correction by: Time of day items. (line 30)
-* Modes of extracted files: Setting Access Permissions.
- (line 6)
-* Modification time, excluding files by: after. (line 8)
-* 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 36)
-* MT: General-Purpose Variables.
- (line 69)
-* MT_BEGIN: Magnetic Tape Control.
- (line 11)
-* MT_OFFLINE: Magnetic Tape Control.
- (line 32)
-* MT_REWIND: Magnetic Tape Control.
- (line 21)
-* MT_STATUS: Magnetic Tape Control.
- (line 42)
-* Multi-volume archives: Multi-Volume Archives.
- (line 6)
-* Mutli-volume archives in PAX format, extracting using non-GNU tars: Split Recovery.
- (line 17)
-* Mutli-volume archives, extracting using non-GNU tars: Split Recovery.
- (line 6)
-* Naming an archive: file. (line 8)
-* negative time stamps: Large or Negative Values.
- (line 6)
-* next DAY: Day of week items. (line 15)
-* next in date strings: General date syntax. (line 26)
-* noon in date strings: Time of day items. (line 22)
-* 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 26)
-* Obtaining help: help. (line 26)
-* Obtaining total status information: verbose. (line 46)
-* Old GNU archive format: gnu. (line 6)
-* Old GNU sparse format: Old GNU Format. (line 6)
-* 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 60)
-* Options when reading archives: Reading. (line 6)
-* Options, archive format specifying: Format Variations. (line 6)
-* Options, format specifying: Format Variations. (line 6)
-* ordinal numbers: General date syntax. (line 26)
-* Overwriting old files, prevention: Dealing with Old Files.
- (line 16)
-* 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 get_date. (line 14)
-* pm in date strings: Time of day items. (line 22)
-* POSIX archive format: posix. (line 6)
-* Progress information: verbose. (line 83)
-* Protecting old files: Dealing with Old Files.
- (line 26)
-* pure numbers in date strings: Pure numbers in date strings.
- (line 6)
-* RCS, excluding files: exclude. (line 39)
-* Reading file names from a file: files. (line 6)
-* Reading incomplete records: Reading. (line 8)
-* Record Size: Blocking Factor. (line 6)
-* Records, incomplete: Reading. (line 8)
-* Recursion in directories, avoiding: recurse. (line 8)
-* relative items in date strings: Relative items in date strings.
- (line 6)
-* Remote devices: file. (line 62)
-* remote tape drive: Remote Tape Server. (line 6)
-* Removing files from an archive: delete. (line 8)
-* Replacing members with other members: append. (line 49)
-* reporting bugs: Reports. (line 6)
-* RESTORE_BEGIN: User Hooks. (line 39)
-* RESTORE_END: User Hooks. (line 42)
-* Resurrecting files from an archive: extract. (line 8)
-* Retrieving files from an archive: extract. (line 8)
-* return status: Synopsis. (line 67)
-* rmargin: Configuring Help Summary.
- (line 160)
-* rmt: Remote Tape Server. (line 6)
-* RSH: General-Purpose Variables.
- (line 72)
-* RSH_COMMAND: General-Purpose Variables.
- (line 77)
-* Running out of space: Scarce. (line 8)
-* Salz, Rich: Authors of get_date. (line 6)
-* SCCS, excluding files: exclude. (line 39)
-* short-opt-col: Configuring Help Summary.
- (line 79)
-* simple backup method: backup. (line 64)
-* SIMPLE_BACKUP_SUFFIX: backup. (line 68)
-* sleep, checkpoint action: checkpoints. (line 90)
-* SLEEP_MESSAGE: General-Purpose Variables.
- (line 111)
-* SLEEP_TIME: General-Purpose Variables.
- (line 97)
-* Small memory: Scarce. (line 8)
-* snapshot file, format 0: Snapshot Files. (line 23)
-* snapshot file, format 1: Snapshot Files. (line 47)
-* snapshot file, format 2: Snapshot Files. (line 69)
-* snapshot files, editing: Fixing Snapshot Files.
- (line 6)
-* snapshot files, fixing device numbers: Fixing Snapshot Files.
- (line 6)
-* 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 50)
-* 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 52)
-* 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 41)
-* 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 39)
-* Symbolic link as file name: dereference. (line 6)
-* TAPE: file tutorial. (line 14)
-* tape blocking: Blocking Factor. (line 194)
-* tape marks: Many. (line 44)
-* tape positioning: Many. (line 26)
-* TAPE_FILE: General-Purpose Variables.
- (line 19)
-* Tapes, using --delete and: delete. (line 19)
-* TAR: General-Purpose Variables.
- (line 115)
-* tar: What tar Does. (line 6)
-* 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 62)
-* tar to standard input and output: file. (line 41)
-* tar-snapshot-edit: Fixing Snapshot Files.
- (line 15)
-* TAR_ARCHIVE, checkpoint script environment: checkpoints. (line 108)
-* TAR_ARCHIVE, info script environment variable: Multi-Volume Archives.
- (line 100)
-* TAR_ATIME, to-command environment: Writing to an External Program.
- (line 49)
-* TAR_BLOCKING_FACTOR, checkpoint script environment: checkpoints.
- (line 111)
-* TAR_BLOCKING_FACTOR, info script environment variable: Multi-Volume Archives.
- (line 103)
-* TAR_CHECKPOINT, checkpoint script environment: checkpoints. (line 114)
-* TAR_CTIME, to-command environment: Writing to an External Program.
- (line 58)
-* TAR_FD, info script environment variable: Multi-Volume Archives.
- (line 117)
-* TAR_FILENAME, to-command environment: Writing to an External Program.
- (line 37)
-* TAR_FILETYPE, to-command environment: Writing to an External Program.
- (line 22)
-* TAR_FORMAT, checkpoint script environment: checkpoints. (line 121)
-* TAR_FORMAT, info script environment variable: Multi-Volume Archives.
- (line 113)
-* TAR_GID, to-command environment: Writing to an External Program.
- (line 67)
-* TAR_GNAME, to-command environment: Writing to an External Program.
- (line 46)
-* TAR_MODE, to-command environment: Writing to an External Program.
- (line 34)
-* TAR_MTIME, to-command environment: Writing to an External Program.
- (line 55)
-* TAR_OPTIONS, environment variable: using tar options. (line 30)
-* TAR_REALNAME, to-command environment: Writing to an External Program.
- (line 40)
-* TAR_SIZE, to-command environment: Writing to an External Program.
- (line 61)
-* TAR_SUBCOMMAND, checkpoint script environment: checkpoints. (line 117)
-* TAR_SUBCOMMAND, info script environment variable: Multi-Volume Archives.
- (line 109)
-* TAR_UID, to-command environment: Writing to an External Program.
- (line 64)
-* TAR_UNAME, to-command environment: Writing to an External Program.
- (line 43)
-* TAR_VERSION, checkpoint script environment: checkpoints. (line 105)
-* TAR_VERSION, info script environment variable: Multi-Volume Archives.
- (line 97)
-* TAR_VOLUME, info script environment variable: Multi-Volume Archives.
- (line 106)
-* tarcat: Tarcat. (line 6)
-* this in date strings: Relative items in date strings.
- (line 33)
-* time of day item: Time of day items. (line 6)
-* time zone correction: Time of day items. (line 30)
-* time zone item <1>: Time zone items. (line 6)
-* time zone item: General date syntax. (line 44)
-* today in date strings: Relative items in date strings.
- (line 33)
-* tomorrow in date strings: Relative items in date strings.
- (line 29)
-* ttyout, checkpoint action: checkpoints. (line 70)
-* TZ: Specifying time zone rules.
- (line 6)
-* Ultrix 3.1 and write failure: Remote Tape Server. (line 40)
-* unpacking: Definitions. (line 22)
-* Updating an archive: update. (line 8)
-* usage-indent: Configuring Help Summary.
- (line 156)
-* Using encrypted archives: gzip. (line 146)
-* ustar archive format: ustar. (line 6)
-* uuencode: Applications. (line 8)
-* v7 archive format: old. (line 6)
-* VCS, excluding files: exclude. (line 39)
-* 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 39)
-* 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 71)
-* VOLNO_FILE: General-Purpose Variables.
- (line 82)
-* Volume label, listing: label. (line 29)
-* Volume number file: Multi-Volume Archives.
- (line 71)
-* week in date strings: Relative items in date strings.
- (line 15)
-* Where is the archive?: file. (line 8)
-* Working directory, specifying: directory. (line 6)
-* Writing extracted files to standard output: Writing to Standard Output.
- (line 6)
-* Writing new archives: file. (line 36)
-* XLIST: General-Purpose Variables.
- (line 87)
-* 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)
-
-
+++ /dev/null
-\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
-
-@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
-
-@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, 1995, 1996, 1997, 1999, 2000, 2001,
-2003, 2004, 2005, 2006, 2007, 2008 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.1 or
-any later version published by the Free Software Foundation; with no
-Invariant Sections, 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. Buying copies from the FSF
-supports it in developing GNU and promoting software freedom.''
-@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::
-
-Appendices
-
-* Changes::
-* Configuring Help Summary::
-* Fixing Snapshot Files::
-* Tar Internals::
-* Genfile::
-* Free Software Needs Free Documentation::
-* Copying This Manual::
-* 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::
-* 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::
-
-@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.
-* 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 get_date:: 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
-
-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 the 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
-@UNREVISED
-
-@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}. You could also say:
-
-@smallexample
-$ @kbd{tar blues --create folk --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 lines
-@iftex
-(note the different font styles).
-@end iftex
-@ifinfo
-.
-@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 blues --create folk --file=collection.tar jazz}
-@end smallexample
-
-@noindent
-is confusing as it is. When shown using short forms, however, it
-becomes much more so:
-
-@smallexample
-$ @kbd{tar blues -c folk -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, 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
-The archive @file{bfiles.tar} would list as follows:
-
-@smallexample
-./birds
-baboon
-./box
-@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.
-
-@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:
-
-@smallexample
-@group
-$ @kbd{tar cfv archive /etc/mail}
-tar: Removing leading `/' from member names
-/etc/mail/
-/etc/mail/sendmail.cf
-/etc/mail/aliases
-$ @kbd{tar tf archive}
-etc/mail/
-etc/mail/sendmail.cf
-etc/mail/aliases
-@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
-
-@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=afiles.tar apple}} would only print @file{apple}.
-
-Because @command{tar} preserves file names, these must be specified as
-they appear in the archive (i.e., relative to the directory from which
-the archive was created). Therefore, it is essential when specifying
-member names to @command{tar} that you give the exact member names.
-For example, @w{@kbd{tar --list --file=bfiles.tar birds}} would produce an
-error message something like @samp{tar: birds: Not found in archive},
-because there is no member named @file{birds}, only one named
-@file{./birds}. While the names @file{birds} and @file{./birds} name
-the same file, @emph{member} names by default are compared verbatim.
-
-However, @w{@kbd{tar --list --file=bfiles.tar baboon}} would respond
-with @file{baboon}, because this exact member name is in the archive file
-@file{bfiles.tar}. If you are not sure of the exact file name,
-use @dfn{globbing patterns}, for example:
-
-@smallexample
-$ @kbd{tar --list --file=bfiles.tar --wildcards '*b*'}
-@end smallexample
-
-@noindent
-will list all members whose name contains @samp{b}. @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
-@UNREVISED
-@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-- 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
-@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. @w{@kbd{tar --extract --file=bfiles.tar birds}}
-will fail, because there is no member named @file{birds}. To extract
-the member named @file{./birds}, you must specify @w{@kbd{tar
---extract --file=bfiles.tar ./birds}}. If you don't remember the
-exact member names, use @option{--list} (@option{-t}) option
-(@pxref{list}). You can also extract those members that match a
-specific @dfn{globbing pattern}. For example, to extract from
-@file{bfiles.tar} all files that begin with @samp{b}, no matter their
-directory prefix, you could type:
-
-@smallexample
-$ @kbd{tar -x -f bfiles.tar --wildcards --no-anchored 'b*'}
-@end smallexample
-
-@noindent
-Here, @option{--wildcards} instructs @command{tar} to treat
-command line arguments as globbing patterns and @option{--no-anchored}
-informs it that the patterns apply to member names after any @samp{/}
-delimiter. The use of globbing patterns is discussed in detail in
-@xref{wildcards}.
-
-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/folk
-practice/jazz
-practice/rock
-@end smallexample
-
-@FIXME{make sure the above works when going through the examples in
-order...}
-
-@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.
-
-@FIXME{more examples, here? hag thinks it's a good idea.}
-
-@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{}
-@UNREVISED
-
-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::
-* help::
-* defaults::
-* verbose::
-* checkpoints::
-* interactive::
-@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.
-
-@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 is improperly written. Errors may be
-encountered later, while encountering an error 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 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 (two lists of four operations each 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. (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
-
-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}.
-
-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}.
-
-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
-
-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.
-
-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}.
-
-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
-@UNREVISED
-
-Like short options, @dfn{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@footnote{Beware that if you precede options
-with a dash, you are announcing the short option style instead of the
-old option style; short options are decoded differently.}. 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}.
-
-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}.
-
-On the other hand, this old style syntax makes 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.
-
-Old options are kept for compatibility with old versions of @command{tar}.
-
-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
-
-@cindex option syntax, traditional
-As far as we know, all @command{tar} programs, @acronym{GNU} and
-non-@acronym{GNU}, support old options. @GNUTAR{}
-supports them not only for historical reasons, but also because many
-people are used to them. For compatibility with Unix @command{tar},
-the first argument is always treated as containing command and option
-letters even if it doesn't start with @samp{-}. Thus, @samp{tar c} is
-equivalent to @w{@samp{tar -c}:} both of them specify the
-@option{--create} (@option{-c}) command to create an archive.
-
-@node Mixing
-@subsection Mixing Option 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::
-@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 a 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. This option disables that behavior.
-@xref{absolute}.
-
-@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. (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 system does not support
-@option{--atime-preserve=@-system}, you might be able to preserve access
-times reliably by 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. @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{--checklist-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{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 creating a @command{tar} archive, @command{tar} will archive the
-file that a symbolic link points to, rather than archiving the
-symlink. @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-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}.
-
-@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-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}.
-
-@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}.
-
-@opsummary{exclude-tag-all}
-@item --exclude-tag-all=@var{file}
-
-Exclude from dump any directory containing file named @var{file}.
-@xref{exclude}.
-
-@opsummary{exclude-vcs}
-@item --exclude-vcs
-
-Exclude from dump directories and files, that are internal for some
-widely used version control systems.
-
-@xref{exclude}.
-
-@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{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} is first decoded
-as a group symbolic name, but if this interpretation fails, it has to be
-a decimal numeric group @acronym{ID}. @xref{override}.
-
-Also see the comments for the @option{--owner=@var{user}} option.
-
-@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{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{Reading}.
-
-@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{script-file}
-@itemx --new-volume-script=@var{script-file}
-@itemx -F @var{script-file}
-
-When @command{tar} is performing multi-tape backups, @var{script-file} is run
-at the end of each tape. If @var{script-file} exits with nonzero status,
-@command{tar} fails immediately. @xref{info-script}, for a detailed
-discussion of @var{script-file}.
-
-@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-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.
-@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{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{lzma}
-@item --lzma
-
-This option tells @command{tar} to read or write archives through
-@command{lzma}. @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}.
-
-@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 --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-anchored}
-@item --no-anchored
-An exclude pattern can match any subsequence of the name's components.
-@xref{controlling pattern-matching}.
-
-@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-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-unquote}
-@item --no-unquote
-Treat all input file or member names literally, do not interpret
-escape sequences. @xref{input name quoting}.
-
-@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{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}, so
-@command{tar} can correctly work with file names that contain newlines.
-@xref{nul}.
-
-@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{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} is first decoded as a user symbolic name, but if
-this interpretation fails, it has to be a decimal numeric user @acronym{ID}.
-@xref{override}.
-
-This option does not affect extraction from archives.
-
-@opsummary{pax-option}
-@item --pax-option=@var{keyword-list}
-This option is meaningful only with @acronym{POSIX.1-2001} archives
-(@pxref{posix}). It 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}
-@item --preserve
-
-Synonymous with specifying both @option{--preserve-permissions} and
-@option{--same-order}. @xref{Setting Access Permissions}.
-
-@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}
-
-Instructs @command{tar} to use @var{size} bytes per record when accessing the
-archive. @xref{Blocking Factor}.
-
-@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.
-
-@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
-$ tar --show-defaults
---format=gnu -f- -b20 --quoting-style=escape \
---rmt-command=/usr/libexec/rmt --rsh-command=/usr/bin/rsh
-@end smallexample
-
-@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-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{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}.
-
-@opsummary{suffix}, summary
-@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}
-@itemx -L @var{num}
-
-Specifies the length of tapes that @command{tar} is writing as being
-@w{@var{num} x 1024} bytes long. @xref{Using Multiple Tapes}.
-
-@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}
-@item --transform=@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}
-
-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{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{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}.
-@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 -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 later 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 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) 2008 Free Software Foundation, Inc.
-This is free software. You may redistribute copies of it under the terms
-of the GNU General Public License <http://www.gnu.org/licenses/gpl.html>.
-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} option 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 cfv -}, 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 if 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{meta-characters}. The @samp{%s} meta-character 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} meta-character 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
-
-Aside from meta-character 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=\rHit %s checkpoint #%u"
-@end smallexample
-
-@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{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
-
-@cindex @code{exec}, checkpoint action
-Finally, the @code{exec} action executes a given external program.
-For example:
-
-@smallexample
-$ @kbd{tar -c --checkpoint=1000 --checkpoint-action=exec=/sbin/cpoint}
-@end smallexample
-
-This program is executed using @command{/bin/sh -c}, with no
-additional arguments. Its exit code is ignored. It 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
-The checkpoint number.
-
-@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
-
-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 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 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 cfT empty-archive.tar /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
-@UNREVISED
-
-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},
-@samp{rock}, 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 -r
-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}
-@UNREVISED
-
-@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 four
-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} option, or the disk copy is newer than the
-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.
-
-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. (maybe xref Multiple Members
-with the Same Name.}
-
-@cindex Members, replacing with other members
-@cindex Replacing members with other members
-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
-@UNREVISED
-@cindex Adding files to an Archive
-@cindex Appending files to an Archive
-@cindex Archives, Appending files to
-
-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
-
-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
-@xref{Option Summary, --occurrence}, for the description of
-@option{--occurrence} option.
-
-@node update
-@subsection Updating an Archive
-@UNREVISED
-@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}
-
-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 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, @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}
-@UNREVISED
-@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
-@UNREVISED
-
-@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 later goal, @xref{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.
-* 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 the 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 UTC,
-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
-
-@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. The argument @var{user} can be either an existing user symbolic
-name, or a decimal numeric user @acronym{ID}.
-
-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
-@group
-$ @kbd{tar -c -f archive.tar --owner=0 .}
-# @r{Or:}
-$ @kbd{tar -c -f archive.tar --owner=root .}
-@end group
-@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. The argument @var{group}
-can be either an existing group symbolic name, or a decimal numeric group @acronym{ID}.
-@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}
-@UNREVISED
-
-@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
-@UNREVISED
-
-@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.
-
-@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
-
-@table @option
-@opindex keep-old-files
-@item --keep-old-files
-@itemx -k
-Do not replace existing files from archive. The
-@option{--keep-old-files} (@option{-k}) option prevents @command{tar}
-from replacing existing files with files with the same name from the
-archive. The @option{--keep-old-files} option is meaningless with
-@option{--list} (@option{-t}). Prevents @command{tar} from replacing
-files in the file system during extraction.
-@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
-@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. @var{Command} may
-contain command line arguments. The program is executed via
-@code{sh -c}. 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
-
-In addition to these variables, @env{TAR_VERSION} contains the
-@GNUTAR{} version number.
-
-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 restart the same @command{tar} operation.
-In this case, @option{--starting-file} is not necessary.
-@xref{Incremental Dumps}, @xref{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
-has having similar names through the side-effect of name truncation.
-(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}, which is one a Unix redirection mechanism:
-
-@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 short option forms:
-
-@smallexample
-$ @kbd{(cd sourcedir; tar --create --file=- . ) \
- | (cd targetdir; tar --extract --file=-)}
-# Or:
-$ @kbd{tar --directory sourcedir --create --file=- . ) \
- | tar --directory targetdir --extract --file=-}
-@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
-@UNREVISED
-
-@GNUTAR{} is distributed along with the scripts
-which the Free Software Foundation uses for performing backups. There
-is no corresponding scripts available yet for doing restoration of
-files. 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 at these places:
-
-@smallexample
-http://www.cs.umd.edu/projects/amanda/amanda.html
-ftp://ftp.cs.umd.edu/pub/amanda
-@end smallexample
-
-@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}).
-
-@opindex listed-incremental
-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
-
-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 a 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 considers 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 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 file systems 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} 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}
-@UNREVISED
-
-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
-@UNREVISED
-
-@cindex Naming an archive
-@cindex Archive Name
-@cindex Choosing an archive file
-@cindex Where is the archive?
-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 complete 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 complete the remote connection, if possible, 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}, were @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
-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 can not 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
-In the file list given by @option{-T} option, any file name beginning
-with @samp{-} character 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
-
-@noindent
-@xopindex{directory, using in @option{--files-from} argument}
-Notice that the option parsing algorithm used with @option{-T} is
-stricter than the one used by shell. Namely, when specifying option
-arguments, you should observe the following rules:
-
-@itemize @bullet
-@item
-When using short (single-letter) option form, its argument must
-immediately follow the option letter, without any intervening
-whitespace. For example: @code{-Cdir}.
-
-@item
-When using long option form, the option argument must be separated
-from the option by a single equal sign. No whitespace is allowed on
-any side of the equal sign. For example: @code{--directory=dir}.
-
-@item
-For both short and long option forms, the option argument can be given
-on the next line after the option name, e.g.:
-
-@smallexample
-@group
---directory
-dir
-@end group
-@end smallexample
-
-@noindent
-and
-
-@smallexample
-@group
--C
-dir
-@end group
-@end smallexample
-@end itemize
-
-@opindex add-file
-If you happen to have a file whose name starts with @samp{-},
-precede it with @option{--add-file} option to prevent it from
-being recognized as an option. For example: @code{--add-file=--my-file}.
-
-@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
-@opindex null
-@item --null
-Only consider @code{NUL} terminated file names, instead of files that
-terminate in a newline.
-@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.
-
-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} get 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
-
-@FIXME{say anything else here to conclude the section?}
-
-@node exclude
-@section Excluding Some Files
-@UNREVISED
-
-@cindex File names, excluding files by
-@cindex Excluding files by name and pattern
-@cindex Excluding files by file system
-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 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
-@table @option
-@opindex exclude-vcs
-@item --exclude-vcs
-Exclude files and directories used by some version control systems.
-@end table
-
-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{.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}
-@end itemize
-
-@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
-@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.
-
-@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 @samp{'} 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 file to an archive, its file name is recorded in the archive
-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 two 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 to the above invocation @option{--verbose} (@option{-v})
-option, 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 is @file{stdlib.h} 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
-@item --transform=@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}.
-
-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 @var{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
-
-Any delimiter can be used in lieue 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/\//-/}.
-
-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 Prepend @file{/prefix/} to each file name:
-
-@smallexample
-$ @kbd{tar --transform 's,^,/prefix/,' -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
-
-@end enumerate
-
-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
-@UNREVISED
-
-@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.
-
-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
-@UNREVISED
-@cindex Avoiding recursion in directories
-@cindex Descending directories, avoiding
-@cindex Directories, avoiding recursion
-@cindex Recursion in directories, avoiding
-
-@FIXME{arrggh! this is still somewhat confusing to me. :-< }
-
-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
-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} 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}, or look.
-
-@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
-@UNREVISED
-
-@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{orange-colored}.
-
-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 @option{--directory} is disabled by
-@option{--null} option.
-
-@node absolute
-@subsection Absolute File Names
-@UNREVISED
-
-@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
-
-By default, @GNUTAR{} drops a leading @samp{/} on
-input or output, and complains about file names containing a @file{..}
-component. This option turns off this behavior.
-
-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.}
-
-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.}
-
-@FIXME{Is write access an issue?}
-
-@table @option
-@item --absolute-names
-Preserves full file names (including superior directory names) when
-archiving files. Preserves leading slash when extracting files.
-
-@end table
-
-@FIXME{this is still horrible; need to talk with dan on monday.}
-
-@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{(cd / && tar -c -f archive.tar home)}
-# @i{or}:
-$ @kbd{tar -c -f archive.tar -C / home}
-@end smallexample
-
-@include getdate.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
-
-@GNUTAR{} is able to create and read compressed archives. It supports
-@command{gzip}, @command{bzip2} and @command{lzma} compression
-programs. For backward compatibility, it also supports
-@command{compress} command, although we strongly recommend against
-using it, because it is by far less effective than 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{--lzma} to create an @asis{LZMA} compressed archive and
-@option{-Z} (@option{--compress}) to use @command{compress} program.
-For example:
-
-@smallexample
-$ @kbd{tar cfz archive.tar.gz .}
-@end smallexample
-
-You can also let @GNUTAR{} select the compression program basing 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 cfa archive.tar.bz2 .}
-@end smallexample
-
-@noindent
-whereas the following one will use @command{lzma}:
-
-@smallexample
-$ @kbd{tar cfa archive.tar.lzma .}
-@end smallexample
-
-For a complete list of file name suffixes recognized by @GNUTAR{},
-@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 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 tfz -}
-@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} (@option{-u}))
-them or delete (@option{--delete}) members from them or
-add (@option{--append} (@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 table summarizes compression options used by @GNUTAR{}.
-
-@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{.lzma} @tab @command{lzma}
-@item @samp{.tlz} @tab @command{lzma}
-@end multitable
-
-@opindex gzip
-@opindex ungzip
-@item -z
-@itemx --gzip
-@itemx --ungzip
-Filter the archive through @command{gzip}.
-
-You can use @option{--gzip} and @option{--gunzip} 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; if you need to
-override them, set @env{GZIP} environment variable, e.g.:
-
-@smallexample
-$ @kbd{GZIP=--best tar cfz archive.tar.gz subdir}
-@end smallexample
-
-@noindent
-Another way would be to avoid the @option{--gzip} (@option{--gunzip}, @option{--ungzip}, @option{-z}) option and run
-@command{gzip} explicitly:
-
-@smallexample
-$ @kbd{tar cf - subdir | gzip --best -c - > archive.tar.gz}
-@end smallexample
-
-@cindex corrupted archives
-About corrupted compressed archives: @command{gzip}'ed files have no
-redundancy, for maximum compression. 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.
-
-There are pending suggestions for having a per-volume or per-file
-compression in @GNUTAR{}. This would allow for viewing the
-contents without decompression, and for resynchronizing decompression at
-every volume or file, in case of corrupted archives. Doing so, we might
-lose some compressibility. But this would have make recovering easier.
-So, there are pros and cons. We'll see!
-
-@opindex bzip2
-@item -j
-@itemx --bzip2
-Filter the archive through @code{bzip2}. Otherwise like @option{--gzip}.
-
-@opindex lzma
-@item --lzma
-Filter the archive through @command{lzma}. Otherwise like @option{--gzip}.
-
-@opindex compress
-@opindex uncompress
-@item -Z
-@itemx --compress
-@itemx --uncompress
-Filter the archive through @command{compress}. Otherwise like @option{--gzip}.
-
-@opindex use-compress-program
-@item --use-compress-program=@var{prog}
-Use external compression program @var{prog}. Use this option if you
-have a compression program that @GNUTAR{} does not support. There
-are two requirements to which @var{prog} should comply:
-
-First, when called without options, it should read data from standard
-input, compress it and output it on standard output.
-
-Secondly, if called with @option{-d} argument, it should do exactly
-the opposite, i.e., read the compressed data from the standard input
-and produce uncompressed data on the standard output.
-@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 --use-compress=gpgz .}
-@end smallexample
-
-@noindent
-Likewise, the following command will list its contents:
-
-@smallexample
-$ @kbd{tar -tf foo.tar.gpgz --use-compress=gpgz .}
-@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
-
-@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 consecutive stretches of zeros. It then records
-in the archive for the file where the 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 holes created wherever the continuous stretches of zeros
-were found. Thus, if you use @option{--sparse}, @command{tar} archives
-won't take more space than the original.
-
-@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 presents a serious
-drawback. Namely, in order to determine if the file is sparse
-@command{tar} has to read it before trying to archive it, so in total
-the file is read @strong{twice}. So, always bear in mind that the
-time needed to process all files with this option is roughly twice
-the time needed to archive them without it.
-@FIXME{A technical note:
-
-Programs like @command{dump} do not have to read the entire file; by
-examining the file system directly, they can determine in advance
-exactly where the holes are and thus avoid reading through them. The
-only data it need read are the actual allocated data blocks.
-@GNUTAR{} uses a more portable and straightforward
-archiving approach, it would be fairly difficult that it does
-otherwise. Elizabeth Zwicky writes to @file{comp.unix.internals}, on
-1990-12-10:
-
-@quotation
-What I did say is that you cannot tell the difference between a hole and an
-equivalent number of nulls without reading raw blocks. @code{st_blocks} at
-best tells you how many holes there are; it doesn't tell you @emph{where}.
-Just as programs may, conceivably, care what @code{st_blocks} is (care
-to name one that does?), they may also care where the holes are (I have
-no examples of this one either, but it's equally imaginable).
-
-I conclude from this that good archivers are not portable. One can
-arguably conclude that if you want a portable program, you can in good
-conscience restore files with as many holes as possible, since you can't
-get it right.
-@end quotation
-}
-
-@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}.
-
-@node Attributes
-@section Handling File Attributes
-@UNREVISED
-
-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.
-
-Handling of file attributes
-
-@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{--old-archive} (@option{-o}) 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}).
-
-@opindex preserve
-@item --preserve
-Same as both @option{--same-permissions} and @option{--same-order}.
-
-The @option{--preserve} option has no equivalent short option name.
-It is equivalent to @option{--same-permissions} plus @option{--same-order}.
-
-@FIXME{I do not see the purpose of such an option. (Neither I. FP.)
-Neither do I. --Sergey}
-
-@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.
-@option{--dereference} (@option{-h}) is used with @option{--create} (@option{-c}), and causes
-@command{tar} to archive the files symbolic links point to, instead of
-the links themselves. When this option is used, when @command{tar}
-encounters a symbolic link, it will archive the linked-to file,
-instead of simply recording the presence of a symbolic link.
-
-The name under which the file is stored in the file system is not
-recorded in the archive. To record both the symbolic link name and
-the file name in the system, archive the file under both names. If
-all links were recorded automatically by @command{tar}, an extracted file
-might be linked to a file name that no longer exists in the file
-system.
-
-If a linked-to file is encountered again by @command{tar} while creating
-the same archive, an entire second copy of it will be stored. (This
-@emph{might} be considered a bug.)
-
-So, for portable archives, do not archive symbolic links as such,
-and use @option{--dereference} (@option{-h}): many systems do not support
-symbolic links, and moreover, your distribution might be unusable if
-it contains unresolved symbolic links.
-
-@node hard links
-@subsection Hard Links
-@UNREVISED{}
-@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
--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 cfvv ../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 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 absense 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
-Archive format defined by @acronym{POSIX}.1-1988 specification is called
-@code{ustar}. Although it is more flexible than the V7 format, it
-still has many restrictions (@xref{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 archive in @code{ustar} format, use @option{--format=ustar}
-option in conjunction with the @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 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 @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
-
-@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 eight 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
-accept any. 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{} compute checksums both ways, and accept
-any 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 that 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 Mutli-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 Mutli-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 preceeded 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 simething 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 inumbers (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 @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{num}
-Change tape after writing @var{num} x 1024 bytes.
-
-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{file}
-@itemx --info-script=@var{file}
-@itemx --new-volume-script=@var{file}
-Execute @file{file} 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 The 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. It is
-Copyright @copyright{} 1983 by the Regents of the University of
-California, but 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
-@UNREVISED
-
-@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. 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 loosing 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
-
-@FIXME{Is there a better way to frob the spacing on the list?}
-
-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 disk.
-
-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}
-@itemx -L @var{size}
-Set maximum length of a volume. The @var{size} argument should then
-be the usable size of the tape in units of 1024 bytes. This option
-selects @option{--multi-volume} automatically. For example:
-
-@smallexample
-$ @kbd{tar --create --tape-length=41943040 --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{script-name}
-@itemx --new-volume-script=@var{script-name}
-@itemx -F @var{script-name}
-Specify the full name of the volume script to use. The script 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{script-name} is executed without any command line
-arguments. 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
-
-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 cMff /dev/tape0 /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/sh
-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
-@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 give. @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
-@UNREVISED
-
-@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 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
-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 a single command line
-argument, @command{tar} compares the volume label with the
-argument. It exits with code 0 if the two strings match, and with code
-2 otherwise. In this case no output is displayed. For example:
-
-@smallexample
-@group
-$ @kbd{tar --test-label --file=iamanarchive 'iamalable'}
-@result{} 0
-$ @kbd{tar --test-label --file=iamanarchive 'iamalable' alabel}
-@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.
-
- The @option{--label} was once called @option{--volume}, but is not
-available under that name anymore.
-
- 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 cfMV /dev/tape "Daily backup for `date +%Y-%m-%d`"}
-$ @kbd{tar --create --file=/dev/tape --multi-volume \
- --volume="Daily backup for `date +%Y-%m-%d`"}
-@end group
-@end smallexample
-
- Also note that each label has its own date and time, which corresponds
-to 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. Comparing date
-labels does give an idea of tape throughput only if the delays for
-rewinding tapes and the operator switching them were negligible, which
-is usually not the case.
-
-@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 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 --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.
-
-@FIXME{Change the first argument to tar-formats when the new Automake is
-out. The proposition to add @anchor{} to the appropriate place of its
-docs was accepted by Automake people --Sergey 2006-05-25}.
-@xref{Options, tar-v7, 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
-implementation, 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 Copying This Manual
-@appendix Copying This Manual
-
-@menu
-* GNU Free Documentation License:: License for copying this manual
-@end menu
-
-@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, @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:
+++ /dev/null
-# Copyright (C) 2006, 2007 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, 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 GNU tar; if not, write to the Free Software
-# Foundation, Inc. 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
-
-1{s,/\*,@comment ,
-b
-}
-2,/.*\*\//{s,\*/,,;s/^/@comment/
-b
-}
-/\/* END \*\//,$d
-s/\([{}]\)/@\1/g
-s,/\*,&@r{,
-s,\*/,}&,
+++ /dev/null
-;;;; 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)
+++ /dev/null
-@c This is part of GNU tar manual.
-@c Copyright (C) 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001,
-@c 2003, 2004, 2005, 2006 Free Software 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
-
-
+++ /dev/null
-@set UPDATED 14 April 2008
-@set UPDATED-MONTH April 2008
-@set EDITION 1.20
-@set VERSION 1.20
projects / debian / tar / commitdiff