Debian Codegraph @

upstream/debian-unstable/man1/perlxstypemap.1

raw
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.