Sends data to the server during <literal>COPY_IN</literal> state. COPY_IN状態の間、サーバにデータを送信します。

int PQputCopyData(PGconn *conn,
                  const char *buffer,
                  int nbytes);

Transmits the <command>COPY</command> data in the specified <parameter>buffer</parameter>, of length <parameter>nbytes</parameter>, to the server. The result is 1 if the data was queued, zero if it was not queued because of full buffers (this will only happen in nonblocking mode), or -1 if an error occurred. (Use <xref linkend="libpq-PQerrorMessage"/> to retrieve details if the return value is -1. If the value is zero, wait for write-ready and try again.) 指定したbufferにあるCOPYデータをnbytes長分、サーバに送信します。 データがキューに入れられた場合、この結果は1になります。 バッファが一杯でキューに入らなかった場合はゼロになります。 （これは、接続が非ブロックモードの場合にのみ起こります。） エラーが発生した場合は-1になります。 （戻り値が-1の場合、詳細を取り出すためにはPQerrorMessageを使用してください。 戻り値がゼロの場合は書き込み準備が整うまで待ち、再実行してください。）

The application can divide the <command>COPY</command> data stream into buffer loads of any convenient size. Buffer-load boundaries have no semantic significance when sending. The contents of the data stream must match the data format expected by the <command>COPY</command> command; see <xref linkend="sql-copy"/> for details. アプリケーションはCOPYデータストリームを使いやすい大きさのバッファに分けて読み込むことができます。 送信時の読み込みバッファの境界には意味的な重要性はありません。 データストリームの内容は、COPYコマンドで想定しているデータ書式に一致している必要があります。 詳細はCOPYを参照してください。

Sends end-of-data indication to the server during <literal>COPY_IN</literal> state. COPY_IN状態の間に、サーバにデータ終了指示を送信します。

int PQputCopyEnd(PGconn *conn,
                 const char *errormsg);

Ends the <literal>COPY_IN</literal> operation successfully if <parameter>errormsg</parameter> is <symbol>NULL</symbol>. If <parameter>errormsg</parameter> is not <symbol>NULL</symbol> then the <command>COPY</command> is forced to fail, with the string pointed to by <parameter>errormsg</parameter> used as the error message. (One should not assume that this exact error message will come back from the server, however, as the server might have already failed the <command>COPY</command> for its own reasons.) errormsgがNULLなら、COPY_INを成功として終了させます。 errormsgがNULLではないなら、errmsgの指し示す文字列をエラーメッセージとして用いてCOPYを強制的に失敗させます。 （しかし、このエラーメッセージがサーバからそのまま返ってくると仮定すべきではありません。サーバは既に別の原因でCOPYに失敗していた可能性があります。）

The result is 1 if the termination message was sent; or in nonblocking mode, this may only indicate that the termination message was successfully queued. (In nonblocking mode, to be certain that the data has been sent, you should next wait for write-ready and call <xref linkend="libpq-PQflush"/>, repeating until it returns zero.) Zero indicates that the function could not queue the termination message because of full buffers; this will only happen in nonblocking mode. (In this case, wait for write-ready and try the <xref linkend="libpq-PQputCopyEnd"/> call again.) If a hard error occurs, -1 is returned; you can use <xref linkend="libpq-PQerrorMessage"/> to retrieve details. 終端メッセージが送信された場合は結果は1になります。 非ブロックモードでは、終端メッセージがキューに入れられたことしか意味しないかもしれません。 （非ブロックモードでデータが送信されたことを確認するには、次に書き込み準備ができるまで待ち、PQflushを呼ぶことを、それが0を返すまでくり返します。） バッファが一杯で終端メッセージがキューに入れられなかった場合はゼロになります。 これは、接続が非ブロックモードの場合にのみ起こります。 （この場合、書き込み準備ができるまで待ち、再度PQputCopyEndを呼び出してみてください。） ハードエラーが発生した場合は-1になります。 このとき、詳細を取得するためにPQerrorMessageを使用できます。

After successfully calling <xref linkend="libpq-PQputCopyEnd"/>, call <xref linkend="libpq-PQgetResult"/> to obtain the final result status of the <command>COPY</command> command. One can wait for this result to be available in the usual way. Then return to normal operation. PQputCopyEndの呼び出しに成功した後、PQgetResultを呼び出してCOPYコマンドの最終的な結果状態を取り出してください。 通常の方法でこの結果が使用できるようになるまで待機しても構いません。 そして、通常の操作に戻ってください。

