Frees memory allocated by <application>libpq</application>. libpqが割り当てたメモリを解放します。

void PQfreemem(void *ptr);

Frees memory allocated by <application>libpq</application>, particularly <xref linkend="libpq-PQescapeByteaConn"/>, <xref linkend="libpq-PQescapeBytea"/>, <xref linkend="libpq-PQunescapeBytea"/>, and <function>PQnotifies</function>. It is particularly important that this function, rather than <function>free()</function>, be used on Microsoft Windows. This is because allocating memory in a DLL and releasing it in the application works only if multithreaded/single-threaded, release/debug, and static/dynamic flags are the same for the DLL and the application. On non-Microsoft Windows platforms, this function is the same as the standard library function <function>free()</function>. 具体的にはPQescapeByteaConn、PQescapeBytea、PQunescapeByteaおよびPQnotifiesによりlibpqが割り当てたメモリを解放します。 Microsoft Windowsにおいてfree()ではなく、この関数を使用することが特に重要です。 DLLにおけるメモリ割り当てとアプリケーションにおけるその解放が、DLLとアプリケーションとでマルチスレッド/シングルスレッド、リリース用/デバッグ用、静的/動的フラグが同じ場合でのみ動作するためです。 Microsoft Windowsプラットフォーム以外では、この関数は標準ライブラリのfree()関数と同じです。

Frees the data structures allocated by <xref linkend="libpq-PQconndefaults"/> or <xref linkend="libpq-PQconninfoParse"/>. PQconndefaultsもしくはPQconninfoParseが割り当てたデータ構造を解放します。

void PQconninfoFree(PQconninfoOption *connOptions);

If the argument is a NULL pointer, no operation is performed.

A simple <xref linkend="libpq-PQfreemem"/> will not do for this, since the array contains references to subsidiary strings. 単純なPQfreememは、配列が補助文字列への参照を含んでいることから、このためには作業しません。

Prepares the encrypted form of a <productname>PostgreSQL</productname> password. PostgreSQLパスワードの暗号化された形式を準備します。

char *PQencryptPasswordConn(PGconn *conn, const char *passwd, const char *user, const char *algorithm);

This function is intended to be used by client applications that wish to send commands like <literal>ALTER USER joe PASSWORD 'pwd'</literal>. It is good practice not to send the original cleartext password in such a command, because it might be exposed in command logs, activity displays, and so on. Instead, use this function to convert the password to encrypted form before it is sent. この関数は、ALTER USER joe PASSWORD 'pwd'のようなコマンドを送信したいクライアントアプリケーションで使用されることを意図したものです。 こうしたコマンドでは、コマンドログが活動の監視などで晒されてしまうため、元々の平文テキストでパスワードを送信しないことが推奨されています。 その代わりに、この関数を使用して送信前にパスワードを暗号化形式に変換してください。

The <parameter>passwd</parameter> and <parameter>user</parameter> arguments are the cleartext password, and the SQL name of the user it is for. <parameter>algorithm</parameter> specifies the encryption algorithm to use to encrypt the password. Currently supported algorithms are <literal>md5</literal> and <literal>scram-sha-256</literal> (<literal>on</literal> and <literal>off</literal> are also accepted as aliases for <literal>md5</literal>, for compatibility with older server versions). Note that support for <literal>scram-sha-256</literal> was introduced in <productname>PostgreSQL</productname> version 10, and will not work correctly with older server versions. If <parameter>algorithm</parameter> is <symbol>NULL</symbol>, this function will query the server for the current value of the <xref linkend="guc-password-encryption"/> setting. That can block, and will fail if the current transaction is aborted, or if the connection is busy executing another query. If you wish to use the default algorithm for the server but want to avoid blocking, query <varname>password_encryption</varname> yourself before calling <xref linkend="libpq-PQencryptPasswordConn"/>, and pass that value as the <parameter>algorithm</parameter>. passwdとuser引数は、関数が使用する平文のパスワードとそのSQL上のユーザ名です。 algorithmは、パスワードを暗号化するために使用する暗号化アルゴリズムを指定します。 現在サポートされているアルゴリズムは、md5とscram-sha-256です。 (古いサーババージョンとの互換性のために、md5の別名として、onとoffも受け付けます。) scram-sha-256のサポートは、PostgreSQLバージョン10で導入されたので、古いサーババージョンでは正しく動作しないことに注意してください。 algorithmがNULLなら、この関数はサーバに問合せて現在のpassword_encryption設定を返します。 これは、ブロックする可能性があり、また現在のトランザクションがアボートしているか、あるいは他の問合せを実行中でビジーなら失敗します。 サーバのデフォルトアルゴリズムを使用したいが、ブロックは避けたい、という場合は、PQencryptPasswordConnを呼び出す前にpassword_encryptionを自分で調べ、その値をalgorithmに渡してください。

