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, calls this C
26 function, and then transfers the return values of the C function back
27 to Perl. Return values here may be a conventional C return value or
28 any C function arguments that may serve as output parameters. These
29 return values may be passed back to Perl either by putting them on the
30 Perl 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 to 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 gettime().
393 This keyword should follow the PACKAGE keyword when used. If PACKAGE
395 is not used then PREFIX should follow the MODULE keyword.
396 MODULE = RPC PREFIX = rpc_
398 MODULE = RPC PACKAGE = RPCB PREFIX = rpcb_
400 The OUTPUT: Keyword
402 The OUTPUT: keyword indicates that certain function parameters should
403 be updated (new values made visible to Perl) when the XSUB terminates
404 or that certain values should be returned to the calling Perl function.
405 For simple functions which have no CODE: or PPCODE: section, such as
406 the sin() function above, the RETVAL variable is automatically
407 designated as an output value. For more complex functions the xsubpp
408 compiler will need help to determine which variables are output
409 variables.
410 This keyword will normally be used to complement the CODE: keyword.
412 The RETVAL variable is not recognized as an output variable when the
413 CODE: keyword is present. The OUTPUT: keyword is used in this
414 situation to tell the compiler that RETVAL really is an output
415 variable.
416 The OUTPUT: keyword can also be used to indicate that function
418 parameters are output variables. This may be necessary when a
419 parameter has been modified within the function and the programmer
420 would like the update to be seen by Perl.
421 bool_t
423 rpcb_gettime(host,timep)
424 char *host
425 time_t &timep
426 OUTPUT:
427 timep
428 The OUTPUT: keyword will also allow an output parameter to be mapped to
430 a matching piece of code rather than to a typemap.
431 bool_t
433 rpcb_gettime(host,timep)
434 char *host
435 time_t &timep
436 OUTPUT:
437 timep sv_setnv(ST(1), (double)timep);
438 xsubpp emits an automatic SvSETMAGIC() for all parameters in the OUTPUT
440 section of the XSUB, except RETVAL. This is the usually desired
441 behavior, as it takes care of properly invoking 'set' magic on output
442 parameters (needed for hash or array element parameters that must be
443 created if they didn't exist). If for some reason, this behavior is
444 not desired, the OUTPUT section may contain a "SETMAGIC: DISABLE" line
445 to disable it for the remainder of the parameters in the OUTPUT
446 section. Likewise, "SETMAGIC: ENABLE" can be used to reenable it for
447 the remainder of the OUTPUT section. See perlguts for more details
448 about 'set' magic.
449 The NO_OUTPUT Keyword
451 The NO_OUTPUT can be placed as the first token of the XSUB. This
452 keyword indicates that while the C subroutine we provide an interface
453 to has a non-"void" return type, the return value of this C subroutine
454 should not be returned from the generated Perl subroutine.
455 With this keyword present "The RETVAL Variable" is created, and in the
457 generated call to the subroutine this variable is assigned to, but the
458 value of this variable is not going to be used in the auto-generated
459 code.
460 This keyword makes sense only if "RETVAL" is going to be accessed by
462 the user-supplied code. It is especially useful to make a function
463 interface more Perl-like, especially when the C return value is just an
464 error condition indicator. For example,
465 NO_OUTPUT int
467 delete_file(char *name)
468 POSTCALL:
469 if (RETVAL != 0)
470 croak("Error %d while deleting file '%s'", RETVAL, name);
471 Here the generated XS function returns nothing on success, and will
473 die() with a meaningful error message on error.
474 The CODE: Keyword
476 This keyword is used in more complicated XSUBs which require special
477 handling for the C function. The RETVAL variable is still declared,
478 but it will not be returned unless it is specified in the OUTPUT:
479 section.
480 The following XSUB is for a C function which requires special handling
482 of its parameters. The Perl usage is given first.
483 $status = rpcb_gettime( "localhost", $timep );
485 The XSUB follows.
487 bool_t
489 rpcb_gettime(host,timep)
490 char *host
491 time_t timep
492 CODE:
493 RETVAL = rpcb_gettime( host, &timep );
494 OUTPUT:
495 timep
496 RETVAL
497 The INIT: Keyword
499 The INIT: keyword allows initialization to be inserted into the XSUB
500 before the compiler generates the call to the C function. Unlike the
501 CODE: keyword above, this keyword does not affect the way the compiler
502 handles RETVAL.
503 bool_t
505 rpcb_gettime(host,timep)
506 char *host
507 time_t &timep
508 INIT:
509 printf("# Host is %s\n", host );
510 OUTPUT:
511 timep
512 Another use for the INIT: section is to check for preconditions before
514 making a call to the C function:
515 long long
517 lldiv(a,b)
518 long long a
519 long long b
520 INIT:
521 if (a == 0 && b == 0)
522 XSRETURN_UNDEF;
523 if (b == 0)
524 croak("lldiv: cannot divide by 0");
525 The NO_INIT Keyword
527 The NO_INIT keyword is used to indicate that a function parameter is
528 being used only as an output value. The xsubpp compiler will normally
529 generate code to read the values of all function parameters from the
530 argument stack and assign them to C variables upon entry to the
531 function. NO_INIT will tell the compiler that some parameters will be
532 used for output rather than for input and that they will be handled
533 before the function terminates.
534 The following example shows a variation of the rpcb_gettime() function.
536 This function uses the timep variable only as an output variable and
537 does not care about its initial contents.
538 bool_t
540 rpcb_gettime(host,timep)
541 char *host
542 time_t &timep = NO_INIT
543 OUTPUT:
544 timep
545 The TYPEMAP: Keyword
547 Starting with Perl 5.16, you can embed typemaps into your XS code
548 instead of or in addition to typemaps in a separate file. Multiple
549 such embedded typemaps will be processed in order of appearance in the
550 XS code and like local typemap files take precedence over the default
551 typemap, the embedded typemaps may overwrite previous definitions of
552 TYPEMAP, INPUT, and OUTPUT stanzas. The syntax for embedded typemaps
553 is
554 TYPEMAP: <<HERE
556 ... your typemap code here ...
557 HERE
558 where the "TYPEMAP" keyword must appear in the first column of a new
560 line.
561 Refer to perlxstypemap for details on writing typemaps.
563 Initializing Function Parameters
565 C function parameters are normally initialized with their values from
566 the argument stack (which in turn contains the parameters that were
567 passed to the XSUB from Perl). The typemaps contain the code segments
568 which are used to translate the Perl values to the C parameters. The
569 programmer, however, is allowed to override the typemaps and supply
570 alternate (or additional) initialization code. Initialization code
571 starts with the first "=", ";" or "+" on a line in the INPUT: section.
572 The only exception happens if this ";" terminates the line, then this
573 ";" is quietly ignored.
574 The following code demonstrates how to supply initialization code for
576 function parameters. The initialization code is eval'ed within double
577 quotes by the compiler before it is added to the output so anything
578 which should be interpreted literally [mainly "$", "@", or "\\"] must
579 be protected with backslashes. The variables $var, $arg, and $type can
580 be used as in typemaps.
581 bool_t
583 rpcb_gettime(host,timep)
584 char *host = (char *)SvPVbyte_nolen($arg);
585 time_t &timep = 0;
586 OUTPUT:
587 timep
588 This should not be used to supply default values for parameters. One
590 would normally use this when a function parameter must be processed by
591 another library function before it can be used. Default parameters are
592 covered in the next section.
593 If the initialization begins with "=", then it is output in the
595 declaration for the input variable, replacing the initialization
596 supplied by the typemap. If the initialization begins with ";" or "+",
597 then it is performed after all of the input variables have been
598 declared. In the ";" case the initialization normally supplied by the
599 typemap is not performed. For the "+" case, the declaration for the
600 variable will include the initialization from the typemap. A global
601 variable, %v, is available for the truly rare case where information
602 from one initialization is needed in another initialization.
603 Here's a truly obscure example:
605 bool_t
607 rpcb_gettime(host,timep)
608 time_t &timep; /* \$v{timep}=@{[$v{timep}=$arg]} */
609 char *host + SvOK($v{timep}) ? SvPVbyte_nolen($arg) : NULL;
610 OUTPUT:
611 timep
612 The construct "\$v{timep}=@{[$v{timep}=$arg]}" used in the above
614 example has a two-fold purpose: first, when this line is processed by
615 xsubpp, the Perl snippet "$v{timep}=$arg" is evaluated. Second, the
616 text of the evaluated snippet is output into the generated C file
617 (inside a C comment)! During the processing of "char *host" line, $arg
618 will evaluate to ST(0), and $v{timep} will evaluate to ST(1).
619 Default Parameter Values
621 Default values for XSUB arguments can be specified by placing an
622 assignment statement in the parameter list. The default value may be a
623 number, a string or the special string "NO_INIT". Defaults should
624 always be used on the right-most parameters only.
625 To allow the XSUB for rpcb_gettime() to have a default host value the
627 parameters to the XSUB could be rearranged. The XSUB will then call
628 the real rpcb_gettime() function with the parameters in the correct
629 order. This XSUB can be called from Perl with either of the following
630 statements:
631 $status = rpcb_gettime( $timep, $host );
633 $status = rpcb_gettime( $timep );
635 The XSUB will look like the code which follows. A CODE: block is used
637 to call the real rpcb_gettime() function with the parameters in the
638 correct order for that function.
639 bool_t
641 rpcb_gettime(timep,host="localhost")
642 char *host
643 time_t timep = NO_INIT
644 CODE:
645 RETVAL = rpcb_gettime( host, &timep );
646 OUTPUT:
647 timep
648 RETVAL
649 The PREINIT: Keyword
651 The PREINIT: keyword allows extra variables to be declared immediately
652 before or after the declarations of the parameters from the INPUT:
653 section are emitted.
654 If a variable is declared inside a CODE: section it will follow any
656 typemap code that is emitted for the input parameters. This may result
657 in the declaration ending up after C code, which is C syntax error.
658 Similar errors may happen with an explicit ";"-type or "+"-type
659 initialization of parameters is used (see "Initializing Function
660 Parameters"). Declaring these variables in an INIT: section will not
661 help.
662 In such cases, to force an additional variable to be declared together
664 with declarations of other variables, place the declaration into a
665 PREINIT: section. The PREINIT: keyword may be used one or more times
666 within an XSUB.
667 The following examples are equivalent, but if the code is using complex
669 typemaps then the first example is safer.
670 bool_t
672 rpcb_gettime(timep)
673 time_t timep = NO_INIT
674 PREINIT:
675 char *host = "localhost";
676 CODE:
677 RETVAL = rpcb_gettime( host, &timep );
678 OUTPUT:
679 timep
680 RETVAL
681 For this particular case an INIT: keyword would generate the same C
683 code as the PREINIT: keyword. Another correct, but error-prone
684 example:
685 bool_t
687 rpcb_gettime(timep)
688 time_t timep = NO_INIT
689 CODE:
690 char *host = "localhost";
691 RETVAL = rpcb_gettime( host, &timep );
692 OUTPUT:
693 timep
694 RETVAL
695 Another way to declare "host" is to use a C block in the CODE: section:
697 bool_t
699 rpcb_gettime(timep)
700 time_t timep = NO_INIT
701 CODE:
702 {
703 char *host = "localhost";
704 RETVAL = rpcb_gettime( host, &timep );
705 }
706 OUTPUT:
707 timep
708 RETVAL
709 The ability to put additional declarations before the typemap entries
711 are processed is very handy in the cases when typemap conversions
712 manipulate some global state:
713 MyObject
715 mutate(o)
716 PREINIT:
717 MyState st = global_state;
718 INPUT:
719 MyObject o;
720 CLEANUP:
721 reset_to(global_state, st);
722 Here we suppose that conversion to "MyObject" in the INPUT: section and
724 from MyObject when processing RETVAL will modify a global variable
725 "global_state". After these conversions are performed, we restore the
726 old value of "global_state" (to avoid memory leaks, for example).
727 There is another way to trade clarity for compactness: INPUT sections
729 allow declaration of C variables which do not appear in the parameter
730 list of a subroutine. Thus the above code for mutate() can be
731 rewritten as
732 MyObject
734 mutate(o)
735 MyState st = global_state;
736 MyObject o;
737 CLEANUP:
738 reset_to(global_state, st);
739 and the code for rpcb_gettime() can be rewritten as
741 bool_t
743 rpcb_gettime(timep)
744 time_t timep = NO_INIT
745 char *host = "localhost";
746 C_ARGS:
747 host, &timep
748 OUTPUT:
749 timep
750 RETVAL
751 The SCOPE: Keyword
753 The SCOPE: keyword allows scoping to be enabled for a particular XSUB.
754 If enabled, the XSUB will invoke ENTER and LEAVE automatically.
755 To support potentially complex type mappings, if a typemap entry used
757 by an XSUB contains a comment like "/*scope*/" then scoping will be
758 automatically enabled for that XSUB.
759 To enable scoping:
761 SCOPE: ENABLE
763 To disable scoping:
765 SCOPE: DISABLE
767 The INPUT: Keyword
769 The XSUB's parameters are usually evaluated immediately after entering
770 the XSUB. The INPUT: keyword can be used to force those parameters to
771 be evaluated a little later. The INPUT: keyword can be used multiple
772 times within an XSUB and can be used to list one or more input
773 variables. This keyword is used with the PREINIT: keyword.
774 The following example shows how the input parameter "timep" can be
776 evaluated late, after a PREINIT.
777 bool_t
779 rpcb_gettime(host,timep)
780 char *host
781 PREINIT:
782 time_t tt;
783 INPUT:
784 time_t timep
785 CODE:
786 RETVAL = rpcb_gettime( host, &tt );
787 timep = tt;
788 OUTPUT:
789 timep
790 RETVAL
791 The next example shows each input parameter evaluated late.
793 bool_t
795 rpcb_gettime(host,timep)
796 PREINIT:
797 time_t tt;
798 INPUT:
799 char *host
800 PREINIT:
801 char *h;
802 INPUT:
803 time_t timep
804 CODE:
805 h = host;
806 RETVAL = rpcb_gettime( h, &tt );
807 timep = tt;
808 OUTPUT:
809 timep
810 RETVAL
811 Since INPUT sections allow declaration of C variables which do not
813 appear in the parameter list of a subroutine, this may be shortened to:
814 bool_t
816 rpcb_gettime(host,timep)
817 time_t tt;
818 char *host;
819 char *h = host;
820 time_t timep;
821 CODE:
822 RETVAL = rpcb_gettime( h, &tt );
823 timep = tt;
824 OUTPUT:
825 timep
826 RETVAL
827 (We used our knowledge that input conversion for "char *" is a "simple"
829 one, thus "host" is initialized on the declaration line, and our
830 assignment "h = host" is not performed too early. Otherwise one would
831 need to have the assignment "h = host" in a CODE: or INIT: section.)
832 The IN/OUTLIST/IN_OUTLIST/OUT/IN_OUT Keywords
834 In the list of parameters for an XSUB, one can precede parameter names
835 by the "IN"/"OUTLIST"/"IN_OUTLIST"/"OUT"/"IN_OUT" keywords. "IN"
836 keyword is the default, the other keywords indicate how the Perl
837 interface should differ from the C interface.
838 Parameters preceded by "OUTLIST"/"IN_OUTLIST"/"OUT"/"IN_OUT" keywords
840 are considered to be used by the C subroutine via pointers.
841 "OUTLIST"/"OUT" keywords indicate that the C subroutine does not
842 inspect the memory pointed by this parameter, but will write through
843 this pointer to provide additional return values.
844 Parameters preceded by "OUTLIST" keyword do not appear in the usage
846 signature of the generated Perl function.
847 Parameters preceded by "IN_OUTLIST"/"IN_OUT"/"OUT" do appear as
849 parameters to the Perl function. With the exception of
850 "OUT"-parameters, these parameters are converted to the corresponding C
851 type, then pointers to these data are given as arguments to the C
852 function. It is expected that the C function will write through these
853 pointers.
854 The return list of the generated Perl function consists of the C return
856 value from the function (unless the XSUB is of "void" return type or
857 "The NO_OUTPUT Keyword" was used) followed by all the "OUTLIST" and
858 "IN_OUTLIST" parameters (in the order of appearance). On the return
859 from the XSUB the "IN_OUT"/"OUT" Perl parameter will be modified to
860 have the values written by the C function.
861 For example, an XSUB
863 void
865 day_month(OUTLIST day, IN unix_time, OUTLIST month)
866 int day
867 int unix_time
868 int month
869 should be used from Perl as
871 my ($day, $month) = day_month(time);
873 The C signature of the corresponding function should be
875 void day_month(int *day, int unix_time, int *month);
877 The "IN"/"OUTLIST"/"IN_OUTLIST"/"IN_OUT"/"OUT" keywords can be mixed
879 with ANSI-style declarations, as in
880 void
882 day_month(OUTLIST int day, int unix_time, OUTLIST int month)
883 (here the optional "IN" keyword is omitted).
885 The "IN_OUT" parameters are identical with parameters introduced with
887 "The & Unary Operator" and put into the "OUTPUT:" section (see "The
888 OUTPUT: Keyword"). The "IN_OUTLIST" parameters are very similar, the
889 only difference being that the value C function writes through the
890 pointer would not modify the Perl parameter, but is put in the output
891 list.
892 The "OUTLIST"/"OUT" parameter differ from "IN_OUTLIST"/"IN_OUT"
894 parameters only by the initial value of the Perl parameter not being
895 read (and not being given to the C function - which gets some garbage
896 instead). For example, the same C function as above can be interfaced
897 with as
898 void day_month(OUT int day, int unix_time, OUT int month);
900 or
902 void
904 day_month(day, unix_time, month)
905 int &day = NO_INIT
906 int unix_time
907 int &month = NO_INIT
908 OUTPUT:
909 day
910 month
911 However, the generated Perl function is called in very C-ish style:
913 my ($day, $month);
915 day_month($day, time, $month);
916 The length(NAME) Keyword
918 If one of the input arguments to the C function is the length of a
919 string argument "NAME", one can substitute the name of the length-
920 argument by length(NAME) in the XSUB declaration. This argument must
921 be omitted when the generated Perl function is called. E.g.,
922 void
924 dump_chars(char *s, short l)
925 {
926 short n = 0;
927 while (n < l) {
928 printf("s[%d] = \"\\%#03o\"\n", n, (int)s[n]);
929 n++;
930 }
931 }
932 MODULE = x PACKAGE = x
934 void dump_chars(char *s, short length(s))
936 should be called as dump_chars($string).
938 This directive is supported with ANSI-type function declarations only.
940 Variable-length Parameter Lists
942 XSUBs can have variable-length parameter lists by specifying an
943 ellipsis "(...)" in the parameter list. This use of the ellipsis is
944 similar to that found in ANSI C. The programmer is able to determine
945 the number of arguments passed to the XSUB by examining the "items"
946 variable which the xsubpp compiler supplies for all XSUBs. By using
947 this mechanism one can create an XSUB which accepts a list of
948 parameters of unknown length.
949 The host parameter for the rpcb_gettime() XSUB can be optional so the
951 ellipsis can be used to indicate that the XSUB will take a variable
952 number of parameters. Perl should be able to call this XSUB with
953 either of the following statements.
954 $status = rpcb_gettime( $timep, $host );
956 $status = rpcb_gettime( $timep );
958 The XS code, with ellipsis, follows.
960 bool_t
962 rpcb_gettime(timep, ...)
963 time_t timep = NO_INIT
964 PREINIT:
965 char *host = "localhost";
966 CODE:
967 if( items > 1 )
968 host = (char *)SvPVbyte_nolen(ST(1));
969 RETVAL = rpcb_gettime( host, &timep );
970 OUTPUT:
971 timep
972 RETVAL
973 The C_ARGS: Keyword
975 The C_ARGS: keyword allows creating of XSUBS which have different
976 calling sequence from Perl than from C, without a need to write CODE:
977 or PPCODE: section. The contents of the C_ARGS: paragraph is put as
978 the argument to the called C function without any change.
979 For example, suppose that a C function is declared as
981 symbolic nth_derivative(int n, symbolic function, int flags);
983 and that the default flags are kept in a global C variable
985 "default_flags". Suppose that you want to create an interface which is
986 called as
987 $second_deriv = $function->nth_derivative(2);
989 To do this, declare the XSUB as
991 symbolic
993 nth_derivative(function, n)
994 symbolic function
995 int n
996 C_ARGS:
997 n, function, default_flags
998 The PPCODE: Keyword
1000 The PPCODE: keyword is an alternate form of the CODE: keyword and is
1001 used to tell the xsubpp compiler that the programmer is supplying the
1002 code to control the argument stack for the XSUBs return values.
1003 Occasionally one will want an XSUB to return a list of values rather
1004 than a single value. In these cases one must use PPCODE: and then
1005 explicitly push the list of values on the stack. The PPCODE: and CODE:
1006 keywords should not be used together within the same XSUB.
1007 The actual difference between PPCODE: and CODE: sections is in the
1009 initialization of "SP" macro (which stands for the current Perl stack
1010 pointer), and in the handling of data on the stack when returning from
1011 an XSUB. In CODE: sections SP preserves the value which was on entry
1012 to the XSUB: SP is on the function pointer (which follows the last
1013 parameter). In PPCODE: sections SP is moved backward to the beginning
1014 of the parameter list, which allows "PUSH*()" macros to place output
1015 values in the place Perl expects them to be when the XSUB returns back
1016 to Perl.
1017 The generated trailer for a CODE: section ensures that the number of
1019 return values Perl will see is either 0 or 1 (depending on the
1020 "void"ness of the return value of the C function, and heuristics
1021 mentioned in "The RETVAL Variable"). The trailer generated for a
1022 PPCODE: section is based on the number of return values and on the
1023 number of times "SP" was updated by "[X]PUSH*()" macros.
1024 Note that macros ST(i), "XST_m*()" and "XSRETURN*()" work equally well
1026 in CODE: sections and PPCODE: sections.
1027 The following XSUB will call the C rpcb_gettime() function and will
1029 return its two output values, timep and status, to Perl as a single
1030 list.
1031 void
1033 rpcb_gettime(host)
1034 char *host
1035 PREINIT:
1036 time_t timep;
1037 bool_t status;
1038 PPCODE:
1039 status = rpcb_gettime( host, &timep );
1040 EXTEND(SP, 2);
1041 PUSHs(sv_2mortal(newSViv(status)));
1042 PUSHs(sv_2mortal(newSViv(timep)));
1043 Notice that the programmer must supply the C code necessary to have the
1045 real rpcb_gettime() function called and to have the return values
1046 properly placed on the argument stack.
1047 The "void" return type for this function tells the xsubpp compiler that
1049 the RETVAL variable is not needed or used and that it should not be
1050 created. In most scenarios the void return type should be used with
1051 the PPCODE: directive.
1052 The EXTEND() macro is used to make room on the argument stack for 2
1054 return values. The PPCODE: directive causes the xsubpp compiler to
1055 create a stack pointer available as "SP", and it is this pointer which
1056 is being used in the EXTEND() macro. The values are then pushed onto
1057 the stack with the PUSHs() macro.
1058 Now the rpcb_gettime() function can be used from Perl with the
1060 following statement.
1061 ($status, $timep) = rpcb_gettime("localhost");
1063 When handling output parameters with a PPCODE section, be sure to
1065 handle 'set' magic properly. See perlguts for details about 'set'
1066 magic.
1067 Returning Undef And Empty Lists
1069 Occasionally the programmer will want to return simply "undef" or an
1070 empty list if a function fails rather than a separate status value.
1071 The rpcb_gettime() function offers just this situation. If the
1072 function succeeds we would like to have it return the time and if it
1073 fails we would like to have undef returned. In the following Perl code
1074 the value of $timep will either be undef or it will be a valid time.
1075 $timep = rpcb_gettime( "localhost" );
1077 The following XSUB uses the "SV *" return type as a mnemonic only, and
1079 uses a CODE: block to indicate to the compiler that the programmer has
1080 supplied all the necessary code. The sv_newmortal() call will
1081 initialize the return value to undef, making that the default return
1082 value.
1083 SV *
1085 rpcb_gettime(host)
1086 char * host
1087 PREINIT:
1088 time_t timep;
1089 bool_t x;
1090 CODE:
1091 ST(0) = sv_newmortal();
1092 if( rpcb_gettime( host, &timep ) )
1093 sv_setnv( ST(0), (double)timep);
1094 The next example demonstrates how one would place an explicit undef in
1096 the return value, should the need arise.
1097 SV *
1099 rpcb_gettime(host)
1100 char * host
1101 PREINIT:
1102 time_t timep;
1103 bool_t x;
1104 CODE:
1105 if( rpcb_gettime( host, &timep ) ){
1106 ST(0) = sv_newmortal();
1107 sv_setnv( ST(0), (double)timep);
1108 }
1109 else{
1110 ST(0) = &PL_sv_undef;
1111 }
1112 To return an empty list one must use a PPCODE: block and then not push
1114 return values on the stack.
1115 void
1117 rpcb_gettime(host)
1118 char *host
1119 PREINIT:
1120 time_t timep;
1121 PPCODE:
1122 if( rpcb_gettime( host, &timep ) )
1123 PUSHs(sv_2mortal(newSViv(timep)));
1124 else{
1125 /* Nothing pushed on stack, so an empty
1126 * list is implicitly returned. */
1127 }
1128 Some people may be inclined to include an explicit "return" in the
1130 above XSUB, rather than letting control fall through to the end. In
1131 those situations "XSRETURN_EMPTY" should be used, instead. This will
1132 ensure that the XSUB stack is properly adjusted. Consult perlapi for
1133 other "XSRETURN" macros.
1134 Since "XSRETURN_*" macros can be used with CODE blocks as well, one can
1136 rewrite this example as:
1137 int
1139 rpcb_gettime(host)
1140 char *host
1141 PREINIT:
1142 time_t timep;
1143 CODE:
1144 RETVAL = rpcb_gettime( host, &timep );
1145 if (RETVAL == 0)
1146 XSRETURN_UNDEF;
1147 OUTPUT:
1148 RETVAL
1149 In fact, one can put this check into a POSTCALL: section as well.
1151 Together with PREINIT: simplifications, this leads to:
1152 int
1154 rpcb_gettime(host)
1155 char *host
1156 time_t timep;
1157 POSTCALL:
1158 if (RETVAL == 0)
1159 XSRETURN_UNDEF;
1160 The REQUIRE: Keyword
1162 The REQUIRE: keyword is used to indicate the minimum version of the
1163 xsubpp compiler needed to compile the XS module. An XS module which
1164 contains the following statement will compile with only xsubpp version
1165 1.922 or greater:
1166 REQUIRE: 1.922
1168 The CLEANUP: Keyword
1170 This keyword can be used when an XSUB requires special cleanup
1171 procedures before it terminates. When the CLEANUP: keyword is used it
1172 must follow any CODE:, or OUTPUT: blocks which are present in the XSUB.
1173 The code specified for the cleanup block will be added as the last
1174 statements in the XSUB.
1175 The POSTCALL: Keyword
1177 This keyword can be used when an XSUB requires special procedures
1178 executed after the C subroutine call is performed. When the POSTCALL:
1179 keyword is used it must precede OUTPUT: and CLEANUP: blocks which are
1180 present in the XSUB.
1181 See examples in "The NO_OUTPUT Keyword" and "Returning Undef And Empty
1183 Lists".
1184 The POSTCALL: block does not make a lot of sense when the C subroutine
1186 call is supplied by user by providing either CODE: or PPCODE: section.
1187 The BOOT: Keyword
1189 The BOOT: keyword is used to add code to the extension's bootstrap
1190 function. The bootstrap function is generated by the xsubpp compiler
1191 and normally holds the statements necessary to register any XSUBs with
1192 Perl. With the BOOT: keyword the programmer can tell the compiler to
1193 add extra statements to the bootstrap function.
1194 This keyword may be used any time after the first MODULE keyword and
1196 should appear on a line by itself. The first blank line after the
1197 keyword will terminate the code block.
1198 BOOT:
1200 # The following message will be printed when the
1201 # bootstrap function executes.
1202 printf("Hello from the bootstrap!\n");
1203 The VERSIONCHECK: Keyword
1205 The VERSIONCHECK: keyword corresponds to xsubpp's "-versioncheck" and
1206 "-noversioncheck" options. This keyword overrides the command line
1207 options. Version checking is enabled by default. When version
1208 checking is enabled the XS module will attempt to verify that its
1209 version matches the version of the PM module.
1210 To enable version checking:
1212 VERSIONCHECK: ENABLE
1214 To disable version checking:
1216 VERSIONCHECK: DISABLE
1218 Note that if the version of the PM module is an NV (a floating point
1220 number), it will be stringified with a possible loss of precision
1221 (currently chopping to nine decimal places) so that it may not match
1222 the version of the XS module anymore. Quoting the $VERSION declaration
1223 to make it a string is recommended if long version numbers are used.
1224 The PROTOTYPES: Keyword
1226 The PROTOTYPES: keyword corresponds to xsubpp's "-prototypes" and
1227 "-noprototypes" options. This keyword overrides the command line
1228 options. Prototypes are disabled by default. When prototypes are
1229 enabled, XSUBs will be given Perl prototypes. This keyword may be used
1230 multiple times in an XS module to enable and disable prototypes for
1231 different parts of the module. Note that xsubpp will nag you if you
1232 don't explicitly enable or disable prototypes, with:
1233 Please specify prototyping behavior for Foo.xs (see perlxs manual)
1235 To enable prototypes:
1237 PROTOTYPES: ENABLE
1239 To disable prototypes:
1241 PROTOTYPES: DISABLE
1243 The PROTOTYPE: Keyword
1245 This keyword is similar to the PROTOTYPES: keyword above but can be
1246 used to force xsubpp to use a specific prototype for the XSUB. This
1247 keyword overrides all other prototype options and keywords but affects
1248 only the current XSUB. Consult "Prototypes" in perlsub for information
1249 about Perl prototypes.
1250 bool_t
1252 rpcb_gettime(timep, ...)
1253 time_t timep = NO_INIT
1254 PROTOTYPE: $;$
1255 PREINIT:
1256 char *host = "localhost";
1257 CODE:
1258 if( items > 1 )
1259 host = (char *)SvPVbyte_nolen(ST(1));
1260 RETVAL = rpcb_gettime( host, &timep );
1261 OUTPUT:
1262 timep
1263 RETVAL
1264 If the prototypes are enabled, you can disable it locally for a given
1266 XSUB as in the following example:
1267 void
1269 rpcb_gettime_noproto()
1270 PROTOTYPE: DISABLE
1271 ...
1272 The ALIAS: Keyword
1274 The ALIAS: keyword allows an XSUB to have two or more unique Perl names
1275 and to know which of those names was used when it was invoked. The
1276 Perl names may be fully-qualified with package names. Each alias is
1277 given an index. The compiler will setup a variable called "ix" which
1278 contain the index of the alias which was used. When the XSUB is called
1279 with its declared name "ix" will be 0.
1280 The following example will create aliases FOO::gettime() and
1282 BAR::getit() for this function.
1283 bool_t
1285 rpcb_gettime(host,timep)
1286 char *host
1287 time_t &timep
1288 ALIAS:
1289 FOO::gettime = 1
1290 BAR::getit = 2
1291 INIT:
1292 printf("# ix = %d\n", ix );
1293 OUTPUT:
1294 timep
1295 The OVERLOAD: Keyword
1297 Instead of writing an overloaded interface using pure Perl, you can
1298 also use the OVERLOAD keyword to define additional Perl names for your
1299 functions (like the ALIAS: keyword above). However, the overloaded
1300 functions must be defined in such a way as to accept the number of
1301 parameters supplied by perl's overload system. For most overload
1302 methods, it will be three parameters; for the "nomethod" function it
1303 will be four. However, the bitwise operators "&", "|", "^", and "~"
1304 may be called with three or five arguments (see overload).
1305 If any function has the OVERLOAD: keyword, several additional lines
1307 will be defined in the c file generated by xsubpp in order to register
1308 with the overload magic.
1309 Since blessed objects are actually stored as RV's, it is useful to use
1311 the typemap features to preprocess parameters and extract the actual SV
1312 stored within the blessed RV. See the sample for T_PTROBJ_SPECIAL
1313 below.
1314 To use the OVERLOAD: keyword, create an XS function which takes three
1316 input parameters (or use the C-style '...' definition) like this:
1317 SV *
1319 cmp (lobj, robj, swap)
1320 My_Module_obj lobj
1321 My_Module_obj robj
1322 IV swap
1323 OVERLOAD: cmp <=>
1324 { /* function defined here */}
1325 In this case, the function will overload both of the three way
1327 comparison operators. For all overload operations using non-alpha
1328 characters, you must type the parameter without quoting, separating
1329 multiple overloads with whitespace. Note that "" (the stringify
1330 overload) should be entered as \"\" (i.e. escaped).
1331 Since, as mentioned above, bitwise operators may take extra arguments,
1333 you may want to use something like "(lobj, robj, swap, ...)" (with
1334 literal "...") as your parameter list.
1335 The FALLBACK: Keyword
1337 In addition to the OVERLOAD keyword, if you need to control how Perl
1338 autogenerates missing overloaded operators, you can set the FALLBACK
1339 keyword in the module header section, like this:
1340 MODULE = RPC PACKAGE = RPC
1342 FALLBACK: TRUE
1344 ...
1345 where FALLBACK can take any of the three values TRUE, FALSE, or UNDEF.
1347 If you do not set any FALLBACK value when using OVERLOAD, it defaults
1348 to UNDEF. FALLBACK is not used except when one or more functions using
1349 OVERLOAD have been defined. Please see "fallback" in overload for more
1350 details.
1351 The INTERFACE: Keyword
1353 This keyword declares the current XSUB as a keeper of the given calling
1354 signature. If some text follows this keyword, it is considered as a
1355 list of functions which have this signature, and should be attached to
1356 the current XSUB.
1357 For example, if you have 4 C functions multiply(), divide(), add(),
1359 subtract() all having the signature:
1360 symbolic f(symbolic, symbolic);
1362 you can make them all to use the same XSUB using this:
1364 symbolic
1366 interface_s_ss(arg1, arg2)
1367 symbolic arg1
1368 symbolic arg2
1369 INTERFACE:
1370 multiply divide
1371 add subtract
1372 (This is the complete XSUB code for 4 Perl functions!) Four generated
1374 Perl function share names with corresponding C functions.
1375 The advantage of this approach comparing to ALIAS: keyword is that
1377 there is no need to code a switch statement, each Perl function (which
1378 shares the same XSUB) knows which C function it should call.
1379 Additionally, one can attach an extra function remainder() at runtime
1380 by using
1381 CV *mycv = newXSproto("Symbolic::remainder",
1383 XS_Symbolic_interface_s_ss, __FILE__, "$$");
1384 XSINTERFACE_FUNC_SET(mycv, remainder);
1385 say, from another XSUB. (This example supposes that there was no
1387 INTERFACE_MACRO: section, otherwise one needs to use something else
1388 instead of "XSINTERFACE_FUNC_SET", see the next section.)
1389 The INTERFACE_MACRO: Keyword
1391 This keyword allows one to define an INTERFACE using a different way to
1392 extract a function pointer from an XSUB. The text which follows this
1393 keyword should give the name of macros which would extract/set a
1394 function pointer. The extractor macro is given return type, "CV*", and
1395 "XSANY.any_dptr" for this "CV*". The setter macro is given cv, and the
1396 function pointer.
1397 The default value is "XSINTERFACE_FUNC" and "XSINTERFACE_FUNC_SET". An
1399 INTERFACE keyword with an empty list of functions can be omitted if
1400 INTERFACE_MACRO keyword is used.
1401 Suppose that in the previous example functions pointers for multiply(),
1403 divide(), add(), subtract() are kept in a global C array "fp[]" with
1404 offsets being "multiply_off", "divide_off", "add_off", "subtract_off".
1405 Then one can use
1406 #define XSINTERFACE_FUNC_BYOFFSET(ret,cv,f) \
1408 ((XSINTERFACE_CVT_ANON(ret))fp[CvXSUBANY(cv).any_i32])
1409 #define XSINTERFACE_FUNC_BYOFFSET_set(cv,f) \
1410 CvXSUBANY(cv).any_i32 = CAT2( f, _off )
1411 in C section,
1413 symbolic
1415 interface_s_ss(arg1, arg2)
1416 symbolic arg1
1417 symbolic arg2
1418 INTERFACE_MACRO:
1419 XSINTERFACE_FUNC_BYOFFSET
1420 XSINTERFACE_FUNC_BYOFFSET_set
1421 INTERFACE:
1422 multiply divide
1423 add subtract
1424 in XSUB section.
1426 The INCLUDE: Keyword
1428 This keyword can be used to pull other files into the XS module. The
1429 other files may have XS code. INCLUDE: can also be used to run a
1430 command to generate the XS code to be pulled into the module.
1431 The file Rpcb1.xsh contains our rpcb_gettime() function:
1433 bool_t
1435 rpcb_gettime(host,timep)
1436 char *host
1437 time_t &timep
1438 OUTPUT:
1439 timep
1440 The XS module can use INCLUDE: to pull that file into it.
1442 INCLUDE: Rpcb1.xsh
1444 If the parameters to the INCLUDE: keyword are followed by a pipe ("|")
1446 then the compiler will interpret the parameters as a command. This
1447 feature is mildly deprecated in favour of the "INCLUDE_COMMAND:"
1448 directive, as documented below.
1449 INCLUDE: cat Rpcb1.xsh |
1451 Do not use this to run perl: "INCLUDE: perl |" will run the perl that
1453 happens to be the first in your path and not necessarily the same perl
1454 that is used to run "xsubpp". See "The INCLUDE_COMMAND: Keyword".
1455 The INCLUDE_COMMAND: Keyword
1457 Runs the supplied command and includes its output into the current XS
1458 document. "INCLUDE_COMMAND" assigns special meaning to the $^X token in
1459 that it runs the same perl interpreter that is running "xsubpp":
1460 INCLUDE_COMMAND: cat Rpcb1.xsh
1462 INCLUDE_COMMAND: $^X -e ...
1464 The CASE: Keyword
1466 The CASE: keyword allows an XSUB to have multiple distinct parts with
1467 each part acting as a virtual XSUB. CASE: is greedy and if it is used
1468 then all other XS keywords must be contained within a CASE:. This
1469 means nothing may precede the first CASE: in the XSUB and anything
1470 following the last CASE: is included in that case.
1471 A CASE: might switch via a parameter of the XSUB, via the "ix" ALIAS:
1473 variable (see "The ALIAS: Keyword"), or maybe via the "items" variable
1474 (see "Variable-length Parameter Lists"). The last CASE: becomes the
1475 default case if it is not associated with a conditional. The following
1476 example shows CASE switched via "ix" with a function rpcb_gettime()
1477 having an alias x_gettime(). When the function is called as
1478 rpcb_gettime() its parameters are the usual "(char *host, time_t
1479 *timep)", but when the function is called as x_gettime() its parameters
1480 are reversed, "(time_t *timep, char *host)".
1481 long
1483 rpcb_gettime(a,b)
1484 CASE: ix == 1
1485 ALIAS:
1486 x_gettime = 1
1487 INPUT:
1488 # 'a' is timep, 'b' is host
1489 char *b
1490 time_t a = NO_INIT
1491 CODE:
1492 RETVAL = rpcb_gettime( b, &a );
1493 OUTPUT:
1494 a
1495 RETVAL
1496 CASE:
1497 # 'a' is host, 'b' is timep
1498 char *a
1499 time_t &b = NO_INIT
1500 OUTPUT:
1501 b
1502 RETVAL
1503 That function can be called with either of the following statements.
1505 Note the different argument lists.
1506 $status = rpcb_gettime( $host, $timep );
1508 $status = x_gettime( $timep, $host );
1510 The EXPORT_XSUB_SYMBOLS: Keyword
1512 The EXPORT_XSUB_SYMBOLS: keyword is likely something you will never
1513 need. In perl versions earlier than 5.16.0, this keyword does nothing.
1514 Starting with 5.16, XSUB symbols are no longer exported by default.
1515 That is, they are "static" functions. If you include
1516 EXPORT_XSUB_SYMBOLS: ENABLE
1518 in your XS code, the XSUBs following this line will not be declared
1520 "static". You can later disable this with
1521 EXPORT_XSUB_SYMBOLS: DISABLE
1523 which, again, is the default that you should probably never change.
1525 You cannot use this keyword on versions of perl before 5.16 to make
1526 XSUBs "static".
1527 The & Unary Operator
1529 The "&" unary operator in the INPUT: section is used to tell xsubpp
1530 that it should convert a Perl value to/from C using the C type to the
1531 left of "&", but provide a pointer to this value when the C function is
1532 called.
1533 This is useful to avoid a CODE: block for a C function which takes a
1535 parameter by reference. Typically, the parameter should be not a
1536 pointer type (an "int" or "long" but not an "int*" or "long*").
1537 The following XSUB will generate incorrect C code. The xsubpp compiler
1539 will turn this into code which calls rpcb_gettime() with parameters
1540 "(char *host, time_t timep)", but the real rpcb_gettime() wants the
1541 "timep" parameter to be of type "time_t*" rather than "time_t".
1542 bool_t
1544 rpcb_gettime(host,timep)
1545 char *host
1546 time_t timep
1547 OUTPUT:
1548 timep
1549 That problem is corrected by using the "&" operator. The xsubpp
1551 compiler will now turn this into code which calls rpcb_gettime()
1552 correctly with parameters "(char *host, time_t *timep)". It does this
1553 by carrying the "&" through, so the function call looks like
1554 "rpcb_gettime(host, &timep)".
1555 bool_t
1557 rpcb_gettime(host,timep)
1558 char *host
1559 time_t &timep
1560 OUTPUT:
1561 timep
1562 Inserting POD, Comments and C Preprocessor Directives
1564 C preprocessor directives are allowed within BOOT:, PREINIT: INIT:,
1565 CODE:, PPCODE:, POSTCALL:, and CLEANUP: blocks, as well as outside the
1566 functions. Comments are allowed anywhere after the MODULE keyword.
1567 The compiler will pass the preprocessor directives through untouched
1568 and will remove the commented lines. POD documentation is allowed at
1569 any point, both in the C and XS language sections. POD must be
1570 terminated with a "=cut" command; "xsubpp" will exit with an error if
1571 it does not. It is very unlikely that human generated C code will be
1572 mistaken for POD, as most indenting styles result in whitespace in
1573 front of any line starting with "=". Machine generated XS files may
1574 fall into this trap unless care is taken to ensure that a space breaks
1575 the sequence "\n=".
1576 Comments can be added to XSUBs by placing a "#" as the first non-
1578 whitespace of a line. Care should be taken to avoid making the comment
1579 look like a C preprocessor directive, lest it be interpreted as such.
1580 The simplest way to prevent this is to put whitespace in front of the
1581 "#".
1582 If you use preprocessor directives to choose one of two versions of a
1584 function, use
1585 #if ... version1
1587 #else /* ... version2 */
1588 #endif
1589 and not
1591 #if ... version1
1593 #endif
1594 #if ... version2
1595 #endif
1596 because otherwise xsubpp will believe that you made a duplicate
1598 definition of the function. Also, put a blank line before the
1599 #else/#endif so it will not be seen as part of the function body.
1600 Using XS With C++
1602 If an XSUB name contains "::", it is considered to be a C++ method.
1603 The generated Perl function will assume that its first argument is an
1604 object pointer. The object pointer will be stored in a variable called
1605 THIS. The object should have been created by C++ with the new()
1606 function and should be blessed by Perl with the sv_setref_pv() macro.
1607 The blessing of the object by Perl can be handled by a typemap. An
1608 example typemap is shown at the end of this section.
1609 If the return type of the XSUB includes "static", the method is
1611 considered to be a static method. It will call the C++ function using
1612 the class::method() syntax. If the method is not static the function
1613 will be called using the THIS->method() syntax.
1614 The next examples will use the following C++ class.
1616 class color {
1618 public:
1619 color();
1620 ~color();
1621 int blue();
1622 void set_blue( int );
1623 private:
1625 int c_blue;
1626 };
1627 The XSUBs for the blue() and set_blue() methods are defined with the
1629 class name but the parameter for the object (THIS, or "self") is
1630 implicit and is not listed.
1631 int
1633 color::blue()
1634 void
1636 color::set_blue( val )
1637 int val
1638 Both Perl functions will expect an object as the first parameter. In
1640 the generated C++ code the object is called "THIS", and the method call
1641 will be performed on this object. So in the C++ code the blue() and
1642 set_blue() methods will be called as this:
1643 RETVAL = THIS->blue();
1645 THIS->set_blue( val );
1647 You could also write a single get/set method using an optional
1649 argument:
1650 int
1652 color::blue( val = NO_INIT )
1653 int val
1654 PROTOTYPE $;$
1655 CODE:
1656 if (items > 1)
1657 THIS->set_blue( val );
1658 RETVAL = THIS->blue();
1659 OUTPUT:
1660 RETVAL
1661 If the function's name is DESTROY then the C++ "delete" function will
1663 be called and "THIS" will be given as its parameter. The generated C++
1664 code for
1665 void
1667 color::DESTROY()
1668 will look like this:
1670 color *THIS = ...; // Initialized as in typemap
1672 delete THIS;
1674 If the function's name is new then the C++ "new" function will be
1676 called to create a dynamic C++ object. The XSUB will expect the class
1677 name, which will be kept in a variable called "CLASS", to be given as
1678 the first argument.
1679 color *
1681 color::new()
1682 The generated C++ code will call "new".
1684 RETVAL = new color();
1686 The following is an example of a typemap that could be used for this
1688 C++ example.
1689 TYPEMAP
1691 color * O_OBJECT
1692 OUTPUT
1694 # The Perl object is blessed into 'CLASS', which should be a
1695 # char* having the name of the package for the blessing.
1696 O_OBJECT
1697 sv_setref_pv( $arg, CLASS, (void*)$var );
1698 INPUT
1700 O_OBJECT
1701 if( sv_isobject($arg) && (SvTYPE(SvRV($arg)) == SVt_PVMG) )
1702 $var = ($type)SvIV((SV*)SvRV( $arg ));
1703 else{
1704 warn(\"${Package}::$func_name() -- \"
1705 \"$var is not a blessed SV reference\");
1706 XSRETURN_UNDEF;
1707 }
1708 Interface Strategy
1710 When designing an interface between Perl and a C library a straight
1711 translation from C to XS (such as created by "h2xs -x") is often
1712 sufficient. However, sometimes the interface will look very C-like and
1713 occasionally nonintuitive, especially when the C function modifies one
1714 of its parameters, or returns failure inband (as in "negative return
1715 values mean failure"). In cases where the programmer wishes to create
1716 a more Perl-like interface the following strategy may help to identify
1717 the more critical parts of the interface.
1718 Identify the C functions with input/output or output parameters. The
1720 XSUBs for these functions may be able to return lists to Perl.
1721 Identify the C functions which use some inband info as an indication of
1723 failure. They may be candidates to return undef or an empty list in
1724 case of failure. If the failure may be detected without a call to the
1725 C function, you may want to use an INIT: section to report the failure.
1726 For failures detectable after the C function returns one may want to
1727 use a POSTCALL: section to process the failure. In more complicated
1728 cases use CODE: or PPCODE: sections.
1729 If many functions use the same failure indication based on the return
1731 value, you may want to create a special typedef to handle this
1732 situation. Put
1733 typedef int negative_is_failure;
1735 near the beginning of XS file, and create an OUTPUT typemap entry for
1737 "negative_is_failure" which converts negative values to "undef", or
1738 maybe croak()s. After this the return value of type
1739 "negative_is_failure" will create more Perl-like interface.
1740 Identify which values are used by only the C and XSUB functions
1742 themselves, say, when a parameter to a function should be a contents of
1743 a global variable. If Perl does not need to access the contents of the
1744 value then it may not be necessary to provide a translation for that
1745 value from C to Perl.
1746 Identify the pointers in the C function parameter lists and return
1748 values. Some pointers may be used to implement input/output or output
1749 parameters, they can be handled in XS with the "&" unary operator, and,
1750 possibly, using the NO_INIT keyword. Some others will require handling
1751 of types like "int *", and one needs to decide what a useful Perl
1752 translation will do in such a case. When the semantic is clear, it is
1753 advisable to put the translation into a typemap file.
1754 Identify the structures used by the C functions. In many cases it may
1756 be helpful to use the T_PTROBJ typemap for these structures so they can
1757 be manipulated by Perl as blessed objects. (This is handled
1758 automatically by "h2xs -x".)
1759 If the same C type is used in several different contexts which require
1761 different translations, "typedef" several new types mapped to this C
1762 type, and create separate typemap entries for these new types. Use
1763 these types in declarations of return type and parameters to XSUBs.
1764 Perl Objects And C Structures
1766 When dealing with C structures one should select either T_PTROBJ or
1767 T_PTRREF for the XS type. Both types are designed to handle pointers
1768 to complex objects. The T_PTRREF type will allow the Perl object to be
1769 unblessed while the T_PTROBJ type requires that the object be blessed.
1770 By using T_PTROBJ one can achieve a form of type-checking because the
1771 XSUB will attempt to verify that the Perl object is of the expected
1772 type.
1773 The following XS code shows the getnetconfigent() function which is
1775 used with ONC+ TIRPC. The getnetconfigent() function will return a
1776 pointer to a C structure and has the C prototype shown below. The
1777 example will demonstrate how the C pointer will become a Perl
1778 reference. Perl will consider this reference to be a pointer to a
1779 blessed object and will attempt to call a destructor for the object. A
1780 destructor will be provided in the XS source to free the memory used by
1781 getnetconfigent(). Destructors in XS can be created by specifying an
1782 XSUB function whose name ends with the word DESTROY. XS destructors
1783 can be used to free memory which may have been malloc'd by another
1784 XSUB.
1785 struct netconfig *getnetconfigent(const char *netid);
1787 A "typedef" will be created for "struct netconfig". The Perl object
1789 will be blessed in a class matching the name of the C type, with the
1790 tag "Ptr" appended, and the name should not have embedded spaces if it
1791 will be a Perl package name. The destructor will be placed in a class
1792 corresponding to the class of the object and the PREFIX keyword will be
1793 used to trim the name to the word DESTROY as Perl will expect.
1794 typedef struct netconfig Netconfig;
1796 MODULE = RPC PACKAGE = RPC
1798 Netconfig *
1800 getnetconfigent(netid)
1801 char *netid
1802 MODULE = RPC PACKAGE = NetconfigPtr PREFIX = rpcb_
1804 void
1806 rpcb_DESTROY(netconf)
1807 Netconfig *netconf
1808 CODE:
1809 printf("Now in NetconfigPtr::DESTROY\n");
1810 free( netconf );
1811 This example requires the following typemap entry. Consult
1813 perlxstypemap for more information about adding new typemaps for an
1814 extension.
1815 TYPEMAP
1817 Netconfig * T_PTROBJ
1818 This example will be used with the following Perl statements.
1820 use RPC;
1822 $netconf = getnetconfigent("udp");
1823 When Perl destroys the object referenced by $netconf it will send the
1825 object to the supplied XSUB DESTROY function. Perl cannot determine,
1826 and does not care, that this object is a C struct and not a Perl
1827 object. In this sense, there is no difference between the object
1828 created by the getnetconfigent() XSUB and an object created by a normal
1829 Perl subroutine.
1830 Safely Storing Static Data in XS
1832 Starting with Perl 5.8, a macro framework has been defined to allow
1833 static data to be safely stored in XS modules that will be accessed
1834 from a multi-threaded Perl.
1835 Although primarily designed for use with multi-threaded Perl, the
1837 macros have been designed so that they will work with non-threaded Perl
1838 as well.
1839 It is therefore strongly recommended that these macros be used by all
1841 XS modules that make use of static data.
1842 The easiest way to get a template set of macros to use is by specifying
1844 the "-g" ("--global") option with h2xs (see h2xs).
1845 Below is an example module that makes use of the macros.
1847 #define PERL_NO_GET_CONTEXT
1849 #include "EXTERN.h"
1850 #include "perl.h"
1851 #include "XSUB.h"
1852 /* Global Data */
1854 #define MY_CXT_KEY "BlindMice::_guts" XS_VERSION
1856 typedef struct {
1858 int count;
1859 char name[3][100];
1860 } my_cxt_t;
1861 START_MY_CXT
1863 MODULE = BlindMice PACKAGE = BlindMice
1865 BOOT:
1867 {
1868 MY_CXT_INIT;
1869 MY_CXT.count = 0;
1870 strcpy(MY_CXT.name[0], "None");
1871 strcpy(MY_CXT.name[1], "None");
1872 strcpy(MY_CXT.name[2], "None");
1873 }
1874 int
1876 newMouse(char * name)
1877 PREINIT:
1878 dMY_CXT;
1879 CODE:
1880 if (MY_CXT.count >= 3) {
1881 warn("Already have 3 blind mice");
1882 RETVAL = 0;
1883 }
1884 else {
1885 RETVAL = ++ MY_CXT.count;
1886 strcpy(MY_CXT.name[MY_CXT.count - 1], name);
1887 }
1888 OUTPUT:
1889 RETVAL
1890 char *
1892 get_mouse_name(index)
1893 int index
1894 PREINIT:
1895 dMY_CXT;
1896 CODE:
1897 if (index > MY_CXT.count)
1898 croak("There are only 3 blind mice.");
1899 else
1900 RETVAL = MY_CXT.name[index - 1];
1901 OUTPUT:
1902 RETVAL
1903 void
1905 CLONE(...)
1906 CODE:
1907 MY_CXT_CLONE;
1908 MY_CXT REFERENCE
1910 MY_CXT_KEY
1912 This macro is used to define a unique key to refer to the static
1913 data for an XS module. The suggested naming scheme, as used by
1914 h2xs, is to use a string that consists of the module name, the
1915 string "::_guts" and the module version number.
1916 #define MY_CXT_KEY "MyModule::_guts" XS_VERSION
1918 typedef my_cxt_t
1920 This struct typedef must always be called "my_cxt_t". The other
1921 "CXT*" macros assume the existence of the "my_cxt_t" typedef name.
1922 Declare a typedef named "my_cxt_t" that is a structure that
1924 contains all the data that needs to be interpreter-local.
1925 typedef struct {
1927 int some_value;
1928 } my_cxt_t;
1929 START_MY_CXT
1931 Always place the START_MY_CXT macro directly after the declaration
1932 of "my_cxt_t".
1933 MY_CXT_INIT
1935 The MY_CXT_INIT macro initializes storage for the "my_cxt_t"
1936 struct.
1937 It must be called exactly once, typically in a BOOT: section. If
1939 you are maintaining multiple interpreters, it should be called
1940 once in each interpreter instance, except for interpreters cloned
1941 from existing ones. (But see "MY_CXT_CLONE" below.)
1942 dMY_CXT
1944 Use the dMY_CXT macro (a declaration) in all the functions that
1945 access MY_CXT.
1946 MY_CXT
1948 Use the MY_CXT macro to access members of the "my_cxt_t" struct.
1949 For example, if "my_cxt_t" is
1950 typedef struct {
1952 int index;
1953 } my_cxt_t;
1954 then use this to access the "index" member
1956 dMY_CXT;
1958 MY_CXT.index = 2;
1959 aMY_CXT/pMY_CXT
1961 "dMY_CXT" may be quite expensive to calculate, and to avoid the
1962 overhead of invoking it in each function it is possible to pass
1963 the declaration onto other functions using the "aMY_CXT"/"pMY_CXT"
1964 macros, eg
1965 void sub1() {
1967 dMY_CXT;
1968 MY_CXT.index = 1;
1969 sub2(aMY_CXT);
1970 }
1971 void sub2(pMY_CXT) {
1973 MY_CXT.index = 2;
1974 }
1975 Analogously to "pTHX", there are equivalent forms for when the
1977 macro is the first or last in multiple arguments, where an
1978 underscore represents a comma, i.e. "_aMY_CXT", "aMY_CXT_",
1979 "_pMY_CXT" and "pMY_CXT_".
1980 MY_CXT_CLONE
1982 By default, when a new interpreter is created as a copy of an
1983 existing one (eg via "threads->create()"), both interpreters share
1984 the same physical my_cxt_t structure. Calling "MY_CXT_CLONE"
1985 (typically via the package's CLONE() function), causes a byte-for-
1986 byte copy of the structure to be taken, and any future dMY_CXT
1987 will cause the copy to be accessed instead.
1988 MY_CXT_INIT_INTERP(my_perl)
1990 dMY_CXT_INTERP(my_perl)
1991 These are versions of the macros which take an explicit
1992 interpreter as an argument.
1993 Note that these macros will only work together within the same source
1995 file; that is, a dMY_CTX in one source file will access a different
1996 structure than a dMY_CTX in another source file.
1997 Thread-aware system interfaces
1999 Starting from Perl 5.8, in C/C++ level Perl knows how to wrap
2000 system/library interfaces that have thread-aware versions (e.g.
2001 getpwent_r()) into frontend macros (e.g. getpwent()) that correctly
2002 handle the multithreaded interaction with the Perl interpreter. This
2003 will happen transparently, the only thing you need to do is to
2004 instantiate a Perl interpreter.
2005 This wrapping happens always when compiling Perl core source (PERL_CORE
2007 is defined) or the Perl core extensions (PERL_EXT is defined). When
2008 compiling XS code outside of the Perl core, the wrapping does not take
2009 place before Perl 5.28. Starting in that release you can
2010 #define PERL_REENTRANT
2012 in your code to enable the wrapping. It is advisable to do so if you
2014 are using such functions, as intermixing the "_r"-forms (as Perl
2015 compiled for multithreaded operation will do) and the "_r"-less forms
2016 is neither well-defined (inconsistent results, data corruption, or even
2017 crashes become more likely), nor is it very portable. Unfortunately,
2018 not all systems have all the "_r" forms, but using this "#define" gives
2019 you whatever protection that Perl is aware is available on each system.
2020
2022 File "RPC.xs": Interface to some ONC+ RPC bind library functions.
2023 #define PERL_NO_GET_CONTEXT
2025 #include "EXTERN.h"
2026 #include "perl.h"
2027 #include "XSUB.h"
2028 /* Note: On glibc 2.13 and earlier, this needs be <rpc/rpc.h> */
2030 #include <tirpc/rpc.h>
2031 typedef struct netconfig Netconfig;
2033 MODULE = RPC PACKAGE = RPC
2035 SV *
2037 rpcb_gettime(host="localhost")
2038 char *host
2039 PREINIT:
2040 time_t timep;
2041 CODE:
2042 ST(0) = sv_newmortal();
2043 if( rpcb_gettime( host, &timep ) )
2044 sv_setnv( ST(0), (double)timep );
2045 Netconfig *
2047 getnetconfigent(netid="udp")
2048 char *netid
2049 MODULE = RPC PACKAGE = NetconfigPtr PREFIX = rpcb_
2051 void
2053 rpcb_DESTROY(netconf)
2054 Netconfig *netconf
2055 CODE:
2056 printf("NetconfigPtr::DESTROY\n");
2057 free( netconf );
2058 File "typemap": Custom typemap for RPC.xs. (cf. perlxstypemap)
2060 TYPEMAP
2062 Netconfig * T_PTROBJ
2063 File "RPC.pm": Perl module for the RPC extension.
2065 package RPC;
2067 require Exporter;
2069 require DynaLoader;
2070 @ISA = qw(Exporter DynaLoader);
2071 @EXPORT = qw(rpcb_gettime getnetconfigent);
2072 bootstrap RPC;
2074 1;
2075 File "rpctest.pl": Perl test program for the RPC extension.
2077 use RPC;
2079 $netconf = getnetconfigent();
2081 $a = rpcb_gettime();
2082 print "time = $a\n";
2083 print "netconf = $netconf\n";
2084 $netconf = getnetconfigent("tcp");
2086 $a = rpcb_gettime("poplar");
2087 print "time = $a\n";
2088 print "netconf = $netconf\n";
2089 In Makefile.PL add -ltirpc and -I/usr/include/tirpc.
2091
2093 XS code has full access to system calls including C library functions.
2094 It thus has the capability of interfering with things that the Perl
2095 core or other modules have set up, such as signal handlers or file
2096 handles. It could mess with the memory, or any number of harmful
2097 things. Don't.
2098 Some modules have an event loop, waiting for user-input. It is highly
2100 unlikely that two such modules would work adequately together in a
2101 single Perl application.
2102 In general, the perl interpreter views itself as the center of the
2104 universe as far as the Perl program goes. XS code is viewed as a help-
2105 mate, to accomplish things that perl doesn't do, or doesn't do fast
2106 enough, but always subservient to perl. The closer XS code adheres to
2107 this model, the less likely conflicts will occur.
2108 One area where there has been conflict is in regards to C locales.
2110 (See perllocale.) perl, with one exception and unless told otherwise,
2111 sets up the underlying locale the program is running in to the locale
2112 passed into it from the environment. This is an important difference
2113 from a generic C language program, where the underlying locale is the
2114 "C" locale unless the program changes it. As of v5.20, this underlying
2115 locale is completely hidden from pure Perl code outside the lexical
2116 scope of "use locale" except for a couple of function calls in the
2117 POSIX module which of necessity use it. But the underlying locale,
2118 with that one exception is exposed to XS code, affecting all C library
2119 routines whose behavior is locale-dependent. Your XS code better not
2120 assume that the underlying locale is "C". The exception is the
2121 "LC_NUMERIC" locale category, and the reason it is an exception is that
2122 experience has shown that it can be problematic for XS code, whereas we
2123 have not had reports of problems with the other locale categories. And
2124 the reason for this one category being problematic is that the
2125 character used as a decimal point can vary. Many European languages
2126 use a comma, whereas English, and hence Perl are expecting a dot
2127 (U+002E: FULL STOP). Many modules can handle only the radix character
2128 being a dot, and so perl attempts to make it so. Up through Perl
2129 v5.20, the attempt was merely to set "LC_NUMERIC" upon startup to the
2130 "C" locale. Any setlocale() otherwise would change it; this caused
2131 some failures. Therefore, starting in v5.22, perl tries to keep
2132 "LC_NUMERIC" always set to "C" for XS code.
2133 To summarize, here's what to expect and how to handle locales in XS
2135 code:
2136 Non-locale-aware XS code
2138 Keep in mind that even if you think your code is not locale-aware,
2139 it may call a library function that is. Hopefully the man page for
2140 such a function will indicate that dependency, but the
2141 documentation is imperfect.
2142 The current locale is exposed to XS code except possibly
2144 "LC_NUMERIC" (explained in the next paragraph). There have not
2145 been reports of problems with the other categories. Perl
2146 initializes things on start-up so that the current locale is the
2147 one which is indicated by the user's environment in effect at that
2148 time. See "ENVIRONMENT" in perllocale.
2149 However, up through v5.20, Perl initialized things on start-up so
2151 that "LC_NUMERIC" was set to the "C" locale. But if any code
2152 anywhere changed it, it would stay changed. This means that your
2153 module can't count on "LC_NUMERIC" being something in particular,
2154 and you can't expect floating point numbers (including version
2155 strings) to have dots in them. If you don't allow for a non-dot,
2156 your code could break if anyone anywhere changed the locale. For
2157 this reason, v5.22 changed the behavior so that Perl tries to keep
2158 "LC_NUMERIC" in the "C" locale except around the operations
2159 internally where it should be something else. Misbehaving XS code
2160 will always be able to change the locale anyway, but the most
2161 common instance of this is checked for and handled.
2162 Locale-aware XS code
2164 If the locale from the user's environment is desired, there should
2165 be no need for XS code to set the locale except for "LC_NUMERIC",
2166 as perl has already set the others up. XS code should avoid
2167 changing the locale, as it can adversely affect other, unrelated,
2168 code and may not be thread-safe. To minimize problems, the macros
2169 "STORE_LC_NUMERIC_SET_TO_NEEDED" in perlapi,
2170 "STORE_LC_NUMERIC_FORCE_TO_UNDERLYING" in perlapi, and
2171 "RESTORE_LC_NUMERIC" in perlapi should be used to affect any needed
2172 change.
2173 But, starting with Perl v5.28, locales are thread-safe on platforms
2175 that support this functionality. Windows has this starting with
2176 Visual Studio 2005. Many other modern platforms support the
2177 thread-safe POSIX 2008 functions. The C "#define"
2178 "USE_THREAD_SAFE_LOCALE" will be defined iff this build is using
2179 these. From Perl-space, the read-only variable "${SAFE_LOCALES}"
2180 is 1 if either the build is not threaded, or if
2181 "USE_THREAD_SAFE_LOCALE" is defined; otherwise it is 0.
2182 The way this works under-the-hood is that every thread has a choice
2184 of using a locale specific to it (this is the Windows and POSIX
2185 2008 functionality), or the global locale that is accessible to all
2186 threads (this is the functionality that has always been there).
2187 The implementations for Windows and POSIX are completely different.
2188 On Windows, the runtime can be set up so that the standard
2189 setlocale(3) function either only knows about the global locale or
2190 the locale for this thread. On POSIX, "setlocale" always deals
2191 with the global locale, and other functions have been created to
2192 handle per-thread locales. Perl makes this transparent to perl-
2193 space code. It continues to use POSIX::setlocale(), and the
2194 interpreter translates that into the per-thread functions.
2195 All other locale-sensitive functions automatically use the per-
2197 thread locale, if that is turned on, and failing that, the global
2198 locale. Thus calls to "setlocale" are ineffective on POSIX systems
2199 for the current thread if that thread is using a per-thread locale.
2200 If perl is compiled for single-thread operation, it does not use
2201 the per-thread functions, so "setlocale" does work as expected.
2202 If you have loaded the "POSIX" module you can use the methods given
2204 in perlcall to call "POSIX::setlocale" to safely change or query
2205 the locale (on systems where it is safe to do so), or you can use
2206 the new 5.28 function "Perl_setlocale" in perlapi instead, which is
2207 a drop-in replacement for the system setlocale(3), and handles
2208 single-threaded and multi-threaded applications transparently.
2209 There are some locale-related library calls that still aren't
2211 thread-safe because they return data in a buffer global to all
2212 threads. In the past, these didn't matter as locales weren't
2213 thread-safe at all. But now you have to be aware of them in case
2214 your module is called in a multi-threaded application. The known
2215 ones are
2216 asctime()
2218 ctime()
2219 gcvt() [POSIX.1-2001 only (function removed in POSIX.1-2008)]
2220 getdate()
2221 wcrtomb() if its final argument is NULL
2222 wcsrtombs() if its final argument is NULL
2223 wcstombs()
2224 wctomb()
2225 Some of these shouldn't really be called in a Perl application, and
2227 for others there are thread-safe versions of these already
2228 implemented:
2229 asctime_r()
2231 ctime_r()
2232 Perl_langinfo()
2233 The "_r" forms are automatically used, starting in Perl 5.28, if
2235 you compile your code, with
2236 #define PERL_REENTRANT
2238 See also "Perl_langinfo" in perlapi. You can use the methods given
2240 in perlcall, to get the best available locale-safe versions of
2241 these
2242 POSIX::localeconv()
2244 POSIX::wcstombs()
2245 POSIX::wctomb()
2246 And note, that some items returned by "Localeconv" are available
2248 through "Perl_langinfo" in perlapi.
2249 The others shouldn't be used in a threaded application.
2251 Some modules may call a non-perl library that is locale-aware.
2253 This is fine as long as it doesn't try to query or change the
2254 locale using the system "setlocale". But if these do call the
2255 system "setlocale", those calls may be ineffective. Instead,
2256 "Perl_setlocale" works in all circumstances. Plain setlocale is
2257 ineffective on multi-threaded POSIX 2008 systems. It operates only
2258 on the global locale, whereas each thread has its own locale,
2259 paying no attention to the global one. Since converting these non-
2260 Perl libraries to "Perl_setlocale" is out of the question, there is
2261 a new function in v5.28 "switch_to_global_locale" that will switch
2262 the thread it is called from so that any system "setlocale" calls
2263 will have their desired effect. The function "sync_locale" must be
2264 called before returning to perl.
2265 This thread can change the locale all it wants and it won't affect
2267 any other thread, except any that also have been switched to the
2268 global locale. This means that a multi-threaded application can
2269 have a single thread using an alien library without a problem; but
2270 no more than a single thread can be so-occupied. Bad results
2271 likely will happen.
2272 In perls without multi-thread locale support, some alien libraries,
2274 such as "Gtk" change locales. This can cause problems for the Perl
2275 core and other modules. For these, before control is returned to
2276 perl, starting in v5.20.1, calling the function sync_locale() from
2277 XS should be sufficient to avoid most of these problems. Prior to
2278 this, you need a pure Perl statement that does this:
2279 POSIX::setlocale(LC_ALL, POSIX::setlocale(LC_ALL));
2281 or use the methods given in perlcall.
2283
2285 This document covers features supported by "ExtUtils::ParseXS" (also
2286 known as "xsubpp") 3.13_01.
2287
2289 Originally written by Dean Roehrich <roehrich@cray.com>.
2290 Maintained since 1996 by The Perl Porters <perl5-porters@perl.org>.
2292perl v5.36.0 2023-01-20 perlxs(3)