fields
   are historical; in particular, channel names need not have anything to
   do with relation names.)
  </para>

  <para>
   <xref linkend="libpq-example-2"/> gives a sample program that illustrates
   the use of asynchronous notification.
  </para>

  <para>
   <function>PQnotifies</function> does not actually read data from the
   server; it just returns messages previously absorbed by another
   <application>libpq</application> function.  In ancient releases of
   <application>libpq</application>, the only way to ensure timely receipt
   of <command>NOTIFY</command> messages was to constantly submit commands, even
   empty ones, and then check <function>PQnotifies</function> after each
   <xref linkend="libpq-PQexec"/>.  While this still works, it is deprecated
   as a waste of processing power.
  </para>

  <para>
   A better way to check for <command>NOTIFY</command> messages when you have no
   useful commands to execute is to call
   <xref linkend="libpq-PQconsumeInput"/>, then check
   <function>PQnotifies</function>.  You can use
   <function>select()</function> to wait for data to arrive from the
   server, thereby using no <acronym>CPU</acronym> power unless there is
   something to do.  (See <xref linkend="libpq-PQsocket"/> to obtain the file
   descriptor number to use with <function>select()</function>.) Note that
   this will work OK whether you submit commands with
   <xref linkend="libpq-PQsendQuery"/>/<xref linkend="libpq-PQgetResult"/> or
   simply use <xref linkend="libpq-PQexec"/>.  You should, however, remember
   to check <function>PQnotifies</function> after each
   <xref linkend="libpq-PQgetResult"/> or <xref linkend="libpq-PQexec"/>, to
   see if any notifications came in during the processing of the command.
  </para>

 </sect1>

 <sect1 id="libpq-copy">
  <title>Functions Associated with the <command>COPY</command> Command</title>

  <indexterm zone="libpq-copy">
   <primary>COPY</primary>
   <secondary>with libpq</secondary>
  </indexterm>

  <para>
   The <command>COPY</command> command in
   <productname>PostgreSQL</productname> has options to read from or write
   to the network connection used by <application>libpq</application>.
   The functions described in this section allow applications to take
   advantage of this capability by supplying or consuming copied data.
  </para>

  <para>
   The overall process is that the application first issues the SQL
   <command>COPY</command> command via <xref linkend="libpq-PQexec"/> or one
   of the equivalent functions.  The response to this (if there is no
   error in the command) will be a <structname>PGresult</structname> object bearing
   a status code of <literal>PGRES_COPY_OUT</literal> or
   <literal>PGRES_COPY_IN</literal> (depending on the specified copy
   direction).  The application should then use the functions of this
   section to receive or transmit data rows.  When the data transfer is
   complete, another <structname>PGresult</structname> object is returned to indicate
   success or failure of the transfer.  Its status will be
   <literal>PGRES_COMMAND_OK</literal> for success or
   <literal>PGRES_FATAL_ERROR</literal> if some problem was encountered.
   At this point further SQL commands can be issued via
   <xref linkend="libpq-PQexec"/>.  (It is not possible to execute other SQL
   commands using the same connection while the <command>COPY</command>
   operation is in progress.)
  </para>

  <para>
   If a <command>COPY</command> command is issued via
   <xref linkend="libpq-PQexec"/> in a string that could contain additional
   commands, the application must continue fetching results via
   <xref linkend="libpq-PQgetResult"/> after completing the <command>COPY</command>
   sequence.  Only when <xref linkend="libpq-PQgetResult"/> returns
   <symbol>NULL</symbol> is it certain that the <xref linkend="libpq-PQexec"/>
   command string is done and it is safe to issue more commands.
  </para>

  <para>
   The functions of this section