begriffs open source - ai-pg/blob - full-docs/src/sgml/html/libpq-cancel.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>32.7. Canceling Queries in Progress</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="libpq-single-row-mode.html" title="32.6. Retrieving Query Results in Chunks" /><link rel="next" href="libpq-fastpath.html" title="32.8. The Fast-Path Interface" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">32.7. Canceling Queries in Progress</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="libpq-single-row-mode.html" title="32.6. Retrieving Query Results in Chunks">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="libpq.html" title="Chapter 32. libpq — C Library">Up</a></td><th width="60%" align="center">Chapter 32. <span class="application">libpq</span> — C Library</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="libpq-fastpath.html" title="32.8. The Fast-Path Interface">Next</a></td></tr></table><hr /></div><div class="sect1" id="LIBPQ-CANCEL"><div class="titlepage"><div><div><h2 class="title" style="clear: both">32.7. Canceling Queries in Progress <a href="#LIBPQ-CANCEL" class="id_link">#</a></h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="libpq-cancel.html#LIBPQ-CANCEL-FUNCTIONS">32.7.1. Functions for Sending Cancel Requests</a></span></dt><dt><span class="sect2"><a href="libpq-cancel.html#LIBPQ-CANCEL-DEPRECATED">32.7.2. Obsolete Functions for Sending Cancel Requests</a></span></dt></dl></div><a id="id-1.7.3.14.2" class="indexterm"></a><a id="id-1.7.3.14.3" class="indexterm"></a><div class="sect2" id="LIBPQ-CANCEL-FUNCTIONS"><div class="titlepage"><div><div><h3 class="title">32.7.1. Functions for Sending Cancel Requests <a href="#LIBPQ-CANCEL-FUNCTIONS" class="id_link">#</a></h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQCANCELCREATE"><span class="term"><code class="function">PQcancelCreate</code><a id="id-1.7.3.14.4.2.1.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQCANCELCREATE" class="id_link">#</a></dt><dd><p>
   3        Prepares a connection over which a cancel request can be sent.
   4 </p><pre class="synopsis">
   5 PGcancelConn *PQcancelCreate(PGconn *conn);
   6 </pre><p>
   7       </p><p>
   8        <a class="xref" href="libpq-cancel.html#LIBPQ-PQCANCELCREATE"><code class="function">PQcancelCreate</code></a> creates a
   9        <code class="structname">PGcancelConn</code><a id="id-1.7.3.14.4.2.1.2.2.3" class="indexterm"></a>
  10        object, but it won't instantly start sending a cancel request over this
  11        connection. A cancel request can be sent over this connection in a
  12        blocking manner using <a class="xref" href="libpq-cancel.html#LIBPQ-PQCANCELBLOCKING"><code class="function">PQcancelBlocking</code></a> and in a
  13        non-blocking manner using <a class="xref" href="libpq-cancel.html#LIBPQ-PQCANCELSTART"><code class="function">PQcancelStart</code></a>.
  14        The return value can be passed to <a class="xref" href="libpq-cancel.html#LIBPQ-PQCANCELSTATUS"><code class="function">PQcancelStatus</code></a>
  15        to check if the <code class="structname">PGcancelConn</code> object was
  16        created successfully. The <code class="structname">PGcancelConn</code> object
  17        is an opaque structure that is not meant to be accessed directly by the
  18        application. This <code class="structname">PGcancelConn</code> object can be
  19        used to cancel the query that's running on the original connection in a
  20        thread-safe way.
  21       </p><p>
  22        Many connection parameters of the original client will be reused when
  23        setting up the connection for the cancel request. Importantly, if the
  24        original connection requires encryption of the connection and/or
  25        verification of the target host (using <code class="literal">sslmode</code> or
  26        <code class="literal">gssencmode</code>), then the connection for the cancel
  27        request is made with these same requirements. Any connection options
  28        that are only used during authentication or after authentication of the
  29        client are ignored though, because cancellation requests do not require
  30        authentication and the connection is closed right after the cancellation
  31        request is submitted.
  32       </p><p>
  33        Note that when <code class="function">PQcancelCreate</code> returns a non-null
  34        pointer, you must call <a class="xref" href="libpq-cancel.html#LIBPQ-PQCANCELFINISH"><code class="function">PQcancelFinish</code></a> when you
  35        are finished with it, in order to dispose of the structure and any
  36        associated memory blocks. This must be done even if the cancel request
  37        failed or was abandoned.
  38       </p></dd><dt id="LIBPQ-PQCANCELBLOCKING"><span class="term"><code class="function">PQcancelBlocking</code><a id="id-1.7.3.14.4.2.2.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQCANCELBLOCKING" class="id_link">#</a></dt><dd><p>
  39        Requests that the server abandons processing of the current command
  40        in a blocking manner.
  41 </p><pre class="synopsis">
  42 int PQcancelBlocking(PGcancelConn *cancelConn);
  43 </pre><p>
  44       </p><p>
  45        The request is made over the given <code class="structname">PGcancelConn</code>,
  46        which needs to be created with <a class="xref" href="libpq-cancel.html#LIBPQ-PQCANCELCREATE"><code class="function">PQcancelCreate</code></a>.
  47        The return value of <a class="xref" href="libpq-cancel.html#LIBPQ-PQCANCELBLOCKING"><code class="function">PQcancelBlocking</code></a>
  48        is 1 if the cancel request was successfully
  49        dispatched and 0 if not. If it was unsuccessful, the error message can be
  50        retrieved using <a class="xref" href="libpq-cancel.html#LIBPQ-PQCANCELERRORMESSAGE">
  51       <code class="function">PQcancelErrorMessage</code>
  52
  53      </a>.
  54       </p><p>
  55        Successful dispatch of the cancellation is no guarantee that the request
  56        will have any effect, however. If the cancellation is effective, the
  57        command being canceled will terminate early and return an error result.
  58        If the cancellation fails (say, because the server was already done
  59        processing the command), then there will be no visible result at all.
  60       </p></dd><dt id="LIBPQ-PQCANCELSTART"><span class="term"><code class="function">PQcancelStart</code><a id="id-1.7.3.14.4.2.3.1.2" class="indexterm"></a><br /></span><span class="term"><code class="function">PQcancelPoll</code><a id="id-1.7.3.14.4.2.3.2.2" class="indexterm"></a></span> <a href="#LIBPQ-PQCANCELSTART" class="id_link">#</a></dt><dd><p>
  61        Requests that the server abandons processing of the current command
  62        in a non-blocking manner.
  63 </p><pre class="synopsis">
  64 int PQcancelStart(PGcancelConn *cancelConn);
  65
  66 PostgresPollingStatusType PQcancelPoll(PGcancelConn *cancelConn);
  67 </pre><p>
  68       </p><p>
  69        The request is made over the given <code class="structname">PGcancelConn</code>,
  70        which needs to be created with <a class="xref" href="libpq-cancel.html#LIBPQ-PQCANCELCREATE"><code class="function">PQcancelCreate</code></a>.
  71        The return value of <a class="xref" href="libpq-cancel.html#LIBPQ-PQCANCELSTART"><code class="function">PQcancelStart</code></a>
  72        is 1 if the cancellation request could be started and 0 if not.
  73        If it was unsuccessful, the error message can be
  74        retrieved using <a class="xref" href="libpq-cancel.html#LIBPQ-PQCANCELERRORMESSAGE">
  75       <code class="function">PQcancelErrorMessage</code>
  76
  77      </a>.
  78       </p><p>
  79        If <code class="function">PQcancelStart</code> succeeds, the next stage
  80        is to poll <span class="application">libpq</span> so that it can proceed with
  81        the cancel connection sequence.
  82        Use <a class="xref" href="libpq-cancel.html#LIBPQ-PQCANCELSOCKET"><code class="function">PQcancelSocket</code></a> to obtain the descriptor of the
  83        socket underlying the database connection.
  84        (Caution: do not assume that the socket remains the same
  85        across <code class="function">PQcancelPoll</code> calls.)
  86        Loop thus: If <code class="function">PQcancelPoll(cancelConn)</code> last returned
  87        <code class="symbol">PGRES_POLLING_READING</code>, wait until the socket is ready to
  88        read (as indicated by <code class="function">select()</code>,
  89        <code class="function">poll()</code>, or similar system function).
  90        Then call <code class="function">PQcancelPoll(cancelConn)</code> again.
  91        Conversely, if <code class="function">PQcancelPoll(cancelConn)</code> last returned
  92        <code class="symbol">PGRES_POLLING_WRITING</code>, wait until the socket is ready
  93        to write, then call <code class="function">PQcancelPoll(cancelConn)</code> again.
  94        On the first iteration, i.e., if you have yet to call
  95        <code class="function">PQcancelPoll(cancelConn)</code>, behave as if it last returned
  96        <code class="symbol">PGRES_POLLING_WRITING</code>.  Continue this loop until
  97        <code class="function">PQcancelPoll(cancelConn)</code> returns
  98        <code class="symbol">PGRES_POLLING_FAILED</code>, indicating the connection procedure
  99        has failed, or <code class="symbol">PGRES_POLLING_OK</code>, indicating cancel
 100        request was successfully dispatched.
 101       </p><p>
 102        Successful dispatch of the cancellation is no guarantee that the request
 103        will have any effect, however. If the cancellation is effective, the
 104        command being canceled will terminate early and return an error result.
 105        If the cancellation fails (say, because the server was already done
 106        processing the command), then there will be no visible result at all.
 107       </p><p>
 108        At any time during connection, the status of the connection can be
 109        checked by calling <a class="xref" href="libpq-cancel.html#LIBPQ-PQCANCELSTATUS"><code class="function">PQcancelStatus</code></a>.
 110        If this call returns <code class="symbol">CONNECTION_BAD</code>, then
 111        the cancel procedure has failed; if the call returns
 112        <code class="symbol">CONNECTION_OK</code>, then cancel request was
 113        successfully dispatched.
 114        Both of these states are equally detectable from the return value of
 115        <code class="function">PQcancelPoll</code>, described above.
 116        Other states might also occur during (and only during) an asynchronous
 117        connection procedure.
 118        These indicate the current stage of the connection procedure and might
 119        be useful to provide feedback to the user for example.
 120        These statuses are:
 121
 122        </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-CANCEL-CONNECTION-ALLOCATED"><span class="term"><code class="symbol">CONNECTION_ALLOCATED</code></span> <a href="#LIBPQ-CANCEL-CONNECTION-ALLOCATED" class="id_link">#</a></dt><dd><p>
 123            Waiting for a call to <a class="xref" href="libpq-cancel.html#LIBPQ-PQCANCELSTART"><code class="function">PQcancelStart</code></a> or
 124            <a class="xref" href="libpq-cancel.html#LIBPQ-PQCANCELBLOCKING"><code class="function">PQcancelBlocking</code></a>, to actually open the
 125            socket. This is the connection state right after
 126            calling <a class="xref" href="libpq-cancel.html#LIBPQ-PQCANCELCREATE"><code class="function">PQcancelCreate</code></a>
 127            or <a class="xref" href="libpq-cancel.html#LIBPQ-PQCANCELRESET"><code class="function">PQcancelReset</code></a>. No connection to the
 128            server has been initiated yet at this point. To actually start
 129            sending the cancel request use <a class="xref" href="libpq-cancel.html#LIBPQ-PQCANCELSTART"><code class="function">PQcancelStart</code></a> or
 130            <a class="xref" href="libpq-cancel.html#LIBPQ-PQCANCELBLOCKING"><code class="function">PQcancelBlocking</code></a>.
 131           </p></dd><dt id="LIBPQ-CANCEL-CONNECTION-STARTED"><span class="term"><code class="symbol">CONNECTION_STARTED</code></span> <a href="#LIBPQ-CANCEL-CONNECTION-STARTED" class="id_link">#</a></dt><dd><p>
 132            Waiting for connection to be made.
 133           </p></dd><dt id="LIBPQ-CANCEL-CONNECTION-MADE"><span class="term"><code class="symbol">CONNECTION_MADE</code></span> <a href="#LIBPQ-CANCEL-CONNECTION-MADE" class="id_link">#</a></dt><dd><p>
 134            Connection OK; waiting to send.
 135           </p></dd><dt id="LIBPQ-CANCEL-CONNECTION-AWAITING-RESPONSE"><span class="term"><code class="symbol">CONNECTION_AWAITING_RESPONSE</code></span> <a href="#LIBPQ-CANCEL-CONNECTION-AWAITING-RESPONSE" class="id_link">#</a></dt><dd><p>
 136            Waiting for a response from the server.
 137           </p></dd><dt id="LIBPQ-CANCEL-CONNECTION-SSL-STARTUP"><span class="term"><code class="symbol">CONNECTION_SSL_STARTUP</code></span> <a href="#LIBPQ-CANCEL-CONNECTION-SSL-STARTUP" class="id_link">#</a></dt><dd><p>
 138            Negotiating SSL encryption.
 139           </p></dd><dt id="LIBPQ-CANCEL-CONNECTION-GSS-STARTUP"><span class="term"><code class="symbol">CONNECTION_GSS_STARTUP</code></span> <a href="#LIBPQ-CANCEL-CONNECTION-GSS-STARTUP" class="id_link">#</a></dt><dd><p>
 140            Negotiating GSS encryption.
 141           </p></dd></dl></div><p>
 142
 143        Note that, although these constants will remain (in order to maintain
 144        compatibility), an application should never rely upon these occurring in a
 145        particular order, or at all, or on the status always being one of these
 146        documented values. An application might do something like this:
 147 </p><pre class="programlisting">
 148 switch(PQcancelStatus(conn))
 149 {
 150         case CONNECTION_STARTED:
 151             feedback = "Connecting...";
 152             break;
 153
 154         case CONNECTION_MADE:
 155             feedback = "Connected to server...";
 156             break;
 157 .
 158 .
 159 .
 160         default:
 161             feedback = "Connecting...";
 162 }
 163 </pre><p>
 164       </p><p>
 165        The <code class="literal">connect_timeout</code> connection parameter is ignored
 166        when using <code class="function">PQcancelPoll</code>; it is the application's
 167        responsibility to decide whether an excessive amount of time has elapsed.
 168        Otherwise, <code class="function">PQcancelStart</code> followed by a
 169        <code class="function">PQcancelPoll</code> loop is equivalent to
 170        <a class="xref" href="libpq-cancel.html#LIBPQ-PQCANCELBLOCKING"><code class="function">PQcancelBlocking</code></a>.
 171       </p></dd><dt id="LIBPQ-PQCANCELSTATUS"><span class="term"><code class="function">PQcancelStatus</code><a id="id-1.7.3.14.4.2.4.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQCANCELSTATUS" class="id_link">#</a></dt><dd><p>
 172        Returns the status of the cancel connection.
 173 </p><pre class="synopsis">
 174 ConnStatusType PQcancelStatus(const PGcancelConn *cancelConn);
 175 </pre><p>
 176       </p><p>
 177        The status can be one of a number of values.  However, only three of
 178        these are seen outside of an asynchronous cancel procedure:
 179        <code class="symbol">CONNECTION_ALLOCATED</code>,
 180        <code class="symbol">CONNECTION_OK</code> and
 181        <code class="symbol">CONNECTION_BAD</code>. The initial state of a
 182        <code class="function">PGcancelConn</code> that's successfully created using
 183        <a class="xref" href="libpq-cancel.html#LIBPQ-PQCANCELCREATE"><code class="function">PQcancelCreate</code></a> is <code class="symbol">CONNECTION_ALLOCATED</code>.
 184        A cancel request that was successfully dispatched
 185        has the status <code class="symbol">CONNECTION_OK</code>.  A failed
 186        cancel attempt is signaled by status
 187        <code class="symbol">CONNECTION_BAD</code>.  An OK status will
 188        remain so until <a class="xref" href="libpq-cancel.html#LIBPQ-PQCANCELFINISH"><code class="function">PQcancelFinish</code></a> or
 189        <a class="xref" href="libpq-cancel.html#LIBPQ-PQCANCELRESET"><code class="function">PQcancelReset</code></a> is called.
 190       </p><p>
 191        See the entry for <a class="xref" href="libpq-cancel.html#LIBPQ-PQCANCELSTART"><code class="function">PQcancelStart</code></a> with regards
 192        to other status codes that might be returned.
 193       </p><p>
 194        Successful dispatch of the cancellation is no guarantee that the request
 195        will have any effect, however. If the cancellation is effective, the
 196        command being canceled will terminate early and return an error result.
 197        If the cancellation fails (say, because the server was already done
 198        processing the command), then there will be no visible result at all.
 199       </p></dd><dt id="LIBPQ-PQCANCELSOCKET"><span class="term"><code class="function">PQcancelSocket</code><a id="id-1.7.3.14.4.2.5.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQCANCELSOCKET" class="id_link">#</a></dt><dd><p>
 200        Obtains the file descriptor number of the cancel connection socket to
 201        the server.
 202 </p><pre class="synopsis">
 203 int PQcancelSocket(const PGcancelConn *cancelConn);
 204 </pre><p>
 205       </p><p>
 206        A valid descriptor will be greater than or equal to 0;
 207        a result of -1 indicates that no server connection is currently open.
 208        This might change as a result of calling any of the functions
 209        in this section on the <code class="structname">PGcancelConn</code>
 210        (except for <a class="xref" href="libpq-cancel.html#LIBPQ-PQCANCELERRORMESSAGE">
 211       <code class="function">PQcancelErrorMessage</code>
 212
 213      </a> and
 214        <code class="function">PQcancelSocket</code> itself).
 215       </p></dd><dt id="LIBPQ-PQCANCELERRORMESSAGE"><span class="term">
 216       <code class="function">PQcancelErrorMessage</code><a id="id-1.7.3.14.4.2.6.1.2" class="indexterm"></a>
 217       <a id="id-1.7.3.14.4.2.6.1.3" class="indexterm"></a>
 218      </span> <a href="#LIBPQ-PQCANCELERRORMESSAGE" class="id_link">#</a></dt><dd><p>
 219        Returns the error message most recently generated by an
 220        operation on the cancel connection.
 221 </p><pre class="synopsis">
 222 char *PQcancelErrorMessage(const PGcancelConn *cancelconn);
 223 </pre><p>
 224       </p><p>
 225        Nearly all <span class="application">libpq</span> functions that take a
 226        <code class="structname">PGcancelConn</code> will set a message for
 227        <a class="xref" href="libpq-cancel.html#LIBPQ-PQCANCELERRORMESSAGE">
 228       <code class="function">PQcancelErrorMessage</code>
 229
 230      </a> if they fail.
 231        Note that by <span class="application">libpq</span> convention,
 232        a nonempty <a class="xref" href="libpq-cancel.html#LIBPQ-PQCANCELERRORMESSAGE">
 233       <code class="function">PQcancelErrorMessage</code>
 234
 235      </a> result
 236        can consist of multiple lines, and will include a trailing newline.
 237        The caller should not free the result directly.
 238        It will be freed when the associated
 239        <code class="structname">PGcancelConn</code> handle is passed to
 240        <a class="xref" href="libpq-cancel.html#LIBPQ-PQCANCELFINISH"><code class="function">PQcancelFinish</code></a>.  The result string should not be
 241        expected to remain the same across operations on the
 242        <code class="literal">PGcancelConn</code> structure.
 243       </p></dd><dt id="LIBPQ-PQCANCELFINISH"><span class="term"><code class="function">PQcancelFinish</code><a id="id-1.7.3.14.4.2.7.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQCANCELFINISH" class="id_link">#</a></dt><dd><p>
 244        Closes the cancel connection (if it did not finish sending the
 245        cancel request yet). Also frees memory used by the
 246        <code class="structname">PGcancelConn</code> object.
 247 </p><pre class="synopsis">
 248 void PQcancelFinish(PGcancelConn *cancelConn);
 249 </pre><p>
 250       </p><p>
 251        Note that even if the cancel attempt fails (as
 252        indicated by <a class="xref" href="libpq-cancel.html#LIBPQ-PQCANCELSTATUS"><code class="function">PQcancelStatus</code></a>), the
 253        application should call <a class="xref" href="libpq-cancel.html#LIBPQ-PQCANCELFINISH"><code class="function">PQcancelFinish</code></a>
 254        to free the memory used by the <code class="structname">PGcancelConn</code>
 255        object.
 256        The <code class="structname">PGcancelConn</code> pointer must not be used
 257        again after <a class="xref" href="libpq-cancel.html#LIBPQ-PQCANCELFINISH"><code class="function">PQcancelFinish</code></a> has been called.
 258       </p></dd><dt id="LIBPQ-PQCANCELRESET"><span class="term"><code class="function">PQcancelReset</code><a id="id-1.7.3.14.4.2.8.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQCANCELRESET" class="id_link">#</a></dt><dd><p>
 259        Resets the <code class="symbol">PGcancelConn</code> so it can be reused for a new
 260        cancel connection.
 261 </p><pre class="synopsis">
 262 void PQcancelReset(PGcancelConn *cancelConn);
 263 </pre><p>
 264       </p><p>
 265        If the <code class="symbol">PGcancelConn</code> is currently used to send a cancel
 266        request, then this connection is closed. It will then prepare the
 267        <code class="symbol">PGcancelConn</code> object such that it can be used to send a
 268        new cancel request.
 269       </p><p>
 270        This can be used to create one <code class="structname">PGcancelConn</code>
 271        for a <code class="structname">PGconn</code> and reuse it multiple times
 272        throughout the lifetime of the original <code class="structname">PGconn</code>.
 273       </p></dd></dl></div></div><div class="sect2" id="LIBPQ-CANCEL-DEPRECATED"><div class="titlepage"><div><div><h3 class="title">32.7.2. Obsolete Functions for Sending Cancel Requests <a href="#LIBPQ-CANCEL-DEPRECATED" class="id_link">#</a></h3></div></div></div><p>
 274     These functions represent older methods of sending cancel requests.
 275     Although they still work, they are deprecated due to not sending the cancel
 276     requests in an encrypted manner, even when the original connection
 277     specified <code class="literal">sslmode</code> or <code class="literal">gssencmode</code> to
 278     require encryption. Thus these older methods are heavily discouraged from
 279     being used in new code, and it is recommended to change existing code to
 280     use the new functions instead.
 281    </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQGETCANCEL"><span class="term"><code class="function">PQgetCancel</code><a id="id-1.7.3.14.5.3.1.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQGETCANCEL" class="id_link">#</a></dt><dd><p>
 282        Creates a data structure containing the information needed to cancel
 283        a command using <a class="xref" href="libpq-cancel.html#LIBPQ-PQCANCEL"><code class="function">PQcancel</code></a>.
 284 </p><pre class="synopsis">
 285 PGcancel *PQgetCancel(PGconn *conn);
 286 </pre><p>
 287       </p><p>
 288        <a class="xref" href="libpq-cancel.html#LIBPQ-PQGETCANCEL"><code class="function">PQgetCancel</code></a> creates a
 289        <code class="structname">PGcancel</code><a id="id-1.7.3.14.5.3.1.2.2.3" class="indexterm"></a>
 290        object given a <code class="structname">PGconn</code> connection object.
 291        It will return <code class="symbol">NULL</code> if the given <em class="parameter"><code>conn</code></em>
 292        is <code class="symbol">NULL</code> or an invalid connection.
 293        The <code class="structname">PGcancel</code> object is an opaque
 294        structure that is not meant to be accessed directly by the
 295        application; it can only be passed to <a class="xref" href="libpq-cancel.html#LIBPQ-PQCANCEL"><code class="function">PQcancel</code></a>
 296        or <a class="xref" href="libpq-cancel.html#LIBPQ-PQFREECANCEL"><code class="function">PQfreeCancel</code></a>.
 297       </p></dd><dt id="LIBPQ-PQFREECANCEL"><span class="term"><code class="function">PQfreeCancel</code><a id="id-1.7.3.14.5.3.2.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQFREECANCEL" class="id_link">#</a></dt><dd><p>
 298        Frees a data structure created by <a class="xref" href="libpq-cancel.html#LIBPQ-PQGETCANCEL"><code class="function">PQgetCancel</code></a>.
 299 </p><pre class="synopsis">
 300 void PQfreeCancel(PGcancel *cancel);
 301 </pre><p>
 302       </p><p>
 303        <a class="xref" href="libpq-cancel.html#LIBPQ-PQFREECANCEL"><code class="function">PQfreeCancel</code></a> frees a data object previously created
 304        by <a class="xref" href="libpq-cancel.html#LIBPQ-PQGETCANCEL"><code class="function">PQgetCancel</code></a>.
 305       </p></dd><dt id="LIBPQ-PQCANCEL"><span class="term"><code class="function">PQcancel</code><a id="id-1.7.3.14.5.3.3.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQCANCEL" class="id_link">#</a></dt><dd><p>
 306        <a class="xref" href="libpq-cancel.html#LIBPQ-PQCANCEL"><code class="function">PQcancel</code></a> is a deprecated and insecure
 307        variant of <a class="xref" href="libpq-cancel.html#LIBPQ-PQCANCELBLOCKING"><code class="function">PQcancelBlocking</code></a>, but one that can be
 308        used safely from within a signal handler.
 309 </p><pre class="synopsis">
 310 int PQcancel(PGcancel *cancel, char *errbuf, int errbufsize);
 311 </pre><p>
 312       </p><p>
 313        <a class="xref" href="libpq-cancel.html#LIBPQ-PQCANCEL"><code class="function">PQcancel</code></a> only exists because of backwards
 314        compatibility reasons. <a class="xref" href="libpq-cancel.html#LIBPQ-PQCANCELBLOCKING"><code class="function">PQcancelBlocking</code></a> should be
 315        used instead. The only benefit that <a class="xref" href="libpq-cancel.html#LIBPQ-PQCANCEL"><code class="function">PQcancel</code></a> has
 316        is that it can be safely invoked from a signal handler, if the
 317        <em class="parameter"><code>errbuf</code></em> is a local variable in the signal handler.
 318        However, this is generally not considered a big enough benefit to be
 319        worth the security issues that this function has.
 320       </p><p>
 321        The <code class="structname">PGcancel</code> object is read-only as far as
 322        <a class="xref" href="libpq-cancel.html#LIBPQ-PQCANCEL"><code class="function">PQcancel</code></a> is concerned, so it can also be invoked
 323        from a thread that is separate from the one manipulating the
 324        <code class="structname">PGconn</code> object.
 325       </p><p>
 326        The return value of <a class="xref" href="libpq-cancel.html#LIBPQ-PQCANCEL"><code class="function">PQcancel</code></a> is 1 if the
 327        cancel request was successfully dispatched and 0 if not.
 328        If not, <em class="parameter"><code>errbuf</code></em> is filled with an explanatory
 329        error message.
 330        <em class="parameter"><code>errbuf</code></em> must be a char array of size
 331        <em class="parameter"><code>errbufsize</code></em> (the recommended size is 256 bytes).
 332       </p></dd></dl></div><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQREQUESTCANCEL"><span class="term"><code class="function">PQrequestCancel</code><a id="id-1.7.3.14.5.4.1.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQREQUESTCANCEL" class="id_link">#</a></dt><dd><p>
 333        <a class="xref" href="libpq-cancel.html#LIBPQ-PQREQUESTCANCEL"><code class="function">PQrequestCancel</code></a> is a deprecated and insecure
 334        variant of <a class="xref" href="libpq-cancel.html#LIBPQ-PQCANCELBLOCKING"><code class="function">PQcancelBlocking</code></a>.
 335 </p><pre class="synopsis">
 336 int PQrequestCancel(PGconn *conn);
 337 </pre><p>
 338       </p><p>
 339        <a class="xref" href="libpq-cancel.html#LIBPQ-PQREQUESTCANCEL"><code class="function">PQrequestCancel</code></a> only exists because of backwards
 340        compatibility reasons. <a class="xref" href="libpq-cancel.html#LIBPQ-PQCANCELBLOCKING"><code class="function">PQcancelBlocking</code></a> should be
 341        used instead. There is no benefit to using
 342        <a class="xref" href="libpq-cancel.html#LIBPQ-PQREQUESTCANCEL"><code class="function">PQrequestCancel</code></a> over
 343        <a class="xref" href="libpq-cancel.html#LIBPQ-PQCANCELBLOCKING"><code class="function">PQcancelBlocking</code></a>.
 344       </p><p>
 345        Requests that the server abandon processing of the current
 346        command.  It operates directly on the
 347        <code class="structname">PGconn</code> object, and in case of failure stores the
 348        error message in the <code class="structname">PGconn</code> object (whence it can
 349        be retrieved by <a class="xref" href="libpq-status.html#LIBPQ-PQERRORMESSAGE">
 350       <code class="function">PQerrorMessage</code>
 351
 352      </a>).  Although
 353        the functionality is the same, this approach is not safe within
 354        multiple-thread programs or signal handlers, since it is possible
 355        that overwriting the <code class="structname">PGconn</code>'s error message will
 356        mess up the operation currently in progress on the connection.
 357       </p></dd></dl></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="libpq-single-row-mode.html" title="32.6. Retrieving Query Results in Chunks">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="libpq.html" title="Chapter 32. libpq — C Library">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="libpq-fastpath.html" title="32.8. The Fast-Path Interface">Next</a></td></tr><tr><td width="40%" align="left" valign="top">32.6. Retrieving Query Results in Chunks </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 32.8. The Fast-Path Interface</td></tr></table></div></body></html>