| Inline::C(3) | User Contributed Perl Documentation | Inline::C(3) |
Inline::C - C Language Support for Inline
This document describes Inline::C version 0.81.
"Inline::C" is a module that allows you to write Perl subroutines in C. Since version 0.30 the Inline module supports multiple programming languages and each language has its own support module. This document describes how to use Inline with the C programming language. It also goes a bit into Perl C internals.
If you want to start working with programming examples right away, check out Inline::C::Cookbook. For more information on Inline in general, see Inline.
You never actually use "Inline::C" directly. It is just a support module for using "Inline.pm" with C. So the usage is always:
use Inline C => ...;
or
bind Inline C => ...;
The Inline grammar for C recognizes certain function definitions (or signatures) in your C code. If a signature is recognized by Inline, then it will be available in Perl-space. That is, Inline will generate the "glue" necessary to call that function as if it were a Perl subroutine. If the signature is not recognized, Inline will simply ignore it, with no complaints. It will not be available from Perl-space, although it will be available from C-space.
Inline looks for ANSI/prototype style function definitions. They must be of the form:
return-type function-name ( type-name-pairs ) { ... }
The most common types are: "int", "long", "double", "char*", and "SV*". But you can use any type for which Inline can find a typemap. Inline uses the "typemap" file distributed with Perl as the default. You can specify more typemaps with the "typemaps" configuration option.
A return type of "void" may also be used. The following are examples of valid function definitions.
int Foo(double num, char* str) {
void Foo(double num, char* str) {
void Foo(SV*, ...) {
long Foo(int i, int j, ...) {
SV* Foo(void) { # 'void' arg invalid with the ParseRecDescent parser.
# Works only with the ParseRegExp parser.
# See the section on `using` (below).
SV* Foo() { # Alternative to specifying 'void' arg. Is valid with
# both the ParseRecDescent and ParseRegExp parsers.
The following definitions would not be recognized:
Foo(int i) { # no return type
int Foo(float f) { # no (default) typemap for float
int Foo(num, str) double num; char* str; {
Notice that Inline only looks for function definitions, not function prototypes. Definitions are the syntax directly preceding a function body. Also Inline does not scan external files, like headers. Only the code passed to Inline is used to create bindings; although other libraries can linked in, and called from C-space.
For information on how to specify Inline configuration options, see Inline. This section describes each of the configuration options available for C. Most of the options correspond either to MakeMaker or XS options of the same name. See ExtUtils::MakeMaker and perlxs.
use Inline C => config => auto_include => '#include "yourheader.h"';
This is similar to the base functionality you get from "h2xs". It can be very useful for binding to external libraries.
use Inline C => Config => ccflags => $Config{ccflags} . " -DXTRA -DTOO";
use Inline C => config => ccflagsex => "-DXTRA -DTOO";
Specify preprocessor flags. Passed to "cpp" C preprocessor by "Preprocess()" in Inline::Filters.
use Inline C => <<'END',
CPPFLAGS => ' -DPREPROCESSOR_DEFINE',
FILTERS => 'Preprocess';
use Inline C => <<'END',
CPPFLAGS => ' -DPREPROCESSOR_DEFINE=4321',
FILTERS => 'Preprocess';
Your source code will be filtered just before it is parsed by Inline. The MD5 fingerprint is generated before filtering. Source code filters can be used to do things like stripping out POD documentation, pre-expanding "#include" statements or whatever else you please. For example:
use Inline C => DATA =>
filters => [Strip_POD => \&MyFilter => Preprocess ];
Filters are invoked in the order specified. See Inline::Filters for more information.
If a filter is an array reference, it is assumed to be a usage of a filter plug- in named by the first element of that array reference. The rest of the elements of the array reference are used as arguments to the filter. For example, consider a "filters" parameter like this:
use Inline C => DATA => filters => [ [ Ragel => '-G2' ] ];
In order for Inline::C to process this filter, it will attempt to require the module Inline::Filters::Ragel and will then call the "filter" function in that package with the argument '-G2'. This function will return the actual filtering function.
use Inline C => config => inc => '-I/inc/path';
NOTE: These flags will completely override the existing flags,
instead of
just adding to them. So if you need to use those too, you must
respecify them here.
use Inline C => config => libs => '-lyourlib';
or
use Inline C => config => libs => '-L/your/path -lyourlib';
use Inline C => config => myextlib => '/your/path/yourmodule.so';
use Inline C => config => prefix => 'ZLIB_';
use Inline C => config => pre_head => $code_or_filename;
use Inline C => config => prototype => {foo => '$', bar => 'DISABLE'}
use Inline C => config => prototypes => 'ENABLE';
use Inline C => config => typemaps => '/your/path/typemap';
The other options are "::Parser::Pegex" and "::Parser::RegExp", which uses the Inline::C::Parser::Pegex and Inline::C::Parser::RegExp modules that ship with Inline::C.
use Inline C => config => using => '::Parser::Pegex';
Note that the following old options are deprecated, but still work at this time:
This section describes how the "Perl" variables get mapped to "C" variables and back again.
First, you need to know how "Perl" passes arguments back and forth to subroutines. Basically it uses a stack (also known as the Stack). When a sub is called, all of the parenthesized arguments get expanded into a list of scalars and pushed onto the Stack. The subroutine then pops all of its parameters off of the Stack. When the sub is done, it pushes all of its return values back onto the Stack.
The Stack is an array of scalars known internally as "SV"'s. The Stack is actually an array of pointers to SV or "SV*"; therefore every element of the Stack is natively a "SV*". For FMTYEWTK about this, read "perldoc perlguts".
So back to variable mapping. XS uses a thing known as "typemaps" to turn each "SV*" into a "C" type and back again. This is done through various XS macro calls, casts and the Perl API. See "perldoc perlapi". XS allows you to define your own typemaps as well for fancier non-standard types such as "typedef"- ed structs.
Inline uses the default Perl typemap file for its default types. This file is called "/usr/local/lib/perl5/5.6.1/ExtUtils/typemap", or something similar, depending on your Perl installation. It has definitions for over 40 types, which are automatically used by Inline. (You should probably browse this file at least once, just to get an idea of the possibilities.)
Inline parses your code for these types and generates the XS code to map them. The most commonly used types are:
If you need to deal with a type that is not in the defaults, just use the generic "SV*" type in the function definition. Then inside your code, do the mapping yourself. Alternatively, you can create your own typemap files and specify them using the "typemaps" configuration option.
A return type of "void" has a special meaning to Inline. It means that you plan to push the values back onto the Stack yourself. This is what you need to do to return a list of values. If you really don't want to return anything (the traditional meaning of "void") then simply don't push anything back.
If ellipsis or "..." is used at the end of an argument list, it means that any number of "SV*"s may follow. Again you will need to pop the values off of the "Stack" yourself.
See "EXAMPLES" below.
When you write Inline C, the following lines are automatically prepended to your code (by default):
#include "EXTERN.h"
#include "perl.h"
#include "XSUB.h"
#include "INLINE.h"
The file "INLINE.h" defines a set of macros that are useful for handling the Perl Stack from your C functions.
NOTE: Since this macro declares variables, you'll need to put
it with your
other variable declarations at the top of your function. It must
come before any executable statements and before any other
"Inline_Stack" macros.
Inline_Stack_Return(0);
Please note that this macro actually returns from your function.
Each of these macros is available in 3 different styles to suit your coding tastes. The following macros are equivalent.
Inline_Stack_Vars
inline_stack_vars
INLINE_STACK_VARS
All of this functionality is available through XS macro calls as well. So why duplicate the functionality? There are a few reasons why I decided to offer this set of macros. First, as a convenient way to access the Stack. Second, for consistent, self documenting, non-cryptic coding. Third, for future compatibility. It occurred to me that if a lot of people started using XS macros for their C code, the interface might break under Perl6. By using this set, hopefully I will be able to insure future compatibility of argument handling.
Of course, if you use the rest of the Perl API, your code will most likely break under Perl6. So this is not a 100% guarantee. But since argument handling is the most common interface you're likely to use, it seemed like a wise thing to do.
The definitions of your C functions will fall into one of the following four categories. For each category there are special considerations.
int i, max; SV* my_sv[10];
Inline_Stack_Vars;
Inline_Stack_Reset;
for (i = 0; i < max; i++)
Inline_Stack_Push(my_sv[i]);
Inline_Stack_Done;
After resetting the Stack pointer, this code pushes a series of return values. At the end it uses "Inline_Stack_Done" to mark the end of the return stack.
If you really want to return nothing, then don't use the "Inline_Stack_" macros. If you must use them, then set use "Inline_Stack_Void" at the end of your function.
int i;
Inline_Stack_Vars;
for (i = 0; i < Inline_Stack_Items; i++)
handle_sv(Inline_Stack_Item(i));
The return type of Inline_Stack_Item(i) is "SV*".
Here are a few examples. Each one is a complete program that you can try running yourself. For many more examples see Inline::C::Cookbook.
This example will take one string argument (a name) and print a greeting. The function is called with a string and with a number. In the second case the number is forced to a string.
Notice that you do not need to "#include <stdio.h">. The "perl.h" header file which gets included by default, automatically loads the standard C header files for you.
use Inline 'C';
greet('Ingy');
greet(42);
__END__
__C__
void greet(char* name) {
printf("Hello %s!\n", name);
}
This is similar to the last example except that the name is passed in as a "SV*" (pointer to Scalar Value) rather than a string ("char*"). That means we need to convert the "SV" to a string ourselves. This is accomplished using the "SvPVX" function which is part of the "Perl" internal API. See "perldoc perlapi" for more info.
One problem is that "SvPVX" doesn't automatically convert strings to numbers, so we get a little surprise when we try to greet 42. The program segfaults, a common occurrence when delving into the guts of Perl.
use Inline 'C';
greet('Ingy');
greet(42);
__END__
__C__
void greet(SV* sv_name) {
printf("Hello %s!\n", SvPVX(sv_name));
}
We can fix the problem in Example #2 by using the "SvPV" function instead. This function will stringify the "SV" if it does not contain a string. "SvPV" returns the length of the string as it's second parameter. Since we don't care about the length, we can just put "PL_na" there, which is a special variable designed for that purpose.
use Inline 'C';
greet('Ingy');
greet(42);
__END__
__C__
void greet(SV* sv_name) {
printf("Hello %s!\n", SvPV(sv_name, PL_na));
}
For general information about Inline see Inline.
For sample programs using Inline with C see Inline::C::Cookbook.
For information on supported languages and platforms see Inline-Support.
For information on writing your own Inline Language Support Module, see Inline-API.
Inline's mailing list is inline@perl.org
To subscribe, send email to inline-subscribe@perl.org
If you use C function names that happen to be used internally by Perl, you will get a load error at run time. There is currently no functionality to prevent this or to warn you. For now, a list of Perl's internal symbols is packaged in the Inline module distribution under the filename 'symbols.perl'. Avoid using these in your code.
Ingy döt Net <ingy@cpan.org>
Sisyphus <sisyphus@cpan.org>
Copyright 2000-2019. Ingy döt Net.
Copyright 2008, 2010-2014. Sisyphus.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
See <http://www.perl.com/perl/misc/Artistic.html>
| 2019-05-11 | perl v5.34.0 |