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

EXAMPLES

2018       File "RPC.xs": Interface to some ONC+ RPC bind library functions.
2019
2020            #define PERL_NO_GET_CONTEXT
2021            #include "EXTERN.h"
2022            #include "perl.h"
2023            #include "XSUB.h"
2024
2025            #include <rpc/rpc.h>
2026
2027            typedef struct netconfig Netconfig;
2028
2029            MODULE = RPC  PACKAGE = RPC
2030
2031            SV *
2032            rpcb_gettime(host="localhost")
2033                 char *host
2034               PREINIT:
2035                 time_t  timep;
2036               CODE:
2037                 ST(0) = sv_newmortal();
2038                 if( rpcb_gettime( host, &timep ) )
2039                      sv_setnv( ST(0), (double)timep );
2040
2041            Netconfig *
2042            getnetconfigent(netid="udp")
2043                 char *netid
2044
2045            MODULE = RPC  PACKAGE = NetconfigPtr  PREFIX = rpcb_
2046
2047            void
2048            rpcb_DESTROY(netconf)
2049                 Netconfig *netconf
2050               CODE:
2051                 printf("NetconfigPtr::DESTROY\n");
2052                 free( netconf );
2053
2054       File "typemap": Custom typemap for RPC.xs. (cf. perlxstypemap)
2055
2056            TYPEMAP
2057            Netconfig *  T_PTROBJ
2058
2059       File "RPC.pm": Perl module for the RPC extension.
2060
2061            package RPC;
2062
2063            require Exporter;
2064            require DynaLoader;
2065            @ISA = qw(Exporter DynaLoader);
2066            @EXPORT = qw(rpcb_gettime getnetconfigent);
2067
2068            bootstrap RPC;
2069            1;
2070
2071       File "rpctest.pl": Perl test program for the RPC extension.
2072
2073            use RPC;
2074
2075            $netconf = getnetconfigent();
2076            $a = rpcb_gettime();
2077            print "time = $a\n";
2078            print "netconf = $netconf\n";
2079
2080            $netconf = getnetconfigent("tcp");
2081            $a = rpcb_gettime("poplar");
2082            print "time = $a\n";
2083            print "netconf = $netconf\n";
2084

CAVEATS

2086       XS code has full access to system calls including C library functions.
2087       It thus has the capability of interfering with things that the Perl
2088       core or other modules have set up, such as signal handlers or file
2089       handles.  It could mess with the memory, or any number of harmful
2090       things.  Don't.
2091
2092       Some modules have an event loop, waiting for user-input.  It is highly
2093       unlikely that two such modules would work adequately together in a
2094       single Perl application.
2095
2096       In general, the perl interpreter views itself as the center of the
2097       universe as far as the Perl program goes.  XS code is viewed as a help-
2098       mate, to accomplish things that perl doesn't do, or doesn't do fast
2099       enough, but always subservient to perl.  The closer XS code adheres to
2100       this model, the less likely conflicts will occur.
2101
2102       One area where there has been conflict is in regards to C locales.
2103       (See perllocale.)  perl, with one exception and unless told otherwise,
2104       sets up the underlying locale the program is running in to the locale
2105       passed into it from the environment.  This is an important difference
2106       from a generic C language program, where the underlying locale is the
2107       "C" locale unless the program changes it.  As of v5.20, this underlying
2108       locale is completely hidden from pure Perl code outside the lexical
2109       scope of "use locale" except for a couple of function calls in the
2110       POSIX module which of necessity use it.  But the underlying locale,
2111       with that one exception is exposed to XS code, affecting all C library
2112       routines whose behavior is locale-dependent.  Your XS code better not
2113       assume that the underlying locale is "C".  The exception is the
2114       "LC_NUMERIC" locale category, and the reason it is an exception is that
2115       experience has shown that it can be problematic for XS code, whereas we
2116       have not had reports of problems with the other locale categories.  And
2117       the reason for this one category being problematic is that the
2118       character used as a decimal point can vary.  Many European languages
2119       use a comma, whereas English, and hence Perl are expecting a dot
2120       (U+002E: FULL STOP).  Many modules can handle only the radix character
2121       being a dot, and so perl attempts to make it so.  Up through Perl
2122       v5.20, the attempt was merely to set "LC_NUMERIC" upon startup to the
2123       "C" locale.  Any setlocale() otherwise would change it; this caused
2124       some failures.  Therefore, starting in v5.22, perl tries to keep
2125       "LC_NUMERIC" always set to "C" for XS code.
2126
2127       To summarize, here's what to expect and how to handle locales in XS
2128       code:
2129
2130       Non-locale-aware XS code
2131           Keep in mind that even if you think your code is not locale-aware,
2132           it may call a library function that is.  Hopefully the man page for
2133           such a function will indicate that dependency, but the
2134           documentation is imperfect.
2135
2136           The current locale is exposed to XS code except possibly
2137           "LC_NUMERIC" (explained in the next paragraph).  There have not
2138           been reports of problems with the other categories.  Perl
2139           initializes things on start-up so that the current locale is the
2140           one which is indicated by the user's environment in effect at that
2141           time.  See "ENVIRONMENT" in perllocale.
2142
2143           However, up through v5.20, Perl initialized things on start-up so
2144           that "LC_NUMERIC" was set to the "C" locale.  But if any code
2145           anywhere changed it, it would stay changed.  This means that your
2146           module can't count on "LC_NUMERIC" being something in particular,
2147           and you can't expect floating point numbers (including version
2148           strings) to have dots in them.  If you don't allow for a non-dot,
2149           your code could break if anyone anywhere changed the locale.  For
2150           this reason, v5.22 changed the behavior so that Perl tries to keep
2151           "LC_NUMERIC" in the "C" locale except around the operations
2152           internally where it should be something else.  Misbehaving XS code
2153           will always be able to change the locale anyway, but the most
2154           common instance of this is checked for and handled.
2155
2156       Locale-aware XS code
2157           If the locale from the user's environment is desired, there should
2158           be no need for XS code to set the locale except for "LC_NUMERIC",
2159           as perl has already set the others up.  XS code should avoid
2160           changing the locale, as it can adversely affect other, unrelated,
2161           code and may not be thread-safe.  To minimize problems, the macros
2162           "STORE_LC_NUMERIC_SET_TO_NEEDED" in perlapi,
2163           "STORE_LC_NUMERIC_FORCE_TO_UNDERLYING" in perlapi, and
2164           "RESTORE_LC_NUMERIC" in perlapi should be used to affect any needed
2165           change.
2166
2167           But, starting with Perl v5.28, locales are thread-safe on platforms
2168           that support this functionality.  Windows has this starting with
2169           Visual Studio 2005.  Many other modern platforms support the
2170           thread-safe POSIX 2008 functions.  The C "#define"
2171           "USE_THREAD_SAFE_LOCALE" will be defined iff this build is using
2172           these.  From Perl-space, the read-only variable "${SAFE_LOCALES}"
2173           is 1 if either the build is not threaded, or if
2174           "USE_THREAD_SAFE_LOCALE" is defined; otherwise it is 0.
2175
2176           The way this works under-the-hood is that every thread has a choice
2177           of using a locale specific to it (this is the Windows and POSIX
2178           2008 functionality), or the global locale that is accessible to all
2179           threads (this is the functionality that has always been there).
2180           The implementations for Windows and POSIX are completely different.
2181           On Windows, the runtime can be set up so that the standard
2182           setlocale(3) function either only knows about the global locale or
2183           the locale for this thread.  On POSIX, "setlocale" always deals
2184           with the global locale, and other functions have been created to
2185           handle per-thread locales.  Perl makes this transparent to perl-
2186           space code.  It continues to use "POSIX::setlocale()", and the
2187           interpreter translates that into the per-thread functions.
2188
2189           All other locale-senstive functions automatically use the per-
2190           thread locale, if that is turned on, and failing that, the global
2191           locale.  Thus calls to "setlocale" are ineffective on POSIX systems
2192           for the current thread if that thread is using a per-thread locale.
2193           If perl is compiled for single-thread operation, it does not use
2194           the per-thread functions, so "setlocale" does work as expected.
2195
2196           If you have loaded the "POSIX" module you can use the methods given
2197           in perlcall to call "POSIX::setlocale" to safely change or query
2198           the locale (on systems where it is safe to do so), or you can use
2199           the new 5.28 function "Perl_setlocale" in perlapi instead, which is
2200           a drop-in replacement for the system setlocale(3), and handles
2201           single-threaded and multi-threaded applications transparently.
2202
2203           There are some locale-related library calls that still aren't
2204           thread-safe because they return data in a buffer global to all
2205           threads.  In the past, these didn't matter as locales weren't
2206           thread-safe at all.  But now you have to be aware of them in case
2207           your module is called in a multi-threaded application.  The known
2208           ones are
2209
2210            asctime()
2211            ctime()
2212            gcvt() [POSIX.1-2001 only (function removed in POSIX.1-2008)]
2213            getdate()
2214            wcrtomb() if its final argument is NULL
2215            wcsrtombs() if its final argument is NULL
2216            wcstombs()
2217            wctomb()
2218
2219           Some of these shouldn't really be called in a Perl application, and
2220           for others there are thread-safe versions of these already
2221           implemented:
2222
2223            asctime_r()
2224            ctime_r()
2225            Perl_langinfo()
2226
2227           The "_r" forms are automatically used, starting in Perl 5.28, if
2228           you compile your code, with
2229
2230            #define PERL_REENTRANT
2231
2232           See also "Perl_langinfo" in perlapi.  You can use the methods given
2233           in perlcall, to get the best available locale-safe versions of
2234           these
2235
2236            POSIX::localeconv()
2237            POSIX::wcstombs()
2238            POSIX::wctomb()
2239
2240           And note, that some items returned by "Localeconv" are available
2241           through "Perl_langinfo" in perlapi.
2242
2243           The others shouldn't be used in a threaded application.
2244
2245           Some modules may call a non-perl library that is locale-aware.
2246           This is fine as long as it doesn't try to query or change the
2247           locale using the system "setlocale".  But if these do call the
2248           system "setlocale", those calls may be ineffective.  Instead,
2249           "Perl_setlocale" works in all circumstances.  Plain setlocale is
2250           ineffective on multi-threaded POSIX 2008 systems.  It operates only
2251           on the global locale, whereas each thread has its own locale,
2252           paying no attention to the global one.  Since converting these non-
2253           Perl libraries to "Perl_setlocale" is out of the question, there is
2254           a new function in v5.28 "switch_to_global_locale" that will switch
2255           the thread it is called from so that any system "setlocale" calls
2256           will have their desired effect.  The function "sync_locale" must be
2257           called before returning to perl.
2258
2259           This thread can change the locale all it wants and it won't affect
2260           any other thread, except any that also have been switched to the
2261           global locale.  This means that a multi-threaded application can
2262           have a single thread using an alien library without a problem; but
2263           no more than a single thread can be so-occupied.  Bad results
2264           likely will happen.
2265
2266           In perls without multi-thread locale support, some alien libraries,
2267           such as "Gtk" change locales.  This can cause problems for the Perl
2268           core and other modules.  For these, before control is returned to
2269           perl, starting in v5.20.1, calling the function sync_locale() from
2270           XS should be sufficient to avoid most of these problems.  Prior to
2271           this, you need a pure Perl statement that does this:
2272
2273            POSIX::setlocale(LC_ALL, POSIX::setlocale(LC_ALL));
2274
2275           or use the methods given in perlcall.
2276

XS VERSION

2278       This document covers features supported by "ExtUtils::ParseXS" (also
2279       known as "xsubpp") 3.13_01.
2280

AUTHOR

2282       Originally written by Dean Roehrich <roehrich@cray.com>.
2283
2284       Maintained since 1996 by The Perl Porters <perlbug@perl.org>.
2285
2286
2287
2288perl v5.30.2                      2020-03-27                         PERLXS(1)
Impressum