1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
|
<HTML>
<HEAD>
<TITLE>The POSTGRES95 User Manual - Appendix A:</TITLE>
</HEAD>
<BODY>
<font size=-1>
<A HREF="pg95user.html">[ TOC ]</A>
<A HREF="refs.html">[ Previous ]</A>
[ Next ]
</font>
<HR>
<H1>Appendix A: Linking Dynamically-Loaded Functions</H1>
<HR>
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
linkedit it in a special way. This section briefly
describes how to perform the compilation and
linkediting 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.<A HREF="#11">11</A> 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
/usr/local/postgres95/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:
<DL>
<DT>Dynamic loading
<DD>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 POSTGRES process. POSTGRES does this using
the dynamic loading mechanism provided by the
operating system.
<DT>Loading and link editing
<DD>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).
</DL>
<p>
The following general restrictions and notes also apply
to the discussion below.
<UL>
<LI>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.<A HREF="#12">12</A>
<LI>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.)
<LI>Symbol names defined within object files must not
conflict with each other or with symbols defined in
POSTGRES.
<LI>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.
</UL>
<p>
<B>ULTRIX</B><br>
It is very easy to build dynamically-loaded object
files under ULTRIX. ULTRIX does not have any sharedlibrary
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,
<pre> # simple ULTRIX example
% cc -G 0 -c foo.c
</pre>
produces an object file called foo.o that can then be
dynamically loaded into POSTGRES. No additional loading or link-editing must be performed.
<p>
<B>DEC OSF/1</B><br>
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:
<pre> # simple DEC OSF/1 example
% cc -c foo.c
% ld -shared -expect_unresolved '*' -o foo.so foo.o
</pre>
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.<A HREF="#13">13</A> If the file you specify is
not a shared object, the backend will hang!
<p>
<B>SunOS 4.x, Solaris 2.x and HP-UX</B><br>
Under both 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:
<pre> # simple HP-UX example
% cc +z +u -c foo.c
% ld -b -o foo.sl foo.o
</pre>
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:
<pre> # simple SunOS 4.x example
% cc -PIC -c foo.c
% ld -dc -dp -Bdynamic -o foo.so foo.o
</pre>
and the equivalent lines under Solaris 2.x are:
<pre> # simple Solaris 2.x example
% cc -K PIC -c foo.c
or
% gcc -fPIC -c foo.c
% ld -G -Bdynamic -o foo.so foo.o
</pre>
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.
<HR>
<A NAME="11"><B>11.</B></A> 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.
<hr width=50 align=left>
<A NAME="12"><B>12.</B></A> 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!<br>
<hr width=50 align=left>
<A NAME="13"><B>13.</B></A> 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
is fine with POSTGRES 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!<br>
<HR>
<font size=-1>
<A HREF="pg95user.html">[ TOC ]</A>
<A HREF="refs.html">[ Previous ]</A>
[ Next ]
</font>
</BODY>
</HTML>
|
