database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-07-08 11:42:09 +03:00
Code Activity

Back out libpq doc change; not ready yet.

Browse Source
This commit is contained in:
Bruce Momjian
2011-02-13 00:17:55 -05:00
parent 8e7af60872
commit cebbaa1d5d
2 changed files with 29 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

46
doc/src/sgml/libpq.sgml
View File

@ -3385,17 +3385,15 @@ size_t PQescapeStringConn(PGconn *conn,
<listitem> <listitem>
<para> <para>
<function>PQescapeString</> is an older, deprecated version of
<function>PQescapeStringConn</>.
<synopsis> <synopsis>
size_t PQescapeString (char *to, const char *from, size_t length); size_t PQescapeString (char *to, const char *from, size_t length);
</synopsis> </synopsis>
</para> </para>
<para> <para>
The only difference from <function>PQescapeStringConn</> is that <function>PQescapeString</> is an older, deprecated version of
<function>PQescapeString</> does not take <structname>PGconn</> <function>PQescapeStringConn</>; the difference is that it does
or <parameter>error</> parameters. not take <parameter>conn</> or <parameter>error</> parameters.
Because of this, it cannot adjust its behavior depending on the Because of this, it cannot adjust its behavior depending on the
connection properties (such as character encoding) and therefore connection properties (such as character encoding) and therefore
<emphasis>it might give the wrong results</>. Also, it has no way <emphasis>it might give the wrong results</>. Also, it has no way
@ -3403,7 +3401,7 @@ size_t PQescapeString (char *to, const char *from, size_t length);
</para> </para>
<para> <para>
<function>PQescapeString</> can be used safely in <function>PQescapeString</> can be used safely in single-threaded
client programs that work with only one <productname>PostgreSQL</> client programs that work with only one <productname>PostgreSQL</>
connection at a time (in this case it can find out what it needs to connection at a time (in this case it can find out what it needs to
know <quote>behind the scenes</>). In other contexts it is a security know <quote>behind the scenes</>). In other contexts it is a security
@ -3435,11 +3433,16 @@ unsigned char *PQescapeByteaConn(PGconn *conn,
</para> </para>
<para> <para>
Certain byte values must be escaped when used as part of a Certain byte values <emphasis>must</emphasis> be escaped (but all
<type>bytea</type> literal in an <acronym>SQL</acronym> statement. byte values <emphasis>can</emphasis> be escaped) when used as part
<function>PQescapeByteaConn</function> escapes bytes using of a <type>bytea</type> literal in an <acronym>SQL</acronym>
either hex encoding or backslash escaping. See <xref statement. In general, to escape a byte, it is converted into the
linkend="datatype-binary"> for more information. three digit octal number equal to the octet value, and preceded by
usually two backslashes. The single quote (<literal>'</>) and backslash
(<literal>\</>) characters have special alternative escape
sequences. See <xref linkend="datatype-binary"> for more
information. <function>PQescapeByteaConn</function> performs this
operation, escaping only the minimally required bytes.
</para> </para>
<para> <para>
@ -3496,13 +3499,20 @@ unsigned char *PQescapeBytea(const unsigned char *from,
<para> <para>
The only difference from <function>PQescapeByteaConn</> is that The only difference from <function>PQescapeByteaConn</> is that
<function>PQescapeBytea</> does not take a <structname>PGconn</> <function>PQescapeBytea</> does not take a <structname>PGconn</>
parameter. Because of this, <function>PQescapeBytea</> can parameter. Because of this, it cannot adjust its behavior
only be used safely in client programs that use a single depending on the connection properties (in particular, whether
<productname>PostgreSQL</> connection at a time (in this case standard-conforming strings are enabled) and therefore
it can find out what it needs to know <quote>behind the <emphasis>it might give the wrong results</>. Also, it has no
scenes</>). It <emphasis>might give the wrong results</> if way to return an error message on failure.
used in programs that use multiple database connections (use </para>
<function>PQescapeByteaConn</> in such cases).
<para>
<function>PQescapeBytea</> can be used safely in single-threaded
client programs that work with only one <productname>PostgreSQL</>
connection at a time (in this case it can find out what it needs
to know <quote>behind the scenes</>). In other contexts it is
a security hazard and should be avoided in favor of
<function>PQescapeByteaConn</>.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>

3
doc/src/sgml/release-9.0.sgml
View File

@ -2342,8 +2342,7 @@
whether hex or traditional format is used for <type>bytea</> whether hex or traditional format is used for <type>bytea</>
output. Libpq's <function>PQescapeByteaConn()</> function automatically output. Libpq's <function>PQescapeByteaConn()</> function automatically
uses the hex format when connected to <productname>PostgreSQL</> 9.0 uses the hex format when connected to <productname>PostgreSQL</> 9.0
or newer servers. However, pre-9.0 libpq versions will not or newer servers.
correctly process hex format from newer servers.
</para> </para>
<para> <para>