From 5c46f61cabb7912f25347b9300d1d585d7a635cb Mon Sep 17 00:00:00 2001 From: Bdale Garbee Date: Tue, 24 Feb 2009 21:57:41 -0700 Subject: [PATCH] strip docs under GFDL which are not DFSG-compliant --- cleanup-script.sh | 7 + doc/Makefile.am | 144 - doc/Makefile.in | 1049 ---- doc/dumpdir.texi | 132 - doc/fdl.texi | 452 -- doc/freemanuals.texi | 89 - doc/gendocs_template | 125 - doc/genfile.texi | 331 - doc/getdate.texi | 553 -- doc/header.texi | 242 - doc/intern.texi | 333 - doc/mastermenu.el | 91 - doc/rendition.texi | 99 - doc/snapshot.texi | 141 - doc/sparse.texi | 235 - doc/stamp-vti | 4 - doc/tar-snapshot-edit.texi | 58 - doc/tar.info | 402 -- doc/tar.info-1 | 7723 ----------------------- doc/tar.info-2 | 5226 ---------------- doc/tar.texi | 11458 ----------------------------------- doc/texify.sed | 26 - doc/untabify.el | 13 - doc/value.texi | 22 - doc/version.texi | 4 - 25 files changed, 7 insertions(+), 28952 deletions(-) create mode 100755 cleanup-script.sh delete mode 100644 doc/Makefile.am delete mode 100644 doc/Makefile.in delete mode 100644 doc/dumpdir.texi delete mode 100644 doc/fdl.texi delete mode 100644 doc/freemanuals.texi delete mode 100755 doc/gendocs_template delete mode 100644 doc/genfile.texi delete mode 100644 doc/getdate.texi delete mode 100644 doc/header.texi delete mode 100644 doc/intern.texi delete mode 100644 doc/mastermenu.el delete mode 100644 doc/rendition.texi delete mode 100644 doc/snapshot.texi delete mode 100644 doc/sparse.texi delete mode 100644 doc/stamp-vti delete mode 100644 doc/tar-snapshot-edit.texi delete mode 100644 doc/tar.info delete mode 100644 doc/tar.info-1 delete mode 100644 doc/tar.info-2 delete mode 100644 doc/tar.texi delete mode 100644 doc/texify.sed delete mode 100644 doc/untabify.el delete mode 100644 doc/value.texi delete mode 100644 doc/version.texi diff --git a/cleanup-script.sh b/cleanup-script.sh new file mode 100755 index 0000000..899cbf9 --- /dev/null +++ b/cleanup-script.sh @@ -0,0 +1,7 @@ +#!/bin/sh +# +# clean upstream source to achieve DFSG compliance +# Copyright 2009 by Bdale Garbee. GPL v2 or any later version. +# + +rm -rf doc diff --git a/doc/Makefile.am b/doc/Makefile.am deleted file mode 100644 index 1715d35..0000000 --- a/doc/Makefile.am +++ /dev/null @@ -1,144 +0,0 @@ -# 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' - diff --git a/doc/Makefile.in b/doc/Makefile.in deleted file mode 100644 index 73bebcd..0000000 --- a/doc/Makefile.in +++ /dev/null @@ -1,1049 +0,0 @@ -# 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: diff --git a/doc/dumpdir.texi b/doc/dumpdir.texi deleted file mode 100644 index faf9ca2..0000000 --- a/doc/dumpdir.texi +++ /dev/null @@ -1,132 +0,0 @@ -@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 diff --git a/doc/fdl.texi b/doc/fdl.texi deleted file mode 100644 index fe78df8..0000000 --- a/doc/fdl.texi +++ /dev/null @@ -1,452 +0,0 @@ - -@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: - diff --git a/doc/freemanuals.texi b/doc/freemanuals.texi deleted file mode 100644 index 25343f9..0000000 --- a/doc/freemanuals.texi +++ /dev/null @@ -1,89 +0,0 @@ -@cindex free documentation - -The biggest deficiency in the free software community today is not in -the software---it is the lack of good free documentation that we can -include with the free software. Many of our most important -programs do not come with free reference manuals and free introductory -texts. Documentation is an essential part of any software package; -when an important free software package does not come with a free -manual and a free tutorial, that is a major gap. We have many such -gaps today. - -Consider Perl, for instance. The tutorial manuals that people -normally use are non-free. How did this come about? Because the -authors of those manuals published them with restrictive terms---no -copying, no modification, source files not available---which exclude -them from the free software world. - -That wasn't the first time this sort of thing happened, and it was far -from the last. Many times we have heard a GNU user eagerly describe a -manual that he is writing, his intended contribution to the community, -only to learn that he had ruined everything by signing a publication -contract to make it non-free. - -Free documentation, like free software, is a matter of freedom, not -price. The problem with the non-free manual is not that publishers -charge a price for printed copies---that in itself is fine. (The Free -Software Foundation sells printed copies of manuals, too.) The -problem is the restrictions on the use of the manual. Free manuals -are available in source code form, and give you permission to copy and -modify. Non-free manuals do not allow this. - -The criteria of freedom for a free manual are roughly the same as for -free software. Redistribution (including the normal kinds of -commercial redistribution) must be permitted, so that the manual can -accompany every copy of the program, both on-line and on paper. - -Permission for modification of the technical content is crucial too. -When people modify the software, adding or changing features, if they -are conscientious they will change the manual too---so they can -provide accurate and clear documentation for the modified program. A -manual that leaves you no choice but to write a new manual to document -a changed version of the program is not really available to our -community. - -Some kinds of limits on the way modification is handled are -acceptable. For example, requirements to preserve the original -author's copyright notice, the distribution terms, or the list of -authors, are ok. It is also no problem to require modified versions -to include notice that they were modified. Even entire sections that -may not be deleted or changed are acceptable, as long as they deal -with nontechnical topics (like this one). These kinds of restrictions -are acceptable because they don't obstruct the community's normal use -of the manual. - -However, it must be possible to modify all the @emph{technical} -content of the manual, and then distribute the result in all the usual -media, through all the usual channels. Otherwise, the restrictions -obstruct the use of the manual, it is not free, and we need another -manual to replace it. - -Please spread the word about this issue. Our community continues to -lose manuals to proprietary publishing. If we spread the word that -free software needs free reference manuals and free tutorials, perhaps -the next person who wants to contribute by writing documentation will -realize, before it is too late, that only free manuals contribute to -the free software community. - -If you are writing documentation, please insist on publishing it under -the GNU Free Documentation License or another free documentation -license. Remember that this decision requires your approval---you -don't have to let the publisher decide. Some commercial publishers -will use a free license if you insist, but they will not propose the -option; it is up to you to raise the issue and say firmly that this is -what you want. If the publisher you are dealing with refuses, please -try other publishers. If you're not sure whether a proposed license -is free, write to @email{licensing@@gnu.org}. - -You can encourage commercial publishers to sell more free, copylefted -manuals and tutorials by buying them, and particularly by buying -copies from the publishers that paid for their writing or for major -improvements. Meanwhile, try to avoid buying non-free documentation -at all. Check the distribution terms of a manual before you buy it, -and insist that whoever seeks your business must respect your freedom. -Check the history of the book, and try reward the publishers that have -paid or pay the authors to work on it. - -The Free Software Foundation maintains a list of free documentation -published by other publishers, at -@url{http://www.fsf.org/doc/other-free-books.html}. diff --git a/doc/gendocs_template b/doc/gendocs_template deleted file mode 100755 index 2f989ed..0000000 --- a/doc/gendocs_template +++ /dev/null @@ -1,125 +0,0 @@ - - - - - - -%%TITLE%% - GNU Project - Free Software Foundation (FSF) - - - - - - - - - - - - - - -

%%TITLE%%

- -
Free Software Foundation
-
last updated %%DATE%%
-

- - [image of the head of a GNU] - -

-
- -

The manual for %%PACKAGE%% is available in the following formats:

- - - -

(This page generated by the %%SCRIPTNAME%% script.) -

- -

-Valid XHTML 1.0! -

- -
-

-Return to the GNU Project home page. -

- -

-Please send FSF & GNU inquiries to -gnu@gnu.org. -There are also other ways to contact -the FSF. -
-Please send broken links and other corrections (or suggestions) to -webmasters@gnu.org. -

- -

-Copyright (C) 2004 Free Software Foundation, Inc., -51 Franklin Street, Fifth Floor, Boston, MA 02111, USA -
-Verbatim copying and distribution of this entire article is -permitted in any medium, provided this notice is preserved. -

- -

-Updated: - -$Date: 2007/10/30 14:58:52 $ $Author: gray $ - -

