</para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>

  <caution>
   <para>
    While processing a query, the server may return some rows and then
    encounter an error, causing the query to be aborted.  Ordinarily,
    <application>libpq</application> discards any such rows and reports only the
    error.  But in single-row or chunked mode, some rows may have already
    been returned to the application. Hence, the application will see some
    <literal>PGRES_SINGLE_TUPLE</literal> or <literal>PGRES_TUPLES_CHUNK</literal>
    <structname>PGresult</structname>
    objects followed by a <literal>PGRES_FATAL_ERROR</literal> object.  For
    proper transactional behavior, the application must be designed to
    discard or undo whatever has been done with the previously-processed
    rows, if the query ultimately fails.
   </para>
  </caution>

 </sect1>

 <sect1 id="libpq-cancel">
  <title>Canceling Queries in Progress</title>

  <indexterm zone="libpq-cancel">
   <primary>canceling SQL queries</primary>
  </indexterm>
  <indexterm zone="libpq-cancel">
   <primary>query cancellation</primary>
  </indexterm>

  <sect2 id="libpq-cancel-functions">
   <title>Functions for Sending Cancel Requests</title>
   <variablelist>
    <varlistentry id="libpq-PQcancelCreate">
     <term><function>PQcancelCreate</function><indexterm><primary>PQcancelCreate</primary></indexterm></term>

     <listitem>
      <para>
       Prepares a connection over which a cancel request can be sent.
<synopsis>
PGcancelConn *PQcancelCreate(PGconn *conn);
</synopsis>
      </para>

      <para>
       <xref linkend="libpq-PQcancelCreate"/> creates a
       <structname>PGcancelConn</structname><indexterm><primary>PGcancelConn</primary></indexterm>
       object, but it won't instantly start sending a cancel request over this
       connection. A cancel request can be sent over this connection in a
       blocking manner using <xref linkend="libpq-PQcancelBlocking"/> and in a
       non-blocking manner using <xref linkend="libpq-PQcancelStart"/>.
       The return value can be passed to <xref linkend="libpq-PQcancelStatus"/>
       to check if the <structname>PGcancelConn</structname> object was
       created successfully. The <structname>PGcancelConn</structname> object
       is an opaque structure that is not meant to be accessed directly by the
       application. This <structname>PGcancelConn</structname> object can be
       used to cancel the query that's running on the original connection in a
       thread-safe way.
      </para>

      <para>
       Many connection parameters of the original client will be reused when
       setting up the connection for the cancel request. Importantly, if the
       original connection requires encryption of the connection and/or
       verification of the target host (using <literal>sslmode</literal> or
       <literal>gssencmode</literal>), then the connection for the cancel
       request is made with these same requirements. Any connection options
       that are only used during authentication or after authentication of the
       client are ignored though, because cancellation requests do not require
       authentication and the connection is closed right after the cancellation
       request is submitted.
      </para>

      <para>
       Note that when <function>PQcancelCreate</function> returns a non-null
       pointer, you must call <xref linkend="libpq-PQcancelFinish"/> when you
       are finished with it, in order to dispose of the structure and any
       associated memory blocks. This must be done even if the cancel request
       failed or was abandoned.
      </para>
     </listitem>
    </varlistentry>

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

     <listitem>
      <para>
       Requests that the server abandons processing of the current command
       in