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