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