From: François Pinard Date: Wed, 16 Nov 1994 02:51:32 +0000 (+0000) Subject: Initial revision X-Git-Url: https://git.brokenzipper.com/gitweb?a=commitdiff_plain;h=7ac3cfedacb2f9a113fd80fd57443c703e3567e9;p=chaz%2Ftar Initial revision --- diff --git a/doc/tar.texi b/doc/tar.texi new file mode 100644 index 0000000..72e1551 --- /dev/null +++ b/doc/tar.texi @@ -0,0 +1,3961 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename tar.info +@settitle The Tar Manual: DRAFT +@setchapternewpage odd +@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 Search for comments marked with !! or <<< (or >>>) + +@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).>>> + +@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 <<< @code{tar} is always lower case, in bold. >>> + +@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 + +@c <<< (don't forget to comment these out in final draft) -ringo + +@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 + +@iftex +@c finalout +@end iftex + +@ifinfo +This file documents @code{tar}, a utility used to store, backup, and +transport files. + +Copyright (C) 1992 Free Software Foundation, Inc. DRAFT! +@c Need to put distribution information here when ready. +@end ifinfo + +@c !!set edition number and date here +@titlepage +@title @code{tar} +@subtitle The GNU Tape Archiver +@subtitle Edition 0.01, for @code{tar} Version 1.10 +@subtitle @today{} +@c remove preceding today line when ready +@sp 1 +@subtitle DRAFT +@c subtitle insert month here when ready + +@author Amy Gorin and Jay Fenlason +@c <<>>> + +@page +@vskip 0pt plus 1filll +Copyright @copyright{} 1992 Free Software Foundation, Inc. + +@sp 2 +This draft is not yet ready for distribution. +@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. + +@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 + +@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 + +@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 file's contents as well as a listing of those +files' characteristics. You can also use @code{tar} to read, add to, +or manipulate already existing archives. Because an archive created +by @code{tar} is capable of preserving file information and directory +structure, @code{tar} is ideal for performing full and incremental +backups, as well as for transferring groups of files between disks and +over networks. + +Despite the utility's name, which comes from the words @samp{T(ape)} +@samp{AR(chiver)}, @code{tar}'s output can be directed to any +available device. For instance, @code{tar} archives can be stored in +a file or sent to another program via a pipe. + +@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 + +@node Invoking @code{tar}, Tutorial, Introduction, Top +@chapter How To Invoke @code{tar} + +You can use @code{tar} to store files in an archive, to extract them +from an archive, and to do other types of archive manipulation. The +primary argument to @code{tar}, which is called the @dfn{operation}, +specifies which action to take. The other arguments to @code{tar} are +either @dfn{options}, which change the way @code{tar} performs an +operation, or @dfn{file-names}, which specify the files @code{tar} is +to act on. The typical @code{tar} command line syntax is: + +@example +@code{tar} @var{operation} [@var{options}...] [@var{file-names}...] +@end example + +Note: You can actually type in arguments in any order. In this manual +the operation is always first, the options second and the file-name +arguments last, to make examples easier to understand. + +@menu +* Argument Functions:: The Functions of Arguments +* Argument Form:: The Forms of Arguments +* Old Syntax for Commands:: An Old, but Still Supported, Syntax + for @code{tar} Commands +@end menu + +@node Argument Functions, Argument Form, Invoking @code{tar}, Invoking @code{tar} +@section The Functions of Arguments + +The primary argument to @code{tar} is the @dfn{operation}, which +specifies what @code{tar} does. @code{tar} can be used to: + +@itemize +@item +Add files to an existing archive (@samp{+add-file}, @samp+{append} or +@samp{-r}) + +@item +Compare files in an archive with files in the file system +(@samp{+compare}, @samp{+diff} or @samp{-d}) +@c !!! is diff still working?? --- yes -ringo + +@item +Add archives to another archive (@samp{+add-archive}, @samp{+catenate} +or @samp{-A}) +@c was +concatenate. -ringo + +@item +Create an archive (@samp{+create} or @samp{-c}) + +@item +Delete files from an archive (@samp{+delete}) +@c -D should have been removed -ringo + +@item +Extract files from an archive (@samp{+extract}, @samp{+get} or @samp{-x}) + +@item +List the files in an archive (@samp{+list} or @samp{-t}) + +@item +Update an archive by appending newer versions of already stored files +(@samp{+update} or @samp{-u}) +@end itemize + +@xref{Reading and Writing}, for more information about these +operations. + +@dfn{Option} arguments to @code{tar} change details of the operation, +such as archive format, archive name, or level of user interaction. +You can specify more than one option. All options are optional. + +@dfn{File-name} arguments specify which files (including directory +files) to archive, extract, delete or otherwise operate on. + +If you don't use any file-name arguments, @samp{+add-file}, +@samp{+update} and @samp{+delete} will do nothing. The other +operations of @code{tar} will act on defaults. + +When you use a file-name argument to specify a directory file, +@code{tar} acts on all the files in that directory, including +sub-directories. + +@node Argument Form, Old Syntax for Commands, Argument Functions, Invoking @code{tar} +@section The Forms of Arguments + +Most operations of @code{tar} have a single letter form (a single +letter preceded by a @samp{-}), and at least one mnemonic form (a +word or abbreviation preceded by a @samp{+}). The forms are +identical in function. For example, you can use either @samp{tar -t} +or @samp{tar +list} to list the contents of an archive + +Options, like operations, have both single letter and mnemonic forms. +Options, however, may also incorporate an argument. Single letter +options are separated from their arguments by a space. Mnemonic +options are separated from their arguments by an @samp{=} sign. For +example, to create an an archive file named @file{george}, use either +@samp{tar +create +file=george} or @samp{tar +create -f george}. Both +@samp{+file=@var{archive-name}} and @samp{-f @var{archive-name}} +denote the option to give the archive a non-default name, which in the +example is @samp{george}. + +You can mix single letter and mnemonic forms in the same command. You +could type the above example as @samp{tar -c +file=george} or +@samp{tar +create -f george}. However, @code{tar} operations and +options are case sensitive. You would not type the above example as +@samp{tar -C +file=george}, because @samp{-C} is an option that causes +@code{tar} to change directories, not an operation that creates an +archive. + +File-name arguments are the names of files (including directories). +These names can be specified on the command line or read from a text +file in the file system (using the @samp{+files-from} option). Files +stored in an archive are called @dfn{archive members}. The operations +@samp{+delete}, @samp{+extract}, @samp{+list}, @samp{+compare} and +@samp{+update} take the names of archive members as file-name +arguments. The other operations take the names of files in the file +system. + +@code{tar} interprets relative file names as being relative to the +working directory. @code{tar} will make all file names relative (by +removing leading @samp{/}s when archiving or restoring files), unless +you specify otherwise (using the @samp{+absolute-paths} option). +@xref{File Name Interpretation}, for more information about +@samp{+absolute-paths}. +@c >>> yet another node name that is probably wrong. + +@node Old Syntax for Commands, , Argument Form, Invoking @code{tar} +@section An Old, but Still Supported, Syntax for @code{tar} Commands + +For historical reasons, GNU @code{tar} also accepts a syntax for +commands which splits options that include arguments into two parts. +That syntax is of the form: + +@example +@code{tar} @var{operation}[@var{option-letters}...] [@var{option-arguments}...] [@var{file-names}...]@refill +@end example + +@noindent +where arguments to the options appear in the same order as the letters +to which they correspond, and the operation and all the option letters +appear as a single argument, without separating spaces. + +This command syntax is useful because it lets you type the single +letter forms of the operation and options as a single argument to +@code{tar}, without writing preceding @samp{-}s or inserting spaces +between letters. @samp{tar cv} or @samp{tar -cv} are equivalent to +@samp{tar -c -v}. + +This old style syntax makes it difficult to match option letters with +their corresponding arguments, and is often confusing. In the command +@samp{tar cvbf 20 /dev/rmt0}, for example, @samp{20} is the argument +for @samp{-b}, @samp{/dev/rmt0} is the argument for @samp{-f}, and +@samp{-v} does not have a corresponding argument. The modern +syntax---@samp{tar -c -v -b 20 -f /dev/rmt0}---is clearer. + +@node Tutorial, Wizardry, Invoking @code{tar}, Top +@chapter Getting Started With @code{tar} + +This chapter guides you through some basic examples of @code{tar} +operations. In the examples, the lines you should type are preceded +by a @samp{%}, which is a typical shell prompt. We use mnemonic forms +of operations and options in the examples, and in discussions in the +text, but short forms produce the same result. + +@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 + +@node Creating Archives, Listing Archive Contents, Tutorial, Tutorial +@section Creating Archives + +To create a new archive, use @code{tar +create} (or @code{tar -c}). +You can use options to specify the name and format of the archive (as +well as other characteristics), and you can use file-name arguments to +specify which files to put in the archive. If you don't use any +options or file-name arguments, @code{tar} will use default values. +@xref{Creating Example}, for more information about the @samp{+create} +operation. + +@menu +* Creating Example:: Creating Archives of Files +* Subdirectory:: Creating an Archive of a Subdirectory +@end menu + +@node Creating Example, Subdirectory, Creating Archives, Creating Archives +@subsection Creating Archives of Files + +This example shows you how to create an archive file in the working +directory containing other files in the working directory. The three +files you archive in this example are called @file{blues}, +@file{folk}, and @file{jazz}. The archive file is called +@file{records}. While the archive in this example is written to the +file system, it could also be written to any other device. + +(If you want to follow along with this and future examples, create a +directory called @file{practice} containing files called @file{blues}, +@file{folk} and @file{jazz}. To create the directory, type +@samp{mkdir practice} at the system prompt. It will probably be +easiest to create the files using a text editor, such as Emacs.) + +First, change into the directory containing the files you want to +archive: + +@example +% cd practice +@end example + +@noindent +@file{~/practice} is now your working directory. + +Then, check that the files to be archived do in fact exist in the +working directory, and make sure there isn't already a file in the +working directory with the archive name you intend to use. If you +specify an archive file name that is already in use, @code{tar} will +overwrite the old file and its contents will be lost. + +To list the names of files in the working directory, type: + +@example +% ls +@end example + +The system responds: + +@example +blues folk jazz +% +@end example + +@noindent +Then, +@itemize @bullet +@item +Create a new archive (@samp{tar -c} or @samp{tar +create}) + +@item +Explicitly name the archive file being created (@samp{-f +@var{archive-name}} or @samp{+file=@var{archive-name}}). If you don't +use this option @code{tar} will write the archive to the default +storage device, which varies from system to system. +@c <<< this syntax may change. OK now---check before printing -ringo + +@code{tar} interprets archive file names relative to the working +directory. Make sure you have write access to the working directory +before using @code{tar}. + +@item +Specify which files to put into the archive (@code{tar} interprets +file names relative to the working directory). If you don't use any +@var{file-name} arguments, @code{tar} will archive everything in the +working directory. +@end itemize + +@noindent +Type: +@example +% tar +create +file=records blues folk jazz +@end example + +@noindent +If you now list the contents of the working directory (@samp{ls}), you +will find the archive file listed as well as the files you saw +previously. + +@example +% ls +blues folk jazz records +% +@end example + +@menu +* Listing Files:: Listing files in an archive +* Verbose:: Using @code{tar} in Verbose Mode +@end menu + +@node Listing Files, Verbose, Creating Example, Creating Example +@subsubsection Listing files in an archive + +You can list the contents of an archive with another operation of +@code{tar}---@samp{+list} or @samp{-l}. To list the contents of the +archive you just created, type: + +@example +% tar +list +file=records +@end example + +@noindent +@code{tar} will respond: + +@example +blues folk jazz +@end example + +@xref{Listing Archive Contents}, for a more detailed tutorial of the +@samp{+list} operation. @xref{Listing Contents}, for more information +about the @samp{+list} operation. + +@node Verbose, , Listing Files, Creating Example +@subsubsection Using @code{tar} in Verbose Mode + +If you include the @samp{+verbose} or @samp{-v} option on the command +line, @code{tar} will list the files it is acting on as it is working. +In verbose mode, the creation example above would appear as: +@cindex Verbose mode example +@findex -v (verbose mode example) + +@example +% tar +create +file=records +verbose blues folk jazz +blues +folk +jazz +@end example + +@noindent +The first line is the command typed in by the user. The remaining +lines are generated by @code{tar}. In the following examples we +usually use verbose mode, though it is almost never required. + +@node Subdirectory, Changing, Creating Example, Creating Archives +@subsection Creating an Archive of a Subdirectory + +You can store a directory in an archive by using the directory name as +a file-name argument to @code{tar}. When you specify a directory +file, @code{tar} archives the directory file and all the files it +contains. The names of the directory and the files it contains are +stored in the archive relative to the current working directory---when +the directory is extracted they will be written into the file system +relative to the working directory at that time. +@c <<< add an xref to +absolute-paths -ringo + +To archive a directory, first move to its superior directory. If you +have been following the tutorial, you should type: + +@example +% cd .. +% +@end example + +Once in the superior directory, specify the subdirectory using a +file-name argument. To store the directory file @file{~/practice} in +the archive file @file{music}, type: + +@example +% tar +create +verbose +file=music practice +@end example + +@noindent +@code{tar} should respond: + +@example +practice/ +practice/blues +practice/folk +practice/jazz +practice/records +@end example + +Note that @file{~/practice/records}, another archive file, has +itself been archived. @code{tar} will accept any file as a file to be +archived, even an archive file. + +@c >>> symbolic links and changing directories are now in main body, not in +@c >>> tutorial. -ringo + +@node Extracting Files +@section Extracting Files from an Archive + +Creating an archive is only half the job---there would be no point in +storing files in an archive if you couldn't retrieve them. To extract +files from an archive, use the @samp{+extract} or @samp{-x} operation. + +To extract specific files, use their names as file-name arguments. If +you use a directory name as a file-name argument, @code{tar} extracts +all the files (including subdirectories) in that directory. If you +don't use any file-name arguments, @code{tar} extracts all the files +in the archive. + +Note: @code{tar} will extract an archive member into the file system +without checking to see if there is already a file with the archive +member's file name. If there is a file with that name, @code{tar} +will @strong{overwrite} that file and its contents will be lost. +@c <<>> we want people to use the script for backups, so I an not going to +@c >>> use backups as an explanation in the tutorial. (people can still +@c >>> do it if they really want to) -ringo + +While you can use @code{tar} to create a new archive every time you +want to store a file, it is more sometimes efficient to add files to +an existing archive. + +To add new files to an existing archive, use the @samp{+add-file}, +@samp{+append} or @samp{-r} operation. To add newer versions of +archive members to an archive, use the @samp{+update} or @samp{-u} +operation. + +@menu +* Append:: Appending Files to an Archive +* Update:: Updating Files in an Archive +@end menu + +@node Append, Update, Adding to Archives, Adding to Archives +@subsection Appending Files to an Archive + +The simplest method of adding a file to an existing archive is the +@samp{+add-file}, @samp{-r} or @samp{+append} operation, which writes +files into the archive without regard to whether or not they are +already archive members. When you use @samp{+add-file} you must use +file-name arguments; there is no default. If you specify a file that +is already stored in the archive, @code{tar} adds another copy of the +file to the archive. + +If you have been following the previous examples, you should have a +text file called @file{~/practice/rock} which has not been stored in +either the archive file @file{~/practice/records}, or the archive file +@file{~/music}. To add @file{rock} to @file{records}, first make +@file{practice} the working directory (@samp{cd practice}). Then: + +@itemize @bullet +@item +Invoke @code{tar} and specify the @samp{+add-file} operation +(@samp{+add-file}, @samp{-r} or @samp{+append}) + +@item +Specify the archive to which the file will be added +(@samp{+file=@var{archive-name}} or @samp{-f @var{archive-name}}) + +@item +Specify the files to be added to the archive, using file-name +arguments +@end itemize + +@noindent +For example: + +@example +% tar +add-file +file=records rock +@end example + +@noindent +If you list the archive members in @file{records}, you will see that +@file{rock} has been added to the archive: + +@example +% tar +list +file=records +blues +folk +jazz +rock +@end example + +@c <<< this should be some kind of node. + +You can use @samp{+add-file} to keep archive members current with +active files. Because @samp{+add-file} stores a file whether or not +there is already an archive member with the same file name, you can +use @samp{+add-file} to add newer versions of archive members to an +archive. When you extract the file, only the version stored last will +wind up in the file system. Because @samp{tar +extract} extracts +files from an archive in sequence, and overwrites files with the same +name in the file system, if a file name appears more than once in an +archive the last version of the file will overwrite the previous +versions which have just been extracted. + +If you recall from the examples using @samp{+compare} above, +@file{blues} was changed after the archive @file{records} was created. +It is simple, however, to use @samp{+add-file} to add the new version +of @file{blues} to @file{records}: + +@example +% tar +add-file +verbose +file=records blues +blues +@end example + +@noindent +If you now list the contents of the archive, you will obtain the following: + +@example +% tar +list -f records +blues +folk +jazz +rock +blues +@end example + +@noindent +The newest version of @file{blues} is at the end of the archive. When +the files in @file{records} are extracted, the newer version of +@file{blues} (which has the same name as the older) will overwrite the +version stored first. When @samp{tar +extract} is finished, only the +newer version of @file{blues} is in the file system. <<>> + +@node Update, , Append, Adding to Archives +@subsection Updating Files in an Archive + +To keep archive members up to date with their counterparts of the same +name in the file system, use the @samp{+update} or @samp{-u} +operation. @samp{tar +update} adds a specified file to an archive if +no file of that name is already stored in the archive. If there is +already an archive member with the same name, @code{tar} checks the +modification date of the archive member, and adds the file only if its +modification date is later. If a file is stored in the archive but no +longer exists under the same name in the active file system, +@code{tar} reports an error. + +You could use the @samp{+add-file} option to keep an archive current, +but do so you would either have to use the @samp{+compare} and +@samp{+list} options to determine what files needed to be re-archived +(which could waste a lot of time), or you would have to be willing to +add identical copies of already archived files to the archive (which +could waste a lot of space). + +You must use file-name arguments with the @samp{+update} +operation---if you don't specify any files, @code{tar} won't act on +any files. + +To see the @samp{+update} option at work, create a new file, +@file{~/practice/classical}, and modify the file +@file{~/practice/blues} (you can use a text editor, such as Emacs, to +do both these things). Then, with @file{practice} as your working +directory, invoke @samp{tar +update} using the names of all the files +in the practice directory as file-name arguments, and specifying the +@samp{+verbose} option: + +@example +% tar +update +verbose +file=records blues folk rock classical +blues +classical +% +@end example + +@noindent +Because you specified verbose mode, @code{tar} printed out the names +of the files it acted on. If you now list the archive members of the +archive, (@samp{tar +list +file=records}), you will see that the file +@file{classical} and another version of the file @file{blues} have +been added to @file{records}. + +Note: When you update an archive, @code{tar} does not overwrite old +archive members when it stores newer versions of a file. This is +because archive members appear in an archive in the order in which +they are stored, and some archive devices do not allow writing in the +middle of an archive. + +@node Concatenate, Extracting Files Example, Adding to Archives, Tutorial +@comment node-name, next, previous, up +@section Concatenating Archives + +To concatenate archive files, use @samp{tar +concatenate} or @samp{tar +-A}. This operation adds other archives to the end of an archive. +While it may seem intuitive to concatenate archives using @code{cat}, +the utility for adding files together, archive files which have been +"catted" together cannot be read properly by @code{tar}. Archive +files incorporate an end of file marker---if archives are concatenated +using @code{cat}, this marker will appear before the end of the new +archive. This will interfere with operations on that archive. +@c <<>> + +In earlier examples, you stored the @file{~/practice} directory in an +archive file, @file{~/music}. If you have been following the +examples, you have since changed the contents of the @file{~/practice} +directory. There is a current version of the files in the +@file{practice} directory, however, stored in the archive file +@file{~/practice/records}. + +To store current versions of the files in @file{practice} in the +archive file @file{music}, you can use @samp{tar +concatenate} to add +the archive file @file{~/practice/records} to @file{music}. First, +make sure you are in your home directory (@samp{cd ~}). Then: + +@itemize @bullet +@item +Invoke @code{tar}, and specify the @samp{+concatenate} operation +(@samp{-A} or @samp{+concatenate}) + +@item +Specify the archive file to be added to +(@samp{+file=@var{archive-name}} or @samp{-f @var{archive-name}}) + +@item +Specify the archives to be added, using file-name arguments. In this +case, the file-name arguments are, unusually, the names of archive +files. (Remember to include the path in the archive name, if the +archive file is not in your working directory.) +@end itemize + +@example +% cd ~ +% tar +concatenate +file=music practice/records +@end example + +If you now list the contents of the @file{music}, you see it now +contains the archive members of @file{practice/records}: + +@example +%tar +list +file=music +blues +folk +jazz +rock +blues +practice/blues +practice/folk +practice/jazz +practice/rock +practice/blues +practice/classical +@end example + +@node Deleting Files, , , Tutorial +@comment node-name, next, previous, up +@section Deleting Files From an Archive + +In some instances, you may want to remove some files from an archive +stored on disk + +@quotation +@emph{Caution:} you should never delete files from an archive stored +on tape---because of the linear nature of tape storage, doing this is +likely to scramble the archive. +@end quotation + +To remove archive members from an archive, use the @samp{+delete} +operation. You must specify the names of files to be removed as +file-name arguments. All versions of the named file are removed from +the archive. + +Execution of the @samp{+delete} operation can be very slow. + +To delete all versions of the file @file{blues} from the archive +@file{records} in the @file{practice} directory, make sure you are in +that directory, and then: + +@itemize @bullet +@item +List the contents of the archive file @file{records} (see above for +the steps involved) to insure that the file(s) you wish to delete are +stored in the archive. (This step is optional) + +@item +Invoke @code{tar} and specify the @samp{+delete} operation +(@samp{+delete}). + +@item +Specify the name of the archive file that the file(s) will be deleted +from (@samp{+file=@var{archive-name}} or @samp{-f @var{archive-name}}) + +@item +Specify the files to be deleted, using file-name arguments. + +@item +List the contents of the archive file again---note that the files have +been removed. (this step is also optional) +@end itemize + +@example +% tar +list +file=records +blues +folk +jazz +% tar +delete +file=records blues +% tar +list +file=records +folk +jazz +% +@end example + +@node Wizardry, Archive Structure, Tutorial, Top +@chapter Wizardry + +<<>>>> + +@node Archive Structure, Reading and Writing, Wizardry, Top +@chapter The Structure of an Archive + +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. + + +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. + +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}. + +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. + +@menu +* Old Style File Information:: Old Style File Information +* Archive Label:: +* Format Variations:: +@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. + +@table @samp +@item +old-archive +@itemx -o +@itemx +old +@itemx +portable +@c has portability been changed to portable? +Creates an archive that can be read by an old @code{tar} program. +Used in conjunction with the @samp{tar +create} operation. +@end table + +@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 + +@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: + +@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 + +@table @samp +@item +label=@var{archive-label} +@itemx -V @var{archive-label} +Includes an @dfn{archive-label} at the beginning of the archive when +the archive is being created (when used in conjunction with the +@samp{tar +create} operation). Checks to make sure the archive label +matches the one specified (when used in conjunction with the @samp{tar ++extract} operation. +@end table +@c was +volume + +@node Format Variations, , Archive Label, Archive Structure +@section Format Variations +@cindex Format Parameters +@cindex Format Options +@cindex Options to specify archive format. + +Format parameters specify how an archive is written on the archive +media. The best choice of format parameters will vary depending on +the type and number of files being archived, and on the media used to +store the archive. + +To specify format parameters when accessing or creating an archive, +you can use the options described in the following sections. If you +do not specify any format parameters, @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. + + +@menu +* Multi-Volume Archives:: +* Sparse Files:: +* Blocking Factor:: +* Compressed Archives:: +@end menu + +@node Multi-Volume Archives, Sparse Files, Format Variations, Format Variations +@subsection Archives Longer than One Tape or Disk +@cindex Multi-volume archives + +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. + +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. + +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}. + +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. + +@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. + + +<<< There should be a sample program here, including an exit before +<<< end. + +@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 +info-script=@var{program-file} +@itemx -F @var{program-file} +Creates a multi-volume archive via a script. Used in conjunction with +@samp{tar +create}. +@end table + +@node Sparse Files, Blocking Factor, Multi-Volume Archives, Format Variations +@subsection Archiving Sparse Files +@cindex Sparse Files + +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. + +@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. + +@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 + +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 + +@code{tar} ignores the @samp{+sparse} option when reading an archive. + +@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 + +@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. + +@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 + +@node Compressed Archives, , Blocking Factor, Format Variations +@subsection Creating and Reading Compressed Archives +@cindex Compressed archives +@cindex Storing archives in compressed format + +@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. + +@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. + +@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 + +@table @samp +@item +compress +@itemx +uncompress +@itemx -z +@itemx -Z +When this option is specified, @code{tar} will compress (when writing +an archive), or uncompress (when reading an archive). Used in +conjunction with the @samp{+create}, @samp{+extract}, @samp{+list} and +@samp{+compare} operations. + +@item +compress-block +@itemx -z -z +Acts like @samp{+compress}, but pads the archive out to the next block +boundary as it is written when used in conjunction with the +@samp{+create} operation. +@end table + +@c >>> MIB -- why not use -Z instead of -z -z ? -ringo + +@node Reading and Writing, Insuring Accuracy, Archive Structure, Top +@chapter Reading and Writing Archives + +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. + +@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 + +@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? + +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. + +@c >>> MIB--does standard input and output redirection work with all +@c >>> operations? +@c >>> need example for standard input and output (screen and keyboard?) + +@cindex Standard input and output +@cindex tar to standard input and output + +To specify an archive file on a device attached to a remote machine, +use the following: + +@example ++file=@var{hostname}:/@var{dev}/@var{file name} +@end example + +@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. + +@c >>>MIB --- is this clear? + +@table @samp +@item +file=@var{archive-name} +@itemx -f @var{archive-name} +Names the archive to create or operate on. Use in conjunction with +any operation. +@end table + +@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 + +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. + +The following example creates an archive named @file{stooges}, +containing the files @file{larry}, @file{moe} and @file{curley}: + +@example +tar +create +file=stooges larry moe curley +@end example + +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}: + +@example +tar +create +file=hail/hail/fredonia marx +@end example + +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: + +@example +tar +create +file=home +@end example + +@xref{File Name Lists}, for other ways to specify files to archive. + +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. + +@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. + +To find out what files are already stored in an archive, use @samp{tar ++list +file=@var{archive-name}}. @xref{Listing Contents}. + +@menu +* Adding Files:: +* Appending Archives:: +* Deleting Archive Files:: Deleting Files From an Archive +* Matching Format Parameters:: +@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 + +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}. + +The following example adds the file @file{shemp} to the archive +@file{stooges} created above: + +@example +tar +add-file +file=stooges shemp +@end example + +You must specify the files to be added; there is no default. + +@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. + +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. + +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. + +@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 + +To append copies of an archive or archives to the end of another +archive, use @samp{tar +add-archive}. The source and target archives +must already exist and have been created using compatable format +parameters (@pxref{Matching Format Parameters}). + +@code{tar} will stop reading an archive if it encounters an +end-of-archive marker. The @code{cat} utility does not remove +end-of-archive markers, and is therefore unsuitable for concatenating +archives. @samp{tar +add-archive} removes the end-of-archive marker +from the target archive before each new archive is appended. +@c <<< xref ignore-zeros + +You must specify the source archives using +@samp{+file=@var{archive-name}} (@pxref{Archive Name}). If you do not +specify the target archive , @code{tar} uses the value of the +environment variable @code{TAPE}, or, if this has not been set, the +default archive name. + +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): + +@example +tar +add-archive +file=stooges hail/hail/fredonia +@end example + +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}). + +@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 + +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. + +The following example removes the file @file{curley} from the archive +@file{stooges}: + +@example +tar +delete +file=stooges curley +@end example + +You can only use @samp{tar +delete} on an archive if the archive +device allows you to write to any point on the media. + +@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 + +@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=-). + +@node Matching Format Parameters, , Deleting Archive Files, Modifying +@subsection Matching the Format Parameters + +Some format parameters must be taken into consideration when modifying +an archive: + +Compressed archives cannot be modified. + +You have to specify the block size of the archive when modifying an +archive with a non-default block size. + +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 @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 + +@c <<< xref somewhere, for more information about format parameters. + +@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 + +@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. + +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. + +If the blocking factor of the archive differs from the default, +@code{tar} reports this. @xref{Blocking Factor}. + +@xref{Archive Reading Options} for a list of options which can be used +to modify @samp{+list}'s operation. + +This example prints a list of the archive members of the archive +@file{stooges}: + +@example +tar +list +file=stooges +@end example + +@noindent +@code{tar} responds: + +@example +larry +moe +shemp +marx/julius +marx/alexander +marx/karl +@end example + +This example generates a verbose list of the archive members of the +archive file @file{dwarves}, which has a blocking factor of two: + +@example +tar +list -v +file=blocks +@end example + +@noindent +@code{tar} responds: + +@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 + +@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 + +To read archive members from the archive and write them into the file +system, use @samp{tar +extract}. The archive itself is left +unchanged. + +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. + +The following example shows the extraction of the archive +@file{stooges} into an empty directory: + +@example +tar +extract +file=stooges +@end example + +@noindent +Generating a listing of the directory (@samp{ls}) produces: + +@example +larry +moe +shemp +marx +@end example + +@noindent +The subdirectory @file{marx} contains the files @file{julius}, +@file{alexander} and @file{karl}. + +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: + +@example +tar +extract +file=stooges marx +@end example + +@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 + +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}). + +@menu +* Archive Reading Options:: +* File Writing Options:: +* Scarce Disk Space:: Recovering From Scarce Disk Space +@end menu + +@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 + +@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. + +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}. + +@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 + +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). + +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. + +@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 + +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. + +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. + +This option is probably never needed on modern computer systems. + +@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 + +@c we don't need/want +preserve to exist any more + +@node File Writing Options, Scarce Disk Space, Archive Reading Options, Extracting From Archives +@subsection Changing How @code{tar} Writes Files +@c <<< find a better title +@cindex Overwriting old files, prevention +@cindex Protecting old files +@cindex Modification times of extracted files +@cindex Permissions of extracted files +@cindex Modes of extracted files +@cindex Writing extracted files to standard output +@cindex Standard output, writing extracted files to + +Normally, @code{tar} writes extracted files into the file system +without regard to the files already on the system---files with the +same name as archive members are overwritten. To prevent @code{tar} +from extracting an archive member from an archive, if doing so will +overwrite a file in the file system, use @samp{+keep-old-files} in +conjunction with the @samp{+extract} operation. When this option is +specified, @code{tar} reports an error stating the name of the files +in conflict, instead of writing the file from the archive. + +@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. + +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}. + +@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 + +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. + +@c >>> is write access an issue? + +@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 + +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, + +@example +tar +create iggy ziggy +directory=baz melvin +@end example + +@noindent +will place the files @file{iggy} and @file{ziggy} from the current +directory into the archive, followed by the file @file{melvin} from +the directory @file{baz}. This option is especially useful when you +have several widely separated files that you want to store in the same +directory in the archive. + +Note that the file @file{melvin} is recorded in the archive under the +precise name @file{melvin}, @emph{not} @file{baz/melvin}. Thus, the +archive will contain three files that all appear to have come from the +same directory; if the archive is extracted with plain @samp{tar ++extract}, all three files will be written in the current directory. + +Contrast this with the command + +@example +tar -c iggy ziggy bar/melvin +@end example + +@noindent +which records the third file in the archive under the name +@file{bar/melvin} so that, if the archive is extracted using @samp{tar ++extract}, the third file will be written in a subdirectory named +@file{bar}. + +@table @samp +@item +directory=@file{directory} +@itemx -C @file{directory} +Changes the working directory. +@end table + +@c <<>> + +@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} + +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. + +@menu +* Additional Information:: +* Interactive Operation:: +@end menu + +@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. + +@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 + +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. + +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 + +@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 + +@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: + +@example +tar +version +@end example + +@noindent +might return: + +@example +GNU tar version 1.09 +@end example +@c used to be an option. has been fixed. + +@node Interactive Operation, , Additional Information, User Interaction +@section Asking for Confirmation During Operations +@cindex Interactive operation + +Typically, @code{tar} carries out a command without stopping for +further instructions. In some situations however, you +may want to exclude some files and archive members from the operation +(for instance if disk or storage space is tight). You can do this by +excluding certain files automatically (@pxref{File Exclusion}), or by +performing an operation interactively, using the @samp{+interactive} +operation. + +When the @samp{+interactive} option is specified, @code{tar} asks for +confirmation before reading, writing, or deleting each file it +encounters while carrying out an operation. To confirm the action you +must type a line of input beginning with @samp{y}. If your input line +begins with anything other than @samp{y}, @code{tar} skips that file. + +Commands which might be useful to perform interactively include +appending files to an archive, extracting files from an archive, +deleting a file from an archive, and deleting a file from disk during +an incremental restore. + +If @code{tar} is reading the archive from the standard input, +@code{tar} opens the file @file{/dev/tty} to support the interactive +communications. +<<< this aborts if you won't OK the working directory. this is a bug. -ringo + +@table @samp +@item +interactive +@itemx +confirmation +@itemx -w +Asks for confirmation before reading, writing or deleting an archive +member (when listing, comparing or writing an archive or deleting +archive members), or before writing or deleting a file (when +extracting an archive). +@end table + +@node Backups and Restoration, Media, User Interaction, Top +@chapter Performing Backups and Restoring Files + +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}. + +@menu +* Backup Levels:: Levels of backups +* Backup Scripts:: Using scripts to perform backups + and restoration +* incremental and listed-incremental:: The +incremental + and +listed-incremental Options +* Problems:: Some common problems and their solutions +@end menu + +@node Backup Levels, Backup Scripts, Backups and Restoration, Backups and Restoration +@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 a incremental dump. 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). + +@node Backup Scripts, incremental and listed-incremental, Backup Levels, Backups and Restoration +@section Using Scripts to Perform Backups and Restoration + +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. + +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 +@end menu + +@node Backup Parameters, Scripted Backups, Backup Scripts, Backup Scripts +@subsection Setting Parameters for Backups and Restoration + +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. + +@c <<< This about backup scripts needs to be written: +@c <<>> + +@item +tape-length=@var{n} (-L) +@c <<>> +@c <<< this needs to be written into main body as well -ringo + +@item +info-script=@var{program-file} +Create a multi-volume archive via a script. @xref{Multi-Volume Archives}. + +@item +interactive +Ask for confirmation before performing any operation on a file or +archive member. + +@item +keep-old-files +Prevent overwriting during extraction. @xref{File Writing Options}. + +@item +label=@var{archive-label} +Include an archive-label in the archive being created. @xref{Archive +Label}. + +@item +modification-time +Set the modification time of extracted files to the time they were +extracted. @xref{File Writing Options}. + +@item +multi-volume +Specify a multi-volume archive. @xref{Multi-Volume Archives}. + +@item +newer=@var{date} +Limit the operation to files changed after the given date. +@xref{File Exclusion}. + +@item +newer-mtime=@var{date} +Limit the operation to files modified after the given date. @xref{File +Exclusion}. + +@item +old +Create an old format archive. @xref{Old Style File Information}. +@c <<< did we agree this should go away as a synonym? + +@item +old-archive +Create an old format archive. @xref{Old Style File Information}. + +@item +one-file-system +Prevent @code{tar} from crossing file system boundaries when +archiving. @xref{File Exclusion}. + +@item +portable +Create an old format archive. @xref{Old Style File Information}. +@c <<< was portability, may still need to be changed + +@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}. + +@item +same-order +Help process large lists of file-names on machines with small amounts of +memory. @xref{Archive Reading Options}. + +@item +same-permission +Set the modes of extracted files to those recorded in the archive. +@xref{File Writing Options}. + +@item +sparse +Archive sparse files sparsely. @xref{Sparse Files}. + +@item +starting-file=@var{file-name} +Begin reading in the middle of an archive. @xref{Scarce Disk Space}. + +@item +to-stdout +Write files to the standard output. @xref{File Writing Options}. + +@item +uncompress +Specifdo a compressed archive. @xref{Compressed Archives}. + +@item -V @var{archive-label} +Include an archive-label in the archive being created. @xref{Archive +Label}. +@c was +volume + +@item +verbose +Print the names of files or archive members as they are being +operated on. @xref{Additional Information}. + +@item +verify +Check for discrepancies in the archive immediately after it is +written. @xref{Write Verification}. + +@item -B +Read an archive with a smaller than specified block size or which +contains incomplete blocks. @xref{Archive Reading Options}). + +@item -K @var{file-name} +Begin reading in the middle of an archive. @xref{Scarce Disk Space}. + +@item -M +Specify a multi-volume archive. @xref{Multi-Volume Archives}. + +@item -N @var{date} +Limit operation to files changed after the given date. @xref{File Exclusion}. + +@item -O +Write files to the standard output. @xref{File Writing Options}. + +@c <<<<- P is absolute paths, add when resolved. -ringo>>> + +@item -R +Print the record number where a message is generated. +@xref{Additional Information}. + +@item -S +Archive sparse files sparsely. @xref{Sparse Files}. + +@item -T @var{file} +Read file-name arguments from a file on the file system. +@xref{File Name Lists}. + +@item -W +Check for discrepancies in the archive immediately after it is +written. @xref{Write Verification}. + +@item -Z +Specify a compressed archive. @xref{Compressed Archives}. + +@item -b @var{number} +Specify the blocking factor of an archive. @xref{Blocking Factor}. + +@item -f @var{archive-name} +Name the archive. @xref{Archive Name}). + +@item -h +Treat a symbolic link as an alternate name for the file the link +points to. @xref{Symbolic Links}. + +@item -i +Ignore end-of-archive entries. @xref{Archive Reading Options}. + +@item -k +Prevent overwriting during extraction. @xref{File Writing Options}. + +@item -l +Prevent @code{tar} from crossing file system boundaries when +archiving. @xref{File Exclusion}. + +@item -m +Set the modification time of extracted files to the time they were +extracted. @xref{File Writing Options}. + +@item -o +Create an old format archive. @xref{Old Style File Information}. + +@item -p +Set the modes of extracted files to those recorded in the archive. +@xref{File Writing Options}. + +@item -s +Help process large lists of file-names on machines with small amounts of +memory. @xref{Archive Reading Options}. + +@item -v +Print the names of files or archive members they are being operated +on. @xref{Additional Information}. + +@item -w +@c <<>> + +@item -z +Specify a compressed archive. @xref{Compressed Archives}. + +@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 -C @file{directory} +Change the working directory. @xref{Changing Working Directory}. + +@item -F @var{program-file} +Create a multi-volume archive via a script. @xref{Multi-Volume Archives}. + +@item -X @file{file} +Exclude files which match any of the regular expressions listed in +the file @file{file}. @xref{File Exclusion}. +@end table + +@node Data Format Details, Concept Index, Quick Reference, Top +@appendix Details of the Archive Data Format + +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. + +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. + +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. + +@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 + +@node Header Data, Header Fields, Data Format Details, Data Format Details +@appendixsec The Distribution of Data in the Header + +The header record is defined in C as follows: +@c I am taking the following code on faith. + +@example +@r{Standard Archive Format - Standard TAR - USTAR} + +#define RECORDSIZE 512 +#define NAMSIZ 100 +#define TUNMLEN 32 +#define TGNMLEN 32 +#define SPARSE_EXT_HDR 21 +#define SPARSE_IN_HDR 4 + +struct sparse @{ + char offset[12]; + char numbytes[12]; +@}; + +union record @{ + char charptr[RECORDSIZE]; + struct header @{ + char name[NAMSIZ]; + char mode[8]; + char uid[8]; + char gid[8]; + char size[12]; + char mtime[12]; + char chksum[8]; + char linkflag; + char linkname[NAMSIZ]; + char magic[8]; + char uname[TUNMLEN]; + char gname[TGNMLEN]; + char devmajor[8]; + char devminor[8]; + +@r{The following fields were added by gnu and are not used by other} +@r{versions of @code{tar}}. + char atime[12]; + char ctime[12]; + char offset[12]; + char longnames[4]; +@r{The next three fields were added by gnu to deal with shrinking down} +@r{sparse files.} + struct sparse sp[SPARSE_IN_HDR]; + char isextended; +@r{This is the number of nulls at the end of the file, if any.} + char ending_blanks[12]; + + @} header; + + struct extended_header @{ + struct sparse sp[21]; + char isextended; + @} ext_hdr; + +@}; +@c <<< this whole thing needs to be put into better english + +@r{The checksum field is filled with this while the checksum is computed.} +#define CHKBLANKS " " @r{8 blanks, no null} + +@r{Inclusion of this field marks an archive as being in standard} +@r{Posix format (though GNU tar itself is not Posix conforming). GNU} +@r{tar puts "ustar" in this field if uname and gname are valid.} +#define TMAGIC "ustar " @r{7 chars and a null} + +@r{The magic field is filled with this if this is a GNU format dump entry.} +#define GNUMAGIC "GNUtar " @r{7 chars and a null} + +@r{The linkflag defines the type of file.} +#define LF_OLDNORMAL '\0' @r{Normal disk file, Unix compatible} +#define LF_NORMAL '0' @r{Normal disk file} +#define LF_LINK '1' @r{Link to previously dumped file} +#define LF_SYMLINK '2' @r{Symbolic link} +#define LF_CHR '3' @r{Character special file} +#define LF_BLK '4' @r{Block special file} +#define LF_DIR '5' @r{Directory} +#define LF_FIFO '6' @r{FIFO special file} +#define LF_CONTIG '7' @r{Contiguous file} + +@r{hhe following are further link types which were defined later.} + +@r{This is a dir entry that contains the names of files that were in} +@r{the dir at the time the dump was made.} +#define LF_DUMPDIR 'D' + +@r{This is the continuation of a file that began on another volume} +#define LF_MULTIVOL 'M' + +@r{This is for sparse files} +#define LF_SPARSE 'S' + +@r{This file is a tape/volume header. Ignore it on extraction.} +#define LF_VOLHDR 'V' + +@r{These are bits used in the mode field - the values are in octal} +#define TSUID 04000 @r{Set UID on execution} +#define TSGID 02000 @r{Set GID on execution} +#define TSVTX 01000 @r{Save text (sticky bit)} + +@r{These are file permissions} +#define TUREAD 00400 @r{read by owner} +#define TUWRITE 00200 @r{write by owner} +#define TUEXEC 00100 @r{execute/search by owner} +#define TGREAD 00040 @r{read by group} +#define TGWRITE 00020 @r{write by group} +#define TGEXEC 00010 @r{execute/search by group} +#define TOREAD 00004 @r{read by other} +#define TOWRITE 00002 @r{write by other} +#define TOEXEC 00001 @r{execute/search by other} +@end example + + +All characters in headers are 8-bit characters in the local variant of +ASCII. Each field in the header is contiguous; that is, there is no +padding in the header format. + +Data representing the contents of files is not translated in any way +and is not constrained to represent characters in any character set. +@code{tar} does not distinguish between text files and binary files. + +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}. + +@menu +* File Types:: File Types +* GNU File Types:: Additional File Types Supported by GNU +@end menu + +@node File Types, GNU File Types, Header Fields, Header Fields +@appendixsubsec File Types + +The following flags are used to describe file types: + +@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. + +@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. + +@item LF_SPARSE +@itemx 'S' +Indicates a sparse file. @xref{Sparse Files}. @xref{Sparse File +Handling}. + +@item LF_VOLHDR +@itemx 'V' +Marks an archive label that was created using the @samp{+label} option +when the archive was created (@pxref{Archive Label}. The @code{name} +field contains the argument to the option. The @code{size} field is +zero. Only the first file in each volume of an archive should have +this type. +@end table + +@node Sparse File Handling, , Header Fields, Data Format Details +@appendixsec Fields to Handle Sparse Files + +The following header information was added to deal with sparse files +(@pxref{Sparse Files}): + +@c TALK TO MIB +The @code{sp} field (fields? something else?) is an array of +@code{struct sparse}. Each @code{struct sparse} contains two +12-character strings, which represent the offset into the file and the +number of bytes to be written at that offset. The offset is absolute, +and not relative to the offset in preceding array elements. + +The 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. + +The @code{isextended} flag is only set for sparse files, and then only +if extended header records are needed when archiving the file. + +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. + +@c so is @code{extended_header} the right way to write this? + +@node Concept Index, , Data Format Details, Top +@unnumbered Concept Index + +@printindex cp + +@summarycontents +@contents +@bye + +