This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Add new test file to MANIFEST. Fix tests for threaded builds.
[perl5.git] / ext / XS / Typemap / Typemap.xs
CommitLineData
ea035a69
JH
1
2/*
3 XS code to test the typemap entries
4
5 Copyright (C) 2001 Tim Jenness.
6 All Rights Reserved
7
8*/
9
10#include "EXTERN.h" /* std perl include */
11#include "perl.h" /* std perl include */
12#include "XSUB.h" /* XSUB include */
13
14/* Prototypes for external functions */
15FILE * xsfopen( const char * );
16int xsfclose( FILE * );
17int xsfprintf( FILE *, const char *);
18
19/* Type definitions required for the XS typemaps */
20typedef SV * SVREF; /* T_SVREF */
21typedef int SysRet; /* T_SYSRET */
22typedef int Int; /* T_INT */
23typedef int intRef; /* T_PTRREF */
24typedef int intObj; /* T_PTROBJ */
25typedef int intRefIv; /* T_REF_IV_PTR */
26typedef int intArray; /* T_ARRAY */
27typedef short shortOPQ; /* T_OPAQUE */
28typedef int intOpq; /* T_OPAQUEPTR */
29
5abff6f9
TJ
30/* A structure to test T_OPAQUEPTR */
31struct t_opaqueptr {
32 int a;
33 int b;
34 double c;
35};
36
37typedef struct t_opaqueptr astruct;
38
ea035a69 39/* Some static memory for the tests */
052980ee
TJ
40static I32 xst_anint;
41static intRef xst_anintref;
42static intObj xst_anintobj;
43static intRefIv xst_anintrefiv;
44static intOpq xst_anintopq;
ea035a69
JH
45
46/* Helper functions */
47
48/* T_ARRAY - allocate some memory */
49intArray * intArrayPtr( int nelem ) {
50 intArray * array;
a02a5408 51 Newx(array, nelem, intArray);
ea035a69
JH
52 return array;
53}
54
55
56MODULE = XS::Typemap PACKAGE = XS::Typemap
57
58PROTOTYPES: DISABLE
59
60=head1 TYPEMAPS
61
62Each C type is represented by an entry in the typemap file that
63is responsible for converting perl variables (SV, AV, HV and CV) to
64and from that type.
65
66=over 4
67
68=item T_SV
69
70This simply passes the C representation of the Perl variable (an SV*)
71in and out of the XS layer. This can be used if the C code wants
72to deal directly with the Perl variable.
73
74=cut
75
76SV *
77T_SV( sv )
78 SV * sv
79 CODE:
80 /* create a new sv for return that is a copy of the input
81 do not simply copy the pointer since the SV will be marked
82 mortal by the INPUT typemap when it is pushed back onto the stack */
83 RETVAL = sv_mortalcopy( sv );
84 /* increment the refcount since the default INPUT typemap mortalizes
85 by default and we don't want to decrement the ref count twice
86 by mistake */
87 SvREFCNT_inc(RETVAL);
88 OUTPUT:
89 RETVAL
90
91=item T_SVREF
92
93Used to pass in and return a reference to an SV.
94
95=cut
96
97SVREF
98T_SVREF( svref )
99 SVREF svref
100 CODE:
101 RETVAL = svref;
102 OUTPUT:
103 RETVAL
104
105=item T_AVREF
106
107From the perl level this is a reference to a perl array.
108From the C level this is a pointer to an AV.
109
110=cut
111
112AV *
113T_AVREF( av )
114 AV * av
115 CODE:
116 RETVAL = av;
117 OUTPUT:
118 RETVAL
119
120=item T_HVREF
121
122From the perl level this is a reference to a perl hash.
d1be9408 123From the C level this is a pointer to an HV.
ea035a69
JH
124
125=cut
126
127HV *
128T_HVREF( hv )
129 HV * hv
130 CODE:
131 RETVAL = hv;
132 OUTPUT:
133 RETVAL
134
135=item T_CVREF
136
137From the perl level this is a reference to a perl subroutine
138(e.g. $sub = sub { 1 };). From the C level this is a pointer
139to a CV.
140
141=cut
142
143CV *
144T_CVREF( cv )
145 CV * cv
146 CODE:
147 RETVAL = cv;
148 OUTPUT:
149 RETVAL
150
151
152=item T_SYSRET
153
154The T_SYSRET typemap is used to process return values from system calls.
155It is only meaningful when passing values from C to perl (there is
156no concept of passing a system return value from Perl to C).
157
158System calls return -1 on error (setting ERRNO with the reason)
159and (usually) 0 on success. If the return value is -1 this typemap
160returns C<undef>. If the return value is not -1, this typemap
161translates a 0 (perl false) to "0 but true" (which
162is perl true) or returns the value itself, to indicate that the
163command succeeded.
164
165The L<POSIX|POSIX> module makes extensive use of this type.
166
167=cut
168
169# Test a successful return
170
171SysRet
172T_SYSRET_pass()
173 CODE:
174 RETVAL = 0;
175 OUTPUT:
176 RETVAL
177
178# Test failure
179
180SysRet
181T_SYSRET_fail()
182 CODE:
183 RETVAL = -1;
184 OUTPUT:
185 RETVAL
186
187=item T_UV
188
189An unsigned integer.
190
191=cut
192
193unsigned int
194T_UV( uv )
195 unsigned int uv
196 CODE:
197 RETVAL = uv;
198 OUTPUT:
199 RETVAL
200
201=item T_IV
202
203A signed integer. This is cast to the required integer type when
d1be9408 204passed to C and converted to an IV when passed back to Perl.
ea035a69
JH
205
206=cut
207
208long
209T_IV( iv )
210 long iv
211 CODE:
212 RETVAL = iv;
213 OUTPUT:
214 RETVAL
215
216=item T_INT
217
218A signed integer. This typemap converts the Perl value to a native
219integer type (the C<int> type on the current platform). When returning
220the value to perl it is processed in the same way as for T_IV.
221
222Its behaviour is identical to using an C<int> type in XS with T_IV.
223
224=item T_ENUM
225
226An enum value. Used to transfer an enum component
227from C. There is no reason to pass an enum value to C since
228it is stored as an IV inside perl.
229
230=cut
231
232# The test should return the value for SVt_PVHV.
233# 11 at the present time but we can't not rely on this
234# for testing purposes.
235
236svtype
237T_ENUM()
238 CODE:
239 RETVAL = SVt_PVHV;
240 OUTPUT:
241 RETVAL
242
243=item T_BOOL
244
245A boolean type. This can be used to pass true and false values to and
246from C.
247
248=cut
249
250bool
251T_BOOL( in )
252 bool in
253 CODE:
254 RETVAL = in;
255 OUTPUT:
256 RETVAL
257
258=item T_U_INT
259
260This is for unsigned integers. It is equivalent to using T_UV
261but explicitly casts the variable to type C<unsigned int>.
262The default type for C<unsigned int> is T_UV.
263
264=item T_SHORT
265
266Short integers. This is equivalent to T_IV but explicitly casts
267the return to type C<short>. The default typemap for C<short>
268is T_IV.
269
270=item T_U_SHORT
271
272Unsigned short integers. This is equivalent to T_UV but explicitly
273casts the return to type C<unsigned short>. The default typemap for
274C<unsigned short> is T_UV.
275
276T_U_SHORT is used for type C<U16> in the standard typemap.
277
278=cut
279
280U16
281T_U_SHORT( in )
282 U16 in
283 CODE:
284 RETVAL = in;
285 OUTPUT:
286 RETVAL
287
288
289=item T_LONG
290
291Long integers. This is equivalent to T_IV but explicitly casts
292the return to type C<long>. The default typemap for C<long>
293is T_IV.
294
295=item T_U_LONG
296
297Unsigned long integers. This is equivalent to T_UV but explicitly
298casts the return to type C<unsigned long>. The default typemap for
299C<unsigned long> is T_UV.
300
301T_U_LONG is used for type C<U32> in the standard typemap.
302
303=cut
304
305U32
306T_U_LONG( in )
307 U32 in
308 CODE:
309 RETVAL = in;
310 OUTPUT:
311 RETVAL
312
313=item T_CHAR
314
315Single 8-bit characters.
316
317=cut
318
319char
320T_CHAR( in );
321 char in
322 CODE:
323 RETVAL = in;
324 OUTPUT:
325 RETVAL
326
327
328=item T_U_CHAR
329
330An unsigned byte.
331
332=cut
333
334unsigned char
335T_U_CHAR( in );
336 unsigned char in
337 CODE:
338 RETVAL = in;
339 OUTPUT:
340 RETVAL
341
342
343=item T_FLOAT
344
345A floating point number. This typemap guarantees to return a variable
346cast to a C<float>.
347
348=cut
349
350float
351T_FLOAT( in )
352 float in
353 CODE:
354 RETVAL = in;
355 OUTPUT:
356 RETVAL
357
358=item T_NV
359
360A Perl floating point number. Similar to T_IV and T_UV in that the
361return type is cast to the requested numeric type rather than
362to a specific type.
363
364=cut
365
366NV
367T_NV( in )
368 NV in
369 CODE:
370 RETVAL = in;
371 OUTPUT:
372 RETVAL
373
374=item T_DOUBLE
375
376A double precision floating point number. This typemap guarantees to
377return a variable cast to a C<double>.
378
379=cut
380
381double
382T_DOUBLE( in )
383 double in
384 CODE:
385 RETVAL = in;
386 OUTPUT:
387 RETVAL
388
389=item T_PV
390
391A string (char *).
392
393=cut
394
395char *
396T_PV( in )
397 char * in
398 CODE:
399 RETVAL = in;
400 OUTPUT:
401 RETVAL
402
403=item T_PTR
404
405A memory address (pointer). Typically associated with a C<void *>
406type.
407
408=cut
409
410# Pass in a value. Store the value in some static memory and
411# then return the pointer
412
413void *
414T_PTR_OUT( in )
415 int in;
416 CODE:
052980ee
TJ
417 xst_anint = in;
418 RETVAL = &xst_anint;
ea035a69
JH
419 OUTPUT:
420 RETVAL
421
422# pass in the pointer and return the value
423
424int
425T_PTR_IN( ptr )
426 void * ptr
427 CODE:
428 RETVAL = *(int *)ptr;
429 OUTPUT:
430 RETVAL
431
432=item T_PTRREF
433
434Similar to T_PTR except that the pointer is stored in a scalar and the
435reference to that scalar is returned to the caller. This can be used
436to hide the actual pointer value from the programmer since it is usually
437not required directly from within perl.
438
439The typemap checks that a scalar reference is passed from perl to XS.
440
441=cut
442
443# Similar test to T_PTR
444# Pass in a value. Store the value in some static memory and
445# then return the pointer
446
447intRef *
448T_PTRREF_OUT( in )
449 intRef in;
450 CODE:
052980ee
TJ
451 xst_anintref = in;
452 RETVAL = &xst_anintref;
ea035a69
JH
453 OUTPUT:
454 RETVAL
455
456# pass in the pointer and return the value
457
458intRef
459T_PTRREF_IN( ptr )
460 intRef * ptr
461 CODE:
462 RETVAL = *ptr;
463 OUTPUT:
464 RETVAL
465
466
467
468=item T_PTROBJ
469
470Similar to T_PTRREF except that the reference is blessed into a class.
471This allows the pointer to be used as an object. Most commonly used to
472deal with C structs. The typemap checks that the perl object passed
473into the XS routine is of the correct class (or part of a subclass).
474
475The pointer is blessed into a class that is derived from the name
476of type of the pointer but with all '*' in the name replaced with
477'Ptr'.
478
479=cut
480
481# Similar test to T_PTRREF
482# Pass in a value. Store the value in some static memory and
483# then return the pointer
484
485intObj *
486T_PTROBJ_OUT( in )
487 intObj in;
488 CODE:
052980ee
TJ
489 xst_anintobj = in;
490 RETVAL = &xst_anintobj;
ea035a69
JH
491 OUTPUT:
492 RETVAL
493
494# pass in the pointer and return the value
495
496MODULE = XS::Typemap PACKAGE = intObjPtr
497
498intObj
499T_PTROBJ_IN( ptr )
500 intObj * ptr
501 CODE:
502 RETVAL = *ptr;
503 OUTPUT:
504 RETVAL
505
506MODULE = XS::Typemap PACKAGE = XS::Typemap
507
508=item T_REF_IV_REF
509
510NOT YET
511
512=item T_REF_IV_PTR
513
514Similar to T_PTROBJ in that the pointer is blessed into a scalar object.
515The difference is that when the object is passed back into XS it must be
516of the correct type (inheritance is not supported).
517
518The pointer is blessed into a class that is derived from the name
519of type of the pointer but with all '*' in the name replaced with
520'Ptr'.
521
522=cut
523
524# Similar test to T_PTROBJ
525# Pass in a value. Store the value in some static memory and
526# then return the pointer
527
528intRefIv *
529T_REF_IV_PTR_OUT( in )
530 intRefIv in;
531 CODE:
052980ee
TJ
532 xst_anintrefiv = in;
533 RETVAL = &xst_anintrefiv;
ea035a69
JH
534 OUTPUT:
535 RETVAL
536
537# pass in the pointer and return the value
538
539MODULE = XS::Typemap PACKAGE = intRefIvPtr
540
541intRefIv
542T_REF_IV_PTR_IN( ptr )
543 intRefIv * ptr
544 CODE:
545 RETVAL = *ptr;
546 OUTPUT:
547 RETVAL
548
549
550MODULE = XS::Typemap PACKAGE = XS::Typemap
551
552=item T_PTRDESC
553
554NOT YET
555
556=item T_REFREF
557
558NOT YET
559
560=item T_REFOBJ
561
562NOT YET
563
564=item T_OPAQUEPTR
565
5abff6f9
TJ
566This can be used to store bytes in the string component of the
567SV. Here the representation of the data is irrelevant to perl and the
568bytes themselves are just stored in the SV. It is assumed that the C
569variable is a pointer (the bytes are copied from that memory
570location). If the pointer is pointing to something that is
571represented by 8 bytes then those 8 bytes are stored in the SV (and
572length() will report a value of 8). This entry is similar to T_OPAQUE.
ea035a69 573
5abff6f9
TJ
574In principal the unpack() command can be used to convert the bytes
575back to a number (if the underlying type is known to be a number).
576
577This entry can be used to store a C structure (the number
578of bytes to be copied is calculated using the C C<sizeof> function)
579and can be used as an alternative to T_PTRREF without having to worry
580about a memory leak (since Perl will clean up the SV).
ea035a69
JH
581
582=cut
583
584intOpq *
585T_OPAQUEPTR_IN( val )
586 intOpq val
587 CODE:
052980ee
TJ
588 xst_anintopq = val;
589 RETVAL = &xst_anintopq;
ea035a69
JH
590 OUTPUT:
591 RETVAL
592
593intOpq
594T_OPAQUEPTR_OUT( ptr )
595 intOpq * ptr
596 CODE:
597 RETVAL = *ptr;
598 OUTPUT:
599 RETVAL
600
aa921f48
TJ
601short
602T_OPAQUEPTR_OUT_short( ptr )
603 shortOPQ * ptr
604 CODE:
605 RETVAL = *ptr;
606 OUTPUT:
607 RETVAL
608
5abff6f9
TJ
609# Test it with a structure
610astruct *
611T_OPAQUEPTR_IN_struct( a,b,c )
612 int a
613 int b
614 double c
615 PREINIT:
616 struct t_opaqueptr test;
617 CODE:
618 test.a = a;
619 test.b = b;
620 test.c = c;
621 RETVAL = &test;
622 OUTPUT:
623 RETVAL
624
625void
626T_OPAQUEPTR_OUT_struct( test )
627 astruct * test
628 PPCODE:
629 XPUSHs(sv_2mortal(newSViv(test->a)));
630 XPUSHs(sv_2mortal(newSViv(test->b)));
631 XPUSHs(sv_2mortal(newSVnv(test->c)));
632
633
ea035a69
JH
634=item T_OPAQUE
635
5abff6f9
TJ
636This can be used to store data from non-pointer types in the string
637part of an SV. It is similar to T_OPAQUEPTR except that the
638typemap retrieves the pointer directly rather than assuming it
639is being supplied. For example if an integer is imported into
052980ee
TJ
640Perl using T_OPAQUE rather than T_IV the underlying bytes representing
641the integer will be stored in the SV but the actual integer value will not
642be available. i.e. The data is opaque to perl.
ea035a69 643
5abff6f9
TJ
644The data may be retrieved using the C<unpack> function if the
645underlying type of the byte stream is known.
646
647T_OPAQUE supports input and output of simple types.
648T_OPAQUEPTR can be used to pass these bytes back into C if a pointer
649is acceptable.
ea035a69
JH
650
651=cut
652
653shortOPQ
654T_OPAQUE_IN( val )
655 int val
656 CODE:
657 RETVAL = (shortOPQ)val;
658 OUTPUT:
659 RETVAL
660
5abff6f9
TJ
661IV
662T_OPAQUE_OUT( val )
663 shortOPQ val
664 CODE:
665 RETVAL = (IV)val;
666 OUTPUT:
667 RETVAL
668
ea035a69
JH
669=item Implicit array
670
671xsubpp supports a special syntax for returning
672packed C arrays to perl. If the XS return type is given as
673
674 array(type, nelem)
675
676xsubpp will copy the contents of C<nelem * sizeof(type)> bytes from
677RETVAL to an SV and push it onto the stack. This is only really useful
678if the number of items to be returned is known at compile time and you
679don't mind having a string of bytes in your SV. Use T_ARRAY to push a
680variable number of arguments onto the return stack (they won't be
681packed as a single string though).
682
683This is similar to using T_OPAQUEPTR but can be used to process more than
684one element.
685
686=cut
687
688array(int,3)
689T_OPAQUE_array( a,b,c)
690 int a
691 int b
692 int c
693 PREINIT:
3d5d53b8 694 int array[3];
ea035a69
JH
695 CODE:
696 array[0] = a;
697 array[1] = b;
698 array[2] = c;
699 RETVAL = array;
700 OUTPUT:
701 RETVAL
702
703
704=item T_PACKED
705
706NOT YET
707
708=item T_PACKEDARRAY
709
710NOT YET
711
712=item T_DATAUNIT
713
714NOT YET
715
716=item T_CALLBACK
717
718NOT YET
719
720=item T_ARRAY
721
722This is used to convert the perl argument list to a C array
723and for pushing the contents of a C array onto the perl
724argument stack.
725
726The usual calling signature is
727
728 @out = array_func( @in );
729
730Any number of arguments can occur in the list before the array but
731the input and output arrays must be the last elements in the list.
732
733When used to pass a perl list to C the XS writer must provide a
734function (named after the array type but with 'Ptr' substituted for
735'*') to allocate the memory required to hold the list. A pointer
736should be returned. It is up to the XS writer to free the memory on
737exit from the function. The variable C<ix_$var> is set to the number
738of elements in the new array.
739
740When returning a C array to Perl the XS writer must provide an integer
741variable called C<size_$var> containing the number of elements in the
742array. This is used to determine how many elements should be pushed
743onto the return argument stack. This is not required on input since
744Perl knows how many arguments are on the stack when the routine is
745called. Ordinarily this variable would be called C<size_RETVAL>.
746
747Additionally, the type of each element is determined from the type of
748the array. If the array uses type C<intArray *> xsubpp will
749automatically work out that it contains variables of type C<int> and
750use that typemap entry to perform the copy of each element. All
751pointer '*' and 'Array' tags are removed from the name to determine
752the subtype.
753
754=cut
755
756# Test passes in an integer array and returns it along with
757# the number of elements
758# Pass in a dummy value to test offsetting
759
760# Problem is that xsubpp does XSRETURN(1) because we arent
761# using PPCODE. This means that only the first element
762# is returned. KLUGE this by using CLEANUP to return before the
763# end.
764
765intArray *
766T_ARRAY( dummy, array, ... )
4d0439ce 767 int dummy = 0;
ea035a69
JH
768 intArray * array
769 PREINIT:
770 U32 size_RETVAL;
771 CODE:
8876ff82 772 dummy += 0; /* Fix -Wall */
ea035a69
JH
773 size_RETVAL = ix_array;
774 RETVAL = array;
775 OUTPUT:
776 RETVAL
777 CLEANUP:
778 Safefree(array);
779 XSRETURN(size_RETVAL);
780
781
782=item T_STDIO
783
784This is used for passing perl filehandles to and from C using
785C<FILE *> structures.
786
787=cut
788
789FILE *
790T_STDIO_open( file )
791 const char * file
792 CODE:
793 RETVAL = xsfopen( file );
794 OUTPUT:
795 RETVAL
796
797SysRet
c72de6e4
TJ
798T_STDIO_close( f )
799 PerlIO * f
800 PREINIT:
801 FILE * stream;
ea035a69 802 CODE:
c72de6e4
TJ
803 /* Get the FILE* */
804 stream = PerlIO_findFILE( f );
c72de6e4
TJ
805 /* Release the FILE* from the PerlIO system so that we do
806 not close the file twice */
807 PerlIO_releaseFILE(f,stream);
6b54a403
NC
808 /* Must release the file before closing it */
809 RETVAL = xsfclose( stream );
ea035a69
JH
810 OUTPUT:
811 RETVAL
812
813int
814T_STDIO_print( stream, string )
815 FILE * stream
816 const char * string
817 CODE:
818 RETVAL = xsfprintf( stream, string );
819 OUTPUT:
820 RETVAL
821
822
823=item T_IN
824
825NOT YET
826
827=item T_INOUT
828
829This is used for passing perl filehandles to and from C using
830C<PerlIO *> structures. The file handle can used for reading and
831writing.
832
833See L<perliol> for more information on the Perl IO abstraction
834layer. Perl must have been built with C<-Duseperlio>.
835
836=item T_OUT
837
838NOT YET
839
840=back
841
842=cut
843