X-Git-Url: https://git.dogcows.com/gitweb?a=blobdiff_plain;f=doc%2Ftar.texi;h=726661a9e5a143bb4cf947f683be883f17737c7d;hb=88ffc1355e95a1bbc8d1db7abf667aa3164e95e5;hp=72e1551e44419d8a1445b666882c28d990d201ac;hpb=7ac3cfedacb2f9a113fd80fd57443c703e3567e9;p=chaz%2Ftar diff --git a/doc/tar.texi b/doc/tar.texi index 72e1551..726661a 100644 --- a/doc/tar.texi +++ b/doc/tar.texi @@ -1,3956 +1,8530 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header +\input texinfo @c -*-texinfo-*- +@comment %**start of header @setfilename tar.info -@settitle The Tar Manual: DRAFT +@include version.texi +@settitle GNU tar @value{VERSION} @setchapternewpage odd + +@finalout + +@smallbook @c %**end of header -@c Note: the edition number and date is listed in *two* places; please update. -@c subtitle and top node; search for !!set +@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 tar 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 ====================================================================== + +@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 --------------------------------------------------------------------- +@c The @FIXME's, @UNREVISED and @c comments are part Fran@,{c}ois's work +@c plan. These annotations are somewhat precious to him; he asks that I +@c do not alter them inconsiderately. Much work is needed for GNU tar +@c internals (the sources, the programs themselves). Revising the +@c adequacy of the manual while revising the sources, and cleaning them +@c both at the same time, seems to him like a good way to proceed. +@c --------------------------------------------------------------------- + +@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} +@allow-recursion +@quote-arg +@ifset PROOF +@strong{} \string\ @strong{} +@end ifset + +@end macro + +@macro FIXME-ref{string} +@quote-arg +@ifset PROOF +@strong{} \string\ @strong{} +@end ifset + +@end macro + +@macro FIXME-pxref{string} +@quote-arg +@ifset PROOF +@strong{} \string\ @strong{} +@end ifset + +@end macro + +@macro FIXME-xref{string} +@quote-arg +@ifset PROOF +@strong{} \string\ @strong{} +@end ifset + +@end macro + +@c @macro option{entry} +@c @quote-arg +@c @opindex{--\entry\} +@c @value{\entry\} +@c @end macro + +@set op-absolute-names @kbd{--absolute-names} (@kbd{-P}) +@set ref-absolute-names @ref{absolute} +@set xref-absolute-names @xref{absolute} +@set pxref-absolute-names @pxref{absolute} + +@set op-after-date @kbd{--after-date=@var{date}} (@kbd{--newer=@var{date}}, @kbd{-N @var{date}}) +@set ref-after-date @ref{after} +@set xref-after-date @xref{after} +@set pxref-after-date @pxref{after} + +@set op-append @kbd{--append} (@kbd{-r}) +@set ref-append @ref{add} +@set xref-append @xref{add} +@set pxref-append @pxref{add} + +@set op-atime-preserve @kbd{--atime-preserve} +@set ref-atime-preserve @ref{Attributes} +@set xref-atime-preserve @xref{Attributes} +@set pxref-atime-preserve @pxref{Attributes} + +@set op-backup @kbd{--backup} +@set ref-backup @ref{Backup options} +@set xref-backup @xref{Backup options} +@set pxref-backup @pxref{Backup options} + +@set op-block-number @kbd{--block-number} (@kbd{-R}) +@set ref-block-number @ref{verbose} +@set xref-block-number @xref{verbose} +@set pxref-block-number @pxref{verbose} + +@set op-blocking-factor @kbd{--blocking-factor=@var{512-size}} (@kbd{-b @var{512-size}}) +@set ref-blocking-factor @ref{Blocking Factor} +@set xref-blocking-factor @xref{Blocking Factor} +@set pxref-blocking-factor @pxref{Blocking Factor} + +@set op-bzip2 @kbd{--bzip2} (@kbd{-j}) +@set ref-bzip2 @ref{gzip} +@set xref-bzip2 @xref{gzip} +@set pxref-bzip2 @pxref{gzip} + +@set op-checkpoint @kbd{--checkpoint} +@set ref-checkpoint @ref{verbose} +@set xref-checkpoint @xref{verbose} +@set pxref-checkpoint @pxref{verbose} + +@set op-compare @kbd{--compare} (@kbd{--diff}, @kbd{-d}) +@set ref-compare @ref{compare} +@set xref-compare @xref{compare} +@set pxref-compare @pxref{compare} + +@set op-compress @kbd{--compress} (@kbd{--uncompress}, @kbd{-Z}) +@set ref-compress @ref{gzip} +@set xref-compress @xref{gzip} +@set pxref-compress @pxref{gzip} + +@set op-concatenate @kbd{--concatenate} (@kbd{--catenate}, @kbd{-A}) +@set ref-concatenate @ref{concatenate} +@set xref-concatenate @xref{concatenate} +@set pxref-concatenate @pxref{concatenate} + +@set op-create @kbd{--create} (@kbd{-c}) +@set ref-create @ref{create} +@set xref-create @xref{create} +@set pxref-create @pxref{create} + +@set op-delete @kbd{--delete} +@set ref-delete @ref{delete} +@set xref-delete @xref{delete} +@set pxref-delete @pxref{delete} + +@set op-dereference @kbd{--dereference} (@kbd{-h}) +@set ref-dereference @ref{dereference} +@set xref-dereference @xref{dereference} +@set pxref-dereference @pxref{dereference} + +@set op-directory @kbd{--directory=@var{directory}} (@kbd{-C @var{directory}}) +@set ref-directory @ref{directory} +@set xref-directory @xref{directory} +@set pxref-directory @pxref{directory} + +@set op-exclude @kbd{--exclude=@var{pattern}} +@set ref-exclude @ref{exclude} +@set xref-exclude @xref{exclude} +@set pxref-exclude @pxref{exclude} + +@set op-exclude-from @kbd{--exclude-from=@var{file-of-patterns}} (@kbd{-X @var{file-of-patterns}}) +@set ref-exclude-from @ref{exclude} +@set xref-exclude-from @xref{exclude} +@set pxref-exclude-from @pxref{exclude} + +@set op-extract @kbd{--extract} (@kbd{--get}, @kbd{-x}) +@set ref-extract @ref{extract} +@set xref-extract @xref{extract} +@set pxref-extract @pxref{extract} + +@set op-file @kbd{--file=@var{archive-name}} (@kbd{-f @var{archive-name}}) +@set ref-file @ref{file} +@set xref-file @xref{file} +@set pxref-file @pxref{file} + +@set op-files-from @kbd{--files-from=@var{file-of-names}} (@kbd{-T @var{file-of-names}}) +@set ref-files-from @ref{files} +@set xref-files-from @xref{files} +@set pxref-files-from @pxref{files} + +@set op-force-local @kbd{--force-local} +@set ref-force-local @ref{file} +@set xref-force-local @xref{file} +@set pxref-force-local @pxref{file} + +@set op-group @kbd{--group=@var{group}} +@set ref-group @ref{Option Summary} +@set xref-group @xref{Option Summary} +@set pxref-group @pxref{Option Summary} + +@set op-gzip @kbd{--gzip} (@kbd{--gunzip}, @kbd{--ungzip}, @kbd{-z}) +@set ref-gzip @ref{gzip} +@set xref-gzip @xref{gzip} +@set pxref-gzip @pxref{gzip} + +@set op-help @kbd{--help} +@set ref-help @ref{help} +@set xref-help @xref{help} +@set pxref-help @pxref{help} + +@set op-ignore-failed-read @kbd{--ignore-failed-read} +@set ref-ignore-failed-read @ref{create options} +@set xref-ignore-failed-read @xref{create options} +@set pxref-ignore-failed-read @pxref{create options} + +@set op-ignore-zeros @kbd{--ignore-zeros} (@kbd{-i}) +@set ref-ignore-zeros @ref{Reading} +@set xref-ignore-zeros @xref{Reading} +@set pxref-ignore-zeros @pxref{Reading} + +@set op-incremental @kbd{--incremental} (@kbd{-G}) +@set ref-incremental @ref{Inc Dumps} +@set xref-incremental @xref{Inc Dumps} +@set pxref-incremental @pxref{Inc Dumps} + +@set op-info-script @kbd{--info-script=@var{script-name}} (@kbd{--new-volume-script=@var{script-name}}, @kbd{-F @var{script-name}}) +@set ref-info-script @ref{Multi-Volume Archives} +@set xref-info-script @xref{Multi-Volume Archives} +@set pxref-info-script @pxref{Multi-Volume Archives} + +@set op-interactive @kbd{--interactive} (@kbd{-w}) +@set ref-interactive @ref{interactive} +@set xref-interactive @xref{interactive} +@set pxref-interactive @pxref{interactive} + +@set op-keep-old-files @kbd{--keep-old-files} (@kbd{-k}) +@set ref-keep-old-files @ref{Writing} +@set xref-keep-old-files @xref{Writing} +@set pxref-keep-old-files @pxref{Writing} + +@set op-label @kbd{--label=@var{archive-label}} (@kbd{-V @var{archive-label}}) +@set ref-label @ref{label} +@set xref-label @xref{label} +@set pxref-label @pxref{label} + +@set op-list @kbd{--list} (@kbd{-t}) +@set ref-list @ref{list} +@set xref-list @xref{list} +@set pxref-list @pxref{list} + +@set op-listed-incremental @kbd{--listed-incremental=@var{snapshot-file}} (@kbd{-g @var{snapshot-file}}) +@set ref-listed-incremental @ref{Inc Dumps} +@set xref-listed-incremental @xref{Inc Dumps} +@set pxref-listed-incremental @pxref{Inc Dumps} + +@set op-mode @kbd{--mode=@var{permissions}} +@set ref-mode @ref{Option Summary} +@set xref-mode @xref{Option Summary} +@set pxref-mode @pxref{Option Summary} + +@set op-multi-volume @kbd{--multi-volume} (@kbd{-M}) +@set ref-multi-volume @ref{Multi-Volume Archives} +@set xref-multi-volume @xref{Multi-Volume Archives} +@set pxref-multi-volume @pxref{Multi-Volume Archives} + +@set op-newer-mtime @kbd{--newer-mtime=@var{date}} +@set ref-newer-mtime @ref{after} +@set xref-newer-mtime @xref{after} +@set pxref-newer-mtime @pxref{after} + +@set op-no-recursion @kbd{--no-recursion} +@set ref-no-recursion @ref{recurse} +@set xref-no-recursion @xref{recurse} +@set pxref-no-recursion @pxref{recurse} + +@set op-no-same-owner @kbd{--no-same-owner} +@set ref-no-same-owner @ref{Attributes} +@set xref-no-same-owner @xref{Attributes} +@set pxref-no-same-owner @pxref{Attributes} + +@set op-no-same-permissions @kbd{--no-same-permissions} +@set ref-no-same-permissions @ref{Attributes} +@set xref-no-same-permissions @xref{Attributes} +@set pxref-no-same-permissions @pxref{Attributes} + +@set op-null @kbd{--null} +@set ref-null @ref{files} +@set xref-null @xref{files} +@set pxref-null @pxref{files} + +@set op-numeric-owner @kbd{--numeric-owner} +@set ref-numeric-owner @ref{Attributes} +@set xref-numeric-owner @xref{Attributes} +@set pxref-numeric-owner @pxref{Attributes} + +@set op-old-archive @kbd{--old-archive} (@kbd{-o}) +@set ref-old-archive @ref{old} +@set xref-old-archive @xref{old} +@set pxref-old-archive @pxref{old} + +@set op-one-file-system @kbd{--one-file-system} (@kbd{-l}) +@set ref-one-file-system @ref{one} +@set xref-one-file-system @xref{one} +@set pxref-one-file-system @pxref{one} + +@set op-overwrite @kbd{--overwrite} +@set ref-overwrite @ref{Overwrite Old Files} +@set xref-overwrite @xref{Overwrite Old Files} +@set pxref-overwrite @pxref{Overwrite Old Files} + +@set op-owner @kbd{--owner=@var{user}} +@set ref-owner @ref{Option Summary} +@set xref-owner @xref{Option Summary} +@set pxref-owner @pxref{Option Summary} + +@set op-posix @kbd{--posix} +@set ref-posix @ref{posix} +@set xref-posix @xref{posix} +@set pxref-posix @pxref{posix} + +@set op-preserve @kbd{--preserve} +@set ref-preserve @ref{Attributes} +@set xref-preserve @xref{Attributes} +@set pxref-preserve @pxref{Attributes} + +@set op-record-size @kbd{--record-size=@var{size}} +@set ref-record-size @ref{Blocking} +@set xref-record-size @xref{Blocking} +@set pxref-record-size @pxref{Blocking} + +@set op-recursive-unlink @kbd{--recursive-unlink} +@set ref-recursive-unlink @ref{Writing} +@set xref-recursive-unlink @xref{Writing} +@set pxref-recursive-unlink @pxref{Writing} + +@set op-read-full-records @kbd{--read-full-records} (@kbd{-B}) +@set ref-read-full-records @ref{Blocking} +@set xref-read-full-records @xref{Blocking} +@set pxref-read-full-records @pxref{Blocking} +@c FIXME: or should it be Reading, or Blocking Factor + +@set op-remove-files @kbd{--remove-files} +@set ref-remove-files @ref{Writing} +@set xref-remove-files @xref{Writing} +@set pxref-remove-files @pxref{Writing} + +@set op-rsh-command @kbd{rsh-command=@var{command}} + +@set op-same-order @kbd{--same-order} (@kbd{--preserve-order}, @kbd{-s}) +@set ref-same-order @ref{Scarce} +@set xref-same-order @xref{Scarce} +@set pxref-same-order @pxref{Scarce} +@c FIXME: or should it be Reading, or Attributes? + +@set op-same-owner @kbd{--same-owner} +@set ref-same-owner @ref{Attributes} +@set xref-same-owner @xref{Attributes} +@set pxref-same-owner @pxref{Attributes} + +@set op-same-permissions @kbd{--same-permissions} (@kbd{--preserve-permissions}, @kbd{-p}) +@set ref-same-permissions @ref{Attributes} +@set xref-same-permissions @xref{Attributes} +@set pxref-same-permissions @pxref{Attributes} +@c FIXME: or should it be Writing? + +@set op-show-omitted-dirs @kbd{--show-omitted-dirs} +@set ref-show-omitted-dirs @ref{verbose} +@set xref-show-omitted-dirs @xref{verbose} +@set pxref-show-omitted-dirs @pxref{verbose} + +@set op-sparse @kbd{--sparse} (@kbd{-S}) +@set ref-sparse @ref{sparse} +@set xref-sparse @xref{sparse} +@set pxref-sparse @pxref{sparse} + +@set op-starting-file @kbd{--starting-file=@var{name}} (@kbd{-K @var{name}}) +@set ref-starting-file @ref{Scarce} +@set xref-starting-file @xref{Scarce} +@set pxref-starting-file @pxref{Scarce} + +@set op-suffix @kbd{--suffix=@var{suffix}} +@set ref-suffix @ref{Backup options} +@set xref-suffix @xref{Backup options} +@set pxref-suffix @pxref{Backup options} + +@set op-tape-length @kbd{--tape-length=@var{1024-size}} (@kbd{-L @var{1024-size}}) +@set ref-tape-length @ref{Using Multiple Tapes} +@set xref-tape-length @xref{Using Multiple Tapes} +@set pxref-tape-length @pxref{Using Multiple Tapes} + +@set op-to-stdout @kbd{--to-stdout} (@kbd{-O}) +@set ref-to-stdout @ref{Writing} +@set xref-to-stdout @xref{Writing} +@set pxref-to-stdout @pxref{Writing} + +@set op-totals @kbd{--totals} +@set ref-totals @ref{verbose} +@set xref-totals @xref{verbose} +@set pxref-totals @pxref{verbose} + +@set op-touch @kbd{--touch} (@kbd{-m}) +@set ref-touch @ref{Writing} +@set xref-touch @xref{Writing} +@set pxref-touch @pxref{Writing} + +@set op-unlink-first @kbd{--unlink-first} (@kbd{-U}) +@set ref-unlink-first @ref{Writing} +@set xref-unlink-first @xref{Writing} +@set pxref-unlink-first @pxref{Writing} + +@set op-update @kbd{--update} (@kbd{-u}) +@set ref-update @ref{update} +@set xref-update @xref{update} +@set pxref-update @pxref{update} + +@set op-use-compress-prog @kbd{--use-compress-prog=@var{program}} +@set ref-use-compress-prog @ref{gzip} +@set xref-use-compress-prog @xref{gzip} +@set pxref-use-compress-prog @pxref{gzip} + +@set op-verbose @kbd{--verbose} (@kbd{-v}) +@set ref-verbose @ref{verbose} +@set xref-verbose @xref{verbose} +@set pxref-verbose @pxref{verbose} + +@set op-verify @kbd{--verify} (@kbd{-W}) +@set ref-verify @ref{verify} +@set xref-verify @xref{verify} +@set pxref-verify @pxref{verify} + +@set op-version @kbd{--version} +@set ref-version @ref{help} +@set xref-version @xref{help} +@set pxref-version @pxref{help} + +@set op-volno-file @kbd{--volno-file=@var{file-of-number}} +@set ref-volno-file @ref{Using Multiple Tapes} +@set xref-volno-file @xref{Using Multiple Tapes} +@set pxref-volno-file @pxref{Using Multiple Tapes} + +@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 + +@defindex op +@syncodeindex op 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 Free Software Foundation, Inc. -@c Search for comments marked with !! or <<< (or >>>) +@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 the +Invariant Sections being "GNU General Public License", with the +Front-Cover Texts being ``A GNU Manual,'' and with the Back-Cover Texts +as in (a) below. A copy of the license is included in the section +entitled "GNU Free Documentation License". + +(a) The FSF's Back-Cover Text is: ``You are free to copy and modify +this GNU Manual. Buying copies from GNU Press supports the FSF in +developing GNU and promoting software freedom.'' +@end quotation +@end copying -@c <<< CONVENTIONS: this manual refers to "ordinary files" , "directory -files" (or "directories"), "archive files", "archive members", and -various I/O devices (which have names and file names).>>> +@dircategory Archiving +@direntry +* Tar: (tar). Making tape (or disk) archives. +@end direntry -@c <<< it's "file name" (not filename) unless we are talking about an -argument, ie. @var{file-name}. also, you "use" a "file-name argument" -to "specify" a "file".>>> +@dircategory Individual utilities +@direntry +* tar: (tar)tar invocation. Invoking @acronym{GNU} @command{tar} +@end direntry -@c <<< @code{tar} is always lower case, in bold. >>> +@shorttitlepage @acronym{GNU} @command{tar} -@c <<< it's "operations of tar", "options to tar" also, it's " @samp{tar -+foo}" or "the @samp{+foo} operation". MIB doesn't like using -operations and options as separate concepts. I disagree --- would be a -mess to explain otherwise +@titlepage +@title @acronym{GNU} tar: an archiver tool +@subtitle @value{RENDITION} @value{VERSION}, @value{UPDATED} +@author Melissa Weisshaus, Jay Fenlason, +@author Thomas Bushnell, n/BSG, Amy Gorin +@c he said to remove it: Fran@,{c}ois Pinard +@c i'm thinking about how the author page *should* look. -mew 2may96 -@c <<< (don't forget to comment these out in final draft) -ringo +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage -@c <<< please dont' change this without sending me e-mail. some things -@c are in progress or waiting to be edited in hardcopy. -ringo -@c smallbook +@ifnottex +@node Top +@top @acronym{GNU} tar: an archiver tool -@iftex -@c finalout -@end iftex +@insertcopying -@ifinfo -This file documents @code{tar}, a utility used to store, backup, and -transport files. +@cindex file archival +@cindex archiving files -Copyright (C) 1992 Free Software Foundation, Inc. DRAFT! -@c Need to put distribution information here when ready. -@end ifinfo +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 !!set edition number and date here -@titlepage -@title @code{tar} -@subtitle The GNU Tape Archiver -@subtitle Edition 0.01, for @code{tar} Version 1.10 -@subtitle @today{} -@c remove preceding today line when ready -@sp 1 -@subtitle DRAFT -@c subtitle insert month here when ready - -@author Amy Gorin and Jay Fenlason -@c <<>>> +@c The master menu, created with texinfo-master-menu, goes here. +@c (However, getdate.texi's menu is interpolated by hand.) -@page -@vskip 0pt plus 1filll -Copyright @copyright{} 1992 Free Software Foundation, Inc. +@menu +* Introduction:: +* Tutorial:: +* tar invocation:: +* operations:: +* Backups:: +* Choosing:: +* Date input formats:: +* Formats:: +* Media:: +* Free Software Needs Free Documentation:: +* Copying This Manual:: +* Index:: + +@detailmenu + --- The Detailed Node Listing --- -@sp 2 -This draft is not yet ready for distribution. -@end titlepage +Introduction -@ifinfo -@node Top, Introduction, (dir), (dir) -@top @code{tar} +* 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 +* posix compliance:: +* Authors:: @acronym{GNU} @command{tar} Authors +* Reports:: Reporting bugs or suggestions -This file documents @code{tar}, a utility used to store, backup, and -transport files. +Tutorial Introduction to @command{tar} -@c !!set edition number and date here -This is DRAFT Edition 0.01 of the @code{tar} documentation, @today{}, for @code{tar} -version 1.12. -@end ifinfo +* 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:: -@c <<< The menus need to be gone over, and node names fixed. -@menu -* Introduction:: @code{tar}: The GNU Tape Archiver -* Invoking @code{tar}:: How to invoke @code{tar} -* Tutorial:: Getting started -* Wizardry:: Some More Advanced Uses for @code{tar} -* Archive Structure:: The structure of an archive -* Reading and Writing:: Reading and writing archives -* Insuring Accuracy:: How to insure the accuracy of an archive -* Selecting Archive Members:: How to select archive members -* User Interaction:: How @code{tar} interacts with people. -* Backups and Restoration:: How to restore files and perform backups -* Media:: Using tapes and other archive media -* Quick Reference:: A quick reference guide to - @code{tar} operations and options -* Data Format Details:: Details of the archive data format -* Concept Index:: Concept Index -@end menu +Two Frequently Used Options -@node Introduction, Invoking @code{tar}, Top, Top -@chapter @code{tar}: The GNU Tape Archiver +* file tutorial:: +* verbose tutorial:: +* help tutorial:: -You can use @code{tar} to create an @dfn{archive}---a single file -which contains other file's contents as well as a listing of those -files' characteristics. You can also use @code{tar} to read, add to, -or manipulate already existing archives. Because an archive created -by @code{tar} is capable of preserving file information and directory -structure, @code{tar} is ideal for performing full and incremental -backups, as well as for transferring groups of files between disks and -over networks. +How to Create Archives -Despite the utility's name, which comes from the words @samp{T(ape)} -@samp{AR(chiver)}, @code{tar}'s output can be directed to any -available device. For instance, @code{tar} archives can be stored in -a file or sent to another program via a pipe. +* prepare for examples:: +* Creating the archive:: +* create verbose:: +* short create:: +* create dir:: -@c <<< this menu will conflict with menu above in info mode. -ringo -@menu -* Invoking @code{tar}:: How to invoke @code{tar} and specify arguments. -* Tutorial:: An introduction to @code{tar}. -* Operations:: What you can use @code{tar} to do. -* Options:: How to change the way @code{tar} behaves. -* Problems:: Common problems with @code{tar}. -@end menu +How to List Archives -@node Invoking @code{tar}, Tutorial, Introduction, Top -@chapter How To Invoke @code{tar} +* list dir:: -You can use @code{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 @code{tar}, which is called the @dfn{operation}, -specifies which action to take. The other arguments to @code{tar} are -either @dfn{options}, which change the way @code{tar} performs an -operation, or @dfn{file-names}, which specify the files @code{tar} is -to act on. The typical @code{tar} command line syntax is: +How to Extract Members from an Archive -@example -@code{tar} @var{operation} [@var{options}...] [@var{file-names}...] -@end example +* extracting archives:: +* extracting files:: +* extract dir:: +* failing commands:: -Note: You can actually type in arguments in any order. In this manual -the operation is always first, the options second and the file-name -arguments last, to make examples easier to understand. +Invoking @acronym{GNU} @command{tar} -@menu -* Argument Functions:: The Functions of Arguments -* Argument Form:: The Forms of Arguments -* Old Syntax for Commands:: An Old, but Still Supported, Syntax - for @code{tar} Commands -@end menu +* Synopsis:: +* using tar options:: +* Styles:: +* All Options:: +* help:: +* verbose:: +* interactive:: -@node Argument Functions, Argument Form, Invoking @code{tar}, Invoking @code{tar} -@section The Functions of Arguments +The Three Option Styles -The primary argument to @code{tar} is the @dfn{operation}, which -specifies what @code{tar} does. @code{tar} can be used to: +* Mnemonic Options:: Mnemonic Option Style +* Short Options:: Short Option Style +* Old Options:: Old Option Style +* Mixing:: Mixing Option Styles -@itemize -@item -Add files to an existing archive (@samp{+add-file}, @samp+{append} or -@samp{-r}) +All @command{tar} Options -@item -Compare files in an archive with files in the file system -(@samp{+compare}, @samp{+diff} or @samp{-d}) -@c !!! is diff still working?? --- yes -ringo +* Operation Summary:: +* Option Summary:: +* Short Option Summary:: -@item -Add archives to another archive (@samp{+add-archive}, @samp{+catenate} -or @samp{-A}) -@c was +concatenate. -ringo +@acronym{GNU} @command{tar} Operations -@item -Create an archive (@samp{+create} or @samp{-c}) +* Basic tar:: +* Advanced tar:: +* create options:: +* extract options:: +* backup:: +* Applications:: +* looking ahead:: -@item -Delete files from an archive (@samp{+delete}) -@c -D should have been removed -ringo +Advanced @acronym{GNU} @command{tar} Operations -@item -Extract files from an archive (@samp{+extract}, @samp{+get} or @samp{-x}) +* Operations:: +* append:: +* update:: +* concatenate:: +* delete:: +* compare:: -@item -List the files in an archive (@samp{+list} or @samp{-t}) +How to Add Files to Existing Archives: @code{--append} -@item -Update an archive by appending newer versions of already stored files -(@samp{+update} or @samp{-u}) -@end itemize +* appending files:: Appending Files to an Archive +* multiple:: -@xref{Reading and Writing}, for more information about these -operations. - -@dfn{Option} arguments to @code{tar} change details of the operation, -such as archive format, archive name, or level of user interaction. -You can specify more than one option. All options are optional. - -@dfn{File-name} arguments specify which files (including directory -files) to archive, extract, delete or otherwise operate on. - -If you don't use any file-name arguments, @samp{+add-file}, -@samp{+update} and @samp{+delete} will do nothing. The other -operations of @code{tar} will act on defaults. - -When you use a file-name argument to specify a directory file, -@code{tar} acts on all the files in that directory, including -sub-directories. - -@node Argument Form, Old Syntax for Commands, Argument Functions, Invoking @code{tar} -@section The Forms of Arguments - -Most operations of @code{tar} have a single letter form (a single -letter preceded by a @samp{-}), and at least one mnemonic form (a -word or abbreviation preceded by a @samp{+}). The forms are -identical in function. For example, you can use either @samp{tar -t} -or @samp{tar +list} to list the contents of an archive - -Options, like operations, have both single letter and mnemonic forms. -Options, however, may also incorporate an argument. Single letter -options are separated from their arguments by a space. Mnemonic -options are separated from their arguments by an @samp{=} sign. For -example, to create an an archive file named @file{george}, use either -@samp{tar +create +file=george} or @samp{tar +create -f george}. Both -@samp{+file=@var{archive-name}} and @samp{-f @var{archive-name}} -denote the option to give the archive a non-default name, which in the -example is @samp{george}. - -You can mix single letter and mnemonic forms in the same command. You -could type the above example as @samp{tar -c +file=george} or -@samp{tar +create -f george}. However, @code{tar} operations and -options are case sensitive. You would not type the above example as -@samp{tar -C +file=george}, because @samp{-C} is an option that causes -@code{tar} to change directories, not an operation that creates an -archive. +Updating an Archive -File-name arguments are the names of files (including directories). -These names can be specified on the command line or read from a text -file in the file system (using the @samp{+files-from} option). Files -stored in an archive are called @dfn{archive members}. The operations -@samp{+delete}, @samp{+extract}, @samp{+list}, @samp{+compare} and -@samp{+update} take the names of archive members as file-name -arguments. The other operations take the names of files in the file -system. +* how to update:: -@code{tar} interprets relative file names as being relative to the -working directory. @code{tar} will make all file names relative (by -removing leading @samp{/}s when archiving or restoring files), unless -you specify otherwise (using the @samp{+absolute-paths} option). -@xref{File Name Interpretation}, for more information about -@samp{+absolute-paths}. -@c >>> yet another node name that is probably wrong. +Options Used by @code{--create} -@node Old Syntax for Commands, , Argument Form, Invoking @code{tar} -@section An Old, but Still Supported, Syntax for @code{tar} Commands +* Ignore Failed Read:: -For historical reasons, GNU @code{tar} also accepts a syntax for -commands which splits options that include arguments into two parts. -That syntax is of the form: +Options Used by @code{--extract} -@example -@code{tar} @var{operation}[@var{option-letters}...] [@var{option-arguments}...] [@var{file-names}...]@refill -@end example +* Reading:: Options to Help Read Archives +* Writing:: Changing How @command{tar} Writes Files +* Scarce:: Coping with Scarce Resources -@noindent -where arguments to the options appear in the same order as the letters -to which they correspond, and the operation and all the option letters -appear as a single argument, without separating spaces. - -This command syntax is useful because it lets you type the single -letter forms of the operation and options as a single argument to -@code{tar}, without writing preceding @samp{-}s or inserting spaces -between letters. @samp{tar cv} or @samp{tar -cv} are equivalent to -@samp{tar -c -v}. - -This old style syntax makes it difficult to match option letters with -their corresponding arguments, and is often confusing. In the command -@samp{tar cvbf 20 /dev/rmt0}, for example, @samp{20} is the argument -for @samp{-b}, @samp{/dev/rmt0} is the argument for @samp{-f}, and -@samp{-v} does not have a corresponding argument. The modern -syntax---@samp{tar -c -v -b 20 -f /dev/rmt0}---is clearer. - -@node Tutorial, Wizardry, Invoking @code{tar}, Top -@chapter Getting Started With @code{tar} - -This chapter guides you through some basic examples of @code{tar} -operations. In the examples, the lines you should type are preceded -by a @samp{%}, which is a typical shell prompt. We use mnemonic forms -of operations and options in the examples, and in discussions in the -text, but short forms produce the same result. +Options to Help Read Archives -@menu -* Creating Archives:: Creating Archives -* Extracting Files:: Extracting Files from an Archive -* Listing Archive Contents:: Listing the Contents of an Archive -* Comparing Files:: Comparing Archives with the File System -* Adding to Archives:: Adding Files to Existing Archives -* Concatenate:: Concatenating Archives -* Deleting Files:: Deleting Files From an Archive -@end menu +* read full records:: +* Ignore Zeros:: -@node Creating Archives, Listing Archive Contents, Tutorial, Tutorial -@section Creating Archives +Changing How @command{tar} Writes Files -To create a new archive, use @code{tar +create} (or @code{tar -c}). -You can use options to specify the name and format of the archive (as -well as other characteristics), and you can use file-name arguments to -specify which files to put in the archive. If you don't use any -options or file-name arguments, @code{tar} will use default values. -@xref{Creating Example}, for more information about the @samp{+create} -operation. +* Dealing with Old Files:: +* Overwrite Old Files:: +* Keep Old Files:: +* Unlink First:: +* Recursive Unlink:: +* Modification Times:: +* Setting Access Permissions:: +* Writing to Standard Output:: +* remove files:: -@menu -* Creating Example:: Creating Archives of Files -* Subdirectory:: Creating an Archive of a Subdirectory -@end menu +Coping with Scarce Resources -@node Creating Example, Subdirectory, Creating Archives, Creating Archives -@subsection Creating Archives of Files +* Starting File:: +* Same Order:: -This example shows you how to create an archive file in the working -directory containing other files in the working directory. The three -files you archive in this example are called @file{blues}, -@file{folk}, and @file{jazz}. The archive file is called -@file{records}. While the archive in this example is written to the -file system, it could also be written to any other device. +Performing Backups and Restoring Files -(If you want to follow along with this and future examples, create a -directory called @file{practice} containing files called @file{blues}, -@file{folk} and @file{jazz}. To create the directory, type -@samp{mkdir practice} at the system prompt. It will probably be -easiest to create the files using a text editor, such as Emacs.) +* Full Dumps:: Using @command{tar} to Perform Full Dumps +* Inc Dumps:: Using @command{tar} to Perform Incremental Dumps +* incremental and listed-incremental:: The Incremental Options +* 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 -First, change into the directory containing the files you want to -archive: +Setting Parameters for Backups and Restoration -@example -% cd practice -@end example +* backup-specs example:: An Example Text of @file{Backup-specs} +* Script Syntax:: Syntax for @file{Backup-specs} -@noindent -@file{~/practice} is now your working directory. +Choosing Files and Names for @command{tar} -Then, check that the files to be archived do in fact exist in the -working directory, and make sure there isn't already a file in the -working directory with the archive name you intend to use. If you -specify an archive file name that is already in use, @code{tar} will -overwrite the old file and its contents will be lost. +* file:: Choosing the Archive's Name +* Selecting Archive Members:: +* files:: Reading Names from a File +* exclude:: Excluding Some Files +* Wildcards:: +* after:: Operating Only on New Files +* recurse:: Descending into Directories +* one:: Crossing Filesystem Boundaries -To list the names of files in the working directory, type: +Reading Names from a File -@example -% ls -@end example +* nul:: -The system responds: +Excluding Some Files -@example -blues folk jazz -% -@end example +* controlling pattern-patching with exclude:: +* problems with exclude:: -@noindent -Then, -@itemize @bullet -@item -Create a new archive (@samp{tar -c} or @samp{tar +create}) +Crossing Filesystem Boundaries -@item -Explicitly name the archive file being created (@samp{-f -@var{archive-name}} or @samp{+file=@var{archive-name}}). If you don't -use this option @code{tar} will write the archive to the default -storage device, which varies from system to system. -@c <<< this syntax may change. OK now---check before printing -ringo +* directory:: Changing Directory +* absolute:: Absolute File Names -@code{tar} interprets archive file names relative to the working -directory. Make sure you have write access to the working directory -before using @code{tar}. +Date input formats -@item -Specify which files to put into the archive (@code{tar} interprets -file names relative to the working directory). If you don't use any -@var{file-name} arguments, @code{tar} will archive everything in the -working directory. -@end itemize +* 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. +* Authors of getdate:: Bellovin, Eggert, Salz, Berets, et al. -@noindent -Type: -@example -% tar +create +file=records blues folk jazz -@end example +Controlling the Archive Format -@noindent -If you now list the contents of the working directory (@samp{ls}), you -will find the archive file listed as well as the files you saw -previously. +* Portability:: Making @command{tar} Archives More Portable +* Compression:: Using Less Space through Compression +* Attributes:: Handling File Attributes +* Standard:: The Standard Format +* Extensions:: @acronym{GNU} Extensions to the Archive Format +* cpio:: Comparison of @command{tar} and @command{cpio} -@example -% ls -blues folk jazz records -% -@end example +Making @command{tar} Archives More Portable -@menu -* Listing Files:: Listing files in an archive -* Verbose:: Using @code{tar} in Verbose Mode -@end menu +* Portable Names:: Portable Names +* dereference:: Symbolic Links +* old:: Old V7 Archives +* posix:: @sc{posix} archives +* Checksumming:: Checksumming Problems +* Large or Negative Values:: Large files, negative time stamps, etc. -@node Listing Files, Verbose, Creating Example, Creating Example -@subsubsection Listing files in an archive +Using Less Space through Compression -You can list the contents of an archive with another operation of -@code{tar}---@samp{+list} or @samp{-l}. To list the contents of the -archive you just created, type: +* gzip:: Creating and Reading Compressed Archives +* sparse:: Archiving Sparse Files -@example -% tar +list +file=records -@end example +Tapes and Other Archive Media -@noindent -@code{tar} will respond: +* 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:: -@example -blues folk jazz -@end example +Blocking -@xref{Listing Archive Contents}, for a more detailed tutorial of the -@samp{+list} operation. @xref{Listing Contents}, for more information -about the @samp{+list} operation. +* Format Variations:: Format Variations +* Blocking Factor:: The Blocking Factor of an Archive -@node Verbose, , Listing Files, Creating Example -@subsubsection Using @code{tar} in Verbose Mode +Many Archives on One Tape -If you include the @samp{+verbose} or @samp{-v} option on the command -line, @code{tar} will list the files it is acting on as it is working. -In verbose mode, the creation example above would appear as: -@cindex Verbose mode example -@findex -v (verbose mode example) +* Tape Positioning:: Tape Positions and Tape Marks +* mt:: The @command{mt} Utility -@example -% tar +create +file=records +verbose blues folk jazz -blues -folk -jazz -@end example +Using Multiple Tapes -@noindent -The first line is the command typed in by the user. The remaining -lines are generated by @code{tar}. In the following examples we -usually use verbose mode, though it is almost never required. - -@node Subdirectory, Changing, Creating Example, Creating Archives -@subsection Creating an Archive of a Subdirectory - -You can store a directory in an archive by using the directory name as -a file-name argument to @code{tar}. When you specify a directory -file, @code{tar} archives the directory file and all the files it -contains. The names of the directory and the files it contains are -stored in the archive relative to the current working directory---when -the directory is extracted they will be written into the file system -relative to the working directory at that time. -@c <<< add an xref to +absolute-paths -ringo +* Multi-Volume Archives:: Archives Longer than One Tape or Disk +* Tape Files:: Tape Files -To archive a directory, first move to its superior directory. If you -have been following the tutorial, you should type: +Copying This Manual -@example -% cd .. -% -@end example +* GNU Free Documentation License:: License for copying this manual -Once in the superior directory, specify the subdirectory using a -file-name argument. To store the directory file @file{~/practice} in -the archive file @file{music}, type: +@end detailmenu +@end menu -@example -% tar +create +verbose +file=music practice -@end example +@node Introduction +@chapter Introduction -@noindent -@code{tar} should respond: +@acronym{GNU} @command{tar} 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. -@example -practice/ -practice/blues -practice/folk -practice/jazz -practice/records -@end example +@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 +* posix compliance:: +* Authors:: @acronym{GNU} @command{tar} Authors +* Reports:: Reporting bugs or suggestions +@end menu -Note that @file{~/practice/records}, another archive file, has -itself been archived. @code{tar} will accept any file as a file to be -archived, even an archive file. +@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 @acronym{GNU} +@command{tar} 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. + +@FIXME{this sounds more like a @acronym{GNU} Project Manuals Concept [tm] more +than the reality. should think about whether this makes sense to say +here, or not.} 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 the 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 last 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 filesystem, +and a @dfn{member name} is the name of an archive member within the +archive. -@c >>> symbolic links and changing directories are now in main body, not in -@c >>> tutorial. -ringo +@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 filesystem. 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). + +@FIXME{the following table entries need a bit of work..} + +You can use @command{tar} archives in many ways. We want to stress a few +of them: storage, backup, and transportation. + +@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. +@acronym{GNU} @command{tar} has special features that allow it to be +used to make incremental and full dumps of all the files in a +filesystem. + +@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 Extracting Files -@section Extracting Files from an Archive +@node Naming tar Archives +@section How @command{tar} Archives are Named -Creating an archive is only half the job---there would be no point in -storing files in an archive if you couldn't retrieve them. To extract -files from an archive, use the @samp{+extract} or @samp{-x} operation. +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. -To extract specific files, use their names as file-name arguments. If -you use a directory name as a file-name argument, @code{tar} extracts -all the files (including subdirectories) in that directory. If you -don't use any file-name arguments, @code{tar} extracts all the files -in the archive. +@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. -Note: @code{tar} will extract an archive member into the file system -without checking to see if there is already a file with the archive -member's file name. If there is a file with that name, @code{tar} -will @strong{overwrite} that file and its contents will be lost. -@c <<>> we want people to use the script for backups, so I an not going to -@c >>> use backups as an explanation in the tutorial. (people can still -@c >>> do it if they really want to) -ringo +@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 -While you can use @code{tar} to create a new archive every time you -want to store a file, it is more sometimes efficient to add files to -an existing archive. +Creating an archive is only half the job---there is no point in storing +files in an archive if you can't retrieve them. The act of retrieving +members from an archive so they can be used and manipulated as +unarchived files again is called @dfn{extraction}. To extract files +from an archive, use the @value{op-extract} operation. As with +@value{op-create}, specify the name of the archive with @value{op-file}. +Extracting an archive does not modify the archive in any way; you can +extract it multiple times if you want or need to. -To add new files to an existing archive, use the @samp{+add-file}, -@samp{+append} or @samp{-r} operation. To add newer versions of -archive members to an archive, use the @samp{+update} or @samp{-u} -operation. +Using @samp{--extract}, you can extract an entire archive, or specific +files. The files can be directories containing other files, or not. As +with @value{op-create} and @value{op-list}, you may use the short or the +long form of the operation without affecting the performance. @menu -* Append:: Appending Files to an Archive -* Update:: Updating Files in an Archive +* extracting archives:: +* extracting files:: +* extract dir:: +* failing commands:: @end menu -@node Append, Update, Adding to Archives, Adding to Archives -@subsection Appending Files to an Archive - -The simplest method of adding a file to an existing archive is the -@samp{+add-file}, @samp{-r} or @samp{+append} operation, which writes -files into the archive without regard to whether or not they are -already archive members. When you use @samp{+add-file} you must use -file-name arguments; there is no default. If you specify a file that -is already stored in the archive, @code{tar} adds another copy of the -file to the archive. - -If you have been following the previous examples, you should have a -text file called @file{~/practice/rock} which has not been stored in -either the archive file @file{~/practice/records}, or the archive file -@file{~/music}. To add @file{rock} to @file{records}, first make -@file{practice} the working directory (@samp{cd practice}). Then: - -@itemize @bullet -@item -Invoke @code{tar} and specify the @samp{+add-file} operation -(@samp{+add-file}, @samp{-r} or @samp{+append}) - -@item -Specify the archive to which the file will be added -(@samp{+file=@var{archive-name}} or @samp{-f @var{archive-name}}) - -@item -Specify the files to be added to the archive, using file-name -arguments -@end itemize +@node extracting archives +@subsection Extracting an Entire Archive -@noindent -For example: +To extract an entire archive, specify the archive file name only, with +no individual file names as arguments. For example, @example -% tar +add-file +file=records rock +$ @kbd{tar -xvf collection.tar} @end example @noindent -If you list the archive members in @file{records}, you will see that -@file{rock} has been added to the archive: +produces this: @example -% tar +list +file=records -blues -folk -jazz -rock +-rw-rw-rw- me user 28 1996-10-18 16:31 jazz +-rw-rw-rw- me user 21 1996-09-23 16:44 blues +-rw-rw-rw- me user 20 1996-09-23 16:44 folk @end example -@c <<< this should be some kind of node. +@node extracting files +@subsection Extracting Specific Files + +To extract specific archive members, give their exact member names as +arguments, as printed by @value{op-list}. 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. It will be identical to the original +file @file{blues} that you deleted. @FIXME{check this; will the times, +permissions, owner, etc be the same, also?} -You can use @samp{+add-file} to keep archive members current with -active files. Because @samp{+add-file} stores a file whether or not -there is already an archive member with the same file name, you can -use @samp{+add-file} to add newer versions of archive members to an -archive. When you extract the file, only the version stored last will -wind up in the file system. Because @samp{tar +extract} extracts -files from an archive in sequence, and overwrites files with the same -name in the file system, if a file name appears more than once in an -archive the last version of the file will overwrite the previous -versions which have just been extracted. +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. -If you recall from the examples using @samp{+compare} above, -@file{blues} was changed after the archive @file{records} was created. -It is simple, however, to use @samp{+add-file} to add the new version -of @file{blues} to @file{records}: +You can now extract the member @file{blues} from the archive file +@file{collection.tar} like this: @example -% tar +add-file +verbose +file=records blues -blues +$ @kbd{tar --extract --file=collection.tar blues} @end example @noindent -If you now list the contents of the archive, you will obtain the following: +If you list the files in the directory again, you will see that the file +@file{blues} has been restored, with its original permissions, creation +times, and owner.@FIXME{This is only accidentally true, but not in +general. 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 +@value{op-list}. + +@FIXME{we hope this will change:}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}}. To find the +exact member names of the members of an archive, use @value{op-list} +(@pxref{list}). + +You can extract a file to standard output by combining the above options +with the @option{--to-stdout} option (@pxref{Writing to Standard +Output}). + +If you give the @value{op-verbose} option, then @value{op-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. + +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 @samp{--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: @example -% tar +list -f records -blues -folk -jazz -rock -blues +$ @kbd{tar -xvf music.tar practice/folk practice/jazz} @end example -@noindent -The newest version of @file{blues} is at the end of the archive. When -the files in @file{records} are extracted, the newer version of -@file{blues} (which has the same name as the older) will overwrite the -version stored first. When @samp{tar +extract} is finished, only the -newer version of @file{blues} is in the file system. <<>> - -@node Update, , Append, Adding to Archives -@subsection Updating Files in an Archive - -To keep archive members up to date with their counterparts of the same -name in the file system, use the @samp{+update} or @samp{-u} -operation. @samp{tar +update} adds a specified file to an archive if -no file of that name is already stored in the archive. If there is -already an archive member with the same name, @code{tar} checks the -modification date of the archive member, and adds the file only if its -modification date is later. If a file is stored in the archive but no -longer exists under the same name in the active file system, -@code{tar} reports an error. - -You could use the @samp{+add-file} option to keep an archive current, -but do so you would either have to use the @samp{+compare} and -@samp{+list} options to determine what files needed to be re-archived -(which could waste a lot of time), or you would have to be willing to -add identical copies of already archived files to the archive (which -could waste a lot of space). - -You must use file-name arguments with the @samp{+update} -operation---if you don't specify any files, @code{tar} won't act on -any files. - -To see the @samp{+update} option at work, create a new file, -@file{~/practice/classical}, and modify the file -@file{~/practice/blues} (you can use a text editor, such as Emacs, to -do both these things). Then, with @file{practice} as your working -directory, invoke @samp{tar +update} using the names of all the files -in the practice directory as file-name arguments, and specifying the -@samp{+verbose} option: - -@example -% tar +update +verbose +file=records blues folk rock classical -blues -classical -% -@end example +@FIXME{need to show tar's response; used verbose above. also, here's a +good place to demonstrate the -v -v thing. have to write that up +(should be trivial, but i'm too tired!).} @noindent -Because you specified verbose mode, @code{tar} printed out the names -of the files it acted on. If you now list the archive members of the -archive, (@samp{tar +list +file=records}), you will see that the file -@file{classical} and another version of the file @file{blues} have -been added to @file{records}. - -Note: When you update an archive, @code{tar} does not overwrite old -archive members when it stores newer versions of a file. This is -because archive members appear in an archive in the order in which -they are stored, and some archive devices do not allow writing in the -middle of an archive. - -@node Concatenate, Extracting Files Example, Adding to Archives, Tutorial -@comment node-name, next, previous, up -@section Concatenating Archives - -To concatenate archive files, use @samp{tar +concatenate} or @samp{tar --A}. This operation adds other archives to the end of an archive. -While it may seem intuitive to concatenate archives using @code{cat}, -the utility for adding files together, archive files which have been -"catted" together cannot be read properly by @code{tar}. Archive -files incorporate an end of file marker---if archives are concatenated -using @code{cat}, this marker will appear before the end of the new -archive. This will interfere with operations on that archive. -@c <<>> - -In earlier examples, you stored the @file{~/practice} directory in an -archive file, @file{~/music}. If you have been following the -examples, you have since changed the contents of the @file{~/practice} -directory. There is a current version of the files in the -@file{practice} directory, however, stored in the archive file -@file{~/practice/records}. - -To store current versions of the files in @file{practice} in the -archive file @file{music}, you can use @samp{tar +concatenate} to add -the archive file @file{~/practice/records} to @file{music}. First, -make sure you are in your home directory (@samp{cd ~}). Then: +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. -@itemize @bullet -@item -Invoke @code{tar}, and specify the @samp{+concatenate} operation -(@samp{-A} or @samp{+concatenate}) +@FIXME{IMPORTANT! show the final structure, here. figure out what it +will be.} -@item -Specify the archive file to be added to -(@samp{+file=@var{archive-name}} or @samp{-f @var{archive-name}}) +@node failing commands +@subsection Commands That Will Fail -@item -Specify the archives to be added, using file-name arguments. In this -case, the file-name arguments are, unusually, the names of archive -files. (Remember to include the path in the archive name, if the -archive file is not in your working directory.) -@end itemize +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, @example -% cd ~ -% tar +concatenate +file=music practice/records +$ @kbd{tar -xvf music.tar folk jazz} @end example -If you now list the contents of the @file{music}, you see it now -contains the archive members of @file{practice/records}: +@noindent +you will get the following response: @example -%tar +list +file=music -blues -folk -jazz -rock -blues -practice/blues +tar: folk: Not found in archive +tar: jazz: Not found in archive +$ +@end example + +@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: + +@example +$ @kbd{tar -tvf music.tar} practice/folk practice/jazz practice/rock -practice/blues -practice/classical @end example -@node Deleting Files, , , Tutorial -@comment node-name, next, previous, up -@section Deleting Files From an Archive +@FIXME{make sure the above works when going through the examples in +order...} -In some instances, you may want to remove some files from an archive -stored on disk +@noindent +Likewise, if you try to use this command, -@quotation -@emph{Caution:} you should never delete files from an archive stored -on tape---because of the linear nature of tape storage, doing this is -likely to scramble the archive. -@end quotation +@example +$ @kbd{tar -tvf music.tar folk jazz} +@end example -To remove archive members from an archive, use the @samp{+delete} -operation. You must specify the names of files to be removed as -file-name arguments. All versions of the named file are removed from -the archive. +@noindent +you would get a similar response. Members with those names are not in the +archive. You must use the correct member names 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 + +@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 @acronym{GNU} @command{tar} +@UNREVISED + +This chapter is about how one invokes the @acronym{GNU} @command{tar} +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 @value{op-help} and +@value{op-version} (@pxref{help}), @value{op-verbose} (@pxref{verbose}) +and @value{op-interactive} options (@pxref{interactive}). -Execution of the @samp{+delete} operation can be very slow. +@menu +* Synopsis:: +* using tar options:: +* Styles:: +* All Options:: +* help:: +* verbose:: +* interactive:: +@end menu -To delete all versions of the file @file{blues} from the archive -@file{records} in the @file{practice} directory, make sure you are in -that directory, and then: +@node Synopsis +@section General Synopsis of @command{tar} -@itemize @bullet -@item -List the contents of the archive file @file{records} (see above for -the steps involved) to insure that the file(s) you wish to delete are -stored in the archive. (This step is optional) +The @acronym{GNU} @command{tar} program is invoked as either one of: -@item -Invoke @code{tar} and specify the @samp{+delete} operation -(@samp{+delete}). +@example +@kbd{tar @var{option}@dots{} [@var{name}]@dots{}} +@kbd{tar @var{letter}@dots{} [@var{argument}]@dots{} [@var{option}]@dots{} [@var{name}]@dots{}} +@end example -@item -Specify the name of the archive file that the file(s) will be deleted -from (@samp{+file=@var{archive-name}} or @samp{-f @var{archive-name}}) +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 @value{op-compare}, @value{op-delete}, +@value{op-extract}, @value{op-list} or @value{op-update}. When naming +archive members, you must give the exact name of the member in the +archive, as it is printed by @value{op-list}. For @value{op-append} +and @value{op-create}, 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 @value{op-absolute-names} +option). @value{xref-absolute-names}, for more information about +@value{op-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 filesystem 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 +@value{op-files-from} option. + +If you don't use any file name arguments, @value{op-append}, +@value{op-delete} and @value{op-concatenate} will do nothing, while +@value{op-create} will usually yield a diagnostic and inhibit @command{tar} +execution. The other operations of @command{tar} (@value{op-list}, +@value{op-extract}, @value{op-compare}, and @value{op-update}) will act +on the entire contents of the archive. + +@cindex exit status +@cindex return status +Besides successful exits, @acronym{GNU} @command{tar} 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. + +@acronym{GNU} @command{tar} returns only a few exit statuses. I'm really +aiming simplicity in that area, for now. If you are not using the +@value{op-compare} option, zero means that everything went well, besides +maybe innocuous warnings. Nonzero means that something went wrong. +Right now, as of today, ``nonzero'' is almost always 2, except for +remote operations, where it may be 128. + +@node using tar options +@section Using @command{tar} Options + +@acronym{GNU} @command{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 @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 @value{op-verbose}, 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}.) + +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 @samp{-T} and @samp{-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 @value{op-list}. + +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 chap. 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, @value{op-file} 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. + +@FIXME{hag to write a brief paragraph on the option(s) which can +optionally take an argument} -@item -Specify the files to be deleted, using file-name arguments. +@menu +* Mnemonic Options:: Mnemonic Option Style +* Short Options:: Short Option Style +* Old Options:: Old Option Style +* Mixing:: Mixing Option Styles +@end menu -@item -List the contents of the archive file again---note that the files have -been removed. (this step is also optional) -@end itemize +@node Mnemonic Options +@subsection Mnemonic Option Style + +@FIXME{have to decide whether or ot to replace other occurrences of +"mnemonic" with "long", or *ugh* vice versa.} + +Each option has at least one long (or mnemonic) name starting with two +dashes in a row, e.g.@: @samp{--list}. The long names are more clear than +their corresponding short or old names. It sometimes happens that a +single mnemonic option has many different different names which are +synonymous, such as @samp{--compare} and @samp{--diff}. In addition, +long option names can be given unique abbreviations. For example, +@samp{--cre} can be used in place of @samp{--create} because there is no +other mnemonic 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.) + +Mnemonic 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: @example -% tar +list +file=records -blues -folk -jazz -% tar +delete +file=records blues -% tar +list +file=records -folk -jazz -% +$ @kbd{tar --create --verbose --blocking-factor=20 --file=/dev/rmt0} @end example -@node Wizardry, Archive Structure, Tutorial, Top -@chapter Wizardry - -<<>>>> +This second example could be corrected in many ways, among which the +following are equivalent: -@node Archive Structure, Reading and Writing, Wizardry, Top -@chapter The Structure of an Archive +@example +@kbd{tar -czf archive.tar.gz file} +@kbd{tar -cf archive.tar.gz -z file} +@kbd{tar cf archive.tar.gz -z file} +@end example -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 @code{tar} utility or Tar mode in Emacs. +@FIXME{still could explain this better; it's redundant:} + +@cindex option syntax, traditional +As far as we know, all @command{tar} programs, @acronym{GNU} and +non-@acronym{GNU}, support old options. @acronym{GNU} @command{tar} +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 +@value{op-create} 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 @acronym{GNU} @command{tar} version 1.11.6, +a bug prevented intermixing old style options with mnemonic 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. +@example +@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 example -Physically, an archive consists of a series of file entries terminated -by an end-of-archive entry, which consists of 512 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 @code{tar} uses to detect file corruption, and -information about file types. +On the other hand, the following commands are @emph{not} equivalent to +the previous set: -More than archive member can have the same file 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, @pxref{Modifying}. +@example +@kbd{tar -f -c archive.tar} +@kbd{tar -fc archive.tar} +@kbd{tar -fcarchive.tar} +@kbd{tar -farchive.tarc} +@kbd{tar cfarchive.tar} +@end example -In addition to entries describing archive members, an archive may contain -entries which @code{tar} itself uses to store information. -@xref{Archive Label}, for an example of such an archive entry. +@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 +@samp{-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 -* Old Style File Information:: Old Style File Information -* Archive Label:: -* Format Variations:: +* Operation Summary:: +* Option Summary:: +* Short Option Summary:: @end menu -@node Old Style File Information, Archive Label, Archive Structure, Archive Structure -@section Old Style File Information -@cindex Format, old style -@cindex Old style format -@cindex Old style archives +@node Operation Summary +@subsection Operations -Archives record not only an archive member's contents, but also its -file name or names, its access permissions, user and group, size in -bytes, and last modification time. Some archives also record the file -names in each archived directory, as well as other file and directory -information. - -Certain old versions of @code{tar} cannot handle additional -information recorded by newer @code{tar} programs. To create an -archive which can be read by these old versions, specify the -@samp{+old-archive} option in conjunction with the @samp{tar +create} -operation. When you specify this option, @code{tar} leaves out -information about directories, pipes, fifos, contiguous files, and -device files, and specifies file ownership by group and user ids -instead of names. - -The @samp{+old-archive} option is needed only if the archive must be -readable by an older tape archive program which cannot handle the new format. -Most @code{tar} programs do not have this limitation, so this option -is seldom needed. +@table @kbd -@table @samp -@item +old-archive -@itemx -o -@itemx +old -@itemx +portable -@c has portability been changed to portable? -Creates an archive that can be read by an old @code{tar} program. -Used in conjunction with the @samp{tar +create} operation. -@end table +@item --append +@itemx -r -@node Archive Label, Format Variations, Old Style File Information, Archive Structure -@section Including a Label in the Archive -@cindex Labeling an archive -@cindex Labels on the archive media +Appends files to the end of the archive. @xref{append}. -@c !! Should the arg to +label be a quoted string?? no - ringo -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 -@samp{+label=@var{archive-label}} option in conjunction with the -@samp{+create} operation to include a label entry in the archive as it -is being created. +@item --catenate +@itemx -A -If you create an archive using both @samp{+label=@var{archive-label}} -and @samp{+multi-volume}, 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{Multi-Volume Archives}, for information on creating multiple -volume archives. +Same as @samp{--concatenate}. @xref{concatenate}. -If you extract an archive using @samp{+label=@var{archive-label}}, -@code{tar} will print an error if the archive label doesn't match the -@var{archive-label} specified, and will then not extract the archive. -You can include a regular expression in @var{archive-label}, in this -case only. -@c >>> why is a reg. exp. useful here? (to limit extraction to a -@c >>>specific group? ie for multi-volume??? -ringo +@item --compare +@itemx -d -To find out an archive's label entry (or to find out if an archive has -a label at all), use @samp{tar +list +verbose}. @code{tar} will print the -label first, and then print archive member information, as in the -example below: +Compares archive members with their counterparts in the file +system, and reports differences in file size, mode, owner, +modification date and contents. @xref{compare}. -@example -% tar +verbose +list +file=iamanarchive -V--------- 0/0 0 Mar 7 12:01 1992 iamalabel--Volume Header-- --rw-rw-rw- ringo/user 40 May 21 13:30 1990 iamafilename -@end example +@item --concatenate +@itemx -A -@table @samp -@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 -@samp{tar +create} operation). Checks to make sure the archive label -matches the one specified (when used in conjunction with the @samp{tar -+extract} operation. -@end table -@c was +volume +Appends other @command{tar} archives to the end of the archive. +@xref{concatenate}. -@node Format Variations, , Archive Label, Archive Structure -@section Format Variations -@cindex Format Parameters -@cindex Format Options -@cindex Options to specify archive format. +@item --create +@itemx -c -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. +Creates a new @command{tar} archive. @xref{create}. -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, @code{tar} uses default -parameters. You cannot modify a compressed archive. If you create an -archive with the @samp{+block-size} option specified (@pxref{Blocking -Factor}), you must specify that block-size when operating on the -archive. @xref{Matching Format Parameters}, for other examples of -format parameter considerations. +@item --delete +Deletes members from the archive. Don't try this on a archive on a +tape! @xref{delete}. -@menu -* Multi-Volume Archives:: -* Sparse Files:: -* Blocking Factor:: -* Compressed Archives:: -@end menu +@item --diff +@itemx -d -@node Multi-Volume Archives, Sparse Files, Format Variations, Format Variations -@subsection Archives Longer than One Tape or Disk -@cindex Multi-volume archives +Same @samp{--compare}. @xref{compare}. -To create an archive that is larger than will fit on a single unit of -the media, use the @samp{+multi-volume} option in conjunction with the -@samp{tar +create} operation (@pxref{Creating Archives}). A -@dfn{multi-volume} archive can be manipulated like any other archive -(provided the @samp{+multi-volume} option is specified), but is stored -on more than one tape or disk. +@item --extract +@itemx -x -When you specify @samp{+multi-volume}, @code{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. +Extracts members from the archive into the file system. @xref{extract}. -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 @samp{tar +list}, without @samp{+multi-volume} specified. -To extract an archive member from one volume (assuming it is described -that volume), use @samp{tar +extract}, again without -@samp{+multi-volume}. +@item --get +@itemx -x -If an archive member is split across volumes (ie. its entry begins on -one volume of the media and ends on another), you need to specify -@samp{+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}---@code{tar} will prompt for later -volumes as it needs them. @xref{Extracting From Archives} for more -information about extracting archives. +Same as @samp{--extract}. @xref{extract}. -@samp{+info-script=@var{program-file}} is like @samp{+multi-volume}, -except that @code{tar} does not prompt you directly to change media -volumes when a volume is full---instead, @code{tar} runs commands you -have stored in @var{program-file}. This option can be used to -broadcast messages such as @samp{someone please come change my tape} -when performing unattended backups. When @var{program-file} is done, -@code{tar} will assume that the media has been changed. +@item --list +@itemx -t +Lists the members in an archive. @xref{list}. -<<< There should be a sample program here, including an exit before -<<< end. +@item --update +@itemx -u -@table @samp -@item +multi-volume -@itemx -M -Creates a multi-volume archive, when used in conjunction with -@samp{tar +create}. To perform any other operation on a multi-volume -archive, specify @samp{+multi-volume} in conjunction with that -operation. +@FIXME{It was: A combination of the @samp{--compare} and +@samp{--append} operations. This is not true and rather misleading, +as @value{op-compare} does a lot more than @value{op-update} for +ensuring files are identical.} 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}. -@item +info-script=@var{program-file} -@itemx -F @var{program-file} -Creates a multi-volume archive via a script. Used in conjunction with -@samp{tar +create}. @end table -@node Sparse Files, Blocking Factor, Multi-Volume Archives, Format Variations -@subsection Archiving Sparse Files -@cindex Sparse Files +@node Option Summary +@subsection @command{tar} Options -A file is sparse if it contains blocks of zeros whose existance is -recorded, but that have no space allocated on disk. When you specify -the @samp{+sparse} option in conjunction with the @samp{+create} -operation, @code{tar} tests all files for sparseness while archiving. -If @code{tar} finds a file to be sparse, it uses a sparse -representation of the file in the archive. @xref{Creating Archives}, -for more information about creating archives. +@table @kbd -@samp{+sparse} is useful when archiving files, such as dbm files, -likely to contain many nulls. This option dramatically -decreases the amount of space needed to store such an archive. +@item --absolute-names +@itemx -P -@quotation -@strong{Please Note:} Always use @samp{+sparse} when performing file -system backups, to avoid archiving the expanded forms of files stored -sparsely in the system.@refill +Normally when creating an archive, @command{tar} strips an initial +@samp{/} from member names. This option disables that behavior. +@FIXME-xref{} -Even if your system has no no sparse files currently, some may be -created in the future. If you use @samp{+sparse} while making file -system backups as a matter of course, you can be assured the archive -will always take no more space on the media than the files take on -disk (otherwise, archiving a disk filled with sparse files might take -hundreds of tapes).@refill -<<< xref incremental when node name is set. -@end quotation +@item --after-date -@code{tar} ignores the @samp{+sparse} option when reading an archive. +(See @samp{--newer}.) @FIXME-pxref{} -@table @samp -@item +sparse -@itemx -S -Files stored sparsely in the file system are represented sparsely in -the archive. Use in conjunction with write operations. -@end table +@item --anchored +An exclude pattern must match an initial subsequence of the name's components. +@FIXME-xref{} -@node Blocking Factor, Compressed Archives, Sparse Files, Format Variations -@subsection The Blocking Factor of an Archive -@cindex Blocking Factor -@cindex Block Size -@cindex Number of records per block -@cindex Number of bytes per block -@cindex Bytes per block -@cindex Records per block - -The data in an archive is grouped into records, which are 512 bytes. -Records are read and written in whole number multiples called -@dfn{blocks}. The number of records in a block (ie. the size of a -block in units of 512 bytes) is called the @dfn{blocking factor}. The -@samp{+block-size=@var{number}} option specifies the blocking factor -of an archive. The default blocking factor is typically 20 (ie.@: -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. - -Blocks are seperated by gaps, which waste space on the archive media. -If you are archiving on magnetic tape, using a larger blocking factor -(and therefore larger blocks) 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 usefull when -archiving small files, to avoid archiving lots of nulls as @code{tar} -fills out the archive to the end of the block. In general, the ideal block size -depends on the size of the inter-block gaps on the tape you are using, -and the average size of the files you are archiving. @xref{Creating -Archives}, for information on writing archives. - -Archives with blocking factors larger than 20 cannot be read by very -old versions of @code{tar}, or by some newer versions of @code{tar} -running on old machines with small address spaces. With GNU -@code{tar}, the blocking factor of an archive is limited only by the -maximum block size of the device containing the archive, or by the -amount of available virtual memory. - -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 @samp{tar +list} without -specifying a blocking factor---@code{tar} reports a non-default block -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-blocks} option while specifying a blocking -factor larger then the blocking factor of the archive (ie. @samp{tar -+extract +read-full-blocks +block-size=300}. @xref{Listing Contents} -for more information on the @samp{+list} operation. -@xref{read-full-blocks} for a more detailed explanation of that -option. +@item --atime-preserve -@table @samp -@item +block-size=@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 @samp{tar +list}. -@end table +Tells @command{tar} to preserve the access time field in a file's inode when +reading it. Due to limitations in the @code{utimes} system call, the +modification time field is also preserved, which may cause problems if +the file is simultaneously being modified by another program. +This option is incompatible with incremental backups, because +preserving the access time involves updating the last-changed time. +Also, this option does not work on files that you do not own, +unless you're root. +@FIXME-xref{} -@node Compressed Archives, , Blocking Factor, Format Variations -@subsection Creating and Reading Compressed Archives -@cindex Compressed archives -@cindex Storing archives in compressed format +@item --backup=@var{backup-type} -@samp{+compress} indicates an archive stored in compressed format. -The @samp{+compress} option is useful in saving time over networks and -space in pipes, and when storage space is at a premium. -@samp{+compress} causes @code{tar} to compress when writing the -archive, or to uncompress when reading the archive. +Rather than deleting files from the file system, @command{tar} will +back them up using simple or numbered backups, depending upon +@var{backup-type}. @FIXME-xref{} -To perform compression and uncompression on the archive, @code{tar} -runs the @code{compress} utility. @code{tar} uses the default -compression parameters; if you need to override them, avoid the -@samp{+compress} option and run the @code{compress} utility -explicitly. It is useful to be able to call the @code{compress} -utility from within @code{tar} because the @code{compress} utility by -itself cannot access remote tape drives. +@item --block-number +@itemx -R -The @samp{+compress} option will not work in conjunction with the -@samp{+multi-volume} option or the @samp{+add-file}, @samp{+update}, -@samp{+add-file} and @samp{+delete} operations. @xref{Modifying}, for -more information on these operations. +With this option present, @command{tar} prints error messages for read errors +with the block number in the archive file. @FIXME-xref{} -If there is no compress utility available, @code{tar} will report an -error. +@item --blocking-factor=@var{blocking} +@itemx -b @var{blocking} -@samp{+compress-block} is like @samp{+compress}, but when used in -conjunction with @samp{+create} also causes @code{tar} to pad the last -block of the archive out to the next block boundary as it is written. -This is useful with certain devices which require all write operations -be a multiple of a specific size. +Sets the blocking factor @command{tar} uses to @var{blocking} x 512 bytes per +record. @FIXME-xref{} -@quotation -@strong{Please Note:} The @code{compress} program may be covered by a patent, -and therefore we recommend you stop using it. We hope to have a -different compress program in the future. We may change the name of -this option at that time. -@end quotation +@item --bzip2 +@itemx -j -@table @samp -@item +compress -@itemx +uncompress -@itemx -z -@itemx -Z -When this option is specified, @code{tar} will compress (when writing -an archive), or uncompress (when reading an archive). Used in -conjunction with the @samp{+create}, @samp{+extract}, @samp{+list} and -@samp{+compare} operations. - -@item +compress-block -@itemx -z -z -Acts like @samp{+compress}, but pads the archive out to the next block -boundary as it is written when used in conjunction with the -@samp{+create} operation. -@end table +This option tells @command{tar} to read or write archives through +@code{bzip2}. @FIXME-xref{} -@c >>> MIB -- why not use -Z instead of -z -z ? -ringo +@item --checkpoint -@node Reading and Writing, Insuring Accuracy, Archive Structure, Top -@chapter Reading and Writing Archives +This option directs @command{tar} to print periodic checkpoint messages as it +reads through the archive. Its intended for when you want a visual +indication that @command{tar} is still running, but don't want to see +@samp{--verbose} output. @FIXME-xref{} -The @samp{+create} operation writes a new archive, and the -@samp{+extract} operation reads files from an archive and writes them -into the file system. You can use other @code{tar} operations to -write new information into an existing archive (adding files to it, -adding another archive to it, or deleting files from it), and you can -read a list of the files in an archive without extracting it using the -@samp{+list} operation. +@item --compress +@itemx --uncompress +@itemx -Z -@menu -* Archive Name:: The name of an archive -* Creating in Detail:: Creating in detail -* Modifying:: Modifying archives -* Listing Contents:: Listing the contents of an archive -* Extracting From Archives:: Extracting files from an archive -@end menu +@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. @FIXME-xref{} -@node Archive Name, Creating in Detail, Reading and Writing, Reading and Writing -@section The Name of an Archive -@cindex Naming an archive -@cindex Archive Name -@cindex Directing output -@cindex Where is the archive? +@item --confirmation -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 or -disk drive. To specify the name of the archive, use the -@samp{+file=@var{archive-name}} option. - -An archive name can be the name of an ordinary file or the name of an -I/O device. @code{tar} always needs an archive name---if you do not -specify an archive name, the archive name comes from the environment -variable @code{TAPE} or, if that variable is not specified, a default -archive name, which is usually the name of tape unit zero (ie. -/dev/tu00). - -If you use @file{-} as an @var{archive-name}, @code{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, -@code{tar} reads the original archive from its standard input and -writes the entire new archive to its standard output. +(See @samp{--interactive}.) @FIXME-pxref{} -@c >>> MIB--does standard input and output redirection work with all -@c >>> operations? -@c >>> need example for standard input and output (screen and keyboard?) +@item --dereference +@itemx -h -@cindex Standard input and output -@cindex tar to standard input and output +When creating a @command{tar} archive, @command{tar} will archive the +file that a symbolic link points to, rather than archiving the +symlink. @FIXME-xref{} -To specify an archive file on a device attached to a remote machine, -use the following: +@item --directory=@var{dir} +@itemx -C @var{dir} -@example -+file=@var{hostname}:/@var{dev}/@var{file name} -@end example +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. @FIXME-xref{} -@noindent -@code{tar} will complete the remote connection, if possible, and -prompt you for a username and password. If you use -@samp{+file=@@@var{hostname}:/@var{dev}/@var{file-name}}, @code{tar} -will complete the remote connection, if possible, using your username -as the username on the remote machine. +@item --exclude=@var{pattern} -@c >>>MIB --- is this clear? +When performing operations, @command{tar} will skip files that match +@var{pattern}. @FIXME-xref{} -@table @samp -@item +file=@var{archive-name} -@itemx -f @var{archive-name} -Names the archive to create or operate on. Use in conjunction with -any operation. -@end table +@item --exclude-from=@var{file} +@itemx -X @var{file} -@node Creating in Detail, Modifying, Archive Name, Reading and Writing -@section Creating in Detail -@c operations should probably have examples, not tables. -@cindex Writing new archives -@cindex Archive creation +Similar to @samp{--exclude}, except @command{tar} will use the list of +patterns in the file @var{file}. @FIXME-xref{} -To create an archive, use @samp{tar +create}. To name the archive, -use @samp{+file=@var{archive-name}} in conjunction with the -@samp{+create} operation (@pxref{Archive Name}). If you do not name -the archive, @code{tar} uses the value of the environment variable -@code{TAPE} as the file name for the archive, or, if that is not -available, @code{tar} uses a default archive name, usually that for tape -unit zero. @xref{Archive Name}, for more information about specifying -an archive name. +@item --file=@var{archive} +@itemx -f @var{archive} -The following example creates an archive named @file{stooges}, -containing the files @file{larry}, @file{moe} and @file{curley}: +@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. @FIXME-xref{} -@example -tar +create +file=stooges larry moe curley -@end example +@item --files-from=@var{file} +@itemx -T @var{file} -If you specify a directory name as a file-name argument, @code{tar} -will archive all the files in that directory. The following example -creates an archive named @file{hail/hail/fredonia}, containing the -contents of the directory @file{marx}: +@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. @FIXME-xref{} -@example -tar +create +file=hail/hail/fredonia marx -@end example +@item --force-local -If you don't specify files to put in the archive, @code{tar} archives -all the files in the working directory. The following example creates -an archive named @file{home} containing all the files in the working -directory: +Forces @command{tar} to interpret the filename given to @samp{--file} +as a local file, even if it looks like a remote tape drive name. +@FIXME-xref{} -@example -tar +create +file=home -@end example +@item --group=@var{group} -@xref{File Name Lists}, for other ways to specify files to archive. +Files added to the @command{tar} archive will have a group 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 ID. @FIXME-xref{} -Note: In the example above, an archive containing all the files in the -working directory is being written to the working directory. GNU -@code{tar} stores files in the working directory in an archive which -is itself in the working directory without falling into an infinite -loop. Other versions of @code{tar} may fall into this trap. +Also see the comments for the @value{op-owner} option. -@node Modifying, Listing Contents, Creating in Detail, Reading and Writing -@section Modifying Archives -@cindex Modifying archives +@item --gunzip -Once an archive is created, you can add new archive members to it, add -the contents of another archive, add newer versions of members already -stored, or delete archive members already stored. +(See @samp{--gzip}.) @FIXME-pxref{} -To find out what files are already stored in an archive, use @samp{tar -+list +file=@var{archive-name}}. @xref{Listing Contents}. +@item --gzip +@itemx --gunzip +@itemx --ungzip +@itemx -z -@menu -* Adding Files:: -* Appending Archives:: -* Deleting Archive Files:: Deleting Files From an Archive -* Matching Format Parameters:: -@end menu +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. @FIXME-xref{} -@node Adding Files, Appending Archives, Modifying, Modifying -@subsection Adding Files to an Archive -@cindex Adding files to an archive -@cindex Updating an archive +@item --help -To add files to an archive, use @samp{tar +add-file}. The archive to -be added to must already exist and be in proper archive format (which -normally means it was created previously using @code{tar}). If the -archive was created with a different block size than now specified, -@code{tar} will report an error (@pxref{Blocking Factor}). If the -archive is not a valid @code{tar} archive, the results will be -unpredictable. You cannot add files to a compressed archive, however -you can add files to the last volume of a multi-volume archive. -@xref{Matching Format Parameters}. +@command{tar} will print out a short message summarizing the operations and +options to @command{tar} and exit. @FIXME-xref{} -The following example adds the file @file{shemp} to the archive -@file{stooges} created above: +@item --ignore-case +Ignore case when excluding files. +@FIXME-xref{} -@example -tar +add-file +file=stooges shemp -@end example +@item --ignore-failed-read -You must specify the files to be added; there is no default. +Do not exit unsuccessfully merely because an unreadable file was encountered. +@xref{Reading}. -@samp{tar +update} acts like @samp{tar +add-file}, but does not add -files to the archive if there is already a file entry with that name -in the archive that has the same modification time. +@item --ignore-zeros +@itemx -i -Both @samp{+update} and @samp{+add-file} 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. Because -@samp{tar +extract} extracts files from an archive in sequence, and -overwrites files with the same name in the file system, if a file name -appears more than once in an archive the last version of the file will -overwrite the previous versions which have just been extracted. You -should avoid storing older versions of a file later in the archive. +With this option, @command{tar} will ignore zeroed blocks in the +archive, which normally signals EOF. @xref{Reading}. -Note: @samp{+update} is not suitable for performing backups, because -it doesn't change directory content entries, and because it lengthens -the archive every time it is used. -@c <<< xref to scripted backup, listed incremental, for info on backups. +@item --incremental +@itemx -G -@node Appending Archives, Deleting Archive Files, Adding Files, Modifying -@subsection Appending One Archive's Contents to Another Archive -@cindex Adding archives to an archive -@cindex Concatenating Archives +Used to inform @command{tar} that it is working with an old +@acronym{GNU}-format incremental backup archive. It is intended +primarily for backwards compatibility only. @FIXME-xref{} -To append copies of an archive or archives to the end of another -archive, use @samp{tar +add-archive}. The source and target archives -must already exist and have been created using compatable format -parameters (@pxref{Matching Format Parameters}). - -@code{tar} will stop reading an archive if it encounters an -end-of-archive marker. The @code{cat} utility does not remove -end-of-archive markers, and is therefore unsuitable for concatenating -archives. @samp{tar +add-archive} removes the end-of-archive marker -from the target archive before each new archive is appended. -@c <<< xref ignore-zeros - -You must specify the source archives using -@samp{+file=@var{archive-name}} (@pxref{Archive Name}). If you do not -specify the target archive , @code{tar} uses the value of the -environment variable @code{TAPE}, or, if this has not been set, the -default archive name. +@item --index-file=@var{file} -The following example adds the contents of the archive -@file{hail/hail/fredonia} to the archive @file{stooges} (both archives -were created in examples above): +Send verbose output to @var{file} instead of to standard output. -@example -tar +add-archive +file=stooges hail/hail/fredonia -@end example +@item --info-script=@var{script-file} +@itemx --new-volume-script=@var{script-file} +@itemx -F @var{script-file} -If you need to retrieve files from an archive that was added to using -the @code{cat} utility, use the @samp{+ignore-zeros} option -(@pxref{Archive Reading Options}). +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. @FIXME-xref{} -@node Deleting Archive Files, Matching Format Parameters, Appending Archives, Modifying -@subsection Deleting Files From an Archive -@cindex Deleting files from an archive -@cindex Removing files from an archive +@item --interactive +@itemx --confirmation +@itemx -w -To delete archive members from an archive, use @samp{tar +delete}. -You must specify the file names of the members to be deleted. All -archive members with the specified file names will be removed from the -archive. +Specifies that @command{tar} should ask the user for confirmation before +performing potentially destructive options, such as overwriting files. +@FIXME-xref{} -The following example removes the file @file{curley} from the archive -@file{stooges}: +@item --keep-old-files +@itemx -k -@example -tar +delete +file=stooges curley -@end example +Do not overwrite existing files when extracting files from an archive. +@xref{Writing}. -You can only use @samp{tar +delete} on an archive if the archive -device allows you to write to any point on the media. +@item --label=@var{name} +@itemx -V @var{name} -@quotation -@strong{Warning:} Don't try to delete an archive member from a -magnetic tape, lest you scramble the archive. There is no safe way -(except by completely re-writing the archive) to delete files from -most kinds of magnetic tape. -@end quotation +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}. @FIXME-xref{} -@c <<< MIB -- how about automatic detection of archive media? give error -@c <<< unless the archive device is either an ordinary file or different -@c <<< input and output (+file=-). +@item --listed-incremental=@var{snapshot-file} +@itemx -g @var{snapshot-file} -@node Matching Format Parameters, , Deleting Archive Files, Modifying -@subsection Matching the Format Parameters +During a @samp{--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. @FIXME-xref{} -Some format parameters must be taken into consideration when modifying -an archive: +@item --mode=@var{permissions} -Compressed archives cannot be modified. +When adding files to an archive, @command{tar} will use +@var{permissions} for the archive members, rather than the permissions +from the files. The program @command{chmod} and this @command{tar} +option share the same syntax for what @var{permissions} might be. +@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. -You have to specify the block size of the archive when modifying an -archive with a non-default block size. +Of course, @var{permissions} might be plainly specified as an octal number. +However, by using generic symbolic modifications to mode bits, this allows +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. -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. +@item --multi-volume +@itemx -M -If a multi-volume archive was labeled using @samp{+label} -(@pxref{Archive Label}) when it was created, @code{tar} will not -automatically label volumes which are added later. To label -subsequent volumes, specify @samp{+label=@var{archive-label}} again in -conjunction with the @samp{+add-file}, @samp{+update} or -@samp{+add-archive} operation. -@cindex Labelling multi-volume archives -@c <<< example +Informs @command{tar} that it should create or otherwise operate on a +multi-volume @command{tar} archive. @FIXME-xref{} -@c <<< xref somewhere, for more information about format parameters. +@item --new-volume-script -@node Listing Contents, Extracting From Archives, Modifying, Reading and Writing -@section Listing the Contents of an Archive -@cindex Names of the files in an archive -@cindex Archive contents, list of -@cindex Archive members, list of +(see --info-script) -@samp{tar +list} prints a list of the file names of the archive -members on the standard output. If you specify @var{file-name} -arguments on the command line (or using the @samp{+files-from} option, -@pxref{File Name Lists}), only the files you specify will be listed, -and only if they exist in the archive. Files not specified will be -ignored, unless they are under a specific directory. +@item --newer=@var{date} +@itemx --after-date=@var{date} +@itemx -N -If you include the @samp{+verbose} option, @code{tar} prints an -@samp{ls -l} type listing for the archive. @pxref{Additional -Information}, for a description of the @samp{+verbose} option. +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 last-modified time specifies +the date. @FIXME-xref{} -If the blocking factor of the archive differs from the default, -@code{tar} reports this. @xref{Blocking Factor}. +@item --newer-mtime=@var{date} -@xref{Archive Reading Options} for a list of options which can be used -to modify @samp{+list}'s operation. +Like @samp{--newer}, but add only files whose +contents have changed (as opposed to just @samp{--newer}, which will +also back up files for which any status information has changed). -This example prints a list of the archive members of the archive -@file{stooges}: +@item --no-anchored +An exclude pattern can match any subsequence of the name's components. +@FIXME-xref{} -@example -tar +list +file=stooges -@end example +@item --no-ignore-case +Use case-sensitive matching when excluding files. +@FIXME-xref{} -@noindent -@code{tar} responds: +@item --no-recursion -@example -larry -moe -shemp -marx/julius -marx/alexander -marx/karl -@end example +With this option, @command{tar} will not recurse into directories. +@FIXME-xref{} -This example generates a verbose list of the archive members of the -archive file @file{dwarves}, which has a blocking factor of two: +@item --no-same-owner -@example -tar +list -v +file=blocks -@end example +When extracting an archive, do not attempt to preserve the owner +specified in the @command{tar} archive. This the default behavior +for ordinary users; this option has an effect only for the superuser. -@noindent -@code{tar} responds: +@item --no-same-permissions -@example -tar: Blocksize = 2 records --rw------- ringo/user 42 May 1 13:29 1990 .bashful --rw-rw-rw- ringo/user 42 Oct 4 13:29 1990 doc --rw-rw-rw- ringo/user 42 Jul 20 18:01 1969 dopey --rw-rw---- ringo/user 42 Nov 26 13:42 1963 grumpy --rw-rw-rw- ringo/user 42 May 5 13:29 1990 happy --rw-rw-rw- ringo/user 42 May 1 12:00 1868 sleepy --rw-rw-rw- ringo/user 42 Jul 4 17:29 1776 sneezy -@end example +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; this option has an effect only for the superuser. -@node Extracting From Archives, , Listing Contents, Reading and Writing -@section Extracting Files from an Archive -@cindex Extraction -@cindex Retrieving files from an archive -@cindex Resurrecting files from an archive +@item --no-wildcards +Do not use wildcards when excluding files. +@FIXME-xref{} -To read archive members from the archive and write them into the file -system, use @samp{tar +extract}. The archive itself is left -unchanged. +@item --no-wildcards-match-slash +Wildcards do not match @samp{/} when excluding files. +@FIXME-xref{} -If you do not specify the files to extract, @code{tar} extracts all -the files in the archive. If you specify the name of a directory as a -file-name argument, @code{tar} will extract all files which have been -stored as part of that directory. 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, -@code{tar} will create the directory. @xref{Selecting Archive -Members}, for information on specifying files to extract. +@item --null -The following example shows the extraction of the archive -@file{stooges} into an empty directory: +When @command{tar} is using the @samp{--files-from} option, this option +instructs @command{tar} to expect filenames terminated with @kbd{NUL}, so +@command{tar} can correctly work with file names that contain newlines. +@FIXME-xref{} -@example -tar +extract +file=stooges -@end example +@item --numeric-owner -@noindent -Generating a listing of the directory (@samp{ls}) produces: +This option will notify @command{tar} that it should use numeric user +and group IDs when creating a @command{tar} file, rather than names. +@FIXME-xref{} -@example -larry -moe -shemp -marx -@end example +@item --old-archive -@noindent -The subdirectory @file{marx} contains the files @file{julius}, -@file{alexander} and @file{karl}. +(See @samp{--portability}.) @FIXME-pxref{} -If you wanted to just extract the files in the subdirectory -@file{marx}, you could specify that directory as a file-name argument -in conjunction with the @samp{+extract} operation: +@item --one-file-system +@itemx -l -@example -tar +extract +file=stooges marx -@end example +Used when creating an archive. Prevents @command{tar} from recursing into +directories that are on different file systems from the current +directory. @FIXME-xref{} -@quotation -@strong{Warning:} Extraction can overwrite files in the file system. -To avoid losing files in the file system when extracting files from -the archive with the same name, use the @samp{+keep-old-files} option -(@pxref{File Writing Options}). -@end quotation +@item --overwrite -If the archive was created using @samp{+block-size}, @samp{+compress} -or @samp{+multi-volume}, you must specify those format options again -when extracting files from the archive (@pxref{Format Variations}). +Overwrite existing files and directory metadata when extracting files +from an archive. @xref{Overwrite Old Files}. -@menu -* Archive Reading Options:: -* File Writing Options:: -* Scarce Disk Space:: Recovering From Scarce Disk Space -@end menu +@item --overwrite-dir -@node Archive Reading Options, File Writing Options, Extracting From Archives, Extracting From Archives -@subsection Options to Help Read Archives -@cindex Options when reading archives -@cindex Reading incomplete blocks -@cindex Blocks, incomplete -@cindex End of archive markers, ignoring -@cindex Ignoring end of archive markers -@cindex Large lists of file names on small machines -@cindex Small memory -@cindex Running out of space +Overwrite the metadata of existing directories when extracting files +from an archive. @xref{Overwrite Old Files}. -@c <<< each option wants its own node. summary after menu +@item --owner=@var{user} -Normally, @code{tar} will request data in full block increments from -an archive storage device. If the device cannot return a full block, -@code{tar} will report an error. However, some devices do not always -return full blocks, or do not require the last block of an archive to -be padded out to the next block boundary. To keep reading until you -obtain a full block, or to accept an incomplete block if it contains -an end-of-archive marker, specify the @samp{+read-full-blocks} option -in conjunction with the @samp{+extract} or @samp{+list} operations. -@xref{Listing Contents}. +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 ID. +@FIXME-xref{} -The @samp{+read-full-blocks} option is turned on by default when -@code{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, @code{tar} -would fail as soon as it read an incomplete block from the pipe. +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. -If you're not sure of the blocking factor of an archive, you can read -the archive by specifying @samp{+read-full-blocks} and -@samp{+block-size=@var{n}}, where @var{n} is a blocking factor larger -than the blocking factor of the archive. This lets you avoid having -to determine the blocking factor of an archive. @xref{Blocking -Factor}. +This option does not affect extraction from archives. -@table @samp -@item +read-full-blocks -@item -B -Use in conjunction with @samp{tar +extract} to read an archive which -contains incomplete blocks, or one which has a blocking factor less -than the one specified. -@end table +@item --portability +@itemx --old-archive +@itemx -o -Normally @code{tar} stops reading when it encounters a block of zeros -between file entries (which usually indicates the end of the archive). -@samp{+ignore-zeros} allows @code{tar} to completely read an archive -which contains a block of zeros before the end (i.e.@: a damaged -archive, or one which was created by @code{cat}-ing several archives -together). +Tells @command{tar} to create an archive that is compatible with Unix V7 +@command{tar}. @FIXME-xref{} -The @samp{+ignore-zeros} option is turned off by default because many -versions of @code{tar} write garbage after the end of archive entry, -since that part of the media is never supposed to be read. GNU -@code{tar} does not write after the end of an archive, but seeks to -maintain compatablity among archiving utilities. +@item --posix -@table @samp -@item +ignore-zeros -@itemx -i -To ignore blocks of zeros (ie.@: end-of-archive entries) which may be -encountered while reading an archive. Use in conjunction with -@samp{tar +extract} or @samp{tar +list}. -@end table +Instructs @command{tar} to create a @sc{posix} compliant @command{tar} +archive. @FIXME-xref{} -If you are using a machine with a small amount of memory, and you need -to process large list of file-names, you can reduce the amount of -space @code{tar} needs to process the list. To do so, specify the -@samp{+same-order} option and provide an ordered list of file names. -This option tells @code{tar} that the @file{file-name} arguments -(provided on the command line, or read from a file using the -@samp{+files-from} option) are listed in the same order as the files -in the archive. +@item --preserve -You can create a file containing an ordered list of files in the -archive by storing the output produced by @samp{tar +list -+file=@var{archive-name}}. @xref{Listing Contents}, for information -on the @samp{+list} operation. +Synonymous with specifying both @samp{--preserve-permissions} and +@samp{--same-order}. @FIXME-xref{} -This option is probably never needed on modern computer systems. +@item --preserve-order -@table @samp -@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 @samp{tar +compare}, @samp{tar +list} -or @samp{tar +extract}. -@end table +(See @samp{--same-order}; @pxref{Reading}.) -@c we don't need/want +preserve to exist any more +@item --preserve-permissions +@itemx --same-permissions +@itemx -p -@node File Writing Options, Scarce Disk Space, Archive Reading Options, Extracting From Archives -@subsection Changing How @code{tar} Writes Files -@c <<< find a better title -@cindex Overwriting old files, prevention -@cindex Protecting old files -@cindex Modification times of extracted files -@cindex Permissions of extracted files -@cindex Modes of extracted files -@cindex Writing extracted files to standard output -@cindex Standard output, writing extracted files to - -Normally, @code{tar} writes extracted files into the file system -without regard to the files already on the system---files with the -same name as archive members are overwritten. To prevent @code{tar} -from extracting an archive member from an archive, if doing so will -overwrite a file in the file system, use @samp{+keep-old-files} in -conjunction with the @samp{+extract} operation. When this option is -specified, @code{tar} reports an error stating the name of the files -in conflict, instead of writing the file from the archive. +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{Writing}. -@table @samp -@item +keep-old files -@itemx -k -Prevents @code{tar} from overwriting files in the file system during -extraction. -@end table +@item --read-full-records +@itemx -B -Normally, @code{tar} sets the modification times of extracted files to -the modification times recorded for the files in the archive, but -limits the permissions of extracted files by the current @code{umask} -setting. +Specifies that @command{tar} should reblock its input, for reading +from pipes on systems with buggy implementations. @xref{Reading}. -To set the modification times of extracted files to the time when -the files were extracted, use the @samp{+modification-time} option in -conjunction with @samp{tar +extract}. +@item --record-size=@var{size} -@table @samp -@item +modification-time -@itemx -m -Sets the 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 @samp{+extract}. -@end table +Instructs @command{tar} to use @var{size} bytes per record when accessing the +archive. @FIXME-xref{} -To set the modes (access permissions) of extracted files to those -recorded for those files in the archive, use the -@samp{+preserve-permissions} option in conjunction with the -@samp{+extract} operation. -@c <<>> should be an example in the tutorial/wizardry section using this -@c >>> to transfer files between systems. +Verifies that the archive was correctly written when creating an +archive. @FIXME-xref{} -@c >>> is write access an issue? +@item --version -@table @samp -@item +absolute-paths -Preserves full file names (inclusing superior dirctory names) when -archiving files. Preserves leading slash when extracting files. -@end table +@command{tar} will print an informational message about what version +it is and a copyright message, some credits, and then exit. +@FIXME-xref{} -@node Changing Working Directory, Archiving with Symbolic Links, Absolute File Names, File Name Interpretation -@subsection Changing the Working Directory Within a List of File-names -@cindex Directory, changing in mid-stream -@cindex Working directory, specifying +@item --volno-file=@var{file} -To change working directory in the middle of a list of file names, -(either on the command line or in a file specified using -@samp{+files-from}), use @samp{+directory=@var{directory}}. This will -change the working directory to the directory @var{directory} after -that point in the list. For example, +Used in conjunction with @samp{--multi-volume}. @command{tar} will keep track +of which volume of a multi-volume archive its working in @var{file}. +@FIXME-xref{} -@example -tar +create iggy ziggy +directory=baz melvin -@end example +@item --wildcards +Use wildcards when excluding files. +@FIXME-xref{} -@noindent -will place the files @file{iggy} and @file{ziggy} from the current -directory into the archive, followed by the file @file{melvin} from -the directory @file{baz}. This option is especially useful when you -have several widely separated files that you want to store in the same -directory in the archive. - -Note that the file @file{melvin} is recorded in the archive under the -precise name @file{melvin}, @emph{not} @file{baz/melvin}. 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. +@item --wildcards-match-slash +Wildcards match @samp{/} when excluding files. +@FIXME-xref{} +@end table -Contrast this with the command +@node Short Option Summary +@subsection Short Options Cross Reference -@example -tar -c iggy ziggy bar/melvin -@end example +Here is an alphabetized list of all of the short option forms, matching +them with the equivalent long option. -@noindent -which records the third file in the archive under the name -@file{bar/melvin} so that, if the archive is extracted using @samp{tar -+extract}, the third file will be written in a subdirectory named -@file{bar}. +@table @kbd -@table @samp -@item +directory=@file{directory} -@itemx -C @file{directory} -Changes the working directory. -@end table +@item -A -@c <<>> +@samp{--unlink-first} -@node User Interaction, Backups and Restoration, Selecting Archive Members, Top -@chapter User Interaction -@cindex Getting more information during the operation -@cindex Information during operation -@cindex Feedback from @code{tar} +@item -V -Once you have typed a @code{tar}command, it is usually performed -without any further information required of the user, or provided by -@code{tar}. The following options allow you to generate progress and -status information during an operation, or to confirm operations on -files as they are performed. +@samp{--label} -@menu -* Additional Information:: -* Interactive Operation:: -@end menu +@item -W -@node Additional Information, Interactive Operation, User Interaction, User Interaction -@section Progress and Status Information -@cindex Progress information -@cindex Status information -@cindex Information on progress and status of operations -@cindex Verbose operation -@cindex Record number where error occured -@cindex Error message, record number of -@cindex Version of the @code{tar} program - -Typically, @code{tar} performs most operations without reporting any -information to the user except error messages. 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. - -When used with most operations, @samp{+verbose} causes @code{tar} to -print the file names of the files or archive members it is operating -on. When used with @samp{tar +list}, the verbose option causes -@code{tar} to print out an @samp{ls -l} type listing of the files in -the archive. - -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}). In that case @code{tar} writes verbose output to -the standard error stream. +@samp{--verify} -@table @samp -@item +verbose -@itemx -v -Prints the names of files or archive members as they are being -operated on. Can be used in conjunction with any operation. When -used with @samp{+list}, generates an @samp{ls -l} type listing. -@end table +@item -X -To find out where in an archive a message was triggered, use -@samp{+record-number}. @samp{+record-number} causes @code{tar} to -print, along with every message it produces, the record number within -the archive where the message was triggered. +@samp{--exclude-from} -This option is especially useful when reading damaged archives, since -it helps pinpoint the damaged sections. It can also be used with -@samp{tar +list} 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). -@c <<< xref when the node name is set and the backup section written +@item -Z -@table @samp -@item +record-number -@itemx -R -Prints the record number whenever a message is generated by -@code{tar}. Use in conjunction with any operation. -@end table +@samp{--compress} -@c rewrite below -To print the version number of the @code{tar} program, use @samp{tar -+version}. @code{tar} prints the version number to the standard -error. For example: +@item -b -@example -tar +version -@end example +@samp{--blocking-factor} -@noindent -might return: +@item -c -@example -GNU tar version 1.09 -@end example -@c used to be an option. has been fixed. +@samp{--create} -@node Interactive Operation, , Additional Information, User Interaction -@section Asking for Confirmation During Operations -@cindex Interactive operation +@item -d -Typically, @code{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{File Exclusion}), or by -performing an operation interactively, using the @samp{+interactive} -operation. - -When the @samp{+interactive} option is specified, @code{tar} asks for -confirmation before reading, writing, or deleting each file it -encounters while carrying out an operation. 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}, @code{tar} skips that file. - -Commands which might be useful to perform interactively include -appending files to an archive, extracting files from an archive, -deleting a file from an archive, and deleting a file from disk during -an incremental restore. - -If @code{tar} is reading the archive from the standard input, -@code{tar} opens the file @file{/dev/tty} to support the interactive -communications. -<<< this aborts if you won't OK the working directory. this is a bug. -ringo +@samp{--compare} -@table @samp -@item +interactive -@itemx +confirmation -@itemx -w -Asks for confirmation before reading, writing or deleting an archive -member (when listing, comparing or writing an archive or deleting -archive members), or before writing or deleting a file (when -extracting an archive). -@end table +@item -f -@node Backups and Restoration, Media, User Interaction, Top -@chapter Performing Backups and Restoring Files +@samp{--file} -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 accidently deleted). File system @dfn{backups} are also -called @dfn{dumps}. +@item -g -@menu -* Backup Levels:: Levels of backups -* Backup Scripts:: Using scripts to perform backups - and restoration -* incremental and listed-incremental:: The +incremental - and +listed-incremental Options -* Problems:: Some common problems and their solutions -@end menu +@samp{--listed-incremental} -@node Backup Levels, Backup Scripts, Backups and Restoration, Backups and Restoration -@section Levels of Backups +@item -h -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. +@samp{--dereference} -It is more efficient to do a full dump only occasionally. To back up -files between full dumps, you can a incremental dump. A @dfn{level -one} dump archives all the files that have changed since the last full -dump. +@item -i -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). +@samp{--ignore-zeros} -@node Backup Scripts, incremental and listed-incremental, Backup Levels, Backups and Restoration -@section Using Scripts to Perform Backups and Restoration +@item -j -GNU @code{tar} comes with scripts you can use to do full and level-one -dumps. Using scripts (shell programs) to perform backups and -restoration is a convenient and reliable alternative to typing out -file name lists and @code{tar} commands by hand. +@samp{--bzip2} -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. @xref{Script Syntax}. -Once the backup parameters are set, you can perform backups or -restoration by running the appropriate script. - -The name of the restore script is @code{restore}. The names of the -level one and full backup scripts are, respectively, @code{level-1} and -@code{level-0}. The @code{level-0} script also exists under the name -@code{weekly}, and the @code{level-1} under the name -@code{daily}---these additional names can be changed according to your -backup schedule. @xref{Scripted Restoration}, for more information -on running the restoration script. @xref{Scripted Backups}, for more -information on running the backup scripts. +@item -k -@emph{Please Note:} The backup scripts and the 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 -and listed-incremental}, before making such an attempt. +@samp{--keep-old-files} -@c shorten node names -@menu -* Backup Parameters:: Setting parameters for backups and restoration -* Scripted Backups:: Using the backup scripts -* Scripted Restoration:: Using the restore script -@end menu +@item -l -@node Backup Parameters, Scripted Backups, Backup Scripts, Backup Scripts -@subsection Setting Parameters for Backups and Restoration +@samp{--one-file-system} -The file @file{backup-specs} specifies backup parameters for the -backup and restoration scripts provided with @code{tar}. You must -edit @file{backup-specs} to fit your system configuration and schedule -before using these scripts. +@item -m -@c <<< This about backup scripts needs to be written: -@c <<>. bob also comments that if Amanda isn't free software, we +shouldn't mention it..} + +When the archive is being created to @file{/dev/null}, @acronym{GNU} +@command{tar} tries to minimize input and output operations. The +Amanda backup system, when used with @acronym{GNU} @command{tar}, 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 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 when @command{tar} is invoked with +@value{op-create}, @command{tar} operates on all the non-directory files in +the working directory. If you specify either @value{op-list} or +@value{op-extract}, @command{tar} operates on all the archive members in the +archive. If you specify any operation other than one of these three, +@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. @FIXME{add xref here}In general, these methods work both for +specifying the names of files and archive members. + +@node files +@section Reading Names from a File +@UNREVISED + +@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 +@value{op-files-from} option to @command{tar}. Give the name of the file +which contains the list of files to include as the argument to +@samp{--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 @kbd +@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 @samp{--files-from}, (i.e., +you specify either @samp{--files-from=-} or @samp{-T -}), then the file +names are read from standard input. + +Unless you are running @command{tar} with @samp{--create}, you can not use +both @samp{--files-from=-} and @samp{--file=-} (@samp{-f -}) in the same +command. + +@FIXME{add bob's example, from his message on 2-10-97} + +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 @samp{-T} option to +@command{tar} to specify the files from that file, @file{small-files}, to +create the archive @file{little.tgz}. (The @samp{-z} option to +@command{tar} compresses the archive with @command{gzip}; @pxref{gzip} for +more information.) + +@example +$ @kbd{find . -size -400 -print > small-files} +$ @kbd{tar -c -v -z -T small-files -f little.tgz} +@end example + +@noindent +@FIXME{say more here to conclude the example/section?} + +@menu +* nul:: +@end menu + +@node nul +@subsection @kbd{NUL} Terminated File Names + +@cindex File names, terminated by @kbd{NUL} +@cindex @kbd{NUL} terminated file names +The @value{op-null} option causes @value{op-files-from} to read file +names terminated by a @code{NUL} instead of a newline, so files whose +names contain newlines can be archived using @samp{--files-from}. + +@table @kbd +@item --null +Only consider @kbd{NUL} terminated file names, instead of files that +terminate in a newline. +@end table + +The @samp{--null} option is just like the one in @acronym{GNU} +@command{xargs} and @command{cpio}, and is useful with the +@samp{-print0} predicate of @acronym{GNU} @command{find}. In +@command{tar}, @samp{--null} also causes @value{op-directory} options +to be treated as file names to archive, in case there are any files +out there called @file{-C}. + +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 @samp{-print0} option to @command{find} just just +like @samp{-print}, except that it separates files with a @kbd{NUL} +rather than with a newline. You can then run @command{tar} with both the +@samp{--null} and @samp{-T} options to specify that @command{tar} get the +files from that file, @file{long-files}, to create the archive +@file{big.tgz}. The @samp{--null} option to @command{tar} will cause +@command{tar} to recognize the @kbd{NUL} separator between files. + +@example +$ @kbd{find . -size +800 -print0 > long-files} +$ @kbd{tar -c -v --null --files-from=long-files --file=big.tar} +@end example + +@FIXME{say anything else here to conclude the section?} + +@node exclude +@section Excluding Some Files +@cindex File names, excluding files by +@cindex Excluding files by name and pattern +@cindex Excluding files by file system +@UNREVISED + +To avoid operating on files whose names match a particular pattern, +use the @value{op-exclude} or @value{op-exclude-from} options. + +@table @kbd +@item --exclude=@var{pattern} +Causes @command{tar} to ignore files that match the @var{pattern}. +@end table + +@findex exclude +The @value{op-exclude} 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 @samp{--exclude} options. + +@table @kbd +@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 @samp{--exclude-from=@var{file-of-patterns}} 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. + +@FIXME{do the exclude options files need to have stuff separated by +newlines the same as the files-from option does?} + +@menu +* controlling pattern-patching with exclude:: +* problems with exclude:: +@end menu + +@node controlling pattern-patching with exclude +@unnumberedsubsec Controlling Pattern-Matching with the @code{exclude} Options + +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: + +@example +--ignore-case --exclude='makefile' --no-ignore-case ---exclude='readme' +@end example + +ignores case when excluding @samp{makefile}, but not when excluding +@samp{readme}. + +@table @option +@item --anchored +@itemx --no-anchored +If anchored (the default), a pattern must match an initial subsequence +of the name's components. Otherwise, the pattern can match any subsequence. + +@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. + +@item --wildcards +@itemx --no-wildcards +When using wildcards (the default), @samp{*}, @samp{?}, and @samp{[...]} +are the usual shell wildcards, and @samp{\} escapes wildcards. +Otherwise, none of these characters are special, and patterns must match +names literally. + +@item --wildcards-match-slash +@itemx --no-wildcards-match-slash +When wildcards match slash (the default), 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 exclude patterns are interpreted. If +recursion is in effect, a pattern excludes a name if it matches any of +the name's parent directories. + +@node problems with exclude +@unnumberedsubsec Problems with Using the @code{exclude} Options + +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 path 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 @value{op-exclude} and +@value{op-exclude-from}. Be careful: use @value{op-exclude} when files +to be excluded are given as a pattern on the command line. Use +@samp{--exclude-from=@var{file-of-patterns}} 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 @value{op-exclude}, be sure to quote the @var{pattern} +parameter, so @acronym{GNU} @command{tar} 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: + +@example +$ @kbd{tar -c -f @var{archive.tar} --exclude '*.o' @var{directory}} +@end example + +@noindent +rather than: + +@example +$ @kbd{tar -c -f @var{archive.tar} --exclude *.o @var{directory}} +@end example + +@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 +In earlier versions of @command{tar}, what is now the +@samp{--exclude-from=@var{file-of-patterns}} option was called +@samp{--exclude=@var{pattern}} instead. Now, +@samp{--exclude=@var{pattern}} applies to patterns listed on the command +line and @samp{--exclude-from=@var{file-of-patterns}} 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. However, @command{tar} often +uses wildcard patterns for matching (or globbing) archive members instead +of actual files in the filesystem. 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: excluding a directory also excludes all the files beneath it. + +@node after +@section Operating Only on New Files +@cindex Excluding file by age +@cindex Modification time, excluding files by +@cindex Age, excluding files by +@UNREVISED + +The @value{op-after-date} option causes @command{tar} to only work on files +whose modification or inode-changed 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 last-modified 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 @samp{--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 actual contents of the file (rather than inode +changes), then use the @value{op-newer-mtime} option. + +You may use these options with any operation. Note that these options +differ from the @value{op-update} 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 @kbd +@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 modification or inode-changed 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 last-modified time of that file is used as the date. + +@item --newer-mtime=@var{date} +Acts like @value{op-after-date}, but only looks at modification times. +@end table + +These options limit @command{tar} to only operating on files which have +been modified after the date specified. A file is considered to have +changed if the contents have been modified, or if the 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 @value{op-after-date} tests both the @code{mtime} +(time the contents of the file were last modified) and @code{ctime} +(time the file's status was last changed: owner, permissions, etc) +fields, while @value{op-newer-mtime} tests only @code{mtime} field. + +To be precise, @value{op-after-date} checks @emph{both} @code{mtime} and +@code{ctime} and processes the file if either one is more recent than +@var{date}, while @value{op-newer-mtime} only checks @code{mtime} and +disregards @code{ctime}. Neither uses @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. + +@FIXME{Need example of --newer-mtime with quoted argument.} + +@quotation +@strong{Please Note:} @value{op-after-date} and @value{op-newer-mtime} +should not be used for incremental backups. Some files (such as those +in renamed directories) are not selected properly by these options. +@xref{incremental and listed-incremental}. +@end quotation + +@noindent +@FIXME{which tells -- need to fill this in!} + +@node recurse +@section Descending into Directories +@cindex Avoiding recursion in directories +@cindex Descending directories, avoiding +@cindex Directories, avoiding recursion +@cindex Recursion in directories, avoiding +@UNREVISED + +@FIXME{arrggh! this is still somewhat confusing to me. :-< } + +@FIXME{show dan bob's comments, from 2-10-97} + +Usually, @command{tar} will recursively explore all directories (either +those given on the command line or through the @value{op-files-from} +option) for the various files they contain. However, you may not always +want @command{tar} to act this way. + +The @value{op-no-recursion} option inhibits @command{tar}'s recursive descent +into specified directories. If you specify @samp{--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 @kbd +@item --no-recursion +Prevents @command{tar} from recursively descending directories. + +@item --recursion +Requires @command{tar} to recursively descend directories. +This is the default. +@end table + +When you use @samp{--no-recursion}, @acronym{GNU} @command{tar} 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{! -d}} option +to @command{find} @FIXME{needs more explanation or a cite to another +info file}as they usually do not want all the files in a directory. +They then use the @value{op-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 +@value{op-same-permissions} option does not affect them---while users +might really like it to. Specifying @value{op-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. + +The @value{op-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 @value{op-no-recursion} option also affects how exclude patterns +are interpreted (@pxref{controlling pattern-patching with exclude}). + +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: + +@example +$ @kbd{tar -cf jams.tar --norecursion grape --recursion grape/concord} +@end example + +@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 Filesystem 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 +@value{op-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 @value{op-files-from}, regardless of where they reside. + +@table @kbd +@item --one-file-system +@itemx -l +Prevents @command{tar} from crossing file system boundaries when +archiving. Use in conjunction with any write operation. +@end table + +The @samp{--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 filesystem 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. + +It is reported that using this option, the mount point is is archived, +but nothing under it. + +This option is useful for making full or incremental archival backups of +a file system. If this option is used in conjunction with +@value{op-verbose}, 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 +@UNREVISED + +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 +@value{op-files-from}, use @value{op-directory}. This will change the +working directory to the directory @var{directory} after that point in +the list. + +@table @kbd +@item --directory=@var{directory} +@itemx -C @var{directory} +Changes the working directory in the middle of a command line. +@end table + +For example, + +@example +$ @kbd{tar -c -f jams.tar grape prune -C food cherry} +@end example + +@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, + +@example +$ @kbd{tar -c -f jams.tar grape prune -C food red/cherry} +@end example + +@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 @samp{--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}: + +@example +$ @kbd{tar -c -f foo.tar -C /etc passwd hosts -C /lib libc.a} +@end example + +@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 @samp{--directory} options are interpreted consecutively. If +@samp{--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 +@samp{--directory} option. + +@FIXME{dan: does this mean that you *can* use the short option form, but +you can *not* use the long option form with --files-from? or is this +totally screwed?} + +When using @samp{--files-from} (@pxref{files}), you can put @samp{-C} +options in the file list. Unfortunately, you cannot put +@samp{--directory} options in the file list. (This interpretation can +be disabled by using the @value{op-null} option.) + +@node absolute +@subsection Absolute File Names +@UNREVISED + +@table @kbd +@item -P +@itemx --absolute-names +Do not strip leading slashes from file names, and permit file names +containing a @file{..} file name component. +@end table + +By default, @acronym{GNU} @command{tar} 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-@acronym{GNU} @command{tar} +program to use. Therefore, @acronym{GNU} @command{tar} 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}. + +If you use the @value{op-absolute-names} option, @command{tar} will do +none of these transformations. + +To archive or extract files relative to the root directory, specify +the @value{op-absolute-names} 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 @value{op-absolute-names}, @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 @value{op-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 @kbd +@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 @acronym{GNU} @command{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 @command{tar} standard +error to the sink. For example, under @command{sh}: + +@example +$ @kbd{tar -c -f archive.tar /home 2> /dev/null} +@end example + +@noindent +Another solution, both nicer and simpler, would be to change to +the @file{/} directory first, and then avoid absolute notation. +For example: + +@example +$ @kbd{(cd / && tar -c -f archive.tar home)} +$ @kbd{tar -c -f archive.tar -C / home} +@end example + +@include getdate.texi + +@node Formats +@chapter Controlling the Archive Format + +@FIXME{need an intro here} + +@menu +* Portability:: Making @command{tar} Archives More Portable +* Compression:: Using Less Space through Compression +* Attributes:: Handling File Attributes +* Standard:: The Standard Format +* Extensions:: @acronym{GNU} Extensions to the Archive Format +* cpio:: Comparison of @command{tar} and @command{cpio} +@end menu + +@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. + +@menu +* Portable Names:: Portable Names +* dereference:: Symbolic Links +* old:: Old V7 Archives +* posix:: @sc{posix} archives +* Checksumming:: Checksumming Problems +* Large or Negative Values:: Large files, negative time stamps, etc. +@end menu + +@node Portable Names +@subsection Portable Names + +Use portable file and member names. A name is portable if it contains +only 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 + +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 filesystem contents. +@value{op-dereference} is used with @value{op-create}, 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 @value{op-dereference}: many systems do not support +symbolic links, and moreover, your distribution might be unusable if +it contains unresolved symbolic links. + +@node old +@subsection Old V7 Archives +@cindex Format, old style +@cindex Old style format +@cindex Old style archives + +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 @value{op-old-archive} option in +conjunction with the @value{op-create}. @command{tar} also +accepts @samp{--portability} 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 @value{op-old-archive} +unless the archive was created with 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 @value{op-old-archive} for your distributions. + +@node posix +@subsection @acronym{GNU} @command{tar} and @sc{posix} @command{tar} + +@acronym{GNU} @command{tar} was based on an early draft of the +@sc{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 @sc{posix} draft as unused. Subsequent changes in +@sc{posix} have allocated the same parts of the header record for +other purposes. As a result, @acronym{GNU} @command{tar} is +incompatible with the current @sc{posix} spec, and with @command{tar} +programs that follow it. + +We plan to reimplement these @acronym{GNU} extensions in a new way which is +upward compatible with the latest @sc{posix} @command{tar} format, but we +don't know when this will be done. + +In the mean time, there is simply no telling what might happen if you +read a @acronym{GNU} @command{tar} archive, which uses the +@acronym{GNU} extensions, using some other @command{tar} program. So +if you want to read the archive with another @command{tar} program, be +sure to write it using the @samp{--old-archive} option (@samp{-o}). + +@FIXME{is there a way to tell which flavor of tar was used to write a +particular archive before you try to read it?} + +Traditionally, old @command{tar}s have a limit of 100 characters. +@acronym{GNU} @command{tar} attempted two different approaches to +overcome this limit, using and extending a format specified by a draft +of some P1003.1. The first way was not that successful, and involved +@file{@@MaNgLeD@@} file names, or such; while a second approach used +@file{././@@LongLink} and other tricks, yielding better success. In +theory, @acronym{GNU} @command{tar} should be able to handle file +names of practically unlimited length. So, if @acronym{GNU} +@command{tar} fails to dump and retrieve files having more than 100 +characters, then there is a bug in @acronym{GNU} @command{tar}, +indeed. + +But, being strictly @sc{posix}, the limit was still 100 characters. +For various other purposes, @acronym{GNU} @command{tar} used areas +left unassigned in the @sc{posix} draft. @sc{posix} later revised +P1003.1 @code{ustar} format by assigning previously unused header +fields, in such a way that the upper limit for file name length was +raised to 256 characters. However, the actual @sc{posix} limit +oscillates between 100 and 256, depending on the precise location of +slashes in full file name (this is rather ugly). Since @acronym{GNU} +@command{tar} use the same fields for quite other purposes, it became +incompatible with the latest @sc{posix} standards. + +For longer or non-fitting file names, we plan to use yet another set +of @acronym{GNU} extensions, but this time, complying with the +provisions @sc{posix} offers for extending the format, rather than +conflicting with it. Whenever an archive uses old @acronym{GNU} +@command{tar} extension format or @sc{posix} extensions, would it be +for very long file names or other specialities, this archive becomes +non-portable to other @command{tar} implementations. In fact, +anything can happen. The most forgiving @command{tar}s will merely +unpack the file using a wrong name, and maybe create another file +named something like @file{@@LongName}, with the true file name in it. +@command{tar}s not protecting themselves may segment violate! + +Compatibility concerns make all this thing more difficult, as we will +have to support @emph{all} these things together, for a while. +@acronym{GNU} @command{tar} should be able to produce and read true +@sc{posix} format files, while being able to detect old @acronym{GNU} +@command{tar} formats, besides old V7 format, and process them +conveniently. It would take years before this whole area +stabilizes@dots{} + +There are plans to raise this 100 limit to 256, and yet produce +@sc{posix} conforming archives. Past 256, I do not know yet if +@acronym{GNU} @command{tar} will go non-@sc{posix} again, or merely +refuse to archive the file. + +There are plans so @acronym{GNU} @command{tar} support more fully the +latest @sc{posix} format, while being able to read old V7 format, +@acronym{GNU} (semi-@sc{posix} plus extension), as well as full +@sc{posix}. One may ask if there is part of the @sc{posix} format +that we still cannot support. This simple question has a complex +answer. Maybe that, on intimate look, some strong limitations will +pop up, but until now, nothing sounds too difficult (but see below). +I only have these few pages of @sc{posix} telling about ``Extended tar +Format'' (P1003.1-1990 -- section 10.1.1), and there are references to +other parts of the standard I do not have, which should normally +enforce limitations on stored file names (I suspect things like fixing +what @kbd{/} and @kbd{@key{NUL}} means). There are also some points +which the standard does not make clear, Existing practice will then +drive what I should do. + +@sc{posix} mandates that, when a file name cannot fit within 100 to +256 characters (the variance comes from the fact a @kbd{/} is ideally +needed as the 156'th character), or a link name cannot fit within 100 +characters, a warning should be issued and the file @emph{not} be +stored. Unless some @value{op-posix} option is given (or +@env{POSIXLY_CORRECT} is set), I suspect that @acronym{GNU} +@command{tar} should disobey this specification, and automatically +switch to using @acronym{GNU} extensions to overcome file name or link +name length limitations. + +There is a problem, however, which I did not intimately studied yet. +Given a truly @sc{posix} archive with names having more than 100 +characters, I guess that @acronym{GNU} @command{tar} up to 1.11.8 will +process it as if it were an old V7 archive, and be fooled by some +fields which are coded differently. So, the question is to decide if +the next generation of @acronym{GNU} @command{tar} should produce +@sc{posix} format by default, whenever possible, producing archives +older versions of @acronym{GNU} @command{tar} might not be able to +read correctly. I fear that we will have to suffer such a choice one +of these days, if we want @acronym{GNU} @command{tar} to go closer to +@sc{posix}. We can rush it. Another possibility is to produce the +current @acronym{GNU} @command{tar} format by default for a few years, +but have @acronym{GNU} @command{tar} versions from some 1.@var{POSIX} +and up able to recognize all three formats, and let older +@acronym{GNU} @command{tar} fade out slowly. Then, we could switch to +producing @sc{posix} format by default, with not much harm to those +still having (very old at that time) @acronym{GNU} @command{tar} +versions prior to 1.@var{POSIX}. + +@sc{posix} format cannot represent very long names, volume headers, +splitting of files in multi-volumes, sparse files, and incremental +dumps; these would be all disallowed if @value{op-posix} or +@env{POSIXLY_CORRECT}. Otherwise, if @command{tar} is given long +names, or @samp{-[VMSgG]}, then it should automatically go non-@sc{posix}. +I think this is easily granted without much discussion. + +Another point is that only @code{mtime} is stored in @sc{posix} +archives, while @acronym{GNU} @command{tar} currently also store +@code{atime} and @code{ctime}. If we want @acronym{GNU} @command{tar} +to go closer to @sc{posix}, my choice would be to drop @code{atime} +and @code{ctime} support on average. On the other hand, I perceive +that full dumps or incremental dumps need @code{atime} and +@code{ctime} support, so for those special applications, @sc{posix} +has to be avoided altogether. + +A few users requested that @value{op-sparse} be always active by +default, I think that before replying to them, we have to decide if we +want @acronym{GNU} @command{tar} to go closer to @sc{posix} on +average, while producing files. My choice would be to go closer to +@sc{posix} in the long run. Besides possible double reading, I do not +see any point of not trying to save files as sparse when creating +archives which are neither @sc{posix} nor old-V7, so the actual +@value{op-sparse} would become selected by default when producing such +archives, whatever the reason is. So, @value{op-sparse} alone might +be redefined to force @acronym{GNU}-format archives, and recover its +previous meaning from this fact. + +@acronym{GNU}-format as it exists now can easily fool other @sc{posix} +@command{tar}, as it uses fields which @sc{posix} considers to be part +of the file name prefix. I wonder if it would not be a good idea, in +the long run, to try changing @acronym{GNU}-format so any added field +(like @code{ctime}, @code{atime}, file offset in subsequent volumes, +or sparse file descriptions) be wholly and always pushed into an +extension block, instead of using space in the @sc{posix} header +block. I could manage to do that portably between future +@acronym{GNU} @command{tar}s. So other @sc{posix} @command{tar}s +might be at least able to provide kind of correct listings for the +archives produced by @acronym{GNU} @command{tar}, if not able to +process them otherwise. + +Using these projected extensions might induce older @command{tar}s to +fail. We would use the same approach as for @sc{posix}. I'll put out +a @command{tar} capable of reading @sc{posix}ier, yet extended +archives, but will not produce this format by default, in +@acronym{GNU} mode. In a few years, when newer @acronym{GNU} +@command{tar}s will have flooded out @command{tar} 1.11.X and +previous, we could switch to producing @sc{posix}ier extended +archives, with no real harm to users, as almost all existing +@acronym{GNU} @command{tar}s will be ready to read @sc{posix}ier +format. In fact, I'll do both changes at the same time, in a few +years, and just prepare @command{tar} for both changes, without +effecting them, from 1.@var{POSIX}. (Both changes: 1---using +@sc{posix} convention for getting over 100 characters; 2---avoiding +mangling @sc{posix} headers for @acronym{GNU} extensions, using only +@sc{posix} mandated extension techniques). + +So, a future @command{tar} will have a @value{op-posix} flag forcing +the usage of truly @sc{posix} headers, and so, producing archives +previous @acronym{GNU} @command{tar} will not be able to read. So, +@emph{once} pretest will announce that feature, it would be +particularly useful that users test how exchangeable will be archives +between @acronym{GNU} @command{tar} with @value{op-posix} and other +@sc{posix} @command{tar}. + +In a few years, when @acronym{GNU} @command{tar} will produce +@sc{posix} headers by default, @value{op-posix} will have a strong +meaning and will disallow @acronym{GNU} extensions. But in the +meantime, for a long while, @value{op-posix} in @acronym{GNU} tar will +not disallow @acronym{GNU} extensions like @value{op-label}, +@value{op-multi-volume}, @value{op-sparse}, or very long file or link +names. However, @value{op-posix} with @acronym{GNU} extensions will +use @sc{posix} headers with reserved-for-users extensions to headers, +and I will be curious to know how well or bad @sc{posix} +@command{tar}s will react to these. + +@acronym{GNU} @command{tar} prior to 1.@var{POSIX}, and after +1.@var{POSIX} without @value{op-posix}, generates and checks +@samp{ustar@w{ }@w{ }}, with two suffixed spaces. This is sufficient +for older @acronym{GNU} @command{tar} not to recognize @sc{posix} +archives, and consequently, wrongly decide those archives are in old +V7 format. It is a useful bug for me, because @acronym{GNU} +@command{tar} has other @sc{posix} incompatibilities, and I need to +segregate @acronym{GNU} @command{tar} semi-@sc{posix} archives from +truly @sc{posix} archives, for @acronym{GNU} @command{tar} should be +somewhat compatible with itself, while migrating closer to latest +@sc{posix} standards. So, I'll be very careful about how and when I +will do the correction. + +@node Checksumming +@subsection Checksumming Problems + +SunOS and HP-UX @command{tar} fail to accept archives created using +@acronym{GNU} @command{tar} and containing non-ASCII file names, that +is, file names having characters with the eight bit set, because they +use signed checksums, while @acronym{GNU} @command{tar} uses unsigned +checksums while creating archives, as per @sc{posix} standards. On +reading, @acronym{GNU} @command{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. + +@acronym{GNU} @command{tar} compute checksums both ways, and accept +any on read, so @acronym{GNU} tar can read Sun tapes even with their +wrong checksums. @acronym{GNU} @command{tar} produces the standard +checksum, however, raising incompatibilities with Sun. That is to +say, @acronym{GNU} @command{tar} 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 + +@sc{posix} @command{tar} format uses fixed-sized unsigned octal strings +to represent numeric values. User and group IDs and device major and +minor numbers have unsigned 21-bit representations, and file sizes and +times have unsigned 33-bit representations. @acronym{GNU} @command{tar} +generates @sc{posix} representations when possible, but for values +outside the @sc{posix} range it generates two's-complement base-256 +strings: uids, gids, and device numbers have signed 57-bit +representations, and file sizes and times have signed 89-bit +representations. These representations are an extension to @sc{posix} +@command{tar} format, so they are not universally portable. + +The most common portability problems with out-of-range numeric values +are large files and future or negative time stamps. + +Portable archives should avoid members of 8 GB or larger, as @sc{posix} +@command{tar} format cannot represent them. + +Portable archives should avoid time stamps from the future. @sc{posix} +@command{tar} format can represent time stamps in the range 1970-01-01 +00:00:00 through 2242-03-16 12:56:31 @sc{utc}. However, many current +hosts use a signed 32-bit @code{time_t}, or internal time stamp format, +and cannot represent time stamps after 2038-01-19 03:14:07 @sc{utc}; so +portable archives must avoid these time stamps for many years to come. + +Portable archives should also avoid time stamps before 1970. These time +stamps are a common @sc{posix} extension but their @code{time_t} +representations are negative. Many traditional @command{tar} +implementations generate a two's complement representation for negative +time stamps that assumes a signed 32-bit @code{time_t}; hence they +generate archives that are not portable to hosts with differing +@code{time_t} representations. @acronym{GNU} @command{tar} recognizes this +situation when it is run on host with a signed 32-bit @code{time_t}, but +it issues a warning, as these time stamps are nonstandard and unportable. + +@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 +@UNREVISED + +@table @kbd +@item -z +@itemx --gzip +@itemx --ungzip +Filter the archive through @command{gzip}. +@end table + +@FIXME{ach; these two bits orig from "compare" (?). where to put?} Some +format parameters must be taken into consideration when modifying an +archive.@FIXME{???} Compressed archives cannot be modified. + +You can use @samp{--gzip} and @samp{--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, avoid the @value{op-gzip} option and run @command{gzip} +explicitly. (Or set the @env{GZIP} environment variable.) + +The @value{op-gzip} option does not work with the @value{op-multi-volume} +option, or with the @value{op-update}, @value{op-append}, +@value{op-concatenate}, or @value{op-delete} operations. + +It is not exact to say that @acronym{GNU} @command{tar} is to work in concert +with @command{gzip} in a way similar to @command{zip}, say. Surely, it is +possible that @command{tar} and @command{gzip} be done with a single call, +like in: + +@example +$ @kbd{tar cfz archive.tar.gz subdir} +@end example + +@noindent +to save all of @samp{subdir} into a @code{gzip}'ed archive. Later you +can do: + +@example +$ @kbd{tar xfz archive.tar.gz} +@end example + +@noindent +to explode and unpack. + +The difference is that the whole archive is compressed. With +@command{zip}, archive members are archived individually. @command{tar}'s +method yields better compression. On the other hand, one can view the +contents of a @command{zip} archive without having to decompress it. As +for the @command{tar} and @command{gzip} tandem, you need to decompress the +archive to see its contents. However, this may be done without needing +disk space, by using pipes internally: + +@example +$ @kbd{tar tfz archive.tar.gz} +@end example + +@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 @acronym{GNU} @command{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! + +@table @kbd +@item -j +@itemx --bzip2 +Filter the archive through @code{bzip2}. Otherwise like @value{op-gzip}. + +@item -Z +@itemx --compress +@itemx --uncompress +Filter the archive through @command{compress}. Otherwise like +@value{op-gzip}. + +@item --use-compress-program=@var{prog} +Filter through @var{prog} (must accept @samp{-d}). +@end table + +@value{op-compress} stores an archive in compressed format. This +option is useful in saving time over networks and space in pipes, and +when storage space is at a premium. @value{op-compress} causes +@command{tar} to compress when writing the archive, or to uncompress when +reading the archive. + +To perform compression and uncompression on the archive, @command{tar} +runs the @command{compress} utility. @command{tar} uses the default +compression parameters; if you need to override them, avoid the +@value{op-compress} option and run the @command{compress} utility +explicitly. It is useful to be able to call the @command{compress} +utility from within @command{tar} because the @command{compress} utility by +itself cannot access remote tape drives. + +The @value{op-compress} option will not work in conjunction with the +@value{op-multi-volume} option or the @value{op-append}, @value{op-update} +and @value{op-delete} operations. @xref{Operations}, for +more information on these operations. + +If there is no compress utility available, @command{tar} will report an error. +@strong{Please note} that the @command{compress} program may be covered by +a patent, and therefore we recommend you stop using it. + +@value{op-bzip2} acts like @value{op-compress}, except that it uses +the @code{bzip2} utility. + +@table @kbd +@item --compress +@itemx --uncompress +@itemx -z +@itemx -Z +When this option is specified, @command{tar} will compress (when +writing an archive), or uncompress (when reading an archive). Used in +conjunction with the @value{op-create}, @value{op-extract}, +@value{op-list} and @value{op-compare} operations. +@end table + +You can have archives be compressed by using the @value{op-gzip} option. +This will arrange for @command{tar} to use the @command{gzip} program to be +used to compress or uncompress the archive wren writing or reading it. + +To use the older, obsolete, @command{compress} program, use the +@value{op-compress} option. The @acronym{GNU} Project recommends you not use +@command{compress}, because there is a patent covering the algorithm it +uses. You could be sued for patent infringement merely by running +@command{compress}. + +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 @value{op-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 @value{op-use-compress-prog} 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 @samp{-d} option, for when +extraction is needed rather than creation. + +It has been reported that if one writes compressed data (through the +@value{op-gzip} or @value{op-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. + +@node sparse +@subsection Archiving Sparse Files +@cindex Sparse Files +@UNREVISED + +@table @kbd +@item -S +@itemx --sparse +Handle sparse files efficiently. +@end table + +This option causes all files to be put in the archive to be tested for +sparseness, and handled specially if they are. The @value{op-sparse} +option is useful when many @code{dbm} files, for example, are being +backed up. Using this option dramatically decreases the amount of +space needed to store such a file. + +In later versions, this option may be removed, and the testing and +treatment of sparse files may be done automatically with any special +@acronym{GNU} options. For now, it is an option needing to be specified on +the command line with the creation or updating of an archive. + +Files in the filesystem 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 read 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 @value{op-sparse}. When +you use the @value{op-sparse} 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 +@value{op-sparse} is not needed on extraction) any such files have +hols created wherever the continuous stretches of zeros were found. +Thus, if you use @value{op-sparse}, @command{tar} archives won't take +more space than the original. + +A file is sparse if it contains blocks of zeros whose existence is +recorded, but that have no space allocated on disk. When you specify +the @value{op-sparse} option in conjunction with the @value{op-create} +operation, @command{tar} tests all files for sparseness while archiving. +If @command{tar} finds a file to be sparse, it uses a sparse representation of +the file in the archive. @value{xref-create}, for more information +about creating archives. + +@value{op-sparse} is useful when archiving files, such as dbm files, +likely to contain many nulls. This option dramatically +decreases the amount of space needed to store such an archive. + +@quotation +@strong{Please Note:} Always use @value{op-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 @value{op-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). @FIXME-xref{incremental when node name is set.} +@end quotation + +@command{tar} ignores the @value{op-sparse} option when reading an archive. + +@table @kbd +@item --sparse +@itemx -S +Files stored sparsely in the file system are represented sparsely in +the archive. Use in conjunction with write operations. +@end table + +However, users should be well aware that at archive creation time, +@acronym{GNU} @command{tar} still has to read whole disk file to +locate the @dfn{holes}, and so, even if sparse files use little space +on disk and in the archive, they may sometimes require inordinate +amount of time for reading and examining all-zero blocks of a file. +Although it works, it's painfully slow for a large (sparse) file, even +though the resulting tar archive may be small. (One user reports that +dumping a @file{core} file of over 400 megabytes, but with only about +3 megabytes of actual data, took about 9 minutes on a Sun Sparcstation +ELC, with full CPU utilization.) + +This reading is required in all cases and is not related to the fact +the @value{op-sparse} option is used or not, so by merely @emph{not} +using the option, you are not saving time@footnote{Well! We should say +the whole truth, here. When @value{op-sparse} is selected while creating +an archive, the current @command{tar} algorithm requires sparse files to be +read twice, not once. We hope to develop a new archive format for saving +sparse files in which one pass will be sufficient.}. + +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. +@acronym{GNU} @command{tar} 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 + +@node Attributes +@section Handling File Attributes +@UNREVISED + +When @command{tar} reads files, this causes them to have the access +times updated. To have @command{tar} attempt to set the access times +back to what they were before they were read, use the +@value{op-atime-preserve} option. + +Handling of file attributes + +@table @kbd +@item --atime-preserve +Preserve access times on files that are read. +This doesn't work for files that +you don't own, unless you're root, and it doesn't interact with +incremental dumps nicely (@pxref{Backups}), and it can set access or +modification times incorrectly if other programs access the file while +@command{tar} is running; but it is good enough for some purposes. + +@item -m +@itemx --touch +Do not extract file modified time. + +When this option is used, @command{tar} leaves the modification times +of the files it extracts as the time when the files were extracted, +instead of setting it to the time recorded in the archive. + +This option is meaningless with @value{op-list}. + +@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 id and user name +separately. If it can't find a user name (because the user id is not +in @file{/etc/passwd}), then it does not write one. When restoring, +and doing a @code{chmod} like when you use @value{op-same-permissions}, +@FIXME{same-owner?}it tries to look the name (if one was written) +up in @file{/etc/passwd}. If it fails, then it uses the user id +stored in the archive instead. + +@item --no-same-owner +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. + +@item --numeric-owner +The @value{op-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 filesystem(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 @value{op-old-archive} 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 +@acronym{GNU} @command{tar} for fine tuning permissions and ownership. +This is not the good way, I think. @acronym{GNU} @command{tar} is +already crowded with options and moreover, the approach just explained +gives you a great deal of control already. + +@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 meaningless with @value{op-list}. + +@item --preserve +Same as both @value{op-same-permissions} and @value{op-same-order}. + +The @value{op-preserve} option has no equivalent short option name. +It is equivalent to @value{op-same-permissions} plus @value{op-same-order}. + +@FIXME{I do not see the purpose of such an option. (Neither I. FP.)} + +@end table + +@node Standard +@section The Standard 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 512 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}. +@FIXME-xref{To learn more about having more than one archive member with the +same name, see -backup node, when it's written.} + +In addition to entries describing archive members, an archive may +contain entries which @command{tar} itself uses to store information. +@value{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 may be a block +filled with binary zeros as an end-of-file marker. A reasonable system +should write a block of zeros at the end, but must not assume that +such a block exists when reading an archive. + +The blocks may be @dfn{blocked} for physical I/O operations. +Each record of @var{n} blocks (where @var{n} is set by the +@value{op-blocking-factor} 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 @acronym{GNU} +@command{tar} distribution, this is part of file @file{src/tar.h}: + +@example +@include header.texi +@end example + +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 2 digits, a space, and a null, except +@code{size}, and @code{mtime}, which do not contain the trailing 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 UID, Set 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 +ID of the file owners, respectively. If the operating system does +not support numeric user or group IDs, 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. @FIXME-xref{Modifiers, in +particular the @value{op-incremental} option.} + +The @code{mtime} field is the 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 was 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 time +and last inode-change time. + +The @code{offset} is used by the @value{op-multi-volume} 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 IDs 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 +@section @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 +@value{op-incremental} 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 @value{op-multi-volume} 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 @value{op-label} option when the archive was created. The @code{name} +field contains the @code{name} given after the @value{op-label} option. +The @code{size} field is zero. Only the first file in each volume +of an archive should have this type. -@item status -Prints status information about the tape unit. @end table -<<< is there a better way to frob the spacing on the list? -ringo -If you don't specify a @var{tapename}, @code{mt} uses the environment -variable TAPE; if TAPE does not exist, @code{mt} uses the device -@file{/dev/rmt12}. +You may have trouble reading a @acronym{GNU} format archive on a +non-@acronym{GNU} system if the options @value{op-incremental}, +@value{op-multi-volume}, @value{op-sparse}, or @value{op-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 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 +pathname lengths. The binary and old ASCII formats have a max path +length of 256, and the new ASCII and CRC ASCII formats have a max +path length of 1024. @acronym{GNU} @command{cpio} can read and write archives +with arbitrary pathname 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 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 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 BSD source; +@command{cpio} comes only with System III, System V, and later 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 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 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 +@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. -@code{mt} returns a 0 exit status when the operation(s) were -successful, 1 if the command was unrecognized, and 2 if an operation -failed. +@quotation +What type of check sum (if any) is used, and how is this calculated. +@end quotation -@c <<< new node on how to find an archive? -ringo -If you use @code{tar +extract} with the -@samp{+label=@var{archive-name}} option specified, @code{tar} will -read an archive label (the tape head has to be positioned on it) and -print an error if the archive label doesn't match the -@var{archive-name} specified. @var{archive-name} can be any regular -expression. If the labels match, @code{tar} extracts the archive. -@xref{Archive Label}. @xref{Matching Format Parameters}. -<<< fix cross references +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. -@code{tar +list +label} will cause @code{tar} to print the label. +@quotation +If anyone knows why @command{cpio} was made when @command{tar} was present +at the unix scene, +@end quotation -@c <<< MIB -- program to list all the labels on a tape? +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. -@node Quick Reference, Data Format Details, Media, Top -@appendix A Quick Reference Guide to @code{tar} Operations and Options -@c put in proper form for appendix. (unnumbered?) +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. -@menu -* Operations:: A Table of Operations -* Options:: Table of Options -@end menu +The main difference is just in the command syntax and header format. -@node Operations, Options, Quick Reference, Quick Reference -@appendixsec A Table of Operations -@c add xrefs, note synonyms +@command{tar} is a little more tape-oriented in that everything is blocked +to start on a record boundary. -The operation argument to @code{tar} specifies which action you want to -take. +@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 -@table @samp -@item -A -Adds copies of an archive or archives to the end of another archive. +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. -@item -c -Creates a new 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 -@item -d -Compares files in the archive with their counterparts in the file -system, and reports differences in file size, mode, owner, -modification date and contents. +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. -@item -r -Adds files to the end of the archive. +You might want to look at the freely available alternatives. The +major ones are @command{afio}, @acronym{GNU} @command{tar}, and +@command{pax}, each of which have their own extensions with some +backwards compatibility. -@item -t -Prints a list of the contents of the archive. +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). -@item -x -Reads files from the archive and writes them into the active file -system. +@node Media +@chapter Tapes and Other Archive Media +@UNREVISED -@item -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. +A few special cases about tape handling warrant more detailed +description. These special cases are discussed below. -@item +add-archive -Adds copies of an archive or archives to the end of another archive. +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. -@item +add-file -Adds files to the end of the archive. +Archives are usually written on dismountable media---tape cartridges, +mag tapes, or floppy disks. -@item +append -Adds files to the end of the archive. +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. -@item +catenate -Adds copies of an archive or archives to the end of another archive. +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. -@item +compare -Compares files in the archive with their counterparts in the file -system, and reports differences in file size, mode, owner, -modification date and contents. +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. -@item +concatenate -Adds copies of an archive or archives to the end of another archive. +@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 -@item +create -Creates a new archive. +@node Device +@section Device Selection and Switching +@UNREVISED -@item +delete -Deletes files from the archive. All versions of the files are deleted. +@table @kbd +@item -f [@var{hostname}:]@var{file} +@itemx --file=[@var{hostname}:]@var{file} +Use archive file or device @var{file} on @var{hostname}. +@end table -@item +diff -Compares files in the archive with their counterparts in the file -system, and reports differences in file size, mode, owner, -modification date and contents. +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 (@kbd{@@}), 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 @file{/etc/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 @file{/etc/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. + +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, @acronym{GNU} @command{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 @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. + +@acronym{GNU} @command{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 @samp{DEFTAPE} in +@file{}. + +@table @kbd +@item --force-local +Archive file is local even if it contains a colon. + +@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. -@item +extract -Reads files from the archive and writes them into the active file -system. +@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}. + +@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. + +@item -F @var{file} +@itemx --info-script=@var{file} +@itemx --new-volume-script=@var{file} +Execute @file{file} at end of each tape. If @file{file} exits with +nonzero status, exit. This implies @value{op-multi-volume}. +@end table -@item +get -Reads files from the archive and writes them into the active file -system. +@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{/etc/rmt} +on any machine whose tape drive you want to use. @command{tar} calls +@file{/etc/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. Instructions for compiling +and installing it are included in the @file{Makefile}. + +@cindex absolute file names +Unless you use the @value{op-absolute-names} option, @acronym{GNU} +@command{tar} 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, @acronym{GNU} @command{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 @command{tar} tape to an operator to restore; +the operator used Sun @command{tar} instead of @acronym{GNU} +@command{tar}, 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}, +@acronym{GNU} @command{tar} 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 @value{op-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 @value{op-append}, @value{op-update}, +@value{op-concatenate}, and @value{op-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 @value{op-multi-volume}, @value{op-label}, and +@value{op-incremental} 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 @value{op-incremental} option. + +@node Common Problems and Solutions +@section Some Common Problems and their Solutions -@item +help -Prints a list of @code{tar} operations and options. +@ifclear PUBLISH -@item +list -Prints a list of the contents of the archive. +@format +errors from system: +permission denied +no such file or directory +not owner -@item +update -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. +errors from @command{tar}: +directory checksum error +header format error -@item +version -Prints the version number of the @code{tar} program to the standard -error. -@end table +errors from media/system: +i/o error +device busy +@end format -@node Options, , Operations, Quick Reference -@appendixsec Table of Options +@end ifclear -Options change the way @code{tar} performs an operation. +@node Blocking +@section Blocking +@UNREVISED -@table @samp -@item +absolute-paths -WILL BE INPUT WHEN QUESTION IS RESOLVED +@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. -@item +after-date=@var{date} -Limit the operation to files changed after the given date. -@xref{File Exclusion}. +John Gilmore, the writer of the public domain @command{tar} from which +@acronym{GNU} @command{tar} was originally derived, wrote (June 1995): -@item +block-size=@var{number} -Specify the blocking factor of an archive. @xref{Blocking Factor}. +@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 @sc{posix} (no surprise +here), and now Fran@,{c}ois has migrated that terminology back +into the source code too. +@end quotation -@item +compress -Specify a compressed archive. @xref{Compressed Archives}. +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 @acronym{GNU} @command{tar}. + +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 @acronym{GNU} @command{tar}. + +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 @value{op-blocking-factor} 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 @value{op-blocking-factor}) larger than the +actual blocking factor, and then use the @value{op-read-full-records} +option. (If you specify a blocking factor with +@value{op-blocking-factor} and don't use the +@value{op-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 +@value{op-blocking-factor} when reading, because @command{tar} cannot +figure it out. In any case, use @value{op-list} 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 +@value{op-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. @acronym{GNU} @command{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 +@end menu -@item +compress-block. -Create a whole block sized compressed archive. @xref{Compressed Archives}. +@node Format Variations +@subsection Format Variations +@cindex Format Parameters +@cindex Format Options +@cindex Options, archive format specifying +@cindex Options, format specifying +@UNREVISED -@item +confirmation -Solicit confirmation for each file. @xref{Interactive Operation} -<<< +selective should be a synonym. +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. -@item +dereference -Treat a symbolic link as an alternate name for the file the link -points to. @xref{Symbolic Links}. +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 @value{op-blocking-factor} option +specified (@value{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 + +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 (ie. the size of a +record in units of 512 bytes) is called the @dfn{blocking factor}. +The @value{op-blocking-factor} option specifies the blocking factor of +an archive. The default blocking factor is typically 20 (ie.@: +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 @acronym{GNU} @command{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: -@item +directory=@file{directory} -Change the working directory. @xref{Changing Working Directory}. +@example +Cannot write to /dev/dlt: Invalid argument +@end example -@item +exclude=@var{pattern} -Exclude files which match the regular expression @var{pattern}. -@xref{File Exclusion}. +@noindent +In such cases, it sometimes happen that the @command{tar} bundled by +the system is aware of block size idiosyncrasies, while @acronym{GNU} +@command{tar} requires an explicit specification for the block size, +which it cannot guess. This yields some people to consider +@acronym{GNU} @command{tar} 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 @value{op-list} 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 @value{op-read-full-records} option while +specifying a blocking factor larger then the blocking factor of the archive +(ie. @samp{tar --extract --read-full-records --blocking-factor=300}. +@xref{list}, for more information on the @value{op-list} +operation. @xref{Reading}, for a more detailed explanation of that option. + +@table @kbd +@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 @value{op-list}. +@end table -@item +exclude-from=@file{file} -Exclude files which match any of the regular expressions listed in -the file @file{file}. @xref{File Exclusion}. +Device blocking + +@table @kbd +@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 dissapper. Id est, we are using block size of 112 right +now, and we haven't had the problem since we switched@dots{} + +With @acronym{GNU} @command{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: +@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 +@value{op-blocking-factor} is not explicitly specified on the @command{tar} +invocation. +@end itemize -@item +file=@var{archive-name} -Name the archive. @xref{Archive Name}). +In previous versions of @acronym{GNU} @command{tar}, the +@samp{--compress-block} option (or even older: +@samp{--block-compress}) was necessary to reblock compressed archives. +It is now a dummy option just asking not to be used, and otherwise +ignored. 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: -@item +files-from=@file{file} -Read file-name arguments from a file on the file system. -@xref{File Name Lists}. +@itemize @bullet -@item +ignore-umask -Set modes of extracted files to those recorded in the archive. -@xref{File Writing Options}. +@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 +ignore-zeros -Ignore end-of-archive entries. @xref{Archive Reading Options}. -<<< this should be changed to +ignore-end +@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 +listed-incremental=@var{file-name} (-g) -Take a file name argument always. If the file doesn't exist, run a level -zero dump, creating the file. If the file exists, uses that file to see -what has changed. +@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 +incremental (-G) -@c <<>> +@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 -@item +tape-length=@var{n} (-L) -@c <<>> -@c <<< this needs to be written into main body as well -ringo +@item -i +@itemx --ignore-zeros +Ignore blocks of zeros in archive (means EOF). + +The @value{op-ignore-zeros} 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. + +@item -B +@itemx --read-full-records +Reblock as we read (for reading 4.2BSD pipes). + +If @value{op-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 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. -@item +info-script=@var{program-file} -Create a multi-volume archive via a script. @xref{Multi-Volume Archives}. +@end table -@item +interactive -Ask for confirmation before performing any operation on a file or -archive member. +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 @samp{--number-blocks} instead of +@samp{--block-number}, so @samp{--block} will then expand to +@samp{--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: -@item +keep-old-files -Prevent overwriting during extraction. @xref{File Writing Options}. +@example +$ @kbd{tar cf /dev/tape @var{directory}} +@end example -@item +label=@var{archive-label} -Include an archive-label in the archive being created. @xref{Archive -Label}. +@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: -@item +modification-time -Set the modification time of extracted files to the time they were -extracted. @xref{File Writing Options}. +@example +$ @kbd{mt -f /dev/nrtape rewind} +$ @kbd{tar cf /dev/nrtape @var{directory-1}} +@end example -@item +multi-volume -Specify a multi-volume archive. @xref{Multi-Volume Archives}. +@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: -@item +newer=@var{date} -Limit the operation to files changed after the given date. -@xref{File Exclusion}. +@example +$ @kbd{tar cf /dev/nrtape @var{directory-2}} +@end example -@item +newer-mtime=@var{date} -Limit the operation to files modified after the given date. @xref{File -Exclusion}. +@noindent +and so on for all the archives you want to put on the same tape. -@item +old -Create an old format archive. @xref{Old Style File Information}. -@c <<< did we agree this should go away as a synonym? +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: -@item +old-archive -Create an old format archive. @xref{Old Style File Information}. +@example +$ @kbd{mt -f /dev/nrtape rewind} +$ @kbd{mt -f /dev/nrtape fsf 16} +$ @kbd{tar cf /dev/nrtape @var{directory-17}} +@end example -@item +one-file-system -Prevent @code{tar} from crossing file system boundaries when -archiving. @xref{File Exclusion}. +In all the previous examples, we put aside blocking considerations, but +you should do the proper things for that as well. @xref{Blocking}. -@item +portable -Create an old format archive. @xref{Old Style File Information}. -@c <<< was portability, may still need to be changed +@menu +* Tape Positioning:: Tape Positions and Tape Marks +* mt:: The @command{mt} Utility +@end menu -@item +preserve-order -Help process large lists of file-names on machines with small amounts of -memory. @xref{Archive Reading Options}. +@node Tape Positioning +@subsection Tape Positions and Tape Marks +@UNREVISED -@item +preserve-permission -Set modes of extracted files to those recorded in the archive. -@xref{File Writing Options}. +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. -@item +read-full-blocks -Read an archive with a smaller than specified block size or which -contains incomplete blocks. @xref{Archive Reading Options}). -@c should be +partial-blocks (!!!) - -@item +record-number -Print the record number where a message is generated. -@xref{Additional Information}. +If you think of data as a series of records "rrrr"'s, and tape marks as +"*"'s, a tape might look like the following: -@item +same-order -Help process large lists of file-names on machines with small amounts of -memory. @xref{Archive Reading Options}. +@example +rrrr*rrrrrr*rrrrr*rr*rrrrr**------------------------- +@end example -@item +same-permission -Set the modes of extracted files to those recorded in the archive. -@xref{File Writing Options}. +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. (The @code{restore} +script will find the archive automatically. @FIXME{There is no such +restore script!}@FIXME-xref{Scripted Restoration}@xref{mt}, for +an explanation of the tape moving utility. -@item +sparse -Archive sparse files sparsely. @xref{Sparse Files}. +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: -@item +starting-file=@var{file-name} -Begin reading in the middle of an archive. @xref{Scarce Disk Space}. +@example +rrrr*rrrrrr*rrrrr*rr*rrrrr*rrr*rrrr**---------------- +@end example -@item +to-stdout -Write files to the standard output. @xref{File Writing Options}. +@node mt +@subsection The @command{mt} Utility +@UNREVISED -@item +uncompress -Specifdo a compressed archive. @xref{Compressed Archives}. +@FIXME{Is it true that this only works on non-block devices? +should explain the difference, (fixed or variable).} +@value{xref-blocking-factor}. -@item -V @var{archive-label} -Include an archive-label in the archive being created. @xref{Archive -Label}. -@c was +volume +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"?} -@item +verbose -Print the names of files or archive members as they are being -operated on. @xref{Additional Information}. +The syntax of the @command{mt} command is: -@item +verify -Check for discrepancies in the archive immediately after it is -written. @xref{Write Verification}. +@example +@kbd{mt [-f @var{tapename}] @var{operation} [@var{number}]} +@end example -@item -B -Read an archive with a smaller than specified block size or which -contains incomplete blocks. @xref{Archive Reading Options}). +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: -@item -K @var{file-name} -Begin reading in the middle of an archive. @xref{Scarce Disk Space}. +@FIXME{is there any use for record operations?} -@item -M -Specify a multi-volume archive. @xref{Multi-Volume Archives}. +@table @kbd +@item eof +@itemx weof +Writes @var{number} tape marks at the current position on the tape. -@item -N @var{date} -Limit operation to files changed after the given date. @xref{File Exclusion}. +@item fsf +Moves tape position forward @var{number} files. -@item -O -Write files to the standard output. @xref{File Writing Options}. +@item bsf +Moves tape position back @var{number} files. -@c <<<<- P is absolute paths, add when resolved. -ringo>>> +@item rewind +Rewinds the tape. (Ignores @var{number}). -@item -R -Print the record number where a message is generated. -@xref{Additional Information}. +@item offline +@itemx rewoff1 +Rewinds the tape and takes the tape device off-line. (Ignores @var{number}). -@item -S -Archive sparse files sparsely. @xref{Sparse Files}. +@item status +Prints status information about the tape unit. -@item -T @var{file} -Read file-name arguments from a file on the file system. -@xref{File Name Lists}. +@end table -@item -W -Check for discrepancies in the archive immediately after it is -written. @xref{Write Verification}. +@FIXME{Is there a better way to frob the spacing on the list?} -@item -Z -Specify a compressed archive. @xref{Compressed Archives}. +If you don't specify a @var{tapename}, @command{mt} uses the environment +variable @env{TAPE}; if @env{TAPE} is not set, @command{mt} uses the device +@file{/dev/rmt12}. -@item -b @var{number} -Specify the blocking factor of an archive. @xref{Blocking Factor}. +@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. -@item -f @var{archive-name} -Name the archive. @xref{Archive Name}). +@FIXME{New node on how to find an archive?} -@item -h -Treat a symbolic link as an alternate name for the file the link -points to. @xref{Symbolic Links}. +If you use @value{op-extract} with the @value{op-label} option specified, +@command{tar} will read an archive label (the tape head has to be positioned +on it) and print an error if the archive label doesn't match the +@var{archive-name} specified. @var{archive-name} can be any regular +expression. If the labels match, @command{tar} extracts the archive. +@value{xref-label}. +@FIXME-xref{Matching Format Parameters}@FIXME{fix cross +references}@samp{tar --list --label} will cause @command{tar} to print the +label. + +@FIXME{Program to list all the labels on a tape?} + +@node Using Multiple Tapes +@section Using Multiple Tapes +@UNREVISED + +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 @value{op-exclude} or dumping entire filesystems. +Therefore, @command{tar} supports multiple tapes automatically. + +Use @value{op-multi-volume} on the command line, and then @command{tar} will, +when it reaches the end of the tape, prompt for another tape, and +continue the archive. Each tape will have an independent archive, and +can be read without needing the other. (As an exception to this, the +file that @command{tar} was archiving when it ran out of tape will usually +be split between the two archives; in this case you need to extract from +the first archive, using @value{op-multi-volume}, and then put in the +second tape when prompted, so @command{tar} can restore both halves of the +file.) + +@acronym{GNU} @command{tar} multi-volume archives do not use a truly +portable format. You need @acronym{GNU} @command{tar} at both end to +process them properly. + +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. +@item y +Request @command{tar} to begin writing the next volume. +@end table -@item -i -Ignore end-of-archive entries. @xref{Archive Reading Options}. +(You should only type @samp{y} after you have changed the tape; +otherwise @command{tar} will write over the volume it just finished.) + +If you want more elaborate behavior than this, give @command{tar} the +@value{op-info-script} option. The file @var{script-name} is expected +to be a program (or shell script) to be run instead of the normal +prompting procedure. If the program fails, @command{tar} exits; +otherwise, @command{tar} begins writing the next volume. The behavior +of the +@samp{n} response to the normal tape-change prompt is not available +if you use @value{op-info-script}. + +The method @command{tar} uses to detect end of tape is not perfect, and +fails on some operating systems or on some devices. You can use the +@value{op-tape-length} option if @command{tar} can't detect the end of the +tape itself. This option selects @value{op-multi-volume} automatically. +The @var{size} argument should then be the usable size of the tape. +But for many devices, and floppy disks in particular, this option is +never required for real, as far as we know. + +The volume number used by @command{tar} in its tape-change prompt +can be changed; if you give the @value{op-volno-file} option, then +@var{file-of-number} should be an unexisting 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 @value{ref-label}, it @emph{only} affects the number used in +the prompt.) + +If you want @command{tar} to cycle through a series of tape drives, then +you can use the @samp{n} response to the tape-change prompt. This is +error prone, however, and doesn't work at all with @value{op-info-script}. +Therefore, if you give @command{tar} multiple @value{op-file} options, then +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). + +Multi-volume archives + +With @value{op-multi-volume}, @command{tar} will not abort when it cannot +read or write any more data. Instead, it will ask you to prepare a new +volume. If the archive is on a magnetic tape, you should change tapes +now; if the archive is on a floppy disk, you should change disks, etc. + +Each volume of a multi-volume archive is an independent @command{tar} +archive, complete in itself. For example, you can list or extract any +volume alone; just don't specify @value{op-multi-volume}. However, if one +file in the archive is split across volumes, the only way to extract +it successfully is with a multi-volume extract command @samp{--extract +--multi-volume} (@samp{-xM}) starting on or before the volume where +the file begins. + +For example, let's presume someone has two tape drives on a system +named @file{/dev/tape0} and @file{/dev/tape1}. For having @acronym{GNU} +@command{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: + +@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 -@item -k -Prevent overwriting during extraction. @xref{File Writing Options}. +@menu +* Multi-Volume Archives:: Archives Longer than One Tape or Disk +* Tape Files:: Tape Files +@end menu -@item -l -Prevent @code{tar} from crossing file system boundaries when -archiving. @xref{File Exclusion}. +@node Multi-Volume Archives +@subsection Archives Longer than One Tape or Disk +@cindex Multi-volume archives +@UNREVISED -@item -m -Set the modification time of extracted files to the time they were -extracted. @xref{File Writing Options}. +To create an archive that is larger than will fit on a single unit of +the media, use the @value{op-multi-volume} option in conjunction with +the @value{op-create} option (@pxref{create}). A +@dfn{multi-volume} archive can be manipulated like any other archive +(provided the @value{op-multi-volume} option is specified), but is +stored on more than one tape or disk. -@item -o -Create an old format archive. @xref{Old Style File Information}. +When you specify @value{op-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. -@item -p -Set the modes of extracted files to those recorded in the archive. -@xref{File Writing Options}. +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 @value{op-list}, without @value{op-multi-volume} specified. +To extract an archive member from one volume (assuming it is described +that volume), use @value{op-extract}, again without +@value{op-multi-volume}. -@item -s -Help process large lists of file-names on machines with small amounts of -memory. @xref{Archive Reading Options}. +If an archive member is split across volumes (ie. its entry begins on +one volume of the media and ends on another), you need to specify +@value{op-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. -@item -v -Print the names of files or archive members they are being operated -on. @xref{Additional Information}. +@value{op-info-script} is like @value{op-multi-volume}, except that +@command{tar} does not prompt you directly to change media volumes when +a volume is full---instead, @command{tar} runs commands you have stored +in @var{script-name}. For example, this option can be used to eject +cassettes, or to broadcast messages such as @samp{Someone please come +change my tape} when performing unattended backups. When @var{script-name} +is done, @command{tar} will assume that the media has been changed. -@item -w -@c <<>> +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. -@item -z -Specify a compressed archive. @xref{Compressed Archives}. +If a multi-volume archive was labeled using @value{op-label} +(@value{pxref-label}) when it was created, @command{tar} will not +automatically label volumes which are added later. To label subsequent +volumes, specify @value{op-label} again in conjunction with the +@value{op-append}, @value{op-update} or @value{op-concatenate} operation. -@item -z -z -Create a whole block sized compressed archive. @xref{Compressed Archives}. -@c I would rather this were -Z. it is the only double letter short -@c form. +@cindex Labeling multi-volume archives +@FIXME{example} -@item -C @file{directory} -Change the working directory. @xref{Changing Working Directory}. +@FIXME{There should be a sample program here, including an exit +before end. Is the exit status even checked in tar? :-(} -@item -F @var{program-file} -Create a multi-volume archive via a script. @xref{Multi-Volume Archives}. +@table @kbd +@item --multi-volume +@itemx -M +Creates a multi-volume archive, when used in conjunction with +@value{op-create}. To perform any other operation on a multi-volume +archive, specify @value{op-multi-volume} in conjunction with that +operation. -@item -X @file{file} -Exclude files which match any of the regular expressions listed in -the file @file{file}. @xref{File Exclusion}. +@item --info-script=@var{program-file} +@itemx -F @var{program-file} +Creates a multi-volume archive via a script. Used in conjunction with +@value{op-create}. @end table -@node Data Format Details, Concept Index, Quick Reference, Top -@appendix Details of the Archive Data Format +Beware that there is @emph{no} real standard about the proper way, for +a @command{tar} archive, to span volume boundaries. If you have a +multi-volume created by some vendor's @command{tar}, there is almost +no chance you could read all the volumes with @acronym{GNU} +@command{tar}. The converse is also true: you may not expect +multi-volume archives created by @acronym{GNU} @command{tar} to be +fully recovered by vendor's @command{tar}. Since there is little +chance that, in mixed system configurations, some vendor's +@command{tar} will work on another vendor's machine, and there is a +great chance that @acronym{GNU} @command{tar} will work on most of +them, your best bet is to install @acronym{GNU} @command{tar} on all +machines between which you know exchange of files is possible. + +@node Tape Files +@subsection Tape Files +@UNREVISED + +To give the archive a name which will be recorded in it, use the +@value{op-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 @value{op-list}. +If you are creating a multi-volume archive with +@value{op-multi-volume}@FIXME-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 @value{op-label} +option when reading an archive, it checks to make sure the label on the +tape matches the one you give. @value{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: -This chapter is based heavily on John Gilmore's @i{tar}(5) manual page -for the public domain @code{tar} that GNU @code{tar} is based on. -@c it's been majorly edited since, we may be able to lose this. +@example +@kbd{--label="@var{some-prefix} `date +@var{some-format}`"} +@end example -The archive media contains a series of records, each of which contains -512 bytes. Each archive member is represented by a header record, -which describes the file, followed by zero or more records which -represent the contents of the file. At the end of the archive file -there may be a record consisting of a series of binary zeros, as an -end-of-archive marker. GNU @code{tar} writes a record of zeros at the -end of an archive, but does not assume that such a record exists when -reading an archive. +or such, for pushing a common date in all volumes or an archive set. -Records may be grouped into @dfn{blocks} for I/O operations. A block -of records is written with a single @code{write()} operation. The -number of records in a block is specified using the @samp{+block-size} -option. @xref{Blocking Factor}, for more information about specifying -block size. +@node label +@section Including a Label in the Archive +@cindex Labeling an archive +@cindex Labels on the archive media +@UNREVISED -@menu -* Header Data:: The Distribution of Data in the Header -* Header Fields:: The Meaning of Header Fields -* Sparse File Handling:: Fields to Handle Sparse Files -@end menu +@table @kbd +@item -V @var{name} +@itemx --label=@var{name} +Create archive with volume name @var{name}. +@end table -@node Header Data, Header Fields, Data Format Details, Data Format Details -@appendixsec The Distribution of Data in the Header - -The header record is defined in C as follows: -@c I am taking the following code on faith. - -@example -@r{Standard Archive Format - Standard TAR - USTAR} - -#define RECORDSIZE 512 -#define NAMSIZ 100 -#define TUNMLEN 32 -#define TGNMLEN 32 -#define SPARSE_EXT_HDR 21 -#define SPARSE_IN_HDR 4 - -struct sparse @{ - char offset[12]; - char numbytes[12]; -@}; - -union record @{ - char charptr[RECORDSIZE]; - struct header @{ - char name[NAMSIZ]; - char mode[8]; - char uid[8]; - char gid[8]; - char size[12]; - char mtime[12]; - char chksum[8]; - char linkflag; - char linkname[NAMSIZ]; - char magic[8]; - char uname[TUNMLEN]; - char gname[TGNMLEN]; - char devmajor[8]; - char devminor[8]; - -@r{The following fields were added by gnu and are not used by other} -@r{versions of @code{tar}}. - char atime[12]; - char ctime[12]; - char offset[12]; - char longnames[4]; -@r{The next three fields were added by gnu to deal with shrinking down} -@r{sparse files.} - struct sparse sp[SPARSE_IN_HDR]; - char isextended; -@r{This is the number of nulls at the end of the file, if any.} - char ending_blanks[12]; - - @} header; - - struct extended_header @{ - struct sparse sp[21]; - char isextended; - @} ext_hdr; - -@}; -@c <<< this whole thing needs to be put into better english - -@r{The checksum field is filled with this while the checksum is computed.} -#define CHKBLANKS " " @r{8 blanks, no null} - -@r{Inclusion of this field marks an archive as being in standard} -@r{Posix format (though GNU tar itself is not Posix conforming). GNU} -@r{tar puts "ustar" in this field if uname and gname are valid.} -#define TMAGIC "ustar " @r{7 chars and a null} - -@r{The magic field is filled with this if this is a GNU format dump entry.} -#define GNUMAGIC "GNUtar " @r{7 chars and a null} - -@r{The linkflag defines the type of file.} -#define LF_OLDNORMAL '\0' @r{Normal disk file, Unix compatible} -#define LF_NORMAL '0' @r{Normal disk file} -#define LF_LINK '1' @r{Link to previously dumped file} -#define LF_SYMLINK '2' @r{Symbolic link} -#define LF_CHR '3' @r{Character special file} -#define LF_BLK '4' @r{Block special file} -#define LF_DIR '5' @r{Directory} -#define LF_FIFO '6' @r{FIFO special file} -#define LF_CONTIG '7' @r{Contiguous file} - -@r{hhe following are further link types which were defined later.} - -@r{This is a dir entry that contains the names of files that were in} -@r{the dir at the time the dump was made.} -#define LF_DUMPDIR 'D' - -@r{This is the continuation of a file that began on another volume} -#define LF_MULTIVOL 'M' - -@r{This is for sparse files} -#define LF_SPARSE 'S' - -@r{This file is a tape/volume header. Ignore it on extraction.} -#define LF_VOLHDR 'V' - -@r{These are bits used in the mode field - the values are in octal} -#define TSUID 04000 @r{Set UID on execution} -#define TSGID 02000 @r{Set GID on execution} -#define TSVTX 01000 @r{Save text (sticky bit)} - -@r{These are 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} -@end example - - -All characters in headers are 8-bit characters in the local variant of -ASCII. Each field in the header is contiguous; that is, there is no -padding in the header format. - -Data representing the contents of files is not translated in any way -and is not constrained to represent characters in any character set. -@code{tar} does not distinguish between text files and binary files. +This option causes @command{tar} to write out a @dfn{volume header} at +the beginning of the archive. If @value{op-multi-volume} is used, each +volume of the archive will have a volume header of @samp{@var{name} +Volume @var{n}}, where @var{n} is 1 for the first volume, 2 for the +next, and so on. -The @code{name}, @code{linkname}, @code{magic}, @code{uname}, and -@code{gname} fields contain null-terminated character strings. All -other fields contain zero-filled octal numbers in ASCII. Each numeric -field of width @var{w} contains @var{w} @minus{} 2 digits, a space, and a -null, except @code{size} and @code{mtime}, which do not contain the -trailing null. - -@node Header Fields, Sparse File Handling, Header Data, Data Format Details -@appendixsec The Meaning of Header Fields - -The @code{name} field contains the name of the file. -<<< how big a name before field overflows? - -The @code{mode} field contains nine bits which specify file -permissions, and three bits which specify the Set UID, Set GID, and -Save Text (``stick'') modes. Values for these bits are defined above. -@xref{File Writing Options}, for information on how file permissions -and modes are used by @code{tar}. - -The @code{uid} and @code{gid} fields contain the numeric user and -group IDs of the file owners. If the operating system does not -support numeric user or group IDs, these fields should be ignored. -@c but are they? - -The @code{size} field contains the size of the file in bytes; this -field contains a zero if the header describes a link to a file. - -The @code{mtime} field contains the modification time of the file. -This is the ASCII representation of the octal value of the last time -the file was modified, represented as an integer number of seconds -since January 1, 1970, 00:00 Coordinated Universal Time. -@xref{File Writing Options}, for a description of how @code{tar} uses -this information. - -The @code{chksum} field contains the ASCII representation of the octal -value of the simple sum of all bytes in the header record. To -generate this sum, each 8-bit byte in the header is added to an -unsigned integer, which has been initialized to zero. The precision -of the integer is seventeen bits. When calculating the checksum, the -@code{chksum} field itself is treated as blank. - -The @code{atime} and @code{ctime} fields are used when making -incremental backups; they store, respectively, the file's access time -and last inode-change time. +@FIXME{Should the arg to --label be a quoted string?? No.} -The value in the @code{offset} field is used when making a -multi-volume archive. The offset is number of bytes into the file -that we need to go to pick up where we left off in the previous -volume, i.e the location that a continued file is continued from. +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 +@value{op-label} option in conjunction with the @value{op-create} operation +to include a label entry in the archive as it is being created. -The @code{longnames} field supports a feature that is not yet -implemented. This field should be empty. +If you create an archive using both @value{op-label} and +@value{op-multi-volume}, 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. +@FIXME-xref{Multi-Volume Archives, for information on creating multiple +volume archives.} + +If you list or extract an archive using @value{op-label}, @command{tar} will +print an error if the archive label doesn't match the @var{archive-label} +specified, and will then not list nor extract the archive. 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 @value{op-multi-volume} 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 @value{op-label} was once called @samp{--volume}, but is not available +under that name anymore. -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 IDs are used rather than the values in the -@code{uid} and @code{gid} fields. +To find out an archive's label entry (or to find out if an archive has +a label at all), use @samp{tar --list --verbose}. @command{tar} will +print the label first, and then print archive member information, as +in the example below: -The @code{sp} field is used to archive sparse files efficiently. -@xref{Sparse File Handling}, for a description of this field, and -other fields it may imply. +@example +$ @kbd{tar --verbose --list --file=iamanarchive} +V--------- 0 0 0 1992-03-07 12:01 iamalabel--Volume Header-- +-rw-rw-rw- ringo user 40 1990-05-21 13:30 iamafilename +@end example -The @code{typeflag} field specifies the file's type. If a particular -implementation does not recognize or permit the specified type, -@code{tar} extracts the file as if it were a regular file, and reports -the discrepancy on the standard error. @xref{File Types}. @xref{GNU -File Types}. +@table @kbd +@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 +@value{op-create} option. Checks to make sure the archive label +matches the one specified (when used in conjunction with the +@value{op-extract} option. +@end table -@menu -* File Types:: File Types -* GNU File Types:: Additional File Types Supported by GNU -@end menu +To get a common information on all tapes of a series, use the +@value{op-label} option. 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: -@node File Types, GNU File Types, Header Fields, Header Fields -@appendixsubsec File Types +@example +$ @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 example -The following flags are used to describe file types: +Also note that each label has its own date and time, which corresponds +to when @acronym{GNU} @command{tar} 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. -@table @code -@item LF_NORMAL -@itemx LF_OLDNORMAL -Indicates a regular file. In order to be compatible with older -versions of @code{tar}, a @code{typeflag} value of @code{LF_OLDNORMAL} -should be silently recognized as a regular file. New archives should -be created using @code{LF_NORMAL} for regular files. For backward -compatibility, @code{tar} treats a regular file whose name ends with a -slash as a directory. - -@item LF_LINK -Indicates a link to another file, of any type, which has been -previously archived. @code{tar} identifies linked files in Unix by -matching device and inode numbers. The linked-to name is specified in -the @code{linkname} field with a trailing null. - -@item LF_SYMLINK -Indicates a symbolic link to another file. The linked-to -name is specified in the @code{linkname} field with a trailing null. -@xref{File Writing Options}, for information on archiving files -referenced by a symbolic link. - -@item LF_CHR -@itemx LF_BLK -Indicate 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. Operating -systems may map the device specifications to their own local -specification, or may ignore the entry. - -@item LF_DIR -Indicates 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) that the directory can hold. A -@code{size} field of zero indicates no size limitations. Systems that -do not support size limiting in this manner should ignore the -@code{size} field. +@FIXME{was --volume} + +@node verify +@section Verifying Data as It is Stored +@cindex Verifying a write operation +@cindex Double-checking a write operation -@item LF_FIFO -Indicates a FIFO special file. Note that archiving a FIFO file -archives the existence of the file and not its contents. - -@item LF_CONTIG -Indicates a contiguous file. Contiguous files are the same as normal -files except that, in operating systems that support it, all the -files' disk space is allocated contiguously. Operating systems which -do not allow contiguous allocation should silently treat this type as -a normal file. - -@item 'A' @dots{} -@itemx 'Z' -These are reserved for custom implementations. Some of these are used -in the GNU modified format, which is described below. @xref{GNU File -Types}. +@table @kbd +@item -W +@itemx --verify +Attempt to verify the archive after writing. @end table -Certain other flag values are reserved for specification in future -revisions of the P1003 standard, and should not be used by any -@code{tar} program. +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. -@node GNU File Types, , File Types, Header Fields -@appendixsubsec Additional File Types Supported by GNU +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. -GNU @code{tar} uses additional file types to describe new types of -files in an archive. These are listed below. +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. -@table @code -@item LF_DUMPDIR -@itemx 'D' -Indicates a directory and a list of files created by the -@samp{+incremental} option. The @code{size} field gives the total -size of the associated list of files. Each file name is preceded by -either a @code{'Y'} (the file should be in this archive) or an -@code{'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. +To check for discrepancies in an archive immediately after it is +written, use the @value{op-verify} option in conjunction with +the @value{op-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. -@item LF_MULTIVOL -@itemx 'M' -Indicates a file continued from another volume of a multi-volume -archive (@pxref{Multi-Volume Archives}). 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 LF_SPARSE -@itemx 'S' -Indicates a sparse file. @xref{Sparse Files}. @xref{Sparse File -Handling}. - -@item LF_VOLHDR -@itemx 'V' -Marks an archive label that was created using the @samp{+label} option -when the archive was created (@pxref{Archive Label}. The @code{name} -field contains the argument to the option. The @code{size} field is -zero. Only the first file in each volume of an archive should have -this type. -@end table +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. -@node Sparse File Handling, , Header Fields, Data Format Details -@appendixsec Fields to Handle Sparse Files +One can explicitly compare an already made archive with the file system +by using the @value{op-compare} option, instead of using the more automatic +@value{op-verify} option. @value{xref-compare}. + +Note that these two options have a slightly different intent. The +@value{op-compare} option how identical are the logical contents of some +archive with what is on your disks, while the @value{op-verify} option is +really for checking if the physical contents agree and if the recording +media itself is of dependable quality. So, for the @value{op-verify} +operation, @command{tar} tries to defeat all in-memory cache pertaining to +the archive, while it lets the speed optimization undisturbed for the +@value{op-compare} option. If you nevertheless use @value{op-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 @value{op-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 @value{op-verify} option will not work in conjunction with the +@value{op-multi-volume} option or the @value{op-append}, +@value{op-update} and @value{op-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 -The following header information was added to deal with sparse files -(@pxref{Sparse Files}): +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). -@c TALK TO MIB -The @code{sp} field (fields? something else?) is an array of -@code{struct sparse}. Each @code{struct sparse} contains two -12-character strings, which represent the offset into the file and the -number of bytes to be written at that offset. The offset is absolute, -and not relative to the offset in preceding array elements. +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. -The header can contain four of these @code{struct sparse}; if more are -needed, they are not stored in the header, instead, the flag -@code{isextended} is set and the next record is an -@code{extended_header}. -@c @code{extended_header} or @dfn{extended_header} ??? the next -@c record after the header, or in the middle of it. +@node Free Software Needs Free Documentation +@appendix Free Software Needs Free Documentation +@include freemanuals.texi -The @code{isextended} flag is only set for sparse files, and then only -if extended header records are needed when archiving the file. +@node Copying This Manual +@appendix Copying This Manual -Each extended header record can contain an array of 21 sparse -structures, as well as another @code{isextended} flag. There is no -limit (except that implied by the archive media) on the number of -extended header records that can be used to describe a sparse file. +@menu +* GNU Free Documentation License:: License for copying this manual +@end menu -@c so is @code{extended_header} the right way to write this? +@include fdl.texi -@node Concept Index, , Data Format Details, Top -@unnumbered Concept Index +@node Index +@appendix Index @printindex cp @@ -3958,4 +8532,6 @@ extended header records that can be used to describe a sparse file. @contents @bye - +@c Local variables: +@c texinfo-column-for-description: 32 +@c End: