1Inline::C(3) User Contributed Perl Documentation Inline::C(3)
2
6 Inline::C - C Language Support for Inline
7
9 This document describes Inline::C version 0.81.
10
12 "Inline::C" is a module that allows you to write Perl subroutines in C.
13 Since version 0.30 the Inline module supports multiple programming
14 languages and each language has its own support module. This document
15 describes how to use Inline with the C programming language. It also
16 goes a bit into Perl C internals.
17 If you want to start working with programming examples right away,
19 check out Inline::C::Cookbook. For more information on Inline in
20 general, see Inline.
21
23 You never actually use "Inline::C" directly. It is just a support
24 module for using "Inline.pm" with C. So the usage is always:
25 use Inline C => ...;
27 or
29 bind Inline C => ...;
31
33 The Inline grammar for C recognizes certain function definitions (or
34 signatures) in your C code. If a signature is recognized by Inline,
35 then it will be available in Perl-space. That is, Inline will generate
36 the "glue" necessary to call that function as if it were a Perl
37 subroutine. If the signature is not recognized, Inline will simply
38 ignore it, with no complaints. It will not be available from Perl-
39 space, although it will be available from C-space.
40 Inline looks for ANSI/prototype style function definitions. They must
42 be of the form:
43 return-type function-name ( type-name-pairs ) { ... }
45 The most common types are: "int", "long", "double", "char*", and "SV*".
47 But you can use any type for which Inline can find a typemap. Inline
48 uses the "typemap" file distributed with Perl as the default. You can
49 specify more typemaps with the "typemaps" configuration option.
50 A return type of "void" may also be used. The following are examples of
52 valid function definitions.
53 int Foo(double num, char* str) {
55 void Foo(double num, char* str) {
56 void Foo(SV*, ...) {
57 long Foo(int i, int j, ...) {
58 SV* Foo(void) { # 'void' arg invalid with the ParseRecDescent parser.
59 # Works only with the ParseRegExp parser.
60 # See the section on `using` (below).
61 SV* Foo() { # Alternative to specifying 'void' arg. Is valid with
62 # both the ParseRecDescent and ParseRegExp parsers.
63 The following definitions would not be recognized:
65 Foo(int i) { # no return type
67 int Foo(float f) { # no (default) typemap for float
68 int Foo(num, str) double num; char* str; {
69 Notice that Inline only looks for function definitions, not function
71 prototypes. Definitions are the syntax directly preceding a function
72 body. Also Inline does not scan external files, like headers. Only the
73 code passed to Inline is used to create bindings; although other
74 libraries can linked in, and called from C-space.
75
77 For information on how to specify Inline configuration options, see
78 Inline. This section describes each of the configuration options
79 available for C. Most of the options correspond either to MakeMaker or
80 XS options of the same name. See ExtUtils::MakeMaker and perlxs.
81 "auto_include"
83 Specifies extra statements to automatically included. They will be
84 added onto the defaults. A newline char will be automatically
85 added.
86 use Inline C => config => auto_include => '#include "yourheader.h"';
88 "autowrap"
90 If you "enable => autowrap", Inline::C will parse function
91 declarations (prototype statements) in your C code. For each
92 declaration it can bind to, it will create a dummy wrapper that
93 will call the real function which may be in an external library.
94 This is a nice convenience for functions that would otherwise just
95 require an empty wrapper function.
96 This is similar to the base functionality you get from "h2xs". It
98 can be very useful for binding to external libraries.
99 "boot"
101 Specifies C code to be executed in the XS "BOOT" section.
102 Corresponds to the XS parameter.
103 "cc"
105 Specify which compiler to use.
106 "ccflags"
108 Specify compiler flags - same as ExtUtils::MakeMaker's "CCFLAGS"
109 option. Whatever gets specified here replaces the default
110 $Config{ccflags}. Often, you'll want to add an extra flag or two
111 without clobbering the default flags in which case you could
112 instead use "ccflagsex" (see below) or, if Config.pm has already
113 been loaded:
114 use Inline C => Config => ccflags => $Config{ccflags} . " -DXTRA -DTOO";
116 "ccflagsex"
118 Extend compiler flags. Sets "CCFLAGS" to $Config{ccflags} followed
119 by a space, followed by the specified value:
120 use Inline C => config => ccflagsex => "-DXTRA -DTOO";
122 "cppflags"
124 Specify preprocessor flags. Passed to "cpp" C preprocessor by
126 "Preprocess()" in Inline::Filters.
127 use Inline C => <<'END',
129 CPPFLAGS => ' -DPREPROCESSOR_DEFINE',
130 FILTERS => 'Preprocess';
131 use Inline C => <<'END',
132 CPPFLAGS => ' -DPREPROCESSOR_DEFINE=4321',
133 FILTERS => 'Preprocess';
134 "filters"
136 Allows you to specify a list of source code filters. If more than
137 one is requested, be sure to group them with an array ref. The
138 filters can either be subroutine references or names of filters
139 provided by the supplementary Inline::Filters module.
140 Your source code will be filtered just before it is parsed by
142 Inline. The MD5 fingerprint is generated before filtering. Source
143 code filters can be used to do things like stripping out POD
144 documentation, pre-expanding "#include" statements or whatever else
145 you please. For example:
146 use Inline C => DATA =>
148 filters => [Strip_POD => \&MyFilter => Preprocess ];
149 Filters are invoked in the order specified. See Inline::Filters for
151 more information.
152 If a filter is an array reference, it is assumed to be a usage of a
154 filter plug- in named by the first element of that array reference.
155 The rest of the elements of the array reference are used as
156 arguments to the filter. For example, consider a "filters"
157 parameter like this:
158 use Inline C => DATA => filters => [ [ Ragel => '-G2' ] ];
160 In order for Inline::C to process this filter, it will attempt to
162 require the module Inline::Filters::Ragel and will then call the
163 "filter" function in that package with the argument '-G2'. This
164 function will return the actual filtering function.
165 "inc"
167 Specifies an include path to use. Corresponds to the MakeMaker
168 parameter. Expects a fully qualified path.
169 use Inline C => config => inc => '-I/inc/path';
171 "ld"
173 Specify which linker to use.
174 "lddlflags"
176 Specify which linker flags to use.
177 NOTE: These flags will completely override the existing flags,
179 instead of
180 just adding to them. So if you need to use those too, you
181 must
182 respecify them here.
183 "libs"
185 Specifies external libraries that should be linked into your code.
186 Corresponds to the MakeMaker parameter. Provide a fully qualified
187 path with the "-L" switch if the library is in a location where it
188 won't be found automatically.
189 use Inline C => config => libs => '-lyourlib';
191 or
193 use Inline C => config => libs => '-L/your/path -lyourlib';
195 "make"
197 Specify the name of the 'make' utility to use.
198 "myextlib"
200 Specifies a user compiled object that should be linked in.
201 Corresponds to the MakeMaker parameter. Expects a fully qualified
202 path.
203 use Inline C => config => myextlib => '/your/path/yourmodule.so';
205 "optimize"
207 This controls the MakeMaker "OPTIMIZE" setting. By setting this
208 value to '-g', you can turn on debugging support for your Inline
209 extensions. This will allow you to be able to set breakpoints in
210 your C code using a debugger like gdb.
211 "prefix"
213 Specifies a prefix that will be automatically stripped from C
214 functions when they are bound to Perl. Useful for creating wrappers
215 for shared library API-s, and binding to the original names in
216 Perl. Also useful when names conflict with Perl internals.
217 Corresponds to the XS parameter.
218 use Inline C => config => prefix => 'ZLIB_';
220 "pre_head"
222 Specifies code that will precede the inclusion of all files
223 specified in "auto_include" (ie "EXTERN.h", "perl.h", "XSUB.h",
224 "INLINE.h" and anything else that might have been added to
225 "auto_include" by the user). If the specified value identifies a
226 file, the contents of that file will be inserted, otherwise the
227 specified value is inserted.
228 use Inline C => config => pre_head => $code_or_filename;
230 "prototype"
232 Corresponds to the XS keyword 'PROTOTYPE'. See the perlxs
233 documentation for both 'PROTOTYPES' and 'PROTOTYPE'. As an example,
234 the following will set the PROTOTYPE of the 'foo' function to '$',
235 and disable prototyping for the 'bar' function.
236 use Inline C => config => prototype => {foo => '$', bar => 'DISABLE'}
238 "prototypes"
240 Corresponds to the XS keyword 'PROTOTYPES'. Can take only values of
241 'ENABLE' or 'DISABLE'. (Contrary to XS, default value is
242 'DISABLE'). See the perlxs documentation for both 'PROTOTYPES' and
243 'PROTOTYPE'.
244 use Inline C => config => prototypes => 'ENABLE';
246 "typemaps"
248 Specifies extra typemap files to use. These types will modify the
249 behaviour of the C parsing. Corresponds to the MakeMaker parameter.
250 Specify either a fully qualified path or a path relative to the cwd
251 (ie relative to what the cwd is at the time the script is loaded).
252 use Inline C => config => typemaps => '/your/path/typemap';
254 "using"
256 Specifies which parser to use. The default is
257 Inline::C::Parser::RecDescent, which uses the Parse::RecDescent
258 module.
259 The other options are "::Parser::Pegex" and "::Parser::RegExp",
261 which uses the Inline::C::Parser::Pegex and
262 Inline::C::Parser::RegExp modules that ship with Inline::C.
263 use Inline C => config => using => '::Parser::Pegex';
265 Note that the following old options are deprecated, but still work
267 at this time:
268 · "ParseRecDescent"
270 · "ParseRegExp"
272 · "ParsePegex"
274
276 This section describes how the "Perl" variables get mapped to "C"
277 variables and back again.
278 First, you need to know how "Perl" passes arguments back and forth to
280 subroutines. Basically it uses a stack (also known as the Stack). When
281 a sub is called, all of the parenthesized arguments get expanded into a
282 list of scalars and pushed onto the Stack. The subroutine then pops all
283 of its parameters off of the Stack. When the sub is done, it pushes all
284 of its return values back onto the Stack.
285 The Stack is an array of scalars known internally as "SV"'s. The Stack
287 is actually an array of pointers to SV or "SV*"; therefore every
288 element of the Stack is natively a "SV*". For FMTYEWTK about this, read
289 "perldoc perlguts".
290 So back to variable mapping. XS uses a thing known as "typemaps" to
292 turn each "SV*" into a "C" type and back again. This is done through
293 various XS macro calls, casts and the Perl API. See "perldoc perlapi".
294 XS allows you to define your own typemaps as well for fancier non-
295 standard types such as "typedef"- ed structs.
296 Inline uses the default Perl typemap file for its default types. This
298 file is called "/usr/local/lib/perl5/5.6.1/ExtUtils/typemap", or
299 something similar, depending on your Perl installation. It has
300 definitions for over 40 types, which are automatically used by Inline.
301 (You should probably browse this file at least once, just to get an
302 idea of the possibilities.)
303 Inline parses your code for these types and generates the XS code to
305 map them. The most commonly used types are:
306 · "int"
308 · "long"
310 · "double"
312 · "char*"
314 · "void"
316 · "SV*"
318 If you need to deal with a type that is not in the defaults, just use
320 the generic "SV*" type in the function definition. Then inside your
321 code, do the mapping yourself. Alternatively, you can create your own
322 typemap files and specify them using the "typemaps" configuration
323 option.
324 A return type of "void" has a special meaning to Inline. It means that
326 you plan to push the values back onto the Stack yourself. This is what
327 you need to do to return a list of values. If you really don't want to
328 return anything (the traditional meaning of "void") then simply don't
329 push anything back.
330 If ellipsis or "..." is used at the end of an argument list, it means
332 that any number of "SV*"s may follow. Again you will need to pop the
333 values off of the "Stack" yourself.
334 See "EXAMPLES" below.
336
338 When you write Inline C, the following lines are automatically
339 prepended to your code (by default):
340 #include "EXTERN.h"
342 #include "perl.h"
343 #include "XSUB.h"
344 #include "INLINE.h"
345 The file "INLINE.h" defines a set of macros that are useful for
347 handling the Perl Stack from your C functions.
348 "Inline_Stack_Vars"
350 You'll need to use this one, if you want to use the others. It sets
351 up a few local variables: "sp", "items", "ax" and "mark", for use
352 by the other macros. It's not important to know what they do, but I
353 mention them to avoid possible name conflicts.
354 NOTE: Since this macro declares variables, you'll need to put it
356 with your
357 other variable declarations at the top of your function. It
358 must
359 come before any executable statements and before any other
360 "Inline_Stack" macros.
361 "Inline_Stack_Items"
363 Returns the number of arguments passed in on the Stack.
364 Inline_Stack_Item(i)
366 Refers to a particular "SV*" in the Stack, where "i" is an index
367 number starting from zero. Can be used to get or set the value.
368 "Inline_Stack_Reset"
370 Use this before pushing anything back onto the Stack. It resets the
371 internal Stack pointer to the beginning of the Stack.
372 "Inline_Stack_Push(sv)"
374 Push a return value back onto the Stack. The value must be of type
375 "SV*".
376 "Inline_Stack_Done"
378 After you have pushed all of your return values, you must call this
379 macro.
380 Inline_Stack_Return(n)
382 Return "n" items on the Stack.
383 "Inline_Stack_Void"
385 A special macro to indicate that you really don't want to return
386 anything. Same as:
387 Inline_Stack_Return(0);
389 Please note that this macro actually returns from your function.
391 Each of these macros is available in 3 different styles to suit your
393 coding tastes. The following macros are equivalent.
394 Inline_Stack_Vars
396 inline_stack_vars
397 INLINE_STACK_VARS
398 All of this functionality is available through XS macro calls as well.
400 So why duplicate the functionality? There are a few reasons why I
401 decided to offer this set of macros. First, as a convenient way to
402 access the Stack. Second, for consistent, self documenting, non-
403 cryptic coding. Third, for future compatibility. It occurred to me that
404 if a lot of people started using XS macros for their C code, the
405 interface might break under Perl6. By using this set, hopefully I will
406 be able to insure future compatibility of argument handling.
407 Of course, if you use the rest of the Perl API, your code will most
409 likely break under Perl6. So this is not a 100% guarantee. But since
410 argument handling is the most common interface you're likely to use, it
411 seemed like a wise thing to do.
412
414 The definitions of your C functions will fall into one of the following
415 four categories. For each category there are special considerations.
416 "int Foo(int arg1, char* arg2, SV* arg3) {"
418 This is the simplest case. You have a non "void" return type and a
419 fixed length argument list. You don't need to worry about much. All
420 the conversions will happen automatically.
421 "void Foo(int arg1, char* arg2, SV* arg3) {"
423 In this category you have a "void" return type. This means that
424 either you want to return nothing, or that you want to return a
425 list. In the latter case you'll need to push values onto the Stack
426 yourself. There are a few Inline macros that make this easy. Code
427 something like this:
428 int i, max; SV* my_sv[10];
430 Inline_Stack_Vars;
431 Inline_Stack_Reset;
432 for (i = 0; i < max; i++)
433 Inline_Stack_Push(my_sv[i]);
434 Inline_Stack_Done;
435 After resetting the Stack pointer, this code pushes a series of
437 return values. At the end it uses "Inline_Stack_Done" to mark the
438 end of the return stack.
439 If you really want to return nothing, then don't use the
441 "Inline_Stack_" macros. If you must use them, then set use
442 "Inline_Stack_Void" at the end of your function.
443 "char* Foo(SV* arg1, ...) {"
445 In this category you have an unfixed number of arguments. This
446 means that you'll have to pop values off the Stack yourself. Do it
447 like this:
448 int i;
450 Inline_Stack_Vars;
451 for (i = 0; i < Inline_Stack_Items; i++)
452 handle_sv(Inline_Stack_Item(i));
453 The return type of Inline_Stack_Item(i) is "SV*".
455 "void* Foo(SV* arg1, ...) {"
457 In this category you have both a "void" return type and an unfixed
458 number of arguments. Just combine the techniques from Categories 3
459 and 4.
460
462 Here are a few examples. Each one is a complete program that you can
463 try running yourself. For many more examples see Inline::C::Cookbook.
464 Example #1 - Greetings
466 This example will take one string argument (a name) and print a
467 greeting. The function is called with a string and with a number. In
468 the second case the number is forced to a string.
469 Notice that you do not need to "#include <stdio.h">. The "perl.h"
471 header file which gets included by default, automatically loads the
472 standard C header files for you.
473 use Inline 'C';
475 greet('Ingy');
476 greet(42);
477 __END__
478 __C__
479 void greet(char* name) {
480 printf("Hello %s!\n", name);
481 }
482 Example #2 - and Salutations
484 This is similar to the last example except that the name is passed in
485 as a "SV*" (pointer to Scalar Value) rather than a string ("char*").
486 That means we need to convert the "SV" to a string ourselves. This is
487 accomplished using the "SvPVX" function which is part of the "Perl"
488 internal API. See "perldoc perlapi" for more info.
489 One problem is that "SvPVX" doesn't automatically convert strings to
491 numbers, so we get a little surprise when we try to greet 42. The
492 program segfaults, a common occurrence when delving into the guts of
493 Perl.
494 use Inline 'C';
496 greet('Ingy');
497 greet(42);
498 __END__
499 __C__
500 void greet(SV* sv_name) {
501 printf("Hello %s!\n", SvPVX(sv_name));
502 }
503 Example #3 - Fixing the problem
505 We can fix the problem in Example #2 by using the "SvPV" function
506 instead. This function will stringify the "SV" if it does not contain
507 a string. "SvPV" returns the length of the string as it's second
508 parameter. Since we don't care about the length, we can just put
509 "PL_na" there, which is a special variable designed for that purpose.
510 use Inline 'C';
512 greet('Ingy');
513 greet(42);
514 __END__
515 __C__
516 void greet(SV* sv_name) {
517 printf("Hello %s!\n", SvPV(sv_name, PL_na));
518 }
519
521 For general information about Inline see Inline.
522 For sample programs using Inline with C see Inline::C::Cookbook.
524 For information on supported languages and platforms see Inline-
526 Support.
527 For information on writing your own Inline Language Support Module, see
529 Inline-API.
530 Inline's mailing list is inline@perl.org
532 To subscribe, send email to inline-subscribe@perl.org
534
536 If you use C function names that happen to be used internally by Perl,
537 you will get a load error at run time. There is currently no
538 functionality to prevent this or to warn you. For now, a list of Perl's
539 internal symbols is packaged in the Inline module distribution under
540 the filename 'symbols.perl'. Avoid using these in your code.
541
543 Ingy döt Net <ingy@cpan.org>
544 Sisyphus <sisyphus@cpan.org>
546
548 Copyright 2000-2019. Ingy döt Net.
549 Copyright 2008, 2010-2014. Sisyphus.
551 This program is free software; you can redistribute it and/or modify it
553 under the same terms as Perl itself.
554 See <http://www.perl.com/perl/misc/Artistic.html>
556perl v5.32.0 2020-07-28 Inline::C(3)