| blob | f777b40385c157e49af934c0f7a29f42b9d28cdc |
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
4 <head>
8 </head>
13 <big><strong><span class="block"> perlXStut - Tutorial for writing XSUBs</span></strong></big>
14 </td></tr>
15 </table>
18 <!-- INDEX BEGIN -->
20 <ul>
25 <ul>
29 <li><a href="#dynamic_loading_versus_static_loading">Dynamic Loading versus Static Loading</a></li>
30 </ul>
33 <ul>
60 <li><a href="#example_9_passing_open_files_to_xses">EXAMPLE 9 Passing open files to XSes</a></li>
62 </ul>
66 <ul>
69 </ul>
71 </ul>
72 <!-- INDEX END -->
74 <hr />
75 <p>
76 </p>
79 <p>
80 </p>
81 <hr />
83 <p>This tutorial will educate the reader on the steps involved in creating
84 a Perl extension. The reader is assumed to have access to <a href="file://C|\msysgit\mingw\html/pod/perlguts.html">the perlguts manpage</a>,
85 <a href="file://C|\msysgit\mingw\html/pod/perlapi.html">the perlapi manpage</a> and <a href="file://C|\msysgit\mingw\html/pod/perlxs.html">the perlxs manpage</a>.</p>
86 <p>This tutorial starts with very simple examples and becomes more complex,
87 with each new example adding new features. Certain concepts may not be
88 completely explained until later in the tutorial in order to slowly ease
89 the reader into building extensions.</p>
90 <p>This tutorial was written from a Unix point of view. Where I know them
91 to be otherwise different for other platforms (e.g. Win32), I will list
92 them. If you find something that was missed, please let me know.</p>
93 <p>
94 </p>
95 <hr />
97 <p>
98 </p>
100 <p>This tutorial assumes that the make program that Perl is configured to
102 follow, you may have to substitute whatever make program Perl has been
104 <p>
105 </p>
107 <p>When writing a Perl extension for general consumption, one should expect that
108 the extension will be used with versions of Perl different from the
109 version available on your machine. Since you are reading this document,
110 the version of Perl on your machine is probably 5.005 or later, but the users
111 of your extension may have more ancient versions.</p>
112 <p>To understand what kinds of incompatibilities one may expect, and in the rare
113 case that the version of Perl on your machine is older than this document,
114 see the section on ``Troubleshooting these Examples'' for more information.</p>
115 <p>If your extension uses some features of Perl which are not available on older
116 releases of Perl, your users would appreciate an early meaningful warning.
119 module or other tools.</p>
121 opportunity to perform version checks. One can put something like this
123 <pre>
124 eval { require 5.007 }
125 or die <<EOD;
126 ############
127 ### This module uses frobnication framework which is not available before
128 ### version 5.007 of Perl. Upgrade your Perl before installing Kara::Mba.
129 ############
130 EOD</pre>
131 <p>
132 </p>
133 <h2><a name="dynamic_loading_versus_static_loading">Dynamic Loading versus Static Loading</a></h2>
134 <p>It is commonly thought that if a system does not have the capability to
135 dynamically load a library, you cannot build XSUBs. This is incorrect.
137 rest of Perl, creating a new executable. This situation is similar to
139 <p>This tutorial can still be used on such a system. The XSUB build mechanism
140 will check the system and build a dynamically-loadable library if possible,
141 or else a static library and then, optionally, a new statically-linked
142 executable with that static library linked in.</p>
143 <p>Should you wish to build a statically-linked executable on a system which
144 can dynamically load libraries, you may, in all the following examples,
147 <p>If you have generated such a statically-linked executable by choice, then
149 On systems that cannot build dynamically-loadable libraries at all, simply
151 <p>
152 </p>
153 <hr />
156 <p>
157 </p>
159 <p>Our first extension will be very simple. When we call the routine in the
160 extension, it will print out a well-known message and return.</p>
162 possibly under ext/ if that directory exists in the current working
163 directory. Several files will be created in the Mytest dir, including
164 MANIFEST, Makefile.PL, Mytest.pm, Mytest.xs, test.pl, and Changes.</p>
165 <p>The MANIFEST file contains the names of all the files just created in the
166 Mytest directory.</p>
168 <pre>
169 use ExtUtils::MakeMaker;
170 # See lib/ExtUtils/MakeMaker.pm for details of how to influence
171 # the contents of the Makefile that is written.
172 WriteMakefile(
173 NAME => 'Mytest',
174 VERSION_FROM => 'Mytest.pm', # finds $VERSION
175 LIBS => [''], # e.g., '-lm'
176 DEFINE => '', # e.g., '-DHAVE_SOMETHING'
177 INC => '', # e.g., '-I/usr/include/other'
178 );</pre>
180 <pre>
181 package Mytest;</pre>
182 <pre>
183 use strict;
184 use warnings;</pre>
185 <pre>
186 require Exporter;
187 require DynaLoader;</pre>
188 <pre>
189 our @ISA = qw(Exporter DynaLoader);
190 # Items to export into callers namespace by default. Note: do not export
191 # names by default without a very good reason. Use EXPORT_OK instead.
192 # Do not simply export all your public functions/methods/constants.
193 our @EXPORT = qw(</pre>
194 <pre>
195 );
197 <pre>
198 bootstrap Mytest $VERSION;</pre>
199 <pre>
200 # Preloaded methods go here.</pre>
201 <pre>
202 # Autoload methods go after __END__, and are processed by the autosplit program.</pre>
203 <pre>
204 1;
205 __END__
206 # Below is the stub of documentation for your module. You better edit it!</pre>
207 <p>The rest of the .pm file contains sample code for providing documentation for
208 the extension.</p>
210 <pre>
214 <pre>
215 MODULE = Mytest PACKAGE = Mytest</pre>
217 <pre>
218 void
219 hello()
220 CODE:
222 <p>It is okay for the lines starting at the ``CODE:'' line to not be indented.
223 However, for readability purposes, it is suggested that you indent CODE:
224 one level and the lines following one more level.</p>
226 which make needs. Its output looks something like:</p>
227 <pre>
228 % perl Makefile.PL
229 Checking if your kit is complete...
230 Looks good
231 Writing Makefile for Mytest
232 %</pre>
233 <p>Now, running make will produce output that looks something like this (some
234 long lines have been shortened for clarity and some extraneous lines have
235 been deleted):</p>
236 <pre>
237 % make
240 Please specify prototyping behavior for Mytest.xs (see <a href="//C|\msysgit\mingw\html/pod/perlxs.html">perlxs</a> manual)
241 cc -c Mytest.c
242 Running Mkbootstrap for Mytest ()
243 chmod 644 Mytest.bs
244 LD_RUN_PATH="" ld -o ./blib/PA-RISC1.1/auto/Mytest/Mytest.sl -b Mytest.o
245 chmod 755 ./blib/PA-RISC1.1/auto/Mytest/Mytest.sl
246 cp Mytest.bs ./blib/PA-RISC1.1/auto/Mytest/Mytest.bs
247 chmod 644 ./blib/PA-RISC1.1/auto/Mytest/Mytest.bs
248 Manifying ./blib/man3/Mytest.3
249 %</pre>
250 <p>You can safely ignore the line about ``prototyping behavior'' - it is
251 explained in the section ``The PROTOTYPES: Keyword'' in <a href="file://C|\msysgit\mingw\html/pod/perlxs.html">the perlxs manpage</a>.</p>
252 <p>If you are on a Win32 system, and the build process fails with linker
253 errors for functions in the C library, check if your Perl is configured
255 case). If Perl is configured to use PerlCRT, you have to make sure
256 PerlCRT.lib is copied to the same location that msvcrt.lib lives in,
257 so that the compiler can find it on its own. msvcrt.lib is usually
258 found in the Visual C compiler's lib directory (e.g. C:/DevStudio/VC/lib).</p>
259 <p>Perl has its own special way of easily writing test scripts, but for this
260 example only, we'll create our own test script. Create a file called hello
261 that looks like this:</p>
262 <pre>
263 #! /opt/perl5/bin/perl</pre>
264 <pre>
265 use ExtUtils::testlib;</pre>
266 <pre>
267 use Mytest;</pre>
268 <pre>
269 Mytest::hello();</pre>
271 and we should see the following output:</p>
272 <pre>
273 % ./hello
274 Hello, world!
275 %</pre>
276 <p>
277 </p>
279 <p>Now let's add to our extension a subroutine that will take a single numeric
281 is odd.</p>
283 <pre>
284 int
285 is_even(input)
286 int input
287 CODE:
289 OUTPUT:
290 RETVAL</pre>
292 line, but it is useful for improving readability. Placing a semi-colon at
293 the end of that line is also optional. Any amount and kind of whitespace
294 may be placed between the ``<a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_int"><code>int</code></a>'' and ``<code>input</code>''.</p>
296 <p>Now perform the same steps as before, generating a Makefile from the
297 Makefile.PL file, and running make.</p>
298 <p>In order to test that our extension works, we now need to look at the
299 file test.pl. This file is set up to imitate the same kind of testing
300 structure that Perl itself has. Within the test script, you perform a
301 number of tests to confirm the behavior of the extension, printing ``ok''
302 when the test is correct, ``not ok'' when it is not. Change the print
304 to the end of the file:</p>
305 <pre>
308 print &Mytest::is_even(2) == 1 ? "ok 4" : "not ok 4", "\n";</pre>
310 should see output that looks something like this:</p>
311 <pre>
312 % make test
313 PERL_DL_NONLAZY=1 /opt/perl5.004/bin/perl (lots of -I arguments) test.pl
315 ok 1
316 ok 2
317 ok 3
318 ok 4
319 %</pre>
320 <p>
321 </p>
323 <p>The program h2xs is the starting point for creating extensions. In later
324 examples we'll see how we can use h2xs to read header files and generate
325 templates to connect to C routines.</p>
326 <p>h2xs creates a number of files in the extension directory. The file
327 Makefile.PL is a perl script which will generate a true Makefile to build
328 the extension. We'll take a closer look at it later.</p>
329 <p>The .pm and .xs files contain the meat of the extension. The .xs file holds
330 the C routines that make up the extension. The .pm file contains routines
331 that tell Perl how to load your extension.</p>
333 (which stands for ``build library'') in the current working directory. This
334 directory will contain the shared library that we will build. Once we have
335 tested it, we can install it into its final location.</p>
340 try to run the test script all by itself, you will get a fatal error.
342 script is that if you are testing an upgrade to an already-existing version,
344 already-existing version.</p>
346 as the <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_use"><code>use</code></a>'d extension that has a .pm suffix. If that file cannot be found,
347 Perl dies with a fatal error. The default search path is contained in the
348 <a href="file://C|\msysgit\mingw\html/pod/perlvar.html#item__inc"><code>@INC</code></a> array.</p>
349 <p>In our case, Mytest.pm tells perl that it will need the Exporter and Dynamic
352 will call its dynamic loader routine (if there is one) and load the shared
353 library.</p>
354 <p>The two arrays <code>@ISA</code> and <code>@EXPORT</code> are very important. The <code>@ISA</code>
355 array contains a list of other packages in which to search for methods (or
356 subroutines) that do not exist in the current package. This is usually
357 only important for object-oriented extensions (which we will talk about
358 much later), and so usually doesn't need to be modified.</p>
360 subroutines should be placed into the calling package's namespace. Because
361 you don't know if the user has already used your variable and subroutine
364 <p>As a general rule, if the module is trying to be object-oriented then don't
365 export anything. If it's just a collection of functions and variables, then
367 does not automatically place its subroutine and variable names into the
368 namespace unless the user specifically requests that this be done.</p>
369 <p>See <a href="file://C|\msysgit\mingw\html/pod/perlmod.html">the perlmod manpage</a> for more information.</p>
371 library are ``in sync'' with each other. Any time you make changes to
372 the .pm or .xs files, you should increment the value of this variable.</p>
373 <p>
374 </p>
376 <p>The importance of writing good test scripts cannot be overemphasized. You
377 should closely follow the ``ok/not ok'' style that Perl itself uses, so that
378 it is very easy and unambiguous to determine the outcome of each test case.
379 When you find and fix a bug, make sure you add a test case for it.</p>
381 the correct version of your extension. If you have many test cases, you
382 might want to copy Perl's test style. Create a directory named ``t'' in the
383 extension's directory and append the suffix ``.t'' to the names of your test
385 <p>
386 </p>
388 <p>Our third extension will take one argument as its input, round off that
391 <pre>
392 void
393 round(arg)
394 double arg
395 CODE:
397 arg = floor(arg + 0.5);
399 arg = ceil(arg - 0.5);
400 } else {
401 arg = 0.0;
402 }
403 OUTPUT:
404 arg</pre>
406 <pre>
408 <p>Generate the Makefile and run make. Change the BEGIN block to print
410 <pre>
411 $i = -1.5; &Mytest::round($i); print $i == -2.0 ? "ok 5" : "not ok 5", "\n";
412 $i = -1.1; &Mytest::round($i); print $i == -1.0 ? "ok 6" : "not ok 6", "\n";
413 $i = 0.0; &Mytest::round($i); print $i == 0.0 ? "ok 7" : "not ok 7", "\n";
414 $i = 0.5; &Mytest::round($i); print $i == 1.0 ? "ok 8" : "not ok 8", "\n";
415 $i = 1.2; &Mytest::round($i); print $i == 1.0 ? "ok 9" : "not ok 9", "\n";</pre>
417 <p>Notice that in these new test cases, the argument passed to round was a
418 scalar variable. You might be wondering if you can round a constant or
419 literal. To see what happens, temporarily add the following line to test.pl:</p>
420 <pre>
423 let you change the value of constants!</p>
424 <p>
425 </p>
427 <ul>
428 <li>
429 <p>We've made some changes to Makefile.PL. In this case, we've specified an
430 extra library to be linked into the extension's shared library, the math
431 library libm in this case. We'll talk later about how to write XSUBs that
432 can call every routine in a library.</p>
433 </li>
434 <li>
435 <p>The value of the function is not being passed back as the function's return
436 value, but by changing the value of the variable that was passed into the
437 function. You might have guessed that when you saw that the return value
438 of round is of type ``void''.</p>
439 </li>
440 </ul>
441 <p>
442 </p>
445 after you declare the function's return value and name. Each input parameter
446 line starts with optional whitespace, and may have an optional terminating
447 semicolon.</p>
448 <p>The list of output parameters occurs at the very end of the function, just
449 before after the OUTPUT: directive. The use of RETVAL tells Perl that you
450 wish to send this value back as the return value of the XSUB function. In
451 Example 3, we wanted the ``return value'' placed in the original variable
452 which we passed in, so we listed it (and not RETVAL) in the OUTPUT: section.</p>
453 <p>
454 </p>
457 C code, placing it in a file whose suffix is .c. The C code created makes
458 heavy use of the C functions within Perl.</p>
459 <p>
460 </p>
463 array, etc.) to C's data types (int, char, etc.). These rules are stored
464 in the typemap file ($PERLLIB/ExtUtils/typemap). This file is split into
465 three parts.</p>
466 <p>The first section maps various C data types to a name, which corresponds
467 somewhat with the various Perl types. The second section contains C code
470 <p>Let's take a look at a portion of the .c file created for our extension.
471 The file name is Mytest.c:</p>
472 <pre>
473 XS(XS_Mytest_round)
474 {
475 dXSARGS;
476 if (items != 1)
478 {
479 double arg = (double)SvNV(ST(0)); /* XXXXX */
481 arg = floor(arg + 0.5);
483 arg = ceil(arg - 0.5);
484 } else {
485 arg = 0.0;
486 }
487 sv_setnv(ST(0), (double)arg); /* XXXXX */
488 }
489 XSRETURN(1);
490 }</pre>
491 <p>Notice the two lines commented with ``XXXXX''. If you check the first section
492 of the typemap file, you'll see that doubles are of type T_DOUBLE. In the
493 INPUT section, an argument that is T_DOUBLE is assigned to the variable
494 arg by calling the routine SvNV on something, then casting it to double,
495 then assigned to the variable arg. Similarly, in the OUTPUT section,
496 once arg has its final value, it is passed to the sv_setnv function to
497 be passed back to the calling subroutine. These two functions are explained
498 in <a href="file://C|\msysgit\mingw\html/pod/perlguts.html">the perlguts manpage</a>; we'll talk more later about what that ``ST(0)'' means in the
499 section on the argument stack.</p>
500 <p>
501 </p>
503 <p>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.</p>
509 <p>
510 </p>
512 <p>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.</p>
515 <p>Create a new directory called Mytest2 at the same level as the directory
516 Mytest. In the Mytest2 directory, create another directory called mylib,
517 and cd into that directory.</p>
518 <p>Here we'll create some files that will generate a test library. These will
519 include a C source file and a header file. We'll also create a Makefile.PL
520 in this directory. Then we'll make sure that running make at the Mytest2
521 level will automatically run this Makefile.PL file and the resulting Makefile.</p>
523 <pre>
525 <pre>
526 extern double foo(int, long, const char*);</pre>
528 <pre>
531 <pre>
532 double
533 foo(int a, long b, const char *c)
534 {
535 return (a + b + atof(c) + TESTVAL);
536 }</pre>
538 <pre>
539 use ExtUtils::MakeMaker;
540 $Verbose = 1;
541 WriteMakefile(
542 NAME => 'Mytest2::mylib',
543 SKIP => [qw(all static static_lib dynamic dynamic_lib)],
545 );</pre>
546 <pre>
547 sub MY::top_targets {
548 '
549 all :: static</pre>
550 <pre>
551 pure_all :: static</pre>
552 <pre>
553 static :: libmylib$(LIB_EXT)</pre>
554 <pre>
555 libmylib$(LIB_EXT): $(O_FILES)
556 $(AR) cr libmylib$(LIB_EXT) $(O_FILES)
557 $(RANLIB) libmylib$(LIB_EXT)</pre>
558 <pre>
559 ';
560 }</pre>
561 <p>Make sure you use a tab and not spaces on the lines beginning with ``$(AR)''
562 and ``$(RANLIB)''. Make will not function properly if you use spaces.
563 It has also been reported that the ``cr'' argument to $(AR) is unnecessary
564 on Win32 systems.</p>
565 <p>We will now create the main top-level Mytest2 files. Change to the directory
566 above Mytest2 and run the following command:</p>
567 <pre>
568 % h2xs -O -n Mytest2 ./Mytest2/mylib/mylib.h</pre>
569 <p>This will print out a warning about overwriting Mytest2, but that's okay.
570 Our files are stored in Mytest2/mylib, and will be untouched.</p>
571 <p>The normal Makefile.PL that h2xs generates doesn't know about the mylib
572 directory. We need to tell it that there is a subdirectory and that we
573 will be generating a library in it. Let's add the argument MYEXTLIB to
574 the WriteMakefile call so that it looks like this:</p>
575 <pre>
576 WriteMakefile(
577 'NAME' => 'Mytest2',
578 'VERSION_FROM' => 'Mytest2.pm', # finds $VERSION
579 'LIBS' => [''], # e.g., '-lm'
580 'DEFINE' => '', # e.g., '-DHAVE_SOMETHING'
581 'INC' => '', # e.g., '-I/usr/include/other'
582 'MYEXTLIB' => 'mylib/libmylib$(LIB_EXT)',
583 );</pre>
584 <p>and then at the end add a subroutine (which will override the pre-existing
585 subroutine). Remember to use a tab character to indent the line beginning
586 with ``cd''!</p>
587 <pre>
588 sub MY::postamble {
589 '
590 $(MYEXTLIB): mylib/Makefile
591 cd mylib && $(MAKE) $(PASSTHRU)
592 ';
593 }</pre>
594 <p>Let's also fix the MANIFEST file so that it accurately reflects the contents
595 of our extension. The single line that says ``mylib'' should be replaced by
596 the following three lines:</p>
597 <pre>
598 mylib/Makefile.PL
599 mylib/mylib.c
600 mylib/mylib.h</pre>
601 <p>To keep our namespace nice and unpolluted, edit the .pm file and change
603 .xs file, edit the #include line to read:</p>
604 <pre>
607 <pre>
608 double
609 foo(a,b,c)
610 int a
611 long b
612 const char * c
613 OUTPUT:
614 RETVAL</pre>
615 <p>Now we also need to create a typemap file because the default Perl doesn't
616 currently support the const char * type. Create a file called typemap in
617 the Mytest2 directory and place the following in it:</p>
618 <pre>
619 const char * T_PV</pre>
620 <p>Now run perl on the top-level Makefile.PL. Notice that it also created a
621 Makefile in the mylib directory. Run make and watch that it does cd into
622 the mylib directory and run make in there as well.</p>
624 and add the following lines to the end of the script:</p>
625 <pre>
626 print &Mytest2::foo(1, 2, "Hello, world!") == 7 ? "ok 2\n" : "not ok 2\n";
627 print &Mytest2::foo(1, 2, "0.0") == 7 ? "ok 3\n" : "not ok 3\n";
628 print abs(&Mytest2::foo(0, 0, "-3.4") - 0.6) <= 0.01 ? "ok 4\n" : "not ok 4\n";</pre>
629 <p>(When dealing with floating-point comparisons, it is best to not check for
630 equality, but rather that the difference between the expected and actual
633 <p>
634 </p>
636 <p>Unlike previous examples, we've now run h2xs on a real include file. This
637 has caused some extra goodies to appear in both the .pm and .xs files.</p>
638 <ul>
639 <li>
640 <p>In the .xs file, there's now a #include directive with the absolute path to
641 the mylib.h header file. We changed this to a relative path so that we
642 could move the extension directory if we wanted to.</p>
643 </li>
644 <li>
645 <p>There's now some new C code that's been added to the .xs file. The purpose
650 </li>
651 <li>
652 <p>The .pm file originally exported the name <code>TESTVAL</code> in the <code>@EXPORT</code> array.
653 This could lead to name clashes. A good rule of thumb is that if the #define
654 is only going to be used by the C routines themselves, and not by the user,
656 mind using the ``fully qualified name'' of a variable, you could move most
657 or all of the items from the <code>@EXPORT</code> array into the <code>@EXPORT_OK</code> array.</p>
658 </li>
659 <li>
660 <p>If our include file had contained #include directives, these would not have
661 been processed by h2xs. There is no good solution to this right now.</p>
662 </li>
663 <li>
664 <p>We've also told Perl about the library that we built in the mylib
666 to the WriteMakefile call and the replacement of the postamble subroutine
667 to cd into the subdirectory and run make. The Makefile.PL for the
668 library is a bit more complicated, but not excessively so. Again we
669 replaced the postamble subroutine to insert our own code. This code
670 simply specified that the library to be created here was a static archive
671 library (as opposed to a dynamically loadable library) and provided the
672 commands to build it.</p>
673 </li>
674 </ul>
675 <p>
676 </p>
678 <p>The .xs file of <a href="#example_4">EXAMPLE 4</a> contained some new elements. To understand
679 the meaning of these elements, pay attention to the line which reads</p>
680 <pre>
681 MODULE = Mytest2 PACKAGE = Mytest2</pre>
682 <p>Anything before this line is plain C code which describes which headers
683 to include, and defines some convenience functions. No translations are
684 performed on this part, apart from having embedded POD documentation
685 skipped over (see <a href="file://C|\msysgit\mingw\html/pod/perlpod.html">the perlpod manpage</a>) it goes into the generated output C file as is.</p>
686 <p>Anything after this line is the description of XSUB functions.
688 implements these functions using Perl calling conventions, and which
689 makes these functions visible from Perl interpreter.</p>
691 twice in the generated .xs file: once in the first part, as a static C
692 function, then another time in the second part, when an XSUB interface to
693 this static C function is defined.</p>
694 <p>This is quite typical for .xs files: usually the .xs file provides
695 an interface to an existing C function. Then this C function is defined
696 somewhere (either in an external library, or in the first part of .xs file),
697 and a Perl interface to this function (i.e. ``Perl glue'') is described in the
698 second part of .xs file. The situation in <a href="#example_1">EXAMPLE 1</a>, <a href="#example_2">EXAMPLE 2</a>,
700 somewhat of an exception rather than the rule.</p>
701 <p>
702 </p>
705 description of an XSUB:</p>
706 <pre>
707 double
708 foo(a,b,c)
709 int a
710 long b
711 const char * c
712 OUTPUT:
713 RETVAL</pre>
714 <p>Note that in contrast with <a href="#example_1">EXAMPLE 1</a>, <a href="#example_2">EXAMPLE 2</a> and <a href="#example_3">EXAMPLE 3</a>,
716 is done during a call to Perl function foo(). To understand what is going
717 on here, one can add a CODE section to this XSUB:</p>
718 <pre>
719 double
720 foo(a,b,c)
721 int a
722 long b
723 const char * c
724 CODE:
725 RETVAL = foo(a,b,c);
726 OUTPUT:
727 RETVAL</pre>
734 section, and will autogenerate the OUTPUT section too. Thus one can
735 shortcut the XSUB to become:</p>
736 <pre>
737 double
738 foo(a,b,c)
739 int a
740 long b
741 const char * c</pre>
743 <pre>
744 int
745 is_even(input)
746 int input
747 CODE:
749 OUTPUT:
750 RETVAL</pre>
751 <p>of <a href="#example_2">EXAMPLE 2</a>? To do this, one needs to define a C function <code>int
752 is_even(int input)</code>. As we saw in <a href="#anatomy_of__xs_file">Anatomy of .xs file</a>, a proper place
753 for this definition is in the first part of .xs file. In fact a C function</p>
754 <pre>
755 int
756 is_even(int arg)
757 {
759 }</pre>
761 do too:</p>
762 <pre>
764 <p>After having this in the first part of .xs file, the ``Perl glue'' part becomes
765 as simple as</p>
766 <pre>
767 int
768 is_even(input)
769 int input</pre>
770 <p>This technique of separation of the glue part from the workhorse part has
771 obvious tradeoffs: if you want to change a Perl interface, you need to
772 change two places in your code. However, it removes a lot of clutter,
773 and makes the workhorse part independent from idiosyncrasies of Perl calling
774 convention. (In fact, there is nothing Perl-specific in the above description,
776 Python glue as well.)</p>
777 <p>
778 </p>
781 real-life libraries whose interfaces may not be the cleanest in the world.
782 We shall now continue with a discussion of the arguments passed to the
784 <p>When you specify arguments to routines in the .xs file, you are really
785 passing three pieces of information for each argument listed. The first
786 piece is the order of that argument relative to the others (first, second,
787 etc). The second is the type of argument, and consists of the type
788 declaration of the argument (e.g., int, char*, etc). The third piece is
789 the calling convention for the argument in the call to the library function.</p>
790 <p>While Perl passes arguments to functions by reference,
791 C passes arguments by value; to implement a C function which modifies data
792 of one of the ``arguments'', the actual argument of this C function would be
793 a pointer to the data. Thus two C functions with declarations</p>
794 <pre>
795 int string_length(char *s);
796 int upper_case_char(char *cp);</pre>
797 <p>may have completely different semantics: the first one may inspect an array
800 indicator). From Perl one would use these functions in
801 a completely different manner.</p>
803 argument by <code>&</code>. <code>&</code> means that the argument should be passed to a library
804 function by its address. The above two function may be XSUB-ified as</p>
805 <pre>
806 int
807 string_length(s)
808 char * s</pre>
809 <pre>
810 int
811 upper_case_char(cp)
814 <pre>
815 int
816 foo(a,b)
817 char &a
818 char * b</pre>
819 <p>The first Perl argument to this function would be treated as a char and assigned
820 to the variable a, and its address would be passed into the function foo.
821 The second Perl argument would be treated as a string pointer and assigned to the
823 actual call to the function foo that <strong>xsubpp</strong> generates would look like this:</p>
824 <pre>
827 <pre>
828 char &a
829 char&a
832 next to the variable name and away from the variable type), and place a
833 ``*'' near the variable type, but away from the variable name (as in the
834 call to foo above). By doing so, it is easy to understand exactly what
835 will be passed to the C function -- it will be whatever is in the ``last
836 column''.</p>
837 <p>You should take great pains to try to pass the function the type of variable
838 it wants, when possible. It will save you a lot of trouble in the long run.</p>
839 <p>
840 </p>
842 <p>If we look at any of the C code generated by any of the examples except
843 example 1, you will notice a number of references to ST(n), where n is
844 usually 0. ``ST'' is actually a macro that points to the n'th argument
847 argument, and so on.</p>
849 which argument corresponds to which of the argument stack (i.e., the first
850 one listed is the first argument, and so on). You invite disaster if you
851 do not list them in the same order as the function expects them.</p>
852 <p>The actual values on the argument stack are pointers to the values passed
853 in. When an argument is listed as being an OUTPUT value, its corresponding
855 You can verify this by looking at the C code generated for Example 3.
857 <pre>
858 double arg = (double)SvNV(ST(0));
859 /* Round the contents of the variable arg */
863 <p>XSUBs are also allowed to return lists, not just scalars. This must be
865 different way. See <a href="file://C|\msysgit\mingw\html/pod/perlxs.html">the perlxs manpage</a> for details.</p>
866 <p>XSUBs are also allowed to avoid automatic conversion of Perl function arguments
867 to C function arguments. See <a href="file://C|\msysgit\mingw\html/pod/perlxs.html">the perlxs manpage</a> for details. Some people prefer
869 conversion will do, arguing that this makes the logic of an XSUB call clearer.
870 Compare with <a href="#getting_the_fat_out_of_xsubs">Getting the fat out of XSUBs</a> for a similar tradeoff of
871 a complete separation of ``Perl glue'' and ``workhorse'' parts of an XSUB.</p>
872 <p>While experts may argue about these idioms, a novice to Perl guts may
873 prefer a way which is as little Perl-guts-specific as possible, meaning
874 automatic conversion and automatic call generation, as in
875 <a href="#getting_the_fat_out_of_xsubs">Getting the fat out of XSUBs</a>. This approach has the additional
876 benefit of protecting the XSUB writer from future changes to the Perl API.</p>
877 <p>
878 </p>
880 <p>Sometimes you might want to provide some extra methods or subroutines
881 to assist in making the interface between Perl and your extension simpler
882 or easier to understand. These routines should live in the .pm file.
883 Whether they are automatically loaded when the extension itself is loaded
884 or only loaded when called depends on where in the .pm file the subroutine
885 definition is placed. You can also consult <a href="file://C|\msysgit\mingw\html/lib/AutoLoader.html">the AutoLoader manpage</a> for an alternate
886 way to store and load your extra subroutines.</p>
887 <p>
888 </p>
890 <p>There is absolutely no excuse for not documenting your extension.
891 Documentation belongs in the .pm file. This file will be fed to pod2man,
892 and the embedded documentation will be converted to the manpage format,
893 then placed in the blib directory. It will be copied to Perl's
894 manpage directory when the extension is installed.</p>
895 <p>You may intersperse documentation and Perl code within the .pm file.
896 In fact, if you want to use method autoloading, you must do this,
897 as the comment inside the .pm file explains.</p>
898 <p>See <a href="file://C|\msysgit\mingw\html/pod/perlpod.html">the perlpod manpage</a> for more information about the pod format.</p>
899 <p>
900 </p>
902 <p>Once your extension is complete and passes all its tests, installing it
903 is quite simple: you simply run ``make install''. You will either need
904 to have write permission into the directories where Perl is installed,
905 or ask your system administrator to run the make for you.</p>
906 <p>Alternately, you can specify the exact directory to place the extension's
907 files by placing a ``PREFIX=/destination/directory'' after the make install.
908 (or in between the make and install if you have a brain-dead version of make).
909 This can be very useful if you are building an extension that will eventually
910 be distributed to multiple systems. You can then just archive the files in
911 the destination directory and distribute them to your destination systems.</p>
912 <p>
913 </p>
915 <p>In this example, we'll do some more work with the argument stack. The
916 previous examples have all returned only a single value. We'll now
917 create an extension that returns an array.</p>
918 <p>This extension is very Unix-oriented (struct statfs and the statfs system
919 call). If you are not running on a Unix system, you can substitute for
920 statfs any other function that returns multiple values, you can hard-code
921 values to be returned to the caller (although this will be a bit harder
922 to test the error case), or you can simply not do this example. If you
923 change the XSUB, be sure to fix the test cases to match the changes.</p>
924 <p>Return to the Mytest directory and add the following code to the end of
925 Mytest.xs:</p>
926 <pre>
927 void
928 statfs(path)
929 char * path
930 INIT:
931 int i;
932 struct statfs buf;</pre>
933 <pre>
934 PPCODE:
935 i = statfs(path, &buf);
936 if (i == 0) {
937 XPUSHs(sv_2mortal(newSVnv(buf.f_bavail)));
938 XPUSHs(sv_2mortal(newSVnv(buf.f_bfree)));
939 XPUSHs(sv_2mortal(newSVnv(buf.f_blocks)));
940 XPUSHs(sv_2mortal(newSVnv(buf.f_bsize)));
941 XPUSHs(sv_2mortal(newSVnv(buf.f_ffree)));
942 XPUSHs(sv_2mortal(newSVnv(buf.f_files)));
943 XPUSHs(sv_2mortal(newSVnv(buf.f_type)));
944 XPUSHs(sv_2mortal(newSVnv(buf.f_fsid[0])));
945 XPUSHs(sv_2mortal(newSVnv(buf.f_fsid[1])));
946 } else {
947 XPUSHs(sv_2mortal(newSVnv(errno)));
948 }</pre>
949 <p>You'll also need to add the following code to the top of the .xs file, just
950 after the include of ``XSUB.h'':</p>
951 <pre>
955 <pre>
957 print ((scalar(@a) == 1 && $a[0] == 2) ? "ok 10\n" : "not ok 10\n");
960 <p>
961 </p>
964 <ul>
965 <li>
966 <p>The INIT: directive contains code that will be placed immediately after
967 the argument stack is decoded. C does not allow variable declarations at
968 arbitrary locations inside a function,
969 so this is usually the best way to declare local variables needed by the XSUB.
971 put these declarations on top.)</p>
972 </li>
973 <li>
974 <p>This routine also returns a different number of arguments depending on the
975 success or failure of the call to statfs. If there is an error, the error
976 number is returned as a single-element array. If the call is successful,
977 then a 9-element array is returned. Since only one argument is passed into
978 this function, we need room on the stack to hold the 9 values which may be
979 returned.</p>
980 <p>We do this by using the PPCODE: directive, rather than the CODE: directive.
982 put on the argument stack by ourselves.</p>
983 </li>
984 <li>
985 <p>When we want to place values to be returned to the caller onto the stack,
986 we use the series of macros that begin with ``XPUSH''. There are five
987 different versions, for placing integers, unsigned integers, doubles,
988 strings, and Perl scalars on the stack. In our example, we placed a
989 Perl scalar onto the stack. (In fact this is the only macro which
990 can be used to return multiple values.)</p>
991 <p>The XPUSH* macros will automatically extend the return stack to prevent
992 it from being overrun. You push values onto the stack in the order you
993 want them seen by the calling program.</p>
994 </li>
995 <li>
996 <p>The values pushed onto the return stack of the XSUB are actually mortal SV's.
997 They are made mortal so that once the values are copied by the calling
998 program, the SV's that held the returned values can be deallocated.
999 If they were not mortal, then they would continue to exist after the XSUB
1000 routine returned, but would not be accessible. This is a memory leak.</p>
1001 </li>
1002 <li>
1003 <p>If we were interested in performance, not in code compactness, in the success
1005 pre-extend the stack before pushing the return values:</p>
1006 <pre>
1008 <p>The tradeoff is that one needs to calculate the number of return values
1009 in advance (though overextending the stack will not typically hurt
1010 anything but memory consumption).</p>
1012 the stack: the Perl function reference comes to an XSUB on the stack, thus
1014 </li>
1015 </ul>
1016 <p>
1017 </p>
1019 <p>In this example, we will accept a reference to an array as an input
1020 parameter, and return a reference to an array of hashes. This will
1021 demonstrate manipulation of complex Perl data types from an XSUB.</p>
1022 <p>This extension is somewhat contrived. It is based on the code in
1023 the previous example. It calls the statfs function multiple times,
1024 accepting a reference to an array of filenames as input, and returning
1025 a reference to an array of hashes containing the data for each of the
1026 filesystems.</p>
1027 <p>Return to the Mytest directory and add the following code to the end of
1028 Mytest.xs:</p>
1029 <pre>
1030 SV *
1031 multi_statfs(paths)
1032 SV * paths
1033 INIT:
1034 AV * results;
1035 I32 numpaths = 0;
1036 int i, n;
1037 struct statfs buf;</pre>
1038 <pre>
1039 if ((!SvROK(paths))
1040 || (SvTYPE(SvRV(paths)) != SVt_PVAV)
1042 {
1043 XSRETURN_UNDEF;
1044 }
1045 results = (AV *)sv_2mortal((SV *)newAV());
1046 CODE:
1048 HV * rh;
1049 STRLEN l;
1051 <pre>
1052 i = statfs(fn, &buf);
1053 if (i != 0) {
1054 av_push(results, newSVnv(errno));
1055 continue;
1056 }</pre>
1057 <pre>
1058 rh = (HV *)sv_2mortal((SV *)newHV());</pre>
1059 <pre>
1067 <pre>
1068 av_push(results, newRV((SV *)rh));
1069 }
1070 RETVAL = newRV((SV *)results);
1071 OUTPUT:
1072 RETVAL</pre>
1075 <pre>
1076 $results = Mytest::multi_statfs([ '/', '/blech' ]);
1079 <p>
1080 </p>
1083 <ul>
1084 <li>
1085 <p>This function does not use a typemap. Instead, we declare it as accepting
1086 one SV* (scalar) parameter, and returning an SV* value, and we take care of
1087 populating these scalars within the code. Because we are only returning
1090 </li>
1091 <li>
1092 <p>When dealing with references, it is important to handle them with caution.
1098 function (which returns -1 if the array is empty). The XSRETURN_UNDEF macro
1099 is used to abort the XSUB and return the undefined value whenever all three of
1100 these conditions are not met.</p>
1101 </li>
1102 <li>
1103 <p>We manipulate several arrays in this XSUB. Note that an array is represented
1104 internally by an AV* pointer. The functions and macros for manipulating
1108 end of the array, automatically extending the array as necessary.</p>
1109 <p>Specifically, we read pathnames one at a time from the input array, and
1110 store the results in an output array (results) in the same order. If
1111 statfs fails, the element pushed onto the return array is the value of
1112 errno after the failure. If statfs succeeds, though, the value pushed
1113 onto the return array is a reference to a hash containing some of the
1114 information in the statfs structure.</p>
1115 <p>As with the return stack, it would be possible (and a small performance win)
1116 to pre-extend the return array before pushing data into it, since we know
1117 how many elements we will return:</p>
1118 <pre>
1119 av_extend(results, numpaths);</pre>
1120 </li>
1121 <li>
1122 <p>We are performing only one hash operation in this function, which is storing
1124 pointer. Like arrays, the functions for manipulating hashes from an XSUB
1125 mirror the functionality available from Perl. See <a href="file://C|\msysgit\mingw\html/pod/perlguts.html">the perlguts manpage</a> and <a href="file://C|\msysgit\mingw\html/pod/perlapi.html">the perlapi manpage</a>
1126 for details.</p>
1127 </li>
1128 <li>
1130 cast an AV* or an HV* to type SV* in this case (and many others). This
1131 allows you to take references to arrays, hashes and scalars with the same
1133 need to be cast to the appropriate type if it is something other than a
1135 </li>
1136 <li>
1137 <p>At this point, xsubpp is doing very little work - the differences between
1138 Mytest.xs and Mytest.c are minimal.</p>
1139 </li>
1140 </ul>
1141 <p>
1142 </p>
1145 <p>
1146 </p>
1149 <p>
1150 </p>
1151 <h2><a name="example_9_passing_open_files_to_xses">EXAMPLE 9 Passing open files to XSes</a></h2>
1152 <p>You would think passing files to an XS is difficult, with all the
1153 typeglobs and stuff. Well, it isn't.</p>
1154 <p>Suppose that for some strange reason we need a wrapper around the
1156 <pre>
1157 #define PERLIO_NOT_STDIO 0
1161 <pre>
1163 <pre>
1164 int
1165 fputs(s, stream)
1166 char * s
1167 FILE * stream</pre>
1171 <p>The standard typemap offers three variants of PerlIO *:
1172 <code>InputStream</code> (T_IN), <code>InOutStream</code> (T_INOUT) and <code>OutputStream</code>
1174 in your code (see below for why it might) #define or typedef
1175 one of the specific names and use that as the argument or result
1176 type in your XS file.</p>
1178 but it has the three stream variants. Using a PerlIO * directly
1179 is not backwards compatible unless you provide your own typemap.</p>
1182 a difference on a socket. Like in our example...</p>
1184 (i.e. a reference to a new glob) and associated with the PerlIO *
1185 provided. If the read/write state of the PerlIO * is not correct then you
1186 may get errors or warnings from when the file handle is used.
1187 So if you opened the PerlIO * as ``w'' it should really be an
1189 <p>Now, suppose you want to use perlio layers in your XS. We'll use the
1191 <p>In the C part of the XS file (above the first MODULE line) you
1192 have</p>
1193 <pre>
1194 #define OutputStream PerlIO *
1195 or
1196 typedef PerlIO * OutputStream;</pre>
1198 <pre>
1199 int
1200 perlioputs(s, stream)
1201 char * s
1202 OutputStream stream
1203 CODE:
1204 RETVAL = PerlIO_puts(stream, s);
1205 OUTPUT:
1206 RETVAL</pre>
1207 <p>We have to use a <code>CODE</code> section because <code>PerlIO_puts()</code> has the arguments
1210 on a PerlIO *. This means we have to ask the perlio system for a stdio
1212 <pre>
1213 int
1214 perliofputs(s, stream)
1215 char * s
1216 OutputStream stream
1217 PREINIT:
1218 FILE *fp = PerlIO_findFILE(stream);
1219 CODE:
1220 if (fp != (FILE*) 0) {
1221 RETVAL = fputs(s, fp);
1222 } else {
1223 RETVAL = -1;
1224 }
1225 OUTPUT:
1226 RETVAL</pre>
1231 new stdio layer. So don't call it repeatedly on the same
1236 <p>
1237 </p>
1239 <p>As mentioned at the top of this document, if you are having problems with
1240 these example extensions, you might see if any of these help you.</p>
1241 <ul>
1242 <li>
1244 1 will not function properly. You need to change the ``use lib'' line to
1245 read:</p>
1246 <pre>
1247 use lib './blib';</pre>
1248 </li>
1249 <li>
1251 automatically created by h2xs. This means that you cannot say ``make test''
1252 to run the test script. You will need to add the following line before the
1253 ``use extension'' statement:</p>
1254 <pre>
1255 use lib './blib';</pre>
1256 </li>
1257 <li>
1259 to use the following line:</p>
1260 <pre>
1262 </li>
1263 <li>
1266 </li>
1267 </ul>
1268 <p>
1269 </p>
1270 <hr />
1272 <p>For more information, consult <a href="file://C|\msysgit\mingw\html/pod/perlguts.html">the perlguts manpage</a>, <a href="file://C|\msysgit\mingw\html/pod/perlapi.html">the perlapi manpage</a>, <a href="file://C|\msysgit\mingw\html/pod/perlxs.html">the perlxs manpage</a>, <a href="file://C|\msysgit\mingw\html/pod/perlmod.html">the perlmod manpage</a>,
1274 <p>
1275 </p>
1276 <hr />
1278 <p>Jeff Okamoto <<em><a href="mailto:okamoto@corp.hp.com">okamoto@corp.hp.com</a></em>></p>
1279 <p>Reviewed and assisted by Dean Roehrich, Ilya Zakharevich, Andreas Koenig,
1280 and Tim Bunce.</p>
1281 <p>PerlIO material contributed by Lupe Christoph, with some clarification
1282 by Nick Ing-Simmons.</p>
1283 <p>
1284 </p>
1289 <big><strong><span class="block"> perlXStut - Tutorial for writing XSUBs</span></strong></big>
1290 </td></tr>
1291 </table>
1293 </body>
1295 </html>