Debian Codegraph @

upstream/mageia-cauldron/man1/perlxstypemap.1

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