copy; so the per-column
       formats always match the overall format at present.)
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>

  <sect2 id="libpq-copy-send">
   <title>Functions for Sending <command>COPY</command> Data</title>

   <para>
    These functions are used to send data during <literal>COPY FROM
    STDIN</literal>.  They will fail if called when the connection is not in
    <literal>COPY_IN</literal> state.
   </para>

   <variablelist>
    <varlistentry id="libpq-PQputCopyData">
     <term><function>PQputCopyData</function><indexterm><primary>PQputCopyData</primary></indexterm></term>

     <listitem>
      <para>
       Sends data to the server during <literal>COPY_IN</literal> state.
<synopsis>
int PQputCopyData(PGconn *conn,
                  const char *buffer,
                  int nbytes);
</synopsis>
      </para>

      <para>
       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.)
      </para>

      <para>
       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.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry id="libpq-PQputCopyEnd">
     <term><function>PQputCopyEnd</function><indexterm><primary>PQputCopyEnd</primary></indexterm></term>

     <listitem>
      <para>
       Sends end-of-data indication to the server during <literal>COPY_IN</literal> state.
<synopsis>
int PQputCopyEnd(PGconn *conn,
                 const char *errormsg);
</synopsis>
      </para>

      <para>
       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.)
      </para>

      <para>
       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.
      </para>

      <para>
       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.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>