コマンドをサーバに送信し、結果を待機します。

PGresult *PQexec(PGconn *conn, const char *command);

戻り値はPGresultへのポインタ、場合によってはNULLポインタです。 メモリ不足の状態、あるいはサーバへのコマンド送信が不可能といった深刻なエラーの場合を除けば、通常非NULLのポインタが返ります。 PQresultStatus関数を呼び出して、何かエラー（NULLポインタ値を含むエラー。この場合はPGRES_FATAL_ERRORが返されます）がないか戻り値を検査しなければなりません。 こうしたエラーの詳しい情報は PQerrorMessage で得ることができます。

サーバにコマンドを送信し、結果を待ちます。 ただし、SQLコマンドテキストとは別にパラメータを渡すことができます。

PGresult *PQexecParams(PGconn *conn,
                       const char *command,
                       int nParams,
                       const Oid *paramTypes,
                       const char * const *paramValues,
                       const int *paramLengths,
                       const int *paramFormats,
                       int resultFormat);

PQexecParamsとPQexecは似ていますが、前者は次の機能が追加されています。 パラメータ値をコマンド文字列とは別に適切に指定することができ、また、問い合わせの結果をテキスト書式としてでもバイナリ書式としてでも要求できます。

この関数の引数を以下に示します。

指定パラメータを持つ準備された文の作成要求を送信し、その完了を待ちます。

PGresult *PQprepare(PGconn *conn,
                    const char *stmtName,
                    const char *query,
                    int nParams,
                    const Oid *paramTypes);

PQprepareは、後でPQexecPreparedを使用して実行する準備された文を作成します。 この機能を使用すると、コマンドを実行の度に解析して計画することなく、繰り返し実行することができます。 詳しくはPREPAREを参照してください。

この関数はquery文字列からstmtNameという名前の準備された文を作成します。 queryは単一のSQLコマンドでなければなりません。 stmtNameを""にして、無名の文を作成することができます。 もし、無名の文が既に存在していた場合は自動的に置き換えられます。 その他の場合、文の名前が現在のセッションで既に存在するとエラーになります。 何らかのパラメータが使用される場合、問い合わせ内では$1、$2などで参照します。 nParamsはパラメータ数です。 その型については事前にparamTypes[]配列で指定されています。 (nParamsがゼロの場合、この配列ポインタはNULLにすることができます。) paramTypes[]は、OIDによりパラメータシンボルに割り当てるデータ型を指定します。 paramTypesがNULLの場合、もしくは、配列内の特定要素がゼロの場合、サーバはそのパラメータシンボルに対して、型指定の無いリテラル文字列に対する処理と同等の方法でデータ型を割り当てます。 また、問い合わせではnParamsより多くのパラメータシンボルを使用することができます。 これらのシンボルに対するデータ型も同様に推測されます。 （どのようなデータ型が推測されるかを検出する手法についてはPQdescribePreparedを参照してください。）

PQexec同様、結果は通常PGresultオブジェクトで、その内容でサーバ側の成功や失敗を示します。 NULLという結果はメモリ不足や全くコマンドを送信することができなかったことを示します。 こうしたエラーの詳細情報を入手するには PQerrorMessage を使用してください。

指定パラメータによる準備された文の実行要求を送信し、結果を待ちます。

PGresult *PQexecPrepared(PGconn *conn,
                         const char *stmtName,
                         int nParams,
                         const char * const *paramValues,
                         const int *paramLengths,
                         const int *paramFormats,
                         int resultFormat);

PQexecPreparedとPQexecParamsは似ていますが、前者では実行されるコマンドは、問い合わせ文字列を与えるのではなく、事前に準備された文を指名することで指定されます。 この機能により、繰り返し使用する予定のコマンドを実行する度にではなく、一度だけ解析、計画作成を行うことができます。 この文は現在のセッションで事前に準備されていなければなりません。

パラメータは、問い合わせ文字列ではなく指定された準備された文の名前を与える点を除き、PQexecParamsと同じです。 また、paramTypes[]パラメータは存在しません。 (準備された文のパラメータ型はその作成時点で決定されているため、これは不要です。)

指定した準備された文に関する情報入手要求を送り、入手完了まで待機します。

PGresult *PQdescribePrepared(PGconn *conn, const char *stmtName);

