Debian Codegraph @

upstream/debian-unstable/man1/perlxs.1

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