C 语言函数

PostgreSQL 9.6.0 手册
上一页	上一级	章 36. 扩展 SQL	下一页

36.9.1. 动态载入

在一个会话中第一次调用一个特定可载入对象文件中的用户定义函数时，动态载入器会把那个对象文件载入到内存以便该函数被调用。因此用户定义的 C 函数的CREATE FUNCTION必须为该函数指定两块信息：可载入对象文件的名称，以及要在该对象文件中调用的特定函数的 C 名称（链接符号）。如果没有显式指定 C 名称，则它被假定为和 SQL 函数名相同。

下面的算法被用来基于CREATE FUNCTION 命令中给定的名称来定位共享对象文件：

如果名称是一个绝对路径，则载入给定的文件。
如果该名称以字符串$libdir开始，那么这一部分会被 PostgreSQL包的库目录名（在编译时确定）替换。
如果该名称不包含目录部分，会在配置变量 dynamic_library_path指定的路径中搜索该文件。
否则（在该路径中没找到该文件，或者它包含一个非绝对目录），动态载入器将尝试接受给定的名称，这大部分会导致失败（依赖当前工作目录是不可靠的）。

如果这个序列不起作用，会把平台相关的共享库文件名扩展（通常是 .so）追加到给定的名称并且再次尝试上述的过程。如果还是失败，则载入失败。

我们推荐相对于$libdir或者通过动态库路径来定位共享库。如果升级版本时新的安装在一个不同的位置，则可以简化升级过程。$libdir实际表示的目录可以用命令pg_config --pkglibdir来找到。

用于运行PostgreSQL服务器的用户 ID 必须能够通过要载入文件的路径。常见的错误是把文件或更高层的目录变得对postgres用户不可读或者不可执行。

在任何情况下，CREATE FUNCTION命令中给定的文件名会被原封不动地记录在系统目录中，这样如果需要再次载入该文件则会应用同样的过程。

注意: PostgreSQL不会自动编译 C 函数。在从CREATE FUNCTION命令中引用对象文件之前，它必须先被编译好。更多信息请见第 36.9.6 节。

为了确保动态载入对象文件不会被载入到一个不兼容的服务器， PostgreSQL会检查该文件是否包含一个带有合适内容的"magic block"。这允许服务器检测到明显的不兼容，例如为不同PostgreSQL主版本编译的代码。从PostgreSQL 8.2 开始，动态载入的函数要求有一个 magic block。要包括一个 magic block，在写上包括头文件fmgr.h的语句之后，在该模块的源文件之一（并且只能在其中一个）中写上这些：

#ifdef PG_MODULE_MAGIC
PG_MODULE_MAGIC;
#endif

如果代码不需要针对 8.2 之前的PostgreSQL 发行版进行编译，则#ifdef测试可以被省略。

在被第一次使用后，动态载入对象文件会留在内存中。在同一个会话中对该函数未来的调用将只会消耗很小的负荷进行符号表查找。如果需要重新载入一个对象文件（例如重新编译以后），需要开始一个新的会话。

可以选择让一个动态载入文件包含初始化和终止化函数。如果文件包含一个名为_PG_init的函数，则文件被载入后会立刻调用该函数。该函数不接受参数并且应该返回 void。如果文件包括一个名为 _PG_fini的函数，则在卸载该文件之前会立即调用该函数。同样地，该函数不接受参数并且应该返回 void。注意将只在卸载文件的过程中会调用_PG_fini，进程结束时不会调用它（当前，卸载被禁用并且从不发生，但是未来可能会改变）。

36.9.2. C 语言函数中的基本类型

要了解如何编写 C 语言函数，你需要了解 PostgreSQL如何在内部表达基本数据类型以及如何与函数传递它们。在内部， PostgreSQL把一个基本类型认为是 "一团内存"。在类型上定义的用户定义函数说明了 PostgreSQL在该类型上操作的方式。也就是说，PostgreSQL将只负责把数据存在磁盘以及从磁盘检索数据，而使用你的用户定义函数来输入、处理和输出该数据。

基本类型可以有三种内部格式之一：

传值，定长
传引用，定长
串引用，变长

传值类型在长度上只能是 1、2 或 4 字节（如果你的机器上 sizeof(Datum)是 8，则还有 8 字节）。你应当小心地定义你的类型以便它们在所有的架构上都是相同的尺寸（字节）。例如， long类型很危险，因为它在某些机器上是 4 字节但在另外一些机器上是 8 字节，而int类型在大部分 Unix 机器上都是 4 字节。在 Unix 机器上int4类型一种合理的实现可能是：

/* 4 字节整数，传值 */
typedef int int4;

（实际的 PostgreSQL C 代码会把这种类型称为int32，因为 C 中的习惯是intXX 表示XX 位。注意因此还有尺寸为 1 字节的 C 类型int8。SQL 类型 int8在 C 中被称为int64。另见表 36-1）。

在另一方面，任何尺寸的定长类型可以用传引用的方法传递。例如，这里有一种 PostgreSQL类型的实现示例：

/* 16 字节结构，传引用 */
typedef struct
{
    double  x, y;
} Point;

在PostgreSQL函数中传进或传出这种类型时，只能使用指向这种类型的指针。要返回这样一种类型的值，用 palloc分配正确的内存量，然后填充分配好的内存，并且返回一个指向该内存的指针（还有，如果只想返回与具有相同数据类型的一个输入参数相同的值，可以跳过额外的palloc并且返回指向该输入值的指针）。

最后，所有变长类型必须也以引用的方式传递。所有变长类型必须用一个正好 4 字节的不透明长度域开始，该域会由SET_VARSIZE 设置，绝不要直接设置该域！所有要被存储在该类型中的数据必须在内存中接着该长度域的后面存储。长度域包含该结构的总长度，也就是包括长度域本身的尺寸。

另一个重点是要避免在数据类型值中留下未被初始化的位。例如，要注意把可能存在于结构中的任何对齐填充字节置零。如果不这样做，你的数据类型的逻辑等价常量可能会被规划器认为是不等的，进而导致低效的（不过还是正确的）计划。

警告

绝不要修改通过引用传递的输入值的内容。如果这样做很可能会破坏磁盘上的数据，因为给出的指针可能直接指向一个磁盘缓冲区。这条规则唯一的例外在第 36.10 节中有解释。

