From: Bruce Momjian <bruce@momjian.us>
To: ljb <ljb9832@pobox.com>
Cc: pgsql-docs@postgresql.org
Subject: Re: [GENERAL] Gripe: bytea_output default => data corruption
Date: Fri, 4 Feb 2011 20:34:38 -0500 (EST)
Message-ID: <201102050134.p151Ycu19097@momjian.us> (raw)
In-Reply-To: <iii215$1jhb$1@news.hub.org>
ljb wrote:
> bruce@momjian.us wrote:
> > Here is an updated patch, again to be backpatched to 9.0.
>
> Getting better.
>
> In change block 1, after PQescapeString synopsis:
> Change: "does not take a Pgconn or error parameters"
> to: "does not take Pgconn or error parameters"
>
> In change block 4, PQescapeBytea, I don't like the change.
> This: "is that PQescapeBytea does not take a PGconn or error parameters"
> is wrong. PQescapeByteaConn does not take an 'error' parameter either.
> Also "no way to report error conditions" is wrong. It returns NULL on an
> error; it just cannot return a specific error message. (Which is OK because
> there is only one, unlikely error: out of memory.)
>
> Reading the before/after text here, I don't see anything that needs
> changing except for dropping the reference to single-threaded (same as for
> PQescapeString). I suggest going back to the original text and just
> changing:
> From: "can be used safely in single-threaded client programs that work with
> only one"
> to: "can only be used safely in client programs that use a single"
>
> (Sorry for the trouble. I should have fully commented on the first one, but
> I find it hard to see the changes with these "git" diffs of SGML.)
OK, updated version attached. I keep most of the new patch for the
PQescapeBytea docs rather than use most of the original so it would
match text for other escape functions.
--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com
+ It's impossible for everything to be true. +
Attachments:/rtmp/libpq.diff (text/x-diff, 6.1K) downloaddiff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgmlindex e78d708..b2ab555 100644
*** a/doc/src/sgml/libpq.sgml
--- b/doc/src/sgml/libpq.sgml
*************** size_t PQescapeStringConn(PGconn *conn,
*** 3371,3385 ****
<listitem>
<para>
<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.
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
--- 3371,3387 ----
<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>
! 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
*************** size_t PQescapeString (char *to, const c
*** 3387,3393 ****
</para>
<para>
! <function>PQescapeString</> 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
--- 3389,3395 ----
</para>
<para>
! <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
*************** unsigned char *PQescapeByteaConn(PGconn
*** 3419,3434 ****
</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.
</para>
<para>
--- 3421,3431 ----
</para>
<para>
! 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>
*************** unsigned char *PQescapeBytea(const unsig
*** 3485,3504 ****
<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</>.
</para>
</listitem>
</varlistentry>
--- 3482,3494 ----
<para>
The only difference from <function>PQescapeByteaConn</> is that
<function>PQescapeBytea</> does not take a <structname>PGconn</>
! 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.sgmlindex 2288f1b..c43f142 100644
*** a/doc/src/sgml/release-9.0.sgml
--- b/doc/src/sgml/release-9.0.sgml
***************
*** 2342,2348 ****
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.
</para>
<para>
--- 2342,2349 ----
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. However, pre-9.0 libpq versions will not
! correctly process hex format from newer servers.
</para>
<para>
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-docs@postgresql.org
Cc: bruce@momjian.us, ljb9832@pobox.com
Subject: Re: [GENERAL] Gripe: bytea_output default => data corruption
In-Reply-To: <201102050134.p151Ycu19097@momjian.us>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox