3 perlxs - XS language reference manual
9 XS is a language used to create an extension interface
10 between Perl and some C library which one wishes to use with
11 Perl. The XS interface is combined with the library to
12 create a new library which can be linked to Perl. An B<XSUB>
13 is a function in the XS language and is the core component
14 of the Perl application interface.
16 The XS compiler is called B<xsubpp>. This compiler will embed
17 the constructs necessary to let an XSUB, which is really a C
18 function in disguise, manipulate Perl values and creates the
19 glue necessary to let Perl access the XSUB. The compiler
20 uses B<typemaps> to determine how to map C function parameters
21 and variables to Perl values. The default typemap handles
22 many common C types. A supplement typemap must be created
23 to handle special structures and types for the library being
26 =head2 Getting Started
28 A new extension should begin with the B<h2xs> tool. This will generate
29 templates for the new Perl module (PM), the XS source file (XS), the MANIFEST
30 file, and the Makefile.PL (PL) files. The Makefile.PL file is a Perl script
31 which will generate a Makefile. This makefile knows how to find and run
32 xsubpp for your extension. When you type "make" your XS file will be run
33 through xsubpp and a C file will be produced. Then the C file will be
34 compiled. A simple example looks like this for an example module named
40 Foo.pm Foo.xs MANIFEST Makefile.PL
43 Foo.pm Foo.xs MANIFEST Makefile.PL Makefile
44 $ <edit Foo.pm and Foo.xs to add your stuff>
46 <you will see xsubpp run on Foo.xs and you'll see the C compiler
47 <run on Foo.c, and a bunch of other less-interesting things
50 If your Perl was built with dynamic loading then the makefile will build a
51 dynamically loadable extension. If you don't have dynamic loading then the
52 makefile will build a static extension and should create a new Perl binary.
53 The default behavior depends on what is available.
55 For more information about h2xs consult its manpage, embedded in the
56 source. For information about the Makefile.PL and Makefile consult the
61 Many of the examples which follow will concentrate on creating an
62 interface between Perl and the ONC+ RPC bind library functions.
63 Specifically, the rpcb_gettime() function will be used to demonstrate many
64 features of the XS language. This function has two parameters; the first
65 is an input parameter and the second is an output parameter. The function
66 also returns a status value.
68 bool_t rpcb_gettime(const char *host, time_t *timep);
70 From C this function will be called with the following
76 status = rpcb_gettime( "localhost", &timep );
78 If an XSUB is created to offer a direct translation between this function
79 and Perl, then this XSUB will be used from Perl with the following code.
80 The $status and $timep variables will contain the output of the function.
83 $status = rpcb_gettime( "localhost", $timep );
85 The following XS file shows an XS subroutine, or XSUB, which
86 demonstrates one possible interface to the rpcb_gettime()
87 function. This XSUB represents a direct translation between
88 C and Perl and so preserves the interface even from Perl.
89 This XSUB will be invoked from Perl with the usage shown
90 above. Note that the first three #include statements, for
91 C<EXTERN.h>, C<perl.h>, and C<XSUB.h>, will always be present at the
92 beginning of an XS file. This approach and others will be
93 expanded later in this document.
100 MODULE = RPC PACKAGE = RPC
103 rpcb_gettime(host,timep)
109 Any extension to Perl, including those containing XSUBs,
110 should have a Perl module to serve as the bootstrap which
111 pulls the extension into Perl. This module will export the
112 extension's functions and variables to the Perl program and
113 will cause the extension's XSUBs to be linked into Perl.
114 The following module will be used for most of the examples
115 in this document and should be used from Perl with the C<use>
116 command as shown earlier. Perl modules are explained in
117 more detail later in this document.
123 @ISA = qw(Exporter DynaLoader);
124 @EXPORT = qw( rpcb_gettime );
129 Throughout this document a variety of interfaces to the rpcb_gettime()
130 XSUB will be explored. The XSUBs will take their parameters in different
131 orders or will take different numbers of parameters. In each case the
132 XSUB is an abstraction between Perl and the real C rpcb_gettime()
133 function, and the XSUB must always ensure that the real rpcb_gettime()
134 function is called with the correct parameters. This abstraction will
135 allow the programmer to create a more Perl-like interface to the C
138 =head2 The Anatomy of an XSUB
140 The following XSUB allows a Perl program to access a C library function
141 called sin(). The XSUB will imitate the C function which takes a single
142 argument and returns a single value.
148 When using C pointers the indirection operator C<*> should be considered
149 part of the type and the address operator C<&> should be considered part of
150 the variable, as is demonstrated in the rpcb_gettime() function above. See
151 the section on typemaps for more about handling qualifiers and unary
152 operators in C types.
154 The function name and the return type must be placed on
163 =head2 The Argument Stack
165 The argument stack is used to store the values which are
166 sent as parameters to the XSUB and to store the XSUB's
167 return value. In reality all Perl functions keep their
168 values on this stack at the same time, each limited to its
169 own range of positions on the stack. In this document the
170 first position on that stack which belongs to the active
171 function will be referred to as position 0 for that function.
173 XSUBs refer to their stack arguments with the macro B<ST(x)>, where I<x>
174 refers to a position in this XSUB's part of the stack. Position 0 for that
175 function would be known to the XSUB as ST(0). The XSUB's incoming
176 parameters and outgoing return values always begin at ST(0). For many
177 simple cases the B<xsubpp> compiler will generate the code necessary to
178 handle the argument stack by embedding code fragments found in the
179 typemaps. In more complex cases the programmer must supply the code.
181 =head2 The RETVAL Variable
183 The RETVAL variable is a magic variable which always matches
184 the return type of the C library function. The B<xsubpp> compiler will
185 supply this variable in each XSUB and by default will use it to hold the
186 return value of the C library function being called. In simple cases the
187 value of RETVAL will be placed in ST(0) of the argument stack where it can
188 be received by Perl as the return value of the XSUB.
190 If the XSUB has a return type of C<void> then the compiler will
191 not supply a RETVAL variable for that function. When using
192 the PPCODE: directive the RETVAL variable may not be needed.
194 =head2 The MODULE Keyword
196 The MODULE keyword is used to start the XS code and to
197 specify the package of the functions which are being
198 defined. All text preceding the first MODULE keyword is
199 considered C code and is passed through to the output
200 untouched. Every XS module will have a bootstrap function
201 which is used to hook the XSUBs into Perl. The package name
202 of this bootstrap function will match the value of the last
203 MODULE statement in the XS source files. The value of
204 MODULE should always remain constant within the same XS
205 file, though this is not required.
207 The following example will start the XS code and will place
208 all functions in a package named RPC.
212 =head2 The PACKAGE Keyword
214 When functions within an XS source file must be separated into packages
215 the PACKAGE keyword should be used. This keyword is used with the MODULE
216 keyword and must follow immediately after it when used.
218 MODULE = RPC PACKAGE = RPC
220 [ XS code in package RPC ]
222 MODULE = RPC PACKAGE = RPCB
224 [ XS code in package RPCB ]
226 MODULE = RPC PACKAGE = RPC
228 [ XS code in package RPC ]
230 Although this keyword is optional and in some cases provides redundant
231 information it should always be used. This keyword will ensure that the
232 XSUBs appear in the desired package.
234 =head2 The PREFIX Keyword
236 The PREFIX keyword designates prefixes which should be
237 removed from the Perl function names. If the C function is
238 C<rpcb_gettime()> and the PREFIX value is C<rpcb_> then Perl will
239 see this function as C<gettime()>.
241 This keyword should follow the PACKAGE keyword when used.
242 If PACKAGE is not used then PREFIX should follow the MODULE
245 MODULE = RPC PREFIX = rpc_
247 MODULE = RPC PACKAGE = RPCB PREFIX = rpcb_
249 =head2 The OUTPUT: Keyword
251 The OUTPUT: keyword indicates that certain function parameters should be
252 updated (new values made visible to Perl) when the XSUB terminates or that
253 certain values should be returned to the calling Perl function. For
254 simple functions, such as the sin() function above, the RETVAL variable is
255 automatically designated as an output value. In more complex functions
256 the B<xsubpp> compiler will need help to determine which variables are output
259 This keyword will normally be used to complement the CODE: keyword.
260 The RETVAL variable is not recognized as an output variable when the
261 CODE: keyword is present. The OUTPUT: keyword is used in this
262 situation to tell the compiler that RETVAL really is an output
265 The OUTPUT: keyword can also be used to indicate that function parameters
266 are output variables. This may be necessary when a parameter has been
267 modified within the function and the programmer would like the update to
271 rpcb_gettime(host,timep)
277 The OUTPUT: keyword will also allow an output parameter to
278 be mapped to a matching piece of code rather than to a
282 rpcb_gettime(host,timep)
286 timep sv_setnv(ST(1), (double)timep);
288 =head2 The CODE: Keyword
290 This keyword is used in more complicated XSUBs which require
291 special handling for the C function. The RETVAL variable is
292 available but will not be returned unless it is specified
293 under the OUTPUT: keyword.
295 The following XSUB is for a C function which requires special handling of
296 its parameters. The Perl usage is given first.
298 $status = rpcb_gettime( "localhost", $timep );
303 rpcb_gettime(host,timep)
307 RETVAL = rpcb_gettime( host, &timep );
312 In many of the examples shown here the CODE: block (and
313 other blocks) will often be contained within braces ( C<{> and
314 C<}> ). This protects the CODE: block from complex INPUT
315 typemaps and ensures the resulting C code is legal.
317 =head2 The NO_INIT Keyword
319 The NO_INIT keyword is used to indicate that a function
320 parameter is being used as only an output value. The B<xsubpp>
321 compiler will normally generate code to read the values of
322 all function parameters from the argument stack and assign
323 them to C variables upon entry to the function. NO_INIT
324 will tell the compiler that some parameters will be used for
325 output rather than for input and that they will be handled
326 before the function terminates.
328 The following example shows a variation of the rpcb_gettime() function.
329 This function uses the timep variable as only an output variable and does
330 not care about its initial contents.
333 rpcb_gettime(host,timep)
335 time_t &timep = NO_INIT
339 =head2 Initializing Function Parameters
341 Function parameters are normally initialized with their
342 values from the argument stack. The typemaps contain the
343 code segments which are used to transfer the Perl values to
344 the C parameters. The programmer, however, is allowed to
345 override the typemaps and supply alternate initialization
348 The following code demonstrates how to supply initialization code for
349 function parameters. The initialization code is eval'd by the compiler
350 before it is added to the output so anything which should be interpreted
351 literally, such as double quotes, must be protected with backslashes.
354 rpcb_gettime(host,timep)
355 char *host = (char *)SvPV(ST(0),na);
360 This should not be used to supply default values for parameters. One
361 would normally use this when a function parameter must be processed by
362 another library function before it can be used. Default parameters are
363 covered in the next section.
365 =head2 Default Parameter Values
367 Default values can be specified for function parameters by
368 placing an assignment statement in the parameter list. The
369 default value may be a number or a string. Defaults should
370 always be used on the right-most parameters only.
372 To allow the XSUB for rpcb_gettime() to have a default host
373 value the parameters to the XSUB could be rearranged. The
374 XSUB will then call the real rpcb_gettime() function with
375 the parameters in the correct order. Perl will call this
376 XSUB with either of the following statements.
378 $status = rpcb_gettime( $timep, $host );
380 $status = rpcb_gettime( $timep );
382 The XSUB will look like the code which follows. A CODE:
383 block is used to call the real rpcb_gettime() function with
384 the parameters in the correct order for that function.
387 rpcb_gettime(timep,host="localhost")
389 time_t timep = NO_INIT
391 RETVAL = rpcb_gettime( host, &timep );
396 =head2 Variable-length Parameter Lists
398 XSUBs can have variable-length parameter lists by specifying an ellipsis
399 C<(...)> in the parameter list. This use of the ellipsis is similar to that
400 found in ANSI C. The programmer is able to determine the number of
401 arguments passed to the XSUB by examining the C<items> variable which the
402 B<xsubpp> compiler supplies for all XSUBs. By using this mechanism one can
403 create an XSUB which accepts a list of parameters of unknown length.
405 The I<host> parameter for the rpcb_gettime() XSUB can be
406 optional so the ellipsis can be used to indicate that the
407 XSUB will take a variable number of parameters. Perl should
408 be able to call this XSUB with either of the following statements.
410 $status = rpcb_gettime( $timep, $host );
412 $status = rpcb_gettime( $timep );
414 The XS code, with ellipsis, follows.
417 rpcb_gettime(timep, ...)
418 time_t timep = NO_INIT
421 char *host = "localhost";
424 host = (char *)SvPV(ST(1), na);
425 RETVAL = rpcb_gettime( host, &timep );
431 =head2 The PPCODE: Keyword
433 The PPCODE: keyword is an alternate form of the CODE: keyword and is used
434 to tell the B<xsubpp> compiler that the programmer is supplying the code to
435 control the argument stack for the XSUBs return values. Occasionally one
436 will want an XSUB to return a list of values rather than a single value.
437 In these cases one must use PPCODE: and then explicitly push the list of
438 values on the stack. The PPCODE: and CODE: keywords are not used
439 together within the same XSUB.
441 The following XSUB will call the C rpcb_gettime() function
442 and will return its two output values, timep and status, to
443 Perl as a single list.
452 status = rpcb_gettime( host, &timep );
454 PUSHs(sv_2mortal(newSVnv(status)));
455 PUSHs(sv_2mortal(newSVnv(timep)));
458 Notice that the programmer must supply the C code necessary
459 to have the real rpcb_gettime() function called and to have
460 the return values properly placed on the argument stack.
462 The C<void> return type for this function tells the B<xsubpp> compiler that
463 the RETVAL variable is not needed or used and that it should not be created.
464 In most scenarios the void return type should be used with the PPCODE:
467 The EXTEND() macro is used to make room on the argument
468 stack for 2 return values. The PPCODE: directive causes the
469 B<xsubpp> compiler to create a stack pointer called C<sp>, and it
470 is this pointer which is being used in the EXTEND() macro.
471 The values are then pushed onto the stack with the PUSHs()
474 Now the rpcb_gettime() function can be used from Perl with
475 the following statement.
477 ($status, $timep) = rpcb_gettime("localhost");
479 =head2 Returning Undef And Empty Lists
481 Occasionally the programmer will want to simply return
482 C<undef> or an empty list if a function fails rather than a
483 separate status value. The rpcb_gettime() function offers
484 just this situation. If the function succeeds we would like
485 to have it return the time and if it fails we would like to
486 have undef returned. In the following Perl code the value
487 of $timep will either be undef or it will be a valid time.
489 $timep = rpcb_gettime( "localhost" );
491 The following XSUB uses the C<void> return type to disable the generation of
492 the RETVAL variable and uses a CODE: block to indicate to the compiler
493 that the programmer has supplied all the necessary code. The
494 sv_newmortal() call will initialize the return value to undef, making that
495 the default return value.
504 ST(0) = sv_newmortal();
505 if( rpcb_gettime( host, &timep ) )
506 sv_setnv( ST(0), (double)timep);
509 The next example demonstrates how one would place an explicit undef in the
510 return value, should the need arise.
519 ST(0) = sv_newmortal();
520 if( rpcb_gettime( host, &timep ) ){
521 sv_setnv( ST(0), (double)timep);
528 To return an empty list one must use a PPCODE: block and
529 then not push return values on the stack.
537 if( rpcb_gettime( host, &timep ) )
538 PUSHs(sv_2mortal(newSVnv(timep)));
540 /* Nothing pushed on stack, so an empty */
541 /* list is implicitly returned. */
545 =head2 The REQUIRE: Keyword
547 The REQUIRE: keyword is used to indicate the minimum version of the
548 B<xsubpp> compiler needed to compile the XS module. An XS module which
549 contains the following statement will only compile with B<xsubpp> version
554 =head2 The CLEANUP: Keyword
556 This keyword can be used when an XSUB requires special cleanup procedures
557 before it terminates. When the CLEANUP: keyword is used it must follow
558 any CODE:, PPCODE:, or OUTPUT: blocks which are present in the XSUB. The
559 code specified for the cleanup block will be added as the last statements
562 =head2 The BOOT: Keyword
564 The BOOT: keyword is used to add code to the extension's bootstrap
565 function. The bootstrap function is generated by the B<xsubpp> compiler and
566 normally holds the statements necessary to register any XSUBs with Perl.
567 With the BOOT: keyword the programmer can tell the compiler to add extra
568 statements to the bootstrap function.
570 This keyword may be used any time after the first MODULE keyword and should
571 appear on a line by itself. The first blank line after the keyword will
572 terminate the code block.
575 # The following message will be printed when the
576 # bootstrap function executes.
577 printf("Hello from the bootstrap!\n");
579 =head2 Inserting Comments and C Preprocessor Directives
581 Comments and C preprocessor directives are allowed within
582 CODE:, PPCODE:, BOOT:, and CLEANUP: blocks. The compiler
583 will pass the preprocessor directives through untouched and
584 will remove the commented lines. Comments can be added to
585 XSUBs by placing a C<#> at the beginning of the line. Care
586 should be taken to avoid making the comment look like a C
587 preprocessor directive, lest it be interpreted as such.
589 =head2 Using XS With C++
591 If a function is defined as a C++ method then it will assume
592 its first argument is an object pointer. The object pointer
593 will be stored in a variable called THIS. The object should
594 have been created by C++ with the new() function and should
595 be blessed by Perl with the sv_setptrobj() macro. The
596 blessing of the object by Perl can be handled by the
599 If the method is defined as static it will call the C++
600 function using the class::method() syntax. If the method is not static
601 the function will be called using the THIS->method() syntax.
603 =head2 Perl Variables
605 The following demonstrates how the Perl variable $host can
606 be accessed from an XSUB. The function B<perl_get_sv()> is
607 used to obtain a pointer to the variable, known as an B<SV>
608 (Scalar Variable) internally. The package name C<RPC> will be
609 added to the name of the variable so perl_get_sv() will know
610 in which package $host can be found. If the package name is
611 not supplied then perl_get_sv() will search package C<main> for
612 the variable. The macro B<SvPVX()> is then used to dereference
613 the SV to obtain a C<char*> pointer to its contents.
623 hostsv = perl_get_sv( "RPC::host", FALSE );
624 if( hostsv != NULL ){
625 host = SvPVX( hostsv );
626 if( rpcb_gettime( host, &timep ) )
627 PUSHs(sv_2mortal(newSVnv(timep)));
631 This Perl code can be used to call that XSUB.
633 $RPC::host = "localhost";
634 $timep = rpcb_gettime();
636 In the above example the SV contained a C C<char*> but a Perl
637 scalar variable may also contain numbers and references. If
638 the SV is expected to have a C C<int> then the macro B<SvIVX()>
639 should be used to dereference the SV. When the SV contains
640 a C double then B<SvNVX()> should be used.
642 The macro B<SvRV()> can be used to dereference an SV when it is a Perl
643 reference. The result will be another SV which points to the actual Perl
644 variable. This can then be dereferenced with SvPVX(), SvNVX(), or
645 SvIVX(). The following XSUB will use SvRV().
656 rv = perl_get_sv( "RPC::host", FALSE );
659 host = SvPVX( hostsv );
660 if( rpcb_gettime( host, &timep ) )
661 PUSHs(sv_2mortal(newSVnv(timep)));
665 This Perl code will create a variable $RPC::host which is a
666 reference to $MY::host. The variable $MY::host contains the
667 hostname which will be used.
669 $MY::host = "localhost";
670 $RPC::host = \$MY::host;
671 $timep = rpcb_gettime();
673 The second argument to perl_get_sv() will normally be B<FALSE>
674 as shown in the above examples. An argument of B<TRUE> will
675 cause variables to be created if they do not already exist.
676 One should not use TRUE unless steps are taken to deal with
679 XSUBs may use B<perl_get_av()>, B<perl_get_hv()>, and B<perl_get_cv()> to
680 access Perl arrays, hashes, and code values.
682 =head2 Interface Strategy
684 When designing an interface between Perl and a C library a straight
685 translation from C to XS is often sufficient. The interface will often be
686 very C-like and occasionally nonintuitive, especially when the C function
687 modifies one of its parameters. In cases where the programmer wishes to
688 create a more Perl-like interface the following strategy may help to
689 identify the more critical parts of the interface.
691 Identify the C functions which modify their parameters. The XSUBs for
692 these functions may be able to return lists to Perl, or may be
693 candidates to return undef or an empty list in case of failure.
695 Identify which values are used by only the C and XSUB functions
696 themselves. If Perl does not need to access the contents of the value
697 then it may not be necessary to provide a translation for that value
700 Identify the pointers in the C function parameter lists and return
701 values. Some pointers can be handled in XS with the & unary operator on
702 the variable name while others will require the use of the * operator on
703 the type name. In general it is easier to work with the & operator.
705 Identify the structures used by the C functions. In many
706 cases it may be helpful to use the T_PTROBJ typemap for
707 these structures so they can be manipulated by Perl as
710 =head2 The Perl Module
712 The Perl module is the link between the extension library,
713 which was generated from XS code, and the Perl interpreter.
714 The module is used to tell Perl what the extension library
715 contains. The name and package of the module should match
716 the name of the library.
718 The following is a Perl module for an extension containing
719 some ONC+ RPC bind library functions.
725 @ISA = qw(Exporter DynaLoader);
726 @EXPORT = qw( rpcb_gettime rpcb_getmaps rpcb_getaddr
727 rpcb_rmtcall rpcb_set rpcb_unset );
732 The RPC extension contains the functions found in the
733 @EXPORT list. By using the C<Exporter> module the RPC module
734 can make these function names visible to the rest of the
735 Perl program. The C<DynaLoader> module will allow the RPC
736 module to bootstrap the extension library. To load this
737 extension and make the functions available, the following
738 Perl statement should be used.
742 For more information about the DynaLoader consult its documentation in the
743 ext/DynaLoader directory in the Perl source.
745 =head2 Perl Objects And C Structures
747 When dealing with C structures one should select either
748 B<T_PTROBJ> or B<T_PTRREF> for the XS type. Both types are
749 designed to handle pointers to complex objects. The
750 T_PTRREF type will allow the Perl object to be unblessed
751 while the T_PTROBJ type requires that the object be blessed.
752 By using T_PTROBJ one can achieve a form of type-checking
753 because the XSUB will attempt to verify that the Perl object
754 is of the expected type.
756 The following XS code shows the getnetconfigent() function which is used
757 with ONC+ TIRPC. The getnetconfigent() function will return a pointer to a
758 C structure and has the C prototype shown below. The example will
759 demonstrate how the C pointer will become a Perl reference. Perl will
760 consider this reference to be a pointer to a blessed object and will
761 attempt to call a destructor for the object. A destructor will be
762 provided in the XS source to free the memory used by getnetconfigent().
763 Destructors in XS can be created by specifying an XSUB function whose name
764 ends with the word B<DESTROY>. XS destructors can be used to free memory
765 which may have been malloc'd by another XSUB.
767 struct netconfig *getnetconfigent(const char *netid);
769 A C<typedef> will be created for C<struct netconfig>. The Perl
770 object will be blessed in a class matching the name of the C
771 type, with the tag C<Ptr> appended, and the name should not
772 have embedded spaces if it will be a Perl package name. The
773 destructor will be placed in a class corresponding to the
774 class of the object and the PREFIX keyword will be used to
775 trim the name to the word DESTROY as Perl will expect.
777 typedef struct netconfig Netconfig;
779 MODULE = RPC PACKAGE = RPC
782 getnetconfigent(netid)
785 MODULE = RPC PACKAGE = NetconfigPtr PREFIX = rpcb_
788 rpcb_DESTROY(netconf)
791 printf("Now in NetconfigPtr::DESTROY\n");
794 This example requires the following typemap entry. Consult the typemap
795 section for more information about adding new typemaps for an extension.
800 This example will be used with the following Perl statements.
803 $netconf = getnetconfigent("udp");
805 When Perl destroys the object referenced by $netconf it will send the
806 object to the supplied XSUB DESTROY function. Perl cannot determine, and
807 does not care, that this object is a C struct and not a Perl object. In
808 this sense, there is no difference between the object created by the
809 getnetconfigent() XSUB and an object created by a normal Perl subroutine.
811 =head2 C Headers and Perl
813 The B<h2xs> compiler is designed to convert C header files in
814 /usr/include into Perl extensions. This compiler will
815 create a directory under the C<ext> directory of the Perl
816 source and will populate it with a Makefile, a Perl Module,
817 an XS source file, and a MANIFEST file.
819 The following command will create an extension called C<Rusers>
820 from the <rpcsvc/rusers.h> header.
824 When the Rusers extension has been compiled and installed
825 Perl can use it to retrieve any C<#define> statements which
826 were in the C header.
829 print "RPC program number for rusers service: ";
830 print &RUSERSPROG, "\n";
832 =head2 Creating A New Extension
834 The B<h2xs> compiler can generate template source files and
835 Makefiles. These templates offer a suitable starting point
836 for most extensions. The following example demonstrates how
837 one might use B<h2xs> to create an extension containing the RPC
838 functions in this document.
840 The extension will not use autoloaded functions and will not define
841 constants, so the B<-A> option will be given to B<h2xs>. When run from the
842 Perl source directory, the B<h2xs> compiler will create the directory
843 ext/RPC and will populate it with files called RPC.xs, RPC.pm, Makefile.PL,
844 and MANIFEST. The XS code for the RPC functions should be added to the
845 RPC.xs file. The @EXPORT list in RPC.pm should be updated to include the
846 functions from RPC.xs.
850 To compile the extension for dynamic loading the following
851 command should be executed from the ext/RPC directory.
855 If the extension will be statically linked into the Perl
856 binary then the makefile (use C<makefile>, not C<Makefile>) in the
857 Perl source directory should be edited to add C<ext/RPC/RPC.a>
858 to the C<static_ext> variable. Before making this change Perl
859 should have already been built. After the makefile has been
860 updated the following command should be executed from the
861 Perl source directory.
865 Perl's B<Configure> script can also be used to add extensions. The extension
866 should be placed in the C<ext> directory under the Perl source before Perl
867 has been built and prior to running Configure. When Configure is run it
868 will find the extension along with the other extensions in the C<ext>
869 directory and will add it to the list of extensions to be built. When make
870 is run the extension will be built along with the other extensions.
872 Configure recognizes extensions if they have an XS source
873 file which matches the name of the extension directory. If
874 the extension directory includes a MANIFEST file Configure
875 will search that file for any B<.SH> files and extract them
876 after it extracts all the other .SH files listed in the main
877 MANIFEST. The main Perl Makefile will then run B<make> in the
878 extension's directory if it finds an XS file matching the
879 name of the extension's directory.
883 The typemap is a collection of code fragments which are used by the B<xsubpp>
884 compiler to map C function parameters and values to Perl values. The
885 typemap file may consist of three sections labeled C<TYPEMAP>, C<INPUT>, and
886 C<OUTPUT>. The INPUT section tells the compiler how to translate Perl values
887 into variables of certain C types. The OUTPUT section tells the compiler
888 how to translate the values from certain C types into values Perl can
889 understand. The TYPEMAP section tells the compiler which of the INPUT and
890 OUTPUT code fragments should be used to map a given C type to a Perl value.
891 Each of the sections of the typemap must be preceded by one of the TYPEMAP,
892 INPUT, or OUTPUT keywords.
894 The default typemap in the C<ext> directory of the Perl source contains many
895 useful types which can be used by Perl extensions. Some extensions define
896 additional typemaps which they keep in their own directory. These
897 additional typemaps may reference INPUT and OUTPUT maps in the main
898 typemap. The B<xsubpp> compiler will allow the extension's own typemap to
899 override any mappings which are in the default typemap.
901 Most extensions which require a custom typemap will need only the TYPEMAP
902 section of the typemap file. The custom typemap used in the
903 getnetconfigent() example shown earlier demonstrates what may be the typical
904 use of extension typemaps. That typemap is used to equate a C structure
905 with the T_PTROBJ typemap. The typemap used by getnetconfigent() is shown
906 here. Note that the C type is separated from the XS type with a tab and
907 that the C unary operator C<*> is considered to be a part of the C type name.
910 Netconfig *<tab>T_PTROBJ
914 File C<RPC.xs>: Interface to some ONC+ RPC bind library functions.
922 typedef struct netconfig Netconfig;
924 MODULE = RPC PACKAGE = RPC
927 rpcb_gettime(host="localhost")
932 ST(0) = sv_newmortal();
933 if( rpcb_gettime( host, &timep ) )
934 sv_setnv( ST(0), (double)timep );
938 getnetconfigent(netid="udp")
941 MODULE = RPC PACKAGE = NetconfigPtr PREFIX = rpcb_
944 rpcb_DESTROY(netconf)
947 printf("NetconfigPtr::DESTROY\n");
950 File C<typemap>: Custom typemap for RPC.xs.
955 File C<RPC.pm>: Perl module for the RPC extension.
961 @ISA = qw(Exporter DynaLoader);
962 @EXPORT = qw(rpcb_gettime getnetconfigent);
967 File C<rpctest.pl>: Perl test program for the RPC extension.
971 $netconf = getnetconfigent();
974 print "netconf = $netconf\n";
976 $netconf = getnetconfigent("tcp");
977 $a = rpcb_gettime("poplar");
979 print "netconf = $netconf\n";
984 Dean Roehrich F<E<lt>roehrich@cray.comE<gt>>