This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
generalize "%v" format into a flag for any integral format type:
[perl5.git] / pod / perlxs.pod
CommitLineData
a0d0e21e
LW
1=head1 NAME
2
8e07c86e 3perlxs - XS language reference manual
a0d0e21e
LW
4
5=head1 DESCRIPTION
6
7=head2 Introduction
8
beb31b0b
GS
9XS is an interface description file format used to create an extension
10interface between Perl and C code (or a C library) which one wishes
11to use with Perl. The XS interface is combined with the library to
12create a new library which can then be either dynamically loaded
13or statically linked into perl. The XS interface description is
14written in the XS language and is the core component of the Perl
15extension interface.
16
17An B<XSUB> forms the basic unit of the XS interface. After compilation
18by the B<xsubpp> compiler, each XSUB amounts to a C function definition
19which will provide the glue between Perl calling conventions and C
20calling conventions.
21
22The glue code pulls the arguments from the Perl stack, converts these
23Perl values to the formats expected by a C function, call this C function,
24transfers the return values of the C function back to Perl.
25Return values here may be a conventional C return value or any C
26function arguments that may serve as output parameters. These return
27values may be passed back to Perl either by putting them on the
28Perl stack, or by modifying the arguments supplied from the Perl side.
29
30The above is a somewhat simplified view of what really happens. Since
31Perl allows more flexible calling conventions than C, XSUBs may do much
32more in practice, such as checking input parameters for validity,
33throwing exceptions (or returning undef/empty list) if the return value
34from the C function indicates failure, calling different C functions
35based on numbers and types of the arguments, providing an object-oriented
36interface, etc.
37
38Of course, one could write such glue code directly in C. However, this
39would be a tedious task, especially if one needs to write glue for
40multiple C functions, and/or one is not familiar enough with the Perl
41stack discipline and other such arcana. XS comes to the rescue here:
42instead of writing this glue C code in long-hand, one can write
43a more concise short-hand I<description> of what should be done by
44the glue, and let the XS compiler B<xsubpp> handle the rest.
45
46The XS language allows one to describe the mapping between how the C
47routine is used, and how the corresponding Perl routine is used. It
48also allows creation of Perl routines which are directly translated to
49C code and which are not related to a pre-existing C function. In cases
50when the C interface coincides with the Perl interface, the XSUB
51declaration is almost identical to a declaration of a C function (in K&R
52style). In such circumstances, there is another tool called C<h2xs>
53that is able to translate an entire C header file into a corresponding
54XS file that will provide glue to the functions/macros described in
55the header file.
56
57The XS compiler is called B<xsubpp>. This compiler creates
58the constructs necessary to let an XSUB manipulate Perl values, and
59creates the glue necessary to let Perl call the XSUB. The compiler
a0d0e21e 60uses B<typemaps> to determine how to map C function parameters
beb31b0b
GS
61and output values to Perl values and back. The default typemap
62(which comes with Perl) handles many common C types. A supplementary
63typemap may also be needed to handle any special structures and types
64for the library being linked.
65
66A file in XS format starts with a C language section which goes until the
67first C<MODULE =Z<>> directive. Other XS directives and XSUB definitions
68may follow this line. The "language" used in this part of the file
69is usually referred to as the XS language.
a0d0e21e 70
cb1a09d0 71See L<perlxstut> for a tutorial on the whole extension creation process.
8e07c86e 72
beb31b0b
GS
73Note: For some extensions, Dave Beazley's SWIG system may provide a
74significantly more convenient mechanism for creating the extension glue
7b8d334a
GS
75code. See L<http://www.cs.utah.edu/~beazley/SWIG> for more
76information.
77
8e07c86e
AD
78=head2 On The Road
79
a5f75d66
AD
80Many of the examples which follow will concentrate on creating an interface
81between Perl and the ONC+ RPC bind library functions. The rpcb_gettime()
82function is used to demonstrate many features of the XS language. This
83function has two parameters; the first is an input parameter and the second
84is an output parameter. The function also returns a status value.
a0d0e21e
LW
85
86 bool_t rpcb_gettime(const char *host, time_t *timep);
87
88From C this function will be called with the following
89statements.
90
91 #include <rpc/rpc.h>
92 bool_t status;
93 time_t timep;
94 status = rpcb_gettime( "localhost", &timep );
95
96If an XSUB is created to offer a direct translation between this function
97and Perl, then this XSUB will be used from Perl with the following code.
98The $status and $timep variables will contain the output of the function.
99
100 use RPC;
101 $status = rpcb_gettime( "localhost", $timep );
102
103The following XS file shows an XS subroutine, or XSUB, which
104demonstrates one possible interface to the rpcb_gettime()
105function. This XSUB represents a direct translation between
106C and Perl and so preserves the interface even from Perl.
107This XSUB will be invoked from Perl with the usage shown
108above. Note that the first three #include statements, for
109C<EXTERN.h>, C<perl.h>, and C<XSUB.h>, will always be present at the
110beginning of an XS file. This approach and others will be
111expanded later in this document.
112
113 #include "EXTERN.h"
114 #include "perl.h"
115 #include "XSUB.h"
116 #include <rpc/rpc.h>
117
118 MODULE = RPC PACKAGE = RPC
119
120 bool_t
121 rpcb_gettime(host,timep)
8e07c86e
AD
122 char *host
123 time_t &timep
beb31b0b 124 OUTPUT:
a0d0e21e
LW
125 timep
126
127Any extension to Perl, including those containing XSUBs,
128should have a Perl module to serve as the bootstrap which
129pulls the extension into Perl. This module will export the
130extension's functions and variables to the Perl program and
131will cause the extension's XSUBs to be linked into Perl.
132The following module will be used for most of the examples
133in this document and should be used from Perl with the C<use>
134command as shown earlier. Perl modules are explained in
135more detail later in this document.
136
137 package RPC;
138
139 require Exporter;
140 require DynaLoader;
141 @ISA = qw(Exporter DynaLoader);
142 @EXPORT = qw( rpcb_gettime );
143
144 bootstrap RPC;
145 1;
146
147Throughout this document a variety of interfaces to the rpcb_gettime()
148XSUB will be explored. The XSUBs will take their parameters in different
149orders or will take different numbers of parameters. In each case the
150XSUB is an abstraction between Perl and the real C rpcb_gettime()
151function, and the XSUB must always ensure that the real rpcb_gettime()
152function is called with the correct parameters. This abstraction will
153allow the programmer to create a more Perl-like interface to the C
154function.
155
156=head2 The Anatomy of an XSUB
157
beb31b0b
GS
158The simplest XSUBs consist of 3 parts: a description of the return
159value, the name of the XSUB routine and the names of its arguments,
160and a description of types or formats of the arguments.
161
8e07c86e
AD
162The following XSUB allows a Perl program to access a C library function
163called sin(). The XSUB will imitate the C function which takes a single
164argument and returns a single value.
a0d0e21e
LW
165
166 double
167 sin(x)
8e07c86e 168 double x
a0d0e21e 169
beb31b0b
GS
170When using parameters with C pointer types, as in
171
172 double string_to_double(char *s);
173
174there may be two ways to describe this argument to B<xsubpp>:
175
176 char * s
177 char &s
178
179Both these XS declarations correspond to the C<char*> C type, but they have
180different semantics. It is convenient to think that the indirection operator
181C<*> should be considered as a part of the type and the address operator C<&>
182should be considered part of the variable. See L<"The Typemap"> and
183L<"The & Unary Operator"> for more info about handling qualifiers and unary
8e07c86e 184operators in C types.
a0d0e21e 185
a0d0e21e 186The function name and the return type must be placed on
beb31b0b 187separate lines and should be flush left-adjusted.
a0d0e21e
LW
188
189 INCORRECT CORRECT
190
191 double sin(x) double
8e07c86e
AD
192 double x sin(x)
193 double x
a0d0e21e 194
c07a80fd
PP
195The function body may be indented or left-adjusted. The following example
196shows a function with its body left-adjusted. Most examples in this
beb31b0b 197document will indent the body for better readability.
c07a80fd
PP
198
199 CORRECT
200
201 double
202 sin(x)
203 double x
204
beb31b0b
GS
205More complicated XSUBs may contain many other sections. Each section of
206an XSUB starts with the corresponding keyword, such as INIT: or CLEANUP:.
207However, the first two lines of an XSUB always contain the same data:
208descriptions of the return type and the names of the function and its
209parameters. Whatever immediately follows these is considered to be
210an INPUT: section unless explicitly marked with another keyword.
211(See L<The INPUT: Keyword>.)
212
213An XSUB section continues until another section-start keyword is found.
214
a0d0e21e
LW
215=head2 The Argument Stack
216
beb31b0b 217The Perl argument stack is used to store the values which are
a0d0e21e 218sent as parameters to the XSUB and to store the XSUB's
beb31b0b
GS
219return value(s). In reality all Perl functions (including non-XSUB
220ones) keep their values on this stack all the same time, each limited
221to its own range of positions on the stack. In this document the
a0d0e21e
LW
222first position on that stack which belongs to the active
223function will be referred to as position 0 for that function.
224
8e07c86e
AD
225XSUBs refer to their stack arguments with the macro B<ST(x)>, where I<x>
226refers to a position in this XSUB's part of the stack. Position 0 for that
a0d0e21e
LW
227function would be known to the XSUB as ST(0). The XSUB's incoming
228parameters and outgoing return values always begin at ST(0). For many
229simple cases the B<xsubpp> compiler will generate the code necessary to
230handle the argument stack by embedding code fragments found in the
231typemaps. In more complex cases the programmer must supply the code.
232
233=head2 The RETVAL Variable
234
beb31b0b
GS
235The RETVAL variable is a special C variable that is declared automatically
236for you. The C type of RETVAL matches the return type of the C library
237function. The B<xsubpp> compiler will declare this variable in each XSUB
238with non-C<void> return type. By default the generated C function
239will use RETVAL to hold the return value of the C library function being
240called. In simple cases the value of RETVAL will be placed in ST(0) of
241the argument stack where it can be received by Perl as the return value
242of the XSUB.
a0d0e21e
LW
243
244If the XSUB has a return type of C<void> then the compiler will
beb31b0b
GS
245not declare a RETVAL variable for that function. When using
246a PPCODE: section no manipulation of the RETVAL variable is required, the
247section may use direct stack manipulation to place output values on the stack.
e7ea3e70
IZ
248
249If PPCODE: directive is not used, C<void> return value should be used
250only for subroutines which do not return a value, I<even if> CODE:
54310121 251directive is used which sets ST(0) explicitly.
e7ea3e70
IZ
252
253Older versions of this document recommended to use C<void> return
254value in such cases. It was discovered that this could lead to
c2611fb3 255segfaults in cases when XSUB was I<truly> C<void>. This practice is
e7ea3e70
IZ
256now deprecated, and may be not supported at some future version. Use
257the return value C<SV *> in such cases. (Currently C<xsubpp> contains
c2611fb3 258some heuristic code which tries to disambiguate between "truly-void"
e7ea3e70
IZ
259and "old-practice-declared-as-void" functions. Hence your code is at
260mercy of this heuristics unless you use C<SV *> as return value.)
a0d0e21e
LW
261
262=head2 The MODULE Keyword
263
264The MODULE keyword is used to start the XS code and to
265specify the package of the functions which are being
266defined. All text preceding the first MODULE keyword is
267considered C code and is passed through to the output
268untouched. Every XS module will have a bootstrap function
269which is used to hook the XSUBs into Perl. The package name
270of this bootstrap function will match the value of the last
271MODULE statement in the XS source files. The value of
272MODULE should always remain constant within the same XS
273file, though this is not required.
274
275The following example will start the XS code and will place
276all functions in a package named RPC.
277
278 MODULE = RPC
279
280=head2 The PACKAGE Keyword
281
282When functions within an XS source file must be separated into packages
283the PACKAGE keyword should be used. This keyword is used with the MODULE
284keyword and must follow immediately after it when used.
285
286 MODULE = RPC PACKAGE = RPC
287
288 [ XS code in package RPC ]
289
290 MODULE = RPC PACKAGE = RPCB
291
292 [ XS code in package RPCB ]
293
294 MODULE = RPC PACKAGE = RPC
295
296 [ XS code in package RPC ]
297
298Although this keyword is optional and in some cases provides redundant
299information it should always be used. This keyword will ensure that the
300XSUBs appear in the desired package.
301
302=head2 The PREFIX Keyword
303
304The PREFIX keyword designates prefixes which should be
305removed from the Perl function names. If the C function is
306C<rpcb_gettime()> and the PREFIX value is C<rpcb_> then Perl will
307see this function as C<gettime()>.
308
309This keyword should follow the PACKAGE keyword when used.
310If PACKAGE is not used then PREFIX should follow the MODULE
311keyword.
312
313 MODULE = RPC PREFIX = rpc_
314
315 MODULE = RPC PACKAGE = RPCB PREFIX = rpcb_
316
317=head2 The OUTPUT: Keyword
318
319The OUTPUT: keyword indicates that certain function parameters should be
320updated (new values made visible to Perl) when the XSUB terminates or that
321certain values should be returned to the calling Perl function. For
beb31b0b
GS
322simple functions which have no CODE: or PPCODE: section,
323such as the sin() function above, the RETVAL variable is
324automatically designated as an output value. For more complex functions
a0d0e21e
LW
325the B<xsubpp> compiler will need help to determine which variables are output
326variables.
327
328This keyword will normally be used to complement the CODE: keyword.
329The RETVAL variable is not recognized as an output variable when the
330CODE: keyword is present. The OUTPUT: keyword is used in this
331situation to tell the compiler that RETVAL really is an output
332variable.
333
334The OUTPUT: keyword can also be used to indicate that function parameters
335are output variables. This may be necessary when a parameter has been
336modified within the function and the programmer would like the update to
8e07c86e 337be seen by Perl.
a0d0e21e
LW
338
339 bool_t
340 rpcb_gettime(host,timep)
8e07c86e
AD
341 char *host
342 time_t &timep
beb31b0b 343 OUTPUT:
a0d0e21e
LW
344 timep
345
346The OUTPUT: keyword will also allow an output parameter to
347be mapped to a matching piece of code rather than to a
ef50df4b 348typemap.
a0d0e21e
LW
349
350 bool_t
351 rpcb_gettime(host,timep)
8e07c86e
AD
352 char *host
353 time_t &timep
beb31b0b 354 OUTPUT:
ef50df4b
GS
355 timep sv_setnv(ST(1), (double)timep);
356
357B<xsubpp> emits an automatic C<SvSETMAGIC()> for all parameters in the
358OUTPUT section of the XSUB, except RETVAL. This is the usually desired
359behavior, as it takes care of properly invoking 'set' magic on output
360parameters (needed for hash or array element parameters that must be
361created if they didn't exist). If for some reason, this behavior is
362not desired, the OUTPUT section may contain a C<SETMAGIC: DISABLE> line
363to disable it for the remainder of the parameters in the OUTPUT section.
364Likewise, C<SETMAGIC: ENABLE> can be used to reenable it for the
365remainder of the OUTPUT section. See L<perlguts> for more details
366about 'set' magic.
a0d0e21e
LW
367
368=head2 The CODE: Keyword
369
370This keyword is used in more complicated XSUBs which require
371special handling for the C function. The RETVAL variable is
beb31b0b
GS
372still declared, but it will not be returned unless it is specified
373in the OUTPUT: section.
a0d0e21e
LW
374
375The following XSUB is for a C function which requires special handling of
376its parameters. The Perl usage is given first.
377
378 $status = rpcb_gettime( "localhost", $timep );
379
54310121 380The XSUB follows.
a0d0e21e 381
d1b91892
AD
382 bool_t
383 rpcb_gettime(host,timep)
8e07c86e
AD
384 char *host
385 time_t timep
beb31b0b 386 CODE:
a0d0e21e 387 RETVAL = rpcb_gettime( host, &timep );
beb31b0b 388 OUTPUT:
a0d0e21e
LW
389 timep
390 RETVAL
391
c07a80fd
PP
392=head2 The INIT: Keyword
393
394The INIT: keyword allows initialization to be inserted into the XSUB before
395the compiler generates the call to the C function. Unlike the CODE: keyword
396above, this keyword does not affect the way the compiler handles RETVAL.
397
398 bool_t
399 rpcb_gettime(host,timep)
400 char *host
401 time_t &timep
beb31b0b 402 INIT:
c07a80fd 403 printf("# Host is %s\n", host );
beb31b0b 404 OUTPUT:
c07a80fd 405 timep
a0d0e21e 406
beb31b0b
GS
407Another use for the INIT: section is to check for preconditions before
408making a call to the C function:
409
410 long long
411 lldiv(a,b)
412 long long a
413 long long b
414 INIT:
415 if (a == 0 && b == 0)
416 XSRETURN_UNDEF;
417 if (b == 0)
418 croak("lldiv: cannot divide by 0");
419
a0d0e21e
LW
420=head2 The NO_INIT Keyword
421
422The NO_INIT keyword is used to indicate that a function
54310121 423parameter is being used only as an output value. The B<xsubpp>
a0d0e21e
LW
424compiler will normally generate code to read the values of
425all function parameters from the argument stack and assign
426them to C variables upon entry to the function. NO_INIT
427will tell the compiler that some parameters will be used for
428output rather than for input and that they will be handled
429before the function terminates.
430
431The following example shows a variation of the rpcb_gettime() function.
54310121 432This function uses the timep variable only as an output variable and does
a0d0e21e
LW
433not care about its initial contents.
434
435 bool_t
436 rpcb_gettime(host,timep)
8e07c86e
AD
437 char *host
438 time_t &timep = NO_INIT
beb31b0b 439 OUTPUT:
a0d0e21e
LW
440 timep
441
442=head2 Initializing Function Parameters
443
beb31b0b
GS
444C function parameters are normally initialized with their values from
445the argument stack (which in turn contains the parameters that were
446passed to the XSUB from Perl). The typemaps contain the
447code segments which are used to translate the Perl values to
a0d0e21e 448the C parameters. The programmer, however, is allowed to
7ad6fb0b 449override the typemaps and supply alternate (or additional)
beb31b0b
GS
450initialization code. Initialization code starts with the first
451C<=>, C<;> or C<+> on a line in the INPUT: section. The only
452exception happens if this C<;> terminates the line, then this C<;>
453is quietly ignored.
a0d0e21e
LW
454
455The following code demonstrates how to supply initialization code for
7ad6fb0b
TM
456function parameters. The initialization code is eval'd within double
457quotes by the compiler before it is added to the output so anything
458which should be interpreted literally [mainly C<$>, C<@>, or C<\\>]
19799a22
GS
459must be protected with backslashes. The variables $var, $arg,
460and $type can be used as in typemaps.
a0d0e21e
LW
461
462 bool_t
463 rpcb_gettime(host,timep)
9cde0e7f 464 char *host = (char *)SvPV($arg,PL_na);
8e07c86e 465 time_t &timep = 0;
beb31b0b 466 OUTPUT:
a0d0e21e
LW
467 timep
468
469This should not be used to supply default values for parameters. One
470would normally use this when a function parameter must be processed by
471another library function before it can be used. Default parameters are
472covered in the next section.
473
beb31b0b
GS
474If the initialization begins with C<=>, then it is output in
475the declaration for the input variable, replacing the initialization
476supplied by the typemap. If the initialization
477begins with C<;> or C<+>, then it is performed after
478all of the input variables have been declared. In the C<;>
479case the initialization normally supplied by the typemap is not performed.
480For the C<+> case, the declaration for the variable will include the
481initialization from the typemap. A global
c2611fb3 482variable, C<%v>, is available for the truly rare case where
7ad6fb0b
TM
483information from one initialization is needed in another
484initialization.
485
beb31b0b
GS
486Here's a truly obscure example:
487
7ad6fb0b
TM
488 bool_t
489 rpcb_gettime(host,timep)
beb31b0b
GS
490 time_t &timep ; /* \$v{timep}=@{[$v{timep}=$arg]} */
491 char *host + SvOK($v{timep}) ? SvPV($arg,PL_na) : NULL;
492 OUTPUT:
7ad6fb0b
TM
493 timep
494
beb31b0b
GS
495The construct C<\$v{timep}=@{[$v{timep}=$arg]}> used in the above
496example has a two-fold purpose: first, when this line is processed by
497B<xsubpp>, the Perl snippet C<$v{timep}=$arg> is evaluated. Second,
498the text of the evaluated snippet is output into the generated C file
499(inside a C comment)! During the processing of C<char *host> line,
500$arg will evaluate to C<ST(0)>, and C<$v{timep}> will evaluate to
501C<ST(1)>.
502
a0d0e21e
LW
503=head2 Default Parameter Values
504
beb31b0b 505Default values for XSUB arguments can be specified by
a0d0e21e
LW
506placing an assignment statement in the parameter list. The
507default value may be a number or a string. Defaults should
508always be used on the right-most parameters only.
509
510To allow the XSUB for rpcb_gettime() to have a default host
511value the parameters to the XSUB could be rearranged. The
512XSUB will then call the real rpcb_gettime() function with
beb31b0b
GS
513the parameters in the correct order. This XSUB can be called
514from Perl with either of the following statements:
a0d0e21e
LW
515
516 $status = rpcb_gettime( $timep, $host );
517
518 $status = rpcb_gettime( $timep );
519
520The XSUB will look like the code which follows. A CODE:
521block is used to call the real rpcb_gettime() function with
522the parameters in the correct order for that function.
523
524 bool_t
525 rpcb_gettime(timep,host="localhost")
8e07c86e
AD
526 char *host
527 time_t timep = NO_INIT
beb31b0b 528 CODE:
a0d0e21e 529 RETVAL = rpcb_gettime( host, &timep );
beb31b0b 530 OUTPUT:
a0d0e21e
LW
531 timep
532 RETVAL
533
c07a80fd
PP
534=head2 The PREINIT: Keyword
535
beb31b0b
GS
536The PREINIT: keyword allows extra variables to be declared immediately
537before or after the declartions of the parameters from the INPUT: section
538are emitted.
539
540If a variable is declared inside a CODE: section it will follow any typemap
541code that is emitted for the input parameters. This may result in the
542declaration ending up after C code, which is C syntax error. Similar
543errors may happen with an explicit C<;>-type or C<+>-type initialization of
544parameters is used (see L<"Initializing Function Parameters">). Declaring
545these variables in an INIT: section will not help.
546
547In such cases, to force an additional variable to be declared together
548with declarations of other variables, place the declaration into a
549PREINIT: section. The PREINIT: keyword may be used one or more times
550within an XSUB.
c07a80fd
PP
551
552The following examples are equivalent, but if the code is using complex
553typemaps then the first example is safer.
554
555 bool_t
556 rpcb_gettime(timep)
557 time_t timep = NO_INIT
beb31b0b 558 PREINIT:
c07a80fd 559 char *host = "localhost";
beb31b0b 560 CODE:
c07a80fd 561 RETVAL = rpcb_gettime( host, &timep );
beb31b0b 562 OUTPUT:
c07a80fd
PP
563 timep
564 RETVAL
565
beb31b0b
GS
566For this particular case an INIT: keyword would generate the
567same C code as the PREINIT: keyword. Another correct, but error-prone example:
c07a80fd
PP
568
569 bool_t
570 rpcb_gettime(timep)
571 time_t timep = NO_INIT
beb31b0b 572 CODE:
c07a80fd
PP
573 char *host = "localhost";
574 RETVAL = rpcb_gettime( host, &timep );
beb31b0b
GS
575 OUTPUT:
576 timep
577 RETVAL
578
579Another way to declare C<host> is to use a C block in the CODE: section:
580
581 bool_t
582 rpcb_gettime(timep)
583 time_t timep = NO_INIT
584 CODE:
585 {
586 char *host = "localhost";
587 RETVAL = rpcb_gettime( host, &timep );
588 }
589 OUTPUT:
590 timep
591 RETVAL
592
593The ability to put additional declarations before the typemap entries are
594processed is very handy in the cases when typemap conversions manipulate
595some global state:
596
597 MyObject
598 mutate(o)
599 PREINIT:
600 MyState st = global_state;
601 INPUT:
602 MyObject o;
603 CLEANUP:
604 reset_to(global_state, st);
605
606Here we suppose that conversion to C<MyObject> in the INPUT: section and from
607MyObject when processing RETVAL will modify a global variable C<global_state>.
608After these conversions are performed, we restore the old value of
609C<global_state> (to avoid memory leaks, for example).
610
611There is another way to trade clarity for compactness: INPUT sections allow
612declaration of C variables which do not appear in the parameter list of
613a subroutine. Thus the above code for mutate() can be rewritten as
614
615 MyObject
616 mutate(o)
617 MyState st = global_state;
618 MyObject o;
619 CLEANUP:
620 reset_to(global_state, st);
621
622and the code for rpcb_gettime() can be rewritten as
623
624 bool_t
625 rpcb_gettime(timep)
626 time_t timep = NO_INIT
627 char *host = "localhost";
628 C_ARGS:
629 host, &timep
630 OUTPUT:
c07a80fd
PP
631 timep
632 RETVAL
633
84287afe
PP
634=head2 The SCOPE: Keyword
635
636The SCOPE: keyword allows scoping to be enabled for a particular XSUB. If
637enabled, the XSUB will invoke ENTER and LEAVE automatically.
638
639To support potentially complex type mappings, if a typemap entry used
beb31b0b
GS
640by an XSUB contains a comment like C</*scope*/> then scoping will
641be automatically enabled for that XSUB.
84287afe
PP
642
643To enable scoping:
644
645 SCOPE: ENABLE
646
647To disable scoping:
648
649 SCOPE: DISABLE
650
c07a80fd
PP
651=head2 The INPUT: Keyword
652
653The XSUB's parameters are usually evaluated immediately after entering the
654XSUB. The INPUT: keyword can be used to force those parameters to be
655evaluated a little later. The INPUT: keyword can be used multiple times
656within an XSUB and can be used to list one or more input variables. This
657keyword is used with the PREINIT: keyword.
658
659The following example shows how the input parameter C<timep> can be
660evaluated late, after a PREINIT.
661
662 bool_t
663 rpcb_gettime(host,timep)
664 char *host
beb31b0b 665 PREINIT:
c07a80fd 666 time_t tt;
beb31b0b 667 INPUT:
c07a80fd 668 time_t timep
beb31b0b 669 CODE:
c07a80fd
PP
670 RETVAL = rpcb_gettime( host, &tt );
671 timep = tt;
beb31b0b 672 OUTPUT:
c07a80fd
PP
673 timep
674 RETVAL
675
676The next example shows each input parameter evaluated late.
677
678 bool_t
679 rpcb_gettime(host,timep)
beb31b0b 680 PREINIT:
c07a80fd 681 time_t tt;
beb31b0b 682 INPUT:
c07a80fd 683 char *host
beb31b0b 684 PREINIT:
c07a80fd 685 char *h;
beb31b0b 686 INPUT:
c07a80fd 687 time_t timep
beb31b0b 688 CODE:
c07a80fd
PP
689 h = host;
690 RETVAL = rpcb_gettime( h, &tt );
691 timep = tt;
beb31b0b
GS
692 OUTPUT:
693 timep
694 RETVAL
695
696Since INPUT sections allow declaration of C variables which do not appear
697in the parameter list of a subroutine, this may be shortened to:
698
699 bool_t
700 rpcb_gettime(host,timep)
701 time_t tt;
702 char *host;
703 char *h = host;
704 time_t timep;
705 CODE:
706 RETVAL = rpcb_gettime( h, &tt );
707 timep = tt;
708 OUTPUT:
c07a80fd
PP
709 timep
710 RETVAL
711
beb31b0b
GS
712(We used our knowledge that input conversion for C<char *> is a "simple" one,
713thus C<host> is initialized on the declaration line, and our assignment
714C<h = host> is not performed too early. Otherwise one would need to have the
715assignment C<h = host> in a CODE: or INIT: section.)
716
a0d0e21e
LW
717=head2 Variable-length Parameter Lists
718
719XSUBs can have variable-length parameter lists by specifying an ellipsis
720C<(...)> in the parameter list. This use of the ellipsis is similar to that
721found in ANSI C. The programmer is able to determine the number of
722arguments passed to the XSUB by examining the C<items> variable which the
723B<xsubpp> compiler supplies for all XSUBs. By using this mechanism one can
724create an XSUB which accepts a list of parameters of unknown length.
725
726The I<host> parameter for the rpcb_gettime() XSUB can be
727optional so the ellipsis can be used to indicate that the
728XSUB will take a variable number of parameters. Perl should
d1b91892 729be able to call this XSUB with either of the following statements.
a0d0e21e
LW
730
731 $status = rpcb_gettime( $timep, $host );
732
733 $status = rpcb_gettime( $timep );
734
735The XS code, with ellipsis, follows.
736
737 bool_t
738 rpcb_gettime(timep, ...)
8e07c86e 739 time_t timep = NO_INIT
beb31b0b 740 PREINIT:
a0d0e21e 741 char *host = "localhost";
2d8e6c8d 742 STRLEN n_a;
beb31b0b
GS
743 CODE:
744 if( items > 1 )
745 host = (char *)SvPV(ST(1), n_a);
746 RETVAL = rpcb_gettime( host, &timep );
747 OUTPUT:
a0d0e21e
LW
748 timep
749 RETVAL
750
cfc02341
IZ
751=head2 The C_ARGS: Keyword
752
753The C_ARGS: keyword allows creating of XSUBS which have different
754calling sequence from Perl than from C, without a need to write
beb31b0b 755CODE: or PPCODE: section. The contents of the C_ARGS: paragraph is
cfc02341
IZ
756put as the argument to the called C function without any change.
757
beb31b0b 758For example, suppose that a C function is declared as
cfc02341
IZ
759
760 symbolic nth_derivative(int n, symbolic function, int flags);
761
762and that the default flags are kept in a global C variable
763C<default_flags>. Suppose that you want to create an interface which
764is called as
765
766 $second_deriv = $function->nth_derivative(2);
767
768To do this, declare the XSUB as
769
770 symbolic
771 nth_derivative(function, n)
772 symbolic function
773 int n
beb31b0b 774 C_ARGS:
cfc02341
IZ
775 n, function, default_flags
776
a0d0e21e
LW
777=head2 The PPCODE: Keyword
778
779The PPCODE: keyword is an alternate form of the CODE: keyword and is used
780to tell the B<xsubpp> compiler that the programmer is supplying the code to
d1b91892 781control the argument stack for the XSUBs return values. Occasionally one
a0d0e21e
LW
782will want an XSUB to return a list of values rather than a single value.
783In these cases one must use PPCODE: and then explicitly push the list of
beb31b0b 784values on the stack. The PPCODE: and CODE: keywords should not be used
a0d0e21e
LW
785together within the same XSUB.
786
beb31b0b
GS
787The actual difference between PPCODE: and CODE: sections is in the
788initialization of C<SP> macro (which stands for the I<current> Perl
789stack pointer), and in the handling of data on the stack when returning
790from an XSUB. In CODE: sections SP preserves the value which was on
791entry to the XSUB: SP is on the function pointer (which follows the
792last parameter). In PPCODE: sections SP is moved backward to the
793beginning of the parameter list, which allows C<PUSH*()> macros
794to place output values in the place Perl expects them to be when
795the XSUB returns back to Perl.
796
797The generated trailer for a CODE: section ensures that the number of return
798values Perl will see is either 0 or 1 (depending on the C<void>ness of the
799return value of the C function, and heuristics mentioned in
800L<"The RETVAL Variable">). The trailer generated for a PPCODE: section
801is based on the number of return values and on the number of times
802C<SP> was updated by C<[X]PUSH*()> macros.
803
804Note that macros C<ST(i)>, C<XST_m*()> and C<XSRETURN*()> work equally
805well in CODE: sections and PPCODE: sections.
806
a0d0e21e
LW
807The following XSUB will call the C rpcb_gettime() function
808and will return its two output values, timep and status, to
809Perl as a single list.
810
d1b91892
AD
811 void
812 rpcb_gettime(host)
8e07c86e 813 char *host
beb31b0b 814 PREINIT:
a0d0e21e
LW
815 time_t timep;
816 bool_t status;
beb31b0b 817 PPCODE:
a0d0e21e 818 status = rpcb_gettime( host, &timep );
924508f0 819 EXTEND(SP, 2);
cb1a09d0
AD
820 PUSHs(sv_2mortal(newSViv(status)));
821 PUSHs(sv_2mortal(newSViv(timep)));
a0d0e21e
LW
822
823Notice that the programmer must supply the C code necessary
824to have the real rpcb_gettime() function called and to have
825the return values properly placed on the argument stack.
826
827The C<void> return type for this function tells the B<xsubpp> compiler that
828the RETVAL variable is not needed or used and that it should not be created.
829In most scenarios the void return type should be used with the PPCODE:
830directive.
831
832The EXTEND() macro is used to make room on the argument
833stack for 2 return values. The PPCODE: directive causes the
924508f0 834B<xsubpp> compiler to create a stack pointer available as C<SP>, and it
a0d0e21e
LW
835is this pointer which is being used in the EXTEND() macro.
836The values are then pushed onto the stack with the PUSHs()
837macro.
838
839Now the rpcb_gettime() function can be used from Perl with
840the following statement.
841
842 ($status, $timep) = rpcb_gettime("localhost");
843
ef50df4b
GS
844When handling output parameters with a PPCODE section, be sure to handle
845'set' magic properly. See L<perlguts> for details about 'set' magic.
846
a0d0e21e
LW
847=head2 Returning Undef And Empty Lists
848
5f05dabc 849Occasionally the programmer will want to return simply
a0d0e21e
LW
850C<undef> or an empty list if a function fails rather than a
851separate status value. The rpcb_gettime() function offers
852just this situation. If the function succeeds we would like
853to have it return the time and if it fails we would like to
854have undef returned. In the following Perl code the value
855of $timep will either be undef or it will be a valid time.
856
857 $timep = rpcb_gettime( "localhost" );
858
7b8d334a 859The following XSUB uses the C<SV *> return type as a mnemonic only,
e7ea3e70 860and uses a CODE: block to indicate to the compiler
a0d0e21e
LW
861that the programmer has supplied all the necessary code. The
862sv_newmortal() call will initialize the return value to undef, making that
863the default return value.
864
e7ea3e70 865 SV *
a0d0e21e
LW
866 rpcb_gettime(host)
867 char * host
beb31b0b 868 PREINIT:
a0d0e21e
LW
869 time_t timep;
870 bool_t x;
beb31b0b 871 CODE:
a0d0e21e
LW
872 ST(0) = sv_newmortal();
873 if( rpcb_gettime( host, &timep ) )
874 sv_setnv( ST(0), (double)timep);
a0d0e21e
LW
875
876The next example demonstrates how one would place an explicit undef in the
877return value, should the need arise.
878
e7ea3e70 879 SV *
a0d0e21e
LW
880 rpcb_gettime(host)
881 char * host
beb31b0b 882 PREINIT:
a0d0e21e
LW
883 time_t timep;
884 bool_t x;
beb31b0b 885 CODE:
a0d0e21e
LW
886 ST(0) = sv_newmortal();
887 if( rpcb_gettime( host, &timep ) ){
888 sv_setnv( ST(0), (double)timep);
889 }
890 else{
9cde0e7f 891 ST(0) = &PL_sv_undef;
a0d0e21e 892 }
a0d0e21e
LW
893
894To return an empty list one must use a PPCODE: block and
895then not push return values on the stack.
896
897 void
898 rpcb_gettime(host)
8e07c86e 899 char *host
beb31b0b 900 PREINIT:
a0d0e21e 901 time_t timep;
beb31b0b 902 PPCODE:
a0d0e21e 903 if( rpcb_gettime( host, &timep ) )
cb1a09d0 904 PUSHs(sv_2mortal(newSViv(timep)));
a0d0e21e 905 else{
beb31b0b
GS
906 /* Nothing pushed on stack, so an empty
907 * list is implicitly returned. */
a0d0e21e 908 }
a0d0e21e 909
f27cfbbe
PP
910Some people may be inclined to include an explicit C<return> in the above
911XSUB, rather than letting control fall through to the end. In those
912situations C<XSRETURN_EMPTY> should be used, instead. This will ensure that
913the XSUB stack is properly adjusted. Consult L<perlguts/"API LISTING"> for
914other C<XSRETURN> macros.
915
beb31b0b
GS
916Since C<XSRETURN_*> macros can be used with CODE blocks as well, one can
917rewrite this example as:
918
919 int
920 rpcb_gettime(host)
921 char *host
922 PREINIT:
923 time_t timep;
924 CODE:
925 RETVAL = rpcb_gettime( host, &timep );
926 if (RETVAL == 0)
927 XSRETURN_UNDEF;
928 OUTPUT:
929 RETVAL
930
931In fact, one can put this check into a CLEANUP: section as well. Together
932with PREINIT: simplifications, this leads to:
933
934 int
935 rpcb_gettime(host)
936 char *host
937 time_t timep;
938 CLEANUP:
939 if (RETVAL == 0)
940 XSRETURN_UNDEF;
941
4633a7c4
LW
942=head2 The REQUIRE: Keyword
943
944The REQUIRE: keyword is used to indicate the minimum version of the
945B<xsubpp> compiler needed to compile the XS module. An XS module which
5f05dabc 946contains the following statement will compile with only B<xsubpp> version
4633a7c4
LW
9471.922 or greater:
948
949 REQUIRE: 1.922
950
a0d0e21e
LW
951=head2 The CLEANUP: Keyword
952
953This keyword can be used when an XSUB requires special cleanup procedures
954before it terminates. When the CLEANUP: keyword is used it must follow
955any CODE:, PPCODE:, or OUTPUT: blocks which are present in the XSUB. The
956code specified for the cleanup block will be added as the last statements
957in the XSUB.
958
959=head2 The BOOT: Keyword
960
961The BOOT: keyword is used to add code to the extension's bootstrap
962function. The bootstrap function is generated by the B<xsubpp> compiler and
963normally holds the statements necessary to register any XSUBs with Perl.
964With the BOOT: keyword the programmer can tell the compiler to add extra
965statements to the bootstrap function.
966
967This keyword may be used any time after the first MODULE keyword and should
968appear on a line by itself. The first blank line after the keyword will
969terminate the code block.
970
971 BOOT:
972 # The following message will be printed when the
973 # bootstrap function executes.
974 printf("Hello from the bootstrap!\n");
975
c07a80fd
PP
976=head2 The VERSIONCHECK: Keyword
977
978The VERSIONCHECK: keyword corresponds to B<xsubpp>'s C<-versioncheck> and
5f05dabc 979C<-noversioncheck> options. This keyword overrides the command line
c07a80fd
PP
980options. Version checking is enabled by default. When version checking is
981enabled the XS module will attempt to verify that its version matches the
982version of the PM module.
983
984To enable version checking:
985
986 VERSIONCHECK: ENABLE
987
988To disable version checking:
989
990 VERSIONCHECK: DISABLE
991
992=head2 The PROTOTYPES: Keyword
993
994The PROTOTYPES: keyword corresponds to B<xsubpp>'s C<-prototypes> and
54310121 995C<-noprototypes> options. This keyword overrides the command line options.
c07a80fd
PP
996Prototypes are enabled by default. When prototypes are enabled XSUBs will
997be given Perl prototypes. This keyword may be used multiple times in an XS
998module to enable and disable prototypes for different parts of the module.
999
1000To enable prototypes:
1001
1002 PROTOTYPES: ENABLE
1003
1004To disable prototypes:
1005
1006 PROTOTYPES: DISABLE
1007
1008=head2 The PROTOTYPE: Keyword
1009
1010This keyword is similar to the PROTOTYPES: keyword above but can be used to
1011force B<xsubpp> to use a specific prototype for the XSUB. This keyword
1012overrides all other prototype options and keywords but affects only the
1013current XSUB. Consult L<perlsub/Prototypes> for information about Perl
1014prototypes.
1015
1016 bool_t
1017 rpcb_gettime(timep, ...)
1018 time_t timep = NO_INIT
beb31b0b
GS
1019 PROTOTYPE: $;$
1020 PREINIT:
c07a80fd 1021 char *host = "localhost";
2d8e6c8d 1022 STRLEN n_a;
beb31b0b 1023 CODE:
c07a80fd 1024 if( items > 1 )
2d8e6c8d 1025 host = (char *)SvPV(ST(1), n_a);
c07a80fd 1026 RETVAL = rpcb_gettime( host, &timep );
beb31b0b 1027 OUTPUT:
c07a80fd
PP
1028 timep
1029 RETVAL
1030
1031=head2 The ALIAS: Keyword
1032
cfc02341 1033The ALIAS: keyword allows an XSUB to have two or more unique Perl names
c07a80fd
PP
1034and to know which of those names was used when it was invoked. The Perl
1035names may be fully-qualified with package names. Each alias is given an
1036index. The compiler will setup a variable called C<ix> which contain the
1037index of the alias which was used. When the XSUB is called with its
1038declared name C<ix> will be 0.
1039
1040The following example will create aliases C<FOO::gettime()> and
1041C<BAR::getit()> for this function.
1042
1043 bool_t
1044 rpcb_gettime(host,timep)
1045 char *host
1046 time_t &timep
beb31b0b 1047 ALIAS:
c07a80fd
PP
1048 FOO::gettime = 1
1049 BAR::getit = 2
beb31b0b 1050 INIT:
c07a80fd 1051 printf("# ix = %d\n", ix );
beb31b0b 1052 OUTPUT:
c07a80fd
PP
1053 timep
1054
cfc02341
IZ
1055=head2 The INTERFACE: Keyword
1056
1057This keyword declares the current XSUB as a keeper of the given
1058calling signature. If some text follows this keyword, it is
1059considered as a list of functions which have this signature, and
beb31b0b 1060should be attached to the current XSUB.
cfc02341 1061
beb31b0b
GS
1062For example, if you have 4 C functions multiply(), divide(), add(),
1063subtract() all having the signature:
cfc02341
IZ
1064
1065 symbolic f(symbolic, symbolic);
1066
beb31b0b 1067you can make them all to use the same XSUB using this:
cfc02341
IZ
1068
1069 symbolic
1070 interface_s_ss(arg1, arg2)
1071 symbolic arg1
1072 symbolic arg2
1073 INTERFACE:
1074 multiply divide
1075 add subtract
1076
beb31b0b
GS
1077(This is the complete XSUB code for 4 Perl functions!) Four generated
1078Perl function share names with corresponding C functions.
1079
1080The advantage of this approach comparing to ALIAS: keyword is that there
1081is no need to code a switch statement, each Perl function (which shares
1082the same XSUB) knows which C function it should call. Additionally, one
cfc02341 1083can attach an extra function remainder() at runtime by using
beb31b0b 1084
cfc02341
IZ
1085 CV *mycv = newXSproto("Symbolic::remainder",
1086 XS_Symbolic_interface_s_ss, __FILE__, "$$");
1087 XSINTERFACE_FUNC_SET(mycv, remainder);
1088
beb31b0b
GS
1089say, from another XSUB. (This example supposes that there was no
1090INTERFACE_MACRO: section, otherwise one needs to use something else instead of
1091C<XSINTERFACE_FUNC_SET>, see the next section.)
cfc02341
IZ
1092
1093=head2 The INTERFACE_MACRO: Keyword
1094
1095This keyword allows one to define an INTERFACE using a different way
1096to extract a function pointer from an XSUB. The text which follows
1097this keyword should give the name of macros which would extract/set a
1098function pointer. The extractor macro is given return type, C<CV*>,
1099and C<XSANY.any_dptr> for this C<CV*>. The setter macro is given cv,
1100and the function pointer.
1101
1102The default value is C<XSINTERFACE_FUNC> and C<XSINTERFACE_FUNC_SET>.
1103An INTERFACE keyword with an empty list of functions can be omitted if
1104INTERFACE_MACRO keyword is used.
1105
1106Suppose that in the previous example functions pointers for
1107multiply(), divide(), add(), subtract() are kept in a global C array
1108C<fp[]> with offsets being C<multiply_off>, C<divide_off>, C<add_off>,
1109C<subtract_off>. Then one can use
1110
1111 #define XSINTERFACE_FUNC_BYOFFSET(ret,cv,f) \
1112 ((XSINTERFACE_CVT(ret,))fp[CvXSUBANY(cv).any_i32])
1113 #define XSINTERFACE_FUNC_BYOFFSET_set(cv,f) \
1114 CvXSUBANY(cv).any_i32 = CAT2( f, _off )
1115
1116in C section,
1117
1118 symbolic
1119 interface_s_ss(arg1, arg2)
1120 symbolic arg1
1121 symbolic arg2
beb31b0b 1122 INTERFACE_MACRO:
cfc02341
IZ
1123 XSINTERFACE_FUNC_BYOFFSET
1124 XSINTERFACE_FUNC_BYOFFSET_set
beb31b0b 1125 INTERFACE:
cfc02341
IZ
1126 multiply divide
1127 add subtract
1128
1129in XSUB section.
1130
c07a80fd
PP
1131=head2 The INCLUDE: Keyword
1132
1133This keyword can be used to pull other files into the XS module. The other
1134files may have XS code. INCLUDE: can also be used to run a command to
1135generate the XS code to be pulled into the module.
1136
1137The file F<Rpcb1.xsh> contains our C<rpcb_gettime()> function:
1138
1139 bool_t
1140 rpcb_gettime(host,timep)
1141 char *host
1142 time_t &timep
beb31b0b 1143 OUTPUT:
c07a80fd
PP
1144 timep
1145
1146The XS module can use INCLUDE: to pull that file into it.
1147
1148 INCLUDE: Rpcb1.xsh
1149
1150If the parameters to the INCLUDE: keyword are followed by a pipe (C<|>) then
1151the compiler will interpret the parameters as a command.
1152
1153 INCLUDE: cat Rpcb1.xsh |
1154
1155=head2 The CASE: Keyword
1156
1157The CASE: keyword allows an XSUB to have multiple distinct parts with each
1158part acting as a virtual XSUB. CASE: is greedy and if it is used then all
1159other XS keywords must be contained within a CASE:. This means nothing may
1160precede the first CASE: in the XSUB and anything following the last CASE: is
1161included in that case.
1162
1163A CASE: might switch via a parameter of the XSUB, via the C<ix> ALIAS:
1164variable (see L<"The ALIAS: Keyword">), or maybe via the C<items> variable
1165(see L<"Variable-length Parameter Lists">). The last CASE: becomes the
1166B<default> case if it is not associated with a conditional. The following
1167example shows CASE switched via C<ix> with a function C<rpcb_gettime()>
1168having an alias C<x_gettime()>. When the function is called as
b772cb6e
PP
1169C<rpcb_gettime()> its parameters are the usual C<(char *host, time_t *timep)>,
1170but when the function is called as C<x_gettime()> its parameters are
c07a80fd
PP
1171reversed, C<(time_t *timep, char *host)>.
1172
1173 long
1174 rpcb_gettime(a,b)
1175 CASE: ix == 1
beb31b0b 1176 ALIAS:
c07a80fd 1177 x_gettime = 1
beb31b0b 1178 INPUT:
c07a80fd
PP
1179 # 'a' is timep, 'b' is host
1180 char *b
1181 time_t a = NO_INIT
beb31b0b 1182 CODE:
c07a80fd 1183 RETVAL = rpcb_gettime( b, &a );
beb31b0b 1184 OUTPUT:
c07a80fd
PP
1185 a
1186 RETVAL
1187 CASE:
1188 # 'a' is host, 'b' is timep
1189 char *a
1190 time_t &b = NO_INIT
beb31b0b 1191 OUTPUT:
c07a80fd
PP
1192 b
1193 RETVAL
1194
1195That function can be called with either of the following statements. Note
1196the different argument lists.
1197
1198 $status = rpcb_gettime( $host, $timep );
1199
1200 $status = x_gettime( $timep, $host );
1201
1202=head2 The & Unary Operator
1203
beb31b0b
GS
1204The C<&> unary operator in the INPUT: section is used to tell B<xsubpp>
1205that it should convert a Perl value to/from C using the C type to the left
1206of C<&>, but provide a pointer to this value when the C function is called.
1207
1208This is useful to avoid a CODE: block for a C function which takes a parameter
1209by reference. Typically, the parameter should be not a pointer type (an
1210C<int> or C<long> but not a C<int*> or C<long*>).
c07a80fd 1211
beb31b0b 1212The following XSUB will generate incorrect C code. The B<xsubpp> compiler will
c07a80fd
PP
1213turn this into code which calls C<rpcb_gettime()> with parameters C<(char
1214*host, time_t timep)>, but the real C<rpcb_gettime()> wants the C<timep>
1215parameter to be of type C<time_t*> rather than C<time_t>.
1216
1217 bool_t
1218 rpcb_gettime(host,timep)
1219 char *host
1220 time_t timep
beb31b0b 1221 OUTPUT:
c07a80fd
PP
1222 timep
1223
beb31b0b 1224That problem is corrected by using the C<&> operator. The B<xsubpp> compiler
c07a80fd
PP
1225will now turn this into code which calls C<rpcb_gettime()> correctly with
1226parameters C<(char *host, time_t *timep)>. It does this by carrying the
1227C<&> through, so the function call looks like C<rpcb_gettime(host, &timep)>.
1228
1229 bool_t
1230 rpcb_gettime(host,timep)
1231 char *host
1232 time_t &timep
beb31b0b 1233 OUTPUT:
c07a80fd
PP
1234 timep
1235
a0d0e21e
LW
1236=head2 Inserting Comments and C Preprocessor Directives
1237
f27cfbbe 1238C preprocessor directives are allowed within BOOT:, PREINIT: INIT:,
5f05dabc 1239CODE:, PPCODE:, and CLEANUP: blocks, as well as outside the functions.
f27cfbbe
PP
1240Comments are allowed anywhere after the MODULE keyword. The compiler
1241will pass the preprocessor directives through untouched and will remove
1242the commented lines.
b772cb6e 1243
f27cfbbe
PP
1244Comments can be added to XSUBs by placing a C<#> as the first
1245non-whitespace of a line. Care should be taken to avoid making the
1246comment look like a C preprocessor directive, lest it be interpreted as
1247such. The simplest way to prevent this is to put whitespace in front of
1248the C<#>.
1249
f27cfbbe
PP
1250If you use preprocessor directives to choose one of two
1251versions of a function, use
1252
1253 #if ... version1
1254 #else /* ... version2 */
1255 #endif
1256
1257and not
1258
1259 #if ... version1
1260 #endif
1261 #if ... version2
1262 #endif
1263
beb31b0b 1264because otherwise B<xsubpp> will believe that you made a duplicate
f27cfbbe
PP
1265definition of the function. Also, put a blank line before the
1266#else/#endif so it will not be seen as part of the function body.
a0d0e21e
LW
1267
1268=head2 Using XS With C++
1269
beb31b0b
GS
1270If an XSUB name contains C<::>, it is considered to be a C++ method.
1271The generated Perl function will assume that
a0d0e21e
LW
1272its first argument is an object pointer. The object pointer
1273will be stored in a variable called THIS. The object should
1274have been created by C++ with the new() function and should
cb1a09d0
AD
1275be blessed by Perl with the sv_setref_pv() macro. The
1276blessing of the object by Perl can be handled by a typemap. An example
1277typemap is shown at the end of this section.
a0d0e21e 1278
beb31b0b
GS
1279If the return type of the XSUB includes C<static>, the method is considered
1280to be a static method. It will call the C++
a0d0e21e 1281function using the class::method() syntax. If the method is not static
f27cfbbe 1282the function will be called using the THIS-E<gt>method() syntax.
a0d0e21e 1283
cb1a09d0 1284The next examples will use the following C++ class.
a0d0e21e 1285
a5f75d66 1286 class color {
cb1a09d0 1287 public:
a5f75d66
AD
1288 color();
1289 ~color();
cb1a09d0
AD
1290 int blue();
1291 void set_blue( int );
1292
1293 private:
1294 int c_blue;
1295 };
1296
1297The XSUBs for the blue() and set_blue() methods are defined with the class
1298name but the parameter for the object (THIS, or "self") is implicit and is
1299not listed.
1300
1301 int
1302 color::blue()
a0d0e21e
LW
1303
1304 void
cb1a09d0
AD
1305 color::set_blue( val )
1306 int val
a0d0e21e 1307
beb31b0b
GS
1308Both Perl functions will expect an object as the first parameter. In the
1309generated C++ code the object is called C<THIS>, and the method call will
1310be performed on this object. So in the C++ code the blue() and set_blue()
1311methods will be called as this:
a0d0e21e 1312
cb1a09d0 1313 RETVAL = THIS->blue();
a0d0e21e 1314
cb1a09d0 1315 THIS->set_blue( val );
a0d0e21e 1316
cb1a09d0 1317If the function's name is B<DESTROY> then the C++ C<delete> function will be
beb31b0b 1318called and C<THIS> will be given as its parameter. The generated C++ code for
a0d0e21e 1319
d1b91892 1320 void
cb1a09d0
AD
1321 color::DESTROY()
1322
beb31b0b
GS
1323will look like this:
1324
1325 color *THIS = ...; // Initialized as in typemap
cb1a09d0
AD
1326
1327 delete THIS;
a0d0e21e 1328
cb1a09d0
AD
1329If the function's name is B<new> then the C++ C<new> function will be called
1330to create a dynamic C++ object. The XSUB will expect the class name, which
1331will be kept in a variable called C<CLASS>, to be given as the first
1332argument.
a0d0e21e 1333
cb1a09d0
AD
1334 color *
1335 color::new()
a0d0e21e 1336
beb31b0b 1337The generated C++ code will call C<new>.
a0d0e21e 1338
beb31b0b 1339 RETVAL = new color();
cb1a09d0
AD
1340
1341The following is an example of a typemap that could be used for this C++
1342example.
1343
1344 TYPEMAP
1345 color * O_OBJECT
1346
1347 OUTPUT
1348 # The Perl object is blessed into 'CLASS', which should be a
1349 # char* having the name of the package for the blessing.
1350 O_OBJECT
1351 sv_setref_pv( $arg, CLASS, (void*)$var );
a6006777 1352
cb1a09d0
AD
1353 INPUT
1354 O_OBJECT
1355 if( sv_isobject($arg) && (SvTYPE(SvRV($arg)) == SVt_PVMG) )
1356 $var = ($type)SvIV((SV*)SvRV( $arg ));
1357 else{
1358 warn( \"${Package}::$func_name() -- $var is not a blessed SV reference\" );
1359 XSRETURN_UNDEF;
1360 }
a0d0e21e 1361
d1b91892 1362=head2 Interface Strategy
a0d0e21e
LW
1363
1364When designing an interface between Perl and a C library a straight
beb31b0b
GS
1365translation from C to XS (such as created by C<h2xs -x>) is often sufficient.
1366However, sometimes the interface will look
a0d0e21e 1367very C-like and occasionally nonintuitive, especially when the C function
beb31b0b
GS
1368modifies one of its parameters, or returns failure inband (as in "negative
1369return values mean failure"). In cases where the programmer wishes to
a0d0e21e
LW
1370create a more Perl-like interface the following strategy may help to
1371identify the more critical parts of the interface.
1372
beb31b0b
GS
1373Identify the C functions with input/output or output parameters. The XSUBs for
1374these functions may be able to return lists to Perl.
1375
1376Identify the C functions which use some inband info as an indication
1377of failure. They may be
1378candidates to return undef or an empty list in case of failure. If the
1379failure may be detected without a call to the C function, you may want to use
1380an INIT: section to report the failure. For failures detectable after the C
1381function returns one may want to use a CLEANUP: section to process the
1382failure. In more complicated cases use CODE: or PPCODE: sections.
1383
1384If many functions use the same failure indication based on the return value,
1385you may want to create a special typedef to handle this situation. Put
1386
1387 typedef int negative_is_failure;
1388
1389near the beginning of XS file, and create an OUTPUT typemap entry
1390for C<negative_is_failure> which converts negative values to C<undef>, or
1391maybe croak()s. After this the return value of type C<negative_is_failure>
1392will create more Perl-like interface.
a0d0e21e 1393
d1b91892 1394Identify which values are used by only the C and XSUB functions
beb31b0b
GS
1395themselves, say, when a parameter to a function should be a contents of a
1396global variable. If Perl does not need to access the contents of the value
a0d0e21e
LW
1397then it may not be necessary to provide a translation for that value
1398from C to Perl.
1399
1400Identify the pointers in the C function parameter lists and return
beb31b0b
GS
1401values. Some pointers may be used to implement input/output or
1402output parameters, they can be handled in XS with the C<&> unary operator,
1403and, possibly, using the NO_INIT keyword.
1404Some others will require handling of types like C<int *>, and one needs
1405to decide what a useful Perl translation will do in such a case. When
1406the semantic is clear, it is advisable to put the translation into a typemap
1407file.
a0d0e21e
LW
1408
1409Identify the structures used by the C functions. In many
1410cases it may be helpful to use the T_PTROBJ typemap for
1411these structures so they can be manipulated by Perl as
beb31b0b
GS
1412blessed objects. (This is handled automatically by C<h2xs -x>.)
1413
1414If the same C type is used in several different contexts which require
1415different translations, C<typedef> several new types mapped to this C type,
1416and create separate F<typemap> entries for these new types. Use these
1417types in declarations of return type and parameters to XSUBs.
a0d0e21e 1418
a0d0e21e
LW
1419=head2 Perl Objects And C Structures
1420
1421When dealing with C structures one should select either
1422B<T_PTROBJ> or B<T_PTRREF> for the XS type. Both types are
1423designed to handle pointers to complex objects. The
1424T_PTRREF type will allow the Perl object to be unblessed
1425while the T_PTROBJ type requires that the object be blessed.
1426By using T_PTROBJ one can achieve a form of type-checking
d1b91892 1427because the XSUB will attempt to verify that the Perl object
a0d0e21e
LW
1428is of the expected type.
1429
1430The following XS code shows the getnetconfigent() function which is used
8e07c86e 1431with ONC+ TIRPC. The getnetconfigent() function will return a pointer to a
a0d0e21e
LW
1432C structure and has the C prototype shown below. The example will
1433demonstrate how the C pointer will become a Perl reference. Perl will
1434consider this reference to be a pointer to a blessed object and will
1435attempt to call a destructor for the object. A destructor will be
1436provided in the XS source to free the memory used by getnetconfigent().
1437Destructors in XS can be created by specifying an XSUB function whose name
1438ends with the word B<DESTROY>. XS destructors can be used to free memory
1439which may have been malloc'd by another XSUB.
1440
1441 struct netconfig *getnetconfigent(const char *netid);
1442
1443A C<typedef> will be created for C<struct netconfig>. The Perl
1444object will be blessed in a class matching the name of the C
1445type, with the tag C<Ptr> appended, and the name should not
1446have embedded spaces if it will be a Perl package name. The
1447destructor will be placed in a class corresponding to the
1448class of the object and the PREFIX keyword will be used to
1449trim the name to the word DESTROY as Perl will expect.
1450
1451 typedef struct netconfig Netconfig;
1452
1453 MODULE = RPC PACKAGE = RPC
1454
1455 Netconfig *
1456 getnetconfigent(netid)
8e07c86e 1457 char *netid
a0d0e21e
LW
1458
1459 MODULE = RPC PACKAGE = NetconfigPtr PREFIX = rpcb_
1460
1461 void
1462 rpcb_DESTROY(netconf)
8e07c86e 1463 Netconfig *netconf
beb31b0b 1464 CODE:
a0d0e21e
LW
1465 printf("Now in NetconfigPtr::DESTROY\n");
1466 free( netconf );
1467
1468This example requires the following typemap entry. Consult the typemap
1469section for more information about adding new typemaps for an extension.
1470
1471 TYPEMAP
1472 Netconfig * T_PTROBJ
1473
1474This example will be used with the following Perl statements.
1475
1476 use RPC;
1477 $netconf = getnetconfigent("udp");
1478
1479When Perl destroys the object referenced by $netconf it will send the
1480object to the supplied XSUB DESTROY function. Perl cannot determine, and
1481does not care, that this object is a C struct and not a Perl object. In
1482this sense, there is no difference between the object created by the
1483getnetconfigent() XSUB and an object created by a normal Perl subroutine.
1484
a0d0e21e
LW
1485=head2 The Typemap
1486
1487The typemap is a collection of code fragments which are used by the B<xsubpp>
1488compiler to map C function parameters and values to Perl values. The
1489typemap file may consist of three sections labeled C<TYPEMAP>, C<INPUT>, and
beb31b0b
GS
1490C<OUTPUT>. An unlabelled initial section is assumed to be a C<TYPEMAP>
1491section. The INPUT section tells
7e9d670d 1492the compiler how to translate Perl values
a0d0e21e
LW
1493into variables of certain C types. The OUTPUT section tells the compiler
1494how to translate the values from certain C types into values Perl can
1495understand. The TYPEMAP section tells the compiler which of the INPUT and
1496OUTPUT code fragments should be used to map a given C type to a Perl value.
7e9d670d
GS
1497The section labels C<TYPEMAP>, C<INPUT>, or C<OUTPUT> must begin
1498in the first column on a line by themselves, and must be in uppercase.
a0d0e21e
LW
1499
1500The default typemap in the C<ext> directory of the Perl source contains many
1501useful types which can be used by Perl extensions. Some extensions define
1502additional typemaps which they keep in their own directory. These
1503additional typemaps may reference INPUT and OUTPUT maps in the main
1504typemap. The B<xsubpp> compiler will allow the extension's own typemap to
1505override any mappings which are in the default typemap.
1506
1507Most extensions which require a custom typemap will need only the TYPEMAP
1508section of the typemap file. The custom typemap used in the
1509getnetconfigent() example shown earlier demonstrates what may be the typical
1510use of extension typemaps. That typemap is used to equate a C structure
1511with the T_PTROBJ typemap. The typemap used by getnetconfigent() is shown
1512here. Note that the C type is separated from the XS type with a tab and
1513that the C unary operator C<*> is considered to be a part of the C type name.
1514
beb31b0b
GS
1515 TYPEMAP
1516 Netconfig *<tab>T_PTROBJ
a0d0e21e 1517
1748e8dd
RS
1518Here's a more complicated example: suppose that you wanted C<struct
1519netconfig> to be blessed into the class C<Net::Config>. One way to do
1520this is to use underscores (_) to separate package names, as follows:
1521
1522 typedef struct netconfig * Net_Config;
1523
1524And then provide a typemap entry C<T_PTROBJ_SPECIAL> that maps underscores to
1525double-colons (::), and declare C<Net_Config> to be of that type:
1526
1527
1528 TYPEMAP
1529 Net_Config T_PTROBJ_SPECIAL
1530
1531 INPUT
1532 T_PTROBJ_SPECIAL
1533 if (sv_derived_from($arg, \"${(my $ntt=$ntype)=~s/_/::/g;\$ntt}\")) {
1534 IV tmp = SvIV((SV*)SvRV($arg));
1535 $var = ($type) tmp;
1536 }
1537 else
1538 croak(\"$var is not of type ${(my $ntt=$ntype)=~s/_/::/g;\$ntt}\")
1539
1540 OUTPUT
1541 T_PTROBJ_SPECIAL
1542 sv_setref_pv($arg, \"${(my $ntt=$ntype)=~s/_/::/g;\$ntt}\",
1543 (void*)$var);
1544
1545The INPUT and OUTPUT sections substitute underscores for double-colons
1546on the fly, giving the desired effect. This example demonstrates some
1547of the power and versatility of the typemap facility.
1548
a0d0e21e
LW
1549=head1 EXAMPLES
1550
1551File C<RPC.xs>: Interface to some ONC+ RPC bind library functions.
1552
1553 #include "EXTERN.h"
1554 #include "perl.h"
1555 #include "XSUB.h"
1556
1557 #include <rpc/rpc.h>
1558
1559 typedef struct netconfig Netconfig;
1560
1561 MODULE = RPC PACKAGE = RPC
1562
e7ea3e70 1563 SV *
a0d0e21e 1564 rpcb_gettime(host="localhost")
8e07c86e 1565 char *host
beb31b0b 1566 PREINIT:
a0d0e21e 1567 time_t timep;
beb31b0b 1568 CODE:
a0d0e21e
LW
1569 ST(0) = sv_newmortal();
1570 if( rpcb_gettime( host, &timep ) )
1571 sv_setnv( ST(0), (double)timep );
a0d0e21e
LW
1572
1573 Netconfig *
1574 getnetconfigent(netid="udp")
8e07c86e 1575 char *netid
a0d0e21e
LW
1576
1577 MODULE = RPC PACKAGE = NetconfigPtr PREFIX = rpcb_
1578
1579 void
1580 rpcb_DESTROY(netconf)
8e07c86e 1581 Netconfig *netconf
beb31b0b 1582 CODE:
a0d0e21e
LW
1583 printf("NetconfigPtr::DESTROY\n");
1584 free( netconf );
1585
1586File C<typemap>: Custom typemap for RPC.xs.
1587
1588 TYPEMAP
1589 Netconfig * T_PTROBJ
1590
1591File C<RPC.pm>: Perl module for the RPC extension.
1592
1593 package RPC;
1594
1595 require Exporter;
1596 require DynaLoader;
1597 @ISA = qw(Exporter DynaLoader);
1598 @EXPORT = qw(rpcb_gettime getnetconfigent);
1599
1600 bootstrap RPC;
1601 1;
1602
1603File C<rpctest.pl>: Perl test program for the RPC extension.
1604
1605 use RPC;
1606
1607 $netconf = getnetconfigent();
1608 $a = rpcb_gettime();
1609 print "time = $a\n";
1610 print "netconf = $netconf\n";
1611
1612 $netconf = getnetconfigent("tcp");
1613 $a = rpcb_gettime("poplar");
1614 print "time = $a\n";
1615 print "netconf = $netconf\n";
1616
1617
c07a80fd
PP
1618=head1 XS VERSION
1619
f27cfbbe 1620This document covers features supported by C<xsubpp> 1.935.
c07a80fd 1621
a0d0e21e
LW
1622=head1 AUTHOR
1623
beb31b0b
GS
1624Originally written by Dean Roehrich <F<roehrich@cray.com>>.
1625
1626Maintained since 1996 by The Perl Porters <F<perlbug@perl.com>>.