pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedPQescapeBytea documentation patch
4+ messages / 3 participants
[nested] [flat]
* PQescapeBytea documentation patch
@ 2001-11-20 20:21 Joe Conway <joseph.conway@home.com>
0 siblings, 2 replies; 4+ messages in thread
From: Joe Conway @ 2001-11-20 20:21 UTC (permalink / raw)
To: pgsql-patches@postgresql.org <pgsql-patches@postgresql.org>
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
Attachments:
libpq.sgml.diff (text/html, 2.6K) download
*** 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>
* Re: PQescapeBytea documentation patch
@ 2001-11-20 20:29 Bruce Momjian <pgman@candle.pha.pa.us>
parent: Joe Conway <joseph.conway@home.com>
1 sibling, 0 replies; 4+ messages in thread
From: Bruce Momjian @ 2001-11-20 20:29 UTC (permalink / raw)
To: Joe Conway <joseph.conway@home.com>; +Cc: pgsql-patches@postgresql.org <pgsql-patches@postgresql.org>
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
^ permalink raw reply [nested|flat] 4+ messages in thread
* Re: [PATCHES] PQescapeBytea documentation patch
@ 2001-11-21 12:25 Patrick Welche <prlw1@newn.cam.ac.uk>
parent: Joe Conway <joseph.conway@home.com>
1 sibling, 1 reply; 4+ messages in thread
From: Patrick Welche @ 2001-11-21 12:25 UTC (permalink / raw)
To: Joe Conway <joseph.conway@home.com>; +Cc: pgsql-interfaces@postgresql.org
On Tue, Nov 20, 2001 at 12:21:00PM -0800, Joe Conway wrote:
> Here's a patch adding documentation for the PQescapeBytea function to
> libpq.sgml
...
+ <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);
This makes me wonder: should libpq contain a function to do the opposite
too? eg.
string=GetValue(from a bytea type column)
PQunescapeBytea(string, some buffer, buffer's size)
- or is there already another way of doing it?
It seems to me that anyone using bytea with libpq will end up having
to reinvent this wheel. (Something worthy of being knocked up in my
Copious Free Time (tm))
Cheers,
Patrick
^ permalink raw reply [nested|flat] 4+ messages in thread
* Re: [PATCHES] PQescapeBytea documentation patch
@ 2001-11-21 17:04 Joe Conway <joseph.conway@home.com>
parent: Patrick Welche <prlw1@newn.cam.ac.uk>
0 siblings, 0 replies; 4+ messages in thread
From: Joe Conway @ 2001-11-21 17:04 UTC (permalink / raw)
To: Patrick Welche <prlw1@newn.cam.ac.uk>; +Cc: pgsql-interfaces@postgresql.org
Patrick Welche wrote:
> This makes me wonder: should libpq contain a function to do the opposite
> too? eg.
>
> string=GetValue(from a bytea type column)
> PQunescapeBytea(string, some buffer, buffer's size)
>
> - or is there already another way of doing it?
>
> It seems to me that anyone using bytea with libpq will end up having
> to reinvent this wheel. (Something worthy of being knocked up in my
> Copious Free Time (tm))
I thought about that, but did not write it for a couple of reasons:
First, there wasn't a strong consensus that this type of function
belonged as part of libpq in the first place, so I didn't want to push
my luck ;-)
Second, at least in my current work, I'm using binary cursors, in which
case no unescaping is necessary.
I do agree that a standard bytea unescape function should be available
in the client library somewhere. Maybe for 7.3 . . .
Joe
^ permalink raw reply [nested|flat] 4+ messages in thread
end of thread, other threads:[~2001-11-21 17:04 UTC | newest]
Thread overview: 4+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2001-11-20 20:21 PQescapeBytea documentation patch Joe Conway <joseph.conway@home.com>
2001-11-20 20:29 ` Bruce Momjian <pgman@candle.pha.pa.us>
2001-11-21 12:25 ` Patrick Welche <prlw1@newn.cam.ac.uk>
2001-11-21 17:04 ` Joe Conway <joseph.conway@home.com>
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