例如，我们可以这样定义类型text：

typedef struct {
    int32 length;
    char data[FLEXIBLE_ARRAY_MEMBER];
} text;

[FLEXIBLE_ARRAY_MEMBER]记号表示数据部分的实际长度不由该声明指定。

在操纵变长字节时，我们必须小心地分配正确数量的内存并且正确地设置长度域。例如，如果我们想在一个text结构中存储 40 字节，我们可以使用这样的代码片段：

#include "postgres.h"
...
char buffer[40]; /* our source data */
...
text *destination = (text *) palloc(VARHDRSZ + 40);
SET_VARSIZE(destination, VARHDRSZ + 40);
memcpy(destination->data, buffer, 40);
...

VARHDRSZ和sizeof(int32)一样，但是用宏VARHDRSZ来引用变长类型的载荷的尺寸被认为是比较好的风格。还有，必须使用SET_VARSIZE宏来设置长度域，而不是用简单的赋值来设置。

表 36-1指定在编写使用一种 PostgreSQL内建类型的 C 语言函数时，哪一种 C 类型对应于哪一种 SQL 类型。 "定义文件"列给出了要得到该类型定义需要包括的头文件（实际的定义可能在一个由列举文件包括的不同文件中。推荐用户坚持使用已定义的接口）。注意在任何源文件中应该总是首先包括postgres.h，因为它声明了很多你需要的东西。

表 36-1. 内建 SQL 类型等效的 C 类型

SQL 类型	C 类型	定义文件
`abstime`	`AbsoluteTime`	`utils/nabstime.h`
`bigint` (`int8`)	`int64`	`postgres.h`
`boolean`	`bool`	`postgres.h`（可能是编译器内建）
`box`	`BOX*`	`utils/geo_decls.h`
`bytea`	`bytea*`	`postgres.h`
`"char"`	`char`	（编译器内建）
`character`	`BpChar*`	`postgres.h`
`cid`	`CommandId`	`postgres.h`
`date`	`DateADT`	`utils/date.h`
`smallint` (`int2`)	`int16`	`postgres.h`
`int2vector`	`int2vector*`	`postgres.h`
`integer` (`int4`)	`int32`	`postgres.h`
`real` (`float4`)	`float4*`	`postgres.h`
`double precision` (`float8`)	`float8*`	`postgres.h`
`interval`	`Interval*`	`datatype/timestamp.h`
`lseg`	`LSEG*`	`utils/geo_decls.h`
`name`	`Name`	`postgres.h`
`oid`	`Oid`	`postgres.h`
`oidvector`	`oidvector*`	`postgres.h`
`path`	`PATH*`	`utils/geo_decls.h`
`point`	`POINT*`	`utils/geo_decls.h`
`regproc`	`regproc`	`postgres.h`
`reltime`	`RelativeTime`	`utils/nabstime.h`
`text`	`text*`	`postgres.h`
`tid`	`ItemPointer`	`storage/itemptr.h`
`time`	`TimeADT`	`utils/date.h`
`time with time zone`	`TimeTzADT`	`utils/date.h`
`timestamp`	`Timestamp*`	`datatype/timestamp.h`
`tinterval`	`TimeInterval`	`utils/nabstime.h`
`varchar`	`VarChar*`	`postgres.h`
`xid`	`TransactionId`	`postgres.h`

现在我们已经复习了基本类型所有可能的结构，现在可以展示一些真实函数的例子了。

36.9.3. 版本 0 调用约定

我们先介绍"旧风格"的调用规范 — 尽管这种方法已经被废弃，它对初学者更容易掌握。在版本-0 方法中， C 函数的参数和结果只是以不同的 C 风格声明，但是要小心使用上文所示的每种 SQL 数据类型的 C 表达。

这里有一些例子：

#include "postgres.h"
#include <string.h>
#include "utils/geo_decls.h"

#ifdef PG_MODULE_MAGIC
PG_MODULE_MAGIC;
#endif

/* 传值 */

int
add_one(int arg)
{
    return arg + 1;
}

/* 传引用，定长 */

float8 *
add_one_float8(float8 *arg)
{
    float8    *result = (float8 *) palloc(sizeof(float8));

    *result = *arg + 1.0;

    return result;
}

Point *
makepoint(Point *pointx, Point *pointy)
{
    Point     *new_point = (Point *) palloc(sizeof(Point));

    new_point->x = pointx->x;
    new_point->y = pointy->y;

    return new_point;
}

/* 传引用，变长 */

text *
copytext(text *t)
{
    /*
     * VARSIZE 是结构的总尺寸（字节）。
     */
    text *new_t = (text *) palloc(VARSIZE(t));
    SET_VARSIZE(new_t, VARSIZE(t));
    /*
     * VARDATA 是指向结构的数据区域的指针。
     */
    memcpy((void *) VARDATA(new_t), /* 目标 */
           (void *) VARDATA(t),     /* 源 */
           VARSIZE(t) - VARHDRSZ);  /* 多少字节 */
    return new_t;
}

text *
concat_text(text *arg1, text *arg2)
{
    int32 new_text_size = VARSIZE(arg1) + VARSIZE(arg2) - VARHDRSZ;
    text *new_text = (text *) palloc(new_text_size);

    SET_VARSIZE(new_text, new_text_size);
    memcpy(VARDATA(new_text), VARDATA(arg1), VARSIZE(arg1) - VARHDRSZ);
    memcpy(VARDATA(new_text) + (VARSIZE(arg1) - VARHDRSZ),
           VARDATA(arg2), VARSIZE(arg2) - VARHDRSZ);
    return new_text;
}

假定上述代码已经在文件funcs.c中准备好并且已经被编译到一个共享对象中，我们可以用下面的命令在 PostgreSQL中定义这些函数：

CREATE FUNCTION add_one(integer) RETURNS integer
     AS 'DIRECTORY/funcs', 'add_one'
     LANGUAGE C STRICT;

-- 注意这是重载名为 "add_one" 的 SQL 函数
CREATE FUNCTION add_one(double precision) RETURNS double precision
     AS 'DIRECTORY/funcs', 'add_one_float8'
     LANGUAGE C STRICT;

CREATE FUNCTION makepoint(point, point) RETURNS point
     AS 'DIRECTORY/funcs', 'makepoint'
     LANGUAGE C STRICT;

