Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | =head1 NAME |
2 | ||
3 | Inline::C - Write Perl Subroutines in C | |
4 | ||
5 | =head1 DESCRIPTION | |
6 | ||
7 | C<Inline::C> is a module that allows you to write Perl subroutines in C. | |
8 | Since version 0.30 the Inline module supports multiple programming | |
9 | languages and each language has its own support module. This document | |
10 | describes how to use Inline with the C programming language. It also | |
11 | goes a bit into Perl C internals. | |
12 | ||
13 | If you want to start working with programming examples right away, check | |
14 | out L<Inline::C-Cookbook>. For more information on Inline in general, | |
15 | see L<Inline>. | |
16 | ||
17 | =head1 Usage | |
18 | ||
19 | You never actually use C<Inline::C> directly. It is just a support | |
20 | module for using C<Inline.pm> with C. So the usage is always: | |
21 | ||
22 | use Inline C => ...; | |
23 | ||
24 | or | |
25 | ||
26 | bind Inline C => ...; | |
27 | ||
28 | =head1 Function Definitions | |
29 | ||
30 | The Inline grammar for C recognizes certain function definitions (or | |
31 | signatures) in your C code. If a signature is recognized by Inline, then | |
32 | it will be available in Perl-space. That is, Inline will generate the | |
33 | "glue" necessary to call that function as if it were a Perl subroutine. | |
34 | If the signature is not recognized, Inline will simply ignore it, with | |
35 | no complaints. It will not be available from Perl-space, although it | |
36 | I<will> be available from C-space. | |
37 | ||
38 | Inline looks for ANSI/prototype style function definitions. They must be | |
39 | of the form: | |
40 | ||
41 | return-type function-name ( type-name-pairs ) { ... } | |
42 | ||
43 | The most common types are: C<int>, C<long>, C<double>, C<char*>, and | |
44 | C<SV*>. But you can use any type for which Inline can find a typemap. | |
45 | Inline uses the C<typemap> file distributed with Perl as the default. | |
46 | You can specify more typemaps with the TYPEMAPS configuration option. | |
47 | ||
48 | A return type of C<void> may also be used. The following are examples of | |
49 | valid function definitions. | |
50 | ||
51 | int Foo(double num, char* str) { | |
52 | void Foo(double num, char* str) { | |
53 | SV* Foo() { | |
54 | void Foo(SV*, ...) { | |
55 | long Foo(int i, int j, ...) { | |
56 | ||
57 | The following definitions would not be recognized: | |
58 | ||
59 | Foo(int i) { # no return type | |
60 | int Foo(float f) { # no (default) typemap for float | |
61 | int Foo(num, str) double num; char* str; { | |
62 | void Foo(void) { # void only valid for return type | |
63 | ||
64 | Notice that Inline only looks for function I<definitions>, not function | |
65 | I<prototypes>. Definitions are the syntax directly preceeding a function | |
66 | body. Also Inline does not scan external files, like headers. Only the | |
67 | code passed to Inline is used to create bindings; although other | |
68 | libraries can linked in, and called from C-space. | |
69 | ||
70 | =head1 C Configuration Options | |
71 | ||
72 | For information on how to specify Inline configuration options, see | |
73 | L<Inline>. This section describes each of the configuration options | |
74 | available for C. Most of the options correspond either to MakeMaker or | |
75 | XS options of the same name. See L<ExtUtils::MakeMaker> and L<perlxs>. | |
76 | ||
77 | =head2 AUTO_INCLUDE | |
78 | ||
79 | Specifies extra statements to automatically included. They will be added | |
80 | onto the defaults. A newline char will be automatically added. | |
81 | ||
82 | use Inline C => Config => AUTO_INCLUDE => '#include "yourheader.h"'; | |
83 | ||
84 | =head2 AUTOWRAP | |
85 | ||
86 | If you 'ENABLE => AUTOWRAP', Inline::C will parse function declarations | |
87 | (prototype statements) in your C code. For each declaration it can bind | |
88 | to, it will create a dummy wrapper that will call the real function | |
89 | which may be in an external library. This is a nice convenience for | |
90 | functions that would otherwise just require an empty wrapper function. | |
91 | ||
92 | This is similar to the base functionality you get from C<h2xs>. It can | |
93 | be very useful for binding to external libraries. | |
94 | ||
95 | =head2 BOOT | |
96 | ||
97 | Specifies C code to be executed in the XS BOOT section. Corresponds to | |
98 | the XS parameter. | |
99 | ||
100 | =head2 CC | |
101 | ||
102 | Specify which compiler to use. | |
103 | ||
104 | =head2 CCFLAGS | |
105 | ||
106 | Specify extra compiler flags. | |
107 | ||
108 | =head2 FILTERS | |
109 | ||
110 | Allows you to specify a list of source code filters. If more than one is | |
111 | requested, be sure to group them with an array ref. The filters can | |
112 | either be subroutine references or names of filters provided by the | |
113 | supplementary Inline::Filters module. | |
114 | ||
115 | Your source code will be filtered just before it is parsed by Inline. | |
116 | The MD5 fingerprint is generated before filtering. Source code | |
117 | filters can be used to do things like stripping out POD | |
118 | documentation, pre-expanding #include statements or whatever else you | |
119 | please. For example: | |
120 | ||
121 | use Inline C => DATA => | |
122 | FILTERS => [Strip_POD => \&MyFilter => Preprocess ]; | |
123 | ||
124 | Filters are invoked in the order specified. See L<Inline::Filters> for | |
125 | more information. | |
126 | ||
127 | =head2 INC | |
128 | ||
129 | Specifies an include path to use. Corresponds to the MakeMaker parameter. | |
130 | ||
131 | use Inline C => Config => INC => '-I/inc/path'; | |
132 | ||
133 | =head2 LD | |
134 | ||
135 | Specify which linker to use. | |
136 | ||
137 | =head2 LDDLFLAGS | |
138 | ||
139 | Specify which linker flags to use. | |
140 | ||
141 | NOTE: | |
142 | These flags will completely override the existing flags, instead of | |
143 | just adding to them. So if you need to use those too, you must | |
144 | respecify them here. | |
145 | ||
146 | =head2 LIBS | |
147 | ||
148 | Specifies external libraries that should be linked into your code. | |
149 | Corresponds to the MakeMaker parameter. | |
150 | ||
151 | use Inline C => Config => LIBS => '-lyourlib'; | |
152 | ||
153 | or | |
154 | ||
155 | use Inline C => Config => LIBS => '-L/your/path -lyourlib'; | |
156 | ||
157 | =head2 MAKE | |
158 | ||
159 | Specify the name of the 'make' utility to use. | |
160 | ||
161 | =head2 MYEXTLIB | |
162 | ||
163 | Specifies a user compiled object that should be linked in. Corresponds | |
164 | to the MakeMaker parameter. | |
165 | ||
166 | use Inline C => Config => MYEXTLIB => '/your/path/yourmodule.so'; | |
167 | ||
168 | =head2 OPTIMIZE | |
169 | ||
170 | This controls the MakeMaker OPTIMIZE setting. By setting this value to | |
171 | C<'-g'>, you can turn on debugging support for your Inline extensions. | |
172 | This will allow you to be able to set breakpoints in your C code using a | |
173 | debugger like gdb. | |
174 | ||
175 | =head2 PREFIX | |
176 | ||
177 | Specifies a prefix that will be automatically stripped from C functions | |
178 | when they are bound to Perl. Useful for creating wrappers for shared | |
179 | library API-s, and binding to the original names in Perl. Also useful | |
180 | when names conflict with Perl internals. Corresponds to the XS | |
181 | parameter. | |
182 | ||
183 | use Inline C => Config => PREFIX => 'ZLIB_'; | |
184 | ||
185 | =head2 TYPEMAPS | |
186 | ||
187 | Specifies extra typemap files to use. These types will modify the | |
188 | behaviour of the C parsing. Corresponds to the MakeMaker parameter. | |
189 | ||
190 | use Inline C => Config => TYPEMAPS => '/your/path/typemap'; | |
191 | ||
192 | =head1 C-Perl Bindings | |
193 | ||
194 | This section describes how the C<Perl> variables get mapped to C<C> | |
195 | variables and back again. | |
196 | ||
197 | First, you need to know how C<Perl> passes arguments back and forth to | |
198 | subroutines. Basically it uses a stack (also known as the B<Stack>). | |
199 | When a sub is called, all of the parenthesized arguments get expanded | |
200 | into a list of scalars and pushed onto the B<Stack>. The subroutine then | |
201 | pops all of its parameters off of the B<Stack>. When the sub is done, it | |
202 | pushes all of its return values back onto the B<Stack>. | |
203 | ||
204 | The B<Stack> is an array of scalars known internally as C<SV>'s. The | |
205 | B<Stack> is actually an array of B<pointers to SV> or C<SV*>; therefore | |
206 | every element of the B<Stack> is natively a C<SV*>. For I<FMTYEWTK> | |
207 | about this, read C<perldoc perlguts>. | |
208 | ||
209 | So back to variable mapping. XS uses a thing known as "typemaps" to turn | |
210 | each C<SV*> into a C<C> type and back again. This is done through | |
211 | various XS macro calls, casts and the Perl API. See C<perldoc perlapi>. | |
212 | XS allows you to define your own typemaps as well for fancier | |
213 | non-standard types such as C<typedef>-ed structs. | |
214 | ||
215 | Inline uses the default Perl typemap file for its default types. This | |
216 | file is called C</usr/local/lib/perl5/5.6.1/ExtUtils/typemap>, or | |
217 | something similar, depending on your Perl installation. It has | |
218 | definitions for over 40 types, which are automatically used by Inline. | |
219 | (You should probably browse this file at least once, just to get an idea | |
220 | of the possibilities.) | |
221 | ||
222 | Inline parses your code for these types and generates the XS code to map | |
223 | them. The most commonly used types are: | |
224 | ||
225 | - int | |
226 | - long | |
227 | - double | |
228 | - char* | |
229 | - void | |
230 | - SV* | |
231 | ||
232 | If you need to deal with a type that is not in the defaults, just | |
233 | use the generic C<SV*> type in the function definition. Then inside | |
234 | your code, do the mapping yourself. Alternatively, you can create | |
235 | your own typemap files and specify them using the C<TYPEMAPS> | |
236 | configuration option. | |
237 | ||
238 | A return type of C<void> has a special meaning to Inline. It means that | |
239 | you plan to push the values back onto the B<Stack> yourself. This is | |
240 | what you need to do to return a list of values. If you really don't want | |
241 | to return anything (the traditional meaning of C<void>) then simply | |
242 | don't push anything back. | |
243 | ||
244 | If ellipsis or C<...> is used at the end of an argument list, it means | |
245 | that any number of C<SV*>s may follow. Again you will need to pop the | |
246 | values off of the C<Stack> yourself. | |
247 | ||
248 | See L<"Examples"> below. | |
249 | ||
250 | =head1 The Inline Stack Macros | |
251 | ||
252 | When you write Inline C, the following lines are automatically prepended | |
253 | to your code (by default): | |
254 | ||
255 | #include "EXTERN.h" | |
256 | #include "perl.h" | |
257 | #include "XSUB.h" | |
258 | #include "INLINE.h" | |
259 | ||
260 | The file C<INLINE.h> defines a set of macros that are useful for | |
261 | handling the Perl Stack from your C functions. | |
262 | ||
263 | =over 4 | |
264 | ||
265 | =item Inline_Stack_Vars | |
266 | ||
267 | You'll need to use this one, if you want to use the others. It sets up a | |
268 | few local variables: C<sp>, C<items>, C<ax> and C<mark>, for use by the | |
269 | other macros. It's not important to know what they do, but I mention | |
270 | them to avoid possible name conflicts. | |
271 | ||
272 | NOTE: | |
273 | Since this macro declares variables, you'll need to put it with your | |
274 | other variable declarations at the top of your function. It must | |
275 | come before any executable statements and before any other | |
276 | C<Inline_Stack> macros. | |
277 | ||
278 | =item Inline_Stack_Items | |
279 | ||
280 | Returns the number of arguments passed in on the Stack. | |
281 | ||
282 | =item Inline_Stack_Item(i) | |
283 | ||
284 | Refers to a particular C<SV*> in the Stack, where C<i> is an index | |
285 | number starting from zero. Can be used to get or set the value. | |
286 | ||
287 | =item Inline_Stack_Reset | |
288 | ||
289 | Use this before pushing anything back onto the Stack. It resets the | |
290 | internal Stack pointer to the beginning of the Stack. | |
291 | ||
292 | =item Inline_Stack_Push(sv) | |
293 | ||
294 | Push a return value back onto the Stack. The value must be of type C<SV*>. | |
295 | ||
296 | =item Inline_Stack_Done | |
297 | ||
298 | After you have pushed all of your return values, you must call this macro. | |
299 | ||
300 | =item Inline_Stack_Return(n) | |
301 | ||
302 | Return C<n> items on the Stack. | |
303 | ||
304 | =item Inline_Stack_Void | |
305 | ||
306 | A special macro to indicate that you really don't want to return | |
307 | anything. Same as: | |
308 | ||
309 | Inline_Stack_Return(0); | |
310 | ||
311 | Please note that this macro actually B<returns> from your function. | |
312 | ||
313 | =back | |
314 | ||
315 | Each of these macros is available in 3 different styles to suit your | |
316 | coding tastes. The following macros are equivalent. | |
317 | ||
318 | Inline_Stack_Vars | |
319 | inline_stack_vars | |
320 | INLINE_STACK_VARS | |
321 | ||
322 | All of this functionality is available through XS macro calls as well. | |
323 | So why duplicate the functionality? There are a few reasons why I | |
324 | decided to offer this set of macros. First, as a convenient way to | |
325 | access the Stack. Second, for consistent, self documenting, non-cryptic | |
326 | coding. Third, for future compatibility. It occured to me that if a lot | |
327 | of people started using XS macros for their C code, the interface might | |
328 | break under Perl6. By using this set, hopefully I will be able to insure | |
329 | future compatibility of argument handling. | |
330 | ||
331 | Of course, if you use the rest of the Perl API, your code will most | |
332 | likely break under Perl6. So this is not a 100% guarantee. But since | |
333 | argument handling is the most common interface you're likely to use, it | |
334 | seemed like a wise thing to do. | |
335 | ||
336 | =head1 Writing C Subroutines | |
337 | ||
338 | The definitions of your C functions will fall into one of the following | |
339 | four categories. For each category there are special considerations. | |
340 | ||
341 | =over 4 | |
342 | ||
343 | =item 1 | |
344 | ||
345 | int Foo(int arg1, char* arg2, SV* arg3) { | |
346 | ||
347 | This is the simplest case. You have a non C<void> return type and a | |
348 | fixed length argument list. You don't need to worry about much. All the | |
349 | conversions will happen automatically. | |
350 | ||
351 | =item 2 | |
352 | ||
353 | void Foo(int arg1, char* arg2, SV* arg3) { | |
354 | ||
355 | In this category you have a C<void> return type. This means that either | |
356 | you want to return nothing, or that you want to return a list. In the | |
357 | latter case you'll need to push values onto the B<Stack> yourself. There | |
358 | are a few Inline macros that make this easy. Code something like this: | |
359 | ||
360 | int i, max; SV* my_sv[10]; | |
361 | Inline_Stack_Vars; | |
362 | Inline_Stack_Reset; | |
363 | for (i = 0; i < max; i++) | |
364 | Inline_Stack_Push(my_sv[i]); | |
365 | Inline_Stack_Done; | |
366 | ||
367 | After resetting the Stack pointer, this code pushes a series of return | |
368 | values. At the end it uses C<Inline_Stack_Done> to mark the end of the | |
369 | return stack. | |
370 | ||
371 | If you really want to return nothing, then don't use the | |
372 | C<Inline_Stack_> macros. If you must use them, then set use | |
373 | C<Inline_Stack_Void> at the end of your function. | |
374 | ||
375 | =item 3 | |
376 | ||
377 | char* Foo(SV* arg1, ...) { | |
378 | ||
379 | In this category you have an unfixed number of arguments. This | |
380 | means that you'll have to pop values off the B<Stack> yourself. Do | |
381 | it like this: | |
382 | ||
383 | int i; | |
384 | Inline_Stack_Vars; | |
385 | for (i = 0; i < Inline_Stack_Items; i++) | |
386 | handle_sv(Inline_Stack_Item(i)); | |
387 | ||
388 | The return type of C<Inline_Stack_Item(i)> is C<SV*>. | |
389 | ||
390 | =item 4 | |
391 | ||
392 | void* Foo(SV* arg1, ...) { | |
393 | ||
394 | In this category you have both a C<void> return type and an | |
395 | unfixed number of arguments. Just combine the techniques from | |
396 | Categories 3 and 4. | |
397 | ||
398 | =back | |
399 | ||
400 | =head1 Examples | |
401 | ||
402 | Here are a few examples. Each one is a complete program that you can try | |
403 | running yourself. For many more examples see L<Inline::C-Cookbook>. | |
404 | ||
405 | =head2 Example #1 - Greetings | |
406 | ||
407 | This example will take one string argument (a name) and print a | |
408 | greeting. The function is called with a string and with a number. In the | |
409 | second case the number is forced to a string. | |
410 | ||
411 | Notice that you do not need to C<#include <stdio.h>>. The C<perl.h> | |
412 | header file which gets included by default, automatically loads the | |
413 | standard C header files for you. | |
414 | ||
415 | use Inline C; | |
416 | greet('Ingy'); | |
417 | greet(42); | |
418 | __END__ | |
419 | __C__ | |
420 | void greet(char* name) { | |
421 | printf("Hello %s!\n", name); | |
422 | } | |
423 | ||
424 | =head2 Example #2 - and Salutations | |
425 | ||
426 | This is similar to the last example except that the name is passed in as | |
427 | a C<SV*> (pointer to Scalar Value) rather than a string (C<char*>). That | |
428 | means we need to convert the C<SV> to a string ourselves. This is | |
429 | accomplished using the C<SvPVX> function which is part of the C<Perl> | |
430 | internal API. See C<perldoc perlapi> for more info. | |
431 | ||
432 | One problem is that C<SvPVX> doesn't automatically convert strings | |
433 | to numbers, so we get a little surprise when we try to greet C<42>. | |
434 | The program segfaults, a common occurence when delving into the | |
435 | guts of Perl. | |
436 | ||
437 | use Inline C; | |
438 | greet('Ingy'); | |
439 | greet(42); | |
440 | __END__ | |
441 | __C__ | |
442 | void greet(SV* sv_name) { | |
443 | printf("Hello %s!\n", SvPVX(sv_name)); | |
444 | } | |
445 | ||
446 | =head2 Example #3 - Fixing the problem | |
447 | ||
448 | We can fix the problem in Example #2 by using the C<SvPV> function | |
449 | instead. This function will stringify the C<SV> if it does not contain a | |
450 | string. C<SvPV> returns the length of the string as it's second | |
451 | parameter. Since we don't care about the length, we can just put | |
452 | C<PL_na> there, which is a special variable designed for that purpose. | |
453 | ||
454 | use Inline C; | |
455 | greet('Ingy'); | |
456 | greet(42); | |
457 | __END__ | |
458 | __C__ | |
459 | void greet(SV* sv_name) { | |
460 | printf("Hello %s!\n", SvPV(sv_name, PL_na)); | |
461 | } | |
462 | ||
463 | =head1 SEE ALSO | |
464 | ||
465 | For general information about Inline see L<Inline>. | |
466 | ||
467 | For sample programs using Inline with C see L<Inline::C-Cookbook>. | |
468 | ||
469 | For information on supported languages and platforms see | |
470 | L<Inline-Support>. | |
471 | ||
472 | For information on writing your own Inline Language Support Module, see | |
473 | L<Inline-API>. | |
474 | ||
475 | Inline's mailing list is inline@perl.org | |
476 | ||
477 | To subscribe, send email to inline-subscribe@perl.org | |
478 | ||
479 | =head1 BUGS AND DEFICIENCIES | |
480 | ||
481 | =over 4 | |
482 | ||
483 | =item 1 | |
484 | ||
485 | If you use C function names that happen to be used internally by Perl, | |
486 | you will get a load error at run time. There is currently no | |
487 | functionality to prevent this or to warn you. For now, a list of Perl's | |
488 | internal symbols is packaged in the Inline module distribution under the | |
489 | filename C<'symbols.perl'>. Avoid using these in your code. | |
490 | ||
491 | =back | |
492 | ||
493 | =head1 AUTHOR | |
494 | ||
495 | Brian Ingerson <INGY@cpan.org> | |
496 | ||
497 | =head1 COPYRIGHT | |
498 | ||
499 | Copyright (c) 2000, 2001, 2002. Brian Ingerson. All rights reserved. | |
500 | ||
501 | This program is free software; you can redistribute it and/or modify it | |
502 | under the same terms as Perl itself. | |
503 | ||
504 | See http://www.perl.com/perl/misc/Artistic.html | |
505 | ||
506 | =cut |