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