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