be defensive about setting {host,group,pass}cat (from Andy Dougherty)
[p5sagit/p5-mst-13.2.git] / pod / 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.
65
66 A file in XS format starts with a C language section which goes until the
67 first C<MODULE =Z<>> directive.  Other XS directives and XSUB definitions
68 may follow this line.  The "language" used in this part of the file
69 is usually referred to as the XS language.
70
71 See L<perlxstut> for a tutorial on the whole extension creation process.
72
73 Note: For some extensions, Dave Beazley's SWIG system may provide a
74 significantly more convenient mechanism for creating the extension glue
75 code. See L<http://www.cs.utah.edu/~beazley/SWIG> for more 
76 information.
77
78 =head2 On The Road
79
80 Many of the examples which follow will concentrate on creating an interface
81 between Perl and the ONC+ RPC bind library functions.  The rpcb_gettime()
82 function is used to demonstrate many features of the XS language.  This
83 function has two parameters; the first is an input parameter and the second
84 is an output parameter.  The function also returns a status value.
85
86         bool_t rpcb_gettime(const char *host, time_t *timep);
87
88 From C this function will be called with the following
89 statements.
90
91      #include <rpc/rpc.h>
92      bool_t status;
93      time_t timep;
94      status = rpcb_gettime( "localhost", &timep );
95
96 If an XSUB is created to offer a direct translation between this function
97 and Perl, then this XSUB will be used from Perl with the following code.
98 The $status and $timep variables will contain the output of the function.
99
100      use RPC;
101      $status = rpcb_gettime( "localhost", $timep );
102
103 The following XS file shows an XS subroutine, or XSUB, which
104 demonstrates one possible interface to the rpcb_gettime()
105 function.  This XSUB represents a direct translation between
106 C and Perl and so preserves the interface even from Perl.
107 This XSUB will be invoked from Perl with the usage shown
108 above.  Note that the first three #include statements, for
109 C<EXTERN.h>, C<perl.h>, and C<XSUB.h>, will always be present at the
110 beginning of an XS file.  This approach and others will be
111 expanded later in this document.
112
113      #include "EXTERN.h"
114      #include "perl.h"
115      #include "XSUB.h"
116      #include <rpc/rpc.h>
117
118      MODULE = RPC  PACKAGE = RPC
119
120      bool_t
121      rpcb_gettime(host,timep)
122           char *host
123           time_t &timep
124         OUTPUT:
125           timep
126
127 Any extension to Perl, including those containing XSUBs,
128 should have a Perl module to serve as the bootstrap which
129 pulls the extension into Perl.  This module will export the
130 extension's functions and variables to the Perl program and
131 will cause the extension's XSUBs to be linked into Perl.
132 The following module will be used for most of the examples
133 in this document and should be used from Perl with the C<use>
134 command as shown earlier.  Perl modules are explained in
135 more detail later in this document.
136
137      package RPC;
138
139      require Exporter;
140      require DynaLoader;
141      @ISA = qw(Exporter DynaLoader);
142      @EXPORT = qw( rpcb_gettime );
143
144      bootstrap RPC;
145      1;
146
147 Throughout this document a variety of interfaces to the rpcb_gettime()
148 XSUB will be explored.  The XSUBs will take their parameters in different
149 orders or will take different numbers of parameters.  In each case the
150 XSUB is an abstraction between Perl and the real C rpcb_gettime()
151 function, and the XSUB must always ensure that the real rpcb_gettime()
152 function is called with the correct parameters.  This abstraction will
153 allow the programmer to create a more Perl-like interface to the C
154 function.
155
156 =head2 The Anatomy of an XSUB
157
158 The simplest XSUBs consist of 3 parts: a description of the return
159 value, the name of the XSUB routine and the names of its arguments,
160 and a description of types or formats of the arguments.
161
162 The following XSUB allows a Perl program to access a C library function
163 called sin().  The XSUB will imitate the C function which takes a single
164 argument and returns a single value.
165
166      double
167      sin(x)
168        double x
169
170 When using parameters with C pointer types, as in
171
172      double string_to_double(char *s);
173
174 there may be two ways to describe this argument to B<xsubpp>:
175
176      char *  s
177      char    &s
178
179 Both these XS declarations correspond to the C<char*> C type, but they have
180 different semantics.  It is convenient to think that the indirection operator
181 C<*> should be considered as a part of the type and the address operator C<&>
182 should be considered part of the variable.  See L<"The Typemap"> and
183 L<"The & Unary Operator"> for more info about handling qualifiers and unary
184 operators in C types.
185
186 The function name and the return type must be placed on
187 separate lines and should be flush left-adjusted.
188
189   INCORRECT                        CORRECT
190
191   double sin(x)                    double
192     double x                       sin(x)
193                                      double x
194
195 The function body may be indented or left-adjusted.  The following example
196 shows a function with its body left-adjusted.  Most examples in this
197 document will indent the body for better readability.
198
199   CORRECT
200
201   double
202   sin(x)
203   double x
204
205 More complicated XSUBs may contain many other sections.  Each section of
206 an XSUB starts with the corresponding keyword, such as INIT: or CLEANUP:.
207 However, the first two lines of an XSUB always contain the same data:
208 descriptions of the return type and the names of the function and its
209 parameters.  Whatever immediately follows these is considered to be
210 an INPUT: section unless explicitly marked with another keyword.
211 (See L<The INPUT: Keyword>.)
212
213 An XSUB section continues until another section-start keyword is found.
214
215 =head2 The Argument Stack
216
217 The Perl argument stack is used to store the values which are
218 sent as parameters to the XSUB and to store the XSUB's
219 return value(s).  In reality all Perl functions (including non-XSUB
220 ones) keep their values on this stack all the same time, each limited
221 to its own range of positions on the stack.  In this document the
222 first position on that stack which belongs to the active
223 function will be referred to as position 0 for that function.
224
225 XSUBs refer to their stack arguments with the macro B<ST(x)>, where I<x>
226 refers to a position in this XSUB's part of the stack.  Position 0 for that
227 function would be known to the XSUB as ST(0).  The XSUB's incoming
228 parameters and outgoing return values always begin at ST(0).  For many
229 simple cases the B<xsubpp> compiler will generate the code necessary to
230 handle the argument stack by embedding code fragments found in the
231 typemaps.  In more complex cases the programmer must supply the code.
232
233 =head2 The RETVAL Variable
234
235 The RETVAL variable is a special C variable that is declared automatically
236 for you.  The C type of RETVAL matches the return type of the C library
237 function.  The B<xsubpp> compiler will declare this variable in each XSUB
238 with non-C<void> return type.  By default the generated C function
239 will use RETVAL to hold the return value of the C library function being
240 called.  In simple cases the value of RETVAL will be placed in ST(0) of
241 the argument stack where it can be received by Perl as the return value
242 of the XSUB.
243
244 If the XSUB has a return type of C<void> then the compiler will
245 not declare a RETVAL variable for that function.  When using
246 a PPCODE: section no manipulation of the RETVAL variable is required, the
247 section may use direct stack manipulation to place output values on the stack.
248
249 If PPCODE: directive is not used, C<void> return value should be used
250 only for subroutines which do not return a value, I<even if> CODE:
251 directive is used which sets ST(0) explicitly.
252
253 Older versions of this document recommended to use C<void> return
254 value in such cases. It was discovered that this could lead to
255 segfaults in cases when XSUB was I<truly> C<void>. This practice is
256 now deprecated, and may be not supported at some future version. Use
257 the return value C<SV *> in such cases. (Currently C<xsubpp> contains
258 some heuristic code which tries to disambiguate between "truly-void"
259 and "old-practice-declared-as-void" functions. Hence your code is at
260 mercy of this heuristics unless you use C<SV *> as return value.)
261
262 =head2 The MODULE Keyword
263
264 The MODULE keyword is used to start the XS code and to
265 specify the package of the functions which are being
266 defined.  All text preceding the first MODULE keyword is
267 considered C code and is passed through to the output
268 untouched.  Every XS module will have a bootstrap function
269 which is used to hook the XSUBs into Perl.  The package name
270 of this bootstrap function will match the value of the last
271 MODULE statement in the XS source files.  The value of
272 MODULE should always remain constant within the same XS
273 file, though this is not required.
274
275 The following example will start the XS code and will place
276 all functions in a package named RPC.
277
278      MODULE = RPC
279
280 =head2 The PACKAGE Keyword
281
282 When functions within an XS source file must be separated into packages
283 the PACKAGE keyword should be used.  This keyword is used with the MODULE
284 keyword and must follow immediately after it when used.
285
286      MODULE = RPC  PACKAGE = RPC
287
288      [ XS code in package RPC ]
289
290      MODULE = RPC  PACKAGE = RPCB
291
292      [ XS code in package RPCB ]
293
294      MODULE = RPC  PACKAGE = RPC
295
296      [ XS code in package RPC ]
297
298 Although this keyword is optional and in some cases provides redundant
299 information it should always be used.  This keyword will ensure that the
300 XSUBs appear in the desired package.
301
302 =head2 The PREFIX Keyword
303
304 The PREFIX keyword designates prefixes which should be
305 removed from the Perl function names.  If the C function is
306 C<rpcb_gettime()> and the PREFIX value is C<rpcb_> then Perl will
307 see this function as C<gettime()>.
308
309 This keyword should follow the PACKAGE keyword when used.
310 If PACKAGE is not used then PREFIX should follow the MODULE
311 keyword.
312
313      MODULE = RPC  PREFIX = rpc_
314
315      MODULE = RPC  PACKAGE = RPCB  PREFIX = rpcb_
316
317 =head2 The OUTPUT: Keyword
318
319 The OUTPUT: keyword indicates that certain function parameters should be
320 updated (new values made visible to Perl) when the XSUB terminates or that
321 certain values should be returned to the calling Perl function.  For
322 simple functions which have no CODE: or PPCODE: section,
323 such as the sin() function above, the RETVAL variable is
324 automatically designated as an output value.  For more complex functions
325 the B<xsubpp> compiler will need help to determine which variables are output
326 variables.
327
328 This keyword will normally be used to complement the CODE:  keyword.
329 The RETVAL variable is not recognized as an output variable when the
330 CODE: keyword is present.  The OUTPUT:  keyword is used in this
331 situation to tell the compiler that RETVAL really is an output
332 variable.
333
334 The OUTPUT: keyword can also be used to indicate that function parameters
335 are output variables.  This may be necessary when a parameter has been
336 modified within the function and the programmer would like the update to
337 be seen by Perl.
338
339      bool_t
340      rpcb_gettime(host,timep)
341           char *host
342           time_t &timep
343         OUTPUT:
344           timep
345
346 The OUTPUT: keyword will also allow an output parameter to
347 be mapped to a matching piece of code rather than to a
348 typemap.
349
350      bool_t
351      rpcb_gettime(host,timep)
352           char *host
353           time_t &timep
354         OUTPUT:
355           timep sv_setnv(ST(1), (double)timep);
356
357 B<xsubpp> emits an automatic C<SvSETMAGIC()> for all parameters in the
358 OUTPUT section of the XSUB, except RETVAL.  This is the usually desired
359 behavior, as it takes care of properly invoking 'set' magic on output
360 parameters (needed for hash or array element parameters that must be
361 created if they didn't exist).  If for some reason, this behavior is
362 not desired, the OUTPUT section may contain a C<SETMAGIC: DISABLE> line
363 to disable it for the remainder of the parameters in the OUTPUT section.
364 Likewise,  C<SETMAGIC: ENABLE> can be used to reenable it for the
365 remainder of the OUTPUT section.  See L<perlguts> for more details
366 about 'set' magic.
367
368 =head2 The CODE: Keyword
369
370 This keyword is used in more complicated XSUBs which require
371 special handling for the C function.  The RETVAL variable is
372 still declared, but it will not be returned unless it is specified
373 in the OUTPUT: section.
374
375 The following XSUB is for a C function which requires special handling of
376 its parameters.  The Perl usage is given first.
377
378      $status = rpcb_gettime( "localhost", $timep );
379
380 The XSUB follows.
381
382      bool_t
383      rpcb_gettime(host,timep)
384           char *host
385           time_t timep
386         CODE:
387                RETVAL = rpcb_gettime( host, &timep );
388         OUTPUT:
389           timep
390           RETVAL
391
392 =head2 The INIT: Keyword
393
394 The INIT: keyword allows initialization to be inserted into the XSUB before
395 the compiler generates the call to the C function.  Unlike the CODE: keyword
396 above, this keyword does not affect the way the compiler handles RETVAL.
397
398     bool_t
399     rpcb_gettime(host,timep)
400           char *host
401           time_t &timep
402         INIT:
403           printf("# Host is %s\n", host );
404         OUTPUT:
405           timep
406
407 Another use for the INIT: section is to check for preconditions before
408 making a call to the C function:
409
410     long long
411     lldiv(a,b)
412         long long a
413         long long b
414       INIT:
415         if (a == 0 && b == 0)
416             XSRETURN_UNDEF;
417         if (b == 0)
418             croak("lldiv: cannot divide by 0");
419
420 =head2 The NO_INIT Keyword
421
422 The NO_INIT keyword is used to indicate that a function
423 parameter is being used only as an output value.  The B<xsubpp>
424 compiler will normally generate code to read the values of
425 all function parameters from the argument stack and assign
426 them to C variables upon entry to the function.  NO_INIT
427 will tell the compiler that some parameters will be used for
428 output rather than for input and that they will be handled
429 before the function terminates.
430
431 The following example shows a variation of the rpcb_gettime() function.
432 This function uses the timep variable only as an output variable and does
433 not care about its initial contents.
434
435      bool_t
436      rpcb_gettime(host,timep)
437           char *host
438           time_t &timep = NO_INIT
439         OUTPUT:
440           timep
441
442 =head2 Initializing Function Parameters
443
444 C function parameters are normally initialized with their values from
445 the argument stack (which in turn contains the parameters that were
446 passed to the XSUB from Perl).  The typemaps contain the
447 code segments which are used to translate the Perl values to
448 the C parameters.  The programmer, however, is allowed to
449 override the typemaps and supply alternate (or additional)
450 initialization code.  Initialization code starts with the first
451 C<=>, C<;> or C<+> on a line in the INPUT: section.  The only
452 exception happens if this C<;> terminates the line, then this C<;>
453 is quietly ignored.
454
455 The following code demonstrates how to supply initialization code for
456 function parameters.  The initialization code is eval'd within double
457 quotes by the compiler before it is added to the output so anything
458 which should be interpreted literally [mainly C<$>, C<@>, or C<\\>]
459 must be protected with backslashes.  The variables $var, $arg,
460 and $type can be used as in typemaps.
461
462      bool_t
463      rpcb_gettime(host,timep)
464           char *host = (char *)SvPV($arg,PL_na);
465           time_t &timep = 0;
466         OUTPUT:
467           timep
468
469 This should not be used to supply default values for parameters.  One
470 would normally use this when a function parameter must be processed by
471 another library function before it can be used.  Default parameters are
472 covered in the next section.
473
474 If the initialization begins with C<=>, then it is output in
475 the declaration for the input variable, replacing the initialization
476 supplied by the typemap.  If the initialization
477 begins with C<;> or C<+>, then it is performed after
478 all of the input variables have been declared.  In the C<;>
479 case the initialization normally supplied by the typemap is not performed.
480 For the C<+> case, the declaration for the variable will include the
481 initialization from the typemap.  A global
482 variable, C<%v>, is available for the truly rare case where
483 information from one initialization is needed in another
484 initialization.
485
486 Here's a truly obscure example:
487
488      bool_t
489      rpcb_gettime(host,timep)
490           time_t &timep ; /* \$v{timep}=@{[$v{timep}=$arg]} */
491           char *host + SvOK($v{timep}) ? SvPV($arg,PL_na) : NULL;
492         OUTPUT:
493           timep
494
495 The construct C<\$v{timep}=@{[$v{timep}=$arg]}> used in the above
496 example has a two-fold purpose: first, when this line is processed by
497 B<xsubpp>, the Perl snippet C<$v{timep}=$arg> is evaluated.  Second,
498 the text of the evaluated snippet is output into the generated C file
499 (inside a C comment)!  During the processing of C<char *host> line,
500 $arg will evaluate to C<ST(0)>, and C<$v{timep}> will evaluate to
501 C<ST(1)>.
502
503 =head2 Default Parameter Values
504
505 Default values for XSUB arguments can be specified by
506 placing an assignment statement in the parameter list.  The
507 default value may be a number or a string.  Defaults should
508 always be used on the right-most parameters only.
509
510 To allow the XSUB for rpcb_gettime() to have a default host
511 value the parameters to the XSUB could be rearranged.  The
512 XSUB will then call the real rpcb_gettime() function with
513 the parameters in the correct order.  This XSUB can be called
514 from Perl with either of the following statements:
515
516      $status = rpcb_gettime( $timep, $host );
517
518      $status = rpcb_gettime( $timep );
519
520 The XSUB will look like the code  which  follows.   A  CODE:
521 block  is used to call the real rpcb_gettime() function with
522 the parameters in the correct order for that function.
523
524      bool_t
525      rpcb_gettime(timep,host="localhost")
526           char *host
527           time_t timep = NO_INIT
528         CODE:
529                RETVAL = rpcb_gettime( host, &timep );
530         OUTPUT:
531           timep
532           RETVAL
533
534 =head2 The PREINIT: Keyword
535
536 The PREINIT: keyword allows extra variables to be declared immediately
537 before or after the declartions of the parameters from the INPUT: section
538 are emitted.
539
540 If a variable is declared inside a CODE: section it will follow any typemap
541 code that is emitted for the input parameters.  This may result in the
542 declaration ending up after C code, which is C syntax error.  Similar
543 errors may happen with an explicit C<;>-type or C<+>-type initialization of
544 parameters is used (see L<"Initializing Function Parameters">).  Declaring
545 these variables in an INIT: section will not help.
546
547 In such cases, to force an additional variable to be declared together
548 with declarations of other variables, place the declaration into a
549 PREINIT: section.  The PREINIT: keyword may be used one or more times
550 within an XSUB.
551
552 The following examples are equivalent, but if the code is using complex
553 typemaps then the first example is safer.
554
555      bool_t
556      rpcb_gettime(timep)
557           time_t timep = NO_INIT
558         PREINIT:
559           char *host = "localhost";
560         CODE:
561           RETVAL = rpcb_gettime( host, &timep );
562         OUTPUT:
563           timep
564           RETVAL
565
566 For this particular case an INIT: keyword would generate the
567 same C code as the PREINIT: keyword.  Another correct, but error-prone example:
568
569      bool_t
570      rpcb_gettime(timep)
571           time_t timep = NO_INIT
572         CODE:
573           char *host = "localhost";
574           RETVAL = rpcb_gettime( host, &timep );
575         OUTPUT:
576           timep
577           RETVAL
578
579 Another way to declare C<host> is to use a C block in the CODE: section:
580
581      bool_t
582      rpcb_gettime(timep)
583           time_t timep = NO_INIT
584         CODE:
585           {
586             char *host = "localhost";
587             RETVAL = rpcb_gettime( host, &timep );
588           }
589         OUTPUT:
590           timep
591           RETVAL
592
593 The ability to put additional declarations before the typemap entries are
594 processed is very handy in the cases when typemap conversions manipulate
595 some global state:
596
597     MyObject
598     mutate(o)
599         PREINIT:
600             MyState st = global_state;
601         INPUT:
602             MyObject o;
603         CLEANUP:
604             reset_to(global_state, st);
605
606 Here we suppose that conversion to C<MyObject> in the INPUT: section and from
607 MyObject when processing RETVAL will modify a global variable C<global_state>.
608 After these conversions are performed, we restore the old value of
609 C<global_state> (to avoid memory leaks, for example).
610
611 There is another way to trade clarity for compactness: INPUT sections allow
612 declaration of C variables which do not appear in the parameter list of
613 a subroutine.  Thus the above code for mutate() can be rewritten as
614
615     MyObject
616     mutate(o)
617           MyState st = global_state;
618           MyObject o;
619         CLEANUP:
620           reset_to(global_state, st);
621
622 and the code for rpcb_gettime() can be rewritten as
623
624      bool_t
625      rpcb_gettime(timep)
626           time_t timep = NO_INIT
627           char *host = "localhost";
628         C_ARGS:
629           host, &timep
630         OUTPUT:
631           timep
632           RETVAL
633
634 =head2 The SCOPE: Keyword
635
636 The SCOPE: keyword allows scoping to be enabled for a particular XSUB. If
637 enabled, the XSUB will invoke ENTER and LEAVE automatically.
638
639 To support potentially complex type mappings, if a typemap entry used
640 by an XSUB contains a comment like C</*scope*/> then scoping will
641 be automatically enabled for that XSUB.
642
643 To enable scoping:
644
645     SCOPE: ENABLE
646
647 To disable scoping:
648
649     SCOPE: DISABLE
650
651 =head2 The INPUT: Keyword
652
653 The XSUB's parameters are usually evaluated immediately after entering the
654 XSUB.  The INPUT: keyword can be used to force those parameters to be
655 evaluated a little later.  The INPUT: keyword can be used multiple times
656 within an XSUB and can be used to list one or more input variables.  This
657 keyword is used with the PREINIT: keyword.
658
659 The following example shows how the input parameter C<timep> can be
660 evaluated late, after a PREINIT.
661
662     bool_t
663     rpcb_gettime(host,timep)
664           char *host
665         PREINIT:
666           time_t tt;
667         INPUT:
668           time_t timep
669         CODE:
670                RETVAL = rpcb_gettime( host, &tt );
671                timep = tt;
672         OUTPUT:
673           timep
674           RETVAL
675
676 The next example shows each input parameter evaluated late.
677
678     bool_t
679     rpcb_gettime(host,timep)
680         PREINIT:
681           time_t tt;
682         INPUT:
683           char *host
684         PREINIT:
685           char *h;
686         INPUT:
687           time_t timep
688         CODE:
689                h = host;
690                RETVAL = rpcb_gettime( h, &tt );
691                timep = tt;
692         OUTPUT:
693           timep
694           RETVAL
695
696 Since INPUT sections allow declaration of C variables which do not appear
697 in the parameter list of a subroutine, this may be shortened to:
698
699     bool_t
700     rpcb_gettime(host,timep)
701           time_t tt;
702           char *host;
703           char *h = host;
704           time_t timep;
705         CODE:
706           RETVAL = rpcb_gettime( h, &tt );
707           timep = tt;
708         OUTPUT:
709           timep
710           RETVAL
711
712 (We used our knowledge that input conversion for C<char *> is a "simple" one,
713 thus C<host> is initialized on the declaration line, and our assignment
714 C<h = host> is not performed too early.  Otherwise one would need to have the
715 assignment C<h = host> in a CODE: or INIT: section.)
716
717 =head2 Variable-length Parameter Lists
718
719 XSUBs can have variable-length parameter lists by specifying an ellipsis
720 C<(...)> in the parameter list.  This use of the ellipsis is similar to that
721 found in ANSI C.  The programmer is able to determine the number of
722 arguments passed to the XSUB by examining the C<items> variable which the
723 B<xsubpp> compiler supplies for all XSUBs.  By using this mechanism one can
724 create an XSUB which accepts a list of parameters of unknown length.
725
726 The I<host> parameter for the rpcb_gettime() XSUB can be
727 optional so the ellipsis can be used to indicate that the
728 XSUB will take a variable number of parameters.  Perl should
729 be able to call this XSUB with either of the following statements.
730
731      $status = rpcb_gettime( $timep, $host );
732
733      $status = rpcb_gettime( $timep );
734
735 The XS code, with ellipsis, follows.
736
737      bool_t
738      rpcb_gettime(timep, ...)
739           time_t timep = NO_INIT
740         PREINIT:
741           char *host = "localhost";
742           STRLEN n_a;
743         CODE:
744           if( items > 1 )
745                host = (char *)SvPV(ST(1), n_a);
746           RETVAL = rpcb_gettime( host, &timep );
747         OUTPUT:
748           timep
749           RETVAL
750
751 =head2 The C_ARGS: Keyword
752
753 The C_ARGS: keyword allows creating of XSUBS which have different
754 calling sequence from Perl than from C, without a need to write
755 CODE: or PPCODE: section.  The contents of the C_ARGS: paragraph is
756 put as the argument to the called C function without any change.
757
758 For example, suppose that a C function is declared as
759
760     symbolic nth_derivative(int n, symbolic function, int flags);
761
762 and that the default flags are kept in a global C variable
763 C<default_flags>.  Suppose that you want to create an interface which
764 is called as
765
766     $second_deriv = $function->nth_derivative(2);
767
768 To do this, declare the XSUB as
769
770     symbolic
771     nth_derivative(function, n)
772         symbolic        function
773         int             n
774       C_ARGS:
775         n, function, default_flags
776
777 =head2 The PPCODE: Keyword
778
779 The PPCODE: keyword is an alternate form of the CODE: keyword and is used
780 to tell the B<xsubpp> compiler that the programmer is supplying the code to
781 control the argument stack for the XSUBs return values.  Occasionally one
782 will want an XSUB to return a list of values rather than a single value.
783 In these cases one must use PPCODE: and then explicitly push the list of
784 values on the stack.  The PPCODE: and CODE:  keywords should not be used
785 together within the same XSUB.
786
787 The actual difference between PPCODE: and CODE: sections is in the
788 initialization of C<SP> macro (which stands for the I<current> Perl
789 stack pointer), and in the handling of data on the stack when returning
790 from an XSUB.  In CODE: sections SP preserves the value which was on
791 entry to the XSUB: SP is on the function pointer (which follows the
792 last parameter).  In PPCODE: sections SP is moved backward to the
793 beginning of the parameter list, which allows C<PUSH*()> macros
794 to place output values in the place Perl expects them to be when
795 the XSUB returns back to Perl.
796
797 The generated trailer for a CODE: section ensures that the number of return
798 values Perl will see is either 0 or 1 (depending on the C<void>ness of the
799 return value of the C function, and heuristics mentioned in
800 L<"The RETVAL Variable">).  The trailer generated for a PPCODE: section
801 is based on the number of return values and on the number of times
802 C<SP> was updated by C<[X]PUSH*()> macros.
803
804 Note that macros C<ST(i)>, C<XST_m*()> and C<XSRETURN*()> work equally
805 well in CODE: sections and PPCODE: sections.
806
807 The following XSUB will call the C rpcb_gettime() function
808 and will return its two output values, timep and status, to
809 Perl as a single list.
810
811      void
812      rpcb_gettime(host)
813           char *host
814         PREINIT:
815           time_t  timep;
816           bool_t  status;
817         PPCODE:
818           status = rpcb_gettime( host, &timep );
819           EXTEND(SP, 2);
820           PUSHs(sv_2mortal(newSViv(status)));
821           PUSHs(sv_2mortal(newSViv(timep)));
822
823 Notice that the programmer must supply the C code necessary
824 to have the real rpcb_gettime() function called and to have
825 the return values properly placed on the argument stack.
826
827 The C<void> return type for this function tells the B<xsubpp> compiler that
828 the RETVAL variable is not needed or used and that it should not be created.
829 In most scenarios the void return type should be used with the PPCODE:
830 directive.
831
832 The EXTEND() macro is used to make room on the argument
833 stack for 2 return values.  The PPCODE: directive causes the
834 B<xsubpp> compiler to create a stack pointer available as C<SP>, and it
835 is this pointer which is being used in the EXTEND() macro.
836 The values are then pushed onto the stack with the PUSHs()
837 macro.
838
839 Now the rpcb_gettime() function can be used from Perl with
840 the following statement.
841
842      ($status, $timep) = rpcb_gettime("localhost");
843
844 When handling output parameters with a PPCODE section, be sure to handle
845 'set' magic properly.  See L<perlguts> for details about 'set' magic.
846
847 =head2 Returning Undef And Empty Lists
848
849 Occasionally the programmer will want to return simply
850 C<undef> or an empty list if a function fails rather than a
851 separate status value.  The rpcb_gettime() function offers
852 just this situation.  If the function succeeds we would like
853 to have it return the time and if it fails we would like to
854 have undef returned.  In the following Perl code the value
855 of $timep will either be undef or it will be a valid time.
856
857      $timep = rpcb_gettime( "localhost" );
858
859 The following XSUB uses the C<SV *> return type as a mnemonic only,
860 and uses a CODE: block to indicate to the compiler
861 that the programmer has supplied all the necessary code.  The
862 sv_newmortal() call will initialize the return value to undef, making that
863 the default return value.
864
865      SV *
866      rpcb_gettime(host)
867           char *  host
868         PREINIT:
869           time_t  timep;
870           bool_t x;
871         CODE:
872           ST(0) = sv_newmortal();
873           if( rpcb_gettime( host, &timep ) )
874                sv_setnv( ST(0), (double)timep);
875
876 The next example demonstrates how one would place an explicit undef in the
877 return value, should the need arise.
878
879      SV *
880      rpcb_gettime(host)
881           char *  host
882         PREINIT:
883           time_t  timep;
884           bool_t x;
885         CODE:
886           ST(0) = sv_newmortal();
887           if( rpcb_gettime( host, &timep ) ){
888                sv_setnv( ST(0), (double)timep);
889           }
890           else{
891                ST(0) = &PL_sv_undef;
892           }
893
894 To return an empty list one must use a PPCODE: block and
895 then not push return values on the stack.
896
897      void
898      rpcb_gettime(host)
899           char *host
900         PREINIT:
901           time_t  timep;
902         PPCODE:
903           if( rpcb_gettime( host, &timep ) )
904                PUSHs(sv_2mortal(newSViv(timep)));
905           else{
906               /* Nothing pushed on stack, so an empty
907                * list is implicitly returned. */
908           }
909
910 Some people may be inclined to include an explicit C<return> in the above
911 XSUB, rather than letting control fall through to the end.  In those
912 situations C<XSRETURN_EMPTY> should be used, instead.  This will ensure that
913 the XSUB stack is properly adjusted.  Consult L<perlguts/"API LISTING"> for
914 other C<XSRETURN> macros.
915
916 Since C<XSRETURN_*> macros can be used with CODE blocks as well, one can
917 rewrite this example as:
918
919      int
920      rpcb_gettime(host)
921           char *host
922         PREINIT:
923           time_t  timep;
924         CODE:
925           RETVAL = rpcb_gettime( host, &timep );
926           if (RETVAL == 0)
927                 XSRETURN_UNDEF;
928         OUTPUT:
929           RETVAL
930
931 In fact, one can put this check into a CLEANUP: section as well.  Together
932 with PREINIT: simplifications, this leads to:
933
934      int
935      rpcb_gettime(host)
936           char *host
937           time_t  timep;
938         CLEANUP:
939           if (RETVAL == 0)
940                 XSRETURN_UNDEF;
941
942 =head2 The REQUIRE: Keyword
943
944 The REQUIRE: keyword is used to indicate the minimum version of the
945 B<xsubpp> compiler needed to compile the XS module.  An XS module which
946 contains the following statement will compile with only B<xsubpp> version
947 1.922 or greater:
948
949         REQUIRE: 1.922
950
951 =head2 The CLEANUP: Keyword
952
953 This keyword can be used when an XSUB requires special cleanup procedures
954 before it terminates.  When the CLEANUP:  keyword is used it must follow
955 any CODE:, PPCODE:, or OUTPUT: blocks which are present in the XSUB.  The
956 code specified for the cleanup block will be added as the last statements
957 in the XSUB.
958
959 =head2 The BOOT: Keyword
960
961 The BOOT: keyword is used to add code to the extension's bootstrap
962 function.  The bootstrap function is generated by the B<xsubpp> compiler and
963 normally holds the statements necessary to register any XSUBs with Perl.
964 With the BOOT: keyword the programmer can tell the compiler to add extra
965 statements to the bootstrap function.
966
967 This keyword may be used any time after the first MODULE keyword and should
968 appear on a line by itself.  The first blank line after the keyword will
969 terminate the code block.
970
971      BOOT:
972      # The following message will be printed when the
973      # bootstrap function executes.
974      printf("Hello from the bootstrap!\n");
975
976 =head2 The VERSIONCHECK: Keyword
977
978 The VERSIONCHECK: keyword corresponds to B<xsubpp>'s C<-versioncheck> and
979 C<-noversioncheck> options.  This keyword overrides the command line
980 options.  Version checking is enabled by default.  When version checking is
981 enabled the XS module will attempt to verify that its version matches the
982 version of the PM module.
983
984 To enable version checking:
985
986     VERSIONCHECK: ENABLE
987
988 To disable version checking:
989
990     VERSIONCHECK: DISABLE
991
992 =head2 The PROTOTYPES: Keyword
993
994 The PROTOTYPES: keyword corresponds to B<xsubpp>'s C<-prototypes> and
995 C<-noprototypes> options.  This keyword overrides the command line options.
996 Prototypes are enabled by default.  When prototypes are enabled XSUBs will
997 be given Perl prototypes.  This keyword may be used multiple times in an XS
998 module to enable and disable prototypes for different parts of the module.
999
1000 To enable prototypes:
1001
1002     PROTOTYPES: ENABLE
1003
1004 To disable prototypes:
1005
1006     PROTOTYPES: DISABLE
1007
1008 =head2 The PROTOTYPE: Keyword
1009
1010 This keyword is similar to the PROTOTYPES: keyword above but can be used to
1011 force B<xsubpp> to use a specific prototype for the XSUB.  This keyword
1012 overrides all other prototype options and keywords but affects only the
1013 current XSUB.  Consult L<perlsub/Prototypes> for information about Perl
1014 prototypes.
1015
1016     bool_t
1017     rpcb_gettime(timep, ...)
1018           time_t timep = NO_INIT
1019         PROTOTYPE: $;$
1020         PREINIT:
1021           char *host = "localhost";
1022           STRLEN n_a;
1023         CODE:
1024                   if( items > 1 )
1025                        host = (char *)SvPV(ST(1), n_a);
1026                   RETVAL = rpcb_gettime( host, &timep );
1027         OUTPUT:
1028           timep
1029           RETVAL
1030
1031 =head2 The ALIAS: Keyword
1032
1033 The ALIAS: keyword allows an XSUB to have two or more unique Perl names
1034 and to know which of those names was used when it was invoked.  The Perl
1035 names may be fully-qualified with package names.  Each alias is given an
1036 index.  The compiler will setup a variable called C<ix> which contain the
1037 index of the alias which was used.  When the XSUB is called with its
1038 declared name C<ix> will be 0.
1039
1040 The following example will create aliases C<FOO::gettime()> and
1041 C<BAR::getit()> for this function.
1042
1043     bool_t
1044     rpcb_gettime(host,timep)
1045           char *host
1046           time_t &timep
1047         ALIAS:
1048             FOO::gettime = 1
1049             BAR::getit = 2
1050         INIT:
1051           printf("# ix = %d\n", ix );
1052         OUTPUT:
1053           timep
1054
1055 =head2 The INTERFACE: Keyword
1056
1057 This keyword declares the current XSUB as a keeper of the given
1058 calling signature.  If some text follows this keyword, it is
1059 considered as a list of functions which have this signature, and
1060 should be attached to the current XSUB.
1061
1062 For example, if you have 4 C functions multiply(), divide(), add(),
1063 subtract() all having the signature:
1064
1065     symbolic f(symbolic, symbolic);
1066
1067 you can make them all to use the same XSUB using this:
1068
1069     symbolic
1070     interface_s_ss(arg1, arg2)  
1071         symbolic        arg1
1072         symbolic        arg2
1073     INTERFACE:
1074         multiply divide 
1075         add subtract
1076
1077 (This is the complete XSUB code for 4 Perl functions!)  Four generated
1078 Perl function share names with corresponding C functions.
1079
1080 The advantage of this approach comparing to ALIAS: keyword is that there
1081 is no need to code a switch statement, each Perl function (which shares
1082 the same XSUB) knows which C function it should call.  Additionally, one
1083 can attach an extra function remainder() at runtime by using
1084
1085     CV *mycv = newXSproto("Symbolic::remainder", 
1086                           XS_Symbolic_interface_s_ss, __FILE__, "$$");
1087     XSINTERFACE_FUNC_SET(mycv, remainder);
1088
1089 say, from another XSUB.  (This example supposes that there was no
1090 INTERFACE_MACRO: section, otherwise one needs to use something else instead of
1091 C<XSINTERFACE_FUNC_SET>, see the next section.)
1092
1093 =head2 The INTERFACE_MACRO: Keyword
1094
1095 This keyword allows one to define an INTERFACE using a different way
1096 to extract a function pointer from an XSUB.  The text which follows
1097 this keyword should give the name of macros which would extract/set a
1098 function pointer.  The extractor macro is given return type, C<CV*>,
1099 and C<XSANY.any_dptr> for this C<CV*>.  The setter macro is given cv,
1100 and the function pointer.
1101
1102 The default value is C<XSINTERFACE_FUNC> and C<XSINTERFACE_FUNC_SET>.
1103 An INTERFACE keyword with an empty list of functions can be omitted if
1104 INTERFACE_MACRO keyword is used.
1105
1106 Suppose that in the previous example functions pointers for 
1107 multiply(), divide(), add(), subtract() are kept in a global C array
1108 C<fp[]> with offsets being C<multiply_off>, C<divide_off>, C<add_off>,
1109 C<subtract_off>.  Then one can use 
1110
1111     #define XSINTERFACE_FUNC_BYOFFSET(ret,cv,f) \
1112         ((XSINTERFACE_CVT(ret,))fp[CvXSUBANY(cv).any_i32])
1113     #define XSINTERFACE_FUNC_BYOFFSET_set(cv,f) \
1114         CvXSUBANY(cv).any_i32 = CAT2( f, _off )
1115
1116 in C section,
1117
1118     symbolic
1119     interface_s_ss(arg1, arg2)  
1120         symbolic        arg1
1121         symbolic        arg2
1122       INTERFACE_MACRO: 
1123         XSINTERFACE_FUNC_BYOFFSET
1124         XSINTERFACE_FUNC_BYOFFSET_set
1125       INTERFACE:
1126         multiply divide 
1127         add subtract
1128
1129 in XSUB section.
1130
1131 =head2 The INCLUDE: Keyword
1132
1133 This keyword can be used to pull other files into the XS module.  The other
1134 files may have XS code.  INCLUDE: can also be used to run a command to
1135 generate the XS code to be pulled into the module.
1136
1137 The file F<Rpcb1.xsh> contains our C<rpcb_gettime()> function:
1138
1139     bool_t
1140     rpcb_gettime(host,timep)
1141           char *host
1142           time_t &timep
1143         OUTPUT:
1144           timep
1145
1146 The XS module can use INCLUDE: to pull that file into it.
1147
1148     INCLUDE: Rpcb1.xsh
1149
1150 If the parameters to the INCLUDE: keyword are followed by a pipe (C<|>) then
1151 the compiler will interpret the parameters as a command.
1152
1153     INCLUDE: cat Rpcb1.xsh |
1154
1155 =head2 The CASE: Keyword
1156
1157 The CASE: keyword allows an XSUB to have multiple distinct parts with each
1158 part acting as a virtual XSUB.  CASE: is greedy and if it is used then all
1159 other XS keywords must be contained within a CASE:.  This means nothing may
1160 precede the first CASE: in the XSUB and anything following the last CASE: is
1161 included in that case.
1162
1163 A CASE: might switch via a parameter of the XSUB, via the C<ix> ALIAS:
1164 variable (see L<"The ALIAS: Keyword">), or maybe via the C<items> variable
1165 (see L<"Variable-length Parameter Lists">).  The last CASE: becomes the
1166 B<default> case if it is not associated with a conditional.  The following
1167 example shows CASE switched via C<ix> with a function C<rpcb_gettime()>
1168 having an alias C<x_gettime()>.  When the function is called as
1169 C<rpcb_gettime()> its parameters are the usual C<(char *host, time_t *timep)>,
1170 but when the function is called as C<x_gettime()> its parameters are
1171 reversed, C<(time_t *timep, char *host)>.
1172
1173     long
1174     rpcb_gettime(a,b)
1175       CASE: ix == 1
1176         ALIAS:
1177           x_gettime = 1
1178         INPUT:
1179           # 'a' is timep, 'b' is host
1180           char *b
1181           time_t a = NO_INIT
1182         CODE:
1183                RETVAL = rpcb_gettime( b, &a );
1184         OUTPUT:
1185           a
1186           RETVAL
1187       CASE:
1188           # 'a' is host, 'b' is timep
1189           char *a
1190           time_t &b = NO_INIT
1191         OUTPUT:
1192           b
1193           RETVAL
1194
1195 That function can be called with either of the following statements.  Note
1196 the different argument lists.
1197
1198         $status = rpcb_gettime( $host, $timep );
1199
1200         $status = x_gettime( $timep, $host );
1201
1202 =head2 The & Unary Operator
1203
1204 The C<&> unary operator in the INPUT: section is used to tell B<xsubpp>
1205 that it should convert a Perl value to/from C using the C type to the left
1206 of C<&>, but provide a pointer to this value when the C function is called.
1207
1208 This is useful to avoid a CODE: block for a C function which takes a parameter
1209 by reference.  Typically, the parameter should be not a pointer type (an
1210 C<int> or C<long> but not a C<int*> or C<long*>).
1211
1212 The following XSUB will generate incorrect C code.  The B<xsubpp> compiler will
1213 turn this into code which calls C<rpcb_gettime()> with parameters C<(char
1214 *host, time_t timep)>, but the real C<rpcb_gettime()> wants the C<timep>
1215 parameter to be of type C<time_t*> rather than C<time_t>.
1216
1217     bool_t
1218     rpcb_gettime(host,timep)
1219           char *host
1220           time_t timep
1221         OUTPUT:
1222           timep
1223
1224 That problem is corrected by using the C<&> operator.  The B<xsubpp> compiler
1225 will now turn this into code which calls C<rpcb_gettime()> correctly with
1226 parameters C<(char *host, time_t *timep)>.  It does this by carrying the
1227 C<&> through, so the function call looks like C<rpcb_gettime(host, &timep)>.
1228
1229     bool_t
1230     rpcb_gettime(host,timep)
1231           char *host
1232           time_t &timep
1233         OUTPUT:
1234           timep
1235
1236 =head2 Inserting Comments and C Preprocessor Directives
1237
1238 C preprocessor directives are allowed within BOOT:, PREINIT: INIT:,
1239 CODE:, PPCODE:, and CLEANUP: blocks, as well as outside the functions.
1240 Comments are allowed anywhere after the MODULE keyword.  The compiler
1241 will pass the preprocessor directives through untouched and will remove
1242 the commented lines.
1243
1244 Comments can be added to XSUBs by placing a C<#> as the first
1245 non-whitespace of a line.  Care should be taken to avoid making the
1246 comment look like a C preprocessor directive, lest it be interpreted as
1247 such.  The simplest way to prevent this is to put whitespace in front of
1248 the C<#>.
1249
1250 If you use preprocessor directives to choose one of two
1251 versions of a function, use
1252
1253     #if ... version1
1254     #else /* ... version2  */
1255     #endif
1256
1257 and not
1258
1259     #if ... version1
1260     #endif
1261     #if ... version2
1262     #endif
1263
1264 because otherwise B<xsubpp> will believe that you made a duplicate
1265 definition of the function.  Also, put a blank line before the
1266 #else/#endif so it will not be seen as part of the function body.
1267
1268 =head2 Using XS With C++
1269
1270 If an XSUB name contains C<::>, it is considered to be a C++ method.
1271 The generated Perl function will assume that
1272 its first argument is an object pointer.  The object pointer
1273 will be stored in a variable called THIS.  The object should
1274 have been created by C++ with the new() function and should
1275 be blessed by Perl with the sv_setref_pv() macro.  The
1276 blessing of the object by Perl can be handled by a typemap.  An example
1277 typemap is shown at the end of this section.
1278
1279 If the return type of the XSUB includes C<static>, the method is considered
1280 to be a static method.  It will call the C++
1281 function using the class::method() syntax.  If the method is not static
1282 the function will be called using the THIS-E<gt>method() syntax.
1283
1284 The next examples will use the following C++ class.
1285
1286      class color {
1287           public:
1288           color();
1289           ~color();
1290           int blue();
1291           void set_blue( int );
1292
1293           private:
1294           int c_blue;
1295      };
1296
1297 The XSUBs for the blue() and set_blue() methods are defined with the class
1298 name but the parameter for the object (THIS, or "self") is implicit and is
1299 not listed.
1300
1301      int
1302      color::blue()
1303
1304      void
1305      color::set_blue( val )
1306           int val
1307
1308 Both Perl functions will expect an object as the first parameter.  In the 
1309 generated C++ code the object is called C<THIS>, and the method call will
1310 be performed on this object.  So in the C++ code the blue() and set_blue()
1311 methods will be called as this:
1312
1313      RETVAL = THIS->blue();
1314
1315      THIS->set_blue( val );
1316
1317 If the function's name is B<DESTROY> then the C++ C<delete> function will be
1318 called and C<THIS> will be given as its parameter.  The generated C++ code for
1319
1320      void
1321      color::DESTROY()
1322
1323 will look like this:
1324
1325      color *THIS = ...; // Initialized as in typemap
1326
1327      delete THIS;
1328
1329 If the function's name is B<new> then the C++ C<new> function will be called
1330 to create a dynamic C++ object.  The XSUB will expect the class name, which
1331 will be kept in a variable called C<CLASS>, to be given as the first
1332 argument.
1333
1334      color *
1335      color::new()
1336
1337 The generated C++ code will call C<new>.
1338
1339      RETVAL = new color();
1340
1341 The following is an example of a typemap that could be used for this C++
1342 example.
1343
1344     TYPEMAP
1345     color *             O_OBJECT
1346
1347     OUTPUT
1348     # The Perl object is blessed into 'CLASS', which should be a
1349     # char* having the name of the package for the blessing.
1350     O_OBJECT
1351         sv_setref_pv( $arg, CLASS, (void*)$var );
1352
1353     INPUT
1354     O_OBJECT
1355         if( sv_isobject($arg) && (SvTYPE(SvRV($arg)) == SVt_PVMG) )
1356                 $var = ($type)SvIV((SV*)SvRV( $arg ));
1357         else{
1358                 warn( \"${Package}::$func_name() -- $var is not a blessed SV reference\" );
1359                 XSRETURN_UNDEF;
1360         }
1361
1362 =head2 Interface Strategy
1363
1364 When designing an interface between Perl and a C library a straight
1365 translation from C to XS (such as created by C<h2xs -x>) is often sufficient.
1366 However, sometimes the interface will look
1367 very C-like and occasionally nonintuitive, especially when the C function
1368 modifies one of its parameters, or returns failure inband (as in "negative
1369 return values mean failure").  In cases where the programmer wishes to
1370 create a more Perl-like interface the following strategy may help to
1371 identify the more critical parts of the interface.
1372
1373 Identify the C functions with input/output or output parameters.  The XSUBs for
1374 these functions may be able to return lists to Perl.
1375
1376 Identify the C functions which use some inband info as an indication
1377 of failure.  They may be
1378 candidates to return undef or an empty list in case of failure.  If the
1379 failure may be detected without a call to the C function, you may want to use
1380 an INIT: section to report the failure.  For failures detectable after the C
1381 function returns one may want to use a CLEANUP: section to process the
1382 failure.  In more complicated cases use CODE: or PPCODE: sections.
1383
1384 If many functions use the same failure indication based on the return value,
1385 you may want to create a special typedef to handle this situation.  Put
1386
1387   typedef int negative_is_failure;
1388
1389 near the beginning of XS file, and create an OUTPUT typemap entry
1390 for C<negative_is_failure> which converts negative values to C<undef>, or
1391 maybe croak()s.  After this the return value of type C<negative_is_failure>
1392 will create more Perl-like interface.
1393
1394 Identify which values are used by only the C and XSUB functions
1395 themselves, say, when a parameter to a function should be a contents of a
1396 global variable.  If Perl does not need to access the contents of the value
1397 then it may not be necessary to provide a translation for that value
1398 from C to Perl.
1399
1400 Identify the pointers in the C function parameter lists and return
1401 values.  Some pointers may be used to implement input/output or
1402 output parameters, they can be handled in XS with the C<&> unary operator,
1403 and, possibly, using the NO_INIT keyword.
1404 Some others will require handling of types like C<int *>, and one needs
1405 to decide what a useful Perl translation will do in such a case.  When
1406 the semantic is clear, it is advisable to put the translation into a typemap
1407 file.
1408
1409 Identify the structures used by the C functions.  In many
1410 cases it may be helpful to use the T_PTROBJ typemap for
1411 these structures so they can be manipulated by Perl as
1412 blessed objects.  (This is handled automatically by C<h2xs -x>.)
1413
1414 If the same C type is used in several different contexts which require
1415 different translations, C<typedef> several new types mapped to this C type,
1416 and create separate F<typemap> entries for these new types.  Use these
1417 types in declarations of return type and parameters to XSUBs.
1418
1419 =head2 Perl Objects And C Structures
1420
1421 When dealing with C structures one should select either
1422 B<T_PTROBJ> or B<T_PTRREF> for the XS type.  Both types are
1423 designed to handle pointers to complex objects.  The
1424 T_PTRREF type will allow the Perl object to be unblessed
1425 while the T_PTROBJ type requires that the object be blessed.
1426 By using T_PTROBJ one can achieve a form of type-checking
1427 because the XSUB will attempt to verify that the Perl object
1428 is of the expected type.
1429
1430 The following XS code shows the getnetconfigent() function which is used
1431 with ONC+ TIRPC.  The getnetconfigent() function will return a pointer to a
1432 C structure and has the C prototype shown below.  The example will
1433 demonstrate how the C pointer will become a Perl reference.  Perl will
1434 consider this reference to be a pointer to a blessed object and will
1435 attempt to call a destructor for the object.  A destructor will be
1436 provided in the XS source to free the memory used by getnetconfigent().
1437 Destructors in XS can be created by specifying an XSUB function whose name
1438 ends with the word B<DESTROY>.  XS destructors can be used to free memory
1439 which may have been malloc'd by another XSUB.
1440
1441      struct netconfig *getnetconfigent(const char *netid);
1442
1443 A C<typedef> will be created for C<struct netconfig>.  The Perl
1444 object will be blessed in a class matching the name of the C
1445 type, with the tag C<Ptr> appended, and the name should not
1446 have embedded spaces if it will be a Perl package name.  The
1447 destructor will be placed in a class corresponding to the
1448 class of the object and the PREFIX keyword will be used to
1449 trim the name to the word DESTROY as Perl will expect.
1450
1451      typedef struct netconfig Netconfig;
1452
1453      MODULE = RPC  PACKAGE = RPC
1454
1455      Netconfig *
1456      getnetconfigent(netid)
1457           char *netid
1458
1459      MODULE = RPC  PACKAGE = NetconfigPtr  PREFIX = rpcb_
1460
1461      void
1462      rpcb_DESTROY(netconf)
1463           Netconfig *netconf
1464         CODE:
1465           printf("Now in NetconfigPtr::DESTROY\n");
1466           free( netconf );
1467
1468 This example requires the following typemap entry.  Consult the typemap
1469 section for more information about adding new typemaps for an extension.
1470
1471      TYPEMAP
1472      Netconfig *  T_PTROBJ
1473
1474 This example will be used with the following Perl statements.
1475
1476      use RPC;
1477      $netconf = getnetconfigent("udp");
1478
1479 When Perl destroys the object referenced by $netconf it will send the
1480 object to the supplied XSUB DESTROY function.  Perl cannot determine, and
1481 does not care, that this object is a C struct and not a Perl object.  In
1482 this sense, there is no difference between the object created by the
1483 getnetconfigent() XSUB and an object created by a normal Perl subroutine.
1484
1485 =head2 The Typemap
1486
1487 The typemap is a collection of code fragments which are used by the B<xsubpp>
1488 compiler to map C function parameters and values to Perl values.  The
1489 typemap file may consist of three sections labeled C<TYPEMAP>, C<INPUT>, and
1490 C<OUTPUT>.  An unlabelled initial section is assumed to be a C<TYPEMAP>
1491 section.  The INPUT section tells
1492 the compiler how to translate Perl values
1493 into variables of certain C types.  The OUTPUT section tells the compiler
1494 how to translate the values from certain C types into values Perl can
1495 understand.  The TYPEMAP section tells the compiler which of the INPUT and
1496 OUTPUT code fragments should be used to map a given C type to a Perl value.
1497 The section labels C<TYPEMAP>, C<INPUT>, or C<OUTPUT> must begin
1498 in the first column on a line by themselves, and must be in uppercase.
1499
1500 The default typemap in the C<ext> directory of the Perl source contains many
1501 useful types which can be used by Perl extensions.  Some extensions define
1502 additional typemaps which they keep in their own directory.  These
1503 additional typemaps may reference INPUT and OUTPUT maps in the main
1504 typemap.  The B<xsubpp> compiler will allow the extension's own typemap to
1505 override any mappings which are in the default typemap.
1506
1507 Most extensions which require a custom typemap will need only the TYPEMAP
1508 section of the typemap file.  The custom typemap used in the
1509 getnetconfigent() example shown earlier demonstrates what may be the typical
1510 use of extension typemaps.  That typemap is used to equate a C structure
1511 with the T_PTROBJ typemap.  The typemap used by getnetconfigent() is shown
1512 here.  Note that the C type is separated from the XS type with a tab and
1513 that the C unary operator C<*> is considered to be a part of the C type name.
1514
1515         TYPEMAP
1516         Netconfig *<tab>T_PTROBJ
1517
1518 Here's a more complicated example: suppose that you wanted C<struct
1519 netconfig> to be blessed into the class C<Net::Config>.  One way to do
1520 this is to use underscores (_) to separate package names, as follows:
1521
1522         typedef struct netconfig * Net_Config;
1523
1524 And then provide a typemap entry C<T_PTROBJ_SPECIAL> that maps underscores to
1525 double-colons (::), and declare C<Net_Config> to be of that type:
1526
1527
1528         TYPEMAP
1529         Net_Config      T_PTROBJ_SPECIAL
1530
1531         INPUT
1532         T_PTROBJ_SPECIAL
1533                 if (sv_derived_from($arg, \"${(my $ntt=$ntype)=~s/_/::/g;\$ntt}\")) {
1534                         IV tmp = SvIV((SV*)SvRV($arg));
1535                 $var = ($type) tmp;
1536                 }
1537                 else
1538                         croak(\"$var is not of type ${(my $ntt=$ntype)=~s/_/::/g;\$ntt}\")
1539
1540         OUTPUT
1541         T_PTROBJ_SPECIAL
1542                 sv_setref_pv($arg, \"${(my $ntt=$ntype)=~s/_/::/g;\$ntt}\",
1543                 (void*)$var);
1544
1545 The INPUT and OUTPUT sections substitute underscores for double-colons
1546 on the fly, giving the desired effect.  This example demonstrates some
1547 of the power and versatility of the typemap facility.
1548
1549 =head1 EXAMPLES
1550
1551 File C<RPC.xs>: Interface to some ONC+ RPC bind library functions.
1552
1553      #include "EXTERN.h"
1554      #include "perl.h"
1555      #include "XSUB.h"
1556
1557      #include <rpc/rpc.h>
1558
1559      typedef struct netconfig Netconfig;
1560
1561      MODULE = RPC  PACKAGE = RPC
1562
1563      SV *
1564      rpcb_gettime(host="localhost")
1565           char *host
1566         PREINIT:
1567           time_t  timep;
1568         CODE:
1569           ST(0) = sv_newmortal();
1570           if( rpcb_gettime( host, &timep ) )
1571                sv_setnv( ST(0), (double)timep );
1572
1573      Netconfig *
1574      getnetconfigent(netid="udp")
1575           char *netid
1576
1577      MODULE = RPC  PACKAGE = NetconfigPtr  PREFIX = rpcb_
1578
1579      void
1580      rpcb_DESTROY(netconf)
1581           Netconfig *netconf
1582         CODE:
1583           printf("NetconfigPtr::DESTROY\n");
1584           free( netconf );
1585
1586 File C<typemap>: Custom typemap for RPC.xs.
1587
1588      TYPEMAP
1589      Netconfig *  T_PTROBJ
1590
1591 File C<RPC.pm>: Perl module for the RPC extension.
1592
1593      package RPC;
1594
1595      require Exporter;
1596      require DynaLoader;
1597      @ISA = qw(Exporter DynaLoader);
1598      @EXPORT = qw(rpcb_gettime getnetconfigent);
1599
1600      bootstrap RPC;
1601      1;
1602
1603 File C<rpctest.pl>: Perl test program for the RPC extension.
1604
1605      use RPC;
1606
1607      $netconf = getnetconfigent();
1608      $a = rpcb_gettime();
1609      print "time = $a\n";
1610      print "netconf = $netconf\n";
1611
1612      $netconf = getnetconfigent("tcp");
1613      $a = rpcb_gettime("poplar");
1614      print "time = $a\n";
1615      print "netconf = $netconf\n";
1616
1617
1618 =head1 XS VERSION
1619
1620 This document covers features supported by C<xsubpp> 1.935.
1621
1622 =head1 AUTHOR
1623
1624 Originally written by Dean Roehrich <F<roehrich@cray.com>>.
1625
1626 Maintained since 1996 by The Perl Porters <F<perlbug@perl.com>>.