diff options
Diffstat (limited to 'Master/tlpkg/tlperl/lib/pods/perlxstut.pod')
| -rw-r--r-- | Master/tlpkg/tlperl/lib/pods/perlxstut.pod | 49 |
1 files changed, 29 insertions, 20 deletions
diff --git a/Master/tlpkg/tlperl/lib/pods/perlxstut.pod b/Master/tlpkg/tlperl/lib/pods/perlxstut.pod index 91c13ed358f..93c1bfbe61b 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlxstut.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlxstut.pod @@ -1,6 +1,6 @@ =head1 NAME -perlXStut - Tutorial for writing XSUBs +perlxstut - Tutorial for writing XSUBs =head1 DESCRIPTION @@ -435,8 +435,12 @@ heavy use of the C functions within Perl. The B<xsubpp> program uses rules to convert from Perl's data types (scalar, array, etc.) to C's data types (int, char, etc.). These rules are stored -in the typemap file ($PERLLIB/ExtUtils/typemap). This file is split into -three parts. +in the typemap file ($PERLLIB/ExtUtils/typemap). There's a brief discussion +below, but all the nitty-gritty details can be found in L<perlxstypemap>. +If you have a new-enough version of perl (5.16 and up) or an upgraded +XS compiler (C<ExtUtils::ParseXS> 3.13_01 or better), then you can inline +typemaps in your XS instead of writing separate files. +Either way, this typemap thing is split into three parts: The first section maps various C data types to a name, which corresponds somewhat with the various Perl types. The second section contains C code @@ -451,7 +455,7 @@ The file name is Mytest.c: dXSARGS; if (items != 1) Perl_croak(aTHX_ "Usage: Mytest::round(arg)"); - PERL_UNUSED_VAR(cv); /* -W */ + PERL_UNUSED_VAR(cv); /* -W */ { double arg = (double)SvNV(ST(0)); /* XXXXX */ if (arg > 0.0) { @@ -462,20 +466,20 @@ The file name is Mytest.c: arg = 0.0; } sv_setnv(ST(0), (double)arg); /* XXXXX */ - SvSETMAGIC(ST(0)); + SvSETMAGIC(ST(0)); } XSRETURN_EMPTY; } -Notice the two lines commented with "XXXXX". If you check the first section -of the typemap file, you'll see that doubles are of type T_DOUBLE. In the -INPUT section, an argument that is T_DOUBLE is assigned to the variable -arg by calling the routine SvNV on something, then casting it to double, -then assigned to the variable arg. Similarly, in the OUTPUT section, -once arg has its final value, it is passed to the sv_setnv function to -be passed back to the calling subroutine. These two functions are explained -in L<perlguts>; we'll talk more later about what that "ST(0)" means in the -section on the argument stack. +Notice the two lines commented with "XXXXX". If you check the first part +of the typemap file (or section), you'll see that doubles are of type +T_DOUBLE. In the INPUT part of the typemap, an argument that is T_DOUBLE +is assigned to the variable arg by calling the routine SvNV on something, +then casting it to double, then assigned to the variable arg. Similarly, +in the OUTPUT section, once arg has its final value, it is passed to the +sv_setnv function to be passed back to the calling subroutine. These two +functions are explained in L<perlguts>; we'll talk more later about what +that "ST(0)" means in the section on the argument stack. =head2 Warning about Output Arguments @@ -606,11 +610,13 @@ And also add the following function definition to the end of the .xs file: OUTPUT: RETVAL -Now we also need to create a typemap file because the default Perl doesn't -currently support the const char * type. Create a file called typemap in -the Mytest2 directory and place the following in it: +Now we also need to create a typemap because the default Perl doesn't +currently support the C<const char *> type. Include a new TYPEMAP +section in your XS code before the above function: + TYPEMAP: <<END; const char * T_PV + END Now run perl on the top-level Makefile.PL. Notice that it also created a Makefile in the mylib directory. Run make and watch that it does cd into @@ -1086,6 +1092,7 @@ Mytest.xs: int i, n; struct statfs buf; + SvGETMAGIC(paths); if ((!SvROK(paths)) || (SvTYPE(SvRV(paths)) != SVt_PVAV) || ((numpaths = av_len((AV *)SvRV(paths))) < 0)) @@ -1145,8 +1152,10 @@ and C<OUTPUT:> directives. =item * When dealing with references, it is important to handle them with caution. -The C<INIT:> block first checks that -C<SvROK> returns true, which indicates that paths is a valid reference. It +The C<INIT:> block first calls SvGETMAGIC(paths), in case +paths is a tied variable. Then it checks that C<SvROK> returns +true, which indicates that paths is a valid reference. (Simply +checking C<SvROK> won't trigger FETCH on a tied variable.) It then verifies that the object referenced by paths is an array, using C<SvRV> to dereference paths, and C<SvTYPE> to discover its type. As an added test, it checks that the array referenced by paths is non-empty, using the C<av_len> @@ -1367,4 +1376,4 @@ Changes for h2xs as of Perl 5.8.x by Renee Baecker =head2 Last Changed -2007/10/11 +2012-01-20 |