diff options
Diffstat (limited to 'doc/src')
| -rw-r--r-- | doc/src/sgml/ref/create_function.sgml | 90 | ||||
| -rw-r--r-- | doc/src/sgml/xfunc.sgml | 61 |
2 files changed, 111 insertions, 40 deletions
diff --git a/doc/src/sgml/ref/create_function.sgml b/doc/src/sgml/ref/create_function.sgml index 84f4f5c958f..b22b9e4088f 100644 --- a/doc/src/sgml/ref/create_function.sgml +++ b/doc/src/sgml/ref/create_function.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.9 1999/07/22 15:09:07 thomas Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.10 1999/09/28 04:34:39 momjian Exp $ Postgres documentation --> @@ -25,8 +25,14 @@ Postgres documentation <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> + AS <replaceable class="parameter">definition</replaceable> LANGUAGE '<replaceable class="parameter">langname</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 'c' </synopsis> <refsect2 id="R2-SQL-CREATEFUNCTION-1"> @@ -84,6 +90,22 @@ CREATE FUNCTION <replaceable class="parameter">name</replaceable> ( [ <replaceab </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 which is the same as the name of the function in the C + language source code. + </para> + </listitem> + </varlistentry> + <varlistentry> <term><replaceable class="parameter">langname</replaceable></term> <listitem> <para> @@ -165,10 +187,10 @@ CREATE <para> <productname>Postgres</productname> allows function "overloading"; 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 <literal>internal</literal> - and C-language functions, however. - </para> + so long as they have distinct argument types. This facility must + be used with caution for <literal>internal</literal> and + C-language functions, however. + </para> <para> Two <literal>internal</literal> @@ -181,18 +203,15 @@ CREATE </para> <para> - For dynamically-loaded C functions, the SQL name of the function must - be the same as the C function name, because the AS clause is used to - give the path name of the object file containing the C code. In this - situation it is best not to try to overload SQL function names. It - might work to load a C function that has the same C name as an internal - function or another dynamically-loaded function --- or it might not. - On some platforms the dynamic loader may botch the load in interesting - ways if there is a conflict of C function names. So, even if it works - for you today, you might regret overloading names later when you try - to run the code somewhere else. + When overloading SQL functions with C-language functions, give + each C-language instance of the function a distinct name, and use + the alternative form of the <command>AS</command> clause in the + <command>CREATE FUNCTION</command> syntax to ensure that + overloaded SQL functions names are resolved to the correct + dynamically linked objects. </para> + <para> A C function cannot return a set of values. </para> @@ -227,7 +246,6 @@ SELECT one() AS answer; is correct. It is intended for use in a CHECK contraint. </para> <programlisting> - <userinput> CREATE FUNCTION ean_checkdigit(bpchar, bpchar) RETURNS bool AS '/usr1/proj/bray/sql/funcs.so' LANGUAGE 'c'; @@ -238,8 +256,41 @@ CREATE TABLE product ( eancode char(6) CHECK (eancode ~ '[0-9]{6}'), CONSTRAINT ean CHECK (ean_checkdigit(eanprefix, eancode)) ); - </userinput> </programlisting> + + + <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 + to have the same name as the return type, and 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> +CREATE FUNCTION point(complex) RETURNS point + AS '/home/bernie/pgsql/lib/complex.so', 'complex_to_point' + LANGUAGE 'c'; + </programlisting> + <para> + The C decalaration of the function is: + </para> + <programlisting> +Point * complex_to_point (Complex *z) +{ + Point *p; + + p = (Point *) palloc(sizeof(Point)); + p->x = z->x; + p->y = z->y; + + return p; +} + </programlisting> + + </refsect1> <refsect1 id="R1-SQL-CREATEFUNCTION-4"> @@ -283,8 +334,7 @@ CREATE TABLE product ( SQL/PSM <command>CREATE FUNCTION</command> has the following syntax: <synopsis> CREATE FUNCTION <replaceable class="parameter">name</replaceable> - ( [ [ IN | OUT | INOUT ] <replaceable class="parameter">eter</replaceable>eable>eable> <replaceable - class="parameter">type</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> diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml index 036d029d818..879f6f66672 100644 --- a/doc/src/sgml/xfunc.sgml +++ b/doc/src/sgml/xfunc.sgml @@ -357,25 +357,43 @@ WARN::function declared to return type EMP does not retrieve (EMP.*) <title>Compiled (C) Language Functions</title> <para> - Functions written in C can be defined to Postgres, which will dynamically - load them into its address space. The AS - clause gives the full path name of the object file that contains the - function. This file is loaded either using - load(l) - or automatically the first time the function is necessary for - execution. Repeated execution of a function will cause negligible - additional overhead, as the function will remain in a main memory - cache. + Functions written in C can be compiled into dynamically loadable + objects, and used to implement user-defined SQL functions. The + first time the user defined function is called inside the backend, + the dynamic loader loads the function's object code into memory, + and links the function with the running + <productname>Postgres</productname> executable. The SQL syntax + for the <xref linkend="sql-createfunction-title" + endterm="sql-createfunction-title"> command links the SQL function + to the C source function in one of two ways. If the SQL function + has the same name as the C source function the first form of the + statement is used. The string argument in the AS clause is the + full pathname of the file that contains the dynamically loadable + compiled object. If the name of C function is different from the + name of the SQL function, then the second form is used. In this + form the AS clause takes two string arguments, the first is the + full pathname of the dynamically loadable object file, and the + second is the link symbol that the dynamic loader should search + for. This link symbol is just the function name in the C source + code. + + After it is used for the first time, a dynamically loaded, user + function is retained in memory, and future calls to the function + only incur the small overhead of a symbol table lookup. </para> <para> - The string which specifies the object file (the string in the AS clause) - should be the <emphasis>full path</emphasis> - of the object code file for the function, bracketed by quotation - marks. (<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.) + The string which specifies the object file (the string in the AS + clause) should be the <emphasis>full path</emphasis> of the object + code file for the function, bracketed by quotation marks. If a + link symbol is used in the AS clause, the link symbol should also be + bracketed by single quotation marks, and should be exactly the + same as the name of 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. + (<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> <sect2> @@ -960,10 +978,13 @@ memmove(destination->data, buffer, 40); <title>Name Space Conflicts</title> <para> - As of <productname>Postgres</productname> v6.5, - <command>CREATE FUNCTION</command> can decouple a C language - function name from the name of the entry point. This is now the - preferred technique to accomplish function overloading. + As of <productname>Postgres</productname> v6.6, the alternative + form of the AS clause for the SQL <command>CREATE + FUNCTION</command> command described in <xref + linkend="sql-createfunction-title" endterm="sql-createfunction-title"> + decouples the SQL function name from the function name in the C + source code. This is now the preferred technique to accomplish + function overloading. </para> <sect3> |