1perlxs(3) User Contributed Perl Documentation perlxs(3)
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 Before writing XS, read the "CAVEATS" section below.
18 An XSUB forms the basic unit of the XS interface. After compilation by
20 the xsubpp compiler, each XSUB amounts to a C function definition which
21 will provide the glue between Perl calling conventions and C calling
22 conventions.
23 The glue code pulls the arguments from the Perl stack, converts these
25 Perl values to the formats expected by a C function, call this C
26 function, transfers the return values of the C function back to Perl.
27 Return values here may be a conventional C return value or any C
28 function arguments that may serve as output parameters. These return
29 values may be passed back to Perl either by putting them on the Perl
30 stack, or by modifying the arguments supplied from the Perl side.
31 The above is a somewhat simplified view of what really happens. Since
33 Perl allows more flexible calling conventions than C, XSUBs may do much
34 more in practice, such as checking input parameters for validity,
35 throwing exceptions (or returning undef/empty list) if the return value
36 from the C function indicates failure, calling different C functions
37 based on numbers and types of the arguments, providing an object-
38 oriented interface, etc.
39 Of course, one could write such glue code directly in C. However, this
41 would be a tedious task, especially if one needs to write glue for
42 multiple C functions, and/or one is not familiar enough with the Perl
43 stack discipline and other such arcana. XS comes to the rescue here:
44 instead of writing this glue C code in long-hand, one can write a more
45 concise short-hand description of what should be done by the glue, and
46 let the XS compiler xsubpp handle the rest.
47 The XS language allows one to describe the mapping between how the C
49 routine is used, and how the corresponding Perl routine is used. It
50 also allows creation of Perl routines which are directly translated to
51 C code and which are not related to a pre-existing C function. In
52 cases when the C interface coincides with the Perl interface, the XSUB
53 declaration is almost identical to a declaration of a C function (in
54 K&R style). In such circumstances, there is another tool called "h2xs"
55 that is able to translate an entire C header file into a corresponding
56 XS file that will provide glue to the functions/macros described in the
57 header file.
58 The XS compiler is called xsubpp. This compiler creates the constructs
60 necessary to let an XSUB manipulate Perl values, and creates the glue
61 necessary to let Perl call the XSUB. The compiler uses typemaps to
62 determine how to map C function parameters and output values to Perl
63 values and back. The default typemap (which comes with Perl) handles
64 many common C types. A supplementary typemap may also be needed to
65 handle any special structures and types for the library being linked.
66 For more information on typemaps, see perlxstypemap.
67 A file in XS format starts with a C language section which goes until
69 the first "MODULE =" directive. Other XS directives and XSUB
70 definitions may follow this line. The "language" used in this part of
71 the file is usually referred to as the XS language. xsubpp recognizes
72 and skips POD (see perlpod) in both the C and XS language sections,
73 which allows the XS file to contain embedded documentation.
74 See perlxstut for a tutorial on the whole extension creation process.
76 Note: For some extensions, Dave Beazley's SWIG system may provide a
78 significantly more convenient mechanism for creating the extension glue
79 code. See <http://www.swig.org/> for more information.
80 For simple bindings to C libraries as well as other machine code
82 libraries, consider instead using the much simpler libffi
83 <http://sourceware.org/libffi/> interface via CPAN modules like
84 FFI::Platypus or FFI::Raw.
85 On The Road
87 Many of the examples which follow will concentrate on creating an
88 interface between Perl and the ONC+ RPC bind library functions. The
89 rpcb_gettime() function is used to demonstrate many features of the XS
90 language. This function has two parameters; the first is an input
91 parameter and the second is an output parameter. The function also
92 returns a status value.
93 bool_t rpcb_gettime(const char *host, time_t *timep);
95 From C this function will be called with the following statements.
97 #include <rpc/rpc.h>
99 bool_t status;
100 time_t timep;
101 status = rpcb_gettime( "localhost", &timep );
102 If an XSUB is created to offer a direct translation between this
104 function and Perl, then this XSUB will be used from Perl with the
105 following code. The $status and $timep variables will contain the
106 output of the function.
107 use RPC;
109 $status = rpcb_gettime( "localhost", $timep );
110 The following XS file shows an XS subroutine, or XSUB, which
112 demonstrates one possible interface to the rpcb_gettime() function.
113 This XSUB represents a direct translation between C and Perl and so
114 preserves the interface even from Perl. This XSUB will be invoked from
115 Perl with the usage shown above. Note that the first three #include
116 statements, for "EXTERN.h", "perl.h", and "XSUB.h", will always be
117 present at the beginning of an XS file. This approach and others will
118 be expanded later in this document. A #define for
119 "PERL_NO_GET_CONTEXT" should be present to fetch the interpreter
120 context more efficiently, see perlguts for details.
121 #define PERL_NO_GET_CONTEXT
123 #include "EXTERN.h"
124 #include "perl.h"
125 #include "XSUB.h"
126 #include <rpc/rpc.h>
127 MODULE = RPC PACKAGE = RPC
129 bool_t
131 rpcb_gettime(host,timep)
132 char *host
133 time_t &timep
134 OUTPUT:
135 timep
136 Any extension to Perl, including those containing XSUBs, should have a
138 Perl module to serve as the bootstrap which pulls the extension into
139 Perl. This module will export the extension's functions and variables
140 to the Perl program and will cause the extension's XSUBs to be linked
141 into Perl. The following module will be used for most of the examples
142 in this document and should be used from Perl with the "use" command as
143 shown earlier. Perl modules are explained in more detail later in this
144 document.
145 package RPC;
147 require Exporter;
149 require DynaLoader;
150 @ISA = qw(Exporter DynaLoader);
151 @EXPORT = qw( rpcb_gettime );
152 bootstrap RPC;
154 1;
155 Throughout this document a variety of interfaces to the rpcb_gettime()
157 XSUB will be explored. The XSUBs will take their parameters in
158 different orders or will take different numbers of parameters. In each
159 case the XSUB is an abstraction between Perl and the real C
160 rpcb_gettime() function, and the XSUB must always ensure that the real
161 rpcb_gettime() function is called with the correct parameters. This
162 abstraction will allow the programmer to create a more Perl-like
163 interface to the C function.
164 The Anatomy of an XSUB
166 The simplest XSUBs consist of 3 parts: a description of the return
167 value, the name of the XSUB routine and the names of its arguments, and
168 a description of types or formats of the arguments.
169 The following XSUB allows a Perl program to access a C library function
171 called sin(). The XSUB will imitate the C function which takes a
172 single argument and returns a single value.
173 double
175 sin(x)
176 double x
177 Optionally, one can merge the description of types and the list of
179 argument names, rewriting this as
180 double
182 sin(double x)
183 This makes this XSUB look similar to an ANSI C declaration. An
185 optional semicolon is allowed after the argument list, as in
186 double
188 sin(double x);
189 Parameters with C pointer types can have different semantic: C
191 functions with similar declarations
192 bool string_looks_as_a_number(char *s);
194 bool make_char_uppercase(char *c);
195 are used in absolutely incompatible manner. Parameters to these
197 functions could be described xsubpp like this:
198 char * s
200 char &c
201 Both these XS declarations correspond to the "char*" C type, but they
203 have different semantics, see "The & Unary Operator".
204 It is convenient to think that the indirection operator "*" should be
206 considered as a part of the type and the address operator "&" should be
207 considered part of the variable. See perlxstypemap for more info about
208 handling qualifiers and unary operators in C types.
209 The function name and the return type must be placed on separate lines
211 and should be flush left-adjusted.
212 INCORRECT CORRECT
214 double sin(x) double
216 double x sin(x)
217 double x
218 The rest of the function description may be indented or left-adjusted.
220 The following example shows a function with its body left-adjusted.
221 Most examples in this document will indent the body for better
222 readability.
223 CORRECT
225 double
227 sin(x)
228 double x
229 More complicated XSUBs may contain many other sections. Each section
231 of an XSUB starts with the corresponding keyword, such as INIT: or
232 CLEANUP:. However, the first two lines of an XSUB always contain the
233 same data: descriptions of the return type and the names of the
234 function and its parameters. Whatever immediately follows these is
235 considered to be an INPUT: section unless explicitly marked with
236 another keyword. (See "The INPUT: Keyword".)
237 An XSUB section continues until another section-start keyword is found.
239 The Argument Stack
241 The Perl argument stack is used to store the values which are sent as
242 parameters to the XSUB and to store the XSUB's return value(s). In
243 reality all Perl functions (including non-XSUB ones) keep their values
244 on this stack all the same time, each limited to its own range of
245 positions on the stack. In this document the first position on that
246 stack which belongs to the active function will be referred to as
247 position 0 for that function.
248 XSUBs refer to their stack arguments with the macro ST(x), where x
250 refers to a position in this XSUB's part of the stack. Position 0 for
251 that function would be known to the XSUB as ST(0). The XSUB's incoming
252 parameters and outgoing return values always begin at ST(0). For many
253 simple cases the xsubpp compiler will generate the code necessary to
254 handle the argument stack by embedding code fragments found in the
255 typemaps. In more complex cases the programmer must supply the code.
256 The RETVAL Variable
258 The RETVAL variable is a special C variable that is declared
259 automatically for you. The C type of RETVAL matches the return type of
260 the C library function. The xsubpp compiler will declare this variable
261 in each XSUB with non-"void" return type. By default the generated C
262 function will use RETVAL to hold the return value of the C library
263 function being called. In simple cases the value of RETVAL will be
264 placed in ST(0) of the argument stack where it can be received by Perl
265 as the return value of the XSUB.
266 If the XSUB has a return type of "void" then the compiler will not
268 declare a RETVAL variable for that function. When using a PPCODE:
269 section no manipulation of the RETVAL variable is required, the section
270 may use direct stack manipulation to place output values on the stack.
271 If PPCODE: directive is not used, "void" return value should be used
273 only for subroutines which do not return a value, even if CODE:
274 directive is used which sets ST(0) explicitly.
275 Older versions of this document recommended to use "void" return value
277 in such cases. It was discovered that this could lead to segfaults in
278 cases when XSUB was truly "void". This practice is now deprecated, and
279 may be not supported at some future version. Use the return value "SV
280 *" in such cases. (Currently "xsubpp" contains some heuristic code
281 which tries to disambiguate between "truly-void" and "old-practice-
282 declared-as-void" functions. Hence your code is at mercy of this
283 heuristics unless you use "SV *" as return value.)
284 Returning SVs, AVs and HVs through RETVAL
286 When you're using RETVAL to return an "SV *", there's some magic going
287 on behind the scenes that should be mentioned. When you're manipulating
288 the argument stack using the ST(x) macro, for example, you usually have
289 to pay special attention to reference counts. (For more about reference
290 counts, see perlguts.) To make your life easier, the typemap file
291 automatically makes "RETVAL" mortal when you're returning an "SV *".
292 Thus, the following two XSUBs are more or less equivalent:
293 void
295 alpha()
296 PPCODE:
297 ST(0) = newSVpv("Hello World",0);
298 sv_2mortal(ST(0));
299 XSRETURN(1);
300 SV *
302 beta()
303 CODE:
304 RETVAL = newSVpv("Hello World",0);
305 OUTPUT:
306 RETVAL
307 This is quite useful as it usually improves readability. While this
309 works fine for an "SV *", it's unfortunately not as easy to have "AV *"
310 or "HV *" as a return value. You should be able to write:
311 AV *
313 array()
314 CODE:
315 RETVAL = newAV();
316 /* do something with RETVAL */
317 OUTPUT:
318 RETVAL
319 But due to an unfixable bug (fixing it would break lots of existing
321 CPAN modules) in the typemap file, the reference count of the "AV *" is
322 not properly decremented. Thus, the above XSUB would leak memory
323 whenever it is being called. The same problem exists for "HV *", "CV
324 *", and "SVREF" (which indicates a scalar reference, not a general "SV
325 *"). In XS code on perls starting with perl 5.16, you can override the
326 typemaps for any of these types with a version that has proper handling
327 of refcounts. In your "TYPEMAP" section, do
328 AV* T_AVREF_REFCOUNT_FIXED
330 to get the repaired variant. For backward compatibility with older
332 versions of perl, you can instead decrement the reference count
333 manually when you're returning one of the aforementioned types using
334 "sv_2mortal":
335 AV *
337 array()
338 CODE:
339 RETVAL = newAV();
340 sv_2mortal((SV*)RETVAL);
341 /* do something with RETVAL */
342 OUTPUT:
343 RETVAL
344 Remember that you don't have to do this for an "SV *". The reference
346 documentation for all core typemaps can be found in perlxstypemap.
347 The MODULE Keyword
349 The MODULE keyword is used to start the XS code and to specify the
350 package of the functions which are being defined. All text preceding
351 the first MODULE keyword is considered C code and is passed through to
352 the output with POD stripped, but otherwise untouched. Every XS module
353 will have a bootstrap function which is used to hook the XSUBs into
354 Perl. The package name of this bootstrap function will match the value
355 of the last MODULE statement in the XS source files. The value of
356 MODULE should always remain constant within the same XS file, though
357 this is not required.
358 The following example will start the XS code and will place all
360 functions in a package named RPC.
361 MODULE = RPC
363 The PACKAGE Keyword
365 When functions within an XS source file must be separated into packages
366 the PACKAGE keyword should be used. This keyword is used with the
367 MODULE keyword and must follow immediately after it when used.
368 MODULE = RPC PACKAGE = RPC
370 [ XS code in package RPC ]
372 MODULE = RPC PACKAGE = RPCB
374 [ XS code in package RPCB ]
376 MODULE = RPC PACKAGE = RPC
378 [ XS code in package RPC ]
380 The same package name can be used more than once, allowing for non-
382 contiguous code. This is useful if you have a stronger ordering
383 principle than package names.
384 Although this keyword is optional and in some cases provides redundant
386 information it should always be used. This keyword will ensure that
387 the XSUBs appear in the desired package.
388 The PREFIX Keyword
390 The PREFIX keyword designates prefixes which should be removed from the
391 Perl function names. If the C function is "rpcb_gettime()" and the
392 PREFIX value is "rpcb_" then Perl will see this function as
393 "gettime()".
394 This keyword should follow the PACKAGE keyword when used. If PACKAGE
396 is not used then PREFIX should follow the MODULE keyword.
397 MODULE = RPC PREFIX = rpc_
399 MODULE = RPC PACKAGE = RPCB PREFIX = rpcb_
401 The OUTPUT: Keyword
403 The OUTPUT: keyword indicates that certain function parameters should
404 be updated (new values made visible to Perl) when the XSUB terminates
405 or that certain values should be returned to the calling Perl function.
406 For simple functions which have no CODE: or PPCODE: section, such as
407 the sin() function above, the RETVAL variable is automatically
408 designated as an output value. For more complex functions the xsubpp
409 compiler will need help to determine which variables are output
410 variables.
411 This keyword will normally be used to complement the CODE: keyword.
413 The RETVAL variable is not recognized as an output variable when the
414 CODE: keyword is present. The OUTPUT: keyword is used in this
415 situation to tell the compiler that RETVAL really is an output
416 variable.
417 The OUTPUT: keyword can also be used to indicate that function
419 parameters are output variables. This may be necessary when a
420 parameter has been modified within the function and the programmer
421 would like the update to be seen by Perl.
422 bool_t
424 rpcb_gettime(host,timep)
425 char *host
426 time_t &timep
427 OUTPUT:
428 timep
429 The OUTPUT: keyword will also allow an output parameter to be mapped to
431 a matching piece of code rather than to a typemap.
432 bool_t
434 rpcb_gettime(host,timep)
435 char *host
436 time_t &timep
437 OUTPUT:
438 timep sv_setnv(ST(1), (double)timep);
439 xsubpp emits an automatic "SvSETMAGIC()" for all parameters in the
441 OUTPUT section of the XSUB, except RETVAL. This is the usually desired
442 behavior, as it takes care of properly invoking 'set' magic on output
443 parameters (needed for hash or array element parameters that must be
444 created if they didn't exist). If for some reason, this behavior is
445 not desired, the OUTPUT section may contain a "SETMAGIC: DISABLE" line
446 to disable it for the remainder of the parameters in the OUTPUT
447 section. Likewise, "SETMAGIC: ENABLE" can be used to reenable it for
448 the remainder of the OUTPUT section. See perlguts for more details
449 about 'set' magic.
450 The NO_OUTPUT Keyword
452 The NO_OUTPUT can be placed as the first token of the XSUB. This
453 keyword indicates that while the C subroutine we provide an interface
454 to has a non-"void" return type, the return value of this C subroutine
455 should not be returned from the generated Perl subroutine.
456 With this keyword present "The RETVAL Variable" is created, and in the
458 generated call to the subroutine this variable is assigned to, but the
459 value of this variable is not going to be used in the auto-generated
460 code.
461 This keyword makes sense only if "RETVAL" is going to be accessed by
463 the user-supplied code. It is especially useful to make a function
464 interface more Perl-like, especially when the C return value is just an
465 error condition indicator. For example,
466 NO_OUTPUT int
468 delete_file(char *name)
469 POSTCALL:
470 if (RETVAL != 0)
471 croak("Error %d while deleting file '%s'", RETVAL, name);
472 Here the generated XS function returns nothing on success, and will
474 die() with a meaningful error message on error.
475 The CODE: Keyword
477 This keyword is used in more complicated XSUBs which require special
478 handling for the C function. The RETVAL variable is still declared,
479 but it will not be returned unless it is specified in the OUTPUT:
480 section.
481 The following XSUB is for a C function which requires special handling
483 of its parameters. The Perl usage is given first.
484 $status = rpcb_gettime( "localhost", $timep );
486 The XSUB follows.
488 bool_t
490 rpcb_gettime(host,timep)
491 char *host
492 time_t timep
493 CODE:
494 RETVAL = rpcb_gettime( host, &timep );
495 OUTPUT:
496 timep
497 RETVAL
498 The INIT: Keyword
500 The INIT: keyword allows initialization to be inserted into the XSUB
501 before the compiler generates the call to the C function. Unlike the
502 CODE: keyword above, this keyword does not affect the way the compiler
503 handles RETVAL.
504 bool_t
506 rpcb_gettime(host,timep)
507 char *host
508 time_t &timep
509 INIT:
510 printf("# Host is %s\n", host );
511 OUTPUT:
512 timep
513 Another use for the INIT: section is to check for preconditions before
515 making a call to the C function:
516 long long
518 lldiv(a,b)
519 long long a
520 long long b
521 INIT:
522 if (a == 0 && b == 0)
523 XSRETURN_UNDEF;
524 if (b == 0)
525 croak("lldiv: cannot divide by 0");
526 The NO_INIT Keyword
528 The NO_INIT keyword is used to indicate that a function parameter is
529 being used only as an output value. The xsubpp compiler will normally
530 generate code to read the values of all function parameters from the
531 argument stack and assign them to C variables upon entry to the
532 function. NO_INIT will tell the compiler that some parameters will be
533 used for output rather than for input and that they will be handled
534 before the function terminates.
535 The following example shows a variation of the rpcb_gettime() function.
537 This function uses the timep variable only as an output variable and
538 does not care about its initial contents.
539 bool_t
541 rpcb_gettime(host,timep)
542 char *host
543 time_t &timep = NO_INIT
544 OUTPUT:
545 timep
546 The TYPEMAP: Keyword
548 Starting with Perl 5.16, you can embed typemaps into your XS code
549 instead of or in addition to typemaps in a separate file. Multiple
550 such embedded typemaps will be processed in order of appearance in the
551 XS code and like local typemap files take precedence over the default
552 typemap, the embedded typemaps may overwrite previous definitions of
553 TYPEMAP, INPUT, and OUTPUT stanzas. The syntax for embedded typemaps
554 is
555 TYPEMAP: <<HERE
557 ... your typemap code here ...
558 HERE
559 where the "TYPEMAP" keyword must appear in the first column of a new
561 line.
562 Refer to perlxstypemap for details on writing typemaps.
564 Initializing Function Parameters
566 C function parameters are normally initialized with their values from
567 the argument stack (which in turn contains the parameters that were
568 passed to the XSUB from Perl). The typemaps contain the code segments
569 which are used to translate the Perl values to the C parameters. The
570 programmer, however, is allowed to override the typemaps and supply
571 alternate (or additional) initialization code. Initialization code
572 starts with the first "=", ";" or "+" on a line in the INPUT: section.
573 The only exception happens if this ";" terminates the line, then this
574 ";" is quietly ignored.
575 The following code demonstrates how to supply initialization code for
577 function parameters. The initialization code is eval'ed within double
578 quotes by the compiler before it is added to the output so anything
579 which should be interpreted literally [mainly "$", "@", or "\\"] must
580 be protected with backslashes. The variables $var, $arg, and $type can
581 be used as in typemaps.
582 bool_t
584 rpcb_gettime(host,timep)
585 char *host = (char *)SvPVbyte_nolen($arg);
586 time_t &timep = 0;
587 OUTPUT:
588 timep
589 This should not be used to supply default values for parameters. One
591 would normally use this when a function parameter must be processed by
592 another library function before it can be used. Default parameters are
593 covered in the next section.
594 If the initialization begins with "=", then it is output in the
596 declaration for the input variable, replacing the initialization
597 supplied by the typemap. If the initialization begins with ";" or "+",
598 then it is performed after all of the input variables have been
599 declared. In the ";" case the initialization normally supplied by the
600 typemap is not performed. For the "+" case, the declaration for the
601 variable will include the initialization from the typemap. A global
602 variable, %v, is available for the truly rare case where information
603 from one initialization is needed in another initialization.
604 Here's a truly obscure example:
606 bool_t
608 rpcb_gettime(host,timep)
609 time_t &timep; /* \$v{timep}=@{[$v{timep}=$arg]} */
610 char *host + SvOK($v{timep}) ? SvPVbyte_nolen($arg) : NULL;
611 OUTPUT:
612 timep
613 The construct "\$v{timep}=@{[$v{timep}=$arg]}" used in the above
615 example has a two-fold purpose: first, when this line is processed by
616 xsubpp, the Perl snippet "$v{timep}=$arg" is evaluated. Second, the
617 text of the evaluated snippet is output into the generated C file
618 (inside a C comment)! During the processing of "char *host" line, $arg
619 will evaluate to ST(0), and $v{timep} will evaluate to ST(1).
620 Default Parameter Values
622 Default values for XSUB arguments can be specified by placing an
623 assignment statement in the parameter list. The default value may be a
624 number, a string or the special string "NO_INIT". Defaults should
625 always be used on the right-most parameters only.
626 To allow the XSUB for rpcb_gettime() to have a default host value the
628 parameters to the XSUB could be rearranged. The XSUB will then call
629 the real rpcb_gettime() function with the parameters in the correct
630 order. This XSUB can be called from Perl with either of the following
631 statements:
632 $status = rpcb_gettime( $timep, $host );
634 $status = rpcb_gettime( $timep );
636 The XSUB will look like the code which follows. A CODE: block is used
638 to call the real rpcb_gettime() function with the parameters in the
639 correct order for that function.
640 bool_t
642 rpcb_gettime(timep,host="localhost")
643 char *host
644 time_t timep = NO_INIT
645 CODE:
646 RETVAL = rpcb_gettime( host, &timep );
647 OUTPUT:
648 timep
649 RETVAL
650 The PREINIT: Keyword
652 The PREINIT: keyword allows extra variables to be declared immediately
653 before or after the declarations of the parameters from the INPUT:
654 section are emitted.
655 If a variable is declared inside a CODE: section it will follow any
657 typemap code that is emitted for the input parameters. This may result
658 in the declaration ending up after C code, which is C syntax error.
659 Similar errors may happen with an explicit ";"-type or "+"-type
660 initialization of parameters is used (see "Initializing Function
661 Parameters"). Declaring these variables in an INIT: section will not
662 help.
663 In such cases, to force an additional variable to be declared together
665 with declarations of other variables, place the declaration into a
666 PREINIT: section. The PREINIT: keyword may be used one or more times
667 within an XSUB.
668 The following examples are equivalent, but if the code is using complex
670 typemaps then the first example is safer.
671 bool_t
673 rpcb_gettime(timep)
674 time_t timep = NO_INIT
675 PREINIT:
676 char *host = "localhost";
677 CODE:
678 RETVAL = rpcb_gettime( host, &timep );
679 OUTPUT:
680 timep
681 RETVAL
682 For this particular case an INIT: keyword would generate the same C
684 code as the PREINIT: keyword. Another correct, but error-prone
685 example:
686 bool_t
688 rpcb_gettime(timep)
689 time_t timep = NO_INIT
690 CODE:
691 char *host = "localhost";
692 RETVAL = rpcb_gettime( host, &timep );
693 OUTPUT:
694 timep
695 RETVAL
696 Another way to declare "host" is to use a C block in the CODE: section:
698 bool_t
700 rpcb_gettime(timep)
701 time_t timep = NO_INIT
702 CODE:
703 {
704 char *host = "localhost";
705 RETVAL = rpcb_gettime( host, &timep );
706 }
707 OUTPUT:
708 timep
709 RETVAL
710 The ability to put additional declarations before the typemap entries
712 are processed is very handy in the cases when typemap conversions
713 manipulate some global state:
714 MyObject
716 mutate(o)
717 PREINIT:
718 MyState st = global_state;
719 INPUT:
720 MyObject o;
721 CLEANUP:
722 reset_to(global_state, st);
723 Here we suppose that conversion to "MyObject" in the INPUT: section and
725 from MyObject when processing RETVAL will modify a global variable
726 "global_state". After these conversions are performed, we restore the
727 old value of "global_state" (to avoid memory leaks, for example).
728 There is another way to trade clarity for compactness: INPUT sections
730 allow declaration of C variables which do not appear in the parameter
731 list of a subroutine. Thus the above code for mutate() can be
732 rewritten as
733 MyObject
735 mutate(o)
736 MyState st = global_state;
737 MyObject o;
738 CLEANUP:
739 reset_to(global_state, st);
740 and the code for rpcb_gettime() can be rewritten as
742 bool_t
744 rpcb_gettime(timep)
745 time_t timep = NO_INIT
746 char *host = "localhost";
747 C_ARGS:
748 host, &timep
749 OUTPUT:
750 timep
751 RETVAL
752 The SCOPE: Keyword
754 The SCOPE: keyword allows scoping to be enabled for a particular XSUB.
755 If enabled, the XSUB will invoke ENTER and LEAVE automatically.
756 To support potentially complex type mappings, if a typemap entry used
758 by an XSUB contains a comment like "/*scope*/" then scoping will be
759 automatically enabled for that XSUB.
760 To enable scoping:
762 SCOPE: ENABLE
764 To disable scoping:
766 SCOPE: DISABLE
768 The INPUT: Keyword
770 The XSUB's parameters are usually evaluated immediately after entering
771 the XSUB. The INPUT: keyword can be used to force those parameters to
772 be evaluated a little later. The INPUT: keyword can be used multiple
773 times within an XSUB and can be used to list one or more input
774 variables. This keyword is used with the PREINIT: keyword.
775 The following example shows how the input parameter "timep" can be
777 evaluated late, after a PREINIT.
778 bool_t
780 rpcb_gettime(host,timep)
781 char *host
782 PREINIT:
783 time_t tt;
784 INPUT:
785 time_t timep
786 CODE:
787 RETVAL = rpcb_gettime( host, &tt );
788 timep = tt;
789 OUTPUT:
790 timep
791 RETVAL
792 The next example shows each input parameter evaluated late.
794 bool_t
796 rpcb_gettime(host,timep)
797 PREINIT:
798 time_t tt;
799 INPUT:
800 char *host
801 PREINIT:
802 char *h;
803 INPUT:
804 time_t timep
805 CODE:
806 h = host;
807 RETVAL = rpcb_gettime( h, &tt );
808 timep = tt;
809 OUTPUT:
810 timep
811 RETVAL
812 Since INPUT sections allow declaration of C variables which do not
814 appear in the parameter list of a subroutine, this may be shortened to:
815 bool_t
817 rpcb_gettime(host,timep)
818 time_t tt;
819 char *host;
820 char *h = host;
821 time_t timep;
822 CODE:
823 RETVAL = rpcb_gettime( h, &tt );
824 timep = tt;
825 OUTPUT:
826 timep
827 RETVAL
828 (We used our knowledge that input conversion for "char *" is a "simple"
830 one, thus "host" is initialized on the declaration line, and our
831 assignment "h = host" is not performed too early. Otherwise one would
832 need to have the assignment "h = host" in a CODE: or INIT: section.)
833 The IN/OUTLIST/IN_OUTLIST/OUT/IN_OUT Keywords
835 In the list of parameters for an XSUB, one can precede parameter names
836 by the "IN"/"OUTLIST"/"IN_OUTLIST"/"OUT"/"IN_OUT" keywords. "IN"
837 keyword is the default, the other keywords indicate how the Perl
838 interface should differ from the C interface.
839 Parameters preceded by "OUTLIST"/"IN_OUTLIST"/"OUT"/"IN_OUT" keywords
841 are considered to be used by the C subroutine via pointers.
842 "OUTLIST"/"OUT" keywords indicate that the C subroutine does not
843 inspect the memory pointed by this parameter, but will write through
844 this pointer to provide additional return values.
845 Parameters preceded by "OUTLIST" keyword do not appear in the usage
847 signature of the generated Perl function.
848 Parameters preceded by "IN_OUTLIST"/"IN_OUT"/"OUT" do appear as
850 parameters to the Perl function. With the exception of
851 "OUT"-parameters, these parameters are converted to the corresponding C
852 type, then pointers to these data are given as arguments to the C
853 function. It is expected that the C function will write through these
854 pointers.
855 The return list of the generated Perl function consists of the C return
857 value from the function (unless the XSUB is of "void" return type or
858 "The NO_OUTPUT Keyword" was used) followed by all the "OUTLIST" and
859 "IN_OUTLIST" parameters (in the order of appearance). On the return
860 from the XSUB the "IN_OUT"/"OUT" Perl parameter will be modified to
861 have the values written by the C function.
862 For example, an XSUB
864 void
866 day_month(OUTLIST day, IN unix_time, OUTLIST month)
867 int day
868 int unix_time
869 int month
870 should be used from Perl as
872 my ($day, $month) = day_month(time);
874 The C signature of the corresponding function should be
876 void day_month(int *day, int unix_time, int *month);
878 The "IN"/"OUTLIST"/"IN_OUTLIST"/"IN_OUT"/"OUT" keywords can be mixed
880 with ANSI-style declarations, as in
881 void
883 day_month(OUTLIST int day, int unix_time, OUTLIST int month)
884 (here the optional "IN" keyword is omitted).
886 The "IN_OUT" parameters are identical with parameters introduced with
888 "The & Unary Operator" and put into the "OUTPUT:" section (see "The
889 OUTPUT: Keyword"). The "IN_OUTLIST" parameters are very similar, the
890 only difference being that the value C function writes through the
891 pointer would not modify the Perl parameter, but is put in the output
892 list.
893 The "OUTLIST"/"OUT" parameter differ from "IN_OUTLIST"/"IN_OUT"
895 parameters only by the initial value of the Perl parameter not being
896 read (and not being given to the C function - which gets some garbage
897 instead). For example, the same C function as above can be interfaced
898 with as
899 void day_month(OUT int day, int unix_time, OUT int month);
901 or
903 void
905 day_month(day, unix_time, month)
906 int &day = NO_INIT
907 int unix_time
908 int &month = NO_INIT
909 OUTPUT:
910 day
911 month
912 However, the generated Perl function is called in very C-ish style:
914 my ($day, $month);
916 day_month($day, time, $month);
917 The "length(NAME)" Keyword
919 If one of the input arguments to the C function is the length of a
920 string argument "NAME", one can substitute the name of the length-
921 argument by "length(NAME)" in the XSUB declaration. This argument must
922 be omitted when the generated Perl function is called. E.g.,
923 void
925 dump_chars(char *s, short l)
926 {
927 short n = 0;
928 while (n < l) {
929 printf("s[%d] = \"\\%#03o\"\n", n, (int)s[n]);
930 n++;
931 }
932 }
933 MODULE = x PACKAGE = x
935 void dump_chars(char *s, short length(s))
937 should be called as "dump_chars($string)".
939 This directive is supported with ANSI-type function declarations only.
941 Variable-length Parameter Lists
943 XSUBs can have variable-length parameter lists by specifying an
944 ellipsis "(...)" in the parameter list. This use of the ellipsis is
945 similar to that found in ANSI C. The programmer is able to determine
946 the number of arguments passed to the XSUB by examining the "items"
947 variable which the xsubpp compiler supplies for all XSUBs. By using
948 this mechanism one can create an XSUB which accepts a list of
949 parameters of unknown length.
950 The host parameter for the rpcb_gettime() XSUB can be optional so the
952 ellipsis can be used to indicate that the XSUB will take a variable
953 number of parameters. Perl should be able to call this XSUB with
954 either of the following statements.
955 $status = rpcb_gettime( $timep, $host );
957 $status = rpcb_gettime( $timep );
959 The XS code, with ellipsis, follows.
961 bool_t
963 rpcb_gettime(timep, ...)
964 time_t timep = NO_INIT
965 PREINIT:
966 char *host = "localhost";
967 CODE:
968 if( items > 1 )
969 host = (char *)SvPVbyte_nolen(ST(1));
970 RETVAL = rpcb_gettime( host, &timep );
971 OUTPUT:
972 timep
973 RETVAL
974 The C_ARGS: Keyword
976 The C_ARGS: keyword allows creating of XSUBS which have different
977 calling sequence from Perl than from C, without a need to write CODE:
978 or PPCODE: section. The contents of the C_ARGS: paragraph is put as
979 the argument to the called C function without any change.
980 For example, suppose that a C function is declared as
982 symbolic nth_derivative(int n, symbolic function, int flags);
984 and that the default flags are kept in a global C variable
986 "default_flags". Suppose that you want to create an interface which is
987 called as
988 $second_deriv = $function->nth_derivative(2);
990 To do this, declare the XSUB as
992 symbolic
994 nth_derivative(function, n)
995 symbolic function
996 int n
997 C_ARGS:
998 n, function, default_flags
999 The PPCODE: Keyword
1001 The PPCODE: keyword is an alternate form of the CODE: keyword and is
1002 used to tell the xsubpp compiler that the programmer is supplying the
1003 code to control the argument stack for the XSUBs return values.
1004 Occasionally one will want an XSUB to return a list of values rather
1005 than a single value. In these cases one must use PPCODE: and then
1006 explicitly push the list of values on the stack. The PPCODE: and CODE:
1007 keywords should not be used together within the same XSUB.
1008 The actual difference between PPCODE: and CODE: sections is in the
1010 initialization of "SP" macro (which stands for the current Perl stack
1011 pointer), and in the handling of data on the stack when returning from
1012 an XSUB. In CODE: sections SP preserves the value which was on entry
1013 to the XSUB: SP is on the function pointer (which follows the last
1014 parameter). In PPCODE: sections SP is moved backward to the beginning
1015 of the parameter list, which allows "PUSH*()" macros to place output
1016 values in the place Perl expects them to be when the XSUB returns back
1017 to Perl.
1018 The generated trailer for a CODE: section ensures that the number of
1020 return values Perl will see is either 0 or 1 (depending on the
1021 "void"ness of the return value of the C function, and heuristics
1022 mentioned in "The RETVAL Variable"). The trailer generated for a
1023 PPCODE: section is based on the number of return values and on the
1024 number of times "SP" was updated by "[X]PUSH*()" macros.
1025 Note that macros ST(i), "XST_m*()" and "XSRETURN*()" work equally well
1027 in CODE: sections and PPCODE: sections.
1028 The following XSUB will call the C rpcb_gettime() function and will
1030 return its two output values, timep and status, to Perl as a single
1031 list.
1032 void
1034 rpcb_gettime(host)
1035 char *host
1036 PREINIT:
1037 time_t timep;
1038 bool_t status;
1039 PPCODE:
1040 status = rpcb_gettime( host, &timep );
1041 EXTEND(SP, 2);
1042 PUSHs(sv_2mortal(newSViv(status)));
1043 PUSHs(sv_2mortal(newSViv(timep)));
1044 Notice that the programmer must supply the C code necessary to have the
1046 real rpcb_gettime() function called and to have the return values
1047 properly placed on the argument stack.
1048 The "void" return type for this function tells the xsubpp compiler that
1050 the RETVAL variable is not needed or used and that it should not be
1051 created. In most scenarios the void return type should be used with
1052 the PPCODE: directive.
1053 The EXTEND() macro is used to make room on the argument stack for 2
1055 return values. The PPCODE: directive causes the xsubpp compiler to
1056 create a stack pointer available as "SP", and it is this pointer which
1057 is being used in the EXTEND() macro. The values are then pushed onto
1058 the stack with the PUSHs() macro.
1059 Now the rpcb_gettime() function can be used from Perl with the
1061 following statement.
1062 ($status, $timep) = rpcb_gettime("localhost");
1064 When handling output parameters with a PPCODE section, be sure to
1066 handle 'set' magic properly. See perlguts for details about 'set'
1067 magic.
1068 Returning Undef And Empty Lists
1070 Occasionally the programmer will want to return simply "undef" or an
1071 empty list if a function fails rather than a separate status value.
1072 The rpcb_gettime() function offers just this situation. If the
1073 function succeeds we would like to have it return the time and if it
1074 fails we would like to have undef returned. In the following Perl code
1075 the value of $timep will either be undef or it will be a valid time.
1076 $timep = rpcb_gettime( "localhost" );
1078 The following XSUB uses the "SV *" return type as a mnemonic only, and
1080 uses a CODE: block to indicate to the compiler that the programmer has
1081 supplied all the necessary code. The sv_newmortal() call will
1082 initialize the return value to undef, making that the default return
1083 value.
1084 SV *
1086 rpcb_gettime(host)
1087 char * host
1088 PREINIT:
1089 time_t timep;
1090 bool_t x;
1091 CODE:
1092 ST(0) = sv_newmortal();
1093 if( rpcb_gettime( host, &timep ) )
1094 sv_setnv( ST(0), (double)timep);
1095 The next example demonstrates how one would place an explicit undef in
1097 the return value, should the need arise.
1098 SV *
1100 rpcb_gettime(host)
1101 char * host
1102 PREINIT:
1103 time_t timep;
1104 bool_t x;
1105 CODE:
1106 if( rpcb_gettime( host, &timep ) ){
1107 ST(0) = sv_newmortal();
1108 sv_setnv( ST(0), (double)timep);
1109 }
1110 else{
1111 ST(0) = &PL_sv_undef;
1112 }
1113 To return an empty list one must use a PPCODE: block and then not push
1115 return values on the stack.
1116 void
1118 rpcb_gettime(host)
1119 char *host
1120 PREINIT:
1121 time_t timep;
1122 PPCODE:
1123 if( rpcb_gettime( host, &timep ) )
1124 PUSHs(sv_2mortal(newSViv(timep)));
1125 else{
1126 /* Nothing pushed on stack, so an empty
1127 * list is implicitly returned. */
1128 }
1129 Some people may be inclined to include an explicit "return" in the
1131 above XSUB, rather than letting control fall through to the end. In
1132 those situations "XSRETURN_EMPTY" should be used, instead. This will
1133 ensure that the XSUB stack is properly adjusted. Consult perlapi for
1134 other "XSRETURN" macros.
1135 Since "XSRETURN_*" macros can be used with CODE blocks as well, one can
1137 rewrite this example as:
1138 int
1140 rpcb_gettime(host)
1141 char *host
1142 PREINIT:
1143 time_t timep;
1144 CODE:
1145 RETVAL = rpcb_gettime( host, &timep );
1146 if (RETVAL == 0)
1147 XSRETURN_UNDEF;
1148 OUTPUT:
1149 RETVAL
1150 In fact, one can put this check into a POSTCALL: section as well.
1152 Together with PREINIT: simplifications, this leads to:
1153 int
1155 rpcb_gettime(host)
1156 char *host
1157 time_t timep;
1158 POSTCALL:
1159 if (RETVAL == 0)
1160 XSRETURN_UNDEF;
1161 The REQUIRE: Keyword
1163 The REQUIRE: keyword is used to indicate the minimum version of the
1164 xsubpp compiler needed to compile the XS module. An XS module which
1165 contains the following statement will compile with only xsubpp version
1166 1.922 or greater:
1167 REQUIRE: 1.922
1169 The CLEANUP: Keyword
1171 This keyword can be used when an XSUB requires special cleanup
1172 procedures before it terminates. When the CLEANUP: keyword is used it
1173 must follow any CODE:, or OUTPUT: blocks which are present in the XSUB.
1174 The code specified for the cleanup block will be added as the last
1175 statements in the XSUB.
1176 The POSTCALL: Keyword
1178 This keyword can be used when an XSUB requires special procedures
1179 executed after the C subroutine call is performed. When the POSTCALL:
1180 keyword is used it must precede OUTPUT: and CLEANUP: blocks which are
1181 present in the XSUB.
1182 See examples in "The NO_OUTPUT Keyword" and "Returning Undef And Empty
1184 Lists".
1185 The POSTCALL: block does not make a lot of sense when the C subroutine
1187 call is supplied by user by providing either CODE: or PPCODE: section.
1188 The BOOT: Keyword
1190 The BOOT: keyword is used to add code to the extension's bootstrap
1191 function. The bootstrap function is generated by the xsubpp compiler
1192 and normally holds the statements necessary to register any XSUBs with
1193 Perl. With the BOOT: keyword the programmer can tell the compiler to
1194 add extra statements to the bootstrap function.
1195 This keyword may be used any time after the first MODULE keyword and
1197 should appear on a line by itself. The first blank line after the
1198 keyword will terminate the code block.
1199 BOOT:
1201 # The following message will be printed when the
1202 # bootstrap function executes.
1203 printf("Hello from the bootstrap!\n");
1204 The VERSIONCHECK: Keyword
1206 The VERSIONCHECK: keyword corresponds to xsubpp's "-versioncheck" and
1207 "-noversioncheck" options. This keyword overrides the command line
1208 options. Version checking is enabled by default. When version
1209 checking is enabled the XS module will attempt to verify that its
1210 version matches the version of the PM module.
1211 To enable version checking:
1213 VERSIONCHECK: ENABLE
1215 To disable version checking:
1217 VERSIONCHECK: DISABLE
1219 Note that if the version of the PM module is an NV (a floating point
1221 number), it will be stringified with a possible loss of precision
1222 (currently chopping to nine decimal places) so that it may not match
1223 the version of the XS module anymore. Quoting the $VERSION declaration
1224 to make it a string is recommended if long version numbers are used.
1225 The PROTOTYPES: Keyword
1227 The PROTOTYPES: keyword corresponds to xsubpp's "-prototypes" and
1228 "-noprototypes" options. This keyword overrides the command line
1229 options. Prototypes are disabled by default. When prototypes are
1230 enabled, XSUBs will be given Perl prototypes. This keyword may be used
1231 multiple times in an XS module to enable and disable prototypes for
1232 different parts of the module. Note that xsubpp will nag you if you
1233 don't explicitly enable or disable prototypes, with:
1234 Please specify prototyping behavior for Foo.xs (see perlxs manual)
1236 To enable prototypes:
1238 PROTOTYPES: ENABLE
1240 To disable prototypes:
1242 PROTOTYPES: DISABLE
1244 The PROTOTYPE: Keyword
1246 This keyword is similar to the PROTOTYPES: keyword above but can be
1247 used to force xsubpp to use a specific prototype for the XSUB. This
1248 keyword overrides all other prototype options and keywords but affects
1249 only the current XSUB. Consult "Prototypes" in perlsub for information
1250 about Perl prototypes.
1251 bool_t
1253 rpcb_gettime(timep, ...)
1254 time_t timep = NO_INIT
1255 PROTOTYPE: $;$
1256 PREINIT:
1257 char *host = "localhost";
1258 CODE:
1259 if( items > 1 )
1260 host = (char *)SvPVbyte_nolen(ST(1));
1261 RETVAL = rpcb_gettime( host, &timep );
1262 OUTPUT:
1263 timep
1264 RETVAL
1265 If the prototypes are enabled, you can disable it locally for a given
1267 XSUB as in the following example:
1268 void
1270 rpcb_gettime_noproto()
1271 PROTOTYPE: DISABLE
1272 ...
1273 The ALIAS: Keyword
1275 The ALIAS: keyword allows an XSUB to have two or more unique Perl names
1276 and to know which of those names was used when it was invoked. The
1277 Perl names may be fully-qualified with package names. Each alias is
1278 given an index. The compiler will setup a variable called "ix" which
1279 contain the index of the alias which was used. When the XSUB is called
1280 with its declared name "ix" will be 0.
1281 The following example will create aliases "FOO::gettime()" and
1283 "BAR::getit()" for this function.
1284 bool_t
1286 rpcb_gettime(host,timep)
1287 char *host
1288 time_t &timep
1289 ALIAS:
1290 FOO::gettime = 1
1291 BAR::getit = 2
1292 INIT:
1293 printf("# ix = %d\n", ix );
1294 OUTPUT:
1295 timep
1296 The OVERLOAD: Keyword
1298 Instead of writing an overloaded interface using pure Perl, you can
1299 also use the OVERLOAD keyword to define additional Perl names for your
1300 functions (like the ALIAS: keyword above). However, the overloaded
1301 functions must be defined in such a way as to accept the number of
1302 parameters supplied by perl's overload system. For most overload
1303 methods, it will be three parameters; for the "nomethod" function it
1304 will be four. However, the bitwise operators "&", "|", "^", and "~"
1305 may be called with three or five arguments (see overload).
1306 If any function has the OVERLOAD: keyword, several additional lines
1308 will be defined in the c file generated by xsubpp in order to register
1309 with the overload magic.
1310 Since blessed objects are actually stored as RV's, it is useful to use
1312 the typemap features to preprocess parameters and extract the actual SV
1313 stored within the blessed RV. See the sample for T_PTROBJ_SPECIAL
1314 below.
1315 To use the OVERLOAD: keyword, create an XS function which takes three
1317 input parameters (or use the C-style '...' definition) like this:
1318 SV *
1320 cmp (lobj, robj, swap)
1321 My_Module_obj lobj
1322 My_Module_obj robj
1323 IV swap
1324 OVERLOAD: cmp <=>
1325 { /* function defined here */}
1326 In this case, the function will overload both of the three way
1328 comparison operators. For all overload operations using non-alpha
1329 characters, you must type the parameter without quoting, separating
1330 multiple overloads with whitespace. Note that "" (the stringify
1331 overload) should be entered as \"\" (i.e. escaped).
1332 Since, as mentioned above, bitwise operators may take extra arguments,
1334 you may want to use something like "(lobj, robj, swap, ...)" (with
1335 literal "...") as your parameter list.
1336 The FALLBACK: Keyword
1338 In addition to the OVERLOAD keyword, if you need to control how Perl
1339 autogenerates missing overloaded operators, you can set the FALLBACK
1340 keyword in the module header section, like this:
1341 MODULE = RPC PACKAGE = RPC
1343 FALLBACK: TRUE
1345 ...
1346 where FALLBACK can take any of the three values TRUE, FALSE, or UNDEF.
1348 If you do not set any FALLBACK value when using OVERLOAD, it defaults
1349 to UNDEF. FALLBACK is not used except when one or more functions using
1350 OVERLOAD have been defined. Please see "fallback" in overload for more
1351 details.
1352 The INTERFACE: Keyword
1354 This keyword declares the current XSUB as a keeper of the given calling
1355 signature. If some text follows this keyword, it is considered as a
1356 list of functions which have this signature, and should be attached to
1357 the current XSUB.
1358 For example, if you have 4 C functions multiply(), divide(), add(),
1360 subtract() all having the signature:
1361 symbolic f(symbolic, symbolic);
1363 you can make them all to use the same XSUB using this:
1365 symbolic
1367 interface_s_ss(arg1, arg2)
1368 symbolic arg1
1369 symbolic arg2
1370 INTERFACE:
1371 multiply divide
1372 add subtract
1373 (This is the complete XSUB code for 4 Perl functions!) Four generated
1375 Perl function share names with corresponding C functions.
1376 The advantage of this approach comparing to ALIAS: keyword is that
1378 there is no need to code a switch statement, each Perl function (which
1379 shares the same XSUB) knows which C function it should call.
1380 Additionally, one can attach an extra function remainder() at runtime
1381 by using
1382 CV *mycv = newXSproto("Symbolic::remainder",
1384 XS_Symbolic_interface_s_ss, __FILE__, "$$");
1385 XSINTERFACE_FUNC_SET(mycv, remainder);
1386 say, from another XSUB. (This example supposes that there was no
1388 INTERFACE_MACRO: section, otherwise one needs to use something else
1389 instead of "XSINTERFACE_FUNC_SET", see the next section.)
1390 The INTERFACE_MACRO: Keyword
1392 This keyword allows one to define an INTERFACE using a different way to
1393 extract a function pointer from an XSUB. The text which follows this
1394 keyword should give the name of macros which would extract/set a
1395 function pointer. The extractor macro is given return type, "CV*", and
1396 "XSANY.any_dptr" for this "CV*". The setter macro is given cv, and the
1397 function pointer.
1398 The default value is "XSINTERFACE_FUNC" and "XSINTERFACE_FUNC_SET". An
1400 INTERFACE keyword with an empty list of functions can be omitted if
1401 INTERFACE_MACRO keyword is used.
1402 Suppose that in the previous example functions pointers for multiply(),
1404 divide(), add(), subtract() are kept in a global C array "fp[]" with
1405 offsets being "multiply_off", "divide_off", "add_off", "subtract_off".
1406 Then one can use
1407 #define XSINTERFACE_FUNC_BYOFFSET(ret,cv,f) \
1409 ((XSINTERFACE_CVT_ANON(ret))fp[CvXSUBANY(cv).any_i32])
1410 #define XSINTERFACE_FUNC_BYOFFSET_set(cv,f) \
1411 CvXSUBANY(cv).any_i32 = CAT2( f, _off )
1412 in C section,
1414 symbolic
1416 interface_s_ss(arg1, arg2)
1417 symbolic arg1
1418 symbolic arg2
1419 INTERFACE_MACRO:
1420 XSINTERFACE_FUNC_BYOFFSET
1421 XSINTERFACE_FUNC_BYOFFSET_set
1422 INTERFACE:
1423 multiply divide
1424 add subtract
1425 in XSUB section.
1427 The INCLUDE: Keyword
1429 This keyword can be used to pull other files into the XS module. The
1430 other files may have XS code. INCLUDE: can also be used to run a
1431 command to generate the XS code to be pulled into the module.
1432 The file Rpcb1.xsh contains our "rpcb_gettime()" function:
1434 bool_t
1436 rpcb_gettime(host,timep)
1437 char *host
1438 time_t &timep
1439 OUTPUT:
1440 timep
1441 The XS module can use INCLUDE: to pull that file into it.
1443 INCLUDE: Rpcb1.xsh
1445 If the parameters to the INCLUDE: keyword are followed by a pipe ("|")
1447 then the compiler will interpret the parameters as a command. This
1448 feature is mildly deprecated in favour of the "INCLUDE_COMMAND:"
1449 directive, as documented below.
1450 INCLUDE: cat Rpcb1.xsh |
1452 Do not use this to run perl: "INCLUDE: perl |" will run the perl that
1454 happens to be the first in your path and not necessarily the same perl
1455 that is used to run "xsubpp". See "The INCLUDE_COMMAND: Keyword".
1456 The INCLUDE_COMMAND: Keyword
1458 Runs the supplied command and includes its output into the current XS
1459 document. "INCLUDE_COMMAND" assigns special meaning to the $^X token in
1460 that it runs the same perl interpreter that is running "xsubpp":
1461 INCLUDE_COMMAND: cat Rpcb1.xsh
1463 INCLUDE_COMMAND: $^X -e ...
1465 The CASE: Keyword
1467 The CASE: keyword allows an XSUB to have multiple distinct parts with
1468 each part acting as a virtual XSUB. CASE: is greedy and if it is used
1469 then all other XS keywords must be contained within a CASE:. This
1470 means nothing may precede the first CASE: in the XSUB and anything
1471 following the last CASE: is included in that case.
1472 A CASE: might switch via a parameter of the XSUB, via the "ix" ALIAS:
1474 variable (see "The ALIAS: Keyword"), or maybe via the "items" variable
1475 (see "Variable-length Parameter Lists"). The last CASE: becomes the
1476 default case if it is not associated with a conditional. The following
1477 example shows CASE switched via "ix" with a function "rpcb_gettime()"
1478 having an alias "x_gettime()". When the function is called as
1479 "rpcb_gettime()" its parameters are the usual "(char *host, time_t
1480 *timep)", but when the function is called as "x_gettime()" its
1481 parameters are reversed, "(time_t *timep, char *host)".
1482 long
1484 rpcb_gettime(a,b)
1485 CASE: ix == 1
1486 ALIAS:
1487 x_gettime = 1
1488 INPUT:
1489 # 'a' is timep, 'b' is host
1490 char *b
1491 time_t a = NO_INIT
1492 CODE:
1493 RETVAL = rpcb_gettime( b, &a );
1494 OUTPUT:
1495 a
1496 RETVAL
1497 CASE:
1498 # 'a' is host, 'b' is timep
1499 char *a
1500 time_t &b = NO_INIT
1501 OUTPUT:
1502 b
1503 RETVAL
1504 That function can be called with either of the following statements.
1506 Note the different argument lists.
1507 $status = rpcb_gettime( $host, $timep );
1509 $status = x_gettime( $timep, $host );
1511 The EXPORT_XSUB_SYMBOLS: Keyword
1513 The EXPORT_XSUB_SYMBOLS: keyword is likely something you will never
1514 need. In perl versions earlier than 5.16.0, this keyword does nothing.
1515 Starting with 5.16, XSUB symbols are no longer exported by default.
1516 That is, they are "static" functions. If you include
1517 EXPORT_XSUB_SYMBOLS: ENABLE
1519 in your XS code, the XSUBs following this line will not be declared
1521 "static". You can later disable this with
1522 EXPORT_XSUB_SYMBOLS: DISABLE
1524 which, again, is the default that you should probably never change.
1526 You cannot use this keyword on versions of perl before 5.16 to make
1527 XSUBs "static".
1528 The & Unary Operator
1530 The "&" unary operator in the INPUT: section is used to tell xsubpp
1531 that it should convert a Perl value to/from C using the C type to the
1532 left of "&", but provide a pointer to this value when the C function is
1533 called.
1534 This is useful to avoid a CODE: block for a C function which takes a
1536 parameter by reference. Typically, the parameter should be not a
1537 pointer type (an "int" or "long" but not an "int*" or "long*").
1538 The following XSUB will generate incorrect C code. The xsubpp compiler
1540 will turn this into code which calls "rpcb_gettime()" with parameters
1541 "(char *host, time_t timep)", but the real "rpcb_gettime()" wants the
1542 "timep" parameter to be of type "time_t*" rather than "time_t".
1543 bool_t
1545 rpcb_gettime(host,timep)
1546 char *host
1547 time_t timep
1548 OUTPUT:
1549 timep
1550 That problem is corrected by using the "&" operator. The xsubpp
1552 compiler will now turn this into code which calls "rpcb_gettime()"
1553 correctly with parameters "(char *host, time_t *timep)". It does this
1554 by carrying the "&" through, so the function call looks like
1555 "rpcb_gettime(host, &timep)".
1556 bool_t
1558 rpcb_gettime(host,timep)
1559 char *host
1560 time_t &timep
1561 OUTPUT:
1562 timep
1563 Inserting POD, Comments and C Preprocessor Directives
1565 C preprocessor directives are allowed within BOOT:, PREINIT: INIT:,
1566 CODE:, PPCODE:, POSTCALL:, and CLEANUP: blocks, as well as outside the
1567 functions. Comments are allowed anywhere after the MODULE keyword.
1568 The compiler will pass the preprocessor directives through untouched
1569 and will remove the commented lines. POD documentation is allowed at
1570 any point, both in the C and XS language sections. POD must be
1571 terminated with a "=cut" command; "xsubpp" will exit with an error if
1572 it does not. It is very unlikely that human generated C code will be
1573 mistaken for POD, as most indenting styles result in whitespace in
1574 front of any line starting with "=". Machine generated XS files may
1575 fall into this trap unless care is taken to ensure that a space breaks
1576 the sequence "\n=".
1577 Comments can be added to XSUBs by placing a "#" as the first non-
1579 whitespace of a line. Care should be taken to avoid making the comment
1580 look like a C preprocessor directive, lest it be interpreted as such.
1581 The simplest way to prevent this is to put whitespace in front of the
1582 "#".
1583 If you use preprocessor directives to choose one of two versions of a
1585 function, use
1586 #if ... version1
1588 #else /* ... version2 */
1589 #endif
1590 and not
1592 #if ... version1
1594 #endif
1595 #if ... version2
1596 #endif
1597 because otherwise xsubpp will believe that you made a duplicate
1599 definition of the function. Also, put a blank line before the
1600 #else/#endif so it will not be seen as part of the function body.
1601 Using XS With C++
1603 If an XSUB name contains "::", it is considered to be a C++ method.
1604 The generated Perl function will assume that its first argument is an
1605 object pointer. The object pointer will be stored in a variable called
1606 THIS. The object should have been created by C++ with the new()
1607 function and should be blessed by Perl with the sv_setref_pv() macro.
1608 The blessing of the object by Perl can be handled by a typemap. An
1609 example typemap is shown at the end of this section.
1610 If the return type of the XSUB includes "static", the method is
1612 considered to be a static method. It will call the C++ function using
1613 the class::method() syntax. If the method is not static the function
1614 will be called using the THIS->method() syntax.
1615 The next examples will use the following C++ class.
1617 class color {
1619 public:
1620 color();
1621 ~color();
1622 int blue();
1623 void set_blue( int );
1624 private:
1626 int c_blue;
1627 };
1628 The XSUBs for the blue() and set_blue() methods are defined with the
1630 class name but the parameter for the object (THIS, or "self") is
1631 implicit and is not listed.
1632 int
1634 color::blue()
1635 void
1637 color::set_blue( val )
1638 int val
1639 Both Perl functions will expect an object as the first parameter. In
1641 the generated C++ code the object is called "THIS", and the method call
1642 will be performed on this object. So in the C++ code the blue() and
1643 set_blue() methods will be called as this:
1644 RETVAL = THIS->blue();
1646 THIS->set_blue( val );
1648 You could also write a single get/set method using an optional
1650 argument:
1651 int
1653 color::blue( val = NO_INIT )
1654 int val
1655 PROTOTYPE $;$
1656 CODE:
1657 if (items > 1)
1658 THIS->set_blue( val );
1659 RETVAL = THIS->blue();
1660 OUTPUT:
1661 RETVAL
1662 If the function's name is DESTROY then the C++ "delete" function will
1664 be called and "THIS" will be given as its parameter. The generated C++
1665 code for
1666 void
1668 color::DESTROY()
1669 will look like this:
1671 color *THIS = ...; // Initialized as in typemap
1673 delete THIS;
1675 If the function's name is new then the C++ "new" function will be
1677 called to create a dynamic C++ object. The XSUB will expect the class
1678 name, which will be kept in a variable called "CLASS", to be given as
1679 the first argument.
1680 color *
1682 color::new()
1683 The generated C++ code will call "new".
1685 RETVAL = new color();
1687 The following is an example of a typemap that could be used for this
1689 C++ example.
1690 TYPEMAP
1692 color * O_OBJECT
1693 OUTPUT
1695 # The Perl object is blessed into 'CLASS', which should be a
1696 # char* having the name of the package for the blessing.
1697 O_OBJECT
1698 sv_setref_pv( $arg, CLASS, (void*)$var );
1699 INPUT
1701 O_OBJECT
1702 if( sv_isobject($arg) && (SvTYPE(SvRV($arg)) == SVt_PVMG) )
1703 $var = ($type)SvIV((SV*)SvRV( $arg ));
1704 else{
1705 warn(\"${Package}::$func_name() -- \"
1706 \"$var is not a blessed SV reference\");
1707 XSRETURN_UNDEF;
1708 }
1709 Interface Strategy
1711 When designing an interface between Perl and a C library a straight
1712 translation from C to XS (such as created by "h2xs -x") is often
1713 sufficient. However, sometimes the interface will look very C-like and
1714 occasionally nonintuitive, especially when the C function modifies one
1715 of its parameters, or returns failure inband (as in "negative return
1716 values mean failure"). In cases where the programmer wishes to create
1717 a more Perl-like interface the following strategy may help to identify
1718 the more critical parts of the interface.
1719 Identify the C functions with input/output or output parameters. The
1721 XSUBs for these functions may be able to return lists to Perl.
1722 Identify the C functions which use some inband info as an indication of
1724 failure. They may be candidates to return undef or an empty list in
1725 case of failure. If the failure may be detected without a call to the
1726 C function, you may want to use an INIT: section to report the failure.
1727 For failures detectable after the C function returns one may want to
1728 use a POSTCALL: section to process the failure. In more complicated
1729 cases use CODE: or PPCODE: sections.
1730 If many functions use the same failure indication based on the return
1732 value, you may want to create a special typedef to handle this
1733 situation. Put
1734 typedef int negative_is_failure;
1736 near the beginning of XS file, and create an OUTPUT typemap entry for
1738 "negative_is_failure" which converts negative values to "undef", or
1739 maybe croak()s. After this the return value of type
1740 "negative_is_failure" will create more Perl-like interface.
1741 Identify which values are used by only the C and XSUB functions
1743 themselves, say, when a parameter to a function should be a contents of
1744 a global variable. If Perl does not need to access the contents of the
1745 value then it may not be necessary to provide a translation for that
1746 value from C to Perl.
1747 Identify the pointers in the C function parameter lists and return
1749 values. Some pointers may be used to implement input/output or output
1750 parameters, they can be handled in XS with the "&" unary operator, and,
1751 possibly, using the NO_INIT keyword. Some others will require handling
1752 of types like "int *", and one needs to decide what a useful Perl
1753 translation will do in such a case. When the semantic is clear, it is
1754 advisable to put the translation into a typemap file.
1755 Identify the structures used by the C functions. In many cases it may
1757 be helpful to use the T_PTROBJ typemap for these structures so they can
1758 be manipulated by Perl as blessed objects. (This is handled
1759 automatically by "h2xs -x".)
1760 If the same C type is used in several different contexts which require
1762 different translations, "typedef" several new types mapped to this C
1763 type, and create separate typemap entries for these new types. Use
1764 these types in declarations of return type and parameters to XSUBs.
1765 Perl Objects And C Structures
1767 When dealing with C structures one should select either T_PTROBJ or
1768 T_PTRREF for the XS type. Both types are designed to handle pointers
1769 to complex objects. The T_PTRREF type will allow the Perl object to be
1770 unblessed while the T_PTROBJ type requires that the object be blessed.
1771 By using T_PTROBJ one can achieve a form of type-checking because the
1772 XSUB will attempt to verify that the Perl object is of the expected
1773 type.
1774 The following XS code shows the getnetconfigent() function which is
1776 used with ONC+ TIRPC. The getnetconfigent() function will return a
1777 pointer to a C structure and has the C prototype shown below. The
1778 example will demonstrate how the C pointer will become a Perl
1779 reference. Perl will consider this reference to be a pointer to a
1780 blessed object and will attempt to call a destructor for the object. A
1781 destructor will be provided in the XS source to free the memory used by
1782 getnetconfigent(). Destructors in XS can be created by specifying an
1783 XSUB function whose name ends with the word DESTROY. XS destructors
1784 can be used to free memory which may have been malloc'd by another
1785 XSUB.
1786 struct netconfig *getnetconfigent(const char *netid);
1788 A "typedef" will be created for "struct netconfig". The Perl object
1790 will be blessed in a class matching the name of the C type, with the
1791 tag "Ptr" appended, and the name should not have embedded spaces if it
1792 will be a Perl package name. The destructor will be placed in a class
1793 corresponding to the class of the object and the PREFIX keyword will be
1794 used to trim the name to the word DESTROY as Perl will expect.
1795 typedef struct netconfig Netconfig;
1797 MODULE = RPC PACKAGE = RPC
1799 Netconfig *
1801 getnetconfigent(netid)
1802 char *netid
1803 MODULE = RPC PACKAGE = NetconfigPtr PREFIX = rpcb_
1805 void
1807 rpcb_DESTROY(netconf)
1808 Netconfig *netconf
1809 CODE:
1810 printf("Now in NetconfigPtr::DESTROY\n");
1811 free( netconf );
1812 This example requires the following typemap entry. Consult
1814 perlxstypemap for more information about adding new typemaps for an
1815 extension.
1816 TYPEMAP
1818 Netconfig * T_PTROBJ
1819 This example will be used with the following Perl statements.
1821 use RPC;
1823 $netconf = getnetconfigent("udp");
1824 When Perl destroys the object referenced by $netconf it will send the
1826 object to the supplied XSUB DESTROY function. Perl cannot determine,
1827 and does not care, that this object is a C struct and not a Perl
1828 object. In this sense, there is no difference between the object
1829 created by the getnetconfigent() XSUB and an object created by a normal
1830 Perl subroutine.
1831 Safely Storing Static Data in XS
1833 Starting with Perl 5.8, a macro framework has been defined to allow
1834 static data to be safely stored in XS modules that will be accessed
1835 from a multi-threaded Perl.
1836 Although primarily designed for use with multi-threaded Perl, the
1838 macros have been designed so that they will work with non-threaded Perl
1839 as well.
1840 It is therefore strongly recommended that these macros be used by all
1842 XS modules that make use of static data.
1843 The easiest way to get a template set of macros to use is by specifying
1845 the "-g" ("--global") option with h2xs (see h2xs).
1846 Below is an example module that makes use of the macros.
1848 #define PERL_NO_GET_CONTEXT
1850 #include "EXTERN.h"
1851 #include "perl.h"
1852 #include "XSUB.h"
1853 /* Global Data */
1855 #define MY_CXT_KEY "BlindMice::_guts" XS_VERSION
1857 typedef struct {
1859 int count;
1860 char name[3][100];
1861 } my_cxt_t;
1862 START_MY_CXT
1864 MODULE = BlindMice PACKAGE = BlindMice
1866 BOOT:
1868 {
1869 MY_CXT_INIT;
1870 MY_CXT.count = 0;
1871 strcpy(MY_CXT.name[0], "None");
1872 strcpy(MY_CXT.name[1], "None");
1873 strcpy(MY_CXT.name[2], "None");
1874 }
1875 int
1877 newMouse(char * name)
1878 PREINIT:
1879 dMY_CXT;
1880 CODE:
1881 if (MY_CXT.count >= 3) {
1882 warn("Already have 3 blind mice");
1883 RETVAL = 0;
1884 }
1885 else {
1886 RETVAL = ++ MY_CXT.count;
1887 strcpy(MY_CXT.name[MY_CXT.count - 1], name);
1888 }
1889 OUTPUT:
1890 RETVAL
1891 char *
1893 get_mouse_name(index)
1894 int index
1895 PREINIT:
1896 dMY_CXT;
1897 CODE:
1898 if (index > MY_CXT.count)
1899 croak("There are only 3 blind mice.");
1900 else
1901 RETVAL = MY_CXT.name[index - 1];
1902 OUTPUT:
1903 RETVAL
1904 void
1906 CLONE(...)
1907 CODE:
1908 MY_CXT_CLONE;
1909 MY_CXT REFERENCE
1911 MY_CXT_KEY
1913 This macro is used to define a unique key to refer to the static
1914 data for an XS module. The suggested naming scheme, as used by
1915 h2xs, is to use a string that consists of the module name, the
1916 string "::_guts" and the module version number.
1917 #define MY_CXT_KEY "MyModule::_guts" XS_VERSION
1919 typedef my_cxt_t
1921 This struct typedef must always be called "my_cxt_t". The other
1922 "CXT*" macros assume the existence of the "my_cxt_t" typedef name.
1923 Declare a typedef named "my_cxt_t" that is a structure that
1925 contains all the data that needs to be interpreter-local.
1926 typedef struct {
1928 int some_value;
1929 } my_cxt_t;
1930 START_MY_CXT
1932 Always place the START_MY_CXT macro directly after the declaration
1933 of "my_cxt_t".
1934 MY_CXT_INIT
1936 The MY_CXT_INIT macro initializes storage for the "my_cxt_t"
1937 struct.
1938 It must be called exactly once, typically in a BOOT: section. If
1940 you are maintaining multiple interpreters, it should be called
1941 once in each interpreter instance, except for interpreters cloned
1942 from existing ones. (But see "MY_CXT_CLONE" below.)
1943 dMY_CXT
1945 Use the dMY_CXT macro (a declaration) in all the functions that
1946 access MY_CXT.
1947 MY_CXT
1949 Use the MY_CXT macro to access members of the "my_cxt_t" struct.
1950 For example, if "my_cxt_t" is
1951 typedef struct {
1953 int index;
1954 } my_cxt_t;
1955 then use this to access the "index" member
1957 dMY_CXT;
1959 MY_CXT.index = 2;
1960 aMY_CXT/pMY_CXT
1962 "dMY_CXT" may be quite expensive to calculate, and to avoid the
1963 overhead of invoking it in each function it is possible to pass
1964 the declaration onto other functions using the "aMY_CXT"/"pMY_CXT"
1965 macros, eg
1966 void sub1() {
1968 dMY_CXT;
1969 MY_CXT.index = 1;
1970 sub2(aMY_CXT);
1971 }
1972 void sub2(pMY_CXT) {
1974 MY_CXT.index = 2;
1975 }
1976 Analogously to "pTHX", there are equivalent forms for when the
1978 macro is the first or last in multiple arguments, where an
1979 underscore represents a comma, i.e. "_aMY_CXT", "aMY_CXT_",
1980 "_pMY_CXT" and "pMY_CXT_".
1981 MY_CXT_CLONE
1983 By default, when a new interpreter is created as a copy of an
1984 existing one (eg via "threads->create()"), both interpreters share
1985 the same physical my_cxt_t structure. Calling "MY_CXT_CLONE"
1986 (typically via the package's "CLONE()" function), causes a byte-
1987 for-byte copy of the structure to be taken, and any future dMY_CXT
1988 will cause the copy to be accessed instead.
1989 MY_CXT_INIT_INTERP(my_perl)
1991 dMY_CXT_INTERP(my_perl)
1992 These are versions of the macros which take an explicit
1993 interpreter as an argument.
1994 Note that these macros will only work together within the same source
1996 file; that is, a dMY_CTX in one source file will access a different
1997 structure than a dMY_CTX in another source file.
1998 Thread-aware system interfaces
2000 Starting from Perl 5.8, in C/C++ level Perl knows how to wrap
2001 system/library interfaces that have thread-aware versions (e.g.
2002 getpwent_r()) into frontend macros (e.g. getpwent()) that correctly
2003 handle the multithreaded interaction with the Perl interpreter. This
2004 will happen transparently, the only thing you need to do is to
2005 instantiate a Perl interpreter.
2006 This wrapping happens always when compiling Perl core source (PERL_CORE
2008 is defined) or the Perl core extensions (PERL_EXT is defined). When
2009 compiling XS code outside of the Perl core, the wrapping does not take
2010 place before Perl 5.28. Starting in that release you can
2011 #define PERL_REENTRANT
2013 in your code to enable the wrapping. It is advisable to do so if you
2015 are using such functions, as intermixing the "_r"-forms (as Perl
2016 compiled for multithreaded operation will do) and the "_r"-less forms
2017 is neither well-defined (inconsistent results, data corruption, or even
2018 crashes become more likely), nor is it very portable. Unfortunately,
2019 not all systems have all the "_r" forms, but using this "#define" gives
2020 you whatever protection that Perl is aware is available on each system.
2021
2023 File "RPC.xs": Interface to some ONC+ RPC bind library functions.
2024 #define PERL_NO_GET_CONTEXT
2026 #include "EXTERN.h"
2027 #include "perl.h"
2028 #include "XSUB.h"
2029 /* Note: On glibc 2.13 and earlier, this needs be <rpc/rpc.h> */
2031 #include <tirpc/rpc.h>
2032 typedef struct netconfig Netconfig;
2034 MODULE = RPC PACKAGE = RPC
2036 SV *
2038 rpcb_gettime(host="localhost")
2039 char *host
2040 PREINIT:
2041 time_t timep;
2042 CODE:
2043 ST(0) = sv_newmortal();
2044 if( rpcb_gettime( host, &timep ) )
2045 sv_setnv( ST(0), (double)timep );
2046 Netconfig *
2048 getnetconfigent(netid="udp")
2049 char *netid
2050 MODULE = RPC PACKAGE = NetconfigPtr PREFIX = rpcb_
2052 void
2054 rpcb_DESTROY(netconf)
2055 Netconfig *netconf
2056 CODE:
2057 printf("NetconfigPtr::DESTROY\n");
2058 free( netconf );
2059 File "typemap": Custom typemap for RPC.xs. (cf. perlxstypemap)
2061 TYPEMAP
2063 Netconfig * T_PTROBJ
2064 File "RPC.pm": Perl module for the RPC extension.
2066 package RPC;
2068 require Exporter;
2070 require DynaLoader;
2071 @ISA = qw(Exporter DynaLoader);
2072 @EXPORT = qw(rpcb_gettime getnetconfigent);
2073 bootstrap RPC;
2075 1;
2076 File "rpctest.pl": Perl test program for the RPC extension.
2078 use RPC;
2080 $netconf = getnetconfigent();
2082 $a = rpcb_gettime();
2083 print "time = $a\n";
2084 print "netconf = $netconf\n";
2085 $netconf = getnetconfigent("tcp");
2087 $a = rpcb_gettime("poplar");
2088 print "time = $a\n";
2089 print "netconf = $netconf\n";
2090 In Makefile.PL add -ltirpc and -I/usr/include/tirpc.
2092
2094 XS code has full access to system calls including C library functions.
2095 It thus has the capability of interfering with things that the Perl
2096 core or other modules have set up, such as signal handlers or file
2097 handles. It could mess with the memory, or any number of harmful
2098 things. Don't.
2099 Some modules have an event loop, waiting for user-input. It is highly
2101 unlikely that two such modules would work adequately together in a
2102 single Perl application.
2103 In general, the perl interpreter views itself as the center of the
2105 universe as far as the Perl program goes. XS code is viewed as a help-
2106 mate, to accomplish things that perl doesn't do, or doesn't do fast
2107 enough, but always subservient to perl. The closer XS code adheres to
2108 this model, the less likely conflicts will occur.
2109 One area where there has been conflict is in regards to C locales.
2111 (See perllocale.) perl, with one exception and unless told otherwise,
2112 sets up the underlying locale the program is running in to the locale
2113 passed into it from the environment. This is an important difference
2114 from a generic C language program, where the underlying locale is the
2115 "C" locale unless the program changes it. As of v5.20, this underlying
2116 locale is completely hidden from pure Perl code outside the lexical
2117 scope of "use locale" except for a couple of function calls in the
2118 POSIX module which of necessity use it. But the underlying locale,
2119 with that one exception is exposed to XS code, affecting all C library
2120 routines whose behavior is locale-dependent. Your XS code better not
2121 assume that the underlying locale is "C". The exception is the
2122 "LC_NUMERIC" locale category, and the reason it is an exception is that
2123 experience has shown that it can be problematic for XS code, whereas we
2124 have not had reports of problems with the other locale categories. And
2125 the reason for this one category being problematic is that the
2126 character used as a decimal point can vary. Many European languages
2127 use a comma, whereas English, and hence Perl are expecting a dot
2128 (U+002E: FULL STOP). Many modules can handle only the radix character
2129 being a dot, and so perl attempts to make it so. Up through Perl
2130 v5.20, the attempt was merely to set "LC_NUMERIC" upon startup to the
2131 "C" locale. Any setlocale() otherwise would change it; this caused
2132 some failures. Therefore, starting in v5.22, perl tries to keep
2133 "LC_NUMERIC" always set to "C" for XS code.
2134 To summarize, here's what to expect and how to handle locales in XS
2136 code:
2137 Non-locale-aware XS code
2139 Keep in mind that even if you think your code is not locale-aware,
2140 it may call a library function that is. Hopefully the man page for
2141 such a function will indicate that dependency, but the
2142 documentation is imperfect.
2143 The current locale is exposed to XS code except possibly
2145 "LC_NUMERIC" (explained in the next paragraph). There have not
2146 been reports of problems with the other categories. Perl
2147 initializes things on start-up so that the current locale is the
2148 one which is indicated by the user's environment in effect at that
2149 time. See "ENVIRONMENT" in perllocale.
2150 However, up through v5.20, Perl initialized things on start-up so
2152 that "LC_NUMERIC" was set to the "C" locale. But if any code
2153 anywhere changed it, it would stay changed. This means that your
2154 module can't count on "LC_NUMERIC" being something in particular,
2155 and you can't expect floating point numbers (including version
2156 strings) to have dots in them. If you don't allow for a non-dot,
2157 your code could break if anyone anywhere changed the locale. For
2158 this reason, v5.22 changed the behavior so that Perl tries to keep
2159 "LC_NUMERIC" in the "C" locale except around the operations
2160 internally where it should be something else. Misbehaving XS code
2161 will always be able to change the locale anyway, but the most
2162 common instance of this is checked for and handled.
2163 Locale-aware XS code
2165 If the locale from the user's environment is desired, there should
2166 be no need for XS code to set the locale except for "LC_NUMERIC",
2167 as perl has already set the others up. XS code should avoid
2168 changing the locale, as it can adversely affect other, unrelated,
2169 code and may not be thread-safe. To minimize problems, the macros
2170 "STORE_LC_NUMERIC_SET_TO_NEEDED" in perlapi,
2171 "STORE_LC_NUMERIC_FORCE_TO_UNDERLYING" in perlapi, and
2172 "RESTORE_LC_NUMERIC" in perlapi should be used to affect any needed
2173 change.
2174 But, starting with Perl v5.28, locales are thread-safe on platforms
2176 that support this functionality. Windows has this starting with
2177 Visual Studio 2005. Many other modern platforms support the
2178 thread-safe POSIX 2008 functions. The C "#define"
2179 "USE_THREAD_SAFE_LOCALE" will be defined iff this build is using
2180 these. From Perl-space, the read-only variable "${SAFE_LOCALES}"
2181 is 1 if either the build is not threaded, or if
2182 "USE_THREAD_SAFE_LOCALE" is defined; otherwise it is 0.
2183 The way this works under-the-hood is that every thread has a choice
2185 of using a locale specific to it (this is the Windows and POSIX
2186 2008 functionality), or the global locale that is accessible to all
2187 threads (this is the functionality that has always been there).
2188 The implementations for Windows and POSIX are completely different.
2189 On Windows, the runtime can be set up so that the standard
2190 setlocale(3) function either only knows about the global locale or
2191 the locale for this thread. On POSIX, "setlocale" always deals
2192 with the global locale, and other functions have been created to
2193 handle per-thread locales. Perl makes this transparent to perl-
2194 space code. It continues to use "POSIX::setlocale()", and the
2195 interpreter translates that into the per-thread functions.
2196 All other locale-sensitive functions automatically use the per-
2198 thread locale, if that is turned on, and failing that, the global
2199 locale. Thus calls to "setlocale" are ineffective on POSIX systems
2200 for the current thread if that thread is using a per-thread locale.
2201 If perl is compiled for single-thread operation, it does not use
2202 the per-thread functions, so "setlocale" does work as expected.
2203 If you have loaded the "POSIX" module you can use the methods given
2205 in perlcall to call "POSIX::setlocale" to safely change or query
2206 the locale (on systems where it is safe to do so), or you can use
2207 the new 5.28 function "Perl_setlocale" in perlapi instead, which is
2208 a drop-in replacement for the system setlocale(3), and handles
2209 single-threaded and multi-threaded applications transparently.
2210 There are some locale-related library calls that still aren't
2212 thread-safe because they return data in a buffer global to all
2213 threads. In the past, these didn't matter as locales weren't
2214 thread-safe at all. But now you have to be aware of them in case
2215 your module is called in a multi-threaded application. The known
2216 ones are
2217 asctime()
2219 ctime()
2220 gcvt() [POSIX.1-2001 only (function removed in POSIX.1-2008)]
2221 getdate()
2222 wcrtomb() if its final argument is NULL
2223 wcsrtombs() if its final argument is NULL
2224 wcstombs()
2225 wctomb()
2226 Some of these shouldn't really be called in a Perl application, and
2228 for others there are thread-safe versions of these already
2229 implemented:
2230 asctime_r()
2232 ctime_r()
2233 Perl_langinfo()
2234 The "_r" forms are automatically used, starting in Perl 5.28, if
2236 you compile your code, with
2237 #define PERL_REENTRANT
2239 See also "Perl_langinfo" in perlapi. You can use the methods given
2241 in perlcall, to get the best available locale-safe versions of
2242 these
2243 POSIX::localeconv()
2245 POSIX::wcstombs()
2246 POSIX::wctomb()
2247 And note, that some items returned by "Localeconv" are available
2249 through "Perl_langinfo" in perlapi.
2250 The others shouldn't be used in a threaded application.
2252 Some modules may call a non-perl library that is locale-aware.
2254 This is fine as long as it doesn't try to query or change the
2255 locale using the system "setlocale". But if these do call the
2256 system "setlocale", those calls may be ineffective. Instead,
2257 "Perl_setlocale" works in all circumstances. Plain setlocale is
2258 ineffective on multi-threaded POSIX 2008 systems. It operates only
2259 on the global locale, whereas each thread has its own locale,
2260 paying no attention to the global one. Since converting these non-
2261 Perl libraries to "Perl_setlocale" is out of the question, there is
2262 a new function in v5.28 "switch_to_global_locale" that will switch
2263 the thread it is called from so that any system "setlocale" calls
2264 will have their desired effect. The function "sync_locale" must be
2265 called before returning to perl.
2266 This thread can change the locale all it wants and it won't affect
2268 any other thread, except any that also have been switched to the
2269 global locale. This means that a multi-threaded application can
2270 have a single thread using an alien library without a problem; but
2271 no more than a single thread can be so-occupied. Bad results
2272 likely will happen.
2273 In perls without multi-thread locale support, some alien libraries,
2275 such as "Gtk" change locales. This can cause problems for the Perl
2276 core and other modules. For these, before control is returned to
2277 perl, starting in v5.20.1, calling the function sync_locale() from
2278 XS should be sufficient to avoid most of these problems. Prior to
2279 this, you need a pure Perl statement that does this:
2280 POSIX::setlocale(LC_ALL, POSIX::setlocale(LC_ALL));
2282 or use the methods given in perlcall.
2284
2286 This document covers features supported by "ExtUtils::ParseXS" (also
2287 known as "xsubpp") 3.13_01.
2288
2290 Originally written by Dean Roehrich <roehrich@cray.com>.
2291 Maintained since 1996 by The Perl Porters <perlbug@perl.org>.
2293perl v5.34.0 2021-07-22 perlxs(3)