Debian Codegraph @

upstream/opensuse-tumbleweed/man1/perlxs.1

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "PERLXS 1"
61 .TH PERLXS 1 2026-03-09 "perl v5.42.1" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 perlxs \- XS language reference manual
68 .SH DESCRIPTION
69 .IX Header "DESCRIPTION"
70 .SS Introduction
71 .IX Subsection "Introduction"
72 XS is an interface description file format used to create an extension
73 interface between Perl and C code (or a C library) which one wishes
74 to use with Perl. The XS interface is combined with the library to
75 create a new library which can then be either dynamically loaded
76 or statically linked into perl. The XS interface description is
77 written in the XS language and is the core component of the Perl
78 extension interface.
79 .PP
80 This documents the XS language, but it\*(Aqs important to first note that XS
81 code has full access to system calls including C library functions. It
82 thus has the capability of interfering with things that the Perl core or
83 other modules have set up, such as signal handlers or file handles. It
84 could mess with the memory, or any number of harmful things. Don\*(Aqt.
85 Further detail is in perlclib, which you should read before actually
86 writing any production XS.
87 .PP
88 An \fBXSUB\fR forms the basic unit of the XS interface. After compilation
89 by the \fBxsubpp\fR compiler, each XSUB amounts to a C function definition
90 which will provide the glue between Perl calling conventions and C
91 calling conventions.
92 .PP
93 The glue code pulls the arguments from the Perl stack, converts these
94 Perl values to the formats expected by a C function, calls this C function,
95 and then transfers the return values of the C function back to Perl.
96 Return values here may be a conventional C return value or any C
97 function arguments that may serve as output parameters. These return
98 values may be passed back to Perl either by putting them on the
99 Perl stack, or by modifying the arguments supplied from the Perl side.
100 .PP
101 The above is a somewhat simplified view of what really happens. Since
102 Perl allows more flexible calling conventions than C, XSUBs may do much
103 more in practice, such as checking input parameters for validity,
104 throwing exceptions (or returning undef/empty list) if the return value
105 from the C function indicates failure, calling different C functions
106 based on numbers and types of the arguments, providing an object\-oriented
107 interface, etc.
108 .PP
109 Of course, one could write such glue code directly in C. However, this
110 would be a tedious task, especially if one needs to write glue for
111 multiple C functions, and/or one is not familiar enough with the Perl
112 stack discipline and other such arcana. XS comes to the rescue here:
113 instead of writing this glue C code in long\-hand, one can write
114 a more concise short\-hand \fIdescription\fR of what should be done by
115 the glue, and let the XS compiler \fBxsubpp\fR handle the rest.
116 .PP
117 The XS language allows one to describe the mapping between how the C
118 routine is used, and how the corresponding Perl routine is used. It
119 also allows creation of Perl routines which are directly translated to
120 C code and which are not related to a pre\-existing C function. In cases
121 when the C interface coincides with the Perl interface, the XSUB
122 declaration is almost identical to a declaration of a C function (in K&R
123 style). In such circumstances, there is another tool called \f(CW\*(C`h2xs\*(C'\fR
124 that is able to translate an entire C header file into a corresponding
125 XS file that will provide glue to the functions/macros described in
126 the header file.
127 .PP
128 The XS compiler is called \fBxsubpp\fR. This compiler creates
129 the constructs necessary to let an XSUB manipulate Perl values, and
130 creates the glue necessary to let Perl call the XSUB. The compiler
131 uses \fBtypemaps\fR to determine how to map C function parameters
132 and output values to Perl values and back. The default typemap
133 (which comes with Perl) handles many common C types. A supplementary
134 typemap may also be needed to handle any special structures and types
135 for the library being linked. For more information on typemaps,
136 see perlxstypemap.
137 .PP
138 A file in XS format starts with a C language section which goes until the
139 first \f(CW\*(C`MODULE =\*(C'\fR directive. Other XS directives and XSUB definitions
140 may follow this line. The "language" used in this part of the file
141 is usually referred to as the XS language. \fBxsubpp\fR recognizes and
142 skips POD (see perlpod) in both the C and XS language sections, which
143 allows the XS file to contain embedded documentation.
144 .PP
145 See perlxstut for a tutorial on the whole extension creation process.
146 .PP
147 Note: For some extensions, Dave Beazley\*(Aqs SWIG system may provide a
148 significantly more convenient mechanism for creating the extension
149 glue code. See <http://www.swig.org/> for more information.
150 .PP
151 For simple bindings to C libraries as well as other machine code libraries,
152 consider instead using the much simpler
153 libffi <http://sourceware.org/libffi/> interface via CPAN modules like
154 FFI::Platypus or FFI::Raw.
155 .SS "On The Road"
156 .IX Subsection "On The Road"
157 Many of the examples which follow will concentrate on creating an interface
158 between Perl and the ONC+ RPC bind library functions. The \fBrpcb_gettime()\fR
159 function is used to demonstrate many features of the XS language. This
160 function has two parameters; the first is an input parameter and the second
161 is an output parameter. The function also returns a status value.
162 .PP
163 .Vb 1
164 \& bool_t rpcb_gettime(const char *host, time_t *timep);
165 .Ve
166 .PP
167 From C this function will be called with the following
168 statements.
169 .PP
170 .Vb 4
171 \& #include <rpc/rpc.h>
172 \& bool_t status;
173 \& time_t timep;
174 \& status = rpcb_gettime( "localhost", &timep );
175 .Ve
176 .PP
177 If an XSUB is created to offer a direct translation between this function
178 and Perl, then this XSUB will be used from Perl with the following code.
179 The \f(CW$status\fR and \f(CW$timep\fR variables will contain the output of the function.
180 .PP
181 .Vb 2
182 \& use RPC;
183 \& $status = rpcb_gettime( "localhost", $timep );
184 .Ve
185 .PP
186 The following XS file shows an XS subroutine, or XSUB, which
187 demonstrates one possible interface to the \fBrpcb_gettime()\fR
188 function. This XSUB represents a direct translation between
189 C and Perl and so preserves the interface even from Perl.
190 This XSUB will be invoked from Perl with the usage shown
191 above. Note that the first three #include statements, for
192 \&\f(CW\*(C`EXTERN.h\*(C'\fR, \f(CW\*(C`perl.h\*(C'\fR, and \f(CW\*(C`XSUB.h\*(C'\fR, will always be present at the
193 beginning of an XS file. This approach and others will be
194 expanded later in this document. A #define for \f(CW\*(C`PERL_NO_GET_CONTEXT\*(C'\fR
195 should be present to fetch the interpreter context more efficiently,
196 see perlguts for details.
197 .PP
198 .Vb 5
199 \& #define PERL_NO_GET_CONTEXT
200 \& #include "EXTERN.h"
201 \& #include "perl.h"
202 \& #include "XSUB.h"
203 \& #include <rpc/rpc.h>
204 \&
205 \& MODULE = RPC PACKAGE = RPC
206 \&
207 \& bool_t
208 \& rpcb_gettime(host,timep)
209 \& char *host
210 \& time_t &timep
211 \& OUTPUT:
212 \& timep
213 .Ve
214 .PP
215 Any extension to Perl, including those containing XSUBs,
216 should have a Perl module to serve as the bootstrap which
217 pulls the extension into Perl. This module will export the
218 extension\*(Aqs functions and variables to the Perl program and
219 will cause the extension\*(Aqs XSUBs to be linked into Perl.
220 The following module will be used for most of the examples
221 in this document and should be used from Perl with the \f(CW\*(C`use\*(C'\fR
222 command as shown earlier. Perl modules are explained in
223 more detail later in this document.
224 .PP
225 .Vb 1
226 \& package RPC;
227 \&
228 \& require Exporter;
229 \& require DynaLoader;
230 \& @ISA = qw(Exporter DynaLoader);
231 \& @EXPORT = qw( rpcb_gettime );
232 \&
233 \& bootstrap RPC;
234 \& 1;
235 .Ve
236 .PP
237 Throughout this document a variety of interfaces to the \fBrpcb_gettime()\fR
238 XSUB will be explored. The XSUBs will take their parameters in different
239 orders or will take different numbers of parameters. In each case the
240 XSUB is an abstraction between Perl and the real C \fBrpcb_gettime()\fR
241 function, and the XSUB must always ensure that the real \fBrpcb_gettime()\fR
242 function is called with the correct parameters. This abstraction will
243 allow the programmer to create a more Perl\-like interface to the C
244 function.
245 .SS "The Anatomy of an XSUB"
246 .IX Subsection "The Anatomy of an XSUB"
247 The simplest XSUBs consist of 3 parts: a description of the return
248 value, the name of the XSUB routine and the names of its arguments,
249 and a description of types or formats of the arguments.
250 .PP
251 The following XSUB allows a Perl program to access a C library function
252 called \fBsin()\fR. The XSUB will imitate the C function which takes a single
253 argument and returns a single value.
254 .PP
255 .Vb 3
256 \& double
257 \& sin(x)
258 \& double x
259 .Ve
260 .PP
261 Optionally, one can merge the description of types and the list of
262 argument names, rewriting this as
263 .PP
264 .Vb 2
265 \& double
266 \& sin(double x)
267 .Ve
268 .PP
269 This makes this XSUB look similar to an ANSI C declaration. An optional
270 semicolon is allowed after the argument list, as in
271 .PP
272 .Vb 2
273 \& double
274 \& sin(double x);
275 .Ve
276 .PP
277 Parameters with C pointer types can have different semantic: C functions
278 with similar declarations
279 .PP
280 .Vb 2
281 \& bool string_looks_as_a_number(char *s);
282 \& bool make_char_uppercase(char *c);
283 .Ve
284 .PP
285 are used in absolutely incompatible manner. Parameters to these functions
286 could be described to \fBxsubpp\fR like this:
287 .PP
288 .Vb 2
289 \& char * s
290 \& char &c
291 .Ve
292 .PP
293 Both these XS declarations correspond to the \f(CW\*(C`char*\*(C'\fR C type, but they have
294 different semantics, see "The & Unary Operator".
295 .PP
296 It is convenient to think that the indirection operator
297 \&\f(CW\*(C`*\*(C'\fR should be considered as a part of the type and the address operator \f(CW\*(C`&\*(C'\fR
298 should be considered part of the variable. See perlxstypemap
299 for more info about handling qualifiers and unary operators in C types.
300 .PP
301 The function name and the return type must be placed on
302 separate lines and should be flush left\-adjusted.
303 .PP
304 .Vb 1
305 \& INCORRECT CORRECT
306 \&
307 \& double sin(x) double
308 \& double x sin(x)
309 \& double x
310 .Ve
311 .PP
312 The rest of the function description may be indented or left\-adjusted. The
313 following example shows a function with its body left\-adjusted. Most
314 examples in this document will indent the body for better readability.
315 .PP
316 .Vb 1
317 \& CORRECT
318 \&
319 \& double
320 \& sin(x)
321 \& double x
322 .Ve
323 .PP
324 More complicated XSUBs may contain many other sections. Each section of
325 an XSUB starts with the corresponding keyword, such as INIT: or CLEANUP:.
326 However, the first two lines of an XSUB always contain the same data:
327 descriptions of the return type and the names of the function and its
328 parameters. Whatever immediately follows these is considered to be
329 an INPUT: section unless explicitly marked with another keyword.
330 (See "The INPUT: Keyword".)
331 .PP
332 An XSUB section continues until another section\-start keyword is found.
333 .SS "The Argument Stack"
334 .IX Subsection "The Argument Stack"
335 The Perl argument stack is used to store the values which are
336 sent as parameters to the XSUB and to store the XSUB\*(Aqs
337 return value(s). In reality all Perl functions (including non\-XSUB
338 ones) keep their values on this stack all the same time, each limited
339 to its own range of positions on the stack. In this document the
340 first position on that stack which belongs to the active
341 function will be referred to as position 0 for that function.
342 .PP
343 XSUBs refer to their stack arguments with the macro \fBST(x)\fR, where \fIx\fR
344 refers to a position in this XSUB\*(Aqs part of the stack. Position 0 for that
345 function would be known to the XSUB as \fBST\fR\|(0). The XSUB\*(Aqs incoming
346 parameters and outgoing return values always begin at \fBST\fR\|(0). For many
347 simple cases the \fBxsubpp\fR compiler will generate the code necessary to
348 handle the argument stack by embedding code fragments found in the
349 typemaps. In more complex cases the programmer must supply the code.
350 .SS "The RETVAL Variable"
351 .IX Subsection "The RETVAL Variable"
352 The RETVAL variable is a special C variable that is declared automatically
353 for you. The C type of RETVAL matches the return type of the C library
354 function. The \fBxsubpp\fR compiler will declare this variable in each XSUB
355 with non\-\f(CW\*(C`void\*(C'\fR return type. By default the generated C function
356 will use RETVAL to hold the return value of the C library function being
357 called. In simple cases the value of RETVAL will be placed in \fBST\fR\|(0) of
358 the argument stack where it can be received by Perl as the return value
359 of the XSUB.
360 .PP
361 If the XSUB has a return type of \f(CW\*(C`void\*(C'\fR then the compiler will
362 not declare a RETVAL variable for that function. When using
363 a PPCODE: section no manipulation of the RETVAL variable is required, the
364 section may use direct stack manipulation to place output values on the stack.
365 .PP
366 If PPCODE: directive is not used, \f(CW\*(C`void\*(C'\fR return value should be used
367 only for subroutines which do not return a value, \fIeven if\fR CODE:
368 directive is used which sets \fBST\fR\|(0) explicitly.
369 .PP
370 Older versions of this document recommended to use \f(CW\*(C`void\*(C'\fR return
371 value in such cases. It was discovered that this could lead to
372 segfaults in cases when XSUB was \fItruly\fR \f(CW\*(C`void\*(C'\fR. This practice is
373 now deprecated, and may be not supported at some future version. Use
374 the return value \f(CW\*(C`SV *\*(C'\fR in such cases. (Currently \f(CW\*(C`xsubpp\*(C'\fR contains
375 some heuristic code which tries to disambiguate between "truly\-void"
376 and "old\-practice\-declared\-as\-void" functions. Hence your code is at
377 mercy of this heuristics unless you use \f(CW\*(C`SV *\*(C'\fR as return value.)
378 .SS "Returning SVs, AVs and HVs through RETVAL"
379 .IX Subsection "Returning SVs, AVs and HVs through RETVAL"
380 When you\*(Aqre using RETVAL to return an \f(CW\*(C`SV *\*(C'\fR, there\*(Aqs some magic
381 going on behind the scenes that should be mentioned. When you\*(Aqre
382 manipulating the argument stack using the ST(x) macro, for example,
383 you usually have to pay special attention to reference counts. (For
384 more about reference counts, see perlguts.) To make your life
385 easier, the typemap file automatically makes \f(CW\*(C`RETVAL\*(C'\fR mortal when
386 you\*(Aqre returning an \f(CW\*(C`SV *\*(C'\fR. Thus, the following two XSUBs are more
387 or less equivalent:
388 .PP
389 .Vb 6
390 \& void
391 \& alpha()
392 \& PPCODE:
393 \& ST(0) = newSVpv("Hello World",0);
394 \& sv_2mortal(ST(0));
395 \& XSRETURN(1);
396 \&
397 \& SV *
398 \& beta()
399 \& CODE:
400 \& RETVAL = newSVpv("Hello World",0);
401 \& OUTPUT:
402 \& RETVAL
403 .Ve
404 .PP
405 This is quite useful as it usually improves readability. While
406 this works fine for an \f(CW\*(C`SV *\*(C'\fR, it\*(Aqs unfortunately not as easy
407 to have \f(CW\*(C`AV *\*(C'\fR or \f(CW\*(C`HV *\*(C'\fR as a return value. You \fIshould\fR be
408 able to write:
409 .PP
410 .Vb 7
411 \& AV *
412 \& array()
413 \& CODE:
414 \& RETVAL = newAV();
415 \& /* do something with RETVAL */
416 \& OUTPUT:
417 \& RETVAL
418 .Ve
419 .PP
420 But due to an unfixable bug (fixing it would break lots of existing
421 CPAN modules) in the typemap file, the reference count of the \f(CW\*(C`AV *\*(C'\fR
422 is not properly decremented. Thus, the above XSUB would leak memory
423 whenever it is being called. The same problem exists for \f(CW\*(C`HV *\*(C'\fR,
424 \&\f(CW\*(C`CV *\*(C'\fR, and \f(CW\*(C`SVREF\*(C'\fR (which indicates a scalar reference, not
425 a general \f(CW\*(C`SV *\*(C'\fR).
426 In XS code on perls starting with perl 5.16, you can override the
427 typemaps for any of these types with a version that has proper
428 handling of refcounts. In your \f(CW\*(C`TYPEMAP\*(C'\fR section, do
429 .PP
430 .Vb 1
431 \& AV* T_AVREF_REFCOUNT_FIXED
432 .Ve
433 .PP
434 to get the repaired variant. For backward compatibility with older
435 versions of perl, you can instead decrement the reference count
436 manually when you\*(Aqre returning one of the aforementioned
437 types using \f(CW\*(C`sv_2mortal\*(C'\fR:
438 .PP
439 .Vb 8
440 \& AV *
441 \& array()
442 \& CODE:
443 \& RETVAL = newAV();
444 \& sv_2mortal((SV*)RETVAL);
445 \& /* do something with RETVAL */
446 \& OUTPUT:
447 \& RETVAL
448 .Ve
449 .PP
450 Remember that you don\*(Aqt have to do this for an \f(CW\*(C`SV *\*(C'\fR. The reference
451 documentation for all core typemaps can be found in perlxstypemap.
452 .SS "The MODULE Keyword"
453 .IX Subsection "The MODULE Keyword"
454 The MODULE keyword is used to start the XS code and to specify the package
455 of the functions which are being defined. All text preceding the first
456 MODULE keyword is considered C code and is passed through to the output with
457 POD stripped, but otherwise untouched. Every XS module will have a
458 bootstrap function which is used to hook the XSUBs into Perl. The package
459 name of this bootstrap function will match the value of the last MODULE
460 statement in the XS source files. The value of MODULE should always remain
461 constant within the same XS file, though this is not required.
462 .PP
463 The following example will start the XS code and will place
464 all functions in a package named RPC.
465 .PP
466 .Vb 1
467 \& MODULE = RPC
468 .Ve
469 .SS "The PACKAGE Keyword"
470 .IX Subsection "The PACKAGE Keyword"
471 When functions within an XS source file must be separated into packages
472 the PACKAGE keyword should be used. This keyword is used with the MODULE
473 keyword and must follow immediately after it when used.
474 .PP
475 .Vb 1
476 \& MODULE = RPC PACKAGE = RPC
477 \&
478 \& [ XS code in package RPC ]
479 \&
480 \& MODULE = RPC PACKAGE = RPCB
481 \&
482 \& [ XS code in package RPCB ]
483 \&
484 \& MODULE = RPC PACKAGE = RPC
485 \&
486 \& [ XS code in package RPC ]
487 .Ve
488 .PP
489 The same package name can be used more than once, allowing for
490 non\-contiguous code. This is useful if you have a stronger ordering
491 principle than package names.
492 .PP
493 Although this keyword is optional and in some cases provides redundant
494 information it should always be used. This keyword will ensure that the
495 XSUBs appear in the desired package.
496 .SS "The PREFIX Keyword"
497 .IX Subsection "The PREFIX Keyword"
498 The PREFIX keyword designates prefixes which should be
499 removed from the Perl function names. If the C function is
500 \&\f(CWrpcb_gettime()\fR and the PREFIX value is \f(CW\*(C`rpcb_\*(C'\fR then Perl will
501 see this function as \f(CWgettime()\fR.
502 .PP
503 This keyword should follow the PACKAGE keyword when used.
504 If PACKAGE is not used then PREFIX should follow the MODULE
505 keyword.
506 .PP
507 .Vb 1
508 \& MODULE = RPC PREFIX = rpc_
509 \&
510 \& MODULE = RPC PACKAGE = RPCB PREFIX = rpcb_
511 .Ve
512 .SS "The OUTPUT: Keyword"
513 .IX Subsection "The OUTPUT: Keyword"
514 The OUTPUT: keyword indicates that certain function parameters should be
515 updated (new values made visible to Perl) when the XSUB terminates or that
516 certain values should be returned to the calling Perl function. For
517 simple functions which have no CODE: or PPCODE: section,
518 such as the \fBsin()\fR function above, the RETVAL variable is
519 automatically designated as an output value. For more complex functions
520 the \fBxsubpp\fR compiler will need help to determine which variables are output
521 variables.
522 .PP
523 This keyword will normally be used to complement the CODE: keyword.
524 The RETVAL variable is not recognized as an output variable when the
525 CODE: keyword is present. The OUTPUT: keyword is used in this
526 situation to tell the compiler that RETVAL really is an output
527 variable.
528 .PP
529 The OUTPUT: keyword can also be used to indicate that function parameters
530 are output variables. This may be necessary when a parameter has been
531 modified within the function and the programmer would like the update to
532 be seen by Perl.
533 .PP
534 .Vb 6
535 \& bool_t
536 \& rpcb_gettime(host,timep)
537 \& char *host
538 \& time_t &timep
539 \& OUTPUT:
540 \& timep
541 .Ve
542 .PP
543 The OUTPUT: keyword will also allow an output parameter to
544 be mapped to a matching piece of code rather than to a
545 typemap.
546 .PP
547 .Vb 6
548 \& bool_t
549 \& rpcb_gettime(host,timep)
550 \& char *host
551 \& time_t &timep
552 \& OUTPUT:
553 \& timep sv_setnv(ST(1), (double)timep);
554 .Ve
555 .PP
556 \&\fBxsubpp\fR emits an automatic \f(CWSvSETMAGIC()\fR for all parameters in the
557 OUTPUT section of the XSUB, except RETVAL. This is the usually desired
558 behavior, as it takes care of properly invoking \*(Aqset\*(Aq magic on output
559 parameters (needed for hash or array element parameters that must be
560 created if they didn\*(Aqt exist). If for some reason, this behavior is
561 not desired, the OUTPUT section may contain a \f(CW\*(C`SETMAGIC: DISABLE\*(C'\fR line
562 to disable it for the remainder of the parameters in the OUTPUT section.
563 Likewise, \f(CW\*(C`SETMAGIC: ENABLE\*(C'\fR can be used to reenable it for the
564 remainder of the OUTPUT section. See perlguts for more details
565 about \*(Aqset\*(Aq magic.
566 .SS "The NO_OUTPUT Keyword"
567 .IX Subsection "The NO_OUTPUT Keyword"
568 The NO_OUTPUT can be placed as the first token of the XSUB. This keyword
569 indicates that while the C subroutine we provide an interface to has
570 a non\-\f(CW\*(C`void\*(C'\fR return type, the return value of this C subroutine should not
571 be returned from the generated Perl subroutine.
572 .PP
573 With this keyword present "The RETVAL Variable" is created, and in the
574 generated call to the subroutine this variable is assigned to, but the value
575 of this variable is not going to be used in the auto\-generated code.
576 .PP
577 This keyword makes sense only if \f(CW\*(C`RETVAL\*(C'\fR is going to be accessed by the
578 user\-supplied code. It is especially useful to make a function interface
579 more Perl\-like, especially when the C return value is just an error condition
580 indicator. For example,
581 .PP
582 .Vb 5
583 \& NO_OUTPUT int
584 \& delete_file(char *name)
585 \& POSTCALL:
586 \& if (RETVAL != 0)
587 \& croak("Error %d while deleting file \*(Aq%s\*(Aq", RETVAL, name);
588 .Ve
589 .PP
590 Here the generated XS function returns nothing on success, and will \fBdie()\fR
591 with a meaningful error message on error.
592 .SS "The CODE: Keyword"
593 .IX Subsection "The CODE: Keyword"
594 This keyword is used in more complicated XSUBs which require
595 special handling for the C function. The RETVAL variable is
596 still declared, but it will not be returned unless it is specified
597 in the OUTPUT: section.
598 .PP
599 The following XSUB is for a C function which requires special handling of
600 its parameters. The Perl usage is given first.
601 .PP
602 .Vb 1
603 \& $status = rpcb_gettime( "localhost", $timep );
604 .Ve
605 .PP
606 The XSUB follows.
607 .PP
608 .Vb 9
609 \& bool_t
610 \& rpcb_gettime(host,timep)
611 \& char *host
612 \& time_t timep
613 \& CODE:
614 \& RETVAL = rpcb_gettime( host, &timep );
615 \& OUTPUT:
616 \& timep
617 \& RETVAL
618 .Ve
619 .SS "The INIT: Keyword"
620 .IX Subsection "The INIT: Keyword"
621 The INIT: keyword allows initialization to be inserted into the XSUB before
622 the compiler generates the call to the C function. Unlike the CODE: keyword
623 above, this keyword does not affect the way the compiler handles RETVAL.
624 .PP
625 .Vb 8
626 \& bool_t
627 \& rpcb_gettime(host,timep)
628 \& char *host
629 \& time_t &timep
630 \& INIT:
631 \& printf("# Host is %s\en", host );
632 \& OUTPUT:
633 \& timep
634 .Ve
635 .PP
636 Another use for the INIT: section is to check for preconditions before
637 making a call to the C function:
638 .PP
639 .Vb 9
640 \& long long
641 \& lldiv(a,b)
642 \& long long a
643 \& long long b
644 \& INIT:
645 \& if (a == 0 && b == 0)
646 \& XSRETURN_UNDEF;
647 \& if (b == 0)
648 \& croak("lldiv: cannot divide by 0");
649 .Ve
650 .SS "The NO_INIT Keyword"
651 .IX Subsection "The NO_INIT Keyword"
652 The NO_INIT keyword is used to indicate that a function
653 parameter is being used only as an output value. The \fBxsubpp\fR
654 compiler will normally generate code to read the values of
655 all function parameters from the argument stack and assign
656 them to C variables upon entry to the function. NO_INIT
657 will tell the compiler that some parameters will be used for
658 output rather than for input and that they will be handled
659 before the function terminates.
660 .PP
661 The following example shows a variation of the \fBrpcb_gettime()\fR function.
662 This function uses the timep variable only as an output variable and does
663 not care about its initial contents.
664 .PP
665 .Vb 6
666 \& bool_t
667 \& rpcb_gettime(host,timep)
668 \& char *host
669 \& time_t &timep = NO_INIT
670 \& OUTPUT:
671 \& timep
672 .Ve
673 .SS "The TYPEMAP: Keyword"
674 .IX Subsection "The TYPEMAP: Keyword"
675 Starting with Perl 5.16, you can embed typemaps into your XS code
676 instead of or in addition to typemaps in a separate file. Multiple
677 such embedded typemaps will be processed in order of appearance in
678 the XS code and like local typemap files take precedence over the
679 default typemap, the embedded typemaps may overwrite previous
680 definitions of TYPEMAP, INPUT, and OUTPUT stanzas. The syntax for
681 embedded typemaps is
682 .PP
683 .Vb 3
684 \& TYPEMAP: <<HERE
685 \& ... your typemap code here ...
686 \& HERE
687 .Ve
688 .PP
689 where the \f(CW\*(C`TYPEMAP\*(C'\fR keyword must appear in the first column of a
690 new line.
691 .PP
692 Refer to perlxstypemap for details on writing typemaps.
693 .SS "Initializing Function Parameters"
694 .IX Subsection "Initializing Function Parameters"
695 C function parameters are normally initialized with their values from
696 the argument stack (which in turn contains the parameters that were
697 passed to the XSUB from Perl). The typemaps contain the
698 code segments which are used to translate the Perl values to
699 the C parameters. The programmer, however, is allowed to
700 override the typemaps and supply alternate (or additional)
701 initialization code. Initialization code starts with the first
702 \&\f(CW\*(C`=\*(C'\fR, \f(CW\*(C`;\*(C'\fR or \f(CW\*(C`+\*(C'\fR on a line in the INPUT: section. The only
703 exception happens if this \f(CW\*(C`;\*(C'\fR terminates the line, then this \f(CW\*(C`;\*(C'\fR
704 is quietly ignored.
705 .PP
706 The following code demonstrates how to supply initialization code for
707 function parameters. The initialization code is eval\*(Aqed within double
708 quotes by the compiler before it is added to the output so anything
709 which should be interpreted literally [mainly \f(CW\*(C`$\*(C'\fR, \f(CW\*(C`@\*(C'\fR, or \f(CW\*(C`\e\e\*(C'\fR]
710 must be protected with backslashes. The variables \f(CW$var\fR, \f(CW$arg\fR,
711 and \f(CW$type\fR can be used as in typemaps.
712 .PP
713 .Vb 6
714 \& bool_t
715 \& rpcb_gettime(host,timep)
716 \& char *host = (char *)SvPVbyte_nolen($arg);
717 \& time_t &timep = 0;
718 \& OUTPUT:
719 \& timep
720 .Ve
721 .PP
722 This should not be used to supply default values for parameters. One
723 would normally use this when a function parameter must be processed by
724 another library function before it can be used. Default parameters are
725 covered in the next section.
726 .PP
727 If the initialization begins with \f(CW\*(C`=\*(C'\fR, then it is output in
728 the declaration for the input variable, replacing the initialization
729 supplied by the typemap. If the initialization
730 begins with \f(CW\*(C`;\*(C'\fR or \f(CW\*(C`+\*(C'\fR, then it is performed after
731 all of the input variables have been declared. In the \f(CW\*(C`;\*(C'\fR
732 case the initialization normally supplied by the typemap is not performed.
733 For the \f(CW\*(C`+\*(C'\fR case, the declaration for the variable will include the
734 initialization from the typemap. A global
735 variable, \f(CW%v\fR, is available for the truly rare case where
736 information from one initialization is needed in another
737 initialization.
738 .PP
739 Here\*(Aqs a truly obscure example:
740 .PP
741 .Vb 6
742 \& bool_t
743 \& rpcb_gettime(host,timep)
744 \& time_t &timep; /* \e$v{timep}=@{[$v{timep}=$arg]} */
745 \& char *host + SvOK($v{timep}) ? SvPVbyte_nolen($arg) : NULL;
746 \& OUTPUT:
747 \& timep
748 .Ve
749 .PP
750 The construct \f(CW\*(C`\e$v{timep}=@{[$v{timep}=$arg]}\*(C'\fR used in the above
751 example has a two\-fold purpose: first, when this line is processed by
752 \&\fBxsubpp\fR, the Perl snippet \f(CW\*(C`$v{timep}=$arg\*(C'\fR is evaluated. Second,
753 the text of the evaluated snippet is output into the generated C file
754 (inside a C comment)! During the processing of \f(CW\*(C`char *host\*(C'\fR line,
755 \&\f(CW$arg\fR will evaluate to \f(CWST(0)\fR, and \f(CW$v{timep}\fR will evaluate to
756 \&\f(CWST(1)\fR.
757 .SS "Default Parameter Values"
758 .IX Subsection "Default Parameter Values"
759 Default values for XSUB arguments can be specified by placing an
760 assignment statement in the parameter list. The default value may
761 be a number, a string or the special string \f(CW\*(C`NO_INIT\*(C'\fR. Defaults should
762 always be used on the right\-most parameters only.
763 .PP
764 To allow the XSUB for \fBrpcb_gettime()\fR to have a default host
765 value the parameters to the XSUB could be rearranged. The
766 XSUB will then call the real \fBrpcb_gettime()\fR function with
767 the parameters in the correct order. This XSUB can be called
768 from Perl with either of the following statements:
769 .PP
770 .Vb 1
771 \& $status = rpcb_gettime( $timep, $host );
772 \&
773 \& $status = rpcb_gettime( $timep );
774 .Ve
775 .PP
776 The XSUB will look like the code which follows. A CODE:
777 block is used to call the real \fBrpcb_gettime()\fR function with
778 the parameters in the correct order for that function.
779 .PP
780 .Vb 9
781 \& bool_t
782 \& rpcb_gettime(timep,host="localhost")
783 \& char *host
784 \& time_t timep = NO_INIT
785 \& CODE:
786 \& RETVAL = rpcb_gettime( host, &timep );
787 \& OUTPUT:
788 \& timep
789 \& RETVAL
790 .Ve
791 .SS "The PREINIT: Keyword"
792 .IX Subsection "The PREINIT: Keyword"
793 The PREINIT: keyword allows extra variables to be declared immediately
794 before or after the declarations of the parameters from the INPUT: section
795 are emitted.
796 .PP
797 If a variable is declared inside a CODE: section it will follow any typemap
798 code that is emitted for the input parameters. This may result in the
799 declaration ending up after C code, which is C syntax error. Similar
800 errors may happen with an explicit \f(CW\*(C`;\*(C'\fR\-type or \f(CW\*(C`+\*(C'\fR\-type initialization of
801 parameters is used (see "Initializing Function Parameters"). Declaring
802 these variables in an INIT: section will not help.
803 .PP
804 In such cases, to force an additional variable to be declared together
805 with declarations of other variables, place the declaration into a
806 PREINIT: section. The PREINIT: keyword may be used one or more times
807 within an XSUB.
808 .PP
809 The following examples are equivalent, but if the code is using complex
810 typemaps then the first example is safer.
811 .PP
812 .Vb 10
813 \& bool_t
814 \& rpcb_gettime(timep)
815 \& time_t timep = NO_INIT
816 \& PREINIT:
817 \& char *host = "localhost";
818 \& CODE:
819 \& RETVAL = rpcb_gettime( host, &timep );
820 \& OUTPUT:
821 \& timep
822 \& RETVAL
823 .Ve
824 .PP
825 For this particular case an INIT: keyword would generate the
826 same C code as the PREINIT: keyword. Another correct, but error\-prone example:
827 .PP
828 .Vb 9
829 \& bool_t
830 \& rpcb_gettime(timep)
831 \& time_t timep = NO_INIT
832 \& CODE:
833 \& char *host = "localhost";
834 \& RETVAL = rpcb_gettime( host, &timep );
835 \& OUTPUT:
836 \& timep
837 \& RETVAL
838 .Ve
839 .PP
840 Another way to declare \f(CW\*(C`host\*(C'\fR is to use a C block in the CODE: section:
841 .PP
842 .Vb 11
843 \& bool_t
844 \& rpcb_gettime(timep)
845 \& time_t timep = NO_INIT
846 \& CODE:
847 \& {
848 \& char *host = "localhost";
849 \& RETVAL = rpcb_gettime( host, &timep );
850 \& }
851 \& OUTPUT:
852 \& timep
853 \& RETVAL
854 .Ve
855 .PP
856 The ability to put additional declarations before the typemap entries are
857 processed is very handy in the cases when typemap conversions manipulate
858 some global state:
859 .PP
860 .Vb 8
861 \& MyObject
862 \& mutate(o)
863 \& PREINIT:
864 \& MyState st = global_state;
865 \& INPUT:
866 \& MyObject o;
867 \& CLEANUP:
868 \& reset_to(global_state, st);
869 .Ve
870 .PP
871 Here we suppose that conversion to \f(CW\*(C`MyObject\*(C'\fR in the INPUT: section and from
872 MyObject when processing RETVAL will modify a global variable \f(CW\*(C`global_state\*(C'\fR.
873 After these conversions are performed, we restore the old value of
874 \&\f(CW\*(C`global_state\*(C'\fR (to avoid memory leaks, for example).
875 .PP
876 There is another way to trade clarity for compactness: INPUT sections allow
877 declaration of C variables which do not appear in the parameter list of
878 a subroutine. Thus the above code for \fBmutate()\fR can be rewritten as
879 .PP
880 .Vb 6
881 \& MyObject
882 \& mutate(o)
883 \& MyState st = global_state;
884 \& MyObject o;
885 \& CLEANUP:
886 \& reset_to(global_state, st);
887 .Ve
888 .PP
889 and the code for \fBrpcb_gettime()\fR can be rewritten as
890 .PP
891 .Vb 9
892 \& bool_t
893 \& rpcb_gettime(timep)
894 \& time_t timep = NO_INIT
895 \& char *host = "localhost";
896 \& C_ARGS:
897 \& host, &timep
898 \& OUTPUT:
899 \& timep
900 \& RETVAL
901 .Ve
902 .SS "The SCOPE: Keyword"
903 .IX Subsection "The SCOPE: Keyword"
904 The SCOPE: keyword allows scoping to be enabled for a particular XSUB. If
905 enabled, the XSUB will invoke ENTER and LEAVE automatically.
906 .PP
907 To support potentially complex type mappings, if a typemap entry used
908 by an XSUB contains a comment like \f(CW\*(C`/*scope*/\*(C'\fR then scoping will
909 be automatically enabled for that XSUB.
910 .PP
911 To enable scoping:
912 .PP
913 .Vb 1
914 \& SCOPE: ENABLE
915 .Ve
916 .PP
917 To disable scoping:
918 .PP
919 .Vb 1
920 \& SCOPE: DISABLE
921 .Ve
922 .SS "The INPUT: Keyword"
923 .IX Subsection "The INPUT: Keyword"
924 The XSUB\*(Aqs parameters are usually evaluated immediately after entering the
925 XSUB. The INPUT: keyword can be used to force those parameters to be
926 evaluated a little later. The INPUT: keyword can be used multiple times
927 within an XSUB and can be used to list one or more input variables. This
928 keyword is used with the PREINIT: keyword.
929 .PP
930 The following example shows how the input parameter \f(CW\*(C`timep\*(C'\fR can be
931 evaluated late, after a PREINIT.
932 .PP
933 .Vb 10
934 \& bool_t
935 \& rpcb_gettime(host,timep)
936 \& char *host
937 \& PREINIT:
938 \& time_t tt;
939 \& INPUT:
940 \& time_t timep
941 \& CODE:
942 \& RETVAL = rpcb_gettime( host, &tt );
943 \& timep = tt;
944 \& OUTPUT:
945 \& timep
946 \& RETVAL
947 .Ve
948 .PP
949 The next example shows each input parameter evaluated late.
950 .PP
951 .Vb 10
952 \& bool_t
953 \& rpcb_gettime(host,timep)
954 \& PREINIT:
955 \& time_t tt;
956 \& INPUT:
957 \& char *host
958 \& PREINIT:
959 \& char *h;
960 \& INPUT:
961 \& time_t timep
962 \& CODE:
963 \& h = host;
964 \& RETVAL = rpcb_gettime( h, &tt );
965 \& timep = tt;
966 \& OUTPUT:
967 \& timep
968 \& RETVAL
969 .Ve
970 .PP
971 Since INPUT sections allow declaration of C variables which do not appear
972 in the parameter list of a subroutine, this may be shortened to:
973 .PP
974 .Vb 12
975 \& bool_t
976 \& rpcb_gettime(host,timep)
977 \& time_t tt;
978 \& char *host;
979 \& char *h = host;
980 \& time_t timep;
981 \& CODE:
982 \& RETVAL = rpcb_gettime( h, &tt );
983 \& timep = tt;
984 \& OUTPUT:
985 \& timep
986 \& RETVAL
987 .Ve
988 .PP
989 (We used our knowledge that input conversion for \f(CW\*(C`char *\*(C'\fR is a "simple" one,
990 thus \f(CW\*(C`host\*(C'\fR is initialized on the declaration line, and our assignment
991 \&\f(CW\*(C`h = host\*(C'\fR is not performed too early. Otherwise one would need to have the
992 assignment \f(CW\*(C`h = host\*(C'\fR in a CODE: or INIT: section.)
993 .SS "The IN/OUTLIST/IN_OUTLIST/OUT/IN_OUT Keywords"
994 .IX Subsection "The IN/OUTLIST/IN_OUTLIST/OUT/IN_OUT Keywords"
995 In the list of parameters for an XSUB, one can precede parameter names
996 by the \f(CW\*(C`IN\*(C'\fR/\f(CW\*(C`OUTLIST\*(C'\fR/\f(CW\*(C`IN_OUTLIST\*(C'\fR/\f(CW\*(C`OUT\*(C'\fR/\f(CW\*(C`IN_OUT\*(C'\fR keywords.
997 \&\f(CW\*(C`IN\*(C'\fR keyword is the default, the other keywords indicate how the Perl
998 interface should differ from the C interface.
999 .PP
1000 Parameters preceded by \f(CW\*(C`OUTLIST\*(C'\fR/\f(CW\*(C`IN_OUTLIST\*(C'\fR/\f(CW\*(C`OUT\*(C'\fR/\f(CW\*(C`IN_OUT\*(C'\fR
1001 keywords are considered to be used by the C subroutine \fIvia
1002 pointers\fR. \f(CW\*(C`OUTLIST\*(C'\fR/\f(CW\*(C`OUT\*(C'\fR keywords indicate that the C subroutine
1003 does not inspect the memory pointed by this parameter, but will write
1004 through this pointer to provide additional return values.
1005 .PP
1006 Parameters preceded by \f(CW\*(C`OUTLIST\*(C'\fR keyword do not appear in the usage
1007 signature of the generated Perl function.
1008 .PP
1009 Parameters preceded by \f(CW\*(C`IN_OUTLIST\*(C'\fR/\f(CW\*(C`IN_OUT\*(C'\fR/\f(CW\*(C`OUT\*(C'\fR \fIdo\fR appear as
1010 parameters to the Perl function. With the exception of
1011 \&\f(CW\*(C`OUT\*(C'\fR\-parameters, these parameters are converted to the corresponding
1012 C type, then pointers to these data are given as arguments to the C
1013 function. It is expected that the C function will write through these
1014 pointers.
1015 .PP
1016 The return list of the generated Perl function consists of the C return value
1017 from the function (unless the XSUB is of \f(CW\*(C`void\*(C'\fR return type or
1018 \&\f(CW\*(C`The NO_OUTPUT Keyword\*(C'\fR was used) followed by all the \f(CW\*(C`OUTLIST\*(C'\fR
1019 and \f(CW\*(C`IN_OUTLIST\*(C'\fR parameters (in the order of appearance). On the
1020 return from the XSUB the \f(CW\*(C`IN_OUT\*(C'\fR/\f(CW\*(C`OUT\*(C'\fR Perl parameter will be
1021 modified to have the values written by the C function.
1022 .PP
1023 For example, an XSUB
1024 .PP
1025 .Vb 5
1026 \& void
1027 \& day_month(OUTLIST day, IN unix_time, OUTLIST month)
1028 \& int day
1029 \& int unix_time
1030 \& int month
1031 .Ve
1032 .PP
1033 should be used from Perl as
1034 .PP
1035 .Vb 1
1036 \& my ($day, $month) = day_month(time);
1037 .Ve
1038 .PP
1039 The C signature of the corresponding function should be
1040 .PP
1041 .Vb 1
1042 \& void day_month(int *day, int unix_time, int *month);
1043 .Ve
1044 .PP
1045 The \f(CW\*(C`IN\*(C'\fR/\f(CW\*(C`OUTLIST\*(C'\fR/\f(CW\*(C`IN_OUTLIST\*(C'\fR/\f(CW\*(C`IN_OUT\*(C'\fR/\f(CW\*(C`OUT\*(C'\fR keywords can be
1046 mixed with ANSI\-style declarations, as in
1047 .PP
1048 .Vb 2
1049 \& void
1050 \& day_month(OUTLIST int day, int unix_time, OUTLIST int month)
1051 .Ve
1052 .PP
1053 (here the optional \f(CW\*(C`IN\*(C'\fR keyword is omitted).
1054 .PP
1055 The \f(CW\*(C`IN_OUT\*(C'\fR parameters are identical with parameters introduced with
1056 "The & Unary Operator" and put into the \f(CW\*(C`OUTPUT:\*(C'\fR section (see
1057 "The OUTPUT: Keyword"). The \f(CW\*(C`IN_OUTLIST\*(C'\fR parameters are very similar,
1058 the only difference being that the value C function writes through the
1059 pointer would not modify the Perl parameter, but is put in the output
1060 list.
1061 .PP
1062 The \f(CW\*(C`OUTLIST\*(C'\fR/\f(CW\*(C`OUT\*(C'\fR parameter differ from \f(CW\*(C`IN_OUTLIST\*(C'\fR/\f(CW\*(C`IN_OUT\*(C'\fR
1063 parameters only by the initial value of the Perl parameter not
1064 being read (and not being given to the C function \- which gets some
1065 garbage instead). For example, the same C function as above can be
1066 interfaced with as
1067 .PP
1068 .Vb 1
1069 \& void day_month(OUT int day, int unix_time, OUT int month);
1070 .Ve
1071 .PP
1072 or
1073 .PP
1074 .Vb 8
1075 \& void
1076 \& day_month(day, unix_time, month)
1077 \& int &day = NO_INIT
1078 \& int unix_time
1079 \& int &month = NO_INIT
1080 \& OUTPUT:
1081 \& day
1082 \& month
1083 .Ve
1084 .PP
1085 However, the generated Perl function is called in very C\-ish style:
1086 .PP
1087 .Vb 2
1088 \& my ($day, $month);
1089 \& day_month($day, time, $month);
1090 .Ve
1091 .ie n .SS "The length(NAME) Keyword"
1092 .el .SS "The \f(CWlength(NAME)\fP Keyword"
1093 .IX Subsection "The length(NAME) Keyword"
1094 If one of the input arguments to the C function is the length of a string
1095 argument \f(CW\*(C`NAME\*(C'\fR, one can substitute the name of the length\-argument by
1096 \&\f(CWlength(NAME)\fR in the XSUB declaration. This argument must be omitted when
1097 the generated Perl function is called. E.g.,
1098 .PP
1099 .Vb 9
1100 \& void
1101 \& dump_chars(char *s, short l)
1102 \& {
1103 \& short n = 0;
1104 \& while (n < l) {
1105 \& printf("s[%d] = \e"\e\e%#03o\e"\en", n, (int)s[n]);
1106 \& n++;
1107 \& }
1108 \& }
1109 \&
1110 \& MODULE = x PACKAGE = x
1111 \&
1112 \& void dump_chars(char *s, short length(s))
1113 .Ve
1114 .PP
1115 should be called as \f(CWdump_chars($string)\fR.
1116 .PP
1117 This directive is supported with ANSI\-type function declarations only.
1118 .SS "Variable\-length Parameter Lists"
1119 .IX Subsection "Variable-length Parameter Lists"
1120 XSUBs can have variable\-length parameter lists by specifying an ellipsis
1121 \&\f(CW\*(C`(...)\*(C'\fR in the parameter list. This use of the ellipsis is similar to that
1122 found in ANSI C. The programmer is able to determine the number of
1123 arguments passed to the XSUB by examining the \f(CW\*(C`items\*(C'\fR variable which the
1124 \&\fBxsubpp\fR compiler supplies for all XSUBs. By using this mechanism one can
1125 create an XSUB which accepts a list of parameters of unknown length.
1126 .PP
1127 The \fIhost\fR parameter for the \fBrpcb_gettime()\fR XSUB can be
1128 optional so the ellipsis can be used to indicate that the
1129 XSUB will take a variable number of parameters. Perl should
1130 be able to call this XSUB with either of the following statements.
1131 .PP
1132 .Vb 1
1133 \& $status = rpcb_gettime( $timep, $host );
1134 \&
1135 \& $status = rpcb_gettime( $timep );
1136 .Ve
1137 .PP
1138 The XS code, with ellipsis, follows.
1139 .PP
1140 .Vb 12
1141 \& bool_t
1142 \& rpcb_gettime(timep, ...)
1143 \& time_t timep = NO_INIT
1144 \& PREINIT:
1145 \& char *host = "localhost";
1146 \& CODE:
1147 \& if( items > 1 )
1148 \& host = (char *)SvPVbyte_nolen(ST(1));
1149 \& RETVAL = rpcb_gettime( host, &timep );
1150 \& OUTPUT:
1151 \& timep
1152 \& RETVAL
1153 .Ve
1154 .SS "The C_ARGS: Keyword"
1155 .IX Subsection "The C_ARGS: Keyword"
1156 The C_ARGS: keyword allows creating of XSUBS which have different
1157 calling sequence from Perl than from C, without a need to write
1158 CODE: or PPCODE: section. The contents of the C_ARGS: paragraph is
1159 put as the argument to the called C function without any change.
1160 .PP
1161 For example, suppose that a C function is declared as
1162 .PP
1163 .Vb 1
1164 \& symbolic nth_derivative(int n, symbolic function, int flags);
1165 .Ve
1166 .PP
1167 and that the default flags are kept in a global C variable
1168 \&\f(CW\*(C`default_flags\*(C'\fR. Suppose that you want to create an interface which
1169 is called as
1170 .PP
1171 .Vb 1
1172 \& $second_deriv = $function\->nth_derivative(2);
1173 .Ve
1174 .PP
1175 To do this, declare the XSUB as
1176 .PP
1177 .Vb 6
1178 \& symbolic
1179 \& nth_derivative(function, n)
1180 \& symbolic function
1181 \& int n
1182 \& C_ARGS:
1183 \& n, function, default_flags
1184 .Ve
1185 .SS "The PPCODE: Keyword"
1186 .IX Subsection "The PPCODE: Keyword"
1187 The PPCODE: keyword is an alternate form of the CODE: keyword and is used
1188 to tell the \fBxsubpp\fR compiler that the programmer is supplying the code to
1189 control the argument stack for the XSUBs return values. Occasionally one
1190 will want an XSUB to return a list of values rather than a single value.
1191 In these cases one must use PPCODE: and then explicitly push the list of
1192 values on the stack. The PPCODE: and CODE: keywords should not be used
1193 together within the same XSUB.
1194 .PP
1195 The actual difference between PPCODE: and CODE: sections is in the
1196 initialization of \f(CW\*(C`SP\*(C'\fR macro (which stands for the \fIcurrent\fR Perl
1197 stack pointer), and in the handling of data on the stack when returning
1198 from an XSUB. In CODE: sections SP preserves the value which was on
1199 entry to the XSUB: SP is on the function pointer (which follows the
1200 last parameter). In PPCODE: sections SP is moved backward to the
1201 beginning of the parameter list, which allows \f(CW\*(C`PUSH*()\*(C'\fR macros
1202 to place output values in the place Perl expects them to be when
1203 the XSUB returns back to Perl.
1204 .PP
1205 The generated trailer for a CODE: section ensures that the number of return
1206 values Perl will see is either 0 or 1 (depending on the \f(CW\*(C`void\*(C'\fRness of the
1207 return value of the C function, and heuristics mentioned in
1208 "The RETVAL Variable"). The trailer generated for a PPCODE: section
1209 is based on the number of return values and on the number of times
1210 \&\f(CW\*(C`SP\*(C'\fR was updated by \f(CW\*(C`[X]PUSH*()\*(C'\fR macros.
1211 .PP
1212 Note that macros \f(CWST(i)\fR, \f(CW\*(C`XST_m*()\*(C'\fR and \f(CW\*(C`XSRETURN*()\*(C'\fR work equally
1213 well in CODE: sections and PPCODE: sections.
1214 .PP
1215 The following XSUB will call the C \fBrpcb_gettime()\fR function
1216 and will return its two output values, timep and status, to
1217 Perl as a single list.
1218 .PP
1219 .Vb 11
1220 \& void
1221 \& rpcb_gettime(host)
1222 \& char *host
1223 \& PREINIT:
1224 \& time_t timep;
1225 \& bool_t status;
1226 \& PPCODE:
1227 \& status = rpcb_gettime( host, &timep );
1228 \& EXTEND(SP, 2);
1229 \& PUSHs(sv_2mortal(newSViv(status)));
1230 \& PUSHs(sv_2mortal(newSViv(timep)));
1231 .Ve
1232 .PP
1233 Notice that the programmer must supply the C code necessary
1234 to have the real \fBrpcb_gettime()\fR function called and to have
1235 the return values properly placed on the argument stack.
1236 .PP
1237 The \f(CW\*(C`void\*(C'\fR return type for this function tells the \fBxsubpp\fR compiler that
1238 the RETVAL variable is not needed or used and that it should not be created.
1239 In most scenarios the void return type should be used with the PPCODE:
1240 directive.
1241 .PP
1242 The \fBEXTEND()\fR macro is used to make room on the argument
1243 stack for 2 return values. The PPCODE: directive causes the
1244 \&\fBxsubpp\fR compiler to create a stack pointer available as \f(CW\*(C`SP\*(C'\fR, and it
1245 is this pointer which is being used in the \fBEXTEND()\fR macro.
1246 The values are then pushed onto the stack with the \fBPUSHs()\fR
1247 macro.
1248 .PP
1249 Now the \fBrpcb_gettime()\fR function can be used from Perl with
1250 the following statement.
1251 .PP
1252 .Vb 1
1253 \& ($status, $timep) = rpcb_gettime("localhost");
1254 .Ve
1255 .PP
1256 When handling output parameters with a PPCODE section, be sure to handle
1257 \&\*(Aqset\*(Aq magic properly. See perlguts for details about \*(Aqset\*(Aq magic.
1258 .SS "Returning Undef And Empty Lists"
1259 .IX Subsection "Returning Undef And Empty Lists"
1260 Occasionally the programmer will want to return simply
1261 \&\f(CW\*(C`undef\*(C'\fR or an empty list if a function fails rather than a
1262 separate status value. The \fBrpcb_gettime()\fR function offers
1263 just this situation. If the function succeeds we would like
1264 to have it return the time and if it fails we would like to
1265 have undef returned. In the following Perl code the value
1266 of \f(CW$timep\fR will either be undef or it will be a valid time.
1267 .PP
1268 .Vb 1
1269 \& $timep = rpcb_gettime( "localhost" );
1270 .Ve
1271 .PP
1272 The following XSUB uses the \f(CW\*(C`SV *\*(C'\fR return type as a mnemonic only,
1273 and uses a CODE: block to indicate to the compiler
1274 that the programmer has supplied all the necessary code. The
1275 \&\fBsv_newmortal()\fR call will initialize the return value to undef, making that
1276 the default return value.
1277 .PP
1278 .Vb 10
1279 \& SV *
1280 \& rpcb_gettime(host)
1281 \& char * host
1282 \& PREINIT:
1283 \& time_t timep;
1284 \& bool_t x;
1285 \& CODE:
1286 \& ST(0) = sv_newmortal();
1287 \& if( rpcb_gettime( host, &timep ) )
1288 \& sv_setnv( ST(0), (double)timep);
1289 .Ve
1290 .PP
1291 The next example demonstrates how one would place an explicit undef in the
1292 return value, should the need arise.
1293 .PP
1294 .Vb 10
1295 \& SV *
1296 \& rpcb_gettime(host)
1297 \& char * host
1298 \& PREINIT:
1299 \& time_t timep;
1300 \& bool_t x;
1301 \& CODE:
1302 \& if( rpcb_gettime( host, &timep ) ){
1303 \& ST(0) = sv_newmortal();
1304 \& sv_setnv( ST(0), (double)timep);
1305 \& }
1306 \& else{
1307 \& ST(0) = &PL_sv_undef;
1308 \& }
1309 .Ve
1310 .PP
1311 To return an empty list one must use a PPCODE: block and
1312 then not push return values on the stack.
1313 .PP
1314 .Vb 12
1315 \& void
1316 \& rpcb_gettime(host)
1317 \& char *host
1318 \& PREINIT:
1319 \& time_t timep;
1320 \& PPCODE:
1321 \& if( rpcb_gettime( host, &timep ) )
1322 \& PUSHs(sv_2mortal(newSViv(timep)));
1323 \& else{
1324 \& /* Nothing pushed on stack, so an empty
1325 \& * list is implicitly returned. */
1326 \& }
1327 .Ve
1328 .PP
1329 Some people may be inclined to include an explicit \f(CW\*(C`return\*(C'\fR in the above
1330 XSUB, rather than letting control fall through to the end. In those
1331 situations \f(CW\*(C`XSRETURN_EMPTY\*(C'\fR should be used, instead. This will ensure that
1332 the XSUB stack is properly adjusted. Consult perlapi for other
1333 \&\f(CW\*(C`XSRETURN\*(C'\fR macros.
1334 .PP
1335 Since \f(CW\*(C`XSRETURN_*\*(C'\fR macros can be used with CODE blocks as well, one can
1336 rewrite this example as:
1337 .PP
1338 .Vb 11
1339 \& int
1340 \& rpcb_gettime(host)
1341 \& char *host
1342 \& PREINIT:
1343 \& time_t timep;
1344 \& CODE:
1345 \& RETVAL = rpcb_gettime( host, &timep );
1346 \& if (RETVAL == 0)
1347 \& XSRETURN_UNDEF;
1348 \& OUTPUT:
1349 \& RETVAL
1350 .Ve
1351 .PP
1352 In fact, one can put this check into a POSTCALL: section as well. Together
1353 with PREINIT: simplifications, this leads to:
1354 .PP
1355 .Vb 7
1356 \& int
1357 \& rpcb_gettime(host)
1358 \& char *host
1359 \& time_t timep;
1360 \& POSTCALL:
1361 \& if (RETVAL == 0)
1362 \& XSRETURN_UNDEF;
1363 .Ve
1364 .SS "The REQUIRE: Keyword"
1365 .IX Subsection "The REQUIRE: Keyword"
1366 The REQUIRE: keyword is used to indicate the minimum version of the
1367 \&\fBxsubpp\fR compiler needed to compile the XS module. An XS module which
1368 contains the following statement will compile with only \fBxsubpp\fR version
1369 1.922 or greater:
1370 .PP
1371 .Vb 1
1372 \& REQUIRE: 1.922
1373 .Ve
1374 .SS "The CLEANUP: Keyword"
1375 .IX Subsection "The CLEANUP: Keyword"
1376 This keyword can be used when an XSUB requires special cleanup procedures
1377 before it terminates. When the CLEANUP: keyword is used it must follow
1378 any CODE:, or OUTPUT: blocks which are present in the XSUB. The code
1379 specified for the cleanup block will be added as the last statements in
1380 the XSUB.
1381 .SS "The POSTCALL: Keyword"
1382 .IX Subsection "The POSTCALL: Keyword"
1383 This keyword can be used when an XSUB requires special procedures
1384 executed after the C subroutine call is performed. When the POSTCALL:
1385 keyword is used it must precede OUTPUT: and CLEANUP: blocks which are
1386 present in the XSUB.
1387 .PP
1388 See examples in "The NO_OUTPUT Keyword" and "Returning Undef And Empty Lists".
1389 .PP
1390 The POSTCALL: block does not make a lot of sense when the C subroutine
1391 call is supplied by user by providing either CODE: or PPCODE: section.
1392 .SS "The BOOT: Keyword"
1393 .IX Subsection "The BOOT: Keyword"
1394 The BOOT: keyword is used to add code to the extension\*(Aqs bootstrap
1395 function. The bootstrap function is generated by the \fBxsubpp\fR compiler and
1396 normally holds the statements necessary to register any XSUBs with Perl.
1397 With the BOOT: keyword the programmer can tell the compiler to add extra
1398 statements to the bootstrap function.
1399 .PP
1400 This keyword may be used any time after the first MODULE keyword and should
1401 appear on a line by itself. The first blank line after the keyword will
1402 terminate the code block.
1403 .PP
1404 .Vb 4
1405 \& BOOT:
1406 \& # The following message will be printed when the
1407 \& # bootstrap function executes.
1408 \& printf("Hello from the bootstrap!\en");
1409 .Ve
1410 .SS "The VERSIONCHECK: Keyword"
1411 .IX Subsection "The VERSIONCHECK: Keyword"
1412 The VERSIONCHECK: keyword corresponds to \fBxsubpp\fR\*(Aqs \f(CW\*(C`\-versioncheck\*(C'\fR and
1413 \&\f(CW\*(C`\-noversioncheck\*(C'\fR options. This keyword overrides the command line
1414 options. Version checking is enabled by default. When version checking is
1415 enabled the XS module will attempt to verify that its version matches the
1416 version of the PM module.
1417 .PP
1418 To enable version checking:
1419 .PP
1420 .Vb 1
1421 \& VERSIONCHECK: ENABLE
1422 .Ve
1423 .PP
1424 To disable version checking:
1425 .PP
1426 .Vb 1
1427 \& VERSIONCHECK: DISABLE
1428 .Ve
1429 .PP
1430 Note that if the version of the PM module is an NV (a floating point
1431 number), it will be stringified with a possible loss of precision
1432 (currently chopping to nine decimal places) so that it may not match
1433 the version of the XS module anymore. Quoting the \f(CW$VERSION\fR declaration
1434 to make it a string is recommended if long version numbers are used.
1435 .SS "The PROTOTYPES: Keyword"
1436 .IX Subsection "The PROTOTYPES: Keyword"
1437 The PROTOTYPES: keyword corresponds to \fBxsubpp\fR\*(Aqs \f(CW\*(C`\-prototypes\*(C'\fR and
1438 \&\f(CW\*(C`\-noprototypes\*(C'\fR options. This keyword overrides the command line options.
1439 Prototypes are disabled by default. When prototypes are enabled, XSUBs will
1440 be given Perl prototypes. This keyword may be used multiple times in an XS
1441 module to enable and disable prototypes for different parts of the module.
1442 Note that \fBxsubpp\fR will nag you if you don\*(Aqt explicitly enable or disable
1443 prototypes, with:
1444 .PP
1445 .Vb 1
1446 \& Please specify prototyping behavior for Foo.xs (see perlxs manual)
1447 .Ve
1448 .PP
1449 To enable prototypes:
1450 .PP
1451 .Vb 1
1452 \& PROTOTYPES: ENABLE
1453 .Ve
1454 .PP
1455 To disable prototypes:
1456 .PP
1457 .Vb 1
1458 \& PROTOTYPES: DISABLE
1459 .Ve
1460 .SS "The PROTOTYPE: Keyword"
1461 .IX Subsection "The PROTOTYPE: Keyword"
1462 This keyword is similar to the PROTOTYPES: keyword above but can be used to
1463 force \fBxsubpp\fR to use a specific prototype for the XSUB. This keyword
1464 overrides all other prototype options and keywords but affects only the
1465 current XSUB. Consult "Prototypes" in perlsub for information about Perl
1466 prototypes.
1467 .PP
1468 .Vb 10
1469 \& bool_t
1470 \& rpcb_gettime(timep, ...)
1471 \& time_t timep = NO_INIT
1472 \& PROTOTYPE: $;$
1473 \& PREINIT:
1474 \& char *host = "localhost";
1475 \& CODE:
1476 \& if( items > 1 )
1477 \& host = (char *)SvPVbyte_nolen(ST(1));
1478 \& RETVAL = rpcb_gettime( host, &timep );
1479 \& OUTPUT:
1480 \& timep
1481 \& RETVAL
1482 .Ve
1483 .PP
1484 If the prototypes are enabled, you can disable it locally for a given
1485 XSUB as in the following example:
1486 .PP
1487 .Vb 4
1488 \& void
1489 \& rpcb_gettime_noproto()
1490 \& PROTOTYPE: DISABLE
1491 \& ...
1492 .Ve
1493 .SS "The ALIAS: Keyword"
1494 .IX Subsection "The ALIAS: Keyword"
1495 The ALIAS: keyword allows an XSUB to have two or more unique Perl names
1496 and to know which of those names was used when it was invoked. The Perl
1497 names may be fully\-qualified with package names. Each alias is given an
1498 index. The compiler will setup a variable called \f(CW\*(C`ix\*(C'\fR which contain the
1499 index of the alias which was used. When the XSUB is called with its
1500 declared name \f(CW\*(C`ix\*(C'\fR will be 0.
1501 .PP
1502 The following example will create aliases \f(CWFOO::gettime()\fR and
1503 \&\f(CWBAR::getit()\fR for this function.
1504 .PP
1505 .Vb 11
1506 \& bool_t
1507 \& rpcb_gettime(host,timep)
1508 \& char *host
1509 \& time_t &timep
1510 \& ALIAS:
1511 \& FOO::gettime = 1
1512 \& BAR::getit = 2
1513 \& INIT:
1514 \& printf("# ix = %d\en", ix );
1515 \& OUTPUT:
1516 \& timep
1517 .Ve
1518 .PP
1519 A warning will be produced when you create more than one alias to the same
1520 value. This may be worked around in a backwards compatible way by creating
1521 multiple defines which resolve to the same value, or with a modern version
1522 of ExtUtils::ParseXS you can use a symbolic alias, which are denoted with
1523 a \f(CW\*(C`=>\*(C'\fR instead of a \f(CW\*(C`=\*(C'\fR. For instance you could change the above
1524 so that the alias section looked like this:
1525 .PP
1526 .Vb 4
1527 \& ALIAS:
1528 \& FOO::gettime = 1
1529 \& BAR::getit = 2
1530 \& BAZ::gettime => FOO::gettime
1531 .Ve
1532 .PP
1533 this would have the same effect as this:
1534 .PP
1535 .Vb 4
1536 \& ALIAS:
1537 \& FOO::gettime = 1
1538 \& BAR::getit = 2
1539 \& BAZ::gettime = 1
1540 .Ve
1541 .PP
1542 except that the latter will produce warnings during the build process. A
1543 mechanism that would work in a backwards compatible way with older
1544 versions of our tool chain would be to do this:
1545 .PP
1546 .Vb 3
1547 \& #define FOO_GETTIME 1
1548 \& #define BAR_GETIT 2
1549 \& #define BAZ_GETTIME 1
1550 \&
1551 \& bool_t
1552 \& rpcb_gettime(host,timep)
1553 \& char *host
1554 \& time_t &timep
1555 \& ALIAS:
1556 \& FOO::gettime = FOO_GETTIME
1557 \& BAR::getit = BAR_GETIT
1558 \& BAZ::gettime = BAZ_GETTIME
1559 \& INIT:
1560 \& printf("# ix = %d\en", ix );
1561 \& OUTPUT:
1562 \& timep
1563 .Ve
1564 .SS "The OVERLOAD: Keyword"
1565 .IX Subsection "The OVERLOAD: Keyword"
1566 Instead of writing an overloaded interface using pure Perl, you
1567 can also use the OVERLOAD keyword to define additional Perl names
1568 for your functions (like the ALIAS: keyword above). However, the
1569 overloaded functions must be defined in such a way as to accept the number
1570 of parameters supplied by perl\*(Aqs overload system. For most overload
1571 methods, it will be three parameters; for the \f(CW\*(C`nomethod\*(C'\fR function it will
1572 be four. However, the bitwise operators \f(CW\*(C`&\*(C'\fR, \f(CW\*(C`|\*(C'\fR, \f(CW\*(C`^\*(C'\fR, and \f(CW\*(C`~\*(C'\fR may be
1573 called with three \fIor\fR five arguments (see overload).
1574 .PP
1575 If any
1576 function has the OVERLOAD: keyword, several additional lines
1577 will be defined in the c file generated by xsubpp in order to
1578 register with the overload magic.
1579 .PP
1580 Since blessed objects are actually stored as RV\*(Aqs, it is useful
1581 to use the typemap features to preprocess parameters and extract
1582 the actual SV stored within the blessed RV. See the sample for
1583 T_PTROBJ_SPECIAL in perlxstypemap.
1584 .PP
1585 To use the OVERLOAD: keyword, create an XS function which takes
1586 three input parameters (or use the C\-style \*(Aq...\*(Aq definition) like
1587 this:
1588 .PP
1589 .Vb 7
1590 \& SV *
1591 \& cmp (lobj, robj, swap)
1592 \& My_Module_obj lobj
1593 \& My_Module_obj robj
1594 \& IV swap
1595 \& OVERLOAD: cmp <=>
1596 \& { /* function defined here */}
1597 .Ve
1598 .PP
1599 In this case, the function will overload both of the three way
1600 comparison operators. For all overload operations using non\-alpha
1601 characters, you must type the parameter without quoting, separating
1602 multiple overloads with whitespace. Note that "" (the stringify
1603 overload) should be entered as \e"\e" (i.e. escaped).
1604 .PP
1605 Since, as mentioned above, bitwise operators may take extra arguments, you
1606 may want to use something like \f(CW\*(C`(lobj, robj, swap, ...)\*(C'\fR (with
1607 literal \f(CW\*(C`...\*(C'\fR) as your parameter list.
1608 .SS "The FALLBACK: Keyword"
1609 .IX Subsection "The FALLBACK: Keyword"
1610 In addition to the OVERLOAD keyword, if you need to control how
1611 Perl autogenerates missing overloaded operators, you can set the
1612 FALLBACK keyword in the module header section, like this:
1613 .PP
1614 .Vb 1
1615 \& MODULE = RPC PACKAGE = RPC
1616 \&
1617 \& FALLBACK: TRUE
1618 \& ...
1619 .Ve
1620 .PP
1621 where FALLBACK can take any of the three values TRUE, FALSE, or
1622 UNDEF. If you do not set any FALLBACK value when using OVERLOAD,
1623 it defaults to UNDEF. FALLBACK is not used except when one or
1624 more functions using OVERLOAD have been defined. Please see
1625 "fallback" in overload for more details.
1626 .SS "The INTERFACE: Keyword"
1627 .IX Subsection "The INTERFACE: Keyword"
1628 This keyword declares the current XSUB as a keeper of the given
1629 calling signature. If some text follows this keyword, it is
1630 considered as a list of functions which have this signature, and
1631 should be attached to the current XSUB.
1632 .PP
1633 For example, if you have 4 C functions \fBmultiply()\fR, \fBdivide()\fR, \fBadd()\fR,
1634 \&\fBsubtract()\fR all having the signature:
1635 .PP
1636 .Vb 1
1637 \& symbolic f(symbolic, symbolic);
1638 .Ve
1639 .PP
1640 you can make them all to use the same XSUB using this:
1641 .PP
1642 .Vb 7
1643 \& symbolic
1644 \& interface_s_ss(arg1, arg2)
1645 \& symbolic arg1
1646 \& symbolic arg2
1647 \& INTERFACE:
1648 \& multiply divide
1649 \& add subtract
1650 .Ve
1651 .PP
1652 (This is the complete XSUB code for 4 Perl functions!) Four generated
1653 Perl function share names with corresponding C functions.
1654 .PP
1655 The advantage of this approach comparing to ALIAS: keyword is that there
1656 is no need to code a switch statement, each Perl function (which shares
1657 the same XSUB) knows which C function it should call. Additionally, one
1658 can attach an extra function \fBremainder()\fR at runtime by using
1659 .PP
1660 .Vb 3
1661 \& CV *mycv = newXSproto("Symbolic::remainder",
1662 \& XS_Symbolic_interface_s_ss, _\|_FILE_\|_, "$$");
1663 \& XSINTERFACE_FUNC_SET(mycv, remainder);
1664 .Ve
1665 .PP
1666 say, from another XSUB. (This example supposes that there was no
1667 INTERFACE_MACRO: section, otherwise one needs to use something else instead of
1668 \&\f(CW\*(C`XSINTERFACE_FUNC_SET\*(C'\fR, see the next section.)
1669 .SS "The INTERFACE_MACRO: Keyword"
1670 .IX Subsection "The INTERFACE_MACRO: Keyword"
1671 This keyword allows one to define an INTERFACE using a different way
1672 to extract a function pointer from an XSUB. The text which follows
1673 this keyword should give the name of macros which would extract/set a
1674 function pointer. The extractor macro is given return type, \f(CW\*(C`CV*\*(C'\fR,
1675 and \f(CW\*(C`XSANY.any_dptr\*(C'\fR for this \f(CW\*(C`CV*\*(C'\fR. The setter macro is given cv,
1676 and the function pointer.
1677 .PP
1678 The default value is \f(CW\*(C`XSINTERFACE_FUNC\*(C'\fR and \f(CW\*(C`XSINTERFACE_FUNC_SET\*(C'\fR.
1679 An INTERFACE keyword with an empty list of functions can be omitted if
1680 INTERFACE_MACRO keyword is used.
1681 .PP
1682 Suppose that in the previous example functions pointers for
1683 \&\fBmultiply()\fR, \fBdivide()\fR, \fBadd()\fR, \fBsubtract()\fR are kept in a global C array
1684 \&\f(CW\*(C`fp[]\*(C'\fR with offsets being \f(CW\*(C`multiply_off\*(C'\fR, \f(CW\*(C`divide_off\*(C'\fR, \f(CW\*(C`add_off\*(C'\fR,
1685 \&\f(CW\*(C`subtract_off\*(C'\fR. Then one can use
1686 .PP
1687 .Vb 4
1688 \& #define XSINTERFACE_FUNC_BYOFFSET(ret,cv,f) \e
1689 \& ((XSINTERFACE_CVT_ANON(ret))fp[CvXSUBANY(cv).any_i32])
1690 \& #define XSINTERFACE_FUNC_BYOFFSET_set(cv,f) \e
1691 \& CvXSUBANY(cv).any_i32 = CAT2( f, _off )
1692 .Ve
1693 .PP
1694 in C section,
1695 .PP
1696 .Vb 10
1697 \& symbolic
1698 \& interface_s_ss(arg1, arg2)
1699 \& symbolic arg1
1700 \& symbolic arg2
1701 \& INTERFACE_MACRO:
1702 \& XSINTERFACE_FUNC_BYOFFSET
1703 \& XSINTERFACE_FUNC_BYOFFSET_set
1704 \& INTERFACE:
1705 \& multiply divide
1706 \& add subtract
1707 .Ve
1708 .PP
1709 in XSUB section.
1710 .SS "The INCLUDE: Keyword"
1711 .IX Subsection "The INCLUDE: Keyword"
1712 This keyword can be used to pull other files into the XS module. The other
1713 files may have XS code. INCLUDE: can also be used to run a command to
1714 generate the XS code to be pulled into the module.
1715 .PP
1716 The file \fIRpcb1.xsh\fR contains our \f(CWrpcb_gettime()\fR function:
1717 .PP
1718 .Vb 6
1719 \& bool_t
1720 \& rpcb_gettime(host,timep)
1721 \& char *host
1722 \& time_t &timep
1723 \& OUTPUT:
1724 \& timep
1725 .Ve
1726 .PP
1727 The XS module can use INCLUDE: to pull that file into it.
1728 .PP
1729 .Vb 1
1730 \& INCLUDE: Rpcb1.xsh
1731 .Ve
1732 .PP
1733 If the parameters to the INCLUDE: keyword are followed by a pipe (\f(CW\*(C`|\*(C'\fR) then
1734 the compiler will interpret the parameters as a command. This feature is
1735 mildly deprecated in favour of the \f(CW\*(C`INCLUDE_COMMAND:\*(C'\fR directive, as documented
1736 below.
1737 .PP
1738 .Vb 1
1739 \& INCLUDE: cat Rpcb1.xsh |
1740 .Ve
1741 .PP
1742 Do not use this to run perl: \f(CW\*(C`INCLUDE: perl |\*(C'\fR will run the perl that
1743 happens to be the first in your path and not necessarily the same perl that is
1744 used to run \f(CW\*(C`xsubpp\*(C'\fR. See "The INCLUDE_COMMAND: Keyword".
1745 .SS "The INCLUDE_COMMAND: Keyword"
1746 .IX Subsection "The INCLUDE_COMMAND: Keyword"
1747 Runs the supplied command and includes its output into the current XS
1748 document. \f(CW\*(C`INCLUDE_COMMAND\*(C'\fR assigns special meaning to the \f(CW$^X\fR token
1749 in that it runs the same perl interpreter that is running \f(CW\*(C`xsubpp\*(C'\fR:
1750 .PP
1751 .Vb 1
1752 \& INCLUDE_COMMAND: cat Rpcb1.xsh
1753 \&
1754 \& INCLUDE_COMMAND: $^X \-e ...
1755 .Ve
1756 .SS "The CASE: Keyword"
1757 .IX Subsection "The CASE: Keyword"
1758 The CASE: keyword allows an XSUB to have multiple distinct parts with each
1759 part acting as a virtual XSUB. CASE: is greedy and if it is used then all
1760 other XS keywords must be contained within a CASE:. This means nothing may
1761 precede the first CASE: in the XSUB and anything following the last CASE: is
1762 included in that case.
1763 .PP
1764 A CASE: might switch via a parameter of the XSUB, via the \f(CW\*(C`ix\*(C'\fR ALIAS:
1765 variable (see "The ALIAS: Keyword"), or maybe via the \f(CW\*(C`items\*(C'\fR variable
1766 (see "Variable\-length Parameter Lists"). The last CASE: becomes the
1767 \&\fBdefault\fR case if it is not associated with a conditional. The following
1768 example shows CASE switched via \f(CW\*(C`ix\*(C'\fR with a function \f(CWrpcb_gettime()\fR
1769 having an alias \f(CWx_gettime()\fR. When the function is called as
1770 \&\f(CWrpcb_gettime()\fR its parameters are the usual \f(CW\*(C`(char *host, time_t *timep)\*(C'\fR,
1771 but when the function is called as \f(CWx_gettime()\fR its parameters are
1772 reversed, \f(CW\*(C`(time_t *timep, char *host)\*(C'\fR.
1773 .PP
1774 .Vb 10
1775 \& long
1776 \& rpcb_gettime(a,b)
1777 \& CASE: ix == 1
1778 \& ALIAS:
1779 \& x_gettime = 1
1780 \& INPUT:
1781 \& # \*(Aqa\*(Aq is timep, \*(Aqb\*(Aq is host
1782 \& char *b
1783 \& time_t a = NO_INIT
1784 \& CODE:
1785 \& RETVAL = rpcb_gettime( b, &a );
1786 \& OUTPUT:
1787 \& a
1788 \& RETVAL
1789 \& CASE:
1790 \& # \*(Aqa\*(Aq is host, \*(Aqb\*(Aq is timep
1791 \& char *a
1792 \& time_t &b = NO_INIT
1793 \& OUTPUT:
1794 \& b
1795 \& RETVAL
1796 .Ve
1797 .PP
1798 That function can be called with either of the following statements. Note
1799 the different argument lists.
1800 .PP
1801 .Vb 1
1802 \& $status = rpcb_gettime( $host, $timep );
1803 \&
1804 \& $status = x_gettime( $timep, $host );
1805 .Ve
1806 .SS "The EXPORT_XSUB_SYMBOLS: Keyword"
1807 .IX Subsection "The EXPORT_XSUB_SYMBOLS: Keyword"
1808 The EXPORT_XSUB_SYMBOLS: keyword is likely something you will never need.
1809 In perl versions earlier than 5.16.0, this keyword does nothing. Starting
1810 with 5.16, XSUB symbols are no longer exported by default. That is, they
1811 are \f(CW\*(C`static\*(C'\fR functions. If you include
1812 .PP
1813 .Vb 1
1814 \& EXPORT_XSUB_SYMBOLS: ENABLE
1815 .Ve
1816 .PP
1817 in your XS code, the XSUBs following this line will not be declared \f(CW\*(C`static\*(C'\fR.
1818 You can later disable this with
1819 .PP
1820 .Vb 1
1821 \& EXPORT_XSUB_SYMBOLS: DISABLE
1822 .Ve
1823 .PP
1824 which, again, is the default that you should probably never change.
1825 You cannot use this keyword on versions of perl before 5.16 to make
1826 XSUBs \f(CW\*(C`static\*(C'\fR.
1827 .SS "The & Unary Operator"
1828 .IX Subsection "The & Unary Operator"
1829 The \f(CW\*(C`&\*(C'\fR unary operator in the INPUT: section is used to tell \fBxsubpp\fR
1830 that it should convert a Perl value to/from C using the C type to the left
1831 of \f(CW\*(C`&\*(C'\fR, but provide a pointer to this value when the C function is called.
1832 .PP
1833 This is useful to avoid a CODE: block for a C function which takes a parameter
1834 by reference. Typically, the parameter should be not a pointer type (an
1835 \&\f(CW\*(C`int\*(C'\fR or \f(CW\*(C`long\*(C'\fR but not an \f(CW\*(C`int*\*(C'\fR or \f(CW\*(C`long*\*(C'\fR).
1836 .PP
1837 The following XSUB will generate incorrect C code. The \fBxsubpp\fR compiler will
1838 turn this into code which calls \f(CWrpcb_gettime()\fR with parameters \f(CW\*(C`(char
1839 *host, time_t timep)\*(C'\fR, but the real \f(CWrpcb_gettime()\fR wants the \f(CW\*(C`timep\*(C'\fR
1840 parameter to be of type \f(CW\*(C`time_t*\*(C'\fR rather than \f(CW\*(C`time_t\*(C'\fR.
1841 .PP
1842 .Vb 6
1843 \& bool_t
1844 \& rpcb_gettime(host,timep)
1845 \& char *host
1846 \& time_t timep
1847 \& OUTPUT:
1848 \& timep
1849 .Ve
1850 .PP
1851 That problem is corrected by using the \f(CW\*(C`&\*(C'\fR operator. The \fBxsubpp\fR compiler
1852 will now turn this into code which calls \f(CWrpcb_gettime()\fR correctly with
1853 parameters \f(CW\*(C`(char *host, time_t *timep)\*(C'\fR. It does this by carrying the
1854 \&\f(CW\*(C`&\*(C'\fR through, so the function call looks like \f(CW\*(C`rpcb_gettime(host, &timep)\*(C'\fR.
1855 .PP
1856 .Vb 6
1857 \& bool_t
1858 \& rpcb_gettime(host,timep)
1859 \& char *host
1860 \& time_t &timep
1861 \& OUTPUT:
1862 \& timep
1863 .Ve
1864 .SS "Inserting POD, Comments and C Preprocessor Directives"
1865 .IX Subsection "Inserting POD, Comments and C Preprocessor Directives"
1866 C preprocessor directives are allowed within BOOT:, PREINIT: INIT:, CODE:,
1867 PPCODE:, POSTCALL:, and CLEANUP: blocks, as well as outside the functions.
1868 Comments are allowed anywhere after the MODULE keyword. The compiler will
1869 pass the preprocessor directives through untouched and will remove the
1870 commented lines. POD documentation is allowed at any point, both in the
1871 C and XS language sections. POD must be terminated with a \f(CW\*(C`=cut\*(C'\fR command;
1872 \&\f(CW\*(C`xsubpp\*(C'\fR will exit with an error if it does not. It is very unlikely that
1873 human generated C code will be mistaken for POD, as most indenting styles
1874 result in whitespace in front of any line starting with \f(CW\*(C`=\*(C'\fR. Machine
1875 generated XS files may fall into this trap unless care is taken to
1876 ensure that a space breaks the sequence "\en=".
1877 .PP
1878 Comments can be added to XSUBs by placing a \f(CW\*(C`#\*(C'\fR as the first
1879 non\-whitespace of a line. Care should be taken to avoid making the
1880 comment look like a C preprocessor directive, lest it be interpreted as
1881 such. The simplest way to prevent this is to put whitespace in front of
1882 the \f(CW\*(C`#\*(C'\fR.
1883 .PP
1884 If you use preprocessor directives to choose one of two
1885 versions of a function, use
1886 .PP
1887 .Vb 3
1888 \& #if ... version1
1889 \& #else /* ... version2 */
1890 \& #endif
1891 .Ve
1892 .PP
1893 and not
1894 .PP
1895 .Vb 4
1896 \& #if ... version1
1897 \& #endif
1898 \& #if ... version2
1899 \& #endif
1900 .Ve
1901 .PP
1902 because otherwise \fBxsubpp\fR will believe that you made a duplicate
1903 definition of the function. Also, put a blank line before the
1904 #else/#endif so it will not be seen as part of the function body.
1905 .SS "Using XS With C++"
1906 .IX Subsection "Using XS With C++"
1907 If an XSUB name contains \f(CW\*(C`::\*(C'\fR, it is considered to be a C++ method.
1908 The generated Perl function will assume that
1909 its first argument is an object pointer. The object pointer
1910 will be stored in a variable called THIS. The object should
1911 have been created by C++ with the \fBnew()\fR function and should
1912 be blessed by Perl with the \fBsv_setref_pv()\fR macro. The
1913 blessing of the object by Perl can be handled by a typemap. An example
1914 typemap is shown at the end of this section.
1915 .PP
1916 If the return type of the XSUB includes \f(CW\*(C`static\*(C'\fR, the method is considered
1917 to be a static method. It will call the C++
1918 function using the \fBclass::method()\fR syntax. If the method is not static
1919 the function will be called using the THIS\->\fBmethod()\fR syntax.
1920 .PP
1921 The next examples will use the following C++ class.
1922 .PP
1923 .Vb 6
1924 \& class color {
1925 \& public:
1926 \& color();
1927 \& ~color();
1928 \& int blue();
1929 \& void set_blue( int );
1930 \&
1931 \& private:
1932 \& int c_blue;
1933 \& };
1934 .Ve
1935 .PP
1936 The XSUBs for the \fBblue()\fR and \fBset_blue()\fR methods are defined with the class
1937 name but the parameter for the object (THIS, or "self") is implicit and is
1938 not listed.
1939 .PP
1940 .Vb 2
1941 \& int
1942 \& color::blue()
1943 \&
1944 \& void
1945 \& color::set_blue( val )
1946 \& int val
1947 .Ve
1948 .PP
1949 Both Perl functions will expect an object as the first parameter. In the
1950 generated C++ code the object is called \f(CW\*(C`THIS\*(C'\fR, and the method call will
1951 be performed on this object. So in the C++ code the \fBblue()\fR and \fBset_blue()\fR
1952 methods will be called as this:
1953 .PP
1954 .Vb 1
1955 \& RETVAL = THIS\->blue();
1956 \&
1957 \& THIS\->set_blue( val );
1958 .Ve
1959 .PP
1960 You could also write a single get/set method using an optional argument:
1961 .PP
1962 .Vb 10
1963 \& int
1964 \& color::blue( val = NO_INIT )
1965 \& int val
1966 \& PROTOTYPE $;$
1967 \& CODE:
1968 \& if (items > 1)
1969 \& THIS\->set_blue( val );
1970 \& RETVAL = THIS\->blue();
1971 \& OUTPUT:
1972 \& RETVAL
1973 .Ve
1974 .PP
1975 If the function\*(Aqs name is \fBDESTROY\fR then the C++ \f(CW\*(C`delete\*(C'\fR function will be
1976 called and \f(CW\*(C`THIS\*(C'\fR will be given as its parameter. The generated C++ code for
1977 .PP
1978 .Vb 2
1979 \& void
1980 \& color::DESTROY()
1981 .Ve
1982 .PP
1983 will look like this:
1984 .PP
1985 .Vb 1
1986 \& color *THIS = ...; // Initialized as in typemap
1987 \&
1988 \& delete THIS;
1989 .Ve
1990 .PP
1991 If the function\*(Aqs name is \fBnew\fR then the C++ \f(CW\*(C`new\*(C'\fR function will be called
1992 to create a dynamic C++ object. The XSUB will expect the class name, which
1993 will be kept in a variable called \f(CW\*(C`CLASS\*(C'\fR, to be given as the first
1994 argument.
1995 .PP
1996 .Vb 2
1997 \& color *
1998 \& color::new()
1999 .Ve
2000 .PP
2001 The generated C++ code will call \f(CW\*(C`new\*(C'\fR.
2002 .PP
2003 .Vb 1
2004 \& RETVAL = new color();
2005 .Ve
2006 .PP
2007 The following is an example of a typemap that could be used for this C++
2008 example.
2009 .PP
2010 .Vb 2
2011 \& TYPEMAP
2012 \& color * O_OBJECT
2013 \&
2014 \& OUTPUT
2015 \& # The Perl object is blessed into \*(AqCLASS\*(Aq, which should be a
2016 \& # char* having the name of the package for the blessing.
2017 \& O_OBJECT
2018 \& sv_setref_pv( $arg, CLASS, (void*)$var );
2019 \&
2020 \& INPUT
2021 \& O_OBJECT
2022 \& if( sv_isobject($arg) && (SvTYPE(SvRV($arg)) == SVt_PVMG) )
2023 \& $var = ($type)SvIV((SV*)SvRV( $arg ));
2024 \& else{
2025 \& warn(\e"${Package}::$func_name() \-\- \e"
2026 \& \e"$var is not a blessed SV reference\e");
2027 \& XSRETURN_UNDEF;
2028 \& }
2029 .Ve
2030 .SS "Interface Strategy"
2031 .IX Subsection "Interface Strategy"
2032 When designing an interface between Perl and a C library a straight
2033 translation from C to XS (such as created by \f(CW\*(C`h2xs \-x\*(C'\fR) is often sufficient.
2034 However, sometimes the interface will look
2035 very C\-like and occasionally nonintuitive, especially when the C function
2036 modifies one of its parameters, or returns failure inband (as in "negative
2037 return values mean failure"). In cases where the programmer wishes to
2038 create a more Perl\-like interface the following strategy may help to
2039 identify the more critical parts of the interface.
2040 .PP
2041 Identify the C functions with input/output or output parameters. The XSUBs for
2042 these functions may be able to return lists to Perl.
2043 .PP
2044 Identify the C functions which use some inband info as an indication
2045 of failure. They may be
2046 candidates to return undef or an empty list in case of failure. If the
2047 failure may be detected without a call to the C function, you may want to use
2048 an INIT: section to report the failure. For failures detectable after the C
2049 function returns one may want to use a POSTCALL: section to process the
2050 failure. In more complicated cases use CODE: or PPCODE: sections.
2051 .PP
2052 If many functions use the same failure indication based on the return value,
2053 you may want to create a special typedef to handle this situation. Put
2054 .PP
2055 .Vb 1
2056 \& typedef int negative_is_failure;
2057 .Ve
2058 .PP
2059 near the beginning of XS file, and create an OUTPUT typemap entry
2060 for \f(CW\*(C`negative_is_failure\*(C'\fR which converts negative values to \f(CW\*(C`undef\*(C'\fR, or
2061 maybe \fBcroak()\fRs. After this the return value of type \f(CW\*(C`negative_is_failure\*(C'\fR
2062 will create more Perl\-like interface.
2063 .PP
2064 Identify which values are used by only the C and XSUB functions
2065 themselves, say, when a parameter to a function should be a contents of a
2066 global variable. If Perl does not need to access the contents of the value
2067 then it may not be necessary to provide a translation for that value
2068 from C to Perl.
2069 .PP
2070 Identify the pointers in the C function parameter lists and return
2071 values. Some pointers may be used to implement input/output or
2072 output parameters, they can be handled in XS with the \f(CW\*(C`&\*(C'\fR unary operator,
2073 and, possibly, using the NO_INIT keyword.
2074 Some others will require handling of types like \f(CW\*(C`int *\*(C'\fR, and one needs
2075 to decide what a useful Perl translation will do in such a case. When
2076 the semantic is clear, it is advisable to put the translation into a typemap
2077 file.
2078 .PP
2079 Identify the structures used by the C functions. In many
2080 cases it may be helpful to use the T_PTROBJ typemap for
2081 these structures so they can be manipulated by Perl as
2082 blessed objects. (This is handled automatically by \f(CW\*(C`h2xs \-x\*(C'\fR.)
2083 .PP
2084 If the same C type is used in several different contexts which require
2085 different translations, \f(CW\*(C`typedef\*(C'\fR several new types mapped to this C type,
2086 and create separate \fItypemap\fR entries for these new types. Use these
2087 types in declarations of return type and parameters to XSUBs.
2088 .SS "Perl Objects And C Structures"
2089 .IX Subsection "Perl Objects And C Structures"
2090 When dealing with C structures one should select either
2091 \&\fBT_PTROBJ\fR or \fBT_PTRREF\fR for the XS type. Both types are
2092 designed to handle pointers to complex objects. The
2093 T_PTRREF type will allow the Perl object to be unblessed
2094 while the T_PTROBJ type requires that the object be blessed.
2095 By using T_PTROBJ one can achieve a form of type\-checking
2096 because the XSUB will attempt to verify that the Perl object
2097 is of the expected type.
2098 .PP
2099 The following XS code shows the \fBgetnetconfigent()\fR function which is used
2100 with ONC+ TIRPC. The \fBgetnetconfigent()\fR function will return a pointer to a
2101 C structure and has the C prototype shown below. The example will
2102 demonstrate how the C pointer will become a Perl reference. Perl will
2103 consider this reference to be a pointer to a blessed object and will
2104 attempt to call a destructor for the object. A destructor will be
2105 provided in the XS source to free the memory used by \fBgetnetconfigent()\fR.
2106 Destructors in XS can be created by specifying an XSUB function whose name
2107 ends with the word \fBDESTROY\fR. XS destructors can be used to free memory
2108 which may have been malloc\*(Aqd by another XSUB.
2109 .PP
2110 .Vb 1
2111 \& struct netconfig *getnetconfigent(const char *netid);
2112 .Ve
2113 .PP
2114 A \f(CW\*(C`typedef\*(C'\fR will be created for \f(CW\*(C`struct netconfig\*(C'\fR. The Perl
2115 object will be blessed in a class matching the name of the C
2116 type, with the tag \f(CW\*(C`Ptr\*(C'\fR appended, and the name should not
2117 have embedded spaces if it will be a Perl package name. The
2118 destructor will be placed in a class corresponding to the
2119 class of the object and the PREFIX keyword will be used to
2120 trim the name to the word DESTROY as Perl will expect.
2121 .PP
2122 .Vb 1
2123 \& typedef struct netconfig Netconfig;
2124 \&
2125 \& MODULE = RPC PACKAGE = RPC
2126 \&
2127 \& Netconfig *
2128 \& getnetconfigent(netid)
2129 \& char *netid
2130 \&
2131 \& MODULE = RPC PACKAGE = NetconfigPtr PREFIX = rpcb_
2132 \&
2133 \& void
2134 \& rpcb_DESTROY(netconf)
2135 \& Netconfig *netconf
2136 \& CODE:
2137 \& printf("Now in NetconfigPtr::DESTROY\en");
2138 \& free( netconf );
2139 .Ve
2140 .PP
2141 This example requires the following typemap entry. Consult
2142 perlxstypemap for more information about adding new typemaps
2143 for an extension.
2144 .PP
2145 .Vb 2
2146 \& TYPEMAP
2147 \& Netconfig * T_PTROBJ
2148 .Ve
2149 .PP
2150 This example will be used with the following Perl statements.
2151 .PP
2152 .Vb 2
2153 \& use RPC;
2154 \& $netconf = getnetconfigent("udp");
2155 .Ve
2156 .PP
2157 When Perl destroys the object referenced by \f(CW$netconf\fR it will send the
2158 object to the supplied XSUB DESTROY function. Perl cannot determine, and
2159 does not care, that this object is a C struct and not a Perl object. In
2160 this sense, there is no difference between the object created by the
2161 \&\fBgetnetconfigent()\fR XSUB and an object created by a normal Perl subroutine.
2162 .SS "Safely Storing Static Data in XS"
2163 .IX Subsection "Safely Storing Static Data in XS"
2164 Starting with Perl 5.8, a macro framework has been defined to allow
2165 static data to be safely stored in XS modules that will be accessed from
2166 a multi\-threaded Perl.
2167 .PP
2168 Although primarily designed for use with multi\-threaded Perl, the macros
2169 have been designed so that they will work with non\-threaded Perl as well.
2170 .PP
2171 It is therefore strongly recommended that these macros be used by all
2172 XS modules that make use of static data.
2173 .PP
2174 The easiest way to get a template set of macros to use is by specifying
2175 the \f(CW\*(C`\-g\*(C'\fR (\f(CW\*(C`\-\-global\*(C'\fR) option with h2xs (see h2xs).
2176 .PP
2177 Below is an example module that makes use of the macros.
2178 .PP
2179 .Vb 4
2180 \& #define PERL_NO_GET_CONTEXT
2181 \& #include "EXTERN.h"
2182 \& #include "perl.h"
2183 \& #include "XSUB.h"
2184 \&
2185 \& /* Global Data */
2186 \&
2187 \& #define MY_CXT_KEY "BlindMice::_guts" XS_VERSION
2188 \&
2189 \& typedef struct {
2190 \& int count;
2191 \& char name[3][100];
2192 \& } my_cxt_t;
2193 \&
2194 \& START_MY_CXT
2195 \&
2196 \& MODULE = BlindMice PACKAGE = BlindMice
2197 \&
2198 \& BOOT:
2199 \& {
2200 \& MY_CXT_INIT;
2201 \& MY_CXT.count = 0;
2202 \& strcpy(MY_CXT.name[0], "None");
2203 \& strcpy(MY_CXT.name[1], "None");
2204 \& strcpy(MY_CXT.name[2], "None");
2205 \& }
2206 \&
2207 \& int
2208 \& newMouse(char * name)
2209 \& PREINIT:
2210 \& dMY_CXT;
2211 \& CODE:
2212 \& if (MY_CXT.count >= 3) {
2213 \& warn("Already have 3 blind mice");
2214 \& RETVAL = 0;
2215 \& }
2216 \& else {
2217 \& RETVAL = ++ MY_CXT.count;
2218 \& strcpy(MY_CXT.name[MY_CXT.count \- 1], name);
2219 \& }
2220 \& OUTPUT:
2221 \& RETVAL
2222 \&
2223 \& char *
2224 \& get_mouse_name(index)
2225 \& int index
2226 \& PREINIT:
2227 \& dMY_CXT;
2228 \& CODE:
2229 \& if (index > MY_CXT.count)
2230 \& croak("There are only 3 blind mice.");
2231 \& else
2232 \& RETVAL = MY_CXT.name[index \- 1];
2233 \& OUTPUT:
2234 \& RETVAL
2235 \&
2236 \& void
2237 \& CLONE(...)
2238 \& CODE:
2239 \& MY_CXT_CLONE;
2240 .Ve
2241 .PP
2242 \fIMY_CXT REFERENCE\fR
2243 .IX Subsection "MY_CXT REFERENCE"
2244 .IP MY_CXT_KEY 5
2245 .IX Item "MY_CXT_KEY"
2246 This macro is used to define a unique key to refer to the static data
2247 for an XS module. The suggested naming scheme, as used by h2xs, is to
2248 use a string that consists of the module name, the string "::_guts"
2249 and the module version number.
2250 .Sp
2251 .Vb 1
2252 \& #define MY_CXT_KEY "MyModule::_guts" XS_VERSION
2253 .Ve
2254 .IP "typedef my_cxt_t" 5
2255 .IX Item "typedef my_cxt_t"
2256 This struct typedef \fImust\fR always be called \f(CW\*(C`my_cxt_t\*(C'\fR. The other
2257 \&\f(CW\*(C`CXT*\*(C'\fR macros assume the existence of the \f(CW\*(C`my_cxt_t\*(C'\fR typedef name.
2258 .Sp
2259 Declare a typedef named \f(CW\*(C`my_cxt_t\*(C'\fR that is a structure that contains
2260 all the data that needs to be interpreter\-local.
2261 .Sp
2262 .Vb 3
2263 \& typedef struct {
2264 \& int some_value;
2265 \& } my_cxt_t;
2266 .Ve
2267 .IP START_MY_CXT 5
2268 .IX Item "START_MY_CXT"
2269 Always place the START_MY_CXT macro directly after the declaration
2270 of \f(CW\*(C`my_cxt_t\*(C'\fR.
2271 .IP MY_CXT_INIT 5
2272 .IX Item "MY_CXT_INIT"
2273 The MY_CXT_INIT macro initializes storage for the \f(CW\*(C`my_cxt_t\*(C'\fR struct.
2274 .Sp
2275 It \fImust\fR be called exactly once, typically in a BOOT: section. If you
2276 are maintaining multiple interpreters, it should be called once in each
2277 interpreter instance, except for interpreters cloned from existing ones.
2278 (But see "MY_CXT_CLONE" below.)
2279 .IP dMY_CXT 5
2280 .IX Item "dMY_CXT"
2281 Use the dMY_CXT macro (a declaration) in all the functions that access
2282 MY_CXT.
2283 .IP MY_CXT 5
2284 .IX Item "MY_CXT"
2285 Use the MY_CXT macro to access members of the \f(CW\*(C`my_cxt_t\*(C'\fR struct. For
2286 example, if \f(CW\*(C`my_cxt_t\*(C'\fR is
2287 .Sp
2288 .Vb 3
2289 \& typedef struct {
2290 \& int index;
2291 \& } my_cxt_t;
2292 .Ve
2293 .Sp
2294 then use this to access the \f(CW\*(C`index\*(C'\fR member
2295 .Sp
2296 .Vb 2
2297 \& dMY_CXT;
2298 \& MY_CXT.index = 2;
2299 .Ve
2300 .IP aMY_CXT/pMY_CXT 5
2301 .IX Item "aMY_CXT/pMY_CXT"
2302 \&\f(CW\*(C`dMY_CXT\*(C'\fR may be quite expensive to calculate, and to avoid the overhead
2303 of invoking it in each function it is possible to pass the declaration
2304 onto other functions using the \f(CW\*(C`aMY_CXT\*(C'\fR/\f(CW\*(C`pMY_CXT\*(C'\fR macros, eg
2305 .Sp
2306 .Vb 5
2307 \& void sub1() {
2308 \& dMY_CXT;
2309 \& MY_CXT.index = 1;
2310 \& sub2(aMY_CXT);
2311 \& }
2312 \&
2313 \& void sub2(pMY_CXT) {
2314 \& MY_CXT.index = 2;
2315 \& }
2316 .Ve
2317 .Sp
2318 Analogously to \f(CW\*(C`pTHX\*(C'\fR, there are equivalent forms for when the macro is the
2319 first or last in multiple arguments, where an underscore represents a
2320 comma, i.e. \f(CW\*(C`_aMY_CXT\*(C'\fR, \f(CW\*(C`aMY_CXT_\*(C'\fR, \f(CW\*(C`_pMY_CXT\*(C'\fR and \f(CW\*(C`pMY_CXT_\*(C'\fR.
2321 .IP MY_CXT_CLONE 5
2322 .IX Item "MY_CXT_CLONE"
2323 By default, when a new interpreter is created as a copy of an existing one
2324 (eg via \f(CW\*(C`threads\->create()\*(C'\fR), both interpreters share the same physical
2325 my_cxt_t structure. Calling \f(CW\*(C`MY_CXT_CLONE\*(C'\fR (typically via the package\*(Aqs
2326 \&\f(CWCLONE()\fR function), causes a byte\-for\-byte copy of the structure to be
2327 taken, and any future dMY_CXT will cause the copy to be accessed instead.
2328 .IP MY_CXT_INIT_INTERP(my_perl) 5
2329 .IX Item "MY_CXT_INIT_INTERP(my_perl)"
2330 .PD 0
2331 .IP dMY_CXT_INTERP(my_perl) 5
2332 .IX Item "dMY_CXT_INTERP(my_perl)"
2333 .PD
2334 These are versions of the macros which take an explicit interpreter as an
2335 argument.
2336 .PP
2337 Note that these macros will only work together within the \fIsame\fR source
2338 file; that is, a dMY_CTX in one source file will access a different structure
2339 than a dMY_CTX in another source file.
2340 .SH EXAMPLES
2341 .IX Header "EXAMPLES"
2342 File \f(CW\*(C`RPC.xs\*(C'\fR: Interface to some ONC+ RPC bind library functions.
2343 .PP
2344 .Vb 4
2345 \& #define PERL_NO_GET_CONTEXT
2346 \& #include "EXTERN.h"
2347 \& #include "perl.h"
2348 \& #include "XSUB.h"
2349 \&
2350 \& /* Note: On glibc 2.13 and earlier, this needs be <rpc/rpc.h> */
2351 \& #include <tirpc/rpc.h>
2352 \&
2353 \& typedef struct netconfig Netconfig;
2354 \&
2355 \& MODULE = RPC PACKAGE = RPC
2356 \&
2357 \& SV *
2358 \& rpcb_gettime(host="localhost")
2359 \& char *host
2360 \& PREINIT:
2361 \& time_t timep;
2362 \& CODE:
2363 \& ST(0) = sv_newmortal();
2364 \& if( rpcb_gettime( host, &timep ) )
2365 \& sv_setnv( ST(0), (double)timep );
2366 \&
2367 \& Netconfig *
2368 \& getnetconfigent(netid="udp")
2369 \& char *netid
2370 \&
2371 \& MODULE = RPC PACKAGE = NetconfigPtr PREFIX = rpcb_
2372 \&
2373 \& void
2374 \& rpcb_DESTROY(netconf)
2375 \& Netconfig *netconf
2376 \& CODE:
2377 \& printf("NetconfigPtr::DESTROY\en");
2378 \& free( netconf );
2379 .Ve
2380 .PP
2381 File \f(CW\*(C`typemap\*(C'\fR: Custom typemap for RPC.xs. (cf. perlxstypemap)
2382 .PP
2383 .Vb 2
2384 \& TYPEMAP
2385 \& Netconfig * T_PTROBJ
2386 .Ve
2387 .PP
2388 File \f(CW\*(C`RPC.pm\*(C'\fR: Perl module for the RPC extension.
2389 .PP
2390 .Vb 1
2391 \& package RPC;
2392 \&
2393 \& require Exporter;
2394 \& require DynaLoader;
2395 \& @ISA = qw(Exporter DynaLoader);
2396 \& @EXPORT = qw(rpcb_gettime getnetconfigent);
2397 \&
2398 \& bootstrap RPC;
2399 \& 1;
2400 .Ve
2401 .PP
2402 File \f(CW\*(C`rpctest.pl\*(C'\fR: Perl test program for the RPC extension.
2403 .PP
2404 .Vb 1
2405 \& use RPC;
2406 \&
2407 \& $netconf = getnetconfigent();
2408 \& $a = rpcb_gettime();
2409 \& print "time = $a\en";
2410 \& print "netconf = $netconf\en";
2411 \&
2412 \& $netconf = getnetconfigent("tcp");
2413 \& $a = rpcb_gettime("poplar");
2414 \& print "time = $a\en";
2415 \& print "netconf = $netconf\en";
2416 .Ve
2417 .PP
2418 In Makefile.PL add \-ltirpc and \-I/usr/include/tirpc.
2419 .SH CAVEATS
2420 .IX Header "CAVEATS"
2421 .SS "Use of standard C library functions"
2422 .IX Subsection "Use of standard C library functions"
2423 See perlclib.
2424 .SS "Event loops and control flow"
2425 .IX Subsection "Event loops and control flow"
2426 Some modules have an event loop, waiting for user\-input. It is highly
2427 unlikely that two such modules would work adequately together in a
2428 single Perl application.
2429 .PP
2430 In general, the perl interpreter views itself as the center of the
2431 universe as far as the Perl program goes. XS code is viewed as a
2432 help\-mate, to accomplish things that perl doesn\*(Aqt do, or doesn\*(Aqt do fast
2433 enough, but always subservient to perl. The closer XS code adheres to
2434 this model, the less likely conflicts will occur.
2435 .SH "XS VERSION"
2436 .IX Header "XS VERSION"
2437 This document covers features supported by \f(CW\*(C`ExtUtils::ParseXS\*(C'\fR
2438 (also known as \f(CW\*(C`xsubpp\*(C'\fR) 3.57.
2439 .SH "AUTHOR DIAGNOSTICS"
2440 .IX Header "AUTHOR DIAGNOSTICS"
2441 As of version 3.49 certain warnings are disabled by default. While developing
2442 you can set \f(CW$ENV{AUTHOR_WARNINGS}\fR to true in your environment or in your
2443 Makefile.PL, or set \f(CW$ExtUtils::ParseXS::AUTHOR_WARNINGS\fR to true via code, or
2444 pass \f(CW\*(C`author_warnings=>1\*(C'\fR into \fBprocess_file()\fR explicitly. Currently this will
2445 enable stricter alias checking but more warnings might be added in the future.
2446 The kind of warnings this will enable are only helpful to the author of the XS
2447 file, and the diagnostics produced will not include installation specific
2448 details so they are only useful to the maintainer of the XS code itself.
2449 .SH AUTHOR
2450 .IX Header "AUTHOR"
2451 Originally written by Dean Roehrich <\[email protected]\fR>.
2452 .PP
2453 Maintained since 1996 by The Perl Porters <\fIperl5\[email protected]\fR>.