<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/libpq.sgml,v 1.77 2001/11/19 03:58:23 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/libpq.sgml,v 1.78 2001/11/20 20:28:31 momjian Exp $
-->
<chapter id="libpq">
</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>