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