9.5. C 语言函数

9.5.1. 动态装载

当某个特定的可装载对象文件里的用户定义的函数第一次被后端会话调用 时，动态装载器把函数的目标码装载入内存。 因此，用于用户定义的 C 函数的 CREATE FUNCTION必须为函数声明两部分信息： 可装载对象文件名字，和所声明的在那个目标文件里调用的函数的 C名字（联接符号）．如果没有明确声明C名字，那么就假设它与SQL函数 名相同．

基于在 CREATE FUNCTION 命令中给出的名字, 下面的算法用于定位共享对象文件∶

1. 如果名字是一个绝对路径名，则装载给出的文件．

2. 如果名字以字串 $libdir 开头， 那么该部分将被PostgreSQL库目录名代替， 该目录是在制作的时候判定的．

3. 如果名字不包含目录部分，那么在配置变量 dynamic_library_path 里声明的路径里查找．

4. 否则(没有在路径里找到该文件，或者它包含一个非绝对目录部分)， 那么动态装载器就会试图拿这个名字来装载，这样几乎可以肯定是 要失败的．(依靠当前工作目录是不可靠的．)

如果这个顺序不管用，那么就给这个给出的名字附加上 平台相关的共享库文件名扩展(通常是 .so)， 然后再重新按照上面的过程来一便．如果还是失败，那么装载失败．

在任何情况下，在 CREATE FUNCTION 命令里给出的文件名是在系统表里按照文本记录的，因此， 如果需要再次装载，那么会再次运行这个过程．

我们建议使用与 $libdir 相对的目录或者 通过动态库路径定位共享库．这样，如果新版本安装在一个不同的 位置，那么就可以简化版本升级．

9.5.2. 基本类型的 C 语言函数

表Table 9-1 列出了被装载入PostgreSQL的 C 函数里需要的当作参数的 C 类型。 "定义在" 列给出了等效的 C 类型定义的实际的头文件 (实际的定义可能是在包含在列出的文件所包含的文件中． 我们建议用户只使用这里定义的接口．) 注意，你应该总是首先包括postgres.h， 因为它声明了许多你需要的东西．

PostgreSQL 内部把基本类型当作"一片内存"看待． 定义在某种类型上的用户定义函数实际上定义了 PostgreSQL 对（该数据类型） 可能的操作．也就是说， PostgreSQL 只是从磁盘读取和存储该数据类型， 而使用你定义的函数来输入，处理和输出数据．基本 类型可以有下面三种内部形态（格式）之一：

• 传递数值，定长（pass by value, fixed-length）

• 传递引用，定长（pass by reference, fixed-length）

• 传递引用，变长（pass by reference, variable-length）

传递数值的类型的长度只能是1，2 或 4 字节． （还有 8 字节，如果 sizeof(Datum) 在你的机器上是 8 的话．）． 你要仔细定义你的类型， 确保它们在任何体系平台上都是相同尺寸（字节）． 例如， long 型是一个危险 的类型因为在一些机器上它是 4 字节而在另外一些机器上是 8 字节，而 int型在大多数 Unix 机器上都是4字节的（尽管不是 在多数个人微机上）．在一个 Unix 机器上的 integer合理的实现可能是：

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

另外，任何尺寸的定长类型都可以是传递引用型．例如，下面是一个 PostgreSQL 类型的实现：

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

只能使用指向这些类型的指针来在 PostgreSQL 函数里输入和输出． 要返回这样的类型的值，用 palloc() 分配正确数量的存储器，填充这些存储器，然后返回一个指向它的指针． (另外，你可以通过返回指针的方法返回一个与输入数据同类型的值． 但是，绝对不要 修改传递引用的输入数值．)

最后，所有变长类型同样也只能通过传递引用的方法来传 递．所有变长类型必须以一个4字节长的长度域开始， 并且所有存储在该类型的数据必须放在紧接着长度域的存储空间里． 长度域是结构的全长（也就是说，包括长度域本身的长度）． 我们可以用下面方法定义一个 text 类型：

typedef struct {
    integer length;
    char data[1];
} text;

