|PostgreSQL Reference Manual - Volume 2 - Programming Guide|
by The PostgreSQL Global Development Group
Paperback (6"x9"), 408 pages
RRP £19.95 ($34.95)
Sales of this book support the PostgreSQL project! Get a printed copy>>>
5.9.1 Dynamic Loading
The first time a user-defined function in a particular
loadable object file is called in a session,
the dynamic loader loads that object file into memory so that the
function can be called. The
for a user-defined C function must therefore specify two pieces of
information for the function: the name of the loadable
object file, and the C name (link symbol) of the specific function to call
within that object file. If the C name is not explicitly specified then
it is assumed to be the same as the SQL function name.
The following algorithm is used to locate the shared object file
based on the name given in the
- If the name is an absolute path, the given file is loaded.
If the name starts with the string
$libdir, that part is replaced by the PostgreSQL package library directory name, which is determined at build time.
If the name does not contain a directory part, the file is
searched for in the path specified by the configuration variable
- Otherwise (the file was not found in the path, or it contains a non-absolute directory part), the dynamic loader will try to take the name as given, which will most likely fail. (It is unreliable to depend on the current working directory.)
If this sequence does not work, the platform-specific shared library file name extension (often ‘.so’) is appended to the given name and this sequence is tried again. If that fails as well, the load will fail.
It is recommended to locate shared libraries either relative to
$libdir or through the dynamic library path.
This simplifies version upgrades if the new installation is at a
different location. The actual directory that
$libdir stands for can be found out with the
The user ID the PostgreSQL server runs
as must be able to traverse the path to the file you intend to
load. Making the file or a higher-level directory not readable
and/or not executable by the
user is a common mistake.
In any case, the file name that is given in the
CREATE FUNCTION command is recorded literally
in the system catalogs, so if the file needs to be loaded again
the same procedure is applied.
Note: PostgreSQL will not compile a C function automatically. The object file must be compiled before it is referenced in a
CREATE FUNCTIONcommand. See section 5.9.6 Compiling and Linking Dynamically-Loaded Functions for additional information.
To ensure that a dynamically loaded object file is not loaded into an incompatible server, PostgreSQL checks that the file contains a “magic block” with the appropriate contents. This allows the server to detect obvious incompatibilities, such as code compiled for a different major version of PostgreSQL. A magic block is required as of PostgreSQL 8.2. To include a magic block, write this in one (and only one) of the module source files, after having included the header ‘fmgr.h’:
#ifdef PG_MODULE_MAGIC PG_MODULE_MAGIC; #endif
#ifdef test can be omitted if the code doesn't
need to compile against pre-8.2 PostgreSQL
After it is used for the first time, a dynamically loaded object
file is retained in memory. Future calls in the same session to
the function(s) in that file will only incur the small overhead of
a symbol table lookup. If you need to force a reload of an object
file, for example after recompiling it, use the
LOAD command or begin a
Optionally, a dynamically loaded file can contain initialization and
finalization functions. If the file includes a function named
_PG_init, that function will be called immediately after
loading the file. The function receives no parameters and should
return void. If the file includes a function named
_PG_fini, that function will be called immediately before
unloading the file. Likewise, the function receives no parameters and
should return void. Note that
_PG_fini will only be called
during an unload of the file, not during process termination.
(Presently, an unload only happens in the context of re-loading
the file due to an explicit
|ISBN 0954612035||PostgreSQL Reference Manual - Volume 2 - Programming Guide||See the print edition|