Received: from maia.hub.org (maia-5.hub.org [200.46.204.29])
	by mail.postgresql.org (Postfix) with ESMTP id 37036133740B
	for <pgsql-docs-postgresql.org@mail.postgresql.org>;
	Fri,  4 Feb 2011 21:34:45 -0400 (AST)
Received: from mail.postgresql.org ([200.46.204.86])
	by maia.hub.org (mx1.hub.org [200.46.204.29]) (amavisd-maia, port 10024)
	with ESMTP id 83475-06 for
	<pgsql-docs-postgresql.org@mail.postgresql.org>;
	Sat,  5 Feb 2011 01:34:39 +0000 (UTC)
X-Greylist: from auto-whitelisted by SQLgrey-1.7.6
Received: from momjian.us (momjian.us [70.90.9.53])
	by mail.postgresql.org (Postfix) with ESMTP id 5ABE7133616B
	for <pgsql-docs@postgresql.org>; Fri,  4 Feb 2011 21:34:37 -0400 (AST)
Received: (from bruce@localhost) by momjian.us (8.11.6/8.11.6) id
 p151Ycu19097;
	Fri, 4 Feb 2011 20:34:38 -0500 (EST)
From: Bruce Momjian <bruce@momjian.us>
Message-Id: <201102050134.p151Ycu19097@momjian.us>
Subject: Re: [GENERAL] Gripe: bytea_output default => data
 corruption
In-Reply-To: <iii215$1jhb$1@news.hub.org>
To: ljb <ljb9832@pobox.com>
Date: Fri, 4 Feb 2011 20:34:38 -0500 (EST)
CC: pgsql-docs@postgresql.org
X-Mailer: ELM [version 2.4ME+ PL124 (25)]
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="ELM1296869678-1254-0_"
Content-Transfer-Encoding: 7bit
X-Virus-Scanned: Maia Mailguard 1.0.1
X-Spam-Status: No, hits=-1.91 tagged_above=-5 required=5 tests=BAYES_00=-1.9,
	T_RP_MATCHES_RCVD=-0.01
X-Spam-Level: 
X-Archive-Number: 201102/25
X-Sequence-Number: 6373


--ELM1296869678-1254-0_
Content-Transfer-Encoding: 7bit
Content-Type: text/plain; charset="US-ASCII"

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. +

--ELM1296869678-1254-0_
Content-Transfer-Encoding: 7bit
Content-Type: text/x-diff
Content-Disposition: inline; filename="/rtmp/libpq.diff"

diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 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.sgml
index 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>

--ELM1296869678-1254-0_--