1PERLXS(1) Perl Programmers Reference Guide PERLXS(1)
2
6 perlxs - XS language reference manual
7
9 Introduction
10 XS is an interface description file format used to create an extension
11 interface between Perl and C code (or a C library) which one wishes to
12 use with Perl. The XS interface is combined with the library to create
13 a new library which can then be either dynamically loaded or statically
14 linked into perl. The XS interface description is written in the XS
15 language and is the core component of the Perl extension interface.
16 An XSUB forms the basic unit of the XS interface. After compilation by
18 the xsubpp compiler, each XSUB amounts to a C function definition which
19 will provide the glue between Perl calling conventions and C calling
20 conventions.
21 The glue code pulls the arguments from the Perl stack, converts these
23 Perl values to the formats expected by a C function, call this C
24 function, transfers the return values of the C function back to Perl.
25 Return values here may be a conventional C return value or any C
26 function arguments that may serve as output parameters. These return
27 values may be passed back to Perl either by putting them on the Perl
28 stack, or by modifying the arguments supplied from the Perl side.
29 The above is a somewhat simplified view of what really happens. Since
31 Perl allows more flexible calling conventions than C, XSUBs may do much
32 more in practice, such as checking input parameters for validity,
33 throwing exceptions (or returning undef/empty list) if the return value
34 from the C function indicates failure, calling different C functions
35 based on numbers and types of the arguments, providing an object-
36 oriented interface, etc.
37 Of course, one could write such glue code directly in C. However, this
39 would be a tedious task, especially if one needs to write glue for
40 multiple C functions, and/or one is not familiar enough with the Perl
41 stack discipline and other such arcana. XS comes to the rescue here:
42 instead of writing this glue C code in long-hand, one can write a more
43 concise short-hand description of what should be done by the glue, and
44 let the XS compiler xsubpp handle the rest.
45 The XS language allows one to describe the mapping between how the C
47 routine is used, and how the corresponding Perl routine is used. It
48 also allows creation of Perl routines which are directly translated to
49 C code and which are not related to a pre-existing C function. In
50 cases when the C interface coincides with the Perl interface, the XSUB
51 declaration is almost identical to a declaration of a C function (in
52 K&R style). In such circumstances, there is another tool called "h2xs"
53 that is able to translate an entire C header file into a corresponding
54 XS file that will provide glue to the functions/macros described in the
55 header file.
56 The XS compiler is called xsubpp. This compiler creates the constructs
58 necessary to let an XSUB manipulate Perl values, and creates the glue
59 necessary to let Perl call the XSUB. The compiler uses typemaps to
60 determine how to map C function parameters and output values to Perl
61 values and back. The default typemap (which comes with Perl) handles
62 many common C types. A supplementary typemap may also be needed to
63 handle any special structures and types for the library being linked.
64 For more information on typemaps, see perlxstypemap.
65 A file in XS format starts with a C language section which goes until
67 the first "MODULE =" directive. Other XS directives and XSUB
68 definitions may follow this line. The "language" used in this part of
69 the file is usually referred to as the XS language. xsubpp recognizes
70 and skips POD (see perlpod) in both the C and XS language sections,
71 which allows the XS file to contain embedded documentation.
72 See perlxstut for a tutorial on the whole extension creation process.
74 Note: For some extensions, Dave Beazley's SWIG system may provide a
76 significantly more convenient mechanism for creating the extension glue
77 code. See <http://www.swig.org/> for more information.
78 On The Road
80 Many of the examples which follow will concentrate on creating an
81 interface between Perl and the ONC+ RPC bind library functions. The
82 rpcb_gettime() function is used to demonstrate many features of the XS
83 language. This function has two parameters; the first is an input
84 parameter and the second is an output parameter. The function also
85 returns a status value.
86 bool_t rpcb_gettime(const char *host, time_t *timep);
88 From C this function will be called with the following statements.
90 #include <rpc/rpc.h>
92 bool_t status;
93 time_t timep;
94 status = rpcb_gettime( "localhost", &timep );
95 If an XSUB is created to offer a direct translation between this
97 function and Perl, then this XSUB will be used from Perl with the
98 following code. The $status and $timep variables will contain the
99 output of the function.
100 use RPC;
102 $status = rpcb_gettime( "localhost", $timep );
103 The following XS file shows an XS subroutine, or XSUB, which
105 demonstrates one possible interface to the rpcb_gettime() function.
106 This XSUB represents a direct translation between C and Perl and so
107 preserves the interface even from Perl. This XSUB will be invoked from
108 Perl with the usage shown above. Note that the first three #include
109 statements, for "EXTERN.h", "perl.h", and "XSUB.h", will always be
110 present at the beginning of an XS file. This approach and others will
111 be expanded later in this document.
112 #include "EXTERN.h"
114 #include "perl.h"
115 #include "XSUB.h"
116 #include <rpc/rpc.h>
117 MODULE = RPC PACKAGE = RPC
119 bool_t
121 rpcb_gettime(host,timep)
122 char *host
123 time_t &timep
124 OUTPUT:
125 timep
126 Any extension to Perl, including those containing XSUBs, should have a
128 Perl module to serve as the bootstrap which pulls the extension into
129 Perl. This module will export the extension's functions and variables
130 to the Perl program and will cause the extension's XSUBs to be linked
131 into Perl. The following module will be used for most of the examples
132 in this document and should be used from Perl with the "use" command as
133 shown earlier. Perl modules are explained in more detail later in this
134 document.
135 package RPC;
137 require Exporter;
139 require DynaLoader;
140 @ISA = qw(Exporter DynaLoader);
141 @EXPORT = qw( rpcb_gettime );
142 bootstrap RPC;
144 1;
145 Throughout this document a variety of interfaces to the rpcb_gettime()
147 XSUB will be explored. The XSUBs will take their parameters in
148 different orders or will take different numbers of parameters. In each
149 case the XSUB is an abstraction between Perl and the real C
150 rpcb_gettime() function, and the XSUB must always ensure that the real
151 rpcb_gettime() function is called with the correct parameters. This
152 abstraction will allow the programmer to create a more Perl-like
153 interface to the C function.
154 The Anatomy of an XSUB
156 The simplest XSUBs consist of 3 parts: a description of the return
157 value, the name of the XSUB routine and the names of its arguments, and
158 a description of types or formats of the arguments.
159 The following XSUB allows a Perl program to access a C library function
161 called sin(). The XSUB will imitate the C function which takes a
162 single argument and returns a single value.
163 double
165 sin(x)
166 double x
167 Optionally, one can merge the description of types and the list of
169 argument names, rewriting this as
170 double
172 sin(double x)
173 This makes this XSUB look similar to an ANSI C declaration. An
175 optional semicolon is allowed after the argument list, as in
176 double
178 sin(double x);
179 Parameters with C pointer types can have different semantic: C
181 functions with similar declarations
182 bool string_looks_as_a_number(char *s);
184 bool make_char_uppercase(char *c);
185 are used in absolutely incompatible manner. Parameters to these
187 functions could be described xsubpp like this:
188 char * s
190 char &c
191 Both these XS declarations correspond to the "char*" C type, but they
193 have different semantics, see "The & Unary Operator".
194 It is convenient to think that the indirection operator "*" should be
196 considered as a part of the type and the address operator "&" should be
197 considered part of the variable. See perlxstypemap for more info about
198 handling qualifiers and unary operators in C types.
199 The function name and the return type must be placed on separate lines
201 and should be flush left-adjusted.
202 INCORRECT CORRECT
204 double sin(x) double
206 double x sin(x)
207 double x
208 The rest of the function description may be indented or left-adjusted.
210 The following example shows a function with its body left-adjusted.
211 Most examples in this document will indent the body for better
212 readability.
213 CORRECT
215 double
217 sin(x)
218 double x
219 More complicated XSUBs may contain many other sections. Each section
221 of an XSUB starts with the corresponding keyword, such as INIT: or
222 CLEANUP:. However, the first two lines of an XSUB always contain the
223 same data: descriptions of the return type and the names of the
224 function and its parameters. Whatever immediately follows these is
225 considered to be an INPUT: section unless explicitly marked with
226 another keyword. (See "The INPUT: Keyword".)
227 An XSUB section continues until another section-start keyword is found.
229 The Argument Stack
231 The Perl argument stack is used to store the values which are sent as
232 parameters to the XSUB and to store the XSUB's return value(s). In
233 reality all Perl functions (including non-XSUB ones) keep their values
234 on this stack all the same time, each limited to its own range of
235 positions on the stack. In this document the first position on that
236 stack which belongs to the active function will be referred to as
237 position 0 for that function.
238 XSUBs refer to their stack arguments with the macro ST(x), where x
240 refers to a position in this XSUB's part of the stack. Position 0 for
241 that function would be known to the XSUB as ST(0). The XSUB's incoming
242 parameters and outgoing return values always begin at ST(0). For many
243 simple cases the xsubpp compiler will generate the code necessary to
244 handle the argument stack by embedding code fragments found in the
245 typemaps. In more complex cases the programmer must supply the code.
246 The RETVAL Variable
248 The RETVAL variable is a special C variable that is declared
249 automatically for you. The C type of RETVAL matches the return type of
250 the C library function. The xsubpp compiler will declare this variable
251 in each XSUB with non-"void" return type. By default the generated C
252 function will use RETVAL to hold the return value of the C library
253 function being called. In simple cases the value of RETVAL will be
254 placed in ST(0) of the argument stack where it can be received by Perl
255 as the return value of the XSUB.
256 If the XSUB has a return type of "void" then the compiler will not
258 declare a RETVAL variable for that function. When using a PPCODE:
259 section no manipulation of the RETVAL variable is required, the section
260 may use direct stack manipulation to place output values on the stack.
261 If PPCODE: directive is not used, "void" return value should be used
263 only for subroutines which do not return a value, even if CODE:
264 directive is used which sets ST(0) explicitly.
265 Older versions of this document recommended to use "void" return value
267 in such cases. It was discovered that this could lead to segfaults in
268 cases when XSUB was truly "void". This practice is now deprecated, and
269 may be not supported at some future version. Use the return value "SV
270 *" in such cases. (Currently "xsubpp" contains some heuristic code
271 which tries to disambiguate between "truly-void" and "old-practice-
272 declared-as-void" functions. Hence your code is at mercy of this
273 heuristics unless you use "SV *" as return value.)
274 Returning SVs, AVs and HVs through RETVAL
276 When you're using RETVAL to return an "SV *", there's some magic going
277 on behind the scenes that should be mentioned. When you're manipulating
278 the argument stack using the ST(x) macro, for example, you usually have
279 to pay special attention to reference counts. (For more about reference
280 counts, see perlguts.) To make your life easier, the typemap file
281 automatically makes "RETVAL" mortal when you're returning an "SV *".
282 Thus, the following two XSUBs are more or less equivalent:
283 void
285 alpha()
286 PPCODE:
287 ST(0) = newSVpv("Hello World",0);
288 sv_2mortal(ST(0));
289 XSRETURN(1);
290 SV *
292 beta()
293 CODE:
294 RETVAL = newSVpv("Hello World",0);
295 OUTPUT:
296 RETVAL
297 This is quite useful as it usually improves readability. While this
299 works fine for an "SV *", it's unfortunately not as easy to have "AV *"
300 or "HV *" as a return value. You should be able to write:
301 AV *
303 array()
304 CODE:
305 RETVAL = newAV();
306 /* do something with RETVAL */
307 OUTPUT:
308 RETVAL
309 But due to an unfixable bug (fixing it would break lots of existing
311 CPAN modules) in the typemap file, the reference count of the "AV *" is
312 not properly decremented. Thus, the above XSUB would leak memory
313 whenever it is being called. The same problem exists for "HV *", "CV
314 *", and "SVREF" (which indicates a scalar reference, not a general "SV
315 *"). In XS code on perls starting with perl 5.16, you can override the
316 typemaps for any of these types with a version that has proper handling
317 of refcounts. In your "TYPEMAP" section, do
318 AV* T_AVREF_REFCOUNT_FIXED
320 to get the repaired variant. For backward compatibility with older
322 versions of perl, you can instead decrement the reference count
323 manually when you're returning one of the aforementioned types using
324 "sv_2mortal":
325 AV *
327 array()
328 CODE:
329 RETVAL = newAV();
330 sv_2mortal((SV*)RETVAL);
331 /* do something with RETVAL */
332 OUTPUT:
333 RETVAL
334 Remember that you don't have to do this for an "SV *". The reference
336 documentation for all core typemaps can be found in perlxstypemap.
337 The MODULE Keyword
339 The MODULE keyword is used to start the XS code and to specify the
340 package of the functions which are being defined. All text preceding
341 the first MODULE keyword is considered C code and is passed through to
342 the output with POD stripped, but otherwise untouched. Every XS module
343 will have a bootstrap function which is used to hook the XSUBs into
344 Perl. The package name of this bootstrap function will match the value
345 of the last MODULE statement in the XS source files. The value of
346 MODULE should always remain constant within the same XS file, though
347 this is not required.
348 The following example will start the XS code and will place all
350 functions in a package named RPC.
351 MODULE = RPC
353 The PACKAGE Keyword
355 When functions within an XS source file must be separated into packages
356 the PACKAGE keyword should be used. This keyword is used with the
357 MODULE keyword and must follow immediately after it when used.
358 MODULE = RPC PACKAGE = RPC
360 [ XS code in package RPC ]
362 MODULE = RPC PACKAGE = RPCB
364 [ XS code in package RPCB ]
366 MODULE = RPC PACKAGE = RPC
368 [ XS code in package RPC ]
370 The same package name can be used more than once, allowing for non-
372 contiguous code. This is useful if you have a stronger ordering
373 principle than package names.
374 Although this keyword is optional and in some cases provides redundant
376 information it should always be used. This keyword will ensure that
377 the XSUBs appear in the desired package.
378 The PREFIX Keyword
380 The PREFIX keyword designates prefixes which should be removed from the
381 Perl function names. If the C function is "rpcb_gettime()" and the
382 PREFIX value is "rpcb_" then Perl will see this function as
383 "gettime()".
384 This keyword should follow the PACKAGE keyword when used. If PACKAGE
386 is not used then PREFIX should follow the MODULE keyword.
387 MODULE = RPC PREFIX = rpc_
389 MODULE = RPC PACKAGE = RPCB PREFIX = rpcb_
391 The OUTPUT: Keyword
393 The OUTPUT: keyword indicates that certain function parameters should
394 be updated (new values made visible to Perl) when the XSUB terminates
395 or that certain values should be returned to the calling Perl function.
396 For simple functions which have no CODE: or PPCODE: section, such as
397 the sin() function above, the RETVAL variable is automatically
398 designated as an output value. For more complex functions the xsubpp
399 compiler will need help to determine which variables are output
400 variables.
401 This keyword will normally be used to complement the CODE: keyword.
403 The RETVAL variable is not recognized as an output variable when the
404 CODE: keyword is present. The OUTPUT: keyword is used in this
405 situation to tell the compiler that RETVAL really is an output
406 variable.
407 The OUTPUT: keyword can also be used to indicate that function
409 parameters are output variables. This may be necessary when a
410 parameter has been modified within the function and the programmer
411 would like the update to be seen by Perl.
412 bool_t
414 rpcb_gettime(host,timep)
415 char *host
416 time_t &timep
417 OUTPUT:
418 timep
419 The OUTPUT: keyword will also allow an output parameter to be mapped to
421 a matching piece of code rather than to a typemap.
422 bool_t
424 rpcb_gettime(host,timep)
425 char *host
426 time_t &timep
427 OUTPUT:
428 timep sv_setnv(ST(1), (double)timep);
429 xsubpp emits an automatic "SvSETMAGIC()" for all parameters in the
431 OUTPUT section of the XSUB, except RETVAL. This is the usually desired
432 behavior, as it takes care of properly invoking 'set' magic on output
433 parameters (needed for hash or array element parameters that must be
434 created if they didn't exist). If for some reason, this behavior is
435 not desired, the OUTPUT section may contain a "SETMAGIC: DISABLE" line
436 to disable it for the remainder of the parameters in the OUTPUT
437 section. Likewise, "SETMAGIC: ENABLE" can be used to reenable it for
438 the remainder of the OUTPUT section. See perlguts for more details
439 about 'set' magic.
440 The NO_OUTPUT Keyword
442 The NO_OUTPUT can be placed as the first token of the XSUB. This
443 keyword indicates that while the C subroutine we provide an interface
444 to has a non-"void" return type, the return value of this C subroutine
445 should not be returned from the generated Perl subroutine.
446 With this keyword present "The RETVAL Variable" is created, and in the
448 generated call to the subroutine this variable is assigned to, but the
449 value of this variable is not going to be used in the auto-generated
450 code.
451 This keyword makes sense only if "RETVAL" is going to be accessed by
453 the user-supplied code. It is especially useful to make a function
454 interface more Perl-like, especially when the C return value is just an
455 error condition indicator. For example,
456 NO_OUTPUT int
458 delete_file(char *name)
459 POSTCALL:
460 if (RETVAL != 0)
461 croak("Error %d while deleting file '%s'", RETVAL, name);
462 Here the generated XS function returns nothing on success, and will
464 die() with a meaningful error message on error.
465 The CODE: Keyword
467 This keyword is used in more complicated XSUBs which require special
468 handling for the C function. The RETVAL variable is still declared,
469 but it will not be returned unless it is specified in the OUTPUT:
470 section.
471 The following XSUB is for a C function which requires special handling
473 of its parameters. The Perl usage is given first.
474 $status = rpcb_gettime( "localhost", $timep );
476 The XSUB follows.
478 bool_t
480 rpcb_gettime(host,timep)
481 char *host
482 time_t timep
483 CODE:
484 RETVAL = rpcb_gettime( host, &timep );
485 OUTPUT:
486 timep
487 RETVAL
488 The INIT: Keyword
490 The INIT: keyword allows initialization to be inserted into the XSUB
491 before the compiler generates the call to the C function. Unlike the
492 CODE: keyword above, this keyword does not affect the way the compiler
493 handles RETVAL.
494 bool_t
496 rpcb_gettime(host,timep)
497 char *host
498 time_t &timep
499 INIT:
500 printf("# Host is %s\n", host );
501 OUTPUT:
502 timep
503 Another use for the INIT: section is to check for preconditions before
505 making a call to the C function:
506 long long
508 lldiv(a,b)
509 long long a
510 long long b
511 INIT:
512 if (a == 0 && b == 0)
513 XSRETURN_UNDEF;
514 if (b == 0)
515 croak("lldiv: cannot divide by 0");
516 The NO_INIT Keyword
518 The NO_INIT keyword is used to indicate that a function parameter is
519 being used only as an output value. The xsubpp compiler will normally
520 generate code to read the values of all function parameters from the
521 argument stack and assign them to C variables upon entry to the
522 function. NO_INIT will tell the compiler that some parameters will be
523 used for output rather than for input and that they will be handled
524 before the function terminates.
525 The following example shows a variation of the rpcb_gettime() function.
527 This function uses the timep variable only as an output variable and
528 does not care about its initial contents.
529 bool_t
531 rpcb_gettime(host,timep)
532 char *host
533 time_t &timep = NO_INIT
534 OUTPUT:
535 timep
536 The TYPEMAP: Keyword
538 Starting with Perl 5.16, you can embed typemaps into your XS code
539 instead of or in addition to typemaps in a separate file. Multiple
540 such embedded typemaps will be processed in order of appearance in the
541 XS code and like local typemap files take precendence over the default
542 typemap, the embedded typemaps may overwrite previous definitions of
543 TYPEMAP, INPUT, and OUTPUT stanzas. The syntax for embedded typemaps
544 is
545 TYPEMAP: <<HERE
547 ... your typemap code here ...
548 HERE
549 where the "TYPEMAP" keyword must appear in the first column of a new
551 line.
552 Refer to perlxstypemap for details on writing typemaps.
554 Initializing Function Parameters
556 C function parameters are normally initialized with their values from
557 the argument stack (which in turn contains the parameters that were
558 passed to the XSUB from Perl). The typemaps contain the code segments
559 which are used to translate the Perl values to the C parameters. The
560 programmer, however, is allowed to override the typemaps and supply
561 alternate (or additional) initialization code. Initialization code
562 starts with the first "=", ";" or "+" on a line in the INPUT: section.
563 The only exception happens if this ";" terminates the line, then this
564 ";" is quietly ignored.
565 The following code demonstrates how to supply initialization code for
567 function parameters. The initialization code is eval'ed within double
568 quotes by the compiler before it is added to the output so anything
569 which should be interpreted literally [mainly "$", "@", or "\\"] must
570 be protected with backslashes. The variables $var, $arg, and $type can
571 be used as in typemaps.
572 bool_t
574 rpcb_gettime(host,timep)
575 char *host = (char *)SvPV_nolen($arg);
576 time_t &timep = 0;
577 OUTPUT:
578 timep
579 This should not be used to supply default values for parameters. One
581 would normally use this when a function parameter must be processed by
582 another library function before it can be used. Default parameters are
583 covered in the next section.
584 If the initialization begins with "=", then it is output in the
586 declaration for the input variable, replacing the initialization
587 supplied by the typemap. If the initialization begins with ";" or "+",
588 then it is performed after all of the input variables have been
589 declared. In the ";" case the initialization normally supplied by the
590 typemap is not performed. For the "+" case, the declaration for the
591 variable will include the initialization from the typemap. A global
592 variable, %v, is available for the truly rare case where information
593 from one initialization is needed in another initialization.
594 Here's a truly obscure example:
596 bool_t
598 rpcb_gettime(host,timep)
599 time_t &timep; /* \$v{timep}=@{[$v{timep}=$arg]} */
600 char *host + SvOK($v{timep}) ? SvPV_nolen($arg) : NULL;
601 OUTPUT:
602 timep
603 The construct "\$v{timep}=@{[$v{timep}=$arg]}" used in the above
605 example has a two-fold purpose: first, when this line is processed by
606 xsubpp, the Perl snippet "$v{timep}=$arg" is evaluated. Second, the
607 text of the evaluated snippet is output into the generated C file
608 (inside a C comment)! During the processing of "char *host" line, $arg
609 will evaluate to ST(0), and $v{timep} will evaluate to ST(1).
610 Default Parameter Values
612 Default values for XSUB arguments can be specified by placing an
613 assignment statement in the parameter list. The default value may be a
614 number, a string or the special string "NO_INIT". Defaults should
615 always be used on the right-most parameters only.
616 To allow the XSUB for rpcb_gettime() to have a default host value the
618 parameters to the XSUB could be rearranged. The XSUB will then call
619 the real rpcb_gettime() function with the parameters in the correct
620 order. This XSUB can be called from Perl with either of the following
621 statements:
622 $status = rpcb_gettime( $timep, $host );
624 $status = rpcb_gettime( $timep );
626 The XSUB will look like the code which follows. A CODE: block is
628 used to call the real rpcb_gettime() function with the parameters in
629 the correct order for that function.
630 bool_t
632 rpcb_gettime(timep,host="localhost")
633 char *host
634 time_t timep = NO_INIT
635 CODE:
636 RETVAL = rpcb_gettime( host, &timep );
637 OUTPUT:
638 timep
639 RETVAL
640 The PREINIT: Keyword
642 The PREINIT: keyword allows extra variables to be declared immediately
643 before or after the declarations of the parameters from the INPUT:
644 section are emitted.
645 If a variable is declared inside a CODE: section it will follow any
647 typemap code that is emitted for the input parameters. This may result
648 in the declaration ending up after C code, which is C syntax error.
649 Similar errors may happen with an explicit ";"-type or "+"-type
650 initialization of parameters is used (see "Initializing Function
651 Parameters"). Declaring these variables in an INIT: section will not
652 help.
653 In such cases, to force an additional variable to be declared together
655 with declarations of other variables, place the declaration into a
656 PREINIT: section. The PREINIT: keyword may be used one or more times
657 within an XSUB.
658 The following examples are equivalent, but if the code is using complex
660 typemaps then the first example is safer.
661 bool_t
663 rpcb_gettime(timep)
664 time_t timep = NO_INIT
665 PREINIT:
666 char *host = "localhost";
667 CODE:
668 RETVAL = rpcb_gettime( host, &timep );
669 OUTPUT:
670 timep
671 RETVAL
672 For this particular case an INIT: keyword would generate the same C
674 code as the PREINIT: keyword. Another correct, but error-prone
675 example:
676 bool_t
678 rpcb_gettime(timep)
679 time_t timep = NO_INIT
680 CODE:
681 char *host = "localhost";
682 RETVAL = rpcb_gettime( host, &timep );
683 OUTPUT:
684 timep
685 RETVAL
686 Another way to declare "host" is to use a C block in the CODE: section:
688 bool_t
690 rpcb_gettime(timep)
691 time_t timep = NO_INIT
692 CODE:
693 {
694 char *host = "localhost";
695 RETVAL = rpcb_gettime( host, &timep );
696 }
697 OUTPUT:
698 timep
699 RETVAL
700 The ability to put additional declarations before the typemap entries
702 are processed is very handy in the cases when typemap conversions
703 manipulate some global state:
704 MyObject
706 mutate(o)
707 PREINIT:
708 MyState st = global_state;
709 INPUT:
710 MyObject o;
711 CLEANUP:
712 reset_to(global_state, st);
713 Here we suppose that conversion to "MyObject" in the INPUT: section and
715 from MyObject when processing RETVAL will modify a global variable
716 "global_state". After these conversions are performed, we restore the
717 old value of "global_state" (to avoid memory leaks, for example).
718 There is another way to trade clarity for compactness: INPUT sections
720 allow declaration of C variables which do not appear in the parameter
721 list of a subroutine. Thus the above code for mutate() can be
722 rewritten as
723 MyObject
725 mutate(o)
726 MyState st = global_state;
727 MyObject o;
728 CLEANUP:
729 reset_to(global_state, st);
730 and the code for rpcb_gettime() can be rewritten as
732 bool_t
734 rpcb_gettime(timep)
735 time_t timep = NO_INIT
736 char *host = "localhost";
737 C_ARGS:
738 host, &timep
739 OUTPUT:
740 timep
741 RETVAL
742 The SCOPE: Keyword
744 The SCOPE: keyword allows scoping to be enabled for a particular XSUB.
745 If enabled, the XSUB will invoke ENTER and LEAVE automatically.
746 To support potentially complex type mappings, if a typemap entry used
748 by an XSUB contains a comment like "/*scope*/" then scoping will be
749 automatically enabled for that XSUB.
750 To enable scoping:
752 SCOPE: ENABLE
754 To disable scoping:
756 SCOPE: DISABLE
758 The INPUT: Keyword
760 The XSUB's parameters are usually evaluated immediately after entering
761 the XSUB. The INPUT: keyword can be used to force those parameters to
762 be evaluated a little later. The INPUT: keyword can be used multiple
763 times within an XSUB and can be used to list one or more input
764 variables. This keyword is used with the PREINIT: keyword.
765 The following example shows how the input parameter "timep" can be
767 evaluated late, after a PREINIT.
768 bool_t
770 rpcb_gettime(host,timep)
771 char *host
772 PREINIT:
773 time_t tt;
774 INPUT:
775 time_t timep
776 CODE:
777 RETVAL = rpcb_gettime( host, &tt );
778 timep = tt;
779 OUTPUT:
780 timep
781 RETVAL
782 The next example shows each input parameter evaluated late.
784 bool_t
786 rpcb_gettime(host,timep)
787 PREINIT:
788 time_t tt;
789 INPUT:
790 char *host
791 PREINIT:
792 char *h;
793 INPUT:
794 time_t timep
795 CODE:
796 h = host;
797 RETVAL = rpcb_gettime( h, &tt );
798 timep = tt;
799 OUTPUT:
800 timep
801 RETVAL
802 Since INPUT sections allow declaration of C variables which do not
804 appear in the parameter list of a subroutine, this may be shortened to:
805 bool_t
807 rpcb_gettime(host,timep)
808 time_t tt;
809 char *host;
810 char *h = host;
811 time_t timep;
812 CODE:
813 RETVAL = rpcb_gettime( h, &tt );
814 timep = tt;
815 OUTPUT:
816 timep
817 RETVAL
818 (We used our knowledge that input conversion for "char *" is a "simple"
820 one, thus "host" is initialized on the declaration line, and our
821 assignment "h = host" is not performed too early. Otherwise one would
822 need to have the assignment "h = host" in a CODE: or INIT: section.)
823 The IN/OUTLIST/IN_OUTLIST/OUT/IN_OUT Keywords
825 In the list of parameters for an XSUB, one can precede parameter names
826 by the "IN"/"OUTLIST"/"IN_OUTLIST"/"OUT"/"IN_OUT" keywords. "IN"
827 keyword is the default, the other keywords indicate how the Perl
828 interface should differ from the C interface.
829 Parameters preceded by "OUTLIST"/"IN_OUTLIST"/"OUT"/"IN_OUT" keywords
831 are considered to be used by the C subroutine via pointers.
832 "OUTLIST"/"OUT" keywords indicate that the C subroutine does not
833 inspect the memory pointed by this parameter, but will write through
834 this pointer to provide additional return values.
835 Parameters preceded by "OUTLIST" keyword do not appear in the usage
837 signature of the generated Perl function.
838 Parameters preceded by "IN_OUTLIST"/"IN_OUT"/"OUT" do appear as
840 parameters to the Perl function. With the exception of
841 "OUT"-parameters, these parameters are converted to the corresponding C
842 type, then pointers to these data are given as arguments to the C
843 function. It is expected that the C function will write through these
844 pointers.
845 The return list of the generated Perl function consists of the C return
847 value from the function (unless the XSUB is of "void" return type or
848 "The NO_OUTPUT Keyword" was used) followed by all the "OUTLIST" and
849 "IN_OUTLIST" parameters (in the order of appearance). On the return
850 from the XSUB the "IN_OUT"/"OUT" Perl parameter will be modified to
851 have the values written by the C function.
852 For example, an XSUB
854 void
856 day_month(OUTLIST day, IN unix_time, OUTLIST month)
857 int day
858 int unix_time
859 int month
860 should be used from Perl as
862 my ($day, $month) = day_month(time);
864 The C signature of the corresponding function should be
866 void day_month(int *day, int unix_time, int *month);
868 The "IN"/"OUTLIST"/"IN_OUTLIST"/"IN_OUT"/"OUT" keywords can be mixed
870 with ANSI-style declarations, as in
871 void
873 day_month(OUTLIST int day, int unix_time, OUTLIST int month)
874 (here the optional "IN" keyword is omitted).
876 The "IN_OUT" parameters are identical with parameters introduced with
878 "The & Unary Operator" and put into the "OUTPUT:" section (see "The
879 OUTPUT: Keyword"). The "IN_OUTLIST" parameters are very similar, the
880 only difference being that the value C function writes through the
881 pointer would not modify the Perl parameter, but is put in the output
882 list.
883 The "OUTLIST"/"OUT" parameter differ from "IN_OUTLIST"/"IN_OUT"
885 parameters only by the initial value of the Perl parameter not being
886 read (and not being given to the C function - which gets some garbage
887 instead). For example, the same C function as above can be interfaced
888 with as
889 void day_month(OUT int day, int unix_time, OUT int month);
891 or
893 void
895 day_month(day, unix_time, month)
896 int &day = NO_INIT
897 int unix_time
898 int &month = NO_INIT
899 OUTPUT:
900 day
901 month
902 However, the generated Perl function is called in very C-ish style:
904 my ($day, $month);
906 day_month($day, time, $month);
907 The "length(NAME)" Keyword
909 If one of the input arguments to the C function is the length of a
910 string argument "NAME", one can substitute the name of the length-
911 argument by "length(NAME)" in the XSUB declaration. This argument must
912 be omitted when the generated Perl function is called. E.g.,
913 void
915 dump_chars(char *s, short l)
916 {
917 short n = 0;
918 while (n < l) {
919 printf("s[%d] = \"\\%#03o\"\n", n, (int)s[n]);
920 n++;
921 }
922 }
923 MODULE = x PACKAGE = x
925 void dump_chars(char *s, short length(s))
927 should be called as "dump_chars($string)".
929 This directive is supported with ANSI-type function declarations only.
931 Variable-length Parameter Lists
933 XSUBs can have variable-length parameter lists by specifying an
934 ellipsis "(...)" in the parameter list. This use of the ellipsis is
935 similar to that found in ANSI C. The programmer is able to determine
936 the number of arguments passed to the XSUB by examining the "items"
937 variable which the xsubpp compiler supplies for all XSUBs. By using
938 this mechanism one can create an XSUB which accepts a list of
939 parameters of unknown length.
940 The host parameter for the rpcb_gettime() XSUB can be optional so the
942 ellipsis can be used to indicate that the XSUB will take a variable
943 number of parameters. Perl should be able to call this XSUB with
944 either of the following statements.
945 $status = rpcb_gettime( $timep, $host );
947 $status = rpcb_gettime( $timep );
949 The XS code, with ellipsis, follows.
951 bool_t
953 rpcb_gettime(timep, ...)
954 time_t timep = NO_INIT
955 PREINIT:
956 char *host = "localhost";
957 CODE:
958 if( items > 1 )
959 host = (char *)SvPV_nolen(ST(1));
960 RETVAL = rpcb_gettime( host, &timep );
961 OUTPUT:
962 timep
963 RETVAL
964 The C_ARGS: Keyword
966 The C_ARGS: keyword allows creating of XSUBS which have different
967 calling sequence from Perl than from C, without a need to write CODE:
968 or PPCODE: section. The contents of the C_ARGS: paragraph is put as
969 the argument to the called C function without any change.
970 For example, suppose that a C function is declared as
972 symbolic nth_derivative(int n, symbolic function, int flags);
974 and that the default flags are kept in a global C variable
976 "default_flags". Suppose that you want to create an interface which is
977 called as
978 $second_deriv = $function->nth_derivative(2);
980 To do this, declare the XSUB as
982 symbolic
984 nth_derivative(function, n)
985 symbolic function
986 int n
987 C_ARGS:
988 n, function, default_flags
989 The PPCODE: Keyword
991 The PPCODE: keyword is an alternate form of the CODE: keyword and is
992 used to tell the xsubpp compiler that the programmer is supplying the
993 code to control the argument stack for the XSUBs return values.
994 Occasionally one will want an XSUB to return a list of values rather
995 than a single value. In these cases one must use PPCODE: and then
996 explicitly push the list of values on the stack. The PPCODE: and CODE:
997 keywords should not be used together within the same XSUB.
998 The actual difference between PPCODE: and CODE: sections is in the
1000 initialization of "SP" macro (which stands for the current Perl stack
1001 pointer), and in the handling of data on the stack when returning from
1002 an XSUB. In CODE: sections SP preserves the value which was on entry
1003 to the XSUB: SP is on the function pointer (which follows the last
1004 parameter). In PPCODE: sections SP is moved backward to the beginning
1005 of the parameter list, which allows "PUSH*()" macros to place output
1006 values in the place Perl expects them to be when the XSUB returns back
1007 to Perl.
1008 The generated trailer for a CODE: section ensures that the number of
1010 return values Perl will see is either 0 or 1 (depending on the
1011 "void"ness of the return value of the C function, and heuristics
1012 mentioned in "The RETVAL Variable"). The trailer generated for a
1013 PPCODE: section is based on the number of return values and on the
1014 number of times "SP" was updated by "[X]PUSH*()" macros.
1015 Note that macros ST(i), "XST_m*()" and "XSRETURN*()" work equally well
1017 in CODE: sections and PPCODE: sections.
1018 The following XSUB will call the C rpcb_gettime() function and will
1020 return its two output values, timep and status, to Perl as a single
1021 list.
1022 void
1024 rpcb_gettime(host)
1025 char *host
1026 PREINIT:
1027 time_t timep;
1028 bool_t status;
1029 PPCODE:
1030 status = rpcb_gettime( host, &timep );
1031 EXTEND(SP, 2);
1032 PUSHs(sv_2mortal(newSViv(status)));
1033 PUSHs(sv_2mortal(newSViv(timep)));
1034 Notice that the programmer must supply the C code necessary to have the
1036 real rpcb_gettime() function called and to have the return values
1037 properly placed on the argument stack.
1038 The "void" return type for this function tells the xsubpp compiler that
1040 the RETVAL variable is not needed or used and that it should not be
1041 created. In most scenarios the void return type should be used with
1042 the PPCODE: directive.
1043 The EXTEND() macro is used to make room on the argument stack for 2
1045 return values. The PPCODE: directive causes the xsubpp compiler to
1046 create a stack pointer available as "SP", and it is this pointer which
1047 is being used in the EXTEND() macro. The values are then pushed onto
1048 the stack with the PUSHs() macro.
1049 Now the rpcb_gettime() function can be used from Perl with the
1051 following statement.
1052 ($status, $timep) = rpcb_gettime("localhost");
1054 When handling output parameters with a PPCODE section, be sure to
1056 handle 'set' magic properly. See perlguts for details about 'set'
1057 magic.
1058 Returning Undef And Empty Lists
1060 Occasionally the programmer will want to return simply "undef" or an
1061 empty list if a function fails rather than a separate status value.
1062 The rpcb_gettime() function offers just this situation. If the
1063 function succeeds we would like to have it return the time and if it
1064 fails we would like to have undef returned. In the following Perl code
1065 the value of $timep will either be undef or it will be a valid time.
1066 $timep = rpcb_gettime( "localhost" );
1068 The following XSUB uses the "SV *" return type as a mnemonic only, and
1070 uses a CODE: block to indicate to the compiler that the programmer has
1071 supplied all the necessary code. The sv_newmortal() call will
1072 initialize the return value to undef, making that the default return
1073 value.
1074 SV *
1076 rpcb_gettime(host)
1077 char * host
1078 PREINIT:
1079 time_t timep;
1080 bool_t x;
1081 CODE:
1082 ST(0) = sv_newmortal();
1083 if( rpcb_gettime( host, &timep ) )
1084 sv_setnv( ST(0), (double)timep);
1085 The next example demonstrates how one would place an explicit undef in
1087 the return value, should the need arise.
1088 SV *
1090 rpcb_gettime(host)
1091 char * host
1092 PREINIT:
1093 time_t timep;
1094 bool_t x;
1095 CODE:
1096 if( rpcb_gettime( host, &timep ) ){
1097 ST(0) = sv_newmortal();
1098 sv_setnv( ST(0), (double)timep);
1099 }
1100 else{
1101 ST(0) = &PL_sv_undef;
1102 }
1103 To return an empty list one must use a PPCODE: block and then not push
1105 return values on the stack.
1106 void
1108 rpcb_gettime(host)
1109 char *host
1110 PREINIT:
1111 time_t timep;
1112 PPCODE:
1113 if( rpcb_gettime( host, &timep ) )
1114 PUSHs(sv_2mortal(newSViv(timep)));
1115 else{
1116 /* Nothing pushed on stack, so an empty
1117 * list is implicitly returned. */
1118 }
1119 Some people may be inclined to include an explicit "return" in the
1121 above XSUB, rather than letting control fall through to the end. In
1122 those situations "XSRETURN_EMPTY" should be used, instead. This will
1123 ensure that the XSUB stack is properly adjusted. Consult perlapi for
1124 other "XSRETURN" macros.
1125 Since "XSRETURN_*" macros can be used with CODE blocks as well, one can
1127 rewrite this example as:
1128 int
1130 rpcb_gettime(host)
1131 char *host
1132 PREINIT:
1133 time_t timep;
1134 CODE:
1135 RETVAL = rpcb_gettime( host, &timep );
1136 if (RETVAL == 0)
1137 XSRETURN_UNDEF;
1138 OUTPUT:
1139 RETVAL
1140 In fact, one can put this check into a POSTCALL: section as well.
1142 Together with PREINIT: simplifications, this leads to:
1143 int
1145 rpcb_gettime(host)
1146 char *host
1147 time_t timep;
1148 POSTCALL:
1149 if (RETVAL == 0)
1150 XSRETURN_UNDEF;
1151 The REQUIRE: Keyword
1153 The REQUIRE: keyword is used to indicate the minimum version of the
1154 xsubpp compiler needed to compile the XS module. An XS module which
1155 contains the following statement will compile with only xsubpp version
1156 1.922 or greater:
1157 REQUIRE: 1.922
1159 The CLEANUP: Keyword
1161 This keyword can be used when an XSUB requires special cleanup
1162 procedures before it terminates. When the CLEANUP: keyword is used it
1163 must follow any CODE:, PPCODE:, or OUTPUT: blocks which are present in
1164 the XSUB. The code specified for the cleanup block will be added as
1165 the last statements in the XSUB.
1166 The POSTCALL: Keyword
1168 This keyword can be used when an XSUB requires special procedures
1169 executed after the C subroutine call is performed. When the POSTCALL:
1170 keyword is used it must precede OUTPUT: and CLEANUP: blocks which are
1171 present in the XSUB.
1172 See examples in "The NO_OUTPUT Keyword" and "Returning Undef And Empty
1174 Lists".
1175 The POSTCALL: block does not make a lot of sense when the C subroutine
1177 call is supplied by user by providing either CODE: or PPCODE: section.
1178 The BOOT: Keyword
1180 The BOOT: keyword is used to add code to the extension's bootstrap
1181 function. The bootstrap function is generated by the xsubpp compiler
1182 and normally holds the statements necessary to register any XSUBs with
1183 Perl. With the BOOT: keyword the programmer can tell the compiler to
1184 add extra statements to the bootstrap function.
1185 This keyword may be used any time after the first MODULE keyword and
1187 should appear on a line by itself. The first blank line after the
1188 keyword will terminate the code block.
1189 BOOT:
1191 # The following message will be printed when the
1192 # bootstrap function executes.
1193 printf("Hello from the bootstrap!\n");
1194 The VERSIONCHECK: Keyword
1196 The VERSIONCHECK: keyword corresponds to xsubpp's "-versioncheck" and
1197 "-noversioncheck" options. This keyword overrides the command line
1198 options. Version checking is enabled by default. When version
1199 checking is enabled the XS module will attempt to verify that its
1200 version matches the version of the PM module.
1201 To enable version checking:
1203 VERSIONCHECK: ENABLE
1205 To disable version checking:
1207 VERSIONCHECK: DISABLE
1209 Note that if the version of the PM module is an NV (a floating point
1211 number), it will be stringified with a possible loss of precision
1212 (currently chopping to nine decimal places) so that it may not match
1213 the version of the XS module anymore. Quoting the $VERSION declaration
1214 to make it a string is recommended if long version numbers are used.
1215 The PROTOTYPES: Keyword
1217 The PROTOTYPES: keyword corresponds to xsubpp's "-prototypes" and
1218 "-noprototypes" options. This keyword overrides the command line
1219 options. Prototypes are enabled by default. When prototypes are
1220 enabled XSUBs will be given Perl prototypes. This keyword may be used
1221 multiple times in an XS module to enable and disable prototypes for
1222 different parts of the module.
1223 To enable prototypes:
1225 PROTOTYPES: ENABLE
1227 To disable prototypes:
1229 PROTOTYPES: DISABLE
1231 The PROTOTYPE: Keyword
1233 This keyword is similar to the PROTOTYPES: keyword above but can be
1234 used to force xsubpp to use a specific prototype for the XSUB. This
1235 keyword overrides all other prototype options and keywords but affects
1236 only the current XSUB. Consult "Prototypes" in perlsub for information
1237 about Perl prototypes.
1238 bool_t
1240 rpcb_gettime(timep, ...)
1241 time_t timep = NO_INIT
1242 PROTOTYPE: $;$
1243 PREINIT:
1244 char *host = "localhost";
1245 CODE:
1246 if( items > 1 )
1247 host = (char *)SvPV_nolen(ST(1));
1248 RETVAL = rpcb_gettime( host, &timep );
1249 OUTPUT:
1250 timep
1251 RETVAL
1252 If the prototypes are enabled, you can disable it locally for a given
1254 XSUB as in the following example:
1255 void
1257 rpcb_gettime_noproto()
1258 PROTOTYPE: DISABLE
1259 ...
1260 The ALIAS: Keyword
1262 The ALIAS: keyword allows an XSUB to have two or more unique Perl names
1263 and to know which of those names was used when it was invoked. The
1264 Perl names may be fully-qualified with package names. Each alias is
1265 given an index. The compiler will setup a variable called "ix" which
1266 contain the index of the alias which was used. When the XSUB is called
1267 with its declared name "ix" will be 0.
1268 The following example will create aliases "FOO::gettime()" and
1270 "BAR::getit()" for this function.
1271 bool_t
1273 rpcb_gettime(host,timep)
1274 char *host
1275 time_t &timep
1276 ALIAS:
1277 FOO::gettime = 1
1278 BAR::getit = 2
1279 INIT:
1280 printf("# ix = %d\n", ix );
1281 OUTPUT:
1282 timep
1283 The OVERLOAD: Keyword
1285 Instead of writing an overloaded interface using pure Perl, you can
1286 also use the OVERLOAD keyword to define additional Perl names for your
1287 functions (like the ALIAS: keyword above). However, the overloaded
1288 functions must be defined with three parameters (except for the
1289 nomethod() function which needs four parameters). If any function has
1290 the OVERLOAD: keyword, several additional lines will be defined in the
1291 c file generated by xsubpp in order to register with the overload
1292 magic.
1293 Since blessed objects are actually stored as RV's, it is useful to use
1295 the typemap features to preprocess parameters and extract the actual SV
1296 stored within the blessed RV. See the sample for T_PTROBJ_SPECIAL
1297 below.
1298 To use the OVERLOAD: keyword, create an XS function which takes three
1300 input parameters ( or use the c style '...' definition) like this:
1301 SV *
1303 cmp (lobj, robj, swap)
1304 My_Module_obj lobj
1305 My_Module_obj robj
1306 IV swap
1307 OVERLOAD: cmp <=>
1308 { /* function defined here */}
1309 In this case, the function will overload both of the three way
1311 comparison operators. For all overload operations using non-alpha
1312 characters, you must type the parameter without quoting, separating
1313 multiple overloads with whitespace. Note that "" (the stringify
1314 overload) should be entered as \"\" (i.e. escaped).
1315 The FALLBACK: Keyword
1317 In addition to the OVERLOAD keyword, if you need to control how Perl
1318 autogenerates missing overloaded operators, you can set the FALLBACK
1319 keyword in the module header section, like this:
1320 MODULE = RPC PACKAGE = RPC
1322 FALLBACK: TRUE
1324 ...
1325 where FALLBACK can take any of the three values TRUE, FALSE, or UNDEF.
1327 If you do not set any FALLBACK value when using OVERLOAD, it defaults
1328 to UNDEF. FALLBACK is not used except when one or more functions using
1329 OVERLOAD have been defined. Please see "fallback" in overload for more
1330 details.
1331 The INTERFACE: Keyword
1333 This keyword declares the current XSUB as a keeper of the given calling
1334 signature. If some text follows this keyword, it is considered as a
1335 list of functions which have this signature, and should be attached to
1336 the current XSUB.
1337 For example, if you have 4 C functions multiply(), divide(), add(),
1339 subtract() all having the signature:
1340 symbolic f(symbolic, symbolic);
1342 you can make them all to use the same XSUB using this:
1344 symbolic
1346 interface_s_ss(arg1, arg2)
1347 symbolic arg1
1348 symbolic arg2
1349 INTERFACE:
1350 multiply divide
1351 add subtract
1352 (This is the complete XSUB code for 4 Perl functions!) Four generated
1354 Perl function share names with corresponding C functions.
1355 The advantage of this approach comparing to ALIAS: keyword is that
1357 there is no need to code a switch statement, each Perl function (which
1358 shares the same XSUB) knows which C function it should call.
1359 Additionally, one can attach an extra function remainder() at runtime
1360 by using
1361 CV *mycv = newXSproto("Symbolic::remainder",
1363 XS_Symbolic_interface_s_ss, __FILE__, "$$");
1364 XSINTERFACE_FUNC_SET(mycv, remainder);
1365 say, from another XSUB. (This example supposes that there was no
1367 INTERFACE_MACRO: section, otherwise one needs to use something else
1368 instead of "XSINTERFACE_FUNC_SET", see the next section.)
1369 The INTERFACE_MACRO: Keyword
1371 This keyword allows one to define an INTERFACE using a different way to
1372 extract a function pointer from an XSUB. The text which follows this
1373 keyword should give the name of macros which would extract/set a
1374 function pointer. The extractor macro is given return type, "CV*", and
1375 "XSANY.any_dptr" for this "CV*". The setter macro is given cv, and the
1376 function pointer.
1377 The default value is "XSINTERFACE_FUNC" and "XSINTERFACE_FUNC_SET". An
1379 INTERFACE keyword with an empty list of functions can be omitted if
1380 INTERFACE_MACRO keyword is used.
1381 Suppose that in the previous example functions pointers for multiply(),
1383 divide(), add(), subtract() are kept in a global C array "fp[]" with
1384 offsets being "multiply_off", "divide_off", "add_off", "subtract_off".
1385 Then one can use
1386 #define XSINTERFACE_FUNC_BYOFFSET(ret,cv,f) \
1388 ((XSINTERFACE_CVT_ANON(ret))fp[CvXSUBANY(cv).any_i32])
1389 #define XSINTERFACE_FUNC_BYOFFSET_set(cv,f) \
1390 CvXSUBANY(cv).any_i32 = CAT2( f, _off )
1391 in C section,
1393 symbolic
1395 interface_s_ss(arg1, arg2)
1396 symbolic arg1
1397 symbolic arg2
1398 INTERFACE_MACRO:
1399 XSINTERFACE_FUNC_BYOFFSET
1400 XSINTERFACE_FUNC_BYOFFSET_set
1401 INTERFACE:
1402 multiply divide
1403 add subtract
1404 in XSUB section.
1406 The INCLUDE: Keyword
1408 This keyword can be used to pull other files into the XS module. The
1409 other files may have XS code. INCLUDE: can also be used to run a
1410 command to generate the XS code to be pulled into the module.
1411 The file Rpcb1.xsh contains our "rpcb_gettime()" function:
1413 bool_t
1415 rpcb_gettime(host,timep)
1416 char *host
1417 time_t &timep
1418 OUTPUT:
1419 timep
1420 The XS module can use INCLUDE: to pull that file into it.
1422 INCLUDE: Rpcb1.xsh
1424 If the parameters to the INCLUDE: keyword are followed by a pipe ("|")
1426 then the compiler will interpret the parameters as a command. This
1427 feature is mildly deprecated in favour of the "INCLUDE_COMMAND:"
1428 directive, as documented below.
1429 INCLUDE: cat Rpcb1.xsh |
1431 Do not use this to run perl: "INCLUDE: perl |" will run the perl that
1433 happens to be the first in your path and not necessarily the same perl
1434 that is used to run "xsubpp". See "The INCLUDE_COMMAND: Keyword".
1435 The INCLUDE_COMMAND: Keyword
1437 Runs the supplied command and includes its output into the current XS
1438 document. "INCLUDE_COMMAND" assigns special meaning to the $^X token in
1439 that it runs the same perl interpreter that is running "xsubpp":
1440 INCLUDE_COMMAND: cat Rpcb1.xsh
1442 INCLUDE_COMMAND: $^X -e ...
1444 The CASE: Keyword
1446 The CASE: keyword allows an XSUB to have multiple distinct parts with
1447 each part acting as a virtual XSUB. CASE: is greedy and if it is used
1448 then all other XS keywords must be contained within a CASE:. This
1449 means nothing may precede the first CASE: in the XSUB and anything
1450 following the last CASE: is included in that case.
1451 A CASE: might switch via a parameter of the XSUB, via the "ix" ALIAS:
1453 variable (see "The ALIAS: Keyword"), or maybe via the "items" variable
1454 (see "Variable-length Parameter Lists"). The last CASE: becomes the
1455 default case if it is not associated with a conditional. The following
1456 example shows CASE switched via "ix" with a function "rpcb_gettime()"
1457 having an alias "x_gettime()". When the function is called as
1458 "rpcb_gettime()" its parameters are the usual "(char *host, time_t
1459 *timep)", but when the function is called as "x_gettime()" its
1460 parameters are reversed, "(time_t *timep, char *host)".
1461 long
1463 rpcb_gettime(a,b)
1464 CASE: ix == 1
1465 ALIAS:
1466 x_gettime = 1
1467 INPUT:
1468 # 'a' is timep, 'b' is host
1469 char *b
1470 time_t a = NO_INIT
1471 CODE:
1472 RETVAL = rpcb_gettime( b, &a );
1473 OUTPUT:
1474 a
1475 RETVAL
1476 CASE:
1477 # 'a' is host, 'b' is timep
1478 char *a
1479 time_t &b = NO_INIT
1480 OUTPUT:
1481 b
1482 RETVAL
1483 That function can be called with either of the following statements.
1485 Note the different argument lists.
1486 $status = rpcb_gettime( $host, $timep );
1488 $status = x_gettime( $timep, $host );
1490 The EXPORT_XSUB_SYMBOLS: Keyword
1492 The EXPORT_XSUB_SYMBOLS: keyword is likely something you will never
1493 need. In perl versions earlier than 5.16.0, this keyword does nothing.
1494 Starting with 5.16, XSUB symbols are no longer exported by default.
1495 That is, they are "static" functions. If you include
1496 EXPORT_XSUB_SYMBOLS: ENABLE
1498 in your XS code, the XSUBs following this line will not be declared
1500 "static". You can later disable this with
1501 EXPORT_XSUB_SYMBOLS: DISABLE
1503 which, again, is the default that you should probably never change.
1505 You cannot use this keyword on versions of perl before 5.16 to make
1506 XSUBs "static".
1507 The & Unary Operator
1509 The "&" unary operator in the INPUT: section is used to tell xsubpp
1510 that it should convert a Perl value to/from C using the C type to the
1511 left of "&", but provide a pointer to this value when the C function is
1512 called.
1513 This is useful to avoid a CODE: block for a C function which takes a
1515 parameter by reference. Typically, the parameter should be not a
1516 pointer type (an "int" or "long" but not an "int*" or "long*").
1517 The following XSUB will generate incorrect C code. The xsubpp compiler
1519 will turn this into code which calls "rpcb_gettime()" with parameters
1520 "(char *host, time_t timep)", but the real "rpcb_gettime()" wants the
1521 "timep" parameter to be of type "time_t*" rather than "time_t".
1522 bool_t
1524 rpcb_gettime(host,timep)
1525 char *host
1526 time_t timep
1527 OUTPUT:
1528 timep
1529 That problem is corrected by using the "&" operator. The xsubpp
1531 compiler will now turn this into code which calls "rpcb_gettime()"
1532 correctly with parameters "(char *host, time_t *timep)". It does this
1533 by carrying the "&" through, so the function call looks like
1534 "rpcb_gettime(host, &timep)".
1535 bool_t
1537 rpcb_gettime(host,timep)
1538 char *host
1539 time_t &timep
1540 OUTPUT:
1541 timep
1542 Inserting POD, Comments and C Preprocessor Directives
1544 C preprocessor directives are allowed within BOOT:, PREINIT: INIT:,
1545 CODE:, PPCODE:, POSTCALL:, and CLEANUP: blocks, as well as outside the
1546 functions. Comments are allowed anywhere after the MODULE keyword.
1547 The compiler will pass the preprocessor directives through untouched
1548 and will remove the commented lines. POD documentation is allowed at
1549 any point, both in the C and XS language sections. POD must be
1550 terminated with a "=cut" command; "xsubpp" will exit with an error if
1551 it does not. It is very unlikely that human generated C code will be
1552 mistaken for POD, as most indenting styles result in whitespace in
1553 front of any line starting with "=". Machine generated XS files may
1554 fall into this trap unless care is taken to ensure that a space breaks
1555 the sequence "\n=".
1556 Comments can be added to XSUBs by placing a "#" as the first non-
1558 whitespace of a line. Care should be taken to avoid making the comment
1559 look like a C preprocessor directive, lest it be interpreted as such.
1560 The simplest way to prevent this is to put whitespace in front of the
1561 "#".
1562 If you use preprocessor directives to choose one of two versions of a
1564 function, use
1565 #if ... version1
1567 #else /* ... version2 */
1568 #endif
1569 and not
1571 #if ... version1
1573 #endif
1574 #if ... version2
1575 #endif
1576 because otherwise xsubpp will believe that you made a duplicate
1578 definition of the function. Also, put a blank line before the
1579 #else/#endif so it will not be seen as part of the function body.
1580 Using XS With C++
1582 If an XSUB name contains "::", it is considered to be a C++ method.
1583 The generated Perl function will assume that its first argument is an
1584 object pointer. The object pointer will be stored in a variable called
1585 THIS. The object should have been created by C++ with the new()
1586 function and should be blessed by Perl with the sv_setref_pv() macro.
1587 The blessing of the object by Perl can be handled by a typemap. An
1588 example typemap is shown at the end of this section.
1589 If the return type of the XSUB includes "static", the method is
1591 considered to be a static method. It will call the C++ function using
1592 the class::method() syntax. If the method is not static the function
1593 will be called using the THIS->method() syntax.
1594 The next examples will use the following C++ class.
1596 class color {
1598 public:
1599 color();
1600 ~color();
1601 int blue();
1602 void set_blue( int );
1603 private:
1605 int c_blue;
1606 };
1607 The XSUBs for the blue() and set_blue() methods are defined with the
1609 class name but the parameter for the object (THIS, or "self") is
1610 implicit and is not listed.
1611 int
1613 color::blue()
1614 void
1616 color::set_blue( val )
1617 int val
1618 Both Perl functions will expect an object as the first parameter. In
1620 the generated C++ code the object is called "THIS", and the method call
1621 will be performed on this object. So in the C++ code the blue() and
1622 set_blue() methods will be called as this:
1623 RETVAL = THIS->blue();
1625 THIS->set_blue( val );
1627 You could also write a single get/set method using an optional
1629 argument:
1630 int
1632 color::blue( val = NO_INIT )
1633 int val
1634 PROTOTYPE $;$
1635 CODE:
1636 if (items > 1)
1637 THIS->set_blue( val );
1638 RETVAL = THIS->blue();
1639 OUTPUT:
1640 RETVAL
1641 If the function's name is DESTROY then the C++ "delete" function will
1643 be called and "THIS" will be given as its parameter. The generated C++
1644 code for
1645 void
1647 color::DESTROY()
1648 will look like this:
1650 color *THIS = ...; // Initialized as in typemap
1652 delete THIS;
1654 If the function's name is new then the C++ "new" function will be
1656 called to create a dynamic C++ object. The XSUB will expect the class
1657 name, which will be kept in a variable called "CLASS", to be given as
1658 the first argument.
1659 color *
1661 color::new()
1662 The generated C++ code will call "new".
1664 RETVAL = new color();
1666 The following is an example of a typemap that could be used for this
1668 C++ example.
1669 TYPEMAP
1671 color * O_OBJECT
1672 OUTPUT
1674 # The Perl object is blessed into 'CLASS', which should be a
1675 # char* having the name of the package for the blessing.
1676 O_OBJECT
1677 sv_setref_pv( $arg, CLASS, (void*)$var );
1678 INPUT
1680 O_OBJECT
1681 if( sv_isobject($arg) && (SvTYPE(SvRV($arg)) == SVt_PVMG) )
1682 $var = ($type)SvIV((SV*)SvRV( $arg ));
1683 else{
1684 warn( \"${Package}::$func_name() -- $var is not a blessed SV reference\" );
1685 XSRETURN_UNDEF;
1686 }
1687 Interface Strategy
1689 When designing an interface between Perl and a C library a straight
1690 translation from C to XS (such as created by "h2xs -x") is often
1691 sufficient. However, sometimes the interface will look very C-like and
1692 occasionally nonintuitive, especially when the C function modifies one
1693 of its parameters, or returns failure inband (as in "negative return
1694 values mean failure"). In cases where the programmer wishes to create
1695 a more Perl-like interface the following strategy may help to identify
1696 the more critical parts of the interface.
1697 Identify the C functions with input/output or output parameters. The
1699 XSUBs for these functions may be able to return lists to Perl.
1700 Identify the C functions which use some inband info as an indication of
1702 failure. They may be candidates to return undef or an empty list in
1703 case of failure. If the failure may be detected without a call to the
1704 C function, you may want to use an INIT: section to report the failure.
1705 For failures detectable after the C function returns one may want to
1706 use a POSTCALL: section to process the failure. In more complicated
1707 cases use CODE: or PPCODE: sections.
1708 If many functions use the same failure indication based on the return
1710 value, you may want to create a special typedef to handle this
1711 situation. Put
1712 typedef int negative_is_failure;
1714 near the beginning of XS file, and create an OUTPUT typemap entry for
1716 "negative_is_failure" which converts negative values to "undef", or
1717 maybe croak()s. After this the return value of type
1718 "negative_is_failure" will create more Perl-like interface.
1719 Identify which values are used by only the C and XSUB functions
1721 themselves, say, when a parameter to a function should be a contents of
1722 a global variable. If Perl does not need to access the contents of the
1723 value then it may not be necessary to provide a translation for that
1724 value from C to Perl.
1725 Identify the pointers in the C function parameter lists and return
1727 values. Some pointers may be used to implement input/output or output
1728 parameters, they can be handled in XS with the "&" unary operator, and,
1729 possibly, using the NO_INIT keyword. Some others will require handling
1730 of types like "int *", and one needs to decide what a useful Perl
1731 translation will do in such a case. When the semantic is clear, it is
1732 advisable to put the translation into a typemap file.
1733 Identify the structures used by the C functions. In many cases it may
1735 be helpful to use the T_PTROBJ typemap for these structures so they can
1736 be manipulated by Perl as blessed objects. (This is handled
1737 automatically by "h2xs -x".)
1738 If the same C type is used in several different contexts which require
1740 different translations, "typedef" several new types mapped to this C
1741 type, and create separate typemap entries for these new types. Use
1742 these types in declarations of return type and parameters to XSUBs.
1743 Perl Objects And C Structures
1745 When dealing with C structures one should select either T_PTROBJ or
1746 T_PTRREF for the XS type. Both types are designed to handle pointers
1747 to complex objects. The T_PTRREF type will allow the Perl object to be
1748 unblessed while the T_PTROBJ type requires that the object be blessed.
1749 By using T_PTROBJ one can achieve a form of type-checking because the
1750 XSUB will attempt to verify that the Perl object is of the expected
1751 type.
1752 The following XS code shows the getnetconfigent() function which is
1754 used with ONC+ TIRPC. The getnetconfigent() function will return a
1755 pointer to a C structure and has the C prototype shown below. The
1756 example will demonstrate how the C pointer will become a Perl
1757 reference. Perl will consider this reference to be a pointer to a
1758 blessed object and will attempt to call a destructor for the object. A
1759 destructor will be provided in the XS source to free the memory used by
1760 getnetconfigent(). Destructors in XS can be created by specifying an
1761 XSUB function whose name ends with the word DESTROY. XS destructors
1762 can be used to free memory which may have been malloc'd by another
1763 XSUB.
1764 struct netconfig *getnetconfigent(const char *netid);
1766 A "typedef" will be created for "struct netconfig". The Perl object
1768 will be blessed in a class matching the name of the C type, with the
1769 tag "Ptr" appended, and the name should not have embedded spaces if it
1770 will be a Perl package name. The destructor will be placed in a class
1771 corresponding to the class of the object and the PREFIX keyword will be
1772 used to trim the name to the word DESTROY as Perl will expect.
1773 typedef struct netconfig Netconfig;
1775 MODULE = RPC PACKAGE = RPC
1777 Netconfig *
1779 getnetconfigent(netid)
1780 char *netid
1781 MODULE = RPC PACKAGE = NetconfigPtr PREFIX = rpcb_
1783 void
1785 rpcb_DESTROY(netconf)
1786 Netconfig *netconf
1787 CODE:
1788 printf("Now in NetconfigPtr::DESTROY\n");
1789 free( netconf );
1790 This example requires the following typemap entry. Consult
1792 perlxstypemap for more information about adding new typemaps for an
1793 extension.
1794 TYPEMAP
1796 Netconfig * T_PTROBJ
1797 This example will be used with the following Perl statements.
1799 use RPC;
1801 $netconf = getnetconfigent("udp");
1802 When Perl destroys the object referenced by $netconf it will send the
1804 object to the supplied XSUB DESTROY function. Perl cannot determine,
1805 and does not care, that this object is a C struct and not a Perl
1806 object. In this sense, there is no difference between the object
1807 created by the getnetconfigent() XSUB and an object created by a normal
1808 Perl subroutine.
1809 Safely Storing Static Data in XS
1811 Starting with Perl 5.8, a macro framework has been defined to allow
1812 static data to be safely stored in XS modules that will be accessed
1813 from a multi-threaded Perl.
1814 Although primarily designed for use with multi-threaded Perl, the
1816 macros have been designed so that they will work with non-threaded Perl
1817 as well.
1818 It is therefore strongly recommended that these macros be used by all
1820 XS modules that make use of static data.
1821 The easiest way to get a template set of macros to use is by specifying
1823 the "-g" ("--global") option with h2xs (see h2xs).
1824 Below is an example module that makes use of the macros.
1826 #include "EXTERN.h"
1828 #include "perl.h"
1829 #include "XSUB.h"
1830 /* Global Data */
1832 #define MY_CXT_KEY "BlindMice::_guts" XS_VERSION
1834 typedef struct {
1836 int count;
1837 char name[3][100];
1838 } my_cxt_t;
1839 START_MY_CXT
1841 MODULE = BlindMice PACKAGE = BlindMice
1843 BOOT:
1845 {
1846 MY_CXT_INIT;
1847 MY_CXT.count = 0;
1848 strcpy(MY_CXT.name[0], "None");
1849 strcpy(MY_CXT.name[1], "None");
1850 strcpy(MY_CXT.name[2], "None");
1851 }
1852 int
1854 newMouse(char * name)
1855 char * name;
1856 PREINIT:
1857 dMY_CXT;
1858 CODE:
1859 if (MY_CXT.count >= 3) {
1860 warn("Already have 3 blind mice");
1861 RETVAL = 0;
1862 }
1863 else {
1864 RETVAL = ++ MY_CXT.count;
1865 strcpy(MY_CXT.name[MY_CXT.count - 1], name);
1866 }
1867 char *
1869 get_mouse_name(index)
1870 int index
1871 CODE:
1872 dMY_CXT;
1873 RETVAL = MY_CXT.lives ++;
1874 if (index > MY_CXT.count)
1875 croak("There are only 3 blind mice.");
1876 else
1877 RETVAL = newSVpv(MY_CXT.name[index - 1]);
1878 void
1880 CLONE(...)
1881 CODE:
1882 MY_CXT_CLONE;
1883 REFERENCE
1885 MY_CXT_KEY
1887 This macro is used to define a unique key to refer to the static
1888 data for an XS module. The suggested naming scheme, as used by
1889 h2xs, is to use a string that consists of the module name, the
1890 string "::_guts" and the module version number.
1891 #define MY_CXT_KEY "MyModule::_guts" XS_VERSION
1893 typedef my_cxt_t
1895 This struct typedef must always be called "my_cxt_t". The other
1896 "CXT*" macros assume the existence of the "my_cxt_t" typedef name.
1897 Declare a typedef named "my_cxt_t" that is a structure that
1899 contains all the data that needs to be interpreter-local.
1900 typedef struct {
1902 int some_value;
1903 } my_cxt_t;
1904 START_MY_CXT
1906 Always place the START_MY_CXT macro directly after the declaration
1907 of "my_cxt_t".
1908 MY_CXT_INIT
1910 The MY_CXT_INIT macro initialises storage for the "my_cxt_t"
1911 struct.
1912 It must be called exactly once, typically in a BOOT: section. If
1914 you are maintaining multiple interpreters, it should be called
1915 once in each interpreter instance, except for interpreters cloned
1916 from existing ones. (But see "MY_CXT_CLONE" below.)
1917 dMY_CXT
1919 Use the dMY_CXT macro (a declaration) in all the functions that
1920 access MY_CXT.
1921 MY_CXT
1923 Use the MY_CXT macro to access members of the "my_cxt_t" struct.
1924 For example, if "my_cxt_t" is
1925 typedef struct {
1927 int index;
1928 } my_cxt_t;
1929 then use this to access the "index" member
1931 dMY_CXT;
1933 MY_CXT.index = 2;
1934 aMY_CXT/pMY_CXT
1936 "dMY_CXT" may be quite expensive to calculate, and to avoid the
1937 overhead of invoking it in each function it is possible to pass
1938 the declaration onto other functions using the "aMY_CXT"/"pMY_CXT"
1939 macros, eg
1940 void sub1() {
1942 dMY_CXT;
1943 MY_CXT.index = 1;
1944 sub2(aMY_CXT);
1945 }
1946 void sub2(pMY_CXT) {
1948 MY_CXT.index = 2;
1949 }
1950 Analogously to "pTHX", there are equivalent forms for when the
1952 macro is the first or last in multiple arguments, where an
1953 underscore represents a comma, i.e. "_aMY_CXT", "aMY_CXT_",
1954 "_pMY_CXT" and "pMY_CXT_".
1955 MY_CXT_CLONE
1957 By default, when a new interpreter is created as a copy of an
1958 existing one (eg via "threads->create()"), both interpreters share
1959 the same physical my_cxt_t structure. Calling "MY_CXT_CLONE"
1960 (typically via the package's "CLONE()" function), causes a byte-
1961 for-byte copy of the structure to be taken, and any future dMY_CXT
1962 will cause the copy to be accessed instead.
1963 MY_CXT_INIT_INTERP(my_perl)
1965 dMY_CXT_INTERP(my_perl)
1966 These are versions of the macros which take an explicit
1967 interpreter as an argument.
1968 Note that these macros will only work together within the same source
1970 file; that is, a dMY_CTX in one source file will access a different
1971 structure than a dMY_CTX in another source file.
1972 Thread-aware system interfaces
1974 Starting from Perl 5.8, in C/C++ level Perl knows how to wrap
1975 system/library interfaces that have thread-aware versions (e.g.
1976 getpwent_r()) into frontend macros (e.g. getpwent()) that correctly
1977 handle the multithreaded interaction with the Perl interpreter. This
1978 will happen transparently, the only thing you need to do is to
1979 instantiate a Perl interpreter.
1980 This wrapping happens always when compiling Perl core source (PERL_CORE
1982 is defined) or the Perl core extensions (PERL_EXT is defined). When
1983 compiling XS code outside of Perl core the wrapping does not take
1984 place. Note, however, that intermixing the _r-forms (as Perl compiled
1985 for multithreaded operation will do) and the _r-less forms is neither
1986 well-defined (inconsistent results, data corruption, or even crashes
1987 become more likely), nor is it very portable.
1988
1990 File "RPC.xs": Interface to some ONC+ RPC bind library functions.
1991 #include "EXTERN.h"
1993 #include "perl.h"
1994 #include "XSUB.h"
1995 #include <rpc/rpc.h>
1997 typedef struct netconfig Netconfig;
1999 MODULE = RPC PACKAGE = RPC
2001 SV *
2003 rpcb_gettime(host="localhost")
2004 char *host
2005 PREINIT:
2006 time_t timep;
2007 CODE:
2008 ST(0) = sv_newmortal();
2009 if( rpcb_gettime( host, &timep ) )
2010 sv_setnv( ST(0), (double)timep );
2011 Netconfig *
2013 getnetconfigent(netid="udp")
2014 char *netid
2015 MODULE = RPC PACKAGE = NetconfigPtr PREFIX = rpcb_
2017 void
2019 rpcb_DESTROY(netconf)
2020 Netconfig *netconf
2021 CODE:
2022 printf("NetconfigPtr::DESTROY\n");
2023 free( netconf );
2024 File "typemap": Custom typemap for RPC.xs. (cf. perlxstypemap)
2026 TYPEMAP
2028 Netconfig * T_PTROBJ
2029 File "RPC.pm": Perl module for the RPC extension.
2031 package RPC;
2033 require Exporter;
2035 require DynaLoader;
2036 @ISA = qw(Exporter DynaLoader);
2037 @EXPORT = qw(rpcb_gettime getnetconfigent);
2038 bootstrap RPC;
2040 1;
2041 File "rpctest.pl": Perl test program for the RPC extension.
2043 use RPC;
2045 $netconf = getnetconfigent();
2047 $a = rpcb_gettime();
2048 print "time = $a\n";
2049 print "netconf = $netconf\n";
2050 $netconf = getnetconfigent("tcp");
2052 $a = rpcb_gettime("poplar");
2053 print "time = $a\n";
2054 print "netconf = $netconf\n";
2055
2057 This document covers features supported by "ExtUtils::ParseXS" (also
2058 known as "xsubpp") 3.13_01.
2059
2061 Originally written by Dean Roehrich <roehrich@cray.com>.
2062 Maintained since 1996 by The Perl Porters <perlbug@perl.org>.
2064perl v5.16.3 2013-03-04 PERLXS(1)