c(3)

NAME

Inline::C - Write Perl Subroutines in C

DESCRIPTION

"Inline::C" is a module that allows you to write Perl sub
routines in C. Since version 0.30 the Inline module sup
ports 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 infor
mation on Inline in general, see Inline.

Usage

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 => ...;

Function Definitions

The Inline grammar for C recognizes certain function defi
nitions (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" nec
essary to call that function as if it were a Perl subrou
tine. If the signature is not recognized, Inline will sim
ply ignore it, with no complaints. It will not be avail
able from Perl-space, although it will be available from
C-space.

Inline looks for ANSI/prototype style function defini tions. 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) {
SV* Foo() {
void Foo(SV*, ...) {
long Foo(int i, int j, ...) {
The following definitions would not be recognized:: Foo(int i) { # no return type
int Foo(float f) { # no (default) typemap for; float
unsigned int Foo(int i) { # 'unsigned int' not recog; nized
int Foo(num, str) double num; char* str; {
void Foo(void) { # void only valid for re; turn type
Notice that Inline only looks for function definitions, not function prototypes. Definitions are the syntax directly preceeding 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.

C Configuration Options

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.

AUTO_INCLUDE

Specifies extra statements to automatically included. They will be added onto the defaults. A newline char will be automatically added.: use C => Config => AUTO_INCLUDE => '#include "your; header.h"';
AUTOWRAP
If you 'ENABLE => AUTOWRAP', Inline::C will parse function declarations (prototype statements) in your C code. For each declaration it can bind to, it will create a dummy wrapper that will call the real function which may be in an external library. This is a nice convenience for func tions that would otherwise just require an empty wrapper function.
This is similar to the base functionality you get from "h2xs". It can be very useful for binding to external libraries.
BOOT
Specifies C code to be executed in the XS BOOT section. Corresponds to the XS parameter.
CC
Specify which compiler to use.
CCFLAGS
Specify extra compiler flags.
FILTERS
Allows you to specify a list of source code filters. If more than one is requested, be sure to group them with an array ref. The filters can either be subroutine references or names of filters provided by the supplementary Inline::Filters module.
Your source code will be filtered just before it is parsed by Inline. The MD5 fingerprint is generated before filter ing. 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 => Pre

process ];
Filters are invoked in the order specified. See Inline::Filters for more information.
INC
Specifies an include path to use. Corresponds to the Make Maker parameter.: use C => Config => INC => '-I/inc/path';
LD
Specify which linker to use.
LDDLFLAGS
Specify which linker flags to use.
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.
LIBS
Specifies external libraries that should be linked into your code. Corresponds to the MakeMaker parameter.: use C => Config => LIBS => '-lyourlib';
or: use C => Config => LIBS => '-L/your/path -lyourlib';
MAKE
Specify the name of the 'make' utility to use.
MYEXTLIB
Specifies a user compiled object that should be linked in. Corresponds to the MakeMaker parameter.: use C => Config => MYEXTLIB => '/your/path/yourmod; ule.so';
OPTIMIZE
This controls the MakeMaker OPTIMIZE setting. By setting this value to '-g', you can turn on debugging support for your Inline extensions. This will allow you to be able to set breakpoints in your C code using a debugger like gdb.
PREFIX
Specifies a prefix that will be automatically stripped from C functions when they are bound to Perl. Useful for creating wrappers for shared library API-s, and binding to the original names in Perl. Also useful when names con flict with Perl internals. Corresponds to the XS parame ter.: use C => Config => PREFIX => 'ZLIB_';
TYPEMAPS
Specifies extra typemap files to use. These types will modify the behaviour of the C parsing. Corresponds to the MakeMaker parameter.: use C => Config => TYPEMAPS => '/your/path/typemap';

C-Perl Bindings

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 some
thing 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:: - int
- long
- double
- char*
- void
- SV*
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 your self. 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 any
thing (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" your self.
See "Examples" below.

The Inline Stack Macros

When you write Inline C, the following lines are automati cally 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 use ful for handling the Perl Stack from your C functions.
Inline_Stack_Vars: You'll need to use this one, if you want to use the
others. It sets up a few local variables: "sp",
"items", "ax" and "mark", for use by the other macros.
It's not important to know what they do, but I mention
them to avoid possible name conflicts.; 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 exe
cutable statements and before any other "Inline_Stack"
macros.
Inline_Stack_Items: Returns the number of arguments passed in on the
Stack.
Inline_Stack_Item(i): Refers to a particular "SV*" in the Stack, where "i"
is an index number starting from zero. Can be used to
get or set the value.
Inline_Stack_Reset: Use this before pushing anything back onto the Stack.
It resets the internal Stack pointer to the beginning
of the Stack.
Inline_Stack_Push(sv): Push a return value back onto the Stack. The value
must be of type "SV*".
Inline_Stack_Done: After you have pushed all of your return values, you
must call this macro.
Inline_Stack_Return(n): Return "n" items on the Stack.
Inline_Stack_Void: A special macro to indicate that you really don't want
to return anything. Same as:

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 equiva lent.: 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 cod ing. Third, for future compatibility. It occured 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 com patibility 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.

Writing C Subroutines

The definitions of your C functions will fall into one of
the following four categories. For each category there are
special considerations.

1: int Foo(int arg1, char* arg2, SV* arg3) {
This is the simplest case. You have a non "void" return type and a fixed length argument list. You don't need to worry about much. All the conversions will happen automatically.
2: void Foo(int arg1, char* arg2, SV* arg3) {
In this category you have a "void" return type. This
means that either you want to return nothing, or that
you want to return a list. In the latter case you'll
need to push values onto the Stack yourself. There are
a few Inline macros that make this easy. Code some
thing like this:: 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 func tion.
3: char* Foo(SV* arg1, ...) {
In this category you have an unfixed number of argu
ments. This means that you'll have to pop values off
the Stack yourself. Do it like this:: 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*".
4: void* Foo(SV* arg1, ...) {
In this category you have both a "void" return type and an unfixed number of arguments. Just combine the techniques from Categories 3 and 4.

Examples

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.

Example #1 - Greetings

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, auto matically loads the standard C header files for you.: use Inline C;
greet('Ingy');
greet(42);
__END__
__C__
void greet(char* name) {
printf("Hello %s!0, name);; }
Example #2 - and Salutations
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 occurence when delving into the guts of Perl.: use Inline C;
greet('Ingy');
greet(42);
__END__
__C__
void greet(SV* sv_name) {
printf("Hello %s!0, SvPVX(sv_name));; }
Example #3 - Fixing the problem
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!0, SvPV(sv_name, PL_na));; }

BUGS AND DEFICIENCIES

1 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 inter
nal symbols is packaged in the Inline module distribu
tion under the filename 'symbols.perl'. Avoid using
these in your code.

AUTHOR

Brian Ingerson <INGY@cpan.org>

COPYRIGHT

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

docs.sk

comprehensive documentation repository

Most Viewed