CREATE FUNCTION copytext(text) RETURNS text
     AS 'DIRECTORY/funcs', 'copytext'
     LANGUAGE C STRICT;

CREATE FUNCTION concat_text(text, text) RETURNS text
     AS 'DIRECTORY/funcs', 'concat_text'
     LANGUAGE C STRICT;

这里，DIRECTORY表示共享库文件的目录（例如PostgreSQL的教程目录，它包含这一节使用的例子的代码）。（更好的风格是在把 DIRECTORY增加到搜索路径后，只在 AS子句中使用'funcs'。在很多情况下，我们可以省略共享库的系统相关的扩展，通常是.so或者 .sl）。

注意我们已经指定这些函数为"严格的"，表示如果任何输入值为空系统应该自动假定它们会得到空值结果。通过这样做，我们可以避免在函数代码中检测空值输入。如果不这样做，我们必须显式地检查空值，做法是对每一个传引用参数检查是不是空指针（对于传值参数，我们甚至没有方法来检查！）。

尽管这种调用规范简单易用，它不太容易移植，某些架构上对于用这种方法传递小于int的数据类型会有问题。还有，没有简单的方法返回空结果，也没有办法处理空值参数（除了让该函数变成严格的）。下文介绍的版本-1 规范克服了这些缺陷。

36.9.4. 版本 1 的调用约定

版本-1 的调用规范依赖于宏来降低传参数和结果的复杂度。版本-1 函数的 C 声明总是：

Datum funcname(PG_FUNCTION_ARGS)

此外，宏调用：

PG_FUNCTION_INFO_V1(funcname);

必须出现在同一个源文件中（按惯例会正好写在该函数本身之前）。这种宏调用不是内部语言函数所需要的，因为 PostgreSQL会假定所有内部函数都使用版本-1 规范。不过，对于动态载入函数是必需的。

在版本-1 函数中，每一个实参都使用对应于该参数数据类型的 PG_GETARG_xxx() 宏取得，并且结果要用对应于返回类型的 PG_RETURN_xxx() 宏返回。 PG_GETARG_xxx() 的参数是要取得的函数参数的编号，从零开始计。 PG_RETURN_xxx() 的参数是实际要返回的值。

这里展示的是和上述函数相同的函数，但是用版本-1 的风格编码：

#include "postgres.h"
#include <string.h>
#include "fmgr.h"
#include "utils/geo_decls.h"

#ifdef PG_MODULE_MAGIC
PG_MODULE_MAGIC;
#endif

/* 传值 */

PG_FUNCTION_INFO_V1(add_one);

Datum
add_one(PG_FUNCTION_ARGS)
{
    int32   arg = PG_GETARG_INT32(0);

    PG_RETURN_INT32(arg + 1);
}

/* 传引用，定长 */

PG_FUNCTION_INFO_V1(add_one_float8);

Datum
add_one_float8(PG_FUNCTION_ARGS)
{
    /* FLOAT8 的宏隐藏了它的传引用本质。 */
    float8   arg = PG_GETARG_FLOAT8(0);

    PG_RETURN_FLOAT8(arg + 1.0);
}

PG_FUNCTION_INFO_V1(makepoint);

Datum
makepoint(PG_FUNCTION_ARGS)
{
    /* 这里，Point 的传引用本质没有被掩盖。 */
    Point     *pointx = PG_GETARG_POINT_P(0);
    Point     *pointy = PG_GETARG_POINT_P(1);
    Point     *new_point = (Point *) palloc(sizeof(Point));

    new_point->x = pointx->x;
    new_point->y = pointy->y;

    PG_RETURN_POINT_P(new_point);
}

/* 传引用，变长 */

PG_FUNCTION_INFO_V1(copytext);

Datum
copytext(PG_FUNCTION_ARGS)
{
    text     *t = PG_GETARG_TEXT_P(0);
    /*
     * VARSIZE 是结构的总尺寸（字节）。
     */
    text     *new_t = (text *) palloc(VARSIZE(t));
    SET_VARSIZE(new_t, VARSIZE(t));
    /*
     * VARDATA 是指向结构的数据区域的指针。
     */
    memcpy((void *) VARDATA(new_t), /* 目标 */
           (void *) VARDATA(t),     /* 源 */
           VARSIZE(t) - VARHDRSZ);  /* 多少字节 */
    PG_RETURN_TEXT_P(new_t);
}

PG_FUNCTION_INFO_V1(concat_text);

Datum
concat_text(PG_FUNCTION_ARGS)
{
    text  *arg1 = PG_GETARG_TEXT_P(0);
    text  *arg2 = PG_GETARG_TEXT_P(1);
    int32 new_text_size = VARSIZE(arg1) + VARSIZE(arg2) - VARHDRSZ;
    text *new_text = (text *) palloc(new_text_size);

    SET_VARSIZE(new_text, new_text_size);
    memcpy(VARDATA(new_text), VARDATA(arg1), VARSIZE(arg1) - VARHDRSZ);
    memcpy(VARDATA(new_text) + (VARSIZE(arg1) - VARHDRSZ),
           VARDATA(arg2), VARSIZE(arg2) - VARHDRSZ);
    PG_RETURN_TEXT_P(new_text);
}

版本-1 的CREATE FUNCTION命令和版本-0 的相同。

乍一看，版本-1 编码规范可能就是无意义的愚民政策。不过，它们确实提供了很多改进，因为那些宏可以隐藏不需要的细节。一个例子是在编码 add_one_float8时，我们不再需要关注 float8是一种传引用类型。另一个例子是变长类型的 GETARG宏允许更方便地取得"被 TOAST"（压缩或者线外）的值。

版本-1 函数中的一个大进步是对空值输入和结果更好的处理。宏 PG_ARGISNULL(n)允许一个函数测试是否每一个输入为空（当然，只需要在没有声明为"strict" 的函数中这样做）。和 PG_GETARG_xxx()宏一样，输入参数也是从零开始计数。注意应该在验证了一个参数不是空之后才执行 PG_GETARG_xxx()。要返回一个空结果，应执行PG_RETURN_NULL()，它对严格的以及非严格的函数都有用。

在新风格接口中提供的其他选项是 PG_GETARG_xxx()宏的两个变种。其中的第一种是 PG_GETARG_xxx_COPY()，它确保返回的指定参数的拷贝可以被安全地写入（通常的宏有时会返回一个指向表中物理存储的值，它不能被写入。使用 PG_GETARG_xxx_COPY() 宏可以保证得到一个可写的结果）。第二种变种 PG_GETARG_xxx_SLICE() 宏有三个参数。第一个是函数参数的编号（如上文）。第二个和第三个是要被返回的段的偏移量和长度。偏移量从零开始计算，而负值的长度则表示要求返回该值的剩余部分。当大型值的存储类型为"external"时，这些宏提供了访问这些大型值的更有效的方法（列的存储类型可以使用 ALTER TABLE tablename ALTER COLUMN colname SET STORAGE storagetype来指定。 storagetype取plain、 external、extended或者 main）。

最后，版本-1 的函数调用规范可以返回集合结果（第 36.9.9 节）、实现触发器函数（第 37 章）和过程语言调用处理器（第 54 章）。版本-1 的代码也比版本-0 的可移植性更好，因为它不会打破 C 标准中对函数调用协议上的限制。更多细节可见源代码发布中的 src/backend/utils/fmgr/README。

36.9.5. 编写代码

在开始更高级的话题之前，我们应该讨论一下用于 PostgreSQL C 语言函数的编码规则。虽然可以把不是 C 编写的函数载入到 PostgreSQL中，这通常是很困难的，因为其他语言（例如 C++、FORTRAN 或者 Pascal）通常不会遵循和 C 相同的调用规范。也就是说，其他语言不会以同样的方式在函数之间传递参数以及返回值。由于这个原因，我们会假定你的 C 语言函数确实是用 C 编写的。

编写和编译 C 函数的基本规则如下：

使用pg_config --includedir-server 找出PostgreSQL服务器头文件安装在系统的哪个位置。
编译并且链接你的代码（这样它就能被动态载入到 PostgreSQL中）总是要求特殊的标志。对特定的操作系统的做法详见第 36.9.6 节。
记住为你的共享库按第 36.9.1 节中所述定义一个"magic block"。
在分配内存时，使用 PostgreSQL函数 palloc和 pfree，而不是使用对应的 C 库函数 malloc和free。在每个事务结束时会自动释放通过palloc 分配的内存，以免内存泄露。
总是要使用memset把你的结构中的字节置零（或者最开始就用palloc0分配它们）。即使你对结构中的每个域都赋值，也可能有对齐填充（结构中的空洞）包含着垃圾值。如果不这样做，很难支持哈希索引或哈希连接，因为你必须选出数据结构中有意义的位进行哈希计算。规划器有时也依赖于用按位相等来比较常量，因此如果逻辑等价的值不是按位相等的会导致出现不想要的规划结果。
大部分的内部PostgreSQL类型都声明在postgres.h中，不过函数管理器接口（PG_FUNCTION_ARGS等）在 fmgr.h中，因此你将需要包括至少这两个文件。为了移植性，最好在包括任何其他系统或者用户头文件之前，先包括postgres.h。包括postgres.h也将会为你包括 elog.h和palloc.h。
对象文件中定义的符号名不能相互冲突或者与 PostgreSQL服务器可执行程序中定义的符号冲突。如果出现有关于此的错误消息，你将必须重命名你的函数或者变量。

36.9.6. 编译和链接动态载入的函数

在使用 C 编写的PostgreSQL扩展函数之前，必须以一种特殊的方式编译并且链接它们，以便产生一个能被服务器动态载入的文件。简而言之，需要创建一个共享库。

超出本节所含内容之外的信息请参考你的操作系统文档，特别是 C 编译器（cc）和链接编辑器（ld）的手册页。另外，PostgreSQL源代码的contrib目录中包含了一些可以工作的例子。但是，如果你依靠这些例子，也会使你的模块依赖于PostgreSQL源码的可用性。

创建共享库通常与链接可执行文件相似：首先源文件被编译成对象文件，然后对象文件被链接起来。对象文件需要被创建为独立位置代码（PIC），，这在概念上意味着当它们被可执行文件载入时，它们可以被放置在内存中的任意位置（用于可执行文件的对象文件通常不会以那种方式编译）。链接一个共享库的命令会包含特殊标志来把它与链接一个可执行文件区分开（至少在理论上 — 在某些系统上实际上很丑陋）。

在下列例子中，我们假定你的源代码在一个文件foo.c中，并且我们将创建一个共享库foo.so。除非特别注明，中间的对象文件将被称为foo.o。一个共享库能包含多于一个对象文件，但是我们在这里只使用一个。

FreeBSD

用来创建PIC的编译器标志是-fpic。要创建共享库，编译器标志是-shared。

gcc -fpic -c foo.c
gcc -shared -o foo.so foo.o

这适用于FreeBSD从 3.0 开始的版本。

HP-UX

该系统编译器创建PIC的编译器标志是+z。当使用GCC自己的-fpic时。用于共享库的链接器标志是-b。因此：

cc +z -c foo.c

或者：

gcc -fpic -c foo.c

并且然后：

ld -b -o foo.sl foo.o

和大部分其他系统不同，HP-UX为共享库使用扩展.sl。

Linux

创建PIC的编译器标志是-fpic。在某些平台上的某些情况下，如果-fpic不起作用，那么必须使用-fPIC。详情请参考 GCC 手册。创建一个共享库的编译器标志是-shared。一个完整的例子看起来像：

cc -fpic -c foo.c
cc -shared -o foo.so foo.o

Mac OS X

这里是一个例子。它假定安装了开发者工具。

cc -c foo.c
cc -bundle -flat_namespace -undefined suppress -o foo.so foo.o

NetBSD

创建PIC的编译器标志是-fpic。对于ELF系统，带着标志-shared的编译器被用来链接共享库。在旧的非 ELF 系统上，ld -Bshareable会被使用。

gcc -fpic -c foo.c
gcc -shared -o foo.so foo.o

OpenBSD

创建PIC的编译器标志是-fpic。ld -Bshareable被用来链接共享库。

gcc -fpic -c foo.c
ld -Bshareable -o foo.so foo.o

Solaris

创建PIC的编译器标志是-KPIC（用于 Sun 编译器）以及-fpic（用于GCC）。要链接共享库，编译器选项对几种编译器都是-G或者是对GCC使用-shared。

cc -KPIC -c foo.c
cc -G -o foo.so foo.o

or

gcc -fpic -c foo.c
gcc -G -o foo.so foo.o

UnixWare

创建PIC的编译器标志是-KPIC（用于 SCO 编译器）以及-fpic（用于GCC）。要链接共享库，编译器选项是-G（用于 SCO 编译器）以及-shared（用于GCC）。

cc -K PIC -c foo.c
cc -G -o foo.so foo.o

or

gcc -fpic -c foo.c
gcc -shared -o foo.so foo.o

提示: 如果这对你来说太复杂，你应该考虑使用 GNU Libtool，它会用一个统一的接口隐藏平台差异。

结果的共享库文件接着就可以被载入到PostgreSQL。当把文件名指定给CREATE FUNCTION命令时，必须把共享库文件的名字给它，而不是中间的对象文件。注意系统的标准共享库扩展（通常是.so或者.sl）在CREATE FUNCTION命令中可以被忽略，并且通常为了最好的可移植性应该被忽略。

服务器会期望在哪里寻找共享库文件请参考第 36.9.1 节。

36.9.7. 组合类型参数

组合类型没有像 C 结构那样的固定布局。组合类型的实例可能包含空值域。此外，继承层次中的组合类型可能具有和同一继承层次中其他成员不同的域。因此， PostgreSQL提供了函数接口来访问 C 的组合类型的域。

假设我们想要写一个函数来回答查询：

SELECT name, c_overpaid(emp, 1500) AS overpaid
    FROM emp
    WHERE name = 'Bill' OR name = 'Sam';

如果使用调用规范版本 0，我们可以定义 c_overpaid为：

#include "postgres.h"
#include "executor/executor.h"  /* 用于 GetAttributeByName() */

#ifdef PG_MODULE_MAGIC
PG_MODULE_MAGIC;
#endif

bool
c_overpaid(HeapTupleHeader t, /* emp 的当前行 */
           int32 limit)
{
    bool isnull;
    int32 salary;

    salary = DatumGetInt32(GetAttributeByName(t, "salary", &isnull));
    if (isnull)
        return false;
    return salary > limit;
}

在版本-1 编码中，上面的函数可能看起来是这样的：

#include "postgres.h"
#include "executor/executor.h"  /* 用于 GetAttributeByName() */

#ifdef PG_MODULE_MAGIC
PG_MODULE_MAGIC;
#endif

PG_FUNCTION_INFO_V1(c_overpaid);

Datum
c_overpaid(PG_FUNCTION_ARGS)
{
    HeapTupleHeader  t = PG_GETARG_HEAPTUPLEHEADER(0);
    int32            limit = PG_GETARG_INT32(1);
    bool isnull;
    Datum salary;

    salary = GetAttributeByName(t, "salary", &isnull);
    if (isnull)
        PG_RETURN_BOOL(false);
    /* 另外，我们可能更想对空 salary 用 PG_RETURN_NULL() 。*/

    PG_RETURN_BOOL(DatumGetInt32(salary) > limit);
}

GetAttributeByName是返回指定行的属性的 PostgreSQL系统函数。它有三个参数：类型为HeapTupleHeader的传入参数、想要访问的函数名以及一个说明该属性是否为空的返回参数。 GetAttributeByName返回一个Datum 值，可以把它用合适的DatumGetXXX() 宏转换成正确的数据类型。注意如果空值标志被设置，那么返回值是没有意义的，所以在对结果做任何事情之前应该先检查空值标志。

也有GetAttributeByNum函数，它可以用目标属性的属性号而不是属性名来选择目标属性。

下面的命令声明 SQL 中的c_overpaid：

CREATE FUNCTION c_overpaid(emp, integer) RETURNS boolean
    AS 'DIRECTORY/funcs', 'c_overpaid'
    LANGUAGE C STRICT;

注意我们用了STRICT，这样我们不需要检查输入参数是否为 NULL。

36.9.8. 返回行（组合类型）

要从一个 C 语言函数中返回一个行或者组合类型值，你可以使用一种特殊的 API，它提供的宏和函数隐藏了大部分的构建组合数据类型的复杂性。要使用这种 API，源文件中必须包括：

#include "funcapi.h"

有两种方式可以构建一个组合数据值（以后就叫一个"元组"）：可以从一个 Datum 值的数组构造，或者从一个 C 字符串（可被传递给该元组各列的数据类型的输入转换函数）的数组构造。在两种情况下，都首先需要为该元组的结构获得或者构造一个TupleDesc描述符。在处理 Datum 时，需要把该TupleDesc传递给 BlessTupleDesc，接着为每一行调用 heap_form_tuple。在处理 C 字符串时，需要把该 TupleDesc传递给 TupleDescGetAttInMetadata，接着为每一行调用 BuildTupleFromCStrings。对于返回一个元组集合的函数，这些设置步骤可以在第一次调用该函数时一次性完成。

有一些助手函数可以用来设置所需的TupleDesc。在大部分返回组合值的函数中推荐的方式是调用：

TypeFuncClass get_call_result_type(FunctionCallInfo fcinfo,
                                   Oid *resultTypeId,
                                   TupleDesc *resultTupleDesc)

传递传给调用函数本身的同一个fcinfo结构（这当然要求使用的是版本-1 的调用规范）。resultTypeId可以被指定为 NULL或者一个本地变量的地址以接收该函数的结果类型 OID。 resultTupleDesc应该是一个本地 TupleDesc变量的地址。检查结果是不是 TYPEFUNC_COMPOSITE，如果是则 resultTupleDesc已经被用所需的 TupleDesc填充（如果不是，你可以报告一个错误，并且返回"function returning record called in context that cannot accept type record"字样的消息）。

提示: get_call_result_type能够解析一个多态函数结果的实际类型，因此不仅在返回组合类型的函数中，在返回标量多态结果的函数中它也是非常有用的。resultTypeId输出主要用于返回多态标量的函数。

注意: get_call_result_type有一个兄弟 get_expr_result_type，它被用来解析被表示为一棵表达式树的函数调用的输出类型。在尝试确定来自函数外部的结果类型时可以用它。也有一个get_func_result_type，当只有函数的 OID 可用时可以用它。不过这些函数无法处理被声明为返回record的函数，并且get_func_result_type无法解析多态类型，因此你应该优先使用get_call_result_type。

比较老的，现在已经被废弃的获得TupleDesc的函数是：

