|
The RETVAL variable is a special C variable that is declared automatically for you. The C
type of RETVAL matches the return type of the C library function. The xsubpp compiler
will declare this variable in each XSUB with non-void return type. By default the
generated C function will use RETVAL to hold the return value of the C library function being
called. In simple cases the value of RETVAL will be placed in ST(0) of the argument stack
where it can be received by Perl as the return value of the XSUB.
If the XSUB has a return type of void then the compiler will not declare a
RETVAL variable for that function. When using a PPCODE: section no manipulation of the RETVAL
variable is required, the section may use direct stack manipulation to place output values on
the stack.
If PPCODE: directive is not used, void return value should be used only for
subroutines which do not return a value, even if CODE: directive is used which sets
ST(0) explicitly.
Older versions of this document recommended to use void return value in such
cases. It was discovered that this could lead to segfaults in cases when XSUB was truly
void. This practice is now deprecated, and may be not supported at some future
version. Use the return value SV * in such cases. (Currently xsubpp
contains some heuristic code which tries to disambiguate between "truly-void" and
"old-practice-declared-as-void" functions. Hence your code is at mercy of this
heuristics unless you use SV * as return value.)
|
