Unix/Linux Go Back    


CentOS 7.0 - man page for inline::c (centos section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


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

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 compiler flags - same as ExtUtils::MakeMaker's CCFLAGS option.  Whatever gets
       specified here replaces the default $Config{ccflags}.  Often, you'll want to add an extra
       flag or two without clobbering the default flags in which case you could instead use
       CCFLAGSEX (see below) or, iff Config.pm has already been loaded:

	 use Inline C => Config => CCFLAGS => $Config{ccflags} . " -DXTRA -DTOO";

   CCFLAGSEX
       Extend compiler flags.  Sets CCFLAGS to $Config{ccflags} followed by a space, followed by
       the specified value:

	 use Inline C => Config => CCFLAGSEX => "-DXTRA -DTOO";

   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.  Expects a fully
       qualified path.

	   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.  Provide a fully qualified path with the -L switch if the library is
       in a location where it won't be found automatically.

	   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.  Expects a fully qualified path.

	   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_';

   PRE_HEAD
       Specifies code that will precede the inclusion of all files specified in AUTO_INCLUDE (ie
       EXTERN.h, perl.h, XSUB.h, INLINE.h and anything else that might have been added to
       AUTO_INCLUDE by the user). If the specified value identifies a file, the contents of that
       file will be inserted, otherwise the specified value is inserted.

	 use Inline C => Config => PRE_HEAD => $code_or_filename;

   TYPEMAPS
       Specifies extra typemap files to use. These types will modify the behaviour of the C
       parsing. Corresponds to the MakeMaker parameter.  Specify either a fully qualified path or
       a path relative to the cwd (ie relative to what the cwd is at the time the script is
       loaded).

	   use Inline C => Config => TYPEMAPS => '/your/path/typemap';

   USING
       Specifies which parser to use. Default is 'ParseRecDescent', which uses the
       Parse::RecDescent module. The only other option is 'ParseRegExp', which uses the
       Inline::C::ParseRegExp module that ships with Inline.

	   use Inline C => Config => USING => 'ParseRegExp';

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>

       Sisyphus <sisyphus@cpan.org> fixed some bugs and is current co-maintainer.

COPYRIGHT
       Copyright (c) 2000-2002. Brian Ingerson.

       Copyright (c) 2008, 2010-2012. 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

perl v5.16.3				    2012-11-20					     C(3)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 09:42 PM.