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"/> creates a
       <structname>PGcancel</structname><indexterm><primary>PGcancel</primary></indexterm>
       object given a <structname>PGconn</structname> connection object.
       It will return <symbol>NULL</symbol> if the given <parameter>conn</parameter>
       is <symbol>NULL</symbol> or an invalid connection.
       The <structname>PGcancel</structname> object is an opaque
       structure that is not meant to be accessed directly by the
       application; it can only be passed to <xref linkend="libpq-PQcancel"/>
       or <xref linkend="libpq-PQfreeCancel"/>.
      </para>
     </listitem>
    </varlistentry>

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

     <listitem>
      <para>
       Frees a data structure created by <xref linkend="libpq-PQgetCancel"/>.
<synopsis>
void PQfreeCancel(PGcancel *cancel);
</synopsis>
      </para>

      <para>
       <xref linkend="libpq-PQfreeCancel"/> frees a data object previously created
       by <xref linkend="libpq-PQgetCancel"/>.
      </para>
     </listitem>
    </varlistentry>

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

     <listitem>
      <para>
       <xref linkend="libpq-PQcancel"/> is a deprecated and insecure
       variant of <xref linkend="libpq-PQcancelBlocking"/>, but one that can be
       used safely from within a signal handler.
<synopsis>
int PQcancel(PGcancel *cancel, char *errbuf, int errbufsize);
</synopsis>
      </para>

      <para>
       <xref linkend="libpq-PQcancel"/> only exists because of backwards
       compatibility reasons. <xref linkend="libpq-PQcancelBlocking"/> should be
       used instead. The only benefit that <xref linkend="libpq-PQcancel"/> has
       is that it can be safely invoked from a signal handler, if the
       <parameter>errbuf</parameter> is a local variable in the signal handler.
       However, this is generally not considered a big enough benefit to be
       worth the security issues that this function has.
      </para>

      <para>
       The <structname>PGcancel</structname> object is read-only as far as
       <xref linkend="libpq-PQcancel"/> is concerned, so it can also be invoked
       from a thread that is separate from the one manipulating the
       <structname>PGconn</structname> object.
      </para>

      <para>
       The return value of <xref linkend="libpq-PQcancel"/> is 1 if the
       cancel request was successfully dispatched and 0 if not.
       If not, <parameter>errbuf</parameter> is filled with an explanatory
       error message.
       <parameter>errbuf</parameter> must be a char array of size
       <parameter>errbufsize</parameter> (the recommended size is 256 bytes).
      </para>
     </listitem>
    </varlistentry>
   </variablelist>

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