显然，上面声明的数据域的长度不足以存储任何可能的字串．因为在 C中不可能声明变长度的结构， 所以我们倚赖这样的知识∶C 编译器不会对数组 下标金星范围检查．我们只需要分配足够的空间，然后把数组当做已经 声明为合适长度的变量访问．(如果你不熟悉这个技巧，那么你在开始 深入 PostgreSQL 服务器编程之前可能需要 花点时间阅读一些 C 编程的介绍性读物．) 当处理变长类型时，我们必须仔细 分配正确的存储器数量并正确设置长度域． 例如，如果我们想在一个 text 结构里存储 40 字节， 我们可能会使用象下面的代码片段：

#include "postgres.h"
...
char buffer[40]; /* 我们的源数据 */
...
text *destination = (text *) palloc(VARHDRSZ + 40);
destination->length = VARHDRSZ + 40;
memcpy(destination->data, buffer, 40);
...

VARHDRSZ 和 sizeof(int4) 一样， 但是我们认为用宏 VARHDRSZ 表示附加尺寸是用于变长类型的 更好的风格．

既然我们已经讨论了基本类型所有的可能结构， 我们便可以用实际的函数举一些例子．

9.5.3. C 语言函数的版本-0 调用风格

我们先提供"老风格"的调用风格 --- 尽管这种做法现在已经不提倡了， 但它还是比较容易迈出第一步．在版本-0方法里，C函数的参数和 结果只是用普通C风格声明，但是要小心使用上面显示的SQL数据类型 的C表现形式．

下面是一些例子：

#include "postgres.h"
#include <string.h>

/* 传递数值 */
         
int
add_one(int arg)
{
    return arg + 1;
}

/* 传递引用，定长 */

double precision *
add_one_double precision(double precision *arg)
{
    double precision    *result = (double precision *) palloc(sizeof(double precision));

    *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));
    VARATT_SIZEP(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);

    VARATT_SIZEP(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 'PGROOT/tutorial/funcs' LANGUAGE C
     WITH (isStrict);

-- 注意：重载了名字为 add_one() 的 SQL 函数
CREATE FUNCTION add_one(float8) RETURNS float8
     AS 'PGROOT/tutorial/funcs',
        'add_one_float8'
     LANGUAGE C WITH (isStrict);

CREATE FUNCTION makepoint(point, point) RETURNS point
     AS 'PGROOT/tutorial/funcs' LANGUAGE C
     WITH (isStrict);
                         
CREATE FUNCTION copytext(text) RETURNS text
     AS 'PGROOT/tutorial/funcs' LANGUAGE C
     WITH (isStrict);

CREATE FUNCTION concat_text(text, text) RETURNS text
     AS 'PGROOT/tutorial/funcs' LANGUAGE C
     WITH (isStrict);

这里的 PGROOT 代表 PostgreSQL 源代码的全路径． (更好的风格应该是在向搜索路径里增加 PGROOT/tutorial 之后，在 AS 子句里只使用 'funcs'， 不管怎样，我们都可以省略和系统相关的共享库扩展， 通常是 .so 或 .sl．)

请注意我们把函数声明为"strict"（严格），意思是说如果任何输入值为NULL， 那么系统应该自动假设一个NULL的结果．这样处理可以让我们避免在 函数代码里面检查NULL输入．如果不这样处理，我们就得明确检查空值， 比如为每个传递引用的参数检查空指针．（对于传值类型的参数，我们 甚至没有办法检查！）

尽管这种老风格的调用风格用起来简单，它确不太容易移植；在一些系统上， 我们用这种方法传递比 int 小的数据类型就会碰到困难．而且，我们 没有很好的返回NULL结果的办法，也没有除了把函数严格化以外的处理 NULL参数的方法． 下面要讲的版本-1的方法则解决了这些问题．

9.5.4. C语言函数的版本-1调用风格

版本-1调用风格依赖宏来消除大多数传递参数和结果的复杂性．版本-1风格函数的 C定义总是下面这样

                Datum funcname(PG_FUNCTION_ARGS)

另外，下面的宏

                PG_FUNCTION_INFO_V1(funcname);

也必须出现在同一个源文件里（通常就可以写在函数自身前面）． 对那些"内部"-语言函数而言，不需要调用这个宏， 因为PostgreSQL目前假设内部函数都是版本-1． 不过，对于动态链接的函数，它是必须的．

在版本-1函数里， 每个实际参数都是用一个对应该参数的数据类型的 PG_GETARG_xxx()宏 抓取的，结果是用返回类型的 PG_RETURN_xxx()宏返回的．

下面是和上面一样的函数，但是是用新风格编的：

#include "postgres.h"
#include <string.h>
#include "fmgr.h"

/* 传递数值 */

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_double precision);

Datum
add_one_double precision(PG_FUNCTION_ARGS)
{
    /* 用于 FLOAT8 的宏，隐藏其传递引用的本质 */
    double precision   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));
    VARATT_SIZEP(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);

    VARATT_SIZEP(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);
}

用到的 CREATE FUNCTION 命令和用于老风格的等效的命令一样．

猛地一看，版本-1的编码好象只是无目的地蒙人．但是它们的确给我们 许多改进，因为宏可以隐藏许多不必要的细节． 一个例子在add_one_float8的编码里，这里我们不再需要不停叮嘱自己 float8是传递引用类型．另外一个例子是用于变长类型的宏 GETARG隐藏 了抓取"toasted"（烤炉）（压缩的或者超长的）值需要做的处理． 上面显示的老风格的 copytext和 concat_text函数在处理 toasted 的值的时候 实际上是错的，因为它们在处理输入时没有调用 pg_detoast_datum()． (用于老风格动态装载函数的句柄现在会处理这些细节， 不过与版本-1函数的所有可能性相比，它做的实在是不够充分．)

版本-1的函数另一个巨大的改进是对 NULL 输入和结果的处理． 宏 PG_ARGISNULL(n) 允许一个函数测试每个输入 是否为 NULL (当然，这件事只是对那些没有声明为 "strict" 的函数有必要)．因为如果有PG_GETARG_xxx() 宏，输入参数是从零开始计算的．请注意我们不应该执行 PG_GETARG_xxx()， 除非有人声明了参数不是 NULL． 要返回一个 NULL 结果，执行一个 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指定．存储类型是 plain，external，extended 或 main 之一．)

版本-1的函数调用风格也令我们可能返回一"套" 结果并且实现触发器函数和过程语言调用句柄．版本-1的代码 也比版本-0的更容易移植，因为它没有违反 ANSI C 对函数调用 协议的限制．更多的细节请参阅 源程序中的src/backend/utils/fmgr/README．

9.5.5. 复合类型的 C 语言函数

复合类型不象 C 结构那样有固定的布局． 复合类型的记录可能包含空（null）域． 另外，一个属于继承层次一部分的复合类 型可能和同一继承范畴的其他成员有不同的域/字段． 因此， PostgreSQL 提供一个过程接口用于从 C 里面访问复合类型．在 PostgreSQL 处理一个记录集时， 每条记录都将作为一个类型为 TUPLE(元组) 的不透明（opaque）的结构被传递给你的函数． 假设我们 为下面查询写一个函数

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

在上面的查询里，我们可以这样定义c_overpaid：

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

bool
c_overpaid(TupleTableSlot *t, /* the current row of EMP */
           int32 limit)
{
    bool isnull;
    int32 salary;

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

/* 以版本-1编码，上面的东西会写成下面这样：*/

PG_FUNCTION_INFO_V1(c_overpaid);

Datum
c_overpaid(PG_FUNCTION_ARGS)
{
    TupleTableSlot  *t = (TupleTableSlot *) PG_GETARG_POINTER(0);
    int32            limit = PG_GETARG_INT32(1);
    bool isnull;
    int32 salary;

    salary = DatumGetInt32(GetAttributeByName(t, "salary", &isnull));
    if (isnull)
        PG_RETURN_BOOL(false);
    /* 另外，我们可能更希望将 PG_RETURN_NULL() 用在空薪水上 */

    PG_RETURN_BOOL(salary > limit);
}

GetAttributeByName 是 PostgreSQL 系统函数， 用来返回当前记录的字段． 它有三个参数：类型为 TupleTableSlot* 的传入函数 的参数，你想要的字段名称， 以及一个用以确定字段是否为空（null）的返回参数． GetAttributeByName 函数返回一个Datum值， 你可以用对应的 DatumGetXXX() 宏把它转换成合适的数据类型．

下面的命令让 PostgreSQL 知道c_overpaid函数：

CREATE FUNCTION c_overpaid(emp, integer) 
RETURNS bool
AS 'PGROOT/tutorial/funcs' 
LANGUAGE C;

9.5.6. 表函数 API

表函数 API 帮助我们创建用户定义的 C 语言表函数（Section 9.7）。 表函数都是生成一个行集合的函数，这些行要么是由基本（标量）数据类型， 要么是由复合（多字段）数据类型组成。API 分隔为两个主要部件： 支持返回复合数据类型的，以及支持返回多行的（返回集合的函数或者SRF (set returning function)）。

表函数 API 宏和函数来消除大多数制作复合数据类型和返回多个结果的复杂性。 一个表函数必须遵循上面描述的版本－1的调用规则。另外，源文件必须包含：

#include "funcapi.h"

typedef struct AttInMetadata
{
    /* 完整的 TupleDesc */
    TupleDesc       tupdesc;

    /* 输入函数属性 finfo 类型数组 */
    FmgrInfo       *attinfuncs;

    /* 属性 typelem 类型数组 */
    Oid            *attelems;

    /* 属性 typmod 类型数组 */
    int32        *atttypmods;
}     AttInMetadata;

TupleDesc RelationNameGetTupleDesc(const char *relname)

TupleDesc TypeGetTupleDesc(Oid typeoid, List *colaliases)

AttInMetadata *TupleDescGetAttInMetadata(TupleDesc tupdesc)

TupleTableSlot *TupleDescGetSlot(TupleDesc tupdesc)

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

TupleGetDatum(TupleTableSlot *slot, HeapTuple tuple)

typedef struct
{
    /*
     * 我们前面已经被调用的次数
     *
     * 初始的时候，call_cntr 被 SRF_FIRSTCALL_INIT() 置为里 0，并且
     * 每次你调用 SRF_RETURN_NEXT() 的时候都递增
     */
    uint32 call_cntr;

    /*
     * 可选的最大调用数量
     *
     * 这里的 max_calls 只是为了方便，设置它也是可选的
     * 如果没有设置，你必须提供可选的方法来知道函数何时结束
     * 
     */
    uint32 max_calls;

    /*
     * 指向结果槽位的可选指针
     *
     * 槽位是在返回元组的时候使用的（也就是说，返回复合数据类型）
     * 如果返回基本类型（也就是说，标量），是不需要的
     */
    TupleTableSlot *slot;

    /*
     * 可选的指向用户提供的杂项环境信息的指针
     *
     * user_fctx 用做一个指向你自己的结构的指针，包含任意提供给你的函数的调用间的环境信息
     * 
     */
    void *user_fctx;

    /*
     * 可选的指向包含属性类型输入元信息的结构数组的指针
     * 
     *
     * attinmeta 用于在返回元组的时候（也就是说返回复合数据类型）
     * 在只返回基本（也就是标量）数据类型的时候并不需要。
     * 只有在你准备用 BuildTupleFromCStrings() 创建返回元组的时候才需要它
     * 
     */
    AttInMetadata *attinmeta;

    /*
     * 用于必须在多次调用间存活的结构的内存环境
     *
     * multi_call_memory_ctx 是由 SRF_FIRSTCALL_INIT() 为你设置的，并且由
     * SRF_RETURN_DONE() 用于清理。它是用于存放任何需要跨越多次调用 SRF 之间重复使用的内存
     * 
     * 
     */
    MemoryContext multi_call_memory_ctx;
} FuncCallContext;

SRF_IS_FIRSTCALL()

SRF_FIRSTCALL_INIT()

SRF_PERCALL_SETUP()

SRF_RETURN_NEXT(funcctx, result)

SRF_RETURN_DONE(funcctx)

Datum
my_Set_Returning_Function(PG_FUNCTION_ARGS)
{
    FuncCallContext  *funcctx;
    Datum             result;
    MemoryContext     oldcontext;
    [user defined declarations]

    if (SRF_IS_FIRSTCALL())
    {
        funcctx = SRF_FIRSTCALL_INIT();
        oldcontext = MemoryContextSwitchTo(funcctx->multi_call_memory_ctx);
        /* 这里放出现一次的设置代码：*/
        [用户定义代码]
        [if 返回复合]
            [制作 TupleDesc，以及可能还有 AttInMetadata]
            [获取槽位]
            funcctx->slot = slot;
        [endif 返回复合]
        [用户定义代码]
        MemoryContextSwitchTo(oldcontext);
    }

    /* 每次都执行的设置代码在这里出现：*/
    [用户定义代码]
    funcctx = SRF_PERCALL_SETUP();
    [用户定义代码]

    /* 这里只是用来测试我们是否完成的一个方法：*/
    if (funcctx->call_cntr < funcctx->max_calls)
    {
        /* 这里我们想返回另外一个条目：*/
         [user defined code]
         [obtain result Datum]
         SRF_RETURN_NEXT(funcctx, result);
     }
     else
     {
         /* 这里我们完成返回条目的工作了，只需要清理就OK了：*/
         [user defined code]
         SRF_RETURN_DONE(funcctx);
     }
 }
 

 PG_FUNCTION_INFO_V1(testpassbyval);
 Datum
 testpassbyval(PG_FUNCTION_ARGS)
 {
     FuncCallContext     *funcctx;
     int                  call_cntr;
     int                  max_calls;
     TupleDesc            tupdesc;
     TupleTableSlot       *slot;
     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);

         /*
          * 为 __testpassbyval 元组制作一个元组描述
          */
         tupdesc = RelationNameGetTupleDesc("__testpassbyval");

         /* 用这个 tupdesc 为一个元组分配槽位 */
         slot = TupleDescGetSlot(tupdesc);

         /* 将槽位赋予给函数环境 */
         funcctx->slot = slot;

         /*
          * 生成稍后从裸 C 字串生成元组的属性元数据
          * 
          */
         attinmeta = TupleDescGetAttInMetadata(tupdesc);
         funcctx->attinmeta = attinmeta;

         MemoryContextSwitchTo(oldcontext);
     }

     /* 每次函数调用都要做的事情 */
     funcctx = SRF_PERCALL_SETUP();

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

     if (call_cntr < max_calls)    /* 在还有需要发送的东西时继续处理 */
     {
         char       **values;
         HeapTuple    tuple;
         Datum        result;

         /*
          * 准备一个数值数组用于在我们的槽位中存储。
          * 它应该是一个 C 字串数组，稍后可以被合适的“in”函数处理。
          * 
          */
         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 = TupleGetDatum(slot, tuple);

         /* 清理（这些时间上并非必要） */
         pfree(values[0]);
         pfree(values[1]);
         pfree(values[2]);
         pfree(values);

          SRF_RETURN_NEXT(funcctx, result);
     }
     else    /* 在没有数据残留的时候干的事情 */
     {
          SRF_RETURN_DONE(funcctx);
     }
 }
 

 CREATE TYPE __testpassbyval AS (f1 int4, f2 int4, f3 int4);

 CREATE OR REPLACE FUNCTION testpassbyval(int4, int4) RETURNS setof __testpassbyval
   AS 'MODULE_PATHNAME','testpassbyval' LANGUAGE 'c' IMMUTABLE STRICT;
 

9.5.7. 书写代码

我们现在转到了书写编程语言函数的更艰难的阶段． 要注意：本手册此章的内容不会让你成为程序员． 在你尝试用C 书写用于 PostgreSQL 的函数之前，你必须对 C 有很深的了解（包括对指针的使用）． 虽然可以用 C 以外的其他语 言如 FORTRAN 和 Pascal 书写用于PostgreSQL 的共享函数，但通常很麻烦（虽然是完全可能的），因为其他语言并不遵循和 C 一样的 调用习惯． 其他语言与C的传递参数和返回值的方式不一样． 因此我们假设你的编程语言函数是用 C 写的．

制作 C 函数的基本规则如下：

• 使用 pg_config --includedir-server 找出PostgreSQL服务器的头文件安装在你的系统 (或者是你的用户所运行的系统)的何处． 这个选项是PostgreSQL7.2 新增的．对于 PostgreSQL7.1， 你应该使用选项 --includedir． (如果碰到未知选项，pg_config 将带着非零 状态退出．)对于早于 7.1 的版本，你就只能自己猜了， 但是因为那是在引入目前的调用方式之前，所以你不大可能会去支持 那些版本．

• 当分配存储器时，用 PostgreSQL 的函数palloc和 pfree 取代相应的 C 库函数 malloc和free． 用palloc分配的存储器在每个事 务结束时会自动释放，避免了内存泄露．

