# 34.12. Miscellaneous Functions
As always, there are some functions that just don't fit anywhere.
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()
.
Frees the data structures allocated byPQconndefaults
orPQconninfoParse
.
void PQconninfoFree(PQconninfoOption *connOptions);
A simplePQfreemem
will not do for this, since the array contains references to subsidiary strings.
Prepares the encrypted form of a PostgreSQL password.
char *PQencryptPasswordConn(PGconn *conn, const char *passwd, const char *user, const char *algorithm);
此功能旨在供希望发送命令的客户端应用程序使用更改用户乔密码'pwd'
.最好不要在此类命令中发送原始明文密码,因为它可能会暴露在命令日志、活动显示等中。相反,在发送密码之前,请使用此功能将密码转换为加密形式。
这*密码
和用户
参数是明文密码,以及它所针对的用户的 SQL 名称。算法
指定用于加密密码的加密算法。目前支持的算法是md5
和scram-sha-256
(在
和离开
也被接受为别名md5
, 为了与旧的服务器版本兼容)。请注意,支持scram-sha-256
是在 PostgreSQL 版本 10 中引入的,并且不能在旧版本的服务器上正常工作。如果算法
是空值
,此函数将向服务器查询当前值密码_加密环境。这可能会阻塞,并且如果当前事务被中止,或者如果连接正忙于执行另一个查询,则会失败。如果您希望对服务器使用默认算法但又想避免阻塞,请查询密码加密
打电话之前自己PQencryptPasswordConn
,并将该值作为算法
*.
返回值是由分配的字符串malloc
.调用者可以假设字符串不包含任何需要转义的特殊字符。采用PQfreemem
完成后释放结果。出错,返回空值
,并且合适的消息存储在连接对象中。
准备 PostgreSQL 密码的 md5 加密形式。
char *PQencryptPassword(const char *passwd, const char *user);
PQencrypt密码
是旧的,已弃用的版本PQencryptPasswordConn
.不同之处在于PQencrypt密码
不需要连接对象,并且md5
始终用作加密算法。
构造一个空的PG结果
具有给定状态的对象。
PGresult *PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status);
这是 libpq 分配和初始化一个空的内部函数PG结果
目的。这个函数返回空值
如果无法分配内存。它被导出是因为一些应用程序发现自己生成结果对象(特别是具有错误状态的对象)很有用。如果*康恩
不为空并且状态
表示错误,将指定连接的当前错误信息复制到PG结果
.另外,如果康恩
*不为空,在连接中注册的任何事件过程都被复制到PG结果
.(他们没有得到PGEVT_RESULTCREATE
打电话,但见PQfireResultCreateEvents
。) 注意PQclear
最终应该在对象上调用,就像使用PG结果
由 libpq 本身返回。
发射一个PGEVT_RESULTCREATE
事件(见第 34.14 节) 对于在PG结果
目的。返回非零表示成功,如果任何事件过程失败则返回零。
int PQfireResultCreateEvents(PGconn *conn, PGresult *res);
这康恩
参数被传递给事件过程,但不直接使用。有可能空值
如果事件程序不使用它。
已经收到的事件过程PGEVT_RESULTCREATE
或者PGEVT_RESULTCOPY
此对象的事件不会再次触发。
此功能与PQmakeEmptyPGresult
是它通常是适当的创建一个PG结果
并在调用事件过程之前用数据填充它。
制作一个副本PG结果
目的。该副本未以任何方式链接到源结果,并且PQclear
不再需要副本时必须调用。如果函数失败,空值
被退回。
PGresult *PQcopyResult(const PGresult *src, int flags);
这不是为了制作精确的副本。返回的结果总是放入PGRES_TUPLES_OK
状态,并且不会复制源中的任何错误消息。(但是,它确实复制了命令状态字符串。)*旗帜
*参数确定要复制的其他内容。它是几个标志的按位或。PG_COPYRES_ATTRS
指定复制源结果的属性(列定义)。PG_COPYRES_TUPLES
指定复制源结果的元组。(这也意味着复制属性。)PG_COPYRES_NOTICEHOOKS
指定复制源结果的通知挂钩。PG_COPYRES_EVENTS
指定复制源结果的事件。(但不会复制与源关联的任何实例数据。)
设置一个属性PG结果
目的。
int PQsetResultAttrs(PGresult *res, int numAttributes, PGresAttDesc *attDescs);
提供的*描述
被复制到结果中。如果描述
指针是空值
或者numAttributes
小于一,请求被忽略,函数成功。如果资源
*已经包含属性,该函数将失败。如果函数失败,则返回值为零。如果函数成功,则返回值非零。
设置一个元组字段值PG结果
目的。
int PQsetvalue(PGresult *res, int tup_num, int field_num, char *value, int len);
该函数将根据需要自动增长结果的内部元组数组。然而*tup_num
参数必须小于或等于元组
,这意味着此函数一次只能将元组数组增长一个元组。但是任何现有元组的任何字段都可以按任何顺序修改。如果一个值在字段编号
已经存在,它将被覆盖。如果连
是 -1 或价值
是空值
,字段值将设置为 SQL 空值。这价值
*被复制到结果的私有存储中,因此在函数返回后不再需要。如果函数失败,则返回值为零。如果函数成功,则返回值非零。
为 a 分配辅助存储PG结果
目的。
void *PQresultAlloc(PGresult *res, size_t nBytes);
使用此函数分配的任何内存都将在以下情况下被释放*资源
*被清除。如果函数失败,返回值为空值
.结果保证与任何类型的数据充分对齐,就像malloc
.
检索为 a 分配的字节数PG结果
目的。
size_t PQresultMemorySize(const PGresult *res);
这个值是所有的总和malloc
与相关的请求PG结果
对象,即所有将被释放的空间PQclear
.此信息可用于管理内存消耗。
返回正在使用的 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 或更高版本的链接依赖。