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