Received: from femail21.sdc1.sfba.home.com (femail21.sdc1.sfba.home.com
	[24.0.95.146])
	by postgresql.org (8.11.3/8.11.4) with ESMTP id fAKKKwm42591
	for <pgsql-patches@postgresql.org>;
	Tue, 20 Nov 2001 15:20:58 -0500 (EST)
	(envelope-from joseph.conway@home.com)
Received: from home.com ([24.0.42.111]) by femail21.sdc1.sfba.home.com
	(InterMail vM.4.01.03.20 201-229-121-120-20010223) with ESMTP
	id <20011120202048.TIFJ25754.femail21.sdc1.sfba.home.com@home.com>
	for <pgsql-patches@postgresql.org>; Tue, 20 Nov 2001 12:20:48 -0800
Message-ID: <3BFABB2C.3020307@home.com>
Date: Tue, 20 Nov 2001 12:21:00 -0800
From: Joe Conway <joseph.conway@home.com>
User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.0; en-US;
	rv:0.9.6) Gecko/20011116
X-Accept-Language: en-us
MIME-Version: 1.0
To: "pgsql-patches@postgresql.org" <pgsql-patches@postgresql.org>
Subject: PQescapeBytea documentation patch
Content-Type: multipart/mixed; boundary="------------080608040402010901090704"
X-Archive-Number: 200111/201
X-Sequence-Number: 2632

This is a multi-part message in MIME format.
--------------080608040402010901090704
Content-Type: text/plain; charset=us-ascii; format=flowed
Content-Transfer-Encoding: 7bit

Here's a patch adding documentation for the PQescapeBytea function to 
libpq.sgml

I was trying (but gave up) to cross-reference back to the input escape 
table in the User's Guide, but could not get the documentation to 
compile with a cross-book xref (missing IDREF error). Can a cross-book 
xref be done?

Thanks,

Joe

--------------080608040402010901090704
Content-Type: text/html; name="libpq.sgml.diff"
Content-Transfer-Encoding: 7bit
Content-Disposition: inline; filename="libpq.sgml.diff"

*** sgml.orig/libpq.sgml	Sun Nov 18 19:58:23 2001
--- sgml/libpq.sgml	Tue Nov 20 12:16:30 2001
***************
*** 903,908 ****
--- 903,958 ----
  </para>
  </sect2>
  
+ 
+  <sect2 id="libpq-exec-escape-bytea">
+   <title>Escaping binary strings for inclusion in SQL queries</title>
+   <indexterm zone="libpq-exec-escape-bytea">
+    <primary>escaping binary strings</primary>
+   </indexterm>
+   <para>
+    <function>PQescapeBytea</function>
+    Escapes a binary string (bytea type) for use within an SQL query.
+    <synopsis>
+     unsigned char *PQescapeBytea(unsigned char *from,
+                                          size_t from_length,
+                                          size_t *to_length);
+    </synopsis>
+ 
+    Certain <acronym>ASCII</acronym> characters MUST be escaped (but all
+    characters MAY be escaped) when used as part of a <type>BYTEA</type>
+    string literal in an <acronym>SQL</acronym> statement. In general, to
+    escape a character, it is converted into the three digit octal number
+    equal to the decimal <acronym>ASCII</acronym> value, and preceeded by
+    two backslashes. The single quote (') and backslash (\) characters have
+    special alternate escape sequences. See the Binary String data type
+    in the User's Guide for more information. <function>PQescapeBytea
+    </function> performs this operation, escaping only the minimally
+    required characters.
+   </para>
+ 
+   <para>
+    The <parameter>from</parameter> parameter points to the first
+    character of the string that is to be escaped, and the
+    <parameter>from_length</parameter> parameter reflects the number of
+    characters in this binary string (a terminating NUL character is
+    neither necessary nor counted).  The <parameter>to_length</parameter>
+    parameter shall point to a buffer suitable to hold the resultant
+    escaped string length. The result string length does not
+    include the terminating NUL character of the result.
+   </para>
+ 
+   <para>
+    <function>PQescapeBytea</> returns an escaped version of the
+    <parameter>from</parameter> parameter binary string, to a caller
+    provided buffer. The return string has all special characters replaced
+    so that they can be properly processed by the PostgreSQL string literal
+    parser, and the <type>bytea</type> input function. A terminating NUL
+    character is also added.  The single quotes that must surround
+    PostgreSQL string literals are not part of the result string.
+   </para>
+  </sect2>
+ 
+ 
  <sect2 id="libpq-exec-select-info">
    <title>Retrieving SELECT Result Information</title>
  

--------------080608040402010901090704--