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.
   </para>

   <para>
    The following algorithm is used to locate the shared object file
    based on the name given in the <command>CREATE FUNCTION</command>
    command:

    <orderedlist>
     <listitem>
      <para>
       If the name is an absolute path, the given file is loaded.
      </para>
     </listitem>

     <listitem>
      <para>
       If the name starts with the string <literal>$libdir</literal>,
       that part is replaced by the <productname>PostgreSQL</productname> package
        library directory
       name, which is determined at build time.<indexterm><primary>$libdir</primary></indexterm>
      </para>
     </listitem>

     <listitem>
      <para>
       If the name does not contain a directory part, the file is
       searched for in the path specified by the configuration variable
       <xref linkend="guc-dynamic-library-path"/>.<indexterm><primary>dynamic_library_path</primary></indexterm>
      </para>
     </listitem>

     <listitem>
      <para>
       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.)
      </para>
     </listitem>
    </orderedlist>

    If this sequence does not work, the platform-specific shared
    library file name extension (often <filename>.so</filename>) is
    appended to the given name and this sequence is tried again.  If
    that fails as well, the load will fail.
   </para>

   <para>
    It is recommended to locate shared libraries either relative to
    <literal>$libdir</literal> or through the dynamic library path.
    This simplifies version upgrades if the new installation is at a
    different location.  The actual directory that
    <literal>$libdir</literal> stands for can be found out with the
    command <literal>pg_config --pkglibdir</literal>.
   </para>

   <para>
    The user ID the <productname>PostgreSQL</productname> 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 <systemitem>postgres</systemitem>
    user is a common mistake.
   </para>

   <para>
    In any case, the file name that is given in the
    <command>CREATE FUNCTION</command> command is recorded literally
    in the system catalogs, so if the file needs to be loaded again
    the same procedure is applied.
   </para>

   <note>
    <para>
     <productname>PostgreSQL</productname> will not compile a C function
     automatically.  The object file must be compiled before it is referenced
     in a <command>CREATE
     FUNCTION</command> command.  See <xref linkend="dfunc"/> for additional
     information.
    </para>
   </note>

   <indexterm zone="xfunc-c-dynload">
    <primary>magic block</primary>
   </indexterm>
   <indexterm zone="xfunc-c-dynload">
    <primary><literal>PG_MODULE_MAGIC</literal></primary>
   </indexterm>

   <para>
    To ensure that a dynamically loaded object file is not loaded into an
    incompatible server, <productname>PostgreSQL</productname> checks that the
    file contains a <quote>magic block</quote> with the appropriate contents.
    This allows the server to detect obvious incompatibilities, such as code
    compiled for a different major version of
    <productname>PostgreSQL</productname>. To include a magic block,
    write this in one (and only one) of the module source files, after having
    included the header <filename>fmgr.h</filename>:

<programlisting>
PG_MODULE_MAGIC;
</programlisting>