From 07c179a82b39ffbc172175382717706d90c714cd Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Fri, 14 Nov 2008 22:58:51 +0000
Subject: [PATCH] Document a gotcha that happens on Windows when using libpq's
 new event procedure support: it's possible to get confused because exported
 procedures have two different addresses.  Per Andrew Chernow.

---
 doc/src/sgml/libpq.sgml | 15 ++++++++++++++-
 1 file changed, 14 insertions(+), 1 deletion(-)

diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 0b220ab514..d7b4d2393a 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.269 2008/11/13 09:45:24 mha Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.270 2008/11/14 22:58:51 tgl Exp $ -->
 
 <chapter id="libpq">
  <title><application>libpq</application> - C Library</title>
@@ -5255,6 +5255,19 @@ int eventproc(PGEventId evtId, void *evtInfo, void *passThrough)
        <structname>PGconn</>.  This is because the address of the procedure
        is used as a lookup key to identify the associated instance data.
       </para>
+
+      <caution>
+       <para>
+        On Windows, functions can have two different addresses: one visible
+        from outside a DLL and another visible from inside the DLL.  One
+        should be careful that only one of these addresses is used with
+        <application>libpq</>'s event-procedure functions, else confusion will
+        result.  The simplest rule for writing code that will work is to
+        ensure that event procedures are declared <literal>static</>.  If the
+        procedure's address must be available outside its own source file,
+        expose a separate function to return the address.
+       </para>
+      </caution>
      </listitem>
     </varlistentry>
    </variablelist>
-- 
2.40.0