よくあることですが、うまく分類できない関数がいくつか存在します。
PQfreemem
libpqが割り当てたメモリを解放します。
void PQfreemem(void *ptr);
具体的にはPQescapeByteaConn
、PQescapeBytea
、PQunescapeBytea
およびPQnotifies
によりlibpqが割り当てたメモリを解放します。
Microsoft Windowsにおいてfree()
ではなく、この関数を使用することが特に重要です。
DLLにおけるメモリ割り当てとアプリケーションにおけるその解放が、DLLとアプリケーションとでマルチスレッド/シングルスレッド、リリース用/デバッグ用、静的/動的フラグが同じ場合でのみ動作するためです。
Microsoft Windowsプラットフォーム以外では、この関数は標準ライブラリのfree()
関数と同じです。
PQconninfoFree
PQconndefaults
もしくはPQconninfoParse
が割り当てたデータ構造を解放します。
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'
のようなコマンドを送信したいクライアントアプリケーションで使用されることを意図したものです。
こうしたコマンドでは、コマンドログが活動の監視などで晒されてしまうため、元々の平文テキストでパスワードを送信しないことが推奨されています。
その代わりに、この関数を使用して送信前にパスワードを暗号化形式に変換してください。
passwd
とuser
引数は、関数が使用する平文のパスワードとそのSQL上のユーザ名です。
algorithm
は、パスワードを暗号化するために使用する暗号化アルゴリズムを指定します。
現在サポートされているアルゴリズムは、md5
とscram-sha-256
です。
(古いサーババージョンとの互換性のために、md5
の別名として、on
とoff
も受け付けます。)
scram-sha-256
のサポートは、PostgreSQLバージョン10で導入されたので、古いサーババージョンでは正しく動作しないことに注意してください。
algorithm
がNULL
なら、この関数はサーバに問合せて現在のpassword_encryption設定を返します。
これは、ブロックする可能性があり、また現在のトランザクションがアボートしているか、あるいは他の問合せを実行中でビジーなら失敗します。
サーバのデフォルトアルゴリズムを使用したいが、ブロックは避けたい、という場合は、PQencryptPasswordConn
を呼び出す前にpassword_encryption
を自分で調べ、その値をalgorithm
に渡してください。
戻り値はmalloc
で割り当てられた文字列です。
呼び出し元は、その文字列にエスケープしなければならない特殊な文字列が含まれていないことを仮定することができます。
処理が終わった時にPQfreemem
を使用して結果を解放してください。
エラーの場合にNULL
が返され、接続オブジェクトに対応するメッセージが格納されます。
PQencryptPassword
md5暗号化形式のPostgreSQLパスワードを準備します。
char *PQencryptPassword(const char *passwd, const char *user);
PQencryptPassword
は、古くて非推奨のバージョンのPQencryptPasswordConn
です。
違いは、PQencryptPassword
はコネクションオブジェクトを必要とせず、md5
が常に暗号化アルゴリズムに使用されることです。
PQmakeEmptyPGresult
与えられたステータスで空のPGresult
オブジェクトを構築します。
PGresult *PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status);
これは空のPGresult
オブジェクトを割り当てて、初期化するlibpqの内部関数です。
メモリが割り当てられなかった場合、この関数はNULL
を返します。
一部のアプリケーションで結果オブジェクト(特にエラーステータスを伴ったオブジェクト)それ自身を生成することが便利であることが分かりましたので、外部公開されました。
conn
が非NULで、status
がエラーを示唆している場合、特定された接続の現在のエラーメッセージはPGresult
にコピーされます。
同時に、conn
が非NULLの場合、接続で登録された任意のイベントプロシージャはPGresult
にコピーされます。
(それらはPGEVT_RESULTCREATE
呼び出しを受けませんが、PQfireResultCreateEvents
を理解します。)
libpq自身で返されたPGresult
と同様に、最終的にはこのオブジェクトに対してPQclear
を呼び出さなければならないことに注意してください。
PQfireResultCreateEvents
PGresult
オブジェクトに登録されたそれぞれのイベントプロシージャに対し、PGEVT_RESULTCREATE
イベント(34.14を参照)を発行します。
イベントプロシージャが成功の場合は非ゼロ、失敗の場合はゼロを返します。
int PQfireResultCreateEvents(PGconn *conn, PGresult *res);
conn
引数はイベントプロシージャに渡されますが、直接には使用されません。
イベントプロシージャが使用しない場合はNULL
で構いません。
このオブジェクトに対し、PGEVT_RESULTCREATE
もしくはPGEVT_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
ポインタがNULL
、またはnumAttributes
が1未満の場合、要求は無視され、関数は成功します。
res
が既に属性を所有している場合、関数は失敗に終わります。
関数が失敗すると、戻り値はゼロです。
関数が成功すると戻り値は非ゼロになります。
PQsetvalue
PGresult
オブジェクトのタプルフィールド値を設定します。
int PQsetvalue(PGresult *res, int tup_num, int field_num, char *value, int len);
必要に応じて関数は自動的に結果の内部タプル配列を肥大化させます。
しかし、tup_num
引数はPQntuples
と同じか、もしくは小さくなければなりません。
その意味は、この関数は一回にタプル配列を1タプル大きくさせるだけだからです。
とは言っても、存在するいかなるタプルの任意のフィールドも、順序を問わず変更できます。
もしfield_num
に値が既に存在すれば、書き換えられます。
len
が-1、またはvalue
がNULL
であれば、フィールドの値はSQLのNULLに設定されます。
value
は結果のプライベート格納領域にコピーされるため、関数が返った後ではもう必要がなくなります。
関数が失敗すると、戻り値はゼロです。
関数が成功すると戻り値は非ゼロになります。
PQresultAlloc
PGresult
オブジェクトに補助ストレージを割り当てます。
void *PQresultAlloc(PGresult *res, size_t nBytes);
res
が消去された時、この関数で割り付けられたメモリは解放されます。
関数が失敗すると戻り値はNULL
です。
malloc
と同じように、どのような種類のデータでも結果は適切に整列されることが保証されています。
PQresultMemorySize
PGresult
オブジェクトのために割り当てられたバイト数を取り出します。
size_t PQresultMemorySize(const PGresult *res);
この値はPGresult
オブジェクトに関連するmalloc
要求すべての和、すなわちPQclear
で解放される空間全体です。
この情報はメモリ消費を管理するのに有用でしょう。
PQlibVersion
使用中のlibpqのバージョンを返します。
int PQlibVersion(void);
この関数の結果を使用して、現在読み込まれているバージョンのlibpqで特定の機能が利用可能かどうかを実行時に決定することができます。
例えばこの関数を使用して、PQconnectdb
でどの接続オプションが利用できるかを確認することができます。
返却値の形式は、メジャーバージョン番号に10000を掛け、マイナーバージョン番号を加えたものです。 例えば、バージョン10.1では100001を返し、バージョン11.0では110000を返します。
バージョン10よりも前では、PostgreSQLでは、最初の2つの部分がメジャーバージョンを表す、3つの部分からなるバージョン番号が使われていました。
これらのバージョンでは、PQlibVersion
はそれぞれの部分に2桁の数字を使います。
たとえば、バージョン9.1.5では90105が返され、バージョン9.2.0では90200が返されます。
ですから、機能の互換性を見極めるのが目的なら、アプリケーションはPQlibVersion
の結果を10000ではなく、100で割り、論理的なメジャーバージョンを求めるべきです。
すべてのリリースで、最後の2桁だけがマイナーリリースで異なります。
(バグ修正リリースです。)
この関数はPostgreSQLバージョン9.1で追加されました。 このため以前のバージョンにおいて要求される機能を検知するために使用することができません。 この関数の呼び出しがバージョン9.1以降とのリンク依存性を作成するためです。