PQdescribePreparedにより、アプリケーションは事前に準備された文に関する情報を入手できます。

stmtNameを""またはNULLとすることで、無名の文を参照することができます。 これ以外では、存在する準備された文の名前でなければなりません。 成功すると、PGRES_COMMAND_OKというステータスのPGresultが返されます。 PQnparamsおよびPQparamtype関数をこのPGresultに適用して、準備された文のパラメータに関する情報を得ることができます。 また、PQnfields、PQfname、PQftype関数などを使用して、文の結果列（もしあれば）に関する情報を提供できます。

指定したポータルに関する情報入手要求を送信し、完了まで待機します。

PGresult *PQdescribePortal(PGconn *conn, const char *portalName);

PQdescribePortalにより、アプリケーションは事前に作成されたポータルの情報を入手することができます。 （libpqはポータルへの直接アクセスする方法を提供していませんが、この関数を使用してDECLARE CURSOR SQLコマンドで作成したカーソルの属性を確認することができます。）

portalNameに""またはNULLを指定して、無名のポータルを参照することができます。 これ以外では、既存のポータルの名前でなければなりません。 成功すると、PGRES_COMMAND_OKというステータスのPGresultが返されます。 PQnfields、PQfname、PQftype関数などをこのPGresultに適用して、ポータルの結果列（もしあれば）に関する情報を得ることができます。

指定した準備された文をクローズする要求を送信し、完了を待機します。

PGresult *PQclosePrepared(PGconn *conn, const char *stmtName);

PQclosePreparedを使用すると、アプリケーションは以前に作られた準備された文を閉じることができます。 文を閉じると、サーバ上の関連するすべてのリソースが解放され、その名前を再利用できるようになります。

stmtNameは""またはNULLで、名前のない文を参照できます。 この名前がついた文は存在しなくてもよく、この場合は何も操作は行われません。 成功した場合、ステータスPGRES_COMMAND_OKを持つPGresultが返されます。

指定されたポータルを閉じる要求を送信し、完了を待機します。

PGresult *PQclosePortal(PGconn *conn, const char *portalName);

PQclosePortalを使用すると、アプリケーションは以前に作成したポータルを閉じることができます。 ポータルを閉じると、サーバ上の関連するすべてのリソースが解放され、その名前を再利用できるようになります。 （libpqはポータルへの直接アクセスを提供しませんが、この関数を使用してDECLARE CURSORSQLコマンドで作成されたカーソルを閉じることができます。）

portalNameは""またはNULLで、名前のないポータルを参照できます。 この名前のポータルが存在しない場合は、操作は何も行われません。 成功した場合、ステータスPGRES_COMMAND_OKを持つPGresultが返されます。

コマンドの結果状態を返します。

ExecStatusType PQresultStatus(const PGresult *res);

PQresultStatusは以下のいずれかの値を返します。

結果の状態がPGRES_TUPLES_OK、PGRES_SINGLE_TUPLE、またはPGRES_TUPLES_CHUNKの場合、以下に説明する関数を使用して、問い合わせによって返された行を取り出すことができます。 ただし、たまたまSELECTコマンドが返す行が０個だったような場合でもPGRES_TUPLES_OKとなることに注意してください。 PGRES_COMMAND_OKは、行を決して返さない(RETURNING句の無いINSERTまたはUPDATEなど)コマンド用です。 PGRES_EMPTY_QUERYという応答はクライアントソフトウェアの不具合を示しているかもしれません。

PGRES_NONFATAL_ERROR状態の場合、結果はPQexecや他の問い合わせ実行関数によって直接返されません。 その代わりに、この種の結果は注意喚起プロセッサ(32.13を参照)に渡されます。

PQresultStatusが返す列挙型から状態コードを説明する文字列定数に変換します。 呼び出し元はこの結果を解放してはいけません。

char *PQresStatus(ExecStatusType status);

コマンドに関するエラーメッセージを返します。 エラーが何もなければ、空の文字列を返します。

char *PQresultErrorMessage(const PGresult *res);

エラーがあった場合、返される文字列の最後には改行が含まれます。 呼び出し元はこの結果を直接解放してはいけません。 関連するPGresultハンドルがPQclearに渡された時にこれは解放されます。