Receives data from the server during <literal>COPY_OUT</literal> state. COPY_OUT状態時にサーバからデータを受信します。

int PQgetCopyData(PGconn *conn,
                  char **buffer,
                  int async);

Attempts to obtain another row of data from the server during a <command>COPY</command>. Data is always returned one data row at a time; if only a partial row is available, it is not returned. Successful return of a data row involves allocating a chunk of memory to hold the data. The <parameter>buffer</parameter> parameter must be non-<symbol>NULL</symbol>. <parameter>*buffer</parameter> is set to point to the allocated memory, or to <symbol>NULL</symbol> in cases where no buffer is returned. A non-<symbol>NULL</symbol> result buffer should be freed using <xref linkend="libpq-PQfreemem"/> when no longer needed. COPY期間中、サーバから別の行データの入手を試みます。 常に1度に1つの行データが返されます。 部分的な行のみが利用可能な場合は返されません。 行データの取得に成功することは、そのデータを保持するためのメモリチャンクの割り当てを意味します。 bufferパラメータは非NULLでなければなりません。 *bufferは割り当てられたメモリへのポインタに、バッファが返されなかった場合はNULLに設定されます。 非NULLの結果バッファは、不要になったらPQfreememを使用して解放しなければなりません。

When a row is successfully returned, the return value is the number of data bytes in the row (this will always be greater than zero). The returned string is always null-terminated, though this is probably only useful for textual <command>COPY</command>. A result of zero indicates that the <command>COPY</command> is still in progress, but no row is yet available (this is only possible when <parameter>async</parameter> is true). A result of -1 indicates that the <command>COPY</command> is done. A result of -2 indicates that an error occurred (consult <xref linkend="libpq-PQerrorMessage"/> for the reason). 行の取り込みに成功した時、戻り値は行内のデータのバイト数になります。 (これは常に0より大きくなります。) 返された文字列は常にNULL終端ですが、おそらくテキストCOPYでのみ有用になるでしょう。 ゼロという結果は、COPYが進行中で、行がまだ利用できない状態であることを示します。 (asyncが真の場合にのみ発生することがあります。) -1という結果は、COPYが完了したことを示します。 -2という結果はエラーが発生したことを示します。 (その理由についてはPQerrorMessageを参照してください。)

When <parameter>async</parameter> is true (not zero), <xref linkend="libpq-PQgetCopyData"/> will not block waiting for input; it will return zero if the <command>COPY</command> is still in progress but no complete row is available. (In this case wait for read-ready and then call <xref linkend="libpq-PQconsumeInput"/> before calling <xref linkend="libpq-PQgetCopyData"/> again.) When <parameter>async</parameter> is false (zero), <xref linkend="libpq-PQgetCopyData"/> will block until data is available or the operation completes. asyncが真(非0)の場合、PQgetCopyDataは入力待ちのためのブロックを行いません。 COPY実行中で完全な行を取り出せない場合PQgetCopyDataは0を返します。 (この場合、再試行の前に読み込み準備が整うまで待機してください。 PQconsumeInput を呼び出したかどうかは関係ありません。) asyncが偽(0)の場合、PQgetCopyDataはデータが利用できるようになるまで、もしくは、操作が完了するまでブロックします。

After <xref linkend="libpq-PQgetCopyData"/> returns -1, call <xref linkend="libpq-PQgetResult"/> to obtain the final result status of the <command>COPY</command> command. One can wait for this result to be available in the usual way. Then return to normal operation. PQgetCopyDataが-1を返した後、PQgetResultを呼び出して、COPYコマンドの最終結果状態を取り出してください。 通常の方法で結果が利用できるようになるまで待機しても構いません。 そして、通常の操作に戻ってください。

Reads a newline-terminated line of characters (transmitted by the server) into a buffer string of size <parameter>length</parameter>. 改行で終端する文字列（サーバから送信されたもの）を長さlengthのバッファ用文字列に読み込みます。

int PQgetline(PGconn *conn,
              char *buffer,
              int length);

This function copies up to <parameter>length</parameter>-1 characters into the buffer and converts the terminating newline into a zero byte. <xref linkend="libpq-PQgetline"/> returns <symbol>EOF</symbol> at the end of input, 0 if the entire line has been read, and 1 if the buffer is full but the terminating newline has not yet been read. この関数はバッファにlength-1個までの文字をコピーし、終端の改行を1バイトのゼロに置き換えます。 PQgetlineは、入力の終端ではEOFを、行全体が読み込まれれば0を返します。 そしてまだ終端の改行が読み込まれていないうちにバッファがいっぱいになってしまった場合は1を返します。

