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