</para>

  <para>
   To pass a NULL argument to the function, set
   the <parameter>len</parameter> field of that parameter structure
   to <literal>-1</literal>; the <parameter>isint</parameter>
   and <parameter>u</parameter> fields are then irrelevant.
  </para>

  <para>
   If the function returns NULL, <parameter>*result_len</parameter> is set
   to <literal>-1</literal>, and <parameter>*result_buf</parameter> is not
   modified.
  </para>

  <para>
   Note that it is not possible to handle set-valued results when using
   this interface.  Also, the function must be a plain function, not an
   aggregate, window function, or procedure.
  </para>

 </sect1>

 <sect1 id="libpq-notify">
  <title>Asynchronous Notification</title>

  <indexterm zone="libpq-notify">
   <primary>NOTIFY</primary>
   <secondary>in libpq</secondary>
  </indexterm>

  <para>
   <productname>PostgreSQL</productname> offers asynchronous notification
   via the <command>LISTEN</command> and <command>NOTIFY</command>
   commands.  A client session registers its interest in a particular
   notification channel with the <command>LISTEN</command> command (and
   can stop listening with the <command>UNLISTEN</command> command).  All
   sessions listening on a particular channel will be notified
   asynchronously when a <command>NOTIFY</command> command with that
   channel name is executed by any session. A <quote>payload</quote> string can
   be passed to communicate additional data to the listeners.
  </para>

  <para>
   <application>libpq</application> applications submit
   <command>LISTEN</command>, <command>UNLISTEN</command>,
   and <command>NOTIFY</command> commands as
   ordinary SQL commands.  The arrival of <command>NOTIFY</command>
   messages can subsequently be detected by calling
   <function id="libpq-PQnotifies">PQnotifies</function>.<indexterm><primary>PQnotifies</primary></indexterm>
  </para>

  <para>
   The function <function>PQnotifies</function> returns the next notification
   from a list of unhandled notification messages received from the server.
   It returns a null pointer if there are no pending notifications.  Once a
   notification is returned from <function>PQnotifies</function>, it is considered
   handled and will be removed from the list of notifications.

<synopsis>
PGnotify *PQnotifies(PGconn *conn);

typedef struct pgNotify
{
    char *relname;              /* notification channel name */
    int  be_pid;                /* process ID of notifying server process */
    char *extra;                /* notification payload string */
} PGnotify;
</synopsis>

   After processing a <structname>PGnotify</structname> object returned
   by <function>PQnotifies</function>, be sure to free it with
   <xref linkend="libpq-PQfreemem"/>.  It is sufficient to free the
   <structname>PGnotify</structname> pointer; the
   <structfield>relname</structfield> and <structfield>extra</structfield>
   fields do not represent separate allocations.  (The names of these 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"/>,