database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-07-28 23:42:10 +03:00
Code Activity

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

Browse Source 
FUNCTION command.  Guard against trying to load a directory.  Update
documentation some.
This commit is contained in:
Peter Eisentraut
2001-05-19 09:01:10 +00:00
parent a008109d05
commit cb8b40e6d5
7 changed files with 394 additions and 529 deletions
Download Patch File Download Diff File Expand all files Collapse all files

21
doc/src/sgml/dfunc.sgml
View File

@ -1,5 +1,5 @@
<!--
$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>
<!--

449
doc/src/sgml/ref/create_function.sgml
View File

@ -1,187 +1,151 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.22 2001/04/28 13:59:07 momjian Exp $
Postgres documentation
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.23 2001/05/19 09:01:10 petere Exp $
-->
<refentry id="SQL-CREATEFUNCTION">
<refmeta>
<refentrytitle id="sql-createfunction-title">
CREATE FUNCTION
</refentrytitle>
<refentrytitle>CREATE FUNCTION</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta>
<refnamediv>
<refname>
CREATE FUNCTION
</refname>
<refpurpose>
Defines a new function
</refpurpose>
<refname>CREATE FUNCTION</refname>
<refpurpose>Defines a new function</refpurpose>
</refnamediv>
<refsynopsisdiv>
<refsynopsisdivinfo>
<date>2000-03-25</date>
</refsynopsisdivinfo>
<synopsis>
CREATE FUNCTION <replaceable class="parameter">name</replaceable> ( [ <replaceable class="parameter">ftype</replaceable> [, ...] ] )
RETURNS <replaceable class="parameter">rtype</replaceable>
AS <replaceable class="parameter">definition</replaceable>
<synopsis>
CREATE FUNCTION <replaceable class="parameter">name</replaceable> ( [ <replaceable class="parameter">argtype</replaceable> [, ...] ] )
RETURNS <replaceable class="parameter">rettype</replaceable>
AS '<replaceable class="parameter">definition</replaceable>'
LANGUAGE '<replaceable class="parameter">langname</replaceable>'
[ WITH ( <replaceable class="parameter">attribute</replaceable> [, ...] ) ]
CREATE FUNCTION <replaceable class="parameter">name</replaceable> ( [ <replaceable class="parameter">ftype</replaceable> [, ...] ] )
RETURNS <replaceable class="parameter">rtype</replaceable>
AS <replaceable class="parameter">obj_file</replaceable> , <replaceable class="parameter">link_symbol</replaceable>
LANGUAGE 'langname'
CREATE FUNCTION <replaceable class="parameter">name</replaceable> ( [ <replaceable class="parameter">argtype</replaceable> [, ...] ] )
RETURNS <replaceable class="parameter">rettype</replaceable>
AS '<replaceable class="parameter">obj_file</replaceable>', '<replaceable class="parameter">link_symbol</replaceable>'
LANGUAGE '<replaceable class="parameter">langname</replaceable>'
[ WITH ( <replaceable class="parameter">attribute</replaceable> [, ...] ) ]
</synopsis>
<refsect2 id="R2-SQL-CREATEFUNCTION-1">
<refsect2info>
<date>2000-03-25</date>
</refsect2info>
<title>
Inputs
</title>
<para>
<variablelist>
<varlistentry>
<term><replaceable class="parameter">name</replaceable></term>
<listitem>
<para>
The name of a function to create.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">ftype</replaceable></term>
<listitem>
<para>
The data type(s) of the function's arguments, if any.
The input types may be base or complex types, or
<firstterm>opaque</firstterm>.
<literal>Opaque</literal> indicates that the function
accepts arguments of a non-SQL type such as <type>char *</type>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">rtype</replaceable></term>
<listitem>
<para>
The return data type.
The output type may be specified as a base type, complex type,
<option>setof type</option>,
or <option>opaque</option>.
The <option>setof</option>
modifier indicates that the function will return a set of items,
rather than a single item.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">attribute</replaceable></term>
<listitem>
<para>
An optional piece of information about the function, used for
optimization. See below for details.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">definition</replaceable></term>
<listitem>
<para>
A string defining the function; the meaning depends on the language.
It may be an internal function name, the path to an object file,
an SQL query, or text in a procedural language.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">obj_file</replaceable> , <replaceable class="parameter">link_symbol</replaceable></term>
<listitem>
<para>
This form of the <command>AS</command> clause is used for
dynamically linked, C language functions when the function name in
the C language source code is not the same as the name of the SQL
function. The string <replaceable
class="parameter">obj_file</replaceable> is the name of the file
containing the dynamically loadable object, and <replaceable
class="parameter">link_symbol</replaceable> is the object's link
symbol, that is the name of the function in the C
language source code.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">langname</replaceable></term>
<listitem>
<para>
May be '<literal>sql</literal>',
'<literal>C</literal>', '<literal>internal</literal>',
or '<replaceable class="parameter">plname</replaceable>',
where '<replaceable class="parameter">plname</replaceable>'
is the name of a created procedural language. See
<xref linkend="sql-createlanguage" endterm="sql-createlanguage-title">
for details.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<refsect2 id="R2-SQL-CREATEFUNCTION-2">
<refsect2info>
<date>2000-03-25</date>
</refsect2info>
<title>
Outputs
</title>
<para>
<variablelist>
<varlistentry>
<term><computeroutput>
CREATE
</computeroutput></term>
<listitem>
<para>
This is returned if the command completes successfully.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</synopsis>
</refsynopsisdiv>
<refsect1 id="sql-createfunction-description">
<title>Description</title>
<refsect1 id="R1-SQL-CREATEFUNCTION-1">
<refsect1info>
<date>2000-03-25</date>
</refsect1info>
<title>
Description
</title>
<para>
<command>CREATE FUNCTION</command> allows a
<productname>Postgres</productname> user
to register a function
with the database. Subsequently, this user is considered the
owner of the function.
<command>CREATE FUNCTION</command> defines a new function.
<variablelist>
<title>Parameters</title>
<varlistentry>
<term><replaceable class="parameter">name</replaceable></term>
<listitem>
<para>
The name of a function to create. The name need not be unique,
because functions may be overloaded, but functions with the
same name must have different argument types.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">argtype</replaceable></term>
<listitem>
<para>
The data type(s) of the function's arguments, if any. The
input types may be base or complex types, or
<literal>opaque</literal>. <literal>Opaque</literal> indicates
that the function accepts arguments of a non-SQL type such as
<type>char *</type>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">rettype</replaceable></term>
<listitem>
<para>
The return data type. The output type may be specified as a
base type, complex type, <literal>setof</literal> type, or
<literal>opaque</literal>. The <literal>setof</literal>
modifier indicates that the function will return a set of
items, rather than a single item. Functions with a declared
return type of <literal>opaque</literal> do not return a value.
These cannot be called directly; trigger functions make use of
this feature.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">definition</replaceable></term>
<listitem>
<para>
A string defining the function; the meaning depends on the
language. It may be an internal function name, the path to an
object file, an SQL query, or text in a procedural language.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">obj_file</replaceable>, <replaceable class="parameter">link_symbol</replaceable></term>
<listitem>
<para>
This form of the <literal>AS</literal> clause is used for
dynamically linked C language functions when the function name
in the C language source code is not the same as the name of
the SQL function. The string <replaceable
class="parameter">obj_file</replaceable> is the name of the
file containing the dynamically loadable object, and
<replaceable class="parameter">link_symbol</replaceable> is the
object's link symbol, that is, the name of the function in the C
language source code.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">langname</replaceable></term>
<listitem>
<para>
May be '<literal>sql</literal>', '<literal>C</literal>',
'<literal>internal</literal>', or '<replaceable
class="parameter">plname</replaceable>', where '<replaceable
class="parameter">plname</replaceable>' is the name of a
created procedural language. See
<xref linkend="sql-createlanguage">
for details.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">attribute</replaceable></term>
<listitem>
<para>
An optional piece of information about the function, used for
optimization. See below for details.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<refsect2 id="R2-SQL-CREATEFUNCTION-3">
<refsect2info>
<date>2000-08-24</date>
</refsect2info>
<title>
Function Attributes
</title>
<para>
The user that creates the function becomes the owner of the function.
</para>
<para>
The following items may appear in the WITH clause:
<para>
The following attributes may appear in the WITH clause:
<variablelist>
<varlistentry>
@ -214,17 +178,12 @@ CREATE
</listitem>
</varlistentry>
</variablelist>
</para>
</para>
</refsect2>
</refsect1>
<refsect2 id="R2-SQL-CREATEFUNCTION-4">
<refsect2info>
<date>2000-03-25</date>
</refsect2info>
<title>
Notes
</title>
<refsect1 id="sql-createfunction-notes">
<title>Notes</title>
<para>
Refer to the chapter in the
@ -240,7 +199,7 @@ CREATE
</para>
<para>
The full <acronym>SQL92</acronym> type syntax is allowed for
The full <acronym>SQL</acronym> type syntax is allowed for
input arguments and return value. However, some details of the
type specification (e.g., the precision field for
<type>numeric</type> types) are the responsibility of the
@ -250,7 +209,7 @@ CREATE
</para>
<para>
<productname>Postgres</productname> allows function "overloading";
<productname>Postgres</productname> allows function <firstterm>overloading</firstterm>;
that is, the same name can be used for several different functions
so long as they have distinct argument types. This facility must
be used with caution for internal and C-language functions, however.
@ -275,38 +234,45 @@ CREATE
C-language implementation of each overloaded SQL function.
</para>
</refsect2>
<para>
When repeated <command>CREATE FUNCTION</command> calls refer to
the same object file, the file is only loaded once. To unload and
reload the file (perhaps during development), use the <xref
linkend="sql-load"> command.
</para>
</refsect1>
<refsect1 id="R1-SQL-CREATEFUNCTION-2">
<title>
Usage
</title>
<refsect1 id="sql-createfunction-examples">
<title>Examples</title>
<para>
To create a simple SQL function:
<programlisting>
CREATE FUNCTION one() RETURNS int4
AS 'SELECT 1 AS RESULT'
<programlisting>
CREATE FUNCTION one() RETURNS integer
AS 'SELECT 1 AS RESULT;'
LANGUAGE 'sql';
SELECT one() AS answer;
<computeroutput>
SELECT one() AS answer;
<computeroutput>
answer
--------
1
</computeroutput>
</programlisting>
</computeroutput>
</programlisting>
</para>
<para>
This example creates a C function by calling a routine from a user-created
shared library. This particular routine calculates a check
digit and returns TRUE if the check digit in the function parameters
is correct. It is intended for use in a CHECK contraint.
</para>
<programlisting>
CREATE FUNCTION ean_checkdigit(bpchar, bpchar) RETURNS boolean
The next example creates a C function by calling a routine from a
user-created shared library. This particular routine calculates a
check digit and returns TRUE if the check digit in the function
parameters is correct. It is intended for use in a CHECK
constraint.
<programlisting>
CREATE FUNCTION ean_checkdigit(char, char) RETURNS boolean
AS '/usr1/proj/bray/sql/funcs.so' LANGUAGE 'c';
CREATE TABLE product (
@ -316,28 +282,28 @@ CREATE TABLE product (
eancode char(6) CHECK (eancode ~ '[0-9]{6}'),
CONSTRAINT ean CHECK (ean_checkdigit(eanprefix, eancode))
);
</programlisting>
</programlisting>
</para>
<para>
This example creates a function that does type conversion between the
user-defined type complex, and the internal type point. The
function is implemented by a dynamically loaded object that was
compiled from C source. For <productname>Postgres</productname> to
find a type conversion function automatically, the sql function has
compiled from C source. For <productname>PostgreSQL</productname> to
find a type conversion function automatically, the SQL function has
to have the same name as the return type, and so overloading is
unavoidable. The function name is overloaded by using the second
form of the <command>AS</command> clause in the SQL definition:
</para>
<programlisting>
<programlisting>
CREATE FUNCTION point(complex) RETURNS point
AS '/home/bernie/pgsql/lib/complex.so', 'complex_to_point'
LANGUAGE 'c';
</programlisting>
<para>
The C declaration of the function is:
</para>
<programlisting>
</programlisting>
The C declaration of the function could be:
<programlisting>
Point * complex_to_point (Complex *z)
{
Point *p;
@ -348,58 +314,33 @@ Point * complex_to_point (Complex *z)
return p;
}
</programlisting>
</programlisting>
</para>
</refsect1>
<refsect1 id="R1-SQL-CREATEFUNCTION-4">
<title>
Compatibility
</title>
<refsect1 id="sql-createfunction-compat">
<title>Compatibility</title>
<refsect2 id="R2-SQL-CREATEFUNCTION-5">
<refsect2info>
<date>2000-03-25</date>
</refsect2info>
<title>
SQL92
</title>
<para>
<command>CREATE FUNCTION</command> is
a <productname>Postgres</productname> language extension.
</para>
</refsect2>
<refsect2 id="R2-SQL-CREATEFUNCTION-6">
<refsect2info>
<date>2000-03-25</date>
</refsect2info>
<title>
SQL/PSM
</title>
<para>
<note>
<para>
PSM stands for Persistent Stored Modules. It is a procedural
language. SQL/PSM is a standard to enable function extensibility.
</para>
</note>
SQL/PSM <command>CREATE FUNCTION</command> has the following syntax:
<synopsis>
CREATE FUNCTION <replaceable class="parameter">name</replaceable>
( [ [ IN | OUT | INOUT ] <replaceable class="parameter">type</replaceable> [, ...] ] )
RETURNS <replaceable class="parameter">rtype</replaceable>
LANGUAGE '<replaceable class="parameter">langname</replaceable>'
ESPECIFIC <replaceable class="parameter">routine</replaceable>
<replaceable class="parameter">SQL-statement</replaceable>
</synopsis>
</para>
</refsect2>
<para>
A <command>CREATE FUNCTION</command> command is defined in SQL99.
The <application>PostgreSQL</application> version is similar but
not compatible. The attributes are not portable, neither are the
different available languages.
</para>
</refsect1>
<refsect1 id="sql-createfunction-seealso">
<title>See Also</title>
<para>
<xref linkend="sql-dropfunction">,
<xref linkend="sql-load">,
<citetitle>PostgreSQL Programmer's Guide</citetitle>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file

4
doc/src/sgml/ref/drop_function.sgml
View File

@ -1,5 +1,5 @@
<!--
$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>

193
doc/src/sgml/ref/load.sgml
View File

@ -1,183 +1,54 @@
<!--
$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.
</para>
<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.
</para>
<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 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>
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="R1-SQL-LOAD-3">
<title>
Compatibility
</title>
<refsect1 id="sql-load-compat">
<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>
<para>
<command>LOAD</command> is a <application>PostgreSQL</application>
extension.
</para>
</refsect1>
<refsect1>
<title>See Also</title>
<para>
<xref linkend="sql-createfunction">,
<citetitle>PostgreSQL Programmer's Guide</citetitle>
</para>
</refsect1>
</refentry>

131
doc/src/sgml/xfunc.sgml
View File

@ -1,5 +1,5 @@
<!--
$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:
<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>
<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>
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>

6
doc/src/sgml/xplang.sgml
View File

@ -1,5 +1,5 @@
<!--
$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'