doc/src/sgml/ref/unlisten.sgml

   1 <!--
   2 $PostgreSQL$
   3 PostgreSQL documentation
   4 -->
   5
   6 <refentry id="SQL-UNLISTEN">
   7  <refmeta>
   8   <refentrytitle id="SQL-UNLISTEN-TITLE">UNLISTEN</refentrytitle>
   9   <refmiscinfo>SQL - Language Statements</refmiscinfo>
  10  </refmeta>
  11
  12  <refnamediv>
  13   <refname>UNLISTEN</refname>
  14   <refpurpose>stop listening for a notification</refpurpose>
  15  </refnamediv>
  16
  17  <indexterm zone="sql-unlisten">
  18   <primary>UNLISTEN</primary>
  19  </indexterm>
  20
  21  <refsynopsisdiv>
  22 <synopsis>
  23 UNLISTEN { <replaceable class="PARAMETER">name</replaceable> | * }
  24 </synopsis>
  25  </refsynopsisdiv>
  26
  27  <refsect1>
  28   <title>Description</title>
  29
  30   <para>
  31    <command>UNLISTEN</command> is used to remove an existing
  32    registration for <command>NOTIFY</command> events.
  33    <command>UNLISTEN</command> cancels any existing registration of
  34    the current <productname>PostgreSQL</productname> session as a
  35    listener on the notification <replaceable
  36    class="PARAMETER">name</replaceable>.  The special wildcard
  37    <literal>*</literal> cancels all listener registrations for the
  38    current session.
  39   </para>
  40
  41   <para>
  42    <xref endterm="sql-notify-title" linkend="sql-notify">
  43    contains a more extensive
  44    discussion of the use of <command>LISTEN</command> and
  45    <command>NOTIFY</command>.
  46   </para>
  47  </refsect1>
  48
  49  <refsect1>
  50   <title>Parameters</title>
  51
  52   <variablelist>
  53    <varlistentry>
  54     <term><replaceable class="PARAMETER">name</replaceable></term>
  55     <listitem>
  56      <para>
  57       Name of a notification (any identifier).
  58      </para>
  59     </listitem>
  60    </varlistentry>
  61
  62    <varlistentry>
  63     <term><literal>*</literal></term>
  64     <listitem>
  65      <para>
  66       All current listen registrations for this session are cleared.
  67      </para>
  68     </listitem>
  69    </varlistentry>
  70   </variablelist>
  71  </refsect1>
  72
  73  <refsect1>
  74   <title>Notes</title>
  75
  76   <para>
  77    You can unlisten something you were not listening for; no warning or error
  78    will appear.
  79   </para>
  80
  81   <para>
  82    At the end of each session, <command>UNLISTEN *</command> is
  83    automatically executed.
  84   </para>
  85  </refsect1>
  86
  87  <refsect1>
  88   <title>Examples</title>
  89
  90   <para>
  91    To make a registration:
  92
  93 <programlisting>
  94 LISTEN virtual;
  95 NOTIFY virtual;
  96 Asynchronous notification "virtual" received from server process with PID 8448.
  97 </programlisting>
  98   </para>
  99
 100   <para>
 101    Once <command>UNLISTEN</> has been executed, further <command>NOTIFY</>
 102    commands will be ignored:
 103
 104 <programlisting>
 105 UNLISTEN virtual;
 106 NOTIFY virtual;
 107 -- no NOTIFY event is received
 108 </programlisting>
 109   </para>
 110  </refsect1>
 111
 112  <refsect1>
 113   <title>Compatibility</title>
 114
 115   <para>
 116    There is no <command>UNLISTEN</command> command in the SQL standard.
 117   </para>
 118  </refsect1>
 119
 120  <refsect1>
 121   <title>See Also</title>
 122
 123   <simplelist type="inline">
 124    <member><xref linkend="sql-listen" endterm="sql-listen-title"></member>
 125    <member><xref linkend="sql-notify" endterm="sql-notify-title"></member>
 126   </simplelist>
 127  </refsect1>
 128 </refentry>