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