This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
1. Add section to perlxs.pod describing that the refcount of AVs/HVs
[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 278
c4e79b56
MHM
279=head2 Returning SVs, AVs and HVs through RETVAL
280
281When you're using RETVAL to return an C<SV *>, there's some magic
282going on behind the scenes that should be mentioned. When you're
283manipulating the argument stack using the ST(x) macro, for example,
284you usually have to pay special attention to reference counts. (For
285more about reference counts, see L<perlguts>.) To make your life
286easier, the typemap file automatically makes C<RETVAL> mortal when
287you're returning an C<SV *>. Thus, the following two XSUBs are more
288or less equivalent:
289
290 void
291 alpha()
292 PPCODE:
293 ST(0) = newSVpv("Hello World",0);
294 sv_2mortal(ST(0));
295 XSRETURN(1);
296
297 SV *
298 beta()
299 CODE:
300 RETVAL = newSVpv("Hello World",0);
301 OUTPUT:
302 RETVAL
303
304This is quite useful as it usually improves readability. While
305this works fine for an C<SV *>, it's unfortunately not as easy
306to have C<AV *> or C<HV *> as a return value. You I<should> be
307able to write:
308
309 AV *
310 array()
311 CODE:
312 RETVAL = newAV();
313 /* do something with RETVAL */
314 OUTPUT:
315 RETVAL
316
317But due to an unfixable bug (fixing it would break lots of existing
318CPAN modules) in the typemap file, the reference count of the C<AV *>
319is not properly decremented. Thus, the above XSUB would leak memory
320whenever it is being called. The same problem exists for C<HV *>.
321
322When you're returning an C<AV *> or a C<HV *>, you have make sure
323their reference count is decremented by making the AV or HV mortal:
324
325 AV *
326 array()
327 CODE:
328 RETVAL = newAV();
329 sv_2mortal((SV*)RETVAL);
330 /* do something with RETVAL */
331 OUTPUT:
332 RETVAL
333
334And also remember that you don't have to do this for an C<SV *>.
335
a0d0e21e
LW
336=head2 The MODULE Keyword
337
7817ba4d
NC
338The MODULE keyword is used to start the XS code and to specify the package
339of the functions which are being defined. All text preceding the first
340MODULE keyword is considered C code and is passed through to the output with
341POD stripped, but otherwise untouched. Every XS module will have a
342bootstrap function which is used to hook the XSUBs into Perl. The package
343name of this bootstrap function will match the value of the last MODULE
344statement in the XS source files. The value of MODULE should always remain
345constant within the same XS file, though this is not required.
a0d0e21e
LW
346
347The following example will start the XS code and will place
348all functions in a package named RPC.
349
350 MODULE = RPC
351
352=head2 The PACKAGE Keyword
353
354When functions within an XS source file must be separated into packages
355the PACKAGE keyword should be used. This keyword is used with the MODULE
356keyword and must follow immediately after it when used.
357
358 MODULE = RPC PACKAGE = RPC
359
360 [ XS code in package RPC ]
361
362 MODULE = RPC PACKAGE = RPCB
363
364 [ XS code in package RPCB ]
365
366 MODULE = RPC PACKAGE = RPC
367
368 [ XS code in package RPC ]
369
a2acea2c
LC
370The same package name can be used more than once, allowing for
371non-contiguous code. This is useful if you have a stronger ordering
372principle than package names.
373
a0d0e21e
LW
374Although this keyword is optional and in some cases provides redundant
375information it should always be used. This keyword will ensure that the
376XSUBs appear in the desired package.
377
378=head2 The PREFIX Keyword
379
380The PREFIX keyword designates prefixes which should be
381removed from the Perl function names. If the C function is
382C<rpcb_gettime()> and the PREFIX value is C<rpcb_> then Perl will
383see this function as C<gettime()>.
384
385This keyword should follow the PACKAGE keyword when used.
386If PACKAGE is not used then PREFIX should follow the MODULE
387keyword.
388
389 MODULE = RPC PREFIX = rpc_
390
391 MODULE = RPC PACKAGE = RPCB PREFIX = rpcb_
392
393=head2 The OUTPUT: Keyword
394
395The OUTPUT: keyword indicates that certain function parameters should be
396updated (new values made visible to Perl) when the XSUB terminates or that
397certain values should be returned to the calling Perl function. For
beb31b0b
GS
398simple functions which have no CODE: or PPCODE: section,
399such as the sin() function above, the RETVAL variable is
400automatically designated as an output value. For more complex functions
a0d0e21e
LW
401the B<xsubpp> compiler will need help to determine which variables are output
402variables.
403
404This keyword will normally be used to complement the CODE: keyword.
405The RETVAL variable is not recognized as an output variable when the
406CODE: keyword is present. The OUTPUT: keyword is used in this
407situation to tell the compiler that RETVAL really is an output
408variable.
409
410The OUTPUT: keyword can also be used to indicate that function parameters
411are output variables. This may be necessary when a parameter has been
412modified within the function and the programmer would like the update to
8e07c86e 413be seen by Perl.
a0d0e21e
LW
414
415 bool_t
416 rpcb_gettime(host,timep)
8e07c86e
AD
417 char *host
418 time_t &timep
beb31b0b 419 OUTPUT:
a0d0e21e
LW
420 timep
421
422The OUTPUT: keyword will also allow an output parameter to
423be mapped to a matching piece of code rather than to a
ef50df4b 424typemap.
a0d0e21e
LW
425
426 bool_t
427 rpcb_gettime(host,timep)
8e07c86e
AD
428 char *host
429 time_t &timep
beb31b0b 430 OUTPUT:
ef50df4b
GS
431 timep sv_setnv(ST(1), (double)timep);
432
433B<xsubpp> emits an automatic C<SvSETMAGIC()> for all parameters in the
434OUTPUT section of the XSUB, except RETVAL. This is the usually desired
435behavior, as it takes care of properly invoking 'set' magic on output
436parameters (needed for hash or array element parameters that must be
437created if they didn't exist). If for some reason, this behavior is
438not desired, the OUTPUT section may contain a C<SETMAGIC: DISABLE> line
439to disable it for the remainder of the parameters in the OUTPUT section.
440Likewise, C<SETMAGIC: ENABLE> can be used to reenable it for the
441remainder of the OUTPUT section. See L<perlguts> for more details
442about 'set' magic.
a0d0e21e 443
9e24e6f2
IZ
444=head2 The NO_OUTPUT Keyword
445
446The NO_OUTPUT can be placed as the first token of the XSUB. This keyword
447indicates that while the C subroutine we provide an interface to has
448a non-C<void> return type, the return value of this C subroutine should not
449be returned from the generated Perl subroutine.
450
451With this keyword present L<The RETVAL Variable> is created, and in the
452generated call to the subroutine this variable is assigned to, but the value
453of this variable is not going to be used in the auto-generated code.
454
455This keyword makes sense only if C<RETVAL> is going to be accessed by the
456user-supplied code. It is especially useful to make a function interface
457more Perl-like, especially when the C return value is just an error condition
458indicator. For example,
459
460 NO_OUTPUT int
461 delete_file(char *name)
375cc10d 462 POSTCALL:
9e24e6f2
IZ
463 if (RETVAL != 0)
464 croak("Error %d while deleting file '%s'", RETVAL, name);
465
466Here the generated XS function returns nothing on success, and will die()
467with a meaningful error message on error.
468
a0d0e21e
LW
469=head2 The CODE: Keyword
470
471This keyword is used in more complicated XSUBs which require
472special handling for the C function. The RETVAL variable is
beb31b0b
GS
473still declared, but it will not be returned unless it is specified
474in the OUTPUT: section.
a0d0e21e
LW
475
476The following XSUB is for a C function which requires special handling of
477its parameters. The Perl usage is given first.
478
479 $status = rpcb_gettime( "localhost", $timep );
480
54310121 481The XSUB follows.
a0d0e21e 482
d1b91892
AD
483 bool_t
484 rpcb_gettime(host,timep)
8e07c86e
AD
485 char *host
486 time_t timep
beb31b0b 487 CODE:
a0d0e21e 488 RETVAL = rpcb_gettime( host, &timep );
beb31b0b 489 OUTPUT:
a0d0e21e
LW
490 timep
491 RETVAL
492
c07a80fd
PP
493=head2 The INIT: Keyword
494
495The INIT: keyword allows initialization to be inserted into the XSUB before
496the compiler generates the call to the C function. Unlike the CODE: keyword
497above, this keyword does not affect the way the compiler handles RETVAL.
498
499 bool_t
500 rpcb_gettime(host,timep)
501 char *host
502 time_t &timep
beb31b0b 503 INIT:
c07a80fd 504 printf("# Host is %s\n", host );
beb31b0b 505 OUTPUT:
c07a80fd 506 timep
a0d0e21e 507
beb31b0b
GS
508Another use for the INIT: section is to check for preconditions before
509making a call to the C function:
510
511 long long
512 lldiv(a,b)
513 long long a
514 long long b
515 INIT:
516 if (a == 0 && b == 0)
517 XSRETURN_UNDEF;
518 if (b == 0)
519 croak("lldiv: cannot divide by 0");
520
a0d0e21e
LW
521=head2 The NO_INIT Keyword
522
523The NO_INIT keyword is used to indicate that a function
54310121 524parameter is being used only as an output value. The B<xsubpp>
a0d0e21e
LW
525compiler will normally generate code to read the values of
526all function parameters from the argument stack and assign
527them to C variables upon entry to the function. NO_INIT
528will tell the compiler that some parameters will be used for
529output rather than for input and that they will be handled
530before the function terminates.
531
532The following example shows a variation of the rpcb_gettime() function.
54310121 533This function uses the timep variable only as an output variable and does
a0d0e21e
LW
534not care about its initial contents.
535
536 bool_t
537 rpcb_gettime(host,timep)
8e07c86e
AD
538 char *host
539 time_t &timep = NO_INIT
beb31b0b 540 OUTPUT:
a0d0e21e
LW
541 timep
542
543=head2 Initializing Function Parameters
544
beb31b0b
GS
545C function parameters are normally initialized with their values from
546the argument stack (which in turn contains the parameters that were
547passed to the XSUB from Perl). The typemaps contain the
548code segments which are used to translate the Perl values to
a0d0e21e 549the C parameters. The programmer, however, is allowed to
7ad6fb0b 550override the typemaps and supply alternate (or additional)
beb31b0b
GS
551initialization code. Initialization code starts with the first
552C<=>, C<;> or C<+> on a line in the INPUT: section. The only
553exception happens if this C<;> terminates the line, then this C<;>
554is quietly ignored.
a0d0e21e
LW
555
556The following code demonstrates how to supply initialization code for
7ad6fb0b
TM
557function parameters. The initialization code is eval'd within double
558quotes by the compiler before it is added to the output so anything
559which should be interpreted literally [mainly C<$>, C<@>, or C<\\>]
19799a22
GS
560must be protected with backslashes. The variables $var, $arg,
561and $type can be used as in typemaps.
a0d0e21e
LW
562
563 bool_t
564 rpcb_gettime(host,timep)
9cde0e7f 565 char *host = (char *)SvPV($arg,PL_na);
8e07c86e 566 time_t &timep = 0;
beb31b0b 567 OUTPUT:
a0d0e21e
LW
568 timep
569
570This should not be used to supply default values for parameters. One
571would normally use this when a function parameter must be processed by
572another library function before it can be used. Default parameters are
573covered in the next section.
574
beb31b0b
GS
575If the initialization begins with C<=>, then it is output in
576the declaration for the input variable, replacing the initialization
577supplied by the typemap. If the initialization
578begins with C<;> or C<+>, then it is performed after
579all of the input variables have been declared. In the C<;>
580case the initialization normally supplied by the typemap is not performed.
581For the C<+> case, the declaration for the variable will include the
582initialization from the typemap. A global
c2611fb3 583variable, C<%v>, is available for the truly rare case where
7ad6fb0b
TM
584information from one initialization is needed in another
585initialization.
586
beb31b0b
GS
587Here's a truly obscure example:
588
7ad6fb0b
TM
589 bool_t
590 rpcb_gettime(host,timep)
beb31b0b
GS
591 time_t &timep ; /* \$v{timep}=@{[$v{timep}=$arg]} */
592 char *host + SvOK($v{timep}) ? SvPV($arg,PL_na) : NULL;
593 OUTPUT:
7ad6fb0b
TM
594 timep
595
beb31b0b
GS
596The construct C<\$v{timep}=@{[$v{timep}=$arg]}> used in the above
597example has a two-fold purpose: first, when this line is processed by
598B<xsubpp>, the Perl snippet C<$v{timep}=$arg> is evaluated. Second,
599the text of the evaluated snippet is output into the generated C file
600(inside a C comment)! During the processing of C<char *host> line,
601$arg will evaluate to C<ST(0)>, and C<$v{timep}> will evaluate to
602C<ST(1)>.
603
a0d0e21e
LW
604=head2 Default Parameter Values
605
4628e4f8
GS
606Default values for XSUB arguments can be specified by placing an
607assignment statement in the parameter list. The default value may
a104f515 608be a number, a string or the special string C<NO_INIT>. Defaults should
a0d0e21e
LW
609always be used on the right-most parameters only.
610
611To allow the XSUB for rpcb_gettime() to have a default host
612value the parameters to the XSUB could be rearranged. The
613XSUB will then call the real rpcb_gettime() function with
beb31b0b
GS
614the parameters in the correct order. This XSUB can be called
615from Perl with either of the following statements:
a0d0e21e
LW
616
617 $status = rpcb_gettime( $timep, $host );
618
619 $status = rpcb_gettime( $timep );
620
621The XSUB will look like the code which follows. A CODE:
622block is used to call the real rpcb_gettime() function with
623the parameters in the correct order for that function.
624
625 bool_t
626 rpcb_gettime(timep,host="localhost")
8e07c86e
AD
627 char *host
628 time_t timep = NO_INIT
beb31b0b 629 CODE:
a0d0e21e 630 RETVAL = rpcb_gettime( host, &timep );
beb31b0b 631 OUTPUT:
a0d0e21e
LW
632 timep
633 RETVAL
634
c07a80fd
PP
635=head2 The PREINIT: Keyword
636
beb31b0b 637The PREINIT: keyword allows extra variables to be declared immediately
a2293a43 638before or after the declarations of the parameters from the INPUT: section
beb31b0b
GS
639are emitted.
640
641If a variable is declared inside a CODE: section it will follow any typemap
642code that is emitted for the input parameters. This may result in the
643declaration ending up after C code, which is C syntax error. Similar
644errors may happen with an explicit C<;>-type or C<+>-type initialization of
645parameters is used (see L<"Initializing Function Parameters">). Declaring
646these variables in an INIT: section will not help.
647
648In such cases, to force an additional variable to be declared together
649with declarations of other variables, place the declaration into a
650PREINIT: section. The PREINIT: keyword may be used one or more times
651within an XSUB.
c07a80fd
PP
652
653The following examples are equivalent, but if the code is using complex
654typemaps then the first example is safer.
655
656 bool_t
657 rpcb_gettime(timep)
658 time_t timep = NO_INIT
beb31b0b 659 PREINIT:
c07a80fd 660 char *host = "localhost";
beb31b0b 661 CODE:
c07a80fd 662 RETVAL = rpcb_gettime( host, &timep );
beb31b0b 663 OUTPUT:
c07a80fd
PP
664 timep
665 RETVAL
666
beb31b0b
GS
667For this particular case an INIT: keyword would generate the
668same C code as the PREINIT: keyword. Another correct, but error-prone example:
c07a80fd
PP
669
670 bool_t
671 rpcb_gettime(timep)
672 time_t timep = NO_INIT
beb31b0b 673 CODE:
c07a80fd
PP
674 char *host = "localhost";
675 RETVAL = rpcb_gettime( host, &timep );
beb31b0b
GS
676 OUTPUT:
677 timep
678 RETVAL
679
680Another way to declare C<host> is to use a C block in the CODE: section:
681
682 bool_t
683 rpcb_gettime(timep)
684 time_t timep = NO_INIT
685 CODE:
686 {
687 char *host = "localhost";
688 RETVAL = rpcb_gettime( host, &timep );
689 }
690 OUTPUT:
691 timep
692 RETVAL
693
694The ability to put additional declarations before the typemap entries are
695processed is very handy in the cases when typemap conversions manipulate
696some global state:
697
698 MyObject
699 mutate(o)
700 PREINIT:
701 MyState st = global_state;
702 INPUT:
703 MyObject o;
704 CLEANUP:
705 reset_to(global_state, st);
706
707Here we suppose that conversion to C<MyObject> in the INPUT: section and from
708MyObject when processing RETVAL will modify a global variable C<global_state>.
709After these conversions are performed, we restore the old value of
710C<global_state> (to avoid memory leaks, for example).
711
712There is another way to trade clarity for compactness: INPUT sections allow
713declaration of C variables which do not appear in the parameter list of
714a subroutine. Thus the above code for mutate() can be rewritten as
715
716 MyObject
717 mutate(o)
718 MyState st = global_state;
719 MyObject o;
720 CLEANUP:
721 reset_to(global_state, st);
722
723and the code for rpcb_gettime() can be rewritten as
724
725 bool_t
726 rpcb_gettime(timep)
727 time_t timep = NO_INIT
728 char *host = "localhost";
729 C_ARGS:
730 host, &timep
731 OUTPUT:
c07a80fd
PP
732 timep
733 RETVAL
734
84287afe
PP
735=head2 The SCOPE: Keyword
736
737The SCOPE: keyword allows scoping to be enabled for a particular XSUB. If
738enabled, the XSUB will invoke ENTER and LEAVE automatically.
739
740To support potentially complex type mappings, if a typemap entry used
beb31b0b
GS
741by an XSUB contains a comment like C</*scope*/> then scoping will
742be automatically enabled for that XSUB.
84287afe
PP
743
744To enable scoping:
745
746 SCOPE: ENABLE
747
748To disable scoping:
749
750 SCOPE: DISABLE
751
c07a80fd
PP
752=head2 The INPUT: Keyword
753
754The XSUB's parameters are usually evaluated immediately after entering the
755XSUB. The INPUT: keyword can be used to force those parameters to be
756evaluated a little later. The INPUT: keyword can be used multiple times
757within an XSUB and can be used to list one or more input variables. This
758keyword is used with the PREINIT: keyword.
759
760The following example shows how the input parameter C<timep> can be
761evaluated late, after a PREINIT.
762
763 bool_t
764 rpcb_gettime(host,timep)
765 char *host
beb31b0b 766 PREINIT:
c07a80fd 767 time_t tt;
beb31b0b 768 INPUT:
c07a80fd 769 time_t timep
beb31b0b 770 CODE:
c07a80fd
PP
771 RETVAL = rpcb_gettime( host, &tt );
772 timep = tt;
beb31b0b 773 OUTPUT:
c07a80fd
PP
774 timep
775 RETVAL
776
777The next example shows each input parameter evaluated late.
778
779 bool_t
780 rpcb_gettime(host,timep)
beb31b0b 781 PREINIT:
c07a80fd 782 time_t tt;
beb31b0b 783 INPUT:
c07a80fd 784 char *host
beb31b0b 785 PREINIT:
c07a80fd 786 char *h;
beb31b0b 787 INPUT:
c07a80fd 788 time_t timep
beb31b0b 789 CODE:
c07a80fd
PP
790 h = host;
791 RETVAL = rpcb_gettime( h, &tt );
792 timep = tt;
beb31b0b
GS
793 OUTPUT:
794 timep
795 RETVAL
796
797Since INPUT sections allow declaration of C variables which do not appear
798in the parameter list of a subroutine, this may be shortened to:
799
800 bool_t
801 rpcb_gettime(host,timep)
802 time_t tt;
803 char *host;
804 char *h = host;
805 time_t timep;
806 CODE:
807 RETVAL = rpcb_gettime( h, &tt );
808 timep = tt;
809 OUTPUT:
c07a80fd
PP
810 timep
811 RETVAL
812
beb31b0b
GS
813(We used our knowledge that input conversion for C<char *> is a "simple" one,
814thus C<host> is initialized on the declaration line, and our assignment
815C<h = host> is not performed too early. Otherwise one would need to have the
816assignment C<h = host> in a CODE: or INIT: section.)
817
cb79badd 818=head2 The IN/OUTLIST/IN_OUTLIST/OUT/IN_OUT Keywords
9e24e6f2
IZ
819
820In the list of parameters for an XSUB, one can precede parameter names
cb79badd
IZ
821by the C<IN>/C<OUTLIST>/C<IN_OUTLIST>/C<OUT>/C<IN_OUT> keywords.
822C<IN> keyword is the default, the other keywords indicate how the Perl
823interface should differ from the C interface.
824
825Parameters preceded by C<OUTLIST>/C<IN_OUTLIST>/C<OUT>/C<IN_OUT>
826keywords are considered to be used by the C subroutine I<via
827pointers>. C<OUTLIST>/C<OUT> keywords indicate that the C subroutine
828does not inspect the memory pointed by this parameter, but will write
829through this pointer to provide additional return values.
830
831Parameters preceded by C<OUTLIST> keyword do not appear in the usage
832signature of the generated Perl function.
833
834Parameters preceded by C<IN_OUTLIST>/C<IN_OUT>/C<OUT> I<do> appear as
835parameters to the Perl function. With the exception of
836C<OUT>-parameters, these parameters are converted to the corresponding
837C type, then pointers to these data are given as arguments to the C
838function. It is expected that the C function will write through these
839pointers.
9e24e6f2
IZ
840
841The return list of the generated Perl function consists of the C return value
842from the function (unless the XSUB is of C<void> return type or
cb79badd
IZ
843C<The NO_OUTPUT Keyword> was used) followed by all the C<OUTLIST>
844and C<IN_OUTLIST> parameters (in the order of appearance). On the
845return from the XSUB the C<IN_OUT>/C<OUT> Perl parameter will be
846modified to have the values written by the C function.
847
848For example, an XSUB
9e24e6f2
IZ
849
850 void
851 day_month(OUTLIST day, IN unix_time, OUTLIST month)
852 int day
853 int unix_time
854 int month
855
856should be used from Perl as
857
858 my ($day, $month) = day_month(time);
859
860The C signature of the corresponding function should be
861
862 void day_month(int *day, int unix_time, int *month);
863
cb79badd
IZ
864The C<IN>/C<OUTLIST>/C<IN_OUTLIST>/C<IN_OUT>/C<OUT> keywords can be
865mixed with ANSI-style declarations, as in
9e24e6f2
IZ
866
867 void
868 day_month(OUTLIST int day, int unix_time, OUTLIST int month)
869
870(here the optional C<IN> keyword is omitted).
871
cb79badd 872The C<IN_OUT> parameters are identical with parameters introduced with
cea6626f
MS
873L<The & Unary Operator> and put into the C<OUTPUT:> section (see
874L<The OUTPUT: Keyword>). The C<IN_OUTLIST> parameters are very similar,
875the only difference being that the value C function writes through the
cb79badd
IZ
876pointer would not modify the Perl parameter, but is put in the output
877list.
878
879The C<OUTLIST>/C<OUT> parameter differ from C<IN_OUTLIST>/C<IN_OUT>
d1be9408 880parameters only by the initial value of the Perl parameter not
cb79badd
IZ
881being read (and not being given to the C function - which gets some
882garbage instead). For example, the same C function as above can be
883interfaced with as
884
885 void day_month(OUT int day, int unix_time, OUT int month);
886
887or
9e24e6f2
IZ
888
889 void
890 day_month(day, unix_time, month)
891 int &day = NO_INIT
892 int unix_time
893 int &month = NO_INIT
894 OUTPUT:
895 day
896 month
897
898However, the generated Perl function is called in very C-ish style:
899
900 my ($day, $month);
901 day_month($day, time, $month);
902
08ff138d
IZ
903=head2 The C<length(NAME)> Keyword
904
905If one of the input arguments to the C function is the length of a string
906argument C<NAME>, one can substitute the name of the length-argument by
907C<length(NAME)> in the XSUB declaration. This argument must be omited when
908the generated Perl function is called. E.g.,
909
910 void
911 dump_chars(char *s, short l)
912 {
913 short n = 0;
914 while (n < l) {
915 printf("s[%d] = \"\\%#03o\"\n", n, (int)s[n]);
916 n++;
917 }
918 }
919
920 MODULE = x PACKAGE = x
921
922 void dump_chars(char *s, short length(s))
923
924should be called as C<dump_chars($string)>.
925
926This directive is supported with ANSI-type function declarations only.
927
a0d0e21e
LW
928=head2 Variable-length Parameter Lists
929
930XSUBs can have variable-length parameter lists by specifying an ellipsis
931C<(...)> in the parameter list. This use of the ellipsis is similar to that
932found in ANSI C. The programmer is able to determine the number of
933arguments passed to the XSUB by examining the C<items> variable which the
934B<xsubpp> compiler supplies for all XSUBs. By using this mechanism one can
935create an XSUB which accepts a list of parameters of unknown length.
936
937The I<host> parameter for the rpcb_gettime() XSUB can be
938optional so the ellipsis can be used to indicate that the
939XSUB will take a variable number of parameters. Perl should
d1b91892 940be able to call this XSUB with either of the following statements.
a0d0e21e
LW
941
942 $status = rpcb_gettime( $timep, $host );
943
944 $status = rpcb_gettime( $timep );
945
946The XS code, with ellipsis, follows.
947
948 bool_t
949 rpcb_gettime(timep, ...)
8e07c86e 950 time_t timep = NO_INIT
beb31b0b 951 PREINIT:
a0d0e21e 952 char *host = "localhost";
2d8e6c8d 953 STRLEN n_a;
beb31b0b
GS
954 CODE:
955 if( items > 1 )
956 host = (char *)SvPV(ST(1), n_a);
957 RETVAL = rpcb_gettime( host, &timep );
958 OUTPUT:
a0d0e21e
LW
959 timep
960 RETVAL
961
cfc02341
IZ
962=head2 The C_ARGS: Keyword
963
964The C_ARGS: keyword allows creating of XSUBS which have different
965calling sequence from Perl than from C, without a need to write
beb31b0b 966CODE: or PPCODE: section. The contents of the C_ARGS: paragraph is
cfc02341
IZ
967put as the argument to the called C function without any change.
968
beb31b0b 969For example, suppose that a C function is declared as
cfc02341
IZ
970
971 symbolic nth_derivative(int n, symbolic function, int flags);
972
973and that the default flags are kept in a global C variable
974C<default_flags>. Suppose that you want to create an interface which
975is called as
976
977 $second_deriv = $function->nth_derivative(2);
978
979To do this, declare the XSUB as
980
981 symbolic
982 nth_derivative(function, n)
983 symbolic function
984 int n
beb31b0b 985 C_ARGS:
cfc02341
IZ
986 n, function, default_flags
987
a0d0e21e
LW
988=head2 The PPCODE: Keyword
989
990The PPCODE: keyword is an alternate form of the CODE: keyword and is used
991to tell the B<xsubpp> compiler that the programmer is supplying the code to
d1b91892 992control the argument stack for the XSUBs return values. Occasionally one
a0d0e21e
LW
993will want an XSUB to return a list of values rather than a single value.
994In these cases one must use PPCODE: and then explicitly push the list of
beb31b0b 995values on the stack. The PPCODE: and CODE: keywords should not be used
a0d0e21e
LW
996together within the same XSUB.
997
beb31b0b
GS
998The actual difference between PPCODE: and CODE: sections is in the
999initialization of C<SP> macro (which stands for the I<current> Perl
1000stack pointer), and in the handling of data on the stack when returning
1001from an XSUB. In CODE: sections SP preserves the value which was on
1002entry to the XSUB: SP is on the function pointer (which follows the
1003last parameter). In PPCODE: sections SP is moved backward to the
1004beginning of the parameter list, which allows C<PUSH*()> macros
1005to place output values in the place Perl expects them to be when
1006the XSUB returns back to Perl.
1007
1008The generated trailer for a CODE: section ensures that the number of return
1009values Perl will see is either 0 or 1 (depending on the C<void>ness of the
1010return value of the C function, and heuristics mentioned in
1011L<"The RETVAL Variable">). The trailer generated for a PPCODE: section
1012is based on the number of return values and on the number of times
1013C<SP> was updated by C<[X]PUSH*()> macros.
1014
1015Note that macros C<ST(i)>, C<XST_m*()> and C<XSRETURN*()> work equally
1016well in CODE: sections and PPCODE: sections.
1017
a0d0e21e
LW
1018The following XSUB will call the C rpcb_gettime() function
1019and will return its two output values, timep and status, to
1020Perl as a single list.
1021
d1b91892
AD
1022 void
1023 rpcb_gettime(host)
8e07c86e 1024 char *host
beb31b0b 1025 PREINIT:
a0d0e21e
LW
1026 time_t timep;
1027 bool_t status;
beb31b0b 1028 PPCODE:
a0d0e21e 1029 status = rpcb_gettime( host, &timep );
924508f0 1030 EXTEND(SP, 2);
cb1a09d0
AD
1031 PUSHs(sv_2mortal(newSViv(status)));
1032 PUSHs(sv_2mortal(newSViv(timep)));
a0d0e21e
LW
1033
1034Notice that the programmer must supply the C code necessary
1035to have the real rpcb_gettime() function called and to have
1036the return values properly placed on the argument stack.
1037
1038The C<void> return type for this function tells the B<xsubpp> compiler that
1039the RETVAL variable is not needed or used and that it should not be created.
1040In most scenarios the void return type should be used with the PPCODE:
1041directive.
1042
1043The EXTEND() macro is used to make room on the argument
1044stack for 2 return values. The PPCODE: directive causes the
924508f0 1045B<xsubpp> compiler to create a stack pointer available as C<SP>, and it
a0d0e21e
LW
1046is this pointer which is being used in the EXTEND() macro.
1047The values are then pushed onto the stack with the PUSHs()
1048macro.
1049
1050Now the rpcb_gettime() function can be used from Perl with
1051the following statement.
1052
1053 ($status, $timep) = rpcb_gettime("localhost");
1054
ef50df4b
GS
1055When handling output parameters with a PPCODE section, be sure to handle
1056'set' magic properly. See L<perlguts> for details about 'set' magic.
1057
a0d0e21e
LW
1058=head2 Returning Undef And Empty Lists
1059
5f05dabc 1060Occasionally the programmer will want to return simply
a0d0e21e
LW
1061C<undef> or an empty list if a function fails rather than a
1062separate status value. The rpcb_gettime() function offers
1063just this situation. If the function succeeds we would like
1064to have it return the time and if it fails we would like to
1065have undef returned. In the following Perl code the value
1066of $timep will either be undef or it will be a valid time.
1067
1068 $timep = rpcb_gettime( "localhost" );
1069
7b8d334a 1070The following XSUB uses the C<SV *> return type as a mnemonic only,
e7ea3e70 1071and uses a CODE: block to indicate to the compiler
a0d0e21e
LW
1072that the programmer has supplied all the necessary code. The
1073sv_newmortal() call will initialize the return value to undef, making that
1074the default return value.
1075
e7ea3e70 1076 SV *
a0d0e21e
LW
1077 rpcb_gettime(host)
1078 char * host
beb31b0b 1079 PREINIT:
a0d0e21e
LW
1080 time_t timep;
1081 bool_t x;
beb31b0b 1082 CODE:
a0d0e21e
LW
1083 ST(0) = sv_newmortal();
1084 if( rpcb_gettime( host, &timep ) )
1085 sv_setnv( ST(0), (double)timep);
a0d0e21e
LW
1086
1087The next example demonstrates how one would place an explicit undef in the
1088return value, should the need arise.
1089
e7ea3e70 1090 SV *
a0d0e21e
LW
1091 rpcb_gettime(host)
1092 char * host
beb31b0b 1093 PREINIT:
a0d0e21e
LW
1094 time_t timep;
1095 bool_t x;
beb31b0b 1096 CODE:
a0d0e21e
LW
1097 ST(0) = sv_newmortal();
1098 if( rpcb_gettime( host, &timep ) ){
1099 sv_setnv( ST(0), (double)timep);
1100 }
1101 else{
9cde0e7f 1102 ST(0) = &PL_sv_undef;
a0d0e21e 1103 }
a0d0e21e
LW
1104
1105To return an empty list one must use a PPCODE: block and
1106then not push return values on the stack.
1107
1108 void
1109 rpcb_gettime(host)
8e07c86e 1110 char *host
beb31b0b 1111 PREINIT:
a0d0e21e 1112 time_t timep;
beb31b0b 1113 PPCODE:
a0d0e21e 1114 if( rpcb_gettime( host, &timep ) )
cb1a09d0 1115 PUSHs(sv_2mortal(newSViv(timep)));
a0d0e21e 1116 else{
beb31b0b
GS
1117 /* Nothing pushed on stack, so an empty
1118 * list is implicitly returned. */
a0d0e21e 1119 }
a0d0e21e 1120
f27cfbbe
PP
1121Some people may be inclined to include an explicit C<return> in the above
1122XSUB, rather than letting control fall through to the end. In those
1123situations C<XSRETURN_EMPTY> should be used, instead. This will ensure that
8a2949d9
SB
1124the XSUB stack is properly adjusted. Consult L<perlapi> for other
1125C<XSRETURN> macros.
f27cfbbe 1126
beb31b0b
GS
1127Since C<XSRETURN_*> macros can be used with CODE blocks as well, one can
1128rewrite this example as:
1129
1130 int
1131 rpcb_gettime(host)
1132 char *host
1133 PREINIT:
1134 time_t timep;
1135 CODE:
1136 RETVAL = rpcb_gettime( host, &timep );
1137 if (RETVAL == 0)
1138 XSRETURN_UNDEF;
1139 OUTPUT:
1140 RETVAL
1141
375cc10d 1142In fact, one can put this check into a POSTCALL: section as well. Together
beb31b0b
GS
1143with PREINIT: simplifications, this leads to:
1144
1145 int
1146 rpcb_gettime(host)
1147 char *host
1148 time_t timep;
375cc10d 1149 POSTCALL:
beb31b0b
GS
1150 if (RETVAL == 0)
1151 XSRETURN_UNDEF;
1152
4633a7c4
LW
1153=head2 The REQUIRE: Keyword
1154
1155The REQUIRE: keyword is used to indicate the minimum version of the
1156B<xsubpp> compiler needed to compile the XS module. An XS module which
5f05dabc 1157contains the following statement will compile with only B<xsubpp> version
4633a7c4
LW
11581.922 or greater:
1159
1160 REQUIRE: 1.922
1161
a0d0e21e
LW
1162=head2 The CLEANUP: Keyword
1163
1164This keyword can be used when an XSUB requires special cleanup procedures
1165before it terminates. When the CLEANUP: keyword is used it must follow
1166any CODE:, PPCODE:, or OUTPUT: blocks which are present in the XSUB. The
1167code specified for the cleanup block will be added as the last statements
1168in the XSUB.
1169
375cc10d 1170=head2 The POSTCALL: Keyword
9e24e6f2
IZ
1171
1172This keyword can be used when an XSUB requires special procedures
375cc10d 1173executed after the C subroutine call is performed. When the POSTCALL:
9e24e6f2
IZ
1174keyword is used it must precede OUTPUT: and CLEANUP: blocks which are
1175present in the XSUB.
1176
375cc10d
IZ
1177See examples in L<"The NO_OUTPUT Keyword"> and L<"Returning Undef And Empty Lists">.
1178
1179The POSTCALL: block does not make a lot of sense when the C subroutine
9e24e6f2
IZ
1180call is supplied by user by providing either CODE: or PPCODE: section.
1181
a0d0e21e
LW
1182=head2 The BOOT: Keyword
1183
1184The BOOT: keyword is used to add code to the extension's bootstrap
1185function. The bootstrap function is generated by the B<xsubpp> compiler and
1186normally holds the statements necessary to register any XSUBs with Perl.
1187With the BOOT: keyword the programmer can tell the compiler to add extra
1188statements to the bootstrap function.
1189
1190This keyword may be used any time after the first MODULE keyword and should
1191appear on a line by itself. The first blank line after the keyword will
1192terminate the code block.
1193
1194 BOOT:
1195 # The following message will be printed when the
1196 # bootstrap function executes.
1197 printf("Hello from the bootstrap!\n");
1198
c07a80fd
PP
1199=head2 The VERSIONCHECK: Keyword
1200
1201The VERSIONCHECK: keyword corresponds to B<xsubpp>'s C<-versioncheck> and
5f05dabc 1202C<-noversioncheck> options. This keyword overrides the command line
c07a80fd
PP
1203options. Version checking is enabled by default. When version checking is
1204enabled the XS module will attempt to verify that its version matches the
1205version of the PM module.
1206
1207To enable version checking:
1208
1209 VERSIONCHECK: ENABLE
1210
1211To disable version checking:
1212
1213 VERSIONCHECK: DISABLE
1214
1215=head2 The PROTOTYPES: Keyword
1216
1217The PROTOTYPES: keyword corresponds to B<xsubpp>'s C<-prototypes> and
54310121 1218C<-noprototypes> options. This keyword overrides the command line options.
c07a80fd
PP
1219Prototypes are enabled by default. When prototypes are enabled XSUBs will
1220be given Perl prototypes. This keyword may be used multiple times in an XS
1221module to enable and disable prototypes for different parts of the module.
1222
1223To enable prototypes:
1224
1225 PROTOTYPES: ENABLE
1226
1227To disable prototypes:
1228
1229 PROTOTYPES: DISABLE
1230
1231=head2 The PROTOTYPE: Keyword
1232
1233This keyword is similar to the PROTOTYPES: keyword above but can be used to
1234force B<xsubpp> to use a specific prototype for the XSUB. This keyword
1235overrides all other prototype options and keywords but affects only the
1236current XSUB. Consult L<perlsub/Prototypes> for information about Perl
1237prototypes.
1238
1239 bool_t
1240 rpcb_gettime(timep, ...)
1241 time_t timep = NO_INIT
beb31b0b
GS
1242 PROTOTYPE: $;$
1243 PREINIT:
c07a80fd 1244 char *host = "localhost";
2d8e6c8d 1245 STRLEN n_a;
beb31b0b 1246 CODE:
c07a80fd 1247 if( items > 1 )
2d8e6c8d 1248 host = (char *)SvPV(ST(1), n_a);
c07a80fd 1249 RETVAL = rpcb_gettime( host, &timep );
beb31b0b 1250 OUTPUT:
c07a80fd
PP
1251 timep
1252 RETVAL
1253
dd76e73a
SB
1254If the prototypes are enabled, you can disable it locally for a given
1255XSUB as in the following example:
1256
1257 void
1258 rpcb_gettime_noproto()
1259 PROTOTYPE: DISABLE
1260 ...
1261
c07a80fd
PP
1262=head2 The ALIAS: Keyword
1263
cfc02341 1264The ALIAS: keyword allows an XSUB to have two or more unique Perl names
c07a80fd
PP
1265and to know which of those names was used when it was invoked. The Perl
1266names may be fully-qualified with package names. Each alias is given an
1267index. The compiler will setup a variable called C<ix> which contain the
1268index of the alias which was used. When the XSUB is called with its
1269declared name C<ix> will be 0.
1270
1271The following example will create aliases C<FOO::gettime()> and
1272C<BAR::getit()> for this function.
1273
1274 bool_t
1275 rpcb_gettime(host,timep)
1276 char *host
1277 time_t &timep
beb31b0b 1278 ALIAS:
c07a80fd
PP
1279 FOO::gettime = 1
1280 BAR::getit = 2
beb31b0b 1281 INIT:
c07a80fd 1282 printf("# ix = %d\n", ix );
beb31b0b 1283 OUTPUT:
c07a80fd
PP
1284 timep
1285
54162f5c
JP
1286=head2 The OVERLOAD: Keyword
1287
1288Instead of writing an overloaded interface using pure Perl, you
1289can also use the OVERLOAD keyword to define additional Perl names
1290for your functions (like the ALIAS: keyword above). However, the
1291overloaded functions must be defined with three parameters (except
1292for the nomethod() function which needs four parameters). If any
1293function has the OVERLOAD: keyword, several additional lines
1294will be defined in the c file generated by xsubpp in order to
1295register with the overload magic.
1296
1297Since blessed objects are actually stored as RV's, it is useful
1298to use the typemap features to preprocess parameters and extract
1299the actual SV stored within the blessed RV. See the sample for
1300T_PTROBJ_SPECIAL below.
1301
1302To use the OVERLOAD: keyword, create an XS function which takes
1303three input parameters ( or use the c style '...' definition) like
1304this:
1305
1306 SV *
1307 cmp (lobj, robj, swap)
1308 My_Module_obj lobj
1309 My_Module_obj robj
1310 IV swap
1311 OVERLOAD: cmp <=>
1312 { /* function defined here */}
1313
1314In this case, the function will overload both of the three way
1315comparison operators. For all overload operations using non-alpha
1316characters, you must type the parameter without quoting, seperating
1317multiple overloads with whitespace. Note that "" (the stringify
1318overload) should be entered as \"\" (i.e. escaped).
1319
30d6fba6
JP
1320=head2 The FALLBACK: Keyword
1321
1322In addition to the OVERLOAD keyword, if you need to control how
1323Perl autogenerates missing overloaded operators, you can set the
1324FALLBACK keyword in the module header section, like this:
1325
1326 MODULE = RPC PACKAGE = RPC
1327
1328 FALLBACK: TRUE
1329 ...
1330
1331where FALLBACK can take any of the three values TRUE, FALSE, or
1332UNDEF. If you do not set any FALLBACK value when using OVERLOAD,
1333it defaults to UNDEF. FALLBACK is not used except when one or
1334more functions using OVERLOAD have been defined. Please see
1335L<overload/Fallback> for more details.
1336
cfc02341
IZ
1337=head2 The INTERFACE: Keyword
1338
1339This keyword declares the current XSUB as a keeper of the given
1340calling signature. If some text follows this keyword, it is
1341considered as a list of functions which have this signature, and
beb31b0b 1342should be attached to the current XSUB.
cfc02341 1343
beb31b0b
GS
1344For example, if you have 4 C functions multiply(), divide(), add(),
1345subtract() all having the signature:
cfc02341
IZ
1346
1347 symbolic f(symbolic, symbolic);
1348
beb31b0b 1349you can make them all to use the same XSUB using this:
cfc02341
IZ
1350
1351 symbolic
1352 interface_s_ss(arg1, arg2)
1353 symbolic arg1
1354 symbolic arg2
1355 INTERFACE:
1356 multiply divide
1357 add subtract
1358
beb31b0b
GS
1359(This is the complete XSUB code for 4 Perl functions!) Four generated
1360Perl function share names with corresponding C functions.
1361
1362The advantage of this approach comparing to ALIAS: keyword is that there
1363is no need to code a switch statement, each Perl function (which shares
1364the same XSUB) knows which C function it should call. Additionally, one
cfc02341 1365can attach an extra function remainder() at runtime by using
beb31b0b 1366
cfc02341
IZ
1367 CV *mycv = newXSproto("Symbolic::remainder",
1368 XS_Symbolic_interface_s_ss, __FILE__, "$$");
1369 XSINTERFACE_FUNC_SET(mycv, remainder);
1370
beb31b0b
GS
1371say, from another XSUB. (This example supposes that there was no
1372INTERFACE_MACRO: section, otherwise one needs to use something else instead of
1373C<XSINTERFACE_FUNC_SET>, see the next section.)
cfc02341
IZ
1374
1375=head2 The INTERFACE_MACRO: Keyword
1376
1377This keyword allows one to define an INTERFACE using a different way
1378to extract a function pointer from an XSUB. The text which follows
1379this keyword should give the name of macros which would extract/set a
1380function pointer. The extractor macro is given return type, C<CV*>,
1381and C<XSANY.any_dptr> for this C<CV*>. The setter macro is given cv,
1382and the function pointer.
1383
1384The default value is C<XSINTERFACE_FUNC> and C<XSINTERFACE_FUNC_SET>.
1385An INTERFACE keyword with an empty list of functions can be omitted if
1386INTERFACE_MACRO keyword is used.
1387
1388Suppose that in the previous example functions pointers for
1389multiply(), divide(), add(), subtract() are kept in a global C array
1390C<fp[]> with offsets being C<multiply_off>, C<divide_off>, C<add_off>,
1391C<subtract_off>. Then one can use
1392
1393 #define XSINTERFACE_FUNC_BYOFFSET(ret,cv,f) \
1394 ((XSINTERFACE_CVT(ret,))fp[CvXSUBANY(cv).any_i32])
1395 #define XSINTERFACE_FUNC_BYOFFSET_set(cv,f) \
1396 CvXSUBANY(cv).any_i32 = CAT2( f, _off )
1397
1398in C section,
1399
1400 symbolic
1401 interface_s_ss(arg1, arg2)
1402 symbolic arg1
1403 symbolic arg2
beb31b0b 1404 INTERFACE_MACRO:
cfc02341
IZ
1405 XSINTERFACE_FUNC_BYOFFSET
1406 XSINTERFACE_FUNC_BYOFFSET_set
beb31b0b 1407 INTERFACE:
cfc02341
IZ
1408 multiply divide
1409 add subtract
1410
1411in XSUB section.
1412
c07a80fd
PP
1413=head2 The INCLUDE: Keyword
1414
1415This keyword can be used to pull other files into the XS module. The other
1416files may have XS code. INCLUDE: can also be used to run a command to
1417generate the XS code to be pulled into the module.
1418
1419The file F<Rpcb1.xsh> contains our C<rpcb_gettime()> function:
1420
1421 bool_t
1422 rpcb_gettime(host,timep)
1423 char *host
1424 time_t &timep
beb31b0b 1425 OUTPUT:
c07a80fd
PP
1426 timep
1427
1428The XS module can use INCLUDE: to pull that file into it.
1429
1430 INCLUDE: Rpcb1.xsh
1431
1432If the parameters to the INCLUDE: keyword are followed by a pipe (C<|>) then
1433the compiler will interpret the parameters as a command.
1434
1435 INCLUDE: cat Rpcb1.xsh |
1436
1437=head2 The CASE: Keyword
1438
1439The CASE: keyword allows an XSUB to have multiple distinct parts with each
1440part acting as a virtual XSUB. CASE: is greedy and if it is used then all
1441other XS keywords must be contained within a CASE:. This means nothing may
1442precede the first CASE: in the XSUB and anything following the last CASE: is
1443included in that case.
1444
1445A CASE: might switch via a parameter of the XSUB, via the C<ix> ALIAS:
1446variable (see L<"The ALIAS: Keyword">), or maybe via the C<items> variable
1447(see L<"Variable-length Parameter Lists">). The last CASE: becomes the
1448B<default> case if it is not associated with a conditional. The following
1449example shows CASE switched via C<ix> with a function C<rpcb_gettime()>
1450having an alias C<x_gettime()>. When the function is called as
b772cb6e
PP
1451C<rpcb_gettime()> its parameters are the usual C<(char *host, time_t *timep)>,
1452but when the function is called as C<x_gettime()> its parameters are
c07a80fd
PP
1453reversed, C<(time_t *timep, char *host)>.
1454
1455 long
1456 rpcb_gettime(a,b)
1457 CASE: ix == 1
beb31b0b 1458 ALIAS:
c07a80fd 1459 x_gettime = 1
beb31b0b 1460 INPUT:
c07a80fd
PP
1461 # 'a' is timep, 'b' is host
1462 char *b
1463 time_t a = NO_INIT
beb31b0b 1464 CODE:
c07a80fd 1465 RETVAL = rpcb_gettime( b, &a );
beb31b0b 1466 OUTPUT:
c07a80fd
PP
1467 a
1468 RETVAL
1469 CASE:
1470 # 'a' is host, 'b' is timep
1471 char *a
1472 time_t &b = NO_INIT
beb31b0b 1473 OUTPUT:
c07a80fd
PP
1474 b
1475 RETVAL
1476
1477That function can be called with either of the following statements. Note
1478the different argument lists.
1479
1480 $status = rpcb_gettime( $host, $timep );
1481
1482 $status = x_gettime( $timep, $host );
1483
1484=head2 The & Unary Operator
1485
beb31b0b
GS
1486The C<&> unary operator in the INPUT: section is used to tell B<xsubpp>
1487that it should convert a Perl value to/from C using the C type to the left
1488of C<&>, but provide a pointer to this value when the C function is called.
1489
1490This is useful to avoid a CODE: block for a C function which takes a parameter
1491by reference. Typically, the parameter should be not a pointer type (an
d1be9408 1492C<int> or C<long> but not an C<int*> or C<long*>).
c07a80fd 1493
beb31b0b 1494The following XSUB will generate incorrect C code. The B<xsubpp> compiler will
c07a80fd
PP
1495turn this into code which calls C<rpcb_gettime()> with parameters C<(char
1496*host, time_t timep)>, but the real C<rpcb_gettime()> wants the C<timep>
1497parameter to be of type C<time_t*> rather than C<time_t>.
1498
1499 bool_t
1500 rpcb_gettime(host,timep)
1501 char *host
1502 time_t timep
beb31b0b 1503 OUTPUT:
c07a80fd
PP
1504 timep
1505
beb31b0b 1506That problem is corrected by using the C<&> operator. The B<xsubpp> compiler
c07a80fd
PP
1507will now turn this into code which calls C<rpcb_gettime()> correctly with
1508parameters C<(char *host, time_t *timep)>. It does this by carrying the
1509C<&> through, so the function call looks like C<rpcb_gettime(host, &timep)>.
1510
1511 bool_t
1512 rpcb_gettime(host,timep)
1513 char *host
1514 time_t &timep
beb31b0b 1515 OUTPUT:
c07a80fd
PP
1516 timep
1517
7817ba4d 1518=head2 Inserting POD, Comments and C Preprocessor Directives
a0d0e21e 1519
7817ba4d 1520C preprocessor directives are allowed within BOOT:, PREINIT: INIT:, CODE:,
375cc10d 1521PPCODE:, POSTCALL:, and CLEANUP: blocks, as well as outside the functions.
7817ba4d
NC
1522Comments are allowed anywhere after the MODULE keyword. The compiler will
1523pass the preprocessor directives through untouched and will remove the
1524commented lines. POD documentation is allowed at any point, both in the
1525C and XS language sections. POD must be terminated with a C<=cut> command;
1526C<xsubpp> will exit with an error if it does not. It is very unlikely that
1527human generated C code will be mistaken for POD, as most indenting styles
1528result in whitespace in front of any line starting with C<=>. Machine
1529generated XS files may fall into this trap unless care is taken to
1530ensure that a space breaks the sequence "\n=".
b772cb6e 1531
f27cfbbe
PP
1532Comments can be added to XSUBs by placing a C<#> as the first
1533non-whitespace of a line. Care should be taken to avoid making the
1534comment look like a C preprocessor directive, lest it be interpreted as
1535such. The simplest way to prevent this is to put whitespace in front of
1536the C<#>.
1537
f27cfbbe
PP
1538If you use preprocessor directives to choose one of two
1539versions of a function, use
1540
1541 #if ... version1
1542 #else /* ... version2 */
1543 #endif
1544
1545and not
1546
1547 #if ... version1
1548 #endif
1549 #if ... version2
1550 #endif
1551
beb31b0b 1552because otherwise B<xsubpp> will believe that you made a duplicate
f27cfbbe
PP
1553definition of the function. Also, put a blank line before the
1554#else/#endif so it will not be seen as part of the function body.
a0d0e21e
LW
1555
1556=head2 Using XS With C++
1557
beb31b0b
GS
1558If an XSUB name contains C<::>, it is considered to be a C++ method.
1559The generated Perl function will assume that
a0d0e21e
LW
1560its first argument is an object pointer. The object pointer
1561will be stored in a variable called THIS. The object should
1562have been created by C++ with the new() function and should
cb1a09d0
AD
1563be blessed by Perl with the sv_setref_pv() macro. The
1564blessing of the object by Perl can be handled by a typemap. An example
1565typemap is shown at the end of this section.
a0d0e21e 1566
beb31b0b
GS
1567If the return type of the XSUB includes C<static>, the method is considered
1568to be a static method. It will call the C++
a0d0e21e 1569function using the class::method() syntax. If the method is not static
f27cfbbe 1570the function will be called using the THIS-E<gt>method() syntax.
a0d0e21e 1571
cb1a09d0 1572The next examples will use the following C++ class.
a0d0e21e 1573
a5f75d66 1574 class color {
cb1a09d0 1575 public:
a5f75d66
AD
1576 color();
1577 ~color();
cb1a09d0
AD
1578 int blue();
1579 void set_blue( int );
1580
1581 private:
1582 int c_blue;
1583 };
1584
1585The XSUBs for the blue() and set_blue() methods are defined with the class
1586name but the parameter for the object (THIS, or "self") is implicit and is
1587not listed.
1588
1589 int
1590 color::blue()
a0d0e21e
LW
1591
1592 void
cb1a09d0
AD
1593 color::set_blue( val )
1594 int val
a0d0e21e 1595
beb31b0b
GS
1596Both Perl functions will expect an object as the first parameter. In the
1597generated C++ code the object is called C<THIS>, and the method call will
1598be performed on this object. So in the C++ code the blue() and set_blue()
1599methods will be called as this:
a0d0e21e 1600
cb1a09d0 1601 RETVAL = THIS->blue();
a0d0e21e 1602
cb1a09d0 1603 THIS->set_blue( val );
a0d0e21e 1604
4628e4f8
GS
1605You could also write a single get/set method using an optional argument:
1606
1607 int
a104f515 1608 color::blue( val = NO_INIT )
4628e4f8
GS
1609 int val
1610 PROTOTYPE $;$
1611 CODE:
1612 if (items > 1)
1613 THIS->set_blue( val );
1614 RETVAL = THIS->blue();
1615 OUTPUT:
1616 RETVAL
1617
cb1a09d0 1618If the function's name is B<DESTROY> then the C++ C<delete> function will be
beb31b0b 1619called and C<THIS> will be given as its parameter. The generated C++ code for
a0d0e21e 1620
d1b91892 1621 void
cb1a09d0
AD
1622 color::DESTROY()
1623
beb31b0b
GS
1624will look like this:
1625
1626 color *THIS = ...; // Initialized as in typemap
cb1a09d0
AD
1627
1628 delete THIS;
a0d0e21e 1629
cb1a09d0
AD
1630If the function's name is B<new> then the C++ C<new> function will be called
1631to create a dynamic C++ object. The XSUB will expect the class name, which
1632will be kept in a variable called C<CLASS>, to be given as the first
1633argument.
a0d0e21e 1634
cb1a09d0
AD
1635 color *
1636 color::new()
a0d0e21e 1637
beb31b0b 1638The generated C++ code will call C<new>.
a0d0e21e 1639
beb31b0b 1640 RETVAL = new color();
cb1a09d0
AD
1641
1642The following is an example of a typemap that could be used for this C++
1643example.
1644
1645 TYPEMAP
1646 color * O_OBJECT
1647
1648 OUTPUT
1649 # The Perl object is blessed into 'CLASS', which should be a
1650 # char* having the name of the package for the blessing.
1651 O_OBJECT
1652 sv_setref_pv( $arg, CLASS, (void*)$var );
a6006777 1653
cb1a09d0
AD
1654 INPUT
1655 O_OBJECT
1656 if( sv_isobject($arg) && (SvTYPE(SvRV($arg)) == SVt_PVMG) )
1657 $var = ($type)SvIV((SV*)SvRV( $arg ));
1658 else{
1659 warn( \"${Package}::$func_name() -- $var is not a blessed SV reference\" );
1660 XSRETURN_UNDEF;
1661 }
a0d0e21e 1662
d1b91892 1663=head2 Interface Strategy
a0d0e21e
LW
1664
1665When designing an interface between Perl and a C library a straight
beb31b0b
GS
1666translation from C to XS (such as created by C<h2xs -x>) is often sufficient.
1667However, sometimes the interface will look
a0d0e21e 1668very C-like and occasionally nonintuitive, especially when the C function
beb31b0b
GS
1669modifies one of its parameters, or returns failure inband (as in "negative
1670return values mean failure"). In cases where the programmer wishes to
a0d0e21e
LW
1671create a more Perl-like interface the following strategy may help to
1672identify the more critical parts of the interface.
1673
beb31b0b
GS
1674Identify the C functions with input/output or output parameters. The XSUBs for
1675these functions may be able to return lists to Perl.
1676
1677Identify the C functions which use some inband info as an indication
1678of failure. They may be
1679candidates to return undef or an empty list in case of failure. If the
1680failure may be detected without a call to the C function, you may want to use
1681an INIT: section to report the failure. For failures detectable after the C
375cc10d 1682function returns one may want to use a POSTCALL: section to process the
beb31b0b
GS
1683failure. In more complicated cases use CODE: or PPCODE: sections.
1684
1685If many functions use the same failure indication based on the return value,
1686you may want to create a special typedef to handle this situation. Put
1687
1688 typedef int negative_is_failure;
1689
1690near the beginning of XS file, and create an OUTPUT typemap entry
1691for C<negative_is_failure> which converts negative values to C<undef>, or
1692maybe croak()s. After this the return value of type C<negative_is_failure>
1693will create more Perl-like interface.
a0d0e21e 1694
d1b91892 1695Identify which values are used by only the C and XSUB functions
beb31b0b
GS
1696themselves, say, when a parameter to a function should be a contents of a
1697global variable. If Perl does not need to access the contents of the value
a0d0e21e
LW
1698then it may not be necessary to provide a translation for that value
1699from C to Perl.
1700
1701Identify the pointers in the C function parameter lists and return
beb31b0b
GS
1702values. Some pointers may be used to implement input/output or
1703output parameters, they can be handled in XS with the C<&> unary operator,
1704and, possibly, using the NO_INIT keyword.
1705Some others will require handling of types like C<int *>, and one needs
1706to decide what a useful Perl translation will do in such a case. When
1707the semantic is clear, it is advisable to put the translation into a typemap
1708file.
a0d0e21e
LW
1709
1710Identify the structures used by the C functions. In many
1711cases it may be helpful to use the T_PTROBJ typemap for
1712these structures so they can be manipulated by Perl as
beb31b0b
GS
1713blessed objects. (This is handled automatically by C<h2xs -x>.)
1714
1715If the same C type is used in several different contexts which require
1716different translations, C<typedef> several new types mapped to this C type,
1717and create separate F<typemap> entries for these new types. Use these
1718types in declarations of return type and parameters to XSUBs.
a0d0e21e 1719
a0d0e21e
LW
1720=head2 Perl Objects And C Structures
1721
1722When dealing with C structures one should select either
1723B<T_PTROBJ> or B<T_PTRREF> for the XS type. Both types are
1724designed to handle pointers to complex objects. The
1725T_PTRREF type will allow the Perl object to be unblessed
1726while the T_PTROBJ type requires that the object be blessed.
1727By using T_PTROBJ one can achieve a form of type-checking
d1b91892 1728because the XSUB will attempt to verify that the Perl object
a0d0e21e
LW
1729is of the expected type.
1730
1731The following XS code shows the getnetconfigent() function which is used
8e07c86e 1732with ONC+ TIRPC. The getnetconfigent() function will return a pointer to a
a0d0e21e
LW
1733C structure and has the C prototype shown below. The example will
1734demonstrate how the C pointer will become a Perl reference. Perl will
1735consider this reference to be a pointer to a blessed object and will
1736attempt to call a destructor for the object. A destructor will be
1737provided in the XS source to free the memory used by getnetconfigent().
1738Destructors in XS can be created by specifying an XSUB function whose name
1739ends with the word B<DESTROY>. XS destructors can be used to free memory
1740which may have been malloc'd by another XSUB.
1741
1742 struct netconfig *getnetconfigent(const char *netid);
1743
1744A C<typedef> will be created for C<struct netconfig>. The Perl
1745object will be blessed in a class matching the name of the C
1746type, with the tag C<Ptr> appended, and the name should not
1747have embedded spaces if it will be a Perl package name. The
1748destructor will be placed in a class corresponding to the
1749class of the object and the PREFIX keyword will be used to
1750trim the name to the word DESTROY as Perl will expect.
1751
1752 typedef struct netconfig Netconfig;
1753
1754 MODULE = RPC PACKAGE = RPC
1755
1756 Netconfig *
1757 getnetconfigent(netid)
8e07c86e 1758 char *netid
a0d0e21e
LW
1759
1760 MODULE = RPC PACKAGE = NetconfigPtr PREFIX = rpcb_
1761
1762 void
1763 rpcb_DESTROY(netconf)
8e07c86e 1764 Netconfig *netconf
beb31b0b 1765 CODE:
a0d0e21e
LW
1766 printf("Now in NetconfigPtr::DESTROY\n");
1767 free( netconf );
1768
1769This example requires the following typemap entry. Consult the typemap
1770section for more information about adding new typemaps for an extension.
1771
1772 TYPEMAP
1773 Netconfig * T_PTROBJ
1774
1775This example will be used with the following Perl statements.
1776
1777 use RPC;
1778 $netconf = getnetconfigent("udp");
1779
1780When Perl destroys the object referenced by $netconf it will send the
1781object to the supplied XSUB DESTROY function. Perl cannot determine, and
1782does not care, that this object is a C struct and not a Perl object. In
1783this sense, there is no difference between the object created by the
1784getnetconfigent() XSUB and an object created by a normal Perl subroutine.
1785
a0d0e21e
LW
1786=head2 The Typemap
1787
1788The typemap is a collection of code fragments which are used by the B<xsubpp>
1789compiler to map C function parameters and values to Perl values. The
7817ba4d 1790typemap file may consist of three sections labelled C<TYPEMAP>, C<INPUT>, and
beb31b0b
GS
1791C<OUTPUT>. An unlabelled initial section is assumed to be a C<TYPEMAP>
1792section. The INPUT section tells
7e9d670d 1793the compiler how to translate Perl values
a0d0e21e
LW
1794into variables of certain C types. The OUTPUT section tells the compiler
1795how to translate the values from certain C types into values Perl can
1796understand. The TYPEMAP section tells the compiler which of the INPUT and
1797OUTPUT code fragments should be used to map a given C type to a Perl value.
7e9d670d
GS
1798The section labels C<TYPEMAP>, C<INPUT>, or C<OUTPUT> must begin
1799in the first column on a line by themselves, and must be in uppercase.
a0d0e21e 1800
dcd2ee75
YST
1801The default typemap in the C<lib/ExtUtils> directory of the Perl source
1802contains many useful types which can be used by Perl extensions. Some
1803extensions define additional typemaps which they keep in their own directory.
1804These additional typemaps may reference INPUT and OUTPUT maps in the main
a0d0e21e
LW
1805typemap. The B<xsubpp> compiler will allow the extension's own typemap to
1806override any mappings which are in the default typemap.
1807
1808Most extensions which require a custom typemap will need only the TYPEMAP
1809section of the typemap file. The custom typemap used in the
1810getnetconfigent() example shown earlier demonstrates what may be the typical
1811use of extension typemaps. That typemap is used to equate a C structure
1812with the T_PTROBJ typemap. The typemap used by getnetconfigent() is shown
1813here. Note that the C type is separated from the XS type with a tab and
1814that the C unary operator C<*> is considered to be a part of the C type name.
1815
beb31b0b
GS
1816 TYPEMAP
1817 Netconfig *<tab>T_PTROBJ
a0d0e21e 1818
1748e8dd
RS
1819Here's a more complicated example: suppose that you wanted C<struct
1820netconfig> to be blessed into the class C<Net::Config>. One way to do
1821this is to use underscores (_) to separate package names, as follows:
1822
1823 typedef struct netconfig * Net_Config;
1824
1825And then provide a typemap entry C<T_PTROBJ_SPECIAL> that maps underscores to
1826double-colons (::), and declare C<Net_Config> to be of that type:
1827
1828
1829 TYPEMAP
1830 Net_Config T_PTROBJ_SPECIAL
1831
1832 INPUT
1833 T_PTROBJ_SPECIAL
1834 if (sv_derived_from($arg, \"${(my $ntt=$ntype)=~s/_/::/g;\$ntt}\")) {
1835 IV tmp = SvIV((SV*)SvRV($arg));
1836 $var = ($type) tmp;
1837 }
1838 else
1839 croak(\"$var is not of type ${(my $ntt=$ntype)=~s/_/::/g;\$ntt}\")
1840
1841 OUTPUT
1842 T_PTROBJ_SPECIAL
1843 sv_setref_pv($arg, \"${(my $ntt=$ntype)=~s/_/::/g;\$ntt}\",
1844 (void*)$var);
1845
1846The INPUT and OUTPUT sections substitute underscores for double-colons
1847on the fly, giving the desired effect. This example demonstrates some
1848of the power and versatility of the typemap facility.
1849
662a0f8c
JH
1850=head2 Safely Storing Static Data in XS
1851
1852Starting with Perl 5.8, a macro framework has been defined to allow
1853static data to be safely stored in XS modules that will be accessed from
1854a multi-threaded Perl.
1855
1856Although primarily designed for use with multi-threaded Perl, the macros
1857have been designed so that they will work with non-threaded Perl as well.
1858
1859It is therefore strongly recommended that these macros be used by all
1860XS modules that make use of static data.
1861
fe854a6f 1862The easiest way to get a template set of macros to use is by specifying
662a0f8c
JH
1863the C<-g> (C<--global>) option with h2xs (see L<h2xs>).
1864
1865Below is an example module that makes use of the macros.
1866
1867 #include "EXTERN.h"
1868 #include "perl.h"
1869 #include "XSUB.h"
7207e29d 1870
662a0f8c 1871 /* Global Data */
7207e29d 1872
662a0f8c 1873 #define MY_CXT_KEY "BlindMice::_guts" XS_VERSION
7207e29d 1874
662a0f8c
JH
1875 typedef struct {
1876 int count;
1877 char name[3][100];
1878 } my_cxt_t;
7207e29d 1879
662a0f8c 1880 START_MY_CXT
7207e29d 1881
662a0f8c 1882 MODULE = BlindMice PACKAGE = BlindMice
7207e29d 1883
662a0f8c
JH
1884 BOOT:
1885 {
1886 MY_CXT_INIT;
1887 MY_CXT.count = 0;
1888 strcpy(MY_CXT.name[0], "None");
1889 strcpy(MY_CXT.name[1], "None");
1890 strcpy(MY_CXT.name[2], "None");
1891 }
1892
1893 int
1894 newMouse(char * name)
1895 char * name;
1896 PREINIT:
1897 dMY_CXT;
1898 CODE:
1899 if (MY_CXT.count >= 3) {
1900 warn("Already have 3 blind mice") ;
1901 RETVAL = 0;
1902 }
1903 else {
1904 RETVAL = ++ MY_CXT.count;
1905 strcpy(MY_CXT.name[MY_CXT.count - 1], name);
1906 }
1907
1908 char *
1909 get_mouse_name(index)
1910 int index
1911 CODE:
1912 dMY_CXT;
1913 RETVAL = MY_CXT.lives ++;
1914 if (index > MY_CXT.count)
1915 croak("There are only 3 blind mice.");
1916 else
1917 RETVAL = newSVpv(MY_CXT.name[index - 1]);
1918
1919
1920B<REFERENCE>
1921
1922=over 5
1923
1924=item MY_CXT_KEY
1925
1926This macro is used to define a unique key to refer to the static data
1927for an XS module. The suggested naming scheme, as used by h2xs, is to
1928use a string that consists of the module name, the string "::_guts"
1929and the module version number.
1930
1931 #define MY_CXT_KEY "MyModule::_guts" XS_VERSION
1932
1933=item typedef my_cxt_t
1934
1935This struct typedef I<must> always be called C<my_cxt_t> -- the other
1936C<CXT*> macros assume the existence of the C<my_cxt_t> typedef name.
1937
1938Declare a typedef named C<my_cxt_t> that is a structure that contains
1939all the data that needs to be interpreter-local.
1940
1941 typedef struct {
1942 int some_value;
1943 } my_cxt_t;
1944
1945=item START_MY_CXT
1946
1947Always place the START_MY_CXT macro directly after the declaration
1948of C<my_cxt_t>.
1949
1950=item MY_CXT_INIT
1951
1952The MY_CXT_INIT macro initialises storage for the C<my_cxt_t> struct.
1953
1954It I<must> be called exactly once -- typically in a BOOT: section.
1955
1956=item dMY_CXT
1957
1958Use the dMY_CXT macro (a declaration) in all the functions that access
1959MY_CXT.
1960
1961=item MY_CXT
1962
1963Use the MY_CXT macro to access members of the C<my_cxt_t> struct. For
1964example, if C<my_cxt_t> is
1965
1966 typedef struct {
1967 int index;
1968 } my_cxt_t;
1969
1970then use this to access the C<index> member
1971
1972 dMY_CXT;
1973 MY_CXT.index = 2;
1974
1975=back
1976
a0d0e21e
LW
1977=head1 EXAMPLES
1978
1979File C<RPC.xs>: Interface to some ONC+ RPC bind library functions.
1980
1981 #include "EXTERN.h"
1982 #include "perl.h"
1983 #include "XSUB.h"
1984
1985 #include <rpc/rpc.h>
1986
1987 typedef struct netconfig Netconfig;
1988
1989 MODULE = RPC PACKAGE = RPC
1990
e7ea3e70 1991 SV *
a0d0e21e 1992 rpcb_gettime(host="localhost")
8e07c86e 1993 char *host
beb31b0b 1994 PREINIT:
a0d0e21e 1995 time_t timep;
beb31b0b 1996 CODE:
a0d0e21e
LW
1997 ST(0) = sv_newmortal();
1998 if( rpcb_gettime( host, &timep ) )
1999 sv_setnv( ST(0), (double)timep );
a0d0e21e
LW
2000
2001 Netconfig *
2002 getnetconfigent(netid="udp")
8e07c86e 2003 char *netid
a0d0e21e
LW
2004
2005 MODULE = RPC PACKAGE = NetconfigPtr PREFIX = rpcb_
2006
2007 void
2008 rpcb_DESTROY(netconf)
8e07c86e 2009 Netconfig *netconf
beb31b0b 2010 CODE:
a0d0e21e
LW
2011 printf("NetconfigPtr::DESTROY\n");
2012 free( netconf );
2013
2014File C<typemap>: Custom typemap for RPC.xs.
2015
2016 TYPEMAP
2017 Netconfig * T_PTROBJ
2018
2019File C<RPC.pm>: Perl module for the RPC extension.
2020
2021 package RPC;
2022
2023 require Exporter;
2024 require DynaLoader;
2025 @ISA = qw(Exporter DynaLoader);
2026 @EXPORT = qw(rpcb_gettime getnetconfigent);
2027
2028 bootstrap RPC;
2029 1;
2030
2031File C<rpctest.pl>: Perl test program for the RPC extension.
2032
2033 use RPC;
2034
2035 $netconf = getnetconfigent();
2036 $a = rpcb_gettime();
2037 print "time = $a\n";
2038 print "netconf = $netconf\n";
2039
2040 $netconf = getnetconfigent("tcp");
2041 $a = rpcb_gettime("poplar");
2042 print "time = $a\n";
2043 print "netconf = $netconf\n";
2044
2045
c07a80fd
PP
2046=head1 XS VERSION
2047
f27cfbbe 2048This document covers features supported by C<xsubpp> 1.935.
c07a80fd 2049
a0d0e21e
LW
2050=head1 AUTHOR
2051
beb31b0b
GS
2052Originally written by Dean Roehrich <F<roehrich@cray.com>>.
2053
7f2de2d2 2054Maintained since 1996 by The Perl Porters <F<perlbug@perl.org>>.