Skip to content

P
Postgres FD Implementation
Commit cb8b40e6 authored by Peter Eisentraut's avatar Peter Eisentraut
Browse files
Options

Allow special '$libdir' macro to show up in object file path in CREATE 

FUNCTION command.  Guard against trying to load a directory.  Update
documentation some.
parent a008109d
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 387 additions and 522 deletions
doc/src/sgml/dfunc.sgml
View file @ cb8b40e6
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/dfunc.sgml,v 1.13 2001/01/20 20:59:28 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/dfunc.sgml,v 1.14 2001/05/19 09:01:10 petere Exp $
-->
<sect2 id="dfunc">
......@@ -264,7 +264,7 @@ gcc -shared -o foo.so foo.o
<productname>Postgres</productname>. When specifying the file name
to the <command>CREATE FUNCTION</command> command, one must give it
the name of the shared library file (ending in
<filename>.so</filename>) rather than the simple object file.
<filename>.so</filename>) rather than the intermediate object file.
<note>
<para>
......@@ -273,21 +273,8 @@ gcc -shared -o foo.so foo.o
</para>
</note>
Paths given to the <command>CREATE FUNCTION</command> command must
be absolute paths (i.e., start with <literal>/</literal>) that refer
to directories visible on the machine on which the
<productname>Postgres</productname> 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 user id the
<productname>Postgres</productname> server runs as must be able to
traverse the path given to the <command>CREATE FUNCTION</command>
command and be able to read the shared library file. (Making the
file or a higher-level directory not readable and/or not executable
by the <quote>postgres</quote> user is a common mistake.)
Refer back to <xref linkend="xfunc-c-dynload"> about where the
server expects to find the shared library files.
</para>
<!--
......
doc/src/sgml/ref/create_function.sgml
View file @ cb8b40e6
This diff is collapsed.
doc/src/sgml/ref/drop_function.sgml
View file @ cb8b40e6
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_function.sgml,v 1.11 2001/05/08 17:35:57 momjian Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_function.sgml,v 1.12 2001/05/19 09:01:10 petere Exp $
Postgres documentation
-->
......@@ -116,7 +116,7 @@ NOTICE RemoveFunction: Function "<replaceable class="parameter">name</replaceabl
<para>
Refer to
<xref linkend="sql-createfunction" endterm="sql-createfunction-title">
<xref linkend="sql-createfunction">
for information on creating functions.
</para>
......
doc/src/sgml/ref/load.sgml
View file @ cb8b40e6
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/load.sgml,v 1.7 1999/07/22 15:09:12 thomas Exp $
Postgres documentation
$Header: /cvsroot/pgsql/doc/src/sgml/ref/load.sgml,v 1.8 2001/05/19 09:01:10 petere Exp $
-->
<refentry id="SQL-LOAD">
<refmeta>
<refentrytitle id="SQL-LOAD-TITLE">
LOAD
</refentrytitle>
<refentrytitle>LOAD</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta>
<refnamediv>
<refname>
LOAD
</refname>
<refpurpose>
Dynamically loads an object file
</refpurpose>
<refname>LOAD</refname>
<refpurpose>Loads a shared object file</refpurpose>
</refnamediv>
<refsynopsisdiv>
<refsynopsisdivinfo>
<date>1999-07-20</date>
</refsynopsisdivinfo>
<synopsis>
<synopsis>
LOAD '<replaceable class="PARAMETER">filename</replaceable>'
</synopsis>
<refsect2 id="R2-SQL-LOAD-1">
<refsect2info>
<date>1998-09-01</date>
</refsect2info>
<title>
Inputs
</title>
<para>
<variablelist>
<varlistentry>
<term><replaceable class="PARAMETER">filename</replaceable></term>
<listitem>
<para>
Object file for dynamic loading.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<refsect2 id="R2-SQL-LOAD-2">
<refsect2info>
<date>1998-09-24</date>
</refsect2info>
<title>
Outputs
</title>
<para>
<variablelist>
<varlistentry>
<term><computeroutput>
LOAD
</computeroutput></term>
<listitem>
<para>
Message returned on successful completion.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>
ERROR: LOAD: could not open file '<replaceable class="PARAMETER">filename</replaceable>'
</computeroutput></term>
<listitem>
<para>
Message returned if the specified file is not found. The file must be visible
<emphasis>to the <productname>Postgres</productname> backend</emphasis>,
with the appropriate full path name specified, to avoid this message.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</synopsis>
</refsynopsisdiv>
<refsect1 id="R1-SQL-LOAD-1">
<refsect1info>
<date>1998-09-24</date>
</refsect1info>
<title>
Description
</title>
<refsect1 id="sql-load-description">
<title>Description</title>
<para>
Loads an object (or ".o") file into the
<productname>Postgres</productname> backend address space. Once a
file is loaded, all functions in that file can be accessed. This
function is used in support of user-defined types and functions.
Loads a shared object file into the PostgreSQL backend's address
space. If the file had been loaded previously, it is first
unloaded. This command is primarily useful to unload and reload a
shared object file if it has been changed. To make use of the
shared object, a function needs to be declared using the <xref
linkend="sql-createfunction"> command.
</para>
</refsect1>
<refsect1 id="sql-load-compat">
<title>Compatibility</title>
<para>
If a file is not loaded using
<command>LOAD</command>,
the file will be loaded automatically the first time the
function is called by <productname>Postgres</productname>.
<command>LOAD</command>
can also be used to reload an object file if it has been edited and
recompiled. Only objects created from C language files are supported
at this time.
<command>LOAD</command> is a <application>PostgreSQL</application>
extension.
</para>
</refsect1>
<refsect2 id="R2-SQL-LOAD-3">
<refsect2info>
<date>1998-09-24</date>
</refsect2info>
<title>
Notes
</title>
<para>
Functions in loaded object files should not call functions in other
object files loaded through the
<command>LOAD</command>
command. For example, all functions in file <literal>A</literal> should
call each other, functions in the standard or math libraries, or in
Postgres itself. They should not call functions defined in a different
loaded file <literal>B</literal>.
This is because if <literal>B</literal> is reloaded, the Postgres loader is
not able to relocate the calls from the functions in
<literal>A</literal> into
the new address space of <literal>B</literal>.
If <literal>B</literal> is not reloaded, however, there will
not be a problem.
</para>
<para>
Object files must be compiled to contain position independent code.
For example,
on DECstations you must use
<application>/bin/cc</application>
with the <literal>-G 0</literal> option when compiling object files to be
loaded.
</para>
<para>
Note that if you are porting <productname>Postgres</productname>
to a new platform, <command>LOAD</command>
will have to work in order to support ADTs.
</para>
</refsect2>
</refsect1>
<refsect1>
<title>See Also</title>
<refsect1 id="R1-SQL-LOAD-2">
<title>
Usage
</title>
<para>
Load the file <filename>/usr/postgres/demo/circle.o</filename>:
<programlisting>
LOAD '/usr/postgres/demo/circle.o'
</programlisting>
<xref linkend="sql-createfunction">,
<citetitle>PostgreSQL Programmer's Guide</citetitle>
</para>
</refsect1>
<refsect1 id="R1-SQL-LOAD-3">
<title>
Compatibility
</title>
<refsect2 id="R2-SQL-LOAD-4">
<refsect2info>
<date>1998-09-24</date>
</refsect2info>
<title>
SQL92
</title>
<para>
There is no <command>LOAD</command> in <acronym>SQL92</acronym>.
</para>
</refsect2>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
......
doc/src/sgml/xfunc.sgml
View file @ cb8b40e6
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/xfunc.sgml,v 1.31 2001/02/15 19:03:35 tgl Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/xfunc.sgml,v 1.32 2001/05/19 09:01:10 petere Exp $
-->
<chapter id="xfunc">
......@@ -29,14 +29,12 @@ $Header: /cvsroot/pgsql/doc/src/sgml/xfunc.sgml,v 1.31 2001/02/15 19:03:35 tgl E
<listitem>
<para>
procedural language
functions (functions written in, for example, PLTCL or PLSQL)
functions (functions written in, for example, PL/Tcl or PL/pgSQL)
</para>
</listitem>
<listitem>
<para>
programming
language functions (functions written in a compiled
programming language such as <acronym>C</acronym>)
C language functions
</para>
</listitem>
</itemizedlist>
......@@ -371,16 +369,36 @@ SELECT clean_EMP();
</sect1>
<sect1 id="xfunc-c">
<title>Compiled (C) Language Functions</title>
<title>C Language Functions</title>
<para>
Functions written in C can be compiled into dynamically loadable
objects (also called shared libraries), and used to implement user-defined
SQL functions. The first time a user-defined function in a particular
User-defined functions can be written in C (or a language that can
be made compatible with C, such as C++). Such functions are
compiled into dynamically loadable objects (also called shared
libraries) and are loaded by the server on demand. This
distinguishes them from internal functions.
</para>
<para>
Two different calling conventions are currently used for C functions.
The newer "version 1" calling convention is indicated by writing
a <literal>PG_FUNCTION_INFO_V1()</literal> macro call for the function,
as illustrated below. Lack of such a macro indicates an old-style
("version 0") function. The language name specified in CREATE FUNCTION
is 'C' in either case. Old-style functions are now deprecated
because of portability problems and lack of functionality, but they
are still supported for compatibility reasons.
</para>
<sect2 id="xfunc-c-dynload">
<title>Dynamic Loading</title>
<para>
The first time a user-defined function in a particular
loadable object file is called in a backend session,
the dynamic loader loads that object file into memory so that the
function can be called. The <command>CREATE FUNCTION</command>
for a user-defined function must therefore specify two pieces of
for a 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
......@@ -397,35 +415,82 @@ SELECT clean_EMP();
</para>
<para>
The string that specifies the object file (the first string in the AS
clause) should be the <emphasis>full path</emphasis> of the object
code file for the function, bracketed by single quote marks. If a
link symbol is given in the AS clause, the link symbol should also be
bracketed by single quote marks, and should be exactly the
same as the name of the function in the C source code. On Unix systems
the command <command>nm</command> will print all of the link
symbols in a dynamically loadable object.
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 file name, 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 PostgreSQL library directory,
which is determined at build time.
</para>
</listitem>
<listitem>
<para>
If the name does not contain a directory part, the file is
searched the path specified by the configuration variable
<varname>dynamic_library_path</varname>.
</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>
<note>
<para>
<productname>Postgres</productname> will not compile a function
automatically; it must be compiled before it is used in a CREATE
FUNCTION command. See below for additional information.
</para>
</note>
<note>
<para>
The user id the <application>PostgreSQL</application> 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 <quote>postgres</quote> user is a
common mistake.
</para>
</note>
<para>
In any case, the file name that is specified 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>
<para>
Two different calling conventions are currently used for C functions.
The newer "version 1" calling convention is indicated by writing
a <literal>PG_FUNCTION_INFO_V1()</literal> macro call for the function,
as illustrated below. Lack of such a macro indicates an old-style
("version 0") function. The language name specified in CREATE FUNCTION
is 'C' in either case. Old-style functions are now deprecated
because of portability problems and lack of functionality, but they
are still supported for compatibility reasons.
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.
</para>
<note>
<para>
<application>PostgreSQL</application> will not compile a function
automatically; it must be compiled before it is used in a CREATE
FUNCTION command. See <xref linkend="dfunc"> for additional information.
</para>
</note>
</sect2>
<sect2>
<title>Base Types in C-Language Functions</title>
......
doc/src/sgml/xplang.sgml
View file @ cb8b40e6
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/xplang.sgml,v 1.12 2001/02/09 02:20:52 tgl Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/xplang.sgml,v 1.13 2001/05/19 09:01:10 petere Exp $
-->
<chapter id="xplang">
......@@ -130,13 +130,13 @@ CREATE <optional>TRUSTED</optional> <optional>PROCEDURAL</optional> LANGUAGE '<r
<programlisting>
CREATE FUNCTION plpgsql_call_handler () RETURNS OPAQUE AS
'/usr/local/pgsql/lib/plpgsql.so' LANGUAGE 'C';
'$libdir/plpgsql' LANGUAGE 'C';
</programlisting>
</para>
</step>
<step performance="Required">
<para>
<para>
The command
<programlisting>
CREATE TRUSTED PROCEDURAL LANGUAGE 'plpgsql'
......
src/backend/utils/fmgr/dfmgr.c
View file @ cb8b40e6
......@@ -8,7 +8,7 @@
*
*
* IDENTIFICATION
* $Header: /cvsroot/pgsql/src/backend/utils/fmgr/dfmgr.c,v 1.49 2001/05/17 17:44:18 petere Exp $
* $Header: /cvsroot/pgsql/src/backend/utils/fmgr/dfmgr.c,v 1.50 2001/05/19 09:01:10 petere Exp $
*
*-------------------------------------------------------------------------
*/
......@@ -51,7 +51,7 @@ char * Dynamic_library_path;
static bool file_exists(const char *name);
static char * find_in_dynamic_libpath(const char * basename);
static char * expand_dynamic_library_name(const char *name);
static char * substitute_libpath_macro(const char * name);
/*
* Load the specified dynamic-link library file, and look for a function
......@@ -210,7 +210,7 @@ file_exists(const char *name)
AssertArg(name != NULL);
if (stat(name, &st) == 0)
return true;
return S_ISDIR(st.st_mode) ? false : true;
else if (!(errno == ENOENT || errno == ENOTDIR || errno == EACCES))
elog(ERROR, "stat failed on %s: %s", name, strerror(errno));
......@@ -234,15 +234,14 @@ file_exists(const char *name)
* the name. Else (no slash) try to expand using search path (see
* find_in_dynamic_libpath below); if that works, return the fully
* expanded file name. If the previous failed, append DLSUFFIX and
* try again. If all fails, return NULL. The return value is
* palloc'ed.
* try again. If all fails, return NULL.
*/
static char *
expand_dynamic_library_name(const char *name)
{
bool have_slash;
char * new;
size_t len;
char * full;
AssertArg(name);
......@@ -250,28 +249,23 @@ expand_dynamic_library_name(const char *name)
if (!have_slash)
{
char * full;
full = find_in_dynamic_libpath(name);
if (full)
return full;
}
else
{
if (file_exists(name))
return pstrdup(name);
full = substitute_libpath_macro(name);
if (file_exists(full))
return full;
}
len = strlen(name);
new = palloc(len + strlen(DLSUFFIX) + 1);
new = palloc(strlen(name)+ strlen(DLSUFFIX) + 1);
strcpy(new, name);
strcpy(new + len, DLSUFFIX);
strcat(new, DLSUFFIX);
if (!have_slash)
{
char * full;
full = find_in_dynamic_libpath(new);
pfree(new);
if (full)
......@@ -279,8 +273,9 @@ expand_dynamic_library_name(const char *name)
}
else
{
if (file_exists(new))
return new;
full = substitute_libpath_macro(new);
if (file_exists(full))
return full;
}
return NULL;
......@@ -288,6 +283,40 @@ expand_dynamic_library_name(const char *name)
static char *
substitute_libpath_macro(const char * name)
{
size_t macroname_len;
char * replacement = NULL;
AssertArg(name != NULL);
if (strlen(name) == 0 || name[0] != '$')
return pstrdup(name);
macroname_len = strcspn(name + 1, "/") + 1;
if (strncmp(name, "$libdir", macroname_len)==0)
replacement = LIBDIR;
else
elog(ERROR, "invalid macro name in dynamic library path");
if (name[macroname_len] == '\0')
return replacement;
else
{
char * new;
new = palloc(strlen(replacement) + (strlen(name) - macroname_len) + 1);
strcpy(new, replacement);
strcat(new, name + macroname_len);
return new;
}
}
/*
* Search for a file called 'basename' in the colon-separated search
* path 'path'. If the file is found, the full file name is returned
......@@ -312,55 +341,26 @@ find_in_dynamic_libpath(const char * basename)
baselen = strlen(basename);
do {
char * piece;
const char * mangled;
len = strcspn(p, ":");
if (len == 0)
elog(ERROR, "zero length dynamic_library_path component");
/* substitute special value */
if (p[0] == '$')
{
size_t varname_len = strcspn(p + 1, "/") + 1;
const char * replacement = NULL;
size_t repl_len;
piece = palloc(len + 1);
strncpy(piece, p, len);
piece[len] = '\0';
if (strncmp(p, "$libdir", varname_len)==0)
replacement = LIBDIR;
else
elog(ERROR, "invalid dynamic_library_path specification");
mangled = substitute_libpath_macro(piece);
repl_len = strlen(replacement);
/* only absolute paths */
if (mangled[0] != '/')
elog(ERROR, "dynamic_library_path component is not absolute");
if (p[varname_len] == '\0')
{
full = palloc(repl_len + 1 + baselen + 1);
snprintf(full, repl_len + 1 + baselen + 1,
"%s/%s", replacement, basename);
}
else
{
full = palloc(repl_len + (len - varname_len) + 1 + baselen + 1);
strcpy(full, replacement);
strncat(full, p + varname_len, len - varname_len);
full[repl_len + (len - varname_len)] = '\0';
strcat(full, "/");
strcat(full, basename);
}
}
/* regular case */
else
{
/* only absolute paths */
if (p[0] != '/')
elog(ERROR, "dynamic_library_path component is not absolute");
full = palloc(len + 1 + baselen + 1);
strncpy(full, p, len);
full[len] = '/';
strcpy(full + len + 1, basename);
}
full = palloc(strlen(mangled) + 1 + baselen + 1);
sprintf(full, "%s/%s", mangled, basename);
if (DebugLvl > 1)
elog(DEBUG, "find_in_dynamic_libpath: trying %s", full);
......@@ -368,6 +368,7 @@ find_in_dynamic_libpath(const char * basename)
if (file_exists(full))
return full;
pfree(piece);
pfree(full);
if (p[len] == '\0')
break;
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment