From 156048b6fd448ca6c89b67d390decb91cb164788 Mon Sep 17 00:00:00 2001 From: Gurjeet Singh Date: Mon, 23 Oct 2023 21:13:42 -0700 Subject: [PATCH v1] Replace references to malloc() in libpq documentation with generic language The user does not benefit from knowing that libpq allocates some/all memory using malloc(). Mentioning malloc() here has a few downsides, and almost no benefits. All the relevant mentions of malloc() are followed by an explicit instruction to use PQfreemem() to free the resulting objects. So the docs perform the sufficient job of educating the user on how to properly free the memory. But these mentions of malloc() may still lead an inexperienced or careless user to (wrongly) believe that they may use free() to free the resulting memory. They will be in a lot of pain until they learn that (when linked statically) libpq's malloc()/free() cannot be mixed with malloc()/free() of whichever malloc() library the client application is being linked with. Another downside of explicitly mentioning that objects returned by libpq functions are allocated with malloc(), is that it exposes the implementation details of libpq to the users. Such details are best left unmentioned so that these can be freely changed in the future without having to worry about its effect on client applications. Whenever necessary, it is sufficient to tell the user that the objects/memory returned by libpq functions is allocated on the heap. That is just enough detail for the user to realize that the relevant object/memory needs to be freed; and the instructions that follow mention to use PQfreemem() to free such memory. One mention of malloc is left intact, because that mention is unrelated to how the memory is allocated, or how to free it. In passing, slightly improve the language of PQencryptPasswordConn() documentation. --- doc/src/sgml/libpq.sgml | 24 ++++++++++++------------ src/interfaces/libpq/fe-auth.c | 2 +- 2 files changed, 13 insertions(+), 13 deletions(-) diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index a52baa27d5..7da2a1d482 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -591,25 +591,25 @@ PQconninfoOption *PQconninfoParse(const char *conninfo, char **errmsg); with an entry having a null keyword pointer. All legal options will be present in the result array, but the PQconninfoOption for any option not present in the connection string will have val set to NULL; default values are not inserted. If errmsg is not NULL, then *errmsg is set - to NULL on success, else to a malloc'd error string explaining + to NULL on success, else to an error string allocated on the heap, explaining the problem. (It is also possible for *errmsg to be set to NULL and the function to return NULL; this indicates an out-of-memory condition.) After processing the options array, free it by passing it to . If this is not done, some memory is leaked for each call to . Conversely, if an error occurs and errmsg is not NULL, be sure to free the error string using . @@ -4543,26 +4543,26 @@ char *PQescapeLiteral(PGconn *conn, const char *str, size_t length); 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. performs this operation. returns an escaped version of the - str parameter in memory allocated with - malloc(). This memory should be freed using + str parameter in memory allocated on the heap. + This memory should be freed using PQfreemem() when the result is no longer needed. 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, stops at the zero; the behavior is thus rather like strncpy.) The return string has all special characters replaced so that they can be properly processed by the PostgreSQL string literal parser. A terminating zero byte is also added. The single quotes that must surround PostgreSQL string literals are included in the result string. @@ -4603,25 +4603,25 @@ char *PQescapeIdentifier(PGconn *conn, const char *str, size_t length); escapes a string for use as an SQL identifier, such as a table, column, or function name. This is useful when a user-supplied identifier might contain special characters that would otherwise not be interpreted as part of the identifier by the SQL parser, or when the identifier might contain upper case characters whose case should be preserved. returns a version of the str parameter escaped as an SQL identifier - in memory allocated with malloc(). This memory must be + in memory allocated on the heap. This memory must be freed using PQfreemem() when the result is no longer needed. 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, stops at the zero; the behavior is thus rather like strncpy.) The return string has all special characters replaced so that it will be properly processed as an SQL identifier. A terminating zero byte is also added. The return string will also be surrounded by double quotes. @@ -4752,25 +4752,25 @@ unsigned char *PQescapeByteaConn(PGconn *conn, byte of the string that is to be escaped, and the from_length parameter gives the number of bytes in this binary string. (A terminating zero byte is neither necessary nor counted.) The to_length parameter points to a variable that will hold the resultant escaped string length. This result string length includes the terminating zero byte of the result. returns an escaped version of the from parameter binary string in memory - allocated with malloc(). This memory should be freed using + allocated on the heap. This memory should be freed using PQfreemem() when the result is no longer needed. 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 zero byte is also added. The single quotes that must surround PostgreSQL string literals are not part of the result string. On error, a null pointer is returned, and a suitable error message is stored in the conn object. Currently, the only @@ -4818,26 +4818,26 @@ unsigned char *PQescapeBytea(const unsigned char *from, but not when retrieving it in binary format. unsigned char *PQunescapeBytea(const unsigned char *from, size_t *to_length); The from parameter points to a string such as might be returned by when applied to a bytea column. converts this string representation into its binary representation. - It returns a pointer to a buffer allocated with - malloc(), or NULL on error, and puts the size of + It returns a pointer to a buffer allocated on the heap, + or NULL on error, and puts the size of the buffer in to_length. The result must be freed using when it is no longer needed. This conversion is not exactly the inverse of , because the string is not expected to be escaped when received from . In particular this means there is no need for string quoting considerations, and so no need for a PGconn parameter. @@ -7086,35 +7086,35 @@ char *PQencryptPasswordConn(PGconn *conn, const char *passwd, const char *user, The passwd and user arguments are the cleartext password, and the SQL name of the user it is for. algorithm specifies the encryption algorithm to use to encrypt the password. Currently supported algorithms are md5 and scram-sha-256 (on and off are also accepted as aliases for md5, for compatibility with older server versions). Note that support for scram-sha-256 was introduced in PostgreSQL version 10, and will not work correctly with older server versions. If algorithm is NULL, this function will query the server for the current value of the - setting. That can block, and + setting. This can block the calling thread, and will fail if the current transaction is aborted, or if the connection - is busy executing another query. If you wish to use the default + is busy executing another command. If you wish to use the default algorithm for the server but want to avoid blocking, query password_encryption yourself before calling , and pass that value as the algorithm. - The return value is a string allocated by malloc. + The return value is a string allocated on the heap. The caller can assume the string doesn't contain any special characters that would require escaping. Use to free the result when done with it. On error, returns NULL, and a suitable message is stored in the connection object. PQencryptPasswordPQencryptPassword @@ -7312,27 +7312,27 @@ void *PQresultAlloc(PGresult *res, size_t nBytes); PQresultMemorySizePQresultMemorySize Retrieves the number of bytes allocated for a PGresult object. size_t PQresultMemorySize(const PGresult *res); - This value is the sum of all malloc requests + This value is the sum of sizes of all memory allocation requests associated with the PGresult object, that is, - all the space that will be freed by . + all the memory that will be freed by . This information can be useful for managing memory consumption. PQlibVersionPQlibVersionPQserverVersion Return the version of libpq that is being used. diff --git a/src/interfaces/libpq/fe-auth.c b/src/interfaces/libpq/fe-auth.c index 912aa14821..5a1b3795d5 100644 --- a/src/interfaces/libpq/fe-auth.c +++ b/src/interfaces/libpq/fe-auth.c @@ -1257,25 +1257,25 @@ PQencryptPassword(const char *passwd, const char *user) * be sent in cleartext if it is encrypted on the client side. This is * good because it ensures the cleartext password won't end up in logs, * pg_stat displays, etc. We export the function so that clients won't * be dependent on low-level details like whether the encryption is MD5 * or something else. * * Arguments are a connection object, the cleartext password, the SQL * name of the user it is for, and a string indicating the algorithm to * use for encrypting the password. If algorithm is NULL, this queries * the server for the current 'password_encryption' value. If you wish * to avoid that, e.g. to avoid blocking, you can execute * 'show password_encryption' yourself before calling this function, and - * pass it as the algorithm. + * pass the result as the algorithm. * * Return value is a malloc'd string. The client may assume the string * doesn't contain any special characters that would require escaping. * On error, an error message is stored in the connection object, and * returns NULL. */ char * PQencryptPasswordConn(PGconn *conn, const char *passwd, const char *user, const char *algorithm) { #define MAX_ALGORITHM_NAME_LEN 50 char algobuf[MAX_ALGORITHM_NAME_LEN + 1]; -- 2.41.0