PostgreSQL 10.1 手册_部分 IV. 客户端接口_第 33 章 libpq - C 库_33.11. 杂项函数
33.11.?雜項(xiàng)函數(shù)
一如往常，總有一些函數(shù)不適合放在任何其他地方。
PQfreemem釋放libpq分配的內(nèi)存。
void PQfreemem(void *ptr);釋放libpq分配的內(nèi)存，尤其是PQescapeByteaConn、PQescapeBytea、PQunescapeBytea和PQnotifies分配的內(nèi)存。特別重要的是，在微軟 Windows 上使用這個(gè)函數(shù)，而不是free()。這是因?yàn)橹挥?DLL 和應(yīng)用的當(dāng)多線程/單線程、發(fā)布/調(diào)試以及靜態(tài)/動(dòng)態(tài)標(biāo)志相同時(shí)，才能在一個(gè) DLL 中分配內(nèi)存并且在應(yīng)用中釋放它。在非微軟 Windows 平臺(tái)上，這個(gè)函數(shù)與標(biāo)準(zhǔn)庫(kù)函數(shù)free()相同。
釋放PQconndefaults或PQconninfoParse分配的數(shù)據(jù)結(jié)構(gòu)。
void PQconninfoFree(PQconninfoOption *connOptions);一個(gè)簡(jiǎn)單的PQfreemem不會(huì)做這些，因?yàn)閿?shù)組包含對(duì)子字符串的引用。
準(zhǔn)備一個(gè)PostgreSQL口令的加密形式。
char *PQencryptPasswordConn(PGconn *conn, const char *passwd, const char *user, const char *algorithm);這個(gè)函數(shù)旨在用于那些希望發(fā)送類似于ALTER USER joe PASSWORD 'pwd'命令的客戶端應(yīng)用。不在這樣一個(gè)命令中發(fā)送原始的明文密碼是一個(gè)好習(xí)慣，因?yàn)樗赡鼙槐┞对诿钊罩尽⒒顒?dòng)顯示等等中。相反，在發(fā)送之前使用這個(gè)函數(shù)可以將口令轉(zhuǎn)換為加密的形式。
algorithm指定用于加密口令的加密算法。目前支持的算法是?md5和scram-sha-256，（on和off?也被接受為md5的別名，以與舊版服務(wù)器版本兼容）。 請(qǐng)注意，在PostgreSQL版本10中引入了對(duì)scram-sha-256?的支持，并且在舊版服務(wù)器版本中無(wú)法正常工作。如果algorithm?是NULL，則此函數(shù)將向服務(wù)器查詢password_encryption?設(shè)置的當(dāng)前值。如果當(dāng)前事務(wù)中止，或者連接忙于執(zhí)行另一個(gè)查詢，則可能會(huì)阻塞， 并會(huì)失敗。如果您希望服務(wù)器使用默認(rèn)算法，但希望避免阻塞， 請(qǐng)?jiān)谡{(diào)用PQencryptPasswordConn之前親自查詢?password_encryption，并將該值作為algorithm傳遞。
返回值是malloc分配的一個(gè)字符串。 調(diào)用者可以假定該字符串中不包含任何需要轉(zhuǎn)義的特殊字符。當(dāng)使用結(jié)束之后， 用PQfreemem釋放結(jié)果。錯(cuò)誤時(shí)，返回NULL， 并且一個(gè)合適的消息被存儲(chǔ)在連接對(duì)象中。
準(zhǔn)備一個(gè)PostgreSQL口令的md5加密形式。
char *PQencryptPassword(const char *passwd, const char *user);PQencryptPassword是PQencryptPasswodConn?的一個(gè)較舊的，廢棄的版本。區(qū)別在于PQencryptPassword?不需要連接對(duì)象，并且始終使用md5作為加密算法。
用給定的狀態(tài)，構(gòu)造一個(gè)空PGresult對(duì)象。
PGresult *PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status);這是libpq內(nèi)部用于分配并初始化一個(gè)空PGresult對(duì)象的函數(shù)。如果不能分配內(nèi)存，那么這個(gè)函數(shù)返回NULL。它也是可以對(duì)外使用的，因?yàn)橐恍?yīng)用認(rèn)為它可以用于產(chǎn)生結(jié)果對(duì)象（特別是帶有錯(cuò)誤狀態(tài)的對(duì)象）本身。如果conn非空，并且status表示一個(gè)錯(cuò)誤，那么指定連接的當(dāng)前錯(cuò)誤消息會(huì)被復(fù)制到PGresult中。如果conn非空，那么連接中的任何已注冊(cè)事件過(guò)程也會(huì)被復(fù)制到PGresult中（它們不會(huì)獲得PGEVT_RESULTCREATE調(diào)用，但會(huì)看到PQfireResultCreateEvents）。注意在該對(duì)象上最終應(yīng)該調(diào)用PQclear，正如對(duì)libpq本身返回的PGresult對(duì)象所作的那樣。
為每一個(gè)在PGresult對(duì)象中注冊(cè)的事件過(guò)程觸發(fā)一個(gè)PGEVT_RESULTCREATE事件（見(jiàn)第?33.13?節(jié)）。成功時(shí)返回非 0，如果任何事件過(guò)程失敗則返回 0。
int PQfireResultCreateEvents(PGconn *conn, PGresult *res);conn參數(shù)被傳送給事件過(guò)程，但不會(huì)被直接使用。如果事件過(guò)程不使用它，則會(huì)返回NULL。
已經(jīng)接收到這個(gè)對(duì)象的PGEVT_RESULTCREATE或PGEVT_RESULTCOPY事件的事件過(guò)程不會(huì)被再次觸發(fā)。
這個(gè)函數(shù)與PQmakeEmptyPGresult分開(kāi)的主要原因是在調(diào)用事件過(guò)程之前創(chuàng)建一個(gè)PGresult并且填充它常常是合適的。
為一個(gè)PGresult對(duì)象創(chuàng)建一個(gè)拷貝。這個(gè)拷貝不會(huì)以任何方式鏈接到源結(jié)果，并且當(dāng)該拷貝不再需要時(shí)，必須調(diào)用PQclear進(jìn)行清理。如果函數(shù)失敗，返回NULL。
PGresult *PQcopyResult(const PGresult *src, int flags);這個(gè)函數(shù)的意圖并非是制作一個(gè)準(zhǔn)確的拷貝。返回的結(jié)果總是會(huì)被放入PGRES_TUPLES_OK狀態(tài)，并且不會(huì)拷貝來(lái)源中的任何錯(cuò)誤消息（不過(guò)它確實(shí)會(huì)拷貝命令狀態(tài)字符串）。flags參數(shù)決定還要拷貝些什么。它通常是幾個(gè)標(biāo)志的按位 OR。PG_COPYRES_ATTRS指定復(fù)制源結(jié)果的屬性（列定義）。PG_COPYRES_TUPLES指定復(fù)制源結(jié)果的元組（這也意味著復(fù)制屬性）。PG_COPYRES_NOTICEHOOKS指定復(fù)制源結(jié)果的提醒鉤子。PG_COPYRES_EVENTS指定復(fù)制源結(jié)果的事件（但是不會(huì)復(fù)制與源結(jié)果相關(guān)的實(shí)例數(shù)據(jù)）。
設(shè)置PGresult對(duì)象的屬性。
int PQsetResultAttrs(PGresult *res, int numAttributes, PGresAttDesc *attDescs);提供的attDescs被復(fù)制到結(jié)果中。如果attDescs指針為NULL或numAttributes小于1，那么請(qǐng)求將被忽略并且函數(shù)成功。如果res已經(jīng)包含屬性，那么函數(shù)會(huì)失敗。如果函數(shù)失敗，返回值是 0。如果函數(shù)成功，返回值是非 0。
設(shè)置一個(gè)PGresult對(duì)象的一個(gè)元組域值。
int PQsetvalue(PGresult *res, int tup_num, int field_num, char *value, int len);這個(gè)函數(shù)將自動(dòng)按需增加結(jié)果的內(nèi)置元組數(shù)組。但是，tup_num參數(shù)必須小于等于PQntuples，意味著這個(gè)函數(shù)對(duì)元組數(shù)組一次只能增加一個(gè)元組。但已存在的任意元組中的任意域可以以任意順序進(jìn)行調(diào)整。如果field_num的一個(gè)值已經(jīng)存在，它會(huì)被覆蓋。如果len是 -1，或value是NULL， 該域值會(huì)被設(shè)置為一個(gè) SQL 空值。value會(huì)被復(fù)制到結(jié)果的私有存儲(chǔ)中，因此函數(shù)返回后就不再需要了。如果函數(shù)失敗，返回值是 0。如果函數(shù)成功，返回值會(huì)是非 0。
為一個(gè)PGresult對(duì)象分配附屬存儲(chǔ)。
void *PQresultAlloc(PGresult *res, size_t nBytes);當(dāng)res被清除時(shí)，這個(gè)函數(shù)分配的內(nèi)存也會(huì)被釋放掉。如果函數(shù)失敗，返回值是NULL。結(jié)果被保證為按照數(shù)據(jù)的任意類型充分地對(duì)齊，正如malloc所作的。
返回所使用的libpq版本。
int PQlibVersion(void);在運(yùn)行時(shí)，這個(gè)函數(shù)的結(jié)果可以被用來(lái)決定在當(dāng)前已載入的 libpq 版本中特定的功能是否可用。 例如，這個(gè)函數(shù)可以被用來(lái)決定哪些選項(xiàng)可以被用于PQconnectdb。
結(jié)果是通過(guò)將庫(kù)的主要版本號(hào)乘以10000并添加次要版本號(hào)形成的。 例如，版本10.1將返回100001，版本11.0將返回110000。如果連接不正確，則返回零。
在主版本10之前，PostgreSQL使用三部分版本號(hào)， 前兩部分代表主要版本。對(duì)于這些版本，PQserverVersion?對(duì)每個(gè)部分使用兩個(gè)數(shù)字；例如版本9.1.5將返回90105，版本9.2.0將返回90200。
因此，為確定功能兼容性，應(yīng)用程序應(yīng)將PQserverVersion?的結(jié)果除以100而不是10000，以確定邏輯主要版本號(hào)。在所有發(fā)行版系列中， 只有最后兩位數(shù)字在次版本（錯(cuò)誤修復(fù)版本）之間有所不同。
注意
這個(gè)函數(shù)出現(xiàn)于PostgreSQL版本 9.1，因此它不能被用來(lái)在早期的版本中檢測(cè)所需的功能，因?yàn)檎{(diào)用它將會(huì)創(chuàng)建一個(gè)對(duì)版本 9.1 或更高版本的鏈接依賴。
本文轉(zhuǎn)自PostgreSQL中文社區(qū)，原文鏈接：33.11.?雜項(xiàng)函數(shù)
總結(jié)
以上是生活随笔為你收集整理的PostgreSQL 10.1 手册_部分 IV. 客户端接口_第 33 章 libpq - C 库_33.11. 杂项函数的全部?jī)?nèi)容，希望文章能夠幫你解決所遇到的問(wèn)題。
- 上一篇： Tomcat启动过程源码解读
- 下一篇： WebAssembly 技术汇总