30.10. 雑多な関数

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

       void PQfreemem(void *ptr);
      

特に PQescapeByteaConn、 PQescapeBytea、 PQunescapeBytea、 およびPQnotifiesによりlibpqが割り当てたメモリーを解放します。

PQconndefaultsもしくはPQconninfoParseが割り当てたデータ構造を開放します。

       void PQconninfoFree(PQconninfoOption *connOptions);
      

単純なPQfreememは、配列が補助文字列への参照を含んでいることから、このためには作業しません。

PostgreSQLパスワードの暗号化された形式を準備します。

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

この関数は、ALTER USER joe PASSWORD 'pwd'のようなコマンドを送信したいクライアントアプリケーションで使用されることを意図したものです。 こうしたコマンドでは、コマンドログが活動の監視などで晒されてしまうため、元々の平文テキストでパスワードを送信しないことが推奨されています。 その代わりに、この関数を使用して送信前にパスワードを暗号化形式に変換してください。 引数は平文のパスワードとそのSQL上のユーザ名です。 戻り値はmallocで割り当てられた文字列です。 メモリ不足の場合にNULLが返されます。 呼び出し元は、その文字列にエスケープしなければならない特殊な文字列が含まれていないことを仮定することができます。 処理が終わった時にPQfreememを使用して結果を解放してください。

与えられたステータスで空のPGresultオブジェクトを構築します。

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

これは空のPGresultオブジェクトを割り当てて、初期化するlibpqの内部関数です。メモリーが割り当てられなかった場合、この関数はNULLを返します。結果オブジェクト（特にエラーステータスを伴ったオブジェクト）それ自身をアプリケーションが生成するのに便利なため保存されました。connが非NULLで、statusがエラーを示唆している場合、特定された接続の現在のエラーメッセージはPGresultに複写されます。同時に、connが非NULLの場合、接続で登録されたどんなイベントプロシージャであってもPGresultに複写されます。（それらはPGEVT_RESULTCREATE呼び出しを受けませんが、PQfireResultCreateEventsを理解します。）libpq自身で返されたPGresultによるのと同じに、PQclearはそのオブジェクト上で結局のところ呼ばれることに注意してください。

PGresultオブジェクトに登録されたそれぞれのイベントプロシージャに対し、PGEVT_RESULTCREATEイベント（項30.12を参照）を立ち上げます。イベントプロシージャが成功の場合は非ゼロ、失敗の場合はゼロを返します。

       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引数はそのほかに複写するものがないかを決定します。それは幾つかのフラグのビット単位のORです。PG_COPYRES_ATTRSはソース結果の属性（列定義）の複写を指定します。PG_COPYRES_TUPLESはソースタプルの結果の複写を指定します。（これは属性も複写することを意味しています。）PG_COPYRES_NOTICEHOOKSはソース結果の警告フックの複写を指定します。PG_COPYRES_EVENTSはソース結果イベントの複写を指定します。（しかし、ソースに連携したどんなインスタンスデータも複写されません。）

PGresultオブジェクトの属性を設定します。

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

提供されたattDescsは結果に複写されます。もしattDescsポインタがNULL、またはnumAttributesが１未満の場合、要求は無視され、関数は成功します。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のNULLに設定されます。valueは結果の私的ストレージに複写されるため、関数が返った後ではもう必要がなくなります。関数が失敗すると、戻り値はゼロです。関数が成功すると戻り値は非ゼロになります。

PGresultオブジェクトに補助ストレージを割り当てます。

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

resが除去されたとき、この関数で割り付けられたメモリは解放されます。 関数が失敗すると戻り値はNULLです。 mallocに対するのと同じように、どのような種類のデータでも結果は適切に整列されることが保証されています。