X-Git-Url: https://git.dogcows.com/gitweb?a=blobdiff_plain;f=doc%2Ftar.texi;h=ab7c1b5c0a61657676c695cc5123e3868c32d641;hb=05b84a0990b40c36b9799ec7e37731492cba8ff1;hp=f55ea78873097d3a31511bf1cd0ffc29ff2ac35e;hpb=3112b152e66ed563ecbcca763ccd458b529ec208;p=chaz%2Ftar diff --git a/doc/tar.texi b/doc/tar.texi index f55ea78..ab7c1b5 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,188 +76,13 @@ 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 - -@node Invoking @code{tar}, Tutorial, Introduction, Top -@chapter How To Invoke @code{tar} - -The usual way to invoke tar is - -@example -@code{tar} @var{options}... [@var{file-names}...] -@end example - -All the options start with @samp{-}. The arguments which do not start -with @samp{-} are taken to be file-name arguments. (But -@xref{Argument Form}.) You can actually type in arguments in any -order. In this manual the options always precede the file-name -arguments, to make examples easier to understand. - -@menu -* Option Form:: The Forms of Arguments -* Argument Functions:: The Functions of Arguments -* Old Syntax for Commands:: An Old, but Still Supported, Syntax - for @code{tar} Commands -@end menu - -@node Option Form, Old Syntax for Commands, Argument Functions, Invoking @code{tar} -@section The Forms of Arguments - -Most options of @code{tar} have a single letter form (a single letter -preceded by @samp{-}), and at least one mnemonic form (a word or -abbreviation preceded by @samp{--}). The forms are absolutely -identical in function. For example, you can use either @samp{tar -t} -or @samp{tar --list} to list the contents of an archive. In addition, -mnemonic names can be given unique abbreviations. For example, -@samp{--cre} can be used in place of @samp{--create} because there is -no other option which begins with @samp{cre}. - -Some options require an additional argument. Single letter options -which require arguments use the immediately following argument. (This -is an exception to the rule that @code{tar} arguments which are not -options are file-name arguments.) 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. In fact, @samp{-C} requires a further argument (the name -of the directory which to change to). In this case, tar would think -it needs to change to a directory named @samp{--file=george}, and -wouldn't interpret @samp{--file-george} as an option at all! - -@node Argument Functions, Argument Form, Invoking @code{tar}, Invoking @code{tar} -@section The Functions of Arguments - -You must give exactly one option from the following list to tar. This -option specifies the basic operation for tar to perform. - -@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}) - -@item -Add archives to another archive (@samp{--add-archive}, @samp{--catenate} -or @samp{-A}) -@c was --concatenate. -ringo - -@item -Create a new archive (@samp{--create} or @samp{-c}) - -@item -Delete files from an archive (@samp{--delete}) - -@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. - -The remaining options to @code{tar} change details of the operation, -such as archive format, archive name, or level of user interaction. -You can specify more than one option. - -The remaining arguments are file-name arguments. For --add-file and ---create these arguments specify the names of files (which must -already exist) to place in the archive. For the remaining operation -types, the file-name arguments specify archive members to compare, -delete, extract, list, or update. When naming archive members, you -must give the exact name of the member in the archive. When naming -files, the normal file name rules apply. - -If you don't use any file-name arguments, @samp{--add-file}, -@samp{--update} and @samp{--delete} will do nothing. Naturally, -@samp{--create} will make an empty archive if given no file-name -arguments. The other operations of @code{tar} will act on defaults. - -Anytime you use a file-name argument to specify a directory file, -@code{tar} acts recursively on all the files and directories beneath -that directory. - -@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 require additional arguments into -two parts. That syntax is of the form: - -@example -@code{tar} @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}. - -On the other hand, this old style syntax makes it difficult to match -option letters with their corresponding arguments, and is often -confusing. In the command @samp{tar cvbf 20 /dev/rmt0}, for example, -@samp{20} is the argument for @samp{-b}, @samp{/dev/rmt0} is the -argument for @samp{-f}, and @samp{-v} does not have a corresponding -argument. The modern syntax---@samp{tar -c -v -b 20 -f -/dev/rmt0}---is clearer. - -@node Tutorial, Wizardry, Invoking @code{tar}, Top -@chapter Getting Started With @code{tar} +@chapter Tutorial Introduction to @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. +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 @@ -290,924 +94,938 @@ typical shell prompt. * Deleting Files:: Deleting Files From an Archive @end menu -@node Creating Archives, Listing Archive Contents, Tutorial, Tutorial -@section Creating Archives +@section What @code{tar} Does + +The @code{tar} program is used to create and manipulate @code{tar} +archives. An @dfn{archive} is a single file which contains within it +the contents of many files. In addition, the archive identifies the +names of the files, their owner, and so forth. + +You can use @code{tar} archives in many ways. Initially, @code{tar} +archives were used to store files conveniently on magnetic tape. The +name @samp{tar} comes from this use; it stands for Tape ARchiver. +Often, @code{tar} archives are used to store related files for +convenient file transfer over a network. For example, the GNU Project +distributes its software bundled into @code{tar} archives, so that all +the files relating to a particular program (or set of related programs) +can be transferred as a single unit. + +The files inside an archive are called @dfn{members}. Within this +manual, we use the term @dfn{file} to refer only to files accessible in +the normal ways (by @code{ls}, @code{cat}, and so forth), and the term +@dfn{members} to refer only to the members of an archive. Similarly, a +@dfn{file name} is the name of a file, as it resides in the filesystem, +and a @dfn{member name} is the name of an archive member within the +archive. -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. +The @code{tar} program provides the ability to create @code{tar} +archives, as well as for various other kinds of manipulation. The term +@dfn{extraction} is used to refer to the process of copying an archive +member into a file in the filesystem. One might speak of extracting a +single member. Extracting all the members of an archive is often called +extracting the archive. Often the term @dfn{unpack} is used to refer to +the extraction of many or all the members of an archive. -@menu -* Creating Example:: Creating Archives of Files -* Subdirectory:: Creating an Archive of a Subdirectory -@end menu +Conventionally, @code{tar} archives are given names ending with +@samp{.tar}. This is not necessary for @code{tar} to operate properly, +but this manual follows the convention in order to get the reader used +to seeing it. -@node Creating Example, Subdirectory, Creating Archives, Creating Archives -@subsection Creating Archives of Files +Occasionally archive members are referred to as files. For people +familiar with the operation of @code{tar}, this causes no difficulty. +However, this manual consistently uses the terminology above in +referring to files and archive members, to make it easier to learn how +to use @code{tar}. -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. +@section How to Create Archives -(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: +To create a new archive, use @samp{tar --create}. You should generally +use the @samp{--file} option to specify the name the tar archive will +have. Then specify the names of the files you wish to place in the new +archive. For example, to place the files @file{apple}, @file{angst}, +and @file{asparagus} into an archive named @file{afiles.tar}, use the +following command: @example -% cd practice +tar --create --file=afiles.tar apple angst asparagus @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: +The order of the arguments is not important. You could also say: @example -% ls +tar apple --create angst --file=afiles.tar asparagus @end example -The system responds: +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. -@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 +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: -@noindent -Type: @example -% tar --create --file=records blues folk jazz +tar --create --file=empty-archive.tar @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. +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. -@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: +When @samp{tar --create} creates an archive, the member names of the +members of the archive are exactly the same as the file names as you +typed them in the @code{tar} command. So, the member names of +@file{afiles} (as created by the first example above) are @file{apple}, +@file{angst}, and @file{asparagus}. However, suppose an archive were +created with this command: @example -% tar --list --file=records +tar --create --file=bfiles.tar ./balloons baboon ./bodacious @end example -@noindent -@code{tar} will respond: - -@example -blues folk jazz -@end example +Then, the three files @file{balloons}, @file{baboon}, and +@file{bodacious} would get placed in the archive (because @file{./} is a +synonym for the current directory), but their member names would be +@file{./balloons}, @file{baboon}, and @file{./bodacious}. -@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. +If you want to see the progress of tar as it writes files into the +archive, you can use the @samp{--verbose} option. -@node Verbose, , Listing Files, Creating Example -@subsubsection Using @code{tar} in Verbose Mode +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. -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) +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 --create --file=records --verbose blues folk jazz -blues -folk -jazz +tar: can't open /dev/rmt8 : No such device or address +tar: can't open /dev/rsmt0 : I/O error @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 +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. -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 +@section How to List Archives -To archive a directory, first move to its superior directory. If you -have been following the tutorial, you should type: +Use @samp{tar --list} to print the names of members stored in an +archive. Use a @samp{--file} option just as with @samp{tar --create} to +specify the name of the archive. For example, the archive +@file{afiles.tar} created in the last section could be examined with the +command @samp{tar --list --file=afiles.tar}. The output of tar would +then be: @example -% cd .. -% +apple +angst +asparagus @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: +The archive @file{bfiles.tar} would list as follows: @example -% tar --create --verbose --file=music practice +./baloons +baboon +./bodacious @end example -@noindent -@code{tar} should respond: +(Of course, @samp{tar --list --file=empty-archive.tar} would produce no +output.) -@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 +On the other hand, this old style syntax makes it difficult to match +option letters with their corresponding arguments, and is often +confusing. In the command @samp{tar cvbf 20 /dev/rmt0}, for example, +@samp{20} is the argument for @samp{-b}, @samp{/dev/rmt0} is the +argument for @samp{-f}, and @samp{-v} does not have a corresponding +argument. The modern syntax---@samp{tar -c -v -b 20 -f +/dev/rmt0}---is clearer. -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. +@chapter Basic @code{tar} Operations -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. +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. -@menu -* Append:: Appending Files to an Archive -* Update:: Updating Files in an Archive -@end menu +@section Creating a New Archive -@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 +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. -@noindent -For example: +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}. -@example -% tar --add-file --file=records rock -@end example +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. -@noindent -If you list the archive members in @file{records}, you will see that -@file{rock} has been added to the archive: +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}.) -@example -% tar --list --file=records -blues -folk -jazz -rock -@end example +There are various ways of causing @code{tar} to skip over some files, +and not archive them. @xref{Specifying Names to @code{tar}}. -@c <<< this should be some kind of node. +@section Adding to an Existing Archive -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. +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. -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}: +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}. -@example -% tar --add-file --verbose --file=records blues -blues -@end example +This operation cannot be performed on some tape drives, unfortunately, +due to deficiencies in the formats thoes tape drives use. -@noindent -If you now list the contents of the archive, you will obtain the following: +@section Combining Archives -@example -% tar --list -f records -blues -folk -jazz -rock -blues -@end example +The @samp{--catenate} (or @code{--concatenate}, or @code{-A}) causes +@code{tar} to add the contents of several archives to an existing +archive. -@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: +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}. -@example -% tar --update --verbose --file=records blues folk rock classical -blues -classical -% -@end example +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. -@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 +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 +default takes the names of the files from the command line. There are +other ways, however, to specify file or member names, or to modify the +manner in which @code{tar} selects the files or members upon which to +operate. In general, these methods work both for specifying the names +of files and archive members. + +@section Reading Names from a File + +Instead of giving the names of files or archive members on the command +line, you can put the names into a file, and then use the +@samp{--files-from=@var{file-name-list}} (@samp{-T +@var{file-name-list}}) option to @code{tar}. Give the name of the file +which contains the list as the argument to @samp{--files-from}. The +file names should be separated by newlines in the list. 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 +characters (ASCII 000) instead of newlines. In addition, the +@samp{--null} option turns off the @samp{-C} option (@pxref{Changing +Directory}). + +@section Excluding Some Files + +The @samp{--exclude=@var{pattern}} option will prevent any file or +member which matches the regular expression @var{pattern} from being +operated on. For example, if you want to create an archive with all the +contents of @file{/tmp} except the file @file{/tmp/foo}, you can use the +command @samp{tar --create --file=arch.tar --exclude=foo}. + +If there are many files you want to exclude, you can use the +@samp{--exclude-from=@var{exclude-list}} (@samp{-X @var{exclude-list}}) +option. This works just like the +@samp{--files-from=@var{file-name-list}} option: specify the name of a +file as @var{exclude-list} which contains the list of patterns you want +to exclude. + +@xref{Regular Expressions} for more information on the syntax and +meaning of regular expressions. + +@section Operating Only on New Files + +The @samp{--newer=@var{date}} (@samp{--after-date=@var{date}} or +@samp{-N @var{date}}) limits @code{tar} to only operating on files which +have been modified after the date specified. (For more information on +how to specify a date, @xref{Date Formats}.) A file is considered to +have changed if the contents have been modified, or if the owner, +permissions, and so forth, have been changed. + +If you only want @code{tar} make the date comparison on the basis of the +actual contents of the file's modification, then use the +@samp{--newer-mtime=@var{date}} option. + +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}.) + +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. + +@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. + +@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 (@pxref{Making @code{tar} More Verbose}) +causes @code{tar} to print the name of each file or archive member as it +is processed. + +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. + +@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: -@example -% cd ~ -% tar --concatenate --file=music practice/records -@end example +@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 -If you now list the contents of the @file{music}, you see it now -contains the archive members of @file{practice/records}: +(You should only type @samp{y} after you have changed the tape; +otherwise @code{tar} will write over the volume it just finished.) -@example -%tar --list --file=music -blues -folk -jazz -rock -blues -practice/blues -practice/folk -practice/jazz -practice/rock -practice/blues -practice/classical -@end example +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}.) -@node Deleting Files, , , Tutorial -@comment node-name, next, previous, up -@section Deleting Files From an Archive +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. -In some instances, you may want to remove some files from an archive -stored on disk +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; it @emph{only} affects the number used in the prompt.) -@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 +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). -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. +XXXX MIB XXXX -@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