|
In the list of parameters for an XSUB, one can precede parameter names by the IN/OUTLIST/IN_OUTLIST/OUT/IN_OUT
keywords. IN keyword is the default, the other keywords indicate how the Perl
interface should differ from the C interface.
Parameters preceded by OUTLIST/IN_OUTLIST/OUT/IN_OUT
keywords are considered to be used by the C subroutine via pointers. OUTLIST/OUT
keywords indicate that the C subroutine does not inspect the memory pointed by this parameter,
but will write through this pointer to provide additional return values.
Parameters preceded by OUTLIST keyword do not appear in the usage signature of
the generated Perl function.
Parameters preceded by IN_OUTLIST/IN_OUT/OUT do
appear as parameters to the Perl function. With the exception of OUT-parameters,
these parameters are converted to the corresponding C type, then pointers to these data are
given as arguments to the C function. It is expected that the C function will write through
these pointers.
The return list of the generated Perl function consists of the C return value from the
function (unless the XSUB is of void return type or The NO_OUTPUT Keyword
was used) followed by all the OUTLIST and IN_OUTLIST parameters (in
the order of appearance). On the return from the XSUB the IN_OUT/OUT
Perl parameter will be modified to have the values written by the C function.
For example, an XSUB
void
day_month(OUTLIST day, IN unix_time, OUTLIST month)
int day
int unix_time
int month
|
|
should be used from Perl as
my ($day, $month) = day_month(time);
|
|
The C signature of the corresponding function should be
void day_month(int *day, int unix_time, int *month);
|
|
The IN/OUTLIST/IN_OUTLIST/IN_OUT/OUT
keywords can be mixed with ANSI-style declarations, as in
void
day_month(OUTLIST int day, int unix_time, OUTLIST int month)
|
|
(here the optional IN keyword is omitted).
The IN_OUT parameters are identical with parameters introduced with The & Unary Operator and put into the OUTPUT:
section (see The OUTPUT: Keyword). The IN_OUTLIST
parameters are very similar, the only difference being that the value C function writes
through the pointer would not modify the Perl parameter, but is put in the output list.
The OUTLIST/OUT parameter differ from IN_OUTLIST/IN_OUT
parameters only by the initial value of the Perl parameter not being read (and not being given
to the C function - which gets some garbage instead). For example, the same C function as
above can be interfaced with as
void day_month(OUT int day, int unix_time, OUT int month);
|
|
or
void
day_month(day, unix_time, month)
int &day = NO_INIT
int unix_time
int &month = NO_INIT
OUTPUT:
day
month
|
|
However, the generated Perl function is called in very C-ish style:
my ($day, $month);
day_month($day, time, $month);
|
|
|
|
