From joseph.conway@home.com Tue Nov 20 20:20:58 2001 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 ; 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 ; 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 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" 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 ---- + + + Escaping binary strings for inclusion in SQL queries + + escaping binary strings + + + PQescapeBytea + Escapes a binary string (bytea type) for use within an SQL query. + + unsigned char *PQescapeBytea(unsigned char *from, + size_t from_length, + size_t *to_length); + + + Certain ASCII characters MUST be escaped (but all + characters MAY be escaped) when used as part of a BYTEA + string literal in an SQL statement. In general, to + escape a character, it is converted into the three digit octal number + equal to the decimal ASCII 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. PQescapeBytea + performs this operation, escaping only the minimally + required characters. + + + + The from parameter points to the first + character of the string that is to be escaped, and the + from_length parameter reflects the number of + characters in this binary string (a terminating NUL character is + neither necessary nor counted). The to_length + 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. + + + + PQescapeBytea returns an escaped version of the + from 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 bytea 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. + + + + Retrieving SELECT Result Information --------------080608040402010901090704-- From pgman@candle.pha.pa.us Tue Nov 20 20:29:08 2001 Received: from candle.pha.pa.us (candle.navpoint.com [162.33.245.46]) by postgresql.org (8.11.3/8.11.4) with ESMTP id fAKKT8m42839 for ; Tue, 20 Nov 2001 15:29:08 -0500 (EST) (envelope-from pgman@candle.pha.pa.us) Received: (from pgman@localhost) by candle.pha.pa.us (8.11.6/8.10.1) id fAKKT5g13850; Tue, 20 Nov 2001 15:29:05 -0500 (EST) From: Bruce Momjian Message-Id: <200111202029.fAKKT5g13850@candle.pha.pa.us> Subject: Re: PQescapeBytea documentation patch In-Reply-To: <3BFABB2C.3020307@home.com> "from Joe Conway at Nov 20, 2001 12:21:00 pm" To: Joe Conway Date: Tue, 20 Nov 2001 15:29:05 -0500 (EST) CC: "pgsql-patches@postgresql.org" X-Mailer: ELM [version 2.4ME+ PL90 (25)] MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Type: text/plain; charset=US-ASCII X-Archive-Number: 200111/202 X-Sequence-Number: 2633 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 ---- > > > > + > + > + Escaping binary strings for inclusion in SQL queries > + > + escaping binary strings > + > + > + PQescapeBytea > + Escapes a binary string (bytea type) for use within an SQL query. > + > + unsigned char *PQescapeBytea(unsigned char *from, > + size_t from_length, > + size_t *to_length); > + > + > + Certain ASCII characters MUST be escaped (but all > + characters MAY be escaped) when used as part of a BYTEA > + string literal in an SQL statement. In general, to > + escape a character, it is converted into the three digit octal number > + equal to the decimal ASCII 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. PQescapeBytea > + performs this operation, escaping only the minimally > + required characters. > + > + > + > + The from parameter points to the first > + character of the string that is to be escaped, and the > + from_length parameter reflects the number of > + characters in this binary string (a terminating NUL character is > + neither necessary nor counted). The to_length > + 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. > + > + > + > + PQescapeBytea returns an escaped version of the > + from 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 bytea 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. > + > + > + > + > > Retrieving SELECT Result Information > > > ---------------------------(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 From prlw1@newn.cam.ac.uk Wed Nov 21 12:26:13 2001 Received: from henry.newn.cam.ac.uk (henry.newn.cam.ac.uk [131.111.204.130]) by postgresql.org (8.11.3/8.11.4) with ESMTP id fALCQ3m34112 for ; Wed, 21 Nov 2001 07:26:13 -0500 (EST) (envelope-from prlw1@newn.cam.ac.uk) Received: from [131.111.204.180] (helo=quartz.newn.cam.ac.uk) by henry.newn.cam.ac.uk with esmtp (Exim 3.13 #1) id 166WRv-0003Jm-00; Wed, 21 Nov 2001 12:25:55 +0000 Received: from prlw1 by quartz.newn.cam.ac.uk with local (Exim 3.13 #1) id 166WRv-0005VM-00; Wed, 21 Nov 2001 12:25:55 +0000 Date: Wed, 21 Nov 2001 12:25:55 +0000 From: Patrick Welche To: Joe Conway Cc: pgsql-interfaces@postgresql.org Subject: Re: [PATCHES] PQescapeBytea documentation patch Message-ID: <20011121122555.B21102@quartz.newn.cam.ac.uk> References: <3BFABB2C.3020307@home.com> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <3BFABB2C.3020307@home.com> User-Agent: Mutt/1.3.19i X-Archive-Number: 200111/52 X-Sequence-Number: 2112 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 ... + PQescapeBytea + Escapes a binary string (bytea type) for use within an SQL query. + + 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 From joseph.conway@home.com Wed Nov 21 17:04:31 2001 Received: from femail35.sdc1.sfba.home.com (femail35.sdc1.sfba.home.com [24.254.60.25]) by postgresql.org (8.11.3/8.11.4) with ESMTP id fALH4Vm47099 for ; Wed, 21 Nov 2001 12:04:31 -0500 (EST) (envelope-from joseph.conway@home.com) Received: from home.com ([24.0.42.111]) by femail35.sdc1.sfba.home.com (InterMail vM.4.01.03.20 201-229-121-120-20010223) with ESMTP id <20011121170431.GGAK22926.femail35.sdc1.sfba.home.com@home.com>; Wed, 21 Nov 2001 09:04:31 -0800 Message-ID: <3BFBDEA9.3070703@home.com> Date: Wed, 21 Nov 2001 09:04:41 -0800 From: Joe Conway 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: Patrick Welche CC: pgsql-interfaces@postgresql.org Subject: Re: [PATCHES] PQescapeBytea documentation patch References: <3BFABB2C.3020307@home.com> <20011121122555.B21102@quartz.newn.cam.ac.uk> Content-Type: text/plain; charset=us-ascii; format=flowed Content-Transfer-Encoding: 7bit X-Archive-Number: 200111/53 X-Sequence-Number: 2113 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