他のバージョンの文書 16 | 15 | 14 | 13 | 12 | 11 | 10 | 9.6 | 9.5 | 9.4 | 9.3 | 9.2 | 9.1 | 9.0 | 8.4 | 8.3 | 8.2 | 8.1 | 8.0 | 7.4 | 7.3 | 7.2

34.12. 雑多な関数

よくあることですが、うまく分類できない関数がいくつか存在します。

PQfreemem

libpqが割り当てたメモリを解放します。

void PQfreemem(void *ptr);

具体的にはPQescapeByteaConnPQescapeByteaPQunescapeByteaおよび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'のようなコマンドを送信したいクライアントアプリケーションで使用されることを意図したものです。 こうしたコマンドでは、コマンドログが活動の監視などで晒されてしまうため、元々の平文テキストでパスワードを送信しないことが推奨されています。 その代わりに、この関数を使用して送信前にパスワードを暗号化形式に変換してください。

passwduser引数は、関数が使用する平文のパスワードとそのSQL上のユーザ名です。 algorithmは、パスワードを暗号化するために使用する暗号化アルゴリズムを指定します。 現在サポートされているアルゴリズムは、md5scram-sha-256です。 (古いサーババージョンとの互換性のために、md5の別名として、onoffも受け付けます。) scram-sha-256のサポートは、PostgreSQLバージョン10で導入されたので、古いサーババージョンでは正しく動作しないことに注意してください。 algorithmNULLなら、この関数はサーバに問合せて現在の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、またはvalueNULLであれば、フィールドの値は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以降とのリンク依存性を作成するためです。