opensourcemirror
/
postgresql
mirror of git://git.postgresql.org/git/postgresql.git
1
0
Fork 0
Code Issues Releases Wiki Activity

Doco updates for change to handling of INTERNAL function 

entries (prosrc is now name of C-level function).
This commit is contained in:
Tom Lane 1999-05-20 02:44:53 +00:00
parent 77d3355900
commit f9e497db7f
2 changed files with 51 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
src/man/catalogs.3
View File

@ -1,6 +1,6 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/catalogs.3,v 1.5 1998/03/25 01:54:49 momjian Exp $
.\" $Header: /cvsroot/pgsql/src/man/Attic/catalogs.3,v 1.6 1999/05/20 02:44:53 tgl Exp $
.TH "SYSTEM CATALOGS" INTRO 03/13/94 PostgreSQL PostgreSQL
.SH "Section 7 - System Catalogs"
.de LS
@ -316,8 +316,12 @@ pg_proc
size) */
int4 prooutin_ratio /* size of the function's output as a
percentage of the size of the input */
text prosrc /* function definition (postquel only) */
bytea probin /* path to object file (C only) */
text prosrc /* function definition:
INTERNAL function: actual C name of function
C function: currently, this field is unused
SQL function: text of query(s)
PL function: text in procedural language */
bytea probin /* path to object file (C functions only) */
.fi
.nf M
pg_language

68
src/man/create_function.l
View File

@ -1,6 +1,6 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/create_function.l,v 1.10 1998/06/24 13:21:24 momjian Exp $
.\" $Header: /cvsroot/pgsql/src/man/Attic/create_function.l,v 1.11 1999/05/20 02:44:53 tgl Exp $
.TH "CREATE FUNCTION" SQL 11/05/95 PostgreSQL PostgreSQL
.SH "NAME"
create function - define a new function
@ -9,8 +9,9 @@ create function - define a new function
\fBcreate function\fP function_name
\fB(\fP[type1 {, type-n}]\fB)\fP
\fBreturns\fP type-r
\fBas\fP {'/full/path/to/objectfile' | 'sql-queries'}
\fBlanguage\fP {'c' \ 'sql' \ 'internal' \ 'plname'}
\fBas\fP { '/full/path/to/objectfile' | 'sql-queries' |
'builtin-function-name' | 'pl-program-text' }
\fBlanguage\fP { 'c' | 'sql' | 'internal' | 'plname' }
.fi
.SH "DESCRIPTION"
With this command, a Postgres user can register a function with Postgres.
@ -35,9 +36,8 @@ or
.IR "plname"
is the language name of a created procedural language. See
create_language(l) for details.)
(The
.IR "arg is"
clause may be left out if the function has no arguments, or
(The argument list
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
.IR opaque .
@ -54,32 +54,43 @@ modifier indicates that the function will return a set of items,
rather than a single item.
The
.IR as
clause of the command is treated differently for C and SQL
functions, as explained below.
clause of the command is treated differently depending on the language,
as explained below.
.SH "INTERNAL FUNCTIONS"
Internal functions are functions written in C which have been statically
linked into the postgres backend process. The
.BR as
clause gives the C-language name of the function, which need not be the
same as the name being declared for SQL use. (For reasons of backwards
compatibility, an empty
.BR as
string is accepted as meaning that the C-language function name is the
same as the SQL name.) Normally, all internal functions present in the
backend are declared as SQL functions during database initialization,
but a user could use
.BR "create function"
to create additional alias names for an internal function.
.SH "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 them into its address space. The
.IR as
clause gives the full path name of the object file that contains the
function. This file is loaded either using
.IR 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.
.PP
Internal functions are functions written in C which have been statically
linked into the postgres backend process. The
.BR as
clause must still be specified when defining an internal function but
the contents are ignored.
.SH "Writing C Functions"
The body of a C function following
For a C function, the string following
.BR as
should be the
.BR "FULL PATH"
of the object code (.o file) for the function, bracketed by quotation
of the object code 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
.BR "define function"
command.)
.BR "create function"
command. See below for additional information.)
.PP
C functions with base type arguments can be written in a
straightforward fashion. The C equivalents of built-in Postgres types
@ -297,7 +308,7 @@ on. If an argument is complex, then a \*(lqdot\*(rq notation may be
used to access attributes of the argument (e.g. \*(lq$1.emp\*(rq), or
to invoke functions via a nested-dot syntax.
.SH "PL FUNCTIONS"
Procedural languages aren't builtin to Postgres. They are offered
Procedural languages aren't built into Postgres. They are offered
by loadable modules. Please refer to the documentation for the
PL in question for details about the syntax and how the
.IR "as"
@ -400,10 +411,11 @@ A function may also have the same name as an attribute. In the case
that there is an ambiguity between a function on a complex type and
an attribute of the complex type, the attribute will always be used.
.SH "RESTRICTIONS"
The name of the C function must be a legal C function name, and the
name of the function in C code must be exactly the same as the name
used in
.BR "create function" .
For functions written in C, the SQL name declared in
.BR "create function"
must be exactly the same as the actual name of the function in the
C code (hence it must be a legal C function name).
.PP
There is a subtle implication of this restriction: while the
dynamic loading routines in most operating systems are more than
happy to allow you to load any number of shared libraries that
@ -422,6 +434,14 @@ define a set of C functions with different names and then define
a set of identically-named SQL function wrappers that take the
appropriate argument types and call the matching C function.
.PP
Another solution is not to use dynamic loading, but to link your
functions into the backend statically and declare them as INTERNAL
functions. Then, the functions must all have distinct C names but
they can be declared with the same SQL names (as long as their
argument types differ, of course). This way avoids the overhead of
an SQL wrapper function, at the cost of more effort to prepare a
custom backend executable.
.PP
.IR opaque
cannot be given as an argument to a SQL function.
.SH "BUGS"