33.11. 杂项函数

一如往常,总有一些函数不适合放在任何其他地方。

PQfreemem

释放libpq分配的内存。

void PQfreemem(void *ptr);

释放libpq分配的内存,尤其是PQescapeByteaConnPQescapeByteaPQunescapeByteaPQnotifies分配的内存。特别重要的是,在微软 Windows 上使用这个函数,而不是free()。这是因为只有 DLL 和应用的当多线程/单线程、发布/调试以及静态/动态标志相同时,才能在一个 DLL 中分配内存并且在应用中释放它。在非微软 Windows 平台上,这个函数与标准库函数free()相同。

PQconninfoFree

释放PQconndefaultsPQconninfoParse分配的数据结构。

void PQconninfoFree(PQconninfoOption *connOptions);

一个简单的PQfreemem不会做这些,因为数组包含对子字符串的引用。

PQencryptPasswordConn

准备一个PostgreSQL口令的加密形式。

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

这个函数旨在用于那些希望发送类似于ALTER USER joe PASSWORD 'pwd'命令的客户端应用。不在这样一个命令中发送原始的明文密码是一个好习惯,因为它可能被暴露在命令日志、活动显示等等中。相反,在发送之前使用这个函数可以将口令转换为加密的形式。

algorithm指定用于加密口令的加密算法。目前支持的算法是 md5scram-sha-256,(onoff 也被接受为md5的别名,以与旧版服务器版本兼容)。 请注意,在PostgreSQL版本10中引入了对scram-sha-256 的支持,并且在旧版服务器版本中无法正常工作。如果algorithmNULL,则此函数将向服务器查询password_encryption 设置的当前值。如果当前事务中止,或者连接忙于执行另一个查询,则可能会阻塞, 并会失败。如果您希望服务器使用默认算法,但希望避免阻塞, 请在调用PQencryptPasswordConn之前亲自查询 password_encryption,并将该值作为algorithm传递。

返回值是malloc分配的一个字符串。 调用者可以假定该字符串中不包含任何需要转义的特殊字符。当使用结束之后, 用PQfreemem释放结果。错误时,返回NULL, 并且一个合适的消息被存储在连接对象中。

PQencryptPassword

准备一个PostgreSQL口令的md5加密形式。

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

PQencryptPasswordPQencryptPasswodConn 的一个较旧的,废弃的版本。区别在于PQencryptPassword 不需要连接对象,并且始终使用md5作为加密算法。

PQmakeEmptyPGresult

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

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

这是libpq内部用于分配并初始化一个空PGresult对象的函数。如果不能分配内存,那么这个函数返回NULL。它也是可以对外使用的,因为一些应用认为它可以用于产生结果对象(特别是带有错误状态的对象)本身。如果conn非空,并且status表示一个错误,那么指定连接的当前错误消息会被复制到PGresult中。如果conn非空,那么连接中的任何已注册事件过程也会被复制到PGresult中(它们不会获得PGEVT_RESULTCREATE调用,但会看到PQfireResultCreateEvents)。注意在该对象上最终应该调用PQclear,正如对libpq本身返回的PGresult对象所作的那样。

PQfireResultCreateEvents

为每一个在PGresult对象中注册的事件过程触发一个PGEVT_RESULTCREATE事件(见第 33.13 节)。成功时返回非 0,如果任何事件过程失败则返回 0。

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

conn参数被传送给事件过程,但不会被直接使用。如果事件过程不使用它,则会返回NULL

已经接收到这个对象的PGEVT_RESULTCREATEPGEVT_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指定复制源结果的事件(但是不会复制与源结果相关的实例数据)。

PQsetResultAttrs

设置PGresult对象的属性。

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

提供的attDescs被复制到结果中。如果attDescs指针为NULLnumAttributes小于1,那么请求将被忽略并且函数成功。如果res已经包含属性,那么函数会失败。如果函数失败,返回值是 0。如果函数成功,返回值是非 0。

PQsetvalue

设置一个PGresult对象的一个元组域值。

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

这个函数将自动按需增加结果的内置元组数组。但是,tup_num参数必须小于等于PQntuples,意味着这个函数对元组数组一次只能增加一个元组。但已存在的任意元组中的任意域可以以任意顺序进行调整。如果field_num的一个值已经存在,它会被覆盖。如果len是 -1,或valueNULL, 该域值会被设置为一个 SQL 空值。value会被复制到结果的私有存储中,因此函数返回后就不再需要了。如果函数失败,返回值是 0。如果函数成功,返回值会是非 0。

PQresultAlloc

为一个PGresult对象分配附属存储。

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

res被清除时,这个函数分配的内存也会被释放掉。如果函数失败,返回值是NULL。结果被保证为按照数据的任意类型充分地对齐,正如malloc所作的。

PQlibVersion

返回所使用的libpq版本。

int PQlibVersion(void);

在运行时,这个函数的结果可以被用来决定在当前已载入的 libpq 版本中特定的功能是否可用。 例如,这个函数可以被用来决定哪些选项可以被用于PQconnectdb

结果是通过将库的主要版本号乘以10000并添加次要版本号形成的。 例如,版本10.1将返回100001,版本11.0将返回110000。如果连接不正确,则返回零。

在主版本10之前,PostgreSQL使用三部分版本号, 前两部分代表主要版本。对于这些版本,PQserverVersion 对每个部分使用两个数字;例如版本9.1.5将返回90105,版本9.2.0将返回90200。

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

注意

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