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