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
12 interface between Perl and C code (or a C library) which one wishes to
13 use with Perl. The XS interface is combined with the library to create
14 a new library which can then be either dynamically loaded or statically
15 linked into perl. The XS interface description is written in the XS
16 language and is the core component of the Perl extension interface.
17 An XSUB forms the basic unit of the XS interface. After compilation by
19 the xsubpp compiler, each XSUB amounts to a C function definition which
20 will provide the glue between Perl calling conventions and C calling
21 conventions.
22 The glue code pulls the arguments from the Perl stack, converts these
24 Perl values to the formats expected by a C function, call this C func‐
25 tion, transfers the return values of the C function back to Perl.
26 Return values here may be a conventional C return value or any C func‐
27 tion arguments that may serve as output parameters. These return val‐
28 ues may be passed back to Perl either by putting them on the Perl
29 stack, or by modifying the arguments supplied from the Perl side.
30 The above is a somewhat simplified view of what really happens. Since
32 Perl allows more flexible calling conventions than C, XSUBs may do much
33 more in practice, such as checking input parameters for validity,
34 throwing exceptions (or returning undef/empty list) if the return value
35 from the C function indicates failure, calling different C functions
36 based on numbers and types of the arguments, providing an object-ori‐
37 ented interface, etc.
38 Of course, one could write such glue code directly in C. However, this
40 would be a tedious task, especially if one needs to write glue for mul‐
41 tiple C functions, and/or one is not familiar enough with the Perl
42 stack discipline and other such arcana. XS comes to the rescue here:
43 instead of writing this glue C code in long-hand, one can write a more
44 concise short-hand description of what should be done by the glue, and
45 let the XS compiler xsubpp handle the rest.
46 The XS language allows one to describe the mapping between how the C
48 routine is used, and how the corresponding Perl routine is used. It
49 also allows creation of Perl routines which are directly translated to
50 C code and which are not related to a pre-existing C function. In
51 cases when the C interface coincides with the Perl interface, the XSUB
52 declaration is almost identical to a declaration of a C function (in
53 K&R style). In such circumstances, there is another tool called "h2xs"
54 that is able to translate an entire C header file into a corresponding
55 XS file that will provide glue to the functions/macros described in the
56 header file.
57 The XS compiler is called xsubpp. This compiler creates the constructs
59 necessary to let an XSUB manipulate Perl values, and creates the glue
60 necessary to let Perl call the XSUB. The compiler uses typemaps to
61 determine how to map C function parameters and output values to Perl
62 values and back. The default typemap (which comes with Perl) handles
63 many common C types. A supplementary typemap may also be needed to
64 handle any special structures and types for the library being linked.
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 defini‐
68 tions may follow this line. The "language" used in this part of the
69 file is usually referred to as the XS language. xsubpp recognizes and
70 skips POD (see perlpod) in both the C and XS language sections, which
71 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
82 interface between Perl and the ONC+ RPC bind library functions. The
83 rpcb_gettime() function is used to demonstrate many features of the XS
84 language. This function has two parameters; the first is an input
85 parameter and the second is an output parameter. The function also
86 returns a status value.
87 bool_t rpcb_gettime(const char *host, time_t *timep);
89 From C this function will be called with the following statements.
91 #include <rpc/rpc.h>
93 bool_t status;
94 time_t timep;
95 status = rpcb_gettime( "localhost", &timep );
96 If an XSUB is created to offer a direct translation between this func‐
98 tion and Perl, then this XSUB will be used from Perl with the following
99 code. The $status and $timep variables will contain the output of the
100 function.
101 use RPC;
103 $status = rpcb_gettime( "localhost", $timep );
104 The following XS file shows an XS subroutine, or XSUB, which demon‐
106 strates one possible interface to the rpcb_gettime() function. This
107 XSUB represents a direct translation between C and Perl and so pre‐
108 serves the interface even from Perl. This XSUB will be invoked from
109 Perl with the usage shown above. Note that the first three #include
110 statements, for "EXTERN.h", "perl.h", and "XSUB.h", will always be
111 present at the beginning of an XS file. This approach and others will
112 be expanded later in this document.
113 #include "EXTERN.h"
115 #include "perl.h"
116 #include "XSUB.h"
117 #include <rpc/rpc.h>
118 MODULE = RPC PACKAGE = RPC
120 bool_t
122 rpcb_gettime(host,timep)
123 char *host
124 time_t &timep
125 OUTPUT:
126 timep
127 Any extension to Perl, including those containing XSUBs, should have a
129 Perl module to serve as the bootstrap which pulls the extension into
130 Perl. This module will export the extension's functions and variables
131 to the Perl program and will cause the extension's XSUBs to be linked
132 into Perl. The following module will be used for most of the examples
133 in this document and should be used from Perl with the "use" command as
134 shown earlier. Perl modules are explained in more detail later in this
135 document.
136 package RPC;
138 require Exporter;
140 require DynaLoader;
141 @ISA = qw(Exporter DynaLoader);
142 @EXPORT = qw( rpcb_gettime );
143 bootstrap RPC;
145 1;
146 Throughout this document a variety of interfaces to the rpcb_gettime()
148 XSUB will be explored. The XSUBs will take their parameters in differ‐
149 ent orders or will take different numbers of parameters. In each case
150 the XSUB is an abstraction between Perl and the real C rpcb_gettime()
151 function, and the XSUB must always ensure that the real rpcb_gettime()
152 function is called with the correct parameters. This abstraction will
153 allow the programmer to create a more Perl-like interface to the C
154 function.
155 The Anatomy of an XSUB
157 The simplest XSUBs consist of 3 parts: a description of the return
159 value, the name of the XSUB routine and the names of its arguments, and
160 a description of types or formats of the arguments.
161 The following XSUB allows a Perl program to access a C library function
163 called sin(). The XSUB will imitate the C function which takes a sin‐
164 gle argument and returns a single value.
165 double
167 sin(x)
168 double x
169 Optionally, one can merge the description of types and the list of
171 argument names, rewriting this as
172 double
174 sin(double x)
175 This makes this XSUB look similar to an ANSI C declaration. An
177 optional semicolon is allowed after the argument list, as in
178 double
180 sin(double x);
181 Parameters with C pointer types can have different semantic: C func‐
183 tions with similar declarations
184 bool string_looks_as_a_number(char *s);
186 bool make_char_uppercase(char *c);
187 are used in absolutely incompatible manner. Parameters to these func‐
189 tions could be described xsubpp like this:
190 char * s
192 char &c
193 Both these XS declarations correspond to the "char*" C type, but they
195 have different semantics, see "The & Unary Operator".
196 It is convenient to think that the indirection operator "*" should be
198 considered as a part of the type and the address operator "&" should be
199 considered part of the variable. See "The Typemap" for more info about
200 handling qualifiers and unary operators in C types.
201 The function name and the return type must be placed on separate lines
203 and should be flush left-adjusted.
204 INCORRECT CORRECT
206 double sin(x) double
208 double x sin(x)
209 double x
210 The rest of the function description may be indented or left-adjusted.
212 The following example shows a function with its body left-adjusted.
213 Most examples in this document will indent the body for better read‐
214 ability.
215 CORRECT
217 double
219 sin(x)
220 double x
221 More complicated XSUBs may contain many other sections. Each section
223 of an XSUB starts with the corresponding keyword, such as INIT: or
224 CLEANUP:. However, the first two lines of an XSUB always contain the
225 same data: descriptions of the return type and the names of the func‐
226 tion and its parameters. Whatever immediately follows these is consid‐
227 ered to be an INPUT: section unless explicitly marked with another key‐
228 word. (See "The INPUT: Keyword".)
229 An XSUB section continues until another section-start keyword is found.
231 The Argument Stack
233 The Perl argument stack is used to store the values which are sent as
235 parameters to the XSUB and to store the XSUB's return value(s). In
236 reality all Perl functions (including non-XSUB ones) keep their values
237 on this stack all the same time, each limited to its own range of posi‐
238 tions on the stack. In this document the first position on that stack
239 which belongs to the active function will be referred to as position 0
240 for that function.
241 XSUBs refer to their stack arguments with the macro ST(x), where x
243 refers to a position in this XSUB's part of the stack. Position 0 for
244 that function would be known to the XSUB as ST(0). The XSUB's incoming
245 parameters and outgoing return values always begin at ST(0). For many
246 simple cases the xsubpp compiler will generate the code necessary to
247 handle the argument stack by embedding code fragments found in the
248 typemaps. In more complex cases the programmer must supply the code.
249 The RETVAL Variable
251 The RETVAL variable is a special C variable that is declared automati‐
253 cally for you. The C type of RETVAL matches the return type of the C
254 library function. The xsubpp compiler will declare this variable in
255 each XSUB with non-"void" return type. By default the generated C
256 function will use RETVAL to hold the return value of the C library
257 function being called. In simple cases the value of RETVAL will be
258 placed in ST(0) of the argument stack where it can be received by Perl
259 as the return value of the XSUB.
260 If the XSUB has a return type of "void" then the compiler will not
262 declare a RETVAL variable for that function. When using a PPCODE: sec‐
263 tion no manipulation of the RETVAL variable is required, the section
264 may use direct stack manipulation to place output values on the stack.
265 If PPCODE: directive is not used, "void" return value should be used
267 only for subroutines which do not return a value, even if CODE: direc‐
268 tive is used which sets ST(0) explicitly.
269 Older versions of this document recommended to use "void" return value
271 in such cases. It was discovered that this could lead to segfaults in
272 cases when XSUB was truly "void". This practice is now deprecated, and
273 may be not supported at some future version. Use the return value "SV
274 *" in such cases. (Currently "xsubpp" contains some heuristic code
275 which tries to disambiguate between "truly-void" and "old-prac‐
276 tice-declared-as-void" functions. Hence your code is at mercy of this
277 heuristics unless you use "SV *" as return value.)
278 Returning SVs, AVs and HVs through RETVAL
280 When you're using RETVAL to return an "SV *", there's some magic going
282 on behind the scenes that should be mentioned. When you're manipulating
283 the argument stack using the ST(x) macro, for example, you usually have
284 to pay special attention to reference counts. (For more about reference
285 counts, see perlguts.) To make your life easier, the typemap file auto‐
286 matically makes "RETVAL" mortal when you're returning an "SV *". Thus,
287 the following two XSUBs are more or less equivalent:
288 void
290 alpha()
291 PPCODE:
292 ST(0) = newSVpv("Hello World",0);
293 sv_2mortal(ST(0));
294 XSRETURN(1);
295 SV *
297 beta()
298 CODE:
299 RETVAL = newSVpv("Hello World",0);
300 OUTPUT:
301 RETVAL
302 This is quite useful as it usually improves readability. While this
304 works fine for an "SV *", it's unfortunately not as easy to have "AV *"
305 or "HV *" as a return value. You should be able to write:
306 AV *
308 array()
309 CODE:
310 RETVAL = newAV();
311 /* do something with RETVAL */
312 OUTPUT:
313 RETVAL
314 But due to an unfixable bug (fixing it would break lots of existing
316 CPAN modules) in the typemap file, the reference count of the "AV *" is
317 not properly decremented. Thus, the above XSUB would leak memory when‐
318 ever it is being called. The same problem exists for "HV *".
319 When you're returning an "AV *" or a "HV *", you have make sure their
321 reference count is decremented by making the AV or HV mortal:
322 AV *
324 array()
325 CODE:
326 RETVAL = newAV();
327 sv_2mortal((SV*)RETVAL);
328 /* do something with RETVAL */
329 OUTPUT:
330 RETVAL
331 And also remember that you don't have to do this for an "SV *".
333 The MODULE Keyword
335 The MODULE keyword is used to start the XS code and to specify the
337 package of the functions which are being defined. All text preceding
338 the first MODULE keyword is considered C code and is passed through to
339 the output with POD stripped, but otherwise untouched. Every XS module
340 will have a bootstrap function which is used to hook the XSUBs into
341 Perl. The package name of this bootstrap function will match the value
342 of the last MODULE statement in the XS source files. The value of MOD‐
343 ULE should always remain constant within the same XS file, though this
344 is not required.
345 The following example will start the XS code and will place all func‐
347 tions in a package named RPC.
348 MODULE = RPC
350 The PACKAGE Keyword
352 When functions within an XS source file must be separated into packages
354 the PACKAGE keyword should be used. This keyword is used with the MOD‐
355 ULE keyword and must follow immediately after it when used.
356 MODULE = RPC PACKAGE = RPC
358 [ XS code in package RPC ]
360 MODULE = RPC PACKAGE = RPCB
362 [ XS code in package RPCB ]
364 MODULE = RPC PACKAGE = RPC
366 [ XS code in package RPC ]
368 The same package name can be used more than once, allowing for non-con‐
370 tiguous code. This is useful if you have a stronger ordering principle
371 than package names.
372 Although this keyword is optional and in some cases provides redundant
374 information it should always be used. This keyword will ensure that
375 the XSUBs appear in the desired package.
376 The PREFIX Keyword
378 The PREFIX keyword designates prefixes which should be removed from the
380 Perl function names. If the C function is "rpcb_gettime()" and the
381 PREFIX value is "rpcb_" then Perl will see this function as "get‐
382 time()".
383 This keyword should follow the PACKAGE keyword when used. If PACKAGE
385 is not used then PREFIX should follow the MODULE keyword.
386 MODULE = RPC PREFIX = rpc_
388 MODULE = RPC PACKAGE = RPCB PREFIX = rpcb_
390 The OUTPUT: Keyword
392 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 desig‐
398 nated as an output value. For more complex functions the xsubpp com‐
399 piler will need help to determine which variables are output variables.
400 This keyword will normally be used to complement the CODE: keyword.
402 The RETVAL variable is not recognized as an output variable when the
403 CODE: keyword is present. The OUTPUT: keyword is used in this situa‐
404 tion to tell the compiler that RETVAL really is an output variable.
405 The OUTPUT: keyword can also be used to indicate that function parame‐
407 ters are output variables. This may be necessary when a parameter has
408 been modified within the function and the programmer would like the
409 update to be seen by Perl.
410 bool_t
412 rpcb_gettime(host,timep)
413 char *host
414 time_t &timep
415 OUTPUT:
416 timep
417 The OUTPUT: keyword will also allow an output parameter to be mapped to
419 a matching piece of code rather than to a typemap.
420 bool_t
422 rpcb_gettime(host,timep)
423 char *host
424 time_t &timep
425 OUTPUT:
426 timep sv_setnv(ST(1), (double)timep);
427 xsubpp emits an automatic "SvSETMAGIC()" for all parameters in the OUT‐
429 PUT section of the XSUB, except RETVAL. This is the usually desired
430 behavior, as it takes care of properly invoking 'set' magic on output
431 parameters (needed for hash or array element parameters that must be
432 created if they didn't exist). If for some reason, this behavior is
433 not desired, the OUTPUT section may contain a "SETMAGIC: DISABLE" line
434 to disable it for the remainder of the parameters in the OUTPUT sec‐
435 tion. Likewise, "SETMAGIC: ENABLE" can be used to reenable it for the
436 remainder of the OUTPUT section. See perlguts for more details about
437 'set' magic.
438 The NO_OUTPUT Keyword
440 The NO_OUTPUT can be placed as the first token of the XSUB. This key‐
442 word indicates that while the C subroutine we provide an interface to
443 has a non-"void" return type, the return value of this C subroutine
444 should not be returned from the generated Perl subroutine.
445 With this keyword present "The RETVAL Variable" is created, and in the
447 generated call to the subroutine this variable is assigned to, but the
448 value of this variable is not going to be used in the auto-generated
449 code.
450 This keyword makes sense only if "RETVAL" is going to be accessed by
452 the user-supplied code. It is especially useful to make a function
453 interface more Perl-like, especially when the C return value is just an
454 error condition indicator. For example,
455 NO_OUTPUT int
457 delete_file(char *name)
458 POSTCALL:
459 if (RETVAL != 0)
460 croak("Error %d while deleting file '%s'", RETVAL, name);
461 Here the generated XS function returns nothing on success, and will
463 die() with a meaningful error message on error.
464 The CODE: Keyword
466 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: sec‐
470 tion.
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
492 before the compiler generates the call to the C function. Unlike the
493 CODE: keyword above, this keyword does not affect the way the compiler
494 handles RETVAL.
495 bool_t
497 rpcb_gettime(host,timep)
498 char *host
499 time_t &timep
500 INIT:
501 printf("# Host is %s\n", host );
502 OUTPUT:
503 timep
504 Another use for the INIT: section is to check for preconditions before
506 making a call to the C function:
507 long long
509 lldiv(a,b)
510 long long a
511 long long b
512 INIT:
513 if (a == 0 && b == 0)
514 XSRETURN_UNDEF;
515 if (b == 0)
516 croak("lldiv: cannot divide by 0");
517 The NO_INIT Keyword
519 The NO_INIT keyword is used to indicate that a function parameter is
521 being used only as an output value. The xsubpp compiler will normally
522 generate code to read the values of all function parameters from the
523 argument stack and assign them to C variables upon entry to the func‐
524 tion. NO_INIT will tell the compiler that some parameters will be used
525 for output rather than for input and that they will be handled before
526 the function terminates.
527 The following example shows a variation of the rpcb_gettime() function.
529 This function uses the timep variable only as an output variable and
530 does not care about its initial contents.
531 bool_t
533 rpcb_gettime(host,timep)
534 char *host
535 time_t &timep = NO_INIT
536 OUTPUT:
537 timep
538 Initializing Function Parameters
540 C function parameters are normally initialized with their values from
542 the argument stack (which in turn contains the parameters that were
543 passed to the XSUB from Perl). The typemaps contain the code segments
544 which are used to translate the Perl values to the C parameters. The
545 programmer, however, is allowed to override the typemaps and supply
546 alternate (or additional) initialization code. Initialization code
547 starts with the first "=", ";" or "+" on a line in the INPUT: section.
548 The only exception happens if this ";" terminates the line, then this
549 ";" is quietly ignored.
550 The following code demonstrates how to supply initialization code for
552 function parameters. The initialization code is eval'd within double
553 quotes by the compiler before it is added to the output so anything
554 which should be interpreted literally [mainly "$", "@", or "\\"] must
555 be protected with backslashes. The variables $var, $arg, and $type can
556 be used as in typemaps.
557 bool_t
559 rpcb_gettime(host,timep)
560 char *host = (char *)SvPV($arg,PL_na);
561 time_t &timep = 0;
562 OUTPUT:
563 timep
564 This should not be used to supply default values for parameters. One
566 would normally use this when a function parameter must be processed by
567 another library function before it can be used. Default parameters are
568 covered in the next section.
569 If the initialization begins with "=", then it is output in the decla‐
571 ration for the input variable, replacing the initialization supplied by
572 the typemap. If the initialization begins with ";" or "+", then it is
573 performed after all of the input variables have been declared. In the
574 ";" case the initialization normally supplied by the typemap is not
575 performed. For the "+" case, the declaration for the variable will
576 include the initialization from the typemap. A global variable, %v, is
577 available for the truly rare case where information from one initial‐
578 ization is needed in another initialization.
579 Here's a truly obscure example:
581 bool_t
583 rpcb_gettime(host,timep)
584 time_t &timep; /* \$v{timep}=@{[$v{timep}=$arg]} */
585 char *host + SvOK($v{timep}) ? SvPV($arg,PL_na) : NULL;
586 OUTPUT:
587 timep
588 The construct "\$v{timep}=@{[$v{timep}=$arg]}" used in the above exam‐
590 ple has a two-fold purpose: first, when this line is processed by
591 xsubpp, the Perl snippet "$v{timep}=$arg" is evaluated. Second, the
592 text of the evaluated snippet is output into the generated C file
593 (inside a C comment)! During the processing of "char *host" line, $arg
594 will evaluate to ST(0), and $v{timep} will evaluate to ST(1).
595 Default Parameter Values
597 Default values for XSUB arguments can be specified by placing an
599 assignment statement in the parameter list. The default value may be a
600 number, a string or the special string "NO_INIT". Defaults should
601 always be used on the right-most parameters only.
602 To allow the XSUB for rpcb_gettime() to have a default host value the
604 parameters to the XSUB could be rearranged. The XSUB will then call
605 the real rpcb_gettime() function with the parameters in the correct
606 order. This XSUB can be called from Perl with either of the following
607 statements:
608 $status = rpcb_gettime( $timep, $host );
610 $status = rpcb_gettime( $timep );
612 The XSUB will look like the code which follows. A CODE: block is
614 used to call the real rpcb_gettime() function with the parameters in
615 the correct order for that function.
616 bool_t
618 rpcb_gettime(timep,host="localhost")
619 char *host
620 time_t timep = NO_INIT
621 CODE:
622 RETVAL = rpcb_gettime( host, &timep );
623 OUTPUT:
624 timep
625 RETVAL
626 The PREINIT: Keyword
628 The PREINIT: keyword allows extra variables to be declared immediately
630 before or after the declarations of the parameters from the INPUT: sec‐
631 tion are emitted.
632 If a variable is declared inside a CODE: section it will follow any
634 typemap code that is emitted for the input parameters. This may result
635 in the declaration ending up after C code, which is C syntax error.
636 Similar errors may happen with an explicit ";"-type or "+"-type ini‐
637 tialization of parameters is used (see "Initializing Function Parame‐
638 ters"). Declaring these variables in an INIT: section will not help.
639 In such cases, to force an additional variable to be declared together
641 with declarations of other variables, place the declaration into a
642 PREINIT: section. The PREINIT: keyword may be used one or more times
643 within an XSUB.
644 The following examples are equivalent, but if the code is using complex
646 typemaps then the first example is safer.
647 bool_t
649 rpcb_gettime(timep)
650 time_t timep = NO_INIT
651 PREINIT:
652 char *host = "localhost";
653 CODE:
654 RETVAL = rpcb_gettime( host, &timep );
655 OUTPUT:
656 timep
657 RETVAL
658 For this particular case an INIT: keyword would generate the same C
660 code as the PREINIT: keyword. Another correct, but error-prone exam‐
661 ple:
662 bool_t
664 rpcb_gettime(timep)
665 time_t timep = NO_INIT
666 CODE:
667 char *host = "localhost";
668 RETVAL = rpcb_gettime( host, &timep );
669 OUTPUT:
670 timep
671 RETVAL
672 Another way to declare "host" is to use a C block in the CODE: section:
674 bool_t
676 rpcb_gettime(timep)
677 time_t timep = NO_INIT
678 CODE:
679 {
680 char *host = "localhost";
681 RETVAL = rpcb_gettime( host, &timep );
682 }
683 OUTPUT:
684 timep
685 RETVAL
686 The ability to put additional declarations before the typemap entries
688 are processed is very handy in the cases when typemap conversions
689 manipulate some global state:
690 MyObject
692 mutate(o)
693 PREINIT:
694 MyState st = global_state;
695 INPUT:
696 MyObject o;
697 CLEANUP:
698 reset_to(global_state, st);
699 Here we suppose that conversion to "MyObject" in the INPUT: section and
701 from MyObject when processing RETVAL will modify a global variable
702 "global_state". After these conversions are performed, we restore the
703 old value of "global_state" (to avoid memory leaks, for example).
704 There is another way to trade clarity for compactness: INPUT sections
706 allow declaration of C variables which do not appear in the parameter
707 list of a subroutine. Thus the above code for mutate() can be rewrit‐
708 ten as
709 MyObject
711 mutate(o)
712 MyState st = global_state;
713 MyObject o;
714 CLEANUP:
715 reset_to(global_state, st);
716 and the code for rpcb_gettime() can be rewritten as
718 bool_t
720 rpcb_gettime(timep)
721 time_t timep = NO_INIT
722 char *host = "localhost";
723 C_ARGS:
724 host, &timep
725 OUTPUT:
726 timep
727 RETVAL
728 The SCOPE: Keyword
730 The SCOPE: keyword allows scoping to be enabled for a particular XSUB.
732 If enabled, the XSUB will invoke ENTER and LEAVE automatically.
733 To support potentially complex type mappings, if a typemap entry used
735 by an XSUB contains a comment like "/*scope*/" then scoping will be
736 automatically enabled for that XSUB.
737 To enable scoping:
739 SCOPE: ENABLE
741 To disable scoping:
743 SCOPE: DISABLE
745 The INPUT: Keyword
747 The XSUB's parameters are usually evaluated immediately after entering
749 the XSUB. The INPUT: keyword can be used to force those parameters to
750 be evaluated a little later. The INPUT: keyword can be used multiple
751 times within an XSUB and can be used to list one or more input vari‐
752 ables. This keyword is used with the PREINIT: keyword.
753 The following example shows how the input parameter "timep" can be
755 evaluated late, after a PREINIT.
756 bool_t
758 rpcb_gettime(host,timep)
759 char *host
760 PREINIT:
761 time_t tt;
762 INPUT:
763 time_t timep
764 CODE:
765 RETVAL = rpcb_gettime( host, &tt );
766 timep = tt;
767 OUTPUT:
768 timep
769 RETVAL
770 The next example shows each input parameter evaluated late.
772 bool_t
774 rpcb_gettime(host,timep)
775 PREINIT:
776 time_t tt;
777 INPUT:
778 char *host
779 PREINIT:
780 char *h;
781 INPUT:
782 time_t timep
783 CODE:
784 h = host;
785 RETVAL = rpcb_gettime( h, &tt );
786 timep = tt;
787 OUTPUT:
788 timep
789 RETVAL
790 Since INPUT sections allow declaration of C variables which do not
792 appear in the parameter list of a subroutine, this may be shortened to:
793 bool_t
795 rpcb_gettime(host,timep)
796 time_t tt;
797 char *host;
798 char *h = host;
799 time_t timep;
800 CODE:
801 RETVAL = rpcb_gettime( h, &tt );
802 timep = tt;
803 OUTPUT:
804 timep
805 RETVAL
806 (We used our knowledge that input conversion for "char *" is a "simple"
808 one, thus "host" is initialized on the declaration line, and our
809 assignment "h = host" is not performed too early. Otherwise one would
810 need to have the assignment "h = host" in a CODE: or INIT: section.)
811 The IN/OUTLIST/IN_OUTLIST/OUT/IN_OUT Keywords
813 In the list of parameters for an XSUB, one can precede parameter names
815 by the "IN"/"OUTLIST"/"IN_OUTLIST"/"OUT"/"IN_OUT" keywords. "IN" key‐
816 word is the default, the other keywords indicate how the Perl interface
817 should differ from the C interface.
818 Parameters preceded by "OUTLIST"/"IN_OUTLIST"/"OUT"/"IN_OUT" keywords
820 are considered to be used by the C subroutine via pointers. "OUT‐
821 LIST"/"OUT" keywords indicate that the C subroutine does not inspect
822 the memory pointed by this parameter, but will write through this
823 pointer to provide additional return values.
824 Parameters preceded by "OUTLIST" keyword do not appear in the usage
826 signature of the generated Perl function.
827 Parameters preceded by "IN_OUTLIST"/"IN_OUT"/"OUT" do appear as parame‐
829 ters to the Perl function. With the exception of "OUT"-parameters,
830 these parameters are converted to the corresponding C type, then point‐
831 ers to these data are given as arguments to the C function. It is
832 expected that the C function will write through these pointers.
833 The return list of the generated Perl function consists of the C return
835 value from the function (unless the XSUB is of "void" return type or
836 "The NO_OUTPUT Keyword" was used) followed by all the "OUTLIST" and
837 "IN_OUTLIST" parameters (in the order of appearance). On the return
838 from the XSUB the "IN_OUT"/"OUT" Perl parameter will be modified to
839 have the values written by the C function.
840 For example, an XSUB
842 void
844 day_month(OUTLIST day, IN unix_time, OUTLIST month)
845 int day
846 int unix_time
847 int month
848 should be used from Perl as
850 my ($day, $month) = day_month(time);
852 The C signature of the corresponding function should be
854 void day_month(int *day, int unix_time, int *month);
856 The "IN"/"OUTLIST"/"IN_OUTLIST"/"IN_OUT"/"OUT" keywords can be mixed
858 with ANSI-style declarations, as in
859 void
861 day_month(OUTLIST int day, int unix_time, OUTLIST int month)
862 (here the optional "IN" keyword is omitted).
864 The "IN_OUT" parameters are identical with parameters introduced with
866 "The & Unary Operator" and put into the "OUTPUT:" section (see "The
867 OUTPUT: Keyword"). The "IN_OUTLIST" parameters are very similar, the
868 only difference being that the value C function writes through the
869 pointer would not modify the Perl parameter, but is put in the output
870 list.
871 The "OUTLIST"/"OUT" parameter differ from "IN_OUTLIST"/"IN_OUT" parame‐
873 ters only by the initial value of the Perl parameter not being read
874 (and not being given to the C function - which gets some garbage
875 instead). For example, the same C function as above can be interfaced
876 with as
877 void day_month(OUT int day, int unix_time, OUT int month);
879 or
881 void
883 day_month(day, unix_time, month)
884 int &day = NO_INIT
885 int unix_time
886 int &month = NO_INIT
887 OUTPUT:
888 day
889 month
890 However, the generated Perl function is called in very C-ish style:
892 my ($day, $month);
894 day_month($day, time, $month);
895 The "length(NAME)" Keyword
897 If one of the input arguments to the C function is the length of a
899 string argument "NAME", one can substitute the name of the length-argu‐
900 ment by "length(NAME)" in the XSUB declaration. This argument must be
901 omitted when the generated Perl function is called. E.g.,
902 void
904 dump_chars(char *s, short l)
905 {
906 short n = 0;
907 while (n < l) {
908 printf("s[%d] = \"\\%#03o\"\n", n, (int)s[n]);
909 n++;
910 }
911 }
912 MODULE = x PACKAGE = x
914 void dump_chars(char *s, short length(s))
916 should be called as "dump_chars($string)".
918 This directive is supported with ANSI-type function declarations only.
920 Variable-length Parameter Lists
922 XSUBs can have variable-length parameter lists by specifying an ellip‐
924 sis "(...)" in the parameter list. This use of the ellipsis is similar
925 to that found in ANSI C. The programmer is able to determine the num‐
926 ber of arguments passed to the XSUB by examining the "items" variable
927 which the xsubpp compiler supplies for all XSUBs. By using this mecha‐
928 nism one can create an XSUB which accepts a list of parameters of
929 unknown length.
930 The host parameter for the rpcb_gettime() XSUB can be optional so the
932 ellipsis can be used to indicate that the XSUB will take a variable
933 number of parameters. Perl should be able to call this XSUB with
934 either of the following statements.
935 $status = rpcb_gettime( $timep, $host );
937 $status = rpcb_gettime( $timep );
939 The XS code, with ellipsis, follows.
941 bool_t
943 rpcb_gettime(timep, ...)
944 time_t timep = NO_INIT
945 PREINIT:
946 char *host = "localhost";
947 STRLEN n_a;
948 CODE:
949 if( items > 1 )
950 host = (char *)SvPV(ST(1), n_a);
951 RETVAL = rpcb_gettime( host, &timep );
952 OUTPUT:
953 timep
954 RETVAL
955 The C_ARGS: Keyword
957 The C_ARGS: keyword allows creating of XSUBS which have different call‐
959 ing sequence from Perl than from C, without a need to write CODE: or
960 PPCODE: section. The contents of the C_ARGS: paragraph is put as the
961 argument to the called C function without any change.
962 For example, suppose that a C function is declared as
964 symbolic nth_derivative(int n, symbolic function, int flags);
966 and that the default flags are kept in a global C variable
968 "default_flags". Suppose that you want to create an interface which is
969 called as
970 $second_deriv = $function->nth_derivative(2);
972 To do this, declare the XSUB as
974 symbolic
976 nth_derivative(function, n)
977 symbolic function
978 int n
979 C_ARGS:
980 n, function, default_flags
981 The PPCODE: Keyword
983 The PPCODE: keyword is an alternate form of the CODE: keyword and is
985 used to tell the xsubpp compiler that the programmer is supplying the
986 code to control the argument stack for the XSUBs return values. Occa‐
987 sionally one will want an XSUB to return a list of values rather than a
988 single value. In these cases one must use PPCODE: and then explicitly
989 push the list of values on the stack. The PPCODE: and CODE: keywords
990 should not be used together within the same XSUB.
991 The actual difference between PPCODE: and CODE: sections is in the ini‐
993 tialization of "SP" macro (which stands for the current Perl stack
994 pointer), and in the handling of data on the stack when returning from
995 an XSUB. In CODE: sections SP preserves the value which was on entry
996 to the XSUB: SP is on the function pointer (which follows the last
997 parameter). In PPCODE: sections SP is moved backward to the beginning
998 of the parameter list, which allows "PUSH*()" macros to place output
999 values in the place Perl expects them to be when the XSUB returns back
1000 to Perl.
1001 The generated trailer for a CODE: section ensures that the number of
1003 return values Perl will see is either 0 or 1 (depending on the
1004 "void"ness of the return value of the C function, and heuristics men‐
1005 tioned in "The RETVAL Variable"). The trailer generated for a PPCODE:
1006 section is based on the number of return values and on the number of
1007 times "SP" was updated by "[X]PUSH*()" macros.
1008 Note that macros ST(i), "XST_m*()" and "XSRETURN*()" work equally well
1010 in CODE: sections and PPCODE: sections.
1011 The following XSUB will call the C rpcb_gettime() function and will
1013 return its two output values, timep and status, to Perl as a single
1014 list.
1015 void
1017 rpcb_gettime(host)
1018 char *host
1019 PREINIT:
1020 time_t timep;
1021 bool_t status;
1022 PPCODE:
1023 status = rpcb_gettime( host, &timep );
1024 EXTEND(SP, 2);
1025 PUSHs(sv_2mortal(newSViv(status)));
1026 PUSHs(sv_2mortal(newSViv(timep)));
1027 Notice that the programmer must supply the C code necessary to have the
1029 real rpcb_gettime() function called and to have the return values prop‐
1030 erly placed on the argument stack.
1031 The "void" return type for this function tells the xsubpp compiler that
1033 the RETVAL variable is not needed or used and that it should not be
1034 created. In most scenarios the void return type should be used with
1035 the PPCODE: directive.
1036 The EXTEND() macro is used to make room on the argument stack for 2
1038 return values. The PPCODE: directive causes the xsubpp compiler to
1039 create a stack pointer available as "SP", and it is this pointer which
1040 is being used in the EXTEND() macro. The values are then pushed onto
1041 the stack with the PUSHs() macro.
1042 Now the rpcb_gettime() function can be used from Perl with the follow‐
1044 ing statement.
1045 ($status, $timep) = rpcb_gettime("localhost");
1047 When handling output parameters with a PPCODE section, be sure to han‐
1049 dle 'set' magic properly. See perlguts for details about 'set' magic.
1050 Returning Undef And Empty Lists
1052 Occasionally the programmer will want to return simply "undef" or an
1054 empty list if a function fails rather than a separate status value.
1055 The rpcb_gettime() function offers just this situation. If the func‐
1056 tion succeeds we would like to have it return the time and if it fails
1057 we would like to have undef returned. In the following Perl code the
1058 value of $timep will either be undef or it will be a valid time.
1059 $timep = rpcb_gettime( "localhost" );
1061 The following XSUB uses the "SV *" return type as a mnemonic only, and
1063 uses a CODE: block to indicate to the compiler that the programmer has
1064 supplied all the necessary code. The sv_newmortal() call will initial‐
1065 ize the return value to undef, making that the default return value.
1066 SV *
1068 rpcb_gettime(host)
1069 char * host
1070 PREINIT:
1071 time_t timep;
1072 bool_t x;
1073 CODE:
1074 ST(0) = sv_newmortal();
1075 if( rpcb_gettime( host, &timep ) )
1076 sv_setnv( ST(0), (double)timep);
1077 The next example demonstrates how one would place an explicit undef in
1079 the return value, should the need arise.
1080 SV *
1082 rpcb_gettime(host)
1083 char * host
1084 PREINIT:
1085 time_t timep;
1086 bool_t x;
1087 CODE:
1088 ST(0) = sv_newmortal();
1089 if( rpcb_gettime( host, &timep ) ){
1090 sv_setnv( ST(0), (double)timep);
1091 }
1092 else{
1093 ST(0) = &PL_sv_undef;
1094 }
1095 To return an empty list one must use a PPCODE: block and then not push
1097 return values on the stack.
1098 void
1100 rpcb_gettime(host)
1101 char *host
1102 PREINIT:
1103 time_t timep;
1104 PPCODE:
1105 if( rpcb_gettime( host, &timep ) )
1106 PUSHs(sv_2mortal(newSViv(timep)));
1107 else{
1108 /* Nothing pushed on stack, so an empty
1109 * list is implicitly returned. */
1110 }
1111 Some people may be inclined to include an explicit "return" in the
1113 above XSUB, rather than letting control fall through to the end. In
1114 those situations "XSRETURN_EMPTY" should be used, instead. This will
1115 ensure that the XSUB stack is properly adjusted. Consult perlapi for
1116 other "XSRETURN" macros.
1117 Since "XSRETURN_*" macros can be used with CODE blocks as well, one can
1119 rewrite this example as:
1120 int
1122 rpcb_gettime(host)
1123 char *host
1124 PREINIT:
1125 time_t timep;
1126 CODE:
1127 RETVAL = rpcb_gettime( host, &timep );
1128 if (RETVAL == 0)
1129 XSRETURN_UNDEF;
1130 OUTPUT:
1131 RETVAL
1132 In fact, one can put this check into a POSTCALL: section as well.
1134 Together with PREINIT: simplifications, this leads to:
1135 int
1137 rpcb_gettime(host)
1138 char *host
1139 time_t timep;
1140 POSTCALL:
1141 if (RETVAL == 0)
1142 XSRETURN_UNDEF;
1143 The REQUIRE: Keyword
1145 The REQUIRE: keyword is used to indicate the minimum version of the
1147 xsubpp compiler needed to compile the XS module. An XS module which
1148 contains the following statement will compile with only xsubpp version
1149 1.922 or greater:
1150 REQUIRE: 1.922
1152 The CLEANUP: Keyword
1154 This keyword can be used when an XSUB requires special cleanup proce‐
1156 dures before it terminates. When the CLEANUP: keyword is used it must
1157 follow any CODE:, PPCODE:, or OUTPUT: blocks which are present in the
1158 XSUB. The code specified for the cleanup block will be added as the
1159 last statements in the XSUB.
1160 The POSTCALL: Keyword
1162 This keyword can be used when an XSUB requires special procedures exe‐
1164 cuted after the C subroutine call is performed. When the POSTCALL:
1165 keyword is used it must precede OUTPUT: and CLEANUP: blocks which are
1166 present in the XSUB.
1167 See examples in "The NO_OUTPUT Keyword" and "Returning Undef And Empty
1169 Lists".
1170 The POSTCALL: block does not make a lot of sense when the C subroutine
1172 call is supplied by user by providing either CODE: or PPCODE: section.
1173 The BOOT: Keyword
1175 The BOOT: keyword is used to add code to the extension's bootstrap
1177 function. The bootstrap function is generated by the xsubpp compiler
1178 and normally holds the statements necessary to register any XSUBs with
1179 Perl. With the BOOT: keyword the programmer can tell the compiler to
1180 add extra statements to the bootstrap function.
1181 This keyword may be used any time after the first MODULE keyword and
1183 should appear on a line by itself. The first blank line after the key‐
1184 word will terminate the code block.
1185 BOOT:
1187 # The following message will be printed when the
1188 # bootstrap function executes.
1189 printf("Hello from the bootstrap!\n");
1190 The VERSIONCHECK: Keyword
1192 The VERSIONCHECK: keyword corresponds to xsubpp's "-versioncheck" and
1194 "-noversioncheck" options. This keyword overrides the command line
1195 options. Version checking is enabled by default. When version check‐
1196 ing is enabled the XS module will attempt to verify that its version
1197 matches the version of the PM module.
1198 To enable version checking:
1200 VERSIONCHECK: ENABLE
1202 To disable version checking:
1204 VERSIONCHECK: DISABLE
1206 The PROTOTYPES: Keyword
1208 The PROTOTYPES: keyword corresponds to xsubpp's "-prototypes" and
1210 "-noprototypes" options. This keyword overrides the command line
1211 options. Prototypes are enabled by default. When prototypes are
1212 enabled XSUBs will be given Perl prototypes. This keyword may be used
1213 multiple times in an XS module to enable and disable prototypes for
1214 different parts of the module.
1215 To enable prototypes:
1217 PROTOTYPES: ENABLE
1219 To disable prototypes:
1221 PROTOTYPES: DISABLE
1223 The PROTOTYPE: Keyword
1225 This keyword is similar to the PROTOTYPES: keyword above but can be
1227 used to force xsubpp to use a specific prototype for the XSUB. This
1228 keyword overrides all other prototype options and keywords but affects
1229 only the current XSUB. Consult "Prototypes" in perlsub for information
1230 about Perl prototypes.
1231 bool_t
1233 rpcb_gettime(timep, ...)
1234 time_t timep = NO_INIT
1235 PROTOTYPE: $;$
1236 PREINIT:
1237 char *host = "localhost";
1238 STRLEN n_a;
1239 CODE:
1240 if( items > 1 )
1241 host = (char *)SvPV(ST(1), n_a);
1242 RETVAL = rpcb_gettime( host, &timep );
1243 OUTPUT:
1244 timep
1245 RETVAL
1246 If the prototypes are enabled, you can disable it locally for a given
1248 XSUB as in the following example:
1249 void
1251 rpcb_gettime_noproto()
1252 PROTOTYPE: DISABLE
1253 ...
1254 The ALIAS: Keyword
1256 The ALIAS: keyword allows an XSUB to have two or more unique Perl names
1258 and to know which of those names was used when it was invoked. The
1259 Perl names may be fully-qualified with package names. Each alias is
1260 given an index. The compiler will setup a variable called "ix" which
1261 contain the index of the alias which was used. When the XSUB is called
1262 with its declared name "ix" will be 0.
1263 The following example will create aliases "FOO::gettime()" and
1265 "BAR::getit()" for this function.
1266 bool_t
1268 rpcb_gettime(host,timep)
1269 char *host
1270 time_t &timep
1271 ALIAS:
1272 FOO::gettime = 1
1273 BAR::getit = 2
1274 INIT:
1275 printf("# ix = %d\n", ix );
1276 OUTPUT:
1277 timep
1278 The OVERLOAD: Keyword
1280 Instead of writing an overloaded interface using pure Perl, you can
1282 also use the OVERLOAD keyword to define additional Perl names for your
1283 functions (like the ALIAS: keyword above). However, the overloaded
1284 functions must be defined with three parameters (except for the
1285 nomethod() function which needs four parameters). If any function has
1286 the OVERLOAD: keyword, several additional lines will be defined in the
1287 c file generated by xsubpp in order to register with the overload
1288 magic.
1289 Since blessed objects are actually stored as RV's, it is useful to use
1291 the typemap features to preprocess parameters and extract the actual SV
1292 stored within the blessed RV. See the sample for T_PTROBJ_SPECIAL
1293 below.
1294 To use the OVERLOAD: keyword, create an XS function which takes three
1296 input parameters ( or use the c style '...' definition) like this:
1297 SV *
1299 cmp (lobj, robj, swap)
1300 My_Module_obj lobj
1301 My_Module_obj robj
1302 IV swap
1303 OVERLOAD: cmp <=>
1304 { /* function defined here */}
1305 In this case, the function will overload both of the three way compari‐
1307 son operators. For all overload operations using non-alpha characters,
1308 you must type the parameter without quoting, seperating multiple over‐
1309 loads with whitespace. Note that "" (the stringify overload) should be
1310 entered as \"\" (i.e. escaped).
1311 The FALLBACK: Keyword
1313 In addition to the OVERLOAD keyword, if you need to control how Perl
1315 autogenerates missing overloaded operators, you can set the FALLBACK
1316 keyword in the module header section, like this:
1317 MODULE = RPC PACKAGE = RPC
1319 FALLBACK: TRUE
1321 ...
1322 where FALLBACK can take any of the three values TRUE, FALSE, or UNDEF.
1324 If you do not set any FALLBACK value when using OVERLOAD, it defaults
1325 to UNDEF. FALLBACK is not used except when one or more functions using
1326 OVERLOAD have been defined. Please see "Fallback" in overload for more
1327 details.
1328 The INTERFACE: Keyword
1330 This keyword declares the current XSUB as a keeper of the given calling
1332 signature. If some text follows this keyword, it is considered as a
1333 list of functions which have this signature, and should be attached to
1334 the current XSUB.
1335 For example, if you have 4 C functions multiply(), divide(), add(),
1337 subtract() all having the signature:
1338 symbolic f(symbolic, symbolic);
1340 you can make them all to use the same XSUB using this:
1342 symbolic
1344 interface_s_ss(arg1, arg2)
1345 symbolic arg1
1346 symbolic arg2
1347 INTERFACE:
1348 multiply divide
1349 add subtract
1350 (This is the complete XSUB code for 4 Perl functions!) Four generated
1352 Perl function share names with corresponding C functions.
1353 The advantage of this approach comparing to ALIAS: keyword is that
1355 there is no need to code a switch statement, each Perl function (which
1356 shares the same XSUB) knows which C function it should call. Addition‐
1357 ally, one can attach an extra function remainder() at runtime by using
1358 CV *mycv = newXSproto("Symbolic::remainder",
1360 XS_Symbolic_interface_s_ss, __FILE__, "$$");
1361 XSINTERFACE_FUNC_SET(mycv, remainder);
1362 say, from another XSUB. (This example supposes that there was no
1364 INTERFACE_MACRO: section, otherwise one needs to use something else
1365 instead of "XSINTERFACE_FUNC_SET", see the next section.)
1366 The INTERFACE_MACRO: Keyword
1368 This keyword allows one to define an INTERFACE using a different way to
1370 extract a function pointer from an XSUB. The text which follows this
1371 keyword should give the name of macros which would extract/set a func‐
1372 tion pointer. The extractor macro is given return type, "CV*", and
1373 "XSANY.any_dptr" for this "CV*". The setter macro is given cv, and the
1374 function pointer.
1375 The default value is "XSINTERFACE_FUNC" and "XSINTERFACE_FUNC_SET". An
1377 INTERFACE keyword with an empty list of functions can be omitted if
1378 INTERFACE_MACRO keyword is used.
1379 Suppose that in the previous example functions pointers for multiply(),
1381 divide(), add(), subtract() are kept in a global C array "fp[]" with
1382 offsets being "multiply_off", "divide_off", "add_off", "subtract_off".
1383 Then one can use
1384 #define XSINTERFACE_FUNC_BYOFFSET(ret,cv,f) \
1386 ((XSINTERFACE_CVT(ret,))fp[CvXSUBANY(cv).any_i32])
1387 #define XSINTERFACE_FUNC_BYOFFSET_set(cv,f) \
1388 CvXSUBANY(cv).any_i32 = CAT2( f, _off )
1389 in C section,
1391 symbolic
1393 interface_s_ss(arg1, arg2)
1394 symbolic arg1
1395 symbolic arg2
1396 INTERFACE_MACRO:
1397 XSINTERFACE_FUNC_BYOFFSET
1398 XSINTERFACE_FUNC_BYOFFSET_set
1399 INTERFACE:
1400 multiply divide
1401 add subtract
1402 in XSUB section.
1404 The INCLUDE: Keyword
1406 This keyword can be used to pull other files into the XS module. The
1408 other files may have XS code. INCLUDE: can also be used to run a com‐
1409 mand to generate the XS code to be pulled into the module.
1410 The file Rpcb1.xsh contains our "rpcb_gettime()" function:
1412 bool_t
1414 rpcb_gettime(host,timep)
1415 char *host
1416 time_t &timep
1417 OUTPUT:
1418 timep
1419 The XS module can use INCLUDE: to pull that file into it.
1421 INCLUDE: Rpcb1.xsh
1423 If the parameters to the INCLUDE: keyword are followed by a pipe ("⎪")
1425 then the compiler will interpret the parameters as a command.
1426 INCLUDE: cat Rpcb1.xsh ⎪
1428 The CASE: Keyword
1430 The CASE: keyword allows an XSUB to have multiple distinct parts with
1432 each part acting as a virtual XSUB. CASE: is greedy and if it is used
1433 then all other XS keywords must be contained within a CASE:. This
1434 means nothing may precede the first CASE: in the XSUB and anything fol‐
1435 lowing the last CASE: is included in that case.
1436 A CASE: might switch via a parameter of the XSUB, via the "ix" ALIAS:
1438 variable (see "The ALIAS: Keyword"), or maybe via the "items" variable
1439 (see "Variable-length Parameter Lists"). The last CASE: becomes the
1440 default case if it is not associated with a conditional. The following
1441 example shows CASE switched via "ix" with a function "rpcb_gettime()"
1442 having an alias "x_gettime()". When the function is called as
1443 "rpcb_gettime()" its parameters are the usual "(char *host, time_t
1444 *timep)", but when the function is called as "x_gettime()" its parame‐
1445 ters are reversed, "(time_t *timep, char *host)".
1446 long
1448 rpcb_gettime(a,b)
1449 CASE: ix == 1
1450 ALIAS:
1451 x_gettime = 1
1452 INPUT:
1453 # 'a' is timep, 'b' is host
1454 char *b
1455 time_t a = NO_INIT
1456 CODE:
1457 RETVAL = rpcb_gettime( b, &a );
1458 OUTPUT:
1459 a
1460 RETVAL
1461 CASE:
1462 # 'a' is host, 'b' is timep
1463 char *a
1464 time_t &b = NO_INIT
1465 OUTPUT:
1466 b
1467 RETVAL
1468 That function can be called with either of the following statements.
1470 Note the different argument lists.
1471 $status = rpcb_gettime( $host, $timep );
1473 $status = x_gettime( $timep, $host );
1475 The & Unary Operator
1477 The "&" unary operator in the INPUT: section is used to tell xsubpp
1479 that it should convert a Perl value to/from C using the C type to the
1480 left of "&", but provide a pointer to this value when the C function is
1481 called.
1482 This is useful to avoid a CODE: block for a C function which takes a
1484 parameter by reference. Typically, the parameter should be not a
1485 pointer type (an "int" or "long" but not an "int*" or "long*").
1486 The following XSUB will generate incorrect C code. The xsubpp compiler
1488 will turn this into code which calls "rpcb_gettime()" with parameters
1489 "(char *host, time_t timep)", but the real "rpcb_gettime()" wants the
1490 "timep" parameter to be of type "time_t*" rather than "time_t".
1491 bool_t
1493 rpcb_gettime(host,timep)
1494 char *host
1495 time_t timep
1496 OUTPUT:
1497 timep
1498 That problem is corrected by using the "&" operator. The xsubpp com‐
1500 piler will now turn this into code which calls "rpcb_gettime()" cor‐
1501 rectly with parameters "(char *host, time_t *timep)". It does this by
1502 carrying the "&" through, so the function call looks like "rpcb_get‐
1503 time(host, &timep)".
1504 bool_t
1506 rpcb_gettime(host,timep)
1507 char *host
1508 time_t &timep
1509 OUTPUT:
1510 timep
1511 Inserting POD, Comments and C Preprocessor Directives
1513 C preprocessor directives are allowed within BOOT:, PREINIT: INIT:,
1515 CODE:, PPCODE:, POSTCALL:, and CLEANUP: blocks, as well as outside the
1516 functions. Comments are allowed anywhere after the MODULE keyword.
1517 The compiler will pass the preprocessor directives through untouched
1518 and will remove the commented lines. POD documentation is allowed at
1519 any point, both in the C and XS language sections. POD must be termi‐
1520 nated with a "=cut" command; "xsubpp" will exit with an error if it
1521 does not. It is very unlikely that human generated C code will be mis‐
1522 taken for POD, as most indenting styles result in whitespace in front
1523 of any line starting with "=". Machine generated XS files may fall into
1524 this trap unless care is taken to ensure that a space breaks the
1525 sequence "\n=".
1526 Comments can be added to XSUBs by placing a "#" as the first non-white‐
1528 space of a line. Care should be taken to avoid making the comment look
1529 like a C preprocessor directive, lest it be interpreted as such. The
1530 simplest way to prevent this is to put whitespace in front of the "#".
1531 If you use preprocessor directives to choose one of two versions of a
1533 function, use
1534 #if ... version1
1536 #else /* ... version2 */
1537 #endif
1538 and not
1540 #if ... version1
1542 #endif
1543 #if ... version2
1544 #endif
1545 because otherwise xsubpp will believe that you made a duplicate defini‐
1547 tion of the function. Also, put a blank line before the #else/#endif
1548 so it will not be seen as part of the function body.
1549 Using XS With C++
1551 If an XSUB name contains "::", it is considered to be a C++ method.
1553 The generated Perl function will assume that its first argument is an
1554 object pointer. The object pointer will be stored in a variable called
1555 THIS. The object should have been created by C++ with the new() func‐
1556 tion and should be blessed by Perl with the sv_setref_pv() macro. The
1557 blessing of the object by Perl can be handled by a typemap. An example
1558 typemap is shown at the end of this section.
1559 If the return type of the XSUB includes "static", the method is consid‐
1561 ered to be a static method. It will call the C++ function using the
1562 class::method() syntax. If the method is not static the function will
1563 be called using the THIS->method() syntax.
1564 The next examples will use the following C++ class.
1566 class color {
1568 public:
1569 color();
1570 ~color();
1571 int blue();
1572 void set_blue( int );
1573 private:
1575 int c_blue;
1576 };
1577 The XSUBs for the blue() and set_blue() methods are defined with the
1579 class name but the parameter for the object (THIS, or "self") is
1580 implicit and is not listed.
1581 int
1583 color::blue()
1584 void
1586 color::set_blue( val )
1587 int val
1588 Both Perl functions will expect an object as the first parameter. In
1590 the generated C++ code the object is called "THIS", and the method call
1591 will be performed on this object. So in the C++ code the blue() and
1592 set_blue() methods will be called as this:
1593 RETVAL = THIS->blue();
1595 THIS->set_blue( val );
1597 You could also write a single get/set method using an optional argu‐
1599 ment:
1600 int
1602 color::blue( val = NO_INIT )
1603 int val
1604 PROTOTYPE $;$
1605 CODE:
1606 if (items > 1)
1607 THIS->set_blue( val );
1608 RETVAL = THIS->blue();
1609 OUTPUT:
1610 RETVAL
1611 If the function's name is DESTROY then the C++ "delete" function will
1613 be called and "THIS" will be given as its parameter. The generated C++
1614 code for
1615 void
1617 color::DESTROY()
1618 will look like this:
1620 color *THIS = ...; // Initialized as in typemap
1622 delete THIS;
1624 If the function's name is new then the C++ "new" function will be
1626 called to create a dynamic C++ object. The XSUB will expect the class
1627 name, which will be kept in a variable called "CLASS", to be given as
1628 the first argument.
1629 color *
1631 color::new()
1632 The generated C++ code will call "new".
1634 RETVAL = new color();
1636 The following is an example of a typemap that could be used for this
1638 C++ example.
1639 TYPEMAP
1641 color * O_OBJECT
1642 OUTPUT
1644 # The Perl object is blessed into 'CLASS', which should be a
1645 # char* having the name of the package for the blessing.
1646 O_OBJECT
1647 sv_setref_pv( $arg, CLASS, (void*)$var );
1648 INPUT
1650 O_OBJECT
1651 if( sv_isobject($arg) && (SvTYPE(SvRV($arg)) == SVt_PVMG) )
1652 $var = ($type)SvIV((SV*)SvRV( $arg ));
1653 else{
1654 warn( \"${Package}::$func_name() -- $var is not a blessed SV reference\" );
1655 XSRETURN_UNDEF;
1656 }
1657 Interface Strategy
1659 When designing an interface between Perl and a C library a straight
1661 translation from C to XS (such as created by "h2xs -x") is often suffi‐
1662 cient. However, sometimes the interface will look very C-like and
1663 occasionally nonintuitive, especially when the C function modifies one
1664 of its parameters, or returns failure inband (as in "negative return
1665 values mean failure"). In cases where the programmer wishes to create
1666 a more Perl-like interface the following strategy may help to identify
1667 the more critical parts of the interface.
1668 Identify the C functions with input/output or output parameters. The
1670 XSUBs for these functions may be able to return lists to Perl.
1671 Identify the C functions which use some inband info as an indication of
1673 failure. They may be candidates to return undef or an empty list in
1674 case of failure. If the failure may be detected without a call to the
1675 C function, you may want to use an INIT: section to report the failure.
1676 For failures detectable after the C function returns one may want to
1677 use a POSTCALL: section to process the failure. In more complicated
1678 cases use CODE: or PPCODE: sections.
1679 If many functions use the same failure indication based on the return
1681 value, you may want to create a special typedef to handle this situa‐
1682 tion. Put
1683 typedef int negative_is_failure;
1685 near the beginning of XS file, and create an OUTPUT typemap entry for
1687 "negative_is_failure" which converts negative values to "undef", or
1688 maybe croak()s. After this the return value of type "negative_is_fail‐
1689 ure" will create more Perl-like interface.
1690 Identify which values are used by only the C and XSUB functions them‐
1692 selves, say, when a parameter to a function should be a contents of a
1693 global variable. If Perl does not need to access the contents of the
1694 value then it may not be necessary to provide a translation for that
1695 value from C to Perl.
1696 Identify the pointers in the C function parameter lists and return val‐
1698 ues. Some pointers may be used to implement input/output or output
1699 parameters, they can be handled in XS with the "&" unary operator, and,
1700 possibly, using the NO_INIT keyword. Some others will require handling
1701 of types like "int *", and one needs to decide what a useful Perl
1702 translation will do in such a case. When the semantic is clear, it is
1703 advisable to put the translation into a typemap file.
1704 Identify the structures used by the C functions. In many cases it may
1706 be helpful to use the T_PTROBJ typemap for these structures so they can
1707 be manipulated by Perl as blessed objects. (This is handled automati‐
1708 cally by "h2xs -x".)
1709 If the same C type is used in several different contexts which require
1711 different translations, "typedef" several new types mapped to this C
1712 type, and create separate typemap entries for these new types. Use
1713 these types in declarations of return type and parameters to XSUBs.
1714 Perl Objects And C Structures
1716 When dealing with C structures one should select either T_PTROBJ or
1718 T_PTRREF for the XS type. Both types are designed to handle pointers
1719 to complex objects. The T_PTRREF type will allow the Perl object to be
1720 unblessed while the T_PTROBJ type requires that the object be blessed.
1721 By using T_PTROBJ one can achieve a form of type-checking because the
1722 XSUB will attempt to verify that the Perl object is of the expected
1723 type.
1724 The following XS code shows the getnetconfigent() function which is
1726 used with ONC+ TIRPC. The getnetconfigent() function will return a
1727 pointer to a C structure and has the C prototype shown below. The
1728 example will demonstrate how the C pointer will become a Perl refer‐
1729 ence. Perl will consider this reference to be a pointer to a blessed
1730 object and will attempt to call a destructor for the object. A
1731 destructor will be provided in the XS source to free the memory used by
1732 getnetconfigent(). Destructors in XS can be created by specifying an
1733 XSUB function whose name ends with the word DESTROY. XS destructors
1734 can be used to free memory which may have been malloc'd by another
1735 XSUB.
1736 struct netconfig *getnetconfigent(const char *netid);
1738 A "typedef" will be created for "struct netconfig". The Perl object
1740 will be blessed in a class matching the name of the C type, with the
1741 tag "Ptr" appended, and the name should not have embedded spaces if it
1742 will be a Perl package name. The destructor will be placed in a class
1743 corresponding to the class of the object and the PREFIX keyword will be
1744 used to trim the name to the word DESTROY as Perl will expect.
1745 typedef struct netconfig Netconfig;
1747 MODULE = RPC PACKAGE = RPC
1749 Netconfig *
1751 getnetconfigent(netid)
1752 char *netid
1753 MODULE = RPC PACKAGE = NetconfigPtr PREFIX = rpcb_
1755 void
1757 rpcb_DESTROY(netconf)
1758 Netconfig *netconf
1759 CODE:
1760 printf("Now in NetconfigPtr::DESTROY\n");
1761 free( netconf );
1762 This example requires the following typemap entry. Consult the typemap
1764 section for more information about adding new typemaps for an exten‐
1765 sion.
1766 TYPEMAP
1768 Netconfig * T_PTROBJ
1769 This example will be used with the following Perl statements.
1771 use RPC;
1773 $netconf = getnetconfigent("udp");
1774 When Perl destroys the object referenced by $netconf it will send the
1776 object to the supplied XSUB DESTROY function. Perl cannot determine,
1777 and does not care, that this object is a C struct and not a Perl
1778 object. In this sense, there is no difference between the object cre‐
1779 ated by the getnetconfigent() XSUB and an object created by a normal
1780 Perl subroutine.
1781 The Typemap
1783 The typemap is a collection of code fragments which are used by the
1785 xsubpp compiler to map C function parameters and values to Perl values.
1786 The typemap file may consist of three sections labelled "TYPEMAP",
1787 "INPUT", and "OUTPUT". An unlabelled initial section is assumed to be
1788 a "TYPEMAP" section. The INPUT section tells the compiler how to
1789 translate Perl values into variables of certain C types. The OUTPUT
1790 section tells the compiler how to translate the values from certain C
1791 types into values Perl can understand. The TYPEMAP section tells the
1792 compiler which of the INPUT and OUTPUT code fragments should be used to
1793 map a given C type to a Perl value. The section labels "TYPEMAP",
1794 "INPUT", or "OUTPUT" must begin in the first column on a line by them‐
1795 selves, and must be in uppercase.
1796 The default typemap in the "lib/ExtUtils" directory of the Perl source
1798 contains many useful types which can be used by Perl extensions. Some
1799 extensions define additional typemaps which they keep in their own
1800 directory. These additional typemaps may reference INPUT and OUTPUT
1801 maps in the main typemap. The xsubpp compiler will allow the exten‐
1802 sion's own typemap to override any mappings which are in the default
1803 typemap.
1804 Most extensions which require a custom typemap will need only the
1806 TYPEMAP section of the typemap file. The custom typemap used in the
1807 getnetconfigent() example shown earlier demonstrates what may be the
1808 typical use of extension typemaps. That typemap is used to equate a C
1809 structure with the T_PTROBJ typemap. The typemap used by getnetconfi‐
1810 gent() is shown here. Note that the C type is separated from the XS
1811 type with a tab and that the C unary operator "*" is considered to be a
1812 part of the C type name.
1813 TYPEMAP
1815 Netconfig *<tab>T_PTROBJ
1816 Here's a more complicated example: suppose that you wanted "struct net‐
1818 config" to be blessed into the class "Net::Config". One way to do this
1819 is to use underscores (_) to separate package names, as follows:
1820 typedef struct netconfig * Net_Config;
1822 And then provide a typemap entry "T_PTROBJ_SPECIAL" that maps under‐
1824 scores to double-colons (::), and declare "Net_Config" to be of that
1825 type:
1826 TYPEMAP
1828 Net_Config T_PTROBJ_SPECIAL
1829 INPUT
1831 T_PTROBJ_SPECIAL
1832 if (sv_derived_from($arg, \"${(my $ntt=$ntype)=~s/_/::/g;\$ntt}\")) {
1833 IV tmp = SvIV((SV*)SvRV($arg));
1834 $var = INT2PTR($type, tmp);
1835 }
1836 else
1837 croak(\"$var is not of type ${(my $ntt=$ntype)=~s/_/::/g;\$ntt}\")
1838 OUTPUT
1840 T_PTROBJ_SPECIAL
1841 sv_setref_pv($arg, \"${(my $ntt=$ntype)=~s/_/::/g;\$ntt}\",
1842 (void*)$var);
1843 The INPUT and OUTPUT sections substitute underscores for double-colons
1845 on the fly, giving the desired effect. This example demonstrates some
1846 of the power and versatility of the typemap facility.
1847 The INT2PTR macro (defined in perl.h) casts an integer to a pointer, of
1849 a given type, taking care of the possible different size of integers
1850 and pointers. There are also PTR2IV, PTR2UV, PTR2NV macros, to map the
1851 other way, which may be useful in OUTPUT sections.
1852 Safely Storing Static Data in XS
1854 Starting with Perl 5.8, a macro framework has been defined to allow
1856 static data to be safely stored in XS modules that will be accessed
1857 from a multi-threaded Perl.
1858 Although primarily designed for use with multi-threaded Perl, the
1860 macros have been designed so that they will work with non-threaded Perl
1861 as well.
1862 It is therefore strongly recommended that these macros be used by all
1864 XS modules that make use of static data.
1865 The easiest way to get a template set of macros to use is by specifying
1867 the "-g" ("--global") option with h2xs (see h2xs).
1868 Below is an example module that makes use of the macros.
1870 #include "EXTERN.h"
1872 #include "perl.h"
1873 #include "XSUB.h"
1874 /* Global Data */
1876 #define MY_CXT_KEY "BlindMice::_guts" XS_VERSION
1878 typedef struct {
1880 int count;
1881 char name[3][100];
1882 } my_cxt_t;
1883 START_MY_CXT
1885 MODULE = BlindMice PACKAGE = BlindMice
1887 BOOT:
1889 {
1890 MY_CXT_INIT;
1891 MY_CXT.count = 0;
1892 strcpy(MY_CXT.name[0], "None");
1893 strcpy(MY_CXT.name[1], "None");
1894 strcpy(MY_CXT.name[2], "None");
1895 }
1896 int
1898 newMouse(char * name)
1899 char * name;
1900 PREINIT:
1901 dMY_CXT;
1902 CODE:
1903 if (MY_CXT.count >= 3) {
1904 warn("Already have 3 blind mice");
1905 RETVAL = 0;
1906 }
1907 else {
1908 RETVAL = ++ MY_CXT.count;
1909 strcpy(MY_CXT.name[MY_CXT.count - 1], name);
1910 }
1911 char *
1913 get_mouse_name(index)
1914 int index
1915 CODE:
1916 dMY_CXT;
1917 RETVAL = MY_CXT.lives ++;
1918 if (index > MY_CXT.count)
1919 croak("There are only 3 blind mice.");
1920 else
1921 RETVAL = newSVpv(MY_CXT.name[index - 1]);
1922 REFERENCE
1924 MY_CXT_KEY
1926 This macro is used to define a unique key to refer to the static
1927 data for an XS module. The suggested naming scheme, as used by
1928 h2xs, is to use a string that consists of the module name, the
1929 string "::_guts" and the module version number.
1930 #define MY_CXT_KEY "MyModule::_guts" XS_VERSION
1932 typedef my_cxt_t
1934 This struct typedef must always be called "my_cxt_t" -- the other
1935 "CXT*" macros assume the existence of the "my_cxt_t" typedef name.
1936 Declare a typedef named "my_cxt_t" that is a structure that con‐
1938 tains all the data that needs to be interpreter-local.
1939 typedef struct {
1941 int some_value;
1942 } my_cxt_t;
1943 START_MY_CXT
1945 Always place the START_MY_CXT macro directly after the declaration
1946 of "my_cxt_t".
1947 MY_CXT_INIT
1949 The MY_CXT_INIT macro initialises storage for the "my_cxt_t"
1950 struct.
1951 It must be called exactly once -- typically in a BOOT: section.
1953 dMY_CXT
1955 Use the dMY_CXT macro (a declaration) in all the functions that
1956 access MY_CXT.
1957 MY_CXT
1959 Use the MY_CXT macro to access members of the "my_cxt_t" struct.
1960 For example, if "my_cxt_t" is
1961 typedef struct {
1963 int index;
1964 } my_cxt_t;
1965 then use this to access the "index" member
1967 dMY_CXT;
1969 MY_CXT.index = 2;
1970
1972 File "RPC.xs": Interface to some ONC+ RPC bind library functions.
1973 #include "EXTERN.h"
1975 #include "perl.h"
1976 #include "XSUB.h"
1977 #include <rpc/rpc.h>
1979 typedef struct netconfig Netconfig;
1981 MODULE = RPC PACKAGE = RPC
1983 SV *
1985 rpcb_gettime(host="localhost")
1986 char *host
1987 PREINIT:
1988 time_t timep;
1989 CODE:
1990 ST(0) = sv_newmortal();
1991 if( rpcb_gettime( host, &timep ) )
1992 sv_setnv( ST(0), (double)timep );
1993 Netconfig *
1995 getnetconfigent(netid="udp")
1996 char *netid
1997 MODULE = RPC PACKAGE = NetconfigPtr PREFIX = rpcb_
1999 void
2001 rpcb_DESTROY(netconf)
2002 Netconfig *netconf
2003 CODE:
2004 printf("NetconfigPtr::DESTROY\n");
2005 free( netconf );
2006 File "typemap": Custom typemap for RPC.xs.
2008 TYPEMAP
2010 Netconfig * T_PTROBJ
2011 File "RPC.pm": Perl module for the RPC extension.
2013 package RPC;
2015 require Exporter;
2017 require DynaLoader;
2018 @ISA = qw(Exporter DynaLoader);
2019 @EXPORT = qw(rpcb_gettime getnetconfigent);
2020 bootstrap RPC;
2022 1;
2023 File "rpctest.pl": Perl test program for the RPC extension.
2025 use RPC;
2027 $netconf = getnetconfigent();
2029 $a = rpcb_gettime();
2030 print "time = $a\n";
2031 print "netconf = $netconf\n";
2032 $netconf = getnetconfigent("tcp");
2034 $a = rpcb_gettime("poplar");
2035 print "time = $a\n";
2036 print "netconf = $netconf\n";
2037
2039 This document covers features supported by "xsubpp" 1.935.
2040
2042 Originally written by Dean Roehrich <roehrich@cray.com>.
2043 Maintained since 1996 by The Perl Porters <perlbug@perl.org>.
2045perl v5.8.8 2006-01-07 PERLXS(1)