tar: don't assume O_NONBLOCK is benign on regular files

[chaz/tar] / doc / tar.texi

diff --git a/doc/tar.texi b/doc/tar.texi
index edeabf50940629e25a87cce60b7f52741076483b..1a28cb26c62612b0626d381c2ae9a54a22050128 100644 (file)
--- a/doc/tar.texi
+++ b/doc/tar.texi
@@ -37,20 +37,16 @@ This manual is for @acronym{GNU} @command{tar} (version
 from archives.
 
 Copyright @copyright{} 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001,
 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
 
 @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
 
 @end quotation
 @end copying
 


@@ -1022,13 +1018,12 @@ suffixes explained above:
 
 @smallexample
 @group
 
 @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
 
 @end group
 @end smallexample
 


@@ -1421,7 +1416,7 @@ above would look like:
 
 @smallexample
 $ @kbd{tar --list --verbose --file=collection.tar folk}
 
 @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
 @end smallexample
 
 @cindex listing member and file names


@@ -1513,11 +1508,11 @@ $ @kbd{tar --list --verbose --file=music.tar practice}
 @command{tar} responds:
 
 @smallexample
 @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
 @end smallexample
 
 When you use a directory name as a file name argument, @command{tar} acts on


@@ -1567,9 +1562,9 @@ $ @kbd{tar -xvf collection.tar}
 produces this:
 
 @smallexample
 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
 @end smallexample
 
 @node extracting files


@@ -1683,8 +1678,8 @@ in the example below:
 
 @smallexample
 $ @kbd{tar -xvvf music.tar practice/folk practice/jazz}
 
 @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
 @end smallexample
 
 @noindent


@@ -1882,6 +1877,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.
 
 @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
 @cindex exit status
 @cindex return status
 Besides successful exits, @GNUTAR{} may fail for


@@ -2118,12 +2114,20 @@ end up overwriting files.
 @subsection Old Option Style
 @cindex options, old style
 @cindex old option style
 @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
 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
 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


@@ -2147,7 +2151,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}.
 
 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
 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


@@ -2173,8 +2177,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.
 
 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:
 
 This second example could be corrected in many ways, among which the
 following are equivalent:
 


@@ -2184,16 +2186,6 @@ following are equivalent:
 @kbd{tar cf archive.tar.gz -z file}
 @end smallexample
 
 @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
 
 @node Mixing
 @subsection Mixing Option Styles
 


@@ -2367,8 +2359,9 @@ exist in the archive. @xref{update}.
 @itemx -P
 
 Normally when creating an archive, @command{tar} strips an initial
 @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
 
 @opsummary{after-date}
 @item --after-date


@@ -2718,9 +2711,9 @@ tutorial}).
 @item --group=@var{group}
 
 Files added to the @command{tar} archive will have a group @acronym{ID} of @var{group},
 @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.
 
 
 Also see the comments for the @option{--owner=@var{user}} option.
 


@@ -2816,7 +2809,10 @@ when extracting files from an archive.
 @item --keep-old-files
 @itemx -k
 
 @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}
 @xref{Keep Old Files}.
 
 @opsummary{label}


@@ -3087,8 +3083,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
 
 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.
 @xref{override}.
 
 This option does not affect extraction from archives.


@@ -3269,6 +3265,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}.
 
 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
 @opsummary{sparse}
 @item --sparse
 @itemx -S


@@ -3577,8 +3587,8 @@ successfully.  For example, @w{@samp{tar --version}} might print:
 
 @smallexample
 tar (GNU tar) @value{VERSION}
 
 @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.
 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.


@@ -3733,7 +3743,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
 
 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.
 
 installer let standard output be the default archive).  In that case
 @command{tar} writes verbose output to the standard error stream.
 


@@ -4313,7 +4323,7 @@ the following commands:
 
 @smallexample
 @kbd{tar --create --file=empty-archive.tar --files-from=/dev/null}
 
 @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}
 @end smallexample
 
 @xopindex{extract, complementary notes}


@@ -4444,11 +4454,11 @@ 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
 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}
 
 @cindex extracting @var{n}th copy of the file
 @xopindex{occurrence, described}


@@ -4534,10 +4544,10 @@ If you now use the @option{--list} (@option{-t}) operation, you will see that
 
 @smallexample
 $ @kbd{tar --list --file=collection.tar}
 
 @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
 @end smallexample
 
 @node multiple


