PG_DIAG_MESSAGE_DETAIL詳細です。問題に関するより詳細を表す補助的なエラーメッセージです。複数行に跨る可能性があります。PG_DIAG_MESSAGE_HINTヒントです。問題の対応方法についての補助的な提言です。これは、詳細(detail)とは異なり、問題の事象ではなく、(適切でない可能性がありますが)アドバイスを提供することを目的としています。複数行に跨る可能性があります。PG_DIAG_STATEMENT_POSITION元の問い合わせ文字列のインデックスとなる、エラーが発生したカーソル位置を示す10進整数を持つ文字列です。先頭文字がインデックス1となり、また、バイトではなく、文字数で数えた位置です。PG_DIAG_INTERNAL_POSITIONこの定義はPG_DIAG_STATEMENT_POSITIONフィールドと同じです。これは、クライアントが発行したコマンドではなく、カーソル位置が内部生成コマンドを参照する場合に使用されます。このフィールドが存在する時は常にPG_DIAG_INTERNAL_QUERYフィールドが存在します。PG_DIAG_INTERNAL_QUERY失敗した内部生成コマンドのテキストです。これは、例えば、PL/pgSQL関数で発行されたSQL問い合わせになります。PG_DIAG_CONTEXTエラーが発生した文脈を示すものです。今の所、これは活動中の手続き言語関数や内部生成問い合わせの呼び出しスタックの追跡情報が含まれます。この追跡は行単位で1項目であり、その順番は呼び出し順の反対になります。PG_DIAG_SCHEMA_NAMEもしそのエラーが特定のデータベースオブジェクトに付随する時、もしあれば、そのオブジェクトを含むスキーマ名です。PG_DIAG_TABLE_NAMEもしそのエラーが特定のテーブルに付随する時のテーブル名です。(テーブルのスキーマ名についてはスキーマ名フィールドを参照ください。)PG_DIAG_COLUMN_NAMEもしそのエラーが特定のテーブル列に付随する時の列名です。(テーブルを識別するにはスキーマとテーブル名フィールドを参照ください。)PG_DIAG_DATATYPE_NAMEもしそのエラーが特定のデータ型に付随する時のデータ型名です。(データ型のスキーマ名についてはスキーマ名フィールドを参照ください。)PG_DIAG_CONSTRAINT_NAMEもしそのエラーが特定の制約に付随する時の制約名です。付随するテーブルまたはドメインについては上記にリストされたフィールドを参照ください。(この目的のために、制約は制約構文で作成されていなくてもインデックスは制約として扱われます。)PG_DIAG_SOURCE_FILEエラーが報告された場所のソースコードのファイル名です。PG_DIAG_SOURCE_LINEエラーが報告された場所のソースコードにおける行番号です。PG_DIAG_SOURCE_FUNCTIONエラーを報告した、ソースコードにおける関数名です。スキーマ名、テーブル名、列名、データ型名、および制約名に対するフィールドは限定的なエラー型に対してのみ提供されます。付録Aを参照ください。これらのフィールドのいかなる存在もその他のフィールドの存在を保証すると推測してはなりません。コアエラーの出所は上に記載の相互関係を監視しますが、ユーザ定義関数はこれらフィールドを別目的で使用しているかもしれません。これらのフィールドが同時に存在するオブジェクトを意味すると推測してはなりません。表示情報の必要に応じた整形はクライアントの責任です。具体的には、必要に応じて長い行を分割しなければなりません。エラーメッセージフィールド内の改行文字は、改行としてではなく段落として分かれたものとして取扱うべきです。libpqで内部的に生成されたエラーは、深刻度と主要メッセージを持ちますが、通常は他のフィールドを持ちません。3.0より前のプロトコルのサーバで返されるエラーは、深刻度と主要メッセージ、場合によって詳細メッセージを持ちますが、他のフィールドを持ちません。エラーフィールドはPGresultからのみ利用でき、PGconnからは利用できません。PQerrorFieldという関数はありません。PQclearPGresultに割り当てられた記憶領域を解放します。個々の問い合わせ結果は、必要なくなった時にPQclearで解放するべきです。*res);PGresultオブジェクトは必要な間保持することができます。新しい問い合わせを発行する場合でも、接続を閉じてしまうまではPGresultは消えません。PGresultを解放するには、PQclearを呼び出さなくてはいけません。その操作に失敗してしまうと、アプリケーションのメモリリークを引き起こしてしまいます。問い合わせ結果の情報の取り出しこれらの関数を使用して、正常終了した問い合わせ結果を示す(つまり、その状態がPGRES_TUPLES_OKまたはPGRES_SINGLE_TUPLEとなっている)PGresultオブジェクトから情報を抽出することができます。成功したDescribe操作から情報を抽出することもできます。Describeの結果はすべて、実際に問い合わせを実行した時に提供されるものと同じ列情報を持ちますが、行はありません。他の状態値を持つオブジェクトでは、これらの関数は、結果が0行0列であるものと同様に動作します。PQntuples問い合わせ結果内の行(タプル)数を返します。これは整数を結果として返しますので、32ビットオペレーティングシステムでは、大規模な結果セットの戻り値はオーバーフローする可能性があります。*res);PQnfields問い合わせ結果の各行の列(フィールド)の数を返します。*res);PQfname指定した列番号に対応する列の名前を返します。列番号は0から始まります。呼び出し元はこの結果を直接解放してはいけません。関連するPGresultハンドルがPQclearに渡された時にこれは解放されます。column_number);列番号が範囲外であった場合、NULLが返ります。PQfnumber指定した列名に関連する列番号を返します。*column_name);指定した名前に一致する列がなければ、-1が返ります。指定した名前はSQLコマンドの識別子同様に扱われます。二重引用符でくくられていない限り、小文字化されます。以下のSQLで生成された問い合わせ結果を考えます。"BAR";以下により、結果を取り出すことができます。1PQftable指定した列の抽出元であるテーブルのOIDを返します。列番号は0から始まります。column_number);列番号が範囲外の場合や指定した列がテーブル列への単純な参照でない場合、3.0より前のプロトコルを使用している場合は、InvalidOidが返されます。pg_classシステムテーブルに問い合わせ、どのテーブルが参照されているのかを正確に求めることができます。libpqヘッダファイルをインクルードすると、Oid型とInvalidOid定数が定義されます。これらは両方とも何らかの整数型です。PQftablecol指定した問い合わせ結果の列を作成した列の(それが属するテーブル内での)列番号を返します。問い合わせ結果の列番号は0から始まります。テーブル列には0以外の番号が付けられています。column_number);列番号が範囲外の場合や指定した列がテーブル列への単純な参照でなかった場合、3.0より前のプロトコルを使用している場合は、ゼロが返されます。PQfformat指定した列の書式を示す書式コードを返します。列番号は0から始まります。column_number);ゼロという書式コードはテキストデータ表現を示し、1という書式コードはバイナリ表現を示します。(他のコードは将来の定義のために予約されています。)PQftype指定した列番号に関連したデータ型を返します。返された整数はその型の内部的なOID番号です。列番号は0から始まります。column_number);pg_typeシステムテーブルに問い合わせて、各種データ型の名前や属性を得ることができます。組み込みデータ型のOIDは、ソースツリー内のsrc/include/catalog/pg_type.hファイル内で定義されています。PQfmod指定した列番号に関連した列の型修飾子を返します。列番号は0から始まります。column_number);修飾子の値の解釈は型に固有なものです。通常これらは精度やサイズの制限を示します。-1という値は"使用できる情報がない"ことを示します。ほとんどのデータ型は修飾子を使用しません。この場合は常に-1という値になります。PQfsize指定した列番号に関連した列のバイト単位のサイズを返します。列番号は0から始まります。column_number);PQfsizeはデータベース行内でその列用に割り当てられる領域を返します。言い替えると、そのデータ型についてのサーバでの内部表現のサイズです。(従って、実際にはクライアントから見るとあまり役には立ちません。負の値は可変長データ型を示します。PQbinaryTuplesPGresultがバイナリデータを持つ場合は1を、テキストデータを持つ場合は0を返します。*res);この関数は廃れたものです。(COPYを行う接続での使用を除きます。単一のPGresultで、ある列はテキストデータを持ち、他の列ではバイナリデータを持つことが可能であるためです。PQfformatの利用が推奨されます。結果のすべての列がバイナリ(書式1)の場合のみPQbinaryTuplesは1を返します。PQgetvaluePGresultの1行における単一フィールドの値を返します。行番号と列番号は0から始まります。呼び出し元はこの結果を直接解放してはいけません。関連するPGresultハンドルがPQclearに渡された時に、これは解放されます。column_number);テキスト書式のデータでは、PQgetvalueで返される値はフィールド値をヌル終端の文字列表現となります。バイナリ書式のデータでは、この値はデータ型のtypsend関数とtypreceive関数で決まるバイナリ表現となります。(実際にはこの場合でも値の終わりにゼロというバイトが付与されます。この値の内部には大抵の場合ヌルが埋め込まれていますので、通常このバイトは有用ではありません。)フィールド値がNULLの場合、空文字列が返されます。NULL値と空文字列という値とを区別する方法はPQgetisnullを参照してください。PQgetvalueによって返されるポインタはPGresult構造体の一部の格納領域を指し示します。このポインタが指し示すデータを変更すべきではありません。PGresult構造体を解放した後も使用し続ける場合は、データを別の格納領域に明示的にコピーしなければなりません。PQgetisnullフィールドがNULL値かどうか検査します。行番号と列番号は0から始まります。column_number);この関数は、フィールドがNULLの場合に1を、フィールドが非NULL値を持つ場合は0を返します。(PQgetvalueでは、NULLフィールドはヌルポインタではなく空文字列を返すことに注意してください。)PQgetlength実際のフィールド値の長さをバイト単位で返します。行番号と列番号は0から始まります。column_number);これは特定のデータ値についての実際のデータ長です。PQgetvalueによって指し示されるオブジェクトのサイズです。テキストデータ書式ではstrlen()と同一です。バイナリ書式ではこれは重要な情報です。実際のデータ長を取り出すためにPQfsizeを信用してはなりません。PQnparamsプリペアド文のパラメータ数を返します。*res);この関数はPQdescribePreparedの結果を確認する時にのみ有用です。他の種類の問い合わせではゼロを返します。PQparamtype指定された文パラメータのデータ型を返します。パラメータ番号は0から始まります。param_number);この関数は、PQdescribePreparedの結果を確認する時にのみ有用です。他の種類の問い合わせではゼロを返します。PQprintすべての行と列名(省略可能)を指定した出力ストリームに表示します。PQprintOpt;この関数は以前に問い合わせ結果を表示するためにpsqlで使用されていましたが、今ではもう使用されていません。これはすべてのデータがテキスト書式であるという前提で動作することに注意してください。他の結果情報の取り出しこれらの関数はPGresultオブジェクトからその他の情報を取り出すために使用されます。PQcmdStatusPGresultを生成したSQLコマンドのコマンド状態タグを返します。*res);これは通常単なるコマンド名ですが、処理行数など追加情報が含まれる場合もあります。呼び出し元はこの戻り値を直接解放してはいけません。関連するPGresultハンドルがPQclearに渡された時にこれは解放されます。PQcmdTuplesSQLコマンドにより影響を受けた行数を返します。*res);この関数はPGresultを生成したSQLコマンドにより影響を受けた行数を持つ文字列を返します。AS、INSERT、UPDATE、DELETE、MOVE、FETCH、COPY文の実行、あるいは、INSERT、UPDATE、DELETEを含むプリペアド問い合わせのEXECUTE文の後でのみ使用することができます。PGresultを生成したコマンドが他のコマンドであった場合、PQcmdTuplesは空文字列を返します。呼び出し元はこの戻り値を直接解放してはいけません。関連するPGresultハンドルがPQclearに渡された時にこれは解放されます。PQoidValueSQLコマンドが、OIDを持つテーブル内に1行のみを挿入するINSERTだった場合、あるいは、適切なINSERTを持つプリペアド問い合わせのEXECUTEだった場合に、挿入された行のOIDを返します。なくばInvalidOidを返します。INSERT文の影響を受けたテーブルがOIDを持たなかった場合、この関数はInvalidOidを返します。*res);PQoidStatusこの関数はPQoidValueのため廃止予定になりました。これはスレッドセーフではありません。これは挿入された行のOIDを文字列として返します。PQoidValueはOID値を返します。length);PQescapeLiteralは、SQLコマンド内で使用するために文字列をエスケープします。これは、SQLコマンド内のリテラル定数としてデータ値を挿入する時に有用です。特定の文字(引用符やバックスラッシュ)は、SQLパーサによって特殊な解釈がなされないようにエスケープされなければなりません。PQescapeLiteralはこの操作を行います。PQescapeLiteralはstrパラメータをエスケープしたものをmalloc()で割り当てたメモリ内に返します。その結果が不要になったら、そのメモリをPQfreemem()を使用して解放しなければなりません。ゼロバイト終端は必要なく、lengthに含めて数えてはいけません。(lengthバイトを処理する前にゼロバイト終端が見つかると、PQescapeLiteralはそのゼロで終了します。この動作はstrncpyと似ています。返される文字列では、PostgreSQL文字列リテラルパーサで適切に処理することができるように、すべての特殊文字は置換されます。ゼロバイト終端も追加されます。PostgreSQLの文字列リテラルでは前後に必要となる単一引用符も、その結果文字列には含まれています。エラー時、PQescapeLiteralはNULLを返し、connオブジェクト内に適切なメッセージを残します。信用できない入力元から受けとった文字列を扱う場合に適切なエスケープ処理を行なうことは非常に重要です。なくば、セキュリティ上の危険性が発生します。"SQLインジェクション"攻撃という弱点となり、好ましくないSQLコマンドがデータベースに流れてしまいます。データがPQexecParamsまたは同義のルーチン内で別のパラメータとしてデータ値が渡される場合は、エスケープする必要も修正することもないことに注意してください。length);PQescapeIdentifierは、テーブル、列、関数名などのSQL識別子として使用できるように文字列をエスケープします。これはユーザが提供した識別子に、そのままではSQLパーサで識別子として解釈されない特殊な文字が含まれる可能性がある場合、または、大文字小文字の違いを維持しなければならない状況で識別子に大文字が含まれる可能性がある場合に有用です。PQescapeIdentifierはstrパラメータをSQL識別子としてエスケープしたものをmalloc()で割り当てたメモリ内に返します。その結果が不要になったら、そのメモリをPQfreemem()を使用して解放しなければなりません。ゼロバイト終端は必要なく、lengthに含めて数えてはいけません。(lengthバイトを処理する前にゼロバイト終端が見つかると、PQescapeIdentifierはそのゼロで終了します。この動作はstrncpyと似ています。返される文字列では、SQL識別子として適切に処理することができるように、すべての特殊文字は置換されます。ゼロバイト終端も追加されます。その結果文字列の前後には二重引用符が付与されます。エラー時、PQescapeIdentifierはNULLを返し、connオブジェクト内に適切なメッセージを残します。文字列リテラルと同様、SQLインジェクション攻撃を防ぐために、信頼できない入力元から受けとる場合にはSQL識別子をエスケープしなければなりません。*error);PQescapeStringConnは、PQescapeLiteralとほぼ同様に文字列リテラルをエスケープします。PQescapeLiteralとは異なり、呼び出し元が適切な大きさのバッファを提供することに責任を持ちます。PQescapeStringConnはPostgreSQLの文字リテラルとして囲まれなければならない単一引用符を生成しません。これは、結果をSQLコマンドに挿入するときに付与しなければなりません。fromパラメータはエスケープ対象の文字列の先頭を指すポインタです。lengthパラメータはこの文字列のバイト数を示します。ゼロバイト終端は必要なく、また、lenthではこれを数えてはなりません。(もしlengthバイト処理する前にゼロバイト終端が存在すると、PQescapeStringConnはそのゼロで終了します。この動作はstrncpyと同様です。toは、最低でもlengthの2倍よりも1バイト多い文字を保持可能なバッファへのポインタにしなければなりません。ないと、動作は不定になります。toとfrom文字領域が重なる場合の動作も不定です。errorパラメータがNULLでなければ、*errorには成功の0か、エラーの0以外が設定されます。現時点であり得る唯一のエラー条件は、元文字列に無効なマルチバイト符号が含まれている場合です。出力文字列はエラーであっても生成されますが、サーバが不整合として却下することが想定できます。エラーの際、適切なメッセージはerrorがNULLかどうかにかかわらずconnオブジェクト内に格納されます。PQescapeStringConnはtoに書き出したバイト数を返します。文字数にはゼロバイト終端は含まれません。PQescapeStringPQescapeStringはPQescapeStringConnの推奨されない古いものです。length);PQescapeStringConnとの唯一の違いは、PQescapeStringはPGconnやerrorパラメータを取らないことです。このため(文字符号化方式のような)接続属性に依存する振舞いを調整できません。その結果間違った結果を返す可能性があります。エラー状態を通知する機能がありません。PQescapeStringは、一度に1つのPostgreSQL接続のみで動作するクライアントプログラムでは安全に利用できます。(この場合知らなければならない"裏側に隠された情報"を知ることができるからです。他の場合には、セキュリティ要因でありPQescapeStringConnを利用することで避けなければなりません。PQescapeByteaConnbytea型としてSQLコマンド内で使用するバイナリデータをエスケープします。PQescapeStringConnと同様、これは、SQLコマンド文字列にデータを直接含める場合にのみに使用されます。*to_length);SQL文内のbyteaリテラルの一部として使用する場合、特定のバイト値はエスケープされなければなりません。PQescapeByteaConnは16進数符号化またはバックスラッシュエスケープ処理を使用してバイトをエスケープします。詳しくは項8.4を参照してください。fromパラメータはエスケープ対象の文字列の先頭バイトを指し示すポインタです。from_lengthパラメータは、このバイナリ列内のバイト数を指定します。(ゼロバイト終端は不要、かつ、数えられません。to_lengthパラメータは結果となるエスケープされた文字列の長さを保持する変数へのポインタです。この結果文字列長は、結果内のゼロバイト終端を含みます。PQescapeByteaConnは、fromパラメータが示すバイナリ文字列をエスケープしたものをmalloc()で確保したメモリ内に返します。その結果が不要になったら、このメモリをPQfreememを使用して解放しなければなりません。返される文字列では、PostgreSQLリテラル文字列パーサとbytea入力関数によって適切に処理できるように、すべての特殊な文字が置換されています。ゼロバイト終端も追加されます。PostgreSQLのリテラル文字列をくくる単一引用符は結果文字列には含まれません。エラー時、ヌルポインタを返し適切なエラーメッセージをconnオブジェクトに格納します。現在、唯一あり得るエラーは結果文字列のメモリ不足です。PQescapeByteaPQescapeByteaは、PQescapeByteaConnの推奨されない古いものです。*to_length);PQescapeByteaのPQescapeByteaConnとの唯一の違いは、PGconnパラメータです。このためPQescapeByteaは、一度に1つのPostgreSQL接続を使用するクライアントプログラムのみで安全に利用することができます。(この場合知らなければならない"裏側に隠された情報"を知ることができるからです。複数のデータベース接続を使用するプログラムでは間違った結果を返す可能性があります。(このような場合はPQescapeByteaConnを使用してください。)PQunescapeByteaバイナリデータの文字列表現をバイナリデータに変換します。PQescapeByteaの逆です。これは、byteaデータをテキスト書式で受けとった場合に必要とされます。バイナリ書式で受けとった場合は不要です。*to_length);fromパラメータは、例えば、bytea列にPQgetvalueを行なった場合に返される可能性がある、文字列を指し示すポインタです。PQunescapeByteaは、この文字列表現をバイナリ表現に変換します。malloc()で確保したバッファへのポインタを返します。エラー時はNULLです。このバッファのサイズをto_lengthに格納します。不要になったら、この結果をPQfreememを使用して解放しなければなりません。この変換は、PQescapeByteaの逆ではありません。文字列はPQgetvalueから受け取る場合"エスケープされた"ことを予想しないためです。これは、文字列の引用符付けを意識する必要がなく、そのためPGconnパラメータを持つ必要がないことを意味します。