1perlxstut(3)          User Contributed Perl Documentation         perlxstut(3)
2
3
4

NAME

6       perlxstut - Tutorial for writing XSUBs
7

DESCRIPTION

9       This tutorial will educate the reader on the steps involved in creating
10       a Perl extension.  The reader is assumed to have access to perlguts,
11       perlapi and perlxs.
12
13       This tutorial starts with very simple examples and becomes more
14       complex, with each new example adding new features.  Certain concepts
15       may not be completely explained until later in the tutorial in order to
16       slowly ease the reader into building extensions.
17
18       This tutorial was written from a Unix point of view.  Where I know them
19       to be otherwise different for other platforms (e.g. Win32), I will list
20       them.  If you find something that was missed, please let me know.
21

SPECIAL NOTES

23   make
24       This tutorial assumes that the make program that Perl is configured to
25       use is called "make".  Instead of running "make" in the examples that
26       follow, you may have to substitute whatever make program Perl has been
27       configured to use.  Running perl -V:make should tell you what it is.
28
29   Version caveat
30       When writing a Perl extension for general consumption, one should
31       expect that the extension will be used with versions of Perl different
32       from the version available on your machine.  Since you are reading this
33       document, the version of Perl on your machine is probably 5.005 or
34       later, but the users of your extension may have more ancient versions.
35
36       To understand what kinds of incompatibilities one may expect, and in
37       the rare case that the version of Perl on your machine is older than
38       this document, see the section on "Troubleshooting these Examples" for
39       more information.
40
41       If your extension uses some features of Perl which are not available on
42       older releases of Perl, your users would appreciate an early meaningful
43       warning.  You would probably put this information into the README file,
44       but nowadays installation of extensions may be performed automatically,
45       guided by CPAN.pm module or other tools.
46
47       In MakeMaker-based installations, Makefile.PL provides the earliest
48       opportunity to perform version checks.  One can put something like this
49       in Makefile.PL for this purpose:
50
51           eval { require 5.007 }
52               or die <<EOD;
53           ############
54           ### This module uses frobnication framework which is not available
55           ### before version 5.007 of Perl.  Upgrade your Perl before
56           ### installing Kara::Mba.
57           ############
58           EOD
59
60   Dynamic Loading versus Static Loading
61       It is commonly thought that if a system does not have the capability to
62       dynamically load a library, you cannot build XSUBs.  This is incorrect.
63       You can build them, but you must link the XSUBs subroutines with the
64       rest of Perl, creating a new executable.  This situation is similar to
65       Perl 4.
66
67       This tutorial can still be used on such a system.  The XSUB build
68       mechanism will check the system and build a dynamically-loadable
69       library if possible, or else a static library and then, optionally, a
70       new statically-linked executable with that static library linked in.
71
72       Should you wish to build a statically-linked executable on a system
73       which can dynamically load libraries, you may, in all the following
74       examples, where the command ""make"" with no arguments is executed, run
75       the command ""make perl"" instead.
76
77       If you have generated such a statically-linked executable by choice,
78       then instead of saying ""make test"", you should say ""make
79       test_static"".  On systems that cannot build dynamically-loadable
80       libraries at all, simply saying ""make test"" is sufficient.
81
82   Threads and PERL_NO_GET_CONTEXT
83       For threaded builds, perl requires the context pointer for the current
84       thread, without "PERL_NO_GET_CONTEXT", perl will call a function to
85       retrieve the context.
86
87       For improved performance, include:
88
89         #define PERL_NO_GET_CONTEXT
90
91       as shown below.
92
93       For more details, see perlguts.
94

TUTORIAL

96       Now let's go on with the show!
97
98   EXAMPLE 1
99       Our first extension will be very simple.  When we call the routine in
100       the extension, it will print out a well-known message and return.
101
102       Run ""h2xs -A -n Mytest"".  This creates a directory named Mytest,
103       possibly under ext/ if that directory exists in the current working
104       directory.  Several files will be created under the Mytest dir,
105       including MANIFEST, Makefile.PL, lib/Mytest.pm, Mytest.xs, t/Mytest.t,
106       and Changes.
107
108       The MANIFEST file contains the names of all the files just created in
109       the Mytest directory.
110
111       The file Makefile.PL should look something like this:
112
113           use ExtUtils::MakeMaker;
114           # See lib/ExtUtils/MakeMaker.pm for details of how to influence
115           # the contents of the Makefile that is written.
116           WriteMakefile(
117               NAME         => 'Mytest',
118               VERSION_FROM => 'Mytest.pm', # finds $VERSION
119               LIBS         => [''],   # e.g., '-lm'
120               DEFINE       => '',     # e.g., '-DHAVE_SOMETHING'
121               INC          => '',     # e.g., '-I/usr/include/other'
122           );
123
124       The file Mytest.pm should start with something like this:
125
126           package Mytest;
127
128           use 5.008008;
129           use strict;
130           use warnings;
131
132           require Exporter;
133
134           our @ISA = qw(Exporter);
135           our %EXPORT_TAGS = ( 'all' => [ qw(
136
137           ) ] );
138
139           our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );
140
141           our @EXPORT = qw(
142
143           );
144
145           our $VERSION = '0.01';
146
147           require XSLoader;
148           XSLoader::load('Mytest', $VERSION);
149
150           # Preloaded methods go here.
151
152           1;
153           __END__
154           # Below is the stub of documentation for your module. You better
155           # edit it!
156
157       The rest of the .pm file contains sample code for providing
158       documentation for the extension.
159
160       Finally, the Mytest.xs file should look something like this:
161
162           #define PERL_NO_GET_CONTEXT
163           #include "EXTERN.h"
164           #include "perl.h"
165           #include "XSUB.h"
166
167           #include "ppport.h"
168
169           MODULE = Mytest             PACKAGE = Mytest
170
171       Let's edit the .xs file by adding this to the end of the file:
172
173           void
174           hello()
175               CODE:
176                   printf("Hello, world!\n");
177
178       It is okay for the lines starting at the "CODE:" line to not be
179       indented.  However, for readability purposes, it is suggested that you
180       indent CODE: one level and the lines following one more level.
181
182       Now we'll run ""perl Makefile.PL"".  This will create a real Makefile,
183       which make needs.  Its output looks something like:
184
185           % perl Makefile.PL
186           Checking if your kit is complete...
187           Looks good
188           Writing Makefile for Mytest
189           %
190
191       Now, running make will produce output that looks something like this
192       (some long lines have been shortened for clarity and some extraneous
193       lines have been deleted):
194
195        % make
196        cp lib/Mytest.pm blib/lib/Mytest.pm
197        perl xsubpp  -typemap typemap  Mytest.xs > Mytest.xsc && \
198        mv Mytest.xsc Mytest.c
199        Please specify prototyping behavior for Mytest.xs (see perlxs manual)
200        cc -c     Mytest.c
201        Running Mkbootstrap for Mytest ()
202        chmod 644 Mytest.bs
203        rm -f blib/arch/auto/Mytest/Mytest.so
204        cc -shared -L/usr/local/lib Mytest.o -o blib/arch/auto/Mytest/Mytest.so
205
206        chmod 755 blib/arch/auto/Mytest/Mytest.so
207        cp Mytest.bs blib/arch/auto/Mytest/Mytest.bs
208        chmod 644 blib/arch/auto/Mytest/Mytest.bs
209        Manifying blib/man3/Mytest.3pm
210        %
211
212       You can safely ignore the line about "prototyping behavior" - it is
213       explained in "The PROTOTYPES: Keyword" in perlxs.
214
215       Perl has its own special way of easily writing test scripts, but for
216       this example only, we'll create our own test script.  Create a file
217       called hello that looks like this:
218
219           #! /opt/perl5/bin/perl
220
221           use ExtUtils::testlib;
222
223           use Mytest;
224
225           Mytest::hello();
226
227       Now we make the script executable ("chmod +x hello"), run the script
228       and we should see the following output:
229
230           % ./hello
231           Hello, world!
232           %
233
234   EXAMPLE 2
235       Now let's add to our extension a subroutine that will take a single
236       numeric argument as input and return 1 if the number is even or 0 if
237       the number is odd.
238
239       Add the following to the end of Mytest.xs:
240
241           int
242           is_even(input)
243                   int input
244               CODE:
245                   RETVAL = (input % 2 == 0);
246               OUTPUT:
247                   RETVAL
248
249       There does not need to be whitespace at the start of the ""int input""
250       line, but it is useful for improving readability.  Placing a semi-colon
251       at the end of that line is also optional.  Any amount and kind of
252       whitespace may be placed between the ""int"" and ""input"".
253
254       Now re-run make to rebuild our new shared library.
255
256       Now perform the same steps as before, generating a Makefile from the
257       Makefile.PL file, and running make.
258
259       In order to test that our extension works, we now need to look at the
260       file Mytest.t.  This file is set up to imitate the same kind of testing
261       structure that Perl itself has.  Within the test script, you perform a
262       number of tests to confirm the behavior of the extension, printing "ok"
263       when the test is correct, "not ok" when it is not.
264
265           use Test::More tests => 4;
266           BEGIN { use_ok('Mytest') };
267
268           #########################
269
270           # Insert your test code below, the Test::More module is use()ed here
271           # so read its man page ( perldoc Test::More ) for help writing this
272           # test script.
273
274           is(&Mytest::is_even(0), 1);
275           is(&Mytest::is_even(1), 0);
276           is(&Mytest::is_even(2), 1);
277
278       We will be calling the test script through the command ""make test"".
279       You should see output that looks something like this:
280
281        %make test
282        PERL_DL_NONLAZY=1 /usr/bin/perl "-MExtUtils::Command::MM" "-e"
283        "test_harness(0, 'blib/lib', 'blib/arch')" t/*.t
284        t/Mytest....ok
285        All tests successful.
286        Files=1, Tests=4, 0 wallclock secs ( 0.03 cusr + 0.00 csys = 0.03 CPU)
287        %
288
289   What has gone on?
290       The program h2xs is the starting point for creating extensions.  In
291       later examples we'll see how we can use h2xs to read header files and
292       generate templates to connect to C routines.
293
294       h2xs creates a number of files in the extension directory.  The file
295       Makefile.PL is a perl script which will generate a true Makefile to
296       build the extension.  We'll take a closer look at it later.
297
298       The .pm and .xs files contain the meat of the extension.  The .xs file
299       holds the C routines that make up the extension.  The .pm file contains
300       routines that tell Perl how to load your extension.
301
302       Generating the Makefile and running "make" created a directory called
303       blib (which stands for "build library") in the current working
304       directory.  This directory will contain the shared library that we will
305       build.  Once we have tested it, we can install it into its final
306       location.
307
308       Invoking the test script via ""make test"" did something very
309       important.  It invoked perl with all those "-I" arguments so that it
310       could find the various files that are part of the extension.  It is
311       very important that while you are still testing extensions that you use
312       ""make test"".  If you try to run the test script all by itself, you
313       will get a fatal error.  Another reason it is important to use ""make
314       test"" to run your test script is that if you are testing an upgrade to
315       an already-existing version, using ""make test"" ensures that you will
316       test your new extension, not the already-existing version.
317
318       When Perl sees a "use extension;", it searches for a file with the same
319       name as the "use"'d extension that has a .pm suffix.  If that file
320       cannot be found, Perl dies with a fatal error.  The default search path
321       is contained in the @INC array.
322
323       In our case, Mytest.pm tells perl that it will need the Exporter and
324       Dynamic Loader extensions.  It then sets the @ISA and @EXPORT arrays
325       and the $VERSION scalar; finally it tells perl to bootstrap the module.
326       Perl will call its dynamic loader routine (if there is one) and load
327       the shared library.
328
329       The two arrays @ISA and @EXPORT are very important.  The @ISA array
330       contains a list of other packages in which to search for methods (or
331       subroutines) that do not exist in the current package.  This is usually
332       only important for object-oriented extensions (which we will talk about
333       much later), and so usually doesn't need to be modified.
334
335       The @EXPORT array tells Perl which of the extension's variables and
336       subroutines should be placed into the calling package's namespace.
337       Because you don't know if the user has already used your variable and
338       subroutine names, it's vitally important to carefully select what to
339       export.  Do not export method or variable names by default without a
340       good reason.
341
342       As a general rule, if the module is trying to be object-oriented then
343       don't export anything.  If it's just a collection of functions and
344       variables, then you can export them via another array, called
345       @EXPORT_OK.  This array does not automatically place its subroutine and
346       variable names into the namespace unless the user specifically requests
347       that this be done.
348
349       See perlmod for more information.
350
351       The $VERSION variable is used to ensure that the .pm file and the
352       shared library are "in sync" with each other.  Any time you make
353       changes to the .pm or .xs files, you should increment the value of this
354       variable.
355
356   Writing good test scripts
357       The importance of writing good test scripts cannot be over-emphasized.
358       You should closely follow the "ok/not ok" style that Perl itself uses,
359       so that it is very easy and unambiguous to determine the outcome of
360       each test case.  When you find and fix a bug, make sure you add a test
361       case for it.
362
363       By running ""make test"", you ensure that your Mytest.t script runs and
364       uses the correct version of your extension.  If you have many test
365       cases, save your test files in the "t" directory and use the suffix
366       ".t".  When you run ""make test"", all of these test files will be
367       executed.
368
369   EXAMPLE 3
370       Our third extension will take one argument as its input, round off that
371       value, and set the argument to the rounded value.
372
373       Add the following to the end of Mytest.xs:
374
375               void
376               round(arg)
377                       double  arg
378                   CODE:
379                       if (arg > 0.0) {
380                               arg = floor(arg + 0.5);
381                       } else if (arg < 0.0) {
382                               arg = ceil(arg - 0.5);
383                       } else {
384                               arg = 0.0;
385                       }
386                   OUTPUT:
387                       arg
388
389       Edit the Makefile.PL file so that the corresponding line looks like
390       this:
391
392               'LIBS'      => ['-lm'],   # e.g., '-lm'
393
394       Generate the Makefile and run make.  Change the test number in Mytest.t
395       to "9" and add the following tests:
396
397               $i = -1.5; &Mytest::round($i); is( $i, -2.0 );
398               $i = -1.1; &Mytest::round($i); is( $i, -1.0 );
399               $i = 0.0; &Mytest::round($i);  is( $i,  0.0 );
400               $i = 0.5; &Mytest::round($i);  is( $i,  1.0 );
401               $i = 1.2; &Mytest::round($i);  is( $i,  1.0 );
402
403       Running ""make test"" should now print out that all nine tests are
404       okay.
405
406       Notice that in these new test cases, the argument passed to round was a
407       scalar variable.  You might be wondering if you can round a constant or
408       literal.  To see what happens, temporarily add the following line to
409       Mytest.t:
410
411               &Mytest::round(3);
412
413       Run ""make test"" and notice that Perl dies with a fatal error.  Perl
414       won't let you change the value of constants!
415
416   What's new here?
417       ·   We've made some changes to Makefile.PL.  In this case, we've
418           specified an extra library to be linked into the extension's shared
419           library, the math library libm in this case.  We'll talk later
420           about how to write XSUBs that can call every routine in a library.
421
422       ·   The value of the function is not being passed back as the
423           function's return value, but by changing the value of the variable
424           that was passed into the function.  You might have guessed that
425           when you saw that the return value of round is of type "void".
426
427   Input and Output Parameters
428       You specify the parameters that will be passed into the XSUB on the
429       line(s) after you declare the function's return value and name.  Each
430       input parameter line starts with optional whitespace, and may have an
431       optional terminating semicolon.
432
433       The list of output parameters occurs at the very end of the function,
434       just after the OUTPUT: directive.  The use of RETVAL tells Perl that
435       you wish to send this value back as the return value of the XSUB
436       function.  In Example 3, we wanted the "return value" placed in the
437       original variable which we passed in, so we listed it (and not RETVAL)
438       in the OUTPUT: section.
439
440   The XSUBPP Program
441       The xsubpp program takes the XS code in the .xs file and translates it
442       into C code, placing it in a file whose suffix is .c.  The C code
443       created makes heavy use of the C functions within Perl.
444
445   The TYPEMAP file
446       The xsubpp program uses rules to convert from Perl's data types
447       (scalar, array, etc.) to C's data types (int, char, etc.).  These rules
448       are stored in the typemap file ($PERLLIB/ExtUtils/typemap).  There's a
449       brief discussion below, but all the nitty-gritty details can be found
450       in perlxstypemap.  If you have a new-enough version of perl (5.16 and
451       up) or an upgraded XS compiler ("ExtUtils::ParseXS" 3.13_01 or better),
452       then you can inline typemaps in your XS instead of writing separate
453       files.  Either way, this typemap thing is split into three parts:
454
455       The first section maps various C data types to a name, which
456       corresponds somewhat with the various Perl types.  The second section
457       contains C code which xsubpp uses to handle input parameters.  The
458       third section contains C code which xsubpp uses to handle output
459       parameters.
460
461       Let's take a look at a portion of the .c file created for our
462       extension.  The file name is Mytest.c:
463
464               XS(XS_Mytest_round)
465               {
466                   dXSARGS;
467                   if (items != 1)
468                       Perl_croak(aTHX_ "Usage: Mytest::round(arg)");
469                   PERL_UNUSED_VAR(cv); /* -W */
470                   {
471                       double  arg = (double)SvNV(ST(0));      /* XXXXX */
472                       if (arg > 0.0) {
473                               arg = floor(arg + 0.5);
474                       } else if (arg < 0.0) {
475                               arg = ceil(arg - 0.5);
476                       } else {
477                               arg = 0.0;
478                       }
479                       sv_setnv(ST(0), (double)arg);   /* XXXXX */
480                       SvSETMAGIC(ST(0));
481                   }
482                   XSRETURN_EMPTY;
483               }
484
485       Notice the two lines commented with "XXXXX".  If you check the first
486       part of the typemap file (or section), you'll see that doubles are of
487       type T_DOUBLE.  In the INPUT part of the typemap, an argument that is
488       T_DOUBLE is assigned to the variable arg by calling the routine SvNV on
489       something, then casting it to double, then assigned to the variable
490       arg.  Similarly, in the OUTPUT section, once arg has its final value,
491       it is passed to the sv_setnv function to be passed back to the calling
492       subroutine.  These two functions are explained in perlguts; we'll talk
493       more later about what that "ST(0)" means in the section on the argument
494       stack.
495
496   Warning about Output Arguments
497       In general, it's not a good idea to write extensions that modify their
498       input parameters, as in Example 3.  Instead, you should probably return
499       multiple values in an array and let the caller handle them (we'll do
500       this in a later example).  However, in order to better accommodate
501       calling pre-existing C routines, which often do modify their input
502       parameters, this behavior is tolerated.
503
504   EXAMPLE 4
505       In this example, we'll now begin to write XSUBs that will interact with
506       pre-defined C libraries.  To begin with, we will build a small library
507       of our own, then let h2xs write our .pm and .xs files for us.
508
509       Create a new directory called Mytest2 at the same level as the
510       directory Mytest.  In the Mytest2 directory, create another directory
511       called mylib, and cd into that directory.
512
513       Here we'll create some files that will generate a test library.  These
514       will include a C source file and a header file.  We'll also create a
515       Makefile.PL in this directory.  Then we'll make sure that running make
516       at the Mytest2 level will automatically run this Makefile.PL file and
517       the resulting Makefile.
518
519       In the mylib directory, create a file mylib.h that looks like this:
520
521               #define TESTVAL 4
522
523               extern double   foo(int, long, const char*);
524
525       Also create a file mylib.c that looks like this:
526
527               #include <stdlib.h>
528               #include "./mylib.h"
529
530               double
531               foo(int a, long b, const char *c)
532               {
533                       return (a + b + atof(c) + TESTVAL);
534               }
535
536       And finally create a file Makefile.PL that looks like this:
537
538               use ExtUtils::MakeMaker;
539               $Verbose = 1;
540               WriteMakefile(
541                   NAME   => 'Mytest2::mylib',
542                   SKIP   => [qw(all static static_lib dynamic dynamic_lib)],
543                   clean  => {'FILES' => 'libmylib$(LIB_EXT)'},
544               );
545
546
547               sub MY::top_targets {
548                       '
549               all :: static
550
551               pure_all :: static
552
553               static ::       libmylib$(LIB_EXT)
554
555               libmylib$(LIB_EXT): $(O_FILES)
556                       $(AR) cr libmylib$(LIB_EXT) $(O_FILES)
557                       $(RANLIB) libmylib$(LIB_EXT)
558
559               ';
560               }
561
562       Make sure you use a tab and not spaces on the lines beginning with
563       "$(AR)" and "$(RANLIB)".  Make will not function properly if you use
564       spaces.  It has also been reported that the "cr" argument to $(AR) is
565       unnecessary on Win32 systems.
566
567       We will now create the main top-level Mytest2 files.  Change to the
568       directory above Mytest2 and run the following command:
569
570               % h2xs -O -n Mytest2 ./Mytest2/mylib/mylib.h
571
572       This will print out a warning about overwriting Mytest2, but that's
573       okay.  Our files are stored in Mytest2/mylib, and will be untouched.
574
575       The normal Makefile.PL that h2xs generates doesn't know about the mylib
576       directory.  We need to tell it that there is a subdirectory and that we
577       will be generating a library in it.  Let's add the argument MYEXTLIB to
578       the WriteMakefile call so that it looks like this:
579
580               WriteMakefile(
581                   'NAME'      => 'Mytest2',
582                   'VERSION_FROM' => 'Mytest2.pm', # finds $VERSION
583                   'LIBS'      => [''],   # e.g., '-lm'
584                   'DEFINE'    => '',     # e.g., '-DHAVE_SOMETHING'
585                   'INC'       => '',     # e.g., '-I/usr/include/other'
586                   'MYEXTLIB' => 'mylib/libmylib$(LIB_EXT)',
587               );
588
589       and then at the end add a subroutine (which will override the pre-
590       existing subroutine).  Remember to use a tab character to indent the
591       line beginning with "cd"!
592
593               sub MY::postamble {
594               '
595               $(MYEXTLIB): mylib/Makefile
596                       cd mylib && $(MAKE) $(PASSTHRU)
597               ';
598               }
599
600       Let's also fix the MANIFEST file so that it accurately reflects the
601       contents of our extension.  The single line that says "mylib" should be
602       replaced by the following three lines:
603
604               mylib/Makefile.PL
605               mylib/mylib.c
606               mylib/mylib.h
607
608       To keep our namespace nice and unpolluted, edit the .pm file and change
609       the variable @EXPORT to @EXPORT_OK.  Finally, in the .xs file, edit the
610       #include line to read:
611
612               #include "mylib/mylib.h"
613
614       And also add the following function definition to the end of the .xs
615       file:
616
617               double
618               foo(a,b,c)
619                       int             a
620                       long            b
621                       const char *    c
622                   OUTPUT:
623                       RETVAL
624
625       Now we also need to create a typemap because the default Perl doesn't
626       currently support the "const char *" type.  Include a new TYPEMAP
627       section in your XS code before the above function:
628
629               TYPEMAP: <<END
630               const char *    T_PV
631               END
632
633       Now run perl on the top-level Makefile.PL.  Notice that it also created
634       a Makefile in the mylib directory.  Run make and watch that it does cd
635       into the mylib directory and run make in there as well.
636
637       Now edit the Mytest2.t script and change the number of tests to "4",
638       and add the following lines to the end of the script:
639
640               is( &Mytest2::foo(1, 2, "Hello, world!"), 7 );
641               is( &Mytest2::foo(1, 2, "0.0"), 7 );
642               ok( abs(&Mytest2::foo(0, 0, "-3.4") - 0.6) <= 0.01 );
643
644       (When dealing with floating-point comparisons, it is best to not check
645       for equality, but rather that the difference between the expected and
646       actual result is below a certain amount (called epsilon) which is 0.01
647       in this case)
648
649       Run ""make test"" and all should be well. There are some warnings on
650       missing tests for the Mytest2::mylib extension, but you can ignore
651       them.
652
653   What has happened here?
654       Unlike previous examples, we've now run h2xs on a real include file.
655       This has caused some extra goodies to appear in both the .pm and .xs
656       files.
657
658       ·   In the .xs file, there's now a #include directive with the absolute
659           path to the mylib.h header file.  We changed this to a relative
660           path so that we could move the extension directory if we wanted to.
661
662       ·   There's now some new C code that's been added to the .xs file.  The
663           purpose of the "constant" routine is to make the values that are
664           #define'd in the header file accessible by the Perl script (by
665           calling either "TESTVAL" or &Mytest2::TESTVAL).  There's also some
666           XS code to allow calls to the "constant" routine.
667
668       ·   The .pm file originally exported the name "TESTVAL" in the @EXPORT
669           array.  This could lead to name clashes.  A good rule of thumb is
670           that if the #define is only going to be used by the C routines
671           themselves, and not by the user, they should be removed from the
672           @EXPORT array.  Alternately, if you don't mind using the "fully
673           qualified name" of a variable, you could move most or all of the
674           items from the @EXPORT array into the @EXPORT_OK array.
675
676       ·   If our include file had contained #include directives, these would
677           not have been processed by h2xs.  There is no good solution to this
678           right now.
679
680       ·   We've also told Perl about the library that we built in the mylib
681           subdirectory.  That required only the addition of the "MYEXTLIB"
682           variable to the WriteMakefile call and the replacement of the
683           postamble subroutine to cd into the subdirectory and run make.  The
684           Makefile.PL for the library is a bit more complicated, but not
685           excessively so.  Again we replaced the postamble subroutine to
686           insert our own code.  This code simply specified that the library
687           to be created here was a static archive library (as opposed to a
688           dynamically loadable library) and provided the commands to build
689           it.
690
691   Anatomy of .xs file
692       The .xs file of "EXAMPLE 4" contained some new elements.  To understand
693       the meaning of these elements, pay attention to the line which reads
694
695               MODULE = Mytest2                PACKAGE = Mytest2
696
697       Anything before this line is plain C code which describes which headers
698       to include, and defines some convenience functions.  No translations
699       are performed on this part, apart from having embedded POD
700       documentation skipped over (see perlpod) it goes into the generated
701       output C file as is.
702
703       Anything after this line is the description of XSUB functions.  These
704       descriptions are translated by xsubpp into C code which implements
705       these functions using Perl calling conventions, and which makes these
706       functions visible from Perl interpreter.
707
708       Pay a special attention to the function "constant".  This name appears
709       twice in the generated .xs file: once in the first part, as a static C
710       function, then another time in the second part, when an XSUB interface
711       to this static C function is defined.
712
713       This is quite typical for .xs files: usually the .xs file provides an
714       interface to an existing C function.  Then this C function is defined
715       somewhere (either in an external library, or in the first part of .xs
716       file), and a Perl interface to this function (i.e. "Perl glue") is
717       described in the second part of .xs file.  The situation in "EXAMPLE
718       1", "EXAMPLE 2", and "EXAMPLE 3", when all the work is done inside the
719       "Perl glue", is somewhat of an exception rather than the rule.
720
721   Getting the fat out of XSUBs
722       In "EXAMPLE 4" the second part of .xs file contained the following
723       description of an XSUB:
724
725               double
726               foo(a,b,c)
727                       int             a
728                       long            b
729                       const char *    c
730                   OUTPUT:
731                       RETVAL
732
733       Note that in contrast with "EXAMPLE 1", "EXAMPLE 2" and "EXAMPLE 3",
734       this description does not contain the actual code for what is done
735       during a call to Perl function foo().  To understand what is going on
736       here, one can add a CODE section to this XSUB:
737
738               double
739               foo(a,b,c)
740                       int             a
741                       long            b
742                       const char *    c
743                   CODE:
744                       RETVAL = foo(a,b,c);
745                   OUTPUT:
746                       RETVAL
747
748       However, these two XSUBs provide almost identical generated C code:
749       xsubpp compiler is smart enough to figure out the "CODE:" section from
750       the first two lines of the description of XSUB.  What about "OUTPUT:"
751       section?  In fact, that is absolutely the same!  The "OUTPUT:" section
752       can be removed as well, as far as "CODE:" section or "PPCODE:" section
753       is not specified: xsubpp can see that it needs to generate a function
754       call section, and will autogenerate the OUTPUT section too.  Thus one
755       can shortcut the XSUB to become:
756
757               double
758               foo(a,b,c)
759                       int             a
760                       long            b
761                       const char *    c
762
763       Can we do the same with an XSUB
764
765               int
766               is_even(input)
767                       int     input
768                   CODE:
769                       RETVAL = (input % 2 == 0);
770                   OUTPUT:
771                       RETVAL
772
773       of "EXAMPLE 2"?  To do this, one needs to define a C function "int
774       is_even(int input)".  As we saw in "Anatomy of .xs file", a proper
775       place for this definition is in the first part of .xs file.  In fact a
776       C function
777
778               int
779               is_even(int arg)
780               {
781                       return (arg % 2 == 0);
782               }
783
784       is probably overkill for this.  Something as simple as a "#define" will
785       do too:
786
787               #define is_even(arg)    ((arg) % 2 == 0)
788
789       After having this in the first part of .xs file, the "Perl glue" part
790       becomes as simple as
791
792               int
793               is_even(input)
794                       int     input
795
796       This technique of separation of the glue part from the workhorse part
797       has obvious tradeoffs: if you want to change a Perl interface, you need
798       to change two places in your code.  However, it removes a lot of
799       clutter, and makes the workhorse part independent from idiosyncrasies
800       of Perl calling convention.  (In fact, there is nothing Perl-specific
801       in the above description, a different version of xsubpp might have
802       translated this to TCL glue or Python glue as well.)
803
804   More about XSUB arguments
805       With the completion of Example 4, we now have an easy way to simulate
806       some real-life libraries whose interfaces may not be the cleanest in
807       the world.  We shall now continue with a discussion of the arguments
808       passed to the xsubpp compiler.
809
810       When you specify arguments to routines in the .xs file, you are really
811       passing three pieces of information for each argument listed.  The
812       first piece is the order of that argument relative to the others
813       (first, second, etc).  The second is the type of argument, and consists
814       of the type declaration of the argument (e.g., int, char*, etc).  The
815       third piece is the calling convention for the argument in the call to
816       the library function.
817
818       While Perl passes arguments to functions by reference, C passes
819       arguments by value; to implement a C function which modifies data of
820       one of the "arguments", the actual argument of this C function would be
821       a pointer to the data.  Thus two C functions with declarations
822
823               int string_length(char *s);
824               int upper_case_char(char *cp);
825
826       may have completely different semantics: the first one may inspect an
827       array of chars pointed by s, and the second one may immediately
828       dereference "cp" and manipulate *cp only (using the return value as,
829       say, a success indicator).  From Perl one would use these functions in
830       a completely different manner.
831
832       One conveys this info to xsubpp by replacing "*" before the argument by
833       "&".  "&" means that the argument should be passed to a library
834       function by its address.  The above two function may be XSUB-ified as
835
836               int
837               string_length(s)
838                       char *  s
839
840               int
841               upper_case_char(cp)
842                       char    &cp
843
844       For example, consider:
845
846               int
847               foo(a,b)
848                       char    &a
849                       char *  b
850
851       The first Perl argument to this function would be treated as a char and
852       assigned to the variable a, and its address would be passed into the
853       function foo. The second Perl argument would be treated as a string
854       pointer and assigned to the variable b. The value of b would be passed
855       into the function foo.  The actual call to the function foo that xsubpp
856       generates would look like this:
857
858               foo(&a, b);
859
860       xsubpp will parse the following function argument lists identically:
861
862               char    &a
863               char&a
864               char    & a
865
866       However, to help ease understanding, it is suggested that you place a
867       "&" next to the variable name and away from the variable type), and
868       place a "*" near the variable type, but away from the variable name (as
869       in the call to foo above).  By doing so, it is easy to understand
870       exactly what will be passed to the C function; it will be whatever is
871       in the "last column".
872
873       You should take great pains to try to pass the function the type of
874       variable it wants, when possible.  It will save you a lot of trouble in
875       the long run.
876
877   The Argument Stack
878       If we look at any of the C code generated by any of the examples except
879       example 1, you will notice a number of references to ST(n), where n is
880       usually 0.  "ST" is actually a macro that points to the n'th argument
881       on the argument stack.  ST(0) is thus the first argument on the stack
882       and therefore the first argument passed to the XSUB, ST(1) is the
883       second argument, and so on.
884
885       When you list the arguments to the XSUB in the .xs file, that tells
886       xsubpp which argument corresponds to which of the argument stack (i.e.,
887       the first one listed is the first argument, and so on).  You invite
888       disaster if you do not list them in the same order as the function
889       expects them.
890
891       The actual values on the argument stack are pointers to the values
892       passed in.  When an argument is listed as being an OUTPUT value, its
893       corresponding value on the stack (i.e., ST(0) if it was the first
894       argument) is changed.  You can verify this by looking at the C code
895       generated for Example 3.  The code for the round() XSUB routine
896       contains lines that look like this:
897
898               double  arg = (double)SvNV(ST(0));
899               /* Round the contents of the variable arg */
900               sv_setnv(ST(0), (double)arg);
901
902       The arg variable is initially set by taking the value from ST(0), then
903       is stored back into ST(0) at the end of the routine.
904
905       XSUBs are also allowed to return lists, not just scalars.  This must be
906       done by manipulating stack values ST(0), ST(1), etc, in a subtly
907       different way.  See perlxs for details.
908
909       XSUBs are also allowed to avoid automatic conversion of Perl function
910       arguments to C function arguments.  See perlxs for details.  Some
911       people prefer manual conversion by inspecting ST(i) even in the cases
912       when automatic conversion will do, arguing that this makes the logic of
913       an XSUB call clearer.  Compare with "Getting the fat out of XSUBs" for
914       a similar tradeoff of a complete separation of "Perl glue" and
915       "workhorse" parts of an XSUB.
916
917       While experts may argue about these idioms, a novice to Perl guts may
918       prefer a way which is as little Perl-guts-specific as possible, meaning
919       automatic conversion and automatic call generation, as in "Getting the
920       fat out of XSUBs".  This approach has the additional benefit of
921       protecting the XSUB writer from future changes to the Perl API.
922
923   Extending your Extension
924       Sometimes you might want to provide some extra methods or subroutines
925       to assist in making the interface between Perl and your extension
926       simpler or easier to understand.  These routines should live in the .pm
927       file.  Whether they are automatically loaded when the extension itself
928       is loaded or only loaded when called depends on where in the .pm file
929       the subroutine definition is placed.  You can also consult AutoLoader
930       for an alternate way to store and load your extra subroutines.
931
932   Documenting your Extension
933       There is absolutely no excuse for not documenting your extension.
934       Documentation belongs in the .pm file.  This file will be fed to
935       pod2man, and the embedded documentation will be converted to the
936       manpage format, then placed in the blib directory.  It will be copied
937       to Perl's manpage directory when the extension is installed.
938
939       You may intersperse documentation and Perl code within the .pm file.
940       In fact, if you want to use method autoloading, you must do this, as
941       the comment inside the .pm file explains.
942
943       See perlpod for more information about the pod format.
944
945   Installing your Extension
946       Once your extension is complete and passes all its tests, installing it
947       is quite simple: you simply run "make install".  You will either need
948       to have write permission into the directories where Perl is installed,
949       or ask your system administrator to run the make for you.
950
951       Alternately, you can specify the exact directory to place the
952       extension's files by placing a "PREFIX=/destination/directory" after
953       the make install (or in between the make and install if you have a
954       brain-dead version of make).  This can be very useful if you are
955       building an extension that will eventually be distributed to multiple
956       systems.  You can then just archive the files in the destination
957       directory and distribute them to your destination systems.
958
959   EXAMPLE 5
960       In this example, we'll do some more work with the argument stack.  The
961       previous examples have all returned only a single value.  We'll now
962       create an extension that returns an array.
963
964       This extension is very Unix-oriented (struct statfs and the statfs
965       system call).  If you are not running on a Unix system, you can
966       substitute for statfs any other function that returns multiple values,
967       you can hard-code values to be returned to the caller (although this
968       will be a bit harder to test the error case), or you can simply not do
969       this example.  If you change the XSUB, be sure to fix the test cases to
970       match the changes.
971
972       Return to the Mytest directory and add the following code to the end of
973       Mytest.xs:
974
975               void
976               statfs(path)
977                       char *  path
978                   INIT:
979                       int i;
980                       struct statfs buf;
981
982                   PPCODE:
983                       i = statfs(path, &buf);
984                       if (i == 0) {
985                               XPUSHs(sv_2mortal(newSVnv(buf.f_bavail)));
986                               XPUSHs(sv_2mortal(newSVnv(buf.f_bfree)));
987                               XPUSHs(sv_2mortal(newSVnv(buf.f_blocks)));
988                               XPUSHs(sv_2mortal(newSVnv(buf.f_bsize)));
989                               XPUSHs(sv_2mortal(newSVnv(buf.f_ffree)));
990                               XPUSHs(sv_2mortal(newSVnv(buf.f_files)));
991                               XPUSHs(sv_2mortal(newSVnv(buf.f_type)));
992                       } else {
993                               XPUSHs(sv_2mortal(newSVnv(errno)));
994                       }
995
996       You'll also need to add the following code to the top of the .xs file,
997       just after the include of "XSUB.h":
998
999               #include <sys/vfs.h>
1000
1001       Also add the following code segment to Mytest.t while incrementing the
1002       "9" tests to "11":
1003
1004               @a = &Mytest::statfs("/blech");
1005               ok( scalar(@a) == 1 && $a[0] == 2 );
1006               @a = &Mytest::statfs("/");
1007               is( scalar(@a), 7 );
1008
1009   New Things in this Example
1010       This example added quite a few new concepts.  We'll take them one at a
1011       time.
1012
1013       ·   The INIT: directive contains code that will be placed immediately
1014           after the argument stack is decoded.  C does not allow variable
1015           declarations at arbitrary locations inside a function, so this is
1016           usually the best way to declare local variables needed by the XSUB.
1017           (Alternatively, one could put the whole "PPCODE:" section into
1018           braces, and put these declarations on top.)
1019
1020       ·   This routine also returns a different number of arguments depending
1021           on the success or failure of the call to statfs.  If there is an
1022           error, the error number is returned as a single-element array.  If
1023           the call is successful, then a 7-element array is returned.  Since
1024           only one argument is passed into this function, we need room on the
1025           stack to hold the 7 values which may be returned.
1026
1027           We do this by using the PPCODE: directive, rather than the CODE:
1028           directive.  This tells xsubpp that we will be managing the return
1029           values that will be put on the argument stack by ourselves.
1030
1031       ·   When we want to place values to be returned to the caller onto the
1032           stack, we use the series of macros that begin with "XPUSH".  There
1033           are five different versions, for placing integers, unsigned
1034           integers, doubles, strings, and Perl scalars on the stack.  In our
1035           example, we placed a Perl scalar onto the stack.  (In fact this is
1036           the only macro which can be used to return multiple values.)
1037
1038           The XPUSH* macros will automatically extend the return stack to
1039           prevent it from being overrun.  You push values onto the stack in
1040           the order you want them seen by the calling program.
1041
1042       ·   The values pushed onto the return stack of the XSUB are actually
1043           mortal SV's.  They are made mortal so that once the values are
1044           copied by the calling program, the SV's that held the returned
1045           values can be deallocated.  If they were not mortal, then they
1046           would continue to exist after the XSUB routine returned, but would
1047           not be accessible.  This is a memory leak.
1048
1049       ·   If we were interested in performance, not in code compactness, in
1050           the success branch we would not use "XPUSHs" macros, but "PUSHs"
1051           macros, and would pre-extend the stack before pushing the return
1052           values:
1053
1054                   EXTEND(SP, 7);
1055
1056           The tradeoff is that one needs to calculate the number of return
1057           values in advance (though overextending the stack will not
1058           typically hurt anything but memory consumption).
1059
1060           Similarly, in the failure branch we could use "PUSHs" without
1061           extending the stack: the Perl function reference comes to an XSUB
1062           on the stack, thus the stack is always large enough to take one
1063           return value.
1064
1065   EXAMPLE 6
1066       In this example, we will accept a reference to an array as an input
1067       parameter, and return a reference to an array of hashes.  This will
1068       demonstrate manipulation of complex Perl data types from an XSUB.
1069
1070       This extension is somewhat contrived.  It is based on the code in the
1071       previous example.  It calls the statfs function multiple times,
1072       accepting a reference to an array of filenames as input, and returning
1073       a reference to an array of hashes containing the data for each of the
1074       filesystems.
1075
1076       Return to the Mytest directory and add the following code to the end of
1077       Mytest.xs:
1078
1079           SV *
1080           multi_statfs(paths)
1081                   SV * paths
1082               INIT:
1083                   AV * results;
1084                   SSize_t numpaths = 0, n;
1085                   int i;
1086                   struct statfs buf;
1087
1088                   SvGETMAGIC(paths);
1089                   if ((!SvROK(paths))
1090                       || (SvTYPE(SvRV(paths)) != SVt_PVAV)
1091                       || ((numpaths = av_top_index((AV *)SvRV(paths))) < 0))
1092                   {
1093                       XSRETURN_UNDEF;
1094                   }
1095                   results = (AV *)sv_2mortal((SV *)newAV());
1096               CODE:
1097                   for (n = 0; n <= numpaths; n++) {
1098                       HV * rh;
1099                       STRLEN l;
1100                       char * fn = SvPV(*av_fetch((AV *)SvRV(paths), n, 0), l);
1101
1102                       i = statfs(fn, &buf);
1103                       if (i != 0) {
1104                           av_push(results, newSVnv(errno));
1105                           continue;
1106                       }
1107
1108                       rh = (HV *)sv_2mortal((SV *)newHV());
1109
1110                       hv_store(rh, "f_bavail", 8, newSVnv(buf.f_bavail), 0);
1111                       hv_store(rh, "f_bfree",  7, newSVnv(buf.f_bfree),  0);
1112                       hv_store(rh, "f_blocks", 8, newSVnv(buf.f_blocks), 0);
1113                       hv_store(rh, "f_bsize",  7, newSVnv(buf.f_bsize),  0);
1114                       hv_store(rh, "f_ffree",  7, newSVnv(buf.f_ffree),  0);
1115                       hv_store(rh, "f_files",  7, newSVnv(buf.f_files),  0);
1116                       hv_store(rh, "f_type",   6, newSVnv(buf.f_type),   0);
1117
1118                       av_push(results, newRV_inc((SV *)rh));
1119                   }
1120                   RETVAL = newRV_inc((SV *)results);
1121               OUTPUT:
1122                   RETVAL
1123
1124       And add the following code to Mytest.t, while incrementing the "11"
1125       tests to "13":
1126
1127               $results = Mytest::multi_statfs([ '/', '/blech' ]);
1128               ok( ref $results->[0] );
1129               ok( ! ref $results->[1] );
1130
1131   New Things in this Example
1132       There are a number of new concepts introduced here, described below:
1133
1134       ·   This function does not use a typemap.  Instead, we declare it as
1135           accepting one SV* (scalar) parameter, and returning an SV* value,
1136           and we take care of populating these scalars within the code.
1137           Because we are only returning one value, we don't need a "PPCODE:"
1138           directive - instead, we use "CODE:" and "OUTPUT:" directives.
1139
1140       ·   When dealing with references, it is important to handle them with
1141           caution.  The "INIT:" block first calls SvGETMAGIC(paths), in case
1142           paths is a tied variable.  Then it checks that "SvROK" returns
1143           true, which indicates that paths is a valid reference.  (Simply
1144           checking "SvROK" won't trigger FETCH on a tied variable.)  It then
1145           verifies that the object referenced by paths is an array, using
1146           "SvRV" to dereference paths, and "SvTYPE" to discover its type.  As
1147           an added test, it checks that the array referenced by paths is non-
1148           empty, using the "av_top_index" function (which returns -1 if the
1149           array is empty). The XSRETURN_UNDEF macro is used to abort the XSUB
1150           and return the undefined value whenever all three of these
1151           conditions are not met.
1152
1153       ·   We manipulate several arrays in this XSUB.  Note that an array is
1154           represented internally by an AV* pointer.  The functions and macros
1155           for manipulating arrays are similar to the functions in Perl:
1156           "av_top_index" returns the highest index in an AV*, much like
1157           $#array; "av_fetch" fetches a single scalar value from an array,
1158           given its index; "av_push" pushes a scalar value onto the end of
1159           the array, automatically extending the array as necessary.
1160
1161           Specifically, we read pathnames one at a time from the input array,
1162           and store the results in an output array (results) in the same
1163           order.  If statfs fails, the element pushed onto the return array
1164           is the value of errno after the failure.  If statfs succeeds,
1165           though, the value pushed onto the return array is a reference to a
1166           hash containing some of the information in the statfs structure.
1167
1168           As with the return stack, it would be possible (and a small
1169           performance win) to pre-extend the return array before pushing data
1170           into it, since we know how many elements we will return:
1171
1172                   av_extend(results, numpaths);
1173
1174       ·   We are performing only one hash operation in this function, which
1175           is storing a new scalar under a key using "hv_store".  A hash is
1176           represented by an HV* pointer.  Like arrays, the functions for
1177           manipulating hashes from an XSUB mirror the functionality available
1178           from Perl.  See perlguts and perlapi for details.
1179
1180       ·   To create a reference, we use the "newRV_inc" function.  Note that
1181           you can cast an AV* or an HV* to type SV* in this case (and many
1182           others).  This allows you to take references to arrays, hashes and
1183           scalars with the same function.  Conversely, the "SvRV" function
1184           always returns an SV*, which may need to be cast to the appropriate
1185           type if it is something other than a scalar (check with "SvTYPE").
1186
1187       ·   At this point, xsubpp is doing very little work - the differences
1188           between Mytest.xs and Mytest.c are minimal.
1189
1190   EXAMPLE 7 (Coming Soon)
1191       XPUSH args AND set RETVAL AND assign return value to array
1192
1193   EXAMPLE 8 (Coming Soon)
1194       Setting $!
1195
1196   EXAMPLE 9 Passing open files to XSes
1197       You would think passing files to an XS is difficult, with all the
1198       typeglobs and stuff. Well, it isn't.
1199
1200       Suppose that for some strange reason we need a wrapper around the
1201       standard C library function "fputs()". This is all we need:
1202
1203               #define PERLIO_NOT_STDIO 0
1204               #define PERL_NO_GET_CONTEXT
1205               #include "EXTERN.h"
1206               #include "perl.h"
1207               #include "XSUB.h"
1208
1209               #include <stdio.h>
1210
1211               int
1212               fputs(s, stream)
1213                       char *          s
1214                       FILE *          stream
1215
1216       The real work is done in the standard typemap.
1217
1218       But you lose all the fine stuff done by the perlio layers. This calls
1219       the stdio function "fputs()", which knows nothing about them.
1220
1221       The standard typemap offers three variants of PerlIO *: "InputStream"
1222       (T_IN), "InOutStream" (T_INOUT) and "OutputStream" (T_OUT). A bare
1223       "PerlIO *" is considered a T_INOUT. If it matters in your code (see
1224       below for why it might) #define or typedef one of the specific names
1225       and use that as the argument or result type in your XS file.
1226
1227       The standard typemap does not contain PerlIO * before perl 5.7, but it
1228       has the three stream variants. Using a PerlIO * directly is not
1229       backwards compatible unless you provide your own typemap.
1230
1231       For streams coming from perl the main difference is that "OutputStream"
1232       will get the output PerlIO * - which may make a difference on a socket.
1233       Like in our example...
1234
1235       For streams being handed to perl a new file handle is created (i.e. a
1236       reference to a new glob) and associated with the PerlIO * provided. If
1237       the read/write state of the PerlIO * is not correct then you may get
1238       errors or warnings from when the file handle is used.  So if you opened
1239       the PerlIO * as "w" it should really be an "OutputStream" if open as
1240       "r" it should be an "InputStream".
1241
1242       Now, suppose you want to use perlio layers in your XS. We'll use the
1243       perlio "PerlIO_puts()" function as an example.
1244
1245       In the C part of the XS file (above the first MODULE line) you have
1246
1247               #define OutputStream    PerlIO *
1248           or
1249               typedef PerlIO *        OutputStream;
1250
1251       And this is the XS code:
1252
1253               int
1254               perlioputs(s, stream)
1255                       char *          s
1256                       OutputStream    stream
1257               CODE:
1258                       RETVAL = PerlIO_puts(stream, s);
1259               OUTPUT:
1260                       RETVAL
1261
1262       We have to use a "CODE" section because "PerlIO_puts()" has the
1263       arguments reversed compared to "fputs()", and we want to keep the
1264       arguments the same.
1265
1266       Wanting to explore this thoroughly, we want to use the stdio "fputs()"
1267       on a PerlIO *. This means we have to ask the perlio system for a stdio
1268       "FILE *":
1269
1270               int
1271               perliofputs(s, stream)
1272                       char *          s
1273                       OutputStream    stream
1274               PREINIT:
1275                       FILE *fp = PerlIO_findFILE(stream);
1276               CODE:
1277                       if (fp != (FILE*) 0) {
1278                               RETVAL = fputs(s, fp);
1279                       } else {
1280                               RETVAL = -1;
1281                       }
1282               OUTPUT:
1283                       RETVAL
1284
1285       Note: "PerlIO_findFILE()" will search the layers for a stdio layer. If
1286       it can't find one, it will call "PerlIO_exportFILE()" to generate a new
1287       stdio "FILE". Please only call "PerlIO_exportFILE()" if you want a new
1288       "FILE". It will generate one on each call and push a new stdio layer.
1289       So don't call it repeatedly on the same file. "PerlIO_findFILE()" will
1290       retrieve the stdio layer once it has been generated by
1291       "PerlIO_exportFILE()".
1292
1293       This applies to the perlio system only. For versions before 5.7,
1294       "PerlIO_exportFILE()" is equivalent to "PerlIO_findFILE()".
1295
1296   Troubleshooting these Examples
1297       As mentioned at the top of this document, if you are having problems
1298       with these example extensions, you might see if any of these help you.
1299
1300       ·   In versions of 5.002 prior to the gamma version, the test script in
1301           Example 1 will not function properly.  You need to change the "use
1302           lib" line to read:
1303
1304                   use lib './blib';
1305
1306       ·   In versions of 5.002 prior to version 5.002b1h, the test.pl file
1307           was not automatically created by h2xs.  This means that you cannot
1308           say "make test" to run the test script.  You will need to add the
1309           following line before the "use extension" statement:
1310
1311                   use lib './blib';
1312
1313       ·   In versions 5.000 and 5.001, instead of using the above line, you
1314           will need to use the following line:
1315
1316                   BEGIN { unshift(@INC, "./blib") }
1317
1318       ·   This document assumes that the executable named "perl" is Perl
1319           version 5.  Some systems may have installed Perl version 5 as
1320           "perl5".
1321

See also

1323       For more information, consult perlguts, perlapi, perlxs, perlmod, and
1324       perlpod.
1325

Author

1327       Jeff Okamoto <okamoto@corp.hp.com>
1328
1329       Reviewed and assisted by Dean Roehrich, Ilya Zakharevich, Andreas
1330       Koenig, and Tim Bunce.
1331
1332       PerlIO material contributed by Lupe Christoph, with some clarification
1333       by Nick Ing-Simmons.
1334
1335       Changes for h2xs as of Perl 5.8.x by Renee Baecker
1336
1337   Last Changed
1338       2012-01-20
1339
1340
1341
1342perl v5.28.1                      2018-12-05                      perlxstut(3)
Impressum