Received: from localhost (wm.hub.org [200.46.204.128])
	by postgresql.org (Postfix) with ESMTP id E734B9FA465
	for <pgsql-docs-postgresql.org@postgresql.org>;
	Thu, 23 Nov 2006 00:28:51 -0400 (AST)
Received: from postgresql.org ([200.46.204.71])
	by localhost (mx1.hub.org [200.46.204.128]) (amavisd-new, port 10024)
	with ESMTP id 89696-04 for <pgsql-docs-postgresql.org@postgresql.org>;
	Thu, 23 Nov 2006 04:28:36 +0000 (UTC)
X-Greylist: from auto-whitelisted by SQLgrey-1.7.4
Received: from momjian.us (momjian.us [70.90.9.53])
	by postgresql.org (Postfix) with ESMTP id 7E2439FA220
	for <pgsql-docs@postgresql.org>; Thu, 23 Nov 2006 00:28:35 -0400 (AST)
Received: (from bruce@localhost) by momjian.us (8.11.6/8.11.6) id
 kAN4Sa714977;
	Wed, 22 Nov 2006 23:28:36 -0500 (EST)
From: Bruce Momjian <bruce@momjian.us>
Message-Id: <200611230428.kAN4Sa714977@momjian.us>
Subject: Re: bytea vs standard_conforming_strings
In-Reply-To: <1836.1161654209@sss.pgh.pa.us>
To: Tom Lane <tgl@sss.pgh.pa.us>
Date: Wed, 22 Nov 2006 23:28:36 -0500 (EST)
CC: pgsql-docs@postgresql.org
X-Mailer: ELM [version 2.4ME+ PL123]
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="ELM1164256116-22309-0_"
Content-Transfer-Encoding: 7bit
X-Virus-Scanned: Maia Mailguard 1.0.1
X-Archive-Number: 200611/77
X-Sequence-Number: 3911


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

Tom Lane wrote:
> The discussion of bytea in section 8.4,
> http://developer.postgresql.org/pgdocs/postgres/datatype-binary.html
> is obsolete because it assumes that standard_conforming_strings is
> always OFF.  It could be very much simpler and shorter if
> standard_conforming_strings were always ON, but that's not reality
> either.  Anyone have an idea on how to rewrite it in a way that
> isn't awkward, incomprehensible, or both?

I added two "(assuming <varname>standard_conforming_strings</> is
<literal>off</>)" clauses in the bytea docs.  Patch attached, sorry for
the new wrapping.

-- 
  Bruce Momjian   bruce@momjian.us
  EnterpriseDB    http://www.enterprisedb.com

  + If your life is a hard drive, Christ can be your backup. +

--ELM1164256116-22309-0_
Content-Transfer-Encoding: 7bit
Content-Type: text/x-diff
Content-Disposition: inline; filename="/rtmp/diff"

Index: doc/src/sgml/datatype.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v
retrieving revision 1.180
diff -c -c -r1.180 datatype.sgml
*** doc/src/sgml/datatype.sgml	23 Oct 2006 18:10:30 -0000	1.180
--- doc/src/sgml/datatype.sgml	23 Nov 2006 04:21:46 -0000
***************
*** 1097,1111 ****
     </para>
  
     <para>
!     When entering <type>bytea</type> values, octets of certain values
!     <emphasis>must</emphasis> be escaped (but all octet values
!     <emphasis>can</emphasis> be escaped) when used as part of a string
!     literal in an <acronym>SQL</acronym> statement. In general, to
!     escape an octet, it is converted into the three-digit octal number
!     equivalent of its decimal octet value, and preceded by two
!     backslashes. <xref linkend="datatype-binary-sqlesc"> shows the
!     characters that must be escaped, and gives the alternate escape
!     sequences where applicable.
     </para>
  
     <table id="datatype-binary-sqlesc">
--- 1097,1113 ----
     </para>
  
     <para>
!     When entering <type>bytea</type> values, octets of certain
!     values <emphasis>must</emphasis> be escaped (but all octet
!     values <emphasis>can</emphasis> be escaped) when used as part
!     of a string literal in an <acronym>SQL</acronym> statement. In
!     general, to escape an octet, it is converted into the three-digit
!     octal number equivalent of its decimal octet value, and preceded
!     by two backslashes (or one backslash if
!     <varname>standard_conforming_strings</> is <literal>off</>).
!     <xref linkend="datatype-binary-sqlesc"> shows the characters
!     that must be escaped, and gives the alternate escape sequences
!     where applicable.
     </para>
  
     <table id="datatype-binary-sqlesc">
***************
*** 1168,1191 ****
     </para>
  
     <para>
!     The reason that you have to write so many backslashes, as shown in
!     <xref linkend="datatype-binary-sqlesc">, is that an input string
!     written as a string literal must pass through two parse phases in
!     the <productname>PostgreSQL</productname> server.  The first
!     backslash of each pair is interpreted as an escape character by
!     the string-literal parser and is therefore consumed, leaving the
!     second backslash of the pair.  The remaining backslash is then
!     recognized by the <type>bytea</type> input function as starting
!     either a three digit octal value or escaping another backslash.
!     For example, a string literal passed to the server as
!     <literal>'\\001'</literal> becomes <literal>\001</literal> after
!     passing through the string-literal parser. The
!     <literal>\001</literal> is then sent to the <type>bytea</type>
!     input function, where it is converted to a single octet with a
!     decimal value of 1.  Note that the apostrophe character is not
!     treated specially by <type>bytea</type>, so it follows the normal
!     rules for string literals.  (See also <xref
!     linkend="sql-syntax-strings">.)
     </para>
  
     <para>
--- 1170,1194 ----
     </para>
  
     <para>
!     The reason that you have to write so many backslashes, as shown
!     in <xref linkend="datatype-binary-sqlesc">, is that an input
!     string written as a string literal must pass through two parse
!     phases in the <productname>PostgreSQL</productname> server.
!     The first backslash of each pair is interpreted as an escape
!     character by the string-literal parser (assuming
!     <varname>standard_conforming_strings</> is <literal>off</>)
!     and is therefore consumed, leaving the second backslash of the
!     pair.  The remaining backslash is then recognized by the
!     <type>bytea</type> input function as starting either a three
!     digit octal value or escaping another backslash.  For example,
!     a string literal passed to the server as <literal>'\\001'</literal>
!     becomes <literal>\001</literal> after passing through the
!     string-literal parser. The <literal>\001</literal> is then sent
!     to the <type>bytea</type> input function, where it is converted
!     to a single octet with a decimal value of 1.  Note that the
!     apostrophe character is not treated specially by <type>bytea</type>,
!     so it follows the normal rules for string literals.  (See also
!     <xref linkend="sql-syntax-strings">.)
     </para>
  
     <para>

--ELM1164256116-22309-0_--