Note that the application must check to see if a new line consists of the two characters <literal>\.</literal>, which indicates that the server has finished sending the results of the <command>COPY</command> command. If the application might receive lines that are more than <parameter>length</parameter>-1 characters long, care is needed to be sure it recognizes the <literal>\.</literal> line correctly (and does not, for example, mistake the end of a long data line for a terminator line). アプリケーションは新しく読み込んだ行が、\.という2文字であるかどうか確認しなければいけません。 この2文字は、COPYコマンドの結果をサーバが送信し終えたことを示すものです。 アプリケーションには、仮にlength-1文字より長い行を受け取るようなことがあっても、間違いなく\.行を認識するような配慮が必要です （また例えば長いデータの行の終端を、最終行と取り違えないようにもしてください）。

Reads a row of <command>COPY</command> data (transmitted by the server) into a buffer without blocking. COPYデータ行（サーバから送信されたもの）を、ブロッキングなしでバッファに読み込みます。

int PQgetlineAsync(PGconn *conn,
                   char *buffer,
                   int bufsize);

This function is similar to <xref linkend="libpq-PQgetline"/>, but it can be used by applications that must read <command>COPY</command> data asynchronously, that is, without blocking. Having issued the <command>COPY</command> command and gotten a <literal>PGRES_COPY_OUT</literal> response, the application should call <xref linkend="libpq-PQconsumeInput"/> and <xref linkend="libpq-PQgetlineAsync"/> until the end-of-data signal is detected. PQgetlineと似ていますが、COPYのデータを非同期的に、つまりブロッキングなしで読み出さなければならないアプリケーションで使用することができます。 COPYコマンドを発行し、そしてPGRES_COPY_OUT応答を受け取ったら、アプリケーションはデータ終了の合図を受け取るまでPQconsumeInput とPQgetlineAsyncを呼び出します。

Unlike <xref linkend="libpq-PQgetline"/>, this function takes responsibility for detecting end-of-data. PQgetlineと違い、この関数はデータ終了の検出に対して責任を持ちます。

On each call, <xref linkend="libpq-PQgetlineAsync"/> will return data if a complete data row is available in <application>libpq</application>'s input buffer. Otherwise, no data is returned until the rest of the row arrives. The function returns -1 if the end-of-copy-data marker has been recognized, or 0 if no data is available, or a positive number giving the number of bytes of data returned. If -1 is returned, the caller must next call <xref linkend="libpq-PQendcopy"/>, and then return to normal processing. PQgetlineAsyncの個々の呼び出しでは、libpqの入力バッファ内で完全な行データが利用できる場合にデータを返します。 さもなければ、行の残りが届くまでデータは返されません。 この関数は、コピーデータの終端を示す符号を認識すると-1を、また何もデータがなければ0を、そしてデータを返す場合はそのバイト数を正の値で返します。 もし-1が返されたら、呼び出し側は次にPQendcopyを呼び出さなければいけません。 それから通常の処理に戻ります。

The data returned will not extend beyond a data-row boundary. If possible a whole row will be returned at one time. But if the buffer offered by the caller is too small to hold a row sent by the server, then a partial data row will be returned. With textual data this can be detected by testing whether the last returned byte is <literal>\n</literal> or not. (In a binary <command>COPY</command>, actual parsing of the <command>COPY</command> data format will be needed to make the equivalent determination.) The returned string is not null-terminated. (If you want to add a terminating null, be sure to pass a <parameter>bufsize</parameter> one smaller than the room actually available.) 返されるデータは行データの境界を越えて拡張されることはありません。 可能であれば行全体を一度に返します。 しかし呼び出し側が準備したバッファが少なすぎ、サーバから送られてくる行を保持しておくことができない場合には、分割された行データを返します。 テキストデータでは、これは最後の1バイトが\nかどうかを確認すれば検出できます。 （バイナリCOPYの場合に同様の検出を行うためには、実際にCOPYデータの書式を解析しなければなりません。） なお、返される文字列はNULL終端ではありません。 （NULL終端を後から付け加えるのであれば、実際に確保するバッファサイズ-1をbufsizeとして渡すようにしてください。）

Sends a null-terminated string to the server. Returns 0 if OK and <symbol>EOF</symbol> if unable to send the string. サーバにNULL終端の文字列を送信します。 問題なければ0を返します。 文字列の送信ができなかった場合はEOFを返します。

