summaryrefslogtreecommitdiff
path: root/doc/src/sgml
diff options
context:
space:
mode:
Diffstat (limited to 'doc/src/sgml')
-rw-r--r--doc/src/sgml/catalogs.sgml69
-rw-r--r--doc/src/sgml/func.sgml18
-rw-r--r--doc/src/sgml/libpq.sgml52
-rw-r--r--doc/src/sgml/protocol.sgml23
-rw-r--r--doc/src/sgml/ref/listen.sgml38
-rw-r--r--doc/src/sgml/ref/notify.sgml121
-rw-r--r--doc/src/sgml/ref/unlisten.sgml19
-rw-r--r--doc/src/sgml/storage.sgml7
8 files changed, 184 insertions, 163 deletions
diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml
index 3503bc852cd..e5bef18d7d8 100644
--- a/doc/src/sgml/catalogs.sgml
+++ b/doc/src/sgml/catalogs.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/catalogs.sgml,v 2.221 2010/02/07 20:48:09 tgl Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/catalogs.sgml,v 2.222 2010/02/16 22:34:41 tgl Exp $ -->
<!--
Documentation of the system catalogs, directed toward PostgreSQL developers
-->
@@ -169,11 +169,6 @@
</row>
<row>
- <entry><link linkend="catalog-pg-listener"><structname>pg_listener</structname></link></entry>
- <entry>asynchronous notification support</entry>
- </row>
-
- <row>
<entry><link linkend="catalog-pg-namespace"><structname>pg_namespace</structname></link></entry>
<entry>schemas</entry>
</row>
@@ -3253,68 +3248,6 @@
</table>
</sect1>
- <sect1 id="catalog-pg-listener">
- <title><structname>pg_listener</structname></title>
-
- <indexterm zone="catalog-pg-listener">
- <primary>pg_listener</primary>
- </indexterm>
-
- <para>
- The catalog <structname>pg_listener</structname> supports the
- <xref linkend="sql-listen" endterm="sql-listen-title"> and
- <xref linkend="sql-notify" endterm="sql-notify-title">
- commands. A listener creates an entry in
- <structname>pg_listener</structname> for each notification name
- it is listening for. A notifier scans <structname>pg_listener</structname>
- and updates each matching entry to show that a notification has occurred.
- The notifier also sends a signal (using the PID recorded in the table)
- to awaken the listener from sleep.
- </para>
-
- <table>
- <title><structname>pg_listener</> Columns</title>
-
- <tgroup cols="3">
- <thead>
- <row>
- <entry>Name</entry>
- <entry>Type</entry>
- <entry>Description</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry><structfield>relname</structfield></entry>
- <entry><type>name</type></entry>
- <entry>
- Notify condition name. (The name need not match any actual
- relation in the database; the name <structfield>relname</> is historical.)
- </entry>
- </row>
-
- <row>
- <entry><structfield>listenerpid</structfield></entry>
- <entry><type>int4</type></entry>
- <entry>PID of the server process that created this entry</entry>
- </row>
-
- <row>
- <entry><structfield>notification</structfield></entry>
- <entry><type>int4</type></entry>
- <entry>
- Zero if no event is pending for this listener. If an event is
- pending, the PID of the server process that sent the notification
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- </sect1>
-
-
<sect1 id="catalog-pg-namespace">
<title><structname>pg_namespace</structname></title>
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 71952ee1fc4..54369711155 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.503 2010/02/16 21:18:01 momjian Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.504 2010/02/16 22:34:42 tgl Exp $ -->
<chapter id="functions">
<title>Functions and Operators</title>
@@ -11530,6 +11530,12 @@ postgres=# select * from unnest2(array[[1,2],[3,4]]);
</row>
<row>
+ <entry><literal><function>pg_listening_channels</function>()</literal></entry>
+ <entry><type>setof text</type></entry>
+ <entry>channel names that the session is currently listening on</entry>
+ </row>
+
+ <row>
<entry><literal><function>inet_client_addr</function>()</literal></entry>
<entry><type>inet</type></entry>
<entry>address of the remote connection</entry>
@@ -11675,6 +11681,16 @@ SET search_path TO <replaceable>schema</> <optional>, <replaceable>schema</>, ..
</note>
<indexterm>
+ <primary>pg_listening_channels</primary>
+ </indexterm>
+
+ <para>
+ <function>pg_listening_channels</function> returns a set of names of
+ channels that the current session is listening to. See <xref
+ linkend="sql-listen" endterm="sql-listen-title"> for more information.
+ </para>
+
+ <indexterm>
<primary>inet_client_addr</primary>
</indexterm>
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 4972a8c2592..0bdb6401c34 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.298 2010/02/16 20:58:13 momjian Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.299 2010/02/16 22:34:42 tgl Exp $ -->
<chapter id="libpq">
<title><application>libpq</application> - C Library</title>
@@ -307,28 +307,28 @@
<entry>Description</entry>
</row>
</thead>
-
+
<tbody>
-
+
<row>
<entry><literal>disable</></entry>
<entry>only try a non-<acronym>SSL</> connection</entry>
</row>
-
+
<row>
<entry><literal>allow</></entry>
<entry>first try a non-<acronym>SSL</>
connection; if that fails, try an <acronym>SSL</>
connection</entry>
</row>
-
+
<row>
<entry><literal>prefer</> (default)</entry>
<entry>first try an <acronym>SSL</> connection; if
that fails, try a non-<acronym>SSL</>
connection</entry>
</row>
-
+
<row>
<entry><literal>require</></entry>
<entry>only try an <acronym>SSL</> connection</entry>
@@ -481,7 +481,7 @@
</para>
<para>
- If <literal>expand_dbname</literal> is non-zero and
+ If <literal>expand_dbname</literal> is non-zero and
<parameter>dbname</parameter> contains an <symbol>=</symbol> sign, it
is taken as a <parameter>conninfo</parameter> string in exactly the same way as
if it had been passed to <function>PQconnectdb</function>(see below). Previously
@@ -4111,50 +4111,48 @@ typedef struct {
<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 condition with the <command>LISTEN</command> command (and
+ notification channel with the <command>LISTEN</command> command (and
can stop listening with the <command>UNLISTEN</command> command). All
- sessions listening on a particular condition will be notified
+ sessions listening on a particular channel will be notified
asynchronously when a <command>NOTIFY</command> command with that
- condition name is executed by any session. No additional information
- is passed from the notifier to the listener. Thus, typically, any
- actual data that needs to be communicated is transferred through a
- database table. Commonly, the condition name is the same as the
- associated table, but it is not necessary for there to be any associated
- table.
+ channel name is executed by any session. A <quote>payload</> string can
+ be passed to communicate additional data to the listeners.
</para>
<para>
<application>libpq</application> applications submit
- <command>LISTEN</command> and <command>UNLISTEN</command> commands as
+ <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>PQnotifies</function>.<indexterm><primary>PQnotifies</></>
</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</>, it is considered handled and will be
- removed from the list of notifications.
+ 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</>, it is considered
+ handled and will be removed from the list of notifications.
+
<synopsis>
PGnotify *PQnotifies(PGconn *conn);
typedef struct pgNotify {
- char *relname; /* notification condition name */
+ char *relname; /* notification channel name */
int be_pid; /* process ID of notifying server process */
- char *extra; /* notification parameter */
+ 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
<function>PQfreemem</function>. It is sufficient to free the
<structname>PGnotify</structname> pointer; the
<structfield>relname</structfield> and <structfield>extra</structfield>
- fields do not represent separate allocations. (At present, the
- <structfield>extra</structfield> field is unused and will always point
- to an empty string.)
+ 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>
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index e4364ec305f..f0a2aeba03a 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/protocol.sgml,v 1.80 2010/02/16 20:58:14 momjian Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/protocol.sgml,v 1.81 2010/02/16 22:34:43 tgl Exp $ -->
<chapter id="protocol">
<title>Frontend/Backend Protocol</title>
@@ -354,7 +354,7 @@
<para>
This message contains the response data from the previous step
of GSSAPI or SSPI negotiation (AuthenticationGSS, AuthenticationSSPI
- or a previous AuthenticationGSSContinue). If the GSSAPI
+ or a previous AuthenticationGSSContinue). If the GSSAPI
or SSPI data in this message
indicates more data is needed to complete the authentication,
the frontend must send that data as another PasswordMessage. If
@@ -992,7 +992,7 @@
<para>
In the event of a backend-detected error during copy-in mode (including
- receipt of a CopyFail message), the backend will issue an ErrorResponse
+ receipt of a CopyFail message), the backend will issue an ErrorResponse
message. If the <command>COPY</> command was issued via an extended-query
message, the backend will now discard frontend messages until a Sync
message is received, then it will issue ReadyForQuery and return to normal
@@ -1117,7 +1117,7 @@
backend will send a NotificationResponse message (not to be
confused with NoticeResponse!) whenever a
<command>NOTIFY</command> command is executed for the same
- notification name.
+ channel name.
</para>
<note>
@@ -1340,7 +1340,7 @@ This section describes the base data types used in messages.
value that will appear, otherwise the value is variable.
Eg. String, String("user").
</para>
-
+
<note>
<para>
<emphasis>There is no predefined limit</emphasis> on the length of a string
@@ -1951,7 +1951,7 @@ Bind (F)
(denoted <replaceable>R</> below).
This can be zero to indicate that there are no result columns
or that the result columns should all use the default format
- (text);
+ (text);
or one, in which case the specified format code is applied
to all result columns (if any); or it can equal the actual
number of result columns of the query.
@@ -2500,7 +2500,7 @@ CopyOutResponse (B)
separated by separator characters, etc). 1 indicates
the overall copy format is binary (similar to DataRow
format). See <xref linkend="sql-copy"
- endterm="sql-copy-title"> for more information.
+ endterm="sql-copy-title"> for more information.
</para>
</listitem>
</varlistentry>
@@ -3187,7 +3187,7 @@ NotificationResponse (B)
</term>
<listitem>
<para>
- The name of the condition that the notify has been raised on.
+ The name of the channel that the notify has been raised on.
</para>
</listitem>
</varlistentry>
@@ -3197,9 +3197,7 @@ NotificationResponse (B)
</term>
<listitem>
<para>
- Additional information passed from the notifying process.
- (Currently, this feature is unimplemented so the field
- is always an empty string.)
+ The <quote>payload</> string passed from the notifying process.
</para>
</listitem>
</varlistentry>
@@ -4353,7 +4351,7 @@ the backend.
<para>
The NotificationResponse ('<literal>A</>') message has an additional string
-field, which is presently empty but might someday carry additional data passed
+field, which can carry a <quote>payload</> string passed
from the <command>NOTIFY</command> event sender.
</para>
@@ -4364,5 +4362,4 @@ string parameter; this has been removed.
</sect1>
-
</chapter>
diff --git a/doc/src/sgml/ref/listen.sgml b/doc/src/sgml/ref/listen.sgml
index 93ca74c5722..57577c1f6ac 100644
--- a/doc/src/sgml/ref/listen.sgml
+++ b/doc/src/sgml/ref/listen.sgml
@@ -1,5 +1,5 @@
<!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/listen.sgml,v 1.23 2008/11/14 10:22:47 petere Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/listen.sgml,v 1.24 2010/02/16 22:34:43 tgl Exp $
PostgreSQL documentation
-->
@@ -21,7 +21,7 @@ PostgreSQL documentation
<refsynopsisdiv>
<synopsis>
-LISTEN <replaceable class="PARAMETER">name</replaceable>
+LISTEN <replaceable class="PARAMETER">channel</replaceable>
</synopsis>
</refsynopsisdiv>
@@ -30,24 +30,23 @@ LISTEN <replaceable class="PARAMETER">name</replaceable>
<para>
<command>LISTEN</command> registers the current session as a
- listener on the notification condition <replaceable
- class="PARAMETER">name</replaceable>.
+ listener on the notification channel named <replaceable
+ class="PARAMETER">channel</replaceable>.
If the current session is already registered as a listener for
- this notification condition, nothing is done.
+ this notification channel, nothing is done.
</para>
<para>
Whenever the command <command>NOTIFY <replaceable
- class="PARAMETER">name</replaceable></command> is invoked, either
+ 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 condition are
+ the sessions currently listening on that notification channel are
notified, and each will in turn notify its connected client
- application. See the discussion of <command>NOTIFY</command> for
- more information.
+ application.
</para>
<para>
- A session can be unregistered for a given notify condition with the
+ 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>
@@ -78,10 +77,10 @@ LISTEN <replaceable class="PARAMETER">name</replaceable>
<variablelist>
<varlistentry>
- <term><replaceable class="PARAMETER">name</replaceable></term>
+ <term><replaceable class="PARAMETER">channel</replaceable></term>
<listitem>
<para>
- Name of a notify condition (any identifier).
+ Name of a notification channel (any identifier).
</para>
</listitem>
</varlistentry>
@@ -89,6 +88,21 @@ LISTEN <replaceable class="PARAMETER">name</replaceable>
</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>
+ </refsect1>
+
+ <refsect1>
<title>Examples</title>
<para>
diff --git a/doc/src/sgml/ref/notify.sgml b/doc/src/sgml/ref/notify.sgml
index 563fbbe9638..b612bb4cb2a 100644
--- a/doc/src/sgml/ref/notify.sgml
+++ b/doc/src/sgml/ref/notify.sgml
@@ -1,5 +1,5 @@
<!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/notify.sgml,v 1.31 2008/11/14 10:22:47 petere Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/notify.sgml,v 1.32 2010/02/16 22:34:43 tgl Exp $
PostgreSQL documentation
-->
@@ -21,7 +21,7 @@ PostgreSQL documentation
<refsynopsisdiv>
<synopsis>
-NOTIFY <replaceable class="PARAMETER">name</replaceable>
+NOTIFY <replaceable class="PARAMETER">channel</replaceable> [ , <replaceable class="PARAMETER">payload</replaceable> ]
</synopsis>
</refsynopsisdiv>
@@ -29,35 +29,39 @@ NOTIFY <replaceable class="PARAMETER">name</replaceable>
<title>Description</title>
<para>
- The <command>NOTIFY</command> command sends a notification event to each
- client application that has previously executed
- <command>LISTEN <replaceable class="parameter">name</replaceable></command>
- for the specified notification name in the current database.
+ The <command>NOTIFY</command> command sends a notification event together
+ with an optional <quote>payload</> string to each client application that
+ has previously executed
+ <command>LISTEN <replaceable class="parameter">channel</></command>
+ for the specified channel name in the current database.
</para>
<para>
- <command>NOTIFY</command> provides a simple form of signal or
+ <command>NOTIFY</command> provides a simple
interprocess communication mechanism for a collection of processes
accessing the same <productname>PostgreSQL</productname> database.
- Higher-level mechanisms can be built by using tables in the database to
- pass additional data (beyond a mere notification name) from notifier to
- listener(s).
+ A payload string can be sent along with the notification, and
+ higher-level mechanisms for passing structured data can be built by using
+ tables in the database to pass additional data from notifier to listener(s).
</para>
<para>
- The information passed to the client for a notification event includes the notification
- name and the notifying session's server process <acronym>PID</>. It is up to the
- database designer to define the notification names that will be used in a given
- database and what each one means.
+ The information passed to the client for a notification event includes the
+ notification channel
+ name, the notifying session's server process <acronym>PID</>, and the
+ payload string, which is an empty string if it has not been specified.
</para>
<para>
- Commonly, the notification name is the same as the name of some table in
+ It is up to the database designer to define the channel names that will
+ be used in a given database and what each one means.
+ Commonly, the channel name is the same as the name of some table in
the database, and the notify event essentially means, <quote>I changed this table,
take a look at it to see what's new</quote>. But no such association is enforced by
the <command>NOTIFY</command> and <command>LISTEN</command> commands. For
- example, a database designer could use several different notification names
- to signal different sorts of changes to a single table.
+ example, a database designer could use several different channel names
+ to signal different sorts of changes to a single table. Alternatively,
+ the payload string could be used to differentiate various cases.
</para>
<para>
@@ -89,19 +93,22 @@ NOTIFY <replaceable class="PARAMETER">name</replaceable>
</para>
<para>
- <command>NOTIFY</command> behaves like Unix signals in one important
- respect: if the same notification name is signaled multiple times in quick
- succession, recipients might get only one notification event for several executions
- of <command>NOTIFY</command>. So it is a bad idea to depend on the number
- of notifications received. Instead, use <command>NOTIFY</command> to wake up
- applications that need to pay attention to something, and use a database
- object (such as a sequence) to keep track of what happened or how many times
- it happened.
+ If the same channel name is signaled multiple times from the same
+ transaction with identical payload strings, the
+ database server can decide to deliver a single notification only.
+ On the other hand, notifications with distinct payload strings will
+ always be delivered as distinct notifications. Similarly, notifications from
+ different transactions will never get folded into one notification.
+ Except for dropping later instances of duplicate notifications,
+ <command>NOTIFY</command> guarantees that notifications from the same
+ transaction get delivered in the order they were sent. It is also
+ guaranteed that messages from different transactions are delivered in
+ the order in which the transactions committed.
</para>
<para>
It is common for a client that executes <command>NOTIFY</command>
- to be listening on the same notification name itself. In that case
+ to be listening on the same notification channel itself. In that case
it will get back a notification event, just like all the other
listening sessions. Depending on the application logic, this could
result in useless work, for example, reading a database table to
@@ -111,12 +118,7 @@ NOTIFY <replaceable class="PARAMETER">name</replaceable>
notification event message) is the same as one's own session's
<acronym>PID</> (available from <application>libpq</>). When they
are the same, the notification event is one's own work bouncing
- back, and can be ignored. (Despite what was said in the preceding
- paragraph, this is a safe technique.
- <productname>PostgreSQL</productname> keeps self-notifications
- separate from notifications arriving from other sessions, so you
- cannot miss an outside notification by ignoring your own
- notifications.)
+ back, and can be ignored.
</para>
</refsect1>
@@ -125,10 +127,22 @@ NOTIFY <replaceable class="PARAMETER">name</replaceable>
<variablelist>
<varlistentry>
- <term><replaceable class="PARAMETER">name</replaceable></term>
+ <term><replaceable class="PARAMETER">channel</replaceable></term>
<listitem>
<para>
- Name of the notification to be signaled (any identifier).
+ Name of the notification channel to be signaled (any identifier).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><replaceable class="PARAMETER">payload</replaceable></term>
+ <listitem>
+ <para>
+ The <quote>payload</> string to be communicated along with the
+ notification. This string must be shorter than 8000 bytes, and
+ is treated as text.
+ (If binary data or large amounts of information need to be communicated,
+ it's best to put it in a database table and send the key of the record.)
</para>
</listitem>
</varlistentry>
@@ -136,6 +150,39 @@ NOTIFY <replaceable class="PARAMETER">name</replaceable>
</refsect1>
<refsect1>
+ <title>Notes</title>
+
+ <indexterm>
+ <primary>pg_notify</primary>
+ </indexterm>
+
+ <para>
+ To send a notification you can also use the function
+ <literal><function>pg_notify</function>(<type>text</type>,
+ <type>text</type>)</literal>. The function takes the channel name as the
+ first argument and the payload as the second. The function is much easier
+ to use than the <command>NOTIFY</command> command if you need to work with
+ non-constant channel names and payloads.
+ </para>
+ <para>
+ There is a queue that holds notifications that have been sent but not
+ yet processed by all listening sessions. If this queue becomes full,
+ transactions calling <command>NOTIFY</command> will fail at commit.
+ The queue is quite large (8GB in a standard installation) and should be
+ sufficiently sized for almost every use case. However, no cleanup can take
+ place if a session executes <command>LISTEN</command> and then enters a
+ transaction for a very long time. Once the queue is half full you will see
+ warnings in the log file pointing you to the session that is preventing
+ cleanup. In this case you should make sure that this session ends its
+ current transaction so that cleanup can proceed.
+ </para>
+ <para>
+ A transaction that has executed <command>NOTIFY</command> cannot be
+ prepared for two-phase commit.
+ </para>
+ </refsect1>
+
+ <refsect1>
<title>Examples</title>
<para>
@@ -146,6 +193,12 @@ NOTIFY <replaceable class="PARAMETER">name</replaceable>
LISTEN virtual;
NOTIFY virtual;
Asynchronous notification "virtual" received from server process with PID 8448.
+NOTIFY virtual, 'This is the payload';
+Asynchronous notification "virtual" with payload "This is the payload" received from server process with PID 8448.
+
+LISTEN foo;
+SELECT pg_notify('fo' || 'o', 'pay' || 'load');
+Asynchronous notification "foo" with payload "payload" received from server process with PID 14728.
</programlisting>
</para>
</refsect1>
diff --git a/doc/src/sgml/ref/unlisten.sgml b/doc/src/sgml/ref/unlisten.sgml
index 7cdd7394cb9..9e22ea4edc4 100644
--- a/doc/src/sgml/ref/unlisten.sgml
+++ b/doc/src/sgml/ref/unlisten.sgml
@@ -1,5 +1,5 @@
<!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/unlisten.sgml,v 1.30 2008/11/14 10:22:47 petere Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/unlisten.sgml,v 1.31 2010/02/16 22:34:43 tgl Exp $
PostgreSQL documentation
-->
@@ -21,7 +21,7 @@ PostgreSQL documentation
<refsynopsisdiv>
<synopsis>
-UNLISTEN { <replaceable class="PARAMETER">name</replaceable> | * }
+UNLISTEN { <replaceable class="PARAMETER">channel</replaceable> | * }
</synopsis>
</refsynopsisdiv>
@@ -33,8 +33,8 @@ UNLISTEN { <replaceable class="PARAMETER">name</replaceable> | * }
registration for <command>NOTIFY</command> events.
<command>UNLISTEN</command> cancels any existing registration of
the current <productname>PostgreSQL</productname> session as a
- listener on the notification <replaceable
- class="PARAMETER">name</replaceable>. The special wildcard
+ listener on the notification channel named <replaceable
+ class="PARAMETER">channel</replaceable>. The special wildcard
<literal>*</literal> cancels all listener registrations for the
current session.
</para>
@@ -52,10 +52,10 @@ UNLISTEN { <replaceable class="PARAMETER">name</replaceable> | * }
<variablelist>
<varlistentry>
- <term><replaceable class="PARAMETER">name</replaceable></term>
+ <term><replaceable class="PARAMETER">channel</replaceable></term>
<listitem>
<para>
- Name of a notification (any identifier).
+ Name of a notification channel (any identifier).
</para>
</listitem>
</varlistentry>
@@ -83,6 +83,11 @@ UNLISTEN { <replaceable class="PARAMETER">name</replaceable> | * }
At the end of each session, <command>UNLISTEN *</command> is
automatically executed.
</para>
+
+ <para>
+ A transaction that has executed <command>UNLISTEN</command> cannot be
+ prepared for two-phase commit.
+ </para>
</refsect1>
<refsect1>
@@ -100,7 +105,7 @@ Asynchronous notification "virtual" received from server process with PID 8448.
<para>
Once <command>UNLISTEN</> has been executed, further <command>NOTIFY</>
- commands will be ignored:
+ messages will be ignored:
<programlisting>
UNLISTEN virtual;
diff --git a/doc/src/sgml/storage.sgml b/doc/src/sgml/storage.sgml
index e0cef7dd7b0..c4b38ddb6c8 100644
--- a/doc/src/sgml/storage.sgml
+++ b/doc/src/sgml/storage.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/storage.sgml,v 1.31 2010/02/07 20:48:09 tgl Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/storage.sgml,v 1.32 2010/02/16 22:34:43 tgl Exp $ -->
<chapter id="storage">
@@ -78,6 +78,11 @@ Item
</row>
<row>
+ <entry><filename>pg_notify</></entry>
+ <entry>Subdirectory containing LISTEN/NOTIFY status data</entry>
+</row>
+
+<row>
<entry><filename>pg_stat_tmp</></entry>
<entry>Subdirectory containing temporary files for the statistics
subsystem</entry>
generated by cgit v1.2.3 (git 2.46.0) at 2025-10-30 04:00:14 +0000