X-Git-Url: https://git.dogcows.com/gitweb?a=blobdiff_plain;f=doc%2Ftar.texi;h=78cc8b1f02b36d1206fc4dd98e3c25d4b258c6bc;hb=63f2f45b88e84d2a8d414da0ae81ffe58fda7cb4;hp=7ed5fa492aa4b430a1ca54c2d18866a17cd6c8af;hpb=6556021bfdacadb3759670964e91911320c870d9;p=chaz%2Ftar diff --git a/doc/tar.texi b/doc/tar.texi index 7ed5fa4..78cc8b1 100644 --- a/doc/tar.texi +++ b/doc/tar.texi @@ -10,26 +10,7 @@ @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 +@smallbook @iftex @c finalout @@ -54,9 +35,7 @@ Copyright (C) 1992 Free Software Foundation, Inc. DRAFT! @subtitle DRAFT @c subtitle insert month here when ready -@author Amy Gorin, Michael I. Bushnell, and Jay Fenlason -@c <<>>> +@author Michael I. Bushnell and Amy Gorin @page @vskip 0pt plus 1filll @@ -97,32 +76,6 @@ version 1.12. * 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 files' contents as well as a listing of those -files' characteristics. You can also use @code{tar} to read, add to, -or manipulate already existing archives. Because an archive created -by @code{tar} is capable of preserving file information and directory -structure, @code{tar} is ideal for performing full and incremental -backups, as well as for transferring groups of files between disks and -over networks. - -The name @code{tar} comes from the words ``Tape ARchiver'', but -@code{tar} can actually process archives wherever they are stored; on -tapes and disk files, for example. In addition, tar can read archives -from standard input or write them to standard output. (This is often -useful if redirected another program with a pipe.) - -@c <<< this menu will conflict with menu above in info mode. -ringo -@menu -* Invoking @code{tar}:: How to invoke @code{tar} and specify arguments. -* Tutorial:: An introduction to @code{tar}. -* Operations:: What you can use @code{tar} to do. -* Options:: How to change the way @code{tar} behaves. -* Problems:: Common problems with @code{tar}. -@end menu @chapter Tutorial Introduction to @code{tar} This chapter guides you through some basic examples of @code{tar} @@ -184,7 +137,7 @@ However, this manual consistently uses the terminology above in referring to files and archive members, to make it easier to learn how to use @code{tar}. -@section Creating Archives +@section How to Create Archives To create a new archive, use @samp{tar --create}. You should generally use the @samp{--file} option to specify the name the tar archive will @@ -260,7 +213,7 @@ is using a default value for @samp{--file}. You should generally specify a @samp{--file} argument whenever you use @code{tar}, rather than relying on a default. -@section Listing Archives +@section How to List Archives Use @samp{tar --list} to print the names of members stored in an archive. Use a @samp{--file} option just as with @samp{tar --create} to @@ -301,7 +254,7 @@ file names @file{baloons} and @file{./baloons} name the same file, member names are compared using a simplistic name comparison, in which an exact match is necessary. -@section Extracting Members from an Archive +@section How to Extract Members from an Archive In order to extract members from an archive, use @samp{tar --extract}. Specify the name of the archive with @samp{--file}. To extract specific @@ -331,7 +284,7 @@ will extract all the members of the archive. If you give the @samp{--verbose} option, then @samp{tar --extract} will print the names of the archive members as it extracts them. -@section Adding Files to Existing Archives +@section How to Add Files to Existing Archives If you want to add files to an existing archive, then don't use @samp{tar --create}. That will erase the archive and create a new one @@ -352,7 +305,7 @@ complex. @xref{Multiple Members with the Same Name}. If you want to replace an archive member, use @samp{tar --delete} first, and then use @samp{tar --append}. -@section Deleting Members from Archives +@section How to Delete Members from Archives You can delete members from an archive using @samp{tar --delete}. Specify the name of the archive with @samp{--file}. List the member @@ -367,7 +320,7 @@ Archives}). The @samp{tar --delete} command only works with archives stored on disk. You cannot delete members from an archive stored on a tape. -@section Directories +@section How to Archive Directories When the names of files or members specify directories, the operation of @code{tar} is more complex. Generally, when a directory is named, @@ -405,7 +358,7 @@ The command @samp{tar --extract --file=@var{archive-name} .} will not extract all the contents of the archive, but only those members whose member names begin with @samp{./}. -@section Shorthand names +@section Shorthand Names Most of the options to @code{tar} come in both long forms and short forms. The options described in this tutorial have the following @@ -590,6 +543,138 @@ argument for @samp{-f}, and @samp{-v} does not have a corresponding argument. The modern syntax---@samp{tar -c -v -b 20 -f /dev/rmt0}---is clearer. +@chapter Basic @code{tar} Operations + +This chapter describes the basic operations supported by the @code{tar} +program. A given invocation of @code{tar} will do exactly one of these +operations. + +@section Creating a New Archive + +The @samp{--create} (@code{-c}) option causes @code{tar} to create a new +archive. The files to be archived are then named on the command line. +Each file will be added to the archive with a member name exactly the +same as the name given on the command line. (When you give an absolute +file name @code{tar} actually modifies it slightly, @ref{Absolute +Paths}.) If you list no files to be archived, then an empty archive is +created. + +If there are two many files to conveniently list on the command line, +you can list the names in a file, and @code{tar} will read that file. +@xref{Reading Names from a File}. + +If you name a directory, then @code{tar} will archive not only the +directory, but all its contents, recursively. For example, if you name +@file{/}, then @code{tar} will archive the entire filesystem. + +Do not use the option to add files to an existing archive; it will +delete the archive and write a new one. Use @samp{--append} instead. +(@xref{Adding to an Existing Archive}.) + +There are various ways of causing @code{tar} to skip over some files, +and not archive them. @xref{Specifying Names to @code{tar}}. + +@section Adding to an Existing Archive + +The @samp{--append} (@code{-r}) option will case @code{tar} to add new +files to an existing archive. It interprets file names and member names +in exactly the same manner as @samp{--create}. Nothing happens if you +don't list any names. + +This option never deletes members. If a new member is added under the +same name as an existing member, then both will be in the archive, with +the new member after the old one. For information on how this affects +reading the archive, @ref{Multiple Members with the Same Name}. + +This operation cannot be performed on some tape drives, unfortunately, +due to deficiencies in the formats thoes tape drives use. + +@section Combining Archives + +The @samp{--catenate} (or @code{--concatenate}, or @code{-A}) causes +@code{tar} to add the contents of several archives to an existing +archive. + +Name the archives to be catenated on the command line. (Nothing happens +if you don't list any.) The members, and their member names, will be +copied verbatim from those archives. If this causes multiple members to +have the same name, it does not delete either; all the members with the +same name coexist. For information on how this affects reading the +archive, @ref{Multiple Members with the Same Name}. + +You must use this option to concatenate archives. If you just combine +them with @code{cat}, the result will not be a valid @code{tar} format +archive. + +This operation cannot be performed on some tape drives, unfortunately, +due to deficiencies in the formats thoes tape drives use. + +@section Removing Archive Members + +You can use the @samp{--delete} option to remove members from an +archive. Name the members on the command line to be deleted. This +option will rewrite the archive; because of this, it does not work on +tape drives. If you list no members to be deleted, nothing happens. + +@section Listing Archive Members + +The @samp{--list} (@samp{-t}) option will list the names of members of +the archive. Name the members to be listed on the command line (to +modify the way these names are interpreted, @pxref{Specifying Names to +@code{tar}}). If you name no members, then @samp{--list} will list the +names of all the members of the archive. + +To see more than just the names of the members, use the @samp{--verbose} +option to cause @code{tar} to print out a listing similar to that of +@samp{ls -l}. + +@section Extracting Archive Members + +Use @samp{--extract} (or @samp{--get}, or @samp{-x}) to extract members +from an archive. For each member named (or for the entire archive if no +members are named) on the command line (or with @samp{--files-from}) the +a file is created with the contents of the archive member. The name of +the file is the same as the member name. + +Various options cause @code{tar} to extract more than just file +contents, such as the owner, the permissions, the modification date, and +so forth. + +XXX +The @samp{--same-permissions} (or @samp{--preserve-permissions}, or +@samp{-p}) options cause @code{tar} to cause the new file to have the +same permissions as the original file did when it was placed in the +archive. Without this option, the current @code{umask} is used to +affect the permissions. + +When extrating, @code{tar} normally sets the modification time of the +file to the value recorded in the archive. The +@samp{--modification-time} option causes @code{tar} to omit doing this. +XXX + +@section Updating an Archive + +The @samp{--update} (or @samp{-u}) option updates a @code{tar} archive +by comparing the date of the specified archive members against the date +of the file with the same name. If the file has been modified more +recently than the archive member, then the archive member is deleted (as +with @samp{--delete}) and then the file is added to the archive (as with +@samp{--append}). On media where the @samp{--delete} option cannot be +performed (such as magnetic tapes), the @samp{--update} option similarly +fails. + +If no archive members are named (either on the command line or via +@samp{--files-from}), then the entire archive is processed in this +manner. + +@section Comparing Archives Members with Files + +The @samp{--compare} (or @samp{--diff}, or @samp{-d}) option compares +the contents of the specified archive members against the files with the +same names, and reports its findings. If no members are named on the +command line (or through @samp{--files-from}), then the entire archive +is so compared. + @chapter Specifying Names to @code{tar} When specifying the names of files or members to @code{tar}, it by @@ -606,7 +691,10 @@ line, you can put the names into a file, and then use the @samp{--files-from=@var{file-name-list}} (@samp{-T @var{file-name-list}}) option to @code{tar}. Give the name of the file which contains the list as the argument to @samp{--files-from}. The -file names should be separated by newlines in the list. +file names should be separated by newlines in the list. If you give a +single dash as a filename for @samp{--files-from} (that is, you specify +@samp{--files-from=-} or @samp{-T -}), then the filenames are read from +standard input. If you want to specify names that might contain newlines, use the @samp{--null} option. Then, the filenames should be separated by NUL @@ -645,8 +733,378 @@ If you only want @code{tar} make the date comparison on the basis of the actual contents of the file's modification, then use the @samp{--newer-mtime=@var{date}} option. -You should not depend on this option for making incremental dumps. To -learn how to use @code{tar} to make backups, @ref{Making Backups}. +You should never use this option for making incremental dumps. To learn +how to use @code{tar} to make backups, @ref{Making Backups}. + +@section Crossing Filesystem Boundaries + +The @samp{--one-file-system} option causes @code{tar} to modify its +normal behavior in archiving the contents of directories. If a file in +a directory is not on the same filesystem as the directory itself +(because it is a mounted filesystem in its own right), then @code{tar} +will not archive that file, or (if it is a directory itself) anything +beneath it. + +This does not necessarily limit @code{tar} to only archiving the +contents of a single filesystem, because all files named on the command +line (or through the @samp{--files-from} option) will always be +archived. + +@chapter Changing the Names of Members when Archiving + +@section Changing Directory + +The @samp{--directory=@var{directory}} (@samp{-C @var{directory}}) +option causes @code{tar} to change its current working directory to +@var{directory}. Unlike most options, this one is processed at the +point it occurs within the list of files to be processed. Consider the +following command: +@example +tar --create --file=foo.tar -C /etc passwd hosts -C /lib libc.a +@end example + +This command will place the files @file{/etc/passwd}, @file{/etc/hosts}, +and @file{/lib/libc.a} into the archive. However, the names of the +archive members will be exactly what they were on the command line: +@file{passwd}, @file{hosts}, and @file{libc.a}. The @samp{--directory} +option is frequently used to make the archive independent of the +original name of the directory holding the files. + +Note that @samp{--directory} options are interpreted consecutively. If +@samp{--directory} option specifies a relative pathname, it is +interpreted relative to the then current directory, which might not be +the same as the original current working directory of @code{tar}, due to +a previous @samp{--directory} option. + +When using @samp{--files-from} (@pxref{Reading Names from a File}), you +can put @samp{-C} options in the file list. Unfortunately, you cannot +put @samp{--directory} options in the file list. (This interpretation +can be disabled by using the @samp{--null} option.) + +@section Absolute Path Names + +When @code{tar} extracts archive members from an archive, it strips any +leading slashes (@code{/}) from the member name. This causes absolute +member names in the archive to be treated as relative file names. This +allows you to have such members extracted wherever you want, instead of +being restricted to extracting the member in the exact directory named +in the archive. For example, if the archive member has the name +@file{/etc/passwd}, @code{tar} will extract it as if the name were +really @file{etc/passwd}. + +Other @code{tar} programs do not do this. As a result, if you create an +archive whose member names start with a slash, they will be difficult +for other people with an inferior @code{tar} program to use. Therefore, +GNU @code{tar} also strips leading slashes from member names when +putting members into the archive. For example, if you ask @code{tar} to +add the file @file{/bin/ls} to an archive, it will do so, but the member +name will be @file{bin/ls}. + +If you use the @samp{--absolute-paths} option, @code{tar} will do +neither of these transformations. + +@section Symbolic Links + +Normally, when @code{tar} archives a symbolic link, it writes a record +to the archive naming the target of the link. In that way, the +@code{tar} archive is a faithful record of the filesystem contents. +However, if you want @code{tar} to actually dump the contents of the +target of the symbolic link, then use the @samp{--dereference} option. + +@chapter Making @code{tar} More Verbose + +Various options cause @code{tar} to print information as it progresses +in its job. + +The @samp{--verbose} (or @samp{-v}) option causes @code{tar} to print +the name of each archive member or file as it is processed. Since +@samp{--list} already prints the names of the members, @samp{--verbose} +used with @samp{--list} causes @code{tar} to print a longer listing +(reminiscent of @samp{ls -l}) for each member. + +To see the progress of @code{tar} through the archive, the +@samp{--record-number} option prints a message for each record read or +writted. (@xref{Archive Structure}.) This option can be very helpful +when trying to figure out where in the archive an error occurs. + +The @samp{--totals} option (which is only meaningful when used with +@samp{--create}) causes @code{tar} to print the total amount written to +the archive, after it has been fully created. + +The @samp{--checkpoint} option prints an occasional message as +@code{tar} reads or writes the archive. It is designed for those who +don't need the more detailed (and voluminous) output of +@samp{--record-number}, but do want visual confirmation that @code{tar} +is actually making forward progress. + +The @samp{--version} option will generate a message with the version of +GNU @code{tar} you are using. + +@chapter Input and Output + +@section Changing the Archive Name + +By default, @code{tar} uses an archive file name compiled in when +@code{tar} was built. Usually this refers to some physical tape drive +on the machine. Often, the installer of @code{tar} didn't set the +default to anything meaningful at all. + +As a result, most uses of @code{tar} need to tell @code{tar} where to +find (or create) the archive. The @samp{--file=@var{archive-name}} (or +@samp{-f @var{archive-name}} option selects another file to use as the +archive. + +If the archive file name includes a colon (@samp{:}), then it is assumed +to be a file on another machine. If the archive file is +@samp{@var{user}@@@var{host}:@var{file}}, then @var{file} is used on the +host @var{host}. The remote host is accessed using the @code{rsh} +program, with a username of @var{user}. If the username is omitted +(along with the @samp{@@} sign), then your user name will be used. +(This is the normal @code{rsh} behavior.) It is necessary for the +remote machine, in addition to permitting your @code{rsh} access, to +have the @code{/usr/ucb/rmt} program installed. If you need to use a +file whose name includes a colon, then the remote tape drive behavior +can be inhibited by using the @samp{--force-local} option. + +If the filename you give to @samp{--file} is a single dash (@samp{-}), +then @code{tar} will read the archive from (or write it to) standard +input (or standard output). + +@section Extracting Members to Standard Output + +An archive member in normally extracted into a file with the same name +as the archive member. However, you can use the @samp{--to-stdout} to +cause @code{tar} to write extracted archive members to standard output. +If you extract multiple members, they appear on standard output +concatenated, in the order they are found in the archive. + +@section Dealing with Compressed Archives + +You can have archives be compressed by using the @samp{--gzip} (or +@samp{-z}) option. This will arrange for @code{tar} to use the +@code{gzip} program to be used to compress or uncompress the archive +wren writing or reading it. + +To use the older, obsolete, @code{compress} program, use the +@samp{--compress} (or @samp{-Z}) option. The GNU Project recommends you +not use @code{compress}, because there is a patent covering the +algorithm it uses. Merely by running @code{compress} you could be sued +for patent infringment. + +When using either @samp{--gzip} or @samp{--compress}, @code{tar} does +not do blocking (@pxref{Blocking}) correctly. Use @samp{--gzip-block} +or @samp{--compress-block} instead when using real tape drives. + +@chapter Being More Careful + +When using @code{tar} with many options, particularly ones with +complicated or difficult-to-predict behavior, it is possible to make +serious mistakes. As a result, @code{tar} provides several options that +make observing @code{tar} easier. + +The @samp{--verbose} option causes @code{tar} to print the name of each +file or archive member as it is processed. This and the other options +which make tar print status information can be useful in monitoring +@code{tar}. @xref{Making @code{tar} More Verbose}. + +If you use @samp{--interactive} (or {@samp--confirm}), then @code{tar} +will ask you for confirmation before each operation. For example, when +extracting, it will prompt you before each archive member is extracted, +and you can select that member for extraction or pass over to the next. + +The @samp{--verify} option, when using @samp{--create}, causes +@code{tar}, after having finished creating the archive, to go back over +it and compare its contents against the files that were placed in the +archive. + +The @samp{--show-omitted-dirs} option, when reading an archive (with +@samp{--list} or @samp{--extract}, for example), causes a message to be +printed for each directory in the archive which is skipped. This +happens regardless of the reason for skipping: the directory might not +have been named on the command line (implicitly or explicitly), it might +be excluded by the use of the @samp{--exclude} option, or some other +reason. + +@chapter Using Real Tape Drives + +Many complexities surround the use of @code{tar} on tape drives. Since +the creation and manipulation of archives located on magnetic tape was +the original purpose of @code{tar}, it contains many features making +such manipulation easier. + +@section Blocking + +When writing to tapes, @code{tar} writes the contents of the archive in +chunks known as @dfn{blocks}. To change the default blocksize, use the +@samp{--block-size=@var{blocking-factor}} (@samp{-b +@var{blocking-factor}) option. Each block will then be composed of +@var{blocking-factor} records. (Each @code{tar} record is 512 bytes. +@xref{Archive Format}.) Each file written to the archive uses at least +one full block. As a result, using a larger block size can result in +more wasted space for small files. On the other hand, a larger block +size can ofter be read and written much more efficiently. + +Further complicating the problem is that some tape drives ignore the +blocking entirely. For these, a larger block size can still improve +performance (because the software layers above the tape drive still +honor the blocking), but not as dramatically as on tape drives that +honor blocking. + +Wher reading an archive, @code{tar} can usually figure out the block +size on itself. When this is the case, and a non-standard block size +was used when the archive was created, @code{tar} will print a message +about a non-standard blocking factor, and then operate normally. On +some tape devices, however, @code{tar} cannot figure out the block size +itself. On most of those, you can specify a blocking factor (with +@samp{--block-size) larger than the actual blocking factor, and then use +the @samp{--read-full-blocks} option. (If you specify a blocking factor +with @samp{--block-size} and don't use the @samp{--read-full-blocks} +option, then @code{tar} will not attempt to figure out the blocking size +itself.) On some devices, you must always specify the block size +exactly with @samp{--block-size} when reading, because @code{tar} cannot +figure it out. In any case, use @samp{--list} before doing any +extractions to see whether @code{tar} is reading the archive correctly. + +If you use a blocking factor larger than 20, older @code{tar} programs +might not be able to read the archive, so we recommend this as a limit +to use in practice. GNU @code{tar}, however, will support arbitrarily +large block sizes, limited only by the amount of virtual memory or the +physical characteristics of the tape device. + +If you are writing a compressed archive to tape with @samp{--compress} +or @samp{--gzip} (@pxref{Input and Output}), @code{tar} will not block +the archive correctly. This doesn't matter if you are writing the +archive to a normal file or through a pipe, but if you are writing it to +a tape drive, then this causes problems. Use @samp{--compress-block} or +@samp{--gzip-block} instead, to cause @code{tar} to arrange to have +blocking work correctly. + +@section Using Multiple Tapes + +Often you might want to write a large archive, one larger than will fit +on the actual tape you are using. In such a case, you can run multiple +@code{tar} commands, but this can be inconvenient, particularly if you +are using options like @samp{--exclude} or dumping entire filesystems. +Therefore, @code{tar} supports multiple tapes automatically. + +Use @samp{--multi-volume} on the command line, and then @code{tar} will, +when it reaches the end of the tape, prompt for another tape, and +continue the archive. Each tape will have an independent archive, and +can be read without needing the other. (As an exception to this, the +file that @code{tar} was archiving when it ran out of tape will usually +be split between the two archives; in this case you need to extract from +the first archive, using @samp{--multi-volume}, and then put in the +second tape when prompted, so @code{tar} can restore both halves of the +file.) + +When prompting for a new tape, @code{tar} accepts any of the following +responses: + +@table @samp +@item ? +Request @code{tar} to explain possible responses +@item q +Request @code{tar} to exit immediately. +@item n @var{file-name} +Request @code{tar} to write the next volume on the file @var{file-name}. +@item ! +Request @code{tar} to run a subshell. +@item y +Request @code{tar} to begin writing the next volume. +@end table + +(You should only type @samp{y} after you have changed the tape; +otherwise @code{tar} will write over the volume it just finished.) + +If you want more elaborate behavior than this, give @code{tar} the +@samp{--info-script=@var{script-name}} option. The file +@var{script-name} is expected to be a program (or shell script) to be +run instead of the normal prompting procedure. When the program +finishes, @code{tar} will immediately begin writing the next volume. +(The behavior of the @samp{n} response to the normal tape-change prompt +is not available if you use @samp{--info-script}.) + +The method @code{tar} uses to detect end of tape is not perfect, and +fails on some operating systems or on some devices. You can use the +@samp{--tape-length=@var{size}} (or @samp{-L @var{size}}) option if +@code{tar} can't detect the end of the tape itself. The @var{size} +argument should be the size of the tape. + +The volume number used by @code{tar} in its tape-change prompt can be +changed; if you give the @samp{--volno-file=@var{file-name}} option, +then @var{file-name} should contain a decimal number. That number will +be used as the volume number of the first volume written. When +@code{tar} is finished, it will rewrite the file with the now--current +volume number. (This does not change the volume number written on a +tape label (@pxref{Special Options for Archiving}; it @emph{only} +affects the number used in the prompt.) + +If you want @code{tar} to cycle through a series of tape drives, then +you can use the @samp{n} response to the tape-change prompt. This is +error prone, however, and doesn't work at all with @samp{--info-script}. +Therefore, if you give @code{tar} multiple @samp{--file} options, then +the specified files will be used, in sequence, as the successive volumes +of the archive. Only when the first one in the sequence needs to be +used again will @code{tar} prompt for a tape change (or run the info +script). + +@section Tape Files + +When @code{tar} writes an archive to tape, it creates a single tape +file. If multiple archives are written to the same tape, one after the +other, they each get written as separate tape files. When extracting, +it is necessary to position the tape at the right place before running +@code{tar}. To do this, use the @code{mt} command. For more +information on the @code{mt} command and on the organization of tapes +into a sequence of tape files, see XXX. + +@chapter Special Options for Archiving + +To give the archive a name which will be recorded in it, use the +@samp{--label=@var{volume-label}} (or @samp{-V}) option. This will +write a special record identifying @var{volume-label} as the name of the +archive to the front of the archive which will be displayed when the +archive is listed with @samp{--list}. If you are creating a +multi-volume archive with @samp{--multi-volume} (@pxref{Using Multiple +Tapes}), then the volume label will have @same{ Volume @var{nnn}} +appended to the name you give, where @var{nnn} is the number of the +volume of the archive. (If you use the @samp{--label} option when +reading an archive, it checks to make sure the label on the tape matches +the one you give. @xref{Special Options for Archiving}.) + +Files in the filesystem occasionally have ``holes.'' A hole in a file +is a section of the file's contents which was never written. The +contents of a hole read as all zeros. On many operating systems, actual@c +disk storage is not allocated for holes, but they are counted in the +length of the file. If you archive such a file, @code{tar} could create +an archive longer than the original. To have @code{tar} attempt to +recognize the holes in a file, use @samp{--sparse}. When you use the +@samp{--sparse} option, then, for any file using less disk space than +would be expected from its length, @code{tar} searches the file for +consecutive stretches of zeros. It then records in the archive for the +file where the consecutive stretches of zeros are, and only archives the +``real contents'' of the file. On extraction (using @samp{--sparse} is +not needed on extraction) any such files have hols created wherever the +continuous stretches of zeros were found. Thus, if you use +@samp{--sparse}, @code{tar} archives won't take more space than the +original. + +When @code{tar} reads files, this causes them to have the access times +updated. To have @code{tar} attempt to set the access times back to +what they were before they were read, use the @samp{--atime-preserve} +option. This doesn't work for files that you don't own, unless you're +root, and it doesn't interact with incremental dumps nicely +(@pxref{Making Backups}), but it is good enough for some purposes. + +@chapter Special Options for Reading Archives + + + + + + + + XXXX MIB XXXX