int PQputline(PGconn *conn,
              const char *string);

The <command>COPY</command> data stream sent by a series of calls to <xref linkend="libpq-PQputline"/> has the same format as that returned by <xref linkend="libpq-PQgetlineAsync"/>, except that applications are not obliged to send exactly one data row per <xref linkend="libpq-PQputline"/> call; it is okay to send a partial line or multiple lines per call. PQputlineの呼び出しによって送信されるCOPYデータストリームは、PQgetlineAsyncで返される書式と同じ書式を持ちます。 ただし、アプリケーションは、PQputline毎に正確に1つのデータ行を送信するように強制されていません。 呼び出し毎に行の一部や複数の行を送信しても問題ありません。

Sends a non-null-terminated string to the server. Returns 0 if OK and <symbol>EOF</symbol> if unable to send the string. NULL終端ではない文字列をサーバに送信します。 問題なければ0を返します。 文字列の送信ができなかった場合はEOFを返します。

int PQputnbytes(PGconn *conn,
                const char *buffer,
                int nbytes);

This is exactly like <xref linkend="libpq-PQputline"/>, except that the data buffer need not be null-terminated since the number of bytes to send is specified directly. Use this procedure when sending binary data. これはまさにPQputlineと同様です。 ただし、直接送信バイト数を指定するため、NULL終端である必要がありません。 バイナリデータを送信する時はこのプロシージャを使用してください。

Synchronizes with the server. サーバと同期します。

int PQendcopy(PGconn *conn);

This function waits until the server has finished the copying. It should either be issued when the last string has been sent to the server using <xref linkend="libpq-PQputline"/> or when the last string has been received from the server using <function>PQgetline</function>. It must be issued or the server will get <quote>out of sync</quote> with the client. Upon return from this function, the server is ready to receive the next SQL command. The return value is 0 on successful completion, nonzero otherwise. (Use <xref linkend="libpq-PQerrorMessage"/> to retrieve details if the return value is nonzero.) この関数はサーバがコピーを完了するのを待ちます。 この関数は、PQputlineを使ったサーバへの文字列送信が完了した時点、あるいはPQgetlineを使ったサーバからの文字列受信が完了した時点のいずれでも呼び出さなければなりません。 これを発行しないと、サーバはクライアントとの「同期がずれた」状態になってしまいます。 この関数から戻った時点で、サーバは次のSQLコマンドを受ける準備が整います。 正常に終了した場合、返り値は0です。 さもなくば、非ゼロです。 （戻り値が非ゼロの場合、PQerrorMessageを使用して詳細を取り出してください。）

When using <xref linkend="libpq-PQgetResult"/>, the application should respond to a <literal>PGRES_COPY_OUT</literal> result by executing <xref linkend="libpq-PQgetline"/> repeatedly, followed by <xref linkend="libpq-PQendcopy"/> after the terminator line is seen. It should then return to the <xref linkend="libpq-PQgetResult"/> loop until <xref linkend="libpq-PQgetResult"/> returns a null pointer. Similarly a <literal>PGRES_COPY_IN</literal> result is processed by a series of <xref linkend="libpq-PQputline"/> calls followed by <xref linkend="libpq-PQendcopy"/>, then return to the <xref linkend="libpq-PQgetResult"/> loop. This arrangement will ensure that a <command>COPY</command> command embedded in a series of <acronym>SQL</acronym> commands will be executed correctly. PQgetResultを使う場合、アプリケーションはPQgetlineを繰り返し呼び出してPGRES_COPY_OUTに応答し、終端行を見つけたら続いてPQendcopyを呼び出さなければなりません。 それから、PQgetResultがNULLポインタを返すまで、PQgetResultのループに戻らなければなりません。 同じように PGRES_COPY_INは連続したPQputlineで処理し、それからPQendcopyで締めくくった後にPQgetResultのループに戻ります。 このようにすることで、一連のSQLコマンド群に含めたCOPYコマンドを確実に、また正しく実行できるはずです。

Older applications are likely to submit a <command>COPY</command> via <xref linkend="libpq-PQexec"/> and assume that the transaction is done after <xref linkend="libpq-PQendcopy"/>. This will work correctly only if the <command>COPY</command> is the only <acronym>SQL</acronym> command in the command string. 比較的古いアプリケーションでは、COPYをPQexecで実行し、PQendcopyの実行でトランザクションは完了する、と想定していることがよくあります。 これはコマンド文字列中のSQLがCOPYだけであった時にのみ正しく動作します。