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