（接続に対する） PQerrorMessage も、PQexecまたはPQgetResult呼び出しの直後なら（結果に対する）PQresultErrorMessageと同じ文字列を返します。 しかし、接続に対するエラーメッセージは続いて操作を行うと変化してしまうのに対し、PGresultは自身が破棄されるまでそのエラーメッセージを維持し続けます。 このPQresultErrorMessageは個々のPGresultに結び付けられた状態を確認する時に、そして PQerrorMessage は接続における最後の操作の状態を確認する時に使用してください。

PGresultオブジェクトに関連したエラーメッセージの再フォーマットしたバージョンを返します。

char *PQresultVerboseErrorMessage(const PGresult *res,
                                  PGVerbosity verbosity,
                                  PGContextVisibility show_context);

状況によっては、クライアントは以前に報告されたエラーのより詳細なバージョンを取得したいと思うかもしれません。 PQresultVerboseErrorMessageは、指定のPGresultが生成されたときに、指定した冗長設定がその接続で使われていたならPQresultErrorMessageが生成したであろうメッセージを計算することで、この要請に応えます。 PGresultがエラーの結果ではない場合は、「PGresult is not an error result」が代わりに報告されます。 返される文字列は行末に改行コードが含まれます。

PGresultからデータを抽出する他の多くの関数と異なり、この関数の結果は新しく割り当てられた文字列です。 その文字列が必要なくなったときは、呼び出し側がPQfreemem()を使ってそれを解放しなければなりません。

十分なメモリがないときは、NULLが返されることもありえます。

エラー報告の個々のフィールドを返します。

char *PQresultErrorField(const PGresult *res, int fieldcode);

fieldcodeはエラーフィールド識別子です。 以下に示すシンボルを参照してください。 PGresultがエラーではない、もしくは、警告付きの結果である場合や指定したフィールドを含まない場合、NULLが返されます。 通常フィールド値には改行が含まれません。 フィールド値は関連するPGresultハンドルがPQclearに渡された時に解放されます。

以下のフィールドコードが使用できます。

表示情報の必要に応じた整形はクライアントの責任です。 具体的には、必要に応じて長い行を分割しなければなりません。 エラーメッセージフィールド内の改行文字は、改行としてではなく段落として分かれたものとして取扱うべきです。

libpqで内部的に生成されたエラーは、深刻度と主要メッセージを持ちますが、通常は他のフィールドを持ちません。

エラーフィールドはPGresultからのみ利用でき、PGconnからは利用できません。 PQerrorFieldという関数はありません。

PGresultに割り当てられた記憶領域を解放します。 個々の問い合わせ結果は、必要なくなった時にPQclearで解放するべきです。

void PQclear(PGresult *res);

引数がNULLポインタの場合、操作は実行されません。

PGresultオブジェクトは必要な間保持することができます。 新しい問い合わせを発行する場合でも、接続を閉じてしまうまではPGresultは消えません。 PGresultを解放するには、PQclearを呼び出さなくてはいけません。 その操作に失敗してしまうと、アプリケーションのメモリリークを引き起こしてしまいます。

問い合わせ結果内の行(タプル)数を返します。 （ PGresultオブジェクトはINT_MAX行に制限されているため、intの結果で十分です。）

int PQntuples(const PGresult *res);

問い合わせ結果の各行の列(フィールド)の数を返します。

int PQnfields(const PGresult *res);

指定した列番号に対応する列の名前を返します。 列番号は0から始まります。 呼び出し元はこの結果を直接解放してはいけません。 関連するPGresultハンドルがPQclearに渡された時にこれは解放されます。

char *PQfname(const PGresult *res,
              int column_number);

列番号が範囲外であった場合、NULLが返ります。

指定した列名に関連する列番号を返します。

int PQfnumber(const PGresult *res,
              const char *column_name);

指定した名前に一致する列がなければ、-1が返ります。

指定した名前はSQLコマンドの識別子同様に扱われます。 つまり、二重引用符でくくられていない限り、小文字化されます。 例えば、以下のSQLで生成された問い合わせ結果を考えます。

SELECT 1 AS FOO, 2 AS "BAR";

以下により、結果を取り出すことができます。

