From: François Pinard Date: Wed, 16 Nov 1994 02:51:47 +0000 (+0000) Subject: *** empty log message *** X-Git-Url: https://git.dogcows.com/gitweb?a=commitdiff_plain;h=9e95900ce7813c06b3a330267428266aec39ef0e;p=chaz%2Ftar *** empty log message *** --- diff --git a/doc/tar.texi b/doc/tar.texi index f55ea78..e82ab98 100644 --- a/doc/tar.texi +++ b/doc/tar.texi @@ -124,6 +124,245 @@ useful if redirected another program with a pipe.) * Problems:: Common problems with @code{tar}. @end menu +@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. If you already know how to use some other version of +@code{tar}, then you probably don't need to read this chapter. This +chapter omits complicated details about many of the ways @code{tar} +works. See later chapters for full information. + +@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 @samp{tar --create}. You should generally +use the @samp{--file} option to specify the name the tar archive will +have. Then specify the names of the files you wish to place in the +archive. For example, to place the files @file{foo}, @file{bar}, and +@file{baz} into an archive named @file{my-archive}, use the following +command: + +@example +tar --create --file=my-archive foo bar baz +@end example + +The order of the arguments is not important. You could also say: + +@example +tar foo --create --file=my-archive bar baz +@end example + +This order is harder to understand however. In this manual, we will +list the arguments in a reasonable order to make the commands easier to +understand, but you can type them in any order you wish. + +If you don't specify the @samp{--file} option, then @code{tar} will use +a default. Usually this default is some physical tape drive attached to +your machine. If there is no tape drive attached, or the default is not +meaningful, then tar will print an error message. This error message +might look roughly like one of the following: + +@example +tar: can't open /dev/rmt8 : No such device or address +tar: can't open /dev/rsmt0 : I/O error +@end example + +If you get an error like this, mentioning a file you didn't specify +(@file{/dev/rmt8} or @file{/dev/rsmt0} in the examples above), then @code{tar} +is using a default value for @samp{--file}. You should generally specify a +@samp{--file} argument whenever you use @code{tar}, rather than relying +on a default. + +If you don't specify the names of any files to put in the archive, then +tar will create an empty archive. So, the following command will create +an archive with nothing in it: + +@example +tar --create --file=my-empty-archive +@end example + +Whenever you use @samp{tar --create}, @code{tar} will erase the current +contents of the file named by @samp{--file} if it exists. To add files +to an existing archive, you need to use a different option. +@xref{Adding to Archives} for information on how to do this. + +The names of the members of an archive are called @dfn{member names}. +When @samp{tar --create} creates an archive, the member names of the +members of the archive are exactly the same as the file names as you +typed them in the @code{tar} command. So, the member names of +@file{my-archive} (as created by the first example above) are +@file{foo}, @file{bar}, and @file{baz}. However, suppose the archive +were created with this command instead: + +@example +tar --create --file=my-new-archive ./foo bar ./baz +@end example + +Then, the same three files would get placed in the archive (because +@file{./} is a synonym for the current directory), but their member +names would now be @file{./foo}, @file{bar}, and @file{./baz}. + +If you want to see the progress of tar as it writes files into the +archive, you can use the @samp{--verbose} option. + +If one of the files named to @samp{tar --create} is a directory, then +the operation of tar is more complicated. @xref{Tar and Directories}, +the last section of this tutorial, for more information. + +@section Listing 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 +specify the name of the archive. For example, the archive +@file{my-archive} created in the last section could be examined with the +command @samp{tar --list --file=my-archive}. The output of tar would +then be: + +@example +foo +bar +baz +@end example + +The archive @file{my-new-archive} would list as follows: + +@example +./foo +bar +./baz +@end example + +Note that, despite the identical contents of the two archives' members, +the member names are different. (Of course, @samp{tar --list +--file=my-empty-archive} would produce no output.) + +If you use the @samp{--verbose} option with @samp{tar --list}, then tar +will print out a listing reminiscent of @samp{ls -l}, showing owner, +file size, and so forth. + +You can also specify member names when using @samp{tar --list}. In this +case, tar will only list the names of members you identify. For +example, @samp{tar --list --file=my-archive foo} would only print +@samp{foo}. It is essential when specifying member names to tar that +you give the exact member names. For example, @samp{tar --list +--file=my-new-archive foo} would produce no output, because there is no +member named @file{foo}, only one named @file{./foo}. While the file +names @file{foo} and @file{./foo} name the same file, member names are +compared using a simplistic name comparison, in which an exact match is +necessary. + +@section Extracting Files from an Archive + +In order to extract files from an archive, use @samp{tar --extract}. +Specify the name of the archive with @samp{--file}. To extract specific +archive members, give their member names as arguments. It essential to +give their exact member name, as printed by @samp{tar --list}. + +Keeping the example of the two archives created at the beginning of this +tutorial, @samp{tar --extract --file=my-archive foo} would create a file +@file{foo} in the current directory with the contents of the archive +member @file{foo}. It would remove any file named @file{foo} already +present in the directory, but it would not change the archive in any +way. + +Remember that specifying the exact member name is important. @samp{tar +--extract --file=my-new-archive foo} will fail, because there is no +member named @file{foo}. To extract the member named @file{./foo} you +would need to specify @samp{tar --extract --file=my-new-archive ./foo}. +To find the exact member names of the members of an archive, use +@samp{tar --list}. @xref{Listing Archives}. + +If you do not list any archive member names, then @samp{tar --extract} +will extract all the members of the archive. + +If you give the @samp{--verbose} option, then @samp{tar --extract} will +print the names of the archive members as it extracts them. + +@section Adding Files to Existing Archives + +If you want to add files to an existing archive, then don't use +@samp{tar --create}. That will erase an archive and create a new one in +its place. Instead, use @samp{tar --add-file}. The command @samp{tar +--add-file --file=my-archive qux} would add the file @file{qux} to the +existing archive @file{my-archive}. It is essential that the archive +exist already in order to use @samp{tar --add-file}. + +As with @samp{tar --create}, the member names of the newly added files +will be the exact same as their names given on the command line. The +@samp{--verbose} option will print out the names of the files as they +are written into the archive. + +If you add a file to an archive using @samp{tar --add-file} with the +same name as an archive member already present in the archive, then the +old member is not deleted. What does happen, however, is somewhat +complex. @xref{Multiple Members with the Same Name}. If you want to +replace an archive member, use @samp{tar --delete} first, and then use +@samp{tar --add-file}. + +@section Deleting Files from Archives + +You can delete files from an archive using @samp{tar --delete}. Specify +the name of the archive with @samp{--file}. List the member names of +the files to be deleted. If you list no member names, then nothing will +be deleted. The @samp{--verbose} option will cause @code{tar} to print +the names of the members as they are deleted. As with @samp{tar +--extract}, it is important that you give the exact member names when +using @samp{tar --delete}. Use @samp{tar --list} to find out the exact +member names in an archive (@pxref{Listing Archives}). + +The @samp{tar --delete} command only works with archives stored on disk. +Archives stored on a tape drive cannot be deleted from. + +@section Directories + +When the names of files or member names specify directories, the +operation of @code{tar} is more complex. Generally, when a directory is +named, @code{tar} also operates on all the contents of the directory, +recursively. Thus, to @code{tar}, the file name @file{/} names the +entire file system. + +To archive the entire contents of a directory, use @samp{tar --create} +(or @samp{tar --add-file}) as usual, and specify the name of the +directory. For example, to archive all the contents of the current +directory, use @samp{tar --create --file=@var{archive-name} .}. Doing +this will give the archive members names starting with @samp{./}. To +archive the contents of a directory named @file{foodir}, use @samp{tar +--create --file=@var{archive-name} foodir}. In this case, the member +names will all start with @samp{foodir/}. + +If you give @code{tar} a command such as @samp{tar --create --file=foo +.}, it will report @samp{tar: foo is the archive; not dumped}. This +happens because the archive @file{foo} is created before putting any +files into it. Then, when @code{tar} attempts to add all the files in +the directory @file{.} to the archive, it notices that the file +@file{foo} is the same as the archive, and skips it. (It makes no sense +to put an archive into itself.) GNU @code{tar} will continue in this +case, and create the archive as normal, except for the exclusion of that +one file. Other versions of @code{tar}, however, are not so clever, and +will enter an infinite loop when this happens, so you should not depend +on this behavior. In general, make sure that the archive is not inside +a directory being dumped. + +When extracting files, you can also name directory archive members on +the command line. In this case, @code{tar} extracts all the archive +members whose names begin with the name of the directory. As usual, +@code{tar} is not particularly clever about interpreting member names. +The command @samp{tar --extract --file=@var{archive-name} .} will not +extract all the contents of the archive, but only those members whose +member names begin with @samp{./}. + + @node Invoking @code{tar}, Tutorial, Introduction, Top @chapter How To Invoke @code{tar} @@ -271,944 +510,6 @@ 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. If you already know how to use some other version of tar, -then you probably don't need to read this chapter. In the examples, -the lines you should type are preceded by a @samp{%}, which is a -typical shell prompt. - -@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