X-Git-Url: https://git.dogcows.com/gitweb?a=blobdiff_plain;f=doc%2Ftar.texi;h=4a49282c60e7f609eb3f475a302cacabab9c6e08;hb=cd7bdd4076ca154575bbef85eb2157e59befcfe2;hp=30fa61fcd35180f872ae9bcb5f654d008f2bf55a;hpb=b4bcb97e386a30996d3d4df8255116fc09c1f505;p=chaz%2Ftar

diff --git a/doc/tar.texi b/doc/tar.texi
index 30fa61f..4a49282 100644
--- a/doc/tar.texi
+++ b/doc/tar.texi
@@ -13,9 +13,9 @@
 @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
@@ -36,20 +36,20 @@ This manual is for @acronym{GNU} @command{tar} (version
 @value{VERSION}, @value{UPDATED}), which creates and extracts files
 from archives.
 
-Copyright @copyright{} 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001,
-2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Free Software Foundation, Inc.
+Copyright @copyright{} 1992, 1994--1997, 1999--2001, 2003--2013 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.1 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".
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with the
+Invariant Sections being ``GNU General Public License'', 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.''
+copy and modify this GNU manual.''
 @end quotation
 @end copying
 
@@ -106,6 +106,7 @@ document.  The rest of the menu lists all the lower level nodes.
 * Date input formats::
 * Formats::
 * Media::
+* Reliability and security::
 
 Appendices
 
@@ -115,7 +116,7 @@ Appendices
 * Tar Internals::
 * Genfile::
 * Free Software Needs Free Documentation::
-* Copying This Manual::
+* GNU Free Documentation License::
 * Index of Command Line Options::
 * Index::
 
@@ -316,7 +317,7 @@ Date input formats
 * Pure numbers in date strings::   19931219, 1440.
 * Seconds since the Epoch::        @@1078100502.
 * Specifying time zone rules::     TZ="America/New_York", TZ="UTC0".
-* Authors of get_date::            Bellovin, Eggert, Salz, Berets, et al.
+* Authors of parse_datetime::      Bellovin, Eggert, Salz, Berets, et al.
 
 Controlling the Archive Format
 
@@ -1020,13 +1021,12 @@ suffixes explained above:
 
 @smallexample
 @group
-V--------- 0/0          1536 2006-06-09 13:07 MyVolume--Volume Header--
--rw-r--r-- gray/staff 456783 2006-06-09 12:06 aspic--Continued at
-byte 32456--
--rw-r--r-- gray/staff  62373 2006-06-09 12:06 apple
-lrwxrwxrwx gray/staff      0 2006-06-09 13:01 angst -> apple
--rw-r--r-- gray/staff  35793 2006-06-09 12:06 blues
-hrw-r--r-- gray/staff      0 2006-06-09 12:06 music link to blues
+V--------- 0/0            1536 2006-06-09 13:07 MyVolume--Volume Header--
+-rw-r--r-- gray/staff   456783 2006-06-09 12:06 aspic--Continued at byte 32456--
+-rw-r--r-- gray/staff    62373 2006-06-09 12:06 apple
+lrwxrwxrwx gray/staff        0 2006-06-09 13:01 angst -> apple
+-rw-r--r-- gray/staff    35793 2006-06-09 12:06 blues
+hrw-r--r-- gray/staff        0 2006-06-09 12:06 music link to blues
 @end group
 @end smallexample
 
@@ -1419,7 +1419,7 @@ above would look like:
 
 @smallexample
 $ @kbd{tar --list --verbose --file=collection.tar folk}
--rw-r--r-- 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
@@ -1437,7 +1437,7 @@ example:
 @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
@@ -1511,11 +1511,11 @@ $ @kbd{tar --list --verbose --file=music.tar practice}
 @command{tar} responds:
 
 @smallexample
-drwxrwxrwx myself user 0 1990-05-31 21:49 practice/
--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
+drwxrwxrwx myself/user       0 1990-05-31 21:49 practice/
+-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
@@ -1565,9 +1565,9 @@ $ @kbd{tar -xvf collection.tar}
 produces this:
 
 @smallexample
--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          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
@@ -1681,8 +1681,8 @@ in the example below:
 
 @smallexample
 $ @kbd{tar -xvvf music.tar practice/folk practice/jazz}
