From: Bruce Momjian <pgman@candle.pha.pa.us>
To: Joe Conway <joseph.conway@home.com>
Cc: pgsql-patches@postgresql.org <pgsql-patches@postgresql.org>
Subject: Re: PQescapeBytea documentation patch
Date: Tue, 20 Nov 2001 15:29:05 -0500 (EST)
Message-ID: <200111202029.fAKKT5g13850@candle.pha.pa.us> (raw)
In-Reply-To: <3BFABB2C.3020307@home.com>
We can fix any cross-reference later. I am applying any reasonable doc
changes and /contrib change by authors right away because we don't have
time for delay.
Patch applied. Thanks.
---------------------------------------------------------------------------
> 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
[ text/html is unsupported, treating like TEXT/PLAIN ]
> *** 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>
>
>
> ---------------------------(end of broadcast)---------------------------
> TIP 3: if posting/reading through Usenet, please send an appropriate
> subscribe-nomail command to majordomo@postgresql.org so that your
> message can get through to the mailing list cleanly
--
Bruce Momjian | http://candle.pha.pa.us
pgman@candle.pha.pa.us | (610) 853-3000
+ If your life is a hard drive, | 830 Blythe Avenue
+ Christ can be your backup. | Drexel Hill, Pennsylvania 19026
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: pgman@candle.pha.pa.us, joseph.conway@home.com, pgsql-patches@postgresql.org
Subject: Re: PQescapeBytea documentation patch
In-Reply-To: <200111202029.fAKKT5g13850@candle.pha.pa.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