1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
|
<!-- manual page source format generated by PolyglotMan v3.0.4, -->
<!-- available via anonymous ftp from ftp.cs.berkeley.edu:/ucb/people/phelps/tcltk/rman.tar.Z -->
<HTML>
<HEAD>
<TITLE>"CREATE(FUNCTION") manual page</TITLE>
</HEAD>
<BODY>
<A HREF="sql.html">SQL Reference Contents</A>
<H2><A NAME="sect0" HREF="#toc0">NAME </A></H2>
create function - define a new function
<H2><A NAME="sect1" HREF="#toc1">SYNOPSIS </A></H2>
<B>create function
</B> function_name <BR>
<tt> </tt><tt> </tt><B>( </B>[type1 {, type-n}]<B>) </B> <BR>
<tt> </tt><tt> </tt><B>returns </B> type-r <BR>
<tt> </tt><tt> </tt><B>as </B> {'/full/path/to/objectfile'
| 'sql-queries'} <BR>
<tt> </tt><tt> </tt><B>language </B> {'c' 'sql' 'internal' 'plname'} <BR>
<H2><A NAME="sect2" HREF="#toc2">DESCRIPTION </A></H2>
With this
command, a Postgres user can register a function with Postgres. Subsequently,
this user is treated as the owner of the function. <P>
When defining a function
with arguments, the input data types, <I>type-1</I>, <I>type-2</I>, ..., <I>type-n</I>, and the return
data type, <I>type-r</I> must be specified, along with the language, which may
be <I>`c'</I> or <I>`sql'</I>. or <I>`internal'</I>. or <I>`plname'</I>. (The <I>plname</I> is the language name of
a created procedural language. See create <A HREF="language.l.html">language(l)</A>
for details.) (The
<I>arg is</I> clause may be left out if the function has no arguments, or alternatively
the argument list may be left empty.) The input types may be base or complex
types, or <I>opaque</I>. <I>Opaque</I> indicates that the function accepts arguments
of an invalid type such as (char *). The output type may be specified as
a base type, complex type, <I>setof <type></I>, or <I>opaque</I>. The <I>setof</I> modifier
indicates that the function will return a set of items, rather than a
single item. The <I>as</I> clause of the command is treated differently for
C and SQL functions, as explained below.
<H2><A NAME="sect3" HREF="#toc3">C FUNCTIONS </A></H2>
Functions written
in C can be defined to Postgres, which will dynamically load them into
its address space. The loading happens either using <I><A HREF="load.l.html">load</I>(l)</A>
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. <P>
Internal functions are functions written
in C which have been statically linked into the postgres backend process.
The <B>as</B> clause must still be specified when defining an internal function
but the contents are ignored.
<H2><A NAME="sect4" HREF="#toc4">Writing C Functions </A></H2>
The body of a C function
following <B>as</B> should be the <B>FULL PATH</B> of the object code (.o file) for
the function, bracketed by quotation marks. (Postgres will not compile
a function automatically - it must be compiled before it is used in a <B>define
function</B> command.) <P>
C functions with base type arguments can be written
in a straightforward fashion. The C equivalents of built-in Postgres types
are accessible in a C file if .../src/backend/utils/builtins.h <BR>
is included
as a header file. This can be achieved by having #include <utils/builtins.h>
<BR>
at the top of the C source file and by compiling all C files with the
following include options: -I.../src/backend <BR>
-I.../src/backend/port/<portname>
<BR>
-I.../src/backend/obj <BR>
before any `.c' programs in the <I>cc</I> command line, e.g.:
cc -I.../src/backend \ <BR>
-I.../src/backend/port/<portname> \ <BR>
-I.../src/backend/obj
\ <BR>
-c progname.c <BR>
where `...' is the path to the installed Postgres source
tree and `<portname>' is the name of the port for which the source tree has
been built. <P>
The convention for passing arguments to and from the user's
C functions is to use pass-by-value for data types that are 32 bits (4 bytes)
or smaller, and pass-by-reference for data types that require more than
32 bits. <P>
<HR><P>
<A NAME="toc"><B>Table of Contents</B></A><P>
<UL>
<LI><A NAME="toc0" HREF="#sect0">NAME</A></LI>
<LI><A NAME="toc1" HREF="#sect1">SYNOPSIS</A></LI>
<LI><A NAME="toc2" HREF="#sect2">DESCRIPTION</A></LI>
<LI><A NAME="toc3" HREF="#sect3">C FUNCTIONS</A></LI>
<LI><A NAME="toc4" HREF="#sect4">Writing C Functions</A></LI>
</UL>
</BODY></HTML>
|