@@ -4581,11 +4591,11 @@ list the contents of the archive:
 
 @smallexample
 $ @kbd{tar --list --verbose --file=collection.tar}
 
 @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
 @end smallexample
 
 @noindent


@@ -4601,7 +4611,7 @@ the following example:
 
 @smallexample
 $ @kbd{tar --extract -vv --occurrence --file=collection.tar blues}
 
 @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
 @end smallexample
 
 @xref{Writing}, for more information on @option{--extract} and


@@ -4728,11 +4738,11 @@ contain what they are supposed to:
 
 @smallexample
 $ @kbd{tar -tvf bluesrock.tar}
 
 @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}
 $ @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}:
 @end smallexample
 
 We can concatenate these two archives with @command{tar}:


@@ -4952,8 +4962,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
 
 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
 
 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


@@ -4976,8 +5000,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},
 @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
 @end table
 
 @node Ignore Failed Read


@@ -5124,10 +5149,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
 @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
 
 @xopindex{overwrite, introduced}
 To be more aggressive about altering existing files, use the


@@ -5193,16 +5233,24 @@ archive, but remove other files before extracting.
 @node Keep Old Files
 @unnumberedsubsubsec Keep Old Files
 
 @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
 @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
 @end table
 
 @node Keep Newer Files


@@ -8525,6 +8573,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.}.
 
 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.
 
 If you use the @option{--absolute-names} (@option{-P}) option,
 @command{tar} will do none of these transformations.
 


@@ -8548,7 +8600,7 @@ to transfer files between systems.}
 @table @option
 @item --absolute-names
 Preserves full file names (including superior directory names) when
 @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
 
 
 @end table
 


@@ -8731,7 +8783,7 @@ archive, @option{--lzop} to create an @asis{LSOP} archive, and
 For example:
 
 @smallexample
 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
 @end smallexample
 
 You can also let @GNUTAR{} select the compression program based on


@@ -8741,14 +8793,14 @@ example, the following invocation will use @command{bzip2} for
 compression:
 
 @smallexample
 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
 @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{},
 @end smallexample
 
 For a complete list of file name suffixes recognized by @GNUTAR{},


@@ -8783,7 +8835,7 @@ tried@footnote{To verbosely trace the decompressor selection, use the
 @option{--warning=decompress-program} option
 (@pxref{warnings,decompress-program}).}:
 
 @option{--warning=decompress-program} option
 (@pxref{warnings,decompress-program}).}:
 

-@multitable @columnfractions 0.3 0.3 0.3 
+@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
 @headitem Format @tab Main decompressor @tab Alternatives
 @item compress @tab compress @tab gzip
 @item lzma     @tab lzma     @tab xz


@@ -8805,7 +8857,7 @@ If you see such diagnostics, just add the suggested option to the
 invocation of @GNUTAR{}:
 
 @smallexample
 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
 @end smallexample
 
 Notice also, that there are several restrictions on operations on


@@ -8876,7 +8928,7 @@ environment variable.  For example, when using @command{gzip} you can
 use @env{GZIP} as in the example below:
 
 @smallexample
 use @env{GZIP} as in the example below:
 
 @smallexample

-$ @kbd{GZIP=--best tar cfz archive.tar.gz subdir}
+$ @kbd{GZIP=--best tar czf archive.tar.gz subdir}

 @end smallexample
 
 @noindent
 @end smallexample
 
 @noindent


@@ -9387,9 +9439,9 @@ once.  For example, consider the following two files:
 
 @smallexample
 @group
 
 @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
 
 @end group
 @end smallexample
 


@@ -9398,7 +9450,7 @@ directory with a verbose level 2, you will get an output similar to
 the following:
 
 @smallexample
 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
 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


@@ -11368,7 +11420,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}}
 
 @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
 @end smallexample
 
 The second method is to use the @samp{n} response to the tape-change


@@ -11551,8 +11603,8 @@ explicitly marked as in the example below:
 @smallexample
 @group
 $ @kbd{tar --verbose --list --file=iamanarchive}
 @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
 
 @end group
 @end smallexample
 


@@ -11647,7 +11699,7 @@ manage to get some date string as part of the label.  For example:
 
 @smallexample
 @group
 
 @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
 $ @kbd{tar --create --file=/dev/tape --multi-volume \
      --label="Daily backup for `date +%Y-%m-%d`"}
 @end group


@@ -11926,11 +11978,16 @@ 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.
 
 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
 
 @node Live untrusted data
 @subsection Dealing with Live Untrusted Data