THE PERL_CALL FUNCTIONS

Although this stuff is easier to explain using examples, you first need be aware of a few important definitions.

Perl has a number of C functions that allow you to call Perl subroutines. They are

I32 perl_call_sv(SV* sv, I32 flags) ;
I32 perl_call_pv(char *subname, I32 flags) ;
I32 perl_call_method(char *methname, I32 flags) ;
I32 perl_call_argv(char *subname, I32 flags, register char **argv) ;

The key function is perl_call_sv. All the other functions are fairly simple wrappers which make it easier to call Perl subroutines in special cases. At the end of the day they will all call perl_call_sv to invoke the Perl subroutine.

All the perl_call_* functions have a flags parameter which is used to pass a bit mask of options to Perl. This bit mask operates identically for each of the functions. The settings available in the bit mask are discussed in FLAG VALUES.

Each of the functions will now be discussed in turn.

perl_call_sv

perl_call_sv takes two parameters, the first, sv, is an SV*. This allows you to specify the Perl subroutine to be called either as a C string (which has first been converted to an SV) or a reference to a subroutine. The section, Using perl_call_sv, shows how you can make use of perl_call_sv.

perl_call_pv

The function, perl_call_pv, is similar to perl_call_sv except it expects its first parameter to be a C char* which identifies the Perl subroutine you want to call, e.g., perl_call_pv("fred", 0). If the subroutine you want to call is in another package, just include the package name in the string, e.g., "pkg::fred".

perl_call_method

The function perl_call_method is used to call a method from a Perl class. The parameter methname corresponds to the name of the method to be called. Note that the class that the method belongs to is passed on the Perl stack rather than in the parameter list. This class can be either the name of the class (for a static method) or a reference to an object (for a virtual method). See the perlobj manpage for more information on static and virtual methods and Using perl_call_method for an example of using perl_call_method.

perl_call_argv

perl_call_argv calls the Perl subroutine specified by the C string stored in the subname parameter. It also takes the usual flags parameter. The final parameter, argv, consists of a NULL terminated list of C strings to be passed as parameters to the Perl subroutine. See Using perl_call_argv.

All the functions return an integer. This is a count of the number of items returned by the Perl subroutine. The actual items returned by the subroutine are stored on the Perl stack.

As a general rule you should always check the return value from these functions. Even if you are expecting only a particular number of values to be returned from the Perl subroutine, there is nothing to stop someone from doing something unexpected - don't say you haven't been warned.