This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Latch LC_NUMERIC during critical sections
[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:, or OUTPUT: blocks which are present in the XSUB.  The code
1202 specified for the cleanup block will be added as the last statements in
1203 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 disabled 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 Note that B<xsubpp> will nag you if you don't explicitly enable or disable
1264 prototypes, with:
1265
1266     Please specify prototyping behavior for Foo.xs (see perlxs manual)
1267
1268 To enable prototypes:
1269
1270     PROTOTYPES: ENABLE
1271
1272 To disable prototypes:
1273
1274     PROTOTYPES: DISABLE
1275
1276 =head2 The PROTOTYPE: Keyword
1277
1278 This keyword is similar to the PROTOTYPES: keyword above but can be used to
1279 force B<xsubpp> to use a specific prototype for the XSUB.  This keyword
1280 overrides all other prototype options and keywords but affects only the
1281 current XSUB.  Consult L<perlsub/Prototypes> for information about Perl
1282 prototypes.
1283
1284     bool_t
1285     rpcb_gettime(timep, ...)
1286           time_t timep = NO_INIT
1287         PROTOTYPE: $;$
1288         PREINIT:
1289           char *host = "localhost";
1290         CODE:
1291                   if( items > 1 )
1292                        host = (char *)SvPV_nolen(ST(1));
1293                   RETVAL = rpcb_gettime( host, &timep );
1294         OUTPUT:
1295           timep
1296           RETVAL
1297
1298 If the prototypes are enabled, you can disable it locally for a given
1299 XSUB as in the following example:
1300
1301     void
1302     rpcb_gettime_noproto()
1303         PROTOTYPE: DISABLE
1304     ...
1305
1306 =head2 The ALIAS: Keyword
1307
1308 The ALIAS: keyword allows an XSUB to have two or more unique Perl names
1309 and to know which of those names was used when it was invoked.  The Perl
1310 names may be fully-qualified with package names.  Each alias is given an
1311 index.  The compiler will setup a variable called C<ix> which contain the
1312 index of the alias which was used.  When the XSUB is called with its
1313 declared name C<ix> will be 0.
1314
1315 The following example will create aliases C<FOO::gettime()> and
1316 C<BAR::getit()> for this function.
1317
1318     bool_t
1319     rpcb_gettime(host,timep)
1320           char *host
1321           time_t &timep
1322         ALIAS:
1323             FOO::gettime = 1
1324             BAR::getit = 2
1325         INIT:
1326           printf("# ix = %d\n", ix );
1327         OUTPUT:
1328           timep
1329
1330 =head2 The OVERLOAD: Keyword
1331
1332 Instead of writing an overloaded interface using pure Perl, you
1333 can also use the OVERLOAD keyword to define additional Perl names
1334 for your functions (like the ALIAS: keyword above).  However, the
1335 overloaded functions must be defined in such a way as to accept the number
1336 of parameters supplied by perl's overload system.  For most overload
1337 methods, it will be three parameters; for the C<nomethod> function it will
1338 be four.  However, the bitwise operators C<&>, C<|>, C<^>, and C<~> may be
1339 called with three I<or> five arguments (see L<overload>).
1340
1341 If any
1342 function has the OVERLOAD: keyword, several additional lines
1343 will be defined in the c file generated by xsubpp in order to
1344 register with the overload magic.
1345
1346 Since blessed objects are actually stored as RV's, it is useful
1347 to use the typemap features to preprocess parameters and extract
1348 the actual SV stored within the blessed RV.  See the sample for
1349 T_PTROBJ_SPECIAL below.
1350
1351 To use the OVERLOAD: keyword, create an XS function which takes
1352 three input parameters (or use the C-style '...' definition) like
1353 this:
1354
1355     SV *
1356     cmp (lobj, robj, swap)
1357     My_Module_obj    lobj
1358     My_Module_obj    robj
1359     IV               swap
1360     OVERLOAD: cmp <=>
1361     { /* function defined here */}
1362
1363 In this case, the function will overload both of the three way
1364 comparison operators.  For all overload operations using non-alpha
1365 characters, you must type the parameter without quoting, separating
1366 multiple overloads with whitespace.  Note that "" (the stringify
1367 overload) should be entered as \"\" (i.e. escaped).
1368
1369 Since, as mentioned above, bitwise operators may take extra arguments, you
1370 may want to use something like C<(lobj, robj, swap, ...)> (with
1371 literal C<...>) as your parameter list.
1372
1373 =head2 The FALLBACK: Keyword
1374
1375 In addition to the OVERLOAD keyword, if you need to control how
1376 Perl autogenerates missing overloaded operators, you can set the
1377 FALLBACK keyword in the module header section, like this:
1378
1379     MODULE = RPC  PACKAGE = RPC
1380
1381     FALLBACK: TRUE
1382     ...
1383
1384 where FALLBACK can take any of the three values TRUE, FALSE, or
1385 UNDEF.  If you do not set any FALLBACK value when using OVERLOAD,
1386 it defaults to UNDEF.  FALLBACK is not used except when one or
1387 more functions using OVERLOAD have been defined.  Please see
1388 L<overload/fallback> for more details.
1389
1390 =head2 The INTERFACE: Keyword
1391
1392 This keyword declares the current XSUB as a keeper of the given
1393 calling signature.  If some text follows this keyword, it is
1394 considered as a list of functions which have this signature, and
1395 should be attached to the current XSUB.
1396
1397 For example, if you have 4 C functions multiply(), divide(), add(),
1398 subtract() all having the signature:
1399
1400     symbolic f(symbolic, symbolic);
1401
1402 you can make them all to use the same XSUB using this:
1403
1404     symbolic
1405     interface_s_ss(arg1, arg2)
1406         symbolic        arg1
1407         symbolic        arg2
1408     INTERFACE:
1409         multiply divide
1410         add subtract
1411
1412 (This is the complete XSUB code for 4 Perl functions!)  Four generated
1413 Perl function share names with corresponding C functions.
1414
1415 The advantage of this approach comparing to ALIAS: keyword is that there
1416 is no need to code a switch statement, each Perl function (which shares
1417 the same XSUB) knows which C function it should call.  Additionally, one
1418 can attach an extra function remainder() at runtime by using
1419
1420     CV *mycv = newXSproto("Symbolic::remainder",
1421                           XS_Symbolic_interface_s_ss, __FILE__, "$$");
1422     XSINTERFACE_FUNC_SET(mycv, remainder);
1423
1424 say, from another XSUB.  (This example supposes that there was no
1425 INTERFACE_MACRO: section, otherwise one needs to use something else instead of
1426 C<XSINTERFACE_FUNC_SET>, see the next section.)
1427
1428 =head2 The INTERFACE_MACRO: Keyword
1429
1430 This keyword allows one to define an INTERFACE using a different way
1431 to extract a function pointer from an XSUB.  The text which follows
1432 this keyword should give the name of macros which would extract/set a
1433 function pointer.  The extractor macro is given return type, C<CV*>,
1434 and C<XSANY.any_dptr> for this C<CV*>.  The setter macro is given cv,
1435 and the function pointer.
1436
1437 The default value is C<XSINTERFACE_FUNC> and C<XSINTERFACE_FUNC_SET>.
1438 An INTERFACE keyword with an empty list of functions can be omitted if
1439 INTERFACE_MACRO keyword is used.
1440
1441 Suppose that in the previous example functions pointers for
1442 multiply(), divide(), add(), subtract() are kept in a global C array
1443 C<fp[]> with offsets being C<multiply_off>, C<divide_off>, C<add_off>,
1444 C<subtract_off>.  Then one can use
1445
1446     #define XSINTERFACE_FUNC_BYOFFSET(ret,cv,f) \
1447         ((XSINTERFACE_CVT_ANON(ret))fp[CvXSUBANY(cv).any_i32])
1448     #define XSINTERFACE_FUNC_BYOFFSET_set(cv,f) \
1449         CvXSUBANY(cv).any_i32 = CAT2( f, _off )
1450
1451 in C section,
1452
1453     symbolic
1454     interface_s_ss(arg1, arg2)
1455         symbolic        arg1
1456         symbolic        arg2
1457       INTERFACE_MACRO:
1458         XSINTERFACE_FUNC_BYOFFSET
1459         XSINTERFACE_FUNC_BYOFFSET_set
1460       INTERFACE:
1461         multiply divide
1462         add subtract
1463
1464 in XSUB section.
1465
1466 =head2 The INCLUDE: Keyword
1467
1468 This keyword can be used to pull other files into the XS module.  The other
1469 files may have XS code.  INCLUDE: can also be used to run a command to
1470 generate the XS code to be pulled into the module.
1471
1472 The file F<Rpcb1.xsh> contains our C<rpcb_gettime()> function:
1473
1474     bool_t
1475     rpcb_gettime(host,timep)
1476           char *host
1477           time_t &timep
1478         OUTPUT:
1479           timep
1480
1481 The XS module can use INCLUDE: to pull that file into it.
1482
1483     INCLUDE: Rpcb1.xsh
1484
1485 If the parameters to the INCLUDE: keyword are followed by a pipe (C<|>) then
1486 the compiler will interpret the parameters as a command. This feature is
1487 mildly deprecated in favour of the C<INCLUDE_COMMAND:> directive, as documented
1488 below.
1489
1490     INCLUDE: cat Rpcb1.xsh |
1491
1492 Do not use this to run perl: C<INCLUDE: perl |> will run the perl that
1493 happens to be the first in your path and not necessarily the same perl that is
1494 used to run C<xsubpp>. See L<"The INCLUDE_COMMAND: Keyword">.
1495
1496 =head2 The INCLUDE_COMMAND: Keyword
1497
1498 Runs the supplied command and includes its output into the current XS
1499 document. C<INCLUDE_COMMAND> assigns special meaning to the C<$^X> token
1500 in that it runs the same perl interpreter that is running C<xsubpp>:
1501
1502     INCLUDE_COMMAND: cat Rpcb1.xsh
1503
1504     INCLUDE_COMMAND: $^X -e ...
1505
1506 =head2 The CASE: Keyword
1507
1508 The CASE: keyword allows an XSUB to have multiple distinct parts with each
1509 part acting as a virtual XSUB.  CASE: is greedy and if it is used then all
1510 other XS keywords must be contained within a CASE:.  This means nothing may
1511 precede the first CASE: in the XSUB and anything following the last CASE: is
1512 included in that case.
1513
1514 A CASE: might switch via a parameter of the XSUB, via the C<ix> ALIAS:
1515 variable (see L<"The ALIAS: Keyword">), or maybe via the C<items> variable
1516 (see L<"Variable-length Parameter Lists">).  The last CASE: becomes the
1517 B<default> case if it is not associated with a conditional.  The following
1518 example shows CASE switched via C<ix> with a function C<rpcb_gettime()>
1519 having an alias C<x_gettime()>.  When the function is called as
1520 C<rpcb_gettime()> its parameters are the usual C<(char *host, time_t *timep)>,
1521 but when the function is called as C<x_gettime()> its parameters are
1522 reversed, C<(time_t *timep, char *host)>.
1523
1524     long
1525     rpcb_gettime(a,b)
1526       CASE: ix == 1
1527         ALIAS:
1528           x_gettime = 1
1529         INPUT:
1530           # 'a' is timep, 'b' is host
1531           char *b
1532           time_t a = NO_INIT
1533         CODE:
1534                RETVAL = rpcb_gettime( b, &a );
1535         OUTPUT:
1536           a
1537           RETVAL
1538       CASE:
1539           # 'a' is host, 'b' is timep
1540           char *a
1541           time_t &b = NO_INIT
1542         OUTPUT:
1543           b
1544           RETVAL
1545
1546 That function can be called with either of the following statements.  Note
1547 the different argument lists.
1548
1549         $status = rpcb_gettime( $host, $timep );
1550
1551         $status = x_gettime( $timep, $host );
1552
1553 =head2 The EXPORT_XSUB_SYMBOLS: Keyword
1554
1555 The EXPORT_XSUB_SYMBOLS: keyword is likely something you will never need.
1556 In perl versions earlier than 5.16.0, this keyword does nothing. Starting
1557 with 5.16, XSUB symbols are no longer exported by default. That is, they
1558 are C<static> functions. If you include
1559
1560   EXPORT_XSUB_SYMBOLS: ENABLE
1561
1562 in your XS code, the XSUBs following this line will not be declared C<static>.
1563 You can later disable this with
1564
1565   EXPORT_XSUB_SYMBOLS: DISABLE
1566
1567 which, again, is the default that you should probably never change.
1568 You cannot use this keyword on versions of perl before 5.16 to make
1569 XSUBs C<static>.
1570
1571 =head2 The & Unary Operator
1572
1573 The C<&> unary operator in the INPUT: section is used to tell B<xsubpp>
1574 that it should convert a Perl value to/from C using the C type to the left
1575 of C<&>, but provide a pointer to this value when the C function is called.
1576
1577 This is useful to avoid a CODE: block for a C function which takes a parameter
1578 by reference.  Typically, the parameter should be not a pointer type (an
1579 C<int> or C<long> but not an C<int*> or C<long*>).
1580
1581 The following XSUB will generate incorrect C code.  The B<xsubpp> compiler will
1582 turn this into code which calls C<rpcb_gettime()> with parameters C<(char
1583 *host, time_t timep)>, but the real C<rpcb_gettime()> wants the C<timep>
1584 parameter to be of type C<time_t*> rather than C<time_t>.
1585
1586     bool_t
1587     rpcb_gettime(host,timep)
1588           char *host
1589           time_t timep
1590         OUTPUT:
1591           timep
1592
1593 That problem is corrected by using the C<&> operator.  The B<xsubpp> compiler
1594 will now turn this into code which calls C<rpcb_gettime()> correctly with
1595 parameters C<(char *host, time_t *timep)>.  It does this by carrying the
1596 C<&> through, so the function call looks like C<rpcb_gettime(host, &timep)>.
1597
1598     bool_t
1599     rpcb_gettime(host,timep)
1600           char *host
1601           time_t &timep
1602         OUTPUT:
1603           timep
1604
1605 =head2 Inserting POD, Comments and C Preprocessor Directives
1606
1607 C preprocessor directives are allowed within BOOT:, PREINIT: INIT:, CODE:,
1608 PPCODE:, POSTCALL:, and CLEANUP: blocks, as well as outside the functions.
1609 Comments are allowed anywhere after the MODULE keyword.  The compiler will
1610 pass the preprocessor directives through untouched and will remove the
1611 commented lines. POD documentation is allowed at any point, both in the
1612 C and XS language sections. POD must be terminated with a C<=cut> command;
1613 C<xsubpp> will exit with an error if it does not. It is very unlikely that
1614 human generated C code will be mistaken for POD, as most indenting styles
1615 result in whitespace in front of any line starting with C<=>. Machine
1616 generated XS files may fall into this trap unless care is taken to
1617 ensure that a space breaks the sequence "\n=".
1618
1619 Comments can be added to XSUBs by placing a C<#> as the first
1620 non-whitespace of a line.  Care should be taken to avoid making the
1621 comment look like a C preprocessor directive, lest it be interpreted as
1622 such.  The simplest way to prevent this is to put whitespace in front of
1623 the C<#>.
1624
1625 If you use preprocessor directives to choose one of two
1626 versions of a function, use
1627
1628     #if ... version1
1629     #else /* ... version2  */
1630     #endif
1631
1632 and not
1633
1634     #if ... version1
1635     #endif
1636     #if ... version2
1637     #endif
1638
1639 because otherwise B<xsubpp> will believe that you made a duplicate
1640 definition of the function.  Also, put a blank line before the
1641 #else/#endif so it will not be seen as part of the function body.
1642
1643 =head2 Using XS With C++
1644
1645 If an XSUB name contains C<::>, it is considered to be a C++ method.
1646 The generated Perl function will assume that
1647 its first argument is an object pointer.  The object pointer
1648 will be stored in a variable called THIS.  The object should
1649 have been created by C++ with the new() function and should
1650 be blessed by Perl with the sv_setref_pv() macro.  The
1651 blessing of the object by Perl can be handled by a typemap.  An example
1652 typemap is shown at the end of this section.
1653
1654 If the return type of the XSUB includes C<static>, the method is considered
1655 to be a static method.  It will call the C++
1656 function using the class::method() syntax.  If the method is not static
1657 the function will be called using the THIS-E<gt>method() syntax.
1658
1659 The next examples will use the following C++ class.
1660
1661      class color {
1662           public:
1663           color();
1664           ~color();
1665           int blue();
1666           void set_blue( int );
1667
1668           private:
1669           int c_blue;
1670      };
1671
1672 The XSUBs for the blue() and set_blue() methods are defined with the class
1673 name but the parameter for the object (THIS, or "self") is implicit and is
1674 not listed.
1675
1676      int
1677      color::blue()
1678
1679      void
1680      color::set_blue( val )
1681           int val
1682
1683 Both Perl functions will expect an object as the first parameter.  In the
1684 generated C++ code the object is called C<THIS>, and the method call will
1685 be performed on this object.  So in the C++ code the blue() and set_blue()
1686 methods will be called as this:
1687
1688      RETVAL = THIS->blue();
1689
1690      THIS->set_blue( val );
1691
1692 You could also write a single get/set method using an optional argument:
1693
1694      int
1695      color::blue( val = NO_INIT )
1696          int val
1697          PROTOTYPE $;$
1698          CODE:
1699              if (items > 1)
1700                  THIS->set_blue( val );
1701              RETVAL = THIS->blue();
1702          OUTPUT:
1703              RETVAL
1704
1705 If the function's name is B<DESTROY> then the C++ C<delete> function will be
1706 called and C<THIS> will be given as its parameter.  The generated C++ code for
1707
1708      void
1709      color::DESTROY()
1710
1711 will look like this:
1712
1713      color *THIS = ...;  // Initialized as in typemap
1714
1715      delete THIS;
1716
1717 If the function's name is B<new> then the C++ C<new> function will be called
1718 to create a dynamic C++ object.  The XSUB will expect the class name, which
1719 will be kept in a variable called C<CLASS>, to be given as the first
1720 argument.
1721
1722      color *
1723      color::new()
1724
1725 The generated C++ code will call C<new>.
1726
1727      RETVAL = new color();
1728
1729 The following is an example of a typemap that could be used for this C++
1730 example.
1731
1732     TYPEMAP
1733     color *  O_OBJECT
1734
1735     OUTPUT
1736     # The Perl object is blessed into 'CLASS', which should be a
1737     # char* having the name of the package for the blessing.
1738     O_OBJECT
1739         sv_setref_pv( $arg, CLASS, (void*)$var );
1740
1741     INPUT
1742     O_OBJECT
1743         if( sv_isobject($arg) && (SvTYPE(SvRV($arg)) == SVt_PVMG) )
1744             $var = ($type)SvIV((SV*)SvRV( $arg ));
1745         else{
1746             warn("${Package}::$func_name() -- " .
1747                 "$var is not a blessed SV reference");
1748             XSRETURN_UNDEF;
1749         }
1750
1751 =head2 Interface Strategy
1752
1753 When designing an interface between Perl and a C library a straight
1754 translation from C to XS (such as created by C<h2xs -x>) is often sufficient.
1755 However, sometimes the interface will look
1756 very C-like and occasionally nonintuitive, especially when the C function
1757 modifies one of its parameters, or returns failure inband (as in "negative
1758 return values mean failure").  In cases where the programmer wishes to
1759 create a more Perl-like interface the following strategy may help to
1760 identify the more critical parts of the interface.
1761
1762 Identify the C functions with input/output or output parameters.  The XSUBs for
1763 these functions may be able to return lists to Perl.
1764
1765 Identify the C functions which use some inband info as an indication
1766 of failure.  They may be
1767 candidates to return undef or an empty list in case of failure.  If the
1768 failure may be detected without a call to the C function, you may want to use
1769 an INIT: section to report the failure.  For failures detectable after the C
1770 function returns one may want to use a POSTCALL: section to process the
1771 failure.  In more complicated cases use CODE: or PPCODE: sections.
1772
1773 If many functions use the same failure indication based on the return value,
1774 you may want to create a special typedef to handle this situation.  Put
1775
1776   typedef int negative_is_failure;
1777
1778 near the beginning of XS file, and create an OUTPUT typemap entry
1779 for C<negative_is_failure> which converts negative values to C<undef>, or
1780 maybe croak()s.  After this the return value of type C<negative_is_failure>
1781 will create more Perl-like interface.
1782
1783 Identify which values are used by only the C and XSUB functions
1784 themselves, say, when a parameter to a function should be a contents of a
1785 global variable.  If Perl does not need to access the contents of the value
1786 then it may not be necessary to provide a translation for that value
1787 from C to Perl.
1788
1789 Identify the pointers in the C function parameter lists and return
1790 values.  Some pointers may be used to implement input/output or
1791 output parameters, they can be handled in XS with the C<&> unary operator,
1792 and, possibly, using the NO_INIT keyword.
1793 Some others will require handling of types like C<int *>, and one needs
1794 to decide what a useful Perl translation will do in such a case.  When
1795 the semantic is clear, it is advisable to put the translation into a typemap
1796 file.
1797
1798 Identify the structures used by the C functions.  In many
1799 cases it may be helpful to use the T_PTROBJ typemap for
1800 these structures so they can be manipulated by Perl as
1801 blessed objects.  (This is handled automatically by C<h2xs -x>.)
1802
1803 If the same C type is used in several different contexts which require
1804 different translations, C<typedef> several new types mapped to this C type,
1805 and create separate F<typemap> entries for these new types.  Use these
1806 types in declarations of return type and parameters to XSUBs.
1807
1808 =head2 Perl Objects And C Structures
1809
1810 When dealing with C structures one should select either
1811 B<T_PTROBJ> or B<T_PTRREF> for the XS type.  Both types are
1812 designed to handle pointers to complex objects.  The
1813 T_PTRREF type will allow the Perl object to be unblessed
1814 while the T_PTROBJ type requires that the object be blessed.
1815 By using T_PTROBJ one can achieve a form of type-checking
1816 because the XSUB will attempt to verify that the Perl object
1817 is of the expected type.
1818
1819 The following XS code shows the getnetconfigent() function which is used
1820 with ONC+ TIRPC.  The getnetconfigent() function will return a pointer to a
1821 C structure and has the C prototype shown below.  The example will
1822 demonstrate how the C pointer will become a Perl reference.  Perl will
1823 consider this reference to be a pointer to a blessed object and will
1824 attempt to call a destructor for the object.  A destructor will be
1825 provided in the XS source to free the memory used by getnetconfigent().
1826 Destructors in XS can be created by specifying an XSUB function whose name
1827 ends with the word B<DESTROY>.  XS destructors can be used to free memory
1828 which may have been malloc'd by another XSUB.
1829
1830      struct netconfig *getnetconfigent(const char *netid);
1831
1832 A C<typedef> will be created for C<struct netconfig>.  The Perl
1833 object will be blessed in a class matching the name of the C
1834 type, with the tag C<Ptr> appended, and the name should not
1835 have embedded spaces if it will be a Perl package name.  The
1836 destructor will be placed in a class corresponding to the
1837 class of the object and the PREFIX keyword will be used to
1838 trim the name to the word DESTROY as Perl will expect.
1839
1840      typedef struct netconfig Netconfig;
1841
1842      MODULE = RPC  PACKAGE = RPC
1843
1844      Netconfig *
1845      getnetconfigent(netid)
1846           char *netid
1847
1848      MODULE = RPC  PACKAGE = NetconfigPtr  PREFIX = rpcb_
1849
1850      void
1851      rpcb_DESTROY(netconf)
1852           Netconfig *netconf
1853         CODE:
1854           printf("Now in NetconfigPtr::DESTROY\n");
1855           free( netconf );
1856
1857 This example requires the following typemap entry.  Consult
1858 L<perlxstypemap> for more information about adding new typemaps
1859 for an extension.
1860
1861      TYPEMAP
1862      Netconfig *  T_PTROBJ
1863
1864 This example will be used with the following Perl statements.
1865
1866      use RPC;
1867      $netconf = getnetconfigent("udp");
1868
1869 When Perl destroys the object referenced by $netconf it will send the
1870 object to the supplied XSUB DESTROY function.  Perl cannot determine, and
1871 does not care, that this object is a C struct and not a Perl object.  In
1872 this sense, there is no difference between the object created by the
1873 getnetconfigent() XSUB and an object created by a normal Perl subroutine.
1874
1875 =head2 Safely Storing Static Data in XS
1876
1877 Starting with Perl 5.8, a macro framework has been defined to allow
1878 static data to be safely stored in XS modules that will be accessed from
1879 a multi-threaded Perl.
1880
1881 Although primarily designed for use with multi-threaded Perl, the macros
1882 have been designed so that they will work with non-threaded Perl as well.
1883
1884 It is therefore strongly recommended that these macros be used by all
1885 XS modules that make use of static data.
1886
1887 The easiest way to get a template set of macros to use is by specifying
1888 the C<-g> (C<--global>) option with h2xs (see L<h2xs>).
1889
1890 Below is an example module that makes use of the macros.
1891
1892     #define PERL_NO_GET_CONTEXT
1893     #include "EXTERN.h"
1894     #include "perl.h"
1895     #include "XSUB.h"
1896
1897     /* Global Data */
1898
1899     #define MY_CXT_KEY "BlindMice::_guts" XS_VERSION
1900
1901     typedef struct {
1902         int count;
1903         char name[3][100];
1904     } my_cxt_t;
1905
1906     START_MY_CXT
1907
1908     MODULE = BlindMice           PACKAGE = BlindMice
1909
1910     BOOT:
1911     {
1912         MY_CXT_INIT;
1913         MY_CXT.count = 0;
1914         strcpy(MY_CXT.name[0], "None");
1915         strcpy(MY_CXT.name[1], "None");
1916         strcpy(MY_CXT.name[2], "None");
1917     }
1918
1919     int
1920     newMouse(char * name)
1921         PREINIT:
1922           dMY_CXT;
1923         CODE:
1924           if (MY_CXT.count >= 3) {
1925               warn("Already have 3 blind mice");
1926               RETVAL = 0;
1927           }
1928           else {
1929               RETVAL = ++ MY_CXT.count;
1930               strcpy(MY_CXT.name[MY_CXT.count - 1], name);
1931           }
1932         OUTPUT:
1933           RETVAL
1934
1935     char *
1936     get_mouse_name(index)
1937           int index
1938         PREINIT:
1939           dMY_CXT;
1940         CODE:
1941           if (index > MY_CXT.count)
1942             croak("There are only 3 blind mice.");
1943           else
1944             RETVAL = MY_CXT.name[index - 1];
1945         OUTPUT:
1946           RETVAL
1947
1948     void
1949     CLONE(...)
1950         CODE:
1951           MY_CXT_CLONE;
1952
1953 =head3 MY_CXT REFERENCE
1954
1955 =over 5
1956
1957 =item MY_CXT_KEY
1958
1959 This macro is used to define a unique key to refer to the static data
1960 for an XS module. The suggested naming scheme, as used by h2xs, is to
1961 use a string that consists of the module name, the string "::_guts"
1962 and the module version number.
1963
1964     #define MY_CXT_KEY "MyModule::_guts" XS_VERSION
1965
1966 =item typedef my_cxt_t
1967
1968 This struct typedef I<must> always be called C<my_cxt_t>. The other
1969 C<CXT*> macros assume the existence of the C<my_cxt_t> typedef name.
1970
1971 Declare a typedef named C<my_cxt_t> that is a structure that contains
1972 all the data that needs to be interpreter-local.
1973
1974     typedef struct {
1975         int some_value;
1976     } my_cxt_t;
1977
1978 =item START_MY_CXT
1979
1980 Always place the START_MY_CXT macro directly after the declaration
1981 of C<my_cxt_t>.
1982
1983 =item MY_CXT_INIT
1984
1985 The MY_CXT_INIT macro initializes storage for the C<my_cxt_t> struct.
1986
1987 It I<must> be called exactly once, typically in a BOOT: section. If you
1988 are maintaining multiple interpreters, it should be called once in each
1989 interpreter instance, except for interpreters cloned from existing ones.
1990 (But see L</MY_CXT_CLONE> below.)
1991
1992 =item dMY_CXT
1993
1994 Use the dMY_CXT macro (a declaration) in all the functions that access
1995 MY_CXT.
1996
1997 =item MY_CXT
1998
1999 Use the MY_CXT macro to access members of the C<my_cxt_t> struct. For
2000 example, if C<my_cxt_t> is
2001
2002     typedef struct {
2003         int index;
2004     } my_cxt_t;
2005
2006 then use this to access the C<index> member
2007
2008     dMY_CXT;
2009     MY_CXT.index = 2;
2010
2011 =item aMY_CXT/pMY_CXT
2012
2013 C<dMY_CXT> may be quite expensive to calculate, and to avoid the overhead
2014 of invoking it in each function it is possible to pass the declaration
2015 onto other functions using the C<aMY_CXT>/C<pMY_CXT> macros, eg
2016
2017     void sub1() {
2018         dMY_CXT;
2019         MY_CXT.index = 1;
2020         sub2(aMY_CXT);
2021     }
2022
2023     void sub2(pMY_CXT) {
2024         MY_CXT.index = 2;
2025     }
2026
2027 Analogously to C<pTHX>, there are equivalent forms for when the macro is the
2028 first or last in multiple arguments, where an underscore represents a
2029 comma, i.e.  C<_aMY_CXT>, C<aMY_CXT_>, C<_pMY_CXT> and C<pMY_CXT_>.
2030
2031 =item MY_CXT_CLONE
2032
2033 By default, when a new interpreter is created as a copy of an existing one
2034 (eg via C<< threads->create() >>), both interpreters share the same physical
2035 my_cxt_t structure. Calling C<MY_CXT_CLONE> (typically via the package's
2036 C<CLONE()> function), causes a byte-for-byte copy of the structure to be
2037 taken, and any future dMY_CXT will cause the copy to be accessed instead.
2038
2039 =item MY_CXT_INIT_INTERP(my_perl)
2040
2041 =item dMY_CXT_INTERP(my_perl)
2042
2043 These are versions of the macros which take an explicit interpreter as an
2044 argument.
2045
2046 =back
2047
2048 Note that these macros will only work together within the I<same> source
2049 file; that is, a dMY_CTX in one source file will access a different structure
2050 than a dMY_CTX in another source file.
2051
2052 =head2 Thread-aware system interfaces
2053
2054 Starting from Perl 5.8, in C/C++ level Perl knows how to wrap
2055 system/library interfaces that have thread-aware versions
2056 (e.g. getpwent_r()) into frontend macros (e.g. getpwent()) that
2057 correctly handle the multithreaded interaction with the Perl
2058 interpreter.  This will happen transparently, the only thing
2059 you need to do is to instantiate a Perl interpreter.
2060
2061 This wrapping happens always when compiling Perl core source
2062 (PERL_CORE is defined) or the Perl core extensions (PERL_EXT is
2063 defined).  When compiling XS code outside of the Perl core, the wrapping
2064 does not take place before Perl 5.28.  Starting in that release you can
2065
2066  #define PERL_REENTRANT
2067
2068 in your code to enable the wrapping.  It is advisable to do so if you
2069 are using such functions, as intermixing the C<_r>-forms (as Perl compiled
2070 for multithreaded operation will do) and the C<_r>-less forms is neither
2071 well-defined (inconsistent results, data corruption, or even crashes
2072 become more likely), nor is it very portable.  Unfortunately, not all
2073 systems have all the C<_r> forms, but using this C<#define> gives you
2074 whatever protection that Perl is aware is available on each system.
2075
2076 =head1 EXAMPLES
2077
2078 File C<RPC.xs>: Interface to some ONC+ RPC bind library functions.
2079
2080      #define PERL_NO_GET_CONTEXT
2081      #include "EXTERN.h"
2082      #include "perl.h"
2083      #include "XSUB.h"
2084
2085      #include <rpc/rpc.h>
2086
2087      typedef struct netconfig Netconfig;
2088
2089      MODULE = RPC  PACKAGE = RPC
2090
2091      SV *
2092      rpcb_gettime(host="localhost")
2093           char *host
2094         PREINIT:
2095           time_t  timep;
2096         CODE:
2097           ST(0) = sv_newmortal();
2098           if( rpcb_gettime( host, &timep ) )
2099                sv_setnv( ST(0), (double)timep );
2100
2101      Netconfig *
2102      getnetconfigent(netid="udp")
2103           char *netid
2104
2105      MODULE = RPC  PACKAGE = NetconfigPtr  PREFIX = rpcb_
2106
2107      void
2108      rpcb_DESTROY(netconf)
2109           Netconfig *netconf
2110         CODE:
2111           printf("NetconfigPtr::DESTROY\n");
2112           free( netconf );
2113
2114 File C<typemap>: Custom typemap for RPC.xs. (cf. L<perlxstypemap>)
2115
2116      TYPEMAP
2117      Netconfig *  T_PTROBJ
2118
2119 File C<RPC.pm>: Perl module for the RPC extension.
2120
2121      package RPC;
2122
2123      require Exporter;
2124      require DynaLoader;
2125      @ISA = qw(Exporter DynaLoader);
2126      @EXPORT = qw(rpcb_gettime getnetconfigent);
2127
2128      bootstrap RPC;
2129      1;
2130
2131 File C<rpctest.pl>: Perl test program for the RPC extension.
2132
2133      use RPC;
2134
2135      $netconf = getnetconfigent();
2136      $a = rpcb_gettime();
2137      print "time = $a\n";
2138      print "netconf = $netconf\n";
2139
2140      $netconf = getnetconfigent("tcp");
2141      $a = rpcb_gettime("poplar");
2142      print "time = $a\n";
2143      print "netconf = $netconf\n";
2144
2145 =head1 CAVEATS
2146
2147 XS code has full access to system calls including C library functions.
2148 It thus has the capability of interfering with things that the Perl core
2149 or other modules have set up, such as signal handlers or file handles.
2150 It could mess with the memory, or any number of harmful things.  Don't.
2151
2152 Some modules have an event loop, waiting for user-input.  It is highly
2153 unlikely that two such modules would work adequately together in a
2154 single Perl application.
2155
2156 In general, the perl interpreter views itself as the center of the
2157 universe as far as the Perl program goes.  XS code is viewed as a
2158 help-mate, to accomplish things that perl doesn't do, or doesn't do fast
2159 enough, but always subservient to perl.  The closer XS code adheres to
2160 this model, the less likely conflicts will occur.
2161
2162 One area where there has been conflict is in regards to C locales.  (See
2163 L<perllocale>.)  perl, with one exception and unless told otherwise,
2164 sets up the underlying locale the program is running in to the locale
2165 passed
2166 into it from the environment.  This is an important difference from a
2167 generic C language program, where the underlying locale is the "C"
2168 locale unless the program changes it.  As of v5.20, this underlying
2169 locale is completely hidden from pure Perl code outside the lexical
2170 scope of C<S<use locale>> except for a couple of function calls in the
2171 POSIX module which of necessity use it.  But the underlying locale, with
2172 that
2173 one exception is exposed to XS code, affecting all C library routines
2174 whose behavior is locale-dependent.  Your XS code better not assume that
2175 the underlying locale is "C".  The exception is the
2176 L<C<LC_NUMERIC>|perllocale/Category LC_NUMERIC: Numeric Formatting>
2177 locale category, and the reason it is an exception is that experience
2178 has shown that it can be problematic for XS code, whereas we have not
2179 had reports of problems with the
2180 L<other locale categories|perllocale/WHAT IS A LOCALE>.  And the reason
2181 for this one category being problematic is that the character used as a
2182 decimal point can vary.  Many European languages use a comma, whereas
2183 English, and hence Perl are expecting a dot (U+002E: FULL STOP).  Many
2184 modules can handle only the radix character being a dot, and so perl
2185 attempts to make it so.  Up through Perl v5.20, the attempt was merely
2186 to set C<LC_NUMERIC> upon startup to the C<"C"> locale.  Any
2187 L<setlocale()|perllocale/The setlocale function> otherwise would change
2188 it; this caused some failures.  Therefore, starting in v5.22, perl tries
2189 to keep C<LC_NUMERIC> always set to C<"C"> for XS code.
2190
2191 To summarize, here's what to expect and how to handle locales in XS code:
2192
2193 =over
2194
2195 =item Non-locale-aware XS code
2196
2197 Keep in mind that even if you think your code is not locale-aware, it
2198 may call a C library function that is.  Hopefully the man page for such
2199 a function will indicate that dependency, but the documentation is
2200 imperfect.
2201
2202 The current locale is exposed to XS code except possibly C<LC_NUMERIC>
2203 (explained in the next paragraph).
2204 There have not been reports of problems with the other categories.
2205 Perl initializes things on start-up so that the current locale is the
2206 one which is indicated by the user's environment in effect at that time.
2207 See L<perllocale/ENVIRONMENT>.
2208
2209 However, up through v5.20, Perl initialized things on start-up so that
2210 C<LC_NUMERIC> was set to the "C" locale.  But if any code anywhere
2211 changed it, it would stay changed.  This means that your module can't
2212 count on C<LC_NUMERIC> being something in particular, and you can't
2213 expect floating point numbers (including version strings) to have dots
2214 in them.  If you don't allow for a non-dot, your code could break if
2215 anyone anywhere changed the locale.  For this reason, v5.22 changed
2216 the behavior so that Perl tries to keep C<LC_NUMERIC> in the "C" locale
2217 except around the operations internally where it should be something
2218 else.  Misbehaving XS code will always be able to change the locale
2219 anyway, but the most common instance of this is checked for and
2220 handled.
2221
2222 =item Locale-aware XS code
2223
2224 If the locale from the user's environment is desired, there should be no
2225 need for XS code to set the locale except for C<LC_NUMERIC>, as perl has
2226 already set the others up.  XS code should avoid changing the locale, as
2227 it can adversely affect other, unrelated, code and may not be
2228 thread-safe.  To minimize problems, the macros
2229 L<perlapi/STORE_LC_NUMERIC_SET_TO_NEEDED>,
2230 L<perlapi/STORE_LC_NUMERIC_FORCE_TO_UNDERLYING>, and
2231 L<perlapi/RESTORE_LC_NUMERIC> should be used to affect any needed
2232 change.
2233
2234 However, some alien libraries that may be called do set it, such as
2235 C<Gtk>.  This can cause problems for the perl core and other modules.
2236 Starting in v5.20.1, calling the function
2237 L<sync_locale()|perlapi/sync_locale> from XS should be sufficient to
2238 avoid most of these problems.  Prior to this, you need a pure Perl
2239 statement that does this:
2240
2241  POSIX::setlocale(LC_ALL, POSIX::setlocale(LC_ALL));
2242
2243 or use the methods given in L<perlcall>.
2244
2245 =back
2246
2247 =head1 XS VERSION
2248
2249 This document covers features supported by C<ExtUtils::ParseXS>
2250 (also known as C<xsubpp>) 3.13_01.
2251
2252 =head1 AUTHOR
2253
2254 Originally written by Dean Roehrich <F<roehrich@cray.com>>.
2255
2256 Maintained since 1996 by The Perl Porters <F<perlbug@perl.org>>.