raw/man7/listen.7

   1 .\\" auto-generated by docbook2man-spec $Revision: 1.1 $
   2 .TH "LISTEN" "7" "2003-11-02" "SQL - Language Statements" "SQL Commands"
   3 .SH NAME
   4 LISTEN \- listen for a notification
   5
   6 .SH SYNOPSIS
   7 .sp
   8 .nf
   9 LISTEN \fIname\fR
  10 .sp
  11 .fi
  12 .SH "DESCRIPTION"
  13 .PP
  14 \fBLISTEN\fR registers the current session as a
  15 listener on the notification condition \fIname\fR.
  16 If the current session is already registered as a listener for
  17 this notification condition, nothing is done.
  18 .PP
  19 Whenever the command \fBNOTIFY \fIname\fB\fR is invoked, either
  20 by this session or another one connected to the same database, all
  21 the sessions currently listening on that notification condition are
  22 notified, and each will in turn notify its connected client
  23 application. See the discussion of \fBNOTIFY\fR for
  24 more information.
  25 .PP
  26 A session can be unregistered for a given notify condition with the
  27 \fBUNLISTEN\fR command. A session's listen
  28 registrations are automatically cleared when the session ends.
  29 .PP
  30 The method a client application must use to detect notification events depends on
  31 which PostgreSQL application programming interface it
  32 uses. With the \fBlibpq\fR library, the application issues
  33 \fBLISTEN\fR as an ordinary SQL command, and then must
  34 periodically call the function \fBPQnotifies\fR to find out
  35 whether any notification events have been received. Other interfaces such as
  36 \fBlibpgtcl\fR provide higher-level methods for handling notify events; indeed,
  37 with \fBlibpgtcl\fR the application programmer should not even issue
  38 \fBLISTEN\fR or \fBUNLISTEN\fR directly. See the
  39 documentation for the interface you are using for more details.
  40 .PP
  41 NOTIFY [\fBnotify\fR(7)]
  42 contains a more extensive
  43 discussion of the use of \fBLISTEN\fR and
  44 \fBNOTIFY\fR.
  45 .SH "PARAMETERS"
  46 .TP
  47 \fB\fIname\fB\fR
  48 Name of a notify condition (any identifier).
  49 .SH "EXAMPLES"
  50 .PP
  51 Configure and execute a listen/notify sequence from
  52 \fBpsql\fR:
  53 .sp
  54 .nf
  55 LISTEN virtual;
  56 NOTIFY virtual;
  57 Asynchronous notification "virtual" received from server process with PID 8448.
  58 .sp
  59 .fi
  60 .SH "COMPATIBILITY"
  61 .PP
  62 There is no \fBLISTEN\fR statement in the SQL
  63 standard.
  64 .SH "SEE ALSO"
  65 NOTIFY [\fBnotify\fR(7)], UNLISTEN [\fBunlisten\fR(l)]
  66