Inline::C man page on aLinux

Man page or keyword search:  
man Server   7435 pages
apropos Keyword Search (all sections)
Output format
aLinux logo
[printable version]

C(3)		      User Contributed Perl Documentation		  C(3)

NAME
       Inline::C - Write Perl Subroutines in C

DESCRIPTION
       "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.

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 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) {
	   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
	   int Foo(num, str) double num; char* str; {
	   void Foo(void) {	      # void only valid for return 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 Inline C => Config => AUTO_INCLUDE => '#include "yourheader.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
       functions 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 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.

       INC

       Specifies an include path to use. Corresponds to the MakeMaker
       parameter.

	   use Inline 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 Inline C => Config => LIBS => '-lyourlib';

       or

	   use Inline 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 Inline C => Config => MYEXTLIB => '/your/path/yourmodule.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 conflict with Perl internals. Corresponds to the XS
       parameter.

	   use Inline 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 Inline 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
       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:

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

The Inline Stack Macros
       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.

       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 executable 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 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 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 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.

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
	   something 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 function.

       3.
	       char* Foo(SV* arg1, ...) {

	   In this category you have an unfixed number of arguments. 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, 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);
	   }

       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!\n", 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!\n", SvPV(sv_name, PL_na));
	   }

SEE ALSO
       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

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 internal symbols is packaged in the Inline module
	   distribution under the filename 'symbols.perl'. Avoid using these
	   in your code.

AUTHOR
       Brian Ingerson <INGY@cpan.org>

COPYRIGHT
       Copyright (c) 2000, 2001, 2002. Brian Ingerson. All rights reserved.

       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

perl v5.10.0			  2002-11-04				  C(3)
[top]

List of man pages available for aLinux

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net