The return value is a string allocated by <function>malloc</function>. The caller can assume the string doesn't contain any special characters that would require escaping. Use <xref linkend="libpq-PQfreemem"/> to free the result when done with it. On error, returns <symbol>NULL</symbol>, and a suitable message is stored in the connection object. 戻り値はmallocで割り当てられた文字列です。 呼び出し元は、その文字列にエスケープしなければならない特殊な文字列が含まれていないことを仮定することができます。 処理が終わった時にPQfreememを使用して結果を解放してください。 エラーの場合にNULLが返され、接続オブジェクトに対応するメッセージが格納されます。

Prepares the md5-encrypted form of a <productname>PostgreSQL</productname> password. md5暗号化形式のPostgreSQLパスワードを準備します。

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

<xref linkend="libpq-PQencryptPassword"/> is an older, deprecated version of <xref linkend="libpq-PQencryptPasswordConn"/>. The difference is that <xref linkend="libpq-PQencryptPassword"/> does not require a connection object, and <literal>md5</literal> is always used as the encryption algorithm. PQencryptPasswordは、古くて非推奨のバージョンのPQencryptPasswordConnです。 違いは、PQencryptPasswordはコネクションオブジェクトを必要とせず、md5が常に暗号化アルゴリズムに使用されることです。

Constructs an empty <structname>PGresult</structname> object with the given status. 与えられたステータスで空のPGresultオブジェクトを構築します。

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

This is <application>libpq</application>'s internal function to allocate and initialize an empty <structname>PGresult</structname> object. This function returns <symbol>NULL</symbol> if memory could not be allocated. It is exported because some applications find it useful to generate result objects (particularly objects with error status) themselves. If <parameter>conn</parameter> is not null and <parameter>status</parameter> indicates an error, the current error message of the specified connection is copied into the <structname>PGresult</structname>. Also, if <parameter>conn</parameter> is not null, any event procedures registered in the connection are copied into the <structname>PGresult</structname>. (They do not get <literal>PGEVT_RESULTCREATE</literal> calls, but see <xref linkend="libpq-PQfireResultCreateEvents"/>.) Note that <xref linkend="libpq-PQclear"/> should eventually be called on the object, just as with a <structname>PGresult</structname> returned by <application>libpq</application> itself. これは空のPGresultオブジェクトを割り当てて、初期化するlibpqの内部関数です。 メモリが割り当てられなかった場合、この関数はNULLを返します。 一部のアプリケーションで結果オブジェクト（特にエラーステータスを伴ったオブジェクト）それ自身を生成することが便利であることが分かりましたので、外部公開されました。 connが非NULで、statusがエラーを示唆している場合、特定された接続の現在のエラーメッセージはPGresultにコピーされます。 同時に、connが非NULLの場合、接続で登録された任意のイベントプロシージャはPGresultにコピーされます。 （それらはPGEVT_RESULTCREATE呼び出しを受けませんが、PQfireResultCreateEventsを理解します。） libpq自身で返されたPGresultと同様に、最終的にはこのオブジェクトに対してPQclearを呼び出さなければならないことに注意してください。

Fires a <literal>PGEVT_RESULTCREATE</literal> event (see <xref linkend="libpq-events"/>) for each event procedure registered in the <structname>PGresult</structname> object. Returns non-zero for success, zero if any event procedure fails. PGresultオブジェクトに登録されたそれぞれのイベントプロシージャに対し、PGEVT_RESULTCREATEイベント（34.14を参照）を発行します。 イベントプロシージャが成功の場合は非ゼロ、失敗の場合はゼロを返します。

int PQfireResultCreateEvents(PGconn *conn, PGresult *res);

The <literal>conn</literal> argument is passed through to event procedures but not used directly. It can be <symbol>NULL</symbol> if the event procedures won't use it. conn引数はイベントプロシージャに渡されますが、直接には使用されません。 イベントプロシージャが使用しない場合はNULLで構いません。