• 记得用memset或bzero 对你的结构清零． 有些函数（像 hash （散列）访问方法，hash （散列）联合和排序算法）计 算包含在你的结构里的裸位（row bit）．即使你初始化了你的结构的所有域， 仍然有可能有几个对齐字节（结构中的 洞）含有垃圾值．

• 大多数的 PostgreSQL 内部类型定义在 postgres.h， 而函数管理器接口(PG_FUNCTION_ARGS 等等．) 都在 fmgr.h，所以你至少应该包括这两个 文件．出于移植性原因，最好先包括 postgres.h，然后再包括其它系统或者用户 头文件． 包含了 postgres.h 将自动包含 c.h， elog.h 和 palloc.h．

• 在目标文件里定义的符号一定不能相互冲突，也不能和定义在 PostgreSQL 服务器可执行代码 中的符号名字冲突．如果你看到了与此相关的错误信息，那么 你必须给你的函数或者变量重命名．

• 把你的目标码编译和装载成可以动态装入 PostgreSQL 的库文件总是需要一些特殊的标记。参阅 Section 9.5.8 获取如 何在你的平台上做这件事的详细说明。

9.5.8. 编译和链接动态链接的函数

在你能够使用由 C 写的 PostgreSQL 扩展函数之前，你必须 用一种特殊的方法编译和链接它们，这样才能生成可以被服务器 动态地装载的文件．准确地说，我们需要创建一个 共享库．

如果需要更都的信息，那么你应该阅读你的操作系统的文档， 特别是 C 编译器，cc 和链接器， ld 的手册页． 另外，PostgreSQL 源代码里包含几个 可以运行的例子，它们在 contrib 目录里． 不过，如果你依赖这些例子，那么你就要把自己的模块做得和 PostgreSQL 源代码无关才行．

创建共享库和链接可执行文件类似：首先把源代码编译成目标文件， 然后把目标文件链接起来．目标文件需要创建成 位置无关码（position-independent code） （PIC），概念上就是在可执行程序装载它们的时候， 它们可以放在可执行程序的内存里的任何地方， （用于可执行文件的目标文件通常不是用这个方式编译的．） 链接动态库的命令包含特殊标志，与链接可执行文件的命令是有区别的． --- 至少理论上如此．在一些系统里的现实更恶心．

在下面的例子里，我们假设你的源程序代码在 foo.c 文件里并且将创建成名字叫 foo.so的共享库．中介的对象文件将叫做 foo.o，除非我们另外注明．一个共享库可以 包含多个对象文件，不过我们在这里只用一个．

生成的共享库文件然后就可以装载到 PostgreSQL里面去了．在给 CREATE FUNCTION 命令声明文件名的时候，我们必须声明 共享库文件的名字而不是中间目标文件的名字．请注意你可以在 CREATE FUNCTION 命令上忽略 系统标准的共享库扩展 (通常是.so或.sl)， 并且出于最佳的兼容性考虑也应该忽略．

回去看看 Section 9.5.1 获取有关服务器 预期在哪里找到共享库的信息．