How can Perl's XSUB die?

Question

I have written a Perl XS wrapper for a C library consisting of about ~80 functions. Right now my general strategy is to substitute the error from a C function with PL_sv_undef and the calling Perl code has to check explicitly whether the return is not undef. (For some C functions it is more complicated as I convert their output into a HV/AV and use empty list to report the error.)

Now as I moved to writing bigger Perl scripts using that library, I want to simplify the error handling and use e.g. the usual eval {}/die exception-like mechanism to handle errors.

At the moment a simple XSUB in my XS look like that:

SV *
simple_function( param1, param2 = 0, param3 = 0)
        int             param1
        int             param2
        int             param3
        CODE:
                int rc;
                rc = simple_function( param1, param2, param3 );
                RETVAL = (rc == 0) ? &PL_sv_yes : &PL_sv_undef;
        OUTPUT:
                RETVAL

I have seen that some modules have global flag like "RaiseError" to die on errors but failed to find any example I can borrow from. The few modules I have found handle the "RaiseError" flag inside the .pm, not inside the .xs, and thus allowed to use the Perl's die. In my case that is rather hard to implement inside the .pm as many functions require special error checks. That would also lead to code duplication as the checks are already present inside the XS.

I found nothing relevant in the perlxs/perlguts documentation. In particular, I have seen calls to Perl_croak() in the .c generated from my .xs, but failed to locate any documentation for the function.

What is the XS' analog of the Perl's die? Or how else can the XSUB report to Perl run-time that the function has failed and there is no RETVAL to return? How to properly set the $@?

Answer 1

Perl_croak() is documented here on the perlapi man page. As the example on that page shows, you can either pass it a message string, or you can manually set $@ to an exception object and pass NULL.