Inline::C
=========

Write Perl Subroutines in C

<badge travis coveralls ingydotnet/inline-c-pm>

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

== 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. 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 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 inline@perl.org

To subscribe, send email to inline-subscribe@perl.org

= 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 <ingy@cpan.org>

Sisyphus <sisyphus@cpan.org> 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
