# 34.12. Miscellaneous Functions

As always, there are some functions that just don't fit anywhere.

PQfreemem

Frees memory allocated by libpq.

void PQfreemem(void *ptr);

Frees memory allocated by libpq, particularlyPQescapeByteaConn,PQescapeBytea,PQunescapeBytea, andPQnotifies. It is particularly important that this function, rather thanfree(), be used on Microsoft Windows. This is because allocating memory in a DLL and releasing it in the application works only if multithreaded/single-threaded, release/debug, and static/dynamic flags are the same for the DLL and the application. On non-Microsoft Windows platforms, this function is the same as the standard library functionfree().

PQconninfoFree

Frees the data structures allocated byPQconndefaultsorPQconninfoParse.

void PQconninfoFree(PQconninfoOption *connOptions);

A simplePQfreememwill not do for this, since the array contains references to subsidiary strings.

PQencryptPasswordConn

Prepares the encrypted form of a PostgreSQL password.

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

此功能旨在供希望发送命令的客户端应用程序使用更改用户乔密码'pwd'.最好不要在此类命令中发送原始明文密码,因为它可能会暴露在命令日志、活动显示等中。相反,在发送密码之前,请使用此功能将密码转换为加密形式。

这*密码用户参数是明文密码,以及它所针对的用户的 SQL 名称。算法指定用于加密密码的加密算法。目前支持的算法是md5scram-sha-256(离开也被接受为别名md5, 为了与旧的服务器版本兼容)。请注意,支持scram-sha-256是在 PostgreSQL 版本 10 中引入的,并且不能在旧版本的服务器上正常工作。如果算法空值,此函数将向服务器查询当前值密码_加密环境。这可能会阻塞,并且如果当前事务被中止,或者如果连接正忙于执行另一个查询,则会失败。如果您希望对服务器使用默认算法但又想避免阻塞,请查询密码加密打电话之前自己PQencryptPasswordConn,并将该值作为算法*.

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

PQencrypt密码

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

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

PQencrypt密码是旧的,已弃用的版本PQencryptPasswordConn.不同之处在于PQencrypt密码不需要连接对象,并且md5始终用作加密算法。

PQmakeEmptyPGresult

构造一个空的PG结果具有给定状态的对象。

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

这是 libpq 分配和初始化一个空的内部函数PG结果目的。这个函数返回空值如果无法分配内存。它被导出是因为一些应用程序发现自己生成结果对象(特别是具有错误状态的对象)很有用。如果*康恩不为空并且状态表示错误,将指定连接的当前错误信息复制到PG结果.另外,如果康恩*不为空,在连接中注册的任何事件过程都被复制到PG结果.(他们没有得到PGEVT_RESULTCREATE打电话,但见PQfireResultCreateEvents。) 注意PQclear最终应该在对象上调用,就像使用PG结果由 libpq 本身返回。

PQfireResultCreateEvents

发射一个PGEVT_RESULTCREATE事件(见第 34.14 节) 对于在PG结果目的。返回非零表示成功,如果任何事件过程失败则返回零。

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

康恩参数被传递给事件过程,但不直接使用。有可能空值如果事件程序不使用它。

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

此功能与PQmakeEmptyPGresult是它通常是适当的创建一个PG结果并在调用事件过程之前用数据填充它。

PQcopyResult

制作一个副本PG结果目的。该副本未以任何方式链接到源结果,并且PQclear不再需要副本时必须调用。如果函数失败,空值被退回。

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

这不是为了制作精确的副本。返回的结果总是放入PGRES_TUPLES_OK状态,并且不会复制源中的任何错误消息。(但是,它确实复制了命令状态字符串。)*旗帜*参数确定要复制的其他内容。它是几个标志的按位或。PG_COPYRES_ATTRS指定复制源结果的属性(列定义)。PG_COPYRES_TUPLES指定复制源结果的元组。(这也意味着复制属性。)PG_COPYRES_NOTICEHOOKS指定复制源结果的通知挂钩。PG_COPYRES_EVENTS指定复制源结果的事件。(但不会复制与源关联的任何实例数据。)

PQsetResultAttrs

设置一个属性PG结果目的。

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

提供的*描述被复制到结果中。如果描述指针是空值或者numAttributes小于一,请求被忽略,函数成功。如果资源*已经包含属性,该函数将失败。如果函数失败,则返回值为零。如果函数成功,则返回值非零。

PQset值

设置一个元组字段值PG结果目的。

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

该函数将根据需要自动增长结果的内部元组数组。然而*tup_num参数必须小于或等于元组,这意味着此函数一次只能将元组数组增长一个元组。但是任何现有元组的任何字段都可以按任何顺序修改。如果一个值在字段编号已经存在,它将被覆盖。如果是 -1 或价值空值,字段值将设置为 SQL 空值。这价值*被复制到结果的私有存储中,因此在函数返回后不再需要。如果函数失败,则返回值为零。如果函数成功,则返回值非零。

PQresultAlloc

为 a 分配辅助存储PG结果目的。

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

使用此函数分配的任何内存都将在以下情况下被释放*资源*被清除。如果函数失败,返回值为空值.结果保证与任何类型的数据充分对齐,就像malloc.

PQresultMemorySize

检索为 a 分配的字节数PG结果目的。

size_t PQresultMemorySize(const PGresult *res);

这个值是所有的总和malloc与相关的请求PG结果对象,即所有将被释放的空间PQclear.此信息可用于管理内存消耗。

PQlib版本

返回正在使用的 libpq 版本。

int PQlibVersion(void);

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

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

在主要版本 10 之前,PostgreSQL 使用三部分版本号,其中前两部分一起代表主要版本。对于那些版本,PQlib版本每个部分使用两位数字;例如版本 9.1.5 将返回为 90105,版本 9.2.0 将返回为 90200.

因此,为了确定功能兼容性,应用程序应该划分结果PQlib版本通过 100 而不是 10000 来确定逻辑主版本号。在所有版本系列中,次要版本(错误修复版本)之间只有最后两位数不同。

# 笔记

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