释放由 libpq 分配的内存。

void PQfreemem(void *ptr);

释放由 libpq 分配的内存， 特别是 PQescapeByteaConn、 PQescapeBytea、 PQunescapeBytea 和 PQnotifies 分配的内存。 在 Microsoft Windows 上， 使用这个函数而非 free() 尤其重要。 这是因为在一个 DLL 中分配内存而在应用程序中释放它， 只有当 DLL 与应用程序的多线程/单线程、 release/debug 以及静态/动态标志相同时才能工作。 在非 Microsoft Windows 平台上， 这个函数与标准库函数 free() 相同。

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

void PQconninfoFree(PQconninfoOption *connOptions);

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

对此， 简单地用 PQfreemem 是不行的， 因为该数组包含对附属字符串的引用。

准备一个 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， 并且一条合适的消息被存储在连接对象中。

更改一个 PostgreSQL 密码。

PGresult *PQchangePassword(PGconn *conn, const char *user, const char *passwd);

这个函数使用 PQencryptPasswordConn 来构建并执行命令 ALTER USER ... PASSWORD '...'， 从而更改该用户的密码。 它存在的理由与 PQencryptPasswordConn 相同， 但它更方便， 因为它同时为你构建和运行该命令。 PQencryptPasswordConn 的算法参数被传入 NULL， 因此加密按照服务器的 password_encryption 设置完成。

user 和 passwd 参数分别是目标用户的 SQL 名和新的明文密码。

返回一个 PGresult 指针， 表示 ALTER USER 命令的结果； 如果该例程在发出任何命令之前失败， 则返回一个空指针。 应当调用 PQresultStatus 函数来检查返回值中是否有任何错误 （包括空指针的值， 在那种情况下它会返回 PGRES_FATAL_ERROR）。 错误细节请使用 PQerrorMessage 检索。

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

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

PQencryptPassword 是 PQencryptPasswordConn 的一个较旧的、已弃用的版本。 区别在于 PQencryptPassword 不需要连接对象， 并且总是使用 md5 作为加密算法。

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

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

这是 libpq 内部用于分配并初始化一个空的 PGresult 对象的函数。 如果无法分配内存， 这个函数返回 NULL。 它之所以被导出， 是因为一些应用程序发现自行生成结果对象 （特别是带有错误状态的对象） 很有用。 如果 conn 不为空且 status 指示一个错误， 那么指定连接的当前错误消息会被复制到该 PGresult 中。 此外， 如果 conn 不为空， 在该连接中注册的任何事件过程都会被复制到该 PGresult 中。 （它们不会收到 PGEVT_RESULTCREATE 调用， 但请参见 PQfireResultCreateEvents。） 注意， 最终应当在这个对象上调用 PQclear， 就像对 libpq 自身返回的 PGresult 一样。

为 PGresult 对象中注册的每个事件过程触发一个 PGEVT_RESULTCREATE 事件（参见 Section 32.14）。 成功时返回非零， 任何一个事件过程失败则返回零。

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

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

已经为这个对象收到过 PGEVT_RESULTCREATE 或 PGEVT_RESULTCOPY 事件的事件过程不会被再次触发。

这个函数与 PQmakeEmptyPGresult 分开的主要原因是： 在调用事件过程之前先创建一个 PGresult 并用数据填充它， 往往是合适的。

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

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

它并不预期制作一份精确的副本。 返回的结果总是被置于 PGRES_TUPLES_OK 状态， 并且不复制源中的任何错误消息。 （不过它确实会复制命令状态字符串。） flags 参数决定还复制哪些内容。 它是若干标志的按位或。 PG_COPYRES_ATTRS 指定复制源结果的属性 （列定义）。 PG_COPYRES_TUPLES 指定复制源结果的元组。 （这也意味着复制属性。） PG_COPYRES_NOTICEHOOKS 指定复制源结果的通知钩子。 PG_COPYRES_EVENTS 指定复制源结果的事件。 （但与源关联的任何实例数据不会被复制。） 事件过程会收到 PGEVT_RESULTCOPY 事件。

设置一个 PGresult 对象的属性。

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

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

设置一个 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 空值。 value 会被复制到结果的私有存储中， 因此在函数返回之后就不再需要它了。 如果该函数失败， 返回值为零。 如果该函数成功， 返回值为非零。

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

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

用这个函数分配的任何内存都会在 res 被清除时被释放。 如果该函数失败， 返回值为 NULL。 与 malloc 一样， 结果保证被充分地对齐， 可用于任何类型的数据。

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

size_t PQresultMemorySize(const PGresult *res);

这个值是与该 PGresult 对象关联的所有 malloc 请求的总和， 也就是将被 PQclear 释放的所有内存。 这项信息对管理内存消耗可能有用。

返回正在使用的 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， 以得到一个逻辑主版本号。 在所有发行系列中， 次要发行版（缺陷修复发行版）之间只有最后两位数字不同。

检索当前时间， 表示为自 Unix 纪元以来的微秒数 （即 time_t 乘以一百万）。

pg_usec_time_t PQgetCurrentTimeUSec(void);

这主要用于计算与 PQsocketPoll 一起使用的超时值。