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
11 languages 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
17 general, see Inline.
18
20 You never actually use "Inline::C" directly. It is just a support
21 module 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
34 subroutine. If the signature is not recognized, Inline will simply
35 ignore it, with no complaints. It will not be available from Perl-
36 space, 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 void Foo(SV*, ...) {
54 long Foo(int i, int j, ...) {
55 SV* Foo(void) { # 'void' arg invalid with the ParseRecDescent parser.
56 # Works only with the ParseRegExp parser.
57 # See the section on USING (below).
58 SV* Foo() { # Alternative to specifying 'void' arg. Is valid with
59 # both the ParseRecDescent and ParseRegExp parsers.
60 The following definitions would not be recognized:
62 Foo(int i) { # no return type
64 int Foo(float f) { # no (default) typemap for float
65 int Foo(num, str) double num; char* str; {
66 Notice that Inline only looks for function definitions, not function
68 prototypes. Definitions are the syntax directly preceding a function
69 body. Also Inline does not scan external files, like headers. Only the
70 code passed to Inline is used to create bindings; although other
71 libraries can linked in, and called from C-space.
72
74 For information on how to specify Inline configuration options, see
75 Inline. This section describes each of the configuration options
76 available for C. Most of the options correspond either to MakeMaker or
77 XS options of the same name. See ExtUtils::MakeMaker and perlxs.
78 AUTO_INCLUDE
80 Specifies extra statements to automatically included. They will be
81 added onto the defaults. A newline char will be automatically added.
82 use Inline C => Config => AUTO_INCLUDE => '#include "yourheader.h"';
84 AUTOWRAP
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 This is similar to the base functionality you get from "h2xs". It can
93 be very useful for binding to external libraries.
94 BOOT
96 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.
101 CCFLAGS
103 Specify compiler flags - same as ExtUtils::MakeMaker's CCFLAGS option.
104 Whatever gets specified here replaces the default $Config{ccflags}.
105 Often, you'll want to add an extra flag or two without clobbering the
106 default flags in which case you could instead use CCFLAGSEX (see below)
107 or, iff Config.pm has already been loaded:
108 use Inline C => Config => CCFLAGS => $Config{ccflags} . " -DXTRA -DTOO";
110 CCFLAGSEX
112 Extend compiler flags. Sets CCFLAGS to $Config{ccflags} followed by a
113 space, followed by the specified value:
114 use Inline C => Config => CCFLAGSEX => "-DXTRA -DTOO";
116 FILTERS
118 Allows you to specify a list of source code filters. If more than one
119 is requested, be sure to group them with an array ref. The filters can
120 either be subroutine references or names of filters provided by the
121 supplementary Inline::Filters module.
122 Your source code will be filtered just before it is parsed by Inline.
124 The MD5 fingerprint is generated before filtering. Source code filters
125 can be used to do things like stripping out POD documentation, pre-
126 expanding #include statements or whatever else you please. For example:
127 use Inline C => DATA =>
129 FILTERS => [Strip_POD => \&MyFilter => Preprocess ];
130 Filters are invoked in the order specified. See Inline::Filters for
132 more information.
133 INC
135 Specifies an include path to use. Corresponds to the MakeMaker
136 parameter. Expects a fully qualified path.
137 use Inline C => Config => INC => '-I/inc/path';
139 LD
141 Specify which linker to use.
142 LDDLFLAGS
144 Specify which linker flags to use.
145 NOTE: These flags will completely override the existing flags, instead
147 of just adding to them. So if you need to use those too, you must
148 respecify them here.
149 LIBS
151 Specifies external libraries that should be linked into your code.
152 Corresponds to the MakeMaker parameter. Provide a fully qualified path
153 with the -L switch if the library is in a location where it won't be
154 found automatically.
155 use Inline C => Config => LIBS => '-lyourlib';
157 or
159 use Inline C => Config => LIBS => '-L/your/path -lyourlib';
161 MAKE
163 Specify the name of the 'make' utility to use.
164 MYEXTLIB
166 Specifies a user compiled object that should be linked in. Corresponds
167 to the MakeMaker parameter. Expects a fully qualified path.
168 use Inline C => Config => MYEXTLIB => '/your/path/yourmodule.so';
170 OPTIMIZE
172 This controls the MakeMaker OPTIMIZE setting. By setting this value to
173 '-g', you can turn on debugging support for your Inline extensions.
174 This will allow you to be able to set breakpoints in your C code using
175 a debugger like gdb.
176 PREFIX
178 Specifies a prefix that will be automatically stripped from C functions
179 when they are bound to Perl. Useful for creating wrappers for shared
180 library API-s, and binding to the original names in Perl. Also useful
181 when names conflict with Perl internals. Corresponds to the XS
182 parameter.
183 use Inline C => Config => PREFIX => 'ZLIB_';
185 PRE_HEAD
187 Specifies code that will precede the inclusion of all files specified
188 in AUTO_INCLUDE (ie EXTERN.h, perl.h, XSUB.h, INLINE.h and anything
189 else that might have been added to AUTO_INCLUDE by the user). If the
190 specified value identifies a file, the contents of that file will be
191 inserted, otherwise the specified value is inserted.
192 use Inline C => Config => PRE_HEAD => $code_or_filename;
194 TYPEMAPS
196 Specifies extra typemap files to use. These types will modify the
197 behaviour of the C parsing. Corresponds to the MakeMaker parameter.
198 Specify either a fully qualified path or a path relative to the cwd (ie
199 relative to what the cwd is at the time the script is loaded).
200 use Inline C => Config => TYPEMAPS => '/your/path/typemap';
202 USING
204 Specifies which parser to use. Default is 'ParseRecDescent', which uses
205 the Parse::RecDescent module. The only other option is 'ParseRegExp',
206 which uses the Inline::C::ParseRegExp module that ships with Inline.
207 use Inline C => Config => USING => 'ParseRegExp';
209
211 This section describes how the "Perl" variables get mapped to "C"
212 variables and back again.
213 First, you need to know how "Perl" passes arguments back and forth to
215 subroutines. Basically it uses a stack (also known as the Stack). When
216 a sub is called, all of the parenthesized arguments get expanded into a
217 list of scalars and pushed onto the Stack. The subroutine then pops all
218 of its parameters off of the Stack. When the sub is done, it pushes all
219 of its return values back onto the Stack.
220 The Stack is an array of scalars known internally as "SV"'s. The Stack
222 is actually an array of pointers to SV or "SV*"; therefore every
223 element of the Stack is natively a "SV*". For FMTYEWTK about this, read
224 "perldoc perlguts".
225 So back to variable mapping. XS uses a thing known as "typemaps" to
227 turn each "SV*" into a "C" type and back again. This is done through
228 various XS macro calls, casts and the Perl API. See "perldoc perlapi".
229 XS allows you to define your own typemaps as well for fancier non-
230 standard types such as "typedef"-ed structs.
231 Inline uses the default Perl typemap file for its default types. This
233 file is called "/usr/local/lib/perl5/5.6.1/ExtUtils/typemap", or
234 something similar, depending on your Perl installation. It has
235 definitions for over 40 types, which are automatically used by Inline.
236 (You should probably browse this file at least once, just to get an
237 idea of the possibilities.)
238 Inline parses your code for these types and generates the XS code to
240 map them. The most commonly used types are:
241 - int
243 - long
244 - double
245 - char*
246 - void
247 - SV*
248 If you need to deal with a type that is not in the defaults, just use
250 the generic "SV*" type in the function definition. Then inside your
251 code, do the mapping yourself. Alternatively, you can create your own
252 typemap files and specify them using the "TYPEMAPS" configuration
253 option.
254 A return type of "void" has a special meaning to Inline. It means that
256 you plan to push the values back onto the Stack yourself. This is what
257 you need to do to return a list of values. If you really don't want to
258 return anything (the traditional meaning of "void") then simply don't
259 push anything back.
260 If ellipsis or "..." is used at the end of an argument list, it means
262 that any number of "SV*"s may follow. Again you will need to pop the
263 values off of the "Stack" yourself.
264 See "Examples" below.
266
268 When you write Inline C, the following lines are automatically
269 prepended to your code (by default):
270 #include "EXTERN.h"
272 #include "perl.h"
273 #include "XSUB.h"
274 #include "INLINE.h"
275 The file "INLINE.h" defines a set of macros that are useful for
277 handling the Perl Stack from your C functions.
278 Inline_Stack_Vars
280 You'll need to use this one, if you want to use the others. It sets
281 up a few local variables: "sp", "items", "ax" and "mark", for use
282 by the other macros. It's not important to know what they do, but I
283 mention them to avoid possible name conflicts.
284 NOTE: Since this macro declares variables, you'll need to put it
286 with your other variable declarations at the top of your function.
287 It must come before any executable statements and before any other
288 "Inline_Stack" macros.
289 Inline_Stack_Items
291 Returns the number of arguments passed in on the Stack.
292 Inline_Stack_Item(i)
294 Refers to a particular "SV*" in the Stack, where "i" is an index
295 number starting from zero. Can be used to get or set the value.
296 Inline_Stack_Reset
298 Use this before pushing anything back onto the Stack. It resets the
299 internal Stack pointer to the beginning of the Stack.
300 Inline_Stack_Push(sv)
302 Push a return value back onto the Stack. The value must be of type
303 "SV*".
304 Inline_Stack_Done
306 After you have pushed all of your return values, you must call this
307 macro.
308 Inline_Stack_Return(n)
310 Return "n" items on the Stack.
311 Inline_Stack_Void
313 A special macro to indicate that you really don't want to return
314 anything. Same as:
315 Inline_Stack_Return(0);
317 Please note that this macro actually returns from your function.
319 Each of these macros is available in 3 different styles to suit your
321 coding tastes. The following macros are equivalent.
322 Inline_Stack_Vars
324 inline_stack_vars
325 INLINE_STACK_VARS
326 All of this functionality is available through XS macro calls as well.
328 So why duplicate the functionality? There are a few reasons why I
329 decided to offer this set of macros. First, as a convenient way to
330 access the Stack. Second, for consistent, self documenting, non-cryptic
331 coding. Third, for future compatibility. It occured to me that if a lot
332 of people started using XS macros for their C code, the interface might
333 break under Perl6. By using this set, hopefully I will be able to
334 insure future compatibility of argument handling.
335 Of course, if you use the rest of the Perl API, your code will most
337 likely break under Perl6. So this is not a 100% guarantee. But since
338 argument handling is the most common interface you're likely to use, it
339 seemed like a wise thing to do.
340
342 The definitions of your C functions will fall into one of the following
343 four categories. For each category there are special considerations.
344 1.
346 int Foo(int arg1, char* arg2, SV* arg3) {
347 This is the simplest case. You have a non "void" return type and a
349 fixed length argument list. You don't need to worry about much. All
350 the conversions will happen automatically.
351 2.
353 void Foo(int arg1, char* arg2, SV* arg3) {
354 In this category you have a "void" return type. This means that
356 either you want to return nothing, or that you want to return a
357 list. In the latter case you'll need to push values onto the Stack
358 yourself. There are a few Inline macros that make this easy. Code
359 something like this:
360 int i, max; SV* my_sv[10];
362 Inline_Stack_Vars;
363 Inline_Stack_Reset;
364 for (i = 0; i < max; i++)
365 Inline_Stack_Push(my_sv[i]);
366 Inline_Stack_Done;
367 After resetting the Stack pointer, this code pushes a series of
369 return values. At the end it uses "Inline_Stack_Done" to mark the
370 end of the return stack.
371 If you really want to return nothing, then don't use the
373 "Inline_Stack_" macros. If you must use them, then set use
374 "Inline_Stack_Void" at the end of your function.
375 3.
377 char* Foo(SV* arg1, ...) {
378 In this category you have an unfixed number of arguments. This
380 means that you'll have to pop values off the Stack yourself. Do it
381 like this:
382 int i;
384 Inline_Stack_Vars;
385 for (i = 0; i < Inline_Stack_Items; i++)
386 handle_sv(Inline_Stack_Item(i));
387 The return type of Inline_Stack_Item(i) is "SV*".
389 4.
391 void* Foo(SV* arg1, ...) {
392 In this category you have both a "void" return type and an unfixed
394 number of arguments. Just combine the techniques from Categories 3
395 and 4.
396
398 Here are a few examples. Each one is a complete program that you can
399 try running yourself. For many more examples see Inline::C-Cookbook.
400 Example #1 - Greetings
402 This example will take one string argument (a name) and print a
403 greeting. The function is called with a string and with a number. In
404 the second case the number is forced to a string.
405 Notice that you do not need to "#include <stdio.h">. The "perl.h"
407 header file which gets included by default, automatically loads the
408 standard C header files for you.
409 use Inline C;
411 greet('Ingy');
412 greet(42);
413 __END__
414 __C__
415 void greet(char* name) {
416 printf("Hello %s!\n", name);
417 }
418 Example #2 - and Salutations
420 This is similar to the last example except that the name is passed in
421 as a "SV*" (pointer to Scalar Value) rather than a string ("char*").
422 That means we need to convert the "SV" to a string ourselves. This is
423 accomplished using the "SvPVX" function which is part of the "Perl"
424 internal API. See "perldoc perlapi" for more info.
425 One problem is that "SvPVX" doesn't automatically convert strings to
427 numbers, so we get a little surprise when we try to greet 42. The
428 program segfaults, a common occurence when delving into the guts of
429 Perl.
430 use Inline C;
432 greet('Ingy');
433 greet(42);
434 __END__
435 __C__
436 void greet(SV* sv_name) {
437 printf("Hello %s!\n", SvPVX(sv_name));
438 }
439 Example #3 - Fixing the problem
441 We can fix the problem in Example #2 by using the "SvPV" function
442 instead. This function will stringify the "SV" if it does not contain a
443 string. "SvPV" returns the length of the string as it's second
444 parameter. Since we don't care about the length, we can just put
445 "PL_na" there, which is a special variable designed for that purpose.
446 use Inline C;
448 greet('Ingy');
449 greet(42);
450 __END__
451 __C__
452 void greet(SV* sv_name) {
453 printf("Hello %s!\n", SvPV(sv_name, PL_na));
454 }
455
457 For general information about Inline see Inline.
458 For sample programs using Inline with C see Inline::C-Cookbook.
460 For information on supported languages and platforms see Inline-
462 Support.
463 For information on writing your own Inline Language Support Module, see
465 Inline-API.
466 Inline's mailing list is inline@perl.org
468 To subscribe, send email to inline-subscribe@perl.org
470
472 1. If you use C function names that happen to be used internally by
473 Perl, you will get a load error at run time. There is currently no
474 functionality to prevent this or to warn you. For now, a list of
475 Perl's internal symbols is packaged in the Inline module
476 distribution under the filename 'symbols.perl'. Avoid using these
477 in your code.
478
480 Brian Ingerson <INGY@cpan.org>
481 Sisyphus <sisyphus@cpan.org> fixed some bugs and is current co-
483 maintainer.
484
486 Copyright (c) 2000-2002. Brian Ingerson.
487 Copyright (c) 2008, 2010-2012. Sisyphus.
489 This program is free software; you can redistribute it and/or modify it
491 under the same terms as Perl itself.
492 See http://www.perl.com/perl/misc/Artistic.html
494perl v5.16.3 2012-11-20 C(3)