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