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