From 888fda809239f2b4c7daa992f504c495f7ec7c92 Mon Sep 17 00:00:00 2001
From: Bruce Momjian <bruce@momjian.us>
Date: Sun, 13 Feb 2011 09:29:01 -0500
Subject: [PATCH] Clarify documentation for libpq's PQescapeBytea to mention
 the new hex format.

Modify PQescapeStringConn() docs to be consisent with other escaping
functions.

Add mention problems with pre-9.0 versions of libpq using not understanding
bytea hex format to the 9.0 release notes.

Backpatch to 9.0 docs.
---
 doc/src/sgml/libpq.sgml       | 46 +++++++++++++++++--------------------------
 doc/src/sgml/release-9.0.sgml |  3 ++-
 2 files changed, 20 insertions(+), 29 deletions(-)

diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 7854998281..f53702c6ad 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -3256,15 +3256,17 @@ size_t PQescapeStringConn(PGconn *conn,
 
      <listitem>
      <para>
+       <function>PQescapeString</> is an older, deprecated version of
+       <function>PQescapeStringConn</>.
 <synopsis>
 size_t PQescapeString (char *to, const char *from, size_t length);
 </synopsis>
      </para>
 
      <para>
-      <function>PQescapeString</> is an older, deprecated version of
-      <function>PQescapeStringConn</>; the difference is that it does
-      not take <parameter>conn</> or <parameter>error</> parameters.
+      The only difference from <function>PQescapeStringConn</> is that
+      <function>PQescapeString</> does not take <structname>PGconn</>
+      or <parameter>error</> parameters.
       Because of this, it cannot adjust its behavior depending on the
       connection properties (such as character encoding) and therefore
       <emphasis>it might give the wrong results</>.  Also, it has no way
@@ -3272,7 +3274,7 @@ size_t PQescapeString (char *to, const char *from, size_t length);
      </para>
 
      <para>
-      <function>PQescapeString</> can be used safely in single-threaded
+      <function>PQescapeString</> can be used safely in
       client programs that work with only one <productname>PostgreSQL</>
       connection at a time (in this case it can find out what it needs to
       know <quote>behind the scenes</>).  In other contexts it is a security
@@ -3304,16 +3306,11 @@ unsigned char *PQescapeByteaConn(PGconn *conn,
       </para>
 
       <para>
-       Certain byte values <emphasis>must</emphasis> be escaped (but all
-       byte values <emphasis>can</emphasis> be escaped) when used as part
-       of a <type>bytea</type> literal in an <acronym>SQL</acronym>
-       statement. In general, to escape a byte, it is converted into the
-       three digit octal number equal to the octet value, and preceded by
-       usually two backslashes. The single quote (<literal>'</>) and backslash
-       (<literal>\</>) characters have special alternative escape
-       sequences. See <xref linkend="datatype-binary"> for more
-       information. <function>PQescapeByteaConn</function> performs this
-       operation, escaping only the minimally required bytes.
+       Certain byte values must be escaped when used as part of a
+       <type>bytea</type> literal in an <acronym>SQL</acronym> statement.
+       <function>PQescapeByteaConn</function> escapes bytes using
+       either hex encoding or backslash escaping.  See <xref
+       linkend="datatype-binary"> for more information.
       </para>
 
       <para>
@@ -3370,20 +3367,13 @@ unsigned char *PQescapeBytea(const unsigned char *from,
       <para>
        The only difference from <function>PQescapeByteaConn</> is that
        <function>PQescapeBytea</> does not take a <structname>PGconn</>
-       parameter.  Because of this, it cannot adjust its behavior
-       depending on the connection properties (in particular, whether
-       standard-conforming strings are enabled) and therefore
-       <emphasis>it might give the wrong results</>.  Also, it has no
-       way to return an error message on failure.
-      </para>
-
-      <para>
-       <function>PQescapeBytea</> can be used safely in single-threaded
-       client programs that work with only one <productname>PostgreSQL</>
-       connection at a time (in this case it can find out what it needs
-       to know <quote>behind the scenes</>).  In other contexts it is
-       a security hazard and should be avoided in favor of
-       <function>PQescapeByteaConn</>.
+       parameter.  Because of this, <function>PQescapeBytea</> can
+       only be used safely in client programs that use a single
+       <productname>PostgreSQL</> connection at a time (in this case
+       it can find out what it needs to know <quote>behind the
+       scenes</>).  It <emphasis>might give the wrong results</> if
+       used in programs that use multiple database connections (use
+       <function>PQescapeByteaConn</> in such cases).
       </para>
      </listitem>
     </varlistentry>
diff --git a/doc/src/sgml/release-9.0.sgml b/doc/src/sgml/release-9.0.sgml
index dcd9e1e22c..8fe18cc30e 100644
--- a/doc/src/sgml/release-9.0.sgml
+++ b/doc/src/sgml/release-9.0.sgml
@@ -2342,7 +2342,8 @@
       whether hex or traditional format is used for <type>bytea</>
       output.  Libpq's <function>PQescapeByteaConn()</> function automatically
       uses the hex format when connected to <productname>PostgreSQL</> 9.0
-      or newer servers.
+      or newer servers.  However, pre-9.0 libpq versions will not
+      correctly process hex format from newer servers.
      </para>
 
      <para>
-- 
2.11.0