| 1 |
=head1 NAME |
| 2 |
|
| 3 |
perlxstypemap - Perl XS C/Perl type mapping |
| 4 |
|
| 5 |
=head1 DESCRIPTION |
| 6 |
|
| 7 |
The more you think about interfacing between two languages, the more |
| 8 |
you'll realize that the majority of programmer effort has to go into |
| 9 |
converting between the data structures that are native to either of |
| 10 |
the languages involved. This trumps other matter such as differing |
| 11 |
calling conventions because the problem space is so much greater. |
| 12 |
There are simply more ways to shove data into memory than there are |
| 13 |
ways to implement a function call. |
| 14 |
|
| 15 |
Perl XS' attempt at a solution to this is the concept of typemaps. |
| 16 |
At an abstract level, a Perl XS typemap is nothing but a recipe for |
| 17 |
converting from a certain Perl data structure to a certain C |
| 18 |
data structure and vice versa. Since there can be C types that |
| 19 |
are sufficiently similar to one another to warrant converting with |
| 20 |
the same logic, XS typemaps are represented by a unique identifier, |
| 21 |
henceforth called an B<XS type> in this document. You can then tell |
| 22 |
the XS compiler that multiple C types are to be mapped with the same |
| 23 |
XS typemap. |
| 24 |
|
| 25 |
In your XS code, when you define an argument with a C type or when |
| 26 |
you are using a C<CODE:> and an C<OUTPUT:> section together with a |
| 27 |
C return type of your XSUB, it'll be the typemapping mechanism that |
| 28 |
makes this easy. |
| 29 |
|
| 30 |
=head2 Anatomy of a typemap |
| 31 |
|
| 32 |
In more practical terms, the typemap is a collection of code |
| 33 |
fragments which are used by the B<xsubpp> compiler to map C function |
| 34 |
parameters and values to Perl values. The typemap file may consist |
| 35 |
of three sections labelled C<TYPEMAP>, C<INPUT>, and C<OUTPUT>. |
| 36 |
An unlabelled initial section is assumed to be a C<TYPEMAP> section. |
| 37 |
The INPUT section tells the compiler how to translate Perl values |
| 38 |
into variables of certain C types. The OUTPUT section tells the |
| 39 |
compiler how to translate the values from certain C types into values |
| 40 |
Perl can understand. The TYPEMAP section tells the compiler which |
| 41 |
of the INPUT and OUTPUT code fragments should be used to map a given |
| 42 |
C type to a Perl value. The section labels C<TYPEMAP>, C<INPUT>, or |
| 43 |
C<OUTPUT> must begin in the first column on a line by themselves, |
| 44 |
and must be in uppercase. |
| 45 |
|
| 46 |
Each type of section can appear an arbitrary number of times |
| 47 |
and does not have to appear at all. For example, a typemap may |
| 48 |
commonly lack C<INPUT> and C<OUTPUT> sections if all it needs to |
| 49 |
do is associate additional C types with core XS types like T_PTROBJ. |
| 50 |
Lines that start with a hash C<#> are considered comments and ignored |
| 51 |
in the C<TYPEMAP> section, but are considered significant in C<INPUT> |
| 52 |
and C<OUTPUT>. Blank lines are generally ignored. |
| 53 |
|
| 54 |
Traditionally, typemaps needed to be written to a separate file, |
| 55 |
conventionally called C<typemap> in a CPAN distribution. With |
| 56 |
ExtUtils::ParseXS (the XS compiler) version 3.12 or better which |
| 57 |
comes with perl 5.16, typemaps can also be embedded directly into |
| 58 |
XS code using a HERE-doc like syntax: |
| 59 |
|
| 60 |
TYPEMAP: <<HERE |
| 61 |
... |
| 62 |
HERE |
| 63 |
|
| 64 |
where C<HERE> can be replaced by other identifiers like with normal |
| 65 |
Perl HERE-docs. All details below about the typemap textual format |
| 66 |
remain valid. |
| 67 |
|
| 68 |
The C<TYPEMAP> section should contain one pair of C type and |
| 69 |
XS type per line as follows. An example from the core typemap file: |
| 70 |
|
| 71 |
TYPEMAP |
| 72 |
# all variants of char* is handled by the T_PV typemap |
| 73 |
char * T_PV |
| 74 |
const char * T_PV |
| 75 |
unsigned char * T_PV |
| 76 |
... |
| 77 |
|
| 78 |
The C<INPUT> and C<OUTPUT> sections have identical formats, that is, |
| 79 |
each unindented line starts a new in- or output map respectively. |
| 80 |
A new in- or output map must start with the name of the XS type to |
| 81 |
map on a line by itself, followed by the code that implements it |
| 82 |
indented on the following lines. Example: |
| 83 |
|
| 84 |
INPUT |
| 85 |
T_PV |
| 86 |
$var = ($type)SvPV_nolen($arg) |
| 87 |
T_PTR |
| 88 |
$var = INT2PTR($type,SvIV($arg)) |
| 89 |
|
| 90 |
We'll get to the meaning of those Perlish-looking variables in a |
| 91 |
little bit. |
| 92 |
|
| 93 |
Finally, here's an example of the full typemap file for mapping C |
| 94 |
strings of the C<char *> type to Perl scalars/strings: |
| 95 |
|
| 96 |
TYPEMAP |
| 97 |
char * T_PV |
| 98 |
|
| 99 |
INPUT |
| 100 |
T_PV |
| 101 |
$var = ($type)SvPV_nolen($arg) |
| 102 |
|
| 103 |
OUTPUT |
| 104 |
T_PV |
| 105 |
sv_setpv((SV*)$arg, $var); |
| 106 |
|
| 107 |
Here's a more complicated example: suppose that you wanted |
| 108 |
C<struct netconfig> to be blessed into the class C<Net::Config>. |
| 109 |
One way to do this is to use underscores (_) to separate package |
| 110 |
names, as follows: |
| 111 |
|
| 112 |
typedef struct netconfig * Net_Config; |
| 113 |
|
| 114 |
And then provide a typemap entry C<T_PTROBJ_SPECIAL> that maps |
| 115 |
underscores to double-colons (::), and declare C<Net_Config> to be of |
| 116 |
that type: |
| 117 |
|
| 118 |
TYPEMAP |
| 119 |
Net_Config T_PTROBJ_SPECIAL |
| 120 |
|
| 121 |
INPUT |
| 122 |
T_PTROBJ_SPECIAL |
| 123 |
if (sv_derived_from($arg, \"${(my $ntt=$ntype)=~s/_/::/g;\$ntt}\")){ |
| 124 |
IV tmp = SvIV((SV*)SvRV($arg)); |
| 125 |
$var = INT2PTR($type, tmp); |
| 126 |
} |
| 127 |
else |
| 128 |
croak(\"$var is not of type ${(my $ntt=$ntype)=~s/_/::/g;\$ntt}\") |
| 129 |
|
| 130 |
OUTPUT |
| 131 |
T_PTROBJ_SPECIAL |
| 132 |
sv_setref_pv($arg, \"${(my $ntt=$ntype)=~s/_/::/g;\$ntt}\", |
| 133 |
(void*)$var); |
| 134 |
|
| 135 |
The INPUT and OUTPUT sections substitute underscores for double-colons |
| 136 |
on the fly, giving the desired effect. This example demonstrates some |
| 137 |
of the power and versatility of the typemap facility. |
| 138 |
|
| 139 |
The C<INT2PTR> macro (defined in perl.h) casts an integer to a pointer |
| 140 |
of a given type, taking care of the possible different size of integers |
| 141 |
and pointers. There are also C<PTR2IV>, C<PTR2UV>, C<PTR2NV> macros, |
| 142 |
to map the other way, which may be useful in OUTPUT sections. |
| 143 |
|
| 144 |
=head2 The Role of the typemap File in Your Distribution |
| 145 |
|
| 146 |
The default typemap in the F<lib/ExtUtils> directory of the Perl source |
| 147 |
contains many useful types which can be used by Perl extensions. Some |
| 148 |
extensions define additional typemaps which they keep in their own directory. |
| 149 |
These additional typemaps may reference INPUT and OUTPUT maps in the main |
| 150 |
typemap. The B<xsubpp> compiler will allow the extension's own typemap to |
| 151 |
override any mappings which are in the default typemap. Instead of using |
| 152 |
an additional F<typemap> file, typemaps may be embedded verbatim in XS |
| 153 |
with a heredoc-like syntax. See the documentation on the C<TYPEMAP:> XS |
| 154 |
keyword. |
| 155 |
|
| 156 |
For CPAN distributions, you can assume that the XS types defined by |
| 157 |
the perl core are already available. Additionally, the core typemap |
| 158 |
has default XS types for a large number of C types. For example, if |
| 159 |
you simply return a C<char *> from your XSUB, the core typemap will |
| 160 |
have this C type associated with the T_PV XS type. That means your |
| 161 |
C string will be copied into the PV (pointer value) slot of a new scalar |
| 162 |
that will be returned from your XSUB to Perl. |
| 163 |
|
| 164 |
If you're developing a CPAN distribution using XS, you may add your own |
| 165 |
file called F<typemap> to the distribution. That file may contain |
| 166 |
typemaps that either map types that are specific to your code or that |
| 167 |
override the core typemap file's mappings for common C types. |
| 168 |
|
| 169 |
=head2 Sharing typemaps Between CPAN Distributions |
| 170 |
|
| 171 |
Starting with ExtUtils::ParseXS version 3.13_01 (comes with perl 5.16 |
| 172 |
and better), it is rather easy to share typemap code between multiple |
| 173 |
CPAN distributions. The general idea is to share it as a module that |
| 174 |
offers a certain API and have the dependent modules declare that as a |
| 175 |
built-time requirement and import the typemap into the XS. An example |
| 176 |
of such a typemap-sharing module on CPAN is |
| 177 |
C<ExtUtils::Typemaps::Basic>. Two steps to getting that module's |
| 178 |
typemaps available in your code: |
| 179 |
|
| 180 |
=over 4 |
| 181 |
|
| 182 |
=item * |
| 183 |
|
| 184 |
Declare C<ExtUtils::Typemaps::Basic> as a build-time dependency |
| 185 |
in C<Makefile.PL> (use C<BUILD_REQUIRES>), or in your C<Build.PL> |
| 186 |
(use C<build_requires>). |
| 187 |
|
| 188 |
=item * |
| 189 |
|
| 190 |
Include the following line in the XS section of your XS file: |
| 191 |
(don't break the line) |
| 192 |
|
| 193 |
INCLUDE_COMMAND: $^X -MExtUtils::Typemaps::Cmd |
| 194 |
-e "print embeddable_typemap(q{Basic})" |
| 195 |
|
| 196 |
=back |
| 197 |
|
| 198 |
=head2 Writing typemap Entries |
| 199 |
|
| 200 |
Each INPUT or OUTPUT typemap entry is a double-quoted Perl string that |
| 201 |
will be evaluated in the presence of certain variables to get the |
| 202 |
final C code for mapping a certain C type. |
| 203 |
|
| 204 |
This means that you can embed Perl code in your typemap (C) code using |
| 205 |
constructs such as |
| 206 |
C<${ perl code that evaluates to scalar reference here }>. A common |
| 207 |
use case is to generate error messages that refer to the true function |
| 208 |
name even when using the ALIAS XS feature: |
| 209 |
|
| 210 |
${ $ALIAS ? \q[GvNAME(CvGV(cv))] : \qq[\"$pname\"] } |
| 211 |
|
| 212 |
For many typemap examples, refer to the core typemap file that can be |
| 213 |
found in the perl source tree at F<lib/ExtUtils/typemap>. |
| 214 |
|
| 215 |
The Perl variables that are available for interpolation into typemaps |
| 216 |
are the following: |
| 217 |
|
| 218 |
=over 4 |
| 219 |
|
| 220 |
=item * |
| 221 |
|
| 222 |
I<$var> - the name of the input or output variable, eg. RETVAL for |
| 223 |
return values. |
| 224 |
|
| 225 |
=item * |
| 226 |
|
| 227 |
I<$type> - the raw C type of the parameter, any C<:> replaced with |
| 228 |
C<_>. |
| 229 |
e.g. for a type of C<Foo::Bar>, I<$type> is C<Foo__Bar> |
| 230 |
|
| 231 |
=item * |
| 232 |
|
| 233 |
I<$ntype> - the supplied type with C<*> replaced with C<Ptr>. |
| 234 |
e.g. for a type of C<Foo*>, I<$ntype> is C<FooPtr> |
| 235 |
|
| 236 |
=item * |
| 237 |
|
| 238 |
I<$arg> - the stack entry, that the parameter is input from or output |
| 239 |
to, e.g. C<ST(0)> |
| 240 |
|
| 241 |
=item * |
| 242 |
|
| 243 |
I<$argoff> - the argument stack offset of the argument. ie. 0 for the |
| 244 |
first argument, etc. |
| 245 |
|
| 246 |
=item * |
| 247 |
|
| 248 |
I<$pname> - the full name of the XSUB, with including the C<PACKAGE> |
| 249 |
name, with any C<PREFIX> stripped. This is the non-ALIAS name. |
| 250 |
|
| 251 |
=item * |
| 252 |
|
| 253 |
I<$Package> - the package specified by the most recent C<PACKAGE> |
| 254 |
keyword. |
| 255 |
|
| 256 |
=item * |
| 257 |
|
| 258 |
I<$ALIAS> - non-zero if the current XSUB has any aliases declared with |
| 259 |
C<ALIAS>. |
| 260 |
|
| 261 |
=back |
| 262 |
|
| 263 |
=head2 Full Listing of Core Typemaps |
| 264 |
|
| 265 |
Each C type is represented by an entry in the typemap file that |
| 266 |
is responsible for converting perl variables (SV, AV, HV, CV, etc.) |
| 267 |
to and from that type. The following sections list all XS types |
| 268 |
that come with perl by default. |
| 269 |
|
| 270 |
=over 4 |
| 271 |
|
| 272 |
=item T_SV |
| 273 |
|
| 274 |
This simply passes the C representation of the Perl variable (an SV*) |
| 275 |
in and out of the XS layer. This can be used if the C code wants |
| 276 |
to deal directly with the Perl variable. |
| 277 |
|
| 278 |
=item T_SVREF |
| 279 |
|
| 280 |
Used to pass in and return a reference to an SV. |
| 281 |
|
| 282 |
Note that this typemap does not decrement the reference count |
| 283 |
when returning the reference to an SV*. |
| 284 |
See also: T_SVREF_REFCOUNT_FIXED |
| 285 |
|
| 286 |
=item T_SVREF_FIXED |
| 287 |
|
| 288 |
Used to pass in and return a reference to an SV. |
| 289 |
This is a fixed |
| 290 |
variant of T_SVREF that decrements the refcount appropriately |
| 291 |
when returning a reference to an SV*. Introduced in perl 5.15.4. |
| 292 |
|
| 293 |
=item T_AVREF |
| 294 |
|
| 295 |
From the perl level this is a reference to a perl array. |
| 296 |
From the C level this is a pointer to an AV. |
| 297 |
|
| 298 |
Note that this typemap does not decrement the reference count |
| 299 |
when returning an AV*. See also: T_AVREF_REFCOUNT_FIXED |
| 300 |
|
| 301 |
=item T_AVREF_REFCOUNT_FIXED |
| 302 |
|
| 303 |
From the perl level this is a reference to a perl array. |
| 304 |
From the C level this is a pointer to an AV. This is a fixed |
| 305 |
variant of T_AVREF that decrements the refcount appropriately |
| 306 |
when returning an AV*. Introduced in perl 5.15.4. |
| 307 |
|
| 308 |
=item T_HVREF |
| 309 |
|
| 310 |
From the perl level this is a reference to a perl hash. |
| 311 |
From the C level this is a pointer to an HV. |
| 312 |
|
| 313 |
Note that this typemap does not decrement the reference count |
| 314 |
when returning an HV*. See also: T_HVREF_REFCOUNT_FIXED |
| 315 |
|
| 316 |
=item T_HVREF_REFCOUNT_FIXED |
| 317 |
|
| 318 |
From the perl level this is a reference to a perl hash. |
| 319 |
From the C level this is a pointer to an HV. This is a fixed |
| 320 |
variant of T_HVREF that decrements the refcount appropriately |
| 321 |
when returning an HV*. Introduced in perl 5.15.4. |
| 322 |
|
| 323 |
=item T_CVREF |
| 324 |
|
| 325 |
From the perl level this is a reference to a perl subroutine |
| 326 |
(e.g. $sub = sub { 1 };). From the C level this is a pointer |
| 327 |
to a CV. |
| 328 |
|
| 329 |
Note that this typemap does not decrement the reference count |
| 330 |
when returning an HV*. See also: T_HVREF_REFCOUNT_FIXED |
| 331 |
|
| 332 |
=item T_CVREF_REFCOUNT_FIXED |
| 333 |
|
| 334 |
From the perl level this is a reference to a perl subroutine |
| 335 |
(e.g. $sub = sub { 1 };). From the C level this is a pointer |
| 336 |
to a CV. |
| 337 |
|
| 338 |
This is a fixed |
| 339 |
variant of T_HVREF that decrements the refcount appropriately |
| 340 |
when returning an HV*. Introduced in perl 5.15.4. |
| 341 |
|
| 342 |
=item T_SYSRET |
| 343 |
|
| 344 |
The T_SYSRET typemap is used to process return values from system calls. |
| 345 |
It is only meaningful when passing values from C to perl (there is |
| 346 |
no concept of passing a system return value from Perl to C). |
| 347 |
|
| 348 |
System calls return -1 on error (setting ERRNO with the reason) |
| 349 |
and (usually) 0 on success. If the return value is -1 this typemap |
| 350 |
returns C<undef>. If the return value is not -1, this typemap |
| 351 |
translates a 0 (perl false) to "0 but true" (which |
| 352 |
is perl true) or returns the value itself, to indicate that the |
| 353 |
command succeeded. |
| 354 |
|
| 355 |
The L<POSIX|POSIX> module makes extensive use of this type. |
| 356 |
|
| 357 |
=item T_UV |
| 358 |
|
| 359 |
An unsigned integer. |
| 360 |
|
| 361 |
=item T_IV |
| 362 |
|
| 363 |
A signed integer. This is cast to the required integer type when |
| 364 |
passed to C and converted to an IV when passed back to Perl. |
| 365 |
|
| 366 |
=item T_INT |
| 367 |
|
| 368 |
A signed integer. This typemap converts the Perl value to a native |
| 369 |
integer type (the C<int> type on the current platform). When returning |
| 370 |
the value to perl it is processed in the same way as for T_IV. |
| 371 |
|
| 372 |
Its behaviour is identical to using an C<int> type in XS with T_IV. |
| 373 |
|
| 374 |
=item T_ENUM |
| 375 |
|
| 376 |
An enum value. Used to transfer an enum component |
| 377 |
from C. There is no reason to pass an enum value to C since |
| 378 |
it is stored as an IV inside perl. |
| 379 |
|
| 380 |
=item T_BOOL |
| 381 |
|
| 382 |
A boolean type. This can be used to pass true and false values to and |
| 383 |
from C. |
| 384 |
|
| 385 |
=item T_U_INT |
| 386 |
|
| 387 |
This is for unsigned integers. It is equivalent to using T_UV |
| 388 |
but explicitly casts the variable to type C<unsigned int>. |
| 389 |
The default type for C<unsigned int> is T_UV. |
| 390 |
|
| 391 |
=item T_SHORT |
| 392 |
|
| 393 |
Short integers. This is equivalent to T_IV but explicitly casts |
| 394 |
the return to type C<short>. The default typemap for C<short> |
| 395 |
is T_IV. |
| 396 |
|
| 397 |
=item T_U_SHORT |
| 398 |
|
| 399 |
Unsigned short integers. This is equivalent to T_UV but explicitly |
| 400 |
casts the return to type C<unsigned short>. The default typemap for |
| 401 |
C<unsigned short> is T_UV. |
| 402 |
|
| 403 |
T_U_SHORT is used for type C<U16> in the standard typemap. |
| 404 |
|
| 405 |
=item T_LONG |
| 406 |
|
| 407 |
Long integers. This is equivalent to T_IV but explicitly casts |
| 408 |
the return to type C<long>. The default typemap for C<long> |
| 409 |
is T_IV. |
| 410 |
|
| 411 |
=item T_U_LONG |
| 412 |
|
| 413 |
Unsigned long integers. This is equivalent to T_UV but explicitly |
| 414 |
casts the return to type C<unsigned long>. The default typemap for |
| 415 |
C<unsigned long> is T_UV. |
| 416 |
|
| 417 |
T_U_LONG is used for type C<U32> in the standard typemap. |
| 418 |
|
| 419 |
=item T_CHAR |
| 420 |
|
| 421 |
Single 8-bit characters. |
| 422 |
|
| 423 |
=item T_U_CHAR |
| 424 |
|
| 425 |
An unsigned byte. |
| 426 |
|
| 427 |
=item T_FLOAT |
| 428 |
|
| 429 |
A floating point number. This typemap guarantees to return a variable |
| 430 |
cast to a C<float>. |
| 431 |
|
| 432 |
=item T_NV |
| 433 |
|
| 434 |
A Perl floating point number. Similar to T_IV and T_UV in that the |
| 435 |
return type is cast to the requested numeric type rather than |
| 436 |
to a specific type. |
| 437 |
|
| 438 |
=item T_DOUBLE |
| 439 |
|
| 440 |
A double precision floating point number. This typemap guarantees to |
| 441 |
return a variable cast to a C<double>. |
| 442 |
|
| 443 |
=item T_PV |
| 444 |
|
| 445 |
A string (char *). |
| 446 |
|
| 447 |
=item T_PTR |
| 448 |
|
| 449 |
A memory address (pointer). Typically associated with a C<void *> |
| 450 |
type. |
| 451 |
|
| 452 |
=item T_PTRREF |
| 453 |
|
| 454 |
Similar to T_PTR except that the pointer is stored in a scalar and the |
| 455 |
reference to that scalar is returned to the caller. This can be used |
| 456 |
to hide the actual pointer value from the programmer since it is usually |
| 457 |
not required directly from within perl. |
| 458 |
|
| 459 |
The typemap checks that a scalar reference is passed from perl to XS. |
| 460 |
|
| 461 |
=item T_PTROBJ |
| 462 |
|
| 463 |
Similar to T_PTRREF except that the reference is blessed into a class. |
| 464 |
This allows the pointer to be used as an object. Most commonly used to |
| 465 |
deal with C structs. The typemap checks that the perl object passed |
| 466 |
into the XS routine is of the correct class (or part of a subclass). |
| 467 |
|
| 468 |
The pointer is blessed into a class that is derived from the name |
| 469 |
of type of the pointer but with all '*' in the name replaced with |
| 470 |
'Ptr'. |
| 471 |
|
| 472 |
For C<DESTROY> XSUBs only, a T_PTROBJ is optimized to a T_PTRREF. This means |
| 473 |
the class check is skipped. |
| 474 |
|
| 475 |
=item T_REF_IV_REF |
| 476 |
|
| 477 |
NOT YET |
| 478 |
|
| 479 |
=item T_REF_IV_PTR |
| 480 |
|
| 481 |
Similar to T_PTROBJ in that the pointer is blessed into a scalar object. |
| 482 |
The difference is that when the object is passed back into XS it must be |
| 483 |
of the correct type (inheritance is not supported) while T_PTROBJ supports |
| 484 |
inheritance. |
| 485 |
|
| 486 |
The pointer is blessed into a class that is derived from the name |
| 487 |
of type of the pointer but with all '*' in the name replaced with |
| 488 |
'Ptr'. |
| 489 |
|
| 490 |
For C<DESTROY> XSUBs only, a T_REF_IV_PTR is optimized to a T_PTRREF. This |
| 491 |
means the class check is skipped. |
| 492 |
|
| 493 |
=item T_PTRDESC |
| 494 |
|
| 495 |
NOT YET |
| 496 |
|
| 497 |
=item T_REFREF |
| 498 |
|
| 499 |
Similar to T_PTRREF, except the pointer stored in the referenced scalar |
| 500 |
is dereferenced and copied to the output variable. This means that |
| 501 |
T_REFREF is to T_PTRREF as T_OPAQUE is to T_OPAQUEPTR. All clear? |
| 502 |
|
| 503 |
Only the INPUT part of this is implemented (Perl to XSUB) and there |
| 504 |
are no known users in core or on CPAN. |
| 505 |
|
| 506 |
=item T_REFOBJ |
| 507 |
|
| 508 |
Like T_REFREF, except it does strict type checking (inheritance is not |
| 509 |
supported). |
| 510 |
|
| 511 |
For C<DESTROY> XSUBs only, a T_REFOBJ is optimized to a T_REFREF. This means |
| 512 |
the class check is skipped. |
| 513 |
|
| 514 |
=item T_OPAQUEPTR |
| 515 |
|
| 516 |
This can be used to store bytes in the string component of the |
| 517 |
SV. Here the representation of the data is irrelevant to perl and the |
| 518 |
bytes themselves are just stored in the SV. It is assumed that the C |
| 519 |
variable is a pointer (the bytes are copied from that memory |
| 520 |
location). If the pointer is pointing to something that is |
| 521 |
represented by 8 bytes then those 8 bytes are stored in the SV (and |
| 522 |
length() will report a value of 8). This entry is similar to T_OPAQUE. |
| 523 |
|
| 524 |
In principle the unpack() command can be used to convert the bytes |
| 525 |
back to a number (if the underlying type is known to be a number). |
| 526 |
|
| 527 |
This entry can be used to store a C structure (the number |
| 528 |
of bytes to be copied is calculated using the C C<sizeof> function) |
| 529 |
and can be used as an alternative to T_PTRREF without having to worry |
| 530 |
about a memory leak (since Perl will clean up the SV). |
| 531 |
|
| 532 |
=item T_OPAQUE |
| 533 |
|
| 534 |
This can be used to store data from non-pointer types in the string |
| 535 |
part of an SV. It is similar to T_OPAQUEPTR except that the |
| 536 |
typemap retrieves the pointer directly rather than assuming it |
| 537 |
is being supplied. For example, if an integer is imported into |
| 538 |
Perl using T_OPAQUE rather than T_IV the underlying bytes representing |
| 539 |
the integer will be stored in the SV but the actual integer value will |
| 540 |
not be available. i.e. The data is opaque to perl. |
| 541 |
|
| 542 |
The data may be retrieved using the C<unpack> function if the |
| 543 |
underlying type of the byte stream is known. |
| 544 |
|
| 545 |
T_OPAQUE supports input and output of simple types. |
| 546 |
T_OPAQUEPTR can be used to pass these bytes back into C if a pointer |
| 547 |
is acceptable. |
| 548 |
|
| 549 |
=item Implicit array |
| 550 |
|
| 551 |
xsubpp supports a special syntax for returning |
| 552 |
packed C arrays to perl. If the XS return type is given as |
| 553 |
|
| 554 |
array(type, nelem) |
| 555 |
|
| 556 |
xsubpp will copy the contents of C<nelem * sizeof(type)> bytes from |
| 557 |
RETVAL to an SV and push it onto the stack. This is only really useful |
| 558 |
if the number of items to be returned is known at compile time and you |
| 559 |
don't mind having a string of bytes in your SV. Use T_ARRAY to push a |
| 560 |
variable number of arguments onto the return stack (they won't be |
| 561 |
packed as a single string though). |
| 562 |
|
| 563 |
This is similar to using T_OPAQUEPTR but can be used to process more |
| 564 |
than one element. |
| 565 |
|
| 566 |
=item T_PACKED |
| 567 |
|
| 568 |
Calls user-supplied functions for conversion. For C<OUTPUT> |
| 569 |
(XSUB to Perl), a function named C<XS_pack_$ntype> is called |
| 570 |
with the output Perl scalar and the C variable to convert from. |
| 571 |
C<$ntype> is the normalized C type that is to be mapped to |
| 572 |
Perl. Normalized means that all C<*> are replaced by the |
| 573 |
string C<Ptr>. The return value of the function is ignored. |
| 574 |
|
| 575 |
Conversely for C<INPUT> (Perl to XSUB) mapping, the |
| 576 |
function named C<XS_unpack_$ntype> is called with the input Perl |
| 577 |
scalar as argument and the return value is cast to the mapped |
| 578 |
C type and assigned to the output C variable. |
| 579 |
|
| 580 |
An example conversion function for a typemapped struct |
| 581 |
C<foo_t *> might be: |
| 582 |
|
| 583 |
static void |
| 584 |
XS_pack_foo_tPtr(SV *out, foo_t *in) |
| 585 |
{ |
| 586 |
dTHX; /* alas, signature does not include pTHX_ */ |
| 587 |
HV* hash = newHV(); |
| 588 |
hv_stores(hash, "int_member", newSViv(in->int_member)); |
| 589 |
hv_stores(hash, "float_member", newSVnv(in->float_member)); |
| 590 |
/* ... */ |
| 591 |
|
| 592 |
/* mortalize as thy stack is not refcounted */ |
| 593 |
sv_setsv(out, sv_2mortal(newRV_noinc((SV*)hash))); |
| 594 |
} |
| 595 |
|
| 596 |
The conversion from Perl to C is left as an exercise to the reader, |
| 597 |
but the prototype would be: |
| 598 |
|
| 599 |
static foo_t * |
| 600 |
XS_unpack_foo_tPtr(SV *in); |
| 601 |
|
| 602 |
Instead of an actual C function that has to fetch the thread context |
| 603 |
using C<dTHX>, you can define macros of the same name and avoid the |
| 604 |
overhead. Also, keep in mind to possibly free the memory allocated by |
| 605 |
C<XS_unpack_foo_tPtr>. |
| 606 |
|
| 607 |
=item T_PACKEDARRAY |
| 608 |
|
| 609 |
T_PACKEDARRAY is similar to T_PACKED. In fact, the C<INPUT> (Perl |
| 610 |
to XSUB) typemap is identical, but the C<OUTPUT> typemap passes |
| 611 |
an additional argument to the C<XS_pack_$ntype> function. This |
| 612 |
third parameter indicates the number of elements in the output |
| 613 |
so that the function can handle C arrays sanely. The variable |
| 614 |
needs to be declared by the user and must have the name |
| 615 |
C<count_$ntype> where C<$ntype> is the normalized C type name |
| 616 |
as explained above. The signature of the function would be for |
| 617 |
the example above and C<foo_t **>: |
| 618 |
|
| 619 |
static void |
| 620 |
XS_pack_foo_tPtrPtr(SV *out, foo_t *in, UV count_foo_tPtrPtr); |
| 621 |
|
| 622 |
The type of the third parameter is arbitrary as far as the typemap |
| 623 |
is concerned. It just has to be in line with the declared variable. |
| 624 |
|
| 625 |
Of course, unless you know the number of elements in the |
| 626 |
C<sometype **> C array, within your XSUB, the return value from |
| 627 |
C<foo_t ** XS_unpack_foo_tPtrPtr(...)> will be hard to decipher. |
| 628 |
Since the details are all up to the XS author (the typemap user), |
| 629 |
there are several solutions, none of which particularly elegant. |
| 630 |
The most commonly seen solution has been to allocate memory for |
| 631 |
N+1 pointers and assign C<NULL> to the (N+1)th to facilitate |
| 632 |
iteration. |
| 633 |
|
| 634 |
Alternatively, using a customized typemap for your purposes in |
| 635 |
the first place is probably preferable. |
| 636 |
|
| 637 |
=item T_DATAUNIT |
| 638 |
|
| 639 |
NOT YET |
| 640 |
|
| 641 |
=item T_CALLBACK |
| 642 |
|
| 643 |
NOT YET |
| 644 |
|
| 645 |
=item T_ARRAY |
| 646 |
|
| 647 |
This is used to convert the perl argument list to a C array |
| 648 |
and for pushing the contents of a C array onto the perl |
| 649 |
argument stack. |
| 650 |
|
| 651 |
The usual calling signature is |
| 652 |
|
| 653 |
@out = array_func( @in ); |
| 654 |
|
| 655 |
Any number of arguments can occur in the list before the array but |
| 656 |
the input and output arrays must be the last elements in the list. |
| 657 |
|
| 658 |
When used to pass a perl list to C the XS writer must provide a |
| 659 |
function (named after the array type but with 'Ptr' substituted for |
| 660 |
'*') to allocate the memory required to hold the list. A pointer |
| 661 |
should be returned. It is up to the XS writer to free the memory on |
| 662 |
exit from the function. The variable C<ix_$var> is set to the number |
| 663 |
of elements in the new array. |
| 664 |
|
| 665 |
When returning a C array to Perl the XS writer must provide an integer |
| 666 |
variable called C<size_$var> containing the number of elements in the |
| 667 |
array. This is used to determine how many elements should be pushed |
| 668 |
onto the return argument stack. This is not required on input since |
| 669 |
Perl knows how many arguments are on the stack when the routine is |
| 670 |
called. Ordinarily this variable would be called C<size_RETVAL>. |
| 671 |
|
| 672 |
Additionally, the type of each element is determined from the type of |
| 673 |
the array. If the array uses type C<intArray *> xsubpp will |
| 674 |
automatically work out that it contains variables of type C<int> and |
| 675 |
use that typemap entry to perform the copy of each element. All |
| 676 |
pointer '*' and 'Array' tags are removed from the name to determine |
| 677 |
the subtype. |
| 678 |
|
| 679 |
=item T_STDIO |
| 680 |
|
| 681 |
This is used for passing perl filehandles to and from C using |
| 682 |
C<FILE *> structures. |
| 683 |
|
| 684 |
=item T_INOUT |
| 685 |
|
| 686 |
This is used for passing perl filehandles to and from C using |
| 687 |
C<PerlIO *> structures. The file handle can used for reading and |
| 688 |
writing. This corresponds to the C<+E<lt>> mode, see also T_IN |
| 689 |
and T_OUT. |
| 690 |
|
| 691 |
See L<perliol> for more information on the Perl IO abstraction |
| 692 |
layer. Perl must have been built with C<-Duseperlio>. |
| 693 |
|
| 694 |
There is no check to assert that the filehandle passed from Perl |
| 695 |
to C was created with the right C<open()> mode. |
| 696 |
|
| 697 |
Hint: The L<perlxstut> tutorial covers the T_INOUT, T_IN, and T_OUT |
| 698 |
XS types nicely. |
| 699 |
|
| 700 |
=item T_IN |
| 701 |
|
| 702 |
Same as T_INOUT, but the filehandle that is returned from C to Perl |
| 703 |
can only be used for reading (mode C<E<lt>>). |
| 704 |
|
| 705 |
=item T_OUT |
| 706 |
|
| 707 |
Same as T_INOUT, but the filehandle that is returned from C to Perl |
| 708 |
is set to use the open mode C<+E<gt>>. |
| 709 |
|
| 710 |
=back |
| 711 |
|