This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Typemaps: Start writing some general documentation
[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
5abff6f9
TJ
34/* A structure to test T_OPAQUEPTR */
35struct t_opaqueptr {
36 int a;
37 int b;
38 double c;
39};
40
41typedef struct t_opaqueptr astruct;
42
ea035a69 43/* Some static memory for the tests */
052980ee
TJ
44static I32 xst_anint;
45static intRef xst_anintref;
46static intObj xst_anintobj;
47static intRefIv xst_anintrefiv;
48static intOpq xst_anintopq;
ea035a69 49
b64f48ff 50/* A different type to refer to for testing the different
1d2615b4 51 * AV*, HV*, etc typemaps */
b64f48ff
SM
52typedef AV AV_FIXED;
53typedef HV HV_FIXED;
1d2615b4
SM
54typedef CV CV_FIXED;
55typedef SVREF SVREF_FIXED;
b64f48ff 56
ea035a69
JH
57/* Helper functions */
58
59/* T_ARRAY - allocate some memory */
60intArray * intArrayPtr( int nelem ) {
61 intArray * array;
a02a5408 62 Newx(array, nelem, intArray);
ea035a69
JH
63 return array;
64}
65
66
67MODULE = XS::Typemap PACKAGE = XS::Typemap
68
69PROTOTYPES: DISABLE
70
71=head1 TYPEMAPS
72
8447d1c7
SM
73The more you think about interfacing between two languages, the more
74you'll realize that the majority of programmer effort has to go into
75converting between the data structures that are native to either of
76the languages involved. This trumps other matter such as differing
77calling conventions because the problem space is so much greater.
78There are simply more ways to shove data into memory than there are
79ways to implement a function call.
80
81Perl XS' attempt at a solution to this is the concept of typemaps.
82At an abstract level, a Perl XS typemap is nothing but a recipe for
83converting from a certain Perl data structure to a certain C
84data structure and/or vice versa. Since there can be C types that
85are sufficiently similar to warrant converting with the same logic,
86XS typemaps are represented by a unique identifier, called XS type
87henceforth in this document. You can then tell the XS compiler that
88multiple C types are to be mapped with the same XS typemap.
89
90In your XS code, when you define an argument with a C type or when
91you are using a C<CODE:> and an C<OUTPUT:> section together with a
92C return type of your XSUB, it'll be the typemapping mechanism that
93makes this easy.
94
95=head2 Anatomy of a typemap File
96
97FIXME write
98
99=head2 The Role of the typemap File in Your Distribution
100
101For CPAN distributions, you can assume that the XS types defined by
102the perl core are already available. Additionally, the core typemap
103has default XS types for a large number of C types. For example, if
104you simply return a C<char *> from your XSUB, the core typemap will
105have this C type associated with the T_PV XS type. That means your
106C string will be copied into the PV (pointer value) slot of a new scalar
107that will be returned from your XSUB to to Perl.
108
109If you're developing a CPAN distribution using XS, you may add your own
110file called F<typemap> to the distribution. That file may contain
111typemaps that either map types that are specific to your code or that
112override the core typemap file's mappings for common C types.
113
114=head2 Full Listing of Core Typemaps
115
ea035a69 116Each C type is represented by an entry in the typemap file that
ac23f157 117is responsible for converting perl variables (SV, AV, HV, CV, etc.)
8447d1c7
SM
118to and from that type. The following sections list all XS types
119that come with perl by default.
ea035a69
JH
120
121=over 4
122
123=item T_SV
124
125This simply passes the C representation of the Perl variable (an SV*)
126in and out of the XS layer. This can be used if the C code wants
127to deal directly with the Perl variable.
128
129=cut
130
131SV *
132T_SV( sv )
133 SV * sv
134 CODE:
135 /* create a new sv for return that is a copy of the input
136 do not simply copy the pointer since the SV will be marked
137 mortal by the INPUT typemap when it is pushed back onto the stack */
138 RETVAL = sv_mortalcopy( sv );
139 /* increment the refcount since the default INPUT typemap mortalizes
140 by default and we don't want to decrement the ref count twice
141 by mistake */
142 SvREFCNT_inc(RETVAL);
143 OUTPUT:
144 RETVAL
145
146=item T_SVREF
147
148Used to pass in and return a reference to an SV.
149
1d2615b4
SM
150Note that this typemap does not decrement the reference count
151when returning the reference to an SV*.
152See also: T_SVREF_REFCOUNT_FIXED
153
ea035a69
JH
154=cut
155
156SVREF
157T_SVREF( svref )
158 SVREF svref
159 CODE:
160 RETVAL = svref;
161 OUTPUT:
162 RETVAL
163
1d2615b4
SM
164=item T_SVREF_FIXED
165
166Used to pass in and return a reference to an SV.
167This is a fixed
168variant of T_SVREF that decrements the refcount appropriately
169when returning a reference to an SV*. Introduced in perl 5.15.4.
170
171=cut
172
173SVREF_FIXED
174T_SVREF_REFCOUNT_FIXED( svref )
175 SVREF_FIXED svref
176 CODE:
177 SvREFCNT_inc(svref);
178 RETVAL = svref;
179 OUTPUT:
180 RETVAL
181
ea035a69
JH
182=item T_AVREF
183
184From the perl level this is a reference to a perl array.
185From the C level this is a pointer to an AV.
186
b64f48ff
SM
187Note that this typemap does not decrement the reference count
188when returning an AV*. See also: T_AVREF_REFCOUNT_FIXED
189
ea035a69
JH
190=cut
191
192AV *
193T_AVREF( av )
194 AV * av
195 CODE:
196 RETVAL = av;
197 OUTPUT:
198 RETVAL
199
b64f48ff
SM
200=item T_AVREF_REFCOUNT_FIXED
201
202From the perl level this is a reference to a perl array.
203From the C level this is a pointer to an AV. This is a fixed
204variant of T_AVREF that decrements the refcount appropriately
205when returning an AV*. Introduced in perl 5.15.4.
206
207=cut
208
209AV_FIXED*
210T_AVREF_REFCOUNT_FIXED( av )
211 AV_FIXED * av
212 CODE:
213 SvREFCNT_inc(av);
214 RETVAL = av;
215 OUTPUT:
216 RETVAL
217
ea035a69
JH
218=item T_HVREF
219
220From the perl level this is a reference to a perl hash.
d1be9408 221From the C level this is a pointer to an HV.
ea035a69 222
b64f48ff
SM
223Note that this typemap does not decrement the reference count
224when returning an HV*. See also: T_HVREF_REFCOUNT_FIXED
225
ea035a69
JH
226=cut
227
228HV *
229T_HVREF( hv )
230 HV * hv
231 CODE:
232 RETVAL = hv;
233 OUTPUT:
234 RETVAL
235
b64f48ff
SM
236=item T_HVREF_REFCOUNT_FIXED
237
238From the perl level this is a reference to a perl hash.
239From the C level this is a pointer to an HV. This is a fixed
240variant of T_HVREF that decrements the refcount appropriately
241when returning an HV*. Introduced in perl 5.15.4.
242
243=cut
244
245HV_FIXED*
246T_HVREF_REFCOUNT_FIXED( hv )
247 HV_FIXED * hv
248 CODE:
249 SvREFCNT_inc(hv);
250 RETVAL = hv;
251 OUTPUT:
252 RETVAL
253
254
ea035a69
JH
255=item T_CVREF
256
257From the perl level this is a reference to a perl subroutine
258(e.g. $sub = sub { 1 };). From the C level this is a pointer
259to a CV.
260
1d2615b4
SM
261Note that this typemap does not decrement the reference count
262when returning an HV*. See also: T_HVREF_REFCOUNT_FIXED
263
ea035a69
JH
264=cut
265
266CV *
267T_CVREF( cv )
268 CV * cv
269 CODE:
270 RETVAL = cv;
271 OUTPUT:
272 RETVAL
273
1d2615b4
SM
274=item T_CVREF_REFCOUNT_FIXED
275
276From the perl level this is a reference to a perl subroutine
277(e.g. $sub = sub { 1 };). From the C level this is a pointer
278to a CV.
279
280This is a fixed
281variant of T_HVREF that decrements the refcount appropriately
282when returning an HV*. Introduced in perl 5.15.4.
283
284=cut
285
286CV_FIXED *
287T_CVREF_REFCOUNT_FIXED( cv )
288 CV_FIXED * cv
289 CODE:
290 SvREFCNT_inc(cv);
291 RETVAL = cv;
292 OUTPUT:
293 RETVAL
ea035a69
JH
294
295=item T_SYSRET
296
297The T_SYSRET typemap is used to process return values from system calls.
298It is only meaningful when passing values from C to perl (there is
299no concept of passing a system return value from Perl to C).
300
301System calls return -1 on error (setting ERRNO with the reason)
302and (usually) 0 on success. If the return value is -1 this typemap
303returns C<undef>. If the return value is not -1, this typemap
304translates a 0 (perl false) to "0 but true" (which
305is perl true) or returns the value itself, to indicate that the
306command succeeded.
307
308The L<POSIX|POSIX> module makes extensive use of this type.
309
310=cut
311
312# Test a successful return
313
314SysRet
315T_SYSRET_pass()
316 CODE:
317 RETVAL = 0;
318 OUTPUT:
319 RETVAL
320
321# Test failure
322
323SysRet
324T_SYSRET_fail()
325 CODE:
326 RETVAL = -1;
327 OUTPUT:
328 RETVAL
329
330=item T_UV
331
332An unsigned integer.
333
334=cut
335
336unsigned int
337T_UV( uv )
338 unsigned int uv
339 CODE:
340 RETVAL = uv;
341 OUTPUT:
342 RETVAL
343
344=item T_IV
345
ac23f157 346A signed integer. This is cast to the required integer type when
d1be9408 347passed to C and converted to an IV when passed back to Perl.
ea035a69
JH
348
349=cut
350
351long
352T_IV( iv )
353 long iv
354 CODE:
355 RETVAL = iv;
356 OUTPUT:
357 RETVAL
358
359=item T_INT
360
361A signed integer. This typemap converts the Perl value to a native
362integer type (the C<int> type on the current platform). When returning
363the value to perl it is processed in the same way as for T_IV.
364
365Its behaviour is identical to using an C<int> type in XS with T_IV.
366
604db645
SM
367=cut
368
369intTINT
370T_INT( i )
371 intTINT i
372 CODE:
373 RETVAL = i;
374 OUTPUT:
375 RETVAL
376
ea035a69
JH
377=item T_ENUM
378
379An enum value. Used to transfer an enum component
380from C. There is no reason to pass an enum value to C since
381it is stored as an IV inside perl.
382
383=cut
384
385# The test should return the value for SVt_PVHV.
386# 11 at the present time but we can't not rely on this
387# for testing purposes.
388
389svtype
390T_ENUM()
391 CODE:
392 RETVAL = SVt_PVHV;
393 OUTPUT:
394 RETVAL
395
396=item T_BOOL
397
398A boolean type. This can be used to pass true and false values to and
399from C.
400
401=cut
402
403bool
404T_BOOL( in )
405 bool in
406 CODE:
407 RETVAL = in;
408 OUTPUT:
409 RETVAL
410
411=item T_U_INT
412
413This is for unsigned integers. It is equivalent to using T_UV
414but explicitly casts the variable to type C<unsigned int>.
415The default type for C<unsigned int> is T_UV.
416
604db645
SM
417=cut
418
419intUnsigned
420T_U_INT( uint )
421 intUnsigned uint
422 CODE:
423 RETVAL = uint;
424 OUTPUT:
425 RETVAL
426
ea035a69
JH
427=item T_SHORT
428
429Short integers. This is equivalent to T_IV but explicitly casts
430the return to type C<short>. The default typemap for C<short>
431is T_IV.
432
604db645
SM
433=cut
434
435short
436T_SHORT( s )
437 short s
438 CODE:
439 RETVAL = s;
440 OUTPUT:
441 RETVAL
442
ea035a69
JH
443=item T_U_SHORT
444
445Unsigned short integers. This is equivalent to T_UV but explicitly
446casts the return to type C<unsigned short>. The default typemap for
447C<unsigned short> is T_UV.
448
449T_U_SHORT is used for type C<U16> in the standard typemap.
450
451=cut
452
453U16
454T_U_SHORT( in )
455 U16 in
456 CODE:
457 RETVAL = in;
458 OUTPUT:
459 RETVAL
460
461
462=item T_LONG
463
464Long integers. This is equivalent to T_IV but explicitly casts
465the return to type C<long>. The default typemap for C<long>
466is T_IV.
467
604db645
SM
468=cut
469
470intTLONG
471T_LONG( in )
472 intTLONG in
473 CODE:
474 RETVAL = in;
475 OUTPUT:
476 RETVAL
477
ea035a69
JH
478=item T_U_LONG
479
480Unsigned long integers. This is equivalent to T_UV but explicitly
481casts the return to type C<unsigned long>. The default typemap for
482C<unsigned long> is T_UV.
483
484T_U_LONG is used for type C<U32> in the standard typemap.
485
486=cut
487
488U32
489T_U_LONG( in )
490 U32 in
491 CODE:
492 RETVAL = in;
493 OUTPUT:
494 RETVAL
495
496=item T_CHAR
497
498Single 8-bit characters.
499
500=cut
501
502char
503T_CHAR( in );
504 char in
505 CODE:
506 RETVAL = in;
507 OUTPUT:
508 RETVAL
509
510
511=item T_U_CHAR
512
513An unsigned byte.
514
515=cut
516
517unsigned char
518T_U_CHAR( in );
519 unsigned char in
520 CODE:
521 RETVAL = in;
522 OUTPUT:
523 RETVAL
524
525
526=item T_FLOAT
527
528A floating point number. This typemap guarantees to return a variable
529cast to a C<float>.
530
531=cut
532
533float
534T_FLOAT( in )
535 float in
536 CODE:
537 RETVAL = in;
538 OUTPUT:
539 RETVAL
540
541=item T_NV
542
543A Perl floating point number. Similar to T_IV and T_UV in that the
544return type is cast to the requested numeric type rather than
545to a specific type.
546
547=cut
548
549NV
550T_NV( in )
551 NV in
552 CODE:
553 RETVAL = in;
554 OUTPUT:
555 RETVAL
556
557=item T_DOUBLE
558
559A double precision floating point number. This typemap guarantees to
560return a variable cast to a C<double>.
561
562=cut
563
564double
565T_DOUBLE( in )
566 double in
567 CODE:
568 RETVAL = in;
569 OUTPUT:
570 RETVAL
571
572=item T_PV
573
574A string (char *).
575
576=cut
577
578char *
579T_PV( in )
580 char * in
581 CODE:
582 RETVAL = in;
583 OUTPUT:
584 RETVAL
585
586=item T_PTR
587
588A memory address (pointer). Typically associated with a C<void *>
589type.
590
591=cut
592
593# Pass in a value. Store the value in some static memory and
594# then return the pointer
595
596void *
597T_PTR_OUT( in )
598 int in;
599 CODE:
052980ee
TJ
600 xst_anint = in;
601 RETVAL = &xst_anint;
ea035a69
JH
602 OUTPUT:
603 RETVAL
604
605# pass in the pointer and return the value
606
607int
608T_PTR_IN( ptr )
609 void * ptr
610 CODE:
611 RETVAL = *(int *)ptr;
612 OUTPUT:
613 RETVAL
614
615=item T_PTRREF
616
617Similar to T_PTR except that the pointer is stored in a scalar and the
618reference to that scalar is returned to the caller. This can be used
619to hide the actual pointer value from the programmer since it is usually
620not required directly from within perl.
621
622The typemap checks that a scalar reference is passed from perl to XS.
623
624=cut
625
626# Similar test to T_PTR
627# Pass in a value. Store the value in some static memory and
628# then return the pointer
629
630intRef *
631T_PTRREF_OUT( in )
632 intRef in;
633 CODE:
052980ee
TJ
634 xst_anintref = in;
635 RETVAL = &xst_anintref;
ea035a69
JH
636 OUTPUT:
637 RETVAL
638
639# pass in the pointer and return the value
640
641intRef
642T_PTRREF_IN( ptr )
643 intRef * ptr
644 CODE:
645 RETVAL = *ptr;
646 OUTPUT:
647 RETVAL
648
649
650
651=item T_PTROBJ
652
653Similar to T_PTRREF except that the reference is blessed into a class.
654This allows the pointer to be used as an object. Most commonly used to
655deal with C structs. The typemap checks that the perl object passed
656into the XS routine is of the correct class (or part of a subclass).
657
658The pointer is blessed into a class that is derived from the name
659of type of the pointer but with all '*' in the name replaced with
660'Ptr'.
661
662=cut
663
664# Similar test to T_PTRREF
665# Pass in a value. Store the value in some static memory and
666# then return the pointer
667
668intObj *
669T_PTROBJ_OUT( in )
670 intObj in;
671 CODE:
052980ee
TJ
672 xst_anintobj = in;
673 RETVAL = &xst_anintobj;
ea035a69
JH
674 OUTPUT:
675 RETVAL
676
677# pass in the pointer and return the value
678
679MODULE = XS::Typemap PACKAGE = intObjPtr
680
681intObj
682T_PTROBJ_IN( ptr )
683 intObj * ptr
684 CODE:
685 RETVAL = *ptr;
686 OUTPUT:
687 RETVAL
688
689MODULE = XS::Typemap PACKAGE = XS::Typemap
690
691=item T_REF_IV_REF
692
693NOT YET
694
695=item T_REF_IV_PTR
696
697Similar to T_PTROBJ in that the pointer is blessed into a scalar object.
698The difference is that when the object is passed back into XS it must be
699of the correct type (inheritance is not supported).
700
701The pointer is blessed into a class that is derived from the name
702of type of the pointer but with all '*' in the name replaced with
703'Ptr'.
704
705=cut
706
707# Similar test to T_PTROBJ
708# Pass in a value. Store the value in some static memory and
709# then return the pointer
710
711intRefIv *
712T_REF_IV_PTR_OUT( in )
713 intRefIv in;
714 CODE:
052980ee
TJ
715 xst_anintrefiv = in;
716 RETVAL = &xst_anintrefiv;
ea035a69
JH
717 OUTPUT:
718 RETVAL
719
720# pass in the pointer and return the value
721
722MODULE = XS::Typemap PACKAGE = intRefIvPtr
723
724intRefIv
725T_REF_IV_PTR_IN( ptr )
726 intRefIv * ptr
727 CODE:
728 RETVAL = *ptr;
729 OUTPUT:
730 RETVAL
731
732
733MODULE = XS::Typemap PACKAGE = XS::Typemap
734
735=item T_PTRDESC
736
737NOT YET
738
739=item T_REFREF
740
d3ba6280
SM
741Similar to T_PTRREF, except the pointer stored in the referenced scalar
742is dereferenced and copied to the output variable. This means that
743T_REFREF is to T_PTRREF as T_OPAQUE is to T_OPAQUEPTR. All clear?
744
745Only the INPUT part of this is implemented (Perl to XSUB) and there
746are no known users in core or on CPAN.
747
748=cut
ea035a69
JH
749
750=item T_REFOBJ
751
752NOT YET
753
754=item T_OPAQUEPTR
755
5abff6f9
TJ
756This can be used to store bytes in the string component of the
757SV. Here the representation of the data is irrelevant to perl and the
758bytes themselves are just stored in the SV. It is assumed that the C
759variable is a pointer (the bytes are copied from that memory
760location). If the pointer is pointing to something that is
761represented by 8 bytes then those 8 bytes are stored in the SV (and
762length() will report a value of 8). This entry is similar to T_OPAQUE.
ea035a69 763
5abff6f9
TJ
764In principal the unpack() command can be used to convert the bytes
765back to a number (if the underlying type is known to be a number).
766
767This entry can be used to store a C structure (the number
768of bytes to be copied is calculated using the C C<sizeof> function)
769and can be used as an alternative to T_PTRREF without having to worry
770about a memory leak (since Perl will clean up the SV).
ea035a69
JH
771
772=cut
773
774intOpq *
775T_OPAQUEPTR_IN( val )
776 intOpq val
777 CODE:
052980ee
TJ
778 xst_anintopq = val;
779 RETVAL = &xst_anintopq;
ea035a69
JH
780 OUTPUT:
781 RETVAL
782
783intOpq
784T_OPAQUEPTR_OUT( ptr )
785 intOpq * ptr
786 CODE:
787 RETVAL = *ptr;
788 OUTPUT:
789 RETVAL
790
aa921f48
TJ
791short
792T_OPAQUEPTR_OUT_short( ptr )
793 shortOPQ * ptr
794 CODE:
795 RETVAL = *ptr;
796 OUTPUT:
797 RETVAL
798
5abff6f9
TJ
799# Test it with a structure
800astruct *
801T_OPAQUEPTR_IN_struct( a,b,c )
802 int a
803 int b
804 double c
805 PREINIT:
806 struct t_opaqueptr test;
807 CODE:
808 test.a = a;
809 test.b = b;
810 test.c = c;
811 RETVAL = &test;
812 OUTPUT:
813 RETVAL
814
815void
816T_OPAQUEPTR_OUT_struct( test )
817 astruct * test
818 PPCODE:
819 XPUSHs(sv_2mortal(newSViv(test->a)));
820 XPUSHs(sv_2mortal(newSViv(test->b)));
821 XPUSHs(sv_2mortal(newSVnv(test->c)));
822
823
ea035a69
JH
824=item T_OPAQUE
825
5abff6f9
TJ
826This can be used to store data from non-pointer types in the string
827part of an SV. It is similar to T_OPAQUEPTR except that the
828typemap retrieves the pointer directly rather than assuming it
ac23f157 829is being supplied. For example, if an integer is imported into
052980ee
TJ
830Perl using T_OPAQUE rather than T_IV the underlying bytes representing
831the integer will be stored in the SV but the actual integer value will not
832be available. i.e. The data is opaque to perl.
ea035a69 833
5abff6f9
TJ
834The data may be retrieved using the C<unpack> function if the
835underlying type of the byte stream is known.
836
837T_OPAQUE supports input and output of simple types.
838T_OPAQUEPTR can be used to pass these bytes back into C if a pointer
839is acceptable.
ea035a69
JH
840
841=cut
842
843shortOPQ
844T_OPAQUE_IN( val )
845 int val
846 CODE:
847 RETVAL = (shortOPQ)val;
848 OUTPUT:
849 RETVAL
850
5abff6f9
TJ
851IV
852T_OPAQUE_OUT( val )
853 shortOPQ val
854 CODE:
855 RETVAL = (IV)val;
856 OUTPUT:
857 RETVAL
858
ea035a69
JH
859=item Implicit array
860
861xsubpp supports a special syntax for returning
862packed C arrays to perl. If the XS return type is given as
863
864 array(type, nelem)
865
866xsubpp will copy the contents of C<nelem * sizeof(type)> bytes from
867RETVAL to an SV and push it onto the stack. This is only really useful
868if the number of items to be returned is known at compile time and you
869don't mind having a string of bytes in your SV. Use T_ARRAY to push a
870variable number of arguments onto the return stack (they won't be
871packed as a single string though).
872
873This is similar to using T_OPAQUEPTR but can be used to process more than
874one element.
875
876=cut
877
878array(int,3)
879T_OPAQUE_array( a,b,c)
880 int a
881 int b
882 int c
883 PREINIT:
3d5d53b8 884 int array[3];
ea035a69
JH
885 CODE:
886 array[0] = a;
887 array[1] = b;
888 array[2] = c;
889 RETVAL = array;
890 OUTPUT:
891 RETVAL
892
893
894=item T_PACKED
895
896NOT YET
897
898=item T_PACKEDARRAY
899
900NOT YET
901
902=item T_DATAUNIT
903
904NOT YET
905
906=item T_CALLBACK
907
908NOT YET
909
910=item T_ARRAY
911
912This is used to convert the perl argument list to a C array
913and for pushing the contents of a C array onto the perl
914argument stack.
915
916The usual calling signature is
917
918 @out = array_func( @in );
919
920Any number of arguments can occur in the list before the array but
921the input and output arrays must be the last elements in the list.
922
923When used to pass a perl list to C the XS writer must provide a
924function (named after the array type but with 'Ptr' substituted for
925'*') to allocate the memory required to hold the list. A pointer
926should be returned. It is up to the XS writer to free the memory on
927exit from the function. The variable C<ix_$var> is set to the number
928of elements in the new array.
929
930When returning a C array to Perl the XS writer must provide an integer
931variable called C<size_$var> containing the number of elements in the
932array. This is used to determine how many elements should be pushed
933onto the return argument stack. This is not required on input since
934Perl knows how many arguments are on the stack when the routine is
935called. Ordinarily this variable would be called C<size_RETVAL>.
936
937Additionally, the type of each element is determined from the type of
938the array. If the array uses type C<intArray *> xsubpp will
939automatically work out that it contains variables of type C<int> and
940use that typemap entry to perform the copy of each element. All
941pointer '*' and 'Array' tags are removed from the name to determine
942the subtype.
943
944=cut
945
946# Test passes in an integer array and returns it along with
947# the number of elements
948# Pass in a dummy value to test offsetting
949
950# Problem is that xsubpp does XSRETURN(1) because we arent
951# using PPCODE. This means that only the first element
952# is returned. KLUGE this by using CLEANUP to return before the
953# end.
ac23f157
SM
954# Note: I read this as: The "T_ARRAY" typemap is really rather broken,
955# at least for OUTPUT. That is apart from the general design
956# weaknesses. --Steffen
ea035a69
JH
957
958intArray *
959T_ARRAY( dummy, array, ... )
4d0439ce 960 int dummy = 0;
ea035a69
JH
961 intArray * array
962 PREINIT:
963 U32 size_RETVAL;
964 CODE:
8876ff82 965 dummy += 0; /* Fix -Wall */
ea035a69
JH
966 size_RETVAL = ix_array;
967 RETVAL = array;
968 OUTPUT:
969 RETVAL
970 CLEANUP:
971 Safefree(array);
972 XSRETURN(size_RETVAL);
973
974
975=item T_STDIO
976
977This is used for passing perl filehandles to and from C using
978C<FILE *> structures.
979
980=cut
981
982FILE *
983T_STDIO_open( file )
984 const char * file
985 CODE:
986 RETVAL = xsfopen( file );
987 OUTPUT:
988 RETVAL
989
990SysRet
c72de6e4
TJ
991T_STDIO_close( f )
992 PerlIO * f
993 PREINIT:
994 FILE * stream;
ea035a69 995 CODE:
c72de6e4
TJ
996 /* Get the FILE* */
997 stream = PerlIO_findFILE( f );
c72de6e4
TJ
998 /* Release the FILE* from the PerlIO system so that we do
999 not close the file twice */
1000 PerlIO_releaseFILE(f,stream);
6b54a403
NC
1001 /* Must release the file before closing it */
1002 RETVAL = xsfclose( stream );
ea035a69
JH
1003 OUTPUT:
1004 RETVAL
1005
1006int
1007T_STDIO_print( stream, string )
1008 FILE * stream
1009 const char * string
1010 CODE:
1011 RETVAL = xsfprintf( stream, string );
1012 OUTPUT:
1013 RETVAL
1014
1015
1016=item T_IN
1017
1018NOT YET
1019
1020=item T_INOUT
1021
1022This is used for passing perl filehandles to and from C using
1023C<PerlIO *> structures. The file handle can used for reading and
1024writing.
1025
1026See L<perliol> for more information on the Perl IO abstraction
1027layer. Perl must have been built with C<-Duseperlio>.
1028
1029=item T_OUT
1030
1031NOT YET
1032
1033=back
1034
1035=cut
1036