Commit | Line | Data |
a0d0e21e |
1 | =head1 NAME |
2 | |
8e07c86e |
3 | perlxs - XS language reference manual |
a0d0e21e |
4 | |
5 | =head1 DESCRIPTION |
6 | |
7 | =head2 Introduction |
8 | |
9 | XS is a language used to create an extension interface |
10 | between Perl and some C library which one wishes to use with |
11 | Perl. The XS interface is combined with the library to |
12 | create a new library which can be linked to Perl. An B<XSUB> |
13 | is a function in the XS language and is the core component |
14 | of the Perl application interface. |
15 | |
16 | The XS compiler is called B<xsubpp>. This compiler will embed |
17 | the constructs necessary to let an XSUB, which is really a C |
18 | function in disguise, manipulate Perl values and creates the |
19 | glue necessary to let Perl access the XSUB. The compiler |
20 | uses B<typemaps> to determine how to map C function parameters |
21 | and variables to Perl values. The default typemap handles |
22 | many common C types. A supplement typemap must be created |
23 | to handle special structures and types for the library being |
24 | linked. |
25 | |
8e07c86e |
26 | =head2 Getting Started |
27 | |
28 | A new extension should begin with the B<h2xs> tool. This will generate |
29 | templates for the new Perl module (PM), the XS source file (XS), the MANIFEST |
30 | file, and the Makefile.PL (PL) files. The Makefile.PL file is a Perl script |
31 | which will generate a Makefile. This makefile knows how to find and run |
32 | xsubpp for your extension. When you type "make" your XS file will be run |
33 | through xsubpp and a C file will be produced. Then the C file will be |
34 | compiled. A simple example looks like this for an example module named |
35 | B<Foo>: |
36 | |
37 | $ h2xs -Afn Foo |
38 | $ cd ext/Foo |
39 | $ ls |
40 | Foo.pm Foo.xs MANIFEST Makefile.PL |
41 | $ perl5 Makefile.PL |
42 | $ ls |
43 | Foo.pm Foo.xs MANIFEST Makefile.PL Makefile |
44 | $ <edit Foo.pm and Foo.xs to add your stuff> |
45 | $ make |
46 | <you will see xsubpp run on Foo.xs and you'll see the C compiler |
47 | <run on Foo.c, and a bunch of other less-interesting things |
48 | <will happen. |
49 | |
50 | If your Perl was built with dynamic loading then the makefile will build a |
51 | dynamically loadable extension. If you don't have dynamic loading then the |
52 | makefile will build a static extension and should create a new Perl binary. |
53 | The default behavior depends on what is available. |
54 | |
55 | For more information about h2xs consult its manpage, embedded in the |
56 | source. For information about the Makefile.PL and Makefile consult the |
57 | MakeMaker manpage. |
58 | |
59 | =head2 On The Road |
60 | |
a0d0e21e |
61 | Many of the examples which follow will concentrate on creating an |
8e07c86e |
62 | interface between Perl and the ONC+ RPC bind library functions. |
a0d0e21e |
63 | Specifically, the rpcb_gettime() function will be used to demonstrate many |
64 | features of the XS language. This function has two parameters; the first |
65 | is an input parameter and the second is an output parameter. The function |
66 | also returns a status value. |
67 | |
68 | bool_t rpcb_gettime(const char *host, time_t *timep); |
69 | |
70 | From C this function will be called with the following |
71 | statements. |
72 | |
73 | #include <rpc/rpc.h> |
74 | bool_t status; |
75 | time_t timep; |
76 | status = rpcb_gettime( "localhost", &timep ); |
77 | |
78 | If an XSUB is created to offer a direct translation between this function |
79 | and Perl, then this XSUB will be used from Perl with the following code. |
80 | The $status and $timep variables will contain the output of the function. |
81 | |
82 | use RPC; |
83 | $status = rpcb_gettime( "localhost", $timep ); |
84 | |
85 | The following XS file shows an XS subroutine, or XSUB, which |
86 | demonstrates one possible interface to the rpcb_gettime() |
87 | function. This XSUB represents a direct translation between |
88 | C and Perl and so preserves the interface even from Perl. |
89 | This XSUB will be invoked from Perl with the usage shown |
90 | above. Note that the first three #include statements, for |
91 | C<EXTERN.h>, C<perl.h>, and C<XSUB.h>, will always be present at the |
92 | beginning of an XS file. This approach and others will be |
93 | expanded later in this document. |
94 | |
95 | #include "EXTERN.h" |
96 | #include "perl.h" |
97 | #include "XSUB.h" |
98 | #include <rpc/rpc.h> |
99 | |
100 | MODULE = RPC PACKAGE = RPC |
101 | |
102 | bool_t |
103 | rpcb_gettime(host,timep) |
8e07c86e |
104 | char *host |
105 | time_t &timep |
a0d0e21e |
106 | OUTPUT: |
107 | timep |
108 | |
109 | Any extension to Perl, including those containing XSUBs, |
110 | should have a Perl module to serve as the bootstrap which |
111 | pulls the extension into Perl. This module will export the |
112 | extension's functions and variables to the Perl program and |
113 | will cause the extension's XSUBs to be linked into Perl. |
114 | The following module will be used for most of the examples |
115 | in this document and should be used from Perl with the C<use> |
116 | command as shown earlier. Perl modules are explained in |
117 | more detail later in this document. |
118 | |
119 | package RPC; |
120 | |
121 | require Exporter; |
122 | require DynaLoader; |
123 | @ISA = qw(Exporter DynaLoader); |
124 | @EXPORT = qw( rpcb_gettime ); |
125 | |
126 | bootstrap RPC; |
127 | 1; |
128 | |
129 | Throughout this document a variety of interfaces to the rpcb_gettime() |
130 | XSUB will be explored. The XSUBs will take their parameters in different |
131 | orders or will take different numbers of parameters. In each case the |
132 | XSUB is an abstraction between Perl and the real C rpcb_gettime() |
133 | function, and the XSUB must always ensure that the real rpcb_gettime() |
134 | function is called with the correct parameters. This abstraction will |
135 | allow the programmer to create a more Perl-like interface to the C |
136 | function. |
137 | |
138 | =head2 The Anatomy of an XSUB |
139 | |
8e07c86e |
140 | The following XSUB allows a Perl program to access a C library function |
141 | called sin(). The XSUB will imitate the C function which takes a single |
142 | argument and returns a single value. |
a0d0e21e |
143 | |
144 | double |
145 | sin(x) |
8e07c86e |
146 | double x |
a0d0e21e |
147 | |
8e07c86e |
148 | When using C pointers the indirection operator C<*> should be considered |
149 | part of the type and the address operator C<&> should be considered part of |
150 | the variable, as is demonstrated in the rpcb_gettime() function above. See |
151 | the section on typemaps for more about handling qualifiers and unary |
152 | operators in C types. |
a0d0e21e |
153 | |
a0d0e21e |
154 | The function name and the return type must be placed on |
155 | separate lines. |
156 | |
157 | INCORRECT CORRECT |
158 | |
159 | double sin(x) double |
8e07c86e |
160 | double x sin(x) |
161 | double x |
a0d0e21e |
162 | |
163 | =head2 The Argument Stack |
164 | |
165 | The argument stack is used to store the values which are |
166 | sent as parameters to the XSUB and to store the XSUB's |
167 | return value. In reality all Perl functions keep their |
168 | values on this stack at the same time, each limited to its |
169 | own range of positions on the stack. In this document the |
170 | first position on that stack which belongs to the active |
171 | function will be referred to as position 0 for that function. |
172 | |
8e07c86e |
173 | XSUBs refer to their stack arguments with the macro B<ST(x)>, where I<x> |
174 | refers to a position in this XSUB's part of the stack. Position 0 for that |
a0d0e21e |
175 | function would be known to the XSUB as ST(0). The XSUB's incoming |
176 | parameters and outgoing return values always begin at ST(0). For many |
177 | simple cases the B<xsubpp> compiler will generate the code necessary to |
178 | handle the argument stack by embedding code fragments found in the |
179 | typemaps. In more complex cases the programmer must supply the code. |
180 | |
181 | =head2 The RETVAL Variable |
182 | |
183 | The RETVAL variable is a magic variable which always matches |
184 | the return type of the C library function. The B<xsubpp> compiler will |
185 | supply this variable in each XSUB and by default will use it to hold the |
186 | return value of the C library function being called. In simple cases the |
187 | value of RETVAL will be placed in ST(0) of the argument stack where it can |
188 | be received by Perl as the return value of the XSUB. |
189 | |
190 | If the XSUB has a return type of C<void> then the compiler will |
191 | not supply a RETVAL variable for that function. When using |
192 | the PPCODE: directive the RETVAL variable may not be needed. |
193 | |
194 | =head2 The MODULE Keyword |
195 | |
196 | The MODULE keyword is used to start the XS code and to |
197 | specify the package of the functions which are being |
198 | defined. All text preceding the first MODULE keyword is |
199 | considered C code and is passed through to the output |
200 | untouched. Every XS module will have a bootstrap function |
201 | which is used to hook the XSUBs into Perl. The package name |
202 | of this bootstrap function will match the value of the last |
203 | MODULE statement in the XS source files. The value of |
204 | MODULE should always remain constant within the same XS |
205 | file, though this is not required. |
206 | |
207 | The following example will start the XS code and will place |
208 | all functions in a package named RPC. |
209 | |
210 | MODULE = RPC |
211 | |
212 | =head2 The PACKAGE Keyword |
213 | |
214 | When functions within an XS source file must be separated into packages |
215 | the PACKAGE keyword should be used. This keyword is used with the MODULE |
216 | keyword and must follow immediately after it when used. |
217 | |
218 | MODULE = RPC PACKAGE = RPC |
219 | |
220 | [ XS code in package RPC ] |
221 | |
222 | MODULE = RPC PACKAGE = RPCB |
223 | |
224 | [ XS code in package RPCB ] |
225 | |
226 | MODULE = RPC PACKAGE = RPC |
227 | |
228 | [ XS code in package RPC ] |
229 | |
230 | Although this keyword is optional and in some cases provides redundant |
231 | information it should always be used. This keyword will ensure that the |
232 | XSUBs appear in the desired package. |
233 | |
234 | =head2 The PREFIX Keyword |
235 | |
236 | The PREFIX keyword designates prefixes which should be |
237 | removed from the Perl function names. If the C function is |
238 | C<rpcb_gettime()> and the PREFIX value is C<rpcb_> then Perl will |
239 | see this function as C<gettime()>. |
240 | |
241 | This keyword should follow the PACKAGE keyword when used. |
242 | If PACKAGE is not used then PREFIX should follow the MODULE |
243 | keyword. |
244 | |
245 | MODULE = RPC PREFIX = rpc_ |
246 | |
247 | MODULE = RPC PACKAGE = RPCB PREFIX = rpcb_ |
248 | |
249 | =head2 The OUTPUT: Keyword |
250 | |
251 | The OUTPUT: keyword indicates that certain function parameters should be |
252 | updated (new values made visible to Perl) when the XSUB terminates or that |
253 | certain values should be returned to the calling Perl function. For |
254 | simple functions, such as the sin() function above, the RETVAL variable is |
255 | automatically designated as an output value. In more complex functions |
256 | the B<xsubpp> compiler will need help to determine which variables are output |
257 | variables. |
258 | |
259 | This keyword will normally be used to complement the CODE: keyword. |
260 | The RETVAL variable is not recognized as an output variable when the |
261 | CODE: keyword is present. The OUTPUT: keyword is used in this |
262 | situation to tell the compiler that RETVAL really is an output |
263 | variable. |
264 | |
265 | The OUTPUT: keyword can also be used to indicate that function parameters |
266 | are output variables. This may be necessary when a parameter has been |
267 | modified within the function and the programmer would like the update to |
8e07c86e |
268 | be seen by Perl. |
a0d0e21e |
269 | |
270 | bool_t |
271 | rpcb_gettime(host,timep) |
8e07c86e |
272 | char *host |
273 | time_t &timep |
a0d0e21e |
274 | OUTPUT: |
275 | timep |
276 | |
277 | The OUTPUT: keyword will also allow an output parameter to |
278 | be mapped to a matching piece of code rather than to a |
279 | typemap. |
280 | |
281 | bool_t |
282 | rpcb_gettime(host,timep) |
8e07c86e |
283 | char *host |
284 | time_t &timep |
a0d0e21e |
285 | OUTPUT: |
8e07c86e |
286 | timep sv_setnv(ST(1), (double)timep); |
a0d0e21e |
287 | |
288 | =head2 The CODE: Keyword |
289 | |
290 | This keyword is used in more complicated XSUBs which require |
291 | special handling for the C function. The RETVAL variable is |
292 | available but will not be returned unless it is specified |
293 | under the OUTPUT: keyword. |
294 | |
295 | The following XSUB is for a C function which requires special handling of |
296 | its parameters. The Perl usage is given first. |
297 | |
298 | $status = rpcb_gettime( "localhost", $timep ); |
299 | |
300 | The XSUB follows. |
301 | |
d1b91892 |
302 | bool_t |
303 | rpcb_gettime(host,timep) |
8e07c86e |
304 | char *host |
305 | time_t timep |
a0d0e21e |
306 | CODE: |
307 | RETVAL = rpcb_gettime( host, &timep ); |
308 | OUTPUT: |
309 | timep |
310 | RETVAL |
311 | |
312 | In many of the examples shown here the CODE: block (and |
313 | other blocks) will often be contained within braces ( C<{> and |
314 | C<}> ). This protects the CODE: block from complex INPUT |
315 | typemaps and ensures the resulting C code is legal. |
316 | |
317 | =head2 The NO_INIT Keyword |
318 | |
319 | The NO_INIT keyword is used to indicate that a function |
d1b91892 |
320 | parameter is being used as only an output value. The B<xsubpp> |
a0d0e21e |
321 | compiler will normally generate code to read the values of |
322 | all function parameters from the argument stack and assign |
323 | them to C variables upon entry to the function. NO_INIT |
324 | will tell the compiler that some parameters will be used for |
325 | output rather than for input and that they will be handled |
326 | before the function terminates. |
327 | |
328 | The following example shows a variation of the rpcb_gettime() function. |
d1b91892 |
329 | This function uses the timep variable as only an output variable and does |
a0d0e21e |
330 | not care about its initial contents. |
331 | |
332 | bool_t |
333 | rpcb_gettime(host,timep) |
8e07c86e |
334 | char *host |
335 | time_t &timep = NO_INIT |
a0d0e21e |
336 | OUTPUT: |
337 | timep |
338 | |
339 | =head2 Initializing Function Parameters |
340 | |
341 | Function parameters are normally initialized with their |
342 | values from the argument stack. The typemaps contain the |
343 | code segments which are used to transfer the Perl values to |
344 | the C parameters. The programmer, however, is allowed to |
345 | override the typemaps and supply alternate initialization |
346 | code. |
347 | |
348 | The following code demonstrates how to supply initialization code for |
349 | function parameters. The initialization code is eval'd by the compiler |
350 | before it is added to the output so anything which should be interpreted |
351 | literally, such as double quotes, must be protected with backslashes. |
352 | |
353 | bool_t |
354 | rpcb_gettime(host,timep) |
8e07c86e |
355 | char *host = (char *)SvPV(ST(0),na); |
356 | time_t &timep = 0; |
a0d0e21e |
357 | OUTPUT: |
358 | timep |
359 | |
360 | This should not be used to supply default values for parameters. One |
361 | would normally use this when a function parameter must be processed by |
362 | another library function before it can be used. Default parameters are |
363 | covered in the next section. |
364 | |
365 | =head2 Default Parameter Values |
366 | |
367 | Default values can be specified for function parameters by |
368 | placing an assignment statement in the parameter list. The |
369 | default value may be a number or a string. Defaults should |
370 | always be used on the right-most parameters only. |
371 | |
372 | To allow the XSUB for rpcb_gettime() to have a default host |
373 | value the parameters to the XSUB could be rearranged. The |
374 | XSUB will then call the real rpcb_gettime() function with |
375 | the parameters in the correct order. Perl will call this |
376 | XSUB with either of the following statements. |
377 | |
378 | $status = rpcb_gettime( $timep, $host ); |
379 | |
380 | $status = rpcb_gettime( $timep ); |
381 | |
382 | The XSUB will look like the code which follows. A CODE: |
383 | block is used to call the real rpcb_gettime() function with |
384 | the parameters in the correct order for that function. |
385 | |
386 | bool_t |
387 | rpcb_gettime(timep,host="localhost") |
8e07c86e |
388 | char *host |
389 | time_t timep = NO_INIT |
a0d0e21e |
390 | CODE: |
391 | RETVAL = rpcb_gettime( host, &timep ); |
392 | OUTPUT: |
393 | timep |
394 | RETVAL |
395 | |
396 | =head2 Variable-length Parameter Lists |
397 | |
398 | XSUBs can have variable-length parameter lists by specifying an ellipsis |
399 | C<(...)> in the parameter list. This use of the ellipsis is similar to that |
400 | found in ANSI C. The programmer is able to determine the number of |
401 | arguments passed to the XSUB by examining the C<items> variable which the |
402 | B<xsubpp> compiler supplies for all XSUBs. By using this mechanism one can |
403 | create an XSUB which accepts a list of parameters of unknown length. |
404 | |
405 | The I<host> parameter for the rpcb_gettime() XSUB can be |
406 | optional so the ellipsis can be used to indicate that the |
407 | XSUB will take a variable number of parameters. Perl should |
d1b91892 |
408 | be able to call this XSUB with either of the following statements. |
a0d0e21e |
409 | |
410 | $status = rpcb_gettime( $timep, $host ); |
411 | |
412 | $status = rpcb_gettime( $timep ); |
413 | |
414 | The XS code, with ellipsis, follows. |
415 | |
416 | bool_t |
417 | rpcb_gettime(timep, ...) |
8e07c86e |
418 | time_t timep = NO_INIT |
a0d0e21e |
419 | CODE: |
420 | { |
421 | char *host = "localhost"; |
422 | |
423 | if( items > 1 ) |
424 | host = (char *)SvPV(ST(1), na); |
425 | RETVAL = rpcb_gettime( host, &timep ); |
426 | } |
427 | OUTPUT: |
428 | timep |
429 | RETVAL |
430 | |
431 | =head2 The PPCODE: Keyword |
432 | |
433 | The PPCODE: keyword is an alternate form of the CODE: keyword and is used |
434 | to tell the B<xsubpp> compiler that the programmer is supplying the code to |
d1b91892 |
435 | control the argument stack for the XSUBs return values. Occasionally one |
a0d0e21e |
436 | will want an XSUB to return a list of values rather than a single value. |
437 | In these cases one must use PPCODE: and then explicitly push the list of |
438 | values on the stack. The PPCODE: and CODE: keywords are not used |
439 | together within the same XSUB. |
440 | |
441 | The following XSUB will call the C rpcb_gettime() function |
442 | and will return its two output values, timep and status, to |
443 | Perl as a single list. |
444 | |
d1b91892 |
445 | void |
446 | rpcb_gettime(host) |
8e07c86e |
447 | char *host |
a0d0e21e |
448 | PPCODE: |
449 | { |
450 | time_t timep; |
451 | bool_t status; |
452 | status = rpcb_gettime( host, &timep ); |
453 | EXTEND(sp, 2); |
454 | PUSHs(sv_2mortal(newSVnv(status))); |
455 | PUSHs(sv_2mortal(newSVnv(timep))); |
456 | } |
457 | |
458 | Notice that the programmer must supply the C code necessary |
459 | to have the real rpcb_gettime() function called and to have |
460 | the return values properly placed on the argument stack. |
461 | |
462 | The C<void> return type for this function tells the B<xsubpp> compiler that |
463 | the RETVAL variable is not needed or used and that it should not be created. |
464 | In most scenarios the void return type should be used with the PPCODE: |
465 | directive. |
466 | |
467 | The EXTEND() macro is used to make room on the argument |
468 | stack for 2 return values. The PPCODE: directive causes the |
469 | B<xsubpp> compiler to create a stack pointer called C<sp>, and it |
470 | is this pointer which is being used in the EXTEND() macro. |
471 | The values are then pushed onto the stack with the PUSHs() |
472 | macro. |
473 | |
474 | Now the rpcb_gettime() function can be used from Perl with |
475 | the following statement. |
476 | |
477 | ($status, $timep) = rpcb_gettime("localhost"); |
478 | |
479 | =head2 Returning Undef And Empty Lists |
480 | |
d1b91892 |
481 | Occasionally the programmer will want to simply return |
a0d0e21e |
482 | C<undef> or an empty list if a function fails rather than a |
483 | separate status value. The rpcb_gettime() function offers |
484 | just this situation. If the function succeeds we would like |
485 | to have it return the time and if it fails we would like to |
486 | have undef returned. In the following Perl code the value |
487 | of $timep will either be undef or it will be a valid time. |
488 | |
489 | $timep = rpcb_gettime( "localhost" ); |
490 | |
491 | The following XSUB uses the C<void> return type to disable the generation of |
492 | the RETVAL variable and uses a CODE: block to indicate to the compiler |
493 | that the programmer has supplied all the necessary code. The |
494 | sv_newmortal() call will initialize the return value to undef, making that |
495 | the default return value. |
496 | |
497 | void |
498 | rpcb_gettime(host) |
499 | char * host |
500 | CODE: |
501 | { |
502 | time_t timep; |
503 | bool_t x; |
504 | ST(0) = sv_newmortal(); |
505 | if( rpcb_gettime( host, &timep ) ) |
506 | sv_setnv( ST(0), (double)timep); |
507 | } |
508 | |
509 | The next example demonstrates how one would place an explicit undef in the |
510 | return value, should the need arise. |
511 | |
512 | void |
513 | rpcb_gettime(host) |
514 | char * host |
515 | CODE: |
516 | { |
517 | time_t timep; |
518 | bool_t x; |
519 | ST(0) = sv_newmortal(); |
520 | if( rpcb_gettime( host, &timep ) ){ |
521 | sv_setnv( ST(0), (double)timep); |
522 | } |
523 | else{ |
524 | ST(0) = &sv_undef; |
525 | } |
526 | } |
527 | |
528 | To return an empty list one must use a PPCODE: block and |
529 | then not push return values on the stack. |
530 | |
531 | void |
532 | rpcb_gettime(host) |
8e07c86e |
533 | char *host |
a0d0e21e |
534 | PPCODE: |
535 | { |
536 | time_t timep; |
537 | if( rpcb_gettime( host, &timep ) ) |
538 | PUSHs(sv_2mortal(newSVnv(timep))); |
539 | else{ |
540 | /* Nothing pushed on stack, so an empty */ |
541 | /* list is implicitly returned. */ |
542 | } |
543 | } |
544 | |
4633a7c4 |
545 | =head2 The REQUIRE: Keyword |
546 | |
547 | The REQUIRE: keyword is used to indicate the minimum version of the |
548 | B<xsubpp> compiler needed to compile the XS module. An XS module which |
549 | contains the following statement will only compile with B<xsubpp> version |
550 | 1.922 or greater: |
551 | |
552 | REQUIRE: 1.922 |
553 | |
a0d0e21e |
554 | =head2 The CLEANUP: Keyword |
555 | |
556 | This keyword can be used when an XSUB requires special cleanup procedures |
557 | before it terminates. When the CLEANUP: keyword is used it must follow |
558 | any CODE:, PPCODE:, or OUTPUT: blocks which are present in the XSUB. The |
559 | code specified for the cleanup block will be added as the last statements |
560 | in the XSUB. |
561 | |
562 | =head2 The BOOT: Keyword |
563 | |
564 | The BOOT: keyword is used to add code to the extension's bootstrap |
565 | function. The bootstrap function is generated by the B<xsubpp> compiler and |
566 | normally holds the statements necessary to register any XSUBs with Perl. |
567 | With the BOOT: keyword the programmer can tell the compiler to add extra |
568 | statements to the bootstrap function. |
569 | |
570 | This keyword may be used any time after the first MODULE keyword and should |
571 | appear on a line by itself. The first blank line after the keyword will |
572 | terminate the code block. |
573 | |
574 | BOOT: |
575 | # The following message will be printed when the |
576 | # bootstrap function executes. |
577 | printf("Hello from the bootstrap!\n"); |
578 | |
579 | =head2 Inserting Comments and C Preprocessor Directives |
580 | |
581 | Comments and C preprocessor directives are allowed within |
582 | CODE:, PPCODE:, BOOT:, and CLEANUP: blocks. The compiler |
583 | will pass the preprocessor directives through untouched and |
584 | will remove the commented lines. Comments can be added to |
585 | XSUBs by placing a C<#> at the beginning of the line. Care |
586 | should be taken to avoid making the comment look like a C |
587 | preprocessor directive, lest it be interpreted as such. |
588 | |
589 | =head2 Using XS With C++ |
590 | |
591 | If a function is defined as a C++ method then it will assume |
592 | its first argument is an object pointer. The object pointer |
593 | will be stored in a variable called THIS. The object should |
594 | have been created by C++ with the new() function and should |
595 | be blessed by Perl with the sv_setptrobj() macro. The |
596 | blessing of the object by Perl can be handled by the |
597 | T_PTROBJ typemap. |
598 | |
599 | If the method is defined as static it will call the C++ |
600 | function using the class::method() syntax. If the method is not static |
601 | the function will be called using the THIS->method() syntax. |
602 | |
603 | =head2 Perl Variables |
604 | |
605 | The following demonstrates how the Perl variable $host can |
606 | be accessed from an XSUB. The function B<perl_get_sv()> is |
607 | used to obtain a pointer to the variable, known as an B<SV> |
608 | (Scalar Variable) internally. The package name C<RPC> will be |
609 | added to the name of the variable so perl_get_sv() will know |
610 | in which package $host can be found. If the package name is |
611 | not supplied then perl_get_sv() will search package C<main> for |
612 | the variable. The macro B<SvPVX()> is then used to dereference |
613 | the SV to obtain a C<char*> pointer to its contents. |
614 | |
615 | void |
616 | rpcb_gettime() |
617 | PPCODE: |
618 | { |
619 | char *host; |
620 | SV *hostsv; |
621 | time_t timep; |
622 | |
623 | hostsv = perl_get_sv( "RPC::host", FALSE ); |
624 | if( hostsv != NULL ){ |
625 | host = SvPVX( hostsv ); |
626 | if( rpcb_gettime( host, &timep ) ) |
627 | PUSHs(sv_2mortal(newSVnv(timep))); |
628 | } |
629 | } |
630 | |
631 | This Perl code can be used to call that XSUB. |
632 | |
633 | $RPC::host = "localhost"; |
634 | $timep = rpcb_gettime(); |
635 | |
636 | In the above example the SV contained a C C<char*> but a Perl |
637 | scalar variable may also contain numbers and references. If |
638 | the SV is expected to have a C C<int> then the macro B<SvIVX()> |
639 | should be used to dereference the SV. When the SV contains |
640 | a C double then B<SvNVX()> should be used. |
641 | |
642 | The macro B<SvRV()> can be used to dereference an SV when it is a Perl |
643 | reference. The result will be another SV which points to the actual Perl |
644 | variable. This can then be dereferenced with SvPVX(), SvNVX(), or |
645 | SvIVX(). The following XSUB will use SvRV(). |
646 | |
d1b91892 |
647 | void |
648 | rpcb_gettime() |
a0d0e21e |
649 | PPCODE: |
650 | { |
651 | char *host; |
652 | SV *rv; |
653 | SV *hostsv; |
654 | time_t timep; |
655 | |
656 | rv = perl_get_sv( "RPC::host", FALSE ); |
657 | if( rv != NULL ){ |
658 | hostsv = SvRV( rv ); |
659 | host = SvPVX( hostsv ); |
660 | if( rpcb_gettime( host, &timep ) ) |
661 | PUSHs(sv_2mortal(newSVnv(timep))); |
662 | } |
663 | } |
664 | |
665 | This Perl code will create a variable $RPC::host which is a |
666 | reference to $MY::host. The variable $MY::host contains the |
667 | hostname which will be used. |
668 | |
669 | $MY::host = "localhost"; |
670 | $RPC::host = \$MY::host; |
671 | $timep = rpcb_gettime(); |
672 | |
673 | The second argument to perl_get_sv() will normally be B<FALSE> |
674 | as shown in the above examples. An argument of B<TRUE> will |
675 | cause variables to be created if they do not already exist. |
676 | One should not use TRUE unless steps are taken to deal with |
677 | a possibly empty SV. |
678 | |
679 | XSUBs may use B<perl_get_av()>, B<perl_get_hv()>, and B<perl_get_cv()> to |
680 | access Perl arrays, hashes, and code values. |
681 | |
d1b91892 |
682 | =head2 Interface Strategy |
a0d0e21e |
683 | |
684 | When designing an interface between Perl and a C library a straight |
685 | translation from C to XS is often sufficient. The interface will often be |
686 | very C-like and occasionally nonintuitive, especially when the C function |
687 | modifies one of its parameters. In cases where the programmer wishes to |
688 | create a more Perl-like interface the following strategy may help to |
689 | identify the more critical parts of the interface. |
690 | |
691 | Identify the C functions which modify their parameters. The XSUBs for |
692 | these functions may be able to return lists to Perl, or may be |
693 | candidates to return undef or an empty list in case of failure. |
694 | |
d1b91892 |
695 | Identify which values are used by only the C and XSUB functions |
a0d0e21e |
696 | themselves. If Perl does not need to access the contents of the value |
697 | then it may not be necessary to provide a translation for that value |
698 | from C to Perl. |
699 | |
700 | Identify the pointers in the C function parameter lists and return |
701 | values. Some pointers can be handled in XS with the & unary operator on |
702 | the variable name while others will require the use of the * operator on |
703 | the type name. In general it is easier to work with the & operator. |
704 | |
705 | Identify the structures used by the C functions. In many |
706 | cases it may be helpful to use the T_PTROBJ typemap for |
707 | these structures so they can be manipulated by Perl as |
708 | blessed objects. |
709 | |
710 | =head2 The Perl Module |
711 | |
712 | The Perl module is the link between the extension library, |
713 | which was generated from XS code, and the Perl interpreter. |
714 | The module is used to tell Perl what the extension library |
715 | contains. The name and package of the module should match |
716 | the name of the library. |
717 | |
718 | The following is a Perl module for an extension containing |
719 | some ONC+ RPC bind library functions. |
720 | |
721 | package RPC; |
722 | |
723 | require Exporter; |
724 | require DynaLoader; |
725 | @ISA = qw(Exporter DynaLoader); |
726 | @EXPORT = qw( rpcb_gettime rpcb_getmaps rpcb_getaddr |
727 | rpcb_rmtcall rpcb_set rpcb_unset ); |
728 | |
729 | bootstrap RPC; |
730 | 1; |
731 | |
732 | The RPC extension contains the functions found in the |
733 | @EXPORT list. By using the C<Exporter> module the RPC module |
734 | can make these function names visible to the rest of the |
735 | Perl program. The C<DynaLoader> module will allow the RPC |
736 | module to bootstrap the extension library. To load this |
737 | extension and make the functions available, the following |
738 | Perl statement should be used. |
739 | |
740 | use RPC; |
741 | |
742 | For more information about the DynaLoader consult its documentation in the |
743 | ext/DynaLoader directory in the Perl source. |
744 | |
745 | =head2 Perl Objects And C Structures |
746 | |
747 | When dealing with C structures one should select either |
748 | B<T_PTROBJ> or B<T_PTRREF> for the XS type. Both types are |
749 | designed to handle pointers to complex objects. The |
750 | T_PTRREF type will allow the Perl object to be unblessed |
751 | while the T_PTROBJ type requires that the object be blessed. |
752 | By using T_PTROBJ one can achieve a form of type-checking |
d1b91892 |
753 | because the XSUB will attempt to verify that the Perl object |
a0d0e21e |
754 | is of the expected type. |
755 | |
756 | The following XS code shows the getnetconfigent() function which is used |
8e07c86e |
757 | with ONC+ TIRPC. The getnetconfigent() function will return a pointer to a |
a0d0e21e |
758 | C structure and has the C prototype shown below. The example will |
759 | demonstrate how the C pointer will become a Perl reference. Perl will |
760 | consider this reference to be a pointer to a blessed object and will |
761 | attempt to call a destructor for the object. A destructor will be |
762 | provided in the XS source to free the memory used by getnetconfigent(). |
763 | Destructors in XS can be created by specifying an XSUB function whose name |
764 | ends with the word B<DESTROY>. XS destructors can be used to free memory |
765 | which may have been malloc'd by another XSUB. |
766 | |
767 | struct netconfig *getnetconfigent(const char *netid); |
768 | |
769 | A C<typedef> will be created for C<struct netconfig>. The Perl |
770 | object will be blessed in a class matching the name of the C |
771 | type, with the tag C<Ptr> appended, and the name should not |
772 | have embedded spaces if it will be a Perl package name. The |
773 | destructor will be placed in a class corresponding to the |
774 | class of the object and the PREFIX keyword will be used to |
775 | trim the name to the word DESTROY as Perl will expect. |
776 | |
777 | typedef struct netconfig Netconfig; |
778 | |
779 | MODULE = RPC PACKAGE = RPC |
780 | |
781 | Netconfig * |
782 | getnetconfigent(netid) |
8e07c86e |
783 | char *netid |
a0d0e21e |
784 | |
785 | MODULE = RPC PACKAGE = NetconfigPtr PREFIX = rpcb_ |
786 | |
787 | void |
788 | rpcb_DESTROY(netconf) |
8e07c86e |
789 | Netconfig *netconf |
a0d0e21e |
790 | CODE: |
791 | printf("Now in NetconfigPtr::DESTROY\n"); |
792 | free( netconf ); |
793 | |
794 | This example requires the following typemap entry. Consult the typemap |
795 | section for more information about adding new typemaps for an extension. |
796 | |
797 | TYPEMAP |
798 | Netconfig * T_PTROBJ |
799 | |
800 | This example will be used with the following Perl statements. |
801 | |
802 | use RPC; |
803 | $netconf = getnetconfigent("udp"); |
804 | |
805 | When Perl destroys the object referenced by $netconf it will send the |
806 | object to the supplied XSUB DESTROY function. Perl cannot determine, and |
807 | does not care, that this object is a C struct and not a Perl object. In |
808 | this sense, there is no difference between the object created by the |
809 | getnetconfigent() XSUB and an object created by a normal Perl subroutine. |
810 | |
811 | =head2 C Headers and Perl |
812 | |
813 | The B<h2xs> compiler is designed to convert C header files in |
814 | /usr/include into Perl extensions. This compiler will |
815 | create a directory under the C<ext> directory of the Perl |
816 | source and will populate it with a Makefile, a Perl Module, |
817 | an XS source file, and a MANIFEST file. |
818 | |
819 | The following command will create an extension called C<Rusers> |
820 | from the <rpcsvc/rusers.h> header. |
821 | |
822 | h2xs rpcsvc/rusers |
823 | |
824 | When the Rusers extension has been compiled and installed |
825 | Perl can use it to retrieve any C<#define> statements which |
826 | were in the C header. |
827 | |
828 | use Rusers; |
829 | print "RPC program number for rusers service: "; |
830 | print &RUSERSPROG, "\n"; |
831 | |
832 | =head2 Creating A New Extension |
833 | |
834 | The B<h2xs> compiler can generate template source files and |
835 | Makefiles. These templates offer a suitable starting point |
836 | for most extensions. The following example demonstrates how |
837 | one might use B<h2xs> to create an extension containing the RPC |
838 | functions in this document. |
839 | |
840 | The extension will not use autoloaded functions and will not define |
841 | constants, so the B<-A> option will be given to B<h2xs>. When run from the |
842 | Perl source directory, the B<h2xs> compiler will create the directory |
843 | ext/RPC and will populate it with files called RPC.xs, RPC.pm, Makefile.PL, |
844 | and MANIFEST. The XS code for the RPC functions should be added to the |
845 | RPC.xs file. The @EXPORT list in RPC.pm should be updated to include the |
846 | functions from RPC.xs. |
847 | |
848 | h2xs -An RPC |
849 | |
850 | To compile the extension for dynamic loading the following |
851 | command should be executed from the ext/RPC directory. |
852 | |
853 | make dynamic |
854 | |
855 | If the extension will be statically linked into the Perl |
856 | binary then the makefile (use C<makefile>, not C<Makefile>) in the |
857 | Perl source directory should be edited to add C<ext/RPC/RPC.a> |
858 | to the C<static_ext> variable. Before making this change Perl |
859 | should have already been built. After the makefile has been |
860 | updated the following command should be executed from the |
861 | Perl source directory. |
862 | |
863 | make |
864 | |
865 | Perl's B<Configure> script can also be used to add extensions. The extension |
866 | should be placed in the C<ext> directory under the Perl source before Perl |
867 | has been built and prior to running Configure. When Configure is run it |
868 | will find the extension along with the other extensions in the C<ext> |
869 | directory and will add it to the list of extensions to be built. When make |
870 | is run the extension will be built along with the other extensions. |
871 | |
872 | Configure recognizes extensions if they have an XS source |
873 | file which matches the name of the extension directory. If |
874 | the extension directory includes a MANIFEST file Configure |
875 | will search that file for any B<.SH> files and extract them |
876 | after it extracts all the other .SH files listed in the main |
877 | MANIFEST. The main Perl Makefile will then run B<make> in the |
878 | extension's directory if it finds an XS file matching the |
879 | name of the extension's directory. |
880 | |
881 | =head2 The Typemap |
882 | |
883 | The typemap is a collection of code fragments which are used by the B<xsubpp> |
884 | compiler to map C function parameters and values to Perl values. The |
885 | typemap file may consist of three sections labeled C<TYPEMAP>, C<INPUT>, and |
886 | C<OUTPUT>. The INPUT section tells the compiler how to translate Perl values |
887 | into variables of certain C types. The OUTPUT section tells the compiler |
888 | how to translate the values from certain C types into values Perl can |
889 | understand. The TYPEMAP section tells the compiler which of the INPUT and |
890 | OUTPUT code fragments should be used to map a given C type to a Perl value. |
891 | Each of the sections of the typemap must be preceded by one of the TYPEMAP, |
892 | INPUT, or OUTPUT keywords. |
893 | |
894 | The default typemap in the C<ext> directory of the Perl source contains many |
895 | useful types which can be used by Perl extensions. Some extensions define |
896 | additional typemaps which they keep in their own directory. These |
897 | additional typemaps may reference INPUT and OUTPUT maps in the main |
898 | typemap. The B<xsubpp> compiler will allow the extension's own typemap to |
899 | override any mappings which are in the default typemap. |
900 | |
901 | Most extensions which require a custom typemap will need only the TYPEMAP |
902 | section of the typemap file. The custom typemap used in the |
903 | getnetconfigent() example shown earlier demonstrates what may be the typical |
904 | use of extension typemaps. That typemap is used to equate a C structure |
905 | with the T_PTROBJ typemap. The typemap used by getnetconfigent() is shown |
906 | here. Note that the C type is separated from the XS type with a tab and |
907 | that the C unary operator C<*> is considered to be a part of the C type name. |
908 | |
909 | TYPEMAP |
910 | Netconfig *<tab>T_PTROBJ |
911 | |
912 | =head1 EXAMPLES |
913 | |
914 | File C<RPC.xs>: Interface to some ONC+ RPC bind library functions. |
915 | |
916 | #include "EXTERN.h" |
917 | #include "perl.h" |
918 | #include "XSUB.h" |
919 | |
920 | #include <rpc/rpc.h> |
921 | |
922 | typedef struct netconfig Netconfig; |
923 | |
924 | MODULE = RPC PACKAGE = RPC |
925 | |
926 | void |
927 | rpcb_gettime(host="localhost") |
8e07c86e |
928 | char *host |
a0d0e21e |
929 | CODE: |
930 | { |
931 | time_t timep; |
932 | ST(0) = sv_newmortal(); |
933 | if( rpcb_gettime( host, &timep ) ) |
934 | sv_setnv( ST(0), (double)timep ); |
935 | } |
936 | |
937 | Netconfig * |
938 | getnetconfigent(netid="udp") |
8e07c86e |
939 | char *netid |
a0d0e21e |
940 | |
941 | MODULE = RPC PACKAGE = NetconfigPtr PREFIX = rpcb_ |
942 | |
943 | void |
944 | rpcb_DESTROY(netconf) |
8e07c86e |
945 | Netconfig *netconf |
a0d0e21e |
946 | CODE: |
947 | printf("NetconfigPtr::DESTROY\n"); |
948 | free( netconf ); |
949 | |
950 | File C<typemap>: Custom typemap for RPC.xs. |
951 | |
952 | TYPEMAP |
953 | Netconfig * T_PTROBJ |
954 | |
955 | File C<RPC.pm>: Perl module for the RPC extension. |
956 | |
957 | package RPC; |
958 | |
959 | require Exporter; |
960 | require DynaLoader; |
961 | @ISA = qw(Exporter DynaLoader); |
962 | @EXPORT = qw(rpcb_gettime getnetconfigent); |
963 | |
964 | bootstrap RPC; |
965 | 1; |
966 | |
967 | File C<rpctest.pl>: Perl test program for the RPC extension. |
968 | |
969 | use RPC; |
970 | |
971 | $netconf = getnetconfigent(); |
972 | $a = rpcb_gettime(); |
973 | print "time = $a\n"; |
974 | print "netconf = $netconf\n"; |
975 | |
976 | $netconf = getnetconfigent("tcp"); |
977 | $a = rpcb_gettime("poplar"); |
978 | print "time = $a\n"; |
979 | print "netconf = $netconf\n"; |
980 | |
981 | |
982 | =head1 AUTHOR |
983 | |
d1b91892 |
984 | Dean Roehrich F<E<lt>roehrich@cray.comE<gt>> |
8e07c86e |
985 | Oct 12, 1995 |