34.12. 其他函数#

一如既往，有些函数无法归入任何类别。

PQfreemem #

释放 libpq 分配的内存。

void PQfreemem(void *ptr);

释放 libpq 分配的内存，尤其是 PQescapeByteaConn、PQescapeBytea、PQunescapeBytea 和 PQnotifies。尤其重要的是，在 Microsoft Windows 上使用此函数，而不是 free()。这是因为仅当 DLL 和应用程序的多线程/单线程、发布/调试和静态/动态标志相同的情况下，才能在 DLL 中分配内存并在应用程序中释放内存。在非 Microsoft Windows 平台上，此函数与标准库函数 free() 相同。

PQconninfoFree #

释放 PQconndefaults 或 PQconninfoParse 分配的数据结构。

void PQconninfoFree(PQconninfoOption *connOptions);

如果参数是 NULL 指针，则不执行任何操作。

简单的 PQfreemem 无法实现此目的，因为该数组包含对辅助字符串的引用。

PQencryptPasswordConn #

准备 PostgreSQL 密码的加密形式。

char *PQencryptPasswordConn(PGconn *conn, const char *passwd, const char *user, const char *algorithm);

此函数旨在供希望发送 ALTER USER joe PASSWORD 'pwd' 等命令的客户端应用程序使用。建议不要在该命令中发送原始明文密码，因为它可能会在命令日志、活动显示等中公开。相反，在发送密码之前，请使用此函数将其转换为加密形式。

passwd 和 user 参数是明文密码和它所属用户的 SQL 名称。algorithm 指定用于加密密码的加密算法。当前支持的算法有 md5 和 scram-sha-256（on 和 off 也被接受为 md5 的别名，以兼容旧的服务器版本）。请注意，对 scram-sha-256 的支持是在 PostgreSQL 10 版本中引入的，它不能与旧的服务器版本正确协作。如果 algorithm 为 NULL，此函数将查询服务器以获取 password_encryption 设置的当前值。这可能会阻塞，如果当前事务中止或连接忙于执行另一个查询，它将失败。如果您希望使用服务器的默认算法，但希望避免阻塞，请在调用 PQencryptPasswordConn 之前自行查询 password_encryption，并将该值作为 algorithm 传递。

返回值是由 malloc 分配的字符串。调用者可以假设该字符串不包含任何需要转义的特殊字符。使用 PQfreemem 在完成后释放结果。如果出错，则返回 NULL，并且一个合适的错误消息存储在连接对象中。

PQencryptPassword #

准备 PostgreSQL 密码的 md5 加密形式。

char *PQencryptPassword(const char *passwd, const char *user);

PQencryptPassword 是 PQencryptPasswordConn 的一个较旧的、弃用的版本。不同之处在于 PQencryptPassword 不需要连接对象，并且始终使用 md5 作为加密算法。

PQmakeEmptyPGresult #

使用给定的状态构造一个空的 PGresult 对象。

PGresult *PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status);

这是 libpq 的内部函数，用于分配和初始化一个空的 PGresult 对象。如果无法分配内存，此函数将返回 NULL。它被导出，因为某些应用程序发现它对生成结果对象（尤其是具有错误状态的对象）很有用。如果 conn 不为 null 且 status 指示错误，则将指定连接的当前错误消息复制到 PGresult 中。此外，如果 conn 不为 null，则连接中注册的任何事件过程将被复制到 PGresult 中。（它们不会收到 PGEVT_RESULTCREATE 调用，但请参阅 PQfireResultCreateEvents。）请注意，最终应在对象上调用 PQclear，就像使用 libpq 本身返回的 PGresult 一样。

PQfireResultCreateEvents #

为 PGresult 对象中注册的每个事件过程触发 PGEVT_RESULTCREATE 事件（请参阅第 34.14 节）。成功时返回非零值，如果任何事件过程失败，则返回零。

int PQfireResultCreateEvents(PGconn *conn, PGresult *res);

conn 参数会传递到事件过程，但不会直接使用。如果事件过程不会使用它，则它可以为 NULL。