TupleDesc RelationNameGetTupleDesc(const char *relname)

它可以为一个提到的关系的行类型得到TupleDesc，还有：

TupleDesc TypeGetTupleDesc(Oid typeoid, List *colaliases)

可以基于一个类型 OID 得到TupleDesc。这可以被用来为一种基础或者组合类型获得TupleDesc。不过，对于返回record的函数它不起作用，并且它无法解析多态类型。

一旦有了一个TupleDesc，如果计划处理 Datum可以调用：

TupleDesc BlessTupleDesc(TupleDesc tupdesc)

如果计划处理 C 字符串，可调用：

AttInMetadata *TupleDescGetAttInMetadata(TupleDesc tupdesc)

如果正在编写一个返回集合的函数，你可以把这些函数的结果保存在 FuncCallContext结构中 — 分别使用 tuple_desc或者attinmeta域。

在处理 Datum 时，使用

HeapTuple heap_form_tuple(TupleDesc tupdesc, Datum *values, bool *isnull)

来用 Datum 形式的用户数据构建一个HeapTuple。

在处理 C 字符串时，使用

HeapTuple BuildTupleFromCStrings(AttInMetadata *attinmeta, char **values)

来用 C 字符串形式的用户数据构建一个HeapTuple。 values是一个 C 字符串数组，每一个元素是返回行的一个属性。每一个 C 字符串应该是该属性数据类型的输入函数所期望的格式。为了对一个属性返回空值，values数组中对应的指针应该被设置为NULL。对于你返回的每一行都将再次调用这个函数。

一旦已经构建了一个要从函数中返回的元组，它必须被转换成一个 Datum。使用

HeapTupleGetDatum(HeapTuple tuple)

可把一个HeapTuple转换成合法的 Datum。如果你只想返回一行，那么这个Datum可以被直接返回，在一个集合返回函数中它也可以被当做当前的返回值。

下一节中会有一个例子。

36.9.9. 返回集合

也提供了一种特殊的 API 来支持从 C 语言函数中返回集合（多个行）。集合返回函数必须遵循版本-1 的调用规范。如上文所述，源文件中还必须包括funcapi.h。

对返回的每一个项，一个集合返回函数（SRF）都会被调用一次。因此，这个SRF必须保存足够的状态来记住它正在做什么并且在每次调用时返回下一个项。结构 FuncCallContext被提供来帮助控制这个过程。在一个函数中，fcinfo->flinfo->fn_extra被用来在多次调用中保持指向FuncCallContext的指针。

typedef struct
{
    /*
     * 本次调用以前已经被调用过多少次
     *
     * SRF_FIRSTCALL_INIT() 会为你把 call_cntr 初始化为 0，
     * 并且在每次调用 SRF_RETURN_NEXT() 时增加。
     */
    uint32 call_cntr;

    /*
     * 可选：最大调用次数
     *
     * 这里的 max_calls 只是为了方便，设置它是可选的。
     * 如果没有设置，你必须提供替代的方法来了解函数什么时候做完。
     */
    uint32 max_calls;

    /*
     * 可选：指向结果槽的指针
     *
     * 这已经被废弃并且只为向后兼容而存在，也就是那些使用被废弃的
     * TupleDescGetSlot() 的用户定义 SRF。.
     */
    TupleTableSlot *slot;

    /*
     * 可选：指向用户提供的上下文信息的指针
     *
     * user_fctx 是一个指向你自己的数据的指针，它可用来在函数的多次
     * 调用之间保存任意的上下文信息。
     */
    void *user_fctx;

    /*
     * 可选：指向包含属性类型输入元数据的结构的指针
     *
     * attinmeta 被用在返回元组（即组合数据类型）时，在返回基本数据类型
     * 时不会使用。只有想用BuildTupleFromCStrings()创建返回元组时才需要它。
     */
    AttInMetadata *attinmeta;

    /*
     * 用于保存必须在多次调用间都存在的结构的内存上下文
     *
     * SRF_FIRSTCALL_INIT() 会为你设置 multi_call_memory_ctx，并且由
     * SRF_RETURN_DONE() 来清理。对于任何需要在 SRF 的多次调用间都
     * 存在的内存来说，它是最合适的内存上下文。
     */
    MemoryContext multi_call_memory_ctx;

    /*
     * 可选：指向包含元组描述的结构的指针
     *
     * tuple_desc 被用在返回元组（即组合数据类型）时，并且只有在用
     * heap_form_tuple() 而不是 BuildTupleFromCStrings() 构建元组时才需要它。
     * 注意这里存储的 TupleDesc 指针通常已经被先运行过 BlessTupleDesc()。
     */
    TupleDesc tuple_desc;

} FuncCallContext;

SRF使用一些自动操纵FuncCallContext （并且期望通过fn_extra找到它）的函数和宏。可使用：

SRF_IS_FIRSTCALL()

来判断你的函数是否是第一次被调用。在第一次调用时（只能在第一次调用时）使用：

SRF_FIRSTCALL_INIT()

可初始化FuncCallContext。在每一次函数调用时（包括第一次）可使用：

SRF_PERCALL_SETUP()

为使用FuncCallContext做适当的设置并且清除上一次留下来的任何已返回的数据。

如果你的函数有数据要返回，可使用：

SRF_RETURN_NEXT(funcctx, result)

把它返回给调用者（result必须是类型Datum，可以是一个单一值或者按上文所述准备好的元组）。最后，当函数完成了数据返回后，可使用：

SRF_RETURN_DONE(funcctx)

来清理并且结束SRF。

SRF被调用时的当前内存上下文被称作一个瞬时上下文，在两次调用之间会清除它。这意味着你不必对用palloc 分配的所有东西调用pfree，它们将自动被释放。不过，如果你想要分配任何需要在多次调用间都存在的数据结构，需要把它们放在其他地方。对于任何需要在SRF结束运行之前都存在的数据来说，multi_call_memory_ctx引用的内存上下文是一个合适的位置。在大部分情况中，这意味着应该在做第一次调用设置时就切换到multi_call_memory_ctx中。

警告

虽然函数的实参在多次调用之间保持不变，但如果在瞬时上下文中反 TOAST 了参数（通常由 PG_GETARG_xxx 宏完成），那么被反 TOAST 的拷贝将在每次循环中被释放。相应地，如果你把这些值的引用保存在user_fctx中，你也必须在反 TOAST 之后把它们拷贝到 multi_call_memory_ctx中，或者确保你只在那个上下文中反 TOAST 这些值。

