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