From 5569ae52ae206b3e35411df435884cf848ae0494 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 7131fb4ce62..2d15e78fd08 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -3385,15 +3385,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
@@ -3401,7 +3403,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
@@ -3433,16 +3435,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>
@@ -3499,20 +3496,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 4902c058a96..f33ceea2264 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>
--
GitLab