PQfname(res, 0)              foo
PQfname(res, 1)              BAR
PQfnumber(res, "FOO")        0
PQfnumber(res, "foo")        0
PQfnumber(res, "BAR")        -1
PQfnumber(res, "\"BAR\"")    1

指定した列の抽出元であるテーブルのOIDを返します。 列番号は0から始まります。

Oid PQftable(const PGresult *res,
             int column_number);

列番号が範囲外の場合や指定した列がテーブル列への単純な参照でない場合、InvalidOidが返されます。 pg_classシステムテーブルに問い合わせ、どのテーブルが参照されているのかを正確に求めることができます。

libpqヘッダファイルをインクルードすると、Oid型とInvalidOid定数が定義されます。 これらは両方とも何らかの整数型です。

指定した問い合わせ結果の列を作成した列の(それが属するテーブル内での)列番号を返します。 問い合わせ結果の列番号は0から始まりますが、テーブル列には0以外の番号が付けられています。

int PQftablecol(const PGresult *res,
                int column_number);

列番号が範囲外の場合や指定した列がテーブル列への単純な参照でなかった場合、ゼロが返されます。

指定した列の書式を示す書式コードを返します。 列番号は0から始まります。

int PQfformat(const PGresult *res,
              int column_number);

ゼロという書式コードはテキストデータ表現を示し、1という書式コードはバイナリ表現を示します。 (他のコードは将来の定義のために予約されています。)

指定した列番号に関連したデータ型を返します。 返された整数はその型の内部的なOID番号です。 列番号は0から始まります。

Oid PQftype(const PGresult *res,
            int column_number);

pg_typeシステムテーブルに問い合わせて、各種データ型の名前や属性を得ることができます。 組み込みデータ型のOIDは、PostgreSQLがインストールされたincludeディレクトリ内のcatalog/pg_type_d.hファイルに定義されています。

指定した列番号に関連した列の型修飾子を返します。 列番号は0から始まります。

int PQfmod(const PGresult *res,
           int column_number);

修飾子の値の解釈は型に固有なものです。 通常これらは精度やサイズの制限を示します。 -1という値は「使用できる情報がない」ことを示します。 ほとんどのデータ型は修飾子を使用しません。 この場合は常に-1という値になります。

指定した列番号に関連した列のバイト単位のサイズを返します。 列番号は0から始まります。

int PQfsize(const PGresult *res,
            int column_number);

PQfsizeはデータベース行内でその列用に割り当てられる領域を返します。 言い替えると、そのデータ型についてのサーバでの内部表現のサイズです。 (従って、実際にはクライアントから見るとあまり役には立ちません。) 負の値は可変長データ型を示します。

PGresultがバイナリデータを持つ場合は1を、テキストデータを持つ場合は0を返します。

int PQbinaryTuples(const PGresult *res);

この関数は廃れたものです。 (COPYを行う接続での使用を除きます。) 単一のPGresultで、ある列はテキストデータを持ち、他の列ではバイナリデータを持つことが可能であるためです。 PQfformatの利用が推奨されます。 結果のすべての列がバイナリ(書式1)の場合のみPQbinaryTuplesは1を返します。

PGresultの1行における単一フィールドの値を返します。 行番号と列番号は0から始まります。 呼び出し元はこの結果を直接解放してはいけません。 関連するPGresultハンドルがPQclearに渡された時に、これは解放されます。

char *PQgetvalue(const PGresult *res,
                 int row_number,
                 int column_number);

テキスト書式のデータでは、PQgetvalueで返される値はフィールド値のNULL終端の文字列表現となります。 バイナリ書式のデータでは、この値はデータ型のtypsend関数とtypreceive関数で決まるバイナリ表現となります。 (実際にはこの場合でも値の終わりにゼロというバイトが付与されます。 しかし、この値の内部には大抵の場合NULLが埋め込まれていますので、通常このバイトは有用ではありません。)

フィールド値がNULLの場合、空文字列が返されます。 NULL値と空文字列という値とを区別する方法はPQgetisnullを参照してください。

PQgetvalueによって返されるポインタはPGresult構造体の一部の格納領域を指し示します。 このポインタが指し示すデータを変更すべきではありません。 また、PGresult構造体を解放した後も使用し続ける場合は、データを別の格納領域に明示的にコピーしなければなりません。

