X-Git-Url: https://git.dogcows.com/gitweb?a=blobdiff_plain;f=doc%2Ftar.texi;h=1814bff43a1b7dae5c7cdd76e93fd01654994791;hb=78b078b455b834695ebd3104ec3dbe8a4ac9f3a3;hp=2798e63c1e75ef96120e58b965099b92448be285;hpb=b272b3e2cfa0090936bc21361e2ef46878b14190;p=chaz%2Ftar diff --git a/doc/tar.texi b/doc/tar.texi index 2798e63..1814bff 100644 --- a/doc/tar.texi +++ b/doc/tar.texi @@ -20,7 +20,6 @@ @syncodeindex vr cp @defindex op -@syncodeindex op cp @copying @@ -29,7 +28,7 @@ This manual is for @acronym{GNU} @command{tar} (version from archives. Copyright @copyright{} 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001, -2003, 2004 Free Software Foundation, Inc. +2003, 2004, 2005, 2006 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -97,9 +96,13 @@ document. The rest of the menu lists all the lower level nodes. Appendices +* Changes:: +* Configuring Help Summary:: * Genfile:: +* Snapshot Files:: * Free Software Needs Free Documentation:: * Copying This Manual:: +* Index of Command Line Options:: * Index:: @detailmenu @@ -111,7 +114,6 @@ Introduction * Definitions:: Some Definitions * What tar Does:: What @command{tar} Does * Naming tar Archives:: How @command{tar} Archives are Named -* Current status:: Current development status of @GNUTAR{} * Authors:: @GNUTAR{} Authors * Reports:: Reporting bugs or suggestions @@ -159,6 +161,7 @@ Invoking @GNUTAR{} * Styles:: * All Options:: * help:: +* defaults:: * verbose:: * interactive:: @@ -226,7 +229,7 @@ Changing How @command{tar} Writes Files * Keep Newer Files:: * Unlink First:: * Recursive Unlink:: -* Modification Times:: +* Data Modification Times:: * Setting Access Permissions:: * Writing to Standard Output:: * remove files:: @@ -239,8 +242,7 @@ Coping with Scarce Resources Performing Backups and Restoring Files * Full Dumps:: Using @command{tar} to Perform Full Dumps -* Inc Dumps:: Using @command{tar} to Perform Incremental Dumps -* incremental and listed-incremental:: The Incremental Options +* Incremental Dumps:: Using @command{tar} to Perform Incremental Dumps * Backup Levels:: Levels of Backups * Backup Parameters:: Setting Parameters for Backups and Restoration * Scripted Backups:: Using the Backup Scripts @@ -262,7 +264,7 @@ Choosing Files and Names for @command{tar} * Wildcards:: * after:: Operating Only on New Files * recurse:: Descending into Directories -* one:: Crossing Filesystem Boundaries +* one:: Crossing File System Boundaries Reading Names from a File @@ -270,10 +272,10 @@ Reading Names from a File Excluding Some Files -* controlling pattern-patching with exclude:: +* controlling pattern-matching with exclude:: * problems with exclude:: -Crossing Filesystem Boundaries +Crossing File System Boundaries * directory:: Changing Directory * absolute:: Absolute File Names @@ -339,13 +341,16 @@ Using Multiple Tapes * Multi-Volume Archives:: Archives Longer than One Tape or Disk * Tape Files:: Tape Files +* Tarcat:: Concatenate Volumes into a Single Archive -GNU tar test suite +GNU tar internals and development * Genfile:: +* Snapshot Files:: Copying This Manual +* Free Software Needs Free Documentation:: * GNU Free Documentation License:: License for copying this manual @end detailmenu @@ -366,7 +371,6 @@ archives need not (and these days, typically do not) reside on tapes. * Definitions:: Some Definitions * What tar Does:: What @command{tar} Does * Naming tar Archives:: How @command{tar} Archives are Named -* Current status:: Current development status of @GNUTAR{} * Authors:: @GNUTAR{} Authors * Reports:: Reporting bugs or suggestions @end menu @@ -425,7 +429,7 @@ The @command{tar} program is used to create and manipulate @command{tar} archives. An @dfn{archive} is a single file which contains the contents of many files, while still identifying the names of the files, their owner(s), and so forth. (In addition, archives record access -permissions, user and group, size in bytes, and last modification time. +permissions, user and group, size in bytes, and data modification time. Some archives also record the file names in each archived directory, as well as other file and directory information.) You can use @command{tar} to @dfn{create} a new archive in a specified directory. @@ -438,14 +442,14 @@ 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 @command{ls}, @command{cat}, and so forth), and the term @dfn{member} 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, +@dfn{file name} is the name of a file, as it resides in the file system, and a @dfn{member name} is the name of an archive member within the archive. @cindex extraction @cindex unpacking The term @dfn{extraction} refers to the process of copying an archive -member (or multiple members) into a file in the filesystem. Extracting +member (or multiple members) into a file in the file system. Extracting all the members of an archive is often called @dfn{extracting the archive}. The term @dfn{unpack} can also be used to refer to the extraction of many or all the members of an archive. Extracting an @@ -509,7 +513,7 @@ projects) together on a disk or a tape. This guards against accidental destruction of the information in those files. @GNUTAR{} has special features that allow it to be used to make incremental and full dumps of all the files in a -filesystem. +file system. @item Transportation You can create an archive on one system, transfer it to another system, @@ -534,63 +538,6 @@ the operation of @command{tar}, this causes no difficulty. However, in this manual, we consistently refer to ``archives'' and ``archive members'' to make learning to use @command{tar} easier for novice users. -@node Current status -@section Current development status of @GNUTAR{} - -@GNUTAR{} is currently in the process of active development, whose -primary aims are: - -@itemize @bullet -@item Improve compatibility between @GNUTAR{} and other @command{tar} -implementations. -@item Switch to using @acronym{POSIX} archives. -@item Revise sparse file handling and multiple volume processing. -@item Merge with the @acronym{GNU} @code{paxutils} project. -@end itemize - -Some of these aims are already attained, while others are still -being worked upon. From the point of view of an end user, the -following issues need special mentioning: - -@table @asis -@item Use of short option @option{-o}. - -Earlier versions of @GNUTAR{} understood @option{-o} command line -option as a synonym for @option{--old-archive}. - -@GNUTAR{} starting from version 1.13.90 understands this option as -a synonym for @option{--no-same-owner}. This is compatible with -UNIX98 @command{tar} implementations. - -However, to facilitate transition, @option{-o} option retains its -old semantics when it is used with one of archive-creation commands. -Users are encouraged to use @value{op-format-oldgnu} instead. - -It is especially important, since versions of @acronym{GNU} Automake -up to and including 1.8.4 invoke tar with this option to produce -distribution tarballs. @xref{Formats,v7}, for the detailed discussion -of this issue and its implications. - -Future versions of @GNUTAR{} will understand @option{-o} only as a -synonym for @option{--no-same-owner}. - -@item Use of short option @option{-l} - -Earlier versions of @GNUTAR{} understood @option{-l} option as a -synonym for @option{--one-file-system}. Such usage is deprecated. -For compatibility with other implementations future versions of -@GNUTAR{} will understand this option as a synonym for -@option{--check-links}. - -@item Use of options @option{--portability} and @option{--old-archive} - -These options are deprecated. Please use @option{--format=v7} instead. - -@item Use of option @option{--posix} - -This option is deprecated. Please use @option{--format=posix} instead. -@end table - @node Authors @section @GNUTAR{} Authors @@ -690,7 +637,7 @@ about how Unix-type operating systems work, and you should know how to use some basic utilities. For example, you should know how to create, list, copy, rename, edit, and delete files and directories; how to change between directories; and how to figure out where you are in the -filesystem. You should have some basic understanding of directory +file system. You should have some basic understanding of directory structure and how files are named according to which directory they are in. You should understand concepts such as standard output and standard input, what various definitions of the term ``argument'' mean, and the @@ -762,10 +709,10 @@ corresponding abbreviations. @FIXME{make sure this is still the case, at the end}We will indicate those abbreviations appropriately to get you used to seeing them. (Note that the ``old style'' option forms exist in @GNUTAR{} for compatibility with Unix -@command{tar}. We present a full discussion of this way of writing -options and operations appears in @ref{Old Options}, and we discuss -the other two styles of writing options in @ref{Mnemonic Options}, and -@ref{Short Options}.) +@command{tar}. In this book we present a full discussion of this way +of writing options and operations (@pxref{Old Options}), and we discuss +the other two styles of writing options (@xref{Mnemonic Options}, and +@pxref{Short Options}). In the examples and in the text of this tutorial, we usually use the long forms of operations and options; but the ``short'' forms produce @@ -852,20 +799,27 @@ useful in making things more clear and helping you avoid errors.) @unnumberedsubsec The @option{--file} Option @table @option +@opindex file, tutorial @item --file=@var{archive-name} @itemx -f @var{archive-name} Specify the name of an archive file. @end table -You can specify an argument for the @value{op-file} option whenever you +You can specify an argument for the @option{--file=@var{archive-name}} (@option{-f @var{archive-name}}) option whenever you use @command{tar}; this option determines the name of the archive file that @command{tar} will work on. -If you don't specify this argument, then @command{tar} will use a -default, usually some physical tape drive attached to your machine. -If there is no tape drive attached, or the default is not meaningful, -then @command{tar} will print an error message. The error message might -look roughly like one of the following: +@vrindex TAPE +If you don't specify this argument, then @command{tar} will examine +the environment variable @env{TAPE}. If it is set, its value will be +used as the archive name. Otherwise, @command{tar} will use the +default archive, determined at the compile time. Usually it is +standard output or some physical tape drive attached to your machine +(you can verify what the default is by running @kbd{tar +--show-defaults}, @pxref{defaults}). If there is no tape drive +attached, or the default is not meaningful, then @command{tar} will +print an error message. The error message might look roughly like one +of the following: @smallexample tar: can't open /dev/rmt8 : No such device or address @@ -874,20 +828,21 @@ tar: can't open /dev/rsmt0 : I/O error @noindent To avoid confusion, we recommend that you always specify an archive file -name by using @value{op-file} when writing your @command{tar} commands. -For more information on using the @value{op-file} option, see +name by using @option{--file=@var{archive-name}} (@option{-f @var{archive-name}}) when writing your @command{tar} commands. +For more information on using the @option{--file=@var{archive-name}} (@option{-f @var{archive-name}}) option, see @ref{file}. @node verbose tutorial @unnumberedsubsec The @option{--verbose} Option @table @option +@opindex verbose, introduced @item --verbose @itemx -v Show the files being worked on as @command{tar} is running. @end table -@value{op-verbose} shows details about the results of running +@option{--verbose} (@option{-v}) shows details about the results of running @command{tar}. This can be especially useful when the results might not be obvious. For example, if you want to see the progress of @command{tar} as it writes files into the archive, you can use the @option{--verbose} @@ -937,6 +892,7 @@ Later in the tutorial, we will give examples using @w{@option{--verbose @unnumberedsubsec Getting Help: Using the @option{--help} Option @table @option +@opindex help @item --help The @option{--help} option to @command{tar} prints out a very brief list of @@ -948,7 +904,9 @@ all operations and option available for the current version of @section How to Create Archives @UNREVISED -One of the basic operations of @command{tar} is @value{op-create}, which +@cindex Creation of the archive +@cindex Archive, creation of +One of the basic operations of @command{tar} is @option{--create} (@option{-c}), which you use to create a @command{tar} archive. We will explain @option{--create} first because, in order to learn about the other operations, you will find it useful to have an archive available to @@ -1006,16 +964,17 @@ It is very important to make sure there isn't already a file in the working directory with the archive name you intend to use (in this case, @samp{collection.tar}), or that you don't care about its contents. Whenever you use @samp{create}, @command{tar} will erase the current -contents of the file named by @value{op-file} if it exists. @command{tar} +contents of the file named by @option{--file=@var{archive-name}} (@option{-f @var{archive-name}}) if it exists. @command{tar} will not tell you if you are about to overwrite an archive unless you -specify an option which does this. @FIXME{xref to the node for ---backup!}To add files to an existing archive, you need to use a -different option, such as @value{op-append}; see @ref{append} for -information on how to do this. +specify an option which does this (@pxref{backup}, for the +information on how to do so). To add files to an existing archive, +you need to use a different option, such as @option{--append} (@option{-r}); see +@ref{append} for information on how to do this. @node Creating the archive @subsection Creating the Archive +@opindex create, introduced To place the files @file{blues}, @file{folk}, and @file{jazz} into an archive named @file{collection.tar}, use the following command: @@ -1079,14 +1038,16 @@ run and will prompt you for one. If you don't name any files, @command{tar} will complain. You must have write access to the working directory, or else you will not be able to create an archive in that directory. -@emph{Caution}: Do not attempt to use @value{op-create} to add files to +@emph{Caution}: Do not attempt to use @option{--create} (@option{-c}) to add files to an existing archive; it will delete the archive and write a new one. -Use @value{op-append} instead. @xref{append}. +Use @option{--append} (@option{-r}) instead. @xref{append}. @node create verbose @subsection Running @option{--create} with @option{--verbose} -If you include the @value{op-verbose} option on the command line, +@opindex create, using with @option{--verbose} +@opindex verbose, using with @option{--create} +If you include the @option{--verbose} (@option{-v}) option on the command line, @command{tar} will list the files it is acting on as it is working. In verbose mode, the @code{create} example above would appear as: @@ -1114,12 +1075,12 @@ understand. @node short create @subsection Short Forms with @samp{create} -As we said before, the @value{op-create} operation is one of the most +As we said before, the @option{--create} (@option{-c}) operation is one of the most basic uses of @command{tar}, and you will use it countless times. Eventually, you will probably want to use abbreviated (or ``short'') forms of options. A full discussion of the three different forms that options can take appears in @ref{Styles}; for now, here is what the -previous example (including the @value{op-verbose} option) looks like +previous example (including the @option{--verbose} (@option{-v}) option) looks like using short option forms: @smallexample @@ -1185,9 +1146,6 @@ the order of options and placement of file and archive names, especially when using short option forms. Not having the option name written out mnemonically can affect how well you remember which option does what, and therefore where different names have to be placed. -(Placing options in an unusual order can also cause @command{tar} to -report an error if you have set the shell environment variable -@env{POSIXLY_CORRECT}.) @node create dir @subsection Archiving Directories @@ -1236,7 +1194,7 @@ directory from its superior directory, you should make sure you have write access to the superior directory itself, not only the directory you are trying archive with @command{tar}. For example, you will probably not be able to store your home directory in an archive by invoking -@command{tar} from the root directory; @value{xref-absolute-names}. (Note +@command{tar} from the root directory; @xref{absolute}. (Note also that @file{collection.tar}, the original archive file, has itself been archived. @command{tar} will accept any file as a file to be archived, regardless of its content. When @file{music.tar} is @@ -1270,8 +1228,9 @@ directory being dumped.} @node list @section How to List Archives +@opindex list Frequently, you will find yourself wanting to determine exactly what a -particular archive contains. You can use the @value{op-list} operation +particular archive contains. You can use the @option{--list} (@option{-t}) operation to get the member names as they currently appear in the archive, as well as various attributes of the files at the time they were archived. For example, you can examine the archive @file{collection.tar} that you @@ -1303,19 +1262,21 @@ baboon @end smallexample @noindent -Be sure to use a @value{op-file} option just as with @value{op-create} +Be sure to use a @option{--file=@var{archive-name}} (@option{-f @var{archive-name}}) option just as with @option{--create} (@option{-c}) to specify the name of the archive. -If you use the @value{op-verbose} option with @option{--list}, then +@opindex list, using with @option{--verbose} +@opindex verbose, using with @option{--list} +If you use the @option{--verbose} (@option{-v}) option with @option{--list}, then @command{tar} will print out a listing reminiscent of @w{@samp{ls -l}}, showing owner, file size, and so forth. -If you had used @value{op-verbose} mode, the example above would look +If you had used @option{--verbose} (@option{-v}) mode, the example above would look like: @smallexample $ @kbd{tar --list --verbose --file=collection.tar folk} --rw-rw-rw- myself user 62 1990-05-23 10:55 folk +-rw-r--r-- myself user 62 1990-05-23 10:55 folk @end smallexample @cindex listing member and file names @@ -1344,18 +1305,18 @@ etc/mail/aliases @end group @end smallexample -@cindex @option{--show-stored-names} described +@opindex show-stored-names This default behavior can sometimes be inconvenient. You can force @GNUTAR{} show member names when creating archive by supplying @option{--show-stored-names} option. @table @option @item --show-stored-names -Print member (not @emph{file}) names when creating the archive. +Print member (as opposed to @emph{file}) names when creating the archive. @end table @cindex File name arguments, using @option{--list} with -@cindex @option{--list} with file name arguments +@opindex list, using with file name arguments You can specify one or more individual member names as arguments when using @samp{list}. In this case, @command{tar} will only list the names of members you identify. For example, @w{@kbd{tar --list @@ -1390,8 +1351,8 @@ stored in the specified archive. To get information about the contents of an archived directory, use the directory name as a file name argument in conjunction with -@value{op-list}. To find out file attributes, include the -@value{op-verbose} option. +@option{--list} (@option{-t}). To find out file attributes, include the +@option{--verbose} (@option{-v}) option. For example, to find out about files in the directory @file{practice}, in the archive file @file{music.tar}, type: @@ -1404,10 +1365,10 @@ $ @kbd{tar --list --verbose --file=music.tar practice} @smallexample drwxrwxrwx myself user 0 1990-05-31 21:49 practice/ --rw-rw-rw- myself user 42 1990-05-21 13:29 practice/blues --rw-rw-rw- myself user 62 1990-05-23 10:55 practice/folk --rw-rw-rw- myself user 40 1990-05-21 13:30 practice/jazz --rw-rw-rw- myself user 10240 1990-05-31 21:49 practice/collection.tar +-rw-r--r-- myself user 42 1990-05-21 13:29 practice/blues +-rw-r--r-- myself user 62 1990-05-23 10:55 practice/folk +-rw-r--r-- myself user 40 1990-05-21 13:30 practice/jazz +-rw-r--r-- myself user 10240 1990-05-31 21:49 practice/collection.tar @end smallexample When you use a directory name as a file name argument, @command{tar} acts on @@ -1420,18 +1381,20 @@ all the files (including sub-directories) in that directory. @cindex Retrieving files from an archive @cindex Resurrecting files from an archive +@opindex extract Creating an archive is only half the job---there is no point in storing files in an archive if you can't retrieve them. The act of retrieving members from an archive so they can be used and manipulated as unarchived files again is called @dfn{extraction}. To extract files -from an archive, use the @value{op-extract} operation. As with -@value{op-create}, specify the name of the archive with @value{op-file}. -Extracting an archive does not modify the archive in any way; you can -extract it multiple times if you want or need to. +from an archive, use the @option{--extract} (@option{--get} or +@option{-x}) operation. As with @option{--create}, specify the name +of the archive with @option{--file} (@option{-f}) option. Extracting +an archive does not modify the archive in any way; you can extract it +multiple times if you want or need to. Using @option{--extract}, you can extract an entire archive, or specific files. The files can be directories containing other files, or not. As -with @value{op-create} and @value{op-list}, you may use the short or the +with @option{--create} (@option{-c}) and @option{--list} (@option{-t}), you may use the short or the long form of the operation without affecting the performance. @menu @@ -1456,23 +1419,20 @@ $ @kbd{tar -xvf collection.tar} produces this: @smallexample --rw-rw-rw- me user 28 1996-10-18 16:31 jazz --rw-rw-rw- me user 21 1996-09-23 16:44 blues --rw-rw-rw- me user 20 1996-09-23 16:44 folk +-rw-r--r-- me user 28 1996-10-18 16:31 jazz +-rw-r--r-- me user 21 1996-09-23 16:44 blues +-rw-r--r-- me user 20 1996-09-23 16:44 folk @end smallexample @node extracting files @subsection Extracting Specific Files To extract specific archive members, give their exact member names as -arguments, as printed by @value{op-list}. If you had mistakenly deleted +arguments, as printed by @option{--list} (@option{-t}). If you had mistakenly deleted one of the files you had placed in the archive @file{collection.tar} earlier (say, @file{blues}), you can extract it from the archive without -changing the archive's structure. It will be identical to the original -file @file{blues} that you deleted. @FIXME{At the time of this -writing, atime and ctime are not restored. Since this is a tutorial -for a beginnig user, it should hardly be mentioned here. Maybe in -a footnote? --gray}. +changing the archive's structure. Its contents will be identical to the +original file @file{blues} that you deleted. First, make sure you are in the @file{practice} directory, and list the files in the directory. Now, delete the file, @samp{blues}, and list @@ -1487,7 +1447,7 @@ $ @kbd{tar --extract --file=collection.tar blues} @noindent If you list the files in the directory again, you will see that the file -@file{blues} has been restored, with its original permissions, creation +@file{blues} has been restored, with its original permissions, data modification times, and owner.@FIXME{This is only accidentally true, but not in general. In most cases, one has to be root for restoring the owner, and use a special option for restoring permissions. Here, it just happens @@ -1499,22 +1459,22 @@ you may have made before deleting the file from the file system, however, will @emph{not} have been made to the archive member.) The archive file, @samp{collection.tar}, is the same as it was before you extracted @samp{blues}. You can confirm this by running @command{tar} with -@value{op-list}. +@option{--list} (@option{-t}). @FIXME{we hope this will change:}Remember that as with other operations, specifying the exact member name is important. @w{@kbd{tar --extract --file=bfiles.tar birds}} will fail, because there is no member named @file{birds}. To extract the member named @file{./birds}, you must specify @w{@kbd{tar --extract --file=bfiles.tar ./birds}}. To find the -exact member names of the members of an archive, use @value{op-list} +exact member names of the members of an archive, use @option{--list} (@option{-t}) (@pxref{list}). You can extract a file to standard output by combining the above options -with the @value{op-to-stdout} option (@pxref{Writing to Standard +with the @option{--to-stdout} (@option{-O}) option (@pxref{Writing to Standard Output}). -If you give the @value{op-verbose} option, then @value{op-extract} will -print the names of the archive members as it extracts them. +If you give the @option{--verbose} option, then @option{--extract} +will print the names of the archive members as it extracts them. @node extract dir @subsection Extracting Files that are Directories @@ -1553,14 +1513,14 @@ practice/jazz @end smallexample @noindent -If you were to specify two @value{op-verbose} options, @command{tar} +If you were to specify two @option{--verbose} (@option{-v}) options, @command{tar} would have displayed more detail about the extracted files, as shown in the example below: @smallexample $ @kbd{tar -xvvf music.tar practice/folk practice/jazz} --rw-rw-rw- me user 28 1996-10-18 16:31 practice/jazz --rw-rw-rw- me user 20 1996-09-23 16:44 practice/folk +-rw-r--r-- me user 28 1996-10-18 16:31 practice/jazz +-rw-r--r-- me user 20 1996-09-23 16:44 practice/folk @end smallexample @noindent @@ -1590,8 +1550,8 @@ $ @kbd{tar -xvf ../untrusted.tar} @end smallexample It is also a good practice to examine contents of the archive -before extracting it, using @value{op-list} option, possibly combined -with @value{op-verbose}. +before extracting it, using @option{--list} (@option{-t}) option, possibly combined +with @option{--verbose} (@option{-v}). @node failing commands @subsection Commands That Will Fail @@ -1674,9 +1634,9 @@ pointers to other parts of the @command{tar} manual. Some options are so special they are fully described right in this chapter. They have the effect of inhibiting the normal operation of @command{tar} or else, they globally alter the amount of feedback the user -receives about what is going on. These are the @value{op-help} and -@value{op-version} (@pxref{help}), @value{op-verbose} (@pxref{verbose}) -and @value{op-interactive} options (@pxref{interactive}). +receives about what is going on. These are the @option{--help} and +@option{--version} (@pxref{help}), @option{--verbose} (@pxref{verbose}) +and @option{--interactive} options (@pxref{interactive}). @menu * Synopsis:: @@ -1684,6 +1644,7 @@ and @value{op-interactive} options (@pxref{interactive}). * Styles:: * All Options:: * help:: +* defaults:: * verbose:: * interactive:: @end menu @@ -1714,26 +1675,28 @@ to understand. Further, the option stating the main operation mode (the @command{tar} main command) is usually given first. Each @var{name} in the synopsis above is interpreted as an archive member -name when the main command is one of @value{op-compare}, @value{op-delete}, -@value{op-extract}, @value{op-list} or @value{op-update}. When naming -archive members, you must give the exact name of the member in the -archive, as it is printed by @value{op-list}. For @value{op-append} -and @value{op-create}, these @var{name} arguments specify the names -of either files or directory hierarchies to place in the archive. +name when the main command is one of @option{--compare} +(@option{--diff}, @option{-d}), @option{--delete}, @option{--extract} +(@option{--get}, @option{-x}), @option{--list} (@option{-t}) or +@option{--update} (@option{-u}). When naming archive members, you +must give the exact name of the member in the archive, as it is +printed by @option{--list}. For @option{--append} (@option{-r}) and +@option{--create} (@option{-c}), these @var{name} arguments specify +the names of either files or directory hierarchies to place in the archive. These files or hierarchies should already exist in the file system, prior to the execution of the @command{tar} command. @command{tar} interprets relative file names as being relative to the working directory. @command{tar} will make all file names relative (by removing leading slashes when archiving or restoring files), -unless you specify otherwise (using the @value{op-absolute-names} -option). @value{xref-absolute-names}, for more information about -@value{op-absolute-names}. +unless you specify otherwise (using the @option{--absolute-names} +option). @xref{absolute}, for more information about +@option{--absolute-names}. If you give the name of a directory as either a file name or a member name, then @command{tar} acts recursively on all the files and directories beneath that directory. For example, the name @file{/} identifies all -the files in the filesystem to @command{tar}. +the files in the file system to @command{tar}. The distinction between file names and archive member names is especially important when shell globbing is used, and sometimes a source of confusion @@ -1747,14 +1710,15 @@ sufficient for this. Even if @var{name}s are often specified on the command line, they can also be read from a text file in the file system, using the -@value{op-files-from} option. +@option{--files-from=@var{file-of-names}} (@option{-T @var{file-of-names}}) option. -If you don't use any file name arguments, @value{op-append}, -@value{op-delete} and @value{op-concatenate} will do nothing, while -@value{op-create} will usually yield a diagnostic and inhibit @command{tar} -execution. The other operations of @command{tar} (@value{op-list}, -@value{op-extract}, @value{op-compare}, and @value{op-update}) will act -on the entire contents of the archive. +If you don't use any file name arguments, @option{--append} (@option{-r}), +@option{--delete} and @option{--concatenate} (@option{--catenate}, +@option{-A}) will do nothing, while @option{--create} (@option{-c}) +will usually yield a diagnostic and inhibit @command{tar} execution. +The other operations of @command{tar} (@option{--list}, +@option{--extract}, @option{--compare}, and @option{--update}) +will act on the entire contents of the archive. @cindex exit status @cindex return status @@ -1772,10 +1736,11 @@ the error. @GNUTAR{} returns only a few exit statuses. I'm really aiming simplicity in that area, for now. If you are not using the -@value{op-compare} option, zero means that everything went well, besides -maybe innocuous warnings. Nonzero means that something went wrong. -Right now, as of today, ``nonzero'' is almost always 2, except for -remote operations, where it may be 128. +@option{--compare} @option{--diff}, @option{-d}) option, zero means +that everything went well, besides maybe innocuous warnings. Nonzero +means that something went wrong. Right now, as of today, ``nonzero'' +is almost always 2, except for remote operations, where it may be +128. @node using tar options @section Using @command{tar} Options @@ -1792,18 +1757,20 @@ looks, or the format of the files that you wish to archive may require you to do something special in order to make the archive look right. You can customize and control @command{tar}'s performance by running -@command{tar} with one or more options (such as @value{op-verbose}, which -we used in the tutorial). As we said in the tutorial, @dfn{options} are -arguments to @command{tar} which are (as their name suggests) optional. -Depending on the operating mode, you may specify one or more options. -Different options will have different effects, but in general they all -change details of the operation, such as archive format, archive name, -or level of user interaction. Some options make sense with all -operating modes, while others are meaningful only with particular modes. -You will likely use some options frequently, while you will only use -others infrequently, or not at all. (A full list of options is -available in @pxref{All Options}.) - +@command{tar} with one or more options (such as @option{--verbose} +(@option{-v}), which we used in the tutorial). As we said in the +tutorial, @dfn{options} are arguments to @command{tar} which are (as +their name suggests) optional. Depending on the operating mode, you +may specify one or more options. Different options will have different +effects, but in general they all change details of the operation, such +as archive format, archive name, or level of user interaction. Some +options make sense with all operating modes, while others are +meaningful only with particular modes. You will likely use some +options frequently, while you will only use others infrequently, or +not at all. (A full list of options is available in @pxref{All Options}.) + +@vrindex TAR_OPTIONS, environment variable +@anchor{TAR_OPTIONS} The @env{TAR_OPTIONS} environment variable specifies default options to be placed in front of any explicit options. For example, if @code{TAR_OPTIONS} is @samp{-v --unlink-first}, @command{tar} behaves as @@ -1816,7 +1783,7 @@ Note that @command{tar} options are case sensitive. For example, the options @option{-T} and @option{-t} are different; the first requires an argument for stating the name of a file providing a list of @var{name}s, while the second does not require an argument and is another way to -write @value{op-list}. +write @option{--list} (@option{-t}). In addition to the eight operations, there are many options to @command{tar}, and three different styles for writing both: long (mnemonic) @@ -1836,21 +1803,21 @@ line invoking @command{tar}. The different styles were developed at different times during the history of @command{tar}. These styles will be presented below, from the most recent to the oldest. -Some options must take an argument. (For example, @value{op-file} takes -the name of an archive file as an argument. If you do not supply an -archive file name, @command{tar} will use a default, but this can be -confusing; thus, we recommend that you always supply a specific archive -file name.) Where you @emph{place} the arguments generally depends on -which style of options you choose. We will detail specific information -relevant to each option style in the sections on the different option -styles, below. The differences are subtle, yet can often be very -important; incorrect option placement can cause you to overwrite a -number of important files. We urge you to note these differences, and -only use the option style(s) which makes the most sense to you until you -feel comfortable with the others. +Some options must take an argument. (For example, @option{--file} +(@option{-f})) takes the name of an archive file as an argument. If +you do not supply an archive file name, @command{tar} will use a +default, but this can be confusing; thus, we recommend that you always +supply a specific archive file name.) Where you @emph{place} the +arguments generally depends on which style of options you choose. We +will detail specific information relevant to each option style in the +sections on the different option styles, below. The differences are +subtle, yet can often be very important; incorrect option placement +can cause you to overwrite a number of important files. We urge you +to note these differences, and only use the option style(s) which +makes the most sense to you until you feel comfortable with the others. Some options @emph{may} take an argument (currently, there are -two such options: @value{op-backup} and @value{op-occurrence}). Such +two such options: @option{--backup} and @option{--occurrence}). Such options may have at most long and short forms, they do not have old style equivalent. The rules for specifying an argument for such options are stricter than those for specifying mandatory arguments. Please, @@ -2034,7 +2001,7 @@ people are used to them. For compatibility with Unix @command{tar}, the first argument is always treated as containing command and option letters even if it doesn't start with @samp{-}. Thus, @samp{tar c} is equivalent to @w{@samp{tar -c}:} both of them specify the -@value{op-create} command to create an archive. +@option{--create} (@option{-c}) command to create an archive. @node Mixing @subsection Mixing Option Styles @@ -2125,16 +2092,19 @@ a reference for deciphering @command{tar} commands in scripts. @table @option +@opindex append, summary @item --append @itemx -r Appends files to the end of the archive. @xref{append}. +@opindex catenate, summary @item --catenate @itemx -A Same as @option{--concatenate}. @xref{concatenate}. +@opindex compare, summary @item --compare @itemx -d @@ -2142,48 +2112,56 @@ Compares archive members with their counterparts in the file system, and reports differences in file size, mode, owner, modification date and contents. @xref{compare}. +@opindex concatenate, summary @item --concatenate @itemx -A Appends other @command{tar} archives to the end of the archive. @xref{concatenate}. +@opindex create, summary @item --create @itemx -c Creates a new @command{tar} archive. @xref{create}. +@opindex delete, summary @item --delete Deletes members from the archive. Don't try this on a archive on a tape! @xref{delete}. +@opindex diff, summary @item --diff @itemx -d Same @option{--compare}. @xref{compare}. +@opindex extract, summary @item --extract @itemx -x Extracts members from the archive into the file system. @xref{extract}. +@opindex get, summary @item --get @itemx -x Same as @option{--extract}. @xref{extract}. +@opindex list, summary @item --list @itemx -t Lists the members in an archive. @xref{list}. +@opindex update, summary @item --update @itemx -u @FIXME{It was: A combination of the @option{--compare} and @option{--append} operations. This is not true and rather misleading, -as @value{op-compare} does a lot more than @value{op-update} for +as @option{--compare} (@option{--diff}, @option{-d}) does a lot more than @option{--update} (@option{-u}) for ensuring files are identical.} Adds files to the end of the archive, but only if they are newer than their counterparts already in the archive, or if they do not already exist in the archive. @@ -2196,57 +2174,100 @@ archive, or if they do not already exist in the archive. @table @option +@opindex absolute-names, summary @item --absolute-names @itemx -P Normally when creating an archive, @command{tar} strips an initial @samp{/} from member names. This option disables that behavior. -@FIXME-xref{} +@xref{absolute}. +@opindex after-date, summary @item --after-date -(See @option{--newer}.) @FIXME-pxref{} +(See @option{--newer}, @pxref{after}) +@opindex anchored, summary @item --anchored An exclude pattern must match an initial subsequence of the name's components. -@FIXME-xref{} +@xref{controlling pattern-matching with exclude}. +@opindex atime-preserve, summary @item --atime-preserve - -Tells @command{tar} to preserve the access time field in a file's inode when -reading it. Due to limitations in the @code{utimes} system call, the -modification time field is also preserved, which may cause problems if -the file is simultaneously being modified by another program. -This option is incompatible with incremental backups, because -preserving the access time involves updating the last-changed time. -Also, this option does not work on files that you do not own, -unless you're root. -@FIXME-xref{} - +@itemx --atime-preserve=replace +@itemx --atime-preserve=system + +Attempt to preserve the access time of files when reading them. This +option currently is effective only on files that you own, unless you +have superuser privileges. + +@option{--atime-preserve=replace} remembers the access time of a file +before reading it, and then restores the access time afterwards. This +may cause problems if other programs are reading the file at the same +time, as the times of their accesses will be lost. On most platforms +restoring the access time also requires @command{tar} to restore the +data modification time too, so this option may also cause problems if +other programs are writing the file at the same time. (Tar attempts +to detect this situation, but cannot do so reliably due to race +conditions.) Worse, on most platforms restoring the access time also +updates the status change time, which means that this option is +incompatible with incremental backups. + +@option{--atime-preserve=system} avoids changing time stamps on files, +without interfering with time stamp updates +caused by other programs, so it works better with incremental backups. +However, it requires a special @code{O_NOATIME} option from the +underlying operating and file system implementation, and it also requires +that searching directories does not update their access times. As of +this writing (November 2005) this works only with Linux, and only with +Linux kernels 2.6.8 and later. Worse, there is currently no reliable +way to know whether this feature actually works. Sometimes +@command{tar} knows that it does not work, and if you use +@option{--atime-preserve=system} then @command{tar} complains and +exits right away. But other times @command{tar} might think that the +option works when it actually does not. + +Currently @option{--atime-preserve} with no operand defaults to +@option{--atime-preserve=replace}, but this may change in the future +as support for @option{--atime-preserve=system} improves. + +If your operating system does not support +@option{--atime-preserve=system}, you might be able to preserve access +times reliably by by using the @command{mount} command. For example, +you can mount the file system read-only, or access the file system via +a read-only loopback mount, or use the @samp{noatime} mount option +available on some systems. However, mounting typically requires +superuser privileges and can be a pain to manage. + +@opindex backup, summary @item --backup=@var{backup-type} Rather than deleting files from the file system, @command{tar} will back them up using simple or numbered backups, depending upon -@var{backup-type}. @FIXME-xref{} +@var{backup-type}. @xref{backup}. +@opindex block-number, summary @item --block-number @itemx -R With this option present, @command{tar} prints error messages for read errors -with the block number in the archive file. @FIXME-xref{} +with the block number in the archive file. @xref{block-number}. +@opindex blocking-factor, summary @item --blocking-factor=@var{blocking} @itemx -b @var{blocking} Sets the blocking factor @command{tar} uses to @var{blocking} x 512 bytes per -record. @FIXME-xref{} +record. @xref{Blocking Factor}. +@opindex bzip2, summary @item --bzip2 @itemx -j This option tells @command{tar} to read or write archives through -@code{bzip2}. @FIXME-xref{} +@code{bzip2}. @xref{gzip}. +@opindex checkpoint, summary @item --checkpoint This option directs @command{tar} to print periodic checkpoint messages as it @@ -2254,6 +2275,7 @@ reads through the archive. Its intended for when you want a visual indication that @command{tar} is still running, but don't want to see @option{--verbose} output. @FIXME-xref{} +@opindex check-links, summary @item --check-links @itemx -l If this option was given, @command{tar} will check the number of links @@ -2265,70 +2287,88 @@ Future versions will take @option{-l} as a short version of @option{--check-links}. However, current release still retains the old semantics for @option{-l}. -@xref{Current status}, for more information. +@xref{Changes}, for more information. +@opindex compress, summary +@opindex uncompress, summary @item --compress @itemx --uncompress @itemx -Z @command{tar} will use the @command{compress} program when reading or writing the archive. This allows you to directly act on archives -while saving space. @FIXME-xref{} +while saving space. @xref{gzip}. +@opindex confirmation, summary @item --confirmation -(See @option{--interactive}.) @FIXME-pxref{} +(See @option{--interactive}.) @xref{interactive}. + +@opindex delay-directory-restore, summary +@item --delay-directory-restore +Delay setting modification times and permissions of extracted +directories until the end of extraction. @xref{Directory Modification Times and Permissions}. + +@opindex dereference, summary @item --dereference @itemx -h When creating a @command{tar} archive, @command{tar} will archive the file that a symbolic link points to, rather than archiving the -symlink. @FIXME-xref{} +symlink. @xref{dereference}. +@opindex directory, summary @item --directory=@var{dir} @itemx -C @var{dir} When this option is specified, @command{tar} will change its current directory to @var{dir} before performing any operations. When this option is used -during archive creation, it is order sensitive. @FIXME-xref{} +during archive creation, it is order sensitive. @xref{directory}. +@opindex exclude, summary @item --exclude=@var{pattern} When performing operations, @command{tar} will skip files that match -@var{pattern}. @FIXME-xref{} +@var{pattern}. @xref{exclude}. +@opindex exclude-from, summary @item --exclude-from=@var{file} @itemx -X @var{file} Similar to @option{--exclude}, except @command{tar} will use the list of -patterns in the file @var{file}. @FIXME-xref{} +patterns in the file @var{file}. @xref{exclude}. +@opindex exclude-caches, summary @item --exclude-caches Automatically excludes all directories -containing a cache directory tag. @FIXME-xref{} +containing a cache directory tag. @xref{exclude}. +@opindex file, summary @item --file=@var{archive} @itemx -f @var{archive} @command{tar} will use the file @var{archive} as the @command{tar} archive it performs operations on, rather than @command{tar}'s compilation dependent -default. @FIXME-xref{} +default. @xref{file tutorial}. +@opindex files-from, summary @item --files-from=@var{file} @itemx -T @var{file} @command{tar} will use the contents of @var{file} as a list of archive members or files to operate on, in addition to those specified on the -command-line. @FIXME-xref{} +command-line. @xref{files}. +@opindex force-local, summary @item --force-local Forces @command{tar} to interpret the filename given to @option{--file} as a local file, even if it looks like a remote tape drive name. -@FIXME-xref{} +@xref{local and remote archives}. +@opindex format, summary @item --format=@var{format} Selects output archive format. @var{Format} may be one of the @@ -2357,6 +2397,7 @@ Creates a @acronym{POSIX.1-2001 archive}. @xref{Formats}, for a detailed discussion of these formats. +@opindex group, summary @item --group=@var{group} Files added to the @command{tar} archive will have a group id of @var{group}, @@ -2364,8 +2405,11 @@ rather than the group from the source file. @var{group} is first decoded as a group symbolic name, but if this interpretation fails, it has to be a decimal numeric group ID. @FIXME-xref{} -Also see the comments for the @value{op-owner} option. +Also see the comments for the @option{--owner=@var{user}} option. +@opindex gzip, summary +@opindex gunzip, summary +@opindex ungzip, summary @item --gzip @itemx --gunzip @itemx --ungzip @@ -2373,74 +2417,93 @@ Also see the comments for the @value{op-owner} option. This option tells @command{tar} to read or write archives through @command{gzip}, allowing @command{tar} to directly operate on several -kinds of compressed archives transparently. @FIXME-xref{} +kinds of compressed archives transparently. @xref{gzip}. +@opindex help, summary @item --help @command{tar} will print out a short message summarizing the operations and -options to @command{tar} and exit. @FIXME-xref{} +options to @command{tar} and exit. @xref{help}. +@opindex ignore-case, summary @item --ignore-case -Ignore case when excluding files. -@FIXME-xref{} +Ignore case when excluding files. @xref{controlling pattern-matching +with exclude}. + +@opindex ignore-command-error, summary +@item --ignore-command-error +Ignore exit codes of subprocesses. @xref{Writing to an External Program}. +@opindex ignore-failed-read, summary @item --ignore-failed-read Do not exit unsuccessfully merely because an unreadable file was encountered. @xref{Reading}. +@opindex ignore-zeros, summary @item --ignore-zeros @itemx -i With this option, @command{tar} will ignore zeroed blocks in the archive, which normally signals EOF. @xref{Reading}. +@opindex incremental, summary @item --incremental @itemx -G Used to inform @command{tar} that it is working with an old @acronym{GNU}-format incremental backup archive. It is intended -primarily for backwards compatibility only. @FIXME-xref{} +primarily for backwards compatibility only. @FIXME{incremental and +listed-incremental}. +@opindex index-file, summary @item --index-file=@var{file} Send verbose output to @var{file} instead of to standard output. +@opindex info-script, summary +@opindex new-volume-script, summary @item --info-script=@var{script-file} @itemx --new-volume-script=@var{script-file} @itemx -F @var{script-file} When @command{tar} is performing multi-tape backups, @var{script-file} is run at the end of each tape. If @var{script-file} exits with nonzero status, -@command{tar} fails immediately. @FIXME-xref{} +@command{tar} fails immediately. @xref{info-script}, for a detailed +discussion of @var{script-file}. +@opindex interactive, summary @item --interactive @itemx --confirmation @itemx -w Specifies that @command{tar} should ask the user for confirmation before performing potentially destructive options, such as overwriting files. -@FIXME-xref{} +@xref{interactive}. +@opindex keep-newer-files, summary @item --keep-newer-files Do not replace existing files that are newer than their archive copies when extracting files from an archive. +@opindex keep-old-files, summary @item --keep-old-files @itemx -k Do not overwrite existing files when extracting files from an archive. -@xref{Writing}. +@xref{Keep Old Files}. +@opindex label, summary @item --label=@var{name} @itemx -V @var{name} When creating an archive, instructs @command{tar} to write @var{name} as a name record in the archive. When extracting or listing archives, @command{tar} will only operate on archives that have a label matching -the pattern specified in @var{name}. @FIXME-xref{} +the pattern specified in @var{name}. @xref{Tape Files}. +@opindex listed-incremental, summary @item --listed-incremental=@var{snapshot-file} @itemx -g @var{snapshot-file} @@ -2448,8 +2511,9 @@ During a @option{--create} operation, specifies that the archive that @command{tar} creates is a new @acronym{GNU}-format incremental backup, using @var{snapshot-file} to determine which files to backup. With other operations, informs @command{tar} that the archive is in -incremental format. @FIXME-xref{} +incremental format. @FIXME{incremental and listed-incremental}. +@opindex mode, summary @item --mode=@var{permissions} When adding files to an archive, @command{tar} will use @@ -2467,52 +2531,78 @@ more flexibility. For example, the value @samp{a+rw} adds read and write permissions for everybody, while retaining executable bits on directories or on any other file already marked as executable. +@opindex multi-volume, summary @item --multi-volume @itemx -M Informs @command{tar} that it should create or otherwise operate on a -multi-volume @command{tar} archive. @FIXME-xref{} +multi-volume @command{tar} archive. @xref{Using Multiple Tapes}. +@opindex new-volume-script, summary @item --new-volume-script (see --info-script) -@item -n -@itemx --seek +@opindex seek, summary +@item --seek +@itemx -n Assume that the archive media supports seeks to arbitrary locations. Usually @command{tar} determines automatically whether the archive can be seeked or not. This option is intended for use in cases when such recognition fails. +@opindex newer, summary @item --newer=@var{date} @itemx --after-date=@var{date} @itemx -N When creating an archive, @command{tar} will only add files that have changed since @var{date}. If @var{date} begins with @samp{/} or @samp{.}, it -is taken to be the name of a file whose last-modified time specifies -the date. @FIXME-xref{} +is taken to be the name of a file whose data modification time specifies +the date. @xref{after}. +@opindex newer-mtime, summary @item --newer-mtime=@var{date} Like @option{--newer}, but add only files whose contents have changed (as opposed to just @option{--newer}, which will also back up files for which any status information has changed). +@opindex no-anchored, summary @item --no-anchored An exclude pattern can match any subsequence of the name's components. -@FIXME-xref{} +@xref{controlling pattern-matching with exclude}. + +@opindex no-delay-directory-restore, summary +@item --no-delay-directory-restore +Setting modification times and permissions of extracted +directories when all files from this directory has been +extracted. This is the default. @xref{Directory Modification Times and Permissions}. + +@opindex no-ignore-case, summary @item --no-ignore-case Use case-sensitive matching when excluding files. -@FIXME-xref{} +@xref{controlling pattern-matching with exclude}. + +@opindex no-ignore-command-error, summary +@item --no-ignore-command-error +Print warnings about subprocesses terminated with a non-zero exit +code. @xref{Writing to an External Program}. +@opindex no-quote-chars, summary +@item --no-quote-chars=@var{string} +Do not quote characters from @var{string}, even if the selected +quoting style implies they should be quoted (@FIXME-pxref{Quoting Styles}). + +@opindex no-recursion, summary @item --no-recursion With this option, @command{tar} will not recurse into directories. -@FIXME-xref{} +@xref{recurse}. +@opindex no-same-owner, summary @item --no-same-owner @itemx -o @@ -2520,32 +2610,37 @@ When extracting an archive, do not attempt to preserve the owner specified in the @command{tar} archive. This the default behavior for ordinary users. +@opindex no-same-permissions, summary @item --no-same-permissions When extracting an archive, subtract the user's umask from files from the permissions specified in the archive. This is the default behavior for ordinary users. +@opindex no-wildcards, summary @item --no-wildcards Do not use wildcards when excluding files. -@FIXME-xref{} +@xref{controlling pattern-matching with exclude}. +@opindex no-wildcards-match-slash, summary @item --no-wildcards-match-slash Wildcards do not match @samp{/} when excluding files. -@FIXME-xref{} +@xref{controlling pattern-matching with exclude}. +@opindex null, summary @item --null When @command{tar} is using the @option{--files-from} option, this option instructs @command{tar} to expect filenames terminated with @option{NUL}, so @command{tar} can correctly work with file names that contain newlines. -@FIXME-xref{} +@xref{nul}. +@opindex numeric-owner, summary @item --numeric-owner This option will notify @command{tar} that it should use numeric user and group IDs when creating a @command{tar} file, rather than names. -@FIXME-xref{} +@xref{Attributes}. @item -o When extracting files, this option is a synonym for @@ -2557,8 +2652,9 @@ When creating an archive, @option{-o} is a synonym for with previous versions of @GNUTAR{}, and will be removed in the future releases. -@xref{Current status}, for more information. +@xref{Changes}, for more information. +@opindex occurrence, summary @item --occurrence[=@var{number}] This option can be used in conjunction with one of the subcommands @@ -2577,9 +2673,11 @@ tar -x -f archive.tar --occurrence filename will extract the first occurrence of @file{filename} from @file{archive.tar} and will terminate without scanning to the end of the archive. +@opindex old-archive, summary @item --old-archive Synonym for @option{--format=v7}. +@opindex one-file-system, summary @item --one-file-system @itemx -l Used when creating an archive. Prevents @command{tar} from recursing into @@ -2592,18 +2690,21 @@ allowed in the present version, it is @emph{strongly discouraged}. The future versions of @GNUTAR{} will use @option{-l} as a synonym for @option{--check-links}. -@xref{Current status}, for more information. +@xref{Changes}, for more information. +@opindex overwrite, summary @item --overwrite Overwrite existing files and directory metadata when extracting files from an archive. @xref{Overwrite Old Files}. +@opindex overwrite-dir, summary @item --overwrite-dir Overwrite the metadata of existing directories when extracting files from an archive. @xref{Overwrite Old Files}. +@opindex owner, summary @item --owner=@var{user} Specifies that @command{tar} should use @var{user} as the owner of members @@ -2619,25 +2720,40 @@ anonymous anyway, so that might as well be the owner of anonymous archives. This option does not affect extraction from archives. +@opindex quote-chars, summary +@item --quote-chars=@var{string} +Always quote characters from @var{string}, even if the selected +quoting style would not quote them (@FIXME-pxref{Quoting Styles}). + +@opindex quoting-style, summary +@item --quoting-style=@var{style} +Set quoting style to use when printing member and file names +(@FIXME-pxref{Quoting Styles}). Valid @var{style} values are: +@code{literal}, @code{shell}, @code{shell-always}, @code{c}, +@code{escape}, @code{locale}, and @code{clocale}. Default quoting +style is @code{escape}, unless overridden while configuring the +package. + +@opindex pax-option, summary @item --pax-option=@var{keyword-list} - +@FIXME{Such a detailed description does not belong there, move it elsewhere.} This option is meaningful only with @acronym{POSIX.1-2001} archives -(@FIXME-xref{}). It modifies the way @command{tar} handles the +(@pxref{posix}). It modifies the way @command{tar} handles the extended header keywords. @var{Keyword-list} is a comma-separated list of keyword options, each keyword option taking one of the following forms: @table @asis @item delete=@var{pattern} -When used with one of archive-creation command (@FIXME-xref{}), +When used with one of archive-creation commands, this option instructs @command{tar} to omit from extended header records that it produces any keywords matching the string @var{pattern}. When used in extract or list mode, this option instructs tar to ignore any keywords matching the given @var{pattern} in the extended header records. In both cases, matching is performed using the pattern -matching notation described in @acronym{POSIX 1003.2}, 3.13 @FIXME-xref{see -man 7 glob}. For example: +matching notation described in @acronym{POSIX 1003.2}, 3.13 +(See @cite{glob(7)}). For example: @smallexample --pax-option delete=security.* @@ -2729,22 +2845,28 @@ the group name will be forced to a new value for all files stored in the archive. @end table +@opindex portability, summary @item --portability @itemx --old-archive Synonym for @option{--format=v7}. +@opindex posix, summary @item --posix Same as @option{--format=posix}. +@opindex preserve, summary @item --preserve Synonymous with specifying both @option{--preserve-permissions} and -@option{--same-order}. @FIXME-xref{} +@option{--same-order}. @xref{Setting Access Permissions}. +@opindex preserve-order, summary @item --preserve-order (See @option{--same-order}; @pxref{Reading}.) +@opindex preserve-permissions, summary +@opindex same-permissions, summary @item --preserve-permissions @itemx --same-permissions @itemx -p @@ -2753,45 +2875,60 @@ When @command{tar} is extracting an archive, it normally subtracts the users' umask from the permissions specified in the archive and uses that number as the permissions to create the destination file. Specifying this option instructs @command{tar} that it should use the -permissions directly from the archive. @xref{Writing}. +permissions directly from the archive. @xref{Setting Access Permissions}. +@opindex read-full-records, summary @item --read-full-records @itemx -B Specifies that @command{tar} should reblock its input, for reading from pipes on systems with buggy implementations. @xref{Reading}. +@opindex record-size, summary @item --record-size=@var{size} Instructs @command{tar} to use @var{size} bytes per record when accessing the -archive. @FIXME-xref{} +archive. @xref{Blocking Factor}. +@opindex recursion, summary @item --recursion With this option, @command{tar} recurses into directories. -@FIXME-xref{} +@xref{recurse}. +@opindex recursive-unlink, summary @item --recursive-unlink Remove existing directory hierarchies before extracting directories of the same name -from the archive. @xref{Writing}. +from the archive. @xref{Recursive Unlink}. +@opindex remove-files, summary @item --remove-files Directs @command{tar} to remove the source file from the file system after -appending it to an archive. @FIXME-xref{} +appending it to an archive. @xref{remove files}. + +@opindex restrict, summary +@item --restrict + +Disable use of some potentially harmful @command{tar} options. +Currently this option disables shell invocaton from multi-volume menu +(@pxref{Using Multiple Tapes}). +@opindex rmt-command, summary @item --rmt-command=@var{cmd} Notifies @command{tar} that it should use @var{cmd} instead of the default @file{/usr/libexec/rmt} (@pxref{Remote Tape Server}). +@opindex rsh-command, summary @item --rsh-command=@var{cmd} Notifies @command{tar} that is should use @var{cmd} to communicate with remote -devices. @FIXME-xref{} +devices. @xref{Device}. +@opindex same-order, summary @item --same-order @itemx --preserve-order @itemx -s @@ -2801,17 +2938,20 @@ small amounts of memory. It informs @command{tar} that the list of file arguments has already been sorted to match the order of files in the archive. @xref{Reading}. +@opindex same-owner, summary @item --same-owner When extracting an archive, @command{tar} will attempt to preserve the owner specified in the @command{tar} archive with this option present. This is the default behavior for the superuser; this option has an -effect only for ordinary users. @FIXME-xref{} +effect only for ordinary users. @xref{Attributes}. +@opindex same-permissions, summary @item --same-permissions -(See @option{--preserve-permissions}; @pxref{Writing}.) +(See @option{--preserve-permissions}; @pxref{Setting Access Permissions}.) +@opindex show-defaults, summary @item --show-defaults Displays the default options used by @command{tar} and exits @@ -2820,14 +2960,17 @@ Here is an example of what you can see using this option: @smallexample $ tar --show-defaults ---format=gnu -f- -b20 +--format=gnu -f- -b20 --quoting-style=escape \ +--rmt-command=/usr/libexec/rmt --rsh-command=/usr/bin/rsh @end smallexample +@opindex show-omitted-dirs, summary @item --show-omitted-dirs Instructs @command{tar} to mention directories its skipping over when -operating on a @command{tar} archive. @FIXME-xref{} +operating on a @command{tar} archive. @xref{show-omitted-dirs}. +@opindex show-stored-names, summary @item --show-stored-names This option has effect only when used in conjunction with one of @@ -2835,12 +2978,14 @@ archive creation operations. It instructs tar to list the member names stored in the archive, as opposed to the actual file names. @xref{listing member and file names}. +@opindex sparse, summary @item --sparse @itemx -S Invokes a @acronym{GNU} extension when adding files to an archive that handles -sparse files efficiently. @FIXME-xref{} +sparse files efficiently. @xref{sparse}. +@opindex starting-file, summary @item --starting-file=@var{name} @itemx -K @var{name} @@ -2848,6 +2993,7 @@ This option affects extraction only; @command{tar} will skip extracting files in the archive until it finds one that matches @var{name}. @xref{Scarce}. +@opindex strip-components, summary @item --strip-components=@var{number} Strip given @var{number} of leading components from file names before extraction.@footnote{This option was called @option{--strip-path} in @@ -2861,96 +3007,120 @@ tar --extract --file archive.tar --strip-components=2 @noindent would extracted this file to file @file{name}. +@opindex suffix, summary @item --suffix=@var{suffix} Alters the suffix @command{tar} uses when backing up files from the default -@samp{~}. @FIXME-xref{} +@samp{~}. @xref{backup}. +@opindex tape-length, summary @item --tape-length=@var{num} @itemx -L @var{num} Specifies the length of tapes that @command{tar} is writing as being -@w{@var{num} x 1024} bytes long. @FIXME-xref{} +@w{@var{num} x 1024} bytes long. @xref{Using Multiple Tapes}. +@opindex test-label, summary @item --test-label Reads the volume label. If an argument is specified, test whether it matches the volume label. @xref{--test-label option}. +@opindex to-command, summary +@item --to-command=@var{command} + +During extraction @command{tar} will pipe extracted files to the +standard input of @var{command}. @xref{Writing to an External Program}. + +@opindex to-stdout, summary @item --to-stdout @itemx -O During extraction, @command{tar} will extract files to stdout rather -than to the file system. @xref{Writing}. +than to the file system. @xref{Writing to Standard Output}. +@opindex totals, summary @item --totals Displays the total number of bytes written after creating an archive. -@FIXME-xref{} +@xref{verbose}. +@opindex touch, summary @item --touch @itemx -m -Sets the modification time of extracted files to the extraction time, -rather than the modification time stored in the archive. -@xref{Writing}. +Sets the data modification time of extracted files to the extraction time, +rather than the data modification time stored in the archive. +@xref{Data Modification Times}. +@opindex uncompress, summary @item --uncompress -(See @option{--compress}.) @FIXME-pxref{} +(See @option{--compress}. @pxref{gzip}) +@opindex ungzip, summary @item --ungzip -(See @option{--gzip}.) @FIXME-pxref{} +(See @option{--gzip}. @pxref{gzip}) +@opindex unlink-first, summary @item --unlink-first @itemx -U Directs @command{tar} to remove the corresponding file from the file -system before extracting it from the archive. @xref{Writing}. +system before extracting it from the archive. @xref{Unlink First}. +@opindex use-compress-program, summary @item --use-compress-program=@var{prog} Instructs @command{tar} to access the archive through @var{prog}, which is -presumed to be a compression program of some sort. @FIXME-xref{} +presumed to be a compression program of some sort. @xref{gzip}. +@opindex utc, summary @item --utc Display file modification dates in @acronym{UTC}. This option implies @option{--verbose}. +@opindex verbose, summary @item --verbose @itemx -v Specifies that @command{tar} should be more verbose about the operations its performing. This option can be specified multiple times for some -operations to increase the amount of information displayed. @FIXME-xref{} +operations to increase the amount of information displayed. +@xref{verbose}. +@opindex verify, summary @item --verify @itemx -W Verifies that the archive was correctly written when creating an -archive. @FIXME-xref{} +archive. @xref{verify}. +@opindex version, summary @item --version -@command{tar} will print an informational message about what version -it is and a copyright message, some credits, and then exit. -@FIXME-xref{} +Print information about the program's name, version, origin and legal +status, all on standard output, and then exit successfully. +@xref{help}. +@opindex volno-file, summary @item --volno-file=@var{file} Used in conjunction with @option{--multi-volume}. @command{tar} will keep track of which volume of a multi-volume archive its working in @var{file}. -@FIXME-xref{} +@xref{volno-file}. +@opindex wildcards, summary @item --wildcards Use wildcards when excluding files. -@FIXME-xref{} +@xref{controlling pattern-matching with exclude}. +@opindex wildcards-match-slash, summary @item --wildcards-match-slash Wildcards match @samp{/} when excluding files. -@FIXME-xref{} +@xref{controlling pattern-matching with exclude}. @end table @node Short Option Summary @@ -3079,7 +3249,7 @@ them with the equivalent long option. is retained for compatibility with the earlier versions of GNU @command{tar}, and will be changed in future releases. -@xref{Current status}, for more information. +@xref{Changes}, for more information. @item -m @@ -3135,17 +3305,23 @@ the earlier versions of @GNUTAR{}. In the future releases @node help @section @GNUTAR{} documentation +@cindex Getting program version number +@opindex version +@cindex Version of the @command{tar} program Being careful, the first thing is really checking that you are using -@GNUTAR{}, indeed. The @value{op-version} option -will generate a message giving confirmation that you are using -@GNUTAR{}, with the precise version of @GNUTAR{} -you are using. @command{tar} identifies itself and -prints the version number to the standard output, then immediately -exits successfully, without doing anything else, ignoring all other -options. For example, @w{@samp{tar --version}} might return: +@GNUTAR{}, indeed. The @option{--version} option +causes @command{tar} to print information about its name, version, +origin and legal status, all on standard output, and then exit +successfully. For example, @w{@samp{tar --version}} might print: @smallexample -tar (@acronym{GNU} tar) @value{VERSION} +tar (GNU tar) 1.15.2 +Copyright (C) 2006 Free Software Foundation, Inc. +This is free software. You may redistribute copies of it under the terms of +the GNU General Public License . +There is NO WARRANTY, to the extent permitted by law. + +Written by John Gilmore and Jay Fenlason. @end smallexample @noindent @@ -3157,14 +3333,17 @@ named @samp{tar}, after the name of the main program it contains@footnote{There are plans to merge the @command{cpio} and @command{tar} packages into a single one which would be called @code{paxutils}. So, who knows if, one of this days, the -@value{op-version} would not yield @w{@samp{tar (@acronym{GNU} +@option{--version} would not output @w{@samp{tar (@acronym{GNU} paxutils) 3.2}}}. +@cindex Obtaining help +@cindex Listing all @command{tar} options +@opindex help, introduction Another thing you might want to do is checking the spelling or meaning of some particular @command{tar} option, without resorting to this manual, for once you have carefully read it. @GNUTAR{} has a short help feature, triggerable through the -@value{op-help} option. By using this option, @command{tar} will +@option{--help} option. By using this option, @command{tar} will print a usage message listing all available options on standard output, then exit successfully, without doing anything else and ignoring all other options. Even if this is only a brief summary, it @@ -3179,26 +3358,30 @@ $ @kbd{tar --help | less} presuming, here, that you like using @command{less} for a pager. Other popular pagers are @command{more} and @command{pg}. If you know about some @var{keyword} which interests you and do not want to read all the -@value{op-help} output, another common idiom is doing: +@option{--help} output, another common idiom is doing: @smallexample tar --help | grep @var{keyword} @end smallexample @noindent -for getting only the pertinent lines. +for getting only the pertinent lines. Notice, however, that some +@command{tar} options have long description lines and the above +command will list only the first of them. + +The exact look of the option summary displayed by @kbd{tar --help} is +configurable. @xref{Configuring Help Summary}, for a detailed description. -The perceptive reader would have noticed some contradiction in the -previous paragraphs. It is written that both @value{op-version} and -@value{op-help} print something, and have all other options ignored. In -fact, they cannot ignore each other, and one of them has to win. We do -not specify which is stronger, here; experiment if you really wonder! +@opindex usage +If you only wish to check the spelling of an option, running @kbd{tar +--usage} may be a better choice. This will display a terse list of +@command{tar} option without accompanying explanations. The short help output is quite succinct, and you might have to get back to the full documentation for precise points. If you are reading this paragraph, you already have the @command{tar} manual in some -form. This manual is available in printed form, as a kind of small -book. It may printed out of the @GNUTAR{} +form. This manual is available in a variety of forms from +@url{http://www.gnu.org/software/tar/manual}. It may printed out of the @GNUTAR{} distribution, provided you have @TeX{} already installed somewhere, and a laser printer around. Just configure the distribution, execute the command @w{@samp{make dvi}}, then print @file{doc/tar.dvi} the @@ -3211,25 +3394,38 @@ file. Just call @w{@samp{info tar}} or, if you do not have the There is currently no @code{man} page for @GNUTAR{}. If you observe such a @code{man} page on the system you are running, -either it does not long to @GNUTAR{}, or it has not -been produced by @acronym{GNU}. Currently, @GNUTAR{} -documentation is provided in Texinfo format only, if we -except, of course, the short result of @kbd{tar --help}. +either it does not belong to @GNUTAR{}, or it has not +been produced by @acronym{GNU}. Some package maintainers convert +@kbd{tar --help} output to a man page, using @command{help2man}. In +any case, please bear in mind that the authoritative source of +information about @GNUTAR{} is this Texinfo documentation. -@node verbose -@section Checking @command{tar} progress +@node defaults +@section Obtaining @GNUTAR{} default values -@cindex Progress information -@cindex Status information -@cindex Information on progress and status of operations -@cindex Verbose operation -@cindex Block number where error occurred -@cindex Error message, block number of -@cindex Version of the @command{tar} program +@opindex show-defaults +@GNUTAR{} has some predefined defaults that are used when you do not +explicitely specify another values. To obtain a list of such +defaults, use @option{--show-defaults} option. This will output the +values in the form of @command{tar} command line options: -@cindex Getting more information during the operation -@cindex Information during operation -@cindex Feedback from @command{tar} +@smallexample +@group +@kbd{tar --show-defaults} +--format=gnu -f- -b20 --rmt-command=/etc/rmt --rsh-command=/usr/bin/rsh +@end group +@end smallexample + +@noindent +The above output shows that this version of @GNUTAR{} defaults to +using @samp{gnu} archive format (@pxref{Formats}), it uses standard +output as the archive, if no @option{--file} option has been given +(@pxref{file tutorial}), the default blocking factor is 20 +(@pxref{Blocking Factor}). It also shows the default locations where +@command{tar} will look for @command{rmt} and @command{rsh} binaries. + +@node verbose +@section Checking @command{tar} progress Typically, @command{tar} performs most operations without reporting any information to the user except error messages. When using @command{tar} @@ -3244,21 +3440,24 @@ archive, however, you may need more information than just an error message in order to solve the problem. The following options can be helpful diagnostic tools. -Normally, the @value{op-list} command to list an archive prints just -the file names (one per line) and the other commands are silent. -When used with most operations, the @value{op-verbose} option causes -@command{tar} to print the name of each file or archive member as it -is processed. This and the other options which make @command{tar} print -status information can be useful in monitoring @command{tar}. - -With @value{op-create} or @value{op-extract}, @value{op-verbose} used once -just prints the names of the files or members as they are processed. -Using it twice causes @command{tar} to print a longer listing (reminiscent -of @samp{ls -l}) for each member. Since @value{op-list} already prints -the names of the members, @value{op-verbose} used once with @value{op-list} -causes @command{tar} to print an @samp{ls -l} type listing of the files -in the archive. The following examples both extract members with -long list output: +@cindex Verbose operation +@opindex verbose +Normally, the @option{--list} (@option{-t}) command to list an archive +prints just the file names (one per line) and the other commands are +silent. When used with most operations, the @option{--verbose} +(@option{-v}) option causes @command{tar} to print the name of each +file or archive member as it is processed. This and the other options +which make @command{tar} print status information can be useful in +monitoring @command{tar}. + +With @option{--create} or @option{--extract}, @option{--verbose} used +once just prints the names of the files or members as they are processed. +Using it twice causes @command{tar} to print a longer listing +(reminiscent of @samp{ls -l}) for each member. Since @option{--list} +already prints the names of the members, @option{--verbose} used once +with @option{--list} causes @command{tar} to print an @samp{ls -l} +type listing of the files in the archive. The following examples both +extract members with long list output: @smallexample $ @kbd{tar --extract --file=archive.tar --verbose --verbose} @@ -3275,46 +3474,55 @@ If @option{--index-file=@var{file}} is specified, @command{tar} sends verbose output to @var{file} rather than to standard output or standard error. -The @value{op-totals} option---which is only meaningful when used with -@value{op-create}---causes @command{tar} to print the total +@cindex Obtaining total status information +@opindex totals +The @option{--totals} option---which is only meaningful when used with +@option{--create} (@option{-c})---causes @command{tar} to print the total amount written to the archive, after it has been fully created. -The @value{op-checkpoint} option prints an occasional message +@cindex Progress information +@opindex checkpoint +The @option{--checkpoint} option prints an occasional message as @command{tar} reads or writes the archive. In fact, it prints a message each 10 records read or written. It is designed for those who don't need the more detailed (and voluminous) output of -@value{op-block-number}, but do want visual confirmation that @command{tar} +@option{--block-number} (@option{-R}), but do want visual confirmation that @command{tar} is actually making forward progress. @FIXME{There is some confusion here. It seems that -R once wrote a message at @samp{every} record read or written.} -The @value{op-show-omitted-dirs} option, when reading an archive---with -@value{op-list} or @value{op-extract}, for example---causes a message +@opindex show-omitted-dirs +@anchor{show-omitted-dirs} +The @option{--show-omitted-dirs} option, when reading an archive---with +@option{--list} or @option{--extract}, for example---causes a message to be printed for each directory in the archive which is skipped. This happens regardless of the reason for skipping: the directory might not have been named on the command line (implicitly or explicitly), -it might be excluded by the use of the @value{op-exclude} option, or +it might be excluded by the use of the @option{--exclude=@var{pattern}} option, or some other reason. -If @value{op-block-number} is used, @command{tar} prints, along with +@opindex block-number +@cindex Block number where error occurred +@anchor{block-number} +If @option{--block-number} (@option{-R}) is used, @command{tar} prints, along with every message it would normally produce, the block number within the archive where the message was triggered. Also, supplementary messages are triggered when reading blocks full of NULs, or when hitting end of file on the archive. As of now, if the archive if properly terminated with a NUL block, the reading of the file may stop before end of file is met, so the position of end of file will not usually show when -@value{op-block-number} is used. Note that @GNUTAR{} +@option{--block-number} (@option{-R}) is used. Note that @GNUTAR{} drains the archive before exiting when reading the archive from a pipe. +@cindex Error message, block number of This option is especially useful when reading damaged archives, since it helps pinpoint the damaged sections. It can also be used with -@value{op-list} when listing a file-system backup tape, allowing you to +@option{--list} (@option{-t}) when listing a file-system backup tape, allowing you to choose among several backup tapes when retrieving a file later, in favor of the tape where the file appears earliest (closest to the -front of the tape). @FIXME-xref{when the node name is set and the -backup section written.} +front of the tape). @xref{backup}. @node interactive @section Asking for Confirmation During Operations @@ -3325,10 +3533,11 @@ further instructions. In some situations however, you may want to exclude some files and archive members from the operation (for instance if disk or storage space is tight). You can do this by excluding certain files automatically (@pxref{Choosing}), or by performing -an operation interactively, using the @value{op-interactive} option. +an operation interactively, using the @option{--interactive} (@option{-w}) option. @command{tar} also accepts @option{--confirmation} for this option. -When the @value{op-interactive} option is specified, before +@opindex interactive +When the @option{--interactive} (@option{-w}) option is specified, before reading, writing, or deleting files, @command{tar} first prints a message for each such file, telling what operation it intends to take, then asks for confirmation on the terminal. The actions which require @@ -3370,23 +3579,26 @@ output free to receive verbose output, all separate from errors. @node Basic tar @section Basic @GNUTAR{} Operations -The basic @command{tar} operations, @value{op-create}, @value{op-list} and -@value{op-extract}, are currently presented and described in the tutorial +The basic @command{tar} operations, @option{--create} (@option{-c}), +@option{--list} (@option{-t}) and @option{--extract} (@option{--get}, +@option{-x}), are currently presented and described in the tutorial chapter of this manual. This section provides some complementary notes for these operations. -@table @asis -@item @value{op-create} +@table @option +@opindex create, complementary notes +@item --create +@itemx -c Creating an empty archive would have some kind of elegance. One can -initialize an empty archive and later use @value{op-append} for adding -all members. Some applications would not welcome making an exception -in the way of adding the first archive member. On the other hand, -many people reported that it is dangerously too easy for @command{tar} -to destroy a magnetic tape with an empty archive@footnote{This is well -described in @cite{Unix-haters Handbook}, by Simson Garfinkel, Daniel -Weise & Steven Strassmann, IDG Books, ISBN 1-56884-203-1.}. The two most -common errors are: +initialize an empty archive and later use @option{--append} +(@option{-r}) for adding all members. Some applications would not +welcome making an exception in the way of adding the first archive +member. On the other hand, many people reported that it is +dangerously too easy for @command{tar} to destroy a magnetic tape with +an empty archive@footnote{This is well described in @cite{Unix-haters +Handbook}, by Simson Garfinkel, Daniel Weise & Steven Strassmann, IDG +Books, ISBN 1-56884-203-1.}. The two most common errors are: @enumerate @item @@ -3408,32 +3620,34 @@ file, which was meant to be saved, is rather destroyed. So, recognizing the likelihood and the catastrophical nature of these errors, @GNUTAR{} now takes some distance from elegance, and -cowardly refuses to create an archive when @value{op-create} option is -given, there are no arguments besides options, and @value{op-files-from} -option is @emph{not} used. To get around the cautiousness of @GNUTAR{} -and nevertheless create an archive with nothing in it, -one may still use, as the value for the @value{op-files-from} option, -a file with no names in it, as shown in the following commands: +cowardly refuses to create an archive when @option{--create} option is +given, there are no arguments besides options, and +@option{--files-from} (@option{-T}) option is @emph{not} used. To get +around the cautiousness of @GNUTAR{} and nevertheless create an +archive with nothing in it, one may still use, as the value for the +@option{--files-from} option, a file with no names in it, as shown in +the following commands: @smallexample @kbd{tar --create --file=empty-archive.tar --files-from=/dev/null} @kbd{tar cfT empty-archive.tar /dev/null} @end smallexample -@item @value{op-extract} +@opindex extract, complementary notes +@item --extract +@itemx --get +@itemx -x A socket is stored, within a @GNUTAR{} archive, as a pipe. -@item @value{op-list} +@item @option{--list} (@option{-t}) @GNUTAR{} now shows dates as @samp{1996-08-30}, -while it used to show them as @samp{Aug 30 1996}. (One can revert to -the old behavior by defining @code{USE_OLD_CTIME} in @file{src/list.c} -before reinstalling.) But preferably, people should get used to ISO -8601 dates. Local American dates should be made available again with -full date localization support, once ready. In the meantime, programs -not being localizable for dates should prefer international dates, -that's really the way to go. +while it used to show them as @samp{Aug 30 1996}. Preferably, +people should get used to ISO 8601 dates. Local American dates should +be made available again with full date localization support, once +ready. In the meantime, programs not being localizable for dates +should prefer international dates, that's really the way to go. Look up @url{http://www.ft.uni-erlangen.de/~mskuhn/iso-time.html} if you are curious, it contains a detailed explanation of the ISO 8601 standard. @@ -3521,24 +3735,25 @@ Compare archive members to their counterparts in the file system. @subsection How to Add Files to Existing Archives: @option{--append} @UNREVISED +@opindex append If you want to add files to an existing archive, you don't need to -create a new archive; you can use @value{op-append}. The archive must -already exist in order to use @option{--append}. (A related operation -is the @option{--update} operation; you can use this to add newer -versions of archive members to an existing archive. To learn how to +create a new archive; you can use @option{--append} (@option{-r}). +The archive must already exist in order to use @option{--append}. (A +related operation is the @option{--update} operation; you can use this +to add newer versions of archive members to an existing archive. To learn how to do this with @option{--update}, @pxref{update}.) -If you use @value{op-append} to add a file that has the same name as an +If you use @option{--append} to add a file that has the same name as an archive member to an archive containing that archive member, then the old member is not deleted. What does happen, however, is somewhat complex. @command{tar} @emph{allows} you to have infinite number of files with the same name. Some operations treat these same-named members no differently than any other set of archive members: for example, if you -view an archive with @value{op-list}, you will see all of those members -listed, with their modification times, owners, etc. +view an archive with @option{--list} (@option{-t}), you will see all +of those members listed, with their data modification times, owners, etc. Other operations don't deal with these members as perfectly as you might -prefer; if you were to use @value{op-extract} to extract the archive, +prefer; if you were to use @option{--extract} to extract the archive, only the most recently added copy of a member with the same name as four other members would end up in the working directory. This is because @option{--extract} extracts an archive in the order the members appeared @@ -3566,7 +3781,9 @@ tar --extract --file archive.tar --occurrence=2 myfile @end smallexample @noindent -would extract only the second copy. @xref{Option Summary,---occurrence}, for the description of @value{op-occurrence} option. +would extract only the second copy. @xref{Option +Summary,---occurrence}, for the description of @option{--occurrence} +option. @FIXME{ hag -- you might want to incorporate some of the above into the MMwtSN node; not sure. i didn't know how to make it simpler... @@ -3576,7 +3793,7 @@ with the Same Name.} @cindex Members, replacing with other members @cindex Replacing members with other members -If you want to replace an archive member, use @value{op-delete} to +If you want to replace an archive member, use @option{--delete} to delete the member you want to remove from the archive, , and then use @option{--append} to add the member you want to be in the archive. Note that you can not change the order of the archive; the most recently @@ -3598,15 +3815,15 @@ and @ref{Media}, for more information.) @cindex Archives, Appending files to The simplest way to add a file to an already existing archive is the -@value{op-append} operation, which writes specified files into the +@option{--append} (@option{-r}) operation, which writes specified files into the archive whether or not they are already among the archived files. When you use @option{--append}, you @emph{must} specify file name arguments, as there is no default. If you specify a file that already exists in the archive, another copy of the file will be added to the end of the archive. As with other operations, the member names of the newly added files will be exactly the same as their names given on the -command line. The @value{op-verbose} option will print out the names -of the files as they are written into the archive. +command line. The @option{--verbose} (@option{-v}) option will print +out the names of the files as they are written into the archive. @option{--append} cannot be performed on some tape drives, unfortunately, due to deficiencies in the formats those tape drives use. The archive @@ -3624,15 +3841,15 @@ $ @kbd{tar --append --file=collection.tar rock} @end smallexample @noindent -If you now use the @value{op-list} operation, you will see that +If you now use the @option{--list} (@option{-t}) operation, you will see that @file{rock} has been added to the archive: @smallexample $ @kbd{tar --list --file=collection.tar} --rw-rw-rw- me user 28 1996-10-18 16:31 jazz --rw-rw-rw- me user 21 1996-09-23 16:44 blues --rw-rw-rw- me user 20 1996-09-23 16:44 folk --rw-rw-rw- me user 20 1996-09-23 16:44 rock +-rw-r--r-- me user 28 1996-10-18 16:31 jazz +-rw-r--r-- me user 21 1996-09-23 16:44 blues +-rw-r--r-- me user 20 1996-09-23 16:44 folk +-rw-r--r-- me user 20 1996-09-23 16:44 rock @end smallexample @FIXME{in theory, dan will (soon) try to turn this node into what it's @@ -3641,7 +3858,7 @@ title claims it will become...} @node multiple @subsubsection Multiple Files with the Same Name -You can use @value{op-append} to add copies of files which have been +You can use @option{--append} (@option{-r}) to add copies of files which have been updated since the archive was created. (However, we do not recommend doing this since there is another @command{tar} option called @option{--update}; @pxref{update} for more information. We describe this @@ -3683,11 +3900,11 @@ list the contents of the archive: @smallexample $ @kbd{tar --list --verbose --file=collection.tar} --rw-rw-rw- me user 28 1996-10-18 16:31 jazz --rw-rw-rw- me user 21 1996-09-23 16:44 blues --rw-rw-rw- me user 20 1996-09-23 16:44 folk --rw-rw-rw- me user 20 1996-09-23 16:44 rock --rw-rw-rw- me user 58 1996-10-24 18:30 blues +-rw-r--r-- me user 28 1996-10-18 16:31 jazz +-rw-r--r-- me user 21 1996-09-23 16:44 blues +-rw-r--r-- me user 20 1996-09-23 16:44 folk +-rw-r--r-- me user 20 1996-09-23 16:44 rock +-rw-r--r-- me user 58 1996-10-24 18:30 blues @end smallexample @noindent @@ -3698,30 +3915,32 @@ replaced by the newer version. You can confirm this by extracting the archive and running @samp{ls} on the directory. If you wish to extract the first occurrence of the file @file{blues} -from the archive, use @value{op-occurrence} option, as shown in +from the archive, use @option{--occurrence} option, as shown in the following example: @smallexample $ @kbd{tar --extract -vv --occurrence --file=collection.tar blues} --rw-rw-rw- me user 21 1996-09-23 16:44 blues +-rw-r--r-- me user 21 1996-09-23 16:44 blues @end smallexample -@xref{Writing}, for more information on @value{op-extract} and +@xref{Writing}, for more information on @option{--extract} and @xref{Option Summary, --occurrence}, for the description of -@value{op-occurrence} option. +@option{--occurrence} option. @node update @subsection Updating an Archive @UNREVISED @cindex Updating an archive -In the previous section, you learned how to use @value{op-append} to add -a file to an existing archive. A related operation is -@value{op-update}. The @option{--update} operation updates a @command{tar} -archive by comparing the date of the specified archive members against -the date of the file with the same name. If the file has been modified -more recently than the archive member, then the newer version of the -file is added to the archive (as with @value{op-append}). +@opindex update +In the previous section, you learned how to use @option{--append} to +add a file to an existing archive. A related operation is +@option{--update} (@option{-u}). The @option{--update} operation +updates a @command{tar} archive by comparing the date of the specified +archive members against the date of the file with the same name. If +the file has been modified more recently than the archive member, then +the newer version of the file is added to the archive (as with +@option{--append}). Unfortunately, you cannot use @option{--update} with magnetic tape drives. The operation will fail. @@ -3732,7 +3951,7 @@ charles and/or mib/thomas/dave shevett..} Both @option{--update} and @option{--append} work by adding to the end of the archive. When you extract a file from the archive, only the version stored last will wind up in the file system, unless you use -the @value{op-backup} option. @FIXME-ref{Multiple Members with the +the @option{--backup} option. @FIXME-ref{Multiple Members with the Same Name} @menu @@ -3742,7 +3961,7 @@ Same Name} @node how to update @subsubsection How to Update an Archive Using @option{--update} -You must use file name arguments with the @value{op-update} operation. +You must use file name arguments with the @option{--update} (@option{-u}) operation. If you don't specify any files, @command{tar} won't act on any files and won't tell you that it didn't do anything (which may end up confusing you). @@ -3753,7 +3972,7 @@ behavior just confused the author. :-) } To see the @option{--update} option at work, create a new file, @file{classical}, in your practice directory, and some extra text to the file @file{blues}, using any text editor. Then invoke @command{tar} with -the @samp{update} operation and the @value{op-verbose} option specified, +the @samp{update} operation and the @option{--verbose} (@option{-v}) option specified, using the names of all the files in the practice directory as file name arguments: @@ -3778,7 +3997,7 @@ it is because writing to the middle of a section of tape is a difficult process. Tapes are not designed to go backward. @xref{Media}, for more information about tapes. -@value{op-update} is not suitable for performing backups for two +@option{--update} (@option{-u}) is not suitable for performing backups for two reasons: it does not change directory content entries, and it lengthens the archive every time it is used. The @GNUTAR{} options intended specifically for backups are more @@ -3789,18 +4008,27 @@ efficient. If you need to run backups, please consult @ref{Backups}. @cindex Adding archives to an archive @cindex Concatenating Archives +@opindex concatenate +@opindex catenate +@c @cindex @option{-A} described Sometimes it may be convenient to add a second archive onto the end of an archive rather than adding individual files to the archive. To add one or more archives to the end of another archive, you should use the -@value{op-concatenate} operation. +@option{--concatenate} (@option{--catenate}, @option{-A}) operation. -To use @option{--concatenate}, name the archives to be concatenated 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 -any members; all the members with the same name coexist. @FIXME-ref{For +To use @option{--concatenate}, give the first archive with +@option{--file} option and name the rest of archives to be +concatenated on the command line. The members, and their member +names, will be copied verbatim from those archives to the first one. +@FIXME-ref{This can cause multiple members to have the same name, for information on how this affects reading the archive, Multiple Members with the Same Name.} +The new, concatenated archive will be called by the same name as the +one given with the @option{--file} option. As usual, if you omit +@option{--file}, @command{tar} will use the value of the environment +variable @env{TAPE}, or, if this has not been set, the default archive name. + +@FIXME{There is no way to specify a new name...} To demonstrate how @option{--concatenate} works, create two small archives called @file{bluesrock.tar} and @file{folkjazz.tar}, using the relevant @@ -3821,11 +4049,11 @@ contain what they are supposed to: @smallexample $ @kbd{tar -tvf bluesrock.tar} --rw-rw-rw- melissa user 105 1997-01-21 19:42 blues --rw-rw-rw- melissa user 33 1997-01-20 15:34 rock +-rw-r--r-- melissa user 105 1997-01-21 19:42 blues +-rw-r--r-- melissa user 33 1997-01-20 15:34 rock $ @kbd{tar -tvf folkjazz.tar} --rw-rw-rw- melissa user 20 1996-09-23 16:44 folk --rw-rw-rw- melissa user 65 1997-01-30 14:15 jazz +-rw-r--r-- melissa user 20 1996-09-23 16:44 folk +-rw-r--r-- melissa user 65 1997-01-30 14:15 jazz @end smallexample We can concatenate these two archives with @command{tar}: @@ -3848,12 +4076,11 @@ folk When you use @option{--concatenate}, the source and target archives must already exist and must have been created using compatible format -parameters. @FIXME-pxref{Matching Format Parameters}The new, -concatenated archive will be called by the same name as the first -archive listed on the command line. @FIXME{is there a way to specify a -new name?} +parameters. Notice, that @command{tar} does not check whether the +archives it concatenates have compatible formats, it does not +even check if the files are really tar archives. -Like @value{op-append}, this operation cannot be performed on some +Like @option{--append} (@option{-r}), this operation cannot be performed on some tape drives, due to deficiencies in the formats those tape drives use. @cindex @code{concatenate} vs @command{cat} @@ -3869,31 +4096,26 @@ from the target archive before each new archive is appended. If you use @command{cat} to combine the archives, the result will not be a valid @command{tar} format archive. If you need to retrieve files from an archive that was added to using the @command{cat} utility, use the -@value{op-ignore-zeros} option. @xref{Ignore Zeros}, for further +@option{--ignore-zeros} (@option{-i}) option. @xref{Ignore Zeros}, for further information on dealing with archives improperly combined using the @command{cat} shell utility. -@FIXME{this shouldn't go here. where should it go?} You must specify -the source archives using @value{op-file} (@value{pxref-file}). If you -do not specify the target archive, @command{tar} uses the value of the -environment variable @env{TAPE}, or, if this has not been set, the -default archive name. - @node delete @subsection Removing Archive Members Using @option{--delete} @UNREVISED @cindex Deleting files from an archive @cindex Removing files from an archive -You can remove members from an archive by using the @value{op-delete} -option. Specify the name of the archive with @value{op-file} and then -specify the names of the members to be deleted; if you list no member -names, nothing will be deleted. The @value{op-verbose} option will -cause @command{tar} to print the names of the members as they are deleted. -As with @value{op-extract}, you must give the exact member names when -using @samp{tar --delete}. @option{--delete} will remove all versions of -the named file from the archive. The @option{--delete} operation can run -very slowly. +@opindex delete +You can remove members from an archive by using the @option{--delete} +option. Specify the name of the archive with @option{--file} +(@option{-f}) and then specify the names of the members to be deleted; +if you list no member names, nothing will be deleted. The +@option{--verbose} option will cause @command{tar} to print the names +of the members as they are deleted. As with @option{--extract}, you +must give the exact member names when using @samp{tar --delete}. +@option{--delete} will remove all versions of the named file from the +archive. The @option{--delete} operation can run very slowly. Unlike other operations, @option{--delete} has no short form. @@ -3935,7 +4157,7 @@ $ to fix the above example's results, yet. I have to play with this and follow it and see what it actually does!} -The @value{op-delete} option has been reported to work properly when +The @option{--delete} option has been reported to work properly when @command{tar} acts as a filter from @code{stdin} to @code{stdout}. @node compare @@ -3943,6 +4165,7 @@ The @value{op-delete} option has been reported to work properly when @cindex Verifying the currency of an archive @UNREVISED +@opindex compare The @option{--compare} (@option{-d}), or @option{--diff} operation compares specified archive members against files with the same names, and then reports differences in file size, mode, owner, modification date and @@ -3969,29 +4192,16 @@ blues tar: funk not found in archive @end smallexample -@noindent -@FIXME{what does this actually depend on? i'm making a guess, -here.}Depending on the system where you are running @command{tar} and the -version you are running, @command{tar} may have a different error message, -such as: - -@smallexample -funk: does not exist -@end smallexample - -@FIXME-xref{somewhere, for more information about format parameters. -Melissa says: such as "format variations"? But why? Clearly I don't -get it yet; I'll deal when I get to that section.} - -The spirit behind the @value{op-compare} option is to check whether the +The spirit behind the @option{--compare} (@option{--diff}, @option{-d}) option is to check whether the archive represents the current state of files on disk, more than validating the integrity of the archive media. For this later goal, @xref{verify}. @node create options @section Options Used by @option{--create} +@opindex create, additional options The previous chapter described the basics of how to use -@value{op-create} to create an archive from a set of files. +@option{--create} (@option{-c}) to create an archive from a set of files. @xref{create}. This section described advanced options to be used with @option{--create}. @@ -4014,8 +4224,9 @@ Do not exit with nonzero on unreadable files or directories. @FIXME{i need to get dan to go over these options with me and see if there's a better way of organizing them.} -The previous chapter showed how to use @value{op-extract} to extract -an archive into the filesystem. Various options cause @command{tar} to +@opindex extract, additional options +The previous chapter showed how to use @option{--extract} to extract +an archive into the file system. Various options cause @command{tar} to extract more information than just file contents, such as the owner, the permissions, the modification date, and so forth. This section presents options to be used with @option{--extract} when certain special @@ -4032,26 +4243,22 @@ considerations arise. You may review the information presented in @node Reading @subsection Options to Help Read Archives @cindex Options when reading archives -@cindex Reading incomplete records -@cindex Records, incomplete -@cindex End-of-archive entries, ignoring -@cindex Ignoring end-of-archive entries -@cindex Large lists of file names on small machines -@cindex Small memory -@cindex Running out of space @UNREVISED +@cindex Reading incomplete records +@cindex Records, incomplete +@opindex read-full-records Normally, @command{tar} will request data in full record increments from an archive storage device. If the device cannot return a full record, @command{tar} will report an error. However, some devices do not always return full records, or do not require the last record of an archive to be padded out to the next record boundary. To keep reading until you obtain a full record, or to accept an incomplete record if it contains -an end-of-archive marker, specify the @value{op-read-full-records} option -in conjunction with the @value{op-extract} or @value{op-list} operations. -@value{xref-read-full-records}. +an end-of-archive marker, specify the @option{--read-full-records} (@option{-B}) option +in conjunction with the @option{--extract} or @option{--list} operations. +@xref{Blocking}. -The @value{op-read-full-records} option is turned on by default when +The @option{--read-full-records} (@option{-B}) option is turned on by default when @command{tar} reads an archive from standard input, or from a remote machine. This is because on BSD Unix systems, attempting to read a pipe returns however much happens to be in the pipe, even if it is @@ -4059,10 +4266,11 @@ less than was requested. If this option were not enabled, @command{tar} would fail as soon as it read an incomplete record from the pipe. If you're not sure of the blocking factor of an archive, you can -read the archive by specifying @value{op-read-full-records} and -@value{op-blocking-factor}, using a blocking factor larger than what the -archive uses. This lets you avoid having to determine the blocking factor -of an archive. @value{xref-blocking-factor}. +read the archive by specifying @option{--read-full-records} (@option{-B}) and +@option{--blocking-factor=@var{512-size}} (@option{-b +@var{512-size}}), using a blocking factor larger than what the archive +uses. This lets you avoid having to determine the blocking factor +of an archive. @xref{Blocking Factor}. @menu * read full records:: @@ -4075,24 +4283,28 @@ of an archive. @value{xref-blocking-factor}. @FIXME{need sentence or so of intro here} @table @option +@opindex read-full-records @item --read-full-records @item -B -Use in conjunction with @value{op-extract} to read an archive which -contains incomplete records, or one which has a blocking factor less -than the one specified. +Use in conjunction with @option{--extract} (@option{--get}, +@option{-x}) to read an archive which contains incomplete records, or +one which has a blocking factor less than the one specified. @end table @node Ignore Zeros @unnumberedsubsubsec Ignoring Blocks of Zeros +@cindex End-of-archive blocks, ignoring +@cindex Ignoring end-of-archive blocks +@opindex ignore-zeros Normally, @command{tar} stops reading when it encounters a block of zeros between file entries (which usually indicates the end of the archive). -@value{op-ignore-zeros} allows @command{tar} to completely read an archive -which contains a block of zeros before the end (i.e., a damaged -archive, or one that was created by concatenating several archives -together). +@option{--ignore-zeros} (@option{-i}) allows @command{tar} to +completely read an archive which contains a block of zeros before the +end (i.e., a damaged archive, or one that was created by concatenating +several archives together). -The @value{op-ignore-zeros} option is turned off by default because many +The @option{--ignore-zeros} (@option{-i}) option is turned off by default because many versions of @command{tar} write garbage after the end-of-archive entry, since that part of the media is never supposed to be read. @GNUTAR{} does not write after the end of an archive, but seeks to @@ -4103,21 +4315,14 @@ maintain compatiblity among archiving utilities. @itemx -i To ignore blocks of zeros (i.e., end-of-archive entries) which may be encountered while reading an archive. Use in conjunction with -@value{op-extract} or @value{op-list}. +@option{--extract} or @option{--list}. @end table @node Writing @subsection Changing How @command{tar} Writes Files -@cindex Overwriting old files, prevention -@cindex Protecting old files -@cindex Modification times of extracted files -@cindex Permissions of extracted files -@cindex Modes of extracted files -@cindex Writing extracted files to standard output -@cindex Standard output, writing extracted files to @UNREVISED -@FIXME{need to mention the brand new option, --backup} +@FIXME{Introductory paragraph} @menu * Dealing with Old Files:: @@ -4126,15 +4331,18 @@ encountered while reading an archive. Use in conjunction with * Keep Newer Files:: * Unlink First:: * Recursive Unlink:: -* Modification Times:: +* Data Modification Times:: * Setting Access Permissions:: +* Directory Modification Times and Permissions:: * Writing to Standard Output:: +* Writing to an External Program:: * remove files:: @end menu @node Dealing with Old Files @unnumberedsubsubsec Options Controlling the Overwriting of Existing Files +@opindex overwrite-dir, introduced When extracting files, if @command{tar} discovers that the extracted file already exists, it normally replaces the file by removing it before extracting it, to prevent confusion in the presence of hard or symbolic @@ -4145,20 +4353,24 @@ permission, etc.). The @option{--overwrite-dir} option enables this default behavior. To be more cautious and preserve the metadata of such a directory, use the @option{--no-overwrite-dir} option. +@cindex Overwriting old files, prevention +@opindex keep-old-files, introduced To be even more cautious and prevent existing files from being replaced, use -the @value{op-keep-old-files} option. It causes @command{tar} to refuse +the @option{--keep-old-files} (@option{-k}) option. It causes @command{tar} to refuse to replace or update a file that already exists, i.e., a file with the same name as an archive member prevents extraction of that archive member. Instead, it reports an error. +@opindex overwrite, introduced To be more aggressive about altering existing files, use the -@value{op-overwrite} option. It causes @command{tar} to overwrite +@option{--overwrite} option. It causes @command{tar} to overwrite existing files and to follow existing symbolic links when extracting. +@cindex Protecting old files Some people argue that @GNUTAR{} should not hesitate to overwrite files with other files when extracting. When extracting a @command{tar} archive, they expect to see a faithful copy of the -state of the filesystem when the archive was created. It is debatable +state of the file system when the archive was created. It is debatable that this would always be a proper behavior. For example, suppose one has an archive in which @file{usr/local} is a link to @file{usr/local2}. Since then, maybe the site removed the link and @@ -4169,11 +4381,12 @@ whole hierarchy just to make room for the link to be reinstated (unless it @emph{also} simultaneously restores the full @file{/usr/local2}, of course!) @GNUTAR{} is indeed able to remove a whole hierarchy to reestablish a symbolic link, for -example, but @emph{only if} @value{op-recursive-unlink} is specified +example, but @emph{only if} @option{--recursive-unlink} is specified to allow this behavior. In any case, single files are silently removed. -Finally, the @value{op-unlink-first} option can improve performance in +@opindex unlink-first, introduced +Finally, the @option{--unlink-first} (@option{-U}) option can improve performance in some cases by causing @command{tar} to remove files unconditionally before extracting them. @@ -4181,12 +4394,12 @@ before extracting them. @unnumberedsubsubsec Overwrite Old Files @table @option +@opindex overwrite @item --overwrite Overwrite existing files and directory metadata when extracting files from an archive. -This -causes @command{tar} to write extracted files into the file system without +This causes @command{tar} to write extracted files into the file system without regard to the files already on the system; i.e., files with the same names as archive members are overwritten when the archive is extracted. It also causes @command{tar} to extract the ownership, permissions, @@ -4197,12 +4410,13 @@ symbolic link itself (if this is possible). Moreover, special devices, empty directories and even symbolic links are automatically removed if they are in the way of extraction. -Be careful when using the @value{op-overwrite} option, particularly when -combined with the @value{op-absolute-names} option, as this combination +Be careful when using the @option{--overwrite} option, particularly when +combined with the @option{--absolute-names} (@option{-P}) option, as this combination can change the contents, ownership or permissions of any file on your system. Also, many systems do not take kindly to overwriting files that are currently being executed. +@opindex overwrite-dir @item --overwrite-dir Overwrite the metadata of directories when extracting files from an archive, but remove other files before extracting. @@ -4212,29 +4426,32 @@ archive, but remove other files before extracting. @unnumberedsubsubsec Keep Old Files @table @option +@opindex keep-old-files @item --keep-old-files @itemx -k Do not replace existing files from archive. The -@value{op-keep-old-files} option prevents @command{tar} from replacing -existing files with files with the same name from the archive. -The @value{op-keep-old-files} option is meaningless with @value{op-list}. -Prevents @command{tar} from replacing files in the file system during -extraction. +@option{--keep-old-files} (@option{-k}) option prevents @command{tar} +from replacing existing files with files with the same name from the +archive. The @option{--keep-old-files} option is meaningless with +@option{--list} (@option{-t}). Prevents @command{tar} from replacing +files in the file system during extraction. @end table @node Keep Newer Files @unnumberedsubsubsec Keep Newer Files @table @option +@opindex keep-newer-files @item --keep-newer-files Do not replace existing files that are newer than their archive -copies. This option is meaningless with @value{op-list}. +copies. This option is meaningless with @option{--list} (@option{-t}). @end table @node Unlink First @unnumberedsubsubsec Unlink First @table @option +@opindex unlink-first @item --unlink-first @itemx -U Remove files before extracting over them. @@ -4247,78 +4464,165 @@ slows @command{tar} down slightly, so it is disabled by default. @unnumberedsubsubsec Recursive Unlink @table @option +@opindex recursive-unlink @item --recursive-unlink When this option is specified, try removing files and directory hierarchies before extracting over them. @emph{This is a dangerous option!} @end table -If you specify the @value{op-recursive-unlink} option, +If you specify the @option{--recursive-unlink} option, @command{tar} removes @emph{anything} that keeps you from extracting a file as far as current permissions will allow it. This could include removal of the contents of a full directory hierarchy. -@node Modification Times -@unnumberedsubsubsec Setting Modification Times +@node Data Modification Times +@unnumberedsubsubsec Setting Data Modification Times -Normally, @command{tar} sets the modification times of extracted files to -the modification times recorded for the files in the archive, but +@cindex Data modification times of extracted files +@cindex Modification times of extracted files +Normally, @command{tar} sets the data modification times of extracted +files to the corresponding times recorded for the files in the archive, but limits the permissions of extracted files by the current @code{umask} setting. -To set the modification times of extracted files to the time when -the files were extracted, use the @value{op-touch} option in -conjunction with @value{op-extract}. +To set the data modification times of extracted files to the time when +the files were extracted, use the @option{--touch} (@option{-m}) option in +conjunction with @option{--extract} (@option{--get}, @option{-x}). @table @option +@opindex touch @item --touch @itemx -m -Sets the modification time of extracted archive members to the time +Sets the data modification time of extracted archive members to the time they were extracted, not the time recorded for them in the archive. -Use in conjunction with @value{op-extract}. +Use in conjunction with @option{--extract} (@option{--get}, @option{-x}). @end table @node Setting Access Permissions @unnumberedsubsubsec Setting Access Permissions +@cindex Permissions of extracted files +@cindex Modes of extracted files To set the modes (access permissions) of extracted files to those recorded for those files in the archive, use @option{--same-permissions} -in conjunction with the @value{op-extract} operation. @FIXME{Should be -aliased to ignore-umask.} +in conjunction with the @option{--extract} (@option{--get}, +@option{-x}) operation. @FIXME{Should be aliased to ignore-umask.} @table @option +@opindex preserve-permission +@opindex same-permission @item --preserve-permission @itemx --same-permission -@itemx --ignore-umask +@c @itemx --ignore-umask @itemx -p Set modes of extracted archive members to those recorded in the archive, instead of current umask settings. Use in conjunction with -@value{op-extract}. +@option{--extract} (@option{--get}, @option{-x}). @end table -@FIXME{Following paragraph needs to be rewritten: why doesn't this cat -files together, why is this useful. is it really useful with -more than one file?} +@node Directory Modification Times and Permissions +@unnumberedsubsubsec Directory Modification Times and Permissions + +After sucessfully extracting a file member, @GNUTAR{} normally +restores its permissions and modification times, as described in the +previous sections. This cannot be done for directories, because +after extracting a directory @command{tar} will almost certainly +extract files into that directory and this will cause the directory +modification time to be updated. Moreover, restoring that directory +permissions may not permit file creation within it. Thus, restoring +directory permissions and modification times must be delayed at least +until all files have been extracted into that directory. @GNUTAR{} +restores directories using the following approach. + +The extracted directories are created with the mode specified in the +archive, as modified by the umask of the user, which gives sufficient +permissions to allow file creation. The meta-information about the +directory is recorded in the temporary list of directories. When +preparing to extract next archive member, @GNUTAR{} checks if the +directory prefix of this file contains the remembered directory. If +it does not, the program assumes that all files have been extracted +into that directory, restores its modification time and permissions +and removes its entry from the internal list. This approach allows +to correctly restore directory meta-information in the majority of +cases, while keeping memory requirements sufficiently small. It is +based on the fact, that most @command{tar} archives use the predefined +order of members: first the directory, then all the files and +subdirectories in that directory. + +However, this is not always true. The most important exception are +incremental archives (@pxref{Incremental Dumps}). The member order in +an incremental archive is reversed: first all directory members are +stored, followed by other (non-directory) members. So, when extracting +from incremental archives, @GNUTAR{} alters the above procedure. It +remebers all restored directories, and restores their meta-data +only after the entire archive has been processed. Notice, that you do +not need to specity any special options for that, as @GNUTAR{} +automatically detects archives in incremental format. + +There may be cases, when such processing is required for normal archives +too. Consider the following example: + +@smallexample +@group +$ @kbd{tar --no-recursion -cvf archive \ + foo foo/file1 bar bar/file foo/file2} +foo/ +foo/file1 +bar/ +bar/file +foo/file2 +@end group +@end smallexample + +During the normal operation, after encountering @file{bar} +@GNUTAR{} will assume that all files from the directory @file{foo} +were already extracted and will therefore restore its timestamp and +permission bits. However, after extracting @file{foo/file2} the +directory timestamp will be offset again. + +To correctly restore directory meta-information in such cases, use +@option{delay-directory-restore} command line option: + +@table @option +@opindex delay-directory-restore +@item --delay-directory-restore +Delays restoring of the modification times and permissions of extracted +directories until the end of extraction. This way, correct +meta-information is restored even if the archive has unusual member +ordering. + +@opindex no-delay-directory-restore +@item --no-delay-directory-restore +Cancel the effect of the previous @option{--delay-directory-restore}. +Use this option if you have used @option{--delay-directory-restore} in +@env{TAR_OPTIONS} variable (@pxref{TAR_OPTIONS}) and wish to +temporarily disable it. +@end table @node Writing to Standard Output @unnumberedsubsubsec Writing to Standard Output +@cindex Writing extracted files to standard output +@cindex Standard output, writing extracted files to To write the extracted files to the standard output, instead of -creating the files on the file system, use @value{op-to-stdout} in -conjunction with @value{op-extract}. This option is useful if you are +creating the files on the file system, use @option{--to-stdout} (@option{-O}) in +conjunction with @option{--extract} (@option{--get}, @option{-x}). This option is useful if you are extracting files to send them through a pipe, and do not need to preserve them in the file system. If you extract multiple members, they appear on standard output concatenated, in the order they are found in the archive. @table @option +@opindex to-stdout @item --to-stdout @itemx -O -Writes files to the standard output. Used in conjunction with -@value{op-extract}. Extract files to standard output. When this option -is used, instead of creating the files specified, @command{tar} writes +Writes files to the standard output. Use only in conjunction with +@option{--extract} (@option{--get}, @option{-x}). When this option is +used, instead of creating the files specified, @command{tar} writes the contents of the files extracted to its standard output. This may be useful if you are only extracting the files in order to send them -through a pipe. This option is meaningless with @value{op-list}. +through a pipe. This option is meaningless with @option{--list} +(@option{-t}). @end table This can be useful, for example, if you have a tar archive containing @@ -4335,6 +4639,124 @@ or even like this if you want to process the concatenation of the files: tar -xOzf foo.tgz bigfile1 bigfile2 | process @end smallexample +Hovewer, @option{--to-command} may be more convenient for use with +multiple files. See the next section. + +@node Writing to an External Program +@unnumberedsubsubsec Writing to an External Program + +You can instruct @command{tar} to send the contents of each extracted +file to the standard input of an external program: + +@table @option +@opindex to-program +@item --to-program=@var{command} +Extract files and pipe their contents to the standard input of +@var{command}. When this option is used, instead of creating the +files specified, @command{tar} invokes @var{command} and pipes the +contents of the files to its standard output. @var{Command} may +contain command line arguments. The program is executed via +@code{sh -c}. Notice, that @var{command} is executed once for each regular file +extracted. Non-regular files (directories, etc.) are ignored when this +option is used. +@end table + +The command can obtain the information about the file it processes +from the following environment variables: + +@table @var +@vrindex TAR_FILETYPE, to-command environment +@item TAR_FILETYPE +Type of the file. It is a single letter with the following meaning: + +@multitable @columnfractions 0.10 0.90 +@item f @tab Regular file +@item d @tab Directory +@item l @tab Symbolic link +@item h @tab Hard link +@item b @tab Block device +@item c @tab Character device +@end multitable + +Currently only regular files are supported. + +@vrindex TAR_MODE, to-command environment +@item TAR_MODE +File mode, an octal number. + +@vrindex TAR_FILENAME, to-command environment +@item TAR_FILENAME +The name of the file. + +@vrindex TAR_REALNAME, to-command environment +@item TAR_REALNAME +Name of the file as stored in the archive. + +@vrindex TAR_UNAME, to-command environment +@item TAR_UNAME +Name of the file owner. + +@vrindex TAR_GNAME, to-command environment +@item TAR_GNAME +Name of the file owner group. + +@vrindex TAR_ATIME, to-command environment +@item TAR_ATIME +Time of last access. It is a decimal number, representing seconds +since the epoch. If the archive provides times with nanosecond +precision, the nanoseconds are appended to the timestamp after a +decimal point. + +@vrindex TAR_MTIME, to-command environment +@item TAR_MTIME +Time of last modification. + +@vrindex TAR_CTIME, to-command environment +@item TAR_CTIME +Time of last status change. + +@vrindex TAR_SIZE, to-command environment +@item TAR_SIZE +Size of the file. + +@vrindex TAR_UID, to-command environment +@item TAR_UID +UID of the file owner. + +@vrindex TAR_GID, to-command environment +@item TAR_GID +GID of the file owner. +@end table + +In addition to these variables, @env{TAR_VERSION} contains the +@GNUTAR{} version number. + +If @var{command} exits with a non-0 status, @command{tar} will print +an error message similar to the following: + +@smallexample +tar: 2345: Child returned status 1 +@end smallexample + +Here, @samp{2345} is the PID of the finished process. + +If this behavior is not wanted, use @option{--ignore-command-error}: + +@table @option +@opindex ignore-command-error +@item --ignore-command-error +Ignore exit codes of subprocesses. Notice that if the program +exits on signal or otherwise terminates abnormally, the error message +will be printed even if this option is used. + +@opindex no-ignore-command-error +@item --no-ignore-command-error +Cancel the effect of any previous @option{--ignore-command-error} +option. This option is useful if you have set +@option{--ignore-command-error} in @env{TAR_OPTIONS} +(@pxref{TAR_OPTIONS}) and wish to temporarily cancel it. +@end table + @node remove files @unnumberedsubsubsec Removing Files @@ -4343,18 +4765,18 @@ option goes in this section. i have no idea; i only know it's nowhere else in the book...} @table @option +@opindex remove-files @item --remove-files Remove files after adding them to the archive. @end table @node Scarce @subsection Coping with Scarce Resources -@cindex Middle of the archive, starting in the -@cindex Running out of space during extraction -@cindex Disk space, running out of -@cindex Space on the disk, recovering from lack of @UNREVISED +@cindex Small memory +@cindex Running out of space + @menu * Starting File:: * Same Order:: @@ -4364,42 +4786,41 @@ Remove files after adding them to the archive. @unnumberedsubsubsec Starting File @table @option +@opindex starting-file @item --starting-file=@var{name} @itemx -K @var{name} Starts an operation in the middle of an archive. Use in conjunction -with @value{op-extract} or @value{op-list}. +with @option{--extract} (@option{--get}, @option{-x}) or @option{--list} (@option{-t}). @end table +@cindex Middle of the archive, starting in the If a previous attempt to extract files failed due to lack of disk -space, you can use @value{op-starting-file} to start extracting only -after member @var{name} of the archive. This assumes, of course, that -there is now free space, or that you are now extracting into a -different file system. (You could also choose to suspend @command{tar}, -remove unnecessary files from the file system, and then restart the -same @command{tar} operation. In this case, @value{op-starting-file} is -not necessary. @value{xref-incremental}, @value{xref-interactive}, -and @value{ref-exclude}.) +space, you can use @option{--starting-file=@var{name}} (@option{-K +@var{name}}) to start extracting only after member @var{name} of the +archive. This assumes, of course, that there is now free space, or +that you are now extracting into a different file system. (You could +also choose to suspend @command{tar}, remove unnecessary files from +the file system, and then restart the same @command{tar} operation. +In this case, @option{--starting-file} is not necessary. +@xref{Incremental Dumps}, @xref{interactive}, and @ref{exclude}.) @node Same Order @unnumberedsubsubsec Same Order @table @option +@cindex Large lists of file names on small machines +@opindex same-order +@opindex preserve-order @item --same-order @itemx --preserve-order @itemx -s To process large lists of file names on machines with small amounts of -memory. Use in conjunction with @value{op-compare}, -@value{op-list} -or @value{op-extract}. +memory. Use in conjunction with @option{--compare} (@option{--diff}, +@option{-d}), @option{--list} (@option{-t}) or @option{--extract} +(@option{--get}, @option{-x}). @end table -@FIXME{we don't need/want --preserve to exist any more (from melissa: -ie, don't want that *version* of the option to exist, or don't want -the option to exist in either version?} - -@FIXME{i think this explanation is lacking.} - -The @value{op-same-order} option tells @command{tar} that the list of file +The @option{--same-order} (@option{--preserve-order}, @option{-s}) option tells @command{tar} that the list of file names to be listed or extracted is sorted in the same order as the files in the archive. This allows a large list of names to be used, even on a small machine that would not otherwise be able to hold all @@ -4448,9 +4869,8 @@ partial extraction of a file, both the backup and the partially extracted file are kept. @table @samp - @item --backup[=@var{method}] -@opindex --backup +@opindex backup @vindex VERSION_CONTROL @cindex backups Back up files that are about to be overwritten or removed. @@ -4469,24 +4889,24 @@ also allows more descriptive names. The valid @var{method}s are: @table @samp @item t @itemx numbered -@opindex numbered @r{backup method} +@cindex numbered @r{backup method} Always make numbered backups. @item nil @itemx existing -@opindex existing @r{backup method} +@cindex existing @r{backup method} Make numbered backups of files that already have them, simple backups of the others. @item never @itemx simple -@opindex simple @r{backup method} +@cindex simple @r{backup method} Always make simple backups. @end table @item --suffix=@var{suffix} -@opindex --suffix +@opindex suffix @cindex backup suffix @vindex SIMPLE_BACKUP_SUFFIX Append @var{suffix} to each backup file made with @option{--backup}. If this @@ -4496,7 +4916,7 @@ set, the default is @samp{~}, just as in Emacs. @end table -Some people express the desire to @emph{always} use the @value{op-backup} +Some people express the desire to @emph{always} use the @option{--backup} option, by defining some kind of alias or script. This is not as easy as one may think, due to the fact that old style options should appear first and consume arguments a bit unpredictably for an alias or script. But, @@ -4562,7 +4982,7 @@ remember to stick it in here. :-)} If there are too many files to conveniently list on the command line, you can list the names in a file, and @command{tar} will read that file. -@value{xref-files-from}. +@xref{files}. There are various ways of causing @command{tar} to skip over some files, and not archive them. @xref{Choosing}. @@ -4589,48 +5009,52 @@ http://www.cs.umd.edu/projects/amanda/amanda.html ftp://ftp.cs.umd.edu/pub/amanda @end smallexample -@ifclear PUBLISH +@FIXME{ Here is a possible plan for a future documentation about the backuping scripts which are provided within the @GNUTAR{} distribution. -@smallexample -.* dumps -. + what are dumps - -. + different levels of dumps -. - full dump = dump everything -. - level 1, level 2 dumps etc, - - A level n dump dumps everything changed since the last level - n-1 dump (?) - -. + how to use scripts for dumps (ie, the concept) -. - scripts to run after editing backup specs (details) - -. + Backup Specs, what is it. -. - how to customize -. - actual text of script [/sp/dump/backup-specs] - -. + Problems -. - rsh doesn't work -. - rtape isn't installed -. - (others?) - -. + the --incremental option of tar - -. + tapes -. - write protection -. - types of media -. : different sizes and types, useful for different things -. - files and tape marks +@itemize @bullet +@item dumps + @itemize @minus + @item what are dumps + @item different levels of dumps + @itemize + + @item full dump = dump everything + @item level 1, level 2 dumps etc + A level @var{n} dump dumps everything changed since the last level + @var{n}-1 dump (?) + @end itemize + @item how to use scripts for dumps (ie, the concept) + @itemize + + @item scripts to run after editing backup specs (details) + @end itemize + @item Backup Specs, what is it. + @itemize + + @item how to customize + @item actual text of script [/sp/dump/backup-specs] + @end itemize + @item Problems + @itemize + + @item rsh doesn't work + @item rtape isn't installed + @item (others?) + @end itemize + @item the @option{--incremental} option of tar + @item tapes + @itemize + + @item write protection + @item types of media, different sizes and types, useful for different things + @item files and tape marks one tape mark between files, two at end. -. - positioning the tape + @item positioning the tape MT writes two at end of write, - backspaces over one when writing again. -@end smallexample - -@end ifclear + backspaces over one when writing again. + @end itemize + @end itemize +@end itemize +} This chapter documents both the provided shell scripts and @command{tar} options which are more specific to usage as a backup tool. @@ -4643,8 +5067,7 @@ called @dfn{dumps}. @menu * Full Dumps:: Using @command{tar} to Perform Full Dumps -* Inc Dumps:: Using @command{tar} to Perform Incremental Dumps -* incremental and listed-incremental:: The Incremental Options +* Incremental Dumps:: Using @command{tar} to Perform Incremental Dumps * Backup Levels:: Levels of Backups * Backup Parameters:: Setting Parameters for Backups and Restoration * Scripted Backups:: Using the Backup Scripts @@ -4660,227 +5083,224 @@ called @dfn{dumps}. @cindex corrupted archives Full dumps should only be made when no other people or programs -are modifying files in the filesystem. If files are modified while +are modifying files in the file system. If files are modified while @command{tar} is making the backup, they may not be stored properly in the archive, in which case you won't be able to restore them if you have to. (Files not being modified are written with no trouble, and do not corrupt the entire archive.) -You will want to use the @value{op-label} option to give the archive a +You will want to use the @option{--label=@var{archive-label}} +(@option{-V @var{archive-label}}) option to give the archive a volume label, so you can tell what this archive is even if the label falls off the tape, or anything like that. -Unless the filesystem you are dumping is guaranteed to fit on -one volume, you will need to use the @value{op-multi-volume} option. +Unless the file system you are dumping is guaranteed to fit on +one volume, you will need to use the @option{--multi-volume} (@option{-M}) option. Make sure you have enough tapes on hand to complete the backup. -If you want to dump each filesystem separately you will need to use -the @value{op-one-file-system} option to prevent @command{tar} from crossing -filesystem boundaries when storing (sub)directories. +If you want to dump each file system separately you will need to use +the @option{--one-file-system} (@option{-l}) option to prevent +@command{tar} from crossing file system boundaries when storing +(sub)directories. -The @value{op-incremental} option is not needed, since this is a complete -copy of everything in the filesystem, and a full restore from this -backup would only be done onto a completely empty disk. +The @option{--incremental} (@option{-G}) (@pxref{Incremental Dumps}) +option is not needed, since this is a complete copy of everything in +the file system, and a full restore from this backup would only be +done onto a completely +empty disk. Unless you are in a hurry, and trust the @command{tar} program (and your -tapes), it is a good idea to use the @value{op-verify} option, to make -sure your files really made it onto the dump properly. This will -also detect cases where the file was modified while (or just after) -it was being archived. Not all media (notably cartridge tapes) are -capable of being verified, unfortunately. - -@value{op-listed-incremental} take a file name argument always. If the -file doesn't exist, run a level zero dump, creating the file. If the -file exists, uses that file to see what has changed. - -@value{op-incremental} @FIXME{look it up} - -@value{op-incremental} handle old @acronym{GNU}-format incremental backup. - -This option should only be used when creating an incremental backup of -a filesystem. When the @value{op-incremental} option is used, @command{tar} -writes, at the beginning of the archive, an entry for each of the -directories that will be operated on. The entry for a directory -includes a list of all the files in the directory at the time the -dump was done, and a flag for each file indicating whether the file -is going to be put in the archive. This information is used when -doing a complete incremental restore. - -Note that this option causes @command{tar} to create a non-standard -archive that may not be readable by non-@acronym{GNU} versions of the -@command{tar} program. - -The @value{op-incremental} option means the archive is an incremental -backup. Its meaning depends on the command that it modifies. - -If the @value{op-incremental} option is used with @value{op-list}, -@command{tar} will list, for each directory in the archive, the list -of files in that directory at the time the archive was created. This -information is put out in a format that is not easy for humans to -read, but which is unambiguous for a program: each file name is -preceded by either a @samp{Y} if the file is present in the archive, -an @samp{N} if the file is not included in the archive, or a @samp{D} -if the file is a directory (and is included in the archive). Each -file name is terminated by a null character. The last file is -followed by an additional null and a newline to indicate the end of -the data. - -If the @value{op-incremental} option is used with @value{op-extract}, then -when the entry for a directory is found, all files that currently -exist in that directory but are not listed in the archive @emph{are -deleted from the directory}. - -This behavior is convenient when you are restoring a damaged file -system from a succession of incremental backups: it restores the -entire state of the file system to that which obtained when the backup -was made. If you don't use @value{op-incremental}, the file system will -probably fill up with files that shouldn't exist any more. - -@value{op-listed-incremental} handle new @acronym{GNU}-format -incremental backup. This option handles new @acronym{GNU}-format -incremental backup. It has much the same effect as -@value{op-incremental}, but also the time when the dump is done and -the list of directories dumped is written to the given -@var{file}. When restoring, only files newer than the saved time are -restored, and the directory list is used to speed up operations. - -@value{op-listed-incremental} acts like @value{op-incremental}, but when -used in conjunction with @value{op-create} will also cause @command{tar} to -use the file @var{file}, which contains information about the state -of the filesystem at the time of the last backup, to decide which -files to include in the archive being created. That file will then -be updated by @command{tar}. If the file @var{file} does not exist when -this option is specified, @command{tar} will create it, and include all -appropriate files in the archive. - -The file, which is archive independent, contains the date it was last -modified and a list of devices, inode numbers and directory names. -@command{tar} will archive files with newer mod dates or inode change -times, and directories with an unchanged inode number and device but -a changed directory name. The file is updated after the files to -be archived are determined, but before the new archive is actually -created. - -@node Inc Dumps +tapes), it is a good idea to use the @option{--verify} (@option{-W}) +option, to make sure your files really made it onto the dump properly. +This will also detect cases where the file was modified while (or just +after) it was being archived. Not all media (notably cartridge tapes) +are capable of being verified, unfortunately. + +@node Incremental Dumps @section Using @command{tar} to Perform Incremental Dumps -@UNREVISED -@cindex incremental dumps -@cindex dumps, incremental +@dfn{Incremental backup} is a special form of @GNUTAR{} archive that +stores additional metadata so that exact state of the file system +can be restored when extracting the archive. + +@GNUTAR{} currently offers two options for handling incremental +backups: @option{--listed-incremental=@var{snapshot-file}} (@option{-g +@var{snapshot-file}}) and @option{--incremental} (@option{-G}). -Performing incremental dumps is similar to performing full dumps, -although a few more options will usually be needed. +@opindex listed-incremental +The option @option{--listed-incremental} instructs tar to operate on +an incremental archive with additional metadata stored in a standalone +file, called a @dfn{snapshot file}. The purpose of this file is to help +determine which files have been changed, added or deleted since the +last backup, so that the next incremental backup will contain only +modified files. The name of the snapshot file is given as an argument +to the option: -A standard scheme is to do a @emph{monthly} (full) dump once a month, -a @emph{weekly} dump once a week of everything since the last monthly -and a @emph{daily} every day of everything since the last (weekly or -monthly) dump. +@table @option +@item --listed-incremental=@var{file} +@itemx -g @var{file} + Handle incremental backups with snapshot data in @var{file}. +@end table -Here is a sample script to dump the directory hierarchies @samp{/usr} -and @samp{/var}. +To create an incremental backup, you would use +@option{--listed-incremental} together with @option{--create} +(@pxref{create}). For example: @smallexample -#! /bin/sh -tar --create \ - --blocking-factor=126 \ - --file=/dev/rmt/0 \ - --label="`hostname` /usr /var `date +%Y-%m-%d`" \ - --listed-incremental=/var/log/usr-var.snar \ - --verbose \ - /usr /var +$ @kbd{tar --create \ + --file=archive.1.tar \ + --listed-incremental=/var/log/usr.snar \ + /usr} @end smallexample -This script uses the file @file{/var/log/usr-var.snar} as a snapshot to -store information about the previous tar dump. +This will create in @file{archive.1.tar} an incremental backup of +the @file{/usr} file system, storing additional metadata in the file +@file{/var/log/usr.snar}. If this file does not exist, it will be +created. The created archive will then be a @dfn{level 0 backup}; +please see the next section for more on backup levels. -The blocking factor 126 is an attempt to make the tape drive stream. -Some tape devices cannot handle 64 kB blocks or larger, and require the -block size to be a multiple of 1 kB; for these devices, 126 is the -largest blocking factor that can be used. +Otherwise, if the file @file{/var/log/usr.snar} exists, it +determines which files are modified. In this case only these files will be +stored in the archive. Suppose, for example, that after running the +above command, you delete file @file{/usr/doc/old} and create +directory @file{/usr/local/db} with the following contents: -@node incremental and listed-incremental -@section The Incremental Options -@UNREVISED +@smallexample +$ @kbd{ls /usr/local/db} +/usr/local/db/data +/usr/local/db/index +@end smallexample + +Some time later you create another incremental backup. You will +then see: + +@smallexample +$ @kbd{tar --create \ + --file=archive.2.tar \ + --listed-incremental=/var/log/usr.snar \ + /usr} +tar: usr/local/db: Directory is new +usr/local/db/ +usr/local/db/data +usr/local/db/index +@end smallexample + +@noindent +The created archive @file{archive.2.tar} will contain only these +three members. This archive is called a @dfn{level 1 backup}. Notice +that @file{/var/log/usr.snar} will be updated with the new data, so if +you plan to create more @samp{level 1} backups, it is necessary to +create a working copy of the snapshot file before running +@command{tar}. The above example will then be modified as follows: -@value{op-incremental} is used in conjunction with @value{op-create}, -@value{op-extract} or @value{op-list} when backing up and restoring file -systems. An archive cannot be extracted or listed with the -@value{op-incremental} option specified unless it was created with the -option specified. This option should only be used by a script, not by -the user, and is usually disregarded in favor of -@value{op-listed-incremental}, which is described below. - -@value{op-incremental} in conjunction with @value{op-create} causes -@command{tar} to write, at the beginning of the archive, an entry for -each of the directories that will be archived. The entry for a -directory includes a list of all the files in the directory at the -time the archive was created and a flag for each file indicating -whether or not the file is going to be put in the archive. - -Note that this option causes @command{tar} to create a non-standard -archive that may not be readable by non-@acronym{GNU} versions of the -@command{tar} program. - -@value{op-incremental} in conjunction with @value{op-extract} causes -@command{tar} to read the lists of directory contents previously stored -in the archive, @emph{delete} files in the file system that did not -exist in their directories when the archive was created, and then -extract the files in the archive. - -This behavior is convenient when restoring a damaged file system from -a succession of incremental backups: it restores the entire state of -the file system to that which obtained when the backup was made. If -@value{op-incremental} isn't specified, the file system will probably -fill up with files that shouldn't exist any more. - -@value{op-incremental} in conjunction with @value{op-list} causes -@command{tar} to print, for each directory in the archive, the list of -files in that directory at the time the archive was created. This -information is put out in a format that is not easy for humans to -read, but which is unambiguous for a program: each file name is -preceded by either a @samp{Y} if the file is present in the archive, -an @samp{N} if the file is not included in the archive, or a @samp{D} -if the file is a directory (and is included in the archive). Each -file name is terminated by a null character. The last file is followed -by an additional null and a newline to indicate the end of the data. - -@value{op-listed-incremental} acts like @value{op-incremental}, but when -used in conjunction with @value{op-create} will also cause @command{tar} -to use the file @var{snapshot-file}, which contains information about -the state of the file system at the time of the last backup, to decide -which files to include in the archive being created. That file will -then be updated by @command{tar}. If the file @var{file} does not exist -when this option is specified, @command{tar} will create it, and include -all appropriate files in the archive. - -The file @var{file}, which is archive independent, contains the date -it was last modified and a list of devices, inode numbers and -directory names. @command{tar} will archive files with newer mod dates -or inode change times, and directories with an unchanged inode number -and device but a changed directory name. The file is updated after -the files to be archived are determined, but before the new archive is -actually created. +@smallexample +$ @kbd{cp /var/log/usr.snar /var/log/usr.snar-1} +$ @kbd{tar --create \ + --file=archive.2.tar \ + --listed-incremental=/var/log/usr.snar-1 \ + /usr} +@end smallexample Incremental dumps depend crucially on time stamps, so the results are unreliable if you modify a file's time stamps during dumping (e.g., -with the @option{--atime-preserve} option), or if you set the clock +with the @option{--atime-preserve=replace} option), or if you set the clock backwards. -Despite it should be obvious that a device has a non-volatile value, NFS -devices have non-dependable values when an automounter gets in the picture. -This led to a great deal of spurious redumping in incremental dumps, -so it is somewhat useless to compare two NFS devices numbers over time. -So @command{tar} now considers all NFS devices as being equal when it comes -to comparing directories; this is fairly gross, but there does not seem +Metadata stored in snapshot files include device numbers, which, +obviously is supposed to be a non-volatile value. However, it turns +out that NFS devices have undependable values when an automounter +gets in the picture. This can lead to a great deal of spurious +redumping in incremental dumps, so it is somewhat useless to compare +two NFS devices numbers over time. The solution implemented currently +is to considers all NFS devices as being equal when it comes to +comparing directories; this is fairly gross, but there does not seem to be a better way to go. -@command{tar} doesn't access @var{snapshot-file} when -@value{op-extract} or @value{op-list} are specified, but the -@value{op-listed-incremental} option must still be given. A -placeholder @var{snapshot-file} can be specified, e.g., -@file{/dev/null}. +Note that incremental archives use @command{tar} extensions and may +not be readable by non-@acronym{GNU} versions of the @command{tar} program. + +@opindex listed-incremental, using with @option{--extract} +@opindex extract, using with @option{--listed-incremental} +To extract from the incremental dumps, use +@option{--listed-incremental} together with @option{--extract} +option (@pxref{extracting files}). In this case, @command{tar} does +not need to access snapshot file, since all the data necessary for +extraction are stored in the archive itself. So, when extracting, you +can give whatever argument to @option{--listed-incremental}, the usual +practice is to use @option{--listed-incremental=/dev/null}. +Alternatively, you can use @option{--incremental}, which needs no +arguments. In general, @option{--incremental} (@option{-G}) can be +used as a shortcut for @option{--listed-incremental} when listing or +extracting incremental backups (for more information, regarding this +option, @pxref{incremental-op}). + +When extracting from the incremental backup @GNUTAR{} attempts to +restore the exact state the file system had when the archive was +created. In particular, it will @emph{delete} those files in the file +system that did not exist in their directories when the archive was +created. If you have created several levels of incremental files, +then in order to restore the exact contents the file system had when +the last level was created, you will need to restore from all backups +in turn. Continuing our example, to restore the state of @file{/usr} +file system, one would do@footnote{Notice, that since both archives +were created withouth @option{-P} option (@pxref{absolute}), these +commands should be run from the root file system.}: + +@smallexample +$ @kbd{tar --extract \ + --listed-incremental=/dev/null \ + --file archive.1.tar} +$ @kbd{tar --extract \ + --listed-incremental=/dev/null \ + --file archive.2.tar} +@end smallexample + +To list the contents of an incremental archive, use @option{--list} +(@pxref{list}), as usual. To obtain more information about the +archive, use @option{--listed-incremental} or @option{--incremental} +combined with two @option{--verbose} options@footnote{Two +@option{--verbose} options were selected to avoid breaking usual +verbose listing output (@option{--list --verbose}) when using in +scripts. + +@opindex incremental, using with @option{--list} +@opindex listed-incremental, using with @option{--list} +@opindex list, using with @option{--incremental} +@opindex list, using with @option{--listed-incremental} +Versions of @GNUTAR{} up to 1.15.1 used to dump verbatim binary +contents of the DUMPDIR header (with terminating nulls) when +@option{--incremental} or @option{--listed-incremental} option was +given, no matter what the verbosity level. This behavior, and, +especially, the binary output it produced were considered incovenient +and were changed in version 1.16}: + +@smallexample +@kbd{tar --list --incremental --verbose --verbose archive.tar} +@end smallexample + +This command will print, for each directory in the archive, the list +of files in that directory at the time the archive was created. This +information is put out in a format which is both human-readable and +unambiguous for a program: each file name is printed as -@FIXME{this section needs to be written} +@smallexample +@var{x} @var{file} +@end smallexample + +@noindent +where @var{x} is a letter describing the status of the file: @samp{Y} +if the file is present in the archive, @samp{N} if the file is not +included in the archive, or a @samp{D} if the file is a directory (and +is included in the archive).@FIXME-xref{dumpdir format}. Each such +line is terminated by a newline character. The last line is followed +by an additional newline to indicate the end of the data. + +@anchor{incremental-op}The option @option{--incremental} (@option{-G}) +gives the same behavior as @option{--listed-incremental} when used +with @option{--list} and @option{--extract} options. When used with +@option{--create} option, it creates an incremental archive without +creating snapshot file. Thus, it is impossible to create several +levels of incremental backups with @option{--incremental} option. @node Backup Levels @section Levels of Backups @@ -4914,9 +5334,9 @@ and @command{tar} commands by hand. Before you use these scripts, you need to edit the file @file{backup-specs}, which specifies parameters used by the backup scripts and by the restore script. This file is usually located -in @file{/etc/backup} directory. @FIXME-xref{Script Syntax} Once the -backup parameters are set, you can perform backups or restoration by -running the appropriate script. +in @file{/etc/backup} directory. @xref{Backup Parameters}, for its +detailed description. Once the backup parameters are set, you can +perform backups or restoration by running the appropriate script. The name of the backup script is @code{backup}. The name of the restore script is @code{restore}. The following sections describe @@ -4926,8 +5346,8 @@ their use in detail. designed to be used together. While it is possible to restore files by hand from an archive which was created using a backup script, and to create an archive by hand which could then be extracted using the restore script, -it is easier to use the scripts. @value{xref-incremental}, and -@value{xref-listed-incremental}, before making such an attempt. +it is easier to use the scripts. @xref{Incremental Dumps}, before +making such an attempt. @node Backup Parameters @section Setting Parameters for Backups and Restoration @@ -4985,7 +5405,7 @@ invocations of @command{mt}. @defvr {Backup variable} BLOCKING The blocking factor @command{tar} will use when writing the dump archive. -@value{xref-blocking-factor}. +@xref{Blocking Factor}. @end defvr @defvr {Backup variable} BACKUP_DIRS @@ -5014,7 +5434,7 @@ in a separate file. This file is usually named @defvr {Backup variable} DIRLIST -A path to the file containing the list of the filesystems to backup +A path to the file containing the list of the file systems to backup or restore. By default it is @file{/etc/backup/dirs}. @end defvr @@ -5058,7 +5478,7 @@ of @GNUTAR{}. @defvr {Backup variable} VOLNO_FILE Name of temporary file to hold volume numbers. This needs to be accessible -by all the machines which have filesystems to be dumped. +by all the machines which have file systems to be dumped. @end defvr @defvr {Backup variable} XLIST @@ -5075,7 +5495,7 @@ This variable affects only @code{backup}. @defvr {Backup variable} SLEEP_TIME -Time to sleep between dumps of any two successive filesystems +Time to sleep between dumps of any two successive file systems This variable affects only @code{backup}. @end defvr @@ -5182,10 +5602,10 @@ Current backup or restore level. Name or IP address of the host machine being dumped or restored. @item fs -Full path name to the filesystem being dumped or restored. +Full path name to the file system being dumped or restored. @item fsname -Filesystem name with directory separators replaced with colons. This +File system name with directory separators replaced with colons. This is useful, e.g., for creating unique files. @end table @end deffn @@ -5193,19 +5613,19 @@ is useful, e.g., for creating unique files. Following variables keep the names of user hook functions @defvr {Backup variable} DUMP_BEGIN -Dump begin function. It is executed before dumping the filesystem. +Dump begin function. It is executed before dumping the file system. @end defvr @defvr {Backup variable} DUMP_END -Executed after dumping the filesystem. +Executed after dumping the file system. @end defvr @defvr {Backup variable} RESTORE_BEGIN -Executed before restoring the filesystem. +Executed before restoring the file system. @end defvr @defvr {Backup variable} RESTORE_END -Executed after restoring the filesystem. +Executed after restoring the file system. @end defvr @node backup-specs example @@ -5305,8 +5725,8 @@ The backup scripts write two files on the file system. The first is a record file in @file{/etc/tar-backup/}, which is used by the scripts to store and retrieve information about which files were dumped. This file is not meant to be read by humans, and should not be deleted by -them. @FIXME-xref{incremental and listed-incremental, for a more -detailed explanation of this file.} +them. @xref{Snapshot Files}, for a more detailed explanation of this +file. The second file is a log file containing the names of the file systems and files dumped, what time the backup was made, and any error @@ -5345,13 +5765,10 @@ Wait till @var{time}, then do backup. @itemx --help Display short help message and exit. -@item -L -@itemx --license -Display program license and exit. - @item -V @itemx --version -Display program version and exit. +Display information about the program's name, version, origin and legal +status, all on standard output, and then exit successfully. @end table @@ -5361,10 +5778,10 @@ Display program version and exit. To restore files that were archived using a scripted backup, use the @code{restore} script. Its usage is quite straightforward. In the simplest form, invoke @code{restore --all}, it will -then restore all the filesystems and files specified in +then restore all the file systems and files specified in @file{backup-specs} (@pxref{General-Purpose Variables,BACKUP_DIRS}). -You may select the filesystems (and/or files) to restore by +You may select the file systems (and/or files) to restore by giving @code{restore} list of @dfn{patterns} in its command line. For example, running @@ -5373,7 +5790,7 @@ restore 'albert:*' @end smallexample @noindent -will restore all filesystems on the machine @samp{albert}. A more +will restore all file systems on the machine @samp{albert}. A more complicated example: @smallexample @@ -5381,8 +5798,8 @@ restore 'albert:*' '*:/var' @end smallexample @noindent -This command will restore all filesystems on the machine @samp{albert} -as well as @file{/var} filesystem on all machines. +This command will restore all file systems on the machine @samp{albert} +as well as @file{/var} file system on all machines. By default @code{restore} will start restoring files from the lowest available dump level (usually zero) and will continue through @@ -5400,7 +5817,7 @@ The full list of options accepted by @code{restore} follows: @table @option @item -a @itemx --all -Restore all filesystems and files specified in @file{backup-specs} +Restore all file systems and files specified in @file{backup-specs} @item -l @var{level} @itemx --level=@var{level} @@ -5416,13 +5833,10 @@ is 100, which means the highest debugging level. @itemx --help Display short help message and exit. -@item -L -@itemx --license -Display program license and exit. - @item -V @itemx --version -Display program version and exit. +Display information about the program's name, version, origin and legal +status, all on standard output, and then exit successfully. @end table You should start the restore script with the media containing the @@ -5438,8 +5852,8 @@ positioning.} system if they were not in the file system when the archive was made. @end quotation -@value{xref-incremental}, and @value{ref-listed-incremental}, -for an explanation of how the script makes that determination. +@xref{Incremental Dumps}, for an explanation of how the script makes +that determination. @node Choosing @chapter Choosing Files and Names for @command{tar} @@ -5461,31 +5875,31 @@ are in specified directories. * Wildcards:: * after:: Operating Only on New Files * recurse:: Descending into Directories -* one:: Crossing Filesystem Boundaries +* one:: Crossing File System Boundaries @end menu @node file @section Choosing and Naming Archive Files -@cindex Naming an archive -@cindex Archive Name -@cindex Directing output -@cindex Choosing an archive file -@cindex Where is the archive? @UNREVISED @FIXME{should the title of this section actually be, "naming an archive"?} +@cindex Naming an archive +@cindex Archive Name +@cindex Choosing an archive file +@cindex Where is the archive? By default, @command{tar} uses an archive file name that was compiled when it was built on the system; usually this name refers to some physical tape drive on the machine. However, the person who installed @command{tar} on the system may not set the default to a meaningful value as far as most users are concerned. As a result, you will usually want to tell -@command{tar} where to find (or create) the archive. The @value{op-file} +@command{tar} where to find (or create) the archive. The @option{--file=@var{archive-name}} (@option{-f @var{archive-name}}) option allows you to either specify or name a file to use as the archive instead of the default archive file location. @table @option +@opindex file, short description @item --file=@var{archive-name} @itemx -f @var{archive-name} Name the archive to create or operate on. Use in conjunction with @@ -5551,6 +5965,8 @@ prompt you for a username and password. If you use will complete the remote connection, if possible, using your username as the username on the remote machine. +@cindex Local and remote archives +@anchor{local and remote archives} If the archive file name includes a colon (@samp{:}), then it is assumed to be a file on another machine. If the archive file is @samp{@var{user}@@@var{host}:@var{file}}, then @var{file} is used on the @@ -5564,7 +5980,7 @@ the @GNUTAR{} distribution and by default is installed under @file{@var{prefix}/libexec/rmt}, were @var{prefix} means your installation prefix). If you need to use a file whose name includes a colon, then the remote tape drive behavior -can be inhibited by using the @value{op-force-local} option. +can be inhibited by using the @option{--force-local} option. @FIXME{i know we went over this yesterday, but bob (and now i do again, too) thinks it's out of the middle of nowhere. it doesn't seem to tie @@ -5601,9 +6017,9 @@ If you specify a directory name as a file name argument, all the files in that directory are operated on by @command{tar}. If you do not specify files when @command{tar} is invoked with -@value{op-create}, @command{tar} operates on all the non-directory files in -the working directory. If you specify either @value{op-list} or -@value{op-extract}, @command{tar} operates on all the archive members in the +@option{--create} (@option{-c}), @command{tar} operates on all the non-directory files in +the working directory. If you specify either @option{--list} (@option{-t}) or +@option{--extract} (@option{--get}, @option{-x}), @command{tar} operates on all the archive members in the archive. If you specify any operation other than one of these three, @command{tar} does nothing. @@ -5621,13 +6037,14 @@ specifying the names of files and archive members. @cindex File Name arguments, alternatives 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 -@value{op-files-from} option to @command{tar}. Give the name of the file +@option{--files-from=@var{file-of-names}} (@option{-T @var{file-of-names}}) option to @command{tar}. Give the name of the file which contains the list of files to include as the argument to @option{--files-from}. In the list, the file names should be separated by newlines. You will frequently use this option when you have generated the list of files to archive with the @command{find} utility. @table @option +@opindex files-from @item --files-from=@var{file name} @itemx -T @var{file name} Get names to extract or create from file @var{file name}. @@ -5696,6 +6113,7 @@ libc.a @end smallexample @noindent +@opindex directory, using in @option{--files-from} argument Notice that the option parsing algorithm used with @option{-T} is stricter than the one used by shell. Namely, when specifying option arguments, you should observe the following rules: @@ -5733,7 +6151,7 @@ dir @end smallexample @end itemize -@cindex @option{--add-file} +@opindex add-file If you happen to have a file whose name starts with @samp{-}, precede it with @option{--add-file} option to prevent it from being recognized as an option. For example: @code{--add-file --my-file}. @@ -5747,20 +6165,21 @@ being recognized as an option. For example: @code{--add-file --my-file}. @cindex File names, terminated by @code{NUL} @cindex @code{NUL} terminated file names -The @value{op-null} option causes @value{op-files-from} to read file +The @option{--null} option causes @option{--files-from=@var{file-of-names}} (@option{-T @var{file-of-names}}) to read file names terminated by a @code{NUL} instead of a newline, so files whose names contain newlines can be archived using @option{--files-from}. @table @option +@opindex null @item --null Only consider @code{NUL} terminated file names, instead of files that terminate in a newline. @end table -The @value{op-null} option is just like the one in @acronym{GNU} +The @option{--null} option is just like the one in @acronym{GNU} @command{xargs} and @command{cpio}, and is useful with the @option{-print0} predicate of @acronym{GNU} @command{find}. In -@command{tar}, @value{op-null} also disables special handling for +@command{tar}, @option{--null} also disables special handling for file names that begin with dash. This example shows how to use @command{find} to generate a list of files @@ -5782,21 +6201,22 @@ $ @kbd{tar -c -v --null --files-from=long-files --file=big.tar} @node exclude @section Excluding Some Files +@UNREVISED + @cindex File names, excluding files by @cindex Excluding files by name and pattern @cindex Excluding files by file system -@UNREVISED - To avoid operating on files whose names match a particular pattern, -use the @value{op-exclude} or @value{op-exclude-from} options. +use the @option{--exclude} or @option{--exclude-from} options. @table @option +@opindex exclude @item --exclude=@var{pattern} Causes @command{tar} to ignore files that match the @var{pattern}. @end table @findex exclude -The @value{op-exclude} option prevents any file or member whose name +The @option{--exclude=@var{pattern}} option prevents any file or member whose name matches the shell wildcard (@var{pattern}) from being operated on. For example, to create an archive with all the contents of the directory @file{src} except for files whose names end in @file{.o}, use the @@ -5805,6 +6225,7 @@ command @samp{tar -cf src.tar --exclude='*.o' src}. You may give multiple @option{--exclude} options. @table @option +@opindex exclude-from @item --exclude-from=@var{file} @itemx -X @var{file} Causes @command{tar} to ignore files that match the patterns listed in @@ -5812,7 +6233,7 @@ Causes @command{tar} to ignore files that match the patterns listed in @end table @findex exclude-from -Use the @option{--exclude-from=@var{file-of-patterns}} option to read a +Use the @option{--exclude-from} option to read a list of patterns, one per line, from @var{file}; @command{tar} will ignore files matching those patterns. Thus if @command{tar} is called as @w{@samp{tar -c -X foo .}} and the file @file{foo} contains a @@ -5823,29 +6244,27 @@ added to the archive. newlines the same as the files-from option does?} @table @option +@opindex exclude-caches @item --exclude-caches Causes @command{tar} to ignore directories containing a cache directory tag. @end table @findex exclude-caches -When creating an archive, -the @option{--exclude-caches} option -causes @command{tar} to exclude all directories -that contain a @dfn{cache directory tag}. -A cache directory tag is a short file -with the well-known name @file{CACHEDIR.TAG} -and having a standard header +When creating an archive, the @option{--exclude-caches} option causes +@command{tar} to exclude all directories that contain a @dfn{cache +directory tag}. A cache directory tag is a short file with the +well-known name @file{CACHEDIR.TAG} and having a standard header specified in @url{http://www.brynosaurus.com/cachedir/spec.html}. -Various applications write cache directory tags -into directories they use to hold regenerable, non-precious data, -so that such data can be more easily excluded from backups. +Various applications write cache directory tags into directories they +use to hold regenerable, non-precious data, so that such data can be +more easily excluded from backups. @menu -* controlling pattern-patching with exclude:: +* controlling pattern-matching with exclude:: * problems with exclude:: @end menu -@node controlling pattern-patching with exclude +@node controlling pattern-matching with exclude @unnumberedsubsec Controlling Pattern-Matching with the @code{exclude} Options Normally, a pattern matches a name if an initial subsequence of the @@ -5869,17 +6288,23 @@ ignores case when excluding @samp{makefile}, but not when excluding @samp{readme}. @table @option +@opindex anchored +@opindex no-anchored @item --anchored @itemx --no-anchored If anchored, a pattern must match an initial subsequence of the name's components. Otherwise, the pattern can match any subsequence. Default is @option{--no-anchored}. +@opindex ignore-case +@opindex no-ignore-case @item --ignore-case @itemx --no-ignore-case When ignoring case, upper-case patterns match lower-case names and vice versa. When not ignoring case (the default), matching is case-sensitive. +@opindex wildcards +@opindex no-wildcards @item --wildcards @itemx --no-wildcards When using wildcards (the default), @samp{*}, @samp{?}, and @samp{[...]} @@ -5887,6 +6312,8 @@ are the usual shell wildcards, and @samp{\} escapes wildcards. Otherwise, none of these characters are special, and patterns must match names literally. +@opindex wildcards-match-slash +@opindex no-wildcards-match-slash @item --wildcards-match-slash @itemx --no-wildcards-match-slash When wildcards match slash (the default), a wildcard like @samp{*} in @@ -5903,6 +6330,7 @@ the name's parent directories. @node problems with exclude @unnumberedsubsec Problems with Using the @code{exclude} Options +@opindex exclude, potential problems with Some users find @samp{exclude} options confusing. Here are some common pitfalls: @@ -5916,15 +6344,15 @@ explicitly name the file @samp{dir.o/foo} after all the options have been listed, @samp{dir.o/foo} will be excluded from the archive. @item -You can sometimes confuse the meanings of @value{op-exclude} and -@value{op-exclude-from}. Be careful: use @value{op-exclude} when files +You can sometimes confuse the meanings of @option{--exclude} and +@option{--exclude-from}. Be careful: use @option{--exclude} when files to be excluded are given as a pattern on the command line. Use -@option{--exclude-from=@var{file-of-patterns}} to introduce the name of a -file which contains a list of patterns, one per line; each of these -patterns can exclude zero, one, or many files. +@option{--exclude-from} to introduce the name of a file which contains +a list of patterns, one per line; each of these patterns can exclude +zero, one, or many files. @item -When you use @value{op-exclude}, be sure to quote the @var{pattern} +When you use @option{--exclude=@var{pattern}}, be sure to quote the @var{pattern} parameter, so @GNUTAR{} sees wildcard characters like @samp{*}. If you do not do this, the shell might expand the @samp{*} itself using files at hand, so @command{tar} might receive a @@ -5952,11 +6380,10 @@ might fail. @item In earlier versions of @command{tar}, what is now the -@option{--exclude-from=@var{file-of-patterns}} option was called -@option{--exclude=@var{pattern}} instead. Now, -@option{--exclude=@var{pattern}} applies to patterns listed on the command -line and @option{--exclude-from=@var{file-of-patterns}} applies to -patterns listed in a file. +@option{--exclude-from} option was called @option{--exclude} instead. +Now, @option{--exclude} applies to patterns listed on the command +line and @option{--exclude-from} applies to patterns listed in a +file. @end itemize @@ -5967,7 +6394,7 @@ patterns listed in a file. @samp{*} or @samp{?} for example, are replaced and expanded into all existing files matching the given pattern. However, @command{tar} often uses wildcard patterns for matching (or globbing) archive members instead -of actual files in the filesystem. Wildcard patterns are also used for +of actual files in the file system. Wildcard patterns are also used for verifying volume labels of @command{tar} archives. This section has the purpose of explaining wildcard syntax for @command{tar}. @@ -6016,61 +6443,68 @@ string: excluding a directory also excludes all the files beneath it. @node after @section Operating Only on New Files +@UNREVISED + @cindex Excluding file by age +@cindex Data Modification time, excluding files by @cindex Modification time, excluding files by @cindex Age, excluding files by -@UNREVISED - -The @value{op-after-date} option causes @command{tar} to only work on files -whose modification or inode-changed times are newer than the @var{date} -given. If @var{date} starts with @samp{/} or @samp{.}, it is taken to -be a file name; the last-modified time of that file is used as the date. -If you use this option when creating or appending to an archive, -the archive will only include new files. If you use @option{--after-date} -when extracting an archive, @command{tar} will only extract files newer -than the @var{date} you specify. +The @option{--after-date=@var{date}} (@option{--newer=@var{date}}, +@option{-N @var{date}}) option causes @command{tar} to only work on +files whose data modification or status change times are newer than +the @var{date} given. If @var{date} starts with @samp{/} or @samp{.}, +it is taken to be a file name; the data modification time of that file +is used as the date. If you use this option when creating or appending +to an archive, the archive will only include new files. If you use +@option{--after-date} when extracting an archive, @command{tar} will +only extract files newer than the @var{date} you specify. If you only want @command{tar} to make the date comparison based on -modification of the actual contents of the file (rather than inode -changes), then use the @value{op-newer-mtime} option. +modification of the file's data (rather than status +changes), then use the @option{--newer-mtime=@var{date}} option. You may use these options with any operation. Note that these options -differ from the @value{op-update} operation in that they allow you to -specify a particular date against which @command{tar} can compare when -deciding whether or not to archive the files. +differ from the @option{--update} (@option{-u}) operation in that they +allow you to specify a particular date against which @command{tar} can +compare when deciding whether or not to archive the files. @table @option +@opindex after-date +@opindex newer @item --after-date=@var{date} @itemx --newer=@var{date} @itemx -N @var{date} Only store files newer than @var{date}. -Acts on files only if their modification or inode-changed times are +Acts on files only if their data modification or status change times are later than @var{date}. Use in conjunction with any operation. If @var{date} starts with @samp{/} or @samp{.}, it is taken to be a file -name; the last-modified time of that file is used as the date. +name; the data modification time of that file is used as the date. +@opindex newer-mtime @item --newer-mtime=@var{date} -Acts like @value{op-after-date}, but only looks at modification times. +Acts like @option{--after-date}, but only looks at data modification times. @end table -These options limit @command{tar} to only operating on files which have -been modified after the date specified. A file is considered to have -changed if the contents have been modified, or if the owner, +These options limit @command{tar} to operate only on files which have +been modified after the date specified. A file's status is considered to have +changed if its contents have been modified, or if its owner, permissions, and so forth, have been changed. (For more information on how to specify a date, see @ref{Date input formats}; remember that the entire date argument must be quoted if it contains any spaces.) -Gurus would say that @value{op-after-date} tests both the @code{mtime} -(time the contents of the file were last modified) and @code{ctime} -(time the file's status was last changed: owner, permissions, etc) -fields, while @value{op-newer-mtime} tests only @code{mtime} field. +Gurus would say that @option{--after-date} tests both the data +modification time (@code{mtime}, the time the contents of the file +were last modified) and the status change time (@code{ctime}, the time +the file's status was last changed: owner, permissions, etc.@:) +fields, while @option{--newer-mtime} tests only the @code{mtime} +field. -To be precise, @value{op-after-date} checks @emph{both} @code{mtime} and +To be precise, @option{--after-date} checks @emph{both} @code{mtime} and @code{ctime} and processes the file if either one is more recent than -@var{date}, while @value{op-newer-mtime} only checks @code{mtime} and -disregards @code{ctime}. Neither uses @code{atime} (the last time the +@var{date}, while @option{--newer-mtime} only checks @code{mtime} and +disregards @code{ctime}. Neither does it use @code{atime} (the last time the contents of the file were looked at). Date specifiers can have embedded spaces. Because of this, you may need @@ -6080,10 +6514,10 @@ arguments. @FIXME{Need example of --newer-mtime with quoted argument.} @quotation -@strong{Please Note:} @value{op-after-date} and @value{op-newer-mtime} +@strong{Please Note:} @option{--after-date} and @option{--newer-mtime} should not be used for incremental backups. Some files (such as those in renamed directories) are not selected properly by these options. -@xref{incremental and listed-incremental}. +@xref{Incremental Dumps}. @end quotation @noindent @@ -6091,22 +6525,23 @@ in renamed directories) are not selected properly by these options. @node recurse @section Descending into Directories +@UNREVISED @cindex Avoiding recursion in directories @cindex Descending directories, avoiding @cindex Directories, avoiding recursion @cindex Recursion in directories, avoiding -@UNREVISED @FIXME{arrggh! this is still somewhat confusing to me. :-< } @FIXME{show dan bob's comments, from 2-10-97} Usually, @command{tar} will recursively explore all directories (either -those given on the command line or through the @value{op-files-from} +those given on the command line or through the @option{--files-from} option) for the various files they contain. However, you may not always want @command{tar} to act this way. -The @value{op-no-recursion} option inhibits @command{tar}'s recursive descent +@opindex no-recursion +The @option{--no-recursion} option inhibits @command{tar}'s recursive descent into specified directories. If you specify @option{--no-recursion}, you can use the @command{find} utility for hunting through levels of directories to construct a list of file names which you could then pass to @command{tar}. @@ -6118,6 +6553,7 @@ archive; see @ref{files} for more information on using @command{find} with @item --no-recursion Prevents @command{tar} from recursively descending directories. +@opindex recursion @item --recursion Requires @command{tar} to recursively descend directories. This is the default. @@ -6130,29 +6566,30 @@ want to back up, and since @command{tar} @emph{usually} recursively descends on directories, they have to use the @samp{@w{! -d}} option to @command{find} @FIXME{needs more explanation or a cite to another info file}as they usually do not want all the files in a directory. -They then use the @value{op-files-from} option to archive the files +They then use the @option{--files-from} option to archive the files located via @command{find}. The problem when restoring files archived in this manner is that the directories themselves are not in the archive; so the -@value{op-same-permissions} option does not affect them---while users -might really like it to. Specifying @value{op-no-recursion} is a way to -tell @command{tar} to grab only the directory entries given to it, adding +@option{--same-permissions} (@option{--preserve-permissions}, +@option{-p}) option does not affect them---while users might really +like it to. Specifying @option{--no-recursion} is a way to tell +@command{tar} to grab only the directory entries given to it, adding no new files on its own. -The @value{op-no-recursion} option also applies when extracting: it +The @option{--no-recursion} option also applies when extracting: it causes @command{tar} to extract only the matched directory entries, not the files under those directories. -The @value{op-no-recursion} option also affects how exclude patterns -are interpreted (@pxref{controlling pattern-patching with exclude}). +The @option{--no-recursion} option also affects how exclude patterns +are interpreted (@pxref{controlling pattern-matching with exclude}). The @option{--no-recursion} and @option{--recursion} options apply to later options and operands, and can be overridden by later occurrences of @option{--no-recursion} and @option{--recursion}. For example: @smallexample -$ @kbd{tar -cf jams.tar --norecursion grape --recursion grape/concord} +$ @kbd{tar -cf jams.tar --no-recursion grape --recursion grape/concord} @end smallexample @noindent @@ -6161,19 +6598,20 @@ contents of @file{grape/concord}, but no entries under @file{grape} other than @file{grape/concord}. @node one -@section Crossing Filesystem Boundaries +@section Crossing File System Boundaries @cindex File system boundaries, not crossing @UNREVISED @command{tar} will normally automatically cross file system boundaries in order to archive files which are part of a directory tree. You can change this behavior by running @command{tar} and specifying -@value{op-one-file-system}. This option only affects files that are +@option{--one-file-system} (@option{-l}). This option only affects files that are archived because they are in a directory that is being archived; @command{tar} will still archive files explicitly named on the command line -or through @value{op-files-from}, regardless of where they reside. +or through @option{--files-from}, regardless of where they reside. @table @option +@opindex one-file-system @item --one-file-system @itemx -l Prevents @command{tar} from crossing file system boundaries when @@ -6182,7 +6620,7 @@ archiving. Use in conjunction with any write operation. The @option{--one-file-system} option causes @command{tar} to modify its normal behavior in archiving the contents of directories. If a file in -a directory is not on the same filesystem as the directory itself, then +a directory is not on the same file system as the directory itself, then @command{tar} will not archive that file. If the file is a directory itself, @command{tar} will not archive anything beneath it; in other words, @command{tar} will not cross mount points. @@ -6192,7 +6630,7 @@ but nothing under it. This option is useful for making full or incremental archival backups of a file system. If this option is used in conjunction with -@value{op-verbose}, files that are excluded are mentioned by name on the +@option{--verbose} (@option{-v}), files that are excluded are mentioned by name on the standard error. @menu @@ -6202,6 +6640,7 @@ standard error. @node directory @subsection Changing the Working Directory +@UNREVISED @FIXME{need to read over this node now for continuity; i've switched things around some.} @@ -6209,15 +6648,14 @@ things around some.} @cindex Changing directory mid-stream @cindex Directory, changing mid-stream @cindex Working directory, specifying -@UNREVISED - To change the working directory in the middle of a list of file names, either on the command line or in a file specified using -@value{op-files-from}, use @value{op-directory}. This will change the -working directory to the directory @var{directory} after that point in -the list. +@option{--files-from} (@option{-T}), use @option{--directory} (@option{-C}). +This will change the working directory to the specified directory +after that point in the list. @table @option +@opindex directory @item --directory=@var{directory} @itemx -C @var{directory} Changes the working directory in the middle of a command line. @@ -6308,16 +6746,17 @@ $ @kbd{tar -c -f foo.tar --files-from list} Notice also that you can only use the short option variant in the file list, i.e., always use @option{-C}, not @option{--directory}. -The interpretation of @value{op-directory} is disabled by -@value{op-null} option. +The interpretation of @option{--directory} is disabled by +@option{--null} option. @node absolute @subsection Absolute File Names @UNREVISED @table @option -@item -P -@itemx --absolute-names +@opindex absolute-names +@item --absolute-names +@itemx -P Do not strip leading slashes from file names, and permit file names containing a @file{..} file name component. @end table @@ -6353,21 +6792,22 @@ is not, generally speaking, the same as the one you'd get running scripts for comparing both outputs. @xref{listing member and file names}, for the information on how to handle this case.} -If you use the @value{op-absolute-names} option, @command{tar} will do -none of these transformations. +If you use the @option{--absolute-names} (@option{-P}) option, +@command{tar} will do none of these transformations. To archive or extract files relative to the root directory, specify -the @value{op-absolute-names} option. +the @option{--absolute-names} (@option{-P}) option. Normally, @command{tar} acts on files relative to the working directory---ignoring superior directory names when archiving, and ignoring leading slashes when extracting. -When you specify @value{op-absolute-names}, @command{tar} stores file names -including all superior directory names, and preserves leading slashes. -If you only invoked @command{tar} from the root directory you would never -need the @value{op-absolute-names} option, but using this option may be -more convenient than switching to root. +When you specify @option{--absolute-names} (@option{-P}), +@command{tar} stores file names including all superior directory +names, and preserves leading slashes. If you only invoked +@command{tar} from the root directory you would never need the +@option{--absolute-names} option, but using this option +may be more convenient than switching to root. @FIXME{Should be an example in the tutorial/wizardry section using this to transfer files between systems.} @@ -6411,6 +6851,7 @@ $ @kbd{tar -c -f archive.tar -C / home} @node Formats @chapter Controlling the Archive Format +@cindex Tar archive formats Due to historical reasons, there are several formats of tar archives. All of them are based on the same principles, but have some subtle differences that often make them incompatible with each other. @@ -6537,6 +6978,9 @@ archives to contain only regular files and directories, avoiding other kind of special files. Do not attempt to save sparse files or contiguous files as such. Let's discuss a few more problems, in turn. +@FIXME{Discuss GNU extensions (incremental backups, multi-volume +archives and archive labels) in GNU and PAX formats.} + @menu * Portable Names:: Portable Names * dereference:: Symbolic Links @@ -6569,10 +7013,11 @@ than System V's. @cindex File names, using symbolic links @cindex Symbolic link as file name +@opindex dereference Normally, when @command{tar} archives a symbolic link, it writes a block to the archive naming the target of the link. In that way, the -@command{tar} archive is a faithful record of the filesystem contents. -@value{op-dereference} is used with @value{op-create}, and causes +@command{tar} archive is a faithful record of the file system contents. +@option{--dereference} (@option{-h}) is used with @option{--create} (@option{-c}), and causes @command{tar} to archive the files symbolic links point to, instead of the links themselves. When this option is used, when @command{tar} encounters a symbolic link, it will archive the linked-to file, @@ -6590,7 +7035,7 @@ the same archive, an entire second copy of it will be stored. (This @emph{might} be considered a bug.) So, for portable archives, do not archive symbolic links as such, -and use @value{op-dereference}: many systems do not support +and use @option{--dereference} (@option{-h}): many systems do not support symbolic links, and moreover, your distribution might be unusable if it contains unresolved symbolic links. @@ -6599,30 +7044,32 @@ it contains unresolved symbolic links. @cindex Format, old style @cindex Old style format @cindex Old style archives +@cindex v7 archive format Certain old versions of @command{tar} cannot handle additional information recorded by newer @command{tar} programs. To create an archive in V7 format (not ANSI), which can be read by these old -versions, specify the @value{op-format-v7} option in -conjunction with the @value{op-create} (@command{tar} also +versions, specify the @option{--format=v7} option in +conjunction with the @option{--create} (@option{-c}) (@command{tar} also accepts @option{--portability} or @samp{op-old-archive} for this option). When you specify it, @command{tar} leaves out information about directories, pipes, fifos, contiguous files, and device files, and specifies file ownership by group and user IDs instead of group and user names. -When updating an archive, do not use @value{op-format-v7} +When updating an archive, do not use @option{--format=v7} unless the archive was created using this option. In most cases, a @emph{new} format archive can be read by an @emph{old} @command{tar} program without serious trouble, so this option should seldom be needed. On the other hand, most modern @command{tar}s are able to read old format archives, so it might be safer for you to -always use @value{op-format-v7} for your distributions. +always use @option{--format=v7} for your distributions. @node ustar @subsection Ustar Archive Format +@cindex ustar archive format Archive format defined by @acronym{POSIX}.1-1988 specification is called @code{ustar}. Although it is more flexible than the V7 format, it still has many restrictions (@xref{Formats,ustar}, for the detailed @@ -6630,12 +7077,14 @@ description of @code{ustar} format). Along with V7 format, @code{ustar} format is a good choice for archives intended to be read with other implementations of @command{tar}. -To create archive in @code{ustar} format, use @value{op-format-ustar} -option in conjunction with the @value{op-create}. +To create archive in @code{ustar} format, use @option{--format=ustar} +option in conjunction with the @option{--create} (@option{-c}). @node gnu @subsection @acronym{GNU} and old @GNUTAR{} format +@cindex GNU archive format +@cindex Old GNU archive format @GNUTAR{} was based on an early draft of the @acronym{POSIX} 1003.1 @code{ustar} standard. @acronym{GNU} extensions to @command{tar}, such as the support for file names longer than 100 @@ -6651,40 +7100,18 @@ this format by default. This will change in the future releases, since we plan to make @samp{posix} format the default. To force creation a @GNUTAR{} archive, use option -@value{op-format-gnu}. - -Some @command{tar} options are currently basing on @GNUTAR{} -format, and can therefore be used only with @samp{gnu} -or @samp{oldgnu} archive formats. The list of such options follows: - -@itemize @bullet -@item @value{op-label}, when used with @value{op-create}. -@item @value{op-incremental} -@item @value{op-multi-volume} -@end itemize - -These options will be re-implemented for the @samp{posix} archive -format in the future. +@option{--format=gnu}. @node posix @subsection @GNUTAR{} and @acronym{POSIX} @command{tar} +@cindex POSIX archive format +@cindex PAX archive format The version @value{VERSION} of @GNUTAR{} is able to read and create archives conforming to @acronym{POSIX.1-2001} standard. A @acronym{POSIX} conformant archive will be created if @command{tar} -was given @value{op-format-posix} option. -Notice, that currently @acronym{GNU} extensions are not -allowed with this format. Following is the list of options that -cannot be used with @value{op-format-posix}: - -@itemize @bullet -@item @value{op-label}, when used with @value{op-create}. -@item @value{op-incremental} -@item @value{op-multi-volume} -@end itemize - -This restriction will disappear in the future versions. +was given @option{--format=posix} option. @node Checksumming @subsection Checksumming Problems @@ -6727,40 +7154,36 @@ a @command{tar} able to read the good archives they receive. @cindex large values @cindex future time stamps @cindex negative time stamps - -@acronym{POSIX} @command{tar} format uses fixed-sized unsigned octal strings -to represent numeric values. User and group IDs and device major and -minor numbers have unsigned 21-bit representations, and file sizes and -times have unsigned 33-bit representations. @GNUTAR{} -generates @acronym{POSIX} representations when possible, but for values -outside the @acronym{POSIX} range it generates two's-complement base-256 -strings: uids, gids, and device numbers have signed 57-bit -representations, and file sizes and times have signed 89-bit -representations. These representations are an extension to @acronym{POSIX} -@command{tar} format, so they are not universally portable. - -The most common portability problems with out-of-range numeric values -are large files and future or negative time stamps. - -Portable archives should avoid members of 8 GB or larger, as @acronym{POSIX} -@command{tar} format cannot represent them. - -Portable archives should avoid time stamps from the future. @acronym{POSIX} -@command{tar} format can represent time stamps in the range 1970-01-01 -00:00:00 through 2242-03-16 12:56:31 @sc{utc}. However, many current -hosts use a signed 32-bit @code{time_t}, or internal time stamp format, -and cannot represent time stamps after 2038-01-19 03:14:07 @sc{utc}; so -portable archives must avoid these time stamps for many years to come. - -Portable archives should also avoid time stamps before 1970. These time -stamps are a common @acronym{POSIX} extension but their @code{time_t} -representations are negative. Many traditional @command{tar} -implementations generate a two's complement representation for negative -time stamps that assumes a signed 32-bit @code{time_t}; hence they -generate archives that are not portable to hosts with differing -@code{time_t} representations. @GNUTAR{} recognizes this -situation when it is run on host with a signed 32-bit @code{time_t}, but -it issues a warning, as these time stamps are nonstandard and unportable. +@UNREVISED{} + +The above sections suggest to use @samp{oldest possible} archive +format if in doubt. However, sometimes it is not possible. If you +attempt to archive a file whose metadata cannot be represented using +required format, @GNUTAR{} will print error message and ignore such a +file. You will than have to switch to a format that is able to +handle such values. The format summary table (@pxref{Formats}) will +help you to do so. + +In particular, when trying to archive files larger than 8GB or with +timestamps not in the range 1970-01-01 00:00:00 through 2242-03-16 +12:56:31 @sc{utc}, you will have to chose between @acronym{GNU} and +@acronym{POSIX} archive formats. When considering which format to +choose, bear in mind that the @acronym{GNU} format uses +two's-complement base-256 notation to store values that do not fit +into standard @acronym{ustar} range. Such archives can generally be +read only by a @GNUTAR{} implementation. Moreover, they sometimes +cannot be correctly restored on another hosts even by @GNUTAR{}. For +example, using two's complement representation for negative time +stamps that assumes a signed 32-bit @code{time_t} generates archives +that are not portable to hosts with differing @code{time_t} +representations. + +On the other hand, @acronym{POSIX} archives, generally speaking, can +be extracted by any tar implementation that understands older +@acronym{ustar} format. The only exception are files larger than 8GB. + +@FIXME{Describe how @acronym{POSIX} archives are extracted by non +POSIX-aware tars.} @node Compression @section Using Less Space through Compression @@ -6827,15 +7250,17 @@ $ @kbd{cat archive.tar.gz | tar tfz -} Notice also, that there are several restrictions on operations on compressed archives. First of all, compressed archives cannot be -modified, i.e., you cannot update (@value{op-update}) them or delete -(@value{op-delete}) members from them. Likewise, you cannot append +modified, i.e., you cannot update (@option{--update} (@option{-u})) them or delete +(@option{--delete}) members from them. Likewise, you cannot append another @command{tar} archive to a compressed archive using -@value{op-append}). Secondly, multi-volume archives cannot be +@option{--append} (@option{-r})). Secondly, multi-volume archives cannot be compressed. The following table summarizes compression options used by @GNUTAR{}. @table @option +@opindex gzip +@opindex ungzip @item -z @itemx --gzip @itemx --ungzip @@ -6853,7 +7278,7 @@ $ @kbd{GZIP=--best tar cfz archive.tar.gz subdir} @end smallexample @noindent -Another way would be to avoid the @value{op-gzip} option and run +Another way would be to avoid the @option{--gzip} (@option{--gunzip}, @option{--ungzip}, @option{-z}) option and run @command{gzip} explicitly: @smallexample @@ -6875,21 +7300,24 @@ every volume or file, in case of corrupted archives. Doing so, we might lose some compressibility. But this would have make recovering easier. So, there are pros and cons. We'll see! +@opindex bzip2 @item -j @itemx --bzip2 -Filter the archive through @code{bzip2}. Otherwise like @value{op-gzip}. +Filter the archive through @code{bzip2}. Otherwise like @option{--gzip}. +@opindex compress +@opindex uncompress @item -Z @itemx --compress @itemx --uncompress -Filter the archive through @command{compress}. Otherwise like -@value{op-gzip}. +Filter the archive through @command{compress}. Otherwise like @option{--gzip}. The @acronym{GNU} Project recommends you not use @command{compress}, because there is a patent covering the algorithm it uses. You could be sued for patent infringement merely by running @command{compress}. +@opindex use-compress-program @item --use-compress-program=@var{prog} Use external compression program @var{prog}. Use this option if you have a compression program that @GNUTAR{} does not support. There @@ -6904,7 +7332,7 @@ and produce uncompressed data on the standard output. @end table @FIXME{I have one question, or maybe it's a suggestion if there isn't a way -to do it now. I would like to use @value{op-gzip}, but I'd also like +to do it now. I would like to use @option{--gzip}, but I'd also like the output to be fed through a program like @acronym{GNU} @command{ecc} (actually, right now that's @samp{exactly} what I'd like to use :-)), basically adding ECC protection on top of compression. @@ -6926,14 +7354,14 @@ that capability. Supposing I were to actually do such a thing and get it (apparently) working, do you accept contributed changes to utilities like that? (Leigh Clayton @file{loc@@soliton.com}, May 1995). -Isn't that exactly the role of the @value{op-use-compress-prog} option? +Isn't that exactly the role of the @option{--use-compress-prog=@var{program}} option? I never tried it myself, but I suspect you may want to write a @var{prog} script or program able to filter stdin to stdout to way you want. It should recognize the @option{-d} option, for when extraction is needed rather than creation. It has been reported that if one writes compressed data (through the -@value{op-gzip} or @value{op-compress} options) to a DLT and tries to use +@option{--gzip} or @option{--compress} options) to a DLT and tries to use the DLT compression mode, the data will actually get bigger and one will end up with less space on the tape.} @@ -6943,14 +7371,15 @@ end up with less space on the tape.} @UNREVISED @table @option +@opindex sparse @item -S @itemx --sparse Handle sparse files efficiently. @end table This option causes all files to be put in the archive to be tested for -sparseness, and handled specially if they are. The @value{op-sparse} -option is useful when many @code{dbm} files, for example, are being +sparseness, and handled specially if they are. The @option{--sparse} +(@option{-S}) option is useful when many @code{dbm} files, for example, are being backed up. Using this option dramatically decreases the amount of space needed to store such a file. @@ -6959,49 +7388,49 @@ treatment of sparse files may be done automatically with any special @acronym{GNU} options. For now, it is an option needing to be specified on the command line with the creation or updating of an archive. -Files in the filesystem occasionally have ``holes.'' A hole in a file +Files in the file system 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 disk storage is not allocated for holes, but they are counted in the length of the file. If you archive such a file, @command{tar} could create an archive longer than the original. To have @command{tar} -attempt to recognize the holes in a file, use @value{op-sparse}. When -you use the @value{op-sparse} option, then, for any file using less -disk space than would be expected from its length, @command{tar} searches -the file for consecutive stretches of zeros. It then records in the -archive for the file where the consecutive stretches of zeros are, and -only archives the ``real contents'' of the file. On extraction (using -@value{op-sparse} is not needed on extraction) any such files have -holes created wherever the continuous stretches of zeros were found. -Thus, if you use @value{op-sparse}, @command{tar} archives won't take -more space than the original. +attempt to recognize the holes in a file, use @option{--sparse} (@option{-S}). When +you use this option, then, for any file using less disk space than +would be expected from its length, @command{tar} searches the file for +consecutive stretches of zeros. It then records in the archive for +the file where the consecutive stretches of zeros are, and only +archives the ``real contents'' of the file. On extraction (using +@option{--sparse} is not needed on extraction) any such +files have holes created wherever the continuous stretches of zeros +were found. Thus, if you use @option{--sparse}, @command{tar} archives +won't take more space than the original. A file is sparse if it contains blocks of zeros whose existence is recorded, but that have no space allocated on disk. When you specify -the @value{op-sparse} option in conjunction with the @value{op-create} -operation, @command{tar} tests all files for sparseness while archiving. -If @command{tar} finds a file to be sparse, it uses a sparse representation of -the file in the archive. @value{xref-create}, for more information -about creating archives. +the @option{--sparse} option in conjunction with the @option{--create} +(@option{-c}) operation, @command{tar} tests all files for sparseness +while archiving. If @command{tar} finds a file to be sparse, it uses a +sparse representation of the file in the archive. @xref{create}, for +more information about creating archives. -@value{op-sparse} is useful when archiving files, such as dbm files, +@option{--sparse} is useful when archiving files, such as dbm files, likely to contain many nulls. This option dramatically decreases the amount of space needed to store such an archive. @quotation -@strong{Please Note:} Always use @value{op-sparse} when performing file +@strong{Please Note:} Always use @option{--sparse} when performing file system backups, to avoid archiving the expanded forms of files stored sparsely in the system. Even if your system has no sparse files currently, some may be -created in the future. If you use @value{op-sparse} while making file +created in the future. If you use @option{--sparse} while making file system backups as a matter of course, you can be assured the archive will never take more space on the media than the files take on disk (otherwise, archiving a disk filled with sparse files might take hundreds of tapes). @FIXME-xref{incremental when node name is set.} @end quotation -@command{tar} ignores the @value{op-sparse} option when reading an archive. +@command{tar} ignores the @option{--sparse} option when reading an archive. @table @option @item --sparse @@ -7022,9 +7451,9 @@ dumping a @file{core} file of over 400 megabytes, but with only about ELC, with full CPU utilization.) This reading is required in all cases and is not related to the fact -the @value{op-sparse} option is used or not, so by merely @emph{not} +the @option{--sparse} option is used or not, so by merely @emph{not} using the option, you are not saving time@footnote{Well! We should say -the whole truth, here. When @value{op-sparse} is selected while creating +the whole truth, here. When @option{--sparse} is selected while creating an archive, the current @command{tar} algorithm requires sparse files to be read twice, not once. We hope to develop a new archive format for saving sparse files in which one pass will be sufficient.}. @@ -7056,32 +7485,50 @@ get it right. @section Handling File Attributes @UNREVISED -When @command{tar} reads files, this causes them to have the access -times updated. To have @command{tar} attempt to set the access times -back to what they were before they were read, use the -@value{op-atime-preserve} option. +When @command{tar} reads files, it updates their access times. To +avoid this, use the @option{--atime-preserve[=METHOD]} option, which can either +reset the access time retroactively or avoid changing it in the first +place. Handling of file attributes @table @option +@opindex atime-preserve @item --atime-preserve -Preserve access times on files that are read. -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{Backups}), and it can set access or -modification times incorrectly if other programs access the file while -@command{tar} is running; but it is good enough for some purposes. - +@itemx --atime-preserve=replace +@itemx --atime-preserve=system +Preserve the access times of files that are read. This works only for +files that you own, unless you have superuser privileges. + +@option{--atime-preserve=replace} works on most systems, but it also +restores the data modification time and updates the status change +time. Hence it doesn't interact with incremental dumps nicely +(@pxref{Backups}), and it can set access or data modification times +incorrectly if other programs access the file while @command{tar} is +running. + +@option{--atime-preserve=system} avoids changing the access time in +the first place, if the operating system supports this. +Unfortunately, this may or may not work on any given operating system +or file system. If @command{tar} knows for sure it won't work, it +complains right away. + +Currently @option{--atime-preserve} with no operand defaults to +@option{--atime-preserve=replace}, but this is intended to change to +@option{--atime-preserve=system} when the latter is better-supported. + +@opindex touch @item -m @itemx --touch -Do not extract file modified time. +Do not extract data modification time. -When this option is used, @command{tar} leaves the modification times -of the files it extracts as the time when the files were extracted, -instead of setting it to the time recorded in the archive. +When this option is used, @command{tar} leaves the data modification times +of the files it extracts as the times when the files were extracted, +instead of setting it to the times recorded in the archive. -This option is meaningless with @value{op-list}. +This option is meaningless with @option{--list} (@option{-t}). +@opindex same-owner @item --same-owner Create extracted files with the same ownership they have in the archive. @@ -7097,19 +7544,21 @@ files are easily and silently lost when files are given away. When writing an archive, @command{tar} writes the user id and user name separately. If it can't find a user name (because the user id is not in @file{/etc/passwd}), then it does not write one. When restoring, -and doing a @code{chmod} like when you use @value{op-same-permissions}, +and doing a @code{chmod} like when you use @option{--same-permissions}, @FIXME{same-owner?}it tries to look the name (if one was written) up in @file{/etc/passwd}. If it fails, then it uses the user id stored in the archive instead. +@opindex no-same-owner @item --no-same-owner @itemx -o Do not attempt to restore ownership when extracting. This is the default behavior for ordinary users, so this option has an effect only for the superuser. +@opindex numeric-owner @item --numeric-owner -The @value{op-numeric-owner} option allows (ANSI) archives to be written +The @option{--numeric-owner} option allows (ANSI) archives to be written without user/group name information or such information to be ignored when extracting. It effectively disables the generation and/or use of user/group name information. This option forces extraction using @@ -7119,14 +7568,14 @@ This is useful in certain circumstances, when restoring a backup from an emergency floppy with different passwd/group files for example. It is otherwise impossible to extract files with the right ownerships if the password file in use during the extraction does not match the -one belonging to the filesystem(s) being extracted. This occurs, +one belonging to the file system(s) being extracted. This occurs, for example, if you are restoring your files after a major crash and had booted from an emergency floppy with no password file or put your disk into another machine to do the restore. The numeric ids are @emph{always} saved into @command{tar} archives. The identifying names are added at create time when provided by the -system, unless @value{op-old-archive} is used. Numeric ids could be +system, unless @option{--old-archive} (@option{-o}) is used. Numeric ids could be used when moving archives between a collection of machines using a centralized management for attribution of numeric ids to users and groups. This is often made through using the NIS capabilities. @@ -7146,6 +7595,8 @@ This is not the good way, I think. @GNUTAR{} is already crowded with options and moreover, the approach just explained gives you a great deal of control already. +@opindex same-permissions, short description +@opindex preserve-permissions, short description @item -p @itemx --same-permissions @itemx --preserve-permissions @@ -7158,13 +7609,14 @@ on extracted files. This option is by default enabled when @command{tar} is executed by a superuser. -This option is meaningless with @value{op-list}. +This option is meaningless with @option{--list} (@option{-t}). +@opindex preserve @item --preserve -Same as both @value{op-same-permissions} and @value{op-same-order}. +Same as both @option{--same-permissions} and @option{--same-order}. -The @value{op-preserve} option has no equivalent short option name. -It is equivalent to @value{op-same-permissions} plus @value{op-same-order}. +The @option{--preserve} option has no equivalent short option name. +It is equivalent to @option{--same-permissions} plus @option{--same-order}. @FIXME{I do not see the purpose of such an option. (Neither I. FP.)} @@ -7200,7 +7652,7 @@ same name, see -backup node, when it's written.} In addition to entries describing archive members, an archive may contain entries which @command{tar} itself uses to store information. -@value{xref-label}, for an example of such an archive entry. +@xref{label}, for an example of such an archive entry. A @command{tar} archive file contains a series of blocks. Each block contains @code{BLOCKSIZE} bytes. Although this format may be thought @@ -7216,7 +7668,7 @@ particular @GNUTAR{} always issues a warning if it does not encounter it. The blocks may be @dfn{blocked} for physical I/O operations. Each record of @var{n} blocks (where @var{n} is set by the -@value{op-blocking-factor} option to @command{tar}) is written with a single +@option{--blocking-factor=@var{512-size}} (@option{-b @var{512-size}}) option to @command{tar}) is written with a single @w{@samp{write ()}} operation. On magnetic tapes, the result of such a write is a single record. When writing an archive, the last record of blocks should be written at the full size, with @@ -7271,11 +7723,12 @@ not support numeric user or group IDs, these fields should be ignored. The @code{size} field is the size of the file in bytes; linked files are archived with this field specified as zero. @FIXME-xref{Modifiers, in -particular the @value{op-incremental} option.} +particular the @option{--incremental} (@option{-G}) option.} -The @code{mtime} field is the modification time of the file at the time -it was archived. It is the ASCII representation of the octal value of -the last time the file was modified, represented as an integer number of +The @code{mtime} field is the data modification time of the file at +the time it was archived. It is the ASCII representation of the octal +value of the last time the file's contents were modified, represented +as an integer number of seconds since January 1, 1970, 00:00 Coordinated Universal Time. The @code{chksum} field is the ASCII representation of the octal value @@ -7291,10 +7744,10 @@ type, the file will be extracted as if it were a regular file. As this action occurs, @command{tar} issues a warning to the standard error. The @code{atime} and @code{ctime} fields are used in making incremental -backups; they store, respectively, the particular file's access time -and last inode-change time. +backups; they store, respectively, the particular file's access and +status change times. -The @code{offset} is used by the @value{op-multi-volume} option, when +The @code{offset} is used by the @option{--multi-volume} (@option{-M}) option, when making a multi-volume archive. The offset is number of bytes into the file that we need to restart at to continue the file on the next tape, i.e., where we store the location that a continued file is @@ -7435,7 +7888,7 @@ files in an archive. These are listed below. @item GNUTYPE_DUMPDIR @itemx 'D' This represents a directory and a list of files created by the -@value{op-incremental} option. The @code{size} field gives the total +@option{--incremental} (@option{-G}) option. The @code{size} field gives the total size of the associated list of files. Each file name is preceded by either a @samp{Y} (the file should be in this archive) or an @samp{N}. (The file is a directory, or is not stored in the archive.) Each file @@ -7445,7 +7898,7 @@ last file name. @item GNUTYPE_MULTIVOL @itemx 'M' This represents a file continued from another volume of a multi-volume -archive created with the @value{op-multi-volume} option. The original +archive created with the @option{--multi-volume} (@option{-M}) option. The original type of the file is not given here. The @code{size} field gives the maximum size of this piece of the file (assuming the volume does not end before the file is written out). The @code{offset} field @@ -7463,16 +7916,16 @@ with the number of bytes of data to be found after the hole. @item GNUTYPE_VOLHDR @itemx 'V' This file type is used to mark the volume header that was given with -the @value{op-label} option when the archive was created. The @code{name} -field contains the @code{name} given after the @value{op-label} option. +the @option{--label=@var{archive-label}} (@option{-V @var{archive-label}}) option when the archive was created. The @code{name} +field contains the @code{name} given after the @option{--label=@var{archive-label}} (@option{-V @var{archive-label}}) option. The @code{size} field is zero. Only the first file in each volume of an archive should have this type. @end table You may have trouble reading a @acronym{GNU} format archive on a -non-@acronym{GNU} system if the options @value{op-incremental}, -@value{op-multi-volume}, @value{op-sparse}, or @value{op-label} were +non-@acronym{GNU} system if the options @option{--incremental} (@option{-G}), +@option{--multi-volume} (@option{-M}), @option{--sparse} (@option{-S}), or @option{--label=@var{archive-label}} (@option{-V @var{archive-label}}) were used when writing the archive. In general, if @command{tar} does not use the @acronym{GNU}-added fields of the header, other versions of @command{tar} should be able to read the archive. Otherwise, the @@ -7668,7 +8121,7 @@ with the sources for @command{tar}; it's compiled and installed by default. The exact path to this utility is determined when configuring the package. It is @file{@var{prefix}/libexec/rmt}, where @var{prefix} stands for your installation prefix. This location may also be overridden at -runtime by using @value{op-rmt-command} option (@xref{Option Summary, +runtime by using @option{rmt-command=@var{command}} option (@xref{Option Summary, ---rmt-command}, for detailed description of this option. @xref{Remote Tape Server}, for the description of @command{rmt} command). @@ -7708,9 +8161,11 @@ too. The installer could also check for @samp{DEFTAPE} in @file{}. @table @option +@opindex force-local, short description @item --force-local Archive file is local even if it contains a colon. +@opindex rsh-command @item --rsh-command=@var{command} Use remote @var{command} instead of @command{rsh}. This option exists so that people who use something other than the standard @command{rsh} @@ -7726,6 +8181,7 @@ variable @env{RSH} @emph{at installation time}. @item -[0-7][lmh] Specify drive and density. +@opindex multi-volume, short description @item -M @itemx --multi-volume Create/list/extract multi-volume archive. @@ -7734,6 +8190,7 @@ This option causes @command{tar} to write a @dfn{multi-volume} archive---one that may be larger than will fit on the medium used to hold it. @xref{Multi-Volume Archives}. +@opindex tape-length, short description @item -L @var{num} @itemx --tape-length=@var{num} Change tape after writing @var{num} x 1024 bytes. @@ -7742,11 +8199,14 @@ This option might be useful when your tape drivers do not properly detect end of physical tapes. By being slightly conservative on the maximum tape length, you might avoid the problem entirely. +@opindex info-script, short description +@opindex new-volume-script, short description @item -F @var{file} @itemx --info-script=@var{file} @itemx --new-volume-script=@var{file} -Execute @file{file} at end of each tape. If @file{file} exits with -nonzero status, exit. This implies @value{op-multi-volume}. +Execute @file{file} at end of each tape. This implies +@option{--multi-volume} (@option{-M}). @xref{info-script}, for a detailed +description of this option. @end table @node Remote Tape Server @@ -7768,8 +8228,8 @@ California, but can be freely distributed. It is compiled and installed by default. @cindex absolute file names -Unless you use the @value{op-absolute-names} option, @GNUTAR{} -will not allow you to create an archive that contains +Unless you use the @option{--absolute-names} (@option{-P}) option, +@GNUTAR{} will not allow you to create an archive that contains absolute file names (a file name beginning with @samp{/}.) If you try, @command{tar} will automatically remove the leading @samp{/} from the file names it stores in the archive. It will also type a warning @@ -7791,7 +8251,7 @@ For example, if the archive contained a file @file{/usr/bin/computoy}, relative to the current directory. If you want to extract the files in an archive to the same absolute names that they had when the archive was created, you should do a @samp{cd /} before extracting the files -from the archive, or you should either use the @value{op-absolute-names} +from the archive, or you should either use the @option{--absolute-names} option, or use the command @samp{tar -C / @dots{}}. @cindex Ultrix 3.1 and write failure @@ -7808,23 +8268,23 @@ disk files (or any other file that can be backspaced with @samp{lseek}), and industry-standard 9-track magnetic tape (or any other kind of tape that can be backspaced with the @code{MTIOCTOP} @code{ioctl}. -This means that the @value{op-append}, @value{op-update}, -@value{op-concatenate}, and @value{op-delete} commands will not work on any -other kind of file. Some media simply cannot be backspaced, which -means these commands and options will never be able to work on them. -These non-backspacing media include pipes and cartridge tape drives. +This means that the @option{--append}, @option{--concatenate}, and +@option{--delete} commands will not work on any other kind of file. +Some media simply cannot be backspaced, which means these commands and +options will never be able to work on them. These non-backspacing +media include pipes and cartridge tape drives. Some other media can be backspaced, and @command{tar} will work on them once @command{tar} is modified to do so. -Archives created with the @value{op-multi-volume}, @value{op-label}, and -@value{op-incremental} options may not be readable by other version +Archives created with the @option{--multi-volume}, @option{--label}, and +@option{--incremental} (@option{-G}) options may not be readable by other version of @command{tar}. In particular, restoring a file that was split over a volume boundary will require some careful work with @command{dd}, if it can be done at all. Other versions of @command{tar} may also create an empty file whose name is that of the volume header. Some versions of @command{tar} may create normal files instead of directories archived -with the @value{op-incremental} option. +with the @option{--incremental} (@option{-G}) option. @node Common Problems and Solutions @section Some Common Problems and their Solutions @@ -7912,12 +8372,13 @@ to what we call a @dfn{record} in @GNUTAR{}. When writing to tapes, @command{tar} writes the contents of the archive in chunks known as @dfn{records}. To change the default blocking -factor, use the @value{op-blocking-factor} option. Each record will -then be composed of @var{512-size} blocks. (Each @command{tar} block is -512 bytes. @xref{Standard}.) Each file written to the archive uses -at least one full record. As a result, using a larger record size -can result in more wasted space for small files. On the other hand, a -larger record size can often be read and written much more efficiently. +factor, use the @option{--blocking-factor=@var{512-size}} (@option{-b +@var{512-size}}) option. Each record will then be composed of +@var{512-size} blocks. (Each @command{tar} block is 512 bytes. +@xref{Standard}.) Each file written to the archive uses at least one +full record. As a result, using a larger record size can result in +more wasted space for small files. On the other hand, a larger record +size can often be read and written much more efficiently. Further complicating the problem is that some tape drives ignore the blocking entirely. For these, a larger record size can still improve @@ -7931,16 +8392,16 @@ record size was used when the archive was created, @command{tar} will print a message about a non-standard blocking factor, and then operate normally. On some tape devices, however, @command{tar} cannot figure out the record size itself. On most of those, you can specify a -blocking factor (with @value{op-blocking-factor}) larger than the -actual blocking factor, and then use the @value{op-read-full-records} -option. (If you specify a blocking factor with -@value{op-blocking-factor} and don't use the -@value{op-read-full-records} option, then @command{tar} will not +blocking factor (with @option{--blocking-factor}) larger than the +actual blocking factor, and then use the @option{--read-full-records} +(@option{-B}) option. (If you specify a blocking factor with +@option{--blocking-factor} and don't use the +@option{--read-full-records} option, then @command{tar} will not attempt to figure out the recording size itself.) On some devices, you must always specify the record size exactly with -@value{op-blocking-factor} when reading, because @command{tar} cannot -figure it out. In any case, use @value{op-list} before doing any -extractions to see whether @command{tar} is reading the archive +@option{--blocking-factor} when reading, because @command{tar} cannot +figure it out. In any case, use @option{--list} (@option{-t}) before +doing any extractions to see whether @command{tar} is reading the archive correctly. @command{tar} blocks are all fixed size (512 bytes), and its scheme for @@ -7951,7 +8412,7 @@ is how you tell that the remainder of the last record(s) are garbage. In a standard @command{tar} file (no options), the block size is 512 and the record size is 10240, for a blocking factor of 20. What the -@value{op-blocking-factor} option does is sets the blocking factor, +@option{--blocking-factor} option does is sets the blocking factor, changing the record size while leaving the block size at 512 bytes. 20 was fine for ancient 800 or 1600 bpi reel-to-reel tape drives; most tape drives these days prefer much bigger records in order to @@ -7988,8 +8449,8 @@ To specify format parameters when accessing or creating an archive, you can use the options described in the following sections. If you do not specify any format parameters, @command{tar} uses default parameters. You cannot modify a compressed archive. -If you create an archive with the @value{op-blocking-factor} option -specified (@value{pxref-blocking-factor}), you must specify that +If you create an archive with the @option{--blocking-factor} option +specified (@pxref{Blocking Factor}), you must specify that blocking-factor when operating on the archive. @xref{Formats}, for other examples of format parameter considerations. @@ -8003,15 +8464,17 @@ examples of format parameter considerations. @cindex Blocks per record @UNREVISED +@opindex blocking-factor The data in an archive is grouped into blocks, which are 512 bytes. Blocks are read and written in whole number multiples called @dfn{records}. The number of blocks in a record (ie. the size of a record in units of 512 bytes) is called the @dfn{blocking factor}. -The @value{op-blocking-factor} option specifies the blocking factor of -an archive. The default blocking factor is typically 20 (i.e., -10240 bytes), but can be specified at installation. To find out -the blocking factor of an existing archive, use @samp{tar --list ---file=@var{archive-name}}. This may not work on some devices. +The @option{--blocking-factor=@var{512-size}} (@option{-b +@var{512-size}}) option specifies the blocking factor of an archive. +The default blocking factor is typically 20 (i.e., 10240 bytes), but +can be specified at installation. To find out the blocking factor of +an existing archive, use @samp{tar --list --file=@var{archive-name}}. +This may not work on some devices. Records are separated by gaps, which waste space on the archive media. If you are archiving on magnetic tape, using a larger blocking factor @@ -8056,21 +8519,21 @@ If you use a non-default blocking factor when you create an archive, you must specify the same blocking factor when you modify that archive. Some archive devices will also require you to specify the blocking factor when reading that archive, however this is not typically the case. Usually, you -can use @value{op-list} without specifying a blocking factor---@command{tar} +can use @option{--list} (@option{-t}) without specifying a blocking factor---@command{tar} reports a non-default record size and then lists the archive members as it would normally. To extract files from an archive with a non-standard blocking factor (particularly if you're not sure what the blocking factor -is), you can usually use the @value{op-read-full-records} option while +is), you can usually use the @option{--read-full-records} (@option{-B}) option while specifying a blocking factor larger then the blocking factor of the archive (ie. @samp{tar --extract --read-full-records --blocking-factor=300}. -@xref{list}, for more information on the @value{op-list} +@xref{list}, for more information on the @option{--list} (@option{-t}) operation. @xref{Reading}, for a more detailed explanation of that option. @table @option @item --blocking-factor=@var{number} @itemx -b @var{number} Specifies the blocking factor of an archive. Can be used with any -operation, but is usually not necessary with @value{op-list}. +operation, but is usually not necessary with @option{--list} (@option{-t}). @end table Device blocking @@ -8125,7 +8588,7 @@ redirected nor piped, the archive is directly handled to a local disk, instead of any special device, @item -@value{op-blocking-factor} is not explicitly specified on the @command{tar} +@option{--blocking-factor} is not explicitly specified on the @command{tar} invocation. @end itemize @@ -8166,11 +8629,12 @@ the first null block encountered. This inelegantly breaks the pipe. @command{tar} should rather drain the pipe out before exiting itself. @end itemize +@opindex ignore-zeros, short description @item -i @itemx --ignore-zeros Ignore blocks of zeros in archive (means EOF). -The @value{op-ignore-zeros} option causes @command{tar} to ignore blocks +The @option{--ignore-zeros} (@option{-i}) option causes @command{tar} to ignore blocks of zeros in the archive. Normally a block of zeros indicates the end of the archive, but when reading a damaged archive, or one which was created by concatenating several archives together, this option @@ -8182,13 +8646,15 @@ Note that this option causes @command{tar} to read to the end of the archive file, which may sometimes avoid problems when multiple files are stored on a single physical tape. +@opindex read-full-records, short description @item -B @itemx --read-full-records Reblock as we read (for reading 4.2BSD pipes). -If @value{op-read-full-records} is used, @command{tar} will not panic if an -attempt to read a record from the archive does not return a full record. -Instead, @command{tar} will keep reading until it has obtained a full +If @option{--read-full-records} is used, @command{tar} +will not panic if an attempt to read a record from the archive does +not return a full record. Instead, @command{tar} will keep reading +until it has obtained a full record. This option is turned on by default when @command{tar} is reading @@ -8374,9 +8840,9 @@ regardless of which archive or what part of the archive the tape head is on. Before writing an archive, you should make sure that no data on the tape will be overwritten (unless it is no longer needed). Before reading an archive, you should make sure the tape head is at -the beginning of the archive you want to read. (The @code{restore} -script will find the archive automatically. @FIXME-xref{Scripted Restoration}@xref{mt}, for -an explanation of the tape moving utility. +the beginning of the archive you want to read. You can do it manually +via @code{mt} utility (@pxref{mt}). The @code{restore} script does +that automatically (@pxref{Scripted Restoration}). If you want to add new archive file entries to a tape, you should advance the tape to the end of the existing file entries, backspace @@ -8394,7 +8860,7 @@ rrrr*rrrrrr*rrrrr*rr*rrrrr*rrr*rrrr**---------------- @FIXME{Is it true that this only works on non-block devices? should explain the difference, (fixed or variable).} -@value{xref-blocking-factor}. +@xref{Blocking Factor}. You can use the @command{mt} utility to advance or rewind a tape past a specified number of archive files on the tape. This will allow you @@ -8455,22 +8921,21 @@ failed. Often you might want to write a large archive, one larger than will fit on the actual tape you are using. In such a case, you can run multiple @command{tar} commands, but this can be inconvenient, particularly if you -are using options like @value{op-exclude} or dumping entire filesystems. +are using options like @option{--exclude=@var{pattern}} or dumping entire file systems. Therefore, @command{tar} supports multiple tapes automatically. -Use @value{op-multi-volume} on the command line, and then @command{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 @command{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 @value{op-multi-volume}, and then put in the -second tape when prompted, so @command{tar} can restore both halves of the -file.) +Use @option{--multi-volume} (@option{-M}) on the command line, and +then @command{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 @command{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 +@option{--multi-volume}, and then put in the second tape when +prompted, so @command{tar} can restore both halves of the file.) -@GNUTAR{} multi-volume archives do not use a truly -portable format. You need @GNUTAR{} at both end to -process them properly. +@GNUTAR{} multi-volume archives do not use a truly portable format. +You need @GNUTAR{} at both ends to process them properly. When prompting for a new tape, @command{tar} accepts any of the following responses: @@ -8483,7 +8948,8 @@ Request @command{tar} to exit immediately. @item n @var{file name} Request @command{tar} to write the next volume on the file @var{file name}. @item ! -Request @command{tar} to run a subshell. +Request @command{tar} to run a subshell. This option can be disabled +by giving @option{--restrict} command line option to @command{tar}. @item y Request @command{tar} to begin writing the next volume. @end table @@ -8491,56 +8957,110 @@ Request @command{tar} to begin writing the next volume. (You should only type @samp{y} after you have changed the tape; otherwise @command{tar} will write over the volume it just finished.) +@cindex End-of-archive info script +@cindex Info script +@anchor{info-script} +@opindex info-script +@opindex new-volume-script If you want more elaborate behavior than this, give @command{tar} the -@value{op-info-script} option. The file @var{script-name} is expected -to be a program (or shell script) to be run instead of the normal -prompting procedure. If the program fails, @command{tar} exits; -otherwise, @command{tar} begins writing the next volume. The behavior -of the -@samp{n} response to the normal tape-change prompt is not available -if you use @value{op-info-script}. +@option{--info-script=@var{script-name}} +(@option{--new-volume-script=@var{script-name}}, @option{-F +@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. It is executed without any command line +arguments. Additional data is passed to it via the following +environment variables: + +@table @env +@vrindex TAR_VERSION, info script environment variable +@item TAR_VERSION +@GNUTAR{} version number. + +@vrindex TAR_ARCHIVE, info script environment variable +@item TAR_ARCHIVE +The name of the archive @command{tar} is processing. + +@vrindex TAR_VOLUME, info script environment variable +@item TAR_VOLUME +Ordinal number of the volume @command{tar} is about to start. + +@vrindex TAR_SUBCOMMAND, info script environment variable +@item TAR_SUBCOMMAND +Short option describing the operation @command{tar} is executed. +@xref{Operations}, for a complete list of subcommand options. + +@vrindex TAR_FORMAT, info script environment variable +@item TAR_FORMAT +Format of the archive being processed. @xref{Formats}, for a complete +list of archive format names. +@end table + +The info script can instruct @command{tar} to use new archive name, +by writing in to file descriptor 3 (see below for an +example). + +If the info script fails, @command{tar} exits; otherwise, it begins +writing the next volume. The method @command{tar} uses to detect end of tape is not perfect, and fails on some operating systems or on some devices. You can use the -@value{op-tape-length} option if @command{tar} can't detect the end of the -tape itself. This option selects @value{op-multi-volume} automatically. -The @var{size} argument should then be the usable size of the tape. -But for many devices, and floppy disks in particular, this option is -never required for real, as far as we know. - +@option{--tape-length=@var{size}} (@option{-L @var{size}}) option if +@command{tar} can't detect the end of the tape itself. This option +selects @option{--multi-volume} (@option{-M}) automatically. The +@var{size} argument should then be the usable size of the tape in +units of 1024 bytes. But for many devices, and floppy disks in +particular, this option is never required for real, as far as we know. + +@cindex Volume number file +@cindex volno file +@anchor{volno-file} +@opindex volno-file The volume number used by @command{tar} in its tape-change prompt -can be changed; if you give the @value{op-volno-file} option, then -@var{file-of-number} should be an unexisting file to be created, or else, -a file already containing a decimal number. That number will be used -as the volume number of the first volume written. When @command{tar} is -finished, it will rewrite the file with the now-current volume number. -(This does not change the volume number written on a tape label, as -per @value{ref-label}, it @emph{only} affects the number used in -the prompt.) - -If you want @command{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 @value{op-info-script}. -Therefore, if you give @command{tar} multiple @value{op-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 @command{tar} prompt for a tape change (or run the info -script). - -Multi-volume archives - -With @value{op-multi-volume}, @command{tar} will not abort when it cannot -read or write any more data. Instead, it will ask you to prepare a new -volume. If the archive is on a magnetic tape, you should change tapes -now; if the archive is on a floppy disk, you should change disks, etc. +can be changed; if you give the +@option{--volno-file=@var{file-of-number}} option, then +@var{file-of-number} should be an unexisting file to be created, or +else, a file already containing a decimal number. That number will be +used as the volume number of the first volume written. When +@command{tar} is finished, it will rewrite the file with the +now-current volume number. (This does not change the volume number +written on a tape label, as per @ref{label}, it @emph{only} affects +the number used in the prompt.) + +If you want @command{tar} to cycle through a series of files or tape +drives, there are three approaches to choose from. First of all, you +can give @command{tar} multiple @option{--file} options. In this case +the specified files will be used, in sequence, as the successive +volumes of the archive. Only when the first one in the sequence needs +to be used again will @command{tar} prompt for a tape change (or run +the info script). Secondly, you can use the @samp{n} response to the +tape-change prompt, and, finally, you can use an info script, that +writes new archive name to file descriptor. The following example +illustrates this approach: + +@smallexample +@group +#! /bin/sh +echo Preparing volume $TAR_VOLUME of $TAR_ARCHIVE. + +name=`expr $TAR_ARCHIVE : '\(.*\)-.*'` +case $TAR_SUBCOMMAND in +-c) ;; +-d|-x|-t) test -r $@{name:-$TAR_ARCHIVE@}-$TAR_VOLUME || exit 1 + ;; +*) exit 1 +esac + +echo $@{name:-$TAR_ARCHIVE@}-$TAR_VOLUME >&3 +@end group +@end smallexample Each volume of a multi-volume archive is an independent @command{tar} archive, complete in itself. For example, you can list or extract any -volume alone; just don't specify @value{op-multi-volume}. However, if one -file in the archive is split across volumes, the only way to extract -it successfully is with a multi-volume extract command @option{--extract ---multi-volume} (@option{-xM}) starting on or before the volume where -the file begins. +volume alone; just don't specify @option{--multi-volume} +(@option{-M}). However, if one file in the archive is split across +volumes, the only way to extract it successfully is with a +multi-volume extract command @option{--extract --multi-volume} +(@option{-xM}) starting on or before the volume where the file begins. For example, let's presume someone has two tape drives on a system named @file{/dev/tape0} and @file{/dev/tape1}. For having @GNUTAR{} @@ -8555,6 +9075,8 @@ $ @kbd{tar cMff /dev/tape0 /dev/tape1 @var{files}} @menu * Multi-Volume Archives:: Archives Longer than One Tape or Disk * Tape Files:: Tape Files +* Tarcat:: Concatenate Volumes into a Single Archive + @end menu @node Multi-Volume Archives @@ -8562,14 +9084,15 @@ $ @kbd{tar cMff /dev/tape0 /dev/tape1 @var{files}} @cindex Multi-volume archives @UNREVISED +@opindex multi-volume To create an archive that is larger than will fit on a single unit of -the media, use the @value{op-multi-volume} option in conjunction with -the @value{op-create} option (@pxref{create}). A -@dfn{multi-volume} archive can be manipulated like any other archive -(provided the @value{op-multi-volume} option is specified), but is -stored on more than one tape or disk. +the media, use the @option{--multi-volume} (@option{-M}) option in conjunction with +the @option{--create} option (@pxref{create}). A @dfn{multi-volume} +archive can be manipulated like any other archive (provided the +@option{--multi-volume} option is specified), but is stored on more +than one tape or disk. -When you specify @value{op-multi-volume}, @command{tar} does not report an +When you specify @option{--multi-volume}, @command{tar} does not report an error when it comes to the end of an archive volume (when reading), or the end of the media (when writing). Instead, it prompts you to load a new storage volume. If the archive is on a magnetic tape, you @@ -8578,37 +9101,43 @@ floppy disk, you should change disks; etc. You can read each individual volume of a multi-volume archive as if it were an archive by itself. For example, to list the contents of one -volume, use @value{op-list}, without @value{op-multi-volume} specified. +volume, use @option{--list}, without @option{--multi-volume} specified. To extract an archive member from one volume (assuming it is described -that volume), use @value{op-extract}, again without -@value{op-multi-volume}. +that volume), use @option{--extract}, again without +@option{--multi-volume}. If an archive member is split across volumes (ie. its entry begins on one volume of the media and ends on another), you need to specify -@value{op-multi-volume} to extract it successfully. In this case, you +@option{--multi-volume} to extract it successfully. In this case, you should load the volume where the archive member starts, and use @samp{tar --extract --multi-volume}---@command{tar} will prompt for later volumes as it needs them. @xref{extracting archives}, for more information about extracting archives. -@value{op-info-script} is like @value{op-multi-volume}, except that -@command{tar} does not prompt you directly to change media volumes when -a volume is full---instead, @command{tar} runs commands you have stored -in @var{script-name}. For example, this option can be used to eject +@option{--info-script=@var{script-name}} +(@option{--new-volume-script=@var{script-name}}, @option{-F +@var{script-name}}) (@pxref{info-script}) is like +@option{--multi-volume} (@option{-M}), except that @command{tar} does +not prompt you directly to change media volumes when a volume is +full---instead, @command{tar} runs commands you have stored in +@var{script-name}. For example, this option can be used to eject cassettes, or to broadcast messages such as @samp{Someone please come -change my tape} when performing unattended backups. When @var{script-name} -is done, @command{tar} will assume that the media has been changed. +change my tape} when performing unattended backups. When +@var{script-name} is done, @command{tar} will assume that the media +has been changed. Multi-volume archives can be modified like any other archive. To add files to a multi-volume archive, you need to only mount the last volume of the archive media (and new volumes, if needed). For all other operations, you need to use the entire archive. -If a multi-volume archive was labeled using @value{op-label} -(@value{pxref-label}) when it was created, @command{tar} will not -automatically label volumes which are added later. To label subsequent -volumes, specify @value{op-label} again in conjunction with the -@value{op-append}, @value{op-update} or @value{op-concatenate} operation. +If a multi-volume archive was labeled using +@option{--label=@var{archive-label}} (@option{-V @var{archive-label}}) +(@pxref{label}) when it was created, @command{tar} will not +automatically label volumes which are added later. To label +subsequent volumes, specify @option{--label=@var{archive-label}} again +in conjunction with the @option{--append}, @option{--update} or +@option{--concatenate} operation. @cindex Labeling multi-volume archives @FIXME{example} @@ -8620,14 +9149,15 @@ before end. Is the exit status even checked in tar? :-(} @item --multi-volume @itemx -M Creates a multi-volume archive, when used in conjunction with -@value{op-create}. To perform any other operation on a multi-volume -archive, specify @value{op-multi-volume} in conjunction with that +@option{--create} (@option{-c}). To perform any other operation on a multi-volume +archive, specify @option{--multi-volume} in conjunction with that operation. @item --info-script=@var{program-file} +@itemx --new-volume-script=@var{program-file} @itemx -F @var{program-file} Creates a multi-volume archive via a script. Used in conjunction with -@value{op-create}. +@option{--create} (@option{-c}). @xref{info-script}, dor a detailed discussion. @end table Beware that there is @emph{no} real standard about the proper way, for @@ -8648,16 +9178,17 @@ machines between which you know exchange of files is possible. @UNREVISED To give the archive a name which will be recorded in it, use the -@value{op-label} option. This will write a special block identifying -@var{volume-label} as the name of the archive to the front of the archive -which will be displayed when the archive is listed with @value{op-list}. -If you are creating a multi-volume archive with -@value{op-multi-volume}@FIXME-pxref{Using Multiple Tapes}, then the -volume label will have -@samp{Volume @var{nnn}} appended to the name you give, where @var{nnn} is -the number of the volume of the archive. (If you use the @value{op-label} -option when reading an archive, it checks to make sure the label on the -tape matches the one you give. @value{xref-label}. +@option{--label=@var{volume-label}} (@option{-V @var{volume-label}}) +option. This will write a special block identifying +@var{volume-label} as the name of the archive to the front of the +archive which will be displayed when the archive is listed with +@option{--list}. If you are creating a multi-volume archive with +@option{--multi-volume} (@pxref{Using Multiple Tapes}), then the +volume label will have @samp{Volume @var{nnn}} appended to the name +you give, where @var{nnn} is the number of the volume of the archive. +(If you use the @option{--label=@var{volume-label}}) option when +reading an archive, it checks to make sure the label on the tape +matches the one you give. @xref{label}. When @command{tar} writes an archive to tape, it creates a single tape file. If multiple archives are written to the same tape, one @@ -8675,36 +9206,63 @@ People seem to often do: or such, for pushing a common date in all volumes or an archive set. +@node Tarcat +@subsection Concatenate Volumes into a Single Archive + +@pindex tarcat + Sometimes it is necessary to convert existing @GNUTAR{} multi-volume +archive to a single @command{tar} archive. Simply concatenating all +volumes into one will not work, since each volume carries an additional +information at the beginning. @GNUTAR{} is shipped with the shell +script @command{tarcat} designed for this purpose. + + The script takes a list of files comprising a multi-volume archive +and creates the resulting archive at the standard output. For example: + +@smallexample +@kbd{tarcat vol.1 vol.2 vol.3 | tar tf -} +@end smallexample + + The script implements a simple heuristics to determine the format of +the first volume file and to decide how to process the rest of the +files. However, it makes no attempt to verify whether the files are +given in order or even if they are valid @command{tar} archives. +It uses @command{dd} and does not filter its standard error, so you +will usually see lots of spurious messages. + +@FIXME{The script is not installed. Should we install it?} + @node label @section Including a Label in the Archive @cindex Labeling an archive @cindex Labels on the archive media @UNREVISED -@cindex @option{--label} option introduced -@cindex @option{-V} option introduced +@opindex label To avoid problems caused by misplaced paper labels on the archive media, you can include a @dfn{label} entry---an archive member which contains the name of the archive---in the archive itself. Use the -@value{op-label} option in conjunction with the @value{op-create} operation -to include a label entry in the archive as it is being created. +@option{--label=@var{archive-label}} (@option{-V @var{archive-label}}) +option in conjunction with the @option{--create} operation to include +a label entry in the archive as it is being created. @table @option @item --label=@var{archive-label} @itemx -V @var{archive-label} Includes an @dfn{archive-label} at the beginning of the archive when the archive is being created, when used in conjunction with the -@value{op-create} operation. Checks to make sure the archive label +@option{--create} operation. Checks to make sure the archive label matches the one specified (when used in conjunction with any other operation. @end table - If you create an archive using both @value{op-label} and -@value{op-multi-volume}, each volume of the archive will have an -archive label of the form @samp{@var{archive-label} Volume @var{n}}, -where @var{n} is 1 for the first volume, 2 for the next, and so on. -@FIXME-xref{Multi-Volume Archives, for information on creating multiple -volume archives.} + If you create an archive using both +@option{--label=@var{archive-label}} (@option{-V @var{archive-label}}) +and @option{--multi-volume} (@option{-M}), each volume of the archive +will have an archive label of the form @samp{@var{archive-label} +Volume @var{n}}, where @var{n} is 1 for the first volume, 2 for the +next, and so on. @xref{Using Multiple Tapes}, for information on +creating multiple volume archives. @cindex Volume label, listing @cindex Listing volume label @@ -8716,11 +9274,11 @@ explicitely marked as in the example below: @group $ @kbd{tar --verbose --list --file=iamanarchive} V--------- 0 0 0 1992-03-07 12:01 iamalabel--Volume Header-- --rw-rw-rw- ringo user 40 1990-05-21 13:30 iamafilename +-rw-r--r-- ringo user 40 1990-05-21 13:30 iamafilename @end group @end smallexample -@cindex @option{--test-label} option introduced +@opindex test-label @anchor{--test-label option} However, @option{--list} option will cause listing entire contents of the archive, which may be undesirable (for example, if the @@ -8778,15 +9336,15 @@ is attempted@footnote{Previous versions of @command{tar} used full regular expression matching, or before that, only exact string matching, instead of wildcard matchers. We decided for the sake of simplicity to use a uniform matching device through -@command{tar}.}. If the switch @value{op-multi-volume} is being used, +@command{tar}.}. If the switch @option{--multi-volume} (@option{-M}) is being used, the volume label matcher will also suffix @var{archive-label} by @w{@samp{ Volume [1-9]*}} if the initial match fails, before giving up. Since the volume numbering is automatically added in labels at creation time, it sounded logical to equally help the user taking care of it when the archive is being read. - The @value{op-label} was once called @option{--volume}, but is not available -under that name anymore. + The @option{--label} was once called @option{--volume}, but is not +available under that name anymore. You can also use @option{--label} to get a common information on all tapes of a series. For having this information different in each @@ -8817,6 +9375,7 @@ is usually not the case. @table @option @item -W @itemx --verify +@opindex verify, short description Attempt to verify the archive after writing. @end table @@ -8834,9 +9393,11 @@ file system as the archive is being written, to verify a write operation, or can compare a previously written archive, to insure that it is up to date. +@opindex verify, using with @option{--create} +@opindex create, using with @option{--verify} To check for discrepancies in an archive immediately after it is -written, use the @value{op-verify} option in conjunction with -the @value{op-create} operation. When this option is +written, use the @option{--verify} (@option{-W}) option in conjunction with +the @option{--create} operation. When this option is specified, @command{tar} checks archive members against their counterparts in the file system, and reports discrepancies on the standard error. @@ -8845,33 +9406,35 @@ of the last written entry. This option is useful for detecting data errors on some tapes. Archives written to pipes, some cartridge tape drives, and some other devices cannot be verified. -One can explicitly compare an already made archive with the file system -by using the @value{op-compare} option, instead of using the more automatic -@value{op-verify} option. @value{xref-compare}. +One can explicitly compare an already made archive with the file +system by using the @option{--compare} (@option{--diff}, @option{-d}) +option, instead of using the more automatic @option{--verify} option. +@xref{compare}. Note that these two options have a slightly different intent. The -@value{op-compare} option how identical are the logical contents of some -archive with what is on your disks, while the @value{op-verify} option is +@option{--compare} option checks how identical are the logical contents of some +archive with what is on your disks, while the @option{--verify} option is really for checking if the physical contents agree and if the recording -media itself is of dependable quality. So, for the @value{op-verify} +media itself is of dependable quality. So, for the @option{--verify} operation, @command{tar} tries to defeat all in-memory cache pertaining to the archive, while it lets the speed optimization undisturbed for the -@value{op-compare} option. If you nevertheless use @value{op-compare} for +@option{--compare} option. If you nevertheless use @option{--compare} for media verification, you may have to defeat the in-memory cache yourself, maybe by opening and reclosing the door latch of your recording unit, forcing some doubt in your operating system about the fact this is really the same volume as the one just written or read. -The @value{op-verify} option would not be necessary if drivers were indeed +The @option{--verify} option would not be necessary if drivers were indeed able to detect dependably all write failures. This sometimes require many magnetic heads, some able to read after the writes occurred. One would not say that drivers unable to detect all cases are necessarily flawed, as long as programming is concerned. -The @value{op-verify} option will not work in conjunction with the -@value{op-multi-volume} option or the @value{op-append}, -@value{op-update} and @value{op-delete} operations. @xref{Operations}, -for more information on these operations. +The @option{--verify} (@option{-W}) option will not work in +conjunction with the @option{--multi-volume} (@option{-M}) option or +the @option{--append} (@option{-r}), @option{--update} (@option{-u}) +and @option{--delete} operations. @xref{Operations}, for more +information on these operations. Also, since @command{tar} normally strips leading @samp{/} from file names (@pxref{absolute}), a command like @samp{tar --verify -cf @@ -8895,14 +9458,279 @@ disabled) switch, a notch which can be popped out or covered, a ring which can be removed from the center of a tape reel, or some other changeable feature. -@node Free Software Needs Free Documentation -@appendix Free Software Needs Free Documentation -@include freemanuals.texi +@node Changes +@appendix Changes + +This appendix lists some important user-visible changes between +version @GNUTAR{} @value{VERSION} and previous versions. An up-to-date +version of this document is available at +@uref{http://www.gnu.org/@/software/@/tar/manual/changes.html,the +@GNUTAR{} documentation page}. + +@table @asis +@item Use of short option @option{-o}. + +Earlier versions of @GNUTAR{} understood @option{-o} command line +option as a synonym for @option{--old-archive}. + +@GNUTAR{} starting from version 1.13.90 understands this option as +a synonym for @option{--no-same-owner}. This is compatible with +UNIX98 @command{tar} implementations. + +However, to facilitate transition, @option{-o} option retains its +old semantics when it is used with one of archive-creation commands. +Users are encouraged to use @option{--format=oldgnu} instead. + +It is especially important, since versions of @acronym{GNU} Automake +up to and including 1.8.4 invoke tar with this option to produce +distribution tarballs. @xref{Formats,v7}, for the detailed discussion +of this issue and its implications. + +Future versions of @GNUTAR{} will understand @option{-o} only as a +synonym for @option{--no-same-owner}. + +@item Use of short option @option{-l} + +Earlier versions of @GNUTAR{} understood @option{-l} option as a +synonym for @option{--one-file-system}. Such usage is deprecated. +For compatibility with other implementations future versions of +@GNUTAR{} will understand this option as a synonym for +@option{--check-links}. + +@item Use of options @option{--portability} and @option{--old-archive} + +These options are deprecated. Please use @option{--format=v7} instead. + +@item Use of option @option{--posix} + +This option is deprecated. Please use @option{--format=posix} instead. +@end table + +@node Configuring Help Summary +@appendix Configuring Help Summary + +Running @kbd{tar --help} displays the short @command{tar} option +summary (@pxref{help}). This summary is organised by @dfn{groups} of +semantically close options. The options within each group are printed +in the following order: a short option, eventually followed by a list +of corresponding long option names, followed by a short description of +the option. For example, here is an excerpt from the actual @kbd{tar +--help} output: + +@verbatim + Main operation mode: + + -A, --catenate, --concatenate append tar files to an archive + -c, --create create a new archive + -d, --diff, --compare find differences between archive and + file system + --delete delete from the archive +@end verbatim + +@vrindex ARGP_HELP_FMT, environment variable +The exact visual representation of the help output is configurable via +@env{ARGP_HELP_FMT} environment variable. The value of this variable +is a comma-separated list of @dfn{format variable} assignments. There +are two kinds of format variables. An @dfn{offset variable} keeps the +offset of some part of help output text from the leftmost column on +the screen. A @dfn{boolean} variable is a flag that toggles some +output feature on or off. Depending on the type of the corresponding +variable, there are two kinds of assignments: + +@table @asis +@item Offset assignment + +The assignment to an offset variable has the following syntax: + +@smallexample +@var{variable}=@var{value} +@end smallexample + +@noindent +where @var{variable} is the variable name, and @var{value} is a +numeric value to be assigned to the variable. + +@item Boolean assignment + +To assign @code{true} value to a variable, simply put this variable name. To +assign @code{false} value, prefix the variable name with @samp{no-}. For +example: + +@smallexample +@group +# Assign @code{true} value: +dup-args +# Assign @code{false} value: +no-dup-args +@end group +@end smallexample +@end table + +Following variables are declared: + +@deftypevr {Help Output} boolean dup-args +If true, arguments for an option are shown with both short and long +options, even when a given option has both forms, for example: + +@smallexample + -f ARCHIVE, --file=ARCHIVE use archive file or device ARCHIVE +@end smallexample + +If false, then if an option has both short and long forms, the +argument is only shown with the long one, for example: + +@smallexample + -f, --file=ARCHIVE use archive file or device ARCHIVE +@end smallexample + +@noindent +and a message indicating that the argument is applicable to both +forms is printed below the options. This message can be disabled +using @code{dup-args-note} (see below). + +The default is false. +@end deftypevr + +@deftypevr {Help Output} boolean dup-args-note +If this variable is true, which is the default, the following notice +is displayed at the end of the help output: + +@quotation +Mandatory or optional arguments to long options are also mandatory or +optional for any corresponding short options. +@end quotation + +Setting @code{no-dup-args-note} inhibits this message. Normally, only one of +variables @code{dup-args} or @code{dup-args-note} should be set. +@end deftypevr + +@deftypevr {Help Output} offset short-opt-col +Column in which short options start. Default is 2. + +@smallexample +@group +$ @kbd{tar --help|grep ARCHIVE} + -f, --file=ARCHIVE use archive file or device ARCHIVE +$ @kbd{ARGP_HELP_FMT=short-opt-col=6 tar --help|grep ARCHIVE} + -f, --file=ARCHIVE use archive file or device ARCHIVE +@end group +@end smallexample +@end deftypevr + +@deftypevr {Help Output} offset long-opt-col +Column in which long options start. Default is 6. For example: + +@smallexample +@group +$ @kbd{tar --help|grep ARCHIVE} + -f, --file=ARCHIVE use archive file or device ARCHIVE +$ @kbd{ARGP_HELP_FMT=long-opt-col=16 tar --help|grep ARCHIVE} + -f, --file=ARCHIVE use archive file or device ARCHIVE +@end group +@end smallexample +@end deftypevr + +@deftypevr {Help Output} offset doc-opt-col +Column in which @dfn{doc options} start. A doc option isn't actually +an option, but rather an arbitrary piece of documentation that is +displayed in much the same manner as the options. For example, in +the description of @option{--format} option: + +@smallexample +@group + -H, --format=FORMAT create archive of the given format. + + FORMAT is one of the following: + + gnu GNU tar 1.13.x format + oldgnu GNU format as per tar <= 1.12 + pax POSIX 1003.1-2001 (pax) format + posix same as pax + ustar POSIX 1003.1-1988 (ustar) format + v7 old V7 tar format +@end group +@end smallexample + +@noindent +the format names are doc options. Thus, if you set +@kbd{ARGP_HELP_FMT=doc-opt-col=6} the above part of the help output +will look as follows: + +@smallexample +@group + -H, --format=FORMAT create archive of the given format. + + FORMAT is one of the following: + + gnu GNU tar 1.13.x format + oldgnu GNU format as per tar <= 1.12 + pax POSIX 1003.1-2001 (pax) format + posix same as pax + ustar POSIX 1003.1-1988 (ustar) format + v7 old V7 tar format +@end group +@end smallexample +@end deftypevr + +@deftypevr {Help Output} offset opt-doc-col +Column in which option description starts. Default is 29. + +@smallexample +@group +$ @kbd{tar --help|grep ARCHIVE} + -f, --file=ARCHIVE use archive file or device ARCHIVE +$ @kbd{ARGP_HELP_FMT=opt-doc-col=19 tar --help|grep ARCHIVE} + -f, --file=ARCHIVE use archive file or device ARCHIVE +$ @kbd{ARGP_HELP_FMT=opt-doc-col=9 tar --help|grep ARCHIVE} + -f, --file=ARCHIVE + use archive file or device ARCHIVE +@end group +@end smallexample + +@noindent +Notice, that the description starts on a separate line if +@code{opt-doc-col} value is too small. +@end deftypevr + +@deftypevr {Help Output} offset header-col +Column in which @dfn{group headers} are printed. A group header is a +descriptive text preceding an option group. For example, in the +following text: + +@verbatim + Main operation mode: + + -A, --catenate, --concatenate append tar files to + an archive + -c, --create create a new archive +@end verbatim +@noindent +@samp{Main operation mode:} is the group header. + +The default value is 1. +@end deftypevr + +@deftypevr {Help Output} offset usage-indent +Indentation of wrapped usage lines. Affects @option{--usage} +output. Default is 12. +@end deftypevr + +@deftypevr {Help Output} offset rmargin +Right margin of the text output. Used for wrapping. +@end deftypevr @node Genfile @appendix Genfile @include genfile.texi +@node Snapshot Files +@appendix Format of the Incremental Snapshot Files +@include snapshot.texi + +@node Free Software Needs Free Documentation +@appendix Free Software Needs Free Documentation +@include freemanuals.texi + @node Copying This Manual @appendix Copying This Manual @@ -8912,6 +9740,19 @@ changeable feature. @include fdl.texi +@node Index of Command Line Options +@appendix Index of Command Line Options + +This appendix contains an index of all @GNUTAR{} long command line +options. The options are listed without the preceeding double-dash. + +@FIXME{@itemize +@item Make sure @emph{all} options are indexed. +@item Provide an index of short options +@end itemize} + +@printindex op + @node Index @appendix Index