Event procedures that have already received a <literal>PGEVT_RESULTCREATE</literal> or <literal>PGEVT_RESULTCOPY</literal> event for this object are not fired again. このオブジェクトに対し、PGEVT_RESULTCREATEもしくはPGEVT_RESULTCOPYイベントを過去に受け取ったイベントプロシージャは再び発行されません。

The main reason that this function is separate from <xref linkend="libpq-PQmakeEmptyPGresult"/> is that it is often appropriate to create a <structname>PGresult</structname> and fill it with data before invoking the event procedures. この関数がPQmakeEmptyPGresultと分離されている主たる理由は、多くの場合イベントプロシージャを呼び出す前にPGresultを作成し、データを挿入するのが適切であることによります。

Makes a copy of a <structname>PGresult</structname> object. The copy is not linked to the source result in any way and <xref linkend="libpq-PQclear"/> must be called when the copy is no longer needed. If the function fails, <symbol>NULL</symbol> is returned. PGresultオブジェクトのコピーを作ります。 コピーは元の結果にいかなる方法でもリンクされず、コピーが不要になった時にPQclearを呼び出されなければなりません。 関数が失敗するとNULLが返されます。

PGresult *PQcopyResult(const PGresult *src, int flags);

This is not intended to make an exact copy. The returned result is always put into <literal>PGRES_TUPLES_OK</literal> status, and does not copy any error message in the source. (It does copy the command status string, however.) The <parameter>flags</parameter> argument determines what else is copied. It is a bitwise OR of several flags. <literal>PG_COPYRES_ATTRS</literal> specifies copying the source result's attributes (column definitions). <literal>PG_COPYRES_TUPLES</literal> specifies copying the source result's tuples. (This implies copying the attributes, too.) <literal>PG_COPYRES_NOTICEHOOKS</literal> specifies copying the source result's notify hooks. <literal>PG_COPYRES_EVENTS</literal> specifies copying the source result's events. (But any instance data associated with the source is not copied.) The event procedures receive <literal>PGEVT_RESULTCOPY</literal> events. これは正確なコピーの作成を目的としたものではありません。 返された結果は常にPGRES_TUPLES_OK状態の中に置かれ、元の結果におけるエラーメッセージはまったくコピーされません。 （しかしコマンド状態文字列をコピーします。） flags引数はその他にコピーするものがないかを決定します。 それはいくつかのフラグのビット単位のORです。 PG_COPYRES_ATTRSは元の結果の属性（列定義）のコピーを指定します。 PG_COPYRES_TUPLESは元の結果のタプルのコピーを指定します。 （これは属性もコピーされることを意味しています。） PG_COPYRES_NOTICEHOOKSは元の結果の警告フックのコピーを指定します。 PG_COPYRES_EVENTSは元の結果イベントのコピーを指定します。 （しかし、元の結果に関連したインスタンスデータはまったくコピーされません。） イベントプロシージャは、PGEVT_RESULTCOPYイベントを受信します。

Sets the attributes of a <structname>PGresult</structname> object. PGresultオブジェクトの属性を設定します。

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

The provided <parameter>attDescs</parameter> are copied into the result. If the <parameter>attDescs</parameter> pointer is <symbol>NULL</symbol> or <parameter>numAttributes</parameter> is less than one, the request is ignored and the function succeeds. If <parameter>res</parameter> already contains attributes, the function will fail. If the function fails, the return value is zero. If the function succeeds, the return value is non-zero. 提供されたattDescsは結果にコピーされます。 もしattDescsポインタがNULL、またはnumAttributesが１未満の場合、要求は無視され、関数は成功します。 resが既に属性を所有している場合、関数は失敗に終わります。 関数が失敗すると、戻り値はゼロです。 関数が成功すると戻り値は非ゼロになります。

Sets a tuple field value of a <structname>PGresult</structname> object. PGresultオブジェクトのタプルフィールド値を設定します。

int PQsetvalue(PGresult *res, int tup_num, int field_num, char *value, int len);

