This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
add newer malloc.c from Ilya Zakharevich <ilya@math.ohio-state.edu>
[perl5.git] / pod / perlxs.pod
CommitLineData
a0d0e21e
LW
1=head1 NAME
2
8e07c86e 3perlxs - XS language reference manual
a0d0e21e
LW
4
5=head1 DESCRIPTION
6
7=head2 Introduction
8
9XS is a language used to create an extension interface
10between Perl and some C library which one wishes to use with
11Perl. The XS interface is combined with the library to
12create a new library which can be linked to Perl. An B<XSUB>
13is a function in the XS language and is the core component
14of the Perl application interface.
15
16The XS compiler is called B<xsubpp>. This compiler will embed
17the constructs necessary to let an XSUB, which is really a C
18function in disguise, manipulate Perl values and creates the
19glue necessary to let Perl access the XSUB. The compiler
20uses B<typemaps> to determine how to map C function parameters
21and variables to Perl values. The default typemap handles
22many common C types. A supplement typemap must be created
23to handle special structures and types for the library being
24linked.
25
cb1a09d0 26See L<perlxstut> for a tutorial on the whole extension creation process.
8e07c86e 27
7b8d334a
GS
28Note: For many extensions, Dave Beazley's SWIG system provides a
29significantly more convenient mechanism for creating the XS glue
30code. See L<http://www.cs.utah.edu/~beazley/SWIG> for more
31information.
32
8e07c86e
AD
33=head2 On The Road
34
a5f75d66
AD
35Many of the examples which follow will concentrate on creating an interface
36between Perl and the ONC+ RPC bind library functions. The rpcb_gettime()
37function is used to demonstrate many features of the XS language. This
38function has two parameters; the first is an input parameter and the second
39is an output parameter. The function also returns a status value.
a0d0e21e
LW
40
41 bool_t rpcb_gettime(const char *host, time_t *timep);
42
43From C this function will be called with the following
44statements.
45
46 #include <rpc/rpc.h>
47 bool_t status;
48 time_t timep;
49 status = rpcb_gettime( "localhost", &timep );
50
51If an XSUB is created to offer a direct translation between this function
52and Perl, then this XSUB will be used from Perl with the following code.
53The $status and $timep variables will contain the output of the function.
54
55 use RPC;
56 $status = rpcb_gettime( "localhost", $timep );
57
58The following XS file shows an XS subroutine, or XSUB, which
59demonstrates one possible interface to the rpcb_gettime()
60function. This XSUB represents a direct translation between
61C and Perl and so preserves the interface even from Perl.
62This XSUB will be invoked from Perl with the usage shown
63above. Note that the first three #include statements, for
64C<EXTERN.h>, C<perl.h>, and C<XSUB.h>, will always be present at the
65beginning of an XS file. This approach and others will be
66expanded later in this document.
67
68 #include "EXTERN.h"
69 #include "perl.h"
70 #include "XSUB.h"
71 #include <rpc/rpc.h>
72
73 MODULE = RPC PACKAGE = RPC
74
75 bool_t
76 rpcb_gettime(host,timep)
8e07c86e
AD
77 char *host
78 time_t &timep
a0d0e21e
LW
79 OUTPUT:
80 timep
81
82Any extension to Perl, including those containing XSUBs,
83should have a Perl module to serve as the bootstrap which
84pulls the extension into Perl. This module will export the
85extension's functions and variables to the Perl program and
86will cause the extension's XSUBs to be linked into Perl.
87The following module will be used for most of the examples
88in this document and should be used from Perl with the C<use>
89command as shown earlier. Perl modules are explained in
90more detail later in this document.
91
92 package RPC;
93
94 require Exporter;
95 require DynaLoader;
96 @ISA = qw(Exporter DynaLoader);
97 @EXPORT = qw( rpcb_gettime );
98
99 bootstrap RPC;
100 1;
101
102Throughout this document a variety of interfaces to the rpcb_gettime()
103XSUB will be explored. The XSUBs will take their parameters in different
104orders or will take different numbers of parameters. In each case the
105XSUB is an abstraction between Perl and the real C rpcb_gettime()
106function, and the XSUB must always ensure that the real rpcb_gettime()
107function is called with the correct parameters. This abstraction will
108allow the programmer to create a more Perl-like interface to the C
109function.
110
111=head2 The Anatomy of an XSUB
112
8e07c86e
AD
113The following XSUB allows a Perl program to access a C library function
114called sin(). The XSUB will imitate the C function which takes a single
115argument and returns a single value.
a0d0e21e
LW
116
117 double
118 sin(x)
8e07c86e 119 double x
a0d0e21e 120
8e07c86e
AD
121When using C pointers the indirection operator C<*> should be considered
122part of the type and the address operator C<&> should be considered part of
123the variable, as is demonstrated in the rpcb_gettime() function above. See
124the section on typemaps for more about handling qualifiers and unary
125operators in C types.
a0d0e21e 126
a0d0e21e
LW
127The function name and the return type must be placed on
128separate lines.
129
130 INCORRECT CORRECT
131
132 double sin(x) double
8e07c86e
AD
133 double x sin(x)
134 double x
a0d0e21e 135
c07a80fd
PP
136The function body may be indented or left-adjusted. The following example
137shows a function with its body left-adjusted. Most examples in this
138document will indent the body.
139
140 CORRECT
141
142 double
143 sin(x)
144 double x
145
a0d0e21e
LW
146=head2 The Argument Stack
147
148The argument stack is used to store the values which are
149sent as parameters to the XSUB and to store the XSUB's
150return value. In reality all Perl functions keep their
151values on this stack at the same time, each limited to its
152own range of positions on the stack. In this document the
153first position on that stack which belongs to the active
154function will be referred to as position 0 for that function.
155
8e07c86e
AD
156XSUBs refer to their stack arguments with the macro B<ST(x)>, where I<x>
157refers to a position in this XSUB's part of the stack. Position 0 for that
a0d0e21e
LW
158function would be known to the XSUB as ST(0). The XSUB's incoming
159parameters and outgoing return values always begin at ST(0). For many
160simple cases the B<xsubpp> compiler will generate the code necessary to
161handle the argument stack by embedding code fragments found in the
162typemaps. In more complex cases the programmer must supply the code.
163
164=head2 The RETVAL Variable
165
166The RETVAL variable is a magic variable which always matches
167the return type of the C library function. The B<xsubpp> compiler will
168supply this variable in each XSUB and by default will use it to hold the
169return value of the C library function being called. In simple cases the
170value of RETVAL will be placed in ST(0) of the argument stack where it can
171be received by Perl as the return value of the XSUB.
172
173If the XSUB has a return type of C<void> then the compiler will
174not supply a RETVAL variable for that function. When using
e7ea3e70
IZ
175the PPCODE: directive the RETVAL variable is not needed, unless used
176explicitly.
177
178If PPCODE: directive is not used, C<void> return value should be used
179only for subroutines which do not return a value, I<even if> CODE:
54310121 180directive is used which sets ST(0) explicitly.
e7ea3e70
IZ
181
182Older versions of this document recommended to use C<void> return
183value in such cases. It was discovered that this could lead to
184segfaults in cases when XSUB was I<truely> C<void>. This practice is
185now deprecated, and may be not supported at some future version. Use
186the return value C<SV *> in such cases. (Currently C<xsubpp> contains
187some heuristic code which tries to disambiguate between "truely-void"
188and "old-practice-declared-as-void" functions. Hence your code is at
189mercy of this heuristics unless you use C<SV *> as return value.)
a0d0e21e
LW
190
191=head2 The MODULE Keyword
192
193The MODULE keyword is used to start the XS code and to
194specify the package of the functions which are being
195defined. All text preceding the first MODULE keyword is
196considered C code and is passed through to the output
197untouched. Every XS module will have a bootstrap function
198which is used to hook the XSUBs into Perl. The package name
199of this bootstrap function will match the value of the last
200MODULE statement in the XS source files. The value of
201MODULE should always remain constant within the same XS
202file, though this is not required.
203
204The following example will start the XS code and will place
205all functions in a package named RPC.
206
207 MODULE = RPC
208
209=head2 The PACKAGE Keyword
210
211When functions within an XS source file must be separated into packages
212the PACKAGE keyword should be used. This keyword is used with the MODULE
213keyword and must follow immediately after it when used.
214
215 MODULE = RPC PACKAGE = RPC
216
217 [ XS code in package RPC ]
218
219 MODULE = RPC PACKAGE = RPCB
220
221 [ XS code in package RPCB ]
222
223 MODULE = RPC PACKAGE = RPC
224
225 [ XS code in package RPC ]
226
227Although this keyword is optional and in some cases provides redundant
228information it should always be used. This keyword will ensure that the
229XSUBs appear in the desired package.
230
231=head2 The PREFIX Keyword
232
233The PREFIX keyword designates prefixes which should be
234removed from the Perl function names. If the C function is
235C<rpcb_gettime()> and the PREFIX value is C<rpcb_> then Perl will
236see this function as C<gettime()>.
237
238This keyword should follow the PACKAGE keyword when used.
239If PACKAGE is not used then PREFIX should follow the MODULE
240keyword.
241
242 MODULE = RPC PREFIX = rpc_
243
244 MODULE = RPC PACKAGE = RPCB PREFIX = rpcb_
245
246=head2 The OUTPUT: Keyword
247
248The OUTPUT: keyword indicates that certain function parameters should be
249updated (new values made visible to Perl) when the XSUB terminates or that
250certain values should be returned to the calling Perl function. For
251simple functions, such as the sin() function above, the RETVAL variable is
252automatically designated as an output value. In more complex functions
253the B<xsubpp> compiler will need help to determine which variables are output
254variables.
255
256This keyword will normally be used to complement the CODE: keyword.
257The RETVAL variable is not recognized as an output variable when the
258CODE: keyword is present. The OUTPUT: keyword is used in this
259situation to tell the compiler that RETVAL really is an output
260variable.
261
262The OUTPUT: keyword can also be used to indicate that function parameters
263are output variables. This may be necessary when a parameter has been
264modified within the function and the programmer would like the update to
8e07c86e 265be seen by Perl.
a0d0e21e
LW
266
267 bool_t
268 rpcb_gettime(host,timep)
8e07c86e
AD
269 char *host
270 time_t &timep
a0d0e21e
LW
271 OUTPUT:
272 timep
273
274The OUTPUT: keyword will also allow an output parameter to
275be mapped to a matching piece of code rather than to a
ef50df4b 276typemap.
a0d0e21e
LW
277
278 bool_t
279 rpcb_gettime(host,timep)
8e07c86e
AD
280 char *host
281 time_t &timep
a0d0e21e 282 OUTPUT:
ef50df4b
GS
283 timep sv_setnv(ST(1), (double)timep);
284
285B<xsubpp> emits an automatic C<SvSETMAGIC()> for all parameters in the
286OUTPUT section of the XSUB, except RETVAL. This is the usually desired
287behavior, as it takes care of properly invoking 'set' magic on output
288parameters (needed for hash or array element parameters that must be
289created if they didn't exist). If for some reason, this behavior is
290not desired, the OUTPUT section may contain a C<SETMAGIC: DISABLE> line
291to disable it for the remainder of the parameters in the OUTPUT section.
292Likewise, C<SETMAGIC: ENABLE> can be used to reenable it for the
293remainder of the OUTPUT section. See L<perlguts> for more details
294about 'set' magic.
a0d0e21e
LW
295
296=head2 The CODE: Keyword
297
298This keyword is used in more complicated XSUBs which require
299special handling for the C function. The RETVAL variable is
300available but will not be returned unless it is specified
301under the OUTPUT: keyword.
302
303The following XSUB is for a C function which requires special handling of
304its parameters. The Perl usage is given first.
305
306 $status = rpcb_gettime( "localhost", $timep );
307
54310121 308The XSUB follows.
a0d0e21e 309
d1b91892
AD
310 bool_t
311 rpcb_gettime(host,timep)
8e07c86e
AD
312 char *host
313 time_t timep
a0d0e21e
LW
314 CODE:
315 RETVAL = rpcb_gettime( host, &timep );
316 OUTPUT:
317 timep
318 RETVAL
319
c07a80fd
PP
320=head2 The INIT: Keyword
321
322The INIT: keyword allows initialization to be inserted into the XSUB before
323the compiler generates the call to the C function. Unlike the CODE: keyword
324above, this keyword does not affect the way the compiler handles RETVAL.
325
326 bool_t
327 rpcb_gettime(host,timep)
328 char *host
329 time_t &timep
330 INIT:
331 printf("# Host is %s\n", host );
332 OUTPUT:
333 timep
a0d0e21e
LW
334
335=head2 The NO_INIT Keyword
336
337The NO_INIT keyword is used to indicate that a function
54310121 338parameter is being used only as an output value. The B<xsubpp>
a0d0e21e
LW
339compiler will normally generate code to read the values of
340all function parameters from the argument stack and assign
341them to C variables upon entry to the function. NO_INIT
342will tell the compiler that some parameters will be used for
343output rather than for input and that they will be handled
344before the function terminates.
345
346The following example shows a variation of the rpcb_gettime() function.
54310121 347This function uses the timep variable only as an output variable and does
a0d0e21e
LW
348not care about its initial contents.
349
350 bool_t
351 rpcb_gettime(host,timep)
8e07c86e
AD
352 char *host
353 time_t &timep = NO_INIT
a0d0e21e
LW
354 OUTPUT:
355 timep
356
357=head2 Initializing Function Parameters
358
359Function parameters are normally initialized with their
360values from the argument stack. The typemaps contain the
361code segments which are used to transfer the Perl values to
362the C parameters. The programmer, however, is allowed to
363override the typemaps and supply alternate initialization
364code.
365
366The following code demonstrates how to supply initialization code for
367function parameters. The initialization code is eval'd by the compiler
368before it is added to the output so anything which should be interpreted
369literally, such as double quotes, must be protected with backslashes.
370
371 bool_t
372 rpcb_gettime(host,timep)
8e07c86e
AD
373 char *host = (char *)SvPV(ST(0),na);
374 time_t &timep = 0;
a0d0e21e
LW
375 OUTPUT:
376 timep
377
378This should not be used to supply default values for parameters. One
379would normally use this when a function parameter must be processed by
380another library function before it can be used. Default parameters are
381covered in the next section.
382
383=head2 Default Parameter Values
384
385Default values can be specified for function parameters by
386placing an assignment statement in the parameter list. The
387default value may be a number or a string. Defaults should
388always be used on the right-most parameters only.
389
390To allow the XSUB for rpcb_gettime() to have a default host
391value the parameters to the XSUB could be rearranged. The
392XSUB will then call the real rpcb_gettime() function with
393the parameters in the correct order. Perl will call this
394XSUB with either of the following statements.
395
396 $status = rpcb_gettime( $timep, $host );
397
398 $status = rpcb_gettime( $timep );
399
400The XSUB will look like the code which follows. A CODE:
401block is used to call the real rpcb_gettime() function with
402the parameters in the correct order for that function.
403
404 bool_t
405 rpcb_gettime(timep,host="localhost")
8e07c86e
AD
406 char *host
407 time_t timep = NO_INIT
a0d0e21e
LW
408 CODE:
409 RETVAL = rpcb_gettime( host, &timep );
410 OUTPUT:
411 timep
412 RETVAL
413
c07a80fd
PP
414=head2 The PREINIT: Keyword
415
416The PREINIT: keyword allows extra variables to be declared before the
417typemaps are expanded. If a variable is declared in a CODE: block then that
418variable will follow any typemap code. This may result in a C syntax
419error. To force the variable to be declared before the typemap code, place
420it into a PREINIT: block. The PREINIT: keyword may be used one or more
421times within an XSUB.
422
423The following examples are equivalent, but if the code is using complex
424typemaps then the first example is safer.
425
426 bool_t
427 rpcb_gettime(timep)
428 time_t timep = NO_INIT
429 PREINIT:
430 char *host = "localhost";
431 CODE:
432 RETVAL = rpcb_gettime( host, &timep );
433 OUTPUT:
434 timep
435 RETVAL
436
437A correct, but error-prone example.
438
439 bool_t
440 rpcb_gettime(timep)
441 time_t timep = NO_INIT
442 CODE:
443 char *host = "localhost";
444 RETVAL = rpcb_gettime( host, &timep );
445 OUTPUT:
446 timep
447 RETVAL
448
84287afe
PP
449=head2 The SCOPE: Keyword
450
451The SCOPE: keyword allows scoping to be enabled for a particular XSUB. If
452enabled, the XSUB will invoke ENTER and LEAVE automatically.
453
454To support potentially complex type mappings, if a typemap entry used
455by this XSUB contains a comment like C</*scope*/> then scoping will
456automatically be enabled for that XSUB.
457
458To enable scoping:
459
460 SCOPE: ENABLE
461
462To disable scoping:
463
464 SCOPE: DISABLE
465
c07a80fd
PP
466=head2 The INPUT: Keyword
467
468The XSUB's parameters are usually evaluated immediately after entering the
469XSUB. The INPUT: keyword can be used to force those parameters to be
470evaluated a little later. The INPUT: keyword can be used multiple times
471within an XSUB and can be used to list one or more input variables. This
472keyword is used with the PREINIT: keyword.
473
474The following example shows how the input parameter C<timep> can be
475evaluated late, after a PREINIT.
476
477 bool_t
478 rpcb_gettime(host,timep)
479 char *host
480 PREINIT:
481 time_t tt;
482 INPUT:
483 time_t timep
484 CODE:
485 RETVAL = rpcb_gettime( host, &tt );
486 timep = tt;
487 OUTPUT:
488 timep
489 RETVAL
490
491The next example shows each input parameter evaluated late.
492
493 bool_t
494 rpcb_gettime(host,timep)
495 PREINIT:
496 time_t tt;
497 INPUT:
498 char *host
499 PREINIT:
500 char *h;
501 INPUT:
502 time_t timep
503 CODE:
504 h = host;
505 RETVAL = rpcb_gettime( h, &tt );
506 timep = tt;
507 OUTPUT:
508 timep
509 RETVAL
510
a0d0e21e
LW
511=head2 Variable-length Parameter Lists
512
513XSUBs can have variable-length parameter lists by specifying an ellipsis
514C<(...)> in the parameter list. This use of the ellipsis is similar to that
515found in ANSI C. The programmer is able to determine the number of
516arguments passed to the XSUB by examining the C<items> variable which the
517B<xsubpp> compiler supplies for all XSUBs. By using this mechanism one can
518create an XSUB which accepts a list of parameters of unknown length.
519
520The I<host> parameter for the rpcb_gettime() XSUB can be
521optional so the ellipsis can be used to indicate that the
522XSUB will take a variable number of parameters. Perl should
d1b91892 523be able to call this XSUB with either of the following statements.
a0d0e21e
LW
524
525 $status = rpcb_gettime( $timep, $host );
526
527 $status = rpcb_gettime( $timep );
528
529The XS code, with ellipsis, follows.
530
531 bool_t
532 rpcb_gettime(timep, ...)
8e07c86e 533 time_t timep = NO_INIT
c07a80fd 534 PREINIT:
a0d0e21e 535 char *host = "localhost";
c07a80fd
PP
536 CODE:
537 if( items > 1 )
538 host = (char *)SvPV(ST(1), na);
539 RETVAL = rpcb_gettime( host, &timep );
a0d0e21e
LW
540 OUTPUT:
541 timep
542 RETVAL
543
544=head2 The PPCODE: Keyword
545
546The PPCODE: keyword is an alternate form of the CODE: keyword and is used
547to tell the B<xsubpp> compiler that the programmer is supplying the code to
d1b91892 548control the argument stack for the XSUBs return values. Occasionally one
a0d0e21e
LW
549will want an XSUB to return a list of values rather than a single value.
550In these cases one must use PPCODE: and then explicitly push the list of
551values on the stack. The PPCODE: and CODE: keywords are not used
552together within the same XSUB.
553
554The following XSUB will call the C rpcb_gettime() function
555and will return its two output values, timep and status, to
556Perl as a single list.
557
d1b91892
AD
558 void
559 rpcb_gettime(host)
8e07c86e 560 char *host
c07a80fd 561 PREINIT:
a0d0e21e
LW
562 time_t timep;
563 bool_t status;
c07a80fd 564 PPCODE:
a0d0e21e 565 status = rpcb_gettime( host, &timep );
924508f0 566 EXTEND(SP, 2);
cb1a09d0
AD
567 PUSHs(sv_2mortal(newSViv(status)));
568 PUSHs(sv_2mortal(newSViv(timep)));
a0d0e21e
LW
569
570Notice that the programmer must supply the C code necessary
571to have the real rpcb_gettime() function called and to have
572the return values properly placed on the argument stack.
573
574The C<void> return type for this function tells the B<xsubpp> compiler that
575the RETVAL variable is not needed or used and that it should not be created.
576In most scenarios the void return type should be used with the PPCODE:
577directive.
578
579The EXTEND() macro is used to make room on the argument
580stack for 2 return values. The PPCODE: directive causes the
924508f0 581B<xsubpp> compiler to create a stack pointer available as C<SP>, and it
a0d0e21e
LW
582is this pointer which is being used in the EXTEND() macro.
583The values are then pushed onto the stack with the PUSHs()
584macro.
585
586Now the rpcb_gettime() function can be used from Perl with
587the following statement.
588
589 ($status, $timep) = rpcb_gettime("localhost");
590
ef50df4b
GS
591When handling output parameters with a PPCODE section, be sure to handle
592'set' magic properly. See L<perlguts> for details about 'set' magic.
593
a0d0e21e
LW
594=head2 Returning Undef And Empty Lists
595
5f05dabc 596Occasionally the programmer will want to return simply
a0d0e21e
LW
597C<undef> or an empty list if a function fails rather than a
598separate status value. The rpcb_gettime() function offers
599just this situation. If the function succeeds we would like
600to have it return the time and if it fails we would like to
601have undef returned. In the following Perl code the value
602of $timep will either be undef or it will be a valid time.
603
604 $timep = rpcb_gettime( "localhost" );
605
7b8d334a 606The following XSUB uses the C<SV *> return type as a mnemonic only,
e7ea3e70 607and uses a CODE: block to indicate to the compiler
a0d0e21e
LW
608that the programmer has supplied all the necessary code. The
609sv_newmortal() call will initialize the return value to undef, making that
610the default return value.
611
e7ea3e70 612 SV *
a0d0e21e
LW
613 rpcb_gettime(host)
614 char * host
c07a80fd 615 PREINIT:
a0d0e21e
LW
616 time_t timep;
617 bool_t x;
c07a80fd 618 CODE:
a0d0e21e
LW
619 ST(0) = sv_newmortal();
620 if( rpcb_gettime( host, &timep ) )
621 sv_setnv( ST(0), (double)timep);
a0d0e21e
LW
622
623The next example demonstrates how one would place an explicit undef in the
624return value, should the need arise.
625
e7ea3e70 626 SV *
a0d0e21e
LW
627 rpcb_gettime(host)
628 char * host
c07a80fd 629 PREINIT:
a0d0e21e
LW
630 time_t timep;
631 bool_t x;
c07a80fd 632 CODE:
a0d0e21e
LW
633 ST(0) = sv_newmortal();
634 if( rpcb_gettime( host, &timep ) ){
635 sv_setnv( ST(0), (double)timep);
636 }
637 else{
638 ST(0) = &sv_undef;
639 }
a0d0e21e
LW
640
641To return an empty list one must use a PPCODE: block and
642then not push return values on the stack.
643
644 void
645 rpcb_gettime(host)
8e07c86e 646 char *host
c07a80fd 647 PREINIT:
a0d0e21e 648 time_t timep;
c07a80fd 649 PPCODE:
a0d0e21e 650 if( rpcb_gettime( host, &timep ) )
cb1a09d0 651 PUSHs(sv_2mortal(newSViv(timep)));
a0d0e21e
LW
652 else{
653 /* Nothing pushed on stack, so an empty */
654 /* list is implicitly returned. */
655 }
a0d0e21e 656
f27cfbbe
PP
657Some people may be inclined to include an explicit C<return> in the above
658XSUB, rather than letting control fall through to the end. In those
659situations C<XSRETURN_EMPTY> should be used, instead. This will ensure that
660the XSUB stack is properly adjusted. Consult L<perlguts/"API LISTING"> for
661other C<XSRETURN> macros.
662
4633a7c4
LW
663=head2 The REQUIRE: Keyword
664
665The REQUIRE: keyword is used to indicate the minimum version of the
666B<xsubpp> compiler needed to compile the XS module. An XS module which
5f05dabc 667contains the following statement will compile with only B<xsubpp> version
4633a7c4
LW
6681.922 or greater:
669
670 REQUIRE: 1.922
671
a0d0e21e
LW
672=head2 The CLEANUP: Keyword
673
674This keyword can be used when an XSUB requires special cleanup procedures
675before it terminates. When the CLEANUP: keyword is used it must follow
676any CODE:, PPCODE:, or OUTPUT: blocks which are present in the XSUB. The
677code specified for the cleanup block will be added as the last statements
678in the XSUB.
679
680=head2 The BOOT: Keyword
681
682The BOOT: keyword is used to add code to the extension's bootstrap
683function. The bootstrap function is generated by the B<xsubpp> compiler and
684normally holds the statements necessary to register any XSUBs with Perl.
685With the BOOT: keyword the programmer can tell the compiler to add extra
686statements to the bootstrap function.
687
688This keyword may be used any time after the first MODULE keyword and should
689appear on a line by itself. The first blank line after the keyword will
690terminate the code block.
691
692 BOOT:
693 # The following message will be printed when the
694 # bootstrap function executes.
695 printf("Hello from the bootstrap!\n");
696
c07a80fd
PP
697=head2 The VERSIONCHECK: Keyword
698
699The VERSIONCHECK: keyword corresponds to B<xsubpp>'s C<-versioncheck> and
5f05dabc 700C<-noversioncheck> options. This keyword overrides the command line
c07a80fd
PP
701options. Version checking is enabled by default. When version checking is
702enabled the XS module will attempt to verify that its version matches the
703version of the PM module.
704
705To enable version checking:
706
707 VERSIONCHECK: ENABLE
708
709To disable version checking:
710
711 VERSIONCHECK: DISABLE
712
713=head2 The PROTOTYPES: Keyword
714
715The PROTOTYPES: keyword corresponds to B<xsubpp>'s C<-prototypes> and
54310121 716C<-noprototypes> options. This keyword overrides the command line options.
c07a80fd
PP
717Prototypes are enabled by default. When prototypes are enabled XSUBs will
718be given Perl prototypes. This keyword may be used multiple times in an XS
719module to enable and disable prototypes for different parts of the module.
720
721To enable prototypes:
722
723 PROTOTYPES: ENABLE
724
725To disable prototypes:
726
727 PROTOTYPES: DISABLE
728
729=head2 The PROTOTYPE: Keyword
730
731This keyword is similar to the PROTOTYPES: keyword above but can be used to
732force B<xsubpp> to use a specific prototype for the XSUB. This keyword
733overrides all other prototype options and keywords but affects only the
734current XSUB. Consult L<perlsub/Prototypes> for information about Perl
735prototypes.
736
737 bool_t
738 rpcb_gettime(timep, ...)
739 time_t timep = NO_INIT
740 PROTOTYPE: $;$
741 PREINIT:
742 char *host = "localhost";
743 CODE:
744 if( items > 1 )
745 host = (char *)SvPV(ST(1), na);
746 RETVAL = rpcb_gettime( host, &timep );
747 OUTPUT:
748 timep
749 RETVAL
750
751=head2 The ALIAS: Keyword
752
68dc0745 753The ALIAS: keyword allows an XSUB to have two more unique Perl names
c07a80fd
PP
754and to know which of those names was used when it was invoked. The Perl
755names may be fully-qualified with package names. Each alias is given an
756index. The compiler will setup a variable called C<ix> which contain the
757index of the alias which was used. When the XSUB is called with its
758declared name C<ix> will be 0.
759
760The following example will create aliases C<FOO::gettime()> and
761C<BAR::getit()> for this function.
762
763 bool_t
764 rpcb_gettime(host,timep)
765 char *host
766 time_t &timep
767 ALIAS:
768 FOO::gettime = 1
769 BAR::getit = 2
770 INIT:
771 printf("# ix = %d\n", ix );
772 OUTPUT:
773 timep
774
775=head2 The INCLUDE: Keyword
776
777This keyword can be used to pull other files into the XS module. The other
778files may have XS code. INCLUDE: can also be used to run a command to
779generate the XS code to be pulled into the module.
780
781The file F<Rpcb1.xsh> contains our C<rpcb_gettime()> function:
782
783 bool_t
784 rpcb_gettime(host,timep)
785 char *host
786 time_t &timep
787 OUTPUT:
788 timep
789
790The XS module can use INCLUDE: to pull that file into it.
791
792 INCLUDE: Rpcb1.xsh
793
794If the parameters to the INCLUDE: keyword are followed by a pipe (C<|>) then
795the compiler will interpret the parameters as a command.
796
797 INCLUDE: cat Rpcb1.xsh |
798
799=head2 The CASE: Keyword
800
801The CASE: keyword allows an XSUB to have multiple distinct parts with each
802part acting as a virtual XSUB. CASE: is greedy and if it is used then all
803other XS keywords must be contained within a CASE:. This means nothing may
804precede the first CASE: in the XSUB and anything following the last CASE: is
805included in that case.
806
807A CASE: might switch via a parameter of the XSUB, via the C<ix> ALIAS:
808variable (see L<"The ALIAS: Keyword">), or maybe via the C<items> variable
809(see L<"Variable-length Parameter Lists">). The last CASE: becomes the
810B<default> case if it is not associated with a conditional. The following
811example shows CASE switched via C<ix> with a function C<rpcb_gettime()>
812having an alias C<x_gettime()>. When the function is called as
b772cb6e
PP
813C<rpcb_gettime()> its parameters are the usual C<(char *host, time_t *timep)>,
814but when the function is called as C<x_gettime()> its parameters are
c07a80fd
PP
815reversed, C<(time_t *timep, char *host)>.
816
817 long
818 rpcb_gettime(a,b)
819 CASE: ix == 1
820 ALIAS:
821 x_gettime = 1
822 INPUT:
823 # 'a' is timep, 'b' is host
824 char *b
825 time_t a = NO_INIT
826 CODE:
827 RETVAL = rpcb_gettime( b, &a );
828 OUTPUT:
829 a
830 RETVAL
831 CASE:
832 # 'a' is host, 'b' is timep
833 char *a
834 time_t &b = NO_INIT
835 OUTPUT:
836 b
837 RETVAL
838
839That function can be called with either of the following statements. Note
840the different argument lists.
841
842 $status = rpcb_gettime( $host, $timep );
843
844 $status = x_gettime( $timep, $host );
845
846=head2 The & Unary Operator
847
848The & unary operator is used to tell the compiler that it should dereference
849the object when it calls the C function. This is used when a CODE: block is
850not used and the object is a not a pointer type (the object is an C<int> or
851C<long> but not a C<int*> or C<long*>).
852
853The following XSUB will generate incorrect C code. The xsubpp compiler will
854turn this into code which calls C<rpcb_gettime()> with parameters C<(char
855*host, time_t timep)>, but the real C<rpcb_gettime()> wants the C<timep>
856parameter to be of type C<time_t*> rather than C<time_t>.
857
858 bool_t
859 rpcb_gettime(host,timep)
860 char *host
861 time_t timep
862 OUTPUT:
863 timep
864
865That problem is corrected by using the C<&> operator. The xsubpp compiler
866will now turn this into code which calls C<rpcb_gettime()> correctly with
867parameters C<(char *host, time_t *timep)>. It does this by carrying the
868C<&> through, so the function call looks like C<rpcb_gettime(host, &timep)>.
869
870 bool_t
871 rpcb_gettime(host,timep)
872 char *host
873 time_t &timep
874 OUTPUT:
875 timep
876
a0d0e21e
LW
877=head2 Inserting Comments and C Preprocessor Directives
878
f27cfbbe 879C preprocessor directives are allowed within BOOT:, PREINIT: INIT:,
5f05dabc 880CODE:, PPCODE:, and CLEANUP: blocks, as well as outside the functions.
f27cfbbe
PP
881Comments are allowed anywhere after the MODULE keyword. The compiler
882will pass the preprocessor directives through untouched and will remove
883the commented lines.
b772cb6e 884
f27cfbbe
PP
885Comments can be added to XSUBs by placing a C<#> as the first
886non-whitespace of a line. Care should be taken to avoid making the
887comment look like a C preprocessor directive, lest it be interpreted as
888such. The simplest way to prevent this is to put whitespace in front of
889the C<#>.
890
f27cfbbe
PP
891If you use preprocessor directives to choose one of two
892versions of a function, use
893
894 #if ... version1
895 #else /* ... version2 */
896 #endif
897
898and not
899
900 #if ... version1
901 #endif
902 #if ... version2
903 #endif
904
905because otherwise xsubpp will believe that you made a duplicate
906definition of the function. Also, put a blank line before the
907#else/#endif so it will not be seen as part of the function body.
a0d0e21e
LW
908
909=head2 Using XS With C++
910
911If a function is defined as a C++ method then it will assume
912its first argument is an object pointer. The object pointer
913will be stored in a variable called THIS. The object should
914have been created by C++ with the new() function and should
cb1a09d0
AD
915be blessed by Perl with the sv_setref_pv() macro. The
916blessing of the object by Perl can be handled by a typemap. An example
917typemap is shown at the end of this section.
a0d0e21e
LW
918
919If the method is defined as static it will call the C++
920function using the class::method() syntax. If the method is not static
f27cfbbe 921the function will be called using the THIS-E<gt>method() syntax.
a0d0e21e 922
cb1a09d0 923The next examples will use the following C++ class.
a0d0e21e 924
a5f75d66 925 class color {
cb1a09d0 926 public:
a5f75d66
AD
927 color();
928 ~color();
cb1a09d0
AD
929 int blue();
930 void set_blue( int );
931
932 private:
933 int c_blue;
934 };
935
936The XSUBs for the blue() and set_blue() methods are defined with the class
937name but the parameter for the object (THIS, or "self") is implicit and is
938not listed.
939
940 int
941 color::blue()
a0d0e21e
LW
942
943 void
cb1a09d0
AD
944 color::set_blue( val )
945 int val
a0d0e21e 946
cb1a09d0
AD
947Both functions will expect an object as the first parameter. The xsubpp
948compiler will call that object C<THIS> and will use it to call the specified
949method. So in the C++ code the blue() and set_blue() methods will be called
950in the following manner.
a0d0e21e 951
cb1a09d0 952 RETVAL = THIS->blue();
a0d0e21e 953
cb1a09d0 954 THIS->set_blue( val );
a0d0e21e 955
cb1a09d0
AD
956If the function's name is B<DESTROY> then the C++ C<delete> function will be
957called and C<THIS> will be given as its parameter.
a0d0e21e 958
d1b91892 959 void
cb1a09d0
AD
960 color::DESTROY()
961
962The C++ code will call C<delete>.
963
964 delete THIS;
a0d0e21e 965
cb1a09d0
AD
966If the function's name is B<new> then the C++ C<new> function will be called
967to create a dynamic C++ object. The XSUB will expect the class name, which
968will be kept in a variable called C<CLASS>, to be given as the first
969argument.
a0d0e21e 970
cb1a09d0
AD
971 color *
972 color::new()
a0d0e21e 973
cb1a09d0 974The C++ code will call C<new>.
a0d0e21e 975
cb1a09d0
AD
976 RETVAL = new color();
977
978The following is an example of a typemap that could be used for this C++
979example.
980
981 TYPEMAP
982 color * O_OBJECT
983
984 OUTPUT
985 # The Perl object is blessed into 'CLASS', which should be a
986 # char* having the name of the package for the blessing.
987 O_OBJECT
988 sv_setref_pv( $arg, CLASS, (void*)$var );
a6006777 989
cb1a09d0
AD
990 INPUT
991 O_OBJECT
992 if( sv_isobject($arg) && (SvTYPE(SvRV($arg)) == SVt_PVMG) )
993 $var = ($type)SvIV((SV*)SvRV( $arg ));
994 else{
995 warn( \"${Package}::$func_name() -- $var is not a blessed SV reference\" );
996 XSRETURN_UNDEF;
997 }
a0d0e21e 998
d1b91892 999=head2 Interface Strategy
a0d0e21e
LW
1000
1001When designing an interface between Perl and a C library a straight
1002translation from C to XS is often sufficient. The interface will often be
1003very C-like and occasionally nonintuitive, especially when the C function
1004modifies one of its parameters. In cases where the programmer wishes to
1005create a more Perl-like interface the following strategy may help to
1006identify the more critical parts of the interface.
1007
1008Identify the C functions which modify their parameters. The XSUBs for
1009these functions may be able to return lists to Perl, or may be
1010candidates to return undef or an empty list in case of failure.
1011
d1b91892 1012Identify which values are used by only the C and XSUB functions
a0d0e21e
LW
1013themselves. If Perl does not need to access the contents of the value
1014then it may not be necessary to provide a translation for that value
1015from C to Perl.
1016
1017Identify the pointers in the C function parameter lists and return
1018values. Some pointers can be handled in XS with the & unary operator on
1019the variable name while others will require the use of the * operator on
1020the type name. In general it is easier to work with the & operator.
1021
1022Identify the structures used by the C functions. In many
1023cases it may be helpful to use the T_PTROBJ typemap for
1024these structures so they can be manipulated by Perl as
1025blessed objects.
1026
a0d0e21e
LW
1027=head2 Perl Objects And C Structures
1028
1029When dealing with C structures one should select either
1030B<T_PTROBJ> or B<T_PTRREF> for the XS type. Both types are
1031designed to handle pointers to complex objects. The
1032T_PTRREF type will allow the Perl object to be unblessed
1033while the T_PTROBJ type requires that the object be blessed.
1034By using T_PTROBJ one can achieve a form of type-checking
d1b91892 1035because the XSUB will attempt to verify that the Perl object
a0d0e21e
LW
1036is of the expected type.
1037
1038The following XS code shows the getnetconfigent() function which is used
8e07c86e 1039with ONC+ TIRPC. The getnetconfigent() function will return a pointer to a
a0d0e21e
LW
1040C structure and has the C prototype shown below. The example will
1041demonstrate how the C pointer will become a Perl reference. Perl will
1042consider this reference to be a pointer to a blessed object and will
1043attempt to call a destructor for the object. A destructor will be
1044provided in the XS source to free the memory used by getnetconfigent().
1045Destructors in XS can be created by specifying an XSUB function whose name
1046ends with the word B<DESTROY>. XS destructors can be used to free memory
1047which may have been malloc'd by another XSUB.
1048
1049 struct netconfig *getnetconfigent(const char *netid);
1050
1051A C<typedef> will be created for C<struct netconfig>. The Perl
1052object will be blessed in a class matching the name of the C
1053type, with the tag C<Ptr> appended, and the name should not
1054have embedded spaces if it will be a Perl package name. The
1055destructor will be placed in a class corresponding to the
1056class of the object and the PREFIX keyword will be used to
1057trim the name to the word DESTROY as Perl will expect.
1058
1059 typedef struct netconfig Netconfig;
1060
1061 MODULE = RPC PACKAGE = RPC
1062
1063 Netconfig *
1064 getnetconfigent(netid)
8e07c86e 1065 char *netid
a0d0e21e
LW
1066
1067 MODULE = RPC PACKAGE = NetconfigPtr PREFIX = rpcb_
1068
1069 void
1070 rpcb_DESTROY(netconf)
8e07c86e 1071 Netconfig *netconf
a0d0e21e
LW
1072 CODE:
1073 printf("Now in NetconfigPtr::DESTROY\n");
1074 free( netconf );
1075
1076This example requires the following typemap entry. Consult the typemap
1077section for more information about adding new typemaps for an extension.
1078
1079 TYPEMAP
1080 Netconfig * T_PTROBJ
1081
1082This example will be used with the following Perl statements.
1083
1084 use RPC;
1085 $netconf = getnetconfigent("udp");
1086
1087When Perl destroys the object referenced by $netconf it will send the
1088object to the supplied XSUB DESTROY function. Perl cannot determine, and
1089does not care, that this object is a C struct and not a Perl object. In
1090this sense, there is no difference between the object created by the
1091getnetconfigent() XSUB and an object created by a normal Perl subroutine.
1092
a0d0e21e
LW
1093=head2 The Typemap
1094
1095The typemap is a collection of code fragments which are used by the B<xsubpp>
1096compiler to map C function parameters and values to Perl values. The
1097typemap file may consist of three sections labeled C<TYPEMAP>, C<INPUT>, and
1098C<OUTPUT>. The INPUT section tells the compiler how to translate Perl values
1099into variables of certain C types. The OUTPUT section tells the compiler
1100how to translate the values from certain C types into values Perl can
1101understand. The TYPEMAP section tells the compiler which of the INPUT and
1102OUTPUT code fragments should be used to map a given C type to a Perl value.
1103Each of the sections of the typemap must be preceded by one of the TYPEMAP,
1104INPUT, or OUTPUT keywords.
1105
1106The default typemap in the C<ext> directory of the Perl source contains many
1107useful types which can be used by Perl extensions. Some extensions define
1108additional typemaps which they keep in their own directory. These
1109additional typemaps may reference INPUT and OUTPUT maps in the main
1110typemap. The B<xsubpp> compiler will allow the extension's own typemap to
1111override any mappings which are in the default typemap.
1112
1113Most extensions which require a custom typemap will need only the TYPEMAP
1114section of the typemap file. The custom typemap used in the
1115getnetconfigent() example shown earlier demonstrates what may be the typical
1116use of extension typemaps. That typemap is used to equate a C structure
1117with the T_PTROBJ typemap. The typemap used by getnetconfigent() is shown
1118here. Note that the C type is separated from the XS type with a tab and
1119that the C unary operator C<*> is considered to be a part of the C type name.
1120
1121 TYPEMAP
1122 Netconfig *<tab>T_PTROBJ
1123
1748e8dd
RS
1124Here's a more complicated example: suppose that you wanted C<struct
1125netconfig> to be blessed into the class C<Net::Config>. One way to do
1126this is to use underscores (_) to separate package names, as follows:
1127
1128 typedef struct netconfig * Net_Config;
1129
1130And then provide a typemap entry C<T_PTROBJ_SPECIAL> that maps underscores to
1131double-colons (::), and declare C<Net_Config> to be of that type:
1132
1133
1134 TYPEMAP
1135 Net_Config T_PTROBJ_SPECIAL
1136
1137 INPUT
1138 T_PTROBJ_SPECIAL
1139 if (sv_derived_from($arg, \"${(my $ntt=$ntype)=~s/_/::/g;\$ntt}\")) {
1140 IV tmp = SvIV((SV*)SvRV($arg));
1141 $var = ($type) tmp;
1142 }
1143 else
1144 croak(\"$var is not of type ${(my $ntt=$ntype)=~s/_/::/g;\$ntt}\")
1145
1146 OUTPUT
1147 T_PTROBJ_SPECIAL
1148 sv_setref_pv($arg, \"${(my $ntt=$ntype)=~s/_/::/g;\$ntt}\",
1149 (void*)$var);
1150
1151The INPUT and OUTPUT sections substitute underscores for double-colons
1152on the fly, giving the desired effect. This example demonstrates some
1153of the power and versatility of the typemap facility.
1154
a0d0e21e
LW
1155=head1 EXAMPLES
1156
1157File C<RPC.xs>: Interface to some ONC+ RPC bind library functions.
1158
1159 #include "EXTERN.h"
1160 #include "perl.h"
1161 #include "XSUB.h"
1162
1163 #include <rpc/rpc.h>
1164
1165 typedef struct netconfig Netconfig;
1166
1167 MODULE = RPC PACKAGE = RPC
1168
e7ea3e70 1169 SV *
a0d0e21e 1170 rpcb_gettime(host="localhost")
8e07c86e 1171 char *host
c07a80fd 1172 PREINIT:
a0d0e21e 1173 time_t timep;
c07a80fd 1174 CODE:
a0d0e21e
LW
1175 ST(0) = sv_newmortal();
1176 if( rpcb_gettime( host, &timep ) )
1177 sv_setnv( ST(0), (double)timep );
a0d0e21e
LW
1178
1179 Netconfig *
1180 getnetconfigent(netid="udp")
8e07c86e 1181 char *netid
a0d0e21e
LW
1182
1183 MODULE = RPC PACKAGE = NetconfigPtr PREFIX = rpcb_
1184
1185 void
1186 rpcb_DESTROY(netconf)
8e07c86e 1187 Netconfig *netconf
a0d0e21e
LW
1188 CODE:
1189 printf("NetconfigPtr::DESTROY\n");
1190 free( netconf );
1191
1192File C<typemap>: Custom typemap for RPC.xs.
1193
1194 TYPEMAP
1195 Netconfig * T_PTROBJ
1196
1197File C<RPC.pm>: Perl module for the RPC extension.
1198
1199 package RPC;
1200
1201 require Exporter;
1202 require DynaLoader;
1203 @ISA = qw(Exporter DynaLoader);
1204 @EXPORT = qw(rpcb_gettime getnetconfigent);
1205
1206 bootstrap RPC;
1207 1;
1208
1209File C<rpctest.pl>: Perl test program for the RPC extension.
1210
1211 use RPC;
1212
1213 $netconf = getnetconfigent();
1214 $a = rpcb_gettime();
1215 print "time = $a\n";
1216 print "netconf = $netconf\n";
1217
1218 $netconf = getnetconfigent("tcp");
1219 $a = rpcb_gettime("poplar");
1220 print "time = $a\n";
1221 print "netconf = $netconf\n";
1222
1223
c07a80fd
PP
1224=head1 XS VERSION
1225
f27cfbbe 1226This document covers features supported by C<xsubpp> 1.935.
c07a80fd 1227
a0d0e21e
LW
1228=head1 AUTHOR
1229
9607fc9c 1230Dean Roehrich <F<roehrich@cray.com>>
b772cb6e 1231Jul 8, 1996