X-Git-Url: https://git.dogcows.com/gitweb?a=blobdiff_plain;f=doc%2Ftar.texi;h=7cdf0ddca5de3ed67ca65955148b5aa5408102a4;hb=2af87fa2776c8125a587a9b0c2c4fae3bf921ff7;hp=7ed5fa492aa4b430a1ca54c2d18866a17cd6c8af;hpb=6556021bfdacadb3759670964e91911320c870d9;p=chaz%2Ftar diff --git a/doc/tar.texi b/doc/tar.texi index 7ed5fa4..ece40f4 100644 --- a/doc/tar.texi +++ b/doc/tar.texi @@ -1,2549 +1,11235 @@ -\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 Maintenance notes: +@c 1. Pay attention to @FIXME{}s and @UNREVISED{}s +@c 2. Before creating final variant: +@c 2.1. Run 'make check-options' to make sure all options are properly +@c documented; +@c 2.2. Run 'make master-menu' (see comment before the master menu). -@c Search for comments marked with !! or <<< (or >>>) +@include rendition.texi +@include value.texi -@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).>>> +@defcodeindex op +@defcodeindex kw -@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".>>> +@c Put everything in one index (arbitrarily chosen to be the concept index). +@syncodeindex fn cp +@syncodeindex ky cp +@syncodeindex pg cp +@syncodeindex vr cp +@syncodeindex kw cp -@c <<< @code{tar} is always lower case, in bold. >>> +@copying -@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 +This manual is for @acronym{GNU} @command{tar} (version +@value{VERSION}, @value{UPDATED}), which creates and extracts files +from archives. -@c <<< (don't forget to comment these out in final draft) -ringo +Copyright @copyright{} 1992, 1994--1997, 1999--2001, 2003--2013 Free +Software Foundation, Inc. -@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 +@quotation +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being ``GNU General Public License'', with the +Front-Cover Texts being ``A GNU Manual'', and with the Back-Cover Texts +as in (a) below. A copy of the license is included in the section +entitled ``GNU Free Documentation License''. + +(a) The FSF's Back-Cover Text is: ``You have the freedom to +copy and modify this GNU manual.'' +@end quotation +@end copying -@iftex -@c finalout -@end iftex +@dircategory Archiving +@direntry +* Tar: (tar). Making tape (or disk) archives. +@end direntry -@ifinfo -This file documents @code{tar}, a utility used to store, backup, and -transport files. +@dircategory Individual utilities +@direntry +* tar: (tar)tar invocation. Invoking @GNUTAR{}. +@end direntry -Copyright (C) 1992 Free Software Foundation, Inc. DRAFT! -@c Need to put distribution information here when ready. -@end ifinfo +@shorttitlepage @acronym{GNU} @command{tar} -@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, Michael I. Bushnell, and Jay Fenlason -@c <<>>> +@title @acronym{GNU} tar: an archiver tool +@subtitle @value{RENDITION} @value{VERSION}, @value{UPDATED} +@author John Gilmore, Jay Fenlason et al. @page @vskip 0pt plus 1filll -Copyright @copyright{} 1992 Free Software Foundation, Inc. - -@sp 2 -This draft is not yet ready for distribution. +@insertcopying @end titlepage -@ifinfo -@node Top, Introduction, (dir), (dir) -@top @code{tar} - -This file documents @code{tar}, a utility used to store, backup, and -transport files. +@ifnottex +@node Top +@top @acronym{GNU} tar: an archiver tool -@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 +@insertcopying -@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 +@cindex file archival +@cindex archiving files -@node Introduction, Invoking @code{tar}, Top, Top -@chapter @code{tar}: The GNU Tape Archiver - -You can use @code{tar} to create an @dfn{archive}---a single file -which contains other files' 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. - -The name @code{tar} comes from the words ``Tape ARchiver'', but -@code{tar} can actually process archives wherever they are stored; on -tapes and disk files, for example. In addition, tar can read archives -from standard input or write them to standard output. (This is often -useful if redirected another program with a pipe.) - -@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 -@chapter Tutorial Introduction to @code{tar} +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 -This chapter guides you through some basic examples of @code{tar} -operations. If you already know how to use some other version of -@code{tar}, then you probably don't need to read this chapter. This -chapter omits complicated details about many of the ways @code{tar} -works. See later chapters for full information. +@c The master menu goes here. +@c +@c NOTE: To update it from within Emacs, make sure mastermenu.el is +@c loaded and run texinfo-master-menu. +@c To update it from the command line, run +@c +@c make master-menu @menu -* 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 +* Introduction:: +* Tutorial:: +* tar invocation:: +* operations:: +* Backups:: +* Choosing:: +* Date input formats:: +* Formats:: +* Media:: +* Reliability and security:: + +Appendices + +* Changes:: +* Configuring Help Summary:: +* Fixing Snapshot Files:: +* Tar Internals:: +* Genfile:: +* Free Software Needs Free Documentation:: +* GNU Free Documentation License:: +* Index of Command Line Options:: +* Index:: + +@detailmenu + --- The Detailed Node Listing --- + +Introduction + +* Book Contents:: What this Book Contains +* Definitions:: Some Definitions +* What tar Does:: What @command{tar} Does +* Naming tar Archives:: How @command{tar} Archives are Named +* Authors:: @GNUTAR{} Authors +* Reports:: Reporting bugs or suggestions -@section What @code{tar} Does +Tutorial Introduction to @command{tar} + +* assumptions:: +* stylistic conventions:: +* basic tar options:: Basic @command{tar} Operations and Options +* frequent operations:: +* Two Frequent Options:: +* create:: How to Create Archives +* list:: How to List Archives +* extract:: How to Extract Members from an Archive +* going further:: -The @code{tar} program is used to create and manipulate @code{tar} -archives. An @dfn{archive} is a single file which contains within it -the contents of many files. In addition, the archive identifies the -names of the files, their owner, and so forth. +Two Frequently Used Options -You can use @code{tar} archives in many ways. Initially, @code{tar} -archives were used to store files conveniently on magnetic tape. The -name @samp{tar} comes from this use; it stands for Tape ARchiver. -Often, @code{tar} archives are used to store related files for -convenient file transfer over a network. For example, the GNU Project -distributes its software bundled into @code{tar} archives, so that all -the files relating to a particular program (or set of related programs) -can be transferred as a single unit. +* file tutorial:: +* verbose tutorial:: +* help tutorial:: + +How to Create Archives + +* prepare for examples:: +* Creating the archive:: +* create verbose:: +* short create:: +* create dir:: + +How to List Archives -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 @code{ls}, @code{cat}, and so forth), and the term -@dfn{members} 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. +* list dir:: -The @code{tar} program provides the ability to create @code{tar} -archives, as well as for various other kinds of manipulation. The term -@dfn{extraction} is used to refer to the process of copying an archive -member into a file in the filesystem. One might speak of extracting a -single member. Extracting all the members of an archive is often called -extracting the archive. Often the term @dfn{unpack} is used to refer to -the extraction of many or all the members of an archive. - -Conventionally, @code{tar} archives are given names ending with -@samp{.tar}. This is not necessary for @code{tar} to operate properly, -but this manual follows the convention in order to get the reader used -to seeing it. - -Occasionally archive members are referred to as files. For people -familiar with the operation of @code{tar}, this causes no difficulty. -However, this manual consistently uses the terminology above in -referring to files and archive members, to make it easier to learn how -to use @code{tar}. - -@section Creating Archives - -To create a new archive, use @samp{tar --create}. You should generally -use the @samp{--file} option to specify the name the tar archive will -have. Then specify the names of the files you wish to place in the new -archive. For example, to place the files @file{apple}, @file{angst}, -and @file{asparagus} into an archive named @file{afiles.tar}, use the -following command: +How to Extract Members from an Archive -@example -tar --create --file=afiles.tar apple angst asparagus -@end example +* extracting archives:: +* extracting files:: +* extract dir:: +* extracting untrusted archives:: +* failing commands:: + +Invoking @GNUTAR{} -The order of the arguments is not important. You could also say: +* Synopsis:: +* using tar options:: +* Styles:: +* All Options:: +* help:: +* defaults:: +* verbose:: +* checkpoints:: +* warnings:: +* interactive:: + +The Three Option Styles + +* Long Options:: Long Option Style +* Short Options:: Short Option Style +* Old Options:: Old Option Style +* Mixing:: Mixing Option Styles + +All @command{tar} Options + +* Operation Summary:: +* Option Summary:: +* Short Option Summary:: + +@GNUTAR{} Operations + +* Basic tar:: +* Advanced tar:: +* create options:: +* extract options:: +* backup:: +* Applications:: +* looking ahead:: -@example -tar apple --create angst --file=afiles.tar asparagus -@end example +Advanced @GNUTAR{} Operations -This order is harder to understand however. In this manual, we will -list the arguments in a reasonable order to make the commands easier to -understand, but you can type them in any order you wish. +* Operations:: +* append:: +* update:: +* concatenate:: +* delete:: +* compare:: -If you don't specify the names of any files to put in the archive, then -tar will create an empty archive. So, the following command will create -an archive with nothing in it: +How to Add Files to Existing Archives: @option{--append} -@example -tar --create --file=empty-archive.tar -@end example +* appending files:: Appending Files to an Archive +* multiple:: -Whenever you use @samp{tar --create}, @code{tar} will erase the current -contents of the file named by @samp{--file} if it exists. To add files -to an existing archive, you need to use a different option. -@xref{Adding to Archives} for information on how to do this. +Updating an Archive -When @samp{tar --create} creates an archive, the member names of the -members of the archive are exactly the same as the file names as you -typed them in the @code{tar} command. So, the member names of -@file{afiles} (as created by the first example above) are @file{apple}, -@file{angst}, and @file{asparagus}. However, suppose an archive were -created with this command: +* how to update:: -@example -tar --create --file=bfiles.tar ./balloons baboon ./bodacious -@end example +Options Used by @option{--create} -Then, the three files @file{balloons}, @file{baboon}, and -@file{bodacious} would get placed in the archive (because @file{./} is a -synonym for the current directory), but their member names would be -@file{./balloons}, @file{baboon}, and @file{./bodacious}. +* override:: Overriding File Metadata. +* Ignore Failed Read:: -If you want to see the progress of tar as it writes files into the -archive, you can use the @samp{--verbose} option. +Options Used by @option{--extract} -If one of the files named to @samp{tar --create} is a directory, then -the operation of tar is more complicated. @xref{Tar and Directories}, -the last section of this tutorial, for more information. +* Reading:: Options to Help Read Archives +* Writing:: Changing How @command{tar} Writes Files +* Scarce:: Coping with Scarce Resources -If you don't specify the @samp{--file} option, then @code{tar} will use -a default. Usually this default is some physical tape drive attached to -your machine. If there is no tape drive attached, or the default is not -meaningful, then tar will print an error message. This error message -might look roughly like one of the following: +Options to Help Read Archives -@example -tar: can't open /dev/rmt8 : No such device or address -tar: can't open /dev/rsmt0 : I/O error -@end example +* read full records:: +* Ignore Zeros:: -If you get an error like this, mentioning a file you didn't specify -(@file{/dev/rmt8} or @file{/dev/rsmt0} in the examples above), then @code{tar} -is using a default value for @samp{--file}. You should generally specify a -@samp{--file} argument whenever you use @code{tar}, rather than relying -on a default. +Changing How @command{tar} Writes Files -@section Listing Archives +* Dealing with Old Files:: +* Overwrite Old Files:: +* Keep Old Files:: +* Keep Newer Files:: +* Unlink First:: +* Recursive Unlink:: +* Data Modification Times:: +* Setting Access Permissions:: +* Directory Modification Times and Permissions:: +* Writing to Standard Output:: +* Writing to an External Program:: +* remove files:: -Use @samp{tar --list} to print the names of members stored in an -archive. Use a @samp{--file} option just as with @samp{tar --create} to -specify the name of the archive. For example, the archive -@file{afiles.tar} created in the last section could be examined with the -command @samp{tar --list --file=afiles.tar}. The output of tar would -then be: +Coping with Scarce Resources -@example -apple -angst -asparagus -@end example +* Starting File:: +* Same Order:: -The archive @file{bfiles.tar} would list as follows: +Performing Backups and Restoring Files -@example -./baloons -baboon -./bodacious -@end example +* Full Dumps:: Using @command{tar} to Perform Full Dumps +* Incremental Dumps:: Using @command{tar} to Perform Incremental Dumps +* Backup Levels:: Levels of Backups +* Backup Parameters:: Setting Parameters for Backups and Restoration +* Scripted Backups:: Using the Backup Scripts +* Scripted Restoration:: Using the Restore Script -(Of course, @samp{tar --list --file=empty-archive.tar} would produce no -output.) - -If you use the @samp{--verbose} option with @samp{tar --list}, then tar -will print out a listing reminiscent of @samp{ls -l}, showing owner, -file size, and so forth. - -You can also specify member names when using @samp{tar --list}. In this -case, tar will only list the names of members you identify. For -example, @samp{tar --list --file=afiles.tar apple} would only print -@samp{apple}. It is essential when specifying member names to tar that -you give the exact member names. For example, @samp{tar --list ---file=bfiles baloons} would produce no output, because there is no -member named @file{baloons}, only one named @file{./baloons}. While the -file names @file{baloons} and @file{./baloons} name the same file, -member names are compared using a simplistic name comparison, in which -an exact match is necessary. - -@section Extracting Members from an Archive - -In order to extract members from an archive, use @samp{tar --extract}. -Specify the name of the archive with @samp{--file}. To extract specific -archive members, give their member names as arguments. It essential to -give their exact member name, as printed by @samp{tar --list}. This -will create a copy of the archive member, with a file name the same as -its name in the archive. - -Keeping the example of the two archives created at the beginning of this -tutorial, @samp{tar --extract --file=afiles.tar apple} would create a -file @file{apple} in the current directory with the contents of the -archive member @file{apple}. It would remove any file named -@file{apple} already present in the directory, but it would not change -the archive in any way. - -Remember that specifying the exact member name is important. @samp{tar ---extract --file=bfiles.tar baloons} will fail, because there is no -member named @file{baloons}. To extract the member named -@file{./baloons} you would need to specify @samp{tar --extract ---file=bfiles.tar ./baloons}. To find the exact member names of the -members of an archive, use @samp{tar --list} (@pxref{Listing -Archives}). - -If you do not list any archive member names, then @samp{tar --extract} -will extract all the members of the archive. - -If you give the @samp{--verbose} option, then @samp{tar --extract} will -print the names of the archive members as it extracts them. - -@section Adding Files to Existing Archives - -If you want to add files to an existing archive, then don't use -@samp{tar --create}. That will erase the archive and create a new one -in its place. Instead, use @samp{tar --append}. The command @samp{tar ---append --file=afiles.tar arbalest} would add the file @file{arbalest} -to the existing archive @file{afiles.tar}. The archive must already -exist in order to use @samp{tar --append}. - -As with @samp{tar --create}, the member names of the newly added files -will be the exact same as their names given on the command line. The -@samp{--verbose} option will print out the names of the files as they -are written into the archive. - -If you add a file to an archive using @samp{tar --append} with the -same name as an archive member already present in the archive, then the -old member is not deleted. What does happen, however, is somewhat -complex. @xref{Multiple Members with the Same Name}. If you want to -replace an archive member, use @samp{tar --delete} first, and then use -@samp{tar --append}. - -@section Deleting Members from Archives - -You can delete members from an archive using @samp{tar --delete}. -Specify the name of the archive with @samp{--file}. List the member -names of the members to be deleted. (If you list no member names, then -nothing will be deleted.) The @samp{--verbose} option will cause -@code{tar} to print the names of the members as they are deleted. As -with @samp{tar --extract}, it is important that you give the exact -member names when using @samp{tar --delete}. Use @samp{tar --list} to -find out the exact member names in an archive (@pxref{Listing -Archives}). - -The @samp{tar --delete} command only works with archives stored on disk. -You cannot delete members from an archive stored on a tape. - -@section Directories - -When the names of files or members specify directories, the operation of -@code{tar} is more complex. Generally, when a directory is named, -@code{tar} also operates on all the contents of the directory, -recursively. Thus, to @code{tar}, the file name @file{/} names the -entire file system. - -To archive the entire contents of a directory, use @samp{tar --create} -(or @samp{tar --append}) as usual, and specify the name of the -directory. For example, to archive all the contents of the current -directory, use @samp{tar --create --file=@var{archive-name} .}. Doing -this will give the archive members names starting with @samp{./}. To -archive the contents of a directory named @file{foodir}, use @samp{tar ---create --file=@var{archive-name} foodir}. In this case, the member -names will all start with @samp{foodir/}. - -If you give @code{tar} a command such as @samp{tar --create ---file=foo.tar .}, it will report @samp{tar: foo.tar is the archive; not -dumped}. This happens because the archive @file{foo.tar} is created -before putting any files into it. Then, when @code{tar} attempts to add -all the files in the directory @file{.} to the archive, it notices that -the file @file{foo.tar} is the same as the archive, and skips it. (It -makes no sense to put an archive into itself.) GNU @code{tar} will -continue in this case, and create the archive as normal, except for the -exclusion of that one file. Other versions of @code{tar}, however, are -not so clever, and will enter an infinite loop when this happens, so you -should not depend on this behavior. In general, make sure that the -archive is not inside a directory being dumped. - -When extracting files, you can also name directory archive members on -the command line. In this case, @code{tar} extracts all the archive -members whose names begin with the name of the directory. As usual, -@code{tar} is not particularly clever about interpreting member names. -The command @samp{tar --extract --file=@var{archive-name} .} will not -extract all the contents of the archive, but only those members whose -member names begin with @samp{./}. - -@section Shorthand names - -Most of the options to @code{tar} come in both long forms and short -forms. The options described in this tutorial have the following -abbreviations (except @samp{--delete}, which has no shorthand form): +Setting Parameters for Backups and Restoration -@table @samp -@item --create -@samp{-c} -@item --list -@samp{-t} -@item --extract -@samp{-x} -@item --append -@samp{-r} -@item --verbose -@samp{-v} -@item --file=@var{archive-name} -@samp{-f @var{archive-name}} -@end table +* General-Purpose Variables:: +* Magnetic Tape Control:: +* User Hooks:: +* backup-specs example:: An Example Text of @file{Backup-specs} -These options make typing long @code{tar} commands easier. For example, -instead of typing -@example -tar --create --file=/tmp/afiles.tar --verbose apple angst asparagus -@end example -you can type -@example -tar -c -f /tmp/afiles.tar -v apple angst asparagus -@end example +Choosing Files and Names for @command{tar} -For more information on option syntax, @ref{Invoking @code{tar}}. In -the remainder of this manual, short forms and long forms are given -together when an option is discussed. +* file:: Choosing the Archive's Name +* Selecting Archive Members:: +* files:: Reading Names from a File +* exclude:: Excluding Some Files +* wildcards:: Wildcards Patterns and Matching +* quoting styles:: Ways of Quoting Special Characters in Names +* transform:: Modifying File and Member Names +* after:: Operating Only on New Files +* recurse:: Descending into Directories +* one:: Crossing File System Boundaries -@chapter Invoking @code{tar} +Reading Names from a File -The usual way to invoke tar is +* nul:: -@example -@code{tar} @var{options}... [@var{file-or-member-names}...] -@end example +Excluding Some Files -All the options start with @samp{-}. You can actually type in arguments -in any order, but in this manual the options always precede the other -arguments, to make examples easier to understand. +* problems with exclude:: -@menu -* Option Form:: The Forms of Arguments -* Argument Functions:: The Functions of Arguments -* Old Syntax for Commands:: An Old, but Still Supported, Syntax - for @code{tar} Commands -@end menu +Wildcards Patterns and Matching -@section The Forms of Arguments - -Most options of @code{tar} have a single letter form (a single letter -preceded by @samp{-}), and at least one mnemonic form (a word or -abbreviation preceded by @samp{--}). The forms are absolutely -identical in function. For example, you can use either @samp{tar -t} -or @samp{tar --list} to list the contents of an archive. In addition, -mnemonic names can be given unique abbreviations. For example, -@samp{--cre} can be used in place of @samp{--create} because there is -no other option which begins with @samp{cre}. - -Some options require an additional argument. Single letter options -which require arguments use the immediately following argument. -Mnemonic options are separated from their arguments by an @samp{=} -sign. For example, to create an an archive file named -@file{george.tar}, use either @samp{tar --create --file=george.tar} or -@samp{tar --create -f george.tar}. 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 @file{george.tar}. - -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. In fact, @samp{-C} requires a further argument (the name -of the directory which to change to). In this case, tar would think -it needs to change to a directory named @samp{--file=george}, and -wouldn't interpret @samp{--file-george} as an option at all! - -@section The Functions of Arguments - -You must give exactly one option from the following list to tar. This -option specifies the basic operation for @code{tar} to perform. - -@table samp -@item --help -Print a summary of the options to @code{tar} and do nothing else +* controlling pattern-matching:: -@item --create -@item -c -Create a new archive +Crossing File System Boundaries -@item --catenate -@item --concatenate -@item -A -Add the contents of one or more archives to another archive +* directory:: Changing Directory +* absolute:: Absolute File Names -@item --append -@item -a -Add files to an existing archive +Date input formats -@item --list -@item -t -List the members in an archive +* General date syntax:: Common rules. +* Calendar date items:: 19 Dec 1994. +* Time of day items:: 9:20pm. +* Time zone items:: @sc{est}, @sc{pdt}, @sc{gmt}. +* Day of week items:: Monday and others. +* Relative items in date strings:: next tuesday, 2 years ago. +* Pure numbers in date strings:: 19931219, 1440. +* Seconds since the Epoch:: @@1078100502. +* Specifying time zone rules:: TZ="America/New_York", TZ="UTC0". +* Authors of parse_datetime:: Bellovin, Eggert, Salz, Berets, et al. -@item --delete -Delete members from an archive +Controlling the Archive Format -@item --extract -@item --get -@item -x -Extract members from an archive +* Compression:: Using Less Space through Compression +* Attributes:: Handling File Attributes +* Portability:: Making @command{tar} Archives More Portable +* cpio:: Comparison of @command{tar} and @command{cpio} -@item --compare -@item --diff -@item -d -Compare members in an archive with files in the file system +Using Less Space through Compression -@item --update -@item -u -Update an archive by appending newer versions of already stored files -@end itemize +* gzip:: Creating and Reading Compressed Archives +* sparse:: Archiving Sparse Files -The remaining options 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. - -The remaining arguments are interpreted either as file names or as -member names, depending on the basic operation @code{tar} is -performing. For @samp{--append} and @samp{--create} these arguments -specify the names of files (which must already exist) to place in the -archive. For the remaining operation types, the additional arguments -specify archive members to compare, delete, extract, list, or update. -When naming archive members, you must give the exact name of the member -in the archive, as it is printed by @code{tar --list}. When naming -files, the normal file name rules apply. - -If you don't use any additional arguments, @samp{--append}, -@samp{--catenate}, and @samp{--delete} will do nothing. Naturally, -@samp{--create} will make an empty archive if given no files to add. -The other operations of @code{tar} (@samp{--list}, @samp{--extract}, -@samp{--compare}, and @samp{--update}) will act on the entire contents -of the archive. +Creating and Reading Compressed Archives -If you give the name of a directory as either a file name or a member -name, then @code{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 @code{tar}. +* lbzip2:: Using lbzip2 with @GNUTAR{}. -@section An Old, but Still Supported, Syntax for @code{tar} Commands +Making @command{tar} Archives More Portable -For historical reasons, GNU @code{tar} also accepts a syntax for -commands which splits options that require additional arguments into -two parts. That syntax is of the form: +* Portable Names:: Portable Names +* dereference:: Symbolic Links +* hard links:: Hard Links +* old:: Old V7 Archives +* ustar:: Ustar Archives +* gnu:: GNU and old GNU format archives. +* posix:: @acronym{POSIX} archives +* Checksumming:: Checksumming Problems +* Large or Negative Values:: Large files, negative time stamps, etc. +* Other Tars:: How to Extract GNU-Specific Data Using + Other @command{tar} Implementations -@example -@code{tar} @var{option-letters}... [@var{option-arguments}...] [@var{file-names}...]@refill -@end example +@GNUTAR{} and @acronym{POSIX} @command{tar} -@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. +* PAX keywords:: Controlling Extended Header Keywords. -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}. +How to Extract GNU-Specific Data Using Other @command{tar} Implementations -On the other hand, this old style syntax makes it difficult to match -option letters with their corresponding arguments, and is often -confusing. In the command @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. - -@chapter Specifying Names to @code{tar} - -When specifying the names of files or members to @code{tar}, it by -default takes the names of the files from the command line. There are -other ways, however, to specify file or member names, or to modify the -manner in which @code{tar} selects the files or members upon which to -operate. In general, these methods work both for specifying the names -of files and archive members. +* Split Recovery:: Members Split Between Volumes +* Sparse Recovery:: Sparse Members -@section Reading Names from a File +Tapes and Other Archive Media -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 -@samp{--files-from=@var{file-name-list}} (@samp{-T -@var{file-name-list}}) option to @code{tar}. Give the name of the file -which contains the list as the argument to @samp{--files-from}. The -file names should be separated by newlines in the list. +* 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:: -If you want to specify names that might contain newlines, use the -@samp{--null} option. Then, the filenames should be separated by NUL -characters (ASCII 000) instead of newlines. In addition, the -@samp{--null} option turns off the @samp{-C} option (@pxref{Changing -Directory}). +Blocking -@section Excluding Some Files +* Format Variations:: Format Variations +* Blocking Factor:: The Blocking Factor of an Archive -The @samp{--exclude=@var{pattern}} option will prevent any file or -member which matches the regular expression @var{pattern} from being -operated on. For example, if you want to create an archive with all the -contents of @file{/tmp} except the file @file{/tmp/foo}, you can use the -command @samp{tar --create --file=arch.tar --exclude=foo}. +Many Archives on One Tape -If there are many files you want to exclude, you can use the -@samp{--exclude-from=@var{exclude-list}} (@samp{-X @var{exclude-list}}) -option. This works just like the -@samp{--files-from=@var{file-name-list}} option: specify the name of a -file as @var{exclude-list} which contains the list of patterns you want -to exclude. +* Tape Positioning:: Tape Positions and Tape Marks +* mt:: The @command{mt} Utility -@xref{Regular Expressions} for more information on the syntax and -meaning of regular expressions. +Using Multiple Tapes -@section Operating Only on New Files +* Multi-Volume Archives:: Archives Longer than One Tape or Disk +* Tape Files:: Tape Files +* Tarcat:: Concatenate Volumes into a Single Archive -The @samp{--newer=@var{date}} (@samp{--after-date=@var{date}} or -@samp{-N @var{date}}) limits @code{tar} to only operating on files which -have been modified after the date specified. (For more information on -how to specify a date, @xref{Date Formats}.) A file is considered to -have changed if the contents have been modified, or if the owner, -permissions, and so forth, have been changed. -If you only want @code{tar} make the date comparison on the basis of the -actual contents of the file's modification, then use the -@samp{--newer-mtime=@var{date}} option. +Tar Internals -You should not depend on this option for making incremental dumps. To -learn how to use @code{tar} to make backups, @ref{Making Backups}. +* Standard:: Basic Tar Format +* Extensions:: @acronym{GNU} Extensions to the Archive Format +* Sparse Formats:: Storing Sparse Files +* Snapshot Files:: +* Dumpdir:: -XXXX MIB XXXX +Storing Sparse Files +* Old GNU Format:: +* PAX 0:: PAX Format, Versions 0.0 and 0.1 +* PAX 1:: PAX Format, Version 1.0 +Genfile -@node Wizardry, Archive Structure, Tutorial, Top -@chapter Wizardry +* Generate Mode:: File Generation Mode. +* Status Mode:: File Status Mode. +* Exec Mode:: Synchronous Execution mode. -<<>>>> +@node assumptions +@section Assumptions this Tutorial Makes + +This chapter is paced to allow beginners to learn about @command{tar} +slowly. At the same time, we will try to cover all the basic aspects of +these three operations. In order to accomplish both of these tasks, we +have made certain assumptions about your knowledge before reading this +manual, and the hardware you will be using: + +@itemize @bullet +@item +Before you start to work through this tutorial, you should understand +what the terms ``archive'' and ``archive member'' mean +(@pxref{Definitions}). In addition, you should understand something +about how Unix-type operating systems work, and you should know how to +use some basic utilities. For example, you should know how to create, +list, copy, rename, edit, and delete files and directories; how to +change between directories; and how to figure out where you are in the +file system. You should have some basic understanding of directory +structure and how files are named according to which directory they are +in. You should understand concepts such as standard output and standard +input, what various definitions of the term @samp{argument} mean, and the +differences between relative and absolute file names. +@FIXME{and what else?} + +@item +This manual assumes that you are working from your own home directory +(unless we state otherwise). In this tutorial, you will create a +directory to practice @command{tar} commands in. When we show file names, +we will assume that those names are relative to your home directory. +For example, my home directory is @file{/home/fsf/melissa}. All of +my examples are in a subdirectory of the directory named by that file +name; the subdirectory is called @file{practice}. + +@item +In general, we show examples of archives which exist on (or can be +written to, or worked with from) a directory on a hard disk. In most +cases, you could write those archives to, or work with them on any other +device, such as a tape drive. However, some of the later examples in +the tutorial and next chapter will not work on tape drives. +Additionally, working with tapes is much more complicated than working +with hard disks. For these reasons, the tutorial does not cover working +with tape drives. @xref{Media}, for complete information on using +@command{tar} archives with tape drives. + +@FIXME{this is a cop out. need to add some simple tape drive info.} +@end itemize -@node Archive Structure, Reading and Writing, Wizardry, Top -@chapter The Structure of an Archive +@node stylistic conventions +@section Stylistic Conventions + +In the examples, @samp{$} represents a typical shell prompt. It +precedes lines you should type; to make this more clear, those lines are +shown in @kbd{this font}, as opposed to lines which represent the +computer's response; those lines are shown in @code{this font}, or +sometimes @samp{like this}. + +@c When we have lines which are too long to be +@c displayed in any other way, we will show them like this: + +@node basic tar options +@section Basic @command{tar} Operations and Options + +@command{tar} can take a wide variety of arguments which specify and define +the actions it will have on the particular set of files or the archive. +The main types of arguments to @command{tar} fall into one of two classes: +operations, and options. + +Some arguments fall into a class called @dfn{operations}; exactly one of +these is both allowed and required for any instance of using @command{tar}; +you may @emph{not} specify more than one. People sometimes speak of +@dfn{operating modes}. You are in a particular operating mode when you +have specified the operation which specifies it; there are eight +operations in total, and thus there are eight operating modes. + +The other arguments fall into the class known as @dfn{options}. You are +not required to specify any options, and you are allowed to specify more +than one at a time (depending on the way you are using @command{tar} at +that time). Some options are used so frequently, and are so useful for +helping you type commands more carefully that they are effectively +``required''. We will discuss them in this chapter. + +You can write most of the @command{tar} operations and options in any +of three forms: long (mnemonic) form, short form, and old style. Some +of the operations and options have no short or ``old'' forms; however, +the operations and options which we will cover in this tutorial have +corresponding abbreviations. We will indicate those abbreviations +appropriately to get you used to seeing them. Note, that the ``old +style'' option forms exist in @GNUTAR{} for compatibility with Unix +@command{tar}. In this book we present a full discussion of this way +of writing options and operations (@pxref{Old Options}), and we discuss +the other two styles of writing options (@xref{Long Options}, and +@pxref{Short Options}). + +In the examples and in the text of this tutorial, we usually use the +long forms of operations and options; but the ``short'' forms produce +the same result and can make typing long @command{tar} commands easier. +For example, instead of typing + +@smallexample +@kbd{tar --create --verbose --file=afiles.tar apple angst aspic} +@end smallexample -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. +@noindent +you can type +@smallexample +@kbd{tar -c -v -f afiles.tar apple angst aspic} +@end smallexample +@noindent +or even +@smallexample +@kbd{tar -cvf afiles.tar apple angst aspic} +@end smallexample -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. +@noindent +For more information on option syntax, see @ref{Advanced tar}. In +discussions in the text, when we name an option by its long form, we +also give the corresponding short option in parentheses. + +The term, ``option'', can be confusing at times, since ``operations'' +are often lumped in with the actual, @emph{optional} ``options'' in certain +general class statements. For example, we just talked about ``short and +long forms of options and operations''. However, experienced @command{tar} +users often refer to these by shorthand terms such as, ``short and long +options''. This term assumes that the ``operations'' are included, also. +Context will help you determine which definition of ``options'' to use. + +Similarly, the term ``command'' can be confusing, as it is often used in +two different ways. People sometimes refer to @command{tar} ``commands''. +A @command{tar} @dfn{command} is the entire command line of user input +which tells @command{tar} what to do --- including the operation, options, +and any arguments (file names, pipes, other commands, etc.). However, +you will also sometimes hear the term ``the @command{tar} command''. When +the word ``command'' is used specifically like this, a person is usually +referring to the @command{tar} @emph{operation}, not the whole line. +Again, use context to figure out which of the meanings the speaker +intends. + +@node frequent operations +@section The Three Most Frequently Used Operations + +Here are the three most frequently used operations (both short and long +forms), as well as a brief description of their meanings. The rest of +this chapter will cover how to use these operations in detail. We will +present the rest of the operations in the next chapter. + +@table @option +@item --create +@itemx -c +Create a new @command{tar} archive. +@item --list +@itemx -t +List the contents of an archive. +@item --extract +@itemx -x +Extract one or more members from an archive. +@end table -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}. +@node Two Frequent Options +@section Two Frequently Used Options -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. +To understand how to run @command{tar} in the three operating modes listed +previously, you also need to understand how to use two of the options to +@command{tar}: @option{--file} (which takes an archive file as an argument) +and @option{--verbose}. (You are usually not @emph{required} to specify +either of these options when you run @command{tar}, but they can be very +useful in making things more clear and helping you avoid errors.) @menu -* Old Style File Information:: Old Style File Information -* Archive Label:: -* Format Variations:: +* file tutorial:: +* verbose tutorial:: +* help tutorial:: @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 - -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. +@node file tutorial +@unnumberedsubsec The @option{--file} Option -@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. +@table @option +@xopindex{file, tutorial} +@item --file=@var{archive-name} +@itemx -f @var{archive-name} +Specify the name of an archive file. @end table -@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 +You can specify an argument for the @option{--file=@var{archive-name}} (@option{-f @var{archive-name}}) option whenever you +use @command{tar}; this option determines the name of the archive file +that @command{tar} will work on. + +@vrindex TAPE +If you don't specify this argument, then @command{tar} will examine +the environment variable @env{TAPE}. If it is set, its value will be +used as the archive name. Otherwise, @command{tar} will use the +default archive, determined at compile time. Usually it is +standard output or some physical tape drive attached to your machine +(you can verify what the default is by running @kbd{tar +--show-defaults}, @pxref{defaults}). If there is no tape drive +attached, or the default is not meaningful, then @command{tar} will +print an error message. The error message might look roughly like one +of the following: + +@smallexample +tar: can't open /dev/rmt8 : No such device or address +tar: can't open /dev/rsmt0 : I/O error +@end smallexample -@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. - -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. - -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 - -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: +@noindent +To avoid confusion, we recommend that you always specify an archive file +name by using @option{--file=@var{archive-name}} (@option{-f @var{archive-name}}) when writing your @command{tar} commands. +For more information on using the @option{--file=@var{archive-name}} (@option{-f @var{archive-name}}) option, see +@ref{file}. -@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 +@node verbose tutorial +@unnumberedsubsec The @option{--verbose} Option -@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. +@table @option +@xopindex{verbose, introduced} +@item --verbose +@itemx -v +Show the files being worked on as @command{tar} is running. @end table -@c was --volume -@node Format Variations, , Archive Label, Archive Structure -@section Format Variations -@cindex Format Parameters -@cindex Format Options -@cindex Options to specify archive format. +@option{--verbose} (@option{-v}) shows details about the results of running +@command{tar}. This can be especially useful when the results might not be +obvious. For example, if you want to see the progress of @command{tar} as +it writes files into the archive, you can use the @option{--verbose} +option. In the beginning, you may find it useful to use +@option{--verbose} at all times; when you are more accustomed to +@command{tar}, you will likely want to use it at certain times but not at +others. We will use @option{--verbose} at times to help make something +clear, and we will give many examples both using and not using +@option{--verbose} to show the differences. + +Each instance of @option{--verbose} on the command line increases the +verbosity level by one, so if you need more details on the output, +specify it twice. + +When reading archives (@option{--list}, @option{--extract}, +@option{--diff}), @command{tar} by default prints only the names of +the members being extracted. Using @option{--verbose} will show a full, +@command{ls} style member listing. + +In contrast, when writing archives (@option{--create}, @option{--append}, +@option{--update}), @command{tar} does not print file names by +default. So, a single @option{--verbose} option shows the file names +being added to the archive, while two @option{--verbose} options +enable the full listing. + +For example, to create an archive in verbose mode: + +@smallexample +$ @kbd{tar -cvf afiles.tar apple angst aspic} +apple +angst +aspic +@end smallexample -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. +@noindent +Creating the same archive with the verbosity level 2 could give: -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. +@smallexample +$ @kbd{tar -cvvf afiles.tar apple angst aspic} +-rw-r--r-- gray/staff 62373 2006-06-09 12:06 apple +-rw-r--r-- gray/staff 11481 2006-06-09 12:06 angst +-rw-r--r-- gray/staff 23152 2006-06-09 12:06 aspic +@end smallexample +@noindent +This works equally well using short or long forms of options. Using +long forms, you would simply write out the mnemonic form of the option +twice, like this: -@menu -* Multi-Volume Archives:: -* Sparse Files:: -* Blocking Factor:: -* Compressed Archives:: -@end menu +@smallexample +$ @kbd{tar --create --verbose --verbose @dots{}} +@end smallexample -@node Multi-Volume Archives, Sparse Files, Format Variations, Format Variations -@subsection Archives Longer than One Tape or Disk -@cindex Multi-volume archives +@noindent +Note that you must double the hyphens properly each time. -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. +Later in the tutorial, we will give examples using @w{@option{--verbose +--verbose}}. -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. +@anchor{verbose member listing} +The full output consists of six fields: -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}. +@itemize @bullet +@item File type and permissions in symbolic form. +These are displayed in the same format as the first column of +@command{ls -l} output (@pxref{What information is listed, +format=verbose, Verbose listing, fileutils, GNU file utilities}). -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. +@item Owner name and group separated by a slash character. +If these data are not available (for example, when listing a @samp{v7} format +archive), numeric @acronym{ID} values are printed instead. -@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 Size of the file, in bytes. +@item File modification date in ISO 8601 format. -<<< There should be a sample program here, including an exit before -<<< end. +@item File modification time. -@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. +@item File name. +If the name contains any special characters (white space, newlines, +etc.) these are displayed in an unambiguous form using so called +@dfn{quoting style}. For the detailed discussion of available styles +and on how to use them, see @ref{quoting styles}. -@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}. +Depending on the file type, the name can be followed by some +additional information, described in the following table: + +@table @samp +@item -> @var{link-name} +The file or archive member is a @dfn{symbolic link} and +@var{link-name} is the name of file it links to. + +@item link to @var{link-name} +The file or archive member is a @dfn{hard link} and @var{link-name} is +the name of file it links to. + +@item --Long Link-- +The archive member is an old GNU format long link. You will normally +not encounter this. + +@item --Long Name-- +The archive member is an old GNU format long name. You will normally +not encounter this. + +@item --Volume Header-- +The archive member is a GNU @dfn{volume header} (@pxref{Tape Files}). + +@item --Continued at byte @var{n}-- +Encountered only at the beginning of a multi-volume archive +(@pxref{Using Multiple Tapes}). This archive member is a continuation +from the previous volume. The number @var{n} gives the offset where +the original file was split. + +@item unknown file type @var{c} +An archive member of unknown type. @var{c} is the type character from +the archive header. If you encounter such a message, it means that +either your archive contains proprietary member types @GNUTAR{} is not +able to handle, or the archive is corrupted. @end table -@node Sparse Files, Blocking Factor, Multi-Volume Archives, Format Variations -@subsection Archiving Sparse Files -@cindex Sparse Files +@end itemize -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. +For example, here is an archive listing containing most of the special +suffixes explained above: -@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. +@smallexample +@group +V--------- 0/0 1536 2006-06-09 13:07 MyVolume--Volume Header-- +-rw-r--r-- gray/staff 456783 2006-06-09 12:06 aspic--Continued at byte 32456-- +-rw-r--r-- gray/staff 62373 2006-06-09 12:06 apple +lrwxrwxrwx gray/staff 0 2006-06-09 13:01 angst -> apple +-rw-r--r-- gray/staff 35793 2006-06-09 12:06 blues +hrw-r--r-- gray/staff 0 2006-06-09 12:06 music link to blues +@end group +@end smallexample -@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 +@smallexample +@end smallexample -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 +@node help tutorial +@unnumberedsubsec Getting Help: Using the @option{--help} Option -@code{tar} ignores the @samp{--sparse} option when reading an archive. +@table @option +@opindex help +@item --help -@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 +The @option{--help} option to @command{tar} prints out a very brief list of +all operations and option available for the current version of +@command{tar} available on your system. +@end table -@node 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. +@node create +@section How to Create Archives +@UNREVISED + +@cindex Creation of the archive +@cindex Archive, creation of +One of the basic operations of @command{tar} is @option{--create} (@option{-c}), which +you use to create a @command{tar} archive. We will explain +@option{--create} first because, in order to learn about the other +operations, you will find it useful to have an archive available to +practice on. + +To make this easier, in this section you will first create a directory +containing three files. Then, we will show you how to create an +@emph{archive} (inside the new directory). Both the directory, and +the archive are specifically for you to practice on. The rest of this +chapter and the next chapter will show many examples using this +directory and the files you will create: some of those files may be +other directories and other archives. + +The three files you will archive in this example are called +@file{blues}, @file{folk}, and @file{jazz}. The archive is called +@file{collection.tar}. + +This section will proceed slowly, detailing how to use @option{--create} +in @code{verbose} mode, and showing examples using both short and long +forms. In the rest of the tutorial, and in the examples in the next +chapter, we will proceed at a slightly quicker pace. This section +moves more slowly to allow beginning users to understand how +@command{tar} works. -@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 +@menu +* prepare for examples:: +* Creating the archive:: +* create verbose:: +* short create:: +* create dir:: +@end menu -@node Compressed Archives, , Blocking Factor, Format Variations -@subsection Creating and Reading Compressed Archives -@cindex Compressed archives -@cindex Storing archives in compressed format +@node prepare for examples +@subsection Preparing a Practice Directory for Examples + +To follow along with this and future examples, create a new directory +called @file{practice} containing files called @file{blues}, @file{folk} +and @file{jazz}. The files can contain any information you like: +ideally, they should contain information which relates to their names, +and be of different lengths. Our examples assume that @file{practice} +is a subdirectory of your home directory. + +Now @command{cd} to the directory named @file{practice}; @file{practice} +is now your @dfn{working directory}. (@emph{Please note}: Although +the full file name of this directory is +@file{/@var{homedir}/practice}, in our examples we will refer to +this directory as @file{practice}; the @var{homedir} is presumed.) + +In general, you should check that the files to be archived exist where +you think they do (in the working directory) by running @command{ls}. +Because you just created the directory and the files and have changed to +that directory, you probably don't need to do that this time. + +It is very important to make sure there isn't already a file in the +working directory with the archive name you intend to use (in this case, +@samp{collection.tar}), or that you don't care about its contents. +Whenever you use @samp{create}, @command{tar} will erase the current +contents of the file named by @option{--file=@var{archive-name}} (@option{-f @var{archive-name}}) if it exists. @command{tar} +will not tell you if you are about to overwrite an archive unless you +specify an option which does this (@pxref{backup}, for the +information on how to do so). To add files to an existing archive, +you need to use a different option, such as @option{--append} (@option{-r}); see +@ref{append} for information on how to do this. + +@node Creating the archive +@subsection Creating the Archive + +@xopindex{create, introduced} +To place the files @file{blues}, @file{folk}, and @file{jazz} into an +archive named @file{collection.tar}, use the following command: + +@smallexample +$ @kbd{tar --create --file=collection.tar blues folk jazz} +@end smallexample + +The order of the arguments is not very important, @emph{when using long +option forms}. You could also say: + +@smallexample +$ @kbd{tar blues --create folk --file=collection.tar jazz} +@end smallexample -@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. - -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. - -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. - -If there is no compress utility available, @code{tar} will report an -error. +@noindent +However, you can see that this order is harder to understand; this is +why we will list the arguments in the order that makes the commands +easiest to understand (and we encourage you to do the same when you use +@command{tar}, to avoid errors). + +Note that the sequence +@option{--file=@-collection.tar} is considered to be @emph{one} argument. +If you substituted any other string of characters for +@kbd{collection.tar}, then that string would become the name of the +archive file you create. + +The order of the options becomes more important when you begin to use +short forms. With short forms, if you type commands in the wrong order +(even if you type them correctly in all other ways), you may end up with +results you don't expect. For this reason, it is a good idea to get +into the habit of typing options in the order that makes inherent sense. +@xref{short create}, for more information on this. + +In this example, you type the command as shown above: @option{--create} +is the operation which creates the new archive +(@file{collection.tar}), and @option{--file} is the option which lets +you give it the name you chose. The files, @file{blues}, @file{folk}, +and @file{jazz}, are now members of the archive, @file{collection.tar} +(they are @dfn{file name arguments} to the @option{--create} operation. +@xref{Choosing}, for the detailed discussion on these.) Now that they are +in the archive, they are called @emph{archive members}, not files. +(@pxref{Definitions,members}). + +When you create an archive, you @emph{must} specify which files you +want placed in the archive. If you do not specify any archive +members, @GNUTAR{} will complain. + +If you now list the contents of the working directory (@command{ls}), you will +find the archive file listed as well as the files you saw previously: + +@smallexample +blues folk jazz collection.tar +@end smallexample -@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. +@noindent +Creating the archive @samp{collection.tar} did not destroy the copies of +the files in the directory. + +Keep in mind that if you don't indicate an operation, @command{tar} will not +run and will prompt you for one. If you don't name any files, @command{tar} +will complain. You must have write access to the working directory, +or else you will not be able to create an archive in that directory. + +@emph{Caution}: Do not attempt to use @option{--create} (@option{-c}) to add files to +an existing archive; it will delete the archive and write a new one. +Use @option{--append} (@option{-r}) instead. @xref{append}. + +@node create verbose +@subsection Running @option{--create} with @option{--verbose} + +@xopindex{create, using with @option{--verbose}} +@xopindex{verbose, using with @option{--create}} +If you include the @option{--verbose} (@option{-v}) option on the command line, +@command{tar} will list the files it is acting on as it is working. In +verbose mode, the @code{create} example above would appear as: + +@smallexample +$ @kbd{tar --create --verbose --file=collection.tar blues folk jazz} +blues +folk +jazz +@end smallexample + +This example is just like the example we showed which did not use +@option{--verbose}, except that @command{tar} generated the remaining +@iftex +lines (note the different font styles). +@end iftex +@ifinfo +lines. +@end ifinfo -@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 +In the rest of the examples in this chapter, we will frequently use +@code{verbose} mode so we can show actions or @command{tar} responses that +you would otherwise not see, and which are important for you to +understand. + +@node short create +@subsection Short Forms with @samp{create} + +As we said before, the @option{--create} (@option{-c}) operation is one of the most +basic uses of @command{tar}, and you will use it countless times. +Eventually, you will probably want to use abbreviated (or ``short'') +forms of options. A full discussion of the three different forms that +options can take appears in @ref{Styles}; for now, here is what the +previous example (including the @option{--verbose} (@option{-v}) option) looks like +using short option forms: + +@smallexample +$ @kbd{tar -cvf collection.tar blues folk jazz} +blues +folk +jazz +@end smallexample -@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. +@noindent +As you can see, the system responds the same no matter whether you use +long or short option forms. -@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 +@FIXME{i don't like how this is worded:} One difference between using +short and long option forms is that, although the exact placement of +arguments following options is no more specific when using short forms, +it is easier to become confused and make a mistake when using short +forms. For example, suppose you attempted the above example in the +following way: -@c >>> MIB -- why not use -Z instead of -z -z ? -ringo +@smallexample +$ @kbd{tar -cfv collection.tar blues folk jazz} +@end smallexample -@node Reading and Writing, Insuring Accuracy, Archive Structure, Top -@chapter Reading and Writing Archives +@noindent +In this case, @command{tar} will make an archive file called @file{v}, +containing the files @file{blues}, @file{folk}, and @file{jazz}, because +the @samp{v} is the closest ``file name'' to the @option{-f} option, and +is thus taken to be the chosen archive file name. @command{tar} will try +to add a file called @file{collection.tar} to the @file{v} archive file; +if the file @file{collection.tar} did not already exist, @command{tar} will +report an error indicating that this file does not exist. If the file +@file{collection.tar} does already exist (e.g., from a previous command +you may have run), then @command{tar} will add this file to the archive. +Because the @option{-v} option did not get registered, @command{tar} will not +run under @samp{verbose} mode, and will not report its progress. + +The end result is that you may be quite confused about what happened, +and possibly overwrite a file. To illustrate this further, we will show +you how an example we showed previously would look using short forms. + +This example, + +@smallexample +$ @kbd{tar blues --create folk --file=collection.tar jazz} +@end smallexample -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. +@noindent +is confusing as it is. When shown using short forms, however, it +becomes much more so: -@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 +@smallexample +$ @kbd{tar blues -c folk -f collection.tar jazz} +@end smallexample -@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? +@noindent +It would be very easy to put the wrong string of characters +immediately following the @option{-f}, but doing that could sacrifice +valuable data. + +For this reason, we recommend that you pay very careful attention to +the order of options and placement of file and archive names, +especially when using short option forms. Not having the option name +written out mnemonically can affect how well you remember which option +does what, and therefore where different names have to be placed. + +@node create dir +@subsection Archiving Directories + +@cindex Archiving Directories +@cindex Directories, Archiving +You can archive a directory by specifying its directory name as a +file name argument to @command{tar}. The files in the directory will be +archived relative to the working directory, and the directory will be +re-created along with its contents when the archive is extracted. + +To archive a directory, first move to its superior directory. If you +have followed the previous instructions in this tutorial, you should +type: + +@smallexample +$ @kbd{cd ..} +$ +@end smallexample -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. +@noindent +This will put you into the directory which contains @file{practice}, +i.e., your home directory. Once in the superior directory, you can +specify the subdirectory, @file{practice}, as a file name argument. To +store @file{practice} in the new archive file @file{music.tar}, type: -@c >>> MIB--does standard input and output redirection work with all -@c >>> operations? -@c >>> need example for standard input and output (screen and keyboard?) +@smallexample +$ @kbd{tar --create --verbose --file=music.tar practice} +@end smallexample -@cindex Standard input and output -@cindex tar to standard input and output +@noindent +@command{tar} should output: + +@smallexample +practice/ +practice/blues +practice/folk +practice/jazz +practice/collection.tar +@end smallexample + +Note that the archive thus created is not in the subdirectory +@file{practice}, but rather in the current working directory---the +directory from which @command{tar} was invoked. Before trying to archive a +directory from its superior directory, you should make sure you have +write access to the superior directory itself, not only the directory +you are trying archive with @command{tar}. For example, you will probably +not be able to store your home directory in an archive by invoking +@command{tar} from the root directory; @xref{absolute}. (Note +also that @file{collection.tar}, the original archive file, has itself +been archived. @command{tar} will accept any file as a file to be +archived, regardless of its content. When @file{music.tar} is +extracted, the archive file @file{collection.tar} will be re-written +into the file system). + +If you give @command{tar} a command such as + +@smallexample +$ @kbd{tar --create --file=foo.tar .} +@end smallexample -To specify an archive file on a device attached to a remote machine, -use the following: +@noindent +@command{tar} will report @samp{tar: ./foo.tar is the archive; not +dumped}. This happens because @command{tar} creates the archive +@file{foo.tar} in the current directory before putting any files into +it. Then, when @command{tar} attempts to add all the files in the +directory @file{.} to the archive, it notices that the file +@file{./foo.tar} is the same as the archive @file{foo.tar}, and skips +it. (It makes no sense to put an archive into itself.) @GNUTAR{} +will continue in this case, and create the archive +normally, except for the exclusion of that one file. (@emph{Please +note:} Other implementations of @command{tar} may not be so clever; +they will enter an infinite loop when this happens, so you should not +depend on this behavior unless you are certain you are running +@GNUTAR{}. In general, it is wise to always place the archive outside +of the directory being dumped.) + +@node list +@section How to List Archives + +@opindex list +Frequently, you will find yourself wanting to determine exactly what a +particular archive contains. You can use the @option{--list} +(@option{-t}) operation to get the member names as they currently +appear in the archive, as well as various attributes of the files at +the time they were archived. For example, you can examine the archive +@file{collection.tar} that you created in the last section with the +command, + +@smallexample +$ @kbd{tar --list --file=collection.tar} +@end smallexample -@example ---file=@var{hostname}:/@var{dev}/@var{file name} -@end example +@noindent +The output of @command{tar} would then be: + +@smallexample +blues +folk +jazz +@end smallexample @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. +The archive @file{bfiles.tar} would list as follows: -@c >>>MIB --- is this clear? +@smallexample +./birds +baboon +./box +@end smallexample -@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. +@noindent +Be sure to use a @option{--file=@var{archive-name}} (@option{-f +@var{archive-name}}) option just as with @option{--create} +(@option{-c}) to specify the name of the archive. + +@xopindex{list, using with @option{--verbose}} +@xopindex{verbose, using with @option{--list}} +If you use the @option{--verbose} (@option{-v}) option with +@option{--list}, then @command{tar} will print out a listing +reminiscent of @w{@samp{ls -l}}, showing owner, file size, and so +forth. This output is described in detail in @ref{verbose member listing}. + +If you had used @option{--verbose} (@option{-v}) mode, the example +above would look like: + +@smallexample +$ @kbd{tar --list --verbose --file=collection.tar folk} +-rw-r--r-- myself/user 62 1990-05-23 10:55 folk +@end smallexample + +@cindex listing member and file names +@anchor{listing member and file names} +It is important to notice that the output of @kbd{tar --list +--verbose} does not necessarily match that produced by @kbd{tar +--create --verbose} while creating the archive. It is because +@GNUTAR{}, unless told explicitly not to do so, removes some directory +prefixes from file names before storing them in the archive +(@xref{absolute}, for more information). In other +words, in verbose mode @GNUTAR{} shows @dfn{file names} when creating +an archive and @dfn{member names} when listing it. Consider this +example: + +@smallexample +@group +$ @kbd{tar --create --verbose --file archive /etc/mail} +tar: Removing leading '/' from member names +/etc/mail/ +/etc/mail/sendmail.cf +/etc/mail/aliases +$ @kbd{tar --test --file archive} +etc/mail/ +etc/mail/sendmail.cf +etc/mail/aliases +@end group +@end smallexample + +@opindex show-stored-names + This default behavior can sometimes be inconvenient. You can force +@GNUTAR{} show member names when creating archive by supplying +@option{--show-stored-names} option. + +@table @option +@item --show-stored-names +Print member (as opposed to @emph{file}) names when creating the archive. @end table -@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 +@cindex File name arguments, using @option{--list} with +@xopindex{list, using with file name arguments} +You can specify one or more individual member names as arguments when +using @samp{list}. In this case, @command{tar} will only list the +names of members you identify. For example, @w{@kbd{tar --list +--file=afiles.tar apple}} would only print @file{apple}. + +Because @command{tar} preserves file names, these must be specified as +they appear in the archive (i.e., relative to the directory from which +the archive was created). Therefore, it is essential when specifying +member names to @command{tar} that you give the exact member names. +For example, @w{@kbd{tar --list --file=bfiles.tar birds}} would produce an +error message something like @samp{tar: birds: Not found in archive}, +because there is no member named @file{birds}, only one named +@file{./birds}. While the names @file{birds} and @file{./birds} name +the same file, @emph{member} names by default are compared verbatim. + +However, @w{@kbd{tar --list --file=bfiles.tar baboon}} would respond +with @file{baboon}, because this exact member name is in the archive file +@file{bfiles.tar}. If you are not sure of the exact file name, +use @dfn{globbing patterns}, for example: + +@smallexample +$ @kbd{tar --list --file=bfiles.tar --wildcards '*b*'} +@end smallexample -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. +@noindent +will list all members whose name contains @samp{b}. @xref{wildcards}, +for a detailed discussion of globbing patterns and related +@command{tar} command line options. -The following example creates an archive named @file{stooges}, -containing the files @file{larry}, @file{moe} and @file{curley}: +@menu +* list dir:: +@end menu -@example -tar --create --file=stooges larry moe curley -@end example +@node list dir +@unnumberedsubsec Listing the Contents of a Stored Directory -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}: +To get information about the contents of an archived directory, +use the directory name as a file name argument in conjunction with +@option{--list} (@option{-t}). To find out file attributes, include the +@option{--verbose} (@option{-v}) option. -@example -tar --create --file=hail/hail/fredonia marx -@end example +For example, to find out about files in the directory @file{practice}, in +the archive file @file{music.tar}, type: -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: +@smallexample +$ @kbd{tar --list --verbose --file=music.tar practice} +@end smallexample -@example -tar --create --file=home -@end example +@command{tar} responds: -@xref{File Name Lists}, for other ways to specify files to archive. +@smallexample +drwxrwxrwx myself/user 0 1990-05-31 21:49 practice/ +-rw-r--r-- myself/user 42 1990-05-21 13:29 practice/blues +-rw-r--r-- myself/user 62 1990-05-23 10:55 practice/folk +-rw-r--r-- myself/user 40 1990-05-21 13:30 practice/jazz +-rw-r--r-- myself/user 10240 1990-05-31 21:49 practice/collection.tar +@end smallexample -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. +When you use a directory name as a file name argument, @command{tar} acts on +all the files (including sub-directories) in that directory. -@node Modifying, Listing Contents, Creating in Detail, Reading and Writing -@section Modifying Archives -@cindex Modifying archives - -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. +@node extract +@section How to Extract Members from an Archive +@cindex Extraction +@cindex Retrieving files from an archive +@cindex Resurrecting files from an archive -To find out what files are already stored in an archive, use @samp{tar ---list --file=@var{archive-name}}. @xref{Listing Contents}. +@opindex extract +Creating an archive is only half the job---there is no point in storing +files in an archive if you can't retrieve them. The act of retrieving +members from an archive so they can be used and manipulated as +unarchived files again is called @dfn{extraction}. To extract files +from an archive, use the @option{--extract} (@option{--get} or +@option{-x}) operation. As with @option{--create}, specify the name +of the archive with @option{--file} (@option{-f}) option. Extracting +an archive does not modify the archive in any way; you can extract it +multiple times if you want or need to. + +Using @option{--extract}, you can extract an entire archive, or specific +files. The files can be directories containing other files, or not. As +with @option{--create} (@option{-c}) and @option{--list} (@option{-t}), you may use the short or the +long form of the operation without affecting the performance. @menu -* Adding Files:: -* Appending Archives:: -* Deleting Archive Files:: Deleting Files From an Archive -* Matching Format Parameters:: +* extracting archives:: +* extracting files:: +* extract dir:: +* extracting untrusted archives:: +* failing commands:: @end menu -@node Adding Files, Appending Archives, Modifying, Modifying -@subsection Adding Files to an Archive -@cindex Adding files to an archive -@cindex Updating an archive +@node extracting archives +@subsection Extracting an Entire Archive -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}. +To extract an entire archive, specify the archive file name only, with +no individual file names as arguments. For example, -The following example adds the file @file{shemp} to the archive -@file{stooges} created above: +@smallexample +$ @kbd{tar -xvf collection.tar} +@end smallexample -@example -tar --add-file --file=stooges shemp -@end example +@noindent +produces this: -You must specify the files to be added; there is no default. +@smallexample +-rw-r--r-- me/user 28 1996-10-18 16:31 jazz +-rw-r--r-- me/user 21 1996-09-23 16:44 blues +-rw-r--r-- me/user 20 1996-09-23 16:44 folk +@end smallexample -@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. +@node extracting files +@subsection Extracting Specific Files -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. +To extract specific archive members, give their exact member names as +arguments, as printed by @option{--list} (@option{-t}). If you had +mistakenly deleted one of the files you had placed in the archive +@file{collection.tar} earlier (say, @file{blues}), you can extract it +from the archive without changing the archive's structure. Its +contents will be identical to the original file @file{blues} that you +deleted. -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. +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. -@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 +You can now extract the member @file{blues} from the archive file +@file{collection.tar} like this: -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}). +@smallexample +$ @kbd{tar --extract --file=collection.tar blues} +@end smallexample -@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 +@noindent +If you list the files in the directory again, you will see that the file +@file{blues} has been restored, with its original permissions, data +modification times, and owner.@footnote{This is only accidentally +true, but not in general. Whereas modification times are always +restored, in most cases, one has to be root for restoring the owner, +and use a special option for restoring permissions. Here, it just +happens that the restoring user is also the owner of the archived +members, and that the current @code{umask} is compatible with original +permissions.} (These parameters will be identical to those which +the file had when you originally placed it in the archive; any changes +you may have made before deleting the file from the file system, +however, will @emph{not} have been made to the archive member.) The +archive file, @samp{collection.tar}, is the same as it was before you +extracted @samp{blues}. You can confirm this by running @command{tar} with +@option{--list} (@option{-t}). + +Remember that as with other operations, specifying the exact member +name is important. @w{@kbd{tar --extract --file=bfiles.tar birds}} +will fail, because there is no member named @file{birds}. To extract +the member named @file{./birds}, you must specify @w{@kbd{tar +--extract --file=bfiles.tar ./birds}}. If you don't remember the +exact member names, use @option{--list} (@option{-t}) option +(@pxref{list}). You can also extract those members that match a +specific @dfn{globbing pattern}. For example, to extract from +@file{bfiles.tar} all files that begin with @samp{b}, no matter their +directory prefix, you could type: + +@smallexample +$ @kbd{tar -x -f bfiles.tar --wildcards --no-anchored 'b*'} +@end smallexample -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. +@noindent +Here, @option{--wildcards} instructs @command{tar} to treat +command line arguments as globbing patterns and @option{--no-anchored} +informs it that the patterns apply to member names after any @samp{/} +delimiter. The use of globbing patterns is discussed in detail in +@xref{wildcards}. + +You can extract a file to standard output by combining the above options +with the @option{--to-stdout} (@option{-O}) option (@pxref{Writing to Standard +Output}). + +If you give the @option{--verbose} option, then @option{--extract} +will print the names of the archive members as it extracts them. + +@node extract dir +@subsection Extracting Files that are Directories + +Extracting directories which are members of an archive is similar to +extracting other files. The main difference to be aware of is that if +the extracted directory has the same name as any directory already in +the working directory, then files in the extracted directory will be +placed into the directory of the same name. Likewise, if there are +files in the pre-existing directory with the same names as the members +which you extract, the files from the extracted archive will replace +the files already in the working directory (and possible +subdirectories). This will happen regardless of whether or not the +files in the working directory were more recent than those extracted +(there exist, however, special options that alter this behavior +@pxref{Writing}). + +However, if a file was stored with a directory name as part of its file +name, and that directory does not exist under the working directory when +the file is extracted, @command{tar} will create the directory. + +We can demonstrate how to use @option{--extract} to extract a directory +file with an example. Change to the @file{practice} directory if you +weren't there, and remove the files @file{folk} and @file{jazz}. Then, +go back to the parent directory and extract the archive +@file{music.tar}. You may either extract the entire archive, or you may +extract only the files you just deleted. To extract the entire archive, +don't give any file names as arguments after the archive name +@file{music.tar}. To extract only the files you deleted, use the +following command: -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): +@smallexample +$ @kbd{tar -xvf music.tar practice/folk practice/jazz} +practice/folk +practice/jazz +@end smallexample -@example -tar --add-archive --file=stooges hail/hail/fredonia -@end example +@noindent +If you were to specify two @option{--verbose} (@option{-v}) options, @command{tar} +would have displayed more detail about the extracted files, as shown +in the example below: -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}). +@smallexample +$ @kbd{tar -xvvf music.tar practice/folk practice/jazz} +-rw-r--r-- me/user 28 1996-10-18 16:31 practice/jazz +-rw-r--r-- me/user 20 1996-09-23 16:44 practice/folk +@end smallexample -@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 +@noindent +Because you created the directory with @file{practice} as part of the +file names of each of the files by archiving the @file{practice} +directory as @file{practice}, you must give @file{practice} as part +of the file names when you extract those files from the archive. -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. +@node extracting untrusted archives +@subsection Extracting Archives from Untrusted Sources -The following example removes the file @file{curley} from the archive -@file{stooges}: +Extracting files from archives can overwrite files that already exist. +If you receive an archive from an untrusted source, you should make a +new directory and extract into that directory, so that you don't have +to worry about the extraction overwriting one of your existing files. +For example, if @file{untrusted.tar} came from somewhere else on the +Internet, and you don't necessarily trust its contents, you can +extract it as follows: -@example -tar --delete --file=stooges curley -@end example +@smallexample +$ @kbd{mkdir newdir} +$ @kbd{cd newdir} +$ @kbd{tar -xvf ../untrusted.tar} +@end smallexample -You can only use @samp{tar --delete} on an archive if the archive -device allows you to write to any point on the media. +It is also a good practice to examine contents of the archive +before extracting it, using @option{--list} (@option{-t}) option, possibly combined +with @option{--verbose} (@option{-v}). -@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 +@node failing commands +@subsection Commands That Will Fail -@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=-). +Here are some sample commands you might try which will not work, and why +they won't work. -@node Matching Format Parameters, , Deleting Archive Files, Modifying -@subsection Matching the Format Parameters +If you try to use this command, -Some format parameters must be taken into consideration when modifying -an archive: +@smallexample +$ @kbd{tar -xvf music.tar folk jazz} +@end smallexample -Compressed archives cannot be modified. +@noindent +you will get the following response: -You have to specify the block size of the archive when modifying an -archive with a non-default block size. +@smallexample +tar: folk: Not found in archive +tar: jazz: Not found in archive +@end smallexample -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. +@noindent +This is because these files were not originally @emph{in} the parent +directory @file{..}, where the archive is located; they were in the +@file{practice} directory, and their file names reflect this: + +@smallexample +$ @kbd{tar -tvf music.tar} +practice/blues +practice/folk +practice/jazz +@end smallexample -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 +@FIXME{make sure the above works when going through the examples in +order...} + +@noindent +Likewise, if you try to use this command, -@c <<< xref somewhere, for more information about format parameters. +@smallexample +$ @kbd{tar -tvf music.tar folk jazz} +@end smallexample -@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 +@noindent +you would get a similar response. Members with those names are not in the +archive. You must use the correct member names, or wildcards, in order +to extract the files from the archive. + +If you have forgotten the correct names of the files in the archive, +use @w{@kbd{tar --list --verbose}} to list them correctly. + +@FIXME{more examples, here? hag thinks it's a good idea.} + +@node going further +@section Going Further Ahead in this Manual +@UNREVISED + +@FIXME{need to write up a node here about the things that are going to +be in the rest of the manual.} + +@node tar invocation +@chapter Invoking @GNUTAR{} + +This chapter is about how one invokes the @GNUTAR{} +command, from the command synopsis (@pxref{Synopsis}). There are +numerous options, and many styles for writing them. One mandatory +option specifies the operation @command{tar} should perform +(@pxref{Operation Summary}), other options are meant to detail how +this operation should be performed (@pxref{Option Summary}). +Non-option arguments are not always interpreted the same way, +depending on what the operation is. + +You will find in this chapter everything about option styles and rules for +writing them (@pxref{Styles}). On the other hand, operations and options +are fully described elsewhere, in other chapters. Here, you will find +only synthetic descriptions for operations and options, together with +pointers to other parts of the @command{tar} manual. + +Some options are so special they are fully described right in this +chapter. They have the effect of inhibiting the normal operation of +@command{tar} or else, they globally alter the amount of feedback the user +receives about what is going on. These are the @option{--help} and +@option{--version} (@pxref{help}), @option{--verbose} (@pxref{verbose}) +and @option{--interactive} options (@pxref{interactive}). -@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. +@menu +* Synopsis:: +* using tar options:: +* Styles:: +* All Options:: All @command{tar} Options. +* help:: Where to Get Help. +* defaults:: What are the Default Values. +* verbose:: Checking @command{tar} progress. +* checkpoints:: Checkpoints. +* warnings:: Controlling Warning Messages. +* interactive:: Asking for Confirmation During Operations. +* external:: Running External Commands. +@end menu -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. +@node Synopsis +@section General Synopsis of @command{tar} + +The @GNUTAR{} program is invoked as either one of: + +@smallexample +@kbd{tar @var{option}@dots{} [@var{name}]@dots{}} +@kbd{tar @var{letter}@dots{} [@var{argument}]@dots{} [@var{option}]@dots{} [@var{name}]@dots{}} +@end smallexample + +The second form is for when old options are being used. + +You can use @command{tar} to store files in an archive, to extract them from +an archive, and to do other types of archive manipulation. The primary +argument to @command{tar}, which is called the @dfn{operation}, specifies +which action to take. The other arguments to @command{tar} are either +@dfn{options}, which change the way @command{tar} performs an operation, +or file names or archive members, which specify the files or members +@command{tar} is to act on. + +You can actually type in arguments in any order, even if in this manual +the options always precede the other arguments, to make examples easier +to understand. Further, the option stating the main operation mode +(the @command{tar} main command) is usually given first. + +Each @var{name} in the synopsis above is interpreted as an archive member +name when the main command is one of @option{--compare} +(@option{--diff}, @option{-d}), @option{--delete}, @option{--extract} +(@option{--get}, @option{-x}), @option{--list} (@option{-t}) or +@option{--update} (@option{-u}). When naming archive members, you +must give the exact name of the member in the archive, as it is +printed by @option{--list}. For @option{--append} (@option{-r}) and +@option{--create} (@option{-c}), these @var{name} arguments specify +the names of either files or directory hierarchies to place in the archive. +These files or hierarchies should already exist in the file system, +prior to the execution of the @command{tar} command. + +@command{tar} interprets relative file names as being relative to the +working directory. @command{tar} will make all file names relative +(by removing leading slashes when archiving or restoring files), +unless you specify otherwise (using the @option{--absolute-names} +option). @xref{absolute}, for more information about +@option{--absolute-names}. -If the blocking factor of the archive differs from the default, -@code{tar} reports this. @xref{Blocking Factor}. +If you give the name of a directory as either a file name or a member +name, then @command{tar} acts recursively on all the files and directories +beneath that directory. For example, the name @file{/} identifies all +the files in the file system to @command{tar}. + +The distinction between file names and archive member names is especially +important when shell globbing is used, and sometimes a source of confusion +for newcomers. @xref{wildcards}, for more information about globbing. +The problem is that shells may only glob using existing files in the +file system. Only @command{tar} itself may glob on archive members, so when +needed, you must ensure that wildcard characters reach @command{tar} without +being interpreted by the shell first. Using a backslash before @samp{*} +or @samp{?}, or putting the whole argument between quotes, is usually +sufficient for this. + +Even if @var{name}s are often specified on the command line, they +can also be read from a text file in the file system, using the +@option{--files-from=@var{file-of-names}} (@option{-T @var{file-of-names}}) option. + +If you don't use any file name arguments, @option{--append} (@option{-r}), +@option{--delete} and @option{--concatenate} (@option{--catenate}, +@option{-A}) will do nothing, while @option{--create} (@option{-c}) +will usually yield a diagnostic and inhibit @command{tar} execution. +The other operations of @command{tar} (@option{--list}, +@option{--extract}, @option{--compare}, and @option{--update}) +will act on the entire contents of the archive. + +@anchor{exit status} +@cindex exit status +@cindex return status +Besides successful exits, @GNUTAR{} may fail for +many reasons. Some reasons correspond to bad usage, that is, when the +@command{tar} command line is improperly written. Errors may be +encountered later, while processing the archive or the files. Some +errors are recoverable, in which case the failure is delayed until +@command{tar} has completed all its work. Some errors are such that +it would be not meaningful, or at least risky, to continue processing: +@command{tar} then aborts processing immediately. All abnormal exits, +whether immediate or delayed, should always be clearly diagnosed on +@code{stderr}, after a line stating the nature of the error. + +Possible exit codes of @GNUTAR{} are summarized in the following +table: + +@table @asis +@item 0 +@samp{Successful termination}. + +@item 1 +@samp{Some files differ}. If tar was invoked with @option{--compare} +(@option{--diff}, @option{-d}) command line option, this means that +some files in the archive differ from their disk counterparts +(@pxref{compare}). If tar was given @option{--create}, +@option{--append} or @option{--update} option, this exit code means +that some files were changed while being archived and so the resulting +archive does not contain the exact copy of the file set. + +@item 2 +@samp{Fatal error}. This means that some fatal, unrecoverable error +occurred. +@end table -@xref{Archive Reading Options} for a list of options which can be used -to modify @samp{--list}'s operation. +If @command{tar} has invoked a subprocess and that subprocess exited with a +nonzero exit code, @command{tar} exits with that code as well. +This can happen, for example, if @command{tar} was given some +compression option (@pxref{gzip}) and the external compressor program +failed. Another example is @command{rmt} failure during backup to the +remote device (@pxref{Remote Tape Server}). + +@node using tar options +@section Using @command{tar} Options + +@GNUTAR{} has a total of eight operating modes which +allow you to perform a variety of tasks. You are required to choose +one operating mode each time you employ the @command{tar} program by +specifying one, and only one operation as an argument to the +@command{tar} command (the corresponding options may be found +at @ref{frequent operations} and @ref{Operations}). Depending on +circumstances, you may also wish to customize how the chosen operating +mode behaves. For example, you may wish to change the way the output +looks, or the format of the files that you wish to archive may require +you to do something special in order to make the archive look right. + +You can customize and control @command{tar}'s performance by running +@command{tar} with one or more options (such as @option{--verbose} +(@option{-v}), which we used in the tutorial). As we said in the +tutorial, @dfn{options} are arguments to @command{tar} which are (as +their name suggests) optional. Depending on the operating mode, you +may specify one or more options. Different options will have different +effects, but in general they all change details of the operation, such +as archive format, archive name, or level of user interaction. Some +options make sense with all operating modes, while others are +meaningful only with particular modes. You will likely use some +options frequently, while you will only use others infrequently, or +not at all. (A full list of options is available in @pxref{All Options}.) + +@vrindex TAR_OPTIONS, environment variable +@anchor{TAR_OPTIONS} +The @env{TAR_OPTIONS} environment variable specifies default options to +be placed in front of any explicit options. For example, if +@code{TAR_OPTIONS} is @samp{-v --unlink-first}, @command{tar} behaves as +if the two options @option{-v} and @option{--unlink-first} had been +specified before any explicit options. Option specifications are +separated by whitespace. A backslash escapes the next character, so it +can be used to specify an option containing whitespace or a backslash. + +Note that @command{tar} options are case sensitive. For example, the +options @option{-T} and @option{-t} are different; the first requires an +argument for stating the name of a file providing a list of @var{name}s, +while the second does not require an argument and is another way to +write @option{--list} (@option{-t}). + +In addition to the eight operations, there are many options to +@command{tar}, and three different styles for writing both: long (mnemonic) +form, short form, and old style. These styles are discussed below. +Both the options and the operations can be written in any of these three +styles. + +@FIXME{menu at end of this node. need to think of an actual outline +for this chapter; probably do that after stuff from chapter 4 is +incorporated.} + +@node Styles +@section The Three Option Styles + +There are three styles for writing operations and options to the command +line invoking @command{tar}. The different styles were developed at +different times during the history of @command{tar}. These styles will be +presented below, from the most recent to the oldest. + +Some options must take an argument@footnote{For example, @option{--file} +(@option{-f}) takes the name of an archive file as an argument. If +you do not supply an archive file name, @command{tar} will use a +default, but this can be confusing; thus, we recommend that you always +supply a specific archive file name.}. Where you @emph{place} the +arguments generally depends on which style of options you choose. We +will detail specific information relevant to each option style in the +sections on the different option styles, below. The differences are +subtle, yet can often be very important; incorrect option placement +can cause you to overwrite a number of important files. We urge you +to note these differences, and only use the option style(s) which +makes the most sense to you until you feel comfortable with the others. + +Some options @emph{may} take an argument. Such options may have at +most long and short forms, they do not have old style equivalent. The +rules for specifying an argument for such options are stricter than +those for specifying mandatory arguments. Please, pay special +attention to them. -This example prints a list of the archive members of the archive -@file{stooges}: +@menu +* Long Options:: Long Option Style +* Short Options:: Short Option Style +* Old Options:: Old Option Style +* Mixing:: Mixing Option Styles +@end menu -@example -tar --list --file=stooges -@end example +@node Long Options +@subsection Long Option Style + +@cindex long options +@cindex options, long style +@cindex options, GNU style +@cindex options, mnemonic names +Each option has at least one @dfn{long} (or @dfn{mnemonic}) name starting with two +dashes in a row, e.g., @option{--list}. The long names are more clear than +their corresponding short or old names. It sometimes happens that a +single long option has many different names which are +synonymous, such as @option{--compare} and @option{--diff}. In addition, +long option names can be given unique abbreviations. For example, +@option{--cre} can be used in place of @option{--create} because there is no +other long option which begins with @samp{cre}. (One way to find +this out is by trying it and seeing what happens; if a particular +abbreviation could represent more than one option, @command{tar} will tell +you that that abbreviation is ambiguous and you'll know that that +abbreviation won't work. You may also choose to run @samp{tar --help} +to see a list of options. Be aware that if you run @command{tar} with a +unique abbreviation for the long name of an option you didn't want to +use, you are stuck; @command{tar} will perform the command as ordered.) + +Long options are meant to be obvious and easy to remember, and their +meanings are generally easier to discern than those of their +corresponding short options (see below). For example: + +@smallexample +$ @kbd{tar --create --verbose --blocking-factor=20 --file=/dev/rmt0} +@end smallexample @noindent -@code{tar} responds: +gives a fairly good set of hints about what the command does, even +for those not fully acquainted with @command{tar}. + +@cindex arguments to long options +@cindex long options with mandatory arguments +Long options which require arguments take those arguments +immediately following the option name. There are two ways of +specifying a mandatory argument. It can be separated from the +option name either by an equal sign, or by any amount of +white space characters. For example, the @option{--file} option (which +tells the name of the @command{tar} archive) is given a file such as +@file{archive.tar} as argument by using any of the following notations: +@option{--file=archive.tar} or @option{--file archive.tar}. + +@cindex optional arguments to long options +@cindex long options with optional arguments +In contrast, optional arguments must always be introduced using +an equal sign. For example, the @option{--backup} option takes +an optional argument specifying backup type. It must be used +as @option{--backup=@var{backup-type}}. + +@node Short Options +@subsection Short Option Style + +@cindex short options +@cindex options, short style +@cindex options, traditional +Most options also have a @dfn{short option} name. Short options start with +a single dash, and are followed by a single character, e.g., @option{-t} +(which is equivalent to @option{--list}). The forms are absolutely +identical in function; they are interchangeable. + +The short option names are faster to type than long option names. + +@cindex arguments to short options +@cindex short options with mandatory arguments +Short options which require arguments take their arguments immediately +following the option, usually separated by white space. It is also +possible to stick the argument right after the short option name, using +no intervening space. For example, you might write @w{@option{-f +archive.tar}} or @option{-farchive.tar} instead of using +@option{--file=archive.tar}. Both @option{--file=@var{archive-name}} and +@w{@option{-f @var{archive-name}}} denote the option which indicates a +specific archive, here named @file{archive.tar}. + +@cindex optional arguments to short options +@cindex short options with optional arguments +Short options which take optional arguments take their arguments +immediately following the option letter, @emph{without any intervening +white space characters}. + +Short options' letters may be clumped together, but you are not +required to do this (as compared to old options; see below). When +short options are clumped as a set, use one (single) dash for them +all, e.g., @w{@samp{@command{tar} -cvf}}. Only the last option in +such a set is allowed to have an argument@footnote{Clustering many +options, the last of which has an argument, is a rather opaque way to +write options. Some wonder if @acronym{GNU} @code{getopt} should not +even be made helpful enough for considering such usages as invalid.}. + +When the options are separated, the argument for each option which requires +an argument directly follows that option, as is usual for Unix programs. +For example: + +@smallexample +$ @kbd{tar -c -v -b 20 -f /dev/rmt0} +@end smallexample + +If you reorder short options' locations, be sure to move any arguments +that belong to them. If you do not move the arguments properly, you may +end up overwriting files. + +@node Old Options +@subsection Old Option Style +@cindex options, old style +@cindex old option style +@cindex option syntax, traditional + +As far as we know, all @command{tar} programs, @acronym{GNU} and +non-@acronym{GNU}, support @dfn{old options}: that is, if the first +argument does not start with @samp{-}, it is assumed to specify option +letters. @GNUTAR{} supports old options not only for historical +reasons, but also because many people are used to them. If the first +argument does not start with a dash, you are announcing the old option +style instead of the short option style; old options are decoded +differently. + +Like short options, old options are single letters. However, old options +must be written together as a single clumped set, without spaces separating +them or dashes preceding them. This set +of letters must be the first to appear on the command line, after the +@command{tar} program name and some white space; old options cannot appear +anywhere else. The letter of an old option is exactly the same letter as +the corresponding short option. For example, the old option @samp{t} is +the same as the short option @option{-t}, and consequently, the same as the +long option @option{--list}. So for example, the command @w{@samp{tar +cv}} specifies the option @option{-v} in addition to the operation @option{-c}. + +@cindex arguments to old options +@cindex old options with mandatory arguments +When options that need arguments are given together with the command, +all the associated arguments follow, in the same order as the options. +Thus, the example given previously could also be written in the old +style as follows: + +@smallexample +$ @kbd{tar cvbf 20 /dev/rmt0} +@end smallexample -@example -larry -moe -shemp -marx/julius -marx/alexander -marx/karl -@end example +@noindent +Here, @samp{20} is the argument of @option{-b} and @samp{/dev/rmt0} is +the argument of @option{-f}. -This example generates a verbose list of the archive members of the -archive file @file{dwarves}, which has a blocking factor of two: +The old style syntax can make it difficult to match +option letters with their corresponding arguments, and is often +confusing. In the command @w{@samp{tar cvbf 20 /dev/rmt0}}, for example, +@samp{20} is the argument for @option{-b}, @samp{/dev/rmt0} is the +argument for @option{-f}, and @option{-v} does not have a corresponding +argument. Even using short options like in @w{@samp{tar -c -v -b 20 -f +/dev/rmt0}} is clearer, putting all arguments next to the option they +pertain to. -@example -tar --list -v --file=blocks -@end example +If you want to reorder the letters in the old option argument, be +sure to reorder any corresponding argument appropriately. -@noindent -@code{tar} responds: +This old way of writing @command{tar} options can surprise even experienced +users. For example, the two commands: -@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 +@smallexample +@kbd{tar cfz archive.tar.gz file} +@kbd{tar -cfz archive.tar.gz file} +@end smallexample -@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 +@noindent +are quite different. The first example uses @file{archive.tar.gz} as +the value for option @samp{f} and recognizes the option @samp{z}. The +second example, however, uses @file{z} as the value for option +@samp{f} --- probably not what was intended. + +This second example could be corrected in many ways, among which the +following are equivalent: + +@smallexample +@kbd{tar -czf archive.tar.gz file} +@kbd{tar -cf archive.tar.gz -z file} +@kbd{tar cf archive.tar.gz -z file} +@end smallexample + +@node Mixing +@subsection Mixing Option Styles + +@cindex options, mixing different styles +All three styles may be intermixed in a single @command{tar} command, +so long as the rules for each style are fully +respected@footnote{Before @GNUTAR{} version 1.11.6, +a bug prevented intermixing old style options with long options in +some cases.}. Old style options and either of the modern styles of +options may be mixed within a single @command{tar} command. However, +old style options must be introduced as the first arguments only, +following the rule for old options (old options must appear directly +after the @command{tar} command and some white space). Modern options +may be given only after all arguments to the old options have been +collected. If this rule is not respected, a modern option might be +falsely interpreted as the value of the argument to one of the old +style options. + +For example, all the following commands are wholly equivalent, and +illustrate the many combinations and orderings of option styles. + +@smallexample +@kbd{tar --create --file=archive.tar} +@kbd{tar --create -f archive.tar} +@kbd{tar --create -farchive.tar} +@kbd{tar --file=archive.tar --create} +@kbd{tar --file=archive.tar -c} +@kbd{tar -c --file=archive.tar} +@kbd{tar -c -f archive.tar} +@kbd{tar -c -farchive.tar} +@kbd{tar -cf archive.tar} +@kbd{tar -cfarchive.tar} +@kbd{tar -f archive.tar --create} +@kbd{tar -f archive.tar -c} +@kbd{tar -farchive.tar --create} +@kbd{tar -farchive.tar -c} +@kbd{tar c --file=archive.tar} +@kbd{tar c -f archive.tar} +@kbd{tar c -farchive.tar} +@kbd{tar cf archive.tar} +@kbd{tar f archive.tar --create} +@kbd{tar f archive.tar -c} +@kbd{tar fc archive.tar} +@end smallexample + +On the other hand, the following commands are @emph{not} equivalent to +the previous set: + +@smallexample +@kbd{tar -f -c archive.tar} +@kbd{tar -fc archive.tar} +@kbd{tar -fcarchive.tar} +@kbd{tar -farchive.tarc} +@kbd{tar cfarchive.tar} +@end smallexample -To read archive members from the archive and write them into the file -system, use @samp{tar --extract}. The archive itself is left -unchanged. +@noindent +These last examples mean something completely different from what the +user intended (judging based on the example in the previous set which +uses long options, whose intent is therefore very clear). The first +four specify that the @command{tar} archive would be a file named +@option{-c}, @samp{c}, @samp{carchive.tar} or @samp{archive.tarc}, +respectively. The first two examples also specify a single non-option, +@var{name} argument having the value @samp{archive.tar}. The last +example contains only old style option letters (repeating option +@samp{c} twice), not all of which are meaningful (eg., @samp{.}, +@samp{h}, or @samp{i}), with no argument value. +@FIXME{not sure i liked +the first sentence of this paragraph..} + +@node All Options +@section All @command{tar} Options + +The coming manual sections contain an alphabetical listing of all +@command{tar} operations and options, with brief descriptions and +cross-references to more in-depth explanations in the body of the manual. +They also contain an alphabetically arranged table of the short option +forms with their corresponding long option. You can use this table as +a reference for deciphering @command{tar} commands in scripts. -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. +@menu +* Operation Summary:: +* Option Summary:: +* Short Option Summary:: +@end menu -The following example shows the extraction of the archive -@file{stooges} into an empty directory: +@node Operation Summary +@subsection Operations -@example -tar --extract --file=stooges -@end example +@table @option -@noindent -Generating a listing of the directory (@samp{ls}) produces: +@opsummary{append} +@item --append +@itemx -r -@example -larry -moe -shemp -marx -@end example +Appends files to the end of the archive. @xref{append}. -@noindent -The subdirectory @file{marx} contains the files @file{julius}, -@file{alexander} and @file{karl}. +@opsummary{catenate} +@item --catenate +@itemx -A -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: +Same as @option{--concatenate}. @xref{concatenate}. -@example -tar --extract --file=stooges marx -@end example +@opsummary{compare} +@item --compare +@itemx -d -@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 +Compares archive members with their counterparts in the file +system, and reports differences in file size, mode, owner, +modification date and contents. @xref{compare}. -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}). +@opsummary{concatenate} +@item --concatenate +@itemx -A -@menu -* Archive Reading Options:: -* File Writing Options:: -* Scarce Disk Space:: Recovering From Scarce Disk Space -@end menu +Appends other @command{tar} archives to the end of the archive. +@xref{concatenate}. -@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 +@opsummary{create} +@item --create +@itemx -c -@c <<< each option wants its own node. summary after menu - -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}. - -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. +Creates a new @command{tar} archive. @xref{create}. -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}. +@opsummary{delete} +@item --delete -@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 +Deletes members from the archive. Don't try this on an archive on a +tape! @xref{delete}. -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). +@opsummary{diff} +@item --diff +@itemx -d -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. +Same @option{--compare}. @xref{compare}. -@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 +@opsummary{extract} +@item --extract +@itemx -x -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. +Extracts members from the archive into the file system. @xref{extract}. -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. +@opsummary{get} +@item --get +@itemx -x -This option is probably never needed on modern computer systems. +Same as @option{--extract}. @xref{extract}. -@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 +@opsummary{list} +@item --list +@itemx -t -@c we don't need/want --preserve to exist any more +Lists the members in an archive. @xref{list}. -@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 +@opsummary{update} +@item --update +@itemx -u -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. +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}. -@table @samp -@item --keep-old files -@itemx -k -Prevents @code{tar} from overwriting files in the file system during -extraction. @end table -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. +@node Option Summary +@subsection @command{tar} Options + +@table @option + +@opsummary{absolute-names} +@item --absolute-names +@itemx -P + +Normally when creating an archive, @command{tar} strips an initial +@samp{/} from member names, and when extracting from an archive @command{tar} +treats names specially if they have initial @samp{/} or internal +@samp{..}. This option disables that behavior. @xref{absolute}. + +@opsummary{after-date} +@item --after-date + +(See @option{--newer}, @pxref{after}) + +@opsummary{anchored} +@item --anchored +A pattern must match an initial subsequence of the name's components. +@xref{controlling pattern-matching}. + +@opsummary{atime-preserve} +@item --atime-preserve +@itemx --atime-preserve=replace +@itemx --atime-preserve=system + +Attempt to preserve the access time of files when reading them. This +option currently is effective only on files that you own, unless you +have superuser privileges. + +@option{--atime-preserve=replace} remembers the access time of a file +before reading it, and then restores the access time afterwards. This +may cause problems if other programs are reading the file at the same +time, as the times of their accesses will be lost. On most platforms +restoring the access time also requires @command{tar} to restore the +data modification time too, so this option may also cause problems if +other programs are writing the file at the same time (@command{tar} attempts +to detect this situation, but cannot do so reliably due to race +conditions). Worse, on most platforms restoring the access time also +updates the status change time, which means that this option is +incompatible with incremental backups. + +@option{--atime-preserve=system} avoids changing time stamps on files, +without interfering with time stamp updates +caused by other programs, so it works better with incremental backups. +However, it requires a special @code{O_NOATIME} option from the +underlying operating and file system implementation, and it also requires +that searching directories does not update their access times. As of +this writing (November 2005) this works only with Linux, and only with +Linux kernels 2.6.8 and later. Worse, there is currently no reliable +way to know whether this feature actually works. Sometimes +@command{tar} knows that it does not work, and if you use +@option{--atime-preserve=system} then @command{tar} complains and +exits right away. But other times @command{tar} might think that the +option works when it actually does not. + +Currently @option{--atime-preserve} with no operand defaults to +@option{--atime-preserve=replace}, but this may change in the future +as support for @option{--atime-preserve=system} improves. + +If your operating or file system does not support +@option{--atime-preserve=@-system}, you might be able to preserve access +times reliably by using the @command{mount} command. For example, +you can mount the file system read-only, or access the file system via +a read-only loopback mount, or use the @samp{noatime} mount option +available on some systems. However, mounting typically requires +superuser privileges and can be a pain to manage. + +@opsummary{auto-compress} +@item --auto-compress +@itemx -a + +During a @option{--create} operation, enables automatic compressed +format recognition based on the archive suffix. The effect of this +option is cancelled by @option{--no-auto-compress}. @xref{gzip}. + +@opsummary{backup} +@item --backup=@var{backup-type} + +Rather than deleting files from the file system, @command{tar} will +back them up using simple or numbered backups, depending upon +@var{backup-type}. @xref{backup}. + +@opsummary{block-number} +@item --block-number +@itemx -R + +With this option present, @command{tar} prints error messages for read errors +with the block number in the archive file. @xref{block-number}. + +@opsummary{blocking-factor} +@item --blocking-factor=@var{blocking} +@itemx -b @var{blocking} + +Sets the blocking factor @command{tar} uses to @var{blocking} x 512 bytes per +record. @xref{Blocking Factor}. + +@opsummary{bzip2} +@item --bzip2 +@itemx -j + +This option tells @command{tar} to read or write archives through +@code{bzip2}. @xref{gzip}. + +@opsummary{check-device} +@item --check-device +Check device numbers when creating a list of modified files for +incremental archiving. This is the default. @xref{device numbers}, +for a detailed description. + +@opsummary{checkpoint} +@item --checkpoint[=@var{number}] + +This option directs @command{tar} to print periodic checkpoint +messages as it reads through the archive. It is intended for when you +want a visual indication that @command{tar} is still running, but +don't want to see @option{--verbose} output. You can also instruct +@command{tar} to execute a list of actions on each checkpoint, see +@option{--checkpoint-action} below. For a detailed description, see +@ref{checkpoints}. + +@opsummary{checkpoint-action} +@item --checkpoint-action=@var{action} +Instruct @command{tar} to execute an action upon hitting a +breakpoint. Here we give only a brief outline. @xref{checkpoints}, +for a complete description. + +The @var{action} argument can be one of the following: + +@table @asis +@item bell +Produce an audible bell on the console. + +@item dot +@itemx . +Print a single dot on the standard listing stream. + +@item echo +Display a textual message on the standard error, with the status and +number of the checkpoint. This is the default. + +@item echo=@var{string} +Display @var{string} on the standard error. Before output, the string +is subject to meta-character expansion. + +@item exec=@var{command} +Execute the given @var{command}. + +@item sleep=@var{time} +Wait for @var{time} seconds. + +@item ttyout=@var{string} +Output @var{string} on the current console (@file{/dev/tty}). +@end table -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}. +Several @option{--checkpoint-action} options can be specified. The +supplied actions will be executed in order of their appearance in the +command line. -@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 +Using @option{--checkpoint-action} without @option{--checkpoint} +assumes default checkpoint frequency of one checkpoint per 10 records. -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. +@item ustar +Creates a @acronym{POSIX.1-1988} compatible archive. -@c >>> is write access an issue? +@item posix +Creates a @acronym{POSIX.1-2001 archive}. -@table @samp -@item --absolute-paths -Preserves full file names (inclusing superior dirctory names) when -archiving files. Preserves leading slash when extracting files. @end table -@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 +@xref{Formats}, for a detailed discussion of these formats. -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, +@opsummary{full-time} +@item --full-time +This option instructs @command{tar} to print file times to their full +resolution. Usually this means 1-second resolution, but that depends +on the underlying file system. The @option{--full-time} option takes +effect only when detailed output (verbosity level 2 or higher) has +been requested using the @option{--verbose} option, e.g., when listing +or extracting archives: -@example -tar --create iggy ziggy --directory=baz melvin -@end example +@smallexample +$ @kbd{tar -t -v --full-time -f archive.tar} +@end smallexample @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. +or, when creating an 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. +@smallexample +$ @kbd{tar -c -vv --full-time -f archive.tar .} +@end smallexample -Contrast this with the command +Notice, thar when creating the archive you need to specify +@option{--verbose} twice to get a detailed output (@pxref{verbose +tutorial}). -@example -tar -c iggy ziggy bar/melvin -@end example +@opsummary{group} +@item --group=@var{group} -@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}. +Files added to the @command{tar} archive will have a group @acronym{ID} of @var{group}, +rather than the group from the source file. @var{group} can specify a +symbolic name, or a numeric @acronym{ID}, or both as +@var{name}:@var{id}. @xref{override}. -@table @samp -@item --directory=@file{directory} -@itemx -C @file{directory} -Changes the working directory. -@end table +Also see the comments for the @option{--owner=@var{user}} option. -@c <<>> +@xref{Keep Old Files}. -@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} +@opsummary{label} +@item --label=@var{name} +@itemx -V @var{name} -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. +When creating an archive, instructs @command{tar} to write @var{name} +as a name record in the archive. When extracting or listing archives, +@command{tar} will only operate on archives that have a label matching +the pattern specified in @var{name}. @xref{Tape Files}. -@menu -* Additional Information:: -* Interactive Operation:: -@end menu +@opsummary{level} +@item --level=@var{n} +Force incremental backup of level @var{n}. As of @GNUTAR version +@value{VERSION}, the option @option{--level=0} truncates the snapshot +file, thereby forcing the level 0 dump. Other values of @var{n} are +effectively ignored. @xref{--level=0}, for details and examples. -@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. +The use of this option is valid only in conjunction with the +@option{--listed-incremental} option. @xref{Incremental Dumps}, +for a detailed description. -@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 +@opsummary{listed-incremental} +@item --listed-incremental=@var{snapshot-file} +@itemx -g @var{snapshot-file} -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. +During a @option{--create} operation, specifies that the archive that +@command{tar} creates is a new @acronym{GNU}-format incremental +backup, using @var{snapshot-file} to determine which files to backup. +With other operations, informs @command{tar} that the archive is in +incremental format. @xref{Incremental Dumps}. -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 +@opsummary{lzip} +@item --lzip -@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 +This option tells @command{tar} to read or write archives through +@command{lzip}. @xref{gzip}. -@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: +@opsummary{lzma} +@item --lzma -@example -tar --version -@end example +This option tells @command{tar} to read or write archives through +@command{lzma}. @xref{gzip}. -@noindent -might return: +@item --lzop -@example -GNU tar version 1.09 -@end example -@c used to be an option. has been fixed. +This option tells @command{tar} to read or write archives through +@command{lzop}. @xref{gzip}. -@node Interactive Operation, , Additional Information, User Interaction -@section Asking for Confirmation During Operations -@cindex Interactive operation +@opsummary{mode} +@item --mode=@var{permissions} -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 +When adding files to an archive, @command{tar} will use +@var{permissions} for the archive members, rather than the permissions +from the files. @var{permissions} can be specified either as an octal +number or as symbolic permissions, like with +@command{chmod}. @xref{override}. + +@opsummary{mtime} +@item --mtime=@var{date} + +When adding files to an archive, @command{tar} will use @var{date} as +the modification time of members when creating archives, instead of +their actual modification times. The value of @var{date} can be +either a textual date representation (@pxref{Date input formats}) or a +name of the existing file, starting with @samp{/} or @samp{.}. In the +latter case, the modification time of that file is used. @xref{override}. + +@opsummary{multi-volume} +@item --multi-volume +@itemx -M + +Informs @command{tar} that it should create or otherwise operate on a +multi-volume @command{tar} archive. @xref{Using Multiple Tapes}. + +@opsummary{new-volume-script} +@item --new-volume-script + +(see @option{--info-script}) + +@opsummary{newer} +@item --newer=@var{date} +@itemx --after-date=@var{date} +@itemx -N + +When creating an archive, @command{tar} will only add files that have changed +since @var{date}. If @var{date} begins with @samp{/} or @samp{.}, it +is taken to be the name of a file whose data modification time specifies +the date. @xref{after}. + +@opsummary{newer-mtime} +@item --newer-mtime=@var{date} + +Like @option{--newer}, but add only files whose +contents have changed (as opposed to just @option{--newer}, which will +also back up files for which any status information has +changed). @xref{after}. + +@opsummary{no-anchored} +@item --no-anchored +An exclude pattern can match any subsequence of the name's components. +@xref{controlling pattern-matching}. + +@opsummary{no-auto-compress} +@item --no-auto-compress + +Disables automatic compressed format recognition based on the archive +suffix. @xref{--auto-compress}. @xref{gzip}. + +@opsummary{no-check-device} +@item --no-check-device +Do not check device numbers when creating a list of modified files +for incremental archiving. @xref{device numbers}, for +a detailed description. + +@opsummary{no-delay-directory-restore} +@item --no-delay-directory-restore + +Modification times and permissions of extracted +directories are set when all files from this directory have been +extracted. This is the default. +@xref{Directory Modification Times and Permissions}. + +@opsummary{no-ignore-case} +@item --no-ignore-case +Use case-sensitive matching. +@xref{controlling pattern-matching}. + +@opsummary{no-ignore-command-error} +@item --no-ignore-command-error +Print warnings about subprocesses that terminated with a nonzero exit +code. @xref{Writing to an External Program}. + +@opsummary{no-null} +@item --no-null + +If the @option{--null} option was given previously, this option +cancels its effect, so that any following @option{--files-from} +options will expect their file lists to be newline-terminated. + +@opsummary{no-overwrite-dir} +@item --no-overwrite-dir + +Preserve metadata of existing directories when extracting files +from an archive. @xref{Overwrite Old Files}. + +@opsummary{no-quote-chars} +@item --no-quote-chars=@var{string} +Remove characters listed in @var{string} from the list of quoted +characters set by the previous @option{--quote-chars} option +(@pxref{quoting styles}). + +@opsummary{no-recursion} +@item --no-recursion + +With this option, @command{tar} will not recurse into directories. +@xref{recurse}. + +@opsummary{no-same-owner} +@item --no-same-owner +@itemx -o + +When extracting an archive, do not attempt to preserve the owner +specified in the @command{tar} archive. This the default behavior +for ordinary users. + +@opsummary{no-same-permissions} +@item --no-same-permissions + +When extracting an archive, subtract the user's umask from files from +the permissions specified in the archive. This is the default behavior +for ordinary users. + +@opsummary{no-seek} +@item --no-seek + +The archive media does not support seeks to arbitrary +locations. Usually @command{tar} determines automatically whether +the archive can be seeked or not. Use this option to disable this +mechanism. + +@opsummary{no-unquote} +@item --no-unquote +Treat all input file or member names literally, do not interpret +escape sequences. @xref{input name quoting}. + +@opsummary{no-wildcards} +@item --no-wildcards +Do not use wildcards. +@xref{controlling pattern-matching}. + +@opsummary{no-wildcards-match-slash} +@item --no-wildcards-match-slash +Wildcards do not match @samp{/}. +@xref{controlling pattern-matching}. + +@opsummary{null} +@item --null + +When @command{tar} is using the @option{--files-from} option, this option +instructs @command{tar} to expect file names terminated with @acronym{NUL}, so +@command{tar} can correctly work with file names that contain newlines. +@xref{nul}. + +@opsummary{numeric-owner} +@item --numeric-owner + +This option will notify @command{tar} that it should use numeric user +and group IDs when creating a @command{tar} file, rather than names. +@xref{Attributes}. + +@item -o +The function of this option depends on the action @command{tar} is +performing. When extracting files, @option{-o} is a synonym for +@option{--no-same-owner}, i.e., it prevents @command{tar} from +restoring ownership of files being extracted. + +When creating an archive, it is a synonym for +@option{--old-archive}. This behavior is for compatibility +with previous versions of @GNUTAR{}, and will be +removed in future releases. + +@xref{Changes}, for more information. + +@opsummary{occurrence} +@item --occurrence[=@var{number}] + +This option can be used in conjunction with one of the subcommands +@option{--delete}, @option{--diff}, @option{--extract} or +@option{--list} when a list of files is given either on the command +line or via @option{-T} option. + +This option instructs @command{tar} to process only the @var{number}th +occurrence of each named file. @var{Number} defaults to 1, so + +@smallexample +tar -x -f archive.tar --occurrence filename +@end smallexample + +@noindent +will extract the first occurrence of the member @file{filename} from @file{archive.tar} +and will terminate without scanning to the end of the archive. + +@opsummary{old-archive} +@item --old-archive +Synonym for @option{--format=v7}. + +@opsummary{one-file-system} +@item --one-file-system +Used when creating an archive. Prevents @command{tar} from recursing into +directories that are on different file systems from the current +directory. + +@opsummary{one-top-level} +@item --one-top-level +Tells @command{tar} to create a new directory beneath the extraction directory +(or the one passed to @option{-C}) and use it to guard against tarbombs. The +name of the new directory will be equal to the name of the archive with the +extension stripped off. If any archive names (after transformations from +@option{--transform} and @option{--strip-components}) do not already begin with +it, the new directory will be prepended to the names immediately before +extraction. Recognized extensions are @samp{.tar}, @samp{.taz}, @samp{.tbz}, +@samp{.tb2}, @samp{.tgz}, @samp{.tlz} and @samp{.txz}. + +@opsummary{overwrite} +@item --overwrite + +Overwrite existing files and directory metadata when extracting files +from an archive. @xref{Overwrite Old Files}. + +@opsummary{overwrite-dir} +@item --overwrite-dir + +Overwrite the metadata of existing directories when extracting files +from an archive. @xref{Overwrite Old Files}. + +@opsummary{owner} +@item --owner=@var{user} + +Specifies that @command{tar} should use @var{user} as the owner of members +when creating archives, instead of the user associated with the source +file. @var{user} can specify a symbolic name, or a numeric +@acronym{ID}, or both as @var{name}:@var{id}. +@xref{override}. + +This option does not affect extraction from archives. + +@opsummary{pax-option} +@item --pax-option=@var{keyword-list} +This option enables creation of the archive in @acronym{POSIX.1-2001} +format (@pxref{posix}) and modifies the way @command{tar} handles the +extended header keywords. @var{Keyword-list} is a comma-separated +list of keyword options. @xref{PAX keywords}, for a detailed +discussion. + +@opsummary{portability} +@item --portability +@itemx --old-archive +Synonym for @option{--format=v7}. + +@opsummary{posix} +@item --posix +Same as @option{--format=posix}. + +@opsummary{preserve} +@item --preserve + +Synonymous with specifying both @option{--preserve-permissions} and +@option{--same-order}. @xref{Setting Access Permissions}. + +@opsummary{preserve-order} +@item --preserve-order + +(See @option{--same-order}; @pxref{Reading}.) + +@opsummary{preserve-permissions} +@opsummary{same-permissions} +@item --preserve-permissions +@itemx --same-permissions +@itemx -p + +When @command{tar} is extracting an archive, it normally subtracts the +users' umask from the permissions specified in the archive and uses +that number as the permissions to create the destination file. +Specifying this option instructs @command{tar} that it should use the +permissions directly from the archive. @xref{Setting Access Permissions}. + +@opsummary{quote-chars} +@item --quote-chars=@var{string} +Always quote characters from @var{string}, even if the selected +quoting style would not quote them (@pxref{quoting styles}). + +@opsummary{quoting-style} +@item --quoting-style=@var{style} +Set quoting style to use when printing member and file names +(@pxref{quoting styles}). Valid @var{style} values are: +@code{literal}, @code{shell}, @code{shell-always}, @code{c}, +@code{escape}, @code{locale}, and @code{clocale}. Default quoting +style is @code{escape}, unless overridden while configuring the +package. + +@opsummary{read-full-records} +@item --read-full-records +@itemx -B + +Specifies that @command{tar} should reblock its input, for reading +from pipes on systems with buggy implementations. @xref{Reading}. + +@opsummary{record-size} +@item --record-size=@var{size}[@var{suf}] + +Instructs @command{tar} to use @var{size} bytes per record when accessing the +archive. The argument can be suffixed with a @dfn{size suffix}, e.g. +@option{--record-size=10K} for 10 Kilobytes. @xref{size-suffixes}, +for a list of valid suffixes. @xref{Blocking Factor}, for a detailed +description of this option. + +@opsummary{recursion} +@item --recursion + +With this option, @command{tar} recurses into directories (default). +@xref{recurse}. + +@opsummary{recursive-unlink} +@item --recursive-unlink + +Remove existing +directory hierarchies before extracting directories of the same name +from the archive. @xref{Recursive Unlink}. + +@opsummary{remove-files} +@item --remove-files + +Directs @command{tar} to remove the source file from the file system after +appending it to an archive. @xref{remove files}. + +@opsummary{restrict} +@item --restrict + +Disable use of some potentially harmful @command{tar} options. +Currently this option disables shell invocation from multi-volume menu +(@pxref{Using Multiple Tapes}). + +@opsummary{rmt-command} +@item --rmt-command=@var{cmd} + +Notifies @command{tar} that it should use @var{cmd} instead of +the default @file{/usr/libexec/rmt} (@pxref{Remote Tape Server}). + +@opsummary{rsh-command} +@item --rsh-command=@var{cmd} + +Notifies @command{tar} that is should use @var{cmd} to communicate with remote +devices. @xref{Device}. + +@opsummary{same-order} +@item --same-order +@itemx --preserve-order +@itemx -s + +This option is an optimization for @command{tar} when running on machines with +small amounts of memory. It informs @command{tar} that the list of file +arguments has already been sorted to match the order of files in the +archive. @xref{Reading}. + +@opsummary{same-owner} +@item --same-owner + +When extracting an archive, @command{tar} will attempt to preserve the owner +specified in the @command{tar} archive with this option present. +This is the default behavior for the superuser; this option has an +effect only for ordinary users. @xref{Attributes}. + +@opsummary{same-permissions} +@item --same-permissions + +(See @option{--preserve-permissions}; @pxref{Setting Access Permissions}.) + +@opsummary{seek} +@item --seek +@itemx -n + +Assume that the archive media supports seeks to arbitrary +locations. Usually @command{tar} determines automatically whether +the archive can be seeked or not. This option is intended for use +in cases when such recognition fails. It takes effect only if the +archive is open for reading (e.g. with @option{--list} or +@option{--extract} options). + +@opsummary{show-defaults} +@item --show-defaults + +Displays the default options used by @command{tar} and exits +successfully. This option is intended for use in shell scripts. +Here is an example of what you can see using this option: + +@smallexample +$ @kbd{tar --show-defaults} +--format=gnu -f- -b20 --quoting-style=escape +--rmt-command=/usr/libexec/rmt --rsh-command=/usr/bin/rsh +@end smallexample + +@noindent +Notice, that this option outputs only one line. The example output +above has been split to fit page boundaries. @xref{defaults}. + +@opsummary{show-omitted-dirs} +@item --show-omitted-dirs + +Instructs @command{tar} to mention the directories it is skipping when +operating on a @command{tar} archive. @xref{show-omitted-dirs}. + +@opsummary{show-snapshot-field-ranges} +@item --show-snapshot-field-ranges + +Displays the range of values allowed by this version of @command{tar} +for each field in the snapshot file, then exits successfully. +@xref{Snapshot Files}. + +@opsummary{show-transformed-names} +@opsummary{show-stored-names} +@item --show-transformed-names +@itemx --show-stored-names + +Display file or member names after applying any transformations +(@pxref{transform}). In particular, when used in conjunction with one of +the archive creation operations it instructs @command{tar} to list the +member names stored in the archive, as opposed to the actual file +names. @xref{listing member and file names}. + +@opsummary{skip-old-files} +@item --skip-old-files + +Do not overwrite existing files when extracting files from an +archive. @xref{Keep Old Files}. + +This option differs from @option{--keep-old-files} in that it does not +treat such files as an error, instead it just silently avoids +overwriting them. + +The @option{--warning=existing-file} option can be used together with +this option to produce warning messages about existing old files +(@pxref{warnings}). + +@opsummary{sparse} +@item --sparse +@itemx -S + +Invokes a @acronym{GNU} extension when adding files to an archive that handles +sparse files efficiently. @xref{sparse}. + +@opsummary{sparse-version} +@item --sparse-version=@var{version} + +Specifies the @dfn{format version} to use when archiving sparse +files. Implies @option{--sparse}. @xref{sparse}. For the description +of the supported sparse formats, @xref{Sparse Formats}. + +@opsummary{starting-file} +@item --starting-file=@var{name} +@itemx -K @var{name} + +This option affects extraction only; @command{tar} will skip extracting +files in the archive until it finds one that matches @var{name}. +@xref{Scarce}. + +@opsummary{strip-components} +@item --strip-components=@var{number} +Strip given @var{number} of leading components from file names before +extraction. For example, if archive @file{archive.tar} contained +@file{/some/file/name}, then running + +@smallexample +tar --extract --file archive.tar --strip-components=2 +@end smallexample + +@noindent +would extract this file to file @file{name}. + +@opsummary{suffix} +@item --suffix=@var{suffix} + +Alters the suffix @command{tar} uses when backing up files from the default +@samp{~}. @xref{backup}. + +@opsummary{tape-length} +@item --tape-length=@var{num}[@var{suf}] +@itemx -L @var{num}[@var{suf}] + +Specifies the length of tapes that @command{tar} is writing as being +@w{@var{num} x 1024} bytes long. If optional @var{suf} is given, it +specifies a multiplicative factor to be used instead of 1024. For +example, @samp{-L2M} means 2 megabytes. @xref{size-suffixes}, for a +list of allowed suffixes. @xref{Using Multiple Tapes}, for a detailed +discussion of this option. + +@opsummary{test-label} +@item --test-label + +Reads the volume label. If an argument is specified, test whether it +matches the volume label. @xref{--test-label option}. + +@opsummary{to-command} +@item --to-command=@var{command} + +During extraction @command{tar} will pipe extracted files to the +standard input of @var{command}. @xref{Writing to an External Program}. + +@opsummary{to-stdout} +@item --to-stdout +@itemx -O + +During extraction, @command{tar} will extract files to stdout rather +than to the file system. @xref{Writing to Standard Output}. + +@opsummary{totals} +@item --totals[=@var{signo}] + +Displays the total number of bytes transferred when processing an +archive. If an argument is given, these data are displayed on +request, when signal @var{signo} is delivered to @command{tar}. +@xref{totals}. + +@opsummary{touch} +@item --touch +@itemx -m + +Sets the data modification time of extracted files to the extraction time, +rather than the data modification time stored in the archive. +@xref{Data Modification Times}. + +@opsummary{transform} +@opsummary{xform} +@item --transform=@var{sed-expr} +@itemx --xform=@var{sed-expr} +Transform file or member names using @command{sed} replacement expression +@var{sed-expr}. For example, + +@smallexample +$ @kbd{tar cf archive.tar --transform 's,^\./,usr/,' .} +@end smallexample + +@noindent +will add to @file{archive} files from the current working directory, +replacing initial @samp{./} prefix with @samp{usr/}. For the detailed +discussion, @xref{transform}. + +To see transformed member names in verbose listings, use +@option{--show-transformed-names} option +(@pxref{show-transformed-names}). + +@opsummary{uncompress} +@item --uncompress + +(See @option{--compress}, @pxref{gzip}) + +@opsummary{ungzip} +@item --ungzip + +(See @option{--gzip}, @pxref{gzip}) + +@opsummary{unlink-first} +@item --unlink-first +@itemx -U + +Directs @command{tar} to remove the corresponding file from the file +system before extracting it from the archive. @xref{Unlink First}. + +@opsummary{unquote} +@item --unquote +Enable unquoting input file or member names (default). @xref{input +name quoting}. + +@opsummary{use-compress-program} +@item --use-compress-program=@var{prog} +@itemx -I=@var{prog} + +Instructs @command{tar} to access the archive through @var{prog}, which is +presumed to be a compression program of some sort. @xref{gzip}. + +@opsummary{utc} +@item --utc + +Display file modification dates in @acronym{UTC}. This option implies +@option{--verbose}. + +@opsummary{verbose} +@item --verbose +@itemx -v + +Specifies that @command{tar} should be more verbose about the +operations it is performing. This option can be specified multiple +times for some operations to increase the amount of information displayed. +@xref{verbose}. + +@opsummary{verify} +@item --verify +@itemx -W + +Verifies that the archive was correctly written when creating an +archive. @xref{verify}. + +@opsummary{version} +@item --version + +Print information about the program's name, version, origin and legal +status, all on standard output, and then exit successfully. +@xref{help}. + +@opsummary{volno-file} +@item --volno-file=@var{file} + +Used in conjunction with @option{--multi-volume}. @command{tar} will +keep track of which volume of a multi-volume archive it is working in +@var{file}. @xref{volno-file}. + +@opsummary{warning} +@item --warning=@var{keyword} + +Enable or disable warning messages identified by @var{keyword}. The +messages are suppressed if @var{keyword} is prefixed with @samp{no-}. +@xref{warnings}. + +@opsummary{wildcards} +@item --wildcards +Use wildcards when matching member names with patterns. +@xref{controlling pattern-matching}. + +@opsummary{wildcards-match-slash} +@item --wildcards-match-slash +Wildcards match @samp{/}. +@xref{controlling pattern-matching}. + +@opsummary{xz} +@item --xz +@itemx -J +Use @command{xz} for compressing or decompressing the archives. @xref{gzip}. + +@end table + +@node Short Option Summary +@subsection Short Options Cross Reference + +Here is an alphabetized list of all of the short option forms, matching +them with the equivalent long option. + +@multitable @columnfractions 0.20 0.80 +@headitem Short Option @tab Reference + +@item -A @tab @ref{--concatenate}. + +@item -B @tab @ref{--read-full-records}. + +@item -C @tab @ref{--directory}. + +@item -F @tab @ref{--info-script}. + +@item -G @tab @ref{--incremental}. + +@item -J @tab @ref{--xz}. + +@item -K @tab @ref{--starting-file}. + +@item -L @tab @ref{--tape-length}. + +@item -M @tab @ref{--multi-volume}. + +@item -N @tab @ref{--newer}. + +@item -O @tab @ref{--to-stdout}. + +@item -P @tab @ref{--absolute-names}. + +@item -R @tab @ref{--block-number}. + +@item -S @tab @ref{--sparse}. + +@item -T @tab @ref{--files-from}. + +@item -U @tab @ref{--unlink-first}. + +@item -V @tab @ref{--label}. + +@item -W @tab @ref{--verify}. + +@item -X @tab @ref{--exclude-from}. + +@item -Z @tab @ref{--compress}. + +@item -b @tab @ref{--blocking-factor}. + +@item -c @tab @ref{--create}. + +@item -d @tab @ref{--compare}. + +@item -f @tab @ref{--file}. + +@item -g @tab @ref{--listed-incremental}. + +@item -h @tab @ref{--dereference}. + +@item -i @tab @ref{--ignore-zeros}. + +@item -j @tab @ref{--bzip2}. + +@item -k @tab @ref{--keep-old-files}. + +@item -l @tab @ref{--check-links}. + +@item -m @tab @ref{--touch}. + +@item -o @tab When creating, @ref{--no-same-owner}, when extracting --- +@ref{--portability}. + +The latter usage is deprecated. It is retained for compatibility with +the earlier versions of @GNUTAR{}. In future releases +@option{-o} will be equivalent to @option{--no-same-owner} only. + +@item -p @tab @ref{--preserve-permissions}. + +@item -r @tab @ref{--append}. + +@item -s @tab @ref{--same-order}. + +@item -t @tab @ref{--list}. + +@item -u @tab @ref{--update}. + +@item -v @tab @ref{--verbose}. + +@item -w @tab @ref{--interactive}. + +@item -x @tab @ref{--extract}. + +@item -z @tab @ref{--gzip}. + +@end multitable + +@node help +@section @GNUTAR{} documentation + +@cindex Getting program version number +@opindex version +@cindex Version of the @command{tar} program +Being careful, the first thing is really checking that you are using +@GNUTAR{}, indeed. The @option{--version} option +causes @command{tar} to print information about its name, version, +origin and legal status, all on standard output, and then exit +successfully. For example, @w{@samp{tar --version}} might print: + +@smallexample +tar (GNU tar) @value{VERSION} +Copyright (C) 2013 Free Software Foundation, Inc. +License GPLv3+: GNU GPL version 3 or later . +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. + +Written by John Gilmore and Jay Fenlason. +@end smallexample + +@noindent +The first occurrence of @samp{tar} in the result above is the program +name in the package (for example, @command{rmt} is another program), +while the second occurrence of @samp{tar} is the name of the package +itself, containing possibly many programs. The package is currently +named @samp{tar}, after the name of the main program it +contains@footnote{There are plans to merge the @command{cpio} and +@command{tar} packages into a single one which would be called +@code{paxutils}. So, who knows if, one of this days, the +@option{--version} would not output @w{@samp{tar (@acronym{GNU} +paxutils) 3.2}}.}. + +@cindex Obtaining help +@cindex Listing all @command{tar} options +@xopindex{help, introduction} +Another thing you might want to do is checking the spelling or meaning +of some particular @command{tar} option, without resorting to this +manual, for once you have carefully read it. @GNUTAR{} +has a short help feature, triggerable through the +@option{--help} option. By using this option, @command{tar} will +print a usage message listing all available options on standard +output, then exit successfully, without doing anything else and +ignoring all other options. Even if this is only a brief summary, it +may be several screens long. So, if you are not using some kind of +scrollable window, you might prefer to use something like: + +@smallexample +$ @kbd{tar --help | less} +@end smallexample + +@noindent +presuming, here, that you like using @command{less} for a pager. Other +popular pagers are @command{more} and @command{pg}. If you know about some +@var{keyword} which interests you and do not want to read all the +@option{--help} output, another common idiom is doing: + +@smallexample +tar --help | grep @var{keyword} +@end smallexample + +@noindent +for getting only the pertinent lines. Notice, however, that some +@command{tar} options have long description lines and the above +command will list only the first of them. + +The exact look of the option summary displayed by @kbd{tar --help} is +configurable. @xref{Configuring Help Summary}, for a detailed description. + +@opindex usage +If you only wish to check the spelling of an option, running @kbd{tar +--usage} may be a better choice. This will display a terse list of +@command{tar} options without accompanying explanations. + +The short help output is quite succinct, and you might have to get +back to the full documentation for precise points. If you are reading +this paragraph, you already have the @command{tar} manual in some +form. This manual is available in a variety of forms from +@url{http://www.gnu.org/software/tar/manual}. It may be printed out of the @GNUTAR{} +distribution, provided you have @TeX{} already installed somewhere, +and a laser printer around. Just configure the distribution, execute +the command @w{@samp{make dvi}}, then print @file{doc/tar.dvi} the +usual way (contact your local guru to know how). If @GNUTAR{} +has been conveniently installed at your place, this +manual is also available in interactive, hypertextual form as an Info +file. Just call @w{@samp{info tar}} or, if you do not have the +@command{info} program handy, use the Info reader provided within +@acronym{GNU} Emacs, calling @samp{tar} from the main Info menu. + +There is currently no @code{man} page for @GNUTAR{}. +If you observe such a @code{man} page on the system you are running, +either it does not belong to @GNUTAR{}, or it has not +been produced by @acronym{GNU}. Some package maintainers convert +@kbd{tar --help} output to a man page, using @command{help2man}. In +any case, please bear in mind that the authoritative source of +information about @GNUTAR{} is this Texinfo documentation. + +@node defaults +@section Obtaining @GNUTAR{} default values + +@opindex show-defaults +@GNUTAR{} has some predefined defaults that are used when you do not +explicitly specify another values. To obtain a list of such +defaults, use @option{--show-defaults} option. This will output the +values in the form of @command{tar} command line options: + +@smallexample +@group +$ @kbd{tar --show-defaults} +--format=gnu -f- -b20 --quoting-style=escape +--rmt-command=/etc/rmt --rsh-command=/usr/bin/rsh +@end group +@end smallexample + +@noindent +Notice, that this option outputs only one line. The example output above +has been split to fit page boundaries. + +@noindent +The above output shows that this version of @GNUTAR{} defaults to +using @samp{gnu} archive format (@pxref{Formats}), it uses standard +output as the archive, if no @option{--file} option has been given +(@pxref{file tutorial}), the default blocking factor is 20 +(@pxref{Blocking Factor}). It also shows the default locations where +@command{tar} will look for @command{rmt} and @command{rsh} binaries. + +@node verbose +@section Checking @command{tar} progress + +Typically, @command{tar} performs most operations without reporting any +information to the user except error messages. When using @command{tar} +with many options, particularly ones with complicated or +difficult-to-predict behavior, it is possible to make serious mistakes. +@command{tar} provides several options that make observing @command{tar} +easier. These options cause @command{tar} to print information as it +progresses in its job, and you might want to use them just for being +more careful about what is going on, or merely for entertaining +yourself. If you have encountered a problem when operating on an +archive, however, you may need more information than just an error +message in order to solve the problem. The following options can be +helpful diagnostic tools. + +@cindex Verbose operation +@opindex verbose +Normally, the @option{--list} (@option{-t}) command to list an archive +prints just the file names (one per line) and the other commands are +silent. When used with most operations, the @option{--verbose} +(@option{-v}) option causes @command{tar} to print the name of each +file or archive member as it is processed. This and the other options +which make @command{tar} print status information can be useful in +monitoring @command{tar}. + +With @option{--create} or @option{--extract}, @option{--verbose} used +once just prints the names of the files or members as they are processed. +Using it twice causes @command{tar} to print a longer listing +(@xref{verbose member listing}, for the description) for each member. +Since @option{--list} already prints the names of the members, +@option{--verbose} used once with @option{--list} causes @command{tar} +to print an @samp{ls -l} type listing of the files in the archive. +The following examples both extract members with long list output: + +@smallexample +$ @kbd{tar --extract --file=archive.tar --verbose --verbose} +$ @kbd{tar xvvf archive.tar} +@end smallexample + +Verbose output appears on the standard output except when an archive is +being written to the standard output, as with @samp{tar --create +--file=- --verbose} (@samp{tar cvf -}, or even @samp{tar cv}---if the +installer let standard output be the default archive). In that case +@command{tar} writes verbose output to the standard error stream. + +If @option{--index-file=@var{file}} is specified, @command{tar} sends +verbose output to @var{file} rather than to standard output or standard +error. + +@anchor{totals} +@cindex Obtaining total status information +@opindex totals +The @option{--totals} option causes @command{tar} to print on the +standard error the total amount of bytes transferred when processing +an archive. When creating or appending to an archive, this option +prints the number of bytes written to the archive and the average +speed at which they have been written, e.g.: + +@smallexample +@group +$ @kbd{tar -c -f archive.tar --totals /home} +Total bytes written: 7924664320 (7.4GiB, 85MiB/s) +@end group +@end smallexample + +When reading an archive, this option displays the number of bytes +read: + +@smallexample +@group +$ @kbd{tar -x -f archive.tar --totals} +Total bytes read: 7924664320 (7.4GiB, 95MiB/s) +@end group +@end smallexample + +Finally, when deleting from an archive, the @option{--totals} option +displays both numbers plus number of bytes removed from the archive: + +@smallexample +@group +$ @kbd{tar --delete -f foo.tar --totals --wildcards '*~'} +Total bytes read: 9543680 (9.2MiB, 201MiB/s) +Total bytes written: 3829760 (3.7MiB, 81MiB/s) +Total bytes deleted: 1474048 +@end group +@end smallexample + +You can also obtain this information on request. When +@option{--totals} is used with an argument, this argument is +interpreted as a symbolic name of a signal, upon delivery of which the +statistics is to be printed: + +@table @option +@item --totals=@var{signo} +Print statistics upon delivery of signal @var{signo}. Valid arguments +are: @code{SIGHUP}, @code{SIGQUIT}, @code{SIGINT}, @code{SIGUSR1} and +@code{SIGUSR2}. Shortened names without @samp{SIG} prefix are also +accepted. +@end table + +Both forms of @option{--totals} option can be used simultaneously. +Thus, @kbd{tar -x --totals --totals=USR1} instructs @command{tar} to +extract all members from its default archive and print statistics +after finishing the extraction, as well as when receiving signal +@code{SIGUSR1}. + +@anchor{Progress information} +@cindex Progress information +The @option{--checkpoint} option prints an occasional message +as @command{tar} reads or writes the archive. It is designed for +those who don't need the more detailed (and voluminous) output of +@option{--block-number} (@option{-R}), but do want visual confirmation +that @command{tar} is actually making forward progress. By default it +prints a message each 10 records read or written. This can be changed +by giving it a numeric argument after an equal sign: + +@smallexample +$ @kbd{tar -c --checkpoint=1000} /var +tar: Write checkpoint 1000 +tar: Write checkpoint 2000 +tar: Write checkpoint 3000 +@end smallexample + +This example shows the default checkpoint message used by +@command{tar}. If you place a dot immediately after the equal +sign, it will print a @samp{.} at each checkpoint@footnote{This is +actually a shortcut for @option{--checkpoint=@var{n} +--checkpoint-action=dot}. @xref{checkpoints, dot}.}. For example: + +@smallexample +$ @kbd{tar -c --checkpoint=.1000} /var +... +@end smallexample + +The @option{--checkpoint} option provides a flexible mechanism for +executing arbitrary actions upon hitting checkpoints, see the next +section (@pxref{checkpoints}), for more information on it. + +@opindex show-omitted-dirs +@anchor{show-omitted-dirs} +The @option{--show-omitted-dirs} option, when reading an archive---with +@option{--list} or @option{--extract}, for example---causes a message +to be printed for each directory in the archive which is skipped. +This happens regardless of the reason for skipping: the directory might +not have been named on the command line (implicitly or explicitly), +it might be excluded by the use of the +@option{--exclude=@var{pattern}} option, or some other reason. + +@opindex block-number +@cindex Block number where error occurred +@anchor{block-number} +If @option{--block-number} (@option{-R}) is used, @command{tar} prints, along with +every message it would normally produce, the block number within the +archive where the message was triggered. Also, supplementary messages +are triggered when reading blocks full of NULs, or when hitting end of +file on the archive. As of now, if the archive is properly terminated +with a NUL block, the reading of the file may stop before end of file +is met, so the position of end of file will not usually show when +@option{--block-number} (@option{-R}) is used. Note that @GNUTAR{} +drains the archive before exiting when reading the +archive from a pipe. + +@cindex Error message, block number of +This option is especially useful when reading damaged archives, since +it helps pinpoint the damaged sections. It can also be used with +@option{--list} (@option{-t}) when listing a file-system backup tape, allowing you to +choose among several backup tapes when retrieving a file later, in +favor of the tape where the file appears earliest (closest to the +front of the tape). @xref{backup}. + +@node checkpoints +@section Checkpoints +@cindex checkpoints, defined +@opindex checkpoint +@opindex checkpoint-action + +A @dfn{checkpoint} is a moment of time before writing @var{n}th record to +the archive (a @dfn{write checkpoint}), or before reading @var{n}th record +from the archive (a @dfn{read checkpoint}). Checkpoints allow to +periodically execute arbitrary actions. + +The checkpoint facility is enabled using the following option: + +@table @option +@xopindex{checkpoint, defined} +@item --checkpoint[=@var{n}] +Schedule checkpoints before writing or reading each @var{n}th record. +The default value for @var{n} is 10. +@end table + +A list of arbitrary @dfn{actions} can be executed at each checkpoint. +These actions include: pausing, displaying textual messages, and +executing arbitrary external programs. Actions are defined using +the @option{--checkpoint-action} option. + +@table @option +@xopindex{checkpoint-action, defined} +@item --checkpoint-action=@var{action} +Execute an @var{action} at each checkpoint. +@end table + +@cindex @code{echo}, checkpoint action +The simplest value of @var{action} is @samp{echo}. It instructs +@command{tar} to display the default message on the standard error +stream upon arriving at each checkpoint. The default message is (in +@acronym{POSIX} locale) @samp{Write checkpoint @var{n}}, for write +checkpoints, and @samp{Read checkpoint @var{n}}, for read checkpoints. +Here, @var{n} represents ordinal number of the checkpoint. + +In another locales, translated versions of this message are used. + +This is the default action, so running: + +@smallexample +$ @kbd{tar -c --checkpoint=1000 --checkpoint-action=echo} /var +@end smallexample + +@noindent +is equivalent to: + +@smallexample +$ @kbd{tar -c --checkpoint=1000} /var +@end smallexample + +The @samp{echo} action also allows to supply a customized message. +You do so by placing an equals sign and the message right after it, +e.g.: + +@smallexample +--checkpoint-action="echo=Hit %s checkpoint #%u" +@end smallexample + +The @samp{%s} and @samp{%u} in the above example are +@dfn{format specifiers}. The @samp{%s} specifier is replaced with +the @dfn{type} of the checkpoint: @samp{write} or +@samp{read} (or a corresponding translated version in locales other +than @acronym{POSIX}). The @samp{%u} specifier is replaced with +the ordinal number of the checkpoint. Thus, the above example could +produce the following output when used with the @option{--create} +option: + +@smallexample +tar: Hit write checkpoint #10 +tar: Hit write checkpoint #20 +tar: Hit write checkpoint #30 +@end smallexample + +The complete list of available format specifiers follows. Some of +them can take optional arguments. These arguments, if given, are +supplied in curly braces between the percent sign and the specifier +letter. + +@table @samp +@item %s +Print type of the checkpoint (@samp{write} or @samp{read}). + +@item %u +Print number of the checkpoint. + +@item %@{r,w,d@}T +Print number of bytes transferred so far and approximate transfer +speed. Optional arguments supply prefixes to be used before number +of bytes read, written and deleted, correspondingly. If absent, +they default to @samp{R}. @samp{W}, @samp{D}. Any or all of them can +be omitted, so, that e.g. @samp{%@{@}T} means to print corresponding +statistics without any prefixes. Any surplus arguments, if present, +are silently ignored. + +@example +$ @kbd{tar --delete -f f.tar --checkpoint-action=echo="#%u: %T" main.c} +tar: #1: R: 0 (0B, 0B/s),W: 0 (0B, 0B/s),D: 0 +tar: #2: R: 10240 (10KiB, 19MiB/s),W: 0 (0B, 0B/s),D: 10240 +@end example + +@noindent +See also the @samp{totals} action, described below. + +@item %@{@var{fmt}@}t +Output current local time using @var{fmt} as format for @command{strftime} +(@pxref{strftime, strftime,,strftime(3), strftime(3) man page}). The +@samp{@{@var{fmt}@}} part is optional. If not present, the default +format is @samp{%c}, i.e. the preferred date and time representation +for the current locale. + +@item %@{@var{n}@}* +Pad output with spaces to the @var{n}th column. If the +@samp{@{@var{n}@}} part is omitted, the current screen width +is assumed. + +@item %@var{c} +This is a shortcut for @samp{%@{%Y-%m-%d %H:%M:%S@}t: %ds, %@{read,wrote@}T%*\r}, +intended mainly for use with @samp{ttyout} action (see below). +@end table + +Aside from format expansion, the message string is subject to +@dfn{unquoting}, during which the backslash @dfn{escape sequences} are +replaced with their corresponding @acronym{ASCII} characters +(@pxref{escape sequences}). E.g. the following action will produce an +audible bell and the message described above at each checkpoint: + +@smallexample +--checkpoint-action='echo=\aHit %s checkpoint #%u' +@end smallexample + +@cindex @code{bell}, checkpoint action +There is also a special action which produces an audible signal: +@samp{bell}. It is not equivalent to @samp{echo='\a'}, because +@samp{bell} sends the bell directly to the console (@file{/dev/tty}), +whereas @samp{echo='\a'} sends it to the standard error. + +@cindex @code{ttyout}, checkpoint action +The @samp{ttyout=@var{string}} action outputs @var{string} to +@file{/dev/tty}, so it can be used even if the standard output is +redirected elsewhere. The @var{string} is subject to the same +modifications as with @samp{echo} action. In contrast to the latter, +@samp{ttyout} does not prepend @command{tar} executable name to the +string, nor does it output a newline after it. For example, the +following action will print the checkpoint message at the same screen +line, overwriting any previous message: + +@smallexample +--checkpoint-action="ttyout=Hit %s checkpoint #%u%*\r" +@end smallexample + +@noindent +Notice the use of @samp{%*} specifier to clear out any eventual +remains of the prior output line. As as more complex example, +consider this: + +@smallexample +--checkpoint-action=ttyout='%@{%Y-%m-%d %H:%M:%S@}t (%d sec): #%u, %T%*\r' +@end smallexample + +@noindent +This prints the current local time, number of seconds expired since +tar was started, the checkpoint ordinal number, transferred bytes and +average computed I/O speed. + +@cindex @code{dot}, checkpoint action +Another available checkpoint action is @samp{dot} (or @samp{.}). It +instructs @command{tar} to print a single dot on the standard listing +stream, e.g.: + +@smallexample +$ @kbd{tar -c --checkpoint=1000 --checkpoint-action=dot} /var +... +@end smallexample + +For compatibility with previous @GNUTAR{} versions, this action can +be abbreviated by placing a dot in front of the checkpoint frequency, +as shown in the previous section. + +@cindex @code{totals}, checkpoint action +The @samp{totals} action prints the total number of bytes transferred +so far. The format of the data is the same as for the +@option{--totals} option (@pxref{totals}). See also @samp{%T} format +specifier of the @samp{echo} or @samp{ttyout} action. + +@cindex @code{sleep}, checkpoint action +Yet another action, @samp{sleep}, pauses @command{tar} for a specified +amount of seconds. The following example will stop for 30 seconds at each +checkpoint: + +@smallexample +$ @kbd{tar -c --checkpoint=1000 --checkpoint-action=sleep=30} +@end smallexample + +@anchor{checkpoint exec} +@cindex @code{exec}, checkpoint action +Finally, the @code{exec} action executes a given external command. +For example: + +@smallexample +$ @kbd{tar -c --checkpoint=1000 --checkpoint-action=exec=/sbin/cpoint} +@end smallexample + +The supplied command can be any valid command invocation, with or +without additional command line arguments. If it does contain +arguments, don't forget to quote it to prevent it from being split by +the shell. @xref{external, Running External Commands}, for more detail. + +The command gets a copy of @command{tar}'s environment plus the +following variables: + +@table @env +@vrindex TAR_VERSION, checkpoint script environment +@item TAR_VERSION +@GNUTAR{} version number. + +@vrindex TAR_ARCHIVE, checkpoint script environment +@item TAR_ARCHIVE +The name of the archive @command{tar} is processing. + +@vrindex TAR_BLOCKING_FACTOR, checkpoint script environment +@item TAR_BLOCKING_FACTOR +Current blocking factor (@pxref{Blocking}). + +@vrindex TAR_CHECKPOINT, checkpoint script environment +@item TAR_CHECKPOINT +Number of the checkpoint. + +@vrindex TAR_SUBCOMMAND, checkpoint script environment +@item TAR_SUBCOMMAND +A short option describing the operation @command{tar} is executing. +@xref{Operations}, for a complete list of subcommand options. + +@vrindex TAR_FORMAT, checkpoint script environment +@item TAR_FORMAT +Format of the archive being processed. @xref{Formats}, for a complete +list of archive format names. +@end table + +These environment variables can also be passed as arguments to the +command, provided that they are properly escaped, for example: + +@smallexample +@kbd{tar -c -f arc.tar \ + --checkpoint-action='exec=/sbin/cpoint $TAR_FILENAME'} +@end smallexample + +@noindent +Notice single quotes to prevent variable names from being expanded by +the shell when invoking @command{tar}. + +Any number of actions can be defined, by supplying several +@option{--checkpoint-action} options in the command line. For +example, the command below displays two messages, pauses +execution for 30 seconds and executes the @file{/sbin/cpoint} script: + +@example +@group +$ @kbd{tar -c -f arc.tar \ + --checkpoint-action='\aecho=Hit %s checkpoint #%u' \ + --checkpoint-action='echo=Sleeping for 30 seconds' \ + --checkpoint-action='sleep=30' \ + --checkpoint-action='exec=/sbin/cpoint'} +@end group +@end example + +This example also illustrates the fact that +@option{--checkpoint-action} can be used without +@option{--checkpoint}. In this case, the default checkpoint frequency +(at each 10th record) is assumed. + +@node warnings +@section Controlling Warning Messages + +Sometimes, while performing the requested task, @GNUTAR{} notices +some conditions that are not exactly errors, but which the user +should be aware of. When this happens, @command{tar} issues a +@dfn{warning message} describing the condition. Warning messages +are output to the standard error and they do not affect the exit +code of @command{tar} command. + +@xopindex{warning, explained} +@GNUTAR{} allows the user to suppress some or all of its warning +messages: + +@table @option +@item --warning=@var{keyword} +Control display of the warning messages identified by @var{keyword}. +If @var{keyword} starts with the prefix @samp{no-}, such messages are +suppressed. Otherwise, they are enabled. + +Multiple @option{--warning} messages accumulate. + +The tables below list allowed values for @var{keyword} along with the +warning messages they control. +@end table + +@subheading Keywords controlling @command{tar} operation +@table @asis +@kwindex all +@item all +Enable all warning messages. This is the default. +@kwindex none +@item none +Disable all warning messages. +@kwindex filename-with-nuls +@cindex @samp{file name read contains nul character}, warning message +@item filename-with-nuls +@samp{%s: file name read contains nul character} +@kwindex alone-zero-block +@cindex @samp{A lone zero block at}, warning message +@item alone-zero-block +@samp{A lone zero block at %s} +@end table + +@subheading Keywords applicable for @command{tar --create} +@table @asis +@kwindex cachedir +@cindex @samp{contains a cache directory tag}, warning message +@item cachedir +@samp{%s: contains a cache directory tag %s; %s} +@kwindex file-shrank +@cindex @samp{File shrank by %s bytes}, warning message +@item file-shrank +@samp{%s: File shrank by %s bytes; padding with zeros} +@kwindex xdev +@cindex @samp{file is on a different filesystem}, warning message +@item xdev +@samp{%s: file is on a different filesystem; not dumped} +@kwindex file-ignored +@cindex @samp{Unknown file type; file ignored}, warning message +@cindex @samp{socket ignored}, warning message +@cindex @samp{door ignored}, warning message +@item file-ignored +@samp{%s: Unknown file type; file ignored} +@*@samp{%s: socket ignored} +@*@samp{%s: door ignored} +@kwindex file-unchanged +@cindex @samp{file is unchanged; not dumped}, warning message +@item file-unchanged +@samp{%s: file is unchanged; not dumped} +@kwindex ignore-archive +@cindex @samp{file is the archive; not dumped}, warning message +@kwindex ignore-archive +@cindex @samp{file is the archive; not dumped}, warning message +@item ignore-archive +@samp{%s: file is the archive; not dumped} +@kwindex file-removed +@cindex @samp{File removed before we read it}, warning message +@item file-removed +@samp{%s: File removed before we read it} +@kwindex file-changed +@cindex @samp{file changed as we read it}, warning message +@item file-changed +@samp{%s: file changed as we read it} +@end table + +@subheading Keywords applicable for @command{tar --extract} +@table @asis +@kwindex timestamp +@cindex @samp{implausibly old time stamp %s}, warning message +@cindex @samp{time stamp %s is %s s in the future}, warning message +@item timestamp +@samp{%s: implausibly old time stamp %s} +@*@samp{%s: time stamp %s is %s s in the future} +@kwindex contiguous-cast +@cindex @samp{Extracting contiguous files as regular files}, warning message +@item contiguous-cast +@samp{Extracting contiguous files as regular files} +@kwindex symlink-cast +@cindex @samp{Attempting extraction of symbolic links as hard links}, warning message +@item symlink-cast +@samp{Attempting extraction of symbolic links as hard links} +@kwindex unknown-cast +@cindex @samp{Unknown file type '%c', extracted as normal file}, warning message +@item unknown-cast +@samp{%s: Unknown file type '%c', extracted as normal file} +@kwindex ignore-newer +@cindex @samp{Current %s is newer or same age}, warning message +@item ignore-newer +@samp{Current %s is newer or same age} +@kwindex unknown-keyword +@cindex @samp{Ignoring unknown extended header keyword '%s'}, warning message +@item unknown-keyword +@samp{Ignoring unknown extended header keyword '%s'} +@kwindex decompress-program +@item decompress-program +Controls verbose description of failures occurring when trying to run +alternative decompressor programs (@pxref{alternative decompression +programs}). This warning is disabled by default (unless +@option{--verbose} is used). A common example of what you can get +when using this warning is: + +@smallexample +$ @kbd{tar --warning=decompress-program -x -f archive.Z} +tar (child): cannot run compress: No such file or directory +tar (child): trying gzip +@end smallexample + +This means that @command{tar} first tried to decompress +@file{archive.Z} using @command{compress}, and, when that +failed, switched to @command{gzip}. +@kwindex record-size +@cindex @samp{Record size = %lu blocks}, warning message +@item record-size +@samp{Record size = %lu blocks} +@end table + +@subheading Keywords controlling incremental extraction: +@table @asis +@kwindex rename-directory +@cindex @samp{%s: Directory has been renamed from %s}, warning message +@cindex @samp{%s: Directory has been renamed}, warning message +@item rename-directory +@samp{%s: Directory has been renamed from %s} +@*@samp{%s: Directory has been renamed} +@kwindex new-directory +@cindex @samp{%s: Directory is new}, warning message +@item new-directory +@samp{%s: Directory is new} +@kwindex xdev +@cindex @samp{%s: directory is on a different device: not purging}, warning message +@item xdev +@samp{%s: directory is on a different device: not purging} +@kwindex bad-dumpdir +@cindex @samp{Malformed dumpdir: 'X' never used}, warning message +@item bad-dumpdir +@samp{Malformed dumpdir: 'X' never used} +@end table + +@node interactive +@section Asking for Confirmation During Operations +@cindex Interactive operation + +Typically, @command{tar} carries out a command without stopping for +further instructions. In some situations however, you may want to +exclude some files and archive members from the operation (for instance +if disk or storage space is tight). You can do this by excluding +certain files automatically (@pxref{Choosing}), or by performing +an operation interactively, using the @option{--interactive} (@option{-w}) option. +@command{tar} also accepts @option{--confirmation} for this option. + +@opindex interactive +When the @option{--interactive} (@option{-w}) option is specified, before +reading, writing, or deleting files, @command{tar} first prints a message +for each such file, telling what operation it intends to take, then asks +for confirmation on the terminal. The actions which require +confirmation include adding a file to the archive, extracting a file +from the archive, deleting a file from the archive, and deleting a file +from disk. To confirm the action, you must type a line of input +beginning with @samp{y}. If your input line begins with anything other +than @samp{y}, @command{tar} skips that file. + +If @command{tar} is reading the archive from the standard input, +@command{tar} opens the file @file{/dev/tty} to support the interactive communications. -<<< this aborts if you won't OK the working directory. this is a bug. -ringo -@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). +Verbose output is normally sent to standard output, separate from +other error messages. However, if the archive is produced directly +on standard output, then verbose output is mixed with errors on +@code{stderr}. Producing the archive on standard output may be used +as a way to avoid using disk space, when the archive is soon to be +consumed by another process reading it, say. Some people felt the need +of producing an archive on stdout, still willing to segregate between +verbose output and error output. A possible approach would be using a +named pipe to receive the archive, and having the consumer process to +read from that named pipe. This has the advantage of letting standard +output free to receive verbose output, all separate from errors. + +@node external +@section Running External Commands + +Certain @GNUTAR{} operations imply running external commands that you +supply on the command line. One of such operations is checkpointing, +described above (@pxref{checkpoint exec}). Another example of this +feature is the @option{-I} option, which allows you to supply the +program to use for compressing or decompressing the archive +(@pxref{use-compress-program}). + +Whenever such operation is requested, @command{tar} first splits the +supplied command into words much like the shell does. It then treats +the first word as the name of the program or the shell script to execute +and the rest of words as its command line arguments. The program, +unless given as an absolute file name, is searched in the shell's +@env{PATH}. + +Any additional information is normally supplied to external commands +in environment variables, specific to each particular operation. For +example, the @option{--checkpoint-action=exec} option, defines the +@env{TAR_ARCHIVE} variable to the name of the archive being worked +upon. You can, should the need be, use these variables in the +command line of the external command. For example: + +@smallexample +$ @kbd{tar -x -f archive.tar \ + --checkpoint=exec='printf "%04d in %32s\r" $TAR_CHECKPOINT $TAR_ARCHIVE'} +@end smallexample + +@noindent +This command prints for each checkpoint its number and the name of the +archive, using the same output line on the screen. + +Notice the use of single quotes to prevent variable names from being +expanded by the shell when invoking @command{tar}. + +@node operations +@chapter @GNUTAR{} Operations + +@menu +* Basic tar:: +* Advanced tar:: +* create options:: +* extract options:: +* backup:: +* Applications:: +* looking ahead:: +@end menu + +@node Basic tar +@section Basic @GNUTAR{} Operations + +The basic @command{tar} operations, @option{--create} (@option{-c}), +@option{--list} (@option{-t}) and @option{--extract} (@option{--get}, +@option{-x}), are currently presented and described in the tutorial +chapter of this manual. This section provides some complementary notes +for these operations. + +@table @option +@xopindex{create, complementary notes} +@item --create +@itemx -c + +Creating an empty archive would have some kind of elegance. One can +initialize an empty archive and later use @option{--append} +(@option{-r}) for adding all members. Some applications would not +welcome making an exception in the way of adding the first archive +member. On the other hand, many people reported that it is +dangerously too easy for @command{tar} to destroy a magnetic tape with +an empty archive@footnote{This is well described in @cite{Unix-haters +Handbook}, by Simson Garfinkel, Daniel Weise & Steven Strassmann, IDG +Books, ISBN 1-56884-203-1.}. The two most common errors are: + +@enumerate +@item +Mistakingly using @code{create} instead of @code{extract}, when the +intent was to extract the full contents of an archive. This error +is likely: keys @kbd{c} and @kbd{x} are right next to each other on +the QWERTY keyboard. Instead of being unpacked, the archive then +gets wholly destroyed. When users speak about @dfn{exploding} an +archive, they usually mean something else :-). + +@item +Forgetting the argument to @code{file}, when the intent was to create +an archive with a single file in it. This error is likely because a +tired user can easily add the @kbd{f} key to the cluster of option +letters, by the mere force of habit, without realizing the full +consequence of doing so. The usual consequence is that the single +file, which was meant to be saved, is rather destroyed. +@end enumerate + +So, recognizing the likelihood and the catastrophic nature of these +errors, @GNUTAR{} now takes some distance from elegance, and +cowardly refuses to create an archive when @option{--create} option is +given, there are no arguments besides options, and +@option{--files-from} (@option{-T}) option is @emph{not} used. To get +around the cautiousness of @GNUTAR{} and nevertheless create an +archive with nothing in it, one may still use, as the value for the +@option{--files-from} option, a file with no names in it, as shown in +the following commands: + +@smallexample +@kbd{tar --create --file=empty-archive.tar --files-from=/dev/null} +@kbd{tar -cf empty-archive.tar -T /dev/null} +@end smallexample + +@xopindex{extract, complementary notes} +@item --extract +@itemx --get +@itemx -x + +A socket is stored, within a @GNUTAR{} archive, as a pipe. + +@item @option{--list} (@option{-t}) + +@GNUTAR{} now shows dates as @samp{1996-08-30}, +while it used to show them as @samp{Aug 30 1996}. Preferably, +people should get used to ISO 8601 dates. Local American dates should +be made available again with full date localization support, once +ready. In the meantime, programs not being localizable for dates +should prefer international dates, that's really the way to go. + +Look up @url{http://www.cl.cam.ac.uk/@/~mgk25/@/iso-time.html} if you +are curious, it contains a detailed explanation of the ISO 8601 standard. + +@end table + +@node Advanced tar +@section Advanced @GNUTAR{} Operations + +Now that you have learned the basics of using @GNUTAR{}, you may want +to learn about further ways in which @command{tar} can help you. + +This chapter presents five, more advanced operations which you probably +won't use on a daily basis, but which serve more specialized functions. +We also explain the different styles of options and why you might want +to use one or another, or a combination of them in your @command{tar} +commands. Additionally, this chapter includes options which allow you to +define the output from @command{tar} more carefully, and provide help and +error correction in special circumstances. + +@FIXME{check this after the chapter is actually revised to make sure +it still introduces the info in the chapter correctly : ).} + +@menu +* Operations:: +* append:: +* update:: +* concatenate:: +* delete:: +* compare:: +@end menu + +@node Operations +@subsection The Five Advanced @command{tar} Operations + +@cindex basic operations +In the last chapter, you learned about the first three operations to +@command{tar}. This chapter presents the remaining five operations to +@command{tar}: @option{--append}, @option{--update}, @option{--concatenate}, +@option{--delete}, and @option{--compare}. + +You are not likely to use these operations as frequently as those +covered in the last chapter; however, since they perform specialized +functions, they are quite useful when you do need to use them. We +will give examples using the same directory and files that you created +in the last chapter. As you may recall, the directory is called +@file{practice}, the files are @samp{jazz}, @samp{blues}, @samp{folk}, +and the two archive files you created are +@samp{collection.tar} and @samp{music.tar}. + +We will also use the archive files @samp{afiles.tar} and +@samp{bfiles.tar}. The archive @samp{afiles.tar} contains the members @samp{apple}, +@samp{angst}, and @samp{aspic}; @samp{bfiles.tar} contains the members +@samp{./birds}, @samp{baboon}, and @samp{./box}. + +Unless we state otherwise, all practicing you do and examples you follow +in this chapter will take place in the @file{practice} directory that +you created in the previous chapter; see @ref{prepare for examples}. +(Below in this section, we will remind you of the state of the examples +where the last chapter left them.) + +The five operations that we will cover in this chapter are: + +@table @option +@item --append +@itemx -r +Add new entries to an archive that already exists. +@item --update +@itemx -u +Add more recent copies of archive members to the end of an archive, if +they exist. +@item --concatenate +@itemx --catenate +@itemx -A +Add one or more pre-existing archives to the end of another archive. +@item --delete +Delete items from an archive (does not work on tapes). +@item --compare +@itemx --diff +@itemx -d +Compare archive members to their counterparts in the file system. +@end table + +@node append +@subsection How to Add Files to Existing Archives: @option{--append} + +@cindex appending files to existing archive +@opindex append +If you want to add files to an existing archive, you don't need to +create a new archive; you can use @option{--append} (@option{-r}). +The archive must already exist in order to use @option{--append}. (A +related operation is the @option{--update} operation; you can use this +to add newer versions of archive members to an existing archive. To learn how to +do this with @option{--update}, @pxref{update}.) + +If you use @option{--append} to add a file that has the same name as an +archive member to an archive containing that archive member, then the +old member is not deleted. What does happen, however, is somewhat +complex. @command{tar} @emph{allows} you to have infinite number of files +with the same name. Some operations treat these same-named members no +differently than any other set of archive members: for example, if you +view an archive with @option{--list} (@option{-t}), you will see all +of those members listed, with their data modification times, owners, etc. + +Other operations don't deal with these members as perfectly as you might +prefer; if you were to use @option{--extract} to extract the archive, +only the most recently added copy of a member with the same name as +other members would end up in the working directory. This is because +@option{--extract} extracts an archive in the order the members appeared +in the archive; the most recently archived members will be extracted +last. Additionally, an extracted member will @emph{replace} a file of +the same name which existed in the directory already, and @command{tar} +will not prompt you about this@footnote{Unless you give it +@option{--keep-old-files} (or @option{--skip-old-files}) option, or +the disk copy is newer than the one in the archive and you invoke +@command{tar} with @option{--keep-newer-files} option.}. Thus, only +the most recently archived member will end up being extracted, as it +will replace the one extracted before it, and so on. + +@cindex extracting @var{n}th copy of the file +@xopindex{occurrence, described} +There exists a special option that allows you to get around this +behavior and extract (or list) only a particular copy of the file. +This is @option{--occurrence} option. If you run @command{tar} with +this option, it will extract only the first copy of the file. You +may also give this option an argument specifying the number of +copy to be extracted. Thus, for example if the archive +@file{archive.tar} contained three copies of file @file{myfile}, then +the command + +@smallexample +tar --extract --file archive.tar --occurrence=2 myfile +@end smallexample + +@noindent +would extract only the second copy. @xref{Option +Summary,---occurrence}, for the description of @option{--occurrence} +option. + +@FIXME{ hag -- you might want to incorporate some of the above into the +MMwtSN node; not sure. i didn't know how to make it simpler... + +There are a few ways to get around this. Xref to Multiple Members +with the Same Name, maybe.} + +@cindex Members, replacing with other members +@cindex Replacing members with other members +@xopindex{delete, using before --append} +If you want to replace an archive member, use @option{--delete} to +delete the member you want to remove from the archive, and then use +@option{--append} to add the member you want to be in the archive. Note +that you can not change the order of the archive; the most recently +added member will still appear last. In this sense, you cannot truly +``replace'' one member with another. (Replacing one member with another +will not work on certain types of media, such as tapes; see @ref{delete} +and @ref{Media}, for more information.) + +@menu +* appending files:: Appending Files to an Archive +* multiple:: +@end menu + +@node appending files +@subsubsection Appending Files to an Archive +@cindex Adding files to an Archive +@cindex Appending files to an Archive +@cindex Archives, Appending files to +@opindex append + +The simplest way to add a file to an already existing archive is the +@option{--append} (@option{-r}) operation, which writes specified +files into the archive whether or not they are already among the +archived files. + +When you use @option{--append}, you @emph{must} specify file name +arguments, as there is no default. If you specify a file that already +exists in the archive, another copy of the file will be added to the +end of the archive. As with other operations, the member names of the +newly added files will be exactly the same as their names given on the +command line. The @option{--verbose} (@option{-v}) option will print +out the names of the files as they are written into the archive. + +@option{--append} cannot be performed on some tape drives, unfortunately, +due to deficiencies in the formats those tape drives use. The archive +must be a valid @command{tar} archive, or else the results of using this +operation will be unpredictable. @xref{Media}. + +To demonstrate using @option{--append} to add a file to an archive, +create a file called @file{rock} in the @file{practice} directory. +Make sure you are in the @file{practice} directory. Then, run the +following @command{tar} command to add @file{rock} to +@file{collection.tar}: + +@smallexample +$ @kbd{tar --append --file=collection.tar rock} +@end smallexample + +@noindent +If you now use the @option{--list} (@option{-t}) operation, you will see that +@file{rock} has been added to the archive: + +@smallexample +$ @kbd{tar --list --file=collection.tar} +-rw-r--r-- me/user 28 1996-10-18 16:31 jazz +-rw-r--r-- me/user 21 1996-09-23 16:44 blues +-rw-r--r-- me/user 20 1996-09-23 16:44 folk +-rw-r--r-- me/user 20 1996-09-23 16:44 rock +@end smallexample + +@node multiple +@subsubsection Multiple Members with the Same Name +@cindex members, multiple +@cindex multiple members + +You can use @option{--append} (@option{-r}) to add copies of files +which have been updated since the archive was created. (However, we +do not recommend doing this since there is another @command{tar} +option called @option{--update}; @xref{update}, for more information. +We describe this use of @option{--append} here for the sake of +completeness.) When you extract the archive, the older version will +be effectively lost. This works because files are extracted from an +archive in the order in which they were archived. Thus, when the +archive is extracted, a file archived later in time will replace a +file of the same name which was archived earlier, even though the +older version of the file will remain in the archive unless you delete +all versions of the file. + +Supposing you change the file @file{blues} and then append the changed +version to @file{collection.tar}. As you saw above, the original +@file{blues} is in the archive @file{collection.tar}. If you change the +file and append the new version of the file to the archive, there will +be two copies in the archive. When you extract the archive, the older +version of the file will be extracted first, and then replaced by the +newer version when it is extracted. + +You can append the new, changed copy of the file @file{blues} to the +archive in this way: + +@smallexample +$ @kbd{tar --append --verbose --file=collection.tar blues} +blues +@end smallexample + +@noindent +Because you specified the @option{--verbose} option, @command{tar} has +printed the name of the file being appended as it was acted on. Now +list the contents of the archive: + +@smallexample +$ @kbd{tar --list --verbose --file=collection.tar} +-rw-r--r-- me/user 28 1996-10-18 16:31 jazz +-rw-r--r-- me/user 21 1996-09-23 16:44 blues +-rw-r--r-- me/user 20 1996-09-23 16:44 folk +-rw-r--r-- me/user 20 1996-09-23 16:44 rock +-rw-r--r-- me/user 58 1996-10-24 18:30 blues +@end smallexample + +@noindent +The newest version of @file{blues} is now at the end of the archive +(note the different creation dates and file sizes). If you extract +the archive, the older version of the file @file{blues} will be +replaced by the newer version. You can confirm this by extracting +the archive and running @samp{ls} on the directory. + +If you wish to extract the first occurrence of the file @file{blues} +from the archive, use @option{--occurrence} option, as shown in +the following example: + +@smallexample +$ @kbd{tar --extract -vv --occurrence --file=collection.tar blues} +-rw-r--r-- me/user 21 1996-09-23 16:44 blues +@end smallexample + +@xref{Writing}, for more information on @option{--extract} and +see @ref{Option Summary, --occurrence}, for a description of +@option{--occurrence} option. + +@node update +@subsection Updating an Archive +@cindex Updating an archive +@opindex update + +In the previous section, you learned how to use @option{--append} to +add a file to an existing archive. A related operation is +@option{--update} (@option{-u}). The @option{--update} operation +updates a @command{tar} archive by comparing the date of the specified +archive members against the date of the file with the same name. If +the file has been modified more recently than the archive member, then +the newer version of the file is added to the archive (as with +@option{--append}). + +Unfortunately, you cannot use @option{--update} with magnetic tape drives. +The operation will fail. + +@FIXME{other examples of media on which --update will fail? need to ask +charles and/or mib/thomas/dave shevett..} + +Both @option{--update} and @option{--append} work by adding to the end +of the archive. When you extract a file from the archive, only the +version stored last will wind up in the file system, unless you use +the @option{--backup} option. @xref{multiple}, for a detailed discussion. + +@menu +* how to update:: +@end menu + +@node how to update +@subsubsection How to Update an Archive Using @option{--update} +@opindex update + +You must use file name arguments with the @option{--update} +(@option{-u}) operation. If you don't specify any files, +@command{tar} won't act on any files and won't tell you that it didn't +do anything (which may end up confusing you). + +@c note: the above parenthetical added because in fact, this +@c behavior just confused the author. :-) + +To see the @option{--update} option at work, create a new file, +@file{classical}, in your practice directory, and some extra text to the +file @file{blues}, using any text editor. Then invoke @command{tar} with +the @samp{update} operation and the @option{--verbose} (@option{-v}) +option specified, using the names of all the files in the @file{practice} +directory as file name arguments: + +@smallexample +$ @kbd{tar --update -v -f collection.tar blues folk rock classical} +blues +classical +$ +@end smallexample + +@noindent +Because we have specified verbose mode, @command{tar} prints out the names +of the files it is working on, which in this case are the names of the +files that needed to be updated. If you run @samp{tar --list} and look +at the archive, you will see @file{blues} and @file{classical} at its +end. There will be a total of two versions of the member @samp{blues}; +the one at the end will be newer and larger, since you added text before +updating it. + +The reason @command{tar} does not overwrite the older file when updating +it is because writing to the middle of a section of tape is a difficult +process. Tapes are not designed to go backward. @xref{Media}, for more +information about tapes. + +@option{--update} (@option{-u}) is not suitable for performing backups for two +reasons: it does not change directory content entries, and it +lengthens the archive every time it is used. The @GNUTAR{} +options intended specifically for backups are more +efficient. If you need to run backups, please consult @ref{Backups}. + +@node concatenate +@subsection Combining Archives with @option{--concatenate} + +@cindex Adding archives to an archive +@cindex Concatenating Archives +@opindex concatenate +@opindex catenate +@c @cindex @option{-A} described +Sometimes it may be convenient to add a second archive onto the end of +an archive rather than adding individual files to the archive. To add +one or more archives to the end of another archive, you should use the +@option{--concatenate} (@option{--catenate}, @option{-A}) operation. + +To use @option{--concatenate}, give the first archive with +@option{--file} option and name the rest of archives to be +concatenated on the command line. The members, and their member +names, will be copied verbatim from those archives to the first +one@footnote{This can cause multiple members to have the same name. For +information on how this affects reading the archive, see @ref{multiple}.}. +The new, concatenated archive will be called by the same name as the +one given with the @option{--file} option. As usual, if you omit +@option{--file}, @command{tar} will use the value of the environment +variable @env{TAPE}, or, if this has not been set, the default archive name. + +@FIXME{There is no way to specify a new name...} + +To demonstrate how @option{--concatenate} works, create two small archives +called @file{bluesrock.tar} and @file{folkjazz.tar}, using the relevant +files from @file{practice}: + +@smallexample +$ @kbd{tar -cvf bluesrock.tar blues rock} +blues +rock +$ @kbd{tar -cvf folkjazz.tar folk jazz} +folk +jazz +@end smallexample + +@noindent +If you like, You can run @samp{tar --list} to make sure the archives +contain what they are supposed to: + +@smallexample +$ @kbd{tar -tvf bluesrock.tar} +-rw-r--r-- melissa/user 105 1997-01-21 19:42 blues +-rw-r--r-- melissa/user 33 1997-01-20 15:34 rock +$ @kbd{tar -tvf jazzfolk.tar} +-rw-r--r-- melissa/user 20 1996-09-23 16:44 folk +-rw-r--r-- melissa/user 65 1997-01-30 14:15 jazz +@end smallexample + +We can concatenate these two archives with @command{tar}: + +@smallexample +$ @kbd{cd ..} +$ @kbd{tar --concatenate --file=bluesrock.tar jazzfolk.tar} +@end smallexample + +If you now list the contents of the @file{bluesrock.tar}, you will see +that now it also contains the archive members of @file{jazzfolk.tar}: + +@smallexample +$ @kbd{tar --list --file=bluesrock.tar} +blues +rock +folk +jazz +@end smallexample + +When you use @option{--concatenate}, the source and target archives must +already exist and must have been created using compatible format +parameters. Notice, that @command{tar} does not check whether the +archives it concatenates have compatible formats, it does not +even check if the files are really tar archives. + +Like @option{--append} (@option{-r}), this operation cannot be performed on some +tape drives, due to deficiencies in the formats those tape drives use. + +@cindex @code{concatenate} vs @command{cat} +@cindex @command{cat} vs @code{concatenate} +It may seem more intuitive to you to want or try to use @command{cat} to +concatenate two archives instead of using the @option{--concatenate} +operation; after all, @command{cat} is the utility for combining files. + +However, @command{tar} archives incorporate an end-of-file marker which +must be removed if the concatenated archives are to be read properly as +one archive. @option{--concatenate} removes the end-of-archive marker +from the target archive before each new archive is appended. If you use +@command{cat} to combine the archives, the result will not be a valid +@command{tar} format archive. If you need to retrieve files from an +archive that was added to using the @command{cat} utility, use the +@option{--ignore-zeros} (@option{-i}) option. @xref{Ignore Zeros}, for further +information on dealing with archives improperly combined using the +@command{cat} shell utility. + +@node delete +@subsection Removing Archive Members Using @option{--delete} +@cindex Deleting files from an archive +@cindex Removing files from an archive + +@opindex delete +You can remove members from an archive by using the @option{--delete} +option. Specify the name of the archive with @option{--file} +(@option{-f}) and then specify the names of the members to be deleted; +if you list no member names, nothing will be deleted. The +@option{--verbose} option will cause @command{tar} to print the names +of the members as they are deleted. As with @option{--extract}, you +must give the exact member names when using @samp{tar --delete}. +@option{--delete} will remove all versions of the named file from the +archive. The @option{--delete} operation can run very slowly. + +Unlike other operations, @option{--delete} has no short form. + +@cindex Tapes, using @option{--delete} and +@cindex Deleting from tape archives +This operation will rewrite the archive. You can only use +@option{--delete} on an archive if the archive device allows you to +write to any point on the media, such as a disk; because of this, it +does not work on magnetic tapes. Do not try to delete an archive member +from a magnetic tape; the action will not succeed, and you will be +likely to scramble the archive and damage your tape. There is no safe +way (except by completely re-writing the archive) to delete files from +most kinds of magnetic tape. @xref{Media}. + +To delete all versions of the file @file{blues} from the archive +@file{collection.tar} in the @file{practice} directory, make sure you +are in that directory, and then, + +@smallexample +$ @kbd{tar --list --file=collection.tar} +blues +folk +jazz +rock +$ @kbd{tar --delete --file=collection.tar blues} +$ @kbd{tar --list --file=collection.tar} +folk +jazz +rock +@end smallexample + +@FIXME{Check if the above listing is actually produced after running +all the examples on collection.tar.} + +The @option{--delete} option has been reported to work properly when +@command{tar} acts as a filter from @code{stdin} to @code{stdout}. + +@node compare +@subsection Comparing Archive Members with the File System +@cindex Verifying the currency of an archive + +@opindex compare +The @option{--compare} (@option{-d}), or @option{--diff} operation compares +specified archive members against files with the same names, and then +reports differences in file size, mode, owner, modification date and +contents. You should @emph{only} specify archive member names, not file +names. If you do not name any members, then @command{tar} will compare the +entire archive. If a file is represented in the archive but does not +exist in the file system, @command{tar} reports a difference. + +You have to specify the record size of the archive when modifying an +archive with a non-default record size. + +@command{tar} ignores files in the file system that do not have +corresponding members in the archive. + +The following example compares the archive members @file{rock}, +@file{blues} and @file{funk} in the archive @file{bluesrock.tar} with +files of the same name in the file system. (Note that there is no file, +@file{funk}; @command{tar} will report an error message.) + +@smallexample +$ @kbd{tar --compare --file=bluesrock.tar rock blues funk} +rock +blues +tar: funk not found in archive +@end smallexample + +The spirit behind the @option{--compare} (@option{--diff}, +@option{-d}) option is to check whether the archive represents the +current state of files on disk, more than validating the integrity of +the archive media. For this latter goal, see @ref{verify}. + +@node create options +@section Options Used by @option{--create} + +@xopindex{create, additional options} +The previous chapter described the basics of how to use +@option{--create} (@option{-c}) to create an archive from a set of files. +@xref{create}. This section described advanced options to be used with +@option{--create}. + +@menu +* override:: Overriding File Metadata. +* Ignore Failed Read:: +@end menu + +@node override +@subsection Overriding File Metadata + +As described above, a @command{tar} archive keeps, for each member it contains, +its @dfn{metadata}, such as modification time, mode and ownership of +the file. @GNUTAR{} allows to replace these data with other values +when adding files to the archive. The options described in this +section affect creation of archives of any type. For POSIX archives, +see also @ref{PAX keywords}, for additional ways of controlling +metadata, stored in the archive. + +@table @option +@opindex mode +@item --mode=@var{permissions} + +When adding files to an archive, @command{tar} will use +@var{permissions} for the archive members, rather than the permissions +from the files. @var{permissions} can be specified either as an octal +number or as symbolic permissions, like with +@command{chmod} (@xref{File permissions, Permissions, File +permissions, fileutils, @acronym{GNU} file utilities}. This reference +also has useful information for those not being overly familiar with +the UNIX permission system). Using latter syntax allows for +more flexibility. For example, the value @samp{a+rw} adds read and write +permissions for everybody, while retaining executable bits on directories +or on any other file already marked as executable: + +@smallexample +$ @kbd{tar -c -f archive.tar --mode='a+rw' .} +@end smallexample + +@item --mtime=@var{date} +@opindex mtime + +When adding files to an archive, @command{tar} will use @var{date} as +the modification time of members when creating archives, instead of +their actual modification times. The argument @var{date} can be +either a textual date representation in almost arbitrary format +(@pxref{Date input formats}) or a name of an existing file, starting +with @samp{/} or @samp{.}. In the latter case, the modification time +of that file will be used. + +The following example will set the modification date to 00:00:00, +January 1, 1970: + +@smallexample +$ @kbd{tar -c -f archive.tar --mtime='1970-01-01' .} +@end smallexample + +@noindent +When used with @option{--verbose} (@pxref{verbose tutorial}) @GNUTAR{} +will try to convert the specified date back to its textual +representation and compare it with the one given with +@option{--mtime} options. If the two dates differ, @command{tar} will +print a warning saying what date it will use. This is to help user +ensure he is using the right date. + +For example: + +@smallexample +$ @kbd{tar -c -f archive.tar -v --mtime=yesterday .} +tar: Option --mtime: Treating date 'yesterday' as 2006-06-20 +13:06:29.152478 +@dots{} +@end smallexample + +@item --owner=@var{user} +@opindex owner + +Specifies that @command{tar} should use @var{user} as the owner of members +when creating archives, instead of the user associated with the source +file. + +If @var{user} contains a colon, it is taken to be of the form +@var{name}:@var{id} where a nonempty @var{name} specifies the user +name and a nonempty @var{id} specifies the decimal numeric user +@acronym{ID}. If @var{user} does not contain a colon, it is taken to +be a user number if it is one or more decimal digits; otherwise it is +taken to be a user name. + +If a name is given but no number, the number is inferred from the +current host's user database if possible, and the file's user number +is used otherwise. If a number is given but no name, the name is +inferred from the number if possible, and an empty name is used +otherwise. If both name and number are given, the user database is +not consulted, and the name and number need not be valid on the +current host. + +There is no value indicating a missing number, and @samp{0} usually means +@code{root}. Some people like to force @samp{0} as the value to offer in +their distributions for the owner of files, because the @code{root} user is +anonymous anyway, so that might as well be the owner of anonymous +archives. For example: + +@smallexample +$ @kbd{tar -c -f archive.tar --owner=0 .} +@end smallexample + +@noindent +or: + +@smallexample +$ @kbd{tar -c -f archive.tar --owner=root .} +@end smallexample + +@item --group=@var{group} +@opindex group + +Files added to the @command{tar} archive will have a group @acronym{ID} of @var{group}, +rather than the group from the source file. As with @option{--owner}, +the argument @var{group} can be an existing group symbolic name, or a +decimal numeric group @acronym{ID}, or @var{name}:@var{id}. +@end table + +@node Ignore Failed Read +@subsection Ignore Fail Read + +@table @option +@item --ignore-failed-read +@opindex ignore-failed-read +Do not exit with nonzero on unreadable files or directories. +@end table + +@node extract options +@section Options Used by @option{--extract} +@cindex options for use with @option{--extract} + +@xopindex{extract, additional options} +The previous chapter showed how to use @option{--extract} to extract +an archive into the file system. Various options cause @command{tar} to +extract more information than just file contents, such as the owner, +the permissions, the modification date, and so forth. This section +presents options to be used with @option{--extract} when certain special +considerations arise. You may review the information presented in +@ref{extract} for more basic information about the +@option{--extract} operation. + +@menu +* Reading:: Options to Help Read Archives +* Writing:: Changing How @command{tar} Writes Files +* Scarce:: Coping with Scarce Resources +@end menu + +@node Reading +@subsection Options to Help Read Archives +@cindex Options when reading archives + +@cindex Reading incomplete records +@cindex Records, incomplete +@opindex read-full-records +Normally, @command{tar} will request data in full record increments from +an archive storage device. If the device cannot return a full record, +@command{tar} will report an error. However, some devices do not always +return full records, or do not require the last record of an archive to +be padded out to the next record boundary. To keep reading until you +obtain a full record, or to accept an incomplete record if it contains +an end-of-archive marker, specify the @option{--read-full-records} (@option{-B}) option +in conjunction with the @option{--extract} or @option{--list} operations. +@xref{Blocking}. + +The @option{--read-full-records} (@option{-B}) option is turned on by default when +@command{tar} reads an archive from standard input, or from a remote +machine. This is because on @acronym{BSD} Unix systems, attempting to read a +pipe returns however much happens to be in the pipe, even if it is +less than was requested. If this option were not enabled, @command{tar} +would fail as soon as it read an incomplete record from the pipe. + +If you're not sure of the blocking factor of an archive, you can +read the archive by specifying @option{--read-full-records} (@option{-B}) and +@option{--blocking-factor=@var{512-size}} (@option{-b +@var{512-size}}), using a blocking factor larger than what the archive +uses. This lets you avoid having to determine the blocking factor +of an archive. @xref{Blocking Factor}. + +@menu +* read full records:: +* Ignore Zeros:: +@end menu + +@node read full records +@unnumberedsubsubsec Reading Full Records + +@FIXME{need sentence or so of intro here} + +@table @option +@opindex read-full-records +@item --read-full-records +@item -B +Use in conjunction with @option{--extract} (@option{--get}, +@option{-x}) to read an archive which contains incomplete records, or +one which has a blocking factor less than the one specified. +@end table + +@node Ignore Zeros +@unnumberedsubsubsec Ignoring Blocks of Zeros + +@cindex End-of-archive blocks, ignoring +@cindex Ignoring end-of-archive blocks +@opindex ignore-zeros +Normally, @command{tar} stops reading when it encounters a block of zeros +between file entries (which usually indicates the end of the archive). +@option{--ignore-zeros} (@option{-i}) allows @command{tar} to +completely read an archive which contains a block of zeros before the +end (i.e., a damaged archive, or one that was created by concatenating +several archives together). + +The @option{--ignore-zeros} (@option{-i}) option is turned off by default because many +versions of @command{tar} write garbage after the end-of-archive entry, +since that part of the media is never supposed to be read. @GNUTAR{} +does not write after the end of an archive, but seeks to +maintain compatibility among archiving utilities. + +@table @option +@item --ignore-zeros +@itemx -i +To ignore blocks of zeros (i.e., end-of-archive entries) which may be +encountered while reading an archive. Use in conjunction with +@option{--extract} or @option{--list}. +@end table + +@node Writing +@subsection Changing How @command{tar} Writes Files +@UNREVISED + +@FIXME{Introductory paragraph} + +@menu +* Dealing with Old Files:: +* Overwrite Old Files:: +* Keep Old Files:: +* Keep Newer Files:: +* Unlink First:: +* Recursive Unlink:: +* Data Modification Times:: +* Setting Access Permissions:: +* Directory Modification Times and Permissions:: +* Writing to Standard Output:: +* Writing to an External Program:: +* remove files:: +@end menu + +@node Dealing with Old Files +@unnumberedsubsubsec Options Controlling the Overwriting of Existing Files + +@xopindex{overwrite-dir, introduced} +When extracting files, if @command{tar} discovers that the extracted +file already exists, it normally replaces the file by removing it before +extracting it, to prevent confusion in the presence of hard or symbolic +links. (If the existing file is a symbolic link, it is removed, not +followed.) However, if a directory cannot be removed because it is +nonempty, @command{tar} normally overwrites its metadata (ownership, +permission, etc.). The @option{--overwrite-dir} option enables this +default behavior. To be more cautious and preserve the metadata of +such a directory, use the @option{--no-overwrite-dir} option. + +@cindex Overwriting old files, prevention +@xopindex{keep-old-files, introduced} +To be even more cautious and prevent existing files from being replaced, use +the @option{--keep-old-files} (@option{-k}) option. It causes +@command{tar} to refuse to replace or update a file that already +exists, i.e., a file with the same name as an archive member prevents +extraction of that archive member. Instead, it reports an error. For +example: + +@example +$ @kbd{ls} +blues +$ @kbd{tar -x -k -f archive.tar} +tar: blues: Cannot open: File exists +tar: Exiting with failure status due to previous errors +@end example + +@xopindex{skip-old-files, introduced} +If you wish to preserve old files untouched, but don't want +@command{tar} to treat them as errors, use the +@option{--skip-old-files} option. This option causes @command{tar} to +silently skip extracting over existing files. + +@xopindex{overwrite, introduced} +To be more aggressive about altering existing files, use the +@option{--overwrite} option. It causes @command{tar} to overwrite +existing files and to follow existing symbolic links when extracting. + +@cindex Protecting old files +Some people argue that @GNUTAR{} should not hesitate +to overwrite files with other files when extracting. When extracting +a @command{tar} archive, they expect to see a faithful copy of the +state of the file system when the archive was created. It is debatable +that this would always be a proper behavior. For example, suppose one +has an archive in which @file{usr/local} is a link to +@file{usr/local2}. Since then, maybe the site removed the link and +renamed the whole hierarchy from @file{/usr/local2} to +@file{/usr/local}. Such things happen all the time. I guess it would +not be welcome at all that @GNUTAR{} removes the +whole hierarchy just to make room for the link to be reinstated +(unless it @emph{also} simultaneously restores the full +@file{/usr/local2}, of course!) @GNUTAR{} is indeed +able to remove a whole hierarchy to reestablish a symbolic link, for +example, but @emph{only if} @option{--recursive-unlink} is specified +to allow this behavior. In any case, single files are silently +removed. + +@xopindex{unlink-first, introduced} +Finally, the @option{--unlink-first} (@option{-U}) option can improve performance in +some cases by causing @command{tar} to remove files unconditionally +before extracting them. + +@node Overwrite Old Files +@unnumberedsubsubsec Overwrite Old Files + +@table @option +@opindex overwrite +@item --overwrite +Overwrite existing files and directory metadata when extracting files +from an archive. + +This causes @command{tar} to write extracted files into the file system without +regard to the files already on the system; i.e., files with the same +names as archive members are overwritten when the archive is extracted. +It also causes @command{tar} to extract the ownership, permissions, +and time stamps onto any preexisting files or directories. +If the name of a corresponding file name is a symbolic link, the file +pointed to by the symbolic link will be overwritten instead of the +symbolic link itself (if this is possible). Moreover, special devices, +empty directories and even symbolic links are automatically removed if +they are in the way of extraction. + +Be careful when using the @option{--overwrite} option, particularly when +combined with the @option{--absolute-names} (@option{-P}) option, as this combination +can change the contents, ownership or permissions of any file on your +system. Also, many systems do not take kindly to overwriting files that +are currently being executed. + +@opindex overwrite-dir +@item --overwrite-dir +Overwrite the metadata of directories when extracting files from an +archive, but remove other files before extracting. +@end table + +@node Keep Old Files +@unnumberedsubsubsec Keep Old Files + +@GNUTAR{} provides two options to control its actions in a situation +when it is about to extract a file which already exists on disk. + +@table @option +@opindex keep-old-files +@item --keep-old-files +@itemx -k +Do not replace existing files from archive. When such a file is +encountered, @command{tar} issues an error message. Upon end of +extraction, @command{tar} exits with code 2 (@pxref{exit status}). + +@item --skip-old-files +Do not replace existing files from archive, but do not treat that +as error. Such files are silently skipped and do not affect +@command{tar} exit status. + +Additional verbosity can be obtained using @option{--warning=existing-file} +together with that option (@pxref{warnings}). +@end table + +@node Keep Newer Files +@unnumberedsubsubsec Keep Newer Files + +@table @option +@opindex keep-newer-files +@item --keep-newer-files +Do not replace existing files that are newer than their archive +copies. This option is meaningless with @option{--list} (@option{-t}). +@end table + +@node Unlink First +@unnumberedsubsubsec Unlink First + +@table @option +@opindex unlink-first +@item --unlink-first +@itemx -U +Remove files before extracting over them. +This can make @command{tar} run a bit faster if you know in advance +that the extracted files all need to be removed. Normally this option +slows @command{tar} down slightly, so it is disabled by default. +@end table + +@node Recursive Unlink +@unnumberedsubsubsec Recursive Unlink + +@table @option +@opindex recursive-unlink +@item --recursive-unlink +When this option is specified, try removing files and directory hierarchies +before extracting over them. @emph{This is a dangerous option!} +@end table + +If you specify the @option{--recursive-unlink} option, +@command{tar} removes @emph{anything} that keeps you from extracting a file +as far as current permissions will allow it. This could include removal +of the contents of a full directory hierarchy. + +@node Data Modification Times +@unnumberedsubsubsec Setting Data Modification Times + +@cindex Data modification times of extracted files +@cindex Modification times of extracted files +Normally, @command{tar} sets the data modification times of extracted +files to the corresponding times recorded for the files in the archive, but +limits the permissions of extracted files by the current @code{umask} +setting. + +To set the data modification times of extracted files to the time when +the files were extracted, use the @option{--touch} (@option{-m}) option in +conjunction with @option{--extract} (@option{--get}, @option{-x}). + +@table @option +@opindex touch +@item --touch +@itemx -m +Sets the data modification time of extracted archive members to the time +they were extracted, not the time recorded for them in the archive. +Use in conjunction with @option{--extract} (@option{--get}, @option{-x}). +@end table + +@node Setting Access Permissions +@unnumberedsubsubsec Setting Access Permissions + +@cindex Permissions of extracted files +@cindex Modes of extracted files +To set the modes (access permissions) of extracted files to those +recorded for those files in the archive, use @option{--same-permissions} +in conjunction with the @option{--extract} (@option{--get}, +@option{-x}) operation. + +@table @option +@opindex preserve-permissions +@opindex same-permissions +@item --preserve-permissions +@itemx --same-permissions +@c @itemx --ignore-umask +@itemx -p +Set modes of extracted archive members to those recorded in the +archive, instead of current umask settings. Use in conjunction with +@option{--extract} (@option{--get}, @option{-x}). +@end table + +@node Directory Modification Times and Permissions +@unnumberedsubsubsec Directory Modification Times and Permissions + +After successfully extracting a file member, @GNUTAR{} normally +restores its permissions and modification times, as described in the +previous sections. This cannot be done for directories, because +after extracting a directory @command{tar} will almost certainly +extract files into that directory and this will cause the directory +modification time to be updated. Moreover, restoring that directory +permissions may not permit file creation within it. Thus, restoring +directory permissions and modification times must be delayed at least +until all files have been extracted into that directory. @GNUTAR{} +restores directories using the following approach. + +The extracted directories are created with the mode specified in the +archive, as modified by the umask of the user, which gives sufficient +permissions to allow file creation. The meta-information about the +directory is recorded in the temporary list of directories. When +preparing to extract next archive member, @GNUTAR{} checks if the +directory prefix of this file contains the remembered directory. If +it does not, the program assumes that all files have been extracted +into that directory, restores its modification time and permissions +and removes its entry from the internal list. This approach allows +to correctly restore directory meta-information in the majority of +cases, while keeping memory requirements sufficiently small. It is +based on the fact, that most @command{tar} archives use the predefined +order of members: first the directory, then all the files and +subdirectories in that directory. + +However, this is not always true. The most important exception are +incremental archives (@pxref{Incremental Dumps}). The member order in +an incremental archive is reversed: first all directory members are +stored, followed by other (non-directory) members. So, when extracting +from incremental archives, @GNUTAR{} alters the above procedure. It +remembers all restored directories, and restores their meta-data +only after the entire archive has been processed. Notice, that you do +not need to specify any special options for that, as @GNUTAR{} +automatically detects archives in incremental format. + +There may be cases, when such processing is required for normal archives +too. Consider the following example: + +@smallexample +@group +$ @kbd{tar --no-recursion -cvf archive \ + foo foo/file1 bar bar/file foo/file2} +foo/ +foo/file1 +bar/ +bar/file +foo/file2 +@end group +@end smallexample + +During the normal operation, after encountering @file{bar} +@GNUTAR{} will assume that all files from the directory @file{foo} +were already extracted and will therefore restore its timestamp and +permission bits. However, after extracting @file{foo/file2} the +directory timestamp will be offset again. + +To correctly restore directory meta-information in such cases, use +the @option{--delay-directory-restore} command line option: + +@table @option +@opindex delay-directory-restore +@item --delay-directory-restore +Delays restoring of the modification times and permissions of extracted +directories until the end of extraction. This way, correct +meta-information is restored even if the archive has unusual member +ordering. + +@opindex no-delay-directory-restore +@item --no-delay-directory-restore +Cancel the effect of the previous @option{--delay-directory-restore}. +Use this option if you have used @option{--delay-directory-restore} in +@env{TAR_OPTIONS} variable (@pxref{TAR_OPTIONS}) and wish to +temporarily disable it. +@end table + +@node Writing to Standard Output +@unnumberedsubsubsec Writing to Standard Output + +@cindex Writing extracted files to standard output +@cindex Standard output, writing extracted files to +To write the extracted files to the standard output, instead of +creating the files on the file system, use @option{--to-stdout} (@option{-O}) in +conjunction with @option{--extract} (@option{--get}, @option{-x}). This option is useful if you are +extracting files to send them through a pipe, and do not need to +preserve them in the file system. If you extract multiple members, +they appear on standard output concatenated, in the order they are +found in the archive. + +@table @option +@opindex to-stdout +@item --to-stdout +@itemx -O +Writes files to the standard output. Use only in conjunction with +@option{--extract} (@option{--get}, @option{-x}). When this option is +used, instead of creating the files specified, @command{tar} writes +the contents of the files extracted to its standard output. This may +be useful if you are only extracting the files in order to send them +through a pipe. This option is meaningless with @option{--list} +(@option{-t}). +@end table + +This can be useful, for example, if you have a tar archive containing +a big file and don't want to store the file on disk before processing +it. You can use a command like this: + +@smallexample +tar -xOzf foo.tgz bigfile | process +@end smallexample + +or even like this if you want to process the concatenation of the files: + +@smallexample +tar -xOzf foo.tgz bigfile1 bigfile2 | process +@end smallexample + +However, @option{--to-command} may be more convenient for use with +multiple files. See the next section. + +@node Writing to an External Program +@unnumberedsubsubsec Writing to an External Program + +You can instruct @command{tar} to send the contents of each extracted +file to the standard input of an external program: + +@table @option +@opindex to-command +@item --to-command=@var{command} +Extract files and pipe their contents to the standard input of +@var{command}. When this option is used, instead of creating the +files specified, @command{tar} invokes @var{command} and pipes the +contents of the files to its standard output. The @var{command} may +contain command line arguments (see @ref{external, Running External Commands}, +for more detail). + +Notice, that @var{command} is executed once for each regular file +extracted. Non-regular files (directories, etc.) are ignored when this +option is used. +@end table + +The command can obtain the information about the file it processes +from the following environment variables: + +@table @env +@vrindex TAR_FILETYPE, to-command environment +@item TAR_FILETYPE +Type of the file. It is a single letter with the following meaning: + +@multitable @columnfractions 0.10 0.90 +@item f @tab Regular file +@item d @tab Directory +@item l @tab Symbolic link +@item h @tab Hard link +@item b @tab Block device +@item c @tab Character device +@end multitable + +Currently only regular files are supported. + +@vrindex TAR_MODE, to-command environment +@item TAR_MODE +File mode, an octal number. + +@vrindex TAR_FILENAME, to-command environment +@item TAR_FILENAME +The name of the file. + +@vrindex TAR_REALNAME, to-command environment +@item TAR_REALNAME +Name of the file as stored in the archive. + +@vrindex TAR_UNAME, to-command environment +@item TAR_UNAME +Name of the file owner. + +@vrindex TAR_GNAME, to-command environment +@item TAR_GNAME +Name of the file owner group. + +@vrindex TAR_ATIME, to-command environment +@item TAR_ATIME +Time of last access. It is a decimal number, representing seconds +since the Epoch. If the archive provides times with nanosecond +precision, the nanoseconds are appended to the timestamp after a +decimal point. + +@vrindex TAR_MTIME, to-command environment +@item TAR_MTIME +Time of last modification. + +@vrindex TAR_CTIME, to-command environment +@item TAR_CTIME +Time of last status change. + +@vrindex TAR_SIZE, to-command environment +@item TAR_SIZE +Size of the file. + +@vrindex TAR_UID, to-command environment +@item TAR_UID +UID of the file owner. + +@vrindex TAR_GID, to-command environment +@item TAR_GID +GID of the file owner. +@end table + +Additionally, the following variables contain information about +tar mode and the archive being processed: + +@table @env +@vrindex TAR_VERSION, to-command environment +@item TAR_VERSION +@GNUTAR{} version number. + +@vrindex TAR_ARCHIVE, to-command environment +@item TAR_ARCHIVE +The name of the archive @command{tar} is processing. + +@vrindex TAR_BLOCKING_FACTOR, to-command environment +@item TAR_BLOCKING_FACTOR +Current blocking factor (@pxref{Blocking}). + +@vrindex TAR_VOLUME, to-command environment +@item TAR_VOLUME +Ordinal number of the volume @command{tar} is processing. + +@vrindex TAR_FORMAT, to-command environment +@item TAR_FORMAT +Format of the archive being processed. @xref{Formats}, for a complete +list of archive format names. +@end table + +These variables are defined prior to executing the command, so you can +pass them as arguments, if you prefer. For example, if the command +@var{proc} takes the member name and size as its arguments, then you +could do: + +@smallexample +$ @kbd{tar -x -f archive.tar \ + --to-command='proc $TAR_FILENAME $TAR_SIZE'} +@end smallexample + +@noindent +Notice single quotes to prevent variable names from being expanded by +the shell when invoking @command{tar}. + +If @var{command} exits with a non-0 status, @command{tar} will print +an error message similar to the following: + +@smallexample +tar: 2345: Child returned status 1 +@end smallexample + +Here, @samp{2345} is the PID of the finished process. + +If this behavior is not wanted, use @option{--ignore-command-error}: + +@table @option +@opindex ignore-command-error +@item --ignore-command-error +Ignore exit codes of subprocesses. Notice that if the program +exits on signal or otherwise terminates abnormally, the error message +will be printed even if this option is used. + +@opindex no-ignore-command-error +@item --no-ignore-command-error +Cancel the effect of any previous @option{--ignore-command-error} +option. This option is useful if you have set +@option{--ignore-command-error} in @env{TAR_OPTIONS} +(@pxref{TAR_OPTIONS}) and wish to temporarily cancel it. +@end table + +@node remove files +@unnumberedsubsubsec Removing Files + +@FIXME{The section is too terse. Something more to add? An example, +maybe?} + +@table @option +@opindex remove-files +@item --remove-files +Remove files after adding them to the archive. +@end table + +@node Scarce +@subsection Coping with Scarce Resources +@UNREVISED + +@cindex Small memory +@cindex Running out of space + +@menu +* Starting File:: +* Same Order:: +@end menu + +@node Starting File +@unnumberedsubsubsec Starting File + +@table @option +@opindex starting-file +@item --starting-file=@var{name} +@itemx -K @var{name} +Starts an operation in the middle of an archive. Use in conjunction +with @option{--extract} (@option{--get}, @option{-x}) or @option{--list} (@option{-t}). +@end table + +@cindex Middle of the archive, starting in the +If a previous attempt to extract files failed due to lack of disk +space, you can use @option{--starting-file=@var{name}} (@option{-K +@var{name}}) to start extracting only after member @var{name} of the +archive. This assumes, of course, that there is now free space, or +that you are now extracting into a different file system. (You could +also choose to suspend @command{tar}, remove unnecessary files from +the file system, and then resume the same @command{tar} operation. +In this case, @option{--starting-file} is not necessary.) See also +@ref{interactive}, and @ref{exclude}. + +@node Same Order +@unnumberedsubsubsec Same Order + +@table @option +@cindex Large lists of file names on small machines +@opindex same-order +@opindex preserve-order +@item --same-order +@itemx --preserve-order +@itemx -s +To process large lists of file names on machines with small amounts of +memory. Use in conjunction with @option{--compare} (@option{--diff}, +@option{-d}), @option{--list} (@option{-t}) or @option{--extract} +(@option{--get}, @option{-x}). +@end table + +The @option{--same-order} (@option{--preserve-order}, @option{-s}) option tells @command{tar} that the list of file +names to be listed or extracted is sorted in the same order as the +files in the archive. This allows a large list of names to be used, +even on a small machine that would not otherwise be able to hold all +the names in memory at the same time. Such a sorted list can easily be +created by running @samp{tar -t} on the archive and editing its output. + +This option is probably never needed on modern computer systems. + +@node backup +@section Backup options + +@cindex backup options + +@GNUTAR{} offers options for making backups of files +before writing new versions. These options control the details of +these backups. They may apply to the archive itself before it is +created or rewritten, as well as individual extracted members. Other +@acronym{GNU} programs (@command{cp}, @command{install}, @command{ln}, +and @command{mv}, for example) offer similar options. + +Backup options may prove unexpectedly useful when extracting archives +containing many members having identical name, or when extracting archives +on systems having file name limitations, making different members appear +as having similar names through the side-effect of name truncation. +@FIXME{This is true only if we have a good scheme for truncated backup names, +which I'm not sure at all: I suspect work is needed in this area.} +When any existing file is backed up before being overwritten by extraction, +then clashing files are automatically be renamed to be unique, and the +true name is kept for only the last file of a series of clashing files. +By using verbose mode, users may track exactly what happens. + +At the detail level, some decisions are still experimental, and may +change in the future, we are waiting comments from our users. So, please +do not learn to depend blindly on the details of the backup features. +For example, currently, directories themselves are never renamed through +using these options, so, extracting a file over a directory still has +good chances to fail. Also, backup options apply to created archives, +not only to extracted members. For created archives, backups will not +be attempted when the archive is a block or character device, or when it +refers to a remote file. + +For the sake of simplicity and efficiency, backups are made by renaming old +files prior to creation or extraction, and not by copying. The original +name is restored if the file creation fails. If a failure occurs after a +partial extraction of a file, both the backup and the partially extracted +file are kept. + +@table @samp +@item --backup[=@var{method}] +@opindex backup +@vindex VERSION_CONTROL +@cindex backups +Back up files that are about to be overwritten or removed. +Without this option, the original versions are destroyed. + +Use @var{method} to determine the type of backups made. +If @var{method} is not specified, use the value of the @env{VERSION_CONTROL} +environment variable. And if @env{VERSION_CONTROL} is not set, +use the @samp{existing} method. + +@vindex version-control @r{Emacs variable} +This option corresponds to the Emacs variable @samp{version-control}; +the same values for @var{method} are accepted as in Emacs. This option +also allows more descriptive names. The valid @var{method}s are: + +@table @samp +@item t +@itemx numbered +@cindex numbered @r{backup method} +Always make numbered backups. + +@item nil +@itemx existing +@cindex existing @r{backup method} +Make numbered backups of files that already have them, simple backups +of the others. + +@item never +@itemx simple +@cindex simple @r{backup method} +Always make simple backups. + +@end table + +@item --suffix=@var{suffix} +@opindex suffix +@cindex backup suffix +@vindex SIMPLE_BACKUP_SUFFIX +Append @var{suffix} to each backup file made with @option{--backup}. If this +option is not specified, the value of the @env{SIMPLE_BACKUP_SUFFIX} +environment variable is used. And if @env{SIMPLE_BACKUP_SUFFIX} is not +set, the default is @samp{~}, just as in Emacs. + +@end table + +@node Applications +@section Notable @command{tar} Usages +@UNREVISED + +@FIXME{Using Unix file linking capability to recreate directory +structures---linking files into one subdirectory and then +@command{tar}ring that directory.} + +@FIXME{Nice hairy example using absolute-names, newer, etc.} + +@findex uuencode +You can easily use archive files to transport a group of files from +one system to another: put all relevant files into an archive on one +computer system, transfer the archive to another system, and extract +the contents there. The basic transfer medium might be magnetic tape, +Internet FTP, or even electronic mail (though you must encode the +archive with @command{uuencode} in order to transport it properly by +mail). Both machines do not have to use the same operating system, as +long as they both support the @command{tar} program. + +For example, here is how you might copy a directory's contents from +one disk to another, while preserving the dates, modes, owners and +link-structure of all the files therein. In this case, the transfer +medium is a @dfn{pipe}: + +@smallexample +$ @kbd{(cd sourcedir; tar -cf - .) | (cd targetdir; tar -xf -)} +@end smallexample + +@noindent +You can avoid subshells by using @option{-C} option: + +@smallexample +$ @kbd{tar -C sourcedir -cf - . | tar -C targetdir -xf -} +@end smallexample + +@noindent +The command also works using long option forms: + +@smallexample +@group +$ @kbd{(cd sourcedir; tar --create --file=- . ) \ + | (cd targetdir; tar --extract --file=-)} +@end group +@end smallexample + +@noindent +or + +@smallexample +@group +$ @kbd{tar --directory sourcedir --create --file=- . \ + | tar --directory targetdir --extract --file=-} +@end group +@end smallexample + +@noindent +This is one of the easiest methods to transfer a @command{tar} archive. + +@node looking ahead +@section Looking Ahead: The Rest of this Manual + +You have now seen how to use all eight of the operations available to +@command{tar}, and a number of the possible options. The next chapter +explains how to choose and change file and archive names, how to use +files to store names of other files which you can then call as +arguments to @command{tar} (this can help you save time if you expect to +archive the same list of files a number of times), and so forth. +@FIXME{in case it's not obvious, i'm making this up in some sense +based on my limited memory of what the next chapter *really* does. i +just wanted to flesh out this final section a little bit so i'd +remember to stick it in here. :-)} + +If there are too many files to conveniently list on the command line, +you can list the names in a file, and @command{tar} will read that file. +@xref{files}. + +There are various ways of causing @command{tar} to skip over some files, +and not archive them. @xref{Choosing}. + +@node Backups +@chapter Performing Backups and Restoring Files +@cindex backups + +@GNUTAR{} is distributed along with the scripts for performing backups +and restores. Even if there is a good chance those scripts may be +satisfying to you, they are not the only scripts or methods available for doing +backups and restore. You may well create your own, or use more +sophisticated packages dedicated to that purpose. + +Some users are enthusiastic about @code{Amanda} (The Advanced Maryland +Automatic Network Disk Archiver), a backup system developed by James +da Silva @file{jds@@cs.umd.edu} and available on many Unix systems. +This is free software, and it is available from @uref{http://www.amanda.org}. + +@FIXME{ + +Here is a possible plan for a future documentation about the backuping +scripts which are provided within the @GNUTAR{} +distribution. + +@itemize @bullet +@item dumps + @itemize @minus + @item what are dumps + @item different levels of dumps + @itemize + + @item full dump = dump everything + @item level 1, level 2 dumps etc + A level @var{n} dump dumps everything changed since the last level + @var{n}-1 dump (?) + @end itemize + @item how to use scripts for dumps (ie, the concept) + @itemize + + @item scripts to run after editing backup specs (details) + @end itemize + @item Backup Specs, what is it. + @itemize + + @item how to customize + @item actual text of script [/sp/dump/backup-specs] + @end itemize + @item Problems + @itemize + + @item rsh doesn't work + @item rtape isn't installed + @item (others?) + @end itemize + @item the @option{--incremental} option of tar + @item tapes + @itemize + + @item write protection + @item types of media, different sizes and types, useful for different things + @item files and tape marks + one tape mark between files, two at end. + @item positioning the tape + MT writes two at end of write, + backspaces over one when writing again. + @end itemize + @end itemize +@end itemize +} + +This chapter documents both the provided shell scripts and @command{tar} +options which are more specific to usage as a backup tool. + +To @dfn{back up} a file system means to create archives that contain +all the files in that file system. Those archives can then be used to +restore any or all of those files (for instance if a disk crashes or a +file is accidentally deleted). File system @dfn{backups} are also +called @dfn{dumps}. + +@menu +* Full Dumps:: Using @command{tar} to Perform Full Dumps +* Incremental Dumps:: Using @command{tar} to Perform Incremental Dumps +* Backup Levels:: Levels of Backups +* Backup Parameters:: Setting Parameters for Backups and Restoration +* Scripted Backups:: Using the Backup Scripts +* Scripted Restoration:: Using the Restore Script +@end menu + +@node Full Dumps +@section Using @command{tar} to Perform Full Dumps +@UNREVISED + +@cindex full dumps +@cindex dumps, full + +@cindex corrupted archives +Full dumps should only be made when no other people or programs +are modifying files in the file system. If files are modified while +@command{tar} is making the backup, they may not be stored properly in +the archive, in which case you won't be able to restore them if you +have to. (Files not being modified are written with no trouble, and do +not corrupt the entire archive.) + +You will want to use the @option{--label=@var{archive-label}} +(@option{-V @var{archive-label}}) option to give the archive a +volume label, so you can tell what this archive is even if the label +falls off the tape, or anything like that. + +Unless the file system you are dumping is guaranteed to fit on +one volume, you will need to use the @option{--multi-volume} (@option{-M}) option. +Make sure you have enough tapes on hand to complete the backup. + +If you want to dump each file system separately you will need to use +the @option{--one-file-system} option to prevent +@command{tar} from crossing file system boundaries when storing +(sub)directories. + +The @option{--incremental} (@option{-G}) (@pxref{Incremental Dumps}) +option is not needed, since this is a complete copy of everything in +the file system, and a full restore from this backup would only be +done onto a completely +empty disk. + +Unless you are in a hurry, and trust the @command{tar} program (and your +tapes), it is a good idea to use the @option{--verify} (@option{-W}) +option, to make sure your files really made it onto the dump properly. +This will also detect cases where the file was modified while (or just +after) it was being archived. Not all media (notably cartridge tapes) +are capable of being verified, unfortunately. + +@node Incremental Dumps +@section Using @command{tar} to Perform Incremental Dumps + +@dfn{Incremental backup} is a special form of @GNUTAR{} archive that +stores additional metadata so that exact state of the file system +can be restored when extracting the archive. + +@GNUTAR{} currently offers two options for handling incremental +backups: @option{--listed-incremental=@var{snapshot-file}} (@option{-g +@var{snapshot-file}}) and @option{--incremental} (@option{-G}). + +@xopindex{listed-incremental, described} +The option @option{--listed-incremental} instructs tar to operate on +an incremental archive with additional metadata stored in a standalone +file, called a @dfn{snapshot file}. The purpose of this file is to help +determine which files have been changed, added or deleted since the +last backup, so that the next incremental backup will contain only +modified files. The name of the snapshot file is given as an argument +to the option: + +@table @option +@item --listed-incremental=@var{file} +@itemx -g @var{file} + Handle incremental backups with snapshot data in @var{file}. +@end table + +To create an incremental backup, you would use +@option{--listed-incremental} together with @option{--create} +(@pxref{create}). For example: + +@smallexample +$ @kbd{tar --create \ + --file=archive.1.tar \ + --listed-incremental=/var/log/usr.snar \ + /usr} +@end smallexample + +This will create in @file{archive.1.tar} an incremental backup of +the @file{/usr} file system, storing additional metadata in the file +@file{/var/log/usr.snar}. If this file does not exist, it will be +created. The created archive will then be a @dfn{level 0 backup}; +please see the next section for more on backup levels. + +Otherwise, if the file @file{/var/log/usr.snar} exists, it +determines which files are modified. In this case only these files will be +stored in the archive. Suppose, for example, that after running the +above command, you delete file @file{/usr/doc/old} and create +directory @file{/usr/local/db} with the following contents: + +@smallexample +$ @kbd{ls /usr/local/db} +/usr/local/db/data +/usr/local/db/index +@end smallexample + +Some time later you create another incremental backup. You will +then see: + +@smallexample +$ @kbd{tar --create \ + --file=archive.2.tar \ + --listed-incremental=/var/log/usr.snar \ + /usr} +tar: usr/local/db: Directory is new +usr/local/db/ +usr/local/db/data +usr/local/db/index +@end smallexample + +@noindent +The created archive @file{archive.2.tar} will contain only these +three members. This archive is called a @dfn{level 1 backup}. Notice +that @file{/var/log/usr.snar} will be updated with the new data, so if +you plan to create more @samp{level 1} backups, it is necessary to +create a working copy of the snapshot file before running +@command{tar}. The above example will then be modified as follows: + +@smallexample +$ @kbd{cp /var/log/usr.snar /var/log/usr.snar-1} +$ @kbd{tar --create \ + --file=archive.2.tar \ + --listed-incremental=/var/log/usr.snar-1 \ + /usr} +@end smallexample + +@anchor{--level=0} +@xopindex{level, described} +You can force @samp{level 0} backups either by removing the snapshot +file before running @command{tar}, or by supplying the +@option{--level=0} option, e.g.: + +@smallexample +$ @kbd{tar --create \ + --file=archive.2.tar \ + --listed-incremental=/var/log/usr.snar-0 \ + --level=0 \ + /usr} +@end smallexample + +Incremental dumps depend crucially on time stamps, so the results are +unreliable if you modify a file's time stamps during dumping (e.g., +with the @option{--atime-preserve=replace} option), or if you set the clock +backwards. + +@anchor{device numbers} +@cindex Device numbers, using in incremental backups +Metadata stored in snapshot files include device numbers, which, +obviously are supposed to be non-volatile values. However, it turns +out that @acronym{NFS} devices have undependable values when an automounter +gets in the picture. This can lead to a great deal of spurious +redumping in incremental dumps, so it is somewhat useless to compare +two @acronym{NFS} devices numbers over time. The solution implemented +currently is to consider all @acronym{NFS} devices as being equal +when it comes to comparing directories; this is fairly gross, but +there does not seem to be a better way to go. + +Apart from using @acronym{NFS}, there are a number of cases where +relying on device numbers can cause spurious redumping of unmodified +files. For example, this occurs when archiving @acronym{LVM} snapshot +volumes. To avoid this, use @option{--no-check-device} option: + +@table @option +@xopindex{no-check-device, described} +@item --no-check-device +Do not rely on device numbers when preparing a list of changed files +for an incremental dump. + +@xopindex{check-device, described} +@item --check-device +Use device numbers when preparing a list of changed files +for an incremental dump. This is the default behavior. The purpose +of this option is to undo the effect of the @option{--no-check-device} +if it was given in @env{TAR_OPTIONS} environment variable +(@pxref{TAR_OPTIONS}). +@end table + +There is also another way to cope with changing device numbers. It is +described in detail in @ref{Fixing Snapshot Files}. + +Note that incremental archives use @command{tar} extensions and may +not be readable by non-@acronym{GNU} versions of the @command{tar} program. + +@xopindex{listed-incremental, using with @option{--extract}} +@xopindex{extract, using with @option{--listed-incremental}} +To extract from the incremental dumps, use +@option{--listed-incremental} together with @option{--extract} +option (@pxref{extracting files}). In this case, @command{tar} does +not need to access snapshot file, since all the data necessary for +extraction are stored in the archive itself. So, when extracting, you +can give whatever argument to @option{--listed-incremental}, the usual +practice is to use @option{--listed-incremental=/dev/null}. +Alternatively, you can use @option{--incremental}, which needs no +arguments. In general, @option{--incremental} (@option{-G}) can be +used as a shortcut for @option{--listed-incremental} when listing or +extracting incremental backups (for more information regarding this +option, @pxref{incremental-op}). + +When extracting from the incremental backup @GNUTAR{} attempts to +restore the exact state the file system had when the archive was +created. In particular, it will @emph{delete} those files in the file +system that did not exist in their directories when the archive was +created. If you have created several levels of incremental files, +then in order to restore the exact contents the file system had when +the last level was created, you will need to restore from all backups +in turn. Continuing our example, to restore the state of @file{/usr} +file system, one would do@footnote{Notice, that since both archives +were created without @option{-P} option (@pxref{absolute}), these +commands should be run from the root file system.}: + +@smallexample +$ @kbd{tar --extract \ + --listed-incremental=/dev/null \ + --file archive.1.tar} +$ @kbd{tar --extract \ + --listed-incremental=/dev/null \ + --file archive.2.tar} +@end smallexample + +To list the contents of an incremental archive, use @option{--list} +(@pxref{list}), as usual. To obtain more information about the +archive, use @option{--listed-incremental} or @option{--incremental} +combined with two @option{--verbose} options@footnote{Two +@option{--verbose} options were selected to avoid breaking usual +verbose listing output (@option{--list --verbose}) when using in +scripts. + +@xopindex{incremental, using with @option{--list}} +@xopindex{listed-incremental, using with @option{--list}} +@xopindex{list, using with @option{--incremental}} +@xopindex{list, using with @option{--listed-incremental}} +Versions of @GNUTAR{} up to 1.15.1 used to dump verbatim binary +contents of the DUMPDIR header (with terminating nulls) when +@option{--incremental} or @option{--listed-incremental} option was +given, no matter what the verbosity level. This behavior, and, +especially, the binary output it produced were considered inconvenient +and were changed in version 1.16.}: + +@smallexample +@kbd{tar --list --incremental --verbose --verbose archive.tar} +@end smallexample + +This command will print, for each directory in the archive, the list +of files in that directory at the time the archive was created. This +information is put out in a format which is both human-readable and +unambiguous for a program: each file name is printed as + +@smallexample +@var{x} @var{file} +@end smallexample + +@noindent +where @var{x} is a letter describing the status of the file: @samp{Y} +if the file is present in the archive, @samp{N} if the file is not +included in the archive, or a @samp{D} if the file is a directory (and +is included in the archive). @xref{Dumpdir}, for the detailed +description of dumpdirs and status codes. Each such +line is terminated by a newline character. The last line is followed +by an additional newline to indicate the end of the data. + +@anchor{incremental-op}The option @option{--incremental} (@option{-G}) +gives the same behavior as @option{--listed-incremental} when used +with @option{--list} and @option{--extract} options. When used with +@option{--create} option, it creates an incremental archive without +creating snapshot file. Thus, it is impossible to create several +levels of incremental backups with @option{--incremental} option. + +@node Backup Levels +@section Levels of Backups + +An archive containing all the files in the file system is called a +@dfn{full backup} or @dfn{full dump}. You could insure your data by +creating a full dump every day. This strategy, however, would waste a +substantial amount of archive media and user time, as unchanged files +are daily re-archived. + +It is more efficient to do a full dump only occasionally. To back up +files between full dumps, you can use @dfn{incremental dumps}. A @dfn{level +one} dump archives all the files that have changed since the last full +dump. + +A typical dump strategy would be to perform a full dump once a week, +and a level one dump once a day. This means some versions of files +will in fact be archived more than once, but this dump strategy makes +it possible to restore a file system to within one day of accuracy by +only extracting two archives---the last weekly (full) dump and the +last daily (level one) dump. The only information lost would be in +files changed or created since the last daily backup. (Doing dumps +more than once a day is usually not worth the trouble.) + +@GNUTAR{} comes with scripts you can use to do full +and level-one (actually, even level-two and so on) dumps. Using +scripts (shell programs) to perform backups and restoration is a +convenient and reliable alternative to typing out file name lists +and @command{tar} commands by hand. + +Before you use these scripts, you need to edit the file +@file{backup-specs}, which specifies parameters used by the backup +scripts and by the restore script. This file is usually located +in @file{/etc/backup} directory. @xref{Backup Parameters}, for its +detailed description. Once the backup parameters are set, you can +perform backups or restoration by running the appropriate script. + +The name of the backup script is @code{backup}. The name of the +restore script is @code{restore}. The following sections describe +their use in detail. + +@emph{Please Note:} The backup and restoration scripts are +designed to be used together. While it is possible to restore files by +hand from an archive which was created using a backup script, and to create +an archive by hand which could then be extracted using the restore script, +it is easier to use the scripts. @xref{Incremental Dumps}, before +making such an attempt. + +@node Backup Parameters +@section Setting Parameters for Backups and Restoration + +The file @file{backup-specs} specifies backup parameters for the +backup and restoration scripts provided with @command{tar}. You must +edit @file{backup-specs} to fit your system configuration and schedule +before using these scripts. + +Syntactically, @file{backup-specs} is a shell script, containing +mainly variable assignments. However, any valid shell construct +is allowed in this file. Particularly, you may wish to define +functions within that script (e.g., see @code{RESTORE_BEGIN} below). +For more information about shell script syntax, please refer to +@url{http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html#ta +g_02, the definition of the Shell Command Language}. See also +@ref{Top,,Bash Features,bashref,Bash Reference Manual}. + +The shell variables controlling behavior of @code{backup} and +@code{restore} are described in the following subsections. + +@menu +* General-Purpose Variables:: +* Magnetic Tape Control:: +* User Hooks:: +* backup-specs example:: An Example Text of @file{Backup-specs} +@end menu + +@node General-Purpose Variables +@subsection General-Purpose Variables + +@defvr {Backup variable} ADMINISTRATOR +The user name of the backup administrator. @code{Backup} scripts +sends a backup report to this address. +@end defvr + +@defvr {Backup variable} BACKUP_HOUR +The hour at which the backups are done. This can be a number from 0 +to 23, or the time specification in form @var{hours}:@var{minutes}, +or the string @samp{now}. + +This variable is used by @code{backup}. Its value may be overridden +using @option{--time} option (@pxref{Scripted Backups}). +@end defvr + +@defvr {Backup variable} TAPE_FILE + +The device @command{tar} writes the archive to. If @var{TAPE_FILE} +is a remote archive (@pxref{remote-dev}), backup script will suppose +that your @command{mt} is able to access remote devices. If @var{RSH} +(@pxref{RSH}) is set, @option{--rsh-command} option will be added to +invocations of @command{mt}. +@end defvr + +@defvr {Backup variable} BLOCKING + +The blocking factor @command{tar} will use when writing the dump archive. +@xref{Blocking Factor}. +@end defvr + +@defvr {Backup variable} BACKUP_DIRS + +A list of file systems to be dumped (for @code{backup}), or restored +(for @code{restore}). You can include any directory +name in the list --- subdirectories on that file system will be +included, regardless of how they may look to other networked machines. +Subdirectories on other file systems will be ignored. + +The host name specifies which host to run @command{tar} on, and should +normally be the host that actually contains the file system. However, +the host machine must have @GNUTAR{} installed, and +must be able to access the directory containing the backup scripts and +their support files using the same file name that is used on the +machine where the scripts are run (i.e., what @command{pwd} will print +when in that directory on that machine). If the host that contains +the file system does not have this capability, you can specify another +host as long as it can access the file system through @acronym{NFS}. + +If the list of file systems is very long you may wish to put it +in a separate file. This file is usually named +@file{/etc/backup/dirs}, but this name may be overridden in +@file{backup-specs} using @code{DIRLIST} variable. +@end defvr + +@defvr {Backup variable} DIRLIST + +The name of the file that contains a list of file systems to backup +or restore. By default it is @file{/etc/backup/dirs}. +@end defvr + +@defvr {Backup variable} BACKUP_FILES + +A list of individual files to be dumped (for @code{backup}), or restored +(for @code{restore}). These should be accessible from the machine on +which the backup script is run. + +If the list of individual files is very long you may wish to store it +in a separate file. This file is usually named +@file{/etc/backup/files}, but this name may be overridden in +@file{backup-specs} using @code{FILELIST} variable. +@end defvr + +@defvr {Backup variable} FILELIST + +The name of the file that contains a list of individual files to backup +or restore. By default it is @file{/etc/backup/files}. +@end defvr + +@defvr {Backup variable} MT + +Full file name of @command{mt} binary. +@end defvr + +@defvr {Backup variable} RSH +@anchor{RSH} +Full file name of @command{rsh} binary or its equivalent. You may wish to +set it to @code{ssh}, to improve security. In this case you will have +to use public key authentication. +@end defvr + +@defvr {Backup variable} RSH_COMMAND + +Full file name of @command{rsh} binary on remote machines. This will +be passed via @option{--rsh-command} option to the remote invocation +of @GNUTAR{}. +@end defvr + +@defvr {Backup variable} VOLNO_FILE + +Name of temporary file to hold volume numbers. This needs to be accessible +by all the machines which have file systems to be dumped. +@end defvr + +@defvr {Backup variable} XLIST + +Name of @dfn{exclude file list}. An @dfn{exclude file list} is a file +located on the remote machine and containing the list of files to +be excluded from the backup. Exclude file lists are searched in +/etc/tar-backup directory. A common use for exclude file lists +is to exclude files containing security-sensitive information +(e.g., @file{/etc/shadow} from backups). + +This variable affects only @code{backup}. +@end defvr + +@defvr {Backup variable} SLEEP_TIME + +Time to sleep between dumps of any two successive file systems + +This variable affects only @code{backup}. +@end defvr + +@defvr {Backup variable} DUMP_REMIND_SCRIPT + +Script to be run when it's time to insert a new tape in for the next +volume. Administrators may want to tailor this script for their site. +If this variable isn't set, @GNUTAR{} will display its built-in +prompt, and will expect confirmation from the console. For the +description of the default prompt, see @ref{change volume prompt}. + +@end defvr + +@defvr {Backup variable} SLEEP_MESSAGE + +Message to display on the terminal while waiting for dump time. Usually +this will just be some literal text. +@end defvr + +@defvr {Backup variable} TAR + +Full file name of the @GNUTAR{} executable. If this is not set, backup +scripts will search @command{tar} in the current shell path. +@end defvr + +@node Magnetic Tape Control +@subsection Magnetic Tape Control + +Backup scripts access tape device using special @dfn{hook functions}. +These functions take a single argument --- the name of the tape +device. Their names are kept in the following variables: + +@defvr {Backup variable} MT_BEGIN +The name of @dfn{begin} function. This function is called before +accessing the drive. By default it retensions the tape: + +@smallexample +MT_BEGIN=mt_begin + +mt_begin() @{ + mt -f "$1" retension +@} +@end smallexample +@end defvr + +@defvr {Backup variable} MT_REWIND +The name of @dfn{rewind} function. The default definition is as +follows: + +@smallexample +MT_REWIND=mt_rewind + +mt_rewind() @{ + mt -f "$1" rewind +@} +@end smallexample + +@end defvr + +@defvr {Backup variable} MT_OFFLINE +The name of the function switching the tape off line. By default +it is defined as follows: + +@smallexample +MT_OFFLINE=mt_offline + +mt_offline() @{ + mt -f "$1" offl +@} +@end smallexample +@end defvr + +@defvr {Backup variable} MT_STATUS +The name of the function used to obtain the status of the archive device, +including error count. Default definition: + +@smallexample +MT_STATUS=mt_status + +mt_status() @{ + mt -f "$1" status +@} +@end smallexample +@end defvr + +@node User Hooks +@subsection User Hooks + +@dfn{User hooks} are shell functions executed before and after +each @command{tar} invocation. Thus, there are @dfn{backup +hooks}, which are executed before and after dumping each file +system, and @dfn{restore hooks}, executed before and +after restoring a file system. Each user hook is a shell function +taking four arguments: + +@deffn {User Hook Function} hook @var{level} @var{host} @var{fs} @var{fsname} +Its arguments are: + +@table @var +@item level +Current backup or restore level. + +@item host +Name or IP address of the host machine being dumped or restored. + +@item fs +Full file name of the file system being dumped or restored. + +@item fsname +File system name with directory separators replaced with colons. This +is useful, e.g., for creating unique files. +@end table +@end deffn + +Following variables keep the names of user hook functions: + +@defvr {Backup variable} DUMP_BEGIN +Dump begin function. It is executed before dumping the file system. +@end defvr + +@defvr {Backup variable} DUMP_END +Executed after dumping the file system. +@end defvr + +@defvr {Backup variable} RESTORE_BEGIN +Executed before restoring the file system. +@end defvr + +@defvr {Backup variable} RESTORE_END +Executed after restoring the file system. +@end defvr + +@node backup-specs example +@subsection An Example Text of @file{Backup-specs} + +The following is an example of @file{backup-specs}: + +@smallexample +# site-specific parameters for file system backup. + +ADMINISTRATOR=friedman +BACKUP_HOUR=1 +TAPE_FILE=/dev/nrsmt0 + +# Use @code{ssh} instead of the less secure @code{rsh} +RSH=/usr/bin/ssh +RSH_COMMAND=/usr/bin/ssh + +# Override MT_STATUS function: +my_status() @{ + mts -t $TAPE_FILE +@} +MT_STATUS=my_status + +# Disable MT_OFFLINE function +MT_OFFLINE=: + +BLOCKING=124 +BACKUP_DIRS=" + albert:/fs/fsf + apple-gunkies:/gd + albert:/fs/gd2 + albert:/fs/gp + geech:/usr/jla + churchy:/usr/roland + albert:/ + albert:/usr + apple-gunkies:/ + apple-gunkies:/usr + gnu:/hack + gnu:/u + apple-gunkies:/com/mailer/gnu + apple-gunkies:/com/archive/gnu" + +BACKUP_FILES="/com/mailer/aliases /com/mailer/league*[a-z]" + +@end smallexample + +@node Scripted Backups +@section Using the Backup Scripts + +The syntax for running a backup script is: + +@smallexample +backup --level=@var{level} --time=@var{time} +@end smallexample + +The @option{--level} option requests the dump level. Thus, to produce +a full dump, specify @code{--level=0} (this is the default, so +@option{--level} may be omitted if its value is +@code{0})@footnote{For backward compatibility, the @code{backup} will also +try to deduce the requested dump level from the name of the +script itself. If the name consists of a string @samp{level-} +followed by a single decimal digit, that digit is taken as +the dump level number. Thus, you may create a link from @code{backup} +to @code{level-1} and then run @code{level-1} whenever you need to +create a level one dump.}. + +The @option{--time} option determines when should the backup be +run. @var{Time} may take three forms: + +@table @asis +@item @var{hh}:@var{mm} + +The dump must be run at @var{hh} hours @var{mm} minutes. + +@item @var{hh} + +The dump must be run at @var{hh} hours. + +@item now + +The dump must be run immediately. +@end table + +You should start a script with a tape or disk mounted. Once you +start a script, it prompts you for new tapes or disks as it +needs them. Media volumes don't have to correspond to archive +files --- a multi-volume archive can be started in the middle of a +tape that already contains the end of another multi-volume archive. +The @code{restore} script prompts for media by its archive volume, +so to avoid an error message you should keep track of which tape +(or disk) contains which volume of the archive (@pxref{Scripted +Restoration}). + +The backup scripts write two files on the file system. The first is a +record file in @file{/etc/tar-backup/}, which is used by the scripts +to store and retrieve information about which files were dumped. This +file is not meant to be read by humans, and should not be deleted by +them. @xref{Snapshot Files}, for a more detailed explanation of this +file. + +The second file is a log file containing the names of the file systems +and files dumped, what time the backup was made, and any error +messages that were generated, as well as how much space was left in +the media volume after the last volume of the archive was written. +You should check this log file after every backup. The file name is +@file{log-@var{mm-dd-yyyy}-level-@var{n}}, where @var{mm-dd-yyyy} +represents current date, and @var{n} represents current dump level number. + +The script also prints the name of each system being dumped to the +standard output. + +Following is the full list of options accepted by @code{backup} +script: + +@table @option +@item -l @var{level} +@itemx --level=@var{level} +Do backup level @var{level} (default 0). + +@item -f +@itemx --force +Force backup even if today's log file already exists. + +@item -v[@var{level}] +@itemx --verbose[=@var{level}] +Set verbosity level. The higher the level is, the more debugging +information will be output during execution. Default @var{level} +is 100, which means the highest debugging level. + +@item -t @var{start-time} +@itemx --time=@var{start-time} +Wait till @var{time}, then do backup. + +@item -h +@itemx --help +Display short help message and exit. + +@item -V +@itemx --version +Display information about the program's name, version, origin and legal +status, all on standard output, and then exit successfully. +@end table + + +@node Scripted Restoration +@section Using the Restore Script + +To restore files that were archived using a scripted backup, use the +@code{restore} script. Its usage is quite straightforward. In the +simplest form, invoke @code{restore --all}, it will +then restore all the file systems and files specified in +@file{backup-specs} (@pxref{General-Purpose Variables,BACKUP_DIRS}). + +You may select the file systems (and/or files) to restore by +giving @code{restore} a list of @dfn{patterns} in its command +line. For example, running + +@smallexample +restore 'albert:*' +@end smallexample + +@noindent +will restore all file systems on the machine @samp{albert}. A more +complicated example: + +@smallexample +restore 'albert:*' '*:/var' +@end smallexample + +@noindent +This command will restore all file systems on the machine @samp{albert} +as well as @file{/var} file system on all machines. + +By default @code{restore} will start restoring files from the lowest +available dump level (usually zero) and will continue through +all available dump levels. There may be situations where such a +thorough restore is not necessary. For example, you may wish to +restore only files from the recent level one backup. To do so, +use @option{--level} option, as shown in the example below: + +@smallexample +restore --level=1 +@end smallexample + +The full list of options accepted by @code{restore} follows: + +@table @option +@item -a +@itemx --all +Restore all file systems and files specified in @file{backup-specs}. + +@item -l @var{level} +@itemx --level=@var{level} +Start restoring from the given backup level, instead of the default 0. + +@item -v[@var{level}] +@itemx --verbose[=@var{level}] +Set verbosity level. The higher the level is, the more debugging +information will be output during execution. Default @var{level} +is 100, which means the highest debugging level. + +@item -h +@itemx --help +Display short help message and exit. + +@item -V +@itemx --version +Display information about the program's name, version, origin and legal +status, all on standard output, and then exit successfully. +@end table + +You should start the restore script with the media containing the +first volume of the archive mounted. The script will prompt for other +volumes as they are needed. If the archive is on tape, you don't need +to rewind the tape to to its beginning---if the tape head is +positioned past the beginning of the archive, the script will rewind +the tape as needed. @xref{Tape Positioning}, for a discussion of tape +positioning. + +@quotation +@strong{Warning:} The script will delete files from the active file +system if they were not in the file system when the archive was made. +@end quotation + +@xref{Incremental Dumps}, for an explanation of how the script makes +that determination. + +@node Choosing +@chapter Choosing Files and Names for @command{tar} + +Certain options to @command{tar} enable you to specify a name for your +archive. Other options let you decide which files to include or exclude +from the archive, based on when or whether files were modified, whether +the file names do or don't match specified patterns, or whether files +are in specified directories. + +This chapter discusses these options in detail. + +@menu +* file:: Choosing the Archive's Name +* Selecting Archive Members:: +* files:: Reading Names from a File +* exclude:: Excluding Some Files +* wildcards:: Wildcards Patterns and Matching +* quoting styles:: Ways of Quoting Special Characters in Names +* transform:: Modifying File and Member Names +* after:: Operating Only on New Files +* recurse:: Descending into Directories +* one:: Crossing File System Boundaries +@end menu + +@node file +@section Choosing and Naming Archive Files + +@cindex Naming an archive +@cindex Archive Name +@cindex Choosing an archive file +@cindex Where is the archive? +@opindex file +By default, @command{tar} uses an archive file name that was compiled when +it was built on the system; usually this name refers to some physical +tape drive on the machine. However, the person who installed @command{tar} +on the system may not have set the default to a meaningful value as far as +most users are concerned. As a result, you will usually want to tell +@command{tar} where to find (or create) the archive. The +@option{--file=@var{archive-name}} (@option{-f @var{archive-name}}) +option allows you to either specify or name a file to use as the archive +instead of the default archive file location. + +@table @option +@xopindex{file, short description} +@item --file=@var{archive-name} +@itemx -f @var{archive-name} +Name the archive to create or operate on. Use in conjunction with +any operation. +@end table + +For example, in this @command{tar} command, + +@smallexample +$ @kbd{tar -cvf collection.tar blues folk jazz} +@end smallexample + +@noindent +@file{collection.tar} is the name of the archive. It must directly +follow the @option{-f} option, since whatever directly follows @option{-f} +@emph{will} end up naming the archive. If you neglect to specify an +archive name, you may end up overwriting a file in the working directory +with the archive you create since @command{tar} will use this file's name +for the archive name. + +An archive can be saved as a file in the file system, sent through a +pipe or over a network, or written to an I/O device such as a tape, +floppy disk, or CD write drive. + +@cindex Writing new archives +@cindex Archive creation +If you do not name the archive, @command{tar} uses the value of the +environment variable @env{TAPE} as the file name for the archive. If +that is not available, @command{tar} uses a default, compiled-in archive +name, usually that for tape unit zero (i.e., @file{/dev/tu00}). + +@cindex Standard input and output +@cindex tar to standard input and output +If you use @file{-} as an @var{archive-name}, @command{tar} reads the +archive from standard input (when listing or extracting files), or +writes it to standard output (when creating an archive). If you use +@file{-} as an @var{archive-name} when modifying an archive, +@command{tar} reads the original archive from its standard input and +writes the entire new archive to its standard output. + +The following example is a convenient way of copying directory +hierarchy from @file{sourcedir} to @file{targetdir}. + +@smallexample +$ @kbd{(cd sourcedir; tar -cf - .) | (cd targetdir; tar -xpf -)} +@end smallexample + +The @option{-C} option allows to avoid using subshells: + +@smallexample +$ @kbd{tar -C sourcedir -cf - . | tar -C targetdir -xpf -} +@end smallexample + +In both examples above, the leftmost @command{tar} invocation archives +the contents of @file{sourcedir} to the standard output, while the +rightmost one reads this archive from its standard input and +extracts it. The @option{-p} option tells it to restore permissions +of the extracted files. + +@cindex Remote devices +@cindex tar to a remote device +@anchor{remote-dev} +To specify an archive file on a device attached to a remote machine, +use the following: + +@smallexample +@kbd{--file=@var{hostname}:/@var{dev}/@var{file-name}} +@end smallexample + +@noindent +@command{tar} will set up the remote connection, if possible, and +prompt you for a username and password. If you use +@option{--file=@@@var{hostname}:/@var{dev}/@var{file-name}}, @command{tar} +will attempt to set up the remote connection using your username +as the username on the remote machine. + +@cindex Local and remote archives +@anchor{local and remote archives} +If the archive file name includes a colon (@samp{:}), then it is assumed +to be a file on another machine. If the archive file is +@samp{@var{user}@@@var{host}:@var{file}}, then @var{file} is used on the +host @var{host}. The remote host is accessed using the @command{rsh} +program, with a username of @var{user}. If the username is omitted +(along with the @samp{@@} sign), then your user name will be used. +(This is the normal @command{rsh} behavior.) It is necessary for the +remote machine, in addition to permitting your @command{rsh} access, to +have the @file{rmt} program installed (this command is included in +the @GNUTAR{} distribution and by default is installed under +@file{@var{prefix}/libexec/rmt}, where @var{prefix} means your +installation prefix). If you need to use a file whose name includes a +colon, then the remote tape drive behavior +can be inhibited by using the @option{--force-local} option. + +When the archive is being created to @file{/dev/null}, @GNUTAR{} +tries to minimize input and output operations. The Amanda backup +system, when used with @GNUTAR{}, has an initial sizing pass which +uses this feature. + +@node Selecting Archive Members +@section Selecting Archive Members +@cindex Specifying files to act on +@cindex Specifying archive members + +@dfn{File Name arguments} specify which files in the file system +@command{tar} operates on, when creating or adding to an archive, or which +archive members @command{tar} operates on, when reading or deleting from +an archive. @xref{Operations}. + +To specify file names, you can include them as the last arguments on +the command line, as follows: +@smallexample +@kbd{tar} @var{operation} [@var{option1} @var{option2} @dots{}] [@var{file name-1} @var{file name-2} @dots{}] +@end smallexample + +If a file name begins with dash (@samp{-}), precede it with +@option{--add-file} option to prevent it from being treated as an +option. + +@anchor{input name quoting} +By default @GNUTAR{} attempts to @dfn{unquote} each file or member +name, replacing @dfn{escape sequences} according to the following +table: + +@multitable @columnfractions 0.20 0.60 +@headitem Escape @tab Replaced with +@item \a @tab Audible bell (@acronym{ASCII} 7) +@item \b @tab Backspace (@acronym{ASCII} 8) +@item \f @tab Form feed (@acronym{ASCII} 12) +@item \n @tab New line (@acronym{ASCII} 10) +@item \r @tab Carriage return (@acronym{ASCII} 13) +@item \t @tab Horizontal tabulation (@acronym{ASCII} 9) +@item \v @tab Vertical tabulation (@acronym{ASCII} 11) +@item \? @tab @acronym{ASCII} 127 +@item \@var{n} @tab @acronym{ASCII} @var{n} (@var{n} should be an octal number + of up to 3 digits) +@end multitable + +A backslash followed by any other symbol is retained. + +This default behavior is controlled by the following command line +option: + +@table @option +@opindex unquote +@item --unquote +Enable unquoting input file or member names (default). + +@opindex no-unquote +@item --no-unquote +Disable unquoting input file or member names. +@end table + +If you specify a directory name as a file name argument, all the files +in that directory are operated on by @command{tar}. + +If you do not specify files, @command{tar} behavior differs depending +on the operation mode as described below: + +When @command{tar} is invoked with @option{--create} (@option{-c}), +@command{tar} will stop immediately, reporting the following: + +@smallexample +@group +$ @kbd{tar cf a.tar} +tar: Cowardly refusing to create an empty archive +Try 'tar --help' or 'tar --usage' for more information. +@end group +@end smallexample + +If you specify either @option{--list} (@option{-t}) or +@option{--extract} (@option{--get}, @option{-x}), @command{tar} +operates on all the archive members in the archive. + +If run with @option{--diff} option, tar will compare the archive with +the contents of the current working directory. + +If you specify any other operation, @command{tar} does nothing. + +By default, @command{tar} takes file names from the command line. However, +there are other ways to specify file or member names, or to modify the +manner in which @command{tar} selects the files or members upon which to +operate. In general, these methods work both for specifying the names +of files and archive members. + +@node files +@section Reading Names from a File + +@cindex Reading file names from a file +@cindex Lists of file names +@cindex File Name arguments, alternatives +@cindex @command{find}, using with @command{tar} +Instead of giving the names of files or archive members on the command +line, you can put the names into a file, and then use the +@option{--files-from=@var{file-of-names}} (@option{-T +@var{file-of-names}}) option to @command{tar}. Give the name of the +file which contains the list of files to include as the argument to +@option{--files-from}. In the list, the file names should be separated by +newlines. You will frequently use this option when you have generated +the list of files to archive with the @command{find} utility. + +@table @option +@opindex files-from +@item --files-from=@var{file-name} +@itemx -T @var{file-name} +Get names to extract or create from file @var{file-name}. +@end table + +If you give a single dash as a file name for @option{--files-from}, (i.e., +you specify either @code{--files-from=-} or @code{-T -}), then the file +names are read from standard input. + +Unless you are running @command{tar} with @option{--create}, you can not use +both @code{--files-from=-} and @code{--file=-} (@code{-f -}) in the same +command. + +Any number of @option{-T} options can be given in the command line. + +The following example shows how to use @command{find} to generate a list of +files smaller than 400K in length and put that list into a file +called @file{small-files}. You can then use the @option{-T} option to +@command{tar} to specify the files from that file, @file{small-files}, to +create the archive @file{little.tgz}. (The @option{-z} option to +@command{tar} compresses the archive with @command{gzip}; @pxref{gzip} for +more information.) + +@smallexample +$ @kbd{find . -size -400 -print > small-files} +$ @kbd{tar -c -v -z -T small-files -f little.tgz} +@end smallexample + +@noindent +In the file list given by @option{-T} option, any file name beginning +with @samp{-} character is considered a @command{tar} option and is +processed accordingly@footnote{Versions of @GNUTAR{} up to 1.15.1 +recognized only @option{-C} option in file lists, and only if the +option and its argument occupied two consecutive lines.}. For example, +the common use of this feature is to change to another directory by +specifying @option{-C} option: + +@smallexample +@group +$ @kbd{cat list} +-C/etc +passwd +hosts +-C/lib +libc.a +$ @kbd{tar -c -f foo.tar --files-from list} +@end group +@end smallexample + +@noindent +In this example, @command{tar} will first switch to @file{/etc} +directory and add files @file{passwd} and @file{hosts} to the +archive. Then it will change to @file{/lib} directory and will archive +the file @file{libc.a}. Thus, the resulting archive @file{foo.tar} will +contain: + +@smallexample +@group +$ @kbd{tar tf foo.tar} +passwd +hosts +libc.a +@end group +@end smallexample + +@opindex add-file +If you happen to have a file whose name starts with @samp{-}, +precede it with @option{--add-file} option to prevent it from +being recognized as an option. For example: @code{--add-file=--my-file}. + +@menu +* nul:: +@end menu + +@node nul +@subsection @code{NUL}-Terminated File Names + +@cindex File names, terminated by @code{NUL} +@cindex @code{NUL}-terminated file names +The @option{--null} option causes +@option{--files-from=@var{file-of-names}} (@option{-T @var{file-of-names}}) +to read file names terminated by a @code{NUL} instead of a newline, so +files whose names contain newlines can be archived using +@option{--files-from}. + +@table @option +@xopindex{null, described} +@item --null +Only consider @code{NUL}-terminated file names, instead of files that +terminate in a newline. + +@xopindex{no-null, described} +@item --no-null +Undo the effect of any previous @option{--null} option. +@end table + +The @option{--null} option is just like the one in @acronym{GNU} +@command{xargs} and @command{cpio}, and is useful with the +@option{-print0} predicate of @acronym{GNU} @command{find}. In +@command{tar}, @option{--null} also disables special handling for +file names that begin with dash. + +This example shows how to use @command{find} to generate a list of files +larger than 800K in length and put that list into a file called +@file{long-files}. The @option{-print0} option to @command{find} is just +like @option{-print}, except that it separates files with a @code{NUL} +rather than with a newline. You can then run @command{tar} with both the +@option{--null} and @option{-T} options to specify that @command{tar} gets the +files from that file, @file{long-files}, to create the archive +@file{big.tgz}. The @option{--null} option to @command{tar} will cause +@command{tar} to recognize the @code{NUL} separator between files. + +@smallexample +$ @kbd{find . -size +800 -print0 > long-files} +$ @kbd{tar -c -v --null --files-from=long-files --file=big.tar} +@end smallexample + +The @option{--no-null} option can be used if you need to read both +@code{NUL}-terminated and newline-terminated files on the same command line. +For example, if @file{flist} is a newline-terminated file, then the +following command can be used to combine it with the above command: + +@smallexample +@group +$ @kbd{find . -size +800 -print0 | + tar -c -f big.tar --null -T - --no-null -T flist} +@end group +@end smallexample + +This example uses short options for typographic reasons, to avoid +very long lines. + +@GNUTAR is tries to automatically detect @code{NUL}-terminated file +lists, so in many cases it is safe to use them even without the +@option{--null} option. In this case @command{tar} will print a +warning and continue reading such a file as if @option{--null} were +actually given: + +@smallexample +@group +$ @kbd{find . -size +800 -print0 | tar -c -f big.tar -T -} +tar: -: file name read contains nul character +@end group +@end smallexample + +The null terminator, however, remains in effect only for this +particular file, any following @option{-T} options will assume +newline termination. Of course, the null autodetection applies +to these eventual surplus @option{-T} options as well. + +@node exclude +@section Excluding Some Files + +@cindex File names, excluding files by +@cindex Excluding files by name and pattern +@cindex Excluding files by file system +@opindex exclude +@opindex exclude-from +To avoid operating on files whose names match a particular pattern, +use the @option{--exclude} or @option{--exclude-from} options. + +@table @option +@opindex exclude +@item --exclude=@var{pattern} +Causes @command{tar} to ignore files that match the @var{pattern}. +@end table + +@findex exclude +The @option{--exclude=@var{pattern}} option prevents any file or +member whose name matches the shell wildcard (@var{pattern}) from +being operated on. +For example, to create an archive with all the contents of the directory +@file{src} except for files whose names end in @file{.o}, use the +command @samp{tar -cf src.tar --exclude='*.o' src}. + +You may give multiple @option{--exclude} options. + +@table @option +@opindex exclude-from +@item --exclude-from=@var{file} +@itemx -X @var{file} +Causes @command{tar} to ignore files that match the patterns listed in +@var{file}. +@end table + +@findex exclude-from +Use the @option{--exclude-from} option to read a +list of patterns, one per line, from @var{file}; @command{tar} will +ignore files matching those patterns. Thus if @command{tar} is +called as @w{@samp{tar -c -X foo .}} and the file @file{foo} contains a +single line @file{*.o}, no files whose names end in @file{.o} will be +added to the archive. + +Notice, that lines from @var{file} are read verbatim. One of the +frequent errors is leaving some extra whitespace after a file name, +which is difficult to catch using text editors. + +However, empty lines are OK. + +@table @option +@cindex version control system, excluding files +@cindex VCS, excluding files +@cindex SCCS, excluding files +@cindex RCS, excluding files +@cindex CVS, excluding files +@cindex SVN, excluding files +@cindex git, excluding files +@cindex Bazaar, excluding files +@cindex Arch, excluding files +@cindex Mercurial, excluding files +@cindex Darcs, excluding files +@opindex exclude-vcs +@item --exclude-vcs +Exclude files and directories used by following version control +systems: @samp{CVS}, @samp{RCS}, @samp{SCCS}, @samp{SVN}, @samp{Arch}, +@samp{Bazaar}, @samp{Mercurial}, and @samp{Darcs}. + +As of version @value{VERSION}, the following files are excluded: + +@itemize @bullet +@item @file{CVS/}, and everything under it +@item @file{RCS/}, and everything under it +@item @file{SCCS/}, and everything under it +@item @file{.git/}, and everything under it +@item @file{.gitignore} +@item @file{.cvsignore} +@item @file{.svn/}, and everything under it +@item @file{.arch-ids/}, and everything under it +@item @file{@{arch@}/}, and everything under it +@item @file{=RELEASE-ID} +@item @file{=meta-update} +@item @file{=update} +@item @file{.bzr} +@item @file{.bzrignore} +@item @file{.bzrtags} +@item @file{.hg} +@item @file{.hgignore} +@item @file{.hgrags} +@item @file{_darcs} +@end itemize + +@opindex exclude-backups +@item --exclude-backups +Exclude backup and lock files. This option causes exclusion of files +that match the following shell globbing patterns: + +@table @asis +@item .#* +@item *~ +@item #*# +@end table + +@end table + +@findex exclude-caches +When creating an archive, the @option{--exclude-caches} option family +causes @command{tar} to exclude all directories that contain a @dfn{cache +directory tag}. A cache directory tag is a short file with the +well-known name @file{CACHEDIR.TAG} and having a standard header +specified in @url{http://www.brynosaurus.com/cachedir/spec.html}. +Various applications write cache directory tags into directories they +use to hold regenerable, non-precious data, so that such data can be +more easily excluded from backups. + +There are three @samp{exclude-caches} options, each providing a different +exclusion semantics: + +@table @option +@opindex exclude-caches +@item --exclude-caches +Do not archive the contents of the directory, but archive the +directory itself and the @file{CACHEDIR.TAG} file. + +@opindex exclude-caches-under +@item --exclude-caches-under +Do not archive the contents of the directory, nor the +@file{CACHEDIR.TAG} file, archive only the directory itself. + +@opindex exclude-caches-all +@item --exclude-caches-all +Omit directories containing @file{CACHEDIR.TAG} file entirely. +@end table + +@findex exclude-tag +Another option family, @option{--exclude-tag}, provides a generalization of +this concept. It takes a single argument, a file name to look for. +Any directory that contains this file will be excluded from the dump. +Similarly to @samp{exclude-caches}, there are three options in this +option family: + +@table @option +@opindex exclude-tag +@item --exclude-tag=@var{file} +Do not dump the contents of the directory, but dump the +directory itself and the @var{file}. + +@opindex exclude-tag-under +@item --exclude-tag-under=@var{file} +Do not dump the contents of the directory, nor the +@var{file}, archive only the directory itself. + +@opindex exclude-tag-all +@item --exclude-tag-all=@var{file} +Omit directories containing @var{file} file entirely. +@end table + +Multiple @option{--exclude-tag*} options can be given. + +For example, given this directory: + +@smallexample +@group +$ @kbd{find dir} +dir +dir/blues +dir/jazz +dir/folk +dir/folk/tagfile +dir/folk/sanjuan +dir/folk/trote +@end group +@end smallexample + +The @option{--exclude-tag} will produce the following: + +@smallexample +$ @kbd{tar -cf archive.tar --exclude-tag=tagfile -v dir} +dir/ +dir/blues +dir/jazz +dir/folk/ +tar: dir/folk/: contains a cache directory tag tagfile; + contents not dumped +dir/folk/tagfile +@end smallexample + +Both the @file{dir/folk} directory and its tagfile are preserved in +the archive, however the rest of files in this directory are not. + +Now, using the @option{--exclude-tag-under} option will exclude +@file{tagfile} from the dump, while still preserving the directory +itself, as shown in this example: + +@smallexample +$ @kbd{tar -cf archive.tar --exclude-tag-under=tagfile -v dir} +dir/ +dir/blues +dir/jazz +dir/folk/ +./tar: dir/folk/: contains a cache directory tag tagfile; + contents not dumped +@end smallexample + +Finally, using @option{--exclude-tag-all} omits the @file{dir/folk} +directory entirely: + +@smallexample +$ @kbd{tar -cf archive.tar --exclude-tag-all=tagfile -v dir} +dir/ +dir/blues +dir/jazz +./tar: dir/folk/: contains a cache directory tag tagfile; + directory not dumped +@end smallexample + +@menu +* problems with exclude:: +@end menu + +@node problems with exclude +@unnumberedsubsec Problems with Using the @code{exclude} Options + +@xopindex{exclude, potential problems with} +Some users find @samp{exclude} options confusing. Here are some common +pitfalls: + +@itemize @bullet +@item +The main operating mode of @command{tar} does not act on a file name +explicitly listed on the command line, if one of its file name +components is excluded. In the example above, if +you create an archive and exclude files that end with @samp{*.o}, but +explicitly name the file @samp{dir.o/foo} after all the options have been +listed, @samp{dir.o/foo} will be excluded from the archive. + +@item +You can sometimes confuse the meanings of @option{--exclude} and +@option{--exclude-from}. Be careful: use @option{--exclude} when files +to be excluded are given as a pattern on the command line. Use +@option{--exclude-from} to introduce the name of a file which contains +a list of patterns, one per line; each of these patterns can exclude +zero, one, or many files. + +@item +When you use @option{--exclude=@var{pattern}}, be sure to quote the +@var{pattern} parameter, so @GNUTAR{} sees wildcard characters +like @samp{*}. If you do not do this, the shell might expand the +@samp{*} itself using files at hand, so @command{tar} might receive a +list of files instead of one pattern, or none at all, making the +command somewhat illegal. This might not correspond to what you want. + +For example, write: + +@smallexample +$ @kbd{tar -c -f @var{archive.tar} --exclude '*.o' @var{directory}} +@end smallexample + +@noindent +rather than: + +@smallexample +# @emph{Wrong!} +$ @kbd{tar -c -f @var{archive.tar} --exclude *.o @var{directory}} +@end smallexample + +@item +You must use use shell syntax, or globbing, rather than @code{regexp} +syntax, when using exclude options in @command{tar}. If you try to use +@code{regexp} syntax to describe files to be excluded, your command +might fail. + +@item +@FIXME{The change in semantics must have occurred before 1.11, +so I doubt if it is worth mentioning at all. Anyway, should at +least specify in which version the semantics changed.} +In earlier versions of @command{tar}, what is now the +@option{--exclude-from} option was called @option{--exclude} instead. +Now, @option{--exclude} applies to patterns listed on the command +line and @option{--exclude-from} applies to patterns listed in a +file. + +@end itemize + +@node wildcards +@section Wildcards Patterns and Matching + +@dfn{Globbing} is the operation by which @dfn{wildcard} characters, +@samp{*} or @samp{?} for example, are replaced and expanded into all +existing files matching the given pattern. @GNUTAR{} can use wildcard +patterns for matching (or globbing) archive members when extracting +from or listing an archive. Wildcard patterns are also used for +verifying volume labels of @command{tar} archives. This section has the +purpose of explaining wildcard syntax for @command{tar}. + +@FIXME{the next few paragraphs need work.} + +A @var{pattern} should be written according to shell syntax, using wildcard +characters to effect globbing. Most characters in the pattern stand +for themselves in the matched string, and case is significant: @samp{a} +will match only @samp{a}, and not @samp{A}. The character @samp{?} in the +pattern matches any single character in the matched string. The character +@samp{*} in the pattern matches zero, one, or more single characters in +the matched string. The character @samp{\} says to take the following +character of the pattern @emph{literally}; it is useful when one needs to +match the @samp{?}, @samp{*}, @samp{[} or @samp{\} characters, themselves. + +The character @samp{[}, up to the matching @samp{]}, introduces a character +class. A @dfn{character class} is a list of acceptable characters +for the next single character of the matched string. For example, +@samp{[abcde]} would match any of the first five letters of the alphabet. +Note that within a character class, all of the ``special characters'' +listed above other than @samp{\} lose their special meaning; for example, +@samp{[-\\[*?]]} would match any of the characters, @samp{-}, @samp{\}, +@samp{[}, @samp{*}, @samp{?}, or @samp{]}. (Due to parsing constraints, +the characters @samp{-} and @samp{]} must either come @emph{first} or +@emph{last} in a character class.) + +@cindex Excluding characters from a character class +@cindex Character class, excluding characters from +If the first character of the class after the opening @samp{[} +is @samp{!} or @samp{^}, then the meaning of the class is reversed. +Rather than listing character to match, it lists those characters which +are @emph{forbidden} as the next single character of the matched string. + +Other characters of the class stand for themselves. The special +construction @samp{[@var{a}-@var{e}]}, using an hyphen between two +letters, is meant to represent all characters between @var{a} and +@var{e}, inclusive. + +@FIXME{need to add a sentence or so here to make this clear for those +who don't have dan around.} + +Periods (@samp{.}) or forward slashes (@samp{/}) are not considered +special for wildcard matches. However, if a pattern completely matches +a directory prefix of a matched string, then it matches the full matched +string: thus, excluding a directory also excludes all the files beneath it. + +@menu +* controlling pattern-matching:: +@end menu + +@node controlling pattern-matching +@unnumberedsubsec Controlling Pattern-Matching + +For the purposes of this section, we call @dfn{exclusion members} all +member names obtained while processing @option{--exclude} and +@option{--exclude-from} options, and @dfn{inclusion members} those +member names that were given in the command line or read from the file +specified with @option{--files-from} option. + +These two pairs of member lists are used in the following operations: +@option{--diff}, @option{--extract}, @option{--list}, +@option{--update}. + +There are no inclusion members in create mode (@option{--create} and +@option{--append}), since in this mode the names obtained from the +command line refer to @emph{files}, not archive members. + +By default, inclusion members are compared with archive members +literally @footnote{Notice that earlier @GNUTAR{} versions used +globbing for inclusion members, which contradicted to UNIX98 +specification and was not documented. @xref{Changes}, for more +information on this and other changes.} and exclusion members are +treated as globbing patterns. For example: + +@smallexample +@group +$ @kbd{tar tf foo.tar} +a.c +b.c +a.txt +[remarks] +# @i{Member names are used verbatim:} +$ @kbd{tar -xf foo.tar -v '[remarks]'} +[remarks] +# @i{Exclude member names are globbed:} +$ @kbd{tar -xf foo.tar -v --exclude '*.c'} +a.txt +[remarks] +@end group +@end smallexample + +This behavior can be altered by using the following options: + +@table @option +@opindex wildcards +@item --wildcards +Treat all member names as wildcards. + +@opindex no-wildcards +@item --no-wildcards +Treat all member names as literal strings. +@end table + +Thus, to extract files whose names end in @samp{.c}, you can use: + +@smallexample +$ @kbd{tar -xf foo.tar -v --wildcards '*.c'} +a.c +b.c +@end smallexample + +@noindent +Notice quoting of the pattern to prevent the shell from interpreting +it. + +The effect of @option{--wildcards} option is canceled by +@option{--no-wildcards}. This can be used to pass part of +the command line arguments verbatim and other part as globbing +patterns. For example, the following invocation: + +@smallexample +$ @kbd{tar -xf foo.tar --wildcards '*.txt' --no-wildcards '[remarks]'} +@end smallexample + +@noindent +instructs @command{tar} to extract from @file{foo.tar} all files whose +names end in @samp{.txt} and the file named @file{[remarks]}. + +Normally, a pattern matches a name if an initial subsequence of the +name's components matches the pattern, where @samp{*}, @samp{?}, and +@samp{[...]} are the usual shell wildcards, @samp{\} escapes wildcards, +and wildcards can match @samp{/}. + +Other than optionally stripping leading @samp{/} from names +(@pxref{absolute}), patterns and names are used as-is. For +example, trailing @samp{/} is not trimmed from a user-specified name +before deciding whether to exclude it. + +However, this matching procedure can be altered by the options listed +below. These options accumulate. For example: + +@smallexample +--ignore-case --exclude='makefile' --no-ignore-case ---exclude='readme' +@end smallexample + +@noindent +ignores case when excluding @samp{makefile}, but not when excluding +@samp{readme}. + +@table @option +@opindex anchored +@opindex no-anchored +@item --anchored +@itemx --no-anchored +If anchored, a pattern must match an initial subsequence +of the name's components. Otherwise, the pattern can match any +subsequence. Default is @option{--no-anchored} for exclusion members +and @option{--anchored} inclusion members. + +@opindex ignore-case +@opindex no-ignore-case +@item --ignore-case +@itemx --no-ignore-case +When ignoring case, upper-case patterns match lower-case names and vice versa. +When not ignoring case (the default), matching is case-sensitive. + +@opindex wildcards-match-slash +@opindex no-wildcards-match-slash +@item --wildcards-match-slash +@itemx --no-wildcards-match-slash +When wildcards match slash (the default for exclusion members), a +wildcard like @samp{*} in the pattern can match a @samp{/} in the +name. Otherwise, @samp{/} is matched only by @samp{/}. + +@end table + +The @option{--recursion} and @option{--no-recursion} options +(@pxref{recurse}) also affect how member patterns are interpreted. If +recursion is in effect, a pattern matches a name if it matches any of +the name's parent directories. + +The following table summarizes pattern-matching default values: + +@multitable @columnfractions .3 .7 +@headitem Members @tab Default settings +@item Inclusion @tab @option{--no-wildcards --anchored --no-wildcards-match-slash} +@item Exclusion @tab @option{--wildcards --no-anchored --wildcards-match-slash} +@end multitable + +@node quoting styles +@section Quoting Member Names + +When displaying member names, @command{tar} takes care to avoid +ambiguities caused by certain characters. This is called @dfn{name +quoting}. The characters in question are: + +@itemize @bullet +@item Non-printable control characters: +@anchor{escape sequences} +@multitable @columnfractions 0.20 0.10 0.60 +@headitem Character @tab @acronym{ASCII} @tab Character name +@item \a @tab 7 @tab Audible bell +@item \b @tab 8 @tab Backspace +@item \f @tab 12 @tab Form feed +@item \n @tab 10 @tab New line +@item \r @tab 13 @tab Carriage return +@item \t @tab 9 @tab Horizontal tabulation +@item \v @tab 11 @tab Vertical tabulation +@end multitable + +@item Space (@acronym{ASCII} 32) + +@item Single and double quotes (@samp{'} and @samp{"}) + +@item Backslash (@samp{\}) +@end itemize + +The exact way @command{tar} uses to quote these characters depends on +the @dfn{quoting style}. The default quoting style, called +@dfn{escape} (see below), uses backslash notation to represent control +characters, space and backslash. Using this quoting style, control +characters are represented as listed in column @samp{Character} in the +above table, a space is printed as @samp{\ } and a backslash as @samp{\\}. + +@GNUTAR{} offers seven distinct quoting styles, which can be selected +using @option{--quoting-style} option: + +@table @option +@item --quoting-style=@var{style} +@opindex quoting-style + +Sets quoting style. Valid values for @var{style} argument are: +literal, shell, shell-always, c, escape, locale, clocale. +@end table + +These styles are described in detail below. To illustrate their +effect, we will use an imaginary tar archive @file{arch.tar} +containing the following members: + +@smallexample +@group +# 1. Contains horizontal tabulation character. +a tab +# 2. Contains newline character +a +newline +# 3. Contains a space +a space +# 4. Contains double quotes +a"double"quote +# 5. Contains single quotes +a'single'quote +# 6. Contains a backslash character: +a\backslash +@end group +@end smallexample + +Here is how usual @command{ls} command would have listed them, if they +had existed in the current working directory: + +@smallexample +@group +$ @kbd{ls} +a\ttab +a\nnewline +a\ space +a"double"quote +a'single'quote +a\\backslash +@end group +@end smallexample + +Quoting styles: + +@table @samp +@item literal +No quoting, display each character as is: + +@smallexample +@group +$ @kbd{tar tf arch.tar --quoting-style=literal} +./ +./a space +./a'single'quote +./a"double"quote +./a\backslash +./a tab +./a +newline +@end group +@end smallexample + +@item shell +Display characters the same way Bourne shell does: +control characters, except @samp{\t} and @samp{\n}, are printed using +backslash escapes, @samp{\t} and @samp{\n} are printed as is, and a +single quote is printed as @samp{\'}. If a name contains any quoted +characters, it is enclosed in single quotes. In particular, if a name +contains single quotes, it is printed as several single-quoted strings: + +@smallexample +@group +$ @kbd{tar tf arch.tar --quoting-style=shell} +./ +'./a space' +'./a'\''single'\''quote' +'./a"double"quote' +'./a\backslash' +'./a tab' +'./a +newline' +@end group +@end smallexample + +@item shell-always +Same as @samp{shell}, but the names are always enclosed in single +quotes: + +@smallexample +@group +$ @kbd{tar tf arch.tar --quoting-style=shell-always} +'./' +'./a space' +'./a'\''single'\''quote' +'./a"double"quote' +'./a\backslash' +'./a tab' +'./a +newline' +@end group +@end smallexample + +@item c +Use the notation of the C programming language. All names are +enclosed in double quotes. Control characters are quoted using +backslash notations, double quotes are represented as @samp{\"}, +backslash characters are represented as @samp{\\}. Single quotes and +spaces are not quoted: + +@smallexample +@group +$ @kbd{tar tf arch.tar --quoting-style=c} +"./" +"./a space" +"./a'single'quote" +"./a\"double\"quote" +"./a\\backslash" +"./a\ttab" +"./a\nnewline" +@end group +@end smallexample + +@item escape +Control characters are printed using backslash notation, a space is +printed as @samp{\ } and a backslash as @samp{\\}. This is the +default quoting style, unless it was changed when configured the +package. + +@smallexample +@group +$ @kbd{tar tf arch.tar --quoting-style=escape} +./ +./a space +./a'single'quote +./a"double"quote +./a\\backslash +./a\ttab +./a\nnewline +@end group +@end smallexample + +@item locale +Control characters, single quote and backslash are printed using +backslash notation. All names are quoted using left and right +quotation marks, appropriate to the current locale. If it does not +define quotation marks, use @samp{'} as left and as right +quotation marks. Any occurrences of the right quotation mark in a +name are escaped with @samp{\}, for example: + +For example: + +@smallexample +@group +$ @kbd{tar tf arch.tar --quoting-style=locale} +'./' +'./a space' +'./a\'single\'quote' +'./a"double"quote' +'./a\\backslash' +'./a\ttab' +'./a\nnewline' +@end group +@end smallexample + +@item clocale +Same as @samp{locale}, but @samp{"} is used for both left and right +quotation marks, if not provided by the currently selected locale: + +@smallexample +@group +$ @kbd{tar tf arch.tar --quoting-style=clocale} +"./" +"./a space" +"./a'single'quote" +"./a\"double\"quote" +"./a\\backslash" +"./a\ttab" +"./a\nnewline" +@end group +@end smallexample +@end table + +You can specify which characters should be quoted in addition to those +implied by the current quoting style: + +@table @option +@item --quote-chars=@var{string} +Always quote characters from @var{string}, even if the selected +quoting style would not quote them. +@end table + +For example, using @samp{escape} quoting (compare with the usual +escape listing above): + +@smallexample +@group +$ @kbd{tar tf arch.tar --quoting-style=escape --quote-chars=' "'} +./ +./a\ space +./a'single'quote +./a\"double\"quote +./a\\backslash +./a\ttab +./a\nnewline +@end group +@end smallexample + +To disable quoting of such additional characters, use the following +option: + +@table @option +@item --no-quote-chars=@var{string} +Remove characters listed in @var{string} from the list of quoted +characters set by the previous @option{--quote-chars} option. +@end table + +This option is particularly useful if you have added +@option{--quote-chars} to your @env{TAR_OPTIONS} (@pxref{TAR_OPTIONS}) +and wish to disable it for the current invocation. + +Note, that @option{--no-quote-chars} does @emph{not} disable those +characters that are quoted by default in the selected quoting style. + +@node transform +@section Modifying File and Member Names + +@command{Tar} archives contain detailed information about files stored +in them and full file names are part of that information. When +storing a file to an archive, its file name is recorded in it, +along with the actual file contents. When restoring from an archive, +a file is created on disk with exactly the same name as that stored +in the archive. In the majority of cases this is the desired behavior +of a file archiver. However, there are some cases when it is not. + +First of all, it is often unsafe to extract archive members with +absolute file names or those that begin with a @file{../}. @GNUTAR{} +takes special precautions when extracting such names and provides a +special option for handling them, which is described in +@ref{absolute}. + +Secondly, you may wish to extract file names without some leading +directory components, or with otherwise modified names. In other +cases it is desirable to store files under differing names in the +archive. + +@GNUTAR{} provides several options for these needs. + +@table @option +@opindex strip-components +@item --strip-components=@var{number} +Strip given @var{number} of leading components from file names before +extraction. +@end table + +For example, suppose you have archived whole @file{/usr} hierarchy to +a tar archive named @file{usr.tar}. Among other files, this archive +contains @file{usr/include/stdlib.h}, which you wish to extract to +the current working directory. To do so, you type: + +@smallexample +$ @kbd{tar -xf usr.tar --strip=2 usr/include/stdlib.h} +@end smallexample + +The option @option{--strip=2} instructs @command{tar} to strip the +two leading components (@file{usr/} and @file{include/}) off the file +name. + +If you add the @option{--verbose} (@option{-v}) option to the invocation +above, you will note that the verbose listing still contains the +full file name, with the two removed components still in place. This +can be inconvenient, so @command{tar} provides a special option for +altering this behavior: + +@anchor{show-transformed-names} +@table @option +@opindex show-transformed-names +@item --show-transformed-names +Display file or member names with all requested transformations +applied. +@end table + +@noindent +For example: + +@smallexample +@group +$ @kbd{tar -xf usr.tar -v --strip=2 usr/include/stdlib.h} +usr/include/stdlib.h +$ @kbd{tar -xf usr.tar -v --strip=2 --show-transformed usr/include/stdlib.h} +stdlib.h +@end group +@end smallexample + +Notice that in both cases the file @file{stdlib.h} is extracted to the +current working directory, @option{--show-transformed-names} affects +only the way its name is displayed. + +This option is especially useful for verifying whether the invocation +will have the desired effect. Thus, before running + +@smallexample +$ @kbd{tar -x --strip=@var{n}} +@end smallexample + +@noindent +it is often advisable to run + +@smallexample +$ @kbd{tar -t -v --show-transformed --strip=@var{n}} +@end smallexample + +@noindent +to make sure the command will produce the intended results. + +In case you need to apply more complex modifications to the file name, +@GNUTAR{} provides a general-purpose transformation option: + +@table @option +@opindex transform +@opindex xform +@item --transform=@var{expression} +@itemx --xform=@var{expression} +Modify file names using supplied @var{expression}. +@end table + +@noindent +The @var{expression} is a @command{sed}-like replace expression of the +form: + +@smallexample +s/@var{regexp}/@var{replace}/[@var{flags}] +@end smallexample + +@noindent +where @var{regexp} is a @dfn{regular expression}, @var{replace} is a +replacement for each file name part that matches @var{regexp}. Both +@var{regexp} and @var{replace} are described in detail in +@ref{The "s" Command, The "s" Command, The `s' Command, sed, GNU sed}. + +Any delimiter can be used in lieu of @samp{/}, the only requirement being +that it be used consistently throughout the expression. For example, +the following two expressions are equivalent: + +@smallexample +@group +s/one/two/ +s,one,two, +@end group +@end smallexample + +Changing delimiters is often useful when the @var{regex} contains +slashes. For example, it is more convenient to write @code{s,/,-,} than +@code{s/\//-/}. + +As in @command{sed}, you can give several replace expressions, +separated by a semicolon. + +Supported @var{flags} are: + +@table @samp +@item g +Apply the replacement to @emph{all} matches to the @var{regexp}, not +just the first. + +@item i +Use case-insensitive matching. + +@item x +@var{regexp} is an @dfn{extended regular expression} (@pxref{Extended +regexps, Extended regular expressions, Extended regular expressions, +sed, GNU sed}). + +@item @var{number} +Only replace the @var{number}th match of the @var{regexp}. + +Note: the @acronym{POSIX} standard does not specify what should happen +when you mix the @samp{g} and @var{number} modifiers. @GNUTAR{} +follows the GNU @command{sed} implementation in this regard, so +the interaction is defined to be: ignore matches before the +@var{number}th, and then match and replace all matches from the +@var{number}th on. + +@end table + +In addition, several @dfn{transformation scope} flags are supported, +that control to what files transformations apply. These are: + +@table @samp +@item r +Apply transformation to regular archive members. + +@item R +Do not apply transformation to regular archive members. + +@item s +Apply transformation to symbolic link targets. + +@item S +Do not apply transformation to symbolic link targets. + +@item h +Apply transformation to hard link targets. + +@item H +Do not apply transformation to hard link targets. +@end table + +Default is @samp{rsh}, which means to apply tranformations to both archive +members and targets of symbolic and hard links. + +Default scope flags can also be changed using @samp{flags=} statement +in the transform expression. The flags set this way remain in force +until next @samp{flags=} statement or end of expression, whichever +occurs first. For example: + +@smallexample + --transform 'flags=S;s|^|/usr/local/|' +@end smallexample + +Here are several examples of @option{--transform} usage: + +@enumerate +@item Extract @file{usr/} hierarchy into @file{usr/local/}: + +@smallexample +$ @kbd{tar --transform='s,usr/,usr/local/,' -x -f arch.tar} +@end smallexample + +@item Strip two leading directory components (equivalent to +@option{--strip-components=2}): + +@smallexample +$ @kbd{tar --transform='s,/*[^/]*/[^/]*/,,' -x -f arch.tar} +@end smallexample + +@item Convert each file name to lower case: + +@smallexample +$ @kbd{tar --transform 's/.*/\L&/' -x -f arch.tar} +@end smallexample + +@item Prepend @file{/prefix/} to each file name: + +@smallexample +$ @kbd{tar --transform 's,^,/prefix/,' -x -f arch.tar} +@end smallexample + +@item Archive the @file{/lib} directory, prepending @samp{/usr/local} +to each archive member: + +@smallexample +$ @kbd{tar --transform 's,^,/usr/local/,S' -c -f arch.tar /lib} +@end smallexample +@end enumerate + +Notice the use of flags in the last example. The @file{/lib} +directory often contains many symbolic links to files within it. +It may look, for example, like this: + +@smallexample +$ @kbd{ls -l} +drwxr-xr-x root/root 0 2008-07-08 16:20 /lib/ +-rwxr-xr-x root/root 1250840 2008-05-25 07:44 /lib/libc-2.3.2.so +lrwxrwxrwx root/root 0 2008-06-24 17:12 /lib/libc.so.6 -> libc-2.3.2.so +... +@end smallexample + +Using the expression @samp{s,^,/usr/local/,} would mean adding +@samp{/usr/local} to both regular archive members and to link +targets. In this case, @file{/lib/libc.so.6} would become: + +@smallexample + /usr/local/lib/libc.so.6 -> /usr/local/libc-2.3.2.so +@end smallexample + +This is definitely not desired. To avoid this, the @samp{S} flag +is used, which excludes symbolic link targets from filename +transformations. The result is: + +@smallexample +$ @kbd{tar --transform 's,^,/usr/local/,S', -c -v -f arch.tar \ + --show-transformed /lib} +drwxr-xr-x root/root 0 2008-07-08 16:20 /usr/local/lib/ +-rwxr-xr-x root/root 1250840 2008-05-25 07:44 /usr/local/lib/libc-2.3.2.so +lrwxrwxrwx root/root 0 2008-06-24 17:12 /usr/local/lib/libc.so.6 \ + -> libc-2.3.2.so +@end smallexample + +Unlike @option{--strip-components}, @option{--transform} can be used +in any @GNUTAR{} operation mode. For example, the following command +adds files to the archive while replacing the leading @file{usr/} +component with @file{var/}: + +@smallexample +$ @kbd{tar -cf arch.tar --transform='s,^usr/,var/,' /} +@end smallexample + +To test @option{--transform} effect we suggest using +@option{--show-transformed-names} option: + +@smallexample +$ @kbd{tar -cf arch.tar --transform='s,^usr/,var/,' \ + --verbose --show-transformed-names /} +@end smallexample + +If both @option{--strip-components} and @option{--transform} are used +together, then @option{--transform} is applied first, and the required +number of components is then stripped from its result. + +You can use as many @option{--transform} options in a single command +line as you want. The specified expressions will then be applied in +order of their appearance. For example, the following two invocations +are equivalent: + +@smallexample +$ @kbd{tar -cf arch.tar --transform='s,/usr/var,/var/' \ + --transform='s,/usr/local,/usr/,'} +$ @kbd{tar -cf arch.tar \ + --transform='s,/usr/var,/var/;s,/usr/local,/usr/,'} +@end smallexample + +@node after +@section Operating Only on New Files + +@cindex Excluding file by age +@cindex Data Modification time, excluding files by +@cindex Modification time, excluding files by +@cindex Age, excluding files by +The @option{--after-date=@var{date}} (@option{--newer=@var{date}}, +@option{-N @var{date}}) option causes @command{tar} to only work on +files whose data modification or status change times are newer than +the @var{date} given. If @var{date} starts with @samp{/} or @samp{.}, +it is taken to be a file name; the data modification time of that file +is used as the date. If you use this option when creating or appending +to an archive, the archive will only include new files. If you use +@option{--after-date} when extracting an archive, @command{tar} will +only extract files newer than the @var{date} you specify. + +If you only want @command{tar} to make the date comparison based on +modification of the file's data (rather than status +changes), then use the @option{--newer-mtime=@var{date}} option. + +@cindex --after-date and --update compared +@cindex --newer-mtime and --update compared +You may use these options with any operation. Note that these options +differ from the @option{--update} (@option{-u}) operation in that they +allow you to specify a particular date against which @command{tar} can +compare when deciding whether or not to archive the files. + +@table @option +@opindex after-date +@opindex newer +@item --after-date=@var{date} +@itemx --newer=@var{date} +@itemx -N @var{date} +Only store files newer than @var{date}. + +Acts on files only if their data modification or status change times are +later than @var{date}. Use in conjunction with any operation. + +If @var{date} starts with @samp{/} or @samp{.}, it is taken to be a file +name; the data modification time of that file is used as the date. + +@opindex newer-mtime +@item --newer-mtime=@var{date} +Acts like @option{--after-date}, but only looks at data modification times. @end table -@node Backups and Restoration, Media, User Interaction, Top -@chapter Performing Backups and Restoring Files +These options limit @command{tar} to operate only on files which have +been modified after the date specified. A file's status is considered to have +changed if its contents have been modified, or if its owner, +permissions, and so forth, have been changed. (For more information on +how to specify a date, see @ref{Date input formats}; remember that the +entire date argument must be quoted if it contains any spaces.) + +Gurus would say that @option{--after-date} tests both the data +modification time (@code{mtime}, the time the contents of the file +were last modified) and the status change time (@code{ctime}, the time +the file's status was last changed: owner, permissions, etc.@:) +fields, while @option{--newer-mtime} tests only the @code{mtime} +field. + +To be precise, @option{--after-date} checks @emph{both} @code{mtime} and +@code{ctime} and processes the file if either one is more recent than +@var{date}, while @option{--newer-mtime} only checks @code{mtime} and +disregards @code{ctime}. Neither does it use @code{atime} (the last time the +contents of the file were looked at). + +Date specifiers can have embedded spaces. Because of this, you may need +to quote date arguments to keep the shell from parsing them as separate +arguments. For example, the following command will add to the archive +all the files modified less than two days ago: + +@smallexample +$ @kbd{tar -cf foo.tar --newer-mtime '2 days ago'} +@end smallexample + +When any of these options is used with the option @option{--verbose} +(@pxref{verbose tutorial}) @GNUTAR{} will try to convert the specified +date back to its textual representation and compare that with the +one given with the option. If the two dates differ, @command{tar} will +print a warning saying what date it will use. This is to help user +ensure he is using the right date. For example: + +@smallexample +@group +$ @kbd{tar -c -f archive.tar --after-date='10 days ago' .} +tar: Option --after-date: Treating date '10 days ago' as 2006-06-11 +13:19:37.232434 +@end group +@end smallexample -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}. +@quotation +@strong{Please Note:} @option{--after-date} and @option{--newer-mtime} +should not be used for incremental backups. @xref{Incremental Dumps}, +for proper way of creating incremental backups. +@end quotation + +@node recurse +@section Descending into Directories +@cindex Avoiding recursion in directories +@cindex Descending directories, avoiding +@cindex Directories, avoiding recursion +@cindex Recursion in directories, avoiding + +Usually, @command{tar} will recursively explore all directories (either +those given on the command line or through the @option{--files-from} +option) for the various files they contain. However, you may not always +want @command{tar} to act this way. + +@opindex no-recursion +@cindex @command{find}, using with @command{tar} +The @option{--no-recursion} option inhibits @command{tar}'s recursive descent +into specified directories. If you specify @option{--no-recursion}, you can +use the @command{find} (@pxref{Top,, find, find, GNU Find Manual}) +utility for hunting through levels of directories to +construct a list of file names which you could then pass to @command{tar}. +@command{find} allows you to be more selective when choosing which files to +archive; see @ref{files}, for more information on using @command{find} with +@command{tar}. + +@table @option +@item --no-recursion +Prevents @command{tar} from recursively descending directories. + +@opindex recursion +@item --recursion +Requires @command{tar} to recursively descend directories. +This is the default. +@end table + +When you use @option{--no-recursion}, @GNUTAR{} grabs +directory entries themselves, but does not descend on them +recursively. Many people use @command{find} for locating files they +want to back up, and since @command{tar} @emph{usually} recursively +descends on directories, they have to use the @samp{@w{-not -type d}} +test in their @command{find} invocation (@pxref{Type, Type, Type test, +find, Finding Files}), as they usually do not want all the files in a +directory. They then use the @option{--files-from} option to archive +the files located via @command{find}. + +The problem when restoring files archived in this manner is that the +directories themselves are not in the archive; so the +@option{--same-permissions} (@option{--preserve-permissions}, +@option{-p}) option does not affect them---while users might really +like it to. Specifying @option{--no-recursion} is a way to tell +@command{tar} to grab only the directory entries given to it, adding +no new files on its own. To summarize, if you use @command{find} to +create a list of files to be stored in an archive, use it as follows: + +@smallexample +@group +$ @kbd{find @var{dir} @var{tests} | \ + tar -cf @var{archive} -T - --no-recursion} +@end group +@end smallexample + +The @option{--no-recursion} option also applies when extracting: it +causes @command{tar} to extract only the matched directory entries, not +the files under those directories. + +The @option{--no-recursion} option also affects how globbing patterns +are interpreted (@pxref{controlling pattern-matching}). + +The @option{--no-recursion} and @option{--recursion} options apply to +later options and operands, and can be overridden by later occurrences +of @option{--no-recursion} and @option{--recursion}. For example: + +@smallexample +$ @kbd{tar -cf jams.tar --no-recursion grape --recursion grape/concord} +@end smallexample + +@noindent +creates an archive with one entry for @file{grape}, and the recursive +contents of @file{grape/concord}, but no entries under @file{grape} +other than @file{grape/concord}. + +@node one +@section Crossing File System Boundaries +@cindex File system boundaries, not crossing + +@command{tar} will normally automatically cross file system boundaries in +order to archive files which are part of a directory tree. You can +change this behavior by running @command{tar} and specifying +@option{--one-file-system}. This option only affects files that are +archived because they are in a directory that is being archived; +@command{tar} will still archive files explicitly named on the command line +or through @option{--files-from}, regardless of where they reside. + +@table @option +@opindex one-file-system +@item --one-file-system +Prevents @command{tar} from crossing file system boundaries when +archiving. Use in conjunction with any write operation. +@end table + +The @option{--one-file-system} option causes @command{tar} to modify its +normal behavior in archiving the contents of directories. If a file in +a directory is not on the same file system as the directory itself, then +@command{tar} will not archive that file. If the file is a directory +itself, @command{tar} will not archive anything beneath it; in other words, +@command{tar} will not cross mount points. + +This option is useful for making full or incremental archival backups of +a file system. If this option is used in conjunction with +@option{--verbose} (@option{-v}), files that are excluded are +mentioned by name on the standard error. @menu -* 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 +* directory:: Changing Directory +* absolute:: Absolute File Names @end menu -@node Backup Levels, Backup Scripts, Backups and Restoration, Backups and Restoration -@section Levels of Backups +@node directory +@subsection Changing the Working Directory -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. +@FIXME{need to read over this node now for continuity; i've switched +things around some.} -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. +@cindex Changing directory mid-stream +@cindex Directory, changing mid-stream +@cindex Working directory, specifying +To change the working directory in the middle of a list of file names, +either on the command line or in a file specified using +@option{--files-from} (@option{-T}), use @option{--directory} (@option{-C}). +This will change the working directory to the specified directory +after that point in the list. + +@table @option +@opindex directory +@item --directory=@var{directory} +@itemx -C @var{directory} +Changes the working directory in the middle of a command line. +@end table -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). +For example, + +@smallexample +$ @kbd{tar -c -f jams.tar grape prune -C food cherry} +@end smallexample -@node Backup Scripts, incremental and listed-incremental, Backup Levels, Backups and Restoration -@section Using Scripts to Perform Backups and Restoration +@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. -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. +Contrast this with the command, + +@smallexample +$ @kbd{tar -c -f jams.tar grape prune -C food red/cherry} +@end smallexample + +@noindent +which records the third file in the archive under the name +@file{red/cherry} so that, if the archive is extracted using +@samp{tar --extract}, the third file will be written in a subdirectory +named @file{red}. + +You can use the @option{--directory} option to make the archive +independent of the original name of the directory holding the files. +The following command places the files @file{/etc/passwd}, +@file{/etc/hosts}, and @file{/lib/libc.a} into the archive +@file{foo.tar}: + +@smallexample +$ @kbd{tar -c -f foo.tar -C /etc passwd hosts -C /lib libc.a} +@end smallexample + +@noindent +However, the names of the archive members will be exactly what they were +on the command line: @file{passwd}, @file{hosts}, and @file{libc.a}. +They will not appear to be related by file name to the original +directories where those files were located. + +Note that @option{--directory} options are interpreted consecutively. If +@option{--directory} specifies a relative file name, it is interpreted +relative to the then current directory, which might not be the same as +the original current working directory of @command{tar}, due to a previous +@option{--directory} option. + +When using @option{--files-from} (@pxref{files}), you can put various +@command{tar} options (including @option{-C}) in the file list. Notice, +however, that in this case the option and its argument may not be +separated by whitespace. If you use short option, its argument must +either follow the option letter immediately, without any intervening +whitespace, or occupy the next line. Otherwise, if you use long +option, separate its argument by an equal sign. + +For instance, the file list for the above example will be: + +@smallexample +@group +-C/etc +passwd +hosts +--directory=/lib +libc.a +@end group +@end smallexample + +@noindent +To use it, you would invoke @command{tar} as follows: + +@smallexample +$ @kbd{tar -c -f foo.tar --files-from list} +@end smallexample + +The interpretation of @option{--directory} is disabled by +@option{--null} option. + +@node absolute +@subsection Absolute File Names +@cindex absolute file names +@cindex file names, absolute + +By default, @GNUTAR{} drops a leading @samp{/} on +input or output, and complains about file names containing a @file{..} +component. There is an option that turns off this behavior: + +@table @option +@opindex absolute-names +@item --absolute-names +@itemx -P +Do not strip leading slashes from file names, and permit file names +containing a @file{..} file name component. +@end table + +When @command{tar} extracts archive members from an archive, it strips any +leading slashes (@samp{/}) from the member name. This causes absolute +member names in the archive to be treated as relative file names. This +allows you to have such members extracted wherever you want, instead of +being restricted to extracting the member in the exact directory named +in the archive. For example, if the archive member has the name +@file{/etc/passwd}, @command{tar} will extract it as if the name were +really @file{etc/passwd}. + +File names containing @file{..} can cause problems when extracting, so +@command{tar} normally warns you about such files when creating an +archive, and rejects attempts to extracts such files. + +Other @command{tar} programs do not do this. As a result, if you +create an archive whose member names start with a slash, they will be +difficult for other people with a non-@GNUTAR{} +program to use. Therefore, @GNUTAR{} also strips +leading slashes from member names when putting members into the +archive. For example, if you ask @command{tar} to add the file +@file{/bin/ls} to an archive, it will do so, but the member name will +be @file{bin/ls}@footnote{A side effect of this is that when +@option{--create} is used with @option{--verbose} the resulting output +is not, generally speaking, the same as the one you'd get running +@kbd{tar --list} command. This may be important if you use some +scripts for comparing both outputs. @xref{listing member and file names}, +for the information on how to handle this case.}. + +Symbolic links containing @file{..} or leading @samp{/} can also cause +problems when extracting, so @command{tar} normally extracts them last; +it may create empty files as placeholders during extraction. + +If you use the @option{--absolute-names} (@option{-P}) option, +@command{tar} will do none of these transformations. + +To archive or extract files relative to the root directory, specify +the @option{--absolute-names} (@option{-P}) option. + +Normally, @command{tar} acts on files relative to the working +directory---ignoring superior directory names when archiving, and +ignoring leading slashes when extracting. + +When you specify @option{--absolute-names} (@option{-P}), +@command{tar} stores file names including all superior directory +names, and preserves leading slashes. If you only invoked +@command{tar} from the root directory you would never need the +@option{--absolute-names} option, but using this option +may be more convenient than switching to root. + +@FIXME{Should be an example in the tutorial/wizardry section using this +to transfer files between systems.} + +@table @option +@item --absolute-names +Preserves full file names (including superior directory names) when +archiving and extracting files. + +@end table + +@command{tar} prints out a message about removing the @samp{/} from +file names. This message appears once per @GNUTAR{} +invocation. It represents something which ought to be told; ignoring +what it means can cause very serious surprises, later. + +Some people, nevertheless, do not want to see this message. Wanting to +play really dangerously, one may of course redirect @command{tar} standard +error to the sink. For example, under @command{sh}: + +@smallexample +$ @kbd{tar -c -f archive.tar /home 2> /dev/null} +@end smallexample + +@noindent +Another solution, both nicer and simpler, would be to change to +the @file{/} directory first, and then avoid absolute notation. +For example: + +@smallexample +$ @kbd{tar -c -f archive.tar -C / home} +@end smallexample + +@xref{Integrity}, for some of the security-related implications +of using this option. + +@include parse-datetime.texi + +@node Formats +@chapter Controlling the Archive Format + +@cindex Tar archive formats +Due to historical reasons, there are several formats of tar archives. +All of them are based on the same principles, but have some subtle +differences that often make them incompatible with each other. + +GNU tar is able to create and handle archives in a variety of formats. +The most frequently used formats are (in alphabetical order): + +@table @asis +@item gnu +Format used by @GNUTAR{} versions up to 1.13.25. This format derived +from an early @acronym{POSIX} standard, adding some improvements such as +sparse file handling and incremental archives. Unfortunately these +features were implemented in a way incompatible with other archive +formats. + +Archives in @samp{gnu} format are able to hold file names of unlimited +length. + +@item oldgnu +Format used by @GNUTAR{} of versions prior to 1.12. + +@item v7 +Archive format, compatible with the V7 implementation of tar. This +format imposes a number of limitations. The most important of them +are: + +@enumerate +@item The maximum length of a file name is limited to 99 characters. +@item The maximum length of a symbolic link is limited to 99 characters. +@item It is impossible to store special files (block and character +devices, fifos etc.) +@item Maximum value of user or group @acronym{ID} is limited to 2097151 (7777777 +octal) +@item V7 archives do not contain symbolic ownership information (user +and group name of the file owner). +@end enumerate + +This format has traditionally been used by Automake when producing +Makefiles. This practice will change in the future, in the meantime, +however this means that projects containing file names more than 99 +characters long will not be able to use @GNUTAR{} @value{VERSION} and +Automake prior to 1.9. + +@item ustar +Archive format defined by @acronym{POSIX.1-1988} specification. It stores +symbolic ownership information. It is also able to store +special files. However, it imposes several restrictions as well: + +@enumerate +@item The maximum length of a file name is limited to 256 characters, +provided that the file name can be split at a directory separator in +two parts, first of them being at most 155 bytes long. So, in most +cases the maximum file name length will be shorter than 256 +characters. +@item The maximum length of a symbolic link name is limited to +100 characters. +@item Maximum size of a file the archive is able to accommodate +is 8GB +@item Maximum value of UID/GID is 2097151. +@item Maximum number of bits in device major and minor numbers is 21. +@end enumerate + +@item star +Format used by J@"org Schilling @command{star} +implementation. @GNUTAR{} is able to read @samp{star} archives but +currently does not produce them. + +@item posix +Archive format defined by @acronym{POSIX.1-2001} specification. This is the +most flexible and feature-rich format. It does not impose any +restrictions on file sizes or file name lengths. This format is quite +recent, so not all tar implementations are able to handle it properly. +However, this format is designed in such a way that any tar +implementation able to read @samp{ustar} archives will be able to read +most @samp{posix} archives as well, with the only exception that any +additional information (such as long file names etc.) will in such +case be extracted as plain text files along with the files it refers to. + +This archive format will be the default format for future versions +of @GNUTAR{}. + +@end table + +The following table summarizes the limitations of each of these +formats: + +@multitable @columnfractions .10 .20 .20 .20 .20 +@headitem Format @tab UID @tab File Size @tab File Name @tab Devn +@item gnu @tab 1.8e19 @tab Unlimited @tab Unlimited @tab 63 +@item oldgnu @tab 1.8e19 @tab Unlimited @tab Unlimited @tab 63 +@item v7 @tab 2097151 @tab 8GB @tab 99 @tab n/a +@item ustar @tab 2097151 @tab 8GB @tab 256 @tab 21 +@item posix @tab Unlimited @tab Unlimited @tab Unlimited @tab Unlimited +@end multitable + +The default format for @GNUTAR{} is defined at compilation +time. You may check it by running @command{tar --help}, and examining +the last lines of its output. Usually, @GNUTAR{} is configured +to create archives in @samp{gnu} format, however, future version will +switch to @samp{posix}. -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. - -@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. - -@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 +* Compression:: Using Less Space through Compression +* Attributes:: Handling File Attributes +* Portability:: Making @command{tar} Archives More Portable +* cpio:: Comparison of @command{tar} and @command{cpio} @end menu -@node Backup Parameters, Scripted Backups, Backup Scripts, Backup Scripts -@subsection Setting Parameters for Backups and Restoration +@node Compression +@section Using Less Space through Compression -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. +@menu +* gzip:: Creating and Reading Compressed Archives +* sparse:: Archiving Sparse Files +@end menu -@c <<< This about backup scripts needs to be written: -@c << archive.tar.gz} +@end smallexample + +@cindex corrupted archives +Compressed archives are easily corrupted, because compressed files +have little redundancy. The adaptive nature of the +compression scheme means that the compression tables are implicitly +spread all over the archive. If you lose a few blocks, the dynamic +construction of the compression tables becomes unsynchronized, and there +is little chance that you could recover later in the archive. + +Other compression options provide better control over creating +compressed archives. These are: + +@table @option +@anchor{auto-compress} +@opindex auto-compress +@item --auto-compress +@itemx -a +Select a compression program to use by the archive file name +suffix. The following suffixes are recognized: + +@multitable @columnfractions 0.3 0.6 +@headitem Suffix @tab Compression program +@item @samp{.gz} @tab @command{gzip} +@item @samp{.tgz} @tab @command{gzip} +@item @samp{.taz} @tab @command{gzip} +@item @samp{.Z} @tab @command{compress} +@item @samp{.taZ} @tab @command{compress} +@item @samp{.bz2} @tab @command{bzip2} +@item @samp{.tz2} @tab @command{bzip2} +@item @samp{.tbz2} @tab @command{bzip2} +@item @samp{.tbz} @tab @command{bzip2} +@item @samp{.lz} @tab @command{lzip} +@item @samp{.lzma} @tab @command{lzma} +@item @samp{.tlz} @tab @command{lzma} +@item @samp{.lzo} @tab @command{lzop} +@item @samp{.xz} @tab @command{xz} +@end multitable + +@anchor{use-compress-program} +@opindex use-compress-program +@item --use-compress-program=@var{command} +@itemx -I=@var{command} +Use external compression program @var{command}. Use this option if you +are not happy with the compression program associated with the suffix +at compile time or if you have a compression program that @GNUTAR{} +does not support. The @var{command} argument is a valid command +invocation, as you would type it at the command line prompt, with any +additional options as needed. Enclose it in quotes if it contains +white space (see @ref{external, Running External Commands}, for more detail). + +The @var{command} should follow two conventions: + +First, when invoked without additional options, it should read data +from standard input, compress it and output it on standard output. + +Secondly, if invoked with the additional @option{-d} option, it should +do exactly the opposite, i.e., read the compressed data from the +standard input and produce uncompressed data on the standard output. + +The latter requirement means that you must not use the @option{-d} +option as a part of the @var{command} itself. @end table +@cindex gpg, using with tar +@cindex gnupg, using with tar +@cindex Using encrypted archives +The @option{--use-compress-program} option, in particular, lets you +implement your own filters, not necessarily dealing with +compression/decompression. For example, suppose you wish to implement +PGP encryption on top of compression, using @command{gpg} (@pxref{Top, +gpg, gpg ---- encryption and signing tool, gpg, GNU Privacy Guard +Manual}). The following script does that: + +@smallexample +@group +#! /bin/sh +case $1 in +-d) gpg --decrypt - | gzip -d -c;; +'') gzip -c | gpg -s;; +*) echo "Unknown option $1">&2; exit 1;; +esac +@end group +@end smallexample + +Suppose you name it @file{gpgz} and save it somewhere in your +@env{PATH}. Then the following command will create a compressed +archive signed with your private key: + +@smallexample +$ @kbd{tar -cf foo.tar.gpgz -Igpgz .} +@end smallexample + +@noindent +Likewise, the command below will list its contents: + +@smallexample +$ @kbd{tar -tf foo.tar.gpgz -Igpgz .} +@end smallexample + +@ignore +The above is based on the following discussion: + + I have one question, or maybe it's a suggestion if there isn't a way + to do it now. I would like to use @option{--gzip}, but I'd also like + the output to be fed through a program like @acronym{GNU} + @command{ecc} (actually, right now that's @samp{exactly} what I'd like + to use :-)), basically adding ECC protection on top of compression. + It seems as if this should be quite easy to do, but I can't work out + exactly how to go about it. Of course, I can pipe the standard output + of @command{tar} through @command{ecc}, but then I lose (though I + haven't started using it yet, I confess) the ability to have + @command{tar} use @command{rmt} for it's I/O (I think). + + I think the most straightforward thing would be to let me specify a + general set of filters outboard of compression (preferably ordered, + so the order can be automatically reversed on input operations, and + with the options they require specifiable), but beggars shouldn't be + choosers and anything you decide on would be fine with me. + + By the way, I like @command{ecc} but if (as the comments say) it can't + deal with loss of block sync, I'm tempted to throw some time at adding + that capability. Supposing I were to actually do such a thing and + get it (apparently) working, do you accept contributed changes to + utilities like that? (Leigh Clayton @file{loc@@soliton.com}, May 1995). + + Isn't that exactly the role of the + @option{--use-compress-prog=@var{program}} option? + I never tried it myself, but I suspect you may want to write a + @var{prog} script or program able to filter stdin to stdout to + way you want. It should recognize the @option{-d} option, for when + extraction is needed rather than creation. + + It has been reported that if one writes compressed data (through the + @option{--gzip} or @option{--compress} options) to a DLT and tries to use + the DLT compression mode, the data will actually get bigger and one will + end up with less space on the tape. +@end ignore + @menu -* backup-specs example:: An Example Text of @file{Backup-specs} -* Script Syntax:: Syntax for @file{Backup-specs} +* lbzip2:: Using lbzip2 with @GNUTAR{}. @end menu -@node backup-specs example, Script Syntax, Backup Parameters, Backup Parameters -@subsubsection An Example Text of @file{Backup-specs} +@node lbzip2 +@subsubsection Using lbzip2 with @GNUTAR{}. +@cindex lbzip2 +@cindex Laszlo Ersek + @command{Lbzip2} is a multithreaded utility for handling +@samp{bzip2} compression, written by Laszlo Ersek. It makes use of +multiple processors to speed up its operation and in general works +considerably faster than @command{bzip2}. For a detailed description +of @command{lbzip2} see @uref{http://freshmeat.net/@/projects/@/lbzip2} and +@uref{http://www.linuxinsight.com/@/lbzip2-parallel-bzip2-utility.html, +lbzip2: parallel bzip2 utility}. + + Recent versions of @command{lbzip2} are mostly command line compatible +with @command{bzip2}, which makes it possible to automatically invoke +it via the @option{--bzip2} @GNUTAR{} command line option. To do so, +@GNUTAR{} must be configured with the @option{--with-bzip2} command +line option, like this: + +@smallexample +$ @kbd{./configure --with-bzip2=lbzip2 [@var{other-options}]} +@end smallexample + + Once configured and compiled this way, @command{tar --help} will show the +following: -The following is the text of @file{backup-specs} as it appears at FSF: +@smallexample +@group +$ @kbd{tar --help | grep -- --bzip2} + -j, --bzip2 filter the archive through lbzip2 +@end group +@end smallexample -@example -# site-specific parameters for file system backup. +@noindent +which means that running @command{tar --bzip2} will invoke @command{lbzip2}. -ADMINISTRATOR=friedman -BACKUP_HOUR=1 -TAPE_FILE=/dev/nrsmt0 -TAPE_STATUS="mts -t $TAPE_FILE" -BLOCKING=124 -BACKUP_DIRS=" - albert:/fs/fsf - apple-gunkies:/gd - albert:/fs/gd2 - albert:/fs/gp - geech:/usr/jla - churchy:/usr/roland - albert:/ - albert:/usr - apple-gunkies:/ - apple-gunkies:/usr - gnu:/hack - gnu:/u - apple-gunkies:/com/mailer/gnu - apple-gunkies:/com/archive/gnu" +@node sparse +@subsection Archiving Sparse Files +@cindex Sparse Files -BACKUP_FILES="/com/mailer/aliases /com/mailer/league*[a-z]" +Files in the file system occasionally have @dfn{holes}. A @dfn{hole} +in a file is a section of the file's contents which was never written. +The contents of a hole reads as all zeros. On many operating systems, +actual disk storage is not allocated for holes, but they are counted +in the length of the file. If you archive such a file, @command{tar} +could create an archive longer than the original. To have @command{tar} +attempt to recognize the holes in a file, use @option{--sparse} +(@option{-S}). When you use this option, then, for any file using +less disk space than would be expected from its length, @command{tar} +searches the file for consecutive stretches of zeros. It then records +in the archive for the file where the consecutive stretches of zeros +are, and only archives the ``real contents'' of the file. On +extraction (using @option{--sparse} is not needed on extraction) any +such files have holes created wherever the continuous stretches of zeros +were found. Thus, if you use @option{--sparse}, @command{tar} archives +won't take more space than the original. + +@table @option +@opindex sparse +@item -S +@itemx --sparse +This option instructs @command{tar} to test each file for sparseness +before attempting to archive it. If the file is found to be sparse it +is treated specially, thus allowing to decrease the amount of space +used by its image in the archive. + +This option is meaningful only when creating or updating archives. It +has no effect on extraction. +@end table -@end example +Consider using @option{--sparse} when performing file system backups, +to avoid archiving the expanded forms of files stored sparsely in the +system. -@node Script Syntax, , backup-specs example, Backup Parameters -@subsubsection Syntax for @file{Backup-specs} +Even if your system has no sparse files currently, some may be +created in the future. If you use @option{--sparse} while making file +system backups as a matter of course, you can be assured the archive +will never take more space on the media than the files take on disk +(otherwise, archiving a disk filled with sparse files might take +hundreds of tapes). @xref{Incremental Dumps}. + +However, be aware that @option{--sparse} option presents a serious +drawback. Namely, in order to determine if the file is sparse +@command{tar} has to read it before trying to archive it, so in total +the file is read @strong{twice}. So, always bear in mind that the +time needed to process all files with this option is roughly twice +the time needed to archive them without it. +@FIXME{A technical note: + +Programs like @command{dump} do not have to read the entire file; by +examining the file system directly, they can determine in advance +exactly where the holes are and thus avoid reading through them. The +only data it need read are the actual allocated data blocks. +@GNUTAR{} uses a more portable and straightforward +archiving approach, it would be fairly difficult that it does +otherwise. Elizabeth Zwicky writes to @file{comp.unix.internals}, on +1990-12-10: -@file{backup-specs} is in shell script syntax. The following -conventions should be considered when editing the script: -@c <<< "conventions?" +@quotation +What I did say is that you cannot tell the difference between a hole and an +equivalent number of nulls without reading raw blocks. @code{st_blocks} at +best tells you how many holes there are; it doesn't tell you @emph{where}. +Just as programs may, conceivably, care what @code{st_blocks} is (care +to name one that does?), they may also care where the holes are (I have +no examples of this one either, but it's equally imaginable). + +I conclude from this that good archivers are not portable. One can +arguably conclude that if you want a portable program, you can in good +conscience restore files with as many holes as possible, since you can't +get it right. +@end quotation +} + +@cindex sparse formats, defined +When using @samp{POSIX} archive format, @GNUTAR{} is able to store +sparse files using in three distinct ways, called @dfn{sparse +formats}. A sparse format is identified by its @dfn{number}, +consisting, as usual of two decimal numbers, delimited by a dot. By +default, format @samp{1.0} is used. If, for some reason, you wish to +use an earlier format, you can select it using +@option{--sparse-version} option. + +@table @option +@opindex sparse-version +@item --sparse-version=@var{version} + +Select the format to store sparse files in. Valid @var{version} values +are: @samp{0.0}, @samp{0.1} and @samp{1.0}. @xref{Sparse Formats}, +for a detailed description of each format. +@end table -A quoted string is considered to be contiguous, even if it is on more -than one line. Therefore, you cannot include commented-out lines -within a multi-line quoted string. BACKUP_FILES and BACKUP_DIRS are -the two most likely parameters to be multi-line. +Using @option{--sparse-format} option implies @option{--sparse}. + +@node Attributes +@section Handling File Attributes +@cindex atrributes, files +@cindex file attributes + +When @command{tar} reads files, it updates their access times. To +avoid this, use the @option{--atime-preserve[=METHOD]} option, which can either +reset the access time retroactively or avoid changing it in the first +place. + +@table @option +@opindex atime-preserve +@item --atime-preserve +@itemx --atime-preserve=replace +@itemx --atime-preserve=system +Preserve the access times of files that are read. This works only for +files that you own, unless you have superuser privileges. + +@option{--atime-preserve=replace} works on most systems, but it also +restores the data modification time and updates the status change +time. Hence it doesn't interact with incremental dumps nicely +(@pxref{Incremental Dumps}), and it can set access or data modification times +incorrectly if other programs access the file while @command{tar} is +running. + +@option{--atime-preserve=system} avoids changing the access time in +the first place, if the operating system supports this. +Unfortunately, this may or may not work on any given operating system +or file system. If @command{tar} knows for sure it won't work, it +complains right away. + +Currently @option{--atime-preserve} with no operand defaults to +@option{--atime-preserve=replace}, but this is intended to change to +@option{--atime-preserve=system} when the latter is better-supported. + +@opindex touch +@item -m +@itemx --touch +Do not extract data modification time. -A quoted string typically cannot contain wildcards. In -@file{backup-specs}, however, the parameters BACKUP_DIRS and -BACKUP_FILES can contain wildcards. +When this option is used, @command{tar} leaves the data modification times +of the files it extracts as the times when the files were extracted, +instead of setting it to the times recorded in the archive. -@node Scripted Backups, Scripted Restoration, Backup Parameters, Backup Scripts -@subsection Using the Backup Scripts +This option is meaningless with @option{--list} (@option{-t}). -The syntax for running a backup script is: +@opindex same-owner +@item --same-owner +Create extracted files with the same ownership they have in the +archive. -@example -@file{script-name} [@var{time-to-be-run}] -@end example +This is the default behavior for the superuser, +so this option is meaningful only for non-root users, when @command{tar} +is executed on those systems able to give files away. This is +considered as a security flaw by many people, at least because it +makes quite difficult to correctly account users for the disk space +they occupy. Also, the @code{suid} or @code{sgid} attributes of +files are easily and silently lost when files are given away. + +When writing an archive, @command{tar} writes the user @acronym{ID} and user name +separately. If it can't find a user name (because the user @acronym{ID} is not +in @file{/etc/passwd}), then it does not write one. When restoring, +it tries to look the name (if one was written) up in +@file{/etc/passwd}. If it fails, then it uses the user @acronym{ID} stored in +the archive instead. + +@opindex no-same-owner +@item --no-same-owner +@itemx -o +Do not attempt to restore ownership when extracting. This is the +default behavior for ordinary users, so this option has an effect +only for the superuser. + +@opindex numeric-owner +@item --numeric-owner +The @option{--numeric-owner} option allows (ANSI) archives to be written +without user/group name information or such information to be ignored +when extracting. It effectively disables the generation and/or use +of user/group name information. This option forces extraction using +the numeric ids from the archive, ignoring the names. + +This is useful in certain circumstances, when restoring a backup from +an emergency floppy with different passwd/group files for example. +It is otherwise impossible to extract files with the right ownerships +if the password file in use during the extraction does not match the +one belonging to the file system(s) being extracted. This occurs, +for example, if you are restoring your files after a major crash and +had booted from an emergency floppy with no password file or put your +disk into another machine to do the restore. + +The numeric ids are @emph{always} saved into @command{tar} archives. +The identifying names are added at create time when provided by the +system, unless @option{--format=oldgnu} is used. Numeric ids could be +used when moving archives between a collection of machines using +a centralized management for attribution of numeric ids to users +and groups. This is often made through using the NIS capabilities. + +When making a @command{tar} file for distribution to other sites, it +is sometimes cleaner to use a single owner for all files in the +distribution, and nicer to specify the write permission bits of the +files as stored in the archive independently of their actual value on +the file system. The way to prepare a clean distribution is usually +to have some Makefile rule creating a directory, copying all needed +files in that directory, then setting ownership and permissions as +wanted (there are a lot of possible schemes), and only then making a +@command{tar} archive out of this directory, before cleaning +everything out. Of course, we could add a lot of options to +@GNUTAR{} for fine tuning permissions and ownership. +This is not the good way, I think. @GNUTAR{} is +already crowded with options and moreover, the approach just explained +gives you a great deal of control already. + +@xopindex{same-permissions, short description} +@xopindex{preserve-permissions, short description} +@item -p +@itemx --same-permissions +@itemx --preserve-permissions +Extract all protection information. -where @var{time-to-be-run} can be a specific system time, or can be -@kbd{now}. If you do not specify a time, the script runs at the time -specified in @file{backup-specs} (@pxref{Script Syntax}). +This option causes @command{tar} to set the modes (access permissions) of +extracted files exactly as recorded in the archive. If this option +is not used, the current @code{umask} setting limits the permissions +on extracted files. This option is by default enabled when +@command{tar} is executed by a superuser. -You should start a script with a tape or disk mounted. Once you start -a script, it prompts you for new tapes or disks as it needs them. -Media volumes don't have to correspond to archive files---a -multi-volume archive can be started in the middle of a tape that -already contains the end of another multi-volume archive. The -@code{restore} script prompts for media by its archive volume, so to -avoid an error message you should keep track of which tape (or disk) -contains which volume of the archive. @xref{Scripted Restoration}. -@c <<> longfile} +$ rm -f GNUFileParts.27962 +@end group +@end smallexample + +Notice, that if the @command{tar} implementation you use supports PAX +format archives, it will probably emit warnings about unknown keywords +during extraction. They will look like this: + +@smallexample +@group +Tar file too small +Unknown extended header keyword 'GNU.volume.filename' ignored. +Unknown extended header keyword 'GNU.volume.size' ignored. +Unknown extended header keyword 'GNU.volume.offset' ignored. +@end group +@end smallexample + +@noindent +You can safely ignore these warnings. + +If your @command{tar} implementation is not PAX-aware, you will get +more warnings and more files generated on your disk, e.g.: + +@smallexample +@group +$ @kbd{tar xf vol-1.tar} +var/PaxHeaders.27962/longfile: Unknown file type 'x', extracted as +normal file +Unexpected EOF in archive +$ @kbd{tar xf vol-2.tar} +tmp/GlobalHead.27962.1: Unknown file type 'g', extracted as normal file +GNUFileParts.27962/PaxHeaders.27962/sparsefile.1: Unknown file type +'x', extracted as normal file +@end group +@end smallexample + +Ignore these warnings. The @file{PaxHeaders.*} directories created +will contain files with @dfn{extended header keywords} describing the +extracted files. You can delete them, unless they describe sparse +members. Read further to learn more about them. + +@node Sparse Recovery +@subsubsection Extracting Sparse Members + +@cindex sparse files, extracting with non-GNU tars +Any @command{tar} implementation will be able to extract sparse members from a +PAX archive. However, the extracted files will be @dfn{condensed}, +i.e., any zero blocks will be removed from them. When we restore such +a condensed file to its original form, by adding zero blocks (or +@dfn{holes}) back to their original locations, we call this process +@dfn{expanding} a compressed sparse file. + +@pindex xsparse +To expand a file, you will need a simple auxiliary program called +@command{xsparse}. It is available in source form from +@uref{http://www.gnu.org/@/software/@/tar/@/utils/@/xsparse.html, @GNUTAR{} +home page}. + +@cindex sparse files v.1.0, extracting with non-GNU tars +Let's begin with archive members in @dfn{sparse format +version 1.0}@footnote{@xref{PAX 1}.}, which are the easiest to expand. +The condensed file will contain both file map and file data, so no +additional data will be needed to restore it. If the original file +name was @file{@var{dir}/@var{name}}, then the condensed file will be +named @file{@var{dir}/@/GNUSparseFile.@var{n}/@/@var{name}}, where +@var{n} is a decimal number@footnote{Technically speaking, @var{n} is a +@dfn{process @acronym{ID}} of the @command{tar} process which created the +archive (@pxref{PAX keywords}).}. + +To expand a version 1.0 file, run @command{xsparse} as follows: + +@smallexample +$ @kbd{xsparse @file{cond-file}} +@end smallexample + +@noindent +where @file{cond-file} is the name of the condensed file. The utility +will deduce the name for the resulting expanded file using the +following algorithm: + +@enumerate 1 +@item If @file{cond-file} does not contain any directories, +@file{../cond-file} will be used; + +@item If @file{cond-file} has the form +@file{@var{dir}/@var{t}/@var{name}}, where both @var{t} and @var{name} +are simple names, with no @samp{/} characters in them, the output file +name will be @file{@var{dir}/@var{name}}. + +@item Otherwise, if @file{cond-file} has the form +@file{@var{dir}/@var{name}}, the output file name will be +@file{@var{name}}. +@end enumerate + +In the unlikely case when this algorithm does not suit your needs, +you can explicitly specify output file name as a second argument to +the command: + +@smallexample +$ @kbd{xsparse @file{cond-file} @file{out-file}} +@end smallexample + +It is often a good idea to run @command{xsparse} in @dfn{dry run} mode +first. In this mode, the command does not actually expand the file, +but verbosely lists all actions it would be taking to do so. The dry +run mode is enabled by @option{-n} command line argument: + +@smallexample +@group +$ @kbd{xsparse -n /home/gray/GNUSparseFile.6058/sparsefile} +Reading v.1.0 sparse map +Expanding file '/home/gray/GNUSparseFile.6058/sparsefile' to +'/home/gray/sparsefile' +Finished dry run +@end group +@end smallexample + +To actually expand the file, you would run: + +@smallexample +$ @kbd{xsparse /home/gray/GNUSparseFile.6058/sparsefile} +@end smallexample + +@noindent +The program behaves the same way all UNIX utilities do: it will keep +quiet unless it has simething important to tell you (e.g. an error +condition or something). If you wish it to produce verbose output, +similar to that from the dry run mode, use @option{-v} option: + +@smallexample +@group +$ @kbd{xsparse -v /home/gray/GNUSparseFile.6058/sparsefile} +Reading v.1.0 sparse map +Expanding file '/home/gray/GNUSparseFile.6058/sparsefile' to +'/home/gray/sparsefile' +Done +@end group +@end smallexample + +Additionally, if your @command{tar} implementation has extracted the +@dfn{extended headers} for this file, you can instruct @command{xstar} +to use them in order to verify the integrity of the expanded file. +The option @option{-x} sets the name of the extended header file to +use. Continuing our example: + +@smallexample +@group +$ @kbd{xsparse -v -x /home/gray/PaxHeaders.6058/sparsefile \ + /home/gray/GNUSparseFile.6058/sparsefile} +Reading extended header file +Found variable GNU.sparse.major = 1 +Found variable GNU.sparse.minor = 0 +Found variable GNU.sparse.name = sparsefile +Found variable GNU.sparse.realsize = 217481216 +Reading v.1.0 sparse map +Expanding file '/home/gray/GNUSparseFile.6058/sparsefile' to +'/home/gray/sparsefile' +Done +@end group +@end smallexample + +@anchor{extracting sparse v.0.x} +@cindex sparse files v.0.1, extracting with non-GNU tars +@cindex sparse files v.0.0, extracting with non-GNU tars +An @dfn{extended header} is a special @command{tar} archive header +that precedes an archive member and contains a set of +@dfn{variables}, describing the member properties that cannot be +stored in the standard @code{ustar} header. While optional for +expanding sparse version 1.0 members, the use of extended headers is +mandatory when expanding sparse members in older sparse formats: v.0.0 +and v.0.1 (The sparse formats are described in detail in @ref{Sparse +Formats}.) So, for these formats, the question is: how to obtain +extended headers from the archive? + +If you use a @command{tar} implementation that does not support PAX +format, extended headers for each member will be extracted as a +separate file. If we represent the member name as +@file{@var{dir}/@var{name}}, then the extended header file will be +named @file{@var{dir}/@/PaxHeaders.@var{n}/@/@var{name}}, where +@var{n} is an integer number. + +Things become more difficult if your @command{tar} implementation +does support PAX headers, because in this case you will have to +manually extract the headers. We recommend the following algorithm: + +@enumerate 1 +@item +Consult the documentation of your @command{tar} implementation for an +option that prints @dfn{block numbers} along with the archive +listing (analogous to @GNUTAR{}'s @option{-R} option). For example, +@command{star} has @option{-block-number}. + +@item +Obtain verbose listing using the @samp{block number} option, and +find block numbers of the sparse member in question and the member +immediately following it. For example, running @command{star} on our +archive we obtain: + +@smallexample +@group +$ @kbd{star -t -v -block-number -f arc.tar} +@dots{} +star: Unknown extended header keyword 'GNU.sparse.size' ignored. +star: Unknown extended header keyword 'GNU.sparse.numblocks' ignored. +star: Unknown extended header keyword 'GNU.sparse.name' ignored. +star: Unknown extended header keyword 'GNU.sparse.map' ignored. +block 56: 425984 -rw-r--r-- gray/users Jun 25 14:46 2006 GNUSparseFile.28124/sparsefile +block 897: 65391 -rw-r--r-- gray/users Jun 24 20:06 2006 README +@dots{} +@end group +@end smallexample + +@noindent +(as usual, ignore the warnings about unknown keywords.) + +@item +Let @var{size} be the size of the sparse member, @var{Bs} be its block number +and @var{Bn} be the block number of the next member. +Compute: + +@smallexample +@var{N} = @var{Bs} - @var{Bn} - @var{size}/512 - 2 +@end smallexample + +@noindent +This number gives the size of the extended header part in tar @dfn{blocks}. +In our example, this formula gives: @code{897 - 56 - 425984 / 512 - 2 += 7}. + +@item +Use @command{dd} to extract the headers: + +@smallexample +@kbd{dd if=@var{archive} of=@var{hname} bs=512 skip=@var{Bs} count=@var{N}} +@end smallexample + +@noindent +where @var{archive} is the archive name, @var{hname} is a name of the +file to store the extended header in, @var{Bs} and @var{N} are +computed in previous steps. + +In our example, this command will be + +@smallexample +$ @kbd{dd if=arc.tar of=xhdr bs=512 skip=56 count=7} +@end smallexample +@end enumerate + +Finally, you can expand the condensed file, using the obtained header: + +@smallexample +@group +$ @kbd{xsparse -v -x xhdr GNUSparseFile.6058/sparsefile} +Reading extended header file +Found variable GNU.sparse.size = 217481216 +Found variable GNU.sparse.numblocks = 208 +Found variable GNU.sparse.name = sparsefile +Found variable GNU.sparse.map = 0,2048,1050624,2048,@dots{} +Expanding file 'GNUSparseFile.28124/sparsefile' to 'sparsefile' +Done +@end group +@end smallexample + +@node cpio +@section Comparison of @command{tar} and @command{cpio} +@UNREVISED + +@FIXME{Reorganize the following material} + +The @command{cpio} archive formats, like @command{tar}, do have maximum +file name lengths. The binary and old @acronym{ASCII} formats have a maximum file +length of 256, and the new @acronym{ASCII} and @acronym{CRC ASCII} formats have a max +file length of 1024. @acronym{GNU} @command{cpio} can read and write archives +with arbitrary file name lengths, but other @command{cpio} implementations +may crash unexplainedly trying to read them. + +@command{tar} handles symbolic links in the form in which it comes in @acronym{BSD}; +@command{cpio} doesn't handle symbolic links in the form in which it comes +in System V prior to SVR4, and some vendors may have added symlinks +to their system without enhancing @command{cpio} to know about them. +Others may have enhanced it in a way other than the way I did it +at Sun, and which was adopted by AT&T (and which is, I think, also +present in the @command{cpio} that Berkeley picked up from AT&T and put +into a later @acronym{BSD} release---I think I gave them my changes). + +(SVR4 does some funny stuff with @command{tar}; basically, its @command{cpio} +can handle @command{tar} format input, and write it on output, and it +probably handles symbolic links. They may not have bothered doing +anything to enhance @command{tar} as a result.) + +@command{cpio} handles special files; traditional @command{tar} doesn't. + +@command{tar} comes with V7, System III, System V, and @acronym{BSD} source; +@command{cpio} comes only with System III, System V, and later @acronym{BSD} +(4.3-tahoe and later). + +@command{tar}'s way of handling multiple hard links to a file can handle +file systems that support 32-bit i-numbers (e.g., the @acronym{BSD} file system); +@command{cpio}s way requires you to play some games (in its ``binary'' +format, i-numbers are only 16 bits, and in its ``portable @acronym{ASCII}'' format, +they're 18 bits---it would have to play games with the "file system @acronym{ID}" +field of the header to make sure that the file system @acronym{ID}/i-number pairs +of different files were always different), and I don't know which +@command{cpio}s, if any, play those games. Those that don't might get +confused and think two files are the same file when they're not, and +make hard links between them. + +@command{tar}s way of handling multiple hard links to a file places only +one copy of the link on the tape, but the name attached to that copy +is the @emph{only} one you can use to retrieve the file; @command{cpio}s +way puts one copy for every link, but you can retrieve it using any +of the names. + +@quotation +What type of check sum (if any) is used, and how is this calculated. +@end quotation + +See the attached manual pages for @command{tar} and @command{cpio} format. +@command{tar} uses a checksum which is the sum of all the bytes in the +@command{tar} header for a file; @command{cpio} uses no checksum. + +@quotation +If anyone knows why @command{cpio} was made when @command{tar} was present +at the unix scene, +@end quotation + +It wasn't. @command{cpio} first showed up in PWB/UNIX 1.0; no +generally-available version of UNIX had @command{tar} at the time. I don't +know whether any version that was generally available @emph{within AT&T} +had @command{tar}, or, if so, whether the people within AT&T who did +@command{cpio} knew about it. + +On restore, if there is a corruption on a tape @command{tar} will stop at +that point, while @command{cpio} will skip over it and try to restore the +rest of the files. + +The main difference is just in the command syntax and header format. + +@command{tar} is a little more tape-oriented in that everything is blocked +to start on a record boundary. + +@quotation +Is there any differences between the ability to recover crashed +archives between the two of them. (Is there any chance of recovering +crashed archives at all.) +@end quotation + +Theoretically it should be easier under @command{tar} since the blocking +lets you find a header with some variation of @samp{dd skip=@var{nn}}. +However, modern @command{cpio}'s and variations have an option to just +search for the next file header after an error with a reasonable chance +of resyncing. However, lots of tape driver software won't allow you to +continue past a media error which should be the only reason for getting +out of sync unless a file changed sizes while you were writing the +archive. + +@quotation +If anyone knows why @command{cpio} was made when @command{tar} was present +at the unix scene, please tell me about this too. +@end quotation + +Probably because it is more media efficient (by not blocking everything +and using only the space needed for the headers where @command{tar} +always uses 512 bytes per file header) and it knows how to archive +special files. + +You might want to look at the freely available alternatives. The +major ones are @command{afio}, @GNUTAR{}, and +@command{pax}, each of which have their own extensions with some +backwards compatibility. + +Sparse files were @command{tar}red as sparse files (which you can +easily test, because the resulting archive gets smaller, and +@acronym{GNU} @command{cpio} can no longer read it). + +@node Media +@chapter Tapes and Other Archive Media +@UNREVISED + +A few special cases about tape handling warrant more detailed +description. These special cases are discussed below. + +Many complexities surround the use of @command{tar} on tape drives. Since +the creation and manipulation of archives located on magnetic tape was +the original purpose of @command{tar}, it contains many features making +such manipulation easier. + +Archives are usually written on dismountable media---tape cartridges, +mag tapes, or floppy disks. + +The amount of data a tape or disk holds depends not only on its size, +but also on how it is formatted. A 2400 foot long reel of mag tape +holds 40 megabytes of data when formatted at 1600 bits per inch. The +physically smaller EXABYTE tape cartridge holds 2.3 gigabytes. + +Magnetic media are re-usable---once the archive on a tape is no longer +needed, the archive can be erased and the tape or disk used over. +Media quality does deteriorate with use, however. Most tapes or disks +should be discarded when they begin to produce data errors. EXABYTE +tape cartridges should be discarded when they generate an @dfn{error +count} (number of non-usable bits) of more than 10k. + +Magnetic media are written and erased using magnetic fields, and +should be protected from such fields to avoid damage to stored data. +Sticking a floppy disk to a filing cabinet using a magnet is probably +not a good idea. -If you specify @samp{--all} as the @var{files} argument, the -@code{restore} script extracts all the files in the archived file -system into the active file system. +@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 -@quotation -@strong{Warning:}The script will delete files from the active file -system if they were not in the file system when the archive was made. -@end quotation +@node Device +@section Device Selection and Switching +@UNREVISED -@xref{incremental and listed-incremental}, for an explanation of how -the script makes that determination. -@c this may be an option, not a given -@end ignore +@table @option +@item -f [@var{hostname}:]@var{file} +@itemx --file=[@var{hostname}:]@var{file} +Use archive file or device @var{file} on @var{hostname}. +@end table + +This option is used to specify the file name of the archive @command{tar} +works on. + +If the file name is @samp{-}, @command{tar} reads the archive from standard +input (when listing or extracting), or writes it to standard output +(when creating). If the @samp{-} file name is given when updating an +archive, @command{tar} will read the original archive from its standard +input, and will write the entire new archive to its standard output. + +If the file name contains a @samp{:}, it is interpreted as +@samp{hostname:file name}. If the @var{hostname} contains an @dfn{at} +sign (@samp{@@}), it is treated as @samp{user@@hostname:file name}. In +either case, @command{tar} will invoke the command @command{rsh} (or +@command{remsh}) to start up an @command{/usr/libexec/rmt} on the remote +machine. If you give an alternate login name, it will be given to the +@command{rsh}. +Naturally, the remote machine must have an executable +@command{/usr/libexec/rmt}. This program is free software from the +University of California, and a copy of the source code can be found +with the sources for @command{tar}; it's compiled and installed by default. +The exact path to this utility is determined when configuring the package. +It is @file{@var{prefix}/libexec/rmt}, where @var{prefix} stands for +your installation prefix. This location may also be overridden at +runtime by using the @option{--rmt-command=@var{command}} option (@xref{Option Summary, +---rmt-command}, for detailed description of this option. @xref{Remote +Tape Server}, for the description of @command{rmt} command). + +If this option is not given, but the environment variable @env{TAPE} +is set, its value is used; otherwise, old versions of @command{tar} +used a default archive name (which was picked when @command{tar} was +compiled). The default is normally set up to be the @dfn{first} tape +drive or other transportable I/O medium on the system. + +Starting with version 1.11.5, @GNUTAR{} uses +standard input and standard output as the default device, and I will +not try anymore supporting automatic device detection at installation +time. This was failing really in too many cases, it was hopeless. +This is now completely left to the installer to override standard +input and standard output for default device, if this seems +preferable. Further, I think @emph{most} actual usages of +@command{tar} are done with pipes or disks, not really tapes, +cartridges or diskettes. + +Some users think that using standard input and output is running +after trouble. This could lead to a nasty surprise on your screen if +you forget to specify an output file name---especially if you are going +through a network or terminal server capable of buffering large amounts +of output. We had so many bug reports in that area of configuring +default tapes automatically, and so many contradicting requests, that +we finally consider the problem to be portably intractable. We could +of course use something like @samp{/dev/tape} as a default, but this +is @emph{also} running after various kind of trouble, going from hung +processes to accidental destruction of real tapes. After having seen +all this mess, using standard input and output as a default really +sounds like the only clean choice left, and a very useful one too. + +@GNUTAR{} reads and writes archive in records, I +suspect this is the main reason why block devices are preferred over +character devices. Most probably, block devices are more efficient +too. The installer could also check for @samp{DEFTAPE} in +@file{}. + +@table @option +@xopindex{force-local, short description} +@item --force-local +Archive file is local even if it contains a colon. + +@opindex rsh-command +@item --rsh-command=@var{command} +Use remote @var{command} instead of @command{rsh}. This option exists +so that people who use something other than the standard @command{rsh} +(e.g., a Kerberized @command{rsh}) can access a remote device. + +When this command is not used, the shell command found when +the @command{tar} program was installed is used instead. This is +the first found of @file{/usr/ucb/rsh}, @file{/usr/bin/remsh}, +@file{/usr/bin/rsh}, @file{/usr/bsd/rsh} or @file{/usr/bin/nsh}. +The installer may have overridden this by defining the environment +variable @env{RSH} @emph{at installation time}. + +@item -[0-7][lmh] +Specify drive and density. + +@xopindex{multi-volume, short description} +@item -M +@itemx --multi-volume +Create/list/extract multi-volume archive. + +This option causes @command{tar} to write a @dfn{multi-volume} archive---one +that may be larger than will fit on the medium used to hold it. +@xref{Multi-Volume Archives}. + +@xopindex{tape-length, short description} +@item -L @var{num} +@itemx --tape-length=@var{size}[@var{suf}] +Change tape after writing @var{size} units of data. Unless @var{suf} is +given, @var{size} is treated as kilobytes, i.e. @samp{@var{size} x +1024} bytes. The following suffixes alter this behavior: + +@float Table, size-suffixes +@caption{Size Suffixes} +@multitable @columnfractions 0.2 0.3 0.3 +@headitem Suffix @tab Units @tab Byte Equivalent +@item b @tab Blocks @tab @var{size} x 512 +@item B @tab Kilobytes @tab @var{size} x 1024 +@item c @tab Bytes @tab @var{size} +@item G @tab Gigabytes @tab @var{size} x 1024^3 +@item K @tab Kilobytes @tab @var{size} x 1024 +@item k @tab Kilobytes @tab @var{size} x 1024 +@item M @tab Megabytes @tab @var{size} x 1024^2 +@item P @tab Petabytes @tab @var{size} x 1024^5 +@item T @tab Terabytes @tab @var{size} x 1024^4 +@item w @tab Words @tab @var{size} x 2 +@end multitable +@end float + +This option might be useful when your tape drivers do not properly +detect end of physical tapes. By being slightly conservative on the +maximum tape length, you might avoid the problem entirely. + +@xopindex{info-script, short description} +@xopindex{new-volume-script, short description} +@item -F @var{command} +@itemx --info-script=@var{command} +@itemx --new-volume-script=@var{command} +Execute @var{command} at end of each tape. This implies +@option{--multi-volume} (@option{-M}). @xref{info-script}, for a detailed +description of this option. +@end table -@node incremental and listed-incremental, Problems, Backup Scripts, Backups and Restoration -@section The @code{--incremental} and @code{--listed-incremental} Options - -@samp{--incremental} is used in conjunction with @samp{--create}, -@samp{--extract} or @samp{--list} when backing up and restoring file -systems. An archive cannot be extracted or listed with the -@samp{--incremental} option specified unless it was created with the -option specified. This option should only be used by a script, not by -the user, and is usually disregarded in favor of -@samp{--listed-incremental}, which is described below. - -@samp{--incremental} in conjunction with @samp{--create} causes -@code{tar} to write, at the beginning of the archive, an entry for -each of the directories that will be archived. The entry for a -directory includes a list of all the files in the directory at the -time the archive was created and a flag for each file indicating -whether or not the file is going to be put in the archive. - -Note that this option causes @code{tar} to create a non-standard -archive that may not be readable by non-GNU versions of the @code{tar} -program. - -@samp{--incremental} in conjunction with @samp{--extract} causes -@code{tar} to read the lists of directory contents previously stored -in the archive, @emph{delete} files in the file system that did not -exist in their directories when the archive was created, and then -extract the files in the archive. - -This behavior is convenient when restoring a damaged file system from -a succession of incremental backups: it restores the entire state of -the file system to that which obtained when the backup was made. If -@samp{--incremental} isn't specified, the file system will probably -fill up with files that shouldn't exist any more. - -@samp{--incremental} in conjunction with @samp{--list}, causes -@code{tar} to print, for each directory in the archive, the list of -files in that directory at the time the archive was created. This -information is put out in a format that is not easy for humans to -read, but which is unambiguous for a program: each file name is -preceded by either a @samp{Y} if the file is present in the archive, -an @samp{N} if the file is not included in the archive, or a @samp{D} -if the file is a directory (and is included in the archive). Each -file name is terminated by a null character. The last file is followed -by an additional null and a newline to indicate the end of the data. - -@samp{--listed-incremental}=@var{file} acts like @samp{--incremental}, -but when used in conjunction with @samp{--create} will also cause -@code{tar} to use the file @var{file}, which contains information -about the state of the file system at the time of the last backup, to -decide which files to include in the archive being created. That file -will then be updated by @code{tar}. If the file @var{file} does not -exist when this option is specified, @code{tar} will create it, and -include all appropriate files in the archive. - -The file @var{file}, which is archive independent, contains the date -it was last modified and a list of devices, inode numbers and -directory names. @code{tar} will archive files with newer mod dates -or inode change times, and directories with an unchanged inode number -and device but a changed directory name. The file is updated after -the files to be archived are determined, but before the new archive is -actually created. - -@c <<< this section needs to be written -@node Problems, , incremental and listed-incremental, Backups and Restoration +@node Remote Tape Server +@section Remote Tape Server + +@cindex remote tape drive +@pindex rmt +In order to access the tape drive on a remote machine, @command{tar} +uses the remote tape server written at the University of California at +Berkeley. The remote tape server must be installed as +@file{@var{prefix}/libexec/rmt} on any machine whose tape drive you +want to use. @command{tar} calls @command{rmt} by running an +@command{rsh} or @command{remsh} to the remote machine, optionally +using a different login name if one is supplied. + +A copy of the source for the remote tape server is provided. Its +source code can be freely distributed. It is compiled and +installed by default. + +@cindex absolute file names +Unless you use the @option{--absolute-names} (@option{-P}) option, +@GNUTAR{} will not allow you to create an archive that contains +absolute file names (a file name beginning with @samp{/}.) If you try, +@command{tar} will automatically remove the leading @samp{/} from the +file names it stores in the archive. It will also type a warning +message telling you what it is doing. + +When reading an archive that was created with a different +@command{tar} program, @GNUTAR{} automatically +extracts entries in the archive which have absolute file names as if +the file names were not absolute. This is an important feature. A +visitor here once gave a @command{tar} tape to an operator to restore; +the operator used Sun @command{tar} instead of @GNUTAR{}, +and the result was that it replaced large portions of +our @file{/bin} and friends with versions from the tape; needless to +say, we were unhappy about having to recover the file system from +backup tapes. + +For example, if the archive contained a file @file{/usr/bin/computoy}, +@GNUTAR{} would extract the file to @file{usr/bin/computoy}, +relative to the current directory. If you want to extract the files in +an archive to the same absolute names that they had when the archive +was created, you should do a @samp{cd /} before extracting the files +from the archive, or you should either use the @option{--absolute-names} +option, or use the command @samp{tar -C / @dots{}}. + +@cindex Ultrix 3.1 and write failure +Some versions of Unix (Ultrix 3.1 is known to have this problem), +can claim that a short write near the end of a tape succeeded, +when it actually failed. This will result in the -M option not +working correctly. The best workaround at the moment is to use a +significantly larger blocking factor than the default 20. + +In order to update an archive, @command{tar} must be able to backspace the +archive in order to reread or rewrite a record that was just read (or +written). This is currently possible only on two kinds of files: normal +disk files (or any other file that can be backspaced with @samp{lseek}), +and industry-standard 9-track magnetic tape (or any other kind of tape +that can be backspaced with the @code{MTIOCTOP} @code{ioctl}). + +This means that the @option{--append}, @option{--concatenate}, and +@option{--delete} commands will not work on any other kind of file. +Some media simply cannot be backspaced, which means these commands and +options will never be able to work on them. These non-backspacing +media include pipes and cartridge tape drives. + +Some other media can be backspaced, and @command{tar} will work on them +once @command{tar} is modified to do so. + +Archives created with the @option{--multi-volume}, @option{--label}, and +@option{--incremental} (@option{-G}) options may not be readable by other version +of @command{tar}. In particular, restoring a file that was split over +a volume boundary will require some careful work with @command{dd}, if +it can be done at all. Other versions of @command{tar} may also create +an empty file whose name is that of the volume header. Some versions +of @command{tar} may create normal files instead of directories archived +with the @option{--incremental} (@option{-G}) option. + +@node Common Problems and Solutions @section Some Common Problems and their Solutions +@ifclear PUBLISH + +@format errors from system: permission denied no such file or directory not owner -errors from tar: +errors from @command{tar}: directory checksum error header format error errors from media/system: i/o error device busy +@end format -@node Media, Quick Reference, Backups and Restoration, Top -@chapter Tapes and Other Archive Media +@end ifclear -Archives are usually written on dismountable media---tape cartridges, -mag tapes, or floppy disks. +@node Blocking +@section Blocking +@cindex block +@cindex record -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 formated at 1600 bits per inch. The -physically smaller EXABYTE tape cartridge holds 2.3 gigabytes. +@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. -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 disgarded when they begin to produce data errors. EXABYTE -tape cartridges should be disgarded when they generate an @dfn{error -count} (number of non-usable bits) of more than 10k. +John Gilmore, the writer of the public domain @command{tar} from which +@GNUTAR{} was originally derived, wrote (June 1995): -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. +@quotation +The nomenclature of tape drives comes from IBM, where I believe +they were invented for the IBM 650 or so. On IBM mainframes, what +is recorded on tape are tape blocks. The logical organization of +data is into records. There are various ways of putting records into +blocks, including @code{F} (fixed sized records), @code{V} (variable +sized records), @code{FB} (fixed blocked: fixed size records, @var{n} +to a block), @code{VB} (variable size records, @var{n} to a block), +@code{VSB} (variable spanned blocked: variable sized records that can +occupy more than one block), etc. The @code{JCL} @samp{DD RECFORM=} +parameter specified this to the operating system. + +The Unix man page on @command{tar} was totally confused about this. +When I wrote @code{PD TAR}, I used the historically correct terminology +(@command{tar} writes data records, which are grouped into blocks). +It appears that the bogus terminology made it into @acronym{POSIX} (no surprise +here), and now Fran@,{c}ois has migrated that terminology back +into the source code too. +@end quotation +The term @dfn{physical block} means the basic transfer chunk from or +to a device, after which reading or writing may stop without anything +being lost. In this manual, the term @dfn{block} usually refers to +a disk physical block, @emph{assuming} that each disk block is 512 +bytes in length. It is true that some disk devices have different +physical blocks, but @command{tar} ignore these differences in its own +format, which is meant to be portable, so a @command{tar} block is always +512 bytes in length, and @dfn{block} always mean a @command{tar} block. +The term @dfn{logical block} often represents the basic chunk of +allocation of many disk blocks as a single entity, which the operating +system treats somewhat atomically; this concept is only barely used +in @GNUTAR{}. + +The term @dfn{physical record} is another way to speak of a physical +block, those two terms are somewhat interchangeable. In this manual, +the term @dfn{record} usually refers to a tape physical block, +@emph{assuming} that the @command{tar} archive is kept on magnetic tape. +It is true that archives may be put on disk or used with pipes, +but nevertheless, @command{tar} tries to read and write the archive one +@dfn{record} at a time, whatever the medium in use. One record is made +up of an integral number of blocks, and this operation of putting many +disk blocks into a single tape block is called @dfn{reblocking}, or +more simply, @dfn{blocking}. The term @dfn{logical record} refers to +the logical organization of many characters into something meaningful +to the application. The term @dfn{unit record} describes a small set +of characters which are transmitted whole to or by the application, +and often refers to a line of text. Those two last terms are unrelated +to what we call a @dfn{record} in @GNUTAR{}. + +When writing to tapes, @command{tar} writes the contents of the archive +in chunks known as @dfn{records}. To change the default blocking +factor, use the @option{--blocking-factor=@var{512-size}} (@option{-b +@var{512-size}}) option. Each record will then be composed of +@var{512-size} blocks. (Each @command{tar} block is 512 bytes. +@xref{Standard}.) Each file written to the archive uses at least one +full record. As a result, using a larger record size can result in +more wasted space for small files. On the other hand, a larger record +size can often be read and written much more efficiently. + +Further complicating the problem is that some tape drives ignore the +blocking entirely. For these, a larger record size can still improve +performance (because the software layers above the tape drive still +honor the blocking), but not as dramatically as on tape drives that +honor blocking. + +When reading an archive, @command{tar} can usually figure out the +record size on itself. When this is the case, and a non-standard +record size was used when the archive was created, @command{tar} will +print a message about a non-standard blocking factor, and then operate +normally@footnote{If this message is not needed, you can turn it off +using the @option{--warning=no-record-size} option.}. On some tape +devices, however, @command{tar} cannot figure out the record size +itself. On most of those, you can specify a blocking factor (with +@option{--blocking-factor}) larger than the actual blocking factor, +and then use the @option{--read-full-records} (@option{-B}) option. +(If you specify a blocking factor with @option{--blocking-factor} and +don't use the @option{--read-full-records} option, then @command{tar} +will not attempt to figure out the recording size itself.) On some +devices, you must always specify the record size exactly with +@option{--blocking-factor} when reading, because @command{tar} cannot +figure it out. In any case, use @option{--list} (@option{-t}) before +doing any extractions to see whether @command{tar} is reading the archive +correctly. + +@command{tar} blocks are all fixed size (512 bytes), and its scheme for +putting them into records is to put a whole number of them (one or +more) into each record. @command{tar} records are all the same size; +at the end of the file there's a block containing all zeros, which +is how you tell that the remainder of the last record(s) are garbage. + +In a standard @command{tar} file (no options), the block size is 512 +and the record size is 10240, for a blocking factor of 20. What the +@option{--blocking-factor} option does is sets the blocking factor, +changing the record size while leaving the block size at 512 bytes. +20 was fine for ancient 800 or 1600 bpi reel-to-reel tape drives; +most tape drives these days prefer much bigger records in order to +stream and not waste tape. When writing tapes for myself, some tend +to use a factor of the order of 2048, say, giving a record size of +around one megabyte. + +If you use a blocking factor larger than 20, older @command{tar} +programs might not be able to read the archive, so we recommend this +as a limit to use in practice. @GNUTAR{}, however, +will support arbitrarily large record sizes, limited only by the +amount of virtual memory or the physical characteristics of the tape +device. @menu -* Write Protection:: Write Protection -* Tape Positioning:: Tape Positions and Tape Marks +* Format Variations:: Format Variations +* Blocking Factor:: The Blocking Factor of an Archive @end menu -@node Write Protection, Tape Positioning, Media, Media -@section Write Protection +@node Format Variations +@subsection Format Variations +@cindex Format Parameters +@cindex Format Options +@cindex Options, archive format specifying +@cindex Options, format specifying +@UNREVISED -All tapes and 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 accidently -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). +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. -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. +To specify format parameters when accessing or creating an archive, +you can use the options described in the following sections. +If you do not specify any format parameters, @command{tar} uses +default parameters. You cannot modify a compressed archive. +If you create an archive with the @option{--blocking-factor} option +specified (@pxref{Blocking Factor}), you must specify that +blocking-factor when operating on the archive. @xref{Formats}, for other +examples of format parameter considerations. + +@node Blocking Factor +@subsection The Blocking Factor of an Archive +@cindex Blocking Factor +@cindex Record Size +@cindex Number of blocks per record +@cindex Number of bytes per record +@cindex Bytes per record +@cindex Blocks per record +@UNREVISED + +@opindex blocking-factor +The data in an archive is grouped into blocks, which are 512 bytes. +Blocks are read and written in whole number multiples called +@dfn{records}. The number of blocks in a record (i.e., the size of a +record in units of 512 bytes) is called the @dfn{blocking factor}. +The @option{--blocking-factor=@var{512-size}} (@option{-b +@var{512-size}}) option specifies the blocking factor of an archive. +The default blocking factor is typically 20 (i.e., 10240 bytes), but +can be specified at installation. To find out the blocking factor of +an existing archive, use @samp{tar --list --file=@var{archive-name}}. +This may not work on some devices. + +Records are separated by gaps, which waste space on the archive media. +If you are archiving on magnetic tape, using a larger blocking factor +(and therefore larger records) provides faster throughput and allows you +to fit more data on a tape (because there are fewer gaps). If you are +archiving on cartridge, a very large blocking factor (say 126 or more) +greatly increases performance. A smaller blocking factor, on the other +hand, may be useful when archiving small files, to avoid archiving lots +of nulls as @command{tar} fills out the archive to the end of the record. +In general, the ideal record size depends on the size of the +inter-record gaps on the tape you are using, and the average size of the +files you are archiving. @xref{create}, for information on +writing archives. + +@FIXME{Need example of using a cartridge with blocking factor=126 or more.} + +Archives with blocking factors larger than 20 cannot be read +by very old versions of @command{tar}, or by some newer versions +of @command{tar} running on old machines with small address spaces. +With @GNUTAR{}, the blocking factor of an archive is limited +only by the maximum record size of the device containing the archive, +or by the amount of available virtual memory. + +Also, on some systems, not using adequate blocking factors, as sometimes +imposed by the device drivers, may yield unexpected diagnostics. For +example, this has been reported: + +@smallexample +Cannot write to /dev/dlt: Invalid argument +@end smallexample + +@noindent +In such cases, it sometimes happen that the @command{tar} bundled by +the system is aware of block size idiosyncrasies, while @GNUTAR{} +requires an explicit specification for the block size, +which it cannot guess. This yields some people to consider +@GNUTAR{} is misbehaving, because by comparison, +@cite{the bundle @command{tar} works OK}. Adding @w{@kbd{-b 256}}, +for example, might resolve the problem. + +If you use a non-default blocking factor when you create an archive, you +must specify the same blocking factor when you modify that archive. Some +archive devices will also require you to specify the blocking factor when +reading that archive, however this is not typically the case. Usually, you +can use @option{--list} (@option{-t}) without specifying a blocking factor---@command{tar} +reports a non-default record size and then lists the archive members as +it would normally. To extract files from an archive with a non-standard +blocking factor (particularly if you're not sure what the blocking factor +is), you can usually use the @option{--read-full-records} (@option{-B}) option while +specifying a blocking factor larger then the blocking factor of the archive +(i.e., @samp{tar --extract --read-full-records --blocking-factor=300}). +@xref{list}, for more information on the @option{--list} (@option{-t}) +operation. @xref{Reading}, for a more detailed explanation of that option. + +@table @option +@item --blocking-factor=@var{number} +@itemx -b @var{number} +Specifies the blocking factor of an archive. Can be used with any +operation, but is usually not necessary with @option{--list} (@option{-t}). +@end table + +Device blocking + +@table @option +@item -b @var{blocks} +@itemx --blocking-factor=@var{blocks} +Set record size to @math{@var{blocks}*512} bytes. + +This option is used to specify a @dfn{blocking factor} for the archive. +When reading or writing the archive, @command{tar}, will do reads and writes +of the archive in records of @math{@var{block}*512} bytes. This is true +even when the archive is compressed. Some devices requires that all +write operations be a multiple of a certain size, and so, @command{tar} +pads the archive out to the next record boundary. + +The default blocking factor is set when @command{tar} is compiled, and is +typically 20. Blocking factors larger than 20 cannot be read by very +old versions of @command{tar}, or by some newer versions of @command{tar} +running on old machines with small address spaces. + +With a magnetic tape, larger records give faster throughput and fit +more data on a tape (because there are fewer inter-record gaps). +If the archive is in a disk file or a pipe, you may want to specify +a smaller blocking factor, since a large one will result in a large +number of null bytes at the end of the archive. + +When writing cartridge or other streaming tapes, a much larger +blocking factor (say 126 or more) will greatly increase performance. +However, you must specify the same blocking factor when reading or +updating the archive. + +Apparently, Exabyte drives have a physical block size of 8K bytes. +If we choose our blocksize as a multiple of 8k bytes, then the problem +seems to disappear. Id est, we are using block size of 112 right +now, and we haven't had the problem since we switched@dots{} + +With @GNUTAR{} the blocking factor is limited only +by the maximum record size of the device containing the archive, or by +the amount of available virtual memory. + +However, deblocking or reblocking is virtually avoided in a special +case which often occurs in practice, but which requires all the +following conditions to be simultaneously true: +@itemize @bullet +@item +the archive is subject to a compression option, +@item +the archive is not handled through standard input or output, nor +redirected nor piped, +@item +the archive is directly handled to a local disk, instead of any special +device, +@item +@option{--blocking-factor} is not explicitly specified on the @command{tar} +invocation. +@end itemize + +If the output goes directly to a local disk, and not through +stdout, then the last write is not extended to a full record size. +Otherwise, reblocking occurs. Here are a few other remarks on this +topic: + +@itemize @bullet + +@item +@command{gzip} will complain about trailing garbage if asked to +uncompress a compressed archive on tape, there is an option to turn +the message off, but it breaks the regularity of simply having to use +@samp{@var{prog} -d} for decompression. It would be nice if gzip was +silently ignoring any number of trailing zeros. I'll ask Jean-loup +Gailly, by sending a copy of this message to him. + +@item +@command{compress} does not show this problem, but as Jean-loup pointed +out to Michael, @samp{compress -d} silently adds garbage after +the result of decompression, which tar ignores because it already +recognized its end-of-file indicator. So this bug may be safely +ignored. + +@item +@samp{gzip -d -q} will be silent about the trailing zeros indeed, +but will still return an exit status of 2 which tar reports in turn. +@command{tar} might ignore the exit status returned, but I hate doing +that, as it weakens the protection @command{tar} offers users against +other possible problems at decompression time. If @command{gzip} was +silently skipping trailing zeros @emph{and} also avoiding setting the +exit status in this innocuous case, that would solve this situation. + +@item +@command{tar} should become more solid at not stopping to read a pipe at +the first null block encountered. This inelegantly breaks the pipe. +@command{tar} should rather drain the pipe out before exiting itself. +@end itemize + +@xopindex{ignore-zeros, short description} +@item -i +@itemx --ignore-zeros +Ignore blocks of zeros in archive (means EOF). + +The @option{--ignore-zeros} (@option{-i}) option causes @command{tar} to ignore blocks +of zeros in the archive. Normally a block of zeros indicates the +end of the archive, but when reading a damaged archive, or one which +was created by concatenating several archives together, this option +allows @command{tar} to read the entire archive. This option is not on +by default because many versions of @command{tar} write garbage after +the zeroed blocks. + +Note that this option causes @command{tar} to read to the end of the +archive file, which may sometimes avoid problems when multiple files +are stored on a single physical tape. + +@xopindex{read-full-records, short description} +@item -B +@itemx --read-full-records +Reblock as we read (for reading 4.2@acronym{BSD} pipes). + +If @option{--read-full-records} is used, @command{tar} +will not panic if an attempt to read a record from the archive does +not return a full record. Instead, @command{tar} will keep reading +until it has obtained a full +record. + +This option is turned on by default when @command{tar} is reading +an archive from standard input, or from a remote machine. This is +because on @acronym{BSD} Unix systems, a read of a pipe will return however +much happens to be in the pipe, even if it is less than @command{tar} +requested. If this option was not used, @command{tar} would fail as +soon as it read an incomplete record from the pipe. + +This option is also useful with the commands for updating an archive. + +@end table + +Tape blocking + +@FIXME{Appropriate options should be moved here from elsewhere.} + +@cindex blocking factor +@cindex tape blocking + +When handling various tapes or cartridges, you have to take care of +selecting a proper blocking, that is, the number of disk blocks you +put together as a single tape block on the tape, without intervening +tape gaps. A @dfn{tape gap} is a small landing area on the tape +with no information on it, used for decelerating the tape to a +full stop, and for later regaining the reading or writing speed. +When the tape driver starts reading a record, the record has to +be read whole without stopping, as a tape gap is needed to stop the +tape motion without losing information. + +@cindex Exabyte blocking +@cindex DAT blocking +Using higher blocking (putting more disk blocks per tape block) will use +the tape more efficiently as there will be less tape gaps. But reading +such tapes may be more difficult for the system, as more memory will be +required to receive at once the whole record. Further, if there is a +reading error on a huge record, this is less likely that the system will +succeed in recovering the information. So, blocking should not be too +low, nor it should be too high. @command{tar} uses by default a blocking of +20 for historical reasons, and it does not really matter when reading or +writing to disk. Current tape technology would easily accommodate higher +blockings. Sun recommends a blocking of 126 for Exabytes and 96 for DATs. +We were told that for some DLT drives, the blocking should be a multiple +of 4Kb, preferably 64Kb (@w{@kbd{-b 128}}) or 256 for decent performance. +Other manufacturers may use different recommendations for the same tapes. +This might also depends of the buffering techniques used inside modern +tape controllers. Some imposes a minimum blocking, or a maximum blocking. +Others request blocking to be some exponent of two. + +So, there is no fixed rule for blocking. But blocking at read time +should ideally be the same as blocking used at write time. At one place +I know, with a wide variety of equipment, they found it best to use a +blocking of 32 to guarantee that their tapes are fully interchangeable. + +I was also told that, for recycled tapes, prior erasure (by the same +drive unit that will be used to create the archives) sometimes lowers +the error rates observed at rewriting time. + +I might also use @option{--number-blocks} instead of +@option{--block-number}, so @option{--block} will then expand to +@option{--blocking-factor} unambiguously. + +@node Many +@section Many Archives on One Tape + +@FIXME{Appropriate options should be moved here from elsewhere.} + +@findex ntape @r{device} +Most tape devices have two entries in the @file{/dev} directory, or +entries that come in pairs, which differ only in the minor number for +this device. Let's take for example @file{/dev/tape}, which often +points to the only or usual tape device of a given system. There might +be a corresponding @file{/dev/nrtape} or @file{/dev/ntape}. The simpler +name is the @emph{rewinding} version of the device, while the name +having @samp{nr} in it is the @emph{no rewinding} version of the same +device. + +A rewinding tape device will bring back the tape to its beginning point +automatically when this device is opened or closed. Since @command{tar} +opens the archive file before using it and closes it afterwards, this +means that a simple: + +@smallexample +$ @kbd{tar cf /dev/tape @var{directory}} +@end smallexample + +@noindent +will reposition the tape to its beginning both prior and after saving +@var{directory} contents to it, thus erasing prior tape contents and +making it so that any subsequent write operation will destroy what has +just been saved. + +@cindex tape positioning +So, a rewinding device is normally meant to hold one and only one file. +If you want to put more than one @command{tar} archive on a given tape, you +will need to avoid using the rewinding version of the tape device. You +will also have to pay special attention to tape positioning. Errors in +positioning may overwrite the valuable data already on your tape. Many +people, burnt by past experiences, will only use rewinding devices and +limit themselves to one file per tape, precisely to avoid the risk of +such errors. Be fully aware that writing at the wrong position on a +tape loses all information past this point and most probably until the +end of the tape, and this destroyed information @emph{cannot} be +recovered. + +To save @var{directory-1} as a first archive at the beginning of a +tape, and leave that tape ready for a second archive, you should use: + +@smallexample +$ @kbd{mt -f /dev/nrtape rewind} +$ @kbd{tar cf /dev/nrtape @var{directory-1}} +@end smallexample + +@cindex tape marks +@dfn{Tape marks} are special magnetic patterns written on the tape +media, which are later recognizable by the reading hardware. These +marks are used after each file, when there are many on a single tape. +An empty file (that is to say, two tape marks in a row) signal the +logical end of the tape, after which no file exist. Usually, +non-rewinding tape device drivers will react to the close request issued +by @command{tar} by first writing two tape marks after your archive, and by +backspacing over one of these. So, if you remove the tape at that time +from the tape drive, it is properly terminated. But if you write +another file at the current position, the second tape mark will be +erased by the new information, leaving only one tape mark between files. + +So, you may now save @var{directory-2} as a second archive after the +first on the same tape by issuing the command: + +@smallexample +$ @kbd{tar cf /dev/nrtape @var{directory-2}} +@end smallexample + +@noindent +and so on for all the archives you want to put on the same tape. + +Another usual case is that you do not write all the archives the same +day, and you need to remove and store the tape between two archive +sessions. In general, you must remember how many files are already +saved on your tape. Suppose your tape already has 16 files on it, and +that you are ready to write the 17th. You have to take care of skipping +the first 16 tape marks before saving @var{directory-17}, say, by using +these commands: -@node Tape Positioning, , Write Protection, Media -@section Tape Positions and Tape Marks +@smallexample +$ @kbd{mt -f /dev/nrtape rewind} +$ @kbd{mt -f /dev/nrtape fsf 16} +$ @kbd{tar cf /dev/nrtape @var{directory-17}} +@end smallexample + +In all the previous examples, we put aside blocking considerations, but +you should do the proper things for that as well. @xref{Blocking}. + +@menu +* Tape Positioning:: Tape Positions and Tape Marks +* mt:: The @command{mt} Utility +@end menu + +@node Tape Positioning +@subsection Tape Positions and Tape Marks +@UNREVISED Just as archives can store more than one file from the file system, tapes can store more than one archive file. To keep track of where @@ -2552,26 +11238,25 @@ end, tape archive devices write magnetic @dfn{tape marks} on the archive media. Tape drives write one tape mark between files, two at the end of all the file entries. -If you think of data as a series of "0000"'s, and tape marks as "x"'s, -a tape might look like the following: +If you think of data as a series of records "rrrr"'s, and tape marks as +"*"'s, a tape might look like the following: -@example -0000x000000x00000x00x00000xx------------------------- -@end example +@smallexample +rrrr*rrrrrr*rrrrr*rr*rrrrr**------------------------- +@end smallexample Tape devices read and write tapes using a read/write @dfn{tape -head}---a physical part of the device which can only access one point -on the tape at a time. When you use @code{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). +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. @xref{Scripted -Restoration}). @xref{mt}, for an explanation of the tape moving -utility. +the beginning of the archive you want to read. You can do it manually +via @code{mt} utility (@pxref{mt}). The @code{restore} script does +that automatically (@pxref{Scripted Restoration}). If you want to add new archive file entries to a tape, you should advance the tape to the end of the existing file entries, backspace @@ -2579,813 +11264,1315 @@ 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: -@example -0000x000000x00000x00x00000x000x0000xx---------------- -@end example - -@menu -* mt:: The @code{mt} Utility -@end menu +@smallexample +rrrr*rrrrrr*rrrrr*rr*rrrrr*rrr*rrrr**---------------- +@end smallexample -@node mt, , Tape Positioning, Tape Positioning -@subsection The @code{mt} Utility +@node mt +@subsection The @command{mt} Utility +@UNREVISED -<<< is it true that this only works on non-block devices? should -<<< explain the difference, xref to block-size (fixed or variable). +@FIXME{Is it true that this only works on non-block devices? +should explain the difference, (fixed or variable).} +@xref{Blocking Factor}. -You can use the @code{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. -@c why isn't there an "advance 'til you find two tape marks together"? +You can use the @command{mt} utility to advance or rewind a tape past a +specified number of archive files on the tape. This will allow you +to move to the beginning of an archive before extracting or reading +it, or to the end of all the archives before writing a new one. +@FIXME{Why isn't there an "advance 'til you find two tape marks +together"?} -The syntax of the @code{mt} command is: +The syntax of the @command{mt} command is: -@example -mt [-f @var{tapename}] @var{operation} [@var{number}] -@end example +@smallexample +@kbd{mt [-f @var{tapename}] @var{operation} [@var{number}]} +@end smallexample where @var{tapename} is the name of the tape device, @var{number} is the number of times an operation is performed (with a default of one), and @var{operation} is one of the following: -@table @code +@FIXME{is there any use for record operations?} + +@table @option @item eof @itemx weof Writes @var{number} tape marks at the current position on the tape. - -@item fsf +@item fsf Moves tape position forward @var{number} files. - @item bsf Moves tape position back @var{number} files. - @item rewind -Rewinds the tape. (Ignores @var{number}). - +Rewinds the tape. (Ignores @var{number}.) @item offline @itemx rewoff1 -Rewinds the tape and takes the tape device off-line. (Ignores @var{number}). - +Rewinds the tape and takes the tape device off-line. (Ignores @var{number}.) @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}. +If you don't specify a @var{tapename}, @command{mt} uses the environment +variable @env{TAPE}; if @env{TAPE} is not set, @command{mt} will use +the default device specified in your @file{sys/mtio.h} file +(@code{DEFTAPE} variable). If this is not defined, the program will +display a descriptive error message and exit with code 1. -@code{mt} returns a 0 exit status when the operation(s) were +@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. -@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 - -@code{tar --list --label} will cause @code{tar} to print the label. - -@c <<< MIB -- program to list all the labels on a tape? - -@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?) +@node Using Multiple Tapes +@section Using Multiple Tapes + +Often you might want to write a large archive, one larger than will fit +on the actual tape you are using. In such a case, you can run multiple +@command{tar} commands, but this can be inconvenient, particularly if you +are using options like @option{--exclude=@var{pattern}} or dumping entire file systems. +Therefore, @command{tar} provides a special mode for creating +multi-volume archives. + +@dfn{Multi-volume} archive is a single @command{tar} archive, stored +on several media volumes of fixed size. Although in this section we will +often call @samp{volume} a @dfn{tape}, there is absolutely no +requirement for multi-volume archives to be stored on tapes. Instead, +they can use whatever media type the user finds convenient, they can +even be located on files. + +When creating a multi-volume archive, @GNUTAR{} continues to fill +current volume until it runs out of space, then it switches to +next volume (usually the operator is queried to replace the tape on +this point), and continues working on the new volume. This operation +continues until all requested files are dumped. If @GNUTAR{} detects +end of media while dumping a file, such a file is archived in split +form. Some very big files can even be split across several volumes. + +Each volume is itself a valid @GNUTAR{} archive, so it can be read +without any special options. Consequently any file member residing +entirely on one volume can be extracted or otherwise operated upon +without needing the other volume. Sure enough, to extract a split +member you would need all volumes its parts reside on. + +Multi-volume archives suffer from several limitations. In particular, +they cannot be compressed. + +@GNUTAR{} is able to create multi-volume archives of two formats +(@pxref{Formats}): @samp{GNU} and @samp{POSIX}. @menu -* Operations:: A Table of Operations -* Options:: Table of Options -@end menu - -@node Operations, Options, Quick Reference, Quick Reference -@appendixsec A Table of Operations -@c add xrefs, note synonyms - -The operation argument to @code{tar} specifies which action you want to -take. - -@table @samp -@item -A -Adds copies of an archive or archives to the end of another archive. +* Multi-Volume Archives:: Archives Longer than One Tape or Disk +* Tape Files:: Tape Files +* Tarcat:: Concatenate Volumes into a Single Archive -@item -c -Creates a new archive. - -@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. - -@item -r -Adds files to the end of the archive. - -@item -t -Prints a list of the contents of the archive. - -@item -x -Reads files from the archive and writes them into the active file -system. - -@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. - -@item --add-archive -Adds copies of an archive or archives to the end of another archive. - -@item --add-file -Adds files to the end of the archive. - -@item --append -Adds files to the end of the archive. - -@item --catenate -Adds copies of an archive or archives to the end of another archive. - -@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. - -@item --concatenate -Adds copies of an archive or archives to the end of another archive. - -@item --create -Creates a new archive. - -@item --delete -Deletes files from the archive. All versions of the files are deleted. - -@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. - -@item --extract -Reads files from the archive and writes them into the active file -system. +@end menu -@item --get -Reads files from the archive and writes them into the active file -system. +@node Multi-Volume Archives +@subsection Archives Longer than One Tape or Disk +@cindex Multi-volume archives -@item --help -Prints a list of @code{tar} operations and options. +@opindex multi-volume +To create an archive that is larger than will fit on a single unit of +the media, use the @option{--multi-volume} (@option{-M}) option in conjunction with +the @option{--create} option (@pxref{create}). A @dfn{multi-volume} +archive can be manipulated like any other archive (provided the +@option{--multi-volume} option is specified), but is stored on more +than one tape or file. -@item --list -Prints a list of the contents of the archive. +When you specify @option{--multi-volume}, @command{tar} does not report an +error when it comes to the end of an archive volume (when reading), or +the end of the media (when writing). Instead, it prompts you to load +a new storage volume. If the archive is on a magnetic tape, you +should change tapes when you see the prompt; if the archive is on a +floppy disk, you should change disks; etc. -@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. +@table @option +@item --multi-volume +@itemx -M +Creates a multi-volume archive, when used in conjunction with +@option{--create} (@option{-c}). To perform any other operation on a multi-volume +archive, specify @option{--multi-volume} in conjunction with that +operation. +For example: -@item --version -Prints the version number of the @code{tar} program to the standard -error. +@smallexample +$ @kbd{tar --create --multi-volume --file=/dev/tape @var{files}} +@end smallexample @end table -@node Options, , Operations, Quick Reference -@appendixsec Table of Options +The method @command{tar} uses to detect end of tape is not perfect, and +fails on some operating systems or on some devices. If @command{tar} +cannot detect the end of the tape itself, you can use +@option{--tape-length} option to inform it about the capacity of the +tape: + +@anchor{tape-length} +@table @option +@opindex tape-length +@item --tape-length=@var{size}[@var{suf}] +@itemx -L @var{size}[@var{suf}] +Set maximum length of a volume. The @var{suf}, if given, specifies +units in which @var{size} is expressed, e.g. @samp{2M} mean 2 +megabytes (@pxref{size-suffixes}, for a list of allowed size +suffixes). Without @var{suf}, units of 1024 bytes (kilobyte) are +assumed. + +This option selects @option{--multi-volume} automatically. For example: + +@smallexample +$ @kbd{tar --create --tape-length=41943040 --file=/dev/tape @var{files}} +@end smallexample -Options change the way @code{tar} performs an operation. - -@table @samp -@item --absolute-paths -WILL BE INPUT WHEN QUESTION IS RESOLVED +@noindent +or, which is equivalent: -@item --after-date=@var{date} -Limit the operation to files changed after the given date. -@xref{File Exclusion}. +@smallexample +$ @kbd{tar --create --tape-length=4G --file=/dev/tape @var{files}} +@end smallexample +@end table -@item --block-size=@var{number} -Specify the blocking factor of an archive. @xref{Blocking Factor}. +@anchor{change volume prompt} +When @GNUTAR{} comes to the end of a storage media, it asks you to +change the volume. The built-in prompt for POSIX locale +is@footnote{If you run @GNUTAR{} under a different locale, the +translation to the locale's language will be used.}: -@item --compress -Specify a compressed archive. @xref{Compressed Archives}. +@smallexample +Prepare volume #@var{n} for '@var{archive}' and hit return: +@end smallexample -@item --compress-block. -Create a whole block sized compressed archive. @xref{Compressed Archives}. +@noindent +where @var{n} is the ordinal number of the volume to be created and +@var{archive} is archive file or device name. + +When prompting for a new tape, @command{tar} accepts any of the following +responses: + +@table @kbd +@item ? +Request @command{tar} to explain possible responses. +@item q +Request @command{tar} to exit immediately. +@item n @var{file-name} +Request @command{tar} to write the next volume on the file @var{file-name}. +@item ! +Request @command{tar} to run a subshell. This option can be disabled +by giving @option{--restrict} command line option to +@command{tar}@footnote{@xref{--restrict}, for more information about +this option.}. +@item y +Request @command{tar} to begin writing the next volume. +@end table -@item --confirmation -Solicit confirmation for each file. @xref{Interactive Operation} -<<< --selective should be a synonym. +(You should only type @samp{y} after you have changed the tape; +otherwise @command{tar} will write over the volume it just finished.) + +@cindex Volume number file +@cindex volno file +@anchor{volno-file} +@opindex volno-file +The volume number used by @command{tar} in its tape-changing prompt +can be changed; if you give the +@option{--volno-file=@var{file-of-number}} option, then +@var{file-of-number} should be an non-existing file to be created, or +else, a file already containing a decimal number. That number will be +used as the volume number of the first volume written. When +@command{tar} is finished, it will rewrite the file with the +now-current volume number. (This does not change the volume number +written on a tape label, as per @ref{label}, it @emph{only} affects +the number used in the prompt.) + +@cindex End-of-archive info script +@cindex Info script +@anchor{info-script} +@opindex info-script +@opindex new-volume-script +If you want more elaborate behavior than this, you can write a special +@dfn{new volume script}, that will be responsible for changing the +volume, and instruct @command{tar} to use it instead of its normal +prompting procedure: + +@table @option +@item --info-script=@var{command} +@itemx --new-volume-script=@var{command} +@itemx -F @var{command} +Specify the command to invoke when switching volumes. The @var{command} +can be used to eject cassettes, or to broadcast messages such as +@samp{Someone please come change my tape} when performing unattended +backups. +@end table -@item --dereference -Treat a symbolic link as an alternate name for the file the link -points to. @xref{Symbolic Links}. +The @var{command} can contain additional options, if such are needed. +@xref{external, Running External Commands}, for a detailed discussion +of the way @GNUTAR{} runs external commands. It inherits +@command{tar}'s shell environment. Additional data is passed to it +via the following environment variables: + +@table @env +@vrindex TAR_VERSION, info script environment variable +@item TAR_VERSION +@GNUTAR{} version number. + +@vrindex TAR_ARCHIVE, info script environment variable +@item TAR_ARCHIVE +The name of the archive @command{tar} is processing. + +@vrindex TAR_BLOCKING_FACTOR, info script environment variable +@item TAR_BLOCKING_FACTOR +Current blocking factor (@pxref{Blocking}). + +@vrindex TAR_VOLUME, info script environment variable +@item TAR_VOLUME +Ordinal number of the volume @command{tar} is about to start. + +@vrindex TAR_SUBCOMMAND, info script environment variable +@item TAR_SUBCOMMAND +A short option describing the operation @command{tar} is executing. +@xref{Operations}, for a complete list of subcommand options. + +@vrindex TAR_FORMAT, info script environment variable +@item TAR_FORMAT +Format of the archive being processed. @xref{Formats}, for a complete +list of archive format names. + +@vrindex TAR_FD, info script environment variable +@item TAR_FD +File descriptor which can be used to communicate the new volume +name to @command{tar}. +@end table -@item --directory=@file{directory} -Change the working directory. @xref{Changing Working Directory}. +These variables can be used in the @var{command} itself, provided that +they are properly quoted to prevent them from being expanded by the +shell that invokes @command{tar}. + +The volume script can instruct @command{tar} to use new archive name, +by writing in to file descriptor @env{$TAR_FD} (see below for an example). + +If the info script fails, @command{tar} exits; otherwise, it begins +writing the next volume. + +If you want @command{tar} to cycle through a series of files or tape +drives, there are three approaches to choose from. First of all, you +can give @command{tar} multiple @option{--file} options. In this case +the specified files will be used, in sequence, as the successive +volumes of the archive. Only when the first one in the sequence needs +to be used again will @command{tar} prompt for a tape change (or run +the info script). For example, suppose someone has two tape drives on +a system named @file{/dev/tape0} and @file{/dev/tape1}. For having +@GNUTAR{} to switch to the second drive when it needs to write the +second tape, and then back to the first tape, etc., just do either of: + +@smallexample +$ @kbd{tar --create --multi-volume --file=/dev/tape0 --file=/dev/tape1 @var{files}} +$ @kbd{tar -cM -f /dev/tape0 -f /dev/tape1 @var{files}} +@end smallexample + +The second method is to use the @samp{n} response to the tape-change +prompt. + +Finally, the most flexible approach is to use a volume script, that +writes new archive name to the file descriptor @env{$TAR_FD}. For example, the +following volume script will create a series of archive files, named +@file{@var{archive}-@var{vol}}, where @var{archive} is the name of the +archive being created (as given by @option{--file} option) and +@var{vol} is the ordinal number of the archive being created: + +@smallexample +@group +#! /bin/bash +# For this script it's advisable to use a shell, such as Bash, +# that supports a TAR_FD value greater than 9. + +echo Preparing volume $TAR_VOLUME of $TAR_ARCHIVE. + +name=`expr $TAR_ARCHIVE : '\(.*\)-.*'` +case $TAR_SUBCOMMAND in +-c) ;; +-d|-x|-t) test -r $@{name:-$TAR_ARCHIVE@}-$TAR_VOLUME || exit 1 + ;; +*) exit 1 +esac + +echo $@{name:-$TAR_ARCHIVE@}-$TAR_VOLUME >&$TAR_FD +@end group +@end smallexample + +The same script can be used while listing, comparing or extracting +from the created archive. For example: + +@smallexample +@group +# @r{Create a multi-volume archive:} +$ @kbd{tar -c -L1024 -f archive.tar -F new-volume .} +# @r{Extract from the created archive:} +$ @kbd{tar -x -f archive.tar -F new-volume .} +@end group +@end smallexample -@item --exclude=@var{pattern} -Exclude files which match the regular expression @var{pattern}. -@xref{File Exclusion}. +@noindent +Notice, that the first command had to use @option{-L} option, since +otherwise @GNUTAR{} will end up writing everything to file +@file{archive.tar}. -@item --exclude-from=@file{file} -Exclude files which match any of the regular expressions listed in -the file @file{file}. @xref{File Exclusion}. +You can read each individual volume of a multi-volume archive as if it +were an archive by itself. For example, to list the contents of one +volume, use @option{--list}, without @option{--multi-volume} specified. +To extract an archive member from one volume (assuming it is described +that volume), use @option{--extract}, again without +@option{--multi-volume}. -@item --file=@var{archive-name} -Name the archive. @xref{Archive Name}). +If an archive member is split across volumes (i.e., its entry begins on +one volume of the media and ends on another), you need to specify +@option{--multi-volume} to extract it successfully. In this case, you +should load the volume where the archive member starts, and use +@samp{tar --extract --multi-volume}---@command{tar} will prompt for later +volumes as it needs them. @xref{extracting archives}, for more +information about extracting archives. -@item --files-from=@file{file} -Read file-name arguments from a file on the file system. -@xref{File Name Lists}. +Multi-volume archives can be modified like any other archive. To add +files to a multi-volume archive, you need to only mount the last +volume of the archive media (and new volumes, if needed). For all +other operations, you need to use the entire archive. + +If a multi-volume archive was labeled using +@option{--label=@var{archive-label}} (@pxref{label}) when it was +created, @command{tar} will not automatically label volumes which are +added later. To label subsequent volumes, specify +@option{--label=@var{archive-label}} again in conjunction with the +@option{--append}, @option{--update} or @option{--concatenate} operation. + +Notice that multi-volume support is a GNU extension and the archives +created in this mode should be read only using @GNUTAR{}. If you +absolutely have to process such archives using a third-party @command{tar} +implementation, read @ref{Split Recovery}. + +@node Tape Files +@subsection Tape Files +@cindex labeling archives +@opindex label +@UNREVISED + +To give the archive a name which will be recorded in it, use the +@option{--label=@var{volume-label}} (@option{-V @var{volume-label}}) +option. This will write a special block identifying +@var{volume-label} as the name of the archive to the front of the +archive which will be displayed when the archive is listed with +@option{--list}. If you are creating a multi-volume archive with +@option{--multi-volume} (@pxref{Using Multiple Tapes}), then the +volume label will have @samp{Volume @var{nnn}} appended to the name +you give, where @var{nnn} is the number of the volume of the archive. +If you use the @option{--label=@var{volume-label}} option when +reading an archive, it checks to make sure the label on the tape +matches the one you gave. @xref{label}. + +When @command{tar} writes an archive to tape, it creates a single +tape file. If multiple archives are written to the same tape, one +after the other, they each get written as separate tape files. When +extracting, it is necessary to position the tape at the right place +before running @command{tar}. To do this, use the @command{mt} command. +For more information on the @command{mt} command and on the organization +of tapes into a sequence of tape files, see @ref{mt}. + +People seem to often do: + +@smallexample +@kbd{--label="@var{some-prefix} `date +@var{some-format}`"} +@end smallexample + +or such, for pushing a common date in all volumes or an archive set. + +@node Tarcat +@subsection Concatenate Volumes into a Single Archive + +@pindex tarcat + Sometimes it is necessary to convert existing @GNUTAR{} multi-volume +archive to a single @command{tar} archive. Simply concatenating all +volumes into one will not work, since each volume carries an additional +information at the beginning. @GNUTAR{} is shipped with the shell +script @command{tarcat} designed for this purpose. + + The script takes a list of files comprising a multi-volume archive +and creates the resulting archive at the standard output. For example: + +@smallexample +@kbd{tarcat vol.1 vol.2 vol.3 | tar tf -} +@end smallexample + + The script implements a simple heuristics to determine the format of +the first volume file and to decide how to process the rest of the +files. However, it makes no attempt to verify whether the files are +given in order or even if they are valid @command{tar} archives. +It uses @command{dd} and does not filter its standard error, so you +will usually see lots of spurious messages. + +@FIXME{The script is not installed. Should we install it?} + +@node label +@section Including a Label in the Archive +@cindex Labeling an archive +@cindex Labels on the archive media +@cindex Labeling multi-volume archives + +@opindex label + To avoid problems caused by misplaced paper labels on the archive +media, you can include a @dfn{label} entry --- an archive member which +contains the name of the archive --- in the archive itself. Use the +@option{--label=@var{archive-label}} (@option{-V @var{archive-label}}) +option@footnote{Until version 1.10, that option was called +@option{--volume}, but is not available under that name anymore.} in +conjunction with the @option{--create} operation to include a label +entry in the archive as it is being created. + +@table @option +@item --label=@var{archive-label} +@itemx -V @var{archive-label} +Includes an @dfn{archive-label} at the beginning of the archive when +the archive is being created, when used in conjunction with the +@option{--create} operation. Checks to make sure the archive label +matches the one specified (when used in conjunction with any other +operation). +@end table -@item --ignore-umask -Set modes of extracted files to those recorded in the archive. -@xref{File Writing Options}. + If you create an archive using both +@option{--label=@var{archive-label}} (@option{-V @var{archive-label}}) +and @option{--multi-volume} (@option{-M}), each volume of the archive +will have an archive label of the form @samp{@var{archive-label} +Volume @var{n}}, where @var{n} is 1 for the first volume, 2 for the +next, and so on. @xref{Using Multiple Tapes}, for information on +creating multiple volume archives. + +@cindex Volume label, listing +@cindex Listing volume label + The volume label will be displayed by @option{--list} along with +the file contents. If verbose display is requested, it will also be +explicitly marked as in the example below: + +@smallexample +@group +$ @kbd{tar --verbose --list --file=iamanarchive} +V--------- 0/0 0 1992-03-07 12:01 iamalabel--Volume Header-- +-rw-r--r-- ringo/user 40 1990-05-21 13:30 iamafilename +@end group +@end smallexample + +@opindex test-label +@anchor{--test-label option} + However, @option{--list} option will cause listing entire +contents of the archive, which may be undesirable (for example, if the +archive is stored on a tape). You can request checking only the volume +label by specifying @option{--test-label} option. This option reads only the +first block of an archive, so it can be used with slow storage +devices. For example: + +@smallexample +@group +$ @kbd{tar --test-label --file=iamanarchive} +iamalabel +@end group +@end smallexample + + If @option{--test-label} is used with one or more command line +arguments, @command{tar} compares the volume label with each +argument. It exits with code 0 if a match is found, and with code 1 +otherwise@footnote{Note that @GNUTAR{} versions up to 1.23 indicated +mismatch with an exit code 2 and printed a spurious diagnostics on +stderr.}. No output is displayed, unless you also used the +@option{--verbose} option. For example: + +@smallexample +@group +$ @kbd{tar --test-label --file=iamanarchive 'iamalabel'} +@result{} 0 +$ @kbd{tar --test-label --file=iamanarchive 'alabel'} +@result{} 1 +@end group +@end smallexample + + When used with the @option{--verbose} option, @command{tar} +prints the actual volume label (if any), and a verbose diagnostics in +case of a mismatch: + +@smallexample +@group +$ @kbd{tar --test-label --verbose --file=iamanarchive 'iamalabel'} +iamalabel +@result{} 0 +$ @kbd{tar --test-label --verbose --file=iamanarchive 'alabel'} +iamalabel +tar: Archive label mismatch +@result{} 1 +@end group +@end smallexample + + If you request any operation, other than @option{--create}, along +with using @option{--label} option, @command{tar} will first check if +the archive label matches the one specified and will refuse to proceed +if it does not. Use this as a safety precaution to avoid accidentally +overwriting existing archives. For example, if you wish to add files +to @file{archive}, presumably labeled with string @samp{My volume}, +you will get: + +@smallexample +@group +$ @kbd{tar -rf archive --label 'My volume' .} +tar: Archive not labeled to match 'My volume' +@end group +@end smallexample -@item --ignore-zeros -Ignore end-of-archive entries. @xref{Archive Reading Options}. -<<< this should be changed to --ignore-end +@noindent +in case its label does not match. This will work even if +@file{archive} is not labeled at all. + + Similarly, @command{tar} will refuse to list or extract the +archive if its label doesn't match the @var{archive-label} +specified. In those cases, @var{archive-label} argument is interpreted +as a globbing-style pattern which must match the actual magnetic +volume label. @xref{exclude}, for a precise description of how match +is attempted@footnote{Previous versions of @command{tar} used full +regular expression matching, or before that, only exact string +matching, instead of wildcard matchers. We decided for the sake of +simplicity to use a uniform matching device through +@command{tar}.}. If the switch @option{--multi-volume} (@option{-M}) is being used, +the volume label matcher will also suffix @var{archive-label} by +@w{@samp{ Volume [1-9]*}} if the initial match fails, before giving +up. Since the volume numbering is automatically added in labels at +creation time, it sounded logical to equally help the user taking care +of it when the archive is being read. + + You can also use @option{--label} to get a common information on +all tapes of a series. For having this information different in each +series created through a single script used on a regular basis, just +manage to get some date string as part of the label. For example: + +@smallexample +@group +$ @kbd{tar -cM -f /dev/tape -V "Daily backup for `date +%Y-%m-%d`"} +$ @kbd{tar --create --file=/dev/tape --multi-volume \ + --label="Daily backup for `date +%Y-%m-%d`"} +@end group +@end smallexample + + Some more notes about volume labels: + +@itemize @bullet +@item Each label has its own date and time, which corresponds +to the time when @GNUTAR{} initially attempted to write it, +often soon after the operator launches @command{tar} or types the +carriage return telling that the next tape is ready. + +@item Comparing date labels to get an idea of tape throughput is +unreliable. It gives correct results only if the delays for rewinding +tapes and the operator switching them were negligible, which is +usually not the case. +@end itemize -@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. +@node verify +@section Verifying Data as It is Stored +@cindex Verifying a write operation +@cindex Double-checking a write operation -@item --incremental (-G) -@c <<>> +@table @option +@item -W +@itemx --verify +@opindex verify, short description +Attempt to verify the archive after writing. +@end table -@item --tape-length=@var{n} (-L) -@c <<>> -@c <<< this needs to be written into main body as well -ringo +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. -@item --info-script=@var{program-file} -Create a multi-volume archive via a script. @xref{Multi-Volume Archives}. +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. -@item --interactive -Ask for confirmation before performing any operation on a file or -archive member. +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. -@item --keep-old-files -Prevent overwriting during extraction. @xref{File Writing Options}. +@xopindex{verify, using with @option{--create}} +@xopindex{create, using with @option{--verify}} +To check for discrepancies in an archive immediately after it is +written, use the @option{--verify} (@option{-W}) option in conjunction with +the @option{--create} operation. When this option is +specified, @command{tar} checks archive members against their counterparts +in the file system, and reports discrepancies on the standard error. -@item --label=@var{archive-label} -Include an archive-label in the archive being created. @xref{Archive -Label}. +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. -@item --modification-time -Set the modification time of extracted files to the time they were -extracted. @xref{File Writing Options}. +One can explicitly compare an already made archive with the file +system by using the @option{--compare} (@option{--diff}, @option{-d}) +option, instead of using the more automatic @option{--verify} option. +@xref{compare}. + +Note that these two options have a slightly different intent. The +@option{--compare} option checks how identical are the logical contents of some +archive with what is on your disks, while the @option{--verify} option is +really for checking if the physical contents agree and if the recording +media itself is of dependable quality. So, for the @option{--verify} +operation, @command{tar} tries to defeat all in-memory cache pertaining to +the archive, while it lets the speed optimization undisturbed for the +@option{--compare} option. If you nevertheless use @option{--compare} for +media verification, you may have to defeat the in-memory cache yourself, +maybe by opening and reclosing the door latch of your recording unit, +forcing some doubt in your operating system about the fact this is really +the same volume as the one just written or read. + +The @option{--verify} option would not be necessary if drivers were indeed +able to detect dependably all write failures. This sometimes require many +magnetic heads, some able to read after the writes occurred. One would +not say that drivers unable to detect all cases are necessarily flawed, +as long as programming is concerned. + +The @option{--verify} (@option{-W}) option will not work in +conjunction with the @option{--multi-volume} (@option{-M}) option or +the @option{--append} (@option{-r}), @option{--update} (@option{-u}) +and @option{--delete} operations. @xref{Operations}, for more +information on these operations. + +Also, since @command{tar} normally strips leading @samp{/} from file +names (@pxref{absolute}), a command like @samp{tar --verify -cf +/tmp/foo.tar /etc} will work as desired only if the working directory is +@file{/}, as @command{tar} uses the archive's relative member names +(e.g., @file{etc/motd}) when verifying the archive. + +@node Write Protection +@section Write Protection -@item --multi-volume -Specify a multi-volume archive. @xref{Multi-Volume Archives}. +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.) -@item --newer=@var{date} -Limit the operation to files changed after the given date. -@xref{File Exclusion}. +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. -@item --newer-mtime=@var{date} -Limit the operation to files modified after the given date. @xref{File -Exclusion}. +@node Reliability and security +@chapter Reliability and Security -@item --old -Create an old format archive. @xref{Old Style File Information}. -@c <<< did we agree this should go away as a synonym? +The @command{tar} command reads and writes files as any other +application does, and is subject to the usual caveats about +reliability and security. This section contains some commonsense +advice on the topic. -@item --old-archive -Create an old format archive. @xref{Old Style File Information}. +@menu +* Reliability:: +* Security:: +@end menu -@item --one-file-system -Prevent @code{tar} from crossing file system boundaries when -archiving. @xref{File Exclusion}. +@node Reliability +@section Reliability -@item --portable -Create an old format archive. @xref{Old Style File Information}. -@c <<< was portability, may still need to be changed +Ideally, when @command{tar} is creating an archive, it reads from a +file system that is not being modified, and encounters no errors or +inconsistencies while reading and writing. If this is the case, the +archive should faithfully reflect what was read. Similarly, when +extracting from an archive, ideally @command{tar} ideally encounters +no errors and the extracted files faithfully reflect what was in the +archive. -@item --preserve-order -Help process large lists of file-names on machines with small amounts of -memory. @xref{Archive Reading Options}. - -@item --preserve-permission -Set modes of extracted files to those recorded in the archive. -@xref{File Writing Options}. - -@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}. +However, when reading or writing real-world file systems, several +things can go wrong; these include permissions problems, corruption of +data, and race conditions. -@item --same-order -Help process large lists of file-names on machines with small amounts of -memory. @xref{Archive Reading Options}. +@menu +* Permissions problems:: +* Data corruption and repair:: +* Race conditions:: +@end menu -@item --same-permission -Set the modes of extracted files to those recorded in the archive. -@xref{File Writing Options}. +@node Permissions problems +@subsection Permissions Problems + +If @command{tar} encounters errors while reading or writing files, it +normally reports an error and exits with nonzero status. The work it +does may therefore be incomplete. For example, when creating an +archive, if @command{tar} cannot read a file then it cannot copy the +file into the archive. + +@node Data corruption and repair +@subsection Data Corruption and Repair + +If an archive becomes corrupted by an I/O error, this may corrupt the +data in an extracted file. Worse, it may corrupt the file's metadata, +which may cause later parts of the archive to become misinterpreted. +An tar-format archive contains a checksum that most likely will detect +errors in the metadata, but it will not detect errors in the data. + +If data corruption is a concern, you can compute and check your own +checksums of an archive by using other programs, such as +@command{cksum}. + +When attempting to recover from a read error or data corruption in an +archive, you may need to skip past the questionable data and read the +rest of the archive. This requires some expertise in the archive +format and in other software tools. + +@node Race conditions +@subsection Race conditions + +If some other process is modifying the file system while @command{tar} +is reading or writing files, the result may well be inconsistent due +to race conditions. For example, if another process creates some +files in a directory while @command{tar} is creating an archive +containing the directory's files, @command{tar} may see some of the +files but not others, or it may see a file that is in the process of +being created. The resulting archive may not be a snapshot of the +file system at any point in time. If an application such as a +database system depends on an accurate snapshot, restoring from the +@command{tar} archive of a live file system may therefore break that +consistency and may break the application. The simplest way to avoid +the consistency issues is to avoid making other changes to the file +system while tar is reading it or writing it. + +When creating an archive, several options are available to avoid race +conditions. Some hosts have a way of snapshotting a file system, or +of temporarily suspending all changes to a file system, by (say) +suspending the only virtual machine that can modify a file system; if +you use these facilities and have @command{tar -c} read from a +snapshot when creating an archive, you can avoid inconsistency +problems. More drastically, before starting @command{tar} you could +suspend or shut down all processes other than @command{tar} that have +access to the file system, or you could unmount the file system and +then mount it read-only. + +When extracting from an archive, one approach to avoid race conditions +is to create a directory that no other process can write to, and +extract into that. + +@node Security +@section Security + +In some cases @command{tar} may be used in an adversarial situation, +where an untrusted user is attempting to gain information about or +modify otherwise-inaccessible files. Dealing with untrusted data +(that is, data generated by an untrusted user) typically requires +extra care, because even the smallest mistake in the use of +@command{tar} is more likely to be exploited by an adversary than by a +race condition. -@item --sparse -Archive sparse files sparsely. @xref{Sparse Files}. +@menu +* Privacy:: +* Integrity:: +* Live untrusted data:: +* Security rules of thumb:: +@end menu -@item --starting-file=@var{file-name} -Begin reading in the middle of an archive. @xref{Scarce Disk Space}. +@node Privacy +@subsection Privacy + +Standard privacy concerns apply when using @command{tar}. For +example, suppose you are archiving your home directory into a file +@file{/archive/myhome.tar}. Any secret information in your home +directory, such as your SSH secret keys, are copied faithfully into +the archive. Therefore, if your home directory contains any file that +should not be read by some other user, the archive itself should be +not be readable by that user. And even if the archive's data are +inaccessible to untrusted users, its metadata (such as size or +last-modified date) may reveal some information about your home +directory; if the metadata are intended to be private, the archive's +parent directory should also be inaccessible to untrusted users. + +One precaution is to create @file{/archive} so that it is not +accessible to any user, unless that user also has permission to access +all the files in your home directory. + +Similarly, when extracting from an archive, take care that the +permissions of the extracted files are not more generous than what you +want. Even if the archive itself is readable only to you, files +extracted from it have their own permissions that may differ. + +@node Integrity +@subsection Integrity + +When creating archives, take care that they are not writable by a +untrusted user; otherwise, that user could modify the archive, and +when you later extract from the archive you will get incorrect data. + +When @command{tar} extracts from an archive, by default it writes into +files relative to the working directory. If the archive was generated +by an untrusted user, that user therefore can write into any file +under the working directory. If the working directory contains a +symbolic link to another directory, the untrusted user can also write +into any file under the referenced directory. When extracting from an +untrusted archive, it is therefore good practice to create an empty +directory and run @command{tar} in that directory. + +When extracting from two or more untrusted archives, each one should +be extracted independently, into different empty directories. +Otherwise, the first archive could create a symbolic link into an area +outside the working directory, and the second one could follow the +link and overwrite data that is not under the working directory. For +example, when restoring from a series of incremental dumps, the +archives should have been created by a trusted process, as otherwise +the incremental restores might alter data outside the working +directory. + +If you use the @option{--absolute-names} (@option{-P}) option when +extracting, @command{tar} respects any file names in the archive, even +file names that begin with @file{/} or contain @file{..}. As this +lets the archive overwrite any file in your system that you can write, +the @option{--absolute-names} (@option{-P}) option should be used only +for trusted archives. + +Conversely, with the @option{--keep-old-files} (@option{-k}) and +@option{--skip-old-files} options, @command{tar} refuses to replace +existing files when extracting. The difference between the two +options is that the former treats existing files as errors whereas the +latter just silently ignores them. + +Finally, with the @option{--no-overwrite-dir} option, @command{tar} +refuses to replace the permissions or ownership of already-existing +directories. These options may help when extracting from untrusted +archives. + +@node Live untrusted data +@subsection Dealing with Live Untrusted Data + +Extra care is required when creating from or extracting into a file +system that is accessible to untrusted users. For example, superusers +who invoke @command{tar} must be wary about its actions being hijacked +by an adversary who is reading or writing the file system at the same +time that @command{tar} is operating. + +When creating an archive from a live file system, @command{tar} is +vulnerable to denial-of-service attacks. For example, an adversarial +user could create the illusion of an indefinitely-deep directory +hierarchy @file{d/e/f/g/...} by creating directories one step ahead of +@command{tar}, or the illusion of an indefinitely-long file by +creating a sparse file but arranging for blocks to be allocated just +before @command{tar} reads them. There is no easy way for +@command{tar} to distinguish these scenarios from legitimate uses, so +you may need to monitor @command{tar}, just as you'd need to monitor +any other system service, to detect such attacks. + +While a superuser is extracting from an archive into a live file +system, an untrusted user might replace a directory with a symbolic +link, in hopes that @command{tar} will follow the symbolic link and +extract data into files that the untrusted user does not have access +to. Even if the archive was generated by the superuser, it may +contain a file such as @file{d/etc/passwd} that the untrusted user +earlier created in order to break in; if the untrusted user replaces +the directory @file{d/etc} with a symbolic link to @file{/etc} while +@command{tar} is running, @command{tar} will overwrite +@file{/etc/passwd}. This attack can be prevented by extracting into a +directory that is inaccessible to untrusted users. + +Similar attacks via symbolic links are also possible when creating an +archive, if the untrusted user can modify an ancestor of a top-level +argument of @command{tar}. For example, an untrusted user that can +modify @file{/home/eve} can hijack a running instance of @samp{tar -cf +- /home/eve/Documents/yesterday} by replacing +@file{/home/eve/Documents} with a symbolic link to some other +location. Attacks like these can be prevented by making sure that +untrusted users cannot modify any files that are top-level arguments +to @command{tar}, or any ancestor directories of these files. + +@node Security rules of thumb +@subsection Security Rules of Thumb + +This section briefly summarizes rules of thumb for avoiding security +pitfalls. + +@itemize @bullet + +@item +Protect archives at least as much as you protect any of the files +being archived. + +@item +Extract from an untrusted archive only into an otherwise-empty +directory. This directory and its parent should be accessible only to +trusted users. For example: -@item --to-stdout -Write files to the standard output. @xref{File Writing Options}. +@example +@group +$ @kbd{chmod go-rwx .} +$ @kbd{mkdir -m go-rwx dir} +$ @kbd{cd dir} +$ @kbd{tar -xvf /archives/got-it-off-the-net.tar.gz} +@end group +@end example -@item --uncompress -Specifdo a compressed archive. @xref{Compressed Archives}. +As a corollary, do not do an incremental restore from an untrusted archive. -@item -V @var{archive-label} -Include an archive-label in the archive being created. @xref{Archive -Label}. -@c was --volume +@item +Do not let untrusted users access files extracted from untrusted +archives without checking first for problems such as setuid programs. -@item --verbose -Print the names of files or archive members as they are being -operated on. @xref{Additional Information}. +@item +Do not let untrusted users modify directories that are ancestors of +top-level arguments of @command{tar}. For example, while you are +executing @samp{tar -cf /archive/u-home.tar /u/home}, do not let an +untrusted user modify @file{/}, @file{/archive}, or @file{/u}. -@item --verify -Check for discrepancies in the archive immediately after it is -written. @xref{Write Verification}. +@item +Pay attention to the diagnostics and exit status of @command{tar}. -@item -B -Read an archive with a smaller than specified block size or which -contains incomplete blocks. @xref{Archive Reading Options}). +@item +When archiving live file systems, monitor running instances of +@command{tar} to detect denial-of-service attacks. -@item -K @var{file-name} -Begin reading in the middle of an archive. @xref{Scarce Disk Space}. +@item +Avoid unusual options such as @option{--absolute-names} (@option{-P}), +@option{--dereference} (@option{-h}), @option{--overwrite}, +@option{--recursive-unlink}, and @option{--remove-files} unless you +understand their security implications. -@item -M -Specify a multi-volume archive. @xref{Multi-Volume Archives}. +@end itemize -@item -N @var{date} -Limit operation to files changed after the given date. @xref{File Exclusion}. +@node Changes +@appendix Changes -@item -O -Write files to the standard output. @xref{File Writing Options}. +This appendix lists some important user-visible changes between +version @GNUTAR{} @value{VERSION} and previous versions. An up-to-date +version of this document is available at +@uref{http://www.gnu.org/@/software/@/tar/manual/changes.html,the +@GNUTAR{} documentation page}. -@c <<<<- P is absolute paths, add when resolved. -ringo>>> +@table @asis +@item Use of globbing patterns when listing and extracting. -@item -R -Print the record number where a message is generated. -@xref{Additional Information}. +Previous versions of GNU tar assumed shell-style globbing when +extracting from or listing an archive. For example: -@item -S -Archive sparse files sparsely. @xref{Sparse Files}. +@smallexample +$ @kbd{tar xf foo.tar '*.c'} +@end smallexample -@item -T @var{file} -Read file-name arguments from a file on the file system. -@xref{File Name Lists}. +would extract all files whose names end in @samp{.c}. This behavior +was not documented and was incompatible with traditional tar +implementations. Therefore, starting from version 1.15.91, GNU tar +no longer uses globbing by default. For example, the above invocation +is now interpreted as a request to extract from the archive the file +named @file{*.c}. -@item -W -Check for discrepancies in the archive immediately after it is -written. @xref{Write Verification}. +To facilitate transition to the new behavior for those users who got +used to the previous incorrect one, @command{tar} will print a warning +if it finds out that a requested member was not found in the archive +and its name looks like a globbing pattern. For example: -@item -Z -Specify a compressed archive. @xref{Compressed Archives}. +@smallexample +$ @kbd{tar xf foo.tar '*.c'} +tar: Pattern matching characters used in file names. Please, +tar: use --wildcards to enable pattern matching, or --no-wildcards to +tar: suppress this warning. +tar: *.c: Not found in archive +tar: Error exit delayed from previous errors +@end smallexample -@item -b @var{number} -Specify the blocking factor of an archive. @xref{Blocking Factor}. +To treat member names as globbing patterns, use the @option{--wildcards} option. +If you want to tar to mimic the behavior of versions prior to 1.15.91, +add this option to your @env{TAR_OPTIONS} variable. -@item -f @var{archive-name} -Name the archive. @xref{Archive Name}). +@xref{wildcards}, for the detailed discussion of the use of globbing +patterns by @GNUTAR{}. -@item -h -Treat a symbolic link as an alternate name for the file the link -points to. @xref{Symbolic Links}. +@item Use of short option @option{-o}. -@item -i -Ignore end-of-archive entries. @xref{Archive Reading Options}. +Earlier versions of @GNUTAR{} understood @option{-o} command line +option as a synonym for @option{--old-archive}. -@item -k -Prevent overwriting during extraction. @xref{File Writing Options}. +@GNUTAR{} starting from version 1.13.90 understands this option as +a synonym for @option{--no-same-owner}. This is compatible with +UNIX98 @command{tar} implementations. -@item -l -Prevent @code{tar} from crossing file system boundaries when -archiving. @xref{File Exclusion}. +However, to facilitate transition, @option{-o} option retains its +old semantics when it is used with one of archive-creation commands. +Users are encouraged to use @option{--format=oldgnu} instead. -@item -m -Set the modification time of extracted files to the time they were -extracted. @xref{File Writing Options}. +It is especially important, since versions of @acronym{GNU} Automake +up to and including 1.8.4 invoke tar with this option to produce +distribution tarballs. @xref{Formats,v7}, for the detailed discussion +of this issue and its implications. -@item -o -Create an old format archive. @xref{Old Style File Information}. +@xref{Options, tar-formats, Changing Automake's Behavior, +automake, GNU Automake}, for a description on how to use various +archive formats with @command{automake}. -@item -p -Set the modes of extracted files to those recorded in the archive. -@xref{File Writing Options}. +Future versions of @GNUTAR{} will understand @option{-o} only as a +synonym for @option{--no-same-owner}. -@item -s -Help process large lists of file-names on machines with small amounts of -memory. @xref{Archive Reading Options}. +@item Use of short option @option{-l} -@item -v -Print the names of files or archive members they are being operated -on. @xref{Additional Information}. +Earlier versions of @GNUTAR{} understood @option{-l} option as a +synonym for @option{--one-file-system}. Since such usage contradicted +to UNIX98 specification and harmed compatibility with other +implementations, it was declared deprecated in version 1.14. However, +to facilitate transition to its new semantics, it was supported by +versions 1.15 and 1.15.90. The present use of @option{-l} as a short +variant of @option{--check-links} was introduced in version 1.15.91. -@item -w -@c <<>> +@item Use of options @option{--portability} and @option{--old-archive} -@item -z -Specify a compressed archive. @xref{Compressed Archives}. +These options are deprecated. Please use @option{--format=v7} instead. -@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. +@item Use of option @option{--posix} -@item -C @file{directory} -Change the working directory. @xref{Changing Working Directory}. +This option is deprecated. Please use @option{--format=posix} instead. +@end table -@item -F @var{program-file} -Create a multi-volume archive via a script. @xref{Multi-Volume Archives}. +@node Configuring Help Summary +@appendix Configuring Help Summary + +Running @kbd{tar --help} displays the short @command{tar} option +summary (@pxref{help}). This summary is organized by @dfn{groups} of +semantically close options. The options within each group are printed +in the following order: a short option, eventually followed by a list +of corresponding long option names, followed by a short description of +the option. For example, here is an excerpt from the actual @kbd{tar +--help} output: + +@verbatim + Main operation mode: + + -A, --catenate, --concatenate append tar files to an archive + -c, --create create a new archive + -d, --diff, --compare find differences between archive and + file system + --delete delete from the archive +@end verbatim + +@vrindex ARGP_HELP_FMT, environment variable +The exact visual representation of the help output is configurable via +@env{ARGP_HELP_FMT} environment variable. The value of this variable +is a comma-separated list of @dfn{format variable} assignments. There +are two kinds of format variables. An @dfn{offset variable} keeps the +offset of some part of help output text from the leftmost column on +the screen. A @dfn{boolean} variable is a flag that toggles some +output feature on or off. Depending on the type of the corresponding +variable, there are two kinds of assignments: + +@table @asis +@item Offset assignment + +The assignment to an offset variable has the following syntax: + +@smallexample +@var{variable}=@var{value} +@end smallexample -@item -X @file{file} -Exclude files which match any of the regular expressions listed in -the file @file{file}. @xref{File Exclusion}. +@noindent +where @var{variable} is the variable name, and @var{value} is a +numeric value to be assigned to the variable. + +@item Boolean assignment + +To assign @code{true} value to a variable, simply put this variable name. To +assign @code{false} value, prefix the variable name with @samp{no-}. For +example: + +@smallexample +@group +# Assign @code{true} value: +dup-args +# Assign @code{false} value: +no-dup-args +@end group +@end smallexample @end table -@node Data Format Details, Concept Index, Quick Reference, Top -@appendix Details of the Archive Data Format +Following variables are declared: -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. +@deftypevr {Help Output} boolean dup-args +If true, arguments for an option are shown with both short and long +options, even when a given option has both forms, for example: -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. +@smallexample + -f ARCHIVE, --file=ARCHIVE use archive file or device ARCHIVE +@end smallexample -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. +If false, then if an option has both short and long forms, the +argument is only shown with the long one, for example: -@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 +@smallexample + -f, --file=ARCHIVE use archive file or device ARCHIVE +@end smallexample -@node Header Data, Header Fields, Data Format Details, Data Format Details -@appendixsec The Distribution of Data in the Header +@noindent +and a message indicating that the argument is applicable to both +forms is printed below the options. This message can be disabled +using @code{dup-args-note} (see below). -The header record is defined in C as follows: -@c I am taking the following code on faith. +The default is false. +@end deftypevr -@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 +@deftypevr {Help Output} boolean dup-args-note +If this variable is true, which is the default, the following notice +is displayed at the end of the help output: +@quotation +Mandatory or optional arguments to long options are also mandatory or +optional for any corresponding short options. +@end quotation -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. - -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. - -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. - -The @code{longnames} field supports a feature that is not yet -implemented. This field should be empty. - -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. - -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. - -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}. +Setting @code{no-dup-args-note} inhibits this message. Normally, only one of +variables @code{dup-args} or @code{dup-args-note} should be set. +@end deftypevr + +@deftypevr {Help Output} offset short-opt-col +Column in which short options start. Default is 2. + +@smallexample +@group +$ @kbd{tar --help|grep ARCHIVE} + -f, --file=ARCHIVE use archive file or device ARCHIVE +$ @kbd{ARGP_HELP_FMT=short-opt-col=6 tar --help|grep ARCHIVE} + -f, --file=ARCHIVE use archive file or device ARCHIVE +@end group +@end smallexample +@end deftypevr + +@deftypevr {Help Output} offset long-opt-col +Column in which long options start. Default is 6. For example: + +@smallexample +@group +$ @kbd{tar --help|grep ARCHIVE} + -f, --file=ARCHIVE use archive file or device ARCHIVE +$ @kbd{ARGP_HELP_FMT=long-opt-col=16 tar --help|grep ARCHIVE} + -f, --file=ARCHIVE use archive file or device ARCHIVE +@end group +@end smallexample +@end deftypevr + +@deftypevr {Help Output} offset doc-opt-col +Column in which @dfn{doc options} start. A doc option isn't actually +an option, but rather an arbitrary piece of documentation that is +displayed in much the same manner as the options. For example, in +the description of @option{--format} option: + +@smallexample +@group + -H, --format=FORMAT create archive of the given format. + + FORMAT is one of the following: + + gnu GNU tar 1.13.x format + oldgnu GNU format as per tar <= 1.12 + pax POSIX 1003.1-2001 (pax) format + posix same as pax + ustar POSIX 1003.1-1988 (ustar) format + v7 old V7 tar format +@end group +@end smallexample -@menu -* File Types:: File Types -* GNU File Types:: Additional File Types Supported by GNU -@end menu +@noindent +the format names are doc options. Thus, if you set +@kbd{ARGP_HELP_FMT=doc-opt-col=6} the above part of the help output +will look as follows: + +@smallexample +@group + -H, --format=FORMAT create archive of the given format. + + FORMAT is one of the following: + + gnu GNU tar 1.13.x format + oldgnu GNU format as per tar <= 1.12 + pax POSIX 1003.1-2001 (pax) format + posix same as pax + ustar POSIX 1003.1-1988 (ustar) format + v7 old V7 tar format +@end group +@end smallexample +@end deftypevr + +@deftypevr {Help Output} offset opt-doc-col +Column in which option description starts. Default is 29. + +@smallexample +@group +$ @kbd{tar --help|grep ARCHIVE} + -f, --file=ARCHIVE use archive file or device ARCHIVE +$ @kbd{ARGP_HELP_FMT=opt-doc-col=19 tar --help|grep ARCHIVE} + -f, --file=ARCHIVE use archive file or device ARCHIVE +$ @kbd{ARGP_HELP_FMT=opt-doc-col=9 tar --help|grep ARCHIVE} + -f, --file=ARCHIVE + use archive file or device ARCHIVE +@end group +@end smallexample -@node File Types, GNU File Types, Header Fields, Header Fields -@appendixsubsec File Types +@noindent +Notice, that the description starts on a separate line if +@code{opt-doc-col} value is too small. +@end deftypevr + +@deftypevr {Help Output} offset header-col +Column in which @dfn{group headers} are printed. A group header is a +descriptive text preceding an option group. For example, in the +following text: + +@verbatim + Main operation mode: + + -A, --catenate, --concatenate append tar files to + an archive + -c, --create create a new archive +@end verbatim +@noindent +@samp{Main operation mode:} is the group header. -The following flags are used to describe file types: +The default value is 1. +@end deftypevr -@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. - -@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}. -@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. - -@node GNU File Types, , File Types, Header Fields -@appendixsubsec Additional File Types Supported by GNU - -GNU @code{tar} uses additional file types to describe new types of -files in an archive. These are listed below. +@deftypevr {Help Output} offset usage-indent +Indentation of wrapped usage lines. Affects @option{--usage} +output. Default is 12. +@end deftypevr -@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. - -@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. +@deftypevr {Help Output} offset rmargin +Right margin of the text output. Used for wrapping. +@end deftypevr -@item LF_SPARSE -@itemx 'S' -Indicates a sparse file. @xref{Sparse Files}. @xref{Sparse File -Handling}. +@node Fixing Snapshot Files +@appendix Fixing Snapshot Files +@include tar-snapshot-edit.texi -@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 +@node Tar Internals +@appendix Tar Internals +@include intern.texi -@node Sparse File Handling, , Header Fields, Data Format Details -@appendixsec Fields to Handle Sparse Files +@node Genfile +@appendix Genfile +@include genfile.texi -The following header information was added to deal with sparse files -(@pxref{Sparse Files}): +@node Free Software Needs Free Documentation +@appendix Free Software Needs Free Documentation +@include freemanuals.texi -@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. +@node GNU Free Documentation License +@appendix GNU Free Documentation License -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. +@include fdl.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 Index of Command Line Options +@appendix Index of Command Line Options -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. +This appendix contains an index of all @GNUTAR{} long command line +options. The options are listed without the preceding double-dash. +For a cross-reference of short command line options, see +@ref{Short Option Summary}. -@c so is @code{extended_header} the right way to write this? +@printindex op -@node Concept Index, , Data Format Details, Top -@unnumbered Concept Index +@node Index +@appendix Index @printindex cp @@ -3393,4 +12580,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: