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