summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/lib/pods/perlxstut.pod
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl/lib/pods/perlxstut.pod')
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlxstut.pod49
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