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