Skip to content

Commit 5b13d1f

Browse files
robertmhaasrobertmhaas
committed
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.
1 parent 16f2ead commit 5b13d1f

File tree

1 file changed

+104
-96
lines changed

1 file changed

+104
-96
lines changed

‎doc/src/sgml/libpq.sgml‎

Lines changed: 104 additions & 96 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<!-- $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.292 2009/12/02 14:07:25 momjian Exp $ -->
1+
<!-- $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.293 2010/01/20 00:42:28 rhaas Exp $ -->
22

33
<chapter id="libpq">
44
<title><application>libpq</application> - C Library</title>
@@ -2925,118 +2925,126 @@ typedef struct {
29252925
<sect2 id="libpq-exec-escape-string">
29262926
<title>Escaping Strings for Inclusion in SQL Commands</title>
29272927

2928-
<indexterm zone="libpq-exec-escape-string">
2929-
<primary>PQescapeStringConn</primary>
2930-
</indexterm>
2931-
<indexterm zone="libpq-exec-escape-string">
2932-
<primary>PQescapeString</primary>
2933-
</indexterm>
29342928
<indexterm zone="libpq-exec-escape-string">
29352929
<primary>escaping strings</primary>
29362930
<secondary>in libpq</secondary>
29372931
</indexterm>
29382932

2939-
<para>
2940-
<function>PQescapeStringConn</function> escapes a string for use within an SQL
2941-
command. This is useful when inserting data values as literal constants
2942-
in SQL commands. Certain characters (such as quotes and backslashes) must
2943-
be escaped to prevent them from being interpreted specially by the SQL parser.
2944-
<function>PQescapeStringConn</> performs this operation.
2945-
</para>
2933+
<variablelist>
2934+
<varlistentry>
2935+
<term>
2936+
<function>PQescapeStringConn</function>
2937+
<indexterm>
2938+
<primary>PQescapeStringConn</primary>
2939+
</indexterm>
2940+
</term>
29462941

2947-
<tip>
2948-
<para>
2949-
It is especially important to do proper escaping when handling strings that
2950-
were received from an untrustworthy source. Otherwise there is a security
2951-
risk: you are vulnerable to <quote>SQL injection</> attacks wherein unwanted
2952-
SQL commands are fed to your database.
2953-
</para>
2954-
</tip>
2942+
<listitem>
2943+
<para>
2944+
<function>PQescapeStringConn</function> escapes a string for
2945+
use within an SQL command. This is useful when inserting data
2946+
values as literal constants in SQL commands. Certain characters
2947+
(such as quotes and backslashes) must be escaped to prevent them
2948+
from being interpreted specially by the SQL parser.
2949+
<function>PQescapeStringConn</> performs this operation.
2950+
</para>
29552951

2956-
<para>
2957-
Note that it is not necessary nor correct to do escaping when a data
2958-
value is passed as a separate parameter in <function>PQexecParams</> or
2959-
its sibling routines.
2960-
2961-
<synopsis>
2962-
size_t PQescapeStringConn (PGconn *conn,
2963-
char *to, const char *from, size_t length,
2964-
int *error);
2965-
</synopsis>
2966-
</para>
2952+
<tip>
2953+
<para>
2954+
It is especially important to do proper escaping when handling
2955+
strings that were received from an untrustworthy source.
2956+
Otherwise there is a security risk: you are vulnerable to
2957+
<quote>SQL injection</> attacks wherein unwanted SQL commands are
2958+
fed to your database.
2959+
</para>
2960+
</tip>
29672961

2968-
<para>
2969-
<function>PQescapeStringConn</> writes an escaped version of the
2970-
<parameter>from</> string to the <parameter>to</> buffer, escaping
2971-
special characters so that they cannot cause any harm, and adding a
2972-
terminating zero byte. The single quotes that must surround
2973-
<productname>PostgreSQL</> string literals are not included in the
2974-
result string; they should be provided in the SQL command that the
2975-
result is inserted into. The parameter <parameter>from</> points to
2976-
the first character of the string that is to be escaped, and the
2977-
<parameter>length</> parameter gives the number of bytes in this
2978-
string. A terminating zero byte is not required, and should not be
2979-
counted in <parameter>length</>. (If a terminating zero byte is found
2980-
before <parameter>length</> bytes are processed,
2981-
<function>PQescapeStringConn</> stops at the zero; the behavior is
2982-
thus rather like <function>strncpy</>.) <parameter>to</> shall point
2983-
to a buffer that is able to hold at least one more byte than twice
2984-
the value of <parameter>length</>, otherwise the behavior is undefined.
2985-
Behavior is likewise undefined if the <parameter>to</> and
2986-
<parameter>from</> strings overlap.
2987-
</para>
2962+
<para>
2963+
Note that it is not necessary nor correct to do escaping when a data
2964+
value is passed as a separate parameter in <function>PQexecParams</> or
2965+
its sibling routines.
29882966

2989-
<para>
2990-
If the <parameter>error</> parameter is not NULL, then
2991-
<literal>*error</> is set to zero on success, nonzero on error.
2992-
Presently the only possible error conditions involve invalid multibyte
2993-
encoding in the source string. The output string is still generated
2994-
on error, but it can be expected that the server will reject it as
2995-
malformed. On error, a suitable message is stored in the
2996-
<parameter>conn</> object, whether or not <parameter>error</> is NULL.
2997-
</para>
2967+
<synopsis>
2968+
size_t PQescapeStringConn (PGconn *conn,
2969+
char *to, const char *from, size_t length,
2970+
int *error);
2971+
</synopsis>
2972+
</para>
29982973

2999-
<para>
3000-
<function>PQescapeStringConn</> returns the number of bytes written
3001-
to <parameter>to</>, not including the terminating zero byte.
3002-
</para>
2974+
<para>
2975+
<function>PQescapeStringConn</> writes an escaped version of the
2976+
<parameter>from</> string to the <parameter>to</> buffer, escaping
2977+
special characters so that they cannot cause any harm, and adding a
2978+
terminating zero byte. The single quotes that must surround
2979+
<productname>PostgreSQL</> string literals are not included in the
2980+
result string; they should be provided in the SQL command that the
2981+
result is inserted into. The parameter <parameter>from</> points to
2982+
the first character of the string that is to be escaped, and the
2983+
<parameter>length</> parameter gives the number of bytes in this
2984+
string. A terminating zero byte is not required, and should not be
2985+
counted in <parameter>length</>. (If a terminating zero byte is found
2986+
before <parameter>length</> bytes are processed,
2987+
<function>PQescapeStringConn</> stops at the zero; the behavior is
2988+
thus rather like <function>strncpy</>.) <parameter>to</> shall point
2989+
to a buffer that is able to hold at least one more byte than twice
2990+
the value of <parameter>length</>, otherwise the behavior is undefined.
2991+
Behavior is likewise undefined if the <parameter>to</> and
2992+
<parameter>from</> strings overlap.
2993+
</para>
30032994

3004-
<para>
3005-
<synopsis>
3006-
size_t PQescapeString (char *to, const char *from, size_t length);
3007-
</synopsis>
3008-
</para>
2995+
<para>
2996+
If the <parameter>error</> parameter is not NULL, then
2997+
<literal>*error</> is set to zero on success, nonzero on error.
2998+
Presently the only possible error conditions involve invalid multibyte
2999+
encoding in the source string. The output string is still generated
3000+
on error, but it can be expected that the server will reject it as
3001+
malformed. On error, a suitable message is stored in the
3002+
<parameter>conn</> object, whether or not <parameter>error</> is NULL.
3003+
</para>
30093004

3010-
<para>
3011-
<function>PQescapeString</> is an older, deprecated version of
3012-
<function>PQescapeStringConn</>; the difference is that it does
3013-
not take <parameter>conn</> or <parameter>error</> parameters.
3014-
Because of this, it cannot adjust its behavior depending on the
3015-
connection properties (such as character encoding) and therefore
3016-
<emphasis>it might give the wrong results</>. Also, it has no way
3017-
to report error conditions.
3018-
</para>
3005+
<para>
3006+
<function>PQescapeStringConn</> returns the number of bytes written
3007+
to <parameter>to</>, not including the terminating zero byte.
3008+
</para>
3009+
</listitem>
3010+
</varlistentry>
30193011

3020-
<para>
3021-
<function>PQescapeString</> can be used safely in single-threaded
3022-
client programs that work with only one <productname>PostgreSQL</>
3023-
connection at a time (in this case it can find out what it needs to
3024-
know <quote>behind the scenes</>). In other contexts it is a security
3025-
hazard and should be avoided in favor of
3026-
<function>PQescapeStringConn</>.
3027-
</para>
3028-
</sect2>
3012+
<varlistentry>
3013+
<term>
3014+
<function>PQescapeString</function>
3015+
<indexterm>
3016+
<primary>PQescapeString</primary>
3017+
</indexterm>
3018+
</term>
30293019

3020+
<listitem>
3021+
<para>
3022+
<synopsis>
3023+
size_t PQescapeString (char *to, const char *from, size_t length);
3024+
</synopsis>
3025+
</para>
30303026

3031-
<sect2 id="libpq-exec-escape-bytea">
3032-
<title>Escaping Binary Strings for Inclusion in SQL Commands</title>
3027+
<para>
3028+
<function>PQescapeString</> is an older, deprecated version of
3029+
<function>PQescapeStringConn</>; the difference is that it does
3030+
not take <parameter>conn</> or <parameter>error</> parameters.
3031+
Because of this, it cannot adjust its behavior depending on the
3032+
connection properties (such as character encoding) and therefore
3033+
<emphasis>it might give the wrong results</>. Also, it has no way
3034+
to report error conditions.
3035+
</para>
30333036

3034-
<indexterm zone="libpq-exec-escape-bytea">
3035-
<primary>bytea</primary>
3036-
<secondary sortas="libpq">in libpq</secondary>
3037-
</indexterm>
3037+
<para>
3038+
<function>PQescapeString</> can be used safely in single-threaded
3039+
client programs that work with only one <productname>PostgreSQL</>
3040+
connection at a time (in this case it can find out what it needs to
3041+
know <quote>behind the scenes</>). In other contexts it is a security
3042+
hazard and should be avoided in favor of
3043+
<function>PQescapeStringConn</>.
3044+
</para>
3045+
</listitem>
3046+
</varlistentry>
30383047

3039-
<variablelist>
30403048
<varlistentry>
30413049
<term>
30423050
<function>PQescapeByteaConn</function>

0 commit comments

Comments
 (0)