フィールドがNULL値かどうか検査します。 行番号と列番号は0から始まります。

int PQgetisnull(const PGresult *res,
                int row_number,
                int column_number);

この関数は、フィールドがNULLの場合に1を、フィールドが非NULL値を持つ場合は0を返します。 (PQgetvalueでは、NULLフィールドはNULLポインタではなく空文字列を返すことに注意してください。)

実際のフィールド値の長さをバイト単位で返します。 行番号と列番号は0から始まります。

int PQgetlength(const PGresult *res,
                int row_number,
                int column_number);

これは特定のデータ値についての実際のデータ長です。 つまり、PQgetvalueによって指し示されるオブジェクトのサイズです。 テキストデータ書式ではstrlen()と同一です。 バイナリ書式ではこれは重要な情報です。 実際のデータ長を取り出すためにPQfsizeを信用してはなりません。

準備された文のパラメータ数を返します。

int PQnparams(const PGresult *res);

この関数はPQdescribePreparedの結果を確認する時にのみ有用です。 他の種類の結果ではゼロを返します。

指定された文パラメータのデータ型を返します。 パラメータ番号は0から始まります。

Oid PQparamtype(const PGresult *res, int param_number);

この関数は、PQdescribePreparedの結果を確認する時にのみ有用です。 他の種類の結果ではゼロを返します。

すべての行と列名(省略可能)を指定した出力ストリームに表示します。

void PQprint(FILE *fout,      /* 出力ストリーム */
             const PGresult *res,
             const PQprintOpt *po);
typedef struct
{
    pqbool  header;      /* フィールドヘッダ情報と行数の表示出力 */
    pqbool  align;       /* 位置揃えのためのフィールドへの埋め込み */
    pqbool  standard;    /* 古い、無くなりそうな書式 */
    pqbool  html3;       /* HTML表出力 */
    pqbool  expanded;    /* 拡張テーブル */
    pqbool  pager;       /* 必要に応じたページャの使用 */
    char    *fieldSep;   /* フィールド区切り文字 */
    char    *tableOpt;   /* HTML表要素の属性 */
    char    *caption;    /* HTML 表の表題 */
    char    **fieldName; /* フィールド名を置き換えるNULL終端の配列 */
} PQprintOpt;

この関数は以前に問い合わせ結果を表示するためにpsqlで使用されていましたが、今ではもう使用されていません。 これはすべてのデータがテキスト書式であるという前提で動作することに注意してください。

PGresultを生成したSQLコマンドのコマンド状態タグを返します。

char *PQcmdStatus(PGresult *res);

これは通常単なるコマンド名ですが、処理行数など追加情報が含まれる場合もあります。 呼び出し元はこの戻り値を直接解放してはいけません。 関連するPGresultハンドルがPQclearに渡された時にこれは解放されます。

SQLコマンドにより影響を受けた行数を返します。

char *PQcmdTuples(PGresult *res);

この関数はPGresultを生成したSQLコマンドにより影響を受けた行数を含む文字列を返します。 この関数はSELECT、CREATE TABLE AS、INSERT、UPDATE、DELETE、MERGE、MOVE、FETCH、COPY文の実行、あるいは、INSERT、UPDATE、DELETE、MERGEを含むプリペアド問い合わせのEXECUTE文の後でのみ使用することができます。 PGresultを生成したコマンドが他のコマンドであった場合、PQcmdTuplesは空文字列を返します。 呼び出し元はこの戻り値を直接解放してはいけません。 関連するPGresultハンドルがPQclearに渡された時にこれは解放されます。

SQLコマンドが、OIDを持つテーブル内に1行のみを挿入するINSERTだった場合、あるいは、適切なINSERTを持つプリペアド問い合わせのEXECUTEだった場合に、挿入された行のOIDを返します。 さもなくばInvalidOidを返します。 また、INSERT文の影響を受けたテーブルがOIDを持たなかった場合、この関数はInvalidOidを返します。

Oid PQoidValue(const PGresult *res);

この関数はPQoidValueのため廃止予定になりました。 またこれはスレッドセーフではありません。 これは挿入された行のOIDを文字列として返します。 一方PQoidValueはOID値を返します。

char *PQoidStatus(const PGresult *res);

