procedure.
-->
- After you have created and registered a user-defined
- function, your work is essentially done.
Postgres,
- however, must load the object code (e.g., a .o file, or
- a shared library) that implements your function. As
- previously mentioned,
Postgres loads your code at
- runtime, as required. In order to allow your code to be
- dynamically loaded, you may have to compile and
- link-edit it in a special way. This section briefly
- describes how to perform the compilation and
- link-editing required before you can load your user-defined
- functions into a running
Postgres server. Note that
- this process has changed as of Version 4.2.
-
-The old
Postgres dynamic
-loading mechanism required
-in-depth knowledge in terms of executable format, placement
-and alignment of executable instructions within memory, etc.
-on the part of the person writing the dynamic loader. Such
-loaders tended to be slow and buggy. As of Version 4.2, the
-
Postgres dynamic loading mechanism has been rewritten to use
-the dynamic loading mechanism provided by the operating
-system. This approach is generally faster, more reliable and
-more portable than our previous dynamic loading mechanism.
-The reason for this is that nearly all modern versions of
-UNIX use a dynamic loading mechanism to implement shared
-libraries and must therefore provide a fast and reliable
-mechanism. On the other hand, the object file must be
-postprocessed a bit before it can be loaded into
Postgres. We
-hope that the large increase in speed and reliability will
-make up for the slight decrease in convenience.
-
-
-
- You should expect to read (and reread, and re-reread) the
- manual pages for the C compiler, cc(1), and the link
- editor, ld(1), if you have specific questions. In
- addition, the regression test suites in the directory
- PGROOT/src/regress contain several
- working examples of this process. If you copy what these
- tests do, you should not have any problems.
- The following terminology will be used below:
-
-
- Dynamic loading
- is what
Postgres does to an object file. The
- object file is copied into the running
Postgres- server and the functions and variables within the
- file are made available to the functions within
+ After you have created and registered a user-defined
+ function, your work is essentially done.
Postgres,
+ however, must load the object code (e.g., a .o file, or
+ a shared library) that implements your function. As
+ previously mentioned,
Postgres loads your code at
+ runtime, as required. In order to allow your code to be
+ dynamically loaded, you may have to compile and
+ link-edit it in a special way. This section briefly
+ describes how to perform the compilation and
+ link-editing required before you can load your user-defined
+ functions into a running
Postgres server. Note that
+ this process has changed as of Version 4.2.
+
+
+
+ You should expect to read (and reread, and re-reread) the
+ manual pages for the C compiler, cc(1), and the link
+ editor, ld(1), if you have specific questions. In
+ addition, the regression test suites in the directory
+ PGROOT/src/regress contain several
+ working examples of this process. If you copy what these
+ tests do, you should not have any problems.
+
+
+ The following terminology will be used below:
+
+
+
+ Dynamic loading
+ is what
Postgres does to an object file. The
+ object file is copied into the running
Postgres+ server and the functions and variables within the
+ file are made available to the functions within
- the dynamic loading mechanism provided by the
- operating system.
-
-
-
- Loading and link editing
- is what you do to an object file in order to produce
- another kind of object file (e.g., an executable
- program or a shared library). You perform
- this using the link editing program, ld(1).
-
-
-
-
+ the dynamic loading mechanism provided by the
+ operating system.
+
+
+
+ Loading and link editing
+ is what you do to an object file in order to produce
+ another kind of object file (e.g., an executable
+ program or a shared library). You perform
+ this using the link editing program, ld(1).
+
+
+
+
- The following general restrictions and notes also apply
- to the discussion below:
-
-
-Paths given to the create function command must be
- absolute paths (i.e., start with "/") that refer to
- directories visible on the machine on which the
-
Postgres server is running.
-
-Relative paths do in fact work,
-but are relative to
-the directory where the database resides (which is generally
-invisible to the frontend application). Obviously, it makes
-no sense to make the path relative to the directory in which
-the user started the frontend application, since the server
-could be running on a completely different machine!
-
-
-
-
-
-The
Postgres user must be able to traverse the path
- given to the create function command and be able to
- read the object file. This is because the
Postgres- server runs as the
Postgres user, not as the user
- who starts up the frontend process. (Making the
- file or a higher-level directory unreadable and/or
- unexecutable by the "postgres" user is an extremely
- common mistake.)
-
-
-
-Symbol names defined within object files must not
- conflict with each other or with symbols defined in
-
-
-
-The GNU C compiler usually does not provide the special
- options that are required to use the operating
- system's dynamic loader interface. In such cases,
- the C compiler that comes with the operating system
- must be used.
-
-
-
-
+ The following general restrictions and notes also apply
+ to the discussion below:
+
+
+ Paths given to the create function command must be
+ absolute paths (i.e., start with "/") that refer to
+ directories visible on the machine on which the
+
Postgres server is running.
-
-
<acronym>ULTRIX</acronym>
+
+ Relative paths do in fact work,
+ but are relative to
+ the directory where the database resides (which is generally
+ invisible to the frontend application). Obviously, it makes
+ no sense to make the path relative to the directory in which
+ the user started the frontend application, since the server
+ could be running on a completely different machine!
+
+
+
+
- It is very easy to build dynamically-loaded object
- files under ULTRIX. ULTRIX does not have any shared library
- mechanism and hence does not place any restrictions on
- the dynamic loader interface. On the other
- hand, we had to (re)write a non-portable dynamic loader
- ourselves and could not use true shared libraries.
- Under ULTRIX, the only restriction is that you must
- produce each object file with the option -G 0. (Notice
- that that's the numeral ``0'' and not the letter
- ``O''). For example,
+
+ The
Postgres user must be able to traverse the path
+ given to the create function command and be able to
+ read the object file. This is because the
Postgres+ server runs as the
Postgres user, not as the user
+ who starts up the frontend process. (Making the
+ file or a higher-level directory unreadable and/or
+ unexecutable by the "postgres" user is an extremely
+ common mistake.)
+
+
+
+
+ Symbol names defined within object files must not
+ conflict with each other or with symbols defined in
+
+
+
+
+ The GNU C compiler usually does not provide the special
+ options that are required to use the operating
+ system's dynamic loader interface. In such cases,
+ the C compiler that comes with the operating system
+ must be used.
+
+
+
+
+
+
+
<acronym>ULTRIX</acronym>
+
+ It is very easy to build dynamically-loaded object
+ files under ULTRIX. ULTRIX does not have any shared library
+ mechanism and hence does not place any restrictions on
+ the dynamic loader interface. On the other
+ hand, we had to (re)write a non-portable dynamic loader
+ ourselves and could not use true shared libraries.
+ Under ULTRIX, the only restriction is that you must
+ produce each object file with the option -G 0. (Notice
+ that that's the numeral ``0'' and not the letter
+ ``O''). For example,
# simple ULTRIX example
% cc -G 0 -c foo.c
-
- produces an object file called foo.o that can then be
-
dynamically loaded into
Postgres.
-No additional loading or link-editing must be performed.
-
-
+
+ produces an object file called foo.o that can then be
+ dynamically loaded into
Postgres.
+ No additional loading or link-editing must be performed.
+
+
-
-
<acronym>DEC OSF/1</acronym>
+
+
<acronym>DEC OSF/1</acronym>
- Under DEC OSF/1, you can take any simple object file
- and produce a shared object file by running the ld command
- over it with the correct options. The commands to
- do this look like:
+ Under DEC OSF/1, you can take any simple object file
+ and produce a shared object file by running the ld command
+ over it with the correct options. The commands to
+ do this look like:
# simple DEC OSF/1 example
% cc -c foo.c
% ld -shared -expect_unresolved '*' -o foo.so foo.o
-
+
+
+ The resulting shared object file can then be loaded
+ into
Postgres. When specifying the object file name to
+ the create function command, one must give it the name
+ of the shared object file (ending in .so) rather than
+ the simple object file.
- The resulting shared object file can then be loaded
- into
Postgres. When specifying the object file name to
- the create function command, one must give it the name
- of the shared object file (ending in .so) rather than
- the simple object file.
-
-Actually,
Postgres does not care
-what you name the
-file as long as it is a shared object file. If you prefer
-to name your shared object files with the extension .o, this
- so long as you make sure that the correct
-file name is given to the create function command. In
-other words, you must simply be consistent. However, from a
-pragmatic point of view, we discourage this practice because
-you will undoubtedly confuse yourself with regards to which
-files have been made into shared object files and which have
-not. For example, it's very hard to write Makefiles to do
-the link-editing automatically if both the object file and
-the shared object file end in .o!
-
-
+
+ Actually,
Postgres does not care
+ what you name the
+ file as long as it is a shared object file. If you prefer
+ to name your shared object files with the extension .o, this
+ so long as you make sure that the correct
+ file name is given to the create function command. In
+ other words, you must simply be consistent. However, from a
+ pragmatic point of view, we discourage this practice because
+ you will undoubtedly confuse yourself with regards to which
+ files have been made into shared object files and which have
+ not. For example, it's very hard to write Makefiles to do
+ the link-editing automatically if both the object file and
+ the shared object file end in .o!
+
+
-If the file you specify is
- not a shared object, the backend will hang!
-
-
+ If the file you specify is
+ not a shared object, the backend will hang!
+
+
-
-
</div>
<div class="diff rem">-<acronym>SunOS 4.x</acronym>, <acronym>Solaris 2.x</acronym> and</div>
<div class="diff add">+<span class="marked"> </span><sect1></div>
<div class="diff add">+<span class="marked"> </span><title></div>
<div class="diff add">+<span class="marked"> </span><acronym>SunOS 4.x</acronym>, <acronym>Solaris 2.x</acronym> and</div>
<div class="diff ctx"> <acronym>HP-UX</acronym>
- Under SunOS 4.x, Solaris 2.x and HP-UX, the simple
- object file must be created by compiling the source
- file with special compiler flags and a shared library
- must be produced.
- The necessary steps with HP-UX are as follows. The +z
- flag to the HP-UX C compiler produces so-called
- "Position Independent Code" (PIC) and the +u flag
- removes
- some alignment restrictions that the PA-RISC architecture
- normally enforces. The object file must be turned
- into a shared library using the HP-UX link editor with
- the -b option. This sounds complicated but is actually
- very simple, since the commands to do it are just:
+ Under SunOS 4.x, Solaris 2.x and HP-UX, the simple
+ object file must be created by compiling the source
+ file with special compiler flags and a shared library
+ must be produced.
+ The necessary steps with HP-UX are as follows. The +z
+ flag to the HP-UX C compiler produces so-called
+ "Position Independent Code" (PIC) and the +u flag
+ removes
+ some alignment restrictions that the PA-RISC architecture
+ normally enforces. The object file must be turned
+ into a shared library using the HP-UX link editor with
+ the -b option. This sounds complicated but is actually
+ very simple, since the commands to do it are just:
# simple HP-UX example
% cc +z +u -c foo.c
% ld -b -o foo.sl foo.o
-
-
+
+
- As with the .so files mentioned in the last subsection,
- the create function command must be told which file is
- the correct file to load (i.e., you must give it the
- location of the shared library, or .sl file).
- Under SunOS 4.x, the commands look like:
+ As with the .so files mentioned in the last subsection,
+ the create function command must be told which file is
+ the correct file to load (i.e., you must give it the
+ location of the shared library, or .sl file).
+ Under SunOS 4.x, the commands look like:
# simple SunOS 4.x example
% cc -PIC -c foo.c
% ld -dc -dp -Bdynamic -o foo.so foo.o
-
+
- and the equivalent lines under Solaris 2.x are:
+ and the equivalent lines under Solaris 2.x are:
# simple Solaris 2.x example
% cc -K PIC -c foo.c
% ld -G -Bdynamic -o foo.so foo.o
-
+
or
# simple Solaris 2.x example
% gcc -fPIC -c foo.c
% ld -G -Bdynamic -o foo.so foo.o
-
-
+
+
- When linking shared libraries, you may have to specify
- some additional shared libraries (typically system
- libraries, such as the C and math libraries) on your ld
- command line.
-
-
-
+ When linking shared libraries, you may have to specify
+ some additional shared libraries (typically system
+ libraries, such as the C and math libraries) on your ld
+ command line.
+
+
+
projects / postgresql.git / commitdiff