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   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);
 809  OUTPUT:
 810   RETVAL
 811
 812 int
 813 T_STDIO_print( stream, string )
 814   FILE * stream
 815   const char * string
 816  CODE:
 817   RETVAL = xsfprintf( stream, string );
 818  OUTPUT:
 819   RETVAL
 820
 821
 822 =item T_IN
 823
 824 NOT YET
 825
 826 =item T_INOUT
 827
 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
 830 writing.
 831
 832 See L<perliol> for more information on the Perl IO abstraction
 833 layer. Perl must have been built with C<-Duseperlio>.
 834
 835 =item T_OUT
 836
 837 NOT YET
 838
 839 =back
 840
 841 =cut
 842