一个完整的伪代码例子：

Datum
my_set_returning_function(PG_FUNCTION_ARGS)
{
    FuncCallContext  *funcctx;
    Datum             result;
    further declarations as needed

    if (SRF_IS_FIRSTCALL())
    {
        MemoryContext oldcontext;

        funcctx = SRF_FIRSTCALL_INIT();
        oldcontext = MemoryContextSwitchTo(funcctx->multi_call_memory_ctx);
        /* 这里是一次性设置代码： */
        user code
        if returning composite
            build TupleDesc, and perhaps AttInMetadata
        endif returning composite
        user code
        MemoryContextSwitchTo(oldcontext);
    }

    /* 这里是每一次都要做的设置代码： */
    user code
    funcctx = SRF_PERCALL_SETUP();
    user code

    /* 这里只是一种测试是否执行完的方法： */
    if (funcctx->call_cntr < funcctx->max_calls)
    {
        /* 这里返回另一个项： */
        user code
        obtain result Datum
        SRF_RETURN_NEXT(funcctx, result);
    }
    else
    {
        /* 这里已经完成了项的返回并且需要进行清理： */
        user code
        SRF_RETURN_DONE(funcctx);
    }
}

一个返回组合类型的简单SRF的完整例子：

PG_FUNCTION_INFO_V1(retcomposite);

Datum
retcomposite(PG_FUNCTION_ARGS)
{
    FuncCallContext     *funcctx;
    int                  call_cntr;
    int                  max_calls;
    TupleDesc            tupdesc;
    AttInMetadata       *attinmeta;

    /* 只在第一次函数调用时做的事情 */
    if (SRF_IS_FIRSTCALL())
    {
        MemoryContext   oldcontext;

        /* 创建一个函数上下文，让它在多次调用间都保持存在 */
        funcctx = SRF_FIRSTCALL_INIT();

        /* 切换到适合多次函数调用的内存上下文 */
        oldcontext = MemoryContextSwitchTo(funcctx->multi_call_memory_ctx);

        /* 要返回的元组总数 */
        funcctx->max_calls = PG_GETARG_UINT32(0);

        /* 为结果类型构造一个元组描述符 */
        if (get_call_result_type(fcinfo, NULL, &tupdesc) != TYPEFUNC_COMPOSITE)
            ereport(ERROR,
                    (errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
                     errmsg("function returning record called in context "
                            "that cannot accept type record")));

        /*
         * 生成后面需要用来从原始 C 字符串产生元组的属性元数据
         */
        attinmeta = TupleDescGetAttInMetadata(tupdesc);
        funcctx->attinmeta = attinmeta;

        MemoryContextSwitchTo(oldcontext);
    }

    /* 在每一次函数调用都要完成的事情 */
    funcctx = SRF_PERCALL_SETUP();

    call_cntr = funcctx->call_cntr;
    max_calls = funcctx->max_calls;
    attinmeta = funcctx->attinmeta;

    if (call_cntr < max_calls)    /* 如果还有要发送的 */
    {
        char       **values;
        HeapTuple    tuple;
        Datum        result;

        /*
         * 为构建返回元组准备一个值数组。这应该是一个 C
         * 字符串数组，之后类型输入函数会处理它。
         */
        values = (char **) palloc(3 * sizeof(char *));
        values[0] = (char *) palloc(16 * sizeof(char));
        values[1] = (char *) palloc(16 * sizeof(char));
        values[2] = (char *) palloc(16 * sizeof(char));

        snprintf(values[0], 16, "%d", 1 * PG_GETARG_INT32(1));
        snprintf(values[1], 16, "%d", 2 * PG_GETARG_INT32(1));
        snprintf(values[2], 16, "%d", 3 * PG_GETARG_INT32(1));

        /* 构建一个元组 */
        tuple = BuildTupleFromCStrings(attinmeta, values);

        /* 把元组变成 datum */
        result = HeapTupleGetDatum(tuple);

        /* 清理（实际并不必要） */
        pfree(values[0]);
        pfree(values[1]);
        pfree(values[2]);
        pfree(values);

        SRF_RETURN_NEXT(funcctx, result);
    }
    else    /* 如果没有要发送的 */
    {
        SRF_RETURN_DONE(funcctx);
    }
}

在 SQL 中声明这个函数的一种方法是：

CREATE TYPE __retcomposite AS (f1 integer, f2 integer, f3 integer);

CREATE OR REPLACE FUNCTION retcomposite(integer, integer)
    RETURNS SETOF __retcomposite
    AS 'filename', 'retcomposite'
    LANGUAGE C IMMUTABLE STRICT;

一种不同的方法是使用 OUT 参数：

CREATE OR REPLACE FUNCTION retcomposite(IN integer, IN integer,
    OUT f1 integer, OUT f2 integer, OUT f3 integer)
    RETURNS SETOF record
    AS 'filename', 'retcomposite'
    LANGUAGE C IMMUTABLE STRICT;

注意在这种方法中，函数的输出类型在形式上是一种匿名的 record类型。

源码中的目录contrib/tablefunc 下的模块包含集合返回函数更加复杂的例子。

36.9.10. 多态参数和返回类型

C 语言函数可以被声明为接受和返回多态类型 anyelement、anyarray、 anynonarray、 anyenum以及anyrange。关于多态函数的详细介绍请见第 36.2.5 节。当函数参数或者返回类型被定义为多态类型时，函数的编写者无法提前知道会用什么数据类型调用该函数或者该函数需要返回什么数据类型。在fmgr.h 中提供了两种例程来允许版本-1 的 C 函数发现其参数的实际数据类型以及它要返回的类型。这些例程被称为 get_fn_expr_rettype(FmgrInfo *flinfo)和 get_fn_expr_argtype(FmgrInfo *flinfo, int argnum)。它们返回结果或者参数的类型的 OID，或者当该信息不可用时返回 InvalidOid。结构flinfo通常被当做 fcinfo->flinfo访问。参数argnum则是从零开始计。get_call_result_type也可被用作 get_fn_expr_rettype的一种替代品。还有 get_fn_expr_variadic，它可以被用来找出 variadic 参数是否已经被合并到了一个数组中。这主要用于 VARIADIC "any"函数，因为对于接收普通数组类型的 variadic 函数来说总是会发生这类合并。