--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
+-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
@@ -1880,6 +1880,7 @@ The other operations of @command{tar} (@option{--list},
 @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
@@ -2116,12 +2117,20 @@ end up overwriting files.
 @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
@@ -2145,7 +2154,7 @@ $ @kbd{tar cvbf 20 /dev/rmt0}
 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
@@ -2171,8 +2180,6 @@ the value for option @samp{f} and recognizes the option @samp{z}.  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:
 
@@ -2182,16 +2189,6 @@ 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
 
@@ -2365,8 +2362,9 @@ exist in the archive. @xref{update}.
 @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
@@ -2465,7 +2463,7 @@ This option tells @command{tar} to read or write archives through
 @item --check-device
 Check device numbers when creating a list of modified files for
 incremental archiving.  This is the default.  @xref{device numbers},
-for a detailed description. 
+for a detailed description.
 
 @opsummary{checkpoint}
 @item --checkpoint[=@var{number}]
@@ -2557,9 +2555,9 @@ directories until the end of extraction. @xref{Directory Modification Times and
 @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.  @xref{dereference}.
+When reading or writing a file to be archived, @command{tar} accesses
+the file that a symbolic link points to, rather than the symlink
+itself.  @xref{dereference}.
 
 @opsummary{directory}
 @item --directory=@var{dir}
@@ -2716,9 +2714,9 @@ tutorial}).
 @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.
 
@@ -2761,7 +2759,7 @@ Ignore exit codes of subprocesses. @xref{Writing to an External Program}.
 @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
@@ -2814,7 +2812,10 @@ when extracting files from an archive.
 @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}
@@ -2928,7 +2929,7 @@ suffix.  @xref{--auto-compress}.  @xref{gzip}.
 @item --no-check-device
 Do not check device numbers when creating a list of modified files
 for incremental archiving.  @xref{device numbers}, for
-a detailed description. 
+a detailed description.
 
 @opsummary{no-delay-directory-restore}
 @item --no-delay-directory-restore
@@ -3085,8 +3086,8 @@ from an archive.  @xref{Overwrite Old Files}.
 
 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.
@@ -3153,10 +3154,13 @@ Specifies that @command{tar} should reblock its input, for reading
 from pipes on systems with buggy implementations.  @xref{Reading}.
 
 @opsummary{record-size}
-@item --record-size=@var{size}
+@item --record-size=@var{size}[@var{suf}]
 
 Instructs @command{tar} to use @var{size} bytes per record when accessing the
-archive.  @xref{Blocking Factor}.
+archive.  The argument can be suffixed with a @dfn{size suffix}, e.g.
+@option{--record-size=10K} for 10 Kilobytes.  @xref{size-suffixes},
+for a list of valid suffixes.   @xref{Blocking Factor}, for a detailed
+description of this option.
 
 @opsummary{recursion}
 @item --recursion
@@ -3264,6 +3268,20 @@ the archive creation operations it instructs @command{tar} to list the
 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
@@ -3306,11 +3324,15 @@ Alters the suffix @command{tar} uses when backing up files from the default
 @samp{~}.  @xref{backup}.
 
 @opsummary{tape-length}
-@item --tape-length=@var{num}
-@itemx -L @var{num}
+@item --tape-length=@var{num}[@var{suf}]
+@itemx -L @var{num}[@var{suf}]
 
 Specifies the length of tapes that @command{tar} is writing as being
-@w{@var{num} x 1024} bytes long.  @xref{Using Multiple Tapes}.
+@w{@var{num} x 1024} bytes long.  If optional @var{suf} is given, it
+specifies a multiplicative factor to be used instead of 1024.  For
+example, @samp{-L2M} means 2 megabytes.  @xref{size-suffixes}, for a
+list of allowed suffixes.  @xref{Using Multiple Tapes}, for a detailed
+discussion of this option.
 
 @opsummary{test-label}
 @item --test-label
@@ -3568,8 +3590,7 @@ successfully.  For example, @w{@samp{tar --version}} might print:
 
 @smallexample
 tar (GNU tar) @value{VERSION}
