From 26996cf78e27e7bd0feb51a51a5a65308290bc5e Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Fri, 17 Jun 2011 19:13:25 -0400
Subject: [PATCH] Don't use "cp -i" in the example WAL archive_command.

This is a dangerous example to provide because on machines with GNU cp,
it will silently do the wrong thing and risk archive corruption.  Worse,
during the 9.0 cycle somebody "improved" the discussion by removing the
warning that used to be there about that, and instead leaving the
impression that the command would work as desired on most Unixen.
It doesn't.  Try to rectify the damage by providing an example that is safe
most everywhere, and then noting that you can try cp -i if you want but
you'd better test that.

In back-patching this to all supported branches, I also added an example
command for Windows, which wasn't provided before 9.0.
---
 doc/src/sgml/backup.sgml | 23 +++++++++++++----------
 1 file changed, 13 insertions(+), 10 deletions(-)

diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml
index 1640c67fd67..611e94911a4 100644
--- a/doc/src/sgml/backup.sgml
+++ b/doc/src/sgml/backup.sgml
@@ -530,7 +530,8 @@ tar -cf backup.tar /usr/local/pgsql/data
     character in the command.  The simplest useful command is something
     like
 <programlisting>
-archive_command = 'cp -i %p /mnt/server/archivedir/%f &lt;/dev/null'
+archive_command = 'test ! -f /mnt/server/archivedir/%f && cp %p /mnt/server/archivedir/%f'  # Unix
+archive_command = 'copy "%p" "C:\\server\\archivedir\\%f"'  # Windows
 </programlisting>
     which will copy archivable WAL segments to the directory
     <filename>/mnt/server/archivedir</>.  (This is an example, not a 
@@ -562,17 +563,19 @@ archive_command = 'cp -i %p /mnt/server/archivedir/%f &lt;/dev/null'
     preserve the integrity of your archive in case of administrator error
     (such as sending the output of two different servers to the same archive
     directory).
+   </para>
+
+   <para>
     It is advisable to test your proposed archive command to ensure that it
     indeed does not overwrite an existing file, <emphasis>and that it returns
-    nonzero status in this case</>.  We have found that <literal>cp -i</> does
-    this correctly on some platforms but not others.  If the chosen command
-    does not itself handle this case correctly, you should add a command
-    to test for pre-existence of the archive file.  For example, something
-    like
-<programlisting>
-archive_command = 'test ! -f .../%f &amp;&amp; cp %p .../%f'
-</programlisting>
-    works correctly on most Unix variants.
+    nonzero status in this case</>.
+    The example command above for Unix ensures this by including a separate
+    <command>test</> step.  On some Unix platforms, <command>cp</> has
+    switches such as <option>-i</> that can be used to do the same thing
+    less verbosely, but you should not rely on these without verifying that
+    the right exit status is returned.  (In particular, GNU <command>cp</>
+    will return status zero when <option>-i</> is used and the target file
+    already exists, which is <emphasis>not</> the desired behavior.)
    </para>
 
    <para>