This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
XS::Typemap: Fix typo in docs, fix version
[perl5.git] / ext / XS-Typemap / Typemap.xs
CommitLineData
ea035a69
JH
1/*
2 XS code to test the typemap entries
3
4 Copyright (C) 2001 Tim Jenness.
5 All Rights Reserved
6
7*/
8
3c53ff3f
NC
9#define PERL_NO_GET_CONTEXT
10
ea035a69
JH
11#include "EXTERN.h" /* std perl include */
12#include "perl.h" /* std perl include */
13#include "XSUB.h" /* XSUB include */
14
15/* Prototypes for external functions */
16FILE * xsfopen( const char * );
17int xsfclose( FILE * );
18int xsfprintf( FILE *, const char *);
19
20/* Type definitions required for the XS typemaps */
21typedef SV * SVREF; /* T_SVREF */
22typedef int SysRet; /* T_SYSRET */
23typedef int Int; /* T_INT */
24typedef int intRef; /* T_PTRREF */
25typedef int intObj; /* T_PTROBJ */
26typedef int intRefIv; /* T_REF_IV_PTR */
27typedef int intArray; /* T_ARRAY */
604db645
SM
28typedef int intTINT; /* T_INT */
29typedef int intTLONG; /* T_LONG */
ea035a69
JH
30typedef short shortOPQ; /* T_OPAQUE */
31typedef int intOpq; /* T_OPAQUEPTR */
604db645 32typedef unsigned intUnsigned; /* T_U_INT */
21b5216d
SM
33typedef PerlIO inputfh; /* T_IN */
34typedef PerlIO outputfh; /* T_OUT */
ea035a69 35
2465d83f 36/* A structure to test T_OPAQUEPTR and T_PACKED */
5abff6f9
TJ
37struct t_opaqueptr {
38 int a;
39 int b;
40 double c;
41};
42
43typedef struct t_opaqueptr astruct;
2465d83f 44typedef struct t_opaqueptr anotherstruct;
5abff6f9 45
ea035a69 46/* Some static memory for the tests */
052980ee
TJ
47static I32 xst_anint;
48static intRef xst_anintref;
49static intObj xst_anintobj;
50static intRefIv xst_anintrefiv;
51static intOpq xst_anintopq;
ea035a69 52
b64f48ff 53/* A different type to refer to for testing the different
1d2615b4 54 * AV*, HV*, etc typemaps */
b64f48ff
SM
55typedef AV AV_FIXED;
56typedef HV HV_FIXED;
1d2615b4
SM
57typedef CV CV_FIXED;
58typedef SVREF SVREF_FIXED;
b64f48ff 59
ea035a69
JH
60/* Helper functions */
61
62/* T_ARRAY - allocate some memory */
63intArray * intArrayPtr( int nelem ) {
64 intArray * array;
a02a5408 65 Newx(array, nelem, intArray);
ea035a69
JH
66 return array;
67}
68
2465d83f
SM
69/* test T_PACKED */
70#define XS_pack_anotherstructPtr(out, in) \
71 STMT_START { \
72 HV *hash = newHV(); \
73 hv_stores(hash, "a", newSViv((in)->a)); \
74 hv_stores(hash, "b", newSViv((in)->b)); \
75 hv_stores(hash, "c", newSVnv((in)->c)); \
76 sv_setsv((out), sv_2mortal(newRV_noinc((SV*)hash))); \
77 } STMT_END
78
ea0d3d8e 79STATIC anotherstruct *
2465d83f
SM
80XS_unpack_anotherstructPtr(SV *in)
81{
82 dTHX; /* rats, this is expensive */
83 /* this is similar to T_HVREF since we chose to use a hash */
84 HV *inhash;
85 SV **elem;
86 anotherstruct *out;
87 SV *const tmp = in;
88 SvGETMAGIC(tmp);
89 if (SvROK(tmp) && SvTYPE(SvRV(tmp)) == SVt_PVHV)
90 inhash = (HV*)SvRV(tmp);
91 else
92 Perl_croak(aTHX_ "Argument is not a HASH reference");
93
94 /* FIXME dunno if supposed to use perl mallocs here */
95 Newxz(out, 1, anotherstruct);
96
97 elem = hv_fetchs(inhash, "a", 0);
98 if (elem == NULL)
99 Perl_croak(aTHX_ "Shouldn't happen: hv_fetchs returns NULL");
100 out->a = SvIV(*elem);
101
102 elem = hv_fetchs(inhash, "b", 0);
103 if (elem == NULL)
104 Perl_croak(aTHX_ "Shouldn't happen: hv_fetchs returns NULL");
105 out->b = SvIV(*elem);
106
107 elem = hv_fetchs(inhash, "c", 0);
108 if (elem == NULL)
109 Perl_croak(aTHX_ "Shouldn't happen: hv_fetchs returns NULL");
110 out->c = SvNV(*elem);
111
112 return out;
113}
114
ea0d3d8e
SM
115/* test T_PACKEDARRAY */
116#define XS_pack_anotherstructPtrPtr(out, in, cnt) \
117 STMT_START { \
118 UV i; \
119 AV *ary = newAV(); \
120 for (i = 0; i < cnt; ++i) { \
121 HV *hash = newHV(); \
122 hv_stores(hash, "a", newSViv((in)[i]->a)); \
123 hv_stores(hash, "b", newSViv((in)[i]->b)); \
124 hv_stores(hash, "c", newSVnv((in)[i]->c)); \
125 av_push(ary, newRV_noinc((SV*)hash)); \
126 } \
127 sv_setsv((out), sv_2mortal(newRV_noinc((SV*)ary))); \
128 } STMT_END
129
130STATIC anotherstruct **
131XS_unpack_anotherstructPtrPtr(SV *in)
132{
133 dTHX; /* rats, this is expensive */
134 /* this is similar to T_HVREF since we chose to use a hash */
135 HV *inhash;
136 AV *inary;
137 SV **elem;
138 anotherstruct **out;
139 UV nitems, i;
140 SV *tmp;
141
142 /* safely deref the input array ref */
143 tmp = in;
144 SvGETMAGIC(tmp);
145 if (SvROK(tmp) && SvTYPE(SvRV(tmp)) == SVt_PVAV)
146 inary = (AV*)SvRV(tmp);
147 else
148 Perl_croak(aTHX_ "Argument is not an ARRAY reference");
149
150 nitems = av_len(inary) + 1;
151
152 /* FIXME dunno if supposed to use perl mallocs here */
153 /* N+1 elements so we know the last one is NULL */
154 Newxz(out, nitems+1, anotherstruct*);
155
156 /* WARNING: in real code, we'd have to Safefree() on exception, but
157 * since we're testing perl, if we croak() here, stuff is
158 * rotten anyway! */
159 for (i = 0; i < nitems; ++i) {
160 Newxz(out[i], 1, anotherstruct);
161 elem = av_fetch(inary, i, 0);
162 if (elem == NULL)
163 Perl_croak(aTHX_ "Shouldn't happen: av_fetch returns NULL");
164 tmp = *elem;
165 SvGETMAGIC(tmp);
166 if (SvROK(tmp) && SvTYPE(SvRV(tmp)) == SVt_PVHV)
167 inhash = (HV*)SvRV(tmp);
168 else
169 Perl_croak(aTHX_ "Array element %u is not a HASH reference", i);
170
171 elem = hv_fetchs(inhash, "a", 0);
172 if (elem == NULL)
173 Perl_croak(aTHX_ "Shouldn't happen: hv_fetchs returns NULL");
174 out[i]->a = SvIV(*elem);
175
176 elem = hv_fetchs(inhash, "b", 0);
177 if (elem == NULL)
178 Perl_croak(aTHX_ "Shouldn't happen: hv_fetchs returns NULL");
179 out[i]->b = SvIV(*elem);
180
181 elem = hv_fetchs(inhash, "c", 0);
182 if (elem == NULL)
183 Perl_croak(aTHX_ "Shouldn't happen: hv_fetchs returns NULL");
184 out[i]->c = SvNV(*elem);
185
186 }
187
188 return out;
189}
190
191/* no special meaning as far as typemaps are concerned,
192 * just for convenience */
193void
194XS_release_anotherstructPtrPtr(anotherstruct **in)
195{
196 unsigned int i = 0;
197 while (in[i] != NULL)
198 Safefree(in[i++]);
199 Safefree(in);
200}
201
ea035a69
JH
202
203MODULE = XS::Typemap PACKAGE = XS::Typemap
204
205PROTOTYPES: DISABLE
206
09186e9e
SM
207TYPEMAP: <<END_OF_TYPEMAP
208
209# Typemap file for typemap testing
210# includes bonus typemap entries
211# Mainly so that all the standard typemaps can be exercised even when
212# there is not a corresponding type explicitly identified in the standard
213# typemap
214
ea0d3d8e
SM
215svtype T_ENUM
216intRef * T_PTRREF
217intRef T_IV
218intObj * T_PTROBJ
219intObj T_IV
220intRefIv * T_REF_IV_PTR
221intRefIv T_IV
222intArray * T_ARRAY
223intOpq T_IV
224intOpq * T_OPAQUEPTR
225intUnsigned T_U_INT
226intTINT T_INT
227intTLONG T_LONG
228shortOPQ T_OPAQUE
229shortOPQ * T_OPAQUEPTR
230astruct * T_OPAQUEPTR
231anotherstruct * T_PACKED
232anotherstruct ** T_PACKEDARRAY
233AV_FIXED * T_AVREF_REFCOUNT_FIXED
234HV_FIXED * T_HVREF_REFCOUNT_FIXED
235CV_FIXED * T_CVREF_REFCOUNT_FIXED
236SVREF_FIXED T_SVREF_REFCOUNT_FIXED
21b5216d
SM
237inputfh T_IN
238outputfh T_OUT
09186e9e
SM
239
240END_OF_TYPEMAP
241
ea035a69
JH
242=head1 TYPEMAPS
243
8447d1c7
SM
244The more you think about interfacing between two languages, the more
245you'll realize that the majority of programmer effort has to go into
246converting between the data structures that are native to either of
247the languages involved. This trumps other matter such as differing
248calling conventions because the problem space is so much greater.
249There are simply more ways to shove data into memory than there are
250ways to implement a function call.
251
252Perl XS' attempt at a solution to this is the concept of typemaps.
253At an abstract level, a Perl XS typemap is nothing but a recipe for
254converting from a certain Perl data structure to a certain C
255data structure and/or vice versa. Since there can be C types that
256are sufficiently similar to warrant converting with the same logic,
257XS typemaps are represented by a unique identifier, called XS type
258henceforth in this document. You can then tell the XS compiler that
259multiple C types are to be mapped with the same XS typemap.
260
261In your XS code, when you define an argument with a C type or when
262you are using a C<CODE:> and an C<OUTPUT:> section together with a
263C return type of your XSUB, it'll be the typemapping mechanism that
264makes this easy.
265
266=head2 Anatomy of a typemap File
267
853ee02d
SM
268Traditionally, typemaps needed to be written to a separate file,
269conventionally called C<typemap>. With ExtUtils::ParseXS (the XS
270compiler) version 3.00 or better (comes with perl 5.16), typemaps
271can also be embedded directly into your XS code using a HERE-doc
272like syntax:
273
274 TYPEMAP: <<HERE
275 ...
276 HERE
277
278where C<HERE> can be replaced by other identifiers like with normal
279Perl HERE-docs. All details below about the typemap textual format
280remain valid.
281
282A typemap file generally has three sections: The C<TYPEMAP>
283section is used to associate C types with XS type identifiers.
284The C<INPUT> section is used to define the typemaps for I<input>
285into the XSUB from Perl, and the C<OUTPUT> section has the opposite
286conversion logic for getting data out of an XSUB back into Perl.
287
288Each section is started by the section name in capital letters on a
289line of its own. A typemap file implicitly starts in the C<TYPEMAP>
290section. Each type of section can appear an arbitrary number of times
291and does not have to appear at all. For example, a typemap file may
292lack C<INPUT> and C<OUTPUT> sections if all it needs to do is
293associate additional C types with core XS types like T_PTROBJ.
294Lines that start with a hash C<#> are considered comments and ignored
295in the C<TYPEMAP> section, but are considered significant in C<INPUT>
296and C<OUTPUT>. Blank lines are generally ignored.
297
298The C<TYPEMAP> section should contain one pair of C type and
299XS type per line as follows. An example from the core typemap file:
300
301 TYPEMAP
302 # all variants of char* is handled by the T_PV typemap
303 char * T_PV
304 const char * T_PV
305 unsigned char * T_PV
306 ...
307
308The C<INPUT> and C<OUTPUT> sections have identical formats, that is,
309each unindented line starts a new in- or output map respectively.
310A new in- or output map must start with the name of the XS type to
311map on a line by itself, followed by the code that implements it
312indented on the following lines. Example:
313
314 INPUT
315 T_PV
316 $var = ($type)SvPV_nolen($arg)
317 T_PTR
318 $var = INT2PTR($type,SvIV($arg))
319
320We'll get to the meaning of those Perlish-looking variables in a
321little bit.
322
323Finally, here's an example of the full typemap file for mapping C
324strings of the C<char *> type to Perl scalars/strings:
325
326 TYPEMAP
327 char * T_PV
328
329 INPUT
330 T_PV
331 $var = ($type)SvPV_nolen($arg)
332
333 OUTPUT
334 T_PV
335 sv_setpv((SV*)$arg, $var);
8447d1c7
SM
336
337=head2 The Role of the typemap File in Your Distribution
338
339For CPAN distributions, you can assume that the XS types defined by
340the perl core are already available. Additionally, the core typemap
341has default XS types for a large number of C types. For example, if
342you simply return a C<char *> from your XSUB, the core typemap will
343have this C type associated with the T_PV XS type. That means your
344C string will be copied into the PV (pointer value) slot of a new scalar
345that will be returned from your XSUB to to Perl.
346
347If you're developing a CPAN distribution using XS, you may add your own
348file called F<typemap> to the distribution. That file may contain
349typemaps that either map types that are specific to your code or that
350override the core typemap file's mappings for common C types.
351
090ff051
SM
352=head2 Sharing typemaps Between CPAN Distributions
353
56ab3cdc 354Starting with ExtUtils::ParseXS version 3.13_01 (comes with perl 5.16
090ff051
SM
355and better), it is rather easy to share typemap code between multiple
356CPAN distributions. The general idea is to share it as a module that
357offers a certain API and have the dependent modules declare that as a
358built-time requirement and import the typemap into the XS. An example
359of such a typemap-sharing module on CPAN is
360C<ExtUtils::Typemaps::Basic>. Two steps to getting that module's
361typemaps available in your code:
362
363=over 4
364
365=item *
366
56ab3cdc 367Declare C<ExtUtils::Typemaps::Basic> as a build-time dependency
090ff051
SM
368in C<Makefile.PL> (use C<BUILD_REQUIRES>), or in your C<Build.PL>
369(use C<build_requires>).
370
371=item *
372
373Include the following line in the XS section of your XS file:
374(don't break the line)
375
376 INCLUDE_COMMAND: $^X -MExtUtils::Typemaps::Cmd
377 -e "print embeddable_typemap(q{Basic})"
378
379=back
380
8447d1c7
SM
381=head2 Full Listing of Core Typemaps
382
ea035a69 383Each C type is represented by an entry in the typemap file that
ac23f157 384is responsible for converting perl variables (SV, AV, HV, CV, etc.)
8447d1c7
SM
385to and from that type. The following sections list all XS types
386that come with perl by default.
ea035a69
JH
387
388=over 4
389
390=item T_SV
391
392This simply passes the C representation of the Perl variable (an SV*)
393in and out of the XS layer. This can be used if the C code wants
394to deal directly with the Perl variable.
395
396=cut
397
398SV *
399T_SV( sv )
400 SV * sv
401 CODE:
402 /* create a new sv for return that is a copy of the input
403 do not simply copy the pointer since the SV will be marked
404 mortal by the INPUT typemap when it is pushed back onto the stack */
405 RETVAL = sv_mortalcopy( sv );
406 /* increment the refcount since the default INPUT typemap mortalizes
407 by default and we don't want to decrement the ref count twice
408 by mistake */
409 SvREFCNT_inc(RETVAL);
410 OUTPUT:
411 RETVAL
412
413=item T_SVREF
414
415Used to pass in and return a reference to an SV.
416
1d2615b4
SM
417Note that this typemap does not decrement the reference count
418when returning the reference to an SV*.
419See also: T_SVREF_REFCOUNT_FIXED
420
ea035a69
JH
421=cut
422
423SVREF
424T_SVREF( svref )
425 SVREF svref
426 CODE:
427 RETVAL = svref;
428 OUTPUT:
429 RETVAL
430
1d2615b4
SM
431=item T_SVREF_FIXED
432
433Used to pass in and return a reference to an SV.
434This is a fixed
435variant of T_SVREF that decrements the refcount appropriately
436when returning a reference to an SV*. Introduced in perl 5.15.4.
437
438=cut
439
440SVREF_FIXED
441T_SVREF_REFCOUNT_FIXED( svref )
442 SVREF_FIXED svref
443 CODE:
444 SvREFCNT_inc(svref);
445 RETVAL = svref;
446 OUTPUT:
447 RETVAL
448
ea035a69
JH
449=item T_AVREF
450
451From the perl level this is a reference to a perl array.
452From the C level this is a pointer to an AV.
453
b64f48ff
SM
454Note that this typemap does not decrement the reference count
455when returning an AV*. See also: T_AVREF_REFCOUNT_FIXED
456
ea035a69
JH
457=cut
458
459AV *
460T_AVREF( av )
461 AV * av
462 CODE:
463 RETVAL = av;
464 OUTPUT:
465 RETVAL
466
b64f48ff
SM
467=item T_AVREF_REFCOUNT_FIXED
468
469From the perl level this is a reference to a perl array.
470From the C level this is a pointer to an AV. This is a fixed
471variant of T_AVREF that decrements the refcount appropriately
472when returning an AV*. Introduced in perl 5.15.4.
473
474=cut
475
476AV_FIXED*
477T_AVREF_REFCOUNT_FIXED( av )
478 AV_FIXED * av
479 CODE:
480 SvREFCNT_inc(av);
481 RETVAL = av;
482 OUTPUT:
483 RETVAL
484
ea035a69
JH
485=item T_HVREF
486
487From the perl level this is a reference to a perl hash.
d1be9408 488From the C level this is a pointer to an HV.
ea035a69 489
b64f48ff
SM
490Note that this typemap does not decrement the reference count
491when returning an HV*. See also: T_HVREF_REFCOUNT_FIXED
492
ea035a69
JH
493=cut
494
495HV *
496T_HVREF( hv )
497 HV * hv
498 CODE:
499 RETVAL = hv;
500 OUTPUT:
501 RETVAL
502
b64f48ff
SM
503=item T_HVREF_REFCOUNT_FIXED
504
505From the perl level this is a reference to a perl hash.
506From the C level this is a pointer to an HV. This is a fixed
507variant of T_HVREF that decrements the refcount appropriately
508when returning an HV*. Introduced in perl 5.15.4.
509
510=cut
511
512HV_FIXED*
513T_HVREF_REFCOUNT_FIXED( hv )
514 HV_FIXED * hv
515 CODE:
516 SvREFCNT_inc(hv);
517 RETVAL = hv;
518 OUTPUT:
519 RETVAL
520
521
ea035a69
JH
522=item T_CVREF
523
524From the perl level this is a reference to a perl subroutine
525(e.g. $sub = sub { 1 };). From the C level this is a pointer
526to a CV.
527
1d2615b4
SM
528Note that this typemap does not decrement the reference count
529when returning an HV*. See also: T_HVREF_REFCOUNT_FIXED
530
ea035a69
JH
531=cut
532
533CV *
534T_CVREF( cv )
535 CV * cv
536 CODE:
537 RETVAL = cv;
538 OUTPUT:
539 RETVAL
540
1d2615b4
SM
541=item T_CVREF_REFCOUNT_FIXED
542
543From the perl level this is a reference to a perl subroutine
544(e.g. $sub = sub { 1 };). From the C level this is a pointer
545to a CV.
546
547This is a fixed
548variant of T_HVREF that decrements the refcount appropriately
549when returning an HV*. Introduced in perl 5.15.4.
550
551=cut
552
553CV_FIXED *
554T_CVREF_REFCOUNT_FIXED( cv )
555 CV_FIXED * cv
556 CODE:
557 SvREFCNT_inc(cv);
558 RETVAL = cv;
559 OUTPUT:
560 RETVAL
ea035a69
JH
561
562=item T_SYSRET
563
564The T_SYSRET typemap is used to process return values from system calls.
565It is only meaningful when passing values from C to perl (there is
566no concept of passing a system return value from Perl to C).
567
568System calls return -1 on error (setting ERRNO with the reason)
569and (usually) 0 on success. If the return value is -1 this typemap
570returns C<undef>. If the return value is not -1, this typemap
571translates a 0 (perl false) to "0 but true" (which
572is perl true) or returns the value itself, to indicate that the
573command succeeded.
574
575The L<POSIX|POSIX> module makes extensive use of this type.
576
577=cut
578
579# Test a successful return
580
581SysRet
582T_SYSRET_pass()
583 CODE:
584 RETVAL = 0;
585 OUTPUT:
586 RETVAL
587
588# Test failure
589
590SysRet
591T_SYSRET_fail()
592 CODE:
593 RETVAL = -1;
594 OUTPUT:
595 RETVAL
596
597=item T_UV
598
599An unsigned integer.
600
601=cut
602
603unsigned int
604T_UV( uv )
605 unsigned int uv
606 CODE:
607 RETVAL = uv;
608 OUTPUT:
609 RETVAL
610
611=item T_IV
612
ac23f157 613A signed integer. This is cast to the required integer type when
d1be9408 614passed to C and converted to an IV when passed back to Perl.
ea035a69
JH
615
616=cut
617
618long
619T_IV( iv )
620 long iv
621 CODE:
622 RETVAL = iv;
623 OUTPUT:
624 RETVAL
625
626=item T_INT
627
628A signed integer. This typemap converts the Perl value to a native
629integer type (the C<int> type on the current platform). When returning
630the value to perl it is processed in the same way as for T_IV.
631
632Its behaviour is identical to using an C<int> type in XS with T_IV.
633
604db645
SM
634=cut
635
636intTINT
637T_INT( i )
638 intTINT i
639 CODE:
640 RETVAL = i;
641 OUTPUT:
642 RETVAL
643
ea035a69
JH
644=item T_ENUM
645
646An enum value. Used to transfer an enum component
647from C. There is no reason to pass an enum value to C since
648it is stored as an IV inside perl.
649
650=cut
651
652# The test should return the value for SVt_PVHV.
653# 11 at the present time but we can't not rely on this
654# for testing purposes.
655
656svtype
657T_ENUM()
658 CODE:
659 RETVAL = SVt_PVHV;
660 OUTPUT:
661 RETVAL
662
663=item T_BOOL
664
665A boolean type. This can be used to pass true and false values to and
666from C.
667
668=cut
669
670bool
671T_BOOL( in )
672 bool in
673 CODE:
674 RETVAL = in;
675 OUTPUT:
676 RETVAL
677
678=item T_U_INT
679
680This is for unsigned integers. It is equivalent to using T_UV
681but explicitly casts the variable to type C<unsigned int>.
682The default type for C<unsigned int> is T_UV.
683
604db645
SM
684=cut
685
686intUnsigned
687T_U_INT( uint )
688 intUnsigned uint
689 CODE:
690 RETVAL = uint;
691 OUTPUT:
692 RETVAL
693
ea035a69
JH
694=item T_SHORT
695
696Short integers. This is equivalent to T_IV but explicitly casts
697the return to type C<short>. The default typemap for C<short>
698is T_IV.
699
604db645
SM
700=cut
701
702short
703T_SHORT( s )
704 short s
705 CODE:
706 RETVAL = s;
707 OUTPUT:
708 RETVAL
709
ea035a69
JH
710=item T_U_SHORT
711
712Unsigned short integers. This is equivalent to T_UV but explicitly
713casts the return to type C<unsigned short>. The default typemap for
714C<unsigned short> is T_UV.
715
716T_U_SHORT is used for type C<U16> in the standard typemap.
717
718=cut
719
720U16
721T_U_SHORT( in )
722 U16 in
723 CODE:
724 RETVAL = in;
725 OUTPUT:
726 RETVAL
727
728
729=item T_LONG
730
731Long integers. This is equivalent to T_IV but explicitly casts
732the return to type C<long>. The default typemap for C<long>
733is T_IV.
734
604db645
SM
735=cut
736
737intTLONG
738T_LONG( in )
739 intTLONG in
740 CODE:
741 RETVAL = in;
742 OUTPUT:
743 RETVAL
744
ea035a69
JH
745=item T_U_LONG
746
747Unsigned long integers. This is equivalent to T_UV but explicitly
748casts the return to type C<unsigned long>. The default typemap for
749C<unsigned long> is T_UV.
750
751T_U_LONG is used for type C<U32> in the standard typemap.
752
753=cut
754
755U32
756T_U_LONG( in )
757 U32 in
758 CODE:
759 RETVAL = in;
760 OUTPUT:
761 RETVAL
762
763=item T_CHAR
764
765Single 8-bit characters.
766
767=cut
768
769char
770T_CHAR( in );
771 char in
772 CODE:
773 RETVAL = in;
774 OUTPUT:
775 RETVAL
776
777
778=item T_U_CHAR
779
780An unsigned byte.
781
782=cut
783
784unsigned char
785T_U_CHAR( in );
786 unsigned char in
787 CODE:
788 RETVAL = in;
789 OUTPUT:
790 RETVAL
791
792
793=item T_FLOAT
794
795A floating point number. This typemap guarantees to return a variable
796cast to a C<float>.
797
798=cut
799
800float
801T_FLOAT( in )
802 float in
803 CODE:
804 RETVAL = in;
805 OUTPUT:
806 RETVAL
807
808=item T_NV
809
810A Perl floating point number. Similar to T_IV and T_UV in that the
811return type is cast to the requested numeric type rather than
812to a specific type.
813
814=cut
815
816NV
817T_NV( in )
818 NV in
819 CODE:
820 RETVAL = in;
821 OUTPUT:
822 RETVAL
823
824=item T_DOUBLE
825
826A double precision floating point number. This typemap guarantees to
827return a variable cast to a C<double>.
828
829=cut
830
831double
832T_DOUBLE( in )
833 double in
834 CODE:
835 RETVAL = in;
836 OUTPUT:
837 RETVAL
838
839=item T_PV
840
841A string (char *).
842
843=cut
844
845char *
846T_PV( in )
847 char * in
848 CODE:
849 RETVAL = in;
850 OUTPUT:
851 RETVAL
852
853=item T_PTR
854
855A memory address (pointer). Typically associated with a C<void *>
856type.
857
858=cut
859
860# Pass in a value. Store the value in some static memory and
861# then return the pointer
862
863void *
864T_PTR_OUT( in )
865 int in;
866 CODE:
052980ee
TJ
867 xst_anint = in;
868 RETVAL = &xst_anint;
ea035a69
JH
869 OUTPUT:
870 RETVAL
871
872# pass in the pointer and return the value
873
874int
875T_PTR_IN( ptr )
876 void * ptr
877 CODE:
878 RETVAL = *(int *)ptr;
879 OUTPUT:
880 RETVAL
881
882=item T_PTRREF
883
884Similar to T_PTR except that the pointer is stored in a scalar and the
885reference to that scalar is returned to the caller. This can be used
886to hide the actual pointer value from the programmer since it is usually
887not required directly from within perl.
888
889The typemap checks that a scalar reference is passed from perl to XS.
890
891=cut
892
893# Similar test to T_PTR
894# Pass in a value. Store the value in some static memory and
895# then return the pointer
896
897intRef *
898T_PTRREF_OUT( in )
899 intRef in;
900 CODE:
052980ee
TJ
901 xst_anintref = in;
902 RETVAL = &xst_anintref;
ea035a69
JH
903 OUTPUT:
904 RETVAL
905
906# pass in the pointer and return the value
907
908intRef
909T_PTRREF_IN( ptr )
910 intRef * ptr
911 CODE:
912 RETVAL = *ptr;
913 OUTPUT:
914 RETVAL
915
916
917
918=item T_PTROBJ
919
920Similar to T_PTRREF except that the reference is blessed into a class.
921This allows the pointer to be used as an object. Most commonly used to
922deal with C structs. The typemap checks that the perl object passed
923into the XS routine is of the correct class (or part of a subclass).
924
925The pointer is blessed into a class that is derived from the name
926of type of the pointer but with all '*' in the name replaced with
927'Ptr'.
928
929=cut
930
931# Similar test to T_PTRREF
932# Pass in a value. Store the value in some static memory and
933# then return the pointer
934
935intObj *
936T_PTROBJ_OUT( in )
937 intObj in;
938 CODE:
052980ee
TJ
939 xst_anintobj = in;
940 RETVAL = &xst_anintobj;
ea035a69
JH
941 OUTPUT:
942 RETVAL
943
944# pass in the pointer and return the value
945
946MODULE = XS::Typemap PACKAGE = intObjPtr
947
948intObj
949T_PTROBJ_IN( ptr )
950 intObj * ptr
951 CODE:
952 RETVAL = *ptr;
953 OUTPUT:
954 RETVAL
955
956MODULE = XS::Typemap PACKAGE = XS::Typemap
957
958=item T_REF_IV_REF
959
960NOT YET
961
962=item T_REF_IV_PTR
963
964Similar to T_PTROBJ in that the pointer is blessed into a scalar object.
965The difference is that when the object is passed back into XS it must be
966of the correct type (inheritance is not supported).
967
968The pointer is blessed into a class that is derived from the name
969of type of the pointer but with all '*' in the name replaced with
970'Ptr'.
971
972=cut
973
974# Similar test to T_PTROBJ
975# Pass in a value. Store the value in some static memory and
976# then return the pointer
977
978intRefIv *
979T_REF_IV_PTR_OUT( in )
980 intRefIv in;
981 CODE:
052980ee
TJ
982 xst_anintrefiv = in;
983 RETVAL = &xst_anintrefiv;
ea035a69
JH
984 OUTPUT:
985 RETVAL
986
987# pass in the pointer and return the value
988
989MODULE = XS::Typemap PACKAGE = intRefIvPtr
990
991intRefIv
992T_REF_IV_PTR_IN( ptr )
993 intRefIv * ptr
994 CODE:
995 RETVAL = *ptr;
996 OUTPUT:
997 RETVAL
998
999
1000MODULE = XS::Typemap PACKAGE = XS::Typemap
1001
1002=item T_PTRDESC
1003
1004NOT YET
1005
1006=item T_REFREF
1007
d3ba6280
SM
1008Similar to T_PTRREF, except the pointer stored in the referenced scalar
1009is dereferenced and copied to the output variable. This means that
1010T_REFREF is to T_PTRREF as T_OPAQUE is to T_OPAQUEPTR. All clear?
1011
1012Only the INPUT part of this is implemented (Perl to XSUB) and there
1013are no known users in core or on CPAN.
1014
1015=cut
ea035a69
JH
1016
1017=item T_REFOBJ
1018
1019NOT YET
1020
1021=item T_OPAQUEPTR
1022
5abff6f9
TJ
1023This can be used to store bytes in the string component of the
1024SV. Here the representation of the data is irrelevant to perl and the
1025bytes themselves are just stored in the SV. It is assumed that the C
1026variable is a pointer (the bytes are copied from that memory
1027location). If the pointer is pointing to something that is
1028represented by 8 bytes then those 8 bytes are stored in the SV (and
1029length() will report a value of 8). This entry is similar to T_OPAQUE.
ea035a69 1030
5abff6f9
TJ
1031In principal the unpack() command can be used to convert the bytes
1032back to a number (if the underlying type is known to be a number).
1033
1034This entry can be used to store a C structure (the number
1035of bytes to be copied is calculated using the C C<sizeof> function)
1036and can be used as an alternative to T_PTRREF without having to worry
1037about a memory leak (since Perl will clean up the SV).
ea035a69
JH
1038
1039=cut
1040
1041intOpq *
1042T_OPAQUEPTR_IN( val )
1043 intOpq val
1044 CODE:
052980ee
TJ
1045 xst_anintopq = val;
1046 RETVAL = &xst_anintopq;
ea035a69
JH
1047 OUTPUT:
1048 RETVAL
1049
1050intOpq
1051T_OPAQUEPTR_OUT( ptr )
1052 intOpq * ptr
1053 CODE:
1054 RETVAL = *ptr;
1055 OUTPUT:
1056 RETVAL
1057
aa921f48
TJ
1058short
1059T_OPAQUEPTR_OUT_short( ptr )
1060 shortOPQ * ptr
1061 CODE:
1062 RETVAL = *ptr;
1063 OUTPUT:
1064 RETVAL
1065
5abff6f9
TJ
1066# Test it with a structure
1067astruct *
1068T_OPAQUEPTR_IN_struct( a,b,c )
1069 int a
1070 int b
1071 double c
1072 PREINIT:
1073 struct t_opaqueptr test;
1074 CODE:
1075 test.a = a;
1076 test.b = b;
1077 test.c = c;
1078 RETVAL = &test;
1079 OUTPUT:
1080 RETVAL
1081
1082void
1083T_OPAQUEPTR_OUT_struct( test )
1084 astruct * test
1085 PPCODE:
1086 XPUSHs(sv_2mortal(newSViv(test->a)));
1087 XPUSHs(sv_2mortal(newSViv(test->b)));
1088 XPUSHs(sv_2mortal(newSVnv(test->c)));
1089
1090
ea035a69
JH
1091=item T_OPAQUE
1092
5abff6f9
TJ
1093This can be used to store data from non-pointer types in the string
1094part of an SV. It is similar to T_OPAQUEPTR except that the
1095typemap retrieves the pointer directly rather than assuming it
ac23f157 1096is being supplied. For example, if an integer is imported into
052980ee
TJ
1097Perl using T_OPAQUE rather than T_IV the underlying bytes representing
1098the integer will be stored in the SV but the actual integer value will not
1099be available. i.e. The data is opaque to perl.
ea035a69 1100
5abff6f9
TJ
1101The data may be retrieved using the C<unpack> function if the
1102underlying type of the byte stream is known.
1103
1104T_OPAQUE supports input and output of simple types.
1105T_OPAQUEPTR can be used to pass these bytes back into C if a pointer
1106is acceptable.
ea035a69
JH
1107
1108=cut
1109
1110shortOPQ
1111T_OPAQUE_IN( val )
1112 int val
1113 CODE:
1114 RETVAL = (shortOPQ)val;
1115 OUTPUT:
1116 RETVAL
1117
5abff6f9
TJ
1118IV
1119T_OPAQUE_OUT( val )
1120 shortOPQ val
1121 CODE:
1122 RETVAL = (IV)val;
1123 OUTPUT:
1124 RETVAL
1125
ea035a69
JH
1126=item Implicit array
1127
1128xsubpp supports a special syntax for returning
1129packed C arrays to perl. If the XS return type is given as
1130
1131 array(type, nelem)
1132
1133xsubpp will copy the contents of C<nelem * sizeof(type)> bytes from
1134RETVAL to an SV and push it onto the stack. This is only really useful
1135if the number of items to be returned is known at compile time and you
1136don't mind having a string of bytes in your SV. Use T_ARRAY to push a
1137variable number of arguments onto the return stack (they won't be
1138packed as a single string though).
1139
1140This is similar to using T_OPAQUEPTR but can be used to process more than
1141one element.
1142
1143=cut
1144
1145array(int,3)
1146T_OPAQUE_array( a,b,c)
1147 int a
1148 int b
1149 int c
1150 PREINIT:
3d5d53b8 1151 int array[3];
ea035a69
JH
1152 CODE:
1153 array[0] = a;
1154 array[1] = b;
1155 array[2] = c;
1156 RETVAL = array;
1157 OUTPUT:
1158 RETVAL
1159
1160
1161=item T_PACKED
1162
f018eb7c
SM
1163Calls user-supplied functions for conversion. For C<OUTPUT>
1164(XSUB to Perl), a function named C<XS_pack_$ntype> is called
1165with the output Perl scalar and the C variable to convert from.
1166C<$ntype> is the normalized C type that is to be mapped to
1167Perl. Normalized means that all C<*> are replaced by the
1168string C<Ptr>. The return value of the function is ignored.
1169
1170Conversely for C<INPUT> (Perl to XSUB) mapping, the
1171function named C<XS_unpack_$ntype> is called with the input Perl
1172scalar as argument and the return value is cast to the mapped
1173C type and assigned to the output C variable.
1174
1175An example conversion function for a typemapped struct
1176C<foo_t *> might be:
1177
1178 static void
1179 XS_pack_foo_tPtr(SV *out, foo_t *in)
1180 {
2465d83f 1181 dTHX; /* alas, signature does not include pTHX_ */
f018eb7c
SM
1182 HV* hash = newHV();
1183 hv_stores(hash, "int_member", newSViv(in->int_member));
1184 hv_stores(hash, "float_member", newSVnv(in->float_member));
1185 /* ... */
1186
1187 /* mortalize as thy stack is not refcounted */
1188 sv_setsv(out, sv_2mortal(newRV_noinc((SV*)hash)));
1189 }
1190
1191The conversion from Perl to C is left as an exercise to the reader,
1192but the prototype would be:
1193
1194 static foo_t *
1195 XS_unpack_foo_tPtr(SV *in);
ea035a69 1196
2465d83f
SM
1197Instead of an actual C function that has to fetch the thread context
1198using C<dTHX>, you can define macros of the same name and avoid the
1199overhead. Also, keep in mind to possibly free the memory allocated by
1200C<XS_unpack_foo_tPtr>.
1201
1202=cut
1203
1204void
1205T_PACKED_in(in)
1206 anotherstruct *in;
1207 PPCODE:
1208 mXPUSHi(in->a);
1209 mXPUSHi(in->b);
1210 mXPUSHn(in->c);
1211 Safefree(in);
1212 XSRETURN(3);
1213
1214anotherstruct *
1215T_PACKED_out(a, b ,c)
1216 int a;
1217 int b;
1218 double c;
1219 CODE:
1220 Newxz(RETVAL, 1, anotherstruct);
1221 RETVAL->a = a;
1222 RETVAL->b = b;
1223 RETVAL->c = c;
1224 OUTPUT: RETVAL
1225 CLEANUP:
1226 Safefree(RETVAL);
1227
ea035a69
JH
1228=item T_PACKEDARRAY
1229
6b86c0f1
SM
1230T_PACKEDARRAY is similar to T_PACKED. In fact, the C<INPUT> (Perl
1231to XSUB) typemap is indentical, but the C<OUTPUT> typemap passes
1232an additional argument to the C<XS_pack_$ntype> function. This
1233third parameter indicates the number of elements in the output
1234so that the function can handle C arrays sanely. The variable
1235needs to be declared by the user and must have the name
1236C<count_$ntype> where C<$ntype> is the normalized C type name
1237as explained above. The signature of the function would be for
1238the example above and C<foo_t **>:
1239
1240 static void
1241 XS_pack_foo_tPtrPtr(SV *out, foo_t *in, UV count_foo_tPtrPtr);
1242
1243The type of the third parameter is arbitrary as far as the typemap
1244is concerned. It just has to be in line with the declared variable.
ea035a69 1245
ea0d3d8e
SM
1246Of course, unless you know the number of elements in the
1247C<sometype **> C array, within your XSUB, the return value from
1248C<foo_t ** XS_unpack_foo_tPtrPtr(...)> will be hard to decypher.
1249Since the details are all up to the XS author (the typemap user),
1250there are several solutions, none of which particularly elegant.
1251The most commonly seen solution has been to allocate memory for
1252N+1 pointers and assign C<NULL> to the (N+1)th to facilitate
1253iteration.
1254
1255Alternatively, using a customized typemap for your purposes in
1256the first place is probably preferrable.
1257
1258=cut
1259
1260void
1261T_PACKEDARRAY_in(in)
1262 anotherstruct **in;
1263 PREINIT:
1264 unsigned int i = 0;
1265 PPCODE:
1266 while (in[i] != NULL) {
1267 mXPUSHi(in[i]->a);
1268 mXPUSHi(in[i]->b);
1269 mXPUSHn(in[i]->c);
1270 ++i;
1271 }
1272 XS_release_anotherstructPtrPtr(in);
1273 XSRETURN(3*i);
1274
1275anotherstruct **
1276T_PACKEDARRAY_out(...)
1277 PREINIT:
1278 unsigned int i, nstructs, count_anotherstructPtrPtr;
1279 CODE:
1280 if ((items % 3) != 0)
1281 croak("Need nitems divisible by 3");
1282 nstructs = (unsigned int)(items / 3);
1283 count_anotherstructPtrPtr = nstructs;
1284 Newxz(RETVAL, nstructs+1, anotherstruct *);
1285 for (i = 0; i < nstructs; ++i) {
1286 Newxz(RETVAL[i], 1, anotherstruct);
1287 RETVAL[i]->a = SvIV(ST(3*i));
1288 RETVAL[i]->b = SvIV(ST(3*i+1));
1289 RETVAL[i]->c = SvNV(ST(3*i+2));
1290 }
1291 OUTPUT: RETVAL
1292 CLEANUP:
1293 XS_release_anotherstructPtrPtr(RETVAL);
1294
ea035a69
JH
1295=item T_DATAUNIT
1296
1297NOT YET
1298
1299=item T_CALLBACK
1300
1301NOT YET
1302
1303=item T_ARRAY
1304
1305This is used to convert the perl argument list to a C array
1306and for pushing the contents of a C array onto the perl
1307argument stack.
1308
1309The usual calling signature is
1310
1311 @out = array_func( @in );
1312
1313Any number of arguments can occur in the list before the array but
1314the input and output arrays must be the last elements in the list.
1315
1316When used to pass a perl list to C the XS writer must provide a
1317function (named after the array type but with 'Ptr' substituted for
1318'*') to allocate the memory required to hold the list. A pointer
1319should be returned. It is up to the XS writer to free the memory on
1320exit from the function. The variable C<ix_$var> is set to the number
1321of elements in the new array.
1322
1323When returning a C array to Perl the XS writer must provide an integer
1324variable called C<size_$var> containing the number of elements in the
1325array. This is used to determine how many elements should be pushed
1326onto the return argument stack. This is not required on input since
1327Perl knows how many arguments are on the stack when the routine is
1328called. Ordinarily this variable would be called C<size_RETVAL>.
1329
1330Additionally, the type of each element is determined from the type of
1331the array. If the array uses type C<intArray *> xsubpp will
1332automatically work out that it contains variables of type C<int> and
1333use that typemap entry to perform the copy of each element. All
1334pointer '*' and 'Array' tags are removed from the name to determine
1335the subtype.
1336
1337=cut
1338
1339# Test passes in an integer array and returns it along with
1340# the number of elements
1341# Pass in a dummy value to test offsetting
1342
1343# Problem is that xsubpp does XSRETURN(1) because we arent
1344# using PPCODE. This means that only the first element
1345# is returned. KLUGE this by using CLEANUP to return before the
1346# end.
ac23f157
SM
1347# Note: I read this as: The "T_ARRAY" typemap is really rather broken,
1348# at least for OUTPUT. That is apart from the general design
1349# weaknesses. --Steffen
ea035a69
JH
1350
1351intArray *
1352T_ARRAY( dummy, array, ... )
4d0439ce 1353 int dummy = 0;
ea035a69
JH
1354 intArray * array
1355 PREINIT:
1356 U32 size_RETVAL;
1357 CODE:
8876ff82 1358 dummy += 0; /* Fix -Wall */
ea035a69
JH
1359 size_RETVAL = ix_array;
1360 RETVAL = array;
1361 OUTPUT:
1362 RETVAL
1363 CLEANUP:
1364 Safefree(array);
1365 XSRETURN(size_RETVAL);
1366
1367
1368=item T_STDIO
1369
1370This is used for passing perl filehandles to and from C using
1371C<FILE *> structures.
1372
1373=cut
1374
1375FILE *
1376T_STDIO_open( file )
1377 const char * file
1378 CODE:
1379 RETVAL = xsfopen( file );
1380 OUTPUT:
1381 RETVAL
1382
1383SysRet
c72de6e4
TJ
1384T_STDIO_close( f )
1385 PerlIO * f
1386 PREINIT:
1387 FILE * stream;
ea035a69 1388 CODE:
c72de6e4
TJ
1389 /* Get the FILE* */
1390 stream = PerlIO_findFILE( f );
c72de6e4
TJ
1391 /* Release the FILE* from the PerlIO system so that we do
1392 not close the file twice */
1393 PerlIO_releaseFILE(f,stream);
6b54a403
NC
1394 /* Must release the file before closing it */
1395 RETVAL = xsfclose( stream );
ea035a69
JH
1396 OUTPUT:
1397 RETVAL
1398
1399int
1400T_STDIO_print( stream, string )
1401 FILE * stream
1402 const char * string
1403 CODE:
1404 RETVAL = xsfprintf( stream, string );
1405 OUTPUT:
1406 RETVAL
1407
1408
ea035a69
JH
1409=item T_INOUT
1410
1411This is used for passing perl filehandles to and from C using
1412C<PerlIO *> structures. The file handle can used for reading and
21b5216d
SM
1413writing. This corresponds to the C<+E<lt>> mode, see also T_IN
1414and T_OUT.
ea035a69
JH
1415
1416See L<perliol> for more information on the Perl IO abstraction
1417layer. Perl must have been built with C<-Duseperlio>.
1418
21b5216d
SM
1419There is no check to assert that the filehandle passed from Perl
1420to C was created with the right C<open()> mode.
1421
0a442273
SM
1422=cut
1423
1424PerlIO *
1425T_INOUT(in)
1426 PerlIO *in;
1427 CODE:
1428 RETVAL = in; /* silly test but better than nothing */
1429 OUTPUT: RETVAL
1430
21b5216d
SM
1431=item T_IN
1432
1433Same as T_INOUT, but the filehandle that is returned from C to Perl
1434can only be used for reading (mode C<E<lt>>).
1435
1436=cut
1437
1438inputfh
1439T_IN(in)
1440 inputfh in;
1441 CODE:
1442 RETVAL = in; /* silly test but better than nothing */
1443 OUTPUT: RETVAL
1444
ea035a69
JH
1445=item T_OUT
1446
21b5216d
SM
1447Same as T_INOUT, but the filehandle that is returned from C to Perl
1448is set to use the open mode C<+E<gt>>.
ea035a69
JH
1449
1450=back
1451
1452=cut
1453
21b5216d
SM
1454outputfh
1455T_OUT(in)
1456 outputfh in;
1457 CODE:
1458 RETVAL = in; /* silly test but better than nothing */
1459 OUTPUT: RETVAL
1460