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