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