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