This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Re: [ID 20001127.002] const subs hurt under debugger
[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)
401 POST_CALL:
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
9e24e6f2
IZ
757=head2 The IN/OUTLIST/IN_OUTLIST Keywords
758
759In the list of parameters for an XSUB, one can precede parameter names
760by the C<IN>/C<OUTLIST>/C<IN_OUTLIST> keywords. C<IN> keyword is a default,
761the other two keywords indicate how the Perl interface should differ from
762the C interface.
763
764Parameters preceded by C<OUTLIST>/C<IN_OUTLIST> keywords are considered to
765be used by the C subroutine I<via pointers>. C<OUTLIST> keyword indicates
766that the C subroutine does not inspect the memory pointed by this parameter,
767but will write through this pointer to provide additional return values.
768Such parameters do not appear in the usage signature of the generated Perl
769function.
770
771Parameters preceded by C<IN_OUTLIST> I<do> appear as parameters to the
772Perl function. These parameters are converted to the corresponding C type,
773then pointers to these data are given as arguments to the C function. It
774is expected that the C function will write through these pointers
775
776The return list of the generated Perl function consists of the C return value
777from the function (unless the XSUB is of C<void> return type or
778C<The NO_INIT Keyword> was used) followed by all the C<OUTLIST>
7817ba4d 779and C<IN_OUTLIST> parameters (in the order of appearance). Say, an XSUB
9e24e6f2
IZ
780
781 void
782 day_month(OUTLIST day, IN unix_time, OUTLIST month)
783 int day
784 int unix_time
785 int month
786
787should be used from Perl as
788
789 my ($day, $month) = day_month(time);
790
791The C signature of the corresponding function should be
792
793 void day_month(int *day, int unix_time, int *month);
794
795The C<in>/C<OUTLIST>/C<IN_OUTLIST> keywords can be mixed with ANSI-style
796declarations, as in
797
798 void
799 day_month(OUTLIST int day, int unix_time, OUTLIST int month)
800
801(here the optional C<IN> keyword is omitted).
802
803The C<IN_OUTLIST> parameters are somewhat similar to parameters introduced
804with L<The & Unary Operator> and put into the C<OUTPUT:> section (see
805L<The OUTPUT: Keyword>). Say, the same C function can be interfaced with as
806
807 void
808 day_month(day, unix_time, month)
809 int &day = NO_INIT
810 int unix_time
811 int &month = NO_INIT
812 OUTPUT:
813 day
814 month
815
816However, the generated Perl function is called in very C-ish style:
817
818 my ($day, $month);
819 day_month($day, time, $month);
820
a0d0e21e
LW
821=head2 Variable-length Parameter Lists
822
823XSUBs can have variable-length parameter lists by specifying an ellipsis
824C<(...)> in the parameter list. This use of the ellipsis is similar to that
825found in ANSI C. The programmer is able to determine the number of
826arguments passed to the XSUB by examining the C<items> variable which the
827B<xsubpp> compiler supplies for all XSUBs. By using this mechanism one can
828create an XSUB which accepts a list of parameters of unknown length.
829
830The I<host> parameter for the rpcb_gettime() XSUB can be
831optional so the ellipsis can be used to indicate that the
832XSUB will take a variable number of parameters. Perl should
d1b91892 833be able to call this XSUB with either of the following statements.
a0d0e21e
LW
834
835 $status = rpcb_gettime( $timep, $host );
836
837 $status = rpcb_gettime( $timep );
838
839The XS code, with ellipsis, follows.
840
841 bool_t
842 rpcb_gettime(timep, ...)
8e07c86e 843 time_t timep = NO_INIT
beb31b0b 844 PREINIT:
a0d0e21e 845 char *host = "localhost";
2d8e6c8d 846 STRLEN n_a;
beb31b0b
GS
847 CODE:
848 if( items > 1 )
849 host = (char *)SvPV(ST(1), n_a);
850 RETVAL = rpcb_gettime( host, &timep );
851 OUTPUT:
a0d0e21e
LW
852 timep
853 RETVAL
854
cfc02341
IZ
855=head2 The C_ARGS: Keyword
856
857The C_ARGS: keyword allows creating of XSUBS which have different
858calling sequence from Perl than from C, without a need to write
beb31b0b 859CODE: or PPCODE: section. The contents of the C_ARGS: paragraph is
cfc02341
IZ
860put as the argument to the called C function without any change.
861
beb31b0b 862For example, suppose that a C function is declared as
cfc02341
IZ
863
864 symbolic nth_derivative(int n, symbolic function, int flags);
865
866and that the default flags are kept in a global C variable
867C<default_flags>. Suppose that you want to create an interface which
868is called as
869
870 $second_deriv = $function->nth_derivative(2);
871
872To do this, declare the XSUB as
873
874 symbolic
875 nth_derivative(function, n)
876 symbolic function
877 int n
beb31b0b 878 C_ARGS:
cfc02341
IZ
879 n, function, default_flags
880
a0d0e21e
LW
881=head2 The PPCODE: Keyword
882
883The PPCODE: keyword is an alternate form of the CODE: keyword and is used
884to tell the B<xsubpp> compiler that the programmer is supplying the code to
d1b91892 885control the argument stack for the XSUBs return values. Occasionally one
a0d0e21e
LW
886will want an XSUB to return a list of values rather than a single value.
887In these cases one must use PPCODE: and then explicitly push the list of
beb31b0b 888values on the stack. The PPCODE: and CODE: keywords should not be used
a0d0e21e
LW
889together within the same XSUB.
890
beb31b0b
GS
891The actual difference between PPCODE: and CODE: sections is in the
892initialization of C<SP> macro (which stands for the I<current> Perl
893stack pointer), and in the handling of data on the stack when returning
894from an XSUB. In CODE: sections SP preserves the value which was on
895entry to the XSUB: SP is on the function pointer (which follows the
896last parameter). In PPCODE: sections SP is moved backward to the
897beginning of the parameter list, which allows C<PUSH*()> macros
898to place output values in the place Perl expects them to be when
899the XSUB returns back to Perl.
900
901The generated trailer for a CODE: section ensures that the number of return
902values Perl will see is either 0 or 1 (depending on the C<void>ness of the
903return value of the C function, and heuristics mentioned in
904L<"The RETVAL Variable">). The trailer generated for a PPCODE: section
905is based on the number of return values and on the number of times
906C<SP> was updated by C<[X]PUSH*()> macros.
907
908Note that macros C<ST(i)>, C<XST_m*()> and C<XSRETURN*()> work equally
909well in CODE: sections and PPCODE: sections.
910
a0d0e21e
LW
911The following XSUB will call the C rpcb_gettime() function
912and will return its two output values, timep and status, to
913Perl as a single list.
914
d1b91892
AD
915 void
916 rpcb_gettime(host)
8e07c86e 917 char *host
beb31b0b 918 PREINIT:
a0d0e21e
LW
919 time_t timep;
920 bool_t status;
beb31b0b 921 PPCODE:
a0d0e21e 922 status = rpcb_gettime( host, &timep );
924508f0 923 EXTEND(SP, 2);
cb1a09d0
AD
924 PUSHs(sv_2mortal(newSViv(status)));
925 PUSHs(sv_2mortal(newSViv(timep)));
a0d0e21e
LW
926
927Notice that the programmer must supply the C code necessary
928to have the real rpcb_gettime() function called and to have
929the return values properly placed on the argument stack.
930
931The C<void> return type for this function tells the B<xsubpp> compiler that
932the RETVAL variable is not needed or used and that it should not be created.
933In most scenarios the void return type should be used with the PPCODE:
934directive.
935
936The EXTEND() macro is used to make room on the argument
937stack for 2 return values. The PPCODE: directive causes the
924508f0 938B<xsubpp> compiler to create a stack pointer available as C<SP>, and it
a0d0e21e
LW
939is this pointer which is being used in the EXTEND() macro.
940The values are then pushed onto the stack with the PUSHs()
941macro.
942
943Now the rpcb_gettime() function can be used from Perl with
944the following statement.
945
946 ($status, $timep) = rpcb_gettime("localhost");
947
ef50df4b
GS
948When handling output parameters with a PPCODE section, be sure to handle
949'set' magic properly. See L<perlguts> for details about 'set' magic.
950
a0d0e21e
LW
951=head2 Returning Undef And Empty Lists
952
5f05dabc 953Occasionally the programmer will want to return simply
a0d0e21e
LW
954C<undef> or an empty list if a function fails rather than a
955separate status value. The rpcb_gettime() function offers
956just this situation. If the function succeeds we would like
957to have it return the time and if it fails we would like to
958have undef returned. In the following Perl code the value
959of $timep will either be undef or it will be a valid time.
960
961 $timep = rpcb_gettime( "localhost" );
962
7b8d334a 963The following XSUB uses the C<SV *> return type as a mnemonic only,
e7ea3e70 964and uses a CODE: block to indicate to the compiler
a0d0e21e
LW
965that the programmer has supplied all the necessary code. The
966sv_newmortal() call will initialize the return value to undef, making that
967the default return value.
968
e7ea3e70 969 SV *
a0d0e21e
LW
970 rpcb_gettime(host)
971 char * host
beb31b0b 972 PREINIT:
a0d0e21e
LW
973 time_t timep;
974 bool_t x;
beb31b0b 975 CODE:
a0d0e21e
LW
976 ST(0) = sv_newmortal();
977 if( rpcb_gettime( host, &timep ) )
978 sv_setnv( ST(0), (double)timep);
a0d0e21e
LW
979
980The next example demonstrates how one would place an explicit undef in the
981return value, should the need arise.
982
e7ea3e70 983 SV *
a0d0e21e
LW
984 rpcb_gettime(host)
985 char * host
beb31b0b 986 PREINIT:
a0d0e21e
LW
987 time_t timep;
988 bool_t x;
beb31b0b 989 CODE:
a0d0e21e
LW
990 ST(0) = sv_newmortal();
991 if( rpcb_gettime( host, &timep ) ){
992 sv_setnv( ST(0), (double)timep);
993 }
994 else{
9cde0e7f 995 ST(0) = &PL_sv_undef;
a0d0e21e 996 }
a0d0e21e
LW
997
998To return an empty list one must use a PPCODE: block and
999then not push return values on the stack.
1000
1001 void
1002 rpcb_gettime(host)
8e07c86e 1003 char *host
beb31b0b 1004 PREINIT:
a0d0e21e 1005 time_t timep;
beb31b0b 1006 PPCODE:
a0d0e21e 1007 if( rpcb_gettime( host, &timep ) )
cb1a09d0 1008 PUSHs(sv_2mortal(newSViv(timep)));
a0d0e21e 1009 else{
beb31b0b
GS
1010 /* Nothing pushed on stack, so an empty
1011 * list is implicitly returned. */
a0d0e21e 1012 }
a0d0e21e 1013
f27cfbbe
PP
1014Some people may be inclined to include an explicit C<return> in the above
1015XSUB, rather than letting control fall through to the end. In those
1016situations C<XSRETURN_EMPTY> should be used, instead. This will ensure that
1017the XSUB stack is properly adjusted. Consult L<perlguts/"API LISTING"> for
1018other C<XSRETURN> macros.
1019
beb31b0b
GS
1020Since C<XSRETURN_*> macros can be used with CODE blocks as well, one can
1021rewrite this example as:
1022
1023 int
1024 rpcb_gettime(host)
1025 char *host
1026 PREINIT:
1027 time_t timep;
1028 CODE:
1029 RETVAL = rpcb_gettime( host, &timep );
1030 if (RETVAL == 0)
1031 XSRETURN_UNDEF;
1032 OUTPUT:
1033 RETVAL
1034
9e24e6f2 1035In fact, one can put this check into a POST_CALL: section as well. Together
beb31b0b
GS
1036with PREINIT: simplifications, this leads to:
1037
1038 int
1039 rpcb_gettime(host)
1040 char *host
1041 time_t timep;
9e24e6f2 1042 POST_CALL:
beb31b0b
GS
1043 if (RETVAL == 0)
1044 XSRETURN_UNDEF;
1045
4633a7c4
LW
1046=head2 The REQUIRE: Keyword
1047
1048The REQUIRE: keyword is used to indicate the minimum version of the
1049B<xsubpp> compiler needed to compile the XS module. An XS module which
5f05dabc 1050contains the following statement will compile with only B<xsubpp> version
4633a7c4
LW
10511.922 or greater:
1052
1053 REQUIRE: 1.922
1054
a0d0e21e
LW
1055=head2 The CLEANUP: Keyword
1056
1057This keyword can be used when an XSUB requires special cleanup procedures
1058before it terminates. When the CLEANUP: keyword is used it must follow
1059any CODE:, PPCODE:, or OUTPUT: blocks which are present in the XSUB. The
1060code specified for the cleanup block will be added as the last statements
1061in the XSUB.
1062
9e24e6f2
IZ
1063=head2 The POST_CALL: Keyword
1064
1065This keyword can be used when an XSUB requires special procedures
1066executed after the C subroutine call is performed. When the POST_CALL:
1067keyword is used it must precede OUTPUT: and CLEANUP: blocks which are
1068present in the XSUB.
1069
1070The POST_CALL: block does not make a lot of sense when the C subroutine
1071call is supplied by user by providing either CODE: or PPCODE: section.
1072
a0d0e21e
LW
1073=head2 The BOOT: Keyword
1074
1075The BOOT: keyword is used to add code to the extension's bootstrap
1076function. The bootstrap function is generated by the B<xsubpp> compiler and
1077normally holds the statements necessary to register any XSUBs with Perl.
1078With the BOOT: keyword the programmer can tell the compiler to add extra
1079statements to the bootstrap function.
1080
1081This keyword may be used any time after the first MODULE keyword and should
1082appear on a line by itself. The first blank line after the keyword will
1083terminate the code block.
1084
1085 BOOT:
1086 # The following message will be printed when the
1087 # bootstrap function executes.
1088 printf("Hello from the bootstrap!\n");
1089
c07a80fd
PP
1090=head2 The VERSIONCHECK: Keyword
1091
1092The VERSIONCHECK: keyword corresponds to B<xsubpp>'s C<-versioncheck> and
5f05dabc 1093C<-noversioncheck> options. This keyword overrides the command line
c07a80fd
PP
1094options. Version checking is enabled by default. When version checking is
1095enabled the XS module will attempt to verify that its version matches the
1096version of the PM module.
1097
1098To enable version checking:
1099
1100 VERSIONCHECK: ENABLE
1101
1102To disable version checking:
1103
1104 VERSIONCHECK: DISABLE
1105
1106=head2 The PROTOTYPES: Keyword
1107
1108The PROTOTYPES: keyword corresponds to B<xsubpp>'s C<-prototypes> and
54310121 1109C<-noprototypes> options. This keyword overrides the command line options.
c07a80fd
PP
1110Prototypes are enabled by default. When prototypes are enabled XSUBs will
1111be given Perl prototypes. This keyword may be used multiple times in an XS
1112module to enable and disable prototypes for different parts of the module.
1113
1114To enable prototypes:
1115
1116 PROTOTYPES: ENABLE
1117
1118To disable prototypes:
1119
1120 PROTOTYPES: DISABLE
1121
1122=head2 The PROTOTYPE: Keyword
1123
1124This keyword is similar to the PROTOTYPES: keyword above but can be used to
1125force B<xsubpp> to use a specific prototype for the XSUB. This keyword
1126overrides all other prototype options and keywords but affects only the
1127current XSUB. Consult L<perlsub/Prototypes> for information about Perl
1128prototypes.
1129
1130 bool_t
1131 rpcb_gettime(timep, ...)
1132 time_t timep = NO_INIT
beb31b0b
GS
1133 PROTOTYPE: $;$
1134 PREINIT:
c07a80fd 1135 char *host = "localhost";
2d8e6c8d 1136 STRLEN n_a;
beb31b0b 1137 CODE:
c07a80fd 1138 if( items > 1 )
2d8e6c8d 1139 host = (char *)SvPV(ST(1), n_a);
c07a80fd 1140 RETVAL = rpcb_gettime( host, &timep );
beb31b0b 1141 OUTPUT:
c07a80fd
PP
1142 timep
1143 RETVAL
1144
1145=head2 The ALIAS: Keyword
1146
cfc02341 1147The ALIAS: keyword allows an XSUB to have two or more unique Perl names
c07a80fd
PP
1148and to know which of those names was used when it was invoked. The Perl
1149names may be fully-qualified with package names. Each alias is given an
1150index. The compiler will setup a variable called C<ix> which contain the
1151index of the alias which was used. When the XSUB is called with its
1152declared name C<ix> will be 0.
1153
1154The following example will create aliases C<FOO::gettime()> and
1155C<BAR::getit()> for this function.
1156
1157 bool_t
1158 rpcb_gettime(host,timep)
1159 char *host
1160 time_t &timep
beb31b0b 1161 ALIAS:
c07a80fd
PP
1162 FOO::gettime = 1
1163 BAR::getit = 2
beb31b0b 1164 INIT:
c07a80fd 1165 printf("# ix = %d\n", ix );
beb31b0b 1166 OUTPUT:
c07a80fd
PP
1167 timep
1168
cfc02341
IZ
1169=head2 The INTERFACE: Keyword
1170
1171This keyword declares the current XSUB as a keeper of the given
1172calling signature. If some text follows this keyword, it is
1173considered as a list of functions which have this signature, and
beb31b0b 1174should be attached to the current XSUB.
cfc02341 1175
beb31b0b
GS
1176For example, if you have 4 C functions multiply(), divide(), add(),
1177subtract() all having the signature:
cfc02341
IZ
1178
1179 symbolic f(symbolic, symbolic);
1180
beb31b0b 1181you can make them all to use the same XSUB using this:
cfc02341
IZ
1182
1183 symbolic
1184 interface_s_ss(arg1, arg2)
1185 symbolic arg1
1186 symbolic arg2
1187 INTERFACE:
1188 multiply divide
1189 add subtract
1190
beb31b0b
GS
1191(This is the complete XSUB code for 4 Perl functions!) Four generated
1192Perl function share names with corresponding C functions.
1193
1194The advantage of this approach comparing to ALIAS: keyword is that there
1195is no need to code a switch statement, each Perl function (which shares
1196the same XSUB) knows which C function it should call. Additionally, one
cfc02341 1197can attach an extra function remainder() at runtime by using
beb31b0b 1198
cfc02341
IZ
1199 CV *mycv = newXSproto("Symbolic::remainder",
1200 XS_Symbolic_interface_s_ss, __FILE__, "$$");
1201 XSINTERFACE_FUNC_SET(mycv, remainder);
1202
beb31b0b
GS
1203say, from another XSUB. (This example supposes that there was no
1204INTERFACE_MACRO: section, otherwise one needs to use something else instead of
1205C<XSINTERFACE_FUNC_SET>, see the next section.)
cfc02341
IZ
1206
1207=head2 The INTERFACE_MACRO: Keyword
1208
1209This keyword allows one to define an INTERFACE using a different way
1210to extract a function pointer from an XSUB. The text which follows
1211this keyword should give the name of macros which would extract/set a
1212function pointer. The extractor macro is given return type, C<CV*>,
1213and C<XSANY.any_dptr> for this C<CV*>. The setter macro is given cv,
1214and the function pointer.
1215
1216The default value is C<XSINTERFACE_FUNC> and C<XSINTERFACE_FUNC_SET>.
1217An INTERFACE keyword with an empty list of functions can be omitted if
1218INTERFACE_MACRO keyword is used.
1219
1220Suppose that in the previous example functions pointers for
1221multiply(), divide(), add(), subtract() are kept in a global C array
1222C<fp[]> with offsets being C<multiply_off>, C<divide_off>, C<add_off>,
1223C<subtract_off>. Then one can use
1224
1225 #define XSINTERFACE_FUNC_BYOFFSET(ret,cv,f) \
1226 ((XSINTERFACE_CVT(ret,))fp[CvXSUBANY(cv).any_i32])
1227 #define XSINTERFACE_FUNC_BYOFFSET_set(cv,f) \
1228 CvXSUBANY(cv).any_i32 = CAT2( f, _off )
1229
1230in C section,
1231
1232 symbolic
1233 interface_s_ss(arg1, arg2)
1234 symbolic arg1
1235 symbolic arg2
beb31b0b 1236 INTERFACE_MACRO:
cfc02341
IZ
1237 XSINTERFACE_FUNC_BYOFFSET
1238 XSINTERFACE_FUNC_BYOFFSET_set
beb31b0b 1239 INTERFACE:
cfc02341
IZ
1240 multiply divide
1241 add subtract
1242
1243in XSUB section.
1244
c07a80fd
PP
1245=head2 The INCLUDE: Keyword
1246
1247This keyword can be used to pull other files into the XS module. The other
1248files may have XS code. INCLUDE: can also be used to run a command to
1249generate the XS code to be pulled into the module.
1250
1251The file F<Rpcb1.xsh> contains our C<rpcb_gettime()> function:
1252
1253 bool_t
1254 rpcb_gettime(host,timep)
1255 char *host
1256 time_t &timep
beb31b0b 1257 OUTPUT:
c07a80fd
PP
1258 timep
1259
1260The XS module can use INCLUDE: to pull that file into it.
1261
1262 INCLUDE: Rpcb1.xsh
1263
1264If the parameters to the INCLUDE: keyword are followed by a pipe (C<|>) then
1265the compiler will interpret the parameters as a command.
1266
1267 INCLUDE: cat Rpcb1.xsh |
1268
1269=head2 The CASE: Keyword
1270
1271The CASE: keyword allows an XSUB to have multiple distinct parts with each
1272part acting as a virtual XSUB. CASE: is greedy and if it is used then all
1273other XS keywords must be contained within a CASE:. This means nothing may
1274precede the first CASE: in the XSUB and anything following the last CASE: is
1275included in that case.
1276
1277A CASE: might switch via a parameter of the XSUB, via the C<ix> ALIAS:
1278variable (see L<"The ALIAS: Keyword">), or maybe via the C<items> variable
1279(see L<"Variable-length Parameter Lists">). The last CASE: becomes the
1280B<default> case if it is not associated with a conditional. The following
1281example shows CASE switched via C<ix> with a function C<rpcb_gettime()>
1282having an alias C<x_gettime()>. When the function is called as
b772cb6e
PP
1283C<rpcb_gettime()> its parameters are the usual C<(char *host, time_t *timep)>,
1284but when the function is called as C<x_gettime()> its parameters are
c07a80fd
PP
1285reversed, C<(time_t *timep, char *host)>.
1286
1287 long
1288 rpcb_gettime(a,b)
1289 CASE: ix == 1
beb31b0b 1290 ALIAS:
c07a80fd 1291 x_gettime = 1
beb31b0b 1292 INPUT:
c07a80fd
PP
1293 # 'a' is timep, 'b' is host
1294 char *b
1295 time_t a = NO_INIT
beb31b0b 1296 CODE:
c07a80fd 1297 RETVAL = rpcb_gettime( b, &a );
beb31b0b 1298 OUTPUT:
c07a80fd
PP
1299 a
1300 RETVAL
1301 CASE:
1302 # 'a' is host, 'b' is timep
1303 char *a
1304 time_t &b = NO_INIT
beb31b0b 1305 OUTPUT:
c07a80fd
PP
1306 b
1307 RETVAL
1308
1309That function can be called with either of the following statements. Note
1310the different argument lists.
1311
1312 $status = rpcb_gettime( $host, $timep );
1313
1314 $status = x_gettime( $timep, $host );
1315
1316=head2 The & Unary Operator
1317
beb31b0b
GS
1318The C<&> unary operator in the INPUT: section is used to tell B<xsubpp>
1319that it should convert a Perl value to/from C using the C type to the left
1320of C<&>, but provide a pointer to this value when the C function is called.
1321
1322This is useful to avoid a CODE: block for a C function which takes a parameter
1323by reference. Typically, the parameter should be not a pointer type (an
1324C<int> or C<long> but not a C<int*> or C<long*>).
c07a80fd 1325
beb31b0b 1326The following XSUB will generate incorrect C code. The B<xsubpp> compiler will
c07a80fd
PP
1327turn this into code which calls C<rpcb_gettime()> with parameters C<(char
1328*host, time_t timep)>, but the real C<rpcb_gettime()> wants the C<timep>
1329parameter to be of type C<time_t*> rather than C<time_t>.
1330
1331 bool_t
1332 rpcb_gettime(host,timep)
1333 char *host
1334 time_t timep
beb31b0b 1335 OUTPUT:
c07a80fd
PP
1336 timep
1337
beb31b0b 1338That problem is corrected by using the C<&> operator. The B<xsubpp> compiler
c07a80fd
PP
1339will now turn this into code which calls C<rpcb_gettime()> correctly with
1340parameters C<(char *host, time_t *timep)>. It does this by carrying the
1341C<&> through, so the function call looks like C<rpcb_gettime(host, &timep)>.
1342
1343 bool_t
1344 rpcb_gettime(host,timep)
1345 char *host
1346 time_t &timep
beb31b0b 1347 OUTPUT:
c07a80fd
PP
1348 timep
1349
7817ba4d 1350=head2 Inserting POD, Comments and C Preprocessor Directives
a0d0e21e 1351
7817ba4d
NC
1352C preprocessor directives are allowed within BOOT:, PREINIT: INIT:, CODE:,
1353PPCODE:, POST_CALL:, and CLEANUP: blocks, as well as outside the functions.
1354Comments are allowed anywhere after the MODULE keyword. The compiler will
1355pass the preprocessor directives through untouched and will remove the
1356commented lines. POD documentation is allowed at any point, both in the
1357C and XS language sections. POD must be terminated with a C<=cut> command;
1358C<xsubpp> will exit with an error if it does not. It is very unlikely that
1359human generated C code will be mistaken for POD, as most indenting styles
1360result in whitespace in front of any line starting with C<=>. Machine
1361generated XS files may fall into this trap unless care is taken to
1362ensure that a space breaks the sequence "\n=".
b772cb6e 1363
f27cfbbe
PP
1364Comments can be added to XSUBs by placing a C<#> as the first
1365non-whitespace of a line. Care should be taken to avoid making the
1366comment look like a C preprocessor directive, lest it be interpreted as
1367such. The simplest way to prevent this is to put whitespace in front of
1368the C<#>.
1369
f27cfbbe
PP
1370If you use preprocessor directives to choose one of two
1371versions of a function, use
1372
1373 #if ... version1
1374 #else /* ... version2 */
1375 #endif
1376
1377and not
1378
1379 #if ... version1
1380 #endif
1381 #if ... version2
1382 #endif
1383
beb31b0b 1384because otherwise B<xsubpp> will believe that you made a duplicate
f27cfbbe
PP
1385definition of the function. Also, put a blank line before the
1386#else/#endif so it will not be seen as part of the function body.
a0d0e21e
LW
1387
1388=head2 Using XS With C++
1389
beb31b0b
GS
1390If an XSUB name contains C<::>, it is considered to be a C++ method.
1391The generated Perl function will assume that
a0d0e21e
LW
1392its first argument is an object pointer. The object pointer
1393will be stored in a variable called THIS. The object should
1394have been created by C++ with the new() function and should
cb1a09d0
AD
1395be blessed by Perl with the sv_setref_pv() macro. The
1396blessing of the object by Perl can be handled by a typemap. An example
1397typemap is shown at the end of this section.
a0d0e21e 1398
beb31b0b
GS
1399If the return type of the XSUB includes C<static>, the method is considered
1400to be a static method. It will call the C++
a0d0e21e 1401function using the class::method() syntax. If the method is not static
f27cfbbe 1402the function will be called using the THIS-E<gt>method() syntax.
a0d0e21e 1403
cb1a09d0 1404The next examples will use the following C++ class.
a0d0e21e 1405
a5f75d66 1406 class color {
cb1a09d0 1407 public:
a5f75d66
AD
1408 color();
1409 ~color();
cb1a09d0
AD
1410 int blue();
1411 void set_blue( int );
1412
1413 private:
1414 int c_blue;
1415 };
1416
1417The XSUBs for the blue() and set_blue() methods are defined with the class
1418name but the parameter for the object (THIS, or "self") is implicit and is
1419not listed.
1420
1421 int
1422 color::blue()
a0d0e21e
LW
1423
1424 void
cb1a09d0
AD
1425 color::set_blue( val )
1426 int val
a0d0e21e 1427
beb31b0b
GS
1428Both Perl functions will expect an object as the first parameter. In the
1429generated C++ code the object is called C<THIS>, and the method call will
1430be performed on this object. So in the C++ code the blue() and set_blue()
1431methods will be called as this:
a0d0e21e 1432
cb1a09d0 1433 RETVAL = THIS->blue();
a0d0e21e 1434
cb1a09d0 1435 THIS->set_blue( val );
a0d0e21e 1436
4628e4f8
GS
1437You could also write a single get/set method using an optional argument:
1438
1439 int
a104f515 1440 color::blue( val = NO_INIT )
4628e4f8
GS
1441 int val
1442 PROTOTYPE $;$
1443 CODE:
1444 if (items > 1)
1445 THIS->set_blue( val );
1446 RETVAL = THIS->blue();
1447 OUTPUT:
1448 RETVAL
1449
cb1a09d0 1450If the function's name is B<DESTROY> then the C++ C<delete> function will be
beb31b0b 1451called and C<THIS> will be given as its parameter. The generated C++ code for
a0d0e21e 1452
d1b91892 1453 void
cb1a09d0
AD
1454 color::DESTROY()
1455
beb31b0b
GS
1456will look like this:
1457
1458 color *THIS = ...; // Initialized as in typemap
cb1a09d0
AD
1459
1460 delete THIS;
a0d0e21e 1461
cb1a09d0
AD
1462If the function's name is B<new> then the C++ C<new> function will be called
1463to create a dynamic C++ object. The XSUB will expect the class name, which
1464will be kept in a variable called C<CLASS>, to be given as the first
1465argument.
a0d0e21e 1466
cb1a09d0
AD
1467 color *
1468 color::new()
a0d0e21e 1469
beb31b0b 1470The generated C++ code will call C<new>.
a0d0e21e 1471
beb31b0b 1472 RETVAL = new color();
cb1a09d0
AD
1473
1474The following is an example of a typemap that could be used for this C++
1475example.
1476
1477 TYPEMAP
1478 color * O_OBJECT
1479
1480 OUTPUT
1481 # The Perl object is blessed into 'CLASS', which should be a
1482 # char* having the name of the package for the blessing.
1483 O_OBJECT
1484 sv_setref_pv( $arg, CLASS, (void*)$var );
a6006777 1485
cb1a09d0
AD
1486 INPUT
1487 O_OBJECT
1488 if( sv_isobject($arg) && (SvTYPE(SvRV($arg)) == SVt_PVMG) )
1489 $var = ($type)SvIV((SV*)SvRV( $arg ));
1490 else{
1491 warn( \"${Package}::$func_name() -- $var is not a blessed SV reference\" );
1492 XSRETURN_UNDEF;
1493 }
a0d0e21e 1494
d1b91892 1495=head2 Interface Strategy
a0d0e21e
LW
1496
1497When designing an interface between Perl and a C library a straight
beb31b0b
GS
1498translation from C to XS (such as created by C<h2xs -x>) is often sufficient.
1499However, sometimes the interface will look
a0d0e21e 1500very C-like and occasionally nonintuitive, especially when the C function
beb31b0b
GS
1501modifies one of its parameters, or returns failure inband (as in "negative
1502return values mean failure"). In cases where the programmer wishes to
a0d0e21e
LW
1503create a more Perl-like interface the following strategy may help to
1504identify the more critical parts of the interface.
1505
beb31b0b
GS
1506Identify the C functions with input/output or output parameters. The XSUBs for
1507these functions may be able to return lists to Perl.
1508
1509Identify the C functions which use some inband info as an indication
1510of failure. They may be
1511candidates to return undef or an empty list in case of failure. If the
1512failure may be detected without a call to the C function, you may want to use
1513an INIT: section to report the failure. For failures detectable after the C
9e24e6f2 1514function returns one may want to use a POST_CALL: section to process the
beb31b0b
GS
1515failure. In more complicated cases use CODE: or PPCODE: sections.
1516
1517If many functions use the same failure indication based on the return value,
1518you may want to create a special typedef to handle this situation. Put
1519
1520 typedef int negative_is_failure;
1521
1522near the beginning of XS file, and create an OUTPUT typemap entry
1523for C<negative_is_failure> which converts negative values to C<undef>, or
1524maybe croak()s. After this the return value of type C<negative_is_failure>
1525will create more Perl-like interface.
a0d0e21e 1526
d1b91892 1527Identify which values are used by only the C and XSUB functions
beb31b0b
GS
1528themselves, say, when a parameter to a function should be a contents of a
1529global variable. If Perl does not need to access the contents of the value
a0d0e21e
LW
1530then it may not be necessary to provide a translation for that value
1531from C to Perl.
1532
1533Identify the pointers in the C function parameter lists and return
beb31b0b
GS
1534values. Some pointers may be used to implement input/output or
1535output parameters, they can be handled in XS with the C<&> unary operator,
1536and, possibly, using the NO_INIT keyword.
1537Some others will require handling of types like C<int *>, and one needs
1538to decide what a useful Perl translation will do in such a case. When
1539the semantic is clear, it is advisable to put the translation into a typemap
1540file.
a0d0e21e
LW
1541
1542Identify the structures used by the C functions. In many
1543cases it may be helpful to use the T_PTROBJ typemap for
1544these structures so they can be manipulated by Perl as
beb31b0b
GS
1545blessed objects. (This is handled automatically by C<h2xs -x>.)
1546
1547If the same C type is used in several different contexts which require
1548different translations, C<typedef> several new types mapped to this C type,
1549and create separate F<typemap> entries for these new types. Use these
1550types in declarations of return type and parameters to XSUBs.
a0d0e21e 1551
a0d0e21e
LW
1552=head2 Perl Objects And C Structures
1553
1554When dealing with C structures one should select either
1555B<T_PTROBJ> or B<T_PTRREF> for the XS type. Both types are
1556designed to handle pointers to complex objects. The
1557T_PTRREF type will allow the Perl object to be unblessed
1558while the T_PTROBJ type requires that the object be blessed.
1559By using T_PTROBJ one can achieve a form of type-checking
d1b91892 1560because the XSUB will attempt to verify that the Perl object
a0d0e21e
LW
1561is of the expected type.
1562
1563The following XS code shows the getnetconfigent() function which is used
8e07c86e 1564with ONC+ TIRPC. The getnetconfigent() function will return a pointer to a
a0d0e21e
LW
1565C structure and has the C prototype shown below. The example will
1566demonstrate how the C pointer will become a Perl reference. Perl will
1567consider this reference to be a pointer to a blessed object and will
1568attempt to call a destructor for the object. A destructor will be
1569provided in the XS source to free the memory used by getnetconfigent().
1570Destructors in XS can be created by specifying an XSUB function whose name
1571ends with the word B<DESTROY>. XS destructors can be used to free memory
1572which may have been malloc'd by another XSUB.
1573
1574 struct netconfig *getnetconfigent(const char *netid);
1575
1576A C<typedef> will be created for C<struct netconfig>. The Perl
1577object will be blessed in a class matching the name of the C
1578type, with the tag C<Ptr> appended, and the name should not
1579have embedded spaces if it will be a Perl package name. The
1580destructor will be placed in a class corresponding to the
1581class of the object and the PREFIX keyword will be used to
1582trim the name to the word DESTROY as Perl will expect.
1583
1584 typedef struct netconfig Netconfig;
1585
1586 MODULE = RPC PACKAGE = RPC
1587
1588 Netconfig *
1589 getnetconfigent(netid)
8e07c86e 1590 char *netid
a0d0e21e
LW
1591
1592 MODULE = RPC PACKAGE = NetconfigPtr PREFIX = rpcb_
1593
1594 void
1595 rpcb_DESTROY(netconf)
8e07c86e 1596 Netconfig *netconf
beb31b0b 1597 CODE:
a0d0e21e
LW
1598 printf("Now in NetconfigPtr::DESTROY\n");
1599 free( netconf );
1600
1601This example requires the following typemap entry. Consult the typemap
1602section for more information about adding new typemaps for an extension.
1603
1604 TYPEMAP
1605 Netconfig * T_PTROBJ
1606
1607This example will be used with the following Perl statements.
1608
1609 use RPC;
1610 $netconf = getnetconfigent("udp");
1611
1612When Perl destroys the object referenced by $netconf it will send the
1613object to the supplied XSUB DESTROY function. Perl cannot determine, and
1614does not care, that this object is a C struct and not a Perl object. In
1615this sense, there is no difference between the object created by the
1616getnetconfigent() XSUB and an object created by a normal Perl subroutine.
1617
a0d0e21e
LW
1618=head2 The Typemap
1619
1620The typemap is a collection of code fragments which are used by the B<xsubpp>
1621compiler to map C function parameters and values to Perl values. The
7817ba4d 1622typemap file may consist of three sections labelled C<TYPEMAP>, C<INPUT>, and
beb31b0b
GS
1623C<OUTPUT>. An unlabelled initial section is assumed to be a C<TYPEMAP>
1624section. The INPUT section tells
7e9d670d 1625the compiler how to translate Perl values
a0d0e21e
LW
1626into variables of certain C types. The OUTPUT section tells the compiler
1627how to translate the values from certain C types into values Perl can
1628understand. The TYPEMAP section tells the compiler which of the INPUT and
1629OUTPUT code fragments should be used to map a given C type to a Perl value.
7e9d670d
GS
1630The section labels C<TYPEMAP>, C<INPUT>, or C<OUTPUT> must begin
1631in the first column on a line by themselves, and must be in uppercase.
a0d0e21e 1632
dcd2ee75
YST
1633The default typemap in the C<lib/ExtUtils> directory of the Perl source
1634contains many useful types which can be used by Perl extensions. Some
1635extensions define additional typemaps which they keep in their own directory.
1636These additional typemaps may reference INPUT and OUTPUT maps in the main
a0d0e21e
LW
1637typemap. The B<xsubpp> compiler will allow the extension's own typemap to
1638override any mappings which are in the default typemap.
1639
1640Most extensions which require a custom typemap will need only the TYPEMAP
1641section of the typemap file. The custom typemap used in the
1642getnetconfigent() example shown earlier demonstrates what may be the typical
1643use of extension typemaps. That typemap is used to equate a C structure
1644with the T_PTROBJ typemap. The typemap used by getnetconfigent() is shown
1645here. Note that the C type is separated from the XS type with a tab and
1646that the C unary operator C<*> is considered to be a part of the C type name.
1647
beb31b0b
GS
1648 TYPEMAP
1649 Netconfig *<tab>T_PTROBJ
a0d0e21e 1650
1748e8dd
RS
1651Here's a more complicated example: suppose that you wanted C<struct
1652netconfig> to be blessed into the class C<Net::Config>. One way to do
1653this is to use underscores (_) to separate package names, as follows:
1654
1655 typedef struct netconfig * Net_Config;
1656
1657And then provide a typemap entry C<T_PTROBJ_SPECIAL> that maps underscores to
1658double-colons (::), and declare C<Net_Config> to be of that type:
1659
1660
1661 TYPEMAP
1662 Net_Config T_PTROBJ_SPECIAL
1663
1664 INPUT
1665 T_PTROBJ_SPECIAL
1666 if (sv_derived_from($arg, \"${(my $ntt=$ntype)=~s/_/::/g;\$ntt}\")) {
1667 IV tmp = SvIV((SV*)SvRV($arg));
1668 $var = ($type) tmp;
1669 }
1670 else
1671 croak(\"$var is not of type ${(my $ntt=$ntype)=~s/_/::/g;\$ntt}\")
1672
1673 OUTPUT
1674 T_PTROBJ_SPECIAL
1675 sv_setref_pv($arg, \"${(my $ntt=$ntype)=~s/_/::/g;\$ntt}\",
1676 (void*)$var);
1677
1678The INPUT and OUTPUT sections substitute underscores for double-colons
1679on the fly, giving the desired effect. This example demonstrates some
1680of the power and versatility of the typemap facility.
1681
a0d0e21e
LW
1682=head1 EXAMPLES
1683
1684File C<RPC.xs>: Interface to some ONC+ RPC bind library functions.
1685
1686 #include "EXTERN.h"
1687 #include "perl.h"
1688 #include "XSUB.h"
1689
1690 #include <rpc/rpc.h>
1691
1692 typedef struct netconfig Netconfig;
1693
1694 MODULE = RPC PACKAGE = RPC
1695
e7ea3e70 1696 SV *
a0d0e21e 1697 rpcb_gettime(host="localhost")
8e07c86e 1698 char *host
beb31b0b 1699 PREINIT:
a0d0e21e 1700 time_t timep;
beb31b0b 1701 CODE:
a0d0e21e
LW
1702 ST(0) = sv_newmortal();
1703 if( rpcb_gettime( host, &timep ) )
1704 sv_setnv( ST(0), (double)timep );
a0d0e21e
LW
1705
1706 Netconfig *
1707 getnetconfigent(netid="udp")
8e07c86e 1708 char *netid
a0d0e21e
LW
1709
1710 MODULE = RPC PACKAGE = NetconfigPtr PREFIX = rpcb_
1711
1712 void
1713 rpcb_DESTROY(netconf)
8e07c86e 1714 Netconfig *netconf
beb31b0b 1715 CODE:
a0d0e21e
LW
1716 printf("NetconfigPtr::DESTROY\n");
1717 free( netconf );
1718
1719File C<typemap>: Custom typemap for RPC.xs.
1720
1721 TYPEMAP
1722 Netconfig * T_PTROBJ
1723
1724File C<RPC.pm>: Perl module for the RPC extension.
1725
1726 package RPC;
1727
1728 require Exporter;
1729 require DynaLoader;
1730 @ISA = qw(Exporter DynaLoader);
1731 @EXPORT = qw(rpcb_gettime getnetconfigent);
1732
1733 bootstrap RPC;
1734 1;
1735
1736File C<rpctest.pl>: Perl test program for the RPC extension.
1737
1738 use RPC;
1739
1740 $netconf = getnetconfigent();
1741 $a = rpcb_gettime();
1742 print "time = $a\n";
1743 print "netconf = $netconf\n";
1744
1745 $netconf = getnetconfigent("tcp");
1746 $a = rpcb_gettime("poplar");
1747 print "time = $a\n";
1748 print "netconf = $netconf\n";
1749
1750
c07a80fd
PP
1751=head1 XS VERSION
1752
f27cfbbe 1753This document covers features supported by C<xsubpp> 1.935.
c07a80fd 1754
a0d0e21e
LW
1755=head1 AUTHOR
1756
beb31b0b
GS
1757Originally written by Dean Roehrich <F<roehrich@cray.com>>.
1758
7f2de2d2 1759Maintained since 1996 by The Perl Porters <F<perlbug@perl.org>>.