<!-- doc/src/sgml/dfunc.sgml -->

<sect2 id="dfunc">
 <title>Compiling and Linking Dynamically-Loaded Functions</title>

 <para>
  Before you are able to use your
  <productname>PostgreSQL</productname> extension functions written in
  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</primary></indexterm>

 </para>

 <para>
  For information beyond what is contained in this section
  you should read the documentation of your
  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
  examples you will make your modules dependent on the availability
  of the <productname>PostgreSQL</productname> source code, however.
 </para>

 <para>
  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>
  (<acronym>PIC</acronym>),<indexterm><primary>PIC</primary></indexterm> 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
  distinguish it from linking an executable (at least in theory
  &mdash; on some systems the practice is much uglier).
 </para>

 <para>
  In the following examples we assume that your source code is in a
  file <filename>foo.c</filename> and we will create a shared library
  <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>

<!--
  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.
-->

  <variablelist>
   <varlistentry>
    <term>
     <systemitem class="osname">FreeBSD</systemitem>
     <indexterm><primary>FreeBSD</primary><secondary>shared library</secondary></indexterm>
    </term>
    <listitem>
     <para>
      The compiler flag to create <acronym>PIC</acronym> is
      <option>-fPIC</option>.  To create shared libraries the compiler
      flag is <option>-shared</option>.
<programlisting>
cc -fPIC -c foo.c
cc -shared -o foo.so foo.o
</programlisting>
      This is applicable as of version 13.0 of
      <systemitem class="osname">FreeBSD</systemitem>, older versions used
      the <filename>gcc</filename> compiler.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>
     <systemitem class="osname">Linux</systemitem>
     <indexterm><primary>Linux</primary><secondary>shared library</secondary></indexterm>
    </term>
    <listitem>
     <para>
      The compiler flag to create <acronym>PIC</acronym> is
      <option>-fPIC</option>.
      The compiler flag to create a shared library is
      <option>-shared</option>.  A complete example looks like this: