Returning values from your functions to PHP was described briefly
in an earlier section; this section gives the details. Return
values are passed via the return_value variable,
which is passed to your functions as argument. The
return_value argument consists of a
zval container (see the earlier discussion of the
call interface) that you can freely modify. The container itself is
already allocated, so you don't have to run
MAKE_STD_ZVAL on it. Instead, you can access its
To make returning values from functions easier and to prevent
hassles with accessing the internal structures of the
zval container, a set of predefined macros is
available (as usual). These macros automatically set the
correspondent type and value, as described in
Table 46-14 and Table 46-15.
The macros in Table 46-14 automatically
return from your function, those in
Table 46-15 only set
the return value; they don't return from your function.
Table 46-14. Predefined Macros for Returning Values from a
|RETURN_RESOURCE(resource)||Returns a resource.|
|RETURN_BOOL(bool)||Returns a Boolean.|
|RETURN_NULL()||Returns nothing (a NULL value).|
|RETURN_LONG(long)||Returns a long.|
|RETURN_DOUBLE(double)||Returns a double.|
Returns a string. The duplicate flag indicates
whether the string should be duplicated using
RETURN_STRINGL(string, length, duplicate)
Returns a string of the specified length; otherwise, behaves
like RETURN_STRING. This macro is faster
and binary-safe, however.
|RETURN_EMPTY_STRING()||Returns an empty string.|
|RETURN_FALSE||Returns Boolean false.|
|RETURN_TRUE||Returns Boolean true.|
Table 46-15. Predefined Macros for Setting the Return Value
of a Function
|RETVAL_RESOURCE(resource)||Sets the return value to the specified
|RETVAL_BOOL(bool)||Sets the return value to the specified
|RETVAL_NULL||Sets the return value to NULL.|
Sets the return value to the specified long.
Sets the return value to the specified double.
Sets the return value to the specified string and duplicates
it to Zend internal memory if desired (see also
RETVAL_STRINGL(string, length, duplicate)
Sets the return value to the specified string and forces the
length to become length (see also
RETVAL_STRING). This macro is faster and
binary-safe, and should be used whenever the string length is
Sets the return value to an empty string.
Sets the return value to Boolean false.
Sets the return value to Boolean true.
Complex types such as arrays and objects can be returned by using
object_init(), as well as the corresponding hash
functions on return_value. Since these types cannot
be constructed of trivial information, there are no predefined
macros for them.