@c Maintenance notes:
@c 1. Pay attention to @FIXME{}s and @UNREVISED{}s
@c 2. Before creating final variant:
-@c 2.1. Run `make check-options' to make sure all options are properly
+@c 2.1. Run 'make check-options' to make sure all options are properly
@c documented;
-@c 2.2. Run `make master-menu' (see comment before the master menu).
+@c 2.2. Run 'make master-menu' (see comment before the master menu).
@include rendition.texi
@include value.texi
from archives.
Copyright @copyright{} 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001,
-2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Free Software Foundation, Inc.
+2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 Free Software
+Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
-Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'',
-and with the Back-Cover Texts as in (a) below. A copy of the license
-is included in the section entitled ``GNU Free Documentation
-License''.
-
-(a) The FSF's Back-Cover Text is: ``You have the freedom to
-copy and modify this GNU manual. Buying copies from the FSF
-supports it in developing GNU and promoting software freedom.''
+Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+A copy of the license is included in the section entitled ``GNU Free
+Documentation License''.
@end quotation
@end copying
@smallexample
@group
$ @kbd{tar --create --verbose --file archive /etc/mail}
-tar: Removing leading `/' from member names
+tar: Removing leading '/' from member names
/etc/mail/
/etc/mail/sendmail.cf
/etc/mail/aliases
@option{--extract}, @option{--compare}, and @option{--update})
will act on the entire contents of the archive.
+@anchor{exit status}
@cindex exit status
@cindex return status
Besides successful exits, @GNUTAR{} may fail for
@subsection Old Option Style
@cindex options, old style
@cindex old option style
+@cindex option syntax, traditional
-Like short options, @dfn{old options} are single letters. However, old options
+As far as we know, all @command{tar} programs, @acronym{GNU} and
+non-@acronym{GNU}, support @dfn{old options}: that is, if the first
+argument does not start with @samp{-}, it is assumed to specify option
+letters. @GNUTAR{} supports old options not only for historical
+reasons, but also because many people are used to them. If the first
+argument does not start with a dash, you are announcing the old option
+style instead of the short option style; old options are decoded
+differently.
+
+Like short options, old options are single letters. However, old options
must be written together as a single clumped set, without spaces separating
-them or dashes preceding them@footnote{Beware that if you precede options
-with a dash, you are announcing the short option style instead of the
-old option style; short options are decoded differently.}. This set
+them or dashes preceding them. This set
of letters must be the first to appear on the command line, after the
@command{tar} program name and some white space; old options cannot appear
anywhere else. The letter of an old option is exactly the same letter as
Here, @samp{20} is the argument of @option{-b} and @samp{/dev/rmt0} is
the argument of @option{-f}.
-On the other hand, this old style syntax makes it difficult to match
+The old style syntax can make it difficult to match
option letters with their corresponding arguments, and is often
confusing. In the command @w{@samp{tar cvbf 20 /dev/rmt0}}, for example,
@samp{20} is the argument for @option{-b}, @samp{/dev/rmt0} is the
second example, however, uses @file{z} as the value for option
@samp{f} --- probably not what was intended.
-Old options are kept for compatibility with old versions of @command{tar}.
-
This second example could be corrected in many ways, among which the
following are equivalent:
@kbd{tar cf archive.tar.gz -z file}
@end smallexample
-@cindex option syntax, traditional
-As far as we know, all @command{tar} programs, @acronym{GNU} and
-non-@acronym{GNU}, support old options. @GNUTAR{}
-supports them not only for historical reasons, but also because many
-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
-@option{--create} (@option{-c}) command to create an archive.
-
@node Mixing
@subsection Mixing Option Styles
@itemx -P
Normally when creating an archive, @command{tar} strips an initial
-@samp{/} from member names. This option disables that behavior.
-@xref{absolute}.
+@samp{/} from member names, and when extracting from an archive @command{tar}
+treats names specially if they have initial @samp{/} or internal
+@samp{..}. This option disables that behavior. @xref{absolute}.
@opsummary{after-date}
@item --after-date
@item --group=@var{group}
Files added to the @command{tar} archive will have a group @acronym{ID} of @var{group},
-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 @acronym{ID}. @xref{override}.
+rather than the group from the source file. @var{group} can specify a
+symbolic name, or a numeric @acronym{ID}, or both as
+@var{name}:@var{id}. @xref{override}.
Also see the comments for the @option{--owner=@var{user}} option.
@item --ignore-failed-read
Do not exit unsuccessfully merely because an unreadable file was encountered.
-@xref{Reading}.
+@xref{Ignore Failed Read}.
@opsummary{ignore-zeros}
@item --ignore-zeros
@item --keep-old-files
@itemx -k
-Do not overwrite existing files when extracting files from an archive.
+Do not overwrite existing files when extracting files from an
+archive. Return error if such files exist. See also
+@ref{--skip-old-files}.
+
@xref{Keep Old Files}.
@opsummary{label}
Specifies that @command{tar} should use @var{user} as the owner of members
when creating archives, instead of the user associated with the source
-file. @var{user} is first decoded as a user symbolic name, but if
-this interpretation fails, it has to be a decimal numeric user @acronym{ID}.
+file. @var{user} can specify a symbolic name, or a numeric
+@acronym{ID}, or both as @var{name}:@var{id}.
@xref{override}.
This option does not affect extraction from archives.
member names stored in the archive, as opposed to the actual file
names. @xref{listing member and file names}.
+@opsummary{skip-old-files}
+@item --skip-old-files
+
+Do not overwrite existing files when extracting files from an
+archive. @xref{Keep Old Files}.
+
+This option differs from @option{--keep-old-files} in that it does not
+treat such files as an error, instead it just silently avoids
+overwriting them.
+
+The @option{--warning=existing-file} option can be used together with
+this option to produce warning messages about existing old files
+(@pxref{warnings}).
+
@opsummary{sparse}
@item --sparse
@itemx -S
@smallexample
tar (GNU tar) @value{VERSION}
-Copyright (C) 2010 Free Software Foundation, Inc.
-Copyright (C) 2010 Free Software Foundation, Inc.
+Copyright (C) 2011 Free Software Foundation, Inc.
+Copyright (C) 2011 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
Verbose output appears on the standard output except when an archive is
being written to the standard output, as with @samp{tar --create
---file=- --verbose} (@samp{tar cfv -}, or even @samp{tar cv}---if the
+--file=- --verbose} (@samp{tar cvf -}, or even @samp{tar cv}---if the
installer let standard output be the default archive). In that case
@command{tar} writes verbose output to the standard error stream.
@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
+@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}
+@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
+@cindex @samp{Ignoring unknown extended header keyword '%s'}, warning message
@item unknown-keyword
-@samp{Ignoring unknown extended header keyword `%s'}
+@samp{Ignoring unknown extended header keyword '%s'}
@kwindex decompress-program
@item decompress-program
Controls verbose description of failures occurring when trying to run
@smallexample
@kbd{tar --create --file=empty-archive.tar --files-from=/dev/null}
-@kbd{tar cfT empty-archive.tar /dev/null}
+@kbd{tar -cf empty-archive.tar -T /dev/null}
@end smallexample
@xopindex{extract, complementary notes}
last. Additionally, an extracted member will @emph{replace} a file of
the same name which existed in the directory already, and @command{tar}
will not prompt you about this@footnote{Unless you give it
-@option{--keep-old-files} option, or the disk copy is newer than
-the one in the archive and you invoke @command{tar} with
-@option{--keep-newer-files} option.}. Thus, only the most recently archived
-member will end up being extracted, as it will replace the one
-extracted before it, and so on.
+@option{--keep-old-files} (or @option{--skip-old-files}) option, or
+the disk copy is newer than the one in the archive and you invoke
+@command{tar} with @option{--keep-newer-files} option.}. Thus, only
+the most recently archived 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}
@smallexample
$ @kbd{tar -c -f archive.tar -v --mtime=yesterday .}
-tar: Option --mtime: Treating date `yesterday' as 2006-06-20
+tar: Option --mtime: Treating date 'yesterday' as 2006-06-20
13:06:29.152478
@dots{}
@end smallexample
Specifies that @command{tar} should use @var{user} as the owner of members
when creating archives, instead of the user associated with the source
-file. The argument @var{user} can be either an existing user symbolic
-name, or a decimal numeric user @acronym{ID}.
+file.
+
+If @var{user} contains a colon, it is taken to be of the form
+@var{name}:@var{id} where a nonempty @var{name} specifies the user
+name and a nonempty @var{id} specifies the decimal numeric user
+@acronym{ID}. If @var{user} does not contain a colon, it is taken to
+be a user number if it is one or more decimal digits; otherwise it is
+taken to be a user name.
+
+If a name is given but no number, the number is inferred from the
+current host's user database if possible, and the file's user number
+is used otherwise. If a number is given but no name, the name is
+inferred from the number if possible, and an empty name is used
+otherwise. If both name and number are given, the user database is
+not consulted, and the name and number need not be valid on the
+current host.
There is no value indicating a missing number, and @samp{0} usually means
@code{root}. Some people like to force @samp{0} as the value to offer in
@opindex group
Files added to the @command{tar} archive will have a group @acronym{ID} of @var{group},
-rather than the group from the source file. The argument @var{group}
-can be either an existing group symbolic name, or a decimal numeric group @acronym{ID}.
+rather than the group from the source file. As with @option{--owner},
+the argument @var{group} can be an existing group symbolic name, or a
+decimal numeric group @acronym{ID}, or @var{name}:@var{id}.
@end table
@node Ignore Failed Read
@cindex Overwriting old files, prevention
@xopindex{keep-old-files, introduced}
To be even more cautious and prevent existing files from being replaced, use
-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.
+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. For
+example:
+
+@example
+$ @kbd{ls}
+blues
+$ @kbd{tar -x -k -f archive.tar}
+tar: blues: Cannot open: File exists
+tar: Exiting with failure status due to previous errors
+@end example
+
+@xopindex{skip-old-files, introduced}
+If you wish to preserve old files untouched, but don't want
+@command{tar} to treat them as errors, use the
+@option{--skip-old-files} option. This option causes @command{tar} to
+silently skip extracting over existing files.
@xopindex{overwrite, introduced}
To be more aggressive about altering existing files, use the
@node Keep Old Files
@unnumberedsubsubsec Keep Old Files
+@GNUTAR{} provides two options to control its actions in a situation
+when it is about to extract a file which already exists on disk.
+
@table @option
@opindex keep-old-files
@item --keep-old-files
@itemx -k
-Do not replace existing files from archive. The
-@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.
+Do not replace existing files from archive. When such a file is
+encountered, @command{tar} issues an error message. Upon end of
+extraction, @command{tar} exits with code 2 (@pxref{exit status}).
+
+@item --skip-old-files
+Do not replace existing files from archive, but do not treat that
+as error. Such files are silently skipped and do not affect
+@command{tar} exit status.
+
+Additional verbosity can be obtained using @option{--warning=existing-file}
+together with that option (@pxref{warnings}).
@end table
@node Keep Newer Files
@group
$ @kbd{tar cf a.tar}
tar: Cowardly refusing to create an empty archive
-Try `tar --help' or `tar --usage' for more information.
+Try 'tar --help' or 'tar --usage' for more information.
@end group
@end smallexample
Control characters, single quote and backslash are printed using
backslash notation. All names are quoted using left and right
quotation marks, appropriate to the current locale. If it does not
-define quotation marks, use @samp{`} as left and @samp{'} as right
+define quotation marks, use @samp{'} as left and as right
quotation marks. Any occurrences of the right quotation mark in a
name are escaped with @samp{\}, for example:
@smallexample
@group
$ @kbd{tar tf arch.tar --quoting-style=locale}
-`./'
-`./a space'
-`./a\'single\'quote'
-`./a"double"quote'
-`./a\\backslash'
-`./a\ttab'
-`./a\nnewline'
+'./'
+'./a space'
+'./a\'single\'quote'
+'./a"double"quote'
+'./a\\backslash'
+'./a\ttab'
+'./a\nnewline'
@end group
@end smallexample
@smallexample
@group
$ @kbd{tar -c -f archive.tar --after-date='10 days ago' .}
-tar: Option --after-date: Treating date `10 days ago' as 2006-06-11
+tar: Option --after-date: Treating date '10 days ago' as 2006-06-11
13:19:37.232434
@end group
@end smallexample
scripts for comparing both outputs. @xref{listing member and file names},
for the information on how to handle this case.}.
+Symbolic links containing @file{..} or leading @samp{/} can also cause
+problems when extracting, so @command{tar} normally extracts them last;
+it may create empty files as placeholders during extraction.
+
If you use the @option{--absolute-names} (@option{-P}) option,
@command{tar} will do none of these transformations.
@table @option
@item --absolute-names
Preserves full file names (including superior directory names) when
-archiving files. Preserves leading slash when extracting files.
+archiving and extracting files.
@end table
For example:
@smallexample
-$ @kbd{tar cfz archive.tar.gz .}
+$ @kbd{tar czf archive.tar.gz .}
@end smallexample
You can also let @GNUTAR{} select the compression program based on
compression:
@smallexample
-$ @kbd{tar cfa archive.tar.bz2 .}
+$ @kbd{tar caf archive.tar.bz2 .}
@end smallexample
@noindent
whereas the following one will use @command{lzma}:
@smallexample
-$ @kbd{tar cfa archive.tar.lzma .}
+$ @kbd{tar caf archive.tar.lzma .}
@end smallexample
For a complete list of file name suffixes recognized by @GNUTAR{},
invocation of @GNUTAR{}:
@smallexample
-$ @kbd{cat archive.tar.gz | tar tfz -}
+$ @kbd{cat archive.tar.gz | tar tzf -}
@end smallexample
Notice also, that there are several restrictions on operations on
such devices or remote files is reblocked by another copy of the
@command{tar} program to enforce the specified (or default) record
size. The default compression parameters are used. Most compression
-programs allow to override these by setting a program-specific
-environment variable. For example, when using @command{gzip} you can
-use @env{GZIP} as in the example below:
+programs let you override these by setting a program-specific
+environment variable. For example, with @command{gzip} you can set
+@env{GZIP}:
@smallexample
-$ @kbd{GZIP=--best tar cfz archive.tar.gz subdir}
+$ @kbd{GZIP='-9 -n' tar czf archive.tar.gz subdir}
@end smallexample
@noindent
-Another way would be to use the @option{-I} option instead (see
-below), e.g.:
+The traditional way to do this is to use a pipe:
@smallexample
-$ @kbd{tar -cf archive.tar.gz -I 'gzip --best' subdir}
-@end smallexample
-
-@noindent
-Finally, the third, traditional, way to achieve the same result is to
-use pipe:
-
-@smallexample
-$ @kbd{tar cf - subdir | gzip --best -c - > archive.tar.gz}
+$ @kbd{tar cf - subdir | gzip -9 -n > archive.tar.gz}
@end smallexample
@cindex corrupted archives
-About corrupted compressed archives: compressed files have no
-redundancy, for maximum compression. The adaptive nature of the
+Compressed archives are easily corrupted, because compressed files
+have little redundancy. The adaptive nature of the
compression scheme means that the compression tables are implicitly
spread all over the archive. If you lose a few blocks, the dynamic
construction of the compression tables becomes unsynchronized, and there
is little chance that you could recover later in the archive.
-Another compression options provide a better control over creating
+Other compression options provide better control over creating
compressed archives. These are:
@table @option
Use external compression program @var{prog}. Use this option if you
are not happy with the compression program associated with the suffix
at compile time or if you have a compression program that @GNUTAR{}
-does not support. There are two requirements to which @var{prog}
-should comply:
+does not support. The program should follow two conventions:
-First, when called without options, it should read data from standard
+First, when invoked without options, it should read data from standard
input, compress it and output it on standard output.
-Secondly, if called with @option{-d} argument, it should do exactly
+Secondly, if invoked with the @option{-d} option, it should do exactly
the opposite, i.e., read the compressed data from the standard input
and produce uncompressed data on the standard output.
@end table
the following:
@smallexample
-$ tar cfvv ../archive.tar .
+$ tar cvvf ../archive.tar .
drwxr-xr-x gray/staff 0 2007-10-30 15:13 ./
-rw-r--r-- gray/staff 4 2007-10-30 15:11 ./jeden
hrw-r--r-- gray/staff 0 2007-10-30 15:11 ./one link to ./jeden
@smallexample
$ tar -c -f ../archive.tar -l jeden
-tar: Missing links to `jeden'.
+tar: Missing links to 'jeden'.
@end smallexample
Although creating special records for hard links helps keep a faithful
@smallexample
$ tar xf archive.tar ./one
-tar: ./one: Cannot hard link to `./jeden': No such file or directory
+tar: ./one: Cannot hard link to './jeden': No such file or directory
tar: Error exit delayed from previous errors
@end smallexample
@group
$ @kbd{xsparse -n /home/gray/GNUSparseFile.6058/sparsefile}
Reading v.1.0 sparse map
-Expanding file `/home/gray/GNUSparseFile.6058/sparsefile' to
-`/home/gray/sparsefile'
+Expanding file '/home/gray/GNUSparseFile.6058/sparsefile' to
+'/home/gray/sparsefile'
Finished dry run
@end group
@end smallexample
@group
$ @kbd{xsparse -v /home/gray/GNUSparseFile.6058/sparsefile}
Reading v.1.0 sparse map
-Expanding file `/home/gray/GNUSparseFile.6058/sparsefile' to
-`/home/gray/sparsefile'
+Expanding file '/home/gray/GNUSparseFile.6058/sparsefile' to
+'/home/gray/sparsefile'
Done
@end group
@end smallexample
Found variable GNU.sparse.name = sparsefile
Found variable GNU.sparse.realsize = 217481216
Reading v.1.0 sparse map
-Expanding file `/home/gray/GNUSparseFile.6058/sparsefile' to
-`/home/gray/sparsefile'
+Expanding file '/home/gray/GNUSparseFile.6058/sparsefile' to
+'/home/gray/sparsefile'
Done
@end group
@end smallexample
Found variable GNU.sparse.numblocks = 208
Found variable GNU.sparse.name = sparsefile
Found variable GNU.sparse.map = 0,2048,1050624,2048,@dots{}
-Expanding file `GNUSparseFile.28124/sparsefile' to `sparsefile'
+Expanding file 'GNUSparseFile.28124/sparsefile' to 'sparsefile'
Done
@end group
@end smallexample
translation to the locale's language will be used.}:
@smallexample
-Prepare volume #@var{n} for `@var{archive}' and hit return:
+Prepare volume #@var{n} for '@var{archive}' and hit return:
@end smallexample
@noindent
@smallexample
$ @kbd{tar --create --multi-volume --file=/dev/tape0 --file=/dev/tape1 @var{files}}
-$ @kbd{tar cMff /dev/tape0 /dev/tape1 @var{files}}
+$ @kbd{tar -cM -f /dev/tape0 -f /dev/tape1 @var{files}}
@end smallexample
The second method is to use the @samp{n} response to the tape-change
@smallexample
@group
-#! /bin/sh
+#! /bin/bash
+# For this script it's advisable to use a shell, such as Bash,
+# that supports a TAR_FD value greater than 9.
+
echo Preparing volume $TAR_VOLUME of $TAR_ARCHIVE.
name=`expr $TAR_ARCHIVE : '\(.*\)-.*'`
@smallexample
@group
$ @kbd{tar -rf archive --label 'My volume' .}
-tar: Archive not labeled to match `My volume'
+tar: Archive not labeled to match 'My volume'
@end group
@end smallexample
@smallexample
@group
-$ @kbd{tar cfMV /dev/tape "Daily backup for `date +%Y-%m-%d`"}
+$ @kbd{tar -cM -f /dev/tape -V "Daily backup for `date +%Y-%m-%d`"}
$ @kbd{tar --create --file=/dev/tape --multi-volume \
--label="Daily backup for `date +%Y-%m-%d`"}
@end group
the @option{--absolute-names} (@option{-P}) option should be used only
for trusted archives.
-Conversely, with the @option{--keep-old-files} (@option{-k}) option,
-@command{tar} refuses to replace existing files when extracting; and
-with the @option{--no-overwrite-dir} option, @command{tar} refuses to
-replace the permissions or ownership of already-existing directories.
-These options may help when extracting from untrusted archives.
+Conversely, with the @option{--keep-old-files} (@option{-k}) and
+@option{--skip-old-files} options, @command{tar} refuses to replace
+existing files when extracting. The difference between the two
+options is that the former treats existing files as errors whereas the
+latter just silently ignores them.
+
+Finally, with the @option{--no-overwrite-dir} option, @command{tar}
+refuses to replace the permissions or ownership of already-existing
+directories. These options may help when extracting from untrusted
+archives.
@node Live untrusted data
@subsection Dealing with Live Untrusted Data
projects / chaz / tar / blobdiff