-
- - - diff --git a/doc/genfile.texi b/doc/genfile.texi deleted file mode 100644 index f9ef870..0000000 --- a/doc/genfile.texi +++ /dev/null @@ -1,331 +0,0 @@ -@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. diff --git a/doc/getdate.texi b/doc/getdate.texi deleted file mode 100644 index eae4526..0000000 --- a/doc/getdate.texi +++ /dev/null @@ -1,553 +0,0 @@ -@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}). diff --git a/doc/header.texi b/doc/header.texi deleted file mode 100644 index 6efb8f2..0000000 --- a/doc/header.texi +++ /dev/null @@ -1,242 +0,0 @@ -@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; -@}; - diff --git a/doc/intern.texi b/doc/intern.texi deleted file mode 100644 index 3580a7b..0000000 --- a/doc/intern.texi +++ /dev/null @@ -1,333 +0,0 @@ -@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 - diff --git a/doc/mastermenu.el b/doc/mastermenu.el deleted file mode 100644 index 5f1dbe1..0000000 --- a/doc/mastermenu.el +++ /dev/null @@ -1,91 +0,0 @@ -;;; 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 diff --git a/doc/rendition.texi b/doc/rendition.texi deleted file mode 100644 index 558772a..0000000 --- a/doc/rendition.texi +++ /dev/null @@ -1,99 +0,0 @@ -@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{} \string\ @strong{} -@end cartouche -@end ifclear -@end ifset - -@end macro - -@macro FIXME-ref{string} -@ifset PROOF -@strong{} \string\ @strong{} -@end ifset -@ifclear PROOF -@cite{\string\} -@end ifclear -@end macro - -@macro FIXME-pxref{string} -@ifset PROOF -See @strong{} \string\ @strong{} -@end ifset -@ifclear PROOF -See @cite{\string\} -@end ifclear - -@end macro - -@macro FIXME-xref{string} -@ifset PROOF -See @strong{} \string\ @strong{} -@end ifset -@ifclear PROOF -See @cite{\string\} -@end ifclear -@end macro - -@c End of rendition.texi diff --git a/doc/snapshot.texi b/doc/snapshot.texi deleted file mode 100644 index 3366402..0000000 --- a/doc/snapshot.texi +++ /dev/null @@ -1,141 +0,0 @@ -@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 - - diff --git a/doc/sparse.texi b/doc/sparse.texi deleted file mode 100644 index e8a9ea1..0000000 --- a/doc/sparse.texi +++ /dev/null @@ -1,235 +0,0 @@ -@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{}. - diff --git a/doc/stamp-vti b/doc/stamp-vti deleted file mode 100644 index 580b586..0000000 --- a/doc/stamp-vti +++ /dev/null @@ -1,4 +0,0 @@ -@set UPDATED 14 April 2008 -@set UPDATED-MONTH April 2008 -@set EDITION 1.20 -@set VERSION 1.20 diff --git a/doc/tar-snapshot-edit.texi b/doc/tar-snapshot-edit.texi deleted file mode 100644 index 9c01a4a..0000000 --- a/doc/tar-snapshot-edit.texi +++ /dev/null @@ -1,58 +0,0 @@ -@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 - diff --git a/doc/tar.info b/doc/tar.info deleted file mode 100644 index 542ce30..0000000 --- a/doc/tar.info +++ /dev/null @@ -1,402 +0,0 @@ -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 - - -Indirect: -tar.info-1: 1246 -tar.info-2: 303205 - -Tag Table: -(Indirect) -Node: Top1246 -Node: Introduction10511 -Node: Book Contents11298 -Node: Definitions13470 -Node: What tar Does15273 -Node: Naming tar Archives18039 -Node: Authors18759 -Node: Reports20572 -Node: Tutorial20932 -Node: assumptions21745 -Node: stylistic conventions24220 -Node: basic tar options24663 -Node: frequent operations28301 -Node: Two Frequent Options28953 -Node: file tutorial29584 -Node: verbose tutorial30945 -Ref: verbose member listing33159 -Node: help tutorial35912 -Node: create36266 -Node: prepare for examples37767 -Node: Creating the archive39535 -Node: create verbose42367 -Node: short create43188 -Node: create dir45941 -Node: list48648 -Ref: listing member and file names49922 -Node: list dir52203 -Node: extract53192 -Node: extracting archives54369 -Node: extracting files54859 -Ref: extracting files-Footnote-157506 -Node: extract dir57886 -Node: extracting untrusted archives60269 -Node: failing commands61148 -Node: going further62248 -Node: tar invocation62461 -Node: Synopsis63973 -Node: using tar options68942 -Ref: TAR_OPTIONS70527 -Node: Styles71544 -Node: Long Options73256 -Node: Short Options75428 -Ref: Short Options-Footnote-177236 -Node: Old Options77453 -Ref: Old Options-Footnote-180403 -Node: Mixing80573 -Ref: Mixing-Footnote-182939 -Node: All Options83059 -Node: Operation Summary83664 -Ref: --append83784 -Ref: --catenate83864 -Ref: --compare83935 -Ref: --concatenate84138 -Ref: --create84248 -Ref: --delete84316 -Ref: --diff84429 -Ref: --extract84485 -Ref: --get84587 -Ref: --list84645 -Ref: --update84713 -Node: Option Summary84923 -Ref: --absolute-names85078 -Ref: --after-date85256 -Ref: --anchored85308 -Ref: --atime-preserve85441 -Ref: --auto-compress87956 -Ref: --backup88112 -Ref: --block-number88303 -Ref: --blocking-factor88477 -Ref: --bzip288629 -Ref: --check-device88736 -Ref: --checkpoint88931 -Ref: --checkpoint-action89372 -Ref: --check-links90523 -Ref: --compress90800 -Ref: --uncompress90800 -Ref: --confirmation91004 -Ref: --delay-directory-restore91072 -Ref: --dereference91273 -Ref: --directory91458 -Ref: --exclude91711 -Ref: --exclude-from91830 -Ref: --exclude-caches91976 -Ref: --exclude-caches-under92170 -Ref: --exclude-caches-all92348 -Ref: --exclude-tag92477 -Ref: --exclude-tag-under92632 -Ref: --exclude-tag-all92800 -Ref: --exclude-vcs92914 -Ref: --file93069 -Ref: --files-from93269 -Ref: --force-local93472 -Ref: --format93663 -Ref: --group94333 -Ref: --gzip94681 -Ref: --gunzip94681 -Ref: --ungzip94681 -Ref: --hard-dereference94904 -Ref: --help95091 -Ref: --ignore-case95225 -Ref: --ignore-command-error95352 -Ref: --ignore-failed-read95463 -Ref: --ignore-zeros95593 -Ref: --incremental95738 -Ref: --index-file96003 -Ref: --info-script96088 -Ref: --new-volume-script96088 -Ref: --interactive96409 -Ref: --keep-newer-files96621 -Ref: --keep-old-files96763 -Ref: --label96894 -Ref: --listed-incremental97182 -Ref: --lzma97546 -Ref: --mode97646 -Ref: --mtime97937 -Ref: --multi-volume98378 -Ref: --newer98579 -Ref: --newer-mtime98857 -Ref: --no-anchored99081 -Ref: --no-check-device99218 -Ref: --no-delay-directory-restore99401 -Ref: --no-ignore-case99654 -Ref: --no-ignore-command-error99747 -Ref: --no-overwrite-dir99902 -Ref: --no-quote-chars100045 -Ref: --no-recursion100226 -Ref: --no-same-owner100331 -Ref: --no-same-permissions100514 -Ref: --no-unquote100716 -Ref: --no-wildcards100854 -Ref: --no-wildcards-match-slash100938 -Ref: --null101040 -Ref: --numeric-owner101268 -Ref: --occurrence101919 -Ref: --old-archive102486 -Ref: --one-file-system102535 -Ref: --overwrite102713 -Ref: --overwrite-dir102855 -Ref: --owner103000 -Ref: --pax-option103379 -Ref: --portability103678 -Ref: --posix103743 -Ref: --preserve103785 -Ref: --preserve-order103923 -Ref: --preserve-permissions103987 -Ref: --same-permissions103987 -Ref: --quote-chars104401 -Ref: --quoting-style104554 -Ref: --read-full-records104875 -Ref: --record-size105040 -Ref: --recursion105171 -Ref: --recursive-unlink105274 -Ref: --remove-files105441 -Ref: --restrict105587 -Ref: --rmt-command105775 -Ref: --rsh-command105916 -Ref: --same-order106038 -Ref: --same-owner106330 -Ref: --seek106707 -Ref: --show-defaults106964 -Ref: --show-omitted-dirs107332 -Ref: --show-transformed-names107486 -Ref: --show-stored-names107486 -Ref: --sparse107875 -Ref: --sparse-version108014 -Ref: --starting-file108238 -Ref: --strip-components108427 -Ref: --suffix108739 -Ref: --tape-length108874 -Ref: --test-label109029 -Ref: --to-command109181 -Ref: --to-stdout109340 -Ref: --totals109493 -Ref: --touch109724 -Ref: --transform109926 -Ref: --unlink-first110518 -Ref: --unquote110686 -Ref: --use-compress-program110793 -Ref: --utc110961 -Ref: --verbose111054 -Ref: --verify111306 -Ref: --version111424 -Ref: --volno-file111596 -Ref: --wildcards111783 -Ref: --wildcards-match-slash111903 -Ref: Option Summary-Footnote-1112031 -Node: Short Option Summary112249 -Node: help114420 -Ref: help-Footnote-1118250 -Node: defaults118460 -Node: verbose119477 -Ref: totals121778 -Ref: Progress information123368 -Ref: show-omitted-dirs124347 -Ref: block-number124766 -Ref: verbose-Footnote-1125793 -Node: checkpoints125900 -Node: interactive131291 -Node: operations133374 -Node: Basic tar133633 -Ref: Basic tar-Footnote-1136737 -Node: Advanced tar136881 -Node: Operations137726 -Node: append139696 -Ref: append-Footnote-1142861 -Node: appending files143027 -Node: multiple144808 -Node: update147498 -Node: how to update148537 -Node: concatenate150320 -Ref: concatenate-Footnote-1153569 -Node: delete153707 -Node: compare155550 -Node: create options157040 -Node: override157498 -Node: Ignore Failed Read160936 -Node: extract options161156 -Node: Reading162052 -Node: read full records163615 -Node: Ignore Zeros163951 -Node: Writing164942 -Node: Dealing with Old Files165499 -Node: Overwrite Old Files167926 -Node: Keep Old Files169383 -Node: Keep Newer Files169893 -Node: Unlink First170183 -Node: Recursive Unlink170587 -Node: Data Modification Times171140 -Node: Setting Access Permissions171950 -Node: Directory Modification Times and Permissions172582 -Node: Writing to Standard Output176188 -Node: Writing to an External Program177723 -Node: remove files180460 -Node: Scarce180653 -Node: Starting File180901 -Node: Same Order181721 -Node: backup182557 -Node: Applications185781 -Node: looking ahead187294 -Node: Backups188120 -Node: Full Dumps189952 -Node: Incremental Dumps191758 -Ref: device numbers194894 -Ref: incremental-op198876 -Ref: Incremental Dumps-Footnote-1199250 -Ref: Incremental Dumps-Footnote-2199400 -Node: Backup Levels199887 -Node: Backup Parameters202274 -Node: General-Purpose Variables203455 -Ref: RSH206612 -Node: Magnetic Tape Control208491 -Node: User Hooks209828 -Node: backup-specs example211156 -Node: Scripted Backups212299 -Ref: Scripted Backups-Footnote-1215161 -Node: Scripted Restoration215545 -Node: Choosing218153 -Node: file219338 -Ref: remote-dev222037 -Ref: local and remote archives222429 -Node: Selecting Archive Members223459 -Ref: input name quoting224140 -Node: files226126 -Ref: files-Footnote-1229400 -Node: nul229558 -Node: exclude230855 -Node: problems with exclude235619 -Node: wildcards237664 -Node: controlling pattern-matching240248 -Ref: controlling pattern-matching-Footnote-1244238 -Node: quoting styles244454 -Ref: escape sequences244800 -Node: transform250936 -Ref: show-transformed-names252926 -Node: after256915 -Node: recurse260580 -Node: one263349 -Node: directory264845 -Node: absolute267918 -Ref: absolute-Footnote-1271108 -Node: Date input formats271459 -Node: General date syntax273775 -Node: Calendar date items276726 -Node: Time of day items278723 -Node: Time zone items280839 -Node: Day of week items282073 -Node: Relative items in date strings283062 -Node: Pure numbers in date strings285864 -Node: Seconds since the Epoch286845 -Node: Specifying time zone rules288466 -Node: Authors of get_date290830 -Node: Formats291582 -Node: Compression296270 -Node: gzip296562 -Ref: auto-compress299320 -Ref: gzip-Footnote-1303156 -Node: sparse303205 -Node: Attributes306259 -Node: Portability312230 -Node: Portable Names313716 -Node: dereference314421 -Node: hard links315822 -Ref: hard links-Footnote-1318780 -Node: old318836 -Node: ustar320020 -Node: gnu320611 -Node: posix321488 -Node: PAX keywords321969 -Node: Checksumming326297 -Node: Large or Negative Values328221 -Node: Other Tars329821 -Node: Split Recovery330957 -Node: Sparse Recovery334689 -Ref: extracting sparse v.0.x338322 -Ref: Sparse Recovery-Footnote-1341611 -Ref: Sparse Recovery-Footnote-2341634 -Node: cpio341755 -Node: Media346511 -Node: Device348441 -Node: Remote Tape Server353509 -Node: Common Problems and Solutions357239 -Node: Blocking357631 -Node: Format Variations364138 -Node: Blocking Factor365050 -Node: Many376704 -Node: Tape Positioning380498 -Node: mt382371 -Node: Using Multiple Tapes383926 -Node: Multi-Volume Archives385992 -Ref: tape-length387477 -Ref: change volume prompt387781 -Ref: volno-file388651 -Ref: info-script389203 -Ref: Multi-Volume Archives-Footnote-1394387 -Ref: Multi-Volume Archives-Footnote-2394497 -Node: Tape Files394564 -Node: Tarcat396048 -Node: label397093 -Ref: --test-label option398722 -Ref: label-Footnote-1401767 -Node: verify402002 -Node: Write Protection405302 -Node: Changes406132 -Node: Configuring Help Summary409717 -Node: Fixing Snapshot Files416220 -Node: Tar Internals418405 -Node: Standard418737 -Node: Extensions440938 -Node: Sparse Formats443498 -Node: Old GNU Format444788 -Node: PAX 0447199 -Node: PAX 1450326 -Node: Snapshot Files452060 -Node: Dumpdir456513 -Node: Genfile459759 -Node: Generate Mode460852 -Node: Status Mode465149 -Node: Exec Mode466948 -Node: Free Software Needs Free Documentation469184 -Node: Copying This Manual474155 -Node: GNU Free Documentation License474437 -Node: Index of Command Line Options496844 -Node: Index520649 - -End Tag Table diff --git a/doc/tar.info-1 b/doc/tar.info-1 deleted file mode 100644 index 67f9cf9..0000000 --- a/doc/tar.info-1 +++ /dev/null @@ -1,7723 +0,0 @@ -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 - - -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 - - -File: tar.info, Node: Introduction, Next: Tutorial, Prev: Top, Up: Top - -1 Introduction -************** - -GNU `tar' creates and manipulates "archives" which are actually -collections of many other files; the program provides users with an -organized and systematic method for controlling a large amount of data. -The name "tar" originally came from the phrase "Tape ARchive", but -archives need not (and these days, typically do not) reside on tapes. - -* Menu: - -* Book Contents:: What this Book Contains -* Definitions:: Some Definitions -* What tar Does:: What `tar' Does -* Naming tar Archives:: How `tar' Archives are Named -* Authors:: GNU `tar' Authors -* Reports:: Reporting bugs or suggestions - - -File: tar.info, Node: Book Contents, Next: Definitions, Up: Introduction - -1.1 What this Book Contains -=========================== - -The first part of this chapter introduces you to various terms that will -recur throughout the book. It also tells you who has worked on GNU -`tar' and its documentation, and where you should send bug reports or -comments. - - The second chapter is a tutorial (*note Tutorial::) which provides a -gentle introduction for people who are new to using `tar'. It is meant -to be self contained, not requiring any reading from subsequent -chapters to make sense. It moves from topic to topic in a logical, -progressive order, building on information already explained. - - Although the tutorial is paced and structured to allow beginners to -learn how to use `tar', it is not intended solely for beginners. The -tutorial explains how to use the three most frequently used operations -(`create', `list', and `extract') as well as two frequently used -options (`file' and `verbose'). The other chapters do not refer to the -tutorial frequently; however, if a section discusses something which is -a complex variant of a basic concept, there may be a cross reference to -that basic concept. (The entire book, including the tutorial, assumes -that the reader understands some basic concepts of using a Unix-type -operating system; *note Tutorial::.) - - The third chapter presents the remaining five operations, and -information about using `tar' options and option syntax. - - The other chapters are meant to be used as a reference. Each chapter -presents everything that needs to be said about a specific topic. - - One of the chapters (*note Date input formats::) exists in its -entirety in other GNU manuals, and is mostly self-contained. In -addition, one section of this manual (*note Standard::) contains a big -quote which is taken directly from `tar' sources. - - In general, we give both long and short (abbreviated) option names -at least once in each section where the relevant option is covered, so -that novice readers will become familiar with both styles. (A few -options have no short versions, and the relevant sections will indicate -this.) - - -File: tar.info, Node: Definitions, Next: What tar Does, Prev: Book Contents, Up: Introduction - -1.2 Some Definitions -==================== - -The `tar' program is used to create and manipulate `tar' archives. An -"archive" is a single file which contains the contents of many files, -while still identifying the names of the files, their owner(s), and so -forth. (In addition, archives record access permissions, user and -group, size in bytes, and data modification time. Some archives also -record the file names in each archived directory, as well as other file -and directory information.) You can use `tar' to "create" a new -archive in a specified directory. - - The files inside an archive are called "members". Within this -manual, we use the term "file" to refer only to files accessible in the -normal ways (by `ls', `cat', and so forth), and the term "member" to -refer only to the members of an archive. Similarly, a "file name" is -the name of a file, as it resides in the file system, and a "member -name" is the name of an archive member within the archive. - - The term "extraction" refers to the process of copying an archive -member (or multiple members) into a file in the file system. Extracting -all the members of an archive is often called "extracting the archive". -The term "unpack" can also be used to refer to the extraction of many -or all the members of an archive. Extracting an archive does not -destroy the archive's structure, just as creating an archive does not -destroy the copies of the files that exist outside of the archive. You -may also "list" the members in a given archive (this is often thought -of as "printing" them to the standard output, or the command line), or -"append" members to a pre-existing archive. All of these operations -can be performed using `tar'. - - -File: tar.info, Node: What tar Does, Next: Naming tar Archives, Prev: Definitions, Up: Introduction - -1.3 What `tar' Does -=================== - -The `tar' program provides the ability to create `tar' archives, as -well as various other kinds of manipulation. For example, you can use -`tar' on previously created archives to extract files, to store -additional files, or to update or list files which were already stored. - - Initially, `tar' archives were used to store files conveniently on -magnetic tape. The name `tar' comes from this use; it stands for -`t'ape `ar'chiver. Despite the utility's name, `tar' can direct its -output to available devices, files, or other programs (using pipes). -`tar' may even access remote devices or files (as archives). - - You can use `tar' archives in many ways. We want to stress a few of -them: storage, backup, and transportation. - -Storage - Often, `tar' archives are used to store related files for - convenient file transfer over a network. For example, the GNU - Project distributes its software bundled into `tar' archives, so - that all the files relating to a particular program (or set of - related programs) can be transferred as a single unit. - - A magnetic tape can store several files in sequence. However, the - tape has no names for these files; it only knows their relative - position on the tape. One way to store several files on one tape - and retain their names is by creating a `tar' archive. Even when - the basic transfer mechanism can keep track of names, as FTP can, - the nuisance of handling multiple files, directories, and multiple - links makes `tar' archives useful. - - Archive files are also used for long-term storage. You can think - of this as transportation from the present into the future. (It - is a science-fiction idiom that you can move through time as well - as in space; the idea here is that `tar' can be used to move - archives in all dimensions, even time!) - -Backup - Because the archive created by `tar' is capable of preserving file - information and directory structure, `tar' is commonly used for - performing full and incremental backups of disks. A backup puts a - collection of files (possibly pertaining to many users and - projects) together on a disk or a tape. This guards against - accidental destruction of the information in those files. GNU - `tar' has special features that allow it to be used to make - incremental and full dumps of all the files in a file system. - -Transportation - You can create an archive on one system, transfer it to another - system, and extract the contents there. This allows you to - transport a group of files from one system to another. - - -File: tar.info, Node: Naming tar Archives, Next: Authors, Prev: What tar Does, Up: Introduction - -1.4 How `tar' Archives are Named -================================ - -Conventionally, `tar' archives are given names ending with `.tar'. -This is not necessary for `tar' to operate properly, but this manual -follows that convention in order to accustom readers to it and to make -examples more clear. - - Often, people refer to `tar' archives as "`tar' files," and archive -members as "files" or "entries". For people familiar with the -operation of `tar', this causes no difficulty. However, in this -manual, we consistently refer to "archives" and "archive members" to -make learning to use `tar' easier for novice users. - - -File: tar.info, Node: Authors, Next: Reports, Prev: Naming tar Archives, Up: Introduction - -1.5 GNU `tar' Authors -===================== - -GNU `tar' was originally written by John Gilmore, and modified by many -people. The GNU enhancements were written by Jay Fenlason, then Joy -Kendall, and the whole package has been further maintained by Thomas -Bushnell, n/BSG, Franc,ois Pinard, Paul Eggert, and finally Sergey -Poznyakoff with the help of numerous and kind users. - - We wish to stress that `tar' is a collective work, and owes much to -all those people who reported problems, offered solutions and other -insights, or shared their thoughts and suggestions. An impressive, yet -partial list of those contributors can be found in the `THANKS' file -from the GNU `tar' distribution. - - Jay Fenlason put together a draft of a GNU `tar' manual, borrowing -notes from the original man page from John Gilmore. This was withdrawn -in version 1.11. Thomas Bushnell, n/BSG and Amy Gorin worked on a -tutorial and manual for GNU `tar'. Franc,ois Pinard put version 1.11.8 -of the manual together by taking information from all these sources and -merging them. Melissa Weisshaus finally edited and redesigned the book -to create version 1.12. The book for versions from 1.14 up to 1.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. - - -File: tar.info, Node: Reports, Prev: Authors, Up: Introduction - -1.6 Reporting bugs or suggestions -================================= - -If you find problems or have suggestions about this program or manual, -please report them to `bug-tar@gnu.org'. - - When reporting a bug, please be sure to include as much detail as -possible, in order to reproduce it. . - - -File: tar.info, Node: Tutorial, Next: tar invocation, Prev: Introduction, Up: Top - -2 Tutorial Introduction to `tar' -******************************** - -This chapter guides you through some basic examples of three `tar' -operations: `--create', `--list', and `--extract'. If you already know -how to use some other version of `tar', then you may not need to read -this chapter. This chapter omits most complicated details about how -`tar' works. - -* Menu: - -* assumptions:: -* stylistic conventions:: -* basic tar options:: Basic `tar' Operations and Options -* frequent operations:: -* Two Frequent Options:: -* create:: How to Create Archives -* list:: How to List Archives -* extract:: How to Extract Members from an Archive -* going further:: - - -File: tar.info, Node: assumptions, Next: stylistic conventions, Up: Tutorial - -2.1 Assumptions this Tutorial Makes -=================================== - -This chapter is paced to allow beginners to learn about `tar' slowly. -At the same time, we will try to cover all the basic aspects of these -three operations. In order to accomplish both of these tasks, we have -made certain assumptions about your knowledge before reading this -manual, and the hardware you will be using: - - * Before you start to work through this tutorial, you should - understand what the terms "archive" and "archive member" mean - (*note Definitions::). In addition, you should understand - something about how Unix-type operating systems work, and you - should know how to use some basic utilities. For example, you - should know how to create, list, copy, rename, edit, and delete - files and directories; how to change between directories; and how - to figure out where you are in the file system. You should have - some basic understanding of directory structure and how files are - named according to which directory they are in. You should - understand concepts such as standard output and standard input, - what various definitions of the term `argument' mean, and the - differences between relative and absolute file names. - - * This manual assumes that you are working from your own home - directory (unless we state otherwise). In this tutorial, you will - create a directory to practice `tar' commands in. When we show - file names, we will assume that those names are relative to your - home directory. For example, my home directory is - `/home/fsf/melissa'. All of my examples are in a subdirectory of - the directory named by that file name; the subdirectory is called - `practice'. - - * In general, we show examples of archives which exist on (or can be - written to, or worked with from) a directory on a hard disk. In - most cases, you could write those archives to, or work with them - on any other device, such as a tape drive. However, some of the - later examples in the tutorial and next chapter will not work on - tape drives. Additionally, working with tapes is much more - complicated than working with hard disks. For these reasons, the - tutorial does not cover working with tape drives. *Note Media::, - for complete information on using `tar' archives with tape drives. - - - -File: tar.info, Node: stylistic conventions, Next: basic tar options, Prev: assumptions, Up: Tutorial - -2.2 Stylistic Conventions -========================= - -In the examples, `$' represents a typical shell prompt. It precedes -lines you should type; to make this more clear, those lines are shown -in `this font', as opposed to lines which represent the computer's -response; those lines are shown in `this font', or sometimes `like -this'. - - -File: tar.info, Node: basic tar options, Next: frequent operations, Prev: stylistic conventions, Up: Tutorial - -2.3 Basic `tar' Operations and Options -====================================== - -`tar' can take a wide variety of arguments which specify and define the -actions it will have on the particular set of files or the archive. -The main types of arguments to `tar' fall into one of two classes: -operations, and options. - - Some arguments fall into a class called "operations"; exactly one of -these is both allowed and required for any instance of using `tar'; you -may _not_ specify more than one. People sometimes speak of "operating -modes". You are in a particular operating mode when you have specified -the operation which specifies it; there are eight operations in total, -and thus there are eight operating modes. - - The other arguments fall into the class known as "options". You are -not required to specify any options, and you are allowed to specify more -than one at a time (depending on the way you are using `tar' at that -time). Some options are used so frequently, and are so useful for -helping you type commands more carefully that they are effectively -"required". We will discuss them in this chapter. - - You can write most of the `tar' operations and options in any of -three forms: long (mnemonic) form, short form, and old style. Some of -the operations and options have no short or "old" forms; however, the -operations and options which we will cover in this tutorial have -corresponding abbreviations. We will indicate those abbreviations -appropriately to get you used to seeing them. (Note that the "old -style" option forms exist in GNU `tar' for compatibility with Unix -`tar'. In this book we present a full discussion of this way of -writing options and operations (*note Old Options::), and we discuss -the other two styles of writing options (*Note Long Options::, and -*note Short Options::). - - In the examples and in the text of this tutorial, we usually use the -long forms of operations and options; but the "short" forms produce the -same result and can make typing long `tar' commands easier. For -example, instead of typing - - tar --create --verbose --file=afiles.tar apple angst aspic - -you can type - tar -c -v -f afiles.tar apple angst aspic - -or even - tar -cvf afiles.tar apple angst aspic - -For more information on option syntax, see *note Advanced tar::. In -discussions in the text, when we name an option by its long form, we -also give the corresponding short option in parentheses. - - The term, "option", can be confusing at times, since "operations" -are often lumped in with the actual, _optional_ "options" in certain -general class statements. For example, we just talked about "short and -long forms of options and operations". However, experienced `tar' -users often refer to these by shorthand terms such as, "short and long -options". This term assumes that the "operations" are included, also. -Context will help you determine which definition of "options" to use. - - Similarly, the term "command" can be confusing, as it is often used -in two different ways. People sometimes refer to `tar' "commands". A -`tar' "command" is the entire command line of user input which tells -`tar' what to do -- including the operation, options, and any arguments -(file names, pipes, other commands, etc.). However, you will also -sometimes hear the term "the `tar' command". When the word "command" -is used specifically like this, a person is usually referring to the -`tar' _operation_, not the whole line. Again, use context to figure -out which of the meanings the speaker intends. - - -File: tar.info, Node: frequent operations, Next: Two Frequent Options, Prev: basic tar options, Up: Tutorial - -2.4 The Three Most Frequently Used Operations -============================================= - -Here are the three most frequently used operations (both short and long -forms), as well as a brief description of their meanings. The rest of -this chapter will cover how to use these operations in detail. We will -present the rest of the operations in the next chapter. - -`--create' -`-c' - Create a new `tar' archive. - -`--list' -`-t' - List the contents of an archive. - -`--extract' -`-x' - Extract one or more members from an archive. - - -File: tar.info, Node: Two Frequent Options, Next: create, Prev: frequent operations, Up: Tutorial - -2.5 Two Frequently Used Options -=============================== - -To understand how to run `tar' in the three operating modes listed -previously, you also need to understand how to use two of the options to -`tar': `--file' (which takes an archive file as an argument) and -`--verbose'. (You are usually not _required_ to specify either of -these options when you run `tar', but they can be very useful in making -things more clear and helping you avoid errors.) - -* Menu: - -* file tutorial:: -* verbose tutorial:: -* help tutorial:: - - -File: tar.info, Node: file tutorial, Next: verbose tutorial, Up: Two Frequent Options - -The `--file' Option -------------------- - -`--file=ARCHIVE-NAME' -`-f ARCHIVE-NAME' - Specify the name of an archive file. - - You can specify an argument for the `--file=ARCHIVE-NAME' (`-f -ARCHIVE-NAME') option whenever you use `tar'; this option determines -the name of the archive file that `tar' will work on. - - If you don't specify this argument, then `tar' will examine the -environment variable `TAPE'. If it is set, its value will be used as -the archive name. Otherwise, `tar' will use the default archive, -determined at 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::. - - -File: tar.info, Node: verbose tutorial, Next: help tutorial, Prev: file tutorial, Up: Two Frequent Options - -The `--verbose' Option ----------------------- - -`--verbose' -`-v' - Show the files being worked on as `tar' is running. - - `--verbose' (`-v') shows details about the results of running `tar'. -This can be especially useful when the results might not be obvious. -For example, if you want to see the progress of `tar' as it writes -files into the archive, you can use the `--verbose' option. In the -beginning, you may find it useful to use `--verbose' at all times; when -you are more accustomed to `tar', you will likely want to use it at -certain times but not at others. We will use `--verbose' at times to -help make something clear, and we will give many examples both using -and not using `--verbose' to show the differences. - - Each instance of `--verbose' on the command line increases the -verbosity level by one, so if you need more details on the output, -specify it twice. - - When reading archives (`--list', `--extract', `--diff'), `tar' by -default prints only the names of the members being extracted. Using -`--verbose' will show a full, `ls' style member listing. - - In contrast, when writing archives (`--create', `--append', -`--update'), `tar' does not print file names by default. So, a single -`--verbose' option shows the file names being added to the archive, -while two `--verbose' options enable the full listing. - - For example, to create an archive in verbose mode: - - $ tar -cvf afiles.tar apple angst aspic - apple - angst - aspic - -Creating the same archive with the verbosity level 2 could give: - - $ tar -cvvf afiles.tar apple angst aspic - -rw-r--r-- gray/staff 62373 2006-06-09 12:06 apple - -rw-r--r-- gray/staff 11481 2006-06-09 12:06 angst - -rw-r--r-- gray/staff 23152 2006-06-09 12:06 aspic - -This works equally well using short or long forms of options. Using -long forms, you would simply write out the mnemonic form of the option -twice, like this: - - $ tar --create --verbose --verbose ... - -Note that you must double the hyphens properly each time. - - Later in the tutorial, we will give examples using -`--verbose --verbose'. - - The full output consists of six fields: - - * File type and permissions in symbolic form. These are displayed - in the same format as the first column of `ls -l' output (*note - format=verbose: (fileutils)What information is listed.). - - * Owner name and group separated by a slash character. If these - data are not available (for example, when listing a `v7' format - archive), numeric ID values are printed instead. - - * Size of the file, in bytes. - - * File modification date in ISO 8601 format. - - * File modification time. - - * File name. If the name contains any special characters (white - space, newlines, etc.) these are displayed in an unambiguous form - using so called "quoting style". For the detailed discussion of - available styles and on how to use them, see *note quoting - styles::. - - Depending on the file type, the name can be followed by some - additional information, described in the following table: - - `-> LINK-NAME' - The file or archive member is a "symbolic link" and LINK-NAME - is the name of file it links to. - - `link to LINK-NAME' - The file or archive member is a "hard link" and LINK-NAME is - the name of file it links to. - - `--Long Link--' - The archive member is an old GNU format long link. You will - normally not encounter this. - - `--Long Name--' - The archive member is an old GNU format long name. You will - normally not encounter this. - - `--Volume Header--' - The archive member is a GNU "volume header" (*note Tape - Files::). - - `--Continued at byte N--' - Encountered only at the beginning of a multi-volume archive - (*note Using Multiple Tapes::). This archive member is a - continuation from the previous volume. The number N gives the - offset where the original file was split. - - `unknown file type C' - An archive member of unknown type. C is the type character - from the archive header. If you encounter such a message, it - means that either your archive contains proprietary member - types GNU `tar' is not able to handle, or the archive is - corrupted. - - - For example, here is an archive listing containing most of the -special suffixes explained above: - - V--------- 0/0 1536 2006-06-09 13:07 MyVolume--Volume Header-- - -rw-r--r-- gray/staff 456783 2006-06-09 12:06 aspic--Continued at - byte 32456-- - -rw-r--r-- gray/staff 62373 2006-06-09 12:06 apple - lrwxrwxrwx gray/staff 0 2006-06-09 13:01 angst -> apple - -rw-r--r-- gray/staff 35793 2006-06-09 12:06 blues - hrw-r--r-- gray/staff 0 2006-06-09 12:06 music link to blues - - - -File: tar.info, Node: help tutorial, Prev: verbose tutorial, Up: Two Frequent Options - -Getting Help: Using the `--help' Option ---------------------------------------- - -`--help' - The `--help' option to `tar' prints out a very brief list of all - operations and option available for the current version of `tar' - available on your system. - - -File: tar.info, Node: create, Next: list, Prev: Two Frequent Options, Up: Tutorial - -2.6 How to Create Archives -========================== - - _(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:: - - -File: tar.info, Node: prepare for examples, Next: Creating the archive, Up: create - -2.6.1 Preparing a Practice Directory for Examples -------------------------------------------------- - -To follow along with this and future examples, create a new directory -called `practice' containing files called `blues', `folk' and `jazz'. -The files can contain any information you like: ideally, they should -contain information which relates to their names, and be of different -lengths. Our examples assume that `practice' is a subdirectory of your -home directory. - - Now `cd' to the directory named `practice'; `practice' is now your -"working directory". (_Please note_: Although the full file name of -this directory is `/HOMEDIR/practice', in our examples we will refer to -this directory as `practice'; the HOMEDIR is presumed. - - In general, you should check that the files to be archived exist -where you think they do (in the working directory) by running `ls'. -Because you just created the directory and the files and have changed to -that directory, you probably don't need to do that this time. - - It is very important to make sure there isn't already a file in the -working directory with the archive name you intend to use (in this case, -`collection.tar'), or that you don't care about its contents. Whenever -you use `create', `tar' will erase the current contents of the file -named by `--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME') if it exists. `tar' -will not tell you if you are about to overwrite an archive unless you -specify an option which does this (*note backup::, for the information -on how to do so). To add files to an existing archive, you need to use -a different option, such as `--append' (`-r'); see *note append:: for -information on how to do this. - - -File: tar.info, Node: Creating the archive, Next: create verbose, Prev: prepare for examples, Up: create - -2.6.2 Creating the Archive --------------------------- - -To place the files `blues', `folk', and `jazz' into an archive named -`collection.tar', use the following command: - - $ tar --create --file=collection.tar blues folk jazz - - The order of the arguments is not very important, _when using long -option forms_. 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::. - - -File: tar.info, Node: create verbose, Next: short create, Prev: Creating the archive, Up: create - -2.6.3 Running `--create' with `--verbose' ------------------------------------------ - -If you include the `--verbose' (`-v') option on the command line, `tar' -will list the files it is acting on as it is working. In verbose mode, -the `create' example above would appear as: - - $ tar --create --verbose --file=collection.tar blues folk jazz - blues - folk - jazz - - This example is just like the example we showed which did not use -`--verbose', except that `tar' generated the remaining lines . - - In the rest of the examples in this chapter, we will frequently use -`verbose' mode so we can show actions or `tar' responses that you would -otherwise not see, and which are important for you to understand. - - -File: tar.info, Node: short create, Next: create dir, Prev: create verbose, Up: create - -2.6.4 Short Forms with `create' -------------------------------- - -As we said before, the `--create' (`-c') operation is one of the most -basic uses of `tar', and you will use it countless times. Eventually, -you will probably want to use abbreviated (or "short") forms of -options. A full discussion of the three different forms that options -can take appears in *note Styles::; for now, here is what the previous -example (including the `--verbose' (`-v') option) looks like using -short option forms: - - $ tar -cvf collection.tar blues folk jazz - blues - folk - jazz - -As you can see, the system responds the same no matter whether you use -long or short option forms. - - One difference between using short and long option forms is that, -although the exact placement of arguments following options is no more -specific when using short forms, it is easier to become confused and -make a mistake when using short forms. For example, suppose you -attempted the above example in the following way: - - $ tar -cfv collection.tar blues folk jazz - -In this case, `tar' will make an archive file called `v', containing -the files `blues', `folk', and `jazz', because the `v' is the closest -"file name" to the `-f' option, and is thus taken to be the chosen -archive file name. `tar' will try to add a file called -`collection.tar' to the `v' archive file; if the file `collection.tar' -did not already exist, `tar' will report an error indicating that this -file does not exist. If the file `collection.tar' does already exist -(e.g., from a previous command you may have run), then `tar' will add -this file to the archive. Because the `-v' option did not get -registered, `tar' will not run under `verbose' mode, and will not -report its progress. - - The end result is that you may be quite confused about what happened, -and possibly overwrite a file. To illustrate this further, we will show -you how an example we showed previously would look using short forms. - - This example, - - $ tar 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. - - -File: tar.info, Node: create dir, Prev: short create, Up: create - -2.6.5 Archiving Directories ---------------------------- - -You can archive a directory by specifying its directory name as a file -name argument to `tar'. The files in the directory will be archived -relative to the working directory, and the directory will be re-created -along with its contents when the archive is extracted. - - To archive a directory, first move to its superior directory. If you -have followed the previous instructions in this tutorial, you should -type: - - $ cd .. - $ - -This will put you into the directory which contains `practice', i.e., -your home directory. Once in the superior directory, you can specify -the subdirectory, `practice', as a file name argument. To store -`practice' in the new archive file `music.tar', type: - - $ tar --create --verbose --file=music.tar practice - -`tar' should output: - - practice/ - practice/blues - practice/folk - practice/jazz - practice/collection.tar - - Note that the archive thus created is not in the subdirectory -`practice', but rather in the current working directory--the directory -from which `tar' was invoked. Before trying to archive a directory -from its superior directory, you should make sure you have write access -to the superior directory itself, not only the directory you are trying -archive with `tar'. For example, you will probably not be able to -store your home directory in an archive by invoking `tar' from the root -directory; *Note absolute::. (Note also that `collection.tar', the -original archive file, has itself been archived. `tar' will accept any -file as a file to be archived, regardless of its content. When -`music.tar' is extracted, the archive file `collection.tar' will be -re-written into the file system). - - If you give `tar' a command such as - - $ tar --create --file=foo.tar . - -`tar' will report `tar: ./foo.tar is the archive; not dumped'. This -happens because `tar' creates the archive `foo.tar' in the current -directory before putting any files into it. Then, when `tar' attempts -to add all the files in the directory `.' to the archive, it notices -that the file `./foo.tar' is the same as the archive `foo.tar', and -skips it. (It makes no sense to put an archive into itself.) GNU `tar' -will continue in this case, and create the archive normally, except for -the exclusion of that one file. (_Please note:_ Other implementations -of `tar' may not be so clever; they will enter an infinite loop when -this happens, so you should not depend on this behavior unless you are -certain you are running GNU `tar'. In general, it is wise to always -place the archive outside of the directory being dumped. - - -File: tar.info, Node: list, Next: extract, Prev: create, Up: Tutorial - -2.7 How to List Archives -======================== - -Frequently, you will find yourself wanting to determine exactly what a -particular archive contains. You can use the `--list' (`-t') operation -to get the member names as they currently appear in the archive, as -well as various attributes of the files at the time they were archived. -For example, 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:: - - -File: tar.info, Node: list dir, Up: list - -Listing the Contents of a Stored Directory ------------------------------------------- - -To get information about the contents of an archived directory, use the -directory name as a file name argument in conjunction with `--list' -(`-t'). To find out file attributes, include the `--verbose' (`-v') -option. - - For example, to find out about files in the directory `practice', in -the archive file `music.tar', type: - - $ tar --list --verbose --file=music.tar practice - - `tar' responds: - - drwxrwxrwx myself user 0 1990-05-31 21:49 practice/ - -rw-r--r-- myself user 42 1990-05-21 13:29 practice/blues - -rw-r--r-- myself user 62 1990-05-23 10:55 practice/folk - -rw-r--r-- myself user 40 1990-05-21 13:30 practice/jazz - -rw-r--r-- myself user 10240 1990-05-31 21:49 practice/collection.tar - - When you use a directory name as a file name argument, `tar' acts on -all the files (including sub-directories) in that directory. - - -File: tar.info, Node: extract, Next: going further, Prev: list, Up: Tutorial - -2.8 How to Extract Members from an Archive -========================================== - - _(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:: - - -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 - - -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. - - -File: tar.info, Node: extract dir, Next: extracting untrusted archives, Prev: extracting files, Up: extract - -2.8.3 Extracting Files that are Directories -------------------------------------------- - -Extracting directories which are members of an archive is similar to -extracting other files. The main difference to be aware of is that if -the extracted directory has the same name as any directory already in -the working directory, then files in the extracted directory will be -placed into the directory of the same name. Likewise, if there are -files in the pre-existing directory with the same names as the members -which you extract, the files from the extracted archive will replace -the files already in the working directory (and possible -subdirectories). This will happen regardless of whether or not the -files in the working directory were more recent than those extracted -(there exist, however, special options that alter this behavior *note -Writing::). - - However, if a file was stored with a directory name as part of its -file name, and that directory does not exist under the working -directory when the file is extracted, `tar' will create the directory. - - We can demonstrate how to use `--extract' to extract a directory -file with an example. Change to the `practice' directory if you -weren't there, and remove the files `folk' and `jazz'. Then, go back -to the parent directory and extract the archive `music.tar'. You may -either extract the entire archive, or you may extract only the files -you just deleted. To extract the entire archive, don't give any file -names as arguments after the archive name `music.tar'. To extract only -the files you deleted, use the following command: - - $ tar -xvf music.tar practice/folk practice/jazz - practice/folk - practice/jazz - -If you were to specify two `--verbose' (`-v') options, `tar' would have -displayed more detail about the extracted files, as shown in the -example below: - - $ tar -xvvf music.tar practice/folk practice/jazz - -rw-r--r-- me user 28 1996-10-18 16:31 practice/jazz - -rw-r--r-- me user 20 1996-09-23 16:44 practice/folk - -Because you created the directory with `practice' as part of the file -names of each of the files by archiving the `practice' directory as -`practice', you must give `practice' as part of the file names when you -extract those files from the archive. - - -File: tar.info, Node: extracting untrusted archives, Next: failing commands, Prev: extract dir, Up: extract - -2.8.4 Extracting Archives from Untrusted Sources ------------------------------------------------- - -Extracting files from archives can overwrite files that already exist. -If you receive an archive from an untrusted source, you should make a -new directory and extract into that directory, so that you don't have -to worry about the extraction overwriting one of your existing files. -For example, if `untrusted.tar' came from somewhere else on the -Internet, and you don't necessarily trust its contents, you can extract -it as follows: - - $ mkdir newdir - $ cd newdir - $ tar -xvf ../untrusted.tar - - It is also a good practice to examine contents of the archive before -extracting it, using `--list' (`-t') option, possibly combined with -`--verbose' (`-v'). - - -File: tar.info, Node: failing commands, Prev: extracting untrusted archives, Up: extract - -2.8.5 Commands That Will Fail ------------------------------ - -Here are some sample commands you might try which will not work, and why -they won't work. - - If you try to use this command, - - $ tar -xvf music.tar folk jazz - -you will get the following response: - - tar: folk: Not found in archive - tar: jazz: Not found in archive - $ - -This is because these files were not originally _in_ the parent -directory `..', where the archive is located; they were in the -`practice' directory, and their file names reflect this: - - $ tar -tvf music.tar - practice/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. - - -File: tar.info, Node: going further, Prev: extract, Up: Tutorial - -2.9 Going Further Ahead in this Manual -====================================== - - _(This message will disappear, once this node revised.)_ - - -File: tar.info, Node: tar invocation, Next: operations, Prev: Tutorial, Up: Top - -3 Invoking GNU `tar' -******************** - - _(This 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:: - - -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::). - - -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. - - -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 - - -File: tar.info, Node: Long Options, Next: Short Options, Up: Styles - -3.3.1 Long Option Style ------------------------ - -Each option has at least one "long" (or "mnemonic") name starting with -two dashes in a row, e.g., `--list'. The long names are more clear than -their corresponding short or old names. It sometimes happens that a -single long option has many different names which are synonymous, such -as `--compare' and `--diff'. In addition, long option names can be -given unique abbreviations. For example, `--cre' can be used in place -of `--create' because there is no other long option which begins with -`cre'. (One way to find this out is by trying it and seeing what -happens; if a particular abbreviation could represent more than one -option, `tar' will tell you that that abbreviation is ambiguous and -you'll know that that abbreviation won't work. You may also choose to -run `tar --help' to see a list of options. Be aware that if you run -`tar' with a unique abbreviation for the long name of an option you -didn't want to use, you are stuck; `tar' will perform the command as -ordered.) - - Long options are meant to be obvious and easy to remember, and their -meanings are generally easier to discern than those of their -corresponding short options (see below). For example: - - $ tar --create --verbose --blocking-factor=20 --file=/dev/rmt0 - -gives a fairly good set of hints about what the command does, even for -those not fully acquainted with `tar'. - - Long options which require arguments take those arguments -immediately following the option name. There are two ways of -specifying a mandatory argument. It can be separated from the option -name either by an equal sign, or by any amount of white space -characters. For example, the `--file' option (which tells the name of -the `tar' archive) is given a file such as `archive.tar' as argument by -using any of the following notations: `--file=archive.tar' or `--file -archive.tar'. - - In contrast, optional arguments must always be introduced using an -equal sign. For example, the `--backup' option takes an optional -argument specifying backup type. It must be used as -`--backup=BACKUP-TYPE'. - - -File: tar.info, Node: Short Options, Next: Old Options, Prev: Long Options, Up: Styles - -3.3.2 Short Option Style ------------------------- - -Most options also have a "short option" name. Short options start with -a single dash, and are followed by a single character, e.g., `-t' -(which is equivalent to `--list'). The forms are absolutely identical -in function; they are interchangeable. - - The short option names are faster to type than long option names. - - Short options which require arguments take their arguments -immediately following the option, usually separated by white space. It -is also possible to stick the argument right after the short option -name, using no intervening space. For example, you might write -`-f archive.tar' or `-farchive.tar' instead of using -`--file=archive.tar'. Both `--file=ARCHIVE-NAME' and `-f ARCHIVE-NAME' -denote the option which indicates a specific archive, here named -`archive.tar'. - - Short options which take optional arguments take their arguments -immediately following the option letter, _without any intervening white -space characters_. - - Short options' letters may be clumped together, but you are not -required to do this (as compared to old options; see below). When -short options are clumped as a set, use one (single) dash for them all, -e.g., ``tar' -cvf'. Only the last option in such a set is allowed to -have an argument(1). - - When the options are separated, the argument for each option which -requires an argument directly follows that option, as is usual for Unix -programs. For example: - - $ tar -c -v -b 20 -f /dev/rmt0 - - If you reorder short options' locations, be sure to move any -arguments that belong to them. If you do not move the arguments -properly, you may end up overwriting files. - - ---------- Footnotes ---------- - - (1) Clustering many options, the last of which has an argument, is a -rather opaque way to write options. Some wonder if GNU `getopt' should -not even be made helpful enough for considering such usages as invalid. - - -File: tar.info, Node: Old Options, Next: Mixing, Prev: Short Options, Up: Styles - -3.3.3 Old Option Style ----------------------- - - _(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. - - -File: tar.info, Node: Mixing, Prev: Old Options, Up: Styles - -3.3.4 Mixing Option Styles --------------------------- - -All three styles may be intermixed in a single `tar' command, so long -as the rules for each style are fully respected(1). Old style options -and either of the modern styles of options may be mixed within a single -`tar' command. However, old style options must be introduced as the -first arguments only, following the rule for old options (old options -must appear directly after the `tar' command and some white space). -Modern options may be given only after all arguments to the old options -have been collected. If this rule is not respected, a modern option -might be falsely interpreted as the value of the argument to one of the -old style options. - - For example, all the following commands are wholly equivalent, and -illustrate the many combinations and orderings of option styles. - - tar --create --file=archive.tar - tar --create -f archive.tar - tar --create -farchive.tar - tar --file=archive.tar --create - tar --file=archive.tar -c - tar -c --file=archive.tar - tar -c -f archive.tar - tar -c -farchive.tar - tar -cf archive.tar - tar -cfarchive.tar - tar -f archive.tar --create - tar -f archive.tar -c - tar -farchive.tar --create - tar -farchive.tar -c - tar c --file=archive.tar - tar c -f archive.tar - tar c -farchive.tar - tar cf archive.tar - tar f archive.tar --create - tar f archive.tar -c - tar fc archive.tar - - On the other hand, the following commands are _not_ equivalent to -the previous set: - - tar -f -c archive.tar - tar -fc archive.tar - tar -fcarchive.tar - tar -farchive.tarc - tar cfarchive.tar - -These last examples mean something completely different from what the -user intended (judging based on the example in the previous set which -uses long options, whose intent is therefore very clear). The first -four specify that the `tar' archive would be a file named `-c', `c', -`carchive.tar' or `archive.tarc', respectively. The first two examples -also specify a single non-option, NAME argument having the value -`archive.tar'. The last example contains only old style option letters -(repeating option `c' twice), not all of which are meaningful (eg., `.', -`h', or `i'), with no argument value. - - ---------- Footnotes ---------- - - (1) Before GNU `tar' version 1.11.6, a bug prevented intermixing old -style options with long options in some cases. - - -File: tar.info, Node: All Options, Next: help, Prev: Styles, Up: tar invocation - -3.4 All `tar' Options -===================== - -The coming manual sections contain an alphabetical listing of all `tar' -operations and options, with brief descriptions and cross references to -more in-depth explanations in the body of the manual. They also -contain an alphabetically arranged table of the short option forms with -their corresponding long option. You can use this table as a reference -for deciphering `tar' commands in scripts. - -* Menu: - -* Operation Summary:: -* Option Summary:: -* Short Option Summary:: - - -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::. - - - -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. - - -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::. - - -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 . - 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' - - -File: tar.info, Node: defaults, Next: verbose, Prev: help, Up: tar invocation - -3.6 Obtaining GNU `tar' default values -====================================== - -GNU `tar' has some predefined defaults that are used when you do not -explicitly specify another values. To obtain a list of such defaults, -use `--show-defaults' option. This will output the values in the form -of `tar' command line options: - - tar --show-defaults - --format=gnu -f- -b20 --quoting-style=escape - --rmt-command=/etc/rmt --rsh-command=/usr/bin/rsh - -Notice, that this option outputs only one line. The example output -above has been split to fit page boundaries. - -The above output shows that this version of GNU `tar' defaults to using -`gnu' archive format (*note Formats::), it uses standard output as the -archive, if no `--file' option has been given (*note file tutorial::), -the default blocking factor is 20 (*note Blocking Factor::). It also -shows the default locations where `tar' will look for `rmt' and `rsh' -binaries. - - -File: tar.info, Node: verbose, Next: checkpoints, Prev: defaults, Up: tar invocation - -3.7 Checking `tar' progress -=========================== - -Typically, `tar' performs most operations without reporting any -information to the user except error messages. When using `tar' with -many options, particularly ones with complicated or -difficult-to-predict behavior, it is possible to make serious mistakes. -`tar' provides several options that make observing `tar' easier. These -options cause `tar' to print information as it progresses in its job, -and you might want to use them just for being more careful about what -is going on, or merely for entertaining yourself. If you have -encountered a problem when operating on an archive, however, you may -need more information than just an error message in order to solve the -problem. The following options can be helpful diagnostic tools. - - Normally, the `--list' (`-t') command to list an archive prints just -the file names (one per line) and the other commands are silent. When -used with most operations, the `--verbose' (`-v') option causes `tar' -to print the name of each file or archive member as it is processed. -This and the other options which make `tar' print status information -can be useful in monitoring `tar'. - - With `--create' or `--extract', `--verbose' used once just prints -the names of the files or members as they are processed. Using it -twice causes `tar' to print a longer listing (*Note verbose member -listing::, for the description) for each member. Since `--list' -already prints the names of the members, `--verbose' used once with -`--list' causes `tar' to print an `ls -l' type listing of the files in -the archive. The following examples both extract members with long -list output: - - $ tar --extract --file=archive.tar --verbose --verbose - $ tar xvvf archive.tar - - Verbose output appears on the standard output except when an archive -is being written to the standard output, as with `tar --create --file=- ---verbose' (`tar 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. - - -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. - - -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. - - -File: tar.info, Node: operations, Next: Backups, Prev: tar invocation, Up: Top - -4 GNU `tar' Operations -********************** - -* Menu: - -* Basic tar:: -* Advanced tar:: -* create options:: -* extract options:: -* backup:: -* Applications:: -* looking ahead:: - - -File: tar.info, Node: Basic tar, Next: Advanced tar, Up: operations - -4.1 Basic GNU `tar' Operations -============================== - -The basic `tar' operations, `--create' (`-c'), `--list' (`-t') and -`--extract' (`--get', `-x'), are currently presented and described in -the tutorial chapter of this manual. This section provides some -complementary notes for these operations. - -`--create' -`-c' - Creating an empty archive would have some kind of elegance. One - can initialize an empty archive and later use `--append' (`-r') - for adding all members. Some applications would not welcome - making an exception in the way of adding the first archive member. - On the other hand, many people reported that it is dangerously - too easy for `tar' to destroy a magnetic tape with an empty - archive(1). The two most common errors are: - - 1. Mistakingly using `create' instead of `extract', when the - intent was to extract the full contents of an archive. This - error is likely: keys `c' and `x' are right next to each - other on the QWERTY keyboard. Instead of being unpacked, the - archive then gets wholly destroyed. When users speak about - "exploding" an archive, they usually mean something else :-). - - 2. Forgetting the argument to `file', when the intent was to - create an archive with a single file in it. This error is - likely because a tired user can easily add the `f' key to the - cluster of option letters, by the mere force of habit, - without realizing the full consequence of doing so. The - usual consequence is that the single file, which was meant to - be saved, is rather destroyed. - - So, recognizing the likelihood and the catastrophic nature of these - errors, GNU `tar' now takes some distance from elegance, and - cowardly refuses to create an archive when `--create' option is - given, there are no arguments besides options, and `--files-from' - (`-T') option is _not_ used. To get around the cautiousness of - GNU `tar' and nevertheless create an archive with nothing in it, - one may still use, as the value for the `--files-from' option, a - file with no names in it, as shown in the following commands: - - tar --create --file=empty-archive.tar --files-from=/dev/null - tar 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. - - -File: tar.info, Node: Advanced tar, Next: create options, Prev: Basic tar, Up: operations - -4.2 Advanced GNU `tar' Operations -================================= - -Now that you have learned the basics of using GNU `tar', you may want -to learn about further ways in which `tar' can help you. - - This chapter presents five, more advanced operations which you -probably won't use on a daily basis, but which serve more specialized -functions. We also explain the different styles of options and why you -might want to use one or another, or a combination of them in your `tar' -commands. Additionally, this chapter includes options which allow you -to define the output from `tar' more carefully, and provide help and -error correction in special circumstances. - -* Menu: - -* Operations:: -* append:: -* update:: -* concatenate:: -* delete:: -* compare:: - - -File: tar.info, Node: Operations, Next: append, Up: Advanced tar - -4.2.1 The Five Advanced `tar' Operations ----------------------------------------- - - _(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. - - -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 - - -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 - - -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. - - -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:: - - -File: tar.info, Node: how to update, Up: update - -4.2.3.1 How to Update an Archive Using `--update' -................................................. - -You must use file name arguments with the `--update' (`-u') operation. -If you don't specify any files, `tar' won't act on any files and won't -tell you that it didn't do anything (which may end up confusing you). - - To see the `--update' option at work, create a new file, -`classical', in your practice directory, and some extra text to the -file `blues', using any text editor. Then invoke `tar' with the -`update' operation and the `--verbose' (`-v') option specified, using -the names of all the files in the practice directory as file name -arguments: - - $ tar --update -v -f collection.tar blues folk rock classical - blues - classical - $ - -Because we have specified verbose mode, `tar' prints out the names of -the files it is working on, which in this case are the names of the -files that needed to be updated. If you run `tar --list' and look at -the archive, you will see `blues' and `classical' at its end. There -will be a total of two versions of the member `blues'; the one at the -end will be newer and larger, since you added text before updating it. - - (The reason `tar' does not overwrite the older file when updating it -is because writing to the middle of a section of tape is a difficult -process. Tapes are not designed to go backward. *Note Media::, for -more information about tapes. - - `--update' (`-u') is not suitable for performing backups for two -reasons: it does not change directory content entries, and it lengthens -the archive every time it is used. The GNU `tar' options intended -specifically for backups are more efficient. If you need to run -backups, please consult *note Backups::. - - -File: tar.info, Node: concatenate, Next: delete, Prev: update, Up: Advanced tar - -4.2.4 Combining Archives with `--concatenate' ---------------------------------------------- - -Sometimes it may be convenient to add a second archive onto the end of -an archive rather than adding individual files to the archive. To add -one or more archives to the end of another archive, you should use the -`--concatenate' (`--catenate', `-A') operation. - - To use `--concatenate', give the first archive with `--file' option -and name the rest of archives to be concatenated on the command line. -The members, and their member names, will be copied verbatim from those -archives to the first one. (1) The new, concatenated archive will be -called by the same name as the one given with the `--file' option. As -usual, if you omit `--file', `tar' will use the value of the environment -variable `TAPE', or, if this has not been set, the default archive name. - - To demonstrate how `--concatenate' works, create two small archives -called `bluesrock.tar' and `folkjazz.tar', using the relevant files -from `practice': - - $ tar -cvf bluesrock.tar blues rock - blues - rock - $ tar -cvf folkjazz.tar folk jazz - folk - jazz - -If you like, You can run `tar --list' to make sure the archives contain -what they are supposed to: - - $ tar -tvf bluesrock.tar - -rw-r--r-- melissa user 105 1997-01-21 19:42 blues - -rw-r--r-- melissa user 33 1997-01-20 15:34 rock - $ tar -tvf jazzfolk.tar - -rw-r--r-- melissa user 20 1996-09-23 16:44 folk - -rw-r--r-- melissa user 65 1997-01-30 14:15 jazz - - We can concatenate these two archives with `tar': - - $ cd .. - $ tar --concatenate --file=bluesrock.tar jazzfolk.tar - - If you now list the contents of the `bluesrock.tar', you will see -that now it also contains the archive members of `jazzfolk.tar': - - $ tar --list --file=bluesrock.tar - blues - rock - folk - jazz - - When you use `--concatenate', the source and target archives must -already exist and must have been created using compatible format -parameters. Notice, that `tar' does not check whether the archives it -concatenates have compatible formats, it does not even check if the -files are really tar archives. - - Like `--append' (`-r'), this operation cannot be performed on some -tape drives, due to deficiencies in the formats those tape drives use. - - It may seem more intuitive to you to want or try to use `cat' to -concatenate two archives instead of using the `--concatenate' -operation; after all, `cat' is the utility for combining files. - - However, `tar' archives incorporate an end-of-file marker which must -be removed if the concatenated archives are to be read properly as one -archive. `--concatenate' removes the end-of-archive marker from the -target archive before each new archive is appended. If you use `cat' -to combine the archives, the result will not be a valid `tar' format -archive. If you need to retrieve files from an archive that was added -to using the `cat' utility, use the `--ignore-zeros' (`-i') option. -*Note Ignore Zeros::, for further information on dealing with archives -improperly combined using the `cat' shell utility. - - ---------- Footnotes ---------- - - (1) This can cause multiple members to have the same name, for -information on how this affects reading the archive, *note multiple::. - - -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'. - - -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::. - - -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:: - - -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. - - -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. - - -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 - - -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:: - - -File: tar.info, Node: read full records, Next: Ignore Zeros, Up: Reading - -Reading Full Records -.................... - -`--read-full-records' - -`-B' - Use in conjunction with `--extract' (`--get', `-x') to read an - archive which contains incomplete records, or one which has a - blocking factor less than the one specified. - - -File: tar.info, Node: Ignore Zeros, Prev: read full records, Up: Reading - -Ignoring Blocks of Zeros -........................ - -Normally, `tar' stops reading when it encounters a block of zeros -between file entries (which usually indicates the end of the archive). -`--ignore-zeros' (`-i') allows `tar' to completely read an archive -which contains a block of zeros before the end (i.e., a damaged -archive, or one that was created by concatenating several archives -together). - - The `--ignore-zeros' (`-i') option is turned off by default because -many versions of `tar' write garbage after the end-of-archive entry, -since that part of the media is never supposed to be read. GNU `tar' -does not write after the end of an archive, but seeks to maintain -compatibility among archiving utilities. - -`--ignore-zeros' -`-i' - To ignore blocks of zeros (i.e., end-of-archive entries) which may - be encountered while reading an archive. Use in conjunction with - `--extract' or `--list'. - - -File: tar.info, Node: Writing, Next: Scarce, Prev: Reading, Up: extract options - -4.4.2 Changing How `tar' Writes Files -------------------------------------- - - _(This message will disappear, once this node revised.)_ - -* Menu: - -* Dealing with Old Files:: -* Overwrite Old Files:: -* Keep Old Files:: -* Keep Newer Files:: -* Unlink First:: -* Recursive Unlink:: -* Data Modification Times:: -* Setting Access Permissions:: -* Directory Modification Times and Permissions:: -* Writing to Standard Output:: -* Writing to an External Program:: -* remove files:: - - -File: tar.info, Node: Dealing with Old Files, Next: Overwrite Old Files, Up: Writing - -Options Controlling the Overwriting of Existing Files -..................................................... - -When extracting files, if `tar' discovers that the extracted file -already exists, it normally replaces the file by removing it before -extracting it, to prevent confusion in the presence of hard or symbolic -links. (If the existing file is a symbolic link, it is removed, not -followed.) However, if a directory cannot be removed because it is -nonempty, `tar' normally overwrites its metadata (ownership, -permission, etc.). The `--overwrite-dir' option enables this default -behavior. To be more cautious and preserve the metadata of such a -directory, use the `--no-overwrite-dir' option. - - To be even more cautious and prevent existing files from being -replaced, use the `--keep-old-files' (`-k') option. It causes `tar' to -refuse to replace or update a file that already exists, i.e., a file -with the same name as an archive member prevents extraction of that -archive member. Instead, it reports an error. - - To be more aggressive about altering existing files, use the -`--overwrite' option. It causes `tar' to overwrite existing files and -to follow existing symbolic links when extracting. - - Some people argue that GNU `tar' should not hesitate to overwrite -files with other files when extracting. When extracting a `tar' -archive, they expect to see a faithful copy of the state of the file -system when the archive was created. It is debatable that this would -always be a proper behavior. For example, suppose one has an archive -in which `usr/local' is a link to `usr/local2'. Since then, maybe the -site removed the link and renamed the whole hierarchy from -`/usr/local2' to `/usr/local'. Such things happen all the time. I -guess it would not be welcome at all that GNU `tar' removes the whole -hierarchy just to make room for the link to be reinstated (unless it -_also_ simultaneously restores the full `/usr/local2', of course!) GNU -`tar' is indeed able to remove a whole hierarchy to reestablish a -symbolic link, for example, but _only if_ `--recursive-unlink' is -specified to allow this behavior. In any case, single files are -silently removed. - - Finally, the `--unlink-first' (`-U') option can improve performance -in some cases by causing `tar' to remove files unconditionally before -extracting them. - - -File: tar.info, Node: Overwrite Old Files, Next: Keep Old Files, Prev: Dealing with Old Files, Up: Writing - -Overwrite Old Files -................... - -`--overwrite' - Overwrite existing files and directory metadata when extracting - files from an archive. - - This causes `tar' to write extracted files into the file system - without regard to the files already on the system; i.e., files - with the same names as archive members are overwritten when the - archive is extracted. It also causes `tar' to extract the - ownership, permissions, and time stamps onto any preexisting files - or directories. If the name of a corresponding file name is a - symbolic link, the file pointed to by the symbolic link will be - overwritten instead of the symbolic link itself (if this is - possible). Moreover, special devices, empty directories and even - symbolic links are automatically removed if they are in the way of - extraction. - - Be careful when using the `--overwrite' option, particularly when - combined with the `--absolute-names' (`-P') option, as this - combination can change the contents, ownership or permissions of - any file on your system. Also, many systems do not take kindly to - overwriting files that are currently being executed. - -`--overwrite-dir' - Overwrite the metadata of directories when extracting files from an - archive, but remove other files before extracting. - - -File: tar.info, Node: Keep Old Files, Next: Keep Newer Files, Prev: Overwrite Old Files, Up: Writing - -Keep Old Files -.............. - -`--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. - - -File: tar.info, Node: Keep Newer Files, Next: Unlink First, Prev: Keep Old Files, Up: Writing - -Keep Newer Files -................ - -`--keep-newer-files' - Do not replace existing files that are newer than their archive - copies. This option is meaningless with `--list' (`-t'). - - -File: tar.info, Node: Unlink First, Next: Recursive Unlink, Prev: Keep Newer Files, Up: Writing - -Unlink First -............ - -`--unlink-first' -`-U' - Remove files before extracting over them. This can make `tar' run - a bit faster if you know in advance that the extracted files all - need to be removed. Normally this option slows `tar' down - slightly, so it is disabled by default. - - -File: tar.info, Node: Recursive Unlink, Next: Data Modification Times, Prev: Unlink First, Up: Writing - -Recursive Unlink -................ - -`--recursive-unlink' - When this option is specified, try removing files and directory - hierarchies before extracting over them. _This is a dangerous - option!_ - - If you specify the `--recursive-unlink' option, `tar' removes -_anything_ that keeps you from extracting a file as far as current -permissions will allow it. This could include removal of the contents -of a full directory hierarchy. - - -File: tar.info, Node: Data Modification Times, Next: Setting Access Permissions, Prev: Recursive Unlink, Up: Writing - -Setting Data Modification Times -............................... - -Normally, `tar' sets the data modification times of extracted files to -the corresponding times recorded for the files in the archive, but -limits the permissions of extracted files by the current `umask' -setting. - - To set the data modification times of extracted files to the time -when the files were extracted, use the `--touch' (`-m') option in -conjunction with `--extract' (`--get', `-x'). - -`--touch' -`-m' - Sets the data modification time of extracted archive members to - the time they were extracted, not the time recorded for them in - the archive. Use in conjunction with `--extract' (`--get', `-x'). - - -File: tar.info, Node: Setting Access Permissions, Next: Directory Modification Times and Permissions, Prev: Data Modification Times, Up: Writing - -Setting Access Permissions -.......................... - -To set the modes (access permissions) of extracted files to those -recorded for those files in the archive, use `--same-permissions' in -conjunction with the `--extract' (`--get', `-x') operation. - -`--preserve-permissions' -`--same-permissions' -`-p' - Set modes of extracted archive members to those recorded in the - archive, instead of current umask settings. Use in conjunction - with `--extract' (`--get', `-x'). - - -File: tar.info, Node: Directory Modification Times and Permissions, Next: Writing to Standard Output, Prev: Setting Access Permissions, Up: Writing - -Directory Modification Times and Permissions -............................................ - -After successfully extracting a file member, GNU `tar' normally -restores its permissions and modification times, as described in the -previous sections. This cannot be done for directories, because after -extracting a directory `tar' will almost certainly extract files into -that directory and this will cause the directory modification time to -be updated. Moreover, restoring that directory permissions may not -permit file creation within it. Thus, restoring directory permissions -and modification times must be delayed at least until all files have -been extracted into that directory. GNU `tar' restores directories -using the following approach. - - The extracted directories are created with the mode specified in the -archive, as modified by the umask of the user, which gives sufficient -permissions to allow file creation. The meta-information about the -directory is recorded in the temporary list of directories. When -preparing to extract next archive member, GNU `tar' checks if the -directory prefix of this file contains the remembered directory. If it -does not, the program assumes that all files have been extracted into -that directory, restores its modification time and permissions and -removes its entry from the internal list. This approach allows to -correctly restore directory meta-information in the majority of cases, -while keeping memory requirements sufficiently small. It is based on -the fact, that most `tar' archives use the predefined order of members: -first the directory, then all the files and subdirectories in that -directory. - - However, this is not always true. The most important exception are -incremental archives (*note Incremental Dumps::). The member order in -an incremental archive is reversed: first all directory members are -stored, followed by other (non-directory) members. So, when extracting -from incremental archives, GNU `tar' alters the above procedure. It -remembers all restored directories, and restores their meta-data only -after the entire archive has been processed. Notice, that you do not -need to specify any special options for that, as GNU `tar' -automatically detects archives in incremental format. - - There may be cases, when such processing is required for normal -archives too. Consider the following example: - - $ tar --no-recursion -cvf archive \ - foo foo/file1 bar bar/file foo/file2 - foo/ - foo/file1 - bar/ - bar/file - foo/file2 - - During the normal operation, after encountering `bar' GNU `tar' will -assume that all files from the directory `foo' were already extracted -and will therefore restore its timestamp and permission bits. However, -after extracting `foo/file2' the directory timestamp will be offset -again. - - To correctly restore directory meta-information in such cases, use -`delay-directory-restore' command line option: - -`--delay-directory-restore' - Delays restoring of the modification times and permissions of - extracted directories until the end of extraction. This way, - correct meta-information is restored even if the archive has - unusual member ordering. - -`--no-delay-directory-restore' - Cancel the effect of the previous `--delay-directory-restore'. - Use this option if you have used `--delay-directory-restore' in - `TAR_OPTIONS' variable (*note TAR_OPTIONS::) and wish to - temporarily disable it. - - -File: tar.info, Node: Writing to Standard Output, Next: Writing to an External Program, Prev: Directory Modification Times and Permissions, Up: Writing - -Writing to Standard Output -.......................... - -To write the extracted files to the standard output, instead of -creating the files on the file system, use `--to-stdout' (`-O') in -conjunction with `--extract' (`--get', `-x'). This option is useful if -you are extracting files to send them through a pipe, and do not need to -preserve them in the file system. If you extract multiple members, -they appear on standard output concatenated, in the order they are -found in the archive. - -`--to-stdout' -`-O' - Writes files to the standard output. Use only in conjunction with - `--extract' (`--get', `-x'). When this option is used, instead of - creating the files specified, `tar' writes the contents of the - files extracted to its standard output. This may be useful if you - are only extracting the files in order to send them through a - pipe. This option is meaningless with `--list' (`-t'). - - This can be useful, for example, if you have a tar archive containing -a big file and don't want to store the file on disk before processing -it. You can use a command like this: - - tar -xOzf foo.tgz bigfile | process - - or even like this if you want to process the concatenation of the -files: - - tar -xOzf foo.tgz bigfile1 bigfile2 | process - - However, `--to-command' may be more convenient for use with multiple -files. See the next section. - - -File: tar.info, Node: Writing to an External Program, Next: remove files, Prev: Writing to Standard Output, Up: Writing - -Writing to an External Program -.............................. - -You can instruct `tar' to send the contents of each extracted file to -the standard input of an external program: - -`--to-command=COMMAND' - Extract files and pipe their contents to the standard input of - COMMAND. When this option is used, instead of creating the files - specified, `tar' invokes COMMAND and pipes the contents of the - files to its standard output. 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. - - -File: tar.info, Node: remove files, Prev: Writing to an External Program, Up: Writing - -Removing Files -.............. - -`--remove-files' - Remove files after adding them to the archive. - - -File: tar.info, Node: Scarce, Prev: Writing, Up: extract options - -4.4.3 Coping with Scarce Resources ----------------------------------- - - _(This message will disappear, once this node revised.)_ - -* Menu: - -* Starting File:: -* Same Order:: - - -File: tar.info, Node: Starting File, Next: Same Order, Up: Scarce - -Starting File -............. - -`--starting-file=NAME' -`-K NAME' - Starts an operation in the middle of an archive. Use in - conjunction with `--extract' (`--get', `-x') or `--list' (`-t'). - - If a previous attempt to extract files failed due to lack of disk -space, you can use `--starting-file=NAME' (`-K NAME') to start -extracting only after member NAME of the archive. This assumes, of -course, that there is now free space, or that you are now extracting -into a different file system. (You could also choose to suspend `tar', -remove unnecessary files from the file system, and then restart the -same `tar' operation. In this case, `--starting-file' is not necessary. -*Note Incremental Dumps::, *Note interactive::, and *note exclude::.) - - -File: tar.info, Node: Same Order, Prev: Starting File, Up: Scarce - -Same Order -.......... - -`--same-order' -`--preserve-order' -`-s' - To process large lists of file names on machines with small - amounts of memory. Use in conjunction with `--compare' (`--diff', - `-d'), `--list' (`-t') or `--extract' (`--get', `-x'). - - The `--same-order' (`--preserve-order', `-s') option tells `tar' -that the list of file names to be listed or extracted is sorted in the -same order as the files in the archive. This allows a large list of -names to be used, even on a small machine that would not otherwise be -able to hold all the names in memory at the same time. Such a sorted -list can easily be created by running `tar -t' on the archive and -editing its output. - - This option is probably never needed on modern computer systems. - - -File: tar.info, Node: backup, Next: Applications, Prev: extract options, Up: operations - -4.5 Backup options -================== - -GNU `tar' offers options for making backups of files before writing new -versions. These options control the details of these backups. They -may apply to the archive itself before it is created or rewritten, as -well as individual extracted members. Other GNU programs (`cp', -`install', `ln', and `mv', for example) offer similar options. - - Backup options may prove unexpectedly useful when extracting archives -containing many members having identical name, or when extracting -archives on systems having file name limitations, making different -members appear 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. - - - -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. - - -File: tar.info, Node: looking ahead, Prev: Applications, Up: operations - -4.7 Looking Ahead: The Rest of this Manual -========================================== - -You have now seen how to use all eight of the operations available to -`tar', and a number of the possible options. The next chapter explains -how to choose and change file and archive names, how to use files to -store names of other files which you can then call as arguments to -`tar' (this can help you save time if you expect to archive the same -list of files a number of times), and so forth. - - If there are too many files to conveniently list on the command line, -you can list the names in a file, and `tar' will read that file. *Note -files::. - - There are various ways of causing `tar' to skip over some files, and -not archive them. *Note Choosing::. - - -File: tar.info, Node: Backups, Next: Choosing, Prev: operations, Up: Top - -5 Performing Backups and Restoring Files -**************************************** - - _(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 - - -File: tar.info, Node: Full Dumps, Next: Incremental Dumps, Up: Backups - -5.1 Using `tar' to Perform Full Dumps -===================================== - - _(This message will disappear, once this node revised.)_ - -Full dumps should only be made when no other people or programs are -modifying files in the file system. If files are modified while `tar' -is making the backup, they may not be stored properly in the archive, -in which case you won't be able to restore them if you have to. (Files -not being modified are written with no trouble, and do not corrupt the -entire archive.) - - You will want to use the `--label=ARCHIVE-LABEL' (`-V -ARCHIVE-LABEL') option to give the archive a volume label, so you can -tell what this archive is even if the label falls off the tape, or -anything like that. - - Unless the file system you are dumping is guaranteed to fit on one -volume, you will need to use the `--multi-volume' (`-M') option. Make -sure you have enough tapes on hand to complete the backup. - - If you want to dump each file system separately you will need to use -the `--one-file-system' option to prevent `tar' from crossing file -system boundaries when storing (sub)directories. - - The `--incremental' (`-G') (*note Incremental Dumps::) option is not -needed, since this is a complete copy of everything in the file system, -and a full restore from this backup would only be done onto a completely -empty disk. - - Unless you are in a hurry, and trust the `tar' program (and your -tapes), it is a good idea to use the `--verify' (`-W') option, to make -sure your files really made it onto the dump properly. This will also -detect cases where the file was modified while (or just after) it was -being archived. Not all media (notably cartridge tapes) are capable of -being verified, unfortunately. - - -File: tar.info, Node: Incremental Dumps, Next: Backup Levels, Prev: Full Dumps, Up: Backups - -5.2 Using `tar' to Perform Incremental Dumps -============================================ - -"Incremental backup" is a special form of GNU `tar' archive that stores -additional metadata so that exact state of the file system can be -restored when extracting the archive. - - GNU `tar' currently offers two options for handling incremental -backups: `--listed-incremental=SNAPSHOT-FILE' (`-g SNAPSHOT-FILE') and -`--incremental' (`-G'). - - The option `--listed-incremental' instructs tar to operate on an -incremental archive with additional metadata stored in a standalone -file, called a "snapshot file". The purpose of this file is to help -determine which files have been changed, added or deleted since the -last backup, so that the next incremental backup will contain only -modified files. The name of the snapshot file is given as an argument -to the option: - -`--listed-incremental=FILE' -`-g FILE' - Handle incremental backups with snapshot data in FILE. - - To create an incremental backup, you would use -`--listed-incremental' together with `--create' (*note create::). For -example: - - $ tar --create \ - --file=archive.1.tar \ - --listed-incremental=/var/log/usr.snar \ - /usr - - This will create in `archive.1.tar' an incremental backup of the -`/usr' file system, storing additional metadata in the file -`/var/log/usr.snar'. If this file does not exist, it will be created. -The created archive will then be a "level 0 backup"; please see the -next section for more on backup levels. - - Otherwise, if the file `/var/log/usr.snar' exists, it determines -which files are modified. In this case only these files will be stored -in the archive. Suppose, for example, that after running the above -command, you delete file `/usr/doc/old' and create directory -`/usr/local/db' with the following contents: - - $ ls /usr/local/db - /usr/local/db/data - /usr/local/db/index - - Some time later you create another incremental backup. You will -then see: - - $ tar --create \ - --file=archive.2.tar \ - --listed-incremental=/var/log/usr.snar \ - /usr - tar: usr/local/db: Directory is new - usr/local/db/ - usr/local/db/data - usr/local/db/index - -The created archive `archive.2.tar' will contain only these three -members. This archive is called a "level 1 backup". Notice that -`/var/log/usr.snar' will be updated with the new data, so if you plan -to create more `level 1' backups, it is necessary to create a working -copy of the snapshot file before running `tar'. The above example will -then be modified as follows: - - $ cp /var/log/usr.snar /var/log/usr.snar-1 - $ tar --create \ - --file=archive.2.tar \ - --listed-incremental=/var/log/usr.snar-1 \ - /usr - - 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 - - -File: tar.info, Node: Backup Levels, Next: Backup Parameters, Prev: Incremental Dumps, Up: Backups - -5.3 Levels of Backups -===================== - -An archive containing all the files in the file system is called a -"full backup" or "full dump". You could insure your data by creating a -full dump every day. This strategy, however, would waste a substantial -amount of archive media and user time, as unchanged files are daily -re-archived. - - It is more efficient to do a full dump only occasionally. To back up -files between full dumps, you can use "incremental dumps". A "level -one" dump archives all the files that have changed since the last full -dump. - - A typical dump strategy would be to perform a full dump once a week, -and a level one dump once a day. This means some versions of files -will in fact be archived more than once, but this dump strategy makes -it possible to restore a file system to within one day of accuracy by -only extracting two archives--the last weekly (full) dump and the last -daily (level one) dump. The only information lost would be in files -changed or created since the last daily backup. (Doing dumps more than -once a day is usually not worth the trouble). - - GNU `tar' comes with scripts you can use to do full and level-one -(actually, even level-two and so on) dumps. Using scripts (shell -programs) to perform backups and restoration is a convenient and -reliable alternative to typing out file name lists and `tar' commands -by hand. - - Before you use these scripts, you need to edit the file -`backup-specs', which specifies parameters used by the backup scripts -and by the restore script. This file is usually located in -`/etc/backup' directory. *Note Backup Parameters::, for its detailed -description. Once the backup parameters are set, you can perform -backups or restoration by running the appropriate script. - - The name of the backup script is `backup'. The name of the restore -script is `restore'. The following sections describe their use in -detail. - - _Please Note:_ The backup and restoration scripts are designed to be -used together. While it is possible to restore files by hand from an -archive which was created using a backup script, and to create an -archive by hand which could then be extracted using the restore script, -it is easier to use the scripts. *Note Incremental Dumps::, before -making such an attempt. - - -File: tar.info, Node: Backup Parameters, Next: Scripted Backups, Prev: Backup Levels, Up: Backups - -5.4 Setting Parameters for Backups and Restoration -================================================== - -The file `backup-specs' specifies backup parameters for the backup and -restoration scripts provided with `tar'. You must edit `backup-specs' -to fit your system configuration and schedule before using these -scripts. - - Syntactically, `backup-specs' is a shell script, containing mainly -variable assignments. However, any valid shell construct is allowed in -this file. Particularly, you may wish to define functions within that -script (e.g., see `RESTORE_BEGIN' below). For more information about -shell script syntax, please refer to the definition of the Shell -Command Language -(http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html#ta -g_02). See also *note Bash Features: (bashref)Top. - - The shell variables controlling behavior of `backup' and `restore' -are described in the following subsections. - -* Menu: - -* General-Purpose Variables:: -* Magnetic Tape Control:: -* User Hooks:: -* backup-specs example:: An Example Text of `Backup-specs' - - -File: tar.info, Node: General-Purpose Variables, Next: Magnetic Tape Control, Up: Backup Parameters - -5.4.1 General-Purpose Variables -------------------------------- - - -- Backup variable: ADMINISTRATOR - The user name of the backup administrator. `Backup' scripts sends - a backup report to this address. - - -- Backup variable: BACKUP_HOUR - The hour at which the backups are done. This can be a number from - 0 to 23, or the time specification in form HOURS:MINUTES, or the - string `now'. - - This variable is used by `backup'. Its value may be overridden - using `--time' option (*note Scripted Backups::). - - -- Backup variable: TAPE_FILE - The device `tar' writes the archive to. If TAPE_FILE is a remote - archive (*note remote-dev::), backup script will suppose that your - `mt' is able to access remote devices. If RSH (*note RSH::) is - set, `--rsh-command' option will be added to invocations of `mt'. - - -- Backup variable: BLOCKING - The blocking factor `tar' will use when writing the dump archive. - *Note Blocking Factor::. - - -- Backup variable: BACKUP_DIRS - A list of file systems to be dumped (for `backup'), or restored - (for `restore'). You can include any directory name in the list - -- subdirectories on that file system will be included, regardless - of how they may look to other networked machines. Subdirectories - on other file systems will be ignored. - - The host name specifies which host to run `tar' on, and should - normally be the host that actually contains the file system. - However, the host machine must have GNU `tar' installed, and must - be able to access the directory containing the backup scripts and - their support files using the same file name that is used on the - machine where the scripts are run (i.e., what `pwd' will print - when in that directory on that machine). If the host that contains - the file system does not have this capability, you can specify - another host as long as it can access the file system through NFS. - - If the list of file systems is very long you may wish to put it in - a separate file. This file is usually named `/etc/backup/dirs', - but this name may be overridden in `backup-specs' using `DIRLIST' - variable. - - -- Backup variable: DIRLIST - The name of the file that contains a list of file systems to backup - or restore. By default it is `/etc/backup/dirs'. - - -- Backup variable: BACKUP_FILES - A list of individual files to be dumped (for `backup'), or restored - (for `restore'). These should be accessible from the machine on - which the backup script is run. - - If the list of 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. - - -File: tar.info, Node: Magnetic Tape Control, Next: User Hooks, Prev: General-Purpose Variables, Up: Backup Parameters - -5.4.2 Magnetic Tape Control ---------------------------- - -Backup scripts access tape device using special "hook functions". -These functions take a single argument - the name of the tape device. -Their names are kept in the following variables: - - -- Backup variable: MT_BEGIN - The name of "begin" function. This function is called before - accessing the drive. By default it retensions the tape: - - MT_BEGIN=mt_begin - - mt_begin() { - mt -f "$1" retension - } - - -- Backup variable: MT_REWIND - The name of "rewind" function. The default definition is as - follows: - - MT_REWIND=mt_rewind - - mt_rewind() { - mt -f "$1" rewind - } - - - -- Backup variable: MT_OFFLINE - The name of the function switching the tape off line. By default - it is defined as follows: - - MT_OFFLINE=mt_offline - - mt_offline() { - mt -f "$1" offl - } - - -- Backup variable: MT_STATUS - The name of the function used to obtain the status of the archive - device, including error count. Default definition: - - MT_STATUS=mt_status - - mt_status() { - mt -f "$1" status - } - - -File: tar.info, Node: User Hooks, Next: backup-specs example, Prev: Magnetic Tape Control, Up: Backup Parameters - -5.4.3 User Hooks ----------------- - -"User hooks" are shell functions executed before and after each `tar' -invocation. Thus, there are "backup hooks", which are executed before -and after dumping each file system, and "restore hooks", executed -before and after restoring a file system. Each user hook is a shell -function taking four arguments: - - -- User Hook Function: hook LEVEL HOST FS FSNAME - Its arguments are: - - LEVEL - Current backup or restore level. - - HOST - Name or IP address of the host machine being dumped or - restored. - - FS - Full file name of the file system being dumped or restored. - - FSNAME - File system name with directory separators replaced with - colons. This is useful, e.g., for creating unique files. - - Following variables keep the names of user hook functions - - -- Backup variable: DUMP_BEGIN - Dump begin function. It is executed before dumping the file - system. - - -- Backup variable: DUMP_END - Executed after dumping the file system. - - -- Backup variable: RESTORE_BEGIN - Executed before restoring the file system. - - -- Backup variable: RESTORE_END - Executed after restoring the file system. - - -File: tar.info, Node: backup-specs example, Prev: User Hooks, Up: Backup Parameters - -5.4.4 An Example Text of `Backup-specs' ---------------------------------------- - -The following is an example of `backup-specs': - - # site-specific parameters for file system backup. - - ADMINISTRATOR=friedman - BACKUP_HOUR=1 - TAPE_FILE=/dev/nrsmt0 - - # Use `ssh' instead of the less secure `rsh' - RSH=/usr/bin/ssh - RSH_COMMAND=/usr/bin/ssh - - # Override MT_STATUS function: - my_status() { - mts -t $TAPE_FILE - } - MT_STATUS=my_status - - # Disable MT_OFFLINE function - MT_OFFLINE=: - - BLOCKING=124 - BACKUP_DIRS=" - albert:/fs/fsf - apple-gunkies:/gd - albert:/fs/gd2 - albert:/fs/gp - geech:/usr/jla - churchy:/usr/roland - albert:/ - albert:/usr - apple-gunkies:/ - apple-gunkies:/usr - gnu:/hack - gnu:/u - apple-gunkies:/com/mailer/gnu - apple-gunkies:/com/archive/gnu" - - BACKUP_FILES="/com/mailer/aliases /com/mailer/league*[a-z]" - - -File: tar.info, Node: Scripted Backups, Next: Scripted Restoration, Prev: Backup Parameters, Up: Backups - -5.5 Using the Backup Scripts -============================ - -The syntax for running a backup script is: - - backup --level=LEVEL --time=TIME - - The `level' option requests the dump level. Thus, to produce a full -dump, specify `--level=0' (this is the default, so `--level' may be -omitted if its value is `0'). (1) - - The `--time' option determines when should the backup be run. TIME -may take three forms: - -HH:MM - The dump must be run at HH hours MM minutes. - -HH - The dump must be run at HH hours - -now - The dump must be run immediately. - - You should start a script with a tape or disk mounted. Once you -start a script, it prompts you for new tapes or disks as it needs them. -Media volumes don't have to correspond to archive files -- a -multi-volume archive can be started in the middle of a tape that -already contains the end of another multi-volume archive. The -`restore' script prompts for media by its archive volume, so to avoid -an error message you should keep track of which tape (or disk) contains -which volume of the archive (*note Scripted Restoration::). - - The backup scripts write two files on the file system. The first is -a record file in `/etc/tar-backup/', which is used by the scripts to -store and retrieve information about which files were dumped. This -file is not meant to be read by humans, and should not be deleted by -them. *Note Snapshot Files::, for a more detailed explanation of this -file. - - The second file is a log file containing the names of the file -systems and files dumped, what time the backup was made, and any error -messages that were generated, as well as how much space was left in the -media volume after the last volume of the archive was written. You -should check this log file after every backup. The file name is -`log-MM-DD-YYYY-level-N', where MM-DD-YYYY represents current date, and -N represents current dump level number. - - The script also prints the name of each system being dumped to the -standard output. - - Following is the full list of options accepted by `backup' script: - -`-l LEVEL' -`--level=LEVEL' - Do backup level LEVEL (default 0). - -`-f' -`--force' - Force backup even if today's log file already exists. - -`-v[LEVEL]' -`--verbose[=LEVEL]' - Set verbosity level. The higher the level is, the more debugging - information will be output during execution. Default LEVEL is - 100, which means the highest debugging level. - -`-t START-TIME' -`--time=START-TIME' - Wait till TIME, then do backup. - -`-h' -`--help' - Display short help message and exit. - -`-V' -`--version' - Display information about the program's name, version, origin and - legal status, all on standard output, and then exit successfully. - - ---------- Footnotes ---------- - - (1) For backward compatibility, the `backup' will also try to deduce -the requested dump level from the name of the script itself. If the -name consists of a string `level-' followed by a single decimal digit, -that digit is taken as the dump level number. Thus, you may create a -link from `backup' to `level-1' and then run `level-1' whenever you -need to create a level one dump. - - -File: tar.info, Node: Scripted Restoration, Prev: Scripted Backups, Up: Backups - -5.6 Using the Restore Script -============================ - -To restore files that were archived using a scripted backup, use the -`restore' script. Its usage is quite straightforward. In the simplest -form, invoke `restore --all', it will then restore all the file systems -and files specified in `backup-specs' (*note BACKUP_DIRS: -General-Purpose Variables.). - - You may select the file systems (and/or files) to restore by giving -`restore' list of "patterns" in its command line. For example, running - - restore 'albert:*' - -will restore all file systems on the machine `albert'. A more -complicated example: - - restore 'albert:*' '*:/var' - -This command will restore all file systems on the machine `albert' as -well as `/var' file system on all machines. - - By default `restore' will start restoring files from the lowest -available dump level (usually zero) and will continue through all -available dump levels. There may be situations where such a thorough -restore is not necessary. For example, you may wish to restore only -files from the recent level one backup. To do so, use `--level' -option, as shown in the example below: - - restore --level=1 - - The full list of options accepted by `restore' follows: - -`-a' -`--all' - Restore all file systems and files specified in `backup-specs' - -`-l LEVEL' -`--level=LEVEL' - Start restoring from the given backup level, instead of the - default 0. - -`-v[LEVEL]' -`--verbose[=LEVEL]' - Set verbosity level. The higher the level is, the more debugging - information will be output during execution. Default LEVEL is - 100, which means the highest debugging level. - -`-h' -`--help' - Display short help message and exit. - -`-V' -`--version' - Display information about the program's name, version, origin and - legal status, all on standard output, and then exit successfully. - - You should start the restore script with the media containing the -first volume of the archive mounted. The script will prompt for other -volumes as they are needed. If the archive is on tape, you don't need -to rewind the tape to to its beginning--if the tape head is positioned -past the beginning of the archive, the script will rewind the tape as -needed. *Note Tape Positioning::, for a discussion of tape positioning. - - *Warning:* The script will delete files from the active file - system if they were not in the file system when the archive was - made. - - *Note Incremental Dumps::, for an explanation of how the script makes -that determination. - - -File: tar.info, Node: Choosing, Next: Date input formats, Prev: Backups, Up: Top - -6 Choosing Files and Names for `tar' -************************************ - - _(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 - - -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. - - -File: tar.info, Node: Selecting Archive Members, Next: files, Prev: file, Up: Choosing - -6.2 Selecting Archive Members -============================= - -"File Name arguments" specify which files in the file system `tar' -operates on, when creating or adding to an archive, or which archive -members `tar' operates on, when reading or deleting from an archive. -*Note Operations::. - - To specify file names, you can include them as the last arguments on -the command line, as follows: - tar OPERATION [OPTION1 OPTION2 ...] [FILE NAME-1 FILE NAME-2 ...] - - If a file name begins with dash (`-'), precede it with `--add-file' -option to prevent it from being treated as an option. - - By default GNU `tar' attempts to "unquote" each file or member name, -replacing "escape sequences" according to the following table: - -Escape Replaced with ------------------------------------------------------------ -\a Audible bell (ASCII 7) -\b Backspace (ASCII 8) -\f Form feed (ASCII 12) -\n New line (ASCII 10) -\r Carriage return (ASCII 13) -\t Horizontal tabulation (ASCII 9) -\v Vertical tabulation (ASCII 11) -\? ASCII 127 -\N ASCII N (N should be an octal number - of up to 3 digits) - - A backslash followed by any other symbol is retained. - - This default behavior is controlled by the following command line -option: - -`--unquote' - Enable unquoting input file or member names (default). - -`--no-unquote' - Disable unquoting input file or member names. - - If you specify a directory name as a file name argument, all the -files in that directory are operated on by `tar'. - - If you do not specify files, `tar' behavior differs depending on the -operation mode as described below: - - When `tar' is invoked with `--create' (`-c'), `tar' will stop -immediately, reporting the following: - - $ tar cf a.tar - tar: Cowardly refusing to create an empty archive - Try `tar --help' or `tar --usage' for more information. - - If you specify either `--list' (`-t') or `--extract' (`--get', -`-x'), `tar' operates on all the archive members in the archive. - - If run with `--diff' option, tar will compare the archive with the -contents of the current working directory. - - If you specify any other operation, `tar' does nothing. - - By default, `tar' takes file names from the command line. However, -there are other ways to specify file or member names, or to modify the -manner in which `tar' selects the files or members upon which to -operate. In general, these methods work both for specifying the names -of files and archive members. - - -File: tar.info, Node: files, Next: exclude, Prev: Selecting Archive Members, Up: Choosing - -6.3 Reading Names from a File -============================= - -Instead of giving the names of files or archive members on the command -line, you can put the names into a file, and then use the -`--files-from=FILE-OF-NAMES' (`-T FILE-OF-NAMES') option to `tar'. -Give the name of the file which contains the list of files to include -as the argument to `--files-from'. In the list, the file names should -be separated by newlines. You will frequently use this option when you -have generated the list of files to archive with the `find' utility. - -`--files-from=FILE-NAME' -`-T FILE-NAME' - Get names to extract or create from file FILE-NAME. - - If you give a single dash as a file name for `--files-from', (i.e., -you specify either `--files-from=-' or `-T -'), then the file names are -read from standard input. - - Unless you are running `tar' with `--create', you 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. - - -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 - - -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:: - - -File: tar.info, Node: problems with exclude, Up: exclude - -Problems with Using the `exclude' Options ------------------------------------------ - -Some users find `exclude' options confusing. Here are some common -pitfalls: - - * The main operating mode of `tar' does not act on a file name - explicitly listed on the command line, if one of its file name - components is excluded. In the example above, if you create an - archive and exclude files that end with `*.o', but explicitly name - the file `dir.o/foo' after all the options have been listed, - `dir.o/foo' will be excluded from the archive. - - * You can sometimes confuse the meanings of `--exclude' and - `--exclude-from'. Be careful: use `--exclude' when files to be - excluded are given as a pattern on the command line. Use - `--exclude-from' to introduce the name of a file which contains a - list of patterns, one per line; each of these patterns can exclude - zero, one, or many files. - - * When you use `--exclude=PATTERN', be sure to quote the PATTERN - parameter, so GNU `tar' sees wildcard characters like `*'. If you - do not do this, the shell might expand the `*' itself using files - at hand, so `tar' might receive a list of files instead of one - pattern, or none at all, making the command somewhat illegal. - This might not correspond to what you want. - - For example, write: - - $ tar -c -f ARCHIVE.TAR --exclude '*.o' DIRECTORY - - rather than: - - # _Wrong!_ - $ tar -c -f ARCHIVE.TAR --exclude *.o DIRECTORY - - * You must use use shell syntax, or globbing, rather than `regexp' - syntax, when using exclude options in `tar'. If you try to use - `regexp' syntax to describe files to be excluded, your command - might fail. - - * In earlier versions of `tar', what is now the `--exclude-from' - option was called `--exclude' instead. Now, `--exclude' applies - to patterns listed on the command line and `--exclude-from' - applies to patterns listed in a file. - - - -File: tar.info, Node: wildcards, Next: quoting styles, Prev: exclude, Up: Choosing - -6.5 Wildcards Patterns and Matching -=================================== - -"Globbing" is the operation by which "wildcard" characters, `*' or `?' -for example, are replaced and expanded into all existing files matching -the given pattern. GNU `tar' can use wildcard patterns for matching -(or globbing) archive members when extracting from or listing an -archive. Wildcard patterns are also used for verifying volume labels -of `tar' archives. This section has the purpose of explaining wildcard -syntax for `tar'. - - A PATTERN should be written according to shell syntax, using wildcard -characters to effect globbing. Most characters in the pattern stand -for themselves in the matched string, and case is significant: `a' will -match only `a', and not `A'. The character `?' in the pattern matches -any single character in the matched string. The character `*' in the -pattern matches zero, one, or more single characters in the matched -string. The character `\' says to take the following character of the -pattern _literally_; it is useful when one needs to match the `?', `*', -`[' or `\' characters, themselves. - - The character `[', up to the matching `]', introduces a character -class. A "character class" is a list of acceptable characters for the -next single character of the matched string. For example, `[abcde]' -would match any of the first five letters of the alphabet. Note that -within a character class, all of the "special characters" listed above -other than `\' lose their special meaning; for example, `[-\\[*?]]' -would match any of the characters, `-', `\', `[', `*', `?', or `]'. -(Due to parsing constraints, the characters `-' and `]' must either -come _first_ or _last_ in a character class.) - - If the first character of the class after the opening `[' is `!' or -`^', then the meaning of the class is reversed. Rather than listing -character to match, it lists those characters which are _forbidden_ as -the next single character of the matched string. - - Other characters of the class stand for themselves. The special -construction `[A-E]', using an hyphen between two letters, is meant to -represent all characters between A and E, inclusive. - - Periods (`.') or forward slashes (`/') are not considered special -for wildcard matches. However, if a pattern completely matches a -directory prefix of a matched string, then it matches the full matched -string: thus, excluding a directory also excludes all the files beneath -it. - -* Menu: - -* controlling pattern-matching:: - - -File: tar.info, Node: controlling pattern-matching, Up: wildcards - -Controlling Pattern-Matching ----------------------------- - -For the purposes of this section, we call "exclusion members" all -member names obtained while processing `--exclude' and `--exclude-from' -options, and "inclusion members" those member names that were given in -the command line or read from the file specified with `--files-from' -option. - - These two pairs of member lists are used in the following operations: -`--diff', `--extract', `--list', `--update'. - - There are no inclusion members in create mode (`--create' and -`--append'), since in this mode the names obtained from the command -line refer to _files_, not archive members. - - By default, inclusion members are compared with archive members -literally (1) and exclusion members are treated as globbing patterns. -For example: - - $ tar tf foo.tar - a.c - b.c - a.txt - [remarks] - # Member names are used verbatim: - $ tar -xf foo.tar -v '[remarks]' - [remarks] - # Exclude member names are globbed: - $ tar -xf foo.tar -v --exclude '*.c' - a.txt - [remarks] - - This behavior can be altered by using the following options: - -`--wildcards' - Treat all member names as wildcards. - -`--no-wildcards' - Treat all member names as literal strings. - - Thus, to extract files whose names end in `.c', you can use: - - $ tar -xf foo.tar -v --wildcards '*.c' - a.c - b.c - -Notice quoting of the pattern to prevent the shell from interpreting it. - - The effect of `--wildcards' option is canceled by `--no-wildcards'. -This can be used to pass part of the command line arguments verbatim -and other part as globbing patterns. For example, the following -invocation: - - $ tar -xf foo.tar --wildcards '*.txt' --no-wildcards '[remarks]' - -instructs `tar' to extract from `foo.tar' all files whose names end in -`.txt' and the file named `[remarks]'. - - Normally, a pattern matches a name if an initial subsequence of the -name's components matches the pattern, where `*', `?', and `[...]' are -the usual shell wildcards, `\' escapes wildcards, and wildcards can -match `/'. - - Other than optionally stripping leading `/' from names (*note -absolute::), patterns and names are used as-is. For example, trailing -`/' is not trimmed from a user-specified name before deciding whether -to exclude it. - - However, this matching procedure can be altered by the options listed -below. These options accumulate. For example: - - --ignore-case --exclude='makefile' --no-ignore-case ---exclude='readme' - -ignores case when excluding `makefile', but not when excluding `readme'. - -`--anchored' -`--no-anchored' - If anchored, a pattern must match an initial subsequence of the - name's components. Otherwise, the pattern can match any - subsequence. Default is `--no-anchored' for exclusion members and - `--anchored' inclusion members. - -`--ignore-case' -`--no-ignore-case' - When ignoring case, upper-case patterns match lower-case names and - vice versa. When not ignoring case (the default), matching is - case-sensitive. - -`--wildcards-match-slash' -`--no-wildcards-match-slash' - When wildcards match slash (the default for exclusion members), a - wildcard like `*' in the pattern can match a `/' in the name. - Otherwise, `/' is matched only by `/'. - - - The `--recursion' and `--no-recursion' options (*note recurse::) -also affect how member patterns are interpreted. If recursion is in -effect, a pattern matches a name if it matches any of the name's parent -directories. - - The following table summarizes pattern-matching default values: - -Members Default settings --------------------------------------------------------------------------- -Inclusion `--no-wildcards --anchored - --no-wildcards-match-slash' -Exclusion `--wildcards --no-anchored - --wildcards-match-slash' - - ---------- Footnotes ---------- - - (1) Notice that earlier GNU `tar' versions used globbing for -inclusion members, which contradicted to UNIX98 specification and was -not documented. *Note Changes::, for more information on this and other -changes. - - -File: tar.info, Node: quoting styles, Next: transform, Prev: wildcards, Up: Choosing - -6.6 Quoting Member Names -======================== - -When displaying member names, `tar' takes care to avoid ambiguities -caused by certain characters. This is called "name quoting". The -characters in question are: - - * Non-printable control characters: - - Character ASCII Character name - --------------------------------------------------------------- - \a 7 Audible bell - \b 8 Backspace - \f 12 Form feed - \n 10 New line - \r 13 Carriage return - \t 9 Horizontal tabulation - \v 11 Vertical tabulation - - * Space (ASCII 32) - - * Single and double quotes (`'' and `"') - - * Backslash (`\') - - The exact way `tar' uses to quote these characters depends on the -"quoting style". The default quoting style, called "escape" (see -below), uses backslash notation to represent control characters, space -and backslash. Using this quoting style, control characters are -represented as listed in column `Character' in the above table, a space -is printed as `\ ' and a backslash as `\\'. - - GNU `tar' offers seven distinct quoting styles, which can be selected -using `--quoting-style' option: - -`--quoting-style=STYLE' - Sets quoting style. Valid values for STYLE argument are: literal, - shell, shell-always, c, escape, locale, clocale. - - These styles are described in detail below. To illustrate their -effect, we will use an imaginary tar archive `arch.tar' containing the -following members: - - # 1. Contains horizontal tabulation character. - a tab - # 2. Contains newline character - a - newline - # 3. Contains a space - a space - # 4. Contains double quotes - a"double"quote - # 5. Contains single quotes - a'single'quote - # 6. Contains a backslash character: - a\backslash - - Here is how usual `ls' command would have listed them, if they had -existed in the current working directory: - - $ ls - a\ttab - a\nnewline - a\ space - a"double"quote - a'single'quote - a\\backslash - - Quoting styles: - -`literal' - No quoting, display each character as is: - - $ tar tf arch.tar --quoting-style=literal - ./ - ./a space - ./a'single'quote - ./a"double"quote - ./a\backslash - ./a tab - ./a - newline - -`shell' - Display characters the same way Bourne shell does: control - characters, except `\t' and `\n', are printed using backslash - escapes, `\t' and `\n' are printed as is, and a single quote is - printed as `\''. If a name contains any quoted characters, it is - enclosed in single quotes. In particular, if a name contains - single quotes, it is printed as several single-quoted strings: - - $ tar tf arch.tar --quoting-style=shell - ./ - './a space' - './a'\''single'\''quote' - './a"double"quote' - './a\backslash' - './a tab' - './a - newline' - -`shell-always' - Same as `shell', but the names are always enclosed in single - quotes: - - $ tar tf arch.tar --quoting-style=shell-always - './' - './a space' - './a'\''single'\''quote' - './a"double"quote' - './a\backslash' - './a tab' - './a - newline' - -`c' - Use the notation of the C programming language. All names are - enclosed in double quotes. Control characters are quoted using - backslash notations, double quotes are represented as `\"', - backslash characters are represented as `\\'. Single quotes and - spaces are not quoted: - - $ tar tf arch.tar --quoting-style=c - "./" - "./a space" - "./a'single'quote" - "./a\"double\"quote" - "./a\\backslash" - "./a\ttab" - "./a\nnewline" - -`escape' - Control characters are printed using backslash notation, a space is - printed as `\ ' and a backslash as `\\'. This is the default - quoting style, unless it was changed when configured the package. - - $ tar tf arch.tar --quoting-style=escape - ./ - ./a space - ./a'single'quote - ./a"double"quote - ./a\\backslash - ./a\ttab - ./a\nnewline - -`locale' - Control characters, single quote and backslash are printed using - backslash notation. All names are quoted using left and right - quotation marks, appropriate to the current locale. If it does not - define quotation marks, use ``' as left and `'' as right quotation - marks. Any occurrences of the right quotation mark in a name are - escaped with `\', for example: - - For example: - - $ tar tf arch.tar --quoting-style=locale - `./' - `./a space' - `./a\'single\'quote' - `./a"double"quote' - `./a\\backslash' - `./a\ttab' - `./a\nnewline' - -`clocale' - Same as `locale', but `"' is used for both left and right - quotation marks, if not provided by the currently selected locale: - - $ tar tf arch.tar --quoting-style=clocale - "./" - "./a space" - "./a'single'quote" - "./a\"double\"quote" - "./a\\backslash" - "./a\ttab" - "./a\nnewline" - - You can specify which characters should be quoted in addition to -those implied by the current quoting style: - -`--quote-chars=STRING' - Always quote characters from STRING, even if the selected quoting - style would not quote them. - - For example, using `escape' quoting (compare with the usual escape -listing above): - - $ tar tf arch.tar --quoting-style=escape --quote-chars=' "' - ./ - ./a\ space - ./a'single'quote - ./a\"double\"quote - ./a\\backslash - ./a\ttab - ./a\nnewline - - To disable quoting of such additional characters, use the following -option: - -`--no-quote-chars=STRING' - Remove characters listed in STRING from the list of quoted - characters set by the previous `--quote-chars' option. - - This option is particularly useful if you have added `--quote-chars' -to your `TAR_OPTIONS' (*note TAR_OPTIONS::) and wish to disable it for -the current invocation. - - Note, that `--no-quote-chars' does _not_ disable those characters -that are quoted by default in the selected quoting style. - - -File: tar.info, Node: transform, Next: after, Prev: quoting styles, Up: Choosing - -6.7 Modifying File and Member Names -=================================== - -`Tar' archives contain detailed information about files stored in them -and full file names are part of that information. When storing 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/,' - - -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. - - -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'. - - -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 - - -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. - - -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. - - -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. - - -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. - - -File: tar.info, Node: Calendar date items, Next: Time of day items, Prev: General date syntax, Up: Date input formats - -7.2 Calendar date items -======================= - -A "calendar date item" specifies a day of the year. It is specified -differently, depending on whether the month is specified numerically or -literally. All these strings specify the same calendar date: - - 1972-09-24 # ISO 8601. - 72-9-24 # Assume 19xx for 69 through 99, - # 20xx for 00 through 68. - 72-09-24 # Leading zeros are ignored. - 9/24/72 # Common U.S. writing. - 24 September 1972 - 24 Sept 72 # September has a special abbreviation. - 24 Sep 72 # Three-letter abbreviations always allowed. - Sep 24, 1972 - 24-sep-72 - 24sep72 - - The year can also be omitted. In this case, the last specified year -is used, or the current year if none. For example: - - 9/24 - sep 24 - - Here are the rules. - - For numeric months, the ISO 8601 format `YEAR-MONTH-DAY' is allowed, -where YEAR is any positive number, MONTH is a number between 01 and 12, -and DAY is a number between 01 and 31. A leading zero must be present -if a number is less than ten. If YEAR is 68 or smaller, then 2000 is -added to it; otherwise, if YEAR is less than 100, then 1900 is added to -it. The construct `MONTH/DAY/YEAR', popular in the United States, is -accepted. Also `MONTH/DAY', omitting the year. - - Literal months may be spelled out in full: `January', `February', -`March', `April', `May', `June', `July', `August', `September', -`October', `November' or `December'. Literal months may be abbreviated -to their first three letters, possibly followed by an abbreviating dot. -It is also permitted to write `Sept' instead of `September'. - - When months are written literally, the calendar date may be given as -any of the following: - - DAY MONTH YEAR - DAY MONTH - MONTH DAY YEAR - DAY-MONTH-YEAR - - Or, omitting the year: - - MONTH DAY - - -File: tar.info, Node: Time of day items, Next: Time zone items, Prev: Calendar date items, Up: Date input formats - -7.3 Time of day items -===================== - -A "time of day item" in date strings specifies the time on a given day. -Here are some examples, all of which represent the same time: - - 20:02:00.000000 - 20:02 - 8:02pm - 20:02-0500 # In EST (U.S. Eastern Standard Time). - - More generally, the time of day may be given as -`HOUR:MINUTE:SECOND', where HOUR is a number between 0 and 23, MINUTE -is a number between 0 and 59, and SECOND is a number between 0 and 59 -possibly followed by `.' or `,' and a fraction containing one or more -digits. Alternatively, `:SECOND' can be omitted, in which case it is -taken to be zero. On the rare hosts that support leap seconds, SECOND -may be 60. - - If the time is followed by `am' or `pm' (or `a.m.' or `p.m.'), HOUR -is restricted to run from 1 to 12, and `:MINUTE' may be omitted (taken -to be zero). `am' indicates the first half of the day, `pm' indicates -the second half of the day. In this notation, 12 is the predecessor of -1: midnight is `12am' while noon is `12pm'. (This is the zero-oriented -interpretation of `12am' and `12pm', as opposed to the old tradition -derived from Latin which uses `12m' for noon and `12pm' for midnight.) - - The time may alternatively be followed by a time zone correction, -expressed as `SHHMM', where S is `+' or `-', HH is a number of zone -hours and MM is a number of zone minutes. 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. - - -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::). - - -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. - - -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. - - -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. - - -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. - - -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. - - -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 -() 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 () and -Jim Berets () 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 -() from the `getdate.y' source code, and then -edited by K. Berry (). - - -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' - - -File: tar.info, Node: Compression, Next: Attributes, Up: Formats - -8.1 Using Less Space through Compression -======================================== - -* Menu: - -* gzip:: Creating and Reading Compressed Archives -* sparse:: Archiving Sparse Files - - -File: tar.info, Node: gzip, Next: sparse, Up: Compression - -8.1.1 Creating and Reading Compressed Archives ----------------------------------------------- - -GNU `tar' is able to create and read compressed archives. It supports -`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. - diff --git a/doc/tar.info-2 b/doc/tar.info-2 deleted file mode 100644 index bd7e2b3..0000000 --- a/doc/tar.info-2 +++ /dev/null @@ -1,5226 +0,0 @@ -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 - - -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'. - - -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'. - - - -File: tar.info, Node: Portability, Next: cpio, Prev: Attributes, Up: Formats - -8.3 Making `tar' Archives More Portable -======================================= - -Creating a `tar' archive on a particular system that is meant to be -useful later on many other machines and with other versions of `tar' is -more challenging than you might think. `tar' archive formats have been -evolving since the first versions of Unix. Many such formats are -around, and are not always compatible with each other. This section -discusses a few problems, and gives some advice about making `tar' -archives more portable. - - One golden rule is simplicity. For example, limit your `tar' -archives to contain only regular files and directories, avoiding other -kind of special files. Do not attempt to save sparse files or -contiguous files as such. Let's discuss a few more problems, in turn. - -* Menu: - -* Portable Names:: Portable Names -* dereference:: Symbolic Links -* hard links:: Hard Links -* old:: Old V7 Archives -* ustar:: Ustar Archives -* gnu:: GNU and old GNU format archives. -* posix:: POSIX archives -* Checksumming:: Checksumming Problems -* Large or Negative Values:: Large files, negative time stamps, etc. -* Other Tars:: How to Extract GNU-Specific Data Using - Other `tar' Implementations - - -File: tar.info, Node: Portable Names, Next: dereference, Up: Portability - -8.3.1 Portable Names --------------------- - -Use portable file and member names. A name is portable if it contains -only ASCII letters and digits, `/', `.', `_', and `-'; it cannot be -empty, start with `-' or `//', or contain `/-'. Avoid deep directory -nesting. For portability to old Unix hosts, limit your file name -components to 14 characters or less. - - If you intend to have your `tar' archives to be read under MSDOS, -you should not rely on case distinction for file names, and you might -use the GNU `doschk' program for helping you further diagnosing illegal -MSDOS names, which are even more limited than System V's. - - -File: tar.info, Node: dereference, Next: hard links, Prev: Portable Names, Up: Portability - -8.3.2 Symbolic Links --------------------- - -Normally, when `tar' archives a symbolic link, it writes a block to the -archive naming the target of the link. In that way, the `tar' archive -is a faithful record of the file system contents. `--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. - - -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. - - -File: tar.info, Node: old, Next: ustar, Prev: hard links, Up: Portability - -8.3.4 Old V7 Archives ---------------------- - -Certain old versions of `tar' cannot handle additional information -recorded by newer `tar' programs. To create an archive in V7 format -(not ANSI), which can be read by these old versions, specify the -`--format=v7' option in conjunction with the `--create' (`-c') (`tar' -also accepts `--portability' or `--old-archive' for this option). When -you specify it, `tar' leaves out information about directories, pipes, -fifos, contiguous files, and device files, and specifies file ownership -by group and user IDs instead of group and user names. - - When updating an archive, do not use `--format=v7' unless the -archive was created using this option. - - In most cases, a _new_ format archive can be read by an _old_ `tar' -program without serious trouble, so this option should seldom be -needed. On the other hand, most modern `tar's are able to read old -format archives, so it might be safer for you to always use -`--format=v7' for your distributions. Notice, however, that `ustar' -format is a better alternative, as it is free from many of `v7''s -drawbacks. - - -File: tar.info, Node: ustar, Next: gnu, Prev: old, Up: Portability - -8.3.5 Ustar Archive Format --------------------------- - -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'). - - -File: tar.info, Node: gnu, Next: posix, Prev: ustar, Up: Portability - -8.3.6 GNU and old GNU `tar' format ----------------------------------- - -GNU `tar' was based on an early draft of the POSIX 1003.1 `ustar' -standard. GNU extensions to `tar', such as the support for file names -longer than 100 characters, use portions of the `tar' header record -which were specified in that POSIX draft as unused. Subsequent changes -in POSIX have allocated the same parts of the header record for other -purposes. As a result, GNU `tar' format is incompatible with the -current POSIX specification, and with `tar' programs that follow it. - - In the majority of cases, `tar' will be configured to create this -format by default. This will change in future releases, since we plan -to make `POSIX' format the default. - - To force creation a GNU `tar' archive, use option `--format=gnu'. - - -File: tar.info, Node: posix, Next: Checksumming, Prev: gnu, Up: Portability - -8.3.7 GNU `tar' and POSIX `tar' -------------------------------- - -Starting from version 1.14 GNU `tar' features full support for -POSIX.1-2001 archives. - - A POSIX conformant archive will be created if `tar' was given -`--format=posix' (`--format=pax') option. No special option is -required to read and extract from a POSIX archive. - -* Menu: - -* PAX keywords:: Controlling Extended Header Keywords. - - -File: tar.info, Node: PAX keywords, Up: posix - -8.3.7.1 Controlling Extended Header Keywords -............................................ - -`--pax-option=KEYWORD-LIST' - Handle keywords in PAX extended headers. This option is - equivalent to `-o' option of the `pax' utility. - - KEYWORD-LIST is a comma-separated list of keyword options, each -keyword option taking one of the following forms: - -`delete=PATTERN' - When used with one of archive-creation commands, this option - instructs `tar' to omit from extended header records that it - produces any keywords matching the string PATTERN. - - When used in extract or list mode, this option instructs tar to - ignore any keywords matching the given PATTERN in the extended - header records. In both cases, matching is performed using the - pattern matching notation described in POSIX 1003.2, 3.13 (*note - wildcards::). For example: - - --pax-option delete=security.* - - would suppress security-related information. - -`exthdr.name=STRING' - This keyword allows user control over the name that is written - into the ustar header blocks for the extended headers. The name - is obtained from STRING after making the following substitutions: - - Meta-character Replaced By - -------------------------------------------------------- - %d The directory name of the file, - equivalent to the result of the - `dirname' utility on the translated - file name. - %f The name of the file with the - directory information stripped, - equivalent to the result of the - `basename' utility on the translated - file name. - %p The process ID of the `tar' process. - %% A `%' character. - - Any other `%' characters in STRING produce undefined results. - - If no option `exthdr.name=string' is specified, `tar' will use the - following default value: - - %d/PaxHeaders.%p/%f - -`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. - - -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. - - -File: tar.info, Node: Large or Negative Values, Next: Other Tars, Prev: Checksumming, Up: Portability - -8.3.9 Large or Negative Values ------------------------------- - - _(This message will disappear, once this node revised.)_ - -The above sections suggest to use `oldest possible' archive format if -in doubt. However, sometimes it is not possible. If you attempt to -archive a file whose metadata cannot be represented using required -format, GNU `tar' will print error message and ignore such a file. You -will than have to switch to a format that is able to handle such -values. The format summary table (*note Formats::) will help you to do -so. - - In particular, when trying to archive files larger than 8GB or with -timestamps not in the range 1970-01-01 00:00:00 through 2242-03-16 -12:56:31 UTC, you will have to chose between GNU and POSIX archive -formats. When considering which format to choose, bear in mind that -the GNU format uses two's-complement base-256 notation to store values -that do not fit into standard ustar range. Such archives can generally -be read only by a GNU `tar' implementation. Moreover, they sometimes -cannot be correctly restored on another hosts even by GNU `tar'. For -example, using two's complement representation for negative time stamps -that assumes a signed 32-bit `time_t' generates archives that are not -portable to hosts with differing `time_t' representations. - - On the other hand, POSIX archives, generally speaking, can be -extracted by any tar implementation that understands older ustar -format. The only exception are files larger than 8GB. - - -File: tar.info, Node: Other Tars, Prev: Large or Negative Values, Up: Portability - -8.3.10 How to Extract GNU-Specific Data Using Other `tar' Implementations -------------------------------------------------------------------------- - -In previous sections you became acquainted with various quirks -necessary to make your archives portable. Sometimes you may need to -extract archives containing GNU-specific members using some third-party -`tar' implementation or an older version of GNU `tar'. Of course your -best bet is to have GNU `tar' installed, but if it is for some reason -impossible, this section will explain how to cope without it. - - When we speak about "GNU-specific" members we mean two classes of -them: members split between the volumes of a multi-volume archive and -sparse members. You will be able to always recover such members if the -archive is in PAX format. In addition split members can be recovered -from archives in old GNU format. The following subsections describe -the required procedures in detail. - -* Menu: - -* Split Recovery:: Members Split Between Volumes -* Sparse Recovery:: Sparse Members - - -File: tar.info, Node: Split Recovery, Next: Sparse Recovery, Up: Other Tars - -8.3.10.1 Extracting Members Split Between Volumes -................................................. - -If a member is split between several volumes of an old GNU format -archive most third party `tar' implementation will fail to extract it. -To extract it, use `tarcat' program (*note Tarcat::). This program is -available from GNU `tar' home page -(http://www.gnu.org/software/tar/utils/tarcat.html). It concatenates -several archive volumes into a single valid archive. For example, if -you have three volumes named from `vol-1.tar' to `vol-3.tar', you can -do the following to extract them using a third-party `tar': - - $ tarcat vol-1.tar vol-2.tar vol-3.tar | tar xf - - - You could use this approach for most (although not all) PAX format -archives as well. However, extracting split members from a PAX archive -is a much easier task, because PAX volumes are constructed in such a -way that each part of a split member is extracted to a different file -by `tar' implementations that are not aware of GNU extensions. More -specifically, the very first part retains its original name, and all -subsequent parts are named using the pattern: - - %d/GNUFileParts.%p/%f.%n - -where symbols 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. - - -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::). - - -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). - - -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:: - - -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 `'. - -`--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. - - -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. - - -File: tar.info, Node: Common Problems and Solutions, Next: Blocking, Prev: Remote Tape Server, Up: Media - -9.3 Some Common Problems and their Solutions -============================================ - -errors from system: -permission denied -no such file or directory -not owner - -errors from `tar': -directory checksum error -header format error - -errors from media/system: -i/o error -device busy - - -File: tar.info, Node: Blocking, Next: Many, Prev: Common Problems and Solutions, Up: Media - -9.4 Blocking -============ - - _(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 - - -File: tar.info, Node: Format Variations, Next: Blocking Factor, Up: Blocking - -9.4.1 Format Variations ------------------------ - - _(This message will disappear, once this node revised.)_ - -Format parameters specify how an archive is written on the archive -media. The best choice of format parameters will vary depending on the -type and number of files being archived, and on the media used to store -the archive. - - To specify format parameters when accessing or creating an archive, -you can use the options described in the following sections. If you do -not specify any format parameters, `tar' uses default parameters. You -cannot modify a compressed archive. If you create an archive with the -`--blocking-factor' option specified (*note Blocking Factor::), you -must specify that blocking-factor when operating on the archive. *Note -Formats::, for other examples of format parameter considerations. - - -File: tar.info, Node: Blocking Factor, Prev: Format Variations, Up: Blocking - -9.4.2 The Blocking Factor of an Archive ---------------------------------------- - - _(This message will disappear, once this node revised.)_ - -The data in an archive is grouped into blocks, which are 512 bytes. -Blocks are read and written in whole number multiples called "records". -The number of blocks in a record (i.e., the size of a record in units -of 512 bytes) is called the "blocking factor". The -`--blocking-factor=512-SIZE' (`-b 512-SIZE') option specifies the -blocking factor of an archive. The default blocking factor is -typically 20 (i.e., 10240 bytes), but can be specified at installation. -To find out the blocking factor of an existing archive, use `tar ---list --file=ARCHIVE-NAME'. This may not work on some devices. - - Records are separated by gaps, which waste space on the archive -media. If you are archiving on magnetic tape, using a larger blocking -factor (and therefore larger records) provides faster throughput and -allows you to fit more data on a tape (because there are fewer gaps). -If you are archiving on cartridge, a very large blocking factor (say -126 or more) greatly increases performance. A smaller blocking factor, -on the other hand, may be useful when archiving small files, to avoid -archiving lots of nulls as `tar' fills out the archive to the end of -the record. In general, the ideal record size depends on the size of -the inter-record gaps on the tape you are using, and the average size -of the files you are archiving. *Note create::, for information on -writing archives. - - Archives with blocking factors larger than 20 cannot be read by very -old versions of `tar', or by some newer versions of `tar' running on -old machines with small address spaces. With GNU `tar', the blocking -factor of an archive is limited only by the maximum record size of the -device containing the archive, or by the amount of available virtual -memory. - - Also, on some systems, not using adequate blocking factors, as -sometimes imposed by the device drivers, may yield unexpected -diagnostics. For example, this has been reported: - - Cannot write to /dev/dlt: Invalid argument - -In such cases, it sometimes happen that the `tar' bundled by the system -is aware of block size idiosyncrasies, while GNU `tar' requires an -explicit specification for the block size, which it cannot guess. This -yields some people to consider GNU `tar' is misbehaving, because by -comparison, `the bundle `tar' works OK'. Adding `-b 256', for example, -might resolve the problem. - - If you use a non-default blocking factor when you create an archive, -you must specify the same blocking factor when you modify that archive. -Some archive devices will also require you to specify the blocking -factor when reading that archive, however this is not typically the -case. Usually, you can use `--list' (`-t') without specifying a -blocking factor--`tar' reports a non-default record size and then lists -the archive members as it would normally. To extract files from an -archive with a non-standard blocking factor (particularly if you're not -sure what the blocking factor is), you can usually use the -`--read-full-records' (`-B') option while specifying a blocking factor -larger then the blocking factor of the archive (i.e., `tar --extract ---read-full-records --blocking-factor=300'. *Note list::, for more -information on the `--list' (`-t') operation. *Note Reading::, for a -more detailed explanation of that option. - -`--blocking-factor=NUMBER' -`-b NUMBER' - Specifies the blocking factor of an archive. Can be used with any - operation, but is usually not necessary with `--list' (`-t'). - - Device blocking - -`-b BLOCKS' -`--blocking-factor=BLOCKS' - Set record size to BLOCKS * 512 bytes. - - This option is used to specify a "blocking factor" for the archive. - When reading or writing the archive, `tar', will do reads and - writes of the archive in records of BLOCK*512 bytes. This is true - even when the archive is compressed. Some devices requires that - all write operations be a multiple of a certain size, and so, `tar' - pads the archive out to the next record boundary. - - The default blocking factor is set when `tar' is compiled, and is - typically 20. Blocking factors larger than 20 cannot be read by - very old versions of `tar', or by some newer versions of `tar' - running on old machines with small address spaces. - - With a magnetic tape, larger records give faster throughput and fit - more data on a tape (because there are fewer inter-record gaps). - If the archive is in a disk file or a pipe, you may want to specify - a smaller blocking factor, since a large one will result in a large - number of null bytes at the end of the archive. - - When writing cartridge or other streaming tapes, a much larger - blocking factor (say 126 or more) will greatly increase - performance. However, you must specify the same blocking factor - when reading or updating the archive. - - Apparently, Exabyte drives have a physical block size of 8K bytes. - If we choose our blocksize as a multiple of 8k bytes, then the - problem seems to disappear. Id est, we are using block size of - 112 right now, and we haven't had the problem since we switched... - - With GNU `tar' the blocking factor is limited only by the maximum - record size of the device containing the archive, or by the amount - of available virtual memory. - - However, deblocking or reblocking is virtually avoided in a special - case which often occurs in practice, but which requires all the - following conditions to be simultaneously true: - * the archive is subject to a compression option, - - * the archive is not handled through standard input or output, - nor redirected nor piped, - - * the archive is directly handled to a local disk, instead of - any special device, - - * `--blocking-factor' is not explicitly specified on the `tar' - invocation. - - If the output goes directly to a local disk, and not through - stdout, then the last write is not extended to a full record size. - Otherwise, reblocking occurs. Here are a few other remarks on this - topic: - - * `gzip' will complain about trailing garbage if asked to - uncompress a compressed archive on tape, there is an option - to turn the message off, but it breaks the regularity of - simply having to use `PROG -d' for decompression. It would - be nice if gzip was silently ignoring any number of trailing - zeros. I'll ask Jean-loup Gailly, by sending a copy of this - message to him. - - * `compress' does not show this problem, but as Jean-loup - pointed out to Michael, `compress -d' silently adds garbage - after the result of decompression, which tar ignores because - it already recognized its end-of-file indicator. So this bug - may be safely ignored. - - * `gzip -d -q' will be silent about the trailing zeros indeed, - but will still return an exit status of 2 which tar reports - in turn. `tar' might ignore the exit status returned, but I - hate doing that, as it weakens the protection `tar' offers - users against other possible problems at decompression time. - If `gzip' was silently skipping trailing zeros _and_ also - avoiding setting the exit status in this innocuous case, that - would solve this situation. - - * `tar' should become more solid at not stopping to read a pipe - at the first null block encountered. This inelegantly breaks - the pipe. `tar' should rather drain the pipe out before - exiting itself. - -`-i' -`--ignore-zeros' - Ignore blocks of zeros in archive (means EOF). - - The `--ignore-zeros' (`-i') option causes `tar' to ignore blocks - of zeros in the archive. Normally a block of zeros indicates the - end of the archive, but when reading a damaged archive, or one - which was created by concatenating several archives together, this - option allows `tar' to read the entire archive. This option is - not on by default because many versions of `tar' write garbage - after the zeroed blocks. - - Note that this option causes `tar' to read to the end of the - archive file, which may sometimes avoid problems when multiple - files are stored on a single physical tape. - -`-B' -`--read-full-records' - Reblock as we read (for reading 4.2BSD pipes). - - If `--read-full-records' is used, `tar' will not panic if an - attempt to read a record from the archive does not return a full - record. Instead, `tar' will keep reading until it has obtained a - full record. - - This option is turned on by default when `tar' is reading an - archive from standard input, or from a remote machine. This is - because on BSD Unix systems, a read of a pipe will return however - much happens to be in the pipe, even if it is less than `tar' - requested. If this option was not used, `tar' would fail as soon - as it read an incomplete record from the pipe. - - This option is also useful with the commands for updating an - archive. - - - Tape blocking - - When handling various tapes or cartridges, you have to take care of -selecting a proper blocking, that is, the number of disk blocks you put -together as a single tape block on the tape, without intervening tape -gaps. A "tape gap" is a small landing area on the tape with no -information on it, used for decelerating the tape to a full stop, and -for later regaining the reading or writing speed. When the tape driver -starts reading a record, the record has to be read whole without -stopping, as a tape gap is needed to stop the tape motion without -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. - - -File: tar.info, Node: Many, Next: Using Multiple Tapes, Prev: Blocking, Up: Media - -9.5 Many Archives on One Tape -============================= - -Most tape devices have two entries in the `/dev' directory, or entries -that come in pairs, which differ only in the minor number for this -device. Let's take for example `/dev/tape', which often points to the -only or usual tape device of a given system. There might be a -corresponding `/dev/nrtape' or `/dev/ntape'. The simpler name is the -_rewinding_ version of the device, while the name having `nr' in it is -the _no rewinding_ version of the same device. - - A rewinding tape device will bring back the tape to its beginning -point automatically when this device is opened or closed. Since `tar' -opens the archive file before using it and closes it afterwards, this -means that a simple: - - $ tar cf /dev/tape DIRECTORY - -will reposition the tape to its beginning both prior and after saving -DIRECTORY contents to it, thus erasing prior tape contents and making -it so that any subsequent write operation will destroy what has just -been saved. - - So, a rewinding device is normally meant to hold one and only one -file. If you want to put more than one `tar' archive on a given tape, -you will need to avoid using the rewinding version of the tape device. -You will also have to pay special attention to tape positioning. -Errors in positioning may overwrite the valuable data already on your -tape. Many people, burnt by past experiences, will only use rewinding -devices and limit themselves to one file per tape, precisely to avoid -the risk of such errors. Be fully aware that writing at the wrong -position on a tape loses all information past this point and most -probably until the end of the tape, and this destroyed information -_cannot_ be recovered. - - To save DIRECTORY-1 as a first archive at the beginning of a tape, -and leave that tape ready for a second archive, you should use: - - $ mt -f /dev/nrtape rewind - $ tar cf /dev/nrtape DIRECTORY-1 - - "Tape marks" are special magnetic patterns written on the tape -media, which are later recognizable by the reading hardware. These -marks are used after each file, when there are many on a single tape. -An empty file (that is to say, two tape marks in a row) signal the -logical end of the tape, after which no file exist. Usually, -non-rewinding tape device drivers will react to the close request issued -by `tar' by first writing two tape marks after your archive, and by -backspacing over one of these. So, if you remove the tape at that time -from the tape drive, it is properly terminated. But if you write -another file at the current position, the second tape mark will be -erased by the new information, leaving only one tape mark between files. - - So, you may now save DIRECTORY-2 as a second archive after the first -on the same tape by issuing the command: - - $ tar cf /dev/nrtape DIRECTORY-2 - -and so on for all the archives you want to put on the same tape. - - Another usual case is that you do not write all the archives the same -day, and you need to remove and store the tape between two archive -sessions. In general, you must remember how many files are already -saved on your tape. Suppose your tape already has 16 files on it, and -that you are ready to write the 17th. You have to take care of skipping -the first 16 tape marks before saving DIRECTORY-17, say, by using these -commands: - - $ mt -f /dev/nrtape rewind - $ mt -f /dev/nrtape fsf 16 - $ tar cf /dev/nrtape DIRECTORY-17 - - In all the previous examples, we put aside blocking considerations, -but you should do the proper things for that as well. *Note Blocking::. - -* Menu: - -* Tape Positioning:: Tape Positions and Tape Marks -* mt:: The `mt' Utility - - -File: tar.info, Node: Tape Positioning, Next: mt, Up: Many - -9.5.1 Tape Positions and Tape Marks ------------------------------------ - - _(This message will disappear, once this node revised.)_ - -Just as archives can store more than one file from the file system, -tapes can store more than one archive file. To keep track of where -archive files (or any other type of file stored on tape) begin and end, -tape archive devices write magnetic "tape marks" on the archive media. -Tape drives write one tape mark between files, two at the end of all -the file entries. - - If you think of data as a series of records "rrrr"'s, and tape marks -as "*"'s, a tape might look like the following: - - rrrr*rrrrrr*rrrrr*rr*rrrrr**------------------------- - - Tape devices read and write tapes using a read/write "tape head"--a -physical part of the device which can only access one point on the tape -at a time. When you use `tar' to read or write archive data from a -tape device, the device will begin reading or writing from wherever on -the tape the tape head happens to be, regardless of which archive or -what part of the archive the tape head is on. Before writing an -archive, you should make sure that no data on the tape will be -overwritten (unless it is no longer needed). Before reading an -archive, you should make sure the tape head is at the beginning of the -archive you want to read. You can do it manually via `mt' utility -(*note mt::). The `restore' script does that automatically (*note -Scripted Restoration::). - - If you want to add new archive file entries to a tape, you should -advance the tape to the end of the existing file entries, backspace -over the last tape mark, and write the new archive file. If you were -to add two archives to the example above, the tape might look like the -following: - - rrrr*rrrrrr*rrrrr*rr*rrrrr*rrr*rrrr**---------------- - - -File: tar.info, Node: mt, Prev: Tape Positioning, Up: Many - -9.5.2 The `mt' Utility ----------------------- - - _(This message will disappear, once this node revised.)_ - -*Note Blocking Factor::. - - You can use the `mt' utility to advance or rewind a tape past a -specified number of archive files on the tape. This will allow you to -move to the beginning of an archive before extracting or reading it, or -to the end of all the archives before writing a new one. - - The syntax of the `mt' command is: - - mt [-f TAPENAME] OPERATION [NUMBER] - - where TAPENAME is the name of the tape device, NUMBER is the number -of times an operation is performed (with a default of one), and -OPERATION is one of the following: - -`eof' -`weof' - Writes NUMBER tape marks at the current position on the tape. - -`fsf' - Moves tape position forward NUMBER files. - -`bsf' - Moves tape position back NUMBER files. - -`rewind' - Rewinds the tape. (Ignores NUMBER). - -`offline' -`rewoff1' - Rewinds the tape and takes the tape device off-line. (Ignores - NUMBER). - -`status' - Prints status information about the tape unit. - - - If you don't specify a TAPENAME, `mt' uses the environment variable -`TAPE'; if `TAPE' is not set, `mt' will use the default device -specified in your `sys/mtio.h' file (`DEFTAPE' variable). If this is -not defined, the program will display a descriptive error message and -exit with code 1. - - `mt' returns a 0 exit status when the operation(s) were successful, -1 if the command was unrecognized, and 2 if an operation failed. - - -File: tar.info, Node: Using Multiple Tapes, Next: label, Prev: Many, Up: Media - -9.6 Using Multiple Tapes -======================== - -Often you might want to write a large archive, one larger than will fit -on the actual tape you are using. In such a case, you can run multiple -`tar' commands, but this can be inconvenient, particularly if you are -using options like `--exclude=PATTERN' or dumping entire file systems. -Therefore, `tar' provides a special mode for creating multi-volume -archives. - - "Multi-volume" archive is a single `tar' archive, stored on several -media volumes of fixed size. Although in this section we will often -call `volume' a "tape", there is absolutely no requirement for -multi-volume archives to be stored on tapes. Instead, they can use -whatever media type the user finds convenient, they can even be located -on files. - - When creating a multi-volume archive, GNU `tar' continues to fill -current volume until it runs out of space, then it switches to next -volume (usually the operator is queried to replace the tape on this -point), and continues working on the new volume. This operation -continues until all requested files are dumped. If GNU `tar' detects -end of media while dumping a file, such a file is archived in split -form. Some very big files can even be split across several volumes. - - Each volume is itself a valid GNU `tar' archive, so it can be read -without any special options. Consequently any file member residing -entirely on one volume can be extracted or otherwise operated upon -without needing the other volume. Sure enough, to extract a split -member you would need all volumes its parts reside on. - - Multi-volume archives suffer from several limitations. In -particular, they cannot be compressed. - - GNU `tar' is able to create multi-volume archives of two formats -(*note Formats::): `GNU' and `POSIX'. - -* Menu: - -* Multi-Volume Archives:: Archives Longer than One Tape or Disk -* Tape Files:: Tape Files -* Tarcat:: Concatenate Volumes into a Single Archive - - -File: tar.info, Node: Multi-Volume Archives, Next: Tape Files, Up: Using Multiple Tapes - -9.6.1 Archives Longer than One Tape or Disk -------------------------------------------- - -To create an archive that is larger than will fit on a single unit of -the media, use the `--multi-volume' (`-M') option in conjunction with -the `--create' option (*note create::). A "multi-volume" archive can -be manipulated like any other archive (provided the `--multi-volume' -option is specified), but is stored on more than one tape or 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 - - -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. - - -File: tar.info, Node: Tarcat, Prev: Tape Files, Up: Using Multiple Tapes - -9.6.3 Concatenate Volumes into a Single Archive ------------------------------------------------ - -Sometimes it is necessary to convert existing GNU `tar' multi-volume -archive to a single `tar' archive. Simply concatenating all volumes -into one will not work, since each volume carries an additional -information at the beginning. GNU `tar' is shipped with the shell -script `tarcat' designed for this purpose. - - The script takes a list of files comprising a multi-volume archive -and creates the resulting archive at the standard output. For example: - - tarcat vol.1 vol.2 vol.3 | tar tf - - - The script implements a simple heuristics to determine the format of -the first volume file and to decide how to process the rest of the -files. However, it makes no attempt to verify whether the files are -given in order or even if they are valid `tar' archives. It uses `dd' -and does not filter its standard error, so you will usually see lots of -spurious messages. - - -File: tar.info, Node: label, Next: verify, Prev: Using Multiple Tapes, Up: Media - -9.7 Including a Label in the Archive -==================================== - - _(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'. - - -File: tar.info, Node: verify, Next: Write Protection, Prev: label, Up: Media - -9.8 Verifying Data as It is Stored -================================== - -`-W' -`--verify' - Attempt to verify the archive after writing. - - This option causes `tar' to verify the archive after writing it. -Each volume is checked after it is written, and any discrepancies are -recorded on the standard error output. - - Verification requires that the archive be on a back-space-able -medium. This means pipes, some cartridge tape drives, and some other -devices cannot be verified. - - You can insure the accuracy of an archive by comparing files in the -system with archive members. `tar' can compare an archive to the file -system as the archive is being written, to verify a write operation, or -can compare a previously written archive, to insure that it is up to -date. - - To check for discrepancies in an archive immediately after it is -written, use the `--verify' (`-W') option in conjunction with the -`--create' operation. When this option is specified, `tar' checks -archive members against their counterparts in the file system, and -reports discrepancies on the standard error. - - To verify an archive, you must be able to read it from before the end -of the last written entry. This option is useful for detecting data -errors on some tapes. Archives written to pipes, some cartridge tape -drives, and some other devices cannot be verified. - - One can explicitly compare an already made archive with the file -system by using the `--compare' (`--diff', `-d') option, instead of -using the more automatic `--verify' option. *Note compare::. - - Note that these two options have a slightly different intent. The -`--compare' option checks how identical are the logical contents of some -archive with what is on your disks, while the `--verify' option is -really for checking if the physical contents agree and if the recording -media itself is of dependable quality. So, for the `--verify' -operation, `tar' tries to defeat all in-memory cache pertaining to the -archive, while it lets the speed optimization undisturbed for the -`--compare' option. If you nevertheless use `--compare' for media -verification, you may have to defeat the in-memory cache yourself, -maybe by opening and reclosing the door latch of your recording unit, -forcing some doubt in your operating system about the fact this is -really the same volume as the one just written or read. - - The `--verify' option would not be necessary if drivers were indeed -able to detect dependably all write failures. This sometimes require -many magnetic heads, some able to read after the writes occurred. One -would not say that drivers unable to detect all cases are necessarily -flawed, as long as programming is concerned. - - The `--verify' (`-W') option will not work in conjunction with the -`--multi-volume' (`-M') option or the `--append' (`-r'), `--update' -(`-u') and `--delete' operations. *Note Operations::, for more -information on these operations. - - Also, since `tar' normally strips leading `/' from file names (*note -absolute::), a command like `tar --verify -cf /tmp/foo.tar /etc' will -work as desired only if the working directory is `/', as `tar' uses the -archive's relative member names (e.g., `etc/motd') when verifying the -archive. - - -File: tar.info, Node: Write Protection, Prev: verify, Up: Media - -9.9 Write Protection -==================== - -Almost all tapes and diskettes, and in a few rare cases, even disks can -be "write protected", to protect data on them from being changed. Once -an archive is written, you should write protect the media to prevent -the archive from being accidentally overwritten or deleted. (This will -protect the archive from being changed with a tape or floppy drive--it -will not protect it from magnet fields or other physical hazards). - - The write protection device itself is usually an integral part of the -physical media, and can be a two position (write enabled/write -disabled) switch, a notch which can be popped out or covered, a ring -which can be removed from the center of a tape reel, or some other -changeable feature. - - -File: tar.info, Node: 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. - - -File: tar.info, Node: Configuring Help Summary, Next: Fixing Snapshot Files, Prev: Changes, Up: Top - -Appendix B Configuring Help Summary -*********************************** - -Running `tar --help' displays the short `tar' option summary (*note -help::). This summary is organized by "groups" of semantically close -options. The options within each group are printed in the following -order: a short option, eventually followed by a list of corresponding -long option names, followed by a short description of the option. For -example, here is an excerpt from the actual `tar --help' output: - - - Main operation mode: - - -A, --catenate, --concatenate append tar files to an archive - -c, --create create a new archive - -d, --diff, --compare find differences between archive and - file system - --delete delete from the archive - - The exact visual representation of the help output is configurable -via `ARGP_HELP_FMT' environment variable. The value of this variable is -a comma-separated list of "format variable" assignments. There are two -kinds of format variables. An "offset variable" keeps the offset of -some part of help output text from the leftmost column on the screen. A -"boolean" variable is a flag that toggles some output feature on or -off. Depending on the type of the corresponding variable, there are two -kinds of assignments: - -Offset assignment - The assignment to an offset variable has the following syntax: - - VARIABLE=VALUE - - where VARIABLE is the variable name, and VALUE is a numeric value - to be assigned to the variable. - -Boolean assignment - To assign `true' value to a variable, simply put this variable - name. To assign `false' value, prefix the variable name with - `no-'. For example: - - # Assign `true' value: - dup-args - # Assign `false' value: - no-dup-args - - Following variables are declared: - - -- Help Output: boolean dup-args - If true, arguments for an option are shown with both short and long - options, even when a given option has both forms, for example: - - -f ARCHIVE, --file=ARCHIVE use archive file or device ARCHIVE - - If false, then if an option has both short and long forms, the - argument is only shown with the long one, for example: - - -f, --file=ARCHIVE use archive file or device ARCHIVE - - and a message indicating that the argument is applicable to both - forms is printed below the options. This message can be disabled - using `dup-args-note' (see below). - - The default is false. - - -- Help Output: boolean dup-args-note - If this variable is true, which is the default, the following - notice is displayed at the end of the help output: - - Mandatory or optional arguments to long options are also - mandatory or optional for any corresponding short options. - - Setting `no-dup-args-note' inhibits this message. Normally, only - one of variables `dup-args' or `dup-args-note' should be set. - - -- Help Output: offset short-opt-col - Column in which short options start. Default is 2. - - $ tar --help|grep ARCHIVE - -f, --file=ARCHIVE use archive file or device ARCHIVE - $ ARGP_HELP_FMT=short-opt-col=6 tar --help|grep ARCHIVE - -f, --file=ARCHIVE use archive file or device ARCHIVE - - -- Help Output: offset long-opt-col - Column in which long options start. Default is 6. For example: - - $ tar --help|grep ARCHIVE - -f, --file=ARCHIVE use archive file or device ARCHIVE - $ ARGP_HELP_FMT=long-opt-col=16 tar --help|grep ARCHIVE - -f, --file=ARCHIVE use archive file or device ARCHIVE - - -- Help Output: offset doc-opt-col - Column in which "doc options" start. A doc option isn't actually - an option, but rather an arbitrary piece of documentation that is - displayed in much the same manner as the options. For example, in - the description of `--format' option: - - -H, --format=FORMAT create archive of the given format. - - FORMAT is one of the following: - - gnu GNU tar 1.13.x format - oldgnu GNU format as per tar <= 1.12 - pax POSIX 1003.1-2001 (pax) format - posix same as pax - ustar POSIX 1003.1-1988 (ustar) format - v7 old V7 tar format - - the format names are doc options. Thus, if you set - `ARGP_HELP_FMT=doc-opt-col=6' the above part of the help output - will look as follows: - - -H, --format=FORMAT create archive of the given format. - - FORMAT is one of the following: - - gnu GNU tar 1.13.x format - oldgnu GNU format as per tar <= 1.12 - pax POSIX 1003.1-2001 (pax) format - posix same as pax - ustar POSIX 1003.1-1988 (ustar) format - v7 old V7 tar format - - -- Help Output: offset opt-doc-col - Column in which option description starts. Default is 29. - - $ tar --help|grep ARCHIVE - -f, --file=ARCHIVE use archive file or device ARCHIVE - $ ARGP_HELP_FMT=opt-doc-col=19 tar --help|grep ARCHIVE - -f, --file=ARCHIVE use archive file or device ARCHIVE - $ ARGP_HELP_FMT=opt-doc-col=9 tar --help|grep ARCHIVE - -f, --file=ARCHIVE - use archive file or device ARCHIVE - - Notice, that the description starts on a separate line if - `opt-doc-col' value is too small. - - -- Help Output: offset header-col - Column in which "group headers" are printed. A group header is a - descriptive text preceding an option group. For example, in the - following text: - - - Main operation mode: - - -A, --catenate, --concatenate append tar files to - an archive - -c, --create create a new archive - `Main operation mode:' is the group header. - - The default value is 1. - - -- Help Output: offset usage-indent - Indentation of wrapped usage lines. Affects `--usage' output. - Default is 12. - - -- Help Output: offset rmargin - Right margin of the text output. Used for wrapping. - - -File: tar.info, Node: Fixing Snapshot Files, Next: Tar Internals, Prev: Configuring Help Summary, Up: Top - -Appendix C Fixing Snapshot Files -******************************** - -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 - - -File: tar.info, Node: Tar Internals, Next: Genfile, Prev: Fixing Snapshot Files, Up: Top - -Appendix D Tar Internals -************************ - -* Menu: - -* Standard:: Basic Tar Format -* Extensions:: GNU Extensions to the Archive Format -* Sparse Formats:: Storing Sparse Files -* Snapshot Files:: -* Dumpdir:: - - -File: tar.info, Node: Standard, Next: Extensions, Up: Tar Internals - -Basic Tar Format -================ - - _(This message will disappear, once this node revised.)_ - -While an archive may contain many files, the archive itself is a single -ordinary file. Like any other file, an archive file can be written to -a storage device such as a tape or disk, sent through a pipe or over a -network, saved on the active file system, or even stored in another -archive. An archive file is not easy to read or manipulate without -using the `tar' utility or Tar mode in GNU Emacs. - - Physically, an archive consists of a series of file entries -terminated by an end-of-archive entry, which consists of two 512 blocks -of zero bytes. A file entry usually describes one of the files in the -archive (an "archive member"), and consists of a file header and the -contents of the file. File headers contain file names and statistics, -checksum information which `tar' uses to detect file corruption, and -information about file types. - - Archives are permitted to have more than one member with the same -member name. One way this situation can occur is if more than one -version of a file has been stored in the archive. For information -about adding new versions of a file to an archive, see *note update::. - - In addition to entries describing archive members, an archive may -contain entries which `tar' itself uses to store information. *Note -label::, for an example of such an archive entry. - - A `tar' archive file contains a series of blocks. Each block -contains `BLOCKSIZE' bytes. Although this format may be thought of as -being on magnetic tape, other media are often used. - - Each file archived is represented by a header block which describes -the file, followed by zero or more blocks which give the contents of -the file. At the end of the archive file there are two 512-byte blocks -filled with binary zeros as an end-of-file marker. A reasonable system -should write such end-of-file marker at the end of an archive, but must -not assume that such a block exists when reading an archive. In -particular GNU `tar' always issues a warning if it does not encounter -it. - - The blocks may be "blocked" for physical I/O operations. Each -record of N blocks (where N is set by the `--blocking-factor=512-SIZE' -(`-b 512-SIZE') option to `tar') is written with a single `write ()' -operation. On magnetic tapes, the result of such a write is a single -record. When writing an archive, the last record of blocks should be -written at the full size, with blocks after the zero block containing -all zeros. When reading an archive, a reasonable system should -properly handle an archive whose last record is shorter than the rest, -or which contains garbage records after a zero block. - - The header block is defined in C as follows. In the GNU `tar' -distribution, this is part of file `src/tar.h': - - - /* tar Header Block, from POSIX 1003.1-1990. */ - - /* POSIX header. */ - - struct posix_header - { /* byte offset */ - char name[100]; /* 0 */ - char mode[8]; /* 100 */ - char uid[8]; /* 108 */ - char gid[8]; /* 116 */ - char size[12]; /* 124 */ - char mtime[12]; /* 136 */ - char chksum[8]; /* 148 */ - char typeflag; /* 156 */ - char linkname[100]; /* 157 */ - char magic[6]; /* 257 */ - char version[2]; /* 263 */ - char uname[32]; /* 265 */ - char gname[32]; /* 297 */ - char devmajor[8]; /* 329 */ - char devminor[8]; /* 337 */ - char prefix[155]; /* 345 */ - /* 500 */ - }; - - #define TMAGIC "ustar" /* ustar and a null */ - #define TMAGLEN 6 - #define TVERSION "00" /* 00 and no null */ - #define TVERSLEN 2 - - /* Values used in typeflag field. */ - #define REGTYPE '0' /* regular file */ - #define AREGTYPE '\0' /* regular file */ - #define LNKTYPE '1' /* link */ - #define SYMTYPE '2' /* reserved */ - #define CHRTYPE '3' /* character special */ - #define BLKTYPE '4' /* block special */ - #define DIRTYPE '5' /* directory */ - #define FIFOTYPE '6' /* FIFO special */ - #define CONTTYPE '7' /* reserved */ - - #define XHDTYPE 'x' /* Extended header referring to the - next file in the archive */ - #define XGLTYPE 'g' /* Global extended header */ - - /* Bits used in the mode field, values in octal. */ - #define TSUID 04000 /* set UID on execution */ - #define TSGID 02000 /* set GID on execution */ - #define TSVTX 01000 /* reserved */ - /* file permissions */ - #define TUREAD 00400 /* read by owner */ - #define TUWRITE 00200 /* write by owner */ - #define TUEXEC 00100 /* execute/search by owner */ - #define TGREAD 00040 /* read by group */ - #define TGWRITE 00020 /* write by group */ - #define TGEXEC 00010 /* execute/search by group */ - #define TOREAD 00004 /* read by other */ - #define TOWRITE 00002 /* write by other */ - #define TOEXEC 00001 /* execute/search by other */ - - /* tar Header Block, GNU extensions. */ - - /* In GNU tar, SYMTYPE is for to symbolic links, and CONTTYPE is for - contiguous files, so maybe disobeying the `reserved' comment in POSIX - header description. I suspect these were meant to be used this way, and - should not have really been `reserved' in the published standards. */ - - /* *BEWARE* *BEWARE* *BEWARE* that the following information is still - boiling, and may change. Even if the OLDGNU format description should be - accurate, the so-called GNU format is not yet fully decided. It is - surely meant to use only extensions allowed by POSIX, but the sketch - below repeats some ugliness from the OLDGNU format, which should rather - go away. Sparse files should be saved in such a way that they do *not* - require two passes at archive creation time. Huge files get some POSIX - fields to overflow, alternate solutions have to be sought for this. */ - - /* Descriptor for a single file hole. */ - - struct sparse - { /* byte offset */ - char offset[12]; /* 0 */ - char numbytes[12]; /* 12 */ - /* 24 */ - }; - - /* Sparse files are not supported in POSIX ustar format. For sparse files - with a POSIX header, a GNU extra header is provided which holds overall - sparse information and a few sparse descriptors. When an old GNU header - replaces both the POSIX header and the GNU extra header, it holds some - sparse descriptors too. Whether POSIX or not, if more sparse descriptors - are still needed, they are put into as many successive sparse headers as - necessary. The following constants tell how many sparse descriptors fit - in each kind of header able to hold them. */ - - #define SPARSES_IN_EXTRA_HEADER 16 - #define SPARSES_IN_OLDGNU_HEADER 4 - #define SPARSES_IN_SPARSE_HEADER 21 - - /* Extension header for sparse files, used immediately after the GNU extra - header, and used only if all sparse information cannot fit into that - extra header. There might even be many such extension headers, one after - the other, until all sparse information has been recorded. */ - - struct sparse_header - { /* byte offset */ - struct sparse sp[SPARSES_IN_SPARSE_HEADER]; - /* 0 */ - char isextended; /* 504 */ - /* 505 */ - }; - - /* The old GNU format header conflicts with POSIX format in such a way that - POSIX archives may fool old GNU tar's, and POSIX tar's might well be - fooled by old GNU tar archives. An old GNU format header uses the space - used by the prefix field in a POSIX header, and cumulates information - normally found in a GNU extra header. With an old GNU tar header, we - never see any POSIX header nor GNU extra header. Supplementary sparse - headers are allowed, however. */ - - struct oldgnu_header - { /* byte offset */ - char unused_pad1[345]; /* 0 */ - char atime[12]; /* 345 Incr. archive: atime of the file */ - char ctime[12]; /* 357 Incr. archive: ctime of the file */ - char offset[12]; /* 369 Multivolume archive: the offset of - the start of this volume */ - char longnames[4]; /* 381 Not used */ - char unused_pad2; /* 385 */ - struct sparse sp[SPARSES_IN_OLDGNU_HEADER]; - /* 386 */ - char isextended; /* 482 Sparse file: Extension sparse header - follows */ - char realsize[12]; /* 483 Sparse file: Real size*/ - /* 495 */ - }; - - /* OLDGNU_MAGIC uses both magic and version fields, which are contiguous. - Found in an archive, it indicates an old GNU header format, which will be - hopefully become obsolescent. With OLDGNU_MAGIC, uname and gname are - valid, though the header is not truly POSIX conforming. */ - #define OLDGNU_MAGIC "ustar " /* 7 chars and a null */ - - /* The standards committee allows only capital A through capital Z for - user-defined expansion. Other letters in use include: - - 'A' Solaris Access Control List - 'E' Solaris Extended Attribute File - 'I' Inode only, as in 'star' - 'N' Obsolete GNU tar, for file names that do not fit into the main header. - 'X' POSIX 1003.1-2001 eXtended (VU version) */ - - /* This is a dir entry that contains the names of files that were in the - dir at the time the dump was made. */ - #define GNUTYPE_DUMPDIR 'D' - - /* Identifies the *next* file on the tape as having a long linkname. */ - #define GNUTYPE_LONGLINK 'K' - - /* Identifies the *next* file on the tape as having a long name. */ - #define GNUTYPE_LONGNAME 'L' - - /* This is the continuation of a file that began on another volume. */ - #define GNUTYPE_MULTIVOL 'M' - - /* This is for sparse files. */ - #define GNUTYPE_SPARSE 'S' - - /* This file is a tape/volume header. Ignore it on extraction. */ - #define GNUTYPE_VOLHDR 'V' - - /* Solaris extended header */ - #define SOLARIS_XHDTYPE 'X' - - /* Jo"rg Schilling star header */ - - struct star_header - { /* byte offset */ - char name[100]; /* 0 */ - char mode[8]; /* 100 */ - char uid[8]; /* 108 */ - char gid[8]; /* 116 */ - char size[12]; /* 124 */ - char mtime[12]; /* 136 */ - char chksum[8]; /* 148 */ - char typeflag; /* 156 */ - char linkname[100]; /* 157 */ - char magic[6]; /* 257 */ - char version[2]; /* 263 */ - char uname[32]; /* 265 */ - char gname[32]; /* 297 */ - char devmajor[8]; /* 329 */ - char devminor[8]; /* 337 */ - char prefix[131]; /* 345 */ - char atime[12]; /* 476 */ - char ctime[12]; /* 488 */ - /* 500 */ - }; - - #define SPARSES_IN_STAR_HEADER 4 - #define SPARSES_IN_STAR_EXT_HEADER 21 - - struct star_in_header - { - char fill[345]; /* 0 Everything that is before t_prefix */ - char prefix[1]; /* 345 t_name prefix */ - char fill2; /* 346 */ - char fill3[8]; /* 347 */ - char isextended; /* 355 */ - struct sparse sp[SPARSES_IN_STAR_HEADER]; /* 356 */ - char realsize[12]; /* 452 Actual size of the file */ - char offset[12]; /* 464 Offset of multivolume contents */ - char atime[12]; /* 476 */ - char ctime[12]; /* 488 */ - char mfill[8]; /* 500 */ - char xmagic[4]; /* 508 "tar" */ - }; - - struct star_ext_header - { - struct sparse sp[SPARSES_IN_STAR_EXT_HEADER]; - char isextended; - }; - - All characters in header blocks are represented by using 8-bit -characters in the local variant of ASCII. Each field within the -structure is contiguous; that is, there is no padding used within the -structure. Each character on the archive medium is stored contiguously. - - Bytes representing the contents of files (after the header block of -each file) are not translated in any way and are not constrained to -represent characters in any character set. The `tar' format does not -distinguish text files from binary files, and no translation of file -contents is performed. - - The `name', `linkname', `magic', `uname', and `gname' are -null-terminated character strings. All other fields are zero-filled -octal numbers in ASCII. Each numeric field of width W contains W minus -1 digits, and a null. - - The `name' field is the file name of the file, with directory names -(if any) preceding the file name, separated by slashes. - - The `mode' field provides nine bits specifying file permissions and -three bits to specify the Set UID, Set GID, and Save Text ("sticky") -modes. Values for these bits are defined above. When special -permissions are required to create a file with a given mode, and the -user restoring files from the archive does not hold such permissions, -the mode bit(s) specifying those special permissions are ignored. -Modes which are not supported by the operating system restoring files -from the archive will be ignored. Unsupported modes should be faked up -when creating or updating an archive; e.g., the group permission could -be copied from the _other_ permission. - - The `uid' and `gid' fields are the numeric user and group ID of the -file owners, respectively. If the operating system does not support -numeric user or group IDs, these fields should be ignored. - - The `size' field is the size of the file in bytes; linked files are -archived with this field specified as zero. - - The `mtime' field is the data modification time of the file at the -time it was archived. It is the ASCII representation of the octal -value of the last time the file's contents were modified, represented -as an integer number of seconds since January 1, 1970, 00:00 -Coordinated Universal Time. - - The `chksum' field is the ASCII representation of the octal value of -the simple sum of all bytes in the header block. Each 8-bit byte in -the header is added to an unsigned integer, initialized to zero, the -precision of which shall be no less than seventeen bits. When -calculating the checksum, the `chksum' field is treated as if it were -all blanks. - - The `typeflag' field specifies the type of file archived. If a -particular implementation does not recognize or permit the specified -type, the file will be extracted as if it were a regular file. As this -action occurs, `tar' issues a warning to the standard error. - - The `atime' and `ctime' fields are used in making incremental -backups; they store, respectively, the particular file's access and -status change times. - - The `offset' is used by the `--multi-volume' (`-M') option, when -making a multi-volume archive. The offset is number of bytes into the -file that we need to restart at to continue the file on the next tape, -i.e., where we store the location that a continued file is continued at. - - The following fields were added to deal with sparse files. A file -is "sparse" if it takes in unallocated blocks which end up being -represented as zeros, i.e., no useful data. A test to see if a file is -sparse is to look at the number blocks allocated for it versus the -number of characters in the file; if there are fewer blocks allocated -for the file than would normally be allocated for a file of that size, -then the file is sparse. This is the method `tar' uses to detect a -sparse file, and once such a file is detected, it is treated -differently from non-sparse files. - - Sparse files are often `dbm' files, or other database-type files -which have data at some points and emptiness in the greater part of the -file. Such files can appear to be very large when an `ls -l' is done -on them, when in truth, there may be a very small amount of important -data contained in the file. It is thus undesirable to have `tar' think -that it must back up this entire file, as great quantities of room are -wasted on empty blocks, which can lead to running out of room on a tape -far earlier than is necessary. Thus, sparse files are dealt with so -that these empty blocks are not written to the tape. Instead, what is -written to the tape is a description, of sorts, of the sparse file: -where the holes are, how big the holes are, and how much data is found -at the end of the hole. This way, the file takes up potentially far -less room on the tape, and when the file is extracted later on, it will -look exactly the way it looked beforehand. The following is a -description of the fields used to handle a sparse file: - - The `sp' is an array of `struct sparse'. Each `struct sparse' -contains two 12-character strings which represent an offset into the -file and a number of bytes to be written at that offset. The offset is -absolute, and not relative to the offset in preceding array element. - - The header can hold four of these `struct sparse' at the moment; if -more are needed, they are not stored in the header. - - The `isextended' flag is set when an `extended_header' is needed to -deal with a file. Note that this means that this flag can only be set -when dealing with a sparse file, and it is only set in the event that -the description of the file will not fit in the allotted room for -sparse structures in the header. In other words, an extended_header is -needed. - - The `extended_header' structure is used for sparse files which need -more sparse structures than can fit in the header. The header can fit -4 such structures; if more are needed, the flag `isextended' gets set -and the next block is an `extended_header'. - - Each `extended_header' structure contains an array of 21 sparse -structures, along with a similar `isextended' flag that the header had. -There can be an indeterminate number of such `extended_header's to -describe a sparse file. - -`REGTYPE' -`AREGTYPE' - These flags represent a regular file. In order to be compatible - with older versions of `tar', a `typeflag' value of `AREGTYPE' - should be silently recognized as a regular file. New archives - should be created using `REGTYPE'. Also, for backward - compatibility, `tar' treats a regular file whose name ends with a - slash as a directory. - -`LNKTYPE' - This flag represents a file linked to another file, of any type, - previously archived. Such files are identified in Unix by each - file having the same device and inode number. The linked-to name - is specified in the `linkname' field with a trailing null. - -`SYMTYPE' - This represents a symbolic link to another file. The linked-to - name is specified in the `linkname' field with a trailing null. - -`CHRTYPE' -`BLKTYPE' - These represent character special files and block special files - respectively. In this case the `devmajor' and `devminor' fields - will contain the major and minor device numbers respectively. - Operating systems may map the device specifications to their own - local specification, or may ignore the entry. - -`DIRTYPE' - This flag specifies a directory or sub-directory. The directory - name in the `name' field should end with a slash. On systems where - disk allocation is performed on a directory basis, the `size' field - will contain the maximum number of bytes (which may be rounded to - the nearest disk block allocation unit) which the directory may - hold. A `size' field of zero indicates no such limiting. Systems - which do not support limiting in this manner should ignore the - `size' field. - -`FIFOTYPE' - This specifies a FIFO special file. Note that the archiving of a - FIFO file archives the existence of this file and not its contents. - -`CONTTYPE' - This specifies a contiguous file, which is the same as a normal - file except that, in operating systems which support it, all its - space is allocated contiguously on the disk. Operating systems - which do not allow contiguous allocation should silently treat this - type as a normal file. - -`A' ... `Z' - These are reserved for custom implementations. Some of these are - used in the GNU modified format, as described below. - - - Other values are reserved for specification in future revisions of -the P1003 standard, and should not be used by any `tar' program. - - The `magic' field indicates that this archive was output in the -P1003 archive format. If this field contains `TMAGIC', the `uname' and -`gname' fields will contain the ASCII representation of the owner and -group of the file respectively. If found, the user and group IDs are -used rather than the values in the `uid' and `gid' fields. - - For references, see ISO/IEC 9945-1:1990 or IEEE Std 1003.1-1990, -pages 169-173 (section 10.1) for `Archive/Interchange File Format'; and -IEEE Std 1003.2-1992, pages 380-388 (section 4.48) and pages 936-940 -(section E.4.48) for `pax - Portable archive interchange'. - - -File: tar.info, Node: Extensions, Next: Sparse Formats, Prev: Standard, Up: Tar Internals - -GNU Extensions to the Archive Format -==================================== - - _(This message will disappear, once this node revised.)_ - -The GNU format uses additional file types to describe new types of -files in an archive. These are listed below. - -`GNUTYPE_DUMPDIR' -`'D'' - This represents a directory and a list of files created by the - `--incremental' (`-G') option. The `size' field gives the total - size of the associated list of files. Each file name is preceded - by either a `Y' (the file should be in this archive) or an `N'. - (The file is a directory, or is not stored in the archive.) Each - file name is terminated by a null. There is an additional null - after the last file name. - -`GNUTYPE_MULTIVOL' -`'M'' - This represents a file continued from another volume of a - multi-volume archive created with the `--multi-volume' (`-M') - option. The original type of the file is not given here. The - `size' field gives the maximum size of this piece of the file - (assuming the volume does not end before the file is written out). - The `offset' field gives the offset from the beginning of the - file where this part of the file begins. Thus `size' plus - `offset' should equal the original size of the file. - -`GNUTYPE_SPARSE' -`'S'' - This flag indicates that we are dealing with a sparse file. Note - that archiving a sparse file requires special operations to find - holes in the file, which mark the positions of these holes, along - with the number of bytes of data to be found after the hole. - -`GNUTYPE_VOLHDR' -`'V'' - This file type is used to mark the volume header that was given - with the `--label=ARCHIVE-LABEL' (`-V ARCHIVE-LABEL') option when - the archive was created. The `name' field contains the `name' - given after the `--label=ARCHIVE-LABEL' (`-V ARCHIVE-LABEL') - option. The `size' field is zero. Only the first file in each - volume of an archive should have this type. - - - You may have trouble reading a GNU format archive on a non-GNU -system if the options `--incremental' (`-G'), `--multi-volume' (`-M'), -`--sparse' (`-S'), or `--label=ARCHIVE-LABEL' (`-V ARCHIVE-LABEL') were -used when writing the archive. In general, if `tar' does not use the -GNU-added fields of the header, other versions of `tar' should be able -to read the archive. Otherwise, the `tar' program will give an error, -the most likely one being a checksum error. - - -File: tar.info, Node: Sparse Formats, Next: Snapshot Files, Prev: Extensions, Up: Tar Internals - -Storing Sparse Files -==================== - -The notion of sparse file, and the ways of handling it from the point -of view of GNU `tar' user have been described in detail in *note -sparse::. This chapter describes the internal format GNU `tar' uses to -store such files. - - The support for sparse files in GNU `tar' has a long history. The -earliest version featuring this support that I was able to find was -1.09, released in November, 1990. The format introduced back then is -called "old GNU" sparse format and in spite of the fact that its design -contained many flaws, it was the only format GNU `tar' supported until -version 1.14 (May, 2004), which introduced initial support for sparse -archives in PAX archives (*note posix::). This format was not free -from design 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 - - -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. - - -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. - - -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'. - - -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'. - - - -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. - - -File: tar.info, Node: Genfile, Next: Free Software Needs Free Documentation, Prev: Tar Internals, Up: Top - -Appendix E Genfile -****************** - -This appendix describes `genfile', an auxiliary program used in the GNU -tar testsuite. If you are not interested in developing GNU tar, skip -this appendix. - - Initially, `genfile' was used to generate data files for the -testsuite, hence its name. However, new operation modes were being -implemented as the testsuite grew more sophisticated, and now `genfile' -is a multi-purpose instrument. - - There are three basic operation modes: - -File Generation - This is the default mode. In this mode, `genfile' generates data - files. - -File Status - In this mode `genfile' displays status of specified files. - -Synchronous Execution. - In this mode `genfile' executes the given program with - `--checkpoint' option and executes a set of actions when specified - checkpoints are reached. - -* Menu: - -* Generate Mode:: File Generation Mode. -* Status Mode:: File Status Mode. -* Exec Mode:: Synchronous Execution mode. - - -File: tar.info, Node: Generate Mode, Next: Status Mode, Up: Genfile - -E.1 Generate Mode -================= - -In this mode `genfile' creates a data file for the test suite. The size -of the file is given with the `--length' (`-l') option. By default the -file contents is written to the standard output, this can be changed -using `--file' (`-f') command line option. Thus, the following two -commands are equivalent: - - genfile --length 100 > outfile - genfile --length 100 --file outfile - - If `--length' is not given, `genfile' will generate an empty -(zero-length) file. - - The command line option `--seek=N' istructs `genfile' to skip the -given number of bytes (N) in the output file before writing to it. It -is similar to the `seek=N' of the `dd' utility. - - You can instruct `genfile' to create several files at one go, by -giving it `--files-from' (`-T') option followed by a name of file -containing a list of file names. Using dash (`-') instead of the file -name causes `genfile' to read file list from the standard input. For -example: - - # Read file names from file `file.list' - genfile --files-from file.list - # Read file names from standard input - genfile --files-from - - - The list file is supposed to contain one file name per line. To use -file lists separated by ASCII NUL character, use `--null' (`-0') -command line option: - - genfile --null --files-from file.list - - The default data pattern for filling the generated file consists of -first 256 letters of ASCII code, repeated enough times to fill the -entire file. This behavior can be changed with `--pattern' option. This -option takes a mandatory argument, specifying pattern name to use. -Currently two patterns are implemented: - -`--pattern=default' - The default pattern as described above. - -`--pattern=zero' - Fills the file with zeroes. - - If no file name was given, the program exits with the code `0'. -Otherwise, it exits with `0' only if it was able to create a file of -the specified length. - - Special option `--sparse' (`-s') instructs `genfile' to create a -sparse file. Sparse files consist of "data fragments", separated by -"holes" or blocks of zeros. On many operating systems, actual disk -storage is not allocated for holes, but they are counted in the length -of the file. To create a sparse file, `genfile' should know where to -put data fragments, and what data to use to fill them. So, when -`--sparse' is given the rest of the command line specifies a so-called -"file map". - - The file map consists of any number of "fragment descriptors". Each -descriptor is composed of two values: a number, specifying fragment -offset from the end of the previous fragment or, for the very first -fragment, from the beginning of the file, and "contents string", 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. - - -File: tar.info, Node: Status Mode, Next: Exec Mode, Prev: Generate Mode, Up: Genfile - -E.2 Status Mode -=============== - -In status mode, `genfile' prints file system status for each file -specified in the command line. This mode is toggled by `--stat' (`-S') -command line option. An optional argument to this option specifies -output "format": a comma-separated list of `struct stat' fields to be -displayed. This list can contain following identifiers : - -name - The file name. - -dev -st_dev - Device number in decimal. - -ino -st_ino - Inode number. - -mode[.NUMBER] -st_mode[.NUMBER] - File mode in octal. Optional NUMBER specifies octal mask to be - applied to the mode before outputting. For example, `--stat - mode.777' will preserve lower nine bits of it. Notice, that you - can use any punctuation character in place of `.'. - -nlink -st_nlink - Number of hard links. - -uid -st_uid - User ID of owner. - -gid -st_gid - Group ID of owner. - -size -st_size - File size in decimal. - -blksize -st_blksize - The size in bytes of each file block. - -blocks -st_blocks - Number of blocks allocated. - -atime -st_atime - Time of last access. - -mtime -st_mtime - Time of last modification - -ctime -st_ctime - Time of last status change - -sparse - A boolean value indicating whether the file is `sparse'. - - Modification times are displayed in UTC as UNIX timestamps, unless -suffixed with `H' (for "human-readable"), as in `ctimeH', in which case -usual `tar tv' output format is used. - - The default output format is: `name,dev,ino,mode, -nlink,uid,gid,size,blksize,blocks,atime,mtime,ctime'. - - For example, the following command will display file names and -corresponding times of last access for each file in the current working -directory: - - genfile --stat=name,atime * - - -File: tar.info, Node: Exec Mode, Prev: Status Mode, Up: Genfile - -E.3 Exec Mode -============= - -This mode is designed for testing the behavior of `paxutils' commands -when some of the files change during archiving. It is an experimental -mode. - - The `Exec Mode' is toggled by `--run' command line option (or its -alias `-r'). The 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. - - -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 . - - You can encourage commercial publishers to sell more free, copylefted -manuals and tutorials by buying them, and particularly by buying copies -from the publishers that paid for their writing or for major -improvements. Meanwhile, try to avoid buying non-free documentation at -all. Check the distribution terms of a manual before you buy it, and -insist that whoever seeks your business must respect your freedom. -Check the history of the book, and try reward the publishers that have -paid or pay the authors to work on it. - - The Free Software Foundation maintains a list of free documentation -published by other publishers, at -`http://www.fsf.org/doc/other-free-books.html'. - - -File: tar.info, Node: 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 - - -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. - - -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::. - -[index] -* 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) - - -File: tar.info, Node: Index, Prev: Index of Command Line Options, Up: Top - -Appendix I Index -**************** - -[index] -* 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) - - diff --git a/doc/tar.texi b/doc/tar.texi deleted file mode 100644 index 5898792..0000000 --- a/doc/tar.texi +++ /dev/null @@ -1,11458 +0,0 @@ -\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 . -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{}. - -@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: diff --git a/doc/texify.sed b/doc/texify.sed deleted file mode 100644 index a070b11..0000000 --- a/doc/texify.sed +++ /dev/null @@ -1,26 +0,0 @@ -# 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,\*/,}&, diff --git a/doc/untabify.el b/doc/untabify.el deleted file mode 100644 index 77dd5c0..0000000 --- a/doc/untabify.el +++ /dev/null @@ -1,13 +0,0 @@ -;;;; Untabify the sources. -;;;; Usage: emacs -batch -l untabify.el [file ...] - -(defun global-untabify (buflist) - (mapcar - (lambda (bufname) - (set-buffer (find-file bufname)) - (untabify (point-min) (point-max)) - (save-buffer) - (kill-buffer (current-buffer))) - buflist)) - -(global-untabify command-line-args-left) diff --git a/doc/value.texi b/doc/value.texi deleted file mode 100644 index e80311f..0000000 --- a/doc/value.texi +++ /dev/null @@ -1,22 +0,0 @@ -@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 - - diff --git a/doc/version.texi b/doc/version.texi deleted file mode 100644 index 580b586..0000000 --- a/doc/version.texi +++ /dev/null @@ -1,4 +0,0 @@ -@set UPDATED 14 April 2008 -@set UPDATED-MONTH April 2008 -@set EDITION 1.20 -@set VERSION 1.20 -- 2.43.0