char *PQescapeLiteral(PGconn *conn, const char *str, size_t length);

PQescapeLiteralは、SQLコマンド内で使用するために文字列をエスケープします。 これは、SQLコマンド内のリテラル定数としてデータ値を挿入する時に有用です。 特定の文字(引用符やバックスラッシュ)は、SQLパーサによって特殊な解釈がなされないようにエスケープされなければなりません。 PQescapeLiteralはこの操作を行います。

PQescapeLiteralはstrパラメータをエスケープしたものをmalloc()で割り当てたメモリ内に返します。 その結果が不要になったら、そのメモリをPQfreemem()を使用して解放しなければなりません。 ゼロバイト終端は必要なく、lengthに含めて数えてはいけません。 (lengthバイトを処理する前にゼロバイト終端が見つかると、PQescapeLiteralはそのゼロで終了します。 この動作はstrncpyと似ています。) 返される文字列では、PostgreSQL文字列リテラルパーサで適切に処理することができるように、すべての特殊文字は置換されます。 ゼロバイト終端も追加されます。 PostgreSQLの文字列リテラルでは前後に必要となる単一引用符も、その結果文字列には含まれています。

エラー時、PQescapeLiteralはNULLを返し、connオブジェクト内に適切なメッセージを残します。

PQexecParamsまたは同義のルーチン内で別のパラメータとしてデータ値が渡される場合は、エスケープすることは必要でもなければ正しくもないことに注意してください。

char *PQescapeIdentifier(PGconn *conn, const char *str, size_t length);

PQescapeIdentifierは、テーブル、列、関数名などのSQL識別子として使用できるように文字列をエスケープします。 これはユーザが提供した識別子に、そのままではSQLパーサで識別子として解釈されない特殊な文字が含まれる可能性がある場合、または、大文字小文字の違いを維持しなければならない状況で識別子に大文字が含まれる可能性がある場合に有用です。

PQescapeIdentifierはstrパラメータをSQL識別子としてエスケープしたものをmalloc()で割り当てたメモリ内に返します。 その結果が不要になったら、そのメモリをPQfreemem()を使用して解放しなければなりません。 ゼロバイト終端は必要なく、lengthに含めて数えてはいけません。 (lengthバイトを処理する前にゼロバイト終端が見つかると、PQescapeIdentifierはそのゼロで終了します。 この動作はstrncpyと似ています。) 返される文字列では、SQL識別子として適切に処理することができるように、すべての特殊文字は置換されます。 ゼロバイト終端も追加されます。 その結果文字列の前後には二重引用符が付与されます。

エラー時、PQescapeIdentifierはNULLを返し、connオブジェクト内に適切なメッセージを残します。

size_t PQescapeStringConn(PGconn *conn,
                          char *to, const char *from, size_t length,
                          int *error);

PQescapeStringConnは、PQescapeLiteralとほぼ同様に文字列リテラルをエスケープします。 PQescapeLiteralとは異なり、呼び出し元が適切な大きさのバッファを提供することに責任を持ちます。 さらにPQescapeStringConnはPostgreSQLの文字リテラルとして囲まれなければならない単一引用符を生成しません。 これは、結果をSQLコマンドに挿入するときに付与しなければなりません。 fromパラメータはエスケープ対象の文字列の先頭を指すポインタです。 lengthパラメータはこの文字列のバイト数を示します。 ゼロバイト終端は必要なく、また、lengthではこれを数えてはなりません。 (もしlengthバイト処理する前にゼロバイト終端が存在すると、PQescapeStringConnはそのゼロで終了します。 この動作はstrncpyと同様です。) toは、最低でもlengthの2倍よりも1バイト多い文字を保持可能なバッファへのポインタにしなければなりません。 さもないと、動作は不定になります。 toとfrom文字領域が重なる場合の動作も不定です。

errorパラメータがNULLでなければ、*errorには成功の0か、エラーの0以外が設定されます。 現時点であり得る唯一のエラー条件は、元文字列に無効なマルチバイト符号が含まれている場合です。 出力文字列はエラーであっても生成されますが、サーバが不整合として却下することが想定できます。 エラーの際、適切なメッセージはerrorがNULLかどうかにかかわらずconnオブジェクト内に格納されます。

