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