Zend API：深入 PHP 内核（十四） 返回函数值

http://yanbin.org/archive/php-manual-zh-returning-values.html

关于扩展内函数到 PHP 脚本的返回值我们前面谈得比较少，这一节我们就来详细说一下。任何函数的返回值都是通过一个名为 return_value 的变量传递的。这个变量同时也是函数中的一个参数。这个参数总是包含有一个事先申请好空间的 zval 容器，因此你可以直接访问其成员并对其进行修改而无需先对 return_value 执行一下 MAKE_STD_ZVAL 宏指令。

为了能够更方便从函数中返回结果，也为了省却直接访问 zval 容器内部结构的麻烦，ZEND 提供了一大套宏命令来完成相关的这些操作。这些宏命令会自动设置好类型和数值。“表3.14 从函数直接返回值的宏”和“表3.15 设置函数返回值的宏”列出了这些宏和对应的说明。

注意：使用“表3.14 从函数直接返回值的宏”会自动携带结果从当前函数返回。而使用“表3.15 设置函数返回值的宏”则只是设置了一下函数返回值，并不会马上返回。

表3.14 从函数直接返回值的宏

宏说明RETURN_RESOURCE(resource)返回一个资源。RETURN_BOOL(bool)返回一个布尔值。RETURN_NULL()返回一个空值。RETURN_LONG(long)返回一个长整数。RETURN_DOUBLE(double)返回一个双精度浮点数。RETURN_STRING(string, duplicate)返回一个字符串。duplicate 表示这个字符是否使用estrdup() 进行复制。RETURN_STRINGL(string, length, duplicate)返回一个定长的字符串。其余跟 RETURN_STRING 相同。这个宏速度更快而且是二进制安全的。RETURN_EMPTY_STRING()返回一个空字符串。RETURN_FALSE返回一个布尔值假。RETURN_TRUE返回一个布尔值真。

表3.15 设置函数返回值的宏

宏说明RETVAL_RESOURCE(resource)设定返回值为指定的一个资源。RETVAL_BOOL(bool)设定返回值为指定的一个布尔值。RETVAL_NULL设定返回值为空值RETVAL_LONG(long)设定返回值为指定的一个长整数。RETVAL_DOUBLE(double)设定返回值为指定的一个双精度浮点数。RETVAL_STRING(string, duplicate)设定返回值为指定的一个字符串，duplicate 含义同RETURN_STRING。RETVAL_STRINGL(string, length, duplicate)设定返回值为指定的一个定长的字符串。其余跟RETVAL_STRING 相同。这个宏速度更快而且是二进制安全的。RETVAL_EMPTY_STRING设定返回值为空字符串。RETVAL_FALSE设定返回值为布尔值假。RETVAL_TRUE设定返回值为布尔值真。

如果需要返回的是像数组和对象这样的复杂类型的数据，那就需要先调用 array_init() 和object_init()，也可以使用相应的 hash 函数直接操作 return_value。由于这些类型主要是由一些杂七杂八的东西构成，所以对它们就没有了相应的宏。