PQescapeStringConnはtoに書き出したバイト数を返します。 ただし、文字数にはゼロバイト終端は含まれません。

PQescapeStringはPQescapeStringConnの推奨されない古いものです。

size_t PQescapeString (char *to, const char *from, size_t length);

PQescapeStringConnとの唯一の違いは、PQescapeStringはPGconnやerrorパラメータを取らないことです。 このため(文字符号化方式のような)接続属性に依存する振舞いを調整できません。 その結果間違った結果を返す可能性があります。 また、エラー状態を通知する機能がありません。

PQescapeStringは、一度に1つのPostgreSQL接続のみで動作するクライアントプログラムでは安全に利用できます。 (この場合知らなければならない「裏側に隠された情報」を知ることができるからです。) 他の場合には、セキュリティ要因でありPQescapeStringConnを利用することで避けなければなりません。

bytea型としてSQLコマンド内で使用するバイナリデータをエスケープします。 PQescapeStringConnと同様、これは、SQLコマンド文字列にデータを直接含める場合にのみに使用されます。

unsigned char *PQescapeByteaConn(PGconn *conn,
                                 const unsigned char *from,
                                 size_t from_length,
                                 size_t *to_length);

SQL文内のbyteaリテラルの一部として使用する場合、特定のバイト値はエスケープされなければなりません。 PQescapeByteaConnは16進数符号化またはバックスラッシュエスケープ処理を使用してバイトをエスケープします。 詳しくは8.4を参照してください。

fromパラメータはエスケープ対象の文字列の先頭バイトを指し示すポインタです。 from_lengthパラメータは、このバイナリ列内のバイト数を指定します。 (ゼロバイト終端は不要、かつ、数えられません。) to_lengthパラメータは結果となるエスケープされた文字列の長さを保持する変数へのポインタです。 この結果文字列長は、結果内のゼロバイト終端を含みます。

PQescapeByteaConnは、fromパラメータが示すバイナリ文字列をエスケープしたものをmalloc()で確保したメモリ内に返します。 その結果が不要になったら、このメモリをPQfreemem()を使用して解放しなければなりません。 返される文字列では、PostgreSQLリテラル文字列パーサとbytea入力関数によって適切に処理できるように、すべての特殊な文字が置換されています。 ゼロバイト終端も追加されます。 PostgreSQLのリテラル文字列をくくる単一引用符は結果文字列には含まれません。

エラー時、NULLポインタを返し適切なエラーメッセージをconnオブジェクトに格納します。 現在、唯一あり得るエラーは結果文字列のメモリ不足です。

PQescapeByteaは、PQescapeByteaConnの推奨されない古いものです。

unsigned char *PQescapeBytea(const unsigned char *from,
                             size_t from_length,
                             size_t *to_length);

PQescapeByteaのPQescapeByteaConnとの唯一の違いは、PGconnパラメータです。 このためPQescapeByteaは、一度に１つのPostgreSQL接続を使用するクライアントプログラムのみで安全に利用することができます。 (この場合知らなければならない「裏側に隠された情報」を知ることができるからです。) 複数のデータベース接続を使用するプログラムでは間違った結果を返す可能性があります。 （このような場合はPQescapeByteaConnを使用してください。）

バイナリデータの文字列表現をバイナリデータに変換します。 つまり、PQescapeByteaの逆です。 これは、byteaデータをテキスト書式で受けとった場合に必要とされます。 しかし、バイナリ書式で受けとった場合は不要です。

unsigned char *PQunescapeBytea(const unsigned char *from, size_t *to_length);

fromパラメータは、例えば、bytea列にPQgetvalueを行なった場合に返される可能性がある、文字列を指し示すポインタです。 PQunescapeByteaは、この文字列表現をバイナリ表現に変換します。 malloc()で確保したバッファへのポインタを返します。 エラー時はNULLです。 また、このバッファのサイズをto_lengthに格納します。 不要になったら、この結果をPQfreememを使用して解放しなければなりません。

この変換は、PQescapeByteaの逆ではありません。 文字列はPQgetvalueから受け取る場合「エスケープされた」ことを予想しないためです。 特にこれは、文字列の引用符付けを意識する必要がなく、そのためPGconnパラメータを持つ必要がないことを意味します。