The function will automatically grow the result's internal tuples array as needed. However, the <parameter>tup_num</parameter> argument must be less than or equal to <xref linkend="libpq-PQntuples"/>, meaning this function can only grow the tuples array one tuple at a time. But any field of any existing tuple can be modified in any order. If a value at <parameter>field_num</parameter> already exists, it will be overwritten. If <parameter>len</parameter> is -1 or <parameter>value</parameter> is <symbol>NULL</symbol>, the field value will be set to an SQL null value. The <parameter>value</parameter> is copied into the result's private storage, thus is no longer needed after the function returns. If the function fails, the return value is zero. If the function succeeds, the return value is non-zero. 必要に応じて関数は自動的に結果の内部タプル配列を肥大化させます。 しかし、tup_num引数はPQntuplesと同じか、もしくは小さくなければなりません。 その意味は、この関数は一回にタプル配列を１タプル大きくさせるだけだからです。 とは言っても、存在するいかなるタプルの任意のフィールドも、順序を問わず変更できます。 もしfield_numに値が既に存在すれば、書き換えられます。 lenが-1、またはvalueがNULLであれば、フィールドの値はSQLのNULLに設定されます。 valueは結果のプライベート格納領域にコピーされるため、関数が返った後ではもう必要がなくなります。 関数が失敗すると、戻り値はゼロです。 関数が成功すると戻り値は非ゼロになります。

Allocate subsidiary storage for a <structname>PGresult</structname> object. PGresultオブジェクトに補助ストレージを割り当てます。

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

Any memory allocated with this function will be freed when <parameter>res</parameter> is cleared. If the function fails, the return value is <symbol>NULL</symbol>. The result is guaranteed to be adequately aligned for any type of data, just as for <function>malloc</function>. resが消去された時、この関数で割り付けられたメモリは解放されます。 関数が失敗すると戻り値はNULLです。 mallocと同じように、どのような種類のデータでも結果は適切に整列されることが保証されています。

Retrieves the number of bytes allocated for a <structname>PGresult</structname> object. PGresultオブジェクトのために割り当てられたバイト数を取り出します。

size_t PQresultMemorySize(const PGresult *res);

This value is the sum of all <function>malloc</function> requests associated with the <structname>PGresult</structname> object, that is, all the space that will be freed by <xref linkend="libpq-PQclear"/>. This information can be useful for managing memory consumption. この値はPGresultオブジェクトに関連するmalloc要求すべての和、すなわちPQclearで解放される空間全体です。 この情報はメモリ消費を管理するのに有用でしょう。

Return the version of <productname>libpq</productname> that is being used. 使用中のlibpqのバージョンを返します。

int PQlibVersion(void);

The result of this function can be used to determine, at run time, whether specific functionality is available in the currently loaded version of libpq. The function can be used, for example, to determine which connection options are available in <xref linkend="libpq-PQconnectdb"/>. この関数の結果を使用して、現在読み込まれているバージョンのlibpqで特定の機能が利用可能かどうかを実行時に決定することができます。 例えばこの関数を使用して、PQconnectdbでどの接続オプションが利用できるかを確認することができます。

The result is formed by multiplying the library's major version number by 10000 and adding the minor version number. For example, version 10.1 will be returned as 100001, and version 11.0 will be returned as 110000. 返却値の形式は、メジャーバージョン番号に10000を掛け、マイナーバージョン番号を加えたものです。 例えば、バージョン10.1では100001を返し、バージョン11.0では110000を返します。

Prior to major version 10, <productname>PostgreSQL</productname> used three-part version numbers in which the first two parts together represented the major version. For those versions, <xref linkend="libpq-PQlibVersion"/> uses two digits for each part; for example version 9.1.5 will be returned as 90105, and version 9.2.0 will be returned as 90200. バージョン10よりも前では、PostgreSQLでは、最初の2つの部分がメジャーバージョンを表す、3つの部分からなるバージョン番号が使われていました。 これらのバージョンでは、PQlibVersionはそれぞれの部分に2桁の数字を使います。 たとえば、バージョン9.1.5では90105が返され、バージョン9.2.0では90200が返されます。

Therefore, for purposes of determining feature compatibility, applications should divide the result of <xref linkend="libpq-PQlibVersion"/> by 100 not 10000 to determine a logical major version number. In all release series, only the last two digits differ between minor releases (bug-fix releases). ですから、機能の互換性を見極めるのが目的なら、アプリケーションはPQlibVersionの結果を10000ではなく、100で割り、論理的なメジャーバージョンを求めるべきです。 すべてのリリースで、最後の2桁だけがマイナーリリースで異なります。 （バグ修正リリースです。）