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