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