error message most recently generated by an
       operation on the cancel connection.
<synopsis>
char *PQcancelErrorMessage(const PGcancelConn *cancelconn);
</synopsis>
      </para>

      <para>
       Nearly all <application>libpq</application> functions that take a
       <structname>PGcancelConn</structname> will set a message for
       <xref linkend="libpq-PQcancelErrorMessage"/> if they fail.
       Note that by <application>libpq</application> convention,
       a nonempty <xref linkend="libpq-PQcancelErrorMessage"/> result
       can consist of multiple lines, and will include a trailing newline.
       The caller should not free the result directly.
       It will be freed when the associated
       <structname>PGcancelConn</structname> handle is passed to
       <xref linkend="libpq-PQcancelFinish"/>.  The result string should not be
       expected to remain the same across operations on the
       <literal>PGcancelConn</literal> structure.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry id="libpq-PQcancelFinish">
     <term><function>PQcancelFinish</function><indexterm><primary>PQcancelFinish</primary></indexterm></term>
     <listitem>
      <para>
       Closes the cancel connection (if it did not finish sending the
       cancel request yet). Also frees memory used by the
       <structname>PGcancelConn</structname> object.
<synopsis>
void PQcancelFinish(PGcancelConn *cancelConn);
</synopsis>
      </para>

      <para>
       Note that even if the cancel attempt fails (as
       indicated by <xref linkend="libpq-PQcancelStatus"/>), the
       application should call <xref linkend="libpq-PQcancelFinish"/>
       to free the memory used by the <structname>PGcancelConn</structname>
       object.
       The <structname>PGcancelConn</structname> pointer must not be used
       again after <xref linkend="libpq-PQcancelFinish"/> has been called.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry id="libpq-PQcancelReset">
     <term><function>PQcancelReset</function><indexterm><primary>PQcancelReset</primary></indexterm></term>
     <listitem>
      <para>
       Resets the <symbol>PGcancelConn</symbol> so it can be reused for a new
       cancel connection.
<synopsis>
void PQcancelReset(PGcancelConn *cancelConn);
</synopsis>
      </para>

      <para>
       If the <symbol>PGcancelConn</symbol> is currently used to send a cancel
       request, then this connection is closed. It will then prepare the
       <symbol>PGcancelConn</symbol> object such that it can be used to send a
       new cancel request.
      </para>

      <para>
       This can be used to create one <structname>PGcancelConn</structname>
       for a <structname>PGconn</structname> and reuse it multiple times
       throughout the lifetime of the original <structname>PGconn</structname>.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </sect2>

  <sect2 id="libpq-cancel-deprecated">
   <title>Obsolete Functions for Sending Cancel Requests</title>

   <para>
    These functions represent older methods of sending cancel requests.
    Although they still work, they are deprecated due to not sending the cancel
    requests in an encrypted manner, even when the original connection
    specified <literal>sslmode</literal> or <literal>gssencmode</literal> to
    require encryption. Thus these older methods are heavily discouraged from
    being used in new code, and it is recommended to change existing code to
    use the new functions instead.
   </para>

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

     <listitem>
      <para>
       Creates a data structure containing the information needed to cancel
       a command using <xref linkend="libpq-PQcancel"/>.
<synopsis>
PGcancel *PQgetCancel(PGconn *conn);
</synopsis>
      </para>

      <para>
       <xref linkend="libpq-PQgetCancel"/>