2007-02-01 01:28:19 +01:00
|
|
|
<!-- $PostgreSQL: pgsql/doc/src/sgml/dfunc.sgml,v 1.35 2007/02/01 00:28:16 momjian Exp $ -->
|
2000-03-31 05:27:42 +02:00
|
|
|
|
2001-01-12 23:15:32 +01:00
|
|
|
<sect2 id="dfunc">
|
|
|
|
<title id="dfunc-title">Compiling and Linking Dynamically-Loaded Functions</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Before you are able to use your
|
2001-10-26 21:58:12 +02:00
|
|
|
<productname>PostgreSQL</productname> extension functions written in
|
2003-08-31 19:32:24 +02:00
|
|
|
C, they must be compiled and linked in a special way to produce a
|
|
|
|
file that can be dynamically loaded by the server. To be precise, a
|
|
|
|
<firstterm>shared library</firstterm> needs to be
|
|
|
|
created.<indexterm><primary>shared library</></indexterm>
|
|
|
|
|
2001-01-12 23:15:32 +01:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2003-04-10 03:22:45 +02:00
|
|
|
For information beyond what is contained in this section
|
|
|
|
you should read the documentation of your
|
2001-01-12 23:15:32 +01:00
|
|
|
operating system, in particular the manual pages for the C compiler,
|
|
|
|
<command>cc</command>, and the link editor, <command>ld</command>.
|
|
|
|
In addition, the <productname>PostgreSQL</productname> source code
|
|
|
|
contains several working examples in the
|
|
|
|
<filename>contrib</filename> directory. If you rely on these
|
2001-01-20 21:59:29 +01:00
|
|
|
examples you will make your modules dependent on the availability
|
2001-01-12 23:15:32 +01:00
|
|
|
of the <productname>PostgreSQL</productname> source code, however.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2005-09-14 23:14:26 +02:00
|
|
|
Creating shared libraries is generally analogous to linking
|
|
|
|
executables: first the source files are compiled into object files,
|
|
|
|
then the object files are linked together. The object files need to
|
|
|
|
be created as <firstterm>position-independent code</firstterm>
|
2003-08-31 19:32:24 +02:00
|
|
|
(<acronym>PIC</acronym>),<indexterm><primary>PIC</></> which
|
|
|
|
conceptually means that they can be placed at an arbitrary location
|
|
|
|
in memory when they are loaded by the executable. (Object files
|
|
|
|
intended for executables are usually not compiled that way.) The
|
|
|
|
command to link a shared library contains special flags to
|
2004-11-15 07:32:15 +01:00
|
|
|
distinguish it from linking an executable (at least in theory
|
|
|
|
— on some systems the practice is much uglier).
|
2001-01-12 23:15:32 +01:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
In the following examples we assume that your source code is in a
|
2002-01-07 03:29:15 +01:00
|
|
|
file <filename>foo.c</filename> and we will create a shared library
|
2001-01-12 23:15:32 +01:00
|
|
|
<filename>foo.so</filename>. The intermediate object file will be
|
|
|
|
called <filename>foo.o</filename> unless otherwise noted. A shared
|
|
|
|
library can contain more than one object file, but we only use one
|
|
|
|
here.
|
|
|
|
</para>
|
|
|
|
|
1999-10-04 17:18:54 +02:00
|
|
|
<!--
|
2003-04-10 03:22:45 +02:00
|
|
|
Note: Reading GNU Libtool sources is generally a good way of
|
|
|
|
figuring out this information. The methods used within PostgreSQL
|
|
|
|
source code are not necessarily ideal.
|
1999-10-04 17:18:54 +02:00
|
|
|
-->
|
|
|
|
|
2001-01-12 23:15:32 +01:00
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
2002-09-21 20:32:54 +02:00
|
|
|
<term><systemitem class="osname">BSD/OS</></term>
|
2003-08-31 19:32:24 +02:00
|
|
|
<indexterm><primary>BSD/OS</><secondary>shared library</></>
|
1999-10-04 17:18:54 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2001-01-12 23:15:32 +01:00
|
|
|
The compiler flag to create <acronym>PIC</acronym> is
|
|
|
|
<option>-fpic</option>. The linker flag to create shared
|
|
|
|
libraries is <option>-shared</option>.
|
|
|
|
<programlisting>
|
|
|
|
gcc -fpic -c foo.c
|
|
|
|
ld -shared -o foo.so foo.o
|
|
|
|
</programlisting>
|
|
|
|
This is applicable as of version 4.0 of
|
2002-09-21 20:32:54 +02:00
|
|
|
<systemitem class="osname">BSD/OS</>.
|
1999-10-04 17:18:54 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
2001-01-12 23:15:32 +01:00
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
2002-09-21 20:32:54 +02:00
|
|
|
<term><systemitem class="osname">FreeBSD</></term>
|
2003-08-31 19:32:24 +02:00
|
|
|
<indexterm><primary>FreeBSD</><secondary>shared library</></>
|
1999-10-04 17:18:54 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2001-01-12 23:15:32 +01:00
|
|
|
The compiler flag to create <acronym>PIC</acronym> is
|
|
|
|
<option>-fpic</option>. To create shared libraries the compiler
|
|
|
|
flag is <option>-shared</option>.
|
|
|
|
<programlisting>
|
|
|
|
gcc -fpic -c foo.c
|
|
|
|
gcc -shared -o foo.so foo.o
|
|
|
|
</programlisting>
|
|
|
|
This is applicable as of version 3.0 of
|
2002-09-21 20:32:54 +02:00
|
|
|
<systemitem class="osname">FreeBSD</>.
|
1999-10-04 17:18:54 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
2001-01-12 23:15:32 +01:00
|
|
|
</varlistentry>
|
1998-03-01 09:16:16 +01:00
|
|
|
|
2001-01-12 23:15:32 +01:00
|
|
|
<varlistentry>
|
2002-09-21 20:32:54 +02:00
|
|
|
<term><systemitem class="osname">HP-UX</></term>
|
2003-08-31 19:32:24 +02:00
|
|
|
<indexterm><primary>HP-UX</><secondary>shared library</></>
|
1999-10-04 17:18:54 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2001-01-12 23:15:32 +01:00
|
|
|
The compiler flag of the system compiler to create
|
|
|
|
<acronym>PIC</acronym> is <option>+z</option>. When using
|
2002-09-21 20:32:54 +02:00
|
|
|
<application>GCC</application> it's <option>-fpic</option>. The
|
2007-02-01 01:28:19 +01:00
|
|
|
linker flag for shared libraries is <option>-b</option>. So:
|
2001-01-12 23:15:32 +01:00
|
|
|
<programlisting>
|
|
|
|
cc +z -c foo.c
|
|
|
|
</programlisting>
|
2007-02-01 01:28:19 +01:00
|
|
|
or:
|
2001-01-12 23:15:32 +01:00
|
|
|
<programlisting>
|
|
|
|
gcc -fpic -c foo.c
|
|
|
|
</programlisting>
|
2007-02-01 01:28:19 +01:00
|
|
|
and then:
|
2001-01-12 23:15:32 +01:00
|
|
|
<programlisting>
|
|
|
|
ld -b -o foo.sl foo.o
|
|
|
|
</programlisting>
|
2002-09-21 20:32:54 +02:00
|
|
|
<systemitem class="osname">HP-UX</> uses the extension
|
2001-01-12 23:15:32 +01:00
|
|
|
<filename>.sl</filename> for shared libraries, unlike most other
|
|
|
|
systems.
|
1999-10-04 17:18:54 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
2001-01-12 23:15:32 +01:00
|
|
|
</varlistentry>
|
1998-03-01 09:16:16 +01:00
|
|
|
|
2001-01-12 23:15:32 +01:00
|
|
|
<varlistentry>
|
2002-09-21 20:32:54 +02:00
|
|
|
<term><systemitem class="osname">IRIX</></term>
|
2003-08-31 19:32:24 +02:00
|
|
|
<indexterm><primary>IRIX</><secondary>shared library</></>
|
1999-10-04 17:18:54 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2001-01-12 23:15:32 +01:00
|
|
|
<acronym>PIC</acronym> is the default, no special compiler
|
|
|
|
options are necessary. The linker option to produce shared
|
|
|
|
libraries is <option>-shared</option>.
|
|
|
|
<programlisting>
|
|
|
|
cc -c foo.c
|
|
|
|
ld -shared -o foo.so foo.o
|
|
|
|
</programlisting>
|
1999-10-04 17:18:54 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
2001-01-12 23:15:32 +01:00
|
|
|
</varlistentry>
|
1999-10-04 17:18:54 +02:00
|
|
|
|
2001-01-12 23:15:32 +01:00
|
|
|
<varlistentry>
|
2002-09-21 20:32:54 +02:00
|
|
|
<term><systemitem class="osname">Linux</></term>
|
2003-08-31 19:32:24 +02:00
|
|
|
<indexterm><primary>Linux</><secondary>shared library</></>
|
1999-10-04 17:18:54 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2001-01-12 23:15:32 +01:00
|
|
|
The compiler flag to create <acronym>PIC</acronym> is
|
|
|
|
<option>-fpic</option>. On some platforms in some situations
|
|
|
|
<option>-fPIC</option> must be used if <option>-fpic</option>
|
|
|
|
does not work. Refer to the GCC manual for more information.
|
|
|
|
The compiler flag to create a shared library is
|
|
|
|
<option>-shared</option>. A complete example looks like this:
|
|
|
|
<programlisting>
|
|
|
|
cc -fpic -c foo.c
|
|
|
|
cc -shared -o foo.so foo.o
|
|
|
|
</programlisting>
|
1999-10-04 17:18:54 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
2001-01-12 23:15:32 +01:00
|
|
|
</varlistentry>
|
1999-10-04 17:18:54 +02:00
|
|
|
|
2001-01-12 23:15:32 +01:00
|
|
|
<varlistentry>
|
2002-09-21 20:32:54 +02:00
|
|
|
<term><systemitem class="osname">MacOS X</></term>
|
2003-08-31 19:32:24 +02:00
|
|
|
<indexterm><primary>MacOS X</><secondary>shared library</></>
|
2002-09-21 20:32:54 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2003-04-10 03:22:45 +02:00
|
|
|
Here is an example. It assumes the developer tools are installed.
|
2002-09-21 20:32:54 +02:00
|
|
|
<programlisting>
|
|
|
|
cc -c foo.c
|
|
|
|
cc -bundle -flat_namespace -undefined suppress -o foo.so foo.o
|
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><systemitem class="osname">NetBSD</></term>
|
2003-08-31 19:32:24 +02:00
|
|
|
<indexterm><primary>NetBSD</><secondary>shared library</></>
|
1999-10-04 17:18:54 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2001-01-12 23:15:32 +01:00
|
|
|
The compiler flag to create <acronym>PIC</acronym> is
|
|
|
|
<option>-fpic</option>. For <acronym>ELF</acronym> systems, the
|
|
|
|
compiler with the flag <option>-shared</option> is used to link
|
|
|
|
shared libraries. On the older non-ELF systems, <literal>ld
|
|
|
|
-Bshareable</literal> is used.
|
|
|
|
<programlisting>
|
|
|
|
gcc -fpic -c foo.c
|
|
|
|
gcc -shared -o foo.so foo.o
|
|
|
|
</programlisting>
|
1999-10-04 17:18:54 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
2001-01-12 23:15:32 +01:00
|
|
|
</varlistentry>
|
1999-10-04 17:18:54 +02:00
|
|
|
|
2001-01-12 23:15:32 +01:00
|
|
|
<varlistentry>
|
2002-09-21 20:32:54 +02:00
|
|
|
<term><systemitem class="osname">OpenBSD</></term>
|
2003-08-31 19:32:24 +02:00
|
|
|
<indexterm><primary>OpenBSD</><secondary>shared library</></>
|
2001-01-12 23:15:32 +01:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
The compiler flag to create <acronym>PIC</acronym> is
|
|
|
|
<option>-fpic</option>. <literal>ld -Bshareable</literal> is
|
|
|
|
used to link shared libraries.
|
|
|
|
<programlisting>
|
|
|
|
gcc -fpic -c foo.c
|
|
|
|
ld -Bshareable -o foo.so foo.o
|
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
1999-10-04 17:18:54 +02:00
|
|
|
|
2002-08-27 01:22:47 +02:00
|
|
|
<varlistentry>
|
2002-09-21 20:32:54 +02:00
|
|
|
<term><systemitem class="osname">Solaris</></term>
|
2003-08-31 19:32:24 +02:00
|
|
|
<indexterm><primary>Solaris</><secondary>shared library</></>
|
2001-01-12 23:15:32 +01:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
The compiler flag to create <acronym>PIC</acronym> is
|
|
|
|
<option>-KPIC</option> with the Sun compiler and
|
2002-09-21 20:32:54 +02:00
|
|
|
<option>-fpic</option> with <application>GCC</>. To
|
2001-01-12 23:15:32 +01:00
|
|
|
link shared libraries, the compiler option is
|
|
|
|
<option>-G</option> with either compiler or alternatively
|
2002-09-21 20:32:54 +02:00
|
|
|
<option>-shared</option> with <application>GCC</>.
|
2001-01-12 23:15:32 +01:00
|
|
|
<programlisting>
|
|
|
|
cc -KPIC -c foo.c
|
|
|
|
cc -G -o foo.so foo.o
|
|
|
|
</programlisting>
|
|
|
|
or
|
|
|
|
<programlisting>
|
|
|
|
gcc -fpic -c foo.c
|
|
|
|
gcc -G -o foo.so foo.o
|
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
1998-03-01 09:16:16 +01:00
|
|
|
|
2001-11-12 20:19:39 +01:00
|
|
|
<varlistentry>
|
2002-09-21 20:32:54 +02:00
|
|
|
<term><systemitem class="osname">Tru64 UNIX</></term>
|
2003-08-31 19:32:24 +02:00
|
|
|
<indexterm><primary>Tru64 UNIX</><secondary>shared library</></>
|
2001-11-12 20:19:39 +01:00
|
|
|
<indexterm><primary>Digital UNIX</><see>Tru64 UNIX</></>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
<acronym>PIC</acronym> is the default, so the compilation command
|
|
|
|
is the usual one. <command>ld</command> with special options is
|
2007-02-01 01:28:19 +01:00
|
|
|
used to do the linking.
|
2001-11-12 20:19:39 +01:00
|
|
|
<programlisting>
|
|
|
|
cc -c foo.c
|
|
|
|
ld -shared -expect_unresolved '*' -o foo.so foo.o
|
|
|
|
</programlisting>
|
|
|
|
The same procedure is used with GCC instead of the system
|
|
|
|
compiler; no special options are required.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2001-01-12 23:15:32 +01:00
|
|
|
<varlistentry>
|
2002-09-21 20:32:54 +02:00
|
|
|
<term><systemitem class="osname">UnixWare</></term>
|
2003-08-31 19:32:24 +02:00
|
|
|
<indexterm><primary>UnixWare</><secondary>shared library</></>
|
2001-01-12 23:15:32 +01:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
The compiler flag to create <acronym>PIC</acronym> is <option>-K
|
|
|
|
PIC</option> with the SCO compiler and <option>-fpic</option>
|
|
|
|
with <productname>GCC</productname>. To link shared libraries,
|
|
|
|
the compiler option is <option>-G</option> with the SCO compiler
|
|
|
|
and <option>-shared</option> with
|
|
|
|
<productname>GCC</productname>.
|
|
|
|
<programlisting>
|
|
|
|
cc -K PIC -c foo.c
|
|
|
|
cc -G -o foo.so foo.o
|
|
|
|
</programlisting>
|
|
|
|
or
|
|
|
|
<programlisting>
|
|
|
|
gcc -fpic -c foo.c
|
|
|
|
gcc -shared -o foo.so foo.o
|
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
2000-05-02 22:02:03 +02:00
|
|
|
|
2001-01-12 23:15:32 +01:00
|
|
|
</variablelist>
|
1998-03-01 09:16:16 +01:00
|
|
|
|
2001-01-12 23:15:32 +01:00
|
|
|
<tip>
|
|
|
|
<para>
|
2005-04-09 05:52:43 +02:00
|
|
|
If this is too complicated for you, you should consider using
|
|
|
|
<ulink url="http://www.gnu.org/software/libtool/">
|
|
|
|
<productname>GNU Libtool</productname></ulink>,
|
|
|
|
which hides the platform differences behind a uniform interface.
|
2001-01-12 23:15:32 +01:00
|
|
|
</para>
|
|
|
|
</tip>
|
1998-03-01 09:16:16 +01:00
|
|
|
|
2001-01-12 23:15:32 +01:00
|
|
|
<para>
|
|
|
|
The resulting shared library file can then be loaded into
|
2001-11-21 06:53:41 +01:00
|
|
|
<productname>PostgreSQL</productname>. When specifying the file name
|
2001-01-12 23:15:32 +01:00
|
|
|
to the <command>CREATE FUNCTION</command> command, one must give it
|
2001-10-26 21:58:12 +02:00
|
|
|
the name of the shared library file, not the intermediate object file.
|
|
|
|
Note that the system's standard shared-library extension (usually
|
|
|
|
<literal>.so</literal> or <literal>.sl</literal>) can be omitted from
|
|
|
|
the <command>CREATE FUNCTION</command> command, and normally should
|
|
|
|
be omitted for best portability.
|
|
|
|
</para>
|
2001-01-12 23:15:32 +01:00
|
|
|
|
2001-10-26 21:58:12 +02:00
|
|
|
<para>
|
2001-05-19 11:01:10 +02:00
|
|
|
Refer back to <xref linkend="xfunc-c-dynload"> about where the
|
|
|
|
server expects to find the shared library files.
|
2001-01-12 23:15:32 +01:00
|
|
|
</para>
|
2000-05-02 22:02:03 +02:00
|
|
|
|
2001-01-12 23:15:32 +01:00
|
|
|
<!--
|
2000-05-02 22:02:03 +02:00
|
|
|
Under AIX, object files are compiled normally but building the shared
|
|
|
|
library requires a couple of steps. First, create the object file:
|
|
|
|
.nf
|
|
|
|
cc <other flags> -c foo.c
|
|
|
|
.fi
|
|
|
|
You must then create a symbol \*(lqexports\*(rq file for the object
|
|
|
|
file:
|
|
|
|
.nf
|
2005-01-22 23:56:36 +01:00
|
|
|
mkldexport foo.o `pwd` > foo.exp
|
2000-05-02 22:02:03 +02:00
|
|
|
.fi
|
|
|
|
Finally, you can create the shared library:
|
|
|
|
.nf
|
|
|
|
ld <other flags> -H512 -T512 -o foo.so -e _nostart \e
|
|
|
|
-bI:.../lib/postgres.exp -bE:foo.exp foo.o \e
|
|
|
|
-lm -lc 2>/dev/null
|
|
|
|
.fi
|
|
|
|
-->
|
|
|
|
|
2001-01-12 23:15:32 +01:00
|
|
|
</sect2>
|