-Copyright (C) 2010 Free Software Foundation, Inc.
-Copyright (C) 2010 Free Software Foundation, Inc.
+Copyright (C) 2013 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.
@@ -3724,7 +3745,7 @@ $ @kbd{tar xvvf archive.tar}
 
 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.
 
@@ -4146,17 +4167,34 @@ Disable all warning messages.
 @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
-@item unknown-keyword           
-@samp{Ignoring unknown extended header keyword `%s'}
+@cindex @samp{Ignoring unknown extended header keyword '%s'}, warning message
+@item unknown-keyword
+@samp{Ignoring unknown extended header keyword '%s'}
+@kwindex decompress-program
+@item decompress-program
+Controls verbose description of failures occurring when trying to run
+alternative decompressor programs (@pxref{alternative decompression
+programs}).  This warning is disabled by default (unless
+@option{--verbose} is used).  A common example of what you can get
+when using this warning is:
+
+@smallexample
+$ @kbd{tar --warning=decompress-program -x -f archive.Z}
+tar (child): cannot run compress: No such file or directory
+tar (child): trying gzip
+@end smallexample
+
+This means that @command{tar} first tried to decompress
+@file{archive.Z} using @command{compress}, and, when that
+failed, switched to @command{gzip}.
 @end table
 
 @subheading Keywords controlling incremental extraction:
@@ -4287,7 +4325,7 @@ the following commands:
 
 @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}
@@ -4411,18 +4449,18 @@ 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 @option{--extract} to extract the archive,
-only the most recently added copy of a member with the same name as 
+only the most recently added copy of a member with the same name as
 other members would end up in the working directory.  This is because
 @option{--extract} extracts an archive in the order the members appeared
 in the archive; the most recently archived members will be extracted
 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}
@@ -4508,10 +4546,10 @@ If you now use the @option{--list} (@option{-t}) operation, you will see that
 
 @smallexample
 $ @kbd{tar --list --file=collection.tar}
--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          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
 
 @node multiple
@@ -4555,11 +4593,11 @@ list the contents of the archive:
 
 @smallexample
 $ @kbd{tar --list --verbose --file=collection.tar}
--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
+-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
@@ -4575,7 +4613,7 @@ the following example:
 
 @smallexample
 $ @kbd{tar --extract -vv --occurrence --file=collection.tar blues}
--rw-r--r-- 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 @option{--extract} and
@@ -4702,11 +4740,11 @@ contain what they are supposed to:
 
 @smallexample
 $ @kbd{tar -tvf bluesrock.tar}
--rw-r--r-- melissa user    105 1997-01-21 19:42 blues
--rw-r--r-- 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 jazzfolk.tar}
--rw-r--r-- melissa user     20 1996-09-23 16:44 folk
--rw-r--r-- 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}:
@@ -4916,7 +4954,7 @@ For example:
 
 @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
@@ -4926,8 +4964,22 @@ tar: Option --mtime: Treating date `yesterday' as 2006-06-20
 
 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
@@ -4950,8 +5002,9 @@ $ @kbd{tar -c -f archive.tar --owner=root .}
 @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
@@ -5098,10 +5151,25 @@ such a directory, use the @option{--no-overwrite-dir} option.
 @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
@@ -5167,16 +5235,24 @@ archive, but remove other files before extracting.
 @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
@@ -5733,7 +5809,7 @@ or
 @group
 $ @kbd{tar --directory sourcedir --create --file=- . \
        | tar --directory targetdir --extract --file=-}
-@end group       
+@end group
 @end smallexample
 
 @noindent
@@ -5773,7 +5849,7 @@ 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 from @uref{http://www.amanda.org}. 
+This is free software, and it is available from @uref{http://www.amanda.org}.
 
 @FIXME{
 
@@ -6015,7 +6091,7 @@ Use device numbers when preparing a list of changed files
 for an incremental dump.  This is the default behavior.  The purpose
 of this option is to undo the effect of the @option{--no-check-device}
 if it was given in @env{TAR_OPTIONS} environment variable
-(@pxref{TAR_OPTIONS}). 
+(@pxref{TAR_OPTIONS}).
 @end table
 
 There is also another way to cope with changing device numbers.  It is
@@ -6871,7 +6947,7 @@ When @command{tar} is invoked with @option{--create} (@option{-c}),
 @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
 
@@ -7762,7 +7838,7 @@ $ @kbd{tar tf arch.tar --quoting-style=escape}
 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:
 
@@ -7771,13 +7847,13 @@ 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
 
@@ -8224,7 +8300,7 @@ ensure he is using the right date.  For example:
 @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
@@ -8499,6 +8575,10 @@ 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.}.
 
+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.
 
@@ -8522,7 +8602,7 @@ to transfer files between systems.}
 @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
 
@@ -8548,7 +8628,10 @@ For example:
 $ @kbd{tar -c -f archive.tar -C / home}
 @end smallexample
 
-@include getdate.texi
+@xref{Integrity}, for some of the security-related implications
+of using this option.
+
+@include parse-datetime.texi
 
 @node Formats
 @chapter Controlling the Archive Format
@@ -8685,7 +8768,7 @@ switch to @samp{posix}.
 a wide variety of compression programs, namely: @command{gzip},
 @command{bzip2}, @command{lzip}, @command{lzma}, @command{lzop},
 @command{xz} and traditional @command{compress}. The latter is
-supported mostly for backward compatibility, and we recommend 
+supported mostly for backward compatibility, and we recommend
 against using it, because it is by far less effective than the other
 compression programs@footnote{It also had patent problems in the past.}.
 
@@ -8695,14 +8778,14 @@ 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{--lzip} to create an @asis{lzip} compressed archive,
-@option{-J} (@option{--xz}) to create an @asis{XZ} 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:
 
 @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
@@ -8712,14 +8795,14 @@ example, the following invocation will use @command{bzip2} for
 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{},
@@ -8743,6 +8826,24 @@ certain compression formats.  If this approach fails, @command{tar}
 falls back to using archive name suffix to determine its format
 (@pxref{auto-compress}, for a list of recognized suffixes).
 
+@anchor{alternative decompression programs}
+@cindex alternative decompression programs
+Some compression programs are able to handle different compression
+formats.  @GNUTAR{} uses this, if the principal decompressor for the
+given format is not available.  For example, if @command{compress} is
+not installed, @command{tar} will try to use @command{gzip}.  As of
+version @value{VERSION} the following alternatives are
+tried@footnote{To verbosely trace the decompressor selection, use the
+@option{--warning=decompress-program} option
+(@pxref{warnings,decompress-program}).}:
+
+@multitable @columnfractions 0.3 0.3 0.3
+@headitem Format @tab Main decompressor @tab Alternatives
+@item compress @tab compress @tab gzip
+@item lzma     @tab lzma     @tab xz
+@item bzip2    @tab bzip2    @tab lbzip2
+@end multitable
+
 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{}
@@ -8758,7 +8859,7 @@ If you see such diagnostics, just add the suggested option to the
 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
@@ -8822,41 +8923,32 @@ compressor names along with each of these options.
 You can use any of these options on physical devices (tape drives,
 etc.) and remote files as well as on normal files; data to or from
 such devices or remote files is reblocked by another copy of the
-@command{tar} program to enforce the specified (or default) record 
+@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
@@ -8891,13 +8983,12 @@ suffix.  The following suffixes are recognized:
 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
@@ -9012,7 +9103,7 @@ $ @kbd{tar --help | grep -- --bzip2}
   -j, --bzip2                filter the archive through lbzip2
 @end group
 @end smallexample
-  
+
 @noindent
 which means that running @command{tar --bzip2} will invoke @command{lbzip2}.
 
@@ -9307,28 +9398,26 @@ than System V's.
 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 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,
-instead of simply recording the presence of a symbolic link.
-
-The name under which the file is stored in the file system is not
-recorded in the archive.  To record both the symbolic link name and
-the file name in the system, archive the file under both names.  If
-all links were recorded automatically by @command{tar}, an extracted file
-might be linked to a file name that no longer exists in the file
-system.
+When @option{--dereference} (@option{-h}) is used with
+@option{--create} (@option{-c}), @command{tar} archives the files
+symbolic links point to, instead of
+the links themselves.
 
-If a linked-to file is encountered again by @command{tar} while creating
-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 @option{--dereference} (@option{-h}): many systems do not support
+When creating portable archives, use @option{--dereference}
+(@option{-h}): some systems do not support
 symbolic links, and moreover, your distribution might be unusable if
 it contains unresolved symbolic links.
 
+When reading from an archive, the @option{--dereference} (@option{-h})
+option causes @command{tar} to follow an already-existing symbolic
+link when @command{tar} writes or reads a file named in the archive.
+Ordinarily, @command{tar} does not follow such a link, though it may
+remove the link before writing a new file.  @xref{Dealing with Old
+Files}.
+
+The @option{--dereference} option is unsafe if an untrusted user can
+modify directories while @command{tar} is running.  @xref{Security}.
+
 @node hard links
 @subsection Hard Links
 @cindex File names, using hard links
@@ -9342,9 +9431,9 @@ once.  For example, consider the following two files:
 
 @smallexample
 @group
-$ ls
--rw-r--r--   2 gray staff       4 2007-10-30 15:11 one
--rw-r--r--   2 gray staff       4 2007-10-30 15:11 jeden
+$ ls -l
+-rw-r--r-- 2 gray staff 4 2007-10-30 15:11 one
+-rw-r--r-- 2 gray staff 4 2007-10-30 15:11 jeden
 @end group
 @end smallexample
 
@@ -9353,7 +9442,7 @@ directory with a verbose level 2, you will get an output similar to
 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
@@ -9381,7 +9470,7 @@ produces the following diagnostics:
 
 @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
@@ -9393,7 +9482,7 @@ archive created in previous examples produces, in the absense of file
 
 @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
 
@@ -9933,8 +10022,8 @@ run mode is enabled by @option{-n} command line argument:
 @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
@@ -9955,8 +10044,8 @@ similar to that from the dry run mode, use @option{-v} option:
 @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
@@ -9977,8 +10066,8 @@ Found variable GNU.sparse.minor = 0
 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
@@ -10080,7 +10169,7 @@ Found variable GNU.sparse.size = 217481216
 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
@@ -10345,8 +10434,27 @@ that may be larger than will fit on the medium used to hold it.
 
 @xopindex{tape-length, short description}
 @item -L @var{num}
-@itemx --tape-length=@var{num}
-Change tape after writing @var{num} x 1024 bytes.
+@itemx --tape-length=@var{size}[@var{suf}]
+Change tape after writing @var{size} units of data.  Unless @var{suf} is
+given, @var{size} is treated as kilobytes, i.e. @samp{@var{size} x
+1024} bytes.  The following suffixes alter this behavior:
+
+@float Table, size-suffixes
+@caption{Size Suffixes}
+@multitable @columnfractions 0.2 0.3 0.3
+@headitem Suffix @tab Units            @tab Byte Equivalent
+@item b          @tab Blocks           @tab @var{size} x 512
+@item B          @tab Kilobytes        @tab @var{size} x 1024
+@item c          @tab Bytes            @tab @var{size}
+@item G          @tab Gigabytes        @tab @var{size} x 1024^3
+@item K          @tab Kilobytes        @tab @var{size} x 1024
+@item k          @tab Kilobytes        @tab @var{size} x 1024
+@item M          @tab Megabytes        @tab @var{size} x 1024^2
+@item P          @tab Petabytes        @tab @var{size} x 1024^5
+@item T          @tab Terabytes        @tab @var{size} x 1024^4
+@item w          @tab Words            @tab @var{size} x 2
+@end multitable
+@end float
 
 This option might be useful when your tape drivers do not properly
 detect end of physical tapes.  By being slightly conservative on the
@@ -10375,9 +10483,8 @@ want to use.  @command{tar} calls @command{rmt} by running an
 @command{rsh} or @command{remsh} to the remote machine, optionally
 using a different login name if one is supplied.
 
-A copy of the source for the remote tape server is provided.  It is
-Copyright @copyright{} 1983 by the Regents of the University of
-California, but can be freely distributed.  It is compiled and
+A copy of the source for the remote tape server is provided.  Its
+source code can be freely distributed.  It is compiled and
 installed by default.
 
 @cindex absolute file names
@@ -11154,15 +11261,26 @@ tape:
 @anchor{tape-length}
 @table @option
 @opindex tape-length
-@item --tape-length=@var{size}
-@itemx -L @var{size}
-Set maximum length of a volume.  The @var{size} argument should then
-be the usable size of the tape in units of 1024 bytes.  This option
-selects @option{--multi-volume} automatically.  For example:
+@item --tape-length=@var{size}[@var{suf}]
+@itemx -L @var{size}[@var{suf}]
+Set maximum length of a volume.  The @var{suf}, if given, specifies
+units in which @var{size} is expressed, e.g. @samp{2M} mean 2
+megabytes (@pxref{size-suffixes}, for a list of allowed size
+suffixes).  Without @var{suf}, units of 1024 bytes (kilobyte) are
+assumed.
+
+This option selects @option{--multi-volume} automatically.  For example:
 
 @smallexample
 $ @kbd{tar --create --tape-length=41943040 --file=/dev/tape @var{files}}
 @end smallexample
+
+@noindent
+or, which is equivalent:
+
+@smallexample
+$ @kbd{tar --create --tape-length=4G --file=/dev/tape @var{files}}
+@end smallexample
 @end table
 
 @anchor{change volume prompt}
@@ -11172,7 +11290,7 @@ is@footnote{If you run @GNUTAR{} under a different locale, the
 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
@@ -11293,7 +11411,7 @@ second tape, and then back to the first tape, etc., just do either of:
 
 @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
@@ -11308,7 +11426,10 @@ archive being created (as given by @option{--file} option) and
 
 @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 : '\(.*\)-.*'`
@@ -11476,8 +11597,8 @@ explicitly marked as in the example below:
 @smallexample
 @group
 $ @kbd{tar --verbose --list --file=iamanarchive}
-V--------- 0 0        0 1992-03-07 12:01 iamalabel--Volume Header--
--rw-r--r-- ringo user 40 1990-05-21 13:30 iamafilename
+V--------- 0/0               0 1992-03-07 12:01 iamalabel--Volume Header--
+-rw-r--r-- ringo/user       40 1990-05-21 13:30 iamafilename
 @end group
 @end smallexample
 
@@ -11541,7 +11662,7 @@ you will get:
 @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
 
@@ -11572,7 +11693,7 @@ manage to get some date string as part of the label.  For example:
 
 @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
@@ -11683,6 +11804,280 @@ 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 Reliability and security
+@chapter Reliability and Security
+
+The @command{tar} command reads and writes files as any other
+application does, and is subject to the usual caveats about
+reliability and security.  This section contains some commonsense
+advice on the topic.
+
+@menu
+* Reliability::
+* Security::
+@end menu
+
+@node Reliability
+@section Reliability
+
+Ideally, when @command{tar} is creating an archive, it reads from a
+file system that is not being modified, and encounters no errors or
+inconsistencies while reading and writing.  If this is the case, the
+archive should faithfully reflect what was read.  Similarly, when
+extracting from an archive, ideally @command{tar} ideally encounters
+no errors and the extracted files faithfully reflect what was in the
+archive.
+
+However, when reading or writing real-world file systems, several
+things can go wrong; these include permissions problems, corruption of
+data, and race conditions.
+
+@menu
+* Permissions problems::
+* Data corruption and repair::
+* Race conditions::
+@end menu
+
+@node Permissions problems
+@subsection Permissions Problems
+
+If @command{tar} encounters errors while reading or writing files, it
+normally reports an error and exits with nonzero status.  The work it
+does may therefore be incomplete.  For example, when creating an
+archive, if @command{tar} cannot read a file then it cannot copy the
+file into the archive.
+
+@node Data corruption and repair
+@subsection Data Corruption and Repair
+
+If an archive becomes corrupted by an I/O error, this may corrupt the
+data in an extracted file.  Worse, it may corrupt the file's metadata,
+which may cause later parts of the archive to become misinterpreted.
+An tar-format archive contains a checksum that most likely will detect
+errors in the metadata, but it will not detect errors in the data.
+
+If data corruption is a concern, you can compute and check your own
+checksums of an archive by using other programs, such as
+@command{cksum}.
+
+When attempting to recover from a read error or data corruption in an
+archive, you may need to skip past the questionable data and read the
+rest of the archive.  This requires some expertise in the archive
+format and in other software tools.
+
+@node Race conditions
+@subsection Race conditions
+
+If some other process is modifying the file system while @command{tar}
+is reading or writing files, the result may well be inconsistent due
+to race conditions.  For example, if another process creates some
+files in a directory while @command{tar} is creating an archive
+containing the directory's files, @command{tar} may see some of the
+files but not others, or it may see a file that is in the process of
+being created.  The resulting archive may not be a snapshot of the
+file system at any point in time.  If an application such as a
+database system depends on an accurate snapshot, restoring from the
+@command{tar} archive of a live file system may therefore break that
+consistency and may break the application.  The simplest way to avoid
+the consistency issues is to avoid making other changes to the file
+system while tar is reading it or writing it.
+
+When creating an archive, several options are available to avoid race
+conditions.  Some hosts have a way of snapshotting a file system, or
+of temporarily suspending all changes to a file system, by (say)
+suspending the only virtual machine that can modify a file system; if
+you use these facilities and have @command{tar -c} read from a
+snapshot when creating an archive, you can avoid inconsistency
+problems.  More drastically, before starting @command{tar} you could
+suspend or shut down all processes other than @command{tar} that have
+access to the file system, or you could unmount the file system and
+then mount it read-only.
+
+When extracting from an archive, one approach to avoid race conditions
+is to create a directory that no other process can write to, and
+extract into that.
+
+@node Security
+@section Security
+
+In some cases @command{tar} may be used in an adversarial situation,
+where an untrusted user is attempting to gain information about or
+modify otherwise-inaccessible files.  Dealing with untrusted data
+(that is, data generated by an untrusted user) typically requires
+extra care, because even the smallest mistake in the use of
+@command{tar} is more likely to be exploited by an adversary than by a
+race condition.
+
+@menu
+* Privacy::
+* Integrity::
+* Live untrusted data::
+* Security rules of thumb::
+@end menu
+
+@node Privacy
+@subsection Privacy
+
+Standard privacy concerns apply when using @command{tar}.  For
+example, suppose you are archiving your home directory into a file
+@file{/archive/myhome.tar}.  Any secret information in your home
+directory, such as your SSH secret keys, are copied faithfully into
+the archive.  Therefore, if your home directory contains any file that
+should not be read by some other user, the archive itself should be
+not be readable by that user.  And even if the archive's data are
+inaccessible to untrusted users, its metadata (such as size or
+last-modified date) may reveal some information about your home
+directory; if the metadata are intended to be private, the archive's
+parent directory should also be inaccessible to untrusted users.
+
+One precaution is to create @file{/archive} so that it is not
+accessible to any user, unless that user also has permission to access
+all the files in your home directory.
+
+Similarly, when extracting from an archive, take care that the
+permissions of the extracted files are not more generous than what you
+want.  Even if the archive itself is readable only to you, files
+extracted from it have their own permissions that may differ.
+
+@node Integrity
+@subsection Integrity
+
+When creating archives, take care that they are not writable by a
+untrusted user; otherwise, that user could modify the archive, and
+when you later extract from the archive you will get incorrect data.
+
+When @command{tar} extracts from an archive, by default it writes into
+files relative to the working directory.  If the archive was generated
+by an untrusted user, that user therefore can write into any file
+under the working directory.  If the working directory contains a
+symbolic link to another directory, the untrusted user can also write
+into any file under the referenced directory.  When extracting from an
+untrusted archive, it is therefore good practice to create an empty
+directory and run @command{tar} in that directory.
+
+When extracting from two or more untrusted archives, each one should
+be extracted independently, into different empty directories.
+Otherwise, the first archive could create a symbolic link into an area
+outside the working directory, and the second one could follow the
+link and overwrite data that is not under the working directory.  For
+example, when restoring from a series of incremental dumps, the
+archives should have been created by a trusted process, as otherwise
+the incremental restores might alter data outside the working
+directory.
+
+If you use the @option{--absolute-names} (@option{-P}) option when
+extracting, @command{tar} respects any file names in the archive, even
+file names that begin with @file{/} or contain @file{..}.  As this
+lets the archive overwrite any file in your system that you can write,
+the @option{--absolute-names} (@option{-P}) option should be used only
+for trusted 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
+
+Extra care is required when creating from or extracting into a file
+system that is accessible to untrusted users.  For example, superusers
+who invoke @command{tar} must be wary about its actions being hijacked
+by an adversary who is reading or writing the file system at the same
+time that @command{tar} is operating.
+
+When creating an archive from a live file system, @command{tar} is
+vulnerable to denial-of-service attacks.  For example, an adversarial
+user could create the illusion of an indefinitely-deep directory
+hierarchy @file{d/e/f/g/...} by creating directories one step ahead of
+@command{tar}, or the illusion of an indefinitely-long file by
+creating a sparse file but arranging for blocks to be allocated just
+before @command{tar} reads them.  There is no easy way for
+@command{tar} to distinguish these scenarios from legitimate uses, so
+you may need to monitor @command{tar}, just as you'd need to monitor
+any other system service, to detect such attacks.
+
+While a superuser is extracting from an archive into a live file
+system, an untrusted user might replace a directory with a symbolic
+link, in hopes that @command{tar} will follow the symbolic link and
+extract data into files that the untrusted user does not have access
+to.  Even if the archive was generated by the superuser, it may
+contain a file such as @file{d/etc/passwd} that the untrusted user
+earlier created in order to break in; if the untrusted user replaces
+the directory @file{d/etc} with a symbolic link to @file{/etc} while
+@command{tar} is running, @command{tar} will overwrite
+@file{/etc/passwd}.  This attack can be prevented by extracting into a
+directory that is inaccessible to untrusted users.
+
+Similar attacks via symbolic links are also possible when creating an
+archive, if the untrusted user can modify an ancestor of a top-level
+argument of @command{tar}.  For example, an untrusted user that can
+modify @file{/home/eve} can hijack a running instance of @samp{tar -cf
+- /home/eve/Documents/yesterday} by replacing
+@file{/home/eve/Documents} with a symbolic link to some other
+location.  Attacks like these can be prevented by making sure that
+untrusted users cannot modify any files that are top-level arguments
+to @command{tar}, or any ancestor directories of these files.
+
+@node Security rules of thumb
+@subsection Security Rules of Thumb
+
+This section briefly summarizes rules of thumb for avoiding security
+pitfalls.
+
+@itemize @bullet
+
+@item
+Protect archives at least as much as you protect any of the files
+being archived.
+
+@item
+Extract from an untrusted archive only into an otherwise-empty
+directory.  This directory and its parent should be accessible only to
+trusted users.  For example:
+
+@example
+@group
+$ @kbd{chmod go-rwx .}
+$ @kbd{mkdir -m go-rwx dir}
+$ @kbd{cd dir}
+$ @kbd{tar -xvf /archives/got-it-off-the-net.tar.gz}
+@end group
+@end example
+
+As a corollary, do not do an incremental restore from an untrusted archive.
+
+@item
+Do not let untrusted users access files extracted from untrusted
+archives without checking first for problems such as setuid programs.
+
+@item
+Do not let untrusted users modify directories that are ancestors of
+top-level arguments of @command{tar}.  For example, while you are
+executing @samp{tar -cf /archive/u-home.tar /u/home}, do not let an
+untrusted user modify @file{/}, @file{/archive}, or @file{/u}.
+
+@item
+Pay attention to the diagnostics and exit status of @command{tar}.
+
+@item
+When archiving live file systems, monitor running instances of
+@command{tar} to detect denial-of-service attacks.
+
+@item
+Avoid unusual options such as @option{--absolute-names} (@option{-P}),
+@option{--dereference} (@option{-h}), @option{--overwrite},
+@option{--recursive-unlink}, and @option{--remove-files} unless you
+understand their security implications.
+
+@end itemize
+
 @node Changes
 @appendix Changes
 
@@ -12003,12 +12398,8 @@ Right margin of the text output. Used for wrapping.
 @appendix Free Software Needs Free Documentation
 @include freemanuals.texi
 
-@node Copying This Manual
-@appendix Copying This Manual
-
-@menu
-* GNU Free Documentation License::  License for copying this manual
-@end menu
+@node GNU Free Documentation License
+@appendix GNU Free Documentation License
 
 @include fdl.texi