3 XS code to test the typemap entries
5 Copyright (C) 2001 Tim Jenness.
10 #include "EXTERN.h" /* std perl include */
11 #include "perl.h" /* std perl include */
12 #include "XSUB.h" /* XSUB include */
14 /* Prototypes for external functions */
15 FILE * xsfopen( const char * );
16 int xsfclose( FILE * );
17 int xsfprintf( FILE *, const char *);
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 */
30 /* A structure to test T_OPAQUEPTR */
37 typedef struct t_opaqueptr astruct;
39 /* Some static memory for the tests */
41 static intRef xst_anintref;
42 static intObj xst_anintobj;
43 static intRefIv xst_anintrefiv;
44 static intOpq xst_anintopq;
46 /* Helper functions */
48 /* T_ARRAY - allocate some memory */
49 intArray * intArrayPtr( int nelem ) {
51 New(0, array, nelem, intArray);
56 MODULE = XS::Typemap PACKAGE = XS::Typemap
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
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.
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
93 Used to pass in and return a reference to an SV.
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.
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.
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
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).
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
165 The L<POSIX|POSIX> module makes extensive use of this type.
169 # Test a successful return
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.
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.
222 Its behaviour is identical to using an C<int> type in XS with T_IV.
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.
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.
245 A boolean type. This can be used to pass true and false values to and
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.
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>
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.
276 T_U_SHORT is used for type C<U16> in the standard typemap.
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>
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.
301 T_U_LONG is used for type C<U32> in the standard typemap.
315 Single 8-bit characters.
345 A floating point number. This typemap guarantees to return a variable
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
376 A double precision floating point number. This typemap guarantees to
377 return a variable cast to a C<double>.
405 A memory address (pointer). Typically associated with a C<void *>
410 # Pass in a value. Store the value in some static memory and
411 # then return the pointer
422 # pass in the pointer and return the value
428 RETVAL = *(int *)ptr;
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.
439 The typemap checks that a scalar reference is passed from perl to XS.
443 # Similar test to T_PTR
444 # Pass in a value. Store the value in some static memory and
445 # then return the pointer
452 RETVAL = &xst_anintref;
456 # pass in the pointer and return the value
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).
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
481 # Similar test to T_PTRREF
482 # Pass in a value. Store the value in some static memory and
483 # then return the pointer
490 RETVAL = &xst_anintobj;
494 # pass in the pointer and return the value
496 MODULE = XS::Typemap PACKAGE = intObjPtr
506 MODULE = XS::Typemap PACKAGE = XS::Typemap
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).
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
524 # Similar test to T_PTROBJ
525 # Pass in a value. Store the value in some static memory and
526 # then return the pointer
529 T_REF_IV_PTR_OUT( in )
533 RETVAL = &xst_anintrefiv;
537 # pass in the pointer and return the value
539 MODULE = XS::Typemap PACKAGE = intRefIvPtr
542 T_REF_IV_PTR_IN( ptr )
550 MODULE = XS::Typemap PACKAGE = XS::Typemap
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.
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).
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).
585 T_OPAQUEPTR_IN( val )
589 RETVAL = &xst_anintopq;
594 T_OPAQUEPTR_OUT( ptr )
602 T_OPAQUEPTR_OUT_short( ptr )
609 # Test it with a structure
611 T_OPAQUEPTR_IN_struct( a,b,c )
616 struct t_opaqueptr test;
626 T_OPAQUEPTR_OUT_struct( test )
629 XPUSHs(sv_2mortal(newSViv(test->a)));
630 XPUSHs(sv_2mortal(newSViv(test->b)));
631 XPUSHs(sv_2mortal(newSVnv(test->c)));
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.
644 The data may be retrieved using the C<unpack> function if the
645 underlying type of the byte stream is known.
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
657 RETVAL = (shortOPQ)val;
671 xsubpp supports a special syntax for returning
672 packed C arrays to perl. If the XS return type is given as
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).
683 This is similar to using T_OPAQUEPTR but can be used to process more than
689 T_OPAQUE_array( a,b,c)
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
726 The usual calling signature is
728 @out = array_func( @in );
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.
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.
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>.
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
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
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
766 T_ARRAY( dummy, array, ... )
772 dummy += 0; /* Fix -Wall */
773 size_RETVAL = ix_array;
779 XSRETURN(size_RETVAL);
784 This is used for passing perl filehandles to and from C using
785 C<FILE *> structures.
793 RETVAL = xsfopen( file );
804 stream = PerlIO_findFILE( f );
805 RETVAL = xsfclose( stream );
806 /* Release the FILE* from the PerlIO system so that we do
807 not close the file twice */
808 PerlIO_releaseFILE(f,stream);
813 T_STDIO_print( stream, string )
817 RETVAL = xsfprintf( stream, string );
828 This is used for passing perl filehandles to and from C using
829 C<PerlIO *> structures. The file handle can used for reading and
832 See L<perliol> for more information on the Perl IO abstraction
833 layer. Perl must have been built with C<-Duseperlio>.