1 files changed, 153 insertions, 0 deletions
diff --git a/doc/src/sgml/ref/listen.sgml b/doc/src/sgml/ref/listen.sgml
new file mode 100644
index 0000000..2fab9d6
--- /dev/null
+++ b/doc/src/sgml/ref/listen.sgml
@@ -0,0 +1,153 @@
+<!--
+doc/src/sgml/ref/listen.sgml
+PostgreSQL documentation
+-->
+
+<refentry id="sql-listen">
+ <indexterm zone="sql-listen">
+  <primary>LISTEN</primary>
+ </indexterm>
+
+ <refmeta>
+  <refentrytitle>LISTEN</refentrytitle>
+  <manvolnum>7</manvolnum>
+  <refmiscinfo>SQL - Language Statements</refmiscinfo>
+ </refmeta>
+
+ <refnamediv>
+  <refname>LISTEN</refname>
+  <refpurpose>listen for a notification</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+<synopsis>
+LISTEN <replaceable class="parameter">channel</replaceable>
+</synopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+  <title>Description</title>
+
+  <para>
+   <command>LISTEN</command> registers the current session as a
+   listener on the notification channel named <replaceable
+   class="parameter">channel</replaceable>.
+   If the current session is already registered as a listener for
+   this notification channel, nothing is done.
+  </para>
+
+  <para>
+   Whenever the command <command>NOTIFY <replaceable
+   class="parameter">channel</replaceable></command> is invoked, either
+   by this session or another one connected to the same database, all
+   the sessions currently listening on that notification channel are
+   notified, and each will in turn notify its connected client
+   application.
+  </para>
+
+  <para>
+   A session can be unregistered for a given notification channel with the
+   <command>UNLISTEN</command> command.  A session's listen
+   registrations are automatically cleared when the session ends.
+  </para>
+
+  <para>
+   The method a client application must use to detect notification events depends on
+   which <productname>PostgreSQL</productname> application programming interface it
+   uses.  With the <application>libpq</application> library, the application issues
+   <command>LISTEN</command> as an ordinary SQL command, and then must
+   periodically call the function <function>PQnotifies</function> to find out
+   whether any notification events have been received.  Other interfaces such as
+   <application>libpgtcl</application> provide higher-level methods for handling notify events; indeed,
+   with <application>libpgtcl</application> the application programmer should not even issue
+   <command>LISTEN</command> or <command>UNLISTEN</command> directly.  See the
+   documentation for the interface you are using for more details.
+  </para>
+ </refsect1>
+
+ <refsect1>
+  <title>Parameters</title>
+
+  <variablelist>
+   <varlistentry>
+    <term><replaceable class="parameter">channel</replaceable></term>
+    <listitem>
+     <para>
+      Name of a notification channel (any identifier).
+     </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+ </refsect1>
+
+ <refsect1>
+  <title>Notes</title>
+
+  <para>
+   <command>LISTEN</command> takes effect at transaction commit.
+   If <command>LISTEN</command> or <command>UNLISTEN</command> is executed
+   within a transaction that later rolls back, the set of notification
+   channels being listened to is unchanged.
+  </para>
+
+  <para>
+   A transaction that has executed <command>LISTEN</command> cannot be
+   prepared for two-phase commit.
+  </para>
+
+  <para>
+   There is a race condition when first setting up a listening session:
+   if concurrently-committing transactions are sending notify events,
+   exactly which of those will the newly listening session receive?
+   The answer is that the session will receive all events committed after
+   an instant during the transaction's commit step.  But that is slightly
+   later than any database state that the transaction could have observed
+   in queries.  This leads to the following rule for
+   using <command>LISTEN</command>: first execute (and commit!) that
+   command, then in a new transaction inspect the database state as needed
+   by the application logic, then rely on notifications to find out about
+   subsequent changes to the database state.  The first few received
+   notifications might refer to updates already observed in the initial
+   database inspection, but this is usually harmless.
+  </para>
+
+  <para>
+   <xref linkend="sql-notify"/>
+   contains a more extensive
+   discussion of the use of <command>LISTEN</command> and
+   <command>NOTIFY</command>.
+  </para>
+ </refsect1>
+
+ <refsect1>
+  <title>Examples</title>
+
+  <para>
+   Configure and execute a listen/notify sequence from
+   <application>psql</application>:
+
+<programlisting>
+LISTEN virtual;
+NOTIFY virtual;
+Asynchronous notification "virtual" received from server process with PID 8448.
+</programlisting></para>
+ </refsect1>
+
+ <refsect1>
+  <title>Compatibility</title>
+
+  <para>
+   There is no <command>LISTEN</command> statement in the SQL
+   standard.
+  </para>
+ </refsect1>
+
+ <refsect1>
+  <title>See Also</title>
+
+  <simplelist type="inline">
+   <member><xref linkend="sql-notify"/></member>
+   <member><xref linkend="sql-unlisten"/></member>
+  </simplelist>
+ </refsect1>
+</refentry>