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 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
73 available for C. Most of the options correspond either to MakeMaker or
74 XS options of the same name. See ExtUtils::MakeMaker and perlxs.
75 AUTO_INCLUDE
77 Specifies extra statements to automatically included. They will be
78 added onto the defaults. A newline char will be automatically added.
79 use Inline C => Config => AUTO_INCLUDE => '#include "yourheader.h"';
81 AUTOWRAP
83 If you 'ENABLE => AUTOWRAP', Inline::C will parse function declarations
84 (prototype statements) in your C code. For each declaration it can bind
85 to, it will create a dummy wrapper that will call the real function
86 which may be in an external library. This is a nice convenience for
87 functions that would otherwise just require an empty wrapper function.
88 This is similar to the base functionality you get from "h2xs". It can
90 be very useful for binding to external libraries.
91 BOOT
93 Specifies C code to be executed in the XS BOOT section. Corresponds to
94 the XS parameter.
95 CC
97 Specify which compiler to use.
98 CCFLAGS
100 Specify extra compiler flags.
101 FILTERS
103 Allows you to specify a list of source code filters. If more than one
104 is requested, be sure to group them with an array ref. The filters can
105 either be subroutine references or names of filters provided by the
106 supplementary Inline::Filters module.
107 Your source code will be filtered just before it is parsed by Inline.
109 The MD5 fingerprint is generated before filtering. Source code filters
110 can be used to do things like stripping out POD documentation, pre-
111 expanding #include statements or whatever else you please. For example:
112 use Inline C => DATA =>
114 FILTERS => [Strip_POD => \&MyFilter => Preprocess ];
115 Filters are invoked in the order specified. See Inline::Filters for
117 more information.
118 INC
120 Specifies an include path to use. Corresponds to the MakeMaker
121 parameter. Expects a fully qualified path.
122 use Inline C => Config => INC => '-I/inc/path';
124 LD
126 Specify which linker to use.
127 LDDLFLAGS
129 Specify which linker flags to use.
130 NOTE: These flags will completely override the existing flags, instead
132 of just adding to them. So if you need to use those too, you must
133 respecify them here.
134 LIBS
136 Specifies external libraries that should be linked into your code.
137 Corresponds to the MakeMaker parameter. Provide a fully qualified path
138 with the -L switch if the library is in a location where it won't be
139 found automatically.
140 use Inline C => Config => LIBS => '-lyourlib';
142 or
144 use Inline C => Config => LIBS => '-L/your/path -lyourlib';
146 MAKE
148 Specify the name of the 'make' utility to use.
149 MYEXTLIB
151 Specifies a user compiled object that should be linked in. Corresponds
152 to the MakeMaker parameter. Expects a fully qualified path.
153 use Inline C => Config => MYEXTLIB => '/your/path/yourmodule.so';
155 OPTIMIZE
157 This controls the MakeMaker OPTIMIZE setting. By setting this value to
158 '-g', you can turn on debugging support for your Inline extensions.
159 This will allow you to be able to set breakpoints in your C code using
160 a debugger like gdb.
161 PREFIX
163 Specifies a prefix that will be automatically stripped from C functions
164 when they are bound to Perl. Useful for creating wrappers for shared
165 library API-s, and binding to the original names in Perl. Also useful
166 when names conflict with Perl internals. Corresponds to the XS
167 parameter.
168 use Inline C => Config => PREFIX => 'ZLIB_';
170 TYPEMAPS
172 Specifies extra typemap files to use. These types will modify the
173 behaviour of the C parsing. Corresponds to the MakeMaker parameter.
174 Expects a fully qualified path.
175 use Inline C => Config => TYPEMAPS => '/your/path/typemap';
177
179 This section describes how the "Perl" variables get mapped to "C"
180 variables and back again.
181 First, you need to know how "Perl" passes arguments back and forth to
183 subroutines. Basically it uses a stack (also known as the Stack). When
184 a sub is called, all of the parenthesized arguments get expanded into a
185 list of scalars and pushed onto the Stack. The subroutine then pops all
186 of its parameters off of the Stack. When the sub is done, it pushes all
187 of its return values back onto the Stack.
188 The Stack is an array of scalars known internally as "SV"'s. The Stack
190 is actually an array of pointers to SV or "SV*"; therefore every
191 element of the Stack is natively a "SV*". For FMTYEWTK about this, read
192 "perldoc perlguts".
193 So back to variable mapping. XS uses a thing known as "typemaps" to
195 turn each "SV*" into a "C" type and back again. This is done through
196 various XS macro calls, casts and the Perl API. See "perldoc perlapi".
197 XS allows you to define your own typemaps as well for fancier non-
198 standard types such as "typedef"-ed structs.
199 Inline uses the default Perl typemap file for its default types. This
201 file is called "/usr/local/lib/perl5/5.6.1/ExtUtils/typemap", or
202 something similar, depending on your Perl installation. It has
203 definitions for over 40 types, which are automatically used by Inline.
204 (You should probably browse this file at least once, just to get an
205 idea of the possibilities.)
206 Inline parses your code for these types and generates the XS code to
208 map them. The most commonly used types are:
209 - int
211 - long
212 - double
213 - char*
214 - void
215 - SV*
216 If you need to deal with a type that is not in the defaults, just use
218 the generic "SV*" type in the function definition. Then inside your
219 code, do the mapping yourself. Alternatively, you can create your own
220 typemap files and specify them using the "TYPEMAPS" configuration
221 option.
222 A return type of "void" has a special meaning to Inline. It means that
224 you plan to push the values back onto the Stack yourself. This is what
225 you need to do to return a list of values. If you really don't want to
226 return anything (the traditional meaning of "void") then simply don't
227 push anything back.
228 If ellipsis or "..." is used at the end of an argument list, it means
230 that any number of "SV*"s may follow. Again you will need to pop the
231 values off of the "Stack" yourself.
232 See "Examples" below.
234
236 When you write Inline C, the following lines are automatically
237 prepended to your code (by default):
238 #include "EXTERN.h"
240 #include "perl.h"
241 #include "XSUB.h"
242 #include "INLINE.h"
243 The file "INLINE.h" defines a set of macros that are useful for
245 handling the Perl Stack from your C functions.
246 Inline_Stack_Vars
248 You'll need to use this one, if you want to use the others. It sets
249 up a few local variables: "sp", "items", "ax" and "mark", for use
250 by the other macros. It's not important to know what they do, but I
251 mention them to avoid possible name conflicts.
252 NOTE: Since this macro declares variables, you'll need to put it
254 with your other variable declarations at the top of your function.
255 It must come before any executable statements and before any other
256 "Inline_Stack" macros.
257 Inline_Stack_Items
259 Returns the number of arguments passed in on the Stack.
260 Inline_Stack_Item(i)
262 Refers to a particular "SV*" in the Stack, where "i" is an index
263 number starting from zero. Can be used to get or set the value.
264 Inline_Stack_Reset
266 Use this before pushing anything back onto the Stack. It resets the
267 internal Stack pointer to the beginning of the Stack.
268 Inline_Stack_Push(sv)
270 Push a return value back onto the Stack. The value must be of type
271 "SV*".
272 Inline_Stack_Done
274 After you have pushed all of your return values, you must call this
275 macro.
276 Inline_Stack_Return(n)
278 Return "n" items on the Stack.
279 Inline_Stack_Void
281 A special macro to indicate that you really don't want to return
282 anything. Same as:
283 Inline_Stack_Return(0);
285 Please note that this macro actually returns from your function.
287 Each of these macros is available in 3 different styles to suit your
289 coding tastes. The following macros are equivalent.
290 Inline_Stack_Vars
292 inline_stack_vars
293 INLINE_STACK_VARS
294 All of this functionality is available through XS macro calls as well.
296 So why duplicate the functionality? There are a few reasons why I
297 decided to offer this set of macros. First, as a convenient way to
298 access the Stack. Second, for consistent, self documenting, non-cryptic
299 coding. Third, for future compatibility. It occured to me that if a lot
300 of people started using XS macros for their C code, the interface might
301 break under Perl6. By using this set, hopefully I will be able to
302 insure future compatibility of argument handling.
303 Of course, if you use the rest of the Perl API, your code will most
305 likely break under Perl6. So this is not a 100% guarantee. But since
306 argument handling is the most common interface you're likely to use, it
307 seemed like a wise thing to do.
308
310 The definitions of your C functions will fall into one of the following
311 four categories. For each category there are special considerations.
312 1.
314 int Foo(int arg1, char* arg2, SV* arg3) {
315 This is the simplest case. You have a non "void" return type and a
317 fixed length argument list. You don't need to worry about much. All
318 the conversions will happen automatically.
319 2.
321 void Foo(int arg1, char* arg2, SV* arg3) {
322 In this category you have a "void" return type. This means that
324 either you want to return nothing, or that you want to return a
325 list. In the latter case you'll need to push values onto the Stack
326 yourself. There are a few Inline macros that make this easy. Code
327 something like this:
328 int i, max; SV* my_sv[10];
330 Inline_Stack_Vars;
331 Inline_Stack_Reset;
332 for (i = 0; i < max; i++)
333 Inline_Stack_Push(my_sv[i]);
334 Inline_Stack_Done;
335 After resetting the Stack pointer, this code pushes a series of
337 return values. At the end it uses "Inline_Stack_Done" to mark the
338 end of the return stack.
339 If you really want to return nothing, then don't use the
341 "Inline_Stack_" macros. If you must use them, then set use
342 "Inline_Stack_Void" at the end of your function.
343 3.
345 char* Foo(SV* arg1, ...) {
346 In this category you have an unfixed number of arguments. This
348 means that you'll have to pop values off the Stack yourself. Do it
349 like this:
350 int i;
352 Inline_Stack_Vars;
353 for (i = 0; i < Inline_Stack_Items; i++)
354 handle_sv(Inline_Stack_Item(i));
355 The return type of Inline_Stack_Item(i) is "SV*".
357 4.
359 void* Foo(SV* arg1, ...) {
360 In this category you have both a "void" return type and an unfixed
362 number of arguments. Just combine the techniques from Categories 3
363 and 4.
364
366 Here are a few examples. Each one is a complete program that you can
367 try running yourself. For many more examples see Inline::C-Cookbook.
368 Example #1 - Greetings
370 This example will take one string argument (a name) and print a
371 greeting. The function is called with a string and with a number. In
372 the second case the number is forced to a string.
373 Notice that you do not need to "#include <stdio.h">. The "perl.h"
375 header file which gets included by default, automatically loads the
376 standard C header files for you.
377 use Inline C;
379 greet('Ingy');
380 greet(42);
381 __END__
382 __C__
383 void greet(char* name) {
384 printf("Hello %s!\n", name);
385 }
386 Example #2 - and Salutations
388 This is similar to the last example except that the name is passed in
389 as a "SV*" (pointer to Scalar Value) rather than a string ("char*").
390 That means we need to convert the "SV" to a string ourselves. This is
391 accomplished using the "SvPVX" function which is part of the "Perl"
392 internal API. See "perldoc perlapi" for more info.
393 One problem is that "SvPVX" doesn't automatically convert strings to
395 numbers, so we get a little surprise when we try to greet 42. The
396 program segfaults, a common occurence when delving into the guts of
397 Perl.
398 use Inline C;
400 greet('Ingy');
401 greet(42);
402 __END__
403 __C__
404 void greet(SV* sv_name) {
405 printf("Hello %s!\n", SvPVX(sv_name));
406 }
407 Example #3 - Fixing the problem
409 We can fix the problem in Example #2 by using the "SvPV" function
410 instead. This function will stringify the "SV" if it does not contain a
411 string. "SvPV" returns the length of the string as it's second
412 parameter. Since we don't care about the length, we can just put
413 "PL_na" there, which is a special variable designed for that purpose.
414 use Inline C;
416 greet('Ingy');
417 greet(42);
418 __END__
419 __C__
420 void greet(SV* sv_name) {
421 printf("Hello %s!\n", SvPV(sv_name, PL_na));
422 }
423
425 For general information about Inline see Inline.
426 For sample programs using Inline with C see Inline::C-Cookbook.
428 For information on supported languages and platforms see Inline-
430 Support.
431 For information on writing your own Inline Language Support Module, see
433 Inline-API.
434 Inline's mailing list is inline@perl.org
436 To subscribe, send email to inline-subscribe@perl.org
438
440 1. If you use C function names that happen to be used internally by
441 Perl, you will get a load error at run time. There is currently no
442 functionality to prevent this or to warn you. For now, a list of
443 Perl's internal symbols is packaged in the Inline module
444 distribution under the filename 'symbols.perl'. Avoid using these
445 in your code.
446
448 Brian Ingerson <INGY@cpan.org>
449 Sisyphus <sisyphus@cpan.org> fixed some bugs and is current co-
451 maintainer.
452
454 Copyright (c) 2000, 2001, 2002. Brian Ingerson. All rights reserved.
455 This program is free software; you can redistribute it and/or modify it
457 under the same terms as Perl itself.
458 See http://www.perl.com/perl/misc/Artistic.html
460perl v5.12.1 2010-01-27 C(3)