对于已为此对象收到 PGEVT_RESULTCREATE 或 PGEVT_RESULTCOPY 事件的事件过程，不会再次触发。

此函数与 PQmakeEmptyPGresult 分开的主要原因是，通常在调用事件过程之前创建 PGresult 并用数据填充它是很合适的。

PQcopyResult #

复制一个 PGresult 对象。该副本不会以任何方式链接到源结果，并且在不再需要副本时必须调用 PQclear。如果函数失败，则返回 NULL。

PGresult *PQcopyResult(const PGresult *src, int flags);

这不旨在创建精确副本。返回的结果始终放入 PGRES_TUPLES_OK 状态，并且不会复制源中的任何错误消息。（但会复制命令状态字符串。）flags 参数决定了复制哪些其他内容。它是几个标志的按位 OR。 PG_COPYRES_ATTRS 指定复制源结果的属性（列定义）。 PG_COPYRES_TUPLES 指定复制源结果的元组。（这也意味着复制属性。） PG_COPYRES_NOTICEHOOKS 指定复制源结果的通知挂钩。 PG_COPYRES_EVENTS 指定复制源结果的事件。（但与源关联的任何实例数据都不会被复制。）事件过程会接收 PGEVT_RESULTCOPY 事件。

PQsetResultAttrs #

设置 PGresult 对象的属性。

int PQsetResultAttrs(PGresult *res, int numAttributes, PGresAttDesc *attDescs);

提供的 attDescs 会复制到结果中。如果 attDescs 指针为 NULL 或 numAttributes 小于 1，则忽略请求且函数成功。如果 res 已包含属性，则函数将失败。如果函数失败，则返回值为零。如果函数成功，则返回值为非零。

PQsetvalue #

设置 PGresult 对象的元组字段值。

int PQsetvalue(PGresult *res, int tup_num, int field_num, char *value, int len);

该函数会根据需要自动增加结果的内部元组数组。但是，tup_num 参数必须小于或等于 PQntuples，这意味着该函数一次只能增加元组数组一个元组。但可以按任何顺序修改任何现有元组的任何字段。如果 field_num 处已存在值，则会覆盖该值。如果 len 为 -1 或 value 为 NULL，则字段值将设置为 SQL null 值。 value 会复制到结果的私有存储中，因此在函数返回后不再需要它。如果函数失败，则返回值为零。如果函数成功，则返回值为非零。

PQresultAlloc #

为 PGresult 对象分配辅助存储。

void *PQresultAlloc(PGresult *res, size_t nBytes);

使用此函数分配的任何内存将在清除 res 时释放。如果函数失败，返回值为 NULL。结果保证与任何类型的数据充分对齐，就像 malloc 一样。

PQresultMemorySize #

检索为 PGresult 对象分配的字节数。

size_t PQresultMemorySize(const PGresult *res);

此值为与 PGresult 对象关联的所有 malloc 请求的总和，即 PQclear 将释放的所有空间。此信息对于管理内存消耗很有用。

PQlibVersion #

返回正在使用的 libpq 版本。

int PQlibVersion(void);

此函数的结果可用于在运行时确定当前加载的 libpq 版本中是否提供特定功能。例如，此函数可用于确定 PQconnectdb 中提供了哪些连接选项。

结果是通过将库的主版本号乘以 10000 并添加次版本号形成的。例如，版本 10.1 将返回为 100001，版本 11.0 将返回为 110000。

在主版本 10 之前，PostgreSQL 使用三位版本号，其中前两部分一起表示主版本。对于这些版本，PQlibVersion 对每部分使用两位数字；例如，版本 9.1.5 将返回为 90105，版本 9.2.0 将返回为 90200。

因此，为了确定功能兼容性，应用程序应将 PQlibVersion 的结果除以 100，而不是 10000，以确定逻辑主版本号。在所有发行系列中，只有最后两位数字在次要发行版（错误修复发行版）之间有所不同。

注意

此函数出现在 PostgreSQL 版本 9.1 中，因此无法用于检测早期版本中所需的功能，因为调用它会创建对版本 9.1 或更高版本的链接依赖关系。

34.12. 其他函数# ​

注意

34.12. 其他函数#