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