例如，假设我们想要写一个接收一个任意类型元素并且返回一个该类型的一维数组的函数：

PG_FUNCTION_INFO_V1(make_array);
Datum
make_array(PG_FUNCTION_ARGS)
{
    ArrayType  *result;
    Oid         element_type = get_fn_expr_argtype(fcinfo->flinfo, 0);
    Datum       element;
    bool        isnull;
    int16       typlen;
    bool        typbyval;
    char        typalign;
    int         ndims;
    int         dims[MAXDIM];
    int         lbs[MAXDIM];

    if (!OidIsValid(element_type))
        elog(ERROR, "could not determine data type of input");

    /* 得到提供的元素，小心它为 NULL 的情况 */
    isnull = PG_ARGISNULL(0);
    if (isnull)
        element = (Datum) 0;
    else
        element = PG_GETARG_DATUM(0);

    /* 只有一个维度 */
    ndims = 1;
    /* 和一个元素 */
    dims[0] = 1;
    /* 且下界是 1 */
    lbs[0] = 1;

    /* 得到该元素类型所需的信息 */
    get_typlenbyvalalign(element_type, &typlen, &typbyval, &typalign);

    /* 现在构建数组 */
    result = construct_md_array(&element, &isnull, ndims, dims, lbs,
                                element_type, typlen, typbyval, typalign);

    PG_RETURN_ARRAYTYPE_P(result);
}

下面的命令在 SQL 中声明函数make_array：

CREATE FUNCTION make_array(anyelement) RETURNS anyarray
    AS 'DIRECTORY/funcs', 'make_array'
    LANGUAGE C IMMUTABLE;

有一种只对 C 语言函数可用的多态变体：它们可以被声明为接受类型为 "any"的参数（注意这种类型名必须用双引号引用，因为它也是一个 SQL 保留字）。这和anyelement相似，不过它不约束不同的"any"参数为同一种类型，它们也不会帮助确定函数的结果类型。C 语言函数也能声明它的第一个参数为 VARIADIC "any"。这可以匹配一个或者多个任意类型的实参（不需要是同一种类型）。这些参数不会像普通 variadic 函数那样被收集到一个数组中，它们将被单独传递给该函数。使用这种特性时，必须用PG_NARGS()宏以及上述方法来判断实参的个数和类型。还有，这种函数的用户可能希望在他们的函数调用中使用 VARIADIC关键词，以期让该函数将数组元素作为单独的参数对待。如果想要这样，在使用get_fn_expr_variadic检测被标记为VARIADIC的实参之后，函数本身必须实现这种行为。

36.9.11. 转换函数

一些函数调用可以在规划期间基于该函数的特定的属性被简化。例如， int4mul(n, 1)可以被简化为n。要定义这种与函数相关的优化，可以写一个转换函数并且将其 OID 放在主函数的pg_proc项的 protransform域中。该转换函数必须具有 SQL 式样 protransform(internal) RETURNS internal。其参数（实际是FuncExpr *）是一个表示对主函数调用的伪节点。如果该转换函数对表达式树的研究证明一个简化的表达式树能够替代所有可能的具体调用，则会构造并且返回简化的表达式。否则会返回一个 NULL指针（不是一个 SQL 空值）。

我们不保证PostgreSQL在转换函数可以进行简化的情况下绝不会调用主函数。要保证简化后的表达式和对主函数的一次实际调用是严格等价的。

当前，由于安全性的考虑，这种功能没有在 SQL 层面上显示给用户。因此，这种功能实际只用于优化内建函数。

36.9.12. 共享内存和 LWLock

外接程序可以在服务器启动时保留 LWLock 和共享内存。必须通过在shared_preload_libraries 中指定外接程序的共享库来预先载入它。从_PG_init 函数中调用

void RequestAddinShmemSpace(int size)

可以保留共享内存。

通过从_PG_init中调用

void RequestNamedLWLockTranche(const char *tranche_name, int num_lwlocks)

可以保留 LWLock。这将确保一个名为tranche_name 的 LWLock 数组可用，该数组的长度为num_lwlocks。使用GetNamedLWLockTranche可得到该数组的指针。

为了避免可能的竞争情况，在连接并且初始化共享内存时，每一个后端应该使用 LWLock AddinShmemInitLock，如下所示：

static mystruct *ptr = NULL;

if (!ptr)
{
        bool    found;

        LWLockAcquire(AddinShmemInitLock, LW_EXCLUSIVE);
        ptr = ShmemInitStruct("my struct name", size, &found);
        if (!found)
        {
                initialize contents of shmem area;
                acquire any requested LWLocks using:
                ptr->locks = GetNamedLWLockTranche("my tranche name");
        }
        LWLockRelease(AddinShmemInitLock);
}

36.9.13. 把 C++ 用于可扩展性

尽管PostgreSQL后端是用 C 编写的，只要遵循下面的指导方针也可以用 C++ 编写扩展：

所有被后端访问的函数必须对后端呈现一种 C 接口，然后这些 C 函数调用 C++ 函数。例如，对后端访问的函数要求extern C 链接。对需要在后端和 C++ 代码之间作为指针传递的任何函数也要这样做。
使用合适的释放方法释放内存。例如，大部分后端内存是通过 palloc()分配的，所以应使用pfree() 来释放。在这种情况中使用 C++ 的delete会失败。
防止异常传播到 C 代码中（在所有extern C函数的顶层使用一个捕捉全部异常的块）。即使 C++ 代码不会显式地抛出任何异常也需要这样做，因为类似内存不足等事件仍会抛出异常。任何异常都必须被捕捉并且用适当的错误传回给 C 接口。如果可能，用 -fno-exceptions 来编译 C++ 以完全消灭异常。在这种情况下，你必须在 C++ 代码中检查失败，例如检查new() 返回的 NULL。
如果从 C++ 代码调用后端函数，确定 C++ 调用栈值包含传统 C 风格的数据结构（POD）。这是必要的，因为后端错误会产生远距离的longjmp()，它无法正确的退回具有非 POD 对象的 C++ 调用栈。

总之，最好把 C++ 代码放在与后端交互的extern C函数之后，并且避免异常、内存和调用栈泄露。

PostgreSQL

36.9. C 语言函数