X-Git-Url: https://git.dogcows.com/gitweb?a=blobdiff_plain;f=doc%2Ftar.texi;h=ed8e5264b94b754540b2509ec1528e2f26f0c985;hb=bffe1074aab0bd180b6b522f07f951f73ef59191;hp=993db4cfef7321b538c4e5c0a2625f78f4d228c0;hpb=d5f2066cac82e84ba43e22c9718e381732f8454d;p=chaz%2Ftar diff --git a/doc/tar.texi b/doc/tar.texi index 993db4c..ed8e526 100644 --- a/doc/tar.texi +++ b/doc/tar.texi @@ -21,12 +21,14 @@ @include value.texi @defcodeindex op +@defcodeindex kw @c Put everything in one index (arbitrarily chosen to be the concept index). @syncodeindex fn cp @syncodeindex ky cp @syncodeindex pg cp @syncodeindex vr cp +@syncodeindex kw cp @copying @@ -35,7 +37,7 @@ This manual is for @acronym{GNU} @command{tar} (version from archives. Copyright @copyright{} 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001, -2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc. +2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -177,6 +179,7 @@ Invoking @GNUTAR{} * defaults:: * verbose:: * checkpoints:: +* warnings:: * interactive:: The Three Option Styles @@ -1429,12 +1432,12 @@ example: @smallexample @group -$ @kbd{tar cfv archive /etc/mail} +$ @kbd{tar --create --verbose --file archive /etc/mail} tar: Removing leading `/' from member names /etc/mail/ /etc/mail/sendmail.cf /etc/mail/aliases -$ @kbd{tar tf archive} +$ @kbd{tar --test --file archive} etc/mail/ etc/mail/sendmail.cf etc/mail/aliases @@ -1516,7 +1519,6 @@ all the files (including sub-directories) in that directory. @node extract @section How to Extract Members from an Archive -@UNREVISED @cindex Extraction @cindex Retrieving files from an archive @cindex Resurrecting files from an archive @@ -1768,7 +1770,6 @@ be in the rest of the manual.} @node tar invocation @chapter Invoking @GNUTAR{} -@UNREVISED This chapter is about how one invokes the @GNUTAR{} command, from the command synopsis (@pxref{Synopsis}). There are @@ -1801,6 +1802,7 @@ and @option{--interactive} options (@pxref{interactive}). * defaults:: * verbose:: * checkpoints:: +* warnings:: * interactive:: @end menu @@ -1879,15 +1881,14 @@ will act on the entire contents of the archive. @cindex return status Besides successful exits, @GNUTAR{} may fail for many reasons. Some reasons correspond to bad usage, that is, when the -@command{tar} command is improperly written. Errors may be -encountered later, while encountering an error processing the archive -or the files. Some errors are recoverable, in which case the failure -is delayed until @command{tar} has completed all its work. Some -errors are such that it would not meaningful, or at least risky, to -continue processing: @command{tar} then aborts processing immediately. -All abnormal exits, whether immediate or delayed, should always be -clearly diagnosed on @code{stderr}, after a line stating the nature of -the error. +@command{tar} command line is improperly written. Errors may be +encountered later, while processing the archive or the files. Some +errors are recoverable, in which case the failure is delayed until +@command{tar} has completed all its work. Some errors are such that +it would be not meaningful, or at least risky, to continue processing: +@command{tar} then aborts processing immediately. All abnormal exits, +whether immediate or delayed, should always be clearly diagnosed on +@code{stderr}, after a line stating the nature of the error. Possible exit codes of @GNUTAR{} are summarized in the following table: @@ -1924,7 +1925,7 @@ remote device (@pxref{Remote Tape Server}). allow you to perform a variety of tasks. You are required to choose one operating mode each time you employ the @command{tar} program by specifying one, and only one operation as an argument to the -@command{tar} command (two lists of four operations each may be found +@command{tar} command (the corresponding options may be found at @ref{frequent operations} and @ref{Operations}). Depending on circumstances, you may also wish to customize how the chosen operating mode behaves. For example, you may wish to change the way the output @@ -2007,6 +2008,10 @@ attention to them. @node Long Options @subsection Long Option Style +@cindex long options +@cindex options, long style +@cindex options, GNU style +@cindex options, mnemonic names Each option has at least one @dfn{long} (or @dfn{mnemonic}) name starting with two dashes in a row, e.g., @option{--list}. The long names are more clear than their corresponding short or old names. It sometimes happens that a @@ -2035,6 +2040,8 @@ $ @kbd{tar --create --verbose --blocking-factor=20 --file=/dev/rmt0} gives a fairly good set of hints about what the command does, even for those not fully acquainted with @command{tar}. +@cindex arguments to long options +@cindex long options with mandatory arguments Long options which require arguments take those arguments immediately following the option name. There are two ways of specifying a mandatory argument. It can be separated from the @@ -2044,6 +2051,8 @@ tells the name of the @command{tar} archive) is given a file such as @file{archive.tar} as argument by using any of the following notations: @option{--file=archive.tar} or @option{--file archive.tar}. +@cindex optional arguments to long options +@cindex long options with optional arguments In contrast, optional arguments must always be introduced using an equal sign. For example, the @option{--backup} option takes an optional argument specifying backup type. It must be used @@ -2052,6 +2061,9 @@ as @option{--backup=@var{backup-type}}. @node Short Options @subsection Short Option Style +@cindex short options +@cindex options, short style +@cindex options, traditional Most options also have a @dfn{short option} name. Short options start with a single dash, and are followed by a single character, e.g., @option{-t} (which is equivalent to @option{--list}). The forms are absolutely @@ -2059,6 +2071,8 @@ identical in function; they are interchangeable. The short option names are faster to type than long option names. +@cindex arguments to short options +@cindex short options with mandatory arguments Short options which require arguments take their arguments immediately following the option, usually separated by white space. It is also possible to stick the argument right after the short option name, using @@ -2068,6 +2082,8 @@ archive.tar}} or @option{-farchive.tar} instead of using @w{@option{-f @var{archive-name}}} denote the option which indicates a specific archive, here named @file{archive.tar}. +@cindex optional arguments to short options +@cindex short options with optional arguments Short options which take optional arguments take their arguments immediately following the option letter, @emph{without any intervening white space characters}. @@ -2095,7 +2111,8 @@ end up overwriting files. @node Old Options @subsection Old Option Style -@UNREVISED +@cindex options, old style +@cindex old option style Like short options, @dfn{old options} are single letters. However, old options must be written together as a single clumped set, without spaces separating @@ -2110,6 +2127,8 @@ the same as the short option @option{-t}, and consequently, the same as the long option @option{--list}. So for example, the command @w{@samp{tar cv}} specifies the option @option{-v} in addition to the operation @option{-c}. +@cindex arguments to old options +@cindex old options with mandatory arguments When options that need arguments are given together with the command, all the associated arguments follow, in the same order as the options. Thus, the example given previously could also be written in the old @@ -2173,6 +2192,7 @@ equivalent to @w{@samp{tar -c}:} both of them specify the @node Mixing @subsection Mixing Option Styles +@cindex options, mixing different styles All three styles may be intermixed in a single @command{tar} command, so long as the rules for each style are fully respected@footnote{Before @GNUTAR{} version 1.11.6, @@ -2407,7 +2427,8 @@ superuser privileges and can be a pain to manage. @itemx -a During a @option{--create} operation, enables automatic compressed -format recognition based on the archive suffix. @xref{gzip}. +format recognition based on the archive suffix. The effect of this +option is cancelled by @option{--no-auto-compress}. @xref{gzip}. @opsummary{backup} @item --backup=@var{backup-type} @@ -2451,7 +2472,7 @@ messages as it reads through the archive. It is intended for when you want a visual indication that @command{tar} is still running, but don't want to see @option{--verbose} output. You can also instruct @command{tar} to execute a list of actions on each checkpoint, see -@option{--checklist-action} below. For a detailed description, see +@option{--checkpoint-action} below. For a detailed description, see @ref{checkpoints}. @opsummary{checkpoint-action} @@ -2551,6 +2572,10 @@ during archive creation, it is order sensitive. @xref{directory}. When performing operations, @command{tar} will skip files that match @var{pattern}. @xref{exclude}. +@opsummary{exclude-backups} +@item --exclude-backups +Exclude backup and lock files. @xref{exclude,, exclude-backups}. + @opsummary{exclude-from} @item --exclude-from=@var{file} @itemx -X @var{file} @@ -2564,7 +2589,7 @@ patterns in the file @var{file}. @xref{exclude}. Exclude from dump any directory containing a valid cache directory tag file, but still dump the directory node and the tag file itself. -@xref{exclude}. +@xref{exclude,, exclude-caches}. @opsummary{exclude-caches-under} @item --exclude-caches-under @@ -2584,19 +2609,20 @@ tag file. @xref{exclude}. @item --exclude-tag=@var{file} Exclude from dump any directory containing file named @var{file}, but -dump the directory node and @var{file} itself. @xref{exclude}. +dump the directory node and @var{file} itself. @xref{exclude,, exclude-tag}. @opsummary{exclude-tag-under} @item --exclude-tag-under=@var{file} Exclude from dump the contents of any directory containing file -named @var{file}, but dump the directory node itself. @xref{exclude}. +named @var{file}, but dump the directory node itself. @xref{exclude,, +exclude-tag-under}. @opsummary{exclude-tag-all} @item --exclude-tag-all=@var{file} Exclude from dump any directory containing file named @var{file}. -@xref{exclude}. +@xref{exclude,,exclude-tag-all}. @opsummary{exclude-vcs} @item --exclude-vcs @@ -2604,7 +2630,7 @@ Exclude from dump any directory containing file named @var{file}. Exclude from dump directories and files, that are internal for some widely used version control systems. -@xref{exclude}. +@xref{exclude,,exclude-vcs}. @opsummary{file} @item --file=@var{archive} @@ -2773,6 +2799,17 @@ 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}. @xref{Tape Files}. +@opsummary{level} +@item --level=@var{n} +Force incremental backup of level @var{n}. As of @GNUTAR version +@value{VERSION}, the option @option{--level=0} truncates the snapshot +file, thereby forcing the level 0 dump. Other values of @var{n} are +effectively ignored. @xref{--level=0}, for details and examples. + +The use of this option is valid only in conjunction with the +@option{--listed-incremental} option. @xref{Incremental Dumps}, +for a detailed description. + @opsummary{listed-incremental} @item --listed-incremental=@var{snapshot-file} @itemx -g @var{snapshot-file} @@ -2783,12 +2820,23 @@ backup, using @var{snapshot-file} to determine which files to backup. With other operations, informs @command{tar} that the archive is in incremental format. @xref{Incremental Dumps}. +@opsummary{lzip} +@item --lzip + +This option tells @command{tar} to read or write archives through +@command{lzip}. @xref{gzip}. + @opsummary{lzma} @item --lzma This option tells @command{tar} to read or write archives through @command{lzma}. @xref{gzip}. +@item --lzop + +This option tells @command{tar} to read or write archives through +@command{lzop}. @xref{gzip}. + @opsummary{mode} @item --mode=@var{permissions} @@ -2843,6 +2891,12 @@ changed). @xref{after}. An exclude pattern can match any subsequence of the name's components. @xref{controlling pattern-matching}. +@opsummary{no-auto-compress} +@item --no-auto-compress + +Disables automatic compressed format recognition based on the archive +suffix. @xref{--auto-compress}. @xref{gzip}. + @opsummary{no-check-device} @item --no-check-device Do not check device numbers when creating a list of modified files @@ -2867,6 +2921,13 @@ Use case-sensitive matching. Print warnings about subprocesses that terminated with a nonzero exit code. @xref{Writing to an External Program}. +@opsummary{no-null} +@item --no-null + +If the @option{--null} option was given previously, this option +cancels its effect, so that any following @option{--files-from} +options will expect their file lists to be newline-terminated. + @opsummary{no-overwrite-dir} @item --no-overwrite-dir @@ -2900,6 +2961,14 @@ 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. +@opsummary{no-seek} +@item --no-seek + +The archive media does not support seeks to arbitrary +locations. Usually @command{tar} determines automatically whether +the archive can be seeked or not. Use this option to disable this +mechanism. + @opsummary{no-unquote} @item --no-unquote Treat all input file or member names literally, do not interpret @@ -2997,8 +3066,8 @@ This option does not affect extraction from archives. @opsummary{pax-option} @item --pax-option=@var{keyword-list} -This option is meaningful only with @acronym{POSIX.1-2001} archives -(@pxref{posix}). It modifies the way @command{tar} handles the +This option enables creation of the archive in @acronym{POSIX.1-2001} +format (@pxref{posix}) and modifies the way @command{tar} handles the extended header keywords. @var{Keyword-list} is a comma-separated list of keyword options. @xref{PAX keywords}, for a detailed discussion. @@ -3130,7 +3199,9 @@ effect only for ordinary users. @xref{Attributes}. 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. +in cases when such recognition fails. It takes effect only if the +archive is open for reading (e.g. with @option{--list} or +@option{--extract} options). @opsummary{show-defaults} @item --show-defaults @@ -3246,8 +3317,9 @@ rather than the data modification time stored in the archive. @xref{Data Modification Times}. @opsummary{transform} +@opsummary{xform} @item --transform=@var{sed-expr} - +@itemx --xform=@var{sed-expr} Transform file or member names using @command{sed} replacement expression @var{sed-expr}. For example, @@ -3288,6 +3360,7 @@ name quoting}. @opsummary{use-compress-program} @item --use-compress-program=@var{prog} +@itemx -I=@var{prog} Instructs @command{tar} to access the archive through @var{prog}, which is presumed to be a compression program of some sort. @xref{gzip}. @@ -3328,6 +3401,13 @@ Used in conjunction with @option{--multi-volume}. @command{tar} will keep track of which volume of a multi-volume archive it is working in @var{file}. @xref{volno-file}. +@opsummary{warning} +@item --warning=@var{keyword} + +Enable or disable warning messages identified by @var{keyword}. The +messages are suppressed if @var{keyword} is prefixed with @samp{no-}. +@xref{warnings}. + @opsummary{wildcards} @item --wildcards Use wildcards when matching member names with patterns. @@ -3337,6 +3417,12 @@ Use wildcards when matching member names with patterns. @item --wildcards-match-slash Wildcards match @samp{/}. @xref{controlling pattern-matching}. + +@opsummary{xz} +@item --xz +@itemx -J +Use @command{xz} for compressing or decompressing the archives. @xref{gzip}. + @end table @node Short Option Summary @@ -3358,6 +3444,8 @@ them with the equivalent long option. @item -G @tab @ref{--incremental}. +@item -J @tab @ref{--xz}. + @item -K @tab @ref{--starting-file}. @item -L @tab @ref{--tape-length}. @@ -3411,7 +3499,7 @@ them with the equivalent long option. @item -o @tab When creating, @ref{--no-same-owner}, when extracting --- @ref{--portability}. -The later usage is deprecated. It is retained for compatibility with +The latter usage is deprecated. It is retained for compatibility with the earlier versions of @GNUTAR{}. In future releases @option{-o} will be equivalent to @option{--no-same-owner} only. @@ -3718,7 +3806,7 @@ If @option{--block-number} (@option{-R}) is used, @command{tar} prints, along wi 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 +file on the archive. As of now, if the archive is 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 @option{--block-number} (@option{-R}) is used. Note that @GNUTAR{} @@ -3886,15 +3974,15 @@ The name of the archive @command{tar} is processing. @vrindex TAR_BLOCKING_FACTOR, checkpoint script environment @item TAR_BLOCKING_FACTOR -Current blocking factor (@pxref{Blocking}. +Current blocking factor (@pxref{Blocking}). @vrindex TAR_CHECKPOINT, checkpoint script environment @item TAR_CHECKPOINT -The checkpoint number. +Number of the checkpoint. @vrindex TAR_SUBCOMMAND, checkpoint script environment @item TAR_SUBCOMMAND -A short option describing the operation @command{tar} is executing +A short option describing the operation @command{tar} is executing. @xref{Operations}, for a complete list of subcommand options. @vrindex TAR_FORMAT, checkpoint script environment @@ -3923,6 +4011,144 @@ This example also illustrates the fact that @option{--checkpoint}. In this case, the default checkpoint frequency (at each 10th record) is assumed. +@node warnings +@section Controlling Warning Messages + +Sometimes, while performing the requested task, @GNUTAR{} notices +some conditions that are not exactly erros, but which the user +should be aware of. When this happens, @command{tar} issues a +@dfn{warning message} describing the condition. Warning messages +are output to the standard error and they do not affect the exit +code of @command{tar} command. + +@xopindex{warning, explained} +@GNUTAR{} allows the user to suppress some or all of its warning +messages: + +@table @option +@item --warning=@var{keyword} +Control display of the warning messages identified by @var{keyword}. +If @var{keyword} starts with the prefix @samp{no-}, such messages are +suppressed. Otherwise, they are enabled. + +Multiple @option{--warning} messages accumulate. + +The tables below list allowed values for @var{keyword} along with the +warning messages they control. +@end table + +@subheading Keywords controlling @command{tar} operation +@table @asis +@kwindex all +@item all +Enable all warning messages. This is the default. +@kwindex none +@item none +Disable all warning messages. +@kwindex filename-with-nuls +@cindex @samp{file name read contains nul character}, warning message +@item filename-with-nuls +@samp{%s: file name read contains nul character} +@kwindex alone-zero-block +@cindex @samp{A lone zero block at}, warning message +@item alone-zero-block +@samp{A lone zero block at %s} +@end table + +@subheading Keywords applicable for @command{tar --create} +@table @asis +@kwindex cachedir +@cindex @samp{contains a cache directory tag}, warning message +@item cachedir +@samp{%s: contains a cache directory tag %s; %s} +@kwindex file-shrank +@cindex @samp{File shrank by %s bytes}, warning message +@item file-shrank +@samp{%s: File shrank by %s bytes; padding with zeros} +@kwindex xdev +@cindex @samp{file is on a different filesystem}, warning message +@item xdev +@samp{%s: file is on a different filesystem; not dumped} +@kwindex file-ignored +@cindex @samp{Unknown file type; file ignored}, warning message +@cindex @samp{socket ignored}, warning message +@cindex @samp{door ignored}, warning message +@item file-ignored +@samp{%s: Unknown file type; file ignored} +@samp{%s: socket ignored} +@*@samp{%s: door ignored} +@kwindex file-unchanged +@cindex @samp{file is unchanged; not dumped}, warning message +@item file-unchanged +@samp{%s: file is unchanged; not dumped} +@kwindex ignore-archive +@cindex @samp{file is the archive; not dumped}, warning message +@kwindex ignore-archive +@cindex @samp{file is the archive; not dumped}, warning message +@item ignore-archive +@samp{%s: file is the archive; not dumped} +@kwindex file-removed +@cindex @samp{File removed before we read it}, warning message +@item file-removed +@samp{%s: File removed before we read it} +@kwindex file-changed +@cindex @samp{file changed as we read it}, warning message +@item file-changed +@samp{%s: file changed as we read it} +@end table + +@subheading Keywords applicable for @command{tar --extract} +@table @asis +@kwindex timestamp +@cindex @samp{implausibly old time stamp %s}, warning message +@cindex @samp{time stamp %s is %s s in the future}, warning message +@item timestamp +@samp{%s: implausibly old time stamp %s} +@*@samp{%s: time stamp %s is %s s in the future} +@kwindex contiguous-cast +@cindex @samp{Extracting contiguous files as regular files}, warning message +@item contiguous-cast +@samp{Extracting contiguous files as regular files} +@kwindex symlink-cast +@cindex @samp{Attempting extraction of symbolic links as hard links}, warning message +@item symlink-cast +@samp{Attempting extraction of symbolic links as hard links} +@kwindex unknown-cast +@cindex @samp{Unknown file type `%c', extracted as normal file}, warning message +@item unknown-cast +@samp{%s: Unknown file type `%c', extracted as normal file} +@kwindex ignore-newer +@cindex @samp{Current %s is newer or same age}, warning message +@item ignore-newer +@samp{Current %s is newer or same age} +@kwindex unknown-keyword +@cindex @samp{Ignoring unknown extended header keyword `%s'}, warning message +@item unknown-keyword +@samp{Ignoring unknown extended header keyword `%s'} +@end table + +@subheading Keywords controlling incremental extraction: +@table @asis +@kwindex rename-directory +@cindex @samp{%s: Directory has been renamed from %s}, warning message +@cindex @samp{%s: Directory has been renamed}, warning message +@item rename-directory +@samp{%s: Directory has been renamed from %s} +@*@samp{%s: Directory has been renamed} +@kwindex new-directory +@cindex @samp{%s: Directory is new}, warning message +@item new-directory +@samp{%s: Directory is new} +@kwindex xdev +@cindex @samp{%s: directory is on a different device: not purging}, warning message +@item xdev +@samp{%s: directory is on a different device: not purging} +@kwindex bad-dumpdir +@cindex @samp{Malformed dumpdir: 'X' never used}, warning message +@item bad-dumpdir +@samp{Malformed dumpdir: 'X' never used} +@end table + @node interactive @section Asking for Confirmation During Operations @cindex Interactive operation @@ -4081,8 +4307,8 @@ it still introduces the info in the chapter correctly : ).} @node Operations @subsection The Five Advanced @command{tar} Operations -@UNREVISED +@cindex basic operations In the last chapter, you learned about the first three operations to @command{tar}. This chapter presents the remaining five operations to @command{tar}: @option{--append}, @option{--update}, @option{--concatenate}, @@ -4115,7 +4341,7 @@ The five operations that we will cover in this chapter are: @itemx -r Add new entries to an archive that already exists. @item --update -@itemx -r +@itemx -u Add more recent copies of archive members to the end of an archive, if they exist. @item --concatenate @@ -4132,8 +4358,8 @@ Compare archive members to their counterparts in the file system. @node append @subsection How to Add Files to Existing Archives: @option{--append} -@UNREVISED +@cindex appending files to existing archive @opindex append If you want to add files to an existing archive, you don't need to create a new archive; you can use @option{--append} (@option{-r}). @@ -4166,6 +4392,8 @@ the one in the archive and you invoke @command{tar} with member will end up being extracted, as it will replace the one extracted before it, and so on. +@cindex extracting @var{n}th copy of the file +@xopindex{occurrence, described} There exists a special option that allows you to get around this behavior and extract (or list) only a particular copy of the file. This is @option{--occurrence} option. If you run @command{tar} with @@ -4192,8 +4420,9 @@ with the Same Name.} @cindex Members, replacing with other members @cindex Replacing members with other members +@xopindex{delete, using before --append} 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 +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 added member will still appear last. In this sense, you cannot truly @@ -4208,10 +4437,10 @@ and @ref{Media}, for more information.) @node appending files @subsubsection Appending Files to an Archive -@UNREVISED @cindex Adding files to an Archive @cindex Appending files to an Archive @cindex Archives, Appending files to +@opindex append The simplest way to add a file to an already existing archive is the @option{--append} (@option{-r}) operation, which writes specified @@ -4255,6 +4484,8 @@ $ @kbd{tar --list --file=collection.tar} @node multiple @subsubsection Multiple Members with the Same Name +@cindex members, multiple +@cindex multiple members You can use @option{--append} (@option{-r}) to add copies of files which have been updated since the archive was created. (However, we @@ -4321,10 +4552,9 @@ $ @kbd{tar --extract -vv --occurrence --file=collection.tar blues} @node update @subsection Updating an Archive -@UNREVISED @cindex Updating an archive - @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 @@ -4351,6 +4581,7 @@ the @option{--backup} option. @xref{multiple}, for a detailed discussion. @node how to update @subsubsection How to Update an Archive Using @option{--update} +@opindex update You must use file name arguments with the @option{--update} (@option{-u}) operation. If you don't specify any files, @@ -4492,7 +4723,6 @@ information on dealing with archives improperly combined using the @node delete @subsection Removing Archive Members Using @option{--delete} -@UNREVISED @cindex Deleting files from an archive @cindex Removing files from an archive @@ -4547,7 +4777,6 @@ The @option{--delete} option has been reported to work properly when @node compare @subsection Comparing Archive Members with the File System @cindex Verifying the currency of an archive -@UNREVISED @opindex compare The @option{--compare} (@option{-d}), or @option{--diff} operation compares @@ -4702,7 +4931,7 @@ Do not exit with nonzero on unreadable files or directories. @node extract options @section Options Used by @option{--extract} -@UNREVISED +@cindex options for use with @option{--extract} @xopindex{extract, additional options} The previous chapter showed how to use @option{--extract} to extract @@ -4723,7 +4952,6 @@ considerations arise. You may review the information presented in @node Reading @subsection Options to Help Read Archives @cindex Options when reading archives -@UNREVISED @cindex Reading incomplete records @cindex Records, incomplete @@ -5183,7 +5411,7 @@ 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 +since the Epoch. If the archive provides times with nanosecond precision, the nanoseconds are appended to the timestamp after a decimal point. @@ -5208,9 +5436,32 @@ UID of the file owner. GID of the file owner. @end table -In addition to these variables, @env{TAR_VERSION} contains the +Additionally, the following variables contain information about +tar mode and the archive being processed: + +@table @env +@vrindex TAR_VERSION, to-command environment +@item TAR_VERSION @GNUTAR{} version number. +@vrindex TAR_ARCHIVE, to-command environment +@item TAR_ARCHIVE +The name of the archive @command{tar} is processing. + +@vrindex TAR_BLOCKING_FACTOR, to-command environment +@item TAR_BLOCKING_FACTOR +Current blocking factor (@pxref{Blocking}. + +@vrindex TAR_VOLUME, to-command environment +@item TAR_VOLUME +Ordinal number of the volume @command{tar} is processing. + +@vrindex TAR_FORMAT, to-command environment +@item TAR_FORMAT +Format of the archive being processed. @xref{Formats}, for a complete +list of archive format names. +@end table + If @var{command} exits with a non-0 status, @command{tar} will print an error message similar to the following: @@ -5323,9 +5574,9 @@ and @command{mv}, for example) offer similar options. Backup options may prove unexpectedly useful when extracting archives containing many members having identical name, or when extracting archives on systems having file name limitations, making different members appear -has having similar names through the side-effect of name truncation. -(This is true only if we have a good scheme for truncated backup names, -which I'm not sure at all: I suspect work is needed in this area.) +as having similar names through the side-effect of name truncation. +@FIXME{This is true only if we have a good scheme for truncated backup names, +which I'm not sure at all: I suspect work is needed in this area.} When any existing file is backed up before being overwritten by extraction, then clashing files are automatically be renamed to be unique, and the true name is kept for only the last file of a series of clashing files. @@ -5468,25 +5719,18 @@ and not archive them. @xref{Choosing}. @node Backups @chapter Performing Backups and Restoring Files -@UNREVISED +@cindex backups -@GNUTAR{} is distributed along with the scripts -which the Free Software Foundation uses for performing backups. There -is no corresponding scripts available yet for doing restoration of -files. Even if there is a good chance those scripts may be satisfying -to you, they are not the only scripts or methods available for doing +@GNUTAR{} is distributed along with the scripts for performing backups +and restores. Even if there is a good chance those scripts may be +satisfying to you, they are not the only scripts or methods available for doing backups and restore. You may well create your own, or use more sophisticated packages dedicated to that purpose. Some users are enthusiastic about @code{Amanda} (The Advanced Maryland Automatic Network Disk Archiver), a backup system developed by James da Silva @file{jds@@cs.umd.edu} and available on many Unix systems. -This is free software, and it is available at these places: - -@smallexample -http://www.cs.umd.edu/projects/amanda/amanda.html -ftp://ftp.cs.umd.edu/pub/amanda -@end smallexample +This is free software, and it is available from @uref{http://www.amanda.org}. @FIXME{ @@ -5606,7 +5850,7 @@ can be restored when extracting the archive. backups: @option{--listed-incremental=@var{snapshot-file}} (@option{-g @var{snapshot-file}}) and @option{--incremental} (@option{-G}). -@opindex listed-incremental +@xopindex{listed-incremental, described} 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 @@ -5680,6 +5924,20 @@ $ @kbd{tar --create \ /usr} @end smallexample +@anchor{--level=0} +@xopindex{level, described} +You can force @samp{level 0} backups either by removing the snapshot +file before running @command{tar}, or by supplying the +@option{--level=0} option, e.g.: + +@smallexample +$ @kbd{tar --create \ + --file=archive.2.tar \ + --listed-incremental=/var/log/usr.snar-0 \ + --level=0 \ + /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=replace} option), or if you set the clock @@ -6363,7 +6621,6 @@ that determination. @node Choosing @chapter Choosing Files and Names for @command{tar} -@UNREVISED Certain options to @command{tar} enable you to specify a name for your archive. Other options let you decide which files to include or exclude @@ -6388,12 +6645,12 @@ This chapter discusses these options in detail. @node file @section Choosing and Naming Archive Files -@UNREVISED @cindex Naming an archive @cindex Archive Name @cindex Choosing an archive file @cindex Where is the archive? +@opindex file 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} @@ -6596,6 +6853,7 @@ of files and archive members. @cindex Reading file names from a file @cindex Lists of file names @cindex File Name arguments, alternatives +@cindex @command{find}, using with @command{tar} 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 @option{--files-from=@var{file-of-names}} (@option{-T @@ -6732,10 +6990,14 @@ files whose names contain newlines can be archived using @option{--files-from}. @table @option -@opindex null +@xopindex{null, described} @item --null Only consider @code{NUL} terminated file names, instead of files that terminate in a newline. + +@xopindex{no-null, described} +@item --no-null +Undo the effect of any previous @option{--null} option. @end table The @option{--null} option is just like the one in @acronym{GNU} @@ -6759,15 +7021,46 @@ $ @kbd{find . -size +800 -print0 > long-files} $ @kbd{tar -c -v --null --files-from=long-files --file=big.tar} @end smallexample -@FIXME{say anything else here to conclude the section?} +The @option{--no-null} option can be used if you need to read both +zero-terminated and newline-terminated files on the same command line. +For example, if @file{flist} is a newline-terminated file, then the +following command can be used to combine it with the above command: + +@smallexample +@group +$ @kbd{find . -size +800 -print0 | + tar -c -f big.tar --null -T - --no-null -T flist} +@end group +@end smallexample + +This example uses short options for typographic reasons, to avoid +very long lines. + +@GNUTAR is able to automatically detect null-terminated file lists, so +it is safe to use them even without the @option{--null} option. In +this case @command{tar} will print a warning and continue reading such +a file as if @option{--null} were actually given: + +@smallexample +@group +$ @kbd{find . -size +800 -print0 | tar -c -f big.tar -T -} +tar: -: file name read contains nul character +@end group +@end smallexample + +The null terminator, however, remains in effect only for this +particular file, any following @option{-T} options will assume +newline termination. Of course, the null autodetection applies +to these eventual surplus @option{-T} options as well. @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 +@opindex exclude +@opindex exclude-from To avoid operating on files whose names match a particular pattern, use the @option{--exclude} or @option{--exclude-from} options. @@ -6809,6 +7102,7 @@ which is difficult to catch using text editors. However, empty lines are OK. +@table @option @cindex version control system, excluding files @cindex VCS, excluding files @cindex SCCS, excluding files @@ -6820,13 +7114,11 @@ However, empty lines are OK. @cindex Arch, excluding files @cindex Mercurial, excluding files @cindex Darcs, excluding files -@table @option @opindex exclude-vcs @item --exclude-vcs Exclude files and directories used by following version control systems: @samp{CVS}, @samp{RCS}, @samp{SCCS}, @samp{SVN}, @samp{Arch}, @samp{Bazaar}, @samp{Mercurial}, and @samp{Darcs}. -@end table As of version @value{VERSION}, the following files are excluded: @@ -6852,6 +7144,19 @@ As of version @value{VERSION}, the following files are excluded: @item @file{_darcs} @end itemize +@opindex exclude-backups +@item --exclude-backups +Exclude backup and lock files. This option causes exclusion of files +that match the following shell globbing patterns: + +@table @asis +@item .#* +@item *~ +@item #*# +@end table + +@end table + @findex exclude-caches When creating an archive, the @option{--exclude-caches} option family causes @command{tar} to exclude all directories that contain a @dfn{cache @@ -7497,7 +7802,7 @@ characters that are quoted by default in the selected quoting style. @command{Tar} archives contain detailed information about files stored in them and full file names are part of that information. When -storing file to an archive, its file name is recorded in the archive +storing file to an archive, its file name is recorded in it, along with the actual file contents. When restoring from an archive, a file is created on disk with exactly the same name as that stored in the archive. In the majority of cases this is the desired behavior @@ -7514,7 +7819,7 @@ directory components, or with otherwise modified names. In other cases it is desirable to store files under differing names in the archive. -@GNUTAR{} provides two options for these needs. +@GNUTAR{} provides several options for these needs. @table @option @opindex strip-components @@ -7536,8 +7841,8 @@ The option @option{--strip=2} instructs @command{tar} to strip the two leading components (@file{usr/} and @file{include/}) off the file name. -If you add to the above invocation @option{--verbose} (@option{-v}) -option, you will note that the verbose listing still contains the +If you add the @option{--verbose} (@option{-v}) option to the invocation +above, you will note that the verbose listing still contains the full file name, with the two removed components still in place. This can be inconvenient, so @command{tar} provides a special option for altering this behavior: @@ -7562,7 +7867,7 @@ stdlib.h @end group @end smallexample -Notice that in both cases the file is @file{stdlib.h} extracted to the +Notice that in both cases the file @file{stdlib.h} is extracted to the current working directory, @option{--show-transformed-names} affects only the way its name is displayed. @@ -7588,7 +7893,9 @@ In case you need to apply more complex modifications to the file name, @table @option @opindex transform +@opindex xform @item --transform=@var{expression} +@itemx --xform=@var{expression} Modify file names using supplied @var{expression}. @end table @@ -7606,6 +7913,21 @@ replacement for each file name part that matches @var{regexp}. Both @var{regexp} and @var{replace} are described in detail in @ref{The "s" Command, The "s" Command, The `s' Command, sed, GNU sed}. +Any delimiter can be used in lieue of @samp{/}, the only requirement being +that it be used consistently throughout the expression. For example, +the following two expressions are equivalent: + +@smallexample +@group +s/one/two/ +s,one,two, +@end group +@end smallexample + +Changing delimiters is often useful when the @var{regex} contains +slashes. For example, it is more convenient to write @code{s,/,-,} than +@code{s/\//-/}. + As in @command{sed}, you can give several replace expressions, separated by a semicolon. @@ -7627,7 +7949,7 @@ sed, GNU sed}). @item @var{number} Only replace the @var{number}th match of the @var{regexp}. -Note: the @var{posix} standard does not specify what should happen +Note: the @acronym{POSIX} standard does not specify what should happen when you mix the @samp{g} and @var{number} modifiers. @GNUTAR{} follows the GNU @command{sed} implementation in this regard, so the interaction is defined to be: ignore matches before the @@ -7636,21 +7958,41 @@ the interaction is defined to be: ignore matches before the @end table -Any delimiter can be used in lieue of @samp{/}, the only requirement being -that it be used consistently throughout the expression. For example, -the following two expressions are equivalent: +In addition, several @dfn{transformation scope} flags are supported, +that control to what files transformations apply. These are: + +@table @samp +@item r +Apply transformation to regular archive members. + +@item R +Do not apply transformation to regular archive members. + +@item s +Apply transformation to symbolic link targets. + +@item S +Do not apply transformation to symbolic link targets. + +@item h +Apply transformation to hard link targets. + +@item H +Do not apply transformation to hard link targets. +@end table + +Default is @samp{rsh}, which means to apply tranformations to both archive +members and targets of symbolic and hard links. + +Default scope flags can also be changed using @samp{flags=} statement +in the transform expression. The flags set this way remain in force +until next @samp{flags=} statement or end of expression, whichever +occurs first. For example: @smallexample -@group -s/one/two/ -s,one,two, -@end group + --transform 'flags=S;s|^|/usr/local/|' @end smallexample -Changing delimiters is often useful when the @var{regex} contains -slashes. For example, it is more convenient to write @code{s,/,-,} than -@code{s/\//-/}. - Here are several examples of @option{--transform} usage: @enumerate @@ -7667,20 +8009,59 @@ $ @kbd{tar --transform='s,usr/,usr/local/,' -x -f arch.tar} $ @kbd{tar --transform='s,/*[^/]*/[^/]*/,,' -x -f arch.tar} @end smallexample +@item Convert each file name to lower case: + +@smallexample +$ @kbd{tar --transform 's/.*/\L&/' -x -f arch.tar} +@end smallexample + @item Prepend @file{/prefix/} to each file name: @smallexample $ @kbd{tar --transform 's,^,/prefix/,' -x -f arch.tar} @end smallexample -@item Convert each file name to lower case: +@item Archive the @file{/lib} directory, prepending @samp{/usr/local} +to each archive member: @smallexample -$ @kbd{tar --transform 's/.*/\L&/' -x -f arch.tar} +$ @kbd{tar --transform 's,^,/usr/local/,S' -c -f arch.tar /lib} @end smallexample - @end enumerate +Notice the use of flags in the last example. The @file{/lib} +directory often contains many symbolic links to files within it. +It may look, for example, like this: + +@smallexample +$ @kbd{ls -l} +drwxr-xr-x root/root 0 2008-07-08 16:20 /lib/ +-rwxr-xr-x root/root 1250840 2008-05-25 07:44 /lib/libc-2.3.2.so +lrwxrwxrwx root/root 0 2008-06-24 17:12 /lib/libc.so.6 -> libc-2.3.2.so +... +@end smallexample + +Using the expression @samp{s,^,/usr/local/,} would mean adding +@samp{/usr/local} to both regular archive members and to link +targets. In this case, @file{/lib/libc.so.6} would become: + +@smallexample + /usr/local/lib/libc.so.6 -> /usr/local/libc-2.3.2.so +@end smallexample + +This is definitely not desired. To avoid this, the @samp{S} flag +are used, which excludes symbolic link targets from filename +transformations. The result is: + +@smallexample +$ @kbd{tar --transform 's,^,/usr/local/,S', -c -v -f arch.tar \ + --show-transformed /lib} +drwxr-xr-x root/root 0 2008-07-08 16:20 /usr/local/lib/ +-rwxr-xr-x root/root 1250840 2008-05-25 07:44 /usr/local/lib/libc-2.3.2.so +lrwxrwxrwx root/root 0 2008-06-24 17:12 /usr/local/lib/libc.so.6 -> +libc-2.3.2.so +@end smallexample + Unlike @option{--strip-components}, @option{--transform} can be used in any @GNUTAR{} operation mode. For example, the following command adds files to the archive while replacing the leading @file{usr/} @@ -7716,7 +8097,6 @@ $ @kbd{tar -cf arch.tar \ @node after @section Operating Only on New Files -@UNREVISED @cindex Excluding file by age @cindex Data Modification time, excluding files by @@ -7736,6 +8116,8 @@ If you only want @command{tar} to make the date comparison based on modification of the file's data (rather than status changes), then use the @option{--newer-mtime=@var{date}} option. +@cindex --after-date and --update compared +@cindex --newer-mtime and --update compared You may use these options with any operation. Note that these options differ from the @option{--update} (@option{-u}) operation in that they allow you to specify a particular date against which @command{tar} can @@ -7812,27 +8194,26 @@ for proper way of creating incremental backups. @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 -@FIXME{arrggh! this is still somewhat confusing to me. :-< } - Usually, @command{tar} will recursively explore all directories (either 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. @opindex no-recursion +@cindex @command{find}, using with @command{tar} 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 +use the @command{find} (@pxref{Top,, find, find, GNU Find Manual}) +utility for hunting through levels of directories to construct a list of file names which you could then pass to @command{tar}. @command{find} allows you to be more selective when choosing which files to archive; see @ref{files}, for more information on using @command{find} with -@command{tar}, or look. +@command{tar}. @table @option @item --no-recursion @@ -7893,7 +8274,6 @@ other than @file{grape/concord}. @node one @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 @@ -8034,7 +8414,12 @@ The interpretation of @option{--directory} is disabled by @node absolute @subsection Absolute File Names -@UNREVISED +@cindex absolute file names +@cindex file names, absolute + +By default, @GNUTAR{} drops a leading @samp{/} on +input or output, and complains about file names containing a @file{..} +component. There is an option that turns off this behavior: @table @option @opindex absolute-names @@ -8044,10 +8429,6 @@ Do not strip leading slashes from file names, and permit file names containing a @file{..} file name component. @end table -By default, @GNUTAR{} drops a leading @samp{/} on -input or output, and complains about file names containing a @file{..} -component. This option turns off this behavior. - When @command{tar} extracts archive members from an archive, it strips any leading slashes (@samp{/}) from the member name. This causes absolute member names in the archive to be treated as relative file names. This @@ -8095,8 +8476,6 @@ 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.} -@FIXME{Is write access an issue?} - @table @option @item --absolute-names Preserves full file names (including superior directory names) when @@ -8104,8 +8483,6 @@ archiving files. Preserves leading slash when extracting files. @end table -@FIXME{this is still horrible; need to talk with dan on monday.} - @command{tar} prints out a message about removing the @samp{/} from file names. This message appears once per @GNUTAR{} invocation. It represents something which ought to be told; ignoring @@ -8125,9 +8502,7 @@ the @file{/} directory first, and then avoid absolute notation. For example: @smallexample -$ @kbd{(cd / && tar -c -f archive.tar home)} -# @i{or}: -$ @kbd{tar -c -f archive.tar -C / home} +$ @kbd{tar -c -f archive.tar -C / home} @end smallexample @include getdate.texi @@ -8257,19 +8632,28 @@ switch to @samp{posix}. @cindex Compressed archives @cindex Storing archives in compressed format +@cindex gzip +@cindex bzip2 +@cindex lzip +@cindex lzma +@cindex lzop +@cindex compress @GNUTAR{} is able to create and read compressed archives. It supports -@command{gzip}, @command{bzip2} and @command{lzma} compression -programs. For backward compatibility, it also supports -@command{compress} command, although we strongly recommend against -using it, because it is by far less effective than other compression -programs@footnote{It also had patent problems in the past.}. +@command{gzip}, @command{bzip2}, @command{lzip}, @command{lzma} and +@command{lzop} compression programs. For backward compatibility, it +also supports @command{compress} command, although we strongly recommend +against using it, because it is by far less effective than other +compression programs@footnote{It also had patent problems in the past.}. Creating a compressed archive is simple: you just specify a @dfn{compression option} along with the usual archive creation commands. The compression option is @option{-z} (@option{--gzip}) to create a @command{gzip} compressed archive, @option{-j} (@option{--bzip2}) to create a @command{bzip2} compressed archive, -@option{--lzma} to create an @asis{LZMA} compressed archive and +@option{--lzip} to create an @asis{lzip} compressed archive, +@option{-J} (@option{--xz}) to create an @asis{XZ} archive, +@option{--lzma} to create an @asis{LZMA} compressed +archive, @option{--lzop} to create an @asis{LSOP} archive, and @option{-Z} (@option{--compress}) to use @command{compress} program. For example: @@ -8309,6 +8693,12 @@ $ @kbd{tar tf archive.tar.gz} $ @kbd{tar xf archive.tar.gz} @end smallexample +The format recognition algorithm is based on @dfn{signatures}, a +special byte sequences in the beginning of file, that are specific for +certain compression formats. If this approach fails, @command{tar} +falls back to using archive name suffix to determine its format +(@xref{auto-compress}, for a list of recognized suffixes). + The only case when you have to specify a decompression option while reading the archive is when reading from a pipe or from a tape drive that does not support random access. However, in this case @GNUTAR{} @@ -8344,7 +8734,7 @@ The following table summarizes compression options used by @GNUTAR{}. @item --auto-compress @itemx -a Select a compression program to use by the archive file name -suffix. The following suffixes are recognized: +suffix. The following suffixes are recognized: @multitable @columnfractions 0.3 0.6 @headitem Suffix @tab Compression program @@ -8357,8 +8747,11 @@ suffix. The following suffixes are recognized: @item @samp{.tz2} @tab @command{bzip2} @item @samp{.tbz2} @tab @command{bzip2} @item @samp{.tbz} @tab @command{bzip2} +@item @samp{.lz} @tab @command{lzip} @item @samp{.lzma} @tab @command{lzma} @item @samp{.tlz} @tab @command{lzma} +@item @samp{.lzo} @tab @command{lzop} +@item @samp{.xz} @tab @command{xz} @end multitable @opindex gzip @@ -8403,14 +8796,28 @@ lose some compressibility. But this would have make recovering easier. So, there are pros and cons. We'll see! @opindex bzip2 +@item -J +@itemx --xz +Filter the archive through @code{xz}. Otherwise like +@option{--gzip}. + @item -j @itemx --bzip2 Filter the archive through @code{bzip2}. Otherwise like @option{--gzip}. +@opindex lzip +@item --lzip +Filter the archive through @command{lzip}. Otherwise like @option{--gzip}. + @opindex lzma @item --lzma Filter the archive through @command{lzma}. Otherwise like @option{--gzip}. +@opindex lzop +@item --lzop +Filter the archive through @command{lzop}. Otherwise like +@option{--gzip}. + @opindex compress @opindex uncompress @item -Z @@ -8420,6 +8827,7 @@ Filter the archive through @command{compress}. Otherwise like @option{--gzip}. @opindex use-compress-program @item --use-compress-program=@var{prog} +@itemx -I=@var{prog} Use external compression program @var{prog}. Use this option if you have a compression program that @GNUTAR{} does not support. There are two requirements to which @var{prog} should comply: @@ -8458,14 +8866,14 @@ Suppose you name it @file{gpgz} and save it somewhere in your archive signed with your private key: @smallexample -$ @kbd{tar -cf foo.tar.gpgz --use-compress=gpgz .} +$ @kbd{tar -cf foo.tar.gpgz -Igpgz .} @end smallexample @noindent -Likewise, the following command will list its contents: +Likewise, the command below will list its contents: @smallexample -$ @kbd{tar -tf foo.tar.gpgz --use-compress=gpgz .} +$ @kbd{tar -tf foo.tar.gpgz -Igpgz .} @end smallexample @ignore @@ -8606,15 +9014,14 @@ Using @option{--sparse-format} option implies @option{--sparse}. @node Attributes @section Handling File Attributes -@UNREVISED +@cindex atrributes, files +@cindex file attributes 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 @@ -8737,11 +9144,7 @@ This option is meaningless with @option{--list} (@option{-t}). @item --preserve Same as both @option{--same-permissions} and @option{--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.) -Neither do I. --Sergey} +This option is deprecated, and will be removed in @GNUTAR{} version 1.23. @end table @@ -8827,7 +9230,6 @@ it contains unresolved symbolic links. @node hard links @subsection Hard Links -@UNREVISED{} @cindex File names, using hard links @cindex hard links, dereferencing @cindex dereferencing hard links @@ -9060,6 +9462,13 @@ will use the following default value: %d/PaxHeaders.%p/%f @end smallexample +@item exthdr.mtime=@var{value} + +This keyword defines the value of the @samp{mtime} field that +is written into the ustar header blocks for the extended headers. +By default, the @samp{mtime} field is set to the modification time +of the archive member described by that extended headers. + @item globexthdr.name=@var{string} This keyword allows user control over the name that is written into the ustar header blocks for global extended header records. The name @@ -9089,6 +9498,13 @@ where @samp{$TMPDIR} represents the value of the @var{TMPDIR} environment variable. If @var{TMPDIR} is not set, @command{tar} uses @samp{/tmp}. +@item exthdr.mtime=@var{value} + +This keyword defines the value of the @samp{mtime} field that +is written into the ustar header blocks for the global extended headers. +By default, the @samp{mtime} field is set to the time when +@command{tar} was invoked. + @item @var{keyword}=@var{value} When used with one of archive-creation commands, these keyword/value pairs will be included at the beginning of the archive in a global extended @@ -9118,6 +9534,32 @@ the group name will be forced to a new value for all files stored in the archive. @end table +In any of the forms described above, the @var{value} may be +a string enclosed in curly braces. In that case, the string +between the braces is understood either as a textual time +representation, as described in @ref{Date input formats}, or a name of +the existing file, starting with @samp{/} or @samp{.}. In the latter +case, the modification time of that file is used. + +For example, to set all modification times to the current date, you +use the following option: + +@smallexample +--pax-option='mtime:=@{now@}' +@end smallexample + +Note quoting of the option's argument. + +@cindex archives, binary equivalent +@cindex binary equivalent archives, creating +As another example, here is the option that ensures that any two +archives created using it, will be binary equivalent if they have the +same contents: + +@smallexample +--pax-option=exthdr.name=%d/PaxHeaders/%f,atime:=0 +@end smallexample + @node Checksumming @subsection Checksumming Problems @@ -9127,7 +9569,7 @@ is, file names having characters with the eight bit set, because they use signed checksums, while @GNUTAR{} uses unsigned checksums while creating archives, as per @acronym{POSIX} standards. On reading, @GNUTAR{} computes both checksums and -accept any. It is somewhat worrying that a lot of people may go +accepts any. It is somewhat worrying that a lot of people may go around doing backup of their files using faulty (or at least non-standard) software, not learning about it until it's time to restore their missing files with an incompatible file extractor, or @@ -9159,7 +9601,7 @@ a @command{tar} able to read the good archives they receive. @cindex large values @cindex future time stamps @cindex negative time stamps -@UNREVISED{} +@UNREVISED The above sections suggest to use @samp{oldest possible} archive format if in doubt. However, sometimes it is not possible. If you @@ -9920,7 +10362,8 @@ device busy @node Blocking @section Blocking -@UNREVISED +@cindex block +@cindex record @dfn{Block} and @dfn{record} terminology is rather confused, and it is also confusing to the expert reader. On the other hand, readers @@ -10514,8 +10957,6 @@ Prints status information about the tape unit. @end table -@FIXME{Is there a better way to frob the spacing on the list?} - If you don't specify a @var{tapename}, @command{mt} uses the environment variable @env{TAPE}; if @env{TAPE} is not set, @command{mt} will use the default device specified in your @file{sys/mtio.h} file @@ -10832,6 +11273,8 @@ implementation, read @ref{Split Recovery}. @node Tape Files @subsection Tape Files +@cindex labeling archives +@opindex label @UNREVISED To give the archive a name which will be recorded in it, use the @@ -11181,10 +11624,7 @@ 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. -@FIXME{Change the first argument to tar-formats when the new Automake is -out. The proposition to add @anchor{} to the appropriate place of its -docs was accepted by Automake people --Sergey 2006-05-25}. -@xref{Options, tar-v7, Changing Automake's Behavior, +@xref{Options, tar-formats, Changing Automake's Behavior, automake, GNU Automake}, for a description on how to use various archive formats with @command{automake}.