SQL Reference Contents

NAME

create function - define a new function

SYNOPSIS

create function function_name
( [type1 {, type-n}])
returns type-r
as {'/full/path/to/objectfile' | 'sql-queries'}
language {'c' 'sql' 'internal' 'plname'}

DESCRIPTION

With this command, a Postgres user can register a function with Postgres. Subsequently, this user is treated as the owner of the function.

When defining a function with arguments, the input data types, type-1, type-2, ..., type-n, and the return data type, type-r must be specified, along with the language, which may be `c' or `sql'. or `internal'. or `plname'. (The plname is the language name of a created procedural language. See create language(l) for details.) (The arg is 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 opaque. Opaque 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, setof <type>, or opaque. The setof modifier indicates that the function will return a set of items, rather than a single item. The as clause of the command is treated differently for C and SQL functions, as explained below.

C FUNCTIONS

Functions written in C can be defined to Postgres, which will dynamically load them into its address space. The loading happens 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.

Internal functions are functions written in C which have been statically linked into the postgres backend process. The as clause must still be specified when defining an internal function but the contents are ignored.

Writing C Functions

The body of a C function following as should be the FULL PATH 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 define function command.)

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
is included as a header file. This can be achieved by having #include <utils/builtins.h>
at the top of the C source file and by compiling all C files with the following include options: -I.../src/backend
-I.../src/backend/port/<portname>
-I.../src/backend/obj
before any `.c' programs in the cc command line, e.g.: cc -I.../src/backend \
-I.../src/backend/port/<portname> \
-I.../src/backend/obj \
-c progname.c
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.

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.


Table of Contents