XS::Typemap: Tests for T_IN/T_OUT typemaps
[perl.git] / ext / XS-Typemap / Typemap.xs
1 /*
2    XS code to test the typemap entries
3
4    Copyright (C) 2001 Tim Jenness.
5    All Rights Reserved
6
7 */
8
9 #define PERL_NO_GET_CONTEXT
10
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 */
16 FILE * xsfopen( const char * );
17 int xsfclose( FILE * );
18 int xsfprintf( FILE *, const char *);
19
20 /* Type definitions required for the XS typemaps */
21 typedef SV * SVREF; /* T_SVREF */
22 typedef int SysRet; /* T_SYSRET */
23 typedef int Int;    /* T_INT */
24 typedef int intRef; /* T_PTRREF */
25 typedef int intObj; /* T_PTROBJ */
26 typedef int intRefIv; /* T_REF_IV_PTR */
27 typedef int intArray; /* T_ARRAY */
28 typedef int intTINT; /* T_INT */
29 typedef int intTLONG; /* T_LONG */
30 typedef short shortOPQ;   /* T_OPAQUE */
31 typedef int intOpq;   /* T_OPAQUEPTR */
32 typedef unsigned intUnsigned; /* T_U_INT */
33 typedef PerlIO inputfh; /* T_IN */
34 typedef PerlIO outputfh; /* T_OUT */
35
36 /* A structure to test T_OPAQUEPTR and T_PACKED */
37 struct t_opaqueptr {
38   int a;
39   int b;
40   double c;
41 };
42
43 typedef struct t_opaqueptr astruct;
44 typedef struct t_opaqueptr anotherstruct;
45
46 /* Some static memory for the tests */
47 static I32 xst_anint;
48 static intRef xst_anintref;
49 static intObj xst_anintobj;
50 static intRefIv xst_anintrefiv;
51 static intOpq xst_anintopq;
52
53 /* A different type to refer to for testing the different
54  * AV*, HV*, etc typemaps */
55 typedef AV AV_FIXED;
56 typedef HV HV_FIXED;
57 typedef CV CV_FIXED;
58 typedef SVREF SVREF_FIXED;
59
60 /* Helper functions */
61
62 /* T_ARRAY - allocate some memory */
63 intArray * intArrayPtr( int nelem ) {
64     intArray * array;
65     Newx(array, nelem, intArray);
66     return array;
67 }
68
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
79 STATIC anotherstruct *
80 XS_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
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
130 STATIC anotherstruct **
131 XS_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 */
193 void
194 XS_release_anotherstructPtrPtr(anotherstruct **in)
195 {
196   unsigned int i = 0;
197   while (in[i] != NULL)
198     Safefree(in[i++]);
199   Safefree(in);
200 }
201
202
203 MODULE = XS::Typemap   PACKAGE = XS::Typemap
204
205 PROTOTYPES: DISABLE
206
207 TYPEMAP: <<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
215 svtype           T_ENUM
216 intRef *         T_PTRREF
217 intRef           T_IV
218 intObj *         T_PTROBJ
219 intObj           T_IV
220 intRefIv *       T_REF_IV_PTR
221 intRefIv         T_IV
222 intArray *       T_ARRAY
223 intOpq           T_IV
224 intOpq   *       T_OPAQUEPTR
225 intUnsigned      T_U_INT
226 intTINT          T_INT
227 intTLONG         T_LONG
228 shortOPQ         T_OPAQUE
229 shortOPQ *       T_OPAQUEPTR
230 astruct *        T_OPAQUEPTR
231 anotherstruct *  T_PACKED
232 anotherstruct ** T_PACKEDARRAY
233 AV_FIXED *       T_AVREF_REFCOUNT_FIXED
234 HV_FIXED *       T_HVREF_REFCOUNT_FIXED
235 CV_FIXED *       T_CVREF_REFCOUNT_FIXED
236 SVREF_FIXED      T_SVREF_REFCOUNT_FIXED
237 inputfh          T_IN
238 outputfh         T_OUT
239
240 END_OF_TYPEMAP
241
242 =head1 TYPEMAPS
243
244 The more you think about interfacing between two languages, the more
245 you'll realize that the majority of programmer effort has to go into
246 converting between the data structures that are native to either of
247 the languages involved. This trumps other matter such as differing
248 calling conventions because the problem space is so much greater.
249 There are simply more ways to shove data into memory than there are
250 ways to implement a function call.
251
252 Perl XS' attempt at a solution to this is the concept of typemaps.
253 At an abstract level, a Perl XS typemap is nothing but a recipe for
254 converting from a certain Perl data structure to a certain C
255 data structure and/or vice versa. Since there can be C types that
256 are sufficiently similar to warrant converting with the same logic,
257 XS typemaps are represented by a unique identifier, called XS type
258 henceforth in this document. You can then tell the XS compiler that
259 multiple C types are to be mapped with the same XS typemap.
260
261 In your XS code, when you define an argument with a C type or when
262 you are using a C<CODE:> and an C<OUTPUT:> section together with a
263 C return type of your XSUB, it'll be the typemapping mechanism that
264 makes this easy.
265
266 =head2 Anatomy of a typemap File
267
268 Traditionally, typemaps needed to be written to a separate file,
269 conventionally called C<typemap>. With ExtUtils::ParseXS (the XS
270 compiler) version 3.00 or better (comes with perl 5.16), typemaps
271 can also be embedded directly into your XS code using a HERE-doc
272 like syntax:
273
274   TYPEMAP: <<HERE
275   ...
276   HERE
277
278 where C<HERE> can be replaced by other identifiers like with normal
279 Perl HERE-docs. All details below about the typemap textual format
280 remain valid.
281
282 A typemap file generally has three sections: The C<TYPEMAP>
283 section is used to associate C types with XS type identifiers.
284 The C<INPUT> section is used to define the typemaps for I<input>
285 into the XSUB from Perl, and the C<OUTPUT> section has the opposite
286 conversion logic for getting data out of an XSUB back into Perl.
287
288 Each section is started by the section name in capital letters on a
289 line of its own. A typemap file implicitly starts in the C<TYPEMAP>
290 section. Each type of section can appear an arbitrary number of times
291 and does not have to appear at all. For example, a typemap file may
292 lack C<INPUT> and C<OUTPUT> sections if all it needs to do is
293 associate additional C types with core XS types like T_PTROBJ.
294 Lines that start with a hash C<#> are considered comments and ignored
295 in the C<TYPEMAP> section, but are considered significant in C<INPUT>
296 and C<OUTPUT>. Blank lines are generally ignored.
297
298 The C<TYPEMAP> section should contain one pair of C type and
299 XS 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
308 The C<INPUT> and C<OUTPUT> sections have identical formats, that is,
309 each unindented line starts a new in- or output map respectively.
310 A new in- or output map must start with the name of the XS type to
311 map on a line by itself, followed by the code that implements it
312 indented 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
320 We'll get to the meaning of those Perlish-looking variables in a
321 little bit.
322
323 Finally, here's an example of the full typemap file for mapping C
324 strings 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);
336
337 =head2 The Role of the typemap File in Your Distribution
338
339 For CPAN distributions, you can assume that the XS types defined by
340 the perl core are already available. Additionally, the core typemap
341 has default XS types for a large number of C types. For example, if
342 you simply return a C<char *> from your XSUB, the core typemap will
343 have this C type associated with the T_PV XS type. That means your
344 C string will be copied into the PV (pointer value) slot of a new scalar
345 that will be returned from your XSUB to to Perl.
346
347 If you're developing a CPAN distribution using XS, you may add your own
348 file called F<typemap> to the distribution. That file may contain
349 typemaps that either map types that are specific to your code or that
350 override the core typemap file's mappings for common C types.
351
352 =head2 Sharing typemaps Between CPAN Distributions
353
354 Starting with ExtUtils::ParseXS version 3.12 (comes with perl 5.16
355 and better), it is rather easy to share typemap code between multiple
356 CPAN distributions. The general idea is to share it as a module that
357 offers a certain API and have the dependent modules declare that as a
358 built-time requirement and import the typemap into the XS. An example
359 of such a typemap-sharing module on CPAN is
360 C<ExtUtils::Typemaps::Basic>. Two steps to getting that module's
361 typemaps available in your code:
362
363 =over 4
364
365 =item *
366
367 Declare C<ExtUtils::Typemaps::Basic> as a built-time dependency
368 in C<Makefile.PL> (use C<BUILD_REQUIRES>), or in your C<Build.PL>
369 (use C<build_requires>).
370
371 =item *
372
373 Include 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
381 =head2 Full Listing of Core Typemaps
382
383 Each C type is represented by an entry in the typemap file that
384 is responsible for converting perl variables (SV, AV, HV, CV, etc.)
385 to and from that type. The following sections list all XS types
386 that come with perl by default.
387
388 =over 4
389
390 =item T_SV
391
392 This simply passes the C representation of the Perl variable (an SV*)
393 in and out of the XS layer. This can be used if the C code wants
394 to deal directly with the Perl variable.
395
396 =cut
397
398 SV *
399 T_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
415 Used to pass in and return a reference to an SV.
416
417 Note that this typemap does not decrement the reference count
418 when returning the reference to an SV*.
419 See also: T_SVREF_REFCOUNT_FIXED
420
421 =cut
422
423 SVREF
424 T_SVREF( svref )
425   SVREF svref
426  CODE:
427   RETVAL = svref;
428  OUTPUT:
429   RETVAL
430
431 =item T_SVREF_FIXED
432
433 Used to pass in and return a reference to an SV.
434 This is a fixed
435 variant of T_SVREF that decrements the refcount appropriately
436 when returning a reference to an SV*. Introduced in perl 5.15.4.
437
438 =cut
439
440 SVREF_FIXED
441 T_SVREF_REFCOUNT_FIXED( svref )
442   SVREF_FIXED svref
443  CODE:
444   SvREFCNT_inc(svref);
445   RETVAL = svref;
446  OUTPUT:
447   RETVAL
448
449 =item T_AVREF
450
451 From the perl level this is a reference to a perl array.
452 From the C level this is a pointer to an AV.
453
454 Note that this typemap does not decrement the reference count
455 when returning an AV*. See also: T_AVREF_REFCOUNT_FIXED
456
457 =cut
458
459 AV *
460 T_AVREF( av )
461   AV * av
462  CODE:
463   RETVAL = av;
464  OUTPUT:
465   RETVAL
466
467 =item T_AVREF_REFCOUNT_FIXED
468
469 From the perl level this is a reference to a perl array.
470 From the C level this is a pointer to an AV. This is a fixed
471 variant of T_AVREF that decrements the refcount appropriately
472 when returning an AV*. Introduced in perl 5.15.4.
473
474 =cut
475
476 AV_FIXED*
477 T_AVREF_REFCOUNT_FIXED( av )
478   AV_FIXED * av
479  CODE:
480   SvREFCNT_inc(av);
481   RETVAL = av;
482  OUTPUT:
483   RETVAL
484
485 =item T_HVREF
486
487 From the perl level this is a reference to a perl hash.
488 From the C level this is a pointer to an HV.
489
490 Note that this typemap does not decrement the reference count
491 when returning an HV*. See also: T_HVREF_REFCOUNT_FIXED
492
493 =cut
494
495 HV *
496 T_HVREF( hv )
497   HV * hv
498  CODE:
499   RETVAL = hv;
500  OUTPUT:
501   RETVAL
502
503 =item T_HVREF_REFCOUNT_FIXED
504
505 From the perl level this is a reference to a perl hash.
506 From the C level this is a pointer to an HV. This is a fixed
507 variant of T_HVREF that decrements the refcount appropriately
508 when returning an HV*. Introduced in perl 5.15.4.
509
510 =cut
511
512 HV_FIXED*
513 T_HVREF_REFCOUNT_FIXED( hv )
514   HV_FIXED * hv
515  CODE:
516   SvREFCNT_inc(hv);
517   RETVAL = hv;
518  OUTPUT:
519   RETVAL
520
521
522 =item T_CVREF
523
524 From 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
526 to a CV.
527
528 Note that this typemap does not decrement the reference count
529 when returning an HV*. See also: T_HVREF_REFCOUNT_FIXED
530
531 =cut
532
533 CV *
534 T_CVREF( cv )
535   CV * cv
536  CODE:
537   RETVAL = cv;
538  OUTPUT:
539   RETVAL
540
541 =item T_CVREF_REFCOUNT_FIXED
542
543 From 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
545 to a CV.
546
547 This is a fixed
548 variant of T_HVREF that decrements the refcount appropriately
549 when returning an HV*. Introduced in perl 5.15.4.
550
551 =cut
552
553 CV_FIXED *
554 T_CVREF_REFCOUNT_FIXED( cv )
555   CV_FIXED * cv
556  CODE:
557   SvREFCNT_inc(cv);
558   RETVAL = cv;
559  OUTPUT:
560   RETVAL
561
562 =item T_SYSRET
563
564 The T_SYSRET typemap is used to process return values from system calls.
565 It is only meaningful when passing values from C to perl (there is
566 no concept of passing a system return value from Perl to C).
567
568 System calls return -1 on error (setting ERRNO with the reason)
569 and (usually) 0 on success. If the return value is -1 this typemap
570 returns C<undef>. If the return value is not -1, this typemap
571 translates a 0 (perl false) to "0 but true" (which
572 is perl true) or returns the value itself, to indicate that the
573 command succeeded.
574
575 The L<POSIX|POSIX> module makes extensive use of this type.
576
577 =cut
578
579 # Test a successful return
580
581 SysRet
582 T_SYSRET_pass()
583  CODE:
584   RETVAL = 0;
585  OUTPUT:
586   RETVAL
587
588 # Test failure
589
590 SysRet
591 T_SYSRET_fail()
592  CODE:
593   RETVAL = -1;
594  OUTPUT:
595   RETVAL
596
597 =item T_UV
598
599 An unsigned integer.
600
601 =cut
602
603 unsigned int
604 T_UV( uv )
605   unsigned int uv
606  CODE:
607   RETVAL = uv;
608  OUTPUT:
609   RETVAL
610
611 =item T_IV
612
613 A signed integer. This is cast to the required integer type when
614 passed to C and converted to an IV when passed back to Perl.
615
616 =cut
617
618 long
619 T_IV( iv )
620   long iv
621  CODE:
622   RETVAL = iv;
623  OUTPUT:
624   RETVAL
625
626 =item T_INT
627
628 A signed integer. This typemap converts the Perl value to a native
629 integer type (the C<int> type on the current platform). When returning
630 the value to perl it is processed in the same way as for T_IV.
631
632 Its behaviour is identical to using an C<int> type in XS with T_IV.
633
634 =cut
635
636 intTINT
637 T_INT( i )
638   intTINT i
639  CODE:
640   RETVAL = i;
641  OUTPUT:
642   RETVAL
643
644 =item T_ENUM
645
646 An enum value. Used to transfer an enum component
647 from C. There is no reason to pass an enum value to C since
648 it 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
656 svtype
657 T_ENUM()
658  CODE:
659   RETVAL = SVt_PVHV;
660  OUTPUT:
661   RETVAL
662
663 =item T_BOOL
664
665 A boolean type. This can be used to pass true and false values to and
666 from C.
667
668 =cut
669
670 bool
671 T_BOOL( in )
672   bool in
673  CODE:
674   RETVAL = in;
675  OUTPUT:
676   RETVAL
677
678 =item T_U_INT
679
680 This is for unsigned integers. It is equivalent to using T_UV
681 but explicitly casts the variable to type C<unsigned int>.
682 The default type for C<unsigned int> is T_UV.
683
684 =cut
685
686 intUnsigned
687 T_U_INT( uint )
688   intUnsigned uint
689  CODE:
690   RETVAL = uint;
691  OUTPUT:
692   RETVAL
693
694 =item T_SHORT
695
696 Short integers. This is equivalent to T_IV but explicitly casts
697 the return to type C<short>. The default typemap for C<short>
698 is T_IV.
699
700 =cut
701
702 short
703 T_SHORT( s )
704   short s
705  CODE:
706   RETVAL = s;
707  OUTPUT:
708   RETVAL
709
710 =item T_U_SHORT
711
712 Unsigned short integers. This is equivalent to T_UV but explicitly
713 casts the return to type C<unsigned short>. The default typemap for
714 C<unsigned short> is T_UV.
715
716 T_U_SHORT is used for type C<U16> in the standard typemap.
717
718 =cut
719
720 U16
721 T_U_SHORT( in )
722   U16 in
723  CODE:
724   RETVAL = in;
725  OUTPUT:
726   RETVAL
727
728
729 =item T_LONG
730
731 Long integers. This is equivalent to T_IV but explicitly casts
732 the return to type C<long>. The default typemap for C<long>
733 is T_IV.
734
735 =cut
736
737 intTLONG
738 T_LONG( in )
739   intTLONG in
740  CODE:
741   RETVAL = in;
742  OUTPUT:
743   RETVAL
744
745 =item T_U_LONG
746
747 Unsigned long integers. This is equivalent to T_UV but explicitly
748 casts the return to type C<unsigned long>. The default typemap for
749 C<unsigned long> is T_UV.
750
751 T_U_LONG is used for type C<U32> in the standard typemap.
752
753 =cut
754
755 U32
756 T_U_LONG( in )
757   U32 in
758  CODE:
759   RETVAL = in;
760  OUTPUT:
761   RETVAL
762
763 =item T_CHAR
764
765 Single 8-bit characters.
766
767 =cut
768
769 char
770 T_CHAR( in );
771   char in
772  CODE:
773   RETVAL = in;
774  OUTPUT:
775   RETVAL
776
777
778 =item T_U_CHAR
779
780 An unsigned byte.
781
782 =cut
783
784 unsigned char
785 T_U_CHAR( in );
786   unsigned char in
787  CODE:
788   RETVAL = in;
789  OUTPUT:
790   RETVAL
791
792
793 =item T_FLOAT
794
795 A floating point number. This typemap guarantees to return a variable
796 cast to a C<float>.
797
798 =cut
799
800 float
801 T_FLOAT( in )
802   float in
803  CODE:
804   RETVAL = in;
805  OUTPUT:
806   RETVAL
807
808 =item T_NV
809
810 A Perl floating point number. Similar to T_IV and T_UV in that the
811 return type is cast to the requested numeric type rather than
812 to a specific type.
813
814 =cut
815
816 NV
817 T_NV( in )
818   NV in
819  CODE:
820   RETVAL = in;
821  OUTPUT:
822   RETVAL
823
824 =item T_DOUBLE
825
826 A double precision floating point number. This typemap guarantees to
827 return a variable cast to a C<double>.
828
829 =cut
830
831 double
832 T_DOUBLE( in )
833   double in
834  CODE:
835   RETVAL = in;
836  OUTPUT:
837   RETVAL
838
839 =item T_PV
840
841 A string (char *).
842
843 =cut
844
845 char *
846 T_PV( in )
847   char * in
848  CODE:
849   RETVAL = in;
850  OUTPUT:
851   RETVAL
852
853 =item T_PTR
854
855 A memory address (pointer). Typically associated with a C<void *>
856 type.
857
858 =cut
859
860 # Pass in a value. Store the value in some static memory and
861 # then return the pointer
862
863 void *
864 T_PTR_OUT( in )
865   int in;
866  CODE:
867   xst_anint = in;
868   RETVAL = &xst_anint;
869  OUTPUT:
870   RETVAL
871
872 # pass in the pointer and return the value
873
874 int
875 T_PTR_IN( ptr )
876   void * ptr
877  CODE:
878   RETVAL = *(int *)ptr;
879  OUTPUT:
880   RETVAL
881
882 =item T_PTRREF
883
884 Similar to T_PTR except that the pointer is stored in a scalar and the
885 reference to that scalar is returned to the caller. This can be used
886 to hide the actual pointer value from the programmer since it is usually
887 not required directly from within perl.
888
889 The 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
897 intRef *
898 T_PTRREF_OUT( in )
899   intRef in;
900  CODE:
901   xst_anintref = in;
902   RETVAL = &xst_anintref;
903  OUTPUT:
904   RETVAL
905
906 # pass in the pointer and return the value
907
908 intRef
909 T_PTRREF_IN( ptr )
910   intRef * ptr
911  CODE:
912   RETVAL = *ptr;
913  OUTPUT:
914   RETVAL
915
916
917
918 =item T_PTROBJ
919
920 Similar to T_PTRREF except that the reference is blessed into a class.
921 This allows the pointer to be used as an object. Most commonly used to
922 deal with C structs. The typemap checks that the perl object passed
923 into the XS routine is of the correct class (or part of a subclass).
924
925 The pointer is blessed into a class that is derived from the name
926 of 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
935 intObj *
936 T_PTROBJ_OUT( in )
937   intObj in;
938  CODE:
939   xst_anintobj = in;
940   RETVAL = &xst_anintobj;
941  OUTPUT:
942   RETVAL
943
944 # pass in the pointer and return the value
945
946 MODULE = XS::Typemap  PACKAGE = intObjPtr
947
948 intObj
949 T_PTROBJ_IN( ptr )
950   intObj * ptr
951  CODE:
952   RETVAL = *ptr;
953  OUTPUT:
954   RETVAL
955
956 MODULE = XS::Typemap PACKAGE = XS::Typemap
957
958 =item T_REF_IV_REF
959
960 NOT YET
961
962 =item T_REF_IV_PTR
963
964 Similar to T_PTROBJ in that the pointer is blessed into a scalar object.
965 The difference is that when the object is passed back into XS it must be
966 of the correct type (inheritance is not supported).
967
968 The pointer is blessed into a class that is derived from the name
969 of 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
978 intRefIv *
979 T_REF_IV_PTR_OUT( in )
980   intRefIv in;
981  CODE:
982   xst_anintrefiv = in;
983   RETVAL = &xst_anintrefiv;
984  OUTPUT:
985   RETVAL
986
987 # pass in the pointer and return the value
988
989 MODULE = XS::Typemap  PACKAGE = intRefIvPtr
990
991 intRefIv
992 T_REF_IV_PTR_IN( ptr )
993   intRefIv * ptr
994  CODE:
995   RETVAL = *ptr;
996  OUTPUT:
997   RETVAL
998
999
1000 MODULE = XS::Typemap PACKAGE = XS::Typemap
1001
1002 =item T_PTRDESC
1003
1004 NOT YET
1005
1006 =item T_REFREF
1007
1008 Similar to T_PTRREF, except the pointer stored in the referenced scalar
1009 is dereferenced and copied to the output variable. This means that
1010 T_REFREF is to T_PTRREF as T_OPAQUE is to T_OPAQUEPTR. All clear?
1011
1012 Only the INPUT part of this is implemented (Perl to XSUB) and there
1013 are no known users in core or on CPAN.
1014
1015 =cut
1016
1017 =item T_REFOBJ
1018
1019 NOT YET
1020
1021 =item T_OPAQUEPTR
1022
1023 This can be used to store bytes in the string component of the
1024 SV. Here the representation of the data is irrelevant to perl and the
1025 bytes themselves are just stored in the SV. It is assumed that the C
1026 variable is a pointer (the bytes are copied from that memory
1027 location).  If the pointer is pointing to something that is
1028 represented by 8 bytes then those 8 bytes are stored in the SV (and
1029 length() will report a value of 8). This entry is similar to T_OPAQUE.
1030
1031 In principal the unpack() command can be used to convert the bytes
1032 back to a number (if the underlying type is known to be a number).
1033
1034 This entry can be used to store a C structure (the number
1035 of bytes to be copied is calculated using the C C<sizeof> function)
1036 and can be used as an alternative to T_PTRREF without having to worry
1037 about a memory leak (since Perl will clean up the SV).
1038
1039 =cut
1040
1041 intOpq *
1042 T_OPAQUEPTR_IN( val )
1043   intOpq val
1044  CODE:
1045   xst_anintopq = val;
1046   RETVAL = &xst_anintopq;
1047  OUTPUT:
1048   RETVAL
1049
1050 intOpq
1051 T_OPAQUEPTR_OUT( ptr )
1052   intOpq * ptr
1053  CODE:
1054   RETVAL = *ptr;
1055  OUTPUT:
1056   RETVAL
1057
1058 short
1059 T_OPAQUEPTR_OUT_short( ptr )
1060   shortOPQ * ptr
1061  CODE:
1062   RETVAL = *ptr;
1063  OUTPUT:
1064   RETVAL
1065
1066 # Test it with a structure
1067 astruct *
1068 T_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
1082 void
1083 T_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
1091 =item T_OPAQUE
1092
1093 This can be used to store data from non-pointer types in the string
1094 part of an SV. It is similar to T_OPAQUEPTR except that the
1095 typemap retrieves the pointer directly rather than assuming it
1096 is being supplied. For example, if an integer is imported into
1097 Perl using T_OPAQUE rather than T_IV the underlying bytes representing
1098 the integer will be stored in the SV but the actual integer value will not
1099 be available. i.e. The data is opaque to perl.
1100
1101 The data may be retrieved using the C<unpack> function if the
1102 underlying type of the byte stream is known.
1103
1104 T_OPAQUE supports input and output of simple types.
1105 T_OPAQUEPTR can be used to pass these bytes back into C if a pointer
1106 is acceptable.
1107
1108 =cut
1109
1110 shortOPQ
1111 T_OPAQUE_IN( val )
1112   int val
1113  CODE:
1114   RETVAL = (shortOPQ)val;
1115  OUTPUT:
1116   RETVAL
1117
1118 IV
1119 T_OPAQUE_OUT( val )
1120   shortOPQ val
1121  CODE:
1122   RETVAL = (IV)val;
1123  OUTPUT:
1124   RETVAL
1125
1126 =item Implicit array
1127
1128 xsubpp supports a special syntax for returning
1129 packed C arrays to perl. If the XS return type is given as
1130
1131   array(type, nelem)
1132
1133 xsubpp will copy the contents of C<nelem * sizeof(type)> bytes from
1134 RETVAL to an SV and push it onto the stack. This is only really useful
1135 if the number of items to be returned is known at compile time and you
1136 don't mind having a string of bytes in your SV.  Use T_ARRAY to push a
1137 variable number of arguments onto the return stack (they won't be
1138 packed as a single string though).
1139
1140 This is similar to using T_OPAQUEPTR but can be used to process more than
1141 one element.
1142
1143 =cut
1144
1145 array(int,3)
1146 T_OPAQUE_array( a,b,c)
1147   int a
1148   int b
1149   int c
1150  PREINIT:
1151   int array[3];
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
1163 Calls user-supplied functions for conversion. For C<OUTPUT>
1164 (XSUB to Perl), a function named C<XS_pack_$ntype> is called
1165 with the output Perl scalar and the C variable to convert from.
1166 C<$ntype> is the normalized C type that is to be mapped to
1167 Perl. Normalized means that all C<*> are replaced by the
1168 string C<Ptr>. The return value of the function is ignored.
1169
1170 Conversely for C<INPUT> (Perl to XSUB) mapping, the
1171 function named C<XS_unpack_$ntype> is called with the input Perl
1172 scalar as argument and the return value is cast to the mapped
1173 C type and assigned to the output C variable.
1174
1175 An example conversion function for a typemapped struct
1176 C<foo_t *> might be:
1177
1178   static void
1179   XS_pack_foo_tPtr(SV *out, foo_t *in)
1180   {
1181     dTHX; /* alas, signature does not include pTHX_ */
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
1191 The conversion from Perl to C is left as an exercise to the reader,
1192 but the prototype would be:
1193
1194   static foo_t *
1195   XS_unpack_foo_tPtr(SV *in);
1196
1197 Instead of an actual C function that has to fetch the thread context
1198 using C<dTHX>, you can define macros of the same name and avoid the
1199 overhead. Also, keep in mind to possibly free the memory allocated by
1200 C<XS_unpack_foo_tPtr>.
1201
1202 =cut
1203
1204 void
1205 T_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
1214 anotherstruct *
1215 T_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
1228 =item T_PACKEDARRAY
1229
1230 T_PACKEDARRAY is similar to T_PACKED. In fact, the C<INPUT> (Perl
1231 to XSUB) typemap is indentical, but the C<OUTPUT> typemap passes
1232 an additional argument to the C<XS_pack_$ntype> function. This
1233 third parameter indicates the number of elements in the output
1234 so that the function can handle C arrays sanely. The variable
1235 needs to be declared by the user and must have the name
1236 C<count_$ntype> where C<$ntype> is the normalized C type name
1237 as explained above. The signature of the function would be for
1238 the 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
1243 The type of the third parameter is arbitrary as far as the typemap
1244 is concerned. It just has to be in line with the declared variable.
1245
1246 Of course, unless you know the number of elements in the
1247 C<sometype **> C array, within your XSUB, the return value from
1248 C<foo_t ** XS_unpack_foo_tPtrPtr(...)> will be hard to decypher.
1249 Since the details are all up to the XS author (the typemap user),
1250 there are several solutions, none of which particularly elegant.
1251 The most commonly seen solution has been to allocate memory for
1252 N+1 pointers and assign C<NULL> to the (N+1)th to facilitate
1253 iteration.
1254
1255 Alternatively, using a customized typemap for your purposes in
1256 the first place is probably preferrable.
1257
1258 =cut
1259
1260 void
1261 T_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
1275 anotherstruct **
1276 T_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
1295 =item T_DATAUNIT
1296
1297 NOT YET
1298
1299 =item T_CALLBACK
1300
1301 NOT YET
1302
1303 =item T_ARRAY
1304
1305 This is used to convert the perl argument list to a C array
1306 and for pushing the contents of a C array onto the perl
1307 argument stack.
1308
1309 The usual calling signature is
1310
1311   @out = array_func( @in );
1312
1313 Any number of arguments can occur in the list before the array but
1314 the input and output arrays must be the last elements in the list.
1315
1316 When used to pass a perl list to C the XS writer must provide a
1317 function (named after the array type but with 'Ptr' substituted for
1318 '*') to allocate the memory required to hold the list. A pointer
1319 should be returned. It is up to the XS writer to free the memory on
1320 exit from the function. The variable C<ix_$var> is set to the number
1321 of elements in the new array.
1322
1323 When returning a C array to Perl the XS writer must provide an integer
1324 variable called C<size_$var> containing the number of elements in the
1325 array. This is used to determine how many elements should be pushed
1326 onto the return argument stack. This is not required on input since
1327 Perl knows how many arguments are on the stack when the routine is
1328 called. Ordinarily this variable would be called C<size_RETVAL>.
1329
1330 Additionally, the type of each element is determined from the type of
1331 the array. If the array uses type C<intArray *> xsubpp will
1332 automatically work out that it contains variables of type C<int> and
1333 use that typemap entry to perform the copy of each element. All
1334 pointer '*' and 'Array' tags are removed from the name to determine
1335 the 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.
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
1350
1351 intArray *
1352 T_ARRAY( dummy, array, ... )
1353   int dummy = 0;
1354   intArray * array
1355  PREINIT:
1356   U32 size_RETVAL;
1357  CODE:
1358   dummy += 0; /* Fix -Wall */
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
1370 This is used for passing perl filehandles to and from C using
1371 C<FILE *> structures.
1372
1373 =cut
1374
1375 FILE *
1376 T_STDIO_open( file )
1377   const char * file
1378  CODE:
1379   RETVAL = xsfopen( file );
1380  OUTPUT:
1381   RETVAL
1382
1383 SysRet
1384 T_STDIO_close( f )
1385   PerlIO * f
1386  PREINIT:
1387   FILE * stream;
1388  CODE:
1389   /* Get the FILE* */
1390   stream = PerlIO_findFILE( f );  
1391   /* Release the FILE* from the PerlIO system so that we do
1392      not close the file twice */
1393   PerlIO_releaseFILE(f,stream);
1394   /* Must release the file before closing it */
1395   RETVAL = xsfclose( stream );
1396  OUTPUT:
1397   RETVAL
1398
1399 int
1400 T_STDIO_print( stream, string )
1401   FILE * stream
1402   const char * string
1403  CODE:
1404   RETVAL = xsfprintf( stream, string );
1405  OUTPUT:
1406   RETVAL
1407
1408
1409 =item T_INOUT
1410
1411 This is used for passing perl filehandles to and from C using
1412 C<PerlIO *> structures. The file handle can used for reading and
1413 writing. This corresponds to the C<+E<lt>> mode, see also T_IN
1414 and T_OUT.
1415
1416 See L<perliol> for more information on the Perl IO abstraction
1417 layer. Perl must have been built with C<-Duseperlio>.
1418
1419 There is no check to assert that the filehandle passed from Perl
1420 to C was created with the right C<open()> mode.
1421
1422 =cut
1423
1424 PerlIO *
1425 T_INOUT(in)
1426   PerlIO *in;
1427  CODE:
1428   RETVAL = in; /* silly test but better than nothing */
1429  OUTPUT: RETVAL
1430
1431 =item T_IN
1432
1433 Same as T_INOUT, but the filehandle that is returned from C to Perl
1434 can only be used for reading (mode C<E<lt>>). 
1435
1436 =cut
1437
1438 inputfh
1439 T_IN(in)
1440   inputfh in;
1441  CODE:
1442   RETVAL = in; /* silly test but better than nothing */
1443  OUTPUT: RETVAL
1444
1445 =item T_OUT
1446
1447 Same as T_INOUT, but the filehandle that is returned from C to Perl
1448 is set to use the open mode C<+E<gt>>.
1449
1450 =back
1451
1452 =cut
1453
1454 outputfh
1455 T_OUT(in)
1456   outputfh in;
1457  CODE:
1458   RETVAL = in; /* silly test but better than nothing */
1459  OUTPUT: RETVAL
1460