From 01b2168c90f121b5be7da72786c051588c43c128 Mon Sep 17 00:00:00 2001
From: Bruce Momjian
Date: Tue, 30 May 2006 14:09:32 +0000
Subject: Add pgmagic header block to store compile-time constants:

It now only checks four things:

Major version number (7.4 or 8.1 for example)
NAMEDATALEN
FUNC_MAX_ARGS
INDEX_MAX_KEYS

The three constants were chosen because:

1. We document them in the config page in the docs
2. We mark them as changable in pg_config_manual.h
3. Changing any of these will break some of the more popular modules:

FUNC_MAX_ARGS changes fmgr interface, every module uses this NAMEDATALEN
changes syscache interface, every PL as well as tsearch uses this
INDEX_MAX_KEYS breaks tsearch and anything using GiST.

Martijn van Oosterhout
---
 doc/src/sgml/xfunc.sgml | 29 ++++++++++++++++++++++++++++-
 1 file changed, 28 insertions(+), 1 deletion(-)

(limited to 'doc/src')

diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml
index 27cb8c90ca1..1f03d7cd90b 100644
--- a/doc/src/sgml/xfunc.sgml
+++ b/doc/src/sgml/xfunc.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/xfunc.sgml,v 1.112 2006/04/23 03:39:52 momjian Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/xfunc.sgml,v 1.113 2006/05/30 14:09:32 momjian Exp $ -->
 
  <sect1 id="xfunc">
   <title>User-Defined Functions</title>
@@ -1148,6 +1148,13 @@ CREATE FUNCTION square_root(double precision) RETURNS double precision
     that fails as well, the load will fail.
    </para>
 
+   <para>
+    After the module has been found, PostgreSQL looks for its magic block.
+    This block contains information about the environment a module was
+    compiled in. The server uses this to verify the module was compiled
+    under the same assumptions and environment as the backend.
+   </para>
+
    <para>
     The user ID the <productname>PostgreSQL</productname> server runs
     as must be able to traverse the path to the file you intend to
@@ -1951,6 +1958,26 @@ concat_text(PG_FUNCTION_ARGS)
        </para>
       </listitem>
 
+      <listitem>
+       <para>
+        To ensure your module is not loaded into an incompatible backend, it
+        is recommended to include a magic block. To do this you must include
+        the header <filename>pgmagic.h</filename> and declare the block as
+        follows:
+       </para>
+
+<programlisting>
+#include "pgmagic.h"
+
+PG_MODULE_MAGIC;
+</programlisting>
+
+       <para>
+        If the module consists of multiple source files, this only needs to
+        be done in one of them.
+       </para>
+      </listitem>
+
       <listitem>
        <para>
         Symbol names defined within object files must not conflict
-- 
cgit v1.2.3