This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perl 5.000
[perl5.git] / pod / perlapi.pod
CommitLineData
a0d0e21e
LW
1=head1 NAME
2
3perlapi - Perl 5 application programming interface for C extensions
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
26Many of the examples which follow will concentrate on creating an
27interface between Perl and the ONC+RPC bind library functions.
28Specifically, the rpcb_gettime() function will be used to demonstrate many
29features of the XS language. This function has two parameters; the first
30is an input parameter and the second is an output parameter. The function
31also returns a status value.
32
33 bool_t rpcb_gettime(const char *host, time_t *timep);
34
35From C this function will be called with the following
36statements.
37
38 #include <rpc/rpc.h>
39 bool_t status;
40 time_t timep;
41 status = rpcb_gettime( "localhost", &timep );
42
43If an XSUB is created to offer a direct translation between this function
44and Perl, then this XSUB will be used from Perl with the following code.
45The $status and $timep variables will contain the output of the function.
46
47 use RPC;
48 $status = rpcb_gettime( "localhost", $timep );
49
50The following XS file shows an XS subroutine, or XSUB, which
51demonstrates one possible interface to the rpcb_gettime()
52function. This XSUB represents a direct translation between
53C and Perl and so preserves the interface even from Perl.
54This XSUB will be invoked from Perl with the usage shown
55above. Note that the first three #include statements, for
56C<EXTERN.h>, C<perl.h>, and C<XSUB.h>, will always be present at the
57beginning of an XS file. This approach and others will be
58expanded later in this document.
59
60 #include "EXTERN.h"
61 #include "perl.h"
62 #include "XSUB.h"
63 #include <rpc/rpc.h>
64
65 MODULE = RPC PACKAGE = RPC
66
67 bool_t
68 rpcb_gettime(host,timep)
69 char * host
70 time_t &timep
71 OUTPUT:
72 timep
73
74Any extension to Perl, including those containing XSUBs,
75should have a Perl module to serve as the bootstrap which
76pulls the extension into Perl. This module will export the
77extension's functions and variables to the Perl program and
78will cause the extension's XSUBs to be linked into Perl.
79The following module will be used for most of the examples
80in this document and should be used from Perl with the C<use>
81command as shown earlier. Perl modules are explained in
82more detail later in this document.
83
84 package RPC;
85
86 require Exporter;
87 require DynaLoader;
88 @ISA = qw(Exporter DynaLoader);
89 @EXPORT = qw( rpcb_gettime );
90
91 bootstrap RPC;
92 1;
93
94Throughout this document a variety of interfaces to the rpcb_gettime()
95XSUB will be explored. The XSUBs will take their parameters in different
96orders or will take different numbers of parameters. In each case the
97XSUB is an abstraction between Perl and the real C rpcb_gettime()
98function, and the XSUB must always ensure that the real rpcb_gettime()
99function is called with the correct parameters. This abstraction will
100allow the programmer to create a more Perl-like interface to the C
101function.
102
103=head2 The Anatomy of an XSUB
104
105The following XSUB allows a Perl program to access a C library function called sin(). The XSUB will imitate the C
106function which takes a single argument and returns a single
107value.
108
109 double
110 sin(x)
111 double<tab>x
112
113The compiler expects a tab between the parameter name and its type, and
114any or no whitespace before the type. When using C pointers the
115indirection operator C<*> should be considered part of the type and the
116address operator C<&> should be considered part of the variable, as is
117demonstrated in the rpcb_gettime() function above. See the section on
118typemaps for more about handling qualifiers and unary operators in C
119types.
120
121The parameter list of a function must not have whitespace
122after the open-parenthesis or before the close-parenthesis.
123
124 INCORRECT CORRECT
125
126 double double
127 sin( x ) sin(x)
128 double x double x
129
130The function name and the return type must be placed on
131separate lines.
132
133 INCORRECT CORRECT
134
135 double sin(x) double
136 double x sin(x)
137 double x
138
139=head2 The Argument Stack
140
141The argument stack is used to store the values which are
142sent as parameters to the XSUB and to store the XSUB's
143return value. In reality all Perl functions keep their
144values on this stack at the same time, each limited to its
145own range of positions on the stack. In this document the
146first position on that stack which belongs to the active
147function will be referred to as position 0 for that function.
148
149XSUBs refer to their stack arguments with the macro B<ST(x)>, where I<x> refers
150to a position in this XSUB's part of the stack. Position 0 for that
151function would be known to the XSUB as ST(0). The XSUB's incoming
152parameters and outgoing return values always begin at ST(0). For many
153simple cases the B<xsubpp> compiler will generate the code necessary to
154handle the argument stack by embedding code fragments found in the
155typemaps. In more complex cases the programmer must supply the code.
156
157=head2 The RETVAL Variable
158
159The RETVAL variable is a magic variable which always matches
160the return type of the C library function. The B<xsubpp> compiler will
161supply this variable in each XSUB and by default will use it to hold the
162return value of the C library function being called. In simple cases the
163value of RETVAL will be placed in ST(0) of the argument stack where it can
164be received by Perl as the return value of the XSUB.
165
166If the XSUB has a return type of C<void> then the compiler will
167not supply a RETVAL variable for that function. When using
168the PPCODE: directive the RETVAL variable may not be needed.
169
170=head2 The MODULE Keyword
171
172The MODULE keyword is used to start the XS code and to
173specify the package of the functions which are being
174defined. All text preceding the first MODULE keyword is
175considered C code and is passed through to the output
176untouched. Every XS module will have a bootstrap function
177which is used to hook the XSUBs into Perl. The package name
178of this bootstrap function will match the value of the last
179MODULE statement in the XS source files. The value of
180MODULE should always remain constant within the same XS
181file, though this is not required.
182
183The following example will start the XS code and will place
184all functions in a package named RPC.
185
186 MODULE = RPC
187
188=head2 The PACKAGE Keyword
189
190When functions within an XS source file must be separated into packages
191the PACKAGE keyword should be used. This keyword is used with the MODULE
192keyword and must follow immediately after it when used.
193
194 MODULE = RPC PACKAGE = RPC
195
196 [ XS code in package RPC ]
197
198 MODULE = RPC PACKAGE = RPCB
199
200 [ XS code in package RPCB ]
201
202 MODULE = RPC PACKAGE = RPC
203
204 [ XS code in package RPC ]
205
206Although this keyword is optional and in some cases provides redundant
207information it should always be used. This keyword will ensure that the
208XSUBs appear in the desired package.
209
210=head2 The PREFIX Keyword
211
212The PREFIX keyword designates prefixes which should be
213removed from the Perl function names. If the C function is
214C<rpcb_gettime()> and the PREFIX value is C<rpcb_> then Perl will
215see this function as C<gettime()>.
216
217This keyword should follow the PACKAGE keyword when used.
218If PACKAGE is not used then PREFIX should follow the MODULE
219keyword.
220
221 MODULE = RPC PREFIX = rpc_
222
223 MODULE = RPC PACKAGE = RPCB PREFIX = rpcb_
224
225=head2 The OUTPUT: Keyword
226
227The OUTPUT: keyword indicates that certain function parameters should be
228updated (new values made visible to Perl) when the XSUB terminates or that
229certain values should be returned to the calling Perl function. For
230simple functions, such as the sin() function above, the RETVAL variable is
231automatically designated as an output value. In more complex functions
232the B<xsubpp> compiler will need help to determine which variables are output
233variables.
234
235This keyword will normally be used to complement the CODE: keyword.
236The RETVAL variable is not recognized as an output variable when the
237CODE: keyword is present. The OUTPUT: keyword is used in this
238situation to tell the compiler that RETVAL really is an output
239variable.
240
241The OUTPUT: keyword can also be used to indicate that function parameters
242are output variables. This may be necessary when a parameter has been
243modified within the function and the programmer would like the update to
244be seen by Perl. If function parameters are listed under OUTPUT: along
245with the RETVAL variable then the RETVAL variable must be the last one
246listed.
247
248 bool_t
249 rpcb_gettime(host,timep)
250 char * host
251 time_t &timep
252 OUTPUT:
253 timep
254
255The OUTPUT: keyword will also allow an output parameter to
256be mapped to a matching piece of code rather than to a
257typemap.
258
259 bool_t
260 rpcb_gettime(host,timep)
261 char * host
262 time_t &timep
263 OUTPUT:
264 timep<tab>sv_setnv(ST(1), (double)timep);
265
266=head2 The CODE: Keyword
267
268This keyword is used in more complicated XSUBs which require
269special handling for the C function. The RETVAL variable is
270available but will not be returned unless it is specified
271under the OUTPUT: keyword.
272
273The following XSUB is for a C function which requires special handling of
274its parameters. The Perl usage is given first.
275
276 $status = rpcb_gettime( "localhost", $timep );
277
278The XSUB follows.
279
280 bool_t rpcb_gettime(host,timep)
281 char * host
282 time_t timep
283 CODE:
284 RETVAL = rpcb_gettime( host, &timep );
285 OUTPUT:
286 timep
287 RETVAL
288
289In many of the examples shown here the CODE: block (and
290other blocks) will often be contained within braces ( C<{> and
291C<}> ). This protects the CODE: block from complex INPUT
292typemaps and ensures the resulting C code is legal.
293
294=head2 The NO_INIT Keyword
295
296The NO_INIT keyword is used to indicate that a function
297parameter is being used only as an output value. The B<xsubpp>
298compiler will normally generate code to read the values of
299all function parameters from the argument stack and assign
300them to C variables upon entry to the function. NO_INIT
301will tell the compiler that some parameters will be used for
302output rather than for input and that they will be handled
303before the function terminates.
304
305The following example shows a variation of the rpcb_gettime() function.
306This function uses the timep variable only as an output variable and does
307not care about its initial contents.
308
309 bool_t
310 rpcb_gettime(host,timep)
311 char * host
312 time_t &timep = NO_INIT
313 OUTPUT:
314 timep
315
316=head2 Initializing Function Parameters
317
318Function parameters are normally initialized with their
319values from the argument stack. The typemaps contain the
320code segments which are used to transfer the Perl values to
321the C parameters. The programmer, however, is allowed to
322override the typemaps and supply alternate initialization
323code.
324
325The following code demonstrates how to supply initialization code for
326function parameters. The initialization code is eval'd by the compiler
327before it is added to the output so anything which should be interpreted
328literally, such as double quotes, must be protected with backslashes.
329
330 bool_t
331 rpcb_gettime(host,timep)
332 char * host = (char *)SvPV(ST(0),na);
333 time_t &timep = 0;
334 OUTPUT:
335 timep
336
337This should not be used to supply default values for parameters. One
338would normally use this when a function parameter must be processed by
339another library function before it can be used. Default parameters are
340covered in the next section.
341
342=head2 Default Parameter Values
343
344Default values can be specified for function parameters by
345placing an assignment statement in the parameter list. The
346default value may be a number or a string. Defaults should
347always be used on the right-most parameters only.
348
349To allow the XSUB for rpcb_gettime() to have a default host
350value the parameters to the XSUB could be rearranged. The
351XSUB will then call the real rpcb_gettime() function with
352the parameters in the correct order. Perl will call this
353XSUB with either of the following statements.
354
355 $status = rpcb_gettime( $timep, $host );
356
357 $status = rpcb_gettime( $timep );
358
359The XSUB will look like the code which follows. A CODE:
360block is used to call the real rpcb_gettime() function with
361the parameters in the correct order for that function.
362
363 bool_t
364 rpcb_gettime(timep,host="localhost")
365 char * host
366 time_t timep = NO_INIT
367 CODE:
368 RETVAL = rpcb_gettime( host, &timep );
369 OUTPUT:
370 timep
371 RETVAL
372
373=head2 Variable-length Parameter Lists
374
375XSUBs can have variable-length parameter lists by specifying an ellipsis
376C<(...)> in the parameter list. This use of the ellipsis is similar to that
377found in ANSI C. The programmer is able to determine the number of
378arguments passed to the XSUB by examining the C<items> variable which the
379B<xsubpp> compiler supplies for all XSUBs. By using this mechanism one can
380create an XSUB which accepts a list of parameters of unknown length.
381
382The I<host> parameter for the rpcb_gettime() XSUB can be
383optional so the ellipsis can be used to indicate that the
384XSUB will take a variable number of parameters. Perl should
385be able to call this XSUB with either of the following statments.
386
387 $status = rpcb_gettime( $timep, $host );
388
389 $status = rpcb_gettime( $timep );
390
391The XS code, with ellipsis, follows.
392
393 bool_t
394 rpcb_gettime(timep, ...)
395 time_t timep = NO_INIT
396 CODE:
397 {
398 char *host = "localhost";
399
400 if( items > 1 )
401 host = (char *)SvPV(ST(1), na);
402 RETVAL = rpcb_gettime( host, &timep );
403 }
404 OUTPUT:
405 timep
406 RETVAL
407
408=head2 The PPCODE: Keyword
409
410The PPCODE: keyword is an alternate form of the CODE: keyword and is used
411to tell the B<xsubpp> compiler that the programmer is supplying the code to
412control the argument stack for the XSUBs return values. Occassionally one
413will want an XSUB to return a list of values rather than a single value.
414In these cases one must use PPCODE: and then explicitly push the list of
415values on the stack. The PPCODE: and CODE: keywords are not used
416together within the same XSUB.
417
418The following XSUB will call the C rpcb_gettime() function
419and will return its two output values, timep and status, to
420Perl as a single list.
421
422 void rpcb_gettime(host)
423 char * host
424 PPCODE:
425 {
426 time_t timep;
427 bool_t status;
428 status = rpcb_gettime( host, &timep );
429 EXTEND(sp, 2);
430 PUSHs(sv_2mortal(newSVnv(status)));
431 PUSHs(sv_2mortal(newSVnv(timep)));
432 }
433
434Notice that the programmer must supply the C code necessary
435to have the real rpcb_gettime() function called and to have
436the return values properly placed on the argument stack.
437
438The C<void> return type for this function tells the B<xsubpp> compiler that
439the RETVAL variable is not needed or used and that it should not be created.
440In most scenarios the void return type should be used with the PPCODE:
441directive.
442
443The EXTEND() macro is used to make room on the argument
444stack for 2 return values. The PPCODE: directive causes the
445B<xsubpp> compiler to create a stack pointer called C<sp>, and it
446is this pointer which is being used in the EXTEND() macro.
447The values are then pushed onto the stack with the PUSHs()
448macro.
449
450Now the rpcb_gettime() function can be used from Perl with
451the following statement.
452
453 ($status, $timep) = rpcb_gettime("localhost");
454
455=head2 Returning Undef And Empty Lists
456
457Occassionally the programmer will want to simply return
458C<undef> or an empty list if a function fails rather than a
459separate status value. The rpcb_gettime() function offers
460just this situation. If the function succeeds we would like
461to have it return the time and if it fails we would like to
462have undef returned. In the following Perl code the value
463of $timep will either be undef or it will be a valid time.
464
465 $timep = rpcb_gettime( "localhost" );
466
467The following XSUB uses the C<void> return type to disable the generation of
468the RETVAL variable and uses a CODE: block to indicate to the compiler
469that the programmer has supplied all the necessary code. The
470sv_newmortal() call will initialize the return value to undef, making that
471the default return value.
472
473 void
474 rpcb_gettime(host)
475 char * host
476 CODE:
477 {
478 time_t timep;
479 bool_t x;
480 ST(0) = sv_newmortal();
481 if( rpcb_gettime( host, &timep ) )
482 sv_setnv( ST(0), (double)timep);
483 }
484
485The next example demonstrates how one would place an explicit undef in the
486return value, should the need arise.
487
488 void
489 rpcb_gettime(host)
490 char * host
491 CODE:
492 {
493 time_t timep;
494 bool_t x;
495 ST(0) = sv_newmortal();
496 if( rpcb_gettime( host, &timep ) ){
497 sv_setnv( ST(0), (double)timep);
498 }
499 else{
500 ST(0) = &sv_undef;
501 }
502 }
503
504To return an empty list one must use a PPCODE: block and
505then not push return values on the stack.
506
507 void
508 rpcb_gettime(host)
509 char * host
510 PPCODE:
511 {
512 time_t timep;
513 if( rpcb_gettime( host, &timep ) )
514 PUSHs(sv_2mortal(newSVnv(timep)));
515 else{
516 /* Nothing pushed on stack, so an empty */
517 /* list is implicitly returned. */
518 }
519 }
520
521=head2 The CLEANUP: Keyword
522
523This keyword can be used when an XSUB requires special cleanup procedures
524before it terminates. When the CLEANUP: keyword is used it must follow
525any CODE:, PPCODE:, or OUTPUT: blocks which are present in the XSUB. The
526code specified for the cleanup block will be added as the last statements
527in the XSUB.
528
529=head2 The BOOT: Keyword
530
531The BOOT: keyword is used to add code to the extension's bootstrap
532function. The bootstrap function is generated by the B<xsubpp> compiler and
533normally holds the statements necessary to register any XSUBs with Perl.
534With the BOOT: keyword the programmer can tell the compiler to add extra
535statements to the bootstrap function.
536
537This keyword may be used any time after the first MODULE keyword and should
538appear on a line by itself. The first blank line after the keyword will
539terminate the code block.
540
541 BOOT:
542 # The following message will be printed when the
543 # bootstrap function executes.
544 printf("Hello from the bootstrap!\n");
545
546=head2 Inserting Comments and C Preprocessor Directives
547
548Comments and C preprocessor directives are allowed within
549CODE:, PPCODE:, BOOT:, and CLEANUP: blocks. The compiler
550will pass the preprocessor directives through untouched and
551will remove the commented lines. Comments can be added to
552XSUBs by placing a C<#> at the beginning of the line. Care
553should be taken to avoid making the comment look like a C
554preprocessor directive, lest it be interpreted as such.
555
556=head2 Using XS With C++
557
558If a function is defined as a C++ method then it will assume
559its first argument is an object pointer. The object pointer
560will be stored in a variable called THIS. The object should
561have been created by C++ with the new() function and should
562be blessed by Perl with the sv_setptrobj() macro. The
563blessing of the object by Perl can be handled by the
564T_PTROBJ typemap.
565
566If the method is defined as static it will call the C++
567function using the class::method() syntax. If the method is not static
568the function will be called using the THIS->method() syntax.
569
570=head2 Perl Variables
571
572The following demonstrates how the Perl variable $host can
573be accessed from an XSUB. The function B<perl_get_sv()> is
574used to obtain a pointer to the variable, known as an B<SV>
575(Scalar Variable) internally. The package name C<RPC> will be
576added to the name of the variable so perl_get_sv() will know
577in which package $host can be found. If the package name is
578not supplied then perl_get_sv() will search package C<main> for
579the variable. The macro B<SvPVX()> is then used to dereference
580the SV to obtain a C<char*> pointer to its contents.
581
582 void
583 rpcb_gettime()
584 PPCODE:
585 {
586 char *host;
587 SV *hostsv;
588 time_t timep;
589
590 hostsv = perl_get_sv( "RPC::host", FALSE );
591 if( hostsv != NULL ){
592 host = SvPVX( hostsv );
593 if( rpcb_gettime( host, &timep ) )
594 PUSHs(sv_2mortal(newSVnv(timep)));
595 }
596 }
597
598This Perl code can be used to call that XSUB.
599
600 $RPC::host = "localhost";
601 $timep = rpcb_gettime();
602
603In the above example the SV contained a C C<char*> but a Perl
604scalar variable may also contain numbers and references. If
605the SV is expected to have a C C<int> then the macro B<SvIVX()>
606should be used to dereference the SV. When the SV contains
607a C double then B<SvNVX()> should be used.
608
609The macro B<SvRV()> can be used to dereference an SV when it is a Perl
610reference. The result will be another SV which points to the actual Perl
611variable. This can then be dereferenced with SvPVX(), SvNVX(), or
612SvIVX(). The following XSUB will use SvRV().
613
614 void rpcb_gettime()
615 PPCODE:
616 {
617 char *host;
618 SV *rv;
619 SV *hostsv;
620 time_t timep;
621
622 rv = perl_get_sv( "RPC::host", FALSE );
623 if( rv != NULL ){
624 hostsv = SvRV( rv );
625 host = SvPVX( hostsv );
626 if( rpcb_gettime( host, &timep ) )
627 PUSHs(sv_2mortal(newSVnv(timep)));
628 }
629 }
630
631This Perl code will create a variable $RPC::host which is a
632reference to $MY::host. The variable $MY::host contains the
633hostname which will be used.
634
635 $MY::host = "localhost";
636 $RPC::host = \$MY::host;
637 $timep = rpcb_gettime();
638
639The second argument to perl_get_sv() will normally be B<FALSE>
640as shown in the above examples. An argument of B<TRUE> will
641cause variables to be created if they do not already exist.
642One should not use TRUE unless steps are taken to deal with
643a possibly empty SV.
644
645XSUBs may use B<perl_get_av()>, B<perl_get_hv()>, and B<perl_get_cv()> to
646access Perl arrays, hashes, and code values.
647
648=head2 Interface Stategy
649
650When designing an interface between Perl and a C library a straight
651translation from C to XS is often sufficient. The interface will often be
652very C-like and occasionally nonintuitive, especially when the C function
653modifies one of its parameters. In cases where the programmer wishes to
654create a more Perl-like interface the following strategy may help to
655identify the more critical parts of the interface.
656
657Identify the C functions which modify their parameters. The XSUBs for
658these functions may be able to return lists to Perl, or may be
659candidates to return undef or an empty list in case of failure.
660
661Identify which values are used only by the C and XSUB functions
662themselves. If Perl does not need to access the contents of the value
663then it may not be necessary to provide a translation for that value
664from C to Perl.
665
666Identify the pointers in the C function parameter lists and return
667values. Some pointers can be handled in XS with the & unary operator on
668the variable name while others will require the use of the * operator on
669the type name. In general it is easier to work with the & operator.
670
671Identify the structures used by the C functions. In many
672cases it may be helpful to use the T_PTROBJ typemap for
673these structures so they can be manipulated by Perl as
674blessed objects.
675
676=head2 The Perl Module
677
678The Perl module is the link between the extension library,
679which was generated from XS code, and the Perl interpreter.
680The module is used to tell Perl what the extension library
681contains. The name and package of the module should match
682the name of the library.
683
684The following is a Perl module for an extension containing
685some ONC+ RPC bind library functions.
686
687 package RPC;
688
689 require Exporter;
690 require DynaLoader;
691 @ISA = qw(Exporter DynaLoader);
692 @EXPORT = qw( rpcb_gettime rpcb_getmaps rpcb_getaddr
693 rpcb_rmtcall rpcb_set rpcb_unset );
694
695 bootstrap RPC;
696 1;
697
698The RPC extension contains the functions found in the
699@EXPORT list. By using the C<Exporter> module the RPC module
700can make these function names visible to the rest of the
701Perl program. The C<DynaLoader> module will allow the RPC
702module to bootstrap the extension library. To load this
703extension and make the functions available, the following
704Perl statement should be used.
705
706 use RPC;
707
708For more information about the DynaLoader consult its documentation in the
709ext/DynaLoader directory in the Perl source.
710
711=head2 Perl Objects And C Structures
712
713When dealing with C structures one should select either
714B<T_PTROBJ> or B<T_PTRREF> for the XS type. Both types are
715designed to handle pointers to complex objects. The
716T_PTRREF type will allow the Perl object to be unblessed
717while the T_PTROBJ type requires that the object be blessed.
718By using T_PTROBJ one can achieve a form of type-checking
719since the XSUB will attempt to verify that the Perl object
720is of the expected type.
721
722The following XS code shows the getnetconfigent() function which is used
723with ONC TIRPC. The getnetconfigent() function will return a pointer to a
724C structure and has the C prototype shown below. The example will
725demonstrate how the C pointer will become a Perl reference. Perl will
726consider this reference to be a pointer to a blessed object and will
727attempt to call a destructor for the object. A destructor will be
728provided in the XS source to free the memory used by getnetconfigent().
729Destructors in XS can be created by specifying an XSUB function whose name
730ends with the word B<DESTROY>. XS destructors can be used to free memory
731which may have been malloc'd by another XSUB.
732
733 struct netconfig *getnetconfigent(const char *netid);
734
735A C<typedef> will be created for C<struct netconfig>. The Perl
736object will be blessed in a class matching the name of the C
737type, with the tag C<Ptr> appended, and the name should not
738have embedded spaces if it will be a Perl package name. The
739destructor will be placed in a class corresponding to the
740class of the object and the PREFIX keyword will be used to
741trim the name to the word DESTROY as Perl will expect.
742
743 typedef struct netconfig Netconfig;
744
745 MODULE = RPC PACKAGE = RPC
746
747 Netconfig *
748 getnetconfigent(netid)
749 char * netid
750
751 MODULE = RPC PACKAGE = NetconfigPtr PREFIX = rpcb_
752
753 void
754 rpcb_DESTROY(netconf)
755 Netconfig * netconf
756 CODE:
757 printf("Now in NetconfigPtr::DESTROY\n");
758 free( netconf );
759
760This example requires the following typemap entry. Consult the typemap
761section for more information about adding new typemaps for an extension.
762
763 TYPEMAP
764 Netconfig * T_PTROBJ
765
766This example will be used with the following Perl statements.
767
768 use RPC;
769 $netconf = getnetconfigent("udp");
770
771When Perl destroys the object referenced by $netconf it will send the
772object to the supplied XSUB DESTROY function. Perl cannot determine, and
773does not care, that this object is a C struct and not a Perl object. In
774this sense, there is no difference between the object created by the
775getnetconfigent() XSUB and an object created by a normal Perl subroutine.
776
777=head2 C Headers and Perl
778
779The B<h2xs> compiler is designed to convert C header files in
780/usr/include into Perl extensions. This compiler will
781create a directory under the C<ext> directory of the Perl
782source and will populate it with a Makefile, a Perl Module,
783an XS source file, and a MANIFEST file.
784
785The following command will create an extension called C<Rusers>
786from the <rpcsvc/rusers.h> header.
787
788 h2xs rpcsvc/rusers
789
790When the Rusers extension has been compiled and installed
791Perl can use it to retrieve any C<#define> statements which
792were in the C header.
793
794 use Rusers;
795 print "RPC program number for rusers service: ";
796 print &RUSERSPROG, "\n";
797
798=head2 Creating A New Extension
799
800The B<h2xs> compiler can generate template source files and
801Makefiles. These templates offer a suitable starting point
802for most extensions. The following example demonstrates how
803one might use B<h2xs> to create an extension containing the RPC
804functions in this document.
805
806The extension will not use autoloaded functions and will not define
807constants, so the B<-A> option will be given to B<h2xs>. When run from the
808Perl source directory, the B<h2xs> compiler will create the directory
809ext/RPC and will populate it with files called RPC.xs, RPC.pm, Makefile.PL,
810and MANIFEST. The XS code for the RPC functions should be added to the
811RPC.xs file. The @EXPORT list in RPC.pm should be updated to include the
812functions from RPC.xs.
813
814 h2xs -An RPC
815
816To compile the extension for dynamic loading the following
817command should be executed from the ext/RPC directory.
818
819 make dynamic
820
821If the extension will be statically linked into the Perl
822binary then the makefile (use C<makefile>, not C<Makefile>) in the
823Perl source directory should be edited to add C<ext/RPC/RPC.a>
824to the C<static_ext> variable. Before making this change Perl
825should have already been built. After the makefile has been
826updated the following command should be executed from the
827Perl source directory.
828
829 make
830
831Perl's B<Configure> script can also be used to add extensions. The extension
832should be placed in the C<ext> directory under the Perl source before Perl
833has been built and prior to running Configure. When Configure is run it
834will find the extension along with the other extensions in the C<ext>
835directory and will add it to the list of extensions to be built. When make
836is run the extension will be built along with the other extensions.
837
838Configure recognizes extensions if they have an XS source
839file which matches the name of the extension directory. If
840the extension directory includes a MANIFEST file Configure
841will search that file for any B<.SH> files and extract them
842after it extracts all the other .SH files listed in the main
843MANIFEST. The main Perl Makefile will then run B<make> in the
844extension's directory if it finds an XS file matching the
845name of the extension's directory.
846
847=head2 The Typemap
848
849The typemap is a collection of code fragments which are used by the B<xsubpp>
850compiler to map C function parameters and values to Perl values. The
851typemap file may consist of three sections labeled C<TYPEMAP>, C<INPUT>, and
852C<OUTPUT>. The INPUT section tells the compiler how to translate Perl values
853into variables of certain C types. The OUTPUT section tells the compiler
854how to translate the values from certain C types into values Perl can
855understand. The TYPEMAP section tells the compiler which of the INPUT and
856OUTPUT code fragments should be used to map a given C type to a Perl value.
857Each of the sections of the typemap must be preceded by one of the TYPEMAP,
858INPUT, or OUTPUT keywords.
859
860The default typemap in the C<ext> directory of the Perl source contains many
861useful types which can be used by Perl extensions. Some extensions define
862additional typemaps which they keep in their own directory. These
863additional typemaps may reference INPUT and OUTPUT maps in the main
864typemap. The B<xsubpp> compiler will allow the extension's own typemap to
865override any mappings which are in the default typemap.
866
867Most extensions which require a custom typemap will need only the TYPEMAP
868section of the typemap file. The custom typemap used in the
869getnetconfigent() example shown earlier demonstrates what may be the typical
870use of extension typemaps. That typemap is used to equate a C structure
871with the T_PTROBJ typemap. The typemap used by getnetconfigent() is shown
872here. Note that the C type is separated from the XS type with a tab and
873that the C unary operator C<*> is considered to be a part of the C type name.
874
875 TYPEMAP
876 Netconfig *<tab>T_PTROBJ
877
878=head1 EXAMPLES
879
880File C<RPC.xs>: Interface to some ONC+ RPC bind library functions.
881
882 #include "EXTERN.h"
883 #include "perl.h"
884 #include "XSUB.h"
885
886 #include <rpc/rpc.h>
887
888 typedef struct netconfig Netconfig;
889
890 MODULE = RPC PACKAGE = RPC
891
892 void
893 rpcb_gettime(host="localhost")
894 char * host
895 CODE:
896 {
897 time_t timep;
898 ST(0) = sv_newmortal();
899 if( rpcb_gettime( host, &timep ) )
900 sv_setnv( ST(0), (double)timep );
901 }
902
903 Netconfig *
904 getnetconfigent(netid="udp")
905 char * netid
906
907 MODULE = RPC PACKAGE = NetconfigPtr PREFIX = rpcb_
908
909 void
910 rpcb_DESTROY(netconf)
911 Netconfig * netconf
912 CODE:
913 printf("NetconfigPtr::DESTROY\n");
914 free( netconf );
915
916File C<typemap>: Custom typemap for RPC.xs.
917
918 TYPEMAP
919 Netconfig * T_PTROBJ
920
921File C<RPC.pm>: Perl module for the RPC extension.
922
923 package RPC;
924
925 require Exporter;
926 require DynaLoader;
927 @ISA = qw(Exporter DynaLoader);
928 @EXPORT = qw(rpcb_gettime getnetconfigent);
929
930 bootstrap RPC;
931 1;
932
933File C<rpctest.pl>: Perl test program for the RPC extension.
934
935 use RPC;
936
937 $netconf = getnetconfigent();
938 $a = rpcb_gettime();
939 print "time = $a\n";
940 print "netconf = $netconf\n";
941
942 $netconf = getnetconfigent("tcp");
943 $a = rpcb_gettime("poplar");
944 print "time = $a\n";
945 print "netconf = $netconf\n";
946
947
948=head1 AUTHOR
949
950Dean Roehrich <roehrich@cray.com>
951September 27, 1994