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.