1perlxs(3)             User Contributed Perl Documentation            perlxs(3)
2
3
4

NAME

6       perlxs - XS language reference manual
7

DESCRIPTION

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
17       Before writing XS, read the "CAVEATS" section below.
18
19       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
24       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
32       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
40       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
48       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
59       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
68       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
75       See perlxstut for a tutorial on the whole extension creation process.
76
77       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
81       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
86   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
94               bool_t rpcb_gettime(const char *host, time_t *timep);
95
96       From C this function will be called with the following statements.
97
98            #include <rpc/rpc.h>
99            bool_t status;
100            time_t timep;
101            status = rpcb_gettime( "localhost", &timep );
102
103       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
108            use RPC;
109            $status = rpcb_gettime( "localhost", $timep );
110
111       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
122            #define PERL_NO_GET_CONTEXT
123            #include "EXTERN.h"
124            #include "perl.h"
125            #include "XSUB.h"
126            #include <rpc/rpc.h>
127
128            MODULE = RPC  PACKAGE = RPC
129
130            bool_t
131            rpcb_gettime(host,timep)
132                 char *host
133                 time_t &timep
134               OUTPUT:
135                 timep
136
137       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
146            package RPC;
147
148            require Exporter;
149            require DynaLoader;
150            @ISA = qw(Exporter DynaLoader);
151            @EXPORT = qw( rpcb_gettime );
152
153            bootstrap RPC;
154            1;
155
156       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
165   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
170       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
174            double
175            sin(x)
176              double x
177
178       Optionally, one can merge the description of types and the list of
179       argument names, rewriting this as
180
181            double
182            sin(double x)
183
184       This makes this XSUB look similar to an ANSI C declaration.  An
185       optional semicolon is allowed after the argument list, as in
186
187            double
188            sin(double x);
189
190       Parameters with C pointer types can have different semantic: C
191       functions with similar declarations
192
193            bool string_looks_as_a_number(char *s);
194            bool make_char_uppercase(char *c);
195
196       are used in absolutely incompatible manner.  Parameters to these
197       functions could be described to xsubpp like this:
198
199            char *  s
200            char    &c
201
202       Both these XS declarations correspond to the "char*" C type, but they
203       have different semantics, see "The & Unary Operator".
204
205       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
210       The function name and the return type must be placed on separate lines
211       and should be flush left-adjusted.
212
213         INCORRECT                        CORRECT
214
215         double sin(x)                    double
216           double x                       sin(x)
217                                            double x
218
219       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
224         CORRECT
225
226         double
227         sin(x)
228         double x
229
230       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
238       An XSUB section continues until another section-start keyword is found.
239
240   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
249       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
257   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
267       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
272       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
276       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
285   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
294         void
295         alpha()
296             PPCODE:
297                 ST(0) = newSVpv("Hello World",0);
298                 sv_2mortal(ST(0));
299                 XSRETURN(1);
300
301         SV *
302         beta()
303             CODE:
304                 RETVAL = newSVpv("Hello World",0);
305             OUTPUT:
306                 RETVAL
307
308       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
312         AV *
313         array()
314             CODE:
315                 RETVAL = newAV();
316                 /* do something with RETVAL */
317             OUTPUT:
318                 RETVAL
319
320       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
329         AV*   T_AVREF_REFCOUNT_FIXED
330
331       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
336         AV *
337         array()
338             CODE:
339                 RETVAL = newAV();
340                 sv_2mortal((SV*)RETVAL);
341                 /* do something with RETVAL */
342             OUTPUT:
343                 RETVAL
344
345       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
348   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
359       The following example will start the XS code and will place all
360       functions in a package named RPC.
361
362            MODULE = RPC
363
364   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
369            MODULE = RPC  PACKAGE = RPC
370
371            [ XS code in package RPC ]
372
373            MODULE = RPC  PACKAGE = RPCB
374
375            [ XS code in package RPCB ]
376
377            MODULE = RPC  PACKAGE = RPC
378
379            [ XS code in package RPC ]
380
381       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
385       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
389   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
395       This keyword should follow the PACKAGE keyword when used.  If PACKAGE
396       is not used then PREFIX should follow the MODULE keyword.
397
398            MODULE = RPC  PREFIX = rpc_
399
400            MODULE = RPC  PACKAGE = RPCB  PREFIX = rpcb_
401
402   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
412       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
418       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
423            bool_t
424            rpcb_gettime(host,timep)
425                 char *host
426                 time_t &timep
427               OUTPUT:
428                 timep
429
430       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
433            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
440       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
451   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
457       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
462       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
467         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
473       Here the generated XS function returns nothing on success, and will
474       die() with a meaningful error message on error.
475
476   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
482       The following XSUB is for a C function which requires special handling
483       of its parameters.  The Perl usage is given first.
484
485            $status = rpcb_gettime( "localhost", $timep );
486
487       The XSUB follows.
488
489            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
499   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
505           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
514       Another use for the INIT: section is to check for preconditions before
515       making a call to the C function:
516
517           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
527   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
536       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
540            bool_t
541            rpcb_gettime(host,timep)
542                 char *host
543                 time_t &timep = NO_INIT
544               OUTPUT:
545                 timep
546
547   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
556             TYPEMAP: <<HERE
557             ... your typemap code here ...
558             HERE
559
560       where the "TYPEMAP" keyword must appear in the first column of a new
561       line.
562
563       Refer to perlxstypemap for details on writing typemaps.
564
565   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
576       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
583            bool_t
584            rpcb_gettime(host,timep)
585                 char *host = (char *)SvPVbyte_nolen($arg);
586                 time_t &timep = 0;
587               OUTPUT:
588                 timep
589
590       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
595       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
605       Here's a truly obscure example:
606
607            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
614       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
621   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
627       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
633            $status = rpcb_gettime( $timep, $host );
634
635            $status = rpcb_gettime( $timep );
636
637       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
641            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
651   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
656       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
664       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
669       The following examples are equivalent, but if the code is using complex
670       typemaps then the first example is safer.
671
672            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
683       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
687            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
697       Another way to declare "host" is to use a C block in the CODE: section:
698
699            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
711       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
715           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
724       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
729       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
734           MyObject
735           mutate(o)
736                 MyState st = global_state;
737                 MyObject o;
738               CLEANUP:
739                 reset_to(global_state, st);
740
741       and the code for rpcb_gettime() can be rewritten as
742
743            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
753   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
757       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
761       To enable scoping:
762
763           SCOPE: ENABLE
764
765       To disable scoping:
766
767           SCOPE: DISABLE
768
769   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
776       The following example shows how the input parameter "timep" can be
777       evaluated late, after a PREINIT.
778
779           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
793       The next example shows each input parameter evaluated late.
794
795           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
813       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
816           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
829       (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
834   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
840       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
846       Parameters preceded by "OUTLIST" keyword do not appear in the usage
847       signature of the generated Perl function.
848
849       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
856       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
863       For example, an XSUB
864
865         void
866         day_month(OUTLIST day, IN unix_time, OUTLIST month)
867           int day
868           int unix_time
869           int month
870
871       should be used from Perl as
872
873         my ($day, $month) = day_month(time);
874
875       The C signature of the corresponding function should be
876
877         void day_month(int *day, int unix_time, int *month);
878
879       The "IN"/"OUTLIST"/"IN_OUTLIST"/"IN_OUT"/"OUT" keywords can be mixed
880       with ANSI-style declarations, as in
881
882         void
883         day_month(OUTLIST int day, int unix_time, OUTLIST int month)
884
885       (here the optional "IN" keyword is omitted).
886
887       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
894       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
900         void day_month(OUT int day, int unix_time, OUT int month);
901
902       or
903
904         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
913       However, the generated Perl function is called in very C-ish style:
914
915         my ($day, $month);
916         day_month($day, time, $month);
917
918   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
924         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
934         MODULE = x            PACKAGE = x
935
936         void dump_chars(char *s, short length(s))
937
938       should be called as "dump_chars($string)".
939
940       This directive is supported with ANSI-type function declarations only.
941
942   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
951       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
956            $status = rpcb_gettime( $timep, $host );
957
958            $status = rpcb_gettime( $timep );
959
960       The XS code, with ellipsis, follows.
961
962            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
975   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
981       For example, suppose that a C function is declared as
982
983           symbolic nth_derivative(int n, symbolic function, int flags);
984
985       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
989           $second_deriv = $function->nth_derivative(2);
990
991       To do this, declare the XSUB as
992
993           symbolic
994           nth_derivative(function, n)
995               symbolic        function
996               int             n
997             C_ARGS:
998               n, function, default_flags
999
1000   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
1009       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
1019       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
1026       Note that macros ST(i), "XST_m*()" and "XSRETURN*()" work equally well
1027       in CODE: sections and PPCODE: sections.
1028
1029       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
1033            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
1045       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
1049       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
1054       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
1060       Now the rpcb_gettime() function can be used from Perl with the
1061       following statement.
1062
1063            ($status, $timep) = rpcb_gettime("localhost");
1064
1065       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
1069   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
1077            $timep = rpcb_gettime( "localhost" );
1078
1079       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
1085            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
1096       The next example demonstrates how one would place an explicit undef in
1097       the return value, should the need arise.
1098
1099            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
1114       To return an empty list one must use a PPCODE: block and then not push
1115       return values on the stack.
1116
1117            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
1130       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
1136       Since "XSRETURN_*" macros can be used with CODE blocks as well, one can
1137       rewrite this example as:
1138
1139            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
1151       In fact, one can put this check into a POSTCALL: section as well.
1152       Together with PREINIT: simplifications, this leads to:
1153
1154            int
1155            rpcb_gettime(host)
1156                 char *host
1157                 time_t  timep;
1158               POSTCALL:
1159                 if (RETVAL == 0)
1160                       XSRETURN_UNDEF;
1161
1162   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
1168               REQUIRE: 1.922
1169
1170   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
1177   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
1183       See examples in "The NO_OUTPUT Keyword" and "Returning Undef And Empty
1184       Lists".
1185
1186       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
1189   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
1196       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
1200            BOOT:
1201            # The following message will be printed when the
1202            # bootstrap function executes.
1203            printf("Hello from the bootstrap!\n");
1204
1205   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
1212       To enable version checking:
1213
1214           VERSIONCHECK: ENABLE
1215
1216       To disable version checking:
1217
1218           VERSIONCHECK: DISABLE
1219
1220       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
1226   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
1235           Please specify prototyping behavior for Foo.xs (see perlxs manual)
1236
1237       To enable prototypes:
1238
1239           PROTOTYPES: ENABLE
1240
1241       To disable prototypes:
1242
1243           PROTOTYPES: DISABLE
1244
1245   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
1252           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
1266       If the prototypes are enabled, you can disable it locally for a given
1267       XSUB as in the following example:
1268
1269           void
1270           rpcb_gettime_noproto()
1271               PROTOTYPE: DISABLE
1272           ...
1273
1274   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
1282       The following example will create aliases "FOO::gettime()" and
1283       "BAR::getit()" for this function.
1284
1285           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
1297   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
1307       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
1311       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
1316       To use the OVERLOAD: keyword, create an XS function which takes three
1317       input parameters (or use the C-style '...' definition) like this:
1318
1319           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
1327       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
1333       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
1337   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
1342           MODULE = RPC  PACKAGE = RPC
1343
1344           FALLBACK: TRUE
1345           ...
1346
1347       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
1353   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
1359       For example, if you have 4 C functions multiply(), divide(), add(),
1360       subtract() all having the signature:
1361
1362           symbolic f(symbolic, symbolic);
1363
1364       you can make them all to use the same XSUB using this:
1365
1366           symbolic
1367           interface_s_ss(arg1, arg2)
1368               symbolic        arg1
1369               symbolic        arg2
1370           INTERFACE:
1371               multiply divide
1372               add subtract
1373
1374       (This is the complete XSUB code for 4 Perl functions!)  Four generated
1375       Perl function share names with corresponding C functions.
1376
1377       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
1383           CV *mycv = newXSproto("Symbolic::remainder",
1384                                 XS_Symbolic_interface_s_ss, __FILE__, "$$");
1385           XSINTERFACE_FUNC_SET(mycv, remainder);
1386
1387       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
1391   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
1399       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
1403       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
1408           #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
1413       in C section,
1414
1415           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
1426       in XSUB section.
1427
1428   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
1433       The file Rpcb1.xsh contains our "rpcb_gettime()" function:
1434
1435           bool_t
1436           rpcb_gettime(host,timep)
1437                 char *host
1438                 time_t &timep
1439               OUTPUT:
1440                 timep
1441
1442       The XS module can use INCLUDE: to pull that file into it.
1443
1444           INCLUDE: Rpcb1.xsh
1445
1446       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
1451           INCLUDE: cat Rpcb1.xsh |
1452
1453       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
1457   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
1462           INCLUDE_COMMAND: cat Rpcb1.xsh
1463
1464           INCLUDE_COMMAND: $^X -e ...
1465
1466   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
1473       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
1483           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
1505       That function can be called with either of the following statements.
1506       Note the different argument lists.
1507
1508               $status = rpcb_gettime( $host, $timep );
1509
1510               $status = x_gettime( $timep, $host );
1511
1512   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
1518         EXPORT_XSUB_SYMBOLS: ENABLE
1519
1520       in your XS code, the XSUBs following this line will not be declared
1521       "static".  You can later disable this with
1522
1523         EXPORT_XSUB_SYMBOLS: DISABLE
1524
1525       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
1529   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
1535       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
1539       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
1544           bool_t
1545           rpcb_gettime(host,timep)
1546                 char *host
1547                 time_t timep
1548               OUTPUT:
1549                 timep
1550
1551       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
1557           bool_t
1558           rpcb_gettime(host,timep)
1559                 char *host
1560                 time_t &timep
1561               OUTPUT:
1562                 timep
1563
1564   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
1578       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
1584       If you use preprocessor directives to choose one of two versions of a
1585       function, use
1586
1587           #if ... version1
1588           #else /* ... version2  */
1589           #endif
1590
1591       and not
1592
1593           #if ... version1
1594           #endif
1595           #if ... version2
1596           #endif
1597
1598       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
1602   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
1611       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
1616       The next examples will use the following C++ class.
1617
1618            class color {
1619                 public:
1620                 color();
1621                 ~color();
1622                 int blue();
1623                 void set_blue( int );
1624
1625                 private:
1626                 int c_blue;
1627            };
1628
1629       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
1633            int
1634            color::blue()
1635
1636            void
1637            color::set_blue( val )
1638                 int val
1639
1640       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
1645            RETVAL = THIS->blue();
1646
1647            THIS->set_blue( val );
1648
1649       You could also write a single get/set method using an optional
1650       argument:
1651
1652            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
1663       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
1667            void
1668            color::DESTROY()
1669
1670       will look like this:
1671
1672            color *THIS = ...;  // Initialized as in typemap
1673
1674            delete THIS;
1675
1676       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
1681            color *
1682            color::new()
1683
1684       The generated C++ code will call "new".
1685
1686            RETVAL = new color();
1687
1688       The following is an example of a typemap that could be used for this
1689       C++ example.
1690
1691           TYPEMAP
1692           color *  O_OBJECT
1693
1694           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
1700           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
1710   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
1720       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
1723       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
1731       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
1735         typedef int negative_is_failure;
1736
1737       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
1742       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
1748       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
1756       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
1761       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
1766   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
1775       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
1787            struct netconfig *getnetconfigent(const char *netid);
1788
1789       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
1796            typedef struct netconfig Netconfig;
1797
1798            MODULE = RPC  PACKAGE = RPC
1799
1800            Netconfig *
1801            getnetconfigent(netid)
1802                 char *netid
1803
1804            MODULE = RPC  PACKAGE = NetconfigPtr  PREFIX = rpcb_
1805
1806            void
1807            rpcb_DESTROY(netconf)
1808                 Netconfig *netconf
1809               CODE:
1810                 printf("Now in NetconfigPtr::DESTROY\n");
1811                 free( netconf );
1812
1813       This example requires the following typemap entry.  Consult
1814       perlxstypemap for more information about adding new typemaps for an
1815       extension.
1816
1817            TYPEMAP
1818            Netconfig *  T_PTROBJ
1819
1820       This example will be used with the following Perl statements.
1821
1822            use RPC;
1823            $netconf = getnetconfigent("udp");
1824
1825       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
1832   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
1837       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
1841       It is therefore strongly recommended that these macros be used by all
1842       XS modules that make use of static data.
1843
1844       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
1847       Below is an example module that makes use of the macros.
1848
1849           #define PERL_NO_GET_CONTEXT
1850           #include "EXTERN.h"
1851           #include "perl.h"
1852           #include "XSUB.h"
1853
1854           /* Global Data */
1855
1856           #define MY_CXT_KEY "BlindMice::_guts" XS_VERSION
1857
1858           typedef struct {
1859               int count;
1860               char name[3][100];
1861           } my_cxt_t;
1862
1863           START_MY_CXT
1864
1865           MODULE = BlindMice           PACKAGE = BlindMice
1866
1867           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
1876           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
1892           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
1905           void
1906           CLONE(...)
1907               CODE:
1908                 MY_CXT_CLONE;
1909
1910       MY_CXT REFERENCE
1911
1912       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
1918                #define MY_CXT_KEY "MyModule::_guts" XS_VERSION
1919
1920       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
1924            Declare a typedef named "my_cxt_t" that is a structure that
1925            contains all the data that needs to be interpreter-local.
1926
1927                typedef struct {
1928                    int some_value;
1929                } my_cxt_t;
1930
1931       START_MY_CXT
1932            Always place the START_MY_CXT macro directly after the declaration
1933            of "my_cxt_t".
1934
1935       MY_CXT_INIT
1936            The MY_CXT_INIT macro initializes storage for the "my_cxt_t"
1937            struct.
1938
1939            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
1944       dMY_CXT
1945            Use the dMY_CXT macro (a declaration) in all the functions that
1946            access MY_CXT.
1947
1948       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
1952                typedef struct {
1953                    int index;
1954                } my_cxt_t;
1955
1956            then use this to access the "index" member
1957
1958                dMY_CXT;
1959                MY_CXT.index = 2;
1960
1961       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
1967                void sub1() {
1968                    dMY_CXT;
1969                    MY_CXT.index = 1;
1970                    sub2(aMY_CXT);
1971                }
1972
1973                void sub2(pMY_CXT) {
1974                    MY_CXT.index = 2;
1975                }
1976
1977            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
1982       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
1990       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
1995       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
1999   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
2007       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
2012        #define PERL_REENTRANT
2013
2014       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

EXAMPLES

2023       File "RPC.xs": Interface to some ONC+ RPC bind library functions.
2024
2025            #define PERL_NO_GET_CONTEXT
2026            #include "EXTERN.h"
2027            #include "perl.h"
2028            #include "XSUB.h"
2029
2030            /* Note: On glibc 2.13 and earlier, this needs be <rpc/rpc.h> */
2031            #include <tirpc/rpc.h>
2032
2033            typedef struct netconfig Netconfig;
2034
2035            MODULE = RPC  PACKAGE = RPC
2036
2037            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
2047            Netconfig *
2048            getnetconfigent(netid="udp")
2049                 char *netid
2050
2051            MODULE = RPC  PACKAGE = NetconfigPtr  PREFIX = rpcb_
2052
2053            void
2054            rpcb_DESTROY(netconf)
2055                 Netconfig *netconf
2056               CODE:
2057                 printf("NetconfigPtr::DESTROY\n");
2058                 free( netconf );
2059
2060       File "typemap": Custom typemap for RPC.xs. (cf. perlxstypemap)
2061
2062            TYPEMAP
2063            Netconfig *  T_PTROBJ
2064
2065       File "RPC.pm": Perl module for the RPC extension.
2066
2067            package RPC;
2068
2069            require Exporter;
2070            require DynaLoader;
2071            @ISA = qw(Exporter DynaLoader);
2072            @EXPORT = qw(rpcb_gettime getnetconfigent);
2073
2074            bootstrap RPC;
2075            1;
2076
2077       File "rpctest.pl": Perl test program for the RPC extension.
2078
2079            use RPC;
2080
2081            $netconf = getnetconfigent();
2082            $a = rpcb_gettime();
2083            print "time = $a\n";
2084            print "netconf = $netconf\n";
2085
2086            $netconf = getnetconfigent("tcp");
2087            $a = rpcb_gettime("poplar");
2088            print "time = $a\n";
2089            print "netconf = $netconf\n";
2090
2091       In Makefile.PL add -ltirpc and -I/usr/include/tirpc.
2092

CAVEATS

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
2100       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
2104       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
2110       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
2135       To summarize, here's what to expect and how to handle locales in XS
2136       code:
2137
2138       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
2144           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
2151           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
2164       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
2175           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
2184           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
2197           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
2204           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
2211           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
2218            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
2227           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
2231            asctime_r()
2232            ctime_r()
2233            Perl_langinfo()
2234
2235           The "_r" forms are automatically used, starting in Perl 5.28, if
2236           you compile your code, with
2237
2238            #define PERL_REENTRANT
2239
2240           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
2244            POSIX::localeconv()
2245            POSIX::wcstombs()
2246            POSIX::wctomb()
2247
2248           And note, that some items returned by "Localeconv" are available
2249           through "Perl_langinfo" in perlapi.
2250
2251           The others shouldn't be used in a threaded application.
2252
2253           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
2267           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
2274           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
2281            POSIX::setlocale(LC_ALL, POSIX::setlocale(LC_ALL));
2282
2283           or use the methods given in perlcall.
2284

XS VERSION

2286       This document covers features supported by "ExtUtils::ParseXS" (also
2287       known as "xsubpp") 3.13_01.
2288

AUTHOR

2290       Originally written by Dean Roehrich <roehrich@cray.com>.
2291
2292       Maintained since 1996 by The Perl Porters <perl5-porters@perl.org>.
2293
2294
2295
2296perl v5.36.0                      2022-07-22                         perlxs(3)
Impressum