diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index 5dce33fbd24..cfa87d0adae 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -1,4 +1,4 @@ - + <application>libpq</application> - C Library @@ -2925,118 +2925,126 @@ typedef struct { Escaping Strings for Inclusion in SQL Commands - - PQescapeStringConn - - - PQescapeString - escaping strings in libpq - - PQescapeStringConn escapes a string for use within an SQL - command. This is useful when inserting data values as literal constants - in SQL commands. Certain characters (such as quotes and backslashes) must - be escaped to prevent them from being interpreted specially by the SQL parser. - PQescapeStringConn performs this operation. - - - - - It is especially important to do proper escaping when handling strings that - were received from an untrustworthy source. Otherwise there is a security - risk: you are vulnerable to SQL injection attacks wherein unwanted - SQL commands are fed to your database. - - - - - Note that it is not necessary nor correct to do escaping when a data - value is passed as a separate parameter in PQexecParams or - its sibling routines. - - - size_t PQescapeStringConn (PGconn *conn, - char *to, const char *from, size_t length, - int *error); - - - - - PQescapeStringConn writes an escaped version of the - from string to the to buffer, escaping - special characters so that they cannot cause any harm, and adding a - terminating zero byte. The single quotes that must surround - 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 from points to - the first character of the string that is to be escaped, and the - length parameter gives the number of bytes in this - string. A terminating zero byte is not required, and should not be - counted in length. (If a terminating zero byte is found - before length bytes are processed, - PQescapeStringConn stops at the zero; the behavior is - thus rather like strncpy.) to shall point - to a buffer that is able to hold at least one more byte than twice - the value of length, otherwise the behavior is undefined. - Behavior is likewise undefined if the to and - from strings overlap. - - - - If the error parameter is not NULL, then - *error is set to zero on success, nonzero on error. - Presently the only possible error conditions involve invalid multibyte - 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 - conn object, whether or not error is NULL. - - - - PQescapeStringConn returns the number of bytes written - to to, not including the terminating zero byte. - - - - - size_t PQescapeString (char *to, const char *from, size_t length); - - - - - PQescapeString is an older, deprecated version of - PQescapeStringConn; the difference is that it does - not take conn or error parameters. - Because of this, it cannot adjust its behavior depending on the - connection properties (such as character encoding) and therefore - it might give the wrong results. Also, it has no way - to report error conditions. - - - - PQescapeString can be used safely in single-threaded - client programs that work with only one PostgreSQL - connection at a time (in this case it can find out what it needs to - know behind the scenes). In other contexts it is a security - hazard and should be avoided in favor of - PQescapeStringConn. - - - - - - Escaping Binary Strings for Inclusion in SQL Commands - - - bytea - in libpq - - + + + PQescapeStringConn + + PQescapeStringConn + + + + + + PQescapeStringConn escapes a string for + use within an SQL command. This is useful when inserting data + values as literal constants in SQL commands. Certain characters + (such as quotes and backslashes) must be escaped to prevent them + from being interpreted specially by the SQL parser. + PQescapeStringConn performs this operation. + + + + + It is especially important to do proper escaping when handling + strings that were received from an untrustworthy source. + Otherwise there is a security risk: you are vulnerable to + SQL injection attacks wherein unwanted SQL commands are + fed to your database. + + + + + Note that it is not necessary nor correct to do escaping when a data + value is passed as a separate parameter in PQexecParams or + its sibling routines. + + + size_t PQescapeStringConn (PGconn *conn, + char *to, const char *from, size_t length, + int *error); + + + + + PQescapeStringConn writes an escaped version of the + from string to the to buffer, escaping + special characters so that they cannot cause any harm, and adding a + terminating zero byte. The single quotes that must surround + 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 from points to + the first character of the string that is to be escaped, and the + length parameter gives the number of bytes in this + string. A terminating zero byte is not required, and should not be + counted in length. (If a terminating zero byte is found + before length bytes are processed, + PQescapeStringConn stops at the zero; the behavior is + thus rather like strncpy.) to shall point + to a buffer that is able to hold at least one more byte than twice + the value of length, otherwise the behavior is undefined. + Behavior is likewise undefined if the to and + from strings overlap. + + + + If the error parameter is not NULL, then + *error is set to zero on success, nonzero on error. + Presently the only possible error conditions involve invalid multibyte + 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 + conn object, whether or not error is NULL. + + + + PQescapeStringConn returns the number of bytes written + to to, not including the terminating zero byte. + + + + + + + PQescapeString + + PQescapeString + + + + + + + size_t PQescapeString (char *to, const char *from, size_t length); + + + + + PQescapeString is an older, deprecated version of + PQescapeStringConn; the difference is that it does + not take conn or error parameters. + Because of this, it cannot adjust its behavior depending on the + connection properties (such as character encoding) and therefore + it might give the wrong results. Also, it has no way + to report error conditions. + + + + PQescapeString can be used safely in single-threaded + client programs that work with only one PostgreSQL + connection at a time (in this case it can find out what it needs to + know behind the scenes). In other contexts it is a security + hazard and should be avoided in favor of + PQescapeStringConn. + + + + PQescapeByteaConn