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.

diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 7131fb4ce6209ecc87c86c875b11a39eeceebb7d..2d15e78fd08441d7e9113ba4d594dba0135389c6 100644 (file)
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -3385,15 +3385,17 @@ size_t PQescapeStringConn(PGconn *conn,
 
      
      
+       PQescapeString is an older, deprecated version of
+       PQescapeStringConn.
 
 size_t PQescapeString (char *to, const char *from, size_t length);
 
      
 
      
-      PQescapeString is an older, deprecated version of
-      PQescapeStringConn; the difference is that it does
-      not take conn or error parameters.
+      The only difference from PQescapeStringConn is that
+      PQescapeString does not take PGconn
+      or error parameters.
       Because of this, it cannot adjust its behavior depending on the
       connection properties (such as character encoding) and therefore
       it might give the wrong results.  Also, it has no way
@@ -3401,7 +3403,7 @@ size_t PQescapeString (char *to, const char *from, size_t length);
      
 
      
-      PQescapeString can be used safely in single-threaded
+      PQescapeString can be used safely in
       client programs that work with only one PostgreSQL
       connection at a time (in this case it can find out what it needs to
       know behind the scenes).  In other contexts it is a security
@@ -3433,16 +3435,11 @@ unsigned char *PQescapeByteaConn(PGconn *conn,
       
 
       
-       Certain byte values must be escaped (but all
-       byte values can be escaped) when used as part
-       of a bytea literal in an SQL
-       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 (') and backslash
-       (\) characters have special alternative escape
-       sequences. See  for more
-       information. PQescapeByteaConn performs this
-       operation, escaping only the minimally required bytes.
+       Certain byte values must be escaped when used as part of a
+       bytea literal in an SQL statement.
+       PQescapeByteaConn escapes bytes using
+       either hex encoding or backslash escaping.  See 
+       linkend="datatype-binary"> for more information.
       
 
       
@@ -3499,20 +3496,13 @@ unsigned char *PQescapeBytea(const unsigned char *from,
       
        The only difference from PQescapeByteaConn is that
        PQescapeBytea does not take a 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
-       it might give the wrong results.  Also, it has no
-       way to return an error message on failure.
-      
-
-      
-       PQescapeBytea can be used safely in single-threaded
-       client programs that work with only one PostgreSQL
-       connection at a time (in this case it can find out what it needs
-       to know behind the scenes).  In other contexts it is
-       a security hazard and should be avoided in favor of
-       PQescapeByteaConn.
+       parameter.  Because of this, PQescapeBytea can
+       only be used safely in client programs that use a single
+       PostgreSQL connection at a time (in this case
+       it can find out what it needs to know behind the
+       scenes).  It might give the wrong results if
+       used in programs that use multiple database connections (use
+       PQescapeByteaConn in such cases).
       
      
     


diff --git a/doc/src/sgml/release-9.0.sgml b/doc/src/sgml/release-9.0.sgml

index 4902c058a96647153172f000d9bbadcb9782ca25..f33ceea2264c7cc3a208ce3970a3bf62a79f9f5c 100644 (file)

--- 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 bytea
       output.  Libpq's PQescapeByteaConn() function automatically
       uses the hex format when connected to PostgreSQL 9.0
-      or newer servers.
+      or newer servers.  However, pre-9.0 libpq versions will not
+      correctly process hex format from newer servers.
      
 
      

diff --git a/doc/src/sgml/release-9.0.sgml b/doc/src/sgml/release-9.0.sgml
index 4902c058a96647153172f000d9bbadcb9782ca25..f33ceea2264c7cc3a208ce3970a3bf62a79f9f5c 100644 (file)
--- 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 bytea
       output.  Libpq's PQescapeByteaConn() function automatically
       uses the hex format when connected to PostgreSQL 9.0
-      or newer servers.
+      or newer servers.  However, pre-9.0 libpq versions will not
+      correctly process hex format from newer servers.