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, if 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;

 prototype
   Corresponds to the XS keyword 'PROTOTYPE'. See the perlxs documentation
   for both 'PROTOTYPES' and 'PROTOTYPE'. As an example, the following will
   set the PROTOTYPE of the 'foo' function to '$', and disable prototyping
   for the 'bar' function.

       use Inline C => config => prototype => {foo => '$', bar => 'DISABLE'}

 prototypes
   Corresponds to the XS keyword 'PROTOTYPES'. Can take only values of
   'ENABLE' or 'DISABLE'. (Contrary to XS, default value is 'DISABLE'). See
   the perlxs documentation for both 'PROTOTYPES' and 'PROTOTYPE'.

       use Inline C => config => prototypes => 'ENABLE';

 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. The default is
   Inline::C::Parser::RecDescent, which uses the Parse::RecDescent module.

   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:

   *   "ParseRecDescent"

   *   "ParseRegExp"

   *   "ParsePegex"

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

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.

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

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

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

   "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 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));
       }

 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 [email protected]

   To subscribe, send email to [email protected]

BUGS AND DEFICIENCIES
   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
   Ingy dẗ Net <[email protected]>

   Sisyphus <[email protected]> fixed some bugs and is current
   co-maintainer.

COPYRIGHT
   Copyright 2000-2014. 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>

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.