Skip to content

P
Postgres FD Implementation
Commit 5b13d1ff authored by Robert Haas's avatar Robert Haas
Browse files
Options

Reformat documentation of libpq escaping functions. 

Modify the "Escaping Strings for Inclusion in SQL Commands" section
to use a <variablelist> as the preceding and following sections do,
and merge the "Escaping Binary Strings for Inclusion in SQL Commands"
section into it.

This changes only the formatting of these sections, not the content.
It is intended to lay the groundwork for a follow-on patch to add
some new escaping functions, but it makes sense to commit this first,
for clarity.
parent 16f2eadf
Hide whitespace changes
Inline Side-by-side
Showing with 104 additions and 96 deletions
doc/src/sgml/libpq.sgml
View file @ 5b13d1ff
<!-- $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.292 2009/12/02 14:07:25 momjian Exp $ --> <!-- $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.293 2010/01/20 00:42:28 rhaas Exp $ -->
<chapter id="libpq"> <chapter id="libpq">
<title><application>libpq</application> - C Library</title> <title><application>libpq</application> - C Library</title>
...@@ -2925,118 +2925,126 @@ typedef struct { ...@@ -2925,118 +2925,126 @@ typedef struct {
<sect2 id="libpq-exec-escape-string"> <sect2 id="libpq-exec-escape-string">
<title>Escaping Strings for Inclusion in SQL Commands</title> <title>Escaping Strings for Inclusion in SQL Commands</title>
<indexterm zone="libpq-exec-escape-string">
<primary>PQescapeStringConn</primary>
</indexterm>
<indexterm zone="libpq-exec-escape-string">
<primary>PQescapeString</primary>
</indexterm>
<indexterm zone="libpq-exec-escape-string"> <indexterm zone="libpq-exec-escape-string">
<primary>escaping strings</primary> <primary>escaping strings</primary>
<secondary>in libpq</secondary> <secondary>in libpq</secondary>
</indexterm> </indexterm>
<para> <variablelist>
<function>PQescapeStringConn</function> escapes a string for use within an SQL <varlistentry>
command. This is useful when inserting data values as literal constants <term>
in SQL commands. Certain characters (such as quotes and backslashes) must <function>PQescapeStringConn</function>
be escaped to prevent them from being interpreted specially by the SQL parser. <indexterm>
<function>PQescapeStringConn</> performs this operation. <primary>PQescapeStringConn</primary>
</para> </indexterm>
</term>
<tip> <listitem>
<para> <para>
It is especially important to do proper escaping when handling strings that <function>PQescapeStringConn</function> escapes a string for
were received from an untrustworthy source. Otherwise there is a security use within an SQL command. This is useful when inserting data
risk: you are vulnerable to <quote>SQL injection</> attacks wherein unwanted values as literal constants in SQL commands. Certain characters
SQL commands are fed to your database. (such as quotes and backslashes) must be escaped to prevent them
</para> from being interpreted specially by the SQL parser.
</tip> <function>PQescapeStringConn</> performs this operation.
</para>
<para> <tip>
Note that it is not necessary nor correct to do escaping when a data <para>
value is passed as a separate parameter in <function>PQexecParams</> or It is especially important to do proper escaping when handling
its sibling routines. strings that were received from an untrustworthy source.
Otherwise there is a security risk: you are vulnerable to
<synopsis> <quote>SQL injection</> attacks wherein unwanted SQL commands are
size_t PQescapeStringConn (PGconn *conn, fed to your database.
char *to, const char *from, size_t length, </para>
int *error); </tip>
</synopsis>
</para>
<para> <para>
<function>PQescapeStringConn</> writes an escaped version of the Note that it is not necessary nor correct to do escaping when a data
<parameter>from</> string to the <parameter>to</> buffer, escaping value is passed as a separate parameter in <function>PQexecParams</> or
special characters so that they cannot cause any harm, and adding a its sibling routines.
terminating zero byte. The single quotes that must surround
<productname>PostgreSQL</> string literals are not included in the
result string; they should be provided in the SQL command that the
result is inserted into. The parameter <parameter>from</> points to
the first character of the string that is to be escaped, and the
<parameter>length</> parameter gives the number of bytes in this
string. A terminating zero byte is not required, and should not be
counted in <parameter>length</>. (If a terminating zero byte is found
before <parameter>length</> bytes are processed,
<function>PQescapeStringConn</> stops at the zero; the behavior is
thus rather like <function>strncpy</>.) <parameter>to</> shall point
to a buffer that is able to hold at least one more byte than twice
the value of <parameter>length</>, otherwise the behavior is undefined.
Behavior is likewise undefined if the <parameter>to</> and
<parameter>from</> strings overlap.
</para>
<para> <synopsis>
If the <parameter>error</> parameter is not NULL, then size_t PQescapeStringConn (PGconn *conn,
<literal>*error</> is set to zero on success, nonzero on error. char *to, const char *from, size_t length,
Presently the only possible error conditions involve invalid multibyte int *error);
encoding in the source string. The output string is still generated </synopsis>
on error, but it can be expected that the server will reject it as </para>
malformed. On error, a suitable message is stored in the
<parameter>conn</> object, whether or not <parameter>error</> is NULL.
</para>
<para> <para>
<function>PQescapeStringConn</> returns the number of bytes written <function>PQescapeStringConn</> writes an escaped version of the
to <parameter>to</>, not including the terminating zero byte. <parameter>from</> string to the <parameter>to</> buffer, escaping
</para> special characters so that they cannot cause any harm, and adding a
terminating zero byte. The single quotes that must surround
<productname>PostgreSQL</> string literals are not included in the
result string; they should be provided in the SQL command that the
result is inserted into. The parameter <parameter>from</> points to
the first character of the string that is to be escaped, and the
<parameter>length</> parameter gives the number of bytes in this
string. A terminating zero byte is not required, and should not be
counted in <parameter>length</>. (If a terminating zero byte is found
before <parameter>length</> bytes are processed,
<function>PQescapeStringConn</> stops at the zero; the behavior is
thus rather like <function>strncpy</>.) <parameter>to</> shall point
to a buffer that is able to hold at least one more byte than twice
the value of <parameter>length</>, otherwise the behavior is undefined.
Behavior is likewise undefined if the <parameter>to</> and
<parameter>from</> strings overlap.
</para>
<para> <para>
<synopsis> If the <parameter>error</> parameter is not NULL, then
size_t PQescapeString (char *to, const char *from, size_t length); <literal>*error</> is set to zero on success, nonzero on error.
</synopsis> Presently the only possible error conditions involve invalid multibyte
</para> encoding in the source string. The output string is still generated
on error, but it can be expected that the server will reject it as
malformed. On error, a suitable message is stored in the
<parameter>conn</> object, whether or not <parameter>error</> is NULL.
</para>
<para> <para>
<function>PQescapeString</> is an older, deprecated version of <function>PQescapeStringConn</> returns the number of bytes written
<function>PQescapeStringConn</>; the difference is that it does to <parameter>to</>, not including the terminating zero byte.
not take <parameter>conn</> or <parameter>error</> parameters. </para>
Because of this, it cannot adjust its behavior depending on the </listitem>
connection properties (such as character encoding) and therefore </varlistentry>
<emphasis>it might give the wrong results</>. Also, it has no way
to report error conditions.
</para>
<para> <varlistentry>
<function>PQescapeString</> can be used safely in single-threaded <term>
client programs that work with only one <productname>PostgreSQL</> <function>PQescapeString</function>
connection at a time (in this case it can find out what it needs to <indexterm>
know <quote>behind the scenes</>). In other contexts it is a security <primary>PQescapeString</primary>
hazard and should be avoided in favor of </indexterm>
<function>PQescapeStringConn</>. </term>
</para>
</sect2>
<listitem>
<para>
<synopsis>
size_t PQescapeString (char *to, const char *from, size_t length);
</synopsis>
</para>
<sect2 id="libpq-exec-escape-bytea"> <para>
<title>Escaping Binary Strings for Inclusion in SQL Commands</title> <function>PQescapeString</> is an older, deprecated version of
<function>PQescapeStringConn</>; the difference is that it does
not take <parameter>conn</> or <parameter>error</> parameters.
Because of this, it cannot adjust its behavior depending on the
connection properties (such as character encoding) and therefore
<emphasis>it might give the wrong results</>. Also, it has no way
to report error conditions.
</para>
<indexterm zone="libpq-exec-escape-bytea"> <para>
<primary>bytea</primary> <function>PQescapeString</> can be used safely in single-threaded
<secondary sortas="libpq">in libpq</secondary> client programs that work with only one <productname>PostgreSQL</>
</indexterm> 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>PQescapeStringConn</>.
</para>
</listitem>
</varlistentry>
<variablelist>
<varlistentry> <varlistentry>
<term> <term>
<function>PQescapeByteaConn</function> <function>PQescapeByteaConn</function>
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment