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